@akanjs/cli 3.0.2 → 3.1.0-rc.1

package/guidelines/conventions/conventions.instruction.md

@@ -67,7 +67,9 @@ back.
 - **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
-  `common/`, `webkit/`, or `ui/` exist for exactly this reason — they are load-bearing, not cruft.
+  `common/`, `webkit/`, or `ui/` exist for exactly this reason — they are load-bearing, not cruft. A module's
+  `*.signal.test.ts` / `*.service.test.ts` is held to the same rule but may import the runtime's `node:*` and
+  `bun:*` modules (a temp dir, a socket, sqlite), which module code leaves to `srvkit/`.
 - **`#private` is banned in exactly four file suffixes:** `*.constant.ts`, `*.document.ts`, `*.service.ts`, and
   `*.store.ts` (`no-js-private-class-method.grit`). The rule is scoped by file path, not by class shape, so
   `#private` remains the house style everywhere under `srvkit/`, including `adapt()` adapter classes.
@@ -202,6 +204,13 @@ back.
 - Prefer focused behavior tests for public contracts and edge cases over implementation-detail assertions.
 - Run package suites with `bun run akan test <pkg>` from the repo root, or `cd <pkg> && bun test --isolate`. Plain `bun test` without `--isolate` shares one global object across test files and fails dozens of tests from cross-file state pollution (`bunfig.toml` `[test] isolate` is not honored as of Bun 1.3), and running `bun test` from the repo root breaks subprocess stdio pipes.
 - Split signal tests in two. `<model>.signal.spec.ts` holds reusable fixtures built on `sampleOf(cnst.XInput)` with explicit `Promise<cnst.X>` return types and **no assertions**. `<model>.signal.test.ts` holds the assertions: `describe("<Model> Signal")`, `let` fixtures at describe scope, one `beforeAll`, story-ordered `it`s, and negatives via `await expect(p).rejects.toThrow()`.
+- **One suite per module file, named after it.** A module test is `<model>.<role>.test.ts` beside the file it covers
+  (`chatMessage.signal.test.ts`, `chatMessage.service.test.ts`, `ChatMessage.Zone.test.tsx`). Never split one role
+  across topic files such as `chatMessage.trim.signal.test.ts` / `chatMessage.security.signal.test.ts` — add a
+  `describe` block to the existing suite. A suite that drives several modules (guards across models, an app's MCP
+  exposure list) belongs to none of them and goes in `srvkit/`, like `libs/shared/srvkit/guards.signal.test.ts`.
+  Never put a test at the `lib/` root. `akan sync` refuses all three shapes. Nothing imports a test, so a build never
+  typechecks one; `akan typecheck <app-or-lib>` does, `bun:test` types included.
 - `lib/user/user.signal.spec.ts` is the one place agent types are re-exported and re-typed; import `UserAgent` / `AdminAgent` from there rather than from the owning lib directly.
 - A placeholder `it` with a descriptive title is an acceptable floor. Write a real suite when the behaviour is security-relevant.
 
@@ -310,11 +319,11 @@ are, because those are the ones the server could have done.
    consume them in a server component, never as a `Zone` prop.
 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.
+   is the shape: `title` / `left` / `right` beside `back` and `children`, each filled by the server.
 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.
+8. **Gate auth on the server** — `getSelf({ unauthorize: "/signin" })` in `_layout.tsx`, before any of the page's
+   markup renders. After its fetch the redirect is an in-page one (HTTP 200); `.config({ ssr: "block" })` makes it a 3xx.
 9. **Prefer CSS over client state for pure visibility.** A `data-*` attribute plus `group-data-[…]` variants, or
    `<details>`/`<summary>`, keeps both branches server-rendered.
 10. **Keep the heavy island out of the first load** — behind the `ui/<Folder>/index_.tsx` + `lazy()` pair.
@@ -379,8 +388,8 @@ Full contract: `get_guideline` with `runtimeRule`, or `akan guideline show runti
   from `akan start`; `build-ios` / `build-android` / `build-desktop` write
   `dist/native/<app>/<target>/build/<platform>`, a desktop app only for the OS that builds it — `--arch` picks
   a Windows or Linux app's CPU, and a macOS app is Apple silicon only. `--installer true` adds a Windows setup, a
-  macOS dmg or a Linux AppImage; `AKAN_NATIVE_MACOS_*` signs with a Developer ID and notarizes,
-  `AKAN_NATIVE_WINDOWS_*` signs with Authenticode. With `updates: { url, publicKey }` an installed app takes the signed
+  macOS dmg or a Linux AppImage; `--sign` signs with the identity `AKAN_NATIVE_MACOS_*` / `AKAN_NATIVE_WINDOWS_*`
+  names and `--notarize` uploads the signed macOS app to Apple — the env alone does neither. 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`** — and `server: { omit: [...] }` leaves out packages only the image needs. That server is API-only, runs in database mode `single`, and listens on a loopback port any
@@ -393,7 +402,9 @@ Full contract: `get_guideline` with `runtimeRule`, or `akan guideline show runti
   `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()`.
+  from `AKAN_APP_DIR`, never `process.cwd()`. **`server: { profile: "edge" }` bundles `env.server.<env>.edge.ts` in
+  that file's place**, and the build refuses one holding a secret-named value; `server: { modules: ["@edge"] }`
+  mounts only the modules whose `serve()` lists `operationMode: ["edge"]`, and what they reach.
 - **`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/`.
@@ -481,7 +492,9 @@ count was shortened to `count(query)`, with `countDocuments` kept as `@deprecate
 `removeById(id)` are those same query-level writes narrowed to one id, **not** the document path: they fire no hooks,
 so a model whose removal cascades or carries a `_postRemove` still goes through `remove<Model>(id)`. The
 write-through pair is `pickAndWrite(id, data)` / `pickOneAndWrite(query, data)` — pick the document, write into it
