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

package/.build-stamp

@@ -1 +1 @@
-6ee016177b53c853f3bec400bfc5dd004b72cdb2f4e216c9b3d40c0ac292dcfe
+ff52b306f8c96b86a1bb9a1ea7d4a3a02deeb65d3184e77f02398b6eab82b052

package/{CodeAgent-n3tzjm91.js → CodeAgent-fee0pnwp.js}

@@ -1,8 +1,8 @@
 // @bun
 import {
   CodeAgent2
-} from "./index-1djcjcre.js";
-import"./index-dye8pnxx.js";
+} from "./index-vyh8kemm.js";
+import"./index-73esn3y2.js";
 import"./index-7md2g9vw.js";
 export {
   CodeAgent2 as CodeAgent

package/{CodeTui-fnm9ft4d.js → CodeTui-xh71b2k8.js}

@@ -5,7 +5,7 @@ import {
   McpTokenStore,
   McpSignIn,
   AkanCodeCompaction2
-} from "./index-dye8pnxx.js";
+} from "./index-73esn3y2.js";
 import {
   CodeTuiLines2,
   CodeTuiAgents2,

package/TunnelShare-s7bpe55e.js

@@ -0,0 +1,14 @@
+// @bun
+import {
+  TunnelShare2
+} from "./index-x7bny3wv.js";
+import"./index-9h0z0tjr.js";
+import"./index-551gh8h2.js";
+import"./index-m9jj544v.js";
+import"./index-6mprvdt8.js";
+import"./index-6nqnqzv1.js";
+import"./index-gxqvev8w.js";
+import"./index-52w0fvh8.js";
+export {
+  TunnelShare2 as TunnelShare
+};

package/{agent.command-3qxf4xcj.js → agent.command-tge9rvmt.js}

@@ -2,16 +2,16 @@
 import {
   Workspace,
   command
-} from "./index-jw1zm273.js";
+} from "./index-g5px5pxd.js";
 import"./index-52w0fvh8.js";
-import"./index-va06nr10.js";
+import"./index-gxqvev8w.js";
 import"./index-hj6w4ka1.js";
