@akanjs/cli 3.1.0-rc.4 → 3.1.0-rc.5

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:

package/guidelines/fieldRule/fieldRule.instruction.md

@@ -10,8 +10,65 @@ 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`).
+
 ## 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`,
@@ -170,8 +172,8 @@ export default page()
   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
@@ -323,9 +325,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
@@ -485,7 +487,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,26 @@ 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.
+- 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 +133,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

package/guidelines/runtimeRule/runtimeRule.instruction.md

@@ -1,4 +1,4 @@
-# Runtime Rule — Serving, Processes, Logging, Image, Native Apps, Desktop Server, Assets, Build Pipeline
+# Runtime Rule — Serving, Processes, Dev Server, Logging, Image, Native Apps, Desktop Server, Assets, Build Pipeline
 
 How an Akan app is built, what it serves, how many processes it runs, where its logs go, and what ends up in
 its image. Everything here is declared in `akan.config.ts` or narrowed by an env at boot; none of it is reached
@@ -114,6 +114,58 @@ worker per web-serving replica.
   `AkanServer`, whose graph the gateway never runs; through it the process evaluated 35MB of SSR renderer and
   SQLite driver to spawn children and relay bytes. Keep entrypoint imports at the leaf.
 
+## The Dev Server And Local Runs — `akan start`
+
+- After changing application source code, test the app with `bun run akan start <appName>`; test production build
+  generation with `bun run akan build <appName>`.
+- **`akan start` takes several apps** — `akan start a,b`, `akan start a b`, `akan start all`, or no argument at
+  all for a checkbox that remembers the last pick.
+- **It opens a full-screen view by default, at any app count.** A rail of apps with the processes inside each
+  one — `host` for the dev host, gateway and RSC worker, plus a row per replica the gateway forwards — and the
+  selected one's log beside it. `Tab` walks every row and `1`-`9` jump to that app (the rail shows each app's
+  digit), `↑↓` scroll (shift for a page, `G` back to following), `/` greps, `e` shows stderr only, `c` clears,
+  `y` copies, `Y` copies the log path, `o` opens the browser, `r` restarts that app, `q` quits. Under `--share`,
+  `s` copies the public URL — the selected app's, or every app's from the merged row — and the header carries it
+  ahead of the local one, because the line `--share` printed before the view took the terminal is gone by its
+  first repaint. **`--plain` prints prefixed interleaved lines instead**, and a pipe, a redirect or an unsized
+  terminal downgrades to that on its own.
+- **A supervised session writes `local/apps/<app>/runtime/dev.log`, and that path is how a log gets handed over.**
+  Ink repaints one frame in place, so the full-screen view leaves a bordered screenshot in the scrollback and takes
+  the rest of the session with it — a drag-selection is cleared by the next repaint, and what survives carries
+  borders and lines truncated to the pane. The file is the same output with no ANSI, nothing truncated, and every
+  process of the app in arrival order, including the dev host's own build output, which reaches no other file. The
+  previous session is kept beside it as `dev.prev.log`. Hand somebody — or an agent — the path rather than a paste:
+  it costs one line instead of a transcript, and it can be re-read after a fix. In the view, `y` copies the lines
+  the filters have already narrowed and `Y` copies the path.
+- **How many apps boot at once is the machine's answer, not a constant.** A cold boot is an app's RSS peak (~1.8GB
+  per app, most of it the build worker — the base build, then the SSR registry's), so the default wave is what
+  memory and cores allow — half the memory budget divided by that peak, and one app per four cores — which boots a
+  laptop's apps together and still staggers them inside a small container. The session says which in one line.
+  The next wave starts once an app serves and its boot builds have settled, or 30 seconds after it serves, while
+  the app shows as ready — and `--open` opens it — as soon as it serves. `--concurrency <n>` overrides the wave
+  size, and `AKAN_MEMORY_LIMIT` lowers the budget it derives from.
+- **`--kill` frees the dev ports first** — it resolves each port's listener, walks up to the top of that akan dev
+  tree and signals it, so another checkout's server or a stale orphan on the same port is reclaimed. A holder that
+  is not recognisably an akan process is reported and left alone.
+- **A dev server watches its own app directory and the libs it actually depends on**, transitively, resolved once
+  at boot from the synced manifests — so a save under a lib the app never imports rebuilds and reloads nothing,
+  and neither does a save in a sibling app. An import that makes a new lib a dependency needs a fresh
+  `akan start`, because it needs a `sync` first anyway. Before the first `sync` the manifests do not exist yet and
+  the whole `libs/` container is watched, which is the safe direction.
+- **A built artifact runs from the generated app directory** with the Akan runtime environment variables:
+
+  ```bash
+  cd dist/apps/<appName> && USE_AKANJS_PKGS=true AKAN_PUBLIC_REPO_NAME=<repo> AKAN_PUBLIC_SERVE_DOMAIN="<domain>" \
+    AKAN_PUBLIC_APP_NAME=<appName> AKAN_PUBLIC_ENV=local AKAN_PUBLIC_OPERATION_MODE=local SERVER_MODE=federation \
+    AKAN_PUBLIC_BASE_PATHS=<basePaths> bun main.js
+  ```
+
+- **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.
+
 ## Logging — Records, Request Context And Live Tail
 
 Every `Logger` call builds a `LogRecord` before any text exists: `at`, `level`, OTel `sev`, `name`, `message`,
@@ -152,6 +204,18 @@ normalized to `info` with one warning.
 - **The generated Dockerfile sets `AKAN_LOG_TO_FILE=0`.** A container's writable layer is ephemeral and nothing
   collects a file from it; stdout is the collection path. A deployment that wants the files back sets
   `AKAN_LOG_TO_FILE=1`.
+- **`AKAN_LOG_FORMAT=ndjson` makes the container's stdout one JSON record per line, and the hub owner (gateway or
+  solo replica) its only writer** — every other server process turns its console off and forwards from
+  `AKAN_LOG_STDOUT_LEVEL` (default: the console level); a child's or the RSC worker's crash stack is wrapped as a
+  `raw=true` record instead of breaking the stream. Text stays the default; turn it on in the deployment.
+- **`AKAN_LOG_STREAM_TOKEN` mounts `/_akan/app/logs`** (SSE, `Last-Event-ID` resume, explicit `gap` events);
+  unset, the route does not exist.
+- **`AKAN_LOG_CANONICAL=1|slow`** writes one `ok|error <endpoint> ms= status=` line per call; **`AKAN_LOG_FLIGHT=1`**
+  keeps each call's last 64 sub-level records and promotes them (`flight=true`) only when it failed or ran past
+  `AKAN_LOG_FLIGHT_MS`; an `x-akan-debug` header lowers one request to `trace` — in `local`, or with the
+  `AKAN_LOG_DEBUG_HEADER` secret.
+- **Structured values go in `LogRecord.attrs` via `Logger.emit(...)`**; a key naming a secret is `[redacted]`
+  before the record exists.
 - **Never log per delivered record in anything that delivers records.** The control socket and the hub do not,
   and a subscriber asking for everything is the test.
 
