docs: architecture diagrams as PNG with collapsed Mermaid source

.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,34 @@ 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.
 ### Issue Triage (2026-03-22T06:44:01Z)
 
 **Flight triaged 6 unlabeled issues and filed 1 new issue.**

.squad/decisions.md

@@ -6526,6 +6526,77 @@ ESM module resolution uses dual-layer postinstall strategy:
 
 ---
 
+## Docs Catalog Audit Findings — PAO Decision
+
+**Author:** PAO (DevRel)  
+**Date:** 2026-03-22  
+
+Comprehensive audit of the Astro-based Squad docs site identified critical gaps in navigation coverage, stale content, and structural inconsistencies.
+
+### 1. Navigation gap is a CI failure condition
+
+Every content file under docs/src/content/docs/ that is not in 
+avigation.ts (or STANDALONE_PAGES) must be treated as a defect. Pattern of 15 orphaned pages (FAQ, built-in roles reference, context hygiene guide, VS Code troubleshooting, autonomous agent guide, GitHub auth setup) shows no automated check preventing nav gaps.
+
+**Action:** Add test assertion in 	est/docs-build.test.ts to verify every .md file in docs content tree appears in either NAV_SECTIONS or STANDALONE_PAGES.
+
+### 2. Root-level legacy files must be removed
+
+Six root-level files (	our-first-session.md, 	our-github-issues.md, 	our-gitlab-issues.md, guide.md, sample-prompts.md, 	ips-and-tricks.md) are stale legacy artifacts using deprecated install commands (
+px github:bradygaster/squad, .ai-team/), not in nav, creating confusion. Delete or archive — do not keep indefinitely.
+
+### 3. whatsnew.md must be updated on every release
+
+What's New page is the trust signal for active maintenance. Currently reports v0.8.2 when actual is v0.8.26+. This erodes user trust. **Update policy:** whatsnew.md is a required artifact in every release checklist.
+
+### 4. insider-program.md must use current distribution
+
+Insider Program page uses deprecated 
+px github:bradygaster/squad#insider syntax and references old .ai-team/ directory. Must be updated to use current npm insider channel or removed if insider program format changed.
+
+### 5. choose-your-interface.md supersedes choosing-your-path.md
+
+Orphaned get-started/choose-your-interface.md is significantly more complete than navved get-started/choosing-your-path.md. Options: (a) add choose-your-interface to nav and point from installation.md, or (b) merge into single canonical page. Do not keep both — enforce "one canonical page per concept" rule.
+
+### Observations (No Action Required)
+
+- **Zero dead nav links** — every nav reference has backing file (healthy signal)
+- **All actively-navved pages** follow Microsoft Style Guide, use correct install commands
+- **Blog section healthy** — 28 posts, consistent format
+- **Concepts section clean** — well-structured
+
+---
+
+## whatsnew.md "Current Release" Version Sync
+
+**By:** Booster (CI/CD Engineer)  
+**Status:** Implemented  
+**Date:** 2026-03-22
+
+### Problem
+
+`docs/src/content/docs/whatsnew.md` contains a `## v{X} — Current Release` heading that drifts from `package.json` version during build cycles. Manually updating it during releases is error-prone and easy to skip, eroding team trust in release docs.
+
+### Decision
+
+Implement automated version sync via prebuild script:
+
+1. **scripts/sync-whatsnew-version.mjs** — Reads `package.json` version, strips pre-release suffixes (e.g., `-build.N`), finds `## v{X} — Current Release` heading in whatsnew.md, replaces it if needed (idempotent, no-ops if already correct).
+2. **Prebuild hook** — Wire into `package.json` `"prebuild"` script to run after `bump-build.mjs`, so it always sees freshly bumped version.
+3. **Test gate** — Add Vitest test (`test/whatsnew-version-sync.test.ts`) that fails CI if heading and `package.json` are out of sync.
+
+### Rationale
+
+- Root cause: No automated gate. Version bumps fire via `bump-build.mjs` but `whatsnew.md` update was manual and skipped.
+- **Prebuild** (not build) ensures it runs on every local `npm run build` + CI, keeping the file always current.
+- Idempotent design allows safe use with `SKIP_BUILD_BUMP=1` (validate-only builds still sync).
+- Test is the safety net: even manual edits to wrong version are caught.
+
+### Alternatives Rejected
+
+- **Git hook (pre-commit):** Not portable across all contributors and Copilot agents.
+- **Test-only, no script:** Would fail CI but give no remediation path.
+- **Modify bump-build.mjs:** Out of scope per Booster charter (don't modify internal bump logic).
 # Economy Mode Design — #500
 
 **Date:** 2026-03-20