diff --git a/docs/superpowers/plans/2026-06-06-small-libs-docs-technical-review.md b/docs/superpowers/plans/2026-06-06-small-libs-docs-technical-review.md new file mode 100644 index 00000000..294de5d1 --- /dev/null +++ b/docs/superpowers/plans/2026-06-06-small-libs-docs-technical-review.md @@ -0,0 +1,234 @@ +# Small Libs Docs Technical Review (a2ui + licensing + telemetry) 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 16 docs pages of a2ui, licensing, and telemetry against library source, produce one severity-ranked findings report, then ship accuracy fixes as per-lib PRs — every snippet, import/package, API/signature, behavioral claim, and link matching the implementation, with the reference pages as the priority. + +**Architecture:** Two gated phases. Phase 1 fans out four read-only auditors (a2ui split core/reference; licensing; telemetry) plus a per-lib completeness sweep; the controller re-verifies borderline findings (and source freshness) and consolidates one report grouped by lib. Phase 2 fixes per lib (up to 3 PRs, skip clean libs), each branch cut from up-to-date `origin/main`, each finding re-verified against its cited source line. + +**Tech Stack:** MDX docs (Next.js App Router), Angular libraries `libs/a2ui`, `libs/licensing`, `libs/telemetry`, `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-small-libs-docs-technical-review-design.md` + +--- + +## Ground-truth source map (used by every audit task) + +| Audit | Pages (relative to `apps/website/content/docs/`) | Ground-truth source | +|---|---|---| +| a2ui-core | `a2ui/getting-started/{introduction,quickstart}.mdx`, `a2ui/guides/{message-protocol,data-model,adapters-and-validation}.mdx` | `libs/a2ui/src` — `lib/types.ts`, `lib/parser.ts`, resolver/guards, `src/index.ts` | +| a2ui-reference | `a2ui/reference/{schema,parser-resolver-guards}.mdx` | `libs/a2ui/src/lib/types.ts` (schema) + the parser/resolver/guard functions + signatures | +| licensing | `licensing/getting-started/introduction.mdx`, `licensing/guides/{setup,ci-and-offline}.mdx`, `licensing/reference/api.mdx` | `libs/licensing/src` — `evaluateLicense` + status/result types + exports (`src/index.ts`) | +| telemetry | `telemetry/getting-started/introduction.mdx`, `telemetry/guides/{browser,node,privacy-and-opt-out}.mdx`, `telemetry/reference/events.mdx` | `libs/telemetry/src` — `browser/*`, `node/*`, `shared/*`, the events catalog + exports | + +Each lib's authoritative export list is `libs//src/(public-api.ts|index.ts)`. + +## Findings severity taxonomy + row schema + +- **P0 — wrong:** breaks copy-paste (wrong import/package, nonexistent API, wrong signature/type). +- **P1 — misleading:** runs but teaches a wrong model. +- **P2 — gap:** undocumented export, missing option, thin coverage. +- **P3 — polish:** stale wording, inconsistent naming, dead link. + +Finding row: `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–4 concurrently (disjoint reads), runs Task 5, re-verifies borderline findings, then writes the report in Task 6. + +## Tasks 1–4: Section audit subagents + +Each task dispatches ONE read-only audit subagent (use `subagent_type: Explore`). Identical prompt except **section/lib name**, **page list**, **ground-truth source**. + +**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/small-libs-docs-technical-review. + +## Your section:
+## Pages to audit (read each in full): + +## Ground-truth source (read what you need to verify claims): + + +## 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, function/class signatures, option/property keys, types, and documented BEHAVIOR. For REFERENCE pages especially (a2ui schema + parser-resolver-guards, licensing api, telemetry events): every documented type/field/signature/event must match source EXACTLY, and material source items should appear. For internal links (href="/docs/..."), confirm the target exists in apps/website/src/lib/docs-config.ts (built from product/section/slug — check the entry exists; do not grep literal href strings). + +## The four dimensions +1. accuracy — import/package, symbol, 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 + runnable. +4. completeness — flag any obviously missing option/behavior/field/event 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. a2ui/reference/schema.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: | | — | clean | no issues found | | none | +Every finding MUST cite a real source line. If a documented symbol can't be found in source, that's a P0. 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 — a2ui-core.** Pages: `a2ui/getting-started/{introduction,quickstart}.mdx`, `a2ui/guides/{message-protocol,data-model,adapters-and-validation}.mdx`. Source: `libs/a2ui/src/lib/types.ts`, `lib/parser.ts`, resolver/guards, `src/index.ts`. Dispatch; save table for Task 6. + +- [ ] **Task 2 — a2ui-reference.** Pages: `a2ui/reference/{schema,parser-resolver-guards}.mdx`. Source: `libs/a2ui/src/lib/types.ts` (the schema/envelopes/components/dataModel) + the parser/resolver/guard functions + their exact signatures. PRIORITY: every schema type/field + function signature must match source. Dispatch; save table. + +- [ ] **Task 3 — licensing.** Pages: `licensing/getting-started/introduction.mdx`, `licensing/guides/{setup,ci-and-offline}.mdx`, `licensing/reference/api.mdx`. Source: `libs/licensing/src` (`evaluateLicense`, status/result types, `src/index.ts`). Verify the license-evaluation semantics (returns a status, does not throw for normal states) + the api reference signatures. Dispatch; save table. + +- [ ] **Task 4 — telemetry.** Pages: `telemetry/getting-started/introduction.mdx`, `telemetry/guides/{browser,node,privacy-and-opt-out}.mdx`, `telemetry/reference/events.mdx`. Source: `libs/telemetry/src/browser/*`, `node/*`, `shared/*` (sink, tokens incl. deprecated `posthogKey`/`posthogHost`, opt-out, the events catalog). Verify the events reference vs the actually-emitted events; confirm deprecations. Dispatch; save table. + +## Task 5: Per-lib completeness sweep + +**Files:** none (analysis). + +- [ ] **Step 1: Exports vs docs, per lib** + +```bash +cd /Users/blove/repos/angular-agent-framework +for lib in a2ui licensing telemetry; do + echo "===== $lib =====" + ENTRY=$(ls libs/$lib/src/public-api.ts libs/$lib/src/index.ts 2>/dev/null | head -1) + grep -oE "export (function|const|class|type|interface) [A-Za-z0-9_]+|export \{[^}]+\}" "$ENTRY" 2>/dev/null \ + | grep -oE "[A-Z][A-Za-z0-9_]+|[a-z][A-Za-z0-9_]+" | sort -u | while read -r sym; do + c=$(grep -rl "\b$sym\b" apps/website/content/docs/$lib 2>/dev/null | wc -l | tr -d ' ') + [ "$c" = "0" ] && echo " UNDOCUMENTED: $sym" + done + echo " (end $lib)" +done +``` +Record notable undocumented exports as **P2** gaps (skip trivial/internal re-exported types). + +- [ ] **Step 2: Reverse check.** From the Task 1–4 tables, confirm every API the docs claim each lib exports appears in that lib's `public-api.ts`/`index.ts`. Any that doesn't = **P0**. + +## Task 6: Consolidate the findings report + +**Files:** Create `docs/superpowers/specs/2026-06-06-small-libs-docs-review-findings.md` + +- [ ] **Step 1: Re-verify borderline findings** against source; confirm source freshness (`git fetch origin main`; ensure the audit branch's `libs/*` matches `origin/main` — the ag-ui review hit a stale-local-`main` reducer). Drop/correct unverified findings. + +- [ ] **Step 2: Assemble the report** + +```markdown +# Small Libs Docs Technical Review — Findings + +**Date:** 2026-06-06 +**Pages audited:** 16 (a2ui 7, licensing 4, telemetry 5) **Source:** libs/a2ui, libs/licensing, libs/telemetry + +## Summary +- P0: P1: P2: P3: (per lib: a2ui …, licensing …, telemetry …) +- Systemic issues: + +## Findings by lib +### a2ui +#### P0 / P1 / P2 / P3 +### licensing +#### P0 / P1 / P2 / P3 +### telemetry +#### P0 / P1 / P2 / P3 + +## Structural / won't-fix-here +- +- api-docs.json generator nuances (already tracked) + +## Fix plan (per-lib PRs) +- a2ui PR: (skip if clean) +- licensing PR: (skip if clean) +- telemetry PR: (skip if clean) +P-level cutoff: default P0+P1+P2, P3 where it's a one-line change. Structural + source items listed, not actioned. +``` +Merge the section tables verbatim into the per-lib 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-small-libs-docs-review-findings.md +git commit -m "docs(small-libs): technical review findings report" +``` + +- [ ] **Step 4: CHECKPOINT — surface the report to the user.** Present per-lib summary counts + systemic issues + the per-lib fix plan. Confirm the P-level cutoff and that structural/source items stay flagged-only, before Phase 2. + +--- + +# PHASE 2 — FIX (subagent-driven, per-lib PRs) + +> One PR per lib WITH findings (skip clean libs). Each branch cut from up-to-date `origin/main` (run `git fetch origin main` + verify the lib's source blob matches origin/main BEFORE cutting + before applying source-cited fixes — ag-ui lesson). Fix grouped by section; each group's edits gated by re-verification against the cited source line + an independent accuracy review before commit. Only supported `Callout` types (`tip`/`info`/`warning`/`danger`). + +**Shared fix-gate (after each lib's edits, before commit):** + +```bash +cd /Users/blove/repos/angular-agent-framework +# $FILES = edited .mdx paths for this lib +git --no-pager diff $FILES # eyeball: each change matches a report finding; no unrelated heading/link/component churn +grep -rn 'type="note"' $FILES && echo "BAD note callout" || echo "callout types OK" +``` +Then an independent accuracy-reviewer subagent confirms each edit matches its cited source line; loop until clean. + +## Task 7: a2ui fix PR (if findings) + +**Branch:** `claude/fix-a2ui-docs` off up-to-date `origin/main`. +**Files:** the a2ui pages with findings (per report). + +- [ ] **Step 1:** `git fetch origin main`; create the branch off `origin/main`; confirm `libs/a2ui` matches origin/main. +- [ ] **Step 2:** Dispatch implementer with the a2ui findings (full rows, grouped by section). Apply each proposed fix EXACTLY; re-read the cited source line before each edit; do NOT touch anything not in a finding. +- [ ] **Step 3:** Shared fix-gate. +- [ ] **Step 4:** Independent accuracy reviewer subagent; loop until clean. +- [ ] **Step 5:** Render check — edited a2ui routes return 200. +- [ ] **Step 6:** Commit (`docs(a2ui): fix technical accuracy issues`), push, open PR, enable auto-merge (squash). + +## Task 8: licensing fix PR (if findings) + +**Branch:** `claude/fix-licensing-docs` off up-to-date `origin/main`. +**Files:** the licensing pages with findings (per report). + +- [ ] **Step 1:** `git fetch origin main`; branch off `origin/main`; confirm `libs/licensing` matches. +- [ ] **Step 2:** Dispatch implementer with the licensing findings; apply exactly; re-verify each against `libs/licensing/src` cited lines (respect the browser-safe constraint — no Buffer/bare `process` in examples). +- [ ] **Step 3:** Shared fix-gate. +- [ ] **Step 4:** Independent accuracy reviewer; loop until clean. +- [ ] **Step 5:** Render check — edited licensing routes return 200. +- [ ] **Step 6:** Commit (`docs(licensing): fix technical accuracy issues`), push, open PR, enable auto-merge. + +## Task 9: telemetry fix PR (if findings) + +**Branch:** `claude/fix-telemetry-docs` off up-to-date `origin/main`. +**Files:** the telemetry pages with findings (per report). + +- [ ] **Step 1:** `git fetch origin main`; branch off `origin/main`; confirm `libs/telemetry` matches. +- [ ] **Step 2:** Dispatch implementer with the telemetry findings; apply exactly; re-verify each against `libs/telemetry/src` cited lines (sink/tokens/events/deprecations). +- [ ] **Step 3:** Shared fix-gate. +- [ ] **Step 4:** Independent accuracy reviewer; loop until clean. +- [ ] **Step 5:** Render check — edited telemetry routes return 200. +- [ ] **Step 6:** Commit (`docs(telemetry): fix technical accuracy issues`), push, open PR, enable auto-merge. + +## Task 10: Final verification + land planning artifacts + +**Files:** none (verification) + the findings report + spec/plan. + +- [ ] **Step 1: All 16 routes return 200** (serve website on :3000; curl each a2ui/licensing/telemetry page). +- [ ] **Step 2:** Mark each fixed finding ✅ in `2026-06-06-small-libs-docs-review-findings.md`; leave structural/source items open. +- [ ] **Step 3:** Land the planning artifacts (spec + plan + resolved findings report) to main via a small doc-only PR from `claude/small-libs-docs-technical-review` (rebased on up-to-date main), enable auto-merge. +- [ ] **Step 4: Spawn follow-ups** for any real `libs/*` source bug the report flagged. +- [ ] **Step 5:** Confirm all PRs merged (monitor; `gh pr update-branch` any that go BEHIND; serialize as they merge); 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 edited routes render; internal links resolve; no documented API attributed to the wrong package; only supported Callout types used. +- [ ] Findings report committed; structural + source items listed, not actioned. + +## Self-Review (completed during planning) + +- **Spec coverage:** 16 pages across 3 libs audited (Tasks 1–4, a2ui split core/reference) ✓; four dimensions in every audit prompt, with reference pages as priority ✓; per-lib completeness sweep + reverse check (Task 5) ✓; controller re-verification incl. source-freshness check (Task 6 Step 1) ✓; one severity-ranked report grouped by lib at the spec'd path (Task 6) ✓; triage checkpoint (Task 6 Step 4) ✓; per-lib fix PRs with up-to-date-source guard, source-cited review, render check, supported-Callout guard (Tasks 7–9) ✓; final verification + planning-artifact landing + follow-ups (Task 10) ✓; out-of-scope (chat/a2ui pages, other libs' docs, source changes, api-docs.json generator, restructuring) honored. +- **Placeholder scan:** No TBD/TODO. Phase 2 fix snippets are intentionally report-driven (the audit produces the exact corrected text); the gates (up-to-date source, source re-verification, fix-gate diff, reviewer loop, render 200, supported-Callout) 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 page lists in Tasks 1–4 match the spec (a2ui 5+2, licensing 4, telemetry 5 = 16); per-lib PRs in Tasks 7–9 match the report's fix-plan and the spec's Phase 2; `claude/small-libs-docs-technical-review` is the audit/report + planning-artifact branch, with separate per-lib fix branches off `origin/main`; the up-to-date-source guard (ag-ui lesson) appears in Phase 2 + Task 6 + Task 10. diff --git a/docs/superpowers/specs/2026-06-06-small-libs-docs-review-findings.md b/docs/superpowers/specs/2026-06-06-small-libs-docs-review-findings.md new file mode 100644 index 00000000..681915df --- /dev/null +++ b/docs/superpowers/specs/2026-06-06-small-libs-docs-review-findings.md @@ -0,0 +1,74 @@ +# Small Libs Docs Technical Review — Findings + +**Date:** 2026-06-06 +**Pages audited:** 16 (a2ui 7, licensing 4, telemetry 5) +**Source verified against:** `libs/a2ui`, `libs/licensing`, `libs/telemetry` +**Method:** 4 parallel read-only auditors + per-lib completeness sweep; controller re-verified every high-impact finding against source (dropped 1 auditor false alarm). + +## Resolution status — ✅ ALL FINDINGS FIXED (3 per-lib PRs) + +Cutoff: P0+P1+P2 + cheap P3. Each fix verified against current source. +- ✅ **PR #609 — licensing:** L1 (P0 `LicenseTier` values), L3 (P1 `runLicenseCheck` idempotency), L2 (P2 `EvaluateResult` documented), L4 (P3 env bracket-access). +- ✅ **PR #610 — a2ui:** A1 (P2 `A2uiTheme` fields documented in schema). (False-alarm "package doesn't exist" dropped.) +- ✅ **PR #611 — telemetry:** T1 (P2 `ngaf:runtime_request_created` event added to reference), T2 (P2 `captureRuntimeRequestCreated()` documented in browser + node guides). + +**Process note:** the licensing fix branch was cut from a stale local `main`; the source-freshness guard caught it (origin/main had advanced with an unrelated #606 ag-ui feature), and all 3 fix branches were re-based on current `origin/main` before fixes were applied/verified. + +**Verified:** all 16 routes returned HTTP 200; no `type="note"` Callout; no `libs/*` source bugs. + +## Summary + +- **P0: 1** · **P1: 1** · **P2: 5** · **P3: 1** (a2ui: 1 P2; licensing: 1 P0 + 1 P1 + 1 P2 + 1 P3; telemetry: 2 P2) +- **a2ui is nearly clean** (the protocol/schema/parser references are accurate); **licensing** has the only P0 (a wrong `LicenseTier` union) plus a missing exported type and a wrong idempotency claim; **telemetry** is missing a whole event (`ngaf:runtime_request_created`) + its capture method from the docs. +- **Dropped (false alarm):** a2ui `introduction.mdx:5` "`@threadplane/chat`/`@threadplane/render` don't exist" — they do; the prose ("those jobs sit in chat and render") is correct. + +--- + +## Findings by lib + +### a2ui + +| # | page:line | dim | severity | what's wrong | source evidence | fix | +|---|---|---|---|---|---|---| +| A1 | `reference/schema.mdx` (A2uiSurface section, ~line 173) | completeness | P2 | `theme?: A2uiTheme` is referenced but `A2uiTheme`'s fields are never documented | `libs/a2ui/src/lib/types.ts:5-9` (`primaryColor?`, `iconUrl?`, `agentDisplayName?` — all optional strings) | Add a short `A2uiTheme` block: `{ primaryColor?: string; iconUrl?: string; agentDisplayName?: string }` | + +(Optional polish, not blocking — surfaced by the core auditor, low value: nested `valueMap` recursion in `A2uiDataModelEntry`, the `sendDataModel` opt-in flow, and `styles` format guidance. Include only if cheap; otherwise leave — the pages are accurate as-is.) + +### licensing + +| # | page:line | dim | severity | what's wrong | source evidence | fix | +|---|---|---|---|---|---|---| +| L1 | `reference/api.mdx:8` | accuracy | **P0** | `LicenseTier` documented as `'developer-seat' \| 'app-deployment' \| 'enterprise'` | `libs/licensing/src/lib/license-token.ts:4` → `'developer_seat' \| 'team' \| 'enterprise'` | Change to `'developer_seat' \| 'team' \| 'enterprise'` | +| L2 | `reference/api.mdx:5-35` | completeness | P2 | `EvaluateResult` is exported and used in the documented function signatures but missing from the Types section | `libs/licensing/src/index.ts:5` (exported); `libs/licensing/src/lib/evaluate-license.ts:22` (`interface EvaluateResult { status: LicenseStatus; claims?: ... }`) | Add the `EvaluateResult` interface to the Types section (read evaluate-license.ts:22-26 for exact fields) | +| L3 | `reference/api.mdx:101` | conceptual | P1 | Claims a repeated `runLicenseCheck` returns `'licensed'`; it actually returns the **cached original status** (any status) | `libs/licensing/src/lib/run-license-check.ts:26-31` (returns `cached`; source comment: "not a hard-coded 'licensed'") | Reword to "returns the same status computed on the first call" | +| L4 | `guides/setup.mdx:26`, `guides/ci-and-offline.mdx:18`, `getting-started/introduction.mdx:63` | accuracy | P3 | Inconsistent `process.env.X` vs `process.env['X']` access in examples | lib uses bracket-access for `noPropertyAccessFromIndexSignature` (`libs/licensing/src/lib/infer-noncommercial.ts:16-19`) | Optional: standardize on bracket-access in env examples for strict-mode consistency | + +### telemetry + +| # | page:line | dim | severity | what's wrong | source evidence | fix | +|---|---|---|---|---|---|---| +| T1 | `reference/events.mdx:12-47` | completeness | P2 | `ngaf:runtime_request_created` is missing from the documented event-type unions (Node + browser) and the events table | `libs/telemetry/src/shared/events.ts:4`, `libs/telemetry/src/browser/tokens.ts:7` (event exists); node adapter/client emit it | Add `'ngaf:runtime_request_created'` to the documented unions + a table row (payload: `transport`, `requestType`, `provider`, `model` when supplied) | +| T2 | `guides/browser.mdx` (~63-77) + `guides/node.mdx` (~5-59) | completeness | P2 | `captureRuntimeRequestCreated()` (browser service + node adapter) is undocumented | `libs/telemetry/src/browser/service.ts:83-84`; `libs/telemetry/src/node/adapter.ts:36-37` (+ exported from `node/index.ts`) | Document the method in both guides (import + a usage example with `transport`/`requestType`/`provider`/`model`) | + +--- + +## Structural / won't-fix-here + +- No `libs/*` source bugs identified. +- `api-docs.json` generator nuances — already tracked as follow-ups from prior reviews. + +## Verified NON-issues (no change) + +- a2ui `introduction.mdx:5` — `@threadplane/chat`/`@threadplane/render` exist; prose is correct (dropped false-alarm P0). +- a2ui guards — docs correctly list only the 4 exported guards (`isLiteralArray` is internal-only); accurate. +- a2ui schema/parser/resolver/pointer references — verified accurate vs `types.ts`/`parser.ts`/`resolve.ts`/`guards.ts`/`pointer.ts`. +- telemetry `posthogKey`/`posthogHost` deprecation + opt-out env vars — accurately documented. + +--- + +## Fix plan (per-lib PRs) + +Default cutoff: **P0+P1+P2; cheap P3** (L4 optional). Per-lib PRs (all three have findings): +- **PR a2ui:** A1 (+ optional polish only if trivial). +- **PR licensing:** L1 (P0), L2, L3 (+ L4 if cheap). +- **PR telemetry:** T1, T2. diff --git a/docs/superpowers/specs/2026-06-06-small-libs-docs-technical-review-design.md b/docs/superpowers/specs/2026-06-06-small-libs-docs-technical-review-design.md new file mode 100644 index 00000000..4838a2f5 --- /dev/null +++ b/docs/superpowers/specs/2026-06-06-small-libs-docs-technical-review-design.md @@ -0,0 +1,120 @@ +# Small Libs Docs Technical Review (a2ui + licensing + telemetry) — Design + +**Date:** 2026-06-06 +**Status:** Draft for review +**Scope:** A combined technical-accuracy review of the three remaining non-adapter libs' docs — a2ui (7 pages), licensing (4), telemetry (5) — 16 pages / ~1,577 lines, cross-referenced against library source. One severity-ranked findings report; per-lib fix PRs. Completes the docs technical-review program (render #590, chat #594–597, langgraph #601–603, ag-ui #604–605). + +## Goal + +Make the a2ui, licensing, and telemetry docs technically correct: every code +snippet, import/package, API name and signature, behavioral claim, and internal +link matches the implementation — with the **reference pages** as the priority +(a2ui schema + parser/resolver/guards, licensing api, telemetry events). Catch +documented-but-nonexistent APIs and exported-but-undocumented ones. Discovery is +separated from fixing; findings are triaged before any edit. + +This is a **docs accuracy** review. It does not change `libs/*` source and does not +restructure the docs. + +## Surface under review (16 pages, all in scope) + +- **a2ui** (`apps/website/content/docs/a2ui/`, 7): getting-started `introduction`, `quickstart`; guides `message-protocol`, `data-model`, `adapters-and-validation`; reference `schema`, `parser-resolver-guards`. +- **licensing** (`apps/website/content/docs/licensing/`, 4): getting-started `introduction`; guides `setup`, `ci-and-offline`; reference `api`. +- **telemetry** (`apps/website/content/docs/telemetry/`, 5): getting-started `introduction`; guides `browser`, `node`, `privacy-and-opt-out`; reference `events`. + +(The `chat/a2ui/*` surface pages are NOT in scope — reviewed in #590/#594.) + +## Ground-truth sources + +| Auditor | Pages | Ground-truth source | +|---|---|---| +| a2ui-core | a2ui gs ×2 + guides ×3 (5) | `libs/a2ui/src` — `lib/types.ts` (A2uiMessage envelopes, A2uiSurface, components, dataModel), `lib/parser.ts`, `lib/resolver` / `lib/guards`, `src/index.ts` (exports) | +| a2ui-reference | a2ui reference: `schema`, `parser-resolver-guards` (2) | `libs/a2ui/src/lib/types.ts` (the schema), the parser/resolver/guard functions + their signatures (the API surface) | +| licensing | licensing gs + guides ×2 + reference (4) | `libs/licensing/src` — `evaluateLicense` + status/result types; the browser-safe constraint (no Buffer/bare `process`, bracket-access Record types per repo memory) | +| telemetry | telemetry gs + guides ×3 + reference (5) | `libs/telemetry/src` — `browser/*` (tokens incl. deprecated `posthogKey`/`posthogHost`, sink), `node/*`, `shared/*`, the emitted events catalog | + +`libs//src/(public-api.ts|index.ts)` is authoritative for each lib's exports. + +## Methodology — two gated phases + +### Phase 1 — Audit (read-only, parallel) + +Four section audit subagents run concurrently (disjoint reads). Each is read-only +and returns findings as rows: +`page:line · dimension · severity · what's-wrong · source-evidence(libs/…:line) · proposed-fix`. + +Then a **per-lib completeness sweep**: diff each lib's exports against what its docs +document — flag exported-but-undocumented and documented-but-nonexistent. + +The controller re-verifies borderline/surprising findings against source (prior +reviews caught false alarms AND a stale-source bug this way — see the ag-ui +incident), consolidates one severity-ranked report grouped by lib, flags systemic +issues, and **pauses at a triage checkpoint**. + +### Phase 2 — Fix (subagent-driven, per-lib PRs) + +After triage, fixes ship as **up to 3 PRs** (one per lib with findings; skip clean +libs). Each PR is its own branch off the **latest** `origin/main` — explicit +`git fetch origin main` + an up-to-date check BEFORE cutting the branch and BEFORE +applying source-cited fixes (the ag-ui review hit a stale-local-`main` whose +`reducer.ts` predated real handling; this guard prevents a repeat). Within each PR, +fixes are grouped by section; the implementer re-verifies every changed snippet +against the cited source line, re-checks internal links against `docs-config.ts`, +and an independent accuracy reviewer confirms each fix matches source before +commit. Only supported `Callout` types (`tip`/`info`/`warning`/`danger` — never +`note`). Each PR ends with a render-200 check. + +## The four audit dimensions + +1. **Code-snippet accuracy** — import/package, exported symbol, signature, option + keys, types match source exactly. Wrong package or nonexistent symbol = P0. +2. **Conceptual correctness** — prose claims about the A2UI protocol/parsing, + license evaluation semantics, and telemetry sink/opt-out behavior match the + implementation. Runs-but-wrong-model = P1. +3. **Links + runnability** — internal links resolve via `docs-config.ts`; examples + are internally coherent and would compile/run as written. +4. **Completeness/gaps** — exported-but-undocumented APIs, documented-but-nonexistent + APIs, missing options/behaviors, thin coverage. **Reference pages are the + priority:** a2ui `schema` must match `types.ts`; `parser-resolver-guards` must + match the real function signatures; licensing `api` and telemetry `events` must + match source. + +## Findings report format + +One report: `docs/superpowers/specs/2026-06-06-small-libs-docs-review-findings.md`, +**grouped by lib**. Severity taxonomy (same as prior reviews): **P0 wrong** / +**P1 misleading** / **P2 gap** / **P3 polish**. Each row carries a source citation. +The report ends with a "Structural / won't-fix-here" section (any `libs/*` source +bug; api-docs.json generator nuances already tracked) and a per-lib "Fix plan" +with a P-level cutoff. + +## Testing & verification + +- **Phase 1:** every finding carries a concrete source citation; the controller + spot-checks + re-verifies borderline findings (and confirms source freshness) + before trusting them. +- **Phase 2 per PR:** each changed snippet re-verified against its cited source + line on up-to-date source; internal links re-checked; edited pages return HTTP + 200; an independent accuracy reviewer signs off. +- **Final:** the edited routes return 200; no documented API attributed to the + wrong package; planning artifacts landed. + +## Out of scope + +- Voice/prose-register edits (already shipped) — except where a P0/P1 fix rewrites a sentence. +- `libs/*` **source** changes — real code bugs flagged for separate follow-ups. +- Net-new pages/examples beyond filling documented gaps the report identifies. +- The `chat/a2ui/*` surface pages (already reviewed); other libraries' docs; restructuring. +- `api-docs.json` generator nuances (already spawned as follow-ups). + +## Self-review notes + +- **Placeholder scan:** none — every section names concrete files/sources. +- **Internal consistency:** the 4-auditor split matches the ground-truth table; the + per-lib PR structure matches Phase 2 and the report's per-lib fix-plan; reference + pages flagged as priority in both the methodology and dimension 4; the + up-to-date-source guard appears in Phase 2 + verification (ag-ui lesson). +- **Scope:** three independent but small libs handled as one review program (per-lib + audit tracks, per-lib fixes) — efficient without conflating the libs' findings. +- **Ambiguity:** "combined review, per-lib fix PRs" = one findings report grouped by + lib, then up to 3 PRs; clean libs are skipped.