# Spec: Docs and README Multi-Platform Migration

**Created by:** AnaPlan
**Date:** 2026-06-01
**Scope:** .ana/plans/active/docs-readme-platform-update/scope.md

## Approach
Phase 1 fixes the stale public contract: user-facing docs still teach Claude-only invocation even though the CLI now exposes `ana run` as the stable command surface. Treat this phase as a mechanical migration plus positioning pass. Replace normal pipeline instructions with `ana run`, update Claude-exclusive prose to Claude Code plus Codex, enable Codex in the docs switcher, and update landing/README copy so the product reads as a multi-platform CLI with native pipeline support for both platforms.

Use the CLI as source of truth. `packages/cli/src/commands/platform.ts` defines the user-facing command strings through `agentCommand()`: Think is `ana run`, and named agents are `ana run setup`, `ana run plan`, `ana run build`, `ana run verify`, and `ana run learn`. `packages/cli/src/commands/init/state.ts` is the source of truth for quickstart mock output: skills are canonical at `.ana/skills/`, and Next lines use `ana run`, `ana run setup`, and `ana init commit`.

Keep platform-specific rendering light in this phase. Do not add broad `ForPlatform` blocks here except where the migration would otherwise be inaccurate. Phase 2 owns the new platform setup guide and paired platform-specific sections. Phase 1 should leave no user-facing `claude --agent ...` instruction in README or existing docs except where intentionally describing Claude Code internals.

Testing should add one docs enforcement test file under the website tests. Source-content assertions are appropriate here because the documentation text and switcher config are the product behavior being enforced. Follow the existing Vitest import style in `website/lib/__tests__/copy.test.ts` and the file-reading style in `website/lib/__tests__/docs-data/data-integrity.test.ts`.

Open questions resolved:
- Platform setup guide nav placement is Phase 2 and goes immediately after `using-ana-setup`.
- Learn limitation content is Phase 2, but Phase 1 should use `ana run learn` wherever Learn is merely referenced as the universal command.
- Landing agent tree should become multi-platform for agents and canonical `.ana/skills/` for skills.

## Output Mockups
README opening:

```text
Anatomia is a CLI that runs every code change through a five-agent pipeline -- scope, spec, contract, build, and independent verification. It works with Claude Code and Codex.
```

README quickstart:

```bash
ana init                      # generate context + agents
ana init commit               # persist to git (so teammates get it too)
ana doctor                    # verify installation is healthy
ana run setup                 # enrich with your team's knowledge (optional, recommended, ~10 min)
ana run                       # start working -- "hey Ana"
```

Quickstart terminal mockup should show the current init shape:

```text
✓ Context -> .ana/context/ (2 files)
✓ Skills -> .ana/skills/ (7 skills)
  ✓ Cross-tool: CLAUDE.md + AGENTS.md

  Next:
    ana run             Start working (Ana knows your stack)
    ana run setup       Enrich with your team's knowledge (optional, ~10 min)
    ana init commit     Save to main ✓
```

Platform switcher expected behavior:

```text
Claude Code  selectable
Codex        selectable
Cursor       soon
Windsurf     soon
Copilot      soon
Cline        soon
```

## File Changes

Filesystem check before writing: all files below exist except the new test file. `website/public/search-index.json`, `website/public/llms.txt`, and `website/public/llms-full.txt` exist and are generated by `website/scripts/extract-docs-data.ts` during `website` prebuild.

### README.md (modify)
**What changes:** Replace Claude-only product positioning with the locked opening sentence from the scope. Update quickstart commands to `ana run setup` and `ana run`. Replace the Claude-only requirement callout with support for Claude Code and Codex, while preserving the broader markdown-aware tool claim. Update setup and uninstall language so canonical skills are `.ana/skills/`, platform agents may live under platform dirs, and README stays concise.
**Pattern to follow:** Keep README direct and high-level. Do not turn it into the platform setup guide.
**Why:** README is the top-level public contract. Claude-exclusive positioning contradicts the shipped CLI.

### website/content/docs/start.mdx (modify)
**What changes:** Make prerequisites, terminal mockup, setup recommendation, first run, stage handoffs, and rejection loop use `ana run` commands. Explain the dispatch relationship once: `ana run` invokes Claude Code agents on Claude projects and opens Codex with generated agent instructions on Codex projects. Do not wrap the terminal mockup in `ForPlatform`.
**Pattern to follow:** Preserve the existing styled terminal block structure and update the text in place. Use the current init output from `packages/cli/src/commands/init/state.ts`.
**Why:** Quickstart is the first Codex user journey and currently teaches the wrong command surface.

