@akanjs/cli 3.0.0-beta.17 → 3.0.0-beta.19

package/{primitive.command-7kpncmkk.js → primitive.command-ns1mptje.js}

@@ -2,18 +2,18 @@
 import {
   Workspace,
   command
-} from "./index-6na0sd2b.js";
+} from "./index-qdgzsnhg.js";
 import"./index-q0y2jq9j.js";
-import"./index-p4p9t45x.js";
+import"./index-crmeqnmf.js";
 import"./index-6wwzs1bc.js";
 import {
   renderPrimitiveReport
-} from "./index-qhtj9y6j.js";
-import"./index-qh7brn20.js";
-import"./index-xjc7gg65.js";
+} from "./index-2446k7b4.js";
+import"./index-22xtgmhn.js";
+import"./index-esk82rvk.js";
 import {
   PrimitiveScript
-} from "./index-te0y1c0m.js";
+} from "./index-zqgj2rt2.js";
 
 // pkgs/@akanjs/cli/primitive/primitive.command.ts
 import { Logger } from "akanjs/common";

package/{prompter-9mn3kp36.js → prompter-1f8d9pcc.js}

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

package/{quality.command-1ar94hrw.js → quality.command-e76k2q9k.js}

@@ -4,31 +4,32 @@ import {
   runner,
   script,
   command
-} from "./index-6na0sd2b.js";
+} from "./index-qdgzsnhg.js";
 import"./index-q0y2jq9j.js";
 import {
   rootAllowedFiles,
   rootAllowedDirs,
   isAllowedLibFacetRootFile
-} from "./index-p4p9t45x.js";
+} from "./index-crmeqnmf.js";
 import"./index-6wwzs1bc.js";
 
 // pkgs/@akanjs/devkit/qualityScanner.ts
 import { createHash } from "crypto";
 import { readdir, readFile, stat } from "fs/promises";
-import path from "path";
+import path2 from "path";
 import { RESERVED_ROUTE_CONFIG_EXPORTS } from "akanjs/common";
 import ignore from "ignore";
 import ts3 from "typescript";
 
 // pkgs/@akanjs/devkit/abstractDoc.ts
+import path from "path";
+
 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);
