@akanjs/cli 3.0.2 → 3.1.0-rc.0

package/guidelines/cssRule/cssRule.instruction.md

@@ -62,6 +62,25 @@ Screen code is invariant — a plain `<Button variant="primary">` never changes.
 - 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.
 
+## Frame Variables (the page's chrome and the device's insets)
+
+The frame writes these on `#frameRoot` and `<html>`, so any class can read them, web and native alike:
+
+- `--akan-top-safe-area` / `--akan-bottom-safe-area` — the notch and the home indicator. On the web they are
+  `env(safe-area-inset-*)` where the route chain declares `safeArea` (`.config({ safeArea: true })` on the root
+  layout) and `0px` where it does not; in a native app they are the shell's inset. Use the variable alone: never
+  write `env(safe-area-inset-*)` beside it, and never subtract one from the other. The frame paints the bottom strip
+  only under bottom chrome (a `BottomInset` or `BottomTab`) or a route's own `bottomSafeAreaColor`; elsewhere a page's
+  `fixed bottom-0` bar paints its own safe-area padding.
+- `--akan-top-inset` / `--akan-bottom-inset` — the height of the page's top bar and bottom tab slot, per breakpoint
+  when the page declares a responsive inset. A slot whose inset is 0 at a width clips its chrome there and hides it
+  from the keyboard and screen readers, so a phone-only bar needs no `md:hidden`.
+- `--akan-keyboard-inset`, `--akan-viewport-height`, `--akan-viewport-offset-top` — the on-screen keyboard over the
+  page's bottom, the visible height, and how far iOS panned the page to show a field (the top slots follow it).
+- `--akan-content-height` — the room between the insets. iOS pans under the keyboard instead of shrinking the page,
+  so a column sized by it leaves the panned-to area blank: keep a keyboard-heavy screen's input bar in flow at the end
+  of its column, or in the keyboard slot.
+
 ## 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/mcpRule/mcpRule.instruction.md

@@ -10,7 +10,8 @@ The always-loaded convention set carries the short version; this is the full con
 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
+`Public`. `AKAN_MCP=false` takes the whole surface off, and an edge server (`AKAN_PUBLIC_OPERATION_MODE=edge`) starts
+with it off — `AKAN_MCP=true` or `setMcp(true)` puts it back. 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.
@@ -38,6 +39,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.
 - **`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.
@@ -50,13 +54,14 @@ export class FileSlice extends slice(srv.file, {
 
 ## Configuration
 Settings live in the app's `lib/option.ts` — `option.setMcp({ … })`, taking `enabled`, `readOnly`, `path`,
-`version`, `instructions`, `allowedOrigins`, `pageSize`, `language`, `legacyTextBlock`, `outputSchema`, `rateLimit`, and `auth`. **Not `main.ts`**: the gateway
+`version`, `instructions`, `allowedOrigins`, `pageSize`, `language`, `legacyTextBlock`, `outputSchema`, `rateLimit`,
+`promptBudget`, `apps`, `modern`, 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_OUTPUT_SCHEMA`, `AKAN_MCP_RATE_LIMIT`, `AKAN_MCP_CONCURRENT`,
-`AKAN_MCP_AUTH_SERVERS`, `AKAN_MCP_SCOPES`, `AKAN_MCP_RESOURCE`) for a deployment that configures what the source does
+`AKAN_MCP_PROMPT_BUDGET`, `AKAN_MCP_APPS`, `AKAN_MCP_MODERN`, `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.
@@ -100,8 +105,8 @@ export class TaskEndpoint extends endpoint(srv.task, ({ mutation }) => ({
 export default page()
   .param("taskId", ID, { desc: "The task to review." })
   .prompt("reviewTask", "Review this task and suggest next steps.")
-  .render(async ({ taskId }) => {
-    const { taskView } = await fetch.viewTask(taskId);
+  .render(({ taskId }) => {
+    const { taskView } = fetch.viewTask(taskId);
     return <Task.Zone.View view={taskView} />;
   });
 ```
@@ -226,7 +231,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".
+  gone". **While MCP Apps renders views only the legacy pair is spoken**: `server/discover` answers `-32601` and
+  `initialize` settles on `2025-11-25`, because claude.ai renders a view only for a server it reached through
+  `initialize`. `modern: true` / `AKAN_MCP_MODERN=true` offers `2026-07-28` anyway; `false` withholds it everywhere.
 - **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
