# Build Report: Platform setup guide and conditional platform content

**Created by:** AnaBuild
**Date:** 2026-06-01
**Spec:** .ana/plans/active/docs-readme-platform-update/spec-2.md
**Branch:** feature/docs-readme-platform-update

## What Was Built
- website/content/docs/guides/platform-setup.mdx (modified): expanded the Platform setup guide with init and run resolution order, `ANA_PLATFORM`, `platformFlags`, Claude Code permission flags, Codex `.agent.toml` fields, `danger-full-access`, switching platforms, and the current Codex Learn limitation.
- website/content/docs/start.mdx (modified): added paired Claude Code/Codex prerequisite and setup guidance, linked to Platform setup, and kept the terminal mockup unwrapped.
- website/content/docs/guides/configurability.mdx (modified): clarified canonical `.ana/skills/` usage and split Claude Code markdown agent delivery from Codex prompt/manifest delivery.
- website/content/docs/guides/troubleshooting.mdx (modified): added paired platform recovery guidance for missing executables, permission/sandbox/manifest problems, and Codex Learn unavailability.
- website/content/docs/guides/using-ana-learn.mdx (modified): added paired platform guidance near the start while preserving `ana run learn` as the universal command.
- website/lib/__tests__/docs-platform-content.test.ts (modified): extended docs invariants for paired platform blocks, start-page mockup safety, Platform setup resolution topics, manifest fields, and Learn limitation.
- website/public/search-index.json, website/public/llms.txt, website/public/llms-full.txt (regenerated/verified): generated by `website/scripts/extract-docs-data.ts` during website build; these files are ignored by git but current in the working tree.

## PR Summary
- Adds complete Platform setup docs for Claude Code and Codex, including platform resolution, init behavior, flags, Codex manifests, sandbox mode, switching, and Learn limitations.
- Adds paired `ForPlatform` content where Claude Code and Codex behavior differs in Quickstart, Configurability, Troubleshooting, Learn, and Platform setup.
- Extends docs content invariants so every conditional Claude Code block has a Codex counterpart and generated docs data includes the new guide.
- Regenerates docs search and LLM assets through the website build path.

## Acceptance Criteria Coverage
- AC2 "Selecting Codex in the docs switcher shows Codex-appropriate content anywhere `ForPlatform` is used" → docs-platform-content.test.ts "has no unpaired Claude Code conditional docs blocks" and "keeps platform-specific docs in adjacent Claude Code and Codex pairs".
- AC3 "Every `ForPlatform platform=\"claude-code\"` content block has a corresponding `ForPlatform platform=\"codex\"` block for the same user need" → docs-platform-content.test.ts adjacent pair invariant.
- AC4 "start.mdx quickstart works for both Claude Code and Codex users, uses `ana run` commands, explains dispatch once, and does not wrap the terminal mockup" → docs-platform-content.test.ts quickstart tests.
- AC5 "start.mdx terminal mockup reflects current `ana init` output" → docs-platform-content.test.ts quickstart init output test.
- AC11 "New guide exists at `/docs/guides/platform-setup` and is linked from the Guides nav" → docs-platform-content.test.ts Platform setup guide test; website build route generation passed.
- AC12 "Platform setup guide covers platform setup topics" → docs-platform-content.test.ts Platform setup guide and resolution-order tests.
- AC13 "configurability.mdx custom skill and agent sections are updated" → docs-platform-content.test.ts Configurability guide platform paths test.
- AC14 "troubleshooting.mdx includes Codex-specific recovery guidance" → docs-platform-content.test.ts Codex limitations and troubleshooting test.
- AC17 "Learn documentation is honest about current platform support" → docs-platform-content.test.ts Codex limitations and Platform setup tests.
- AC19 "Website build succeeds from website/" → `(cd 'website' && pnpm run build)` passed.
- AC20 "Generated docs assets are regenerated or verified current" → website build ran `tsx scripts/extract-docs-data.ts` and generated `public/search-index.json`, `public/llms.txt`, and `public/llms-full.txt`.
- Tests pass with the website test command → `(cd 'website' && pnpm vitest run lib/__tests__/docs-platform-content.test.ts)` passed with 16 tests.
- Root test baseline still passes after all phases → `pnpm run test -- --run` passed with CLI 3099 passed/2 skipped and website 84 passed.

Contract coverage: 35/35 assertions tagged.

## Implementation Decisions
- Added more than the checkpoint's expected 15 tests: the final docs-platform-content file has 16 tests because I split Platform setup resolution coverage and adjacent `ForPlatform` pair coverage into separate invariants.
- Kept generated public docs assets uncommitted because `website/.gitignore` ignores them; the build command regenerates them and the tests read the generated working-tree files.
- Used paired `ForPlatform` blocks only around platform-specific prose and kept fenced code blocks inside the blocks only where each platform needs distinct examples.

## Deviations from Contract
None — contract followed exactly.

## Test Results

### Baseline (before changes)
Command: `pnpm run build`

