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

MCP `subscription_headroom`: set how much of each window the crew leaves for people, as the Subscriptions page does #5469

Parked opened this
Closed without merging

scout/forge:scout/5439-mcp-subscription-headroom-set-how-much-o → main 4 commits fork 6 threads · 6 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
912 files changed +31931 −8859
CLAUDE.md +14
@@ -4,6 +4,12 @@ Orientation for an agent editing forge. Read this first, then `README.md` (what
44 it is) and `docs/ARCHITECTURE.md` (why it's shaped this way). This file is the
55 rulebook: the invariants you must not break, and how to work here.
66
7 **Read docs/VISION.md first: it says what the forge is for and the order of work.**
8
9 **Done means reachable** — a person reaches it from the feed in two taps, an
10 agent through the MCP, a test proves it, a look shows it. A function nobody can
11 call is not done.
12
713 The whole point of forge is that **one person can hold it in their head**. Every
814 change should leave it that way. When something fights you, step up and
915 understand the system before adding code — a workaround usually means the system
@@ -155,6 +161,8 @@ src/
155161 scope floors, pagination, `securityFloor` — the headers every
156162 response leaves with), api (every /api/v1 route), server
157163 (auth resolution, git smart HTTP, web routes, hook socket), sse
164 mcp (the MCP protocol and dispatch; one file per tool under
165 mcp/tools/, gathered by a generated index)
158166 design/ shared design tokens: themes (palettes both surfaces render)
159167 origins/ other forges as one Provider interface: discover (version-endpoint
160168 probe), providers/{github,forgejo} (+ http: paging, ETags, rate
@@ -245,6 +253,12 @@ flag exists only in the stdio dev runner and is never reachable over SSH.
245253 `{ items, next_cursor }` via `paged(...)`, never a bare array
246254 (`test/api-list-shape.test.ts` fails on one). Web forms follow the same shape
247255 via `readForm(ctx, scope)`.
256 Describe it in OpenAPI as one file, `contract/openapi/routes/<operationId>.ts`,
257 exporting `route`; then `bun scripts/openapi-routes.ts` writes its line in the
258 generated index. Never list it by hand.
259 - **Add an MCP tool:** one file, `http/mcp/tools/<name>.ts`, exporting `tool`;
260 then `bun scripts/mcp-tools.ts` writes its line in the index and its row in
261 docs/MCP.md (docs/MCP.md, "Adding a tool"). Never list it by hand.
248262 - **Add a TUI screen:** one file under `tui/screens/`, exporting
249263 `(f: Session, ctx: Ctx, …) => Screen`. Compose `ui/widgets`; take navigation
250264 from `screens/common.ts` (`ListState`, `Scroll`, `Filter`, `drawList`,
README.md +100 −12
@@ -20,9 +20,15 @@ any URL — and it is the rest of this page.
2020
2121 A forge this one spawned (hosted) runs the apps it was given too: its `bakery`
2222 answers at `bakery--<child>--<this forge's host>`, in this forge's lanes, on the
23 child's own data, and `/forges` says how many are running and why any is not.
23 child's own data, and `/forges` says how many are running and why any is not. Each row also ends with the first step its person has not taken (`not claimed yet`, `no everyday account yet`, `no tell yet`, or `going: last tell <time>`; `has not reported yet` before the child's first beat), read from the child's heartbeat; the terminal's forges screen and the MCP `forges` tool (`nextStep`) say the same.
24 The list leads with the forges that need you, each badged
25 with why (also in the terminal and the MCP `forges`): "Not reporting" (no word
26 in 24 hours), "App down", or "Unclaimed" three days after it was sent; the rest
27 follow by last activity.
2428 In the terminal an admin's palette offers "Forges you sent": each forge with its
25 claim state and the same apps-running note, never a claim link.
29 claim state and the same apps-running note, never a claim link. Both carry the
30 crew's spend today against the daily ceiling that pauses it (`$3.20 of $10 today`), as the
31 child's heartbeat last reported it.
2632
2733 Each agent's scorecard — pulls landed of opened, review rounds, red checks,
2834 reverts, time to land — is on Settings → Crew (`/settings/crew`) and in the
@@ -288,6 +294,26 @@ each, under the forge strip; a list cut to three says "+N more".
288294 The line is the shared `.quiet-details` disclosure, and the "need you" count
289295 carries the attention dot.
290296
297 A fork ahead of its parent offers its commits upstream: on its home a signed-in reader of the parent sees "Offer N commits upstream" (into the new-pull form with both branches chosen) or "Offered in #M" once a pull is open; a writer who has the Following card gets its "Propose upstream" instead, one route not two. In the terminal the fork's About card (`I`) has an `offer` row and `o` opens the same pull form (or the open pull). Both read `upstreamOffer` (`src/actions/offer_upstream.ts`), the open pull by one SQL lookup.
298
299 ## Long threads
300
301 An issue or pull page renders the opening post and its newest 50 comments
302 (`THREAD_WINDOW`, `src/core/issues.ts`) with the state-change lines between
303 them; above them a plain link, `Show N earlier items`, goes to the same page
304 with `?all=1` (other query parts kept), which renders everything, with no
305 JavaScript. N counts state-change lines as well as comments. A comment's own
306 anchor is `#c-<id>`; links the forge writes to a comment (the feed's replies)
307 go through `commentAnchor()`, which counts comments the way the page cuts
308 them, and carry `?all=1` when the comment is folded away, so they always
309 land. A hand-typed `#c-…` into the folded part cannot be seen by the server
310 (the fragment never leaves the browser), so it needs `?all=1` too. The live
311 region still appends new comments at the bottom.
312
313 The terminal's issue and pull screens stay whole on purpose: they are a
314 scrolling text view of one thread already in memory, not a page a phone
315 downloads, so there is no weight to cut and no second key to learn.
316
291317 ## Live in the terminal
292318
293319 `ssh` into the forge and you get the whole thing — repositories, code, issues,
@@ -297,8 +323,13 @@ tokens and keys — as a keyboard-driven terminal app. The same port serves git.
297323 ```sh
298324 ssh -p 2222 localhost # the terminal UI
299325 git clone ssh://localhost:2222/you/hello.git # git, same port
326 ssh -p 2222 localhost tell make the header blue # tell the crew in one line
300327 ```
301328
329 `tell <words>` takes the rest of the command line as given (no shell expansion; control characters are refused) and tells the crew in the forge's own repository, as the account the key belongs to, through the same action as the web composer. It prints the told line and the full address of the issue, and exits 0; an unknown key, nothing said, too much, or an unverified email prints the reason on stderr, records nothing and exits 1. (Quote the words if your local shell would expand them.)
330
331 An app's open pulls, newest five first, one line each (`#n title · green|red|running|none`), need no tty: run `pulls` on the app's login — `ssh <app>@<forge> pulls`, with the app's page printing the exact command as `FORGE_APP_SSH` (the terminal is off when that is unset). A private app answers only a key its gate admits; sealed pulls show to their author, writers and the crew (`src/apps/door_pulls.ts`).
332
302333 A big repository clones over either transport. To skip its large files until a
303334 checkout needs them, run `git clone --filter=blob:none <url>`. See
304335 [`docs/GIT.md`](docs/GIT.md).
@@ -342,9 +373,14 @@ link), the home is their apps, one plain sentence each and one more saying
342373 whether its agents are working, about to start, or waiting: no map, board or
343374 settings until asked. `/?all=1` is the whole home, and its "Just my apps" link
344375 comes back. Each app row also says what its agents are on ("Working on: …")
345 or the last change landed in the past 7 days ("Last change: …, 3 days ago");
346 a quiet app says nothing more. The terminal's first screen opens with the same
347 lines, from the same queries (`src/core/client-apps.ts`).
376 and what was last finished on it ("Finished 3 days ago: …", its newest merged
377 pull however old, read for all rows in one query); an app with neither says
378 nothing more. Both doors show both lines: the terminal's first screen opens
379 with the same lines, worded by the same helpers (`src/core/client-apps.ts`).
380
381 **Reading the home as the eye does (#5735, step 1).** `bun scripts/home-read.ts <url>` fetches a page and prints its visible text, then one line: `chars N · words N · fetched in N ms`. Set `FORGE_COOKIE` (for example `forge_session=…; forge_mode=studio`) to read it as the owner; the cookie is sent and never printed. It exits non-zero on any status but 200. The conversion is `pageText` in `src/web/page_text.ts`: scripts, styles, templates, the head and anything `hidden` or `aria-hidden="true"` are dropped, link text stays, blocks sit on their own lines, entities are decoded. The method then continues: (2) a fresh agent with no context reads only that text and answers in at most 150 words, (3) the steward scores it against ground truth on coverage of the 5 things that mattered, errors, and seconds, (4) repeat after every feed change. The steward runs steps 2–4 and logs them on #5735.
382
383 **Scoring the home (#5805).** `bun scripts/home-eval.ts <url>` is the deterministic half of that loop: it reads `/` with the same text conversion, builds ground truth from the forge's own API (`GET /api/v1/telemetry/home` for landings, the live version, builders and why idle, spend against the ceiling and what waits on the owner; the repository list and each newest commit for repositories quiet 3 days), and prints each of the five facts as `stated`, `missing` or `wrong` with the page's words, then coverage, errors, characters and fetch time. The method and a table of results, one row per feed pull, are in `docs/HOME-EVAL.md`. No dependency was added.
348384
349385 Home shows nine figures first, from `src/flow/kpis.ts`: shipped per hour (with
350386 a 24 h sparkline), the live version and since when, the median check time, the crew builders
@@ -456,9 +492,9 @@ own for it: the same asks are the dashboard's On you card.
456492 A client's forge: `Ctrl+K`, then **New forge** (any signed-in person's, as the
457493 page is), is `/forges/new` in the terminal — name, for whom, what it is for,
458494 apps to fork (`owner/name`, comma-separated), a fresh one-line app, model key
459 (hidden as typed), API base URL and budget, through the same `spawnDoor` as the
495 (hidden as typed), API base URL, budget, how it follows the code and a size (`small` by default, not sent; `medium` or `large` is; left, right or space choose), through the same `spawnDoor` as the
460496 page, `POST /api/v1/forges` and the MCP `spawn`. `Ctrl+P` shows the plan and
461 makes nothing; `enter` on the plan spawns, and the claim link is shown once, in
497 makes nothing (it shows a Size line when one is chosen); `enter` on the plan spawns, and the claim link is shown once, in
462498 a dialog, never kept.
463499
464500 The family across forges: `:` → Family in the terminal, `/family` on the web,
@@ -603,7 +639,7 @@ forge can be a parent. The terminal shows the count, not the release names.
603639
604640 A spawned forge's own code is a fork of its parent's (`<org>/forge`, chosen
605641 `followMode` `tell-me` or `take-updates`; in `take-updates` the hourly check puts what the parent gained in a pull.
606 A spawn may also name a `size`: `small`, `medium` or `large` (`src/spawn/sizes.ts` maps each to CPU, memory and disk). It is recorded in the plan only when given, so a plan without one hashes as it always did, and an unknown size is a 422 on `size`. Nothing enforces the limits yet, and the table's numbers are provisional. `GET /api/v1/forges/sizes` (no sign-in, ETag, cached for 5 minutes) and the MCP tool `sizes` give the same answer — each size's CPU, memory and disk, read from that table, and one sentence on what it is for — so a page or an agent offering a size reads it there.
642 A spawn may also name a `size`: `small`, `medium` or `large` (`src/spawn/sizes.ts` maps each to CPU, memory and disk). It is recorded in the plan only when given, so a plan without one hashes as it always did, and an unknown size is a 422 on `size`. The New forge page and the terminal form both offer it, small preselected and not sent; the page shows a refusal beside the select, linked with `aria-describedby`. Nothing enforces the limits yet, and the table's numbers are provisional. `GET /api/v1/forges/sizes` (no sign-in, ETag, cached for 5 minutes) and the MCP tool `sizes` give the same answer — each size's CPU, memory and disk, read from that table, and one sentence on what it is for — so a page or an agent offering a size reads it there.
607643 Once an hour, and
608644 on demand, a forge that follows and has not severed fetches its parent's code into
609645 `refs/upstream/*` of its own `<org>/forge` (no branch of the fork moves) and keeps
@@ -704,6 +740,10 @@ event, without a fork chain; one picked from a connected origin then has none.
704740
705741 `/search` answers repositories and issues in full, and greps code repository by repository. A first search starts no new `git grep` after 30 ms (`codeBudgetMs` in the forge config; a soft stop, since the grep in flight still finishes, one batch of four) and shows what it has with one link, **More code results** (`?code=all`), that greps the rest. The API and the terminal palette always grep everything.
706742
743 ## Bug hunters
744
745 `bun scripts/hunt.ts <origin>` runs the hunters' detectors against one running app (GET only, same-origin, one pass) and prints findings as JSON; it exits 1 when there are any. Lanes and what is not built yet: `docs/HUNT.md`.
746
707747 ## Health
708748
709749 `GET /api/v1/health` (and the MCP `health` tool) answer a site admin with
@@ -989,6 +1029,17 @@ Under the box, four starter sentences are plain links (no script):
9891029 server-rendered page paints up to 100 ms later (a page sent with a
9901030 `Content-Length`, or one that starts with something other than markup, does
9911031 not wait). Event streams and WebSockets are untouched.
1032 - **A signed-in note needs the panel's one-use proof (#5612).** The grant
1033 cookie alone no longer makes a note `@name`: the forge puts a one-use token in
1034 the panel's script tag on a signed-in page load, the panel sends it as
1035 `x-forge-proof` and each answer carries the next. Without it, a reused one or
1036 one for another grant or host, the sender is a visitor and `admin` is false.
1037 This stops an app's code that merely holds the cookie (a `fetch` from its
1038 page). It does **not** stop app code that runs in the same page and watches
1039 for the tag or patches `fetch` before the panel runs: the token reaches the
1040 panel through the page, so that code can read it. Closing that needs the
1041 panel in a cross-origin frame, which is not built. If a call fails the panel
1042 asks for a reload, since the chain is then spent.
9921043 - **The forge button is a feedback door (#4758).** One tap opens *Tell the
9931044 builders*: a text box and Send, no account. The note is posted to the app's
9941045 own host (`POST /__forge/note`, same-origin only) and filed as an issue on
@@ -1110,7 +1161,12 @@ scripts), `/__forge/` on the app's host is the way back: a small page from the
11101161 forge, never the app, with no script, saying the app and where you are
11111162 (`production` or `preview of pull #N`) and linking Home, the repository (to
11121163 who may read it) and *Tell the crew* (the same link `/__forge/crew` gives; signed
1113 out it offers sign in). The prefix was already the forge's, so an app's own
1164 out it offers sign in). It also says what is serving, read from the deploy
1165 record (no git): production shows the newest release and the three before it
1166 (a redeploy of the same commit is not another release), a preview shows its
1167 pull and the commit it last served, or "not deployed yet". A viewer who cannot
1168 read the repository sees only the time, never a sha. The read is the `serving`
1169 Server-Timing phase. The prefix was already the forge's, so an app's own
11141170 `/__forge/` path is not reachable.
11151171
11161172 **Tell the crew from the pill.** Signed in as someone who may direct the crew,
@@ -1413,7 +1469,7 @@ the work repositories and nothing else. Two on one grant take turns, and
14131469 one the provider rests hands its runs to the other until the reset.
14141470 **Model budget.** A new account has none: its repositories' crew does not run, spends nothing, and says "This repository has no model account". A person adds their own subscription at Settings → Model (or the terminal's **Model budget** command, `a`); it is sealed, granted to their own repositories only, and one per account. A forge admin who is a person gives an account a capped grant, in dollars a month spent on the forge's own credential, from the account's page, the terminal's **Model grant** command, `POST /api/v1/admin/accounts/:name/model-grant` (`{"usdPerMonth": 20}`, `null` takes it back) or the MCP `model_grant` tool; each change is in the audit. The cap is the UTC month's spend in the usage ledger, checked when a run starts and on every spend tick: a run past it stops, and its page says the grant is spent. Two runs that start together each begin with the whole remainder; the tick check ends both once the sum crosses the cap, so the overshoot is at most what they spend between ticks.
14151471
1416 **Roles.** An account is a guest, a member or an admin (`docs/ROLES.md` has the table of what each can do; `src/core/roles.ts` holds it). Admin is the admin flag, a member is promoted, everyone else is a guest. A guest is refused creating or forking a repository, making an app their own and starting a crew run, in the words "the owner has not made this account a member" (after the older refusals: unverified, suspended, agent, private); nothing switches it off. A forge admin who is a person lists everyone with their role at Settings → People (`/settings/people`) and promotes a guest to member with one button, with an optional starter model allowance in dollars a month (none by default, given as a model grant and audited as one), or demotes a member (the allowance stays until taken back on the account's page). In the terminal it is the **People** command (`r` changes a role: `member 5`, or `guest`); over the API, `GET /api/v1/admin/people` (`{ items, next_cursor }`, as `/admin/accounts` and `/admin/invites` answer, with `limit` 1-200, 50 by default, and `cursor`) and `POST /api/v1/admin/accounts/:name/role` (`{"role": "member", "usdPerMonth": 5}`); over MCP, the `account_role` tool (a plan unless `dryRun: false`, with an admin token). Anyone signed in sees their own role and its row of the table: the account page (`/settings`) shows "What you can do here"; over MCP, `whoami_can` returns `{username, role, can, abilities}` with any token; in the terminal it is the **What I can do** command (read only, agents included).
1472 **Roles.** An account is a guest, a member or an admin (`docs/ROLES.md` has the table of what each can do; `src/core/roles.ts` holds it). Admin is the admin flag, a member is promoted, everyone else is a guest. A guest is refused creating or forking a repository, making an app their own and starting a crew run, in the words "the owner has not made this account a member" (after the older refusals: unverified, suspended, agent, private); nothing switches it off. A forge admin who is a person lists everyone with their role at Settings → People (`/settings/people`) and promotes a guest to member with one button, with an optional starter model allowance in dollars a month (none by default, given as a model grant and audited as one), or demotes a member (the allowance stays until taken back on the account's page). In the terminal it is the **People** command (`r` changes a role: `member 5`, or `guest`); over the API, `GET /api/v1/admin/people` (`{ items, next_cursor }`, as `/admin/accounts` and `/admin/invites` answer, with `limit` 1-200, 50 by default, and `cursor`) and `POST /api/v1/admin/accounts/:name/role` (`{"role": "member", "usdPerMonth": 5}`); over MCP, the `account_role` tool (a plan unless `dryRun: false`, with an admin token). Anyone signed in sees their own role and its row of the table: the account page (`/settings`) shows "What you can do here"; over MCP, `whoami_can` returns `{username, role, can, abilities}` with any token (with `{"kind": "passkeys"}` it lists your own passkeys instead, `{ items }` of id, name, created, lastUsed, people only; the page is Settings → Passkeys); in the terminal it is the **What I can do** command (read only, agents included).
14171473
14181474 **Invites.** A forge admin who is a person mints a single-use invite link with `POST /api/v1/admin/invites` (`{"days": 14}`, 1 to 30, 7 by default); the response carries the link once and only its hash is kept. `GET /api/v1/admin/invites` lists them (open, used, revoked, expired) without tokens, and `DELETE /api/v1/admin/invites/:id` revokes one. Minting, revoking and using a link are events (`invite.minted`, `invite.revoked`, `invite.used`; the last names the invite and the account it let in, never the token). The same is the **Invite links** card on `/admin/limits` (a form with expiry days, 1 to 30; the new link is shown once, with a copy button; an open link has a Revoke button) and the terminal's **Invite links** command (`m` makes one and prints the link once, `x` revokes the selected open one). Over MCP, the `mint_invite` tool (`{days?}`, an admin token, a forge admin who is a person) answers with the same link, and the `invites` tool (`{action: "list"|"revoke", id?}`, the same person admin and admin token, for both actions) lists them without links or revokes one. While signup is `invite`, the link opens the door once: `/signup?invite=…` (the form and the passkey door) or `invite` in the `POST /api/v1/users` body. In the terminal, with signup = invite the create-account screen has a fourth, masked **Invite** field that takes the token (not the whole link); a blank one is asked for, and a bad one is refused with the same sentence as `/signup`. The account and the invite's use are one write, so two sign-ups with one link make one account; a used, revoked or expired link, or any link while signup is `closed`, makes none. While signup is `open`, a link is not spent.
14191475
@@ -1561,6 +1617,8 @@ its evidence, filed in `FORGE_SENTINEL_REPO` (default `trevato/forge`) as the
15611617 credential-shaped before it is filed. Other findings (`held`, `ledger`, `red`)
15621618 are filed anew when they return.
15631619
1620 A check that has never been green is filed only for the sentinel's own repository. In any other repository it stays on that repository's checks and the degraded list.
1621
15641622 A capacity setting away from its default is not a finding: the sentinel files
15651623 nothing for it (#3269). On `/settings/capacity` the row of each such setting
15661624 carries one muted line, "changed from X N days ago by who", and its **Put back**
@@ -1707,11 +1765,16 @@ The design check (`test/design-lint.test.ts`, run in the gate) fails a pull that
17071765 adds a colour literal or an off-scale `font-size` beyond
17081766 `docs/design/baseline.json`, or defines a class `docs/DESIGN.md` §5 does not
17091767 name; the message names the file or the class. The way out is to use a token
1710 (`var(--…)`) or a component §5 names; a new component goes into the §5 table
1711 first. When a change lowers the counts, run `bun scripts/design-lint.ts
1768 (`var(--…)`) or a component §5 names; a new component is named in its own
1769 `docs/design/areas/<area>.md`. When a change lowers the counts, run `bun scripts/design-lint.ts
17121770 --update` and commit the baseline; when it deletes the last rule for a class
17131771 in the §5d register, strike the name there too. See `docs/design/plan.md`.
17141772
1773 `docs/DESIGN.md` is a spine: each of its sections is its own file under
1774 `docs/design/sections/` (§5d is `5d-page-local-classes.md`), linked from the
1775 spine in order, and the check reads them in that order. A new section is a
1776 new file and a new line in the spine.
1777
17151778 `bun run check` is the gate: the same command `forge.json` declares, so what
17161779 it says here is what the deploy will say. It type-checks once, then runs the
17171780 test files `scripts/gate.ts` admits — every `test/*.test.ts` not in its
@@ -1875,6 +1938,8 @@ longer hollow turns the check red, so the list only shrinks.
18751938
18761939 ## Following an upstream
18771940
1941 A followed repository's home shows admins "N commits behind owner/name" (or "conflicts with owner/name: resolve") from the last stored check, with an **Update** button: a same-origin POST form to the settings page's check action that returns to the home, no JS. The terminal's About card (`I`) has the same words as a `behind` row, and `u` is the same update (`behindWords`, `src/actions/upstream_follow.ts`).
1942
18781943 A repository can follow an outside git branch (`repo_upstream`, https or
18791944 http only, no credentials in the address). The clock checks each following
18801945 repository every 30 minutes (`checkDue`); the result is the follow row:
@@ -1904,6 +1969,20 @@ in the web settings first" (the address is set on the settings page). A check fe
19041969 the fetched head, the check fails (`squatted`), says so on the row, opens
19051970 no pull and leaves the branch as it was.
19061971
1972 ## Ranked forks
1973
1974 `/:owner/:name/forks` and the terminal's forks screen (`f` in a repository)
1975 list a repository's direct forks the same way, so the best of a fork tree
1976 rises. Order: commits ahead of the parent's default branch (most first),
1977 then fewest behind, then the newest tip commit. Each row reads `N ahead · M
1978 behind` and when the fork last moved; a fork that is ahead has a **Compare**
1979 button (on the page) to its `/pulls/new`, which proposes it to the parent.
1980 Forks with nothing ahead (or whose standing git cannot read) follow under
1981 `N forks with nothing new`. At most 60 forks are ranked per view; past that
1982 the page says `Ranking the first 60 of N forks`. A fork's standing is cached
1983 by the pair of tips (`actions/forks.ts`), so a view of forks that have not
1984 moved costs one `git log` per fork.
1985
19071986 ## Shape
19081987
19091988 ```
@@ -2200,3 +2279,12 @@ The here-manifest (`GET /api/v1/here?path=…`) reads the same for guests and
22002279 members. On `/explore` and `/search` it names the page's own read, `?q=` carried
22012280 over and encoded: `GET /api/v1/explore?q=…` (MCP tool `explore`) or
22022281 `GET /api/v1/search?q=…` (MCP tool `search`), listed once.
2282
2283 ### Child quota
2284
2285 `FORGE_CHILD_CPUS`, `FORGE_CHILD_MEMORY_MIB` and `FORGE_CHILD_DISK_MIB` declare
2286 what all children together may hold; each is the sum of the sizes in the spawn
2287 ledger (`spawn/sizes.ts`). **Unset means no quota.** A spawn that would pass a
2288 declared limit is a 409 `refused` with one sentence naming it, and the New
2289 forge page shows that sentence above the form when even a small forge would
2290 not fit (`spawn/quota.ts`).
docs/CACHING.md +19
@@ -183,6 +183,10 @@ and rounds to 0.0):
183183 event on the repository (see "Gaps") and spend reported by another
184184 process.
185185
186 ### 2b. The API map: the finished answer, by the write clock (#3321)
187
188 `GET /api/v1/repos/:owner/:name/map` keeps its whole answer in `web/map_snapshot.ts`, keyed by repository, the viewer's sealed scope and the UTC minute (the week's merge window slides with time) and valid only under the forge's write clock, so a plan, or any write, drops it before the next read. A hit still names the five phases, flagged as hits. Test: `test/map-seed-timing.test.ts`.
189
186190 ## Home (`/`)
187191
188192 ### 3. The feed's first page: per viewer
@@ -267,6 +271,21 @@ fixture; all three caches hit):
267271 | `panels` | 0.1 | 0.1 |
268272 | `feed` | 7.1 | 10.0 |
269273
274 ### 6. The waiting line: per viewer (#5806)
275
276 - **What:** how many asks wait on the viewer and the oldest's time (the
277 `waitingOn` scan over up to 200 repositories); the words are made fresh
278 for each request.
279 - **Key:** `waiting:{viewerId}`, read for the signed-in viewer only, so no
280 one reads another's count. `waiting` in `Server-Timing` carries `desc="hit"`.
281 - **Invalidated by:** every write, through the write clock (dismissals,
282 assignments, pulls, holds), as the KPI row is.
283 - **Max age:** 30 seconds.
284 - **Measured** (`test/home-200.test.ts`: 200 repositories, 100 assigned asks,
285 owner, second look): the miss cost `waiting` 7.5 ms, the largest read after
286 `feed`; a hit is under 0.1 ms. Every phase over 20 ms is named in the
287 test's output; none is over 20 ms in the sandbox.
288
270289 ### Not cached on home
271290
272291 The anonymous door (1.5 ms, 10 statements), the app shelf, and the
docs/CREW.md +4
@@ -36,6 +36,10 @@ Nesting a sandbox is not possible there, so `test/crew-sandbox.test.ts` checks
3636 the settings that enforce it (`allowLocalBinding` on, `allowAllUnixSockets` off,
3737 the `denyRead` list) and not the boundary itself.
3838
39 ## Where a run's time went
40
41 Every run that started ends its log with one `timing: run ended …s after the run started — clone … · brief … · harness …` line (plus `wrap-up` when the reserve was used), whatever way it ended; `src/apps/timing.ts` draws it.
42
3943 ## The sentinel (#1131)
4044
4145 The forge hunts its own faults. `src/crew/sentinel.ts` runs on the autonomy
docs/DESIGN.md +35 −1361

Diff not shown — 117,268 bytes of diff (limit 100,000). +35 −1361

View file
docs/FLOW.md +11
@@ -63,3 +63,14 @@ tick logs as `held=`, read through `flow/held.ts`, which keeps the rows 5 s.
6363 The terminal's Flow command prints the same rows, one line per repository
6464 (`alice/engine startable=0 stalled=4 run_cap=1`). A granted agent sees
6565 public repositories only, on both.
66
67 One of those filters is the hot-file WIP limit (#5934, `crew/hot_files.ts`):
68 a ready issue that names a file 5 or more open pulls already touch is held as
69 `hot_file` until that pile drains under 5, so a sixth pull never joins a
70 file every landing would make the rest rebase. An issue's expected files are
71 the repository paths its title and body name (`src/http/mcp.ts`,
72 `` `README.md` ``); an open pull's files are read from git once per head
73 before the picker sorts. The tick line names the hot files (`hot=src/http/mcp.ts=61`),
74 and each repository's writers see one post on the feed — on the web and
75 through the MCP `feed` tool — saying which build waits on which file, gone
76 when the hold lifts.
docs/HOME-EVAL.md added +34
@@ -0,0 +1,34 @@
1 # Scoring the owner's home
2
3 The owner's words, from #5735 (2026-10-25): "it's still kinda hard for me to catch up with what was done… the widgets and graphs are nice… but when I scroll down the 'what you asked for' is just not helpful, and the pull requests/decisions, crew words, releases, and the agents buttons do nothing. This was supposed to be like an X feed… iterate heavily, and the validation should be sending an agent with no context to read the feed, then produce a summary in its own words. That must align and get closer over time while also getting more concise and direct. Measure the real time it takes to produce, so that we can target fast comprehension."
4
5 ## The method
6
7 1. Fetch `/` as the owner and convert it to text: what the eye sees, with scripts and styles stripped (`bun scripts/home-read.ts <url>`, #5765).
8 2. A fresh agent with no context reads only that text and answers, in at most 150 words: what got done, what needs me and what I'd do about it, what's worrying, and its confidence. The steward runs this step.
9 3. Score it against ground truth on three numbers: **coverage** of the 5 things that truly mattered, **errors** (claims the page made wrong), and **seconds** to produce.
10 4. Repeat after every feed change. The target: coverage ≥ 4 of 5, 0 errors, under 15 s, and falling words.
11
12 ## The deterministic half
13
14 `bun scripts/home-eval.ts <forge-url>` does step 1 and scores the page itself, so the crew can run it on every feed change. Set `FORGE_COOKIE` (the owner's session) and/or `FORGE_TOKEN` (a `ro` bearer token); neither is printed. It prints each fact as `stated`, `missing` or `wrong` with the page's words beside what the forge says, then `coverage N of 5 · errors N · chars N · fetched in N ms`.
15
16 The five facts, and where the truth comes from:
17
18 | Fact | Truth | `stated` when the page says | `wrong` when |
19 | --- | --- | --- | --- |
20 | landed and released | `GET /api/v1/telemetry/home`: landings in 24 h, the live version | `N changes in 24 h` and the live short sha | N differs |
21 | waiting on the owner | the same: the home's own ask list | `N waiting on you` (or nothing at zero) | N differs, or a line at zero |
22 | builders idle and why | the same: running of slots, and the reason (ceiling reached, no slots, no ready work) | the right `N of M` and the reason | `N of M` differs |
23 | spend against the forge cap | the same: spent today and the daily ceiling | `$X of $Y` | X or Y differs, or `no ceiling` while one is set |
24 | repositories with no commit in 3 days | `GET /api/v1/repos` then each repository's newest commit | every quiet repository named on a line with `no commit`, `quiet`, `stalled` or `silent` | such a line names a repository that is not quiet |
25
26 Limits: the window is the last 24 hours, the one `/api/v1/telemetry/home` reads; landings are counted, not named. A fact the page may rightly leave out (nothing waiting, no quiet repository) scores `stated` when the page does not claim otherwise. The cold-read agent of step 2 stays the steward's.
27
28 ## Results
29
30 One row per feed pull, newest last. Coverage is out of 5; `agent s` is the cold read's seconds (steward), `script` is the fetch time of `home-eval.ts`.
31
32 | Date | Pull | Coverage | Errors | Chars | agent s | script ms | Note |
33 | --- | --- | --- | --- | --- | --- | --- | --- |
34 | 2026-10-25 | baseline (#5735) | ~1.5 | 2 | 7,333 | 21.8 | — | ceiling shown as `no ceiling`; "5 waiting" listed 3 |
docs/HUNT.md added +13
@@ -0,0 +1,13 @@
1 # Hunters (#5846)
2
3 `bun scripts/hunt.ts <origin>` runs the detector sets in `src/hunt/` against one app and prints findings as JSON (exit 1 when there are any). It is GET-only by construction (`probe.ts` has no other method), same-origin only, and ends after one pass.
4
5 | Lane | Module | Detectors |
6 |---|---|---|
7 | Front door | `door.ts` | personal pages send anonymous visitors to sign-in with `next=`; public pages answer 200; unknown path is 404 |
8 | UI (links) | `links.ts` | every link on the top pages: no 404/5xx, and a link landing on `/` must be labelled Home (#5844) |
9 | Contract | `contract.ts` | no OpenAPI GET route answers 5xx; the status is documented or a refusal |
10
11 A finding's `key` is stable (`detector:subject`): one issue per key, a comment only when the evidence changes.
12
13 Not built yet: headless-browser lane (buttons, console errors, fold, overflow), flows, speed, the schedule (post-release and 08:00Z), filing issues, the KPI card on home, and the weekly retro.
docs/MCP.md +145 −84
@@ -25,87 +25,124 @@ for a tunnel and a forge that sleeps.
2525
2626 ## Tools
2727
28 | tool | does | writes |
29 | -------------- | ------------------------------------------------------------------------------------------------- | ------ |
30 | `apps` | the apps you can see: live or not, where served, how each runs itself, what is working | |
31 | `new_app` | `{ name, description?, owner?, visibility?, agent?, pick? }`: make an app from a sentence; answers `{ repo, url, issue, agent, run }` (`run` is the first run's state, or `none`) and draws the `ui://forge/app` card: name, production URL, first issue, agent, first run; refused as `POST /api/v1/apps` is (unverified, app_limit, no_such_agent, name_taken) | yes |
32 | `repo` | `{ repo }`: one repository's description, visibility, autonomy, `audience { level, sentence }` and `provenance` (where a migrated one came from, `null` when hidden), the same as `GET /api/v1/repos/:owner/:name` | |
33 | `repo_settings` | `{ repo, description?, visibility? }` (admin token): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid` | yes |
34 | `tell` | a sentence becomes an issue, a builder is picked, a run starts on the crew's next tick | yes |
35 | `thought` | `{ id }`: where one of your thoughts went (its id comes from `tell` without a repo): the placement, and the earlier thoughts it repeats or takes back and the later ones that did the same; not yours and not there answer alike, `not_found` | |
36 | `say` | speak on an issue or a pull; a working builder hears it as its next step | yes |
37 | `issue` | `{ repo, number }`: one issue's title, state, closeReason, body, labels, assignee, comments (author, authorIsAgent, body, at) and blockedBy/blocks, as `GET …/issues/:number`; a sealed one you cannot see is not found | |
38 | `pull` | `{ repo, number }`: a pull's title, state, head and base, and for an open pull whether it merges into the base's current head (`mergeable`) and the paths that stop it (`conflicts`), and `check: { state, baseOid }`: the latest check's state and the base tip it was merged with (empty when it merged nothing); `mergeable` and `conflicts` are the same fields as `GET …/pulls/:number`, `check` is `state` and `run.baseOid` from `GET …/pulls/:number/checks` | |
39 | `edit` | a new title or body for an issue or a pull: its author's, or a writer's; an agent edits only what it wrote | yes |
40 | `close` | `{ repo, number, state?, reason?, into? }`: close an issue or a pull (`state` closed by default) or reopen it (`open`); the same rules and refusals as `PATCH …/issues/:number`: an agent closes only what the rules give it and reopens nothing; answers `state` and `closeReason` | yes |
41 | `pulls` | `{ repo, state?, limit? }`: a repository's pulls, newest first, one brief line each: `number`, `title`, `author`, `head`, `check` (state), `approvals`, `changesRequested`, `mergeable` (null once closed); `state` open (default) or closed, `limit` 1-50 (default 20); no bodies, no diffs | no |
42 | `read_file` | a file (utf-8, or base64 for binary) or a directory listing at a ref, as GET …/contents | no |
43 | `seal` | `{ repo, number, sealed }`: seal a security report (and the pull that fixes it) so only writers and the crew see it, or unseal it for every reader; a writer's, recorded | yes |
44 | `secrets` | `{ scope, ref?, action, name?, value? }` (forge admin): `list` the names and timestamps of the forge's sealed secrets, `set` or `remove` one; `scope` is forge, org or repo, `ref` the org or `owner/name`; a value is never read back | yes |
45 | `org_teams` | `{ org, action, team, user?, permission? }` (admin-scope token, an org owner): `create` a team (`permission` read, write or admin; read by default), `add_member` a `user`, or `remove` the team; the same as POST/DELETE `/api/v1/orgs/:org/teams` | yes |
46 | `now` | what the crew is doing right now: who, on what, since when, at what cost; a planner that declined the direction and waits for you comes first (`run: null`, its words in `says`) | |
47 | `next_steps` | on a spawned forge, your first three steps and whether each is done; empty elsewhere or for anyone but its owner | |
48 | `returns` | `{ repo?, days? }`: what the crew's tokens bought over the last `days` (1–90, default 7): dollars, runs, changes landed, cost per change; `repo` narrows it to one app of yours | |
49 | `stop` | stop one run by its id from `now` | yes |
50 | `health` | how this forge is: the version and commit it runs, draining or not, the rollout and its incidents | |
51 | `system` | the machine the forge runs on, now: CPU, load, memory, disk, network, processes; a forge admin, or an agent granted `telemetry:read` | |
52 | `cloud_accounts` | the forge's cloud accounts, each attached provider token with its use, verification, write permission and today's calls; a forge admin only (counted as a write so a `ro` token never lists them) | yes |
53 | `cloud_account` | `{ verb, provider, name, value?, to?, allowed?, repo? }`: change a cloud account: `attach` or `rotate` a token (`value`), `verify` it, `rename` it (`to`), `remove` it, `allow_writes` (`allowed` true or false) or `audit` (`repo` owner/name); a forge admin with an admin-scope token; answers a one-line `says` | yes |
54 | `audit` | who can do what, per app, read from its contract.json in git: yes, own or no per door, and whether outsiders may direct its crew (`crewOutsiders`) | |
55 | `account_verify` | `{ username }`: mark a person's email verified, as `POST …/admin/accounts/:username/verify` does; a person admin's, with an admin token | yes |
56 | `outsiders` | `{ repo, on?, dryRun? }`: whether people who cannot write may direct the crew; with `on`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent | yes |
57 | `origins` | `{ action, id? }`: `list` your connected origins, `repos` the repositories one holds (`id`; `mirroredAs` says which are already here), or `sync` one now; the same as `GET /api/v1/user/origins`, `…/:id/repos` and `POST …/:id/sync`, for you only, an admin token as there; never a credential in an answer | yes |
58 | `decisions_by` | `{ repo, by?, dryRun? }`: the standing rule for a repository's hand-overs (`me`, `decider`, `decider_tell`); with `by`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent | yes |
59 | `archive` | `{ repo | repos, archived?, dryRun? }`: archive (true) or wake (false) a repository, by name; planned first (`dryRun` is true unless `false`); only the repository's admin with an admin token, never an agent. `repos` (at most 50) runs the fleet `archive` operation over them, answers each one's outcome and the `operation` id; `limb` with `action: "undo"`, that `operation` and any one of the repositories as `app` reverts it for a day | yes |
60 | `events` | `{ repo, limit?, cursor? }`: the repository's events, newest first, as you may see them (a webhook's URL and an app's variable names are the admins'): `{ items, next_cursor }`, `limit` 1 to 200 (default 50), `cursor` from `next_cursor` | no |
61 | `reports` | `{ repo, id?, action? }`: the waiting reports from outsiders, each `from: "outside"` (their words are unchecked); with `id` and `action` (`accept` opens it as an issue marked as from outside, `dismiss` closes it). A person who writes the repository only; needs an `rw` token | yes |
62 | `trail` | `{ repo, shown?, dryRun? }`: where a migrated repository came from (`provenance`: source, sourceUrl, parents, migratedAt) and whether it is shown; with `shown`, shows or hides the trail — planned first (`dryRun` is true unless `false`), only the repository's admin with an admin token, never an agent. Hiding keeps the record; a hidden one reads `null` to anyone but an admin | yes |
63 | `branches` | `{ repo, name?, action?, from?, kind? }`: without `name`, lists the branches; `kind: "tags"` lists the tags instead (as GET `/api/v1/repos/:owner/:name/tags` does, newest first; no `name` or `action`); with `name` and `action` (`create` from `from`, or `delete`) it does what the branches page does: the default branch is never deleted, only a writer may act | yes |
64 | `migrate` | `{ url, name?, crew? }` brings a public repository in by URL (history only; nothing reaches back) and answers `{ job, state, url }`; `{ job }` alone reads that job. Same validation, scope (`rw`) and private-address refusal as `POST /api/v1/migrate` | yes |
65 | `commits` | `{ repo, ref?, limit? }`: a branch's recent commits, newest first (`limit` 1–100, default 30; refused outside that, where REST clamps), as `GET …/commits` answers | |
66 | `probe` | knock on a running app's doors as nobody, a user and an admin; the ones that disobey its contract | |
67 | `following` | where a fork stands against what it follows, and what the crew is doing about it | |
68 | `spawn` | `{ name, apps?, crew?, dryRun? }`: a child forge, planned first (`dryRun` is true unless `false`); an admin's, and an `ro` token may plan but not make | yes |
69 | `agent` | `{ action, username, … }`: `create` a crew agent, `update` its `model`, `brief` or `budgetUsd`, or `remove` it; an admin's, with an `admin` token, as `/api/v1/agents` | yes |
70 | `claim_link` | `{ name }`: a new claim link for a child you spawned that nobody has claimed; the old one stops working. An admin's | yes |
71 | `upstream` | `{ repo, enabled?, url?, branch?, check? }`: the repository a fork follows (an admin reads it); with `enabled` sets it, with `check: true` checks it now; setting and checking need an admin token | yes |
72 | `take_updates` | a fork takes its parent's updates when git can do it alone; a conflict is refused. On a spawned forge's code repository it opens the one `forge/take-updates` pull and never moves the default branch | yes |
73 | `converge` | the fork's crew merges where both sides changed the same files; comes back as a pull | yes |
74 | `asked` | `{ repo?, show?, order? }`: what people asked the crew for, by default nothing merged yet and oldest first: who and when, the pulls that close it, the crew's last activity, waiting/building/shipped/closed, stale when not shipped in three days and flagged when stale with nothing built; repositories you can write | |
75 | `assigned` | `{ limit? }`: the open issues and pulls assigned to you in every repository you can still read (repository, number, title, kind, state), as `GET /api/v1/user/assigned` | |
76 | `app_members` | `{ repo, members?, dryRun? }`: the people a private app names, who may enter it and its previews and nothing else; a writer (never an agent) changes the list with an admin-scope token | yes |
77 | `explore` | `{ query? }`: the apps and people you can see, ranked by forks, ships, use and freshness, with their numbers; `kind:` `sort:` and words in one line | |
78 | `search` | `{ q, kind?, repo? }`: issues, pulls, repositories and code you can read, the same results as /search; `repo` keeps to one | |
79 | `feed` | `{ limit?, cursor? }`: your home timeline — tells, replies, runs, changes and looks — ranked, with who, what, why and a link; the same items as `GET /api/v1/feed` | |
28 <!-- tools:begin: generated by `bun scripts/mcp-tools.ts` from each tool's `doc` -->
29
30 | tool | does | writes |
31 | ---- | ---- | ------ |
32 | `access` | `{ since?, ua?, path? }`: what outside agents tried: the redacted log of non-browser requests to public paths, newest first; `since` an ISO time (default a day, at most 14 days), `ua` part of the user agent, `path` a prefix; a forge admin's | yes |
33 | `account_role` | `{ username, role, usdPerMonth?, dryRun? }`: make a person a `member`, or a `guest` again, with an optional starter allowance (`usdPerMonth`, 0.01 to 10000, promoting only); planned first (`dryRun` is true unless `false`) | yes |
34 | `account_suspend` | `{ username, suspended }`: suspend a person's account, or unsuspend it with `false`; their sessions and tokens stop at once; the API's rules (not yourself, another admin or an agent; not the only owner of an organization); an admin token | yes |
35 | `account_verify` | `{ username }`: mark a person's email verified, as `POST …/admin/accounts/:username/verify` does; a person admin's, with an admin token | yes |
36 | `accounts` | `{ cursor?, limit? }`: the forge's accounts, newest first: `username`, `role`, `verified`, `suspended`, `created`, and `next` (a cursor, or null); `limit` 1-50 (default 20); a person admin's | |
37 | `agent` | `{ action, username, … }`: `create` a crew agent, `update` its `model`, `brief` or `budgetUsd`, or `remove` it; an admin's, with an `admin` token, as `/api/v1/agents` | yes |
38 | `app_deploy` | `{ repo, env, action }`: `redeploy` or `stop` an app's `production` or a pull's `pull-N` preview; a writer's, queued as `POST …/app/:env/redeploy` and `…/stop` are; answers `{ queued, run }` or `{ stopped }` | yes |
39 | `app_env` | `{ repo, action, name?, value?, scope? }`: `list` an app's variable names and scopes, `set` one, or `unset` it, in `all` (default), `production` or `preview`; the API's rules and errors, an admin of the repository with an admin-scope token; a value is never read back | yes |
40 | `app_members` | `{ repo, members?, dryRun? }`: the people a private app names, who may enter it and its previews and nothing else; a writer (never an agent) changes the list with an admin-scope token | yes |
41 | `apps` | the apps you can see: live or not, where served, how each runs itself, what is working | |
42 | `archive` | `{ repo | repos, archived?, dryRun? }`: archive (true) or wake (false) a repository, by name; planned first (`dryRun` is true unless `false`); only the repository's admin with an admin token, never an agent. `repos` (at most 50) runs the fleet `archive` operation over them, answers each one's outcome and the `operation` id; `limb` with `action: "undo"`, that `operation` and any one of the repositories as `app` reverts it for a day | yes |
43 | `asked` | `{ repo?, show?, order? }`: what people asked the crew for, by default nothing merged yet and oldest first: who and when, the pulls that close it, the crew's last activity, waiting/building/shipped/closed, stale when not shipped in three days and flagged when stale with nothing built; repositories you can write | |
44 | `assigned` | `{ limit? }`: the open issues and pulls assigned to you in every repository you can still read (repository, number, title, kind, state), as `GET /api/v1/user/assigned` | |
45 | `audit` | who can do what, per app, read from its contract.json in git: yes, own or no per door, and whether outsiders may direct its crew (`crewOutsiders`) | |
46 | `board_delete` | `{ slug }` (person admins): delete a board by slug; its history keeps it | yes |
47 | `board_pins` | `{ op?, slug?, title?, by? }` (person admins): without `op`, the panels pinned to your home (`slug`, `title`); `pin` or `unpin` a panel by board `slug` and panel `title`, or `move` it up or down with `by` (-1 or 1) | yes |
48 | `board_write` | `{ slug, board }` (person admins): write a whole board under a slug, made or replaced: `{ title, range, refresh, panels: [{ title, chart, query, w, h }] }` | yes |
49 | `boards` | `{ slug?, panel?, from?, to?, step? }` (person admins): without `slug`, lists the forge's boards (slug, title, range, refresh, panels); with `slug`, that board; with `panel` (place from 0, up to 23), that panel's data over the `from`/`to` window and `step` | |
50 | `branches` | `{ repo, name?, action?, from?, kind? }`: without `name`, lists the branches; `kind: "tags"` lists the tags instead (as GET `/api/v1/repos/:owner/:name/tags` does, newest first; no `name` or `action`); with `name` and `action` (`create` from `from`, or `delete`) it does what the branches page does: the default branch is never deleted, only a writer may act | yes |
51 | `claim_link` | `{ name }`: a new claim link for a child you spawned that nobody has claimed; the old one stops working. An admin's | yes |
52 | `close` | `{ repo, number, state?, reason?, into? }`: close an issue or a pull (`state` closed by default) or reopen it (`open`); the same rules and refusals as `PATCH …/issues/:number`: an agent closes only what the rules give it and reopens nothing; answers `state` and `closeReason` | yes |
53 | `cloud_account` | `{ verb, provider, name, value?, to?, allowed?, repo? }`: change a cloud account: `attach` or `rotate` a token (`value`), `verify` it, `rename` it (`to`), `remove` it, `allow_writes` (`allowed` true or false) or `audit` (`repo` owner/name); a forge admin with an admin-scope token; answers a one-line `says` | yes |
54 | `cloud_accounts` | the forge's cloud accounts, each attached provider token with its use, verification, write permission and today's calls; a forge admin only (counted as a write so a `ro` token never lists them) | yes |
55 | `commits` | `{ repo, ref?, limit?, oid? }`: a branch's recent commits, newest first (`limit` 1–100, default 30; refused outside that, where REST clamps), as `GET …/commits` answers; with `oid` (4–64 hex) one commit with its diff and its check, as `GET …/commits/{oid}` and `…/check` answer | |
56 | `confirm_wait` | `{ app, issue, blocker }`: a person says `issue` may go ahead although `blocker` closed as dropped or split; the API's confirm action, so writers only and never the crew | yes |
57 | `contribute` | for any arriving agent: what this forge is, its bottleneck, open “help wanted” issues, how to propose | |
58 | `converge` | the fork's crew merges where both sides changed the same files; comes back as a pull | yes |
59 | `decisions_by` | `{ repo, by?, dryRun? }`: the standing rule for a repository's hand-overs (`me`, `decider`, `decider_tell`); with `by`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent | yes |
60 | `edit` | a new title or body for an issue or a pull: its author's, or a writer's; an agent edits only what it wrote | yes |
61 | `egress_grants` | `{ repo, op?, destination? }`: the private `host:port` destinations an app's forge.json asks for and which are granted; `op` grant or revoke by a site admin (never an agent), and every op needs an admin-scope token; the same as the settings page and `/api/v1/repos/:owner/:name/egress-grants` | yes |
62 | `email_verify` | no input: send the caller a new verification email, with the API's rate limit and errors; the answer never carries the link | yes |
63 | `events` | `{ repo, limit?, cursor? }`: the repository's events, newest first, as you may see them (a webhook's URL and an app's variable names are the admins'): `{ items, next_cursor }`, `limit` 1 to 200 (default 50), `cursor` from `next_cursor` | |
64 | `explore` | `{ query? }`: the apps and people you can see, ranked by forks, ships, use and freshness, with their numbers; `kind:` `sort:` and words in one line | |
65 | `family` | the forge that sent this one and, for a site admin, those it sent, with state and version | |
66 | `feed` | `{ limit?, cursor? }`: your home timeline — tells, replies, runs, changes and looks — ranked, with who, what, why and a link; the same items as `GET /api/v1/feed`; `quietRuns` counts agent runs of the last 24 h that pushed, opened or said nothing, which the timeline leaves out | |
8067 | `feed_chips` | `{ kind?, value?, hidden? }`: the feed chips you switched off, which `feed` and `asks` leave out; with `kind` (`kind` or `person`), `value` and `hidden` it switches one off or on | yes |
81 | `make_it_yours` | `{ repo, name?, visibility?, dryRun? }`: a fork of an app you can see, as your own app, following the original; code and history copied, data and secrets not; private unless `visibility` is public (a public original only); at most 5 copies an account a day; plans unless `dryRun` is false | yes |
82 | `origin_apps` | `{ action, id?, host?, kind?, clientId?, clientSecret? }`: `list` your OAuth apps for connecting origins, `add` one (a `host`, or `kind` github), or `remove` one by `id`; the API's rules and errors, an admin-scope token; a secret is never read back, only `hasSecret` | yes |
83 | `front_page` | `{ pinned?, hidden?, weights?, dryRun? }`: the front page as a stranger sees it, ranked, with numbers; a site admin sets what is pinned (first public one featured), hidden, and what counts (weights of forks, ships, use, fresh, 0 to 10) | yes |
84 | `invites` | `{ action, id? }`: `list` the outstanding invites (state and expiry, never a link) or `revoke` one by `id`; a person admin with an admin token, stricter than the API's list, which an `ro` token may read | yes |
85 | `map` | an app's plan: ready now, waiting on what, the critical path, where the crew is, parked twice and why (`app`); draws the `ui://forge/map` card | |
86 | `milestones` | `{ app, issue? }`: how far each thing asked for is (and, with `issue`, whether you watch it: `watching`), from the dependency tree: the plan's limbs with their weights, or one milestone opened (who is building, what is blocked and on what, what merged in 7 days, an estimate, and for an owner `spend`: dollars, changes landed ever, the costliest three issues) | |
87 | `limb` | `{ app, issue, action, reason?, pillar?, operation?, dryRun? }`: defer, resume or close a whole limb as not doing, or undo an operation; plans unless `dryRun` is false, and applying takes an admin token | yes |
88 | `watch` | `{ app, issue, watch? }`: watch a milestone, or stop with `watch: false`: one item in your feed that follows it, and one push to your phone when it lands | yes |
89 | `runs` | `{ repo, limit? }`: the repository's recent runs, newest first (id, kind, state, issue or pull number, started, ended), 1–50, default 20; read as the runs page reads them | |
90 | `run_log` | `{ repo, run, tail? }`: a run's log, or its last `tail` lines (1–2000), with the REST route's access: a hidden log or unreadable repository is not found | |
91 | `review` | `{ repo, number, verdict, reason? }`: approve a pull (`approve`) or request changes (`changes`, with a `reason`), as the page does; a writer's or the crew's, and never your own pull | yes |
92 | `threads` | `{ repo, number, anchor?, resolved? }`: a pull's review threads with their comments; with `anchor` (from the list) resolve it (`resolved` true, the default) or reopen it (false), by the API's rules: a writer or someone who commented in the thread | yes |
93 | `usage` | `{ repo, days? }`: what the crew's runs spent — tokens, cost, wall time — by subscription, agent, issue, and each account's 5-hour and weekly standing; a writer's | |
94 | `labels` | `{ repo, number, labels }`: set an issue's or a pull's labels to exactly these (`[]` clears); only labels the repository has, by a writer | yes |
95 | `repo_labels` | `{ repo, action?, name?, color?, id? }`: list (`list`, the default; a read-only token may), create (`create`, `name`, `color` six hex digits) or remove (`remove`, `id`) the repository's labels, as `GET`/`POST …/labels` and `DELETE …/labels/:id`; create and remove need an admin token and a repository admin | yes |
96 | `wait_for` | `{ app, issue, blockedBy, stop? }`: the issue waits for another, or stops with `stop: true`; the page's rules, and the answer carries the issue's URL | yes |
97 | `confirm_wait` | `{ app, issue, blocker }`: a person says `issue` may go ahead although `blocker` closed as dropped or split; the API's confirm action, so writers only and never the crew | yes |
98 | `hold` | `{ app, pull, why?, release?, dryRun? }`: hold a pull so no rule reviews or lands it, or let it go; a person who can write, never an agent; plans unless `dryRun: false` | yes |
99 | `app_env` | `{ repo, action, name?, value?, scope? }`: `list` an app's variable names and scopes, `set` one, or `unset` it, in `all` (default), `production` or `preview`; the API's rules and errors, an admin of the repository with an admin-scope token; a value is never read back | yes |
100 | `email_verify` | no input: send the caller a new verification email, with the API's rate limit and errors; the answer never carries the link | yes |
101 | `plan` | `{ app, issues }`: open up to 12 linked issues, all or none (see below) | yes |
102 | `prompts` | `{ repo, action, kind?, token?, at?, id? }`: list, add, run or remove an app's prompt sources (Instagram), as the `…/prompts` API does; the token goes in once and is never shown; listed only for an admin-scope token, and only the repository's admin may use it | yes |
103 | `account_suspend` | `{ username, suspended }`: suspend a person's account, or unsuspend it with `false`; their sessions and tokens stop at once; the API's rules (not yourself, another admin or an agent; not the only owner of an organization); an admin token | yes |
104 | `account_role` | `{ username, role, usdPerMonth?, dryRun? }`: make a person a `member`, or a `guest` again, with an optional starter allowance (`usdPerMonth`, 0.01 to 10000, promoting only); planned first (`dryRun` is true unless `false`) | yes |
105 | `mint_invite` | `{ days? }`: mint a single-use invite link that expires in `days` (1–30, default 7) and is shown once; a person admin's, with an admin token | yes |
106 | `signup` | `{ mode?, dryRun? }`: who may sign up: `open` (default), `invite` (only a person with an open invite link) or `closed` (no new accounts); without `mode` it reads the setting, with `mode` it plans first (`dryRun` is true unless `false`), and applying needs an admin token | yes |
107 | `access` | `{ since?, ua?, path? }`: what outside agents tried: the redacted log of non-browser requests to public paths, newest first; `since` an ISO time (default a day, at most 14 days), `ua` part of the user agent, `path` a prefix; a forge admin's | yes |
108 | `whoami_can` | no input: your role and that role's row of the roles table, each ability yes or no | |
68 | `follow_mode` | `{ repo, … }`: choose how a spawned forge follows its parent, `tell-me` or `take-updates`; its `forge` repository's admin only | yes |
69 | `following` | where a fork stands against what it follows, and what the crew is doing about it | |
70 | `forge_proposals` | `{ repo }`: what this forge proposed to its parent, newest first; `reachable` is false if the parent did not answer | |
71 | `forges` | an admin's list of the forges sent from here: name, address, whom for, apps, claimed or not, last activity | |
72 | `front_page` | `{ pinned?, hidden?, weights?, dryRun? }`: the front page as a stranger sees it, ranked, with numbers; a site admin sets what is pinned (first public one featured), hidden, and what counts (weights of forks, ships, use, fresh, 0 to 10) | yes |
73 | `health` | how this forge is: the version and commit it runs, draining or not, the rollout and its incidents | |
74 | `hold` | `{ app, pull, why?, release?, dryRun? }`: hold a pull so no rule reviews or lands it, or let it go; a person who can write, never an agent; plans unless `dryRun: false` | yes |
75 | `hooks` | `{ repo, action, url, secret, kinds, id }`: `list`, `add` (`secret`, 16–200 characters, is required) or `remove` the repository's webhooks, as `…/hooks`; an admin-scope token on a repository you administer, and a secret is never shown | yes |
76 | `invites` | `{ action, id? }`: `list` the outstanding invites (state and expiry, never a link) or `revoke` one by `id`; a person admin with an admin token, stricter than the API's list, which an `ro` token may read | yes |
77 | `issue` | `{ repo, number }`: one issue's title, state, closeReason, body, labels, assignee, comments (author, authorIsAgent, body, at) and blockedBy/blocks, as `GET …/issues/:number`; a sealed one you cannot see is not found | |
78 | `labels` | `{ repo, number, labels }`: set an issue's or a pull's labels to exactly these (`[]` clears); only labels the repository has, by a writer | yes |
79 | `limb` | `{ app, issue, action, reason?, pillar?, operation?, dryRun? }`: defer, resume or close a whole limb as not doing, or undo an operation; plans unless `dryRun` is false, and applying takes an admin token | yes |
80 | `make_it_yours` | `{ repo, name?, visibility?, dryRun? }`: a fork of an app you can see, as your own app, following the original; code and history copied, data and secrets not; private unless `visibility` is public (a public original only); at most 5 copies an account a day; plans unless `dryRun` is false | yes |
81 | `map` | an app's plan: ready now, waiting on what, the critical path, where the crew is, parked twice and why (`app`); draws the `ui://forge/map` card | |
82 | `migrate` | `{ url, name?, crew? }` brings a public repository in by URL (history only; nothing reaches back) and answers `{ job, state, url }`; `{ job }` alone reads that job. Same validation, scope (`rw`) and private-address refusal as `POST /api/v1/migrate` | yes |
83 | `milestones` | `{ app, issue? }`: how far each thing asked for is (and, with `issue`, whether you watch it: `watching`), from the dependency tree: the plan's limbs with their weights, or one milestone opened (who is building, what is blocked and on what, what merged in 7 days, an estimate, and for an owner `spend`: dollars, changes landed ever, the costliest three issues) | |
84 | `mint_invite` | `{ days? }`: mint a single-use invite link that expires in `days` (1–30, default 7) and is shown once; a person admin's, with an admin token | yes |
85 | `mirror_set` | `{ action, endpoint?, bucket?, region?, accessKey?, secretKey? }` (forge admin, admin-scope token): `set` seals the off-box snapshot mirror, `forget` clears it; the Backups page's rules and refusals, a blank field keeps what was sealed; answers `{ place, says }`, never a key | yes |
86 | `new_app` | `{ name, description?, owner?, visibility?, agent?, pick? }`: make an app from a sentence; answers `{ repo, url, issue, agent, run }` (`run` is the first run's state, or `none`) and draws the `ui://forge/app` card: name, production URL, first issue, agent, first run; refused as `POST /api/v1/apps` is (unverified, app_limit, no_such_agent, name_taken) | yes |
87 | `next_steps` | on a spawned forge, your first three steps and whether each is done; empty elsewhere or for anyone but its owner | |
88 | `now` | what the crew is doing right now: who, on what, since when, at what cost; a planner that declined the direction and waits for you comes first (`run: null`, its words in `says`) | |
89 | `org_teams` | `{ org, action, team, user?, permission? }` (admin-scope token, an org owner): `create` a team (`permission` read, write or admin; read by default), `add_member` a `user`, or `remove` the team; the same as POST/DELETE `/api/v1/orgs/:org/teams` | yes |
90 | `origin_apps` | `{ action, id?, host?, kind?, clientId?, clientSecret? }`: `list` your OAuth apps for connecting origins, `add` one (a `host`, or `kind` github), or `remove` one by `id`; the API's rules and errors, an admin-scope token; a secret is never read back, only `hasSecret` | yes |
91 | `origins` | `{ action, id? }`: `list` your connected origins, `repos` the repositories one holds (`id`; `mirroredAs` says which are already here), or `sync` one now; the same as `GET /api/v1/user/origins`, `…/:id/repos` and `POST …/:id/sync`, for you only, an admin token as there; never a credential in an answer | yes |
92 | `outsiders` | `{ repo, on?, dryRun? }`: whether people who cannot write may direct the crew; with `on`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent | yes |
93 | `parent_unlink` | no input: stop signing in through the parent forge, as Settings does; refused when it is the account's last way in, and "Nothing to unlink." when nothing is linked; an admin token | yes |
94 | `plan` | `{ app, issues }`: open up to 12 linked issues, all or none (see below) | yes |
95 | `preview` | `{ url }`: what the forge pill says of an app host's URL (production or a pull's preview): `{ app, environment, pull: { number, title } \| null, check: "green" \| "red" \| "running" \| null, firstFailure, logUrl, working: [names] }`; `firstFailure` is the check's first failing test or its summary, `logUrl` is set only for someone who may read the log (a writer), `working` names the agents with a run going; a URL that is not one of this forge's app hosts is `invalid`, an app you cannot read is `not_found` and a pull you cannot see is `no_such_pull`, as `repo` and `pull` say | |
96 | `probe` | knock on a running app's doors as nobody, a user and an admin; the ones that disobey its contract | |
97 | `prompts` | `{ repo, action, kind?, token?, at?, id? }`: list, add, run or remove an app's prompt sources (Instagram), as the `…/prompts` API does; the token goes in once and is never shown; listed only for an admin-scope token, and only the repository's admin may use it | yes |
98 | `propose_to_parent_forge` | `{ repo }`: offer this forge's landed change to its parent as a pull on `child/<name>/…`; the same tip answers with that pull | yes |
99 | `pull` | `{ repo, number }`: a pull's title, state, head and base, and for an open pull whether it merges into the base's current head (`mergeable`) and the paths that stop it (`conflicts`), and `check: { state, baseOid }`: the latest check's state and the base tip it was merged with (empty when it merged nothing); `mergeable` and `conflicts` are the same fields as `GET …/pulls/:number`, `check` is `state` and `run.baseOid` from `GET …/pulls/:number/checks`; draws the `ui://forge/pull` card: `#N title`, state with check and conflicts while open, `head → base` linked to the pull, and the preview link when the pull has an environment | |
100 | `pulls` | `{ repo, state?, limit? }`: a repository's pulls, newest first, one brief line each: `number`, `title`, `author`, `head`, `check` (state), `approvals`, `changesRequested`, `mergeable` (null once closed); `state` open (default) or closed, `limit` 1-50 (default 20); no bodies, no diffs | |
101 | `read_file` | a file (utf-8, or base64 for binary) or a directory listing at a ref, as GET …/contents | |
102 | `repo` | `{ repo }`: one repository's description, visibility, autonomy, `audience { level, sentence }` and `provenance` (where a migrated one came from, `null` when hidden), the same as `GET /api/v1/repos/:owner/:name` | |
103 | `repo_labels` | `{ repo, action?, name?, color?, id? }`: list (`list`, the default; a read-only token may), create (`create`, `name`, `color` six hex digits) or remove (`remove`, `id`) the repository's labels, as `GET`/`POST …/labels` and `DELETE …/labels/:id`; create and remove need an admin token and a repository admin | yes |
104 | `repo_settings` | `{ repo, description?, visibility? }` (admin token): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid` | yes |
105 | `reports` | `{ repo, id?, action? }`: the waiting reports from outsiders, each `from: "outside"` (their words are unchecked); with `id` and `action` (`accept` opens it as an issue marked as from outside, `dismiss` closes it). A person who writes the repository only; needs an `rw` token | yes |
106 | `returns` | `{ repo?, days? }`: what the crew's tokens bought over the last `days` (1–90, default 7): dollars, runs, changes landed, cost per change; `repo` narrows it to one app of yours | |
107 | `review` | `{ repo, number, verdict, reason? }`: approve a pull (`approve`) or request changes (`changes`, with a `reason`), as the page does; a writer's or the crew's, and never your own pull | yes |
108 | `run_log` | `{ repo, run, tail? }`: a run's log, or its last `tail` lines (1–2000), with the REST route's access: a hidden log or unreadable repository is not found | |
109 | `runs` | `{ repo, limit? }`: the repository's recent runs, newest first (id, kind, state, issue or pull number, started, ended), 1–50, default 20; read as the runs page reads them | |
110 | `say` | speak on an issue or a pull; a working builder hears it as its next step | yes |
111 | `seal` | `{ repo, number, sealed }`: seal a security report (and the pull that fixes it) so only writers and the crew see it, or unseal it for every reader; a writer's, recorded | yes |
112 | `search` | `{ q, kind?, repo? }`: issues, pulls, repositories and code you can read, the same results as /search; `repo` keeps to one | |
113 | `secrets` | `{ scope, ref?, action, name?, value? }` (forge admin): `list` the names and timestamps of the forge's sealed secrets, `set` or `remove` one; `scope` is forge, org or repo, `ref` the org or `owner/name`; a value is never read back | yes |
114 | `sever` | `{ repo }`: cut a spawned forge's link to the forge its code came from; its `forge` repository's owner only; deletes nothing | yes |
115 | `signup` | `{ mode?, dryRun? }`: who may sign up: `open` (default), `invite` (only a person with an open invite link) or `closed` (no new accounts); without `mode` it reads the setting, with `mode` it plans first (`dryRun` is true unless `false`), and applying needs an admin token | yes |
116 | `spawn` | `{ name, apps?, crew?, dryRun? }`: a child forge, planned first (`dryRun` is true unless `false`); an admin's, and an `ro` token may plan but not make | yes |
117 | `ssh_keys` | `{ action?, title?, key?, id? }`: list your own SSH keys (default), add one (`key` is an authorized_keys line, `title` optional) or remove one by `id`; the API's rules and errors, add and remove need an `rw` token | yes |
118 | `stop` | stop one run by its id from `now` | yes |
119 | `subscription_budget` | `{ id, usd }`: set an account's whole-life budget in dollars (up to the `subscription.budget_max_usd` limit), or clear it with `usd: null`, as the Subscriptions page does; a locked budget can only be lowered; a forge admin with an admin token | yes |
120 | `subscription_headroom` | `{ id, percent }`: set the whole percent (0–90) of each window the crew leaves for people, as the Subscriptions page does; a forge admin's, with an admin token | yes |
121 | `system` | the machine the forge runs on, now: CPU, load, memory, disk, network, processes; a forge admin, or an agent granted `telemetry:read` | |
122 | `take_updates` | a fork takes its parent's updates when git can do it alone; a conflict is refused. On a spawned forge's code repository it opens the one `forge/take-updates` pull and never moves the default branch | yes |
123 | `telemetry_grant` | `{ agent, on }`: grant an agent `telemetry:read`, or take it back with `false`, as the Telemetry page does; a person admin's, with an admin token; answers `says` | yes |
124 | `tell` | a sentence becomes an issue, a builder is picked, a run starts on the crew's next tick | yes |
125 | `thought` | `{ id }`: where one of your thoughts went (its id comes from `tell` without a repo): the placement, and the earlier thoughts it repeats or takes back and the later ones that did the same; not yours and not there answer alike, `not_found` | |
126 | `threads` | `{ repo, number, anchor?, resolved? }`: a pull's review threads with their comments; with `anchor` (from the list) resolve it (`resolved` true, the default) or reopen it (false), by the API's rules: a writer or someone who commented in the thread | yes |
127 | `trail` | `{ repo, shown?, dryRun? }`: where a migrated repository came from (`provenance`: source, sourceUrl, parents, migratedAt) and whether it is shown; with `shown`, shows or hides the trail — planned first (`dryRun` is true unless `false`), only the repository's admin with an admin token, never an agent. Hiding keeps the record; a hidden one reads `null` to anyone but an admin | yes |
128 | `upstream` | `{ repo, enabled?, url?, branch?, check? }`: the repository a fork follows (an admin reads it); with `enabled` sets it, with `check: true` checks it now; setting and checking need an admin token | yes |
129 | `usage` | `{ repo, days? }`: what the crew's runs spent — tokens, cost, wall time — by subscription, agent, issue, and each account's 5-hour and weekly standing; a writer's | |
130 | `wait_for` | `{ app, issue, blockedBy, stop? }`: the issue waits for another, or stops with `stop: true`; the page's rules, and the answer carries the issue's URL | yes |
131 | `watch` | `{ app, issue, watch? }`: watch a milestone, or stop with `watch: false`: one item in your feed that follows it, and one push to your phone when it lands | yes |
132 | `whoami_can` | `{ kind? }`: your role and that role's row of the roles table, each ability yes or no; `kind: "passkeys"` lists your own passkeys (`{ items }`: id, name, created, lastUsed), people only | |
133
134 <!-- tools:end -->
135
136 ### Adding a tool
137
138 One tool, one file (#5924): `src/http/mcp/tools/<name>.ts` exports `tool`,
139 its definition and `run`, and nothing else; its arguments' shared helpers
140 are in `src/http/mcp/shared.ts`. Its row in the table above is its `doc`.
141 Then run `bun scripts/mcp-tools.ts`: it adds one line to the sorted
142 `tools/index.ts` and one row to the table, so two pulls adding two tools
143 edit no line in common. `test/mcp-tools.test.ts` holds every tool file to
144 the same contract and goes red when either generated file is stale; the
145 tool's own behaviour is tested in `test/mcp-<name>.test.ts`.
109146
110147 ### Room for a new tool
111148
@@ -122,6 +159,26 @@ a failure names the bytes over and the longest descriptions.
122159 Answers are JSON in a text block; most carry a `says` sentence short enough
123160 to relay as it is.
124161
162 ## Arguments, in full
163
164 `tools/list` keeps every argument description to 60 bytes (`test/mcp-size.test.ts`
165 enforces it); `dryRun` reads `false to apply` on every tool that takes it. The
166 longer sentences:
167
168 - `dryRun`: plans unless it is `false`; anything else changes nothing. `limb` applying takes an admin token.
169 - `tell.from`: a path on this forge the issue links to, like `/alice/notes/pulls/3`. `tell.context`: where this was told from, for the builder.
170 - `spawn.reveal`, `claim_link.reveal`: put the live claim link in the answer (default false); it is a secret, only when its person reads it. `spawn.fresh`: a fresh app beside the copied ones. `spawn.followMode`: `tell-me` (default) or `take-updates`. `spawn.size`: recorded only, not enforced. `spawn.keepAccess`: stay an owner once claimed.
171 - `commits.ref`: branch, tag or commit; the default branch when absent. `report.page`: the http(s) address where the problem was seen. `plan.issues.pillar`: the pillar served, as `"P0"` or `"P0 Trust"`; `later: true` means no pillar and needs `why`.
172 - `explore.query`: words, plus `kind:app|person|forge` and `sort:score|forks|ships|use|fresh|name`.
173 - `archive.repos`: several repositories, as `owner/name`, to archive in one operation.
174 - `milestones.issue`: the number of an issue that waits for others; the limbs when absent. `watch.issue` is the same number; `watch.watch` false stops watching, anything else watches.
175 - `limb.reason` (close): why it is not being done, in one sentence. `limb.pillar` (resume): the pillar to return it under. `limb.under` (raise, lower): `top` or a milestone number, only when the limb sits in several places.
176 - `asks.hide_kinds`, `asks.hide_people`, `feed.*`: leave out these kinds or usernames; replaces your saved filter.
177 - `audit.repo`: one app, as `owner/name`; every app you can see when absent.
178 - `model_ceiling.dailyUsd`/`perRunUsd`: 0.01–10000; both null clears; one null is refused. `model_grant.usdPerMonth`: 0 takes the grant back. `account_role.usdPerMonth`: omit or null for none.
179 - `hold.why`: why, in one line; it shows on the pull. `runs.limit`: how many, 1 to 50; 20 when absent.
180 - `boards.step`: with `panel`, seconds per bucket, or a count of `s`, `m`, `h` or `d`. `access.since`: ISO time; default a day, max 14 days.
181
125182 ## Connecting
126183
127184 Mint a token under **Settings → Access tokens** (`rw` to act, `ro` to watch),
@@ -167,7 +224,7 @@ can call `apps` and is refused `tell`.
167224 `src/http/oauth.ts`, `src/core/oauth.ts`, `src/web/pages/oauth.ts`,
168225 `test/oauth-flow.test.ts`.
169226
170 `src/http/mcp.ts`, `src/actions/tell.ts`, `test/mcp.test.ts`.
227 `src/http/mcp.ts`, `src/http/mcp/tools/`, `src/actions/tell.ts`, `test/mcp.test.ts`.
171228
172229 ## `plan`
173230
@@ -223,11 +280,15 @@ answers
223280
224281 ## Cards, the contract and the plugins (#1116)
225282
226 - **Cards.** `apps`, `new_app`, `now`, `asks`, `milestones`, `map` and `feed` name a `ui://` resource in
283 - **Cards.** `apps`, `new_app`, `now`, `asks`, `milestones`, `map`, `feed` and `pull` name a `ui://` resource in
227284 `_meta.ui.resourceUri` (MCP Apps, SEP-1865): `ui://forge/app`, `run`,
228 `decision`, `wave`, `map`, `feed`. The Plan card (`map`) shows one row per pillar with
285 `decision`, `wave`, `map`, `feed`, `pull`. The Plan card (`map`) shows one row per pillar with
229286 its ready, working and waiting counts, and the first five ready issues linked
230 to their pages; it has no actions. `resources/list` and `resources/read` serve one small
287 to their pages; it has no actions.
288 The Apps card (`apps`) links each `owner/name` row to the app's page on the forge and adds a
289 linked production row when the app has an http(s) URL; the `new_app` card links its
290 Production row the same way. Any other address stays plain text, never a link.
291 `resources/list` and `resources/read` serve one small
231292 sandboxed page, which draws the `structuredContent.card` model that the
232293 tool result carries, with `textContent` only. The model is built in
233294 `src/web/studio/cards.ts`. A card's
docs/ORIGINS.md +1 −1
@@ -607,7 +607,7 @@ POST /api/v1/repos/:o/:n/sync sync this mirror now; on a fork,
607607 POST /api/v1/repos/:o/:n/origin/reconnect {originId} → repo JSON; re-attach a
608608 detached mirror (admin token, repo
609609 admin, own origin; else 404/422 code)
610 GET /api/v1/user/pins PUT/DELETE /api/v1/user/pins/:owner/:name
610 GET /api/v1/user/pins ({items, next_cursor}; ?limit=1..200, ?cursor=) PUT/DELETE /api/v1/user/pins/:owner/:name
611611
612612 POST /api/v1/migrate {source: {url} | {originId, fullName},
613613 owner?, name?, visibility?,
docs/SPAWN.md +1
@@ -16,6 +16,7 @@ and user accounts. The child mints its own. A test in #420 and #422 proves it.
1616 | ----- | ------------------------------------------------------- | ---------------- |
1717 | #420 | spawn plan: one validated value, dry-run | #383 |
1818 | #427 | placement seam; hosted inside the parent today | #420 |
19 | #2926 | `cell` placement: a child as its own `bun src/main.ts` in a cell held to its size (`spawn/cell.ts`); `hosted` where the host cannot hold a cell. The spawn answer and the children list say `placement` | #2925 |
1920 | #421 | spawn action: org, instance, apps as repos, briefs | #420, #427 |
2021
2122 `src/actions/spawn.ts` (#421): the child lives in `<data>/children/<bodyId>`; the parent keeps a ledger line in `<data>/spawn/<name>.json` so a retry resumes or answers. Subscription names are in the plan but not yet created in the child (a subscription is a token).
docs/STUDIO.md +2
@@ -463,6 +463,8 @@ page's signals (`core/front.ts`: forks by people, pulls merged this month,
463463 hours in use, how lately it shipped) with the numbers on each row, and — for
464464 a site admin — the forges this one spawned. One line narrows it and stays in
465465 the URL: `kind:app|person|forge`, `sort:score|forks|ships|use|fresh|name`,
466 `owner:<username>` (one account's apps and the person; each person row's
467 count of apps links there), `archived:yes` (put-away repositories too),
466468 and words to match. An agent's working fork is how the crew builds, not a
467469 find, and is left out; a private app's hours are told only to those who may
468470 enter it. Every app row offers **Make it yours** (a fork) to someone signed
docs/VISION.md added +26
@@ -0,0 +1,26 @@
1 # What the forge is for
2 The forge is a social place for building. Everyone who joins gets a whole forge of their own: their apps, and a crew that builds them. People share what they make, take what others made and mold it, and the best of it rises through a visible tree of forks, while anyone can stay as private and as different as they like. Opening it should feel like opening X: you get it at once. Steering it should take one thought: type it, go.
3
4 ## Order of work
5 0. **Trust, always first.** Agents are contained. Agent pulls are reviewed. The gate runs every test. Admin is a separate account from the everyday one, explained kindly and directly; using AI with admin stays possible but deliberate. Private by default, and always plain about who can see what.
6 1. **One front door: the feed.** Home is an X-style timeline that IS the git primitives: a post is a tell or an issue; a reply is a comment; a repost or quote is a share or a fork; a like is a signal written to the decision ledger; a crew member's posts are its runs, pulls and looks. The crew reads and writes through the same feed. There is no dev/studio split: one interface, with every developer depth (files, diffs, runs, terminal) one step deeper from any post.
7 2. **The explorer.** Apps, forges and people ranked by real metrics (use, forks, ships, likes, freshness), and trivially filterable to exactly what you want. Every app says "make it yours": one action forks it into your forge.
8 3. **The fork tree is the organization.** My forge is the public upstream; an organization's forge forks it; each person's forge forks their organization's. Every fork chooses how it follows its upstream. The tree is visible and a pleasure to browse; good changes bubble up as offers and flow down as updates.
9 4. **A forge in a link.** I (or my agent, through the MCP) create a forge for a person, a client or an organization: chosen apps (some forked from mine, some still autonomous so they see it cooking), a starter budget, an admin account, one link. First login shows their crew working right now in the feed, and three next steps: make your everyday account, open your apps, tell the crew something. They add their people; each new person gets their own forge that follows the organization's. A client list tracks who was sent what and what happened.
10 5. **Open to every agent.** Any agent or harness can find and use a forge: the MCP with OAuth (Claude app, Grok in a car); a role-aware, token-efficient manifest on every page saying what you can do here as who you are; standards metadata; and on a public app or repo, an outside person or agent can file a report or offer a pull without being taught how.
11 6. **Never lost.** A forge toolbar in every app and preview: where you are (app, environment, which pull this previews), who is working on it, comment on this page or its issue or pull, tell the crew from here, make it yours. Later: in a preview, a tint on what changed and its diff on selection.
12 7. **Steering is one thought.** Tell from anywhere: the feed composer, the toolbar, a phone share sheet, the MCP.
13
14 ## How we build
15 - A deterministic tool with deliberate noise: actions are explicit, previewed and receipted; AI judgment only where we say so.
16 - The same action has the same shape for a person and an agent: a page and an MCP tool, in the same words.
17 - Done means reachable: a person reaches it from the feed in two taps, an agent through the MCP, a test proves it, a look shows it. A function nobody can call is not done.
18 - Far ideas go on the map behind what they depend on, and we trim honestly.
19
20 ## The tests
21 - **Link test:** someone opens a link to their new forge and, within a minute and without a word from me, sees a crew working and knows what to do next.
22 - **Muse test:** an outside agent looking at a public forge app finds out how to report a problem or offer a change, and does it.
23 - **Friend test:** someone I send an app to makes it theirs in one action.
24 - **Tesla test:** any MCP client connects with OAuth and steers.
25 - **Lost test:** from any app or preview you know where you are and can get home, comment, or tell the crew.
26 - **Admin test:** a new owner is guided to a separate everyday account, told why in two sentences, and can still choose otherwise on purpose.
docs/design/areas/README.md +1 −1
@@ -4,4 +4,4 @@ A new component class is named here, in a file for its area (`docs/design/areas/
44 (`` `.my-class` ``) with a line on what it is for. The design check reads every file in this directory as §5 vocabulary,
55 so two pulls documenting different components touch different files and never conflict on `docs/DESIGN.md`.
66
7 Do not edit `docs/DESIGN.md` §5d: it only shrinks. Prefer a component §5 already has.
7 Do not add to §5d (`docs/design/sections/5d-page-local-classes.md`): it only shrinks. Prefer a component §5 already has.
docs/design/areas/backups.md added +3
@@ -0,0 +1,3 @@
1 # Backups
2
3 - `.restore-command` — the one-line restore command on /settings/backups: a `<pre>` that wraps, scrolls with the keyboard (`tabindex="0"`) and takes its height from its text, so a one-liner is not a log pane.
docs/design/areas/boards.md added +2
@@ -0,0 +1,2 @@
1 # Boards
2
docs/design/areas/chart.md added +11
@@ -0,0 +1,11 @@
1 # Chart
2
3 - Series colours — the eight colours the fleet graph's stacked bar chart draws its series in, one class per series index, drawn by `windowSvg()` in `src/web/fleet-graph.ts` on each bar's `<rect>` beside `data-series` (the same index `seriesDot()` keys the legend and table dots by). Each sets `fill` and `color` from its `--series-N` token in `src/design/themes.ts`: the Okabe–Ito palette, told apart with the common colour-vision deficiencies, with the folded "others" series grey.
4 - `.fg-s0` — series 0.
5 - `.fg-s1` — series 1.
6 - `.fg-s2` — series 2.
7 - `.fg-s3` — series 3.
8 - `.fg-s4` — series 4.
9 - `.fg-s5` — series 5.
10 - `.fg-s6` — series 6.
11 - `.fg-s7` — series 7, the folded "others" series (grey).
docs/design/areas/code.md added +3
@@ -0,0 +1,3 @@
1 # Code
2
3 - `.blob-view` — the file view in the code browser (`renderBlob` in `src/web/pages/repo.ts`): on a Markdown file, wraps the Source/Rendered `.seg` toggle at the end of the file's bar, set 8px off the line count with its segments at 12.5px.
docs/design/areas/comments.md added +8
@@ -0,0 +1,8 @@
1 # Comments
2
3 A comment on an issue or pull, and the form that writes one. Both are a `card()`; these classes give it its comment look.
4
5 - `.comment` — one comment as a card: its `.card-head` (byline and time) on the muted ground, the body under it. Written by `commentCard()` in `src/web/comments.ts` and by `reviewRows()` in `src/web/diff-view.ts` (an inline review comment); styled in `src/web/style/components.ts`, and spaced inside a review thread by `.dc-review .comment` in `src/web/style/content.ts`.
6 - `.comment-body` — a comment's rendered markdown, always beside `.prose`, padded inside its card. Written by `commentCard()` in `src/web/comments.ts`, `reviewRows()` in `src/web/diff-view.ts` and `reviewEntry()` in `src/web/studio/change.ts`; styled in `src/web/style/components.ts` (tighter in a timeline event's card).
7 - `.comment-form` — the card that writes a comment: a textarea and its `.form-actions`. Written by `composer()` and `editForm()` in `src/web/pages/thread.ts`, `reviewRows()` in `src/web/diff-view.ts` (a reply in a review thread) and `studioApp()` in `src/web/studio/app.ts` (the "Tell the crew" box); styled in `src/web/style/components.ts`, with its narrow-screen action line and its review-thread margin in `src/web/style/content.ts`.
8 - `.tl-earlier` — the line above a long thread's newest items, `Show N earlier items`, a plain link to `?all=1`. Written by `conversation()` in `src/web/pages/thread.ts`; styled in `src/web/style/components.ts` beside `.tl-item`, indented to the timeline's item column.
docs/design/areas/dialog.md added +10
@@ -0,0 +1,10 @@
1 # Dialog
2
3 A §5 `.dialog` is one component in three parts: a head that names it, a body that holds what it asks or shows, and a
4 foot of buttons aligned to the end. The shell's keyboard-shortcuts dialog (`overlays()` in `src/web/layout.ts`) and the
5 limb page's confirm form (`limbPreviewPage()` in `src/web/pages/limb.ts`) both draw it; the rules live in
6 `src/web/style/components.ts`.
7
8 - `.dialog-head` — the dialog's first row: its `h2` title (which `aria-labelledby` names) takes the width, anything beside it sits at the end.
9 - `.dialog-body` — the dialog's content, padded to the head's inset; add `.stack` when it holds several fields.
10 - `.dialog-foot` — the dialog's actions on one row, aligned to the end, the primary or danger button last.
docs/design/areas/diff.md added +25
@@ -0,0 +1,25 @@
1 # Diff
2
3 The diff a pull and a commit show is one component, drawn by `renderDiff` in `src/web/diff-view.ts` and styled in
4 `src/web/style/content.ts`. It is a `.diff` wrapper holding a summary line and one §5 **diff file** (`.diff-file`) per
5 file.
6
7 - `.diff-summary` — the card above the files: how many files changed and the `+`/`−` totals, in their add and delete colours.
8 - `.diff-head` — a file's `<summary>` row: the fold chevron, path, status badge, line counts and the Viewed checkbox; sticky under the top bar, and wraps when its card is narrower than 420px.
9 - `.diff-path` — the file's path (or `old → new` for a rename) in the head, monospace and truncated with its full path as the title.
10 - `.diff-stat` — a file's `+`/`−` line counts, in the head and in a stub.
11 - `.diff-body` — the file's contents under its head: scrolls sideways for long lines, hidden once the file is marked viewed.
12 - `.diff-table` — the table of hunks and rows inside the body, monospace at 12.5px.
13 - `.diff-note` — a centred muted line in place of rows: a binary file, no content changes, or files past the cap not shown.
14 - `.diff-stub` — a `.diff-note` for a file too large or generated to draw: why, its real counts and a View file button.
15 - `.dn-comment` — a line number in the gutter that links to commenting on that line, when the diff is reviewable.
16 - `.nonl` — the `↵` mark after a line that has no newline at the end of the file.
17 - `.diff` — the wrapper around one whole diff: its summary and every file.
18 - `.dl` — one line of a hunk, a table row; its `data-k` says whether it is context, added or deleted.
19 - `.dn` — a line number in the gutter.
20 - `.dh` — a hunk head, the `@@` row that opens each hunk.
21 - `.add` — an added line, in the add colours.
22 - `.del` — a deleted line, in the delete colours.
23 - `.wd` — a changed word inside an added or deleted line, underlined on a stronger tint.
24 - `.tok-inserted` — an inserted token in highlighted code, in the add colour.
25 - `.tok-deleted` — a deleted token in highlighted code, in the delete colour.
docs/design/areas/feed.md added +5
@@ -0,0 +1,5 @@
1 # Feed
2
3 - `.feed-head` — the head of the home's feed: a §5 `.bar` above the timeline holding the "What you asked for" link, pushed to the end by a spacer. Drawn by `studioHome` in `src/web/studio/home.ts`, styled in `src/web/studio/feed_style.ts`. Under 900px it is hidden, since that link is a tab on a phone and the first post should come next; a bare `.bar` cannot carry this, as it has no reason to vanish on a narrow screen.
4 - `.look[data-slot="feed"]` — a look post's thumbnail, drawn by `feedCard` in `src/web/studio/feed.ts`: the §5 `.look` frame fixed at 160×100 (the img carries the same width and height, so nothing shifts), cropped from the top like the other thumbs. A bare `.look` is fluid and would resize the post.
5 - `.feed` — the home's timeline list: a one-column grid with no gap that holds the feed's cards, each focusable with a visible outline and removed from layout while `hidden`. Drawn by `drawRegion` in `src/web/studio/feed.ts` (the `#live-feed` section), styled in `src/web/studio/feed_style.ts`.
docs/design/areas/forms.md added +6
@@ -0,0 +1,6 @@
1 # Form layout
2
3 A form's fields and its buttons sit in two rows, one for what you fill in and one for what you do with it.
4
5 - `.field-row` — a row of `.field`s side by side that wraps on a narrow screen, each at least 160px wide and aligned to the bottom so a labelled input and the button beside it share a baseline. Styled in `style/components.ts`; written by `createForm` in `pages/branches.ts` (the new-branch form), the graph filter in `pages/fleet-graph.ts`, the freeze form in `pages/frozen.ts` and the new-pull form in `pages/pulls.ts`.
6 - `.form-actions` — the row of a form's buttons under its fields: 16px above, 8px apart, wrapping. Styled in `style/components.ts`, and in `style/content.ts` for a thread's close reason and "close into" input and for `.comment-form` on a narrow screen; written by nearly every form in `src/web/pages/` (`account.ts`, `settings.ts`, `crew.ts`, `edit.ts`, `issues.ts`, `pulls.ts`, `oauth.ts`, `teams.ts`, `chain.ts`, `everyday.ts`) and by the review comment form in `diff-view.ts`; `client.ts` finds its `.muted` note to report a save.
docs/design/areas/front.md added +7
@@ -0,0 +1,7 @@
1 # Front
2
3 The studio's front page (`studioDoor()` in `src/web/studio/home.ts`) shows an admin, under the shelf of public apps, the
4 controls that pick what the shelf shows; strangers never see them. The rules live in `src/web/style/content.ts`.
5
6 - `.front-admin` — the admin's controls under the front page (`studioDoor()` draws it around `frontControls()`), as wide as the shelf above it and centred with it.
7 - `.front-pick` — one row of choices in those controls (drawn by `frontControls()`): the entry's name, then its pin, unpin, hide or show buttons at the end, its inline forms without the end margin `form.inline` would give them.
docs/design/areas/highlight.md added +23
@@ -0,0 +1,23 @@
1 # Code, coloured
2
3 The highlighter's token colours (§6b): one component, written as `tok-${kind}` by `tokenClasses` in `src/web/highlight-html.ts` and coloured by the `--tok-*` tokens in `src/design/themes.ts`. A token span carries its colour class, plus a finer kind class when it has one; the file browser, the diff viewer and the editor all draw the same spans.
4
5 - `.tok-attribute` — an attribute name, as in markup.
6 - `.tok-comment` — a comment.
7 - `.tok-constant` — a constant: `true`, `null`, a named constant.
8 - `.tok-decorator` — a decorator or annotation.
9 - `.tok-emphasis` — emphasised prose, as in markdown.
10 - `.tok-function` — a function name.
11 - `.tok-heading` — a heading, as in markdown.
12 - `.tok-keyword` — a language keyword.
13 - `.tok-link` — a link, as in markdown.
14 - `.tok-meta` — meta syntax: a preprocessor line, a front-matter fence.
15 - `.tok-number` — a numeric literal.
16 - `.tok-operator` — an operator; muted, it is a line's scaffolding.
17 - `.tok-property` — a property or key name.
18 - `.tok-punctuation` — punctuation; muted, it is a line's scaffolding.
19 - `.tok-regex` — a regular-expression literal.
20 - `.tok-string` — a string literal.
21 - `.tok-tag` — a tag name, as in markup.
22 - `.tok-type` — a type name.
23 - `.tok-variable` — a variable or parameter name.
docs/design/areas/icons.md added +15
@@ -0,0 +1,15 @@
1 # Icons
2
3 One icon set, drawn from one sprite: `icon(name)` in `src/web/icons.ts` writes a `<svg>` slot that `<use>`s a
4 `<symbol>`, and `iconSprite()` defines each drawing a page used once, at the end of `<body>`. Fragments expand the
5 references in place with `inlineIcons()`. Every rule is in `src/web/style/components.ts`.
6
7 - `.ico` — every icon slot: written by `icon()` (`src/web/icons.ts`, as `ico ico-<name>`) and by `themeGlyph`, the
8 theme menu's half-filled circle. Styled in `src/web/style/components.ts` (a 16px inline-flex box that never shrinks); the
9 components that hold one (`.badge`, `.count`, `.menu-item`, `.toast`, `.empty`, and `src/web/style/content.ts`'s
10 `.where-place`, `.live-note`, `.origin-chip`) tune its size and colour.
11 - `.ico-loader` — the spinning loader, written by `icon("loader")` (`src/web/icons.ts`; used on the pull page,
12 `src/web/pages/pull.ts`, and the studio's working word, `src/web/studio/words.ts`). Styled in
13 `src/web/style/components.ts`: it spins, and inside a `.btn` it spins only while the button is `aria-busy="true"`.
14 - `.sprite` — the zero-sized `<svg>` of `<symbol>`s, written by `iconSprite()` (`src/web/icons.ts`, placed by
15 `layout.ts`). Styled in `src/web/style/components.ts`: absolutely positioned at 0×0 so it can never move a layout.
docs/design/areas/layout.md added +13
@@ -0,0 +1,13 @@
1 # Layout utilities
2
3 The spacing and layout utilities every page leans on: one component, styled in `style/base.ts`'s `utilities` layer, so a page spaces and sizes its blocks without a class of its own.
4
5 - `.mt` — a 12px top margin between a block and the one above it; `pages/commits.ts` (`<div class="mt">`), `pages/issues.ts` and most pages write it. Styled in `style/base.ts`.
6 - `.mb` — a 12px bottom margin, the same step downward; `pages/commits.ts` (`<div class="bar mt mb">`) and `pages/settings.ts` write it. Styled in `style/base.ts`.
7 - `.stack` — a flex column with a 12px gap, for a run of cards or form rows; `pages/looks.ts`, `pages/returns.ts` and `pages/everyday.ts` write it. Styled in `style/base.ts`; `style/components.ts` drops the card-to-card margin inside it and `style/content.ts` adjusts it under `#needs-you`.
8 - `.stack-tight` — beside `.stack`, narrows its gap to 4px; `pages/looks.ts` and `pages/first-admin.ts` write it. Styled in `style/base.ts`.
9 - `.spacer` — an empty flex child that takes the free space and pushes what follows to the end of a row; `pages/commits.ts` and `pages/edit.ts` write it. Styled in `style/base.ts` (also inside `.topbar`), `style/components.ts` (`.pager`) and `style/content.ts` (`.app-strip`, `.comment-form`).
10 - `.grow` — a flex child that takes the free space and may shrink below its content (`min-width: 0`), so its text can truncate; `pages/edit.ts`, `pages/settings.ts` and `pages/board.ts` write it. Styled in `style/base.ts`; `style/components.ts` ellipsizes it inside `.menu-item` and `.palette-item`.
11 - `.narrow` — a 400px column centred a little below the top, for a single short form or notice; `pages/oauth.ts` writes it. Styled in `style/base.ts`.
12 - `.narrow-wide` — a 760px reading column for a page of one form or one text; `pages/edit.ts`, `pages/issues.ts` and `pages/forges.ts` write it. Styled in `style/base.ts`.
13 - `.page-head-sub` — the one line under a page head's title: `flex-basis: 100%` and a −4px top margin, so it breaks onto its own full-width line. A layout hook, not a look: it rides with `muted small` (or `bar muted small` for a row of facts); `pageHead({ sub })` in `chrome.ts` and the run, tell, change and browse heads write it. Styled in `style/content.ts`; a `.muted.small` child of a page head without it (the system page's Processes sort row) stays beside its heading.
docs/design/areas/lines.md added +9
@@ -0,0 +1,9 @@
1 # Lines
2
3 The line-number gutter of a file's source view: one cell per line, holding a link to that line's anchor.
4
5 - `.ln` — the number cell of a row in `.code`, written by `blobBody()` in `src/web/pages/repo.ts` as
6 `<td class="ln"><a href="#L…">…</a></td>`, styled by `.code .ln` in `src/web/style/content.ts`: right-aligned
7 tabular numbers in `--faint` behind a hairline border, unselectable so a copy takes only the code, and `--attn` on a
8 `:target` or `[data-hl]` row. `src/web/client.ts` reads `.code .ln a` for shift-click range selection (`#L3-L9`).
9 The editor's own gutter is `.editor-gutter`, already named in §5's file editor row.
docs/design/areas/map.md added +26
@@ -0,0 +1,26 @@
1 # Plan map
2
3 The map of what waits for what (`/:owner/:name/map`): one SVG of the repository's open issues as cards, laid out by
4 dependency, with the edges between them and the pillars beside it. `mapPage` in `src/web/pages/map.ts` draws the page and `drawMap`
5 the SVG; `mapCss` there holds every rule below. A card's state (ready, working, blocked, waiting, parked, held, deferred, done)
6 is `data-state` on `.map-node`, not a class.
7
8 - `.map-wrap` — the page's two-column grid: the canvas, then the 272px side column; one column under 860px.
9 - `.map-main` — the canvas column; `min-width: 0` so a wide map never pushes the side column off the page.
10 - `.map-canvas` — the bordered frame the SVG sits in; `is-view`, `is-drag` and `is-cut` say whether it pans, is being dragged, or is cut off with a fade.
11 - `.map-svg` — the map's SVG itself, full width; its text uses the page font and never takes the pointer.
12 - `.map-rule` — the labelled line across the map above the issues that are "not linked" to any other.
13 - `.map-node` — one issue's card, a link to the issue; `data-state` sets its colours.
14 - `.map-card` — the card's rectangle, filled and stroked by the node's state.
15 - `.map-breath` — the soft accent ring around a card being worked on.
16 - `.map-title` — the issue's title on the card.
17 - `.map-meta` — the issue's number, in tabular figures.
18 - `.map-who` — the assignee's mark: a circle with an initial and a name.
19 - `.map-who-i` — the assignee's initial inside the circle.
20 - `.map-who-n` — the assignee's name beside it.
21 - `.map-word` — the state's word at the card's right edge.
22 - `.map-dot` — the coloured dot before the state's word.
23 - `.map-edge` — one dependency edge between two cards.
24 - `.map-edge-crit` — an edge on the critical path, in the accent.
25 - `.map-edge-done` — an edge with a closed issue at either end, faded.
26 - `.map-ask` — a pillar row's lead-time figures in the side column, inline, with the hover title saying what they measure.
docs/design/areas/menu.md added +11
@@ -0,0 +1,11 @@
1 # Menu
2
3 The popup list a §5 **menu** opens. `menu()` in `src/web/ui.ts` draws it; the refs picker (`src/web/pages/refs.ts`)
4 writes the same parts by hand, and `src/web/client.ts` finds the panel to focus its first item when the menu opens and
5 to move between items with the arrow keys.
6
7 - `.menu-panel` — the raised box under the `<summary>` that holds the `.menu-item`s: absolutely placed, scrolls past
8 `min(70vh, 480px)`, end-aligned unless the menu says `data-align="start"`.
9 - `.menu-title` — a small uppercase heading over a group of items (`menu({ title })`, "Branches" and "Tags" in the refs
10 picker); text only, never focused.
11 - `.menu-sep` — an `<hr>` between groups (`{ separator: true }` among `menu()`'s items): one border line.
docs/design/areas/palette.md added +11
@@ -0,0 +1,11 @@
1 # Command palette
2
3 The command palette is the keyboard-first fuzzy-find overlay (`⌘K` / `Ctrl K`, or the topbar's search button): the §5 `.palette` dialog, with its input, list and foot drawn by `layout.ts` and its results drawn by `openPalette()` in `src/web/client.ts`. Without script it degrades to `/search`. The file finder (`openFinder()`, `.dialog.palette.finder`) draws its rows and its empty note with the same classes. The rules live in `style/components.ts`.
4
5 - `.palette-group` — one group of results under a heading (Recent, Go to, a category); consecutive groups sit 4px apart.
6 - `.palette-heading` — a group's small, uppercase, faint heading; the group's `aria-labelledby` points at it.
7 - `.palette-item` — one result row: an icon, the title truncated on one line, and its category pushed to the end. The row the keyboard or pointer has selected (`aria-selected="true"`) carries the one highlight; the finder keeps plain hover.
8 - `.palette-empty` — the note centred in the list when nothing matches the query.
9 - `.palette-input` — the search field across the top of the dialog: full width, borderless but for a rule beneath it, 48px tall, with no focus ring of its own (the system outline under forced colours).
10 - `.palette-list` — the scrolling results area under the input: a fixed height (not a ceiling) so the dialog does not jump as rows come and go.
11 - `.palette-foot` — the faint one-line strip of key hints under the list, set off by a rule above it.
docs/design/areas/prose.md added +8
@@ -0,0 +1,8 @@
1 # Prose (markdown)
2
3 Markdown table cell alignment: a column whose delimiter row reads `:-:` or `--:` puts the matching class on each of its
4 `th` and `td` cells, written by `cells` in `src/web/markdown.ts` as `ta-${align}` and styled under `.prose` in
5 `src/web/style/content.ts`. A left-aligned or unmarked column carries no class.
6
7 - `.ta-c` — a centred column (`:-:`); text-align center.
8 - `.ta-r` — a right-aligned column (`--:`); text-align right.
docs/design/areas/repo-head.md added +5
@@ -0,0 +1,5 @@
1 # Repository head
2
3 The head of a repository page names the repository and what you can do with it. `scopeHeader()` in `src/web/chrome.ts` draws it; the rules live in `src/web/style/content.ts`.
4
5 - `.repo-title` — the head's `owner / name` line: the owner muted, the slash faint, the name in full weight. It is an `h1` on a repository's own pages and a `div` where the page has its own `h1`.
docs/design/areas/search.md added +3
@@ -0,0 +1,3 @@
1 # Search box
2
3 - `.search` — the search field of a filter or search form: an `.input` that grows to fill its row between 180px and 320px wide. Written by `searchPage` in `src/web/pages/search.ts` (the `/search` form), and by the filter forms in `src/web/pages/browse.ts`, `src/web/pages/org.ts`, `src/web/pages/origins.ts` and `src/web/studio/explore.ts`. Styled in `src/web/style/content.ts` as `.filters .search` and `.bar .search`.
docs/design/areas/settings.md +18
@@ -1,3 +1,21 @@
11 # Settings page
22
3 ## Settings rows
4
5 A list whose rows are settings — each row a name, its current value, and a control to change it (limits, capacity,
6 flags, telemetry, cloud, people, crew roles, subscription headroom and budget) — is §5's list row in a list that lets
7 the text wrap and gives the control a place that is always visible. Use `.row-actions` only for secondary actions
8 (delete, wake, pin, revoke).
9
10 - `.setting-list` — the `<ul class="list setting-list">` around such rows: title and meta wrap instead of ellipsizing,
11 and a row's trail takes its own line under 640px. Written by the settings pages, e.g. `appDomainsView()` and
12 `appEgressView()` in `src/web/pages/settings.ts`, `limitsPage()` in `src/web/pages/admin-limits.ts`, `capacityPage()` in
13 `src/web/pages/capacity.ts`, `flagsPage()` in `src/web/pages/flags.ts`, and by lists of the same shape in
14 `src/web/pages/repo.ts`, `src/web/pages/pull.ts`, `src/web/pages/map.ts` and `src/web/studio/make_it_yours.ts`.
15 Styled in `src/web/style/components.ts`.
16 - `.row-fields` — the form in a settings row's trail (input, Save, Default): always visible, never hover-gated,
17 wrapping under the text before it would clip. Written in the trail of `row()` by `src/web/pages/flags.ts`,
18 `src/web/pages/telemetry.ts`, `src/web/pages/cloud.ts`, `src/web/pages/people.ts`, `src/web/pages/admin-limits.ts`,
19 `src/web/pages/capacity.ts`, `src/web/pages/subscriptions.ts` and `src/web/studio/crew.ts`. Styled in
20 `src/web/style/components.ts`.
321 - `.record-value` — a DNS record's value on an app's domain row (`.setting-list` row meta): monospace, wraps instead of ellipsizing, and `user-select: all` so one click selects the whole value to copy.
docs/design/areas/shell.md added +8
@@ -0,0 +1,8 @@
1 # Page shell
2
3 The chrome every page sits in: the sticky top bar, the main column and the footer, drawn by `page()` in `src/web/layout.ts` (the top bar by `topbar()`, its search by `searchBar()`). Rules live in `src/web/style/base.ts`, the search field's in `src/web/style/components.ts`.
4
5 - `.topbar-tools` — the top bar's right-hand group (search, Asks, the new and user menus): one row that may shrink but never wraps, its bare `a.small` links 44px tall.
6 - `.topbar-search` — the top bar's search form: an icon, a borderless input and its `/` key hint in one bordered pill, the border taking the accent on focus. Shown from 720px; below that the icon button carries search.
7 - `.hide-lg` — shown under 720px, hidden from 720px: the narrow-screen stand-in for something `.hide-sm` shows on wide screens (the search icon button beside `.topbar-search`).
8 - `.shell-wide` — on `<main class="shell">` when a page passes `wide`: from 1200px the column drops its reading width and keeps a 24px gutter, for the one layout that gains from every pixel (a tree beside a file).
docs/design/areas/table.md added +5
@@ -0,0 +1,5 @@
1 # Scrolling table
2
3 A §5 `.table` too wide for a narrow screen sits inside a horizontal scroller, so the page itself never scrolls sideways and only the table's figures move.
4
5 - `.table-scroll` — the wrapper `<div>` around a wide `.table`: `overflow-x: auto` with a thin scrollbar, styled in `src/web/style/components.ts`. Pair it with `.table[data-sticky-lead]` to keep each row's name in view while the figures scroll. Written by `src/web/pages/account.ts`, `src/web/pages/audit.ts`, `src/web/pages/boards-held.ts`, `src/web/pages/crew.ts`, `src/web/pages/flow-panel.ts`, `src/web/pages/passkeys.ts`, `src/web/pages/proposal-tokens.ts`, `src/web/pages/settings.ts`, `src/web/pages/spend.ts`, `src/web/pages/subscriptions.ts`, `src/web/pages/system.ts`, `fleetGraphSection`'s figures table in `src/web/fleet-graph.ts`, and `vitalsTable` in `src/web/studio/vitals.ts`.
docs/design/areas/tell.md added +15
@@ -0,0 +1,15 @@
1 # Tell here
2
3 Telling the crew from any page (tell from anywhere) opens in place: `tellInPlace()` in `src/web/client.ts` fetches the
4 server's own composer (the thread's `.comment-form` saying a tell) and lays it over the bottom of the page, so nothing
5 shifts and Enter sends it with the page's path as `from`. Any failure falls back to the plain link.
6
7 - `.tell-here` — the fixed box holding that composer: pinned to the bottom of the viewport, at most 620px wide and
8 centred, above the page; the `.comment-form` inside drops its margin and takes `--shadow-2` so it reads as raised.
9
10 ## Client home: `client-app-finished`
11
12 A muted line on a client's app row, `Finished <time>: <title>`, for the app's
13 newest merged pull. It sits with `client-app-about`, `client-app-agents` and
14 `client-app-doing`; it uses `muted` and adds no colour or size. The
15 terminal says the same words.
docs/design/areas/text.md added +29
@@ -0,0 +1,29 @@
1 # Text utilities
2
3 One component: the small text utilities every page puts on a span, a paragraph or a cell to say how its text reads,
4 without a page-local class of its own. Each is styled in `style/base.ts`; they compose (`muted small` is the usual
5 quiet line under a card), and a page reaches for them instead of setting a colour or a size by hand.
6
7 - `.muted` — low-emphasis text in `--muted-fg`: notes, timestamps, the summary of a tucked disclosure. Written by
8 `ui.ts` (`envFacts()`, `terminalLine()`, `disclosure()` with `small`) and most pages
9 (`pages/commits.ts`, `pages/settings.ts`, `pages/looks.ts`, …); styled in `style/base.ts`, with contextual rules in
10 `style/content.ts`.
11 - `.small` — 13px text, the step under body. Written by `ui.ts` beside `.muted`, `layout.ts` (the topbar's Asks
12 link) and pages such as `pages/edit.ts` and `pages/boards-view.ts`; styled in `style/base.ts`, with contextual rules
13 in `style/content.ts`.
14 - `.num` — tabular figures so counts line up in a column. Written by `ui.ts` (`stat()`'s value, `counts()`)
15 and pages such as `pages/spend.ts`, `pages/repo.ts` and `pages/crew.ts`; styled in `style/base.ts`, right-aligned
16 inside `.table` by `style/components.ts`.
17 - `.truncate` — one line that ends in an ellipsis rather than wrapping. Written by `ui.ts` (`envFacts()`'s URL) and
18 pages such as `pages/apps.ts`, `pages/refs.ts` and `pages/explorer.ts`; styled in `style/base.ts`, capped at 34ch
19 inside `.table` by `style/content.ts`.
20 - `.nowrap` — keeps a short run (a token count, a figure with its unit) on one line without clipping it. Written by
21 `ui.ts` (`tokenCount()`, with `.num`); styled in `style/base.ts`.
22 - `.break` — lets a long unbroken string (a URL, a hash, a path) wrap anywhere rather than overflow its box. Written by
23 `ui.ts`, `scope.ts` and pages such as `pages/backups.ts`, `pages/origins.ts` and `studio/feed.ts`; styled in
24 `style/base.ts`.
25 - `.sr-only` — text for a screen reader only: a table's caption, a select's label, a fieldset's legend. Written by
26 pages such as `pages/audit.ts`, `pages/pull.ts` and `pages/thread.ts`, and by `studio/app.ts` and
27 `studio/review_act.ts`; styled in `style/base.ts`.
28 - `.mark` — the forge's square glyph beside the wordmark and in the footer. Written by `layout.ts` (the topbar's
29 `.wordmark` and the `.foot`) and `pages/board.ts`; styled in `style/base.ts` only inside `.wordmark` and `.foot`.
docs/design/areas/timeline.md added +6
@@ -0,0 +1,6 @@
1 # Timeline
2
3 The event timeline on an issue or pull thread: a vertical rail of `.tl-item` rows, each with a dot, comments as cards and events as one dim line.
4
5 - `.timeline` — the column that holds the rows and draws the rail behind their dots. Written by `conversation()` in `src/web/pages/thread.ts`, `timelineOf()` in `src/web/pages/browse.ts` and `appEgressView()` in `src/web/pages/settings.ts`; styled in `src/web/style/components.ts`.
6 - `.tl-dot` — the round glyph on the rail at the head of each row, tinted by the row's `data-tone`. Written by `tlEvent()` and `tlComment()` in `src/web/ui.ts` and `threadComment()` in `src/web/pages/thread.ts`; styled in `src/web/style/components.ts`.
docs/design/areas/toast.md added +5
@@ -0,0 +1,5 @@
1 # Toast
2
3 The flash a write leaves after its redirect, and the same one-line banner a page shows for a failure it found itself: one `.toast` per page, toned by `data-tone=success|danger|attn` (§5's toast / flash row), an icon, then the message.
4
5 - `.toast-body` — the message beside the toast's icon: it takes the rest of the row (`flex: 1; min-width: 0`) so a long message wraps instead of pushing the icon off. Written by `flashToast` in `src/web/layout.ts` (the cookie-driven flash), and by `src/web/pages/repo.ts` (a fetch error), `src/web/pages/browse.ts` (a failed mirror) and `src/web/pages/origins.ts` (origin connected or failed); styled in `src/web/style/components.ts` under `/* ---- toast / flash ---- */`.
docs/design/sections/1-principles.md added +19
@@ -0,0 +1,19 @@
1 ## 1. Principles
2
3 1. **Border-first, not shadow-first.** Elevation in a light theme is a hairline
4 plus a 5%-opacity shadow. In a dark theme it is a lighter surface and a
5 stronger border — dark themes have no shadows. If something looks flat in
6 the dark, its surface is wrong, not its shadow.
7 2. **One accent per page.** `--accent` means _interaction_: focus rings, links
8 on hover, the active choice. It is never a status color. If two things on a
9 page are accent-colored and only one is the action, one of them is wrong.
10 3. **Hierarchy from weight and color, not size.** 14px does almost everything.
11 A title is 20px because it is a title, not to be noticed.
12 4. **Everything works with JavaScript off.** Script may make a thing instant.
13 It may never make a thing possible. A control that does nothing without JS
14 is worse than no control.
15 5. **Anything that navigates is `<a>`; anything that mutates is a `<button>`
16 in a `<form method=post>`.** There is no third case, and the CSP forbids
17 inventing one.
18 6. **Never say what you don't know.** A missing thing and a thing you may not
19 see are the same 404, with the same words.
docs/design/sections/2-tokens.md added +32
@@ -0,0 +1,32 @@
1 ## 2. Tokens
2
3 Palettes live in `src/design/themes.ts`; the stylesheet only ever reads
4 variables, so a theme is data. Six ship today. What each role _means_:
5
6 | token | role |
7 | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
8 | `--bg` | the page. Nothing else uses it. |
9 | `--card` | any raised surface: card, menu, dialog, input, button. |
10 | `--muted` | a recessed surface: row hover, table head, code block, pill. |
11 | `--fg` | body text, and the **active tab underline**. |
12 | `--muted-fg` | all metadata. Never a hardcoded gray — muted is a desaturated hue of the surface, so it warms and cools with the theme. |
13 | `--faint` | decoration only: separators between crumbs, gutter numbers, icons inside rows. Never load-bearing text. |
14 | `--border` | every hairline. |
15 | `--border-strong` | a raised edge, and hover on a control. |
16 | `--primary` / `--primary-fg` | the one filled button per page, and the live-activity pill. |
17 | `--accent` / `--accent-fg` | interaction: focus ring, link hover, selection, the review-comment rail. |
18 | `--success` | open issue, mergeable pull, additions. |
19 | `--danger` | closed, destructive, deletions. |
20 | `--merged` | a merged pull. Purple, and only that. |
21 | `--attn` | draft, pending, a highlighted line. |
22 | `--add-*` / `--del-*` / `--wd-*` | the diff. Tints stay ≤14% so syntax color survives on top. |
23 | `--tok-*` | syntax, in two layers: eleven colour classes every consumer knows, plus finer kinds the web paints over them (§6c). |
24 | `--shadow-1` / `--shadow-2` | a hint and an overlay. Near-transparent in dark palettes, so one rule serves every theme. |
25 | `--series-0…7` / `--qr-ground` | the same in every theme (`FIXED_TOKENS`): chart series (Okabe–Ito, colour-vision safe) and a QR code's white ground. |
26
27 **Status surfaces are tinted, never saturated**: `color-mix(in srgb, var(--x)
28 12%, transparent)` for the fill, the pure token for the text, a 34% mix for the
29 border.
30
31 **Contrast targets**: body ≥7:1 where it's cheap, `--muted-fg` ≥4.5:1 on
32 `--bg`, borders ≥1.5:1 against their surface, focus ring ≥3:1.
docs/design/sections/3-typography.md added +38
@@ -0,0 +1,38 @@
1 ## 3. Typography
2
3 ```
4 --font: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif
5 --mono: ui-monospace, "SF Mono", SFMono-Regular, "Cascadia Code", Menlo, Consolas, monospace
6 ```
7
8 | role | size | weight | tracking | line-height |
9 | -------------------------------- | -------- | ------ | -------- | ----------- |
10 | page title `h1` | 20px | 620 | −0.02em | 1.25 |
11 | section `h2` | 16px | 600 | −0.01em | 1.3 |
12 | sub `h3` | 14px | 600 | 0 | 1.4 |
13 | **body, rows, chrome** | **14px** | 400 | 0 | 1.5 |
14 | **prose (`.prose` only)** | **15px** | 400 | 0 | 1.65 |
15 | metadata | 13px | 400 | 0 | 1.45 |
16 | mono (code, sha, diff) | 12.5px | 400 | 0 | 1.55 |
17 | micro (`kbd`, `.pill`, `.badge`) | 11.5px | 500 | 0 | 1 |
18
19 Rules:
20
21 - **Headings tighten as they grow.** Body text is never tracked.
22 - `font-variant-numeric: tabular-nums` on every count, date, line number,
23 diff stat and file size — a count going 9 → 10 must not shift its neighbours.
24 That is `.num`, `.pill`, `.badge`, `.sha`, `.dn`, `.table td`.
25 - `text-wrap: balance` on headings and empty-state titles; `pretty` on prose
26 and descriptions.
27 - **Truncation is honest**: one line, ellipsis, and a `title` with the whole
28 string. Never a fade-out mask — masks lie about whether there is more.
29 - **A token count is shown where a byte size is shown, never as a badge on
30 its own.** Tokens are a unit, like KB: they sit beside a file's size, a
31 directory's total, a run's cost or a window's dollars and percentage, so
32 the context intuition grows next to the storage and money ones. One
33 formatter (`kernel/tokens-format.ts`, rendered by `tokenCount()` /
34 `sizeWithTokens()` in `web/ui.ts`) writes them all: `850 tok`, `1.2k tok`,
35 `48k tok`, `1.1M tok`. A count the provider reported is bare; an estimate
36 (bytes ÷ a stated bytes-per-token ratio for prose, code or data) carries a
37 `~`, and every count's `title` says which tokenizer and whether it is an
38 estimate. A binary file has no token count — no number beats a wrong one.
docs/design/sections/4-space-radius-motion.md added +20
@@ -0,0 +1,20 @@
1 ## 4. Space, radius, motion
2
3 - **4px grid.** Every padding, margin and gap is divisible by 4; 6px is allowed
4 _inside_ a control. Scale: `2 4 6 8 12 16 24 32 48 64`.
5 - **Three radii, held to.** `--radius-sm: 6px` on controls (button, input,
6 chip, kbd), `--radius: 8px` on surfaces (card, code block), `--radius-lg:
7 12px` on overlays (menu, dialog, palette), `999px` on pills and avatars.
8 A nested element uses the outer radius minus the border width, never the same.
9 - **Dividers**: `border-top` on `:not(:first-child)`, never `border-bottom` on
10 all — that is where the double line at the end of a list comes from.
11 - **Density**: dense rows (files, commits, issues) 40px; anything touchable is
12 ≥44px under `@media (pointer: coarse)` — via padding, so text stays centered.
13 - **Motion**: 100–200ms, `cubic-bezier(.2,0,0,1)`, enter only. Only `color`,
14 `background-color`, `border-color`, `opacity` and `transform` are ever
15 animated. Never `height`, never `box-shadow` on scroll. Everything is inside
16 the `prefers-reduced-motion` kill switch.
17 - **Focus** is the accent at 2px with 2px offset, identical on every control,
18 and inset (−2px) on full-bleed rows so nothing reflows. Never `outline: none`.
19 - **Sticky, and only these**: the topbar, a diff file's header, the file path
20 header. Everything anchorable carries `scroll-margin-top`.
docs/design/sections/5-components.md added +111
@@ -0,0 +1,111 @@
1 ## 5. The component vocabulary
2
3 Implemented in `src/web/ui.ts` (pure) and `src/web/chrome.ts` (may read the
4 database). One class, `data-*` for variants. "Terminal" is the shape the same
5 component takes in a TUI — a note for the terminal thread to fill in, not a
6 specification.
7
8 | component | web class | variants (`data-*`) | states | terminal equivalent |
9 | --------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------ | ------ |
10 | **button** `btn()` | `.btn` | `variant=primary\|secondary\|outline\|ghost\|danger\|link`, `size=sm\|lg` | hover, active, `:focus-visible`, `[disabled]`, `[aria-busy]` | a labelled key or a highlighted action cell |
11 | **icon button** `iconBtn()` | `.btn.btn-icon` | same | `aria-label` required | a single glyph with a status-bar hint |
12 | **input / textarea / select** `field()` | `.input` | `size=sm`, `[aria-invalid]` | focus, `:user-invalid`, `[readonly]` | a line editor with an inline error row |
13 | **form field** `field()` | `.field` (`label`, `.hint`, `.error`) | `data-invalid` | — | label line, value line, hint line |
14 | **checkbox** | `.check` | — | native, `accent-color` themed | `[x]` / `[ ]` |
15 | **badge** `badge()` / `stateBadge()` | `.badge` | `variant=secondary\|outline\|success\|danger\|merged\|attn`; `data-state=open\|closed`, `data-pr=merged` | — | a bracketed word in the state color |
16 | **stat** `stat()` | `.stat` (`.stat-label`, `.stat-value`, `.stat-note`, `.stat-spark`; grid: `.stats`) | `data-tone=attn` | hover (`--border-strong`, only when `href` makes it a link, named by `aria` when given); fixed heights, so a changing value shifts no neighbour; value is `.num` with its full form in `title`; note clamps to two lines, its whole text in `noteTitle`; the sparkline carries its own `role=img` and `aria-label`, or is decorative; `.stats` auto-fits columns of at least 160px | a number under its label, a note under that, an optional sparkline top right |
17 | **label chip** `labelChip()` | `.label` | color via `--label` (see §7) | — | a colored `‹name›` |
18 | **author** `userLink()` / `userTag()` | `.byline` (`.byline-name`) | — | `userTag` inside anything already a link — see below | `@name` in the avatar hue |
19 | **name mark** `nameMark()` | `.name-mark[data-mark]` | `owner` / `crew`, from the account | never typed: escaped names cannot make it | beside the name, after the link |
20 | **avatar** `avatar()` | `.avatar` | `size=md\|lg`, `data-h=0..11` | initials, deterministic hue | two initial letters in the same hue |
21 | **count** | `.count` | — | glyph plus a tabular number | `⌸ 3` |
22 | **stat pill** `pill()` | `.pill` | `data-tone=accent\|danger` | tabular | a parenthesised count |
23 | **status dot** `dot()` | `.dot` | `data-tone=success\|danger\|attn\|merged`; `data-series=0…7` (`seriesDot()`) is a chart series' swatch, in its `--series-N` colour | — | `●` in the tone |
24 | **sha** `sha()` | `.sha` | — | first 7 chars | the same 7 chars, dim |
25 | **progress bar** `progress()` (`pages/milestones.ts`) | `progress` (element rule in `style/components.ts`; every `<progress>` on the site) | — | native `<progress max value>`, 4px, full width, an `aria-label` saying what is done; no width rule per value | `▓▓▓░░ 3 of 5` |
26 | **meter** `meter()` | `meter` | `data-tone=attn` when the share is a limit reached | native `<meter min=0 max=100>`, a whole percentage, an `aria-label` saying what it is a share of; no width rule per value, so no inline style | `▓▓▓░░ 62%` |
27 | **kbd** `kbd()` | `kbd` | — | — | a reverse-video key name |
28 | **card** `card()` / `listCard()` | `.card` (`.card-head`, `.card-links`, `.card-body`, `.card-foot`) | `data-tone=success\|danger\|merged\|attn` | — | a box with a title bar |
29 | **list row** `row()` | `.row` (`.row-lead`, `.row-main`, `.row-title`, `.row-meta`, `.row-trail`, `.row-actions`, `.row-children`; settings: `.setting-list`, `.row-fields`) | `data-state=open\|closed\|merged\|draft` — colours the **lead glyph**, so a list filtered by state carries no badge repeating the filter | hover, focus, `data-nav`; `fold` makes the row a `<details>`'s `<summary>`, its lead the caret turned when open (/map's lanes); `children` nests the rows under a row in a `<ul class="row-children">` inside its `<li>` — a tree (/family), a step in under a rule, real list nesting for assistive tech; `aria-current="true"` on the `<li>` (`current`) tints the row; `.row-meta` is one honest line: nowrap, ellipsis, `title` — except in a `.setting-list`, where it wraps | one line: glyph, title, right-aligned meta |
30 | **edit row** | `.edit-row` | — | one line on a desktop, stacked below 720px | a form line |
31 | **colour field** | `.color-field` | — | native `<input type=color>` plus its hex; works with no script | a hex entry |
32 | **table** | `.table` | `data-dense`; `.num` cells right-aligned | — | aligned columns |
33 | **tabs** `tabs()` | `.tabs > a` | — | `aria-current="page"` + 2px `--fg` underline | a header row with the active item underlined |
34 | **segmented control** `seg()` | `.seg > a` | — | `aria-current`, or `:has(:checked)` for radios | `‹ Open | Closed | All ›` |
35 | **menu** `menu()` | `.menu` (`<details>`) | `data-align=start\|end` | open/closed | a popup list |
36 | **disclosure** `disclosure()` | `.disclosure` (`<details>`, a quiet `›` summary) | `small` summary, `label` (aria-label), `extra` classes | open/closed; the chevron turns, the summary is at least 44px tall | a folded section |
37 | **dialog** | `.dialog` | `data-side=bottom` (sheet) | JS `showModal()`; every dialog has a real page behind it | a modal box |
38 | **tooltip** | `[data-tip]` | `data-tip-side=bottom` | hover/focus; hidden on coarse pointers | a status-bar hint |
39 | **toast / flash** `Flash` | `.toast` | `data-tone=success\|danger\|attn` | one per page load, cookie-driven | a one-line banner |
40 | **command palette** | `.palette` | — | JS only; degrades to `/search` | a fuzzy-find overlay |
41 | **breadcrumb** `crumbs()` | `.crumbs` | `.mono` | `aria-current` on the last | `a / b / c` |
42 | **pagination** `pager()` | `.pager` | — | cursor links, absent ends | `‹ Newer Page 2 Older ›` |
43 | **timeline item** `tlEvent()` / `tlComment()` | `.tl-item` | `data-kind=comment\|event`, `data-tone` | — | a card, or one dim line with a glyph |
44 | **empty state** `empty()` | `.card.empty`, title `.empty-title` | — | icon, one title, one sentence, **exactly one** action | the same three lines, centered |
45 | **diff file** | `.diff-file` | `data-status`, `<details open>`, `.diff-viewed` | collapsed, viewed | a foldable file section |
46 | **code block** | `.code` | `:target` / `[data-hl]` line highlight | — | a numbered gutter |
47 | **prose** | `.prose` | — | 15px, 72ch measure | wrapped markdown |
48 | **settings shell** `settingsLayout()` | `.settings` (`.settings-nav`, `.settings-main`) | — | sticky nav ≥860px, scroll strip below | a sidebar and a pane |
49 | **repo header** `repoHeader()` | `.repo-head` | — | tab counts, Settings only for admins | a title line and a tab row |
50 | **where strip** `whereStrip()` (`scope.ts`) | `.where > .where-place` | `data-state=reading\|present\|absent` — accent dot, success dot, faint dot — the dot is the place's `aria-hidden` glyph span, its aside `.muted` | three places, always in this order and these words; a place is a link where one exists, and the third is the pin toggle | `● codeberg.org · ● workbench · ◆ this machine` |
51 | **live-browse banner** `liveBanner()` | `.live-note` | — | only on a live browse, above the content, one sentence | one accent line under the tab row |
52 | **where-it-lives block** | `.where-block` | — | origin, last fetch, Sync now and where pushes land, as one block in the About rail | the same four lines under a rule |
53 | **mirror stages** `stageList()` | `ol.list.stages[aria-live=polite] > li > .row` | `data-state=done\|now\|todo\|failed` (failed: the stage the job stopped on, a danger "Failed" badge) | the stage order is the markup order; a script updates it in place and goes to the mirror on done; without JavaScript the same markup renders and a `<noscript>` Reload link re-reads it. Nothing here refreshes itself: no `<meta refresh>`, no timer | a checklist with `●`/`◐`/`○` |
54 | **origin chip** (`chrome.ts`) | `.repo-origin > .origin-chip` | the forge's mark: `github` / `forgejo` / `gitea` | the older one-line form, still used off the repo header | one `mirrored from owner/name @ host` fact line |
55 | **origin state badge** `badge()` | `.badge` | `success` healthy · `danger` needs re-auth · `attn` error | the error message sits under the row, never inside the badge | the same three words beside the row |
56 | **imported author** `originTag()` | `.byline.origin-by` | the origin's mark instead of an avatar | never a link to `/name` — that would be a different person | `▲ login` |
57 | **pin toggle** `whereRow()` | `.repo-where form.where-pin > .btn` | `outline` unpinned · `secondary` pinned | reads `Keep on my machine` / `On my machine ◆`; the strip's third place submits the same form by id, so a `<button>` can sit in a row of links; the wanted state rides the form, so a double submit is idempotent | `p` on a row, `P` on a repo home; `◆` marks a pinned row |
58 | **device code** | `.device-code` | — | the one deliberately large type in the product: monospace, tabular, `user-select: all` | the code spaced out and centred in a card, with a spinner under it |
59 | **sticky action** `stickyAction()` | `.sticky-action` | — | static ≥720px | a footer action bar |
60 | **count group** `counts()` / `repoCounts()` | `.counts > .count` | — | icon plus a tabular number; **a zero is never drawn** — the absence is the same information | `⊙3 ⑂1` after the row title |
61 | **file explorer** `explorerColumn()` | `.code-layout` (`.explorer-panel`, `.explorer`, `.ex-dir`, `.ex-file`, `.ex-more`) | — | the path's ancestors arrive `open`; the current file is `aria-current`; a folder off the spine holds one `.ex-more` link so it works with no script | a left pane the cursor walks |
62 | **fuzzy finder** `finderDialog()` | `.dialog.palette.finder` | — | JS only; `t` opens it, the explorer beside it is the fallback | the file picker overlay |
63 | **file editor** | `.editor-form` (`.editor-head`, `.editor-wrap`, `textarea.editor`, `.editor-gutter`, `.editor-commit`) | — | a plain `<textarea>` in a `<form>`; the gutter, tab key, auto-indent and Preview tab are all enhancement | a modal buffer with a commit prompt |
64 | **branch row** | `.branch-row` (`.branch-div` → `.ahead` / `.behind`) | — | default first, `Default` and `Protected` badges, `↑ahead ↓behind` | one line per branch with the same arrows |
65 | **code hit** | `.code-hit` (`.code-line`, `mark`) | — | `path:line` in mono, the matching line beneath it with the query marked | the same two lines, the match reversed |
66 | **verdict badge** `verdictBadge()` | `.badge` / `.badge.verdict-stale` | `success` approved · `danger` changes requested · plain commented | a verdict passed before the latest push renders `.verdict-stale`: same words, no colour, and the line says "before the latest push". It is history, not a position — and an approval a push dismissed must never look current | `[✓ approved]` / `[! changes]`, dim when stale |
67 | **reviews chip** | `.reviews-chip` | — | one line inside the merge box: `✓ 2 approvals · ! changes requested by bob · an approval is required`. It names people, because a name is somebody to go and talk to and a number is not | the same line under the merge verdict |
68 | **review card** | `.card.review-card` (`.review-verdicts`) | — | one form, radios plus an optional body. Which radios appear is the rule made visible: no Approve for the author, none of the gating verdicts for a reader — both refused in `submitReview` too | a three-way prompt with a body field |
69 | **review thread** | `.dc-review` (a `card()` per thread) | — | open: the comments, then Resolve. Settled: **one line** — `✓ resolved by alice · 2h ago` — with the conversation behind a small `disclosure()` and Unresolve in the card's foot. Resolving is for getting an answered question out of the way of the unanswered ones | a folded thread with a `✓` header |
70 | **propose card** | `fieldset.editor-target.propose` (`.propose-line`) | — | replaces "Where this lands" when the change is a contribution: the whole outcome in one sentence with **both** repository names, then branch, pull title and pull body. There is no "commit directly" radio, because there is no such option | the same sentence above the commit prompt |
71 | **run state badge** `runStateBadge()` | `.badge` | `queued` · `running` (attn) · `ok` (success: _Passed_, or _Done_ for an agent run) · `failed` (danger) · `cancelled` (outline) | the one badge a check wears on a pull, a run wears in a list, and a log page wears in its head; the log page's script repaints it on `done` | `[✓ passed]` / `[✗ failed]` / `[· running]` |
72 | **env state badge** `envStateBadge()` | `.badge` | `stopped` (outline) · `deploying` (attn) · `running` (success) · `failed` (danger) | what production, or a preview, is doing now; `envTone()` is the same answer as a `dot()` for a list row | the same word in the same tone after the environment's name |
73 | **app strip** | `.app-strip` | — | one line under the repo header of a repository that runs: env state badge, `sha`, the production URL as a link **through `…/app/production/open`** (never the bare hostname — a private app would 404), the preview count, the pace (`first preview 2m 14s after New app · in production 9m`, each part once it exists), App (the studio app page)| one line under the where strip: `● running abc1234 · hello.localhost` |
74 | **environment card** | `.card.env-card` (`.env-facts`, `.env-error`) | `data-tone=danger` when failed | name and state in the head; `envFacts()` in the body — commit, how fast it came up, uptime, a link to the deploy run, and the deployment's own note and error, each on its own line; Open (or Wake it) below. It is a pull's preview card; the facts and `envActions()` (Redeploy / Stop, writers only) are functions, not markup, so the studio head and its preview rows render the same ones | a box per environment with the same three lines |
75 | **checks line** | `.checks-line` (`.ok`, `.bad`, `.now`) | — | inside the merge box, in the reviews chip's voice: `✓ Checks passed · deploy abc1234 · a passing deploy is required`. Rendered only where the repository runs as an app or requires checks; a merge box gains _Waiting on checks_ | the same line under the review line |
76 | **run log** | `pre.run-log` | `data-run` while the run is going | the log as written, wrapped so a phone never scrolls sideways; a script appends the run's lines from the page's one `/events` stream and follows the bottom until the reader scrolls up; the page never reloads itself | a scrolling pane that follows the tail |
77 | **assignee card** | `.card` with an `.edit-row` form | — | who is on it, then one select and one button for a writer. People first, the crew last and marked `(agent)`, because assigning an agent is what starts it working and the choice is not the same kind of choice | a picker with people, then agents |
78 | **inbox** (`asks_page.ts`) | one list above the feed | — | _On you_: what asks you and what is assigned to you, one row each, each with what it waits for (`needsYouSection`), and one count in the top bar. Absent when empty: a card saying nothing is a zero drawn | the same two panes on the dashboard |
79 | **look** (`pages/looks.ts`) | `.look` in a `.looks` strip | `.look[data-slot=phone\|desktop\|thumb\|now]` sizes the frame; `.looks[data-compare]` sets two sides (before · main, then after · the pull) beside each other | a picture always carries its own `width`/`height`, so nothing shifts when it loads; a phone keeps 200px, a desktop takes the rest up to its own size, and under 640px a strip stacks; an attached picture is a `figure` in the strip with its line under it | the picture in the terminal (§6·0c) |
80 | **board** (`pages/board.ts`) | `.board` (`.board-grid`, `.board-region`) | `data-wall` (across the room: no keys, no pointer, larger), `data-focus=working\|landed\|decided\|today` | the one whole-screen layout: four live regions fill a second monitor ≥1100px and each list scrolls on its own, one column below; above the panels only a collapsed one-line `#notes` (`<details>`: closed by default, an open list stays open across live swaps), the strips below them; inside, only §5 parts (list card rows, badges, meters, `kbd`); a swapped region's heading wears `data-fresh` for a moment | four panes, one focused by its number |
81 | **stacked bar chart** `windowSvg()` (`fleet-graph.ts`) | `.plots`, `.plot` (`.plot-name`), `.plot-legend` | bars wear `fg-sN`, the `--series-N` token | server-drawn SVG with `width`/`height` set, so it holds its box before the stylesheet; gridlines `--border`, figures `--muted-fg` in mono, panel names `--faint`; `role="img"` with an `aria-label` totalling it, a `<title>` per bar, and a table of the same numbers beside it | a table of the same numbers |
82 | **chart** `chartBox()` (`ui.ts`) | `.chart-box` wrapping `drawChart`'s svg `.chart` (`.big` for the headline figure) | `.is-table` for a table panel | one query or series drawn on the server: the svg carries its own `width`/`height` and the box holds its space, so nothing shifts; `role="img"` with an `aria-label` of its title. Reach for it wherever a page draws a `boards/chart.ts` chart — `/system`'s memory pair and every board panel — and size it from the page (`.bp-*`, `.plots`, `.bgrid`), never inside the frame | the same numbers as a table |
83
84 Two things are deliberately **not** in the vocabulary: skeleton loaders (the
85 server renders whole pages — there is nothing to skeletonise) and a custom
86 switch control (a native checkbox with `accent-color` is themed, keyboard-correct
87 and honest about what it is).
88
89 Three rules the browser enforces whether or not you meant them:
90
91 - **A name says who it is, and nobody types that.** Beside the owner's name
92 and each agent's, `userLink()` wears a `nameMark()` — `owner`, `crew` —
93 drawn from the account (`core/marks.ts`: an admin who is a person; an
94 agent), never from a display name. Every name is escaped, so no typed word,
95 alphabet or emoji produces the `data-mark` element; a byline without one is
96 nobody the mark vouches for. A page asks `marksByName()` once for the names
97 it will show. `test/name-marks.test.ts` tries the disguises.
98 - **A link inside a link is not a link.** `<a>` nested in `<a>` is not merely
99 invalid — the parser closes the outer anchor and re-parents everything after
100 it as a _sibling_, so the row visibly falls apart. Anything rendered inside a
101 linked `.row` uses the non-anchor form: `userTag()`, not `userLink()`; plain
102 text, not a repo link. `test/web-ui.test.ts` sweeps the list pages for it.
103 - **Whitespace is content inside `white-space: pre`.** The diff cell (`.dc`) is
104 pre-formatted, so a pretty-printer's newline between `<td>` and its span
105 renders as a blank line and an indent. Assemble such a cell into one value
106 and interpolate it whole; `.dcx` holds the `pre`, so a stray newline costs a
107 collapsed space rather than a broken line.
108 - **A grid or flex item's automatic minimum size is its content.** A column
109 holding one long unbreakable line pushes the page wider than the phone
110 instead of letting its own ellipsis work. Every page grid sets
111 `min-width: 0` on its children.
docs/design/sections/5a-reading-from.md added +35
@@ -0,0 +1,35 @@
1 ### 5a. Saying where you are reading from
2
3 Every repository page in the product carries the **where strip**, and it says
4 the same three things in the same order however you got there:
5
6 ```
7 ● codeberg.org · ○ workbench · ○ this machine browsing live, read-only
8 ● codeberg.org · ● workbench (synced 3m ago) · ◆ this machine a mirror you keep
9 ● workbench · ○ this machine a repository born here
10 ```
11
12 - **Filled `●` means present, hollow `○` means absent, `◆` means kept on this
13 machine.** The dot carries the colour; the word never does, so a strip reads
14 as one fact rather than three competing badges.
15 - **Accent marks the place these bytes came from.** That is the page's own
16 subject, which is the one thing accent is allowed to be besides interaction
17 (§1.2). Exactly one place per strip wears it.
18 - **Every place is a link where one exists**: the origin goes to the repository
19 on that forge, the workbench to the mirror here, and "this machine" submits
20 the pin toggle.
21 - A repository that is **your fork of** another one says so in the strip, as
22 the origin place's aside: `● codeberg.org (fork of octo/widgets)`. The About
23 rail carries the same fact as a linked `Fork of` row — the strip is for
24 orienting, the rail is for going there.
25 - A live browse also carries `.live-note` above the content, saying it is
26 read-only and what to do about that. There is no second way to find out: a
27 live page renders no composer, no state form, no labels form, no merge box
28 and no settings tab, because `RepoSource` has no mutation on it to submit to.
29 The three forms it does carry — Mirror, Fork, Propose a change — create
30 something **for you**: a copy here, a fork of your own there, a proposal on
31 it. None of them changes the repository being read.
32
33 The strip is the visible half of `RepoScope` (`src/web/scope.ts`); the pages it
34 sits on are the same renderers for both sides of the world, and a divergence
35 between a live browse and the repository we hold would be a bug you could see.
docs/design/sections/5b-workflow-units.md added +42
@@ -0,0 +1,42 @@
1 ### 5b. The workflow units
2
3 A unit is a whole intention with one button behind it, not a sequence of
4 screens you assemble yourself. Five of them, and the web renders each as one
5 form:
6
7 **Fork** — on a live browse and on every picker row you cannot push to. It
8 POSTs `…/fork`, forks at the origin, and answers with the mirror job page,
9 exactly as Mirror does, because the local copy of a fork is a job with stages.
10 The flash names both halves and the host: `Forked octo/widgets to me/widgets at
11 codeberg.org.` Not offered on a repository the connected account already owns —
12 neither forge forks you to yourself. A native repo keeps its own `…/fork`.
13
14 **Propose a change** — where the origin says you may not push, Edit and New
15 file become Propose a change and open the ordinary editor with the propose card
16 under it. One POST to `…/contribute` forks if needed, branches on the fork,
17 commits, and opens the pull upstream with the `owner:branch` head form. You land
18 on the pull: its page here if we mirror the upstream, its live-browse page if we
19 do not — never thrown out to another forge mid-workflow. Every refusal
20 re-renders the editor with the text still in the textarea (`§6c`'s rule: never
21 lose a keystroke).
22
23 **Pass a verdict** — the review card, one POST to `…/review-state`. Verdicts
24 land in the timeline as `verdictBadge` items in time order with the comments and
25 the state changes, because a verdict is a thing that happened at a time.
26
27 **Settle a thread** — every review comment sharing an anchor is one
28 conversation, resolved by a writer or by anybody in it, at
29 `…/threads/:anchor/{resolve,unresolve}`. The files header counts them:
30 `3 threads · 1 unresolved`.
31
32 **Merge, or not** — the merge box gains a sixth state, _Waiting on review_,
33 whenever `require_review` is unsatisfied or a change is outstanding. The button
34 is disabled and the chip says who to talk to; the refusal is `mergePull`'s
35 (`review_required`), and the disabled button is only the honest preview of it.
36 `Require an approving review before merging` is a checkbox in General settings.
37
38 One rule holds all five: **the page never decides.** Every affordance here is
39 rendered from the same answer the action will give — `permissions.push` for
40 propose, `status.reviews` for the gate, `canWrite` plus thread authorship for
41 resolve — so a button that is absent and a call that is refused are the same
42 fact said twice, and never two different facts.
docs/design/sections/5c-apps-runs-crew.md added +51
@@ -0,0 +1,51 @@
1 ### 5c. Apps, runs and the crew
2
3 `docs/APPS.md` is the contract; these are its units on a page, and the same
4 rule holds: the page never decides. Six of them:
5
6 **New app** — `/apps/new`, one form: a name, a sentence about what it should
7 do, visibility, and an agent from the crew when there is one. One POST makes
8 the repository with a working app in it, makes it an app, starts production,
9 and — with a sentence and an agent — opens issue #1 assigned. The flash names
10 the production URL and the agent. A forge with no agents says so on the form
11 in one line and offers the same button without the select.
12
13 **Run as an app** — on a repository's settings, the App section: enable with a
14 slug, an access choice and the preview-data policy; edit them; disable behind
15 a confirm page. The app strip (§5) appears on the repository the moment it is
16 on.
17
18 **Open** — never the bare hostname. Every link to an environment goes through
19 `…/app/:env/open`, which checks `canRead` and answers with the URL — carrying a
20 grant for a private app — so the same link works for a public app and a
21 private one and a stranger gets `not_found` from the forge rather than a
22 guess at a hostname.
23
24 **Redeploy / Stop** — two POSTs on the studio app page (`studio/app.ts`;
25 dev's old `/:owner/:name/app` redirects there), writers only: production's
26 in the head card, each preview's on its row; a stop keeps the data (a
27 redeploy brings it back), a stopped environment shows the honest word and
28 the run that stopped it.
29
30 **Assign** — the assignee card on an issue and a pull: nobody, then people
31 who can read the repository, then the crew marked as agents. Assigning an
32 agent is the dispatch, so the select says so beside the crew. An agent's own
33 pull opens already assigned to it.
34
35 **Cancel a run** — one POST on the run page while it is unfinished; the log
36 keeps everything up to the cancel and the badge says `cancelled`.
37
38 The merge box gains a seventh state, _Waiting on checks_, when
39 `require_checks` is on and the head's deploy is not green; the refusal is
40 `mergePull`'s (`checks_required`) and the chip links the run. A pull's
41 **Preview** card and its **Checks** line read the same run rows a
42 `runStateBadge` does elsewhere — a check is a deploy, never a separate
43 object that can drift.
44
45 **Website spec findings** — under a pull's Checks line, from the preview's
46 latest deploy run (`core/preview_findings.ts`): a **disclosure** whose
47 summary is the count (edge-owned findings counted apart) and whose body is
48 a `.list` of `.row`s, one per finding, with its specification.website
49 section as an https link. Report-only, so the words never say failed; the
50 summary is at least 44px tall for a thumb. The terminal says the same count
51 at the end of the checks row.
docs/design/sections/5d-page-local-classes.md added +62
@@ -0,0 +1,62 @@
1 ### 5d. Page-local classes
2
3 The close form on an issue's thread is no class at all: its reason select and
4 "close into" input are plain §5 inputs, the height of the Comment button beside them, and `style/content.ts` shows the
5 input only while "split into…" is chosen, by attribute selector inside
6 `.form-actions` (`select[name="reason"]`, `input[name="into"]`). It is a rule
7 about the form, not a component.
8
9 Every class a stylesheet defines is named in this section (`bun
10 scripts/design-lint.ts` fails one that is not, #2700). The table above is
11 the vocabulary; the classes below are what pages built beside it before that
12 rule held. They are registered, not endorsed: each belongs to the file it is
13 listed under, and a new page reaches for §5's components instead of
14 borrowing one. The plan (`docs/design/plan.md`) retires them page by page —
15 onto a §5 component, or into the table when a page-local thing turns out to
16 be a component — and the check fails a name kept here after its last rule is
17 gone, so this list only shrinks. Each class sits on its own line, so to
18 retire a class, delete its line: two pulls retiring two classes never edit
19 the same line (#4888).
20
21 - **`style/base.ts`** — the page shell (topbar, main, footer) and the layout and text utilities every page leans on:
22 - `.bar`
23 - `.bare`
24 - `.foot`
25 - `.hide-sm`
26 - `.js-only`
27 - `.reduced`
28 - `.shell`
29 - `.skip`
30 - `.topbar`
31 - `.wordmark`
32
33 A `.field` directly inside a `.bar` drops its bottom margin and the bar aligns to the end, so a labelled input and its button share a baseline
34 - **`style/components.ts`** — parts of the §5 components that the table does not spell out — the palette's list, the menu's items, a dialog's head and foot, comments, the theme picker — and a few small helpers beside them:
35 - `.cat`
36 - `.error-note`
37 - `.list`
38 - `.menu-item`
39 - `.preview`
40 - `.sep`
41 - `.split`
42 - `.swatch`
43
44 `.split` is the one two-column page: main, then an `<aside>` rail of 260px that sticks from 960px. `data-rail="wide"` on it (the studio's home and an app's page) widens the rail to 320px from 900px, drops the top margin, and lets the rail scroll with the page, since a column of cards runs taller than a screen
45 - **`style/content.ts`, page furniture** — what frames a page's content: page and repo heads, the front page and its tiles, explore, backups, boards, the fleet chart's series colours, lineage:
46 - `.bgrid`
47 - `.bp-h2`
48 - `.bp-h3`
49 - `.bp-w2`
50 - `.bp-w3`
51 - `.commit-body`
52 - `.commit-head`
53 - `.filters`
54 - `.owner`
55 - `.page-head`
56 - `.policy-line`
57 - `.repo-actions`
58 - `.repo-desc`
59 - `.slash`
60 - **`style/content.ts`, apps, runs, and the crew** — run pages, their logs and checks (a pull's look is §5's **look**).
61 - **`pages/board.ts`** — the board itself is §5's **board**; the spend tables `spend.ts` draws wear §5's `.table` and `.stack`, no class of their own
62 - **`studio/feed_style.ts`** — the home feed's cards and its composer (the apps rail is §5's card, row and btn; an admin's tick boxes and Archive are always shown, deliberately, with no Select toggle):
docs/design/sections/6-0-pointer.md added +50
@@ -0,0 +1,50 @@
1 ### 6·0. The pointer
2
3 The terminal UI is keyboard-first and mouse-**complete**: everything you can
4 see is something you can click, and clicking never reaches somewhere the
5 keyboard could not. Reporting is on from the moment a session starts
6 (`?1000h ?1002h ?1006h`, SGR coordinates last) and off before the alt screen
7 is left. The one cost is real and is said out loud in the `?` overlay:
8 **shift-drag** is now how you select text, because the terminal's own
9 selection is what mouse reporting takes away.
10
11 **The model is a hit table rebuilt every frame.** During `render`, a screen
12 claims rectangles with `ctx.hit(rect, handler)`:
13
14 ```ts
15 ctx.hit(rect, (e) => open(rows[e.y])); // click only
16 ctx.hit(rect, { click, wheel }); // and the wheel
17 ```
18
19 The registry is cleared at the top of every paint and rebuilt by whoever
20 draws, so a region can never outlive the pixels it stands for — the bug every
21 retained hit table eventually has. Regions are searched **newest-first**, so
22 whatever drew last is what a click reaches: an overlay draws after the screen
23 beneath it, and needs no z-index to win. A region that does not handle _this_
24 gesture is not in the way of one that does, so the wheel over a clickable row
25 still scrolls the list the row is in.
26
27 Four rules hold the gestures together:
28
29 - **A click selects; a second click on the selected row opens it.** So does a
30 double-click on any row. A single click has to be safe, because half of
31 pointing at a row is looking at it, and a list where looking navigates is a
32 list you cannot browse.
33 - **One notch is three rows**, delivered to the region under the pointer. A
34 notch nobody claimed falls back to arrow keys, which is what a wheel has
35 always meant.
36 - **Mouse input is never a synthetic keystroke.** Nothing reaches
37 `Screen.key`; a screen that wants a click says so with `ctx.hit`. The
38 keyboard behaviour of every screen is unchanged by any of this.
39 - **A click on an overlay's dimmed backdrop dismisses it**, and does not reach
40 the row underneath.
41
42 Clickable today: every list row, the dashboard's four panes, the workspace's
43 explorer rows and tab chips (including the active tab's `✗`), the file pane
44 (focus, and the wheel), the where-strip's three places, the palette's results,
45 the appearance picker's rows, the owner, refs, settings, account
46 lists, the pull's diff-and-threads pane, and **every
47 hint in the help bar** — clicking a hint presses the key it names, taken from
48 the binding itself so a label can never drift from the action. A list with no
49 `hitList` is a bug, not a design decision: "everything you can see is
50 something you can click" is the whole claim.
docs/design/sections/6-0a-1-terminal-layout.md added +24
@@ -0,0 +1,24 @@
1 ### 6·0a·1. Laid out for the terminal it is in
2
3 Three numbers in `ui/layout.ts` decide every screen's shape, so every screen
4 folds at the same width and none invents its own. At **100 columns** a list
5 sits beside its detail; below, `beside()` stacks the two with the detail
6 underneath (two fifths of the height unless the screen says otherwise), and
7 drops it only when there are fewer than twelve rows to share. Under **40×10**
8 no layout survives — a card is narrower than its title — so one line says what
9 would help, and every screen keeps its state for the moment the window grows.
10
11 A resize re-lays the current screen at once and loses nothing: a list keeps
12 its cursor and scrolls it back into view, a log keeps the _line_ at the top
13 of the reader's window whatever number of rows it now wraps to, and a program
14 holding the pty (`$FORGE_EDITOR`, an app's `tty`) hears the new size before
15 the UI does. Long text wraps or ends in an ellipsis at the width, never past
16 it. A row's meta gives way before its title starves — the leading pieces
17 (`metaOf` order: a commit, then a cost, then the time) go first, the last one
18 last — and a table's ranked columns (`drop`) are given up lowest first, the
19 same word `local/rows.ts` uses.
20
21 An activity row is one line, not two, because a row is a thing you can put a
22 cursor on: `who did what · the object`, with the time in a fixed right-hand
23 column. The headline already ends with `#4`, so the object drops the repeated
24 number rather than truncating the title.
docs/design/sections/6-0a-dashboard-panes.md added +13
@@ -0,0 +1,13 @@
1 ### 6·0a. The dashboard's panes
2
3 `Repositories`, `Recent activity`, `On you`, `On your machine`,
4 `Organizations`. What is running is the studio's question, on the web; the
5 terminal's dashboard is the code and the conversations. Each is a pane with its own cursor: `tab` / `shift+tab` cycles, the focused one wears
6 the accent frame, `j`/`k` move inside it and `enter` opens what it is pointing
7 at — an activity row opens **the issue, pull or repository it is about**, a
8 pin opens its repository, an organization opens its page. `d` on a pinned row
9 unpins it (asking first). A click does all of the same. Below 100 columns the
10 activity feed stacks under the repository list and the three small cards wait
11 for a wider window; shorter than twelve body rows, the repositories have the
12 whole body. `tab` reaches exactly the panes the last frame drew: a focus ring
13 on a card that is not on screen is worse than no focus ring.
docs/design/sections/6-0b-icons-appearance.md added +32
@@ -0,0 +1,32 @@
1 ### 6·0b. Icons, and the appearance picker
2
3 Two vocabularies. **`plain`** is the safe set (§6a) — BMP, width 1, in every
4 default terminal font. **`nerd`** is the same vocabulary drawn from a Nerd
5 Font, which is a bet on the reader's _font_, a thing `TERM` cannot tell us.
6 `auto` takes the bet on Ghostty, kitty and WezTerm, because those are
7 terminals people install deliberately and installing a Nerd Font is the next
8 thing those people do. Everything else gets `plain`.
9
10 The bet is bounded: every glyph in both sets is exactly one cell (asserted by
11 `test/tui-icons.test.ts`, since every Nerd codepoint lives in a Private Use
12 Area that `width.ts` measures as width 1), so a missing glyph is one tofu box
13 and never a shifted row. Where the two sets would say different things, the
14 plain set keeps the documented grammar: `◆` still means "kept on your
15 machine", and an unpinned row still wears nothing.
16
17 `ctrl+t` opens **Appearance**: the six themes, then two more rows —
18
19 | row | values |
20 | -------- | --------------------------------------------- |
21 | `Images` | `auto (kitty)` · kitty · sixel · iterm · none |
22 | `Icons` | `auto (nerd)` · nerd · plain |
23
24 `j`/`k` move, `left`/`right`/`enter` cycle a setting's value, a theme applies
25 as the cursor passes over it, and both settings persist through
26 `setPreference` into `user_setting`. It is `ctrl+t` and not `t` because the
27 workspace already spends `t` on the file finder, and an appearance picker
28 that silently does nothing on the one screen people live in is worse than a
29 modifier: one key, every screen, whatever has focus. Under the rows is a **live preview** —
30 three real icons in the set currently chosen — because the only honest way to
31 settle a bet about somebody's font is to show them three glyphs and let them
32 look. If they see boxes, one keypress puts it back.
docs/design/sections/6-0c-terminal-pictures.md added +22
@@ -0,0 +1,22 @@
1 ### 6·0c. Pictures in the terminal
2
3 A tab whose path looks like an image and whose bytes git returned as binary is
4 a **picture tab**. Where the terminal can show pixels it does
5 (§`term/graphics.ts`: kitty for Ghostty/kitty/WezTerm, sixel where detected,
6 iTerm2 by setting); where it cannot, a placeholder card names the format, the
7 geometry and the size, and says plainly what would show it.
8
9 The loop owns the lifecycle. A screen calls `ctx.placeImage(placement)` during
10 render and the bytes go out **after** the frame, raw; not calling it removes
11 whatever the last frame placed. That one rule makes a tab switch, a close, a
12 `pop`, a resize and a theme change all clean up by themselves, with no screen
13 having to remember to. A placement is re-sent only when it is genuinely new —
14 a different image, a different rectangle, or a repaint that invalidated
15 everything — because `drawImage` reserves its cells with the theme ground and
16 an ordinary frame emits nothing over them. Re-sending a megabyte of base64 on
17 every keystroke is the one thing that would make pictures unusable over SSH.
18
19 Aspect ratio comes from the client's own `pty-req` / `window-change` pixel
20 fields when it sends them (most send zeros), and from the 1:2 guess otherwise.
21
22 `v` toggles a picture between the pixels and the facts about the file.
docs/design/sections/6-keyboard.md added +34
@@ -0,0 +1,34 @@
1 ## 6. Keyboard
2
3 Driven entirely from the DOM: `data-shortcut="g i"` on a link, `data-nav` on a
4 row. The `?` overlay is generated by walking `[data-shortcut]`, so the help can
5 never drift from the app.
6
7 | key | action |
8 | --------------- | ---------------------------------------------- |
9 | `g h` | home |
10 | `g c` | repo code |
11 | `g i` | issues |
12 | `g p` | pull requests |
13 | `g m` | commits |
14 | `g b` | branches |
15 | `g s` | repo settings |
16 | `j` / `k` | next / previous row (visible focus ring) |
17 | `o` or `Enter` | open the focused row |
18 | `c` | the page's create action (new issue, new pull) |
19 | `t` | go to file (the fuzzy finder), on a code page |
20 | `e` | edit the file you are looking at |
21 | `/` | focus search |
22 | `⌘K` / `Ctrl K` | command palette |
23 | `?` | shortcut help |
24 | `Esc` | close a menu or dialog, blur a field |
25
26 Inside the code view, shift-clicking a second line number extends `#L3` to
27 `#L3-L9` and highlights the range.
28
29 `t` and `e` are not a new key layer: they are `data-shortcut` attributes on
30 the real controls, so the `?` overlay learns them for free and a page without
31 those controls does not answer the key. `j`/`k` are the shell's own row
32 traversal, and the explorer's files are `data-nav` rows — which is why
33 arrowing through the tree previews as you go without a single extra key
34 handler: `codeJs` listens for **focus**, not for keys.
docs/design/sections/6a-code-browser.md added +33
@@ -0,0 +1,33 @@
1 ### 6a. The code browser
2
3 Tree and blob pages are one layout, not two: a `.code-layout` grid with the
4 explorer on the left and the content on the right at ≥900px, the explorer
5 folding into a "Files" `<details>` above the content below it.
6
7 - **The spine, not the tree.** A page renders the path's ancestors and their
8 siblings, never the whole repository, so a monorepo costs the same markup as
9 a toy. Every directory is a `<details>`; the ones on the spine arrive open.
10 - **A folder the server did not expand is still a link.** Opening one with no
11 script shows a single `Open src/…` link to that folder's own page; with a
12 script, `codeJs` fetches `?fragment=explorer` and drops the rows in.
13 - **The preview is the page.** Hovering or arrowing a file fetches the blob
14 route's own `?fragment=1` — the same renderer, the same markup, the same
15 `#code-pane` — so a preview and a real navigation are indistinguishable, and
16 `enter` simply follows the link that was already there. Fetches are
17 cancelled and cached, and there is no scroll-stealing or URL rewriting.
18 - **The explorer opens closed and the stylesheet opens it.** `<details>`
19 without `open`, plus `::details-content { content-visibility: visible }` at
20 ≥900px. Where that pseudo-element is understood the handle is hidden too;
21 where it is not, the handle stays and one click opens the column. Nothing
22 can end up invisible with no way back.
23 - **The finder is a dialog over JSON.** `t` (or the button) fetches
24 `/:owner/:name/paths/:ref` once and scores it client-side with fzf's
25 FuzzyMatchV2 constants under its `path` scheme — boundary 8, delimiter 9,
26 camel 7, consecutive 4, match 16, gap −1, first character doubled, string
27 start treated as though it followed a `/` — on top of a 28-bit
28 characters-present bitmask prefilter and a two-pointer subsequence check, so
29 the affine-gap DP only ever runs on real candidates. VS Code's tiering sits
30 above the score rather than inside it: any match inside a file's own name
31 outranks any match that only lands in its directories, and a basename
32 _prefix_ outranks that again. Without a script the finder does not exist and
33 the explorer beside it is the answer.
docs/design/sections/6a-counts-and-marks.md added +21
@@ -0,0 +1,21 @@
1 ### 6a. Counts and marks on a row
2
3 Three glyphs carry the at-a-glance numbers, all of them BMP, all width 1, all
4 present in every default terminal font in wide use — no Nerd Font (we cannot
5 assume a patched font over SSH) and no emoji (their width is genuinely
6 inconsistent, and one column of error shifts an entire row):
7
8 | glyph | means | where |
9 | ----- | ----------- | ------------------------ |
10 | `○` | open issues | every repo row |
11 | `↳` | open pulls | every repo row |
12 | `▭` | comments | every issue and pull row |
13
14 They render muted, right-aligned in the row's meta column, and **tabular**:
15 the widths are computed once across the whole page so the numbers form a
16 column instead of jittering row to row. **Zero is absent, not `○ 0`** — an
17 empty queue should read as quiet, and a column of zeroes reads as noise.
18
19 The numbers come from grouped reads (`countsForRepos` / `withCounts`,
20 `commentCountsFor`) and never from a query per row. `test/counts.test.ts` and
21 `test/tui-code.test.ts` both assert that; a list is where N+1 hurts most.
docs/design/sections/6b-code-coloured.md added +41
@@ -0,0 +1,41 @@
1 ### 6b. Code, coloured
2
3 One tokenizer, `src/web/highlight.ts`, serves the file browser, the diff
4 viewer, Markdown fences, the terminal UI and the browser bundle the editor
5 loads. It is a stateful per-line scanner over rule tables — Prism's model, not
6 a parser — and it is bound by three properties the tests assert for every
7 language: **lossless** (a line's tokens concatenate back to the line),
8 **linear** (10,000 characters in well under a millisecond, no backtracking
9 regex), and **total** (random bytes never throw).
10
11 Roughly thirty languages have rule tables, including the ones a forge actually
12 holds: ts/tsx/js/jsx (template literals, regex-versus-division, decorators,
13 JSX tags), python, go, rust, c/c++/objective-c, java, kotlin, swift, ruby,
14 php, lua, zig, elixir, nix, sql, json/jsonc, yaml, toml, ini, markdown,
15 css/scss, html, shell, dockerfile, makefile and diff. Detection is by
16 extension, then by whole filename (`Dockerfile`, `Makefile`, `.zshrc`), then —
17 only for a file that has said nothing else — by shebang or editor modeline:
18 `detectLanguage(path, firstLine)`.
19
20 **Two levels of token.** `cls` is the colour _every_ consumer understands —
21 `keyword string comment number function type operator punctuation constant
22 meta plain` — and it is what the terminal's theme table maps. `kind` is a
23 refinement only the web paints: `property tag attribute regex variable
24 decorator heading emphasis link inserted deleted`. A token renders as
25 `class="tok-<cls> tok-<kind>"`, the kind rule comes last in the stylesheet and
26 so wins at equal specificity, and dropping the kind leaves a page that is less
27 specific but never wrong. That is the whole reason the vocabulary can grow on
28 the web without the terminal having to agree first.
29
30 Punctuation and operators are deliberately **below** body colour
31 (`--tok-punctuation`, `--tok-operator`): they are a line's scaffolding, and
32 colouring them loudly makes code shout. Diff-inside-a-fence borrows the diff
33 tints (`--add-fg` / `--del-fg`) rather than inventing a colour.
34
35 **Markdown has two right answers.** A `.md` blob renders as prose by default
36 and offers `Source | Rendered` in its path header; `?view=source` is a plain
37 link, so both halves work with no JavaScript, are addressable, and survive
38 being sent to somebody. The rendered half is the README renderer — fenced code
39 is highlighted in the language the fence names, tables are tables, and a
40 relative link (`docs/keeping.md`) resolves, while anything carrying a scheme
41 other than http(s), or a protocol-relative `//host`, is left as text.
docs/design/sections/6b-workspace.md added +119
@@ -0,0 +1,119 @@
1 ### 6b. The workspace — one screen for a whole repository
2
3 Opening a repository in the terminal opens a **workspace**, not a home page:
4 the explorer, a tab bar, the file you are reading, and the one commit that
5 carries everything you changed. There is no repo card to leave, no directory
6 screen to push, no blob screen under it and no editor screen on top. The four
7 screens that used to be there were four escapes deep and lost your place at
8 each one.
9
10 ```
11 forge Ink
12 alice › alice/lighthouse
13 ● workbench · ○ this machine main ▾
14 README.md src/lamp.ts ● src/weather.ts 3 tabs
15 ▾ src/ ┃ 1 # Lighthouse
16 lamp.ts ● ┃ 2
17 weather.ts ┃ 3 A beacon. Rotates the lamp, logs the weather, warns the ships.
18 package.json ┃
19 ▸ README.md ┃
20 main · 1 modified src/lamp.ts · 22 lines
21 tab focus explorer e edit c commit b switch ref t find file i issues
22 ```
23
24 The where strip keeps column zero, exactly as it does on every other
25 repository screen, and the ref pill (`main ▾`) takes the right-hand end of the
26 same row. At **≥100 columns** the explorer is a column beside the file; below
27 that it is the pane `tab` toggles onto, never both at once. A repository opens
28 on its **README** — the first file at the root if there is none — with the keys
29 already in the file pane, so `j` scrolls it without a keystroke of ceremony.
30
31 Four rules hold it together, and each one answers something the old
32 arrangement got wrong:
33
34 - **Moving the explorer's cursor reads nothing.** `j` moves a cursor over
35 names; `enter` opens a tab. The preview-that-followed-the-cursor it replaces
36 cost a read per keystroke, needed a debounce and a stale-read token to stay
37 honest, and left you unable to scroll the file you were looking at because
38 the selector lived in the other pane.
39 - **A tab owns its buffer.** Scroll position, in-file search, undo history and
40 every unsaved edit live in the tab. Switching tabs keeps them; so does going
41 to the issue list and coming back, because the workspace stays on the stack
42 while something is pushed over it.
43 - **Editing is a mode, not a screen.** `e` turns the active tab into the
44 buffer from `ui/editor.ts`, in place. `esc` goes back to reading **with the
45 edits still there** — losing work takes `u` (discard this tab) or `x` (close
46 it), and both ask first.
47 - **One commit for the whole change.** Every modified tab and every pending
48 deletion goes into a single `editFiles` call.
49
50 | key | in the explorer | in the file pane |
51 | ------------ | -------------------------------- | ------------------------------- |
52 | `j` `k` | move the cursor (reads nothing) | scroll |
53 | `ctrl+d` `u` | page | page |
54 | `g` `G` | top / bottom | top / bottom |
55 | `enter` `l` | expand a directory / open a tab | — |
56 | `h` | collapse, or go to the parent | scroll left (`l` scrolls right) |
57 | `tab` | focus the file | focus the explorer |
58 | `esc` | back | focus the explorer |
59 | `/` | filter this level | search in the file (`n` / `N`) |
60 | `n` `D` | new file / mark one for deletion | — |
61 | `e` | open the file and edit it | edit |
62 | `u` | — | discard this tab's changes |
63 | `v` | — | the file's other view (below) |
64
65 And the keys the whole workspace answers, from either pane: `]` `[` and `1`–`9`
66 move between tabs, `x` / `X` close one or the others, `c` commits, `b` lists
67 branches and tags, `B` creates a branch, `t` (or `ctrl+p`) is the fuzzy finder,
68 `y` copies the path, `i` / `p` / `C` open issues, pulls and commits, `I` shows
69 the about card, `W` swaps to the other side of a mirror, `O` opens the file on
70 its origin, `P` pins, `S` syncs, `F` forks, `,` is settings, `r` refreshes and
71 `E` hands the file to `$FORGE_EDITOR`.
72
73 **The tab bar.** One row above the panes: the path, the active tab bold and
74 underlined in the accent, `●` on anything modified, `¶` on prose being read
75 rather than edited, `‹ ›` when there are more tabs than fit, and the count on
76 the right. `¶` (U+00B6) is Latin-1, so it is in every font that can draw a box
77 character at all, and it is the one glyph in the safe set that already means
78 "formatted prose". A modified file wears the same `●` in the explorer, and one
79 marked for deletion is struck through in the danger colour — the same change,
80 said in both places. The **active** tab also wears a `✗` you can click; only
81 the active one, because a close box on every chip is a row of targets you hit
82 by accident, and the tab you mean to close is the one you are looking at.
83
84 **Two views, one key.** Some files have two honest ways of being seen, and `v`
85 is the toggle for all of them:
86
87 | file | opens as | `v` shows |
88 | ------------------- | -------------------- | ------------------------ |
89 | `*.md`, `README*` | rendered prose (`¶`) | the source, highlighted |
90 | `*.png`, `*.jpg`, … | the picture (§6·0c) | format · geometry · size |
91 | everything else | code | (nothing else to show) |
92
93 Prose opens **rendered**, because that is what a README is for and it is what
94 the repo card always did — but the rendered view is a view, not a mode: `j`/`k`
95 scroll it, `/` searches it, and `e` always edits the **source**, switching to
96 it if you were reading. The web and the terminal render that markdown through
97 the same rules, so a README reads the same in both.
98
99 **Colour follows the theme.** Switching theme re-tokenises every open tab on
100 the next frame; a tab that kept yesterday's palette is exactly the bug a
101 screenshot hides.
102
103 **Coming back is free.** A workspace's open tabs, its explorer cursor, its ref
104 and every uncommitted buffer live on the **session**, keyed by repository — so
105 popping to the dashboard and re-entering the same repo restores what you were
106 doing, not just where you were. One connection is one identity, so nothing
107 another user opened can be reached, and the memory dies with the connection;
108 an entry nobody has touched for thirty minutes is dropped on the next lookup.
109 `r` is still the refresh, and `x` still closes a tab.
110
111 **The about card (`I`).** What used to be the repo home page: visibility,
112 description, default branch, counts, where a mirror came from and when it was
113 last fetched, and the clone URLs (`y` copies one). It is a card rather than a
114 screen because it is something you glance at on the way to doing something
115 else.
116
117 The finder (`t`) scores with fzf's `--scheme=path` constants plus VS Code's
118 rule that any basename match outranks any directory-only match, and it says
119 "N files (truncated)" honestly when the listing hit its cap.
docs/design/sections/6c-1-contributing.md added +65
@@ -0,0 +1,65 @@
1 ### 6c·1. Contributing: fork at the origin, propose a change
2
3 The workflow the origins layer exists for — _grab their repo, branch, edit,
4 propose it back_ — is one intention, so it is two keys and one action call
5 (`actions/contribute.ts`), never five screens with five half-finished states
6 between them.
7
8 **`F` — fork at the origin.** On a live browse (and on the picker's rows) `F`
9 forks at the origin rather than here: a local fork of a mirror is a copy of a
10 copy with nowhere to propose it back to. One confirm card, saying the whole
11 sentence because two machines are involved —
12
13 ```
14 ╭─ Fork at the origin ───────────────────────────────╮
15 │ Fork octo/widgets to your account │
16 │ at codeberg.org and mirror it here? │
17 │ │
18 │ The copy here is your workbench. │
19 │ Cancel ▸ Fork │
20 ╰────────────────────────────────────────────────────╯
21 ```
22
23 — then the ordinary mirror card over the job the fork started, then the fork's
24 own workspace. A native repository keeps the native fork. Wherever a
25 repository forks something at an origin, the where-strip and the about card
26 say so: `· fork of octo/widgets`, read from `repo.origin_fork_of` on a mirror
27 and from the picker's cached `fork_of` on a live browse.
28
29 **`c` — propose a change.** When the source says `permissions.push === false`
30 — a live browse of somebody else's repository, or a mirror whose upstream is
31 not ours to push to — editing is allowed and the commit dialog becomes a
32 proposal dialog. Same buffers, same ticked files, no "commit to `<ref>`"
33 option (there is no ref of theirs you may write), and a branch that lands in
34 your fork:
35
36 ```
37 ╭─ Propose a change ──────────────────────────── octo/widgets ─╮
38 │ Message │
39 │ Update README.md │
40 │ optional — this becomes the pull request's body │
41 │ Files · 1 of 1 │
42 │ [x] ~ README.md │
43 │ Branch in your fork │
44 │ alice/edit-README-md │
45 │ Pull request › octo/widgets · main │
46 │ Update README.md │
47 │ Propose │
48 ╰──────────────────────────────────────────────────────────────╯
49 ```
50
51 `contribute` does the rest in one call: fork if a fork is needed, branch from
52 the _upstream's_ base rather than a stale copy of it, commit into the fork,
53 push it there, and open the pull upstream with the `owner:branch` head form
54 both forges take. The toast reads `opened pull #12 on octo/widgets`, and when
55 we hold a mirror of that upstream the imported pull is pushed on the stack so
56 the reader lands on what they just proposed. **A refusal keeps every buffer**
57 and names which half failed — `fork_timeout`, `origin_refused`,
58 `mirror_failed`, an edit reason, or "the commit landed but the pull did not
59 open". While such a workspace is open the status row says
60 `proposing to octo/widgets via your fork`, on every frame, so nobody has to
61 press `c` to find out where their change is going.
62
63 A repository the origin says you _may_ push to keeps the ordinary commit
64 dialog: on a mirror that is `editFiles` plus push-through, which is
65 `contribute`'s own `via: "direct"` path by another name.
docs/design/sections/6c-editing-commit-dialog.md added +29
@@ -0,0 +1,29 @@
1 ### 6c. Editing, and the commit dialog
2
3 `e` turns the active tab into a modeless editor: arrows/Home/End/PgUp/PgDn and
4 word jumps, shift-arrows to select, `ctrl+c`/`x`/`v` (which also mirror to
5 _your_ clipboard over OSC 52), `ctrl+z`/`ctrl+y`, `ctrl+f` find, `ctrl+r`
6 replace, horizontal scrolling with no soft wrap, tabs rendered at 4 and kept as
7 tabs. The status row reads `path · Ln 12, Col 4 · modified`.
8
9 Four rules are non-negotiable because this is attached to a git host: CRLF, a
10 BOM and the presence or absence of a trailing newline round-trip exactly;
11 nothing is normalised silently. Past 1 MB or 50k lines the buffer opens
12 read-only and says which, rather than being slow.
13
14 `c` (or `ctrl+s` from inside the buffer) opens the commit dialog. It lists
15 **every** change the workspace is holding — each modified tab and each pending
16 deletion, ticked, marked `+` added, `~` edited, `-` deleted — then asks the
17 three questions `editFiles` takes: message (subject, optional body), target
18 (`current branch` or `new branch`, defaulting to **new**, named
19 `<you>/edit-<file>`), and `[ ] open a pull request` with the title prefilled
20 from the subject. One call: no half-finished state (a branch with no commit, a
21 commit with no pull) can be invented. On success the workspace follows the
22 commit — the ref pill becomes the new branch and every tab is re-read from it.
23 **A refused commit keeps every buffer**, and says why on the dialog: a
24 protected branch, a name git will not take, an origin that said no.
25
26 Where the change has nowhere to go — a reader without write access, a live
27 browse of a repository nobody has offered you a route into — `e`, `c`, `n` and
28 `D` say so instead of opening something that could never land. Where it has a
29 route, they open the proposal dialog instead; §6c·1 is that route.
docs/design/sections/6c-editor.md added +100
@@ -0,0 +1,100 @@
1 ### 6c. The editor
2
3 `GET /:owner/:name/edit/:ref/*path` is a `<textarea>` in a `<form>`, and one
4 rule governs it: **a refusal never costs you your typing.** A protected
5 branch, a file over the size cap, a branch name git will not take, an origin
6 that said no — each re-renders the same page with the text, the message, the
7 branch name and the pull-request fields exactly as they were, and the reason
8 above them. `test/web-editor.test.ts` asserts that, not just the happy path.
9
10 The commit box is one submit, because `editFiles` is one call: message,
11 target (`current branch` / `new branch <name>`, defaulting to
12 `alice/edit-<file>`), and optionally a pull request from the new branch back
13 to where you started. Where committing straight to the ref is not on offer at
14 all — a protected default, or a ref that is not a branch — the page says so on
15 the disabled radio rather than letting somebody find out after typing.
16
17 **The highlighted mirror.** Under the textarea sits a
18 `<pre id="editor-mirror">` holding the same text, syntax-coloured; the
19 textarea on top of it has transparent text and a visible caret. They share one grid cell and one set
20 of metrics — font, size, line height, padding, tab size — because a single
21 divergence puts the caret in the wrong place, and the _height ceiling lives on
22 `.editor-wrap`_ so the gutter, the mirror and the textarea are always the same
23 height and scroll as one. The mirror is rendered by the server for the first
24 paint, so there is no flash of uncoloured code, and kept in step by
25 `window.forgeHighlight`, which is `web/highlight.ts` itself bundled by
26 `Bun.build` at first use and served from `/assets/highlight-<hash>.js`,
27 immutable. That asset is the one thing that relaxes the script CSP — from
28 "this page's nonce" to "this page's nonce, or a file from this origin" — and
29 only the editor page asks for it.
30
31 An edit re-scans from the first changed line and stops as soon as the state
32 entering an unchanged line matches what it was before, so typing costs one
33 line's work; the DOM is patched line by line rather than rebuilt. Tab inserts,
34 Enter keeps your indentation, brackets and quotes close themselves (and wrap a
35 selection), `⌘/Ctrl+S` submits the commit form, and the current line is
36 marked. `⌘/Ctrl+F` is left to the browser on purpose: the mirror holds real
37 text, so the page's own find lands on the line you were looking for.
38
39 **It degrades, in that order.** Over 200 KB or over 10,000 lines the server
40 sends no mirror and no bundle — a file that size is not hand-edited in a
41 browser, and a slow editor is worse than an unhighlighted one. If the bundle
42 fails to build or never loads, the page keeps the plain textarea, because the
43 textarea's own text only turns transparent once the mirror is live. With no
44 JavaScript at all it is a `<textarea>` in a `<form>`, which is what it was
45 before any of this. The Preview tab is offered on Markdown only, and renders
46 through the same `/preview` fragment the server will use for the file.
47
48 **Origins are web-only.** Connecting, syncing and browsing an origin live on the web pages (`/origins`) and in migrate; the terminal has no origins screen. On a mirrored repo's home `y` syncs the mirror and `P` pins it — `p` has meant _pulls_ on that
49 screen since before pins existed, so the toggle takes the shifted key there
50 and the plain `p` everywhere a repo is a _row_ (the dashboard, explore).
51
52 The connect chooser is ordered by what actually gets somebody connected:
53 **Personal access token — recommended** first (paste a string, no setup at
54 all), then **GitHub, one click** (needs a one-time OAuth app setup) and
55 **Forgejo / Gitea, one click** (needs an app registration on the instance).
56 Each row carries that condition on its own line rather than failing later
57 with an error about an environment variable.
58
59 **The where strip.** Every repository screen carries one line directly under
60 its title, naming the three places a repository can be and marking which one
61 the bytes on screen came from:
62
63 ```
64 ● codeberg.org · ○ workbench · ○ this machine
65 reading live from codeberg.org — read-only · m mirror into your workbench
66
67 ● codeberg.org · ● workbench (synced 3m ago) · ◆ this machine
68
69 ● workbench · ○ this machine
70 ```
71
72 The first is a live browse (and only a live browse gets the second, muted
73 banner line); the second is a mirror that is also pinned; the third is a
74 native repository, which has no origin and therefore no first place. The dot
75 is the grammar — **accent** is the place being read from, **success** is a
76 place that has this repository, **muted** is a place that does not:
77
78 | glyph | means |
79 | ----- | ---------------------------------------------------------- |
80 | `●` | this place has the repository (accent = reading from here) |
81 | `○` | this place does not have it |
82 | `◆` | kept on your machine (pinned) |
83 | `▲` | this came from the origin — an imported author or activity |
84
85 **Read-only means read-only.** A screen over a live source has no write keys
86 at all — no `c` comment, no `x`/`o` state, no `l` labels, no `m` merge, no
87 `,` settings, no `F` fork — because `capabilities.write` is false and the
88 source has no method that could write. In their place the help bar shows
89 `m mirror` and `O open on origin` — first, ahead of the navigation keys,
90 because at 80 columns the bar has room for about six bindings and those two
91 are the only things you can actually do here. The banner carries the long
92 wording; `w` opens the workbench copy when one already exists.
93
94 **The mirror card.** `m` opens a checklist over whatever screen you were on:
95 `creating → fetching → labels → issues → pulls → comments`, a spinner on the
96 stage in progress with the job's own words beside it ("42 issues"), and the
97 elapsed time. `esc` hides it and the mirror keeps running, toasting when it
98 lands; on `done` the live screen underneath is replaced in place by the same
99 screen over the local source, and the strip flips to `● workbench`; on
100 `failed` the card shows the scrubbed reason and `r` retries.
docs/design/sections/6d-forge-editor.md added +33
@@ -0,0 +1,33 @@
1 ### 6d. `$FORGE_EDITOR` — the operator's own editor, over a pty
2
3 `E` suspends the UI and hands the terminal to `$FORGE_EDITOR` on a real pty.
4 **Read this before enabling it:** the editor runs on the forge host as the
5 forge user, and nvim's `:!sh`, `:terminal` and a sourced `init.lua` are all
6 arbitrary code execution. CVE-2019-12735 was RCE in Neovim from merely opening
7 a file with a hostile modeline, which is the exact shape of a host whose job is
8 displaying files other people wrote.
9
10 It is coherent under one framing only: **this is the operator's own single-user
11 workbench, and the editor is their shell reached through the forge.** So it is
12 opt-in and absent otherwise — with `FORGE_EDITOR` unset there is no spawn, no
13 temp file and one line of explanation; the name is resolved once with
14 `Bun.which` and spawned as `[bin, file]` **argv, never a shell** (a name with
15 whitespace in it is refused rather than tokenized); and one handoff at a time
16 per session, because nested suspends are the wedge behind every "my TUI hung
17 after I shelled out" report. Nothing in that path writes to a repository: what
18 comes back is spliced into the tab's own buffer — one undoable edit, and a
19 modified tab like any other — and reaches git only through `c` and `editFiles`,
20 the one way anything does. `E` is the escape hatch rather than the tool, so it
21 sits last in the binding list and falls off the end of the help bar.
22
23 Resume is unconditional and state-independent — the child may have crashed, so
24 "undo what we think it did" is exactly the reasoning that leaves a broken
25 terminal. Two fixes beyond re-entering the alt screen, both measured against
26 real nvim: `ESC[0 q` because it exits leaving a steady block and never resets
27 the cursor shape, and `ESC[>0u` to pop kitty keyboard flags it pushes and does
28 not. The input decoder is rebuilt on resume so the Primary DA reply that
29 arrives _after_ the child is gone lands nowhere.
30
31 **Gap:** a launch should leave an outbox event (invariant 5), and appending one
32 from an adapter would break the rule that only `actions/` does. It is a log
33 line for now; the action belongs beside `actions/contents.ts`.
docs/design/sections/6e-1-reviews-merge-gate.md added +47
@@ -0,0 +1,47 @@
1 ### 6e·1. Reviews, threads, and the merge gate
2
3 A pull is judged in three places, and each says one thing.
4
5 **The verdict (`R`).** A card with three radios and an optional note —
6 `( ) approve ( ) request changes ( ) comment`, `ctrl+d` submits. Approve is
7 **absent** when the viewer wrote the change, because `submitReview` refuses it
8 (`self_review`) and a disabled control would only be a slower way to be told
9 no. A verdict renders in the conversation as a timeline item with a state chip
10 (success / danger / muted), and it is recorded against the head it was passed
11 on — so a push dismisses it and the item wears `before the latest push` in
12 muted rather than quietly still counting.
13
14 **The gate.** The merge box grows a second line saying where the verdicts
15 stand: `2 approvals · changes requested by bob`, and `N dismissed by a push`
16 when a push has cleared some. When the reviews do not let it land the box
17 reads `review` in `attn` and `m` says the reason out loud rather than doing
18 nothing:
19
20 ```
21 ╭─ Merge ──────────────────────────────────────────────────────────╮
22 │ review Needs an approval of this head before it can merge │
23 │ no approvals yet │
24 ╰────────────────────────────────────── fix › main · 1 file +1 -1 ─╯
25 ```
26
27 That is a rendering of `reviewGate` (`core/pulls.ts`) and nothing more: an
28 outstanding request for changes blocks whatever the setting says, and
29 `require a review before merging` (repo settings, `R`) additionally demands an
30 approval of the current head. The refusal is mechanical in `mergePull`, which
31 reads the gate from the live head — a check computed earlier and handed down
32 is a check that can be skipped.
33
34 **Threads.** Review comments sharing one anchor are one conversation. In the
35 files tab the section header reads `3 threads · 1 unresolved`; `x` settles or
36 reopens the thread the cursor is standing on (a writer, or whoever raised it);
37 `n`/`p` walk the unsettled ones while the cursor is inside one, and go back to
38 walking hunks when it is not. A settled thread collapses to a single dim line
39 — `✓ resolved by alice · 2h · enter to expand` — because the point of settling
40 something is to stop looking at it, and `enter` opens the record back up
41 because the point of a record is that it is still there. Standing on the diff
42 line a thread hangs from counts as standing on the thread: that is what a
43 reader means by "this one".
44
45 A pull list row wears the same verdict in one tabular column — `✓` approved,
46 `✗` changes requested, `·` nobody has looked — read for the whole page in one
47 grouped query, never one per row.
docs/design/sections/6f-realtime.md added +6
@@ -0,0 +1,6 @@
1 ### 6f. Realtime
2
3 Dashboard, issue and pull lists, the repo home, and the issue and pull screens
4 all subscribe to the outbox for as long as they are on the stack, through one
5 helper (`live()` in `screens/common.ts`). Popping the screen unsubscribes it —
6 there is no lifecycle to get wrong. A burst is coalesced into one refresh.
docs/design/sections/6g-terminal-apps-runs-crew.md added +29
@@ -0,0 +1,29 @@
1 ### 6g. Apps, runs and the crew, where the terminal still shows them
2
3 The terminal's half of §5c is deliberately small: running an app and
4 managing the crew are the studio's (`docs/STUDIO.md`), and the terminal has
5 no apps, app, runs, run or crew screen and no palette entry for one. What
6 remains is where the work is reviewed:
7
8 - **Pull** — a preview line when the repository is an app (`O` opens it,
9 `P` opens production beside it: comparing the two is the review), a
10 checks row in the merge box and a _waiting on checks_ state with the refusal
11 in words on `m`, `a` to assign (nobody, people, then the crew with the bot
12 glyph on a Nerd Font), and a Crew tab of the agent runs about it.
13 - **`T` on a pull's preview** suspends the UI and runs the app's `tty` on
14 the same pty — one connection, two programs in turn, exactly as
15 `$FORGE_EDITOR` runs — and the UI returns when it exits. Every refusal
16 (not running, no `tty`, private to a guest) is a toast in the same words
17 the ssh front door uses.
18 - **Issue** — `a` to assign; a Crew card when an agent has runs, `tab` moves
19 focus to it.
20 - **A run** is a row (`screens/runlist.ts`): state dot and word, who, why,
21 the summary. `enter` on one hands over its web page,
22 `/:owner/:name/runs/:id`, where the live log, cancel and steer are — as a
23 link when the forge knows its public URL, as the path otherwise.
24 - **Settings** — the App tab (enable with slug, access and preview data; edit;
25 `D` to stop running as an app behind a confirm), `C` for require checks on
26 General, the Crew tab (`a` adds an agent from the forge's, `d` removes).
27
28 A guest is told so in words; nothing here is a way around the actions'
29 answers.
docs/design/sections/7-security-boundaries.md added +22
@@ -0,0 +1,22 @@
1 ## 7. Two rules that are security boundaries
2
3 **Label colors.** Inline `style=""` is blocked by the CSP — nonces apply to
4 elements, not attributes. A page therefore collects the label colors it will
5 render and emits one nonce'd rule per color:
6
7 ```css
8 .lc-d73a4a {
9 --label: #d73a4a;
10 }
11 ```
12
13 and the static sheet derives the chip from it with `color-mix`, so one stored
14 hex reads correctly in all six themes. `labelCss()` re-validates
15 `/^[0-9a-f]{6}$/` immediately before embedding. That check is the boundary —
16 treat it like `assertBatchSafe`, not like a nicety.
17
18 **The confirm page.** Every destructive button is a link to `/-/confirm?to=…`.
19 That page derives its own title, detail and typed-phrase requirement from a
20 table of known destructive routes, and 404s on anything else. The wording never
21 comes from the link, so a mailed URL cannot put "Continue" on a button that
22 deletes a repository.
docs/design/sections/8-checklist.md added +21
@@ -0,0 +1,21 @@
1 ## 8. Checklist before you call a screen done
2
3 1. Every divider is exactly 1px. The only 2px things are the active-tab
4 underline and the focus ring.
5 2. Every number that lines up is tabular.
6 3. Icons sit in a fixed 16px slot; the text baseline does not move when one
7 appears.
8 4. Secondary actions are in the DOM at `opacity: 0` and revealed on hover —
9 never `display: none` → `flex`. A settings row is the exception: its
10 control is the point of the row, so it sits in `.row-fields`, visible at
11 rest, and the list wears `.setting-list` (see §5d).
12 5. Exactly one accent-colored thing, and it is the action.
13 6. The empty state has exactly one button.
14 7. Nothing on the page needs JavaScript to work.
15 8. It survives 200% zoom and a 320px viewport with no horizontal body scroll —
16 diffs and code scroll inside their own card.
17 9. Nothing inside a linked row is itself a link.
18 10. Any control that only works with a script carries `js-only`, so a page
19 without JavaScript never shows a dead button.
20 11. Every token count sits beside a byte size, a cost or a percentage, and
21 goes through `tokenCount()` — never a hand-written `k`.
plugins/claude-code/README.md +1 −1
@@ -1,7 +1,7 @@
11 # forge for Claude Code
22
33 Set `FORGE_URL` (the forge's address, no trailing slash) and `FORGE_TOKEN`
4 (an `rw` token; `ro` reads only), then add this directory as a plugin
4 (an `rw` token; `ro` reads only; make one at `/settings/tokens` on the forge, which also shows this line filled in), then add this directory as a plugin
55 (`claude --plugin-dir plugins/claude-code`). It registers the forge's MCP
66 server and a `/forge` command: `tell`, `status`, `decide`, `plan`.
77
plugins/opencode/README.md +6 −2
@@ -1,8 +1,12 @@
11 # forge for OpenCode
22
33 Copy `forge.ts` into `.opencode/plugin/` (or list this package under `plugin`
4 in `opencode.json`), and set `FORGE_URL` and `FORGE_TOKEN`. It registers the
5 forge's MCP server and the `forge` command: `tell`, `status`, `decide`.
4 in `opencode.json`), and set `FORGE_URL` and `FORGE_TOKEN` (make the token at `/settings/tokens` on the forge, which shows the line with its own address filled in):
5 `mkdir -p .opencode/plugin && cp plugins/opencode/forge.ts .opencode/plugin/ && FORGE_URL=<url> FORGE_TOKEN=<token> opencode`. It registers the
6 forge's MCP server and the `forge` command: `tell`, `status`, `decide`, `plan`.
7 `/forge plan` shows the planner's next wave (the first wave-proposal row of `asks`);
8 `/forge plan approve`, `redirect <words>` or `later` steers it through `asks_proposal`,
9 applied only after you say yes. Only the owner may act on a proposal.
610 Code Mode can also read `GET /contract/openapi.json`.
711
812 `test/plugins.test.ts` fails when this plugin names an MCP tool the forge does not list, so a rename in `src/http/mcp.ts` cannot leave it behind.
plugins/opencode/forge.ts +3 −2
@@ -1,6 +1,6 @@
11 /**
22 * forge for OpenCode: registers the forge's MCP server and a `forge`
3 * command (tell, status, decide). Set FORGE_URL and FORGE_TOKEN.
3 * command (tell, status, decide, plan). Set FORGE_URL and FORGE_TOKEN.
44 * No logic lives here: the tools are the forge's own (`docs/MCP.md`).
55 */
66 import type { Plugin } from "@opencode-ai/plugin";
@@ -9,6 +9,7 @@ const COMMAND = `Use the forge MCP tools for: $ARGUMENTS
99 - tell <app> <words>: call \`tell\` with repo and text; pass context { page, run, commit, said }.
1010 - status: call \`now\` and \`asks\`; say in three sentences what runs and what waits on the person.
1111 - decide approve|redirect|decline: call \`asks\`; approve -> \`asks_act\` ship, decline -> \`asks_act\` close, redirect -> \`say\`. Plan first, apply (dryRun false) only after the person says yes.
12 - plan [approve|redirect <words>|later]: call \`asks\`; show the first wave-proposal row (the planner's next wave) in a few lines. approve|redirect|later -> \`asks_proposal\` with that row's id and verb (redirect carries the words as \`words\`). Say what it will do and apply only after the person says yes.
1213 Never merge: a person lands changes.`;
1314
1415 export const Forge: Plugin = async () => ({
@@ -26,7 +27,7 @@ export const Forge: Plugin = async () => ({
2627 };
2728 config["command"] = {
2829 ...config["command"],
29 forge: { description: "Tell, status or decide on your forge", template: COMMAND },
30 forge: { description: "Tell, status, decide or plan on your forge", template: COMMAND },
3031 };
3132 },
3233 });
scripts/design-lint.ts +19 −4
@@ -33,7 +33,10 @@
3333 * A red names the file:line, the literal and what to use instead, so one pass
3434 * fixes it; run `bun scripts/design-lint.ts` before pushing. A new class is named
3535 * in its own `docs/design/areas/<area>.md` rather than in DESIGN.md, which
36 * every pull would otherwise edit (#4063).
36 * every pull would otherwise edit (#4063). DESIGN.md itself is a spine that
37 * links one file per section under `docs/design/sections/` (#5937); `designText`
38 * reads the spine and those files in its order, so the § numbers mean what
39 * they did when it was one file.
3740 *
3841 * Known gaps, so nobody mistakes the gate for more than it is: colours built
3942 * in JS strings other than the forms above, `oklch()`,
@@ -42,7 +45,7 @@
4245 *
4346 * The theme palettes (`src/design/themes.ts`) are where colours live and are
4447 * not scanned. Plain data in, plain data out: `scan` takes files, `compare`
45 * takes the baseline, a scan and the text of DESIGN.md.
48 * takes the baseline, a scan and the text of DESIGN.md with its sections.
4649 */
4750
4851 import { readdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -230,6 +233,17 @@ export function documentedClasses(design: string, areas: readonly string[] = [])
230233 return [...new Set([...namedIn(section(design, "5.")), ...areas.flatMap(namedIn)])].sort();
231234 }
232235
236 /** The section files the spine links, in its order: `](design/sections/<file>.md)`. */
237 export function sectionLinks(spine: string): string[] {
238 return [...spine.matchAll(/\]\(design\/sections\/([a-z0-9-]+\.md)\)/g)].map((m) => m[1]!);
239 }
240
241 /** DESIGN.md as one text: the spine, then each section it links, in order (#5937). */
242 export function designText(root: string): string {
243 const spine = readFileSync(join(root, DESIGN), "utf8");
244 return [spine, ...sectionLinks(spine).map((f) => readFileSync(join(root, SECTIONS, f), "utf8"))].join("\n");
245 }
246
233247 /** The area files under docs/design/areas/: each is wholly vocabulary, one file per component area (#4063). */
234248 export function areaFiles(root: string): string[] {
235249 try {
@@ -289,13 +303,14 @@ export function compare(base: Baseline, now: Scan, design: string, areas: readon
289303 }
290304 const defined = new Set(now.classes);
291305 for (const k of registeredClasses(design)) {
292 if (!defined.has(k)) out.push(`.${k}: no stylesheet defines it any more — strike it from docs/DESIGN.md §5d`);
306 if (!defined.has(k)) out.push(`.${k}: no stylesheet defines it any more — strike it from §5d, docs/design/sections/5d-page-local-classes.md`);
293307 }
294308 return out;
295309 }
296310
297311 const BASELINE = "docs/design/baseline.json";
298312 const DESIGN = "docs/DESIGN.md";
313 const SECTIONS = "docs/design/sections";
299314 const AREAS = "docs/design/areas";
300315
301316 if (import.meta.main) {
@@ -307,7 +322,7 @@ if (import.meta.main) {
307322 console.log(`wrote ${BASELINE}`);
308323 } else {
309324 const base: Baseline = JSON.parse(readFileSync(join(root, BASELINE), "utf8"));
310 const problems = compare(base, now, readFileSync(join(root, DESIGN), "utf8"), areaFiles(root));
325 const problems = compare(base, now, designText(root), areaFiles(root));
311326 for (const p of problems) console.error(p);
312327 if (problems.length) process.exit(1);
313328 console.log("design: no colour, size or component added outside the system");
scripts/home-eval.ts added +68
@@ -0,0 +1,68 @@
1 /**
2 * `bun scripts/home-eval.ts <base-url>` scores the owner's home against
3 * ground truth (#5805), the deterministic half of #5735's loop: it reads `/`
4 * as text (`pageText`, #5765), asks the forge's own API for the five facts
5 * that mattered, and prints each as `stated`, `missing` or `wrong` with the
6 * page's words beside it, then coverage, errors, characters and fetch time.
7 * `FORGE_COOKIE` is sent as the cookie and `FORGE_TOKEN` as a bearer token;
8 * neither is printed. Exits 1 when the page or the API will not answer.
9 */
10 import { pageText } from "../src/web/page_text.ts";
11 import { coverage, errors, scoreHome, type Truth } from "../src/system/home_eval.ts";
12
13 const base = process.argv[2]?.replace(/\/+$/, "");
14 if (!base || !/^https?:\/\//i.test(base)) {
15 console.error("usage: bun scripts/home-eval.ts <http(s)://forge>");
16 process.exit(2);
17 }
18 const cookie = process.env.FORGE_COOKIE;
19 const token = process.env.FORGE_TOKEN;
20 const headers: Record<string, string> = { ...(cookie ? { cookie } : {}), ...(token ? { authorization: `Bearer ${token}` } : {}) };
21 const DAY = 86_400_000;
22
23 async function get(path: string): Promise<any> {
24 const res = await fetch(`${base}${path}`, { headers, redirect: "manual", signal: AbortSignal.timeout(15_000) });
25 if (res.status !== 200) throw new Error(`${path} answered ${res.status}`);
26 return res.json();
27 }
28
29 async function truth(): Promise<Truth> {
30 const home = await get("/api/v1/telemetry/home");
31 const repos: { ownerName: string; name: string; archivedAt?: string | null }[] = [];
32 for (let cursor: string | null = null, page = 0; page < 10; page++) {
33 const r: { items: typeof repos; next_cursor: string | number | null } = await get(`/api/v1/repos?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`);
34 repos.push(...r.items);
35 if (r.next_cursor === null) break;
36 cursor = String(r.next_cursor);
37 }
38 const live = repos.filter((r) => !r.archivedAt).map((r) => `${r.ownerName}/${r.name}`);
39 const quiet: string[] = [];
40 for (let i = 0; i < live.length; i += 8) {
41 await Promise.all(
42 live.slice(i, i + 8).map(async (full) => {
43 const log: { date: string }[] = await get(`/api/v1/repos/${full}/commits?limit=1`);
44 if (log[0] !== undefined && Date.now() - Date.parse(log[0].date) > 3 * DAY) quiet.push(full);
45 }),
46 );
47 }
48 return { ...home, repos: live, quiet: quiet.sort() };
49 }
50
51 try {
52 const started = performance.now();
53 const res = await fetch(`${base}/`, { headers, redirect: "manual", signal: AbortSignal.timeout(15_000) });
54 const html = await res.text();
55 const ms = Math.round(performance.now() - started);
56 if (res.status !== 200) throw new Error(`/ answered ${res.status}`);
57 const text = pageText(html);
58 const facts = scoreHome(text, await truth());
59 for (const f of facts) {
60 console.log(`${f.verdict.padEnd(7)} ${f.label}`);
61 console.log(` page: ${f.words === "" ? "—" : `“${f.words}”`}`);
62 console.log(` forge: ${f.truth}`);
63 }
64 console.log(`coverage ${coverage(facts)} of 5 · errors ${errors(facts)} · chars ${text.length} · fetched in ${ms} ms`);
65 } catch (e) {
66 console.error(e instanceof Error ? e.message : String(e));
67 process.exit(1);
68 }
scripts/home-read.ts added +26
@@ -0,0 +1,26 @@
1 /**
2 * `bun scripts/home-read.ts <url>` prints a page as the eye reads it, then
3 * `chars N · words N · fetched in N ms` (#5765): step 1 of the home cold read
4 * (#5735), so every read starts from the same text. `FORGE_COOKIE`, when set,
5 * is sent as the cookie and never printed. Exits 1 on a non-200 status.
6 */
7 import { pageText } from "../src/web/page_text.ts";
8
9 const url = process.argv[2];
10 if (!url || !/^https?:\/\//i.test(url)) {
11 console.error("usage: bun scripts/home-read.ts <http(s)://url>");
12 process.exit(2);
13 }
14 const cookie = process.env.FORGE_COOKIE;
15 const started = performance.now();
16 const res = await fetch(url, { headers: cookie ? { cookie } : {}, redirect: "manual", signal: AbortSignal.timeout(15_000) });
17 const html = await res.text();
18 const ms = Math.round(performance.now() - started);
19 if (res.status !== 200) {
20 console.error(`${url} answered ${res.status}`);
21 process.exit(1);
22 }
23 const text = pageText(html);
24 const words = text.split(/\s+/).filter(Boolean).length;
25 console.log(text);
26 console.log(`chars ${text.length} · words ${words} · fetched in ${ms} ms`);
scripts/hunt.ts added +16
@@ -0,0 +1,16 @@
1 /**
2 * `bun scripts/hunt.ts <https-origin>`: run the hunters' detectors (GET only)
3 * against one app and print the findings as JSON. Exit 1 when there are any.
4 * Never run on a person's machine in a loop: it is one pass, then it ends.
5 */
6
7 import { huntTarget } from "../src/hunt/hunt.ts";
8
9 const target = process.argv[2];
10 if (!target || !/^https?:\/\//.test(target)) {
11 console.error("usage: bun scripts/hunt.ts <origin>");
12 process.exit(2);
13 }
14 const report = await huntTarget(target.replace(/\/$/, ""));
15 console.log(JSON.stringify(report, null, 2));
16 process.exit(report.findings.length === 0 ? 0 : 1);
scripts/mcp-tools.ts added +81
@@ -0,0 +1,81 @@
1 /**
2 * Writes the MCP tools' generated files from `src/http/mcp/tools/*.ts` (#5924):
3 *
4 * - `src/http/mcp/tools/index.ts`: one sorted line per tool file, so a pull
5 * that adds a tool adds one line and never edits another pull's.
6 * - the `## Tools` table in `docs/MCP.md`, between its `tools:begin` and
7 * `tools:end` markers, from each tool's `doc` and `writes`.
8 *
9 * bun scripts/mcp-tools.ts write both
10 * bun scripts/mcp-tools.ts --check exit 1, naming the file, when either is stale
11 *
12 * `test/mcp-tools.test.ts` runs the check, so a pull that adds a tool file
13 * without running this goes red with the command to run.
14 */
15 import { readdirSync, readFileSync, writeFileSync } from "node:fs";
16 import { join } from "node:path";
17
18 const ROOT = join(import.meta.dir, "..");
19 const DIR = join(ROOT, "src/http/mcp/tools");
20 const INDEX = join(DIR, "index.ts");
21 const DOC = join(ROOT, "docs/MCP.md");
22 const BEGIN = "<!-- tools:begin: generated by `bun scripts/mcp-tools.ts` from each tool's `doc` -->";
23 const END = "<!-- tools:end -->";
24
25 /** The tool files, by name: every `<name>.ts` here but the index. */
26 export function toolFiles(dir = DIR): string[] {
27 return readdirSync(dir)
28 .filter((f) => /^[a-z][a-z0-9_]*\.ts$/.test(f) && f !== "index.ts")
29 .map((f) => f.slice(0, -3))
30 .sort();
31 }
32
33 export function indexText(names: readonly string[]): string {
34 return [
35 "// Generated by `bun scripts/mcp-tools.ts` from the files beside it; do not edit.",
36 "// One line per tool, sorted: a new tool is a new file and one new line here.",
37 ...names.map((n) => `export { tool as ${n} } from "./${n}.ts";`),
38 "",
39 ].join("\n");
40 }
41
42 type Documented = { readonly name: string; readonly doc?: string; readonly writes: boolean };
43
44 export function tableText(tools: readonly Documented[]): string {
45 const rows = [...tools]
46 .filter((t) => t.doc !== undefined)
47 .sort((a, b) => a.name.localeCompare(b.name))
48 .map((t) => `| \`${t.name}\` | ${t.doc} | ${t.writes ? "yes" : ""} |`);
49 return [BEGIN, "", "| tool | does | writes |", "| ---- | ---- | ------ |", ...rows, "", END].join("\n");
50 }
51
52 /** docs/MCP.md with its table replaced by `table`. */
53 export function withTable(md: string, table: string): string {
54 const from = md.indexOf(BEGIN);
55 const to = md.indexOf(END);
56 if (from < 0 || to < from) throw new Error(`docs/MCP.md has no ${BEGIN} … ${END} markers`);
57 return md.slice(0, from) + table + md.slice(to + END.length);
58 }
59
60 if (import.meta.main) {
61 const check = process.argv.includes("--check");
62 const stale: string[] = [];
63 const index = indexText(toolFiles());
64 if (readFileSync(INDEX, "utf8") !== index) {
65 stale.push("src/http/mcp/tools/index.ts");
66 if (!check) writeFileSync(INDEX, index);
67 }
68 // After the index is current, so a new file's row is in the table.
69 const { TOOLS } = await import("../src/http/mcp/tools.ts");
70 const md = readFileSync(DOC, "utf8");
71 const doc = withTable(md, tableText(TOOLS));
72 if (md !== doc) {
73 stale.push("docs/MCP.md");
74 if (!check) writeFileSync(DOC, doc);
75 }
76 if (check && stale.length > 0) {
77 console.error(`stale: ${stale.join(", ")}; run \`bun scripts/mcp-tools.ts\``);
78 process.exit(1);
79 }
80 if (!check) console.log(stale.length > 0 ? `wrote ${stale.join(", ")}` : "current");
81 }
scripts/openapi-routes.ts added +45
@@ -0,0 +1,45 @@
1 /**
2 * Writes `src/contract/openapi/routes/index.ts` from the route files beside
3 * it (#5936): one sorted line per file, so a pull that describes a route adds
4 * one file and one line, and never edits another pull's.
5 *
6 * bun scripts/openapi-routes.ts write it
7 * bun scripts/openapi-routes.ts --check exit 1 when it is stale
8 *
9 * `test/openapi-routes.test.ts` runs the same comparison, so a pull that adds
10 * a route file without running this goes red with the command to run.
11 */
12 import { readdirSync, readFileSync, writeFileSync } from "node:fs";
13 import { join } from "node:path";
14
15 const DIR = join(import.meta.dir, "..", "src/contract/openapi/routes");
16 const INDEX = join(DIR, "index.ts");
17
18 /** The route files, by name: every `<operationId>.ts` here but the index. */
19 export function routeFiles(dir = DIR): string[] {
20 return readdirSync(dir)
21 .filter((f) => /^[a-z][A-Za-z0-9]*\.ts$/.test(f) && f !== "index.ts")
22 .map((f) => f.slice(0, -3))
23 .sort();
24 }
25
26 export function indexText(names: readonly string[]): string {
27 return [
28 "// Generated by `bun scripts/openapi-routes.ts` from the files beside it; do not edit.",
29 "// One line per route, sorted: a new route is a new file and one new line here.",
30 ...names.map((n) => `export { route as ${n} } from "./${n}.ts";`),
31 "",
32 ].join("\n");
33 }
34
35 if (import.meta.main) {
36 const check = process.argv.includes("--check");
37 const index = indexText(routeFiles());
38 const current = readFileSync(INDEX, "utf8") === index;
39 if (check && !current) {
40 console.error("stale: src/contract/openapi/routes/index.ts; run `bun scripts/openapi-routes.ts`");
41 process.exit(1);
42 }
43 if (!check && !current) writeFileSync(INDEX, index);
44 if (!check) console.log(current ? "current" : "wrote src/contract/openapi/routes/index.ts");
45 }
scripts/shards.ts +3 −2
@@ -445,7 +445,8 @@ export function sliceFiles(
445445
446446 /**
447447 * Parses `--shard N/M` (or the same shape from env). Empty / undefined means
448 * no matrix slice — run every named file.
448 * no matrix slice — run every named file. Four digits a side: the gate
449 * passed 999 files, and a slice per file must still be nameable.
449450 */
450451 export function parseShardSpec(
451452 spec: string | undefined,
@@ -454,7 +455,7 @@ export function parseShardSpec(
454455 | { ok: true; none: true }
455456 | { ok: false; error: string } {
456457 if (spec === undefined || spec.trim() === "") return { ok: true, none: true };
457 const m = /^([1-9][0-9]{0,2})\/([1-9][0-9]{0,2})$/.exec(spec.trim());
458 const m = /^([1-9][0-9]{0,3})\/([1-9][0-9]{0,3})$/.exec(spec.trim());
458459 if (!m)
459460 return {
460461 ok: false,
src/actions/admin_limits_words.ts added +10
@@ -0,0 +1,10 @@
1 /**
2 * The quota and usage sentences an admin reads (#5621): said once here and
3 * read by the web pages and the terminal screens alike, so they cannot drift.
4 */
5
6 /** A quota change was refused because a value was not a positive whole number. */
7 export const QUOTA_INVALID = "A quota is a positive whole number, or empty for no limit.";
8
9 /** Someone who is not a forge admin asked for the usage report. */
10 export const USAGE_ADMIN_ONLY = "Usage is read by a forge admin.";
src/actions/admin_words.ts added +14
@@ -0,0 +1,14 @@
1 /**
2 * What a forge admin's doors say when they refuse (#5561): one place, so
3 * the API, MCP and the OpenAPI contract read the same sentence and cannot
4 * drift when one door is edited.
5 */
6
7 export const ADMIN_WORDS = {
8 /** account_suspend / remove: the owner acting on themselves, an admin, or an agent. */
9 selfSuspend: "an admin cannot suspend or remove themselves, another admin, or an agent",
10 /** The crew scorecard, asked for by anyone but a forge admin. */
11 scorecard: "the crew's scorecard is a forge admin's to read",
12 /** Setting the front page's picks, asked for by anyone but a site admin. */
13 frontPage: "the front page is a site admin's to set",
14 } as const;
src/actions/app_notes.ts +11 −3
@@ -9,12 +9,15 @@ import type { App } from "../app.ts";
99 import { banVisitor, bannedNotes, unbanVisitor, markSender, getNote, hideNote, insertNote, isBanned, notesOf, notesOfApp, type AppNote } from "../core/app_notes.ts";
1010 import type { AppRecord } from "../core/apps.ts";
1111 import { createLabel, getIssue, getLabel } from "../core/issues.ts";
12 import { mergedPullClosing } from "../core/pulls.ts";
13 import { releaseName, releaseOfPull } from "../release/record.ts";
1214 import { RateLimiter } from "../core/ratelimit.ts";
1315 import { canAdmin, type Repo } from "../core/repos.ts";
1416 import { plainText } from "../core/reports.ts";
1517 import { workingAgentRuns } from "../core/runs.ts";
1618 import { getUserById, isActive, type User } from "../core/users.ts";
1719 import { unadoptedAmong } from "../crew/direct.ts";
20 import { NOTE_EMPTY } from "../apps/note_words.ts";
1821 import { err, ok, type Result } from "../kernel/result.ts";
1922 import { openIssueThrough, setIssueLabelsThrough, setIssueStateThrough } from "./issues.ts";
2023
@@ -101,8 +104,13 @@ export function statusOf(app: App, repo: Repo, number: number): { status: NoteSt
101104 if (issue.state === "closed") {
102105 const when = (issue.closedAt ?? issue.updatedAt).slice(0, 10);
103106 // Only "done" is a promise kept; the other reasons say what they are.
104 if (issue.closeReason === "done" || issue.closeReason === null)
105 return { title: issue.title, status: { state: "shipped", label: `Shipped on ${when}` } };
107 if (issue.closeReason === "done" || issue.closeReason === null) {
108 const pull = mergedPullClosing(app.db, repo.id, number);
109 const release = pull === undefined ? undefined : releaseOfPull(app.db, repo.id, pull.number);
110 const label =
111 release !== undefined ? `Shipped in ${releaseName(release)}` : `Shipped on ${(pull?.mergedAt ?? issue.closedAt ?? issue.updatedAt).slice(0, 10)}`;
112 return { title: issue.title, status: { state: "shipped", label } };
113 }
106114 const label = issue.closeReason === "parked" ? "Set aside for now" : issue.closeReason === "split" ? "Split into smaller pieces" : "Closed without a change";
107115 return { title: issue.title, status: { state: "closed", label: `${label} (${when})` } };
108116 }
@@ -185,7 +193,7 @@ export async function sendNote(
185193 source: string,
186194 ): Promise<Result<NoteView, Refusal>> {
187195 const text = plainText(input.text).trim();
188 if (text === "") return err({ error: "empty", message: "Write a few words first." });
196 if (text === "") return err({ error: "empty", message: NOTE_EMPTY });
189197 if (text.length > TEXT_MAX) return err({ error: "too_long", message: "That is a bit long. Keep it under 2,000 characters." });
190198 if (isBanned(app.db, record.id, sender.key)) return err({ error: "banned", message: "Notes from here are paused." });
191199 if (filtered(text)) return err({ error: "filtered", message: "Please put that in other words." });
src/actions/ask_state_words.ts added +11
@@ -0,0 +1,11 @@
1 /**
2 * What the crew says about where an ask stands (#5619), said from one place
3 * so the asked and answers views read the same on the web and in the
4 * terminal. Plain strings: each caller escapes them as its surface does.
5 */
6
7 /** An ask the planner has not yet put on any issue, and nobody has replied to. */
8 export const NOT_PLACED_YET = "the planner has not placed it yet";
9
10 /** An ask whose issue has a run going and no answer yet. */
11 export const CREW_WORKING = "The crew is working on it.";
src/actions/asks_bulk.ts +4 −2
@@ -12,6 +12,7 @@ import type { App } from "../app.ts";
1212 import { listOperations, type Operation } from "../core/fleet_ops.ts";
1313 import type { User } from "../core/users.ts";
1414 import { err, ok, type Result } from "../kernel/result.ts";
15 import { NO_SUCH_OPERATION } from "./asks_words.ts";
1516 import { askTargetsFor } from "../web/studio/asks.ts";
1617 import {
1718 applyFleetIds,
@@ -23,6 +24,7 @@ import {
2324 type FleetError,
2425 type Plan,
2526 } from "./fleet.ts";
27 import { SIGN_IN_TO_ACT } from "./asks_words.ts";
2628
2729 /**
2830 * What a bulk action on asks may be: the fleet verb each one is. Decline is
@@ -59,7 +61,7 @@ function resolve(
5961 if (!actor)
6062 return err({
6163 code: "unauthorized",
62 message: "sign in to act on your asks",
64 message: SIGN_IN_TO_ACT,
6365 });
6466 const verb =
6567 typeof action === "string" && Object.hasOwn(ASK_ACTIONS, action)
@@ -190,6 +192,6 @@ export async function undoAsksBulk(
190192 ): Promise<Result<Operation, FleetError>> {
191193 const op = ownAsksOperation(app, actor, operationId);
192194 if (op === undefined)
193 return err({ code: "not_found", message: "no such operation here" });
195 return err({ code: "not_found", message: NO_SUCH_OPERATION });
194196 return undoFleetOp(app, actor, op.id);
195197 }
src/actions/asks_decide.ts +5 −3
@@ -14,7 +14,9 @@ import type { User } from "../core/users.ts";
1414 import { guardedHand, letDeciderHandle, undoHandled } from "../crew/handover.ts";
1515 import { err, ok, type Result } from "../kernel/result.ts";
1616 import { askTargetsFor } from "../web/studio/asks.ts";
17 import { NO_LONGER_ASKS } from "./asks_words.ts";
1718 import type { FleetError } from "./fleet.ts";
19 import { SIGN_IN_TO_ACT } from "./asks_words.ts";
1820
1921 export { HAND_COOLDOWN_MS } from "../crew/handover.ts";
2022
@@ -57,7 +59,7 @@ export async function decideAsk(
5759 item: unknown,
5860 now = Date.now(),
5961 ): Promise<Result<HandAnswer, FleetError>> {
60 if (!actor) return fail("unauthorized", "sign in to act on your asks");
62 if (!actor) return fail("unauthorized", SIGN_IN_TO_ACT);
6163 if (typeof item !== "string" || !ASK_ID.test(item))
6264 return fail("bad_action", "only a hand-over can be handed to the decider");
6365 if (app.config.decider === undefined)
@@ -68,7 +70,7 @@ export async function decideAsk(
6870 const issue = issueIds[0] === undefined ? undefined : getIssueById(app.db, issueIds[0]);
6971 const repo = issue === undefined ? undefined : getRepoById(app.db, issue.repoId);
7072 if (issue === undefined || repo === undefined)
71 return fail("not_found", "it no longer asks you");
73 return fail("not_found", NO_LONGER_ASKS);
7274 const handed = await guardedHand(app, issue.id, now, () =>
7375 letDeciderHandle(app, actor, repo, issue, repo.decisionsBy),
7476 );
@@ -86,7 +88,7 @@ export function undoDecideAsk(
8688 actor: User | undefined,
8789 decisionId: unknown,
8890 ): Result<HandAnswer, FleetError> {
89 if (!actor) return fail("unauthorized", "sign in to act on your asks");
91 if (!actor) return fail("unauthorized", SIGN_IN_TO_ACT);
9092 if (typeof decisionId !== "string" || decisionId === "")
9193 return fail("not_found", "no such decision");
9294 const undone = undoHandled(app, actor, decisionId);
src/actions/asks_words.ts added +18
@@ -0,0 +1,18 @@
1 /**
2 * What acting on asks says, said from one place (#5614): bulk decide,
3 * decide and proposals read it here, and an ask or a bulk operation whose
4 * subject is gone answers from here too, so the web, the API, MCP and the
5 * terminal word it the same.
6 */
7
8 /** Acting on an ask while signed out. */
9 export const SIGN_IN_TO_ACT = "sign in to act on your asks";
10
11 /** Deciding an ask that has moved on: it no longer waits on this person. */
12 export const NO_LONGER_ASKS = "it no longer asks you";
13
14 /** A bulk operation, or a fleet verb, this place does not know. */
15 export const NO_SUCH_OPERATION = "no such operation here";
16
17 /** A milestone that is not here, or not readable by the one asking. */
18 export const NO_SUCH_MILESTONE = "no such milestone here";
src/actions/board_words.ts added +14
@@ -0,0 +1,14 @@
1 /**
2 * The refusals a board save, a vote and a milestone watch answer with
3 * (#5645): one sentence each, said the same by the API and the MCP because
4 * both read it from here. Plain strings, no imports.
5 */
6
7 /** A board write refused for a reason its error code names. */
8 export const BOARD_NOT_SAVED = "that board could not be saved";
9
10 /** A vote refused for a reason its error code names. */
11 export const VOTE_NOT_RECORDED = "that vote could not be recorded";
12
13 /** An agent asked to watch a milestone; watching is a person's. */
14 export const MILESTONE_WATCH_PERSON_ONLY = "only a person watches a milestone";
src/actions/branch_words.ts added +14
@@ -0,0 +1,14 @@
1 /**
2 * A branch's sentences (#5713): making or deleting a branch reads the same
3 * from the branches page, the MCP and the terminal, so each is
4 * typed once and read from here.
5 */
6
7 /** A branch create refused for a reason with no sentence of its own. */
8 export const BRANCH_NOT_CREATED = "That branch was not created.";
9
10 /** A branch delete refused for a reason with no sentence of its own. */
11 export const BRANCH_NOT_DELETED = "That branch was not deleted.";
12
13 /** The terminal's answer to a branch name left empty. */
14 export const NAME_THE_BRANCH = "give the branch a name";
src/actions/comment_words.ts added +10
@@ -0,0 +1,10 @@
1 /**
2 * What a comment's refusal says, wherever it is said: the issue page, the
3 * pull page and the forge toolbar read these so the words cannot drift.
4 */
5
6 /** A comment with nothing in it. */
7 export const COMMENT_EMPTY = "A comment needs something in it.";
8
9 /** A comment the forge would not post, when the origin gave no reason. */
10 export const COMMENT_NOT_POSTED = "That comment could not be posted.";
src/actions/dependencies.ts +2 −1
@@ -18,11 +18,12 @@ import { canRead, canWrite, type Repo } from "../core/repos.ts";
1818 import type { User } from "../core/users.ts";
1919 import { err, ok, type Result } from "../kernel/result.ts";
2020 import type { AccessError } from "./access.ts";
21 import { SELF_WAIT } from "./plan_words.ts";
2122 import { followLink } from "./pillars.ts";
2223
2324 /** What a refused link says, in the words the API and the MCP share. */
2425 export const dependencyWords: Record<string, string> = {
25 self: "an issue cannot wait for itself",
26 self: SELF_WAIT,
2627 cycle: "that would make a loop",
2728 cross_repo: "dependencies stay inside one repository",
2829 not_an_issue: "only issues can depend on issues",
src/actions/destination.ts +2 −1
@@ -18,6 +18,7 @@ import { s3FromEnv, type S3Target } from "../snapshot/store.ts";
1818 import { snapshotsOf } from "../snapshot/service.ts";
1919 import type { User } from "../core/users.ts";
2020 import { err, ok, type Result } from "../kernel/result.ts";
21 import { NOT_SEALED } from "../kernel/seal_words.ts";
2122
2223 export interface DestinationInput {
2324 readonly endpoint: string;
@@ -79,7 +80,7 @@ export function saveDestination(
7980 for (const [name, value] of fields) {
8081 if (value === "") continue;
8182 const set = putSecret(app, actor, "forge", "", name, value);
82 if (!set.ok) return err("That could not be sealed.");
83 if (!set.ok) return err(NOT_SEALED);
8384 }
8485 snapshotsOf(app)?.forget();
8586 const have = sealedSet(app.db);
src/actions/edit_words.ts added +23
@@ -0,0 +1,23 @@
1 /**
2 * The words a file edit refuses in (#5544): one sentence per refusal kind,
3 * so `POST …/contents` and any other door that writes a file say the same
4 * thing for the same failure.
5 */
6 export function editMessage(kind: string): string {
7 switch (kind) {
8 case "protected_branch":
9 return "the default branch is protected; only a repo admin may commit to it directly";
10 case "file_too_large":
11 return "that file is larger than an edit may carry; push it instead";
12 case "commit_too_large":
13 return "the edit is larger than one commit may carry; push it instead";
14 case "branch_moved":
15 return "the branch moved while this edit was being written; re-read and retry";
16 case "land_refused":
17 return "the origin refused this commit; nothing was changed here either";
18 case "pull_failed":
19 return "the commit landed, but the pull request could not be opened";
20 default:
21 return "this edit could not be applied";
22 }
23 }
src/actions/explore.ts +16 −2
@@ -25,6 +25,7 @@ import {
2525 frontWeights,
2626 type FrontSignals,
2727 } from "../core/front.ts";
28 import { isSafeName } from "../git/guard.ts";
2829 import { canEnterApp, listReposVisibleTo, type Repo } from "../core/repos.ts";
2930 import { getUsersByIds, isActive, type User } from "../core/users.ts";
3031 import { writeStamp } from "../core/write_clock.ts";
@@ -47,6 +48,8 @@ export interface ExploreQuery {
4748 readonly text: string;
4849 /** `archived:yes` — put-away repositories are in the list; off, they are not. */
4950 readonly archived: boolean;
51 /** `owner:<name>` — only this account's apps, and the person themself. */
52 readonly owner?: string;
5053 }
5154
5255 const KINDS: Record<string, ExploreKind> = {
@@ -79,6 +82,7 @@ export function parseExploreQuery(line: string): ExploreQuery {
7982 let kind: ExploreKind | "all" = "all";
8083 let sort: ExploreSort = "score";
8184 let archived = false;
85 let owner: string | undefined;
8286 const words: string[] = [];
8387 for (const word of line
8488 .trim()
@@ -94,10 +98,17 @@ export function parseExploreQuery(line: string): ExploreQuery {
9498 sort = value.toLowerCase() as ExploreSort;
9599 else if (k === "archived" && ["yes", "no"].includes(value.toLowerCase()))
96100 archived = value.toLowerCase() === "yes";
101 else if (k === "owner" && isSafeName(value)) owner = value;
97102 else if (k === "q" && value !== "") words.push(value);
98103 else words.push(word);
99104 }
100 return { kind, sort, text: words.join(" ").slice(0, 100), archived };
105 return {
106 kind,
107 sort,
108 text: words.join(" ").slice(0, 100),
109 archived,
110 ...(owner === undefined ? {} : { owner }),
111 };
101112 }
102113
103114 /** The line a query reads as, for links and the query box. */
@@ -106,6 +117,7 @@ export function exploreLine(query: ExploreQuery): string {
106117 query.kind === "all" ? "" : `kind:${query.kind}`,
107118 query.sort === "score" ? "" : `sort:${query.sort}`,
108119 query.archived ? "archived:yes" : "",
120 query.owner === undefined ? "" : `owner:${query.owner}`,
109121 query.text,
110122 ]
111123 .filter((p) => p !== "")
@@ -172,7 +184,7 @@ export async function explore(
172184
173185 /** The forges this forge spawned, for a site admin asking for them. */
174186 async function forges(app: App, viewer: User | undefined, query: ExploreQuery): Promise<ExploreRow[]> {
175 if (viewer?.isAdmin !== true || (query.kind !== "all" && query.kind !== "forge")) return [];
187 if (query.owner !== undefined || viewer?.isAdmin !== true || (query.kind !== "all" && query.kind !== "forge")) return [];
176188 return (await listChildren(app)).map((child) => ({
177189 kind: "forge",
178190 name: child.name,
@@ -292,6 +304,7 @@ function rank(
292304 });
293305
294306 const text = query.text.toLowerCase();
307 const only = query.owner?.toLowerCase();
295308 // Kept rows are shared by every request that reads them: none may change.
296309 const freeze = (row: ExploreRow): ExploreRow => {
297310 Object.freeze(row.numbers);
@@ -301,6 +314,7 @@ function rank(
301314 [...appRows, ...people.values()].map(freeze).filter(
302315 (row) =>
303316 (query.kind === "all" || row.kind === query.kind) &&
317 (only === undefined || (row.repo?.owner ?? row.name).toLowerCase() === only) &&
304318 (text === "" || `${row.name} ${row.description}`.toLowerCase().includes(text)),
305319 ),
306320 query,
src/actions/family_words.ts added +13
@@ -0,0 +1,13 @@
1 /**
2 * The forge family's refusals: what a repository outside the fork tree's
3 * rules is told, typed once so the API, MCP and the contract read the same
4 * sentence from one place.
5 */
6 export const FAMILY_WORDS = {
7 /** Proposing to the parent forge with no commit ahead of it. */
8 nothing_to_propose: "nothing here is ahead of the parent forge",
9 /** Taking, severing or changing the mode of a repository with no chain across forges. */
10 not_following: "this repository follows nothing across forges",
11 /** Showing or hiding a migration trail on a repository that was never migrated. */
12 no_provenance: "this repository was not migrated here",
13 } as const;
src/actions/finish-conflicts.ts +3 −2
@@ -19,6 +19,7 @@ import { repoDir } from "../git/repos.ts";
1919 import { commitFiles } from "../git/write.ts";
2020 import { err, ok, type Result } from "../kernel/result.ts";
2121 import { requireWriter, type AccessError } from "./access.ts";
22 import { NO_WRITE_ACCESS, PULL_GONE } from "./pull_words.ts";
2223
2324 export type FinishError =
2425 | AccessError
@@ -38,8 +39,8 @@ export type FinishError =
3839 /** What each refusal says, on the page and in the terminal alike. */
3940 export const FINISH_REFUSALS: Record<FinishError, string> = {
4041 unauthorized: "Sign in to finish a conflict.",
41 forbidden: "You do not have write access to this repository.",
42 not_found: "That pull request is no longer here.",
42 forbidden: NO_WRITE_ACCESS,
43 not_found: PULL_GONE,
4344 closed: "This pull request is not open. Nothing was written.",
4445 elsewhere: "This pull's branch lives elsewhere; resolve it there. Nothing was written.",
4546 stale:
src/actions/first_admin.ts +6 −5
@@ -30,6 +30,7 @@ import { bucketOf } from "../http/peer.ts";
3030 import { err, ok, type Result } from "../kernel/result.ts";
3131 import { limitValue } from "../settings/limits.ts";
3232 import { handOver, spawnedOrg } from "../spawn/claim.ts";
33 import { EMAIL_TAKEN_MESSAGE, EMAIL_WANTED, INVALID_USERNAME_MESSAGE, NAME_RESERVED, USERNAME_TAKEN } from "./signup_words.ts";
3334
3435 const USERNAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,38}$/;
3536
@@ -48,11 +49,11 @@ export const FIRST_ADMIN_WORDS: Record<FirstAdminError, string> = {
4849 rate_limited: "Too many attempts from here. Wait a minute and try again.",
4950 refused:
5051 "That first-admin code does not work: it may be mistyped, used, expired or replaced, or this forge already has an admin. Ask the operator to run --first-admin again.",
51 invalid_username: "Usernames are letters, digits, dots and dashes.",
52 invalid_email: "An email address, please.",
53 username_taken: "That username is taken.",
54 email_taken: "That email already has an account.",
55 username_reserved: "That name is reserved.",
52 invalid_username: INVALID_USERNAME_MESSAGE,
53 invalid_email: EMAIL_WANTED,
54 username_taken: USERNAME_TAKEN,
55 email_taken: EMAIL_TAKEN_MESSAGE,
56 username_reserved: NAME_RESERVED,
5657 unfinished: "The account could not be finished. Try again.",
5758 };
5859
src/actions/flag_winner.ts +2 −2
@@ -7,7 +7,7 @@
77 */
88
99 import type { App } from "../app.ts";
10 import { flagRegistry, mayManageFlags, winnerOffer } from "../core/flags.ts";
10 import { FLAGS_ADMIN_ONLY, flagRegistry, mayManageFlags, winnerOffer } from "../core/flags.ts";
1111 import type { Issue } from "../core/issues.ts";
1212 import { getRepo } from "../core/repos.ts";
1313 import type { User } from "../core/users.ts";
@@ -19,7 +19,7 @@ export function makeWinnerDefault(
1919 name: string,
2020 winner: "on" | "off",
2121 ): { ok: true; issue: Issue } | { ok: false; message: string } {
22 if (!mayManageFlags(actor)) return { ok: false, message: "Flags are set by a forge admin." };
22 if (!mayManageFlags(actor)) return { ok: false, message: FLAGS_ADMIN_ONLY };
2323 const registry = flagRegistry();
2424 const decl = (registry.decls as Record<string, { why: string; issue: number }>)[name];
2525 if (!Object.hasOwn(registry.decls, name) || decl === undefined)
src/actions/fleet.ts +3 −2
@@ -57,6 +57,7 @@ import {
5757 type FleetKind,
5858 } from "../fleet/selection.ts";
5959 import { VERBS, type Target, type Verb } from "../fleet/verbs.ts";
60 import { NO_SUCH_OPERATION } from "./asks_words.ts";
6061
6162 export interface FleetError {
6263 readonly code:
@@ -599,7 +600,7 @@ export async function undoFleetOp(
599600 op.actorId !== person.value.id &&
600601 (verb.personal || !parseQuery(op.query).ok)
601602 )
602 return fail("not_found", "no such operation here");
603 return fail("not_found", NO_SUCH_OPERATION);
603604 // The day is the same on every door: the card, the API, MCP.
604605 if (keepsADay(op) && Date.now() - Date.parse(op.createdAt) > UNDO_WINDOW_MS)
605606 return fail("expired", "an undo is kept for a day, and this one's day is over");
@@ -661,7 +662,7 @@ export function getFleetOp(
661662 ): Result<Operation, FleetError> {
662663 const op = getOperation(app.db, operationId);
663664 if (!op || !actor || (op.actorId !== actor.id && !actor.isAdmin))
664 return fail("not_found", "no such operation here");
665 return fail("not_found", NO_SUCH_OPERATION);
665666 return ok(op);
666667 }
667668
src/actions/follow.ts +2 −1
@@ -13,6 +13,7 @@ import { ARCHIVED_WHY, canAdmin, canWrite, forkParentFor, type Repo } from "../c
1313 import type { User } from "../core/users.ts";
1414 import { err, ok, type Result } from "../kernel/result.ts";
1515 import { chainOfRepo, forgeLinkOf, FOLLOW_MODES, isFollowMode, setChainMode, severChain, type FollowMode } from "../spawn/chain.ts";
16 import { FAMILY_WORDS } from "./family_words.ts";
1617 import { requireUser } from "./access.ts";
1718 import { takeFromParent, type Taken } from "../spawn/take.ts";
1819 import { takeUpdates, type ForkSync, type TakeUpdatesError } from "./forks.ts";
@@ -102,7 +103,7 @@ export type FollowModeError = SeverError | "invalid_mode" | "severed";
102103 export const FOLLOW_MODE_REFUSALS: Record<FollowModeError, { status: number; message: string }> = {
103104 unauthorized: { status: 401, message: "sign in to change how this forge follows its parent" },
104105 forbidden: { status: 403, message: "only this forge's owner can change how it follows" },
105 not_following: { status: 404, message: "this repository follows nothing across forges" },
106 not_following: { status: 404, message: FAMILY_WORDS.not_following },
106107 invalid_mode: { status: 422, message: `mode is one of: ${FOLLOW_MODES.join(", ")}` },
107108 severed: { status: 409, message: "this forge is severed and follows nothing; there is no mode to change" },
108109 };

812 more files not shown.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs