@akanjs/cli 3.1.0-rc.1 → 3.1.0-rc.11

package/guidelines/cssRule/cssRule.instruction.md

@@ -11,13 +11,28 @@ Use TailwindCSS with Akan's semantic design-token layer and the `akanjs/ui` prim
 - Compose classes with `cn` from `akanjs/client` (token-aware tailwind-merge) — the only class-combining function. No object syntax: write `cond && "x"`.
 - Forward `className` last so callers can extend styles.
 
+## Color Vocabulary — What Lint Refuses
+- Vocabulary closure strips the raw Tailwind palette, so these render as no CSS and fail lint: raw palette classes
+  (`bg-blue-500`, `text-gray-400`), arbitrary color values (`bg-[#3b82f6]`), an arbitrary class built by
+  interpolation, daisyUI legacy classes (`btn-primary`, `card-body`) and its dropped color slots (`bg-base-100`,
+  `text-base-content`, `text-primary-content`, `bg-error` — use `background`/`muted`/`border`, `foreground`,
+  `<color>-foreground`, `destructive`), and color literals in `style={{...}}` (`no-raw-palette-class`,
+  `no-arbitrary-color`, `no-daisyui-legacy-class`, `no-inline-color`, `no-interpolated-arbitrary-class`).
+- A legitimate fixed color (OS-chrome mockups, data-viz) takes a `// biome-ignore lint/plugin: <reason>`.
+- Color literals in SVG color attributes (`fill`, `stroke`, `stopColor`, `floodColor`, `lightingColor`, `color`) and
+  in `el.style.<prop> = …` / `el.style.setProperty(…)` writes are flagged as warnings for now; `currentColor`,
+  `none`, `transparent`, `var(--…)` and `url(#id)` stay legal.
+- Class order is the sorter's: `nursery/useSortedClasses` is an error and also sorts the string arguments to `cn()`.
+  Output such as `font-bold text-2xl text-foreground` or `border-foreground/5 border-t` is correct — write the
+  classes in any order, run the formatter, leave the result.
+
 ## Recipe Layer
 - Reusable or variant-like styling belongs in a recipe (a cva-style factory), not repeated inline class stacks.
 - Framework primitives ship recipes: `buttonRecipe` and `badgeRecipe` from `akanjs/ui`. Call them as `buttonRecipe(variants, className?)` — the second argument is merged automatically, so you never wrap it in `cn()`:
   - `buttonRecipe({ variant: "primary", size: "lg" }, "w-full rounded-2xl")`
 - Prefer the `akanjs/ui` primitives (`Button`, `Badge`, `Input`, `Field`, `Table` …) over re-implementing a component's look with utility stacks. There is **no `Card`/`Box` primitive** — a card/box is a recipe surface (e.g. `appCard`), not an `akanjs/ui` component; do not `import { Card }`.
 - App-specific repeated surfaces go one-per-file in `apps/<app>/ui/Recipe/` (server-safe, no `"use client"`) via `recipe(tv({ base, variants }))`, imported from `@apps/<app>/ui`. App recipes **extend** (surfaces the lib lacks — chat bubble, tile); they never re-define a lib component in parallel.
-- Full recipe authoring/consumption policy: the `recipeRule` guideline. Never guess recipe names/imports — the authoritative list is `AGENTS.md` `## UI Recipes` plus the `list_recipes` tool.
+- Full recipe authoring/consumption policy: the `recipeRule` guideline. Never guess recipe names/imports — the authoritative list is `AGENTS.md` `## Recipes` plus the `list_recipes` tool.
 
 ## Customization Decision (where a design delta goes)
 Screen code is invariant — a plain `<Button variant="primary">` never changes. Only these config files do:
@@ -64,19 +79,25 @@ Screen code is invariant — a plain `<Button variant="primary">` never changes.
 
 ## 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:
+The frame writes these on `#frameRoot` and `<html>`, so any class can read them. The insets and the content height
+are there on every surface; the three keyboard variables are written only on the server-rendered web:
 
 - `--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.
+  layout) and `0px` where it does not, and `env()` measures nothing unless the viewport meta carries
+  `viewport-fit=cover` — the root layout's `.viewport({ fitCover: true })`, which a native app has by default; 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).
+  page's bottom, the visible height, and how far iOS panned the page to show a field (the top slots follow it). Only
+  an SSR page in a browser writes them; a CSR bundle and a native app never do, so read them with a fallback
+  (`var(--akan-keyboard-inset, 0px)`), or take the keyboard from the store's `keyboardHeight`, which a native app's
+  keyboard plugin fills.
 - `--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.

package/guidelines/fieldRule/fieldRule.instruction.md

@@ -10,8 +10,70 @@ Use this whenever generating constants or scalar constants. It defines the curre
 - `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.visual(Type)` is a field the page renders and an agent never sees (below).
 - `field([Type])` defines arrays; provide empty array defaults when the app expects list operations.
 
+## Field Types
+- **Import from `akanjs/base`** (real classes/helpers, not globals): `Int`, `Float`, `ID`, `Any`, `Binary`, `Upload`,
+  `ImageResult`, `enumOf`, and the `dayjs` factory. There is **no `JSON` scalar** — use `Any` for open/flexible
+  payloads, and only when the content is genuinely flexible.
+- **Use the JS globals directly (no import needed)**: `String`, `Boolean`, `Date`. They are monkey-patched to
+  behave like scalars, so `field(String)` typechecks.
+- **`Number` is not a valid field/body type.** `NumberConstructor` is intentionally not augmented, so
+  `field(Number)` / `.body("x", Number)` fails to typecheck. Use `Int` for whole-number counts and quantities and
+  `Float` only for values that need decimals.
+- Runtime resolution of every scalar (globals included) goes through `PrimitiveRegistry` by `refName`
+  (`pkgs/akanjs/base/primitiveRegistry.ts`).
+- **`Binary`, `Upload` and `ImageResult` are never model fields.** The class build refuses `field(Binary)` naming
+  the `File` model instead, because every non-base field lives in the `_doc` JSON column and bytes would sit there
+  as base64 and ride every read of the row. How each travels on the wire: `transportRule` and `mcpRule`.
+- Defaults are a literal for scalars and a thunk for anything constructed (`default: () => dayjs()`, so the value
+  is created at runtime). Optional is the postfix `.optional()`.
+
+## Masked And Visual Fields
+- **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. 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`.
+- **`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.
+- `field.secret`, `field.hidden` and `resolve()` take no `text` search role (`queryRule`).
+
+## Immutable Fields
+- A document-path change to an `{ immutable: true }` field is refused with `base.error.immutableField` (400,
+  `data.field`), which the client toasts in the user's language; query-level writes are not checked.
+
+## Date Fields On An Instance
+- **A model instance's `Date` fields are prototype accessors, not own properties.** `user.createdAt` is still a
+  `Dayjs`, built on first read from a native `Date` the instance holds under a symbol. So `Object.keys(user)` and
+  `{ ...user }` do **not** include them, while `"createdAt" in user`, `for...in`, `JSON.stringify(user)`,
+  `plainFieldsOf(user)` (`akanjs/common`), `immerify`, and `deepObjectify` all do. To copy a model,
+  `new cnst.X().set(user)`, never a spread.
+
+## Image And File Fields
+- **Do not declare `Upload` as a model field.** `Upload` is a signal-body-only primitive. Declare an image/file
+  field as a relation to `File`: `image: field(File).optional()` for one, `images: field([File])` for many.
+- The store then auto-generates an `upload<Field>On<Model>(fileList)` action that calls the framework upload
+  mutation and polls file status until it leaves `"uploading"` (`pkgs/akanjs/store/action.ts`).
+- Storage is wired through the `StorageAdaptor` DI role (default `BlobStorage`,
+  `pkgs/akanjs/service/predefinedAdaptor/storage.adaptor.ts`); the reference implementation is the `file` module.
+  Do not hand-roll data-URL fallbacks. `{ cascade: "removeRef" }` on the field removes the file with its owner
+  (`queryRule`).
+- For a file your own code wrote through `plug(StorageAdaptorRole)`, the disk path is
+  `storage.resolveLocalPath?.(path, access)` — `null` means refused (rooted, NUL, or outside the root; never fall
+  back to `readData()`), `undefined` means the adaptor keeps no local files, and an untrusted key passes
+  `access: "public"`. A `File` field is not one: `libs/shared` stores it through its own `StorageApi`, which may be
+  object storage. Never cast the role to read `BlobStorage`'s `root` / `privateRoot`.
+
 ## Current Akan Patterns
 - Use `String`, `Boolean`, `Date`, `Int`, `Float`, `ID`, scalar classes, model light classes, or enum classes as field types.
 - Use `enumOf()` classes for categorical values that need type-safe values and dictionary entries.

package/guidelines/framework/framework.instruction.md

@@ -1,16 +1,13 @@
 # Akan.js Framework Guide
 
 ## Ownership
-- `apps/<app>` contains app code, pages, env files, module folders, UI, webkit, srvkit, and common utilities.
-- `libs/<lib>` contains reusable domain and utility libraries consumed by apps.
-- `pkgs/akanjs` contains framework facets such as base, constant, document, service, signal, store, client, ui, and CLI tooling.
+- `pkgs/akanjs` facets include base, constant, document, service, signal, store, client, ui, and CLI tooling.
 - Domain behavior lives near the model folder instead of being split by technical layer first.
 
 ## Current Akan Patterns
 - Database module flow is `constant -> dictionary -> document -> service -> signal -> store -> UI`.
-- Scalars live under `lib/__scalar/<scalarName>` and represent embedded value objects.
-- Service modules live under `lib/_<serviceName>` when behavior is not centered on one stored model.
-- Generated registry files such as `cnst.ts`, `db.ts`, `dict.ts`, `sig.ts`, `srv.ts`, and `st.ts` are scanner outputs and should not be hand-authored.
+- Scalars (`lib/__scalar/<scalarName>`) represent embedded value objects; service modules (`lib/_<serviceName>`) hold
+  behavior not centered on one stored model.
 - Pages and components should consume generated client/server helpers rather than duplicating model shapes.
 
 ## Codegen Rules
@@ -23,5 +20,5 @@
 When a request implies a distinct look and feel, do not stop at colors — customize both the theme and, when needed, the components.
 
 - **Theme (`apps/<app>/page/styles.css`).** The app imports Tailwind and `akanjs/ui/styles.css`, then overrides semantic token *values* per theme under `:root, [data-theme="dark"]` and `[data-theme="light"]` (`--background`, `--foreground`, `--primary`, `--muted`, `--border`, … each with a `-foreground` pair for text). The framework maps them to Tailwind color names, so `bg-primary` / `text-foreground` follow the `data-theme` attribute; corner rounding uses `--radius-box` / `--radius-field`. Fetch `get_guideline` with `cssRule` for the full token set before a deep theme pass.
-- **Lib tokens (`libs/<lib>/ui/tokens.css`).** Colors a lib's own components pin — a vendor brand color, a fixed surface — are declared once there as plain `:root` custom properties and compiled into every app that reaches the lib, ahead of the app's stylesheets. Reference them as `bg-[var(--kakao)]`; never copy the block into each app.
+- **Lib tokens (`libs/<lib>/ui/tokens.css`).** The one CSS file a lib owns: colors its own components pin that must **not** follow the theme — a vendor brand color, a fixed surface — declared once as plain `:root` custom properties and compiled automatically into every app whose pages reach the lib, ahead of the app's stylesheets, so nothing is imported by hand. Reference them as `bg-[var(--kakao)]`; never copy the block into each app. `@theme` extensions stay in the app stylesheet, because the color vocabulary is closed per stylesheet, and theme-following colors are the app's.
 - **Components (`page/**/_overrides.tsx`).** When a default `akanjs/ui` component (Button, Modal, Table, Input, Select, …) is too restrictive for the design, re-skin it per route instead of forking, wrapping, or fighting it with utility classes. Write a drop-in replacement in `apps/<app>/ui/` typed against the slot contract (`AkanModalComponent`, or `AkanUiOverrides["<Slot>"]`), composing the framework's headless parts, then bind it in a `page/**/_overrides.tsx` manifest with a single `export default override({ Slot: BrandComponent })`. Overrides cascade down the route tree like layouts (closest ancestor wins). Fetch `get_guideline` with `componentRule` and read the `references/ui/customize` docs page for the slot list and patterns.

