@akanjs/devkit 3.0.0-beta.14 → 3.0.0-beta.15

package/codeAgent/feedback/VerifyFeedback.ts

@@ -0,0 +1,46 @@
+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;
+}
+
+/**
+ * Runs the validation chain over whatever a turn changed and feeds the failures back.
+ *
+ * The model has a verification tool and the observed failure is that it finishes without calling it — so this
+ * is not a second tool but a hook. Detection reads git rather than tool events, because an edit made through
+ * `bash` produces no write tool call and is exactly the kind a model forgets to verify.
+ */
+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");
+    // Leaving the apt lists behind adds ~40MB to every layer of every image that takes this step.
+    expect(step).toContain("rm -rf /var/lib/apt/lists/*");
+  });
+});

package/codeAgent/index.ts

@@ -0,0 +1,43 @@
+/**
+ * The akan coding agent: the engine wrapper, the tools it is given, and the feedback that reopens a turn.
+ *
+ * Importing this barrel loads the engine, which costs ~122MiB resident. A host that only needs the cheap
+ * pieces — the model reference, the stream printer, the sub-agent kinds — reaches for the owning module
+ * instead (`@akanjs/devkit/codeAgent/agent/akanCodeModel`), the same way `@akanjs/devkit` itself asks to be
+ * used. `agent/consoleToStderr` is deliberately absent: it is a side-effect module that takes over
+ * `globalThis.console`, and it has to be the first import of an RPC entry rather than a re-export of this one.
+ */
+
+export * from "./agent/AkanAuthStorageBackend";
+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-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`, `moduleCodegen`, `modelConstant`,
+`modelDocument`, `modelService`, `modelSignal`, `modelStore`, `modelDictionary`.

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

@@ -0,0 +1,76 @@
+---
+name: akan-scaffold
+description: "Create a new module, scalar, field, mutation, slice, or UI surface — scaffold it with the akan workflow tools (plan_workflow / apply_workflow) instead of writing the files by hand."
+---
+
+# Akan scaffolding workflows (use these BEFORE writing files)
+
+Akan generates the conventional file set for you. Creating those files by hand skips the conventions, the
+generated-barrel sync, and the validation chain.
+
+## Step 0 — decide WHAT gets a module, before any tool call
+
+List the things the request says must be **stored in the database**. Those, and only those, become modules.
+Everything else is pages, sections, and props.
+
+- A page or section whose content you can write as static JSX or props is not an entity. "A self-intro page
+  with two detail pages" is pages only — no `profile` module.
+- Never invent a supporting entity (profile, category, tag, author, like) to round out a design. If one looks
+  genuinely necessary, say so in your reply and let the user decide.
+- "… plus a comment zone that saves to a database" is exactly one new module: `comment`.
+- Check what exists first (`list_modules`) and extend it when it already fits — `add-field` / `add-slice` /
+  `create-ui` beat a whole new module.
+- Build the entire request, at the smallest structure that satisfies it.
+
+Then pick the workflow that matches the intent:
+
+| The user wants… | workflow |
+| --- | --- |
+| a new database-backed entity (comment, post, todo, product …) | `create-module` |
+| a reusable embedded value object | `create-scalar` |
+| a new field on an existing module | `add-field` |
+| a new field with a closed set of values | `add-enum-field` |
+| a new state-changing action | `add-mutation` |
+| a filtered list, tab, or reusable query | `add-slice` |
+| a View / Unit / Template / Zone / Util for an existing module | `create-ui` |
+
+## The chain
+
+Each result names the next call in `next.tool`. Follow it; do not improvise.
+
+1. `plan_workflow({ workflow: "create-module", inputs: { app: "<app>", module: "comment" } })` — read-only.
+   Returns `planPath` and `next.tool=apply_workflow`. (`list_workflows` / `explain_workflow` give the names
+   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.
+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.
+5. Now fill in: real fields in the constant, invariants in document and service, non-CRUD API in the signal,
+   extra state in the store, rendering in the UI. Filling in a scaffold is the job; creating one by hand is
+   not.
+
+## Rules
+
+- One run per unit of structure: two new entities are two `create-module` runs.
+- `requiresApproval: true` on a plan is a review signal for you, not a permission gate — read
+  `predictedChanges`, then apply.
+- 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`.
+
+## Worked example — "an intro page, two detail pages, and a comment zone with a database"
+
+0. What must be stored? Only the comments. One module, `comment`. The three pages are static content.
+1. `plan_workflow({ workflow: "create-module", inputs: { app: "<app>", module: "comment" } })`
+2. `apply_workflow({ planPath })` — `lib/comment/*` exists, barrels synced.
+3. Read the scaffolded files. Edit `comment.constant.ts` for the real shape. The store's CRUD already exists;
+   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.

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

