docs(sandboxes): add sandbox environments section (sbx env, experimental)

[dvdksn]

Summary

• Adds a dedicated experimental Sandbox environment files page and links it from the Sandboxes workflows and get-started documentation
• Documents the v0.39 .sbxenv.yaml schema and all four sbx env commands (run, create, exec, and rm)
• Provides common workflows for shared project setup, personal overrides, multiple repositories, and automation
• Clarifies live-update, recreation, failed-create cleanup, global binding, and MCP gateway behavior
• Vendors the generated v0.39 sbx env CLI reference and links each command from the guide

🤖 Updated with Codex

[netlify]

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	8f2a9a7
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/6a7c647b57b0d70008b83b26
😎 Deploy Preview	https://deploy-preview-25487--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

This PR adds a new Sandbox environments section (~158 lines) to workflows.md documenting the experimental sbx env feature. The structure is clear and the YAML examples look correct. A few style-guide issues were found in the newly added content.

[dvdksn]

Verified the .sbxenv.yaml schema, all four sbx env subcommands, merge semantics, and the update/remove/failure-cleanup behavior against a v0.39.0-rc3 install — everything in the doc matches actual CLI behavior, no factual issues found.

A few suggestions for smoother learning flow, from a first-time-reader perspective:

1. Commands are used before they're explained. The "Common workflows" section uses sbx env run, create, exec, rm before the "## Commands" section defines what each one does (e.g. that run creates-if-missing but never re-provisions on an existing sandbox). Consider moving "## Commands" up, right after the intro note, so terms are defined before the examples lean on them.

2. No minimal example before the complex one. The first workflow ("Share a complete project environment") introduces kits, a kit-source allowlist command, ports, and secrets all at once. A 2-3 line "quickstart" (just schemaVersion + agent, which is a fully valid file) before the workflows would give readers a working mental model before the cookbook examples layer on complexity.

3. The live-update vs. recreate distinction lands too late. "## Update an environment" — that editing env applies live but sandboxOptions/ports/kits/etc. require rm + recreate — is important enough to trip people up, but it appears after all four workflows and the commands table. The "Combine team defaults and personal settings" workflow is exactly where someone would edit sandboxOptions and expect it to apply on re-run; a pointer to "## Update an environment" there would help.

4. "Scope" is used before it's defined. secrets, bindings, and rm all depend on the sandbox-scoped vs. global distinction, but it's only implied piecemeal. One clarifying sentence up front (secrets/registry creds are sandbox-scoped and removed with it; bindings are global and shared unless pruned) would help the later field tables land faster.

5. Minor: "## Remove an environment" blends normal removal with failed-create cleanup in one block of text. Since the failed-create behavior is operationally important (secrets/bindings/MCP registrations persist if creation errors out — confirmed this), splitting it into its own subheading like "Clean up after a failed create" would make it easier to find when someone's actually debugging that situation.

— Authored and posted by Claude, on behalf of @dvdksn.