@akanjs/cli 3.0.0-alpha.11 → 3.0.0-alpha.110

package/guidelines/conventions/conventions.instruction.md

@@ -19,44 +19,80 @@
 - Prefer established nearby patterns over introducing a new abstraction.
 - Add new abstractions only when they remove real duplication or match an existing project pattern.
 
+## Deep-Dive Guidelines
+
+This file carries the rules. The reasoning, the measurements, and the per-feature edge cases live in guidelines
+you fetch on demand — `get_guideline` with the name, or `akan guideline show <name>`. Fetch the relevant one
+**before** a deep pass on that area; a section below that points at one is a summary, not the whole contract.
+
+| 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 |
+| `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 |
+| `agentRule` | the in-page agent's chat options, zones, slash commands, transcript compaction |
+| `cssRule` | the full semantic token set for a theme pass |
+| `componentRule` | the `_overrides.tsx` slot list and drop-in component patterns |
+| `recipeRule` | authoring and consuming Tailwind-variant recipes |
+| `workspaceRecipes` | worked step-by-step recipes and the auto-generated API reference |
+
 ## Lint-Enforced Rules (These Break The Build)
 
-Enforced by `biome.json` and the grit plugins in `pkgs/@akanjs/devkit/lint/`. Several of them produce output
-that looks wrong; do not "fix" it back.
+Enforced by `biome.json`, which extends `@akanjs/devkit/biome.base.json` — that file scopes every grit plugin in
+`@akanjs/devkit/lint/` to the paths it applies to. Several rules produce output that looks wrong; do not "fix" it
+back.
 
 - **Never hand-order Tailwind classes.** `nursery/useSortedClasses` is an error and also sorts the string
-  arguments to `cn()`. Sorter output such as `font-bold text-2xl text-base-content` or
-  `border-base-content/5 border-t` is correct. Write the classes in any order, run the formatter, leave the result.
-- **Stay inside the color vocabulary.** Vocabulary closure strips the raw Tailwind palette, so these render as
-  no CSS and fail lint (`no-raw-palette-class.grit`, `no-arbitrary-color.grit`, `no-daisyui-legacy-class.grit`,
-  `no-inline-color.grit`): raw palette classes (`bg-blue-500`), arbitrary color values (`bg-[#3b82f6]`), daisyUI
-  legacy classes (`btn-primary`, `card-body`), and color literals in `style={{...}}`. Use semantic tokens
+  arguments to `cn()`. Sorter output such as `font-bold text-2xl text-foreground` or `border-foreground/5 border-t`
+  is correct. Write the classes in any order, run the formatter, leave the result.
+- **Stay inside the color vocabulary.** Vocabulary closure strips the raw Tailwind palette, so these render as no
+  CSS and fail lint: raw palette classes (`bg-blue-500`), arbitrary color values (`bg-[#3b82f6]`), an arbitrary
+  class built by interpolation, daisyUI legacy classes (`btn-primary`, `card-body`) and its dropped color slots
+  (`bg-base-100`, `text-base-content`, `text-primary-content`, `bg-error` — use `background`/`muted`/`border`,
+  `foreground`, `<color>-foreground`, `destructive`), and color literals in `style={{...}}`. Use semantic tokens
   (`bg-primary`, `text-foreground/70`). A legitimate fixed color (OS-chrome mockups, data-viz) takes a
-  `// biome-ignore lint/plugin: <reason>` with the reason spelled out. `apps/akan/page/v1/**` is excluded.
+  `// biome-ignore lint/plugin: <reason>`. (`no-raw-palette-class`, `no-arbitrary-color`, `no-daisyui-legacy-class`,
+  `no-inline-color`, `no-interpolated-arbitrary-class`)
 - **Never `throw new Error`.** Throw `new Err("<module>.error.<key>")` and register the key as `[en, ko]` in that
   module's dictionary `.error({})`. Import `Err` from `"../dict"` on the server and from `"@libs/<lib>/client"` or
-  `"@apps/<app>/client"` in UI. `no-throw-raw-error.grit` exempts `*.test.ts`, `*.spec.ts`, `*.constant.ts`,
-  `common/**`, and `apps/akan/env/**` — `common/` and `env/` have no legal `Err` import path, so keep throwing code
-  out of them.
+  `"@apps/<app>/client"` in UI. `no-throw-raw-error.grit` exempts tests, `*.constant.ts`, `common/**`, and `env/**`
+  — the last two have no legal `Err` import path, so keep throwing code out of them.
 - **Never import a third-party package** from `page/**`, from any barrel, or from any
   `*.{constant,dictionary,document,service,signal,store}.ts` / `*.{Template,Unit,Util,View,Zone}.tsx`
-  (`no-import-external-library.grit`). Re-export the symbol through a lib first. One-line re-export shims such as
-  `libs/<lib>/base/<pkg>.ts` and `libs/<lib>/webkit/<hook>.ts` exist for exactly this reason — they are
-  load-bearing, not cruft. Do not delete them.
+  (`no-import-external-library.grit`). Re-export the symbol through a lib first. One-line re-export shims in a lib's
+  `common/`, `webkit/`, or `ui/` exist for exactly this reason — they are load-bearing, not cruft.
 - **`#private` is banned in exactly four file suffixes:** `*.constant.ts`, `*.document.ts`, `*.service.ts`, and
   `*.store.ts` (`no-js-private-class-method.grit`). The rule is scoped by file path, not by class shape, so
   `#private` remains the house style everywhere under `srvkit/`, including `adapt()` adapter classes.
 - **No `console.log` / `console.debug`.** Only `assert`, `error`, `info`, and `warn` are allowed. Server code uses
   the injected `this.logger.*` or `new Logger("ClassName")`.
+- **Never call `logger.log()` / `Logger.log()`** (`no-deprecated-log-level.grit`). The ladder is `trace verbose
+  debug info warn error`; `log` was a seventh tier *below* `info` that `AKAN_PUBLIC_LOG_LEVEL=info` silently
+  dropped. The method is kept and emits at `info`, so a call reads like a distinct level and is not one — write
+  `.info()`.
 - **Never write a `//!` marker in browser-reachable code** — `ui/`, `webkit/`, `common/`, `page/**/*.tsx`,
   `*.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 return a value from a store action** (`no-return-in-store-action.grit`). Every method of a `store(...)`
-  class dispatches through `st.do.<action>()`, which is 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, and a `static` helper are all still fine.
+  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,
+  and a `static` helper are all still fine.
 - **Never redeclare a generated CRUD endpoint name** in `*.signal.ts` (`no-redeclare-predefined-endpoint.grit`).
+- **Never type a `*.Util.tsx` / `*.Zone.tsx` prop as a `cnst` model** (`no-model-type-in-util-zone.grit`). Those two
+  roles are always client components, so a `cnst.Banner` / `cnst.LightBanner` prop is a class instance the server
+  has to hand across the boundary; take `bannerId: string` and read the model from the store instead. Only prop
+  positions are read, and only shapes that are actually an instance. Exempt: an indexed enum access
+  (`cnst.<Enum>["value"]`), a `ClientInit` / `ClientView` / `ClientEdit` or `ModelsProps<…>` type argument, a
+  function-typed prop, and any `cnst` type that never leaves the file. Other indexed accesses
+  (`ModelProps<"setting", cnst.LightSetting>`, `cnst.Banner["image"]`) stay flagged.
+- **Never wrap a form setter in a pass-through arrow** (`no-unpublished-form-setter.grit`).
+  `onChange={(type) => st.do.setTypeOnTicket(type)}` runs identically to `onChange={st.do.setTypeOnTicket}`, but
+  the arrow is a fresh anonymous closure, so the control emits no `data-akan-action` and publishes no agent tool
+  for the field — a silent failure in two lines that read the same. A wrapper that transforms the value, adds a
+  statement, or writes a nested path with `writeOnX` stays legal; publish that one with an explicit `st.tool`.
 - **No deep imports past a barrel** (`no-deep-internal-import.grit`). Cross-module constant references such as
   `../map/map.constant` are the sanctioned exception.
 - **Never import across the client/server boundary.** Client files (`ui/`, `webkit/`, `page/`, `*.store.ts`, every
@@ -66,23 +102,35 @@ that looks wrong; do not "fix" it back.
   `*.store.ts`, a module component, `ui/`, `webkit/`, a package `client` entrypoint, or the `st` / `store` /
   `useClient` barrels (`no-import-client-in-server.grit`). Shared files — `common/` and `*.constant.ts` — are held
   to **both**, so they reach neither side. `import type` is erased before bundling and stays legal in every
-  direction; a mixed value-and-type import is not exempt. Scoped to `apps/**` and `libs/**`: `pkgs/akanjs/**`
-  implements the boundary and is where the two graphs legitimately meet.
+  direction; a mixed value-and-type import is not exempt. Scoped to `apps/**` and `libs/**`.
 - **Server-component discipline** is enforced on `page/**`, `*.Unit.tsx`, and `*.View.tsx`
   (`no-import-client-functions.grit`, `no-use-client-in-server.grit`, `non-scalar-props-restricted.grit`).
+- **Never write an async component outside `page/`** (`no-async-component-in-ui.grit`, scoped to
+  `{apps,libs}/**/ui/**/*.tsx`). React has no async client component, so a `ui/` component that awaits breaks as
+  soon as a client parent renders it, and the load drops below the route, which could have started it before the
+  first byte. Await in the page — or hand an unawaited `fetch.*` field to a `Zone` as an `init` / `view` prop, or
+  to a `<Load.Stream of={…}>` that awaits it behind a boundary of its own — and take the resolved data as a prop.
+  Only a PascalCase binding whose own initializer is `async` is matched, so an async handler inside a synchronous
+  component and `lazy(async () => import(…))` are untouched.
+- **Never call `fetch.init*` from a client file** (`no-init-fetch-in-client.grit`). `fetch.init<Model><Suffix>` and
+  `fetch.get<Model>Init<Suffix>` compose the slice's list and insight queries into the hydration snapshot that
+  `Load.Units` / `Load.View` seed the store from. From a route it resolves before the first byte; after hydration
+  it is two extra round-trips for a shell the browser already painted. Load it in the page and pass the result
+  down as an `init` prop — or hand the unawaited `x<Model>Init<Suffix>` promise across — and reload from the client
+  through the generated `st.do.init<Model><Suffix>()`. Gated on the real `"use client"` directive plus
+  `*.store.ts`, and matched by shape (`init` + `Capitalize<refName>` + `Capitalize<suffix>`), so a hand-written
+  `initPayment` is out.
 - `noArrayIndexKey` and `useExhaustiveDependencies` are **off** on purpose: `key={idx}` for embedded scalars and
   short dependency arrays are intentional, not oversights.
 - **A grit plugin diagnostic is suppressed as `lint/plugin`, not `plugin`** — `// biome-ignore lint/plugin: <reason>`
-  for one line, `// biome-ignore-all lint/plugin: <reason>` for a file. The bare `// biome-ignore plugin:` form Biome's
-  own category name suggests does nothing. Suppress a plugin only where the rule is genuinely wrong for the file, and
-  say why: the module-convention plugins (`no-import-external-library`, `no-deep-internal-import`, the store/signal
-  ones) apply to `apps/**` and `libs/**` only, so a plain package under `pkgs/` never needs the escape hatch.
-- **`biome.json` is strict JSON — a comment in it breaks config resolution.** Biome 2.5.8 does not report the parse
-  error; it falls back to discovery and aborts on whatever nested config the walk finds, typically inside a directory
-  `files.includes` excludes. Rename the file to `biome.jsonc` to document a disabled rule; `akan lint` pins the config
-  path either way, so it reports the parse error on the offending line.
-- **`akan lint` prints up to 200 diagnostics** (`--maxDiagnostics <n>`, `0` for no limit). Biome's own default is 20
-  with no count, which reads as progress when the mix of findings merely changed.
+  for one line, `// biome-ignore-all lint/plugin: <reason>` for a file. The bare `// biome-ignore plugin:` form
+  Biome's own category name suggests does nothing. The module-convention plugins apply to `apps/**` and `libs/**`
+  only, so a plain package under `pkgs/` never needs the escape hatch.
+- **`biome.json` is strict JSON — a comment in it breaks config resolution.** Biome does not report the parse
+  error; it falls back to discovery and aborts on whatever nested config the walk finds. Rename the file to
+  `biome.jsonc` to document a disabled rule.
+- **`akan lint` prints up to 200 diagnostics** (`--max-diagnostics <n>`, `0` for no limit). Biome's own default is
+  20 with no count, which reads as progress when the mix of findings merely changed.
 
 ## Coding Style (`**/*.{ts,tsx}`)
 
@@ -121,7 +169,7 @@ that looks wrong; do not "fix" it back.
 - Prefer focused behavior tests for public contracts and edge cases over implementation-detail assertions.
 - Run package suites with `bun run akan test <pkg>` from the repo root, or `cd <pkg> && bun test --isolate`. Plain `bun test` without `--isolate` shares one global object across test files and fails dozens of tests from cross-file state pollution (`bunfig.toml` `[test] isolate` is not honored as of Bun 1.3), and running `bun test` from the repo root breaks subprocess stdio pipes.
 - Split signal tests in two. `<model>.signal.spec.ts` holds reusable fixtures built on `sampleOf(cnst.XInput)` with explicit `Promise<cnst.X>` return types and **no assertions**. `<model>.signal.test.ts` holds the assertions: `describe("<Model> Signal")`, `let` fixtures at describe scope, one `beforeAll`, story-ordered `it`s, and negatives via `await expect(p).rejects.toThrow()`.
-- `lib/user/user.signal.spec.ts` is the one place agent types are re-exported and re-typed; import `UserAgent` / `AdminAgent` from there rather than from the shared lib directly.
+- `lib/user/user.signal.spec.ts` is the one place agent types are re-exported and re-typed; import `UserAgent` / `AdminAgent` from there rather than from the owning lib directly.
 - A placeholder `it` with a descriptive title is an acceptable floor. Write a real suite when the behaviour is security-relevant.
 
 ## Comments
@@ -152,7 +200,7 @@ Do not narrate code. Do document the thing the code cannot say. Both halves are
 - Use Bun and ESM assumptions from the root `tsconfig.json`.
 - Prefer path aliases over deep relative imports when crossing package boundaries.
 - Use `akanjs/*` for framework facets, `@apps/*` for apps, `@libs/*` for shared libs, and `@contract/*` for contract code.
-- Respect existing client/server entrypoints such as `@libs/shared/client`, `@libs/shared/server`, `@apps/akasys/client`, and `@apps/akasys/server`.
+- Respect existing client/server entrypoints — `@libs/<lib>/client` / `@libs/<lib>/server` and `@apps/<app>/client` / `@apps/<app>/server`.
 - Let Biome organize imports instead of manually reshuffling unrelated imports.
 - Namespace the generated barrels in backend `.ts` files: `import * as cnst from "../cnst"`, `* as db`, `* as srv`. Use `import type * as srv` in services so the runtime graph stays lazy, and a value import in signals.
 - In `.tsx` files use one flat named import from the package client path (`import { cnst, fetch, st, Ticket, usePage } from "@apps/<app>/client"`) — never a relative `../` import.
@@ -207,62 +255,86 @@ are, because those are the ones the server could have done.
 
 ### Server-Side Implementation Playbook
 
-**① Wrap the interaction, not the UI.** The smallest useful client component is a shell that adds one behaviour and
-renders `children` untouched. The children stay server components, so the markup inside them never reaches the
-bundle. `libs/shared/ui/Only/User.tsx` is the shape: it reads auth state on the client and returns `{children}`.
-
-```tsx
-"use client";
-export const ClickWrapper = ({ children, onPick }: ClickWrapperProps) => (
-  <div onClick={onPick}>{children}</div>
-);
-```
-
-**② Split compound components so panels stay on the server.** A tab, accordion, or disclosure needs client state
-only for *which* part is visible — never for what the parts contain. Split into a context provider plus menu and
-panel pieces, and take panel content as `children`. `Tab` / `Tab.Menus` / `Tab.Menu` / `Tab.Panel` in `akanjs/ui`
-is exactly this: only the provider and the menu hold state, and `<Tab.Panel>` renders its children as-is, so a
-server `Unit`/`View` passed in stays server-rendered. Never reach for one `"use client"` file with a mode
-`useState` and every panel body inlined.
-
-**③ Sync state instead of fetching it.** A server component cannot hold state, so render the initial data on the
-server and hand it across the boundary as a serializable object. That is what `init` / `view` props are: the route
-calls `fetch.initXInY(...)` / `fetch.viewX(...)`, passes the result into a `Zone`, and `Load.Units` / `Load.View`
-hydrate the store from it. Never replace that with a `useEffect(…, [])` that fetches on mount — it renders an empty
-shell, hydrates, then round-trips for data the server already had.
-
-**④ Push the boundary down to the leaf that needs it.** When a `Zone` reads the store, it should hold *zero*
-markup and delegate to a server `View`. `User.Zone.Self` is one line — `st.use.self()` into
-`<User.View.General user={self} />` — so the whole detail surface renders server-side wherever a route uses the
-`View` directly.
-
-**⑤ Hand the promise across, not the awaited value.** `ClientInit` / `ClientView` are `PromiseOrObject<T>`, so a
-route may pass an unawaited `fetch.initX(...)`; `Load.*` renders a skeleton and resolves it. `await` in the route
-blocks the shell for data the page needs immediately; passing the promise streams the rest. Independent fetches
-still go through one `Promise.all`.
-
-**⑥ Use named `ReactNode` slots, not just `children`.** A client shell can take several server-rendered subtrees:
-`Layout.Navbar` accepts `title`, `back`, `left`, `right`, and `children`, so a client navbar composes server
-content in five places instead of absorbing it.
-
-**⑦ 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 the same method, so the server can render the result — a client component that exists only to compute a label
-is markup in the wrong place.
-
-**⑧ Gate auth on the server.** `getSelf({ unauthorize: "/signin" })` in `_layout.tsx` redirects before any HTML is
-sent. A client-side auth check costs a hydration round-trip and flashes the wrong UI first.
-
-**⑨ Prefer CSS over client state for pure visibility.** Toggling with a `data-*` attribute plus `group-data-[…]`
-variants (see `libs/util/ui/Grid/*`) or with `<details>`/`<summary>` keeps both branches server-rendered. Reach for
-`useState` when the state is real, not when a variant would do.
-
-**⑩ Keep the heavy island out of the first load.** A large client-only widget goes behind the
-`ui/<Folder>/index_.tsx` + `lazy()` pair so the server renders the page around it. `usePage()` and `l()` work in
-server components, so translation never forces a boundary.
-
-Full version with code, the `Tab` composition example, and a review checklist: `get_guideline` with `ssrRule`, or
-`akan guideline show ssrRule`.
+1. **Wrap the interaction, not the UI.** The smallest useful client component adds one behaviour and renders
+   `children` untouched, so the markup inside never reaches the bundle.
+2. **Split compound components so panels stay on the server.** `Tab` / `Tab.Menus` / `Tab.Menu` / `Tab.Panel` in
+   `akanjs/ui` is the shape: only the provider and menu hold state. Never one `"use client"` file with a mode
+   `useState` and every panel body inlined.
+3. **Sync state instead of fetching it.** The route calls `fetch.initXInY(...)` / `fetch.viewX(...)` and passes the
+   result into a `Zone` as an `init` / `view` prop; `Load.Units` / `Load.View` hydrate the store from it. Never a
+   `useEffect(…, [])` that fetches on mount.
+4. **Push the boundary down to the leaf that needs it.** A store-reading `Zone` should hold zero markup and
+   delegate to a server `View`.
+5. **Hand each promise across, not the awaited value.** `fetch.init<Model><Suffix>` / `view<Model>` / `edit<Model>`
+   are awaitable *and* destructurable: `const { xInitInY, xListInY } = fetch.initXInY(id)` hands out one promise
+   per field with both queries already in flight. Give `xInitInY` to a `Zone` and `xListInY` to a
+   `<Load.Stream of={…}>`; each renders behind its own boundary as its own data lands, so the page never waits
+   for the slowest. `await` still returns the old shape and keeps the whole section in the shell — which is what
+   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.
+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.
+9. **Prefer CSS over client state for pure visibility.** A `data-*` attribute plus `group-data-[…]` variants, or
+   `<details>`/`<summary>`, keeps both branches server-rendered.
+10. **Keep the heavy island out of the first load** — behind the `ui/<Folder>/index_.tsx` + `lazy()` pair.
+    `usePage()` and `l()` work in server components, so translation never forces a boundary.
+
+Full version with code, the `Tab` composition example, and a review checklist: `get_guideline` with `ssrRule`.
+
+## Runtime & Build Configuration
+
+What an app serves, how many processes it runs, where its logs go, and what ships in its image. All of it is
+declared in `akan.config.ts` and narrowed — never widened — by an env at boot. Domain code reaches none of it.
+Full contract: `get_guideline` with `runtimeRule`, or `akan guideline show runtimeRule`.
+
+- **Web surfaces are `web: true | false | { csr: boolean }`.** `{ csr: false }` drops the mobile/CSR bundle,
+  `false` is an API-only build that serves nothing under `page/`. There is no CSR-without-SSR option, by type —
+  the CSR bundle inlines the stylesheet the SSR base artifact compiles. `AKAN_SSR` / `AKAN_CSR` narrow further at
+  runtime and can never switch a surface the build left out back on. `akan start` ignores `web` and keeps the
+  whole dev surface.
+- **One traffic replica runs in the container's only process.** `AKAN_REPLICA=0,0,1` — the default everywhere —
+  has nothing to balance, so there is no gateway and no unix-socket proxy hop. Two or more replicas, a batch-only
+  replica, `AKAN_SOLO=false`, passing `replica` to `new AkanApp(...)`, or `akan start` all bring the gateway back.
+  The RSC worker is always its own process (`--conditions react-server`). A solo process answers
+  `/_akan/app/health`, `/_akan/app/metrics` and `/_akan/bench/ping` in the gateway's own shape, and owns the
+  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
+  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
+  origin before the first component renders. A blank prefix, a bare `/`, and one that shadows a basePath are all
+  refused.
+- **`main.ts` imports `AkanApp` from `akanjs/server/akanApp`, not the barrel** — the barrel re-exports
+  `AkanServer`, whose graph the gateway never runs. Keep entrypoint imports at the leaf.
+- **Every `Logger` call builds a `LogRecord`** carrying `traceId`, `endpoint` and `origin` alongside the message,
+  so one request's lines share a trace. Request context is on by default, production included
+  (`AKAN_LOG_CONTEXT=0` opts out). **Give every sink a floor** — `Logger.addSink(sink, { minLevel })`; a sink with
+  none makes every `verbose` call render. **Never log per delivered record in anything that delivers records.**
+  Tail a running server with `akan logs <app>` (`--level --grep --endpoint --trace --child --role --origin
+  --since`, `--json`) or `.tail` / `.trace <id>` inside `akan console`.
+- **`AKAN_LOG_FORMAT=ndjson` makes the container's stdout one JSON record per line, and the hub owner (gateway or
+  solo replica) its only writer** — every other server process turns its console off and forwards from
+  `AKAN_LOG_STDOUT_LEVEL` (default: the console level); a child's or the RSC worker's crash stack is wrapped as a
+  `raw=true` record instead of breaking the stream. Text stays the default; turn it on in the deployment.
+  `AKAN_LOG_STREAM_TOKEN` mounts `/_akan/app/logs` (SSE, `Last-Event-ID` resume, explicit `gap` events); unset,
+  the route does not exist. `AKAN_LOG_CANONICAL=1|slow` writes one `ok|error <endpoint> ms= status=` line per call;
+  `AKAN_LOG_FLIGHT=1` keeps each call's last 64 sub-level records and promotes them (`flight=true`) only when it
+  failed or ran past `AKAN_LOG_FLIGHT_MS`; `x-akan-debug` lowers one request to `trace` — in `local`, or with the
+  `AKAN_LOG_DEBUG_HEADER` secret. Structured values go in `LogRecord.attrs` via `Logger.emit(...)`; a key naming a
+  secret is `[redacted]` before the record exists.
+- **`docker` is `string | { image, preRuns, postRuns, command }`** — a whole Dockerfile, or the parts Akan
+  assembles one from; the string form takes no contributions. The generated image installs `ca-certificates` and
+  `tzdata` and nothing else, so an app needing `ffmpeg` or Chromium declares it in `preRuns` / `postRuns`. A lib
+  declares the steps its own runtime needs and every mounting app inherits them.
+- **`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/`.
 
 ## React Components And Styling (`**/*.tsx`)
 
