@akanjs/cli 3.0.0-alpha.10 → 3.0.0-alpha.100

package/guidelines/cssRule/cssRule.instruction.md

@@ -55,6 +55,13 @@ Screen code is invariant — a plain `<Button variant="primary">` never changes.
 - Switching themes is toggling the `data-theme` attribute. Keep every token defined in both the dark and light blocks.
 - Radius uses `rounded-box` (cards/modals), `rounded-field` (buttons/inputs), `rounded-selector` (toggles/checkboxes).
 
+## Lib-Owned Tokens (`libs/<lib>/ui/tokens.css`)
+- A lib that needs colors of its own — vendor brand colors pinned by someone else's guide (Kakao `#fee500`, Naver `#1ec800`), fixed in-game surfaces — declares them **once** in `libs/<lib>/ui/tokens.css`. Never copy the block into each app's stylesheet.
+- The file is collected automatically: every app whose page graph reaches that lib compiles it, ordered **ahead of** the app's own stylesheets, so the app wins on any variable both declare. There is nothing to import and no sync step to remember; two libs both declaring one variable resolve in lib-name order, so do not rely on that.
+- Declare plain custom properties under `:root`, not a Tailwind `@theme` extension: the color vocabulary is closed per stylesheet, so `bg-kakao` would generate no CSS. Reference them as `bg-[var(--kakao)]` / `text-[var(--kakao-foreground)]`, which `no-arbitrary-color` allows by design (a `var()` reference is not an arbitrary color literal).
+- Theme-following colors still belong to the app: a lib token is for a color that must **not** change with `data-theme`.
+- An `@import` the CSS pipeline cannot resolve fails the build; it is never dropped. A stylesheet under `page/` that no route imports is compiled by nothing and warns at build time.
+
 ## Codegen Rules
 - Do not hardcode hex or raw-palette colors (`bg-red-500`, `#ff0000`); use semantic tokens.
 - Do not put inline color literals in `style={{ }}`; use token classes.

package/guidelines/framework/framework.generate.json

@@ -20,11 +20,12 @@
   ],
   "update": {
     "filePath": "./framework.instruction.md",
-    "contents": ["purpose", "file ownership", "current API patterns", "codegen rules", "validation checklist"],
+    "contents": ["file ownership", "current API patterns", "codegen rules", "theming and UI customization"],
     "rules": [
       "Use current Akan APIs only",
       "Keep output parseable for codegen",
-      "Include ownership boundaries and review checklist"
+      "Include ownership boundaries",
+      "Carry no meta about this document itself — it renders into every workspace's always-loaded AGENTS.md"
     ]
   },
   "page": "apps/akan/page/(docs)/docs/intro/fundamentals.tsx"

package/guidelines/framework/framework.instruction.md

@@ -1,8 +1,5 @@
 # Akan.js Framework Guide
 
-## Purpose
-Use this as the compact framework context for AI codegen. It should explain how Akan turns convention-based files into a full-stack app without teaching every API in one place.
-
 ## 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.
@@ -26,10 +23,5 @@ Use this as the compact framework context for AI codegen. It should explain how
 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.
 - **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.
-
-## Review Checklist
-- The instruction points to current docs pages, not removed docs routes.
-- Generated examples use current Akan builder APIs and scanner-friendly filenames.
-- The output contract tells the model which file paths to return.
-- The guide avoids broad framework essays when a concrete file rule is better.

package/guidelines/mcpRule/mcpRule.generate.json

@@ -0,0 +1,25 @@
+{
+  "title": "MCP Exposure Rule",
+  "description": "How Akan signals reach AI agents over MCP — guard-derived exposure, refusals, prompts, and resources",
+  "group": "core",
+  "codegenPriority": 4,
+  "deprecated": false,
+  "scans": [
+    {
+      "type": "example",
+      "description": "Signal files whose slices and endpoints declare the guards MCP exposure is derived from",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "sample": 4
+    }
+  ],
+  "update": {
+    "filePath": "./mcpRule.instruction.md",
+    "contents": ["exposure rule", "configuration", "declaring endpoints", "refusals and wire behaviour", "prompts"],
+    "rules": [
+      "Use current Akan APIs only",
+      "State the rule before the reason, and keep the reason to one clause",
+      "Name the env spelling beside every option field",
+      "Keep it workspace-neutral — no app or repo names"
+    ]
+  }
+}

package/guidelines/mcpRule/mcpRule.instruction.md