@@ -0,0 +1,52 @@
+---
+name: akan-scalar
+description: "Create an embedded value object (scalar) under lib/__scalar/, or add a relation field to another model — including which cascade direction is which."
+---
+
+# Akan scalars and relations
+
+## Scalars
+
+A scalar is an embedded value object with no collection of its own. It lives in `lib/__scalar/<name>/`, is
+composed into models with `scalar(...)`, and its dictionary is a `scalarDictionary`. Create one with the
+`create-scalar` workflow; its UI surface is limited to `<Scalar>.Template.tsx` and `<Scalar>.Unit.tsx`.
+
+## Relations
+
+A reference to another model is `field(Model)`, or `field([Model])` for many. Files and images are a
+relation to the `File` model — `image: field(File).optional()` — never an `Upload` field; `Upload` is a
+signal-body primitive only. The store then generates `upload<Field>On<Model>(fileList)` for you.
+
+**Hydrated vs raw.** A server query returns a hydrated `cnst.<Model>` instance with `set` / `save` /
+`refresh`. A client `fetch` result is raw plain data with the functions stripped. Code that works in a
+service and fails in a store is usually this.
+
+**A model's `Date` fields are prototype accessors, not own properties.** `user.createdAt` is a `Dayjs` built
+on first read, so `Object.keys(user)` and `{ ...user }` do **not** include it, while `"createdAt" in user`,
+`JSON.stringify(user)` and `plainFieldsOf(user)` do. To copy a model write `new cnst.X().set(user)`, never a
+spread.
+
+## Cascade — the value names the direction, and getting it wrong loses data
+
+The two actions sit on the same field shape, so `cascade` never means "related". It means one of exactly
+these:
+
+- `removeRef` — *when I am removed, remove what this field points at.* Declared on the relation the owner
+  holds: `image: field(File, { cascade: "removeRef" })`.
+- `removeWith` — *when what this field points at is removed, remove me.* Declared on the child's own
+  reference to its owner, so the owner never learns about its children.
+
+Nothing checks whether another document still references the same target, and `File` in particular is
+deduped by `origin`, so two parents can share one row. Removal is soft, but the storage delete a
+`_postRemove` performs is not — a cascade is not restorable.
+
+Query-level removes fire no hooks and therefore no cascade: `removeManyByQuery`, the generated
+`remove<Filter>`, and the facade's `removeById`. Remove one document at a time when it cascades.
+
+## Field types
+
+Import `Int`, `Float`, `ID`, `Any`, `Binary`, `Upload`, `enumOf` and `dayjs` from `akanjs/base`. `String`,
+`Boolean` and `Date` are the globals. **`Number` is not a field type** — use `Int` or `Float`. There is no
+JSON scalar; use `Any`. `Binary` is wire bytes and is never a model field.
+
+Full detail: `get_guideline` with `scalarModule`, `scalarConstant`, `fieldRule`, or `queryRule`.

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

@@ -0,0 +1,34 @@
+---
+name: akan-service
+description: "Add a service module — behaviour not centred on one stored model — under lib/_<service>/, and keep its abstract current."
+---
+
+# Akan service modules
+
+Behaviour that is not centred on a single stored model lives in a **service module**: the folder is
+`lib/_<service>/` and its abstract file is `<service>.abstract.md` — the folder carries the underscore, the
+abstract drops it. Its UI surface is limited to `<Service>.Util.tsx` and `<Service>.Zone.tsx`, and its
+dictionary is a `serviceDictionary`.
+
+## Rules
+
+- Read the module's `*.abstract.md` **before** changing it — it states the invariants the code cannot show.
+  Update it when an invariant, workflow, or public behaviour changes; not for formatting or imports.
+- Keep the public surface in the signal layer and the decisions in the service.
+- Service methods stay a few lines: load → chain → `return await ….save()`. Write `return await` explicitly
+  in tail position. Side effects belong in `_preUpdate` / `_postCreate`, not inline. Fire-and-forget is
+  explicitly `void`-ed.
+- Return `null` / `false` for "not allowed" or "not found" and let the signal decide whether that is an
+  error.
+
+## Reaching other things
+
+Inside a service, in preference order: `service<srv.XService>()` for another module's service,
+`plug(AdapterClass)` for an adapter, `use<T>()` only for an `option.ts`-registered legacy singleton, and
+`env(...)` for config. Injection resolves by field name — a field named `<refName>Service` finds the service
+registered under `<refName>`, and the `Service` suffix is required.
+
+An external API or piece of infrastructure is an `adapt()` class in `srvkit/`, injected with `plug`. It
+self-registers, so do **not** add it to `lib/option.ts`.
+
+Full detail: `get_guideline` with `modelService`.

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

@@ -0,0 +1,63 @@
+---
+name: akan-store
+description: "Fill in a module store, or call module data and actions from UI — what store() already generates (CRUD, form setters, slice actions) and what belongs in your subclass."
+---
+
+# Akan store: what is already generated
+
+`class CommentStore extends store(sig.comment, () => ({ /* extra state */ })) { /* extra actions */ }`
+gives you the whole CRUD and form surface for free. **Redeclaring any of it is a typecheck error
+("already exists"), and the fix is to delete your version and call the generated one** — never rename around
+it, never cast, never reimplement.
+
+For a model `comment` (`<Slice>` is a signal slice suffix, e.g. `InPublic`):
+
+## Generated actions — `st.do.*`
+
+- write: `createComment(input)`, `updateComment(id, input)`, `removeComment(id)`
+- form: `newComment()`, `editComment(model)`, `writeOnComment(path, value)`, `set<Field>OnComment(value)`,
+  `add<Field>OnComment(value)` / `sub<Field>OnComment(idx)` for arrays, `upload<Field>OnComment(fileList)`
+  for file fields, `checkCommentSubmitable()`, `submitComment()`, `createCommentInForm()`,
+  `updateCommentInForm()`
+- single: `viewComment(model)`, `mergeComment(model, data)`, `setComment(...models)`, `resetComment()`
+- per slice: `initComment<Slice>(...args)`, `refreshComment<Slice>()`, `selectComment<Slice>(model)`,
+  `setPageOfComment<Slice>(page)`, `loadMoreOfComment<Slice>()`, `setLimitOfComment<Slice>(limit)`,
+  `setQueryArgsOfComment<Slice>(...)`, `setSortOfComment<Slice>(sort)`
+
+## Generated state — `st.use.*`
+
+`comment`, `commentLoading`, `commentForm`, `commentFormLoading`, `commentSubmit`, `commentModal`,
+`commentViewAt`, `commentOperation`; per slice `commentList<Slice>`, `commentListLoading<Slice>`,
+`commentInitList<Slice>`, `commentSelection<Slice>`, `commentInsight<Slice>`, `pageOfComment<Slice>`,
+`lastPageOfComment<Slice>`, `hasMoreOfComment<Slice>`, `limitOfComment<Slice>`, `sortOfComment<Slice>`.
+
+## What your subclass is for
+
+Only what the generated set does not cover: extra client state, a multi-step or cross-model workflow, and
+calls to the non-CRUD endpoints you added in the signal. Each is an `async` method using `this.set(...)` /
+`this.get()` / `this.pick(...)`.
+
+A store that needs none of this stays empty. `store(sig.comment, () => ({}))` with an empty body is the
+correct, complete result — an empty store is not an unfinished one.
+
+## Two rules the linter enforces
+
+- **An action returns nothing.** Every method dispatches through `st.do.<action>()` and is typed `void`, so a
+  returned value is unreachable. Write it into state with `this.set({ … })`.
+- **Never `import type { RootStore } from "../st"`** — it crashes `akan build` with a Bun SSR segfault.
+
+## From UI
+
+Read with `st.use.commentListInPublic()`, act with `st.do.createComment(input)` / `st.do.submitComment()`.
+Do not wrap a generated action in a store method just to rename it.
+
+**Pass a form setter by reference**: `onChange={st.do.setTypeOnComment}`, never
+`onChange={(v) => st.do.setTypeOnComment(v)}`. The two run identically, but the arrow is an anonymous
+closure, so the control emits no `data-akan-action` and publishes no agent tool for the field —
+`no-unpublished-form-setter.grit` fails the build on it.
+
+## Signal side
+
+The scaffolded `slice(…, { guards: { root, get, cru } })` already exposes get / list / create / update /
+remove. Add a query or mutation only for behaviour beyond CRUD, and give it its own `guards` array — a
+custom endpoint never inherits the slice's.

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

@@ -0,0 +1,63 @@
+---
+name: akan-ui
+description: "Build Akan pages and components: the server-by-default rule, the Unit/View vs Template/Zone/Util split, forms, and what never to hand-roll."
+---
+
+# Akan UI
+
+A new View / Unit / Template / Zone / Util for an existing module comes from the `create-ui` workflow (the
+`akan-scaffold` skill). Edit the scaffolded component instead of authoring one from scratch.
+
+## The boundary is mechanical, not a judgement call
+
+| role | side | directive |
+| --- | --- | --- |
+| `<Model>.Unit.tsx`, `<Model>.View.tsx` | server | never `"use client"` |
+| `<Model>.Template.tsx`, `<Model>.Zone.tsx`, `<Model>.Util.tsx` | client | `"use client"` on line 1 |
+| `page/**` | server | never |
+
+**Server is the default and `"use client"` is a cost you justify per component.** A component earns the
+directive only by using a hook, a JSX event handler, the store, a browser global, or a client-only package.
+Rendering markup, reading a param, calling `l()`, and mapping over data are all server work. Measure with
+`akan quality ssr`; treat 50% server share as the floor and a falling share as a regression.
+
+Four moves that keep markup on the server: wrap the interaction and render `children` untouched; split a
+compound component so only the provider holds state; fetch in the route and pass the result into a `Zone` as
+an `init` prop; push the boundary down to the leaf that needs it.
+
+## Never hand-roll these
+
+- loading / empty / list states → `Load.Units` / `Load.View` / `Load.Edit` with `renderItem`, `renderList`,
+  `renderView`, `renderEmpty`; `<Empty />` for a bare placeholder; `Model.New` / `Model.Edit` /
+  `Model.SureToRemove` for CRUD modals.
+- a mount-time fetch → the route calls `fetch.init<Model><Slice>(…)` before the first byte. A
+  `useEffect(…, [])` that loads data is flagged by `akan quality ssr`, and `fetch.init*` from a client file
+  fails lint outright.
+- a model field input → `Field.*`, never a bare `<input>`.
+- a mode switch → `Tab`, not a `useState`.
+
+## Component shape
+
+`export const X = ({ … }: XProps) => { return (…); };` — arrow const, block body. Never `React.FC`, never
+`defaultProps`, never `PropsWithChildren`; children are `children: ReactNode`. Declare
+`interface XProps` directly above the component with `className?: string` first.
+
+Conditional render is `cond ? <X/> : null`. **Never `{cond && <X/>}`** — in a `className` context it renders
+the literal string `"false"`.
+
+## Classes
+
+Never hand-order Tailwind classes; the formatter sorts them and its output is correct. Stay inside the
+semantic token vocabulary — `bg-primary`, `text-foreground/70` — because a raw palette class (`bg-blue-500`),
+an arbitrary colour (`bg-[#3b82f6]`), a daisyUI legacy class, and a colour literal in `style={{…}}` all
+render no CSS and fail lint. Reach for `cn` only for a conditional or to merge an incoming `className`, and
+merge the caller last.
+
+## Forms
+
+Store-driven end to end: `value={xForm.field}` with `onChange={st.do.setFieldOnX}`, **the setter passed by
+reference**. An inline arrow silently drops the control's agent annotation and fails
+`no-unpublished-form-setter.grit`. Nested rows use `st.do.writeOnX("payments.3.name", v)`.
+
+Full detail: `get_guideline` with `ssrRule`, `componentRule`, `cssRule`, `recipeRule`, or the per-role
+`modelUnit` / `modelView` / `modelZone` / `modelTemplate` / `modelUtil`.