@@ -270,13 +342,21 @@ Full version with code, the `Tab` composition example, and a review checklist: `
 - Never `React.FC`, never `defaultProps`, never `PropsWithChildren`. Defaults go in the destructuring (`prefix = ""`); children are typed `children: ReactNode`.
 - `"use client"` on line 1 above the imports is mechanical by file role: every `.Zone.tsx`, `.Template.tsx`, and `.Util.tsx` has it; no `.Unit.tsx` or `.View.tsx` ever does. `usePage()` is legal in server files.
 - Conditional render is `cond ? <X/> : null`. Never `{cond && <X/>}` — in a `className` context it renders the literal string `"false"`. Early `return null` is for guard clauses only.
-- Never hand-roll loading, empty, or list states. Use `Load.Units` / `Load.View` / `Load.Edit` with `renderItem`, `renderList`, `renderView`, and `renderEmpty`; `<Empty />` for a bare placeholder; and `Model.New` / `Model.Edit` / `Model.SureToRemove` for CRUD modals.
+- Never hand-roll loading, empty, or list states. Use `Load.Units` / `Load.View` / `Load.Edit` with `renderItem`, `renderList`, `renderView`, and `renderEmpty`; `<Empty />` for a bare placeholder; and `Model.New` / `Model.Edit` / `Model.SureToRemove` for CRUD modals. For data no `Load.*` covers, `<Load.Stream of={promise} fallback={…}>{(value) => …}</Load.Stream>` awaits one promise behind its own Suspense boundary; a resolved value renders in the shell with no boundary at all, so the same call site works either way.
 - Avoid hooks. `useState` is for modal-open, tab, draft-input, and drag state only — never for server data. `useEffect` must be a genuine effect such as subscribe-with-cleanup or one-shot init. Prefer `Tab` over a `useState` mode switch. `.Template.tsx` files contain zero `useState`.
-- Forms are entirely store-driven: `value={xForm.field}` with `onChange={st.do.setFieldOnX}`, the setter passed by reference. Always use `Field.*`, never a bare `<input>` for a model field. Nested rows use `st.do.writeOnX("payments.3.name", v)` plus the generated `add<Field>OnX` / `sub<Field>OnX`.
+- Forms are entirely store-driven: `value={xForm.field}` with `onChange={st.do.setFieldOnX}`, the setter passed by reference. Always use `Field.*`, never a bare `<input>` for a model field. Nested rows use `st.do.writeOnX("payments.3.name", v)` plus the generated `add<Field>OnX` / `sub<Field>OnX`. **Passing the setter by reference is also what makes the framework emit `data-akan-action` / `data-akan-state`** on the control — the annotation an in-page agent, an E2E selector, and an external browser agent all read. Wrapping it in an inline arrow (`onChange={(v) => st.do.setFieldOnX(v)}`) silently drops that: a closure the caller wrote says nothing about what it does. Never hand-write a `data-akan-*` attribute.
 - Read with `st.use.*` and write with `st.do.*`. Client components do not call `fetch.*`.
+- **An edit shell recovers its own form — never persist form values yourself.** `Load.Edit`, `Model.EditModal` and
+  `Model.New` save the whole `<model>Form` as the user types and offer it back on the next open, so a modal closed
+  by accident, a route change, or a killed app costs nothing. The scope is the record id for an edit and the seed
+  plus the route for a new form, both keyed to the signed-in user, so another record or another parent never loads
+  someone else's half-finished form. A new form's draft is applied on open with a "start over" chip; an edit whose
+  record moved in the meantime is *not* applied, and asks. Turn it off with `draft={false}`, or name the scope
+  yourself with `draft="<scope>"` when the context is in neither the id nor the seed. `field.secret` and
+  `field.hidden` values are never saved. The old per-field `cache` / `cacheKey` props are deprecated and store
+  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.
-- Use daisyUI semantic tokens with opacity modifiers (`text-base-content/60`, `border-base-content/10`, `bg-base-100/70`, `bg-primary/10`). Never use `dark:` — theming is the daisyUI theme block in `page/*/styles.css`. Raw hex belongs only in marketing surfaces; match the neighbouring files.
 - 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.
 - Use `<Link>` from `akanjs/ui` for internal navigation; `<a>` only for `mailto:` and external links.
 
@@ -304,23 +384,26 @@ Full version with code, the `Tab` composition example, and a review checklist: `
 
 **`<model>.constant.ts`** — five classes in order with one blank line between them and `enumOf("camelName", [...] as const)`
 classes above: `XInput → XObject → LightX → X → XInsight`. Write `XInsight` even when it is empty. Put display and
-predicate logic on `LightX` (`isNew()`, `canWrite(user?)`, `formatTimes()`, `isCancellable()`) — the Light class is the
-one both server and client hold, so shared logic belongs there instead of in a util module. This is the most commonly
-missed rule in the codebase. Collection-level helpers go `static` on the full model. Give any field whose business
-meaning is not obvious a short trailing comment.
+predicate logic on `LightX` (`isNew()`, `canWrite(user?)`, `formatTimes()`) — the Light class is the one both server
+and client hold, so shared logic belongs there instead of in a util module. **This is the most commonly missed rule
+in the codebase.** Collection-level helpers go `static` on the full model. Give any field whose business meaning is
+not obvious a short trailing comment.
+
+**A model instance's `Date` fields are prototype accessors, not own properties.** `user.createdAt` is still a `Dayjs`,
+built on first read from a native `Date` the instance holds under a symbol. So `Object.keys(user)` and `{ ...user }`
+do **not** include them, while `"createdAt" in user`, `for...in`, `JSON.stringify(user)`, `plainFieldsOf(user)`
+(`akanjs/common`), `immerify`, and `deepObjectify` all do. To copy a model, `new cnst.X().set(user)`, never a spread.
 
 **`<model>.document.ts`** — fixed order: `XFilter extends from(...)` → `X extends by(...)` → `XModel extends into(...)`,
 with `sort: {}` always present. Chain methods validate → mutate → `return this`, and never `save()`; the caller saves,
 so chains compose (`org.removeUser(id).removeInvite(id).save()`). Put a one-line comment above each stating the
 transition. Atomic counters live on the Model class with the updater-callback form, returning `!!modifiedCount`.
 Indexes and derived totals go in `static override _onSchema`, not in the service. **Removal is always soft** — the
-model facade's `removeMany(query)` and the store's `removeManyByQuery` stamp `removedAt` like `remove(id)` does; the
 framework has no hard delete for a model table, and `delete` is deliberately left unused so it can mean one later.
-The facade keeps `Many`/`One` spelled out on its writes (`updateOne` / `updateMany` / `removeOne` / `removeMany`):
-a bare `update`/`remove` would read like the document-path `update(id)` / `doc.remove()` while hitting every match.
-Only the count was shortened — `count(query)`, with `countDocuments` kept as `@deprecated`. `updateById(id, update)`
-and `removeById(id)` are those same query-level writes narrowed to one id, **not** the document path: they fire no
-hooks either, so a model whose removal cascades or carries a `_postRemove` still goes through `remove<Model>(id)`.
+The facade spells `Many`/`One` out on its writes (`updateOne` / `updateMany` / `removeOne` / `removeMany`); only the
+count was shortened to `count(query)`, with `countDocuments` kept as `@deprecated`. `updateById(id, update)` and
+`removeById(id)` are those same query-level writes narrowed to one id, **not** the document path: they fire no hooks,
+so a model whose removal cascades or carries a `_postRemove` still goes through `remove<Model>(id)`.
 
 **`<model>.service.ts`** — keep methods to a few lines: load → chain → `return await ….save()`. Write `return await`
 explicitly in tail position; do not "optimize" it away. Side effects belong in `override async _preUpdate` /
@@ -336,18 +419,13 @@ 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** — `st.do.<action>()` is typed `void` / `Promise<void>`, so hand the result to `this.set({...})` rather
-than returning it (`no-return-in-store-action.grit`); a bare `return;` guard stays fine. **Never
-`import type { RootStore } from "../st"`** — it crashes `akan build` with a Bun SSR segfault.
+nothing** (`no-return-in-store-action.grit`). **Never `import type { RootStore } from "../st"`** — it crashes
+`akan build` with a Bun SSR segfault.
 
 **`<model>.dictionary.ts`** — fixed chain, with empty stages still written:
 `.of() → .model() → .insight() → .query() → .sort() → .enum() → .slice() → .endpoint() → .error() → .translate()`.
 Name every argument in `.arg()`, including framework-supplied `skip` / `limit` / `sort`. Use `modelDictionary`,
 `scalarDictionary`, or `serviceDictionary` to match the module kind.
-**`.store()` sits between `.endpoint()` and `.error()` and is the one optional stage** — omit it entirely rather
-than writing it empty. It names custom store actions (labels and `.desc()` only, no `.arg()`), and it is only
-needed where inheriting would be wrong: an action named after the endpoint it calls already reads as that
-endpoint's `.desc()`, which is most of them. `akan.agent.missing-store-description` names the rest.
 
 **`<module>.abstract.md`** — a title line, one declarative sentence naming what the module owns, a `## Rules` list of
 two to five invariants the code cannot show, and an optional workflow arrow chain
@@ -365,17 +443,34 @@ workflow changes.
 
 ### Guards And Transports
 
-- Guards run on both HTTP and websocket calls. Read the caller with `context.get<T>("account")` (`pkgs/akanjs/signal/signalContext.ts`) instead of branching on `getHttpContext()` / `getWebSocketContext()`.
-- Slice-level `guards` only reach the generated query/mutation endpoints. A `pubsub`/`message` endpoint is unguarded unless it declares its own `guards` in its signal option.
-- A pubsub room is authorized once, at subscribe. When a socket's credential changes the framework re-runs each room's guards and unsubscribes the ones that now fail (`SignalResolver.revalidateWsRooms`), so guards must stay side-effect free and safe to re-run.
-- A websocket carries its credential in the handshake snapshot on `ws.data` (`AppWsData`); clients that hold the token in memory send it with `fetch.setJwt(...)`, which forwards an auth frame over the socket.
+Full contract — credential handshake, room revalidation, socket cleanup scoping: `get_guideline` with
+`transportRule`, or `akan guideline show transportRule`.
+
+- Guards run on both HTTP and websocket calls. Read the caller with `context.get<T>("account")` instead of
+  branching on `getHttpContext()` / `getWebSocketContext()`, and keep them side-effect free and safe to re-run —
+  a pubsub room's guards are re-run whenever the socket's credential changes.
+- Slice-level `guards` only reach the generated query/mutation endpoints. A `pubsub`/`message` endpoint is
+  unguarded unless it declares its own `guards` in its signal option.
+- **Never read the caller's IP off the socket or the request peer — take `.with(Ip)`** (`context.getClientIp()`
+  inside a guard or middleware). Behind a federation gateway, `ws.remoteAddress` and the child's own peer are the
+  *gateway* (`127.0.0.1`) for every caller and for the whole life of every socket. `Ip` reads what a proxy
+  recorded, is unwrapped from its `::ffff:` form, and is `null` rather than a placeholder when genuinely unknown.
+- **Every socket carries a `socketId`, and only the framework mints one** — read it off the `Ws` internal arg
+  (`.with(Ws)` hands `{ ws, socketId, subscribe, on, off }`). Never mint your own from `ws.data`: the room
+  bookkeeping keys on the framework's id and a second one fails to match it silently. It identifies a
+  **connection**, not a caller, so per-user state keys on the account.
+- **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.
 
 ### Authorization Defaults
 
 - **Every `slice()` takes an explicit `{ guards: {…} }` second argument, and `root:` is always `Admin`.**
 - **Every custom `mutation` / `query` / `message` names its own `guards: [...]` array.** Never rely on the slice default. `Public` belongs on a slice `get:`, never on a mutation.
+- **The guards are also the MCP exposure decision** — see MCP Exposure. An endpoint that names none is not published to agents at all, and a mutation whose only guard is `Public` is refused, so a missing `guards` array now costs visibility as well as authorization.
 - Resource guards are `Can<Verb><Model>` classes in `srvkit/guards.ts` that `implements Guard` with an `async canPass(context)`. They **fail closed**: no resource named ⇒ `false`; a load that throws ⇒ `logger.warn` then `false`. Admin bypass goes first.
 - Keep `static name = "User";` on guard classes. `fetch` serializes guard names and the API explorer filters on them; it looks like dead code, and deleting it breaks the UI. Comment it so the next reader knows.
+- **Every guard class also declares `static scope: GuardScope`, and it is required with no default.** `"account"` means the verdict reads the caller and nothing about the call, so it can be evaluated with no arguments — which is what lets an MCP listing hide what this caller certainly cannot use. `"resource"` means it needs the call's arguments (`context.getArg()`) and fails closed without them, so it is never evaluated for a listing: the entry stays visible and is stopped at call time. Getting it wrong is not a type error, so the marker is mandatory rather than defaulted — `SignedIn` / `Admin` / role checks are `"account"`, and every `Can<Verb><Model>` is `"resource"`. An `"account"` guard that throws at listing time reached for arguments it does not have: the entry is hidden from every caller and the guard is named once in the log as mismarked. A guard that admits no model at all — `Person` — adds `static agents = false`; the MCP catalogue then refuses every endpoint it guards outright, so the person-only act is absent from the document rather than hidden per caller.
 - The acting user arrives via `.with(Self)` / `.with(CurrentUserId)` / `.with(Me)`. Never trust a client-supplied id.
 - Guards ship with the library that owns the model and are imported by its own signals through the package path, so a mounting app inherits authorization and cannot forget it.
 - Services re-check ownership even when a guard already gated the call — two independent gates.
@@ -385,7 +480,24 @@ workflow changes.
 
 - `.body(...)` / `.param(...)` args accept `ConstantFieldTypeInput` only: scalars, model refs, or `enumOf(...)`.
 - Numbers must use `Int` or `Float` — `Number` is rejected (`pkgs/akanjs/signal/endpointInfo.ts`).
-- `Upload` is valid only inside a mutation flagged for file upload: `mutation([cnst.File], { fileUpload: true }).body("files", [Upload])` (see `libs/shared/lib/file/file.signal.ts`). It is not a model field type.
+- `Upload` is valid only inside a mutation flagged for file upload: `mutation([cnst.File], { fileUpload: true }).body("files", [Upload])`, as the `file` module does. It is not a model field type.
+- Bytes are `Binary`, never `Any` — see Scalar & Field Type Reference.
+
+### Binary Pubsub And Mutation Verbs
+
+Full contract — backpressure modes, the `Any`-carrying-bytes fallback, multi-verb paths: `get_guideline` with
+`transportRule`.
+
+- **`pubsub(Binary)` sends its payload in a websocket binary frame**, skipping the JSON envelope and the base64 a
+  JSON wire would need; the client's subscribe callback receives a `Uint8Array`. The optimization applies only
+  when the **whole** return is `Binary`. A declared `Binary` room **coalesces under backpressure** — keeping only
+  the newest frame — which is what telemetry and video want; declare `{ backpressure: "queue" }` when the frames
+  are a sequence a subscriber must see in full. A `pubsub(Any)` carrying bytes is framed too and warns once;
+  declare `Binary`.
+- **A `mutation` is `POST`.** `{ method: "PATCH" | "PUT" | "DELETE" }` moves it, and one path may carry several
+  verbs; two endpoints claiming the same path **and** verb fail the boot. Reach for it only when a foreign wire
+  protocol forces the verb — Akan's own `fetch.*` client, the OpenAPI document, and the API explorer all follow
+  whatever is declared.
 
 ### Reserved Endpoint Names
 
@@ -394,51 +506,63 @@ workflow changes.
 
 ### Slices, Queries, and Hydration
 
-- A slice's `exec` returns a `QueryOf` (an opaque query descriptor, `pkgs/akanjs/constant/types.ts`); you **cannot** chain `.sort()`/`.limit()` on it.
-- Apply ordering/paging via the store `init` fetch option instead: `initX(..., { sort, page, limit })` (`pkgs/akanjs/fetch/fetchType/sliceFetch.type.ts`).
-- Generated list accessors like `listBy(...)` return `Promise<Doc[]>`. For a chainable builder (`.sort().skip().limit().select()`) use the model facade's `findMany`/`findOne` (`FindManyChain`, `pkgs/akanjs/document/into.ts`).
-- **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`).
+Full contract — filter-arg `ref` pickers, `getQueryMeta` summary counters, `labelOf`, and the `q.exists` /
+`q.missing` / `q.empty` split: `get_guideline` with `queryRule`, or `akan guideline show queryRule`.
+
+- **The root slice (`""`, generated by `slice()`) takes `queryKey` and `args`, not a query.** `initX("byOwner",
+  [ownerId])` names one of the model's own filters and passes that filter's args; no key at all is the `any`
+  filter every model carries. A raw query descriptor could not survive the query string — `String(value)` sends
+  `[object Object]`. It is an admin API: `root:` is always `Admin`.
+- A slice's `exec` returns a `QueryOf` (an opaque query descriptor); you **cannot** chain `.sort()`/`.limit()` on
+  it. Apply ordering/paging via the store `init` fetch option instead: `initX(..., { sort, page, limit })`. For a
+  chainable builder use the model facade's `findMany`/`findOne`.
+- **A slice list is either one window or an accumulated one.** `setPageOf<Model>` swaps the window;
+  `loadMoreOf<Model>()` appends the rows after the ones loaded and takes **no page number** — it skips by
+  `<model>List.length`, so the offset cannot drift from what is on screen when a live insertion moves the server's
+  baseline, and `pageOf<Model>` stays 1, which is what keeps live placement (first page only) working past the
+  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.
 - 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
-  model that carries no removal side effect; otherwise remove documents one at a time.
+  `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 model that carries no removal side effect; otherwise remove documents one at a time.
 - **`update<Filter>` / `updateOne<Filter>` are chains, not calls:** `await updateInRoot(rootId).set({ status:
-  "archived" })`. The patch cannot trail the filter args — a filter's own args may be optional and no tuple type
-  puts a required element after those — so it lands on a terminal `.set()`, mirroring the `UPDATE … SET …` it
-  compiles to. Building the chain touches nothing; only `.set()` runs a query.
-- `removeOne` / `updateOne` hit the **newest** match — the subquery they compile to is ordered `createdAt` descending
-  and there is no way to change that. They also report only counts, never which row they touched, so they are for
-  "there is at most one of these", not for claiming the next item off a queue. Pass a query that matches one row.
-- **A filter may not be keyed after its own model.** Filter methods are assigned after CRUD, so a filter `chat` on
-  model `chat` would silently swap the single-document `removeChat`/`updateChat` for a hookless query-level one. It
-  throws at boot instead (`assertFilterFitsCrud`).
+  "archived" })`. The patch cannot trail the filter args, so it lands on a terminal `.set()`; building the chain
+  touches nothing.
+- `removeOne` / `updateOne` hit the **newest** match, always, and report only counts — they are for "there is at
+  most one of these", not for claiming the next item off a queue.
+- **A filter may not be keyed after its own model.** A filter `chat` on model `chat` would silently swap the
+  single-document `removeChat`/`updateChat` for a hookless query-level one; it throws at boot instead.
+- **"Has no value" is `q.empty`, never `q.missing`.** `q.missing` is the key being *absent from the stored JSON*,
+  which a document written once and saved again no longer is. Reach for it only to find rows written before the
+  field was declared.
 
 ### Text Search In A Filter — `q.search()`
 
+Full contract — relevance ordering, `columns` / `weights`: `get_guideline` with `queryRule`.
+
 - Text search is a filter query node like any other: `bySearch: filter().arg("text", String).query((text, q) =>
   q.search(text, { prefix: true }))`. The generated `listBySearch` / `countBySearch` / `queryBySearch` /
   `insightBySearch` come for free — you do **not** need a slice to make search usable.
 - **Only add a search slice when the model's data is safe to enumerate.** A filter is server-side; a slice is a
-  client-callable endpoint, so on a model whose slice `get:` is `Public` a search slice hands anyone a way to walk the
-  table. Leave that decision to the mounting app.
+  client-callable endpoint, so on a model whose slice `get:` is `Public` a search slice hands anyone a way to walk
+  the table. Leave that decision to the mounting app.
 - `q.search()` compiles to a JOIN, not a WHERE fragment, so it **must sit at an AND position**. Nesting it under
-  `q.any()` or `q.not()` throws, and it is rejected in `updateOneByQuery` / `updateManyByQuery` — a query-level write
-  takes no join, so ignoring the node would silently widen the write to every other matching row.
+  `q.any()` or `q.not()` throws, and it is rejected in `updateOneByQuery` / `updateManyByQuery`.
 - Blank or whitespace-only input matches **nothing**. Never "fix" that into a passthrough: a passthrough turns a
   search endpoint into a full listing.
-- Order by relevance with the built-in `relevance` sort key. It is an empty sort map, which the store reads as
-  "unspecified": score order when a search join is present, `createdAt` descending otherwise. That fallback is the
-  compiler's own, not a model-defined default — redefining `latest` on the model does not change it.
-- **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"]`.
+- Order by relevance with the built-in `relevance` sort key. A slice endpoint never reaches the unspecified
+  fallback — leaving `sort` off gets `latest`, so a client wanting score order has to name `relevance`.
 
 ### Service / Signal Injection
 
 - 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.
 
 ### Adapters — `adapt()` And `plug()`
 
@@ -456,8 +580,8 @@ export class AdminNoti extends adapt("adminNoti" as const, ({ use, env, plug, me
 - Inject it with `plug(TheClass)` from a service or from another adapter. Destructure only the injectors you use, and write the registration key `as const`.
 - **Do not register an `adapt()` class in `lib/option.ts`.** It self-registers, and `plug(Class)` uses the class itself as the token. `option.ts` is now only for legacy constructor-style adapters and for widening the options type.
 - `this.logger` is provided; never construct a `Logger` inside an `adapt()` class. Lifecycle work goes in `override async onInit()`.
-- **`adapt()` is for singletons only.** A per-use value object stays a plain class you `new` at the call site. Ask whether there is exactly one per process that a service needs injected; if not, it is a plain class.
-- **Legacy shape — recognise it, do not copy it.** Plain classes with `constructor(options: XOptions)`, registered in `lib/option.ts` as `options.x ? new XApi(options.x) : null` and injected with `use<T>()`, still work. Migrate one to `adapt()` only when you are already changing it.
+- **`adapt()` is for singletons only.** A per-use value object stays a plain class you `new` at the call site. If there is not exactly one per process that a service needs injected, it is a plain class.
+- **Legacy shape — recognise it, do not copy it.** Plain classes with `constructor(options: XOptions)`, registered in `lib/option.ts` and injected with `use<T>()`, still work. Migrate one to `adapt()` only when you are already changing it.
 
 Conventions that hold for both shapes:
 
@@ -466,7 +590,7 @@ Conventions that hold for both shapes:
 - Resolve secrets as `process.env.X ?? options.x ?? deterministicGenerator(...)` **inside a function**, never at module scope.
 - Extend a function by appending an optional trailing parameter with a default, never by changing arity.
 - Parameters: up to three required primitives positional; optional flags in a trailing `{ … } = {}`; four or more parameters, or any two same-typed strings, in one named destructured object.
-- Release locks in `finally`. Load heavy optional dependencies through a module-level memoized promise (`sharpLoad ??= import("sharp")`).
+- Release locks in `finally`. Load heavy optional dependencies through a module-level memoized promise (`puppeteerLoad ??= import("puppeteer")`).
 
 ### Error Placement
 
@@ -474,147 +598,115 @@ Conventions that hold for both shapes:
 - Best-effort code returns a sentinel (`null`, `undefined`, `[0, 0]`, `{}`). There are no Result/Either wrappers.
 - `try/catch` is rare and always converts an exception into a decision, never swallows one. Guards catch → `logger.warn` → `return false`; adapters catch → `logger.error` → `return null`; UI uses `try/finally` to reset a spinner. A bodyless `catch {}` is acceptable only with a one-line reason.
 - Store actions do not `try/catch` — let the framework toast the `Err`. Client-side validation failure is `msg.error("<key>")` plus an early return, never a throw.
+- **A failure another process reported travels as itself.** A server-to-server `fetch.<endpoint>(..., { origin })` restores the remote `Err` — the same class, key and `data` — so a hop that rethrows it answers its own caller with that error and the dictionary translates it. Never wrap the catch in a `new Error`, and never re-key it as a `new Err` of your own: both discard what the endpoint chose to say, and a bare `Error` is generalized to `Internal Server Error` on the way out.
 
 ### MCP Exposure
 
-Any signal can be served to AI agents as an MCP server on `POST /mcp`, and **nothing is exposed until it says so**.
-Turn it on in the app's `main.ts` — `new AkanApp("./server", { mcp: { … } })` — which takes `enabled`, `readOnly`,
-`path`, `version`, `instructions`, `allowedOrigins`, `pageSize`, `language`, and `auth`. That is the only
-app-authored place for it: `server.ts` is generated and takes no options, and the gateway configures a child
-through its environment — so each field also has an env spelling (`AKAN_MCP`, `AKAN_MCP_READONLY`,
-`AKAN_MCP_PATH`, `AKAN_MCP_VERSION`, `AKAN_MCP_INSTRUCTIONS`, `AKAN_MCP_ALLOWED_ORIGINS`, `AKAN_MCP_PAGE_SIZE`,
-`AKAN_MCP_LANGUAGE`, `AKAN_MCP_AUTH_SERVERS`, `AKAN_MCP_SCOPES`, `AKAN_MCP_RESOURCE`), which code overrides.
-The two booleans answer to `AKAN_PUBLIC_MCP` / `AKAN_PUBLIC_MCP_READONLY` too, the same pairing `AKAN_OPENAPI`
-has, and a value written in code wins over the env of the same name — an explicit `undefined` is not a value.
-`AKAN_MCP_PATH` is normalized to a leading `/`, because the route key and the OAuth metadata path are both built by
-concatenation.
-
-```typescript
-// <model>.signal.ts — a tool, a resource-backed slice, and a slash-command prompt
-export class TaskSlice extends slice(
-  srv.task,
-  // generated CRUD per verb; `list` is the model's own unfiltered list, which `slice()` generates itself
-  { guards: { root: Admin, get: SignedIn, cru: SignedIn }, mcp: { get: true, list: true } },
-  (init) => ({
-    // its own guards: the map above reaches base CRUD and the root slice, never a named slice
-    inTodo: init({ guards: [SignedIn], mcp: { expose: true } }).exec(function () {
-      return this.taskService.queryByStatuses(["todo"]);
-    }),
-  }),
-) {}
-
-export class TaskEndpoint extends endpoint(srv.task, ({ mutation, prompt }) => ({
-  startTask: mutation(cnst.Task, { guards: [SignedIn], mcp: { expose: true } })
-    .param("taskId", ID)
-    .exec(async function (taskId) {
-      return await this.taskService.startTask(taskId);
-    }),
-  reviewTask: prompt({ guards: [SignedIn], mcp: { expose: true } })
-    .param("taskId", ID)
-    .exec(async function (taskId) {
-      const task = await this.taskService.getTask(taskId);
-      return [Msg.user(`Review this task and suggest next steps.`), Msg.resource(`akan://task/${taskId}`, task)];
-    }),
-})) {}
-```
-
-- **The refusals are fail-closed and survive opting in**: `pubsub` and `message` (their internal args read a socket
-  an MCP request does not have), an `Any` or `Upload` return, a file upload, **a mutation with no real `guards`**
-  (`[Public]` is having none, spelled out — it answers true unconditionally), and **an argument typed `Any` that
-  must be filled**.
-  A `prompt` refuses two more, because its `arguments` is one string per name with no schema beside it: a **list
-  argument**, which could never carry a second value, and **any `Any` argument** — a tool leaves that out of its
-  schema, and a prompt has no schema to leave it out of. `resource: true` is refused there too: only a read
-  publishes a resource template.
-- **Every refusal is named in the boot log**, and so is every published entry that declares no `guards` at all —
-  the access is what `[Public]` grants, but only one of the two is a decision you made. One `warn` per endpoint
-  plus a `MCP catalogue: tools=… prompts=…` count. Read that line first when a tool you exposed is missing —
-  fail-closed is right, and a silent fail-closed leaves you nothing to read. `akan quality scan` covers the two
-  shapes visible in source, `akan.mcp.missing-description` and `akan.mcp.unguarded-exposure`; the API explorer
-  badges the per-endpoint rules (`MCP` / `MCP refused`) from the same rule the catalogue runs.
-- **An `Any` argument is left out of the published schema** rather than described as `{}` — it tells a model
-  nothing — and a value sent for one is refused by name, so the endpoint reads it as omitted. That is what happens
-  to the root list's raw `query` descriptor: read as sent, it would be an arbitrary filter over every model you
-  exposed through `mcp: { list: true }`. Expose a named filter slice when an agent should narrow a list.
-- **A nullable model return publishes no `outputSchema`**, and its empty answer ships as the text `null` with no
-  `structuredContent`. That field is an object by definition, so `null` cannot ride in it any more than an array
-  can — a list is wrapped as `{ items: … }` for the same reason — and a declared schema obliges every result to
-  match it, so a client SDK throws on the first call that finds nothing. A nullable *list* keeps its schema, and a
-  scalar return has no structured half at all: it ships as the value itself, not as JSON.
-- **An `outputSchema` names no `hidden` or `secret` field.** Every response has both stripped, so publishing them
-  promises a property no answer can carry — and on a model like `user` the names are the leak. Your *input* schema
-  keeps them: they are legal to send, and the same model describes a request body.
-- An endpoint that did not opt in answers the *same* "unknown tool" as one that does not exist. Never make that
-  message more helpful — the difference is what enumerates your private surface. A guard's refusal is generalized
-  the same way: the caller reads `You are not permitted to perform this action.`, never `Access denied by guard:
-  Admin`, which names your authorization structure to the one caller barred from it. A domain `Err` resolves
-  through the dictionary first and keeps its own words.
-- `mcp: { readOnly, destructive, idempotent }` only override the hints a client renders. Clients are told to
-  distrust hints; they are never a gate.
-- **`AKAN_MCP_READONLY=true` is the read-only-deployment valve, not the exposure switch.** It drops every mutation
-  whatever it declared, and reports each one in the boot log like any other refusal.
-- 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). `AKAN_MCP_AUTH_SERVERS`, `AKAN_MCP_SCOPES`, and `AKAN_MCP_RESOURCE`
-  configure it; `insufficient_scope` is enforced only once `AKAN_MCP_SCOPES` is set. A token carrying no `aud` at
-  all is refused once `AKAN_MCP_AUTH_SERVERS` names an issuer — that issuer mints tokens for its other resources
-  too — and accepted while none is named, because a first-party Akan token is bound by app and environment.
-- `akan quality scan` warns **`akan.mcp.missing-description`** for anything exposed without a dictionary `.desc()`.
-  An agent picks a tool by its description, so a missing one is a broken tool. What the framework generates is
-  exempt and borrows the model's own text, having none of its own: `mcp: { list: true }` reads the `.of()` label,
-  and the base CRUD tools append the model's `.desc()` to their generated `Get X`. Write that model `.desc()` — it
-  is the only text those entries can carry. The scan is not the whole answer either, because it reads source: **the
-  boot log names every published entry with no description**, generated ones included.
-- A browser-hosted client needs `allowedOrigins` **and** the CORS answer the server sends back for those origins.
-  Every other MCP client sends no `Origin` at all, and the one that does is matched against the forwarded host so
-  a proxy does not turn each call into a 403 — which is only as trustworthy as an edge that *overwrites* that
-  header. `AKAN_MCP_RESOURCE` pins the resource identifier where you cannot guarantee it.
-- **A `resources/read` uri that does not decode** — a stray `%` — is `Unknown resource`, not a server failure.
-- **A caller's own mistake is reported as one** and never as a server failure: an argument that is missing,
-  unparseable or **undeclared** comes back as `isError` naming it — `additionalProperties: false` travels in the
-  published schema and nothing on the wire enforces it — and so does a document that is not there, as
-  `No <model> found for the arguments given.` A `prompt`, having no `isError` to carry a refusal, answers `-32602`.
-  Only a real failure logs a stack; an agent can drive the rest at will.
-- **Three revisions are spoken**: the modern `2026-07-28` and the legacy `2025-11-25` / `2025-06-18`, which are
-  wire-identical over the POST-only surface this implements — a client whose proposal is not listed is told to
-  disconnect. An unknown proposal is answered at whichever end of that list it is closer to, and an unimplemented
-  method answers `404` to a modern client but `200` to a legacy one, whose era spends `404` on "your session is
-  gone".
-- **A modern-era request mirrors `MCP-Protocol-Version` and `Mcp-Method` into headers** (plus `Mcp-Name` when the
-  body names one), and one that leaves a mirror out is refused just like one that contradicts the body: a gateway
-  rule keyed on a header never fires for the request that omitted it. Legacy requests are not checked. Capabilities
-  are derived from the catalogue, so a server with no prompts does not advertise `prompts`.
-- **An expired or wrongly-audienced bearer token is refused up front**, so an agent is told to authenticate rather
-  than that the tool does not exist. Its **signature is not checked** — that needs your app's own secret — so a
-  token signed wrong, like an opaque one, still degrades to an anonymous caller.
-- **Resource URIs**: `akan://<model>/{id}`, `akan://<model>/light/{id}`, `akan://<model>/list` for the model's own
-  list, and `akan://<model>/list/<sliceKey>` for a slice's. The root list takes no third segment on purpose — any
-  token there is one a slice could also be named. **Those four are the whole set**, so `mcp: { resource: true }`
-  is honoured only on the generated reads: a custom endpoint keeps its tool, gets no resource template, and is
-  named in the boot log saying so.
-- **The catalogue is one language**, `en` unless `language` says otherwise: it is built once at boot and cached by
-  clients, so there is no `Accept-Language` negotiation.
-
-**`prompt()`** is invoked by the *user* — a client renders it as a slash command — not chosen by the model. `exec`
-returns `PromptMessage[]`, or a bare string that is wrapped into one user message; build them with `Msg.user` /
-`Msg.assistant` / `Msg.link` / `Msg.resource` / `Msg.image` / `Msg.imageOf`. It takes `.param()` and `.search()`
-only, because `prompts/get` sends a flat string map. **An embedded payload is masked by the model you name** —
-`Msg.resource(uri, task, { model: cnst.LightTask })`, or `Msg.mask(cnst.LightTask, task)` for one piece of an
-assembly. Taking the model as an argument is what makes a `{ ...doc }` spread maskable, since that and `toJSON()`
-arrive with the class already gone; a value with no model named whose `hidden`/`secret` fields are populated is
-**refused**, one level into a plain object too. **A `prompt` is also mounted as a
-plain HTTP `GET` whether or not you enabled MCP**, because that route is what lets a web UI preview one — and it
-is in your OpenAPI document like any other `GET`, answering the one fixed `PromptMessage[]` shape. MCP exposure
-gates the catalogue, not the surface, so guard it
-like any other read — and a prompt declaring no
-`guards` at all is named in the boot log, while an explicit `[Public]` is a decision and stays quiet. Every `Msg` builder takes
-optional `annotations` last (`audience`, `priority` 0..1, `lastModified`) — give the instruction a high `priority`
-and its attachments a low one, or a client with a full window drops blocks by position and keeps the attachment
-over the ask.
-
-**`McpProgress.report(n, { total, message })`** reports progress from anywhere inside a call, a service or adapter
-frames down included, and is a no-op when nobody is streaming — so the same code runs unchanged over HTTP, a
-websocket, and in tests. `McpProgress.streaming` says whether anyone is reading, for a report whose message
-costs something to assemble.
+Every signal is served to AI agents as an MCP server on `POST /mcp`. **`/mcp` is mounted by default and exposure
+follows an endpoint's guards — there is no per-endpoint opt-in, and nothing to write in a signal file.** An
+endpoint that declares a real guard is published; one that declares none is refused, and so is a mutation whose
+only guard is `Public`. The guards are already the authorization decision, so a second switch would say nothing
+they do not — while guaranteeing that every endpoint added later is invisible to agents until somebody remembers
+it.
+
+- **`mcp: false` keeps an endpoint off the shelf without touching its guards.** Guards answer "may an agent call
+  this"; they cannot answer "does this belong on a shelf", and a step of a UI-driven state machine
+  (`requestPhoneCodeForSignin`) is perfectly guarded and still a mistake for a model to reach. Write it in the
+  signal option (`mutation(Boolean, { guards: [Every], mcp: false })`, `init({ guards: [SignedIn], mcp: false })`),
+  or as an `mcp` map on `slice()` that **mirrors the `guards` map key for key** (`mcp: { cru: false }`) — root
+  slice and generated CRUD only, never a named slice or a custom endpoint. It is an opt-**out**, and it is
+  curation, not authorization: HTTP serves the endpoint exactly as before.
+- **Narrow by cost, and read the boot log first.** MCP forbids a `$ref` across entries, so every entry inlines the
+  schema of every model it mentions and the listing is re-sent whole to every agent that connects. By default a
+  response schema names a nested model instead of inlining it (`outputSchema: "shallow"`; `"full"` restores the
+  closure, `"none"` drops the schema and keeps the text block) and a request schema asks for a relation's id, which
+  is what the wire carries. `MCP catalogue: … · listing 214KB` plus a per-signal `MCP catalogue cost:` line says
+  where the rest went; `mcp: { cru: false }` on a model is the next lever. `outputSchema` moves wire bytes and client
+  memory only — the model receives names, descriptions and input schemas (measured: 219 tools ≈ 41k tokens either
+  way) — so tool count and the input model behind `create*` / `update*` are what cost context. In one line:
+  `Person` for an act reserved for a person, `mcp: { cru: false }` for the tools whose input models cost the model
+  tokens, `outputSchema` for nothing that reaches the model.
+- Settings live in the app's `lib/option.ts` — `option.setMcp({ enabled, readOnly, path, version, instructions,
+  allowedOrigins, pageSize, language, outputSchema, rateLimit, auth })`, or `setMcp((env) => …)` for one derived from the server env, **not
+  `main.ts`**. Each field has an `AKAN_MCP_*` env spelling. `AKAN_MCP_READONLY=true` is the read-only-deployment
+  valve, not the exposure switch; `AKAN_MCP=false` takes the whole surface off. Every call that executes an
+  endpoint is rate-limited per caller (120 a minute, 8 in flight, per process; 429 + `Retry-After`) — `rateLimit`
+  / `AKAN_MCP_RATE_LIMIT` tunes or disables it.
+- **Authentication is the same server.** An app mounting `libs/shared` serves the OAuth 2.1 authorization server
+  beside `/mcp` — `/.well-known/oauth-authorization-server`, `/oauth/authorize`, `/oauth/token`, `/oauth/register`
+  (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
+  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
+  neither, and `context.origin` is `"mcp"` for a call through the MCP endpoint. `guards: [Every, Person]` refuses a
+  model and, because `Person` declares `static agents = false`, takes the entry out of the MCP catalogue document
+  itself (named in the boot log like `mcp: false`); `.with(AgentCall)` hands an endpoint the same verdict as a
+  boolean to narrow what the call sets in motion; `isAgentCall(context)` is the function behind both
+  (`@libs/shared/srvkit`). Never sniff `aud` through a cast.
+- **The refusals are fail-closed**: a declared `mcp: false`, an endpoint with no `guards`, a mutation with no real
+  guard, `pubsub` and `message`, an `Any` or `Upload` return, a file upload, a required `Any` argument, and the
+  generated `light<Model>` read. An `enumOf` argument is checked against its values on every path. **Every refusal
+  is named in the boot log**, along with every published entry missing a dictionary `.desc()` — an agent picks a
+  tool by its description.
+- A refused endpoint answers the *same* "unknown tool" as one that does not exist, and a guard's refusal is
+  generalized. Never make either message more helpful — the difference is what enumerates your private surface.
+- **A `field.visual` field is stripped from every MCP result** and from the readable schema so the two agree.
+- **A structured result ships twice by default** — as `structuredContent` and as the same JSON in the text block.
+  `option.setMcp({ legacyTextBlock: false })` leaves a pointer there instead.
+- **A prompt is a screen: `page().prompt(name, description)`.** There is no `prompt()` on `endpoint()`.
+  `prompts/get` runs the page's body in the RSC worker under the caller's token — nothing is rendered — and answers
+  the description, one `resource` per `fetch.*` the page made (masked by the endpoint's return model, addressed by
+  its `akan://` uri, one document once whatever shapes read it) and the published tools of the modules it fetched
+  from, minus what is already attached; lists — only lists — are cut to `promptBudget`. A guard refusing a query
+  inside the body reads as the screen refusing the account, the same way a redirect does. A
+  required argument left out answers a pointer to the `<model>List…` tool, never a guess. The description is the
+  only instruction, in English — `<Agent.Guide>` never reaches MCP, and the in-page chat lists no page prompts.
+
+Full contract — configuration, wire behaviour, resource URIs, OAuth metadata, protocol revisions, and
+`McpProgress.report`: `get_guideline` with `mcpRule`, or `akan guideline show mcpRule`.
+
+## In-Page Agent
+
+Every akan app can host a component-level agent that reads the rendered screen and drives it. **A component
+declaration is the surface, exactly**: `st.tool` publishes one action, and `st.use` / `st.sel` / `st.ref` make one
+store key readable while the reading component is mounted. Nothing is derived from a store class — a lever the
+screen does not offer the user is not one an agent may pull in their place. The React core is the `use-agentic`
+package; apps and libs never import it directly (`no-import-external-library`) — everything reaches them through
+`st.*` and `akanjs/ui`.
+
+Read the full contract before building an agent surface — the chat's own options, `st.tool` / `st.expose` /
+`st.useState` in full, zones and namespaces, attachments and speech, slash commands, transcript compaction, and
+the built-in tool semantics: `get_guideline` with `agentRule`, or `akan guideline show agentRule`. What follows is
+what every developer must know even when not building one.
+
+- **Mount `<Agent.Chat />` once in a layout.** The endpoint is a stateless relay that **never executes tools**:
+  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 })`).
+- **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
+  tool without publishing it, and a `disabled` control publishes nothing.
+- **Forms publish themselves**: a `Field.*` / `Input.*` / `Select` / `Switch` handed `onChange={st.do.setXOnY}`
+  **by reference** publishes that setter, and `st.use.yForm()` adds `fillYForm(patch)`. An inline arrow publishes
+  nothing — normalize with the control's `transform` prop, and multi-write with a `_postSet<Field>` store method.
+  This is the same rule `no-unpublished-form-setter.grit` enforces.
+- **Reading is per key, not per store.** `st.use.x({ agent: false })` keeps a subscribed key off the surface; a key
+  no component reads is unreadable. A value with populated `hidden`/`secret` fields is refused at read.
+- **Return what answers the question, not the record.** A tool's value is capped at 20,000 characters before it
+  enters the transcript, and once there it rides *every* later turn. A field that is bulky and useless to a model
+  is fixed once at the model instead: `field.visual(String)`.
+- **Route guidance is `<Agent.Guide instructions="..." />`** rendered from a `_layout.tsx` or page — the render
+  tree is the cascade. It is a component, not a `pageConfig` field, and `*.abstract.md` is never served to agents.
+- **Model-facing text is English, always** — every `.desc()`, `instructions`, Guide text. The `l()` rule covers
+  strings a *user* reads.
 
 ## Scalar Modeling (`**/*.constant.ts`)
 
@@ -625,147 +717,148 @@ costs something to assemble.
 - Follow the established model layering pattern in this order: `Input`, `Object`, `Light<Model>`, full `<Model>`, and `<Model>Insight`. Write all five, and write `<Model>Insight` even when it is empty.
 - 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.
 
 ### Scalar & Field Type Reference
 
-- **Import from `akanjs/base`** (real classes/helpers, not globals): `Int`, `Float`, `ID`, `Any`, `Upload`, `enumOf`, and the `dayjs` factory. There is **no `JSON` scalar** — use `Any` for open/flexible payloads.
+- **Import from `akanjs/base`** (real classes/helpers, not globals): `Int`, `Float`, `ID`, `Any`, `Binary`, `Upload`, `enumOf`, and the `dayjs` factory. There is **no `JSON` scalar** — use `Any` for open/flexible payloads.
 - **Use the JS globals directly (no import needed)**: `String`, `Boolean`, `Date`. They are monkey-patched to behave like scalars, so `field(String)` typechecks.
 - **`Number` is not a valid field/body type.** `NumberConstructor` is intentionally not augmented, so `field(Number)` / `.body("x", Number)` fails to typecheck. Use `Int` or `Float` instead.
 - Runtime resolution of every scalar (globals included) goes through `PrimitiveRegistry` by `refName` (`pkgs/akanjs/base/primitiveRegistry.ts`).
+- **`Binary` is raw bytes on the wire, and never a model field.** It is `Uint8Array` on both sides — a Node
+  `Buffer` is one, so a server handler may pass one straight in — and it accepts base64 in either direction, so
+  the same declaration serves a JSON body and a binary frame. It is **not storable**: the class build refuses
+  `field(Binary)` naming the `File` model instead, because every non-base field lives in the `_doc` JSON column
+  and bytes would sit there as base64 and ride every read of the row. Never send bytes as `Any` — `Any` passes a
+  `Buffer` through untouched and `JSON.stringify` then spells it `{ type: "Buffer", data: number[] }`, which
+  `JSON.parse` never restores; the result is 3.6x the wire and a shape that only breaks at the first byte-offset
+  read. MCP refuses a `Binary` return for the same reason it refuses `Any`.
 
 ### 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.
+Full contract — the trigger-maintained mirror, tokenizer changes, `AKAN_SEARCH_ENABLED`: `get_guideline` with
+`queryRule`.
+
+- 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. Declaring roles is all the wiring there is.
 - Pick the role by what the value *is*, because `bm25` 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.
-- **A `secret`, `hidden`, or `resolve()` field with `text` throws at class-build time**, not at query time. That is
-  deliberate: the mirror is plaintext, so an indexed secret would leak through search. Do not work around it. The
-  same throw covers a `text` field *underneath* one of those — a scalar's own field is reachable through its parent,
-  so `f.secret(Noti)` where `Noti.label` carries a role is rejected at the parent, not silently indexed.
-- The role works on a relation too (`image: field(File, { text: "thumb" })`) and on an array (`playing: field([String],
-  { text: "tag" })`); an array of objects indexes by leaf key, including an array leaf (`works[*].tags`). A field
-  inside a `Map` indexes nothing: there is no fixed path to extract it from.
-- 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.
+  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.
+- **`field.secret`, `field.hidden` and `resolve()` take no `text` role — it is a compile error**, because the
+  mirror is plaintext and an indexed secret would leak through search. The same refusal throws at runtime as a
+  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.
-- `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.
 
 ### Image & File Fields
 
 - **Do not declare `Upload` as a model field.** `Upload` is a signal-body-only primitive (see Service And Signal Conventions). Models reference the `File` model instead.