-and save it, so the save hooks do run; reach for those when the write has to be seen by them.
+and save it, so the save hooks do run; reach for those when the write has to be seen by them. `upsertById(data, {
+preserveTimestamps })` writes a record whole under its own id, new or in place, with no hook: the write a sync or a
+backfill repeats safely, keeping the record's `createdAt`/`updatedAt` when asked.
 
 **`<model>.service.ts`** — keep methods to a few lines: load → chain → `return await ….save()`. Write `return await`
 explicitly in tail position; do not "optimize" it away. Side effects belong in `override async _preUpdate` /
@@ -517,7 +530,9 @@ workflow changes.
 
 - Keep domain business operations in `.service.ts` classes built with `serve(...)`.
 - Keep execution contracts and triggers in `.signal.ts` classes built with `internal(...)`, `slice(...)`, and `endpoint(...)`.
-- Use `Internal` for internal triggers such as init, interval, cron, or queue jobs.
+- Use `Internal` for internal triggers such as init, interval, cron, or queue jobs. A `process` job's
+  `backoff: { type: "exponential", delay, maxDelay }` caps the wait between attempts, and the internal's
+  `onFailed(job, error)` runs once a job has failed its last attempt — the dead letter, on either queue.
 - Use `Slice` for typed data views that feed client stores and zones; keep each slice focused on one purpose.
 - Use `Endpoint` for query and mutation contracts exposed to callers.
 - Connect external APIs or infrastructure through adapters, usually under `srvkit/`, and inject them into services instead of importing vendor clients directly into domain logic.
@@ -541,6 +556,11 @@ Full contract — credential handshake, room revalidation, socket cleanup scopin
   inside a guard or middleware). Behind a federation gateway, `ws.remoteAddress` and the child's own peer are the
   *gateway* (`127.0.0.1`) for every caller and for the whole life of every socket. `Ip` reads what a proxy
   recorded, is unwrapped from its `::ffff:` form, and is `null` rather than a placeholder when genuinely unknown.
+- **A device or another server proves itself with a machine token, never a staff session.**
+  `MachineToken.issue({ kind, id, version })` (`akanjs/server`) signs one with `AKAN_MACHINE_PRIVATE_KEY` (made by
+  `akan machine-keygen <file>`), with no expiry; a server holding that key or `AKAN_MACHINE_PUBLIC_KEY` sets
+  `account.machine` from a verified one on HTTP and websocket alike, and only from one. Read it with `.with(Machine)`
+  or in a guard, and revoke by bumping the version the guard compares to the record's own.
 - **Every socket carries a `socketId`, and only the framework mints one** — read it off the `Ws` internal arg
   (`.with(Ws)` hands `{ ws, socketId, subscribe, on, off }`). Never mint your own from `ws.data`: the room
   bookkeeping keys on the framework's id and a second one fails to match it silently. It identifies a
@@ -603,7 +623,7 @@ Full contract — credential handshake, room revalidation, socket cleanup scopin
 
 - `.body(...)` / `.param(...)` args accept `ConstantFieldTypeInput` only: scalars, model refs, or `enumOf(...)`.
 - Numbers must use `Int` or `Float` — `Number` is rejected (`pkgs/akanjs/signal/endpointInfo.ts`).
-- `Upload` is valid only inside a mutation flagged for file upload: `mutation([cnst.File], { fileUpload: true }).body("files", [Upload])`, as the `file` module does. It is not a model field type.
+- `Upload` is valid only inside a mutation flagged for file upload: `mutation([cnst.File], { fileUpload: true }).body("files", [Upload])`, as the `file` module does. It is not a model field type. The other body args of such a mutation arrive typed as in a JSON body. A file's `type` on the server is what its name implies, not its bytes — check the bytes when the type matters.
 - Bytes are `Binary`, never `Any` — see Scalar & Field Type Reference. A `Binary` return travels as base64 in an
   HTTP body, and a return declared `Any` that turns out to be bytes fails instead of reaching the caller as `{}`.
 
@@ -669,7 +689,8 @@ Full contract — filter-arg `ref` pickers, `getQueryMeta` summary counters, `la
   "archived" })`. The patch cannot trail the filter args, so it lands on a terminal `.set()`; building the chain
   touches nothing.
 - `removeOne` / `updateOne` hit the **newest** match, always, and report only counts — they are for "there is at
