@akanjs/cli 3.0.0-beta.17 → 3.0.0-beta.19

package/guidelines/agentRule/agentRule.instruction.md

@@ -96,15 +96,21 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
   nothing about, and it stays text-only until `option.setLlm({ accepts })` says otherwise — handing bytes to a
   model that cannot decode them kills the whole turn on a 400, where text-only degrades them to a note the model
   can repeat back.
-- **A refusal is one key, `agent.error.llmRequestFailed`, and it names the host.** The provider's own sentence
-  rides in `reason` and the hostname in `provider`, so an adaptor an app wrote reports through the same
-  translated channel the shipped ones do rather than needing a key in the framework's dictionary it cannot
-  add.
+- **A refusal is `agent.error.llmRequestFailed`, and it names the host** — unless the prompt did not fit. The
+  provider's own sentence rides in `reason` and the hostname in `provider`. `LlmOverflow.refusal(host, status,
+  reason)` builds it, and reads the one refusal a chat can undo — a prompt past the window, recognized from each
+  provider's own sentence — as `agent.error.contextOverflow` with the `limit` it named, which the relay flags so
+  the chat compacts and asks again. An adaptor an app wrote throws through the same function, so its refusals
+  translate and recover the way the shipped ones do without a key in the framework's dictionary it cannot add.
 - **`accepts` is answered per model, through `option.setLlm({ accepts })`.** An adaptor answers for an API and one
   API serves models that differ, so the override rides beside the `model` it is a fact about. It is not a table
   the framework keeps: a table is a claim about models that ship after it, and getting this wrong is the worst
   failure available — a provider handed bytes it cannot decode either refuses the turn or accepts it having seen
   nothing, and the model then answers confidently about a file it never read.
+- **`contextWindow` is declared the same way: `option.setLlm({ contextWindow })`.** Every turn relays it with the
+  answer ceiling the adaptor actually sends (`LlmAdaptor.limits` — `AnthropicLlm` always sends one, `OpenaiLlm`
+  none), and the chat guards its window with it. It is not a table either; a model id is retired or renamed long
+  before a table notices.
 - **An adaptor answers `null` for "not configured" and *throws* for a refusal it can explain.** The two are
   different things to be told: collapsing both into `null`, the way the adapter convention otherwise reads, left a
   user reading `llmUnavailable` — "no model is configured" — about a conversation that had merely outgrown the
@@ -539,18 +545,29 @@ apps and libs never import it directly (`no-import-external-library`) — everyt
 - **A long conversation summarizes itself, because nothing else is keeping it inside the model's window.** The
   loop runs in the browser and the relay holds no session, so an uncompacted chat grows until the provider
   refuses the whole request — a refusal, never a shorter answer, which is why compaction runs *before* the turn
-  that would have overflowed rather than as a recovery after it. Past `compact.at` estimated tokens (four
-  characters to a token, over the JSON the turn posts; 24k by default, well under the smallest window a provider
-  is likely to have, since the tools and the screen context ride on top of it and neither compacts) the history above the last `keep` messages
-  becomes one message standing in for it, flagged `summary` on the wire — `<Agent.Chat compact={{ at, keep }} />`
-  tunes it per provider and `{ at: 0 }` turns it off, and `/compact` does the same on demand keeping nothing.
+  that would have overflowed. **Two triggers, each before every assistant turn.** `compact.at` is a ceiling on
+  cost: past that many estimated transcript tokens (four characters to a token, over the JSON the turn posts —
+  except an inlined picture, counted at the ~1,600 tokens a provider bills for its pixels rather than its base64;
+  24k by default) the history compacts, because the relay resends the whole transcript every turn and the app
+  pays for each one. The **window guard** compacts once the prompt nears the window the server reports —
+  `window − answer ceiling (8,192 when unreported) − compact.buffer (13,000, the margin Claude Code leaves)` —
+  measured by the provider's own count of the last turn (`done.usage`, kept on that assistant message) plus the
+  four-character estimate for what arrived since, so a Korean transcript the character rule reads as small is
+  still caught. The window comes from `option.setLlm({ contextWindow })` or from the first refusal that names it;
+  with neither, only the ceiling runs. **A refusal for length is answered once**: a relay flags it `overflow` on
+  the wire, and the session compacts and sends the same turn again, and a second refusal in the same send fails
+  with `agent.error.contextOverflow`. Either way the history above the last `keep` messages
+  becomes one message standing in for it, flagged `summary` on the wire — `<Agent.Chat compact={{ at, keep, buffer }} />`
+  tunes it, `{ at: Infinity }` leaves only the window guard, `{ at: 0 }` turns off the ceiling, the guard and the recovery alike, and `/compact` does
+  the same on demand keeping nothing. The header draws the estimate against whichever trigger is nearer.
   **The cut never lands on a `tool` message**: the kept half may not open with a result whose call was summarized
   away, a shape every provider dialect rejects. A user message is preferred where the tail holds one — everything
   above it is settled — but one assistant turn that ran ten tools has none, and that is the transcript that
   outgrows the window, so a cut there opens on the assistant message instead. The summarizing
   turn carries no tools and no screen context — it summarizes the conversation, it does not act on it — and it is
   fed a *bounded* digest rather than the transcript itself, since the transcript being summarized is the one that
-  no longer fits. A summary that cannot be produced leaves the transcript alone, the turn goes out as it would
+  no longer fits. The previous summary is the exception: it rides the digest whole, under its own label and outside
+  the bound, because it is the only record of what was compacted before it. A summary that cannot be produced leaves the transcript alone, the turn goes out as it would
   have, and the next one asks again — a summarizer that was momentarily unreachable says nothing about whether
   this transcript can shrink. One that *landed* and shrank nothing does, so that one is not retried until another
   threshold's worth has been added. On the

package/guidelines/conventions/conventions.instruction.md

@@ -28,7 +28,7 @@ you fetch on demand — `get_guideline` with the name, or `akan guideline show <
 | name | covers |
 |---|---|
 | `ssrRule` | server-share targets, the `akan.ssr.*` warnings, the client-boundary playbook |
-| `runtimeRule` | `web` / `csr` surfaces, gateway vs solo processes, logging, the generated image, shipped assets |
+| `runtimeRule` | `web` / `csr` surfaces, gateway vs solo processes, logging, the generated image, shipped assets, database modes |
 | `queryRule` | slices and hydration, the generated filter methods, full-text search, cascade removal |
 | `transportRule` | guards across HTTP and websocket, socket identity and cleanup, binary pubsub, mutation verbs |
 | `mcpRule` | MCP configuration, wire behaviour, resource URIs, OAuth metadata, protocol revisions |
@@ -273,8 +273,10 @@ are, because those are the ones the server could have done.
    SEO snapshots, prerendering and pre-hydration E2E read, so await what the page needs immediately and stream
    the rest. `xListInY` / `xInsightInY` hold hydrated model instances that React Flight refuses as client props:
    consume them in a server component, never as a `Zone` prop.
-6. **Use named `ReactNode` slots, not just `children`** — `Layout.Navbar` takes `title`, `back`, `left`, `right`,
-   and `children`, so a client shell composes server content in five places instead of absorbing it.
+6. **Use named `ReactNode` slots, not just `children`** — a client shell that takes one slot per region lets a
+   server component supply each of them, instead of absorbing the whole subtree into the bundle. `Layout.Navbar`
+   declares `title` / `left` / `right` alongside `back` and `children`, but renders only the last two today, so
+   copy the shape rather than the component.
 7. **Let the server do the derived work.** Display and predicate logic belongs on `Light<Model>`; enum→class
    lookups belong in a module-scope `as const` map.
 8. **Gate auth on the server** — `getSelf({ unauthorize: "/signin" })` in `_layout.tsx`, before any HTML is sent.
@@ -335,6 +337,14 @@ Full contract: `get_guideline` with `runtimeRule`, or `akan guideline show runti
 - **`assets: { pruneFonts, keepFonts }`** trims from the `dist` copy of `public/` the fonts nothing reads; source
   trees are never touched. A font with `optimize` on is a build input, not a runtime asset. `keepFonts` belongs to
   the `akan.config.ts` that owns the font, written against that scope's own `public/`.
+- **Database modes are `database: { modes: [...] }`** — `single` (SQLite + Solid), `multiple` (one SQLite file on
+  a host volume + Redis), `cluster` (Postgres + Redis). The build carries the drivers of every declared mode and a
+  deployment picks one with `AKAN_DATABASE_MODE` — a declared one, named whenever the build declares several.
+  Where the data lives (`POSTGRES_URL`, `REDIS_URI`, `SQLITE_DATABASE_PATH`) is the deployment's env, ahead of
+  `env.server.ts`. `q.raw` is written in the dialect's own SQL, so an app running in two modes avoids it.
+- **Backups run through the image's own `main.js`**: `bun main.js ops snapshot` / `ops restore` (offline), and
+  `/_akan/ops/*` for a control plane, mounted only when `AKAN_OPS_PUBLIC_KEY` is set and authenticated by a short
+  EdDSA token that key verifies. `GET /_akan/app/info` is public. `operationMode` gates none of it.
 
 ## React Components And Styling (`**/*.tsx`)
 
@@ -357,7 +367,7 @@ Full contract: `get_guideline` with `runtimeRule`, or `akan guideline show runti
   nothing — they covered five control types, keyed on the translated label, and restored over server data.
 - Static class strings stay plain strings. Reach for `cn` only for a conditional or to merge an incoming `className`, and merge the caller last: `cn("base classes", cond && "extra", className)`. `cn` comes from `akanjs/client` (token-aware tailwind-merge) and is the only class-combining function — no `clsx` (removed), no raw `twMerge` imports, no object syntax (`{ x: cond }` → `cond && "x"`).
 - Multi-slot components take extra named props (`wrapperClassName`, `bodyClassName`), never a `classNames` object.
-- Hoist enum→class lookups to a module-scope `as const` map typed `{ [key in cnst.XStatus["value"]]: string }`. Do not use `Record<...>`. Escalate the map to `webkit/` when a second module needs it.
+- Hoist enum→class lookups to a module-scope `as const` map typed `{ [key in cnst.XStatus["value"]]: string }`. Do not use `Record<...>`. When a second module needs it, the classes become a variant axis of a recipe in `ui/Recipe/`; only a map from the enum to another recipe's variant name (`BadgeVariants["variant"]`) moves to `webkit/`.
 - Use `<Link>` from `akanjs/ui` for internal navigation; `<a>` only for `mailto:` and external links.
 
 ## Naming And Language
@@ -421,8 +431,11 @@ stores need none, because state and CRUD actions are generated. The body is thre
 `this.setX(...)` → toast. The optimistic shape is mutate the client model, `void fetch.*`, then commit. Use
 `this.pick(...)` when the value must exist, `this.get()` when it may not, and `this.set({...})` to write. Mutate lists
 through the collection API (`this.set({ xList: xList.set(x).save() })`), not array spread. **An action returns
-nothing** (`no-return-in-store-action.grit`). **Never `import type { RootStore } from "../st"`** — it crashes
-`akan build` with a Bun SSR segfault.
+nothing** (`no-return-in-store-action.grit`). **Reach another store through `this`:**
+`import type { RootStore } from "../st"`, then `(this as unknown as RootStore).logout()` to call its action or
+`(this as unknown as RootStore).set({ … })` / `.get()` to write or read its state. Every store is mixed into one root
+at runtime, so the cast only tells the type what `this` already is. Keep it `import type` — `st.ts` imports every
+store, so a value import is a cycle.
 
 **`<model>.dictionary.ts`** — fixed chain, with empty stages still written:
 `.of() → .model() → .insight() → .query() → .sort() → .enum() → .slice() → .endpoint() → .error() → .translate()`.
@@ -475,13 +488,14 @@ Full contract — credential handshake, room revalidation, socket cleanup scopin
   never bounded. **Losing the race does not cancel the work**: the handler runs to completion with nobody
   holding its result, so a deadline is an answer to the caller, not an undo.
 - **A cached answer is the endpoint's `{ cache: <ms> }`, and only a `query` taking no internal argument may have
-  one.** The `Cache` middleware is registered by default and stands aside for every endpoint that declares
-  nothing. Internal arguments are how a call learns who is asking (`.with(Self)`), so an endpoint that has them
-  answers per caller and one shared entry would be one caller's answer handed to the next — that endpoint and
-  every `mutation` are named in the log and left uncached. Guards run on every hit; what is cached is the
-  handler's result, so `resolveReturn` still masks fields and resolves relations per call; a cache backend that
-  is down is warned about and the call runs uncached. The default chain is `Logging → Timeout → Cache → handler`,
-  and there is no `Retry` middleware.
+  one.** It is a step of the call, not a middleware, and stands aside for every endpoint that declares nothing.
+  Internal arguments are how a call learns who is asking (`.with(Self)`), so an endpoint that has them answers
+  per caller and one shared entry would be one caller's answer handed to the next — that endpoint and every
+  `mutation` are named in the log and left uncached. The lookup runs after the guards, so a hit reaches only a
+  caller they admitted; what is cached is the handler's result, so `resolveReturn` still masks fields and resolves
+  relations per call; a cache backend that is down is warned about and the call runs uncached. The default
+  middleware chain is `Logging → Timeout → <lib middlewares>`, then guards → internal arguments → cache →
+  handler, and there is no `Retry` middleware.
 
 ### Authorization Defaults
 
@@ -548,8 +562,11 @@ Full contract — filter-arg `ref` pickers, `getQueryMeta` summary counters, `la
   first "more". `isCumulativeOf<Model>` is the mode.
 - **"Is there more" is `hasMoreOf<Model>`, never `count > page * limit`.** It comes from the length of the batch
   the server returned, so it survives `{ insight: false }` and cannot drift from a count a live event moved.
-- **Hydrated vs raw:** server queries return hydrated `cnst.<Model>` instances (with `set`/`save`/`refresh`);
-  client fetch results are raw `GetStateObject` plain data, functions stripped.
+- **Hydrated vs raw:** server queries return hydrated `cnst.<Model>` instances (with `set`/`save`/`refresh`),
+  and so do client fetch results — `FetchClient` parses every return with `crystalize` defaulting to **true**
+  (`pkgs/akanjs/fetch/client/fetchClient.ts`). The raw `GetStateObject` shape is what the `<ref>Obj` /
+  `<ref>ObjList` / `<ref>ObjInsight` handles carry, because those pass `crystalize: false` on purpose so the
+  value can cross the RSC boundary as a client prop.
 - Every filter generates fourteen methods: `list` · `listIds` · `find` · `findId` · `pick` · `pickId` · `exists` ·
   `count` · `insight` · `query` · **`remove`** · **`removeOne`** · **`update`** · **`updateOne`**. The last four
   are query-level writes — one atomic UPDATE, **no hooks**, and therefore no `_postRemove` and no cascade. Use
@@ -587,7 +604,7 @@ Full contract — relevance ordering, `columns` / `weights`: `get_guideline` wit
 - Injected dependencies resolve by field-name convention: a field named `<refName>Service` resolves to the service registered under `<refName>`, and `<refName>Signal` likewise (`pkgs/akanjs/service/injectInfo.ts`).
 - The `Service`/`Signal` suffix is required — the injector strips it to derive the registry lookup key. Name the field after the target refName plus the suffix, not arbitrarily.
 - Preference order inside a service: `service<srv.XService>()` for another module's service · `plug(AdapterClass)` or `plug(StorageAdaptorRole)` for an adapter · `use<T>()` only to reach an `option.ts`-registered legacy singleton · `env(...)` for config.
-- **`memory(...)` takes a scalar or model class, not only a primitive** — `memory(Map, { of: CallStateInput })` serializes through the constant and travels as JSON text, so the Redis and sqlite-backed caches round-trip the same declaration. Never hand-encode JSON into a `String` memory.
+- **`memory(...)` takes a scalar or model class, not only a primitive** — `memory(Map, { of: CallStateInput })` serializes through the constant and travels as JSON text, so the Redis and sqlite-backed caches round-trip the same declaration. Never hand-encode JSON into a `String` memory. A memory is scoped to the service or adaptor that declares it; `ttl` (milliseconds) sets how long each write lives unless the `set` call names its own `expireAt`, and a `Map` entry expires on its own.
 
 ### Adapters — `adapt()` And `plug()`
 
@@ -663,9 +680,11 @@ it.
   names itself as the issuer, so `/mcp` demands a bearer token, verifies its signature, and refuses one carrying no
   `aud`. A token is the app's own access JWT plus `aud`/`iss`/`client_id`, so `AccountMiddleware` and the guards
   judge it unchanged; there is no scope. Per-app knobs live in `env.server.*` under `oauth` (`consentPath` and
-  `signinPath` with the basePath, `clients`, `dynamicRegistration`, `allowedRedirectSchemes`, `clientIdMetadata`,
-  `enabled`). `/mcp` reads the `Authorization` header only — a cookie is dropped at the door — and `JWT_SECRET` is
-  mandatory outside `local`, because the derived fallback is forgeable from three public names. A grant is revoked
+  `signinPath` with the basePath, `clients`, `dynamicRegistration`, `allowedRedirectSchemes`, `accessTokenSeconds`,
+  `clientIdMetadata`, `enabled`, plus `issuer` / `resource` — set those when a tunnel or an edge makes the derived
+  origin wrong, because an MCP client compares the issuer byte for byte). `/mcp` reads the `Authorization` header only — a cookie is dropped at the door — and `JWT_SECRET` (or
+  `security.jwtSecret`) is mandatory whenever `operationMode` is not `local`, because the derived fallback is
+  forgeable from three public names; `AKAN_ALLOW_DERIVED_JWT_SECRET=1` accepts that risk explicitly. A grant is revoked
   whole — `POST /oauth/revoke` (RFC 7009) by the client, `fetch.revokeOAuthConnection(sessionId)` by the account's
   owner, `fetch.listOAuthConnections()` to see them — and a revoked access token is refused at its next call.
 - **A person may, a model may not.** An agent's token names its `client_id` and `aud`; a browser session has
@@ -782,7 +801,8 @@ Full contract — the trigger-maintained mirror, tokenizer changes, `AKAN_SEARCH
   backstop, including for a `text` field *underneath* one of those. Do not work around either.
 - The role works on a relation (`image: field(File, { text: "thumb" })`) and on an array; an array of objects
   indexes by leaf key. A field inside a `Map` indexes nothing — there is no fixed path to extract it from.
-- Search runs on sqlite/libsql only. `q.search()` against Postgres throws, loudly, rather than returning every row.
+- Search runs in every database mode — fts5 on SQLite/libSQL, a weighted `tsvector` (`pg_trgm` for `trigram`) on
+  Postgres. The same text matches the same documents; only the order may differ on Postgres.
 
 ### Image & File Fields
 
@@ -831,10 +851,11 @@ shape, so `cascade` never means "related" — it means one of exactly these:
 - Dynamic segments use `[id]`; route groups use directories like `(user)`, `(public)`, `(tab)`, or `(detail)`.
 - **A route file exports one thing**: `export default page()…render(…)` for a page, `layout()…render(…)` for a
   `_layout.tsx`, `rootLayout()…render(…)` for the app's (or a basePath's) root `_layout.tsx`. Every route setting
-  is a stage of the chain — `.param()`, `.search()`, `.config()`, `.head()` / `.metadata()`, `.loading()`;
-  `.notFound()` / `.error()` on a layout; `.fonts()` / `.theme()` / `.manifest()` / `.reconnect()` / `.wsConnect()`
-  / `.layoutStyle()` / `.gaTrackingId()` on the root layout; `.prompt()` on a page. A named export beside the chain,
-  or `page()` in a `_layout.tsx`, fails the build.
+  is a stage of the chain — `.param()`, `.search()`, `.config()`, `.head()`, `.loading()`; `.notFound()` /
+  `.error()` on a layout; `.fonts()` / `.theme()` / `.manifest()` / `.reconnect()` / `.wsConnect()` /
+  `.layoutStyle()` on the root layout; `.prompt()` on a page. A named export beside the chain, or `page()` in a
+  `_layout.tsx`, fails the build. `.head()` takes JSX — `<title>`, `<meta>`, `<link>` — or a function of the
+  route's args returning it; there is no metadata object, and analytics is the app's own script, not a stage.
 - **A page names every `[x]` segment of its path with `.param("x", Type)`** and reads a query key only through
   `.search("k", Type)`. Values arrive typed — `ID`/`String` → string, `Int`/`Float` → number, `Boolean`, `Date` →
   Dayjs, an `enumOf` class → its union, `[T]` → array — a path value the type refuses answers not-found, and a
@@ -906,10 +927,13 @@ export default page()
 | `common/` | pure, isomorphic, zero-dependency; may import only sibling `common/*` and `akanjs/base`. Cannot import `Err`, so keep throwing code out of it. | camelCase file, filename equals the single export |
 | `webkit/` | touches `window` / `navigator` / Capacitor, or is a React hook | `use<Thing>.tsx` — `.tsx` even with no JSX |
 | `srvkit/` | touches `node:*`, `Bun`, `process.env`, a secret, or a server SDK | camelCase file, PascalCase class |
-| `ui/` | renders JSX and is not bound to one model | PascalCase component, camelCase sidecar (`swipeCard.util.ts`) |
+| `ui/` | renders JSX, or defines a look (a recipe in `Recipe/`, a lib's `tokens.css`), and is not bound to one model | PascalCase component, camelCase sidecar (`swipeCard.util.ts`), `Recipe/<name>.ts` |
 | `plugin/` | build- or CLI-time `AkanPlugin` | `<name>.plugin.ts`, registered in `akan.config.ts` |
 
 - Hooks return a named object of async closures, never a tuple.
+- `ui/` is the presentation layer — markup and the looks it is built from — so a recipe lives there although it is
+  neither a component nor a hook. Not `webkit/`: its hooks are `"use client"`, the opposite signal for a function
+  server components call. Not `common/`: it cannot import `akanjs/ui`, where `recipe` / `tv` come from.
 - `libs/<lib>/ui/tokens.css` is the one CSS file a lib owns: plain `:root` custom properties for colors that must **not** follow the theme (a vendor brand color, a fixed surface). Every app whose pages reach that lib compiles it automatically, ahead of the app's own stylesheets, so nothing is imported by hand and no app can forget it. Reference them as `bg-[var(--kakao)]`; `@theme` extensions stay in the app stylesheet, because the color vocabulary is closed per stylesheet. Theme-following colors are the app's, not the lib's.
 - A layer-root `index.ts` is generated, but a `ui/<Folder>/index.tsx` that builds a namespace is hand-written source. The distinguishing test is that a generated barrel contains nothing but `export * from "./X";` lines.
 - `ui/<Folder>/index_.tsx` (trailing underscore) is the `"use client"` + `lazy()` boundary, with a server-safe `index.tsx` beside it. Collapsing the pair into one file breaks RSC.
@@ -922,12 +946,15 @@ when two shapes disagree.
 - `children: any` — newer files use `children: ReactNode`.
 - Hard-coded API keys or secrets in source; they belong in `option.ts` or env.
 - Large blocks of commented-out code left in place.
-- Cross-store writes through a `RootStore` cast — it collides with the Bun SSR-bundler segfault.
 - Stale `// TODO: Implement …` comments above implemented methods.
 - `{cond && <X/>}` in JSX, hard-coded Korean bypassing `l()`, and `window.alert(...)` for user feedback.
 - Bare `/* eslint-disable */` blocks — use `// biome-ignore lint/<rule>: <why>`.
 - Raw palette grays such as `text-gray-400` instead of the semantic tokens (`text-foreground/70`).
 
+A store calling `(this as unknown as RootStore).<action>()` or `.set({ … })` over
+`import type { RootStore } from "../st"` is **not** one of these — it is the sanctioned way to reach another store's
+actions and state (see `<model>.store.ts` above).
+
 ## Secrets And Env Safety (`.env`, `infra/**`, `*secret*`, `*credential*`)
 
 - Never print, summarize, commit, or expose real secret values, credentials, tokens, private keys, or `.env` contents.

package/guidelines/queryRule/queryRule.instruction.md

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

package/guidelines/runtimeRule/runtimeRule.instruction.md

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

package/guidelines/ssrRule/ssrRule.instruction.md

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

package/guidelines/transportRule/transportRule.instruction.md

@@ -58,23 +58,25 @@ mutation is mounted under. `conventions` carries the invariants — this is the
 
 ## Cached Answers
 
-- **`{ cache: <ms> }` in an endpoint's signal option is the whole cache surface.** The `Cache` middleware is
-  registered by default and stands aside unless an endpoint declares one — it used to be opt-in and to ignore the
-  declared value for a hard-coded 60 seconds, which is the same shape the `timeout` bug had.
+- **`{ cache: <ms> }` in an endpoint's signal option is the whole cache surface.** The lookup is a step of every
+  call and stands aside unless an endpoint declares one.
 - **Only a `query` that takes no internal argument may carry one.** The handler's inputs are its declared
   arguments plus its internal ones, so an endpoint with none of the latter answers the same thing to everyone who
   may read it — which is the only answer a shared entry can hold. An endpoint that takes `.with(Self)` answers
   per caller, and one entry would be one caller's answer handed to the next; that endpoint and every `mutation`
   are named once in the log and left uncached rather than silently ignored.
-- **The guards run on every hit.** A cache hit skips `next()`, and `next()` is what runs them, so the middleware
-  calls `context.checkGuards()` itself before handing the entry over. Shared is not public.
-- **The entry is the handler's result, not the response.** The middleware wraps execution, so `resolveReturn`
+- **The guards run before every hit.** The lookup sits after the guards and the internal arguments, inside the
+  call, so every middleware — the account resolution a lib registers among them — has already run and a hit
+  reaches only a caller the guards admitted. It used to be a middleware ahead of the lib's, and a guard reading
+  the account refused a signed-in caller on every hit. Shared is not public.
+- **The entry is the handler's result, not the response.** The lookup wraps the handler only, so `resolveReturn`
   still runs per call on the cached value — field masking, `hidden`/`secret` stripping and relation resolution are
   never cached, and a relation still costs its own load. The cache saves the handler, not the serialization.
 - **A cache backend that is down does not take the endpoint down.** A failed read is warned and the call runs
   uncached; a failed write is warned and dropped.
-- The default middleware chain is `Logging → Timeout → Cache → handler`: a hung cache backend is bounded by the
-  same deadline as the handler it stands in for. **`Retry` was removed** — an automatic re-run of an endpoint
+- The default middleware chain is `Logging → Timeout → <lib middlewares>`, and the call inside it runs guards →
+  internal arguments → cache → handler: a hung cache backend is bounded by the same deadline as the handler it
+  stands in for. **`Retry` was removed** — an automatic re-run of an endpoint
   whose failure it cannot classify replays whatever the first attempt already did.
 
 ## Binary Pubsub

package/guidelines/workspaceRecipes/workspaceRecipes.instruction.md

@@ -376,15 +376,16 @@ export default page()
 |---|---|
 | `interface PageProps { params }` + `[x]` folder | `.param("x", ID \| String \| Int \| …)` — one per `[x]` segment, every one of them, in path order |
 | `searchParams.k` | `.search("k", Type)`; `[Type]` for a repeated key; the value arrives typed and optional |
-| `params.lang` | `lang` — on every route's `.render()`, `.head()`, `.metadata()` and `.loading()` with no stage; `.param("lang")` is refused |
+| `params.lang` | `lang` — on every route's `.render()`, `.head()` and `.loading()` with no stage; `.param("lang")` is refused |
 | `export const pageConfig = {…}` | `.config({…})` — `devOnly` stays a literal |
 | `export const head = <…/>` / `generateHead({ params })` | `.head(<…/>)` / `.head(({ x }) => <…/>)` |
-| `export const metadata` / `generateMetadata` | `.metadata({…})` / `.metadata((args) => …)` |
+| `export const metadata` / `generateMetadata` | `.head(<><title>…</title><meta name="description" content="…" /></>)` — there is no object form |
 | `export function Loading()` | `.loading((args) => …)` |
 | `export default async function Page({ params, searchParams })` | `.render(async ({ x, k }) => { …same body… })` — `async` only if it awaits |
 | `_layout.tsx`: `export default function Layout({ children })` | `layout().render(({ children }) => …)` |
 | `export function NotFound` / `export function Error` | `.notFound(fn)` / `.error(fn)` on `layout()` |
-| root `_layout.tsx`: `fonts`, `theme`, `manifest`, `reconnect`, `wsConnect`, `layoutStyle`, `gaTrackingId` | `rootLayout().fonts([…]).theme("dark").manifest({…}).reconnect(false).wsConnect(false).layoutStyle("web").gaTrackingId("G-…")` |
+| root `_layout.tsx`: `fonts`, `theme`, `manifest`, `reconnect`, `wsConnect`, `layoutStyle` | `rootLayout().fonts([…]).theme("dark").manifest({…}).reconnect(false).wsConnect(false).layoutStyle("web")` |
+| root `_layout.tsx`: `gaTrackingId` | none — render the app's own `"use client"` analytics component from the root layout's `.render()` |
 | `prompt()` on `endpoint()` (removed) | `.prompt(name, description)` on the page that shows the same screen |
 
 Rules the loader and `akan sync` enforce: a chain module has no other export; `page()` belongs in a page file and

package/incrementalBuilder.proc.js

@@ -3,7 +3,7 @@ import {
   CodegenLock,
   WorkspaceExecutor,
   AppExecutor
-} from "./index-p4p9t45x.js";
+} from "./index-crmeqnmf.js";
 import"./index-q0y2jq9j.js";
 import"./index-6wwzs1bc.js";
 import {
@@ -12,7 +12,7 @@ import {
   AutoImportSync,
   DevChangePlanner,
   DevGeneratedIndexSync
-} from "./index-w8kmx1b6.js";
+} from "./index-89hy31kf.js";
 import {
   HmrWatcher,
   WatchRootResolver
@@ -173,6 +173,7 @@ class IncrementalBuilder {
         app: this.#app,
         routeId: msg.routeId,
         seeds: msg.seeds,
+        graphSeeds: msg.graphSeeds,
         artifact: this.#artifact,
         knownEntries: new Set(msg.knownEntries),
         discovery: this.#discovery

package/{index-4n4821gp.js → index-10dkrrww.js}

@@ -1,16 +1,16 @@
 // @bun
 import {
   jsonText
-} from "./index-qhtj9y6j.js";
+} from "./index-2446k7b4.js";
 import {
   akanMcpInstallTargets
-} from "./index-v17gj504.js";
+} from "./index-18zybgkc.js";
 import {
   script
-} from "./index-6na0sd2b.js";
+} from "./index-qdgzsnhg.js";
 import {
   ContextRunner2
-} from "./index-g9zghs4h.js";
+} from "./index-3jrp517k.js";
 
 // pkgs/@akanjs/cli/context/context.script.ts
 import { Logger } from "akanjs/common";

package/{index-bzakk0c2.js → index-14zrtgfa.js}

@@ -249,7 +249,7 @@ class CodeTuiCommands2 {
   static all = [
     { name: "help", desc: "list these commands and the keys" },
     { name: "tools", desc: "what this session can call" },
-    { name: "model", desc: "switch model", arg: "<provider>/<id>" },
+    { name: "model", desc: "switch model, or list what is available", arg: "[<provider>/<id>]" },
     { name: "effort", desc: "how hard the model thinks before it answers", arg: "<level>" },
     { name: "thinking", desc: "show the model's reasoning, or fold it away again" },
     { name: "compact", desc: "summarise the conversation to free the window", arg: "[notes]" },
@@ -258,7 +258,7 @@ class CodeTuiCommands2 {
     { name: "name", desc: "name this session", arg: "<text>" },
     { name: "fork", desc: "continue this conversation twice; the copy takes over here", arg: "[name]" },
     { name: "agents", desc: "what a sub-agent may be, and what one may spend" },
-    { name: "mcp", desc: "the MCP servers this session reached", arg: "[add|remove|reload]" },
+    { name: "mcp", desc: "the MCP servers this session reached", arg: "[add|remove|login|reload]" },
     { name: "peers", desc: "the other akan code sessions running here" },
     { name: "msg", desc: "hand a message to another session", arg: "<peer> <text>" },
     { name: "quit", desc: "leave the session" }
@@ -292,7 +292,7 @@ class CodeTuiCommands2 {
       "",
       "Images: cmd+v attaches what is on the clipboard \xB7 ^v does too, without the terminal in the way",
       "",
-      'shift+enter needs a terminal that reports it \u2014 in VS Code bind it to send "\\u001b\\r".'
+      'shift+enter needs a terminal that reports it \u2014 in VS Code bind it to send "\\\\u001b\\r".'
     ].join(`
 `);
   }
@@ -335,6 +335,8 @@ class CodeTuiEditor2 {
     this.set(this.#text.slice(0, this.#caret) + clean + this.#text.slice(this.#caret), this.#caret + clean.length);
   }
   newline() {
+    if (this.#text.slice(0, this.#caret).endsWith("\\"))
+      this.set(this.#text.slice(0, this.#caret - 1) + this.#text.slice(this.#caret), this.#caret - 1);
     this.insert(`
 `);
   }

package/{index-v17gj504.js → index-18zybgkc.js}

@@ -7,7 +7,7 @@ import {
   isScannedRootEntry,
   AppExecutor,
   LibExecutor
-} from "./index-p4p9t45x.js";
+} from "./index-crmeqnmf.js";
 import {
   FileSys
 } from "./index-q0y2jq9j.js";
@@ -19,7 +19,7 @@ import {
 import {
   workflowRunArtifactPath,
   workflowSyncDir
-} from "./index-qhtj9y6j.js";
+} from "./index-2446k7b4.js";
 
 // pkgs/@akanjs/devkit/akanContext.ts
 import { readdir } from "fs/promises";

package/{index-qh7brn20.js → index-22xtgmhn.js}

@@ -2,7 +2,7 @@
 import {
   runner,
   script
-} from "./index-6na0sd2b.js";
+} from "./index-qdgzsnhg.js";
 
 // pkgs/@akanjs/cli/page/page.runner.ts
 class PageRunner extends runner("page") {
@@ -10,7 +10,11 @@ class PageRunner extends runner("page") {
     await app.applyTemplate({
       basePath: basePath ?? `page/(${app.name})/(public)/${module.name}`,
       template: single ? "crudSinglePage" : "crudPages",
-      dict: { model: module.name, appName: module.sys.name }
+      dict: {
+        model: module.name,
+        appName: module.sys.name,
+        clientPath: `@${module.sys.type}s/${module.sys.name}/client`
+      }
     });
   }
 }