@akanjs/cli 2.3.11-rc.4 → 2.3.11-rc.6

package/incrementalBuilder.proc.js

@@ -1710,7 +1710,8 @@ var appRootAllowedFiles = new Set([
   "main.ts",
   "package.json",
   "server.ts",
-  "tsconfig.json"
+  "tsconfig.json",
+  "tsconfig.tsbuildinfo"
 ]);
 var appRootAllowedDirs = new Set([
   ".akan",
@@ -15556,7 +15557,8 @@ class AkanQualityScanner {
   #scanGlobalQuality(sourceFiles) {
     const exportedFunctionLikes = sourceFiles.flatMap((sourceFile2) => getExportedFunctionLikes(sourceFile2));
     const warnings = [];
-    for (const [name, declarations] of groupBy(exportedFunctionLikes, (declaration) => declaration.name)) {
+    const nameCheckedDeclarations = exportedFunctionLikes.filter((declaration) => !declaration.duplicateNameExempt);
+    for (const [name, declarations] of groupBy(nameCheckedDeclarations, (declaration) => declaration.name)) {
       if (declarations.length < 2)
         continue;
       warnings.push({
@@ -15710,6 +15712,7 @@ function formatQualityLocation(file, line) {
 }
 function getExportedFunctionLikes(sourceFile2) {
   const declarations = [];
+  const pageExempt = isPageRouteFile(sourceFile2.file);
   for (const statement of sourceFile2.sourceFile.statements) {
     if (ts11.isFunctionDeclaration(statement) && statement.name && isExported(statement)) {
       declarations.push({
@@ -15717,7 +15720,8 @@ function getExportedFunctionLikes(sourceFile2) {
         kind: "function",
         file: sourceFile2.file,
         line: getLine(sourceFile2.sourceFile, statement),
-        bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, statement.body)
+        bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, statement.body),
+        duplicateNameExempt: pageExempt || isConventionDuplicateNameExempt(sourceFile2.file, false)
       });
     }
     if (ts11.isClassDeclaration(statement) && statement.name && isExported(statement)) {
@@ -15726,7 +15730,8 @@ function getExportedFunctionLikes(sourceFile2) {
         kind: "class",
         file: sourceFile2.file,
         line: getLine(sourceFile2.sourceFile, statement),
-        bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, statement)
+        bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, statement),
+        duplicateNameExempt: pageExempt || isConventionDuplicateNameExempt(sourceFile2.file, isEnumClassStatement(sourceFile2.sourceFile, statement))
       });
     }
     if (ts11.isVariableStatement(statement) && isExported(statement)) {
@@ -15738,13 +15743,40 @@ function getExportedFunctionLikes(sourceFile2) {
           kind: "function-variable",
           file: sourceFile2.file,
           line: getLine(sourceFile2.sourceFile, declaration),
-          bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, declaration.initializer)
+          bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, declaration.initializer),
+          duplicateNameExempt: pageExempt || isConventionDuplicateNameExempt(sourceFile2.file, false)
         });
       }
     }
   }
   return declarations;
 }
+function isPageRouteFile(file) {
+  const segments = file.split("/");
+  return (segments[0] === "apps" || segments[0] === "libs") && segments[2] === "page";
+}
+function isConventionDuplicateNameExempt(file, isEnumClass) {
+  if (!isInLibModule(file))
+    return false;
+  if (file.endsWith(".tsx"))
+    return true;
+  if (file.endsWith(".document.ts") || file.endsWith(".service.ts") || file.endsWith(".signal.ts") || file.endsWith(".store.ts"))
+    return true;
+  if (file.endsWith(".constant.ts"))
+    return !isEnumClass;
+  return false;
+}
+function isInLibModule(file) {
+  const segments = file.split("/");
+  return (segments[0] === "apps" || segments[0] === "libs") && segments.includes("lib");
+}
+function isEnumClassStatement(sourceFile2, statement) {
+  if (!ts11.isClassDeclaration(statement))
+    return false;
+  const heritageClause = statement.heritageClauses?.find((clause) => clause.token === ts11.SyntaxKind.ExtendsKeyword);
+  const expression = heritageClause?.types[0]?.expression;
+  return !!expression && expression.getText(sourceFile2).startsWith("enumOf(");
+}
 function getExportedClassNames(sourceFile2) {
   return sourceFile2.statements.filter((statement) => ts11.isClassDeclaration(statement) && !!statement.name).filter((statement) => isExported(statement)).map((statement) => statement.name.text);
 }
