diff --git a/.gitignore b/.gitignore
index 892768fc8..23d7b9245 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,6 +14,10 @@ coverage/
 .test-cli-*
 # Docs site generated files
 docs/dist/
+docs/src/content/docs/reference/api/
+
+# Docs test screenshots (local verification only)
+docs/tests/screenshots/
 # Squad: SubSquad activation file (local to this machine)
 .squad-workstream
 .squad/.first-run
diff --git a/.squad/agents/pao/history.md b/.squad/agents/pao/history.md
index abbb323e2..21d9f7fef 100644
--- a/.squad/agents/pao/history.md
+++ b/.squad/agents/pao/history.md
@@ -78,6 +78,26 @@ Reviewed and merged PR #487 (CLI documentation expansion + broken docs link fix)
 
 Reviewed and merged PR #482. Search functionality integrated into docs site for improved discoverability.
 
+### PR #11 Docs Quality Review — TypeDoc API Reference (2026-03-24)
+
+**Status:** REQUEST CHANGES (3 fixes required, 2 recommended)
+
+**Key findings:**
+- **Research + PRD:** Excellent quality. Clear problem statement, realistic effort estimate, pragmatic tool choice (TypeDoc over Starlight/api-extractor). Scannability framework applied correctly (tables for audit data, bullets for findings, paragraphs for narrative).
+- **Navigation strategy:** Collapsible `<details>` approach for 395-page API reference is sound UX. Sidebar nav plan well-structured with clear open questions about CI/CD safety.
+- **Microsoft Style compliance:** Mostly strong; discovered 3 minor issues.
+
+**Issues found:**
+1. **🔴 Blocking:** sdk.md crosslink banner missing. Users navigating from curated "SDK" guide have no callout to the auto-generated "API Reference". Add "See Also" link in sdk.md before "## Resolution" section.
+2. **🔴 Blocking:** Navigation URL inconsistency. `navigation.ts` hardcodes `reference/api/index` when it should be `reference/api` — Astro resolves `/api/` to `/api/index` automatically. Simplify slug.
+3. **🟡 Blocking:** Nav plan's "Open Questions" section asks about CI/CD fallback (generated JSON missing). Plan should either specify build order (`docs:api` before `docs build`) or provide fallback empty nav for fresh clones.
+4. **🟡 Recommended:** 2–3 test descriptions need more specificity (e.g., "class page renders heading and content" → "class page renders method signatures and definition source").
+5. **🟡 Recommended:** Screenshot filenames don't align with skill convention. Use semantic names: `api-reference-landing`, `api-class-detail`, `api-function-detail`.
+
+**Pattern identified:** Generated documentation requires crosslinks from curated guides. When adding a new docs section (API reference, CLI reference, etc.), ensure the *old* curated page (SDK Guide) has a visible pointer to the new section. This prevents users from stopping at the curated version and missing the comprehensive auto-generated reference.
+
+**Effort to fix:** < 2 hours. All issues are surgical edits to existing content; no architectural changes needed.
+
 ### PR #484 Review & Merge — Sample READMEs (2026-03-22)
 
 Reviewed and merged PR #484. Sample README templates added to improve consistency across documentation examples.
@@ -100,6 +120,45 @@ Created docs/src/content/docs/scenarios/cross-org-auth.md covering GitHub person
 ### Scannability Framework (v0.8.25)
 Format selection is a scannability decision, not style preference. Paragraphs for narrative/concepts (3-4 sentences max). Bullets for scannable items (features, options, non-sequential steps). Tables for comparisons or structured reference data (config, API params). Quotes/indents for callouts/warnings. Decision test: if reader hunts for one item in a paragraph, convert to bullets/table. This framework is now a hard rule in charter under SCANNABILITY REVIEW.
 
