@akanjs/cli 3.0.0-beta.3 → 3.0.0-beta.31

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, native apps and a desktop app's server, 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 |
@@ -57,8 +57,9 @@ back.
   `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 tests, `*.constant.ts`, `common/**`, and `env/**`
-  — the last two 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/**`, `env/**`, and
+  a root `native/` folder — `common/` and `env/` have no legal `Err` import path, so keep throwing code out of them,
+  and a native plugin throws `AkanNativeError`, the error its bridge carries back to the page.
 - **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 in a lib's
@@ -76,6 +77,19 @@ back.
   `*.constant.ts`, `*.store.ts`, and the five module component suffixes (`no-bang-comment-in-client.grit`). Bun
   classifies `//!` and `/*!` as legal comments and keeps them through minification, so the note ships to every
   visitor. Use `// FIXME:` there; `//!` stays legal in server, `srvkit/`, and CLI files.
+- **Never touch `document.cookie`, `localStorage` or `sessionStorage` in app or lib code** (`no-document-cookie.grit`,
+  `no-web-storage.grit`). A native shell serves the page from `app://localhost` on iOS, macOS and Linux, which keeps
+  no cookies: `document.cookie` reads `""` and a write is dropped, so the value exists in the browser and vanishes in
+  the app. Web Storage does work in the shells, but it bypasses the store akanjs picks per platform (the shell's
+  Preferences in an app) and throws during SSR. Use `getCookie` / `setCookie` / `removeCookie`, `storage`, and
+  `secretStorage` for tokens and credentials, all from `akanjs/client`.
+- **Browser APIs an app WebView lacks live in `webkit/`** (`no-web-only-api-outside-webkit.grit`, a warning):
+  `navigator.share` / `canShare` (Android's WebView has none), `navigator.serviceWorker` and
+  `Notification.requestPermission` / `.permission` (no app page has them), `navigator.geolocation` (use
+  `useGeoLocation` from `akanjs/webkit`) and `navigator.vibrate` (iOS has none; use `haptics`). They are legal on the
+  web, so the rule does not ban them: it keeps them in a `webkit/` hook that branches on `isNativeApp()` from
+  `akanjs/client/native`, which is where the app side goes too. A root `native/` folder is out of its scope: a
+  plugin's web part is where those APIs belong.
 - **Never return a value from a store action** (`no-return-in-store-action.grit`). Every method of a `store(...)`
   class dispatches through `st.do.<action>()`, typed `void` / `Promise<void>`, so the value is unreachable — write
   it into state with `this.set({ ... })`. A bare `return;` guard, a `return` inside a nested callback, a getter,
@@ -216,6 +230,8 @@ Do not narrate code. Do document the thing the code cannot say. Both halves are
 ## Client / Server Boundaries (`apps/**`, `libs/**`, `pkgs/akanjs/**`)
 
 - Use `"use client";` at the top of client component files.
+- A `"use client"` file re-exports by name (`export { A, B } from "./x"`), never with `export *`: the server knows a
+  client module only by the export names it spells out, so `akan start` and `akan build` stop on a star re-export.
 - Be careful when importing client-only code from page or layout modules.
 - Keep page props serializable unless the existing route pattern clearly allows otherwise.
 - In domain UI the boundary is mechanical, not a judgment call: `Template`, `Zone`, and `Util` are always client components with `"use client"` on line 1; `Unit` and `View` are always server components and never carry the directive.
@@ -273,8 +289,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.
@@ -291,11 +309,11 @@ What an app serves, how many processes it runs, where its logs go, and what ship
 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.
+- **Web surfaces are `web: true | false | { csr: boolean }`.** `{ csr: false }` drops the CSR bundle the native
+  apps ship, `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.
@@ -304,7 +322,7 @@ Full contract: `get_guideline` with `runtimeRule`, or `akan guideline show runti
   rotating log file; nothing supervises it but the orchestrator's probes.
 - **Route prefixes move together or not at all.** `new AkanApp({ prefix, websocketPrefix })` in `main.ts` moves
   the server's routes, the gateway's websocket upgrade and — through the SSR bootstrap script — the
-  `fetchClient` in every tab the server renders. A prebuilt CSR shell or a Capacitor bundle is never rendered by
+  `fetchClient` in every tab the server renders. A prebuilt CSR shell or a native app bundle is never rendered by
   a server, so `api: { prefix, websocketPrefix }` in `akan.config.ts` is what those follow; declare it there too
   when the app ships either. Read the value with `getApiPrefix()` / `getWsPrefix()` from `akanjs/base` — never
   write `/api` or `/ws` as a literal, and never try to hand it down as a React prop: `FetchClient` fixes its
@@ -332,9 +350,40 @@ Full contract: `get_guideline` with `runtimeRule`, or `akan guideline show runti
   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.
+- **Native apps are the `native` section** — iOS, Android and a desktop app (macOS, Windows, Linux), each shipping
+  the CSR bundle on the native runtime. Shared fields (`appName`, `appId`, `version`, `indexPath`, `permissions`,
+  `plugins`, `deepLinks`, `updates`, …) sit beside one section per platform: `ios`, `android`, `desktop`, and a
+  platform section's own `indexPath` wins on that platform (`desktop: { indexPath: "/" }`). Without
+  `targets` the app has one target, `default`, and an app with no basePaths leaves `basePath` out; a target takes
+  the same shape and overrides the section field by field — objects merge key by key, a list or any other value
+  replaces the section's. `akan start-ios` / `start-android` / `start-desktop` run a dev build that loads its pages
+  from `akan start`; `build-ios` / `build-android` / `build-desktop` write
+  `apps/<app>/.akan/native/<target>/build/<platform>`, a desktop app only for the computer that builds it
+  (`--installer true` adds a Windows setup). With `updates: { url, publicKey }` an installed app takes the signed
+  releases `akan publish-update` makes; `akan update-keygen` makes the key and prints its `publicKey`.
+- **A desktop app that carries its server (`desktop: { server: true }` in `native`, or in one target) gets nothing
+  from `docker`.** That server is API-only, runs in database mode `single`, and listens on a loopback port any
+  program on the computer can call, so guard its endpoints as a network server's. An executable the app spawns
+  goes in `bin` — per platform, a download checked against its `sha256` or a file beside the config, put first on
+  the app's PATH so the server's `spawn("ffmpeg")` finds it, and in `ctx.binDir` for a native plugin — and a package
+  that builds itself at install goes in `trustedDependencies`, which the image honours too. Carry a static LGPL
+  ffmpeg: a `--enable-nonfree` build may not be redistributed. A file the user picks with
+  `filePicker.pickFiles({ forServer: true })` reaches it as a grant, never a copy or a path:
+  `NativeFile.resolve(grant, "read")` in `akanjs/server` asks the shell for it. What it carries is readable on the
+  user's computer — `private/` (each lib's too, under `private/libs/<lib>`), the one `env.server.<env>.ts` of its
+  `--env` and its libs' server env defaults (`env.server.testing.ts`) — and it has no `public/`: read runtime files
+  from `AKAN_APP_DIR`, never `process.cwd()`.
 - **`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 +406,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 +470,11 @@ stores need none, because state and CRUD actions are generated. The body is thre
 `this.setX(...)` → toast. The optimistic shape is mutate the client model, `void fetch.*`, then commit. Use
 `this.pick(...)` when the value must exist, `this.get()` when it may not, and `this.set({...})` to write. Mutate lists
 through the collection API (`this.set({ xList: xList.set(x).save() })`), not array spread. **An action returns
-nothing** (`no-return-in-store-action.grit`). **Never `import type { RootStore } from "../st"`** — it crashes
-`akan build` with a Bun SSR segfault.
+nothing** (`no-return-in-store-action.grit`). **Reach another store through `this`:**
+`import type { RootStore } from "../st"`, then `(this as unknown as RootStore).logout()` to call its action or
+`(this as unknown as RootStore).set({ … })` / `.get()` to write or read its state. Every store is mixed into one root
+at runtime, so the cast only tells the type what `this` already is. Keep it `import type` — `st.ts` imports every
+store, so a value import is a cycle.
 
 **`<model>.dictionary.ts`** — fixed chain, with empty stages still written:
 `.of() → .model() → .insight() → .query() → .sort() → .enum() → .slice() → .endpoint() → .error() → .translate()`.
@@ -464,6 +516,25 @@ Full contract — credential handshake, room revalidation, socket cleanup scopin
 - **A cleanup registered with `ws.on("disconnect" | "unsubscribe", fn)` is scoped to the call that registered it**
   — a room for a `pubsub` subscribe, the socket for a `message` handler. Cleanup that must happen either way
   registers for both.
+- **A call's deadline is the endpoint's `{ timeout: <ms> }`, and there is nowhere else to put one.** It bounds
+  both ends: the `Timeout` middleware — registered by default, and standing aside for every endpoint that
+  declares none — rejects the call with `base.error.gatewayTimeout`, and the same value is serialized to the
+  client as that call's request budget. Declared nowhere, a call takes the client's own default of **30
+  seconds**, so an endpoint whose real work runs longer (provisioning, a firmware flow, an external
+  orchestration) has to declare one or it dies mid-flight with a transport error that does not say whether the
+  server ever received it. A caller overrides it per call with `fetch.x(…, { timeout })` — `false` waits as long
+  as the runtime will — and an app moves its own default with `fetch.instance.setTimeout(ms)`. An upload is
+  never bounded. **Losing the race does not cancel the work**: the handler runs to completion with nobody
+  holding its result, so a deadline is an answer to the caller, not an undo.
+- **A cached answer is the endpoint's `{ cache: <ms> }`, and only a `query` taking no internal argument may have
+  one.** It is a step of the call, not a middleware, and stands aside for every endpoint that declares nothing.
+  Internal arguments are how a call learns who is asking (`.with(Self)`), so an endpoint that has them answers
+  per caller and one shared entry would be one caller's answer handed to the next — that endpoint and every
+  `mutation` are named in the log and left uncached. The lookup runs after the guards, so a hit reaches only a
+  caller they admitted; what is cached is the handler's result, so `resolveReturn` still masks fields and resolves
+  relations per call; a cache backend that is down is warned about and the call runs uncached. The default
+  middleware chain is `Logging → Timeout → <lib middlewares>`, then guards → internal arguments → cache →
+  handler, and there is no `Retry` middleware.
 
 ### Authorization Defaults
 
@@ -530,8 +601,11 @@ Full contract — filter-arg `ref` pickers, `getQueryMeta` summary counters, `la
   first "more". `isCumulativeOf<Model>` is the mode.
 - **"Is there more" is `hasMoreOf<Model>`, never `count > page * limit`.** It comes from the length of the batch
   the server returned, so it survives `{ insight: false }` and cannot drift from a count a live event moved.
-- **Hydrated vs raw:** server queries return hydrated `cnst.<Model>` instances (with `set`/`save`/`refresh`);
-  client fetch results are raw `GetStateObject` plain data, functions stripped.
+- **Hydrated vs raw:** server queries return hydrated `cnst.<Model>` instances (with `set`/`save`/`refresh`),
+  and so do client fetch results — `FetchClient` parses every return with `crystalize` defaulting to **true**
+  (`pkgs/akanjs/fetch/client/fetchClient.ts`). The raw `GetStateObject` shape is what the `<ref>Obj` /
+  `<ref>ObjList` / `<ref>ObjInsight` handles carry, because those pass `crystalize: false` on purpose so the
+  value can cross the RSC boundary as a client prop.
 - Every filter generates fourteen methods: `list` · `listIds` · `find` · `findId` · `pick` · `pickId` · `exists` ·
   `count` · `insight` · `query` · **`remove`** · **`removeOne`** · **`update`** · **`updateOne`**. The last four
   are query-level writes — one atomic UPDATE, **no hooks**, and therefore no `_postRemove` and no cascade. Use
@@ -569,7 +643,7 @@ Full contract — relevance ordering, `columns` / `weights`: `get_guideline` wit
 - Injected dependencies resolve by field-name convention: a field named `<refName>Service` resolves to the service registered under `<refName>`, and `<refName>Signal` likewise (`pkgs/akanjs/service/injectInfo.ts`).
 - The `Service`/`Signal` suffix is required — the injector strips it to derive the registry lookup key. Name the field after the target refName plus the suffix, not arbitrarily.
 - Preference order inside a service: `service<srv.XService>()` for another module's service · `plug(AdapterClass)` or `plug(StorageAdaptorRole)` for an adapter · `use<T>()` only to reach an `option.ts`-registered legacy singleton · `env(...)` for config.
-- **`memory(...)` takes a scalar or model class, not only a primitive** — `memory(Map, { of: CallStateInput })` serializes through the constant and travels as JSON text, so the Redis and sqlite-backed caches round-trip the same declaration. Never hand-encode JSON into a `String` memory.
+- **`memory(...)` takes a scalar or model class, not only a primitive** — `memory(Map, { of: CallStateInput })` serializes through the constant and travels as JSON text, so the Redis and sqlite-backed caches round-trip the same declaration. Never hand-encode JSON into a `String` memory. A memory is scoped to the service or adaptor that declares it; `ttl` (milliseconds) sets how long each write lives unless the `set` call names its own `expireAt`, and a `Map` entry expires on its own.
 
 ### Adapters — `adapt()` And `plug()`
 
@@ -644,10 +718,14 @@ it.
   (RFC 7591; Cursor's `cursor://` redirect admitted) plus the consent page `libs/shared/page/oauth/consent` — and
   names itself as the issuer, so `/mcp` demands a bearer token, verifies its signature, and refuses one carrying no
   `aud`. A token is the app's own access JWT plus `aud`/`iss`/`client_id`, so `AccountMiddleware` and the guards
-  judge it unchanged; there is no scope. Per-app knobs live in `env.server.*` under `oauth` (`consentPath` and
-  `signinPath` with the basePath, `clients`, `dynamicRegistration`, `allowedRedirectSchemes`, `clientIdMetadata`,
-  `enabled`). `/mcp` reads the `Authorization` header only — a cookie is dropped at the door — and `JWT_SECRET` is
-  mandatory outside `local`, because the derived fallback is forgeable from three public names. A grant is revoked
+  judge it unchanged. The tokens this built-in server mints carry no scope; `auth.scopes` / `AKAN_MCP_SCOPES` are for
+  tokens an external issuer mints, and declared beside this server they refuse every one of its tokens with 403
+  `insufficient_scope`. Per-app knobs live in `env.server.*` under `oauth` (`consentPath` and
+  `signinPath` with the basePath, `clients`, `dynamicRegistration`, `allowedRedirectSchemes`, `accessTokenSeconds`,
+  `clientIdMetadata`, `enabled`, plus `issuer` / `resource` — set those when a tunnel or an edge makes the derived
+  origin wrong, because an MCP client compares the issuer byte for byte). `/mcp` reads the `Authorization` header only — a cookie is dropped at the door — and `JWT_SECRET` (or
+  `security.jwtSecret`) is mandatory whenever `operationMode` is not `local`, because the derived fallback is
+  forgeable from three public names; `AKAN_ALLOW_DERIVED_JWT_SECRET=1` accepts that risk explicitly. A grant is revoked
   whole — `POST /oauth/revoke` (RFC 7009) by the client, `fetch.revokeOAuthConnection(sessionId)` by the account's
   owner, `fetch.listOAuthConnections()` to see them — and a revoked access token is refused at its next call.
 - **A person may, a model may not.** An agent's token names its `client_id` and `aud`; a browser session has
@@ -696,9 +774,12 @@ what every developer must know even when not building one.
   every tool runs in the caller's own browser session, gated by guards and the approval card. Its guard is
   `AgentRelayAccess`, which refuses every call until the app names a guard of its own —
   `option.setAgentAccess(SignedIn)`. **The LLM is configured in `option.ts`, never through the environment**
-  (`option.setLlm({ apiKey, model, host })`). Three providers ship — `DeepseekLlm` (the default, text only),
-  `OpenaiLlm` and `AnthropicLlm` (both read images) — and swapping one in is
-  `option.applyAdaptor(LlmAdaptorRole, AnthropicLlm)`.
+  (`option.setLlm({ apiKey, model, host })`). Two adaptors ship, one per wire: `OpenaiLlm` is the default and
+  speaks the chat-completions dialect to whatever `host` names — OpenAI, DeepSeek, Groq, OpenRouter, Ollama — and
+  `AnthropicLlm` speaks the Messages API and reads a PDF as well as a picture. Both require `model`. A provider
+  neither covers is an `adapt()` class in `srvkit/` implementing `LlmAdaptor`, applied with
+  `option.applyAdaptor(LlmAdaptorRole, TheClass)`; whatever settings it needs beyond `LlmOption` ride `setLlm`
+  too, read back with `use<MyLlmOption>()`.
 - **Declare the tool beside the control that already does it**, never as a separate surface:
   `st.tool("x").desc("…").arg("id", ID).exec(fn)` returns the callable to hand to `onClick` — one handler for the
   person and the agent. Publish it only where the screen already renders the control; a falsy name declares the
@@ -727,6 +808,7 @@ what every developer must know even when not building one.
 - Put display and predicate logic on the `Light<Model>` class rather than in a util module — see Module File Playbook.
 - Defaults are a literal for scalars and a thunk for anything constructed. Arrays are `field([T])`; optional is the postfix `.optional()`.
 - **`field.visual(T)` is a field the page renders and an agent never sees** — a blur placeholder, a rendered HTML body, a serialized geometry. It stays an ordinary stored `property` (persistence, search, forms and the page response untouched) and is stripped wherever a value is masked for an AI caller: every in-page-agent read and every MCP result, along with the MCP readable schema. Unlike `hidden`/`secret` it is cost, not secrecy — nothing is refused over one. Reach for it whenever a field is bulky and useless to a model; that is cheaper than every tool learning to avoid it.
+- **A `field.hidden` / `field.secret` value reads `null` on the client, and the type still declares it.** `SignalContext.resolveReturn` skips both field types while it builds an endpoint's response, and hydration writes `null` over the key rather than leaving it absent — the first branch of the loop in `constant/getDefault.ts`, ahead of the field's own default. So the value is a deliberate `null` behind a type promising a `string`, every use of it typechecks, and the failure lands wherever it is finally dereferenced instead of where it was read. **Guard with `??` or `== null`**: `=== undefined`, a destructuring default and an optional parameter default all catch only a missing key and sail straight past this one. A projection (`pickById(id, { secret: true })`) widens the *server's* read, never the response. If a screen needs the value, the field is neither hidden nor secret; if it only needs to be cheap for a model rather than unseen, that is `field.visual`.
 
 ### Scalar & Field Type Reference
 
@@ -760,7 +842,8 @@ Full contract — the trigger-maintained mirror, tokenizer changes, `AKAN_SEARCH
   backstop, including for a `text` field *underneath* one of those. Do not work around either.
 - The role works on a relation (`image: field(File, { text: "thumb" })`) and on an array; an array of objects
   indexes by leaf key. A field inside a `Map` indexes nothing — there is no fixed path to extract it from.
-- Search runs on sqlite/libsql only. `q.search()` against Postgres throws, loudly, rather than returning every row.
+- Search runs in every database mode — fts5 on SQLite/libSQL, a weighted `tsvector` (`pg_trgm` for `trigram`) on
+  Postgres. The same text matches the same documents; only the order may differ on Postgres.
 
 ### Image & File Fields
 
@@ -809,10 +892,17 @@ 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 CSR bundle (a native app, `?csr=true`) never shows a root layout's own markup.** Pages render into the
+  frame, and what the root layout draws around `{children}` stays in a hidden container, so its wrappers cannot
+  stack a second screen beside the frame. Its components still mount and their effects run (`<Auth.User />` works).
+  Anything a person must see from a root layout — an overlay, a gate, a banner — renders through
+  `createPortal(…, document.body)`, as `<Agent.Chat />` and the dialogs already do. A non-root `_layout.tsx` has no
+  such limit.
 - **A page names every `[x]` segment of its path with `.param("x", Type)`** and reads a query key only through
   `.search("k", Type)`. Values arrive typed — `ID`/`String` → string, `Int`/`Float` → number, `Boolean`, `Date` →
   Dayjs, an `enumOf` class → its union, `[T]` → array — a path value the type refuses answers not-found, and a
@@ -855,10 +945,10 @@ export default page()
 
 ## Akan Sync Conventions (`apps/**`, `libs/**`)
 
-- `apps/<appName>` root may only contain these files: `AGENTS.md`, `CLAUDE.md`, `akan.app.json`, `akan.config.ts`, `capacitor.config.ts`, `client.ts`, `main.ts`, `package.json`, `server.ts`, `tsconfig.json`, `tsconfig.tsbuildinfo`.
-- `apps/<appName>` root may only contain these folders: `.akan`, `android`, `common`, `env`, `ios`, `lib`, `mobile`, `page`, `plugin`, `private`, `public`, `script`, `secrets`, `srvkit`, `ui`, `webkit`.
+- `apps/<appName>` root may only contain these files: `AGENTS.md`, `CLAUDE.md`, `akan.app.json`, `akan.config.ts`, `client.ts`, `main.ts`, `package.json`, `server.ts`, `tsconfig.json`, `tsconfig.tsbuildinfo`.
+- `apps/<appName>` root may only contain these folders: `.akan`, `common`, `env`, `lib`, `native`, `page`, `plugin`, `private`, `public`, `script`, `secrets`, `srvkit`, `ui`, `webkit`.
 - `libs/<libName>` root may only contain these files: `AGENTS.md`, `CLAUDE.md`, `README.md`, `akan.config.ts`, `akan.lib.json`, `client.ts`, `index.ts`, `package.json`, `server.ts`, `tsconfig.json`, `tsconfig.spec.json`, `tsconfig.tsbuildinfo`.
-- `libs/<libName>` root may only contain these folders: `common`, `env`, `lib`, `page`, `plugin`, `private`, `public`, `srvkit`, `ui`, `webkit`. A library is never booted or packaged as an app, so the run and mobile entries an app carries (`main.ts`, `capacitor.config.ts`, `.akan`, `android`, `ios`, `mobile`, `script`, `secrets`) are rejected there.
+- `libs/<libName>` root may only contain these folders: `common`, `env`, `lib`, `native`, `page`, `plugin`, `private`, `public`, `srvkit`, `ui`, `webkit`. A library is never booted or packaged as an app, so the run and mobile entries an app carries (`main.ts`, `.akan`, `script`, `secrets`) are rejected there. A Capacitor-era `ios` / `android` / `mobile` folder or `capacitor.config.*` is refused in an app root too, named as a leftover: the native runtime generates its projects under `.akan/native/<target>`.
 - Both allowlists have one source — `pkgs/@akanjs/devkit/workspaceLayout.ts`. `akan sync` (error), `akan doctor`
   (diagnostic), and `akan quality scan` (warning) all read it, so add a new root entry there and mirror it into this
   list, never into one of the three call sites.
@@ -882,12 +972,18 @@ export default page()
 | Folder | Admission test | Naming |
 |---|---|---|
 | `common/` | pure, isomorphic, zero-dependency; may import only sibling `common/*` and `akanjs/base`. Cannot import `Err`, so keep throwing code out of it. | camelCase file, filename equals the single export |
-| `webkit/` | touches `window` / `navigator` / Capacitor, or is a React hook | `use<Thing>.tsx` — `.tsx` even with no JSX |
+| `webkit/` | touches `window` / `navigator` / the native bridge (`akanjs/client/native`, or `akanjs/client/native/<plugin id>` for any builtin plugin), 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` |
+| `native/` | a native plugin the app or lib owns: `native-plugin.json` beside its page API (`src/index.ts`, `definePlugin` from `akanjs/client/native`), its desktop part (`src/desktop.ts`, `defineDesktopPlugin` from `akanjs/native/desktop`), Kotlin and Swift. Every mobile and desktop target ships it; a lib's reach only the apps that depend on it, and the app's own wins an id | `native/<id>/`, the folder named after the plugin id |
 
 - Hooks return a named object of async closures, never a tuple.
+- A `native/` plugin's page API is imported by a `webkit/` hook (`../native/<id>/src`) and nothing else; pages and
+  components call the hook, the same way they reach `akanjs/client/native`.
+- `ui/` is the presentation layer — markup and the looks it is built from — so a recipe lives there although it is
+  neither a component nor a hook. Not `webkit/`: its hooks are `"use client"`, the opposite signal for a function
+  server components call. Not `common/`: it cannot import `akanjs/ui`, where `recipe` / `tv` come from.
 - `libs/<lib>/ui/tokens.css` is the one CSS file a lib owns: plain `:root` custom properties for colors that must **not** follow the theme (a vendor brand color, a fixed surface). Every app whose pages reach that lib compiles it automatically, ahead of the app's own stylesheets, so nothing is imported by hand and no app can forget it. Reference them as `bg-[var(--kakao)]`; `@theme` extensions stay in the app stylesheet, because the color vocabulary is closed per stylesheet. Theme-following colors are the app's, not the lib's.
 - A layer-root `index.ts` is generated, but a `ui/<Folder>/index.tsx` that builds a namespace is hand-written source. The distinguishing test is that a generated barrel contains nothing but `export * from "./X";` lines.
 - `ui/<Folder>/index_.tsx` (trailing underscore) is the `"use client"` + `lazy()` boundary, with a server-safe `index.tsx` beside it. Collapsing the pair into one file breaks RSC.
@@ -900,12 +996,15 @@ when two shapes disagree.
 - `children: any` — newer files use `children: ReactNode`.
 - Hard-coded API keys or secrets in source; they belong in `option.ts` or env.
 - Large blocks of commented-out code left in place.
-- Cross-store writes through a `RootStore` cast — it collides with the Bun SSR-bundler segfault.
 - Stale `// TODO: Implement …` comments above implemented methods.
 - `{cond && <X/>}` in JSX, hard-coded Korean bypassing `l()`, and `window.alert(...)` for user feedback.
 - Bare `/* eslint-disable */` blocks — use `// biome-ignore lint/<rule>: <why>`.
 - Raw palette grays such as `text-gray-400` instead of the semantic tokens (`text-foreground/70`).
 
