@belte/belte 0.19.0 → 0.19.2

package/README.md

@@ -11,251 +11,280 @@ bundler swaps the runtime per target.
 // src/server/rpc/getPost.ts — the filename is the export, the URL, and the command name
 import { GET } from '@belte/belte/server/GET'
 import { json } from '@belte/belte/server/json'
-import { z } from 'zod'
 
-export const getPost = GET(async ({ id }) => json(await db.post(id)), {
-    inputSchema: z.object({ id: z.string() }),
-})
+export const getPost = GET<Post, typeof schema>(
+    async ({ id }) => json(await db.post(id)),
+    { inputSchema: schema },
+)
 ```
 
 That one file is now all of this:
 
 ```text
-src/server/rpc/getPost.ts
-  export const getPost = GET(fn, { inputSchema })
-        │
-        ├─ browser   await cache(getPost)({ id })          decoded body, SSR-hydrated
-        ├─ http      GET /rpc/getPost?id=…                 the wire endpoint
-        ├─ openapi   GET /rpc/getPost in /openapi.json     operationId: getPost
-        ├─ mcp       tool "getPost"                        read-only ⇒ auto-exposed
-        └─ cli       app getPost --id …                    schema ⇒ typed flags
+                 src/server/rpc/getPost.ts
+                            │
+   ┌────────────┬──────────┼───────────┬──────────────────┐
+ browser       http        cli         mcp            openapi
+ cache(getPost) GET         myapp        getPost        GET /rpc/getPost
+   ({ id })     /rpc/        getPost      tool           operation in
+                getPost?     --id 1       (read-only)    /openapi.json
+                id=1
 ```
 
-A bare `GET(fn)` always reaches browser, http, and openapi. The MCP tool and CLI
-subcommand turn on once the declaration carries a Standard Schema — the schema is
-what makes a machine-facing surface safe to advertise.
-
-Don't take the diagram's word for it — belte prints the exact map at boot
-(`DEBUG=belte`):
+Don't take the diagram's word for it — with `DEBUG=belte`, belte prints the exact
+map at boot:
 
 ```sh
 pages:
-  page                   layout  error
-  /                      /       ·
-  /posts/[id]            /       ·
+  page         layout  error
+  /            ·       ·
+  /posts/[id]  ·       ·
 sockets:
-  socket                 schema  browser  mcp  cli  publish
-  chat                   ✓       ✓        ✓    ✓    ✓
+  socket  schema  browser  mcp  cli  publish
+  chat    ✓       ✓        ✓    ✓    ✓
 rpcs:
   http                   schema  browser  mcp  cli
   GET   /rpc/getPost     ✓       ✓        ✓    ✓