@@ -354,6 +361,53 @@ in-page chat lists none of them: its `/` menu is its six built-in commands. Pick
 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`. 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.
+
+- **What a view may call** is every published tool and every endpoint kept off the shelf by `mcp: false` alone,
+  listed with `visibility: ["app"]` — which a host offers to the view and never to the model. Visibility is a host's
+  UX, not authorization: the guards decide, as everywhere. A client that did not declare the extension is listed
+  neither those tools nor the `ui://` resources, a call to one answers `Unknown tool`, and a page tool's result
+  carries none of the view's data for it.
+- **The capability is read per request.** A legacy client declares it once at `initialize` and is issued an
+  `Mcp-Session-Id` (`ui.<uuid>`) that stores nothing, since its id is the capability; with `modern: true` a modern
+  request carries it in `_meta`. A client that declares nothing is issued no session, exactly as before.
+- **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.
+- **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
+  `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.
+- **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.
+
 ## 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
@@ -421,8 +475,9 @@ the same guards.** What stays closed is closed because no agent has a reason to
 
 ## Writing `instructions`
 
-`*.abstract.md` and `<Agent.Guide>` never reach an MCP client. Exactly three texts do: `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 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
 — 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
@@ -453,10 +508,10 @@ published entry's `.desc()`, and a page's `.prompt()` description. All three are
 - 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`.
+- **One exposure test per app**, in `srvkit/mcpExposure.signal.test.ts`, since it spans every module: 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/queryRule/queryRule.instruction.md

@@ -65,9 +65,15 @@ with it. `conventions` carries the invariants — this is the full contract behi
 - `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.
+  The query is a compare-and-set in every mode: of two concurrent `updateOne({ id, balance: { $gte: n } }, …)` that
+  both read the row as matching, only one applies, so `modifiedCount` is the verdict.
 - **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`).
+- **An insight field counts or sums.** `accumulate: {}` counts the rows the query matches and `accumulate: { status:
+  "active" }` those that also match the condition; `accumulate: { $sum: "totalValue", status: "active" }` adds the
+  field up over the same rows (`field(Float, { default: 0, accumulate: … })`), a stored value that is not a number
+  counting as nothing — the same answer on SQLite and Postgres.
 - **"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
@@ -119,7 +125,7 @@ with it. `conventions` carries the invariants — this is the full contract behi
 - 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 in every database mode: fts5 on SQLite/libSQL, a weighted `tsvector` under a GIN index on Postgres.
+- Search runs in every database mode: fts5 on SQLite, a weighted `tsvector` under a GIN index on Postgres.
   For the same text the same documents match — punctuation splits words the way unicode61 does, and a phrase never
   runs from one column into the next — but the order may differ, since Postgres ranks without document frequency.
   Assert on the match set, never on a Postgres order the weights alone do not decide.
@@ -185,6 +191,10 @@ shape, so `cascade` never means "related" — it means one of exactly these:
   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.
+- **A reference no cascade removes keeps pointing at the removed row, and a response reads it live-only**: a list
+  leaves the target out, an optional field reads `null`, and a required one answers 404
+  `base.error.relationNotFound` naming the model and the field path. Make a reference whose target can go first
+  `.optional()`, or let it go with the target through `removeWith`.
 - 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

package/guidelines/runtimeRule/runtimeRule.instruction.md

@@ -1,4 +1,4 @@
-# Runtime Rule — Serving, Processes, Logging, Image, Native Apps, Desktop Server, Assets
+# Runtime Rule — Serving, Processes, Logging, Image, Native Apps, Desktop Server, Assets, Build Pipeline
 
 How an Akan app is built, what it serves, how many processes it runs, where its logs go, and what ends up in
 its image. Everything here is declared in `akan.config.ts` or narrowed by an env at boot; none of it is reached
@@ -255,31 +255,62 @@ const config: AppConfig = {
   other CPU of that OS: the Rust library, Bun's executable, the server's `bun install --cpu` and each `bin` file
   follow it, and a server addon with no binary for that CPU stops the build. A macOS app is Apple silicon only —
   Intel Macs are not a target, so `--arch x64` on macOS is refused.
-- **A macOS release for download is signed with a Developer ID and notarized, from the environment.**
+- **A release is signed only with `--sign` and notarized only with `--notarize`** (`build-desktop`,
+  `publish-update`); the environment names the identity and never decides to use it, so a shell exporting a Developer
+  ID signs and uploads nothing unasked. Before either, the server the app carries is searched for every secret value
+  of the workspace's server env files and refused with the paths, and one line names the identity and the service
+  the app goes to.
+- **A macOS release for download is signed with a Developer ID and notarized.**
   `AKAN_NATIVE_MACOS_IDENTITY` names a keychain identity, or `AKAN_NATIVE_MACOS_CERTIFICATE` +
   `_CERTIFICATE_PASSWORD` a `.p12` the build imports into a keychain of its own (a CI runner);
-  `AKAN_NATIVE_MACOS_NOTARY_KEY` + `_KEY_ID` + `_ISSUER` (an App Store Connect API key) or `_NOTARY_PROFILE` turn on
-  notarization and stapling of the app and the dmg. Every Mach-O file — the server's addons and `bin` included — is
+  `AKAN_NATIVE_MACOS_NOTARY_KEY` + `_KEY_ID` + `_ISSUER` (an App Store Connect API key) or `_NOTARY_PROFILE` are the
+  credentials `--notarize` staples the app and the dmg with. Every Mach-O file — the server's addons and `bin` included — is
   signed inside out with the hardened runtime and a timestamp; the executable gets Bun's JIT entitlements and the
   camera's or microphone's when a usage text asks for them, and `desktop.entitlements` adds the app's own.
-  `publish-update` signs with the same identity, since the updater checks the installed app's signature. Without a
+  `publish-update --sign` signs with the same identity, since the updater checks the installed app's signature. Without a
   Developer ID the build warns, because Gatekeeper blocks a downloaded copy.
-- **A Windows release is signed with Authenticode, from the environment.** `AKAN_NATIVE_WINDOWS_CERTIFICATE` +
+- **A Windows release is signed with Authenticode.** `AKAN_NATIVE_WINDOWS_CERTIFICATE` +
   `_CERTIFICATE_PASSWORD` (a `.pfx`), `AKAN_NATIVE_WINDOWS_THUMBPRINT` (a certificate in the store, a token's or an
   HSM's), or `AKAN_NATIVE_WINDOWS_SIGN_COMMAND` (a JSON array run per file with `{file}`, e.g. signtool with Azure
   Trusted Signing's dlib) signs every PE file of the app — the server's `.node` and `bin` included — the setup program
   and the uninstaller it writes, SHA-256 with a timestamp (`AKAN_NATIVE_WINDOWS_TIMESTAMP_URL`).
-- **`updates: { url, publicKey }` lets an installed app update itself** — the whole app on a desktop, the web
+- **`updates: { url, publicKeys }` lets an installed app update itself** — the whole app on a desktop, the web
   bundle on a phone. `akan update-keygen <app>` makes the signing key once
-  (`~/.akan/native/keys/<app id>.update.key`, or the path `AKAN_NATIVE_UPDATE_KEY` names) and prints the
-  `publicKey`. `akan publish-update <app>` builds and signs a release into `updates/`: upload that folder to `url`,
-  the manifests last. `akan pack-update` writes an unsigned phone bundle for whoever holds the key to sign. The
-  channel is the backend env the binary was built for unless `channel` names one, and a release that does not
-  come up is rolled back to the one before.
+  (`~/.akan/native/keys/<app id>.update.key`, or the path `AKAN_NATIVE_UPDATE_KEY` names) and prints its public
+  key. List the online signing key first and offline spares after it (up to three): a phone binary trusts all of
+  them, and a key may revoke only the keys listed before it, so a leaked key cannot lock out its spares. A desktop
+  app trusts the first; `publicKey` is the one-key form. `akan publish-update <app>` builds and signs a release
+  into `updates/`: upload that folder to `url`, the manifests last, or let `--upload s3://<bucket>/<prefix>` do it
+  (credentials and endpoint from `S3_*` or `AWS_*`; a release file the bucket holds is skipped). A phone reads only
+  `<url>/<platform>/<channel>/<nativeApi>.json`, so each store generation on a channel takes its own fixes.
+  `akan pack-update` writes an unsigned phone bundle for whoever holds the key to sign and records it in
+  `<out>/pack.json`, exiting 2 when `--against` says it needs a new store build; `akan push-update` packs and uploads to
+  an akasys project that holds the key, and `akan register-binary` registers a store build after `release-*`. A
+  release that hangs is rolled back while the app runs, and `report: { url }` has a phone post what became of each
+  release (applied, confirmed, rolled back and why) at its next launch, so rollback rates are visible. `devtools: true`
+  opens the web inspector of a release build for an internal test target. The channel is the backend env the binary was built for unless `channel` names one;
+  on a desktop, `updates.setChannel({ channel })` moves the installed app to another manifest until set back with
+  `null` — a server putting a device on a pilot channel — and never to a release older than the one running. A
+  release that does not come up is rolled back to the one before.
 - **An unattended screen** — signage, a kiosk — takes `desktop.recovery: "reload"` (a crashed page loads again,
-  and the app relaunches when the webview ends), `desktop.window: { fullscreen, skipTaskbar }`,
+  and the app relaunches when the webview ends), `desktop.window: { fullscreen, skipTaskbar, frameless }`,
   `desktop.screenCapture: "auto"` (Windows answers `getDisplayMedia()` with the first screen, no picker) and
-  `android.autoplay` (media plays with sound without a tap).
+  `android.autoplay` (media plays with sound without a tap). Its carried server takes `desktop.server: { restart:
+  "forever", watchdog: true }` — restarted after every crash, never given up on, and killed and restarted when its
+  health route stops answering (every 10 s, 3 misses; `{ intervalMs, failures }` to tune) — and
+  `desktop.webview2: "standalone"` puts the whole WebView2 Runtime (~200 MB) in the Windows setup for a PC offline at
+  install. `desktop.server.env` adds variables to the server's start; the build refuses a secret-named one and those
+  the stage owns. The `window` plugin places it: `placeOnDisplay({ index, bounds, unit: "physical" })` puts a window
+  on one display in that display's device pixels — a 640×128 LED panel — lowering the minimum size to fit, beside
+  `setAlwaysOnTop`, `setCursorVisible` (which hides the pointer over its external views too, on Windows) and
+  `setDecorations`. `native.backgroundColor` (or `{ light, dark }`) is what a window and an external view show before
+  their page paints, so a dark board never flashes white, and `desktop.publisher` names who publishes a Windows app in
+  Apps & features and its executable's company (the app name when unset, never Bun's own).
+- **A third-party page shown first-party** — a scoreboard, a menu board — is the `external-view` plugin, listed in
+  `native.plugins`: a webview over the window with a browser profile of its own, held to the origins it was opened
+  for, with an init script, `evaluate`, a trusted `sendKey`, `capture`, and `loadFailed` / `gone` (it reloads, or is
+  rebuilt, by itself) / `consoleMessage` events. Every method on Windows; macOS 14+ lacks `sendKey`, `setMuted` and
+  `capture`.
 
 ## A Desktop App's Server — `bin` And `trustedDependencies`
 
@@ -340,7 +371,8 @@ const config: AppConfig = {
 - **An executable the desktop app spawns goes in `bin`** — its server's code or its native plugins, whether or not
   it carries a server — keyed by the name the code spawns and then by
   `${process.platform}-${process.arch}` (`darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-x64`, `win32-arm64`,
-  `win32-x64`). A source is `{ url, sha256, file? }` — downloaded when the app is built, refused unless it hashes
+  `win32-x64`) — Node's names, unlike an update feed's folder, which is `<os>-<arch>` with the OS spelled `macos`,
+  `windows` or `linux` (`windows-x64/<channel>.json`). A source is `{ url, sha256, file? }` — downloaded when the app is built, refused unless it hashes
   to `sha256` (so plain http is as safe as https), kept in `apps/<app>/.akan/cache/bin/<sha256>` — or
   `{ path, file? }`, relative to the `akan.config.ts` that declares it. `file` is the executable inside an archive
   (`.zip`, `.tar.gz`, `.tgz`, `.tar.xz`, `.tar.bz2`, `.tar`), unpacked with the OS's own `tar` (`unzip` for a zip
@@ -378,6 +410,18 @@ was still starting — the server sees its parent gone and ends the group itself
 later for whatever ignored it. On Windows the job object ends them all with the app. A process started `detached`
 leaves the group, or the job, and keeps running.
 