@@ -0,0 +1,217 @@
+# Akan MCP Exposure Guideline
+
+## Purpose
+Use this when writing a `*.signal.ts`, configuring `option.setMcp(...)`, or debugging a tool an agent cannot see.
+The always-loaded convention set carries the short version; this is the full contract.
+
+## Exposure Rule
+
+Every signal is served to AI agents as an MCP server on `POST /mcp`. **`/mcp` is mounted by default and exposure
+follows an endpoint's guards — there is no per-endpoint opt-in, and nothing to write in a signal file.** An endpoint
+that declares a real guard is published; one that declares none is refused, and so is a mutation whose only guard is
+`Public`. `AKAN_MCP=false` takes the whole surface off. The reasoning is that the guards are already the
+authorization decision and `filterForAccount` re-reads them per caller on every listing, so a second per-endpoint
+switch says nothing the guards do not — while guaranteeing that every endpoint added later is invisible to agents
+until somebody remembers it.
+
+## Keeping An Endpoint Off The Shelf — `mcp: false`
+
+Guards answer "may an agent call this". They do not answer "does this belong on a shelf", and those are different
+questions: a step of a UI-driven state machine (`requestPhoneCodeForSignin`, `setPasswordInPrepareUser`) is
+perfectly guarded, perfectly callable, and a model would only ever call it by mistake. **`mcp: false` is that
+second answer, and it is an opt-*out*: everything still publishes by default, so an endpoint added later is
+visible without anyone remembering it.**
+
+```ts
+requestPhoneCodeForSignin: mutation(Boolean, { guards: [Every], mcp: false }),
+inTodo: init({ guards: [SignedIn], mcp: false }),           // the slice's list and insight together
+export class FileSlice extends slice(srv.file, {
+  guards: { root: Admin, get: SignedIn, cru: SignedIn },
+  mcp: { cru: false },                                       // reads yes, generated writes no
+}) {}
+```
+
+- **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.
+- **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
+  their own `mcp` beside their own `guards`. The bare `mcp: false` is every key at once, still within that scope.
+- **`mcp: true` is the default and is a no-op**; write it only to say out loud that an entry is deliberately on
+  the shelf. It does not override a shape refusal (an `Any` return stays refused) and it cannot publish something
+  the guard rules keep out.
+- **Reach for it by cost, not by taste.** Every entry inlines the schema of every model it mentions, so a plain
+  21-field model with one named slice costs 12.6KB across its eight entries. `mcp: { cru: false }` on that model
+  takes it to 4.7KB — the write entries carry both the input *and* the full model, and are 63% of it.
+
+## Configuration
+Settings live in the app's `lib/option.ts` — `option.setMcp({ … })`, taking `enabled`, `readOnly`, `path`,
+`version`, `instructions`, `allowedOrigins`, `pageSize`, `language`, `legacyTextBlock`, and `auth`. **Not `main.ts`**: the gateway
+there only spawns children, and `option.ts` is the app-authored file `server.ts` already hands to the process that
+mounts `/mcp`. Every lib's option is read in mount order with the app's last, so an app tightens what a library
+declared without restating it. Each field also has an env spelling (`AKAN_MCP`, `AKAN_MCP_READONLY`,
+`AKAN_MCP_PATH`, `AKAN_MCP_VERSION`, `AKAN_MCP_INSTRUCTIONS`, `AKAN_MCP_ALLOWED_ORIGINS`, `AKAN_MCP_PAGE_SIZE`,
+`AKAN_MCP_LANGUAGE`, `AKAN_MCP_LEGACY_TEXT`, `AKAN_MCP_AUTH_SERVERS`, `AKAN_MCP_SCOPES`, `AKAN_MCP_RESOURCE`) for a
+deployment that configures what the source does not, which the option overrides.
+The two booleans answer to `AKAN_PUBLIC_MCP` / `AKAN_PUBLIC_MCP_READONLY` too, the same pairing `AKAN_OPENAPI`
+has, and a value written in code wins over the env of the same name — an explicit `undefined` is not a value.
+`AKAN_MCP_PATH` is normalized to a leading `/`, because the route key and the OAuth metadata path are both built by
+concatenation.
+
+## Declaring Endpoints
+```typescript
+// apps/<app>/lib/option.ts
+export const option = new AkanOption<ModulesOptions>().setMcp({
+  instructions: "Domain tools for this app. Start from taskInTodo.",
+  language: "en",
+});
+```
+
+```typescript
+// <model>.signal.ts — every one of these is an MCP tool or prompt, with no `mcp:` option anywhere
+export class TaskSlice extends slice(
+  srv.task,
+  { guards: { root: Admin, get: SignedIn, cru: SignedIn } },
+  (init) => ({
+    // its own guards: the map above reaches base CRUD and the root slice, never a named slice — so a named slice
+    // that names none is refused rather than published, which is the one shape to watch for.
+    inTodo: init({ guards: [SignedIn] }).exec(function () {
+      return this.taskService.queryByStatuses(["todo"]);
+    }),
+  }),
+) {}
+
+export class TaskEndpoint extends endpoint(srv.task, ({ mutation, prompt }) => ({
+  startTask: mutation(cnst.Task, { guards: [SignedIn] })
+    .param("taskId", ID)
+    .exec(async function (taskId) {
+      return await this.taskService.startTask(taskId);
+    }),
+  reviewTask: prompt({ guards: [SignedIn] })
+    .param("taskId", ID)
+    .exec(async function (taskId) {
+      const task = await this.taskService.getTask(taskId);
+      return [Msg.user(`Review this task and suggest next steps.`), Msg.resource(`akan://task/${taskId}`, task)];
+    }),
+})) {}
+```
+
+## Refusals And Wire Behaviour
+- **`mcp: false` is read first**, because it is the one answer nobody had to derive — somebody stated it. Its
+  reason says "HTTP still serves it", because that is the sentence that stops the next reader treating it as a lock.
+- **The refusals are fail-closed**: **an endpoint that declares no `guards` at all** (nobody decided who may reach
+  it), **a mutation with no real `guards`** (`[Public]` is having none, spelled out — it answers true
+  unconditionally), `pubsub` and `message` (their internal args read a socket an MCP request does not have), an
+  `Any` or `Upload` return, a file upload, **an argument typed `Any` that must be filled**, and the generated
+  **`light<Model>` read** — it returns the same document as `<Model>` under the same guards, in a shape trimmed
+  for a page's payload, so publishing both put two entries per model in a listing an agent pays for every turn
+  and gave it nothing but the word "light" to choose between them.
+  A `prompt` refuses two more, because its `arguments` is one string per name with no schema beside it: a **list
+  argument**, which could never carry a second value, and **any `Any` argument** — a tool leaves that out of its
+  schema, and a prompt has no schema to leave it out of.
+- **The boot log sizes the catalogue and says which signals it went to** — `MCP catalogue: tools=48 … · listing
+  214KB` and `MCP catalogue cost: user 27/71KB · file 6/22KB · …`, heaviest first. Read it before narrowing
+  anything: the number is nobody's intuition, because MCP has no shared component section and forbids a `$ref`
+  across entries, so **every entry inlines the full schema of every model it mentions** and a listing is re-sent
+  whole to every agent that connects, before its first turn. Past 100KB it says so as a `warn`.
+- **Every refusal is named in the boot log**: one `warn` per endpoint plus a `MCP catalogue: tools=… prompts=…`
+  count. Read that line first when a tool you expected is missing — and it is the *only* place the answer exists,
+  because there is no absent opt-in to notice. The API explorer badges the same rule per endpoint (`MCP` /
+  `MCP refused`), from the same shared implementation the catalogue runs.
+- **An `Any` argument is left out of the published schema** rather than described as `{}` — it tells a model
+  nothing — and a value sent for one is refused by name, so the endpoint reads it as omitted. That is what happens
+  to the root list's raw `query` descriptor: read as sent, it would be an arbitrary filter over every model you
+  publish. Declare a named filter slice when an agent should narrow a list.
+- **A nullable model return publishes no `outputSchema`**, and its empty answer ships as the text `null` with no
+  `structuredContent`. That field is an object by definition, so `null` cannot ride in it any more than an array
+  can — a list is wrapped as `{ items: … }` for the same reason — and a declared schema obliges every result to
+  match it, so a client SDK throws on the first call that finds nothing. A nullable *list* keeps its schema, and a
+  scalar return has no structured half at all: it ships as the value itself, not as JSON.
+- **An `outputSchema` names no `hidden`, `secret`, or `visual` field.** Every response has the first two stripped,
+  so publishing them promises a property no answer can carry — and on a model like `user` the names are the leak.
+  Your *input* schema keeps all three: they are legal to send, and the same model describes a request body.
+- **A `field.visual` is stripped from every MCP result.** It is the marker for a field the page renders and no
+  question is answered from — a blur placeholder, a rendered HTML body — and it is cost rather than secrecy, so
+  nothing is refused over one. The strip happens in the MCP dispatcher rather than in `resolveReturn`, which every
+  ordinary HTTP response also passes through: the whole point is that a browser still receives it. That is also why
+  the readable schema drops it — a non-optional visual field would otherwise be listed `required` and a validating
+  client would refuse a result that correctly omits it.
+- **A structured result ships twice by default**, once as `structuredContent` and once as the same JSON in the text
+  block, which is what the spec asks of a server for clients predating the structured field. It is also a flat
+  doubling of what every model-returning tool costs a model. `option.setMcp({ legacyTextBlock: false })` — or
+  `AKAN_MCP_LEGACY_TEXT=false` — leaves a one-line pointer in the text block instead, for a deployment whose
+  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.
+- A refused endpoint answers the *same* "unknown tool" as one that does not exist. Never make that
+  message more helpful — the difference is what enumerates your private surface. A guard's refusal is generalized
+  the same way: the caller reads `You are not permitted to perform this action.`, never `Access denied by guard:
+  Admin`, which names your authorization structure to the one caller barred from it. A domain `Err` resolves
+  through the dictionary first and keeps its own words.
+- The `readOnly` / `destructive` / `idempotent` hints a client renders are derived from the endpoint type and key
+  and are not configurable. Clients are told to distrust hints; they are never a gate.
+- **`AKAN_MCP_READONLY=true` is the read-only-deployment valve, not the exposure switch.** It drops every mutation
+  whatever it declared, and reports each one in the boot log like any other refusal.
+- OAuth resource metadata is published at `/.well-known/oauth-protected-resource` (and at that path plus the mount
+  path, the spelling most clients try first). `AKAN_MCP_AUTH_SERVERS`, `AKAN_MCP_SCOPES`, and `AKAN_MCP_RESOURCE`
+  configure it; `insufficient_scope` is enforced only once `AKAN_MCP_SCOPES` is set. A token carrying no `aud` at
+  all is refused once `AKAN_MCP_AUTH_SERVERS` names an issuer — that issuer mints tokens for its other resources
+  too — and accepted while none is named, because a first-party Akan token is bound by app and environment.
+- **The boot log names every published entry with no dictionary `.desc()`.** An agent picks a tool by its
+  description, so a missing one is a broken tool. What the framework generates has no text of its own and borrows
+  the model's: the generated list reads the `.of()` label, and the base CRUD tools append the model's `.desc()` to
+  their generated `Get X`. Write that model `.desc()` — it is the only text those entries can carry. There is no
+  `akan quality scan` rule for this any more: a source scanner found the exposure only as an `mcp:` literal, and
+  with exposure derived from the guards the resolved catalogue is the only place that can answer.
+- A browser-hosted client needs `allowedOrigins` **and** the CORS answer the server sends back for those origins.
+  Every other MCP client sends no `Origin` at all, and the one that does is matched against the forwarded host so
+  a proxy does not turn each call into a 403 — which is only as trustworthy as an edge that *overwrites* that
+  header. `AKAN_MCP_RESOURCE` pins the resource identifier where you cannot guarantee it.
+- **A `resources/read` uri that does not decode** — a stray `%` — is `Unknown resource`, not a server failure.
+- **A caller's own mistake is reported as one** and never as a server failure: an argument that is missing,
+  unparseable 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`.
+  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".
+- **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
+  are derived from the catalogue, so a server with no prompts does not advertise `prompts`.
+- **An expired or wrongly-audienced bearer token is refused up front**, so an agent is told to authenticate rather
+  than that the tool does not exist. Its **signature is not checked** — that needs your app's own secret — so a
+  token signed wrong, like an opaque one, still degrades to an anonymous caller.
+- **Resource URIs**: `akan://<model>/{id}`, `akan://<model>/list` for the model's own list, and
+  `akan://<model>/list/<sliceKey>` for a slice's. The root list takes no third segment on purpose — any token
+  there is one a slice could also be named. **Those three are the whole set**, so only the generated reads that
+  publish are addressable: a custom endpoint keeps its tool and gets no resource template, and the refused
+  `light<Model>` read has no address either.
+- **The catalogue is one language**, `en` unless `language` says otherwise: it is built once at boot and cached by
+  clients, so there is no `Accept-Language` negotiation.
+
+## `prompt()`
+**`prompt()`** is invoked by the *user* — a client renders it as a slash command — not chosen by the model. `exec`
+returns `PromptMessage[]`, or a bare string that is wrapped into one user message; build them with `Msg.user` /
+`Msg.assistant` / `Msg.link` / `Msg.resource` / `Msg.image` / `Msg.imageOf`. It takes `.param()` and `.search()`
+only, because `prompts/get` sends a flat string map. **An embedded payload is masked by the model you name** —
+`Msg.resource(uri, task, { model: cnst.LightTask })`, or `Msg.mask(cnst.LightTask, task)` for one piece of an
+assembly. Taking the model as an argument is what makes a `{ ...doc }` spread maskable, since that and `toJSON()`
+arrive with the class already gone; a value with no model named whose `hidden`/`secret` fields are populated is
+**refused**, one level into a plain object too. **A `prompt` is also mounted as a
+plain HTTP `GET` whether or not you enabled MCP**, because that route is what lets a web UI preview one — and it
+is in your OpenAPI document like any other `GET`, answering the one fixed `PromptMessage[]` shape. MCP exposure
+gates the catalogue, not the surface, so guard it
+like any other read — and a prompt declaring no
+`guards` at all is named in the boot log, while an explicit `[Public]` is a decision and stays quiet. Every `Msg` builder takes
+optional `annotations` last (`audience`, `priority` 0..1, `lastModified`) — give the instruction a high `priority`
+and its attachments a low one, or a client with a full window drops blocks by position and keeps the attachment
+over the ask.
+
+## Progress Reporting
+**`McpProgress.report(n, { total, message })`** reports progress from anywhere inside a call, a service or adapter
+frames down included, and is a no-op when nobody is streaming — so the same code runs unchanged over HTTP, a
+websocket, and in tests. `McpProgress.streaming` says whether anyone is reading, for a report whose message
+costs something to assemble.

