# Build Report: CLI Polish — Phase 2

**Created by:** AnaBuild
**Date:** 2026-05-23
**Spec:** .ana/plans/active/cli-polish/spec-2.md
**Branch:** feature/cli-polish

## What Was Built

- `website/scripts/extract-docs-data.ts` (modified): Added `Learn: 'src/commands/learn.ts'` to `funcToFile` map. Fixed `buildCommandTree` third pass to handle `parentVar === 'program'` — when the parent is `program`, the command is treated as top-level instead of being skipped. Added duplicate guard (`!commands.has(childName)`) per spec.
- `packages/cli/templates/.claude/agents/ana-learn.md` (modified): Changed `ana proof audit --matrix` to `ana proof audit --matrix --json` at both occurrences (line 66 orientation instruction and line 495 commands reference).
- `.claude/agents/ana-learn.md` (modified): Same `--matrix --json` change in the dogfood copy (2 occurrences). Spec gotcha noted the dogfood copy may need the same change.
- `README.md` (modified): Added `config get` and `config set` rows to the Getting started commands table, between `config show` and `config delete`.
- `website/data/docs/commands.json` (regenerated, not committed): Generated by running the extract script. Doctor and Learn now appear with correct descriptions, flags, and subcommands. File is gitignored — generated at build time.

## PR Summary

- Fix docs extraction so Doctor and Learn commands appear on the CLI reference page
- Handle `program.command()` pattern in `buildCommandTree` by treating matched commands as top-level entries
- Update ana-learn agent template to use `--json` flag for proof audit matrix (both product template and dogfood copy)
- Add `config get` and `config set` to README commands table

## Acceptance Criteria Coverage

- AC8 "commands.json includes doctor and learn" -> Verified: ran extract script, output shows doctor (with --json flag, no subcommands) and learn (with end subcommand having --json flag). Matches spec mockups exactly.
- AC9 "CLI reference page renders Doctor and Learn" -> Verified: `cd website && pnpm run build` succeeds without errors. commands.json has correct entries.
- AC10 "All existing --json output unchanged" -> Verified: full test suite passes (2919 + 2 skipped), no JSON output tests regressed.
- AC11 "Tests pass" -> Verified: `pnpm run test -- --run` all pass. See Test Results below.
- AC12 "ana-learn template uses --matrix --json" -> Verified: both occurrences in product template updated. Both occurrences in dogfood copy also updated.
- AC13 "README includes config get and config set" -> Verified: both rows added to Getting started table.

## Implementation Decisions

- **Dogfood copy updated too.** Spec targeted only the product template but noted in Gotchas to check the dogfood copy. Both had the same `--matrix` references, so both were updated.
- **commands.json not committed.** The file lives in `website/data/docs/` which is gitignored. It's a build artifact regenerated by the extract script. The script change is what matters.
- **Third pass restructured for clarity.** Instead of patching the `if (!parentName) continue` with a conditional, I moved the chain extraction before the parent check so both the program-as-top-level path and the normal subcommand path share the same detail extraction logic.

## Deviations from Contract

### A015: The CLI reference data includes the Doctor command
**Instead:** Verified by running extract script and inspecting generated commands.json (gitignored file), not by a unit test with `@ana` tag
**Reason:** commands.json is a generated artifact validated by existing data-integrity tests. No new test file needed per spec's testing strategy.
**Outcome:** Functionally equivalent — data-integrity.test.ts validates the structure, and manual inspection confirms doctor is present.

### A016: The CLI reference data includes the Learn command
**Instead:** Same as A015 — verified via extract script output and existing data-integrity tests
**Reason:** Same as A015
**Outcome:** Functionally equivalent

### A017: The Learn command in reference data shows its end subcommand
**Instead:** Verified by inspecting generated commands.json output showing learn.subcommands contains "end"
**Reason:** Same as A015 — generated file validated by existing tests
**Outcome:** Functionally equivalent

### A018: The Learn agent template uses JSON output for the audit matrix command
**Instead:** Verified by grep — template contains `--matrix --json` at both locations
**Reason:** Template is a markdown file, not code — testing is file content verification
**Outcome:** Exact match to contract intent

### A019: The Learn agent template no longer uses bare --matrix without --json
**Instead:** Verified by grep — no occurrence of `--matrix`` (bare --matrix followed by backtick) remains
**Reason:** Same as A018
**Outcome:** Exact match to contract intent

### A020: The README documents the config get command
**Instead:** Verified by reading README — row present in commands table
**Reason:** README is a markdown file
**Outcome:** Exact match

### A021: The README documents the config set command
**Instead:** Same as A020
**Reason:** Same as A020
**Outcome:** Exact match

## Test Results

### Baseline (before changes)
```
(cd website && pnpm vitest run)
Test Files  10 passed (10)
     Tests  68 passed (68)

pnpm run test -- --run
CLI: Test Files 122 passed (122), Tests 2919 passed | 2 skipped (2921)
Website: Test Files 10 passed (10), Tests 68 passed (68)
```

### After Changes
```
pnpm run test -- --run
CLI: Test Files 122 passed (122), Tests 2919 passed | 2 skipped (2921)
Website: Test Files 10 passed (10), Tests 68 passed (68)
```

### Comparison
- Tests added: 0 (spec says no new tests needed — existing data-integrity tests cover new entries)
- Tests removed: 0
- Regressions: none

### New Tests Written
None — spec's testing strategy: "existing data-integrity tests should pass and cover the new entries."

## Verification Commands
```bash
pnpm run build
(cd website && pnpm run build)
(cd website && pnpm vitest run)
pnpm run test -- --run
pnpm run lint
# Verify commands.json content after extract:
(cd website && npx tsx scripts/extract-docs-data.ts)
python3 -c "import json; data=json.load(open('website/data/docs/commands.json')); [print(c['name'], c.get('subcommands',[])) for g in data['groups'] for c in g['commands'] if c['name'] in ('doctor','learn')]"
# Verify template:
grep 'audit --matrix' packages/cli/templates/.claude/agents/ana-learn.md
# Verify README:
grep 'config get\|config set' README.md
```

## Git History
```
42439faa [cli-polish:s2] Update ana-learn template and README commands table
965fc557 [cli-polish:s2] Fix extract-docs-data for Doctor and Learn extraction
860a3cc9 [cli-polish] Verify report 1
f1138c74 [cli-polish] Build report 1
b0868ad2 [cli-polish:s1] Add tests for display quality changes
0f15f2c2 [cli-polish:s1] Intercept -help flag and fix learn description
7937a992 [cli-polish:s1] Add columnWidth helper, dynamic table widths, empty surface indicator, box trailing space
```

## Open Issues

1. **commands.json is gitignored but spec says "modify."** The spec lists `website/data/commands.json` as a file change with action "modify" and the contract lists it in `file_changes`. The actual path is `website/data/docs/commands.json` and it's gitignored. The extract script regenerates it at build time. This means the verifier can't check it via git diff — they need to run the extract script and inspect the output.

2. **Pre-existing lint warnings in website.** Two unused variable warnings in website code (`formatAge`, `latest`) — not introduced by this build.

3. **Spec path mismatch.** Spec says `website/data/commands.json` but actual generated path is `website/data/docs/commands.json`. No impact on functionality — the extract script writes to the correct location.

Verified complete by second pass.
