fix: credibility pass — align docs/site/CLI with reality (0.11.0) - #91
Merged
Conversation
A staff-level review found the shipped surface contradicting itself, fatal for
a tool whose pitch is honest measurement. Every fix aligns surface with reality.
- the flagship number was reported three ways (compile ~517, preview ~507,
benchmark 560) because the permissions note and the adapter wrapper were
counted inconsistently. All three now report the true emitted-file cost (560);
preview renders exactly what compile writes.
- the measurement no longer fails --strict: it moved from the warnings array to
an informational note channel. --strict still fails on real warnings.
- stub commands cited already-passed milestones ("lands in v0.2" on a 0.10
build); now point at the roadmap, and --help lists them under a separate
Planned section instead of mixing with working commands.
- the bundled example advertised mode=gate while gate is unimplemented; now
mode=skill, runnable end to end.
- exit codes: unknown command = 2 (+ did-you-mean) not 1+help-dump; unbuilt = 7;
empty-repo test/lint = 0 to match compile/list.
- doctor: undetected targets show · not ✗ (reserved for real problems) + count.
- compile: partial fan-out shows how to enable more targets.
- site/docs: killed the fictional 1,480-token number, aligned quickstart blocks
to the real CLI, one tax figure, marked shipped-vs-planned skills, expanded KSF.
- added per-command --help, help <command>, did-you-mean, pluralization, token
units; removed -v (collides with verbose).
261 assertions. Number consistency verified across compile/preview/benchmark.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A staff-level review of the shipped product found the docs, site, and CLI contradicting each other — fatal for a tool whose entire pitch is honest measurement. Every fix here aligns the surface with reality; none is a new feature. All were verified against the real CLI before fixing.
The flagship-number bug (worst offender)
The standing-token cost — the one thing Kitbash uniquely measures — was reported three different ways for the same skill on the same target:
compilewarned ~517,previewshowed ~507, the benchmark said 560. Cause: the 0.9.0 permissions note and each adapter's own wrapper were counted inconsistently. All three now report the true cost of the emitted file (560), andpreviewrenders exactly whatcompilewrites.The measurement failed
--strictThe standing-cost report was in the same
warningsarray as real problems, socompile --strictexited 1 on the one bundled skill — the product punishing the number it exists to surface. It's now an informationalℹnote;--strictstill fails on genuine warnings (verified).The self-contradictions
--helplists them under a separate Planned section.mode = gatewhilegateis unimplemented → nowmode = skill, runnable end to end.Consistency + ergonomics
test/lint= 0 to matchcompile/list.doctor: undetected targets show·not✗(reserved for real problems) + an "N of 9" count.compile: a partial fan-out shows how to enable more targets (no more "2 targets" reading as a shortfall).--help,help <command>, did-you-mean, pluralization ("1 skill for 2 targets"), token units; removed-v(collides with verbose).261 assertions. Number consistency verified live across compile/preview/benchmark. This is the highest-ROI change on the project: ~15 edits that flip it from "impressive but self-contradicting" to something a stranger can trust.