@akanjs/cli 3.0.0-beta.13 → 3.0.0-beta.15

package/{library.command-1f9h2ex6.js → library.command-n89re6cx.js}

@@ -3,13 +3,13 @@ import {
   Lib,
   Workspace,
   command
-} from "./index-b3ae16mg.js";
+} from "./index-gca9y01h.js";
 import"./index-q0y2jq9j.js";
-import"./index-5nyznra1.js";
+import"./index-p1j0cyvd.js";
 import"./index-6wwzs1bc.js";
 import {
   LibraryScript
-} from "./index-1nwxbr2y.js";
+} from "./index-ea1smknd.js";
 
 // pkgs/@akanjs/cli/library/library.command.ts
 class LibraryCommand extends command("library", [LibraryScript], ({ public: target }) => ({

package/{localRegistry.command-w6w35j4r.js → localRegistry.command-1mmnegph.js}

@@ -4,28 +4,28 @@ import {
   runner,
   script,
   command
-} from "./index-b3ae16mg.js";
+} from "./index-gca9y01h.js";
 import"./index-q0y2jq9j.js";
 import {
   PkgExecutor
-} from "./index-5nyznra1.js";
+} from "./index-p1j0cyvd.js";
 import"./index-6wwzs1bc.js";
 import {
   ApplicationScript
-} from "./index-cnzm1wn5.js";
-import"./index-1nwxbr2y.js";
+} from "./index-chp5gqmm.js";
+import"./index-ea1smknd.js";
 import"./index-hwkygn9s.js";
-import"./index-649svkyt.js";
-import"./index-5tw8t1ts.js";
+import"./index-7md2g9vw.js";
+import"./index-myj01w9r.js";
 import {
   getNpmRegistryUrl,
   CloudRunner
-} from "./index-bz10w9t2.js";
+} from "./index-0qvq9aeb.js";
 import"./index-kcxmv48c.js";
 import {
   PackageScript
-} from "./index-t8gvwcrx.js";
-import"./index-ys7dvdb3.js";
+} from "./index-va2je2qm.js";
+import"./index-84b080zh.js";
 
 // pkgs/@akanjs/cli/localRegistry/localRegistry.runner.ts
 import { mkdir, rm } from "fs/promises";

package/{module.command-8zkq0q9q.js → module.command-4m82zgfp.js}

@@ -3,27 +3,24 @@ import {
   Sys,
   Module,
   command
-} from "./index-b3ae16mg.js";
+} from "./index-gca9y01h.js";
 import"./index-q0y2jq9j.js";
-import"./index-5nyznra1.js";
+import"./index-p1j0cyvd.js";
 import"./index-6wwzs1bc.js";
 import {
   renderPrimitiveReport
-} from "./index-jwjaf9fy.js";
-import"./index-649svkyt.js";
-import"./index-5tw8t1ts.js";
+} from "./index-1p146w4s.js";
+import"./index-f4gpcp98.js";
 import {
   ModuleScript
-} from "./index-kpnp2e10.js";
-import"./index-sh88vtye.js";
-import"./index-h7yw2z9n.js";
+} from "./index-v156f836.js";
 
 // pkgs/@akanjs/cli/module/module.command.ts
 import { Logger, lowerlize } from "akanjs/common";
 class ModuleCommand extends command("module", [ModuleScript], ({ public: target }) => ({
-  createModule: target({ desc: "Create a new domain module (constant, service, signal, store, UI)" }).arg("moduleName", String, { desc: "name of module" }).with(Sys).option("page", Boolean, { desc: "create page", default: false }).option("ai", Boolean, { desc: "use ai to create module constant and dictionary", default: false }).option("format", String, { flag: "o", desc: "output format", default: "markdown", enum: ["markdown", "json"] }).exec(async function(moduleName, sys, page, ai, format) {
+  createModule: target({ desc: "Create a new domain module (constant, service, signal, store, UI)" }).arg("moduleName", String, { desc: "name of module" }).with(Sys).option("page", Boolean, { desc: "create page", default: false }).option("format", String, { flag: "o", desc: "output format", default: "markdown", enum: ["markdown", "json"] }).exec(async function(moduleName, sys, page, format) {
     const name = lowerlize(moduleName.replace(/ /g, ""));
-    const report = ai ? await this.moduleScript.createModule(sys, name, { page }) : await this.moduleScript.createModuleTemplate(sys, name, { page });
+    const report = await this.moduleScript.createModuleTemplate(sys, name, { page });
     Logger.rawLog(renderPrimitiveReport(report, format));
   }),
   removeModule: target({ desc: "Remove a module from an app or library" }).with(Module).exec(async function(module) {

package/{package.command-y2rh4np7.js → package.command-9dv0p6zq.js}

@@ -3,14 +3,14 @@ import {
   Pkg,
   Workspace,
   command
-} from "./index-b3ae16mg.js";
+} from "./index-gca9y01h.js";
 import"./index-q0y2jq9j.js";
-import"./index-5nyznra1.js";
+import"./index-p1j0cyvd.js";
 import"./index-6wwzs1bc.js";
 import"./index-kcxmv48c.js";
 import {
   PackageScript
-} from "./index-t8gvwcrx.js";
+} from "./index-va2je2qm.js";
 
 // pkgs/@akanjs/cli/package/package.command.ts
 class PackageCommand extends command("package", [PackageScript], ({ public: target }) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "3.0.0-beta.13",
+  "version": "3.0.0-beta.15",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -24,16 +24,18 @@
       "import": "./index.js",
       "default": "./index.js"
     },
+    "./code": {
+      "import": "./akanCode.js",
+      "default": "./akanCode.js"
+    },
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@earendil-works/pi-coding-agent": "0.80.6",
     "@inquirer/prompts": "^8.4.3",
-    "@langchain/core": "^1.1.47",
-    "@langchain/deepseek": "^1.0.26",
-    "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-beta.13",
+    "akanjs": "3.0.0-beta.15",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",
@@ -45,9 +47,11 @@
     "qrcode": "^1.5.4",
     "react": "19.2.7",
     "ssh2": "^1.17.0",
+    "string-width": "^8.2.1",
     "subset-font": "^2.5.0",
     "tailwind-scrollbar": "^4.0.2",
     "tailwindcss": "^4.3.0",
+    "typebox": "1.1.38",
     "typescript": "^6.0.3"
   },
   "devDependencies": {},

package/{page.command-e5h29fyt.js → page.command-q86b0m0z.js}

@@ -3,13 +3,13 @@ import {
   App,
   Module,
   command
-} from "./index-b3ae16mg.js";
+} from "./index-gca9y01h.js";
 import"./index-q0y2jq9j.js";
-import"./index-5nyznra1.js";
+import"./index-p1j0cyvd.js";
 import"./index-6wwzs1bc.js";
 import {
   PageScript
-} from "./index-sh88vtye.js";
+} from "./index-f4gpcp98.js";
 
 // pkgs/@akanjs/cli/page/page.command.ts
 class PageCommand extends command("page", [PageScript], ({ public: target }) => ({

package/{primitive.command-qm7tybpn.js → primitive.command-kaneasq6.js}

@@ -2,21 +2,18 @@
 import {
   Workspace,
   command
-} from "./index-b3ae16mg.js";
+} from "./index-gca9y01h.js";
 import"./index-q0y2jq9j.js";
-import"./index-5nyznra1.js";
+import"./index-p1j0cyvd.js";
 import"./index-6wwzs1bc.js";
 import {
   renderPrimitiveReport
-} from "./index-jwjaf9fy.js";
-import"./index-649svkyt.js";
-import"./index-5tw8t1ts.js";
-import"./index-kpnp2e10.js";
-import"./index-sh88vtye.js";
-import"./index-h7yw2z9n.js";
+} from "./index-1p146w4s.js";
+import"./index-f4gpcp98.js";
+import"./index-v156f836.js";
 import {
   PrimitiveScript
-} from "./index-h3g1152j.js";
+} from "./index-d35a8vc0.js";
 
 // pkgs/@akanjs/cli/primitive/primitive.command.ts
 import { Logger } from "akanjs/common";

package/prompter-9mn3kp36.js

@@ -0,0 +1,8 @@
+// @bun
+import {
+  Prompter2
+} from "./index-twq9p2sp.js";
+import"./index-6wwzs1bc.js";
+export {
+  Prompter2 as Prompter
+};

package/{quality.command-5evdd263.js → quality.command-sgapx315.js}

@@ -4,17 +4,14 @@ import {
   runner,
   script,
   command
-} from "./index-b3ae16mg.js";
+} from "./index-gca9y01h.js";
 import"./index-q0y2jq9j.js";
 import {
   rootAllowedFiles,
   rootAllowedDirs,
   isAllowedLibFacetRootFile
-} from "./index-5nyznra1.js";
+} from "./index-p1j0cyvd.js";
 import"./index-6wwzs1bc.js";
-import {
-  AbstractDoc
-} from "./index-meh558jy.js";
 
 // pkgs/@akanjs/devkit/qualityScanner.ts
 import { createHash } from "crypto";
@@ -24,6 +21,69 @@ import { RESERVED_ROUTE_CONFIG_EXPORTS } from "akanjs/common";
 import ignore from "ignore";
 import ts3 from "typescript";
 
+// pkgs/@akanjs/devkit/abstractDoc.ts
+class AbstractDoc {
+  path;
+  content;
+  siblingFiles;
+  static suffix = ".abstract.md";
+  static maxLines = 300;
+  static compactMinLines = 40;
+  static #facetRoots = "{lib,ui,webkit,srvkit,common,plugin}";
+  static isAbstractPath(filePath) {
+    return filePath.endsWith(AbstractDoc.suffix);
+  }
+  static lineCountOf(content) {
+    return content.split(/\r?\n/).length;
+  }
+  static kindOf(filePath) {
+    const [root, folder, ...rest] = filePath.split("/");
+    if (root !== "lib" || !folder)
+      return "other";
+    if (folder === "__scalar")
+      return rest.length === 2 ? "scalar" : "other";
+    if (rest.length !== 1)
+      return "other";
+    return folder.startsWith("_") ? "service" : "domain";
+  }
+  static async findAll(sys, { module } = {}) {
+    const filePaths = (await sys.getAllFiles(`${AbstractDoc.#facetRoots}/**/*${AbstractDoc.suffix}`)).sort();
+    const docs = await Promise.all(filePaths.map((filePath) => AbstractDoc.read(sys, filePath)));
+    if (!module)
+      return docs;
+    return docs.filter((doc) => doc.moduleName === module || doc.folderName === module);
+  }
+  static async read(sys, filePath) {
+    const dirPath = filePath.split("/").slice(0, -1).join("/");
+    const [content, folderFiles] = await Promise.all([sys.readFile(filePath), sys.readdir(dirPath)]);
+    return new AbstractDoc(filePath, content, folderFiles.filter((fileName) => !AbstractDoc.isAbstractPath(fileName)));
+  }
+  constructor(path, content, siblingFiles) {
+    this.path = path;
+    this.content = content;
+    this.siblingFiles = siblingFiles;
+  }
+  get kind() {
+    return AbstractDoc.kindOf(this.path);
+  }
+  get folderName() {
+    return this.path.split("/").at(-2) ?? "";
+  }
+  get moduleName() {
+    return (this.path.split("/").at(-1) ?? "").slice(0, -AbstractDoc.suffix.length);
+  }
+  get lineCount() {
+    return AbstractDoc.lineCountOf(this.content);
+  }
+  canReplaceWith(candidate) {
+    const next = candidate.trim();
+    if (!next.startsWith("#"))
+      return false;
+    const lineCount = AbstractDoc.lineCountOf(next);
+    return lineCount >= 3 && lineCount < this.lineCount;
+  }
+}
+
 // pkgs/@akanjs/devkit/formSetterScanner.ts
 import ts from "typescript";
 

package/{repair.command-c2amvt74.js → repair.command-efc5gdbq.js}

@@ -3,16 +3,16 @@ import {
   Workspace,
   script,
   command
-} from "./index-b3ae16mg.js";
+} from "./index-gca9y01h.js";
 import"./index-q0y2jq9j.js";
-import"./index-5nyznra1.js";
+import"./index-p1j0cyvd.js";
 import"./index-6wwzs1bc.js";
 import"./index-by5gpp8x.js";
-import"./index-jwjaf9fy.js";
-import"./index-15r9a10e.js";
+import"./index-1p146w4s.js";
+import"./index-3dmebxnk.js";
 import {
   RepairRunner
-} from "./index-em4swemt.js";
+} from "./index-bchkysja.js";
 
 // pkgs/@akanjs/cli/repair/repair.script.ts
 import { Logger } from "akanjs/common";

package/{scalar.command-a1ewkmab.js → scalar.command-e2rpkhqy.js}

@@ -2,26 +2,23 @@
 import {
   Sys,
   command
-} from "./index-b3ae16mg.js";
+} from "./index-gca9y01h.js";
 import"./index-q0y2jq9j.js";
-import"./index-5nyznra1.js";
+import"./index-p1j0cyvd.js";
 import"./index-6wwzs1bc.js";
 import {
   renderPrimitiveReport
-} from "./index-jwjaf9fy.js";
-import"./index-649svkyt.js";
-import"./index-5tw8t1ts.js";
-import"./index-h7yw2z9n.js";
+} from "./index-1p146w4s.js";
 import {
   ScalarScript
-} from "./index-j1tajctp.js";
+} from "./index-v1y3cx0k.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-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`, `moduleCodegen`, `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.