@akanjs/cli 3.1.0-rc.1 → 3.1.0-rc.3

package/{cloud.command-yj6xb2a7.js → cloud.command-nyemv0m3.js}

@@ -3,57 +3,47 @@ import {
   App,
   Workspace,
   command
-} from "./index-6jjtnhkw.js";
+} from "./index-3x7yeecy.js";
 import"./index-52w0fvh8.js";
-import"./index-55mynnqs.js";
-import"./index-1w2qaee2.js";
-import"./index-pgj2rt78.js";
+import"./index-bv210r6t.js";
+import"./index-wjqbc7sf.js";
 import {
   PlatformTestRun
-} from "./index-8ggztp8k.js";
+} from "./index-wanhh011.js";
+import"./index-kmamh5bv.js";
+import"./index-qf8g88j9.js";
+import"./index-ec080x99.js";
 import"./index-k9rrten6.js";
-import"./index-c1x0be5j.js";
-import"./index-jx4bzvwg.js";
+import"./index-dmsvd2rv.js";
+import"./index-1a7nhq56.js";
 import"./index-7md2g9vw.js";
 import"./index-2ahj896a.js";
-import"./index-gnyf1fqy.js";
+import"./index-qvghfv6v.js";
 import {
   CloudScript2
-} from "./index-rc5rwyps.js";
-import"./index-qt22xstj.js";
+} from "./index-jj7yapwq.js";
 import {
-  getMobileTargetChoices
-} from "./index-q958tqqg.js";
+  writeOption,
+  oneNativeTargetOption,
+  nativeEnvs,
+  releaseEnvOption,
+  allowLocalOption,
+  publicEnvOption,
+  hostOption,
+  subspaceOption
+} from "./index-8935h3n1.js";
+import"./index-c9zjb3tw.js";
+import"./index-2z3kykvd.js";
 
 // pkgs/@akanjs/cli/cloud/cloud.command.ts
 var localRegistryUrl = () => process.env.AKAN_NPM_REGISTRY ?? "http://127.0.0.1:4873";
-var hostOption = {
-  desc: "host of the cloud to target (default: cloud.host of the root akan.config.ts, else Akan Cloud)",
-  nullable: true
-};
-var targetOption = {
-  desc: "native target name (a key of native.targets)",
-  ask: "Select native target",
-  enum: async ({ app }) => await getMobileTargetChoices(app)
-};
-var envOption = {
-  enum: ["debug", "develop", "main", "local"],
-  desc: "backend environment",
-  default: "main"
-};
 var resolveRegistryUrl = (registry) => registry === "local" ? localRegistryUrl() : undefined;
 
 class CloudCommand extends command("cloud", [CloudScript2], ({ public: target }) => ({
-  login: target({ desc: "Login to Akan Cloud services" }).option("host", String, {
-    desc: "host of the cloud (default: cloud.host of the root akan.config.ts, else Akan Cloud)",
-    nullable: true
-  }).with(Workspace).exec(async function(host, workspace) {
+  login: target({ desc: "Login to Akan Cloud services" }).option("host", String, hostOption).with(Workspace).exec(async function(host, workspace) {
     await this.cloudScript.login(workspace, host);
   }),
-  logout: target({ desc: "Logout from Akan Cloud services" }).option("host", String, {
-    desc: "host of the cloud (default: cloud.host of the root akan.config.ts, else Akan Cloud)",
-    nullable: true
-  }).with(Workspace).exec(async function(host, workspace) {
+  logout: target({ desc: "Logout from Akan Cloud services" }).option("host", String, hostOption).with(Workspace).exec(async function(host, workspace) {
     await this.cloudScript.logout(workspace, host);
   }),
   deployAkan: target({ devOnly: true, desc: "Deploy Akan.js framework to cloud (internal use)" }).option("test", Boolean, { desc: "test the deployment", default: true }).option("registry", String, {
@@ -105,12 +95,27 @@ class CloudCommand extends command("cloud", [CloudScript2], ({ public: target })
     await this.cloudScript.update(workspace, tag, { registryUrl: resolveRegistryUrl(registry) });
   }),
   pushUpdate: target({
-    desc: "Pack an over-the-air update of a phone's web bundle and upload it to the akasys project, which signs and publishes it"
-  }).with(App).option("platform", String, { enum: ["ios", "android"], desc: "the app it updates" }).option("target", String, targetOption).option("env", String, envOption).option("channel", String, { desc: "the channel (default: the target's updates.channel)", nullable: true }).option("notes", String, { desc: "release notes shown in the project", nullable: true }).option("subspace", String, { desc: "the subspace whose project gets it", nullable: true }).option("host", String, hostOption).option("write", Boolean, { desc: "write code generation", default: true }).option("allowLocalRelease", Boolean, { flag: "l", desc: "allow packing with --env local", default: false }).option("pack", String, {
+    desc: "Pack an over-the-air update of a phone's web bundle, or take the folder `akan pack-update` wrote, and upload it to the Akan Cloud project, which signs and publishes it. Exits 2 when the pack needs a new store build or the project rejects it, 1 on any other failure"
+  }).with(App).option("platform", String, {
+    enum: ["ios", "android"],
+    desc: "the app it updates (with --pack, default: the pack's)",
+    nullable: true
+  }).option("target", String, {
+    desc: "native target name, a key of native.targets (default: the only one; with --pack, the pack's)",
+    nullable: true
+  }).option("env", String, {
+    enum: nativeEnvs,
+    desc: "backend environment (default: main; with --pack, the pack's)",
+    nullable: true
+  }).option("channel", String, { desc: "the channel (default: the target's updates.channel)", nullable: true }).option("notes", String, { desc: "release notes shown in the project", nullable: true }).option("subspace", String, subspaceOption("gets it")).option("host", String, hostOption).option("write", Boolean, writeOption).option("allowLocalRelease", Boolean, {
+    flag: "l",
+    desc: "allow packing, or uploading a pack made, with --env local",
+    default: false
+  }).option("pack", String, {
     flag: "d",
-    desc: "a folder `akan pack-update` wrote, uploaded instead of packing",
+    desc: "a folder `akan pack-update` wrote, uploaded instead of packing; --platform, --target and --env must match it",
     nullable: true
-  }).with(Workspace).exec(async function(app, platform, target, env, channel, notes, subspace, host, write, allowLocalRelease, pack, workspace) {
+  }).option("publicEnv", String, publicEnvOption("the update")).with(Workspace).exec(async function(app, platform, target, env, channel, notes, subspace, host, write, allowLocalRelease, pack, publicEnv, workspace) {
     await this.cloudScript.pushUpdate(workspace, app, {
       platform,
       target,
@@ -121,15 +126,16 @@ class CloudCommand extends command("cloud", [CloudScript2], ({ public: target })
       host,
       write,
       allowLocalRelease,
-      pack
+      pack,
+      publicEnv
     });
   }),
   registerBinary: target({
-    desc: "Register the store build of a phone app with the akasys project, with a pack of the same commit as its embedded bundle"
+    desc: "Register the store build of a phone app with the Akan Cloud project, with a pack of the same commit as its embedded bundle. Exits 2 when the store build differs natively from this commit's pack, 1 on any other failure"
   }).with(App).option("platform", String, { enum: ["ios", "android"], desc: "the store build to register" }).option("distribution", String, {
     enum: ["appStore", "testFlight", "playStore", "playTesting", "direct"],
     desc: "where the binary ships"
-  }).option("target", String, targetOption).option("env", String, envOption).option("subspace", String, { desc: "the subspace whose project gets it", nullable: true }).option("host", String, hostOption).option("write", Boolean, { desc: "write code generation", default: true }).option("allowLocalRelease", Boolean, { flag: "l", desc: "allow packing with --env local", default: false }).with(Workspace).exec(async function(app, platform, distribution, target, env, subspace, host, write, allowLocalRelease, workspace) {
+  }).option("target", String, oneNativeTargetOption).option("env", String, releaseEnvOption).option("subspace", String, subspaceOption("gets it")).option("host", String, hostOption).option("write", Boolean, writeOption).option("allowLocalRelease", Boolean, allowLocalOption("packing")).option("publicEnv", String, publicEnvOption("the pack (default: what the store build recorded)")).with(Workspace).exec(async function(app, platform, distribution, target, env, subspace, host, write, allowLocalRelease, publicEnv, workspace) {
     await this.cloudScript.registerBinary(workspace, app, {
       platform,
       distribution,
@@ -138,51 +144,37 @@ class CloudCommand extends command("cloud", [CloudScript2], ({ public: target })
       subspace,
       host,
       write,
-      allowLocalRelease
+      allowLocalRelease,
+      publicEnv
     });
   }),
   uploadSecret: target({
-    desc: "Upload a named pipeline secret to the akasys project; write-only, it can never be read back"
+    desc: "Upload a named pipeline secret to the Akan Cloud project; write-only, it can never be read back"
   }).arg("name", String, { desc: "secret name, e.g. DISCORD_WEBHOOK" }).option("branch", String, {
     desc: "only builds of this branch use it: debug, develop or main (default: every branch)",
     nullable: true
   }).option("file", String, {
     desc: "read the value from this file instead of stdin or a hidden prompt",
     nullable: true
-  }).option("subspace", String, { desc: "the subspace whose project gets it", nullable: true }).option("host", String, {
-    desc: "host of the cloud to target (default: cloud.host of the root akan.config.ts, else Akan Cloud)",
-    nullable: true
-  }).with(Workspace).exec(async function(name, branch, file, subspace, host, workspace) {
+  }).option("subspace", String, subspaceOption("gets it")).option("host", String, hostOption).with(Workspace).exec(async function(name, branch, file, subspace, host, workspace) {
     await this.cloudScript.uploadSecret(workspace, { name, branch, file, subspace, host });
   }),
-  listSecrets: target({ desc: "List the pipeline secrets of the akasys project: names and scopes, never values" }).option("branch", String, {
+  listSecrets: target({ desc: "List the pipeline secrets of the Akan Cloud project: names and scopes, never values" }).option("branch", String, {
     desc: "only the secrets builds of this branch use: debug, develop or main",
     nullable: true
-  }).option("subspace", String, { desc: "the subspace whose project to list", nullable: true }).option("host", String, {
-    desc: "host of the cloud to target (default: cloud.host of the root akan.config.ts, else Akan Cloud)",
-    nullable: true
-  }).with(Workspace).exec(async function(branch, subspace, host, workspace) {
+  }).option("subspace", String, subspaceOption("to list")).option("host", String, hostOption).with(Workspace).exec(async function(branch, subspace, host, workspace) {
     await this.cloudScript.listSecrets(workspace, { branch, subspace, host });
   }),
-  removeSecret: target({ desc: "Remove a named pipeline secret from the akasys project" }).arg("name", String, { desc: "secret name" }).option("branch", String, {
+  removeSecret: target({ desc: "Remove a named pipeline secret from the Akan Cloud project" }).arg("name", String, { desc: "secret name" }).option("branch", String, {
     desc: "the branch override to remove: debug, develop or main (default: the every-branch value)",
     nullable: true
-  }).option("subspace", String, { desc: "the subspace whose project holds it", nullable: true }).option("host", String, {
-    desc: "host of the cloud to target (default: cloud.host of the root akan.config.ts, else Akan Cloud)",
-    nullable: true
-  }).with(Workspace).exec(async function(name, branch, subspace, host, workspace) {
+  }).option("subspace", String, subspaceOption("holds it")).option("host", String, hostOption).with(Workspace).exec(async function(name, branch, subspace, host, workspace) {
     await this.cloudScript.removeSecret(workspace, { name, branch, subspace, host });
   }),
-  downloadEnv: target({ desc: "Download environment variables from cloud or SCP server" }).option("host", String, {
-    desc: "host of the cloud to target (default: cloud.host of the root akan.config.ts, else Akan Cloud)",
-    nullable: true
-  }).with(Workspace).exec(async function(host, workspace) {
+  downloadEnv: target({ desc: "Download environment variables from cloud or SCP server" }).option("host", String, hostOption).with(Workspace).exec(async function(host, workspace) {
     await this.cloudScript.downloadEnv(workspace, undefined, { host });
   }),
-  uploadEnv: target({ desc: "Upload environment variables to cloud or SCP server" }).option("host", String, {
-    desc: "host of the cloud to target (default: cloud.host of the root akan.config.ts, else Akan Cloud)",
-    nullable: true
-  }).with(Workspace).exec(async function(host, workspace) {
+  uploadEnv: target({ desc: "Upload environment variables to cloud or SCP server" }).option("host", String, hostOption).with(Workspace).exec(async function(host, workspace) {
     await this.cloudScript.uploadEnv(workspace, { host });
   })
 })) {

package/cloud.script-ht6yb203.js

@@ -0,0 +1,23 @@
+// @bun
+import {
+  CloudScript2
+} from "./index-jj7yapwq.js";
+import"./index-wanhh011.js";
+import"./index-1a7nhq56.js";
+import"./index-c9zjb3tw.js";
+import"./index-dmsvd2rv.js";
+import"./index-qvghfv6v.js";
+import"./index-kmamh5bv.js";
+import"./index-wjqbc7sf.js";
+import"./index-qf8g88j9.js";
+import"./index-3x7yeecy.js";
+import"./index-7md2g9vw.js";
+import"./index-2z3kykvd.js";
+import"./index-k9rrten6.js";
+import"./index-ec080x99.js";
+import"./index-bv210r6t.js";
+import"./index-2ahj896a.js";
+import"./index-52w0fvh8.js";
+export {
+  CloudScript2 as CloudScript
+};

package/{code.command-3wkn4ja5.js → code.command-spsrzg63.js}

@@ -4,9 +4,9 @@ import {
   runner,
   script,
   command
-} from "./index-6jjtnhkw.js";
+} from "./index-3x7yeecy.js";
 import"./index-52w0fvh8.js";
-import"./index-55mynnqs.js";
+import"./index-bv210r6t.js";
 import {
   akanCodeDefaultModel2,
   CodeAgentStreamPrinter2
@@ -19,7 +19,7 @@ class CodeRunner extends runner("code") {
   async serve(options, listen) {
     await import("./consoleToStderr-h5bryj94.js");
     const [{ CodeAgent }, { CodeAgentRpcHost }, { CodeAgentRpcListener }] = await Promise.all([
-      import("./CodeAgent-kyprmy06.js"),
+      import("./CodeAgent-ctk4fh2b.js"),
       import("./CodeAgentRpcHost-p7h6n2hp.js"),
       import("./CodeAgentRpcListener-7p7z5dd7.js")
     ]);
@@ -34,8 +34,8 @@ class CodeRunner extends runner("code") {
   }
   async tui(options, seed) {
     const [{ CodeAgent }, { CodeTui }] = await Promise.all([
-      import("./CodeAgent-kyprmy06.js"),
-      import("./CodeTui-21mtze3j.js")
+      import("./CodeAgent-ctk4fh2b.js"),
+      import("./CodeTui-mrxtrdzw.js")
     ]);
     const agentOptions = await CodeRunner.#agentOptions(options, false);
     let resume = options.resume;
@@ -60,7 +60,7 @@ class CodeRunner extends runner("code") {
     }
   }
   async run(prompt, options) {
-    const { CodeAgent } = await import("./CodeAgent-kyprmy06.js");
+    const { CodeAgent } = await import("./CodeAgent-ctk4fh2b.js");
     const agent = await CodeAgent.create(await CodeRunner.#agentOptions(options, false));
     const printer = new CodeAgentStreamPrinter2({ json: options.json, thinking: options.thinking });
     agent.on((event) => printer.print(event));

package/{context.command-9jjn3gcw.js → context.command-768zv7z4.js}

@@ -2,24 +2,27 @@
 import {
   Workspace,
   command
-} from "./index-6jjtnhkw.js";
+} from "./index-3x7yeecy.js";
 import"./index-52w0fvh8.js";
-import"./index-55mynnqs.js";
+import"./index-bv210r6t.js";
 import"./index-hj6w4ka1.js";
-import"./index-05g3jayg.js";
-import"./index-2mx692qq.js";
-import"./index-ae5pwhgs.js";
-import"./index-1w2qaee2.js";
+import"./index-wdze51wz.js";
+import"./index-vhfjzda3.js";
+import"./index-r5d6rq19.js";
+import"./index-kmamh5bv.js";
+import"./index-qf8g88j9.js";
+import"./index-ec080x99.js";
 import"./index-zzvvc845.js";
-import"./index-fm46xrf1.js";
-import"./index-2etcv0sc.js";
-import"./index-e0cvze1s.js";
-import"./index-ctanya41.js";
-import"./index-c76k723e.js";
-import"./index-rwq3ekqc.js";
+import"./index-q5abh0jq.js";
+import"./index-00seamy5.js";
+import"./index-1nyxvz8j.js";
+import"./index-fjqvd5mx.js";
+import"./index-c4h5b5nq.js";
+import"./index-xf40a295.js";
 import {
   ContextScript
-} from "./index-8r4d7cmt.js";
+} from "./index-w9b71b6y.js";
+import"./index-2z3kykvd.js";
 
 // pkgs/@akanjs/cli/context/context.command.ts
 class ContextCommand extends command("context", [ContextScript], ({ public: target }) => ({

package/context.runner-tf1b53qq.js

@@ -0,0 +1,24 @@
+// @bun
+import {
+  ContextRunner2
+} from "./index-r5d6rq19.js";
+import"./index-xf40a295.js";
+import"./index-c4h5b5nq.js";
+import"./index-fjqvd5mx.js";
+import"./index-q5abh0jq.js";
+import"./index-1nyxvz8j.js";
+import"./index-00seamy5.js";
+import"./index-kmamh5bv.js";
+import"./index-qf8g88j9.js";
+import"./index-vhfjzda3.js";
+import"./index-wdze51wz.js";
+import"./index-zzvvc845.js";
+import"./index-3x7yeecy.js";
+import"./index-2z3kykvd.js";
+import"./index-ec080x99.js";
+import"./index-bv210r6t.js";
+import"./index-hj6w4ka1.js";
+import"./index-52w0fvh8.js";
+export {
+  ContextRunner2 as ContextRunner
+};

package/{guideline.command-dtczrqpf.js → guideline.command-4ycwc51q.js}

@@ -2,9 +2,9 @@
 import {
   script,
   command
-} from "./index-6jjtnhkw.js";
+} from "./index-3x7yeecy.js";
 import"./index-52w0fvh8.js";
-import"./index-55mynnqs.js";
+import"./index-bv210r6t.js";
 import {
   Prompter2
 } from "./index-zzvvc845.js";

package/guidelines/conventions/conventions.instruction.md

@@ -68,8 +68,9 @@ back.
   `*.{constant,dictionary,document,service,signal,store}.ts` / `*.{Template,Unit,Util,View,Zone}.tsx`
   (`no-import-external-library.grit`). Re-export the symbol through a lib first. One-line re-export shims in a lib's
   `common/`, `webkit/`, or `ui/` exist for exactly this reason — they are load-bearing, not cruft. A module's
-  `*.signal.test.ts` / `*.service.test.ts` is held to the same rule but may import the runtime's `node:*` and
-  `bun:*` modules (a temp dir, a socket, sqlite), which module code leaves to `srvkit/`.
+  `*.signal.test.ts` / `*.service.test.ts` is held to the same rule (`no-import-external-library-in-test.grit`) but
+  may import the runtime's `node:*` and `bun:*` modules (a temp dir, a socket, sqlite), which module code leaves to
+  `srvkit/`.
 - **`#private` is banned in exactly four file suffixes:** `*.constant.ts`, `*.document.ts`, `*.service.ts`, and
   `*.store.ts` (`no-js-private-class-method.grit`). The rule is scoped by file path, not by class shape, so
   `#private` remains the house style everywhere under `srvkit/`, including `adapt()` adapter classes.
@@ -389,8 +390,11 @@ Full contract: `get_guideline` with `runtimeRule`, or `akan guideline show runti
   `dist/native/<app>/<target>/build/<platform>`, a desktop app only for the OS that builds it — `--arch` picks
   a Windows or Linux app's CPU, and a macOS app is Apple silicon only. `--installer true` adds a Windows setup, a
   macOS dmg or a Linux AppImage; `--sign` signs with the identity `AKAN_NATIVE_MACOS_*` / `AKAN_NATIVE_WINDOWS_*`
-  names and `--notarize` uploads the signed macOS app to Apple — the env alone does neither. With `updates: { url, publicKey }` an installed app takes the signed
-  releases `akan publish-update` makes; `akan update-keygen` makes the key and prints its `publicKey`.
+  names and `--notarize` uploads the signed macOS app to Apple — the env alone does neither. With
+  `updates: { url, publicKeys }` an installed app takes the signed releases `akan publish-update` makes: 1 to 3 keys,
+  the online signing key first and offline spares after it (a key may revoke only those listed before it), of which a
+  desktop app trusts the first, or `publicKey` for one. `akan update-keygen` makes the key and prints it for
+  `publicKeys`.
 - **A desktop app that carries its server (`desktop: { server: true }` in `native`, or in one target) gets nothing
   from `docker`** — and `server: { omit: [...] }` leaves out packages only the image needs. That server is API-only, runs in database mode `single`, and listens on a loopback port any
   program on the computer can call, so guard its endpoints as a network server's. An executable the app spawns
@@ -532,7 +536,8 @@ workflow changes.
 - Keep execution contracts and triggers in `.signal.ts` classes built with `internal(...)`, `slice(...)`, and `endpoint(...)`.
 - Use `Internal` for internal triggers such as init, interval, cron, or queue jobs. A `process` job's
   `backoff: { type: "exponential", delay, maxDelay }` caps the wait between attempts, and the internal's
-  `onFailed(job, error)` runs once a job has failed its last attempt — the dead letter, on either queue.
+  `onFailed(job, error)` runs once a job has failed for good — its last attempt, or bullmq's stall limit — the dead
+  letter, on either queue.
 - Use `Slice` for typed data views that feed client stores and zones; keep each slice focused on one purpose.
 - Use `Endpoint` for query and mutation contracts exposed to callers.
 - Connect external APIs or infrastructure through adapters, usually under `srvkit/`, and inject them into services instead of importing vendor clients directly into domain logic.
@@ -755,13 +760,16 @@ Conventions that hold for both shapes:
 - Best-effort code returns a sentinel (`null`, `undefined`, `[0, 0]`, `{}`). There are no Result/Either wrappers.
 - `try/catch` is rare and always converts an exception into a decision, never swallows one. Guards catch → `logger.warn` → `return false`; adapters catch → `logger.error` → `return null`; UI uses `try/finally` to reset a spinner. A bodyless `catch {}` is acceptable only with a one-line reason.
 - Store actions do not `try/catch` — let the framework toast the `Err`. Client-side validation failure is `msg.error("<key>")` plus an early return, never a throw.
-- **A server-side `fetch.clone({ origin })` opens no websocket unless `connect: true`**: it makes one-off calls to
-  another server, and a socket it opened would reconnect forever with nobody to close it. It never carries the
-  visitor's session either: a call to another origin sends only the `jwt` its caller gave the clone.
+- **A server-side `fetch.clone({ origin })` opens no websocket unless `connect: true`**, and neither does a clone of
+  such a clone: it makes one-off calls to another server, and a socket it opened would reconnect forever with nobody
+  to close it. It never carries the visitor's session either: a call to another origin sends only the `jwt` its
+  caller gave the clone.
 - **Retry a call with `retry`, never with a loop of your own.** `fetch.clone({ origin, retry: {} })` (or a call's
   own `{ retry }`) tries again on an unreachable server, a 502/503/504 and a 429 after its Retry-After, backing off
-  with jitter; a mutation retries under one `Idempotency-Key` it mints, or the `idempotencyKey` you name, and the
-  server runs a mutation once per key and caller, answering a repeat with the first result. A 4xx is never retried.
+  with jitter until the call's one deadline runs out; a mutation retries under one `Idempotency-Key` it mints, or the
+  `idempotencyKey` you name, and the server runs a mutation once per key, caller and arguments, answering a repeat
+  with the first response as it was sent; a signed-out call, one whose handler returns a `Response`, and a call
+  through MCP run every time. A 4xx is never retried.
 - `String(err)` and `${err}` read `Err: <key> {…data}`, the data as one line of JSON with secret-named keys masked,
   so a ``logger.warn(`…: ${String(error)}`)`` keeps the exit code or status the `Err` carried.
 - **A failure another process reported travels as itself.** A server-to-server `fetch.<endpoint>(..., { origin })` restores the remote `Err` — the same class, key and `data` — so a hop that rethrows it answers its own caller with that error and the dictionary translates it. Never wrap the catch in a `new Error`, and never re-key it as a `new Err` of your own: both discard what the endpoint chose to say, and a bare `Error` is generalized to `Internal Server Error` on the way out.
@@ -831,6 +839,10 @@ it.
 - **A `field.visual` field is stripped from every MCP result** and from the readable schema so the two agree.
 - **A structured result ships twice by default** — as `structuredContent` and as the same JSON in the text block.
   `option.setMcp({ legacyTextBlock: false })` leaves a pointer there instead.
+- **A picture is an `ImageResult` return** (`akanjs/base`): `query(ImageResult, { guards })` returns `{ data,
+  mimeType, caption? }` — padded base64 with no `data:` prefix, and `image/png` / `jpeg` / `webp` / `gif`. Over MCP it
+  answers the caption as a text block and the picture as an image block, with no `structuredContent`; over HTTP it
+  is that JSON object. Like `Binary` it is never a model field.
 - **A prompt is a screen: `page().prompt(name, description)`.** There is no `prompt()` on `endpoint()`.
   `prompts/get` runs the page's body in the RSC worker under the caller's token — nothing is rendered — and answers
   the description, one `resource` per `fetch.*` the page made (masked by the endpoint's return model, addressed by
@@ -844,9 +856,9 @@ it.
   ChatGPT, VS Code) shows the screen itself in the chat — the CSR bundle in a sandboxed iframe whose every call the
   host relays under the agent's token. It shows the page alone: every layout above it still runs (guards, providers,
   `<Agent.Guide>`) and draws nothing, unless it draws no page, as a gate does. Nothing is written for the view. An
-  endpoint kept off the shelf only by `mcp: false` stays callable by that view and is listed to no model; a `Person`
-  act is still refused there. `option.setMcp({ apps: false })` keeps pages prompts only, and a page named like an
-  endpoint stays one (boot warns).
+  endpoint kept off the shelf only by `mcp: false`, and the generated `light<Model>` read, stay callable by that view
+  and are listed to no model; a `Person` act is still refused there. `option.setMcp({ apps: false })` keeps pages
+  prompts only, as a read-only deployment does, and a page named like an endpoint stays one (boot warns).
 
 Full contract — configuration, wire behaviour, resource URIs, OAuth metadata, protocol revisions, and
 `McpProgress.report`: `get_guideline` with `mcpRule`, or `akan guideline show mcpRule`.
@@ -909,7 +921,7 @@ what every developer must know even when not building one.
 
 ### Scalar & Field Type Reference
 
-- **Import from `akanjs/base`** (real classes/helpers, not globals): `Int`, `Float`, `ID`, `Any`, `Binary`, `Upload`, `enumOf`, and the `dayjs` factory. There is **no `JSON` scalar** — use `Any` for open/flexible payloads.
+- **Import from `akanjs/base`** (real classes/helpers, not globals): `Int`, `Float`, `ID`, `Any`, `Binary`, `Upload`, `ImageResult`, `enumOf`, and the `dayjs` factory. There is **no `JSON` scalar** — use `Any` for open/flexible payloads.
 - **Use the JS globals directly (no import needed)**: `String`, `Boolean`, `Date`. They are monkey-patched to behave like scalars, so `field(String)` typechecks.
 - **`Number` is not a valid field/body type.** `NumberConstructor` is intentionally not augmented, so `field(Number)` / `.body("x", Number)` fails to typecheck. Use `Int` or `Float` instead.
 - Runtime resolution of every scalar (globals included) goes through `PrimitiveRegistry` by `refName` (`pkgs/akanjs/base/primitiveRegistry.ts`).
@@ -997,7 +1009,8 @@ shape, so `cascade` never means "related" — it means one of exactly these:
   of the route's args returning it, and one that throws renders no head (warned about) so a layout's sign-in redirect
   still answers; there is no metadata object, and analytics is the app's own script, not a stage.
   Heads merge root first: a deeper `.head()` replaces the `<title>`, a `<meta>` with the same `name` / `property`,
-  and a canonical / manifest / icon link, and keeps the rest — so a page states only what it changes.
+  and a canonical / manifest / icon link, and keeps the rest — so a page states only what it changes. A canonical
+  link and `og:url` each name one URL, so a page carries them only from its own `.head()`, never from a layout's.
 - **A CSR bundle (a native app, `?csr=true`) never shows a root layout's own markup.** Pages render into the
   frame, and what the root layout draws around `{children}` stays in a hidden container, so its wrappers cannot
   stack a second screen beside the frame. Its components still mount and their effects run (`<Auth.User />` works).

package/guidelines/cssRule/cssRule.instruction.md

@@ -64,19 +64,25 @@ Screen code is invariant — a plain `<Button variant="primary">` never changes.
 
 ## 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:
+The frame writes these on `#frameRoot` and `<html>`, so any class can read them. The insets and the content height
+are there on every surface; the three keyboard variables are written only on the server-rendered web:
 
 - `--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.
+  layout) and `0px` where it does not, and `env()` measures nothing unless the viewport meta carries
+  `viewport-fit=cover` — the root layout's `.viewport({ fitCover: true })`, which a native app has by default; 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).
+  page's bottom, the visible height, and how far iOS panned the page to show a field (the top slots follow it). Only
+  an SSR page in a browser writes them; a CSR bundle and a native app never do, so read them with a fallback
+  (`var(--akan-keyboard-inset, 0px)`), or take the keyboard from the store's `keyboardHeight`, which a native app's
+  keyboard plugin fills.
 - `--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.

package/guidelines/mcpRule/mcpRule.instruction.md

@@ -155,6 +155,17 @@ export default page()
   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. `resources/read` is unaffected too: `ReadResourceResult` has no
   `structuredContent`, so a resource's text is its only channel and always carries the serialized value.
+- **A picture is an `ImageResult` return, and the one result a model sees rather than reads.**
+  `query(ImageResult, { guards: [...] })` (or `[ImageResult]`) returns `{ data, mimeType, caption? }`: `data` is
+  padded standard base64 with no `data:` prefix, `mimeType` one of `image/png`, `image/jpeg`, `image/webp`,
+  `image/gif` — the types the Anthropic and OpenAI models take. `tools/call` answers the caption as a text block and
+  the picture as an image block, one pair per picture, and publishes no `outputSchema` and no `structuredContent`:
+  either would repeat the base64, a few hundred KB, as text the model pays for and cannot see. A value that breaks
+  the shape is not sent — the dispatcher logs what an `ImageResult` needs and answers the generic failure. Put in
+  the caption what the picture cannot say on its own (the region or scale it spans). Over HTTP the endpoint is the
+  JSON object, so the app's own client and tests read it as usual; everywhere else an agent reads it — a page
+  prompt's resource, the in-page agent — its agent face carries `mimeType` and `caption` only. Nothing caps the
+  size, and Anthropic refuses an image over 5 MB, so keep a picture well under that. It is never a model field.
 - **A request schema asks for a relation's id, and a response schema names a nested model.** `serialize` sends a
   relation field as its id and the server never converts an object back, so publishing the related model's shape
   asked an agent for what the document layer cannot take. On the response side every entry inlines the transitive
@@ -231,9 +242,10 @@ 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 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.
+  gone". **While a `.prompt()` page 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.
+  `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
@@ -362,7 +374,8 @@ rule: a page taking no arguments is the most useful prompt, since MCP has no com
 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
+**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
@@ -371,14 +384,17 @@ in a sandboxed iframe started on the page the tool ran. Its first queries are an
 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.
+- **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.
 - **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.
+  `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