@akanjs/devkit 3.1.1-rc.16 → 3.1.1-rc.17

package/agentAssets.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+import fsPromise from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { AgentAssets } from "./agentAssets";
+
+describe("AgentAssets", () => {
+  test("packs whole H2 sections into parts under the limit, never splitting at a fenced heading", () => {
+    const section = (name: string, size: number) => `## ${name}\n${"x".repeat(size)}`;
+    const fenced = "## C\n```md\n## not a heading\n```";
+    const parts = AgentAssets.split(
+      ["# Title", section("A", 20_000), section("B", 7_000), fenced, section("D", 10_000)].join("\n"),
+    );
+    expect(parts.map((part) => part.headings)).toEqual([["A", "B", "C"], ["D"]]);
+    expect(parts.every((part) => part.text.length <= AgentAssets.referenceLimit)).toBe(true);
+    expect(parts[0]?.text).toStartWith("# Title\n## A");
+  });
+
+  test("ships the public skills under both roots with their guidelines once, inside every size budget", async () => {
+    const assets = await AgentAssets.skills();
+    const names = Object.keys(AgentAssets.skillReferences);
+    const skills = assets.filter((asset) => asset.path.endsWith("/SKILL.md"));
+    expect(names.length).toBeLessThanOrEqual(16);
+    const byName = (a: string, b: string) => a.localeCompare(b);
+    expect(skills.map((asset) => asset.path).sort(byName)).toEqual(
+      AgentAssets.skillRoots.flatMap((root) => names.map((name) => `${root}/${name}/SKILL.md`)).sort(byName),
+    );
+    expect(assets.some((asset) => asset.path.includes("akan-code"))).toBe(false);
+
+    const descriptions = skills
+      .filter((asset) => asset.path.startsWith(".agents/"))
+      .map((asset) => {
+        const described: RegExpExecArray | null = /description:\s*"?(.+?)"?\n/.exec(asset.content);
+        return described?.[1] ?? "";
+      });
+    expect(descriptions.join("").length).toBeLessThanOrEqual(4_000);
+    for (const skill of skills)
+      expect([skill.path, skill.content.split("\n").length <= 500]).toEqual([skill.path, true]);
+
+    const references = assets.filter((asset) => asset.path.includes("/references/"));
+    expect(references.every((asset) => asset.path.startsWith(".agents/skills/"))).toBe(true);
+    for (const reference of references) {
+      expect(reference.content.length).toBeLessThanOrEqual(AgentAssets.referenceLimit + 100);
+      expect(skills.find((skill) => skill.content.includes(`\`${reference.path}\``))).toBeDefined();
+    }
+    expect(references.filter((asset) => asset.path.includes("/agentRule")).length).toBeGreaterThan(1);
+  });
+
+  test("names no rule or skill file that a new workspace's .gitignore would keep out of git", async () => {
+    const assets = [...(await AgentAssets.rules()), ...(await AgentAssets.skills())];
+    const root = await fsPromise.mkdtemp(path.join(os.tmpdir(), "akan-agent-ignore-"));
+    const template = path.join(import.meta.dir, "../cli/templates/workspaceRoot/.gitignore.template");
+    await fsPromise.copyFile(template, path.join(root, ".gitignore"));
+    Bun.spawnSync(["git", "init", "-q"], { cwd: root });
+    const proc = Bun.spawn(["git", "check-ignore", "--no-index", "--stdin"], {
+      cwd: root,
+      stdin: new Blob([assets.map((asset) => asset.path).join("\n")]),
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [ignored, exitCode] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+    await fsPromise.rm(root, { recursive: true, force: true });
+    expect({ exitCode, ignored: ignored.split("\n").filter(Boolean) }).toEqual({ exitCode: 1, ignored: [] });
+  });
+});

package/agentAssets.ts

@@ -0,0 +1,166 @@
+import fsPromise from "node:fs/promises";
+import path from "node:path";
+import { akanCodePaths } from "./codeAgent/agent/akanCodePaths";
+import { type ConventionRule, ConventionSet } from "./conventionSet";
+import { Prompter } from "./prompter";
+
+export interface AgentAsset {
+  path: string;
+  content: string;
+}
+
+interface ReferencePart {
+  text: string;
+  headings: string[];
+}
+
+export class AgentAssets {
+  static readonly marker = "<!-- akan:generated -->";
+  static readonly ruleDir = ".claude/rules/akan";
+  static readonly skillRoots = [".claude/skills", ".agents/skills"] as const;
+  //? Claude Code cuts a shell command's output at 30,000 characters, and an agent without a file reader `cat`s a part.
+  static readonly referenceLimit = 28_000;
+  static readonly ownedGlobs = [
+    ".claude/rules/akan/*.md",
+    ".cursor/rules/akan-*.mdc",
+    ".claude/skills/akan-*/**",
+    ".agents/skills/akan-*/**",
+  ] as const;
+  static readonly skillReferences = {
+    "akan-validate": [],
+    "akan-scaffold": ["workspaceRecipes"],
+    "akan-module": ["moduleOverview", "modelConstant", "modelDictionary", "fieldRule"],
+    "akan-scalar": ["scalarModule", "scalarConstant", "scalarDictionary"],
+    "akan-service": ["modelService", "modelSignal", "modelDocument"],
+    "akan-store": ["modelStore"],
+    "akan-ui": [
+      "ssrRule",
+      "cssRule",
+      "componentRule",
+      "recipeRule",
+      "modelTemplate",
+      "modelUnit",
+      "modelView",
+      "modelZone",
+      "modelUtil",
+      "framework",
+    ],
+    "akan-err": [],
+    "akan-deps": [],
+    "akan-debug": [],
+    "akan-page": ["pageRule"],
+    "akan-query": ["queryRule"],
+    "akan-transport": ["transportRule"],
+    "akan-runtime": ["runtimeRule"],
+    "akan-mcp": ["mcpRule"],
+    "akan-agent": ["agentRule"],
+  } as const;
+
+  static async rules({ appendix = {} }: { appendix?: Record<string, string> } = {}) {
+    const conventions = await Prompter.getConventionSet();
+    return conventions.rules.flatMap((rule) => AgentAssets.#ruleFiles(rule, appendix[rule.name]));
+  }
+
+  static rulePath(name: string) {
+    return `${AgentAssets.ruleDir}/${name}.md`;
+  }
+
+  static #ruleFiles(rule: ConventionRule, appendix?: string): AgentAsset[] {
+    const globs = rule.paths.flatMap((glob) => ConventionSet.expand(glob));
+    const body = appendix ? `${rule.body}\n\n${appendix.trim()}` : rule.body;
+    const claude = `---
+description: ${rule.description}
+paths:
+${globs.map((glob) => `  - "${glob}"`).join("\n")}
+---
+
+${AgentAssets.marker}
+
+${body}
+`;
+    const cursor = `---
+description: ${rule.description}
+globs: ${globs.join(",")}
+alwaysApply: false
+---
+
+${AgentAssets.marker}
+
+@${AgentAssets.rulePath(rule.name)}
+`;
+    return [
+      { path: AgentAssets.rulePath(rule.name), content: claude },
+      { path: `.cursor/rules/akan-${rule.name}.mdc`, content: cursor },
+    ];
+  }
+
+  static async skills() {
+    const dir = akanCodePaths.builtinSkillsDir();
+    if (!dir) return [];
+    const assets: AgentAsset[] = [];
+    for (const [name, guidelines] of Object.entries(AgentAssets.skillReferences)) {
+      const source = await fsPromise.readFile(path.join(dir, name, "SKILL.md"), "utf-8");
+      const index: string[] = [];
+      for (const guideline of guidelines) {
+        const parts = AgentAssets.split(await Prompter.getInstruction(guideline));
+        parts.forEach((part, idx) => {
+          const file = parts.length === 1 ? `${guideline}.md` : `${guideline}-${idx + 1}.md`;
+          const referencePath = `.agents/skills/${name}/references/${file}`;
+          assets.push({ path: referencePath, content: `${AgentAssets.marker}\n\n${part.text.trim()}\n` });
+          index.push(`- \`${referencePath}\` — ${AgentAssets.#summarize(part.headings)}`);
+        });
+      }
+      const skill = AgentAssets.#skillFile(source, index);
+      for (const root of AgentAssets.skillRoots) assets.push({ path: `${root}/${name}/SKILL.md`, content: skill });
+    }
+    return assets;
+  }
+
+  static split(markdown: string): ReferencePart[] {
+    const sections: ReferencePart[] = [];
+    let fenced = false;
+    for (const line of markdown.trim().split("\n")) {
+      if (line.startsWith("```")) fenced = !fenced;
+      const heading = !fenced && line.startsWith("## ") ? line.slice(3).trim() : null;
+      const last = sections.at(-1);
+      if (heading !== null || !last) sections.push({ text: line, headings: heading === null ? [] : [heading] });
+      else last.text += `\n${line}`;
+    }
+    const parts: ReferencePart[] = [];
+    for (const section of sections) {
+      const last = parts.at(-1);
+      if (last && last.text.length + section.text.length + 1 <= AgentAssets.referenceLimit) {
+        last.text += `\n${section.text}`;
+        last.headings.push(...section.headings);
+      } else parts.push({ text: section.text, headings: [...section.headings] });
+    }
+    return parts;
+  }
+
+  static #summarize(headings: string[]) {
+    if (headings.length === 0) return "the whole guideline";
+    const shown = headings.slice(0, 5).join(" · ");
+    return headings.length > 5 ? `${shown} · …` : shown;
+  }
+
+  static #skillFile(source: string, index: string[]) {
+    const match: RegExpExecArray | null = /^---\n[\s\S]*?\n---\n/.exec(source);
+    const front = match?.[0] ?? "";
+    const body = source.slice(front.length).trim();
+    const references = index.length
+      ? `\n\n## References\n\nThe full guidelines, split where each part fits one read; \`akan guideline show <name>\` prints the same text.\n\n${index.join("\n")}`
+      : "";
+    return `${front}\n${AgentAssets.marker}\n\n${body}${references}\n`;
+  }
+
+  static async generatedFiles(workspaceRoot: string) {
+    const found: string[] = [];
+    for (const pattern of AgentAssets.ownedGlobs) {
+      for (const file of new Bun.Glob(pattern).scanSync({ cwd: workspaceRoot, dot: true, onlyFiles: true })) {
+        const content = await Bun.file(path.join(workspaceRoot, file)).text();
+        if (content.includes(AgentAssets.marker)) found.push(file.split(path.sep).join("/"));
+      }
+    }
+    return found.sort((a, b) => a.localeCompare(b));
+  }
+}

package/agentsIndex.ts

@@ -119,16 +119,16 @@ export const renderScopeAgentBlock = (scope: AgentsIndexScope, recipes: RecipeIn
   const scopePath = `${scope.type}s/${scope.name}`;
   const intro = `## Recipes In Scope
 
-UI recipes importable from \`${scopePath}\` code, **in addition to** the framework recipes indexed in the root
-\`AGENTS.md\` \`## Recipes\`. Same contract: import by exact name, then \`<name>(variants?, className?)\` — the second
+UI recipes importable from \`${scopePath}\` code, **in addition to** the framework recipes indexed in
+\`.claude/rules/akan/style.md\`. Same contract: import by exact name, then \`<name>(variants?, className?)\` — the second
 arg merges internally and takes an array too, so never wrap it in \`cn()\`. \`*\` marks the default, \`key?\` is a
 boolean flag. Do not guess recipe names or import paths; this index is regenerated by \`akan sync ${scope.name}\`
 and verified by \`akan lint ${scope.name}\`.`;
   if (recipes.length === 0) {
     return `${intro}
 
-No scope recipes yet. Before inlining a repeated surface (card, box, tile, …), reuse a framework recipe from the
-root \`AGENTS.md\` or author one as \`${scopePath}/ui/Recipe/<name>.ts\` (one recipe per file, re-exported from that
+No scope recipes yet. Before inlining a repeated surface (card, box, tile, …), reuse a framework recipe from
+\`.claude/rules/akan/style.md\` or author one as \`${scopePath}/ui/Recipe/<name>.ts\` (one recipe per file, re-exported from that
 folder's \`index.ts\`) — see the \`recipeRule\` guideline.`;
   }
   return `${intro}

package/akanContext.ts

@@ -280,6 +280,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 +295,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 +455,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,
   };
 };
@@ -632,6 +633,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 +761,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 });
 

package/applicationBuildRunner.ts

@@ -27,6 +27,7 @@ export interface TypecheckOptions {
   incremental?: boolean;
   /** 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";

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/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/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-debug/SKILL.md

@@ -22,7 +22,7 @@ what survives in the scrollback is bordered and truncated to the pane.
 
 ## 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 +38,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.

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,38 @@
+---
+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) instead of one call per item in a loop — lint fails a
+  per-item service call an endpoint reaches.
+
+## 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,40 @@
+---
+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` |
+
+- `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>`.
+- 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`.

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

@@ -43,8 +43,8 @@ Each result names the next call in `next.tool`. Follow it; do not improvise.
    and each workflow's inputs.)
 2. `apply_workflow({ planPath })` — writes the scaffold and syncs the generated barrels. Returns
    `validationTarget`.
-3. `run_validation({ runIdOrPlan: <validationTarget> })`, or just call `akan_verify`, which runs the whole
-   chain over everything the working tree changed.
+3. `run_validation({ runIdOrPlan: <validationTarget> })`, or run `akan verify` (`akan_verify` in akan code);
+   both are the whole chain in one process.
 4. **Read each scaffolded file before editing it.** They are a few lines each and they extend base classes
    that already generated the CRUD surface. Read the `akan-store` skill before touching a store or adding
    signal endpoints, or you will redeclare `create<Model>` and hit an "already exists" typecheck error.
@@ -60,9 +60,19 @@ Each result names the next call in `next.tool`. Follow it; do not improvise.
 - Hand-writing files is the fallback, used only when no workflow matches, or when apply reports
   unsupported / no-op / failed diagnostics telling you to act manually. Say which case applied.
 - Never hand-edit a generated file to "finish" a scaffold — use `repair_generated` or `akan sync <app>`.
-- No workflow tools this turn? The same order through bash:
-  `akan workflow list` → `akan workflow plan create-module --app <app> --module comment --format json --out <path>`
-  → `akan workflow apply <path> --format json`.
+
+## No workflow tools? The CLI is the same chain
+
+The tools come from `akan mcp` (`--mode plan` reads, `--mode apply` writes). When they are not connected, each
+has a command that prints the same report:
+
+| tool | command |
+| --- | --- |
+| `list_workflows` / `explain_workflow` | `akan workflow list` / `akan workflow explain <name>` |
+| `plan_workflow` | `akan workflow plan create-module --app <app> --module comment --format json --out <path>` |
+| `apply_workflow` | `akan workflow apply <path> --format json` (`--dry-run` previews) |
+| `run_validation` | `akan verify <app>` |
+| `repair_generated` / `repair_imports` / `repair_module_shape` | `akan repair generated\|imports\|module-shape --app <app>` |
 
 ## Worked example — "an intro page, two detail pages, and a comment zone with a database"
 
@@ -73,4 +83,4 @@ Each result names the next call in `next.tool`. Follow it; do not improvise.
    leave the store body empty unless you need extra state.
 4. Write the pages and the comment UI against the generated actions — `st.do.createComment`,
    `st.do.initCommentInPublic`, `st.use.commentListInPublic`.
-5. `akan_verify` until clean.
+5. `akan verify` until it prints `verify ok`.