Public: anyone can read this; the crew can change it.

llms.txt and AGENTS.md point agents at the guide spine, and feature notes link from the spine page they belong to #12544

Merged opened this

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

Merged

scout/forge:scout/12529-llms-txt-and-agents-md-point-agents-at-t → main 9 commits fork 7 threads · 7 unresolved

  • Merged. scout/12529-llms-txt-and-agents-md-point-agents-at-t was merged into main as 3a174f7.

Review

Sign in to review this change.
19 files changed +548 −12
AGENTS.md +1 −1
@@ -2,7 +2,7 @@
22
33 Read `CLAUDE.md` first: it is the rulebook for agents editing this repo.
44
5 The guide (`docs/guide-*.md`, ordered in `src/view/guide.ts`, served at `/docs` with search) is how a person and an outside agent are taught the forge: eleven pages, each at most 450 words, every command, path and link in them checked by `test/guide.test.ts`. A feature's `docs/features/<name>.md` is its reference; link it from the guide page it belongs to. llms.txt points at the same pages.
5 Read the guide first, in this order: `docs/guide-what-a-forge-is.md`, `docs/guide-first-app.md`, `docs/guide-tell-the-crew.md`, `docs/guide-ship-and-undo.md`, `docs/guide-your-apps.md`, `docs/guide-hosting.md`, `docs/guide-own-ai.md`, `docs/guide-agents.md`, `docs/guide-backups-moving.md`, `docs/guide-settings.md`, `docs/guide-when-wrong.md`. That is the spine (ordered in `src/view/guide.ts`, served at `/docs` with search, listed first by /llms.txt): eleven pages, each at most 300 words and 60 lines, every command, path and link in them checked by `test/guide.test.ts`. A feature's `docs/features/<name>.md` is its reference; give it one row under its topic in `docs/features/README.md`, the index every spine page links (`test/feature-orphans.test.ts`).
outdated

Too long and says the page order twice (it is in src/view/guide.ts). Say: llms.txt lists the guide first; every docs/features note is linked from a guide page.

