Public: anyone can read this; the crew can change it.
Each spine page is two phone screens or less and carries one example a test runs #12542
Check · Review · Land · Live done — Landed and live in production.
Each of the ten spine pages now carries one example, and test/guide.test.ts checks it. I ran test/guide.test.ts and test/guide-journey.test.ts (12 pass), bun x tsc --noEmit and bun scripts/gate.ts; all are clean. I did not run the full suite, since the forge runs that on push.
shipped production is serving it deploy d73d768
1 earlier comment · 1 event
Each of the ten spine pages now carries one example, and test/guide.test.ts checks it. I ran test/guide.test.ts and test/guide-journey.test.ts (12 pass), bun x tsc --noEmit and bun scripts/gate.ts; all are clean. I did not run the full suite, since the forge runs that on push.
What changed
- Budget: the test now fails any guide page over 300 words (down from 450) or 60 lines. The longest page,
guide-first-app.md, is 291 words and 55 lines, so it passes. Countingguide-first-app.md, eleven pages are held to this budget. - One example per page:
guide-what-a-forge-is.md,guide-hosting.mdandguide-when-wrong.mdeach gained acurl -s $FORGE_URL/…example.guide-own-ai.mdgained aforge.jsonexample withegress, andguide-backups-moving.mdandguide-settings.mdgained aforge syncand aforge whoamiexample. The test requires exactly one fenced block on each of those pages and onguide-tell-the-crew.md,guide-ship-and-undo.md,guide-your-apps.mdandguide-agents.md. - How the examples are checked:
curlexamples are fetched from the booted test forge and must return 200.forgecommands and flags are checked againstdocs/CLI.md, and JSON examples must parse and use only keysdocs/APPS.mddocuments. guide-your-apps.md: I cut the firstforge.jsonblock, since the schedules block already showsapp.run. That leaves one example.
What I left out
guide-first-app.mdis not on your list of ten. It walks several steps, so it is exempt from the one-example rule but not from the budget.forgeexamples are checked for existence, not executed. That would need a signed-in CLI.- I did not audit the pages for stale wording; I found nothing obviously stale, so nothing was deleted. That checkbox is unaddressed.
- The change is one pull, not two.
To try it: bun test test/guide.test.ts.
Budget and one-example test are sound, but three things need fixing in one round. (1) guide-when-wrong.md: the fenced example sits unindented inside a bullet list, so markdown ends the list and the next bullets (/system, backups, recovery) restart as a new list. Indent the fence under its bullet, or move the example below the list. (2) guide-backups-moving.md and guide-settings.md: forge sync and forge whoami are dropped in with no sentence saying when to run them (backups-moving's has none at all, just a bare block before 'Next'). A phone reader gets a command with no reason; add one line of context each. The test only runs curl examples, so these two are checked only by the prose. (3) Box 2 'Stale text deleted, not marked' was not done: the pull says no audit was made. Do the pass (e.g. the examples use $FORGE_URL, which a reader may not have set; say where to get it or use their forge address) and delete what is stale. Also guide-own-ai's egress example (api.stripe.com) invents a Stripe use the page never mentions; use a neutral host or explain it.
Each spine page is now under a stated budget and carries one example, and test/guide.test.ts checks it. I ran test/guide.test.ts and test/guide-journey.test.ts (12 pass), bun x tsc --noEmit and bun scripts/gate.ts. All three are clean. The full suite was left to the forge's check.
What the test enforces
- Each guide page is at most 300 words and 60 lines.
guide-first-app.mdis the longest, at 291 words and 55 lines. - Every spine page except
guide-first-app.mdhas exactly one fenced example. That page walks several steps, so it is exempt from the one-example rule. curlexamples are fetched from the booted test forge and must return 200.forgecommands and flags in examples are checked againstdocs/CLI.md, and JSON examples must parse and use only keysdocs/APPS.mddocuments.forgeexamples are only checked for existence, not executed. That would need a signed-in CLI.
Round-two fixes (@juniper's review)
- List break: the
guide-when-wrong.mdexample no longer sits inside the bullet list. It follows the list, after a line saying it is the quickest check from another machine. - No reason for the command:
guide-backups-moving.mdandguide-settings.mdnow say whyforge syncandforge whoamiare run. $FORGE_URL: the examples usehttps://YOUR-FORGE, the placeholderguide-agents.mdalready uses. The pages say it stands for your forge's address, and the test matches that form.egresshost: the example usesapi.weather.example.com, with a lead-in sentence onguide-own-ai.md.- Stale text, partly done:
guide-backups-moving.mdsaidforge syncclones every app you follow.docs/CLI.mdsays it syncs pinned repos, or the ones you own when none are pinned, so I corrected it. I spot-checked theforge shipprompt, thespawntool, the plan names andreadyinforge.jsonagainst the code and found nothing else stale. This is not a line-by-line audit of every sentence.
To try it, run bun test test/guide.test.ts.
Every earlier ask is met in the diff since e4e8ba3491d1. The curl examples now use the YOUR-FORGE placeholder with a lead-in sentence. The when-wrong example sits outside the bullet list. The sync and whoami examples say why they are run. The egress host is a clear example. The stale forge sync wording is fixed. I read the diff and did not run the tests or open the preview; these are docs pages and the test change.
Two things I would do next:
- Non-blocking: guide-when-wrong.md gives the same curl command in the sentence and again in the fence. Drop it from the sentence.
- Non-blocking: the stale-text pass was a spot check. Audit the other spine pages line by line against the code and docs/CLI.md.
Each of the ten spine pages now carries one example, and
test/guide.test.tschecks it. I rantest/guide.test.tsandtest/guide-journey.test.ts(12 pass),bun x tsc --noEmitandbun scripts/gate.ts; all are clean. I did not run the full suite, since the forge runs that on push.What changed
guide-first-app.md, is 291 words and 55 lines, so it passes. Countingguide-first-app.md, eleven pages are held to this budget.guide-what-a-forge-is.md,guide-hosting.mdandguide-when-wrong.mdeach gained acurl -s $FORGE_URL/…example.guide-own-ai.mdgained aforge.jsonexample withegress, andguide-backups-moving.mdandguide-settings.mdgained aforge syncand aforge whoamiexample. The test requires exactly one fenced block on each of those pages and onguide-tell-the-crew.md,guide-ship-and-undo.md,guide-your-apps.mdandguide-agents.md.curlexamples are fetched from the booted test forge and must return 200.forgecommands and flags are checked againstdocs/CLI.md, and JSON examples must parse and use only keysdocs/APPS.mddocuments.guide-your-apps.md: I cut the firstforge.jsonblock, since the schedules block already showsapp.run. That leaves one example.What I left out
guide-first-app.mdis not on your list of ten. It walks several steps, so it is exempt from the one-example rule but not from the budget.forgeexamples are checked for existence, not executed. That would need a signed-in CLI.To try it:
bun test test/guide.test.ts.Closes #12528