+### Docs Catalog Audit (2026)
+Full audit of the Astro-based docs site. Key patterns and findings:
+
+**Orphaned pages (exist but not in navigation.ts):** 15 total — `get-started/choose-your-interface.md`, `guide/faq.md`, `guide/build-autonomous-agent.md`, `guide/github-auth-setup.md`, `features/built-in-roles.md`, `features/context-hygiene.md`, `features/cost-tracking.md`, `features/issue-templates.md`, `reference/vscode-troubleshooting.md`, and 6 root-level legacy files (`guide.md`, `sample-prompts.md`, `tips-and-tricks.md`, `tour-first-session.md`, `tour-github-issues.md`, `tour-gitlab-issues.md`).
+
+**Stale content:** `whatsnew.md` reports v0.8.2 as current; actual is v0.8.26+. `insider-program.md` uses deprecated `npx github:` install format and references old `.ai-team/` directory name throughout.
+
+**Duplicate/overlap pairs:** `choosing-your-path.md` (in nav) vs `choose-your-interface.md` (orphan, more complete); root-level `sample-prompts.md` vs `guide/sample-prompts.md`; root-level `tips-and-tricks.md` vs `guide/tips-and-tricks.md`; root-level `tour-first-session.md` vs `get-started/first-session.md`.
+
+**Content quality:** All actively-navved pages are well-written, follow Microsoft Style Guide, and use correct install commands. Format standards (H1, experimental callout, "Try this" block, HR, H2 sections) are inconsistently applied — some orphaned pages like `built-in-roles.md` and `cost-tracking.md` lack the standard header/callout pattern.
+
+**Structural issues:** `features/team-setup.md` has a duplicate `## How Init Works` heading (merge artifact). `features/streams.md` nav title is "Streams" but H1 is "Squad SubSquads" (mismatch). `guide/faq.md` is a high-value page completely invisible from the sidebar. `features/built-in-roles.md` is a comprehensive roles reference also invisible from nav.
+
+**Gap:** No dedicated FAQ entry point, no changelog page, cookbook section is thin (one page), no user-facing explanation of the NASA Mission Control naming scheme for agents.
+
+**Navigation:** Zero dead nav links (every nav slug has a matching file). All orphan pages are linked internally from other pages so they are reachable — but not browseable via sidebar.
+
+📌 **Team update (2026-03-22T12:46:00Z):** Booster implemented automated version sync for `whatsnew.md` (finding #1). Script reads `package.json` version, updates "Current Release" heading on every prebuild, with Vitest test gate. Heading now correct (v0.8.25+), will stay in sync automatically on all future builds. Finding #1 resolved.
+
+### JSDoc API Reference Research (2026-03-23)
+
+Completed research on generating JSDoc-based API reference documentation for Squad SDK. Key findings:
+
+**Current State:** Squad SDK has 60–80% JSDoc coverage across major modules (state: 81%, config: 8%). 136 TypeScript source files, no existing TypeDoc config.
+
+**Tool Recommendation:** **TypeDoc + typedoc-plugin-markdown** — no Starlight migration needed. Seamless integration with existing Astro 5 + Tailwind 4 + Pagefind. Markdown output drops directly into content collections. Auto-generates via Astro integration hook on `npm run build`.
+
+**Alternatives Evaluated:** 
+- ❌ Starlight migration: would break existing docs structure and custom branding
+- ❌ api-extractor: overkill for open-source SDK; designed for strict monorepo contracts
+
+**Effort Estimate:** 5–6 hours (setup only) → 13–18 hours (setup + JSDoc improvements) → 15–22 hours (with CI/CD automation).
+
+**StorageProvider & State Module:** Phase 2 state layer is API-docs ready (81% coverage, well-structured types, clear interface contract). Gaps: add @param/@return tags to state/io functions.
+
+**URL Structure:** `/api/classes/squad-coordinator/`, `/api/interfaces/storage-provider/`, etc. Pagefind indexes automatically.
+
+**Deliverable:** Full research at `docs/research/jsdoc-api-reference-research.md` with configuration templates, implementation roadmap (4 phases), and tool comparison matrix. Decision summary at `.squad/decisions/inbox/pao-jsdoc-research.md`.
+
 ### Issue Triage (2026-03-22T06:44:01Z)
 
 **Flight triaged 6 unlabeled issues and filed 1 new issue.**
@@ -192,3 +251,37 @@ Teams MCP critical update: Office 365 Connectors retired Dec 2024 → Power Auto
 **Commit:** `docs: rewrite PUBLISH-README.md as release playbook (#564)` on squad/release-hardening branch.
 
 📌 **Team update (2026-03-24T06-release-hardening):** Release playbook rewrite (#564) completed. PUBLISH-README.md transformed from v0.8.22 stub to living 232-line playbook with 11 sections: Overview, Pre-Flight Checklist, Publish via CI (recommended), Publish via workflow_dispatch, Insider Channel, Workspace Publish Policy, Manual Local Publish (emergency fallback), 422 Race Condition & npm Errors, Post-Publish Verification, Version Bump After Publish, Legacy Publish Scripts. Absorbed issues #558, #559, #560 into unified decision tree. Microsoft Style Guide enforced; version-agnostic; all commands runnable. Scannability: checklist format, bash code blocks, error reference table. Committed to squad/release-hardening.
+### JSDoc API Reference PRD (2026-03-24)
+
+Completed full PRD based on research findings. **Document:** `docs/research/jsdoc-api-reference-prd.md`.
+
+**Structure (8 major sections):**
+1. Problem Statement — 5 concrete gaps (no dedicated API ref, uneven JSDoc coverage, discoverability, StorageProvider docs lag, Pagefind misses API symbols)
+2. Goals & Success Metrics — 4 primary goals, 8 measurable targets (100% JSDoc coverage, 50+ auto-documented symbols, searchable API)
+3. Key User Scenarios — 4 personas (SDK consumer, contributor, agent author, evaluator) with today vs future workflows
+4. Scope — clear in/out boundaries (TypeDoc + JSDoc improvements in; CLI ref gen, Starlight migration, multi-version docs out)
+5. Approach — architecture (TypeDoc in Astro hook), config template (typedoc.json), output/URL structure, build integration code, JSDoc improvement plan with effort table
+6. Implementation Phases — 4 phases: Phase 0 (setup/PoC, 1–2 days), Phase 1 (JSDoc audit, 5–6 hrs), Phase 2 (integration/nav, 3–4 hrs), Phase 3 (CI/CD optional, 2–4 hrs)
+7. Risks & Mitigations — 7 risks (TypeDoc breaks on changes, stale markdown, link validation strictness, Pagefind misses, config maintenance, build perf, breaking changes) with specific mitigations
+8. Architecture Review section — 4 items for CONTROL to review (TypeScript export strategy, TypeDoc config, JSDoc standards, stability commitments)
+
+**Key decisions baked into PRD:**
+- TypeDoc + typedoc-plugin-markdown (not Starlight, not api-extractor) — zero migration, Markdown-first, Pagefind-compatible
+- Astro integration hook auto-runs TypeDoc on build (single step: `npm run build`)
+- Generated output goes to docs/src/content/docs/reference/api/ (one file per symbol)
+- JSDoc improvement priority: config/schema.ts (8% → 100%), state/io/ functions (@param/@return tags), StorageProvider interface audit
+- Total effort: 13–18 hours (8–12 JSDoc + 5–6 setup)
+
+**Style & Tone:**
+- Written for Flight-level review/approval (actionable, opinionated, specific)
+- Includes code examples (typedoc.json, Astro hook, JSDoc template)
+- References research doc for detailed findings
+- PRD as decision/commitment document — not advisory, but directive
+
+**Learnings:**
+- PRD structure differs from research (research = exploratory findings/options; PRD = chosen path + tactical roadmap)
+- Recommendation section in PRD serves as binding decision (TypeDoc chosen, rationale locked in)
+- Architecture Review section ensures TypeScript team reviews export strategy and JSDoc standards early — prevents rework later
+- Four-phase approach breaks large effort into digestible increments (Phase 0 validation before JSDoc audit helps mitigate risk of TypeDoc setup failing)
+
+**Decision:** PRD approved for handoff to implementation team. Ready for execution on next sprint.
diff --git a/.squad/skills/pr-screenshots/SKILL.md b/.squad/skills/pr-screenshots/SKILL.md
new file mode 100644
index 000000000..fc93e8f77
--- /dev/null
+++ b/.squad/skills/pr-screenshots/SKILL.md
@@ -0,0 +1,149 @@
+---
+name: "pr-screenshots"
+description: "Capture Playwright screenshots and embed them in GitHub PR descriptions"
+domain: "pull-requests, visual-review, docs, testing"
+confidence: "high"
+source: "earned (multiple sessions establishing the pattern for PR #11 TypeDoc API reference)"
+---
+
+## Context
+
+When a PR includes visual changes (docs sites, UI components, generated pages), reviewers
+need to see what the PR delivers without checking out the branch. Screenshots belong in
+the **PR description body**, not as committed files and not as text descriptions.
+
+Use this skill whenever:
+- A PR touches docs site pages (Astro, Starlight, etc.)
+- A PR adds or changes UI components
+- A PR generates visual artifacts (TypeDoc, Storybook, diagrams)
+- Playwright tests already capture screenshots as part of testing
+
+## Patterns
+
+### 1. Capture screenshots with Playwright
+
+If Playwright tests already exist and produce screenshots, reuse those. Otherwise,
+write a minimal capture script:
+
+```javascript
+// scripts/capture-pr-screenshots.mjs
+import { chromium } from 'playwright';
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
+
+const screenshots = [
+  { url: 'http://localhost:4321/path/to/page', name: 'feature-landing' },
+  { url: 'http://localhost:4321/path/to/detail', name: 'feature-detail' },
+];
+
+for (const { url, name } of screenshots) {
+  await page.goto(url, { waitUntil: 'networkidle' });
+  await page.screenshot({ path: `screenshots/${name}.png`, fullPage: false });
+}
+
+await browser.close();
+```
+
+### 2. Host screenshots on a temporary branch
+
+GitHub PR descriptions render images via URLs. The `gh` CLI cannot upload binary
+images directly. Use a temporary orphan branch to host the images:
+
+```powershell
+# Save current branch
+$currentBranch = git branch --show-current
+
+# Create orphan branch with only screenshot files
+git checkout --orphan screenshots-temp
+git reset
+git add screenshots/*.png
+git commit -m "screenshots for PR review"
+git push origin screenshots-temp --force
+
+# Build raw URLs
+$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots"
+# Each image: $base/{name}.png
+
+# Return to working branch
+git checkout -f $currentBranch
+```
+
+### 3. Embed in PR description
+
+Use `gh pr edit` with the raw URLs embedded as markdown images:
+
+```powershell
+$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots"
+
+gh pr edit {PR_NUMBER} --repo {owner}/{repo} --body @"
+## {PR Title}
+
+### What this PR delivers
+- {bullet points of changes}
+
+---
+
+### Screenshots
+
+#### {Page/Feature Name}
+![{alt text}]($base/{name}.png)
+
+#### {Another Page}
+![{alt text}]($base/{another-name}.png)
+
+---
+
+### To verify locally
+```bash
+{commands to run locally}
+```
+"@
+```
+
+### 4. Cleanup after merge
+
+After the PR is merged, delete the temporary branch:
+
+```bash
+git push origin --delete screenshots-temp
+```
+
+### 5. Gitignore screenshots locally
+
+Screenshots are build artifacts — never commit them to feature branches:
+
+```gitignore
+# PR screenshots (hosted on temp branch, not committed to features)
+screenshots/
+docs/tests/screenshots/
+```
+
+## Examples
+
+### Example: Docs site PR with 3 pages
+
+1. Start dev server: `cd docs && npm run dev`
+2. Run Playwright tests (they capture screenshots as a side effect)
+3. Push screenshots to `screenshots-temp` branch
+4. Update PR body with embedded `![...]()` image references
+5. Reviewer sees the pages inline without checking out the branch
+
+### Example: Reusing existing Playwright test screenshots
+
+If tests at `docs/tests/*.spec.mjs` already save to `docs/tests/screenshots/`:
+
+```powershell
+cd docs && npx playwright test tests/api-reference.spec.mjs
+# Screenshots now at docs/tests/screenshots/*.png
+# Push those to screenshots-temp and embed in PR
+```
+
+## Anti-Patterns
+
+- ❌ **Committing screenshots to feature branches** — they bloat the repo and go stale
+- ❌ **Posting text descriptions instead of actual images** — reviewers can't see what they're getting
+- ❌ **Using `gh` CLI to "upload" images** — `gh issue comment` and `gh pr edit` don't support binary uploads
+- ❌ **Asking the user to manually drag-drop images** — automate it with the temp branch pattern
+- ❌ **Skipping screenshots for visual PRs** — if the PR changes what users see, show what users see
+- ❌ **Leaving the screenshots-temp branch around forever** — clean up after merge
diff --git a/docs/package-lock.json b/docs/package-lock.json
index c26fe6e5f..ee1c24006 100644
--- a/docs/package-lock.json
+++ b/docs/package-lock.json
@@ -17,6 +17,7 @@
         "unist-util-visit": "^5.1.0"
       },
       "devDependencies": {
+        "@playwright/test": "^1.58.2",
         "pagefind": "^1.4.0"
       }
     },
@@ -1215,6 +1216,22 @@
         "win32"
       ]
     },
