@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/codeAgent/feedback/PreviewView.ts

@@ -0,0 +1,95 @@
+import { PreviewChrome } from "./PreviewChrome";
+
+export interface PreviewProbeResult {
+  url: string;
+  title: string;
+  consoleErrors: string[];
+  pageErrors: string[];
+  /** Cheap structural smells that read as "the page is broken" without anyone looking at it. */
+  domFindings: string[];
+  screenshot?: string;
+}
+
+interface WebViewLike {
+  navigate(url: string): Promise<void>;
+  evaluate(expression: string): Promise<unknown>;
+  screenshot(options: { encoding: "base64" }): Promise<string>;
+  close(): void | Promise<void>;
+  readonly title: string;
+}
+
+// Bun.WebView rather than a downloaded browser: on macOS its webkit backend needs no Chromium at all.
+// It is experimental, so its whole surface stays behind this adapter; a Bun minor that changes it breaks one file.
+export class PreviewView {
+  static get available() {
+    return typeof (Bun as unknown as { WebView?: unknown }).WebView === "function" && PreviewChrome.available;
+  }
+
+  static unavailableReason() {
+    if (typeof (Bun as unknown as { WebView?: unknown }).WebView !== "function")
+      return "This Bun build has no WebView, so the page preview is off.";
+    return PreviewChrome.unavailableReason();
+  }
+
+  static async probe(url: string, { screenshot = false, width = 1280, height = 800 } = {}) {
+    const logs: string[] = [];
+    const view = PreviewView.#open({ width, height, onConsole: (line) => logs.push(line) });
+    try {
+      await view.navigate(url);
+      const result: PreviewProbeResult = {
+        url,
+        title: view.title,
+        consoleErrors: logs.filter((line) => line.startsWith("error") || line.startsWith("warn")),
+        pageErrors: PreviewView.#strings(await view.evaluate(pageErrorsExpression)),
+        domFindings: PreviewView.#strings(await view.evaluate(domFindingsExpression)),
+      };
+      if (screenshot) result.screenshot = await view.screenshot({ encoding: "base64" });
+      return result;
+    } finally {
+      await view.close();
+    }
+  }
+
+  static #open({ width, height, onConsole }: { width: number; height: number; onConsole: (line: string) => void }) {
+    const Ctor = (Bun as unknown as { WebView: new (options: unknown) => WebViewLike }).WebView;
+    return new Ctor({
+      width,
+      height,
+      dataStore: "ephemeral",
+      backend: PreviewChrome.backendOption(),
+      // The console option is a callback taking `(type, ...args)`, not an object of console methods.
+      console: (type: string, ...args: unknown[]) => onConsole(`${type} ${args.map(String).join(" ")}`),
+    });
+  }
+
+  static #strings(value: unknown) {
+    return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+  }
+}
+
+// evaluate() takes one expression (a statement list is a SyntaxError), hence the IIFEs; one call in flight per view.
+const pageErrorsExpression = `(() => {
+  const found = [];
+  const root = document.getElementById("__next") || document.body;
+  const rendered = root ? Array.from(root.children).filter((el) => !["SCRIPT", "STYLE", "TEMPLATE", "LINK", "NOSCRIPT"].includes(el.tagName)) : [];
+  if (!rendered.length && !(root && root.innerText && root.innerText.trim())) found.push("The page body rendered empty.");
+  const overlay = document.querySelector("[data-nextjs-dialog], .error-overlay, #akan-error");
+  if (overlay) found.push("An error overlay is on the page: " + overlay.textContent.slice(0, 400));
+  return found;
+})()`;
+
+const domFindingsExpression = `(() => {
+  const found = [];
+  const all = Array.from(document.querySelectorAll("body *"));
+  const overflowing = all.filter((el) => el.scrollWidth > document.documentElement.clientWidth + 8);
+  if (overflowing.length) found.push(overflowing.length + " element(s) overflow the viewport horizontally, first: " + (overflowing[0].tagName + "." + overflowing[0].className).slice(0, 120));
+  const invisibleText = all.filter((el) => {
+    if (!el.textContent || !el.textContent.trim()) return false;
+    const style = getComputedStyle(el);
+    return style.color === style.backgroundColor && style.backgroundColor !== "rgba(0, 0, 0, 0)";
+  });
+  if (invisibleText.length) found.push(invisibleText.length + " element(s) render text in the same colour as their background.");
+  const unresolved = all.filter((el) => /(^|\\s)(bg|text|border)-(base-100|base-content|primary-content|error)(\\s|$)/.test(el.className || ""));
+  if (unresolved.length) found.push(unresolved.length + " element(s) use a dropped daisyUI colour slot that renders no CSS.");
+  return found;
+})()`;

