@akanjs/cli 3.0.0-alpha.70 → 3.0.0-alpha.71

package/guidelines/framework/framework.generate.json

@@ -20,11 +20,12 @@
   ],
   "update": {
     "filePath": "./framework.instruction.md",
-    "contents": ["purpose", "file ownership", "current API patterns", "codegen rules", "validation checklist"],
+    "contents": ["file ownership", "current API patterns", "codegen rules", "theming and UI customization"],
     "rules": [
       "Use current Akan APIs only",
       "Keep output parseable for codegen",
-      "Include ownership boundaries and review checklist"
+      "Include ownership boundaries",
+      "Carry no meta about this document itself — it renders into every workspace's always-loaded AGENTS.md"
     ]
   },
   "page": "apps/akan/page/(docs)/docs/intro/fundamentals.tsx"

package/guidelines/framework/framework.instruction.md

@@ -1,8 +1,5 @@
 # Akan.js Framework Guide
 
-## Purpose
-Use this as the compact framework context for AI codegen. It should explain how Akan turns convention-based files into a full-stack app without teaching every API in one place.
-
 ## Ownership
 - `apps/<app>` contains app code, pages, env files, module folders, UI, webkit, srvkit, and common utilities.
 - `libs/<lib>` contains reusable domain and utility libraries consumed by apps.
@@ -28,9 +25,3 @@ When a request implies a distinct look and feel, do not stop at colors — custo
 - **Theme (`apps/<app>/page/styles.css`).** The app imports Tailwind and `akanjs/ui/styles.css`, then overrides semantic token *values* per theme under `:root, [data-theme="dark"]` and `[data-theme="light"]` (`--background`, `--foreground`, `--primary`, `--muted`, `--border`, … each with a `-foreground` pair for text). The framework maps them to Tailwind color names, so `bg-primary` / `text-foreground` follow the `data-theme` attribute; corner rounding uses `--radius-box` / `--radius-field`. Fetch `get_guideline` with `cssRule` for the full token set before a deep theme pass.
 - **Lib tokens (`libs/<lib>/ui/tokens.css`).** Colors a lib's own components pin — a vendor brand color, a fixed surface — are declared once there as plain `:root` custom properties and compiled into every app that reaches the lib, ahead of the app's stylesheets. Reference them as `bg-[var(--kakao)]`; never copy the block into each app.
 - **Components (`page/**/_overrides.tsx`).** When a default `akanjs/ui` component (Button, Modal, Table, Input, Select, …) is too restrictive for the design, re-skin it per route instead of forking, wrapping, or fighting it with utility classes. Write a drop-in replacement in `apps/<app>/ui/` typed against the slot contract (`AkanModalComponent`, or `AkanUiOverrides["<Slot>"]`), composing the framework's headless parts, then bind it in a `page/**/_overrides.tsx` manifest with a single `export default override({ Slot: BrandComponent })`. Overrides cascade down the route tree like layouts (closest ancestor wins). Fetch `get_guideline` with `componentRule` and read the `references/ui/customize` docs page for the slot list and patterns.
-
-## Review Checklist
-- The instruction points to current docs pages, not removed docs routes.
-- Generated examples use current Akan builder APIs and scanner-friendly filenames.
-- The output contract tells the model which file paths to return.
-- The guide avoids broad framework essays when a concrete file rule is better.

package/guidelines/mcpRule/mcpRule.instruction.md

