@abide/abide 0.49.0 → 0.50.1

package/AGENTS.md

@@ -1,478 +1,605 @@
 # AGENTS.md — abide complete surface map
 
-> This file is the exhaustive public-surface map of `@abide/abide`: every
-> `exports` key, grouped by namespace, with its import specifier and a one-line
-> spec. The README is the curated three-primitive intro; `CONTEXT.md` is the
-> domain glossary; `docs/adr/` holds the rationale behind decisions. Ground
-> rules: there are **no barrels** — every public name has its own module path,
-> and the namespace marks the side it runs on (`abide/server/*` server-only,
-> `abide/ui/*` client-only, `abide/shared/*` isomorphic — same callable, same
-> behavior on both sides). Package `@abide/abide`, runtime Bun ≥ 1.3, one
-> direct dependency (TypeScript). Import specifiers below are `exports`-map
-> keys (`@abide/abide/server/GET`), not source file paths.
+> This file is the exhaustive map of abide's public surface: every `exports` key
+> grouped by namespace, with its import specifier and a one-line spec, so an
+> agent can grasp the whole API in one read. For the curated three-primitive
+> intro read `README.md`; for the domain glossary read `CONTEXT.md`; for the
+> rationale behind a decision read `docs/adr/`.
+>
+> Ground rule — **no barrels**. Every public name is its own module path; there
+> is no umbrella `index.ts`, so importing one name never drags side-effecting
+> siblings into the bundle. The namespace marks the side a name runs on:
+> `abide/server/*` server-side, `abide/ui/*` client-side, `abide/shared/*`
+> isomorphic (same callable, same behaviour on both sides). The package is
+> `@abide/abide` (Bun ≥ 1.3.0, one direct dependency — TypeScript). Every import
+> specifier below is `@abide/abide<exports-key>`; the file path after it is the
+> source, not an import target.
 
 ## The premise
 
-One typed declaration fans out to every surface:
+One declared RPC fans out to five surfaces:
 
 ```text
-src/server/rpc/getMessages.ts
-      │
-      ├─ SSR / server   await getMessages({ room })  in-process, no HTTP
-      ├─ browser        await getMessages({ room })  typed fetch proxy
-      ├─ HTTP           GET /rpc/getMessages?room=…
-      ├─ CLI            my-app get-messages --room …
-      ├─ MCP            tool: get-messages
-      └─ OpenAPI        operation in /openapi.json
+            export const getMessages = GET(fn, { schemas })
+                               │
+    ┌───────────┬──────────────┼──────────────┬─────────────┐
+    ▼           ▼              ▼              ▼             ▼
+ SSR call   browser fetch   MCP tool      CLI subcmd   OpenAPI op
+ (bare,     (same call,     (read-only    abide-cli    /openapi.json
+  in-proc)   swap to fetch)  from schema)  getMessages
 ```
 
-An `inputSchema` (any Standard Schema library — zod, valibot, arktype,
-unadapted) is the gate: it unlocks the CLI, and for read-only methods
-(GET/HEAD) the MCP tool. A mutating method (POST/PUT/PATCH/DELETE) never
-auto-exposes to MCP — it requires explicit `clients: { mcp: true }`.
+A `schemas.input` (any Standard Schema) unlocks the **CLI** on any RPC and
+**MCP** for read-only methods (`GET`/`HEAD`). A mutating method
+(`POST`/`PUT`/`PATCH`/`DELETE`) never auto-exposes to MCP — it needs an explicit
+`clients: { mcp: true }`. Explicit `clients` values always win; `browser`
+defaults on. A socket with a `schema` auto-exposes to MCP and CLI regardless of
+direction.
 
 ## File-based conventions
 
+The bundler and route resolver read these paths by convention (dir aliases
+`$server`, `$ui`, `$shared`, `$mcp`, `$cli` point at the matching `src/` dirs):
+
 | Path | Meaning |
-| --- | --- |
-| `src/server/rpc/<name>.ts` | One RPC per file; the export name must match the file stem; the file path becomes the URL `/rpc/<name>` (subdirectories nest into the path) |
-| `src/server/sockets/<name>.ts` | One broadcast socket per file; export name = file stem = topic name |
-| `src/mcp/prompts/<name>.md` | An MCP prompt template; `{{arg}}` placeholders become the prompt's arguments |
-| `src/mcp/resources/**` | Files served as MCP resources (gzip-embedded into builds) |
-| `src/server/config.ts` | Boot-time `env()` validation; eager-imported so a bad environment fails the boot |
-| `src/app.ts` | Optional `AppModule` hooks: `init`, `handle`, `handleError`, `health`, `forwardHeaders` |
-| `src/bundle/window.ts` | Optional `BundleWindow` default export configuring the desktop bundle's window and menus |
-| `src/ui/pages/**/page.abide` | A routed page; the directory path is the route — a `[id]` folder is a path param, `[[id]]` an optional param, `[...rest]` a catch-all |
-| `src/ui/pages/**/layout.abide` | A layout wrapping the pages below it; its `{children()}` is the router outlet |
-| `src/ui/public/` | Static assets served as-is |
-| `src/.abide/*.d.ts` | Generated typing (rpc args for `url()`, page routes, health fields, test rpc/socket clients, public asset paths) |
-| `dist/` | Build output — `dist/_app` client bundle, `dist/cli-thin/<platform>/` CLI tarballs |
-
-Project import aliases resolve to the five top-level source dirs: `$server`,
-`$ui`, `$shared`, `$mcp`, `$cli` (e.g. `$server/rpc/getMessages`,
-`$ui/pages/...`). `$server/rpc/*` and `$server/sockets/*` are proxied into
-client bundles; any other `$server/*` import from client code is a
-side-crossing error.
+|---|---|
+| `src/server/rpc/<name>.ts` | One RPC per file; filename = export name = URL under `/rpc/`. The method helper picks the verb. Rewritten to `defineRpc` (server) / `remoteProxy` (client). |
+| `src/server/sockets/<name>.ts` | One socket per file (`export const <name> = socket(...)`); path → socket name. Rewritten to `defineSocket` (server) / `socketProxy` (client). |
+| `src/mcp/prompts/<name>.md` | Markdown MCP prompt: frontmatter (description + arguments) + `{{arg}}` template body, compiled to `definePrompt`. |
+| `src/mcp/resources/*` | MCP resource files served by the generated MCP server. |
+| `src/server/config.ts` | Optional typed-env module: `export const config = env(schema)` validates `Bun.env` at boot (or the floor `export const config = Bun.env`). Eager-imported; deletable. |
+| `src/app.ts` | Optional app hooks (`AppModule` shape): `init` / `handle` / `handleError` / `health` / `forwardHeaders`. Deletable. |
+| `src/ui/pages/**/page.abide` | Folder-based route: a folder's `page.abide` mounts at that folder's URL. `[name]` / `[[name]]` (optional) / `[...rest]` (catch-all) are dynamic segments → `page.params`. |
+| `src/ui/pages/**/layout.abide` | Wraps every page at/below its folder; renders the page where it calls `{children()}`; kept mounted across navigation. |
+| `src/ui/app.html`, `src/ui/app.css` | Custom document shell and root stylesheet. |
+| `src/ui/public/` | Static assets, served at the site root (`/<file>`). |
+| `src/bundle/window.ts` | Optional default-exported `BundleWindow` for the desktop bundle (plus optional `src/bundle/disconnected.abide` connect-screen override). |
+| `src/cli/banner.txt`, `src/cli/footer.txt` | CLI help chrome. |
+| `src/.abide/*.d.ts` | Generated ambient types (`rpc.d.ts`, `routes.d.ts`, `health.d.ts`, `publicAssets.d.ts`, `testRpc.d.ts`, `testSockets.d.ts`). Do not hand-edit. |
+| `dist/` | Build output: `dist/_app/` (prod client) or `dist/_app.gen-<id>/` (dev), `dist/app` (compiled binary), `dist/cli-*`. |
 
 ## CLI
 
+`abide <command>` (the `abide` bin):
+
 | Command | Does |
-| --- | --- |
-| `bunx abide scaffold <name>` | Scaffolds the bundled template, installs it, and (interactive TTY only) starts the dev server; `--no-install` / `--no-dev` opt out |
-| `abide dev` | Dev orchestrator: builds the client, runs the server as a child, watches `src/`, rebuilds + restarts on change, live-reloads the browser |
-| `abide build` | One-shot client build into `dist/_app` (CI / static deploys) |
-| `abide start` | Runs the production server against an already-built `dist/` |
-| `abide run <file> [args...]` | Runs any script under the abide preload — same runtime as the server (`.abide` compilation, `abide/*` + `$` alias resolution) |
-| `abide compile [--target=…] [--out=…]` | Compiles a standalone server executable (client assets embedded) |
-| `abide cli [--target=…] [--out=…] [--platforms=a,b,c]` | Builds the thin CLI binary (rpc manifest baked in) that talks to a remote server or starts a local one; `--platforms` cross-compiles into `dist/cli-thin/<platform>/` |
-| `abide bundle` | Assembles a movable, self-contained desktop app bundle (server binary + launcher + webview) for the host platform; unsigned |
-| `abide check` | Type-checks every `.abide` component's template + props through its shadow; non-zero exit on errors |
-| `abide lsp` | Runs the `.abide` language server over stdio (JSON-RPC) for editor diagnostics |
-| `abide init-agent` | Writes/refreshes the CLAUDE.md pointer to this surface map for non-scaffolded projects |
+|---|---|
+| `abide scaffold <name> [--no-install] [--no-dev]` | Scaffold a project from the bundled template, install it, and (TTY only) start dev. |
+| `abide dev` | Dev orchestrator: build client, spawn the server child, watch `src/`, rebuild + restart on change, browser live-reload. |
+| `abide build` | Single client build into `dist/_app/`, no server (CI / static deploys). |
+| `abide start` | Run the production server against an already-built `dist/`. |
+| `abide run <file> [args...]` | Run an arbitrary script under the abide preload (same runtime as the server); argv after the file is forwarded verbatim. |
+| `abide compile [--target=<bun-…>] [--out=<path>]` | Build a standalone server executable. |
+| `abide cli [--target=…] [--out=…] [--platforms=<a,b,c>]` | Build the thin CLI binary (manifest baked in, ships the compiled server beside it); `--platforms` cross-compiles into `dist/cli-thin/<platform>/`. |
+| `abide bundle` | Assemble a self-contained desktop app bundle for the host platform (`.app` on macOS), unsigned. |
+| `abide check` | Type-check every `.abide` component's template + props through its shadow program; non-zero on error. |
+| `abide lsp` | Run the `.abide` language server over stdio (JSON-RPC) for editor diagnostics. |
+| `abide init-agent` | Write/refresh the abide agent-guide pointer in the project root `CLAUDE.md`. |
 
 For tests, add `preload = ["@abide/abide/preload"]` under `[test]` in
