docs: CI Mermaid-to-PNG rendering proposal

.squad/agents/booster/history.md

@@ -84,6 +84,15 @@ Analyzed 20 CI runs from March 15. Identified 3 distinct failure categories:
 4. Better failure grouping/attribution in CI UI (distinguish "new gate" vs "regression")
 5. Spell check dictionary maintenance workflow (easier to add known-good usernames/terms)
 
+### whatsnew.md Version Sync — March 22, 2026
+**What was built:** scripts/sync-whatsnew-version.mjs — strips -build.N suffix from package.json version, finds the ## v{X} — Current Release heading in docs/src/content/docs/whatsnew.md, and replaces it with the current clean semver. Idempotent; writes only when changed.
+
+**Test added:** 	est/whatsnew-version-sync.test.ts — Vitest test that asserts the Current Release heading in whatsnew.md matches the stripped package.json version. Fails CI when versions diverge.
+
+**Hook:** Appended 
+ode scripts/sync-whatsnew-version.mjs to the prebuild npm script (runs after bump-build.mjs, so it always sees the bumped version). Also set SKIP_BUILD_BUMP=1 guard pattern documented for CI validate runs.
+
+**Immediate fix:** Updated the stale ## v0.8.2 — Current Release heading to ## v0.8.25 — Current Release to match the actual package.json version at time of work.
 ### CI Workflow Audit — March 23, 2026
 
 **Status:** Conducted full audit of 15 workflow files. Brady's perception ("complete nightmare, 12,000 workflows") is not accurate — the codebase is lean, well-organized, and 99% authored by Brady (bradygaster + Copilot).

.squad/agents/pao/history.md

@@ -94,12 +94,45 @@ Evaluated four docs pages from PR #331 (Tamir's blog analysis) against Squad-spe
 ### Boundary Review Execution (v0.8.26)
 Executed boundary review findings from PR #331: (1) Deleted ralph-operations.md (infrastructure around Squad, not Squad itself — moved to IRL); (2) Deleted proactive-communication.md (external tools/webhooks — moved to IRL); (3) Reframed issue-templates.md intro to clarify "GitHub feature configured for Squad" not "Squad feature"; (4) Updated EXPECTED_SCENARIOS in docs-build.test.ts to match remaining files. Pattern reinforced: boundary review = remove external infrastructure docs, reframe platform integration docs to clarify whose feature it is, keep Squad behavior/config docs. Changes staged for commit.
 
-### Cross-Org Authentication Docs (v0.8.26)
+### Docs Catalog Audit (2026-03-22)
+Full audit of the Astro docs site identified critical quality and navigation gaps. **Findings:** 0 dead nav links (healthy); 15 orphaned pages not discoverable via sidebar (FAQ, guides, reference pages, 6 legacy root files); 3 stale/broken pages using deprecated install syntax; 5 duplicate content conflicts. **Top 5 Actions:** (1) Add CI test to enforce nav coverage — catch orphaned pages automatically; (2) Delete 6 root-level legacy files (guide.md, sample-prompts.md, tips-and-tricks.md, tour-*.md) — deprecated syntax and not in nav; (3) Make whatsnew.md a release checklist artifact — current report (v0.8.2) vs actual (v0.8.26+) erodes trust; (4) Update insider-program.md to current install method — replace deprecated `npx github:` syntax; (5) Resolve choose-your-interface vs choosing-your-path duplication — one canonical page rule. **Skill Created:** docs-catalog-audit (low confidence; audit framework needs iteration). **Decision:** Merged into decisions.md for team adoption.
+
+### Docs Fire Fixes (post-audit, 2026-03-22)
+Fixed four fires from the catalog audit: (1) Updated `insider-program.md` — replaced all deprecated `npx github:bradygaster/squad#insider` commands with `npm install -g @bradygaster/squad-cli@insider`, and all `.ai-team/` references with `.squad/`; (2) Added six orphaned pages to `navigation.ts` — `guide/faq`, `guide/build-autonomous-agent`, `features/built-in-roles`, `features/context-hygiene`, `features/issue-templates`, `reference/vscode-troubleshooting`; (3) Deleted five stale root-level files via `git rm` (`guide.md`, `sample-prompts.md`, `tips-and-tricks.md`, `tour-first-session.md`, `tour-github-issues.md`); (4) Added `vscode-troubleshooting` to EXPECTED_REFERENCE in docs-build.test.ts — all 23 tests pass. New nav entries use sentence-case and "and" over ampersands per team decision.
 Created docs/src/content/docs/scenarios/cross-org-auth.md covering GitHub personal + Enterprise Managed Users (EMU) multi-account auth. Three solutions documented: (1) gh auth switch for manual account toggling; (2) Copilot instructions (.github/copilot-instructions.md) for account mapping documentation; (3) Squad skill pattern for auth error detection and recovery. Covered git credential helpers (per-host and per-org), EMU hostname variations (github.com vs dedicated instances), and common error messages (HTTP 401, authentication required). Added cross-references in troubleshooting.md (new section), enterprise-platforms.md (authentication section), and navigation.ts. Updated test/docs-build.test.ts with 'cross-org-auth' in EXPECTED_SCENARIOS. Pattern: Microsoft Style Guide (sentence-case), "Try this" prompts at top, problem/solution structure, practical examples over abstractions, links to related pages at bottom.
 
 ### 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.