package/codeAgent/feedback/TurnFeedback.ts

@@ -0,0 +1,98 @@
+import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
+
+/** A base64 PNG, attached only when the active model can read one. */
+export interface TurnFeedbackImage {
+  data: string;
+  mimeType: string;
+}
+
+export interface TurnFeedbackFinding {
+  text: string;
+  images?: TurnFeedbackImage[];
+}
+
+export interface TurnFeedbackSource {
+  /** Budget is counted per key, so one stuck source cannot spend another's attempts. */
+  key: string;
+  /** Record whatever "before" this source compares against. Never throws — a source that cannot arm is skipped. */
+  begin(): Promise<void> | void;
+  /** What the turn caused that the agent cannot see, or `undefined` when there is nothing to say. */
+  observe(): Promise<TurnFeedbackFinding | string | undefined> | TurnFeedbackFinding | string | undefined;
+}
+
+export interface TurnFeedbackOptions {
+  /** How many times one source may reopen a turn before it gives up and lets the human see it. */
+  budget: number;
+  onNotice?: (message: string) => void;
+}
+
+// The engine's `agent_end` hook cannot veto the end of a turn, so a finding is a follow-up that opens a new one.
+// The budget is load-bearing: without it one unfixable error reopens turns until the context or the wallet runs out.
+export class TurnFeedback {
+  readonly #sources: TurnFeedbackSource[];
+  readonly #options: TurnFeedbackOptions;
+  readonly #spent = new Map<string, number>();
+
+  constructor(sources: TurnFeedbackSource[], options: TurnFeedbackOptions) {
+    this.#sources = sources;
+    this.#options = options;
+  }
+
+  extension(): InlineExtension {
+    return {
+      name: "akan-turn-feedback",
+      factory: (pi: ExtensionAPI) => {
+        pi.on("agent_start", async () => {
+          await Promise.all(this.#sources.map((source) => TurnFeedback.#quietly(() => source.begin())));
+        });
+        pi.on("agent_end", async () => {
+          const message = await this.collect();
+          if (message) pi.sendUserMessage(message, { deliverAs: "followUp" });
+        });
+      },
+    };
+  }
+
+  async collect() {
+    const texts: string[] = [];
+    const images: TurnFeedbackImage[] = [];
+    const reopened: string[] = [];
+    for (const source of this.#sources) {
+      const finding = await TurnFeedback.#quietly(() => source.observe());
+      if (!finding) {
+        this.#spent.delete(source.key);
+        continue;
+      }
+      const spent = this.#spent.get(source.key) ?? 0;
+      if (spent >= this.#options.budget) {
+        this.#options.onNotice?.(`${source.key}: still failing after ${spent} attempts — handing back to you.`);
+        continue;
+      }
+      this.#spent.set(source.key, spent + 1);
+      reopened.push(source.key);
+      if (typeof finding === "string") texts.push(finding);
+      else {
+        texts.push(finding.text);
+        images.push(...(finding.images ?? []));
+      }
+    }
+    if (!texts.length) return undefined;
+    this.#options.onNotice?.(`${reopened.join(" · ")} reopened the turn — esc stops it`);
+    const text = [
+      "The previous turn left problems you cannot see from the transcript. Fix them, then stop.",
+      ...texts,
+    ].join("\n\n");
+    return images.length
+      ? [{ type: "text" as const, text }, ...images.map((image) => ({ type: "image" as const, ...image }))]
+      : text;
+  }
+
+  /** Every source is best-effort: no dev server, no git, no preview — all of them mean "nothing to report". */
+  static async #quietly<T>(fn: () => T | Promise<T>) {
+    try {
+      return await fn();
+    } catch {
+      return undefined;
+    }
+  }
+}

package/codeAgent/feedback/VerifyFeedback.ts