+**An edge server carries no cloud secret.** The carried server runs `operationMode` edge, and the same app's cloud
+deployment runs cloud: a module whose `serve(ref, { operationMode: ["edge"] }, …)` lists the modes it belongs to mounts
+in those alone, and `modules: ["@edge"]` (or `AKAN_MODULES=@edge`) names every module that lists edge, with what they
+inject, cascade to and hold a relation to. `desktop: { server: { profile: "edge", modules: ["@edge"] } }` builds the
+carried server that way: `env/env.server.<env>.edge.ts` is bundled in place of `env/env.server.<env>.ts`, which never
+enters it, and the build evaluates the profile file with no app env and refuses one whose secret-named keys hold a
+value — a `process.env.X ?? "literal"` counts as the literal. Each lib's env defaults (`env.server.testing.ts`) are
+swapped the same way: for the lib's `env/env.server.testing.edge.ts`, held to the same check, or for the defaults with
+every secret-named value left out, which the build names in a warning. `akan build <app> --profile edge` does the
+same for an image. A module listing only edge does not mount under `akan start` (local): list `local` too to develop
+it there.
+
 **A file the user picks reaches the server as a grant, never as a copy or a path.** With `"file-picker"` in
 `native.plugins`, `filePicker.pickFiles({ forServer: true })` (also `pickDirectory` and `saveFile`,
 from `akanjs/client/native`) copies nothing, whatever the size: its FileRefs serve the originals for a preview, and
@@ -417,7 +461,7 @@ lacks is added there: an app's own plugin runs as Bun code in the plugin host an
   `single` and a cloud cluster in `cluster`: declare both.
 - **Where the data lives is the deployment's env, ahead of `env.server.ts`**: `SQLITE_DATABASE_PATH`,
   `AKAN_SOLID_DB_PATH`, `POSTGRES_URL` (or `POSTGRES_HOST`/`PORT`/`DATABASE`/`USER`/`PASSWORD`),
-  `POSTGRES_INSIGHT_URL`, `LIBSQL_URL`. `REDIS_URI` is required outside local development. Pool size, SSL and
+  `POSTGRES_INSIGHT_URL`. `REDIS_URI` is required outside local development. Pool size, SSL and
   prepared statements ride the Postgres URL (`?max=20&ssl=require`, `prepare=false` behind PgBouncer).
 - **Uploads**: a deployed `multiple`/`cluster` app uses object storage, or a volume every instance mounts with
   `AKAN_STORAGE_SHARED=true`.
@@ -508,3 +552,40 @@ const config: AppConfig = { assets: { pruneFonts: false } }; // emergency valve,
 - The phase is `assets`, between `csr` and `compress`. An api-only build (`web: false`) copies no `public/` and
   the phase finds nothing to do.
 
+## The Build Pipeline — `pipeline` In `akan.config.ts`
+
+Akan Cloud builds and deploys each app as `build` → `docker` → `deploy`, and `ota` after them when asked. **An app's own stages go in
+`apps/<app>/akan.config.ts` under `pipeline`; stages around every app go in the workspace root's
+`akan.config.ts`**, typed `WorkspaceConfig` (`before`, `after`, `post`, `env`, `timeout`). Both are `import type`
+objects (or `(ctx) => …`), and `akan pipeline dry-run | validate | plan` turns them into the plan Akan Cloud runs —
+locally, running nothing.
+
+```ts
+const config: AppConfig = {
+  pipeline: { stages: [{ use: "build" }, { name: "Test", sh: "bun run akan test web" }, { use: "docker" }, { use: "deploy" }] },
+};
+const config: WorkspaceConfig = {
+  pipeline: { post: { failure: [{ name: "Notify", sh: "./scripts/notify.sh", secrets: ["DISCORD_WEBHOOK"] }] } },
+};
+```
+
+- **A declared list is the whole pipeline.** Without `pipeline` an app runs the three actions; with it, write them
+  — a list without `{ use: "deploy" }` never deploys. Each action appears at most once, in that order, and
+  `docker` needs a `build` before it (the image is made from that build).
+- **`{ use: "ota" }` ships the native web bundle over the air**, after `deploy` so the API it calls is already up.
+  It is opt-in, makes its own CSR build, and packs every native target that declares `native.updates` for iOS
+  and Android — `targets` and `platforms` narrow it, and a target without `updates` is a plan error. Akan Cloud
+  signs and publishes the packs; the plan never holds a key.
+- **A stage runs after the action before it.** Stages between two actions share a phase across apps, and a phase
+  waits for every stage of the one before; `deploy` runs the apps one at a time in `after` order.
+- **App stages stand on their own.** Never rely on what a root `before` stage left on disk: the root config never
+  travels to a subspace, so an app built there runs its own stages only. Keep the files an app stage needs inside
+  the app or its libs.
+- **Secrets are named and write-only.** `akan upload-secret <NAME>` stores one per project (`--branch` for a
+  branch-only value); a step lists it in `secrets` and reads `$NAME`. Anyone who can push to the repo can make a
+  step print it — the GitHub Actions model — so push access is secret access.
+- **`allowFailure` only means "this failure does not fail the run"**; how the run is reported is Akan Cloud's
+  call. `env` and secret names may not be `CI`, `AKAN_CI_*` or shell names such as `PATH`, and every step gets
+  `AKAN_CI_BRANCH`, `AKAN_CI_APP` and the rest of the build's facts.
+- `akan pipeline` exits 0 with a plan, 1 with an envelope of errors, and 2 for anything else (no envelope). A lib
+  config takes no `pipeline`; the root config takes no app or lib settings.

package/guidelines/ssrRule/ssrRule.instruction.md

@@ -125,21 +125,24 @@ Three rules the shape enforces:
 **A failure now surfaces where it happened.** One `Promise.all` in the page body reports nothing about which of
 eight queries threw; per-section boundaries put each rejection at its own boundary.
 
-**Keep the auth gate in the shell.** A redirect thrown after the shell has flushed can only be delivered as a
-soft-redirect script, so `getSelf({ unauthorize: "/signin" })` stays in `_layout.tsx` or the page body — never
-inside a streamed section.
+**Know which redirects are real.** A streaming response starts while layout and page bodies still run, so a redirect
+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.
 
 **⑥ 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`
-declares `title` / `left` / `right` alongside `back` and `children`, but its render body uses only `back` and
-`children` — copy the shape, not that component.
+is the shape: `title` / `left` / `right` beside `back` and `children`, each filled by the server.
 
 **⑦ Let the server do the derived work.** Display and predicate logic belongs on `Light<Model>` (`isNew()`,
 `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 HTML is
-sent. A client-side check costs a hydration round-trip and flashes the wrong UI first.
+**⑧ 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.
 
 **⑨ 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/transportRule/transportRule.instruction.md

@@ -21,8 +21,27 @@ mutation is mounted under. `conventions` carries the invariants — this is the
   `null` rather than a placeholder when genuinely unknown — a loopback-looking address for an unknown caller
   is the failure this replaced. The gateway also forwards the client port (`x-forwarded-port`, read with
   `context.getClientPort()`) along with host and protocol.
+- **A device or another server proves itself with a machine token.** `MachineToken.issue({ kind, id, version },
+  { expiresAt? })` in `akanjs/server` signs an EdDSA JWT (`typ: akan-machine+jwt`, `aud: <app>/<environment>`) with
+  `AKAN_MACHINE_PRIVATE_KEY`; it never expires unless asked. `akan machine-keygen <file>` writes that key to a file
+  and prints only the public one. A server with either key verifies the bearer of every call — HTTP, and the
+  websocket's auth frame — after every lib middleware, and sets `account.machine = { kind, id, version }` from a
+  verified token; it takes off a `machine` any other middleware or a session's claims put there, so a staff token
+  can never pass for one, and a session middleware already reads the EdDSA token as anonymous. `.with(Machine)` hands
+  the identity (401 without one; `{ nullable: true }` takes `null`), and a pubsub room's guards see it on subscribe
+  and on every credential change. Revocation is the app's: a guard compares `machine.version` with the record's
+  `tokenVersion`, which a removal or a reinstall bumps. An endpoint taking `.with(Machine)` on a server with no key
+  is an error at boot. The calling side is `fetch.clone({ origin, jwt: token, connect: true })`.
 - **Every socket carries a `socketId`, and only the framework mints one.** `AppWsData` assigns it at the handshake, and a `message` / `pubsub` handler reads it off the `Ws` internal arg — `.with(Ws)` hands `{ ws, socketId, subscribe, on, off }`. Never mint your own from `ws.data`: the room bookkeeping keys on the framework's id, and a second one fails to match it silently. It identifies a **connection**, not a caller — a reconnect gets a new id and the federation gateway's own socket is a different one — so per-user state keys on the account, never on this.
 
+- **A socket that dropped comes back on a backoff, and asks for what it missed.** The client waits 1 s doubling to
+  30 s, cut at random so a deploy's dropped clients return apart; `fetch.clone({ ws: { reconnect: { min, max, jitter,
+  maxAttempts } | false, headers, tls, onStateChange, onRevoked, onError } })` (or `fetch.instance.configureWs(…)`)
+  tunes it, and a server-side client sends `headers` and its token with the upgrade. A server numbers the JSON frames
+  each room delivers (`seq`); a client drops a repeat, and a hole — a frame dropped under backpressure — calls the
+  room's `onResync`. A resubscribe names its last frame (`since`): a server that saw every publish (a solo process)
+  replays what followed it ahead of the ack, and otherwise answers a gap, which calls `onResync` as before. Binary
+  rooms are not numbered.
 - **A cleanup registered with `ws.on("disconnect" | "unsubscribe", fn)` is scoped to the call that registered it.**
   From a `pubsub` subscribe it belongs to that room — `unsubscribe` runs when the client leaves it or a credential
   change revokes it, `disconnect` when the socket closes while still subscribed — so a room already left runs

package/guidelines/workspaceRecipes/workspaceRecipes.instruction.md

@@ -187,8 +187,8 @@ export class TaskFilter extends from(cnst.Task, (filter) => ({
 }))
 
 // 4. In page — init the slice inside the page chain's render and hand the init to a Zone.
-export default page().render(async () => {
-  const [{ taskInitInTodo }] = await Promise.all([fetch.initTaskInTodo()]);
+export default page().render(() => {
+  const { taskInitInTodo } = fetch.initTaskInTodo();
   return <Task.Zone.Card init={taskInitInTodo} sliceName="taskInTodo" />;
 });
 ```
@@ -349,8 +349,8 @@ export function generateHead({ params }: PageProps) {
 }
 export default async function Page({ params: { projectId }, searchParams }: PageProps) {
   const { l } = usePage();
-  const { project } = await fetch.viewProject(projectId);
-  return <Project.Zone.View view={project} tab={searchParams.tab} />;
+  const { projectView } = await fetch.viewProject(projectId);
+  return <Project.Zone.View view={projectView} tab={searchParams.tab} />;
 }
 export const pageConfig = { transition: "stack" } satisfies PageConfig;
 
