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

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,35 @@
+{
+  "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",
+      "rolling out to an app",
+      "choosing what to open",
+      "writing instructions",
+      "verifying an app"
+    ],
+    "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,366 @@
+# Akan MCP Exposure Guideline
+
+## Purpose
+Use this when writing a `*.signal.ts`, configuring `option.setMcp(...)`, debugging a tool an agent cannot see, or
+opening an app's service to agents end to end — the rollout checklist and the exposure design rules are at the end.
+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. Every 401 and 403 is generalized
+  the same way, the framework's `Access denied by guard: Admin` and an app's `No authentication with roles: admin`
+  alike: the caller reads `You are not permitted to perform this action.`, because either sentence names your
+  authorization structure to the one caller barred from it. A domain `Err` at any other status resolves through
+  the dictionary and keeps its own words, placeholders filled.
+- 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). `auth.authorizationServers` / `AKAN_MCP_AUTH_SERVERS`,
+  `auth.scopes` / `AKAN_MCP_SCOPES`, `auth.resource` / `AKAN_MCP_RESOURCE` and `auth.verify` configure it;
+  `insufficient_scope` is enforced only once scopes are declared. Naming an issuer changes three things at once: a
+  request with no credential is answered 401 from `initialize` on (an MCP client starts its OAuth flow on nothing
+  else), a token carrying no `aud` is refused (that issuer mints for its other resources too), and the challenge
+  carries no `error` code (RFC 6750 §3.1 reserves it for a credential that was presented). A server naming no
+  issuer keeps anonymous access and accepts a first-party token, which is bound by app and environment instead.
+- **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, wrongly-audienced or unverifiable bearer token is refused up front**, so an agent is told to
+  authenticate rather than that the tool does not exist. The signature is checked through `auth.verify`, which the
+  module that mints the tokens supplies (`libs/shared` does, from the app's signing secret); without a verifier the
+  claims are read unverified and a token signed wrong, like an opaque one, degrades to an anonymous caller.
+- **`/mcp` reads the `Authorization` header and nothing else.** The `cookie` header is deleted from the request
+  before the account middleware runs, so a same-site page cannot drive `tools/call` on the visitor's ambient session
+  — the request class `CrossSiteGuard` shields every mutation from, which this route never passes through.
+- **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.
+
+## Authentication — The Authorization Server Is The Same Process
+
+`libs/shared/lib/_oauth` is an OAuth 2.1 authorization server (RFC 8414 metadata, PKCE `S256` only, RFC 7591
+registration, Client ID Metadata Documents, RFC 9207 `iss`) served by the app that serves `/mcp`. Its `option.ts`
+names the issuer and hands `McpAuth` a verifier, so mounting the lib is all an app does; the protocol engine it
+delegates to lives in `akanjs/server` (`OAuthAuthorize`, `OAuthToken`, `OAuthRegistration`, `OAuthClientIdMetadata`,
+`OAuthPkce`, `OAuthRedirect`, `OAuthMetadata`, `OAuthErrors`) and is unit-tested without a container.
+
+- **Endpoints, at the origin's root:** `GET /.well-known/oauth-authorization-server`, `GET /oauth/authorize`,
+  `POST /oauth/token` (form-encoded), `POST /oauth/register`. The consent step is `libs/shared/page/oauth/consent`
+  — a server-rendered page whose two forms post to `/api/approveOAuthConsent/<requestId>` and
+  `/api/denyOAuthConsent/<requestId>` and follow the 302 back to the client. All of it is `mcp: false`.
+- **The flow:** `POST /mcp` with no token → 401 with `resource_metadata` → the client reads the PRM, then the AS
+  metadata, registers (or uses a pre-registered / URL `client_id`), opens `/oauth/authorize` in a browser → the
+  server parks the request and redirects to the consent page (via `signinPath?redirect=` when anonymous) → the user
+  allows → `redirect_uri?code&state&iss` → the client posts the code and its PKCE verifier to `/oauth/token` → an
+  access token (1h, `aud` = the MCP resource, `iss`, `client_id`, `sub`, and the account's `self`/`me`) plus a
+  rotating refresh token (30d; reuse revokes the family). The token is the app's own access JWT, so
+  `AccountMiddleware` and every guard read it exactly as a browser session; nothing is scoped.
+- **Invariants:** an authorization request lives ten minutes, binds to the first signed-in account that opens it,
+  and is decided once; a code lives sixty seconds and is consumed on first exchange even if that exchange fails; a
+  redirect URI must be registered and match exactly, loopback ports excepted (RFC 8252 §7.3); a refresh token is
+  bound to the client it was issued to. A `client_id` that is an HTTPS URL with a path is fetched as a metadata
+  document, never from the server's own network.
+- **Per-app configuration** goes in `env.server.*` under `oauth`: `consentPath` and `signinPath` (with the basePath
+  when the app has one — `/office/oauth/consent`), `clients` (pre-registered, with an optional `clientSecret`),
+  `dynamicRegistration` (on by default: Claude Code and claude.ai register themselves), `allowedRedirectSchemes`
+  (`["cursor"]` by default, for Cursor's desktop callback), `accessTokenSeconds` (3600), `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.
+- **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
+  `https://claude.ai/api/mcp/auth_callback`). Cursor — the URL alone (DCR with a `cursor://` redirect), or a
+  pre-registered client in `mcp.json` `auth` with `http://localhost:8787/callback` /
+  `https://www.cursor.com/agents/mcp/oauth/callback` registered. A first-party browser token no longer opens `/mcp`
+  once the issuer is named; `--header "Authorization: Bearer …"` needs a token minted with `aud`.
+- **`JWT_SECRET`** (or `security.jwtSecret`) is required outside `local`; the boot refuses without it, because the
+  derived fallback is seeded from the app, environment and repo names and forges an admin token for anyone who
+  knows them. `AKAN_ALLOW_DERIVED_JWT_SECRET=1` accepts that risk explicitly.
+
+## `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.
+
+## Rolling MCP Out To An App
+
+The goal of exposing a service over MCP is that a person uses it through an agent instead of through the page:
+one browser consent (the app's own sign-in included), then an hour-long access token and a thirty-day rotating
+refresh token stand in for every later sign-in. The token is the app's own access JWT, so what an agent may do is
+exactly what that person may do over HTTP — nothing is widened and nothing is scoped. Do these in order; steps 2
+and 3 are the ones whose omission shows up as a 404 or a doubled basePath on the consent page.
+
+1. **Mount the lib that carries the authorization server** (`libs/shared`) and confirm `lib/_oauth`,
+   `page/oauth/consent` and `srvkit/oauthServer.ts` are present. Its `option.ts` declares `auth` for `setMcp`, and
+   `setMcp` merges field by field in mount order with the app last — the app never restates `auth`.
+2. **`akan.config.ts`: `syncPageLibs: true`** (or the lib's name in an array). `akan sync <app>` links the consent
+   route under every basePath the app declares; the link folder is generated and never committed.
+3. **`env.server.*` → `oauth`.** `consentPath` / `signinPath` carry the basePath the browser sees
+   (`/office/oauth/consent`, `/office/signin`) and are omitted for an app without one. The server hands the
+   sign-in page `?redirect=` as the app's router names the route — basePath removed — because `router.push` puts
+   the locale and basePath back; the app adds nothing. `issuer` (`AKAN_MCP_AUTH_SERVERS` for the resource side)
+   only behind a tunnel or an edge that renames the host, `resource` (`AKAN_MCP_RESOURCE`) only when `path` moved
+   off `/mcp`, `clients` + `dynamicRegistration: false` only for a deployment that closes registration.
+4. **The sign-in page honours `?redirect=`** by passing it unchanged to the password and SSO controls — a
+   router-space path, never prefixed by hand. Accepting it needs only `startsWith("/") && !startsWith("//")`.
+5. **`lib/option.ts`: `option.setMcp({ instructions, legacyTextBlock: false })`** (`AKAN_MCP_INSTRUCTIONS`,
+   `AKAN_MCP_LEGACY_TEXT`). Leave `readOnly` (`AKAN_MCP_READONLY`) off when the point is to let people *use* the
+   service; it is the valve for a deployment that must not write, not the way to curate.
+6. **`JWT_SECRET`** (or `security.jwtSecret`) in every deployment outside `local`; the boot refuses without it.
+7. **Read the boot log** — `MCP catalogue: tools=… · listing …KB`, the `MCP catalogue cost:` line, one `warn` per
+   refusal, and the list of published entries with no `.desc()`. A tool missing from it is missing everywhere.
+8. **Connect once per app** — `claude mcp add --transport http <name> <issuer>/mcp`; a second entry for the same
+   server with a pre-registered client tests a registration mode, it does not add anything a user needs.
+
+## Choosing What To Open
+
+One rule: **an endpoint is open to an agent when the same person could do the same thing from the page, under
+the same guards.** What stays closed is closed because no agent has a reason to call it, not because of who may
+— and that is the only thing `mcp: false` says.
+
+| Endpoint | Decision |
+|---|---|
+| Domain read slices (`inOrg`, `inProject`, `inSelf`, `byStatuses`) | Open. A named slice publishes only when it declares its **own** `guards`; the `slice()` map reaches the root slice and the generated CRUD, never a named slice. A search slice only on data that may be enumerated. |
+| The root slice and generated CRUD | Published by default; `root:` is `Admin`, so a user token never lists it. Take the cost line first: `mcp: { cru: false }` keeps the reads and drops the writes of a model whose write entries are most of its bytes; `mcp: false` for an internal or sensitive model. |
+| Domain mutations (`startTask`, `completeTicket`) | Open when a person would ask an agent to do it for them; a resource guard is mandatory. An act that cannot be undone — signing, paying, sending, removing — either stays off or says so in its `.desc()`: MCP has no approval card. |
+| Steps of a UI state machine (`requestPhoneCodeForSignin`, `setPasswordInPrepareUser`, a prepare-user flow) | `mcp: false`. Perfectly guarded, and only ever called by mistake. |
+| Authentication, SSO, and the OAuth protocol endpoints | Already `mcp: false` where they are declared. |
+| File upload, an `Any` / `Upload` return, a required `Any` argument, `pubsub` / `message`, `light<Model>` | Refused by the framework; nothing to write. |
+| Admin-only endpoints | Leave the `Admin` guard; an account-scope guard hides the entry from every caller it refuses. |
+
+- **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.
+- **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
+  passes `Admin` guards; treat that as an operational decision, and read the request's subject type when in doubt.
+- **Return what answers the question.** A count-or-summary endpoint taking an id beats a document; a nullable model
+  return publishes no `outputSchema`, so prefer a non-null return plus an `Err`. Bulky page-only fields are
+  `field.visual`. Narrow a list with a named filter slice, never with the root list's raw `query`.
+
+## Writing `instructions`
+
+`*.abstract.md` and `<Agent.Guide>` never reach an MCP client. Exactly three texts do: `instructions`, every
+published entry's `.desc()`, and a `prompt()`. All three are English, whatever the users speak — the reader is a
+model, and the catalogue is built once in one `language` and cached by clients.
+
+- **`instructions` is the workflow.** Five to eight sentences, in this order: what the app is and what its nouns
+  mean; **which tool to call first** and which ids the rest take; how a name becomes an id; what a write confirms
+  before it runs and which writes cannot be undone; what this server does *not* do and where that is done instead.
+
+  ```ts
+  instructions: [
+    "Operations tools for a back-office that runs consulting projects.",
+    "An org is one company; a project belongs to an org; a ticket is one unit of work on a project.",
+    "Start from orgInSelf, then projectInOrg and ticketInProject; every other tool takes the ids those return.",
+    "Prefer ticketStatusInProject for 'how is it going' and ticketInProject only when the user asks for detail.",
+    "createTicket, startTicket and completeTicket write on the caller's behalf: confirm the project and title first.",
+    "Nothing here signs, invoices or uploads a file; those are deliberate acts on the record's own page.",
+  ].join(" "),
+  ```
+- **`.desc()` is the reason to pick one tool** — what it returns and when to use it, two clauses. An id argument's
+  `.desc()` names the tool that returns it (`From projectInOrg`). The generated CRUD borrows the model's `.of()`
+  label and `.desc()`, which is the only text those entries can carry.
+- **`prompt()` is a workflow the user invokes** as a slash command, not one the model chooses — a weekly report,
+  an onboarding check. Put the ask in `Msg.user` at a high `priority` and the attachments in `Msg.resource` masked
+  by their `Light` model at a low one.
+
+## Verifying An App
+
+- `akan lint <app>`, `akan typecheck <app>`, `akan sync <app>`, then the boot log above.
+- The lib's own suites run wherever it is mounted: the OAuth signal test (metadata, registration, both `authorize`
+  redirects, code exchange, `/mcp` with the minted token and the refusal of a first-party or forged one, refresh
+  rotation) and the refresh-session and option unit tests.
+- **One exposure test per app**, in a `lib/<model>.signal.test.ts`: list `tools/list` with a user token and pin the
+  names with `toEqual`, and assert the curated and admin-only ones with `not.toContain`. Exposure is derived from
+  the guards, so a guard change fails this test first — which is the point. The framework's own pattern is
+  `pkgs/akanjs/server/mcp/mcp.integration.test.ts`.
+- Live: connect a client, consent, call a tool, `claude mcp logout`, authenticate again. `AKAN_PUBLIC_LOG_LEVEL=debug`
+  prints one `OAuth token request grant_type=… client_id=…` line per token call; two refreshes in the same second
+  both answering 200 is the grace window working, not a fault.

package/guidelines/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"
+    ]
+  }
+}