@@ -47,7 +48,7 @@ class AbstractDoc {
     return folder.startsWith("_") ? "service" : "domain";
   }
   static async findAll(sys, { module } = {}) {
-    const filePaths = (await sys.getAllFiles(`${AbstractDoc.#facetRoots}/**/*${AbstractDoc.suffix}`)).sort();
+    const filePaths = (await sys.getAllFiles(`${AbstractDoc.#facetRoots}/**/*${AbstractDoc.suffix}`)).map((filePath) => filePath.split(path.sep).join("/")).sort();
     const docs = await Promise.all(filePaths.map((filePath) => AbstractDoc.read(sys, filePath)));
     if (!module)
       return docs;
@@ -58,8 +59,8 @@ class AbstractDoc {
     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;
+  constructor(path2, content, siblingFiles) {
+    this.path = path2;
     this.content = content;
     this.siblingFiles = siblingFiles;
   }
@@ -551,7 +552,7 @@ var RULE_FIXES = {
   "akan.global.duplicate-exported-function-body": "Extract the shared implementation into a single exported helper and import it, instead of copying the body.",
   "akan.file.recommended-max-lines": "Split the file by responsibility \u2014 move Zones, Utils, or subcomponents into sibling files.",
   "akan.file.max-lines": "Break the file into smaller focused modules; keep one primary responsibility per file.",
-  "akan.file.abstract-max-lines": "Run `akan compact <app-or-lib>` to rewrite the abstract with the AI editor, keeping only the invariants and workflows the source files cannot show.",
+  "akan.file.abstract-max-lines": "Trim the abstract by hand to a title, one sentence naming what the module owns, a `## Rules` list of the invariants the source cannot show, and an optional workflow chain.",
   "akan.file.placeholder-export": "Remove the placeholder export; generated indexes should only re-export real modules.",
   "akan.file.bang-comment-in-client": "Rewrite the marker as `// FIXME:` or `// TODO:`. Keep the bang form for server, srvkit, and CLI files.",
   "akan.file.dictionary-stale-text": "Replace the scaffold text with real localized copy for this dictionary entry.",
@@ -609,7 +610,7 @@ class AkanQualityScanner {
     const ignoreFilter = ignore().add(await this.#readGitIgnore(workspaceRoot));
     const files = [];
     for (const targetRoot of ["apps", "libs"]) {
-      const absoluteTargetRoot = path.join(workspaceRoot, targetRoot);
+      const absoluteTargetRoot = path2.join(workspaceRoot, targetRoot);
       if (!await isDirectory(absoluteTargetRoot))
         continue;
       await this.#walkTargetFiles(workspaceRoot, absoluteTargetRoot, ignoreFilter, files);
@@ -617,7 +618,7 @@ class AkanQualityScanner {
     return files.sort();
   }
   async#readGitIgnore(workspaceRoot) {
-    const gitIgnorePath = path.join(workspaceRoot, ".gitignore");
+    const gitIgnorePath = path2.join(workspaceRoot, ".gitignore");
     if (!await Bun.file(gitIgnorePath).exists())
       return [];
     return (await readFile(gitIgnorePath, "utf8")).split(/\r?\n/);
@@ -625,8 +626,8 @@ class AkanQualityScanner {
   async#walkTargetFiles(workspaceRoot, currentPath, ignoreFilter, files) {
     const entries = await readdir(currentPath, { withFileTypes: true });
     for (const entry of entries) {
-      const absolutePath = path.join(currentPath, entry.name);
-      const relativePath = toPosix(path.relative(workspaceRoot, absolutePath));
+      const absolutePath = path2.join(currentPath, entry.name);
+      const relativePath = toPosix(path2.relative(workspaceRoot, absolutePath));
       if (shouldSkipPath(relativePath, entry.isDirectory(), ignoreFilter))
         continue;
       if (entry.isDirectory()) {
@@ -641,7 +642,7 @@ class AkanQualityScanner {
     }
   }
   async#readSourceFile(workspaceRoot, file) {
-    const absolutePath = path.join(workspaceRoot, file);
+    const absolutePath = path2.join(workspaceRoot, file);
     const content = await readFile(absolutePath, "utf8");
     return {
       file,
@@ -651,7 +652,7 @@ class AkanQualityScanner {
     };
   }
   async#readTextFile(workspaceRoot, file) {
-    return { file, content: await readFile(path.join(workspaceRoot, file), "utf8") };
+    return { file, content: await readFile(path2.join(workspaceRoot, file), "utf8") };
   }
   #scanGlobalQuality(sourceFiles) {
     const exportedFunctionLikes = sourceFiles.flatMap((sourceFile) => getExportedFunctionLikes(sourceFile));
@@ -776,7 +777,7 @@ class AkanQualityScanner {
     const suffix = CONVENTION_SUFFIXES.find((candidate) => sourceFile.file.endsWith(candidate));
     if (!suffix)
       return [];
-    const modelName = toPascalCase(path.basename(sourceFile.file, suffix));
+    const modelName = toPascalCase(path2.basename(sourceFile.file, suffix));
     const warnings = [];
     for (const declaration of getTopLevelDeclarations(sourceFile)) {
       if (isAllowedConventionDeclaration(suffix, modelName, declaration))
@@ -787,7 +788,7 @@ class AkanQualityScanner {
         severity: "warning",
         file: sourceFile.file,
         line: declaration.line,
-        message: `${path.basename(sourceFile.file)} should not declare top-level ${declaration.kind} "${declaration.name}". Allowed declarations: ${getConventionDescription(suffix, modelName)}.`
+        message: `${path2.basename(sourceFile.file)} should not declare top-level ${declaration.kind} "${declaration.name}". Allowed declarations: ${getConventionDescription(suffix, modelName)}.`
       });
     }
     return warnings;
@@ -1322,7 +1323,7 @@ function toPascalCase(value) {
   return value.replace(/(^|[-_./])([a-zA-Z0-9])/g, (_, __, char) => char.toUpperCase()).replace(/[-_./]/g, "");
 }
 function toPosix(value) {
-  return value.split(path.sep).join("/");
+  return value.split(path2.sep).join("/");
 }
 function groupBy(items, getKey) {
   const grouped = new Map;

package/{repair.command-n08t6j8p.js → repair.command-pkrsm3cw.js}

@@ -3,16 +3,16 @@ import {
   Workspace,
   script,
   command
-} from "./index-6na0sd2b.js";
+} from "./index-qdgzsnhg.js";
 import"./index-q0y2jq9j.js";
-import"./index-p4p9t45x.js";
+import"./index-crmeqnmf.js";
 import"./index-6wwzs1bc.js";
 import"./index-by5gpp8x.js";
-import"./index-qhtj9y6j.js";
-import"./index-v17gj504.js";
+import"./index-2446k7b4.js";
+import"./index-18zybgkc.js";
 import {
   RepairRunner
-} from "./index-4cvpzkq6.js";
+} from "./index-53176s7j.js";
 
 // pkgs/@akanjs/cli/repair/repair.script.ts
 import { Logger } from "akanjs/common";

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-mq8qfp4t.js → scalar.command-0cpt3fc8.js}

@@ -2,16 +2,16 @@
 import {
   Sys,
   command
-} from "./index-6na0sd2b.js";
+} from "./index-qdgzsnhg.js";
 import"./index-q0y2jq9j.js";
-import"./index-p4p9t45x.js";
+import"./index-crmeqnmf.js";
 import"./index-6wwzs1bc.js";
 import {
   renderPrimitiveReport
-} from "./index-qhtj9y6j.js";
+} from "./index-2446k7b4.js";
 import {
   ScalarScript
-} from "./index-vpx68e4x.js";
+} from "./index-4m929vvn.js";
 
 // pkgs/@akanjs/cli/scalar/scalar.command.ts
 import { Logger, lowerlize } from "akanjs/common";

package/skills/akan-code/SKILL.md

@@ -0,0 +1,122 @@
+---
+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`**, 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 remove <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`.
+
+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; `/mcp` shows `sign-in needed` when a server wants one.
+
+## 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-module/SKILL.md

@@ -41,5 +41,5 @@ module. Collection-level helpers go `static` on the full model.
 - 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`.
+Deeper detail per layer is a `get_guideline` call away: `moduleOverview`, `modelConstant`, `modelDocument`,
+`modelService`, `modelSignal`, `modelStore`, `modelDictionary`.

package/skills/akan-store/SKILL.md

@@ -37,14 +37,18 @@ Only what the generated set does not cover: extra client state, a multi-step or
 calls to the non-CRUD endpoints you added in the signal. Each is an `async` method using `this.set(...)` /
 `this.get()` / `this.pick(...)`.
 
+To reach another store, cast `this`: `import type { RootStore } from "../st"`, then
+`(this as unknown as RootStore).logout()` to call its action or `(this as unknown as RootStore).set({ … })` /
+`.get()` to write or read its state. Every store is mixed into one root at runtime, so the cast only tells the
+type what `this` already is. Keep it `import type` — `st.ts` imports every store, so a value import is a cycle.
+
 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
+## The rule 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
 

package/{subspace.command-jqv5n79w.js → subspace.command-fktpwp0g.js}

@@ -4,23 +4,23 @@ import {
 } from "./index-q0y2jq9j.js";
 import {
   GlobalConfig
-} from "./index-myj01w9r.js";
+} from "./index-srmay5jw.js";
 import {
   Workspace,
   CommandContainer,
   runner,
   script,
   command
-} from "./index-6na0sd2b.js";
+} from "./index-qdgzsnhg.js";
 import {
   Executor,
   WorkspaceExecutor,
   AppExecutor
-} from "./index-p4p9t45x.js";
+} from "./index-crmeqnmf.js";
 import"./index-6wwzs1bc.js";
 import {
   SlicePlanner
-} from "./index-sn7dnzq4.js";
+} from "./index-kwaq3n9n.js";
 import {
   LibSource
 } from "./index-3d9y066c.js";
@@ -197,9 +197,20 @@ class Subspace {
     }
   }
   async#extract(paths, excludes = []) {
-    const pathspec = paths.map((entry) => `'${entry}'`).join(" ");
-    const excludeArgs = excludes.map((entry) => `--exclude='${entry}'`).join(" ");
-    await this.#workspace.exec(`git archive HEAD -- ${pathspec} | tar -x -C '${this.#clonePath}' ${excludeArgs}`.trim());
+    const archivePath = path.relative(this.#workspace.workspaceRoot, `${this.#clonePath}.tar`);
+    await this.#workspace.spawn("git", ["archive", "-o", archivePath, "HEAD", "--", ...paths]);
+    try {
+      await this.#workspace.spawn("tar", [
+        "-x",
+        "-f",
+        archivePath,
+        "-C",
+        this.#clonePath,
+        ...excludes.map((entry) => `--exclude=${entry}`)
+      ]);
+    } finally {
+      await rm(path.join(this.#workspace.workspaceRoot, archivePath), { force: true });
+    }
   }
   #localEnv() {
     const { serveDomain } = WorkspaceExecutor.getBaseDevEnv();
@@ -269,8 +280,7 @@ class Subspace {
     if (!await FileSys.fileExists(gitignorePath))
       return;
     const [begin = "", end = ""] = Subspace.secretsMarkers;
-    const lines = (await FileSys.readText(gitignorePath)).split(`
-`);
+    const lines = (await FileSys.readText(gitignorePath)).split(/\r?\n/);
     const beginIdx = lines.indexOf(begin);
     const endIdx = lines.indexOf(end);
     const filtered = beginIdx >= 0 && endIdx > beginIdx ? [
@@ -725,7 +735,7 @@ class SubspaceRunner extends runner("subspace") {
     if (!asked)
       return { name: subspace.name, workspaceId, host, apps, libs: [], outcome: "cancelled", files: [] };
     const { libs } = await subspace.slice();
-    const { CloudScript } = await import("./cloud.script-ch3xrw3s.js");
+    const { CloudScript } = await import("./cloud.script-fwx3vb34.js");
     const { files } = await CommandContainer.get(CloudScript).uploadEnv(workspace, {
       host,
       workspaceId,

package/templates/__scalar/__model__/__model__.abstract.md.template

@@ -0,0 +1,8 @@
+# <%= model %> Abstract
+
+<One sentence: the value this scalar holds, and what embeds it.>
+
+## Rules
+
+- <What a caller may assume about the value that the constant file cannot say: an order, a unit, a fixed value.>
+- <Two to five of them. A single field's meaning goes in a trailing comment beside it in the constant file.>

package/templates/appSample/lib/__scalar/workHistory/workHistory.abstract.ts

@@ -3,45 +3,14 @@ import type { AppInfo, LibInfo } from "akanjs";
 export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { appName: string }) {
   return {
     filename: "workHistory.abstract.md",
-    content: `# WorkHistory Scalar Abstract
-
-## Akan.js Module Pattern
-
-WorkHistory is a **scalar module** — a reusable value type under lib/__scalar/.
-Scalar modules are embedded into models via field([ScalarType]), not stored independently.
-They live under the double-underscore prefix to distinguish them from database models.
-
-Standard scalar layers:
-- workHistory.constant.ts — enum (WorkHistoryAction) + entry class (WorkHistory) defined via via() + enumOf()
-- workHistory.dictionary.ts — i18n via scalarDictionary() (fewer layers than modelDictionary)
-- workHistory.abstract.md — embedding rules and intent
-
-## Convention: lib/__scalar/<type>/ directory naming
-
-- Scalar modules use double-underscore prefix: lib/__scalar/workHistory/
-- Files drop the underscores: workHistory.constant.ts, not __workHistory.constant.ts
-- Models embed scalars via field([WorkHistory]) — list-of-scalar embedding
-
-## Embedding Example (in task.constant.ts)
-
-TaskObject embeds a list of WorkHistory:
-  import { WorkHistory } from "../../__scalar/workHistory/workHistory.constant";
-  export class TaskObject extends via(TaskInput, (field) => ({
-    workHistory: field([WorkHistory]),
-  }))
-
-Each status change (create, start, complete) pushes a new entry.
-
-## Agent Notes
-
-- Read this abstract before modifying the WorkHistory scalar.
-- Update when new action types or fields are added.
-- Do not duplicate workHistory fields in individual models; always reuse this scalar.
-
-## Related Modules
-
-- lib/task/ — database module embedding workHistory as a list field
-- lib/_noti/ — pure service module (different module type, no scalar usage)
+    content: `# workHistory Abstract
+One step in a task's history: which move happened, when, and an optional note.
+
+## Rules
+- Entries are only appended — by \`Task\`'s chain methods and by the task service on create — and never edited or
+  removed, so the list reads as the task's moves in order.
+- \`at\` is the moment the entry was built when the writer gives none.
+- \`note\` is empty on every entry the app writes itself.
 `,
   };
 }

package/templates/appSample/lib/_noti/noti.abstract.ts

@@ -3,36 +3,13 @@ import type { AppInfo, LibInfo } from "akanjs";
 export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { appName: string }) {
   return {
     filename: "noti.abstract.md",
-    content: `# Noti Abstract
+    content: `# noti Service Abstract
+Noti holds the in-app notification list on the client: the messages the app shows, an unread count, and dismissal.
 
-## Akan.js Module Pattern
-
-Noti is a **pure service module** — not a database module. It demonstrates the Akan.js convention
-for modules that orchestrate behavior without owning a persistent document model.
-
-Both module types follow the same layer pattern, but service modules have fewer layers:
-no constant.ts (no data shape), no document.ts (no DB queries), no UI components.
-
-- noti.service.ts — business logic via serve("noti" as const, ...) (named service, no DB binding)
-- noti.signal.ts — real-time pubsub endpoint bound via endpoint(srv.noti, ...)
-- noti.store.ts — client state via store("noti" as const, ...) (named store, no signal binding)
-- noti.dictionary.ts — i18n via serviceDictionary() (no model field labels)
-
-## Convention: lib/_<service>/ directory naming
-
-- Service modules live under lib/_<service>/ — the underscore prefix signals "this is a service, not a database model."
-- Files drop the underscore: lib/_noti/noti.service.ts, not lib/_noti/_noti.service.ts.
-- Scan registers into the same barrel files: srv.ts, sig.ts, st.ts, dict.ts.
-
-## Convention: named serve/store (no DB binding)
-
-- serve("noti" as const, ...) — service name passed as string, no db.<module> binding.
-- store("noti" as const, ...) — store name passed as string, no sig.<module> binding.
-
-## Related Modules
-
-- lib/task/ — database module reference (compare structure differences)
-- lib/__scalar/workHistory/ — reusable scalar field modules (double-underscore prefix, embedded in models)
+## Rules
+- Notifications live only in the client store; the server side declares nothing yet, so a reload starts empty.
+- \`unreadCount\` counts additions since the last \`markAllRead()\`, not the list's length — removing a notification
+  does not lower it.
 `,
   };
 }

package/templates/appSample/lib/task/task.abstract.ts

@@ -3,38 +3,18 @@ import type { AppInfo, LibInfo } from "akanjs";
 export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { appName: string }) {
   return {
     filename: "task.abstract.md",
-    content: `# Task Abstract
-
-## Akan.js Module Pattern
-
-Task is a **database-backed domain module** — the standard Akan.js pattern for persisted entities.
-This module demonstrates the full Akan.js module lifecycle:
-constant -> document -> service -> signal -> store -> UI.
-
-Every database module in Akan.js follows this layered architecture:
-- task.constant.ts — data shape (enum, Input, Object, Light, Full layers via via())
-- task.document.ts — DB queries, filters, sorts, indexes, Document chain methods
-- task.dictionary.ts — i18n labels, error messages, UI translations
-- task.service.ts — business logic orchestration bound to DB via serve(db.task, ...)
-- task.signal.ts — API surface (query, mutation, pubsub endpoints bound via endpoint(srv.task, ...))
-- task.store.ts — client state management bound to signal via store(sig.task, ...)
-- Task.*.tsx — UI components (Zone -> Load -> Unit / View / Template / Util)
-
-## Convention: lib/<module>/ directory naming
-
-- Database modules live under lib/<module>/ (no underscore prefix)
-- Files follow <module>.<layer>.ts naming — e.g., task.constant.ts, task.service.ts
-- UI files use PascalCase with explicit suffix: Task.Zone.tsx, Task.Unit.tsx, Task.View.tsx
-
-## Convention: scan-registered barrels
-
-akan sync auto-discovers each file and registers it in the corresponding barrel:
-cnst.ts, db.ts, dict.ts, srv.ts, sig.ts, st.ts
-
-## Related Modules
-
-- lib/__scalar/workHistory/ — standard scalar modules with double-underscore prefix (reusable field sets)
-- lib/_noti/ — pure service module (compare structure differences: no constant/document, serve without DB binding)
+    content: `# task Abstract
+A task is one unit of work that moves from todo through in progress to completed, and keeps a record of each move.
+
+## Rules
+- A task only moves forward: \`start()\` needs \`todo\` and \`complete()\` needs \`inProgress\`; any other state throws.
+- Every move appends one \`workHistory\` entry, and creation writes the first (\`created\`), so the history is never
+  empty and its last entry always matches \`status\`.
+- Anyone may read a task; creating, changing, starting and completing one needs a signed-in caller. There is no
+  generated admin API (\`root: None\`).
+- Removal is soft: a removed task keeps its row with \`removedAt\` set.
+
+todo -> inProgress -> completed
 `,
   };
 }