-`bunfig.toml` and use `bun test`.
+`bunfig.toml` and run `bun test`.
 
 ## Authoring contracts
 
-**RPC** — the handler receives the schema-validated args
-(`InferOutput<inputSchema>`); typed generics on the helper are a compile error
-— type the parameter, let the body infer. Inside it, `request()` / `cookies()`
-/ `server()` read the request scope. Return `json(data)` (or `jsonl` / `sse`
-for streams, `error` / `redirect`, or a raw `Response`). Options:
-`inputSchema`, `outputSchema`, `filesSchema` (validates uploaded `File` parts,
-kept out of the JSON-Schema projection), `clients: { browser, mcp, cli }`,
-`crossOrigin` (exempts a mutating rpc from the same-origin CSRF gate),
-`timeout` (handler deadline in ms → 504 on every surface, composed into
-`request().signal`), `maxBodySize` (per-rpc 413 cap), `outbox` (durable
-delivery, mutating methods only). Query args on GET/HEAD/DELETE travel as
-strings — coerce in the schema (`z.coerce.number()`). A body rpc also accepts
-a `FormData` in place of typed args (the upload escape hatch): text fields
-validate as args, `File` parts validate against `filesSchema`.
-
-**Consuming an rpc** — the bare call `fn(args, opts?)` IS the smart read:
-cached, coalesced, reactive, stale-while-revalidate for replayable (GET/HEAD)
-reads; the second arg takes `{ ttl, tags, throttle, debounce, shared, n }`
-(retention and the refetch clock — not transport). `ttl` defaults to `0` on
-the server (coalesce-only — the request is the atomic unit, nothing is
-retained past it) and `Infinity` on the client (retain until invalidate/
-refresh). `shared: true` selects the process-level store instead of the
-request-scoped default (server) — it does not by itself retain, pair it with
-an explicit `ttl` (e.g. `{ shared: true, ttl: Infinity }`) to memoise across
-requests, for an external endpoint, never per-user data; on the client it is
-a no-op (one tab store). A read with no request in flight (e.g. a background
-job) also resolves against the process-level store. During SSR the same call
-resolves
-in-process and its value is baked into the HTML so hydration starts warm —
-there is no `cache()` wrapper; the bare call carries the caching. Around it:
-`fn.raw(args, init?)` returns the raw `Response` (per-call transport options —
-`signal`, `headers`, `keepalive`, … — live here); `fn.refresh(args?)`
-refetches keeping the stale value visible; `fn.patch(args?, updater)` mutates
-the retained value locally (absent on streaming rpcs); `fn.peek(args?)` reads
-it synchronously; `fn.pending(args?)` / `fn.refreshing(args?)` are reactive
-probes; `fn.error(args?)` is the rpc's last typed error; `fn.watch(args?,
-handler)` pipes each resolved value to a handler (client-only; SSR-inert);
-`fn.isError(e, kind?)` type-guards a caught error against the rpc's declared
-error kinds; `fn.outbox()` exposes a durable rpc's parked-write queue. A
-handler that returns `jsonl()`/`sse()` makes the bare call return a
-`Subscribable` (`for await` it) — detected at build, nothing to declare;
-awaiting a streaming call is a compile error.
-
-**Typed errors** — declare a constructor with
-`error.typed(name, status, schema?)` and `return` it from the handler; the
-client's `HttpError` then carries `kind` (the name) and `data` (the schema's
-payload), narrowed via `rpc.isError`. The framework reserves
-`kind: 'validation'` (422, `data: ValidationErrorData`) and `kind: 'queued'`
-(a durable call parked while unreachable; `data` is the parked `OutboxEntry`).
-
-**Durable outbox** — an `outbox: true` (mutating) rpc still fetches and throws
-normally, but an unreachable server (transport failure or 502/503/504/52x)
-parks the request for replay as a side-effect and throws `kind: 'queued'`;
-once a backlog exists new calls park straight to the tail so writes stay
-ordered. Nothing auto-drains: replay via `rpc.outbox.retry()` or the global
-`outbox.retry()`; cancel via an entry's `controller.abort()`.
-
-**Socket** — `socket<T>(opts)` or `socket({ schema, … })` (with a schema, `T`
-infers and publishes validate). Options: `tail` (retained frames, default 1 —
-`tail: 0` opts out), `ttl` (retained frames expire lazily after N ms),
-`clientPublish` (accept browser/HTTP publishes, off by default), `clients`
-(mcp/cli exposure; a schema flips both on by default). The socket IS the
-`AsyncIterable` — iterating is the live stream, no replay. Members:
-`broadcast(msg)` (isomorphic publish — server fans out in-process + to remote
-subscribers, client sends a validated `pub` frame), `tail(count?)` (a
-subscription seeded with retained frames), `peek()` (latest retained frame),
-`refresh()` (drop local frames and re-pull the server tail; server-side
-no-op), `watch(handler)` ≡ `watch(socket, handler)` (client-only, SSR-inert),
-`pending()` / `refreshing()` / `done()` / `error()` (reactive stream probes),
-plus `name` and `clients`.
-
-**Pages and layouts** — `src/ui/pages/blog/[id]/page.abide` serves
-`/blog/<id>`; the param arrives as a prop (`const { id } = props()`) and on the
-reactive `page.params`. A `[[name]]` folder is an optional segment (the route
-matches with or without it; the param is absent when unmatched), `[...rest]`
-a catch-all capturing the remaining path (last segment only). One matcher
-resolves routes on both sides — at the first position where two matching
-patterns differ, literal beats `[name]` beats `[[name]]` beats `[...rest]`. A `layout.abide` wraps every page below its directory
-and renders the page at its `{children()}` outlet. Links are plain `<a href>`
-(the router intercepts in-app hrefs); build paths with `url()` and navigate
-programmatically with `navigate()`.
-
-**app.ts / config.ts** — `src/app.ts` optionally exports the `AppModule`
-hooks: `init({ server })` (boot; may return a cleanup run on SIGINT/SIGTERM),
-`handle(request, next)` (single middleware), `handleError(error, request)`,
-`health(request)` (fields merged into the `/__abide/health` payload — public
-and unauthenticated, keep it cheap), and `forwardHeaders` (extra inbound
-header names forwarded onto in-process rpc requests beyond the built-in
-auth/identity set). `src/server/config.ts` holds the `env(schema)` call so a
-bad environment fails at boot.
-
-## `.abide` template grammar
-
-A component file is: an optional leading `<script>` (imports + author scope),
-markup, optional `<style>` blocks. The compiler emits a client build and an
-SSR render from the same parse; `abide check` / the LSP type-check the
-template through a generated shadow. HTML comments are dropped; a bare
-`<template>` is an inert element.
-
-Reactive state is reached through **imported primitives**, resolved by import
-binding (alias-safe) and lowered by the compiler — inside a component you read
-and write the declared names as plain variables (`{count}`,
-`onclick={() => (count += 1)}`); there is no `.value` in `.abide` authoring
-and no `$state` sigils. In plain `.ts` modules the same imports are runtime
-cells read/written through `.value`.
-
-| Primitive | Import | Spec |
-| --- | --- | --- |
-| `state(initial, transform?)` | `@abide/abide/ui/state` | Writable cell. Plain `state(v)` lowers to a serializable doc slot (SSR-resumable); with `transform` the gate runs on every write (`(next, previous) => stored`) |
-| `state.computed(fn)` | member of `state` | Read-only derived value, lazy, never serialized |
-| `state.linked(fn, transform?)` | member of `state` | Writable cell re-seeded whenever the thunk's dependencies change |
-| `state.share(key, value)` / `state.shared(key)` | members of `state` | Put a named value on the ambient scope / read the closest ancestor's |
-| `watch(source, handler)` | `@abide/abide/ui/watch` | The single reaction primitive (client-only, stripped from SSR). Sources: a bare thunk `watch(() => …)` (auto-tracked effect), a state cell, a cell array, a socket/stream (`handler(frame)` per frame with reconnect replay), an rpc (`watch(fn, args?, handler)` — runs the smart read, `handler(value)` on each change). Returns a scope-tied disposer |
-| `html(str)` / `` html`…` `` | `@abide/abide/ui/html` | Brands trusted raw HTML so `{expr}` inserts nodes instead of escaped text; plain `{value}` always escapes |
-| `props()` | `@abide/abide/ui/props` | The prop reader, resolved by import binding (alias-safe) like `state`: `const { name = fallback, ...rest } = props()`; a page/layout's declared props are additive with its route-param shape. `children` is an ordinary declared prop (`const { children } = props<{ children: Snippet }>()`), not ambient |
-
-Bindings and directives (the attribute kinds `readAttributes` parses):
-
-| Form | Spec |
-| --- | --- |
-| `{expr}` | Text interpolation, escaped; a snippet or `html`-branded value mounts as nodes |
-| `name={expr}` | Attribute/prop bound to an expression |
-| `name="a {expr} b"` | Interpolated attribute — a literal `{` in a quoted value always interpolates (write `&lbrace;` for a literal brace) |
-| `{...expr}` | Spread — props onto a component, attributes onto a native element (rejected on `<template>`) |
-| `on<event>={fn}` | Event listener (`onclick`, `onsubmit`, …); on a component it is a checked callback prop |
-| `bind:value={cell}` | Two-way input/select/textarea binding. `<input type="number"/"range">` writes back a number; `<select>` re-applies against late-mounting options and `<select multiple>` binds an array of selected values |
-| `bind:value={{ get, set }}` | Writable-computed binding: read via `get()`, write via `set(next)` |
-| `bind:checked={cell}` / `bind:group={cell}` | Checkbox boolean / radio-group value (SSR emits boolean attributes bare — `checked`, `open`, `selected` on the matching option) |
-| `class:name={cond}` | Toggles a class; merges with a reactive `class` base in one effect |
-| `style:property={value}` | Sets one style property; merges with a reactive `style` base |
-| `attach={fn}` | Runs `fn(element)` at build time; an optional returned teardown runs on dispose |
-
-Control flow is mustache blocks (`{#…}` open, `{:…}` branch, `{/…}` close —
-the close must name its block, and a branch outside its block is a parse
-error):
-
-| Block | Spec |
-| --- | --- |
-| `{#if cond}…{:else if cond}…{:else}…{/if}` | Conditional chain (the branch keyword is `{:else if}`, with a space) |
-| `{#for item, i of list by key}…{:catch e}…{/for}` | Keyed list; `, i` index and `by` key optional; `{#for await item of asyncIterable}` renders rows as they arrive (its `{:catch}` shows the stream error) |
-| `{#await p}…{:then v}…{:catch e}…{:finally}…{/await}` | Async block. The branch form streams: SSR flushes the shell and streams the fragment out of order. The head form `{#await p then v}` is blocking — rendered inline (depth-first, serial) during the SSR pass |
-| `{#switch subject}{:case match}…{:default}…{/switch}` | Multi-branch on a subject; only branches render — stray content is a compile error |
-| `{#try}…{:catch e}…{:finally}…{/try}` | Synchronous error boundary around a build/reactive throw |
-| `{#snippet name(args)}…{/snippet}` | Declares a reusable builder, called as an interpolation: `{name(args)}`; a snippet value passes through props like any other value |
-
-Components are capitalised tags (`<Panel prop={x}>…</Panel>`); nested content
-becomes the component's `children` prop — an ordinary declared prop of type
-`Snippet`, read with `const { children } = props<{ children: Snippet }>()`
-and called as `{children()}` — the single fill point (`{#if children}
-{children()}{:else}…{/if}` for a fallback; there are no named slots and no
-`<slot>` element). Slotted content (`<Panel>…</Panel>`) and an explicit
-`children={aSnippet}` attribute set the same prop — slotted content rides in
-as the trailing prop layer, so it wins over an explicit `children` attribute
-on the same tag (`mergeProps`, last layer wins per key). A layout's
-`{children()}` is the route outlet.
-
-`<script>` and `<style>` are **not component-root-only**: either may sit
-inside a control-flow branch, scoped to that branch. A nested `<script>`
-declares branch-local `state` / `state.computed` / `state.linked` the same
-imported way (re-seeded per mount; static `import` statements are illegal
-there — imports live in the leading `<script>`). A **root** `<style>` is
-component-scoped; a nested `<style>` scopes to its sibling subtree only.
-
-Removed forms throw migration errors at parse time: the `<slot>` element (use
-a declared `children: Snippet` prop, called `{children()}`), `<template
-name>` snippets (use `{#snippet}`), and all `<template
-if/each/await/switch/…>` control flow (use `{#…}` blocks).
-
-## Server surface — `abide/server/*`
-
-### RPC — `@documentation rpc`
-
-- `@abide/abide/server/GET` — GET rpc helper: `export const x = GET(handler, opts?)` inside `src/server/rpc/`; the bundler rewrites it to the server dispatcher or the browser proxy — calling it outside an rpc module throws.
-- `@abide/abide/server/POST` — POST rpc helper (mutating: accepts `outbox`, JSON/FormData body).
-- `@abide/abide/server/PUT` — PUT rpc helper (mutating).
-- `@abide/abide/server/PATCH` — PATCH rpc helper (mutating).
-- `@abide/abide/server/DELETE` — DELETE rpc helper (mutating; args travel in the query string).
-- `@abide/abide/server/HEAD` — HEAD rpc helper (read-only).
-
-### Responses — `@documentation response`
-
-- `@abide/abide/server/json` — `json(data, init?)`: JSON response with `Cache-Control: no-store` default; `json(undefined)` emits 204 and round-trips back to `undefined`; carries the value type so the rpc's `Return` infers.
-- `@abide/abide/server/jsonl` — `jsonl(asyncIterable, init?)`: JSON Lines streaming response; consumer cancel flows into the generator's `return`; a generator throw becomes a final `{"$error": message}` line.
-- `@abide/abide/server/sse` — `sse(asyncIterable, init?)`: Server-Sent Events response with a 15s keepalive comment; errors emit an `event: error` frame carrying only the message.
-- `@abide/abide/server/error` — `error(status, message?, init?)`: plain-text error response (message defaults to the reason phrase); the caller's await throws `HttpError`. Member `error.typed(name, status, schema?)` declares a reusable typed-error constructor the handler returns (see Authoring contracts).
-- `@abide/abide/server/redirect` — `redirect(url, status = 302, init?)`: redirect response accepting relative URLs; 301/302/303/307/308.
-
-### Request scope — `@documentation request-scope`
-
-- `@abide/abide/server/request` — `request()`: the inbound `Request` for the in-flight SSR/rpc pass (AsyncLocalStorage); throws outside a request scope.
-- `@abide/abide/server/cookies` — `cookies()`: the request's cookie jar (Bun `CookieMap`) — reads parse the inbound header; `set`/`delete` flush as `Set-Cookie` when the handler returns.
-- `@abide/abide/server/server` — `server()`: the active `Bun.serve` instance; a no-op stand-in during in-process dispatch (CLI/MCP/tests); throws before boot.
-
-### Configuration — `@documentation configuration`
-
-- `@abide/abide/server/env` — `env(schema)`: validates `Bun.env` against a Standard Schema at module top level (synchronous; every issue reported at once) and returns the typed config; the schema also projects the bundle's first-run setup form.
-
-### Sockets — `@documentation sockets`
-
-- `@abide/abide/server/socket` — `socket<T>(opts?)` / `socket({ schema, tail, ttl, clientPublish, clients })`: declares the broadcast topic inside `src/server/sockets/<name>.ts`; see Authoring contracts for the full `Socket<T>` member surface.
-
-### Agent — `@documentation agent`
-
-- `@abide/abide/server/agent` — `agent(engine, messages)`: runs a provider engine (an `@abide/<provider>` package) against the app's own MCP surface inside an rpc's request scope and returns its `AgentFrame` stream; the handler picks the transport (`jsonl(agent(…))` / `sse(agent(…))`). The module also exports the neutral contract types: `NeutralMessage` (user/assistant/tool turns), `AgentFrame` (`text` deltas, `tool_use`, `tool_result`, `done` with a stop reason), `AgentSurface` (the gated tool/prompt/resource surface), and `AgentEngine` (surface + messages + origin in, frames out).
-
-### Server plumbing — `@documentation plumbing`
-
-- `@abide/abide/server/AppModule` — the type of `src/app.ts`'s optional hooks (`init`, `handle`, `handleError`, `health`, `forwardHeaders`).
-- `@abide/abide/server/InspectorContext` — the capability object core injects into `@abide/inspector` (`loadSurface`, `cacheSnapshot`, `inFlightSnapshot`, `onRecord`, app identity); keeps the inspector a pure consumer.
-- `@abide/abide/server/rpc/defineRpc` — `defineRpc(method, url, handler, opts?)`: the server-side construction the bundler rewrites rpc helper calls into — validation, timeout composition, client-flag resolution, registry entry.
-- `@abide/abide/server/sockets/defineSocket` — `defineSocket(name, opts?)`: server-side socket construction (retained-tail buffer with lazy TTL eviction, per-subscriber queues, `server.publish` fan-out).
-- `@abide/abide/server/prompts/definePrompt` — `definePrompt(name, opts)`: registers an MCP prompt; the resolver plugin generates one call per `src/mcp/prompts/<name>.md`.
-- `@abide/abide/server/prompts/renderPromptTemplate` — `renderPromptTemplate(template, args)`: substitutes `{{name}}` placeholders in a prompt body (missing args collapse to empty).
-
-## Isomorphic surface — `abide/shared/*`
-
-### Cache mutators — `@documentation cache`
-
-- `@abide/abide/shared/refresh` — `refresh(selector?, args?)`: refetch every cached read matching the selector, keeping the stale value visible until the fresh one swaps in. Selector grammar: `(fn, args)` exact call, `(fn)` every args-variant, `({ tags })` a tagged group, `()` everything. `fn.refresh(args?)` is the pre-bound sugar.
-- `@abide/abide/shared/patch` — `patch(fn, args?, updater)` / `patch({ tags }, updater)`: mutate the retained value(s) in place — reactive, no network; the optimistic-update / socket-frame primitive. `fn.patch(…)` is the sugar.
-
-### Probes — `@documentation probes`
-
-Probes report, never act — reading one opens no fetch and no stream.
-
-- `@abide/abide/shared/pending` — `pending(selector?, args?)`: reactive "no value yet" probe over calls and streams (global, per-rpc, per-call, tagged, per-subscribable; a durable rpc's parked writes count too).
-- `@abide/abide/shared/refreshing` — `refreshing(selector?, args?)`: "holding a value while a fresher one is in flight" — the SWR reload / stream-reconnect badge.
-- `@abide/abide/shared/peek` — `peek(fn, args?)` / `peek(socket)`: the retained value (or latest frame), synchronously, `T | undefined`; reactive inside a tracking scope.
-- `@abide/abide/shared/done` — `done(subscribable)`: true once a stream closed (stream-only; a cache read's "done" is `!pending && !refreshing`).
-- `@abide/abide/shared/online` — `online()`: reactive connectivity probe — browser `online`/`offline` events; server-side it reflects the *calling client's* reported connectivity (always true during SSR and outside a scope).
-
-### Errors — `@documentation response`
-
-- `@abide/abide/shared/HttpError` — thrown by rpc calls on non-2xx; carries `status`, `statusText`, the raw `response`, and — for typed/validation/queued errors — `kind` + `data`.
-- `@abide/abide/shared/ValidationErrorData` — the `data` shape of a `kind: 'validation'` failure: the raw Standard Schema `issues` plus a `fields` (field → first message) map.
-
-### Schema projection — `@documentation rpc`
-
-- `@abide/abide/shared/withJsonSchema` — `withJsonSchema(schema, toJsonSchema)`: attaches the `toJSONSchema()` projection to a Standard Schema whose library lacks one, feeding OpenAPI, MCP, CLI help, and the bundle setup form.
-
-### Observability — `@documentation observability`
-
-- `@abide/abide/shared/health` — `health()`: reactive backend health — `{ reachable, abide, name, version, …app health-hook fields }`, polled from `/__abide/health` only while a tracking scope reads it; SSR-seeded so hydration starts warm; constant `{ reachable: true }` on the server. The `AppHealth`/`AppHealthMap` types augment from the generated `health.d.ts`.
-- `@abide/abide/shared/reachable` — `await reachable(host?)`: outbound reachability, same callable both sides. The first call probes (HEAD) and starts a TTL background poll; later calls answer instantly off the warm value. Any completed HTTP response counts as reachable. No host asks about the app's own backend: constant true on the server and on a loopback origin (dev, desktop bundle — works offline); a deployed origin probes like any host. The browser probes no-cors and composes `navigator.onLine` in at read time (loopback exempt). Tuned by `ABIDE_REACHABLE_TTL` / `ABIDE_REACHABLE_TIMEOUT` (server env; the browser runs the defaults).
-- `@abide/abide/shared/log` — the unified logger: `log(...)` / `.warn` / `.error` / `.trace` on the app's always-on channel, every record carrying request-scope context (short trace id, +elapsed, method+path); member `log.channel(name)` returns the same shape on a DEBUG-gated diagnostic channel. Renders tsv (default) or JSON per `ABIDE_LOG_FORMAT`.
-- `@abide/abide/shared/trace` — `trace()`: the current request's W3C `traceparent` (client-side: the trace of the request that rendered the page), or undefined outside any scope.
-
-### Page — `@documentation page`
-
-- `@abide/abide/shared/page` — the reactive page proxy: `page.route`, `page.params`, `page.url` (browser-space on both sides, mount base included), `page.navigating`; isomorphic, re-runs readers across navigations.
-
-### URL — `@documentation url`
-
-- `@abide/abide/shared/url` — `url(path, params?/args?)`: resolves any in-app URL to its base-correct form — a page route literal interpolates its `[name]` / `[[name]]` / `[...rest]` params (typed via `PathParams`; an absent optional drops its segment), a GET rpc path serializes typed args to the query, anything else is base-prefixed. Also exports the augmentable `RpcRoutes` / `PageRoutes` / `PublicAssets` maps and the `PathParams<P>` type.
-
-### Templating — `@documentation templating`
-
-- `@abide/abide/shared/snippet` — `snippet(payload)`: brands a snippet payload so a `{expr}` interpolation mounts it (client: a DOM builder; server: the rendered string); the compiler wraps `{#snippet}` bodies in this. Also exports the `Snippet<Args>` type — a callable `(...args: Args) => SnippetValue`, generic over its call arguments (`children` is `Snippet`, invoked `children()`; a row snippet is `Snippet<[Item]>`, invoked `row(item)`) — plus `SnippetValue` (the internal payload brand) and `snippetPayload(value)` (a branded value's payload, or undefined for plain values).
-
-### Shared plumbing — `@documentation plumbing`
-
-- `@abide/abide/shared/createSubscriber` — `createSubscriber(start)`: open-on-first-tracked-read / close-on-last-reader resource lifecycle grounded in the signal core; the substrate under `health()`, `online()`, and the tail probes.
-
-## UI surface — `abide/ui/*` (client-only)
-
-### Reactive state — `@documentation reactive-state`
-
-- `@abide/abide/ui/state` — the `state` primitive: `state(initial, transform?)` writable cell, `state.computed(fn)` read-only derived, `state.linked(fn, transform?)` writable-reseeded, `state.share(key, value)` / `state.shared(key)` ambient context. In `.abide` files the compiler lowers reads/writes to plain variable syntax; in `.ts` the cell is read/written through `.value`.
-- `@abide/abide/ui/watch` — `watch(source, handler)`: the single reaction primitive over a thunk, cell, cell array, socket/stream, or rpc (see the grammar table). Client-only; the compiler strips author calls from SSR, and the `socket.watch` / `fn.watch` instance sugar is SSR-inert.
-- `@abide/abide/ui/props` — `props<T>()`: the prop reader, resolved by import binding (alias-safe) like `state`; a required import — there is no ambient `props()`. Destructure declared props off it (`const { name, ...rest } = props<T>()`); a page/layout's declared `T` is additive with its auto-typed route-param shape. `children` is an ordinary declared prop, not ambient: `const { children } = props<{ children: Snippet }>()` (`Snippet` from `@abide/abide/shared/snippet`).
-
-### Templating — `@documentation templating`
-
-- `@abide/abide/ui/html` — `html(string)` / `` html`…` ``: brands trusted raw HTML for unescaped interpolation; the tag does not escape its interpolations — only feed it values you trust.
-
-### Navigate — `@documentation navigate`
-
-- `@abide/abide/ui/navigate` — `navigate(path, params?, options?)`: typed programmatic navigation off the route map; params interpolate through `url()` (base-correct). Options `{ replace, keepScroll }`. The module also exports `navigatePath(path, options?)` (already-resolved paths — the router's own entry, no re-basing) and the `NavigateOptions` type.
-
-### Outbox — `@documentation ui`
-
-- `@abide/abide/ui/outbox` — the global reactive outbox: `outbox()` lists every durable rpc's undelivered entries (each tagged with its `rpc`), member `outbox.retry()` drains every queue. Empty list server-side. Types `GlobalOutbox`, `GlobalOutboxEntry`.
-
-### UI plumbing — `@documentation plumbing`
-
-Compiler/runtime machinery — published so generated code, the type shadow, and
-tests can import it, not for app code.
-
-- `@abide/abide/ui/effect` — `effect(fn)`: the raw auto-tracked effect the compiler emits for bindings; authors use `watch`. Returns a disposer; SSR strips author calls.
-- `@abide/abide/ui/currentScope` — `scope()`: the ambient lexical scope — the internal lowering host for `state`/`effect` (`derive`/`linked`/`effect`/`share` land here).
-- `@abide/abide/ui/enterRenderScope` — `enterScope()`: opens an isolated scope for an SSR render; returns the previous scope to restore.
-- `@abide/abide/ui/exitRenderScope` — `exitScope(previous)`: restores the scope `enterScope` saved.
-- `@abide/abide/ui/router` — `router(...)`: the client router — fills layout/page chains into comment-marker outlet boundaries, intercepts in-app links, buckets/restores scroll per history entry.
-- `@abide/abide/ui/startClient` — `startClient(...)`: the client entry — reads every `__SSR__` field into its shared slot (cache seed, health seed, client timeout, resume manifest), hydrates the chain, starts the router.
-- `@abide/abide/ui/renderToStream` — `renderToStream(render)`: out-of-order SSR streaming — shell first, then one `<abide-resolve>` fragment per streaming await block in completion order; blocking (`then`-head) awaits render inline.
-- `@abide/abide/ui/remoteProxy` — `remoteProxy(method, url, opts?)`: the browser-side rpc stub the bundler emits (fetch, decode, HttpError, outbox parking, streaming); the `DurableOptions` type rides along.
-- `@abide/abide/ui/socketProxy` — `socketProxy(name)`: the browser-side socket stub — the identical `Socket<T>` shape over the page's lazily-opened multiplexed ws channel.
-- `@abide/abide/ui/runtime/escapeKey` — JSON-Pointer-escapes one reactive-doc path key (`~`→`~0`, `/`→`~1`).
-- `@abide/abide/ui/runtime/nextBlockId` — the next await/try block id in the current render pass (document order, shared across inlined children).
-- `@abide/abide/ui/runtime/enterRenderPass` — marks entry into a render/mount; the outermost resets the block-id counter.
-- `@abide/abide/ui/runtime/exitRenderPass` — unwinds `enterRenderPass`'s depth.
-- `@abide/abide/ui/dom/mount` — mounts a top-level page/layout into a host under an ownership scope; returns the unmount.
-- `@abide/abide/ui/dom/mountChild` — mounts a nested child component as a comment-marker range (dev builds also register it with the hot bridge).
-- `@abide/abide/ui/dom/mountSlot` — mounts a component's passed-children content as a marker-bounded range.
-- `@abide/abide/ui/dom/outlet` — a layout's outlet: an empty `<!--abide:outlet-->…<!--/abide:outlet-->` boundary the router fills.
-- `@abide/abide/ui/dom/hydrate` — adopts server-rendered DOM instead of rebuilding: runs the build with a claim cursor over the existing nodes.
-- `@abide/abide/ui/dom/skeleton` — the parsed-once static-structure clone path every bound element builds through; element holes by path, blocks by anchor comments.
-- `@abide/abide/ui/dom/anchorCursor` — positions a skeleton-anchored block/slot at its `<!--a-->` anchor, in clone and hydrate modes alike.
-- `@abide/abide/ui/dom/cloneStatic` — appends a fully-static subtree (no bindings, control flow, or listeners) by cloning.
-- `@abide/abide/ui/dom/appendStatic` — a static text node: created (create mode) or claimed from server-rendered text (hydrate mode).
-- `@abide/abide/ui/dom/appendText` — a reactive `{expr}` text node under a parent.
-- `@abide/abide/ui/dom/appendTextAt` — a reactive text node mounted at a skeleton anchor (text interleaved with element siblings).
-- `@abide/abide/ui/dom/appendSnippet` — mounts a `{snippet(args)}` interpolation's builder into a marker-bounded range.
-- `@abide/abide/ui/dom/text` — a text node whose content tracks a reactive read.
-- `@abide/abide/ui/dom/attr` — binds an element attribute to a read (boolean true → bare attribute, false/nullish → removed).
-- `@abide/abide/ui/dom/on` — attaches an event listener whose removal is registered with the ownership scope.
-- `@abide/abide/ui/dom/attach` — runs an `attach={fn}` attachment and registers its optional teardown.
-- `@abide/abide/ui/dom/bindSelectValue` — two-way `<select>` binding that re-applies the selection when the option set changes (late-mounting `{#for}`/async options; `multiple` binds an array).
-- `@abide/abide/ui/dom/each` — keyed `{#for}` runtime: marker-bounded rows reconciled by key.
-- `@abide/abide/ui/dom/eachAsync` — `{#for await}` runtime: rows append/reconcile as the AsyncIterable yields.
-- `@abide/abide/ui/dom/when` — `{#if}` runtime (single-branch swap in a marker-bounded range).
-- `@abide/abide/ui/dom/switchBlock` — `{#switch}` runtime (also `{#if}` chains with `{:else if}` branches).
-- `@abide/abide/ui/dom/awaitBlock` — `{#await}` runtime: pending → resolved/error branch swap, teardown-generation guarded.
-- `@abide/abide/ui/dom/tryBlock` — `{#try}` runtime: synchronous error boundary around a subtree build.
-- `@abide/abide/ui/dom/applyResolved` — consumes a streamed SSR `<abide-resolve>` chunk, swapping it into its await boundary (the bundle-side counterpart of the doc stream's inline scripts).
-- `@abide/abide/ui/dom/mergeProps` — composes a child's props from explicit thunk runs, spread layers, and the trailing children layer.
-- `@abide/abide/ui/dom/spreadProps` — wraps a `{...source}` spread layer so every key resolves to a live value thunk.
-- `@abide/abide/ui/dom/restProps` — the live unconsumed-props object behind `const { …, ...rest } = props()`.
-- `@abide/abide/ui/dom/spreadAttrs` — spreads an object's keys onto a native element (`<div {...rest}>`), keys enumerated once.
-- `@abide/abide/ui/dom/readCall` — guarded method call on a reactive-doc read (the `model.draft.trim()` lowering).
+**RPC** (`src/server/rpc/<name>.ts`). `export const x = METHOD(handler, opts?)`.
+The handler receives the validated args — `StandardSchemaV1.InferOutput<schemas.input>`
+when a schema is present, otherwise its own declared first parameter (or `undefined`
+for a nullary handler); you never pass `<Args, Return>` call generics. It reaches
+request context via `request()` (the inbound `Request`) and `cookies()` (the jar),
+and returns a `Response` — canonically `json(...)` (success body → the caller's
+`Return`), `jsonl(...)`/`sse(...)` (streaming), `error(...)` / `error.typed(...)()`
+(non-2xx, body typed `never`), `redirect(...)`, or a hand-built `Response`
+(`Return` falls back to `unknown`). Typed errors are inferred from the
+`error.typed(...)` branches a handler returns — there is no `errors:` option.
+
+`opts` (`RpcSharedOpts`, all optional): `schemas: { input?, output?, files? }`
+(the ADR-0020 namespace — `input` validates args and drives their type, `output`
+is the success-body schema for OpenAPI 200 / MCP `outputSchema` and never drives
+arg inference, `files` validates multipart File parts and merges them into the
+args bag); `clients: { browser?, mcp?, cli? }` (surface-exposure flags);
+`crossOrigin` (exempt a mutating RPC from the same-origin CSRF gate); `maxBodySize`
+(pre-parse body-byte cap, 413 past it); `timeout` (per-RPC handler deadline in ms,
+a 504 on every surface, composed into `request().signal`). Read helpers (GET/HEAD)
+additionally accept `cache` (`ttl`/`tags`/`throttle`/`debounce`/`shared`) and
+`stream` (replay depth); these are a compile error on the mutating helpers. There
+is **no** `outbox` option. Query/path/form args auto-coerce from the endpoint's
+typed shape (ADR-0028 build-time plan) — no `z.coerce` needed; a value that will
+not parse stays a string so the schema raises an honest 422.
+
+Consume forms (`RemoteFunction`): the bare `fn(args)` **is** the smart read —
+cached, coalesced, SWR-reactive; decodes by Content-Type, throws `HttpError` on
+non-2xx. There is no call-site options argument on the bare call. Members:
+`fn.raw(args, opts?)` (raw `Response`, no decode/throw), `fn.refresh(args?)`
+(refetch keeping the stale value visible), `fn.patch(...)` (in-place cache
+mutation; fetch-only, absent on streaming RPCs), `fn.peek(args?)` (retained value,
+sync), `fn.pending(args?)`, `fn.refreshing(args?)`, `fn.error(args?)` (this RPC's
+last typed error), `fn.isError(caught, 'name')` (typed guard), and client-only
+`fn.watch(handler)` / `fn.watch(args, handler)`. A streaming handler
+(`jsonl`/`sse`) makes the bare call return a `NamedAsyncIterable<Frame>`
+synchronously — `for await (… of fn(args))`, never `await`.
+
+**Socket** (`src/server/sockets/<name>.ts`). `export const x = socket(opts?)`.
+`opts` (`SocketOptions`): `tail` (retention count — kept frames for late joiners
+/ reconnects; server default 1), `ttl` (evict retained frames older than N ms,
+lazy), `clientPublish` (allow publishes over the wire; off by default), `schema`
+(validate publish payloads; flips mcp/cli `clients` on), `clients`. A `Socket<T>`
+extends `AsyncIterable<T>` (bare `for await` is the live stream, no replay) with
+`publish(frame)`, `tail(count?)` (subscription seeded from the retained tail),
+`peek()`, `pending()`/`refreshing()`/`done()`/`error()`, `refresh()`, and
+`watch(handler)`. HTTP face at `/__abide/sockets/<name>`: `GET` reads the retained
+tail, `POST` publishes (only when `clientPublish`).
+
+**Page / layout** (`src/ui/pages/**`). `page` (isomorphic `PageSnapshot` proxy)
+exposes `route`, `params`, `url` (browser-space `URL`, base-prefixed), and
+`navigating`; read a field inside an effect/derived and it re-runs on navigation.
+`url(path, params?, query?)` builds base-correct links; `navigate(path, …)`
+performs typed in-app SPA navigation (params first for `[name]` routes, then
+`{ replace?, keepScroll? }`). A layout renders the active page via `{children()}`.
+
+**`app.ts` / `config.ts`.** `app.ts` default- or named-exports the `AppModule`
+hooks (all optional; `init({ server })` may return a cleanup run on
+SIGINT/SIGTERM; `handle(request, next)` is single middleware; `health(request)`
+merges into `/__abide/health`, runs before `handle`, and is public). `config.ts`
+exports `config` — `env(schema)` (validated, typed, throws on bad config at boot)
+or the unvalidated `Bun.env` floor.
+
+**The isomorphism move.** There is no `cache()` wrapper. A bare smart RPC call
+read inline during SSR is captured in the per-request cache; the runtime
+snapshots each settled entry into a wire-safe form serialized into the HTML, and
+the client seeds its store from it on hydration — the same call hydrates warm
+instead of re-firing. Streaming reads are snapshotted again after the stream
+drains and seeded over the wire.
+
+## .abide template grammar
+
+A `.abide` component is HTML with a leading `<script>` (its component script);
+`<script>` and `<style>` may also sit **inside a control-flow branch**, scoped to
+that branch (a nested `<script>` declares branch-local `state`/`state.computed`/
+`state.linked`, re-seeded per mount, and takes **no** module imports — imports
+live only in the leading script; a nested `<style>` scopes to its sibling
+subtree). A *root* `<style>` is component-scoped. Reactive primitives are reached
+through their own imported bindings (alias-safe) — `state` from `abide/ui/state`,
+`watch` from `abide/ui/watch`, `html` from `abide/ui/html`, `snippet` from
+`abide/shared/snippet` — never through `scope()` (internal plumbing). The one
+ambient reader is `props()` (no import).
+
+Reactive state:
+
+| Form | Meaning |
+|---|---|
+| `state(initial, transform?)` | Writable cell; read/write via `.value`; `transform(next, prev)` gates writes. |
+| `state.computed(fn)` | Read-only cell derived from other cells (lazy, never serialized). |
+| `state.linked(fn, transform?)` | Writable cell reseeded when the thunk's deps change. |
+| `watch(source, handler)` | The single reaction primitive: over a cell, a cell array, a socket/stream, or an RPC; bare `watch(thunk)` is an auto-tracked effect. Client-only. |
+| `props()` | Ambient prop reader: `const { name = fallback, ...rest } = props()`. |
+
+Bindings and directives (attribute kinds `event` / `bind` / `class` / `style` /
+`attach` / spread, plus plain `expression` / static):
+
+| Form | Meaning |
+|---|---|
+| `{expr}` | Reactive text (escaped); an `html`-branded value inserts unescaped raw HTML. |
+| `name={expr}` | Reactive attribute. |
+| `on<event>={fn}` | Event listener (`onclick`, `oninput`, `onsubmit`, …). |
+| `bind:value` / `bind:checked` / `bind:group` | Two-way form binds. |
+| `bind:value={{ get, set }}` | Derived two-way binding. |
+| `class:name={cond}` | Toggle a class. |
+| `style:property={value}` | Set one style property. |
+| `attach={fn}` | Run `fn(element)` at mount; its return is the teardown. |
+| `{...spread}` | Spread an object's keys as attributes (element) or props (component). |
+
+Control flow — mustache `{#…}` blocks (NOT `<template>`):
+
+| Block | Form |
+|---|---|
+| Conditional | `{#if}` / `{:else if}` / `{:else}` / `{/if}` |
+| Keyed list | `{#for item, i of list by key}` / `{/for}` |
+| Async list | `{#for await item of source}` / `{/for}` (over an `AsyncIterable`) |
+| Promise | `{#await p}` / `{:then v}` / `{:catch e}` / `{:finally}` / `{/await}` |
+| Switch | `{#switch subject}` / `{:case v}` / `{:default}` / `{/switch}` |
+| Error boundary | `{#try}` / `{:catch}` / `{:finally}` / `{/try}` |
+| Snippet | `{#snippet name(args)}…{/snippet}`, called `{name(args)}` |
+
+Components are capitalised tags; content nested in them renders where the
+component calls `{children()}` (`{#if children}{children()}{:else}…{/if}` is the
+fallback). The `<slot>` element, the `<template name>` snippet form, and
+`<template if>` / `<template each>` / … control flow were **removed** — a bare
+`<template>` is now an inert element, and any removed form throws a migration
+error. The branch keyword is `{:else if}` (a space).
+
+## Server surface — abide/server/*
+
+### RPC helpers — @documentation rpc
+
+- `@abide/abide/server/GET` — declares a read (GET) RPC; accepts `RpcReadOpts`
+  (shared opts + `cache`/`stream`); query args. Bundler-rewritten; calling the
+  bare helper throws.
+- `@abide/abide/server/POST` — declares a mutating (POST) RPC; `RpcSharedOpts`
+  only (`cache`/`stream` are a compile error); JSON-body (or FormData) args.
+- `@abide/abide/server/PUT` — mutating PUT RPC; body args; `RpcSharedOpts`.
+- `@abide/abide/server/PATCH` — mutating PATCH RPC; body args; `RpcSharedOpts`.
+- `@abide/abide/server/DELETE` — mutating DELETE RPC; query args; `RpcSharedOpts`.
+- `@abide/abide/server/HEAD` — read HEAD RPC alongside GET; query args;
+  `RpcReadOpts`.
+
+### Responses — @documentation response
+
+- `@abide/abide/server/json` — `json(data, init?)`: JSON `TypedResponse<T>` with
+  RPC defaults (`no-store`), wire-encoding Set/Map/bigint/Date; `json(undefined)`
+  → 204. `T` drives `Return` inference.
+- `@abide/abide/server/jsonl` — `jsonl(iterable, init?)`: wraps an
+  `AsyncIterable<Frame>` as `application/jsonl` (one JSON value per line); a
+  generator error emits a final `{"$error":…}` line.
+- `@abide/abide/server/sse` — `sse(iterable, init?)`: wraps an
+  `AsyncIterable<Frame>` as `text/event-stream` with 15s keepalive comments;
+  errors emit an `event: error` frame.
+- `@abide/abide/server/error` — `error(status, message?, init?)`:
+  `text/plain` `TypedResponse<never>`. `error.typed(name, status, schema?)`
+  declares a reusable typed-error constructor driving `fn.isError(e, 'name')`.
+- `@abide/abide/server/redirect` — `redirect(url, status=302, init?)`:
+  `TypedResponse<never>`, accepts relative URLs, `no-store`, status restricted to
+  301/302/303/307/308.
+
+### Request scope — @documentation request-scope
+
+- `@abide/abide/server/request` — `request(): Request` — the in-flight inbound
+  request (ALS-scoped); throws outside a request scope.
+- `@abide/abide/server/cookies` — `cookies(): Bun.CookieMap` — the request's
+  cookie jar; reads parse `Cookie`, writes flush as `Set-Cookie` on return.
+- `@abide/abide/server/server` — `server(): Bun.Server` — the active server; a
+  no-op in-process server for CLI/MCP/test dispatch; throws before init.
+
+### Configuration — @documentation configuration
+
+- `@abide/abide/server/env` — `env(schema)`: validate `Bun.env` against a Standard
+  Schema at module top level (synchronous; all issues at once) and return the
+  typed config; also registers the schema for the launcher setup form.
+
+### Sockets — @documentation sockets
+
+- `@abide/abide/server/socket` — `socket(opts?)` / `socket({ schema })` declares a
+  broadcast topic returning `Socket<T>`; opts `tail`/`ttl`/`clientPublish`/
+  `schema`/`clients` (server-only; the client stub discards them).
+
+### Agent — @documentation agent
+
+- `@abide/abide/server/agent` — `agent(engine, messages): AsyncIterable<AgentFrame>`
+  runs a provider `AgentEngine` against the current request's MCP surface
+  (forwarding caller auth); the handler picks transport via `jsonl`/`sse`. Exports
+  `NeutralMessage`, `AgentFrame`, `AgentSurface`, `AgentEngine` types.
+
+### Server plumbing — @documentation plumbing
+
+- `@abide/abide/server/AppModule` — type of the optional `src/app.ts` hooks
+  (`forwardHeaders`/`init`/`handle`/`handleError`/`health`).
+- `@abide/abide/server/InspectorContext` — type of the capability object core
+  injects into `@abide/inspector` when `ABIDE_ENABLE_INSPECTOR=true`.
+- `@abide/abide/server/rpc/defineRpc` — bundler-emitted RPC builder: resolves
+  `clients`, validates input/files, applies `timeout`, registers the entry.
+- `@abide/abide/server/sockets/defineSocket` — bundler-emitted socket builder:
+  per-subscriber queue + retained tail, optional `ttl`/`schema`, Bun-native
+  fan-out.
+- `@abide/abide/server/prompts/definePrompt` — resolver-emitted prompt builder
+  from `src/mcp/prompts/<name>.md`; registers with the MCP dispatcher.
+- `@abide/abide/server/prompts/renderPromptTemplate` — substitutes `{{name}}`
+  placeholders in a prompt template body (missing args → empty string).
+
+## Isomorphic surface — abide/shared/*
+
+### RPC schema projection — @documentation rpc
+
+- `@abide/abide/shared/withJsonSchema` — `withJsonSchema(schema, toJsonSchema)`
+  attaches a `toJSONSchema()` projection to a Standard Schema whose library lacks
+  one native (feeds OpenAPI / MCP / CLI / setup form).
+
+### Error responses — @documentation response
+
+- `@abide/abide/shared/HttpError` — the error class thrown by a remote call on
+  non-2xx: `status`, `statusText`, raw `response`, optional `kind`/`data` (set for
+  a typed error or a 422 validation failure).
+- `@abide/abide/shared/ValidationErrorData` — type of `HttpError.data` when
+  `kind === 'validation'`: `{ issues, fields }` (raw Standard Schema issues + a
+  field→first-message map).
+
+### Cache mutation — @documentation cache
+
+- `@abide/abide/shared/patch` — `patch(fn, args?, updater)` / `patch({tags},
+  updater)`: reactively mutate the retained value of matching cached reads in
+  place, no network — the optimistic-update / real-time primitive.
+- `@abide/abide/shared/refresh` — `refresh(selector?, args?)`: refetch every
+  matching cached read, keeping the stale value visible (`refreshing()` true)
+  until fresh swaps in.
+
+### Page — @documentation page
+
+- `@abide/abide/shared/page` — `page`: isomorphic reactive `PageSnapshot` proxy
+  (`route`/`params`/`url`/`navigating`); reading a field in a tracking scope
+  re-runs on navigation.
+
+### Probes — @documentation probes
+
+- `@abide/abide/shared/pending` — `pending(source?, args?): boolean` — reactive
+  "no value yet" over cached calls and tail streams.
+- `@abide/abide/shared/peek` — `peek(source, args?)` — the currently-retained
+  value synchronously, triggering nothing; `undefined` when nothing retained.
+- `@abide/abide/shared/refreshing` — `refreshing(source?, args?): boolean` —
+  reactive "holding a value while a fresher source is in flight".
+- `@abide/abide/shared/done` — `done(subscribable): boolean` — reactive terminal
+  read: true once a stream closed.
+- `@abide/abide/shared/online` — `online(): boolean` — reactive connectivity
+  probe (browser online/offline; server reflects the caller's reported state).
+
+### URL — @documentation url
+
+- `@abide/abide/shared/url` — `url(path, ...args): string` resolves any in-app URL
+  base-correctly (RPC query, page params, or asset); external paths pass through.
+  Exports `PathParams` and augmentable `RpcRoutes`/`PageRoutes`/`PublicAssets`.
+
+### Templating — @documentation templating
+
+- `@abide/abide/shared/snippet` — `snippet(payload)` brands a snippet payload so a
+  `{expr}` interpolation mounts it (the compiler wraps a `{#snippet}` body); also
+  exports `SnippetValue` and `Snippet<Args>` types.
+
+### Observability — @documentation observability
+
+- `@abide/abide/shared/health` — `health(): HealthState` — reactive backend-health
+  read (reachability + the app's `health()` fields), reader-driven poll of
+  `/__abide/health`; composes `navigator.onLine`.
+- `@abide/abide/shared/log` — `log`: the unified request-scope-aware logger
+  (`log(...)`, `.warn`/`.error`/`.trace`, `.channel(name)` for a DEBUG-gated
+  channel); TSV by default, JSON under `ABIDE_LOG_FORMAT=json`.
+- `@abide/abide/shared/reachable` — `reachable(host?): Promise<boolean>` —
+  isomorphic outbound reachability HEAD probe, cached per TTL; any response counts
+  reachable, only connection failure/timeout is not.
+- `@abide/abide/shared/trace` — `trace(): string | undefined` — the current
+  request's W3C `traceparent` (server from ALS, browser from `__SSR__`).
+
+### Isomorphic plumbing — @documentation plumbing
+
+- `@abide/abide/shared/createSubscriber` — `createSubscriber(start)`: abide-ui
+  subscriber grounded in the signal core (open-on-first-tracked-read,
+  close-on-last-reader).
+
+## UI surface — abide/ui/* (client-only)
+
+### Reactive state — @documentation reactive-state
+
+- `@abide/abide/ui/state` — `state(initial, transform?)` writable cell (`.value`);
+  members `state.computed(fn)` (read-only derived), `state.linked(fn, transform?)`
+  (writable, reseeded from a thunk), `state.share(key, value)` / `state.shared(key)`
+  (ambient scope context).
+- `@abide/abide/ui/watch` — `watch(source, handler)` the single reaction primitive
+  (cell / cell array / socket-stream / RPC); bare `watch(thunk)` is an auto-tracked
+  effect; returns a scope-tied disposer; SSR-inert.
+- `@abide/abide/ui/props` — `props()` ambient prop reader; compiler-lowered inside
+  a component; throws if called directly.
+
+### Templating — @documentation templating
+
+- `@abide/abide/ui/html` — `html\`…\`` (or `html(string)`) returns branded
+  **unescaped** raw HTML for `{expr}` insertion; interpolations are not
+  auto-escaped; nullish → empty.
+
+### Navigate — @documentation navigate
+
+- `@abide/abide/ui/navigate` — `navigate(path, ...rest)` typed in-app SPA
+  navigation (params first for `[name]` routes, then `{ replace?, keepScroll? }`);
+  builds through `url()`.
+
+### UI plumbing — @documentation plumbing
+
+- `@abide/abide/ui/effect` — `effect(fn)` internal reactive effect (tracks reads,
+  re-runs, returns a disposer); compiler-emitted — authors use `watch`.
+- `@abide/abide/ui/currentScope` — `scope()` resolves the current lexical scope;
+  the internal lowering host the compiler targets.
+- `@abide/abide/ui/enterRenderScope` — `enterScope()` establishes a fresh isolated
+  SSR-render scope, returning the previous.
+- `@abide/abide/ui/exitRenderScope` — `exitScope(previous)` restores the scope
+  `enterScope` saved.
+- `@abide/abide/ui/router` — `router(host, loaders, layoutLoaders?, probe?)` the
+  History-API client router: match, code-split, mount a diffed outlet chain, drive
+  SPA nav with scroll restoration.
+- `@abide/abide/ui/startClient` — `startClient(routes, layoutRoutes?, target)` the
+  client entry: read `window.__SSR__`, seed cache/streamed/warm state, start the
+  router; returns a disposer.
+- `@abide/abide/ui/renderToStream` — `renderToStream(render)` out-of-order SSR
+  streaming generator: shell first, then one `<abide-resolve>` fragment per
+  streaming `{#await}` in completion order.
+- `@abide/abide/ui/remoteProxy` — `remoteProxy(method, url, options?)`
+  bundler-target client substitute for a server RPC (fetch over the network; does
+  the client pre-flight input validation; attaches the real `.watch`).
+- `@abide/abide/ui/socketProxy` — `socketProxy(name)` bundler-target client
+  substitute for a server socket (subscribes over the multiplexed ws).
+- `@abide/abide/ui/settleAsyncCells` — the SSR await-barrier draining the
+  request-scoped pending-cell list; client no-op.
+- `@abide/abide/ui/flight` — server-only flight-starter hoisting a hoistable
+  await's promise into the sync prefix so independent flights overlap.
+- `@abide/abide/ui/isolateCellBarrier` — runs a hoisted child render under its own
+  async-cell barrier so its cells isolate from siblings; client passthrough.
+- `@abide/abide/ui/finalizeStreamedChildren` — the when-to-stream decision run
+  after a component body walk; fills each hoistable child's reserved output slot.
+- `@abide/abide/ui/runtime/withPath` — pushes one escaped render-path segment for
+  the duration of a synchronous build.
+- `@abide/abide/ui/runtime/renderPath` — composes a streamed child's ordinal
+  segment onto the ambient render path and returns the boundary id.
+- `@abide/abide/ui/runtime/escapeKey` — escapes one key to an RFC 6901
+  JSON-Pointer token so a `/`-bearing key survives a `/`-joined render path.
+- `@abide/abide/ui/runtime/nextBlockId` — the next await/try block id in the
+  current render pass, namespaced by render path.
+- `@abide/abide/ui/runtime/blockId` — allocates a render-path-namespaced await/try
+  block id with a per-path document-order counter.
+- `@abide/abide/ui/runtime/enterRenderPass` — marks entry into a render/mount;
+  depth 0 clears the per-path block-id counters.
+- `@abide/abide/ui/runtime/exitRenderPass` — marks exit, unwinding the render-pass
+  depth.
+- `@abide/abide/ui/dom/mount` — mounts a top-level page/layout into a host under an
+  ownership scope; returns a disposer.
+- `@abide/abide/ui/dom/mountChild` — mounts a `<Child/>` as a marker-bounded range
+  (no wrapper element).
+- `@abide/abide/ui/dom/mountStreamedChild` — client adopter for a hoistable child:
+  adopts an inlined range or a streamed boundary.
+- `@abide/abide/ui/dom/mergeProps` — composes a child's props from ordered layers
+  (explicit runs, spreads, trailing `children`), last-wins per key.
+- `@abide/abide/ui/dom/spreadProps` — wraps a `{...source}` spread layer so each
+  key resolves to a live value thunk.
+- `@abide/abide/ui/dom/restProps` — the live `...rest` of a `props()` destructure.
+- `@abide/abide/ui/dom/bindProp` — parent half of a component `bind:prop`
+  (annotates the prop thunk with a write-back channel).
+- `@abide/abide/ui/dom/bindableProp` — child half of a two-way prop (the writable
+  cell the child writes/forwards).
+- `@abide/abide/ui/dom/spreadAttrs` — spreads an object's keys onto a native
+  element (`on<event>` keys attach listeners, others bind as reactive attrs).
+- `@abide/abide/ui/dom/readCall` — guarded method call on a reactive-document read
+  so throws name the authored scope path.
+- `@abide/abide/ui/dom/readCell` — unified read for a `computed`/`linked`
+  reference (async peek / derive call / sync `.value`).
+- `@abide/abide/ui/dom/cellPending` — whether a `{#if}`/`{#switch}` async subject
+  is still loading (render no branch while pending).
+- `@abide/abide/ui/dom/mutateDocContainer` — in-place container mutation lowered to
+  clone-mutate-replace so a patch emits and readers wake.
+- `@abide/abide/ui/dom/hydrate` — adopts server-rendered DOM in place with a claim
+  cursor (attach listeners/effects, no re-render); returns a disposer.
+- `@abide/abide/ui/dom/appendText` — reactive `{expr}` interpolation (escaped text
+  / snippet builder / `html\`\`` raw).
+- `@abide/abide/ui/dom/appendTextAt` — reactive `{expr}` mounted at a skeleton
+  anchor comment, interleaved with element siblings.
+- `@abide/abide/ui/dom/appendSnippet` — mounts a `{snippet(args)}` builder's nodes
+  in a marker-bounded range.
+- `@abide/abide/ui/dom/appendStatic` — a static text node, created or claimed from
+  SSR text.
+- `@abide/abide/ui/dom/cloneStatic` — appends a fully-static bindingless subtree via
+  one cached-template deep clone.
+- `@abide/abide/ui/dom/skeleton` — clones a template and locates its bound
+  holes/anchors for a subtree carrying bindings/control-flow.
+- `@abide/abide/ui/dom/anchorCursor` — positions a skeleton-anchored control-flow
+  block or slot at its `<!--a-->` anchor.
+- `@abide/abide/ui/dom/mountSlot` — mounts a component's `{children()}` content
+  (parent children or fallback) as a marker-bounded range.
+- `@abide/abide/ui/dom/outlet` — a layout's outlet boundary the router fills with
+  the next chain layer.
+- `@abide/abide/ui/dom/attr` — binds an element attribute to `read()` via one
+  effect (`name={expr}`).
+- `@abide/abide/ui/dom/on` — attaches an event listener pinned to the owning scope
+  (`on<event>`).
+- `@abide/abide/ui/dom/attach` — runs an `attach={fn}` against an element and
+  registers its teardown.
+- `@abide/abide/ui/dom/bindSelectValue` — two-way `bind:value` for `<select>`
+  (reactive selection + change write-back; `multiple` = array membership).
+- `@abide/abide/ui/dom/each` — keyed list binding (`{#for … by key}`),
+  marker-range rows reconciled by key with minimal DOM moves.
+- `@abide/abide/ui/dom/eachAsync` — async keyed list over an AsyncIterable
+  (`{#for await}`); rows append as it yields; SSR renders none.
+- `@abide/abide/ui/dom/when` — conditional swappable range (`{#if}`/`{:else}`) with
+  an optional pending state.
+- `@abide/abide/ui/dom/awaitBlock` — await-block runtime across
+  pending/resolved/error branches with SSR resume adoption (`{#await}`).
+- `@abide/abide/ui/dom/tryBlock` — error-boundary block catching thrown/async-cell
+  errors into a catch branch (`{#try}`).
+- `@abide/abide/ui/dom/switchBlock` — multi-branch swappable range (first matching
+  `{:case}` else `{:default}`; also backs `{:else if}` chains).
 
 ## Build / tooling
 
-### Building — `@documentation building`
+### Building — @documentation building
+
+- `@abide/abide/build` — `build(opts?)` builds the client bundle into `dist/` and
+  concurrently writes `src/.abide/*.d.ts`; never throws. Options `cwd`/`minify`/
+  `compress`/`clean`/`exitOnFailure`/`dev`.
+- `@abide/abide/compile` — `compile(opts?)` produces a standalone Bun server
+  executable (runs the client build first to embed assets); returns the binary
+  path.
+
+### Tooling — @documentation plumbing
+
+- `@abide/abide/ui-plugin` — the `abide-ui` `BunPlugin` that loads and compiles
+  `.abide` components (and pulls scoped `<style>` into browser bundles).
+- `@abide/abide/preload` — the Bun preload module registering the UI plugin, the
+  resolver plugin, and the `.css` no-op loader (used by `bunfig` `[test]` and the
+  CLI `--preload`).
+- `@abide/abide/resolver-plugin` — `abideResolverPlugin({ cwd?, embedAssets?,
+  target? })` wiring every `abide:*` virtual module, the `$server`/`$ui`/`$shared`/
+  `$mcp`/`$cli` aliases, and the per-target RPC/socket rewrite (with the
+  client-side server-code-leak guard).
+- `@abide/abide/tsconfig` — the base `tsconfig.app.json` for consuming apps to
+  `extends`.
+
+## Desktop bundle — @documentation bundle
+
+- `@abide/abide/server/appDataDir` — `appDataDir()` returns the bundle's per-user
+  data dir keyed by the injected program name; cwd-independent, pure.
+- `@abide/abide/bundle/BundleWindow` — type of the default export from
+  `src/bundle/window.ts`: `{ title?, width?, height?, menu?, config? }`.
+- `@abide/abide/bundle/BundleMenu` — `{ label, items: BundleMenuItem[] }`, a
+  top-level bundle menu.
+- `@abide/abide/bundle/BundleMenuItem` — a menu entry: separator, or `emit` (a
+  page `abide:menu` event), or `navigate`.
+- `@abide/abide/bundle/onMenu` — `onMenu(handler)` / `onMenu(name, handler)`
+  subscribes to bundle menu-click events; returns an unsubscribe; inert in a
+  plain tab / SSR.
+- `@abide/abide/bundle/bundled` — `bundled(): boolean` — am I part of the abide
+  desktop bundle (client reads `window.__ABIDE_BUNDLE__`, server the parent-pid
+  env).
+
+## MCP — @documentation mcp
+
+- `@abide/abide/mcp/createMcpServer` — `createMcpServer(opts?)` constructs the
+  framework-generated MCP server bound to the RPC/socket registries; returns
+  `{ handle(request) }` (the `/__abide/mcp` handler). Tools derive from surfaces
+  with `clients.mcp`.
 
-- `@abide/abide/build` — `build({ cwd, … })`: builds the client bundle into `dist/_app` (`.abide` loader, virtual-module resolver, optional Tailwind); production builds also emit `.gz` siblings; staged and atomically swapped so a live dev server never sees a half-built dist.
-- `@abide/abide/compile` — `compile({ cwd, target?, outfile? })`: produces a standalone server executable (runs the client build first and embeds the compressed assets); returns the binary path.
-
-### Tooling plumbing — `@documentation plumbing`
-
-- `@abide/abide/preload` — the Bun preload installing the `.abide` loader, the virtual-module resolver, and a `.css` no-op loader — the same runtime for the server, scripts (`abide run`), and `bun test`.
-- `@abide/abide/resolver-plugin` — the resolver plugin itself: `$`-alias + virtual-module (`abide:*`) resolution, rpc/socket module rewriting, side-crossing guards.
-- `@abide/abide/ui-plugin` — the Bun plugin that compiles `.abide` single-file components to ES modules (layouts flagged by filename; scoped styles bundled into the entry stylesheet).
-- `@abide/abide/tsconfig` — the base tsconfig apps extend (`bundler` resolution, strict, `types: ["bun"]`, erasable syntax only).
-
-## Desktop bundle — `@documentation bundle`
-
-- `@abide/abide/bundle/BundleWindow` — the type of `src/bundle/window.ts`'s default export: window title/size plus custom `menu` entries inserted between the standard Edit and Window menus.
-- `@abide/abide/bundle/BundleMenu` — one top-level custom menu (`label` + `items`).
-- `@abide/abide/bundle/BundleMenuItem` — one menu entry: a divider, an `emit` item dispatching an `abide:menu` CustomEvent into the page (optional Cmd `shortcut`), or a `navigate` item repointing the window itself.
-- `@abide/abide/bundle/onMenu` — `onMenu(handler)` / `onMenu(name, handler)`: subscribes to bundle menu clicks; returns an unsubscribe; inert during SSR and in plain browser tabs.
-- `@abide/abide/bundle/bundled` — `bundled()`: true inside the desktop bundle (client: webview init flag; server: launcher-spawned process), false in a plain browser tab or on a remote server.
-- `@abide/abide/server/appDataDir` — `appDataDir()`: the running bundle's per-user data dir, keyed by the bundler-injected program name; pure path computation, cwd-independent (`ABIDE_DATA_DIR` overrides).
+## Testing
 
-## MCP — `@documentation mcp`
+### Testing — @documentation testing
 
-- `@abide/abide/mcp/createMcpServer` — `createMcpServer(opts?)`: the MCP server behind `/__abide/mcp` — tools derived from every `clients.mcp` rpc and socket (a `<name>-tail` read tool, plus `<name>-publish` under `clientPublish`), prompts from `src/mcp/prompts/`, auth inherited from the inbound request, optional `authorize` hook. Framework-constructed; there is no user-authored server module.
+- `@abide/abide/test/createTestApp` — `createTestApp()` boots the real app on an
+  ephemeral port; returns `{ origin, fetch, rpc, sockets, health, stop,
+  [Symbol.asyncDispose] }` (`rpc`/`sockets` typed by generated d.ts). Use
+  `await using`.
 
-## Testing
+### Testing plumbing — @documentation plumbing
 
-- `@abide/abide/test/createTestApp` — `@documentation testing` — boots the app in-process for `bun test`: typed `app.rpc.<name>` / `app.sockets.<name>` clients (typed via the generated `testRpc.d.ts` / `testSockets.d.ts`), request scope included, no network.
-- `@abide/abide/test/createScriptedSurface` — `@documentation plumbing` — a scripted `AgentSurface` for engine tests: declarative tool stubs in, an MCP surface out, every dispatched call recorded for assertions.
-- `@abide/abide/test/assertAgentFrameConformance` — `@documentation plumbing` — collects an engine's frame stream and asserts the neutral `AgentFrame` contract (exactly one terminal `done`, paired `tool_use`/`tool_result`, string deltas); returns the frames for provider-specific assertions.
+- `@abide/abide/test/createScriptedSurface` — `createScriptedSurface(tools?)` a
+  scripted `AgentSurface` for engine tests; records every `call`.
+- `@abide/abide/test/assertAgentFrameConformance` — collects an engine frame
+  stream and asserts the neutral `AgentFrame` contract (one terminal `done`; every
+  `tool_use` answered), throwing on violation.
 
 ## Generated machine surfaces
 
+Runtime routes the framework serves:
+
 | Route | Serves |
-| --- | --- |
-| `/openapi.json` | The OpenAPI document projected from every rpc's method, URL, and schemas |
-| `/__abide/mcp` | The MCP endpoint (tools from rpcs/sockets, prompts, resources); auth flows from the inbound request |
-| `/__abide/health` | Liveness + identity JSON: framework version, app name/version, plus the app `health(request)` hook's fields; answered ahead of `app.handle` |
-| `/__abide/identity` | Compatibility alias for the same payload with the legacy `abide: true` marker |
-| `/__abide/sockets` | The single multiplexed WebSocket every client socket rides |
-| `/__abide/sockets/<name>` | A socket's HTTP face: `GET` = retained tail as JSON (SSE stream under `Accept: text/event-stream`; `?tail=N` caps/seeds), `POST` = publish gated by `clientPublish`; 404 unless the socket is exposed to mcp/cli |
-| `/__abide/cli` | `GET` = shell install script; `/__abide/cli/<platform>` streams the thin-CLI tarball (cli + server binaries, `.env` baked with `ABIDE_APP_URL`/`ABIDE_APP_TOKEN`) |
-| `/__abide/inspector` | The `@abide/inspector` UI, mounted only under `ABIDE_ENABLE_INSPECTOR=true` |
-| `/__abide/hot/<moduleId>` | Dev-only component hot-module endpoint backing `.abide` HMR |
+|---|---|
+| `/openapi.json` | OpenAPI spec for the public `/rpc/*` surface, built lazily from the frozen RPC registry. |
+| `/__abide/mcp` | MCP endpoint (POST → `mcp.handle`), through the app auth/CSRF pipeline; mounted when an MCP is configured. |
+| `/__abide/health` | Health/identity probe answered ahead of app middleware (framework identity + `app.health()` fields), `no-store`. |
+| `/__abide/identity` | Compatibility alias of the health payload, stamped `{ abide: true }` for legacy probers. |
+| `/__abide/inspector` | Operator inspector UI + data/SSE routes, gated by `ABIDE_ENABLE_INSPECTOR` (optional `@abide/inspector`). |
+| `/__abide/sockets` | WebSocket upgrade for the socket multiplex hub; `/__abide/sockets/<name>` is one socket's HTTP face (GET tail, POST publish). |
+| `/__abide/cli` | GET returns the platform-detecting install script; `/__abide/cli/<platform>` streams the built CLI binary tarball. |
 
 ## Environment variables
 
 | Variable | Effect |
-| --- | --- |
-| `PORT` | Binds that exact port (a collision fails loudly); unset, the server finds an open port from the default |
-| `APP_URL` | The app's public origin and optional mount base path (a bare `/v2` is tolerated); drives `url()` base-prefixing |
-| `ABIDE_APP_URL` | The remote server a thin CLI binary talks to (baked into its downloaded `.env`) |
-| `ABIDE_APP_TOKEN` | Bearer token the thin CLI sends; baked into the downloaded `.env` when the download request was authenticated |
-| `ABIDE_CLIENT_TIMEOUT` | Default browser-side rpc timeout in ms — read at server boot, shipped to the client via the SSR payload |
-| `ABIDE_DATA_DIR` | Overrides the per-user data directory on every platform |
-| `ABIDE_ENABLE_INSPECTOR` | `true` mounts `@abide/inspector` at `/__abide/inspector` (the package must be installed) |
-| `ABIDE_IDLE_TIMEOUT` | Bun per-connection idle timeout in seconds (default 10) |
-| `ABIDE_INSPECT` | Enables right-click → Inspect in the desktop bundle's webview |
-| `ABIDE_LOG_FORMAT` | `json` renders one JSON object per log line (default: tab-separated tsv) |
-| `ABIDE_MAX_REQUEST_BODY_SIZE` | Server-wide max request body bytes (a per-rpc `maxBodySize` refines it) |
-| `ABIDE_REACHABLE_TTL` | `reachable()` poll cadence / freshness in ms (default 30000) |
-| `ABIDE_REACHABLE_TIMEOUT` | `reachable()` per-probe bound in ms (default 3000) |
-| `DEBUG` | Channel-gated diagnostics (`DEBUG=abide:rpc`, `abide:sockets`, `abide:build`, …); `DEBUG=-abide` silences the framework's own channel |
+|---|---|
+| `PORT` | Exact TCP port to bind; unset/invalid scans from 3000. |
+| `APP_URL` | Derives the server's mount base path from its pathname (e.g. `/v2`). |
+| `ABIDE_APP_URL` | Default server URL the CLI connects to; its pathname sets the mount base. |
+| `ABIDE_APP_TOKEN` | Sent as `Authorization: Bearer <value>` on CLI→server requests. |
+| `ABIDE_APP_DIR` | Overrides the dir the server serves chunks/shell/assets from (set per dev build generation). |
+| `ABIDE_DATA_DIR` | Overrides the app data directory on all platforms, used as-is (no program-name suffix). |
+| `ABIDE_CLIENT_TIMEOUT` | RPC client timeout in ms (1–600000), shipped to the browser transport. |
+| `ABIDE_MAX_REQUEST_BODY_SIZE` | Server-wide max request body size. |
+| `ABIDE_IDLE_TIMEOUT` | Bun per-connection idle timeout in seconds (default 10). |
+| `ABIDE_LOG_FORMAT` | `json` renders log records as JSON instead of TSV. |
+| `ABIDE_ENABLE_INSPECTOR` | `true` mounts the opt-in operator inspector UI/routes. |
+| `ABIDE_INSPECT` | Enables webview devtools/inspect for desktop bundles. |
+| `ABIDE_DEV_SURFACE` | `1` forces the worker to print its surface map (set by the dev orchestrator). |
+| `DEBUG` | npm-debug-style channel gate for diagnostic log channels (e.g. `abide:cache`, `-abide`). |
 
 ---
 
-This file mirrors `package.json`'s `exports`; after adding or renaming an
-export, run `bun run packages/abide/scripts/readmeSurfaces.ts` and regenerate.
+Mirrors `package.json`'s `exports`; run
+`bun run packages/abide/scripts/readmeSurfaces.ts` after adding or renaming an
+export to keep this map honest.