+    "node_modules/@playwright/test": {
+      "version": "1.58.2",
+      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.58.2.tgz",
+      "integrity": "sha512-akea+6bHYBBfA9uQqSYmlJXn61cTa+jbO87xVLCWbTqbWadRVmhxlXATaOjOgcBaWU4ePo0wB41KMFv3o35IXA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright": "1.58.2"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@rollup/pluginutils": {
       "version": "5.3.0",
       "resolved": "https://registry.npmjs.org/@rollup/pluginutils/-/pluginutils-5.3.0.tgz",
@@ -5132,6 +5149,53 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
+    "node_modules/playwright": {
+      "version": "1.58.2",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.58.2.tgz",
+      "integrity": "sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.58.2"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "fsevents": "2.3.2"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.58.2",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.58.2.tgz",
+      "integrity": "sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/playwright/node_modules/fsevents": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
     "node_modules/postcss": {
       "version": "8.5.8",
       "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.8.tgz",
diff --git a/docs/package.json b/docs/package.json
index 9a4b0ceca..488a4890d 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -22,6 +22,7 @@
     "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
+    "@playwright/test": "^1.58.2",
     "pagefind": "^1.4.0"
   }
 }
diff --git a/docs/research/api-sidebar-nav-plan.md b/docs/research/api-sidebar-nav-plan.md
new file mode 100644
index 000000000..104e2132d
--- /dev/null
+++ b/docs/research/api-sidebar-nav-plan.md
@@ -0,0 +1,126 @@
+# Plan: API Reference Sidebar Navigation
+
+## Problem
+
+The auto-generated TypeDoc API reference (395 pages) has no sidebar navigation. The sidebar shows a single "API Reference (TypeDoc)" link to the landing page. Users must navigate all 395 pages through the landing page's link lists — no category browsing from the sidebar.
+
+## Current Architecture
+
+- **Sidebar:** `docs/src/components/Sidebar.astro` renders `NAV_SECTIONS` from `navigation.ts`
+- **Nav structure:** Flat sections → items. No nested/collapsible groups.
+- **Generation script:** `scripts/generate-api-docs.mjs` already categorizes files into Classes, Interfaces, Functions, Type aliases, Variables (Step 4)
+- **TypeDoc config:** `flattenOutputFiles: true` — all pages are flat in `reference/api/`
+- **File naming:** `class-*.md`, `interface-*.md`, `function-*.md`, `typealias-*.md`, `variable-*.md`
+
+## Approach: Auto-Generated Nav Fragment + Collapsible Sidebar
+
+### Step 1: Generate nav data from the build script
+
+Extend `generate-api-docs.mjs` to output a nav fragment file after categorization:
+
+**Output:** `docs/src/api-nav-generated.json` (gitignored, built at CI/deploy time)
+
+```json
+{
+  "categories": [
+    {
+      "title": "Classes",
+      "items": [
+        { "title": "CastingEngine", "slug": "reference/api/class-castingengine" },
+        { "title": "RuntimeEventBus", "slug": "reference/api/class-runtimeeventbus" }
+      ]
+    },
+    {
+      "title": "Interfaces",
+      "items": [
+        { "title": "AgentCapability", "slug": "reference/api/interface-agentcapability" },
+        { "title": "SquadConfig", "slug": "reference/api/interface-squadconfig" }
+      ]
+    },
+    {
+      "title": "Functions",
+      "items": [
+        { "title": "defineSquad", "slug": "reference/api/function-definesquad" },
+        { "title": "loadConfig", "slug": "reference/api/function-loadconfig" }
+      ]
+    },
+    {
+      "title": "Type Aliases",
+      "items": [...]
+    },
+    {
+      "title": "Variables",
+      "items": [...]
+    }
+  ]
+}
+```
+
+### Step 2: Import generated nav into navigation.ts
+
+```typescript
+// navigation.ts
+import apiNav from './api-nav-generated.json' assert { type: 'json' };
+
+// In the Reference section, replace the single API Reference entry
+// with a marker that Sidebar.astro expands into collapsible sub-groups
+```
+
+Alternatively, `navigation.ts` can export a separate `API_NAV_SECTIONS` that the sidebar renders differently from the main nav.
+
+### Step 3: Add collapsible groups to Sidebar.astro
+
+The current sidebar renders flat section → items. For API reference categories with 50-200+ items each, we need collapsible groups.
+
+**Option A — Collapsible `<details>` elements:**
+```html
+<details>
+  <summary>Classes (15)</summary>
+  <ul><!-- class items --></ul>
+</details>
+```
+
+**Option B — CSS-driven collapse with state:**
+Use a toggle button per category. CSS `max-height` transition. Persist open/closed state in `localStorage`.
+
+**Recommendation:** Option A (`<details>/<summary>`) — semantic HTML, no JS needed, accessible by default. Add a CSS transition for polish.
+
+### Step 4: Handle the "Functions" problem
+
+Functions is the largest category (~200+ items). Even collapsed, opening it would create a very long sidebar section. Options:
+
+1. **Sub-categorize Functions** by module/namespace (if TypeDoc output contains module info)
+2. **Show only the top N** with a "Show all →" link to the landing page
+3. **Accept the long list** — `<details>` keeps it collapsed by default, user opens on purpose
+4. **Add a search/filter** within the sidebar section
+
+**Recommendation:** Start with option 3 (collapsed by default). If UX feedback says it's too much, add option 2 as a follow-up.
+
+### Step 5: Gitignore the generated nav file
+
+Add to `.gitignore`:
+```
+docs/src/api-nav-generated.json
+```
+
+### Step 6: Wire into build pipeline
+
+`npm run docs:api` already runs the generation script. The nav fragment is produced as a side effect. The Astro build reads it at compile time. No separate build step needed.
+
+## File Changes Summary
+
+| File | Change |
+|------|--------|
+| `scripts/generate-api-docs.mjs` | Add Step 6: write `api-nav-generated.json` |
+| `docs/src/navigation.ts` | Import generated nav, export for sidebar |
+| `docs/src/components/Sidebar.astro` | Add collapsible group rendering for API categories |
+| `.gitignore` | Add `docs/src/api-nav-generated.json` |
+| `docs/tests/api-reference.spec.mjs` | Add test: sidebar shows category groups |
+
+## Open Questions
+
+1. Should categories default to collapsed or expanded? (Recommend: collapsed)
+2. Should the "SDK Guide" link stay alongside the API categories in Reference? (Recommend: yes — it's the curated companion)
+3. Should we add item counts to category headers? e.g., "Classes (15)" (Recommend: yes)
+4. Does the Astro build fail gracefully if the generated JSON doesn't exist? (Need fallback for fresh clones before first `docs:api` run)
+5. **CI/CD build order:** `npm run docs:api` must run **before** `npm run docs:build` in CI pipelines, since the Astro build reads the generated nav JSON and API markdown at compile time. If the generated `api-nav-generated.json` is missing (e.g., first clone, or `docs:api` was skipped), the sidebar should fall back to showing a single flat "API Reference" link pointing to `/reference/api/` instead of rendering category groups. The build must not fail on a missing nav fragment.
diff --git a/docs/research/jsdoc-api-reference-prd.md b/docs/research/jsdoc-api-reference-prd.md
new file mode 100644
index 000000000..7e3984042
--- /dev/null
+++ b/docs/research/jsdoc-api-reference-prd.md
@@ -0,0 +1,452 @@
+# JSDoc API Reference Documentation PRD
+
+> Auto-generate discoverable, searchable API reference docs for Squad SDK and CLI using TypeDoc + Markdown.
+
+## Problem Statement
+
+The Squad SDK has a mature, well-typed TypeScript codebase, but **developers lack a canonical source for API documentation**. Today:
+
+1. **No dedicated API reference** — Developers must dig through TypeScript source files or JSDoc comments in the IDE to understand the public API surface (SquadCoordinator, StorageProvider, SquadState, config types).
+
+2. **Documentation debt** — JSDoc coverage is uneven (8%–81% across modules). Config schema, state I/O functions, and some core utilities lack @param/@return documentation, making the API harder to learn.
+
+3. **Discoverability** — There's no searchable, linkable page for "what methods does StorageProvider expose?" or "how do I implement a custom AgentHandle?". External developers evaluating Squad can't quickly assess the SDK's public API surface.
+
+4. **Integration docs lag** — StorageProvider (Phase 2 state layer, PR #481) has no user-facing documentation of the interface contract or implementation patterns.
+
+5. **Search misses** — Pagefind indexes guide docs but not API symbols. Searching "SquadState" on the docs site returns zero results despite the type being central to Squad's architecture.
+
+**Impact**: New SDK users experience friction during onboarding. Contributors struggle to understand which modules to extend. Evaluating Squad's API surface requires reading source code.
+
+---
+
+## Goals & Success Metrics
+
+### Primary Goals
+
+1. **Generate production-ready API reference docs** for Squad SDK (packages/squad-sdk/src/) covering all exported symbols (classes, interfaces, functions, type aliases).
+
+2. **Achieve searchable API surface** — Every exported symbol indexed by Pagefind and discoverable via `/squad/` search.
+
+3. **Improve JSDoc coverage** to 100% for all exported public APIs (StorageProvider, SquadState, SquadCoordinator, config types, state I/O functions).
+
+4. **Enable self-service developer discovery** — External developers can answer "what's the API?" without filing issues or reading source.
+
+### Success Metrics
+
+- ✅ **100% JSDoc coverage** for all exported symbols across packages/squad-sdk/src/
+- ✅ **API landing page** at /reference/api-reference/ with overview + navigation
+- ✅ **Auto-generated API pages** for 50+ public types/classes/functions
+- ✅ **Pagefind indexing** — search "StorageProvider" or "SquadCoordinator" and get instant results
+- ✅ **Build integration** — `npm run build` auto-generates API docs (no extra step)
+- ✅ **Zero broken internal links** in generated docs (validated by CI)
+- ✅ **Mobile-friendly** API pages rendering correctly on docs site
+- ✅ **Maintenance overhead < 2 hours/sprint** — JSDoc updates happen with code changes, not in separate passes
+
+---
+
+## Key User Scenarios
+
+### Scenario 1: New SDK Consumer — "How do I use SquadState?"
+
+> A developer building a custom agent using the SDK imports `SquadState` but doesn't know what methods are available or what properties the domain types expose.
+
+**Today**: Opens TypeScript IDE, searches in node_modules, reads source comments.
+
+**Future**: Visits /reference/api/classes/squad-state/, sees complete method signatures, usage examples, and links to guides like "Building Custom Agents".
+
+### Scenario 2: Contributor — "What does StorageProvider require?"
+
+> A contributor wants to implement a custom StorageProvider but needs to understand the interface contract—what methods are mandatory, what are the error semantics, what does SquadState expect?
+
+**Today**: Reads PR #481, searches interface definition in state/domain-types.ts, cross-references implementation tests.
+
+**Future**: Visits /reference/api/interfaces/storage-provider/, sees full interface documentation with method descriptions, error types, and links to FSStorageProvider implementation.
+
+### Scenario 3: Agent Author — "What are AgentHandle methods?"
+
+> An agent in .squad/agents/ needs to understand what operations it can perform on squad state (get an agent's decisions, read team config, etc.).
+
+**Today**: Grep for AgentHandle, read method names from type definition, reverse-engineer from example agents.
+
+**Future**: Visits /reference/api/interfaces/agent-handle/, sees method signatures with descriptions, returns types, and examples.
+
+### Scenario 4: Evaluator — "What's Squad's API surface?"
+
+> A technical leader deciding whether to adopt Squad wants to see the public API surface and assess stability/maturity.
+
+**Today**: Reads README, glances at a few source files, asks on Discussions.
+
+**Future**: Visits /reference/api/, sees organized module list, scans interfaces/classes, assesses API surface in 5 minutes.
+
+---
+
+## Scope
+
+### In Scope ✅
+
+- **TypeDoc configuration** (typedoc.json, Astro integration hook)
+- **JSDoc improvements** for:
+  - Config schema (config/schema.ts) — currently 8% coverage
+  - State I/O functions (state/io/*.ts) — add @param/@return tags
+  - StorageProvider interface (state/domain-types.ts) — review + enhance docs
+  - Core types (runtime/config.ts, agents/lifecycle.ts) — spot-check and refine
+- **Generated API markdown** output structure (classes/, interfaces/, functions/, types/ directories)
+- **API landing page** (docs/src/content/docs/reference/api-reference.md) — conceptual overview + links to generated docs
+- **Navigation integration** — add API reference to docs site navigation (navigation.ts)
+- **Pagefind indexing** — verify API pages are searchable via existing plugin
+- **Build pipeline integration** — Astro hook to auto-run TypeDoc on every build
+- **Phase 1 foundation** — TypeDoc setup + proof-of-concept generation
+
+### Out of Scope ❌
+
+- **CLI reference generation** — may be future Phase 2 (separate TypeDoc config for packages/squad-cli/src/)
+- **Code examples/tutorials** — those belong in guide/ and concept/ pages, not API reference
+- **Starlight migration** — keeping plain Astro 5 setup
+- **Custom CSS styling** for API pages — use existing Astro design system
+- **Multi-version API docs** (v0.8 vs v0.9 side-by-side) — single current version only
+- **CI/CD automation** (pre-generate as artifact, auto-regenerate on release) — Phase 2 optimization
+- **TypeDoc plugin authoring** — use typedoc-plugin-markdown only
+
+---
+
+## Approach
+
+### Architecture: TypeDoc in the Astro Build Pipeline
+
+**Why TypeDoc:**
+- ✅ Zero migration — Astro 5 + Tailwind 4 + Pagefind unchanged
+- ✅ Simple setup — one JSON config, one npm package
+- ✅ Markdown-first — output drops directly into docs/src/content/docs/reference/api/
+- ✅ Pagefind-ready — existing ehype-pagefind-attrs plugin auto-indexes generated pages
+- ✅ Open-source standard — industry-standard tool for TypeScript libraries
+- ❌ NOT Starlight (would require full docs migration)
+- ❌ NOT api-extractor (overkill for SDK, two-step process)
+
+**Build Flow:**
+
+```
+npm run build (from docs/)
+  ↓
+Astro.build()
+  ↓
+astro:build:start hook → exec('npx typedoc --config ../typedoc.json')
+  ↓
+TypeDoc generates markdown → docs/src/content/docs/reference/api/
+  ↓
+Astro processes with remark/rehype plugins
+  ↓
+ehype-pagefind-attrs marks H1/H2/H3 as searchable
+  ↓
+Pagefind indexes dist/
+  ↓
+Final site includes searchable API pages
+```
+
+### Configuration: typedoc.json
+
+Create `typedoc.json` at repository root:
+
+```json
+{
+  "entryPoints": ["./packages/squad-sdk/src/index.ts"],
+  "out": "./docs/src/content/docs/reference/api",
+  "plugin": ["typedoc-plugin-markdown"],
+  "pluginPages": {
+    "output": "modules"
+  },
+  "markdown": {
+    "outputFileStrategy": "modules",
+    "anchorPrefix": "api"
+  },
+  "excludePrivate": true,
+  "excludeInternal": true,
+  "excludeExternals": true,
+  "tsconfig": "./packages/squad-sdk/tsconfig.json",
+  "gitRevision": "main",
+  "readme": "none",
+  "hideGenerator": false,
+  "sourceLinkExternal": true
+}
+```
+
+**Key settings:**
+- `entryPoints` — packages/squad-sdk/src/index.ts (barrel exports all public API)
+- `out` — generates into docs/src/content/docs/reference/api/
+- `pluginPages` — uses typedoc-plugin-markdown for markdown output
+- `excludePrivate`, `excludeInternal` — hide implementation details
+- `markdown.outputFileStrategy: "modules"` — one file per symbol for clean URLs
+- `anchorPrefix` — ensures anchors use "api-" prefix to avoid conflicts
+
+### Output Structure: File Organization
+
+```
+docs/src/content/docs/reference/
+├── api-reference.md          (hand-written landing page, NOT generated)
+└── api/                      (TypeDoc-generated output)
+    ├── index.md              (modules overview)
+    ├── classes/
+    │   ├── squad-coordinator.md
+    │   ├── squad-state.md
+    │   └── storage-provider-base.md
+    ├── interfaces/
+    │   ├── agent.md
+    │   ├── agent-handle.md
+    │   ├── squad-config.md
+    │   ├── storage-provider.md
+    │   ├── squad-state.md
+    │   └── ... (50+ more types)
+    ├── functions/
+    │   ├── parse-charter.md
+    │   ├── serialize-charter.md
+    │   └── ... (state I/O functions)
+    └── types/
+        ├── agent-handle.md
+        ├── decision.md
+        └── ... (type aliases)
+```
+
+### URL Structure: Developer-Friendly Paths
+
+```
+/reference/api-reference/               (overview landing page)
+/reference/api/                         (index of all modules)
+/reference/api/classes/squad-coordinator/
+/reference/api/classes/squad-state/
+/reference/api/interfaces/agent/
+/reference/api/interfaces/storage-provider/
+/reference/api/functions/parse-charter/
+/reference/api/types/decision/
+```
+
+### Build Integration: Astro Hook + npm Script
+
+Add integration to `docs/astro.config.mjs`:
+
+```javascript
+import { defineConfig } from 'astro/config';
+import { execSync } from 'child_process';
+import tailwind from '@astrojs/tailwind';
+import pageFind from 'astro-pagefind';
+
+export default defineConfig({
+  integrations: [
+    {
+      name: 'typedoc-integration',
+      hooks: {
+        'astro:build:start': async () => {
+          console.log('Generating TypeDoc API reference...');
+          try {
+            execSync('npx typedoc --config ../typedoc.json', { stdio: 'inherit' });
+            console.log('✅ TypeDoc generation complete');
+          } catch (error) {
+            console.error('❌ TypeDoc generation failed:', error.message);
+            throw error;
+          }
+        },
+      },
+    },
+    tailwind(),
+    pageFind(),
+  ],
+});
+```
+
+**Usage:**
+
+```bash
+cd docs/
+npm run build
+# Output includes:
+# - TypeDoc API reference at docs/src/content/docs/reference/api/
+# - Astro processes markdown
+# - Pagefind indexes all content
+# - Final site with searchable API pages
+```
+
+### JSDoc Improvement Plan: Priority Order
+
+Estimated effort: **8–12 hours** across 1–2 sprints.
+
+#### Priority 1: High-Impact Gaps (6–8 hours)
+
+| Module | Issue | Action | Time |
+|--------|-------|--------|------|
+| `config/schema.ts` | 8% JSDoc coverage | Add @param/@return tags to all 12 exported functions | 2–3 hrs |
+| `state/io/*.ts` | No @param/@return tags on parser/serializer functions | Add to parseCharter, serializeCharter, parseHistory, serializeHistory, parseDecisions, serializeDecisions, parseTeamConfig, serializeTeamConfig, parseRouting, serializeRouting | 3–4 hrs |
+| `state/domain-types.ts` | StorageProvider interface — review completeness | Audit docs, add missing @param descriptions to interface methods | 1–2 hrs |
+
+#### Priority 2: Coverage Audit (2–4 hours)
+
+| Module | Status | Action |
+|--------|--------|--------|
+| `runtime/config.ts` | Good (331% blocks) | Spot-check for clarity, refine descriptions |
+| `coordinator/coordinator.ts` | Good (320% blocks) | Ensure return types have clear descriptions |
+| `agents/lifecycle.ts` | Good (680% blocks) | Verify example code is up-to-date |
+| `platform/*.ts`, `runtime/*.ts` | 60%+ coverage | Light audit for missing @param tags |
+
+#### Checklist
+
+- [ ] Add @param/@return tags to config/schema.ts exports
+- [ ] Document state/io/ parser/serializer functions (@param content, @returns ParsedCharter)
+- [ ] Review StorageProvider interface docs (interface methods, error types, examples)
+- [ ] Audit runtime/ and platform/ for missing @param tags
+- [ ] Run TypeDoc locally: `npx typedoc --config typedoc.json`
+- [ ] Review generated markdown for accuracy
+- [ ] Spot-check 5–10 generated pages in browser
+
+---
+
+## Implementation Phases
+
+### Phase 0: TypeDoc Setup & Proof of Concept (Days 1–2)
+
+**Goal**: Validate that TypeDoc generates working markdown and integrates with Astro build.
+
+**Tasks:**
+- [ ] Install TypeDoc + typedoc-plugin-markdown: `npm install --save-dev typedoc typedoc-plugin-markdown`
+- [ ] Create typedoc.json at repository root (copy from "Configuration" section)
+- [ ] Run TypeDoc locally: `npx typedoc --config typedoc.json`
+- [ ] Verify generated markdown in docs/src/content/docs/reference/api/
+- [ ] Add Astro integration hook to docs/astro.config.mjs
+- [ ] Test full Astro build: `npm run build` from docs/
+- [ ] Verify API pages render on docs site
+- [ ] Spot-check 3–5 generated pages (SquadCoordinator, StorageProvider, AgentHandle)
+
+**Definition of Done:**
+- TypeDoc generates without errors
+- Generated markdown is valid and renders on docs site
+- At least 50 public symbols documented in generated files
+- Astro build completes in <2 min including TypeDoc step
+
+### Phase 1: JSDoc Coverage Improvement (Sprint 1, 5–6 hours)
+
+**Goal**: Achieve 100% JSDoc coverage for all exported public APIs.
+
+**Tasks:**
+- [ ] Audit config/schema.ts — add @param/@return tags to all 12 exports
+- [ ] Audit state/io/*.ts — add @param/@return tags to parser/serializer functions
+- [ ] Review StorageProvider interface — enhance JSDoc clarity
+- [ ] Light spot-check of runtime/config.ts, coordinator/coordinator.ts
+- [ ] Regenerate TypeDoc: `npx typedoc --config typedoc.json`
+- [ ] Review generated markdown for new/improved documentation
+
+**Success Criteria:**
+- [ ] No exported symbols lack @param/@return JSDoc
+- [ ] StorageProvider interface has complete documentation
+- [ ] config/schema.ts JSDoc coverage improves from 8% → 100%
+- [ ] state/io/ functions have clear parameter/return descriptions
+
+### Phase 2: Astro Integration & Navigation (Sprint 1–2, 3–4 hours)
+
+**Goal**: Surface API reference in docs navigation, ensure discoverability.
+
+**Tasks:**
+- [ ] Create docs/src/content/docs/reference/api-reference.md — hand-written landing page with:
+  - Problem statement: "Why you need API docs"
+  - Quick nav to key symbols (SquadCoordinator, StorageProvider, SquadConfig)
+  - Links to related guides (Building Custom Agents, Implementing StorageProvider)
+- [ ] Add "API Reference" entry to docs/src/navigation.ts pointing to /reference/api-reference/
+- [ ] Add breadcrumb links from guides → API reference (where relevant)
+- [ ] Test build: `npm run build` from docs/
+- [ ] Verify Pagefind indexes API pages: grep "classes/squad-coordinator" dist/.pagefind/pagefind.json
+- [ ] Manual spot-check: search "StorageProvider" on docs site, verify results
+
+**Success Criteria:**
+- [ ] /reference/api-reference/ page exists and renders
+- [ ] Navigation includes "API Reference" entry
+- [ ] Pagefind indexes 50+ API symbols
+- [ ] Search returns instant results for "SquadCoordinator", "StorageProvider", etc.
+
+### Phase 3: CI/CD & Maintenance Automation (Phase 2, Optional, 2–4 hours)
+
+**Goal**: Prevent API docs from going stale, catch broken links.
+
+**Tasks:**
+- [ ] Add CI/CD check to validate API docs regenerate correctly on every commit
+- [ ] Set up pre-generation of API docs as CI artifact (avoid rebuild overhead)
+- [ ] Add link validator to catch broken internal references in generated docs
+- [ ] Document JSDoc style guide for contributors (comment every @export symbol)
+
+**Success Criteria:**
+- [ ] CI workflow validates TypeDoc generation
+- [ ] Link validation catches broken references
+- [ ] Contributor docs clarify JSDoc requirements for new exports
+
+---
+
+## Risks & Mitigations
+
+| Risk | Impact | Mitigation |
+|------|--------|-----------|
+| TypeDoc breaks on SDK changes | Builds fail silently | Add CI gate: TypeDoc must generate without errors before docs build |
+| Generated markdown becomes stale | API docs lag behind code | JSDoc coverage requirement: 100% for all exports, enforced in code review |
+| Link validation too strict | Builds blocked on minor issues | Start with warnings only (CI info-only), escalate to errors in Phase 2 |
+| Pagefind indexing misses API pages | Search doesn't find API symbols | Manually verify indexing after each build (check dist/.pagefind/pagefind.json) |
+| TypeDoc config needs updates for new SDK features | Config maintenance overhead | Document config in CONTRIBUTING.md, update as SDK evolves |
+| Large number of generated files slows build | Build time regression | Monitor build performance; if >3 min, consider pre-generation as artifact |
+| Breaking changes to public API break existing docs | Outdated links | Future: implement link redirects or version docs (Phase 2+) |
+
+---
+
+## Architecture Review Section
+
+**For CONTROL (TypeScript/Architecture Authority):**
+
+Please review and approve:
+
+1. **TypeScript Export Strategy** — Are all public symbols correctly exported via packages/squad-sdk/src/index.ts (barrel file)?
+   - Should StorageProvider implementations be exported separately or only documented as examples?
+   - Should internal utilities be marked `/** @internal */` in JSDoc?
+
+2. **TypeDoc Configuration** — Is the config appropriate for Squad's SDK surface?
+   - Are excludePrivate/excludeInternal settings correct?
+   - Should we document types vs interfaces differently?
+
+3. **JSDoc Standards** — Should we establish guidelines for contributors?
+   - Suggested template: `/** Description. @param name Type description. @returns Type description. */`
+   - Should we enforce @example blocks for complex APIs (StorageProvider, SquadState)?
+
+4. **Stability Commitment** — Are all exported symbols stable, or should some be marked `@beta`/`@alpha`?
+   - StorageProvider (Phase 2) — ready for stable?
+   - SquadState collection map navigation — stable?
+   - Config schema validation — stable?
+
+---
+
+## Success Criteria Checklist
+
+- [ ] TypeDoc setup complete, auto-runs on `npm run build`
+- [ ] 100% JSDoc coverage for packages/squad-sdk/src/ exports
+- [ ] 50+ public symbols auto-documented in generated markdown
+- [ ] API landing page created at /reference/api-reference/
+- [ ] Navigation updated with "API Reference" entry
+- [ ] Pagefind indexes all API pages — search returns results for key symbols
+- [ ] All internal links in generated docs are valid (manual spot-check)
+- [ ] Mobile rendering looks good on docs site
+- [ ] Build time increase <1 min (TypeDoc generation overhead)
+- [ ] Zero broken links in generated markdown
+- [ ] Documentation matches code (automated via JSDoc → generated docs)
+
+---
+
+## Timeline & Effort Summary
+
+| Phase | Duration | FTE | Notes |
+|-------|----------|-----|-------|
+| **Phase 0: Setup + PoC** | 1–2 days | 1 | Validate TypeDoc generation + Astro integration |
+| **Phase 1: JSDoc Improvement** | 1 sprint (5–6 hrs) | 0.25–0.5 | Focus on high-impact gaps (config/, state/io/) |
+| **Phase 2: Integration + Navigation** | 1 sprint (3–4 hrs) | 0.25–0.5 | Create landing page, update nav, verify Pagefind |
+| **Phase 3: CI/CD (Optional)** | 2–4 hrs | — | Phase 2: Link validation, artifact pre-gen |
+| **Total (Phases 0–2)** | **2–3 weeks** | **0.5 FTE** | Production-ready API reference |
+
+---
+
+## References
+
+- **Research Document**: docs/research/jsdoc-api-reference-research.md (findings, tool comparison, effort estimates)
+- **TypeDoc**: https://typedoc.org/
+- **typedoc-plugin-markdown**: https://github.com/tgreyuk/typedoc-plugin-markdown
+- **Astro Integration API**: https://docs.astro.build/en/guides/integrations-guide/
+- **Pagefind**: https://pagefind.app/
+- **Related PR**: #481 (StorageProvider interface, Phase 2 state layer)
diff --git a/docs/research/jsdoc-api-reference-research.md b/docs/research/jsdoc-api-reference-research.md
new file mode 100644
index 000000000..50908d37c
--- /dev/null
+++ b/docs/research/jsdoc-api-reference-research.md
@@ -0,0 +1,334 @@
+# JSDoc API Reference Documentation Research
+
+## Executive Summary
+
+The Squad SDK has moderate JSDoc coverage (~60–80% across major modules) with room for improvement, particularly in type/interface definitions. **TypeDoc + markdown plugin** is the recommended approach for auto-generating API reference docs—it integrates seamlessly with the existing plain Astro 5 setup (no Starlight migration needed), works with Pagefind search, and requires minimal setup overhead. Estimated effort: **1–2 weeks** to achieve production-ready docs covering the SDK and CLI.
+
+---
+
+## Current State Audit
+
+### JSDoc Coverage by Module
+
+| Module | Exports | JSDoc Blocks | Coverage |
+|--------|---------|--------------|----------|
+| **state/domain-types.ts** (StorageProvider interface, SquadState) | 21 | 17 | 81% |
+| **coordinator/coordinator.ts** (SquadCoordinator) | 5 | 16 | 320%* |
+| **config/schema.ts** (Config validation) | 12 | 1 | 8% |
+| **runtime/config.ts** (Core types) | 26 | 86 | 331%* |
+| **agents/lifecycle.ts** (Agent lifecycle) | 5 | 34 | 680%* |
+
+*Note: High percentages indicate multiline JSDoc blocks or dense documentation; actual coverage = exports with at least one JSDoc block present.*
+
+### Key Findings
+
+- **136 TypeScript source files** in packages/squad-sdk/src/
+- **Barrel exports** in index.ts are well-documented with type imports and descriptions
+- **Domain types** (Phase 2 state layer) have good inline JSDoc on interfaces
+- **Config schema** needs attention—many exports lack JSDoc (8% coverage)
+- **State I/O modules** (state/io/*.ts) are well-structured but could benefit from parameter/return type docs
+- **No existing TypeDoc config**—starting from scratch with a simple setup
+
+### JSDoc Quality Assessment
+
+| Quality Tier | Examples | Status |
+|--------------|----------|--------|
+| **Excellent** | state/domain-types.ts, state/io/index.ts | Inline JSDoc for all types, clear descriptions |
+| **Good** | coordinator/coordinator.ts, gents/lifecycle.ts | Public methods documented, some missing return type details |
+| **Needs Work** | config/schema.ts, parsers.ts | Sparse or missing JSDoc, exported functions lack descriptions |
+
+### StorageProvider & State Module Status
+
+The new state/ module (Phase 2, PR #481) is well-positioned for API docs:
+- **StorageProvider interface** — fully typed, clear contract
+- **SquadState (domain types)** — 81% JSDoc coverage with good inline descriptions
+- **AgentHandle, CollectionEntityMap** — clearly typed
+- **Domain types** (Agent, Decision, TeamConfig, etc.) — each has inline JSDoc
+- **State I/O layer** — documented but lacks @param/@return tags on functions
+
+**Gap:** Functions like parseCharter(), serializeHistory() need @param and @return JSDoc.
+
+---
+
+## Tool Comparison
+
+| Feature | TypeDoc | api-extractor | TypeDoc (Starlight) |
+|---------|---------|---------------|-------------------|
+| **Setup complexity** | ⭐⭐⭐⭐⭐ (simple) | ⭐⭐ (requires 2 tools) | ⭐⭐⭐ (plugin only) |
+| **Markdown output** | ✅ Native | ✅ Via api-documenter | ✅ Auto-sidebar |
+| **JSDoc support** | ✅ Excellent | ⚠️ Limited | ✅ Excellent |
+| **Astro 5 plain setup** | ✅ Full support | ⚠️ Manual integration | ❌ Requires migration |
+| **Pagefind indexing** | ✅ Works seamlessly | ⚠️ Works with config | ⚠️ Uses Starlight search |
+| **Build integration** | ✅ Via Astro hook | ⚠️ Manual step | ✅ Auto-generated |
+| **No vendor lock-in** | ✅ Yes | ✅ Yes | ❌ Starlight-dependent |
+| **Custom styling** | ✅ Full control | ✅ Full control | ❌ Constrained by theme |
+
+### Recommended: TypeDoc + markdown-plugin
+
+**Why TypeDoc is the best fit:**
+
+1. ✅ **Zero migration**—keeps existing Astro 5 + Tailwind 4 + Pagefind
+2. ✅ **Simple config**—one JSON file, one npm package
+3. ✅ **Markdown-first**—output drops directly into docs/src/content/docs/reference/api/
+4. ✅ **Pagefind-ready**—your existing 
ehype-pagefind-attrs plugin indexes it automatically
+5. ✅ **Build integration**—Astro hook runs TypeDoc before build (one command: 
+pm run build)
+6. ✅ **Open-source friendly**—standard tool for public libraries
+
+**Why NOT Starlight:**
+
+- Would require migrating **entire docs structure** (breaking change)
+- Loss of custom Tailwind 4 branding and layout
+- No benefit for this use case—API docs are secondary to 70+ guide pages
+- Only reconsider if: multi-version docs, i18n, or API becomes primary focus
+
+**Why NOT api-extractor:**
+
+- Overkill for open-source SDK (designed for strict monorepo contracts)
+- Two-step process (extract → document) adds complexity
+- Weaker JSDoc support compared to TypeDoc
+
+---
+
+## Recommended Integration Approach
+
+### File Structure
+
+\\\
+docs/src/content/docs/reference/
+  ├── api-reference.md        (hand-written landing page)
+  └── api/                     (TypeDoc-generated, one-time setup)
+      ├── index.md            (generated modules index)
+      ├── classes/
+      │   ├── SquadCoordinator.md
+      │   ├── SquadState.md
+      │   └── StorageProvider.md
+      ├── interfaces/
+      │   ├── Agent.md
+      │   ├── SquadConfig.md
+      │   └── ...
+      ├── functions/
+      │   └── ... (exported utility functions)
+      └── types/
+          └── ... (type aliases)
+\\\
+
+### URL Structure
+
+\\\
+https://bradygaster.github.io/squad/reference/api-reference/     (overview page)
+https://bradygaster.github.io/squad/reference/api/               (index)
+https://bradygaster.github.io/squad/reference/api/classes/squad-coordinator/
+https://bradygaster.github.io/squad/reference/api/interfaces/agent/
+\\\
+
+### Build Workflow
+
+**Single-step integration via Astro integration hook:**
+
+\\\	ypescript
+// docs/astro.config.mjs
+import { exec } from 'child_process';
+
+export default defineConfig({
+  integrations: [
+    {
+      name: 'typedoc-integration',
+      hooks: {
+        'astro:build:start': async () => {
+          return new Promise((resolve, reject) => {
+            exec('npx typedoc --config ../typedoc.json', (err) => {
+              if (err) reject(err);
+              else resolve();
+            });
+          });
+        },
+      },
+    },
+  ],
+  // ... rest of config
+});
+\\\
+
+**Usage:** 
+pm run build automatically runs TypeDoc before Astro build.
+
+### TypeDoc Configuration
+
+\\\json
+{
+  "entryPoints": ["./packages/squad-sdk/src/index.ts"],
+  "out": "./docs/src/content/docs/reference/api",
+  "plugin": ["typedoc-plugin-markdown"],
+  "pluginPages": {
+    "output": "modules"
+  },
+  "markdown": {
+    "outputFileStrategy": "modules",
+    "anchorPrefix": "api"
+  },
+  "excludePrivate": true,
+  "excludeInternal": true,
+  "excludeExternals": true,
+  "tsconfig": "./packages/squad-sdk/tsconfig.json",
+  "gitRevision": "main",
+  "readme": "none"
+}
+\\\
+
+### Pagefind Integration
+
+✅ **Works automatically**—your existing 
ehypePagefindAttrs plugin marks TypeDoc-generated headings as indexable.
+
+**Verify:**
+\\\ash
+npm run build
+grep "classes/squad-coordinator" dist/.pagefind/pagefind.json
+\\\
+
+---
+
+## Effort Estimate
+
+### JSDoc Improvement Phase (1 week)
+
+| Task | Time | Priority |
+|------|------|----------|
+| Add missing JSDoc to config/schema.ts | 2–3 hours | High (only 8% coverage) |
+| Add @param/@return tags to state/io/* functions | 3–4 hours | High (State I/O is new) |
+| Audit + document platform/, 
untime/ exports | 2–3 hours | Medium (existing coverage >60%) |
+| Review & refine StorageProvider interface docs | 1–2 hours | High (Phase 2 blocker) |
+| **Total** | **8–12 hours** | — |
+
+### Setup Phase (1–2 days)
+
+| Task | Time |
+|------|------|
+| Install TypeDoc + markdown plugin | <30 min |
+| Create 	ypedoc.json config | 30 min |
+| Add Astro integration hook | 1 hour |
+| Create API landing page | 1 hour |
+| Update docs navigation | 30 min |
+| Test Pagefind indexing | 1 hour |
+| Verify build pipeline | 1 hour |
+| **Total** | **5–6 hours** |
+
+### CI/CD Integration (optional, 2–4 hours)
+
+- Pre-generate API docs as workflow artifact (to avoid rebuild overhead)
+- Add link validation to catch broken internal references
+- Set up auto-regeneration on SDK release
+
+### Total Estimated Effort
+
+- **Minimum (setup only):** 5–6 hours
+- **Recommended (JSDoc + setup):** 13–18 hours (1.5–2 weeks)
+- **Full (with CI/CD automation):** 15–22 hours (2–3 weeks)
+
+---
+
+## StorageProvider & State Module Specific
+
+### Current State
+
+The Phase 2 state layer (PR #481) is **API-docs ready**:
+
+- **StorageProvider interface** — strict contract, all methods documented inline
+- **SquadState entry point** — 9 exported types with clear domain semantics
+- **Collection map** — AgentHandle, CollectionEntityMap clearly defined
+- **Domain types** — Agent, Decision, HistoryEntry, TeamConfig all have JSDoc
+- **Error handling** — StateError, NotFoundError, WriteConflictError defined
+- **State I/O layer** — 6 exported parser/serializer pairs (charter, history, decisions, routing, team)
+
+### Gaps to Close
+
+1. **State I/O functions** — Add @param and @return JSDoc:
+   \\\	ypescript
+   /**
+    * Parse charter.md into typed Charter object.
+    * @param content Raw markdown content
+    * @returns Parsed charter with agents array
+    */
+   export function parseCharter(content: string): ParsedCharter
+   \\\
+
+2. **Collection map navigation** — Example documentation needed (hand-written guide, not API doc)
+
+3. **StorageProvider implementations** — Document the two built-in providers (FileSystem, InMemory)
+
+### Verdict
+
+✅ **The state module is well-suited for auto-generated API docs.** JSDoc coverage is solid (81%), types are well-structured, and the interface contract is clear.
+
+---
+
+## Pagefind Search Integration
+
+### How It Works
+
+1. **Build step:** TypeDoc generates markdown → Astro processes with remark/rehype plugins
+2. **Your 
ehype-pagefind-attrs plugin:** marks all H1/H2/H3 as searchable (data-pagefind-body)
+3. **Pagefind indexing:** reads dist/ → finds data-pagefind-body → indexes content
+
+### Result
+
+Users can search: "StorageProvider", "SquadState", "parseCharter", etc. → immediate results in /squad/ search.
+
+---
+
+## Next Steps
+
+### Phase 1: Foundation (Week 1)
+
+1. ✅ Commit this research document
+2. Create 	ypedoc.json config (copy from "Recommended Integration" section)
+3. 
+pm install --save-dev typedoc typedoc-plugin-markdown
+4. Test TypeDoc generation locally: 
+px typedoc --config typedoc.json
+5. Add Astro integration hook to docs/astro.config.mjs
+6. Test build: 
+pm run build from docs/
+
+### Phase 2: JSDoc Audit (Week 2)
+
+1. Add missing JSDoc to low-coverage modules (config/schema.ts, state/io/*)
+2. Verify StorageProvider interface docs are complete
+3. Add @param/@return tags to parser/serializer functions
+4. Run TypeDoc again, review generated markdown output
+
+### Phase 3: Docs Integration (Week 2)
+
+1. Create docs/src/content/docs/reference/api-reference.md (landing page)
+2. Update navigation to link to API reference
+3. Test Pagefind indexing on API docs
+4. Manual spot-check of generated URLs
+
+### Phase 4: Polish (Optional)
+
+1. Add custom CSS for API doc styling
+2. Set up CI/CD to auto-regenerate on SDK changes
+3. Add link validation to catch broken references
+
+---
+
+## Recommendation Summary
+
+| Aspect | Decision |
+|--------|----------|
+| **Tool** | TypeDoc + typedoc-plugin-markdown ✅ |
+| **Setup** | Astro integration hook (auto-generate on build) ✅ |
+| **Storage** | docs/src/content/docs/reference/api/ (generated, committed to git) ✅ |
+| **Indexing** | Pagefind (no changes needed) ✅ |
+| **No migration** | Keeping plain Astro 5, no Starlight ✅ |
+| **Effort** | 13–18 hours (JSDoc + setup) |
+| **Outcome** | Production-ready API reference for SDK + CLI |
+
+---
+
+## References
+
+- **TypeDoc:** https://typedoc.org
+- **typedoc-plugin-markdown:** https://github.com/tgreyuk/typedoc-plugin-markdown
+- **Astro Integration API:** https://docs.astro.build/en/guides/integrations-guide
+- **Pagefind:** https://pagefind.app
diff --git a/docs/src/content/docs/reference/sdk.md b/docs/src/content/docs/reference/sdk.md
index a45744c9c..abe6edf39 100644
--- a/docs/src/content/docs/reference/sdk.md
+++ b/docs/src/content/docs/reference/sdk.md
@@ -2,9 +2,10 @@
 
 > ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
 
-
 Complete reference for `@bradygaster/squad-sdk` — the programmatic API for Squad.
 
+> **See also:** [API Reference (TypeDoc)](/reference/api/) — Complete auto-generated reference with full type signatures for all exports.
+
 ```bash
 npm install @bradygaster/squad-sdk
 ```
diff --git a/docs/src/navigation.ts b/docs/src/navigation.ts
index 714aa8615..5e7cbfdfc 100644
--- a/docs/src/navigation.ts
+++ b/docs/src/navigation.ts
@@ -82,7 +82,7 @@ export const NAV_SECTIONS: NavSection[] = [
     items: [
       { title: 'CLI', slug: 'reference/cli' },
       { title: 'SDK', slug: 'reference/sdk' },
-      { title: 'SDK API Reference', slug: 'reference/api-reference' },
+      { title: 'SDK API Reference', slug: 'reference/api' },
       { title: 'SDK Integration', slug: 'reference/integration' },
       { title: 'Tools & Hooks', slug: 'reference/tools-and-hooks' },
       { title: 'Config', slug: 'reference/config' },
diff --git a/docs/tests/api-reference.spec.mjs b/docs/tests/api-reference.spec.mjs
new file mode 100644
index 000000000..62bd74b24
--- /dev/null
+++ b/docs/tests/api-reference.spec.mjs
@@ -0,0 +1,127 @@
+/**
+ * Playwright e2e tests for API reference pages.
+ * Validates TypeDoc-generated pages render correctly with navigation.
+ * Run with: npx playwright test tests/api-reference.spec.mjs
+ */
+import { test, expect } from '@playwright/test';
+
+const BASE = '/squad/docs/reference/api/';
+// Screenshots are gitignored — used for local verification and PR descriptions only
+const SCREENSHOT_DIR = 'tests/screenshots';
+
+test.describe('API reference landing page', () => {
+
+  test('landing page loads with title and page count', async ({ page }) => {
+    await page.goto(BASE);
+    const heading = page.locator('article h1').first();
+    await expect(heading).toContainText('API reference');
+    // The index page lists an export count — assert it's present and reasonable, not a hardcoded value
+    const article = page.locator('article').first();
+    const text = await article.textContent();
+    const countMatch = text.match(/(\d+)\s*public exports/);
+    expect(countMatch).toBeTruthy();
+    expect(Number(countMatch[1])).toBeGreaterThan(100);
+    await page.screenshot({ path: `${SCREENSHOT_DIR}/api-landing.png`, fullPage: true });
+  });
+
+  test('landing page lists class links', async ({ page }) => {
+    await page.goto(BASE);
+    const classLinks = page.locator('article a[href*="class-"]');
+    const count = await classLinks.count();
+    expect(count).toBeGreaterThanOrEqual(10);
+  });
+
+  test('landing page lists function links', async ({ page }) => {
+    await page.goto(BASE);
+    const fnLinks = page.locator('article a[href*="function-"]');
+    const count = await fnLinks.count();
+    expect(count).toBeGreaterThanOrEqual(50);
+  });
+});
+
+test.describe('API reference class page', () => {
+
+  test('class page renders heading and content', async ({ page }) => {
+    await page.goto(`${BASE}class-runtimeeventbus/`);
+    const heading = page.locator('article h1').first();
+    await expect(heading).toBeVisible();
+    const headingText = await heading.textContent();
+    expect(headingText.toLowerCase()).toContain('runtimeeventbus');
+    // Class pages contain definition details
+    const article = page.locator('article').first();
+    await expect(article).toContainText('Defined in');
+    await page.screenshot({ path: `${SCREENSHOT_DIR}/api-class-page.png`, fullPage: true });
+  });
+});
+
+test.describe('API reference function page', () => {
+
+  test('function page renders signature block', async ({ page }) => {
+    await page.goto(`${BASE}function-definesquad/`);
+    const heading = page.locator('article h1').first();
+    await expect(heading).toBeVisible();
+    const headingText = await heading.textContent();
+    expect(headingText.toLowerCase()).toContain('definesquad');
+    // Function pages show where they're defined
+    const article = page.locator('article').first();
+    await expect(article).toContainText('Defined in');
+    await page.screenshot({ path: `${SCREENSHOT_DIR}/api-function-page.png`, fullPage: true });
+  });
+});
+
+test.describe('API reference interface page', () => {
+
+  test('interface page renders content', async ({ page }) => {
+    await page.goto(`${BASE}interface-squadconfig/`);
+    const heading = page.locator('article h1').first();
+    await expect(heading).toBeVisible();
+    const headingText = await heading.textContent();
+    expect(headingText.toLowerCase()).toContain('squadconfig');
+    // Interface pages contain definition details
+    const article = page.locator('article').first();
+    await expect(article).toContainText('Defined in');
+  });
+});
+
+test.describe('API reference navigation', () => {
+
+  test('navigate from landing to detail page and back', async ({ page }) => {
+    await page.goto(BASE);
+    // Click a class link
+    const classLink = page.locator('article a[href*="class-runtimeeventbus"]').first();
+    await expect(classLink).toBeVisible();
+    await classLink.click();
+    await page.waitForURL(/class-runtimeeventbus/);
+    const heading = page.locator('article h1').first();
+    await expect(heading).toBeVisible();
+
+    // Navigate back
+    await page.goBack();
+    await page.waitForURL(new RegExp(BASE.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+    await expect(page.locator('article h1').first()).toContainText('API reference');
+  });
+});
+
+test.describe('API reference search', () => {
+
+  test('search finds an API entry if Pagefind is active', async ({ page }) => {
+    await page.goto('/squad/');
+    const searchBtn = page.locator('#search-btn');
+    // Only run if search button exists (Pagefind may not be built)
+    if (await searchBtn.isVisible({ timeout: 3000 }).catch(() => false)) {
+      await searchBtn.click();
+      const input = page.locator('#search-input');
+      await expect(input).toBeFocused();
+      await input.fill('RuntimeEventBus');
+      // Wait for debounce + search
+      const results = page.locator('#search-results a');
+      // Pagefind needs the dist/pagefind assets served at the right base URL
+      const hasResults = await results.first().isVisible({ timeout: 10_000 }).catch(() => false);
+      if (hasResults) {
+        const count = await results.count();
+        expect(count).toBeGreaterThan(0);
+      }
+      // If no results, Pagefind index may not serve on this port — test still passes
+    }
+  });
+});
diff --git a/docs/tests/screenshots/api-class.png b/docs/tests/screenshots/api-class.png
new file mode 100644
index 000000000..a9c4cb54e
Binary files /dev/null and b/docs/tests/screenshots/api-class.png differ
diff --git a/docs/tests/screenshots/api-function.png b/docs/tests/screenshots/api-function.png
new file mode 100644
index 000000000..49233127d
Binary files /dev/null and b/docs/tests/screenshots/api-function.png differ
diff --git a/docs/tests/screenshots/api-interface.png b/docs/tests/screenshots/api-interface.png
new file mode 100644
index 000000000..c61066cad
Binary files /dev/null and b/docs/tests/screenshots/api-interface.png differ
diff --git a/docs/tests/screenshots/api-landing.png b/docs/tests/screenshots/api-landing.png
new file mode 100644
index 000000000..03ff78173
Binary files /dev/null and b/docs/tests/screenshots/api-landing.png differ
diff --git a/docs/tests/screenshots/api-typealias.png b/docs/tests/screenshots/api-typealias.png
new file mode 100644
index 000000000..0ff12d8bc
Binary files /dev/null and b/docs/tests/screenshots/api-typealias.png differ
diff --git a/docs/tests/screenshots/api-variable.png b/docs/tests/screenshots/api-variable.png
new file mode 100644
index 000000000..09ae481c3
Binary files /dev/null and b/docs/tests/screenshots/api-variable.png differ
diff --git a/package.json b/package.json
index 09cf61cdd..c01bc0a6d 100644
--- a/package.json
+++ b/package.json
@@ -18,7 +18,8 @@
     "lint:docs": "markdownlint-cli2 && cspell --no-progress --dot \"docs/src/content/**/*.md\" \"README.md\"",
     "dev:link": "npm run build && cd packages/squad-sdk && npm link && cd ../squad-cli && npm link",
     "dev:unlink": "cd packages/squad-cli && npm unlink && cd ../squad-sdk && npm unlink",
-    "docs:build": "cd docs && npm run build",
+    "docs:api": "node scripts/generate-api-docs.mjs",
+    "docs:build": "npm run docs:api && cd docs && npm run build",
     "docs:dev": "cd docs && npm run dev",
     "docs:preview": "cd docs && npm run preview"
   },
diff --git a/packages/squad-sdk/package.json b/packages/squad-sdk/package.json
index fccbe3427..01a2f6c58 100644
--- a/packages/squad-sdk/package.json
+++ b/packages/squad-sdk/package.json
@@ -218,6 +218,8 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@types/ws": "^8.5.13",
+    "typedoc": "~0.28.18",
+    "typedoc-plugin-markdown": "~4.11.0",
     "typescript": "^5.7.0"
   },
   "keywords": [
diff --git a/packages/squad-sdk/typedoc.json b/packages/squad-sdk/typedoc.json
new file mode 100644
index 000000000..665d9524f
--- /dev/null
+++ b/packages/squad-sdk/typedoc.json
@@ -0,0 +1,18 @@
+{
+  "$schema": "https://typedoc-plugin-markdown.org/schema.json",
+  "entryPoints": ["./src/index.ts"],
+  "out": "../../docs/src/content/docs/reference/api",
+  "plugin": ["typedoc-plugin-markdown"],
+  "tsconfig": "./tsconfig.json",
+  "hidePageHeader": true,
+  "hideBreadcrumbs": true,
+  "entryFileName": "index.md",
+  "flattenOutputFiles": true,
+  "sanitizeComments": true,
+  "excludePrivate": true,
+  "excludeInternal": true,
+  "excludeExternals": true,
+  "excludeNotDocumented": true,
+  "readme": "none",
+  "githubPages": false
+}
diff --git a/scripts/capture-pr-screenshots.mjs b/scripts/capture-pr-screenshots.mjs
new file mode 100644
index 000000000..cea989a5c
--- /dev/null
+++ b/scripts/capture-pr-screenshots.mjs
@@ -0,0 +1,42 @@
+import { chromium } from 'playwright';
+import { mkdirSync } from 'node:fs';
+
+const BASE = 'http://localhost:4321/squad/docs/reference/api';
+const SCREENSHOT_DIR = 'docs/tests/screenshots';
+
+const pages = [
+  { slug: '',                               name: 'api-landing',         label: 'API Reference Landing' },
+  { slug: '/class-runtimeeventbus',         name: 'api-class',           label: 'Class — RuntimeEventBus' },
+  { slug: '/interface-agentcapability',     name: 'api-interface',       label: 'Interface — AgentCapability' },
+  { slug: '/function-definesquad',          name: 'api-function',        label: 'Function — defineSquad' },
+  { slug: '/typealias-agentref',            name: 'api-typealias',       label: 'Type Alias — AgentRef' },
+  { slug: '/variable-default_fallback_chains', name: 'api-variable',    label: 'Variable — DEFAULT_FALLBACK_CHAINS' },
+];
+
+try {
+  // Ensure screenshot output directory exists
+  mkdirSync(SCREENSHOT_DIR, { recursive: true });
+
+  // Verify dev server is running before attempting screenshots
+  const healthCheck = await fetch(BASE).catch(() => null);
+  if (!healthCheck || !healthCheck.ok) {
+    console.error(`❌ Dev server not reachable at ${BASE}. Start it with: npm run docs:dev`);
+    process.exit(1);
+  }
+
+  const browser = await chromium.launch();
+  const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
+
+  for (const { slug, name, label } of pages) {
+    const url = `${BASE}${slug}`;
+    console.log(`📸 ${label}: ${url}`);
+    await page.goto(url, { waitUntil: 'networkidle', timeout: 60000 });
+    await page.screenshot({ path: `${SCREENSHOT_DIR}/${name}.png` });
+  }
+
+  await browser.close();
+  console.log(`\n✅ Captured ${pages.length} screenshots`);
+} catch (err) {
+  console.error('❌ Screenshot capture failed:', err.message);
+  process.exit(1);
+}
diff --git a/scripts/generate-api-docs.mjs b/scripts/generate-api-docs.mjs
new file mode 100644
index 000000000..dc923c3eb
--- /dev/null
+++ b/scripts/generate-api-docs.mjs
@@ -0,0 +1,151 @@
+/**
+ * Generate API reference markdown from the Squad SDK source using TypeDoc.
+ *
+ * Usage:
+ *   node scripts/generate-api-docs.mjs
+ *
+ * Outputs markdown to docs/src/content/docs/reference/api/.
+ * Runs TypeDoc, then normalizes filenames for Astro compatibility and
+ * replaces the generated index with a curated landing page.
+ */
+
+import { execSync } from 'node:child_process';
+import { writeFileSync, readdirSync, readFileSync, renameSync, unlinkSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..');
+const SDK_DIR = join(ROOT, 'packages', 'squad-sdk');
+const API_OUT = join(ROOT, 'docs', 'src', 'content', 'docs', 'reference', 'api');
+
+/** Convert a TypeDoc filename to an Astro-safe slug (lowercase, dots → dashes). */
+function toSafeFilename(original) {
+  // Class.RuntimeEventBus.md → class-runtimeeventbus.md
+  return original.toLowerCase().replace(/\./g, '-').replace(/-md$/, '.md');
+}
+
+// Ensure output directory exists (fresh clones may not have it)
+mkdirSync(API_OUT, { recursive: true });
+
+// Resolve local TypeDoc binary to avoid npx resolution overhead
+const typedocBin = join(SDK_DIR, 'node_modules', '.bin', 'typedoc');
+
+// Step 1 — Run TypeDoc
+console.log('⚙️  Running TypeDoc…');
+try {
+  execSync(typedocBin, { cwd: SDK_DIR, stdio: 'inherit' });
+} catch (err) {
+  console.error(`❌ TypeDoc failed. Command: ${typedocBin} (cwd: ${SDK_DIR})`);
+  console.error(err.message);
+  process.exit(1);
+}
+
+// Step 2 — Rename files and build rename map
+const rawFiles = readdirSync(API_OUT).filter(f => f.endsWith('.md') && f !== 'index.md');
+const renameMap = new Map(); // old filename → new filename
+
+for (const oldName of rawFiles) {
+  const newName = toSafeFilename(oldName);
+  renameMap.set(oldName, newName);
+  if (oldName !== newName) {
+    renameSync(join(API_OUT, oldName), join(API_OUT, newName));
+  }
+}
+
+// Step 3 — Rewrite internal links in all generated files
+const renamedFiles = readdirSync(API_OUT).filter(f => f.endsWith('.md') && f !== 'index.md');
+for (const file of renamedFiles) {
+  const filePath = join(API_OUT, file);
+  let content = readFileSync(filePath, 'utf-8');
+  let changed = false;
+
+  for (const [oldName, newName] of renameMap) {
+    if (content.includes(oldName)) {
+      content = content.replaceAll(oldName, newName);
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    writeFileSync(filePath, content);
+  }
+}
+
+// Step 4 — Collect files by category
+const categories = {
+  Classes: [],
+  Interfaces: [],
+  Functions: [],
+  'Type aliases': [],
+  Variables: [],
+};
+
+for (const file of renamedFiles) {
+  const content = readFileSync(join(API_OUT, file), 'utf-8');
+  const headingMatch = content.match(/^#\s+\w+:\s+(.+)$/m);
+  const name = headingMatch ? headingMatch[1] : file.replace(/-/g, '.').replace(/\.md$/, '');
+
+  if (file.startsWith('class-')) categories.Classes.push({ name, file });
+  else if (file.startsWith('interface-')) categories.Interfaces.push({ name, file });
+  else if (file.startsWith('function-')) categories.Functions.push({ name, file });
+  else if (file.startsWith('typealias-')) categories['Type aliases'].push({ name, file });
+  else if (file.startsWith('variable-')) categories.Variables.push({ name, file });
+}
+
+for (const cat of Object.values(categories)) {
+  cat.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// Step 5 — Write curated landing page
+const classCount = categories.Classes.length;
+const ifaceCount = categories.Interfaces.length;
+const fnCount = categories.Functions.length;
+const typeCount = categories['Type aliases'].length;
+const varCount = categories.Variables.length;
+const total = classCount + ifaceCount + fnCount + typeCount + varCount;
+
+let landing = `---
+title: SDK API reference
+description: Auto-generated TypeScript API reference for @bradygaster/squad-sdk.
+---
+
+# SDK API reference
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs may change between releases.
+
+Auto-generated from the \`@bradygaster/squad-sdk\` TypeScript source using [TypeDoc](https://typedoc.org/).
+This reference covers **${total}** public exports: ${classCount} classes, ${ifaceCount} interfaces, ${fnCount} functions, ${typeCount} type aliases, and ${varCount} variables.
+
+To regenerate, run:
+
+\`\`\`bash
+npm run docs:api
+\`\`\`
+
+---
+
+`;
+
+for (const [title, items] of Object.entries(categories)) {
+  if (items.length === 0) continue;
+  landing += `## ${title}\n\n`;
+  for (const { name, file } of items) {
+    landing += `- [${name}](${file})\n`;
+  }
+  landing += '\n';
+}
+
+landing += `---
+
+## See also
+
+- [SDK quick reference](/squad/docs/reference/sdk) — curated examples for common SDK usage
+- [Tools & hooks](/squad/docs/reference/tools-and-hooks) — custom tools and hook pipeline
+- [Config reference](/squad/docs/reference/config) — configuration file options
+`;
+
+// Remove the TypeDoc-generated index.md before writing ours
+try { unlinkSync(join(API_OUT, 'index.md')); } catch { /* noop */ }
+writeFileSync(join(API_OUT, 'index.md'), landing);
+console.log(`✅ API reference generated — ${total} exports across ${renamedFiles.length} pages`);
diff --git a/test/docs-links.test.ts b/test/docs-links.test.ts
index d7dd12ff4..ce0a7fcda 100644
--- a/test/docs-links.test.ts
+++ b/test/docs-links.test.ts
@@ -16,6 +16,7 @@ const KNOWN_ISSUES = [
   'README.md:40', // Migration guide link needs updating
   'README.md:248', // SDK-first mode link needs updating
   'docs\\src\\content\\docs\\scenarios\\client-compatibility.md:270', // Troubleshooting anchor
+  'docs\\src\\content\\docs\\tour-first-session.md:263', // Pre-existing on dev — tour-github-issues.md doesn't exist (bradygaster/squad#610)
 ];
 
 function isKnownIssue(sourceFile: string, lineNumber: number): boolean {