@@ -151,14 +151,11 @@ export class TaskEndpoint extends endpoint(srv.task, ({ mutation, prompt }) => (
   and are not configurable. 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.
-- **RFC 9728 metadata is published only once `AKAN_MCP_AUTH_SERVERS` names an issuer.** An unprotected resource
-  that still advertises `bearer_methods_supported` is treated by Cursor (and similar clients) as an OAuth
-  mandate, so the well-known document is absent until there is somewhere to obtain a token. When it is served,
-  it lives at `/.well-known/oauth-protected-resource` (and at that path plus the mount path, the spelling most
-  clients try first). `AKAN_MCP_SCOPES` and `AKAN_MCP_RESOURCE` configure the document when it exists;
-  `insufficient_scope` is enforced only once `AKAN_MCP_SCOPES` is set. A token carrying no `aud` at all is
-  refused once an issuer is named — 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.
+- 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.
 - **The boot log names every published entry with no dictionary `.desc()`.** An agent picks a tool by its
   description, so a missing one is a broken tool. What the framework generates has no text of its own and borrows
   the model's: the generated list reads the `.of()` label, and the base CRUD tools append the model's `.desc()` to

package/guidelines/queryRule/queryRule.generate.json

@@ -0,0 +1,31 @@
+{
+  "title": "Query Rule",
+  "description": "Akan data access — filters, slices and hydration, full-text search, and cascade removal",
+  "group": "core",
+  "codegenPriority": 4,
+  "deprecated": false,
+  "scans": [
+    {
+      "type": "example",
+      "description": "Filter and model declarations that drive the generated query surface",
+      "path": "{apps,libs}/*/lib/*/*.document.ts",
+      "sample": 4
+    },
+    {
+      "type": "example",
+      "description": "Slice declarations that expose a query to a client store",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "sample": 4
+    }
+  ],
+  "update": {
+    "filePath": "./queryRule.instruction.md",
+    "contents": ["slices and hydration", "generated filter methods", "text search", "cascade removal"],
+    "rules": [
+      "Use current Akan APIs only",
+      "State the rule and the reason it exists, never restate a type signature",
+      "Say which generated methods fire hooks and which do not",
+      "Keep it workspace-neutral — no app or repo names"
+    ]
+  }
+}

package/guidelines/queryRule/queryRule.instruction.md

@@ -0,0 +1,143 @@
+# Query Rule — Filters, Slices, Hydration, Search, Cascade
+
+How a model's data is queried, exposed to a client store, searched, and removed. Filters and slices are the two
+query surfaces; `q.search()` and the `text` field roles are the search surface; `cascade` is what a removal takes
+with it. `conventions` carries the invariants — this is the full contract behind them.
+
+## Slices, Queries, and Hydration
+
+- **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 let a caller compose a query the model never declared, and
+  could not survive the query string at all — `String(value)` sends `[object Object]`. Args are parsed by the type
+  the filter declared, a missing required one is refused, and args past the declared ones are dropped
+  (`resolveFilterQuery`, `pkgs/akanjs/document/filterMeta.ts`). It is an admin API: `root:` is always `Admin`.
+- **Give an id filter arg a `ref` and the admin panel stops asking for hex.** `filter().arg("ownerId", ID, { ref:
+  "user" })` names the model the id points at; the arg then renders a picker that runs the same query maker against
+  that model's own filters, so a ref of a ref keeps nesting. The picker holds its rows in local state rather than the
+  ref model's store — that store is a singleton, and loading into it would overwrite whatever listing of the same
+  model is already on screen. `ref` is the only UI hint a filter arg carries; there is no render callback, because a
+  function cannot cross to the client.
+- **A summary counter names the listing it counts, on the field itself.** `field(Int).meta(getQueryMeta("user")
+  .query("byStatuses").args([["prepare"]]))` is what makes the dashboard tile clickable: clicking it applies that
+  filter to the listing in place — one request, no navigation — and fills the arg controls under the toolbar, so
+  the filter is visible and editable rather than opaque. `args` may be a thunk (`() => [dayjs().subtract(1,
+  "hour")]`), read at the click so a relative time is current. A meta naming a different model counts a different
+  listing, so its tile stays inert here. `AdminPanel`'s `queryMap` still overrides per column, and is now only for
+  a column whose field cannot declare one.
+- **A picker row is labelled by `labelOf`, which reads `Light<Model>.label()` first.** Then the field carrying
+  `text: "title"`, then `title` / `name`, with the id as the floor. Write the method on the Light class — that is
+  where display logic belongs, and the same label is what `Load.Units` and the in-page agent's screen scope show.
+  A model with none renders ids and says so in the picker.
+- 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`).
+- 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.
+- **`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`).
+- **"Has no value" is `q.empty`, never `q.missing`.** The three absence operators are distinct: `q.exists` is the
+  key being present, `q.missing` is the key being *absent from the stored JSON*, and `q.empty` is either — absent,
+  or present and null. An optional field is written both ways over its life: an insert that omits it leaves the key
+  out, while a document read back and saved carries the explicit `null` that the read materialized. So `q.missing`
+  matches a freshly inserted row and silently stops matching that same row after its first round-trip save. Reach
+  for it only to find rows written before the field was declared.
+
+## Text Search In A Filter — `q.search()`
+
+- 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.
+- `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.
+- 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"]`.
+
+
+## Text Search Fields — the `text` role
+
+- A field joins the full-text index by declaring one of five roles: `field(String, { text: "title" })`, and likewise
+  `"desc"`, `"tag"`, `"thumb"`, `"filter"`. Nothing else opts a field in, and there is no per-model switch.
+- Pick the role by what the value *is*, because `bm25` weights them positionally (`title` 10, `tag` 3, `desc` 1,
+  `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.
+- **`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 class build throws the same refusal as
+  a backstop, for an option object the excess-property check cannot see through, and names the way out: drop the
+  role, or leave the field unmasked. Do not work around either. The throw also 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; that one is only reachable at runtime, since the
+  pairing spans two files.
+- 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.
+- 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.
+
+## Cascade Remove — the `cascade` option
+
+**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.
+- `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 (`field(AgentSession, { cascade: "removeWith" })`), 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, so every
+  model's removal would have to sweep the polymorphic table on the chance it is the owner.
+- **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.
+- **Bulk is decided at boot, per target model, for both directions.** A target with no `remove` schema hook, no
+  `_pre`/`_postRemove`, no cascade of its own, and no children takes one `removeManyByQuery`. Adding a
+  `_postRemove` silently flips it back to one document at a time — the boot log is the only place that shows.
+- **The plan is sealed after every service is live**, so a `listenPost("remove")` registered in `onInit` counts,
+  and an unmounted `removeRef` target or `removeWith` owner fails the boot rather than the first removal. An
+  unmounted `refPath` candidate only warns, since that list spans optional modules by design.
+- **Nothing checks whether another document still references the same target.** `File` in particular is deduped
+  by `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.
+- **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.
+- Cascades are **idempotent**: `removedAt IS NULL` is ANDed into every query-level write. Cycles are cut by a
+  visited set carried down the whole chain, with a depth cap of 16.
+

package/guidelines/runtimeRule/runtimeRule.generate.json

@@ -0,0 +1,25 @@
+{
+  "title": "Runtime Rule",
+  "description": "Akan build and runtime surfaces — web/csr toggles, the gateway/solo process model, logging, the generated image, and shipped assets",
+  "group": "core",
+  "codegenPriority": 4,
+  "deprecated": false,
+  "scans": [
+    {
+      "type": "example",
+      "description": "App and lib runtime declarations",
+      "path": "{apps,libs}/*/akan.config.ts",
+      "sample": 4
+    }
+  ],
+  "update": {
+    "filePath": "./runtimeRule.instruction.md",
+    "contents": ["web surface toggles", "process model", "logging and live tail", "generated image", "shipped assets"],
+    "rules": [
+      "Use current Akan APIs only",
+      "State the rule and the reason it exists, never restate a type signature",
+      "Name the env that narrows a build-time declaration wherever one exists",
+      "Keep it workspace-neutral — no app or repo names"
+    ]
+  }
+}

package/guidelines/runtimeRule/runtimeRule.instruction.md

@@ -0,0 +1,176 @@
+# Runtime Rule — Serving, Processes, Logging, Image, Assets
+
+How an Akan app is built, what it serves, how many processes it runs, where its logs go, and what ends up in
+its image. Everything here is declared in `akan.config.ts` or narrowed by an env at boot; none of it is reached
+from domain code. `conventions` carries the invariants — this is the full contract behind them.
+
+## Web Surfaces — Building And Serving Without SSR/CSR
+
+An app serves three things: the API, the SSR/RSC web renderer, and the CSR single-file bundle. The API is always
+on; the other two are declared in `akan.config.ts` as **`web: true | false | { csr: boolean }`** and can be
+narrowed again per deployment.
+
+```ts
+const config: AppConfig = { web: { csr: false } }; // web without the mobile bundle
+const config: AppConfig = { web: false }; // api only
+```
+
+- **`web: { csr: false }`** drops the CSR build phase and the `/__csr` + `?csr=true` routes. The CSR bundle is
+  what the Capacitor mobile build ships, so a web-only deployment never needs it — and an app that declares a
+  `mobile` section is refused, because `akan build-ios` copies `dist/apps/<app>/csr/<target>.html` into the
+  native project.
+- **`web: false`** is an API-only build: no base artifact, no pages or client bundles, no RSC worker
+  entrypoint, and no `public/` in the image (the web router's catch-all is its only reader). Nothing under
+  `page/` is served, including routes a lib contributed through `syncPageLibs`.
+- **There is no CSR-without-SSR option, by type.** The CSR bundle inlines the stylesheet the SSR base artifact
+  compiles, so it would ship an unstyled app — the object form therefore carries only `csr`, and SSR goes off
+  only through the whole-surface `false`.
+- **At runtime, `AKAN_SSR` and `AKAN_CSR` narrow further and never widen** — `false` or `0` turns one off, and
+  `AKAN_SSR=false` takes CSR with it for the same reason the option has no such pair. A surface the build left
+  out cannot be switched back on, and the boot log names what the process ended up serving. The generated
+  Dockerfile writes the build's own answer as the image default.
+- **A build with no web artifact boots the API instead of crashing.** `WebRouter.create` returns `null` when
+  `.akan/artifact/base-artifact.json` is absent — an api-only build, or a workspace with no `page/` at all.
+- `akan start` ignores `web` and keeps the whole dev surface: the incremental builder is also the file watcher,
+  so switching it off would take server-code HMR with it. It warns once when the config and the dev server
+  disagree.
+- The saving is mostly the RSC worker, which is a **separate process per web-serving replica**. Measured on
+  `apps/akan` at boot plus one render: 350MB across 3 processes with SSR on, 120MB across 2 with
+  `AKAN_SSR=false`, and the built image goes 86MB → 6.2MB when the artifacts are left out of it too.
+- **The generated image installs `ca-certificates` and `tzdata` and nothing else.** It used to carry the whole
+  Chromium runtime, ffmpeg, `build-essential`, `python3` and `redis` in every app's image whether or not the app
+  reached for any of them. An app that needs one declares it in `docker.preRuns` / `docker.postRuns`, which are
+  emitted around the `bun install` — that is the migration for a `puppeteer` or `ffmpeg` app.
+
+## The Process Model — Gateway And Solo
+
+A container runs one process per replica, a gateway in front of them when there is more than one, and one RSC
+worker per web-serving replica.
+
+- **One traffic replica runs in the container's only process.** `AKAN_REPLICA=0,0,1` — the default, and what
+  every environment in `infra/app/values` sets — means there is nothing to balance and nothing to fan pubsub out
+  to, so `AkanApp` starts that replica in-process rather than spawning it. Measured on `apps/akan`: 28MB less RSS
+  and twice the requests per second, because every request used to cross a unix-socket proxy hop. Declare two or
+  more and the gateway is back, spawning and proxying them.
+- **`AKAN_SOLO=false` forces the gateway** for a single replica. Like `AKAN_SSR`, the env only narrows — it
+  cannot fold a real gateway's replicas into one process. Passing `replica` to `new AkanApp(...)` also keeps the
+  gateway: code that states a topology is asking for the thing that serves it.
+- **`akan start` always runs the gateway**, whatever the replica count. It is also the dev host's builder relay,
+  its crash page, and what holds the port across a child restart.
+- **A batch-only replica (`0,1,0`) keeps the gateway too**, because a batch server never listens and the gateway
+  is then the only thing bound to answer `/_akan/app/health`.
+- **The RSC worker is never folded in.** It runs under `--conditions react-server`, which resolves the same
+  module graph differently, so it cannot share a process with the server that renders client components.
+- **A solo process answers `/_akan/app/health`, `/_akan/app/metrics` and `/_akan/bench/ping` itself**, in the
+  gateway's own shape — a `children` array with one entry — so a probe reads one contract either way. It owns the
+  rotating log file the gateway would otherwise write, in the same `runtime/logs` directory.
+- **Nothing supervises a solo process but the orchestrator**, since the gateway's crash-restart-with-backoff went
+  with it. `infra/app/templates/app.yaml` carries the liveness, readiness and startup probes that replace it.
+- **`main.ts` imports `AkanApp` from `akanjs/server/akanApp`, not the barrel.** The barrel re-exports
+  `AkanServer`, whose graph the gateway never runs; through it the process evaluated 35MB of SSR renderer and
+  SQLite driver to spawn children and relay bytes. Keep entrypoint imports at the leaf.
+
+## Logging — Records, Request Context And Live Tail
+
+Every `Logger` call builds a `LogRecord` before any text exists: `at`, `level`, OTel `sev`, `name`, `message`,
+`pid`, `replicaIdx`, `role` (`gateway` / `all` / `batch` / `rsc-worker`) and — inside a call — `traceId`,
+`endpoint` (`mutation:signScContract`, `internal:cleanupJob`, `page:/org/[orgId]`) and `origin` (`http`,
+`websocket`, `mcp`, `internal`, `page`). The console line is rendered from the record and is byte-identical to
+what it was; a sink reads `entry.record` and renders only if it touches `entry.message`.
+
+The level 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
+`no-deprecated-log-level.grit` refuses a call to it — write `.info()`. `AKAN_PUBLIC_LOG_LEVEL=log` still boots,
+normalized to `info` with one warning.
+
+- **Request context is on by default, production included.** `SignalContext.try` / `SignalContext.run` own the
+  `AsyncLocalStorage` scope for the whole call, including the 500 log, so every line of one request shares a
+  `traceId`. Internal triggers get `internal:<key>`, the RSC worker gets `page:<route>`, MCP calls are the
+  endpoint's own type with `origin: "mcp"`. `AKAN_LOG_CONTEXT=0` is the escape hatch; `AKAN_TRACE=1` is a
+  different switch that adds span and query aggregation. Measured cost: ~25ns per call.
+- **Not everything carries context, by design.** The primitive query fast path (an unauthenticated GET of a
+  primitive with no args, guards or middlewares) skips it; the schedule adaptor's own `started/finished/error`
+  lines wrap the traced handler from outside; gateway-internal lines have none. `akan logs --endpoint` says so.
+- **`Logger.addSink(sink, { minLevel })` — give a sink its floor.** A sink with none follows `AKAN_LOG_FILE_LEVEL`
+  (default `trace`), which is why a registered sink used to make every `verbose` call render (1,294ns against an
+  11ns reject). The IPC forwarder and any sink that never reads the text pass a floor and cost a record literal.
+- **The hub lives with whoever owns the surface**: the gateway when there is one, the replica itself under solo
+  (`AKAN_REPLICA=0,0,1`), the same rule as the rotating log file and `/_akan/app/*`. It keeps a ring
+  (`AKAN_LOG_BUFFER` records / `AKAN_LOG_BUFFER_MB`, default 2000 / 4), suppresses a line repeating more than 20
+  times a second into one counted line, and serves `<runtimeDir>/akan-control.sock` (`0600`, NDJSON). A child
+  forwards records only while a subscriber wants that level (`log.level` IPC), so an unwatched process sends
+  nothing; `AKAN_LOG_STREAM=1` keeps it on. The RSC worker forwards to its replica the same way.
+- **`akan logs <app>`** is the client: `--level --grep --endpoint --trace --child --role --origin --since`
+  AND together, comma lists OR, `*` is the only glob; `--replay N` first, `--follow false` for history only,
+  `--json` for NDJSON, `--runtime-dir` for a built app. Inside `akan console`, `.tail level=warn grep=payment`,
+  `.tail off`, `.trace <id>` — the console is its own `listen: false` process, so these attach to the running
+  server's socket rather than reading their own logs.
+- **The generated Dockerfile sets `AKAN_LOG_TO_FILE=0`.** A container's writable layer is ephemeral and nothing
+  collects a file from it; stdout is the collection path. A deployment that wants the files back sets
+  `AKAN_LOG_TO_FILE=1`.
+- **Never log per delivered record in anything that delivers records.** The control socket and the hub do not,
+  and a subscriber asking for everything is the test.
+
+## The Generated Image — `docker` In `akan.config.ts`
+
+**`docker` is `string | { image, preRuns, postRuns, command }`** — a whole Dockerfile, or the parts Akan
+assembles one from. There is no `content` field; the string *is* the content.
+
+```ts
+const config: AppConfig = {
+  docker: { preRuns: ["apt-get update && apt-get install -y --no-install-recommends ffmpeg"] },
+};
+const config: AppConfig = { docker: "FROM oven/bun:1-slim\n…" }; // verbatim, nothing merged in
+```
+
+- `image` and each run entry take `string | { amd64?, arm64? }`; the object form compiles to a
+  `RUN if [ "$TARGETARCH" = "<arch>" ]` guard, so a multi-arch build runs it on one leg only. `preRuns` land
+  before `bun install --production` (where a native dependency's build tools have to be), `postRuns` after it
+  and before the app files are copied.
+- **A lib declares the steps its own runtime needs**, and every app that mounts it inherits them:
+  `libs/<lib>/akan.config.ts` takes `docker: { preRuns, postRuns }` and nothing else — the base image and the
+  command belong to the app. Lib steps are emitted before the app's own, and an identical step declared twice
+  becomes one layer.
+- **The string form takes no contributions.** A Dockerfile handed over whole is used exactly as written, so a
+  lib's `preRuns` are dropped rather than spliced into a file Akan does not own. An app that needs both writes
+  the parts instead.
+- Like `externalLibs`, lib steps are collected from **every lib in the workspace**, not just this app's
+  dependency closure — narrowing that set needs the dependency scan, and this config is re-read on every file
+  change in dev. Keep a lib's steps to what its runtime genuinely requires.
+- `AkanAppConfig.docker` is the resolved declaration; `AkanAppConfig.dockerfile` is the text `akan build` writes
+  to `dist/apps/<app>/Dockerfile`.
+
+## Shipped Assets — `assets` In `akan.config.ts`
+
+`akan build` copies the whole `public/` tree into `dist`, lib assets dereferenced, and that copy is the image.
+**`assets: { pruneFonts, keepFonts }`** trims the fonts out of it that nothing reads. **Source trees are never
+touched** — an app's and a lib's own `public/` keep every file, because one shared font folder is picked over
+differently by every app that mounts it and by other repos.
+
+```ts
+const config: LibConfig = { assets: { keepFonts: ["fonts/Assistant-*.woff2"] } }; // libs/<lib>/akan.config.ts
+const config: AppConfig = { assets: { pruneFonts: false } }; // emergency valve, not the normal escape hatch
+```
+
+- **A font with `optimize` on is a build input, not a runtime asset.** `FontOptimizer` subsets it into
+  `.akan/artifact/fonts` and the emitted CSS points at `/_akan/fonts/*`, which `WebRouter` serves from the
+  artifact — so the source in `public/` is never opened again. That is the bulk of what this drops, and it
+  applies to the fonts the app *does* use, not only the ones it does not.
+- **The keep-set is derived per app, per build; there is no list of fonts to drop.** An exclude list would rot
+  the moment another app or repo started using one of them, and nobody would know to update it. A font survives
+  because ① its font declares `optimize: false`, so `FontCss.getRuntimeCss` emits the raw src; ② something
+  references its filename — anything under `public/`, the compiled stylesheet, a client/server bundle, the CSR
+  shell; or ③ a `keepFonts` glob names it.
+- **`keepFonts` belongs to the `akan.config.ts` that owns the font**, written against that lib's or app's own
+  `public/` (`"fonts/X.woff2"`, resolved to `libs/<lib>/fonts/X.woff2`). A lib shared across repos carries the
+  reason its own CSS needs a font, instead of every mounting app rediscovering it in production.
+- **A reference from a build bundle is ignored for an already-subset font.** Every route file's `fonts`
+  declaration is inlined into the pages bundle, the client chunks and the CSR shell, so a declared source is in
+  all three whether or not anything loads it. `public/` and the compiled CSS are read as authoritative.
+- **A generated manifest that lists every public asset keeps every font it names** — a service-worker precache
+  file is the usual one. That is a real reference, not a false positive, so the build reports it at `info`:
+  read the `[font-prune] kept …` line before concluding the prune does nothing.
+- Matching is by filename, including the percent-encoded spelling, so a `url()` survives however it is written.
+- The phase is `assets`, between `csr` and `compress`. An api-only build (`web: false`) copies no `public/` and
+  the phase finds nothing to do.
+

package/guidelines/transportRule/transportRule.generate.json

@@ -0,0 +1,31 @@
+{
+  "title": "Transport Rule",
+  "description": "How a call reaches an Akan signal — guards across HTTP and websocket, socket identity and cleanup, binary pubsub frames, and mutation HTTP verbs",
+  "group": "core",
+  "codegenPriority": 4,
+  "deprecated": false,
+  "scans": [
+    {
+      "type": "example",
+      "description": "Guard classes and their scope markers",
+      "path": "{apps,libs}/*/srvkit/guards.ts",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "Signal endpoints declaring guards, pubsub, and message handlers",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "sample": 4
+    }
+  ],
+  "update": {
+    "filePath": "./transportRule.instruction.md",
+    "contents": ["guards across transports", "signal body types", "binary pubsub", "mutation HTTP verbs"],
+    "rules": [
+      "Use current Akan APIs only",
+      "State the rule and the reason it exists, never restate a type signature",
+      "Say what leaks or breaks when a rule is ignored",
+      "Keep it workspace-neutral — no app or repo names"
+    ]
+  }
+}

package/guidelines/transportRule/transportRule.instruction.md

@@ -0,0 +1,60 @@
+# Transport Rule — Guards, Sockets, Binary Frames, HTTP Verbs
+
+How a call reaches a signal: what a guard may read on either transport, how a websocket carries its credential
+and its per-connection state, when a pubsub payload leaves JSON for a binary frame, and which HTTP verb a
+mutation is mounted under. `conventions` carries the invariants — this is the full contract behind them.
+
+## 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.
+- **Never read the caller's IP off the socket or the request peer — take `.with(Ip)`.** Whenever a federation
+  gateway is in front, `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 (`x-real-ip`, then the first
+  `x-forwarded-for` entry) and falls back to the peer only when nothing proxied the call — which is the answer
+  for a solo process behind an ingress that sets neither; `context.getClientIp()` is the same answer inside a
+  guard or middleware. It arrives unwrapped from
+  its `::ffff:` IPv4-mapped form, so it can address a `udp4` socket as well as identify a caller, and it is
+  `null` rather than a placeholder when genuinely unknown — a loopback-looking address for an unknown caller
+  is the failure this replaced. The gateway also forwards the client port (`x-forwarded-port`, read with
+  `context.getClientPort()`) along with host and protocol.
+- **Every socket carries a `socketId`, and only the framework mints one.** `AppWsData` assigns it at the handshake, and a `message` / `pubsub` handler reads 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 — a reconnect gets a new id and the federation gateway's own socket is a different one — so per-user state keys on the account, never on this.
+
+- **A cleanup registered with `ws.on("disconnect" | "unsubscribe", fn)` is scoped to the call that registered it.**
+  From a `pubsub` subscribe it belongs to that room — `unsubscribe` runs when the client leaves it or a credential
+  change revokes it, `disconnect` when the socket closes while still subscribed — so a room already left runs
+  neither again, and cleanup that must happen either way registers for both. From a `message` handler it belongs to
+  the socket and runs at close. A handler that throws is logged and never blocks the rest of the teardown.
+
+## Binary Pubsub
+
+- **`pubsub(Binary)` sends its payload in a websocket binary frame**, skipping the JSON `{ type: "pub" }`
+  envelope and the base64 a JSON wire would need. The client's subscribe callback receives a `Uint8Array`.
+  Nothing else is declared: the return type is the whole switch, and text and binary frames coexist on one
+  socket, so every JSON endpoint is untouched. The optimization applies only when the **whole** return is
+  `Binary` — `[Binary]`, or a `Binary` inside a model, falls back to base64.
+- **A declared `Binary` room coalesces under backpressure**: while a socket cannot keep up the room keeps only
+  its newest frame and drops the rest, which is what a telemetry or video stream wants. Declare
+  `pubsub(Binary, { backpressure: "queue" })` when the frames are a sequence a subscriber must see in full, such
+  as deltas against a base it already holds; the send buffer then grows with the slowest subscriber. Coalescing
+  is keyed by the endpoint, not carried with the frame, so this process, an IPC deliver and a Redis fan-out all
+  reach the same answer. Coalesced frames are counted in `pubsubCoalesceCount` on the replica's metrics report.
+- **A `pubsub(Any)` that happens to carry bytes is framed too, and warns once.** `Any` passes a `Buffer` through
+  untouched, so the transport sees bytes and sends them whole rather than as a number array — an undeclared
+  publisher is fixed rather than left corrupt. It is still not the contract: it queues rather than coalescing
+  (nobody declared lossy delivery for that room), and a Redis fan-out still JSON-stringifies it. Declare
+  `Binary`.
+- The federation gateway relays a binary frame unchanged, and Bun IPC carries bytes as bytes, so the only hop
+  that needed teaching was the socket itself. A cross-server (Redis) fan-out encodes it as protobuf `bytes`.
+
+## Mutation HTTP Verb
+
+- A `mutation` is `POST`. `{ method: "PATCH" | "PUT" | "DELETE" }` moves it, and one path may carry several verbs
+  — a `query` GET and a `mutation` POST on the same custom `path` are mounted side by side. Two endpoints claiming
+  the same path **and** verb fail the boot rather than silently shadowing one another.
+- Reach for it only when a foreign wire protocol forces the verb (a client you cannot change that sends
+  `PATCH /rest/v1/<table>`). Akan's own `fetch.*` client, the OpenAPI document, and the API explorer all follow
+  whatever is declared, so nothing needs restating per caller.
+