package/guidelines/modelStore/modelStore.instruction.md

@@ -21,6 +21,18 @@ Generate client state coordination for a module. Store connects generated fetch
 - Do not perform persistence logic in React components when a store action can own it.
 - Do not call private or internal signal operations from UI state.
 
+## Form Draft Recovery
+- `<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`
+  and `jti` removed. **Do not put a claim that changes on every issue into the JWT.** One would rotate the key on
+  every silent token refresh, and the symptom is a form that never recovers anything: the draft was written under
+  a key nothing looks for again, and it lingers until the seven-day sweep.
+- `field.secret` and `field.hidden` values are never written to a draft, so they come back empty. That is the
+  intended trade — a user retypes a password — and is not something to work around.
+- A model whose form holds a large `field.visual` body can pass the 256KB per-draft cap, and a draft over it is
+  dropped with a warning rather than truncated.
+
 ## Review Checklist
 - The instruction points to current docs pages, not removed docs routes.
 - Generated examples use current Akan builder APIs and scanner-friendly filenames.

package/guidelines/modelTemplate/modelTemplate.instruction.md

@@ -17,6 +17,11 @@ Generate form and interaction fragments bound to store form state and generated
 - Do not call service or signal directly from inputs.
 - Do not duplicate validation that belongs in constants or service invariants.
 - Do not build page layout here when Zone should compose it.