-- Declare an image/file field as a relation to `File`: `image: field(File).optional()` for one, `images: field([File])` for many (see `libs/shared/lib/user/user.constant.ts`, `libs/shared/lib/banner/banner.constant.ts`).
+- Declare an image/file field as a relation to `File`: `image: field(File).optional()` for one, `images: field([File])` for many.
 - The store then auto-generates an `upload<Field>On<Model>(fileList)` action that calls the framework upload mutation and polls file status until it leaves `"uploading"` (`pkgs/akanjs/store/action.ts`).
-- Storage is wired through the `StorageAdaptor` DI role (default `BlobStorage`, `pkgs/akanjs/service/predefinedAdaptor/storage.adaptor.ts`); the reference implementation is the `file` lib (`libs/shared/lib/file/*`). Do not hand-roll data-URL fallbacks.
+- Storage is wired through the `StorageAdaptor` DI role (default `BlobStorage`, `pkgs/akanjs/service/predefinedAdaptor/storage.adaptor.ts`); the reference implementation is the `file` module. Do not hand-roll data-URL fallbacks.
 
 ### Cascade Remove — the `cascade` option
 
+Full contract — bulk planning, the auto-created index, cycle cutting, boot-time validation: `get_guideline` with
+`queryRule`.
+
 **The value names the direction, and getting it wrong is a data loss.** The two actions can sit on the same field
 shape, so `cascade` never means "related" — it means one of exactly these:
 
 - `removeRef` — *when I am removed, remove what this field points at.* Declared on the relation the owner holds:
