documentation improvements

[the-simian]

Motivation

User is reading the README on npm and reacting: "a lot of this looks like LLM slop." Reviewer audits (review-the-nit + review-oss-marketing-bro) confirm the diagnosis: over-explained paragraphs, internal-lore references no outsider knows, seven-step pipelines crammed into one sentence, em dashes (CLAUDE.md forbids them), defensive caveats stacked five-deep, and a Testing section that reads like an auditor's report instead of a sales pitch.

User's target: README should be "this rules, here's how you use it" — snappy enough a human can scan it in 30 seconds and want to install. LLM-targeted detail (every overload, every pipeline step, every config knob, every mutation-survivor classification) moves to llms.txt.

Scope (three surfaces)

1. README.md — rewrite for human readers; cut slop; promote the differentiator above the fold; fix dead links.
2. llms.txt — absorb the technical detail moved out of README. Already exists as the canonical agent-orientation doc; this work expands it.
3. Demo prose — apply the same lens to kit intros, section headers, blurbs, and result strings. The cooking kit (most recent) is the biggest surface; geometry and data-storage need a pass too.

User-flagged items (concrete)

1. Dead Crouton demo link (README.md:31, 141). The "Settlers of Crouton" demo route was never built or has been cut; the README links #crouton and #/crouton to nothing. Cited only in source-code comments now. Either ship the demo or remove the links.
2. Scaling-functions use case not surfaced. The library is useful for scaling functions (the cooking demo's recipe machine is a live demo of this — slider scales a recipe, every ingredient translates). README and main-demo home page don't call this out as a use case.
3. Memoize feature isn't visible in the main-demo home page. forge's memoize config knob is real and useful; nothing in the demo shows it in action.
4. Cooking blurb is bloated (README.md:35). Three sentences with internal-lore Settlers-of-Crouton reference. User's preferred voice: "teaspoons, teacups, the usual suspects, but also international units, sugar comparisons, and more."
5. Testing section is LLM slop (README.md:199-207). User just wants: "comprehensive unit tests, fuzz via fast-check, mutation via Stryker" with the headline numbers. Per-file mutation breakdown + Stryker-disable-comment policy moves to llms.txt or TESTING.md.
6. Custom-dimension prefix convention is verbal diarrhea (README.md:143). The blockquote is also incoherent: the build-your-own example uses bare COUNT = 'count', then the blockquote tells kit authors not to use bare strings. Reader whiplash. Fix shape:
   • Update build-your-own example to use the namespaced form ('@mycorp/count' or similar)
   • Shrink the blockquote to one line that points at the demo
   • The convention should be demonstrated IN the demo, not explained in prose
7. The seven-step cross-dim pipeline at README.md:166 is the worst single sentence in the file (nine items in one comma-spliced run). Cut from README; move to llms.txt.
8. Em dashes at README.md:205 and demo/src/components/kits/cooking/sections/comparison-machine/index.tsx:41. CLAUDE.md forbids. Replace with semicolons or rephrase.

Reviewer consensus (review-the-nit + review-oss-marketing-bro)

Move to llms.txt (or TESTING.md / EXTENDING.md)

• Stryker-disable policy and per-file mutation breakdown (README.md:207)
• Custom-dimension prefix rationale long-form (README.md:143)
• linear(scale) tree-shake foot-gun warning (README.md:156)
• (string & {}) brand explanation (README.md:189)
• Cross-dim pipeline ordering (README.md:166)
• "Where 3.0.0-beta changes a row" prose (README.md:75); the table footnote is enough
• Validator return contract (README.md:185)
• 18.5k expect() count and per-file mutation breakdown

Hero is paying the price (oss-marketing-bro)

README.md:27 tagline is "Forge anything measurable. Not just physics." Two issues:

• "Not just physics" is a negation; negations don't sell, they defend
• The differentiator (cross-dimensional, one Coke ≈ N donuts) doesn't appear until the table at README.md:82 — three screens down on mobile

Proposal: lead with the differentiator. Something shaped like "One Coke ≈ 9.75 sugar cubes. A units library that does cross-dimensional conversion and catches dimension mismatches at compile time." The Coke number is the screenshot-worthy quotable; it belongs in pixel one.

"What this isn't" is momentum death (oss-marketing-bro)

Lines 63-72 are five negations stacked right after the Coke example landed the value. "Not a CLI" addresses a buyer who was never going to install anyway. Reframe positively ("ESM-only library, Node 22+, no peer deps; converts values, does not simulate") or delete and let the Install section carry the scope info.

Sections that are tight, leave alone

Hero badges, Quick start, the vs. convert-units table itself, tree-shaking measurement table, Install, the Settlers-of-Crouton cities-recipe example code (the good version of what the rest should sound like), config-options table, Development, Community, Extending, For agents, License.

Demo prose audit (initial findings)

demo/src/components/kits/cooking/index.tsx:58-65 — 90-word header <p> overstuffed with NIST-factor sidebar and "LARGER/SMALLER" caps that reads like an LLM proving it knows the topic.

demo/src/components/kits/cooking/sections/comparison-machine/index.tsx:70-76 — 60-word two-sentence intro doing the work the per-pill hint fields already do.

Geometry and data-storage kits need the same pass; haven't audited yet.

Acceptance criteria

• README rewrites: cooking blurb, Testing section, hero, "What this isn't", custom-dimension prefix note, dead Crouton links removed
• llms.txt absorbs the technical detail listed above
• No em dashes anywhere in README.md, llms.txt, or demo source
• Build-your-own example demonstrates the namespaced-dimension convention rather than explaining it in prose
• Demo: cooking kit intro + comparator intro tightened; geometry + data-storage prose audited
• Main demo surfaces scaling-functions use case + memoize feature
• No internal-lore references (Settlers-of-Crouton, etc.) in user-facing prose

Branch / commit shape

Branch: feat/documentation-improvements
Commit prefix: feat(docs) (per user's note)

[the-simian]

Additional findings (post-open)

README ↔ demo code parity (user notes)

The README's two illustrative code blocks (cities example at README.md:123-139 and handspan example at README.md:148-154) don't match what the actual demo page ships. The demo pages already have:

• demo/src/components/kits/forge/sections/arpy-gee-shop.tsx — the ArPeeGee shop demo (silver + gold = coins, shield = goods; userland custom dimensions). This is the live, working analogue of the README's cities/wheat/ore example. The README should either (a) switch its "Build your own" code to be the exact same code the ArPeeGee shop demo runs, or (b) keep cities but link prominently at "see this idea live: ArPeeGee shop demo."
• demo/src/components/kits/forge/sections/core-api.tsx — the handspan example. The README's handspan + linear(0.235) block at README.md:148-154 doesn't match the demo's version.

The principle: a reader copy-pasting code from the README should get something they can also see running in the demo. Single canonical version, mirrored both places.

Adjusted acceptance criteria

• README "Build your own" example code is identical to demo/src/components/kits/forge/sections/arpy-gee-shop.tsx's rendered code (or both files compose the same buildCode() source)
• README handspan example code matches demo/src/components/kits/forge/sections/core-api.tsx
• Dead Crouton link at README.md:31 and README.md:141 replaced with the ArPeeGee shop demo URL
• Custom-dimension prefix convention shrinks to one line in README; the ArPeeGee shop demo itself demonstrates the namespaced-dimension form so the convention is shown, not explained

[the-simian]

Pedagogical-order fix (both README and demo)

Current order in both the README "Build your own" section and the demo home page: complete integrated example first, then the individual primitives.

Should be flipped: three primitive snippets first (defineUnit → defineConversion → forge), then the complete integrated example (the ArPeeGee shop) as the synthesis.

The three primitive snippets already exist in the demo at demo/src/components/kits/forge/sections/core-api.tsx:

• defineUnit card: handspan example
• defineConversion card: areaFromRectangle (cross-dim length+length → area)
• forge card: uses both above

README rewrite for "Build your own":

1. Three short snippets (one per primitive), matching the demo's core-api cards
2. Then: "putting it all together" complete example → link to the ArPeeGee shop demo

Demo home-page reorder: CoreApi section moves above ArpyGeeShop. The text in core-api.tsx:79 ("The Arpy Gee Shop demo above stitched all three together") also needs to flip its directional reference once the order changes.

Adjusted acceptance criteria

• README "Build your own" section presents primitives in pedagogical order: defineUnit → defineConversion → forge → integrated example
• Each primitive snippet in the README matches the corresponding card in demo/src/components/kits/forge/sections/core-api.tsx
• Demo home page reorders sections: CoreApi cards above ArpyGeeShop integrated demo
• core-api.tsx:79 intro text adjusted to reflect new positional relationship

[the-simian]

Final consolidated structure for "Build your own"

README (README.md):

1. Brief intro line ("three primitives; here's each one, then they compose")
2. defineUnit snippet (handspan, matching core-api.tsx card 1) + one-sentence blurb
3. defineConversion snippet (areaFromRectangle, matching core-api.tsx card 2) + one-sentence blurb
4. forge snippet (using both above, matching core-api.tsx card 3) + one-sentence blurb
5. "See all three composed: ArPeeGee shop demo."
6. (no more prose about the custom-dimension prefix convention)

Demo (demo/src/components/kits/forge/sections/arpy-gee-shop.tsx):

Currently uses bare COIN = 'coin' and GOODS = 'goods'. Switch to namespaced form so the demo teaches the convention by example, not by README prose:

const COIN  = 'arpygee/coin'  as const;
const GOODS = 'arpygee/goods' as const;

That single change makes the demo the canonical reference for "this is how you name custom dimensions when shipping a kit." The README's verbose > Custom-dimension prefix convention. ... blockquote at README.md:143 deletes entirely.

Adjusted acceptance criteria

• README "Build your own" is exactly: intro line, three numbered snippets (each ≤ 6 lines), one-sentence blurb per snippet, link to ArPeeGee shop as the synthesis
• arpy-gee-shop.tsx:24-25 uses namespaced dimension strings ('arpygee/coin', 'arpygee/goods')
• arpy-gee-shop.tsx rendered codegen (line 245-250) also shows the namespaced form
• No "Custom-dimension prefix convention" blockquote anywhere in README.md

[the-simian]

Cut: linear() tree-shake warning blockquote

README.md:156 ("Inside kit-shipped unit definitions, inline the toBase/fromBase closures rather than spreading linear(scale)...") deletes entirely from the README. It's a kit-author concern that only matters when shipping a kit consumed by others; the "Build your own" reader is in userland where tree-shake doesn't bite. Moves to EXTENDING.md or llms.txt if it needs to live anywhere outside source-code comments.

[simiancraft-banana-bot]

🎉 This issue has been resolved in version 3.2.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[simiancraft-banana-bot]

🎉 This issue has been resolved in version 3.2.2 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