docs: rewrite README hero + replace the scan demo GIF (demonstrate, then argue)

[rpatricksmith]

Summary

Rewrite the README hero (top screenful) and replace the scan demo GIF so the README demonstrates then argues — a GIF + a number + the install command above the fold — on our axis (accountability/verification), the way RepoWise's README converts on theirs. The README copy ships immediately (no code); the killer GIF is gated on the scan UX work.

Why it matters

We open with philosophy and bury the demo; RepoWise opens with a banner, a one-line value prop, a spec bar, a number, and a GIF before any prose — a big part of the 2.2k-vs-32-star gap is this first screenful. Our README is only 137 lines — cheap to rewrite, high ROI.

Current state (confirmed against the files)

• README.md:1-19: wordmark + 3 plain badges, then paragraph 1 (5 clauses before you know what to do), then paragraph 2 (pure manifesto: "The cost of building is near zero…"), then a ## Scan any project in 10 seconds heading, then the GIF at ~line 13, then npx anatomia-cli scan .. The GIF is pushed below ~13 lines of prose; no quantified hook in the hero.
• assets/demo/dub-scan.tape: 28 lines, the recording is literally Type "ana scan ." → Enter → Sleep 25s over the single frozen ora spinner (scan.ts:436). It demos nothing.
• Reusable positioning (verified): project-context.md:9 ("Other harnesses are prompt libraries the agent can ignore; Anatomia has an engine it can't skip… Verify never reads Build's report… every run leaves a proof"); package.json:3 ("Verified AI development. Scan your project, generate context, verify every change through a five-agent pipeline."); website/lib/copy.ts:54-79 ("The coding harness with an engine.", "free, local, 2–5s", "Nothing leaves your machine."). The web funnel already has the GIF+number instinct (COMPETITIVE_RESEARCH_repowise.md:468) — we're porting it to the README.
• Badges: have npm/CI/MIT; homepage anatomia.dev; no Discord/social (omit, don't fake).

Proposed new hero (lead with what + number + command)

Centered <div> block (renders cleanly on GitHub), in order:

1. # Anatomia
2. One-line value prop (accountability axis): "Verified AI development. Scan your codebase in seconds — then run every change through a 5-agent pipeline that leaves a proof you can audit."
3. Spec bar: "Deterministic scan · No API key · 5-agent pipeline · Independent verification · A proof per change"
4. LIVE DEMO badge → anatomia.dev; npm / CI / MIT / Node≥22 badges (for-the-badge style).
5. In-page nav: Scan · Pipeline · Proof · Install · How it compares · Works with.
6. --- then ## Scan your codebase in seconds + the GIF (width="100%", descriptive alt text) + npx anatomia-cli scan . + "Deterministic, no API key, nothing leaves your machine."
7. Relocate the two philosophy paragraphs into a ## Why an engine, not a prompt section below the GIF, leading with project-context.md:9. The "cost of building the wrong thing" line stays as the closing argument, not the opener.

Comparison table — "How it compares" (accountability axis, by category, not petty)

Compare categories (not named competitors — stay classy): "Prompt libraries / rule packs" vs "Read-only code intelligence" vs Anatomia. Rows where only Anatomia is "yes": CLI-enforced (agent can't skip), independent verification (Verify never reads Build's report), sealed contract per change, proof per change, compounding audit trail. Plus two broadening rows: zero-config/no-key scan, and "detects how your team actually writes." A <sub> footnote defines "read-only code intelligence" = indexes & answers but never gates a change.

The new GIF + .tape changes

Storyboard (≈10s, from DISTRIBUTION_AND_SCAN_UX.md B4): npx anatomia-cli scan . → pre-scan counts snap in → 7-line engine ticker walks down → lands on "How your team writes" → closes on "Scanned in 7.2s — deterministic, no API key." → CTA, loop.

.tape rewrite (assets/demo/dub-scan.tape): remove Sleep 25s; Type "npx anatomia-cli scan ."; record the real live run (Sleep ~9s for the actual scan + a ~1s hold on the money shot); tighten Height 900→760; keep Width 1200, FontSize 18, Catppuccin Mocha (dark, matches our cyan/green). No gradients/figlet (gaudy undermines a trust product). Still must record on a full dub clone (header lines 4-6) so the git/conventions lines populate. (Ignore the stale worktree copy at .ana/worktrees/.../dub-scan.tape — root is canonical.)

Dependencies / sequencing (3 GIF tiers)

1. Now (no code): ship the README copy + structure + comparison table + relocated philosophy against the existing GIF. This is the bulk of the conversion win and gates on nothing.
2. Interim: re-record after the "How your team writes" slice ships (zero-engine-change, its own issue) — gets the money shot, no live ticker.
3. Killer: re-record after full feat: live, animated scan progress — make the engine visible (ana scan) #299 (engine onProgress + scan-reporter.ts + theme.ts + log-update) — the full B4 storyboard.

• The <!-- mcp-name: dev.anatomia/anatomia --> line-1 handle waits on ana mcp.

Integration points

• README.md — replace hero (lines 1-19), add ## How it compares, relocate philosophy, add anchor-matching headings. prepublishOnly (packages/cli/package.json) copies the root README into the npm package, so npm's listing updates automatically.
• assets/demo/dub-scan.tape — rewrite per above.
• assets/demo/dub-scan.gif — regenerate via vhs on a full dub clone when the scan UX lands.
• Badges — inline shields.io URL strings; no asset generation.
• No code changes for copy/table; the GIF is the only piece gated on engine work.

Acceptance criteria

1. Above the fold (first GitHub screenful, before any prose) shows the GIF + a quantified hook ("seconds"/"5-agent"/"no API key") + the npx anatomia-cli scan . command.
2. A one-line accountability-axis value prop appears within the first ~8 lines; the "engine it can't skip" reasoning is preserved but relocated below the GIF.
3. Spec bar + in-page nav render on GitHub (centered <div>, working anchors).
4. The comparison table includes deterministic/no-key scan, independent verification, sealed contract, proof-per-change, audit trail — with ≥4 accountability rows true only for Anatomia.
5. dub-scan.tape contains no Sleep 25s and types npx anatomia-cli scan .; the regenerated GIF shows a changing scan (ticker and/or "How your team writes") + the no-key/7.2s close, not a static spinner.
6. Badges resolve; the npm-published README (via prepublishOnly) matches the repo README.

Effort

• README copy + table + relocation: small — ~1–2 hours on a 137-line file, no code. Ship now in one PR.
• Tape rewrite: ~20 min, but the useful GIF is gated on the scan UX.
• Killer GIF = scan UX (feat: live, animated scan progress — make the engine visible (ana scan) #299) + ~1–2h recording. Interim GIF = the "How your team writes" slice (~0.5d its own issue) + ~1h recording.

Bottom line: the README rewrite is the ship-today half; the GIF is the gated half — sequence the copy now, swap the GIF when the scan UX lands.

[stevesagronegocios673-ux]

Quick README-conversion note after reading the issue, current README.md, assets/demo/dub-scan.tape, and packages/cli/package.json: I would split the PR more aggressively than the issue text implies.

The immediate copy win is not just moving the GIF upward. It is making the first screen answer three questions before the philosophy starts:

1. What do I run? npx anatomia-cli scan .
2. What happens locally and without keys? stack/convention/pattern scan, no API key, nothing leaves the machine.
3. Why is this different from prompt packs? the later pipeline produces sealed artifacts and independent verification.

That suggests a clean ship-now README slice:

• Keep the existing GIF for now, but caption it honestly as the current scan demo; do not claim the future 7.2s ticker until the GIF is regenerated.
• Put the command directly under the one-line value prop, before badges/nav/table. On GitHub mobile, badges plus nav can consume the whole first viewport if the command waits until after them.
• Move the comparison table after the command/GIF block, not before it. The table is a conviction-builder; the command is the conversion event.
• Preserve the current strong line “Other harnesses are prompt libraries. This one has an engine.”, but use it as the first sentence of Why an engine, not a prompt, not as the first explanation a cold reader sees.
• Keep prepublishOnly in mind: the root README is copied into packages/cli/README.md, so npm users will see the same hero. That makes overly wide HTML tables/badge rows riskier than they look in the repo alone.

If useful, I can do this as a compact $5 copy pass: paste-ready README hero, above-the-fold order, comparison table wording, and the exact dub-scan.tape edit list. Docs/copy only; no PR, no regenerated GIF in that pass. If that scope and $5 price works, confirm here and I’ll send payment options.