-import"./index-trpasv9q.js";
-import"./index-5edzv8fn.js";
+import"./index-5m0s0gdv.js";
+import"./index-tbmtmkhx.js";
 import"./index-zzvvc845.js";
 import {
   AgentScript
-} from "./index-tamvyvj3.js";
+} from "./index-4fe4qqgn.js";
 
 // pkgs/@akanjs/cli/agent/agent.command.ts
 class AgentCommand extends command("agent", [AgentScript], ({ public: target }) => ({

package/akanCode.js

@@ -28,7 +28,7 @@ import {
   CodeMailbox2,
   CodeSessionFork2,
   CodeAgent2
-} from "./index-1djcjcre.js";
+} from "./index-vyh8kemm.js";
 import {
   akanCodeDefaultModel2,
   akanCodeModel2,
@@ -40,7 +40,7 @@ import {
   SubagentPool2,
   akanCodePaths2,
   AkanCodeCompaction2
-} from "./index-dye8pnxx.js";
+} from "./index-73esn3y2.js";
 import"./index-7md2g9vw.js";
 import {
   CodeAgentRpcHost2

package/{application.command-zfja7x4r.js → application.command-j5b8yrcf.js}

@@ -7,18 +7,19 @@ import {
   Exec,
   Workspace,
   command
-} from "./index-jw1zm273.js";
+} from "./index-g5px5pxd.js";
 import"./index-52w0fvh8.js";
-import"./index-va06nr10.js";
+import"./index-gxqvev8w.js";
 import"./index-5nd1wtkv.js";
-import"./index-vk0pa0mn.js";
+import"./index-ex35dg39.js";
 import"./index-m9jj544v.js";
-import"./index-g1mbppa9.js";
-import"./index-192ha4xh.js";
-import"./index-pydbnfez.js";
+import"./index-551gh8h2.js";
+import"./index-6mprvdt8.js";
+import"./index-6nqnqzv1.js";
+import"./index-p44jnjfr.js";
 import {
   ApplicationScript
-} from "./index-qtfmtcrw.js";
+} from "./index-1xqq3va9.js";
 import"./index-7md2g9vw.js";
 import {
   writeOption,
@@ -27,10 +28,11 @@ import {
   allowLocalOption,
   publicEnvOption
 } from "./index-mdjc93e1.js";
-import"./index-35hc95h5.js";
-import"./index-665zp9rs.js";
+import"./index-f9118j70.js";
 
 // pkgs/@akanjs/cli/application/application.command.ts
+import { MigrationCommand } from "akanjs/server/migration/migrationCommand";
+import { MigrationError } from "akanjs/server/migration/migrationError";
 var deviceOption = {
   desc: "simulator, emulator or device to run on: its id or name (e.g. 'iPhone 17' or 'Pixel_10')",
   default: ""
@@ -62,6 +64,30 @@ class ApplicationCommand extends command("application", [ApplicationScript], ({
   script: target({ desc: "Run a custom script in the application" }).with(App).arg("filename", String, { desc: "name of script", nullable: true }).exec(async function(app, filename) {
     await this.applicationScript.script(app, filename);
   }),
+  migrate: target({
+    desc: "List, plan, apply, verify or roll back the app's data migrations in script/migration",
+    stdio: true,
+    usageExitCode: 2,
+    onFailure: async (error, { usage, given }) => {
+      if (given.json !== true)
+        return;
+      const failure = usage ? new MigrationError("usage", MigrationError.messageOf(error)) : error;
+      await MigrationCommand.print(MigrationCommand.failure(null, failure), true);
+    }
+  }).with(App).arg("action", String, { desc: "list, plan, apply, verify or rollback", default: "list" }).arg("target", String, { desc: "migration id; for rollback, an apply's run id too", nullable: true }).option("param", String, { desc: "a param the migration declares, as name=value", multiple: true }).option("expect", String, { desc: "the plan hash an apply must still match", nullable: true }).option("items", Number, { desc: "how many planned decisions to print", nullable: true }).option("actor", String, { desc: "who runs it, as the ledger records", nullable: true }).option("json", Boolean, { desc: "print the result as one JSON line", default: false }).exec(async function(app, action, target, param, expect, items, actor, json) {
+    await this.applicationScript.migrate(app, [
+      action,
+      ...target ? [target] : [],
+      ...param.map((each) => `--param=${each}`),
+      ...expect ? [`--expect=${expect}`] : [],
+      ...items === null ? [] : [`--items=${items}`],
+      ...actor ? [`--actor=${actor}`] : [],
+      ...json ? ["--json"] : []
+    ]);
+  }),
+  createMigration: target({ desc: "Create a data migration in the app's script/migration" }).arg("migrationName", String, { desc: "what it does, in camelCase", example: "bizLicenseOwnership" }).with(App).exec(async function(migrationName, app) {
+    await this.applicationScript.createMigration(app, migrationName);
+  }),
   console: target({ desc: "Open an interactive server console for the application" }).with(App).exec(async function(app) {
     await this.applicationScript.console(app);
   }),

package/{applicationBuildRunner-vh4j6vdv.js → applicationBuildRunner-s41mgz21.js}

@@ -4,20 +4,20 @@ import {
   Spinner,
   ProjectTypecheck2,
   WorkspaceExecutor
-} from "./index-va06nr10.js";
+} from "./index-gxqvev8w.js";
 import"./index-52w0fvh8.js";
-import"./index-w44cy4vs.js";
-import"./index-192ha4xh.js";
+import"./index-cgyqx6q1.js";
+import"./index-6nqnqzv1.js";
 import {
   AllRoutesBuilder,
   FontPruner,
   precompressArtifacts,
   SsrBaseArtifactBuilder
-} from "./index-axs61rna.js";
-import"./index-62md4dwy.js";
+} from "./index-8abyrfw8.js";
 import {
   CsrArtifactBuilder
-} from "./index-665zp9rs.js";
+} from "./index-6mprvdt8.js";
+import"./index-62md4dwy.js";
 
 // pkgs/@akanjs/devkit/applicationBuildRunner.ts
 import path2 from "path";
@@ -124,12 +124,26 @@ class ApplicationBuildRunner {
   get #envDir() {
     return path2.join(this.#app.cwdPath, "env");
   }
+  #pinImageEnv(baseDevEnv, environment) {
+    const imageEnv = {
+      AKAN_PUBLIC_ENV: environment,
+      AKAN_PUBLIC_REPO_NAME: baseDevEnv.repoName,
+      AKAN_PUBLIC_SERVE_DOMAIN: baseDevEnv.serveDomain
+    };
+    const outranked = Object.entries(imageEnv).filter(([key, value]) => {
+      const given = process.env[key];
+      return !!given && given !== value && !(key === "AKAN_PUBLIC_ENV" && this.#environment);
+    });
+    if (outranked.length)
+      this.#app.logger.warn(`The workspace .env outranks this process's environment: the bundles and the image take ${outranked.map(([key, value]) => `${key}=${value} (not ${process.env[key]})`).join(", ")}.`);
+    Object.assign(process.env, imageEnv);
+  }
   async build({ spinner = false } = {}) {
     this.#spinner = spinner;
     const { web, assets, baseDevEnv } = await this.#app.getConfig();
     const environment = this.#environment ?? baseDevEnv.env;
     WorkspaceExecutor.assertDeployableEnv(baseDevEnv, environment, "akan build");
-    process.env.AKAN_PUBLIC_ENV = environment;
+    this.#pinImageEnv(baseDevEnv, environment);
     if (this.#profile)
       await ServerEnvProfile.assertShippable({ envDir: this.#envDir, environment, profile: this.#profile });
     await this.#runPhase("prepare", "Preparing output directory", () => this.#app.prepareCommand("build"));

package/buildBatch.proc.js

@@ -6,27 +6,27 @@ import {
   resolveSsrPageEntriesForApp,
   WorkspaceExecutor,
   AppExecutor
-} from "./index-va06nr10.js";
+} from "./index-gxqvev8w.js";
 import {
   computeRouteSeedIndex,
   saveRouteSeedIndex,
   CsrDevBundler,
   SsrDevBundler
-} from "./index-w44cy4vs.js";
+} from "./index-cgyqx6q1.js";
 import"./index-52w0fvh8.js";
 import {
   ServerGraphFile,
   PagesBundleBuilder
-} from "./index-192ha4xh.js";
+} from "./index-6nqnqzv1.js";
 import {
   CssCompiler,
   FontOptimizer,
   SsrBaseArtifactBuilder
-} from "./index-axs61rna.js";
-import"./index-62md4dwy.js";
+} from "./index-8abyrfw8.js";
 import {
   CsrArtifactBuilder
-} from "./index-665zp9rs.js";
+} from "./index-6mprvdt8.js";
+import"./index-62md4dwy.js";
 
 // pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts
 import path from "path";
@@ -116,10 +116,10 @@ class BuildBatch {
   async#buildShell() {
     const started = Date.now();
     try {
-      await new CsrArtifactBuilder(this.#app, "start", "en", { cssAssets: this.#request.cssAssets }).build();
-      this.#logger.verbose(`csr-shell ok (${Date.now() - started}ms)`);
+      await new CsrArtifactBuilder(this.#app, "start", "en", { cssAssets: this.#request.cssAssets }).buildMcpAppViews();
+      this.#logger.verbose(`mcp-app-views ok (${Date.now() - started}ms)`);
     } catch (err) {
-      this.#fail("shell", "csr-shell", err);
+      this.#fail("shell", "mcp-app-views", err);
     }
   }
   async#rebuildCsrArtifact(started) {

package/{cloud.command-fcc8e8tp.js → cloud.command-q9srng6e.js}

@@ -3,26 +3,27 @@ import {
   App,
   Workspace,
   command
-} from "./index-jw1zm273.js";
+} from "./index-g5px5pxd.js";
 import"./index-52w0fvh8.js";
-import"./index-va06nr10.js";
-import"./index-cpb3nvma.js";
+import"./index-gxqvev8w.js";
+import"./index-9h0z0tjr.js";
 import {
   PlatformTestRun
-} from "./index-fyq1z6kt.js";
-import"./index-vk0pa0mn.js";
+} from "./index-hagw9c94.js";
+import"./index-ex35dg39.js";
 import"./index-m9jj544v.js";
-import"./index-g1mbppa9.js";
-import"./index-192ha4xh.js";
+import"./index-551gh8h2.js";
+import"./index-6mprvdt8.js";
+import"./index-6nqnqzv1.js";
 import"./index-5nd1wtkv.js";
-import"./index-pydbnfez.js";
-import"./index-qtfmtcrw.js";
+import"./index-p44jnjfr.js";
+import"./index-1xqq3va9.js";
 import"./index-7md2g9vw.js";
 import"./index-tvehn2sp.js";
-import"./index-j237xtew.js";
+import"./index-deckcwbg.js";
 import {
   CloudScript2
-} from "./index-hsadfb6c.js";
+} from "./index-c9rfak6r.js";
 import {
   writeOption,
   oneNativeTargetOption,
@@ -33,8 +34,7 @@ import {
   hostOption,
   subspaceOption
 } from "./index-mdjc93e1.js";
-import"./index-35hc95h5.js";
-import"./index-665zp9rs.js";
+import"./index-f9118j70.js";
 
 // pkgs/@akanjs/cli/cloud/cloud.command.ts
 var localRegistryUrl = () => process.env.AKAN_NPM_REGISTRY ?? "http://127.0.0.1:4873";

package/cloud.script-vfsd4gxs.js

@@ -0,0 +1,24 @@
+// @bun
+import {
+  CloudScript2
+} from "./index-c9rfak6r.js";
+import"./index-hagw9c94.js";
+import"./index-1xqq3va9.js";
+import"./index-f9118j70.js";
+import"./index-p44jnjfr.js";
+import"./index-deckcwbg.js";
+import"./index-ex35dg39.js";
+import"./index-9h0z0tjr.js";
+import"./index-551gh8h2.js";
+import"./index-m9jj544v.js";
+import"./index-g5px5pxd.js";
+import"./index-7md2g9vw.js";
+import"./index-6mprvdt8.js";
+import"./index-5nd1wtkv.js";
+import"./index-6nqnqzv1.js";
+import"./index-gxqvev8w.js";
+import"./index-tvehn2sp.js";
+import"./index-52w0fvh8.js";
+export {
+  CloudScript2 as CloudScript
+};

package/{code.command-130bdmhe.js → code.command-n6r6zt97.js}

@@ -4,9 +4,9 @@ import {
   runner,
   script,
   command
-} from "./index-jw1zm273.js";
+} from "./index-g5px5pxd.js";
 import"./index-52w0fvh8.js";
-import"./index-va06nr10.js";
+import"./index-gxqvev8w.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-n3tzjm91.js"),
+      import("./CodeAgent-fee0pnwp.js"),
       import("./CodeAgentRpcHost-9g27hmer.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-n3tzjm91.js"),
-      import("./CodeTui-fnm9ft4d.js")
+      import("./CodeAgent-fee0pnwp.js"),
+      import("./CodeTui-xh71b2k8.js")
     ]);
     const agentOptions = await CodeRunner.#agentOptions(options, false);
     let resume = options.resume;
@@ -67,7 +67,7 @@ class CodeRunner extends runner("code") {
     }
   }
   async run(prompt, options) {
-    const { CodeAgent } = await import("./CodeAgent-n3tzjm91.js");
+    const { CodeAgent } = await import("./CodeAgent-fee0pnwp.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","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"}}
+{"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","migrate":"application","create-migration":"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-0qx447mb.js → context.command-1je84w1b.js}

@@ -2,28 +2,28 @@
 import {
   Workspace,
   command
-} from "./index-jw1zm273.js";
+} from "./index-g5px5pxd.js";
 import"./index-52w0fvh8.js";
-import"./index-va06nr10.js";
+import"./index-gxqvev8w.js";
 import"./index-hj6w4ka1.js";
-import"./index-trpasv9q.js";
-import"./index-5edzv8fn.js";
-import"./index-d72hfmdm.js";
-import"./index-vk0pa0mn.js";
+import"./index-5m0s0gdv.js";
+import"./index-tbmtmkhx.js";
+import"./index-cq5x7a9k.js";
+import"./index-ex35dg39.js";
 import"./index-m9jj544v.js";
-import"./index-g1mbppa9.js";
-import"./index-192ha4xh.js";
+import"./index-551gh8h2.js";
+import"./index-6mprvdt8.js";
+import"./index-6nqnqzv1.js";
 import"./index-zzvvc845.js";
-import"./index-j4mkhz93.js";
-import"./index-86jt2a0e.js";
-import"./index-fmzcs8v6.js";
-import"./index-awbdfcf2.js";
-import"./index-1p98exm2.js";
-import"./index-1xj2t7cb.js";
+import"./index-t8npm331.js";
+import"./index-3xhak9e0.js";
+import"./index-1bhv9dh4.js";
+import"./index-rp9anyeb.js";
+import"./index-94jq9cbz.js";
+import"./index-85h3dhe0.js";
 import {
   ContextScript
-} from "./index-4mhy6qme.js";
-import"./index-665zp9rs.js";
+} from "./index-7xy30jev.js";
 
 // pkgs/@akanjs/cli/context/context.command.ts
 class ContextCommand extends command("context", [ContextScript], ({ public: target }) => ({

package/context.runner-xg0ngz93.js

@@ -0,0 +1,25 @@
+// @bun
+import {
+  ContextRunner2
+} from "./index-cq5x7a9k.js";
+import"./index-85h3dhe0.js";
+import"./index-94jq9cbz.js";
+import"./index-rp9anyeb.js";
+import"./index-t8npm331.js";
+import"./index-1bhv9dh4.js";
+import"./index-3xhak9e0.js";
+import"./index-ex35dg39.js";
+import"./index-551gh8h2.js";
+import"./index-m9jj544v.js";
+import"./index-tbmtmkhx.js";
+import"./index-5m0s0gdv.js";
+import"./index-zzvvc845.js";
+import"./index-g5px5pxd.js";
+import"./index-6mprvdt8.js";
+import"./index-6nqnqzv1.js";
+import"./index-gxqvev8w.js";
+import"./index-hj6w4ka1.js";
+import"./index-52w0fvh8.js";
+export {
+  ContextRunner2 as ContextRunner
+};

package/{guideline.command-cv5bmrx2.js → guideline.command-0e0sx2vg.js}

@@ -2,9 +2,9 @@
 import {
   script,
   command
-} from "./index-jw1zm273.js";
+} from "./index-g5px5pxd.js";
 import"./index-52w0fvh8.js";
-import"./index-va06nr10.js";
+import"./index-gxqvev8w.js";
 import {
   Prompter2
 } from "./index-zzvvc845.js";

package/guidelines/conventions/conventions.instruction.md

@@ -55,7 +55,8 @@ not "fix" it back.
   the module dictionary's `.error({})` — imported from `"../dict"` on the server, from `"@libs/<lib>/client"` /
   `"@apps/<app>/client"` in UI. A `throw` is an error; a raw `Error` rejected, returned or stored loses the key and
   status too (a warning for now). Exempt: tests, `*.constant.ts`, a root `native/` folder (plugins throw
-  `AkanNativeError`), and `common/**` / `env/**`, which have no legal `Err` import — keep throwing code out of them.
+  `AkanNativeError`), `script/migration/**` (an operator reads its message), and `common/**` / `env/**`, which have
+  no legal `Err` import — keep throwing code out of them.
 - **Never import a third-party package** from `page/**`, any barrel, a module logic file
   (`*.{constant,dictionary,document,service,signal,store}.ts`) or module component
   (`*.{Template,Unit,Util,View,Zone}.tsx`) — re-export it through a lib first (one-line shims in a lib's `common/`,
@@ -89,6 +90,10 @@ not "fix" it back.
 - **Never wrap a form setter in a pass-through arrow** — `(v) => st.do.setTypeOnTicket(v)` emits no
   `data-akan-action` and publishes no agent tool. A wrapper that transforms, adds a statement, or calls `writeOnX`
   is legal; publish it with an explicit `st.tool`.
+- **Never call an `st` hook conditionally** — `st.use.*`, `st.sel`, `st.ref` and the last step of `st.tool` /
+  `st.useState` / `st.expose` are hooks Biome's `useHookAtTopLevel` cannot see. Behind `||` / `&&` / `??`, a ternary,
+  an `if`, a loop or a callback, a skipped call shifts every later hook, and production React crashes elsewhere. Read
+  each into its own `const` at the top of the component, then combine.
 - **No deep imports past a barrel**, except cross-module constants (`../map/map.constant`).
 - **Never import across the client/server boundary** (`apps/**`, `libs/**`). Client files (`ui/`, `webkit/`,
   `page/`, `*.store.ts`, every `.tsx`) never import a `*.document|dictionary|service|signal.ts`, `srvkit/`, a
@@ -223,8 +228,8 @@ Playbook (warning table, code, checklist: `ssrRule`): ① wrap the interaction a
 `useEffect(…, [])` load; ④ a store-reading `Zone` holds no markup and delegates to a server `View`; ⑤ hand each
 promise across — `const { xInitInY, xListInY } = fetch.initXInY(id)`, `xInitInY` to a `Zone`, `xListInY` to
 `<Load.Stream>` (model instances, server-only) — and `await` only what the shell must contain; ⑥ named `ReactNode`
-slots (`Layout.Navbar`); ⑦ derived display logic on `Light<Model>`; ⑧ `getSelf({ unauthorize: "/signin" })` in
-`_layout.tsx` (an in-page redirect after I/O; `.config({ ssr: "block" })` for a 3xx); ⑨ CSS (`data-*` +
+slots (`Layout.Navbar`); ⑦ derived display logic on `Light<Model>`; ⑧ `.guard(() => signedIn())` on
+`_layout.tsx` (a real 3xx before anything renders; `getSelf({ unauthorize })` in a body redirects in-page after I/O); ⑨ CSS (`data-*` +
 `group-data-[…]`, `<details>`) over client state for visibility; ⑩ heavy islands behind `index_.tsx` + `lazy()`.
 
 ## Runtime & Build Configuration
@@ -401,8 +406,9 @@ orchestration in `service`, client state in `store`; `Template` is forms, `Unit`
 - **MCP (`mcpRule`)**: `/mcp` publishes every guarded endpoint by default; `mcp: false` (or a `slice()` `mcp` map
   mirroring `guards`) is curation, not authorization. `guards: [Every, Person]` reserves an act for a person;
   `.with(AgentCall)` narrows an agent's call. Settings are `option.setMcp` in `lib/option.ts`; `JWT_SECRET` is
-  required outside `local`. Never make a refusal message more helpful. Every entry needs a `.desc()`; publish a
-  screen with `page().prompt(name, description)`.
+  required outside `local`. Never make a refusal message more helpful. Every entry needs a `.desc()`; brief a
+  screen with `page().prompt(name, description)`, and publish one component a host draws with
+  `page().app(name, description, load)` — a read-only tool whose `load` may only query.
 - **In-page agent (`agentRule`)**: mount `<Agent.Chat />` once in a layout; it never executes tools and refuses
   every call until `option.setAgentAccess(<guard>)`; the LLM is `option.setLlm({ apiKey, model, host })`, never env.
   The surface is what components declare — `st.tool(…).exec(fn)` beside its control, `st.use` / `st.sel` /
@@ -460,15 +466,15 @@ orchestration in `service`, client state in `store`; `Template` is forms, `Unit`
 
 ## Akan Page Routing (`apps/**/page/**`)
 
-Full contract — heads, CSR root layouts, typed params, lib pages, `devOnly`: `pageRule`.
+Full contract — guards, apps, heads, CSR root layouts, typed params, lib pages, `devOnly`: `pageRule`.
 
 - `page/` holds `.tsx` route modules only: `<routeName>.tsx` or `_index.tsx`, `_layout.tsx`, `_overrides.tsx` — no
   other `_*.tsx`, helpers, `.ts` / `.js` files, or uppercase filenames. `[id]` is a dynamic segment, `(group)` a
   route group.
 - **A route file exports one chain** — `page()`, `layout()` in a `_layout.tsx`, `rootLayout()` in a root
-  `_layout.tsx` — and every setting is a stage (`.param`, `.search`, `.config`, `.head`, `.loading`; `.notFound` /
-  `.error` on layouts; `.fonts` / `.theme` / `.manifest` / … on the root; `.prompt` on a page). A named export
-  beside it fails the build.
+  `_layout.tsx` — and every setting is a stage (`.param`, `.search`, `.config`, `.guard`, `.head`, `.loading`;
+  `.notFound` / `.error` on layouts; `.fonts` / `.theme` / `.manifest` / … on the root; `.prompt` / `.app` on a page).
+  A named export beside it fails the build.
 - **Name every `[x]` segment with `.param("x", Type)`** and read query keys only via `.search("k", Type)`; values
   arrive typed. `lang` is never declared — every stage receives it.
 - `.head()` takes JSX or a function returning it — never a metadata object; deeper heads replace by tag identity,
@@ -484,18 +490,19 @@ Full contract — heads, CSR root layouts, typed params, lib pages, `devOnly`: `
 export default page()
   .param("orgId", ID)
   .config({ transition: "stack" })
+  .guard(() => signedIn())
   .render(({ orgId }) => {
     const { l } = usePage();
-    getSelf({ unauthorize: "/signin" });
     const { taskInitInOrg } = fetch.initTaskInOrg(orgId);
     return <Task.Zone.Card init={taskInitInOrg} prefix={`/org/${orgId}`} />;
   });
 ```
 
-- `.render()` gets the declared args flat and typed (no `PageProps`, no `loader=` prop). Order: `usePage()`, auth,
-  fetch, return. Hand `fetch.init*` / `view*` / `edit*` fields to sections unawaited; await only what the shell reads
+- `.render()` gets the declared args flat and typed (no `PageProps`, no `loader=` prop). Order: `usePage()`, fetch,
+  return; auth is the chain's `.guard()`, which runs before anything renders. Hand `fetch.init*` / `view*` / `edit*` fields to sections unawaited; await only what the shell reads
   (title, redirect, link id) in one `Promise.all`.
-- Gate auth at `_layout.tsx` (repeating `getSelf` in the page is fine). `async` only when the body awaits; the
+- Gate auth with `.guard(() => signedIn())` (`@libs/shared/webkit`) at `_layout.tsx`, and repeat it on a page that
+  needs more; it is a courtesy, the endpoint guards are the gate. `getSelf({ unauthorize })` in a body still works. `async` only when the body awaits; the
   callback is not a React component, so it takes no name and no return type. No `useState`, `useEffect`, or
   comments in page files.
 
@@ -551,6 +558,28 @@ export default page()
   barrel holds only `export *` lines). `ui/<Folder>/index_.tsx` is the `"use client"` + `lazy()` boundary beside a
   server-safe `index.tsx` — merging the pair breaks RSC.
 
+## Data Migrations (`apps/*/script/migration/**`)
+
+A change that reshapes stored documents ships a migration: `akan create-migration <name> <app>` writes
+`script/migration/<yyyyMMddHHmm>_<name>.ts`, a default-exported `migration(title)` from `akanjs/server`, which
+`akan migrate <app>` runs locally and `bun main.js ops migrate` in a built container (the `cheatsheet/dev/migration`
+docs page).
+
+- The new code reads both shapes until every environment has applied it — a deploy serves traffic first.
+- Write only through `table(refName)`, never a service, a document or raw `sql` — a service write runs the model's
+  hooks, and none of them reaches the change log a rollback reverts. Call nothing outside the database.
+- `plan` reads only and must hash the same on unchanged data: a timestamp, `createId()` or random value in it makes
+  every `apply --expect <planHash>` refuse as `planChanged`.
+- Past about five seconds on SQLite, an apply's one transaction makes the live server's writes fail. Take
+  `.config({ transaction: false })`, which commits each `rewrite` batch and resumes a `partial` run from the top of
+  `apply` — so a second run must change nothing (a `where` the new shape no longer matches).
+- `$ne` leaves out rows whose path is missing or `null` (match them with `{ path: null }`; `$exists: false` misses a
+  stored `null`); `find`, `count` and `rewrite` include removed rows unless `{ withRemoved: false }`; a `table()` write
+  leaves `updatedAt` alone.
+- Throw a plain `Error` an operator can act on. Never edit a migration an environment has applied — write another;
+  delete it once every environment has, unless its `.rollback(fn)` may still be needed: without the file a rollback
+  runs the default undo.
+
 ## Present In The Code — Do Not Imitate
 
 Warts in older files — never copy them; when two shapes disagree, follow the newer neighbour: `children: any`