docs: subscription auth is the primary sandcastle flow, API key is fallback

docs/decisions/adr-019-sandcastle-for-agent-orchestration.md

@@ -50,12 +50,21 @@ Concretely:
    orchestrator does NOT mutate state in v1 — it prints suggested mutations
    for the human to apply.
 5. **Two modes:** `pnpm work dispatch` (planning, no agent invoked) and
-   `pnpm work dispatch --execute` (real sandcastle call, requires
-   `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`).
+   `pnpm work dispatch --execute` (real sandcastle call, requires auth — see
+   point 7).
 6. **Reviewer agent verifies generator-first.** Hand-rolled output that should
    have been a `pnpm turbo gen <kind>` invocation is grounds for rejection.
-7. **Bring-your-own-key for cost control.** No bundled API key. Agents only
-   dispatch when the operator explicitly provides credentials.
+7. **Bring-your-own-auth.** Two paths are supported, in priority order:
+   - **Subscription (primary)** — bind-mount the host's `~/.claude/` into the
+     sandbox. Claude Code CLI inside the sandbox uses the host's logged-in
+     subscription session. Zero per-task token spend for Pro/Max subscribers.
+     Path overridable via `SANDCASTLE_CLAUDE_CREDS_DIR` env var.
+   - **API key (fallback)** — `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` passed
+     through to the sandbox env. Used when no host creds directory exists.
+   - The resolver (`resolveClaudeAuth` in `scripts/work/dispatch.mjs`) picks
+     automatically with subscription always preferred. Sandcastle's own issue
+     #191 documents that subscription support won't be added natively;
+     this mount-based pattern is our workaround promoted to first-class.
 8. **Per-task max-attempts honoured (v2).** Each task's frontmatter may carry
    `max-attempts: N` to bound the implementer↔reviewer retry loop. Default 3.