### website/content/docs/guides/verifying-changes.mdx (modify)
**What changes:** Update frontmatter description and all Build/Verify examples from `claude --agent ana-build` and `claude --agent ana-verify` to `ana run build` and `ana run verify`.
**Pattern to follow:** Preserve the existing guide structure and terminal block style.
**Why:** Verify docs must match the universal CLI handoff.

### website/content/docs/guides/using-ana-setup.mdx (modify)
**What changes:** Change setup invocation and rerun instructions to `ana run setup`. Keep the existing guide narrative and terminal block, only updating command syntax and any platform-exclusive phrasing.
**Pattern to follow:** Existing styled terminal mockup.
**Why:** Setup is invoked through `ana run setup` across supported platforms.

### website/content/docs/guides/reading-a-proof.mdx (modify)
**What changes:** Replace Learn triage command with `ana run learn`.
**Pattern to follow:** Small prose update only.
**Why:** Proof docs should teach the universal command.

### website/content/docs/concepts/context.mdx (modify)
**What changes:** Replace setup command with `ana run setup`. Update infrastructure list where needed to avoid presenting `.claude/` as universal.
**Pattern to follow:** Keep the concept page focused on context, not platform setup details.
**Why:** Context creation docs currently encode Claude-only setup.

### website/content/docs/concepts/findings.mdx (modify)
**What changes:** Replace Learn triage command with `ana run learn`.
**Pattern to follow:** Small prose update only.
**Why:** Findings lifecycle should use the CLI abstraction.

### website/content/docs/concepts/pipeline.mdx (modify)
**What changes:** Make independence/session language platform-neutral. Avoid saying each agent is a Claude Code session; say each stage starts a fresh platform session through `ana run`.
**Pattern to follow:** Keep the existing five-stage explanation and table.
**Why:** Pipeline independence is an Anatomia guarantee, not a Claude-only implementation detail.

### website/content/docs/concepts/toolbelt.mdx (modify)
**What changes:** Make baseline tooling prose platform-neutral. Keep `ana` CLI enforcement as the point of the page.
**Pattern to follow:** Existing command table and enforcement narrative.
**Why:** Toolbelt docs currently assume Claude Code as the host for all agents.

### website/content/docs/concepts/skills.mdx (modify)
**What changes:** Describe Anatomia skills as canonical `.ana/skills/` files shared by supported platforms. Mention Claude Code skills as one delivery path, not the identity of the feature. Replace setup command with `ana run setup`.
**Pattern to follow:** Keep the four-section structure and ownership model.
**Why:** Skills are no longer canonical under `.claude/skills/`.

### website/components/docs/layout/PlatformSwitcher.tsx (modify)
**What changes:** Set Codex to selectable. Keep Cursor, Windsurf, Copilot, and Cline disabled with "soon". Do not change provider types or cookie behavior.
**Pattern to follow:** Existing `platforms` array and disabled-state rendering.
**Why:** The provider already supports Codex; the disabled flag blocks the shipped platform.

### website/components/docs/content/AudienceCards.tsx (modify)
**What changes:** Replace "Requires Claude Code" with copy that says Claude Code or Codex.
**Pattern to follow:** Existing card copy length and tone.
**Why:** The installing card currently contradicts multi-platform support.

### website/lib/copy.ts (modify)
**What changes:** Update landing copy to include Codex in native pipeline support. Change system tree diagrams so agents are delivered through platform-specific dirs and skills are canonical at `.ana/skills/`. Avoid claiming unsupported platforms have native pipeline integration.
**Pattern to follow:** Keep copy centralized in this file. Preserve object shape so existing tests remain stable.
**Why:** Landing copy and diagrams are high-visibility public positioning.

### website/lib/__tests__/docs-platform-content.test.ts (create)
**What changes:** Add Vitest source-content enforcement for this release's docs contract. Include checks for README locked opening, no user-facing `claude --agent` instructions in migrated files, PlatformSwitcher Codex enabled and other future platforms disabled, canonical `.ana/skills/` references, quickstart current init output strings, landing/AudienceCards multi-platform copy, and generated docs assets after extraction.
**Pattern to follow:** Existing website tests use Vitest with direct imports or `readFileSync` for docs-data integrity.
**Why:** Docs drift caused this work. The test should prevent regression to Claude-only docs.