@@ -0,0 +1,40 @@
+import { AkanEditScope } from "../tools/AkanEditScope";
+import { AkanVerifier } from "../tools/AkanVerifier";
+import type { TurnFeedbackSource } from "./TurnFeedback";
+
+export interface VerifyFeedbackOptions {
+  cwd: string;
+  /** A read-only profile reports what is stale instead of running a chain that would write generated files. */
+  readOnly?: boolean;
+}
+
+// A hook, not a reliance on the akan_verify tool: the observed failure is a model finishing without calling it.
+export class VerifyFeedback implements TurnFeedbackSource {
+  readonly key = "verify";
+  readonly #options: VerifyFeedbackOptions;
+  readonly #verifier: AkanVerifier;
+  #baseline: ReadonlySet<string> = new Set();
+
+  constructor(options: VerifyFeedbackOptions) {
+    this.#options = options;
+    this.#verifier = new AkanVerifier(options.cwd);
+  }
+
+  async begin() {
+    this.#baseline = await AkanEditScope.baseline(this.#options.cwd);
+  }
+
+  async observe() {
+    const scope = await AkanEditScope.since(this.#options.cwd, this.#baseline);
+    if (!scope.apps.length && !scope.libs.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);
+  }
+
+  static #readOnlyNotice(needsSync: boolean, targets: string[]) {
+    if (!needsSync) return undefined;
+    return `Files were added or removed under ${targets.join(", ")}, so the generated barrels are stale. This profile does not write, so run \`akan sync ${targets.join(" ")}\` yourself before trusting a typecheck.`;
+  }
+}

package/codeAgent/feedback/previewChrome.test.ts

@@ -0,0 +1,73 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { PreviewChrome } from "./PreviewChrome";
+
+const saved = {
+  backend: process.env[PreviewChrome.backendEnvKey],
+  path: process.env[PreviewChrome.pathEnvKey],
+};
+
+afterEach(() => {
+  if (saved.backend === undefined) delete process.env[PreviewChrome.backendEnvKey];
+  else process.env[PreviewChrome.backendEnvKey] = saved.backend;
+  if (saved.path === undefined) delete process.env[PreviewChrome.pathEnvKey];
+  else process.env[PreviewChrome.pathEnvKey] = saved.path;
+});
+
+describe("PreviewChrome", () => {
+  test("picks the system framework on macOS and Chrome everywhere else", () => {
+    expect(PreviewChrome.backend).toBe(process.platform === "darwin" ? "webkit" : "chrome");
+  });
+
+  test("an explicit backend wins over the platform default", () => {
+    process.env[PreviewChrome.backendEnvKey] = "chrome";
+    expect(PreviewChrome.backend).toBe("chrome");
+    process.env[PreviewChrome.backendEnvKey] = "webkit";
+    expect(PreviewChrome.backend).toBe("webkit");
+  });
+
+  test("an unknown backend name falls back rather than reaching the launcher", () => {
+    process.env[PreviewChrome.backendEnvKey] = "firefox";
+    expect(PreviewChrome.backend).toBe(process.platform === "darwin" ? "webkit" : "chrome");
+  });
+
+  test("the Chrome option carries the two flags a container needs and Bun does not add", () => {
+    process.env[PreviewChrome.backendEnvKey] = "chrome";
+    const option = PreviewChrome.backendOption();
+    expect(typeof option).toBe("object");
+    expect((option as { argv: string[] }).argv).toContain("--disable-dev-shm-usage");
+  });
+
+  test("the webkit option is the bare string the constructor validates", () => {
+    process.env[PreviewChrome.backendEnvKey] = "webkit";
+    expect(PreviewChrome.backendOption()).toBe("webkit");
+  });
+
+  test("BUN_CHROME_PATH is honoured, because Bun's own launcher reads it", () => {
+    process.env[PreviewChrome.pathEnvKey] = "/opt/custom/chrome";
+    expect(PreviewChrome.executable()).toBe("/opt/custom/chrome");
+  });
+
+  test("availability tracks the resolved backend", () => {
+    process.env[PreviewChrome.backendEnvKey] = "chrome";
+    process.env[PreviewChrome.pathEnvKey] = "/opt/custom/chrome";
+    expect(PreviewChrome.available).toBe(true);
+    expect(PreviewChrome.unavailableReason()).toBeUndefined();
+  });
+
+  test("the unavailable message names the install step rather than only the symptom", () => {
+    process.env[PreviewChrome.backendEnvKey] = "chrome";
+    delete process.env[PreviewChrome.pathEnvKey];
+    if (PreviewChrome.available) return;
+    const reason = PreviewChrome.unavailableReason() ?? "";
+    expect(reason).toContain("chromium");
+    expect(reason).toContain(PreviewChrome.pathEnvKey);
+  });
+
+  test("the image steps install fonts, or every rendered glyph is a box", () => {
+    const step = PreviewChrome.dockerRuns.join(" ");
+    expect(step).toContain("chromium");
+    expect(step).toContain("fonts-noto-cjk");
+    // Leftover apt lists bloat every image layer that takes this step.
+    expect(step).toContain("rm -rf /var/lib/apt/lists/*");
+  });
+});

package/codeAgent/index.ts

@@ -0,0 +1,34 @@
+// 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 "./agent/AkanCodeServices";
+export * from "./agent/akanCodeModel";
+export * from "./agent/akanCodePaths";
+export * from "./agent/akanSystemPrompt";
+export * from "./agent/CodeAgent";
+export * from "./agent/CodeAgentAsks";
+export * from "./agent/CodeAgentEventMapper";
+export * from "./agent/CodeAgentGate";
+export * from "./agent/CodeAgentRpcHost";
+export * from "./agent/CodeAgentStreamPrinter";
+export * from "./agent/CodeAgentUi";
+export * from "./agent/CodeMailbox";
+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";
+export * from "./tools/AkanCodePlugins";
+export * from "./tools/AkanEditScope";
+export * from "./tools/AkanEnvKeys";
+export * from "./tools/AkanToolPack";
+export * from "./tools/AkanVerifier";
+export * from "./tools/MailToolPack";
+export * from "./tools/McpClient";
+export * from "./tools/McpToolPack";
+export * from "./tools/SessionToolPack";
+export * from "./tools/WebToolPack";

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

@@ -0,0 +1,130 @@
+---
+name: akan-code
+description: "Answer a question about `akan code` itself — how to add or remove an MCP server, sign one in, switch model, fork or resume a session, what the slash commands and keys are, and where its files live. Read this before telling anyone how to use this tool."
+---
+
+# akan code — the manual
+
+This is the tool the user is talking to right now. When they ask how to do something *with it* — rather than
+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.
+
+## MCP servers
+
+Declared in **`~/.akan/code/mcp.json`**, which every repo reads, or in this repo's **`.akan/code/mcp.json`**,
+which wins a name both declare — in the same `mcpServers` shape Claude, Cursor and VS Code already write, so a
+block can be pasted across rather than translated. VS Code's `servers` spelling is read too, and
+whichever key the file already uses is the one a write goes back into.
+
+```jsonc
+{
+  "mcpServers": {
+    "github":   { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
+    "linear":   { "url": "https://mcp.linear.app/sse" },
+    "internal": { "url": "https://…/mcp", "headers": { "x-api-key": "…" } },
+    "old":      { "command": "x", "disabled": true }
+  }
+}
+```
+
+A `url` is an http server; anything else is a command with its argv. `env` passes variables to a stdio
+server, `headers` goes on every http request (a server behind a static token needs nothing else), and
+`disabled: true` keeps an entry without connecting it.
+
+From the prompt:
+
+```
+/mcp                      what is declared, what connected, and how many tools each gave
+/mcp <name>               the tools that one server published
+/mcp add <name> <command> [args…]
+/mcp add <name> <https://…>
+/mcp add --local <name> … this repo's file only, not ~/.akan/code/mcp.json
+/mcp remove <name>        this repo's file first, else ~/.akan/code/mcp.json
+/mcp remove --local <name>
+/mcp login <name>         OAuth, in the browser
+/mcp logout <name>        forget the token, leaving the server declared
+/mcp reload               reopen this session so the file takes effect
+```
+
+**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`.
+
+`/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.
+
+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
+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.
+
+## Sessions
+
+Stored under `.akan/code/sessions` — project history, so a second checkout of the same repo has its own.
+
+- `←` at the start of the prompt lists past sessions; enter reopens the chosen one.
+- `akan code --resume <id>` (`-R`) reopens one from the shell.
+- `/fork [name]` continues the conversation twice: the copy takes over here, and the notice names the command
+  that reopens the original.
+- `/name <text>` names this one, which is what the session list is read by.
+- `/peers` lists other `akan code` sessions running in this workspace; `/msg <peer> <text>` hands one a
+  message.
+- `/clear` wipes the screen and keeps the conversation; `/compact [notes]` shortens what the model carries.
+
+## Model, effort, keys
+
+- `/model <provider>/<id>`, e.g. `/model deepseek/deepseek-v4-pro`. `/effort <level>` for how hard it thinks.
+- 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.
+
+## 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.
+
+## Keys
+
+```
+enter send · shift+enter newline · ↑↓ move (history at the edges) · ←→ move
+esc interrupt · pgup/pgdn scroll · ^c quit · tab completes a slash command
+@ completes a file in this repo · wheel scrolls the transcript (hold shift to select text instead)
+cmd+v attaches an image from the clipboard · ^v does too, without the terminal in the way
+```
+
+Most terminals send the same byte for enter and shift+enter, so the key only arrives where the terminal can
+say which was pressed. In VS Code, bind it with `workbench.action.terminal.sendSequence` and a `text` of
+`"\\\u001b\r"`; iTerm2 calls the same thing "Send Text". Either spelling of that sequence works here, and
+the backslash a shell would read as a line continuation never reaches the prompt.
+
+## Starting it
+
+```
+akan code                       open the session
+akan code "<prompt>"            run one turn and print the answer
+akan code -i "<prompt>"         open the session with the prompt already sent
+--app <name>                    narrow the agent to one app
+--profile local|pod|review|web  what it may do (default local)
+--model <provider>/<id>         --thinking, --json, --rpc, --resume <id>
+```
+
+`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.
+
+## The rest of the commands
+
+`/help` prints all of this list · `/tools` what this session can call · `/agents` what a sub-agent may be and
+what one may spend · `/thinking` shows or folds the reasoning · `/abort` stops the running turn · `/quit`.

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

@@ -0,0 +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."
+---
+
+# Akan debug
+
+## 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
+process of the app in arrival order, including the dev host's own build output, which reaches no other
+file. The previous session is kept beside it as `dev.prev.log`.
+
+Read that file. Do not ask for a paste of the terminal: the full-screen view repaints one frame in place, so
+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.
+
+## Which loop you are in
+
+- **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.
+
+If a dev server is already running for the app, do **not** start another. If it looks wedged, surface the
+log tail in your answer rather than killing it.
+
+## Reading a log line
+
+Every `Logger` call carries `traceId`, `endpoint` and `origin` alongside the message, so one request's lines
+share a trace — `akan logs <app> --trace <id>` pulls just that request. The level ladder is
+`trace verbose debug info warn error`; `.log()` is deprecated and emits at `info`, which is why a call that
+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.

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

@@ -0,0 +1,50 @@
+---
+name: akan-deps
+description: "Fix an import, dependency, or barrel problem in an Akan workspace — barrels are generated, and a third-party package may not be imported from most files."
+---
+
+# Akan imports, deps and barrels
+
+## Barrels are generated
+
+Every `index.ts` under `ui/`, `webkit/`, `srvkit/`, `common/`, `plugin/` and `lib/**` is scanner output, as
+are `cnst.ts`, `db.ts`, `dict.ts`, `sig.ts`, `srv.ts`, `st.ts`, `useClient.ts`, `useServer.ts`, `client.ts`
+and `server.ts`. Do not hand-edit them and do not rely on their exact contents.
+
+**If an import "cannot be found" but the file exists, the barrel is stale** — run `akan sync <app-or-lib>`,
+or `repair_generated`. A `ui/<Folder>/index.tsx` that builds a namespace is hand-written source; the
+distinguishing test is that a generated barrel contains nothing but `export * from "./X";` lines.
+
+## Where a dependency is declared
+
+Add the package to the `package.json` of the app or lib that imports it —
+`apps/<app>/package.json` or `libs/<lib>/package.json` — then `bun install` from the repo root.
+
+## A third-party package may not be imported from most files
+
+`no-import-external-library.grit` refuses a third-party import from `page/**`, from any barrel, and from any
+`*.{constant,dictionary,document,service,signal,store}.ts` or `*.{Template,Unit,Util,View,Zone}.tsx`.
+Re-export the symbol through a lib first. The one-line re-export shims in a lib's `common/`, `webkit/` and
+`ui/` exist for exactly this — they are load-bearing, not cruft.
+
+## Two more import rules the build enforces
+
+- **No deep import past a barrel** (`no-deep-internal-import.grit`). Cross-module constant references such as
+  `../map/map.constant` are the sanctioned exception.
+- **No import across the client/server boundary.** A client file may not import a `*.document.ts` /
+  `*.dictionary.ts` / `*.service.ts` / `*.signal.ts`, `srvkit/`, a package `server` entrypoint, or the `db` /
+  `srv` / `sig` / `dict` / `option` / `useServer` barrels. A server file may not import a `*.store.ts`, a
+  module component, `ui/`, `webkit/`, a package `client` entrypoint, or `st` / `store` / `useClient`. Shared
+  files — `common/` and `*.constant.ts` — are held to **both**. `import type` is erased and stays legal in
+  every direction; a mixed value-and-type import is not exempt.
+
+## Aliases
+
+`akanjs/*` for framework facets, `@apps/*`, `@libs/*`, `@contract/*`. In `.tsx`, one flat named import from
+the package client path — `import { cnst, fetch, st, usePage } from "@apps/<app>/client"` — never a relative
+`../` import. In backend `.ts`, namespace the generated barrels: `import * as cnst from "../cnst"`.
+
+## 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.

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

@@ -0,0 +1,39 @@
+---
+name: akan-err
+description: "Throw errors the Akan way — a typed Err with a dictionary key, never a bare throw new Error. Lint-enforced."
+---
+
+# throw → Err
+
+Domain code throws `new Err("<module>.error.<key>")` and registers the key as `[en, ko]` in that module's
+dictionary `.error({})`. `throw new Error(...)` fails the build (`no-throw-raw-error.grit`).
+
+## Getting the import side right
+
+This is the common failure. Import `Err` from the source matching the **runtime side of the file**:
+
+- server code: `import { Err } from "../dict"`
+- UI: `from "@libs/<lib>/client"` or `from "@apps/<app>/client"`
+
+## Where the rule does not apply
+
+The lint rule exempts tests, `*.constant.ts`, `common/**`, and `env/**`. The last two have **no legal `Err`
+import path at all**, so keep throwing code out of them entirely rather than reaching for a workaround.
+
+## Where each error belongs
+
+- a state-machine precondition → `document.ts`
+- a cross-document rule → `service.ts`
+- request-level policy → a guard in `signal.ts`
+
+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`.
+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 })`
+restores the remote `Err` with its class, key and data. Rethrow it as-is — wrapping it in a `new Error`
+discards what the endpoint chose to say, and a bare `Error` is generalized to "Internal Server Error" on the
+way out.
+
+Korean `.error()` messages end in `다.`.

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

@@ -0,0 +1,45 @@
+---
+name: akan-module
+description: "Add or change an Akan database module: the constant→dictionary→document→service→signal→store→UI flow and which layer owns what."
+---
+
+# Akan module flow
+
+Creating a **new** module? Do not hand-write these files — scaffold with `create-module` first (the
+`akan-scaffold` skill), then fill in the layers below.
+
+A stored model flows through layers, one file each under `lib/<model>/`:
+
+`constant → dictionary → document → service → signal → store → UI`
+
+| file | owns |
+| --- | --- |
+| `<model>.constant.ts` | the five classes, in order: `XInput → XObject → LightX → X → XInsight`. Write `XInsight` even when empty. |
+| `<model>.dictionary.ts` | `[en, ko]` labels and the `Err` keys, in the fixed chain with empty stages still written. |
+| `<model>.document.ts` | `XFilter → X → XModel`. Chain methods validate, mutate, `return this`, and never `save()`. |
+| `<model>.service.ts` | load → chain → `return await ….save()`. Side effects go in `_preUpdate` / `_postCreate`. |
+| `<model>.signal.ts` | `XInternal → XSlice → XEndpoint`, all three declared even when empty. |
+| `<model>.store.ts` | only what `store()` does not already generate — see `akan-store`. |
+| `<Model>.*.tsx` | rendering. `Template` / `Zone` / `Util` are client, `Unit` / `View` are server. |
+
+## The rule most often missed
+
+**Display and predicate logic belongs on `Light<Model>`** — `isNew()`, `canWrite(user?)`, `formatTimes()`.
+The Light class is the one both server and client hold, so shared logic lives there instead of in a util
+module. Collection-level helpers go `static` on the full model.
+
+## Rules
+
+- New module ⇒ `create-module`. New field / action / list on an existing one ⇒ `add-field` /
+  `add-mutation` / `add-slice`. Hand-writing is the fallback, not the default.
+- A module is for data that must be **stored**. Static page content is a page.
+- Keep business decisions in constant, document and service; API exposure in signal; client coordination in
+  store; rendering in UI.
+- Never hand-edit a generated registry file — `cnst.ts`, `db.ts`, `dict.ts`, `option.ts`, `sig.ts`, `srv.ts`,
+  `st.ts`, `useClient.ts`, `useServer.ts`, and every `index.ts` barrel. They are scanner output; run
+  `akan sync <app>` or `repair_generated`.
+- Read the module's `<module>.abstract.md` before changing it, and update it when an invariant or workflow
+  changes — not for formatting.
+
+Deeper detail per layer is a `get_guideline` call away: `moduleOverview`, `modelConstant`, `modelDocument`,
+`modelService`, `modelSignal`, `modelStore`, `modelDictionary`.