@akanjs/cli 3.0.0-beta.2 → 3.0.0-beta.21

package/guidelines/conventions/conventions.instruction.md

@@ -28,7 +28,7 @@ you fetch on demand — `get_guideline` with the name, or `akan guideline show <
 | name | covers |
 |---|---|
 | `ssrRule` | server-share targets, the `akan.ssr.*` warnings, the client-boundary playbook |
-| `runtimeRule` | `web` / `csr` surfaces, gateway vs solo processes, logging, the generated image, shipped assets |
+| `runtimeRule` | `web` / `csr` surfaces, gateway vs solo processes, logging, the generated image, shipped assets, database modes |
 | `queryRule` | slices and hydration, the generated filter methods, full-text search, cascade removal |
 | `transportRule` | guards across HTTP and websocket, socket identity and cleanup, binary pubsub, mutation verbs |
 | `mcpRule` | MCP configuration, wire behaviour, resource URIs, OAuth metadata, protocol revisions |
@@ -76,6 +76,18 @@ back.
   `*.constant.ts`, `*.store.ts`, and the five module component suffixes (`no-bang-comment-in-client.grit`). Bun
   classifies `//!` and `/*!` as legal comments and keeps them through minification, so the note ships to every
   visitor. Use `// FIXME:` there; `//!` stays legal in server, `srvkit/`, and CLI files.
