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

Shared lists are generated, not hand-edited: the features index, the docs README, the design file and the rosters are where pulls collide #14267

opened this in answer to

Check · Review · Land · Live — No review yet. Next: reviewer, no review yet.

Ready to land

mason/forge:mason/14248-shared-lists-are-generated-not-hand-edit → main 4 commits fork

Review

Sign in to review this change.
514 files changed +2199 −517
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 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`).
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; open it with front matter `topic:` and `row:` (#14248), which builds its row in `docs/features/README.md`, the index every spine page links; never edit that list by hand (`test/feature-orphans.test.ts`).
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`, `src/web/studio/*.ts` or `src/actions/*.ts` is asked for the screen alone, and a new feature module under `src/` in a pull that edits an existing page is asked for both, and a pull that edits an existing page (or any shared `src/web/` file, #13376: a new feature module wired into it is asked for both) changes something under `src/tui/` and a `docs/features/*.md` too (#13196); an edited API route, MCP tool or `src/actions/*.ts` changes something under `src/tui/` too (#14040); `bun scripts/gate.ts` refuses it otherwise ("both doors", #10628).
docs/features/README.md +17 −512
@@ -10,576 +10,81 @@ are.
1010
1111 Every note is listed once below, under the topic a reader would look in; the
1212 topics follow [the guide](../guide-what-a-forge-is.md).
13 A new note gets a row here (`test/feature-orphans.test.ts`).
13 The rows are built from the notes, not typed here (#14248): a note opens with front matter,
14 `topic:` (one of the headings below) and `row:` (the words of its row), and the index lists it
15 (`src/view/feature_index.ts`, checked by `test/feature-orphans.test.ts`). A new note edits no
16 other file; add a heading here only for a new topic.
1417
1518 ### What a forge is
1619
1720 Read with the guide page [What a forge is](../guide-what-a-forge-is.md).
1821
19 - [A forge made from a template says so on its home](started-from.md)
20 - [First week: three steps on a new forge's home](first-week.md)
21 - [The crew on a forge link's page](crew-now.md)
22 - [A hosted forge proposes to its parent once the parent has handed it a credential](propose-to-parent.md)
23 - [How long the last forge from a template took, at /templates/<name>](template-timing.md)
24 - [What a template holds: its files, run and check lines, on /templates](template-holds.md)
25 - [A look in the feed](feed-look.md)
26 - [One step deeper from a post](feed-depth.md)
27 - [A fork's page finds its place in the tree](fork-tree-here.md)
28 - [Open pulls red for over a day are named in one issue](red-pulls.md)
29 - [A pull whose check is queued behind a red main says "waiting on main"](pull-waiting-on-main.md)
30 - [Empty lists](empty-words.md)
31 - [An app with no description says its README](readme-description.md)
32 - [Arcade carts](arcade-carts.md)
33 - [How far behind a followed fork is](fork-behind.md)
34 - [How far behind each fork in the tree is](fork-tree-behind.md)
35 - [Changelog](changelog.md)
36 - [Tell the crew from any shell with ssh and tell](tell-from-ssh.md)
37 - [/docs](docs-link.md)
38 - [Engine shape](engine-shape.md)
39 - [Feed fold](feed-fold.md)
40 - [Filter the feed by one app](feed-app-filter.md)
41 - [Narrow the feed to crew, yours or ships](feed-filters.md)
42 - [Questions on an issue](question.md)
43 - [A refused comment keeps its words](comment-refused.md)
44 - [A feed post has a permalink](feed-permalink.md)
45 - [A run post opens its log](feed-run-log.md)
46 - [Feed likes: the ledger](feed-like-ledger.md)
47 - [Reply to an issue post in the feed](feed-reply.md)
48 - [Forge packs: a premade forge to deploy (`/packs`)](packs.md)
49 - [Home paints its frame first](home-frame.md)
50 - [Behaviors: shared interactions, attached by attribute](behaviors.md)
51 - [Is v1.0.0 proven?](v1-proven.md)
52 - [Looks of `/` signed out](home-looks.md)
53 - [Milestones at the front door](front-milestones.md)
54 - [Migration mode: a crew whose standing job is parity](migration-mode.md)
55 - [Data move: a platform app's Postgres through the drop into the app's store, with a receipt and an undo](data-move.md)
56 - [Cut over: check a domain against the platform, move it to the forge app with a receipt, undo in one step](cut-over.md)
57 - [Now pages and Repositories](now-pages.md)
58 - [Pixel art: the crew's faces](pixel.md)
59 - [Plans on the home](home-plans.md)
60 - [Returning visitors](returning-visitors.md)
61 - [Template mark](repo-template.md)
62 - [What a template gives: apps, starter budget, model](template-page-gets.md)
63 - [Who changed a setting, and when](setting-history.md)
64 - [A new forge can start from a template repository](new-forge-template.md)
65 - [Spawn a forge from a config, and keep it as a recipe](spawn-recipes.md)
66 - [Made from: the template a forge came from](made-from.md)
67 - [The explorer's sorts](explore.md)
68 - [The feed pages by cursor](feed-cursor.md)
69 - [What shipped on public apps, signed out](public-feed.md)
70 - [The fork tree](fork-tree.md)
71 - [A busy branch of the forge family folds](family-collapse.md)
72 - [The home](living-home.md)
73 - [The quiet feed names its one next thing](quiet-feed.md)
74 - [The feed says how many posts are new since your last visit](feed-new-count.md)
75 - [The roadmap](roadmap.md)
22 <!-- notes -->
7623
7724 ### Getting around: keys, the palette and search
7825
79 - [A mistyped repository address offers close ones](did-you-mean.md)
80 - [Cmd-K: a pull's actions](cmd-k-pull-actions.md)
81 - [Cmd-K: repositories and their apps](cmd-k-repositories.md)
82 - [`g` then a letter: jump between pages](go-jumps.md)
83 - [Hotkey hints](hotkey-hints.md)
84 - [The 404 offers the pages nearest the path asked](near-pages.md)
85 - [The 404 says what happened in one line and offers home, sign-in and search](not-found-page.md)
86 - [Lists that ask for a decision answer the same keys](decision-keys.md)
87 - [Page help (`? Help`)](page-help.md)
88 - [Palette rows: numbers, people, settings, actions](palette-rows.md)
89 - [Phone search is the palette](search-is-palette.md)
90 - [Search finds guides](search-finds-guides.md)
91 - [Pick list](pick-list.md)
92 - [The empty palette lists what you opened last](palette-recent.md)
26 <!-- notes -->
9327
9428 ### Your first app in five minutes
9529
9630 Read with the guide page [Your first app in five minutes](../guide-first-app.md).
9731
98 - [Bring an app from another forge (`/bring`)](bring.md)
99 - [Display](display.md)
100 - [Displays list](displays.md)
101 - [Make it yours](make-it-yours.md)
102 - [New app, from the terminal](new-app.md)
103 - [Plain git contributes](plain-git.md)
104 - [Clones yield to pages](clone-pacing.md)
105 - [Send a change without a forge of your own](send-a-change.md)
106 - [Start: an agent builds with only the forge's URL](start.md)
107 - [The account screen of a forge you just started](welcome.md)
108 - [The line about a sent forge's first screen](first-screen-line.md)
109 - [Home after the first ask](home-after-first-ask.md)
110 - [Where a new app stands](onboarding-line.md)
32 <!-- notes -->
11133
11234 ### Tell the crew
11335
11436 Read with the guide page [Tell the crew](../guide-tell-the-crew.md).
11537
116 - [Take a tell back within a minute, while unread](tell-undo.md)
117 - [Dictate into the tell box](speak.md)
118 - [Send a tell with Ctrl or Cmd+Enter](composer-send-key.md)
119 - [A bug closes with a reason](bug-close.md)
120 - [A business, as a map](atlas-plan.md)
121 - [A maintainer keeps the code easy to change, and nothing else](crew-maintainer.md)
122 - [Switch a repository's crew off](crew-switch.md)
123 - [A new app starts the crew on it](new-app-crew.md)
124 - [A new forge builds at once](starter-crew.md)
125 - [A new issue from any page](new-issue-anywhere.md)
126 - [A run's state is worked out from what it did](run-state.md)
127 - [A team is told once that a pull waits on its review](team-waits.md)
128 - [A tell from a preview's toolbar carries its pull](toolbar-tell.md)
129 - [A tell's page says what became of it](tell-status.md)
130 - [Tell the crew from the terminal's screen: key M](tell-from-here.md)
131 - [A write the restart cut short, in a conversation](talk-resume-writes.md)
132 - [Actions that answer at once](act-now.md)
133 - [Starter prompts in an empty conversation](talk-starters.md)
134 - [A thread folds its settled history](thread-fold.md)
135 - [An agent says what it does; a repo's team is three lists](crew-roles.md)
136 - [An assigned ask can be settled where it stands](ask-settles.md)
137 - [Ask filters](ask-filters.md)
138 - [Ask to reach a host](ask-to-reach.md)
139 - [Attention budgets](attention.md)
140 - [Bets](bets.md)
141 - [Bugs on a clock](bugs.md)
142 - [Chapters: a version with an end](chapters.md)
143 - [The open chapter's bar on the home](chapter-bar.md)
144 - [Each app with its crew member](app-crew.md)
145 - [The app's page: detail on demand](app-page-details.md)
146 - [Estimates](estimates.md)
147 - [Flow keeper](flow-keeper.md)
148 - [Flow line actions](flows-actions.md)
149 - [/flow: pulls closed unmerged after a CPU stop](flow-cpu.md)
150 - [Flow: the week's budget as pipes](flow-valves.md)
151 - [Flow: waiting](flow-waiting.md)
152 - [Flow: where the crew gives up](flow-handover.md)
153 - [Flows](flows.md)
154 - [Flows across the forge](admin-flows.md)
155 - [Give a team member a role](team-roles.md)
156 - [Everyone with an account, last seen first](people.md)
157 - [Hold new work on a file](file-holds.md)
158 - [Maintenance duties](maintain.md)
159 - [See what waits for you: /?waits=me, and the terminal's Waiting for me](waits-for-me.md)
160 - [Preview data of pulls closed over seven days](preview-dirs.md)
161 - [Muting from the inbox keeps you in place](asks-mute-undo.md)
162 - [Next up](next-up.md)
163 - [Next up says why a ready issue is not started](next-up-why.md)
164 - [Notes](notes.md)
165 - [Refused first asks](first-ask.md)
166 - [Share to the forge from a phone](share-to-the-forge.md)
167 - [Since you were here](since-you-were-here.md)
168 - [/talk answers "what needs me?"](talk-decisions.md)
169 - [/talk slash commands: /issue, /pull, /wallet](talk-slash.md)
170 - [Talk as a builder](talk-builder.md)
171 - [Answering a proposed action: Do it and Not now](talk-answer-action.md)
172 - [/talk attachments](talk-attachments.md)
173 - [Talk runs the captain](talk-captain.md)
174 - [Talk to the forge's agent](talk.md)
175 - [Stopping a Talk answer](talk-stop.md)
176 - [Talk answers link the issue and pull numbers they cite](talk-links.md)
177 - [A line said in Talk that became work answers with a receipt](talk-filed.md)
178 - [Dictate a message into the /talk box, on the device](talk-dictation.md)
179 - [Tell the crew from a share, with a look before it files](share-tell.md)
180 - [The crew line on Home](crew-line.md)
181 - [The crew list](crew-list.md)
182 - [The crew's runs on the desk](desk-runs.md)
183 - [The crew's week](crew-week-card.md)
184 - [The crew's week shows which pulls came back](crew-week-returned.md)
185 - [Tokens and price per million on each crew-activity row](crew-row-price.md)
186 <!-- ssh -->
187 - [The first ask by ssh makes an app](ssh-first-ask.md)
188 <!-- /ssh -->
189 - [The governor's line](governor-line.md)
190 - [The map, lightly](map.md)
191 - [The pulls a crew team's review holds](team-waiting.md)
192 - [The pulls waiting on a crew team](team-queue.md)
193 - [The open-issue ceiling](planner-ceiling.md)
194 - [A crew beside a backlog says why it stands still](backlog-beside-idle.md)
195 - [The queue](queue.md)
196 - [The space](space.md)
197 - [The thank-you note](thanks.md)
198 - [The week is one budget for the whole crew](crew-week.md)
199 - [The week's pace](week-pace.md)
200 - [Closing a chapter writes its wave](chapter-wave.md)
201 - [Walking a wave](wave-walk.md)
202 - [The wave-standing line](wave-standing.md)
203 - [How many of a wave's changes are live and waiting to ship](wave-landing.md)
204 - [How close a wave is to done](wave-landed.md)
205 - [What a repository with no waves says and offers](wave-empty.md)
206 - [Reading a wave's pulls, newest landed first, with who merged each](wave-pulls-order.md)
207 - [How long a wave took, or has been open](wave-duration.md)
208 - [What became of the first ask](ask-status.md)
209 - [When a setting or a permission stands in the way](blocked-by.md)
210 - [The map's growth line](map-growth.md)
211 - [Your team](team.md)
38 <!-- notes -->
21239
21340 ### Ship and undo
21441
21542 Read with the guide page [Ship and undo](../guide-ship-and-undo.md).
21643
217 - [One notice per release](release-notice.md)
218 - [A forge killed in the middle of a merge](merge-crash-recovery.md)
219 - [A person's reopen stands](done-on-main.md)
220 - [A preview of the forge, looked at as its owner](preview-owner-looks.md)
221 - [The daily count of look pages in the check log](look-count.md)
222 - [A pull opens on its verdict](pull-verdict.md)
223 - [A pull's looks](pull-looks.md)
224 - [An approval says what it was given for](approval-base.md)
225 - [An approved pull that has waited a week](approved-week.md)
226 - [Build cache](build-cache.md)
227 - [Build pins](build-pins.md)
228 - [Build preview](build-preview.md)
229 - [Code scanning](code-scanning.md)
230 - [Detach a fork from its parent](detach.md)
231 - [Iterations](iterations.md)
232 - [Land it as it is](land-as-is.md)
233 - [Landing a fork's pull in slices](pull-slices.md)
234 - [Naming the approved pull that waits](approved-named.md)
235 - [Nightly jobs](nightly.md)
236 - [One path: check, review, land, live](pipeline.md)
237 - [Pin screenshots](pin-screenshots.md)
238 - [Pulls untouched for 14 days](stale-pulls.md)
239 - [Ranked checks](ranked-checks.md)
240 - [Runners: a check on another machine, with a URL and a token](runners.md)
241 - [A repository stuck behind its pulls](stuck-pile.md)
242 - [A beat the forge owns, and a gate on the push](beat.md)
243 - [Release heartbeat and the main-ahead alarm](release-heartbeat.md)
244 - [Release keeper](release-keeper.md)
245 - [Release what the Later gate holds](release-later.md)
246 - [Reviews are something an owner turns on](reviews-off-lands-on-green.md)
247 - [The forge ships itself](ship-itself.md)
248 - [The landing line: when an approved pull will land](landing-line.md)
249 - [The Later gate in plain sight](later-gate.md)
250 - [The merge queue's gates, by failing test](queue-gates.md)
251 - [The polish share](polish-share.md)
252 - [The throughput keeper](keeper.md)
253 - [Variants](variants.md)
254 - [What a deploy carries, and when each change first went live](deploy-pull-retention.md)
44 <!-- notes -->
25545
25646 ### Your apps
25747
25848 Read with the guide page [Your apps](../guide-your-apps.md).
25949
260 - [An app refused an outside host says so in the forge's words](app-egress-refused.md)
261 - [What the crew is doing, as one sentence per app](apps-crew-sentence.md)
262 - [A child forge's own source](own-source.md)
263 - [A forge that runs its own code](own-code.md)
264 - [Absorb, reviewed from several angles](absorb-review.md)
265 - [Absorb: an app becomes one of the forge's features](absorb.md)
266 - [Adapter facts on the app page and in the terminal](adapters-card.md)
267 - [An app cannot stall the forge](app-asking.md)
268 - [An app's own domain: cut-over and the way back](app-own-domain.md)
269 - [App templates](app-templates.md)
270 - [Template page](template-page.md)
271 - [Find a template by a word in its name or description](templates-search.md)
272 - [Archive listing](archive-listing.md)
273 - [Archive an app: it spins down, hides from lists, stays reachable](app-archive.md)
274 - [A binary file shows its size and type](binary-file.md)
275 - [An OPML or RSS/Atom file opens as its entries](feed-xml.md)
276 - [A big .log or .txt opens its last lines](log-tail.md)
277 - [Crawl budget](crawl-budget.md)
278 - [Data browser (core)](data-browser.md)
279 - [Database size](db-size.md)
280 - [Durable jobs](jobs.md)
281 - [The drop: a private place per app for what the crew cannot find in the repository](drop.md)
282 - [First look at a note from an app](first_look.md)
283 - [Maintenance: shut down for a move and come back by itself](maintenance.md)
284 - [Measuring a page: height and words](measure-page.md)
285 - [New app from a template](app-template.md)
286 - [One place for a secret (`Settings → App → Secrets this app uses`)](app-secrets.md)
287 - [Pause and resume a maintenance duty](maintenance-duties.md)
288 - [Dismiss a duty's finding for seven days](duty-dismiss.md)
289 - [Pinned toolchains (rust)](toolchains.md)
290 - [A run's page folds its steps and its log](run-folds.md)
291 - [A run's cost line shows tokens and the price per million](run-price.md)
292 - [Scheduled tools: the forge calls an absorbed app's tool on time](feature-schedule.md)
293 - [Scrape evidence](scrapes.md)
294 - [The box pass](box-pass.md)
295 - [A table downloads as CSV](data-csv.md)
296 - [The data explorer starts from a question](data-explorer.md)
297 - [The data explorer's sentence box](data-explorer-sentence.md)
298 - [The forge toolbar](forge-toolbar.md)
299 - [Timers and schedules](timers.md)
300 - [Traffic](traffic.md)
301 - [Where people come from and where they go](traffic-sources.md)
302 - [Whose wait it was: the forge's or the app's](app-slowest-wait.md)
50 <!-- notes -->
30351
30452 ### Files in the browser
30553
306 - [Every kind of file the viewer opens, and how large](file-kinds.md)
307 - [A PDF's page count, title and author above the viewer](pdf-facts.md)
308 - [A file too large to draw says so in one line](undrawable-file.md)
309 - [An .obj or .ply file opens in the 3D viewer](mesh-files.md)
310 - [An .stl file as a 3D model](file-stl.md)
311 - [A .dxf file as a picture](file-dxf.md)
312 - [Mermaid, draw.io and Excalidraw files](file-diagrams.md)
313 - [A .psd file: facts, preview and layers](psd.md)
314 - [A .har file as a request waterfall](file-har.md)
315 - [A .sarif file opens as its findings](file-sarif.md)
316 - [A `.env.example` opens as the variables an app needs](file-env.md)
317 - [A `.sql` file opens as its schema](file-sql.md)
318 - [A `Dockerfile` opens as its stages](file-dockerfile.md)
319 - [An .epub opens as its title, author and chapters](file-epub.md)
320 - [A `Makefile` opens as its targets](file-makefile.md)
321 - [A `package.json` opens as its manifest](file-package-json.md)
322 - [A compose file opens as its services](file-compose.md)
323 - [A GitHub Actions workflow opens as its jobs](file-workflow.md)
324 - [A GraphQL schema opens as its types](file-graphql.md)
325 - [A `.mbox` file opens as its messages and a `.proto` as its outline](file-mbox-proto.md)
326 - [`.ini`/`.properties`, `.rtf` and `.xml` files open readable](file-ini-rtf-xml.md)
327 - [A JUnit XML report opens as its results](file-junit.md)
328 - [An .eml file opens as a message](file-eml.md)
329 - [An lcov coverage file opens as its coverage](file-lcov.md)
330 - [An OpenAPI document opens as its operations](file-openapi.md)
331 - [Calendar files (.ics) as a list of events](ics.md)
332 - [Config files as a form](config-form.md)
333 - [A refused form keeps what was typed](form-keeps-input.md)
334 - [Contacts files (.vcf) as a list of people](vcf-view.md)
335 - [CSV and TSV as a table](csv-view.md)
336 - [A big JSON file opens as its first level](json-big.md)
337 - [Video-edit timelines (.otio, .edl, .fcpxml) as a cut list](timeline-cut-list.md)
338 - [Files in the browser: the media route and the kind registry](file-media.md)
339 - [Font specimens](font.md)
340 - [G-code layers](gcode.md)
341 - [STEP (.step, .stp) as a part card](step.md)
342 - [GeoJSON (.geojson) as an outline and a properties table](geojson.md)
343 - [GPS tracks (.gpx) as a route outline](gpx.md)
344 - [HTML preview](html-preview.md)
345 - [KML maps (.kml) as a placemark table](kml.md)
346 - [A half-written tell is kept](kept-tell.md)
347 - [Jupyter notebooks](notebook.md)
348 - [Markdown relative images and links](markdown-relative.md)
349 - [Markdown front matter as a list of facts](front-matter.md)
350 - [Notebooks, JSON Lines and logs in the terminal](terminal-workspace-kinds.md)
351 - [Shift a subtitle file](subtitle-shift.md)
352 - [SQLite files as tables](sqlite-view.md)
353 - [Parquet files as their columns and row groups](parquet.md)
354 - [Excel workbooks (.xlsx) as a table](xlsx.md)
355 - [Office documents and layered images (.docx, .pptx, .ora)](office.md)
356 - [Subtitles as a transcript](subtitles.md)
357 - [Terminal logs in colour](ansi-log.md)
54 <!-- notes -->
35855
35956 ### Hosting forges for others, and getting paid
36057
36158 Read with the guide page [Hosting forges for others, and getting paid](../guide-hosting.md).
36259
363 - [A child forge's cores, held by pausing where the kernel cannot](child-cpu-pausing.md)
364 - [A child forge's disk bandwidth is capped by its size](child-disk-bandwidth.md)
365 - [A child forge's own filesystem](child-filesystem.md)
366 - [A claimed child receives the credential to propose back to its parent](child-proposal-credential.md)
367 - [A client's monthly bill](forge-bill.md)
368 - [A forge for a client, from one link](client-forge.md)
369 - [Regenerating a client forge's claim link](regenerate-client-link.md)
370 - [The sentence under each of a client's apps, on the page, in the terminal and in forge_view](client-app-line.md)
371 - [The client list's three times: sent, opened, first tell](client-link-times.md)
372 - [A forge whose billing is none](lapsed-forge.md)
373 - [A forge's claim link as a QR in the terminal](forge-link-qr.md)
374 - [A forge's own key and budgets](own-forge-budgets.md)
375 - [A forge's size and use on /system](forge-size-use.md)
376 - [A machine shell's first screen](machine-shell-rc.md)
377 - [A new forge's first ten minutes](new-forge-first-minutes.md)
378 - [A pinned forge](pinned-forge.md)
379 - [Billing](billing.md)
380 - [Buy a forge at /pricing](pricing.md)
381 - [What a paid forge is, at /terms](billing.md#what-a-paid-forge-is-at-terms-13207)
382 - [Buy links](billing-links.md)
383 - [Capacity flags a count set below its ceiling](capacity.md)
384 - [CPUs kept for the forge's own process](serving-cores.md)
385 - [Cloud accounts](cloud.md)
386 - [Disks on the machines page](machines-disks.md)
387 - [Does a forge I sent answer yet?](forge-ready.md)
388 - [End a forge link, and undo it](forge-link-revoke.md)
389 - [What a forge link says when it no longer works](forge-link-dead.md)
390 - [Fleet rows](fleet.md)
391 - [Forge it](forge-it.md)
392 - [/forges side by side](forges-side-by-side.md)
393 - [Growth and the planner switch](growth.md)
394 - [Hosted forges that scale to zero](forge-sleep.md)
395 - [How fast a team ships, and what it costs](team-metrics.md)
396 - [How is my forge?](forge-needs.md)
397 - [How much each seat may do at once](seat-slots.md)
398 - [Is a forge name free?](forge-name.md)
399 - [Machines](machines.md)
400 - [Maintenance duty budgets](maintenance-budgets.md)
401 - [Plans](plans.md)
402 - [Real-cell proof: the build half, in process](real-cell-proof.md)
403 - ["Running" is proven from outside](child-reach.md)
404 - [Start my forge](start-my-forge.md)
405 - [Stripe checkout binding](stripe-checkout-binding.md)
406 - [Telemetry readers](telemetry-readers.md)
407 - [The forge view (`GET /api/v1/forge/view`)](forge-view.md)
408 - [The forge's spend in the terminal](forge-usage-terminal.md)
409 - [The last Stripe event and refused signatures](stripe-events-line.md)
410 - [The money line — cost, revenue and the gap](money.md)
411 - [The repository wallet — the last 20 spends](wallet.md)
412 - [A wallet running low — one line for admins under 20% left](wallet-low.md)
413 - [The page that answers "make me a forge"](forge-made.md)
414 - [The Plan row in a forge's settings](plan-row.md)
415 - [The selling funnel](selling-funnel.md)
416 - [A taken forge name: refused with two free ones](spawn-name-taken.md)
417 - [The spawner's claim link](spawner-claim-link.md)
418 - [The statement — what the forge would charge an app](statement.md)
419 - [Ways to the fleet graph](fleet-graph-doors.md)
420 - [What a forge costs](footprint.md)
421 - [What a sized forge's cores mean for builds](cores-row.md)
422 - [What the forge stands on](footing.md)
423 - [Where a sent forge link stands](forge-link-states.md)
424 - [Your shells](my-shells.md)
60 <!-- notes -->
42561
42662 ### Bring your own AI
42763
42864 Read with the guide page [Bring your own AI](../guide-own-ai.md).
42965
430 - [A child forge's cell may reach its model provider](child-model-egress.md)
431 - [A forge with no model key](no-model-key.md)
432 - [A parent funds a child's crew](child-credit.md)
433 - [Hosted forges' cores and the xlarge size](hosted-forge-cores.md)
434 - [A child's proposal says what the child proved](child-attestation.md)
435 - [An org's model account](org-model-grant.md)
436 - [Cost ledger](cost-ledger.md)
437 - [Cost by day](cost-days.md)
438 - [Economics: the profit slider, its prices and what the month costs](economics.md)
439 - [Escalate to Opus by need](model-escalation.md)
440 - [Issue cost: what an issue and its pulls spent](issue-cost.md)
441 - [Dependency standing: what an issue waits for, read at a glance](dependency-standing.md)
442 - [Mirror credit](mirror-credit.md)
443 - [The OpenAI-compatible runner](openai-runner.md)
444 - [The weekly model review](model-review.md)
66 <!-- notes -->
44567
44668 ### Agents: MCP, git, or the terminal
44769
44870 Read with the guide page [Agents: MCP, git, or the terminal](../guide-agents.md).
44971
450 - [AGENTS.md on every repository](agents-md.md)
451 - [Atom feeds](atom.md)
452 - [Guest pulls](guest-pulls.md)
453 - [How a person with no account gets in to contribute](guests.md)
454 - [OAuth consent words](oauth-consent.md)
455 - [Connected agents](oauth-grants.md)
456 - [OAuth refresh](oauth-refresh.md)
457 - [OAuth revoke](oauth-revoke.md)
458 - [OpenAPI and OAuth](openapi-oauth.md)
459 - [Opening /mcp in a browser](mcp.md)
460 - [Health, spoken in two sentences](health-voice.md)
461 - [The desk over the API and the event stream](desk.md)
462 - [Outside agents: a contribute token with no account](contribute-token.md)
463 - [Request access](request-access.md)
464 - [Security contact](security-contact.md)
465 - [Security controls](security-controls.md)
466 - [Stranger pulls](stranger-pulls.md)
467 - [The API reference](api-reference.md)
468 - [The API root](api-root.md)
469 - [The fence: what the forge's agent reads is data](conversation-fence.md)
470 - [The Muse test: how an outsider reports a problem](muse-test.md)
471 - [Offering a patch with no account](offer.md)
472 - [Sending one commit of a fork to its parent as a pull](offer-commit-upstream.md)
473 - [The report form for outsiders](report-form.md)
474 - [The receipt an outsider is handed for a report](report-receipt.md)
475 - [A team's effective share of builder slots](team-effective-share.md)
476 - [Which harness holds a token](tokens-harness.md)
477 - [Signed-in browsers: each named, and signed out one at a time](signed-in-browsers.md)
478 - [When an access code was last used](token-last-used.md)
72 <!-- notes -->
47973
48074 ### Backups and moving
48175
48276 Read with the guide page [Backups and moving](../guide-backups-moving.md).
48377
484 - [A nightly backup that doubles](backup-growth.md)
485 - [A backup that stopped landing](backup-age.md)
486 - [A hosted forge's own backup line](hosted-backup-line.md)
487 - [A data volume that is filling up](disk-free.md)
488 - [A doc that names a file that is gone](dead-doc-paths.md)
489 - [A branch that cannot be backed up](backup-refs.md)
490 - [A forge is an origin](forge-origin.md)
491 - [A pull proposed to an origin, and its state coming back](origin-pull-state.md)
492 - [An app's encrypted backup, with a restore proof](app-backup.md)
493 - [An overdue off-box backup](backup-overdue.md)
494 - [Backups that cannot lie](backup-truth.md)
495 - [Connecting a friend's forge, whatever release it runs](forge-origin-older.md)
496 - [Connecting an origin read-only](origin-read-only.md)
497 - [Forge-to-forge compatibility, measured](forge-origin-compat.md)
498 - [How a fork follows its upstream](follow-mode.md)
499 - [Choosing how a fork follows, in three named choices](follow-choice.md)
500 - [Read an update before you take it](following-incoming.md)
501 - [An upstream update that conflicts is one issue](upstream-conflict-issue.md)
502 - [Moving a forge out of this forge's process into its own sandbox](sandbox-move.md)
503 - [Moving a platform app to the forge (gretchy-stretchy, #11687)](platform-app-move.md)
504 - [Moving a repository to another owner](repo-transfer.md)
505 - [New commits upstream, on a mirror](origin-ahead.md)
506 - [Sending your forge's idea upstream, and pulling back](upstream-landing.md)
507 - [Taking updates from an origin you follow](follow-an-origin.md)
508 - [The backups line on Resilience](resilience-backups.md)
509 - [A backup that finishes on a slow line](slow-line-backups.md)
510 - [Hosted forges in the nightly backup](hosted-backup.md)
511 - [The off-site backup lane](offsite-lane.md)
512 - [The operator guard and proposing through your fork](origin-guard.md)
513 - [Which hosted forges are in use, and archiving one](forge-archive.md)
78 <!-- notes -->
51479
51580 ### Every setting, by topic
51681
51782 Read with the guide page [Every setting, by topic](../guide-settings.md).
51883
519 - [Account settings help](account-help.md)
520 - [Security, for a visitor](security.md)
521 - [Devices](devices.md)
522 - [Edge-only accounts](edge-only-accounts.md)
523 - [Knobs](knobs.md)
524 - [Manage account: reset a person's access](account-access.md)
525 - [Rotating the secret key](rotate-secret-key.md)
526 - [Sent to sign in by an app, and back again](signin-asking.md)
527 - [Taking the forge's own name](claim-own-name.md)
528 - [Ask for a new forge link](claim-renew.md)
529 - [Trusted sources](trusted-sources.md)
530 - [Who can see it, in one line](visibility-line.md)
531 - [Your dotfiles in every shell](dotfiles.md)
84 <!-- notes -->
53285
53386 ### When something is wrong
53487
53588 Read with the guide page [When something is wrong](../guide-when-wrong.md).
53689
537 - [/status says when it was read, and since when a row is not ok](status-time.md)
538 - [The machine's real size on /system and in health](system.md)
539 - [Where the bottleneck is: the line, CPU, checks, crew, memory and disk, each beside its lever](bottleneck.md)
540 - [A child forge the host stopped](child-stopped.md)
541 - [Cells that outlive the host, and are taken back on start](cells-outlive.md)
542 - [A failed adapter pull speaks once in the writers' feed](sync-failed-feed.md)
543 - [A failing webhook is said once](webhook-failing.md)
544 - [A full disk](full-disk.md)
545 - [A rebuild that stopped](combined-rebuild-stopped.md)
546 - [A repeated review comment becomes a check](review-repeats.md)
547 - [Batch doctor](batch-doctor.md)
548 - [Blocked hosts](blocked-hosts.md)
549 - [Clog watch](clog-watch.md)
550 - [Content-Security-Policy reports](csp-reports.md)
551 - [Disk marks and the largest directories](disk-marks.md)
552 - [Disk readings per machine](disk-readings.md)
553 - [Events in the browser](events.md)
554 - [Flaky tests on main](check-flake.md)
555 - [Flow: declined runs](flow-declines.md)
556 - [/flow: what is clogging the lane](flow-clog.md)
557 - [How long the event log keeps what it holds](event-retention.md)
558 - [Interrupted out](interrupted-out.md)
559 - [Load test](load-test.md)
560 - [Main-thread stalls by route](stalls-by-route.md)
561 - [Maintenance, last 7 days](maintenance-week.md)
562 - [Memory held, not hit](memory-held.md)
563 - [Memory by owner and growth across a stall](memory-growth.md)
564 - [Offline page](offline.md)
565 - [Pages over budget (real visitors)](slow-pages.md)
566 - [Pausing a webhook](webhook-pause.md)
567 - [Performance watcher](performance-watcher.md)
568 - [Pulls drifting from main](drift.md)
569 - [Re-checking checks a release cut](recheck-cut-checks.md)
570 - [Red batches, named](red-batches.md)
571 - [Redeliver a failed webhook delivery](webhook-redeliver.md)
572 - [Refused first asks](forges-refused.md)
573 - [Screens and sideways scroll in the check's vitals](vitals-screens.md)
574 - [Send a webhook a test ping](webhook-ping.md)
575 - [The crew does not build the same thing twice](twin-runs.md)
576 - [The from_app alarm](from-app-alarm.md)
577 - [The gate cannot lock itself out](gate-bypass.md)
578 - [The lane has stopped](lane-stopped.md)
579 - [The rule watcher](rule-watcher.md)
580 - [Try again on an issue the crew parked twice](crew-try-again.md)
581 - [What holds a ready issue](map-held.md)
582 - [Who liked a post](likers.md)
583 - [The price of a forge, first on /pricing](pricing-price-line.md)
584 - [A claimed forge tells a stranger whose it is](claimed-forge-door.md)
585 - [One sentence for each pull on a wave](wave-pull-sentence.md)
90 <!-- notes -->
docs/features/absorb-review.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Your apps
3 row: Absorb, reviewed from several angles
4 ---
15 # Absorb, reviewed from several angles (#9441)
26
37 One finding per angle, read from the code at `47c57bd6`. Work that follows is filed as its own issue.
docs/features/absorb.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Your apps
3 row: Absorb: an app becomes one of the forge's features
4 ---
15 # Absorb: an app becomes one of the forge's features
26
37 This page is for site admins and app authors. An app can declare a `feature` in its `forge.json`. A site admin can then absorb it. The app gets a place in the forge's user menu, and the forge keeps the app's typed settings. None of the app's code runs in the forge. The app keeps its repository, data and deploys, and it runs as an ordinary app with an ordinary app's access.
docs/features/account-access.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Every setting, by topic
3 row: Manage account: reset a person's access
4 ---
15 # Manage account: reset a person's access
26
37 An admin opens a person's page (`/settings/accounts/<name>`, linked as **Manage account** from their profile and from `/settings/accounts`, which searches by name) and sees, on one screen: role and join date, email and whether it is verified, passkey count and whether a password is set (never the secrets), the browsers they are signed in on now (when, from where; a person's sign-in history is not kept), what they own, their model allowance and ceilings, and the actions.
docs/features/account-help.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Every setting, by topic
3 row: Account settings help
4 ---
15 # Account settings help
26
37 On the web, Settings › Account (profile, password, tokens) shows each field as a label and a value. One closed
docs/features/act-now.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: Actions that answer at once
4 ---
15 # Actions that answer at once (#8708)
26
37 A form marked `data-now` shows its result in the frame it is submitted in, posts in the background asking for JSON, and rolls back with the server's reason when it is refused. No client model: the page is still what the server rendered, and live regions bring the rest. Without script the form posts and redirects as before.
docs/features/adapters-card.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Your apps
3 row: Adapter facts on the app page and in the terminal
4 ---
15 # Adapter facts on the app page and in the terminal (#10037)
26
37 An app whose `forge.json` declares an `adapter` shows its **source**, how
docs/features/admin-flows.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: Flows across the forge
4 ---
15 # Flows across the forge
26
37 `/admin/flows` (#9594) is one list of every repository's flow lines, for a site admin: each followed upstream, followed source, fork family, mirror and code scan, with its state and when it last moved. `docs/features/flows.md` is the per-repository picture; this is the forge-wide one.
docs/features/agents-md.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Agents: MCP, git, or the terminal
3 row: AGENTS.md on every repository
4 ---
15 # AGENTS.md on every repository
26
37 Any repository you may read answers `/<owner>/<name>/AGENTS.md`, as plain text. Open `https://<forge>/alice/notes/AGENTS.md` in a browser or `curl` it.
docs/features/ansi-log.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Files in the browser
3 row: Terminal logs in colour
4 ---
15 # Terminal logs in colour
26
37 `.log` and `.ansi` files that contain terminal escapes open on the blob page in colour (`src/web/render/log.ts`, parser in `ansi.ts`). A plain log (no escape byte) with an error or warning line (`ERROR x`, `[warn] x`, `level=error x`, after an optional timestamp; prose like "no errors found" does not count) now opens drawn the same way, with those rows marked (`log-error`, `log-warn`) and a "Jump to first error" link above it (`#L<n>`, or `?all=1#L<n>` when the error is past the first 1,500 lines; none past 10,000). A plain log with no such line keeps the ordinary source view.
docs/features/api-reference.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Agents: MCP, git, or the terminal
3 row: The API reference
4 ---
15 # The API reference
26
37 `/api` renders the forge's OpenAPI document (`src/contract/openapi.ts`) as a page: operations grouped by area
docs/features/api-root.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Agents: MCP, git, or the terminal
3 row: The API root
4 ---
15 # The API root
26
37 `GET /api/v1` (and `/api/v1/`) is the API's front door: an agent that starts there, with no account, learns what
docs/features/app-archive.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Your apps
3 row: Archive an app: it spins down, hides from lists, stays reachable
4 ---
15 # Archive an app
26
37 An owner archives an app from its settings (Settings → Archive) or the app page's Archive link. The button opens the confirm page first, which says what will happen; nothing changes until its second button is pressed (a same-origin POST to `/:owner/:name/archive`).
docs/features/app-asking.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Your apps
3 row: An app cannot stall the forge
4 ---
15 # An app cannot stall the forge (#12265)
26
37 The forge serves everyone on one thread, so an app that polls it on a timer must not slow people down. Nothing an app asks is refused; it only goes last, and the forge says who asks the most.
docs/features/app-backup.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Backups and moving
3 row: An app's encrypted backup, with a restore proof
4 ---
15 # An app's encrypted backup, with a restore proof (#11701)
26
37 The forge's backup (`backup-truth.md`) covers the forge. An app's data
docs/features/app-crew.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: Each app with its crew member
4 ---
15 # Each app with its crew member
26
37 On a forge made for someone, every app is one plain line: the app's name, then
docs/features/app-egress-refused.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Your apps
3 row: An app refused an outside host says so in the forge's words
4 ---
15 # An app refused an outside host says so in the forge's words (#12182)
26
37 The forge's gate refuses every outside host that a repository's `forge.json` `egress` does not declare. The refusal says whose no it was, so an app never blames the service it was calling.
docs/features/app-own-domain.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Your apps
3 row: An app's own domain: cut-over and the way back
4 ---
15 # An app's own domain: cut-over and the way back
26
37 The step of a move that can strand a
docs/features/app-page-details.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: The app's page: detail on demand
4 ---
15 # The app's page: detail on demand
26
37 A first ask opens a page of one column: the state, the box to tell the crew, and Now. The operator's
docs/features/app-secrets.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Your apps
3 row: One place for a secret (`Settings → App → Secrets this app uses`)
4 ---
15 # One place for a secret (`Settings → App → Secrets this app uses`)
26
37 Put a secret where it matches who may use it: on the new-app page or the
docs/features/app-slowest-wait.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Your apps
3 row: Whose wait it was: the forge's or the app's
4 ---
15 # Whose wait it was: the forge's or the app's (#10858)
26
37 An app's production speed card says the slowest wait the forge relayed to it in the last 10 minutes, and whether the forge or the app spent it. When the forge's own event-loop lag (`forge-lag`) is more than half the time to the app's headers (`forge-ttfb`), the wait is the forge's (`forgeWaited`, `src/perf/loop_worst.ts`), and the card says so instead of calling the app slow.
docs/features/app-template.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Your apps
3 row: New app from a template
4 ---
15 # New app from a template
26
37 A new app can start as a copy of another repository's tip instead of the starter app.
docs/features/app-templates.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Your apps
3 row: App templates
4 ---
15 # App templates
26
37 A site admin marks repositories as app templates at `/settings/app-templates` (Settings → App templates), or with `POST /api/v1/admin/app-templates` `{ "repo": "owner/name", "marked": true }` (admin scope; anyone else gets 403). The marking is the `app_template` table. `trevato/app-template` is marked by default, comes first, and cannot be unmarked.
docs/features/approval-base.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Ship and undo
3 row: An approval says what it was given for
4 ---
15 # An approval says what it was given for
26
37 An approval is recorded against the head and the base tip it was given for. When the base moves after it (another pull landed), the approval is still counted, and every door says the base moved.
docs/features/approved-named.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Ship and undo
3 row: Naming the approved pull that waits
4 ---
15 # Naming the approved pull that waits
26
37 The flow tick used to say "oldest approved 553 h" and "$66 stranded" and leave you to hunt for which pulls. Now it names them.
docs/features/approved-week.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Ship and undo
3 row: An approved pull that has waited a week
4 ---
15 # An approved pull that has waited a week
26
37 The tick names the oldest approved pull and the needs stack lists those approved a week ago. Past a week the engine also acts (`src/crew/approved_week.ts`, called from `autonomyTick`), in any repository; only landing needs autonomy:
docs/features/apps-crew-sentence.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Your apps
3 row: What the crew is doing, as one sentence per app
4 ---
15 # What the crew is doing, as one sentence per app
26
37 On `/apps` each app's row says what the crew is doing in plain words, under its name, and the terminal says the same in **What the crew is doing** (Ctrl-K, `src/tui/screens/apps_crew.ts`). Both come from `crewLine` (`src/web/studio/crew_line.ts`) through `shelfRows` (`src/web/studio/shelf.ts`), so they cannot disagree.
docs/features/arcade-carts.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: What a forge is
3 row: Arcade carts
4 ---
15 # Arcade carts
26
37 A build pin can name a **cart**: a demo of its commit that plays offline as one HTML page. The cart's facts ride on the pin's tag as trailers (`Demo:`, `Version:`, `Launch: file`, `Page:`, `Showcase: on`, `Cover:`; `git/builds.ts`), so git holds them. The page is captured once from a build preview of the commit and kept under `FORGE_APP_DATA/carts/<owner>/<repo>/<commit>/` with a picture of it (`arcade/carts.ts`). Ported from Jay Moran's arcade.
docs/features/archive-listing.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Your apps
3 row: Archive listing
4 ---
15 # Archive listing
26
37 A `.zip`, `.tar` or `.tar.gz` (also `.tgz`) in a repository shows what is inside it, without unpacking it to disk. Code: `src/web/render/archive.ts` (the bounded reader, `listArchive`), `archive-view.ts` (the page), `src/tui/ui/archive-note.ts` (the terminal).
docs/features/ask-filters.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: Ask filters
4 ---
15 # Ask filters (#11820)
26
37 An owner sets what hides from what asks them, once, and it holds: on the page, in the MCP, in the terminal, on home and in the phone's notifier. Rows live in `ask_filter` (per person, in the forge's database; no cookie). Logic: `src/core/ask_filters.ts`; the one action all three surfaces call: `src/actions/ask_filter.ts`.
docs/features/ask-settles.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: An assigned ask can be settled where it stands
4 ---
15 # An assigned ask can be settled where it stands
26
37 A pull or issue assigned to you, on `/asks` and in the terminal's On you pane, is not only a link to open.
docs/features/ask-status.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: What became of the first ask
4 ---
15 # What became of the first ask
26
37 After a new forge's first ask, home says what became of it, in plain words:
docs/features/ask-to-reach.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: Ask to reach a host
4 ---
15 # Ask to reach a host
26
37 A forge hosted by another reaches the internet only through its host's gate, by name, on port 443, and only the names on the host's list. The list starts as the public git hosts (GitHub, GitLab, Codeberg, Bitbucket) and the forges beside it. A person who connects their own forge on their own domain is refused by the gate, and cannot change the host's list. So the hosted forge asks, and the host's admin answers.
docs/features/asks-mute-undo.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: Muting from the inbox keeps you in place
4 ---
15 # Muting from the inbox keeps you in place
26
37 On `/asks`, "Mute owner/name" under a row mutes that repository. The form carries the page's query as `back`; after the POST you land on the same `/asks?…` (filters kept) with a toast: "Muted owner/name" and an **Undo** button that posts to `/asks/listen`. "Listening to owner/name again" does the reverse, with an Undo that mutes again. Plain forms and redirects: it works without JavaScript.
docs/features/atlas-plan.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: A business, as a map
4 ---
15 # A business, as a map (#439)
26
37 Atlas answers a business described in words with a plan, not code: one
docs/features/atom.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Agents: MCP, git, or the terminal
3 row: Atom feeds
4 ---
15 # Atom feeds
26
37 Follow with a reader, no account needed. Each page that has a feed advertises it with `<link rel="alternate" type="application/atom+xml">`.
docs/features/attention.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: Attention budgets
4 ---
15 # Attention budgets
26
37 `docs/DESIGN.md` holds the five rules of attention. This is how they are measured.
docs/features/backlog-beside-idle.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: A crew beside a backlog says why it stands still
4 ---
15 # A crew beside a backlog says why it stands still
26
37 An engine that reads idle next to open issues accounts for every one of them, and raises its hand when only a
docs/features/backup-age.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Backups and moving
3 row: A backup that stopped landing
4 ---
15 # A backup that stopped landing
26
37 The `backup-age` maintenance duty (#13331) files one issue when the newest backup in the
docs/features/backup-growth.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Backups and moving
3 row: A nightly backup that doubles
4 ---
15 # A nightly backup that doubles
26
37 The `backup-growth` maintenance duty (#13032) files one defect when the last nightly
docs/features/backup-overdue.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Backups and moving
3 row: An overdue off-box backup
4 ---
15 # An overdue off-box backup (#10924)
26
37 When the newest copy of the forge that left the machine is more than 26 hours old (a nightly plus two hours), `flow/alarm_backup.ts` fires the `backup` flow alarm. It reads two small files under the data directory (the snapshot outcome and the mirror's record), never the network, and says one sentence: how old the newest off-box backup is, or that none has landed, and the last failure's cause. A forge that has never sent a copy off the box and never failed to is not alarmed.
docs/features/backup-refs.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Backups and moving
3 row: A branch that cannot be backed up
4 ---
15 # A branch that cannot be backed up
26
37 The nightly snapshot bundles every repository (`src/snapshot/bundle.ts`). A
docs/features/backup-truth.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Backups and moving
3 row: Backups that cannot lie
4 ---
15 # Backups that cannot lie (#8742)
26
37 - **Read from the bucket.** `src/snapshot/bucket.ts` lists the primary and mirror stores every 5 minutes, in the serving process (no CronJob to die). Home's backup tile, vitals (one `backup` card) and the MCP `backups` tool's `verdict` all call `backupVerdict`.
docs/features/batch-doctor.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: When something is wrong
3 row: Batch doctor
4 ---
15 # Batch doctor (#7555)
26
37 When the merge queue's re-gate hands a pull back red (the re-gate carries it alone, so a red on top of other pulls is the queue's own search, #4999), `src/checks/doctor.ts` classes the red (`doctor_classify.ts`) and acts, in `crew/autonomy.ts`'s `handBack`:
docs/features/beat.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Ship and undo
3 row: A beat the forge owns, and a gate on the push
4 ---
15 # A beat the forge owns, and a gate on the push
26
37 ## The beat
docs/features/behaviors.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: What a forge is
3 row: Behaviors: shared interactions, attached by attribute
4 ---
15 # Behaviors: shared interactions, attached by attribute
26
37 One module, `src/web/behaviors.ts` (one string, no dependency, under 2 KB: `test/behaviors.test.ts`), holds the interactions pages share. Each is attached by an attribute on HTML that already works without script. Only what a page uses is in it; a new behavior arrives with the page that needs it, keyboard path and terminal door included. The model is Vercel's UI SDK; none of its code or weight is used.
docs/features/bets.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: Bets
4 ---
15 # Bets
26
37 A bet is a name, an appetite (a share of the week), what done looks like in a few journeys, and scopes — existing issues — that each finish on their own. One crew member leads. Open `/<owner>/<repo>/bets`; the MCP has `bets` (read) and `bet` (act); the terminal has **Bets** in the palette (`p` propose, `b` back, `s` stop, `c` cut, `e` end, `l` what is left, `d` feels done, `n` not yet). All three go through `actions/bets.ts`, and every write emits a `bet.*` event, which the web pages follow with their "new activity" pill.
docs/features/billing.md +5
@@ -1,3 +1,8 @@
1 ---
2 topic: Hosting forges for others, and getting paid
3 row: Billing
4 see: what-a-paid-forge-is-at-terms-13207 | What a paid forge is, at /terms
5 ---
16 # Billing
27
38 Billing records the plan each forge is on (`src/billing/`): a store of entitlements, every change kept. There is no payment processor and nothing reads a plan to limit a forge yet; a grant is a record until a limit reads it.
docs/features/binary-file.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Your apps
3 row: A binary file shows its size and type
4 ---
15 # A binary file shows its size and type
26
37 Open the blob page of a binary nothing can render, such as a `.wasm` or an
docs/features/blocked-by.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: When a setting or a permission stands in the way
4 ---
15 # When a setting or a permission stands in the way
26
37 An error that says a setting or a permission stops the reader holds to three rules.
docs/features/blocked-hosts.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: When something is wrong
3 row: Blocked hosts
4 ---
15 # Blocked hosts (#10456)
26
37 When a production cell is refused a host, the forge says so: `apps/egress_refused.ts` counts one row per host and port (first and last time, a count) in memory and writes `<data>/egress/<repo>.refused.json` at most every few seconds. The first refusal of a host appends `app.egress.refused`, which wakes the notifier. Preview cells (any pull's, a fork's too) neither report here nor read the owner's yes.
docs/features/bottleneck.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: When something is wrong
3 row: Where the bottleneck is: the line, CPU, checks, crew, memory and disk, each beside its lever
4 ---
15 # Where the bottleneck is
26
37 A forge admin sees in one sentence what limits the forge now, then one row each for the internet
docs/features/box-pass.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Your apps
3 row: The box pass
4 ---
15 # The box pass
26
37 An issue's `- [ ]` boxes used to pile up unticked after the pull that did the work landed, and held the issue open for a person. The reviewer that approves the pull now reads its head against each box and reports it.
docs/features/bring.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Your first app in five minutes
3 row: Bring an app from another forge (`/bring`)
4 ---
15 # Bring an app from another forge (`/bring`)
26
37 Paste the link to an app on a forge you have connected (`/settings/origins`), and it
docs/features/bug-close.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: A bug closes with a reason
4 ---
15 # A bug closes with a reason
26
37 An issue labelled `bug` cannot be closed by hand with nothing behind it. Unless
docs/features/bugs.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: Bugs on a clock
4 ---
15 # Bugs on a clock
26
37 An open issue labelled `bug` is answered, fixed or closed as won't fix within a limit.
docs/features/build-cache.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Ship and undo
3 row: Build cache
4 ---
15 # Build cache
26
37 Each environment of an app keeps one build cache under its own data (`apps/<id>/<env>/build-cache/<key>/`), keyed by a hash of `Cargo.lock`, `bun.lock` and the toolchain pins. `CARGO_TARGET_DIR` points into it and `~/.exact` in the build's home links to its `exact/`, so a second deploy of an unchanged Rust app skips the compile. A changed key starts a fresh directory and removes the old one.
docs/features/build-pins.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Ship and undo
3 row: Build pins
4 ---
15 # Build pins
26
37 A writer marks a commit as a build worth keeping: an annotated tag at
docs/features/build-preview.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Ship and undo
3 row: Build preview
4 ---
15 # Build preview
26
37 Look at any one commit of an app, now, without pinning it or opening a pull.
docs/features/capacity.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Hosting forges for others, and getting paid
3 row: Capacity flags a count set below its ceiling
4 ---
15 # Capacity flags a count set below its ceiling (#9049)
26
37 A capacity count (`crew.concurrency`, `checks.concurrency`, `queue.depth` and the rest) that an admin has set **below its default** holds the forge back, and nothing used to show it. Now:
docs/features/cells-outlive.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: When something is wrong
3 row: Cells that outlive the host, and are taken back on start
4 ---
15 # Cells outlive the host (`FORGE_CELLS_OUTLIVE`)
26
37 On when the host boots (#13750), so a production release leaves a hosted forge's checks and runs running; set `FORGE_CELLS_OUTLIVE=off` to tie cells to the host again. With it on, a child's cell runs its proxy and relays in a supervisor of its own and is not tied to this process: stopping the host leaves the cell running (#13755).
docs/features/changelog.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: What a forge is
3 row: Changelog
4 ---
15 # Changelog
26
37 `GET /changelog` is public. It lists the last 30 `Release <version>: …` commits on the default branch of the forge's own repository (`FORGE_REPO`), newest first. Each has a heading anchored `#<version>`, its date, and one link per pull named in the subject (`title (#N);title (#N)`). When `FORGE_REPO` is unset or its repository is private, the page answers 200 with "No releases yet". The footer links to it.
docs/features/chapter-bar.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: The open chapter's bar on the home
4 ---
15 # The chapter bar
26
37 The home shows one row under the hero for the open chapter: how far it is ("v2: 12 of 19") and the next unfinished
docs/features/chapter-wave.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: Closing a chapter writes its wave
4 ---
15 # Closing a chapter writes its wave
26
37 Closing a chapter, in the web page or in the terminal, writes the chapter's
docs/features/chapters.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: Chapters: a version with an end
4 ---
15 # Chapters: a version with an end
26
37 A chapter is a named list of a repository's issues that is finished, tagged and closed (#11603). A name (`v1.0.0`; it becomes the git tag), one sentence of what done means, and the issues in it.
docs/features/check-flake.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: When something is wrong
3 row: Flaky tests on main
4 ---
15 # Flaky tests on main (#6643)
26
37 A default-branch check that fails **one or two named tests** re-runs only those
docs/features/child-attestation.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Bring your own AI
3 row: A child's proposal says what the child proved
4 ---
15 # A child's proposal says what the child proved
26
37 When a child forge proposes a change to its parent, it also sends what its own check found on that commit (#13645). The parent shows this beside its own check. It never decides anything on it.
docs/features/child-cpu-pausing.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Hosting forges for others, and getting paid
3 row: A child forge's cores, held by pausing where the kernel cannot
4 ---
15 # A child forge's cores, held by pausing where the kernel cannot
26
37 A child forge's cell asks for its cores to be held (`cpuQuota`). Where the
docs/features/child-credit.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Bring your own AI
3 row: A parent funds a child's crew
4 ---
15 # A parent funds a child's crew (#10484)
26
37 A parent lends a child forge dollars of its own model credential. The child's
docs/features/child-disk-bandwidth.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Hosting forges for others, and getting paid
3 row: A child forge's disk bandwidth is capped by its size
4 ---
15 # A child forge's disk bandwidth is capped by its size
26
37 A child forge's cell shares the parent's disk. `io.weight` only orders the
docs/features/child-filesystem.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Hosting forges for others, and getting paid
3 row: A child forge's own filesystem
4 ---
15 # A child forge's own filesystem (#10856)
26
37 Everything a child forge writes is kept under `<data>/children/<body id>`. The
docs/features/child-model-egress.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Bring your own AI
3 row: A child forge's cell may reach its model provider
4 ---
15 # A child forge's cell may reach its model provider
26
37 A child forge that runs in a cell (`src/spawn/cell.ts`) could reach its parent and nothing else, so its crew could not call a model. An admin of the parent now chooses one model provider those cells may reach.
docs/features/child-proposal-credential.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Hosting forges for others, and getting paid
3 row: A claimed child receives the credential to propose back to its parent
4 ---
15 # A child receives its proposal credential
26
37 A child forge that carries a fork of its parent's code can propose back to it, but only with a
docs/features/child-reach.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Hosting forges for others, and getting paid
3 row: "Running" is proven from outside
4 ---
15 # "Running" is proven from outside
26
37 A child forge's process being up inside its cell says nothing about whether a
docs/features/child-stopped.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: When something is wrong
3 row: A child forge the host stopped
4 ---
15 # A child forge the host stopped
26
37 `src/spawn/stopped.ts` records a stop (one state object per parent; the host passes in how a forge starts again), writes `stopped.json` into the child's directory, and arms a restart after a backoff: 5 s, doubling per stop to 10 min, the count starting again after 30 clean minutes. The restart goes through the due-wake path, so the disk floor still applies; when the awake ceiling is full, forges quiet for a minute with no crew at work are put to sleep to make room, and a try that is turned away is made again a minute later, for the hour the stop is shown. While it stands, the wake page and the terminal's forges list say "ran out of memory and was stopped at HH:MM UTC; the host starts it again at HH:MM UTC" (or "within a minute") instead of "the forge is full".
docs/features/claim-own-name.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Every setting, by topic
3 row: Taking the forge's own name
4 ---
15 # Taking the forge's own name
26
37 A forge made from a sent link or Start my forge has an organisation named after
docs/features/claim-renew.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Every setting, by topic
3 row: Ask for a new forge link
4 ---
15 # Ask for a new forge link
26
37 When a forge link has expired, the claim page says so and offers one action: **Ask for a new link**. Pressing it
docs/features/claimed-forge-door.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: When something is wrong
3 row: A claimed forge tells a stranger whose it is
4 ---
15 # A claimed forge tells a stranger whose it is (#13795)
26
37 On a hosted forge someone has claimed, `/` for a signed-out visitor says "This is <owner>'s forge" with one Sign in, the public apps if there are any, and a link to get a forge of their own. The product page and its start form stay for forges nobody owns, and for `/front`.
docs/features/client-app-line.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Hosting forges for others, and getting paid
3 row: The sentence under each of a client's apps, on the page, in the terminal and in forge_view
4 ---
15 # The sentence under each app
26
37 A client's first page (`/`) shows each of their apps with one plain sentence about what its crew
docs/features/client-forge.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Hosting forges for others, and getting paid
3 row: A forge for a client, from one link
4 ---
15 # A forge for a client, from one link
26
37 This page is for the person who sends a client a forge and for the planner who
docs/features/clog-watch.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: When something is wrong
3 row: Clog watch
4 ---
15 # Clog watch (#6757)
26
37 Once a minute the forge reads its flow (open pulls that conflict, pulls opened and landed over 2 h, the oldest approved wait) and declares a clog on the thresholds in `src/flow/clog.ts`. A clog clears after two quiet readings.
docs/features/clone-pacing.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Your first app in five minutes
3 row: Clones yield to pages
4 ---
15 # Clones yield to pages
26
37 Pages and git packs leave through the same uplink, so a large clone could starve every page (#13778).
docs/features/cloud.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Hosting forges for others, and getting paid
3 row: Cloud accounts
4 ---
15 # Cloud accounts
26
37 The forge keeps the provider tokens (a cloud vendor's API token) its repositories use, sealed. Four doors show them, all a forge admin's alone; anyone else finds no such page, screen, tool or route. No door ever returns a secret: a token is typed once, checked, sealed, and never drawn, kept in a note or sent back.
docs/features/cmd-k-pull-actions.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Getting around: keys, the palette and search
3 row: Cmd-K: a pull's actions
4 ---
15 # Cmd-K: a pull's actions
26
37 On a pull page, either tab, press Cmd-K (Ctrl-K) and the palette lists what the page lets you do, under "This pull". Type a verb ("close", "check", "reopen") and press Enter. Every row is something the page itself offers you; a reader is never shown a row the server would refuse.
docs/features/cmd-k-repositories.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Getting around: keys, the palette and search
3 row: Cmd-K: repositories and their apps
4 ---
15 # Cmd-K: repositories and their apps
26
37 One row per repository, under "Repositories". A repository with an app says so on its row ("App · running"); Enter goes to the repository; the app is its own option right under it ("Open the app of owner/name"), so arrow keys, touch and screen readers reach it, and Cmd/Ctrl+Enter on the repository is the shortcut. Only someone who may enter the app is shown it, in the index and in the server's search alike (`enterableApps`).
docs/features/code-scanning.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Ship and undo
3 row: Code scanning
4 ---
15 # Code scanning
26
37 Every push to a repository is scanned (`src/checks/scan.ts`, run from the
docs/features/combined-rebuild-stopped.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: When something is wrong
3 row: A rebuild that stopped
4 ---
15 # A rebuild that stopped
26
37 A kept fork's pull is built as main merged into its head (`combined/N`). When main deletes, renames or changes the mode of a file the pull also changed, no side can be picked for it, and nothing lands that nobody chose (#12151). The rebuild stops and the pull says so:
docs/features/comment-refused.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: What a forge is
3 row: A refused comment keeps its words
4 ---
15 # A refused comment keeps its words
26
37 On an issue or a pull page, a comment that is refused (blank, or not posted) draws the page again with status 422:
docs/features/composer-send-key.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: Send a tell with Ctrl or Cmd+Enter
4 ---
15 # Ctrl/Cmd+Enter sends from the feed composer
26
37 This page is for anyone who tells the crew from the feed. In the "Tell the crew" box, Ctrl+Enter (Cmd+Enter on a Mac) sends the tell, the same as the button.
docs/features/config-form.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Files in the browser
3 row: Config files as a form
4 ---
15 # Config files as a form
26
37 A `.json`, `.yml`/`.yaml` or `.toml` file in a repository opens as a form (#7336, #7337, part of #7329).
docs/features/contribute-token.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Agents: MCP, git, or the terminal
3 row: Outside agents: a contribute token with no account
4 ---
15 # Outside agents: a contribute token with no account (#12012)
26
37 An agent with its own sandbox (Codex cloud, Jules, Claude Code, Cursor) contributes by clone and push. It needs no account and spawns no forge.
docs/features/conversation-fence.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Agents: MCP, git, or the terminal
3 row: The fence: what the forge's agent reads is data
4 ---
15 # The fence: what the forge's agent reads is data
26
37 The forge's own agent (#7640) talks to a person through `/mcp` with a **via
docs/features/cores-row.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Hosting forges for others, and getting paid
3 row: What a sized forge's cores mean for builds
4 ---
15 # What a sized forge's cores mean for builds (#11694)
26
37 A child forge's admins see one `Cores` row on `/settings`, next to the Plan row: `1 CPU: builds run, slower.` and how the cores are held. The terminal's palette entry *Cores* (`src/tui/screens/cores.ts`) prints the same sentence (`coresLine`, `src/spawn/cores.ts`).
docs/features/cost-days.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Bring your own AI
3 row: Cost by day
4 ---
15 # Cost by day
26
37 A repository's owner (anyone `canSeeOwnerFacts` names) reads what the crew spent on it in each of the last 30 days as a table: date, dollars, runs. The page is `/:owner/:name/cost`; the terminal's "Usage of a repository" screen opens with the same rows in the same words. Anyone else gets the page's not-found.
docs/features/cost-ledger.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Bring your own AI
3 row: Cost ledger
4 ---
15 # Cost ledger
26
37 Every run that ends (`finishRun`, and `cancelRun`: agent, check, deploy) appends one line to `$FORGE_DATA/ledger/<yyyy-mm>.jsonl` (by the month it ended). Nothing is written on a day with no runs. A snapshot has no `run` row, so the snapshot service appends its own entry when one ends, taken or failed: `kind: "snapshot"`, `run: "snapshot:<startedAt>"`, `startedAt`, `endedAt`, `wall_s`, and `failed: true` only when it failed. It has no `repo`: a snapshot is the whole forge's, so `repo` is optional and absent, never a made-up id. A forge with nowhere to put a snapshot writes nothing.
docs/features/crawl-budget.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Your apps
3 row: Crawl budget
4 ---
15 # Crawl budget (#8129)
26
37 - `/robots.txt` disallows `DEEP_SEGMENTS` (blob, raw, commits, commit, blame, compare, diff, tree, history) at every ref (and `/origins/`), generated from the same list the budget's deep paths use, keeps home, repository roots and docs open, and asks `Crawl-delay: 10`.
docs/features/crew-line.md +4
@@ -1,3 +1,7 @@
1 ---
2 topic: Tell the crew
3 row: The crew line on Home
4 ---
15 # The crew line on Home
26
37 One short line under Home's header, for the owner (a site admin) only, on the web and in the terminal's dashboard. Both print the same words from `crewLineWords` (`src/crew/week_read.ts`):

414 more files not shown.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs