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

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",
@@ -4170,6 +4171,7 @@ var BACKEND_RESTART_DEBOUNCE_MS = 120;
 var BACKEND_GRACEFUL_TIMEOUT_MS = 3000;
 var BACKEND_RECOVERY_BASE_DELAY_MS = 1000;
 var BACKEND_RECOVERY_MAX_DELAY_MS = 30000;
+var BACKEND_STDERR_TAIL_LIMIT = 40;
 var BUILDER_READY_TIMEOUT_MS = 150000;
 var BUILDER_START_MAX_ATTEMPTS = 3;
 var SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
@@ -4372,6 +4374,7 @@ class AkanAppHost {
   #pendingRestartReason = null;
   #backendStartStatus = null;
   #backendBuildStatusGeneration = 0;
+  #backendStderrTail = [];
   #lastGoodFrontend = {};
   #buildStatusByPhase = new Map;
   #pendingBuildStatusReplay = [];
@@ -4423,6 +4426,7 @@ class AkanAppHost {
     this.#backendStartStatus = startStatus;
     this.#setBackendLifecycleState("starting");
     this.#backendReady = false;
+    this.#backendStderrTail = [];
     const backend = Bun.spawn(["bun", `apps/${this.app.name}/main.ts`], {
       cwd: this.app.workspace.workspaceRoot,
       stdio: this.withInk ? ["ignore", "pipe", "pipe"] : ["inherit", "inherit", "inherit"],
@@ -4456,6 +4460,37 @@ class AkanAppHost {
     });
     this.#backend = backend;
     this.logger.verbose(`backend spawned pid=${backend.pid}`);
+    if (this.withInk) {
+      this.#forwardBackendStream(backend.stderr, "stderr");
+      this.#forwardBackendStream(backend.stdout, "stdout");
+    }
+  }
+  #recordBackendStderr(chunk) {
+    const lines = chunk.split(/\r?\n/).filter((line) => line.length > 0);
+    if (lines.length === 0)
+      return;
+    this.#backendStderrTail.push(...lines);
+    if (this.#backendStderrTail.length > BACKEND_STDERR_TAIL_LIMIT) {
+      this.#backendStderrTail.splice(0, this.#backendStderrTail.length - BACKEND_STDERR_TAIL_LIMIT);
+    }
+  }
+  async#forwardBackendStream(stream, kind) {
+    if (!stream)
+      return;
+    const decoder = new TextDecoder;
+    try {
+      for await (const chunk of stream) {
+        const text = decoder.decode(chunk, { stream: true });
+        if (!text.trim())
+          continue;
+        if (kind === "stderr") {
+          this.#recordBackendStderr(text);
+          this.logger.warn(`[backend] ${text.trimEnd()}`);
+        } else {
+          this.logger.verbose(`[backend] ${text.trimEnd()}`);
+        }
+      }
+    } catch {}
   }
   #nextBackendBuildStatusGeneration(generation) {
     if (typeof generation === "number") {
@@ -4580,6 +4615,11 @@ class AkanAppHost {
     });
     this.#sendOrQueueBuildStatus(failureStatus);
     this.logger.warn(`[backend-recovery] backend exited unexpectedly (${reason}); restarting in ${delay}ms (attempt ${this.#backendRecoveryAttempts})`);
+    if (this.#backendStderrTail.length > 0) {
+      this.logger.warn(`[backend-recovery] recent backend stderr:
+${this.#backendStderrTail.join(`
+`)}`);
+    }
     this.#backendRecoveryTimer = setTimeout(() => {
       this.#backendRecoveryTimer = null;
       if (this.#backend)
@@ -5945,6 +5985,117 @@ ${values.map((value) => `    ${value}: t([${JSON.stringify(titleize(value))}, ${
   return `${content.slice(0, insertBeforeIndex)}${enumBlock}${content.slice(insertBeforeIndex)}`;
 };
 var parseValues = (value) => value?.split(",").map((item) => item.trim()).filter(Boolean) ?? [];
+var hasSourceParseErrors = (content, fileName = "source.ts") => hasParseDiagnostics(sourceFileFor(fileName, content));
+var findClassDeclaration = (source, className) => {
+  let found = null;
+  const visit = (node) => {
+    if (found)
+      return;
+    if (ts4.isClassDeclaration(node) && node.name?.text === className) {
+      found = node;
+      return;
+    }
+    ts4.forEachChild(node, visit);
+  };
+  ts4.forEachChild(source, visit);
+  return found;
+};
+var firstHeritageCall = (node) => {
+  const expression = (node.heritageClauses?.flatMap((clause) => [...clause.types]) ?? [])[0]?.expression;
+  return expression && ts4.isCallExpression(expression) ? expression : null;
+};
+var factoryArrowOf = (call) => {
+  const arg = call.arguments.find((argument) => ts4.isArrowFunction(argument) || ts4.isFunctionExpression(argument));
+  return arg && (ts4.isArrowFunction(arg) || ts4.isFunctionExpression(arg)) ? arg : null;
+};
+var hasClassMethod = (content, className, methodName) => {
+  const node = findClassDeclaration(sourceFileFor("service.ts", content), className);
+  return Boolean(node?.members.some((member) => ts4.isMethodDeclaration(member) && nodeName(member.name) === methodName));
+};
+var insertClassMethod = (content, className, methodBlock) => {
+  const source = sourceFileFor("service.ts", content);
+  const node = findClassDeclaration(source, className);
+  if (!node)
+    return null;
+  const closeBrace = node.getEnd() - 1;
+  if (content[closeBrace] !== "}")
+    return null;
+  const lead = content.slice(0, closeBrace).endsWith(`
+`) ? "" : `
+`;
+  return spliceText(content, closeBrace, closeBrace, `${lead}${methodBlock}
+`);
+};
+var arrowParamInnerRegion = (content, source, arrow) => {
+  if (arrow.parameters.length > 0) {
+    return {
+      start: arrow.parameters[0].getStart(source),
+      end: arrow.parameters[arrow.parameters.length - 1].getEnd()
+    };
+  }
+  const open = content.indexOf("(", arrow.getStart(source));
+  if (open < 0)
+    return null;
+  const close = content.indexOf(")", open);
+  if (close < 0)
+    return null;
+  return { start: open + 1, end: close };
+};
+var factoryParamEdit = (content, source, arrow, plan) => {
+  if (arrow.parameters.length > 1)
+    return null;
+  const region = arrowParamInnerRegion(content, source, arrow);
+  if (!region)
+    return null;
+  if (arrow.parameters.length === 0) {
+    return { ...region, text: plan.mode === "destructure" ? `{ ${plan.name} }` : plan.name };
+  }
+  const param = arrow.parameters[0];
+  if (plan.mode === "positional")
+    return nodeName(param.name) === plan.name ? "unchanged" : null;
+  if (!ts4.isObjectBindingPattern(param.name))
+    return null;
+  const names = param.name.elements.map((element) => ts4.isIdentifier(element.name) ? element.name.text : null);
+  if (names.some((name) => name === null))
+    return null;
+  if (names.includes(plan.name))
+    return "unchanged";
+  return {
+    start: param.getStart(source),
+    end: param.getEnd(),
+    text: `{ ${[...names, plan.name].join(", ")} }`
+  };
+};
+var factoryObjectOf = (source, className) => {
+  const node = findClassDeclaration(source, className);
+  const call = node ? firstHeritageCall(node) : null;
+  const arrow = call ? factoryArrowOf(call) : null;
+  const object = arrow ? firstObjectReturnedByArrow(arrow) : null;
+  return arrow && object ? { arrow, object } : null;
+};
+var hasSignalFactoryEntry = (content, className, entryName) => {
+  const located = factoryObjectOf(sourceFileFor("signal.ts", content), className);
+  return Boolean(located?.object.properties.some((property) => propertyName(property) === entryName));
+};
+var insertSignalFactoryEntry = (content, className, entryName, entryLine, param) => {
+  const source = sourceFileFor("signal.ts", content);
+  const located = factoryObjectOf(source, className);
+  if (!located)
+    return null;
+  const locator = locatedObject(source, located.object);
+  if (locator.fields.some((field) => field.name === entryName))
+    return content;
+  const paramEdit = factoryParamEdit(content, source, located.arrow, param);
+  if (paramEdit === null)
+    return null;
+  const withEntry = insertOrderedFieldLine(content, locator, entryName, entryLine, {
+    fieldIndent: "  ",
+    closingIndent: ""
+  });
+  if (withEntry === content)
+    return null;
+  return paramEdit === "unchanged" ? withEntry : spliceText(withEntry, paramEdit.start, paramEdit.end, paramEdit.text);
+};
 
 // pkgs/@akanjs/devkit/workflow/moduleIndex.ts
 var indexFileKinds = [
@@ -6662,7 +6813,9 @@ var createWorkflowStepRegistry = ({
   createScalar,
   createUi,
   addField,
-  addEnumField
+  addEnumField,
+  addMutation,
+  addSlice
 }) => {
   const inspect = async () => {
     return;
@@ -6738,7 +6891,19 @@ var createWorkflowStepRegistry = ({
       defaultValue: workflowStringInput(plan.inputs.default)
     })),
     [workflowStepKey("add-enum-field", "update-dictionary")]: inspect,
-    [workflowStepKey("add-enum-field", "update-option")]: inspect
+    [workflowStepKey("add-enum-field", "update-option")]: inspect,
+    [workflowStepKey("add-mutation", "update-service")]: async (_step, plan) => primitiveReportToWorkflowStepResult(await addMutation({
+      app: workflowStringInput(plan.inputs.app),
+      module: workflowStringInput(plan.inputs.module),
+      mutation: workflowStringInput(plan.inputs.mutation)
+    })),
+    [workflowStepKey("add-mutation", "update-signal")]: inspect,
+    [workflowStepKey("add-slice", "update-service-query")]: async (_step, plan) => primitiveReportToWorkflowStepResult(await addSlice({
+      app: workflowStringInput(plan.inputs.app),
+      module: workflowStringInput(plan.inputs.module),
+      slice: workflowStringInput(plan.inputs.slice)
+    })),
+    [workflowStepKey("add-slice", "update-signal-slice")]: inspect
   };
 };
 class WorkflowExecutor {
@@ -12807,11 +12972,15 @@ async function resolveSignalTestPreloadPath(target) {
   addResolvedPackageCandidate(path39.dirname(Bun.main));
   addResolvedPackageCandidate(import.meta.dir);
   candidates.push(path39.join(target.cwdPath, "../../node_modules/akanjs", SIGNAL_TEST_PRELOAD_PATH), path39.join(target.cwdPath, "../../pkgs/akanjs", SIGNAL_TEST_PRELOAD_PATH), path39.join(process.cwd(), "node_modules/akanjs", SIGNAL_TEST_PRELOAD_PATH), path39.join(process.cwd(), "pkgs/akanjs", SIGNAL_TEST_PRELOAD_PATH), path39.join(path39.dirname(Bun.main), "../../akanjs", SIGNAL_TEST_PRELOAD_PATH), path39.resolve(import.meta.dir, "../../akanjs", SIGNAL_TEST_PRELOAD_PATH));
-  for (const candidate of [...new Set(candidates)]) {
+  const uniqueCandidates = [...new Set(candidates)];
+  for (const candidate of uniqueCandidates) {
     if (await Bun.file(candidate).exists())
       return candidate;
   }
-  throw new Error(`Failed to locate ${SIGNAL_TEST_PRELOAD_PATH} from ${target.cwdPath}`);
+  throw new Error(`Failed to locate ${SIGNAL_TEST_PRELOAD_PATH} from ${target.cwdPath}.
+Probed paths:
+${uniqueCandidates.map((candidate) => `  - ${candidate}`).join(`
+`)}`);
 }
 // pkgs/@akanjs/devkit/builder.ts
 import { existsSync as existsSync2 } from "fs";

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",
@@ -4168,6 +4169,7 @@ var BACKEND_RESTART_DEBOUNCE_MS = 120;
 var BACKEND_GRACEFUL_TIMEOUT_MS = 3000;
 var BACKEND_RECOVERY_BASE_DELAY_MS = 1000;
 var BACKEND_RECOVERY_MAX_DELAY_MS = 30000;
+var BACKEND_STDERR_TAIL_LIMIT = 40;
 var BUILDER_READY_TIMEOUT_MS = 150000;
 var BUILDER_START_MAX_ATTEMPTS = 3;
 var SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
@@ -4370,6 +4372,7 @@ class AkanAppHost {
   #pendingRestartReason = null;
   #backendStartStatus = null;
   #backendBuildStatusGeneration = 0;
+  #backendStderrTail = [];
   #lastGoodFrontend = {};
   #buildStatusByPhase = new Map;
   #pendingBuildStatusReplay = [];
@@ -4421,6 +4424,7 @@ class AkanAppHost {
     this.#backendStartStatus = startStatus;
     this.#setBackendLifecycleState("starting");
     this.#backendReady = false;
+    this.#backendStderrTail = [];
     const backend = Bun.spawn(["bun", `apps/${this.app.name}/main.ts`], {
       cwd: this.app.workspace.workspaceRoot,
       stdio: this.withInk ? ["ignore", "pipe", "pipe"] : ["inherit", "inherit", "inherit"],
@@ -4454,6 +4458,37 @@ class AkanAppHost {
     });
     this.#backend = backend;
     this.logger.verbose(`backend spawned pid=${backend.pid}`);
+    if (this.withInk) {
+      this.#forwardBackendStream(backend.stderr, "stderr");
+      this.#forwardBackendStream(backend.stdout, "stdout");
+    }
+  }
+  #recordBackendStderr(chunk) {
+    const lines = chunk.split(/\r?\n/).filter((line) => line.length > 0);
+    if (lines.length === 0)
+      return;
+    this.#backendStderrTail.push(...lines);
+    if (this.#backendStderrTail.length > BACKEND_STDERR_TAIL_LIMIT) {
+      this.#backendStderrTail.splice(0, this.#backendStderrTail.length - BACKEND_STDERR_TAIL_LIMIT);
+    }
+  }
+  async#forwardBackendStream(stream, kind) {
+    if (!stream)
+      return;
+    const decoder = new TextDecoder;
+    try {
+      for await (const chunk of stream) {
+        const text = decoder.decode(chunk, { stream: true });
+        if (!text.trim())
+          continue;
+        if (kind === "stderr") {
+          this.#recordBackendStderr(text);
+          this.logger.warn(`[backend] ${text.trimEnd()}`);
+        } else {
+          this.logger.verbose(`[backend] ${text.trimEnd()}`);
+        }
+      }
+    } catch {}
   }
   #nextBackendBuildStatusGeneration(generation) {
     if (typeof generation === "number") {
@@ -4578,6 +4613,11 @@ class AkanAppHost {
     });
     this.#sendOrQueueBuildStatus(failureStatus);
     this.logger.warn(`[backend-recovery] backend exited unexpectedly (${reason}); restarting in ${delay}ms (attempt ${this.#backendRecoveryAttempts})`);
+    if (this.#backendStderrTail.length > 0) {
+      this.logger.warn(`[backend-recovery] recent backend stderr:
+${this.#backendStderrTail.join(`
+`)}`);
+    }
     this.#backendRecoveryTimer = setTimeout(() => {
       this.#backendRecoveryTimer = null;
       if (this.#backend)
@@ -5943,6 +5983,117 @@ ${values.map((value) => `    ${value}: t([${JSON.stringify(titleize(value))}, ${
   return `${content.slice(0, insertBeforeIndex)}${enumBlock}${content.slice(insertBeforeIndex)}`;
 };
 var parseValues = (value) => value?.split(",").map((item) => item.trim()).filter(Boolean) ?? [];
+var hasSourceParseErrors = (content, fileName = "source.ts") => hasParseDiagnostics(sourceFileFor(fileName, content));
+var findClassDeclaration = (source, className) => {
+  let found = null;
+  const visit = (node) => {
+    if (found)
+      return;
+    if (ts4.isClassDeclaration(node) && node.name?.text === className) {
+      found = node;
+      return;
+    }
+    ts4.forEachChild(node, visit);
+  };
+  ts4.forEachChild(source, visit);
+  return found;
+};
+var firstHeritageCall = (node) => {
+  const expression = (node.heritageClauses?.flatMap((clause) => [...clause.types]) ?? [])[0]?.expression;
+  return expression && ts4.isCallExpression(expression) ? expression : null;
+};
+var factoryArrowOf = (call) => {
+  const arg = call.arguments.find((argument) => ts4.isArrowFunction(argument) || ts4.isFunctionExpression(argument));
+  return arg && (ts4.isArrowFunction(arg) || ts4.isFunctionExpression(arg)) ? arg : null;
+};
+var hasClassMethod = (content, className, methodName) => {
+  const node = findClassDeclaration(sourceFileFor("service.ts", content), className);
+  return Boolean(node?.members.some((member) => ts4.isMethodDeclaration(member) && nodeName(member.name) === methodName));
+};
+var insertClassMethod = (content, className, methodBlock) => {
+  const source = sourceFileFor("service.ts", content);
+  const node = findClassDeclaration(source, className);
+  if (!node)
+    return null;
+  const closeBrace = node.getEnd() - 1;
+  if (content[closeBrace] !== "}")
+    return null;
+  const lead = content.slice(0, closeBrace).endsWith(`
+`) ? "" : `
+`;
+  return spliceText(content, closeBrace, closeBrace, `${lead}${methodBlock}
+`);
+};
+var arrowParamInnerRegion = (content, source, arrow) => {
+  if (arrow.parameters.length > 0) {
+    return {
+      start: arrow.parameters[0].getStart(source),
+      end: arrow.parameters[arrow.parameters.length - 1].getEnd()
+    };
+  }
+  const open = content.indexOf("(", arrow.getStart(source));
+  if (open < 0)
+    return null;
+  const close = content.indexOf(")", open);
+  if (close < 0)
+    return null;
+  return { start: open + 1, end: close };
+};
+var factoryParamEdit = (content, source, arrow, plan) => {
+  if (arrow.parameters.length > 1)
+    return null;
+  const region = arrowParamInnerRegion(content, source, arrow);
+  if (!region)
+    return null;
+  if (arrow.parameters.length === 0) {
+    return { ...region, text: plan.mode === "destructure" ? `{ ${plan.name} }` : plan.name };
+  }
+  const param = arrow.parameters[0];
+  if (plan.mode === "positional")
+    return nodeName(param.name) === plan.name ? "unchanged" : null;
+  if (!ts4.isObjectBindingPattern(param.name))
+    return null;
+  const names = param.name.elements.map((element) => ts4.isIdentifier(element.name) ? element.name.text : null);
+  if (names.some((name) => name === null))
+    return null;
+  if (names.includes(plan.name))
+    return "unchanged";
+  return {
+    start: param.getStart(source),
+    end: param.getEnd(),
+    text: `{ ${[...names, plan.name].join(", ")} }`
+  };
+};
+var factoryObjectOf = (source, className) => {
+  const node = findClassDeclaration(source, className);
+  const call = node ? firstHeritageCall(node) : null;
+  const arrow = call ? factoryArrowOf(call) : null;
+  const object = arrow ? firstObjectReturnedByArrow(arrow) : null;
+  return arrow && object ? { arrow, object } : null;
+};
+var hasSignalFactoryEntry = (content, className, entryName) => {
+  const located = factoryObjectOf(sourceFileFor("signal.ts", content), className);
+  return Boolean(located?.object.properties.some((property) => propertyName(property) === entryName));
+};
+var insertSignalFactoryEntry = (content, className, entryName, entryLine, param) => {
+  const source = sourceFileFor("signal.ts", content);
+  const located = factoryObjectOf(source, className);
+  if (!located)
+    return null;
+  const locator = locatedObject(source, located.object);
+  if (locator.fields.some((field) => field.name === entryName))
+    return content;
+  const paramEdit = factoryParamEdit(content, source, located.arrow, param);
+  if (paramEdit === null)
+    return null;
+  const withEntry = insertOrderedFieldLine(content, locator, entryName, entryLine, {
+    fieldIndent: "  ",
+    closingIndent: ""
+  });
+  if (withEntry === content)
+    return null;
+  return paramEdit === "unchanged" ? withEntry : spliceText(withEntry, paramEdit.start, paramEdit.end, paramEdit.text);
+};
 
 // pkgs/@akanjs/devkit/workflow/moduleIndex.ts
 var indexFileKinds = [
@@ -6660,7 +6811,9 @@ var createWorkflowStepRegistry = ({
   createScalar,
   createUi,
   addField,
-  addEnumField
+  addEnumField,
+  addMutation,
+  addSlice
 }) => {
   const inspect = async () => {
     return;
@@ -6736,7 +6889,19 @@ var createWorkflowStepRegistry = ({
       defaultValue: workflowStringInput(plan.inputs.default)
     })),
     [workflowStepKey("add-enum-field", "update-dictionary")]: inspect,
-    [workflowStepKey("add-enum-field", "update-option")]: inspect
+    [workflowStepKey("add-enum-field", "update-option")]: inspect,
+    [workflowStepKey("add-mutation", "update-service")]: async (_step, plan) => primitiveReportToWorkflowStepResult(await addMutation({
+      app: workflowStringInput(plan.inputs.app),
+      module: workflowStringInput(plan.inputs.module),
+      mutation: workflowStringInput(plan.inputs.mutation)
+    })),
+    [workflowStepKey("add-mutation", "update-signal")]: inspect,
+    [workflowStepKey("add-slice", "update-service-query")]: async (_step, plan) => primitiveReportToWorkflowStepResult(await addSlice({
+      app: workflowStringInput(plan.inputs.app),
+      module: workflowStringInput(plan.inputs.module),
+      slice: workflowStringInput(plan.inputs.slice)
+    })),
+    [workflowStepKey("add-slice", "update-signal-slice")]: inspect
   };
 };
 class WorkflowExecutor {
@@ -12805,11 +12970,15 @@ async function resolveSignalTestPreloadPath(target) {
   addResolvedPackageCandidate(path39.dirname(Bun.main));
   addResolvedPackageCandidate(import.meta.dir);
   candidates.push(path39.join(target.cwdPath, "../../node_modules/akanjs", SIGNAL_TEST_PRELOAD_PATH), path39.join(target.cwdPath, "../../pkgs/akanjs", SIGNAL_TEST_PRELOAD_PATH), path39.join(process.cwd(), "node_modules/akanjs", SIGNAL_TEST_PRELOAD_PATH), path39.join(process.cwd(), "pkgs/akanjs", SIGNAL_TEST_PRELOAD_PATH), path39.join(path39.dirname(Bun.main), "../../akanjs", SIGNAL_TEST_PRELOAD_PATH), path39.resolve(import.meta.dir, "../../akanjs", SIGNAL_TEST_PRELOAD_PATH));
-  for (const candidate of [...new Set(candidates)]) {
+  const uniqueCandidates = [...new Set(candidates)];
+  for (const candidate of uniqueCandidates) {
     if (await Bun.file(candidate).exists())
       return candidate;
   }
-  throw new Error(`Failed to locate ${SIGNAL_TEST_PRELOAD_PATH} from ${target.cwdPath}`);
+  throw new Error(`Failed to locate ${SIGNAL_TEST_PRELOAD_PATH} from ${target.cwdPath}.
+Probed paths:
+${uniqueCandidates.map((candidate) => `  - ${candidate}`).join(`
+`)}`);
 }
 // pkgs/@akanjs/devkit/builder.ts
 import { existsSync as existsSync2 } from "fs";
@@ -15860,19 +16029,12 @@ 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 renderAgentRules = async (workspace, target) => {
+var AGENT_BLOCK_START = "<!-- akan:agent:start -->";
+var AGENT_BLOCK_END = "<!-- akan:agent:end -->";
+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
+  return `## Workspace
 
 - Repo: ${context.repoName}
 - Apps: ${context.apps.map((app) => app.name).join(", ") || "none"}
@@ -15909,20 +16071,75 @@ ${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") {
   async install(workspace, targets, { force = false } = {}) {
     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;
@@ -17997,8 +18214,18 @@ var addMutationWorkflowSpec = {
     }
   ],
   predictedChanges: [
-    { target: "*/lib/<module>/<module>.service.ts", action: "modify", reason: "Service mutation may be added." },
-    { target: "*/lib/<module>/<module>.signal.ts", action: "modify", reason: "Signal mutation may be added." },
+    {
+      target: "*/lib/<module>/<module>.service.ts",
+      action: "modify",
+      applyScope: "auto",
+      reason: "Service mutation method stub is added."
+    },
+    {
+      target: "*/lib/<module>/<module>.signal.ts",
+      action: "modify",
+      applyScope: "auto",
+      reason: "Signal endpoint mutation is added."
+    },
     { target: "*/lib/srv.ts", action: "sync", reason: "Generated service barrel may change after sync." },
     { target: "*/lib/sig.ts", action: "sync", reason: "Generated signal barrel may change after sync." }
   ],
@@ -18070,9 +18297,24 @@ var addSliceWorkflowSpec = {
     }
   ],
   predictedChanges: [
-    { target: "*/lib/<module>/<module>.service.ts", action: "modify", reason: "Query helper may be added." },
-    { target: "*/lib/<module>/<module>.signal.ts", action: "modify", reason: "Signal slice may be added." },
-    { target: "*/lib/<module>/<Module>.Zone.tsx", action: "modify", reason: "Zone may connect slice state." },
+    {
+      target: "*/lib/<module>/<module>.service.ts",
+      action: "modify",
+      applyScope: "auto",
+      reason: "Query helper method stub is added."
+    },
+    {
+      target: "*/lib/<module>/<module>.signal.ts",
+      action: "modify",
+      applyScope: "auto",
+      reason: "Signal slice entry is added."
+    },
+    {
+      target: "*/lib/<module>/<Module>.Zone.tsx",
+      action: "modify",
+      applyScope: "manual-review",
+      reason: "Zone may connect slice state."
+    },
     { target: "*/lib/sig.ts", action: "sync", reason: "Generated signal barrel may change after sync." }
   ],
   validation: [
@@ -19384,6 +19626,12 @@ class PrimitiveScript extends script("primitive", [ModuleScript]) {
         code: "primitive-field-type-unsupported",
         message: `Field type "${input7.type}" is ambiguous in Akan. Use Int for integer fields or Float for decimal fields.`,
         input: "type"
+      } : null,
+      input7.type && input7.type.toLowerCase() === "upload" ? {
+        severity: "error",
+        code: "primitive-field-type-upload-misuse",
+        message: "Upload is not a model field type. Declare an image/file field as a relation to the File model (e.g. field(File)); Upload is only valid in a { fileUpload: true } signal body. Note the File model is provided by the shared file library.",
+        input: "type"
       } : null
     ]);
     if (!sys3 || !input7.module || !input7.field || !input7.type || diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
@@ -19582,6 +19830,206 @@ class PrimitiveScript extends script("primitive", [ModuleScript]) {
       nextActions: nextActionsForTarget(sys3.name)
     });
   }
+  async addMutation(workspace, input7) {
+    const moduleClassName = input7.module ? moduleComponentName(input7.module) : "";
+    const serviceRef = lowerlize(moduleClassName);
+    const name = input7.mutation;
+    return await this.#writeServiceSignalEntry(workspace, {
+      command: "add-mutation",
+      app: input7.app,
+      module: input7.module,
+      entryKind: "mutation",
+      entryName: name,
+      requiredInput: "mutation",
+      serviceMethod: name ? {
+        name,
+        block: [
+          `  async ${name}() {`,
+          `    // TODO(service): implement ${moduleClassName}Service.${name}`,
+          `    return true;`,
+          `  }`
+        ].join(`
+`)
+      } : null,
+      signal: name ? {
+        className: `${moduleClassName}Endpoint`,
+        entryLine: [
+          `${name}: mutation(Boolean)`,
+          `    .exec(async function () {`,
+          `      return await this.${serviceRef}Service.${name}();`,
+          `    }),`
+        ].join(`
+`),
+        param: { mode: "destructure", name: "mutation" }
+      } : null
+    });
+  }
+  async addSlice(workspace, input7) {
+    const moduleClassName = input7.module ? moduleComponentName(input7.module) : "";
+    const serviceRef = lowerlize(moduleClassName);
+    const name = input7.slice;
+    const queryName = name ? `query${capitalize12(name)}` : null;
+    return await this.#writeServiceSignalEntry(workspace, {
+      command: "add-slice",
+      app: input7.app,
+      module: input7.module,
+      entryKind: "slice",
+      entryName: name,
+      requiredInput: "slice",
+      serviceMethod: name && queryName ? {
+        name: queryName,
+        block: [
+          `  ${queryName}() {`,
+          `    // TODO(service): return a QueryOf for the ${name} slice`,
+          `    return {};`,
+          `  }`
+        ].join(`
+`)
+      } : null,
+      signal: name && queryName ? {
+        className: `${moduleClassName}Slice`,
+        entryLine: [
+          `${name}: init()`,
+          `    .exec(function () {`,
+          `      return this.${serviceRef}Service.${queryName}();`,
+          `    }),`
+        ].join(`
+`),
+        param: { mode: "positional", name: "init" }
+      } : null
+    });
+  }
+  async#writeServiceSignalEntry(workspace, spec) {
+    const sys3 = await this.resolveSys(workspace, spec.app);
+    const diagnostics = compactDiagnostics([
+      !sys3 && { severity: "error", code: "primitive-target-missing", message: "Target app or library was not found." },
+      !spec.module && {
+        severity: "error",
+        code: "primitive-input-missing",
+        message: "Module is required.",
+        input: "module"
+      },
+      !spec.entryName && {
+        severity: "error",
+        code: "primitive-input-missing",
+        message: `${capitalize12(spec.requiredInput)} name is required.`,
+        input: spec.requiredInput
+      }
+    ]);
+    if (!sys3 || !spec.module || !spec.entryName || !spec.serviceMethod || !spec.signal) {
+      return createPrimitiveWriteReport({
+        command: spec.command,
+        changedFiles: [],
+        generatedFiles: [],
+        validationCommands: [],
+        diagnostics,
+        nextActions: []
+      });
+    }
+    const paths = moduleSourcePaths(spec.module);
+    const servicePath = paths.service;
+    const signalPath = paths.signal;
+    const changedFiles = [];
+    const generatedFiles2 = generatedFilesForSync(sys3);
+    const [hasServiceFile, hasSignalFile] = await Promise.all([sys3.exists(servicePath), sys3.exists(signalPath)]);
+    if (!hasServiceFile) {
+      diagnostics.push({
+        severity: "error",
+        code: "primitive-source-missing",
+        message: `Service source file was not found: ${servicePath}.`
+      });
+    }
+    if (!hasSignalFile) {
+      diagnostics.push({
+        severity: "error",
+        code: "primitive-source-missing",
+        message: `Signal source file was not found: ${signalPath}.`
+      });
+    }
+    if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+      return createPrimitiveWriteReport({
+        command: spec.command,
+        changedFiles,
+        generatedFiles: generatedFiles2,
+        validationCommands: validationCommandsForTarget(sys3.name),
+        diagnostics,
+        nextActions: nextActionsForTarget(sys3.name)
+      });
+    }
+    const serviceClassName = `${moduleComponentName(spec.module)}Service`;
+    const serviceContent = await sys3.readFile(servicePath);
+    const signalContent = await sys3.readFile(signalPath);
+    const serviceMethodExists = hasClassMethod(serviceContent, serviceClassName, spec.serviceMethod.name);
+    if (serviceMethodExists) {
+      diagnostics.push({
+        severity: "error",
+        code: "primitive-service-method-exists",
+        input: spec.requiredInput,
+        message: `Method "${spec.serviceMethod.name}" already exists in ${serviceClassName}.`
+      });
+    }
+    if (hasSignalFactoryEntry(signalContent, spec.signal.className, spec.entryName)) {
+      diagnostics.push({
+        severity: "error",
+        code: "primitive-signal-entry-exists",
+        input: spec.requiredInput,
+        message: `Entry "${spec.entryName}" already exists in ${spec.signal.className}.`
+      });
+    }
+    const nextServiceContent = serviceMethodExists ? serviceContent : insertClassMethod(serviceContent, serviceClassName, spec.serviceMethod.block);
+    const nextSignalContent = insertSignalFactoryEntry(signalContent, spec.signal.className, spec.entryName, spec.signal.entryLine, spec.signal.param);
+    if (!nextServiceContent) {
+      diagnostics.push({
+        severity: "error",
+        code: "primitive-service-shape-unsupported",
+        message: `Could not find ${serviceClassName} class body in ${servicePath}.`
+      });
+    }
+    if (!nextSignalContent) {
+      diagnostics.push({
+        severity: "error",
+        code: "primitive-signal-shape-unsupported",
+        message: `Could not find a safe insertion point in ${spec.signal.className} within ${signalPath}. Ensure the class exists and its factory returns an object literal.`
+      });
+    }
+    if (nextServiceContent && hasSourceParseErrors(nextServiceContent, "service.ts")) {
+      diagnostics.push({
+        severity: "error",
+        code: "primitive-post-edit-service-parse-failed",
+        failureScope: "source-change",
+        message: `Edited ${servicePath} did not parse cleanly; refusing to write source.`
+      });
+    }
+    if (nextSignalContent && hasSourceParseErrors(nextSignalContent, "signal.ts")) {
+      diagnostics.push({
+        severity: "error",
+        code: "primitive-post-edit-signal-parse-failed",
+        failureScope: "source-change",
+        message: `Edited ${signalPath} did not parse cleanly; refusing to write source.`
+      });
+    }
+    if (nextSignalContent && !hasSignalFactoryEntry(nextSignalContent, spec.signal.className, spec.entryName)) {
+      diagnostics.push({
+        severity: "error",
+        code: "primitive-post-edit-signal-verify-failed",
+        failureScope: "source-change",
+        message: `Edited ${signalPath} did not contain entry "${spec.entryName}" in ${spec.signal.className}.`
+      });
+    }
+    if (!diagnostics.some((diagnostic) => diagnostic.severity === "error") && nextServiceContent && nextSignalContent) {
+      await sys3.writeFile(servicePath, nextServiceContent);
+      await sys3.writeFile(signalPath, nextSignalContent);
+      changedFiles.push(sourceFile(sys3, servicePath, "modify", `Service ${spec.entryKind} was added.`), sourceFile(sys3, signalPath, "modify", `Signal ${spec.entryKind} was added.`));
+    }
+    return createPrimitiveWriteReport({
+      command: spec.command,
+      changedFiles,
+      generatedFiles: generatedFiles2,
+      validationCommands: validationCommandsForTarget(sys3.name),
+      diagnostics,
+      nextActions: nextActionsForTarget(sys3.name)
+    });
+  }
 }
 
 // pkgs/@akanjs/cli/scalar/scalar.prompt.ts
@@ -19799,7 +20247,9 @@ var createCliWorkflowStepRegistry = (workspace) => createWorkflowStepRegistry({
   createScalar: (sys3, scalar) => CommandContainer.get(ScalarScript).createScalar(sys3, scalar),
   createUi: (input8) => CommandContainer.get(PrimitiveScript).createUi(workspace, input8),
   addField: (input8) => CommandContainer.get(PrimitiveScript).addField(workspace, input8),
-  addEnumField: (input8) => CommandContainer.get(PrimitiveScript).addEnumField(workspace, input8)
+  addEnumField: (input8) => CommandContainer.get(PrimitiveScript).addEnumField(workspace, input8),
+  addMutation: (input8) => CommandContainer.get(PrimitiveScript).addMutation(workspace, input8),
+  addSlice: (input8) => CommandContainer.get(PrimitiveScript).addSlice(workspace, input8)
 });
 
 // pkgs/@akanjs/cli/context/context.runner.ts
@@ -20990,7 +21440,9 @@ class WorkflowScript extends script("workflow", [WorkflowRunner, ModuleScript, S
           createScalar: (sys3, scalar) => this.scalarScript.createScalar(sys3, scalar),
           createUi: (input8) => this.primitiveScript.createUi(workspace, input8),
           addField: (input8) => this.primitiveScript.addField(workspace, input8),
-          addEnumField: (input8) => this.primitiveScript.addEnumField(workspace, input8)
+          addEnumField: (input8) => this.primitiveScript.addEnumField(workspace, input8),
+          addMutation: (input8) => this.primitiveScript.addMutation(workspace, input8),
+          addSlice: (input8) => this.primitiveScript.addSlice(workspace, input8)
         })
       }));
       return;

package/package.json

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

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/.gitignore.template

@@ -118,4 +118,5 @@ libs/*/client.ts
 libs/*/server.ts
 libs/*/index.ts
 **/.akan
-**/bun.lock
+**/bun.lock
+**/tsconfig.tsbuildinfo

package/templates/workspaceRoot/AGENTS.md.template

@@ -576,3 +576,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 -->