Update Claude Code init templates to use claude setup-token and CLAUDE_CODE_OAUTH_TOKEN

[mattpocock]

You use claude setup-token to acquire your auth token. We should add that to the init instructions, as well as to .env.example. We should have ANTHROPIC_API_KEY there too, but commented out.

[github-actions]

Triage notes

Verdict

Difficulty: low. Small, well-scoped string edit in src/InitService.ts plus a few test and doc updates. No runtime/type changes needed — Sandcastle passes whatever keys live in .sandcastle/.env straight through to the agent process and does not validate or hard-code ANTHROPIC_API_KEY anywhere outside the init scaffolding.

Verifying the issue's claims

• The claude setup-token / CLAUDE_CODE_OAUTH_TOKEN flow is confirmed by Matt's own closing comment on Possible to use Claude subscription instead of ANTHROPIC_API_KEY? #191 ("Acquire an oauth token by using claude setup-token. Paste it to CLAUDE_CODE_OAUTH_TOKEN in your .sandcastle/.env file"). Possible to use Claude subscription instead of ANTHROPIC_API_KEY? #191 has been closed in favor of this issue, so the existing # see issues/191 workaround line in the generated .env.example is now a dead pointer.
• The .env.example and next-steps copy are exactly where the issue says they are — both are generated by src/InitService.ts, not by a static template file.

Where the change lands

Primary: src/InitService.ts

• :416-418 — AGENT_REGISTRY[claude-code].envExample. Today emits ANTHROPIC_API_KEY= with a # see issues/191 hint. Needs to become CLAUDE_CODE_OAUTH_TOKEN= with a claude setup-token hint, plus a commented # ANTHROPIC_API_KEY= fallback.
• :645 and :658 — both "next steps" blocks (blank template and other templates) link to issue Possible to use Claude subscription instead of ANTHROPIC_API_KEY? #191 as the subscription workaround. That copy is now stale and should be replaced with a one-line claude setup-token nudge (or removed).
• :427-428 — the pi agent uses the same ANTHROPIC_API_KEY= block. The issue title says "Claude Code" so this is probably out of scope, but it's worth flagging because Pi runs on Anthropic models and the OAuth token doesn't apply to it.

Tests: src/InitService.test.ts

• :65-114 — parametrised .env.example matrix. The claude-code row asserts ANTHROPIC_API_KEY= is present and uses an expectIssue191Link flag; both need rewording to assert CLAUDE_CODE_OAUTH_TOKEN= and the new OAuth hint.
• :1027 and :1214 — two more snapshots that assert ANTHROPIC_API_KEY= appears in the generated .env.example for claude-code. Need updating in lockstep.

Docs:

• README.md:42 — install step 3 still tells users to fill in ANTHROPIC_API_KEY and links to Possible to use Claude subscription instead of ANTHROPIC_API_KEY? #191. This is the most user-visible copy.
• docs/content/docs/agents.mdx:24 — the Claude Code "Required environment variables" table lists only ANTHROPIC_API_KEY.
• README.md:947 (env: { ANTHROPIC_API_KEY: "sk-ant-..." }) is a JS-API code example, not init scaffolding — probably out of scope.

Important notes for the implementer

1. The .env parser ignores comments. src/EnvResolver.ts:17 skips lines starting with #, and :65-70 only resolves keys from process.env if they're declared (uncommented) in .sandcastle/.env. A # ANTHROPIC_API_KEY= line is purely advisory — the user must uncomment it to take effect. That's the expected behaviour for a commented fallback, but the comment copy should make it clear.
2. Runtime is unaffected. No code path inspects the name of the Claude env var. claudeCode() in src/AgentProvider.ts:1115-1120 takes env opaquely, and sandbox providers forward whatever resolveEnv returns. Swapping the recommended key is purely a templating/docs change.
3. Changeset required per CLAUDE.md. This is patch-level (init-output polish), package @ai-hero/sandcastle.

Open questions

• Scope of "init templates": does this also cover the pi agent's ANTHROPIC_API_KEY block at src/InitService.ts:427-428? Title suggests no, but the shared next-steps copy at :645/:658 will be touched either way.
• Exact wording of the new .env.example block and the next-steps hint. A reasonable strawman:

  # Claude Code OAuth token — get one with: claude setup-token
  CLAUDE_CODE_OAUTH_TOKEN=
  # Or use an API key instead:
  # ANTHROPIC_API_KEY=
  

  But the phrasing is a judgement call — defer to Matt.

Possible approach

1. Rewrite AGENT_REGISTRY[claude-code].envExample at src/InitService.ts:416-418 (OAuth token primary, API key commented fallback).
2. Replace the two issues/191 lines in getNextStepsLines (:645, :658) with a one-line claude setup-token hint.
3. Update the four InitService.test.ts assertion sites — rename the expectIssue191Link flag and switch the claude-code row to assert CLAUDE_CODE_OAUTH_TOKEN=.
4. Update README.md:42 and docs/content/docs/agents.mdx:24.
5. Add a patch changeset.

npm run typecheck plus the InitService test suite should be sufficient verification — no behavioural plumbing changes.