README has no run steps or CLI example (#15)

[Param-Harrison]

Closes #15

Summary

Adds a ## Run it section to README.md covering bun install, bun run dev (served at http://localhost:3200, demo data seeded on first run), and a CLI example (bun run src/cli.ts groups). Also adds tests/readme.test.ts, a docs-drift test that keeps these steps accurate.

Acceptance criteria

AC	Evidence (command / test)	Result
AC-1	bun test tests/readme.test.ts › README has a Run it section with install, dev and CLI commands	pass
AC-2	bun test tests/readme.test.ts › documented CLI example lists the demo groups (runs bun run src/cli.ts groups with SPLITBILL_DB=:memory:; exits 0, prints goa-trip and flat-4b)	pass
AC-3	bun test tests/readme.test.ts › README dev URL port matches the server default (README port 3200 matches process.env.PORT ?? 3200 in src/server.ts)	pass
AC-4	make check: tsc --noEmit clean, bun test 29 pass / 0 fail, all 9 skills valid	pass

Non-goals respected

git diff --name-only main...HEAD lists only README.md and tests/readme.test.ts.

• NG-1: nothing under src/ changed.
• NG-2: package.json, bun.lock and Makefile are untouched.
• NG-3: the only README change is the new ## Run it section, inserted between ## What it does and ## Stack. No existing lines changed.
• NG-4: no protected paths edited.
• NG-5: the CLI test uses SPLITBILL_DB=:memory:. It never touches splitbill.sqlite.

The test that bites

• Test: tests/readme.test.ts › README has a Run it section with install, dev and CLI commands and README dev URL port matches the server default
• Fails on main: bun test tests/readme.test.ts → 1 pass, 2 fail (expect(start).toBeGreaterThanOrEqual(0), received -1: ## Run it not found)
• Passes here: bun test tests/readme.test.ts → 3 pass, 0 fail, 11 expect() calls

The CLI test passes either way, as expected: it checks the existing CLI, not README text.

Gate line

.factory/gates.sh: FACTORY_GATES: status=GREEN passed=3 failed=0 skipped=1 failed_gates=audit

audit is advisory and not part of check. It flags existing hono advisories, and this PR leaves package.json and bun.lock unchanged.

Protected paths touched

none

Reviewer findings addressed

• Non-blocking: one make check run during review failed the README-section assertions. Cause: the reviewer and verifier ran at the same time in the same worktree, and the verifier had reverted README.md to main for its revert test. The test correctly caught the missing section, so this was not a flake. Every later run passed. See the verdict comment on README has no run steps or CLI example #15 for details.

Human checklist

• AC table has real evidence, not placeholders
• Non-goals respected
• Gate line is GREEN
• Protected paths are "none", or the change to them is expected and reviewed
• I ran the test that bites myself

🤖 Generated with Claude Code