+- Do not persist typed values yourself. The edit shells (`Load.Edit`, `Model.EditModal`, `Model.New`) save the
+  whole `<model>Form` and recover it on the next open; a Template that reaches for `localStorage` or a per-field
+  cache saves a fragment of a form and restores it over whatever the server just returned.
+- The `Field.*` `cache` prop and the `Input` `cacheKey` prop are deprecated and store nothing. Turn recovery off
+  with `draft={false}` on the shell, or name a scope with `draft="<scope>"`; do not reintroduce a field-level one.
 
 ## Review Checklist
 - The instruction points to current docs pages, not removed docs routes.

package/guidelines/queryRule/queryRule.generate.json

@@ -0,0 +1,31 @@
+{
+  "title": "Query Rule",
+  "description": "Akan data access — filters, slices and hydration, full-text search, and cascade removal",
+  "group": "core",
+  "codegenPriority": 4,
+  "deprecated": false,
+  "scans": [
+    {
+      "type": "example",
+      "description": "Filter and model declarations that drive the generated query surface",
+      "path": "{apps,libs}/*/lib/*/*.document.ts",
+      "sample": 4
+    },
+    {
+      "type": "example",
+      "description": "Slice declarations that expose a query to a client store",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "sample": 4
+    }
+  ],
+  "update": {
+    "filePath": "./queryRule.instruction.md",
+    "contents": ["slices and hydration", "generated filter methods", "text search", "cascade removal"],
+    "rules": [
+      "Use current Akan APIs only",
+      "State the rule and the reason it exists, never restate a type signature",
+      "Say which generated methods fire hooks and which do not",
+      "Keep it workspace-neutral — no app or repo names"
+    ]
+  }
+}