+- **Never touch `document.cookie`, `localStorage` or `sessionStorage` in app or lib code** (`no-document-cookie.grit`,
+  `no-web-storage.grit`). A native shell serves the page from `app://localhost` on iOS, macOS and Linux, which keeps
+  no cookies: `document.cookie` reads `""` and a write is dropped, so the value exists in the browser and vanishes in
+  the app. Web Storage does work in the shells, but it bypasses the store akanjs picks per platform (the shell's
+  Preferences in an app) and throws during SSR. Use `getCookie` / `setCookie` / `removeCookie`, `storage`, and
+  `secretStorage` for tokens and credentials, all from `akanjs/client`.
+- **Browser APIs an app WebView lacks live in `webkit/`** (`no-web-only-api-outside-webkit.grit`, a warning):
+  `navigator.share` / `canShare` (Android's WebView has none), `navigator.serviceWorker` and
+  `Notification.requestPermission` / `.permission` (no app page has them), `navigator.geolocation` (use
+  `useGeoLocation` from `akanjs/webkit`) and `navigator.vibrate` (iOS has none; use `haptics`). They are legal on the
+  web, so the rule does not ban them: it keeps them in a `webkit/` hook that branches on `isNativeApp()` from
+  `akanjs/client/native`, which is where the app side goes too.
 - **Never return a value from a store action** (`no-return-in-store-action.grit`). Every method of a `store(...)`
   class dispatches through `st.do.<action>()`, typed `void` / `Promise<void>`, so the value is unreachable — write
   it into state with `this.set({ ... })`. A bare `return;` guard, a `return` inside a nested callback, a getter,
@@ -216,6 +228,8 @@ Do not narrate code. Do document the thing the code cannot say. Both halves are
 ## Client / Server Boundaries (`apps/**`, `libs/**`, `pkgs/akanjs/**`)
 
 - Use `"use client";` at the top of client component files.
+- A `"use client"` file re-exports by name (`export { A, B } from "./x"`), never with `export *`: the server knows a
+  client module only by the export names it spells out, so `akan start` and `akan build` stop on a star re-export.
 - Be careful when importing client-only code from page or layout modules.
 - Keep page props serializable unless the existing route pattern clearly allows otherwise.
 - In domain UI the boundary is mechanical, not a judgment call: `Template`, `Zone`, and `Util` are always client components with `"use client"` on line 1; `Unit` and `View` are always server components and never carry the directive.
@@ -273,8 +287,10 @@ are, because those are the ones the server could have done.
    SEO snapshots, prerendering and pre-hydration E2E read, so await what the page needs immediately and stream
    the rest. `xListInY` / `xInsightInY` hold hydrated model instances that React Flight refuses as client props:
    consume them in a server component, never as a `Zone` prop.
-6. **Use named `ReactNode` slots, not just `children`** — `Layout.Navbar` takes `title`, `back`, `left`, `right`,
-   and `children`, so a client shell composes server content in five places instead of absorbing it.
+6. **Use named `ReactNode` slots, not just `children`** — a client shell that takes one slot per region lets a
+   server component supply each of them, instead of absorbing the whole subtree into the bundle. `Layout.Navbar`
+   declares `title` / `left` / `right` alongside `back` and `children`, but renders only the last two today, so
+   copy the shape rather than the component.
 7. **Let the server do the derived work.** Display and predicate logic belongs on `Light<Model>`; enum→class
    lookups belong in a module-scope `as const` map.
 8. **Gate auth on the server** — `getSelf({ unauthorize: "/signin" })` in `_layout.tsx`, before any HTML is sent.
@@ -304,7 +320,7 @@ Full contract: `get_guideline` with `runtimeRule`, or `akan guideline show runti
   rotating log file; nothing supervises it but the orchestrator's probes.
 - **Route prefixes move together or not at all.** `new AkanApp({ prefix, websocketPrefix })` in `main.ts` moves
   the server's routes, the gateway's websocket upgrade and — through the SSR bootstrap script — the
-  `fetchClient` in every tab the server renders. A prebuilt CSR shell or a Capacitor bundle is never rendered by
+  `fetchClient` in every tab the server renders. A prebuilt CSR shell or a native app bundle is never rendered by
   a server, so `api: { prefix, websocketPrefix }` in `akan.config.ts` is what those follow; declare it there too
   when the app ships either. Read the value with `getApiPrefix()` / `getWsPrefix()` from `akanjs/base` — never
   write `/api` or `/ws` as a literal, and never try to hand it down as a React prop: `FetchClient` fixes its
@@ -335,6 +351,14 @@ Full contract: `get_guideline` with `runtimeRule`, or `akan guideline show runti
 - **`assets: { pruneFonts, keepFonts }`** trims from the `dist` copy of `public/` the fonts nothing reads; source
   trees are never touched. A font with `optimize` on is a build input, not a runtime asset. `keepFonts` belongs to
   the `akan.config.ts` that owns the font, written against that scope's own `public/`.
+- **Database modes are `database: { modes: [...] }`** — `single` (SQLite + Solid), `multiple` (one SQLite file on
+  a host volume + Redis), `cluster` (Postgres + Redis). The build carries the drivers of every declared mode and a
+  deployment picks one with `AKAN_DATABASE_MODE` — a declared one, named whenever the build declares several.
+  Where the data lives (`POSTGRES_URL`, `REDIS_URI`, `SQLITE_DATABASE_PATH`) is the deployment's env, ahead of
+  `env.server.ts`. `q.raw` is written in the dialect's own SQL, so an app running in two modes avoids it.
+- **Backups run through the image's own `main.js`**: `bun main.js ops snapshot` / `ops restore` (offline), and
+  `/_akan/ops/*` for a control plane, mounted only when `AKAN_OPS_PUBLIC_KEY` is set and authenticated by a short
+  EdDSA token that key verifies. `GET /_akan/app/info` is public. `operationMode` gates none of it.
 
 ## React Components And Styling (`**/*.tsx`)
 
@@ -357,7 +381,7 @@ Full contract: `get_guideline` with `runtimeRule`, or `akan guideline show runti
   nothing — they covered five control types, keyed on the translated label, and restored over server data.
 - Static class strings stay plain strings. Reach for `cn` only for a conditional or to merge an incoming `className`, and merge the caller last: `cn("base classes", cond && "extra", className)`. `cn` comes from `akanjs/client` (token-aware tailwind-merge) and is the only class-combining function — no `clsx` (removed), no raw `twMerge` imports, no object syntax (`{ x: cond }` → `cond && "x"`).
 - Multi-slot components take extra named props (`wrapperClassName`, `bodyClassName`), never a `classNames` object.
-- Hoist enum→class lookups to a module-scope `as const` map typed `{ [key in cnst.XStatus["value"]]: string }`. Do not use `Record<...>`. Escalate the map to `webkit/` when a second module needs it.
+- Hoist enum→class lookups to a module-scope `as const` map typed `{ [key in cnst.XStatus["value"]]: string }`. Do not use `Record<...>`. When a second module needs it, the classes become a variant axis of a recipe in `ui/Recipe/`; only a map from the enum to another recipe's variant name (`BadgeVariants["variant"]`) moves to `webkit/`.
 - Use `<Link>` from `akanjs/ui` for internal navigation; `<a>` only for `mailto:` and external links.
 
 ## Naming And Language
@@ -421,8 +445,11 @@ stores need none, because state and CRUD actions are generated. The body is thre
 `this.setX(...)` → toast. The optimistic shape is mutate the client model, `void fetch.*`, then commit. Use
 `this.pick(...)` when the value must exist, `this.get()` when it may not, and `this.set({...})` to write. Mutate lists
 through the collection API (`this.set({ xList: xList.set(x).save() })`), not array spread. **An action returns
-nothing** (`no-return-in-store-action.grit`). **Never `import type { RootStore } from "../st"`** — it crashes
-`akan build` with a Bun SSR segfault.
+nothing** (`no-return-in-store-action.grit`). **Reach another store through `this`:**
+`import type { RootStore } from "../st"`, then `(this as unknown as RootStore).logout()` to call its action or
+`(this as unknown as RootStore).set({ … })` / `.get()` to write or read its state. Every store is mixed into one root
+at runtime, so the cast only tells the type what `this` already is. Keep it `import type` — `st.ts` imports every
+store, so a value import is a cycle.
 
 **`<model>.dictionary.ts`** — fixed chain, with empty stages still written:
 `.of() → .model() → .insight() → .query() → .sort() → .enum() → .slice() → .endpoint() → .error() → .translate()`.
@@ -464,6 +491,25 @@ Full contract — credential handshake, room revalidation, socket cleanup scopin
 - **A cleanup registered with `ws.on("disconnect" | "unsubscribe", fn)` is scoped to the call that registered it**
   — a room for a `pubsub` subscribe, the socket for a `message` handler. Cleanup that must happen either way
   registers for both.
+- **A call's deadline is the endpoint's `{ timeout: <ms> }`, and there is nowhere else to put one.** It bounds
+  both ends: the `Timeout` middleware — registered by default, and standing aside for every endpoint that
+  declares none — rejects the call with `base.error.gatewayTimeout`, and the same value is serialized to the
+  client as that call's request budget. Declared nowhere, a call takes the client's own default of **30
+  seconds**, so an endpoint whose real work runs longer (provisioning, a firmware flow, an external
+  orchestration) has to declare one or it dies mid-flight with a transport error that does not say whether the
+  server ever received it. A caller overrides it per call with `fetch.x(…, { timeout })` — `false` waits as long
+  as the runtime will — and an app moves its own default with `fetch.instance.setTimeout(ms)`. An upload is
+  never bounded. **Losing the race does not cancel the work**: the handler runs to completion with nobody
+  holding its result, so a deadline is an answer to the caller, not an undo.
+- **A cached answer is the endpoint's `{ cache: <ms> }`, and only a `query` taking no internal argument may have
+  one.** It is a step of the call, not a middleware, and stands aside for every endpoint that declares nothing.
+  Internal arguments are how a call learns who is asking (`.with(Self)`), so an endpoint that has them answers
+  per caller and one shared entry would be one caller's answer handed to the next — that endpoint and every
+  `mutation` are named in the log and left uncached. The lookup runs after the guards, so a hit reaches only a
+  caller they admitted; what is cached is the handler's result, so `resolveReturn` still masks fields and resolves
+  relations per call; a cache backend that is down is warned about and the call runs uncached. The default
+  middleware chain is `Logging → Timeout → <lib middlewares>`, then guards → internal arguments → cache →
+  handler, and there is no `Retry` middleware.
 
 ### Authorization Defaults
 
@@ -530,8 +576,11 @@ Full contract — filter-arg `ref` pickers, `getQueryMeta` summary counters, `la
   first "more". `isCumulativeOf<Model>` is the mode.
 - **"Is there more" is `hasMoreOf<Model>`, never `count > page * limit`.** It comes from the length of the batch
   the server returned, so it survives `{ insight: false }` and cannot drift from a count a live event moved.
-- **Hydrated vs raw:** server queries return hydrated `cnst.<Model>` instances (with `set`/`save`/`refresh`);
-  client fetch results are raw `GetStateObject` plain data, functions stripped.
+- **Hydrated vs raw:** server queries return hydrated `cnst.<Model>` instances (with `set`/`save`/`refresh`),
+  and so do client fetch results — `FetchClient` parses every return with `crystalize` defaulting to **true**
+  (`pkgs/akanjs/fetch/client/fetchClient.ts`). The raw `GetStateObject` shape is what the `<ref>Obj` /
+  `<ref>ObjList` / `<ref>ObjInsight` handles carry, because those pass `crystalize: false` on purpose so the
+  value can cross the RSC boundary as a client prop.
 - Every filter generates fourteen methods: `list` · `listIds` · `find` · `findId` · `pick` · `pickId` · `exists` ·
   `count` · `insight` · `query` · **`remove`** · **`removeOne`** · **`update`** · **`updateOne`**. The last four
   are query-level writes — one atomic UPDATE, **no hooks**, and therefore no `_postRemove` and no cascade. Use
@@ -569,7 +618,7 @@ Full contract — relevance ordering, `columns` / `weights`: `get_guideline` wit
 - Injected dependencies resolve by field-name convention: a field named `<refName>Service` resolves to the service registered under `<refName>`, and `<refName>Signal` likewise (`pkgs/akanjs/service/injectInfo.ts`).
 - The `Service`/`Signal` suffix is required — the injector strips it to derive the registry lookup key. Name the field after the target refName plus the suffix, not arbitrarily.
 - Preference order inside a service: `service<srv.XService>()` for another module's service · `plug(AdapterClass)` or `plug(StorageAdaptorRole)` for an adapter · `use<T>()` only to reach an `option.ts`-registered legacy singleton · `env(...)` for config.
-- **`memory(...)` takes a scalar or model class, not only a primitive** — `memory(Map, { of: CallStateInput })` serializes through the constant and travels as JSON text, so the Redis and sqlite-backed caches round-trip the same declaration. Never hand-encode JSON into a `String` memory.
+- **`memory(...)` takes a scalar or model class, not only a primitive** — `memory(Map, { of: CallStateInput })` serializes through the constant and travels as JSON text, so the Redis and sqlite-backed caches round-trip the same declaration. Never hand-encode JSON into a `String` memory. A memory is scoped to the service or adaptor that declares it; `ttl` (milliseconds) sets how long each write lives unless the `set` call names its own `expireAt`, and a `Map` entry expires on its own.
 
 ### Adapters — `adapt()` And `plug()`
 
@@ -644,10 +693,14 @@ it.
   (RFC 7591; Cursor's `cursor://` redirect admitted) plus the consent page `libs/shared/page/oauth/consent` — and
   names itself as the issuer, so `/mcp` demands a bearer token, verifies its signature, and refuses one carrying no
   `aud`. A token is the app's own access JWT plus `aud`/`iss`/`client_id`, so `AccountMiddleware` and the guards
-  judge it unchanged; there is no scope. Per-app knobs live in `env.server.*` under `oauth` (`consentPath` and
-  `signinPath` with the basePath, `clients`, `dynamicRegistration`, `allowedRedirectSchemes`, `clientIdMetadata`,
-  `enabled`). `/mcp` reads the `Authorization` header only — a cookie is dropped at the door — and `JWT_SECRET` is
-  mandatory outside `local`, because the derived fallback is forgeable from three public names. A grant is revoked
+  judge it unchanged. The tokens this built-in server mints carry no scope; `auth.scopes` / `AKAN_MCP_SCOPES` are for
+  tokens an external issuer mints, and declared beside this server they refuse every one of its tokens with 403
+  `insufficient_scope`. Per-app knobs live in `env.server.*` under `oauth` (`consentPath` and
+  `signinPath` with the basePath, `clients`, `dynamicRegistration`, `allowedRedirectSchemes`, `accessTokenSeconds`,
+  `clientIdMetadata`, `enabled`, plus `issuer` / `resource` — set those when a tunnel or an edge makes the derived
+  origin wrong, because an MCP client compares the issuer byte for byte). `/mcp` reads the `Authorization` header only — a cookie is dropped at the door — and `JWT_SECRET` (or
+  `security.jwtSecret`) is mandatory whenever `operationMode` is not `local`, because the derived fallback is
+  forgeable from three public names; `AKAN_ALLOW_DERIVED_JWT_SECRET=1` accepts that risk explicitly. A grant is revoked
   whole — `POST /oauth/revoke` (RFC 7009) by the client, `fetch.revokeOAuthConnection(sessionId)` by the account's
   owner, `fetch.listOAuthConnections()` to see them — and a revoked access token is refused at its next call.
 - **A person may, a model may not.** An agent's token names its `client_id` and `aud`; a browser session has
@@ -696,9 +749,12 @@ what every developer must know even when not building one.
   every tool runs in the caller's own browser session, gated by guards and the approval card. Its guard is
   `AgentRelayAccess`, which refuses every call until the app names a guard of its own —
   `option.setAgentAccess(SignedIn)`. **The LLM is configured in `option.ts`, never through the environment**
-  (`option.setLlm({ apiKey, model, host })`). Three providers ship — `DeepseekLlm` (the default, text only),
-  `OpenaiLlm` and `AnthropicLlm` (both read images) — and swapping one in is
-  `option.applyAdaptor(LlmAdaptorRole, AnthropicLlm)`.
+  (`option.setLlm({ apiKey, model, host })`). Two adaptors ship, one per wire: `OpenaiLlm` is the default and
+  speaks the chat-completions dialect to whatever `host` names — OpenAI, DeepSeek, Groq, OpenRouter, Ollama — and
+  `AnthropicLlm` speaks the Messages API and reads a PDF as well as a picture. Both require `model`. A provider
+  neither covers is an `adapt()` class in `srvkit/` implementing `LlmAdaptor`, applied with
+  `option.applyAdaptor(LlmAdaptorRole, TheClass)`; whatever settings it needs beyond `LlmOption` ride `setLlm`
+  too, read back with `use<MyLlmOption>()`.
 - **Declare the tool beside the control that already does it**, never as a separate surface:
   `st.tool("x").desc("…").arg("id", ID).exec(fn)` returns the callable to hand to `onClick` — one handler for the
   person and the agent. Publish it only where the screen already renders the control; a falsy name declares the
@@ -727,6 +783,7 @@ what every developer must know even when not building one.
 - Put display and predicate logic on the `Light<Model>` class rather than in a util module — see Module File Playbook.
 - Defaults are a literal for scalars and a thunk for anything constructed. Arrays are `field([T])`; optional is the postfix `.optional()`.
 - **`field.visual(T)` is a field the page renders and an agent never sees** — a blur placeholder, a rendered HTML body, a serialized geometry. It stays an ordinary stored `property` (persistence, search, forms and the page response untouched) and is stripped wherever a value is masked for an AI caller: every in-page-agent read and every MCP result, along with the MCP readable schema. Unlike `hidden`/`secret` it is cost, not secrecy — nothing is refused over one. Reach for it whenever a field is bulky and useless to a model; that is cheaper than every tool learning to avoid it.
+- **A `field.hidden` / `field.secret` value reads `null` on the client, and the type still declares it.** `SignalContext.resolveReturn` skips both field types while it builds an endpoint's response, and hydration writes `null` over the key rather than leaving it absent — the first branch of the loop in `constant/getDefault.ts`, ahead of the field's own default. So the value is a deliberate `null` behind a type promising a `string`, every use of it typechecks, and the failure lands wherever it is finally dereferenced instead of where it was read. **Guard with `??` or `== null`**: `=== undefined`, a destructuring default and an optional parameter default all catch only a missing key and sail straight past this one. A projection (`pickById(id, { secret: true })`) widens the *server's* read, never the response. If a screen needs the value, the field is neither hidden nor secret; if it only needs to be cheap for a model rather than unseen, that is `field.visual`.
 
 ### Scalar & Field Type Reference
 
@@ -760,7 +817,8 @@ Full contract — the trigger-maintained mirror, tokenizer changes, `AKAN_SEARCH
   backstop, including for a `text` field *underneath* one of those. Do not work around either.
 - The role works on a relation (`image: field(File, { text: "thumb" })`) and on an array; an array of objects
   indexes by leaf key. A field inside a `Map` indexes nothing — there is no fixed path to extract it from.
-- Search runs on sqlite/libsql only. `q.search()` against Postgres throws, loudly, rather than returning every row.
+- Search runs in every database mode — fts5 on SQLite/libSQL, a weighted `tsvector` (`pg_trgm` for `trigram`) on
+  Postgres. The same text matches the same documents; only the order may differ on Postgres.
 
 ### Image & File Fields
 
@@ -809,10 +867,11 @@ shape, so `cascade` never means "related" — it means one of exactly these:
 - Dynamic segments use `[id]`; route groups use directories like `(user)`, `(public)`, `(tab)`, or `(detail)`.
 - **A route file exports one thing**: `export default page()…render(…)` for a page, `layout()…render(…)` for a
   `_layout.tsx`, `rootLayout()…render(…)` for the app's (or a basePath's) root `_layout.tsx`. Every route setting
-  is a stage of the chain — `.param()`, `.search()`, `.config()`, `.head()` / `.metadata()`, `.loading()`;
-  `.notFound()` / `.error()` on a layout; `.fonts()` / `.theme()` / `.manifest()` / `.reconnect()` / `.wsConnect()`
-  / `.layoutStyle()` / `.gaTrackingId()` on the root layout; `.prompt()` on a page. A named export beside the chain,
-  or `page()` in a `_layout.tsx`, fails the build.
+  is a stage of the chain — `.param()`, `.search()`, `.config()`, `.head()`, `.loading()`; `.notFound()` /
+  `.error()` on a layout; `.fonts()` / `.theme()` / `.manifest()` / `.reconnect()` / `.wsConnect()` /
+  `.layoutStyle()` on the root layout; `.prompt()` on a page. A named export beside the chain, or `page()` in a
+  `_layout.tsx`, fails the build. `.head()` takes JSX — `<title>`, `<meta>`, `<link>` — or a function of the
+  route's args returning it; there is no metadata object, and analytics is the app's own script, not a stage.
 - **A page names every `[x]` segment of its path with `.param("x", Type)`** and reads a query key only through
   `.search("k", Type)`. Values arrive typed — `ID`/`String` → string, `Int`/`Float` → number, `Boolean`, `Date` →
   Dayjs, an `enumOf` class → its union, `[T]` → array — a path value the type refuses answers not-found, and a
@@ -855,10 +914,10 @@ export default page()
 
 ## Akan Sync Conventions (`apps/**`, `libs/**`)
 
-- `apps/<appName>` root may only contain these files: `AGENTS.md`, `CLAUDE.md`, `akan.app.json`, `akan.config.ts`, `capacitor.config.ts`, `client.ts`, `main.ts`, `package.json`, `server.ts`, `tsconfig.json`, `tsconfig.tsbuildinfo`.
-- `apps/<appName>` root may only contain these folders: `.akan`, `android`, `common`, `env`, `ios`, `lib`, `mobile`, `page`, `plugin`, `private`, `public`, `script`, `secrets`, `srvkit`, `ui`, `webkit`.
+- `apps/<appName>` root may only contain these files: `AGENTS.md`, `CLAUDE.md`, `akan.app.json`, `akan.config.ts`, `client.ts`, `main.ts`, `package.json`, `server.ts`, `tsconfig.json`, `tsconfig.tsbuildinfo`.
+- `apps/<appName>` root may only contain these folders: `.akan`, `common`, `env`, `lib`, `page`, `plugin`, `private`, `public`, `script`, `secrets`, `srvkit`, `ui`, `webkit`.
 - `libs/<libName>` root may only contain these files: `AGENTS.md`, `CLAUDE.md`, `README.md`, `akan.config.ts`, `akan.lib.json`, `client.ts`, `index.ts`, `package.json`, `server.ts`, `tsconfig.json`, `tsconfig.spec.json`, `tsconfig.tsbuildinfo`.
-- `libs/<libName>` root may only contain these folders: `common`, `env`, `lib`, `page`, `plugin`, `private`, `public`, `srvkit`, `ui`, `webkit`. A library is never booted or packaged as an app, so the run and mobile entries an app carries (`main.ts`, `capacitor.config.ts`, `.akan`, `android`, `ios`, `mobile`, `script`, `secrets`) are rejected there.
+- `libs/<libName>` root may only contain these folders: `common`, `env`, `lib`, `page`, `plugin`, `private`, `public`, `srvkit`, `ui`, `webkit`. A library is never booted or packaged as an app, so the run and mobile entries an app carries (`main.ts`, `.akan`, `script`, `secrets`) are rejected there. A Capacitor-era `ios` / `android` / `mobile` folder or `capacitor.config.*` is refused in an app root too, named as a leftover: the native runtime generates its projects under `.akan/mobile/<target>`.
 - Both allowlists have one source — `pkgs/@akanjs/devkit/workspaceLayout.ts`. `akan sync` (error), `akan doctor`
   (diagnostic), and `akan quality scan` (warning) all read it, so add a new root entry there and mirror it into this
   list, never into one of the three call sites.
@@ -882,12 +941,15 @@ export default page()
 | Folder | Admission test | Naming |
 |---|---|---|
 | `common/` | pure, isomorphic, zero-dependency; may import only sibling `common/*` and `akanjs/base`. Cannot import `Err`, so keep throwing code out of it. | camelCase file, filename equals the single export |
-| `webkit/` | touches `window` / `navigator` / Capacitor, or is a React hook | `use<Thing>.tsx` — `.tsx` even with no JSX |
+| `webkit/` | touches `window` / `navigator` / the native bridge (`akanjs/client/native`), or is a React hook | `use<Thing>.tsx` — `.tsx` even with no JSX |
 | `srvkit/` | touches `node:*`, `Bun`, `process.env`, a secret, or a server SDK | camelCase file, PascalCase class |
-| `ui/` | renders JSX and is not bound to one model | PascalCase component, camelCase sidecar (`swipeCard.util.ts`) |
+| `ui/` | renders JSX, or defines a look (a recipe in `Recipe/`, a lib's `tokens.css`), and is not bound to one model | PascalCase component, camelCase sidecar (`swipeCard.util.ts`), `Recipe/<name>.ts` |
 | `plugin/` | build- or CLI-time `AkanPlugin` | `<name>.plugin.ts`, registered in `akan.config.ts` |
 
 - Hooks return a named object of async closures, never a tuple.
+- `ui/` is the presentation layer — markup and the looks it is built from — so a recipe lives there although it is
+  neither a component nor a hook. Not `webkit/`: its hooks are `"use client"`, the opposite signal for a function
+  server components call. Not `common/`: it cannot import `akanjs/ui`, where `recipe` / `tv` come from.
 - `libs/<lib>/ui/tokens.css` is the one CSS file a lib owns: plain `:root` custom properties for colors that must **not** follow the theme (a vendor brand color, a fixed surface). Every app whose pages reach that lib compiles it automatically, ahead of the app's own stylesheets, so nothing is imported by hand and no app can forget it. Reference them as `bg-[var(--kakao)]`; `@theme` extensions stay in the app stylesheet, because the color vocabulary is closed per stylesheet. Theme-following colors are the app's, not the lib's.
 - A layer-root `index.ts` is generated, but a `ui/<Folder>/index.tsx` that builds a namespace is hand-written source. The distinguishing test is that a generated barrel contains nothing but `export * from "./X";` lines.
 - `ui/<Folder>/index_.tsx` (trailing underscore) is the `"use client"` + `lazy()` boundary, with a server-safe `index.tsx` beside it. Collapsing the pair into one file breaks RSC.
@@ -900,12 +962,15 @@ when two shapes disagree.
 - `children: any` — newer files use `children: ReactNode`.
 - Hard-coded API keys or secrets in source; they belong in `option.ts` or env.
 - Large blocks of commented-out code left in place.
-- Cross-store writes through a `RootStore` cast — it collides with the Bun SSR-bundler segfault.
 - Stale `// TODO: Implement …` comments above implemented methods.
 - `{cond && <X/>}` in JSX, hard-coded Korean bypassing `l()`, and `window.alert(...)` for user feedback.
 - Bare `/* eslint-disable */` blocks — use `// biome-ignore lint/<rule>: <why>`.
 - Raw palette grays such as `text-gray-400` instead of the semantic tokens (`text-foreground/70`).
 
+A store calling `(this as unknown as RootStore).<action>()` or `.set({ … })` over
+`import type { RootStore } from "../st"` is **not** one of these — it is the sanctioned way to reach another store's
+actions and state (see `<model>.store.ts` above).
+
 ## Secrets And Env Safety (`.env`, `infra/**`, `*secret*`, `*credential*`)
 
 - Never print, summarize, commit, or expose real secret values, credentials, tokens, private keys, or `.env` contents.
@@ -924,7 +989,9 @@ when two shapes disagree.
   selected one's log beside it. `Tab` walks every row and `1`-`9` jump to that app (the rail shows each
   app's digit), `↑↓` scroll (shift for a page, `G` back to following),
   `/` greps, `e` shows stderr only, `c` clears, `y` copies, `Y` copies the log path, `o` opens the browser,
-  `r` restarts that app, `q` quits.
+  `r` restarts that app, `q` quits. Under `--share`, `s` copies the public URL — the selected app's, or every
+  app's from the merged row — and the header carries it ahead of the local one, because the line `--share`
+  printed before the view took the terminal is gone by its first repaint.
   **`--plain` prints prefixed interleaved lines instead**, and a pipe, a redirect or an unsized terminal
   downgrades to that on its own.
 - **A supervised session writes `local/apps/<app>/runtime/dev.log`, and that path is how a log gets handed over.**

package/guidelines/fieldRule/fieldRule.instruction.md

@@ -9,6 +9,7 @@ Use this whenever generating constants or scalar constants. It defines the curre
 - `field(Type).optional()` marks a nullable or optional business value when absence is valid.
 - `field.hidden(Type).optional()` is for internal state that should not be treated as a normal public field.
 - `field.secret(Type).optional()` is for sensitive values that should not be selected by default.
+- Neither survives an endpoint response: both are stripped on the way out and hydration writes `null` over the key, while the generated type still declares the field — so a client holds a deliberate `null` behind a type that promises a value, and only `??` / `== null` catch it. A field a browser has to read is neither.
 - `field([Type])` defines arrays; provide empty array defaults when the app expects list operations.
 
 ## Current Akan Patterns

package/guidelines/mcpRule/mcpRule.instruction.md

@@ -189,11 +189,13 @@ export default page()
 - OAuth resource metadata is published at `/.well-known/oauth-protected-resource` (and at that path plus the mount
   path, the spelling most clients try first). `auth.authorizationServers` / `AKAN_MCP_AUTH_SERVERS`,
   `auth.scopes` / `AKAN_MCP_SCOPES`, `auth.resource` / `AKAN_MCP_RESOURCE` and `auth.verify` configure it;
-  `insufficient_scope` is enforced only once scopes are declared. Naming an issuer changes three things at once: a
-  request with no credential is answered 401 from `initialize` on (an MCP client starts its OAuth flow on nothing
-  else), a token carrying no `aud` is refused (that issuer mints for its other resources too), and the challenge
-  carries no `error` code (RFC 6750 §3.1 reserves it for a credential that was presented). A server naming no
-  issuer keeps anonymous access and accepts a first-party token, which is bound by app and environment instead.
+  `insufficient_scope` is enforced only once scopes are declared. Declare them only for tokens an external issuer
+  mints: the built-in authorization server's tokens carry no scope, so beside it every one of them would be refused
+  with 403. Naming an issuer changes three things at once: a request with no credential is answered 401 from
+  `initialize` on (an MCP client starts its OAuth flow on nothing else), a token carrying no `aud` is refused (that
+  issuer mints for its other resources too), and the challenge carries no `error` code (RFC 6750 §3.1 reserves it
+  for a credential that was presented). A server naming no issuer keeps anonymous access and accepts a first-party
+  token, which is bound by app and environment instead.
 - **The boot log names every published entry with no dictionary `.desc()`.** An agent picks a tool by its
   description, so a missing one is a broken tool. What the framework generates has no text of its own and borrows
   the model's: the generated list reads the `.of()` label, and the base CRUD tools append the model's `.desc()` to

package/guidelines/queryRule/queryRule.instruction.md

@@ -49,7 +49,7 @@ with it. `conventions` carries the invariants — this is the full contract behi
   `findBy<Filter>(...args, { select: { secretField: true } })` takes it inside the option object. The shapes do not
   swap: `{ select: … }` handed to the facade projects a field named `select`, which no model has, and the read comes
   back empty with no error. This is the only way to read a `field.secret(...)` value, which is otherwise stripped.
-- **Hydrated vs raw:** server queries return hydrated `cnst.<Model>` instances (with `set`/`save`/`refresh`); client fetch results are raw `GetStateObject` plain data (functions stripped, `pkgs/akanjs/base/types.ts`).
+- **Hydrated vs raw:** server queries return hydrated `cnst.<Model>` instances (with `set`/`save`/`refresh`), and so do client fetch results — `FetchClient` parses every return with `crystalize` defaulting to **true** (`pkgs/akanjs/fetch/client/fetchClient.ts`). The raw `GetStateObject` shape (functions stripped, `pkgs/akanjs/base/types.ts`) is what the `<ref>Obj` / `<ref>ObjList` / `<ref>ObjInsight` handles carry, because those pass `crystalize: false` on purpose so the value can cross the RSC boundary as a client prop.
 - Every filter generates fourteen methods: `list` · `listIds` · `find` · `findId` · `pick` · `pickId` · `exists` ·
   `count` · `insight` · `query` · **`remove`** · **`removeOne`** · **`update`** · **`updateOne`**. The last four are
   query-level writes — one atomic UPDATE, **no hooks**, and therefore no `_postRemove` and no cascade. Use them on a
@@ -90,14 +90,15 @@ with it. `conventions` carries the invariants — this is the full contract behi
 - **A slice endpoint never reaches "unspecified".** The resolver fills `latest` before the query is built, so a
   client asking for the score order has to name `relevance`; leaving `sort` off gets `latest`, not relevance.
 - Scope a search with `columns` (`q.search(text, { columns: ["title"] })`) and re-weight with `weights`, a tuple of
-  finite numbers positional over `["title", "desc", "tag", "filter"]`.
+  finite, non-negative numbers positional over `["title", "desc", "tag", "filter"]` — Postgres ranks by weight
+  class and has no reading for a negative one.
 
 
 ## Text Search Fields — the `text` role
 
 - A field joins the full-text index by declaring one of five roles: `field(String, { text: "title" })`, and likewise
   `"desc"`, `"tag"`, `"thumb"`, `"filter"`. Nothing else opts a field in, and there is no per-model switch.
-- Pick the role by what the value *is*, because `bm25` weights them positionally (`title` 10, `tag` 3, `desc` 1,
+- Pick the role by what the value *is*, because the rank weights them positionally (`title` 10, `tag` 3, `desc` 1,
   `filter` 0): `title` is the one line a human scans for, `desc` is prose, `tag` is a keyword list, `filter` is a
   scoping value (status, owner, role) that must be matchable but must never outrank a real title hit.
 - `thumb` is mirrored for rendering a hit and is **not** indexed — never expect it to match.
@@ -114,15 +115,24 @@ with it. `conventions` carries the invariants — this is the full contract behi
 - Declaring roles is all the wiring there is. Mirror rows are maintained by SQL triggers — not document hooks —
   because `updateOneByQuery` and friends fire no hooks, and most searchable-field mutations go through exactly that
   path.
-- Search runs on sqlite/libsql only. `q.search()` against Postgres throws, loudly, rather than returning every row.
+- Search runs in every database mode: fts5 on SQLite/libSQL, a weighted `tsvector` under a GIN index on Postgres.
+  For the same text the same documents match — punctuation splits words the way unicode61 does, and a phrase never
+  runs from one column into the next — but the order may differ, since Postgres ranks without document frequency.
+  Assert on the match set, never on a Postgres order the weights alone do not decide.
+- Postgres reads `AKAN_SEARCH_TOKENIZER` as `unicode61 [remove_diacritics 0|1|2]` (`simple`, with `unaccent` unless
+  `0`) or `trigram [case_sensitive 0|1]` (`pg_trgm`); any other spelling is refused. The extension is created when
+  the role may, otherwise a role that may runs `CREATE EXTENSION`. It indexes the first 20,000 characters of
+  `title`, `tag` and `filter` and 200,000 of `desc` — a tsvector refuses more than 1MB, and the refusal would fail
+  the model write. A database whose `LC_CTYPE` is `C` keeps non-ASCII case apart; use a UTF-8 ctype.
 - `AKAN_SEARCH_ENABLED=0` switches the index off process-wide; unset means on. It never deletes mirror data, and
   re-enabling reconciles every ref. **Give every process the same value** — a process cannot drop triggers for models
   it does not mount, so a mixed fleet leaves stale triggers behind.
 - The tokenizer is `AKAN_SEARCH_TOKENIZER` (or `database.search.tokenizer`, which wins), defaulting to
   `unicode61 remove_diacritics 2`. Changing it rebuilds the index from the mirror on the next boot — the model
-  tables are never re-read — so it is a safe knob, unlike a `text` role change, which re-reads every row. The
-  rebuild takes no cross-process claim, so a fleet restarted at once repeats it in every process; stagger the
-  restart when the mirror is large.
+  tables are never re-read — so it is a safe knob, unlike a `text` role change, which re-reads every row. The schema
+  is ensured in one write turn — a SQLite write transaction, a Postgres schema lock — so of a fleet restarted at
+  once the first rebuilds and the rest find it current. A SQLite process waits for that turn up to its
+  `busy_timeout`, so stagger the restart when the mirror is large.
 
 ## Cascade Remove — the `cascade` option
 

package/guidelines/runtimeRule/runtimeRule.instruction.md

@@ -16,9 +16,9 @@ const config: AppConfig = { web: false }; // api only
 ```
 
 - **`web: { csr: false }`** drops the CSR build phase and the `/__csr` + `?csr=true` routes. The CSR bundle is
-  what the Capacitor mobile build ships, so a web-only deployment never needs it — and an app that declares a
+  what the native mobile build ships, so a web-only deployment never needs it — and an app that declares a
   `mobile` section is refused, because `akan build-ios` copies `dist/apps/<app>/csr/<target>.html` into the
-  native project.
+  target's web root, `.akan/mobile/<target>/web`.
 - **`web: false`** is an API-only build: no base artifact, no pages or client bundles, no RSC worker
   entrypoint, and no `public/` in the image (the web router's catch-all is its only reader). Nothing under
   `page/` is served, including routes a lib contributed through `syncPageLibs`.
@@ -68,7 +68,7 @@ const config: AppConfig = { api: { prefix: "/backend", websocketPrefix: "/socket
   origin when the module graph initializes, before any component renders, so a React prop — a `System.Provider`
   value, anything out of `implicitRootLayout` — is always too late. The value rides the SSR classic bootstrap
   script instead, the one thing guaranteed to run ahead of every module script, and is omitted when it matches
-  what the bundle already assumes. `akan.config.ts` is what a Capacitor bundle or a statically served CSR shell
+  what the bundle already assumes. `akan.config.ts` is what a native app bundle or a statically served CSR shell
   follows, because neither is rendered by a server that could tell it otherwise.
 - **A prefix is a path segment.** A blank value or a bare `/` is refused: `/` would be mounted ahead of the SSR
   catch-all and swallow every page route. A prefix whose first segment is a declared basePath is refused at
@@ -184,6 +184,80 @@ const config: AppConfig = { docker: "FROM oven/bun:1-slim\n…" }; // verbatim,
 - `AkanAppConfig.docker` is the resolved declaration; `AkanAppConfig.dockerfile` is the text `akan build` writes
   to `dist/apps/<app>/Dockerfile`.
 
+## Database Modes — `database` In `akan.config.ts`
+
+| mode | database | cache · queue · pubsub | runs as |
+|---|---|---|---|
+| `single` | SQLite file | SQLite files (Solid) | one container |
+| `multiple` | one SQLite file (WAL) on a host volume every container on that host opens | Redis | containers on one host |
+| `cluster` | Postgres | Redis | pods on several servers |
+
+- **`database: { modes: ["single", "cluster"] }` is what the build can run in**; the first is what `akan start`
+  runs. `akan build` carries the drivers of every declared mode (`multiple` → `bullmq`, `ioredis`; `cluster` adds
+  `postgres`).
+- **A deployment names its mode with `AKAN_DATABASE_MODE`**, and only a declared one. With one declared mode it may
+  leave it out; with several it must name one — the fallback would be a SQLite file inside each pod. `akan start`,
+  `build`, `script` and `console` resolve it the same way from the shell. One image can serve an edge site in
+  `single` and a cloud cluster in `cluster`: declare both.
+- **Where the data lives is the deployment's env, ahead of `env.server.ts`**: `SQLITE_DATABASE_PATH`,
+  `AKAN_SOLID_DB_PATH`, `POSTGRES_URL` (or `POSTGRES_HOST`/`PORT`/`DATABASE`/`USER`/`PASSWORD`),
+  `POSTGRES_INSIGHT_URL`, `LIBSQL_URL`. `REDIS_URI` is required outside local development. Pool size, SSL and
+  prepared statements ride the Postgres URL (`?max=20&ssl=require`, `prepare=false` behind PgBouncer).
+- **Uploads**: a deployed `multiple`/`cluster` app uses object storage, or a volume every instance mounts with
+  `AKAN_STORAGE_SHARED=true`.
+- **`runAdminSql` on Postgres reads as its own login role** holding base-column `SELECT` and nothing else:
+  `CREATE ROLE <name> LOGIN PASSWORD '…'` with no other role granted, `POSTGRES_INSIGHT_URL` logging in as it, and
+  `GRANT USAGE ON SCHEMA` from the DBA when the app does not own its schema. Every model table grants the role its
+  base columns at boot. Without it the console refuses on Postgres; `_doc` is never readable either way.
+- **`akan dbup`** starts what the workspace's apps declare (`--mode multiple` is Redis, `cluster` adds Postgres).
+  **`akan db-export <app>` / `akan db-import <app>`** move every model table as stored rows through NDJSON files
+  (`--dir`, default `local/transfer`) between whatever the shell's `AKAN_DATABASE_MODE` points at; a rerun
+  replaces rows, search is rebuilt after, and sessions, queued jobs and uploaded files do not move.
+- **`q.raw(sql)` is the dialect's own SQL** — `json_extract("_doc", '$.f')` on SQLite, `("_doc" #>> '{f}')` on
+  Postgres. An app that runs in both modes avoids it.
+
+## Operations — Snapshots, Restore And The `/_akan/ops` Channel
+
+`GET /_akan/app/info` answers `{ appName, repoName, environment, operationMode }` on every deployment — the same
+`AKAN_PUBLIC_*` values the client bundle already carries — so a control plane can check which app a host is
+serving without a key. Everything else is behind the ops channel.
+
+| surface | what it does |
+|---|---|
+| `bun main.js ops snapshot [--id] [--out] [--include-solid] [--json]` | `VACUUM INTO` a consistent copy, `integrity_check`, sha256, gzip, optional age encryption, `manifest.json` |
+| `bun main.js ops restore <manifest.json> [--identity <file>]` | offline only: verify, stage, keep the old file as `<db>.pre-restore-<ts>` (its `-wal`/`-shm` beside it), swap |
+| `GET /_akan/ops/info` | the public info plus `akanVersion`, `buildId`, `serverMode`, `databaseMode`, `solo`, `startedAt`, `replicaIdx` |
+| `POST /_akan/ops/snapshot` `{ id, includeSolid?, uploadUrls: { main, solid?, manifest } }` | 202; a child process snapshots, then PUTs each file and the manifest **last** |
+| `GET /_akan/ops/snapshot/:id` | `running` → `uploading` → `done` \| `failed`; kept in memory, so a restart answers 404 |
+
+- **The entry is the image's own `main.js`** — a production image carries no `akan` CLI. `AkanApp.start()` hands
+  `argv[2] === "ops"` to the command before it boots anything. It reads the container's env — the `AKAN_PUBLIC_*`
+  identity and the database paths — so run it with that env (`docker compose exec`), never a bare shell's.
+- **Restore refuses while an app answers `/_akan/app/health` on `PORT`** and names it by its `/_akan/app/info`;
+  `--force` is for a port some other app holds.
+- **The channel exists only when `AKAN_OPS_PUBLIC_KEY` is set** (Ed25519: PEM, JWK, base64 SPKI or raw 32 bytes).
+  The control plane signs a short EdDSA JWS — `aud`, `iat`, `exp` at most 300s after `iat`, a `jti` the process
+  refuses twice — and the host holds only the public half, so a machine someone carries off mints nothing.
+  `aud` is `<appName>/<environment>`, or `<appName>/<environment>/<AKAN_OPS_INSTANCE>` when that is set, and then
+  only that: a token minted for the app as a whole would replay across every host sharing the name. 30 calls a
+  minute per process; every refusal is the same 401. A malformed key leaves the app serving with the channel off.
+- **The app holds no storage credential.** It PUTs to the presigned URLs it was handed (`application/octet-stream`,
+  the manifest `application/json`), plain http only to loopback. The manifest landing is the commit marker.
+- **Snapshots cover the SQLite modes only.** `single` copies the main file and, with `includeSolid`, the Solid file;
+  `multiple` copies the main file; `cluster` is refused. Paths follow the adaptors' env precedence
+  (`SQLITE_DATABASE_PATH`, `AKAN_SOLID_DB_PATH`, `AKAN_SQLITE_DIR`); a solo process uses the path its adaptor
+  actually opened, so a gateway deployment that moved the file in `env.server.ts` names it in the env too.
+- **`AKAN_BACKUP_RECIPIENT=age1…[,age1…]` encrypts before upload** — age v1 X25519, so `age -d -i key.txt` opens
+  it. Restore takes `--identity` / `AKAN_BACKUP_IDENTITY_FILE`, or a file an operator already decrypted with
+  `age -d -o <name without .age>`.
+- **The host keeps the newest `AKAN_OPS_SNAPSHOT_KEEP` (default 2) snapshots** under `AKAN_OPS_SNAPSHOT_DIR`
+  (default `<db dir>/snapshots/<id>/`) — the copy an edge still has while its uplink or the bucket is down.
+- **`buildId` is `AKAN_BUILD_ID` when the deployment sets it**, else the git sha `akan build` wrote into
+  `akan.build.json` beside `main.js` (`-dirty` when the tree was).
+- **`operationMode` does not gate any of this** — the key does. `edge` means a production host outside the
+  cluster: the console refuses it like `cloud`, and `init` / `interval` / `cron` take `operationMode: ["edge"]` to
+  run only there. Everything else behaves as `cloud`; `local` is a developer machine.
+
 ## Shipped Assets — `assets` In `akan.config.ts`
 
 `akan build` copies the whole `public/` tree into `dist`, lib assets dereferenced, and that copy is the image.

package/guidelines/ssrRule/ssrRule.instruction.md

@@ -129,8 +129,10 @@ eight queries threw; per-section boundaries put each rejection at its own bounda
 soft-redirect script, so `getSelf({ unauthorize: "/signin" })` stays in `_layout.tsx` or the page body — never
 inside a streamed section.
 
-**⑥ Use named `ReactNode` slots, not just `children`.** `Layout.Navbar` accepts `title`, `back`, `left`, `right`,
-and `children`, so a client shell composes server-rendered content in five places instead of absorbing it.
+**⑥ Use named `ReactNode` slots, not just `children`.** A client shell that takes one slot per region lets a
+server component supply each of them, instead of absorbing the whole subtree into the bundle. `Layout.Navbar`
+declares `title` / `left` / `right` alongside `back` and `children`, but its render body uses only `back` and
+`children` — copy the shape, not that component.
 
 **⑦ Let the server do the derived work.** Display and predicate logic belongs on `Light<Model>` (`isNew()`,
 `canWrite(user?)`, `formatTimes()`), and enum→class lookups belong in a module-scope `as const` map. Both sides call

package/guidelines/transportRule/transportRule.instruction.md

@@ -28,6 +28,57 @@ mutation is mounted under. `conventions` carries the invariants — this is the
   neither again, and cleanup that must happen either way registers for both. From a `message` handler it belongs to
   the socket and runs at close. A handler that throws is logged and never blocks the rest of the teardown.
 
+## Request Deadlines
+
+- **`{ timeout: <ms> }` in an endpoint's signal option is the whole configuration surface**, and it reaches both
+  ends of the call. Server side, the `Timeout` middleware races the handler against it and answers
+  `base.error.gatewayTimeout` (504) once it is spent. Client side, `FetchSerializer` ships the value on the
+  serialized endpoint and `fetch.<endpoint>()` uses it as that request's `AbortSignal.timeout` budget, so the
+  browser does not abandon a call the server is still allowed to be working on.
+- **The middleware is registered by default and has no default of its own.** An endpoint that declares no
+  `timeout` is passed straight through — a default here would put a deadline on every endpoint in the app that
+  nobody asked for, which is why the middleware used to be opt-in and, being opt-in, made the declared value
+  dead. It clears its timer in a `finally`: the race's loser is a pending timer per call otherwise, and with a
+  five-minute budget that is a five-minute hold on the event loop for a call that answered in a millisecond.
+- **Without a declaration the client's own default applies — 30 seconds** (`DEFAULT_TIMEOUT_MS`,
+  `fetch/client/httpClient.ts`), and the server imposes nothing. Nothing else bounds a request: `Bun.serve` runs
+  with `idleTimeout: 0`, so a long call is only ever ended by one of these two.
+- **Precedence is caller, then endpoint, then client default.** `fetch.x(…, { timeout: 5_000 })` overrides what
+  the endpoint declared; `{ timeout: false }` waits as long as the runtime will. An app moves its own default
+  with `fetch.instance.setTimeout(ms)` — `lib/useClient.ts` is generated, so the `timeout` option on
+  `FetchClient.build` belongs to the template that writes it, not to app code.
+- **A file upload is never bounded**, on any of those paths: a large body on a slow uplink is a request that is
+  working, and the request body is the only thing the client can tell that from.
+- **The deadline answers the caller; it does not undo the call.** `Promise.race` cannot cancel `next()`, so a
+  handler that timed out keeps running and keeps writing. Reach for a `timeout` to bound what a *caller* waits
+  for, not to bound an effect — an operation that must not half-happen needs its own idempotency or compensation.
+- The failure is the same `base.error.gatewayTimeout` key whichever side gave up, so the user reads one sentence
+  in their own language either way. What differs is the status code — 504 from the server's middleware, 408 from
+  the client's own abort — and nothing downstream branches on that.
+
+## Cached Answers
+
+- **`{ cache: <ms> }` in an endpoint's signal option is the whole cache surface.** The lookup is a step of every
+  call and stands aside unless an endpoint declares one.
+- **Only a `query` that takes no internal argument may carry one.** The handler's inputs are its declared
+  arguments plus its internal ones, so an endpoint with none of the latter answers the same thing to everyone who
+  may read it — which is the only answer a shared entry can hold. An endpoint that takes `.with(Self)` answers
+  per caller, and one entry would be one caller's answer handed to the next; that endpoint and every `mutation`
+  are named once in the log and left uncached rather than silently ignored.
+- **The guards run before every hit.** The lookup sits after the guards and the internal arguments, inside the
+  call, so every middleware — the account resolution a lib registers among them — has already run and a hit
+  reaches only a caller the guards admitted. It used to be a middleware ahead of the lib's, and a guard reading
+  the account refused a signed-in caller on every hit. Shared is not public.
+- **The entry is the handler's result, not the response.** The lookup wraps the handler only, so `resolveReturn`
+  still runs per call on the cached value — field masking, `hidden`/`secret` stripping and relation resolution are
+  never cached, and a relation still costs its own load. The cache saves the handler, not the serialization.
+- **A cache backend that is down does not take the endpoint down.** A failed read is warned and the call runs
+  uncached; a failed write is warned and dropped.
+- The default middleware chain is `Logging → Timeout → <lib middlewares>`, and the call inside it runs guards →
+  internal arguments → cache → handler: a hung cache backend is bounded by the same deadline as the handler it
+  stands in for. **`Retry` was removed** — an automatic re-run of an endpoint
+  whose failure it cannot classify replays whatever the first attempt already did.
+
 ## Binary Pubsub
 
 - **`pubsub(Binary)` sends its payload in a websocket binary frame**, skipping the JSON `{ type: "pub" }`