+A store calling `(this as unknown as RootStore).<action>()` or `.set({ … })` over
+`import type { RootStore } from "../st"` is **not** one of these — it is the sanctioned way to reach another store's
+actions and state (see `<model>.store.ts` above).
+
 ## Secrets And Env Safety (`.env`, `infra/**`, `*secret*`, `*credential*`)
 
 - Never print, summarize, commit, or expose real secret values, credentials, tokens, private keys, or `.env` contents.
@@ -924,7 +1023,9 @@ when two shapes disagree.
   selected one's log beside it. `Tab` walks every row and `1`-`9` jump to that app (the rail shows each
   app's digit), `↑↓` scroll (shift for a page, `G` back to following),
   `/` greps, `e` shows stderr only, `c` clears, `y` copies, `Y` copies the log path, `o` opens the browser,
-  `r` restarts that app, `q` quits.
+  `r` restarts that app, `q` quits. Under `--share`, `s` copies the public URL — the selected app's, or every
+  app's from the merged row — and the header carries it ahead of the local one, because the line `--share`
+  printed before the view took the terminal is gone by its first repaint.
   **`--plain` prints prefixed interleaved lines instead**, and a pipe, a redirect or an unsized terminal
   downgrades to that on its own.
 - **A supervised session writes `local/apps/<app>/runtime/dev.log`, and that path is how a log gets handed over.**