-  most one of these", not for claiming the next item off a queue.
+  most one of these", not for claiming the next item off a queue. A condition in the query is a compare-and-set in
+  every mode: of two concurrent calls that both saw the row match, one applies, and `modifiedCount` says which.
 - **A filter may not be keyed after its own model.** A filter `chat` on model `chat` would silently swap the
   single-document `removeChat`/`updateChat` for a hookless query-level one; it throws at boot instead.
 - **"Has no value" is `q.empty`, never `q.missing`.** `q.missing` is the key being *absent from the stored JSON*,
@@ -735,7 +756,12 @@ Conventions that hold for both shapes:
 - `try/catch` is rare and always converts an exception into a decision, never swallows one. Guards catch → `logger.warn` → `return false`; adapters catch → `logger.error` → `return null`; UI uses `try/finally` to reset a spinner. A bodyless `catch {}` is acceptable only with a one-line reason.
 - Store actions do not `try/catch` — let the framework toast the `Err`. Client-side validation failure is `msg.error("<key>")` plus an early return, never a throw.
 - **A server-side `fetch.clone({ origin })` opens no websocket unless `connect: true`**: it makes one-off calls to
-  another server, and a socket it opened would reconnect forever with nobody to close it.
+  another server, and a socket it opened would reconnect forever with nobody to close it. It never carries the
+  visitor's session either: a call to another origin sends only the `jwt` its caller gave the clone.
+- **Retry a call with `retry`, never with a loop of your own.** `fetch.clone({ origin, retry: {} })` (or a call's
+  own `{ retry }`) tries again on an unreachable server, a 502/503/504 and a 429 after its Retry-After, backing off
+  with jitter; a mutation retries under one `Idempotency-Key` it mints, or the `idempotencyKey` you name, and the
+  server runs a mutation once per key and caller, answering a repeat with the first result. A 4xx is never retried.
 - `String(err)` and `${err}` read `Err: <key> {…data}`, the data as one line of JSON with secret-named keys masked,
   so a ``logger.warn(`…: ${String(error)}`)`` keeps the exit code or status the `Err` carried.
 - **A failure another process reported travels as itself.** A server-to-server `fetch.<endpoint>(..., { origin })` restores the remote `Err` — the same class, key and `data` — so a hop that rethrows it answers its own caller with that error and the dictionary translates it. Never wrap the catch in a `new Error`, and never re-key it as a `new Err` of your own: both discard what the endpoint chose to say, and a bare `Error` is generalized to `Internal Server Error` on the way out.
@@ -768,9 +794,10 @@ it.
   `Person` for an act reserved for a person, `mcp: { cru: false }` for the tools whose input models cost the model
   tokens, `outputSchema` for nothing that reaches the model.
 - Settings live in the app's `lib/option.ts` — `option.setMcp({ enabled, readOnly, path, version, instructions,
-  allowedOrigins, pageSize, language, outputSchema, rateLimit, auth })`, or `setMcp((env) => …)` for one derived from the server env, **not
+  allowedOrigins, pageSize, language, outputSchema, rateLimit, apps, modern, auth })`, or `setMcp((env) => …)` for one derived from the server env, **not
   `main.ts`**. Each field has an `AKAN_MCP_*` env spelling. `AKAN_MCP_READONLY=true` is the read-only-deployment
-  valve, not the exposure switch; `AKAN_MCP=false` takes the whole surface off. Every call that executes an
+  valve, not the exposure switch; `AKAN_MCP=false` takes the whole surface off, and an edge server
+  (`AKAN_PUBLIC_OPERATION_MODE=edge`) starts with it off unless `AKAN_MCP=true` or `setMcp(true)`. Every call that executes an
   endpoint is rate-limited per caller (120 a minute, 8 in flight, per process; 429 + `Retry-After`) — `rateLimit`
   / `AKAN_MCP_RATE_LIMIT` tunes or disables it.
 - **Authentication is the same server.** An app mounting `libs/shared` serves the OAuth 2.1 authorization server
@@ -811,7 +838,15 @@ it.
   from, minus what is already attached; lists — only lists — are cut to `promptBudget`. A guard refusing a query
   inside the body reads as the screen refusing the account, the same way a redirect does. A
   required argument left out answers a pointer to the `<model>List…` tool, never a guess. The description is the
-  only instruction, in English — `<Agent.Guide>` never reaches MCP, and the in-page chat lists no page prompts.
+  only instruction, in English — `<Agent.Guide>` never reaches a prompt, and the in-page chat lists no page prompts.
+- **The same page is a tool too, and an MCP Apps host renders it.** A `.prompt()` page answers `tools/call` with
+  that briefing plus its web URL, and a host that declares the `io.modelcontextprotocol/ui` extension (claude.ai,
+  ChatGPT, VS Code) shows the screen itself in the chat — the CSR bundle in a sandboxed iframe whose every call the
+  host relays under the agent's token. It shows the page alone: every layout above it still runs (guards, providers,
+  `<Agent.Guide>`) and draws nothing, unless it draws no page, as a gate does. Nothing is written for the view. An
+  endpoint kept off the shelf only by `mcp: false` stays callable by that view and is listed to no model; a `Person`
+  act is still refused there. `option.setMcp({ apps: false })` keeps pages prompts only, and a page named like an
+  endpoint stays one (boot warns).
 
 Full contract — configuration, wire behaviour, resource URIs, OAuth metadata, protocol revisions, and
 `McpProgress.report`: `get_guideline` with `mcpRule`, or `akan guideline show mcpRule`.