@@ -15763,11 +15795,7 @@ function getPlaceholderExportWarnings(sourceFile2) {
 function getDictionaryTextWarnings(sourceFile2) {
   if (!sourceFile2.file.endsWith(".dictionary.ts"))
     return [];
-  const stalePatterns = [
-    { pattern: /\b[A-Z][A-Za-z0-9]* description\b/, label: "scaffold description text" },
-    { pattern: /settting/, label: "misspelling: settting" },
-    { pattern: /\uBC30\uB108 \uC218/, label: "stale copied Korean domain noun: \uBC30\uB108 \uC218" }
-  ];
+  const stalePatterns = [{ pattern: /\b[A-Z][A-Za-z0-9]* description\b/, label: "scaffold description text" }];
   return stalePatterns.flatMap(({ pattern, label }) => findPatternLines(sourceFile2.content, pattern).map((line) => ({
     rule: "akan.file.dictionary-stale-text",
     scope: "file",

package/index.js

@@ -1708,7 +1708,8 @@ var appRootAllowedFiles = new Set([
   "main.ts",
   "package.json",
   "server.ts",
-  "tsconfig.json"
+  "tsconfig.json",
+  "tsconfig.tsbuildinfo"
 ]);
 var appRootAllowedDirs = new Set([
   ".akan",
@@ -15554,7 +15555,8 @@ class AkanQualityScanner {
   #scanGlobalQuality(sourceFiles) {
     const exportedFunctionLikes = sourceFiles.flatMap((sourceFile2) => getExportedFunctionLikes(sourceFile2));
     const warnings = [];
-    for (const [name, declarations] of groupBy(exportedFunctionLikes, (declaration) => declaration.name)) {
+    const nameCheckedDeclarations = exportedFunctionLikes.filter((declaration) => !declaration.duplicateNameExempt);
+    for (const [name, declarations] of groupBy(nameCheckedDeclarations, (declaration) => declaration.name)) {
       if (declarations.length < 2)
         continue;
       warnings.push({
@@ -15708,6 +15710,7 @@ function formatQualityLocation(file, line) {
 }
 function getExportedFunctionLikes(sourceFile2) {
   const declarations = [];
+  const pageExempt = isPageRouteFile(sourceFile2.file);
   for (const statement of sourceFile2.sourceFile.statements) {
     if (ts11.isFunctionDeclaration(statement) && statement.name && isExported(statement)) {
       declarations.push({
@@ -15715,7 +15718,8 @@ function getExportedFunctionLikes(sourceFile2) {
         kind: "function",
         file: sourceFile2.file,
         line: getLine(sourceFile2.sourceFile, statement),
-        bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, statement.body)
+        bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, statement.body),
+        duplicateNameExempt: pageExempt || isConventionDuplicateNameExempt(sourceFile2.file, false)
       });
     }
     if (ts11.isClassDeclaration(statement) && statement.name && isExported(statement)) {
@@ -15724,7 +15728,8 @@ function getExportedFunctionLikes(sourceFile2) {
         kind: "class",
         file: sourceFile2.file,
         line: getLine(sourceFile2.sourceFile, statement),
-        bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, statement)
+        bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, statement),
+        duplicateNameExempt: pageExempt || isConventionDuplicateNameExempt(sourceFile2.file, isEnumClassStatement(sourceFile2.sourceFile, statement))
       });
     }
     if (ts11.isVariableStatement(statement) && isExported(statement)) {
@@ -15736,13 +15741,40 @@ function getExportedFunctionLikes(sourceFile2) {
           kind: "function-variable",
           file: sourceFile2.file,
           line: getLine(sourceFile2.sourceFile, declaration),
-          bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, declaration.initializer)
+          bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, declaration.initializer),
+          duplicateNameExempt: pageExempt || isConventionDuplicateNameExempt(sourceFile2.file, false)
         });
       }
     }
   }
   return declarations;
 }
+function isPageRouteFile(file) {
+  const segments = file.split("/");
+  return (segments[0] === "apps" || segments[0] === "libs") && segments[2] === "page";
+}
+function isConventionDuplicateNameExempt(file, isEnumClass) {
+  if (!isInLibModule(file))
+    return false;
+  if (file.endsWith(".tsx"))
+    return true;
+  if (file.endsWith(".document.ts") || file.endsWith(".service.ts") || file.endsWith(".signal.ts") || file.endsWith(".store.ts"))
+    return true;
+  if (file.endsWith(".constant.ts"))
+    return !isEnumClass;
+  return false;
+}
+function isInLibModule(file) {
+  const segments = file.split("/");
+  return (segments[0] === "apps" || segments[0] === "libs") && segments.includes("lib");
+}
+function isEnumClassStatement(sourceFile2, statement) {
+  if (!ts11.isClassDeclaration(statement))
+    return false;
+  const heritageClause = statement.heritageClauses?.find((clause) => clause.token === ts11.SyntaxKind.ExtendsKeyword);
+  const expression = heritageClause?.types[0]?.expression;
+  return !!expression && expression.getText(sourceFile2).startsWith("enumOf(");
+}
 function getExportedClassNames(sourceFile2) {
   return sourceFile2.statements.filter((statement) => ts11.isClassDeclaration(statement) && !!statement.name).filter((statement) => isExported(statement)).map((statement) => statement.name.text);
 }
@@ -15761,11 +15793,7 @@ function getPlaceholderExportWarnings(sourceFile2) {
 function getDictionaryTextWarnings(sourceFile2) {
   if (!sourceFile2.file.endsWith(".dictionary.ts"))
     return [];
-  const stalePatterns = [
-    { pattern: /\b[A-Z][A-Za-z0-9]* description\b/, label: "scaffold description text" },
-    { pattern: /settting/, label: "misspelling: settting" },
-    { pattern: /\uBC30\uB108 \uC218/, label: "stale copied Korean domain noun: \uBC30\uB108 \uC218" }
-  ];
+  const stalePatterns = [{ pattern: /\b[A-Z][A-Za-z0-9]* description\b/, label: "scaffold description text" }];
   return stalePatterns.flatMap(({ pattern, label }) => findPatternLines(sourceFile2.content, pattern).map((line) => ({
     rule: "akan.file.dictionary-stale-text",
     scope: "file",
@@ -16028,26 +16056,61 @@ var targetPaths = {
   "agents-md": "AGENTS.md",
   claude: "CLAUDE.md"
 };
-var targetTitle = {
-  cursor: "Akan Cursor Rules",
-  "agents-md": "Akan Agent Rules",
-  claude: "Akan Claude Rules"
+var AGENT_BLOCK_START = "<!-- akan:agent:start -->";
+var AGENT_BLOCK_END = "<!-- akan:agent:end -->";
+var SAMPLE_ARTIFACTS = [
+  { probe: "lib/task/task.constant.ts", target: "lib/task", label: "sample database module" },
+  { probe: "lib/_noti/noti.service.ts", target: "lib/_noti", label: "sample service module" },
+  {
+    probe: "lib/__scalar/workHistory/workHistory.dictionary.ts",
+    target: "lib/__scalar/workHistory",
+    label: "sample scalar module"
+  },
+  { probe: "page/task/_index.tsx", target: "page/task", label: "sample task pages" }
+];
+var DEFAULT_INDEX_MARKER = "Akan.js template";
+var renderSampleCleanup = async (workspace, appNames) => {
+  const items = [];
+  for (const appName of appNames) {
+    for (const artifact2 of SAMPLE_ARTIFACTS) {
+      if (await workspace.exists(`apps/${appName}/${artifact2.probe}`)) {
+        items.push(`- \`apps/${appName}/${artifact2.target}\` \u2014 ${artifact2.label}; delete it once you no longer need the reference.`);
+      }
+    }
+    const indexPath = `apps/${appName}/page/_index.tsx`;
+    if (await workspace.exists(indexPath)) {
+      const content = await workspace.readFile(indexPath).catch(() => "");
+      if (content.includes(DEFAULT_INDEX_MARKER)) {
+        items.push(`- \`${indexPath}\` \u2014 default Akan landing page; replace it with your own home page.`);
+      }
+    }
+  }
+  if (items.length === 0)
+    return "";
+  return `## Start Clean (Remove Scaffolded Samples)
+
+This workspace was scaffolded with reference samples so the Akan conventions are visible in real code. They are
+not part of your product. Before building real features, remove the samples below and run \`akan sync <app>\`:
+
+${items.join(`
+`)}
+
+Keep a sample only while you are still learning its pattern; delete it once your own modules cover the same ground.
+
+`;
 };
-var renderAgentRules = async (workspace, target) => {
+var renderManagedBlock = async (workspace) => {
   const context = await AkanContextAnalyzer.analyze(workspace);
   const frameworkGuide = await Prompter.getInstruction("framework");
-  return `# ${targetTitle[target]}
-
-This file is generated by \`akan agent install ${target}\`.
-
-## Workspace
+  const sampleCleanup = await renderSampleCleanup(workspace, context.apps.map((app) => app.name));
+  return `## Workspace
 
 - Repo: ${context.repoName}
 - Apps: ${context.apps.map((app) => app.name).join(", ") || "none"}
 - Libraries: ${context.libs.map((lib) => lib.name).join(", ") || "none"}
 - Packages: ${context.pkgs.map((pkg) => pkg.name).join(", ") || "none"}
 
-## Akan Module Abstracts
+${sampleCleanup}## Akan Module Abstracts
 
 - Before changing a domain, service, or scalar module, read its \`*.abstract.md\` file first.
 - Update the abstract when business invariants, workflows, or public behavior change.
@@ -16069,6 +16132,7 @@ If generated output is stale or broken, update the owning source file and run \`
 - After \`apply_workflow\`, run \`run_validation\` with \`validationTarget\` when present; otherwise use \`applyReportPath\`.
 - If no workflow exists, or apply reports unsupported/no-op/failed diagnostics that require manual action, keep edits scoped to owning source files and never patch generated files directly.
 - For compound requests, split the request into workflows and apply each \`planPath\` in order, such as \`create-module\` followed by \`add-field\`.
+- **CLI-only fallback (MCP not connected):** \`akan mcp\` starts a stdio MCP server, so the \`list_workflows\`/\`plan_workflow\`/\`apply_workflow\` tools exist only when your agent is wired to it as an MCP client. When they are unavailable, the CLI is a first-class equivalent: \`akan workflow list\` / \`explain <name>\` / \`plan <name> ... --format json --out <planPath>\` / \`apply <planPath> --format json\`, \`akan doctor --strict --format json\` for validation, and \`akan repair generated|imports|module-shape --app <app> --format json\` for repairs. Scaffolding primitives (\`create-module\`/\`create-scalar\`/\`create-service\` take the target app/lib as a POSITIONAL arg; \`add-field\`/\`add-enum-field\` use \`--app\`/\`--module\` flags) call the same code the workflows do.
 
 ## Validation
 
@@ -16077,8 +16141,61 @@ ${context.validationCommands.map((command3) => `- \`${command3}\``).join(`
 
 ## Framework Guide
 
-${frameworkGuide.trim()}
+${frameworkGuide.trim()}`;
+};
+var upsertManagedBlock = (existing, block) => {
+  const managed = `${AGENT_BLOCK_START}
+${block}
+${AGENT_BLOCK_END}`;
+  const startIndex = existing.indexOf(AGENT_BLOCK_START);
+  const endIndex = existing.indexOf(AGENT_BLOCK_END);
+  if (startIndex >= 0 && endIndex > startIndex) {
+    return `${existing.slice(0, startIndex)}${managed}${existing.slice(endIndex + AGENT_BLOCK_END.length)}`;
+  }
+  return `${existing.replace(/\s*$/, "")}
+
+${managed}
+`;
+};
+var renderAgentsMd = async (workspace, existing) => {
+  const block = await renderManagedBlock(workspace);
+  if (existing?.trim())
+    return upsertManagedBlock(existing, block);
+  const context = await AkanContextAnalyzer.analyze(workspace);
+  return `# ${context.repoName} Agent Guide
+
+This file is the single source of truth for coding agents in this workspace. Claude Code reads it through
+\`CLAUDE.md\` (\`@AGENTS.md\`) and Cursor through \`.cursor/rules/akan.mdc\`. The section between the
+\`akan:agent\` markers is regenerated by \`akan agent install\`; edit anything outside the markers freely.
+
+${AGENT_BLOCK_START}
+${block}
+${AGENT_BLOCK_END}
+`;
+};
+var renderClaudeMd = async (workspace) => {
+  const context = await AkanContextAnalyzer.analyze(workspace);
+  return `# ${context.repoName} \u2014 Claude Code Guide
+
+@AGENTS.md
+`;
+};
+var renderCursorRule = () => `---
+description: Akan workspace agent guide
+alwaysApply: true
+---
+
+Follow the workspace agent guide, which is the single source of truth for Akan conventions,
+generated-file rules, and the MCP workflow policy.
+
+@AGENTS.md
 `;
+var renderTarget = async (workspace, target, existing) => {
+  if (target === "agents-md")
+    return await renderAgentsMd(workspace, existing);
+  if (target === "claude")
+    return await renderClaudeMd(workspace);
+  return renderCursorRule();
 };
 
 class AgentRunner extends runner("agent") {
@@ -16086,11 +16203,13 @@ class AgentRunner extends runner("agent") {
     const written = [];
     for (const target of targets) {
       const filePath = targetPaths[target];
-      if (!force && await workspace.exists(filePath)) {
+      const exists2 = await workspace.exists(filePath);
+      if (exists2 && !force && target !== "agents-md") {
         throw new Error(`${filePath} already exists. Re-run with --force to overwrite it.`);
       }
-      const content = await renderAgentRules(workspace, target);
-      await workspace.writeFile(filePath, content, { overwrite: force });
+      const existing = exists2 ? await workspace.readFile(filePath) : null;
+      const content = await renderTarget(workspace, target, existing);
+      await workspace.writeFile(filePath, content, { overwrite: true });
       written.push(filePath);
     }
     return written;
@@ -21439,6 +21558,7 @@ import path48 from "path";
 var defaultWorkspacePeerDependencies = new Set([
   "@react-spring/web",
   "@use-gesture/react",
+  "chance",
   "croner",
   "daisyui",
   "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "2.3.11-rc.4",
+  "version": "2.3.11-rc.6",
   "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.11-rc.4",
+    "akanjs": "2.3.11-rc.6",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/templates/appSample/lib/task/Task.Zone.tsx

@@ -4,12 +4,10 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { a
   return {
     filename: "Task.Zone.tsx",
     content: `"use client";
-import { Task, usePage } from "@apps/${dict.appName}/client";
+import { type cnst, Task, usePage } from "@apps/${dict.appName}/client";
 import type { ClientInit, ClientView } from "akanjs/fetch";
 import { Link, Load } from "akanjs/ui";
 
-import * as cnst from "../cnst";
-
 // ===== Task.Zone.tsx =====
 // Convention: lib/<module>/ — PascalCase .tsx, Zone suffix = composition layer between pages and UI.
 // Zone components use Load.Units / Load.View from akanjs/ui — the framework convention for data-bound zones.

package/templates/crudPages/[__model__Id]/edit/page.tsx

@@ -10,14 +10,14 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: Dic
     filename: "_index.tsx",
     content: `
 import { Load } from "akanjs/ui";
-import { fetch, usePage, ${dict.Model} } from "${dict.appName}/client";
+import { fetch, usePage, ${dict.Model} } from "@apps/${dict.appName}/client";
 import type { PageConfig } from "akanjs/client";
 
 interface PageProps {
   params: { ${dict.model}Id: string };
 }
 
-export default function Page({ params }: PageProps) {
+export default async function Page({ params }: PageProps) {
   const { l } = usePage();
   const { ${dict.model}Id } = params;
   const { ${dict.model}, ${dict.model}Edit } = await fetch.edit${dict.Model}(${dict.model}Id);

package/templates/crudPages/[__model__Id]/page.tsx

@@ -9,8 +9,8 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: Dic
   return {
     filename: "_index.tsx",
     content: `
-import { ${dict.Model}, fetch, usePage } from "${dict.appName}/client";
-import { Link, Load } from "akanjs/ui";
+import { ${dict.Model}, fetch, usePage } from "@apps/${dict.appName}/client";
+import { Link } from "akanjs/ui";
 import type { PageConfig } from "akanjs/client";
 
 interface PageProps {
@@ -29,7 +29,7 @@ export async function generateHead({ params }: PageProps) {
     </>
   );
 }
-export default function Page({ params }: PageProps) {
+export default async function Page({ params }: PageProps) {
   const { l } = usePage();
   const { ${dict.model}Id } = params;
   const { ${dict.model}, ${dict.model}View } = await fetch.view${dict.Model}(${dict.model}Id);

package/templates/crudPages/page.tsx

@@ -10,10 +10,10 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: Dic
     filename: "_index.tsx",
     content: `
 import { ${dict.Model}, fetch, usePage } from "@apps/${dict.appName}/client";
-import { Link, Load } from "akanjs/ui";
+import { Link } from "akanjs/ui";
 import type { PageConfig } from "akanjs/client";
 
-export default function Page() {
+export default async function Page() {
   const { l } = usePage();
   const { ${dict.model}InitInPublic } = await fetch.init${dict.Model}InPublic();
   return (

package/templates/crudSinglePage/page.tsx

@@ -10,10 +10,10 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: Dic
     filename: "_index.tsx",
     content: `
 import type { PageConfig } from "akanjs/client";
-import { Load, Model } from "akanjs/ui";
-import { ${dict.Model}, type cnst, fetch, usePage } from "@apps/${dict.appName}/client";
+import { Model } from "akanjs/ui";
+import { ${dict.Model}, fetch, usePage } from "@apps/${dict.appName}/client";
 
-export default function Page() {
+export default async function Page() {
   const { l } = usePage();
   const { ${dict.model}InitInPublic } = await fetch.init${dict.Model}InPublic();
   return (

package/templates/module/__Model__.Zone.tsx

@@ -11,7 +11,7 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: Dic
     content: `
 "use client";
 import { Load } from "akanjs/ui";
-import { cnst, ${dict.Model} } from "@${scanInfo?.type ?? "apps"}/${dict.sysName}/client";
+import { type cnst, ${dict.Model} } from "@${scanInfo?.type ?? "apps"}/${dict.sysName}/client";
 import type { ClientInit, ClientView, SliceMeta } from "akanjs/fetch";
 
 interface CardProps {

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

@@ -1,38 +1,9 @@
 ---
-description: Akan.js workspace conventions for coding agents
+description: Akan workspace agent guide
 alwaysApply: true
 ---
 
-# Akan.js Workspace Rules
+Follow the workspace agent guide, which is the single source of truth for Akan conventions,
+generated-file rules, and the MCP workflow policy.
 
-- Keep edits inside the established Akan structure: `apps/<app>`, `libs/<lib>`, `pkgs/*`, and `infra`.
-- Pages live under `apps/<app>/page`; index routes use `_index.tsx`, and nested layouts use `_layout.tsx`.
-- Database domain modules live under `lib/<model>`.
-- Service modules live under `lib/_<service>`.
-- Scalar modules live under `lib/__scalar/<scalar>`.
-- Module abstracts live beside module code as `<model>.abstract.md`, `<service>.abstract.md`, or
-  `<scalar>.abstract.md`. Read them before changing module behavior.
-- 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.
-- If `plan_workflow` returns `planPath` or `next.tool=apply_workflow`, call `apply_workflow({ planPath })` before
-  editing source files directly.
-- After `apply_workflow`, run `run_validation` with `validationTarget` when present; otherwise use `applyReportPath`.
-- Direct source edits are denied when an allowlisted Akan workflow or repair tool can perform the change.
-- Direct edits are fallback only after `list_workflows`/`explain_workflow` show no matching workflow, or after
-  `apply_workflow` reports unsupported/no-op/failed diagnostics that require manual action.
-- For compound requests, split the request into workflows and apply each `planPath` in order, such as `create-module`
-  followed by `add-field`.
-- 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
-  formatting-only, import-only, or style-only changes.
-- Respect server/client import boundaries. Use `akanjs/server` only in server-side code and `akanjs/client` only in
-  client/page runtime code.
-- Treat `AKAN_PUBLIC_*` env vars as public values. Do not store secrets in them.
-- Verify changes with the smallest relevant command: `akan lint <target>`, `akan test <target>`, or
-  `akan build <app-name>`.
+@AGENTS.md

package/templates/workspaceRoot/AGENTS.md.template

@@ -87,7 +87,8 @@ When adding a new database-backed domain module (e.g., product, user):
 
 ```bash
 # 1. Scaffold the module with Akan CLI (creates constant, service, signal, store, document files)
-akan create-module <module-name> --app <%= appName %>
+# The target app/lib is a POSITIONAL argument, not a --app flag.
+akan create-module <module-name> <%= appName %>
 
 # 2. Start dev server with HMR and type checking at http://localhost:8282
 akan start <%= appName %>
@@ -114,12 +115,32 @@ akan build <%= appName %>
 ### Other Frequently Used Commands
 
 ```bash
-akan create-scalar <scalar-name> --app <%= appName %>    # Add a scalar module (lib/__scalar/<scalar-name>/)
-akan create-service <service-name> --app <%= appName %>       # Add a service module (lib/_<service-name>/)
+akan create-scalar <scalar-name> <%= appName %>          # Add a scalar module (lib/__scalar/<scalar-name>/)
+akan create-service <service-name> <%= appName %>        # Add a service module (lib/_<service-name>/)
 akan test <%= appName %>                             # Run the test code (lib/*/*.signal.test.ts or others)
 akan lint <%= appName %>                             # Lint only (no typecheck)
 ```
 
+**CLI argument conventions.** Two argument styles, and mixing them up is a common mistake:
+
+- Scaffolding and whole-app commands take the target app/lib as a **positional** argument, not a flag:
+
+  ```bash
+  akan create-module photo <%= appName %>
+  akan create-scalar money <%= appName %>
+  akan create-service billing <%= appName %>
+  akan sync <%= appName %>
+  ```
+
+- Only the source-limited field commands use `--app`/`--module` flags:
+
+  ```bash
+  akan add-field --app <%= appName %> --module photo --field width --type Int
+  akan add-enum-field --app <%= appName %> --module photo --field status --values draft,active
+  ```
+
+Passing `--app` to `create-module` is not recognized, and the target app will not resolve.
+
 For the default generated app, start with:
 
 ```bash
@@ -130,6 +151,11 @@ akan start <%= appName %>
 
 Almost every Akan.js change follows this pattern. **Missing sync or repair is the #1 cause of agent confusion.**
 
+> **If the Akan MCP tools are not connected in your agent, skip straight to the CLI-only fallback below.**
+> `akan mcp --mode plan/apply` starts a stdio MCP server that only works when your agent is wired to it as an
+> MCP client. When those `list_workflows` / `plan_workflow` / `apply_workflow` tools are not available, the CLI
+> commands are a fully supported, first-class path — you are not losing any capability by using them.
+
 1. **Plan** — Ask the Akan MCP server for the workflow first.
    ```
    akan mcp --mode plan
@@ -171,12 +197,31 @@ Almost every Akan.js change follows this pattern. **Missing sync or repair is th
 
    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
+   - Re-run `akan create-module <name> <%= appName %>` if the scaffold is corrupted
 
 For compound natural-language requests, split the request into workflows and apply each artifact in order. For example,
 "create a project module and add a budget field" should run `create-module` plan/apply first, then `add-field`
 plan/apply, then validation/doctor on the returned `validationTarget`.
 
+### CLI-Only Fallback (MCP Not Connected)
+
+When the Akan MCP tools are not loaded, run the CLI commands directly. Each MCP tool maps 1:1 to a CLI command,
+and the CLI emits the same structured report via `--format json`:
+
+| MCP tool | CLI-only equivalent |
+|----------|---------------------|
+| `list_workflows` | `akan workflow list` |
+| `explain_workflow <name>` | `akan workflow explain <name>` |
+| `plan_workflow <name> ...` | `akan workflow plan <name> ... --format json --out <planPath>` |
+| `apply_workflow { planPath }` | `akan workflow apply <planPath> --format json` (add `--dry-run` to preview) |
+| `run_validation { validationTarget }` | `akan doctor --strict --format json` (or `akan typecheck <%= appName %>`) |
+| `repair_generated` / `repair_imports` / `repair_module_shape` | `akan repair generated\|imports\|module-shape --app <%= appName %> --format json` |
+
+The scaffolding primitives (`akan create-module`, `akan create-scalar`, `akan create-service`, `akan add-field`,
+`akan add-enum-field`) are the same primitives the workflows call, so `create-module <name> <%= appName %>` followed
+by `akan sync <%= appName %>` is equivalent to running the `create-module` workflow. Direct source edits remain the
+final fallback when no CLI command covers the change.
+
 ## Quick Decision Matrix — "Where do I put this code?"
 
 | You want to... | Create in... | Run after... |
@@ -289,7 +334,9 @@ const form = st.use.taskForm();
 
 ### Recipe 2: Injecting a Dependency into a Service
 
-Two patterns: injecting an **adapter** (external client) or injecting another **module's service**.
+Three patterns: injecting an **external adapter** (`use<>()`), another **module's service** (`service<>()`),
+or a **predefined framework adapter** (`plug()`). A field named `<refName>Service` resolves to the service
+registered under `<refName>` — the `Service`/`Signal` suffix is required and stripped to derive the lookup key.
 
 **A. Adapter injection via `use<>()` (for external clients / global singletons)**
 
@@ -332,6 +379,32 @@ export class TaskService extends serve(db.task, ({ service }) => ({
 }
 ```
 
+**C. Predefined framework adapter injection via `plug()` (storage, cache, queue, schedule, …)**
+
+Akan ships predefined adapter roles from `akanjs/service`: `StorageAdaptorRole`, `CacheAdaptorRole`,
+`QueueAdaptorRole`, `ScheduleAdaptorRole`, `DatabaseAdaptorRole`, `WebsocketAdaptorRole`,
+`LoggingAdaptorRole`, `CompressAdaptorRole`. `plug()` injects the concrete adapter bound to that role (the
+default `StorageAdaptor` binding is `BlobStorage`). `plug()` also accepts a concrete adapter class directly.
+
+```typescript
+// In <model>.service.ts — inject the framework storage adapter by role
+import { plug, serve, StorageAdaptorRole } from "akanjs/service";
+
+export class TaskService extends serve(db.task, ({ plug }) => ({
+  storage: plug(StorageAdaptorRole),
+})) {
+  async attach(taskId: string, path: string, localPath: string) {
+    // BlobStorage returns a URL under blobStorage.urlPrefix (default "/api/localFile/getBlob").
+    return await this.storage.uploadDataFromLocal({ path, localPath });
+  }
+}
+```
+
+For a custom adapter class (not a predefined role), pass the class itself, e.g. `ipfsApi: plug(IpfsApi)`
+(see `libs/shared/lib/file/file.service.ts`). Injecting a file/image field is usually simpler than calling
+storage directly: declare `image: field(File).optional()` (or `images: field([File])`) on the model and let the
+store's generated `upload<Field>On<Model>(fileList)` action handle the upload.
+
 ---
 
 ### Recipe 3: Creating and Using a Slice
@@ -576,3 +649,13 @@ akan sync automatically generates APIs across all layers. Only write custom logi
 | `insight[Query](args)`, `query[Query](args)` | Insight and raw query |
 
 **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.
+
+## Generated Context
+
+The section below is regenerated by `akan agent install` (run `bun run setup:agent`). It lists this
+workspace's apps, generated files, validation commands, and framework guide. Edit anything outside the
+markers freely; content between them is overwritten on the next install.
+
+<!-- akan:agent:start -->
+<!-- Populated by `akan agent install`. Run `bun run setup:agent` to refresh. -->
+<!-- akan:agent:end -->

package/templates/workspaceRoot/biome.json.template

@@ -50,7 +50,8 @@
       "!!**/dist",
       "!!**/.akan",
       "!!**/dump",
-      "!!**/local"
+      "!!**/local",
+      "!!**/ios/DerivedData"
     ]
   },
   "formatter": {