@akanjs/cli 2.3.11-rc.5 → 2.3.11-rc.7

package/incrementalBuilder.proc.js

@@ -3577,6 +3577,8 @@ class AppExecutor extends SysExecutor {
       ...routeEnv,
       ...devPort ? { PORT: devPort, AKAN_PUBLIC_CLIENT_PORT: devPort, AKAN_PUBLIC_SERVER_PORT: devPort } : {}
     });
+    if (type === "build")
+      Object.assign(process.env, env);
     return { env };
   }
   #publicEnv = null;
@@ -4996,7 +4998,6 @@ var workflowSyncStatePath = (target) => `${workflowSyncDir}/${syncStateSlug(targ
 var generatedFilePathsForTarget = (targetRoot, reason = "Generated files were refreshed by sync.") => [
   { path: `${targetRoot}/lib/cnst.ts`, action: "sync", reason },
   { path: `${targetRoot}/lib/dict.ts`, action: "sync", reason },
-  { path: `${targetRoot}/lib/option.ts`, action: "sync", reason },
   { path: `${targetRoot}/lib/index.ts`, action: "sync", reason }
 ];
 var writeGeneratedSyncState = async (workspace, state) => {
@@ -7650,13 +7651,59 @@ var resourceList = [
   { uri: "akan://workspace/modules", name: "Workspace modules", mimeType: "application/json" }
 ];
 var cursorMcpConfigPath = ".cursor/mcp.json";
+var claudeMcpConfigPath = ".mcp.json";
+var codexMcpConfigPath = ".codex/config.toml";
+var akanMcpInstallTargets = ["cursor", "claude", "codex"];
+var akanMcpInstallConfigPaths = {
+  cursor: cursorMcpConfigPath,
+  claude: claudeMcpConfigPath,
+  codex: codexMcpConfigPath
+};
 var cursorWorkspaceFolder = "$" + "{workspaceFolder}";
+var claudeProjectDir = "$CLAUDE_PROJECT_DIR";
+var akanMcpCommand = (mode, { cd } = {}) => cd ? `cd "${cd}" && akan mcp --mode ${mode}` : `akan mcp --mode ${mode}`;
 var createAkanCursorMcpServer = (mode = "readonly") => ({
   type: "stdio",
   command: "bash",
-  args: ["-lc", `cd "${cursorWorkspaceFolder}" && akan mcp --mode ${mode}`]
+  args: ["-lc", akanMcpCommand(mode, { cd: cursorWorkspaceFolder })]
+});
+var createAkanClaudeMcpServer = (mode = "readonly") => ({
+  type: "stdio",
+  command: "bash",
+  args: ["-lc", akanMcpCommand(mode, { cd: claudeProjectDir })]
 });
+var createAkanMcpServer = (target, mode = "readonly") => target === "cursor" ? createAkanCursorMcpServer(mode) : createAkanClaudeMcpServer(mode);
 var akanCursorMcpServer = createAkanCursorMcpServer();
+var codexMcpServerTableHeader = "[mcp_servers.akan]";
+var createAkanCodexMcpServerBlock = (mode = "readonly") => `${codexMcpServerTableHeader}
+command = "bash"
+args = ["-lc", "${akanMcpCommand(mode)}"]
+`;
+var codexAkanTablePattern = /^\[mcp_servers\.akan\][^\n]*\n(?:(?!\[)[^\n]*(?:\n|$))*/m;
+var upsertCodexMcpServerBlock = (existing, block, { force = false } = {}) => {
+  const nextBlock = block.endsWith(`
+`) ? block : `${block}
+`;
+  const match = existing.match(codexAkanTablePattern);
+  if (!match) {
+    if (!existing.trim())
+      return nextBlock;
+    return `${existing.replace(/\s*$/, "")}
+
+${nextBlock}`;
+  }
+  if (match[0].trim() === nextBlock.trim())
+    return existing;
+  if (!force)
+    throw new Error(`${codexMcpConfigPath} already has an "akan" MCP server. Re-run with --force to overwrite it.`);
+  const start = match.index ?? 0;
+  const before = existing.slice(0, start);
+  const after = existing.slice(start + match[0].length);
+  const separator = after && !after.startsWith(`
+`) ? `
+` : "";
+  return `${before}${nextBlock}${separator}${after}`;
+};
 var renderDoctorText = (result) => {
   const lines = [`Akan doctor status: ${result.status}`];
   if (result.diagnostics.length === 0) {
@@ -7679,7 +7726,6 @@ var generatedFiles = [
   "*/lib/cnst.ts",
   "*/lib/db.ts",
   "*/lib/dict.ts",
-  "*/lib/option.ts",
   "*/lib/sig.ts",
   "*/lib/srv.ts",
   "*/lib/st.ts",
@@ -15557,7 +15603,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({
@@ -15711,6 +15758,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({
@@ -15718,7 +15766,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)) {
@@ -15727,7 +15776,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)) {
@@ -15739,13 +15789,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);
 }
@@ -15764,11 +15841,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

@@ -3575,6 +3575,8 @@ class AppExecutor extends SysExecutor {
       ...routeEnv,
       ...devPort ? { PORT: devPort, AKAN_PUBLIC_CLIENT_PORT: devPort, AKAN_PUBLIC_SERVER_PORT: devPort } : {}
     });
+    if (type === "build")
+      Object.assign(process.env, env);
     return { env };
   }
   #publicEnv = null;
@@ -4994,7 +4996,6 @@ var workflowSyncStatePath = (target) => `${workflowSyncDir}/${syncStateSlug(targ
 var generatedFilePathsForTarget = (targetRoot, reason = "Generated files were refreshed by sync.") => [
   { path: `${targetRoot}/lib/cnst.ts`, action: "sync", reason },
   { path: `${targetRoot}/lib/dict.ts`, action: "sync", reason },
-  { path: `${targetRoot}/lib/option.ts`, action: "sync", reason },
   { path: `${targetRoot}/lib/index.ts`, action: "sync", reason }
 ];
 var writeGeneratedSyncState = async (workspace, state) => {
@@ -7648,13 +7649,59 @@ var resourceList = [
   { uri: "akan://workspace/modules", name: "Workspace modules", mimeType: "application/json" }
 ];
 var cursorMcpConfigPath = ".cursor/mcp.json";
+var claudeMcpConfigPath = ".mcp.json";
+var codexMcpConfigPath = ".codex/config.toml";
+var akanMcpInstallTargets = ["cursor", "claude", "codex"];
+var akanMcpInstallConfigPaths = {
+  cursor: cursorMcpConfigPath,
+  claude: claudeMcpConfigPath,
+  codex: codexMcpConfigPath
+};
 var cursorWorkspaceFolder = "$" + "{workspaceFolder}";
+var claudeProjectDir = "$CLAUDE_PROJECT_DIR";
+var akanMcpCommand = (mode, { cd } = {}) => cd ? `cd "${cd}" && akan mcp --mode ${mode}` : `akan mcp --mode ${mode}`;
 var createAkanCursorMcpServer = (mode = "readonly") => ({
   type: "stdio",
   command: "bash",
-  args: ["-lc", `cd "${cursorWorkspaceFolder}" && akan mcp --mode ${mode}`]
+  args: ["-lc", akanMcpCommand(mode, { cd: cursorWorkspaceFolder })]
+});
+var createAkanClaudeMcpServer = (mode = "readonly") => ({
+  type: "stdio",
+  command: "bash",
+  args: ["-lc", akanMcpCommand(mode, { cd: claudeProjectDir })]
 });
+var createAkanMcpServer = (target, mode = "readonly") => target === "cursor" ? createAkanCursorMcpServer(mode) : createAkanClaudeMcpServer(mode);
 var akanCursorMcpServer = createAkanCursorMcpServer();
+var codexMcpServerTableHeader = "[mcp_servers.akan]";
+var createAkanCodexMcpServerBlock = (mode = "readonly") => `${codexMcpServerTableHeader}
+command = "bash"
+args = ["-lc", "${akanMcpCommand(mode)}"]
+`;
+var codexAkanTablePattern = /^\[mcp_servers\.akan\][^\n]*\n(?:(?!\[)[^\n]*(?:\n|$))*/m;
+var upsertCodexMcpServerBlock = (existing, block, { force = false } = {}) => {
+  const nextBlock = block.endsWith(`
+`) ? block : `${block}
+`;
+  const match = existing.match(codexAkanTablePattern);
+  if (!match) {
+    if (!existing.trim())
+      return nextBlock;
+    return `${existing.replace(/\s*$/, "")}
+
+${nextBlock}`;
+  }
+  if (match[0].trim() === nextBlock.trim())
+    return existing;
+  if (!force)
+    throw new Error(`${codexMcpConfigPath} already has an "akan" MCP server. Re-run with --force to overwrite it.`);
+  const start = match.index ?? 0;
+  const before = existing.slice(0, start);
+  const after = existing.slice(start + match[0].length);
+  const separator = after && !after.startsWith(`
+`) ? `
+` : "";
+  return `${before}${nextBlock}${separator}${after}`;
+};
 var renderDoctorText = (result) => {
   const lines = [`Akan doctor status: ${result.status}`];
   if (result.diagnostics.length === 0) {
@@ -7677,7 +7724,6 @@ var generatedFiles = [
   "*/lib/cnst.ts",
   "*/lib/db.ts",
   "*/lib/dict.ts",
-  "*/lib/option.ts",
   "*/lib/sig.ts",
   "*/lib/srv.ts",
   "*/lib/st.ts",
@@ -15555,7 +15601,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({
@@ -15709,6 +15756,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({
@@ -15716,7 +15764,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)) {
@@ -15725,7 +15774,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)) {
@@ -15737,13 +15787,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);
 }
@@ -15762,11 +15839,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",
@@ -16031,9 +16104,51 @@ var targetPaths = {
 };
 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 renderManagedBlock = async (workspace) => {
   const context = await AkanContextAnalyzer.analyze(workspace);
   const frameworkGuide = await Prompter.getInstruction("framework");
+  const sampleCleanup = await renderSampleCleanup(workspace, context.apps.map((app) => app.name));
   return `## Workspace
 
 - Repo: ${context.repoName}
@@ -16041,7 +16156,7 @@ var renderManagedBlock = async (workspace) => {
 - 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.
@@ -16063,6 +16178,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
 
@@ -18022,8 +18138,7 @@ var addEnumFieldWorkflowSpec = {
   predictedChanges: [
     { target: "*/lib/<module>/<module>.constant.ts", action: "modify", reason: "Enum field shape is added." },
     { target: "*/lib/<module>/<module>.dictionary.ts", action: "modify", reason: "Enum labels are added." },
-    { target: "*/lib/<module>/<module>.option.ts", action: "modify", reason: "Enum options may be added." },
-    { target: "*/lib/option.ts", action: "sync", reason: "Generated option barrel may change after sync." }
+    { target: "*/lib/<module>/<module>.option.ts", action: "modify", reason: "Enum options may be added." }
   ],
   validation: [
     ...baseValidation,
@@ -18428,8 +18543,7 @@ var createScalarWorkflowSpec = {
     }
   ],
   predictedChanges: [
-    { target: "*/lib/__scalar/<scalar>/*", action: "create", reason: "New scalar source files are scaffolded." },
-    { target: "*/lib/option.ts", action: "sync", reason: "Generated option barrel may include scalar options." }
+    { target: "*/lib/__scalar/<scalar>/*", action: "create", reason: "New scalar source files are scaffolded." }
   ],
   validation: baseValidation,
   completionCriteria: ["Scalar files exist under __scalar.", "Generated files are refreshed.", "Lint passes."]
@@ -20300,14 +20414,18 @@ class ContextRunner extends runner("context") {
     return await Prompter.getInstruction(name);
   }
   async installMcp(workspace, target, { force = false, mode = "readonly" } = {}) {
-    if (target !== "cursor")
-      throw new Error(`Unknown MCP install target: ${target}. Use cursor.`);
-    const existing = await workspace.exists(cursorMcpConfigPath) ? await workspace.readJson(cursorMcpConfigPath) : {};
+    if (target === "codex")
+      return await this.#installCodexMcp(workspace, { force, mode });
+    return await this.#installJsonMcp(workspace, target, { force, mode });
+  }
+  async#installJsonMcp(workspace, target, { force, mode }) {
+    const configPath2 = akanMcpInstallConfigPaths[target];
+    const existing = await workspace.exists(configPath2) ? await workspace.readJson(configPath2) : {};
     const mcpServers = existing.mcpServers ?? {};
     const currentAkanServer = mcpServers.akan;
-    const nextAkanServer = createAkanCursorMcpServer(mode);
+    const nextAkanServer = createAkanMcpServer(target, mode);
     if (currentAkanServer && !force && JSON.stringify(currentAkanServer) !== JSON.stringify(nextAkanServer)) {
-      throw new Error(`${cursorMcpConfigPath} already has an "akan" MCP server. Re-run with --force to overwrite it.`);
+      throw new Error(`${configPath2} already has an "akan" MCP server. Re-run with --force to overwrite it.`);
     }
     const nextConfig = {
       ...existing,
@@ -20316,9 +20434,15 @@ class ContextRunner extends runner("context") {
         akan: nextAkanServer
       }
     };
-    await workspace.writeFile(cursorMcpConfigPath, `${JSON.stringify(nextConfig, null, 2)}
+    await workspace.writeFile(configPath2, `${JSON.stringify(nextConfig, null, 2)}
 `);
-    return cursorMcpConfigPath;
+    return configPath2;
+  }
+  async#installCodexMcp(workspace, { force, mode }) {
+    const existing = await workspace.exists(codexMcpConfigPath) ? await workspace.readFile(codexMcpConfigPath) : "";
+    const merged = upsertCodexMcpServerBlock(existing, createAkanCodexMcpServerBlock(mode), { force });
+    await workspace.writeFile(codexMcpConfigPath, merged);
+    return codexMcpConfigPath;
   }
   listMcpTools(mode = "readonly") {
     return listAkanMcpTools(mode);
@@ -20610,13 +20734,26 @@ ${payload}`);
       agent: "`akan agent install <target>` writes editor-specific agent rules with overwrite protection.",
       mcp: "`akan mcp --mode readonly|plan|apply` starts the Akan MCP server over stdio with an explicit permission mode.",
       "mcp-call": '`akan mcp-call <tool> --mode plan --args \'{"workflow":"add-field","inputs":{"app":"demo"}}\'` calls one MCP tool through the same runner path for debugging.',
-      "mcp-install": "`akan mcp-install cursor --mode readonly|plan|apply` installs the Akan MCP server config for Cursor."
+      "mcp-install": "`akan mcp-install [cursor|claude|codex|all] --mode readonly|plan|apply` installs the Akan MCP server config for Cursor (.cursor/mcp.json), Claude Code (.mcp.json), and Codex (.codex/config.toml). Defaults to all targets."
     };
     return explanations[command3] ?? `No detailed explanation is available for ${command3}. Run \`akan --help\` for command help.`;
   }
 }
 
 // pkgs/@akanjs/cli/context/context.script.ts
+var resolveMcpInstallTargets = (target) => {
+  if (!target || target === "all")
+    return [...akanMcpInstallTargets];
+  if (akanMcpInstallTargets.includes(target))
+    return [target];
+  throw new Error(`Unknown MCP install target: ${target}. Use cursor, claude, codex, or all.`);
+};
+var mcpTargetLabels = {
+  cursor: "Cursor",
+  claude: "Claude Code",
+  codex: "Codex"
+};
+
 class ContextScript extends script("context", [ContextRunner]) {
   async context(workspace, options = {}) {
     Logger17.rawLog(await this.contextRunner.getContext(workspace, options));
@@ -20625,11 +20762,15 @@ class ContextScript extends script("context", [ContextRunner]) {
     Logger17.rawLog(await this.contextRunner.doctor(workspace, options));
   }
   async mcpInstall(workspace, target, { force = false, mode = "readonly" } = {}) {
-    if (target && target !== "cursor")
-      throw new Error(`Unknown MCP install target: ${target}. Use cursor.`);
-    const written = await this.contextRunner.installMcp(workspace, "cursor", { force, mode });
-    Logger17.rawLog(`Akan MCP server installed for Cursor:
-- ${written}`);
+    const targets = resolveMcpInstallTargets(target);
+    const written = [];
+    for (const t of targets) {
+      const configPath2 = await this.contextRunner.installMcp(workspace, t, { force, mode });
+      written.push(`${mcpTargetLabels[t]}: ${configPath2}`);
+    }
+    Logger17.rawLog(`Akan MCP server installed (${mode} mode):
+${written.map((line) => `- ${line}`).join(`
+`)}`);
   }
   async mcp(workspace, { mode = "readonly" } = {}) {
     await this.contextRunner.runMcp(workspace, { mode });
@@ -20668,7 +20809,7 @@ class ContextCommand extends command("context", [ContextScript], ({ public: targ
   }).option("strict", Boolean, { desc: "treat recommended conventions as errors", default: false }).with(Workspace).exec(async function(format, strict, workspace) {
     await this.contextScript.doctor(workspace, { format, strict });
   }),
-  mcpInstall: target({ desc: "Install the Akan MCP server config for Cursor" }).arg("target", String, { desc: "cursor", nullable: true }).option("force", Boolean, { desc: "overwrite an existing Akan MCP server entry", default: false }).option("mode", String, {
+  mcpInstall: target({ desc: "Install the Akan MCP server config for Cursor, Claude Code, and Codex" }).arg("target", String, { desc: "cursor, claude, codex, or all", nullable: true }).option("force", Boolean, { desc: "overwrite an existing Akan MCP server entry", default: false }).option("mode", String, {
     desc: "MCP permission mode",
     default: "readonly",
     enum: ["readonly", "plan", "apply"]
@@ -21488,6 +21629,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.5",
+  "version": "2.3.11-rc.7",
   "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.5",
+    "akanjs": "2.3.11-rc.7",
     "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/appSample/lib/task/task.service.ts

@@ -10,7 +10,7 @@ import * as db from "../db";
 // 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 sync (do not write manually):
-//   getTask(id), createModel(data), updateModel(id, data), removeModel(id),
+//   getTask(id), createTask(data), updateTask(id, data), removeTask(id),
 //   listByStatus(status), searchDocs(text), and all filter+query methods from document.ts.
 // Manual below: lifecycle hooks, custom business logic methods.
 // Registered by akan sync into srv.ts barrel.

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__.Template.tsx

@@ -11,7 +11,7 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: Dic
     content: `
 "use client";
 import { Field, Layout } from "akanjs/ui";
-import { cnst, st, usePage } from "@${scanInfo?.type ?? "apps"}/${dict.sysName}/client";
+import { st, usePage } from "@${scanInfo?.type ?? "apps"}/${dict.sysName}/client";
 
 interface GeneralProps {
   className?: string;
@@ -23,10 +23,9 @@ export const General = ({ className }: GeneralProps) => {
   return (
     <Layout.Template className={className}>
       <Field.Text
-        label={l("${dict.model}.id")}
-        desc={l("${dict.model}.id.desc")}
-        value={${dict.model}Form.id}
-        onChange={st.do.setIdOn${dict.Model}}
+        label={l("${dict.model}.name")}
+        value={${dict.model}Form.name}
+        onChange={st.do.setNameOn${dict.Model}}
       />
     </Layout.Template>
   );

package/templates/module/__Model__.Unit.tsx

@@ -17,7 +17,7 @@ export const Card = ({ ${dict.model}, href }: ModelProps<"${dict.model}", cnst.L
   const { l } = usePage();
   return (
     <Link href={href} className="w-full">
-      <div>{l("${dict.model}.id")}:{${dict.model}.id}</div>
+      <div>{l("${dict.model}.name")}: {${dict.model}.name}</div>
     </Link>
   );
 };

package/templates/module/__Model__.View.tsx

@@ -20,7 +20,7 @@ export const General = ({ className, ${dict.model} }: GeneralProps) => {
   const { l } = usePage();
   return (
     <div className={clsx("w-full", className)}>
-      <div>{l("${dict.model}.id")}: {${dict.model}.id}</div>
+      <div>{l("${dict.model}.name")}: {${dict.model}.name}</div>
     </div>
   );
 };

package/templates/module/__Model__.Zone.tsx

@@ -11,7 +11,9 @@ 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";
+// Alias the domain namespace so the Card/View exports below never collide with the model name
+// (a model literally named "card" or "view" would otherwise shadow this import).
+import { type cnst, ${dict.Model} as ${dict.Model}Domain } from "@${scanInfo?.type ?? "apps"}/${dict.sysName}/client";
 import type { ClientInit, ClientView, SliceMeta } from "akanjs/fetch";
 
 interface CardProps {
@@ -25,7 +27,7 @@ export const Card = ({ className, init, slice }: CardProps) => {
       className={className}
       init={init}
       renderItem={(${dict.model}) => (
-        <${dict.Model}.Unit.Card key={${dict.model}.id} href={\`/${dict.model}/\${${dict.model}.id}\`} ${dict.model}={${dict.model}} />
+        <${dict.Model}Domain.Unit.Card key={${dict.model}.id} href={\`/${dict.model}/\${${dict.model}.id}\`} ${dict.model}={${dict.model}} />
       )}
     />
   );
@@ -36,7 +38,7 @@ interface ViewProps {
   view: ClientView<"${dict.model}", cnst.${dict.Model}>;
 }
 export const View = ({ view }: ViewProps) => {
-  return <Load.View view={view} renderView={(${dict.model}) => <${dict.Model}.View.General ${dict.model}={${dict.model}} />} />;
+  return <Load.View view={view} renderView={(${dict.model}) => <${dict.Model}Domain.View.General ${dict.model}={${dict.model}} />} />;
 };
 `,
   };

package/templates/module/__model__.constant.ts

@@ -10,11 +10,12 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: Dic
 import { via } from "akanjs/constant";
 
 export class ${dict.Model}Input extends via((field) => ({
+  name: field(String),
 })) {}
 
 export class ${dict.Model}Object extends via(${dict.Model}Input, (field) => ({})) {}
 
-export class Light${dict.Model} extends via(${dict.Model}Object, [] as const, (resolve) => ({})) {}
+export class Light${dict.Model} extends via(${dict.Model}Object, ["name"] as const, (resolve) => ({})) {}
 
 export class ${dict.Model} extends via(${dict.Model}Object, Light${dict.Model}, (resolve) => ({})) {}
 

package/templates/module/__model__.dictionary.ts

@@ -24,7 +24,9 @@ export const dictionary = modelDictionary(["en", "ko"])
   .of((t) =>
     t(["${modelLabelEn}", "${modelLabelKo}"]).desc(["${modelDescEn}", "${modelDescKo}"])
   )
-  .model<${dict.Model}>((t) => ({}))
+  .model<${dict.Model}>((t) => ({
+    name: t(["Name", "이름"]),
+  }))
   .insight<${dict.Model}Insight>((t) => ({}))
   .slice<${dict.Model}Slice>((fn) => ({
     inPublic: fn(["${dict.Model} In Public", "${dict.Model} 공개"]).arg((t) => ({})),

package/templates/workspaceRoot/AGENTS.md.template

@@ -28,7 +28,6 @@ Common generated files include:
 - `*/lib/cnst.ts`
 - `*/lib/db.ts`
 - `*/lib/dict.ts`
-- `*/lib/option.ts`
 - `*/lib/sig.ts`
 - `*/lib/srv.ts`
 - `*/lib/st.ts`
@@ -87,7 +86,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 %>
@@ -111,15 +111,41 @@ akan test <%= appName %>
 akan build <%= appName %>
 ```
 
+**Verify endpoints with signal tests, not raw HTTP.** The canonical way to check a query/mutation/slice
+contract is an in-memory signal test (`<model>.signal.test.ts`), using the test fetch harness
+(`getOrSetupSignalTestFetch`) — it is fast, needs no running server, and exercises `fetch.*`, `view/edit/merge<Model>`,
+and slice `init`/`list`/`insight` directly. Prefer it over `curl`: the dev gateway locale-prefixes routes (`/en/...`),
+so hand-rolled HTTP calls against a raw path can redirect unexpectedly. See `akan test <%= 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 +156,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 +202,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... |
@@ -185,6 +235,7 @@ plan/apply, then validation/doctor on the returned `validationTarget`.
 | 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) |
+| Change the app color theme / design tokens | `apps/<app>/page/styles.css` → edit the daisyUI `@plugin "daisyui/theme"` blocks (`light`/`dark`, the `--color-*` variables) | akan start hot-reloads |
 | 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>` |
@@ -202,6 +253,7 @@ plan/apply, then validation/doctor on the returned `validationTarget`.
 | 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>` |
+| Name a custom `Endpoint`/`Slice` like a generated CRUD op — `create<Model>`, `update<Model>`, `remove<Model>`, `view<Model>`, `edit<Model>`, `merge<Model>` | These names are already auto-generated. A collision can pass sync/typecheck/build and only fail at runtime. | Pick a distinct verb, e.g. `startTask`/`archiveTask`, never `createTask` for a custom endpoint |
 
 ## Generated File Tracker (Quick Reference)
 
@@ -212,7 +264,6 @@ These files are regenerated by `akan sync` and overwritten on every sync. **Do n
 | `*/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 |
@@ -289,7 +340,13 @@ 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.
+
+> `apps/<app>/lib/option.ts` is a **user-owned** file scaffolded once — edit it to register adapters/DI. Unlike the
+> barrels (`cnst.ts`, `db.ts`, `srv.ts`, …) it is **not** overwritten by `akan sync`, so your `.use(...)` registrations
+> are safe.
 
 **A. Adapter injection via `use<>()` (for external clients / global singletons)**
 
@@ -332,18 +389,51 @@ 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
 
 A Slice is a named, filtered data view. Add file entries and connect from a page.
 
+> **Silent failure — a slice `exec` must return a query descriptor, never an executed list.**
+> Return `this.taskService.queryByStatuses(...)` (the `query<Filter>` builder), **not**
+> `this.taskService.listByStatuses(...)` / `listBy...(...)` (which returns a `Promise<Doc[]>`).
+> Returning an array type-checks but throws at runtime during insight aggregation with the opaque
+> `Error: Unknown document field path: 0`. If you see that error, your slice is returning a list, not a query.
+
 ```typescript
 // 1. apps/<app>/lib/<model>/<model>.signal.ts — Define the slice
 export class TaskSlice extends slice(srv.task, (init) => ({
   inTodo: init()
     .search("statuses", [cnst.TaskStatus])
     .exec(function (statuses?) {
+      // ✅ query<Filter> — a query descriptor.  ❌ listByStatuses(...) returns an array and fails at runtime.
       return this.taskService.queryByStatuses(statuses ?? ["todo", "inProgress"]);
     }),
 })) {}
@@ -522,6 +612,41 @@ For each business question, follow this chain:
 | What client state is shared? | `store.ts` — `store()` with auto-generated form/insight state + custom actions |
 | What should users see? | `View.tsx` + `Zone.tsx` (detail/container), `Template.tsx` (forms), `Unit.tsx` (cards), `Util.tsx` (buttons) |
 
+## Modeling & Query Gotchas
+
+A short list of things the type system does not always catch:
+
+- **Slices return a query, not a list.** A slice `exec` must return `this.<model>Service.query<Filter>(...)`, never
+  a `list<Filter>(...)` / `listBy...(...)` array. Returning an array type-checks but fails at runtime with
+  `Unknown document field path: 0`. (See Recipe 3.)
+- **Custom endpoint names must not collide with generated CRUD.** `create/update/remove/view/edit/merge<Model>`
+  already exist. A collision can build green and fail only at runtime — pick a distinct verb.
+- **Numbers are `Int` or `Float`, never `Number`.** `field(Number)` / `.body("x", Number)` fail to typecheck. Use
+  `Int` for counts, `Float` for decimals.
+- **Array fields use `field([T])`.** e.g. `tags: field([String])`, `images: field([File])` — not `field(String)` with
+  a suffix.
+- **Reading a secret field needs an explicit select.** `field(...).secret()` values (e.g. `passwordHash`) are stripped
+  from query results by default. Fetch them with `{ select: { <field>: true } }`, e.g.
+  `this.userModel.pickById(id, { select: { passwordHash: true } })`.
+
+## Current User, Guards & Auth-Gated Pages
+
+Built-in user authentication (session / JWT / password hashing) ships as a separate Akan auth library, not in the
+core framework. The core framework gives you the composition points below; wire the auth library through them.
+
+- **Guards** attach at the signal declaration, not per-method:
+  `endpoint(srv.task, { guards: { root: SignedIn } }, ({ mutation }) => ({...}))` or
+  `slice(srv.task, { guards: { root: SignedIn, get: Public, cru: Public } }, ...)`. `Public` always allows; other
+  guards implement the `Guard` interface in `srvkit/` (server-only) and read the request context.
+- **Read the current user inside a custom endpoint** by injecting an `InternalArg` with `.with(...)`:
+  `mutation(cnst.Task).with(CurrentUserId).exec(async function (currentUserId) { ... })`. The `Guard` /
+  `InternalArg` helpers live in `srvkit/` and read `context.getHttpContext().req.user`.
+- **Auto-generated CRUD and `serve()` service methods / lifecycle hooks do not receive session context.** If an
+  operation needs the acting user, expose a custom endpoint that takes it via `.with(CurrentUserId)` — never trust a
+  client-supplied user id.
+- **SSR auth-gated pages: guard at the layout.** Check the session in the `_layout.tsx` loader and redirect when it is
+  absent, so nested pages never render for signed-out users.
+
 ## Auto-Generated API Reference
 
 akan sync automatically generates APIs across all layers. Only write custom logic — never hand-write what the framework generates.
@@ -545,7 +670,7 @@ akan sync automatically generates APIs across all layers. Only write custom logi
 |---------------|-------------|
 | `this.<model>Model` | Auto-injected model adaptor |
 | `get<Model>(id)`, `load<Model>(id)` | Single document lookup |
-| `createModel(data)`, `updateModel(id, data)`, `removeModel(id)` | CRUD operations |
+| `create<Model>(data)`, `update<Model>(id, data)`, `remove<Model>(id)` | CRUD operations — named after the model, e.g. `createTask`/`updateTask`/`removeTask` (there is no literal `createModel`) |
 | `list<Query>(args)`, `find<Query>(args)`, `pick<Query>(args)` | Filter-based queries |
 | `exists<Query>(args)`, `count<Query>(args)`, `insight<Query>(args)` | Filter-based helpers |
 | `_preCreate`, `_postCreate`, `_preUpdate`, `_postUpdate`, `_preRemove`, `_postRemove` | Lifecycle hooks (override to add logic) |

package/templates/workspaceRoot/biome.json.template

@@ -50,7 +50,8 @@
       "!!**/dist",
       "!!**/.akan",
       "!!**/dump",
-      "!!**/local"
+      "!!**/local",
+      "!!**/ios/DerivedData"
     ]
   },
   "formatter": {
@@ -146,6 +147,10 @@
       "includes": ["**/*.constant.ts", "**/*.document.ts", "**/*.service.ts", "**/*.store.ts"],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-js-private-class-method.grit"]
     },
+    {
+      "includes": ["**/*.signal.ts"],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-redeclare-predefined-endpoint.grit"]
+    },
     {
       "includes": [
         "**/*.constant.ts",

package/templates/workspaceRoot/docs/GENERATED.md.template

@@ -17,7 +17,6 @@ sync or build can overwrite local changes.
 | `apps/*/lib/cnst.ts` | Re-exports constants and model shapes from module `*.constant.ts` files. |
 | `apps/*/lib/db.ts` | Re-exports database models from module `*.document.ts` files. |
 | `apps/*/lib/dict.ts` | Re-exports dictionaries from module `*.dictionary.ts` files. |
-| `apps/*/lib/option.ts` | Re-exports generated option helpers. |
 | `apps/*/lib/srv.ts` | Re-exports services from module `*.service.ts` files. |
 | `apps/*/lib/sig.ts` | Re-exports endpoints, slices, and internals from module `*.signal.ts` files. |
 | `apps/*/lib/st.ts` | Re-exports stores from module `*.store.ts` files. |

package/templates/workspaceRoot/package.json.template

@@ -13,9 +13,9 @@
     "agent:setup": "akan agent install all --force",
     "agent:doctor": "akan doctor --strict --format json",
     "agent:context": "akan context --format json",
-    "agent:mcp:readonly": "akan mcp-install cursor --mode readonly --force",
-    "agent:mcp:plan": "akan mcp-install cursor --mode plan --force",
-    "agent:mcp:apply": "akan mcp-install cursor --mode apply --force",
+    "agent:mcp:readonly": "akan mcp-install all --mode readonly --force",
+    "agent:mcp:plan": "akan mcp-install all --mode plan --force",
+    "agent:mcp:apply": "akan mcp-install all --mode apply --force",
     "agent:workflows": "akan workflow list",
     "agent:sample:context": "akan context --format markdown --app <%= appName %> --module project",
     "agent:sample:service": "akan create-service billing <%= appName %> --format json",