@akanjs/devkit 3.1.1-rc.9 → 3.1.2-rc.0

package/codeAgent/agent/codeAgentRpcListener.test.ts

@@ -1,5 +1,5 @@
 import { afterAll, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtempSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import type { CodeAgentEvent } from "akanjs/common";
@@ -44,23 +44,28 @@ class FakeAgent {
 
 class Client {
   lines: unknown[] = [];
+  readonly closed = Promise.withResolvers<void>();
   #buffer = "";
   #socket: Awaited<ReturnType<typeof Bun.connect>> | null = null;
-  static async connect(unix: string) {
+  static async connect(target: string | { port: number }) {
     const client = new Client();
-    client.#socket = await Bun.connect({
-      unix,
-      socket: {
-        data: (_socket, data) => {
-          client.#buffer += data.toString();
-          const parts = client.#buffer.split("\n");
-          client.#buffer = parts.pop() ?? "";
-          for (const part of parts) if (part) client.lines.push(JSON.parse(part));
-        },
+    const socket = {
+      data: (_socket: unknown, data: Buffer) => {
+        client.#buffer += data.toString();
+        const parts = client.#buffer.split("\n");
+        client.#buffer = parts.pop() ?? "";
+        for (const part of parts) if (part) client.lines.push(JSON.parse(part));
       },
-    });
+      close: () => client.closed.resolve(),
+    };
+    client.#socket = await (typeof target === "string"
+      ? Bun.connect({ unix: target, socket })
+      : Bun.connect({ hostname: "127.0.0.1", port: target.port, socket }));
     return client;
   }
+  raw(text: string) {
+    this.#socket?.write(text);
+  }
   send(id: string, command: object) {
     this.#socket?.write(`${JSON.stringify({ id, command })}\n`);
   }
@@ -81,10 +86,17 @@ describe("CodeAgentRpcListener", () => {
   test("parses unix and tcp addresses, defaulting tcp to loopback", () => {
     expect(CodeAgentRpcListener.parse("unix:/tmp/a.sock")).toEqual({ unix: "/tmp/a.sock" });
     expect(CodeAgentRpcListener.parse("tcp:7000")).toEqual({ hostname: "127.0.0.1", port: 7000 });
-    expect(CodeAgentRpcListener.parse("0.0.0.0:7000")).toEqual({ hostname: "0.0.0.0", port: 7000 });
+    expect(CodeAgentRpcListener.parse("tcp::7000")).toEqual({ hostname: "127.0.0.1", port: 7000 });
+    expect(CodeAgentRpcListener.parse("localhost:7000")).toEqual({ hostname: "localhost", port: 7000 });
     expect(() => CodeAgentRpcListener.parse("tcp:nope")).toThrow("--rpc-listen");
   });
 
+  test("a bind other machines could reach is refused unless it is asked for", () => {
+    expect(() => CodeAgentRpcListener.parse("0.0.0.0:7000")).toThrow("--rpc-bind-any");
+    expect(() => CodeAgentRpcListener.parse("tcp:192.168.0.2:7000")).toThrow("--rpc-bind-any");
+    expect(CodeAgentRpcListener.parse("0.0.0.0:7000", { anyHost: true })).toEqual({ hostname: "0.0.0.0", port: 7000 });
+  });
+
   test("the agent outlives a dropped client, and the next one catches up by seq", async () => {
     const agent = new FakeAgent();
     const unix = path.join(dir, "agent.sock");
@@ -110,4 +122,94 @@ describe("CodeAgentRpcListener", () => {
     await served;
     expect(agent.disposed).toBe(true);
   });
+
+  describe("over tcp", () => {
+    const opened = () => {
+      const agent = new FakeAgent();
+      const listener = new CodeAgentRpcListener(new CodeAgentRpcHost(agent as unknown as CodeAgent, null), {
+        hostname: "127.0.0.1",
+        port: 0,
+      }).listen();
+      return { agent, listener, port: listener.port ?? 0 };
+    };
+
+    test("a connection opened with the token is answered, and one without it is closed unheard", async () => {
+      const { agent, listener, port } = opened();
+      try {
+        expect(listener.token).toMatch(/^[A-Za-z0-9_-]{43}$/);
+        const anonymous = await Client.connect({ port });
+        anonymous.send("1", { type: "prompt", message: "hi" });
+        await anonymous.closed.promise;
+        expect(anonymous.lines).toEqual([{ type: "reply", id: "auth", ok: false, error: "unauthorized" }]);
+
+        const wrong = await Client.connect({ port });
+        wrong.raw(`${JSON.stringify({ auth: "not-the-token" })}\n`);
+        await wrong.closed.promise;
+        expect(agent.seq).toBe(1);
+
+        const client = await Client.connect({ port });
+        client.raw(
+          `${JSON.stringify({ auth: listener.token })}\n${JSON.stringify({ id: "2", command: { type: "prompt", message: "hi" } })}\n`,
+        );
+        expect((await client.reply("auth")).ok).toBe(true);
+        expect((await client.reply("2")).ok).toBe(true);
+        expect(client.lines.findIndex((line) => (line as { id?: string }).id === "auth")).toBe(0);
+        client.close();
+      } finally {
+        listener.stop();
+      }
+    });
+
+    test("a connection that speaks anything but a JSON frame is dropped at its first byte", async () => {
+      const { listener, port } = opened();
+      try {
+        const browser = await Client.connect({ port });
+        browser.raw("GET / HTTP/1.1\r\nHost: 127.0.0.1\r\n\r\n");
+        await browser.closed.promise;
+        expect(browser.lines).toEqual([]);
+      } finally {
+        listener.stop();
+      }
+    });
+
+    test("a connection that has not authenticated does not displace the client that has", async () => {
+      const { listener, port } = opened();
+      try {
+        const client = await Client.connect({ port });
+        client.raw(`${JSON.stringify({ auth: listener.token })}\n`);
+        await client.reply("auth");
+        const other = await Client.connect({ port });
+        other.raw("{");
+        await Bun.sleep(30);
+        client.send("3", { type: "get_state", sinceSeq: 0 });
+        expect((await client.reply("3")).ok).toBe(true);
+        other.close();
+        client.close();
+      } finally {
+        listener.stop();
+      }
+    });
+  });
+
+  test.skipIf(process.platform === "win32")(
+    "a unix socket is its owner's alone, and needs no token, though one is accepted",
+    async () => {
+      const agent = new FakeAgent();
+      const unix = path.join(dir, "owned.sock");
+      const listener = new CodeAgentRpcListener(new CodeAgentRpcHost(agent as unknown as CodeAgent, null), { unix });
+      listener.listen();
+      try {
+        expect(listener.token).toBeNull();
+        expect(statSync(unix).mode & 0o777).toBe(0o600);
+        const client = await Client.connect(unix);
+        client.raw(`${JSON.stringify({ auth: "anything" })}\n`);
+        expect((await client.reply("auth")).ok).toBe(true);
+        client.send("4", { type: "get_state", sinceSeq: 0 });
+        expect((await client.reply("4")).ok).toBe(true);
+        client.close();
+      } finally {
+        listener.stop();
+      }
+    },
+  );
 });

package/codeAgent/agent/stringArg.ts

@@ -1,4 +1,4 @@
-export const stringArg = (args: unknown, key: "path" | "command") => {
+export const stringArg = (args: unknown, key: "path" | "command" | "url") => {
   if (!args || typeof args !== "object") return undefined;
   const value = (args as Record<string, unknown>)[key];
   return typeof value === "string" && value ? value : undefined;

package/codeAgent/feedback/PreviewFeedback.ts

@@ -1,5 +1,5 @@
+import { PreviewView } from "../../preview/PreviewView";
 import { AkanEditScope } from "../tools/AkanEditScope";
-import { PreviewView } from "./PreviewView";
 import type { TurnFeedbackFinding, TurnFeedbackSource } from "./TurnFeedback";
 
 export interface PreviewFeedbackOptions {
@@ -35,7 +35,7 @@ export class PreviewFeedback implements TurnFeedbackSource {
     for (const route of this.#options.routes ?? ["/en/"]) {
       const url = new URL(route, this.#options.previewUrl).toString();
       const probe = await PreviewView.probe(url, { screenshot: !!this.#options.canSeeImages });
-      const problems = [...probe.pageErrors, ...probe.consoleErrors, ...probe.domFindings];
+      const problems = [...probe.pageErrors, ...probe.consoleErrors, ...probe.consoleWarnings, ...probe.domFindings];
       if (!problems.length) continue;
       findings.push(`**${url}**\n${problems.map((line) => `- ${line}`).join("\n")}`);
       if (probe.screenshot) images.push({ data: probe.screenshot, mimeType: "image/png" });

package/codeAgent/feedback/VerifyFeedback.ts

@@ -26,11 +26,10 @@ export class VerifyFeedback implements TurnFeedbackSource {
 
   async observe() {
     const scope = await AkanEditScope.since(this.#options.cwd, this.#baseline);
-    if (!scope.apps.length && !scope.libs.length) return undefined;
+    if (!scope.apps.length && !scope.libs.length && !scope.pkgs.length) return undefined;
     if (this.#options.readOnly) return VerifyFeedback.#readOnlyNotice(scope.needsSync, [...scope.apps, ...scope.libs]);
-    const report = await this.#verifier.verify(scope);
-    if (report.ok) return undefined;
-    return AkanVerifier.summarize(report);
+    const report = await this.#verifier.verify(scope.paths);
+    return report.ok ? undefined : report.text;
   }
 
   static #readOnlyNotice(needsSync: boolean, targets: string[]) {

package/codeAgent/index.ts

@@ -1,5 +1,7 @@
 // Importing this barrel loads the engine (~122MiB resident); a host needing cheap pieces imports the owning module.
 // agent/consoleToStderr is deliberately absent: it takes over globalThis.console, so an RPC entry imports it first.
+
+export * from "../preview";
 export * from "./agent/AkanCodeCompaction";
 export * from "./agent/AkanCodeServices";
 export * from "./agent/akanCodeModel";
@@ -17,9 +19,7 @@ export * from "./agent/CodeSessionFork";
 export * from "./agent/CodeSessionIndex";
 export * from "./agent/SubagentPool";
 export * from "./feedback/DevLogFeedback";
-export * from "./feedback/PreviewChrome";
 export * from "./feedback/PreviewFeedback";
-export * from "./feedback/PreviewView";
 export * from "./feedback/TurnFeedback";
 export * from "./feedback/VerifyFeedback";
 export * from "./tools/AkanCli";

package/codeAgent/skills/akan-agent/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: akan-agent
+description: "Build the in-page agent: mounting Agent.Chat, setAgentAccess and the request policy, the LLM, publishing st.tool actions and cards, forms, readable state, zones, route guidance and slash commands."
+---
+
+# Akan in-page agent
+
+**The surface is what components declare, exactly.** `st.tool` publishes one action and `st.use` / `st.sel` /
+`st.ref` make one store key readable while the reading component is mounted. A method on a store class gives an
+agent nothing, and only the current page's declarations are live.
+
+## Mount it
+
+1. Mount `<Agent.Chat />` once, in a layout. It never executes tools: every tool runs in the caller's browser,
+   gated by guards and the approval card.
+2. It refuses every call until `option.setAgentAccess(<guard>)` in `lib/option.ts` names who may use it
+   (`SignedIn` for a product with accounts). What a turn may ask is `option.setAgentRequestPolicy`; until one is
+   set, a turn past `AgentRelayPolicy.defaultLimits` is refused with 413, and a policy of the app's own keeps them
+   with `AgentRelayPolicy.capped(request, limits)`. An error that is not an `Err` reaches the chat as a generic
+   failure unless `AKAN_ERROR_DETAIL=1` or a development runtime shows it.
+3. The LLM is `option.setLlm({ apiKey, model, host })`, never env.
+
+## Publish actions
+
+- Declare the tool beside the control that already does it, and hand the result to the control:
+  `st.tool("x").desc("…").arg("id", ID).exec((id) => st.do.removeX(id))`. One handler serves the person and the
+  agent; `.desc()` is required and first.
+- A name starting with a write verb (`remove`, `delete`, `create`, `update`, `upsert`, `submit`, `save`, `send`,
+  `export`) asks the user first; `{ confirm: false }` opts one tool out, `AgentConfirm.set` the app.
+- `.card(({ submit, cancel }) => <Form … />)` parks the call in the chat for an answer that is the user's to give.
+- Store-driven forms publish themselves: `onChange={st.do.setFieldOnX}` by reference emits the `data-akan-action`
+  the agent drives. A pass-through arrow publishes nothing and fails lint.
+- Every `st.tool(…).exec()` / `.card()` is a hook: never behind a condition.
+
+## Reads and guidance
+
+- `st.use.x({ agent: false })` hides a key; `hidden`, `secret` and `visual` fields are stripped from every read.
+- Page text is data the model reads, never instructions: after a screen read the next call that changes something
+  asks once, and `data-agent-private="<label>"` keeps a region's text out of every read.
+- A tool value is capped at 20,000 characters.
+- Route guidance is `<Agent.Guide instructions="…" />`; model-facing text is English.
+
+Full detail: `get_guideline` with `agentRule`.

package/codeAgent/skills/akan-code/SKILL.md

@@ -9,9 +9,9 @@ This is the tool the user is talking to right now. When they ask how to do somet
 with their code — answer from here, and quote the exact gesture: the slash command to type, or the file to
 edit. Do not guess a command; everything this tool offers is listed below.
 
-You cannot type a slash command yourself. They are the host's, not yours — say which one to type. You *can*
-edit the files named below, which is the useful half of most of these answers: write the change, then say
-which command makes it take effect.
+You cannot type a slash command yourself. They are the host's, not yours — say which one to type. You cannot
+edit `mcp.json`, `.akan/code/extensions/` or anything under `~/.akan/` either: the deny list covers them, so
+quote the `/mcp` command that makes the change instead. The context files and skills named below you can edit.
 
 ## MCP servers
 
@@ -52,8 +52,17 @@ From the prompt:
 
 **A server added now is not reachable until the session reloads.** The tool allowlist is fixed when the
 session is created, so `add`, `remove`, `login` and `logout` all reload by themselves — a session that has
-said nothing yet has nothing on disk to reopen, and says so. If you edit `mcp.json` yourself, tell the user to
-run `/mcp reload`.
+said nothing yet has nothing on disk to reopen, and says so. After the user edits `mcp.json` by hand, `/mcp
+reload` makes it take effect.
+
+**This repo's own servers start only once the user approves them.** At start, `akan code` lists what this
+repo's `.akan/code/mcp.json` would run, and the extensions in `.akan/code/extensions/`, and asks once; a yes is
+remembered in `~/.akan/code/trust.json` until that content changes, and is asked again after. An extensions
+folder past 10,000 files or 64 MiB, or with a link that leads out of it, is asked about at every start. With
+nobody at a terminal they are not started, and `/mcp` shows `not approved`. `--trust-workspace` (`-T`) starts
+them for one run without asking. Servers in `~/.akan/code/mcp.json`, where `/mcp add` writes, need no approval;
+`/mcp add --local` writes this repo's file and keeps the approval it had, so a server added while that file
+waits for approval waits with it.
 
 `/mcp remove` on a name both files declare takes this repo's entry and leaves the home file's in force; its
 notice says so, and running it again removes that one too.
@@ -61,8 +70,9 @@ notice says so, and running it again removes that one too.
 Sign-in is discovered, not configured: the server's `401` names its resource metadata, that names the
 authorization server, and most hosted servers register a client on demand — so a url is usually the whole
 entry. For a provider that issues client ids by hand, add `"oauth": { "clientId": "…", "scope": "…" }`.
-Tokens are stored per server in `~/.akan/code/mcpAuth.json` at mode 0600, never in the repo, and refreshed
-silently — at connect when one has expired, and mid-session when a server refuses one, after which the call is
+Tokens are stored in `~/.akan/code/mcpAuth.json` at mode 0600, never in the repo, bound to the server's origin
+rather than its name — a server renamed in the file keeps its sign-in, and one moved to another url signs in
+again. They are refreshed silently — at connect when one has expired, and mid-session when a server refuses one, after which the call is
 retried once. When a refresh cannot fix it, `/mcp` shows `sign-in needed` and that server's tools answer with
 `/mcp login <name>` until the user signs in; the sign-in reloads the session, which brings the server back.
 
@@ -85,19 +95,23 @@ Stored under `.akan/code/sessions` — project history, so a second checkout of
 ## Model, effort, keys
 
 - `/model <provider>/<id>`, e.g. `/model deepseek/deepseek-v4-pro`. `/effort <level>` for how hard it thinks.
+  A `task` sub-agent starts on the model the session is on at that moment.
 - A provider is authorized by **`<PROVIDER>_API_KEY`** — `DEEPSEEK_API_KEY`, `ANTHROPIC_API_KEY`. The
   workspace's own `.env` is read as well as the environment, and a key found there is used for the run and
   never copied anywhere.
-- Credentials and the model catalogue live in `~/.akan/code/` (`auth.json`, `models.json`). **`AKAN_CODE_HOME`
-  moves the whole directory** — for a container with no home, or a checkout that wants its own.
+- Credentials and the model catalogue live in `~/.akan/code/` (`auth.json`, `models.json`), mode 0700.
+  **`AKAN_CODE_HOME` moves the whole directory** — for a container with no home, or a checkout that wants its
+  own. It, `AKAN_CODE_CAN_PROMPT`, the `AKAN_CODE_PROXY_*` settings and `AKAN_CODE_RPC_TOKEN_FILE` are read
+  from the shell only: one a repo's `.env` names is ignored, with a warning at start.
 
 ## What the agent reads, and how to change it
 
 - Every `AGENTS.md` / `CLAUDE.md` from the workspace root down to the working directory, `.cursorrules`, and
   any `.cursor/rules/*.mdc` that applies unconditionally (`alwaysApply: true`, or no frontmatter at all).
   Edit those to change how this agent behaves in this repo — they are the files the editor beside it reads.
-- Skills: drop a `<name>/SKILL.md` into `.akan/code/skills`. Extensions: `.akan/code/extensions`. Neither is
-  read from a home directory, so a session behaves the same in two checkouts.
+- Skills: drop a `<name>/SKILL.md` into `.akan/code/skills`. Extensions: `.akan/code/extensions`, loaded once
+  the user approves them (see MCP servers). Neither is read from a home directory, so a session behaves the
+  same in two checkouts.
 
 ## Keys
 
@@ -123,8 +137,21 @@ akan code -i "<prompt>"         open the session with the prompt already sent
 --profile local|pod|review|web  what it may do (default local)
 --model <provider>/<id>         --thinking, --json, --rpc, --resume <id>
 --compact-at <percent>          compact once the window is this full (10, 20, … 100)
+--trust-workspace               start this repo's MCP servers and extensions without asking
+--no-ask-network                never ask before an unlisted host (local profile)
+--rpc-listen unix:<path>|tcp:[host:]<port>   serve the RPC wire on a socket instead of stdio
 ```
 
+`local` runs as the user: it refuses known secret files and the home credential stores, and asks before it
+fetches a page from a host off a short documentation list or a shell command that reaches the network
+(`curl`, `ssh`, …) — refused outright where nobody can answer, as in a one-shot `akan code "<prompt>"`. It is
+not a sandbox; `pod` in a container is.
+
+A `tcp:` listener asks every connection to open with `{"auth":"<token>"}` on its first line; the token is a
+fresh one in `~/.akan/code/rpc/<port>.token`, or the one in the file `AKAN_CODE_RPC_TOKEN_FILE` names.
+`--no-rpc-token` drops it, and only a loopback address is bound unless `--rpc-bind-any` is given. A unix
+socket is created owner-only and asks for no token.
+
 `review` reads and never writes, loads no project context files, and keeps no session on disk. `pod` has
 nobody in front of it: it cannot ask a question. MCP is off in both.
 

package/codeAgent/skills/akan-debug/SKILL.md

@@ -1,10 +1,43 @@
 ---
 name: akan-debug
-description: "Debug a running Akan app: where the dev-server log is, how to read it, and how to tell a runtime failure from a build one."
+description: "Check and debug a running Akan app: akan preview for what a page shows and throws, where the dev-server log is, how to read it, and how to tell a runtime failure from a build one."
 ---
 
 # Akan debug
 
+## See the change run: `akan preview`
+
+`akan preview <app> [paths]` opens pages of the app's dev server in a headless browser and prints, per page,
+the HTTP status, the title, a slice of the visible text, the uncaught errors and rejections the page reported,
+the server errors logged meanwhile, console errors and warnings, and layout smells. It exits 1 when a page failed.
+
+- It uses the dev server that answers for this app and checkout. With none, it starts one for the run and
+  stops it after; `--keep` leaves it up for the next preview. It never starts a second server beside a
+  running one.
+- Paths are comma-separated (`akan preview <app> /board,/board/new`) and get the default locale when they lack
+  one, unless the app sets `localePrefix: "as-needed"` and `--csr` is off.
+  `--changed` adds the pages your uncommitted page and layout edits reach. A dynamic route needs a concrete
+  path (`/memo/1`); `akan context --app <app>` lists every route with its params and search names.
+- The viewport is a 390x844 phone; `--desktop` is 1280x800. `--csr` loads each page in the CSR boot the native
+  shells load. `--screenshot` saves a PNG per page under `local/apps/<app>/runtime/preview/`, for a model
+  that reads images. `--format json` gives the same report as data.
+
+### Which platforms that covers
+
+- Every change: the server-rendered web page and, with `--csr`, the bundle the iOS, Android and desktop
+  shells run.
+- A change to `native/`, `plugin/`, an `isNativeApp()` branch, `native` in `akan.config.ts` or an
+  `@akanjs/native` plugin also needs that shell: `akan start-ios`, `start-android` or `start-desktop` on top of
+  the running dev server. Errors thrown in the shell reach the same dev-server log as `ClientReport` lines
+  tagged with the platform and target. Capture the shell with `xcrun simctl io booted screenshot <file>.png` or
+  `adb exec-out screencap -p > <file>.png`. When you cannot run the shell, say so: "not checked on iOS".
+- Real devices, memory, OTA updates and store builds are for whoever releases.
+
+### What goes in your answer
+
+The verdict lines of the pages you changed (`ok    /en/board  200  "Board"  1.4s`) and every finding you left
+unfixed. "Not opened in a browser" is not an answer once `akan preview` can run.
+
 ## The log is a file, and that file is the whole session
 
 A supervised `akan start` writes **`local/apps/<app>/runtime/dev.log`** — no ANSI, nothing truncated, every
@@ -17,12 +50,14 @@ what survives in the scrollback is bordered and truncated to the pane.
 - `tail -n 200 local/apps/<app>/runtime/dev.log` after an edit, to see what the reload produced.
 - `akan logs <app>` tails a running server with `--level --grep --endpoint --trace --child --role --origin
   --since` and `--json`.
-- The dev server's URL is printed in that log, and the port is allocated rather than fixed — the log is the
-  only source for it.
+- The dev server's URL is printed in that log. A server `akan preview` started logs to
+  `local/apps/<app>/runtime/preview/server.log` instead.
+- An uncaught error or unhandled rejection in a page reaches the server log as a `ClientReport` error line,
+  naming the page, the client (`ssr` or `csr`) and the native target.
 
 ## Which loop you are in
 
-- **A type or lint failure** is the `akan-validate` loop. `akan_verify`.
+- **A type or lint failure** is the `akan-validate` loop: `akan verify`.
 - **A runtime or SSR failure** is the dev log. The page renders blank, an overlay appears, or a request
   500s — none of that shows up in a typecheck.
 
@@ -38,5 +73,5 @@ reads like its own level is not one.
 
 ## Before you conclude
 
-A change that renders is not a change that passed. Run `akan_verify`, and for a `.tsx` change check
-`akan quality ssr` too — a UI edit that moves markup into a client bundle typechecks perfectly.
+A change that renders is not a change that passed. Run `akan verify`; for a `.tsx` change it also runs the
+SSR check, since a UI edit that moves markup into a client bundle typechecks perfectly.

package/codeAgent/skills/akan-deps/SKILL.md

@@ -46,5 +46,4 @@ the package client path — `import { cnst, fetch, st, usePage } from "@apps/<ap
 
 ## Validate
 
-`akan_verify`, or `akan sync <app>` then `akan lint <app>` then `akan typecheck <app>`. Raw `tsc` misses the
-generated barrels and reports false errors.
+`akan verify`. Raw `tsc` misses the generated barrels and reports false errors.

package/codeAgent/skills/akan-err/SKILL.md

@@ -28,7 +28,8 @@ import path at all**, so keep throwing code out of them entirely rather than rea
 
 Best-effort code returns a sentinel (`null`, `undefined`, `{}`) instead of throwing. `try/catch` is rare and
 always converts an exception into a decision: a guard catches, warns, and returns `false`; an adapter
-catches, logs, and returns `null`. A store action never catches — let the framework toast the `Err`.
+catches, logs, and returns `null`. A store action never catches — let the framework toast the `Err`, or list it in
+the store's `static silent` when no screen waits on it and its caller handles the rejection.
 Client-side validation failure is `msg.error("<key>")` plus an early return, never a throw.
 
 **A failure another process reported travels as itself.** A server-to-server `fetch.<endpoint>(…, { origin })`

package/codeAgent/skills/akan-mcp/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: akan-mcp
+description: "Expose an app to MCP clients: what /mcp publishes from guards, mcp: false curation, option.setMcp settings, OAuth, refusals, page prompts and MCP Apps, and the exposure test."
+---
+
+# Akan MCP
+
+Every app serves its signals as an MCP server on `POST /mcp`, mounted by default. **Exposure follows the guards**:
+an endpoint with a real guard is published, one with none is refused, and so is a mutation guarded only by
+`Public`. There is no per-endpoint opt-in.
+
+## Curation is not authorization
+
+- `mcp: false` on an endpoint, or a `slice()` `mcp` map mirroring `guards`, keeps a perfectly guarded step (a UI
+  state-machine step a model would only call by mistake) off the shelf. It is an opt-out; everything else still
+  publishes.
+- `guards: [Every, Person]` reserves an act for a person; `.with(AgentCall)` narrows what an agent's call may do.
+- A guard's `static scope` decides whether a listing can hide the entry: `"account"` guards are evaluated per
+  caller, `"resource"` guards stay visible and stop the call.
+
+## Settings
+
+- `option.setMcp({ … })` in the app's `lib/option.ts`, never `main.ts`; `AKAN_MCP=false` takes the surface off.
+- `JWT_SECRET` is required outside `local`.
+- Every published entry needs a `.desc()`; model-facing text is English.
+- Never make a refusal message more helpful.
+
+## Pages for the host
+
+- `page().prompt(name, description)` briefs a screen as an MCP prompt.
+- `page().app(name, description, load)` publishes one component a host draws in the chat, as a read-only tool
+  whose `load` may only query.
+
+## Verify
+
+- One exposure test per app in `srvkit/mcpExposure.signal.test.ts`: list the tools with a user token, pin the names
+  with `toEqual`, and assert the curated and admin-only ones are absent. A guard change fails it first.
+- Then `akan verify <app>` and the boot log.
+
+Full detail: `get_guideline` with `mcpRule`, or `transportRule` for guards and rate limits.

package/codeAgent/skills/akan-page/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: akan-page
+description: "Add or change a route under page/: the one page()/layout() chain, typed params and search, guards, heads, loading and errors, overrides, and lib pages."
+---
+
+# Akan pages
+
+A route file exports one chain and nothing else. Every setting is a stage of it.
+
+```tsx
+export default page()
+  .param("orgId", ID)
+  .guard(() => signedIn())
+  .render(({ orgId }) => {
+    const { l } = usePage();
+    const { taskInitInOrg } = fetch.initTaskInOrg(orgId);
+    return <Task.Zone.Card init={taskInitInOrg} prefix={`/org/${orgId}`} />;
+  });
+```
+
+## Steps
+
+1. Place the file: `<route>.tsx` or `<dir>/_index.tsx` serves the path, `_layout.tsx` nests a layout (`layout()`;
+   the root one is `rootLayout()`), `[id]` is a dynamic segment, `(group)` groups without a segment. `page/` holds
+   route modules only — no helpers, no `.ts` files.
+2. Name every `[x]` segment with `.param("x", Type)` and read a query key only with `.search("k", Type)`. Values
+   arrive typed; `lang` reaches every stage and is never declared.
+3. Gate with `.guard(() => signedIn())` on the `_layout.tsx` (a real redirect before anything renders), and repeat
+   a stricter guard on a page that needs more. The endpoint guards are still the real gate.
+4. In `.render()`: `usePage()`, then fetch, then return. Hand `fetch.init*` / `view*` / `edit*` fields to sections
+   unawaited; await only what the shell reads, in one `Promise.all`.
+5. `.head()` takes JSX (or a function returning it), never a metadata object. A canonical link comes only from the
+   page's own head.
+6. Re-skin an `akanjs/ui` component for a subtree with `_overrides.tsx`:
+   `export default override({ Slot: AppComponent })`, no logic.
+
+## Never
+
+- A `fetch.<mutation>()` while rendering — it throws `base.error.mutationInRender`, because opening a link would
+  perform it. Send writes from a user action.
+- `useState`, `useEffect`, comments, a named export beside the chain, or the legacy `export default async function`.
+- Editing a lib page through its link in `page/(libs)/` — edit the lib's own `page/` source.
+
+Full detail: `get_guideline` with `pageRule`, or `ssrRule` for what may render on the server.

package/codeAgent/skills/akan-query/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: akan-query
+description: "Write filters, slices and list loading: query descriptors, init paging and loadMoreOf, soft removal and hookless writes, q.search text search, and the cascade direction."
+---
+
+# Akan queries and slices
+
+## Filters and slices
+
+- A filter in `<model>.document.ts` declares its args; a slice in `<model>.signal.ts` serves it to stores. A slice
+  `exec` returns a `query<Filter>(…)` descriptor — never a `list<Filter>` array — and you cannot chain sort or
+  limit on it.
+- Page through the store: `initX(…, { sort, page, limit })`, then `st.do.loadMoreOf<Model>()` while
+  `hasMoreOf<Model>`. Never compare `count > page * limit`.
+- Never ask for more than 500 rows: the server serves at most 500 per request and drops the rest silently.
+  A figure over the whole set belongs in an insight or an endpoint.
+- The root slice takes a filter name and its args, never a raw query, and its `root:` guard is always `Admin`.
+- No value is `q.empty`, never `q.missing`.
+- A projection is bare on the facade (`pickById(id, { secret: true })`) and under `select` on a filter accessor —
+  the only way to read a `field.secret` value.
+
+## Writes and removal
+
+- Removal is soft: reads see live rows unless `{ withRemoved: true }`. The one hard delete is `purge<Filter>` /
+  `purgeMany`, for data past retention.
+- A filter's `remove*` / `update*`, `updateById` and `removeById` run no hooks and no cascade. A model with a
+  cascade or `_postRemove` removes through `remove<Model>(id)`.
+- Load a set once (`load<Model>Many`, one filter query) and create one with `create<Model>Many(rows)` instead of one
+  call per item in a loop — lint fails a per-item service call an endpoint reaches. `create<Model>Many` runs every
+  row's `_preCreate` before writing any, so a check there does not see the batch's own rows.
+
+## Search and cascade
+
+- `q.search(text, { prefix: true })` sits in a filter at an AND position, over fields with the `text` role. Blank
+  input matches nothing — never a passthrough. A search slice only over data safe to enumerate.
+- `cascade` names a direction, and the wrong one loses data: `removeRef` on the owner's relation, `removeWith` on
+  the child's reference to its owner.
+
+Full detail: `get_guideline` with `queryRule`, and `workspaceRecipes` for a worked slice.

package/codeAgent/skills/akan-runtime/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: akan-runtime
+description: "Configure how an app runs: web surfaces, route prefixes, gateway vs solo, akan start and logs, the Docker image, native and desktop apps, database modes, ops, assets and the build pipeline."
+---
+
+# Akan runtime
+
+Runtime and build settings are declared in `akan.config.ts` and narrowed — never widened — by an env at boot.
+Domain code reaches none of them.
+
+## Where each setting lives
+
+| Want | Setting |
+| --- | --- |
+| API only, or no CSR bundle for native apps | `web: false`, `web: { csr: false }` |
+| Move the API or websocket mount | `new AkanApp({ prefix, websocketPrefix })` in `main.ts`, mirrored in `api: { … }`; read with `getApiPrefix()` / `getWsPrefix()` |
+| The production image | `docker: string \| { image, preRuns, postRuns, command }` |
+| iOS, Android, desktop | the `native` section; `desktop: { server: true }` carries the server |
+| SQLite, several databases, a cluster | `database: { modes: [...] }`, picked by `AKAN_DATABASE_MODE` |
+| URLs without `/<locale>/`: one language, or paths fixed from outside (OAuth callback, QR code, mail link) | `i18n: { localePrefix: "as-needed" }` — the default locale's pages and `<Link>` hrefs drop the prefix, other locales keep it |
+
+- `main.ts` imports `AkanApp` from `akanjs/server/akanApp`, never the barrel.
+- Never write `/api` or `/ws` literally, and never pass a prefix as a prop.
+- The generated image installs only `ca-certificates` and `tzdata`; add the rest in `preRuns`.
+- An app running in two database modes avoids `q.raw`.
+
+## Running and logs
+
+- `akan start <app>` (`a,b` or `all` for several) runs the dev server; `akan build <app>` checks the production
+  build. A supervised session writes `local/apps/<app>/runtime/dev.log` — hand over that path, not a paste of the
+  live view. Tail with `akan logs <app>`.
+- Run a build without Docker with `cd dist/apps/<app> && bun main.js`: it boots with the env the Dockerfile sets,
+  read from `akan.env.json` beside it, and a variable you set yourself (`PORT=3000`) wins.
+- Give every log sink a floor (`Logger.addSink(sink, { minLevel })`) and never log once per delivered record.
+
+## Native and desktop
+
+- `akan start-desktop <app>`, `akan start-ios <app>`, `akan start-android <app>` load pages from a running
+  `akan start`; a desktop app carrying its server starts it itself.
+- A desktop app's carried server listens on a loopback port any local program can call — guard it like a network
+  server. Read runtime files from `AKAN_APP_DIR`, and keep a user's secret with `NativeSecret`, never in a file.
+
+Full detail: `get_guideline` with `runtimeRule`.