docs(sandboxes): credential bindings and first-run approval

[dvdksn]

Summary

Documents the Docker Sandboxes credential-bindings authorization model and the
first-run approval flow for built-in agents.

Split out from #25369. This is the end-user / runtime half. The
authoring-side kit-spec half lives in its companion PR (#25467).

What's in this PR

• security/credentials.md — credential bindings
  (~/.config/sbx/credentials.yaml): per-service discovery + allowedDomains;
  the first-run approval flow (terminal and TUI, API-key and OAuth); fail-closed
  mode (credentials.failClosed); environment variables documented as a binding
  discovery source with no implicit host-env fallback.
• agent pages (claude-code, codex, copilot, cursor, docker-agent,
  droid, gemini, opencode, shell) — env-var authentication now flows
  through a credential binding.
• troubleshooting.md — the "no approved binding" failure (non-interactive
  run or declined prompt).

Why split

This half describes end-user runtime behavior gated on the built-in
schemaVersion: "2" migration (docker/sandboxes#3684). The authoring-side kit
spec (#25467) already exists and iterates on its own timeline. The two concerns
touch disjoint files and gate on independent events.

Status

Note

Draft — intentionally held. Publish when the built-in v2 / credential-
bindings migration ships (docker/sandboxes#3684). Before then, this describes
behavior most users wouldn't yet hit.

Open TODOs before publishing

• Confirm the upgrade path for users with a pre-existing stored secret —
  auto-bound on first run, or prompted to approve a binding? (inline TODO
  in credentials.md)
• customize/build-an-agent.md is still on the v1 schema — separate
  follow-up.
• Final pass on prompt / UX wording against the shipped build.

Generated by Claude Code

[netlify]

❌ Deploy Preview for docsdocker failed. Why did it fail? →

Name	Link
🔨 Latest commit	4b163b0
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/6a44afcbe3977400088eed0e

[docker-agent]

Assessment: 🟢 APPROVE

2 style/completeness findings in credentials.md. All agent pages and troubleshooting.md are clean.

[docker-agent]

[MEDIUM] Bold used for non-UI field names violates STYLE.md

**\discovery`and`allowedDomains`**` combine bold with inline code to format YAML schema field names. Per STYLE.md, bold is reserved exclusively for UI elements (buttons, menus, form field labels) — not for configuration parameters or schema keys.

These should be plain inline code only:

- `discovery` — where to find the value: one or more environment variables,
  or a file. Entries are tried in order. Omit `discovery` to resolve the value
  from the [secret store](#stored-secrets) as usual.
- `allowedDomains` — the domains the proxy may inject this credential into.

[docker-agent]

[MEDIUM] Unresolved TODO comment gating publish-readiness on an open issue

This HTML comment explicitly marks a section as incomplete and instructs "confirm before publish," gated on docker/sandboxes#3684. While the PR is intentionally drafted and held, if this PR is merged before that issue is resolved, the upgrade-experience documentation gap will silently ship — HTML comments are invisible to readers but the missing content is not.

Recommend tracking this as a blocker before merging (or ensuring the TODO is resolved inline before the PR leaves draft status).