@akanjs/cli 3.0.0-beta.2 → 3.0.0-beta.21

package/{recipeScanner-fpagtgc1.js → recipeScanner-4b69ybe0.js}

@@ -3,7 +3,7 @@ import {
   collectRecipeSources2,
   scanRecipes2,
   findInlineRecipeDuplicates2
-} from "./index-by5gpp8x.js";
+} from "./index-hj6w4ka1.js";
 export {
   collectRecipeSources2 as collectRecipeSources,
   findInlineRecipeDuplicates2 as findInlineRecipeDuplicates,

package/{repair.command-bqsjptsj.js → repair.command-d3x1javq.js}

@@ -3,34 +3,21 @@ import {
   Workspace,
   script,
   command
-} from "./index-mak3cd28.js";
-import"./index-q0y2jq9j.js";
-import"./index-2tv3fdx4.js";
-import"./index-6wwzs1bc.js";
-import"./index-by5gpp8x.js";
-import"./index-gyd220p2.js";
-import"./index-ktb5njgy.js";
+} from "./index-rmcw8yc8.js";
+import"./index-5b6tavv3.js";
+import"./index-ga6hygxr.js";
+import"./index-hj6w4ka1.js";
+import"./index-yy4s1j72.js";
+import"./index-9629w7ns.js";
 import {
   RepairRunner
-} from "./index-fz5q3gd7.js";
+} from "./index-ya5qbmyg.js";
 
 // pkgs/@akanjs/cli/repair/repair.script.ts
 import { Logger } from "akanjs/common";
 class RepairScript extends script("repair", [RepairRunner]) {
-  async repair(kind, {
-    workspace,
-    app = null,
-    module = null,
-    target = null,
-    format = "markdown"
-  }) {
-    Logger.rawLog(await this.repairRunner.repair(kind, {
-      workspace,
-      app,
-      module,
-      target,
-      format
-    }));
+  async repair(kind, options) {
+    Logger.rawLog(await this.repairRunner.repair(kind, options));
   }
 }
 
@@ -39,12 +26,7 @@ class RepairCommand extends command("repair", [RepairScript], ({ public: target
   repair: target({ desc: "Run a narrow Akan repair command and return a structured report" }).arg("kind", String, {
     desc: "generated, format, imports, dictionary, or module-shape",
     enum: ["generated", "format", "imports", "dictionary", "module-shape"]
-  }).with(Workspace).option("format", String, {
-    desc: "output format",
-    flag: "o",
-    default: "markdown",
-    enum: ["markdown", "json"]
-  }).option("app", String, {
+  }).with(Workspace).option("format", String, { desc: "output format", flag: "o", default: "markdown", enum: ["markdown", "json"] }).option("app", String, {
     desc: "target app or library for generated/dictionary/module-shape repair",
     nullable: true
   }).option("module", String, { desc: "target module for dictionary/module-shape repair", nullable: true }).option("target", String, {
@@ -52,13 +34,7 @@ class RepairCommand extends command("repair", [RepairScript], ({ public: target
     desc: "target app, library, or package for format/imports repair",
     nullable: true
   }).exec(async function(kind, workspace, format, app, module, targetName) {
-    await this.repairScript.repair(kind, {
-      workspace,
-      format,
-      app,
-      module,
-      target: targetName
-    });
+    await this.repairScript.repair(kind, { workspace, format, app, module, target: targetName });
   })
 })) {
 }

package/{routeSourceValidator-apyqw7wk.js → routeSourceValidator-7ycnfz0e.js}

@@ -57,12 +57,6 @@ class RouteSourceValidator {
     if (exported.has("head") && exported.has("generateHead")) {
       throw new Error(`[route-convention] head and generateHead cannot both be exported in ${filePath}`);
     }
-    if (!options.rootLayout && (exported.has("head") || exported.has("generateHead")) && (exported.has("metadata") || exported.has("generateMetadata"))) {
-      throw new Error(`[route-convention] head/generateHead and metadata/generateMetadata cannot both be exported in ${filePath}`);
-    }
-    if (exported.has("metadata") && exported.has("generateMetadata")) {
-      throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${filePath}`);
-    }
     const chain = RouteSourceValidator.#readChain(sourceFile, filePath);
     if (!chain)
       return { devOnly: RouteSourceValidator.#readDevOnly(sourceFile, filePath) };

package/{scalar.command-6k1vhe9s.js → scalar.command-7ezrac2b.js}

@@ -2,25 +2,22 @@
 import {
   Sys,
   command
-} from "./index-mak3cd28.js";
-import"./index-q0y2jq9j.js";
-import"./index-2tv3fdx4.js";
-import"./index-6wwzs1bc.js";
+} from "./index-rmcw8yc8.js";
+import"./index-5b6tavv3.js";
+import"./index-ga6hygxr.js";
 import {
   renderPrimitiveReport
-} from "./index-gyd220p2.js";
-import"./index-kn1h7p1x.js";
-import"./index-h7yw2z9n.js";
+} from "./index-yy4s1j72.js";
 import {
   ScalarScript
-} from "./index-rwg2aa4f.js";
+} from "./index-pp54p5zk.js";
 
 // pkgs/@akanjs/cli/scalar/scalar.command.ts
 import { Logger, lowerlize } from "akanjs/common";
 class ScalarCommand extends command("scalar", [ScalarScript], ({ public: target }) => ({
-  createScalar: target({ desc: "Create a new scalar type (simple data model without DB)" }).arg("scalarName", String, { desc: "name of scalar" }).with(Sys).option("ai", Boolean, { default: false, desc: "use ai to create scalar" }).option("format", String, { flag: "o", desc: "output format", default: "markdown", enum: ["markdown", "json"] }).exec(async function(scalarName, sys, ai, format) {
+  createScalar: target({ desc: "Create a new scalar type (simple data model without DB)" }).arg("scalarName", String, { desc: "name of scalar" }).with(Sys).option("format", String, { flag: "o", desc: "output format", default: "markdown", enum: ["markdown", "json"] }).exec(async function(scalarName, sys, format) {
     const name = lowerlize(scalarName.replace(/ /g, ""));
-    const report = ai ? await this.scalarScript.createScalarWithAi(sys, name) : await this.scalarScript.createScalar(sys, name);
+    const report = await this.scalarScript.createScalar(sys, name);
     Logger.rawLog(renderPrimitiveReport(report, format));
   }),
   removeScalar: target({ desc: "Remove a scalar type from an app or library" }).arg("scalarName", String, { desc: "name of scalar" }).with(Sys).exec(async function(scalarName, sys) {

package/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/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/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/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/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`.

package/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/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/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`.