@@ -905,7 +940,7 @@ 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 in every database mode — fts5 on SQLite/libSQL, a weighted `tsvector` (`pg_trgm` for `trigram`) on
+- Search runs in every database mode — fts5 on SQLite, 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
@@ -957,9 +992,12 @@ shape, so `cascade` never means "related" — it means one of exactly these:
   `_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()`, `.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.
+  `.layoutStyle()` / `.viewport()` 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, and one that throws renders no head (warned about) so a layout's sign-in redirect
+  still answers; there is no metadata object, and analytics is the app's own script, not a stage.
+  Heads merge root first: a deeper `.head()` replaces the `<title>`, a `<meta>` with the same `name` / `property`,
+  and a canonical / manifest / icon link, and keeps the rest — so a page states only what it changes.
 - **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).
@@ -971,7 +1009,9 @@ shape, so `cascade` never means "related" — it means one of exactly these:
   Dayjs, an `enumOf` class → its union, `[T]` → array — a path value the type refuses answers not-found, and a
   search value that fails is dropped. A layout may declare a subset. Names are string literals: `akan sync` reads
   them off the source and refuses a `[projectId]` folder whose page declares no `.param("projectId")`. `lang` is
-  never declared: every route sits under `/:lang`, and the locale segment reaches every stage as `lang`.
+  never declared: every route sits under `/:lang`, and the locale segment reaches every stage as `lang`. On a web
+  page's first render `st.use.searchParams()` is still the server's empty snapshot, synced right after hydration, so
+  an effect that needs the query on its first run takes the page's `.search()` value as a prop.
 - `_overrides.tsx` is a logic-free UI-override manifest: imports plus a single `export default override({ Slot: AppComponent })` (from `akanjs/ui`), no `"use client"`. It re-skins framework `akanjs/ui` components for its route subtree; nested manifests merge over ancestors slot-by-slot (closest wins). See the UI Customization reference for the slot list.
 - The legacy shape — `export default async function Page` beside `pageConfig` / `head` / `Loading` exports — still
   loads and logs one deprecation warning per file at boot. Migrate with the `workspaceRecipes` recipe "Migrating
@@ -988,10 +1028,10 @@ shape, so `cascade` never means "related" — it means one of exactly these:
 export default page()
   .param("orgId", ID)
   .config({ transition: "stack" })
-  .render(async ({ orgId }) => {
+  .render(({ orgId }) => {
     const { l } = usePage();
     getSelf({ unauthorize: "/signin" });
-    const [{ org }, { taskInitInOrg }] = await Promise.all([fetch.viewOrg(orgId), fetch.initTaskInOrg(orgId)]);
+    const { taskInitInOrg } = fetch.initTaskInOrg(orgId);
     return <Task.Zone.Card init={taskInitInOrg} prefix={`/org/${orgId}`} />;
   });
 ```
@@ -999,7 +1039,8 @@ export default page()
 - There is no `loader=` / `render=` page prop and no `PageProps` interface: the chain declares the arguments and
   `.render()` receives them flat, typed, with `lang` on every route and `children` added for a layout.
 - Body order inside `.render()`: `usePage()`, auth, fetch, return.
-- Run independent fetches through `Promise.all`, even when there is only one.
+- Hand each `fetch.init*` / `view*` / `edit*` field to its section unawaited. Await only what the shell itself
+  reads — a title, a redirect, an id for a link — and run those awaits through one `Promise.all`.
 - Gate auth at `_layout.tsx`; repeating `getSelf({ unauthorize: "/signin" })` in the page is fine and common.
 - `async` on the render callback only when the body awaits; the callback is not a React component, so it takes no
   name and no return type.
@@ -1020,12 +1061,12 @@ export default page()
   content outside the markers is yours. `akan lint` fails when the generated section is stale.
 - The `plugin/` facet holds Akan plugin declarations; files use the `<name>.plugin.ts` convention (e.g. `pushNotification.plugin.ts`) and are re-exported from the generated `plugin/index.ts` barrel.
 - Do not add `apps/*/base` or `libs/*/base`; place shared utilities under that app or lib's own `common/`.
-- `apps/*/lib` and `libs/*/lib` root files are limited to generated/support files: `cnst.ts`, `db.ts`, `dict.ts`, `option.ts`, `sig.ts`, `srv.ts`, `st.ts`, `useClient.ts`, `useServer.ts` — plus a `<model>.signal.test.ts` / `.spec.ts`, the one hand-written file that belongs there because the suite boots the whole barrel.
+- `apps/*/lib` and `libs/*/lib` root files are limited to generated/support files: `cnst.ts`, `db.ts`, `dict.ts`, `option.ts`, `sig.ts`, `srv.ts`, `st.ts`, `useClient.ts`, `useServer.ts`. Nothing hand-written sits beside them, tests included: a test goes in the module folder it covers (`lib/<model>/<model>.signal.test.ts`), or in `srvkit/` when it drives several modules.
 - Domain module folders are `lib/<model>` for database modules, `lib/_<service>` for service modules, and `lib/__scalar/<scalar>` for scalar modules.
 - Database module UI files are limited to `<Model>.Template.tsx`, `<Model>.Unit.tsx`, `<Model>.Util.tsx`, `<Model>.View.tsx`, and `<Model>.Zone.tsx`.
 - Service module UI files are limited to `<Service>.Util.tsx` and `<Service>.Zone.tsx`.
 - Scalar module UI files are limited to `<Scalar>.Template.tsx` and `<Scalar>.Unit.tsx`.