-  POST  /rpc/createPost  ✓       ✓        ·    ✓
-  GET   /rpc/listFeed    ·       ✓        ·    ·
+  POST  /rpc/createPost  ✓       ✓        ✓    ✓
 ```
 
-Scan a column to spot a missing surface, a row to see one declaration's reach. A
-schemaless verb (`listFeed`) reddens its `schema` cell — its machine surfaces are
-gated until a schema lands. Every surface a function reaches is auditable in one
-place; no surface is ever exposed by accident.
+The `schema` column is the gate: a verb or socket with no schema reddens its `·`
+there, because that is what holds its `mcp`/`cli` columns off. Every surface a
+function reaches is auditable in one place — no surface is ever exposed by accident.
 
 ## Why it's built this way
 
-- **Zero runtime dependencies.** `package.json` declares no `dependencies` — only
-  optional `peerDependencies` (`svelte`, and `tailwindcss` / `bun-plugin-tailwind`
-  for styling). Everything else is Web platform and `Bun.*` (`Bun.serve`,
-  `Bun.CookieMap`, `Bun.zstdCompress`, `Bun.YAML`, `Bun.file`).
-- **No magic strings.** The rpc/socket swap is a real tokenizer
-  (`findExportCallSite`) that walks source character-by-character, skipping
-  strings, templates, comments, regexes, and TypeScript generics — so a `GET`
-  inside a docstring or a nested `GET<Map<K, V>>(` is never mistaken for the call.
-- **Safe by default for machines.** A read-only verb (`GET`/`HEAD`) with a schema
+- **Zero runtime dependencies.** belte ships no `dependencies` — only optional
+  peers (`svelte`, and `bun-plugin-tailwind` / `tailwindcss` for styling). The
+  runtime is Bun (`Bun.serve`, `Bun.CookieMap`, `Bun.YAML`, `Bun.zstdDecompress`,
+  `Bun.file`) and Web standards (`Request`/`Response`, `ReadableStream`,
+  `AsyncIterable`, `structuredClone`).
+- **No magic strings.** The bundler finds each `export const x = GET(fn)` with a
+  character-level scanner that skips strings, templates, comments, regexes, and
+  TypeScript generics (`findExportCallSite.ts`) — a `GET` inside a docstring or a
+  `GET<Map<K, V>>(` is never mistaken for the call site.
+- **Safe by default for machines.** A schema-bearing read verb (`GET`/`HEAD`)
   auto-exposes to MCP; a mutating verb (`POST`/`PUT`/`PATCH`/`DELETE`) never does
-  unless you pass `clients: { mcp: true }` explicitly — a model can't delete data
-  just because the handler carries a schema.
+  just because it carries a schema — it requires an explicit `clients: { mcp: true }`
+  (`defineVerb.ts`, `resolveClientFlags.ts`, `isReadOnlyMethod.ts`).
 
 ## Scope — read this before you adopt
 
-- **Bun-only, by design.** `engines.bun >= 1.3.0`. There is no Node fallback; the
-  runtime is built directly on `Bun.serve` and `Bun.*` APIs.
+- **Bun-only, by design.** belte targets `bun >= 1.3.0` and builds on Bun APIs with
+  no Node fallback path.
 - **Svelte-only web surface.** Pages, layouts, and error pages are Svelte 5
-  components; SSR runs through `svelte/server`. There is no other view layer.
-- **Pre-1.0.** The core (rpc, pages, cache, sockets) is the mature center. The
-  machine-facing satellites — MCP, the CLI binary, and the desktop bundle — are
-  newer and move faster. APIs may still shift.
+  components; there is no other view layer.
+- **Pre-1.0.** The core (rpc, sockets, cache, SSR+SPA) is the mature surface; the
+  satellites (`mcp`, `cli`, `bundle`/desktop, `agent`) are newer. Expect change.
+- **No umbrella import.** There is no `.` barrel — every public name has its own
+  path (`@belte/belte/server/GET`, `@belte/belte/shared/cache`, …), so importing one
+  name never drags in side-effecting siblings.
+
+---
 
 ## The mental model
 
 Three ideas carry the whole framework.
 
-1. **One runtime — dev equals build.** `belte dev` and a compiled binary run the
-   same server code over the same registry. There is no separate dev path to
-   diverge from production.
-2. **Declare once.** A file under `src/server/rpc/` holds exactly one
-   `export const <name> = VERB(fn)`. The filename is the export name, the URL
-   (`/rpc/<path>`), the MCP tool name, and the CLI subcommand. The HTTP verb you
-   import picks the method.
-3. **The namespace marks the side.** The import path tells you where a name runs.
+1. **One runtime.** Dev and build run the same code through the same plugins; the
+   only thing that changes per target is which runtime the bundler swaps in behind a
+   declared name.
+2. **Declare once.** A file under `src/server/rpc/` exports exactly one verb; its
+   filename is the export name, its path is the URL, and its schema decides which
+   surfaces it reaches. Same for `src/server/sockets/`.
+3. **The namespace marks the side.** The first path segment tells you where a name
+   runs.
 
-| Namespace | Runs | Public names |
+| namespace | runs on | examples |
 | --- | --- | --- |
-| `belte/server/*` | server only | `GET` `POST` `PUT` `PATCH` `DELETE` `HEAD`, `socket`, `json` `jsonl` `sse` `error` `redirect`, `request` `cookies` `server` `env` `appDataDir`, `AppModule` |
-| `belte/browser/*` | client only | `page` `navigate` `subscribe` |
-| `belte/shared/*` | isomorphic | `cache` `HttpError` `withJsonSchema` `bundled` `log` |
-| `belte/bundle/*` | desktop launcher | `BundleWindow` `BundleMenu` `BundleMenuItem` `onMenu` |
-| `belte/test/*` | tests | `createTestClient` `clearVerbRegistry` |
-
-There is no umbrella `index.ts` and no `.` export. Every public name has its own
-module path (`belte/server/json`, `belte/shared/cache`, …), so importing one name
-never drags a side-effecting sibling into the bundle. `shared/*` names are the
-same callable with the same behaviour on both sides; the bundler swaps only the
-underlying runtime.
+| `server/*` | server only | `server/GET`, `server/socket`, `server/json`, `server/request`, `server/cookies`, `server/env`, `server/agent` |
+| `browser/*` | client only | `browser/page`, `browser/navigate`, `browser/subscribe` |
+| `shared/*` | isomorphic — same callable, same behaviour both sides | `shared/cache`, `shared/HttpError`, `shared/withJsonSchema`, `shared/bundled` |
+| `bundle/*` | desktop bundle | `bundle/BundleWindow`, `bundle/onMenu`, `bundle/BundleMenu` |
+
+No `index.ts` barrels anywhere. Each import is its own module path.
 
 ## One function, every surface
 
-A single schema-bearing verb, consumed from all five surfaces.
+A single schema-bearing verb, consumed five ways. Declare it once:
 
 ```ts
-// src/server/rpc/createOrder.ts
-import { POST } from '@belte/belte/server/POST'
+// src/server/rpc/getPost.ts
+import { GET } from '@belte/belte/server/GET'
 import { json } from '@belte/belte/server/json'
 import { z } from 'zod'
 
-export const createOrder = POST(async ({ sku, qty }) => json(await orders.create(sku, qty)), {
-    inputSchema: z.object({ sku: z.string(), qty: z.number() }),
-    clients: { mcp: true }, // a mutating verb must opt into MCP explicitly
-})
+const schema = z.object({ id: z.string() })
+
+export const getPost = GET<Post, typeof schema>(
+    async ({ id }) => json(await db.post(id)),
+    { inputSchema: schema },
+)
 ```
 
-```svelte
-<!-- browser: SSR + hydrate -->
-<script lang="ts">
-    import { cache } from '@belte/belte/shared/cache'
-    import { createOrder } from '$server/rpc/createOrder'
-    const result = $derived(await cache(createOrder)({ sku: 'A1', qty: 2 }))
-</script>
+Now consume it.
+
+```ts
+// browser / SSR — same callable, bundler-swapped runtime
+const post = await cache(getPost)({ id })
 ```
 
 ```sh
-# http
-curl -X POST localhost:3000/rpc/createOrder -d '{"sku":"A1","qty":2}'
+# http — args on the query string for a GET
+curl 'http://localhost:3000/rpc/getPost?id=42'
+```
 
-# cli (schema → flags)
-app createOrder --sku A1 --qty 2
+```sh
+# cli — the thin client turns it into a subcommand with schema-derived flags
+myapp getPost --id 42
+```
 
-# mcp — tool "createOrder", dispatched at POST /__belte/mcp
+```json
+// mcp — POST /__belte/mcp, tools/call
+{ "method": "tools/call", "params": { "name": "getPost", "arguments": { "id": "42" } } }
+```
 
-# openapi — POST /rpc/createOrder, operationId createOrder, in /openapi.json
+```sh
+# openapi — the operation is in the generated document
+curl http://localhost:3000/openapi.json
 ```
 
+`getPost` is read-only and carries a schema, so all five light up automatically. A
+mutating verb would expose `http`, `openapi`, and `browser` by the same rules, but
+hold `mcp` off until you opt in.
+
+---
+
 ## Server
 
 ### Server / rpc
 
 #### Declaring
 
-Each file under `src/server/rpc/` exports one verb-bound function. Import a verb
-helper from its own path: `belte/server/GET`, `.../POST`, `.../PUT`, `.../PATCH`,
-`.../DELETE`, `.../HEAD`.
+A verb helper rewrites `export const x = VERB(fn, opts?)` into a server handler (or
+a browser fetch stub). One export per file.
 
 ```ts
-type Verb = <Return = unknown, InputSchema = StandardSchemaV1>(
-    handler: (args: InferOutput<InputSchema>) => Response | Promise<Response>,
+type VerbHelper = <Return, InputSchema, FilesSchema>(
+    fn: (args: InferOutput<InputSchema>) => Response | Promise<Response>,
     opts?: {
-        inputSchema?: InputSchema       // validates args; 422 on failure
-        outputSchema?: StandardSchemaV1 // describes the 200 body (OpenAPI + MCP)
-        filesSchema?: StandardSchemaV1  // validates multipart File parts
-        clients?: Partial<{ browser; mcp; cli }>
+        inputSchema?: InputSchema
+        outputSchema?: StandardSchemaV1
+        filesSchema?: FilesSchema
+        clients?: Partial<{ browser: boolean; mcp: boolean; cli: boolean }>
     },
 ) => RemoteFunction<InferInput<InputSchema>, Return>
 ```
 
-| Option | Effect | Default |
+| option | type | effect |
 | --- | --- | --- |
-| `inputSchema` | Validates args (any Standard Schema lib). `Args` infers from it; replies 422 with `{ issues }` on failure. | none |
-| `outputSchema` | Standard Schema for the success body — feeds the OpenAPI 200 response and the MCP tool `outputSchema`. | none |
-| `filesSchema` | Validates the `File` parts of a multipart upload (kept out of the JSON-Schema projection). | none |
-| `clients` | Which surfaces expose the verb: `{ browser, mcp, cli }`. | `browser: true`; `mcp`/`cli` auto-on with a schema (MCP only for read-only verbs) |
+| `inputSchema` | Standard Schema | validates args (422 on failure); projected to OpenAPI / MCP / CLI. Its presence flips on `cli`, and `mcp` for read-only verbs |
+| `outputSchema` | Standard Schema | describes the 200 body in the OpenAPI doc and the MCP tool `outputSchema` |
+| `filesSchema` | Standard Schema | validates multipart `File` parts; kept off the JSON-Schema projection (a `File` has no honest conversion) |
+| `clients` | partial flags | explicit per-surface override; always wins over the computed defaults |
 
-`Args` is inferred from `inputSchema` or from the handler's parameter type; `Return`
-is inferred from the handler's return via the `TypedResponse<T>` brand on the
-response helpers, so `GET(() => json({ ... }))` types end-to-end with no annotation.
+Helpers: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`. Any Standard Schema
+library (zod, valibot, arktype) works without an adapter.
 
-**Response helpers** — one per file under `belte/server/*`. All default to
-`Cache-Control: no-store` (intermediary caches shouldn't memoise rpc replies).
+```ts
+// a mutation must opt into MCP explicitly
+export const createPost = POST<Post, typeof schema>(
+    async (input) => json(await db.create(input), { status: 201 }),
+    { inputSchema: schema, clients: { mcp: true } },
+)
+```
 
-| Helper | Returns | Notes |
+**Response helpers** — each returns a `TypedResponse<T>` whose phantom `T` lets the
+caller-facing return type infer from the handler body.
+
+| helper | path | builds |
 | --- | --- | --- |
-| `json(data, init?)` | `application/json` | Like `Response.json` plus the no-store default. |
-| `error(status, message?, init?)` | `text/plain` | `message` defaults to the status reason phrase. Body reaches `HttpError.response.text()` verbatim. |
-| `redirect(url, status?, init?)` | 3xx | Accepts relative URLs; defaults to 302. Statuses `301/302/303/307/308`. |
-| `jsonl(iterable, init?)` | `application/jsonl` | One JSON value per line from an `AsyncIterable`. Errors emit a final `{"$error":"…"}` line. |
-| `sse(iterable, init?)` | `text/event-stream` | One `data:` event per frame, 15s keepalive comments. Errors emit an `event: error` frame. |
+| `json(data, init?)` | `server/json` | `application/json`, `Cache-Control: no-store` by default |
+| `jsonl(iterable, init?)` | `server/jsonl` | JSON Lines stream (`application/jsonl`), one value per line |
+| `sse(iterable, init?)` | `server/sse` | Server-Sent Events stream with a 15s keepalive comment |
+| `error(status, message?, init?)` | `server/error` | `text/plain` error; message defaults to the standard reason phrase |
+| `redirect(url, status?, init?)` | `server/redirect` | 301/302/303/307/308; accepts relative URLs (default 302) |
+
+`jsonl` and `sse` carry generator errors as a final frame (`{"$error": "…"}` /
+`event: error`) with only the message on the wire — the full error is logged
+server-side. Cancellation flows from the consumer into the generator's `for await`
+via `iter.return()`.
 
 **Request-scoped helpers** — resolve only while an SSR render or rpc handler is in
-flight (they throw at module top level or in `app.ts` `init`):
+flight (they throw outside a request scope):
+
+- `request()` (`server/request`) — the inbound `Request`.
+- `server()` (`server/server`) — the active `Bun.serve` instance (a no-op stand-in
+  under in-process CLI / MCP / test dispatch).
+- `cookies()` (`server/cookies`) — Bun's `CookieMap`: a live `Map<string, string>`
+  plus `.set(name, value, options)` and `.delete(name)`, flushed to `Set-Cookie` on
+  return.
 
-- `request()` → the inbound `Request` (`belte/server/request`).
-- `cookies()` → the live `Bun.CookieMap`; `.set`/`.delete` flush as `Set-Cookie`
-  when the handler returns (`belte/server/cookies`).
-- `server()` → the active `Bun.Server` (`belte/server/server`).
+> SSR and MCP call verbs **in-process**, and that path forwards only an allowlist of
+> inbound headers — `cookie`, `authorization`, and the `x-forwarded-*` hints. A
+> handler that reads any other header (e.g. `accept-language`, `x-tenant-id`) during
+> SSR or an MCP call sees nothing unless you extend the list via the `forwardHeaders`
+> export in `src/app.ts`.
 
-In-process calls (SSR, MCP, CLI) forward only an allowlist of inbound headers onto
-the synthesized rpc `Request`: `cookie`, `authorization`, `x-forwarded-for`,
-`x-forwarded-proto`, `x-forwarded-host`. Every other header is dropped. Extend the
-allowlist with the `forwardHeaders` export in `src/app.ts` (e.g. `accept-language`,
-`x-tenant-id`).
+**Multipart uploads** — a body verb with `filesSchema` receives the validated text
+fields merged with the `File` parts; call it with a `FormData`:
 
-**Multipart uploads** — pass `filesSchema` alongside `inputSchema`. The handler
-receives the validated text fields merged with the validated `File` parts; the
-call site sends a `FormData`. Files stay out of `inputSchema`, so its JSON-Schema
-projection (OpenAPI/MCP/CLI) never has to model a binary.
+```ts
+export const upload = POST(
+    async ({ title, file }) => json(await store(title, file)),
+    { inputSchema: z.object({ title: z.string() }), filesSchema: z.object({ file: z.instanceof(File) }) },
+)
+```
 
-**`withJsonSchema`** — attaches a `toJSONSchema()` projection to a schema whose
-library doesn't expose one (Zod 4 / Effect / Arktype carry their own):
+**Schemas without `toJSONSchema()`** — wrap once at the declaration so the OpenAPI
+doc, MCP tools, and CLI flags can read it:
 
 ```ts
 import { withJsonSchema } from '@belte/belte/shared/withJsonSchema'
-export const fn = POST(handler, { inputSchema: withJsonSchema(vSchema, (s) => toJsonSchema(s)) })
+const schema = withJsonSchema(valibotSchema, (s) => toJsonSchema(s))
 ```
 
 #### Consuming
 
-A verb's value is a `RemoteFunction` with the same call signature on both sides.
+A `RemoteFunction` is one callable with two siblings:
 
-| Form | Resolves to | On non-2xx |
+| form | resolves to | use |
 | --- | --- | --- |
-| `fn(args)` | the Content-Type-decoded body (`Promise<Return>`) | throws `HttpError` |
-| `fn.raw(args)` | the underlying `Response` | no throw — inspect status/headers/body |
-| `fn.stream(args?)` | a `Subscribable<Return>` view of the body (SSE/JSONL frames, or the decoded body once) | surfaced via `subscribe.error` |
+| `fn(args)` | decoded body (`Promise<Return>`); throws `HttpError` on non-2xx | the default call |
+| `fn.raw(args)` | the underlying `Response` | status / headers / manual streaming |
+| `fn.stream(args)` | a `Subscribable<Return>` | frame-by-frame consumption via `subscribe()` |
 
 ```ts
-const post = await getPost({ id })          // decoded body, throws HttpError on 4xx/5xx
-const res = await getPost.raw({ id })        // Response; res.status, res.headers
-const live = orderFeed.stream({ since })     // Subscribable — pass to subscribe()
+import { HttpError } from '@belte/belte/shared/HttpError'
+
+try {
+    const post = await getPost({ id })
+} catch (err) {
+    if (err instanceof HttpError && err.status === 404) {
+        // err.response is the raw Response
+    }
+}
 ```
 
-**`HttpError`** (`belte/shared/HttpError`) carries `status`, `statusText`, and the
-raw `response` so a call site can render error UI without opting into `.raw`.
-
-**OpenAPI** — every verb is described at `/openapi.json` (OpenAPI 3.1) regardless
-of which machine clients it advertises. `GET`/`DELETE`/`HEAD` args become query
-parameters; `POST`/`PUT`/`PATCH` args become a JSON request body (or
-`multipart/form-data` when `filesSchema` is set). `operationId` is the
-folder-prefixed command name.
+The HTTP surface is always on, independent of the other clients. The OpenAPI 3.1
+document for every verb is served at `/openapi.json`.
 
 ### Server / sockets
 
-A bidirectional named broadcast primitive. One file per socket under
-`src/server/sockets/`; import the helper from `belte/server/socket`.
+A WebSocket-backed pub/sub topic. Every socket multiplexes onto one
+framework-owned connection per client at `/__belte/sockets` — user code never
+touches the raw ws lifecycle.
+
+#### Declaring
 
 ```ts
-type socket = <T>(opts?: {
-    history?: number          // messages replayed to a new subscriber (default 0)
-    ttl?: number              // ms; history entries older than this are evicted lazily
-    clientPublish?: boolean   // allow clients to publish over the wire (default false)
-    schema?: StandardSchemaV1 // validates publish payloads; infers T; unlocks mcp/cli
-    clients?: Partial<{ browser; mcp; cli }>
-}) => Socket<T>
+type SocketOptions = {
+    history?: number        // messages replayed to a new subscriber
+    ttl?: number            // ms; history entries past it are evicted lazily on read
+    clientPublish?: boolean // allow clients to publish (off by default)
+    schema?: StandardSchemaV1 // validates publishes; unlocks mcp/cli
+    clients?: Partial<{ browser: boolean; mcp: boolean; cli: boolean }>
+}
 ```
 
 ```ts
@@ -264,296 +293,349 @@ import { socket } from '@belte/belte/server/socket'
 import { z } from 'zod'
 
 export const chat = socket({
+    schema: z.object({ user: z.string(), text: z.string() }),
     history: 50,
     clientPublish: true,
-    schema: z.object({ user: z.string(), text: z.string() }),
 })
 ```
 
-**Publishing** is isomorphic: `chat.publish(msg)` notifies in-process iterators and
-fans out to remote subscribers via Bun's native `server.publish`. With a `schema`,
-publish validates synchronously and throws on a bad payload.
+With a schema, `T` infers from it and publishes validate on the server.
+Schemaless → browser-only; schema present → all surfaces.
+
+#### Publishing
+
+```ts
+chat.publish({ user, text }) // server-side: notifies in-process iterators + broadcasts to ws clients
+```
+
+`publish` is isomorphic — called from the client (via the socket proxy) it sends a
+`pub` frame the server validates and forwards.
+
+#### Consuming
+
+A `Socket<T>` is an `AsyncIterable`: a bare `for await` replays the full history
+buffer then tails live; `.tail(count)` replays the last `count` items (default `0`).
+
+```ts
+for await (const message of chat) {
+    // history first, then live
+}
+
+const recent = chat.tail(10)
+```
+
+In a Svelte component, layer `subscribe()` on top for reactivity (below).
+
+### Server / agent
 
-**Consuming** — a `Socket<T>` is an `AsyncIterable<T>`:
+`agent(engine, messages)` runs a model engine against the app's own MCP surface
+(its gated tools/prompts/resources) and returns the engine's frame stream. The
+handler picks the transport — same as any streaming verb.
 
 ```ts
-for await (const msg of chat) { /* replays history, then tails live */ }
-for await (const msg of chat.tail(10)) { /* last 10, then live */ }
+// src/server/rpc/chat.ts
+import { agent } from '@belte/belte/server/agent'
+import { jsonl } from '@belte/belte/server/jsonl'
+import { engine } from '@belte/anthropic'
+
+const chatEngine = engine({ model: 'claude-opus-4-8', apiKey: config.ANTHROPIC_API_KEY })
+
+export const chat = POST(({ messages }) => jsonl(agent(chatEngine, messages)), { inputSchema })
 ```
 
-`.tail(count)` replays the last `count` items (default `0`, clamped to the configured
-`history`) before tailing. In a Svelte component, layer `subscribe()` on top instead
-of iterating by hand.
+The engine (a `@belte/<provider>` package) only sees the surface in and yields
+frames out, so swapping providers never touches the verb or the UI. Permission is
+decided server-side: the surface is already gated by each verb's `clients.mcp` plus
+its own handler auth.
+
+---
 
 ## Clients
 
 ### Shared
 
-**`cache(fn, options?)`** (`belte/shared/cache`) returns an invoker; calling it
-checks a store and shares the in-flight promise on a hit, or runs `fn` once on a
-miss. `fn` is a verb helper, `fn.raw`, or a plain producer.
+`cache(fn, options?)` (`shared/cache`) returns an invoker; calling it dedupes
+against a store — a shared promise on hit, one invocation on miss. `fn` is a verb
+helper, its `.raw`, or a plain producer returning a `Promise`.
 
 ```ts
-type cache = (fn, options?: {
-    ttl?: number              // ms past resolve: omitted = forever, 0 = dedupe only
-    scope?: string | string[] // tags for grouped cache.invalidate({ scope })
-    global?: boolean          // process-level store instead of request-scoped (server)
-    invalidate?: { throttle?: number } | { debounce?: number } // coalesce refetches
-}) => (args?) => Promise<Return>
+type CacheOptions = {
+    ttl?: number                 // ms past resolve; omitted = forever, 0 = dedupe-only
+    scope?: string | string[]    // tags for grouped cache.invalidate({ scope })
+    global?: boolean             // process-level store instead of per-request
+    invalidate?: { throttle?: number } | { debounce?: number } // coalesce invalidations (stale-while-revalidate)
+}
 ```
 
 ```ts
-// server (SSR) or client
-const post = await cache(getPost)({ id })        // decoded body
-const res  = await cache(getPost.raw)({ id })     // raw Response, same cache key
-const rates = await cache(fetchRates)()           // plain producer (hoist for dedupe)
+// server (request-scoped store by default — per-user data never leaks across requests)
+const post = await cache(getPost)({ id })
+
+// browser (one tab store)
+const post = $derived(await cache(getPost)({ id }))
 ```
 
 `cache.invalidate(selector?)`, `cache.pending(selector?)`, and
-`cache.refreshing(selector?)` share one selector grammar: omitted = all, a function
-= that function's calls, `{ scope }` = a tagged group. Keys are auto-derived from
-`method + url + args` (or `producer-ref + args`); arg keys distinguish `Date`,
-`Map`, `Set`, and `bigint` from look-alike values via `canonicalJson` (a `Date`
-never aliases its ISO string; a `Map` never aliases a plain object).
+`cache.refreshing(selector?)` share one selector grammar: no arg = everything, a
+function = that function's calls, `{ scope }` = a tagged group.
 
-**SSR mode is chosen by how you read** — per Svelte's `{#await}` rule:
+**SSR mode is decided by how you read**, per Svelte's `{#await}` rule:
 
 ```svelte
-<script>const post = await cache(getPost)({ id })</script>  <!-- blocks render → inlined in initial HTML -->
+<!-- top-level await → blocks render → value baked into the initial HTML -->
+<script>const post = await cache(getPost)({ id })</script>
 
-{#await cache(getPost)({ id }) then post}                    <!-- pending → shell flushes, value streams in -->
-    {post.title}
-{/await}
+<!-- {#await} → shell flushes now, value streams in on the same response -->
+{#await cache(getPost)({ id }) then post}…{/await}
 ```
 
-A top-level `await` flips the whole component instance into await-everything mode;
-to mix blocking and streaming reads, isolate each blocking read in its own child
-component. Reactivity is implicit — the invoker registers the surrounding
-`$derived`/`$effect` via `createSubscriber`, so `cache.invalidate` re-runs it.
-
-**`bundled()`** (`belte/shared/bundled`) returns whether the code is running inside
-the desktop bundle — `true` in the bundle's webview or its embedded server process,
-`false` in a plain browser tab or a standalone server binary. Same name, same
-meaning on both sides; each side detects it differently (client: the webview's init
-script; server: the launcher's `BELTE_PARENT_PID`). Branch UI or behaviour on it
-without threading a flag through your code.
+There is no `ssr` option — the consumption form is the switch. (A top-level await
+flips Svelte's whole component instance into await-everything mode, so isolate
+blocking and streaming reads in separate components.)
 
-### Browser
+Cache keys are derived with `canonicalJson.ts`, which tags types so they never
+collide: a `Date` never equals the string of its ISO form, a `Map` never equals a
+plain object, and `Set`/`bigint`/`-0` each key distinctly.
 
-**Pages** are Svelte 5 components. Routing is file-based under `src/browser/pages/`:
-every leaf lives in its own folder as `page.svelte`, `layout.svelte`, or
-`error.svelte`. Dynamic segments use `[id]` / `[...rest]` folder names.
+`HttpError` (`shared/HttpError`) carries `status`, `statusText`, and the raw
+`response` for error UI without opting into `.raw`.
 
-- **Layouts** are nearest-only: the deepest `layout.svelte` ancestor wraps a page.
-- **Error pages** (`error.svelte`) render server-side for a 404 (unknown route) or
-  a throw during a page render, nearest-only, with `{ status, message, stack }`
-  props. The document ships static (no hydration).
+### Browser
 
-**`navigate(href, options?)`** (`belte/browser/navigate`) is the SPA navigation
-entry point.
+- **Pages** are folder-based Svelte 5 components: `src/browser/pages/**/page.svelte`,
+  the URL is the directory path. `[name]` is a dynamic param, `[...rest]` a
+  catch-all; params arrive as `$props`.
+- **Layouts** are `layout.svelte` files; the nearest ancestor wraps a page
+  (nearest-only, not nested chains).
+- **Error pages** are `error.svelte` files (nearest-only); they render on the server
+  for an unknown route (404) or a throw during render, receiving `{ status, message }`.
 
 ```ts
-type navigate = (href: string, options?: { replace?: boolean; scroll?: boolean }) => Promise<void>
+// shared/cache reactivity is implicit — createSubscriber drives the lifecycle
+const post = $derived(await cache(getPost)({ id }))
 ```
 
-A same-pathname change (search/hash only) skips the network round-trip; a
-cross-origin or non-SPA target hard-navigates cleanly.
+**`subscribe(subscribable)`** (`browser/subscribe`) reactively reads a streaming
+source — a `Socket<T>` or `fn.stream(args)`. The first `$derived` read opens the
+underlying iterator; the last to stop reading closes it; readers of the same key
+share one subscription.
 
-**`page`** (`belte/browser/page`) is reactive route state — a discriminated union
-on `route`, so narrowing `page.route` types `page.params`.
+```svelte
+<script>
+import { subscribe } from '@belte/belte/browser/subscribe'
+const latest = $derived(subscribe(chat))                       // socket
+const tick = $derived(subscribe(tickFeed.stream({ to: 5 })))   // rpc stream
+const err = $derived(subscribe.error(chat))                    // surfaced, never thrown
+const status = $derived(subscribe.status(chat))                // 'pending' | 'open' | 'done' | 'error'
+</script>
+```
 
-| Field | Type | Notes |
-| --- | --- | --- |
-| `page.route` | the matched route key | discriminant |
-| `page.params` | param shape for that route | typed from the generated routes |
-| `page.url` | live `URL` | reassigned on every nav so `$derived` re-runs |
+`subscribe` is a no-op during SSR — seed initial HTML with `cache()` against an
+HTTP verb, then layer `subscribe()` for live updates after hydration.
 
-**`subscribe(subscribable)`** (`belte/browser/subscribe`) reactively reads a
-streaming source — a `Socket<T>` or `fn.stream(args)`:
+**`navigate(href, options?)`** (`browser/navigate`) does SPA navigation:
 
-```svelte
-<script lang="ts">
-    import { subscribe } from '@belte/belte/browser/subscribe'
-    import { chat } from '$server/sockets/chat'
-    const latest = $derived(subscribe(chat))             // T | undefined
-    const status = $derived(subscribe.status(chat))      // 'pending' | 'open' | 'done' | 'error'
-    const err = $derived(subscribe.error(chat))          // Error | undefined
-</script>
+```ts
+type NavigateOptions = { replace?: boolean; scroll?: boolean }
+await navigate('/posts/42')
 ```
 
-It opens the iterator on the first `$derived` read and closes it when the last
-reader stops; many `$derived`s reading the same source share one subscription
-(deduped by name). It's a no-op during SSR — seed initial HTML via `cache()` against
-an HTTP rpc and layer `subscribe()` on top for live updates after hydration.
+A same-pathname change skips the network round-trip and just reassigns `page.url`;
+a non-SPA target hard-navigates cleanly.
+
+**`page`** (`browser/page`) is reactive `$state`. Narrowing on `page.route` narrows
+`page.params` to the matching shape.
+
+| field | type | meaning |
+| --- | --- | --- |
+| `page.route` | route key | the matched route (e.g. `/posts/[id]`) |
+| `page.params` | params for the route | path params, typed per route |
+| `page.url` | `URL` | live location; reassigned on every navigation |
 
 ### Mcp
 
-The MCP server is fully framework-generated at `/__belte/mcp` (JSON-RPC, protocol
+The MCP server is generated at `/__belte/mcp` (JSON-RPC over HTTP, protocol
 `2025-06-18`) — there is no module to author.
 
-- **Tools** come from every verb with `clients.mcp` (read-only + schema → auto;
-  mutating → explicit `clients.mcp`) and from every mcp-exposed socket: a
-  `<base>-tail` read tool plus a `<base>-publish` tool when `clientPublish` is set.
-  The HTTP verb feeds each tool's annotations (`readOnlyHint`/`destructiveHint`/
-  `idempotentHint`). Tool calls run through the same `verb.fetch` seam as the HTTP
-  router, inheriting forwarded auth headers.
-- **Resources** are files under `src/mcp/resources/`, served under the
-  `belte://resources/<path>` URI namespace (text inline, binary as base64).
-- **Prompts** are `.md` files under `src/mcp/prompts/`. YAML frontmatter carries
-  `description` and an `arguments` list; the body interpolates `{{name}}`
-  placeholders at `prompts/get`.
+- **Tools** come from every verb with `clients.mcp: true` (read-only + schema
+  auto-on; mutations opt in) and every mcp-exposed socket (a `<base>-tail` read tool,
+  plus `<base>-publish` when `clientPublish` is set). The HTTP verb feeds each tool's
+  `readOnlyHint` / `destructiveHint` / `idempotentHint` annotations. Auth inherits
+  from the inbound request.
+- **Resources** are files under `src/mcp/resources/`, served at
+  `belte://resources/<path>` (text inline, binary as base64). No module to author.
+- **Prompts** are `src/mcp/prompts/**.md` files: optional YAML frontmatter
+  (`description`, `arguments`) plus a body interpolated via `{{name}}` placeholders.
 
 ```md
 ---
-description: Summarize a thread
+description: Summarise a thread
 arguments:
   - name: topic
-    description: what to focus on
     required: true
 ---
-Summarize the discussion, focusing on {{topic}}.
+Summarise the discussion about {{topic}}.
 ```
 
 ### Cli
 
-`belte cli` builds a thin remote-client binary (no handler code) that ships the
-compiled server beside it. It talks to a running server over HTTP, or boots a local
-one with `<name> /start`.
+`belte cli` builds a thin remote client — it carries no handler code, talks to a
+running server over HTTP, and ships the compiled server beside it so it can spawn a
+local instance.
+
+- Connection state comes from `BELTE_APP_URL` / `BELTE_APP_TOKEN` (shell env >
+  data-dir `.env` > binary-dir `.env`). A downloaded binary resumes against its
+  baked default.
+- The first positional decides the action: `/`-prefixed verbs manage the connection,
+  a bare word runs an rpc.
 
-| First arg | Action |
+| command | does |
 | --- | --- |
-| `--help` / `-h`, `/help [cmd]` | top-level or per-command help |
-| (none) on a TTY | interactive session, resuming the saved connection |
+| `<cmd> [--flags]` | one-shot rpc against the resumed target |
 | `/connect <url>` | connect to a remote server, open a session |
 | `/start` | boot a local instance, open a session |
 | `/disconnect` | forget the saved connection |
-| `<cmd> [--flags]` | one-shot rpc against the resumed target |
+| `/help [cmd]` | help, per-command with an arg |
+| *(none)* on a TTY | interactive session resuming the saved connection |
 
-Connection target comes from `BELTE_APP_URL` / `BELTE_APP_TOKEN` (precedence: shell
-> data-dir `.env` > binary-dir `.env`). The token sets a `Bearer` auth header, so an
-authenticated server's CLI (and its authenticated binary downloads via
-`/__belte/cli`) work the same.
+Schema-bearing rpcs become subcommands; the JSON Schema types the flags:
 
-Each rpc becomes a subcommand; the input schema derives the flags:
-
-| Schema type | Flag form |
+| property type | flag form |
 | --- | --- |
 | `boolean` | `--name` / `--no-name` |
 | `number` / `integer` | `--name <n>` (coerced) |
 | `array` | repeated `--name <v>` |
-| anything else | `--name <value>` |
-| complex / nested | `--json '<args>'`, or pipe a JSON object on stdin |
+| anything else | `--name <value>` (string) |
+| complex shapes | `--json '<args>'`, or pipe a JSON object on stdin |
 
-Optional `src/cli/banner.txt` prints above top-level help; `src/cli/footer.txt`
-below it.
+A running server hands out the client: `GET /__belte/cli` returns a POSIX install
+script (detects OS+arch, downloads the right tarball); `GET /__belte/cli/<platform>`
+streams a gzipped tarball of the platform binary, its sibling server, and a `.env`
+carrying `BELTE_APP_URL` (and `BELTE_APP_TOKEN` if the request was authenticated).
+`src/cli/banner.txt` and `src/cli/footer.txt` wrap the help output.
 
 ### Bundle
 
 `belte bundle` assembles a movable, self-contained desktop app for the host
-platform — the server binary, the launcher, and the webview lib together (a `.app`
-on macOS, a flat directory elsewhere). On macOS the `.app` is **ad-hoc
-code-signed** (`codesign --sign -`, no certificate) so it launches on other Macs; a
-quarantined copy may still need `xattr -cr <app>` once. Full distribution still
-needs a Developer ID signature and notarization.
-
-The app boots into a connect screen that either starts the embedded server or
-connects to a remote one. Customize via files under `src/bundle/`:
-
-- **`window.ts`** default-exports a `BundleWindow` (`belte/bundle/BundleWindow`):
-  `title`, `width`, `height`, custom `menu` (`BundleMenu` / `BundleMenuItem`), and a
-  `config` schema override for the first-run setup form (defaults to the
-  `src/server/config.ts` env schema).
-- **`disconnected.svelte`** overrides the connect screen.
-- **`onMenu`** (`belte/bundle/onMenu`) subscribes to custom menu clicks, returning
-  an unsubscribe for `$effect`:
+platform (a `.app` on macOS, a flat directory elsewhere) — the server binary, the
+launcher, and the native webview lib together. It boots into a connect screen that
+can **start the embedded server** or **connect to a remote one**.
+
+> Bundles are **unsigned** — distributing to other users still needs platform
+> signing/notarization, and macOS Gatekeeper will warn until then.
+
+- **`src/bundle/window.ts`** default-exports a `BundleWindow`:
+
+```ts
+type BundleWindow = {
+    title?: string
+    width?: number
+    height?: number
+    menu?: BundleMenu[]      // custom top-level menus between Edit and Window
+    config?: StandardSchemaV1 // overrides the first-run setup form (defaults to the env schema)
+}
+```
+
+- The standard App/Edit/Window menus plus a File menu (Start / Connect /
+  Disconnect) are always installed. Custom menu items are either an `emit` (a
+  `belte:menu` CustomEvent into the page) or a `navigate` (repoints the window).
+- **`onMenu`** (`bundle/onMenu`) subscribes to those emits inside a Svelte `$effect`:
 
 ```ts
 $effect(() => onMenu('reload', () => location.reload()))
 ```
 
-- **`icon.png`** is the app icon.
+- **`src/bundle/disconnected.svelte`** overrides the default connect screen.
+- **`src/bundle/icon.png`** is the app icon.
+- **`bundled()`** (`shared/bundled`) is `true` when running inside the desktop
+  webview (or, server-side, the embedded server process).
+
+---
 
 ## Some details
 
-**Config / env** — optional `src/server/config.ts` calls `env(schema)`
-(`belte/server/env`) to validate `Bun.env` against a Standard Schema at boot; a
-missing/malformed var fails the boot with every issue listed. belte eager-imports
-the file (no import from your code); import `config` from `$server/config`
-server-side. `appDataDir()` (`belte/server/appDataDir`) returns the bundled app's
-per-user data directory.
+### Config / env
 
-**App hooks** — optional exports from `src/app.ts` (`belte/server/AppModule` types
-them):
+`env(schema)` (`server/env`) validates `Bun.env` against a Standard Schema at boot
+— a missing or malformed variable fails the boot with every issue listed, instead
+of surfacing as `undefined` in a handler. The conventional home is
+`src/server/config.ts`, eager-imported at boot:
 
-| Export | Runs |
-| --- | --- |
-| `forwardHeaders` | extra inbound header names to forward onto in-process rpc Requests |
-| `init({ server })` | once after `Bun.serve` is up; return a cleanup for SIGINT/SIGTERM |
-| `handle(request, next)` | middleware wrapping the request pipeline |
-| `handleError(error, request)` | custom 500 fallback |
+```ts
+// src/server/config.ts
+import { env } from '@belte/belte/server/env'
+import { z } from 'zod'
+export const config = env(z.object({ DATABASE_URL: z.string(), STRIPE_KEY: z.string() }))
+```
+
+The same schema drives the desktop bundle's first-run setup form. `appDataDir()`
+(`server/appDataDir`) returns the running bundle's per-user data directory.
 
-**Project layout**
+### App hooks
+
+All optional, exported from `src/app.ts`:
+
+| hook | signature | role |
+| --- | --- | --- |
+| `forwardHeaders` | `string[]` | extra inbound header names to forward onto in-process rpc Requests |
+| `init` | `({ server }) => void \| (() => void)` | boot setup; an optional returned cleanup runs on SIGINT/SIGTERM |
+| `handle` | `(req, next) => Response` | single middleware; mutate the response or branch on the URL |
+| `handleError` | `(error, req) => Response` | catches thrown handler errors |
+
+### Project layout
 
 ```text
 src/
-  app.ts                      optional hooks
+  app.ts                     # optional hooks
   server/
-    config.ts                 optional env(schema), eager-imported at boot
-    rpc/<name>.ts             one verb-bound function per file → /rpc/<path>
-    sockets/<name>.ts         one socket per file
-    lib/                      userland (declare your own aliases)
+    config.ts                # env(schema)
+    rpc/<name>.ts            # one verb each → /rpc/<name>
+    sockets/<name>.ts        # one socket each
   browser/
-    app.html                  optional shell override
-    pages/**/page.svelte      routes (layout.svelte, error.svelte nearest-only)
-    public/                   served at the site root
+    pages/**/page.svelte     # routes
+    pages/**/layout.svelte   # nearest-only layouts
+    pages/**/error.svelte    # nearest-only error pages
+    public/                  # static files served at the site root
   mcp/
-    prompts/*.md              MCP prompts
-    resources/**              MCP resources
+    resources/               # belte://resources/<path>
+    prompts/**.md            # MCP prompts
   bundle/
-    window.ts                 BundleWindow config
-    disconnected.svelte       connect-screen override
+    window.ts                # BundleWindow
+    disconnected.svelte      # connect screen override
     icon.png
   cli/
-    banner.txt  footer.txt    CLI help chrome
+    banner.txt
+    footer.txt
 ```
 
-Aliases `$server`, `$browser`, `$shared`, `$mcp`, `$cli` resolve to the top-level
-project directories; `lib/` is userland.
-
-**CLI commands**
+### CLI commands
 
-| Command | Does |
+| command | does |
 | --- | --- |
 | `bunx belte scaffold <name>` | scaffold a new project |
-| `belte dev` | build the client + run the server with browser live-reload |
+| `belte dev` | build + run with hot reload |
 | `belte build` | build the client into `dist/_app/` |
 | `belte start` | run the production server against `dist/` |
 | `belte run <file> [args]` | run a script under the belte preload (same runtime as the server) |
 | `belte compile [--target] [--out]` | build a standalone server executable |
-| `belte cli [--target] [--out] [--platforms a,b,c]` | build the thin CLI binary (ships the server beside it) |
-| `belte bundle` | build a movable, self-contained desktop app (macOS `.app` ad-hoc signed) |
+| `belte cli [--target] [--out] [--platforms]` | build the thin CLI binary |
+| `belte bundle` | build a movable desktop app for this platform |
 
-**Bundling targets**
+### Bundling targets
 
-| Target | Output | Surface |
-| --- | --- | --- |
-| `belte build` | `dist/_app/` client assets | web (with `belte start`) |
-| `belte compile` | one server executable | self-hosted HTTP |
-| `belte cli` | thin client binary + sibling server | CLI / scripting |
-| `belte bundle` | movable app (`.app` on macOS) | desktop |
+`--target` / `--platforms` accept Bun's target triples:
 
-**`public/` files** under `src/browser/public/` are served at the site root,
-bypassing the request scope and middleware.
+| target |
+| --- |
+| `bun-darwin-arm64` |
+| `bun-darwin-x64` |
+| `bun-linux-arm64` |
+| `bun-linux-x64` |
+| `bun-windows-x64` |
 
-**Logging** — `log` (`belte/shared/log`) wraps `console.*` with a `[belte]` prefix
-and per-method/status coloring. `DEBUG` follows the `debug` convention; `DEBUG=belte`
-turns on request logging and prints the boot surface map.
+### Logging
 
-**Environment variables**
-
-| Var | Effect |
-| --- | --- |
-| `PORT` | bind this exact port; unset scans upward from 3000 |
-| `BELTE_IDLE_TIMEOUT` | Bun per-connection idle timeout (seconds; default 10) |
-| `DEBUG` | `belte` enables request logs + the surface map |
-| `BELTE_APP_URL` / `BELTE_APP_TOKEN` | CLI binary's default server + bearer token |
+The shared logger prefixes `[belte]` and colours request lines by method/status.
+`DEBUG=<scope>` enables scoped debug output; **`DEBUG=belte` prints the boot
+surface map** shown at the top of this document — the auditable list of every page,
+socket, and rpc with the surfaces it reaches.