One-click Codespace with Claude Code preinstalled: build-ready plan (#801)

Status: Draft for operator review, 2026-08-08. This is decision-input for the priorities regroup, not a committed build for a specific date. (The colleague onboarding tomorrow does so locally, via DAY_ONE.md, so she is not #801's first user and #801 is not gated on her.) #801's real audience is future collaborators, disposable sandboxes, and the internal-tools vision in the issue. Issue: #801 (feature), #825 (colleague-onboarding umbrella). Prior DX heritage: #595 (lantern doctor), #657 (dev-container signposting), tonight's onboarding audit (docs/worklog/2026-08-08_ONBOARDING_AUDIT.md, DAY_ONE.md).

Goal

A teammate (including a non-technical one) clicks a link, waits, and lands in a Codespace where Claude Code and the right extensions are already installed and configured: no local setup, no toolchain knowledge. They build an internal tool with Claude doing the heavy lifting.

TLDR recommendation

If the regroup ranks #801 in: ship phase 1 first (preinstall Claude Code into the existing monorepo devcontainer + a one-click README badge, Claude seat auth, monorepo with guardrails not a template repo, defer prebuilds and the template repo to phase 2). Rationale: the existing devcontainer already does the hard part (Node/gcloud/emulators/ports/zero-auth boot); the only gap is Claude itself, so phase 1 is a small diff. Prebuilds and a template repo add ongoing cost + maintenance for a speedup/isolation the early user count does not need. See section 6 for the honest "is this worth building yet" ranking.

Need from the operator (only she can do these), once #801 is greenlit

1. Invite each first user to the private repo (role: write, or triage to start). Blocks their access.
2. Decide Claude auth (seat vs API key, see section 4). Recommendation: provision a Claude seat per user.
3. Optional: an admin-portal account (Users tab invite), and a Tailscale invite if they should reach previews.

---

1. Current .devcontainer vs what #801 needs

Today (.devcontainer/devcontainer.json) already does the hard part:

• javascript-node:24-bookworm image (Node 24 satisfies engines), gcloud CLI + Java 21 features (emulators), postCreateCommand: npm ci, all PORT_MAP ports forwarded (5173 public for the PWA), postAttachCommand prints the zero-auth + secret-bootstrap guidance, and the app boots against dev with no secrets (committed .env.development).
• Extensions today: only dbaeumer.vscode-eslint + esbenp.prettier-vscode.

The day-one gap is Claude + a one-click entry. Concretely:

• Claude Code CLI preinstall. Add to postCreateCommand after npm ci: npm install -g @anthropic-ai/claude-code (fits the Node image; alternative is the official install.sh). Verify the current package name/installer at build time.
• Claude Code VS Code extension. Add anthropic.claude-code to customizations.vscode.extensions (verify the exact Marketplace ID at build time). Keep the list tight for a non-technical user: eslint, prettier, Claude Code. Optionally the repo's own tooling/vscode-extension if we publish it, but do NOT bloat the list.
• Repo agent config already ships for free: .claude/ (skills, settings, hooks) is in the repo, so a cloned Codespace already has the project's skills/guardrails. No extra step. Caveat: any interactively-authenticated MCP servers won't be present in a fresh Codespace, document which MCP tools need per-Codespace setup (most agent work here uses the gh CLI + built-in tools, so this is minor).
• A "start here" entry: a README Codespaces badge/link that opens a ready workspace in one click (section 5's acceptance flow).

Phase-1 devcontainer changes are small and low-risk (append one install line, add one extension, add a badge). No image or feature changes needed.

2. Codespaces prebuilds: cost on a private repo, and defer to phase 2

How prebuilds bill (two separate meters, both against the operator's account on a private repo):

• Build = GitHub Actions minutes. Each prebuild is an Actions job that runs the devcontainer create (npm ci ~1-2 min + feature installs + image assembly). Estimate ~5-15 min of Actions minutes per prebuild run, times how often it runs (on push to each configured branch, or scheduled). Configured on dev with our push cadence, that is many runs/day = real minutes against the private-repo Actions quota.
• Storage = Codespaces storage (GB-month). The prebuild image (node_modules ~1.3 GB + the container) is retained per configured branch/region. Several GB-month, billed on the Codespaces meter (separate from Actions), for as long as prebuilds are enabled.

Recommendation: DEFER prebuilds to phase 2. For one first user, a non-prebuilt boot (npm ci + features, a few minutes) is acceptable, she waits once. Prebuilds trade ongoing Actions+storage spend and a prebuild-config to maintain for a seconds-vs-minutes first boot that only pays off with several users spinning up frequently. Enable in phase 2 once there is a recurring multi-user pattern, and scope the prebuild trigger narrowly (one branch, one region, maybe scheduled not per-push) to bound the bill. Measure the first real prebuild run's minutes before committing to per-push.

3. Template repo vs monorepo (decision)

Recommendation: start first users in the MONOREPO Codespace with guardrails; keep the template repo as a phase-2 option. The monorepo devcontainer already exists and the onboarding audit + DAY_ONE.md already target it, so it is the zero-setup path and the first real run doubles as the #801 acceptance test. Only split to a template repo if casual-builder blast-radius or CI noise proves to be a real problem in practice.

Option	Blast radius	Setup cost	Maintenance	Fit for a casual builder
A. Monorepo Codespace (rec)	Larger, mitigate with role + branch protections + no secret access	None (devcontainer exists)	One devcontainer, one onboarding path	Full context, but more to look at
B. Separate lightweight template repo	Small (no prod/deploy/CI exposure)	New repo + its own devcontainer + a second onboarding path	Two of everything to keep current	Simpler, isolated, but loses the repo's tooling/skills

Guardrails for Option A (address #801's "what should a casual builder NOT touch"):

• Repo role write/triage, not admin. Branch protections on dev/main (already: PRs only, drafts skip CI).
• Deploy creds + prod config are already unreachable by default: the Codespace boots zero-auth on the committed public dev config; the full secret set requires a GCP secretmanager.secretAccessor grant she would not have, so env:bootstrap simply won't pull prod/secret material. That is the strongest guardrail and it is already in place.
• Her PRs target dev as drafts (no CI spend until ready, no prod path).

4. Auth story for Claude in the Codespace (operator decides)

Recommendation: a Claude seat (claude.ai login). For a non-technical colleague, no raw API key to handle, usage runs under the org/team plan, and Claude Code's CLI login (device/OAuth flow) is built for exactly this. API key is the fallback.

Path	How it works	Pros	Cons
A. Claude seat / claude.ai login (rec)	She runs Claude Code once and logs in with her claude.ai account (a seat on the operator's plan)	No key handling; usage under the org plan; designed for interactive login	Operator must provision a seat for her
B. API key as a Codespace secret	ANTHROPIC_API_KEY set as a repo/org Codespaces secret, auto-injected	No seat needed; works headless	Key management + rotation; usage bills to that key; a non-technical user shouldn't handle raw keys

If B is chosen, document setting ANTHROPIC_API_KEY under repo/org Codespaces secrets (not repo Actions secrets) so it reaches the container.

5. Acceptance criteria = a generic first user's day-one flow

A first user (technical or not, no relationship to any one colleague) succeeds if, with zero local setup, they can:

1. Click the README Codespaces badge and land in a running workspace within a few minutes.
2. Find Claude Code preinstalled (CLI + VS Code extension) and authenticate it (seat or key per section 4) without help.
3. See the app running: npm run dev serves Lantern against dev on the forwarded 5173, no secrets entered.
4. Ask Claude to make a small visible change and see it reflected.
5. Run ./lantern doctor (from the repo root; never bare npx lantern, which fetches an unrelated public package) and read a green (or clearly-actionable) report.
6. Build a small internal tool with Claude, and open a draft PR to dev, without touching prod/secret/deploy surfaces.

The first real run is the acceptance test; capture whatever actually blocked that user as the phase-1.1 fix list.

6. When is this worth building? (cost/benefit for the regroup)

Honest read: #801 is a real convenience with a modest, front-loaded cost, but its payoff scales with the number of zero-setup users, and that number is ~0 today. It should rank below anything on the alpha critical path and above speculative polish. It is the right investment the moment there is a recurring stream of collaborators or disposable sandboxes; it is premature if the local path (DAY_ONE.md, which just landed) is serving everyone in sight.

	Cost	Benefit
Phase 1 (Claude preinstall + badge + monorepo/guardrails)	~half a day: small devcontainer diff, verify a real boot, one doc. Low risk.	Any future collaborator goes from "install a toolchain" to "click a link." Compounds per user; the internal-tools vision (#801) leans on it.
Phase 2 (prebuilds)	Ongoing: Actions minutes per prebuild run + GB-month storage on a private repo (section 2), plus a prebuild config to maintain.	Boot time seconds-not-minutes. Only matters with frequent spin-ups by several users.
Phase 2 (template repo)	A second repo + devcontainer + onboarding path to keep current (section 3).	Smaller blast radius for casual internal-tool builders. Only matters if that use case actually grows.

Ranking guidance for the regroup:

• Build phase 1 when the first genuinely-remote or zero-setup collaborator is imminent, or when internal-tool building starts in earnest. Not before: the local path covers the current need.
• Hold phase 2 until real usage shows frequent multi-user spin-ups (prebuilds) or casual-builder blast-radius pain (template repo). Don't pre-pay either.
• Cheapest honest option if #801 ranks low: do nothing now, the local DAY_ONE.md path is sufficient, and phase 1 stays a ~half-day pickup whenever the audience materializes.

Phasing

• Phase 1 (build-ready when greenlit): Claude Code CLI + extension in the devcontainer; README badge; seat auth; monorepo + guardrails; run a first user; capture blockers. Small devcontainer diff + a doc.
• Phase 2 (later, on evidence): prebuilds (narrowly scoped, after measuring one run's minutes); template repo IF blast-radius/CI-noise proves painful; any MCP preconfig the real usage shows it needs.

Open questions for the operator

• Where does #801 rank against the alpha critical path at the regroup? (Section 6 is the input.)
• Seat vs API key (section 4).
• Is "internal-tool building" expected to grow to several casual builders soon? If yes, the template repo (3B) and prebuilds (2) move up; if it stays occasional, phase-1 monorepo is enough.