-- Module `*.test.ts`, `*.test.tsx`, `*.spec.ts`, and `*.spec.tsx` files are allowed.
+- A module test is named after the one module file it covers — `<model>.<role>.test.ts` / `.spec.ts`, `<Model>.<Role>.test.tsx` — so `<model>.<topic>.signal.test.ts` is refused, just like `<model>.<topic>.signal.ts`.
 - `ui/index.ts`, `webkit/index.ts`, `srvkit/index.ts`, `common/index.ts`, `plugin/index.ts`, and module `lib/**/index.ts` files are generated by scanSync; do not hand-edit or track them.
 - Generated facet indexes export only 1-depth files/folders with `export * from "./name";`. A facet folder with
   nothing to export syncs to `export {};` (a missing folder gets no barrel), so a stale barrel heals on the next
@@ -1131,6 +1172,10 @@ actions and state (see `<model>.store.ts` above).
   exist yet and the whole `libs/` container is watched, which is the safe direction.
 - Test production build generation with `bun run akan build <appName>`.
 - To test a built artifact locally, run it from the generated app directory with the required Akan runtime environment variables.
+- A server a test boots in-process takes `start({ listen: false, schedules: false })` to run no internal (init,
+  interval, cron, queue worker); `listen: false` alone still runs them, as a batch replica does. A server process a
+  test spawns from source resolves the workspace from its cwd and gets the root `.env` from Bun, so spawn it inside
+  the repo with `bun --no-env-file`, or spawn the built `dist/apps/<app>` output, which needs neither.
 
 ```bash
 cd dist/apps/<appName> && USE_AKANJS_PKGS=true AKAN_PUBLIC_REPO_NAME=<repo> AKAN_PUBLIC_SERVE_DOMAIN="<domain>" \

package/guidelines/cssRule/cssRule.instruction.md

@@ -62,6 +62,25 @@ Screen code is invariant — a plain `<Button variant="primary">` never changes.
 - Theme-following colors still belong to the app: a lib token is for a color that must **not** change with `data-theme`.
 - An `@import` the CSS pipeline cannot resolve fails the build; it is never dropped. A stylesheet under `page/` that no route imports is compiled by nothing and warns at build time.
 
+## Frame Variables (the page's chrome and the device's insets)
+
+The frame writes these on `#frameRoot` and `<html>`, so any class can read them, web and native alike:
+
+- `--akan-top-safe-area` / `--akan-bottom-safe-area` — the notch and the home indicator. On the web they are
+  `env(safe-area-inset-*)` where the route chain declares `safeArea` (`.config({ safeArea: true })` on the root
+  layout) and `0px` where it does not; in a native app they are the shell's inset. Use the variable alone: never
+  write `env(safe-area-inset-*)` beside it, and never subtract one from the other. The frame paints the bottom strip
+  only under bottom chrome (a `BottomInset` or `BottomTab`) or a route's own `bottomSafeAreaColor`; elsewhere a page's
+  `fixed bottom-0` bar paints its own safe-area padding.
+- `--akan-top-inset` / `--akan-bottom-inset` — the height of the page's top bar and bottom tab slot, per breakpoint
+  when the page declares a responsive inset. A slot whose inset is 0 at a width clips its chrome there and hides it
+  from the keyboard and screen readers, so a phone-only bar needs no `md:hidden`.
+- `--akan-keyboard-inset`, `--akan-viewport-height`, `--akan-viewport-offset-top` — the on-screen keyboard over the
+  page's bottom, the visible height, and how far iOS panned the page to show a field (the top slots follow it).
+- `--akan-content-height` — the room between the insets. iOS pans under the keyboard instead of shrinking the page,
+  so a column sized by it leaves the panned-to area blank: keep a keyboard-heavy screen's input bar in flow at the end
+  of its column, or in the keyboard slot.
+
 ## Codegen Rules
 - Do not hardcode hex or raw-palette colors (`bg-red-500`, `#ff0000`); use semantic tokens.
 - Do not put inline color literals in `style={{ }}`; use token classes.

package/guidelines/mcpRule/mcpRule.instruction.md

@@ -10,7 +10,8 @@ The always-loaded convention set carries the short version; this is the full con
 Every signal is served to AI agents as an MCP server on `POST /mcp`. **`/mcp` is mounted by default and exposure
 follows an endpoint's guards — there is no per-endpoint opt-in, and nothing to write in a signal file.** An endpoint
 that declares a real guard is published; one that declares none is refused, and so is a mutation whose only guard is
