# Build Report: Dynamic Pages — Phase 1 (Data Pipeline + Reference Pages)

**Created by:** AnaBuild
**Date:** 2026-05-13
**Spec:** .ana/plans/active/dynamic-pages/spec-1.md
**Branch:** feature/dynamic-pages

## What Was Built
- `website/scripts/extract-docs-data.ts` (modified): Word boundary `\b` fix on 5 keyword fallback regex patterns. Extraction pipeline extended: ProofEntry gains assertions array, findings array, timing object, hashes, findingSeverity counts, duration, prevSlug/nextSlug. AgentTemplate gains role + displayDescription via static AGENT_DISPLAY map. SkillTemplate gains conditional flag, rules count, content body. Contract normalized to total/satisfied/unsatisfied. Finding severity defaults to "observation". Missing timing stages default to 0. Context extraction extended from 2 to 4 files with path/description metadata.
- `website/lib/docs-data/types.ts` (modified): Added ProofAssertion, ProofFinding, ProofTiming interfaces. Extended ProofEntry with new fields. Extended AgentTemplate with role/displayDescription. Extended SkillTemplate with conditional/rules/content. Extended ContextFile with path/description.
- `website/lib/source.ts` (modified): 4 transformer URLs updated from old slug-style to blueprint routes (/docs/reference/cli, /docs/reference/agents, /docs/reference/skills, /docs/reference/context).
- `website/lib/docs-data/proofs.ts` (modified): Added getProofBySlug(slug) function.
- `website/lib/docs-data/index.ts` (modified): Added exports for getProofBySlug and new types (ProofAssertion, ProofFinding, ProofTiming).
- `website/components/docs/reference/ReferenceGrid.tsx` (created): 2-column CSS grid container with className prop and docs-ref-grid class.
- `website/components/docs/reference/AgentCard.tsx` (created): Agent index card with name, model badge, role, description. Links to detail page.
- `website/components/docs/reference/SkillCard.tsx` (created): Skill index card with name, core/conditional badge, description, rule count. Links to detail page.
- `website/components/docs/reference/CommandGroup.tsx` (created): Command group renderer with heading, command items, flags, recursive subcommands.
- `website/app/docs/reference/cli/page.tsx` (created): CLI reference page rendering all command groups from extracted data.
- `website/app/docs/reference/agents/page.tsx` (created): Agent templates index with Pipeline and System sections.
- `website/app/docs/reference/agents/[name]/page.tsx` (created): Agent detail pages for all 6 agents with reads/writes/forbidden table, full template in CodeBlock, GitHub links.
- `website/app/docs/reference/skills/page.tsx` (created): Skill files index with Core and Conditional sections.
- `website/app/docs/reference/skills/[name]/page.tsx` (created): Skill detail pages for all 8 skills with full SKILL.md content in CodeBlock, GitHub links, callout.
- `website/app/docs/reference/context/page.tsx` (created): Context files reference with all 4 files, paths, descriptions, full content in CodeBlock.
- `website/app/docs/docs.css` (modified): Added docs-ref-card hover state, docs-content-full class, responsive collapse for docs-ref-grid at 660px.

## PR Summary

- Add 18 new reference page routes: CLI commands, 6 agent templates (index + details), 8 skill files (index + details), and context files reference
- Extend the extraction pipeline to produce full proof detail data (assertions, findings, timing, hashes, severity counts, adjacent slugs) for Phase 2
- Fix word boundary regex in keyword fallback categorization and update sidebar transformer URLs to match blueprint routes
- Add AgentCard, SkillCard, ReferenceGrid, and CommandGroup reusable components with supermock-matching styles
- Normalize inconsistent proof chain data: timing defaults, contract shape, finding severity defaults

## Acceptance Criteria Coverage