package/guidelines/queryRule/queryRule.instruction.md

@@ -0,0 +1,175 @@
+# 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.
+
+## Slices, Queries, and Hydration
+
+- **The root slice (`""`, generated by `slice()`) takes `queryKey` and `args`, not a query.** `initX("byOwner",
+  [ownerId])` names one of the model's own filters and passes that filter's args; no key at all is the `any`
+  filter every model carries. A raw query descriptor let a caller compose a query the model never declared, and
+  could not survive the query string at all — `String(value)` sends `[object Object]`. Args are parsed by the type
+  the filter declared, a missing required one is refused, and args past the declared ones are dropped
+  (`resolveFilterQuery`, `pkgs/akanjs/document/filterMeta.ts`). It is an admin API: `root:` is always `Admin`.
+- **Give an id filter arg a `ref` and the admin panel stops asking for hex.** `filter().arg("ownerId", ID, { ref:
+  "user" })` names the model the id points at; the arg then renders a picker that runs the same query maker against
+  that model's own filters, so a ref of a ref keeps nesting. The picker holds its rows in local state rather than the
+  ref model's store — that store is a singleton, and loading into it would overwrite whatever listing of the same
+  model is already on screen. `ref` is the only UI hint a filter arg carries; there is no render callback, because a
+  function cannot cross to the client.
+- **A summary counter names the listing it counts, on the field itself.** `field(Int).meta(getQueryMeta("user")
+  .query("byStatuses").args([["prepare"]]))` is what makes the dashboard tile clickable: clicking it applies that
+  filter to the listing in place — one request, no navigation — and fills the arg controls under the toolbar, so
+  the filter is visible and editable rather than opaque. `args` may be a thunk (`() => [dayjs().subtract(1,
+  "hour")]`), read at the click so a relative time is current. A meta naming a different model counts a different
+  listing, so its tile stays inert here. `AdminPanel`'s `queryMap` still overrides per column, and is now only for
+  a column whose field cannot declare one.
+- **A picker row is labelled by `labelOf`, which reads `Light<Model>.label()` first.** Then the field carrying
+  `text: "title"`, then `title` / `name`, with the id as the floor. Write the method on the Light class — that is
+  where display logic belongs, and the same label is what `Load.Units` and the in-page agent's screen scope show.
+  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`).
+- **A slice list is either one window or an accumulated one, and the store says which.** `setPageOf<Model>` swaps
+  the window and `pageOf<Model>` names it; `loadMoreOf<Model>()` appends the rows *after* the ones already loaded
+  and takes no page number, because in an accumulated list no page number names anything. It skips by
+  `<model>List.length` rather than by `page * limit`, which is what keeps the offset from drifting from what is on
+  screen: a live insertion at the front moves the server's baseline by one, so a page number asks for rows the
+  list already shows. It also leaves `pageOf<Model>` at 1 — live placement is refused anywhere but the first page,
+  so paging by number used to switch live sync off permanently on the first "more", silently. `isCumulativeOf<Model>`
+  is the mode, and it is what stops a live insertion from truncating an accumulated list back to one page's worth.
+- **"Is there more" is `hasMoreOf<Model>`, never `count > page * limit`.** It is set from the length of the batch
+  the server just returned, so it survives `{ insight: false }` — which makes no count query at all — and cannot
+  drift from the count a live event moved. `loadMoreOf<Model>()` is a no-op once it is false, and `Load.Units`
+  draws no infinite-scroll sentinel.
+- Generated list accessors like `listBy(...)` return `Promise<Doc[]>`. For a chainable builder (`.sort().skip().limit().select()`) use the model facade's `findMany`/`findOne` (`FindManyChain`, `pkgs/akanjs/document/into.ts`).
+- **Hydrated vs raw:** server queries return hydrated `cnst.<Model>` instances (with `set`/`save`/`refresh`); client fetch results are raw `GetStateObject` plain data (functions stripped, `pkgs/akanjs/base/types.ts`).
+- Every filter generates fourteen methods: `list` · `listIds` · `find` · `findId` · `pick` · `pickId` · `exists` ·
+  `count` · `insight` · `query` · **`remove`** · **`removeOne`** · **`update`** · **`updateOne`**. The last four are
+  query-level writes — one atomic UPDATE, **no hooks**, and therefore no `_postRemove` and no cascade. Use them on a
+  model that carries no removal side effect; otherwise remove documents one at a time.
+- **`update<Filter>` / `updateOne<Filter>` are chains, not calls:** `await updateInRoot(rootId).set({ status:
+  "archived" })`. The patch cannot trail the filter args — a filter's own args may be optional and no tuple type
+  puts a required element after those — so it lands on a terminal `.set()`, mirroring the `UPDATE … SET …` it
+  compiles to. Building the chain touches nothing; only `.set()` runs a query.
+- `removeOne` / `updateOne` hit the **newest** match — the subquery they compile to is ordered `createdAt` descending
+  and there is no way to change that. They also report only counts, never which row they touched, so they are for
+  "there is at most one of these", not for claiming the next item off a queue. Pass a query that matches one row.
+- **A filter may not be keyed after its own model.** Filter methods are assigned after CRUD, so a filter `chat` on
+  model `chat` would silently swap the single-document `removeChat`/`updateChat` for a hookless query-level one. It
+  throws at boot instead (`assertFilterFitsCrud`).
+- **"Has no value" is `q.empty`, never `q.missing`.** The three absence operators are distinct: `q.exists` is the
+  key being present, `q.missing` is the key being *absent from the stored JSON*, and `q.empty` is either — absent,
+  or present and null. An optional field is written both ways over its life: an insert that omits it leaves the key
+  out, while a document read back and saved carries the explicit `null` that the read materialized. So `q.missing`
+  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.
+
+## 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) =>
+  q.search(text, { prefix: true }))`. The generated `listBySearch` / `countBySearch` / `queryBySearch` /
+  `insightBySearch` come for free — you do **not** need a slice to make search usable.
+- **Only add a search slice when the model's data is safe to enumerate.** A filter is server-side; a slice is a
+  client-callable endpoint, so on a model whose slice `get:` is `Public` a search slice hands anyone a way to walk the
+  table. Leave that decision to the mounting app.
+- `q.search()` compiles to a JOIN, not a WHERE fragment, so it **must sit at an AND position**. Nesting it under
+  `q.any()` or `q.not()` throws, and it is rejected in `updateOneByQuery` / `updateManyByQuery` — a query-level write
+  takes no join, so ignoring the node would silently widen the write to every other matching row.
+- Blank or whitespace-only input matches **nothing**. Never "fix" that into a passthrough: a passthrough turns a
+  search endpoint into a full listing.
+- Order by relevance with the built-in `relevance` sort key. It is an empty sort map, which the store reads as
+  "unspecified": score order when a search join is present, `createdAt` descending otherwise. That fallback is the
+  compiler's own, not a model-defined default — redefining `latest` on the model does not change it.
+- **A slice endpoint never reaches "unspecified".** The resolver fills `latest` before the query is built, so a
+  client asking for the score order has to name `relevance`; leaving `sort` off gets `latest`, not relevance.
+- Scope a search with `columns` (`q.search(text, { columns: ["title"] })`) and re-weight with `weights`, a tuple of
+  finite numbers positional over `["title", "desc", "tag", "filter"]`.
+
+
+## Text Search Fields — the `text` role
+
+- A field joins the full-text index by declaring one of five roles: `field(String, { text: "title" })`, and likewise
+  `"desc"`, `"tag"`, `"thumb"`, `"filter"`. Nothing else opts a field in, and there is no per-model switch.
+- Pick the role by what the value *is*, because `bm25` weights them positionally (`title` 10, `tag` 3, `desc` 1,
+  `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.
+- **`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
+  role, or leave the field unmasked. Do not work around either. The throw also covers a `text` field *underneath*
+  one of those — a scalar's own field is reachable through its parent, so `f.secret(Noti)` where `Noti.label`
+  carries a role is rejected at the parent, not silently indexed; that one is only reachable at runtime, since the
+  pairing spans two files.
+- The role works on a relation too (`image: field(File, { text: "thumb" })`) and on an array (`playing: field([String],
+  { text: "tag" })`); an array of objects indexes by leaf key, including an array leaf (`works[*].tags`). A field
+  inside a `Map` indexes nothing: there is no fixed path to extract it from.
+- Declaring roles is all the wiring there is. Mirror rows are maintained by SQL triggers — not document hooks —
+  because `updateOneByQuery` and friends fire no hooks, and most searchable-field mutations go through exactly that
+  path.
+- Search runs on sqlite/libsql only. `q.search()` against Postgres throws, loudly, rather than returning every row.
+- `AKAN_SEARCH_ENABLED=0` switches the index off process-wide; unset means on. It never deletes mirror data, and
+  re-enabling reconciles every ref. **Give every process the same value** — a process cannot drop triggers for models
+  it does not mount, so a mixed fleet leaves stale triggers behind.
+- The tokenizer is `AKAN_SEARCH_TOKENIZER` (or `database.search.tokenizer`, which wins), defaulting to
+  `unicode61 remove_diacritics 2`. Changing it rebuilds the index from the mirror on the next boot — the model
+  tables are never re-read — so it is a safe knob, unlike a `text` role change, which re-reads every row. The
+  rebuild takes no cross-process claim, so a fleet restarted at once repeats it in every process; stagger the
+  restart when the mirror is large.
+
+## Cascade Remove — the `cascade` option
+
+**The value names the direction, and getting it wrong is a data loss.** The two actions can sit on the same field
+shape, so `cascade` never means "related" — it means one of exactly these:
+
+- `removeRef` — *when I am removed, remove what this field points at.* Declared on the relation the owner holds:
+  `image: field(File, { cascade: "removeRef" })`, arrays included. Only a relation accepts it; a primitive, a bare
+  `ID`, and a scalar each fail the class build.
+- `removeWith` — *when what this field points at is removed, remove me.* Declared on the child's own reference to
+  its owner, so the owner never learns about its children and a lib model can be extended by an app's. Three forms:
+  a relation (`field(AgentSession, { cascade: "removeWith" })`), an id with `ref`, or a polymorphic id with
+  `refPath`. An array, a Map, `ref` together with `refPath`, and a field naming no owner each fail the class build.
+- **A `refPath` must name an `enumOf` field** — a free-form owner type is unknowable at build time, so every
+  model's removal would have to sweep the polymorphic table on the chance it is the owner.
+- **`polymorphic: "any"` buys that sweep on purpose**, for the one shape an enum cannot express: a child whose
+  owner is any model in the app, named by a free-form `String` holding the owner's refName.
+
+  ```ts
+  parent: field(ID, { refPath: "parentType", cascade: "removeWith", polymorphic: "any" }),
+  parentType: field(String),   // holds the owner's refName
+  ```
+
+  The lookup itself is cheap — the declaration auto-creates the same `{ removedAt, typeKey, fk }` index, so a
+  removal that owns nothing is one index probe returning zero rows, not a scan. **The price is bulk: one wildcard
+  edge anywhere turns every cascade in the app back to one document at a time**, because a query-level removal of
+  *any* model would be a removal whose wildcard children were never looked for. The boot log says so in one
+  `info` line naming the edges — that line is the answer to "why does this app remove everything per document".
+  The opt-in is what keeps an app that declared none on the fast path.
+
+  Refused at the class build: `polymorphic: "any"` on a `refPath` that already names an `enumOf` (the enum names
+  the candidates and indexes better — keep one), a `typeKey` that is not a `String` (the sweep matches a refName
+  against that column, and a column that cannot hold one silently finds nothing), and the option anywhere other
+  than a `cascade: "removeWith"` field with a `refPath`. A wildcard owner is also exempt from the mount check
+  that a monomorphic owner fails at boot — it names no module to mount.
+- **A cascade goes through the target's service, never its model** — that path is what runs the target's
+  `_postRemove`, where a module puts the side effect the removal has to carry.
+- **Bulk is decided at boot, per target model, for both directions.** A target with no `remove` schema hook, no
+  `_pre`/`_postRemove`, no cascade of its own, and no children takes one `removeManyByQuery`. Adding a
+  `_postRemove` silently flips it back to one document at a time — the boot log is the only place that shows.
+- **The plan is sealed after every service is live**, so a `listenPost("remove")` registered in `onInit` counts,
+  and an unmounted `removeRef` target or `removeWith` owner fails the boot rather than the first removal. An
+  unmounted `refPath` candidate only warns, since that list spans optional modules by design.
+- **Nothing checks whether another document still references the same target.** `File` in particular is deduped
+  by `origin`, so two parents can share one row; `removeRef` claims the field owns its target exclusively.
+- Removal is soft (`removedAt`), but the storage delete a `_postRemove` performs is not — a cascade is not
+  restorable, and reviving the owner does not revive what went with it.
+- A `removeWith` declaration **auto-creates its index** (`{ removedAt, fk }`, or `{ removedAt, typeKey, fk }` when
+  polymorphic); every non-base field lives in the `_doc` JSON column, so the lookup would otherwise scan the table.
+- **Query-level removes fire no hooks and therefore no cascade** — `removeManyByQuery` / `updateManyByQuery`, the
+  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. Cycles are cut by a
+  visited set carried down the whole chain, with a depth cap of 16.
+

package/guidelines/runtimeRule/runtimeRule.generate.json

@@ -0,0 +1,25 @@
+{
+  "title": "Runtime Rule",
+  "description": "Akan build and runtime surfaces — web/csr toggles, the gateway/solo process model, logging, the generated image, and shipped assets",
+  "group": "core",
+  "codegenPriority": 4,
+  "deprecated": false,
+  "scans": [
+    {
+      "type": "example",
+      "description": "App and lib runtime declarations",
+      "path": "{apps,libs}/*/akan.config.ts",
+      "sample": 4
+    }
+  ],
+  "update": {
+    "filePath": "./runtimeRule.instruction.md",
+    "contents": ["web surface toggles", "process model", "logging and live tail", "generated image", "shipped assets"],
+    "rules": [
+      "Use current Akan APIs only",
+      "State the rule and the reason it exists, never restate a type signature",
+      "Name the env that narrows a build-time declaration wherever one exists",
+      "Keep it workspace-neutral — no app or repo names"
+    ]
+  }
+}