docs(sandboxes): kit spec schemaVersion 2#25467
Conversation
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
| | `tmpfs:` | `volumes:` entries with `type: tmpfs` | | ||
| | `settings:` / `kitDir` / `persistence` | removed (no replacement) | | ||
|
|
||
| Credential **discovery** also moved out of the kit in v2: a kit declares which |
There was a problem hiding this comment.
[MEDIUM] Bold used on discovery for emphasis, not a UI element
The word discovery is bolded for stylistic emphasis in the new "Schema versions" section. The Docker style guide reserves bold exclusively for UI elements (buttons, menus, field labels). Bold should not be used for emphasis or general terms.
Suggested fix: Remove the bold marks — Credential discovery also moved out of the kit in v2:.
| | `credentialFile.path` | Where to write the credential file inside the container (`~` expands). | | ||
| | `credentialFile.template` | JSON template for that file. `{{.AccessToken}}`, `{{.RefreshToken}}`, `{{.ExpiresAt}}`, and `{{.ScopesJSON}}` are substituted at runtime. | | ||
|
|
||
| ### file.parser |
There was a problem hiding this comment.
[MEDIUM] YAML examples removed from file.parser section, leaving only a prose inline example
The old file.parser section included three concrete YAML examples (plain-text token file, nested JSON with fallback, and a sample JSON file), which made it easy to copy-paste working configurations. This PR removes all of them. The remaining content — the behavior table, a single inline path example (json:credentials.github.token), and the error table — is not wrong, but authors trying to configure file parsers now have no complete YAML block to reference.
Consider restoring at least one example showing file.parser in context (for example, the nested JSON field example), or adding a new one that reflects the v2 credentials[] shape.
dvdksn
force-pushed
the
sandboxes-kit-spec-v2
branch
from
8068eb3 to
a53f6ce
Compare
Reworks the kit-authoring schema docs for schemaVersion: "2": adds a "Schema versions" section with a v1-to-v2 field mapping, rewrites the credentials/network/environment field reference to the caps.network and credentials[] model, and defaults kits.md and kit-examples.md examples to schemaVersion: "2". Split out from the combined credentials-rework PR so the kit-authoring schema can iterate independently of the credential-bindings runtime work. Forward-references to credential bindings link at the credentials page generally, since that section ships in the separate bindings PR. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
dvdksn
force-pushed
the
sandboxes-kit-spec-v2
branch
from
a53f6ce to
1abdd3d
Compare
2 participants
Summary
Documents the Docker Sandboxes kit-authoring schema for
schemaVersion: "2".Split out from #25369. This is the authoring-side half: the kit spec
shape only. The end-user credential-bindings / first-run-approval half lives
in its companion PR (#25468).
What's in this PR
customize/kit-reference.md— new "Schema versions" section with av1→v2 field mapping table; credentials/network/environment field reference
rewritten to the
caps.network+credentials[](apiKey/oauth) model;proxyManagedandserviceDomains/serviceAuthdocumented asauto-normalized legacy fields.
customize/kits.md,customize/kit-examples.md— examples default toschemaVersion: "2"and the newcaps.network/credentials[]shape.Why split
The v2 kit spec already exists (tentatively in sbx v0.34) but its final shape
is still in flux, and the migration/mapping story needs more work — so this can
iterate on its own timeline. The credential-bindings half is gated on a
separate runtime migration (docker/sandboxes#3684). The two concerns touch
disjoint files and gate on independent events, so they no longer need to ride
together.
Forward-references to the credential-bindings section link at the credentials
page generally (no
#credential-bindingsfragment), since that section shipsin the companion PR — this avoids a broken anchor regardless of merge order.
Status
Note
Draft. The v2 spec is still subject to change and the migration story
needs expanding before publish.
Generated by Claude Code