66
77 README.md is capped: a new feature's how-to goes in `docs/features/<name>.md`, not a new README section.
88 A pull that adds a page (`src/web/pages/*.ts`) also adds a terminal screen under `src/tui/screens/` that another module imports (its palette entry) and a `docs/features/<name>.md`, or a commit line `No door: <why>`; a new `src/web/render/*.ts` or `src/actions/*.ts` is asked for the screen alone; `bun scripts/gate.ts` refuses it otherwise ("both doors", #10628).
docs/features/README.md +421
@@ -5,3 +5,424 @@ for the one feature it describes. Do not add a section to the top-level
55 `README.md`: it is capped (`test/readme-cap.test.ts`) because every pull that
66 appended to it collided with the next. Existing README sections stay where they
77 are.
8
9 ## Reference notes
10
11 Every note is listed once below, under the topic a reader would look in; the
12 topics follow [the guide](../guide-what-a-forge-is.md).
13 A new note gets a row here (`test/feature-orphans.test.ts`).
14
15 ### What a forge is
16
17 Read with the guide page [What a forge is](../guide-what-a-forge-is.md).
18
19 - [A look in the feed](feed-look.md)
20 - [An app with no description says its README](readme-description.md)
21 - [Arcade carts](arcade-carts.md)
22 - [Changelog](changelog.md)
23 - [/docs](docs-link.md)
24 - [Engine shape](engine-shape.md)
25 - [Feed fold](feed-fold.md)
26 - [Feed likes: the ledger](feed-like-ledger.md)
27 - [Forge packs: a premade forge to deploy (`/packs`)](packs.md)
28 - [Home paints its frame first](home-frame.md)
29 - [Is v1.0.0 proven?](v1-proven.md)
30 - [Looks of `/` signed out](home-looks.md)
31 - [Milestones at the front door](front-milestones.md)
32 - [Now pages and Repositories](now-pages.md)
33 - [Pixel art: the crew's faces](pixel.md)
34 - [Plans on the home](home-plans.md)
35 - [Returning visitors](returning-visitors.md)
36 - [The explorer's sorts](explore.md)
37 - [The feed pages by cursor](feed-cursor.md)
38 - [The fork tree](fork-tree.md)
39 - [The home](living-home.md)
40 - [The quiet feed names its one next thing](quiet-feed.md)
41 - [The roadmap](roadmap.md)
42
43 ### Getting around: keys, the palette and search
44
45 - [A mistyped repository address offers close ones](did-you-mean.md)
46 - [Cmd-K: a pull's actions](cmd-k-pull-actions.md)
47 - [Cmd-K: repositories and their apps](cmd-k-repositories.md)
48 - [`g` then a letter: jump between pages](go-jumps.md)
49 - [Hotkey hints](hotkey-hints.md)
50 - [Lists that ask for a decision answer the same keys](decision-keys.md)
51 - [Page help (`? Help`)](page-help.md)
52 - [Palette rows: numbers, people, settings, actions](palette-rows.md)
53 - [Phone search is the palette](search-is-palette.md)
54 - [Pick list](pick-list.md)
55 - [The empty palette lists what you opened last](palette-recent.md)
56
57 ### Your first app in five minutes
58
59 Read with the guide page [Your first app in five minutes](../guide-first-app.md).
60
61 - [Bring an app from another forge (`/bring`)](bring.md)
62 - [Display](display.md)
63 - [Displays list](displays.md)
64 - [Make it yours](make-it-yours.md)
65 - [New app, from the terminal](new-app.md)
66 - [Plain git contributes](plain-git.md)
67 - [Send a change without a forge of your own](send-a-change.md)
68 - [Start: an agent builds with only the forge's URL](start.md)
69 - [The account screen of a forge you just started](welcome.md)
70 - [The line about a sent forge's first screen](first-screen-line.md)
71 - [Where a new app stands](onboarding-line.md)
72
73 ### Tell the crew
74
75 Read with the guide page [Tell the crew](../guide-tell-the-crew.md).
76
77 - [A bug closes with a reason](bug-close.md)
78 - [A business, as a map](atlas-plan.md)
79 - [A maintainer keeps the code easy to change, and nothing else](crew-maintainer.md)
80 - [A new app starts the crew on it](new-app-crew.md)
81 - [A new forge builds at once](starter-crew.md)
82 - [A new issue from any page](new-issue-anywhere.md)
83 - [A run's state is worked out from what it did](run-state.md)
84 - [A team is told once that a pull waits on its review](team-waits.md)
85 - [A tell from a preview's toolbar carries its pull](toolbar-tell.md)
86 - [A write the restart cut short, in a conversation](talk-resume-writes.md)
87 - [Actions that answer at once](act-now.md)
88 - [An agent says what it does; a repo's team is three lists](crew-roles.md)
89 - [An assigned ask can be settled where it stands](ask-settles.md)
90 - [Ask filters](ask-filters.md)
91 - [Ask to reach a host](ask-to-reach.md)
92 - [Attention budgets](attention.md)
93 - [Bets](bets.md)
94 - [Bugs on a clock](bugs.md)
95 - [Chapters: a version with an end](chapters.md)
96 - [Each app with its crew member](app-crew.md)
97 - [Estimates](estimates.md)
98 - [Flow keeper](flow-keeper.md)
99 - [Flow line actions](flows-actions.md)
100 - [/flow: pulls closed unmerged after a CPU stop](flow-cpu.md)
101 - [Flow: the week's budget as pipes](flow-valves.md)
102 - [Flow: waiting](flow-waiting.md)
103 - [Flow: where the crew gives up](flow-handover.md)
104 - [Flows](flows.md)
105 - [Flows across the forge](admin-flows.md)
106 - [Give a team member a role](team-roles.md)
107 - [Hold new work on a file](file-holds.md)
108 - [Maintenance duties](maintain.md)
109 - [Muting from the inbox keeps you in place](asks-mute-undo.md)
110 - [Next up](next-up.md)
111 - [Next up says why a ready issue is not started](next-up-why.md)
112 - [Notes](notes.md)
113 - [Refused first asks](first-ask.md)
114 - [Share to the forge from a phone](share-to-the-forge.md)
115 - [Since you were here](since-you-were-here.md)
116 - [Talk as a builder](talk-builder.md)
117 - [/talk attachments](talk-attachments.md)
118 - [Talk runs the captain](talk-captain.md)
119 - [Talk to the forge's agent](talk.md)
120 - [Tell the crew from a share, with a look before it files](share-tell.md)
121 - [The crew line on Home](crew-line.md)
122 - [The crew list](crew-list.md)
123 - [The crew's runs on the desk](desk-runs.md)
124 - [The crew's week](crew-week-card.md)
125 - [The crew's week shows which pulls came back](crew-week-returned.md)
126 - [The first ask by ssh makes an app](ssh-first-ask.md)
127 - [The governor's line](governor-line.md)
128 - [The map, lightly](map.md)
129 - [The pulls a crew team's review holds](team-waiting.md)
130 - [The pulls waiting on a crew team](team-queue.md)
131 - [The queue](queue.md)
132 - [The space](space.md)
133 - [The thank-you note](thanks.md)
134 - [The week is one budget for the whole crew](crew-week.md)
135 - [The week's pace](week-pace.md)
136 - [Walking a wave](wave-walk.md)
137 - [What became of the first ask](ask-status.md)
138 - [When a setting or a permission stands in the way](blocked-by.md)
139 - [Your team](team.md)
140
141 ### Ship and undo
142
143 Read with the guide page [Ship and undo](../guide-ship-and-undo.md).
144
145 - [A forge killed in the middle of a merge](merge-crash-recovery.md)
146 - [A person's reopen stands](done-on-main.md)
147 - [A preview of the forge, looked at as its owner](preview-owner-looks.md)
148 - [A pull opens on its verdict](pull-verdict.md)
149 - [A pull's looks](pull-looks.md)
150 - [An approval says what it was given for](approval-base.md)
151 - [An approved pull that has waited a week](approved-week.md)
152 - [Build cache](build-cache.md)
153 - [Build pins](build-pins.md)
154 - [Build preview](build-preview.md)
155 - [Code scanning](code-scanning.md)
156 - [Detach a fork from its parent](detach.md)
157 - [Iterations](iterations.md)
158 - [Land it as it is](land-as-is.md)
159 - [Landing a fork's pull in slices](pull-slices.md)
160 - [Naming the approved pull that waits](approved-named.md)
161 - [Nightly jobs](nightly.md)
162 - [One path: check, review, land, live](pipeline.md)
163 - [Pin screenshots](pin-screenshots.md)
164 - [Pulls untouched for 14 days](stale-pulls.md)
165 - [Ranked checks](ranked-checks.md)
166 - [Release heartbeat and the main-ahead alarm](release-heartbeat.md)
167 - [Release keeper](release-keeper.md)
168 - [Release what the Later gate holds](release-later.md)
169 - [Reviews are something an owner turns on](reviews-off-lands-on-green.md)
170 - [The forge ships itself](ship-itself.md)
171 - [The landing line: when an approved pull will land](landing-line.md)
172 - [The Later gate in plain sight](later-gate.md)
173 - [The merge queue's gates, by failing test](queue-gates.md)
174 - [The polish share](polish-share.md)
175 - [The throughput keeper](keeper.md)
176 - [Variants](variants.md)
177 - [What a deploy carries, and when each change first went live](deploy-pull-retention.md)
178
179 ### Your apps
180
181 Read with the guide page [Your apps](../guide-your-apps.md).
182
183 - [A child forge's own source](own-source.md)
184 - [A forge that runs its own code](own-code.md)
185 - [Absorb, reviewed from several angles](absorb-review.md)
186 - [Absorb: an app becomes one of the forge's features](absorb.md)
187 - [Adapter facts on the app page and in the terminal](adapters-card.md)
188 - [An app cannot stall the forge](app-asking.md)
189 - [An app's own domain: cut-over and the way back](app-own-domain.md)
190 - [App templates](app-templates.md)
191 - [Archive listing](archive-listing.md)
192 - [Crawl budget](crawl-budget.md)
193 - [Data browser (core)](data-browser.md)
194 - [Database size](db-size.md)
195 - [Durable jobs](jobs.md)
196 - [First look at a note from an app](first_look.md)
197 - [Maintenance: shut down for a move and come back by itself](maintenance.md)
198 - [Measuring a page: height and words](measure-page.md)
199 - [New app from a template](app-template.md)
200 - [One place for a secret (`Settings → App → Secrets this app uses`)](app-secrets.md)
201 - [Pause and resume a maintenance duty](maintenance-duties.md)
202 - [Pinned toolchains (rust)](toolchains.md)
203 - [Scheduled tools: the forge calls an absorbed app's tool on time](feature-schedule.md)
204 - [Scrape evidence](scrapes.md)
205 - [The box pass](box-pass.md)
206 - [The data explorer starts from a question](data-explorer.md)
207 - [The data explorer's sentence box](data-explorer-sentence.md)
208 - [The forge toolbar](forge-toolbar.md)
209 - [Timers and schedules](timers.md)
210 - [Traffic](traffic.md)
211 - [Where people come from and where they go](traffic-sources.md)
212 - [Whose wait it was: the forge's or the app's](app-slowest-wait.md)
213
214 ### Files in the browser
215
216 - [A .dxf file as a picture](file-dxf.md)
217 - [A .har file as a request waterfall](file-har.md)
218 - [A .sarif file opens as its findings](file-sarif.md)
219 - [A `.env.example` opens as the variables an app needs](file-env.md)
220 - [A `.sql` file opens as its schema](file-sql.md)
221 - [A `Dockerfile` opens as its stages](file-dockerfile.md)
222 - [A `Makefile` opens as its targets](file-makefile.md)
223 - [A `package.json` opens as its manifest](file-package-json.md)
224 - [A compose file opens as its services](file-compose.md)
225 - [A GitHub Actions workflow opens as its jobs](file-workflow.md)
226 - [A GraphQL schema opens as its types](file-graphql.md)
227 - [A JUnit XML report opens as its results](file-junit.md)
228 - [An .eml file opens as a message](file-eml.md)
229 - [An lcov coverage file opens as its coverage](file-lcov.md)
230 - [An OpenAPI document opens as its operations](file-openapi.md)
231 - [Calendar files (.ics) as a list of events](ics.md)
232 - [Config files as a form](config-form.md)
233 - [Contacts files (.vcf) as a list of people](vcf-view.md)
234 - [CSV and TSV as a table](csv-view.md)
235 - [Files in the browser: the media route and the kind registry](file-media.md)
236 - [Font specimens](font.md)
237 - [G-code layers](gcode.md)
238 - [GeoJSON (.geojson) as an outline and a properties table](geojson.md)
239 - [GPS tracks (.gpx) as a route outline](gpx.md)
240 - [HTML preview](html-preview.md)
241 - [Jupyter notebooks](notebook.md)
242 - [Markdown relative images and links](markdown-relative.md)
243 - [Notebooks, JSON Lines and logs in the terminal](terminal-workspace-kinds.md)
244 - [Shift a subtitle file](subtitle-shift.md)
245 - [SQLite files as tables](sqlite-view.md)
246 - [Subtitles as a transcript](subtitles.md)
247 - [Terminal logs in colour](ansi-log.md)
248
249 ### Hosting forges for others, and getting paid
250
251 Read with the guide page [Hosting forges for others, and getting paid](../guide-hosting.md).
252
253 - [A child forge's cores, held by pausing where the kernel cannot](child-cpu-pausing.md)
254 - [A child forge's disk bandwidth is capped by its size](child-disk-bandwidth.md)
255 - [A child forge's own filesystem](child-filesystem.md)
256 - [A client's monthly bill](forge-bill.md)
257 - [A forge for a client, from one link](client-forge.md)
258 - [A forge whose billing is none](lapsed-forge.md)
259 - [A forge's claim link as a QR in the terminal](forge-link-qr.md)
260 - [A forge's own key and budgets](own-forge-budgets.md)
261 - [A forge's size and use on /system](forge-size-use.md)
262 - [A machine shell's first screen](machine-shell-rc.md)
263 - [A new forge's first ten minutes](new-forge-first-minutes.md)
264 - [A pinned forge](pinned-forge.md)
265 - [Billing](billing.md)
266 - [Buy a forge at /pricing](pricing.md)
267 - [Buy links](billing-links.md)
268 - [Capacity flags a count set below its ceiling](capacity.md)
269 - [Cloud accounts](cloud.md)
270 - [Disks on the machines page](machines-disks.md)
271 - [Does a forge I sent answer yet?](forge-ready.md)
272 - [End a forge link, and undo it](forge-link-revoke.md)
273 - [Fleet rows](fleet.md)
274 - [Forge it](forge-it.md)
275 - [/forges side by side](forges-side-by-side.md)
276 - [Growth and the planner switch](growth.md)
277 - [Hosted forges that scale to zero](forge-sleep.md)
278 - [How fast a team ships, and what it costs](team-metrics.md)
279 - [How is my forge?](forge-needs.md)
280 - [How much each seat may do at once](seat-slots.md)
281 - [Is a forge name free?](forge-name.md)
282 - [Machines](machines.md)
283 - [Maintenance duty budgets](maintenance-budgets.md)
284 - [Plans](plans.md)
285 - [Real-cell proof: the build half, in process](real-cell-proof.md)
286 - ["Running" is proven from outside](child-reach.md)
287 - [Start my forge](start-my-forge.md)
288 - [Stripe checkout binding](stripe-checkout-binding.md)
289 - [Telemetry readers](telemetry-readers.md)
290 - [The forge view (`GET /api/v1/forge/view`)](forge-view.md)
291 - [The forge's spend in the terminal](forge-usage-terminal.md)
292 - [The last Stripe event and refused signatures](stripe-events-line.md)
293 - [The money line — cost, revenue and the gap](money.md)
294 - [The page that answers "make me a forge"](forge-made.md)
295 - [The Plan row in a forge's settings](plan-row.md)
296 - [The selling funnel](selling-funnel.md)
297 - [The spawner's claim link](spawner-claim-link.md)
298 - [The statement — what the forge would charge an app](statement.md)
299 - [Ways to the fleet graph](fleet-graph-doors.md)
300 - [What a forge costs](footprint.md)
301 - [What a sized forge's cores mean for builds](cores-row.md)
302 - [What the forge stands on](footing.md)
303 - [Where a sent forge link stands](forge-link-states.md)
304 - [Your shells](my-shells.md)
305
306 ### Bring your own AI
307
308 Read with the guide page [Bring your own AI](../guide-own-ai.md).
309
310 - [A child forge's cell may reach its model provider](child-model-egress.md)
311 - [A forge with no model key](no-model-key.md)
312 - [A parent funds a child's crew](child-credit.md)
313 - [An org's model account](org-model-grant.md)
314 - [Cost ledger](cost-ledger.md)
315 - [Economics: the profit slider, its prices and what the month costs](economics.md)
316 - [Escalate to Opus by need](model-escalation.md)
317 - [Issue cost: what an issue and its pulls spent](issue-cost.md)
318 - [Mirror credit](mirror-credit.md)
319 - [The OpenAI-compatible runner](openai-runner.md)
320 - [The weekly model review](model-review.md)
321
322 ### Agents: MCP, git, or the terminal
323
324 Read with the guide page [Agents: MCP, git, or the terminal](../guide-agents.md).
325
326 - [AGENTS.md on every repository](agents-md.md)
327 - [Atom feeds](atom.md)
328 - [Guest pulls](guest-pulls.md)
329 - [How a person with no account gets in to contribute](guests.md)
330 - [OAuth refresh](oauth-refresh.md)
331 - [OAuth revoke](oauth-revoke.md)
332 - [OpenAPI and OAuth](openapi-oauth.md)
333 - [Opening /mcp in a browser](mcp.md)
334 - [Outside agents: a contribute token with no account](contribute-token.md)
335 - [Request access](request-access.md)
336 - [Security contact](security-contact.md)
337 - [Security controls](security-controls.md)
338 - [Stranger pulls](stranger-pulls.md)
339 - [The API reference](api-reference.md)
340 - [The API root](api-root.md)
341 - [The fence: what the forge's agent reads is data](conversation-fence.md)
342 - [The Muse test: how an outsider reports a problem](muse-test.md)
343 - [The report form for outsiders](report-form.md)
344 - [Which harness holds a token](tokens-harness.md)
345
346 ### Backups and moving
347
348 Read with the guide page [Backups and moving](../guide-backups-moving.md).
349
350 - [A forge is an origin](forge-origin.md)
351 - [A pull proposed to an origin, and its state coming back](origin-pull-state.md)
352 - [An app's encrypted backup, with a restore proof](app-backup.md)
353 - [An overdue off-box backup](backup-overdue.md)
354 - [Backups that cannot lie](backup-truth.md)
355 - [Connecting a friend's forge, whatever release it runs](forge-origin-older.md)
356 - [Connecting an origin read-only](origin-read-only.md)
357 - [Forge-to-forge compatibility, measured](forge-origin-compat.md)
358 - [How a fork follows its upstream](follow-mode.md)
359 - [Moving a forge out of this forge's process into its own sandbox](sandbox-move.md)
360 - [Moving a platform app to the forge (gretchy-stretchy, #11687)](platform-app-move.md)
361 - [Moving a repository to another owner](repo-transfer.md)
362 - [New commits upstream, on a mirror](origin-ahead.md)
363 - [Sending your forge's idea upstream, and pulling back](upstream-landing.md)
364 - [Taking updates from an origin you follow](follow-an-origin.md)
365 - [The backups line on Resilience](resilience-backups.md)
366 - [The off-site backup lane](offsite-lane.md)
367 - [The operator guard and proposing through your fork](origin-guard.md)
368 - [Which hosted forges are in use, and archiving one](forge-archive.md)
369
370 ### Every setting, by topic
371
372 Read with the guide page [Every setting, by topic](../guide-settings.md).
373
374 - [Account settings help](account-help.md)
375 - [Devices](devices.md)
376 - [Edge-only accounts](edge-only-accounts.md)
377 - [Knobs](knobs.md)
378 - [Manage account: reset a person's access](account-access.md)
379 - [Rotating the secret key](rotate-secret-key.md)
380 - [Sent to sign in by an app, and back again](signin-asking.md)
381 - [Taking the forge's own name](claim-own-name.md)
382 - [Trusted sources](trusted-sources.md)
383 - [Who can see it, in one line](visibility-line.md)
384 - [Your dotfiles in every shell](dotfiles.md)
385
386 ### When something is wrong
387
388 Read with the guide page [When something is wrong](../guide-when-wrong.md).
389
390 - [A child forge the host stopped](child-stopped.md)
391 - [A failed adapter pull speaks once in the writers' feed](sync-failed-feed.md)
392 - [A failing webhook is said once](webhook-failing.md)
393 - [A full disk](full-disk.md)
394 - [A rebuild that stopped](combined-rebuild-stopped.md)
395 - [A repeated review comment becomes a check](review-repeats.md)
396 - [Batch doctor](batch-doctor.md)
397 - [Blocked hosts](blocked-hosts.md)
398 - [Clog watch](clog-watch.md)
399 - [Content-Security-Policy reports](csp-reports.md)
400 - [Disk marks and the largest directories](disk-marks.md)
401 - [Disk readings per machine](disk-readings.md)
402 - [Events in the browser](events.md)
403 - [Flaky tests on main](check-flake.md)
404 - [Flow: declined runs](flow-declines.md)
405 - [/flow: what is clogging the lane](flow-clog.md)
406 - [How long the event log keeps what it holds](event-retention.md)
407 - [Interrupted out](interrupted-out.md)
408 - [Load test](load-test.md)
409 - [Main-thread stalls by route](stalls-by-route.md)
410 - [Maintenance, last 7 days](maintenance-week.md)
411 - [Memory held, not hit](memory-held.md)
412 - [Offline page](offline.md)
413 - [Pages over budget (real visitors)](slow-pages.md)
414 - [Pausing a webhook](webhook-pause.md)
415 - [Performance watcher](performance-watcher.md)
416 - [Pulls drifting from main](drift.md)
417 - [Red batches, named](red-batches.md)
418 - [Redeliver a failed webhook delivery](webhook-redeliver.md)
419 - [Refused first asks](forges-refused.md)
420 - [Screens and sideways scroll in the check's vitals](vitals-screens.md)
421 - [Send a webhook a test ping](webhook-ping.md)
422 - [The crew does not build the same thing twice](twin-runs.md)
423 - [The from_app alarm](from-app-alarm.md)
424 - [The gate cannot lock itself out](gate-bypass.md)
425 - [The lane has stopped](lane-stopped.md)
426 - [The rule watcher](rule-watcher.md)
427 - [Try again on an issue the crew parked twice](crew-try-again.md)
428 - [What holds a ready issue](map-held.md)
docs/guide-agents.md +2
@@ -32,3 +32,5 @@ forge tell "words"
3232 - The repository's `AGENTS.md`.
3333
3434 Reference: [MCP](MCP.md), [CLI](CLI.md), [roles](ROLES.md). Next: [Backups and moving](guide-backups-moving.md).
35
36 Every feature note, by topic: [the reference notes](features/README.md).
docs/guide-backups-moving.md +2
@@ -23,3 +23,5 @@ forge sync
2323 ```
2424
2525 Next: [Every setting, by topic](guide-settings.md).
26
27 Every feature note, by topic: [the reference notes](features/README.md).
docs/guide-first-app.md +2
@@ -53,3 +53,5 @@ forge tell "make the page say hello in big letters"
5353 Or open `/talk` and type it. What happens next is in [Tell the crew](guide-tell-the-crew.md).
5454
5555 If something does not work, see [When something is wrong](guide-when-wrong.md). The reference for the command is [CLI.md](CLI.md).
56
57 Every feature note, by topic: [the reference notes](features/README.md).
docs/guide-hosting.md +2
@@ -27,3 +27,5 @@ Billing is at `/settings/billing`. Connect your Stripe account there, make payme
2727 A hosted forge sleeps when idle and wakes on its next visit. Each person they add gets their own forge that follows theirs, so good changes flow both ways. The client list at `/forges` shows who was sent what and what happened.
2828
2929 Reference: [plans](features/plans.md), [new forge first minutes](features/new-forge-first-minutes.md), [the platform](PLATFORM.md). Next: [Bring your own AI](guide-own-ai.md).
30
31 Every feature note, by topic: [the reference notes](features/README.md).
outdated

52 bare slugs on one line. On a phone the tap targets sit against each other. Rows, or move the index to docs/features/README.md and link it once.

docs/guide-own-ai.md +2
@@ -28,3 +28,5 @@ For example, an app that calls a weather service lists that host in its `forge.j
2828 Your own assistant can drive the forge through the MCP: [Agents](guide-agents.md).
2929
3030 Reference: [the crew](CREW.md), [model grants](features/org-model-grant.md). Next: [Agents](guide-agents.md).
31
32 Every feature note, by topic: [the reference notes](features/README.md).
docs/guide-settings.md +2
@@ -27,3 +27,5 @@ forge whoami
2727 Admin work uses a separate account from the everyday one, and `/admin/limits` holds the limits and plans. Using AI with admin stays possible, but deliberate.
2828
2929 Reference: [operating](OPERATING.md), [roles](ROLES.md). Next: [When something is wrong](guide-when-wrong.md).
30
31 Every feature note, by topic: [the reference notes](features/README.md).
outdated

Misfiled by keyword: cmd-k-pull-actions, palette-rows, go-jumps, font, space and hotkey-hints are not settings. Place each where a reader would look for it.

docs/guide-ship-and-undo.md +2
@@ -32,3 +32,5 @@ Undo is itself a pull or a push, so it is checked and deployed like any other ch
3232 If you are not ready, leave the pull open: it stays previewed and nothing changes in production.
3333
3434 Reference: [pulls](PULLS.md), [apps](APPS.md), [cloning over git](GIT.md). Next: [Your apps](guide-your-apps.md).
35
36 Every feature note, by topic: [the reference notes](features/README.md).
outdated

feed-look, home-looks, first_look and pin-screenshots sit under Ship and undo by the 'look' keyword. Move or delete.

docs/guide-tell-the-crew.md +2
@@ -34,3 +34,5 @@ A run shows its state (queued, running, ok, failed) and its log. A red run says
3434 ## Related
3535
3636 Reference: [the crew](CREW.md), [asks](ASKS.md), [pulls](PULLS.md). Next: [Ship and undo](guide-ship-and-undo.md).
37
38 Every feature note, by topic: [the reference notes](features/README.md).
outdated

Principles 1, 7, 8: 59 links in one paragraph is not a list. One row per note, with a plain phrase saying what it covers. Many of these (flow-, ask-, crew-*) could also be grouped under a heading.

docs/guide-what-a-forge-is.md +2
@@ -31,3 +31,5 @@ Everything is private until you make it public, and each page says in one line w
3131 2. [Tell the crew](guide-tell-the-crew.md)
3232
3333 The reference behind this page is [the studio](STUDIO.md) and [the vision](VISION.md).
34
35 Every feature note, by topic: [the reference notes](features/README.md).
docs/guide-when-wrong.md +2
@@ -38,3 +38,5 @@ curl -s https://YOUR-FORGE/healthz
3838 Report a problem on the app's page, or tell the crew about the forge's own repository. Say what you did, what you saw, and what you expected.
3939
4040 Reference: [operating](OPERATING.md).
41
42 Every feature note, by topic: [the reference notes](features/README.md).
docs/guide-your-apps.md +2
@@ -36,3 +36,5 @@ The forge wakes a sleeping app at that time and calls the path. Printing a daily
3636 An app's own data lives under `FORGE_APP_DATA`. See [an app's encrypted backup](features/app-backup.md).
3737
3838 Reference: [apps](APPS.md). Next: [Hosting forges](guide-hosting.md).
39
40 Every feature note, by topic: [the reference notes](features/README.md).
src/actions/explore.ts +7 −6
@@ -472,7 +472,8 @@ export async function explore(
472472 query: ExploreQuery,
473473 now?: number,
474474 ): Promise<ExploreRow[]> {
475 return described(app, (await everything(app, viewer, query, now)).slice(0, ROWS));
475 const { rows, stamp } = await everything(app, viewer, query, now);
476 return described(app, rows.slice(0, ROWS), stamp);
476477 }
477478
478479 /** The rows as the API and the MCP send them: each with its `why` line when the ranking has one to say (omitted otherwise). */
@@ -512,12 +513,12 @@ export async function explorePage(
512513 if (after === null) return null;
513514 // The caller's narrowing comes first, so a page and its cursor only ever
514515 // hold rows the caller may see.
515 const all = await everything(app, viewer, query, now);
516 const { rows: all, stamp } = await everything(app, viewer, query, now);
516517 const rows = visible === undefined ? all : all.filter(visible);
517518 const rest = after === undefined ? rows : rows.filter((r) => compare(r, after, query) > 0);
518519 const items = rest.slice(0, limit);
519520 return {
520 items: await described(app, items),
521 items: await described(app, items, stamp),
521522 nextCursor: rest.length > limit ? writeCursor(items[items.length - 1]!, query) : null,
522523 total: rows.length,
523524 };
@@ -563,10 +564,10 @@ async function everything(
563564 viewer: User | undefined,
564565 query: ExploreQuery,
565566 now?: number,
566 ): Promise<readonly ExploreRow[]> {
567 ): Promise<{ readonly rows: readonly ExploreRow[]; readonly stamp: string | undefined }> {
567568 const forgeRows = await forges(app, viewer, query);
568569 const stamp = now === undefined ? writeStamp(app.db) : undefined;
569 if (stamp === undefined) return place(rank(app, viewer, query, now ?? Date.now()), forgeRows, query);
570 if (stamp === undefined) return { rows: place(rank(app, viewer, query, now ?? Date.now()), forgeRows, query), stamp };
570571 let tiers = ranked.get(app.db);
571572 if (tiers === undefined) {
572573 tiers = {
@@ -580,7 +581,7 @@ async function everything(
580581 const kept = clock.get(key, stamp, () =>
581582 inputs.get(key, rankInputs(app.db), () => rank(app, viewer, query, Date.now())),
582583 );
583 return place(kept, forgeRows, query);
584 return { rows: place(kept, forgeRows, query), stamp };
584585 }
585586
586587 /** The forges this forge spawned, for a site admin asking for them. */
src/core/readme_description.ts +25 −4
@@ -3,8 +3,11 @@
33 * README instead, for a public repository only; a missing README stays empty.
44 * Visibility comes from the row, which the rank read from the repository, so
55 * nothing here remembers it. The sentence is kept by repository and tip: a tip
6 * names its bytes, so an entry never goes stale. One helper for the page, the
7 * API and the MCP; escaping stays with the page that draws it.
6 * names its bytes, so an entry never goes stale. The tip itself is read from
7 * disk again only when the forge's write clock has moved or 5 s have passed,
8 * the rule the rank's own clock tier keeps, so a warm /explore reads no files
9 * (#3394). One helper for the page, the API and the MCP; escaping stays with
10 * the page that draws it.
811 */
912 import type { ExploreRow } from "../actions/explore.ts";
1013 import type { App } from "../app.ts";
@@ -15,15 +18,33 @@ import { readmeLine } from "./readme_line.ts";
1518 const lines = new Map<string, string>();
1619 const README_BYTES = 16 * 1024;
1720 const KEPT = 2000;
21 const TIP_MAX_AGE_MS = 5_000;
22 const tips = new Map<string, { readonly stamp: string; readonly at: number; readonly tip: string | undefined }>();
1823
19 export async function described(app: App, rows: readonly ExploreRow[]): Promise<ExploreRow[]> {
24 async function tipOf(dir: string, branch: string, stamp: string | undefined): Promise<string | undefined> {
25 const kept = tips.get(dir);
26 const now = Date.now();
27 if (stamp !== undefined && kept !== undefined && kept.stamp === stamp && now - kept.at < TIP_MAX_AGE_MS) return kept.tip;
28 const tip = await refTip(dir, `refs/heads/${branch}`);
29 if (stamp !== undefined) {
30 if (tips.size >= KEPT) tips.clear();
31 tips.set(dir, { stamp, at: now, tip });
32 }
33 return tip;
34 }
35
36 /**
37 * `stamp` is the write clock the rank itself read before computing, so a warm
38 * /explore reads the clock once; with none (a rank asked cold) every tip is read.
39 */
40 export async function described(app: App, rows: readonly ExploreRow[], stamp: string | undefined): Promise<ExploreRow[]> {
2041 return Promise.all(
2142 rows.map(async (row) => {
2243 const repo = row.repo;
2344 if (row.kind !== "app" || row.description !== "" || repo === undefined || !repo.public) return row;
2445 try {
2546 const dir = repoDir(app.reposRoot, repo.owner, repo.name);
26 const tip = await refTip(dir, `refs/heads/${repo.branch}`);
47 const tip = await tipOf(dir, repo.branch, stamp);
2748 if (tip === undefined) return row;
2849 const key = `${repo.id}:${tip}`;
2950 let line = lines.get(key);
src/web/standards.ts +6 −1
@@ -53,6 +53,7 @@ import { agentCard, toolsKey, apiCatalog, cardsLine, DISCOVERY, mcpCard, offered
5353 import { forgeDocument } from "../core/standards_index.ts";
5454 import { TAGS } from "../contract/served.ts";
5555 import { running } from "../kernel/version.ts";
56 import { GUIDE } from "../view/guide.ts";
5657 import { loadMcp } from "../http/mcp/load.ts";
5758 import { timePhase, timePhaseAsync } from "../core/route_timing.ts";
5859 import { shippedReleases, type Shipped } from "../release/shipped.ts";
@@ -479,6 +480,11 @@ function renderLlmsTxt(ctx: Ctx, o: string, tell: string | undefined, running: s
479480 "",
480481 `> ${SITE_LINE} A self-hosted forge in one Bun process and one SQLite file that hosts code and runs apps, with AI agents that build. Forges connect. Part of Open Platform (https://www.open-platform.sh). Anyone may read a public repository and report a problem in it.`,
481482 "",
483 "## The guide (read these first)",
484 "",
485 `- With search: ${o}/docs`,
486 ...GUIDE.map((page) => `- ${o}/docs/${page}`),
487 "",
482488 ...threeDoors(o, mcp.url),
483489 "## Start here",
484490 "",
@@ -489,7 +495,6 @@ function renderLlmsTxt(ctx: Ctx, o: string, tell: string | undefined, running: s
489495 `- Run it yourself instead: \`git clone ${UPSTREAM_REPO}.git && cd forge && bun install && bun run src/main.ts\`, then in a second terminal \`bun src/main.ts --first-admin\`, which prints a one-time link that makes you the admin. It needs Bun; its crew needs a runner CLI and a model credential. Or hosted (plans below): ${o}/forges/new, or MCP \`spawn\` with the person's consent. A hosted forge sleeps when idle and wakes on its next page load, push or API call; on the free plan the person brings their own model credential, or its crew stays off.`,
490496 `- Work from your own forge: connect it to this one as an origin, bring an app in, and send your work back. How: ${UPSTREAM_REPO}/raw/main/docs/ORIGINS.md`,
491497 `- Connect an assistant that uses tools: custom connector URL ${mcp.url} (OAuth); start and report need no account.`,
492 `- The guide, with search: ${o}/docs (${o}/docs/guide-first-app.md, ${o}/docs/guide-agents.md)`,
493498 "",
494499 "## Plans",
495500 "",
test/explore-description.test.ts +9
@@ -131,6 +131,15 @@ test("a repository that goes private stops saying its README at once", async ()
131131 expect(anon.some((r) => r.name === "maker/flips")).toBe(false);
132132 });
133133
134 test("a push that changes the README is said on the next read: the kept tip does not outlive a write", async () => {
135 const repo = await appWith("moves", { readme: "First words.\n", visibility: "public" });
136 expect(await said("moves")).toBe("First words.");
137 expect(await said("moves")).toBe("First words.");
138 const c = await commitToBranch(app, owner, repo, { message: "Again", files: [{ path: "README.md", content: "Second words.\n" }] });
139 if (!c.ok) throw new Error(String(c.error));
140 expect(await said("moves")).toBe("Second words.");
141 });
142
134143 test("the page escapes a README sentence", async () => {
135144 await appWith("evil", { readme: "Tom & <script>alert(1)</script> \"quoted\" garden.\n", visibility: "public" });
136145 const html = await (await fetch(`${servers.url}/explore?kind=app`)).text();
test/feature-orphans.test.ts added +48
@@ -0,0 +1,48 @@
1 /**
2 * Every docs/features note has one row in the reference index,
3 * docs/features/README.md, and every guide page links that index (#12529).
4 * The index is rows, one note to a list item, so it reads on a phone.
5 */
6 import { expect, test } from "bun:test";
7 import { readdirSync, readFileSync } from "node:fs";
8 import { GUIDE } from "../src/view/guide.ts";
9
10 const index = readFileSync("docs/features/README.md", "utf8");
11 const notes = readdirSync("docs/features").filter((n) => n.endsWith(".md") && n !== "README.md");
12
13 test("no feature note is an orphan", () => {
14 const orphans = notes.filter((n) => !index.includes(`](${n})`));
15 expect(orphans, `give each a row in docs/features/README.md under its topic, or delete it: ${orphans.join(", ")}`).toEqual([]);
16 });
17
18 test("the index is one note to a row, each named in words, each once", () => {
19 const rows = index.split("\n").filter((l) => /\]\([\w.-]+\.md\)/.test(l) && !l.includes("../"));
20 for (const row of rows) {
21 const m = row.match(/^- \[([^\]]+)\]\(([\w.-]+\.md)\)$/);
22 expect({ row, ok: m !== null }).toEqual({ row, ok: true });
23 // The link says what the note tells you, not its file name.
24 expect({ row, slug: m?.[1] === m?.[2]?.replace(/\.md$/, "") }).toEqual({ row, slug: false });
25 }
26 const linked = rows.map((r) => r.match(/\(([\w.-]+\.md)\)$/)?.[1]);
27 expect(new Set(linked).size).toBe(linked.length);
28 expect(linked.length).toBe(notes.length);
29 expect(index).toContain("## Reference notes");
30 });
31
32 test("every guide page links the index, and none carries a list of notes itself", () => {
33 for (const page of GUIDE) {
34 const text = readFileSync(`docs/${page}`, "utf8");
35 expect({ page, links: text.includes("](features/README.md)") }).toEqual({ page, links: true });
36 expect({ page, notes: (text.match(/\]\(features\/(?!README)[\w.-]+\.md\)/g) ?? []).length <= 3 }).toEqual({ page, notes: true });
37 }
38 });
39
40 test("AGENTS.md names the spine pages first, in the guide's order", () => {
41 const agents = readFileSync("AGENTS.md", "utf8");
42 const at = GUIDE.map((p) => agents.indexOf(`docs/${p}`));
43 expect(at.every((i) => i >= 0)).toBe(true);
44 expect([...at].sort((a, b) => a - b)).toEqual(at);
45 // Before any other doc or source path the file sends a reader to.
46 const firstOther = agents.search(/`(?:docs\/(?!guide-)|src\/)/);
47 expect(at[at.length - 1] ?? 0).toBeLessThan(firstOther);
48 });
test/llms-anonymous.test.ts +9
@@ -97,3 +97,12 @@ test("the OpenAPI line names ?tag= and the tags", async () => {
9797 expect(line).toContain("?tag=");
9898 expect(line).toContain("pulls");
9999 });
100
101 test("llms.txt lists the guide spine pages first, in order, before the doors", async () => {
102 const { GUIDE } = await import("../src/view/guide.ts");
103 const body = await (await fetch(`${servers.url}/llms.txt`)).text();
104 const at = GUIDE.map((p) => body.indexOf(`${servers.url}/docs/${p}`));
105 expect(at.every((i) => i > 0)).toBe(true);
106 expect([...at].sort((a, b) => a - b)).toEqual(at);
107 expect(at[at.length - 1]).toBeLessThan(body.indexOf("## Start here"));
108 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs