@akanjs/cli 3.1.0-rc.20 → 3.1.0-rc.22

package/guidelines/mcpRule/mcpRule.instruction.md

@@ -40,9 +40,9 @@ export class FileSlice extends slice(srv.file, {
   `update`, `remove`), same fallbacks (`create`/`update`/`remove` inherit `cru`), and the same scope: it narrows
   the root slice and the generated CRUD, and never reaches a named slice or a custom endpoint. Those declare
   their own `mcp` beside their own `guards`. The bare `mcp: false` is every key at once, still within that scope.
-- **A screen keeps reaching it.** To a host that renders MCP Apps views, an endpoint refused for `mcp: false` alone
-  is published with `visibility: ["app"]`: the view the page tool opens may call it, the model is never shown it
-  (below). Every other refusal still holds there.
+- **A view keeps reaching it.** To a host that renders MCP Apps views, an endpoint refused for `mcp: false` alone
+  is published with `visibility: ["app"]`: an app's view may call it, the model is never shown it (below). Every
+  other refusal still holds there.
 - **`mcp: true` is the default and is a no-op**; write it only to say out loud that an entry is deliberately on
   the shelf. It does not override a shape refusal (an `Any` return stays refused) and it cannot publish something
   the guard rules keep out.
@@ -203,7 +203,8 @@ export default page()
 - 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.
+  whatever it declared, and reports each one in the boot log like any other refusal. It also drops each `.prompt()`
+  page's text tool, whose run renders the whole page; the prompts, the `.app()` tools and their views stay.
 - 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;
@@ -248,9 +249,9 @@ export default page()
   wire-identical over the POST-only surface this implements — a client whose proposal is not listed is told to
   disconnect. An unknown proposal is answered at whichever end of that list it is closer to, and an unimplemented
   method answers `404` to a modern client but `200` to a legacy one, whose era spends `404` on "your session is
-  gone". **While a `.prompt()` page may show as a view only the legacy pair is spoken**: `server/discover` answers
+  gone". **While an `.app()` may show as a view only the legacy pair is spoken**: `server/discover` answers
   `-32601` and `initialize` settles on `2025-11-25`, because claude.ai renders a view only for a server it reached
-  through `initialize`. An app that renders no view, or whose RSC worker lists no `.prompt()` page, speaks all three.
+  through `initialize`. An app that renders no view, or whose RSC worker lists no `.app()`, speaks all three.
   `modern: true` / `AKAN_MCP_MODERN=true` offers `2026-07-28` anyway; `false` withholds it everywhere.
 - **A modern-era request mirrors `MCP-Protocol-Version` and `Mcp-Method` into headers** (plus `Mcp-Name` when the
   body names one), and one that leaves a mirror out is refused just like one that contradicts the body: a gateway
@@ -349,8 +350,10 @@ delegates to lives in `akanjs/server` (`OAuthAuthorize`, `OAuthToken`, `OAuthReg
 board of one project.").render(…)` — and that is the whole surface. `prompts/list` is every page carrying
 `.prompt()`; its `.param()` stages are the required arguments and its `.search()` stages the optional ones, a list
 argument is comma-separated on the wire and its description says so, and an `ID`/`Int`/`enumOf` value is checked by
-the page's own declaration. **`prompts/get` runs the page's body** — root layouts, layouts, then the page's
-`.render()` — in the RSC worker under the caller's bearer token, the way a tab would open it. Nothing is rendered:
+the page's own declaration. `prompts/list` shows only the screens whose route `.guard()`s admit the caller; a listing
+knows no arguments, so a guard that reads one admits there and is checked again on the call. **`prompts/get` runs the
+route's guards, then the page's body** — root layouts, layouts, then the page's `.render()` — in the RSC worker under
+the caller's bearer token, the way a tab would open it. Nothing is rendered:
 the JSX comes back as an element tree nobody walks, no client component runs, and the screen's data footprint is
 exactly the `fetch.*` queries its body made, with the arguments it made them with. The answer is the description as
 the first message (priority 1), one embedded `resource` per query masked by that endpoint's return model and
@@ -366,74 +369,109 @@ pass. A layout's own queries (a project selector's `projectListInOrg`) are part
 attached too. **No argument fallback**: a required argument left out answers one message — `No projectId was named for
 "briefProjectTickets". Find it with \`projectListBySearch\`, then run this prompt again with projectId=<id>.` —
 and runs nothing, because a prompt cannot re-run itself and context filled in on a guess would never be used. A
-page that redirects (`getSelf({ unauthorize })`), or whose `fetch.*` a guard refuses with 401/403, answers the 401
+page that redirects (a `.guard()`, `getSelf({ unauthorize })`), or whose `fetch.*` a guard refuses with 401/403, answers the 401
 credential challenge when the call carried no token and `This screen is not available to the signed-in account.`
 when it did — the same sentence for both, so a refused id is never confirmed to exist; `router.notFound()` and a
 404 from a query are `No screen exists for these arguments.`; anything else the body throws is `The page failed to
 load.`, with the cause in the server log only. **The description is the only instruction.** `<Agent.Guide>` is for the in-page agent, whose
 levers are the screen's controls, and is never read here, where the levers are the API — so write the description
 in English, in the API's vocabulary, and put a computed rule (the legal status transitions) into it as a static
-table the model combines with the attached state. Names match `^[A-Za-z0-9_-]{1,64}$` and are unique across pages;
-two pages claiming one name fail the listing. An API-only build (`web: false`) publishes no prompts, and the
+table the model combines with the attached state. Names match `^[A-Za-z0-9_-]{1,64}$` and share one namespace with
+every page's `.app()`s; two pages claiming one name fail the listing. An API-only build (`web: false`) publishes no prompts, and the
 in-page chat lists none of them: its `/` menu is its six built-in commands. Pick which screens to publish by this
 rule: a page taking no arguments is the most useful prompt, since MCP has no completion — one taking an id is for
 when the id is already in hand.
 
-## MCP Apps — The Page, Rendered In The Chat
-**A `.prompt()` page is also a tool**, of the same name and arguments, marked `readOnlyHint: false`, since running
-the page makes its own `fetch.*` calls, mutations included. Its result is the
-prompt's briefing plus `Open this screen in a browser: <url>` — what a client without the
-`io.modelcontextprotocol/ui` extension (Claude Code, Codex) reads. A host that declares the extension (claude.ai,
-Claude Desktop, ChatGPT, VS Code, Goose) is also given `_meta.ui.resourceUri` (`ui://<app>/app`, or
-`ui://<app>/app/<basePath>`) and renders the screen in place of the result: the app's CSR bundle, one HTML document,
-in a sandboxed iframe started on the page the tool ran. Its first queries are answered from that run — carried in
-the result's `_meta`, the one part no host shows the model — so the first paint costs no round trip; every later
-call is relayed by the host as `tools/call` under the host's token. Nothing is declared for any of it.
+## MCP Apps — One Component Of A Page, Drawn In The Chat
+**`page().app(name, description, load)` publishes one component of a screen.** `load` takes the page's typed
+arguments and `lang` and returns the element — usually a `Zone` fed by unawaited `fetch.*` fields — and on the web that
+element reaches `.render()` as the argument named `name`, so the page draws it where it belongs:
 
+```tsx
+export default page()
+  .param("ticketId", ID, { desc: "The ticket to show." })
+  .app("showTicket", "Show one ticket with its status and assignee.", ({ ticketId }) => {
+    const { ticketView } = fetch.viewTicket(ticketId);
+    return <Ticket.Zone.View view={ticketView} />;
+  })
+  .render(({ ticketId, showTicket }) => (
+    <div className="flex flex-col gap-4">
+      {showTicket}
+      <Ticket.Util.Close ticketId={ticketId} />
+    </div>
+  ));
+```
+
+- **Each app is a read-only tool** of its name, whose arguments are the page's `.param()` (required) and `.search()`
+  (optional) stages, marked `readOnlyHint: true`. A call checks the arguments, runs the route's `.guard()`s, then the
+  app's `load` alone — no layout body, no `.render()` — and answers the briefing a prompt would give for what that load
+  fetched, plus `Open the full screen: <url>`: what a client without the `io.modelcontextprotocol/ui` extension
+  (Claude Code, Codex) reads. A refusal is a tool error with the prompt's sentences. Several apps may sit on one page;
+  names share one namespace with the prompts, and an endpoint keeps its name over an app's, with a boot warning.
+- **`load` may only query.** A mutation, a file upload, a room subscription or a message sent while it runs throws
+  `base.error.mutationInApp` before anything is sent — on the server through every `await`, in a browser for its
+  synchronous part. Writes stay in `.render()` around the element (the `Close` above), and gating stays in
+  `.guard()`: a `getSelf({ unauthorize })` inside `load` would redirect a view.
+- **A host that declares the extension** (claude.ai, Claude Desktop, ChatGPT, VS Code, Goose) is also given
+  `_meta.ui.resourceUri` (`ui://<app>/apps/<name>`) and draws the app's own view in place of the result: one HTML
+  document per app, which `akan build` writes to `mcp-apps/<name>.html` beside `csr/` and `akan start` writes to
+  `.akan/artifact/mcp-apps/` when a host first reads it. The view runs `load` again with the route values the result
+  names in `structuredContent`, and its first queries are answered from that call — carried in the result's `_meta`,
+  the one part no host shows the model — so the first paint costs no round trip; every later call is relayed by the
+  host as `tools/call` under the host's token.
+- **The view is the component, not the page.** It bundles the page with `.render()`, `.head()`, `.loading()` and
+  `.guard()` blanked, so it carries what the loads reach and nothing else, and draws the element inside the
+  `_overrides.tsx` over the page and the root layout's `McpAppRoot` (`System.App`: its theme, fonts and providers, with
+  no frame, router or websocket). An `_overrides.tsx` the web draws outside the root layout (on its folder, or on one
+  above it with no layout of its own) wraps `McpAppRoot`, so the toasts and approvals it draws take it too. No layout
+  body runs there, so a layout's `<Agent.Guide>` never reaches the host; one inside the element does. A view never
+  moves: a link or `router.push` to one of the app's screens opens that screen's web page through the host (basePath
+  kept), a fragment of its own screen scrolls it, and `router.back()` / `router.refresh()` do nothing. A host loads one
+  file, so every `lazy(() => import(…))` the loads render is inlined; the view build marks a `const X = lazy(…)` pure,
+  so a barrel's, the page's own that only `.render()` drew, or an override manifest's that nothing renders is dropped,
+  while a `lazy()` called anywhere else stays.
 - **What a view may call** is every published tool, and every endpoint kept off the shelf by `mcp: false` alone or
   the generated `light<Model>` read, listed with `visibility: ["app"]` — which a host offers to the view and never to
   the model; a `Person` guard still refuses one. Visibility is a host's UX, not authorization: the guards decide, as
   everywhere. A client that did not declare the extension is listed neither those tools nor the `ui://` resources, a
-  call to one answers `Unknown tool`, and a page tool's result carries none of the view's data for it.
+  call to one answers `Unknown tool`, and an app tool's result carries none of the view's data for it.
 - **The capability is read per request.** A legacy client declares it once at `initialize` and is issued an
   `Mcp-Session-Id` (`ui.<nonce>.<signature>`) that stores nothing: the app signs it, and an id the app did not sign is
   served as a client without views. With `modern: true` a modern request carries the capability in `_meta`. A client
   that declares nothing is issued no session, exactly as before.
-- **A read-only deployment has no MCP Apps.** With `readOnly` / `AKAN_MCP_READONLY` there are no page tools, app-only
-  tools, views or UI sessions, since running a page makes its own `fetch.*` calls, mutations included.
-- **The view is the page, not the app around it.** Each layout above it still runs — guards, providers,
-  `<Agent.Guide>` — but what it draws around `{children}` is hidden, with its frame chrome (`Layout.Navbar`,
-  `TopInset`, `BottomInset`, `BottomTab`), the `topInset` / `bottomInset` it reserves and the tools its controls
-  publish. A layout that draws no page, like a gate, is the screen then and is shown. The screen the view opened on
-  has no back button: there is nothing behind it.
+- **A read-only deployment keeps its apps.** With `readOnly` / `AKAN_MCP_READONLY` the app tools, their resources and
+  views stay, since a load may only query, and the result says so in `_meta`; the view refuses a write before it
+  reaches the host with `base.error.readOnlyDeployment`, toasted in the person's language. A `.prompt()` page's text
+  tool is dropped, since its run renders the whole page; the prompt stays.
+- **`.prompt()` is a briefing, never a view.** Its page is also a text tool of the same name, marked
+  `readOnlyHint: false`, since running the page makes its own `fetch.*` calls, mutations included. To have a host draw
+  part of that screen, declare an `.app()` beside it.
 - **The view has no network.** `connect-src` stays closed; the app's own origin is opened for what a page loads by
   URL — fonts (served with `Access-Control-Allow-Origin: *`) and stored images — and every root-relative URL the
   page writes is pointed at it, since a host may block the document's `<base>` (Claude does).
-  Cookies and Web Storage are in-memory, history is in-memory, and the websocket, live sync, pubsub, the reconnect
-  overlay and `<Agent.Chat />` are off. A path link routes inside the view; any other link opens through the host.
+  Cookies and Web Storage are in-memory, and the websocket, live sync, pubsub, the reconnect overlay and
+  `<Agent.Chat />` are off.
 - **The view looks like the host.** Its neutrals (`--background`, `--foreground`, `--muted`, `--border`, `--ring`) and
   `--font-sans` / `--font-mono` follow the host's theme variables, its theme follows the host's, and so does its
   language when the app speaks it; the app's brand colors and radii stay its own.
-- **The host's model drives the screen too.** The view offers the host the screen's own tools — the surface
-  `<Agent.Chat />` reads: `st.tool`, the form setters, `fill<Model>Form`, `navigate` / `readScreen` / `readState` /
-  `highlight` — and, to a host that takes it, the screen's context (route, live state, `<Agent.Guide>`) through
+- **The host's model drives the component too.** The view offers the host the tools the element publishes — the
+  surface `<Agent.Chat />` reads: `st.tool`, the form setters, `fill<Model>Form`, `readScreen` / `readState` /
+  `highlight` — and, to a host that takes it, the view's context (route, live state, `<Agent.Guide>`) through
   `ui/update-model-context` whenever it moves. A tool that declares `confirm` asks the person in the view through
   the `AgentApproval` slot, whatever the host asks on its own; a card tool, which a person answers in a chat, is not
   offered.
 - **A person tapping in the view acts with the agent's token**, so `isAgentCall` is true and a `Person` act is
   refused there. That act belongs on the web page the result links to. The view holds no token: it is handed the
-  caller's claims, so `getSelf({ unauthorize })` in a layout renders the screen instead of a sign-in page, and each
-  call it makes is relayed and judged by the guards.
+  caller's claims, and each call it makes is relayed and judged by the guards.
 - **A view's call answers what a browser would get**, in `_meta` beside the masked result: the value with its
   `visual` fields, or the domain `Err` with its key and data, toasted in the user's language. A refusal and a crash
-  stay generalized.
-- **What a document load would do, the view does in place.** `router.refresh()` renders the route afresh, a
-  download (`<a download>`, a data table's export) goes to a host that saves files, and a full navigation off the
-  app shows a notice instead of a blank frame.
-- **A page named like an endpoint stays a prompt only**, published or not, and the boot log says so: the endpoint
-  keeps its name. A refused screen answers as a tool error (`isError`), which the model reads.
-- `option.setMcp({ apps: false })` / `AKAN_MCP_APPS=false` keeps every page a prompt only. `web: { csr: false }`
-  publishes the tool with no view, and an API-only build (`web: false`) has no pages to publish.
+  stay generalized. A load that throws, or a read that fails while the element draws, shows what the call would have
+  answered: `No screen exists for these arguments.` for a 404 (a record removed since the call), `This screen is not
+  available to the signed-in account.` for a 401 or 403, and `The page failed to load.` for anything else; a download
+  (`<a download>`, a data table's export) goes to a host that saves files.
+- `option.setMcp({ apps: false })` / `AKAN_MCP_APPS=false` publishes no page tools: no app is published and every
+  prompt stays a prompt only. `web: { csr: false }` publishes the app tools with no view, and an API-only build
+  (`web: false`) has no pages to publish.
 
 ## Progress Reporting
 **`McpProgress.report(n, { total, message })`** reports progress from anywhere inside a call, a service or adapter
@@ -503,9 +541,9 @@ the same guards.** What stays closed is closed because no agent has a reason to
 
 ## Writing `instructions`
 
-`*.abstract.md` never reaches an MCP client, and `<Agent.Guide>` only through an MCP Apps view, beside the screen's own
-tools it explains. Exactly three texts reach every client: `instructions`, every published entry's `.desc()`, and a
-page's `.prompt()` description. All three are English, whatever the users speak
+`*.abstract.md` never reaches an MCP client, and `<Agent.Guide>` only through an MCP App's view, from inside the app's
+element, beside the tools it explains. Exactly these texts reach every client: `instructions`, every published entry's
+`.desc()`, and a page's `.prompt()` and `.app()` descriptions. All 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
@@ -529,6 +567,9 @@ page's `.prompt()` description. All three are English, whatever the users speak
   report, an onboarding check. Its instruction is the `.prompt()` description alone and its attachments are what
   the screen fetched, masked by their return models — so to change what a prompt hands the model, change what the
   screen loads, and keep the description to the ask.
+- **An app is a tool the model picks**, like a read endpoint: its description says what the component shows and for
+  which arguments (`Show one ticket with its status and assignee.`), and the model reads the briefing of what its load
+  fetched whether or not the host draws the view.
 
 ## Verifying An App
 

package/guidelines/pageRule/pageRule.instruction.md

@@ -1,7 +1,7 @@
 # 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
+What a file under `page/` may be, how a route declares its arguments and settings, how a route guards itself, 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.
 
@@ -25,15 +25,16 @@ body shape — this is the full contract behind them. Before changing route beha
 
 - **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 stage of the chain — `.param()`, `.search()`, `.config()`, `.guard()`, `.head()`, `.loading()`; `.notFound()` /
+  `.error()` on a layout; `.fonts()` / `.theme()` / `.manifest()` / `.reconnect()` / `.wsConnect()` /
+  `.layoutStyle()` / `.viewport()` on the root layout; `.prompt()` and `.app()` 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")`.
+  them off the source and refuses a `[projectId]` folder whose page declares no `.param("projectId")`, so the chain
+  is the `export default` expression itself — one bound to a variable first is refused.
 - **`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
@@ -41,6 +42,50 @@ body shape — this is the full contract behind them. Before changing route beha
 - 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.
 
+## Route Guards — `.guard()`
+
+- **`.guard(fn)` decides who may open a route before any of it renders.** Every chain takes it, once: a second
+  `.guard()` throws when the module loads. `fn` receives the route's typed arguments and `lang` (a layout's gets no
+  `children`) and may be `async`. It refuses by moving the router — `router.redirect(href)`, `router.notFound()` — or
+  with `getSelf({ unauthorize })`; `signedIn()` from `@libs/shared/webkit` is that last one, called inside an arrow
+  (`.guard(() => signedIn())`), because `.guard(signedIn)` would hand the route's arguments to `unauthorize`.
+- **On the server every guard of the chain runs before any layout body starts**, root layout first and before the
+  route's arguments are checked, so a redirect is a real 307 even after an awaited query, and a not-found is a 404 —
+  where a `getSelf({ unauthorize })` inside a layout body after I/O redirects late, inside the stream. A query in a
+  guard that the server refuses with 403 or 404 (an owner check) answers not-found, so the page never confirms the
+  record exists. A refusal's not-found keeps only the layouts above the refusing guard, and a path no page matches
+  asks the guards of the layouts its not-found would sit under first.
+- **On a client navigation a page's layers wait for its guards.** The verdict is kept by what the guards read (a
+  query only the page reads keeps it) and lasts while a layer of that location is on screen. Only the page in front
+  asks — never a parked one, nor the one under it during a swipe back; back in front, a cached page included, it asks
+  again in the background while what it drew stays, and a refusal moves the router and blanks it. A guard that moves
+  the router ends the chain and the page draws nothing; a refused or failed check runs again when its layer is
+  retried. Root layouts are drawn once for every page and are not gated
+  themselves; their guards still run in each page's chain, and a legacy page under them waits too. `guard` is a stage
+  only: a legacy module that exports one, a root layout's included, fails to load and fails `akan build`.
+- **MCP runs them too**: a prompt or an app tool runs its route's guards before anything else, and `prompts/list` and
+  the page tools in `tools/list` show only the screens whose guards admit the caller (a listing knows no arguments,
+  so a guard that reads one admits there and is checked again on the call).
+- **A route guard is not authorization for data.** It keeps a person off a screen and redirects early; every query
+  the screen makes is still judged by that endpoint's own `guards`. Write both: the signal guard is the gate, the
+  route guard is the courtesy that answers before the screen draws.
+
+## MCP Apps — `.app()`
+
+- **`.app(name, description, load)` publishes one component of a page as an MCP App**: a read-only tool of that name,
+  whose arguments are the page's `.param()` and `.search()` stages, and a single-file view of its own. `load` receives
+  the page's typed arguments and `lang` and returns the element (usually a `Zone` fed by unawaited `fetch.*` fields);
+  on the web that element reaches `.render()` as the argument named `name`, so the page places it.
+- A page may declare several. A name matches `^[A-Za-z0-9_-]{1,64}$`, is a string literal (the build reads it off the
+  source), shares one namespace with every page's prompts and apps, and needs an English description. A name
+  `.render()` already receives (`lang`, a `.param()` / `.search()` name, another app) fails to compile and throws when
+  the module loads, as does an app named like the page's `.prompt()`.
+- **`load` may only query** (`base.error.mutationInApp` otherwise): keep writes in `.render()` around the element, and
+  gating in `.guard()`. The view runs `load` with no layout body and no `.render()`: it gets the root layout's theme,
+  fonts and framework providers through the generated `McpAppRoot` and the `_overrides.tsx` over the page (one the web
+  draws outside the root layout wraps `McpAppRoot`, its toasts included), and nothing a layout body provides. The
+  chain is the `export default` expression itself: one bound to a name fails the build. Full contract: `mcpRule`.
+
 ## Heads
 
 - **`.head()` takes JSX — `<title>`, `<meta>`, `<link>` — or a function of the route's args returning it.** One that
@@ -58,7 +103,7 @@ body shape — this is the full contract behind them. Before changing route beha
   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.
+  such limit. A gate belongs in the root layout's `.guard()`, which runs in every page's chain.
 
 ## Lib Pages — `syncPageLibs`
 

package/guidelines/runtimeRule/runtimeRule.instruction.md

@@ -585,6 +585,8 @@ serving without a key. Everything else is behind the ops channel.
 | `GET /_akan/ops/info` | the public info plus `akanVersion`, `buildId`, `serverMode`, `databaseMode`, `solo`, `startedAt`, `replicaIdx` |
 | `POST /_akan/ops/snapshot` `{ id, includeSolid?, uploadUrls: { main, solid?, manifest } }` | 202; a child process snapshots, then PUTs each file and the manifest **last** |
 | `GET /_akan/ops/snapshot/:id` | `running` → `uploading` → `done` \| `failed`; kept in memory, so a restart answers 404 |
+| `POST /_akan/ops/migrate` `{ id, action, target?, params?, expect?, items? }` | 202; a child runs `ops migrate <action> … --json` for the token's `sub` |
+| `GET /_akan/ops/migrate/:id` | `running` → `done` (`exitCode`, and `result`: the line `--json` printed last) \| `failed` (it printed none) |
 
 - **The entry is the image's own `main.js`** — a production image carries no `akan` CLI. `AkanApp.start()` hands
   `argv[2] === "ops"` to the command before it boots anything. It reads the container's env — the `AKAN_PUBLIC_*`
@@ -593,10 +595,15 @@ serving without a key. Everything else is behind the ops channel.
   `--force` is for a port some other app holds.
 - **The channel exists only when `AKAN_OPS_PUBLIC_KEY` is set** (Ed25519: PEM, JWK, base64 SPKI or raw 32 bytes).
   The control plane signs a short EdDSA JWS — `aud`, `iat`, `exp` at most 300s after `iat`, a `jti` the process
-  refuses twice — and the host holds only the public half, so a machine someone carries off mints nothing.
+  refuses twice, and optionally `sub`, whom it acts for — and the host holds only the public half, so a machine
+  someone carries off mints nothing.
   `aud` is `<appName>/<environment>`, or `<appName>/<environment>/<AKAN_OPS_INSTANCE>` when that is set, and then
   only that: a token minted for the app as a whole would replay across every host sharing the name. 30 calls a
   minute per process; every refusal is the same 401. A malformed key leaves the app serving with the channel off.
+- **A migrate job runs for the token's `sub`**, which the run records as its actor: apply and rollback refuse a
+  token without one, and a body naming `actor` is refused. Each option reaches the command as `--name=value`. One
+  job runs at a time per process (409 meanwhile); the run's own lease keeps two hosts on one database apart. Jobs
+  live in memory, so after a restart read the outcome from `list`. Polls count toward the 30 a minute.
 - **The app holds no storage credential.** It PUTs to the presigned URLs it was handed (`application/octet-stream`,
   the manifest `application/json`), plain http only to loopback. The manifest landing is the commit marker.
 - **Snapshots cover the SQLite modes only.** `single` copies the main file and, with `includeSolid`, the Solid file;

package/guidelines/ssrRule/ssrRule.instruction.md

@@ -142,9 +142,10 @@ eight queries threw; per-section boundaries put each rejection at its own bounda
 is a real 3xx only when it was raised before any I/O was awaited, the body's own or a layout's above it (a layout that
 awaits `fetch.viewOrg` makes every page under it late); after one — `getSelf({ unauthorize: "/signin" })` fetches —
 it reaches the browser as an HTTP 200 that navigates in the page, which a crawler or `curl` does not
-follow. Either way no markup below the redirect is sent. A route that must answer a real 3xx after I/O — a gate an
-external client hits, a moved URL — takes `.config({ ssr: "block" })`: the response waits for the whole render.
-Never redirect from inside a streamed section.
+follow. Either way no markup below the redirect is sent. A route's `.guard()` runs before any layout body starts,
+so a redirect from it is a real 3xx even after the guard's own awaited query: gate there. A route that must answer a
+real 3xx from its body after I/O — a moved URL found by a query — takes `.config({ ssr: "block" })`: the response
+waits for the whole render. Never redirect from inside a streamed section.
 
 **⑥ Use named `ReactNode` slots, not just `children`.** A client shell that takes one slot per region lets a
 server component supply each of them, instead of absorbing the whole subtree into the bundle. `Layout.Navbar`
@@ -154,8 +155,10 @@ is the shape: `title` / `left` / `right` beside `back` and `children`, each fill
 `canWrite(user?)`, `formatTimes()`), and enum→class lookups belong in a module-scope `as const` map. Both sides call
 the same method, so a client component that exists only to compute a label is markup in the wrong place.
 
-**⑧ Gate auth on the server.** `getSelf({ unauthorize: "/signin" })` in `_layout.tsx` redirects before any of the
-page's markup is rendered. A client-side check costs a hydration round-trip and flashes the wrong UI first.
+**⑧ Gate auth on the server.** `.guard(() => signedIn())` (`@libs/shared/webkit`) on `_layout.tsx` runs before any
+of the route renders, so the redirect is a real 3xx; `getSelf({ unauthorize: "/signin" })` in a layout body still
+redirects before any of the page's markup, in-page after I/O. A client-side check costs a hydration round-trip and
+flashes the wrong UI first.
 
 **⑨ Prefer CSS over client state for pure visibility.** A `data-*` attribute plus `group-data-[…]` variants (see
 `libs/util/ui/Grid/*`) or `<details>`/`<summary>` keeps both branches server-rendered. Reach for `useState` when the

package/guidelines/workspaceRecipes/workspaceRecipes.instruction.md

@@ -451,7 +451,7 @@ export default page()
 
 Rules the loader and `akan sync` enforce: a chain module has no other export; `page()` belongs in a page file and
 `layout()` / `rootLayout()` in a `_layout.tsx`; a page names every `[x]` of its path, a layout may name a subset;
-`.param()` and `.prompt()` names are string literals; `import "./styles.css"` stays the first line of a root layout;
+`.param()`, `.prompt()` and `.app()` names are string literals; `import "./styles.css"` stays the first line of a root layout;
 `_overrides.tsx` is untouched. MCP: `prompts/get` now runs the page's body under the caller's token and hands the
 model the description, what the page fetched, and the tools of those modules — see `mcpRule`.
 

package/incrementalBuilder.proc.js

@@ -8,7 +8,7 @@ import {
   CodegenLock,
   WorkspaceExecutor,
   AppExecutor
-} from "./index-va06nr10.js";
+} from "./index-gxqvev8w.js";
 import"./index-52w0fvh8.js";
 import {
   GraphClientEntryDiscovery,
@@ -19,10 +19,10 @@ import {
   DevChangePlanner,
   DevGeneratedIndexSync,
   SsrDevBundler
-} from "./index-w44cy4vs.js";
+} from "./index-cgyqx6q1.js";
 import {
   ServerGraphFile
-} from "./index-192ha4xh.js";
+} from "./index-6nqnqzv1.js";
 import {
   prepareDevWatchBatch
 } from "./index-a5vmm6x4.js";

package/{index-fmzcs8v6.js → index-1bhv9dh4.js}

@@ -2,10 +2,10 @@
 import {
   runner,
   script
-} from "./index-jw1zm273.js";
+} from "./index-g5px5pxd.js";
 import {
   ModuleExecutor
-} from "./index-va06nr10.js";
+} from "./index-gxqvev8w.js";
 import {
   sourceFile,
   moduleSourcePaths,
@@ -13,10 +13,10 @@ import {
   createPassedPrimitiveReport,
   bilingualLabelForField,
   bilingualDescriptionForField
-} from "./index-trpasv9q.js";
+} from "./index-5m0s0gdv.js";
 import {
   PageScript
-} from "./index-86jt2a0e.js";
+} from "./index-3xhak9e0.js";
 import {
   pluralizeName
 } from "./index-nz8prx9g.js";

package/{index-qtfmtcrw.js → index-1xqq3va9.js}

@@ -39,18 +39,21 @@ import {
 import {
   runner,
   script,
+  markCliErrorPrinted,
   assertPromptable
-} from "./index-jw1zm273.js";
+} from "./index-g5px5pxd.js";
 import {
+  AppInfo,
+  CommandExecutionError,
   WorkspaceExecutor,
   AppExecutor,
   LibExecutor,
   PkgExecutor
-} from "./index-va06nr10.js";
+} from "./index-gxqvev8w.js";
 import {
   DesktopServerStage,
   UpdateUploader
-} from "./index-vk0pa0mn.js";
+} from "./index-ex35dg39.js";
 import {
   resolveMobileTargets,
   resolveAppId
@@ -59,17 +62,17 @@ import {
   NativePublicEnv,
   UpdatePackFolder,
   NativeApp
-} from "./index-g1mbppa9.js";
+} from "./index-551gh8h2.js";
 import {
   LibraryScript
-} from "./index-pydbnfez.js";
+} from "./index-p44jnjfr.js";
 import {
   stripAnsi
 } from "./index-7md2g9vw.js";
 import {
   SlicePlanner,
   formatSlicePlan
-} from "./index-35hc95h5.js";
+} from "./index-f9118j70.js";
 import {
   openBrowser
 } from "./index-9dp031by.js";
@@ -1896,7 +1899,7 @@ ${uniqueCandidates.map((candidate) => `  - ${candidate}`).join(`
 
 // pkgs/@akanjs/cli/application/application.runner.ts
 import { Logger as Logger3, toError } from "akanjs/common";
-var loadBuildRunner = async () => (await import("./applicationBuildRunner-vh4j6vdv.js")).ApplicationBuildRunner;
+var loadBuildRunner = async () => (await import("./applicationBuildRunner-s41mgz21.js")).ApplicationBuildRunner;
 var loadPrompts = async () => await import("@inquirer/prompts");
 
 class ApplicationRunner extends runner("application") {
@@ -1938,8 +1941,12 @@ class ApplicationRunner extends runner("application") {
     const scriptPath = `script/${scriptName}.ts`;
     if (!await app.exists(scriptPath))
       throw new Error(`Script file not found: apps/${app.name}/${scriptPath}`);
-    await app.spawn("bun", [scriptPath], {
-      env: app.getCommandEnv({ AKAN_COMMAND_TYPE: "script", ...await app.getDatabaseModeEnv() }),
+    await this.#spawnFromRoot(app, "script", [`${app.cwdPath}/${scriptPath}`]);
+  }
+  async#spawnFromRoot(app, commandType, args) {
+    await app.spawn("bun", args, {
+      cwd: app.workspace.workspaceRoot,
+      env: app.getCommandEnv({ AKAN_COMMAND_TYPE: commandType, ...await app.getDatabaseModeEnv() }),
       stdio: "inherit"
     });
   }
@@ -2026,10 +2033,7 @@ try {
   await server.stop();
 }
 `;
-    await app.spawn("bun", ["-e", code], {
-      env: app.getCommandEnv({ AKAN_COMMAND_TYPE: "console", ...await app.getDatabaseModeEnv() }),
-      stdio: "inherit"
-    });
+    await this.#spawnFromRoot(app, "console", ["-e", code]);
   }
   async transferDatabase(app, direction, dir) {
     const serverPath = `${app.cwdPath}/server.ts`;
@@ -2048,16 +2052,55 @@ try {
   await server.stop();
 }
 `;
-    await app.spawn("bun", ["-e", code], {
-      env: app.getCommandEnv({ AKAN_COMMAND_TYPE: "script", ...await app.getDatabaseModeEnv() }),
-      stdio: "inherit"
+    await this.#spawnFromRoot(app, "script", ["-e", code]);
+  }
+  async migrate(app, argv) {
+    const serverPath = `${app.cwdPath}/server.ts`;
+    if (!await app.exists("server.ts"))
+      throw new Error(`Server file not found: apps/${app.name}/server.ts`);
+    const code = `
+const argv = ${JSON.stringify(argv)};
+let loaded;
+try {
+  loaded = await import(${JSON.stringify(serverPath)});
+} catch (error) {
+  console.error(error);
+  const { MigrationCommand } = await import("akanjs/server");
+  process.exitCode = await MigrationCommand.print(MigrationCommand.failure(null, error), MigrationCommand.jsonOf(argv));
+}
+if (loaded) process.exitCode = await loaded.migrations.command(loaded.server, argv, ${JSON.stringify(`akan migrate ${app.name}`)});
+`;
+    try {
+      await this.#spawnFromRoot(app, "script", ["-e", code]);
+    } catch (error) {
+      if (!(error instanceof CommandExecutionError) || error.code === null)
+        throw error;
+      process.exitCode = error.code;
+    }
+  }
+  async createMigration(app, migrationName, now = new Date) {
+    const words = migrationName.split(/[^A-Za-z0-9]+/).filter(Boolean);
+    const name = words.map((word, idx) => (idx ? word.charAt(0).toUpperCase() : word.charAt(0).toLowerCase()) + word.slice(1)).join("");
+    if (!/^[A-Za-z][A-Za-z0-9]*$/.test(name))
+      throw new Error(`"${migrationName}" is no migration name; name what it does in camelCase, e.g. bizLicenseOwnership`);
+    const migrationId = `${now.toISOString().replace(/\D/g, "").slice(0, 12)}_${name}`;
+    const filePath = `${AppInfo.migrationDir}/${migrationId}.ts`;
+    if (await app.exists(filePath))
+      throw new Error(`apps/${app.name}/${filePath} already exists`);
+    const title = name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+    await app.applyTemplate({
+      basePath: AppInfo.migrationDir,
+      template: "migration",
+      dict: { migrationId, title: title.charAt(0).toUpperCase() + title.slice(1) },
+      overwrite: false
     });
+    return migrationId;
   }
   async typecheck(app, options = {}) {
     await new (await loadBuildRunner())(app).typecheck(options);
   }
   async typecheckLibrary(lib, options = {}) {
-    const { ProjectTypecheck } = await import("./projectTypecheck-f534enqj.js");
+    const { ProjectTypecheck } = await import("./projectTypecheck-qg2jf80j.js");
     const root = lib.workspace.workspaceRoot;
     await new ProjectTypecheck(lib.cwdPath, root, { ...process.env, AKAN_WORKSPACE_ROOT: root }).run([
       "../../server.ts",
@@ -3339,6 +3382,14 @@ class ApplicationScript extends script("application", [ApplicationRunner, Librar
     await app.scanSync();
     await this.applicationRunner.runConsole(app);
   }
+  async migrate(app, argv) {
+    await app.scanSync();
+    await this.applicationRunner.migrate(app, argv);
+  }
+  async createMigration(app, migrationName) {
+    const migrationId = await this.applicationRunner.createMigration(app, migrationName);
+    Logger6.rawLog(`Created apps/${app.name}/script/migration/${migrationId}.ts; plan it with \`akan migrate ${app.name} plan ${migrationId}\``);
+  }
   async logs(app, options) {
     await this.applicationRunner.runLogs(app, options);
   }
@@ -3359,6 +3410,7 @@ class ApplicationScript extends script("application", [ApplicationRunner, Librar
     } catch (error) {
       Logger6.rawLog(`${app.name} build failed in dist/apps/${app.name}`, undefined, "error");
       Logger6.rawLog(ApplicationBuildReporter.formatError(error), undefined, "error");
+      markCliErrorPrinted(error);
       throw error;
     }
   }
@@ -3381,6 +3433,7 @@ class ApplicationScript extends script("application", [ApplicationRunner, Librar
     } catch (error) {
       spinner.fail(`${exec.name} typecheck failed`);
       Logger6.rawLog(ApplicationBuildReporter.formatError(error), undefined, "error");
+      markCliErrorPrinted(error);
       throw error;
     }
   }
@@ -3635,7 +3688,7 @@ class ApplicationScript extends script("application", [ApplicationRunner, Librar
       await Promise.all(shares.map(async (share) => await share.close()));
     }, "Abandoning the tunnel release; the shares expire on their own.");
     await Promise.all(apps.map(async (app) => {
-      const { TunnelShare } = await import("./TunnelShare-661cxz5e.js");
+      const { TunnelShare } = await import("./TunnelShare-s7bpe55e.js");
       const share = await TunnelShare.open(app, { workspace: app.workspace });
       shares.push(share);
       urls.set(app.name, share.url);