package/guidelines/mcpRule/mcpRule.instruction.md

@@ -34,7 +34,8 @@ export class FileSlice extends slice(srv.file, {
 ```
 
 - **It is curation, not authorization.** HTTP serves the endpoint exactly as before and the guards are still the
-  only thing deciding who may call it. Never write `mcp: false` where you meant a guard.
+  only thing deciding who may call it. Never write `mcp: false` where you meant a guard. To take generated CRUD off
+  HTTP too, write `guards: { cru: false }`.
 - **The `mcp` map on `slice()` mirrors the `guards` map above it** — same keys (`root`, `get`, `cru`, `create`,
   `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
@@ -55,7 +56,8 @@ 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`,
-`promptBudget`, `apps`, `modern`, and `auth`. **Not `main.ts`**: the gateway
+`promptBudget`, `apps`, `modern`, and `auth` — or `setMcp((env) => …)` for settings derived from the server env.
+**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`,
@@ -155,12 +157,23 @@ export default page()
   clients read the structured half. A scalar return is unaffected: it has no structured half to point at, so it
   ships as the value itself either way. `resources/read` is unaffected too: `ReadResourceResult` has no
   `structuredContent`, so a resource's text is its only channel and always carries the serialized value.
+- **A picture is an `ImageResult` return, and the one result a model sees rather than reads.**
+  `query(ImageResult, { guards: [...] })` (or `[ImageResult]`) returns `{ data, mimeType, caption? }`: `data` is
+  padded standard base64 with no `data:` prefix, `mimeType` one of `image/png`, `image/jpeg`, `image/webp`,
+  `image/gif` — the types the Anthropic and OpenAI models take. `tools/call` answers the caption as a text block and
+  the picture as an image block, one pair per picture, and publishes no `outputSchema` and no `structuredContent`:
+  either would repeat the base64, a few hundred KB, as text the model pays for and cannot see. A value that breaks
+  the shape is not sent — the dispatcher logs what an `ImageResult` needs and answers the generic failure. Put in
+  the caption what the picture cannot say on its own (the region or scale it spans). Over HTTP the endpoint is the
+  JSON object, so the app's own client and tests read it as usual; everywhere else an agent reads it — a page
+  prompt's resource, the in-page agent — its agent face carries `mimeType` and `caption` only. Nothing caps the
+  size, and Anthropic refuses an image over 5 MB, so keep a picture well under that. It is never a model field.
 - **A request schema asks for a relation's id, and a response schema names a nested model.** `serialize` sends a
   relation field as its id and the server never converts an object back, so publishing the related model's shape
   asked an agent for what the document layer cannot take. On the response side every entry inlines the transitive
   closure of every model it mentions (a `$ref` may not cross entries), and on an open catalogue 83% of the bytes
-  were the same schemas repeated — so a nested database model is published as `{ type: "object", description:
-  "<ModelName>" }` and the returned model keeps every field of its own; an embedded scalar stays inline. Measured,
+  were the same schemas repeated — so by default (`outputSchema: "shallow"`) a nested database model is published
+  as `{ type: "object", description: "<ModelName>" }` and the returned model keeps every field of its own; an embedded scalar stays inline. Measured,
   that took a 347-tool listing from 1194KB to 532KB, and one user's paged `tools/list` to 320KB.
   `option.setMcp({ outputSchema: "full" })` (`AKAN_MCP_OUTPUT_SCHEMA`) restores the closure; `"none"` publishes no
   `outputSchema` at all — results still ship as `structuredContent`, and the text block stays on whatever
@@ -225,15 +238,20 @@ export default page()
 - **A caller's own mistake is reported as one** and never as a server failure: an argument that is missing,
   unparseable, outside its `enumOf`, or **undeclared** comes back as `isError` naming it — `additionalProperties: false` travels in the
   published schema and nothing on the wire enforces it — and so does a document that is not there, as
-  `No <model> found for the arguments given.` A prompt, having no `isError` to carry a refusal, answers `-32602`.
+  `No <model> found for the arguments given.`, and an MCP App view also receives the 404 `base.error.documentNotFound`
+  `Err` a browser would get. A prompt, having no `isError` to carry a refusal, answers `-32602`.
+  A document missing on another server this one called (`fetch.clone({ origin })`) arrives as that server's 404
+  `base.error.documentNotFound`, so a tool reads its dictionary sentence (`The requested item does not exist.`) and an
+  MCP App view receives that `Err`; a prompt whose page reads it is `No screen exists for these arguments.`
   Only a real failure logs a stack; an agent can drive the rest at will.
 - **Three revisions are spoken**: the modern `2026-07-28` and the legacy `2025-11-25` / `2025-06-18`, which are
   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". **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.
+  gone". **While a `.prompt()` page may show as a view 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`. An app that renders no view, or whose RSC worker lists no `.prompt()` page, speaks all three.
+  `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
@@ -311,9 +329,9 @@ delegates to lives in `akanjs/server` (`OAuthAuthorize`, `OAuthToken`, `OAuthReg
   (`["cursor"]` by default, for Cursor's desktop callback), `accessTokenSeconds` (3600, also how long a revoked
   access token can outlive its grant), `clientIdMetadata: { enabled, refusePrivateAddresses }` (both on; `enabled:
   false` turns Client ID Metadata Documents off and the metadata stops advertising them — Claude Code then registers
-  dynamically instead), `issuer` and `resource` (only when a tunnel or an edge makes the derived origin wrong),
-  `enabled: false` to take the server and the `/mcp` credential requirement away together. The signin page must
-  honour `?redirect=` to return the user to the consent page.
+  dynamically instead), `issuer` and `resource` (only when a tunnel or an edge makes the derived origin wrong, since
+  an MCP client compares the issuer byte for byte), `enabled: false` to take the server and the `/mcp` credential
+  requirement away together. The signin page must honour `?redirect=` to return the user to the consent page.
 - **Clients:** Claude Code — `claude mcp add --transport http <name> <origin>/mcp` and nothing else; it registers,
   opens the browser to `http://localhost:<port>/callback`, refreshes on 401. claude.ai — a custom connector by URL
   (needs public HTTPS; DCR or the Advanced-settings client id/secret; callback
@@ -362,7 +380,8 @@ rule: a page taking no arguments is the most useful prompt, since MCP has no com
 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
+**A `.prompt()` page is also a tool**, of the same name and arguments, marked `readOnlyHint: false`, since running
+the page makes its own `fetch.*` calls, mutations included. 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
@@ -371,14 +390,17 @@ in a sandboxed iframe started on the page the tool ran. Its first queries are an
 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.
+- **What a view may call** is every published tool, and every endpoint kept off the shelf by `mcp: false` alone or
+  the generated `light<Model>` read, listed with `visibility: ["app"]` — which a host offers to the view and never to
+  the model; a `Person` guard still refuses one. 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.
+  `Mcp-Session-Id` (`ui.<nonce>.<signature>`) that stores nothing: the app signs it, and an id the app did not sign is
+  served as a client without views. With `modern: true` a modern request carries the capability in `_meta`. A client
+  that declares nothing is issued no session, exactly as before.
+- **A read-only deployment has no MCP Apps.** With `readOnly` / `AKAN_MCP_READONLY` there are no page tools, app-only
+  tools, views or UI sessions, since running a page makes its own `fetch.*` calls, mutations included.
 - **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
@@ -469,7 +491,8 @@ the same guards.** What stays closed is closed because no agent has a reason to
 - **Scope is what makes hiding possible.** `static scope: "account"` (a role check) is evaluated with no arguments
   and filters the listing per caller; `"resource"` (`Can<Verb><Model>`, ownership) needs `context.getArg()`, stays
   listed, and stops the call. Marking a resource guard `"account"` would make the listing lie — the marker has no
-  default for that reason.
+  default for that reason. An `"account"` guard that throws at listing time reached for arguments it does not
+  have: the entry is hidden from every caller and the guard is named once in the log as mismarked.
 - **Identity comes from the internal args** (`.with(Self)`, `.with(Account)`, `.with(Me)`), never from an id the
   client sent, and the service re-checks ownership behind the guard.
 - **An admin who signs in on the consent page mints an admin token.** A connector created under an admin account

package/guidelines/modelConstant/modelConstant.instruction.md

@@ -9,7 +9,7 @@ Generate the business data shape for a collection-backed Akan module. This file
 - Define `ModelObject` by extending `via(ModelInput, (field) => ({ ... }))` for stored fields controlled by system or service behavior.
 - Define `LightModel` by selecting compact list/reference fields from the object layer.
 - Define full `Model` by combining object and light layers and adding only small static or type helpers when needed.
-- Define `ModelInsight` only when aggregation or dashboard values are useful.
+- Always define `ModelInsight`, empty when the model has no aggregation or dashboard values yet.
 
 ## Current Akan Patterns
 - Use `via()` and the `field` helper for all model layers.
@@ -21,6 +21,7 @@ Generate the business data shape for a collection-backed Akan module. This file
 - Keep the light model small enough for lists, cards, and relation previews.
 - Do not put persistence queries, service workflows, fetch calls, or React UI in constant files.
 - Use stable defaults for arrays and frequently read values.
+- Never declare a `static` on the Object or Light class: `via(XObject, LightX, …)` mixes in their prototypes only, so a static there never reaches `X` — put it on `XInput` (or a scalar), `X`, or `XInsight`. `no-static-in-object-light-model` recognises the Object class by its `*Object` name (its `via()` shape is the Insight's) and the Light class by its `Light*` name or its `[...] as const` field tuple.
 - Add dictionary coverage for public fields, enums, insights, and query-facing names.
 
 ## Review Checklist

package/guidelines/modelStore/modelStore.instruction.md

@@ -22,6 +22,15 @@ Generate client state coordination for a module. Store connects generated fetch
 - Do not call private or internal signal operations from UI state.
 
 ## Form Draft Recovery
+- `Load.Edit`, `Model.EditModal` and `Model.New` save the whole `<model>Form` as the user types and offer it back on
+  the next open, so a modal closed by accident, a route change, or a killed app costs nothing. The scope is the
+  record id for an edit and the seed plus the route for a new form, both keyed to the signed-in user, so another
+  record or another parent never loads someone else's half-finished form.
+- A new form's draft is applied on open with a "start over" chip; an edit whose record moved in the meantime is
+  *not* applied, and asks. Turn it off with `draft={false}`, or name the scope yourself with `draft="<scope>"` when
+  the context is in neither the id nor the seed.
+- The old per-field `cache` / `cacheKey` props are deprecated and store nothing — they covered five control types,
+  keyed on the translated label, and restored over server data.
 - `<model>FormDraft`, `restore<Model>FormDraft`, `discard<Model>FormDraft` and `load<Model>FormDraft` are
   generated. Do not hand-write a draft action, and do not write `<model>Form` to browser storage yourself.
 - The draft key carries the signed-in user, derived by hashing the auth token's payload with `iat`, `exp`, `nbf`

package/guidelines/pageRule/pageRule.instruction.md

@@ -0,0 +1,80 @@
+# Page Rule — Route Files, The Route Chain, Heads, Lib Pages
+
+What a file under `page/` may be, how a route declares its arguments and settings, how heads merge, what a CSR
+bundle shows of a root layout, and how a lib's routes reach an app. `conventions` carries the invariants and the page
+body shape — this is the full contract behind them. Before changing route behavior, check
+`pkgs/akanjs/server/routeTreeBuilder.ts` and nearby routes for the expected pattern.
+
+## Route Files
+
+- `apps/<app>/page` may contain route modules only. Do not add helper logic or component-only files there.
+- Route source files under `page/` must use `.tsx`. Do not add `logic.ts`, `.js`, or `.jsx` files under `page/`.
+- A route page is either `<routeName>.tsx` (serving `/routeName`) or a directory's `_index.tsx`; layouts use
+  `_layout.tsx`; per-route UI overrides use `_overrides.tsx`.
+- Reserved `_*.tsx` route filenames are limited to `_index.tsx`, `_layout.tsx`, and `_overrides.tsx`; do not add
+  files like `_Component.tsx` or `_helper.tsx`.
+- Page filenames must not start with an uppercase letter. Move helper components like `Component.tsx` to app `ui`,
+  `common`, or `lib` instead.
+- Dynamic segments use `[id]`; route groups use directories like `(user)`, `(public)`, `(tab)`, or `(detail)`.
+- `_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).
+  The slot list is in `componentRule`.
+
+## The Route Chain
+
+- **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()`, `.loading()`; `.notFound()` / `.error()` on
+  a layout; `.fonts()` / `.theme()` / `.manifest()` / `.reconnect()` / `.wsConnect()` / `.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.
+- **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
+  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`.
+- **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.
+- 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.
+
+## Heads
+
+- **`.head()` takes JSX — `<title>`, `<meta>`, `<link>` — or a function of the route's args returning it.** 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 canonical link and `og:url` each name one URL, so a page carries them only from its own `.head()`, never from a
+  layout's.
+
+## A Root Layout Inside A CSR Bundle
+
+- **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.
+
+## Lib Pages — `syncPageLibs`
+
+- `libs/<lib>/page` follows the same rules and ships routes to apps that opt in with `syncPageLibs` in
+  `akan.config.ts`: `true` takes every lib dep that has a `page` folder, an array takes the libs listed, `false` (the
+  default) syncs nothing.
+- `akan sync` links those routes into `apps/<app>/page/(libs)/(<lib>)` — once per basePath when the app declares
+  subRoutes. The folder is generated and gitignored like `public/libs`; edit the lib source, never the link.
+- Both path segments are route groups, so a lib route mounts at its own path (`libs/<lib>/page/login/_index.tsx`
+  serves `/login`). Two synced routes that resolve to the same pattern are a sync-time error.
+
+## Build Scope And The Legacy Shape
+
+- `.config({ devOnly: true })` keeps a route out of `akan build` while it keeps serving under `akan start` and keeps
+  being typechecked. On a `_layout.tsx` it excludes every route under that directory too. Write it as a literal
+  `true`/`false` — the build reads it off the source without evaluating the module.
+- 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
+  `page/` to the route chain"; new files are never written in it.

package/guidelines/queryRule/queryRule.instruction.md

@@ -1,8 +1,9 @@
 # Query Rule — Filters, Slices, Hydration, Search, Cascade
 
-How a model's data is queried, exposed to a client store, searched, and removed. Filters and slices are the two
-query surfaces; `q.search()` and the `text` field roles are the search surface; `cascade` is what a removal takes
-with it. `conventions` carries the invariants — this is the full contract behind them.
+How a model's data is queried, exposed to a client store, searched, written, and removed. Filters and slices are
+the two query surfaces; the model facade carries the scoped reads and writes; `q.search()` and the `text` field
+roles are the search surface; `cascade` is what a removal takes with it. `conventions` carries the invariants —
+this is the full contract behind them.
 
 ## Slices, Queries, and Hydration
 
@@ -31,6 +32,9 @@ 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`).
+- **`limit: 0` means every row on the server, never on the client.** A server `list<Filter>(…, { limit: 0 })`
+  reads without a ceiling, like an omitted limit, and `null` pages at 20. A client's `0` (`initX(…, { limit: 0 })`)
+  is served `MAX_PAGE_SIZE` (500) with a one-time warn. Paginate (`loadMoreOf<Model>`) or name a page size.
 - **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)
@@ -51,8 +55,9 @@ with it. `conventions` carries the invariants — this is the full contract behi
 - **A projection is bare on the facade and nested under `select` on a filter accessor.** `pickById(id, { secretField:
   true })` / `find(query, { secretField: true })` take the projection as their second argument; a generated
   `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.
+  swap: `{ select: … }` handed to the facade projects a field named `select`, which no model has, and throws
+  `Unknown document field path`. The facade's third argument is the scope (`{ withRemoved: true }`), never a field.
+  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`), 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
@@ -81,6 +86,30 @@ with it. `conventions` carries the invariants — this is the full contract behi
   matches a freshly inserted row and silently stops matching that same row after its first round-trip save. Reach
   for it only to find rows written before the field was declared.
 
+## Soft Removal And The Facade's Writes
+
+- **Removal is always soft** — the framework has no hard delete for a model table, and `delete` is deliberately
+  left unused so it can mean one later. Every read and query-level write sees live rows only (`removedAt IS NULL`).
+- **`{ withRemoved: true }` reaches removed rows**: the third argument of `find` / `findOne` / `findById`
+  (projection second, `null` when none), the last of `count` / `exists` / `updateMany`, or inside `updateOne` /
+  `updateById`'s options. Without it, a `removedAt` condition only a removed row can meet (`q.exists("removedAt")`,
+  a comparison) throws `can never match`.
+- Removes, slices, filter methods, loaders and `pickById` stay live-only, a removed document is read-only
+  (`save()` throws), and `updateById(id, { removedAt: null }, { withRemoved: true })` revives one without hooks.
+- **A `pick` that finds no live row throws `NoDocumentError`**, so the generated `get<Model>` of a missing or
+  removed id answers an HTTP or websocket caller 404 `base.error.documentNotFound`, and an agent `No <model> found
+  for the arguments given.` The message, which names the table and the id or query, stays on the server. Throw
+  your own `Err.NotFound` only where a nullable load decides that nothing found is an error.
+- The facade spells `Many`/`One` out on its writes (`updateOne` / `updateMany` / `removeOne` / `removeMany`); only
+  the count was shortened to `count(query)`, with `countDocuments` kept as `@deprecated`.
+- **`updateById(id, update)` and `removeById(id)` are those same query-level writes narrowed to one id, not the
+  document path**: they fire no hooks, so a model whose removal cascades or carries a `_postRemove` still goes
+  through `remove<Model>(id)`.
+- 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.
+- `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.
+
 ## Text Search In A Filter — `q.search()`
 
 - Text search is a filter query node like any other: `bySearch: filter().arg("text", String).query((text, q) =>
@@ -108,10 +137,12 @@ with it. `conventions` carries the invariants — this is the full contract behi
 
 - 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 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.
+- Pick the role by what the value *is*, because the rank (`bm25` on SQLite) 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.
+- `schema.index({ x: "text" })` (a Mongo text spec) builds nothing and warns at boot: full-text search is this role.
 - **`field.secret`, `field.hidden` and `resolve()` take no `text` role — it is a compile error**, because the
   mirror is plaintext and an indexed secret would leak through search. The class build throws the same refusal as
   a backstop, for an option object the excess-property check cannot see through, and names the way out: drop the
@@ -203,7 +234,9 @@ shape, so `cascade` never means "related" — it means one of exactly these:
   generated `remove<Filter>` / `update<Filter>`, and the facade's `removeById` / `updateById`. Remove one document
   at a time when it cascades.
 - Cascades are **idempotent**: `removedAt IS NULL` is ANDed into every query-level write, and a remove never takes
-  `{ withRemoved: true }`, so an already-removed row keeps its original `removedAt`. Cycles are cut by a visited set
-  carried down the whole chain, with a depth cap of 16. `q.search()` cannot see removed rows (the mirror drops
-  them), so search with the flag throws, as does `upsert` with it.
+  `{ withRemoved: true }`, so an already-removed row keeps its original `removedAt`. Every document a cascade
+  removes one at a time joins a visited set carried down the whole chain (a bulk target never does), so a target held
+  by two `removeRef` fields (or twice in one array) is removed once and cycles are cut; the depth cap is 16.
+  `q.search()` cannot see removed rows (the mirror drops them), so search with the flag throws, as does `upsert` with
+  it.