@@ -367,8 +367,8 @@ export default page()
   .prompt("briefProject", "Brief one project: its status and what is due.")
   .render(async ({ projectId, tab }) => {
     const { l } = usePage();
-    const { project } = await fetch.viewProject(projectId);
-    return <Project.Zone.View view={project} tab={tab} />;
+    const { projectView } = await fetch.viewProject(projectId);
+    return <Project.Zone.View view={projectView} tab={tab} />;
   });
 ```
 

package/incrementalBuilder.proc.js

@@ -8,7 +8,7 @@ import {
   CodegenLock,
   WorkspaceExecutor,
   AppExecutor
-} from "./index-50wb2a26.js";
+} from "./index-55mynnqs.js";
 import"./index-52w0fvh8.js";
 import {
   GraphClientEntryDiscovery,
@@ -20,7 +20,7 @@ import {
   DevChangePlanner,
   DevGeneratedIndexSync,
   SsrDevBundler
-} from "./index-gtjgnv36.js";
+} from "./index-aprt7pkz.js";
 import {
   prepareDevWatchBatch
 } from "./index-a5vmm6x4.js";
@@ -235,6 +235,7 @@ class IncrementalBuilder {
   #autoImportSync;
   #watcher = null;
   #generation = 0;
+  #shellGeneration = null;
   #discoveredThrough = 0;
   #csrActive = IncrementalBuilder.#csrArmedByEnv();
   #csrBundler;
@@ -852,7 +853,7 @@ class IncrementalBuilder {
       if (crashedNeeds.includes("ssr"))
         this.#ssrPatcher?.releaseHandedOver();
       for (const need of crashedNeeds)
-        if (need !== "base")
+        if (need !== "base" && need !== "shell")
           this.#sendBuildStatus(need, {
             generation,
             ok: false,
@@ -916,6 +917,10 @@ class IncrementalBuilder {
     this.#logger.verbose(`announced boot state after recycle generation=${generation}`);
   }
   async handleBuildCsr(msg) {
+    if (msg.shell) {
+      await this.#buildShell(msg);
+      return;
+    }
     this.#beginCsrArm();
     this.#csrActive = true;
     const armed = this.#workQueue.enqueue("build-csr", async () => {
@@ -940,6 +945,22 @@ class IncrementalBuilder {
     this.#csrGate = this.#armingCsr(armed);
     await armed;
   }
+  async#buildShell(msg) {
+    await this.#workQueue.enqueue("build-shell", async () => {
+      const generation = this.#generation;
+      let error;
+      if (this.#shellGeneration !== generation)
+        try {
+          const result = await this.#batchRunner.run(await this.#batchRequest({ generation, needs: ["shell"], changedFiles: [] }));
+          error = result.errors.shell;
+          if (!error)
+            this.#shellGeneration = generation;
+        } catch (err) {
+          error = ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot);
+        }
+      await BuilderChannel.send(error ? { type: "build-csr-res", id: msg.id, ok: false, error } : { type: "build-csr-res", id: msg.id, ok: true });
+    });
+  }
   #beginCsrArm() {
     if (this.#csrArms === 0) {
       this.#csrWasActive = this.#csrActive;

package/{index-h9ht6s60.js → index-05g3jayg.js}

@@ -2,7 +2,7 @@
 import {
   AppExecutor,
   LibExecutor
-} from "./index-50wb2a26.js";
+} from "./index-55mynnqs.js";
 
 // pkgs/@akanjs/devkit/workflow/utils.ts
 var jsonText = (value, { trailingNewline = true } = {}) => `${JSON.stringify(value, null, 2)}${trailingNewline ? `

package/{index-j38qkvkk.js → index-0bm04n5g.js}

@@ -1,13 +1,13 @@
 // @bun
 import {
   AppExecutor
-} from "./index-50wb2a26.js";
+} from "./index-55mynnqs.js";
 import {
   jsonText,
   createWorkflowBaselineSummary,
   buildAkanModuleContextIndex,
   toolingRolloutGate
-} from "./index-h9ht6s60.js";
+} from "./index-05g3jayg.js";
 import {
   buildResourceList,
   codexMcpConfigPath,
@@ -17,25 +17,27 @@ import {
   upsertCodexMcpServerBlock,
   renderDoctorText,
   AkanContextAnalyzer
-} from "./index-zyw622y1.js";
+} from "./index-2mx692qq.js";
 import {
   runner
-} from "./index-q6ft9fkc.js";
+} from "./index-6jjtnhkw.js";
 import {
-  getMobileTargets,
-  appIdsOf,
   NativeApp,
   isPlaceholderAppId
-} from "./index-jk9xnck6.js";
+} from "./index-kjvrq3nc.js";
 import {
   Prompter2
 } from "./index-zzvvc845.js";
 import {
   RepairRunner
-} from "./index-hp3stk1m.js";
+} from "./index-fm46xrf1.js";
 import {
   WorkflowRunner
-} from "./index-bsv901fd.js";
+} from "./index-rwq3ekqc.js";
+import {
+  getMobileTargets,
+  appIdsOf
+} from "./index-q958tqqg.js";
 
 // pkgs/@akanjs/devkit/akanMcpContract.ts
 import path from "path";
@@ -947,7 +949,7 @@ ${payload}`);
       "add-enum-field": "`akan add-enum-field --app <app-or-lib> --module <module> --field <field> --values a,b --format json` adds an enum field to source constant/dictionary files without editing generated files.",
       sync: "`akan sync <app-or-lib>` refreshes generated Akan files from source conventions.",
       lint: "`akan lint <app-or-lib-or-pkg>` runs Biome linting after preparing generated files.",
-      typecheck: "`akan typecheck <app-name>` runs an application typecheck after preparing generated files.",
+      typecheck: "`akan typecheck <app-or-lib>` typechecks an app or a library after preparing generated files, its tests and specs included (`--tests false` to leave them out; a build does).",
       test: "`akan test <app-or-lib-or-pkg>` prepares the target and runs its tests.",
       build: "`akan build <app-name>` creates a production build after preparing generated files.",
       doctor: "`akan doctor --strict --format json` reports agent-readable workspace convention diagnostics and validation hints.",

package/{index-g38nhv87.js → index-2etcv0sc.js}

@@ -2,7 +2,7 @@
 import {
   runner,
   script
-} from "./index-q6ft9fkc.js";
+} from "./index-6jjtnhkw.js";
 
 // pkgs/@akanjs/cli/page/page.runner.ts
 class PageRunner extends runner("page") {