### website/public/search-index.json (modify)
**What changes:** Regenerate or verify current after docs copy changes.
**Pattern to follow:** Generated by `website/scripts/extract-docs-data.ts` through `pnpm run build` or `pnpm run prebuild` in `website/`.
**Why:** Search must reflect changed docs text.

### website/public/llms.txt (modify)
**What changes:** Regenerate or verify current after docs copy changes.
**Pattern to follow:** Generated by `website/scripts/extract-docs-data.ts`.
**Why:** LLM-facing docs must not keep stale `claude --agent` guidance.

### website/public/llms-full.txt (modify)
**What changes:** Regenerate or verify current after docs copy changes.
**Pattern to follow:** Generated by `website/scripts/extract-docs-data.ts`; platform labels must remain readable after JSX stripping.
**Why:** Full LLM docs output is an external documentation surface.

## Acceptance Criteria
- [ ] AC1: PlatformSwitcher shows Codex as selectable and no longer marks Codex as disabled or "soon"; Cursor, Copilot, Windsurf, and Cline remain disabled.
- [ ] AC6: User-facing MDX prose and code examples no longer instruct users to run `claude --agent ...`; they use `ana run ...` unless intentionally discussing platform internals.
- [ ] AC7: README no longer claims Claude Code exclusivity and opens with the locked product positioning: "Anatomia is a CLI that runs every code change through a five-agent pipeline — scope, spec, contract, build, and independent verification. It works with Claude Code and Codex."
- [ ] AC8: README quickstart uses `ana run setup` and `ana run`, and the "Works with" section states Claude Code and Codex support while preserving the broader markdown-aware tool claim.
- [ ] AC9: Landing page copy includes Codex in native pipeline support, and homepage tree diagrams stop presenting `.claude/skills/` as the canonical skill location.
- [ ] AC10: `AudienceCards` no longer says installation requires Claude Code only.
- [ ] AC15: `verifying-changes.mdx` frontmatter description and examples use `ana run verify` / `ana run build`.
- [ ] AC16: Concept page prose is platform-neutral in `pipeline.mdx`, `toolbelt.mdx`, and `skills.mdx`.
- [ ] AC18: Reference page path displays and GitHub URLs are not changed solely for platform conditionality.
- [ ] Tests pass with the website test command.
- [ ] Website build succeeds from `website/`.
- [ ] Root test baseline still passes after all phases.
- [ ] New docs enforcement tests cover the migrated command surface and switcher state.

## Testing Strategy
- **Unit tests:** Create `website/lib/__tests__/docs-platform-content.test.ts`. Use `readFileSync` against README, MDX, and copy/component files. Assert exact strings where the product contract is explicit, and use broad absence checks only for migrated user-facing files.
- **Integration tests:** Run `(cd 'website' && pnpm run build)` to validate MDX, internal links, generated docs data, search index, LLM files, and Next build.
- **Edge cases:** Test that `claude --agent` remains blocked in the migrated user-facing docs set, not in CLI source or internal docs. Test that Codex is enabled while the four unsupported future platforms remain disabled. Test generated `llms.txt` and `search-index.json` do not retain stale Verify/Quickstart descriptions.

## Dependencies
- Phase 1 depends on current CLI behavior already shipped in `packages/cli/src/commands/platform.ts`, `packages/cli/src/commands/run.ts`, and `packages/cli/src/commands/init/state.ts`.
- Node 22+ and pnpm workspace dependencies must already be installed.
- No package metadata edits are in scope.

## Constraints
- Do not change `packages/cli/package.json`.
- Do not change dynamic reference page source paths or GitHub URLs solely for platform conditionality.
- Do not alter `PlatformProvider` cookie/default behavior.
- Preserve existing website object shapes in `website/lib/copy.ts`.
- In JSX text content, use `&apos;` for apostrophes.
- Keep README concise. Detailed platform setup belongs to Phase 2.

## Gotchas
- `ForPlatform` inside fenced code blocks will not work. If Phase 1 touches conditional docs at all, wrap the whole block outside the fence.
- MDX lint/build will catch unescaped JSX apostrophes.
- `website/scripts/extract-docs-data.ts` writes both `website/data/docs/search-index.json` and the public docs assets. Build may update generated files after editorial changes.
- Root `pnpm run test -- --run` currently replays some cached website logs from a worktree path; the summary is the reliable baseline.
- `.ana/ana.json` has an existing local diff adding `"setupPhase": "complete"`. Do not revert it.

## Build Brief