```text
> anatomia-workspace@0.0.0 build
> turbo run build

Tasks: 2 successful, 2 total
Cached: 2 cached, 2 total
Time: 428ms >>> FULL TURBO
```

Command: `(cd 'website' && pnpm vitest run lib/__tests__/docs-platform-content.test.ts)`

```text
RUN  v4.1.5 .../website

Test Files  1 passed (1)
Tests  13 passed (13)
Duration  158ms
```

Tests: 13 passed, 0 failed, 0 skipped for the focused website invariant baseline.

### After Changes
Command: `(cd 'website' && pnpm vitest run lib/__tests__/docs-platform-content.test.ts)`

```text
RUN  v4.1.5 .../website

Test Files  1 passed (1)
Tests  16 passed (16)
Duration  233ms
```

Command: `(cd 'website' && pnpm run build)`

```text
> anatomia-website@0.1.0 prebuild
> tsx scripts/extract-docs-data.ts

✓ All data extracted successfully
  Proof entries: 175
  Commands: 35 (4 groups)
  Agents: 6
  Skills: 8
  Gotchas: 15
  Context files: 4
  Search index: 245 entries
  Version: 1.1.5

> anatomia-website@0.1.0 build
> next build

✓ Compiled successfully
✓ Generating static pages using 13 workers (223/223)
```

Command: `(cd 'website' && pnpm run lint)`

```text
> anatomia-website@0.1.0 lint
> eslint

website/components/hero/Hero.tsx
   3:24  warning  'formatAge' is defined but never used        @typescript-eslint/no-unused-vars
  16:9   warning  'latest' is assigned a value but never used  @typescript-eslint/no-unused-vars

✖ 2 problems (0 errors, 2 warnings)
```

Command: `pnpm run test -- --run`

```text
> anatomia-workspace@0.0.0 test
> turbo run test "--" "--run"

anatomia-cli:test:
Test Files  129 passed (129)
Tests  3099 passed | 2 skipped (3101)
Duration  46.80s

anatomia-website:test:
✓ lib/__tests__/docs-data/staleness.test.ts (7 tests)
✓ lib/__tests__/docs-data/data-integrity.test.ts (6 tests)
✓ lib/__tests__/copy.test.ts (6 tests)
✓ lib/__tests__/format.test.ts (4 tests)
✓ lib/__tests__/docs-platform-content.test.ts (16 tests)
✓ lib/__tests__/docs-data/page-dates.test.ts (6 tests)
✓ lib/__tests__/docs-data/proofs.test.ts (8 tests)
✓ lib/__tests__/docs-data/docs-stat-values.test.ts (5 tests)
✓ lib/__tests__/docs-data/strip-jsx.test.ts (8 tests)
✓ lib/__tests__/marketing-stats.test.ts (12 tests)
✓ lib/__tests__/proof-feed.test.ts (6 tests)

Test Files  11 passed (11)
Tests  84 passed (84)

Tasks: 4 successful, 4 total
```

Command: `pnpm run build`

```text
> anatomia-workspace@0.0.0 build
> turbo run build

anatomia-cli:build: ESM Build success in 32ms
anatomia-website:build: ✓ All data extracted successfully
anatomia-website:build: ✓ Compiled successfully
anatomia-website:build: ✓ Generating static pages using 13 workers (223/223)

Tasks: 2 successful, 2 total
Cached: 1 cached, 2 total
Time: 9.065s
```

Tests: 3183 passed, 0 failed, 2 skipped across CLI and website package tests.

### Comparison
- Tests added: 3 focused docs invariant tests.
- Tests removed: 0.
- Regressions: none.

### New Tests Written
- website/lib/__tests__/docs-platform-content.test.ts: added start-page paired-platform/mockup coverage, Platform setup resolution and manifest coverage, and adjacent `ForPlatform` pair coverage.

## Verification Commands
```bash
pnpm run build
cd 'website' && pnpm vitest run lib/__tests__/docs-platform-content.test.ts
cd 'website' && pnpm run build
cd 'website' && pnpm run lint
pnpm run test -- --run
```

## Git History
```text
3c792e91 [docs-readme-platform-update:s2] Add platform setup docs
21f2c10a [docs-readme-platform-update] Verify report 1
a5e07840 [docs-readme-platform-update] Build report 1
d615d0a3 [docs-readme-platform-update:s1] Update docs for multi-platform support
```

## Open Issues
- Website lint reports 2 pre-existing warnings in `website/components/hero/Hero.tsx`; this build did not touch that file.
- `website/public/search-index.json`, `website/public/llms.txt`, and `website/public/llms-full.txt` are regenerated by the build but ignored by git. They were verified current in the working tree and by tests.
- Next.js emits non-fatal data-cache warnings for the remote proof chain exceeding 2MB during static generation. The build still succeeds.

What did I notice during the build that I didn't write down? The final `pnpm run test -- --run` was cached after the first full post-change run, but the uncached post-change run also passed and is reflected above. Verified complete by second pass.