@@ -331,7 +395,7 @@ has none, or none when it has one, is refused, and switching means a reinstall.
 tied to the image's system, code only a process the app never starts loads — and whatever only they pull in; the
 image keeps them, and the server's own bundle must not import them. A package another dependency still installs
 stops the build, naming who needs it. So does a native addon that would not load on a user's computer: no binary
-for the app's OS and CPU, a link outside the system, or a `binding.gyp` its install never compiled. It runs as an API-only edge server on SQLite, on a loopback port the launcher picks — the last session's when
+for the app's OS and CPU, a link outside the system, or a `binding.gyp` its install never compiled. It runs as an API-only edge server in database mode `single` (SQLite), on a loopback port the launcher picks — the last session's when
 it is free, which is not a guarantee, so a provider that needs an exact redirect URI signs in through a cloud
 server's adapter. It refuses a `Host` other than its own, but any program on the computer can still call that port:
 guard its endpoints as a network server's. It runs in one process, so a `main.ts` or an env asking for replicas (`replica`,
@@ -453,6 +517,29 @@ page API is
 hook; `volume` and `filePicker` also come from `akanjs/client/native` itself. A capability the shell
 lacks is added there: an app's own plugin runs as Bun code in the plugin host and cannot add a native shell op.
 
+**A plugin the app or lib owns lives in `native/<id>/`**, the folder named after the plugin id: `native-plugin.json`
+beside its page API (`src/index.ts`, `definePlugin` from `akanjs/client/native`), its desktop part (`src/desktop.ts`,
+`defineDesktopPlugin` from `akanjs/native/desktop`), Kotlin and Swift. Every mobile and desktop target ships it; a
+lib's reach only the apps that depend on it, and the app's own wins an id. Its page API is imported by a `webkit/`
+hook (`../native/<id>/src`) and nothing else; pages and components call the hook, the same way they reach
+`akanjs/client/native`. A plugin throws `AkanNativeError`, the error its bridge carries back to the page, which is
+why `no-throw-raw-error` exempts a root `native/` folder.
+
+**A page's storage and browser APIs follow the shell, not the browser.** A native shell serves the page from
+`app://localhost` on iOS, macOS and Linux, which keeps no cookies: `document.cookie` reads `""` and a write is
+dropped, so the value exists in the browser and vanishes in the app. Web Storage does work in the shells, but it
+bypasses the store akanjs picks per platform (the shell's Preferences in an app) and throws during SSR. So app and lib
+code never touches `document.cookie`, `localStorage` or `sessionStorage` (`no-document-cookie`, `no-web-storage`): it
+uses `getCookie` / `setCookie` / `removeCookie`, `storage`, and `secretStorage` for tokens and credentials, all from
+`akanjs/client`. `setCookie` writes `path=/; SameSite=Lax; Secure`, and an options object overrides only the keys it
+names — pass `sameSite: "none"` only for a cookie a cross-site POST must carry back. Browser APIs an app WebView lacks
+stay in a `webkit/` hook that branches on `isNativeApp()` from `akanjs/client/native`, which is where the app side goes
+too (`no-web-only-api-outside-webkit`, a warning): `navigator.share` / `canShare` (Android's WebView has none),
+`navigator.serviceWorker` and `Notification.requestPermission` / `.permission` (no app page has them),
+`navigator.geolocation` (use `useGeoLocation` from `akanjs/webkit`) and `navigator.vibrate` (iOS has none; use
+`haptics`). They are legal on the web, so the rule does not ban them; a root `native/` folder is out of its scope,
+since a plugin's web part is where those APIs belong.
+
 ## Database Modes — `database` In `akan.config.ts`
 
 | mode | database | cache · queue · pubsub | runs as |

package/guidelines/ssrRule/ssrRule.instruction.md

@@ -38,6 +38,19 @@ A third-party client package and the `ui/<Folder>/index_.tsx` + `lazy()` boundar
 not flagged. Interaction-driven `fetch.*` inside an `onClick` is not flagged either — only mount-time loads are,
 because those are the ones the server could have performed.
 
+## Lint Rules Behind The Boundary
+- `no-async-component-in-ui` (`{apps,libs}/**/ui/**/*.tsx`) — React has no async client component, so a `ui/`
+  component that awaits breaks as soon as a client parent renders it, and the load drops below the route, which
+  could have started it before the first byte. Only a PascalCase binding whose own initializer is `async` is matched,
+  so an async handler inside a synchronous component and `lazy(async () => import(…))` are untouched.
+- `no-init-fetch-in-client` — `fetch.init<Model><Suffix>` and `fetch.get<Model>Init<Suffix>` compose the slice's list
+  and insight queries into the hydration snapshot `Load.Units` / `Load.View` seed the store from. From a route it
+  resolves before the first byte; after hydration it is two extra round-trips for a shell the browser already
+  painted. Load it in the page and pass the result (or the unawaited `x<Model>Init<Suffix>` promise) down as `init`,
+  and reload from the client through the generated `st.do.init<Model><Suffix>()`. The rule is gated on the real
+  `"use client"` directive plus `*.store.ts` and matches by shape (`init` + `Capitalize<refName>` +
+  `Capitalize<suffix>`), so a hand-written `initPayment` is out.
+
 ## Implementation Playbook
 
 **① Wrap the interaction, not the UI.** The smallest useful client component adds one behaviour and renders