docs: rewrite README for humans; tighten demo prose - #34
Merged
Conversation
User reading the README on npm reacted to LLM-slop patterns: over-
explained paragraphs, internal-lore Settlers-of-Crouton references,
seven-step pipelines crammed into one sentence, defensive caveats
stacked five-deep, em dashes throughout. Reviewer audits (the-nit +
oss-marketing-bro) confirmed; user's target is "this rules, here's
how you use it" - snappy enough a human can scan in 30 seconds.
README changes:
- Hero now leads with the differentiator: "One Coke ≈ 9.75 sugar
cubes." Cross-dimensional and compile-time-safe surface immediately.
- Dead Settlers-of-Crouton demo links removed; "Build your own"
points at the live ArPeeGee shop demo instead.
- "Build your own" reordered pedagogically: three primitive snippets
(defineUnit / defineConversion / forge) first, integrated demo
link second. Each snippet matches the corresponding card in
demo/src/components/kits/forge/sections/core-api.tsx.
- "What this isn't" five-negation block replaced by one-line "Scope"
paragraph; the Install section already carried the relevant facts.
- "Testing" section dropped from three paragraphs to three bullets;
per-file mutation breakdown and survivor-classification policy
moved to llms.txt.
- Custom-dimension prefix convention blockquote (95 words of
defensive doc) deleted; the ArPeeGee demo now demonstrates the
convention via its `'arpygee/coin'` dimension strings.
- linear() tree-shake foot-gun blockquote deleted; kit-author concern,
moved to EXTENDING.md / llms.txt.
- Cross-dim 9-step pipeline (the worst single sentence in the file)
deleted from README; full ordering moved to llms.txt.
- API section's validator return contract and (string & {}) brand
explanation moved to llms.txt.
- Em dashes converted to semicolons or rephrased per CLAUDE.md house
style.
llms.txt additions:
- New section: "Forge pipeline (cross-dim)" with the 10-step ordering.
- New section: "Validator contract" with return convention.
- New section: "Dimension type and the (string & {}) brand."
- New section: "Custom-dimension prefix convention" with rationale
and the ArPeeGee demo as worked example.
- New section: "Testing" with example/fuzz/mutation detail, per-file
mutation breakdown, and survivor-classification policy.
- Kits list now includes cooking (was stale).
- Three pre-existing em dashes converted to colons.
Closes substantial parts of #33.
…ump shop sliders Three demo-side changes that pair with the docs rewrite (#33): - Forge home page now shows CoreApi (the three primitive cards) above ArpyGeeShop (the integrated demo), matching the README's pedagogical order: see the primitives, then see them composed. - ArPeeGee shop's COIN/GOODS dimensions go from bare 'coin'/'goods' to namespaced 'arpygee/coin'/'arpygee/goods'. The demo now demonstrates the custom-dimension prefix convention by example so the README's prose explanation can delete entirely. Downstream Unit<'coin', ...> types switch to Unit<typeof COIN, ...> so the literal-string update propagates without hand-editing every interface. - Slider maxes bumped: SILVER_MAX 30 → 45, GOLD_MAX 6 → 45. The conversion's leverage (30 silver-base = 1 shield) feels real to the slider-scrubber when the maxes can reach double-digit shields. CoreApi's intro text adjusted: "Arpy Gee Shop demo above" → "below" to match the new positional relationship.
… dash Cooking-kit demo prose audit (#33): - Kit header text: 90-word paragraph reduced to 35 words. Dropped the NIST-factor sidebar and the LARGER/SMALLER caps that read like an LLM proving it knows the topic. - Kit blurb (registry card): "culinary volumes; US/UK split for cup, tablespoon, teaspoon, and fluid ounce; stick of butter, dash, pinch; system + recipe machines" → "teaspoons, teacups, the usual suspects, but also international units, sugar comparisons, and more." User's preferred voice; matches the geometry/data-storage card rhythm. - Comparison machine introZone: 60-word two-sentence intro reduced to one sentence. The per-pill `hint` fields already do the explaining the intro was duplicating. - International comparator menu-pill hint: em dash converted to semicolon per CLAUDE.md house style. Soda comparator food-icon cluster: - Icon size: h-7 w-7 (28 px) → h-4 w-4 (16 px). ~57% linear / 33% area reduction; at high counts (e.g., 9.8 sugar cubes per Coke can, or 11+ for the 2 L bottles) the icons no longer crowd the row. - MarchingIcons gap: gap-1.5 → gap-1. Tighter cluster keeps the visualization compact at every count.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #34 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 15 15
Lines 1465 1465
=========================================
Hits 1465 1465 🚀 New features to boost your workflow:
|
Reacting to review-the-nit + review-oss-marketing-bro on PR #34. Must-fix (the-nit): - README:162 + core-api.tsx:23 claimed (12 hsp × 8 hsp) area = 57.067 sq ft; actual is 57.0659... which rounds to 57.066. Fixed in both surfaces so a reader copy-pasting the snippet sees the same number the live demo renders. High-impact polish (oss-bro): - "vs. convert-units" reframed. The version-status caveat was a defensive paragraph above the table; promoted the verdict to a bold lead-in ("unitforge catches dimension mismatches at compile time and ships cross-dimensional recipes; convert-units does neither, today or in 3.x"), demoted the version trivia to a <sub> footnote under the table. Same facts, different posture. - "Build your own" intro no longer says the demo "stitches" the primitives ("stitches" is a tell that nobody says out loud). Also names ArPeeGee on first mention so the second link reads as callback, not jargon. - "Build your own" closer dropped the "namespaced-dimension convention" clause; the link carries the lesson, the prose does not need to glossary-explain it. - Tarball line bolded the headline number (52 kB packed) instead of burying it in prose. - "For agents" renamed "For LLMs and agents"; one parenthetical names the use case ("Feeding this repo into Claude / Cursor / Copilot?") so humans reading READMEs to decide what to feed their agent recognize this is the section for them. Deferred to #35: - Memoize demo surface (own-scope; needs a new demo widget, not a README edit). - TESTING.md split for mutation-survivor + per-file breakdown (optional reorganization out of llms.txt).
4 tasks
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.
Closes #33.
Summary
'arpygee/coin','arpygee/goods') so it demonstrates the prefix convention by example; README prose explanation deleted.Version bump
This PR will land as a patch (3.2.0 → 3.2.1):
docs:commit triggers patch per.releaserc.jsonrule{ "type": "docs", "release": "patch" }.feat(demo):andfix(demo):commits excluded per{ "scope": "demo", "release": false }.Test plan
bun run checkclean (lint, typecheck, build, tests, knip, attw, publint)