docs: lead the README with the measurement, not the mascot

[singhharsh1708]

Why

GitHub traffic says the README is the entire funnel and it isn't converting: 13 unique visitors read the Overview; every other path got exactly 1 view. Nobody reaches the docs site, the releases, or the code. Meanwhile the one claim no competing tool can make — measuring a skill's standing token cost before you install it — was the fourth paragraph, below a 240px mascot, six badges, and two analogies ("like npm, like Docker, like ESLint") that place the project in a familiar category rather than apart from it.

Three drafts were written against different strategic angles (measurement-first, pain-first, trust-first) and scored by independent reviewers on skim-conversion, factual accuracy against this repo, and differentiation. Measurement-first won all three, and the best elements of the other two are grafted in.

What changed

The first screen is now: the claim, the commands, real compile output with the ℹ standing-cost line, then a heading that says why that line makes this a compiler rather than a converter. The status-quo-vs-kitbash diagram moves up under "Why not a sync script?" — the reader's actual objection, answered where they have it. preview is shown before install, since reading a stranger's skill before it touches your disk is a differentiator that was previously invisible above the fold.

Corrections found while restructuring

The pitch is honest measurement, so a wrong number in the pitch is a real bug. The review caught six:

• The compile output was not real. The draft (and the framing of the old demo) implied a bare repo emits four files. It emits one — only agentsmd self-detects. The block is now output captured verbatim from an actual run, labelled with the repo shape that produces it, and keeps its trailing "7 more target(s) available" line.
• 47× was misattributed. It is a separate unmanifested fixture (review-checklist, 19 vs 885), not prereview with its manifest removed. prereview is 40 vs 560 = 14×.
• ~5,044 is the instruction body, not the standing cost. It compiles to ~5,101 standing on an eager target — the number compile actually prints. Both are now stated.
• npm run bench only works inside packages/cli — there is no root package.json. The old text told people to run it at the root.
• "The most-starred skill on GitHub ships twenty hand-maintained copies" — unsourced, with an unverifiable superlative and count. Replaced with the same argument stated without the unbacked specifics.
• The diagram claimed "9 native outputs" per run. Compile emits per detected target.

Badges

Dropped GitHub stars and npm monthly downloads. Both actively mislead: downloads track publish-day mirror replication (every spike lands exactly on a publish date, decaying to zero between), and a single-digit star count is the first thing a skeptical reader anchors on. Kept npm version, CI, target count, license; added runtime_deps-0, which is a real and unusual property.

Trust section

The four hard-gate lints become a scannable table, followed by their documented limits stated plainly (c=curl; $c url | sh defeats a regex on prose — these are heuristics plus hard gates, not proof) and the 0.15.0 self-audit as evidence, linked to the A1–A10 regression tests.

Verification

Every relative link resolves, both anchors match real headings, the terminal output is captured from real runs in both repo shapes, preview was confirmed to work on an uninstalled gh: source and write nothing, and the benchmark figures were checked against docs/benchmarks/README.md. Suite green, site/build.mjs --check current. Docs-only — no source changes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
kitbash	Ready	Preview	Aug 7, 2026 12:52pm