bradygaster · Mar 26, 2026 · Mar 25, 2026
@@ -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

@@ -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.
@@ -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
@@ -22,6 +22,7 @@
     "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
+    "@playwright/test": "^1.58.2",
     "pagefind": "^1.4.0"
   }
 }