-  `image: field(File, { cascade: "removeRef" })`, arrays included. Only a relation accepts it; a primitive, a bare
-  `ID`, and a scalar each fail the class build, because none of them names a document to remove.
+  `image: field(File, { cascade: "removeRef" })`, arrays included. Only a relation accepts it.
 - `removeWith` — *when what this field points at is removed, remove me.* Declared on the child's own reference to
-  its owner, so the owner never learns about its children and a lib model can be extended by an app's. Three forms:
-  a relation (`agentSession: field(AgentSession, { cascade: "removeWith" })`), an id with `ref`
-  (`field(ID, { ref: "agentSession", cascade: "removeWith" })`), or a polymorphic id with `refPath`
-  (`field(ID, { refPath: "parentType", cascade: "removeWith" })`). An array, a Map, `ref` together with `refPath`,
-  and a field naming no owner each fail the class build.
-- **A `refPath` must name an `enumOf` field.** A free-form owner type is unknowable at build time, so every model's
-  removal would have to sweep the polymorphic table on the chance it is the owner. The enum names the candidates and
-  the reverse index reaches only them.
-- **A cascade goes through the target's service, never its model** — unless it provably makes no difference. The
-  service path is what runs the target's `_postRemove`, which is where a module puts the side effect the removal has
-  to carry (`FileService._postRemove` deletes the stored blob there).
-- **Bulk is decided at boot, per target model, for both directions.** When the target has no `remove` schema hook, no
-  `_pre`/`_postRemove` (its own or a lib's), no cascade of its own, and no children, one `removeManyByQuery` leaves
-  exactly the rows the loop would, so the framework takes it. Adding a `_postRemove` to that model silently flips it
-  back to one document at a time — the boot log (`info` summary, `verbose` per edge) is the only place that shows.
-- **The plan is sealed after every service is live**, so a `listenPost("remove")` registered in `onInit` still counts
-  and a `removeRef` target the app never mounted fails the boot rather than the first removal. An unmounted
-  `removeWith` owner fails the boot too; an unmounted `refPath` candidate only warns, since that list spans optional
-  modules by design.
+  its owner, so the owner never learns about its children and a lib model can be extended by an app's. Three
+  forms: a relation, an id with `ref`, or a polymorphic id with `refPath`. An array, a Map, `ref` together with
+  `refPath`, and a field naming no owner each fail the class build.
+- **A `refPath` must name an `enumOf` field** — a free-form owner type is unknowable at build time. The one
+  exception is opt-in and priced: `cascade: "removeWithAny"` takes a free-form `String` type field holding the
+  owner's refName, and sweeps for children on **every** model's removal. The sweep is one indexed probe, but a
+  single wildcard edge turns every cascade in the app back to one document at a time; the boot log names the
+  edges in one `info` line. The action carries its own `refPath` in the option type, so the widening cannot be
+  declared apart from the direction it widens.
+- **A cascade goes through the target's service, never its model** — that path is what runs the target's
+  `_postRemove`, where a module puts the side effect the removal has to carry.
 - **Nothing checks whether another document still references the same target.** `File` in particular is deduped by
-  `origin`, so two parents can share one row; declaring `removeRef` says the field owns its target exclusively, and
-  that judgement is the declaring model's to make.
-- Removal is soft (`removedAt`) but the storage delete a `_postRemove` performs is not — a cascade is not
+  `origin`, so two parents can share one row; `removeRef` claims the field owns its target exclusively.
+- Removal is soft (`removedAt`), but the storage delete a `_postRemove` performs is not — a cascade is not
   restorable, and reviving the owner does not revive what went with it.
-- A `removeWith` declaration **auto-creates its index** (`{ removedAt, fk }`, or `{ removedAt, typeKey, fk }` when
-  polymorphic). Every non-base field lives in the `_doc` JSON column, so the lookup would otherwise scan the table
-  on every owner removal.
-- **Query-level removes fire no hooks and therefore no cascade.** `removeManyByQuery` / `updateManyByQuery`, the
-  generated `remove<Filter>` / `update<Filter>`, and the facade's `removeById` / `updateById` stamp
-  `removedAt` in one atomic UPDATE, so nothing downstream runs. Remove one document at a time when it cascades.
-- Cascades are **idempotent**: `removedAt IS NULL` is ANDed into every query-level write, so a retry after a partial
-  failure re-stamps nothing. Cycles are cut by a visited set carried down the whole chain, with a depth cap of 16.
+- **Query-level removes fire no hooks and therefore no cascade** — `removeManyByQuery` / `updateManyByQuery`, the
+  generated `remove<Filter>` / `update<Filter>`, and the facade's `removeById` / `updateById`. Remove one document
+  at a time when it cascades.
 
 ## Akan Page Routing (`apps/**/page/**`)
 
 - `apps/<app>/page` may contain route modules only. Do not add helper logic or component-only files there.
 - Route source files under `page/` must use `.tsx`. Do not add `logic.ts`, `.js`, or `.jsx` files under `page/`.
-- Route pages use `_index.tsx`; layouts use `_layout.tsx`; per-route UI overrides use `_overrides.tsx`.
+- A route page is either `<routeName>.tsx` (serving `/routeName`) or a directory's `_index.tsx`; layouts use `_layout.tsx`; per-route UI overrides use `_overrides.tsx`.
 - Reserved `_*.tsx` route filenames are limited to `_index.tsx`, `_layout.tsx`, and `_overrides.tsx`; do not add files like `_Component.tsx` or `_helper.tsx`.
 - Page filenames must not start with an uppercase letter. Move helper components like `Component.tsx` to app `ui`, `common`, or `lib` instead.
 - Dynamic segments use `[id]`; route groups use directories like `(user)`, `(public)`, `(tab)`, or `(detail)`.
-- Page modules should usually export `default`, `pageConfig`, `head`, `generateHead`, or `Loading`.
+- **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.
+- **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
+  search value that fails is dropped. A layout may declare a subset. Names are string literals: `akan sync` reads
+  them off the source and refuses a `[projectId]` folder whose page declares no `.param("projectId")`. `lang` is
+  never declared: every route sits under `/:lang`, and the locale segment reaches every stage as `lang`.
 - `_overrides.tsx` is a logic-free UI-override manifest: imports plus a single `export default override({ Slot: AppComponent })` (from `akanjs/ui`), no `"use client"`. It re-skins framework `akanjs/ui` components for its route subtree; nested manifests merge over ancestors slot-by-slot (closest wins). See the UI Customization reference for the slot list.
-- Prefer `export default function Page` or `export default async function Page` for page components.
+- The legacy shape — `export default async function Page` beside `pageConfig` / `head` / `Loading` exports — still
+  loads and logs one deprecation warning per file at boot. Migrate with the `workspaceRecipes` recipe "Migrating
+  `page/` to the route chain"; new files are never written in it.
 - `libs/<lib>/page` follows the same rules and ships routes to apps that opt in with `syncPageLibs` in `akan.config.ts`: `true` takes every lib dep that has a `page` folder, an array takes the libs listed, `false` (the default) syncs nothing.
 - `akan sync` links those routes into `apps/<app>/page/(libs)/(<lib>)` — once per basePath when the app declares subRoutes. The folder is generated and gitignored; edit the lib source, never the link.
-- Both path segments are route groups, so a lib route mounts at its own path (`libs/shared/page/login/_index.tsx` serves `/login`). Two synced routes that resolve to the same pattern are a sync-time error.
-- `export const pageConfig = { devOnly: true }` keeps a route out of `akan build` while it keeps serving under `akan start` and keeps being typechecked. On a `_layout.tsx` it excludes every route under that directory too. Write it as a literal `true`/`false` — the build reads it off the source without evaluating the module.
-- Before changing route behavior, check `pkgs/akanjs/server/src/routeTree.tsx` and nearby routes for the expected pattern.
+- Both path segments are route groups, so a lib route mounts at its own path (`libs/<lib>/page/login/_index.tsx` serves `/login`). Two synced routes that resolve to the same pattern are a sync-time error.
+- `.config({ devOnly: true })` keeps a route out of `akan build` while it keeps serving under `akan start` and keeps being typechecked. On a `_layout.tsx` it excludes every route under that directory too. Write it as a literal `true`/`false` — the build reads it off the source without evaluating the module.
+- Before changing route behavior, check `pkgs/akanjs/server/routeTreeBuilder.ts` and nearby routes for the expected pattern.
 
 ### Page Body Shape
 
 ```tsx
-interface PageProps {
-  params: { orgId: string };
-}
-
-export default async function Page({ params }: PageProps) {
-  const { l } = usePage();
-  getSelf({ unauthorize: "/signin" });
-  const { orgId } = params;
-  const [{ org }, { taskInitInOrg }] = await Promise.all([fetch.viewOrg(orgId), fetch.initTaskInOrg(orgId)]);
-  return <Task.Zone.Card init={taskInitInOrg} prefix={`/org/${orgId}`} />;
-}
-
-export const pageConfig = { transition: "stack" } satisfies PageConfig;
+export default page()
+  .param("orgId", ID)
+  .config({ transition: "stack" })
+  .render(async ({ orgId }) => {
+    const { l } = usePage();
+    getSelf({ unauthorize: "/signin" });
+    const [{ org }, { taskInitInOrg }] = await Promise.all([fetch.viewOrg(orgId), fetch.initTaskInOrg(orgId)]);
+    return <Task.Zone.Card init={taskInitInOrg} prefix={`/org/${orgId}`} />;
+  });
 ```
 
-- There is no `loader=` / `render=` page prop. Pages are `export default async function Page`.
-- Declare `interface PageProps { params: {...}; searchParams?: {...} }` immediately above the default export.
-- Body order: `usePage()`, auth, destructure params, fetch, return.
+- There is no `loader=` / `render=` page prop and no `PageProps` interface: the chain declares the arguments and
+  `.render()` receives them flat, typed, with `lang` on every route and `children` added for a layout.
+- Body order inside `.render()`: `usePage()`, auth, fetch, return.
 - Run independent fetches through `Promise.all`, even when there is only one.
 - Gate auth at `_layout.tsx`; repeating `getSelf({ unauthorize: "/signin" })` in the page is fine and common.
-- Keep `async` even when nothing is awaited — it marks a real server page.
+- `async` on the render callback only when the body awaits; the callback is not a React component, so it takes no
+  name and no return type.
+- Publish a screen to agents with `.prompt(name, description)` — see MCP Exposure.
 - No `useState`, no `useEffect`, and no comments in page files.
 
 ## 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`.
+- `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`.
-- That allowlist has one source — `pkgs/@akanjs/devkit/workspaceLayout.ts`. `akan sync` (error), `akan doctor`
+- `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.
+- 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.
 - `akan sync` maintains a scoped agent guide per app/lib: `apps/<app>/AGENTS.md` / `libs/<lib>/AGENTS.md`. The
   section between the `akan:agent` markers (the `## Recipes In Scope` index) is generated — do not hand-edit it;
   content outside the markers is yours. `akan lint` fails when the generated section is stale.
 - The `plugin/` facet holds Akan plugin declarations; files use the `<name>.plugin.ts` convention (e.g. `pushNotification.plugin.ts`) and are re-exported from the generated `plugin/index.ts` barrel.
-- Do not add `apps/*/base`; place shared app utilities under `apps/*/common`.
-- `apps/*/lib` and `libs/*/lib` root files are limited to generated/support files: `cnst.ts`, `db.ts`, `dict.ts`, `option.ts`, `sig.ts`, `srv.ts`, `st.ts`, `useClient.ts`, `useServer.ts`.
+- Do not add `apps/*/base` or `libs/*/base`; place shared utilities under that app or lib's own `common/`.
+- `apps/*/lib` and `libs/*/lib` root files are limited to generated/support files: `cnst.ts`, `db.ts`, `dict.ts`, `option.ts`, `sig.ts`, `srv.ts`, `st.ts`, `useClient.ts`, `useServer.ts` — plus a `<model>.signal.test.ts` / `.spec.ts`, the one hand-written file that belongs there because the suite boots the whole barrel.
 - Domain module folders are `lib/<model>` for database modules, `lib/_<service>` for service modules, and `lib/__scalar/<scalar>` for scalar modules.
 - Database module UI files are limited to `<Model>.Template.tsx`, `<Model>.Unit.tsx`, `<Model>.Util.tsx`, `<Model>.View.tsx`, and `<Model>.Zone.tsx`.
 - Service module UI files are limited to `<Service>.Util.tsx` and `<Service>.Zone.tsx`.
@@ -802,7 +895,7 @@ when two shapes disagree.
 - 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 daisyUI semantic tokens.
+- Raw palette grays such as `text-gray-400` instead of the semantic tokens (`text-foreground/70`).
 
 ## Secrets And Env Safety (`.env`, `infra/**`, `*secret*`, `*credential*`)
 
@@ -815,11 +908,42 @@ when two shapes disagree.
 ## Application Test Commands
 
 - After changing application source code, test the app with `bun run akan start <appName>`.
+- **`akan start` takes several apps** — `akan start a,b`, `akan start a b`, `akan start all`, or no argument at
+  all for a checkbox that remembers the last pick.
+- **It opens a full-screen view by default, at any app count.** A rail of apps with the processes inside each
+  one — `host` for the dev host, gateway and RSC worker, plus a row per replica the gateway forwards — and the
+  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.
+  **`--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.**
+  Ink repaints one frame in place, so the full-screen view leaves a bordered screenshot in the scrollback and
+  takes the rest of the session with it — a drag-selection is cleared by the next repaint, and what survives
+  carries borders and lines truncated to the pane. The file is the same output with no ANSI, nothing truncated,
+  and every process of the app in arrival order, including the dev host's own build output, which reaches no
+  other file. The previous session is kept beside it as `dev.prev.log`. Hand somebody — or an agent — the
+  path rather than a paste: it costs one line instead of a transcript, and it can be re-read after a fix.
+  In the view, `y` copies the lines the filters have already narrowed and `Y` copies the path.
+- **How many apps boot at once is the machine's answer, not a constant.** A cold boot build is the builder's
+  RSS peak (~900MB per app), so the default wave is what memory and cores allow — half the memory budget
+  divided by that peak, and one app per four cores — which boots a laptop's apps together and still staggers
+  them inside a small container. The session says which in one line. `--concurrency <n>` overrides it, and
+  `AKAN_MEMORY_LIMIT` lowers the budget it derives from.
+- `--kill` frees the dev ports first — it resolves each port's listener, walks up to the top of that akan dev
+  tree and signals it, so another checkout's server or a stale orphan on the same port is reclaimed. A holder
+  that is not recognisably an akan process is reported and left alone.
+- **A dev server watches its own app directory and the libs it actually depends on**, transitively, resolved
+  once at boot from the synced manifests — so a save under a lib the app never imports rebuilds and reloads
+  nothing, and neither does a save in a sibling app. An import that makes a new lib a dependency needs a
+  fresh `akan start`, because it needs a `sync` first anyway. Before the first `sync` the manifests do not
+  exist yet and the whole `libs/` container is watched, which is the safe direction.
 - Test production build generation with `bun run akan build <appName>`.
 - To test a built artifact locally, run it from the generated app directory with the required Akan runtime environment variables.
 
 ```bash
-cd dist/apps/akan && USE_AKANJS_PKGS=true AKAN_PUBLIC_REPO_NAME=akanjs AKAN_PUBLIC_SERVE_DOMAIN="akanjs.com" AKAN_PUBLIC_APP_NAME=akan AKAN_PUBLIC_ENV=local AKAN_PUBLIC_OPERATION_MODE=local SERVER_MODE=federation AKAN_PUBLIC_BASE_PATHS=akanjs,soft,office bun main.js
+cd dist/apps/<appName> && USE_AKANJS_PKGS=true AKAN_PUBLIC_REPO_NAME=<repo> AKAN_PUBLIC_SERVE_DOMAIN="<domain>" \
+  AKAN_PUBLIC_APP_NAME=<appName> AKAN_PUBLIC_ENV=local AKAN_PUBLIC_OPERATION_MODE=local SERVER_MODE=federation \
+  AKAN_PUBLIC_BASE_PATHS=<basePaths> bun main.js
 ```
-
-- Adjust `<appName>`, `AKAN_PUBLIC_APP_NAME`, and `AKAN_PUBLIC_BASE_PATHS` to match the app being tested.