# Verify Report: README Terminal Demo

**Result:** PASS
**Created by:** AnaVerify
**Date:** 2026-05-27
**Spec:** .ana/plans/active/readme-terminal-demo/spec.md
**Branch:** feature/readme-terminal-demo

## Pre-Check Results

```
=== CONTRACT COMPLIANCE ===
  Contract: .ana/plans/active/readme-terminal-demo/contract.yaml
  Seal: INTACT (hash sha256:2184442cfbad300cf7516c4e703729ec81c4d19593ec7053cd7143ad8e5700d4)
```

Seal status: **INTACT**

Tests: 3049 passed (2981 CLI + 68 website), 0 failed, 2 skipped. Build: pass (turbo cache hit). Lint: pass (warnings only — pre-existing, not introduced by this build).

## Contract Compliance

No `@ana` tags expected — testing strategy is build-only (no production code changes, no new tests). All assertions verified by source inspection.

| ID   | Says                                           | Status       | Evidence |
|------|------------------------------------------------|--------------|----------|
| A001 | The old static scan output is removed from the README | ✅ SATISFIED | `grep -c "Here's what you'll see" README.md` returns 0 |
| A002 | The inbox-zero scan example no longer appears in the README | ✅ SATISFIED | `grep -c "inbox-zero" README.md` returns 0 |
| A003 | The README embeds the demo GIF with an image tag | ✅ SATISFIED | README.md line 11: `<img alt="ana scan running on dub...` |
| A004 | The demo image displays at 600 pixels wide | ✅ SATISFIED | README.md line 11: `width="600"` present in img tag |
| A005 | The demo image points to the recorded GIF file | ✅ SATISFIED | README.md line 11: `src="assets/demo/dub-scan.gif"` |
| A006 | The demo image has descriptive alt text | ✅ SATISFIED | README.md line 11: `alt="ana scan running on dub — detecting TypeScript, Next.js, Prisma with 80 models, auth, AI, payments, and contributor activity"` |
| A007 | The npx install command appears in the README | ✅ SATISFIED | README.md line 14: `npx anatomia-cli scan .` inside bash code block |
| A008 | The README links to the docs site for more examples | ✅ SATISFIED | README.md line 17: `https://anatomia.dev/docs` |
| A009 | The examples link uses inviting text | ✅ SATISFIED | README.md line 17: `See more examples →` |
| A010 | The VHS tape file sets the terminal output to GIF format | ✅ SATISFIED | `assets/demo/dub-scan.tape` line 16: `Output dub-scan.gif` |
| A011 | The tape file configures terminal width for full scan output | ✅ SATISFIED | `assets/demo/dub-scan.tape` line 18: `Set Width 1200` |
| A012 | The tape file uses the dark terminal theme | ✅ SATISFIED | `assets/demo/dub-scan.tape` line 21: `Set Theme "Catppuccin Mocha"` |
| A013 | The tape file types the scan command, not the npx variant | ✅ SATISFIED | `assets/demo/dub-scan.tape` line 25: `Type "ana scan ."` |
| A014 | The tape file documents that a full clone is required | ✅ SATISFIED | `assets/demo/dub-scan.tape` lines 5-6: comments document full clone requirement and explain shallow clone limitation |
| A015 | The demo GIF file exists in the assets directory | ✅ SATISFIED | `ls -la assets/demo/dub-scan.gif` — 155KB, GIF89a, 1200x1000, 615 frames animated |
| A016 | The project builds without errors | ✅ SATISFIED | `pnpm run build` exits 0, both packages successful |
| A017 | All existing tests continue to pass | ✅ SATISFIED | `pnpm run test -- --run` exits 0, 3049 tests pass, 0 fail |

## Independent Findings

**Predictions resolved:**

1. "GIF is placeholder" — Not found. Real GIF89a, 615 frames, 155KB, 1200x1000. Generated by VHS on a full dub clone.
2. "Tape file issues" — Partially confirmed. The comment on line 14 says "The Output path is relative to the tape file location" but VHS actually resolves `Output` relative to CWD, not the tape file. Minor documentation inaccuracy — doesn't affect functionality since the usage instructions correctly say to cd into the dub clone.
3. "README ordering wrong" — Not found. Heading → img → code block → CTA in correct order.
4. "Arrow character mismatch" — Not found. Uses unicode `→` as specified.
5. "Old content removal incomplete" — Not found. Both marker strings return 0 grep matches.

**Surprise finding:** The GIF uses a relative `src` path (`assets/demo/dub-scan.gif`). This renders correctly on GitHub (which resolves relative paths within the repo). However, the `prepublishOnly` script copies root `README.md` to `packages/cli/README.md` for npm, and `"files": ["dist"]` doesn't include the assets directory. The GIF will appear as a broken image on npmjs.com. This is AC8 in the spec but was not codified as a contract assertion, so it doesn't affect the PASS/FAIL verdict — but it's a real issue for the next publish.

**What I didn't predict:** The tape file is clean and minimal (28 lines). No over-building — no extra VHS directives, no unnecessary configuration. The builder followed the spec precisely.

## AC Walkthrough

