docs(chat): technical review spec, plan + findings report

docs/superpowers/plans/2026-06-06-chat-docs-technical-review.md

@@ -0,0 +1,240 @@
+# Chat Docs Technical Review Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Audit the 33 chat documentation pages against library source, produce one severity-ranked findings report, then ship the accuracy fixes as 3 batched PRs — every snippet, import/package, component selector, `@Input`/`@Output`, signature, behavioral claim, and link matching the implementation.
+
+**Architecture:** Two gated phases. Phase 1 fans out six read-only section auditors (component pages split 7+7) plus a completeness sweep; the controller re-verifies borderline findings and consolidates one report. Phase 2 fixes the report's findings as 3 batched PRs (components / guides+concepts / api+getting-started), each finding re-verified against its cited source line. The 4 `chat/a2ui/*` pages (reviewed in #590) and generated `changelog.mdx` are excluded.
+
+**Tech Stack:** MDX docs (Next.js App Router), Angular library `libs/chat` (+ cross-lib `libs/render`, `libs/langgraph`, `libs/ag-ui`, `libs/a2ui`), `docs-config.ts` for link/nav resolution, `git diff` + source citation as the accuracy gate, dev-server/curl for render checks.
+
+**Reference spec:** `docs/superpowers/specs/2026-06-06-chat-docs-technical-review-design.md`
+
+---
+
+## Ground-truth source map (used by every audit task)
+
+| Audit | Pages (relative to `apps/website/content/docs/chat/`) | Ground-truth source |
+|---|---|---|
+| getting-started | `getting-started/{introduction,quickstart,installation}.mdx` (skip changelog) | `libs/chat/src/public-api.ts`, `lib/agent/*` (Agent contract), `provideChat` |
+| guides | `guides/{layout-modes,theming,markdown,generative-ui,custom-catalogs,streaming,configuration,writing-an-adapter,lifecycle}.mdx` | `libs/chat/src` + cross-lib: `libs/render` (generative-ui), `libs/langgraph` & `libs/ag-ui` (writing-an-adapter), `libs/a2ui` (streaming) |
+| concepts | `concepts/{primitives-vs-compositions,message-model}.mdx` | `libs/chat/src/lib/primitives/*`, `lib/compositions/*`, message types |
+| components A | `components/{chat,chat-popup,chat-sidebar,chat-message-list,chat-trace,chat-input,chat-reasoning}.mdx` | each component class under `libs/chat/src/lib/primitives/*` or `lib/compositions/*` |
+| components B | `components/{chat-interrupt-panel,chat-tool-calls,chat-tool-call-template,chat-tool-call-card,chat-subagent-card,chat-debug,chat-select}.mdx` | same |
+| api | `api/{provide-chat,chat-config,mock-agent,content-classifier,parse-tree-store}.mdx` | `libs/chat/src/public-api.ts` + each named module + `apps/website/content/docs/chat/api/api-docs.json` |
+
+`libs/chat/src/public-api.ts` is authoritative (136 exports). Component classes live under `libs/chat/src/lib/primitives/<name>/<name>.component.ts` or `libs/chat/src/lib/compositions/<name>/<name>.component.ts`.
+
+## Findings severity taxonomy + row schema (used by report + fix gating)
+
+- **P0 — wrong:** breaks copy-paste (wrong import/package, nonexistent API, wrong selector/signature/type).
+- **P1 — misleading:** runs but teaches a wrong model.
+- **P2 — gap:** undocumented export, missing input/output/option, thin coverage.
+- **P3 — polish:** stale wording, inconsistent naming, dead link.
+
+Finding row (every finding MUST use this):
+`page:line · dimension · severity · what's-wrong · source-evidence(libs/…:line) · proposed-fix`
+Dimensions: `accuracy` | `conceptual` | `links` | `completeness`.
+
+---
+
+# PHASE 1 — AUDIT (read-only, parallel)
+
+> Phase 1 produces NO docs edits. The controller dispatches Tasks 1–6 concurrently (disjoint reads), runs Task 7, re-verifies borderline findings, then writes the report in Task 8.
+
+## Tasks 1–6: Section audit subagents
+
+Each task dispatches ONE read-only audit subagent. The prompt template is identical except for **section name**, **page list**, and **ground-truth source** (from the map above). Use `subagent_type: Explore`.
+
+**Shared subagent prompt template:**
+
+```
+You are a READ-ONLY technical-docs auditor. DO NOT edit, write, or commit any file. You only read and return findings.
+
+Repo root: /Users/blove/repos/angular-agent-framework. Branch: claude/chat-docs-technical-review.
+
+## Your section: <SECTION>
+## Pages to audit (read each in full):
+<ABSOLUTE PAGE PATHS>
+## Ground-truth source (read what you need to verify claims):
+<SOURCE PATHS>
+
+## Method
+For every code fence, inline `code`, prose claim, and internal link in your pages, verify it against the ground-truth source. Open the source files and confirm: import paths/packages, exported symbol names, component selectors, @Input/@Output (Angular signal input()/output()) names and types, function/class signatures, generic params, option/property keys, types, and documented behavior. For COMPONENT pages specifically: confirm the component's selector string and every documented input/output name + type against the component class (signal inputs declared as `readonly x = input<T>()` / `input.required<T>()`, outputs as `output<T>()`). For internal links (href="/docs/..."), confirm the target exists in apps/website/src/lib/docs-config.ts (it builds hrefs from product/section/slug — check the entry exists; do not grep literal href strings).
+
+## The four dimensions
+1. accuracy — import/package, symbol, selector, signature, option key, type matches source EXACTLY. Wrong package or nonexistent symbol = P0.
+2. conceptual — behavior claims match implementation; runs-but-wrong-model = P1.
+3. links — internal links resolve via docs-config.ts; examples internally coherent (imports cover symbols used; required providers present) and runnable.
+4. completeness — flag any obviously missing input/output/option/behavior a reader needs.
+
+## Severity
+P0 wrong (breaks copy-paste) | P1 misleading | P2 gap | P3 polish.
+
+## Return format — a markdown table, columns EXACTLY:
+| page:line | dimension | severity | what's wrong | source evidence | proposed fix |
+- page:line = relative path + line, e.g. chat/components/chat-input.mdx:42
+- source evidence = libs/…:line you verified against
+- proposed fix = the concrete corrected text/snippet (specific enough to apply)
+If a page is clean: | <page> | — | clean | no issues found | <source checked> | none |
+Every finding MUST cite a real source line. If a documented symbol can't be found in source, that's a P0 ("documented symbol not found in source"). End with a short "Systemic notes" paragraph for any cross-page pattern.
+
+Your entire final message IS the audit result (table + systemic notes). Return only that.
+```
+
+- [ ] **Task 1 — getting-started.** Pages: `getting-started/{introduction,quickstart,installation}.mdx` (absolute paths under `apps/website/content/docs/chat/`). Source: `libs/chat/src/public-api.ts`, `libs/chat/src/lib/agent/*`, `provideChat`. Dispatch; save the returned table verbatim for Task 8.
+
+- [ ] **Task 2 — guides.** Pages: the 9 guide files. Source: `libs/chat/src` + cross-lib (`libs/render` for generative-ui; `libs/langgraph`, `libs/ag-ui` for writing-an-adapter + Agent contract; `libs/a2ui` for streaming). For cross-lib refs, verify the symbol/package against the OWNING lib (but do not audit those libs' own docs). Dispatch; save table.
+
+- [ ] **Task 3 — concepts.** Pages: `concepts/{primitives-vs-compositions,message-model}.mdx`. Source: `libs/chat/src/lib/primitives/*`, `lib/compositions/*`, message types. Dispatch; save table.
+
+- [ ] **Task 4 — components A (7).** Pages: `components/{chat,chat-popup,chat-sidebar,chat-message-list,chat-trace,chat-input,chat-reasoning}.mdx`. Source: each page's component class (locate under `libs/chat/src/lib/primitives/*` or `lib/compositions/*`). Emphasize selector + input/output exactness. Dispatch; save table.
+
+- [ ] **Task 5 — components B (7).** Pages: `components/{chat-interrupt-panel,chat-tool-calls,chat-tool-call-template,chat-tool-call-card,chat-subagent-card,chat-debug,chat-select}.mdx`. Source: each page's component class / directive. Note: `chat-tool-call-template` documents `ChatToolCallTemplateDirective`; `chat-tool-calls` documents `ChatToolCallsComponent`. Dispatch; save table.
+
+- [ ] **Task 6 — api (5).** Pages: `api/{provide-chat,chat-config,mock-agent,content-classifier,parse-tree-store}.mdx`. Source: `libs/chat/src/public-api.ts` + each named module + `apps/website/content/docs/chat/api/api-docs.json`. Verify each documented signature/option against BOTH source and api-docs.json; flag drift (note which is right per `libs/chat/src`). Dispatch; save table.
+
+## Task 7: Completeness sweep (exports-vs-docs)
+
+**Files:** none (analysis). Run inline or as one subagent.
+
+- [ ] **Step 1: List chat public exports**
+
+```bash
+cd /Users/blove/repos/angular-agent-framework
+grep -E "^export" libs/chat/src/public-api.ts | wc -l
+grep -E "^export \{" libs/chat/src/public-api.ts | grep -oE "Component[A-Za-z]*|[A-Za-z]+Component|provide[A-Za-z]+|create[A-Za-z]+|mock[A-Za-z]+" | sort -u
+```
+
+- [ ] **Step 2: Cross-check documented components/APIs against exports**
+
+For every component the docs document (the 14 component pages) and every api page symbol, confirm the symbol is exported from `libs/chat/src/public-api.ts`. Any documented symbol NOT exported (and not a known internal) is a **P0** (documented-but-nonexistent). Conversely, list notable exported Components/`provide*`/`create*` symbols that have NO doc page — record as **P2** gaps (do not attempt to document every one of 136 exports; flag the material ones, e.g. an exported composition/component or public factory with zero coverage).
+
+```bash
+cd /Users/blove/repos/angular-agent-framework
+# documented component class names appear in the component pages; spot the exported set:
+grep -oE "Chat[A-Za-z]+Component|chatToolCallTemplate|ChatToolCallTemplateDirective" libs/chat/src/public-api.ts | sort -u
+```
+
+- [ ] **Step 3: Record findings** in the row schema for Task 8.
+
+## Task 8: Consolidate the findings report
+
+**Files:** Create `docs/superpowers/specs/2026-06-06-chat-docs-review-findings.md`
+
+- [ ] **Step 1: Re-verify borderline findings.** Before consolidating, the controller spot-checks a sample of cited source lines and re-verifies any finding that looks surprising or contradicts another (as in the render review, which caught two auditor false alarms). Drop or correct unverified findings.
+
+- [ ] **Step 2: Assemble the report**
+
+Structure:
+```markdown
+# Chat Docs Technical Review — Findings
+
+**Date:** 2026-06-06
+**Pages audited:** 33  **Source verified against:** libs/chat (+ render/langgraph/ag-ui/a2ui cross-refs)
+
+## Summary
+- P0: <n>  P1: <n>  P2: <n>  P3: <n>
+- Systemic issues: <bullets>
+
+## Findings by severity
+### P0 — wrong
+<merged rows from all sections, sorted by page>
+### P1 — misleading
+### P2 — gap
+### P3 — polish
+
+## Structural / won't-fix-here
+- <api-docs.json regeneration if a finding is doc↔generated drift — note the fix is `npm run generate-api-docs`, scoped separately if needed>
+- <any libs/* source bug noticed — flagged for separate follow-up, NOT fixed here>
+
+## Fix plan (3 PRs)
+- PR-1 components: <component findings>
+- PR-2 guides + concepts: <findings>
+- PR-3 api + getting-started: <findings>
+P-level cutoff: default P0+P1+P2, P3 where it's a one-line change. Structural + source-bug items listed, not actioned.
+```
+Merge the section tables verbatim into the severity buckets; keep every source citation.
+
+- [ ] **Step 3: Commit the report**
+
+```bash
+cd /Users/blove/repos/angular-agent-framework
+git add docs/superpowers/specs/2026-06-06-chat-docs-review-findings.md
+git commit -m "docs(chat): technical review findings report"
+```
+
+- [ ] **Step 4: CHECKPOINT — surface the report to the user.** Present summary counts + systemic issues + the 3-PR fix plan. Confirm the P-level cutoff and that structural/source items stay flagged-only, before starting Phase 2.
+
+---
+
+# PHASE 2 — FIX (subagent-driven, 3 batched PRs)
+
+> Each PR is its own branch off the latest `origin/main`. Within a PR, fix grouped by section; each group's edits gated by re-verification against the cited source line + an independent accuracy review before commit. Use the Task 8 report as the source of truth for what to change.
+
+**Shared fix-gate (run after each section's edits, before commit):**
+
+```bash
+cd /Users/blove/repos/angular-agent-framework
+# $FILES = edited .mdx paths for this section
+git --no-pager diff $FILES   # eyeball: each change matches a report finding's proposed fix; no unrelated heading/link/component churn
+```
+Then an independent accuracy-reviewer subagent confirms each edit matches its cited source line and no finding was missed/over-applied; loop until clean.
+
+## Task 9: PR-1 — components (14 pages)
+
+**Branch:** `claude/fix-chat-docs-components` off `origin/main`.
+**Files:** the component pages with findings (per report).
+
+- [ ] **Step 1:** Create the branch off latest `origin/main`.
+- [ ] **Step 2:** Dispatch implementer subagent(s) with the report's component findings (full rows, grouped — e.g. components A then B). Instruction: apply each proposed fix EXACTLY; re-read the cited component-class line (selector / `input()` / `output()`) before each edit; do NOT touch anything not in a finding.
+- [ ] **Step 3:** Shared fix-gate on edited files.
+- [ ] **Step 4:** Independent accuracy reviewer subagent; loop until clean.
+- [ ] **Step 5:** Render check — the edited component routes return 200 (serve website on :3000; curl each `/docs/chat/components/<slug>`).
+- [ ] **Step 6:** Commit (`docs(chat): fix component reference technical accuracy`), push, open PR, enable auto-merge (squash).
+
+## Task 10: PR-2 — guides + concepts (11 pages)
+
+**Branch:** `claude/fix-chat-docs-guides-concepts` off `origin/main` (create after PR-1 is up; rebase/update-branch if main moves).
+**Files:** the guide + concept pages with findings (per report).
+
+- [ ] **Step 1:** Create the branch off latest `origin/main`.
+- [ ] **Step 2:** Dispatch implementer with the guides+concepts findings; apply proposed fixes exactly; re-verify each against `libs/chat/src` (and the owning lib for cross-lib refs) cited lines.
+- [ ] **Step 3:** Shared fix-gate.
+- [ ] **Step 4:** Independent accuracy reviewer; loop until clean.
+- [ ] **Step 5:** Render check — edited guide/concept routes return 200.
+- [ ] **Step 6:** Commit (`docs(chat): fix guides + concepts technical accuracy`), push, open PR, enable auto-merge.
+
+## Task 11: PR-3 — api + getting-started (8 pages)
+
+**Branch:** `claude/fix-chat-docs-api-gs` off `origin/main`.
+**Files:** the api + getting-started pages with findings (per report).
+
+- [ ] **Step 1:** Create the branch off latest `origin/main`.
+- [ ] **Step 2:** Dispatch implementer with the api+getting-started findings; verify each signature/option against `libs/chat/src/public-api.ts` + named modules. If a finding is "doc drifted from generated api-docs.json", fix the doc prose to match source; if the generated JSON itself is stale, note whether `npm run generate-api-docs` is the fix (run ONLY if the report says the generator output is wrong, and scope the commit to the chat api-docs.json).
+- [ ] **Step 3:** Shared fix-gate.
+- [ ] **Step 4:** Independent accuracy reviewer; loop until clean.
+- [ ] **Step 5:** Render check — edited api/getting-started routes return 200.
+- [ ] **Step 6:** Commit (`docs(chat): fix api + getting-started technical accuracy`), push, open PR, enable auto-merge.
+
+## Task 12: Final verification + follow-ups
+
+**Files:** none (verification) + update the findings report.
+
+- [ ] **Step 1: All 33 reviewed chat routes return 200** (serve website on :3000; curl each reviewed page under getting-started/guides/concepts/components/api).
+- [ ] **Step 2:** Mark each fixed finding ✅ in `2026-06-06-chat-docs-review-findings.md`; leave structural/source items open. Commit on whichever fix branch is last, or a tiny follow-up branch.
+- [ ] **Step 3: Spawn follow-ups** for any real `libs/*` source bug or generator drift the report flagged (do not fix here).
+- [ ] **Step 4:** Confirm all 3 PRs merged (monitor; `gh pr update-branch` any that go BEHIND); sync local main; delete merged branches.
+
+---
+
+## Manual verification (before each merge)
+- [ ] Every fix traces to a report finding with a source citation; no edit lacks a finding.
+- [ ] The PR's chat routes render; internal links resolve; no documented chat API attributed to the wrong package.
+- [ ] Findings report committed; structural + source items listed, not actioned.
+
+## Self-Review (completed during planning)
+
+- **Spec coverage:** 33 pages across 5 reviewed sections audited (Tasks 1–6, components split 7+7) ✓; four dimensions in every audit prompt, with component selector/input/output emphasis ✓; completeness sweep (Task 7) ✓; controller re-verification of borderline findings (Task 8 Step 1) ✓; one severity-ranked report at the spec'd path (Task 8) ✓; triage checkpoint (Task 8 Step 4) ✓; 3 batched fix PRs grouped by section with source-cited reviews + render checks (Tasks 9–11) ✓; final verification + follow-ups (Task 12) ✓; exclusions (a2ui, changelog) honored; out-of-scope (other libs' docs, source changes, restructuring) honored.
+- **Placeholder scan:** No TBD/TODO. Phase 2 fix snippets are intentionally report-driven (the audit produces the exact corrected text — inherent to a review whose fixes aren't known until discovery); the gates (source re-verification, fix-gate diff, reviewer loop, render 200) make each edit checkable. Commands have expected output.
+- **Consistency:** the ground-truth map, severity taxonomy, and row schema are defined once and referenced by every task; the component pages list in Tasks 4+5 (7+7=14) matches the spec; the 3-PR grouping in Tasks 9–11 matches the report's fix-plan section and the spec's Phase 2; `claude/chat-docs-technical-review` is the audit/report branch, with separate fix branches per PR off `origin/main`.