@akanjs/cli 3.0.2-rc.0 → 3.1.0-rc.0

package/cloud.command-kk2rwkvw.js

@@ -0,0 +1,187 @@
+// @bun
+import {
+  App,
+  Workspace,
+  command
+} from "./index-6jjtnhkw.js";
+import"./index-52w0fvh8.js";
+import"./index-55mynnqs.js";
+import"./index-kjvrq3nc.js";
+import"./index-r2tpeb3n.js";
+import {
+  PlatformTestRun
+} from "./index-y8q31011.js";
+import"./index-k9rrten6.js";
+import"./index-c1x0be5j.js";
+import"./index-p9ystjrp.js";
+import"./index-7md2g9vw.js";
+import"./index-2ahj896a.js";
+import"./index-gnyf1fqy.js";
+import {
+  CloudScript2
+} from "./index-tn4rpqp1.js";
+import"./index-qt22xstj.js";
+import {
+  getMobileTargetChoices
+} from "./index-q958tqqg.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) {
+    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) {
+    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, {
+    desc: "registry target for publishing Akan packages",
+    ask: "Select a registry target",
+    enum: [
+      { label: "local", value: "local" },
+      { label: "npm", value: "npm" }
+    ]
+  }).option("platforms", String, {
+    desc: "platforms to test on besides this machine, comma-separated: linux, windows (none to skip)",
+    default: "linux,windows"
+  }).with(Workspace).exec(async function(test, registry, platforms, workspace) {
+    await this.cloudScript.deployAkan(workspace, {
+      test,
+      registryUrl: resolveRegistryUrl(registry),
+      platforms: PlatformTestRun.parsePlatforms(platforms)
+    });
+  }),
+  testPlatforms: target({
+    devOnly: true,
+    desc: "Run the Akan package suites on Linux (Docker) and Windows (SSH) against a snapshot of this tree"
+  }).option("platforms", String, {
+    desc: "platforms to test on, comma-separated: linux, windows",
+    default: "linux,windows"
+  }).option("pkgs", String, {
+    flag: "k",
+    desc: "packages to test, comma-separated (default: every Akan package)",
+    nullable: true
+  }).with(Workspace).exec(async function(platforms, pkgs, workspace) {
+    await this.cloudScript.testPlatforms(workspace, {
+      platforms: PlatformTestRun.parsePlatforms(platforms),
+      pkgs: pkgs?.split(",").map((pkg) => pkg.trim()).filter(Boolean)
+    });
+  }),
+  update: target({ desc: "Update Akan.js framework to the latest version" }).with(Workspace).option("tag", String, {
+    desc: "tag of the update",
+    default: "latest",
+    enum: ["latest", "dev", "canary", "beta", "rc", "alpha"]
+  }).option("registry", String, {
+    desc: "registry target for resolving Akan packages",
+    ask: "Select a registry target",
+    enum: [
+      { label: "npm", value: "npm" },
+      { label: "local", value: "local" }
+    ],
+    default: process.env.USE_AKANJS_PKGS === "true" ? undefined : "npm"
+  }).exec(async function(workspace, tag, registry) {
+    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 }).with(Workspace).exec(async function(app, platform, target, env, channel, notes, subspace, host, write, allowLocalRelease, workspace) {
+    await this.cloudScript.pushUpdate(workspace, app, {
+      platform,
+      target,
+      env,
+      channel,
+      notes,
+      subspace,
+      host,
+      write,
+      allowLocalRelease
+    });
+  }),
+  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"
+  }).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) {
+    await this.cloudScript.registerBinary(workspace, app, {
+      platform,
+      distribution,
+      target,
+      env,
+      subspace,
+      host,
+      write,
+      allowLocalRelease
+    });
+  }),
+  uploadSecret: target({
+    desc: "Upload a named pipeline secret to the akasys 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) {
+    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, {
+    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) {
+    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, {
+    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) {
+    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) {
+    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) {
+    await this.cloudScript.uploadEnv(workspace, { host });
+  })
+})) {
+}
+export {
+  CloudCommand
+};

package/cloud.script-r7eyfey4.js

@@ -0,0 +1,20 @@
+// @bun
+import {
+  CloudScript2
+} from "./index-tn4rpqp1.js";
+import"./index-y8q31011.js";
+import"./index-p9ystjrp.js";
+import"./index-qt22xstj.js";
+import"./index-c1x0be5j.js";
+import"./index-gnyf1fqy.js";
+import"./index-kjvrq3nc.js";
+import"./index-r2tpeb3n.js";
+import"./index-6jjtnhkw.js";
+import"./index-7md2g9vw.js";
+import"./index-k9rrten6.js";
+import"./index-55mynnqs.js";
+import"./index-2ahj896a.js";
+import"./index-52w0fvh8.js";
+export {
+  CloudScript2 as CloudScript
+};

package/{code.command-hmtx14b2.js → code.command-30sca09d.js}

@@ -4,9 +4,9 @@ import {
   runner,
   script,
   command
-} from "./index-q6ft9fkc.js";
+} from "./index-6jjtnhkw.js";
 import"./index-52w0fvh8.js";
-import"./index-50wb2a26.js";
+import"./index-55mynnqs.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-szbjv4gv.js"),
+      import("./CodeAgent-q7a4srt6.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-szbjv4gv.js"),
-      import("./CodeTui-5nw86ab6.js")
+      import("./CodeAgent-q7a4srt6.js"),
+      import("./CodeTui-ak23dxc9.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-szbjv4gv.js");
+    const { CodeAgent } = await import("./CodeAgent-q7a4srt6.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/commandManifest.json

@@ -1 +1 @@
-{"byCommand":{"create-workspace":"workspace","generate-agent-rules":"workspace","lint":"workspace","lint-all":"workspace","sync-all":"workspace","init":"workspace","agent":"agent","code":"code","create-application":"application","remove-application":"application","plan-slice":"application","sync":"application","script":"application","console":"application","logs":"application","build":"application","b":"application","typecheck":"application","t":"application","test":"application","build-ios":"application","bi":"application","build-android":"application","ba":"application","build-desktop":"application","bd":"application","start":"application","s":"application","start-ios":"application","si":"application","start-android":"application","sa":"application","start-desktop":"application","sd":"application","release-ios":"application","release-android":"application","pack-update":"application","update-keygen":"application","publish-update":"application","dbup":"application","db-export":"application","db-import":"application","dbdown":"application","create-library":"library","remove-library":"library","sync-library":"library","library-status":"library","install-library":"library","start-registry":"localRegistry","reset-registry":"localRegistry","smoke-registry":"localRegistry","version":"package","create-package":"package","remove-package":"package","sync-package":"package","build-package":"package","verify-dist-package":"package","verify-akan-publish-packages":"package","create-module":"module","remove-module":"module","create-service":"module","create-view":"module","create-unit":"module","create-template":"module","create-crud-page":"page","context":"context","doctor":"context","mcp-install":"context","mcp":"context","mcp-call":"context","login":"cloud","logout":"cloud","deploy-akan":"cloud","test-platforms":"cloud","update":"cloud","download-env":"cloud","upload-env":"cloud","subspace":"subspace","guideline":"guideline","create-scalar":"scalar","remove-scalar":"scalar","create-ui":"primitive","add-field":"primitive","add-enum-field":"primitive","quality":"quality","repair":"repair","workflow":"workflow","tunnel":"tunnel"}}
+{"byCommand":{"create-workspace":"workspace","generate-agent-rules":"workspace","lint":"workspace","lint-all":"workspace","machine-keygen":"workspace","sync-all":"workspace","init":"workspace","agent":"agent","code":"code","create-application":"application","remove-application":"application","plan-slice":"application","sync":"application","script":"application","console":"application","logs":"application","build":"application","b":"application","typecheck":"application","t":"application","test":"application","build-ios":"application","bi":"application","build-android":"application","ba":"application","build-desktop":"application","bd":"application","start":"application","s":"application","start-ios":"application","si":"application","start-android":"application","sa":"application","start-desktop":"application","sd":"application","release-ios":"application","release-android":"application","pack-update":"application","update-keygen":"application","publish-update":"application","dbup":"application","db-export":"application","db-import":"application","dbdown":"application","create-library":"library","remove-library":"library","sync-library":"library","library-status":"library","install-library":"library","start-registry":"localRegistry","reset-registry":"localRegistry","smoke-registry":"localRegistry","version":"package","create-package":"package","remove-package":"package","sync-package":"package","build-package":"package","verify-dist-package":"package","verify-akan-publish-packages":"package","create-module":"module","remove-module":"module","create-service":"module","create-view":"module","create-unit":"module","create-template":"module","create-crud-page":"page","context":"context","doctor":"context","mcp-install":"context","mcp":"context","mcp-call":"context","login":"cloud","logout":"cloud","deploy-akan":"cloud","test-platforms":"cloud","update":"cloud","push-update":"cloud","register-binary":"cloud","upload-secret":"cloud","list-secrets":"cloud","remove-secret":"cloud","download-env":"cloud","upload-env":"cloud","subspace":"subspace","guideline":"guideline","create-scalar":"scalar","remove-scalar":"scalar","create-ui":"primitive","add-field":"primitive","add-enum-field":"primitive","quality":"quality","repair":"repair","workflow":"workflow","pipeline":"pipeline","tunnel":"tunnel"}}

package/{context.command-6aqvdx43.js → context.command-k7eqacq6.js}

@@ -2,24 +2,24 @@
 import {
   Workspace,
   command
-} from "./index-q6ft9fkc.js";
+} from "./index-6jjtnhkw.js";
 import"./index-52w0fvh8.js";
-import"./index-50wb2a26.js";
+import"./index-55mynnqs.js";
 import"./index-hj6w4ka1.js";
-import"./index-h9ht6s60.js";
-import"./index-zyw622y1.js";
-import"./index-j38qkvkk.js";
-import"./index-jk9xnck6.js";
+import"./index-05g3jayg.js";
+import"./index-2mx692qq.js";
+import"./index-0bm04n5g.js";
+import"./index-kjvrq3nc.js";
 import"./index-zzvvc845.js";
-import"./index-hp3stk1m.js";
-import"./index-g38nhv87.js";
-import"./index-f4e08ptp.js";
-import"./index-6keyf4sg.js";
-import"./index-cb6yc5mb.js";
-import"./index-bsv901fd.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 {
   ContextScript
-} from "./index-zwd84m0w.js";
+} from "./index-jyv387qw.js";
 
 // pkgs/@akanjs/cli/context/context.command.ts
 class ContextCommand extends command("context", [ContextScript], ({ public: target }) => ({

package/context.runner-hqd1ppqe.js

@@ -0,0 +1,21 @@
+// @bun
+import {
+  ContextRunner2
+} from "./index-0bm04n5g.js";
+import"./index-rwq3ekqc.js";
+import"./index-c76k723e.js";
+import"./index-ctanya41.js";
+import"./index-fm46xrf1.js";
+import"./index-e0cvze1s.js";
+import"./index-2etcv0sc.js";
+import"./index-kjvrq3nc.js";
+import"./index-2mx692qq.js";
+import"./index-05g3jayg.js";
+import"./index-zzvvc845.js";
+import"./index-6jjtnhkw.js";
+import"./index-55mynnqs.js";
+import"./index-hj6w4ka1.js";
+import"./index-52w0fvh8.js";
+export {
+  ContextRunner2 as ContextRunner
+};

package/{guideline.command-axvf68gc.js → guideline.command-dtczrqpf.js}

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

package/guidelines/agentRule/agentRule.instruction.md

@@ -47,7 +47,9 @@ pages declaring one name never clash, and a registry kept outside the surface re
   `AgentProvider` or an `Agent.Zone` belongs to whoever provided it.
 - **The panel is customized in three widening steps, and most designs stop at the first.** Props first:
   `open` / `onOpenChange` drive it from the app's own control (`launcher={false}` then draws no launcher of its
-  own), `launcherClassName` / `panelClassName` reach one surface each where `className` reaches both, `intro`
+  own), `launcherPlacement` / `hideLauncherBelow` place the launcher — which sits above the page's bottom chrome
+  and under every menu and modal — `launcherClassName` / `panelClassName` reach one surface each where
+  `className` reaches both, `intro`
   replaces the empty-state line — where starter questions go — and `header` adds controls beside the built-in
   clear and close. `chrome={false}` drops the header bar whole, for an `inline` chat inside a panel the app
   already titles, and `defaultDraft` opens the composer with text in it without sending it. A panel driven by a
@@ -306,7 +308,9 @@ pages declaring one name never clash, and a registry kept outside the surface re
   an inline arrow can be clicked by a person and by nobody else. `.desc()` is required and comes first, `.arg()`
   is an argument the caller must pass and `.opt()` one it may leave out (the `exec` parameter is then `| null`),
   and `.exec()` is the only hook, so the chain completes in one unconditional statement and the callable carries
-  `data-akan-action` like a store setter does. A `remove*` name defaults to a confirm gate. Reach a store action
+  `data-akan-action` like a store setter does. A `remove*` name defaults to a confirm gate. `st.tool("x", { label:
+  l("ticket.archive") })` gives the action a name a person reads — `Agent.useScreenActions()` hands it to a command
+  palette, and the model never sees it. Reach a store action
   from the body — `.exec((id) => st.do.removeX(id))` — which is how an agent gets CRUD; `st.do` on its own
   reaches nobody.
 - **`.card()` is the other way the chain ends, for an answer that is the user's to give.** Where `.exec()` runs a
@@ -357,6 +361,10 @@ pages declaring one name never clash, and a registry kept outside the surface re
   (a different `modal`, a different redirect) cannot honestly share a description, and that pair wants a
   `namespace` or nothing at all. The ids come from the `<slice>.items` resource `Load.Units` and
   `Data.ListContainer` already expose.
+- **A command palette lists the same declarations.** `Agent.useScreenActions()` returns the screen's published
+  tools that take no required argument, each with a `run` that calls the control's own handler (guard included,
+  not logged as an agent call) and `needsConfirm` for the ones a person should confirm — so ⌘K offers exactly
+  what the agent can do here, with nothing declared twice.
 
 ## What `akanjs/ui` Publishes For You
 - **`akanjs/ui` publishes its own controls, so an app writes nothing for them.** `Data.ListContainer` (and every

package/guidelines/conventions/conventions.instruction.md

@@ -67,7 +67,9 @@ back.
 - **Never import a third-party package** from `page/**`, from any barrel, or from any
   `*.{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.
+  `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/`.
 - **`#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.
@@ -202,6 +204,13 @@ back.
 - Prefer focused behavior tests for public contracts and edge cases over implementation-detail assertions.
 - Run package suites with `bun run akan test <pkg>` from the repo root, or `cd <pkg> && bun test --isolate`. Plain `bun test` without `--isolate` shares one global object across test files and fails dozens of tests from cross-file state pollution (`bunfig.toml` `[test] isolate` is not honored as of Bun 1.3), and running `bun test` from the repo root breaks subprocess stdio pipes.
 - Split signal tests in two. `<model>.signal.spec.ts` holds reusable fixtures built on `sampleOf(cnst.XInput)` with explicit `Promise<cnst.X>` return types and **no assertions**. `<model>.signal.test.ts` holds the assertions: `describe("<Model> Signal")`, `let` fixtures at describe scope, one `beforeAll`, story-ordered `it`s, and negatives via `await expect(p).rejects.toThrow()`.
+- **One suite per module file, named after it.** A module test is `<model>.<role>.test.ts` beside the file it covers
+  (`chatMessage.signal.test.ts`, `chatMessage.service.test.ts`, `ChatMessage.Zone.test.tsx`). Never split one role
+  across topic files such as `chatMessage.trim.signal.test.ts` / `chatMessage.security.signal.test.ts` — add a
+  `describe` block to the existing suite. A suite that drives several modules (guards across models, an app's MCP
+  exposure list) belongs to none of them and goes in `srvkit/`, like `libs/shared/srvkit/guards.signal.test.ts`.
+  Never put a test at the `lib/` root. `akan sync` refuses all three shapes. Nothing imports a test, so a build never
+  typechecks one; `akan typecheck <app-or-lib>` does, `bun:test` types included.
 - `lib/user/user.signal.spec.ts` is the one place agent types are re-exported and re-typed; import `UserAgent` / `AdminAgent` from there rather than from the owning lib directly.
 - A placeholder `it` with a descriptive title is an acceptable floor. Write a real suite when the behaviour is security-relevant.
 
@@ -310,11 +319,11 @@ are, because those are the ones the server could have done.
    consume them in a server component, never as a `Zone` prop.
 6. **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 renders only the last two today, so
-   copy the shape rather than the component.
+   is the shape: `title` / `left` / `right` beside `back` and `children`, each filled by the server.
 7. **Let the server do the derived work.** Display and predicate logic belongs on `Light<Model>`; enum→class
    lookups belong in a module-scope `as const` map.
-8. **Gate auth on the server** — `getSelf({ unauthorize: "/signin" })` in `_layout.tsx`, before any HTML is sent.
+8. **Gate auth on the server** — `getSelf({ unauthorize: "/signin" })` in `_layout.tsx`, before any of the page's
+   markup renders. After its fetch the redirect is an in-page one (HTTP 200); `.config({ ssr: "block" })` makes it a 3xx.
 9. **Prefer CSS over client state for pure visibility.** A `data-*` attribute plus `group-data-[…]` variants, or
    `<details>`/`<summary>`, keeps both branches server-rendered.
 10. **Keep the heavy island out of the first load** — behind the `ui/<Folder>/index_.tsx` + `lazy()` pair.
@@ -379,8 +388,8 @@ Full contract: `get_guideline` with `runtimeRule`, or `akan guideline show runti
   from `akan start`; `build-ios` / `build-android` / `build-desktop` write
   `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; `AKAN_NATIVE_MACOS_*` signs with a Developer ID and notarizes,
-  `AKAN_NATIVE_WINDOWS_*` signs with Authenticode. With `updates: { url, publicKey }` an installed app takes the signed
+  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`.
 - **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
@@ -393,7 +402,9 @@ Full contract: `get_guideline` with `runtimeRule`, or `akan guideline show runti
   `NativeFile.resolve(grant, "read")` in `akanjs/server` asks the shell for it. What it carries is readable on the
   user's computer — `private/` (each lib's too, under `private/libs/<lib>`), the one `env.server.<env>.ts` of its
   `--env` and its libs' server env defaults (`env.server.testing.ts`) — and it has no `public/`: read runtime files
-  from `AKAN_APP_DIR`, never `process.cwd()`.
+  from `AKAN_APP_DIR`, never `process.cwd()`. **`server: { profile: "edge" }` bundles `env.server.<env>.edge.ts` in
+  that file's place**, and the build refuses one holding a secret-named value; `server: { modules: ["@edge"] }`
+  mounts only the modules whose `serve()` lists `operationMode: ["edge"]`, and what they reach.
 - **`assets: { pruneFonts, keepFonts }`** trims from the `dist` copy of `public/` the fonts nothing reads; source
   trees are never touched. A font with `optimize` on is a build input, not a runtime asset. `keepFonts` belongs to
   the `akan.config.ts` that owns the font, written against that scope's own `public/`.
@@ -481,7 +492,9 @@ count was shortened to `count(query)`, with `countDocuments` kept as `@deprecate
 `removeById(id)` are those same query-level writes narrowed to one id, **not** the document path: they fire no hooks,
 so a model whose removal cascades or carries a `_postRemove` still goes through `remove<Model>(id)`. The
 write-through pair is `pickAndWrite(id, data)` / `pickOneAndWrite(query, data)` — pick the document, write into it
-and save it, so the save hooks do run; reach for those when the write has to be seen by them.
+and save it, so the save hooks do run; reach for those when the write has to be seen by them. `upsertById(data, {
+preserveTimestamps })` writes a record whole under its own id, new or in place, with no hook: the write a sync or a
+backfill repeats safely, keeping the record's `createdAt`/`updatedAt` when asked.
 
 **`<model>.service.ts`** — keep methods to a few lines: load → chain → `return await ….save()`. Write `return await`
 explicitly in tail position; do not "optimize" it away. Side effects belong in `override async _preUpdate` /
@@ -517,7 +530,9 @@ workflow changes.
 
 - Keep domain business operations in `.service.ts` classes built with `serve(...)`.
 - 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.
+- 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.
 - 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.
@@ -541,6 +556,11 @@ Full contract — credential handshake, room revalidation, socket cleanup scopin
   inside a guard or middleware). Behind a federation gateway, `ws.remoteAddress` and the child's own peer are the
   *gateway* (`127.0.0.1`) for every caller and for the whole life of every socket. `Ip` reads what a proxy
   recorded, is unwrapped from its `::ffff:` form, and is `null` rather than a placeholder when genuinely unknown.
+- **A device or another server proves itself with a machine token, never a staff session.**
+  `MachineToken.issue({ kind, id, version })` (`akanjs/server`) signs one with `AKAN_MACHINE_PRIVATE_KEY` (made by
+  `akan machine-keygen <file>`), with no expiry; a server holding that key or `AKAN_MACHINE_PUBLIC_KEY` sets
+  `account.machine` from a verified one on HTTP and websocket alike, and only from one. Read it with `.with(Machine)`
+  or in a guard, and revoke by bumping the version the guard compares to the record's own.
 - **Every socket carries a `socketId`, and only the framework mints one** — read 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
@@ -603,7 +623,7 @@ Full contract — credential handshake, room revalidation, socket cleanup scopin
 
 - `.body(...)` / `.param(...)` args accept `ConstantFieldTypeInput` only: scalars, model refs, or `enumOf(...)`.
 - Numbers must use `Int` or `Float` — `Number` is rejected (`pkgs/akanjs/signal/endpointInfo.ts`).
-- `Upload` is valid only inside a mutation flagged for file upload: `mutation([cnst.File], { fileUpload: true }).body("files", [Upload])`, as the `file` module does. It is not a model field type.
+- `Upload` is valid only inside a mutation flagged for file upload: `mutation([cnst.File], { fileUpload: true }).body("files", [Upload])`, as the `file` module does. It is not a model field type. The other body args of such a mutation arrive typed as in a JSON body. A file's `type` on the server is what its name implies, not its bytes — check the bytes when the type matters.
 - Bytes are `Binary`, never `Any` — see Scalar & Field Type Reference. A `Binary` return travels as base64 in an
   HTTP body, and a return declared `Any` that turns out to be bytes fails instead of reaching the caller as `{}`.
 
@@ -669,7 +689,8 @@ Full contract — filter-arg `ref` pickers, `getQueryMeta` summary counters, `la
   "archived" })`. The patch cannot trail the filter args, so it lands on a terminal `.set()`; building the chain
   touches nothing.
 - `removeOne` / `updateOne` hit the **newest** match, always, and report only counts — they are for "there is at
-  most one of these", not for claiming the next item off a queue.
+  most one of these", not for claiming the next item off a queue. A condition in the query is a compare-and-set in
+  every mode: of two concurrent calls that both saw the row match, one applies, and `modifiedCount` says which.
 - **A filter may not be keyed after its own model.** 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.
 - **"Has no value" is `q.empty`, never `q.missing`.** `q.missing` is the key being *absent from the stored JSON*,
@@ -735,7 +756,12 @@ Conventions that hold for both shapes:
 - `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.
+  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.
 - `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.
@@ -768,9 +794,10 @@ it.
   `Person` for an act reserved for a person, `mcp: { cru: false }` for the tools whose input models cost the model
   tokens, `outputSchema` for nothing that reaches the model.
 - Settings live in the app's `lib/option.ts` — `option.setMcp({ enabled, readOnly, path, version, instructions,
-  allowedOrigins, pageSize, language, outputSchema, rateLimit, auth })`, or `setMcp((env) => …)` for one derived from the server env, **not
+  allowedOrigins, pageSize, language, outputSchema, rateLimit, apps, modern, auth })`, or `setMcp((env) => …)` for one derived from the server env, **not
   `main.ts`**. Each field has an `AKAN_MCP_*` env spelling. `AKAN_MCP_READONLY=true` is the read-only-deployment
-  valve, not the exposure switch; `AKAN_MCP=false` takes the whole surface off. Every call that executes an
+  valve, not the exposure switch; `AKAN_MCP=false` takes the whole surface off, and an edge server
+  (`AKAN_PUBLIC_OPERATION_MODE=edge`) starts with it off unless `AKAN_MCP=true` or `setMcp(true)`. Every call that executes an
   endpoint is rate-limited per caller (120 a minute, 8 in flight, per process; 429 + `Retry-After`) — `rateLimit`
   / `AKAN_MCP_RATE_LIMIT` tunes or disables it.
 - **Authentication is the same server.** An app mounting `libs/shared` serves the OAuth 2.1 authorization server
@@ -811,7 +838,13 @@ it.
   from, minus what is already attached; lists — only lists — are cut to `promptBudget`. A guard refusing a query
   inside the body reads as the screen refusing the account, the same way a redirect does. A
   required argument left out answers a pointer to the `<model>List…` tool, never a guess. The description is the
-  only instruction, in English — `<Agent.Guide>` never reaches MCP, and the in-page chat lists no page prompts.
+  only instruction, in English — `<Agent.Guide>` never reaches a prompt, and the in-page chat lists no page prompts.
+- **The same page is a tool too, and an MCP Apps host renders it.** A `.prompt()` page answers `tools/call` with
+  that briefing plus its web URL, and a host that declares the `io.modelcontextprotocol/ui` extension (claude.ai,
+  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. 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).
 
 Full contract — configuration, wire behaviour, resource URIs, OAuth metadata, protocol revisions, and
 `McpProgress.report`: `get_guideline` with `mcpRule`, or `akan guideline show mcpRule`.
@@ -905,7 +938,7 @@ Full contract — the trigger-maintained mirror, tokenizer changes, `AKAN_SEARCH
   backstop, including for a `text` field *underneath* one of those. Do not work around either.
 - The role works on a relation (`image: field(File, { text: "thumb" })`) and on an array; an array of objects
   indexes by leaf key. A field inside a `Map` indexes nothing — there is no fixed path to extract it from.
-- Search runs in every database mode — fts5 on SQLite/libSQL, a weighted `tsvector` (`pg_trgm` for `trigram`) on
+- Search runs in every database mode — fts5 on SQLite, a weighted `tsvector` (`pg_trgm` for `trigram`) on
   Postgres. The same text matches the same documents; only the order may differ on Postgres.
 
 ### Image & File Fields
@@ -957,9 +990,12 @@ shape, so `cascade` never means "related" — it means one of exactly these:
   `_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()` on the root layout; `.prompt()` on a page. A named export beside the chain, or `page()` in a
-  `_layout.tsx`, fails the build. `.head()` takes JSX — `<title>`, `<meta>`, `<link>` — or a function of the
-  route's args returning it; there is no metadata object, and analytics is the app's own script, not a stage.
+  `.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. `.head()` takes JSX — `<title>`, `<meta>`, `<link>` — or a function
+  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.
 - **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).