- AC1 "Word boundary regex fix" → extract-docs-data.ts lines 115-119: all 5 patterns wrapped with `\b` ✅
- AC2 "Transformer URLs match blueprint" → source.ts: 4 URLs updated ✅
- AC3 "ProofEntry type extended" → types.ts: ProofAssertion, ProofFinding, ProofTiming interfaces + all new fields on ProofEntry ✅
- AC4 "SkillTemplate extended" → types.ts: conditional, rules, content fields ✅
- AC5 "AgentTemplate extended" → types.ts: role, displayDescription fields; extract-docs-data.ts: AGENT_DISPLAY map with supermock values ✅
- AC6 "Extraction produces extended data" → Verified via extraction run: 89 entries with all new fields ✅
- AC7 "prevSlug/nextSlug pre-computed" → Verified: first entry prevSlug=null, last entry nextSlug=null ✅
- AC8 "CLI reference page renders" → /docs/reference/cli route in build output ✅
- AC9 "Agent index renders" → /docs/reference/agents with Pipeline and System sections ✅
- AC10 "Agent detail pages render" → 6 agent detail pages in build output ✅
- AC11 "Skill index renders" → /docs/reference/skills with Core and Conditional sections ✅
- AC12 "Skill detail pages render" → 8 skill detail pages in build output ✅
- AC13 "Context reference renders" → /docs/reference/context with 4 files ✅
- AC14 "docs-content-area class" → All 6 page routes use `docs-content-area` on article element ✅
- AC15 "RightRail on all pages" → All 6 page routes render RightRail with appropriate TOC ✅
- AC16 "pnpm build succeeds" → 45 pages generated, exit 0 ✅
- AC17 "Reference card grids responsive" → docs-ref-grid class with 660px collapse in docs.css, className props on ReferenceGrid ✅
- AC34 "Content verbatim from supermock" → All ledes, callouts, section headings translated from supermock render functions ✅
- AC35 "GitHub links" → Agent detail: `packages/cli/templates/.claude/agents/{name}.md`; Skill detail: `packages/cli/templates/.claude/skills/{name}/SKILL.md` ✅
- "Tests pass" → CLI tests: 1895 passed, 283 failed (pre-existing), 2 skipped — same as baseline ✅
- "No build errors" → Website build succeeds with 45 pages ✅

## Implementation Decisions

1. **Context extraction extended to 4 files.** The spec says context page renders "all 4 files" but the existing extraction only pulled 2. Added scan.json and ana.json with descriptions matching the supermock's CONTEXT_FILES data. Updated validation count from 2 to 4.

2. **Command subcommand rendering.** CommandGroup uses recursive CommandItem to render nested subcommands with indentation. The supermock renders flat commands, but the extracted data has tree structure — recursive rendering handles both.

3. **Agent display map values.** Used verbatim text from the supermock spec table in AGENT_DISPLAY, not from CLI frontmatter descriptions.

## Deviations from Contract

None — contract followed exactly for all Phase 1 assertions (A001–A032).

## Fix History

- **Fix 1 (CodeBlock):** Replaced raw `<pre data-language>` with `<CodeBlock data-language>` in agent detail, skill detail, and context reference pages. Added missing CodeBlock imports to skill detail and context pages. Agent detail already had the import. Build verified after fix.

## Test Results

### Baseline (before changes)
```
(cd packages/cli && pnpm vitest run)
Test Files  7 failed | 93 passed (100)
     Tests  283 failed | 1895 passed | 2 skipped (2180)
```

### After Changes
```
(cd packages/cli && pnpm vitest run)
Test Files  7 failed | 93 passed (100)
     Tests  283 failed | 1895 passed | 2 skipped (2180)
```

Website build:
```
(cd website && pnpm build)
✓ Compiled successfully in 2.4s
✓ Generating static pages using 13 workers (45/45) in 699ms
Routes: 45 pages (18 new reference routes)
Exit code: 0
```

### Comparison
- Tests added: 0 (website has no test infrastructure per spec)
- Tests removed: 0
- Regressions: none (CLI test counts identical to baseline)

### New Tests Written
- None — spec explicitly states "No unit tests for website components. This matches existing patterns — the website has zero test files. Verification is via build success + Vercel preview."

## Verification Commands
```bash
pnpm run build                          # Full monorepo build
(cd packages/cli && pnpm vitest run)    # CLI tests
(cd website && pnpm build)              # Website build (primary test surface)
pnpm run lint                           # Lint
```

## Git History
```
9d5bfa5e [dynamic-pages:s1] Fix: use CodeBlock component for template content
c43ec7de [dynamic-pages:s1] Add reference pages and CSS
8c35d3e9 [dynamic-pages:s1] Add reference components
56c5d83b [dynamic-pages:s1] Extend types and extraction pipeline
98a2c549 [dynamic-pages:s1] Fix word boundary regex and transformer URLs
```

## Open Issues

1. **Pre-existing CLI test failures.** 7 test files (283 tests) fail with `MODULE_NOT_FOUND` on Node.js v25.9.0. Pre-existing — identical count before and after changes. Not introduced by this build.

2. **Pre-existing lint warning.** `packages/cli/src/utils/git-operations.ts:198` — unused eslint-disable directive. Not introduced by this build.

3. **1180px responsive breakpoint.** At widths between 881px and 1180px, the reference grid stays 2-column but the right rail hides. The ref-grid 660px collapse rule only fires at 660px. Between 881-1180px the grid may feel wide without the rail. The supermock's behavior at this range is the same — intentional.

Verified complete by second pass.
