@akanjs/cli 2.3.9-rc.0 → 2.3.9-rc.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "2.3.9-rc.0",
+  "version": "2.3.9-rc.2",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -34,7 +34,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.3.9-rc.0",
+    "akanjs": "2.3.9-rc.2",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/templates/appSample/common/formatters.ts

@@ -7,7 +7,7 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { a
 // Convention: common/ folder — only pure functions that run on both server and client.
 // Cannot import window, Bun, process.env, or any runtime-specific API.
 // Naming: camelCase .ts, file name = primary export name.
-// Scanned by akan scan into common/index.ts barrel automatically.
+// Scanned by akan sync into common/index.ts barrel automatically.
 
 export function trimString(str: string, maxLength = 50, suffix = "...") {
   if (str.length <= maxLength) return str;

package/templates/appSample/common/validators.ts

@@ -7,7 +7,7 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { a
 // Convention: common/ folder — only pure functions that run on both server and client.
 // Cannot import window, Bun, process.env, or any runtime-specific API.
 // Naming: camelCase .ts, file name = primary export name.
-// Scanned by akan scan into common/index.ts barrel automatically.
+// Scanned by akan sync into common/index.ts barrel automatically.
 
 export function isValidEmail(email: string): boolean {
   const emailRegex = /^[^s@]+@[^s@]+.[^s@]+$/;

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

@@ -9,7 +9,7 @@ import type { NotiEndpoint } from "./noti.signal";
 // Uses serviceDictionary(["en", "ko"]) from akanjs/dictionary — the framework convention for service dictionaries.
 // Unlike modelDictionary, no model/lightModel/query/sort/enum sections (service modules have no DB model).
 // Sections: .endpoint() for signal endpoint names, .translate() for UI messages.
-// Registered by akan scan into dict.ts barrel.
+// Registered by akan sync into dict.ts barrel.
 
 export const dictionary = serviceDictionary(["en", "ko"])
   .endpoint<NotiEndpoint>((fn) => ({

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

@@ -8,7 +8,7 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { a
 // Extends serve("noti" as const, ...) — named service (string literal), no DB model binding.
 // DB modules use serve(db.<module>, ...); service modules use serve("<name>" as const, ...).
 // DI deps available: { service, use, signal, plug, env, memory }.
-// Registered by akan scan into srv.ts barrel.
+// Registered by akan sync into srv.ts barrel.
 
 export class NotiService extends serve("noti" as const, () => ({})) {}
 

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

@@ -10,7 +10,7 @@ import * as srv from "../srv";
 // Extends endpoint(srv.<module>, ...) — pubsub endpoint for real-time server→client communication.
 // pubsub() is the Akan.js convention for publish-subscribe: server publishes, all connected clients receive.
 // Client subscribes via fetch.subscribeSend((data) => { ... }).
-// Registered by akan scan into sig.ts barrel.
+// Registered by akan sync into sig.ts barrel.
 
 export class NotiInternal extends internal(srv.noti, () => ({})) {}
 

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

@@ -9,7 +9,7 @@ import { store } from "akanjs/store";
 // Extends store("noti" as const, ...) — named store (string literal), no signal binding.
 // DB modules use store(sig.<module>, ...); service modules use store("<name>" as const, ...).
 // State definitions use direct property assignment. Actions use this.set() / this.get().
-// Registered by akan scan into st.ts barrel.
+// Registered by akan sync into st.ts barrel.
 
 export class NotiStore extends store("noti" as const, () => ({
   notiList: [] as { id: string; type: string; message: string; sentAt: Dayjs }[],

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

@@ -28,7 +28,7 @@ Every database module in Akan.js follows this layered architecture:
 
 ## Convention: scan-registered barrels
 
-akan scan auto-discovers each file and registers it in the corresponding barrel:
+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

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

@@ -12,7 +12,7 @@ import { WorkHistory } from "../__scalar/workHistory/workHistory.constant";
 // Scalars are embedded via field([ScalarType], ...) — see WorkHistory embedding below.
 // Layer order: enum → Input → Object → Light → Full.
 //   Input = user-provided fields; Object = Input + system fields + embedded scalars; Light = subset for list views; Full = Object + Light.
-// Registered by akan scan into cnst.ts barrel.
+// Registered by akan sync into cnst.ts barrel.
 
 export class TaskStatus extends enumOf("taskStatus", [
   "todo",

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

@@ -11,7 +11,7 @@ import type { TaskFilter } from "./task.document";
 // Uses modelDictionary(["en", "ko"]) from akanjs/dictionary — the framework convention for bilingual module dictionaries.
 // Sections: .of() module name, .model() field labels, .lightModel() list-view labels, .query() filter labels,
 // .sort() labels, .enum() value labels, .error() messages (thrown via Err()), .translate() UI messages (used in store via msg.xxx).
-// Registered by akan scan into dict.ts barrel.
+// Registered by akan sync into dict.ts barrel.
 
 export const dictionary = modelDictionary(["en", "ko"])
   .of((t) =>

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

@@ -10,10 +10,10 @@ import * as cnst from "../cnst";
 // ===== task.document.ts =====
 // Convention: <module>.document.ts — the database query and persistence layer.
 // Import from/into/by from akanjs/document — the framework convention for Filter, Document, and Model classes.
-// Filter defines query/sort conditions (auto-generates List/Find/Pick/Exists/Count methods via akan scan).
+// Filter defines query/sort conditions (auto-generates List/Find/Pick/Exists/Count methods via akan sync).
 // Document defines chainable per-document methods (e.g., task.start().save()).
 // Model = into(Document, Filter, cnst.module, ...) — collection-level operations, schema hooks.
-// Registered by akan scan into db.ts barrel.
+// Registered by akan sync into db.ts barrel.
 
 export class TaskFilter extends from(cnst.Task, (filter) => ({
   query: {
@@ -34,7 +34,7 @@ export class Task extends by(cnst.Task) {
   start() {
     if (this.status !== "todo") throw new Err("task.error.cannotStartFromNonTodo");
     this.status = "inProgress";
-    this.workHistory.push({ action: "completed", at: dayjs(), note: "" });
+    this.workHistory.push({ action: "started", at: dayjs(), note: "" });
     return this;
   }
 

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

@@ -9,11 +9,11 @@ import * as db from "../db";
 // ===== task.service.ts =====
 // Convention: <module>.service.ts — business logic orchestration for a database module.
 // Extends serve(db.<module>, depsCallback) from akanjs/service — binds to the DB model, receives DI deps.
-// Auto-generated by akan scan (do not write manually):
+// Auto-generated by akan sync (do not write manually):
 //   getTask(id), createModel(data), updateModel(id, data), removeModel(id),
 //   listByStatus(status), searchDocs(text), and all filter+query methods from document.ts.
 // Manual below: lifecycle hooks, custom business logic methods.
-// Registered by akan scan into srv.ts barrel.
+// Registered by akan sync into srv.ts barrel.
 
 export class TaskService extends serve(db.task, () => ({})) {
   // Lifecycle hook: runs before every document creation.

package/templates/appSample/lib/task/task.signal.spec.ts

@@ -0,0 +1,70 @@
+import type { AppInfo, LibInfo } from "akanjs";
+
+export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { appName: string }) {
+  return `import { expect } from "bun:test";
+import type { DocumentModel } from "akanjs/constant";
+import { getOrSetupSignalTestFetch, sampleOf } from "akanjs/test";
+
+import * as cnst from "../cnst";
+import type { fetch as appFetch } from "../useServer";
+
+type AppFetch = typeof appFetch;
+
+const getFetch = async () => await getOrSetupSignalTestFetch<AppFetch>();
+
+export interface TaskAgent {
+  task: cnst.Task;
+  fetch: AppFetch;
+  taskInput: DocumentModel<cnst.TaskInput>;
+}
+
+export const createTask = async (overrides: Partial<DocumentModel<cnst.TaskInput>> = {}): Promise<TaskAgent> => {
+  const fetch = await getFetch();
+  const taskInput = {
+    ...sampleOf(cnst.TaskInput),
+    ...overrides,
+  };
+
+  const task = await fetch.createTask(taskInput);
+
+  expect(task).toMatchObject({
+    title: taskInput.title,
+    content: taskInput.content,
+    status: "todo",
+  });
+  expect(task.workHistory.map((entry) => entry.action)).toEqual(["created"]);
+
+  return {
+    task,
+    fetch,
+    taskInput,
+  };
+};
+
+export const getStartedTask = async (overrides: Partial<DocumentModel<cnst.TaskInput>> = {}): Promise<TaskAgent> => {
+  const agent = await createTask(overrides);
+  const task = await agent.fetch.startTask(agent.task.id);
+
+  expect(task.status).toBe("inProgress");
+  expect(task.workHistory.map((entry) => entry.action)).toEqual(["created", "started"]);
+
+  return {
+    ...agent,
+    task,
+  };
+};
+
+export const getCompletedTask = async (overrides: Partial<DocumentModel<cnst.TaskInput>> = {}): Promise<TaskAgent> => {
+  const agent = await getStartedTask(overrides);
+  const task = await agent.fetch.completeTask(agent.task.id);
+
+  expect(task.status).toBe("completed");
+  expect(task.workHistory.map((entry) => entry.action)).toEqual(["created", "started", "completed"]);
+
+  return {
+    ...agent,
+    task,
+  };
+};
+`;
+}

package/templates/appSample/lib/task/task.signal.test.ts

@@ -0,0 +1,20 @@
+import type { AppInfo, LibInfo } from "akanjs";
+
+export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { appName: string }) {
+  return `import { describe, expect, test } from "bun:test";
+import { configureSignalTest } from "akanjs/test";
+
+import * as taskSpec from "./task.signal.spec";
+
+configureSignalTest({ databaseMode: "memory" });
+
+describe("Task signal smoke", () => {
+  test("exposes custom task mutations over fetch", async () => {
+    const { task } = await taskSpec.getCompletedTask({ title: "Signal smoke task" });
+
+    expect(task.status).toBe("completed");
+    expect(task.workHistory.map((entry) => entry.action)).toEqual(["created", "started", "completed"]);
+  });
+});
+`;
+}

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

@@ -12,12 +12,12 @@ import * as srv from "../srv";
 // endpoint() receives: { query, mutation, pubsub, message } — each typed with the model's return type.
 // .param() = URL path parameter, .body() = request body, .search() = query string.
 //
-// Auto-generated by akan scan (do not write manually):
+// Auto-generated by akan sync (do not write manually):
 //   viewTask(id) — fetch single task for detail view
 //   editTask(id) — fetch task for edit view
 //   mergeTask(id, data) — create/update task
 // Manual endpoints below: only define endpoints that need custom business logic.
-// Registered by akan scan into sig.ts barrel.
+// Registered by akan sync into sig.ts barrel.
 
 export class TaskInternal extends internal(srv.task, ({ interval }) => ({})) {}
 

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

@@ -8,13 +8,13 @@ import { fetch, msg, sig } from "../useClient";
 // ===== task.store.ts =====
 // Convention: <module>.store.ts — client-side state management for a database module.
 // Extends store(sig.<module>, ...) from akanjs/store — binds to the signal to auto-generate model states/actions.
-// Auto-generated by akan scan (do not write manually):
+// Auto-generated by akan sync (do not write manually):
 //   taskForm — form state bound to model fields (create + edit)
 //   setTitleOnTask, setContentOnTask, setDueOnTask — auto-setters for form fields
 //   createTask(data), updateTask(id, data), removeTask(id) — CRUD actions
 //   task (cached model), taskLoading, taskModal — model display states
 // Manual below: custom actions wrapping auto-generated fetch with toast feedback.
-// Registered by akan scan into st.ts barrel.
+// Registered by akan sync into st.ts barrel.
 
 export class TaskStore extends store(sig.task, () => ({})) {
   async startTask(taskId: string) {

package/templates/appSample/srvkit/AuthGuard.ts

@@ -10,7 +10,7 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { a
 // Implements the Guard interface from akanjs/signal.
 // Guards are applied at endpoint/slice declaration: { guards: { root: SignedIn } }.
 // Naming: PascalCase .ts, static name property matches the guard identifier.
-// Scanned by akan scan into srvkit/index.ts barrel automatically.
+// Scanned by akan sync into srvkit/index.ts barrel automatically.
 
 export class SignedIn implements Guard {
   static name = "SignedIn";

package/templates/appSample/srvkit/SessionInternalArg.ts

@@ -11,7 +11,7 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { a
 // InternalArg is an auto-injected argument for resolveField/endpoint .with() chains.
 // Appended to a query/mutation via: .with(CurrentUserId, { nullable: true }).exec(...)
 // Naming: PascalCase .ts, class name = arg identifier.
-// Scanned by akan scan into srvkit/index.ts barrel automatically.
+// Scanned by akan sync into srvkit/index.ts barrel automatically.
 
 export class CurrentUserId implements InternalArg<string | null> {
   getArg(context: SignalContext): string | null {

package/templates/appSample/ui/GlobalLoading.tsx

@@ -10,7 +10,7 @@ import { clsx } from "akanjs/client";
 // ===== GlobalLoading.tsx =====
 // Convention: ui/ folder — reusable visual components. PascalCase .tsx, "use client" directive.
 // File name = exported component name.
-// Scanned by akan scan into ui/index.ts barrel automatically.
+// Scanned by akan sync into ui/index.ts barrel automatically.
 
 interface GlobalLoadingProps {
   className?: string;

package/templates/appSample/ui/QuantityControl.tsx

@@ -10,7 +10,7 @@ import { clsx } from "akanjs/client";
 // ===== QuantityControl.tsx =====
 // Convention: ui/ folder — reusable visual components. PascalCase .tsx, "use client" directive.
 // File name = exported component name.
-// Scanned by akan scan into ui/index.ts barrel automatically.
+// Scanned by akan sync into ui/index.ts barrel automatically.
 
 interface QuantityControlProps {
   className?: string;

package/templates/appSample/webkit/useDebounce.ts

@@ -11,7 +11,7 @@ import { useEffect, useState } from "react";
 // Convention: webkit/ folder — browser-only hooks; "use client" directive required.
 // useEffect/useState are React client-side primitives that only work in the browser.
 // Naming: camelCase .ts, file name = primary export name.
-// Scanned by akan scan into webkit/index.ts barrel automatically.
+// Scanned by akan sync into webkit/index.ts barrel automatically.
 
 export function useDebounce<T>(value: T, delay = 300): T {
   const [debouncedValue, setDebouncedValue] = useState<T>(value);

package/templates/lib/useClient.ts

@@ -1,9 +1,6 @@
 import type { AppInfo, LibInfo } from "akanjs";
 
-export default function getContent(
-  scanInfo: AppInfo | LibInfo | null,
-  dict: { [key: string]: string } = {},
-) {
+export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { [key: string]: string } = {}) {
   return `
 import { makePageProto, registerClientRuntime } from "akanjs/client";
 import { FetchClient } from "akanjs/fetch";

package/templates/module/__Model__.Unit.tsx

@@ -5,10 +5,7 @@ interface Dict {
   model: string;
   sysName: string;
 }
-export default function getContent(
-  scanInfo: AppInfo | LibInfo | null,
-  dict: Dict,
-) {
+export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: Dict) {
   return {
     filename: `${dict.Model}.Unit.tsx`,
     content: `

package/templates/workspaceRoot/.cursor/rules/{akan-scan-conventions.mdc.template → akan-sync-conventions.mdc.template}

@@ -1,10 +1,10 @@
 ---
-description: scanSync-enforced Akan app/lib layout and generated index conventions
+description: sync-enforced Akan app/lib layout and generated index conventions
 globs: apps/**/*,libs/**/*
 alwaysApply: false
 ---
 
-# Akan Scan Conventions
+# Akan Sync Conventions
 
 - `apps/<appName>` root may only contain these files: `akan.app.json`, `akan.config.ts`, `capacitor.config.ts`, `client.ts`, `main.ts`, `package.json`, `server.ts`, `tsconfig.json`.
 - `apps/<appName>` root may only contain these folders: `.akan`, `android`, `common`, `env`, `ios`, `lib`, `page`, `private`, `public`, `script`, `srvkit`, `ui`, `webkit`.
@@ -15,5 +15,5 @@ alwaysApply: false
 - Service module UI files are limited to `<Service>.Util.tsx` and `<Service>.Zone.tsx`.
 - Scalar module UI files are limited to `<Scalar>.Template.tsx` and `<Scalar>.Unit.tsx`.
 - Module `*.test.ts`, `*.test.tsx`, `*.spec.ts`, and `*.spec.tsx` files are allowed.
-- `ui/index.ts`, `webkit/index.ts`, `srvkit/index.ts`, `common/index.ts`, and module `lib/**/index.ts` files are generated by scanSync; do not hand-edit or track them.
+- `ui/index.ts`, `webkit/index.ts`, `srvkit/index.ts`, `common/index.ts`, and module `lib/**/index.ts` files are generated by `akan sync`; do not hand-edit or track them.
 - Generated facet indexes export only 1-depth files/folders with `export * from "./name";`.

package/templates/workspaceRoot/.cursor/rules/akan.mdc.template

@@ -15,6 +15,11 @@ alwaysApply: true
 - Do not hand-edit generated Akan files such as `akan.app.json`, `client.ts`, `server.ts`, generated facet indexes,
   `lib/cnst.ts`, `lib/dict.ts`, `lib/db.ts`, `lib/srv.ts`, `lib/st.ts`, `lib/sig.ts`, `lib/useClient.ts`, or
   `lib/useServer.ts`.
+- Prefer Akan MCP workflows before direct source edits: use `akan mcp --mode plan` for workflow discovery and
+  planning, then `akan mcp --mode apply` only for allowlisted apply, validation, and repair tools.
+- Direct source edits are denied when an allowlisted Akan workflow or repair tool can perform the change.
+- If generated output is stale or broken, update the owning source file and run `akan repair generated` or
+  `akan sync <app-or-lib>` instead of patching generated files.
 - For new domain behavior, inspect sibling `constant`, `dictionary`, `signal`, `document`, `service`, `store`, and UI
   module files before changing shape.
 - Update `*.abstract.md` when business invariants, workflows, or public behavior change. Do not update it for

package/templates/workspaceRoot/AGENTS.md.template

@@ -3,6 +3,9 @@
 This is an Akan.js workspace. Akan is convention-driven: keep business intent in the expected place and let
 the framework generate the repeated surfaces.
 
+For agent-neutral documentation that Claude Code, Codex, Devin, GitHub Copilot Coding Agent, and other tools can
+also read, see `docs/AI-DEVELOPMENT.md` and `docs/GENERATED.md`.
+
 ## Workspace Layout
 
 - `apps/<app>` contains application pages, app UI, app domain modules, env files, and `akan.config.ts`.
@@ -16,25 +19,26 @@ the framework generate the repeated surfaces.
 
 ## Generated Files
 
-Do not hand-edit generated Akan files. Regenerate them through Akan scan, lint, start, build, or the matching
+Do not hand-edit generated Akan files. Regenerate them through Akan sync, lint, start, build, or the matching
 CLI command instead.
 
 Common generated files include:
 - `apps/*/client.ts`
 - `apps/*/server.ts`
-- `apps/*/lib/cnst.ts`
-- `apps/*/lib/dict.ts`
-- `apps/*/lib/db.ts`
-- `apps/*/lib/srv.ts`
-- `apps/*/lib/st.ts`
-- `apps/*/lib/sig.ts`
-- `apps/*/lib/useClient.ts`
-- `apps/*/lib/useServer.ts`
-- `apps/*/lib/*/index.ts`
-- `apps/*/ui/index.ts`
-- `apps/*/webkit/index.ts`
-- `apps/*/srvkit/index.ts`
-- `apps/*/common/index.ts`
+- `*/lib/cnst.ts`
+- `*/lib/db.ts`
+- `*/lib/dict.ts`
+- `*/lib/option.ts`
+- `*/lib/sig.ts`
+- `*/lib/srv.ts`
+- `*/lib/st.ts`
+- `*/lib/useClient.ts`
+- `*/lib/useServer.ts`
+- `*/lib/**/index.ts`
+- `*/ui/index.ts`
+- `*/webkit/index.ts`
+- `*/srvkit/index.ts`
+- `*/common/index.ts`
 
 ## Domain Module Responsibilities
 
@@ -58,15 +62,18 @@ Use the local module shape before adding a new abstraction.
 
 1. Read the nearby module and convention before creating files. If `*.abstract.md` exists, read it first.
 2. Put new files in the established Akan location instead of adding parallel architecture.
-3. Prefer CLI generation commands for new apps, libraries, modules, scalars, pages, and generated references.
-4. Keep page and layout files server-oriented: route-level `usePage`, headers, static layout, and `akanjs/ui` `Tab` composition belong there.
-5. Put interactive loading, submit/import actions, local form state, and `router.push` in client `Util`, `Template`, or `Zone` components.
-6. Prefer `Tab` for static mode selection instead of extra `useState`; render one focused client component inside each `Tab.Panel`.
-7. Keep server-only logic out of client surfaces and client-only code out of server imports.
-8. Treat `AKAN_PUBLIC_*` env vars as public. Never put secrets in them.
-9. Add or update tests when behavior, contracts, or CLI output changes.
-10. Update `*.abstract.md` when business invariants, workflows, or public behavior change.
-11. Run the smallest relevant verification command after changes.
+3. Prefer Akan MCP workflows before direct source edits. Start with `akan mcp --mode plan` for `list_workflows`, `explain_workflow`, and `plan_workflow`.
+4. Use `akan mcp --mode apply` only for allowlisted `apply_workflow`, `run_validation`, and repair tools.
+5. Direct source edits are denied when an allowlisted Akan workflow or repair tool can perform the change.
+6. If no workflow exists, edit only the owning source files and never patch generated files directly.
+7. Keep page and layout files server-oriented: route-level `usePage`, headers, static layout, and `akanjs/ui` `Tab` composition belong there.
+8. Put interactive loading, submit/import actions, local form state, and `router.push` in client `Util`, `Template`, or `Zone` components.
+9. Prefer `Tab` for static mode selection instead of extra `useState`; render one focused client component inside each `Tab.Panel`.
+10. Keep server-only logic out of client surfaces and client-only code out of server imports.
+11. Treat `AKAN_PUBLIC_*` env vars as public. Never put secrets in them.
+12. Add or update tests when behavior, contracts, or CLI output changes.
+13. Update `*.abstract.md` when business invariants, workflows, or public behavior change.
+14. Run the smallest relevant verification command after changes.
 
 ## Common Commands
 
@@ -117,77 +124,89 @@ For the default generated app, start with:
 akan start <%= appName %>
 ```
 
-### The Essential Loop: Edit → Scan → Check
+### The Essential Loop: Workflow -> Sync -> Check
+
+Almost every Akan.js change follows this pattern. **Missing sync or repair is the #1 cause of agent confusion.**
 
-Almost every Akan.js change follows this pattern. **Missing step 2 is the #1 cause of agent confusion.**
+1. **Plan** — Ask the Akan MCP server for the workflow first.
+   ```
+   akan mcp --mode plan
+   # use list_workflows, explain_workflow, and plan_workflow
+   ```
 
-1. **Edit** — Create or modify source files in the correct location.
+2. **Apply or edit source** — Use allowlisted apply/repair tools when available. If no workflow exists, edit only
+   owning source files such as `task.constant.ts`, `task.dictionary.ts`, `Task.Template.tsx`, or `Task.Unit.tsx`.
+   Never edit generated files.
    ```
-   vi apps/<%= appName %>/lib/task/task.constant.ts  # e.g., add a priority field
+   akan mcp --mode apply
+   # use apply_workflow, run_validation, repair_generated, repair_imports, or repair_module_shape
    ```
 
-2. **Scan** — Regenerate barrel files so Akan discovers your change. This regenerates:
+3. **Sync or repair** — Regenerate barrel files so Akan discovers your change. This regenerates:
    `cnst.ts`, `db.ts`, `srv.ts`, `sig.ts`, `st.ts`, `dict.ts`, `useClient.ts`, `useServer.ts`,
    `ui/index.ts`, `webkit/index.ts`, `srvkit/index.ts`, `common/index.ts`, and all module `index.ts` files.
    ```
-   akan scan app <%= appName %>
+   akan sync <%= appName %>
+   # or: akan repair generated --app <%= appName %>
    ```
-   **CRITICAL**: Scan after EVERY file add, delete, or rename. Without scan, other modules cannot
+   **CRITICAL**: Sync after EVERY file add, delete, or rename. Without sync, other modules cannot
    `import * as cnst from "../cnst"` and find your new model.
 
-3. **Check** — Verify your change compiles and lints.
+4. **Check** — Verify your change compiles and lints.
    ```
    akan start <%= appName %>   # dev server with live feedback (preferred)
    akan lint <%= appName %>    # quick lint-only check
+   akan doctor --strict        # structured workspace diagnostics
    ```
 
-   If `akan scan` gives errors, try:
-   - `akan build <%= appName %>` — full rebuild catches type errors scan may miss
-   - Re-run `akan create-model <name> --app <%= appName %>` if the scaffold is corrupted
+   If `akan sync` gives errors, try:
+   - `akan build <%= appName %>` — full rebuild catches type errors sync may miss
+   - Re-run `akan create-module <name> --app <%= appName %>` if the scaffold is corrupted
 
 ## Quick Decision Matrix — "Where do I put this code?"
 
 | You want to... | Create in... | Run after... |
 |----------------|-------------|--------------|
-| Define a new database-backed noun (e.g., User, Product) | `lib/<model>/` → constant, document, service, signal, store, dictionary, abstract | `akan scan app <name>` |
-| Add a pure workflow / integration (e.g., Payment, Email) | `lib/_<service>/` → service, signal, store, dictionary, abstract | `akan scan app <name>` |
-| Add a reusable value type (e.g., Address, WorkHistory) | `lib/__scalar/<type>/` → constant, dictionary, abstract | `akan scan app <name>` |
+| Define a new database-backed noun (e.g., User, Product) | `lib/<model>/` → constant, document, service, signal, store, dictionary, abstract | `akan sync <name>` |
+| Add a pure workflow / integration (e.g., Payment, Email) | `lib/_<service>/` → service, signal, store, dictionary, abstract | `akan sync <name>` |
+| Add a reusable value type (e.g., Address, WorkHistory) | `lib/__scalar/<type>/` → constant, dictionary, abstract | `akan sync <name>` |
 | Create a new URL-visitable page | `page/` → `_index.tsx`, `_layout.tsx`, `[param]/_index.tsx` | Rebuild (akan start auto-detects) |
-| Add a form or reusable UI component | `ui/` → PascalCase `.tsx` with `"use client"` if needed | `akan scan app <name>` |
-| Add a React hook or browser helper | `webkit/` → camelCase `.ts` with `"use client"` | `akan scan app <name>` |
-| Add a server-only guard, middleware, or adaptor | `srvkit/` → PascalCase `.ts` | `akan scan app <name>` |
-| Add a pure helper (no DOM, no server API) | `common/` → camelCase `.ts` | `akan scan app <name>` |
+| Add a form or reusable UI component | `ui/` → PascalCase `.tsx` with `"use client"` if needed | `akan sync <name>` |
+| Add a React hook or browser helper | `webkit/` → camelCase `.ts` with `"use client"` | `akan sync <name>` |
+| Add a server-only guard, middleware, or adaptor | `srvkit/` → PascalCase `.ts` | `akan sync <name>` |
+| Add a pure helper (no DOM, no server API) | `common/` → camelCase `.ts` | `akan sync <name>` |
 
 ## Anti-patterns: Never Do These
 
 | Don't | Why | Do Instead |
 |-------|-----|------------|
-| Edit `cnst.ts`, `db.ts`, `srv.ts`, `sig.ts`, `st.ts`, `dict.ts`, `useClient.ts`, `useServer.ts`, or any `index.ts` | These are **generated by `akan scan`**. Your changes will be overwritten. | Edit the source files in `lib/<model>/` directories and run `akan scan` |
-| Create a file without running scan | New files won't appear in barrel exports. Imports like `import * as cnst from "../cnst"` will fail. | Always run `akan scan app <name>` after creating, renaming, or deleting any module file |
+| Edit `cnst.ts`, `db.ts`, `srv.ts`, `sig.ts`, `st.ts`, `dict.ts`, `useClient.ts`, `useServer.ts`, or any `index.ts` | These are **generated by `akan sync`**. Your changes will be overwritten. | Edit the source files in `lib/<model>/` directories and run `akan sync <name>` |
+| Create a file without running sync | New files won't appear in barrel exports. Imports like `import * as cnst from "../cnst"` will fail. | Always run `akan sync <name>` after creating, renaming, or deleting any module file |
 | Use JS `#private` methods in service classes | Akan's build system rejects `#private`. Use TypeScript `private` keyword instead. | `private _methodName()` — never `#_methodName()` |
 | Use `console.log()` | Biome lint forbids `console.log`. Only `console.error`, `console.info`, `console.warn` are allowed. | Use one of the three allowed console methods |
 | Import server APIs (`fs`, `Bun`, `process.env`) in `ui/`, `webkit/`, or `common/` | Server-only imports in client code cause build failures. | Keep server dependencies in `lib/`, `srvkit/`, or `private/` only |
-| Skip running `akan scan` after deleting a file | Deleted files remain referenced in barrel exports, causing import errors everywhere. | Run `akan scan app <name>` after every file add, remove, or rename |
+| Skip running `akan sync` after deleting a file | Deleted files remain referenced in barrel exports, causing import errors everywhere. | Run `akan sync <name>` after every file add, remove, or rename |
 | Use "use client" or `useState`/`useEffect` in pages/*.tsx, *.Unit.tsx, and *.View.tsx files | Server code cannot use React hooks. Wrap in a separate `"use client"` component. | Move hook logic to `webkit/` or a `"use client"` UI component |
 | Use `<a>` tag for internal navigation between pages | Akan.js uses `<Link>` from `akanjs/ui` for client-side navigation — avoids full page reloads. | `import { Link } from "akanjs/ui"` and use `<Link href="/task">...</Link>` |
 
 ## Generated File Tracker (Quick Reference)
 
-These files are regenerated by `akan scan` and overwritten on every scan. **Do not hand-edit them.**
+These files are regenerated by `akan sync` and overwritten on every sync. **Do not hand-edit them.**
 
 | File | Generated From | Purpose |
 |------|---------------|---------|
-| `apps/*/lib/cnst.ts` | All `*/lib/*/**.constant.ts` | Barrel for all constants |
-| `apps/*/lib/dict.ts` | All `*/lib/*/**.dictionary.ts` | Barrel for all dictionaries |
-| `apps/*/lib/db.ts` | All `*/lib/<model>/*.document.ts` | Barrel for all document models |
-| `apps/*/lib/srv.ts` | All `*/lib/**/**.service.ts` | Barrel for all services |
-| `apps/*/lib/sig.ts` | All `*/lib/**/**.signal.ts` | Barrel for all signals |
-| `apps/*/lib/st.ts` | All `*/lib/**/**.store.ts` | Barrel for all stores |
-| `apps/*/lib/useClient.ts` | Client-safe module re-exports | Client-side import entry |
-| `apps/*/lib/useServer.ts` | Server-only module re-exports | Server-side import entry |
+| `*/lib/cnst.ts` | All `*/lib/*/**.constant.ts` | Barrel for all constants |
+| `*/lib/db.ts` | All `*/lib/<model>/*.document.ts` | Barrel for all document models |
+| `*/lib/dict.ts` | All `*/lib/*/**.dictionary.ts` | Barrel for all dictionaries |
+| `*/lib/option.ts` | Generated option helpers | Option helper entry |
+| `*/lib/sig.ts` | All `*/lib/**/**.signal.ts` | Barrel for all signals |
+| `*/lib/srv.ts` | All `*/lib/**/**.service.ts` | Barrel for all services |
+| `*/lib/st.ts` | All `*/lib/**/**.store.ts` | Barrel for all stores |
+| `*/lib/useClient.ts` | Client-safe module re-exports | Client-side import entry |
+| `*/lib/useServer.ts` | Server-only module re-exports | Server-side import entry |
 | `apps/*/client.ts` | App-wide client barrel | The `fetch` and `st` instances |
 | `apps/*/server.ts` | App-wide server barrel | Server-side service resolution |
-| `*/lib/*/index.ts` | Per-module barrel | Module-level re-exports |
+| `*/lib/**/index.ts` | Per-module barrel | Module-level re-exports |
 | `*/ui/index.ts` | All UI component files | UI barrel |
 | `*/webkit/index.ts` | All webkit files | Webkit barrel |
 | `*/srvkit/index.ts` | All srvkit files | Srvkit barrel |
@@ -206,7 +225,7 @@ rewrite the entire file.
 
 ### Recipe 1: Adding a New Field to a Model
 
-**Files to edit (in order):** `constant.ts` → `dictionary.ts` → `Template.tsx` → `Unit.tsx` → `akan scan`
+**Files to edit (in order):** `constant.ts` → `dictionary.ts` → `Template.tsx` → `Unit.tsx` → `akan sync`
 
 ```typescript
 // 1. apps/<app>/lib/<model>/<model>.constant.ts
@@ -249,7 +268,7 @@ const form = st.use.taskForm();
 })}>{task.priority}</span>
 
 // 5. Regenerate barrels
-// akan scan app <name>
+// akan sync <name>
 ```
 
 ---
@@ -491,7 +510,7 @@ For each business question, follow this chain:
 
 ## Auto-Generated API Reference
 
-akan scan automatically generates APIs across all layers. Only write custom logic — never hand-write what the framework generates.
+akan sync automatically generates APIs across all layers. Only write custom logic — never hand-write what the framework generates.
 
 ### Signal — Endpoint Auto-Generation
 
@@ -542,4 +561,4 @@ akan scan automatically generates APIs across all layers. Only write custom logi
 | `exists[Query](args)`, `count[Query](args)` | Existence check and count |
 | `insight[Query](args)`, `query[Query](args)` | Insight and raw query |
 
-**Rule**: Define `Filter` with `.query()` conditions in `document.ts`. akan scan auto-generates all 10 query helper methods per filter. Write `Document` chain methods only for state transitions with validation.
+**Rule**: Define `Filter` with `.query()` conditions in `document.ts`. akan sync auto-generates all 10 query helper methods per filter. Write `Document` chain methods only for state transitions with validation.