@@ -971,7 +1007,9 @@ shape, so `cascade` never means "related" — it means one of exactly these:
   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")`. `lang` is
-  never declared: every route sits under `/:lang`, and the locale segment reaches every stage as `lang`.
+  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 hydration, so
+  an effect that needs the query on its first run takes the page's `.search()` value as a prop.
 - `_overrides.tsx` is a logic-free UI-override manifest: imports plus a single `export default override({ Slot: AppComponent })` (from `akanjs/ui`), no `"use client"`. It re-skins framework `akanjs/ui` components for its route subtree; nested manifests merge over ancestors slot-by-slot (closest wins). See the UI Customization reference for the slot list.
 - The legacy shape — `export default async function Page` beside `pageConfig` / `head` / `Loading` exports — still
   loads and logs one deprecation warning per file at boot. Migrate with the `workspaceRecipes` recipe "Migrating
@@ -988,10 +1026,10 @@ shape, so `cascade` never means "related" — it means one of exactly these:
 export default page()
   .param("orgId", ID)
   .config({ transition: "stack" })
-  .render(async ({ orgId }) => {
+  .render(({ orgId }) => {
     const { l } = usePage();
     getSelf({ unauthorize: "/signin" });
-    const [{ org }, { taskInitInOrg }] = await Promise.all([fetch.viewOrg(orgId), fetch.initTaskInOrg(orgId)]);
+    const { taskInitInOrg } = fetch.initTaskInOrg(orgId);
     return <Task.Zone.Card init={taskInitInOrg} prefix={`/org/${orgId}`} />;
   });
 ```
@@ -999,7 +1037,8 @@ export default page()
 - 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.
 - Body order inside `.render()`: `usePage()`, auth, fetch, return.
-- Run independent fetches through `Promise.all`, even when there is only one.
+- Hand each `fetch.init*` / `view*` / `edit*` field to its section unawaited. Await only what the shell itself
+  reads — a title, a redirect, an id for a link — and run those awaits through one `Promise.all`.
 - Gate auth at `_layout.tsx`; repeating `getSelf({ unauthorize: "/signin" })` in the page is fine and common.
 - `async` on the render callback only when the body awaits; the callback is not a React component, so it takes no
   name and no return type.
@@ -1020,12 +1059,12 @@ export default page()
   content outside the markers is yours. `akan lint` fails when the generated section is stale.
 - The `plugin/` facet holds Akan plugin declarations; files use the `<name>.plugin.ts` convention (e.g. `pushNotification.plugin.ts`) and are re-exported from the generated `plugin/index.ts` barrel.
 - Do not add `apps/*/base` or `libs/*/base`; place shared utilities under that app or lib's own `common/`.
-- `apps/*/lib` and `libs/*/lib` root files are limited to generated/support files: `cnst.ts`, `db.ts`, `dict.ts`, `option.ts`, `sig.ts`, `srv.ts`, `st.ts`, `useClient.ts`, `useServer.ts` — plus a `<model>.signal.test.ts` / `.spec.ts`, the one hand-written file that belongs there because the suite boots the whole barrel.
+- `apps/*/lib` and `libs/*/lib` root files are limited to generated/support files: `cnst.ts`, `db.ts`, `dict.ts`, `option.ts`, `sig.ts`, `srv.ts`, `st.ts`, `useClient.ts`, `useServer.ts`. Nothing hand-written sits beside them, tests included: a test goes in the module folder it covers (`lib/<model>/<model>.signal.test.ts`), or in `srvkit/` when it drives several modules.
 - Domain module folders are `lib/<model>` for database modules, `lib/_<service>` for service modules, and `lib/__scalar/<scalar>` for scalar modules.
 - Database module UI files are limited to `<Model>.Template.tsx`, `<Model>.Unit.tsx`, `<Model>.Util.tsx`, `<Model>.View.tsx`, and `<Model>.Zone.tsx`.
 - Service module UI files are limited to `<Service>.Util.tsx` and `<Service>.Zone.tsx`.
 - Scalar module UI files are limited to `<Scalar>.Template.tsx` and `<Scalar>.Unit.tsx`.
-- Module `*.test.ts`, `*.test.tsx`, `*.spec.ts`, and `*.spec.tsx` files are allowed.
+- A module test is named after the one module file it covers — `<model>.<role>.test.ts` / `.spec.ts`, `<Model>.<Role>.test.tsx` — so `<model>.<topic>.signal.test.ts` is refused, just like `<model>.<topic>.signal.ts`.
 - `ui/index.ts`, `webkit/index.ts`, `srvkit/index.ts`, `common/index.ts`, `plugin/index.ts`, and module `lib/**/index.ts` files are generated by scanSync; do not hand-edit or track them.
 - Generated facet indexes export only 1-depth files/folders with `export * from "./name";`. A facet folder with
   nothing to export syncs to `export {};` (a missing folder gets no barrel), so a stale barrel heals on the next
@@ -1131,6 +1170,10 @@ actions and state (see `<model>.store.ts` above).
   exist yet and the whole `libs/` container is watched, which is the safe direction.
 - Test production build generation with `bun run akan build <appName>`.
 - To test a built artifact locally, run it from the generated app directory with the required Akan runtime environment variables.
+- A server a test boots in-process takes `start({ listen: false, schedules: false })` to run no internal (init,
+  interval, cron, queue worker); `listen: false` alone still runs them, as a batch replica does. A server process a
+  test spawns from source resolves the workspace from its cwd and gets the root `.env` from Bun, so spawn it inside
+  the repo with `bun --no-env-file`, or spawn the built `dist/apps/<app>` output, which needs neither.
 
 ```bash
 cd dist/apps/<appName> && USE_AKANJS_PKGS=true AKAN_PUBLIC_REPO_NAME=<repo> AKAN_PUBLIC_SERVE_DOMAIN="<domain>" \