Repository navigation
README has no run steps or CLI example #60
Description
Where
README.md
What's missing or wrong
The README describes what splitbill is but never says how to actually run
it: no install step, no bun run dev command, no port number, and no
example of using the CLI (splitbill groups, splitbill balances <group>,
splitbill export <group>). A new contributor has to read package.json
and src/cli.ts to figure out how to start the app.
Expected
A "Run it" section with:
bun installbun run devand the URL it serves (http://localhost:3200)- One CLI example, e.g.
bun run src/cli.ts groups
Done when
The README has these steps and they work when followed on a clean clone.
Activity
Param-Harrison commentedon Oct 8, 2026
Triage
Disposition: proceed
Type: docs
Risk: low
Confidence: 0.9
Done when: README.md has a "Run it" section with
bun install,bun run dev(http://localhost:3200) and a CLI example (bun run src/cli.ts groups) that work on a clean clone.Files expected: README.md
Gate level: full
Param-Harrison commentedon Oct 8, 2026
Plan (rev 1)
Goal: Add a "Run it" section to
README.mdwith the install, dev-server and CLI commands that work on a clean clone.Acceptance criteria
README.mdhas a## Run itheading containingbun install— checked bybun test tests/readme.test.ts("README has a Run it section with bun install")bun run devand the URLhttp://localhost:3200, and both match the repo:package.jsonhas adevscript andsrc/server.tsdefaultsPORTto3200— checked bybun test tests/readme.test.ts("README dev command and URL match package.json and server default port")bun run src/cli.ts groups(and mentionsbalances <group>/export <group>), andsrc/cli.tsexists and handles thegroupscommand — checked bybun test tests/readme.test.ts("README CLI example points at a real CLI command")make checkNon-goals (binding — a diff that crosses one fails verify)
src/,public/,package.json,bun.lockorMakefile— the README documents current behaviour, it does not change it.src/auth/**,.factory/**,.claude/**,.agents/**,.github/**) or toAGENTS.md/DEMO.md.Files to touch
README.md— insert a## Run itsection (after "What it does" or "Stack"):bun install(ormake install),bun run devserving http://localhost:3200 (notePORT/SPLITBILL_DBenv overrides and that demo data is seeded on first run), and a CLI examplebun run src/cli.ts groups, withbalances <group-id>/export <group-id>shown (e.g.bun run src/cli.ts balances goa-trip).tests/readme.test.ts— new test file.Tests to write first
tests/readme.test.ts› "README has a Run it section with bun install"tests/readme.test.ts› "README dev command and URL match package.json and server default port"tests/readme.test.ts› "README CLI example points at a real CLI command"Repo skills to apply
none
Risk: low
Docs-only change plus a new test file, no schema or API-shape change and no protected path —
.factory/charter.mdrisk tiers, low: "docs-only, test-only, or a change confined to a single non-protected module with no schema or API-shape change."Gate level: full
Low risk: eligible for auto-approve if the toggle is on. Otherwise, reply
/factory approveto proceed, or/factory revise <what to change>.Param-Harrison commentedon Oct 8, 2026
Status
Stage: build — finished
Progress: 3/5
Elapsed: n/a
Gate line:
FACTORY_GATES: status=GREEN passed=3 failed=0 skipped=1 failed_gates=auditAdded a
## Run itsection to README.md (bun install, bun run dev on http://localhost:3200, the CLI's groups/balances/export commands). The 3 tests in tests/readme.test.ts failed before the change and pass after. The optionalauditgate flags the existing pinned dependencies, which this change does not touch.factory: build #60
Param-Harrison commentedon Oct 8, 2026
Verdict: pass
Acceptance criteria evidence
bun test tests/readme.test.ts→ "README has a Run it section with bun install" passes (3 pass, 0 fail); fails with README.md reverted tomain(expect(section).not.toBe("")→Expected: not "").bun test tests/readme.test.ts→ "README dev command and URL match package.json and server default port" passes; fails onmain's README (Expected to contain: "bun run dev",Received: ""). Reviewer confirmedpackage.jsondev=bun run src/server.tsandsrc/server.tsserves onNumber(process.env.PORT ?? 3200).bun test tests/readme.test.ts→ "README CLI example points at a real CLI command" passes (runsrun(["groups"], db)on an in-memory seeded DB and findsgoa-trip); fails onmain's README (Expected to contain: "bun run src/cli.ts groups",Received: "").d5a2783c, equal toHEAD^{tree}):FACTORY_GATES: status=GREEN passed=3 failed=0 skipped=1 failed_gates=audit. Re-checked here:bun test→ 32 pass, 0 fail;bun x tsc --noEmit→ exit 0.The test that bites
tests/readme.test.ts› "README has a Run it section with bun install" (and the other two tests in the file) fail withREADME.mdrestored frommain(0 pass, 3 fail,expect(section).not.toBe(expected) — Expected: not ""), and pass here(
bun test tests/readme.test.ts→3 pass, 0 fail, 10 expect() calls).Reviewer findings
tests/readme.test.ts:37: the test grepssrc/server.tssource for the literalprocess.env.PORT ?? 3200, so a harmless refactor (constant, spacing) would fail it. Brittle. Fix (optional): assert against a shared exported constant.tests/readme.test.ts:49: only thegroupscommand is executed; thebalances goa-tripandexportexamples are checked as README text only. Fix (optional): also assertrun(["balances","goa-trip"], db)and thatexportoutput looks like CSV.Neither is blocking.
Non-goals respected
NG-1: only
README.mdandtests/readme.test.tschanged; nothing undersrc/,public/,package.json,bun.lockorMakefile. NG-2: no protected paths,AGENTS.mdorDEMO.mdtouched. NG-3: the README change is a pure 20-line insertion between "What it does" and "Stack"; no existing lines rewritten.