+
+### CI Mermaid Rendering Proposal (2026-03-25)
+
+Researched and proposed CI pipeline for pre-rendering Mermaid diagrams to PNG before docs build. Evaluated three approaches:
+- **Option A:** GitHub Actions pre-build step (CI-only; poor local DX)
+- **Option B:** npm `prebuild` script hook (local + CI; excellent DX)
+- **Option C:** Astro integration plugin (seamless but complex/maintenance burden)
+
+**Recommendation:** Option B (npm prebuild) + Option A (CI safety net). Tool: `@mermaid-js/mermaid-cli` (mmdc). Source files: `.mmd` in `docs/src/content/docs/*/diagrams/`, output PNGs in `*/images/` (git-ignored). Enables live diagram authoring locally, fresh renders in CI. Proposal doc: `docs/research/ci-mermaid-rendering-proposal.md`. Decision: `.squad/decisions/inbox/pao-ci-mermaid.md`.
+Researched and proposed CI pipeline for pre-rendering Mermaid diagrams to PNG before docs build. Evaluated three approaches: Option A (GitHub Actions pre-build, CI-only, poor local DX), Option B (npm prebuild script, local + CI, excellent DX), Option C (Astro integration plugin, seamless but complex/maintenance burden). **Recommendation:** Option B (npm prebuild) + Option A (CI safety net). Tool: `@mermaid-js/mermaid-cli` (mmdc). Source files: `.mmd` in `docs/src/content/docs/*/diagrams/`, output PNGs in `*/images/` (git-ignored, generated). Benefits: excellent local DX (live diagram authoring), reliable CI (always fresh PNGs), simple implementation (npm lifecycle hook). Proposal: `docs/research/ci-mermaid-rendering-proposal.md`. Decision: `.squad/decisions/inbox/pao-ci-mermaid.md`. Enables authors to iterate on diagrams in real-time, reduces client-side rendering load.
+
 ### Issue Triage (2026-03-22T06:44:01Z)
 
 **Flight triaged 6 unlabeled issues and filed 1 new issue.**
@@ -192,3 +225,46 @@ 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.
+### Architecture Diagrams PNG Conversion (2026-03-24)
+
+Converted all 7 Mermaid diagrams from the architecture page to optimized PNG images. **Process:** (1) extracted Mermaid source from squad/pao-arch-diagram branch; (2) ran `mmdc` (mermaid-cli v11.12.0) with `-b transparent -t neutral` flags to generate 7 PNG files (36–124 KB each); (3) created new `squad/pao-arch-docs` branch from dev; (4) updated `docs/src/content/docs/concepts/architecture.md` with PNG references and collapsed Mermaid source blocks; (5) added 2-3 paragraph intro explaining Squad's orchestration model at a glance.
+
+**Diagrams rendered:** User Interaction Flow (sequence), Component Architecture (layered graph), State Management (drop-box pattern), Parallel Execution Model (3-mode routing), Casting & Persistent Naming (knowledge compounds), Decision & Knowledge Flow (full cycle), Git Worktree Lifecycle (worktree-local strategy).
+
+**Key pattern:** PNG images render in docs for clarity and performance; collapsed `<details>` blocks preserve Mermaid source for readers who want to copy/adapt. Structure follows Microsoft Style Guide: sentence-case headings, active voice, second person ("you"), present tense, practical descriptions. Intro contextualizes: "Squad is a programmable multi-agent orchestration runtime" + isolation/persistence/portability principles + preview of layer-by-layer explanation.
+
+**Learning:** Mermaid-cli succeeds with direct call (`mmdc` binary) after global npm install; avoid `npx` wrapper on this machine. Transparent PNG background + neutral theme keeps diagrams legible in both light/dark doc modes. Backtick-escaping in Mermaid `subgraph` labels is brittle; use simpler node labels and rely on Mermaid's rendering. All PNG files committed; docs site Astro will serve from content directory via relative paths (`./images/architecture-*.png`).