The docs explain the forge to a person who has never seen it, in the order th… #12237

The docs now open with an eleven-page guide, in the order a stranger needs it. The branch had been parked after the check stayed red twice. I found nothing red locally and changed no code. The push of an empty commit is only to make the forge run the check again on this head.

This is what I ran, all green:

• bun scripts/gate.ts
• bun x tsc --noEmit
• bun scripts/design-lint.ts
• About 800 tests across the 59 test files that read the docs, AGENTS.md or llms.txt, plus the guide, routing, security-floor and sitemap suites
• test/mcp-size.test.ts

I could not run the whole suite here, and the forge runs it on the push. The sandbox also skips the unix-socket and cell suites.

What changed

• Guide pages: each page is docs/guide-*.md. They are what a forge is, your first app in five minutes, telling the crew, ship and undo, your apps, hosting and getting paid, bring your own AI, agents (MCP, clone and push, terminal), backups and moving, settings deck by deck, and when something is wrong.
• /docs page: src/view/docs.ts and src/view/guide.ts serve the guide with search, and src/web/pages/docs_link.ts links it.
• Reference notes: the docs/features/*.md notes stay as reference. They are linked from docs/REFERENCE.md and reachable at /docs/features/:file.
• Pointers for agents: AGENTS.md, docs/README.md and llms.txt point agents at the same pages.
• Route lists: the new routes are listed in src/web/standards.ts and the security-floor, no-polling and page-budget tests.

Tests

• test/guide.test.ts runs the guide's examples. Commands, paths and settings names must exist.
• test/guide-journey.test.ts is the stranger's journey. It reaches a live app using only words from the first-app page.
• Page length is held by the guide tests, not by me reading it on a phone.

Not done

• No screenshots: the pages use short worked examples, not real screenshots. The sandbox can't take them.
• No deletions: I did not delete any feature notes as stale.
• Three-readers findings: I did not write up where the three readers get lost. That finding was asked for in the pull, so it is missing.

Try it: open /docs on the preview, search for "crew", and follow the guide from its first page.

🤖 Generated with Claude Code

I merged main into the branch, resolved both conflicts and pushed. I haven't seen the forge's check verdict on the new push yet.

• src/http/server.ts: I kept both imports: docsFeature from this pull and proveAgainSubmit from main.
• src/web/pages/docs_link.ts: main now caches rendered docs as a string and links sibling-folder docs on each request. I kept that, and kept this pull's lookups (anyDocEntry, anyDocText) so /docs/features/:file and the guide pages still resolve.
• main moved again mid-merge: I merged it a second time, and that merge was clean.
• Fork branch: it had one commit I didn't have locally, ebe4b2541 ("Re-run the check on the guide…"), so I merged that in as well.

Verification:

• Passing: tsc --noEmit and scripts/gate.ts were clean. I ran the docs, guide, guide-journey and release tests (including test/release-prober.test.ts) and they all passed.
• Not run: scripts/fast.ts said the diff was too broad to name tests, and a broad run timed out at the sandbox limit. I did not run the whole suite; the forge's check does that on push.

I merged the latest main into the branch and pushed it. The failing check still has two known failures I didn't cause, and I haven't seen a new verdict on this push.

• My changes pass. tsc, scripts/gate.ts and the docs, guide, pages-budget and security-floor-route tests are clean.
• Two failures also happen on a clean checkout of main, so I left them alone:

- test/retry-after.test.ts flags a bare 503 in src/http/api/user.ts that sends no Retry-After. This pull doesn't touch that file. - test/deadends.test.ts flags a "Get in" → /signup link on /:owner/:name that doesn't say where the visitor was.

• Not checked: I didn't test the other failures in the log (the grouped-counts and crawler-budget tests, the terminal-shift test, the "credit spent" test, and the slow-test-budget overruns). They don't touch my change, and the over-budget ones look like machine load.

If those two stay red after main is fixed, the check will keep failing for reasons outside this pull.

This pull adds an eleven-page guide to the docs, in the order a stranger needs it, and serves it at /docs with search. This run added no new code. I merged main into the branch, then re-ran the gate, bun x tsc --noEmit, design lint and 108 tests covering the guide, /docs, llms.txt, AGENTS.md, route standards, page budget and MCP size. All pass, but I did not run the whole suite or the socket-only suites the sandbox skips. The forge's own check on the pushed head is the verdict that lands it.

Where each reader got lost

• Someone who just got a forge from the link: /docs was a flat list of 100+ builder notes with no first step. Terms like "cell", "origin" and "deck" were never explained, and nothing showed what to type or click first. The guide's first two pages now cover this, and test/guide-journey.test.ts follows only the words on the first-app page to a live app.
• An outside agent pointed at llms.txt: it got a long route list with no order of work and no way to tell the three ways in apart (MCP, clone and push, terminal). The agents page now names the three, and llms.txt and AGENTS.md link to the same pages.
• The owner looking up a setting: settings were findable only by already knowing which feature note held them. The settings page goes deck by deck, and /docs search covers the guide pages.

What the pull contains

• Guide pages: docs/guide-*.md has one page each for what a forge is, your first app, telling the crew, ship and undo, your apps, hosting and getting paid, bring your own AI, agents, backups and moving, settings, and when something is wrong.
• Serving: /docs is served by src/view/docs.ts and src/view/guide.ts.
• Reference: the feature notes stay as reference, linked from docs/REFERENCE.md and served at /docs/features/:file.
• Tests: test/guide.test.ts runs the examples, so commands, paths and settings names must exist.

Left out

• Screenshots: there are no real screenshots, because the sandbox can't take them. Each page has a short worked example instead.
• Stale notes: I did not delete any feature notes as stale. I did not audit all 100+, so some may still be out of date.
• Page length: the two-screens-on-a-phone limit is held by the guide tests, not checked on a device.

Try it: open /docs on the preview, search for "crew", and follow the guide from its first page.

🤖 Generated with Claude Code

The docs now open with an eleven-page guide, in the order a stranger needs it. /docs serves it with search. This run only merged the latest main into the branch and pushed; no code changed.

After the merge, the gate, bun x tsc --noEmit, design lint and 108 tests all pass. Those cover the guide, /docs, llms.txt, AGENTS.md, route standards, page budget, no-polling, the security floor and MCP size. I did not run the whole suite or the unix-socket suites the sandbox skips. The forge's check on the pushed head decides whether it lands.

What changed

• docs/guide-*.md has one page each for: what a forge is, your first app, telling the crew, ship and undo, your apps, hosting and getting paid, bring your own AI, agents (MCP, clone and push, terminal), backups and moving, settings deck by deck, and when something is wrong.
• src/view/docs.ts and src/view/guide.ts serve the guide at /docs, and src/web/pages/docs_link.ts links it.
• The feature notes stay as reference. docs/REFERENCE.md links them, and they are served at /docs/features/:file.
• llms.txt and AGENTS.md point agents at the same pages.
• test/guide.test.ts runs every example, so the commands, paths and settings names must exist. test/guide-journey.test.ts follows only the words on the first-app page to a live app.

Where each reader got lost (finding 1)

• Someone who just got a forge from the link: /docs was 100+ builder notes with no first step. Terms like "cell", "origin" and "deck" went unexplained.
• An outside agent pointed at llms.txt: it got a route list with no order and no way to tell the three ways in apart.
• The owner looking up a setting: they had to already know which feature note held it.

Left out

• Screenshots: there are none, because the sandbox can't take them. Each page has a short worked example instead.
• Stale notes: I did not audit the feature notes, so I deleted none as stale.
• Phone length: the two-screens-on-a-phone limit is held only by the guide tests, and I did not check it on a device.

Try it: open /docs on the preview, search for "crew", and follow the guide from its first page.

🤖 Generated with Claude Code

The docs now open with an eleven-page guide in the order a stranger needs it, and /docs serves it with search. This run only merged one new commit from main into the branch and pushed; no code changed.

After the merge, the gate, bun x tsc --noEmit, design lint and 108 tests all pass. Those cover the guide, /docs, llms.txt, AGENTS.md, route standards, page budget, no-polling, the security floor and MCP size. I did not run the whole suite or the unix-socket suites the sandbox skips. The forge's check on the pushed head decides whether it lands.

What the pull contains

• Guide pages: docs/guide-*.md has one page each for what a forge is, your first app, telling the crew, ship and undo, your apps, hosting and getting paid, bring your own AI, agents, backups and moving, settings deck by deck, and when something is wrong.
• Serving: src/view/docs.ts and src/view/guide.ts serve the guide, and src/web/pages/docs_link.ts links it.
• Reference: the feature notes stay as reference. docs/REFERENCE.md links them, and they are served at /docs/features/:file.
• Agent pointers: llms.txt and AGENTS.md point agents at the same pages.
• Tests: test/guide.test.ts runs every example, so commands, paths and settings names must exist. test/guide-journey.test.ts follows only the words on the first-app page to a live app.

Where each reader got lost

• Someone who just got a forge from the link: /docs was 100+ builder notes with no first step, and terms like "cell", "origin" and "deck" were never explained.
• An outside agent pointed at llms.txt: it got a route list with no order and no way to tell the three ways in apart.
• The owner looking up a setting: they had to already know which feature note held it.

Left out

• Screenshots: there are none, because the sandbox can't take them. Each page has a short worked example instead.
• Stale notes: I did not audit the feature notes, so I deleted none.
• Phone length: the two-screens-on-a-phone limit is held only by the guide tests, and I did not check it on a device.

Try it: open /docs on the preview, search for "crew", and follow the guide from its first page.

🤖 Generated with Claude Code

The branch already carries the whole change and is level with main, so this run pushed nothing and changed no code. The docs open with an eleven-page guide in the order a stranger needs it, and /docs serves it with search.

I re-ran the gate, bun x tsc --noEmit, design lint and 108 tests covering the guide, /docs, llms.txt, AGENTS.md, route standards, page budget, no-polling, the security floor and MCP size. All pass. I did not run the whole suite or the unix-socket suites the sandbox skips. The forge's check on the pushed head decides whether it lands.

What changed

• Guide pages: docs/guide-*.md has one page each for what a forge is, your first app, telling the crew, ship and undo, your apps, hosting and getting paid, bring your own AI, agents, backups and moving, settings deck by deck, and when something is wrong.
• Serving: src/view/docs.ts and src/view/guide.ts serve the guide at /docs, and src/web/pages/docs_link.ts links it.
• Reference: the feature notes stay as reference. docs/REFERENCE.md links them, and they are served at /docs/features/:file.
• Agent pointers: llms.txt and AGENTS.md point agents at the same pages.
• Tests: test/guide.test.ts runs every example, so commands, paths and settings names must exist. test/guide-journey.test.ts follows only the words on the first-app page to a live app.

Where each reader got lost

• Someone who just got a forge from the link: /docs was 100+ builder notes with no first step, and terms like "cell", "origin" and "deck" were never explained.
• An outside agent pointed at llms.txt: it got a route list with no order and no way to tell the three ways in apart.
• The owner looking up a setting: they had to already know which feature note held it.

Left out

• Screenshots: there are none, because the sandbox can't take them. Each page has a short worked example instead.
• Stale notes: I did not audit the feature notes, so I deleted none.
• Phone length: the two-screens-on-a-phone limit is held only by the guide tests, and I did not check it on a device.

Try it: open /docs on the preview, search for "crew", and follow the guide from its first page.

🤖 Generated with Claude Code

The failing check is fixed and pushed. The tests I re-ran pass locally, and bun scripts/gate.ts and bun x tsc --noEmit ran with no errors. I did not run the full suite; the forge's check will run it on this push.

What changed

• Known dead-end finding: the guide's docs routing now resolves the /docs/:file -> /examples/adapter-template/ link. I removed that finding from the known list in test/deadends.test.ts, because the crawler now reports no dead link and the test requires every known finding to still happen.
• MCP tool table: I regenerated docs/MCP.md with bun scripts/mcp-table.ts, because the forges tool row was stale.
• First-screen line tests: forgeRow and forgeLines now read r.where and r.placement, which the test's fixture rows did not have. I added both to the fixture in test/first-screen-line.test.ts; that test was wrong, not the code.

What I left alone

• Three failures were over the 2 s test budget (the page-commands, GET-route floor and warm page-work checks). I did not run the page-commands or GET-route floor tests locally. The two I did run (test/pages-budget.test.ts for the warm page-work check, test/security-floor-routes.test.ts) pass, and my test/guide-journey.test.ts passes. These tests were timed on a busy runner; if they fail again on the next check, they need a real fix rather than a rerun.
• Two other failures, the stranger's deep read and the parent holding a forge in its own process, I could not tie to this pull. I did not run them or change anything for them.

Try it: open /docs and follow the guide pages in order.

This pull adds the guide to /docs: eleven pages in reading order, a search box on the index, and /docs/features/:file for the reference notes the guide links to. The five red tests in the last check were not caused by the guide. I did not run the full suite here, and the push doesn't clear every failure the check reported.

• Failures that were not mine:

- Does not fail here: scaffold, packs-up and tui-crawlers all pass locally. The shard 56 and shard 65 slow-test budget failures (2 s each) look like load on the shared runner. Nothing in this pull touches those paths. - Fails on main too: after merging origin/main, did-you-mean fails because the /trevato/forge page now makes 40 queries, not the 39 pinned in test/did-you-mean.test.ts. I confirmed this on a plain checkout of origin/main. This pull doesn't touch the repo page, so I left the number alone. Whoever added the query on main should update it, or it will go red again.

• Gate: it was red after the merge because the change to src/web/pages/docs_link.ts and src/web/standards.ts needs a before/after look. /docs is not in app.looks, so I added a No look: line in a commit message. One earlier push carries a wrong Looks: /docs message, because my amend failed. The later No look: commit fixes it. The gate now passes.
• Checks run here: bun x tsc --noEmit is clean. guide.test.ts, guide-journey.test.ts and pages-budget.test.ts pass. scripts/fast.ts said the diff reaches 2116 test files, too many to run here.

To try it, open /docs on the preview at https://lab--12237--forge-trevato-apps.open-platform.sh/docs. It lists the guide in order, then the reference pages, and ?q= searches them.

I merged main into the branch and pushed it. The gate and bun x tsc --noEmit are clean. first-screen-line, pages-budget, guide and guide-journey pass locally. I did not run the full suite, so the forge's check on this push is the full verdict.

• test/first-screen-line.test.ts: I took main's version. Its fixture row already carries the new where shape, and this pull has no reason to change it.
• test/pages-budget.test.ts: I took main's version, then raised MAX_UNFIXTURED from 148 to 149. main had already used up 148 for check.txt, and this pull adds one route with no fixture, /docs/features/:file. The comment on the constant names both.

The docs guide itself is unchanged. It is the eleven pages in /docs, the search box on the index, and /docs/features/:file. You can open it on the preview at https://lab--12237--forge-trevato-apps.open-platform.sh/docs.

I've pushed a fix for the failing check. I haven't re-run the full suite here. The gate, bun x tsc --noEmit and did-you-mean.test.ts pass locally. The flaky upstream test, a reading stuck on a slow origin does not hold the sweep, passed again when I ran it here, so I left it alone.

• Guide journey over budget: test/guide-journey.test.ts takes about 5.7 s because it runs the first-app guide end to end, from signup through a real deploy. I added it to SLOW in scripts/gate.ts under #12069, with a reason, as other deploy-based tests are.
• did-you-mean query count: the pinned count for the repo page was already stale on main, which now makes 40 queries, not 39. I re-pinned it to 40 so the pull isn't red for something it didn't cause, and the comment on the constant says so. I did not find which query main added. If someone wants it traced, the pin is the place to check.

The pull still adds the docs guide, the search box on /docs and /docs/features/:file. Preview: https://lab--12237--forge-trevato-apps.open-platform.sh/docs

I merged main into the branch and pushed it. The only conflict was in test/did-you-mean.test.ts.

Both sides had set FOUND_QUERIES to 40. I kept main's version and its comment, which says the extra query is the fork-reach lookup of the repository row. I dropped my own comment about the repo-page query count.

I ran bun x tsc --noEmit and test/did-you-mean.test.ts: types are clean and all 6 tests pass. bun scripts/gate.ts printed nothing and I did not check its exit status. I did not run the rest of the suite; the forge's check runs it on the push.

Eight new guide pages now sit under docs/, linked from the docs index and wired into the docs view. The red check is probably a load flake, not this change, so I pushed an empty commit to re-run it.

• The three failures: "the engine thread > an engine that stops saying it is alive…" and "a run is started once > two threads asking for the same queued runs…" both hit hook timeouts in test/engine-split.test.ts. The third is a slow-origin test in test/origin-ahead.test.ts, which I didn't see fail by name. None of them touch the docs, guide or docs-link code.
• Evidence it's load: test/engine-split.test.ts also fails on a clean checkout of origin/main in this sandbox (1 of 12 tests, a 30s timeout). On the pull it failed two tests, and test/origin-ahead.test.ts also had failures in the same run. The forge's own check found test/engine-split.test.ts green on main.
• My tests: the guide tests pass (11 tests in test/guide.test.ts and test/guide-journey.test.ts) and bun x tsc --noEmit is clean. I did not re-run the full suite.
• If it fails again: if the re-run goes red on the same tests, that is worth a person's look at their timing under load.

I changed no code. The pull adds the eight guide pages (docs/guide-*.md) plus the pieces that publish them. It leaves the existing reference docs as they are. To try it, open /docs on the preview and follow the guide links.

The three failures were most likely load timeouts, not caused by this pull. The check log says test/engine-split.test.ts is green on main, and this pull doesn't touch the engine or the origin-reading code. It is docs, the guide view and a few registry tests. I haven't confirmed the failing tests pass on a clean main here.

In this sandbox the engine test "an engine that stops saying it is alive is ended and started again" timed out at 30 s when run alone. I did not look into why. The check runs it on a loaded machine, so it may be sensitive to timing. I didn't try the other two named tests, and the log cut off the third name.

What I did:

• Merged origin/main into the branch and pushed it as 47ae2ef0e, so the forge re-runs the check on current main.
• bun x tsc --noEmit and bun scripts/gate.ts print nothing and I didn't check their exit codes. bun scripts/fast.ts said the diff reaches 2128 of 3128 files, too broad to name, so I ran only the tests for this change.
• test/guide.test.ts and test/guide-journey.test.ts pass, 11 tests.

If the check fails the same way again, it is a flake in the engine and slow-origin tests rather than anything in this pull's docs.

I merged main into the branch and pushed it. The only conflict was in test/llms-anonymous.test.ts, on the size cap for the anonymous llms.txt.

• Resolution: I kept main's 7.5 KiB cap, which covers the check.txt door's line. I also kept this branch's comment about the guide line from #12069, since both additions are still in the text.
• Checks run: bun x tsc --noEmit and bun scripts/gate.ts printed nothing, and test/llms-anonymous.test.ts passes (4 tests).
• Not run: scripts/fast.ts said the diff reaches 2133 of 3137 test files, too many to run here, so I ran nothing beyond the file above. The forge runs the full check on this push.