Reading paths

This site has two intended readers. The chapters are the same; only the order and density differ.

New contributor — day one

A linear path from "just cloned" to "shipped first PR." Total time ≈ 90 minutes.

1. Repo tour — what lives where.
2. README.md at the repo root — the public overview (commands, structure, deploy model, three-tier domains). Skim.
3. Workspace → Apps, Design system, Packages — names and one-line purposes.
4. Workspace → Docs sites — the hard boundary between this site and its two siblings. Read once so you never write a doc in the wrong place.
5. Workflow → Local development (PR-CB) — pick a dev mode. Default is localhost-direct (pnpm dev); see docs/local-development.md until that page lands here.
6. Workflow → PR workflow (PR-CB) — the PR-A...PR-Z letter convention and branch naming. Also in CLAUDE.md today.
7. Toolchain → Testing (PR-CB) — what tests to write and where.

New contributor — day two and beyond

Read on demand, not in order:

• Architecture → Auth interaction model (PR-CB) when you touch login / OAuth
• Architecture → Better-Auth quirks (PR-CB) before you debug a flashed redirect
• Architecture → API codegen (PR-CB) when you change a backend contract
• Workflow → Merge queue (PR-CB) the first time gh pr merge confuses you
• Workflow → Parallel worktrees (PR-CB) when you start your second branch
• Workflow → Debugging (PR-CB) — Cmd+. overlay, react-scan, layout outline

AI agent — picking up a task

Most agents land in the repo with a Claude Code / Cursor / SDK context window already half full. The reading order is therefore shallow and addressable:

1. AGENTS.md (repo root) — the agent-runtime entry point. Already auto-attached by Claude Code; skim if not.
2. CLAUDE.md (repo root) — tacit knowledge: PR conventions, merge queue, tsgo quirks, OAuth shells, dev modes. Long, dense, worth a full read.
3. /llms.txt (this site) — the structured index of this manual. Fetch this when you need to find a specific topic by name.
4. /llms-full.txt (this site) — everything concatenated. Fetch this only when you are doing a wide-scope investigation and have token budget.
5. /docs/<path> with Accept: text/markdown — single-page lookup. Use this for targeted questions ("how does the merge queue handle UNSTABLE?").
6. .claude/skills/use-cloud-credentials/SKILL.md — load on demand when you need to talk to Vercel / GitHub / Slack / CloudWatch / E2E auth from a cloud session.

The principle: AGENTS.md and CLAUDE.md stay as the agent runtime hooks (short, dense, agent-prompt style). This site is the expanded form, written for diffability and navigation. Keep them in sync when you change either.

Where the canonical truth lives

When two documents disagree, source-of-truth resolution order:

1. Code — pnpm-workspace.yaml, .moon/workspace.yml, .github/workflows/*, vercel.json, tsconfig.*.
2. This site (apps/dev-docs) for engineering / architecture.
3. apps/webview-bridge-docs for the bridge wire contract.
4. design-system/docs for TDX component / token usage.
5. CLAUDE.md / AGENTS.md as the agent-runtime mirror of (2).

If the code says one thing and a doc says another, fix the doc.