docs: recommend kits v3 and retain a deprecated v2 fallback

[dvdksn]

Description

Recommend v3 for kit development while built-in agent shortcuts remain on v2. Explain that users must select an explicit v3 workload and use v3 mixins throughout, so the recommended customization path does not imply compatibility with the built-ins.

• Teach kits through an approachable, usage-first overview, an OpenCode workload with Ruff, and a Claude Code authoring tutorial.
• Document the complete v3 schema, capabilities, lifecycle, composition, arguments, directory and build layouts, distribution, published format, and runtime limitations. Include independent examples for tools, configuration, instructions, and skills.
• Consolidate the deprecated v2 fallback into one compact page covering usage, migration, schema fields, essential maintenance examples, and distribution. Keep it visible in search and navigation with a clear deprecation notice, and preserve contextual links for existing customizations and historical announcements.
• Explain migration of an entire workload and mixin set into a separate sandbox, and align positional kit commands, credentials, and navigation.

Published v3 agent references are not yet confirmed. The introductory command uses <V3_WORKLOAD_KIT> and links to a complete local workload example; a confirmed published agent reference is still needed for the release on-ramp.

Earlier revisions were validated with kit image builds, binary smoke checks, descriptor samples against the schema implementation, scoped Markdown and style lint, a full Hugo build, and internal links. Subsequent editorial and information architecture changes have not been validated, at the author's request. Registry push/pull, signing/verification, and first-time credential approval/onboarding checks remain pending.

@netlify /ai/sandboxes/customize/kits/

Generated by Codex

[netlify]

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	f74fc70
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/6aa7fdc395e51700089e049a
😎 Deploy Preview	https://deploy-preview-26065--docsdocker.netlify.app/ai/sandboxes/customize/kits/
📱 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.

[Copilot]

🔵 Needs a closer look

Schema-specific credential guidance and the v3 onboarding reference remain unresolved, with validation still pending.

Pull request overview

This PR reorganizes kit documentation around recommended v3 workloads while retaining consolidated deprecated v2 guidance.

Changes:

• Adds v3 authoring, schema, lifecycle, examples, and distribution guidance.
• Consolidates v2 usage, migration, maintenance, and signing documentation.
• Updates related navigation, links, credentials, and guides.

File summaries

File	Summary
data/whats-new.json	Updates historical kit links.
content/manuals/ai/sandboxes/workflows/git.md	Points built-in-agent users to v2 kits.
content/manuals/ai/sandboxes/troubleshooting.md	Updates CA-kit guidance.
content/manuals/ai/sandboxes/release-notes.md	Updates the v2 reference link.
content/manuals/ai/sandboxes/integrations/t3-code.md	Updates kit terminology and links.
content/manuals/ai/sandboxes/faq.md	Clarifies v2 and v3 customization paths.
content/manuals/ai/sandboxes/customize/templates.md	Adds v3 workload context.
content/manuals/ai/sandboxes/customize/kits.md	Adds the primary v3 overview and workflow.
content/manuals/ai/sandboxes/customize/kits-v2/_index.md	Adds consolidated deprecated v2 guidance.
content/manuals/ai/sandboxes/customize/kit-reference.md	Documents the v3 schema and capabilities.
content/manuals/ai/sandboxes/customize/kit-examples.md	Adds v3 customization examples.
content/manuals/ai/sandboxes/customize/build-an-agent.md	Adds a Claude Code v3 tutorial.
content/manuals/ai/sandboxes/customize/_index.md	Updates customization navigation.
content/manuals/ai/sandboxes/configuration/registry-mirror.md	Updates CA-kit guidance.
content/manuals/ai/sandboxes/configuration/credentials.md	Documents kit credential bindings.
content/guides/mistral-vibe-sandbox.md	Aligns the existing v2 guide with the positional kit command.

Review details

Suppressed comments (7)

content/manuals/ai/sandboxes/configuration/credentials.md:40

• Binding approval is not required for every schema version: the v2 implementation uses a schema-version-specific binding path, while legacy v1 credentials use the old resolution behavior. Qualify this row with v2/v3 so v1 users aren't sent through an approval flow their kits don't use.

| [Credential bindings](#credential-bindings) (`credentials.yaml`)            | Per-service mechanism and domain approval                    | Required for third-party kits                                                               |

content/manuals/ai/sandboxes/configuration/credentials.md:472

• The regardless of schema version claim is incorrect for legacy v1 kits. The upstream v2 spec and implementation treat binding behavior as schema-version-specific; scope this paragraph to v2/v3 and describe the v1 path separately so v1 maintenance users don't follow an inapplicable approval flow.

Third-party kits require an approved binding for each credential they use,
regardless of schema version. `sbx` creates one interactively the first time you

content/manuals/ai/sandboxes/configuration/credentials.md:528

• This repeats the schema-version error: v1 is still supported on the page, but the paragraph says every third-party kit needs binding approval. Scope it to v2/v3 and state that legacy v1 credentials use the legacy resolution path.

Third-party kits require a binding regardless of schema version. Credentials
declared only by embedded kits are authorized by provenance and inject
automatically. A third-party v2 kit that extends a built-in agent inherits its

content/manuals/ai/sandboxes/configuration/credentials.md:516

• Required-credential behavior is schema-dependent: the v2 spec says required: true makes sandbox creation fail without a binding, whereas this text says it starts with the credential withheld. Qualify the v2 and v3 cases to avoid instructing v2 users that unattended creation succeeds.

prompt. Without a binding, the sandbox starts with the credential withheld. For a
required credential, `sbx` also prints a warning.

content/manuals/ai/sandboxes/customize/kits-v2/_index.md:334

• The inline-code delimiters in this row are unbalanced, so the Authorization text and the following tokens render incorrectly. Close the Authorization span before basic.

| `inject[].scheme`   | Shorthand for common auth schemes. `bearer` expands to `Authorization: Bearer %s`; `basic` requires `username`. Mutually exclusive with `format`. |

content/manuals/ai/sandboxes/customize/kits-v2/_index.md:317

• According to the v2 spec, required: true causes sandbox creation to fail when no binding is available; it does not warn and continue with the credential withheld. Update this field description so maintainers of the deprecated format don't rely on the wrong unattended behavior.

| `required`    | Marks the credential as essential to the agent. If it has no binding, `sbx` warns and starts with the credential withheld. Default `false`. |

content/manuals/ai/sandboxes/customize/kits.md:83

• The recommended first command still contains <V3_WORKLOAD_KIT>, so a reader cannot run it or discover a verified published v3 workload from this page. The later local example is the only concrete on-ramp, and the PR description says a published reference is still unconfirmed; either make that local example the primary command or add a verified published workload before merging.

$ sbx run <V3_WORKLOAD_KIT> <PROJECT_PATH>

• Files reviewed: 16/16 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.