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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

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.

Notes

shipped production is serving it deploy d73d768

opened this

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. Counting guide-first-app.md, eleven pages are held to this budget.
  • One example per page: guide-what-a-forge-is.md, guide-hosting.md and guide-when-wrong.md each gained a curl -s $FORGE_URL/… example. guide-own-ai.md gained a forge.json example with egress, and guide-backups-moving.md and guide-settings.md gained a forge sync and a forge whoami example. The test requires exactly one fenced block on each of those pages and on guide-tell-the-crew.md, guide-ship-and-undo.md, guide-your-apps.md and guide-agents.md.
  • How the examples are checked: curl examples are fetched from the booted test forge and must return 200. forge commands and flags are checked against docs/CLI.md, and JSON examples must parse and use only keys docs/APPS.md documents.
  • guide-your-apps.md: I cut the first forge.json block, since the schedules block already shows app.run. That leaves one example.

What I left out

  • guide-first-app.md is not on your list of ten. It walks several steps, so it is exempt from the one-example rule but not from the budget.
  • forge examples 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.

Closes #12528

1 earlier comment · 1 event
commented

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. Counting guide-first-app.md, eleven pages are held to this budget.
  • One example per page: guide-what-a-forge-is.md, guide-hosting.md and guide-when-wrong.md each gained a curl -s $FORGE_URL/… example. guide-own-ai.md gained a forge.json example with egress, and guide-backups-moving.md and guide-settings.md gained a forge sync and a forge whoami example. The test requires exactly one fenced block on each of those pages and on guide-tell-the-crew.md, guide-ship-and-undo.md, guide-your-apps.md and guide-agents.md.
  • How the examples are checked: curl examples are fetched from the booted test forge and must return 200. forge commands and flags are checked against docs/CLI.md, and JSON examples must parse and use only keys docs/APPS.md documents.
  • guide-your-apps.md: I cut the first forge.json block, since the schedules block already shows app.run. That leaves one example.

What I left out

  • guide-first-app.md is not on your list of ten. It walks several steps, so it is exempt from the one-example rule but not from the budget.
  • forge examples 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.

Changes requested — before the latest push

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.

commented

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.md is the longest, at 291 words and 55 lines.
  • Every spine page except guide-first-app.md has exactly one fenced example. That page walks several steps, so it is exempt from the one-example rule.
  • curl examples are fetched from the booted test forge and must return 200.
  • forge commands and flags in examples are checked against docs/CLI.md, and JSON examples must parse and use only keys docs/APPS.md documents.
  • forge examples 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.md example 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.md and guide-settings.md now say why forge sync and forge whoami are run.
  • $FORGE_URL: the examples use https://YOUR-FORGE, the placeholder guide-agents.md already uses. The pages say it stands for your forge's address, and the test matches that form.
  • egress host: the example uses api.weather.example.com, with a lead-in sentence on guide-own-ai.md.
  • Stale text, partly done: guide-backups-moving.md said forge sync clones every app you follow. docs/CLI.md says it syncs pinned repos, or the ones you own when none are pinned, so I corrected it. I spot-checked the forge ship prompt, the spawn tool, the plan names and ready in forge.json against 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.

Approved

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:

  1. Non-blocking: guide-when-wrong.md gives the same curl command in the sentence and again in the fence. Drop it from the sentence.
  2. 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.
Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs