@akanjs/devkit 3.1.1-rc.8 → 3.1.1

package/akanContext.ts

@@ -1,6 +1,6 @@
 import { readdir } from "node:fs/promises";
 import path from "node:path";
-import { capitalize, isRecord } from "akanjs/common";
+import { capitalize, isRecord, parseRouteModuleKey } from "akanjs/common";
 import { extractBlockVersion, readDevkitVersion } from "./agentsIndex";
 import { AppExecutor, LibExecutor, type SysExecutor, type WorkspaceExecutor } from "./executors";
 import { FileSys } from "./fileSys";
@@ -48,12 +48,25 @@ export interface AkanModuleContext {
   files: string[];
 }
 
+export interface AkanRouteContext {
+  /** The URL pattern without the `/:lang` segment every route starts with. */
+  path: string;
+  file: string;
+  search: string[];
+  /** The page or a layout above it calls `.guard()`. */
+  guarded: boolean;
+  devOnly: boolean;
+}
+
 export interface AkanSysContext {
   type: "app" | "lib";
   name: string;
   path: string;
   hasConfig: boolean;
   modules: AkanModuleContext[];
+  /** Listed for the app `--app` names only; reading them parses every route file. */
+  routes?: AkanRouteContext[];
+  routeError?: string;
 }
 
 export interface AkanPackageContext {
@@ -280,6 +293,7 @@ const generatedFiles = [
 ];
 
 const validationCommands = [
+  "akan verify [<app-or-lib-or-pkg>]",
   "akan sync <app-or-lib>",
   "akan lint <app-or-lib-or-pkg>",
   "akan typecheck <app-or-lib>",
@@ -294,7 +308,7 @@ const unknownGeneratedFilesFreshness: GeneratedFilesFreshness = {
   status: "unknown" as const,
   message: "Run sync before validation so generated Akan files match the current source conventions.",
   refreshCommand: "akan sync <app-or-lib>",
-  verifyingCommands: ["akan lint <app-or-lib-or-pkg>", "akan build <app-name>"],
+  verifyingCommands: ["akan verify <app-or-lib>"],
 };
 
 const repairAction = (
@@ -454,7 +468,7 @@ const generatedFreshnessFromStates = async (workspace: WorkspaceExecutor): Promi
       ? `Generated files were refreshed for ${lastFresh.target} at ${lastFresh.lastSyncedAt}.`
       : "Generated sync state exists, but the last recorded repair did not pass.",
     refreshCommand: "akan sync <app-or-lib>",
-    verifyingCommands: ["akan lint <app-or-lib-or-pkg>", "akan build <app-name>"],
+    verifyingCommands: ["akan verify <app-or-lib>"],
     targets,
   };
 };
@@ -556,6 +570,34 @@ const getSysModules = async (
   return modules.sort((a, b) => `${a.sysName}:${a.path}`.localeCompare(`${b.sysName}:${b.path}`));
 };
 
+const getAppRoutes = async (app: AppExecutor, workspaceRoot: string): Promise<AkanRouteContext[]> => {
+  const sources = await app.getRouteSources();
+  const guardedLayouts = new Set<string>();
+  const pages: { source: (typeof sources)[number]; parsed: ReturnType<typeof parseRouteModuleKey> }[] = [];
+  for (const source of sources) {
+    const parsed = parseRouteModuleKey(source.key);
+    if (parsed.kind === "layout" && source.info.chain?.guarded) guardedLayouts.add(parsed.routeSegments.join("/"));
+    else if (parsed.kind === "page") pages.push({ source, parsed });
+  }
+  return pages
+    .map(({ source, parsed }) => {
+      const segments = parsed.routeSegments;
+      //? The layouts that wrap a page, as the route seed index walks them: an `_index` sits inside its own folder.
+      const reach = parsed.leaf === "_index" ? segments.length : segments.length - 1;
+      const underGuard = Array.from({ length: reach + 1 }, (_, idx) => segments.slice(0, idx).join("/")).some(
+        (prefix) => guardedLayouts.has(prefix),
+      );
+      return {
+        path: parsed.pattern.replace(/^\/:lang/, "") || "/",
+        file: path.relative(workspaceRoot, source.absPath).replaceAll(path.sep, "/"),
+        search: source.info.chain?.search ?? [],
+        guarded: !!source.info.chain?.guarded || underGuard,
+        devOnly: source.info.devOnly,
+      };
+    })
+    .sort((a, b) => a.path.localeCompare(b.path));
+};
+
 const getSysContext = async (
   workspace: WorkspaceExecutor,
   type: "app" | "lib",
@@ -563,7 +605,7 @@ const getSysContext = async (
   options: AkanContextOptions,
 ): Promise<AkanSysContext> => {
   const sys = type === "app" ? AppExecutor.from(workspace, name) : LibExecutor.from(workspace, name);
-  return {
+  const context: AkanSysContext = {
     type,
     name,
     path: `${type}s/${name}`,
@@ -573,6 +615,12 @@ const getSysContext = async (
       module: options.module,
     }),
   };
+  if (sys instanceof AppExecutor && options.app === name)
+    await getAppRoutes(sys, workspace.workspaceRoot).then(
+      (routes) => (context.routes = routes),
+      (error: unknown) => (context.routeError = error instanceof Error ? error.message : String(error)),
+    );
+  return context;
 };
 
 export class AkanContextAnalyzer {
@@ -632,6 +680,42 @@ export class AkanContextAnalyzer {
     };
   }
 
+  //? Codex joins every AGENTS.md from the repo root down to its folder and drops what passes 32 KiB (`project_doc_max_bytes`).
+  static async #agentGuideOversize(workspace: WorkspaceExecutor, sysPaths: string[]) {
+    const sizeOf = async (file: string) => {
+      const content = await safeReadText(path.join(workspace.workspaceRoot, file));
+      return { file, bytes: content === null ? 0 : Buffer.byteLength(content) };
+    };
+    const root = await sizeOf("AGENTS.md");
+    if (root.bytes === 0) return null;
+    const scoped = await Promise.all(sysPaths.map((sysPath) => sizeOf(`${sysPath}/AGENTS.md`)));
+    const largest = scoped.reduce((max, entry) => (entry.bytes > max.bytes ? entry : max), { file: "", bytes: 0 });
+    const total = root.bytes + largest.bytes;
+    if (total <= 32 * 1024 * 0.8) return null;
+    const subject = largest.bytes ? `AGENTS.md and ${largest.file} add up to` : "AGENTS.md is";
+    return `${subject} ${Math.ceil(total / 1024)} KiB of the 32 KiB Codex reads — run \`akan agent install\`, then shorten the text outside the akan:agent markers or move it into a skill.`;
+  }
+
+  static async #agentGuideLeftovers(workspace: WorkspaceExecutor) {
+    const root = workspace.workspaceRoot;
+    const guide = (await safeReadText(path.join(root, "AGENTS.md"))) ?? "";
+    const leftovers: { path: string; message: string }[] = [];
+    for (const doc of ["docs/AI-DEVELOPMENT.md", "docs/GENERATED.md"]) {
+      const pointer = guide.includes(doc);
+      if ((await safeReadText(path.join(root, doc))) !== null)
+        leftovers.push({
+          path: doc,
+          message: `${doc} is an older template's copy of the agent guide, and nothing reads it now — delete it${pointer ? " and the AGENTS.md sentence that points to it" : ""}.`,
+        });
+      else if (pointer)
+        leftovers.push({
+          path: "AGENTS.md",
+          message: `AGENTS.md points to ${doc}, which is gone — delete that sentence.`,
+        });
+    }
+    return leftovers;
+  }
+
   //? Older templates wrote these for Next.js: nothing installs or reads them, and editors warn about the plugin.
   static async #configLeftovers(workspace: WorkspaceExecutor, sysPaths: string[]) {
     const leftovers: { path: string; message: string }[] = [];
@@ -724,6 +808,11 @@ export class AkanContextAnalyzer {
         repairAction("generated", "akan agent install agents-md", agentDrift.hint, true),
       );
     const sysPaths = [...context.apps, ...context.libs].map((sys) => sys.path);
+    const oversize = await AkanContextAnalyzer.#agentGuideOversize(workspace, sysPaths);
+    if (oversize)
+      diagnostics.push({ severity: "warning", code: "agent-guide-oversized", path: "AGENTS.md", message: oversize });
+    for (const leftover of await AkanContextAnalyzer.#agentGuideLeftovers(workspace))
+      diagnostics.push({ severity: "warning", code: "agent-guide-leftover", ...leftover });
     for (const leftover of await AkanContextAnalyzer.#configLeftovers(workspace, sysPaths))
       diagnostics.push({ severity: "warning", code: "config-leftover", ...leftover });
 
@@ -944,6 +1033,12 @@ export class AkanContextAnalyzer {
       ...context.pkgs.map((pkg) => `- ${pkg.name}${pkg.version ? ` (${pkg.version})` : ""}`),
     );
 
+    for (const app of context.apps) {
+      if (app.routeError) lines.push("", `## Routes: ${app.name}`, `- Not read: ${app.routeError}`);
+      else if (app.routes)
+        lines.push("", `## Routes: ${app.name}`, ...AkanContextAnalyzer.#routeLines(app.name, app.routes));
+    }
+
     const modules = AkanContextAnalyzer.findModules(context, moduleName);
     lines.push("", "## Modules");
     for (const module of modules) {
@@ -958,4 +1053,34 @@ export class AkanContextAnalyzer {
     lines.push("", "## Validation", ...context.validationCommands.map((command) => `- \`${command}\``));
     return `${lines.join("\n")}\n`;
   }
+
+  static readonly routeListLimit = 60;
+
+  //? Past the limit the biggest top folders fold into one line each: a docs section alone would fill the context.
+  static #routeLines(appName: string, routes: AkanRouteContext[]) {
+    const folderOf = (route: AkanRouteContext) => route.file.split("/").slice(0, 4).join("/");
+    const groups = Map.groupBy(routes, folderOf);
+    const folded = new Set<string>();
+    let listed = routes.length;
+    for (const [folder, members] of [...groups].sort((a, b) => b[1].length - a[1].length)) {
+      if (listed <= AkanContextAnalyzer.routeListLimit) break;
+      folded.add(folder);
+      listed -= members.length;
+    }
+    const lines = [`Paths omit the \`/:lang\` prefix; \`akan preview ${appName} <path>\` opens one.`];
+    for (const route of routes) {
+      if (folded.has(folderOf(route))) continue;
+      const search = route.search.length ? ` ?${route.search.join("&")}` : "";
+      const marks = `${route.guarded ? " (guarded)" : ""}${route.devOnly ? " (dev only)" : ""}`;
+      lines.push(`- ${route.path}${search}${marks} — ${route.file}`);
+    }
+    for (const folder of folded) {
+      const members = groups.get(folder) ?? [];
+      const examples = members.slice(0, 3).map((route) => route.path);
+      lines.push(
+        `- ${folder}/: ${members.length} routes folded (${examples.join(", ")}, …); \`--format json\` lists every route`,
+      );
+    }
+    return lines;
+  }
 }

package/applicationBuildRunner.test.ts

@@ -9,6 +9,7 @@ import type { App } from "./commandDecorators";
 import { AppExecutor, Executor } from "./executors";
 import { bundleDefine } from "./frontendBuild/bundleDefine";
 import { createTempApp } from "./testHelpers";
+import { ProjectTypecheck } from "./typecheck/projectTypecheck";
 
 describe("ApplicationBuildRunner", () => {
   test("externalizes Akan optional backend dependencies", () => {
@@ -249,4 +250,20 @@ console.info(new SampleService().name);
       await rm(root, { recursive: true, force: true });
     }
   });
+
+  test("akan typecheck names the script/ files nothing imports, and a build's typecheck leaves them out", async () => {
+    const { root, app } = await createTempApp("portal");
+    const run = spyOn(ProjectTypecheck.prototype, "run").mockImplementation(async () => "");
+    try {
+      const runner = new ApplicationBuildRunner(app);
+      await runner.typecheck({ tests: true });
+      await runner.typecheck();
+      const [checked, built] = run.mock.calls.map(([entries]) => entries);
+      expect(checked).toContain("../../script/**/*.ts");
+      expect(built).not.toContain("../../script/**/*.ts");
+    } finally {
+      run.mockRestore();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
 });

package/applicationBuildRunner.ts

@@ -25,8 +25,9 @@ import type { BaseDevEnv, PackageJson } from "./types";
 export interface TypecheckOptions {
   clean?: boolean;
   incremental?: boolean;
-  /** The app's own tests and specs too (`akan typecheck`); a build leaves them out. */
+  /** The app's own tests, specs and `script/` files too (`akan typecheck`); a build leaves them out. */
   tests?: boolean;
+  report?: "pretty" | "records";
 }
 
 export type BuildPhaseId = "prepare" | "typecheck" | "backend" | "ssr" | "csr" | "assets" | "compress" | "metadata";
@@ -205,6 +206,7 @@ export class ApplicationBuildRunner {
         "../../page/**/*.ts",
         "../../page/**/*.tsx",
         ...libPageIncludes,
+        ...(options.tests ? ["../../script/**/*.ts"] : []),
         "../../../../pkgs/akanjs/*/types/**/*.d.ts",
       ],
       options,

package/biome.base.json

@@ -211,7 +211,10 @@
         "!**/*.spec.ts",
         "!**/*.spec.tsx"
       ],
-      "plugins": ["./node_modules/@akanjs/devkit/lint/no-init-fetch-in-client.grit"]
+      "plugins": [
+        "./node_modules/@akanjs/devkit/lint/no-init-fetch-in-client.grit",
+        "./node_modules/@akanjs/devkit/lint/no-oversized-list-limit.grit"
+      ]
     },
     {
       "includes": [

package/cloud/cloudUpdates.ts

@@ -102,8 +102,9 @@ export class CloudUpdates {
       const problems = (record.problems ?? []).map((problem) => `  - ${problem}`).join("\n");
       if (record.status === "rejected") throw new ExitCodeError(`The project rejected ${label}:\n${problems}`, 2);
       const manifestUrl =
-        typeof record.manifestUrl === "string" ? record.manifestUrl : `${url}/${platform}-${arch}/${channel}.json`;
-      const what = `${label} (${release.manifest.bundle}, ${release.payloads.length + 3} files)`;
+        typeof record.manifestUrl === "string" ? record.manifestUrl : `${url}/${platform}-${arch}/${channel}/app.json`;
+      const files = 1 + release.manifestFiles.length + release.payloads.length;
+      const what = `${label} (${release.manifest.bundle}, ${files} files)`;
       Logger.rawLog(
         record.status === "published"
           ? `Published ${what}. Installed apps read ${manifestUrl}.`

package/codeAgent/agent/CodeAgent.ts

@@ -114,6 +114,10 @@ export class CodeAgent {
       profile: options.profile,
       apps: options.apps ?? [],
       canSeeImages: akanCodeModelSupportsImages(model),
+      model: () => {
+        const current = agent.#session?.model;
+        return current ? { provider: current.provider, id: current.id } : undefined;
+      },
       deepseek: await DeepSeekWeb.fromRuntime(modelRuntime, !!proxy),
       depth: options.depth ?? 0,
       ...(options.subagentSpend ? { subagentSpend: options.subagentSpend } : {}),

package/codeAgent/agent/SubagentPool.ts

@@ -2,11 +2,14 @@ import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-ag
 import { type CodeAgentProfile, type CodeAgentSubagent, codeAgentReadOnlyBuiltins } from "akanjs/common";
 import { Type } from "typebox";
 import type { Workspace } from "../../commandDecorators";
+import type { CodeAgentModelRef } from "./akanCodeModel";
 
 export interface SubagentPoolOptions {
   workspace: Workspace;
   cwd: string;
   parent: CodeAgentProfile;
+  /** The parent's model, read when a task starts: a child runs on the model the parent runs on now. */
+  model?: () => CodeAgentModelRef | undefined;
   depth: number;
   /** What the tree above this pool has spent and has running; a root pool starts its own. */
   spend?: SubagentSpend;
@@ -164,10 +167,12 @@ export class SubagentPool {
     const { CodeAgent } = await import("./CodeAgent");
     const budget = this.#options.parent.tools.subagent;
     const child = SubagentPool.childOf(this.#options.parent, kind);
+    const model = this.#options.model?.();
     const agent = await CodeAgent.create({
       workspace: this.#options.workspace,
       cwd: this.#options.cwd,
       profile: child,
+      ...(model ? { model } : {}),
       apps: [],
       depth: this.#options.depth + 1,
       subagentSpend: this.#spend,

package/codeAgent/agent/akanSystemPrompt.ts

@@ -13,7 +13,7 @@ export const akanSystemPrompt = (profile: CodeAgentProfile) => {
   ];
   if (profile.tools.builtin.includes("write"))
     lines.push(
-      "- After editing, call `akan_verify`. It runs sync, lint, typecheck and the SSR check over what the working tree changed. A turn that edits and does not verify is not finished.",
+      "- After editing, call `akan_verify` once. It runs sync, lint, typecheck, a fast build and the SSR check over what the working tree changed; never run `akan lint`, `akan typecheck` or `akan build` separately. A turn that edits and does not verify is not finished.",
     );
   else
     lines.push(

package/codeAgent/agent/codeAgent.test.ts

@@ -6,7 +6,7 @@ import { type CodeAgentEvent, type CodeAgentProfile, codeAgentPresets } from "ak
 import { WorkspaceExecutor } from "../../executors";
 import { isolateEnv, tempDirs } from "../../testHelpers";
 import { AkanCodePlugins } from "../tools/AkanCodePlugins";
-import { akanCodeDefaultModel } from "./akanCodeModel";
+import { akanCodeDefaultModel, type CodeAgentModelRef } from "./akanCodeModel";
 import { akanCodePaths } from "./akanCodePaths";
 import { CodeAgent, type CodeAgentOptions } from "./CodeAgent";
 import { CodeAgentSuspended } from "./CodeAgentSuspended";
@@ -37,11 +37,14 @@ const usageChunk = (promptTokens: number) =>
 let llm: ReturnType<typeof Bun.serve>;
 let llmCalls = 0;
 let reportedTokens = 0;
+const requestedModels: string[] = [];
 beforeAll(() => {
   llm = Bun.serve({
     port: 0,
-    fetch: () => {
+    fetch: async (request) => {
       llmCalls += 1;
+      const body = (await request.json().catch(() => ({}))) as { model?: string };
+      requestedModels.push(body.model ?? "");
       const usage = reportedTokens ? usageChunk(reportedTokens) : "";
       return new Response(
         `${chunk({ role: "assistant", content: "ok" })}${chunk({}, "stop")}${usage}data: [DONE]\n\n`,
@@ -160,6 +163,42 @@ describe("CodeAgent", () => {
       spy.mockRestore();
     }
   });
+
+  test("a task child sends its requests on the parent's model, and on the one the parent switches to", async () => {
+    const root = await makeTempRoot();
+    const build = AkanCodePlugins.build;
+    let parentModel: (() => CodeAgentModelRef | undefined) | undefined;
+    const spy = spyOn(AkanCodePlugins, "build").mockImplementation(async (options) => {
+      parentModel = options.model;
+      return await build.call(AkanCodePlugins, options);
+    });
+    const agent = await createAgent(root, { model: { provider: "deepseek", id: "deepseek-v4-pro" } });
+    spy.mockRestore();
+    const profile = quietProfile(root);
+    const pool = SubagentPool.extensionFor({
+      workspace: new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" }),
+      cwd: root,
+      parent: { ...profile, tools: { ...profile.tools, subagent: { maxDepth: 2, maxConcurrent: 3, budget: 100_000 } } },
+      ...(parentModel ? { model: parentModel } : {}),
+      depth: 0,
+    });
+    let execute: ((id: string, params: never) => Promise<unknown>) | undefined;
+    if (pool && "factory" in pool)
+      pool.factory({
+        registerTool: (tool: { execute: typeof execute }) => {
+          execute = tool.execute;
+        },
+      } as never);
+    try {
+      requestedModels.length = 0;
+      await execute?.("c1", { description: "d", prompt: "p" } as never);
+      await agent.setModel(akanCodeDefaultModel);
+      await execute?.("c2", { description: "d", prompt: "p" } as never);
+      expect(requestedModels).toEqual(["deepseek-v4-pro", akanCodeDefaultModel.id]);
+    } finally {
+      agent.dispose();
+    }
+  });
 });
 
 describe("a sub-agent its parent stops before the sub-agent's run is live", () => {

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,36 @@
+---
+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`.
+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.
+- `.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.
+- 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

@@ -85,6 +85,7 @@ 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.

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

@@ -1,10 +1,42 @@
 ---
 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 and get the default locale when they lack one: `akan preview <app> /board,/board/new`.
+  `--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 +49,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 +72,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-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.