### Rules That Apply
- Use `ana run` as the public command surface; only mention platform-native commands when explicitly discussing internals.
- Keep skills canonical at `.ana/skills/`; platform skill dirs are delivery/symlink details.
- Source-content tests are acceptable here because documentation text and switcher state are the behavior.
- Always pass `--run` to Vitest in non-interactive contexts.
- In JSX text content, use `&apos;` for apostrophes.
- Preserve local imports and object shapes in website TypeScript files.

### Pattern Extracts
`website/components/docs/layout/PlatformSwitcher.tsx:14`

```tsx
const platforms: PlatformOption[] = [
  { id: "claude-code", label: "Claude Code", disabled: false },
  { id: "cursor", label: "Cursor", disabled: true },
  { id: "codex", label: "Codex", disabled: true },
  { id: "windsurf", label: "Windsurf", disabled: true },
  { id: "copilot", label: "Copilot", disabled: true },
  { id: "cline", label: "Cline", disabled: true },
];
```

`packages/cli/src/commands/platform.ts:54`

```ts
/**
 * Generate a user-facing agent invocation string.
 *
 * Maps agent suffixes to `ana run` syntax:
 * - `agentCommand('build')` → `'ana run build'`
 * - `agentCommand('')` → `'ana run'` (Think agent)
 *
 * Returns plain text — callers apply chalk or backtick formatting.
 *
 * @param agentSuffix - Agent suffix (e.g. 'build', 'plan', '')
 * @returns The invocation string
 */
export function agentCommand(agentSuffix: string): string {
  if (agentSuffix === '') {
    return 'ana run';
  }
  return `ana run ${agentSuffix}`;
}
```

`packages/cli/src/commands/init/state.ts:981`

```ts
console.log(chalk.green(`✓ Skills → ${getSkillsDirRel()}/ (${manifest.length} skills)`));
console.log(`    ${chalk.gray('Core:')}      ${coreSkills.join(', ')}`);
if (conditionalSkills.length > 0) {
  console.log(`    ${chalk.gray('Detected:')}  ${conditionalSkills.join(', ')}`);
}
```

`packages/cli/src/commands/init/state.ts:1073`

```ts
console.log('  Next:');
if (isNonNode && !initTestCmd) {
  console.log(chalk.cyan(`    ${agentCommand('setup')}`) + '       Configure commands + enrich context (~10 min)');
  console.log(chalk.cyan(`    ${agentCommand('')}`) + '             Start working (after setup)');
} else {
  console.log(chalk.cyan(`    ${agentCommand('')}`) + '             Start working (Ana knows your stack)');
  console.log(chalk.cyan(`    ${agentCommand('setup')}`) + '       Enrich with your team\'s knowledge (optional, ~10 min)');
}
```

### Proof Context
- `README.md`: Two old build concerns. One notes README detection has explicit filename variants; not relevant to content migration. One notes a prior documentation contract/spec section-count mismatch; relevant as a reminder to keep this contract values resolved.
- `website/content/docs/using-ana-setup.mdx`: Prior link and apostrophe concerns; relevant because this phase edits JSX text in that file.
- `website/content/docs/concepts/pipeline.mdx`: Existing concern about `PipelineDiagram` descriptions; do not refactor the diagram for this scope.
- `website/lib/copy.ts`: Existing concerns about stale landing links/clickable copy; when editing landing copy, avoid preserving stale claims if encountered nearby.
- No active proof findings for other affected files.

### Checkpoint Commands
- After switcher and copy edits: `(cd 'website' && pnpm vitest run lib/__tests__/copy.test.ts lib/__tests__/docs-platform-content.test.ts)` — Expected: 21 tests pass after the new 15-test enforcement file is added.
- After all Phase 1 changes: `(cd 'website' && pnpm run build)` — Expected: MDX compiles, internal links validate, generated docs assets update, and 219 static docs/proof/reference pages build after Phase 2 adds the new guide; Phase 1 alone may remain 218 pages.
- Lint: `(cd 'website' && pnpm run lint)`
- Final baseline after all phases: `pnpm run test -- --run` — Expected: 139 existing test files plus 1 new website test file; 3182 passing tests and 2 skipped tests if the new file contains 15 tests.

### Build Baseline
- Current tests: 3167 passed, 2 skipped
- Current test files: 139 passed
- Command used: `pnpm run test -- --run`
- Website baseline: 68 tests in 10 files
- After build: expected 3182 passing tests, 2 skipped, in 140 files
- Regression focus: README positioning, Quickstart commands, PlatformSwitcher disabled state, website generated docs assets, docs concept pages with JSX text