- **AC1:** The README hero section contains an animated GIF showing `ana scan .` running on dub, displaying the full scan output including the Intelligence section. — ⚠️ PARTIAL — GIF exists, is animated (615 frames), and was recorded via VHS on dub. I verified the first frame shows the Catppuccin Mocha theme and command prompt. I cannot verify the Intelligence section content from a static frame extraction — the GIF must be viewed animated in a browser. The 155KB size and 615 frame count are consistent with a full scan recording (~25s at ~25fps).
- **AC2:** The static code block that previously showed inbox-zero scan output is removed. — ✅ PASS — `grep -c "inbox-zero" README.md` returns 0. `grep -c "Here's what you'll see" README.md` returns 0.
- **AC3:** The `npx anatomia-cli scan .` command appears below the GIF, not above it. — ✅ PASS — README.md: img tag at line 11, npx command at line 14. Below confirmed.
- **AC4:** The GIF is embedded via `<img>` tag with `alt` text and `width="600"`. — ✅ PASS — README.md line 11: `<img alt="..." width="600" src="...">`.
- **AC5:** `assets/demo/dub-scan.tape` exists and is a valid VHS tape file that reproduces the recording. — ✅ PASS — File exists, 28 lines, contains all required VHS directives (Output, Set Width/Height/FontSize/Theme/TypingSpeed/Padding, Type, Enter, Sleep). VHS validate not run (VHS not available in this env), but syntax matches charmbracelet spec.
- **AC6:** `assets/demo/dub-scan.gif` exists and is under 500KB. — ✅ PASS — 155KB, well under limit.
- **AC7:** The GIF renders correctly on GitHub (animated, autoplaying, looping). — -- UNVERIFIABLE — Requires push to GitHub and browser verification. The `<img>` tag format with relative path is standard for GitHub GIF rendering.
- **AC8:** The GIF renders correctly on npmjs.com via `<img>` tag. — ❌ FAIL — Relative path `assets/demo/dub-scan.gif` will not resolve on npm. The package `files` array is `["dist"]` — assets are not bundled. npm needs an absolute URL (e.g., `https://raw.githubusercontent.com/anatomia-dev/anatomia/main/assets/demo/dub-scan.gif`).
- **AC9:** A "See more examples" link points to `https://anatomia.dev/docs`. — ✅ PASS — README.md line 17: `[See more examples →](https://anatomia.dev/docs)`.
- **AC10:** No build errors — `pnpm run build` passes. — ✅ PASS — Exit 0, both packages built.
- **AC11:** No test regressions — `pnpm run test -- --run` passes. — ✅ PASS — 3049 passed, 0 failed, 2 skipped.

## Blockers

None. AC8 fails (npm image rendering) but this is not a contract assertion — it's a spec AC that was intentionally left out of the contract. The contract has 17 assertions and all are SATISFIED. The npm rendering issue is documented in Findings for future resolution before next publish.

Checked for: unused exports in new files (no new source files — only README, tape, GIF), unhandled error paths (no code paths — documentation change), external state assumptions (relative GIF path — noted as finding), spec gaps (npm rendering gap — noted).

## Findings

- **Code — Tape comment documents wrong Output path behavior:** `assets/demo/dub-scan.tape:14` — Comment says "The Output path is relative to the tape file location" but VHS resolves Output relative to CWD. The usage instructions above (lines 10-11) correctly tell you to cd into dub and run vhs with an absolute path to the tape, so the recording workflow isn't broken — just the explanatory comment is inaccurate.
- **Upstream — GIF uses relative src, breaks on npmjs.com:** `README.md:11` — `src="assets/demo/dub-scan.gif"` works on GitHub (resolves relative paths in-repo) but npm renders README without bundled assets. The `prepublishOnly` copies README to the package dir but `"files": ["dist"]` excludes `assets/`. Fix before next publish: use `https://raw.githubusercontent.com/anatomia-dev/anatomia/main/assets/demo/dub-scan.gif` or add assets to the package.
- **Upstream — AC8 not codified in contract:** The spec lists AC8 (npm rendering) but the contract has no assertion for it. The planner chose not to include it — possibly because it requires a live npm publish to verify. Worth noting: the gap means the npm rendering issue is invisible to the verification pipeline.
- **Upstream — prepublishOnly copies README but not assets:** `packages/cli/package.json` — The prepublish script copies `../../README.md` and `../../CHANGELOG.md` but doesn't copy `../../assets/`. This was fine when README had no local image references. Now that it does, the script needs updating OR the image path needs to be absolute.

## Deployer Handoff

Three files changed: README.md (hero section replacement), `assets/demo/dub-scan.tape` (new), `assets/demo/dub-scan.gif` (new, 155KB binary).

**Before merging:** The GIF will render on GitHub immediately. It will NOT render on npmjs.com with the current relative path. If you're publishing to npm soon, change the `src` to an absolute GitHub raw URL first. If npm publish is distant, merge now and fix the path before publish.

**Re-recording the GIF:** If the scan output format changes, clone dub fresh (`git clone https://github.com/dubinc/dub.git`), build `ana`, cd into the dub clone, run `vhs /path/to/anatomia/assets/demo/dub-scan.tape`, copy the output GIF to `assets/demo/`.

**Lint warnings:** 3 pre-existing warnings (2 in website Hero.tsx, 1 in cli git-operations.ts) — none introduced by this build.

## Verdict

**Shippable:** YES

All 17 contract assertions SATISFIED. Build passes. Tests pass (3049/3049). No regressions. The implementation is precise — tape file, GIF, and README all match the spec exactly. The npm rendering gap (AC8) is real but was not included in the contract, and the spec explicitly anticipated VHS/dub might not be available. The builder had both and delivered a genuine recording. The one tape comment inaccuracy is trivial. Ship it.
