@akanjs/cli 3.0.0-alpha.9 → 3.0.0-alpha.90

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,12 +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. 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}`)
 
@@ -110,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
@@ -141,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.
@@ -196,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`)
 
@@ -259,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.
 
@@ -293,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` /
@@ -325,9 +419,8 @@ 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()`.
@@ -350,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"`.
 - 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.
@@ -370,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
 
@@ -379,45 +506,49 @@ 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`.
+- **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
 
@@ -441,8 +572,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:
 
@@ -451,7 +582,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
 
@@ -460,6 +591,85 @@ Conventions that hold for both shapes:
 - `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.
 
+### MCP Exposure
+
+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
+  full schema of every model it mentions and the listing is re-sent whole to every agent that connects. A plain
+  21-field model costs 12.6KB over eight entries; `mcp: { cru: false }` takes it to 4.7KB. `MCP catalogue: … ·
+  listing 214KB` plus a per-signal `MCP catalogue cost:` line says where it went.
+- Settings live in the app's `lib/option.ts` — `option.setMcp({ enabled, readOnly, path, version, instructions,
+  allowedOrigins, pageSize, language, auth })`, **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.
+- **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. A `prompt` also refuses a list argument and any `Any` argument. **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.
+- **`prompt()`** is invoked by the *user* as a slash command, never chosen by the model. `exec` returns
+  `PromptMessage[]` built with `Msg.user` / `Msg.assistant` / `Msg.resource` / `Msg.image`; an embedded payload is
+  masked by the model you name, and one whose `hidden`/`secret` fields are populated with no model named is
+  refused. It is also mounted as a plain HTTP `GET` whether or not MCP is enabled, so guard it like any other read.
+
+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`)
 
 - Define Akan models in `.constant.ts` files with `via` from `akanjs/constant`.
@@ -469,96 +679,79 @@ Conventions that hold for both shapes:
 - 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.
+- **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)`.
@@ -567,9 +760,9 @@ shape, so `cascade` never means "related" — it means one of exactly these:
 - Prefer `export default function Page` or `export default async function Page` for page components.
 - `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.
+- 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.
 - `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.
+- Before changing route behavior, check `pkgs/akanjs/server/routeTreeBuilder.ts` and nearby routes for the expected pattern.
 
 ### Page Body Shape
 
@@ -599,17 +792,19 @@ export const pageConfig = { transition: "stack" } satisfies PageConfig;
 
 ## 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`.
@@ -630,6 +825,7 @@ export const pageConfig = { transition: "stack" } satisfies PageConfig;
 | `plugin/` | build- or CLI-time `AkanPlugin` | `<name>.plugin.ts`, registered in `akan.config.ts` |
 
 - Hooks return a named object of async closures, never a tuple.
+- `libs/<lib>/ui/tokens.css` is the one CSS file a lib owns: plain `:root` custom properties for colors that must **not** follow the theme (a vendor brand color, a fixed surface). Every app whose pages reach that lib compiles it automatically, ahead of the app's own stylesheets, so nothing is imported by hand and no app can forget it. Reference them as `bg-[var(--kakao)]`; `@theme` extensions stay in the app stylesheet, because the color vocabulary is closed per stylesheet. Theme-following colors are the app's, not the lib's.
 - A layer-root `index.ts` is generated, but a `ui/<Folder>/index.tsx` that builds a namespace is hand-written source. The distinguishing test is that a generated barrel contains nothing but `export * from "./X";` lines.
 - `ui/<Folder>/index_.tsx` (trailing underscore) is the `"use client"` + `lazy()` boundary, with a server-safe `index.tsx` beside it. Collapsing the pair into one file breaks RSC.
 
@@ -645,7 +841,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*`)
 
@@ -658,11 +854,24 @@ 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, `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.
+- `--concurrency <n>` boots more than one app at a time; the default of 1 is what keeps two cold builder peaks
+  from overlapping. `--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.
 - 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.