-`Public`. `AKAN_MCP=false` takes the whole surface off. The reasoning is that the guards are already the
+`Public`. `AKAN_MCP=false` takes the whole surface off, and an edge server (`AKAN_PUBLIC_OPERATION_MODE=edge`) starts
+with it off — `AKAN_MCP=true` or `setMcp(true)` puts it back. The reasoning is that the guards are already the
 authorization decision and `filterForAccount` re-reads them per caller on every listing, so a second per-endpoint
 switch says nothing the guards do not — while guaranteeing that every endpoint added later is invisible to agents
 until somebody remembers it.
@@ -38,6 +39,9 @@ export class FileSlice extends slice(srv.file, {
   `update`, `remove`), same fallbacks (`create`/`update`/`remove` inherit `cru`), and the same scope: it narrows
   the root slice and the generated CRUD, and never reaches a named slice or a custom endpoint. Those declare
   their own `mcp` beside their own `guards`. The bare `mcp: false` is every key at once, still within that scope.
+- **A screen keeps reaching it.** To a host that renders MCP Apps views, an endpoint refused for `mcp: false` alone
+  is published with `visibility: ["app"]`: the view the page tool opens may call it, the model is never shown it
+  (below). Every other refusal still holds there.
 - **`mcp: true` is the default and is a no-op**; write it only to say out loud that an entry is deliberately on
   the shelf. It does not override a shape refusal (an `Any` return stays refused) and it cannot publish something
   the guard rules keep out.
@@ -50,13 +54,14 @@ export class FileSlice extends slice(srv.file, {
 
 ## Configuration
 Settings live in the app's `lib/option.ts` — `option.setMcp({ … })`, taking `enabled`, `readOnly`, `path`,
-`version`, `instructions`, `allowedOrigins`, `pageSize`, `language`, `legacyTextBlock`, `outputSchema`, `rateLimit`, and `auth`. **Not `main.ts`**: the gateway
+`version`, `instructions`, `allowedOrigins`, `pageSize`, `language`, `legacyTextBlock`, `outputSchema`, `rateLimit`,
+`promptBudget`, `apps`, `modern`, and `auth`. **Not `main.ts`**: the gateway
 there only spawns children, and `option.ts` is the app-authored file `server.ts` already hands to the process that
 mounts `/mcp`. Every lib's option is read in mount order with the app's last, so an app tightens what a library
 declared without restating it. Each field also has an env spelling (`AKAN_MCP`, `AKAN_MCP_READONLY`,
 `AKAN_MCP_PATH`, `AKAN_MCP_VERSION`, `AKAN_MCP_INSTRUCTIONS`, `AKAN_MCP_ALLOWED_ORIGINS`, `AKAN_MCP_PAGE_SIZE`,
 `AKAN_MCP_LANGUAGE`, `AKAN_MCP_LEGACY_TEXT`, `AKAN_MCP_OUTPUT_SCHEMA`, `AKAN_MCP_RATE_LIMIT`, `AKAN_MCP_CONCURRENT`,
-`AKAN_MCP_AUTH_SERVERS`, `AKAN_MCP_SCOPES`, `AKAN_MCP_RESOURCE`) for a deployment that configures what the source does
+`AKAN_MCP_PROMPT_BUDGET`, `AKAN_MCP_APPS`, `AKAN_MCP_MODERN`, `AKAN_MCP_AUTH_SERVERS`, `AKAN_MCP_SCOPES`, `AKAN_MCP_RESOURCE`) for a deployment that configures what the source does
 not, which the option overrides.
 The two booleans answer to `AKAN_PUBLIC_MCP` / `AKAN_PUBLIC_MCP_READONLY` too, the same pairing `AKAN_OPENAPI`
 has, and a value written in code wins over the env of the same name — an explicit `undefined` is not a value.
@@ -100,8 +105,8 @@ export class TaskEndpoint extends endpoint(srv.task, ({ mutation }) => ({
 export default page()
   .param("taskId", ID, { desc: "The task to review." })
   .prompt("reviewTask", "Review this task and suggest next steps.")
-  .render(async ({ taskId }) => {
-    const { taskView } = await fetch.viewTask(taskId);
+  .render(({ taskId }) => {
+    const { taskView } = fetch.viewTask(taskId);
     return <Task.Zone.View view={taskView} />;
   });
 ```
@@ -226,7 +231,9 @@ export default page()
   wire-identical over the POST-only surface this implements — a client whose proposal is not listed is told to
   disconnect. An unknown proposal is answered at whichever end of that list it is closer to, and an unimplemented
   method answers `404` to a modern client but `200` to a legacy one, whose era spends `404` on "your session is
-  gone".
+  gone". **While MCP Apps renders views only the legacy pair is spoken**: `server/discover` answers `-32601` and
+  `initialize` settles on `2025-11-25`, because claude.ai renders a view only for a server it reached through
+  `initialize`. `modern: true` / `AKAN_MCP_MODERN=true` offers `2026-07-28` anyway; `false` withholds it everywhere.
 - **A modern-era request mirrors `MCP-Protocol-Version` and `Mcp-Method` into headers** (plus `Mcp-Name` when the
   body names one), and one that leaves a mirror out is refused just like one that contradicts the body: a gateway
   rule keyed on a header never fires for the request that omitted it. Legacy requests are not checked. Capabilities
@@ -354,6 +361,58 @@ in-page chat lists none of them: its `/` menu is its six built-in commands. Pick
 rule: a page taking no arguments is the most useful prompt, since MCP has no completion — one taking an id is for
 when the id is already in hand.
 
+## MCP Apps — The Page, Rendered In The Chat
+**A `.prompt()` page is also a tool**, of the same name and arguments, marked `readOnlyHint`. Its result is the
+prompt's briefing plus `Open this screen in a browser: <url>` — what a client without the
+`io.modelcontextprotocol/ui` extension (Claude Code, Codex) reads. A host that declares the extension (claude.ai,
+Claude Desktop, ChatGPT, VS Code, Goose) is also given `_meta.ui.resourceUri` (`ui://<app>/app`, or
+`ui://<app>/app/<basePath>`) and renders the screen in place of the result: the app's CSR bundle, one HTML document,
+in a sandboxed iframe started on the page the tool ran. Its first queries are answered from that run — carried in
+the result's `_meta`, the one part no host shows the model — so the first paint costs no round trip; every later
+call is relayed by the host as `tools/call` under the host's token. Nothing is declared for any of it.
+
+- **What a view may call** is every published tool and every endpoint kept off the shelf by `mcp: false` alone,
+  listed with `visibility: ["app"]` — which a host offers to the view and never to the model. Visibility is a host's
+  UX, not authorization: the guards decide, as everywhere. A client that did not declare the extension is listed
+  neither those tools nor the `ui://` resources, a call to one answers `Unknown tool`, and a page tool's result
+  carries none of the view's data for it.
+- **The capability is read per request.** A legacy client declares it once at `initialize` and is issued an
+  `Mcp-Session-Id` (`ui.<uuid>`) that stores nothing, since its id is the capability; with `modern: true` a modern
+  request carries it in `_meta`. A client that declares nothing is issued no session, exactly as before.
+- **The view is the page, not the app around it.** Each layout above it still runs — guards, providers,
+  `<Agent.Guide>` — but what it draws around `{children}` is hidden, with its frame chrome (`Layout.Navbar`,
+  `TopInset`, `BottomInset`, `BottomTab`), the `topInset` / `bottomInset` it reserves and the tools its controls
+  publish. A layout that draws no page, like a gate, is the screen then and is shown. The screen the view opened on
+  has no back button: there is nothing behind it.
+- **The view has no network.** `connect-src` stays closed; the app's own origin is opened for what a page loads by
+  URL — fonts (served with `Access-Control-Allow-Origin: *`) and stored images — and every root-relative URL the
+  page writes is pointed at it, since a host may block the document's `<base>` (Claude does).
+  Cookies and Web Storage are in-memory, history is in-memory, and the websocket, live sync, pubsub, the reconnect
+  overlay and `<Agent.Chat />` are off. A path link routes inside the view; any other link opens through the host.
+- **The view looks like the host.** Its neutrals (`--background`, `--foreground`, `--muted`, `--border`, `--ring`) and
+  `--font-sans` / `--font-mono` follow the host's theme variables, its theme follows the host's, and so does its
+  language when the app speaks it; the app's brand colors and radii stay its own.
+- **The host's model drives the screen too.** The view offers the host the screen's own tools — the surface
+  `<Agent.Chat />` reads: `st.tool`, the form setters, `fill<Model>Form`, `navigate` / `readScreen` / `readState` /
+  `highlight` — and, to a host that takes it, the screen's context (route, live state, `<Agent.Guide>`) through
+  `ui/update-model-context` whenever it moves. A tool that declares `confirm` asks the person in the view through
+  the `AgentApproval` slot, whatever the host asks on its own; a card tool, which a person answers in a chat, is not
+  offered.
+- **A person tapping in the view acts with the agent's token**, so `isAgentCall` is true and a `Person` act is
+  refused there. That act belongs on the web page the result links to. The view holds no token: it is handed the
+  caller's claims, so `getSelf({ unauthorize })` in a layout renders the screen instead of a sign-in page, and each
+  call it makes is relayed and judged by the guards.
+- **A view's call answers what a browser would get**, in `_meta` beside the masked result: the value with its
+  `visual` fields, or the domain `Err` with its key and data, toasted in the user's language. A refusal and a crash
+  stay generalized.
+- **What a document load would do, the view does in place.** `router.refresh()` renders the route afresh, a
+  download (`<a download>`, a data table's export) goes to a host that saves files, and a full navigation off the
+  app shows a notice instead of a blank frame.
+- **A page named like an endpoint stays a prompt only**, published or not, and the boot log says so: the endpoint
+  keeps its name. A refused screen answers as a tool error (`isError`), which the model reads.
+- `option.setMcp({ apps: false })` / `AKAN_MCP_APPS=false` keeps every page a prompt only. `web: { csr: false }`
+  publishes the tool with no view, and an API-only build (`web: false`) has no pages to publish.
+
 ## Progress Reporting
 **`McpProgress.report(n, { total, message })`** reports progress from anywhere inside a call, a service or adapter
 frames down included, and is a no-op when nobody is streaming — so the same code runs unchanged over HTTP, a
@@ -421,8 +480,9 @@ the same guards.** What stays closed is closed because no agent has a reason to
 
 ## Writing `instructions`
 
-`*.abstract.md` and `<Agent.Guide>` never reach an MCP client. Exactly three texts do: `instructions`, every
-published entry's `.desc()`, and a page's `.prompt()` description. All three are English, whatever the users speak
+`*.abstract.md` never reaches an MCP client, and `<Agent.Guide>` only through an MCP Apps view, beside the screen's own
+tools it explains. Exactly three texts reach every client: `instructions`, every published entry's `.desc()`, and a
+page's `.prompt()` description. All three are English, whatever the users speak
 — the reader is a model, and the catalogue is built once in one `language` and cached by clients.
 
 - **`instructions` is the workflow.** Five to eight sentences, in this order: what the app is and what its nouns
@@ -453,10 +513,10 @@ published entry's `.desc()`, and a page's `.prompt()` description. All three are
 - The lib's own suites run wherever it is mounted: the OAuth signal test (metadata, registration, both `authorize`
   redirects, code exchange, `/mcp` with the minted token and the refusal of a first-party or forged one, refresh
   rotation) and the refresh-session and option unit tests.
-- **One exposure test per app**, in a `lib/<model>.signal.test.ts`: list `tools/list` with a user token and pin the
-  names with `toEqual`, and assert the curated and admin-only ones with `not.toContain`. Exposure is derived from
-  the guards, so a guard change fails this test first — which is the point. The framework's own pattern is
-  `pkgs/akanjs/server/mcp/mcp.integration.test.ts`.
+- **One exposure test per app**, in `srvkit/mcpExposure.signal.test.ts`, since it spans every module: list
+  `tools/list` with a user token and pin the names with `toEqual`, and assert the curated and admin-only ones with
+  `not.toContain`. Exposure is derived from the guards, so a guard change fails this test first — which is the point.
+  The framework's own pattern is `pkgs/akanjs/server/mcp/mcp.integration.test.ts`.
 - Live: connect a client, consent, call a tool, `claude mcp logout`, authenticate again. `AKAN_PUBLIC_LOG_LEVEL=debug`
   prints one `OAuth token request grant_type=… client_id=…` line per token call; two refreshes in the same second
   both answering 200 is the grace window working, not a fault.

package/guidelines/queryRule/queryRule.instruction.md

@@ -65,9 +65,15 @@ with it. `conventions` carries the invariants — this is the full contract behi
 - `removeOne` / `updateOne` hit the **newest** match — the subquery they compile to is ordered `createdAt` descending
   and there is no way to change that. They also report only counts, never which row they touched, so they are for
   "there is at most one of these", not for claiming the next item off a queue. Pass a query that matches one row.
+  The query is a compare-and-set in every mode: of two concurrent `updateOne({ id, balance: { $gte: n } }, …)` that
+  both read the row as matching, only one applies, so `modifiedCount` is the verdict.
 - **A filter may not be keyed after its own model.** Filter methods are assigned after CRUD, so a filter `chat` on
   model `chat` would silently swap the single-document `removeChat`/`updateChat` for a hookless query-level one. It
   throws at boot instead (`assertFilterFitsCrud`).
+- **An insight field counts or sums.** `accumulate: {}` counts the rows the query matches and `accumulate: { status:
+  "active" }` those that also match the condition; `accumulate: { $sum: "totalValue", status: "active" }` adds the
+  field up over the same rows (`field(Float, { default: 0, accumulate: … })`), a stored value that is not a number
+  counting as nothing — the same answer on SQLite and Postgres.
 - **"Has no value" is `q.empty`, never `q.missing`.** The three absence operators are distinct: `q.exists` is the
   key being present, `q.missing` is the key being *absent from the stored JSON*, and `q.empty` is either — absent,
   or present and null. An optional field is written both ways over its life: an insert that omits it leaves the key
@@ -119,7 +125,7 @@ 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 in every database mode: fts5 on SQLite/libSQL, a weighted `tsvector` under a GIN index on Postgres.
+- Search runs in every database mode: fts5 on SQLite, 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.
@@ -185,6 +191,10 @@ shape, so `cascade` never means "related" — it means one of exactly these:
   unmounted `refPath` candidate only warns, since that list spans optional modules by design.
 - **Nothing checks whether another document still references the same target.** `File` in particular is deduped
   by `origin`, so two parents can share one row; `removeRef` claims the field owns its target exclusively.
+- **A reference no cascade removes keeps pointing at the removed row, and a response reads it live-only**: a list
+  leaves the target out, an optional field reads `null`, and a required one answers 404
+  `base.error.relationNotFound` naming the model and the field path. Make a reference whose target can go first
+  `.optional()`, or let it go with the target through `removeWith`.
 - Removal is soft (`removedAt`), but the storage delete a `_postRemove` performs is not — a cascade is not
   restorable, and reviving the owner does not revive what went with it.
 - A `removeWith` declaration **auto-creates its index** (`{ removedAt, fk }`, or `{ removedAt, typeKey, fk }` when