@@ -935,11 +1036,13 @@ when two shapes disagree.
   other file. The previous session is kept beside it as `dev.prev.log`. Hand somebody — or an agent — the
   path rather than a paste: it costs one line instead of a transcript, and it can be re-read after a fix.
   In the view, `y` copies the lines the filters have already narrowed and `Y` copies the path.
-- **How many apps boot at once is the machine's answer, not a constant.** A cold boot build is the builder's
-  RSS peak (~900MB per app), so the default wave is what memory and cores allow — half the memory budget
-  divided by that peak, and one app per four cores — which boots a laptop's apps together and still staggers
-  them inside a small container. The session says which in one line. `--concurrency <n>` overrides it, and
-  `AKAN_MEMORY_LIMIT` lowers the budget it derives from.
+- **How many apps boot at once is the machine's answer, not a constant.** A cold boot is an app's RSS peak
+  (~1.8GB per app, most of it the build worker — the base build, then the SSR registry's), so the default wave
+  is what memory and cores allow — half the memory budget divided by that peak, and one app per four cores —
+  which boots a laptop's apps together and still staggers them inside a small container. The session says
+  which in one line. The next wave starts once an app serves and its boot builds have settled, or 30 seconds
+  after it serves, while the app shows as ready — and `--open` opens it — as soon as it serves.
+  `--concurrency <n>` overrides the wave size, and `AKAN_MEMORY_LIMIT` lowers the budget it derives from.
 - `--kill` frees the dev ports first — it resolves each port's listener, walks up to the top of that akan dev
   tree and signals it, so another checkout's server or a stale orphan on the same port is reclaimed. A holder
   that is not recognisably an akan process is reported and left alone.

package/guidelines/fieldRule/fieldRule.instruction.md

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

package/guidelines/mcpRule/mcpRule.instruction.md

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

package/guidelines/queryRule/queryRule.instruction.md

@@ -31,6 +31,10 @@ with it. `conventions` carries the invariants — this is the full contract behi
   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`).
+- **Every sort ends with `id`, in the direction of its last key, and a missing value sorts below every other** —
+  first ascending, last descending, in every database mode and in the client placing a live row. Rows the declared
+  keys tie on (a midpoint priority dragged into one gap until the float runs out, two rows saved in one millisecond)
+  therefore keep one order across `loadMoreOf<Model>()` pages and live insertions.
 - **A slice list is either one window or an accumulated one, and the store says which.** `setPageOf<Model>` swaps
   the window and `pageOf<Model>` names it; `loadMoreOf<Model>()` appends the rows *after* the ones already loaded
   and takes no page number, because in an accumulated list no page number names anything. It skips by
@@ -49,7 +53,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 +94,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 +119,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