@akanjs/cli 2.3.11-rc.0 → 2.3.11-rc.10

package/index.js

@@ -664,6 +664,7 @@ import {
 import { readFileSync as readFileSync3 } from "fs";
 import { copyFile, mkdir as mkdir2, readdir as readDirEntries, stat as stat2 } from "fs/promises";
 import path7 from "path";
+import { pathToFileURL } from "url";
 import {
   capitalize,
   isRouteSourceFile,
@@ -1105,6 +1106,63 @@ var decreaseBuildNum = async (app) => {
   const akanConfigContent = akanConfig.replace(`buildNum: ${appConfig.mobile.buildNum}`, `buildNum: ${appConfig.mobile.buildNum - 1}`);
   fs.writeFileSync(akanConfigPath, akanConfigContent);
 };
+// pkgs/@akanjs/devkit/firebaseMessagingSw.ts
+var FIREBASE_WEB_SDK_VERSION = "12.13.0";
+function normalizeFirebaseClientConfig(config) {
+  if (!config || typeof config !== "object")
+    return null;
+  const value = config;
+  if (typeof value.apiKey !== "string" || typeof value.projectId !== "string" || typeof value.messagingSenderId !== "string" || typeof value.appId !== "string") {
+    return null;
+  }
+  return {
+    apiKey: value.apiKey,
+    ...typeof value.authDomain === "string" ? { authDomain: value.authDomain } : {},
+    projectId: value.projectId,
+    ...typeof value.storageBucket === "string" ? { storageBucket: value.storageBucket } : {},
+    messagingSenderId: value.messagingSenderId,
+    appId: value.appId
+  };
+}
+function createFirebaseMessagingServiceWorker(config) {
+  const configJson = JSON.stringify(config);
+  return `/* Generated by Akan.js. Do not edit. */
+const firebaseConfig = ${configJson};
+
+if (firebaseConfig) {
+  importScripts("https://www.gstatic.com/firebasejs/${FIREBASE_WEB_SDK_VERSION}/firebase-app-compat.js");
+  importScripts("https://www.gstatic.com/firebasejs/${FIREBASE_WEB_SDK_VERSION}/firebase-messaging-compat.js");
+
+  firebase.initializeApp(firebaseConfig);
+  const messaging = firebase.messaging();
+
+  const notificationUrl = (payload) =>
+    payload?.data?.url || payload?.fcmOptions?.link || payload?.notification?.click_action;
+
+  messaging.onBackgroundMessage((payload) => {
+    const title = payload?.notification?.title || "";
+    const options = {
+      body: payload?.notification?.body,
+      icon: payload?.notification?.icon,
+      image: payload?.notification?.image,
+      data: {
+        url: notificationUrl(payload),
+        FCM_MSG: payload,
+      },
+    };
+    self.registration.showNotification(title, options);
+  });
+}
+
+self.addEventListener("notificationclick", (event) => {
+  const url = event.notification?.data?.url || event.notification?.data?.FCM_MSG?.data?.url;
+  event.notification?.close();
+  if (!url) return;
+  event.waitUntil(clients.openWindow(url));
+});
+`;
+}
+
 // pkgs/@akanjs/devkit/getDirname.ts
 import path2 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
@@ -1390,6 +1448,7 @@ ${errorText}, ${warningText} found`];
 
 // pkgs/@akanjs/devkit/scanInfo.ts
 import path5 from "path";
+import { rm } from "fs/promises";
 
 // pkgs/@akanjs/devkit/dependencyScanner.ts
 import { builtinModules } from "module";
@@ -1708,8 +1767,10 @@ var appRootAllowedFiles = new Set([
   "main.ts",
   "package.json",
   "server.ts",
-  "tsconfig.json"
+  "tsconfig.json",
+  "tsconfig.tsbuildinfo"
 ]);
+var generatedRootCapacitorConfigFiles = ["capacitor.config.js", "capacitor.config.json"];
 var appRootAllowedDirs = new Set([
   ".akan",
   "android",
@@ -1753,11 +1814,17 @@ var rootSignalTestFilePattern = /^[A-Za-z][A-Za-z0-9_-]*\.signal\.(test|spec)\.(
 var isAllowedTestFile = (filename) => testFilePattern.test(filename);
 var isAllowedLibRootFile = (filename) => libRootAllowedFiles.has(filename) || rootSignalTestFilePattern.test(filename);
 var getScanPath = (exec, relativePath) => path5.posix.join(`${exec.type}s`, exec.name, relativePath.split(path5.sep).join("/"));
+async function clearGeneratedRootCapacitorConfigs(exec) {
+  if (exec.type !== "app")
+    return;
+  await Promise.all(generatedRootCapacitorConfigFiles.map((filename) => rm(exec.getPath(filename), { force: true })));
+}
 var getModuleNameFromPath = (kind, modulePath) => {
   const dirname = path5.basename(modulePath);
   return kind === "service" ? dirname.replace(/^_+/, "") : dirname;
 };
 async function assertScanConvention(exec, libRoot) {
+  await clearGeneratedRootCapacitorConfigs(exec);
   const violations = [];
   const addViolation = (relativePath, reason) => {
     violations.push(`${getScanPath(exec, relativePath)}: ${reason}`);
@@ -2622,6 +2689,31 @@ function validateRouteSourceExports(source, filePath, kind, options = {}) {
     throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${filePath}`);
   }
 }
+function validateOverridesSourceExports(source, filePath) {
+  const sourceFile = ts3.createSourceFile(filePath, source, ts3.ScriptTarget.Latest, true, ts3.ScriptKind.TSX);
+  const fail = (message) => {
+    throw new Error(`[route-convention] ${message}: ${filePath}`);
+  };
+  let defaultOverride = null;
+  for (const statement of sourceFile.statements) {
+    if (ts3.isExpressionStatement(statement) && ts3.isStringLiteral(statement.expression))
+      continue;
+    if (ts3.isImportDeclaration(statement))
+      continue;
+    if (ts3.isInterfaceDeclaration(statement) || ts3.isTypeAliasDeclaration(statement))
+      continue;
+    if (ts3.isExportAssignment(statement) && !statement.isExportEquals) {
+      defaultOverride = statement;
+      continue;
+    }
+    fail(`_overrides.tsx may only contain imports and a single "export default override({ ... })"`);
+  }
+  if (!defaultOverride)
+    fail(`_overrides.tsx must "export default override({ ... })"`);
+  const expression = defaultOverride.expression;
+  if (!ts3.isCallExpression(expression) || !ts3.isIdentifier(expression.expression) || expression.expression.text !== "override")
+    fail(`_overrides.tsx default export must be a call to "override", e.g. "export default override({ Modal: BrandModal })"`);
+}
 
 class Executor {
   static verbose = false;
@@ -3574,6 +3666,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;
@@ -3643,7 +3737,11 @@ class AppExecutor extends SysExecutor {
         throw new Error(`[route-convention] __root_layout is reserved for Akan.js generated root layout: ${absPath}`);
       }
       const isRootLayout = parsed.kind === "layout" && parsed.moduleSegments.at(-1) === "_layout";
-      validateRouteSourceExports(await Bun.file(absPath).text(), absPath, parsed.kind, { rootLayout: isRootLayout });
+      const routeSource = await Bun.file(absPath).text();
+      if (parsed.kind === "overrides")
+        validateOverridesSourceExports(routeSource, absPath);
+      else
+        validateRouteSourceExports(routeSource, absPath, parsed.kind, { rootLayout: isRootLayout });
       pageKeys.push(key);
     }
     pageKeys.sort();
@@ -3684,8 +3782,30 @@ class AppExecutor extends SysExecutor {
     });
     if (write)
       await this.syncAssets(scanInfo.getScanResult().libDeps);
+    if (write)
+      await this.#syncFirebaseMessagingSw();
     return scanInfo;
   }
+  async#syncFirebaseMessagingSw() {
+    const swRelPath = "public/firebase-messaging-sw.js";
+    if (await FileSys.fileExists(this.getPath(swRelPath)))
+      return;
+    const envClientPath = path7.join(this.cwdPath, "env", "env.client.ts");
+    if (!await FileSys.fileExists(envClientPath))
+      return;
+    let firebaseConfig = null;
+    try {
+      const envUrl = pathToFileURL(envClientPath);
+      envUrl.searchParams.set("t", String(Date.now()));
+      const envModule = await import(envUrl.href);
+      firebaseConfig = normalizeFirebaseClientConfig(envModule.env?.firebase);
+    } catch {
+      return;
+    }
+    if (!firebaseConfig)
+      return;
+    await this.writeFile(swRelPath, createFirebaseMessagingServiceWorker(firebaseConfig), { overwrite: false });
+  }
   async increaseBuildNum() {
     await increaseBuildNum(this);
   }
@@ -4168,6 +4288,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 +4491,7 @@ class AkanAppHost {
   #pendingRestartReason = null;
   #backendStartStatus = null;
   #backendBuildStatusGeneration = 0;
+  #backendStderrTail = [];
   #lastGoodFrontend = {};
   #buildStatusByPhase = new Map;
   #pendingBuildStatusReplay = [];
@@ -4421,6 +4543,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 +4577,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 +4732,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)
@@ -4954,7 +5113,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) => {
@@ -5943,6 +6101,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 +6929,9 @@ var createWorkflowStepRegistry = ({
   createScalar,
   createUi,
   addField,
-  addEnumField
+  addEnumField,
+  addMutation,
+  addSlice
 }) => {
   const inspect = async () => {
     return;
@@ -6736,7 +7007,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 {
@@ -7483,13 +7766,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) {
@@ -7512,7 +7841,6 @@ var generatedFiles = [
   "*/lib/cnst.ts",
   "*/lib/db.ts",
   "*/lib/dict.ts",
-  "*/lib/option.ts",
   "*/lib/sig.ts",
   "*/lib/srv.ts",
   "*/lib/st.ts",
@@ -8506,7 +8834,7 @@ Caused by: ${ApplicationBuildReporter.formatError(error.cause)}` : "";
   }
 }
 // pkgs/@akanjs/devkit/applicationBuildRunner.ts
-import { mkdir as mkdir8, rm as rm3 } from "fs/promises";
+import { mkdir as mkdir8, rm as rm4 } from "fs/promises";
 import path37 from "path";
 
 // pkgs/@akanjs/devkit/frontendBuild/allRoutesBuilder.ts
@@ -8521,6 +8849,25 @@ async function appHasStModule(appCwdPath) {
 }
 var IMPLICIT_LAYOUT_DIR = path13.join(".akan", "generated", "root-layouts");
 var IMPLICIT_DICT_DIR = path13.join(".akan", "generated", "dict");
+var IMPLICIT_OVERRIDES_DIR = path13.join(".akan", "generated", "overrides");
+var OVERRIDES_KEY_RE = /^\.\/(.+\/)?_overrides\.(tsx|ts|jsx|js)$/;
+async function writeGeneratedOverridesLayoutFile(opts) {
+  const filename = `${opts.key.replace(/^\.\//, "").replace(/[^a-zA-Z0-9]+/g, "_")}.tsx`;
+  const absPath = path13.join(path13.resolve(opts.appCwdPath), IMPLICIT_OVERRIDES_DIR, filename);
+  const userRel = path13.relative(path13.dirname(absPath), opts.userAbsPath).split(path13.sep).join("/");
+  const userSpecifier = userRel.startsWith(".") ? userRel : `./${userRel}`;
+  const source2 = `"use client";
+import { UiOverrideProvider } from "akanjs/ui";
+import { createElement, type ReactNode } from "react";
+import value from ${JSON.stringify(userSpecifier)};
+
+export default function AkanUiOverridesLayout({ children }: { children?: ReactNode }) {
+  return createElement(UiOverrideProvider, { value }, children);
+}
+`;
+  await Bun.write(absPath, source2);
+  return absPath;
+}
 function getRootBoundarySegments(key) {
   const match = LAYOUT_KEY_RE.exec(key);
   if (!match)
@@ -8713,9 +9060,17 @@ async function resolveSsrPageEntries(opts) {
     const segments = getRootBoundarySegments(key);
     return segments !== null && isRootBoundarySegments(segments, basePaths);
   }));
-  const base = opts.pageKeys.filter((key) => !rootLayoutKeys.has(key)).map((key) => ({
-    key,
-    moduleAbsPath: path13.resolve(absPageDir, key)
+  const base = await Promise.all(opts.pageKeys.filter((key) => !rootLayoutKeys.has(key)).map(async (key) => {
+    const userAbsPath = path13.resolve(absPageDir, key);
+    if (OVERRIDES_KEY_RE.test(key)) {
+      const moduleAbsPath = await writeGeneratedOverridesLayoutFile({
+        appCwdPath: opts.appCwdPath,
+        key,
+        userAbsPath
+      });
+      return { key, moduleAbsPath, seedAbsPaths: [userAbsPath] };
+    }
+    return { key, moduleAbsPath: userAbsPath };
   }));
   const generated = await Promise.all(rootBoundaries.map(async (boundary) => ({
     key: implicitRootLayoutKey(boundary.segments),
@@ -8747,7 +9102,7 @@ function computeRouteSeedIndex(pageEntries) {
   for (const { key, moduleAbsPath, seedAbsPaths } of pageEntries) {
     const parsed = parseRouteModuleKey2(key);
     const files = [path14.resolve(moduleAbsPath), ...(seedAbsPaths ?? []).map((seed) => path14.resolve(seed))];
-    if (parsed.kind === "layout") {
+    if (parsed.kind === "layout" || parsed.kind === "overrides") {
       const prefix = parsed.routeSegments.join("/");
       const prev = layoutsByPrefix.get(prefix) ?? [];
       layoutsByPrefix.set(prefix, [...prev, ...files]);
@@ -10264,7 +10619,7 @@ class AllRoutesBuilder {
   }
 }
 // pkgs/@akanjs/devkit/frontendBuild/csrArtifactBuilder.ts
-import { mkdir as mkdir5, rm, unlink } from "fs/promises";
+import { mkdir as mkdir5, rm as rm2, unlink } from "fs/promises";
 import path24 from "path";
 
 // pkgs/@akanjs/devkit/frontendBuild/pagesEntrySourceGenerator.ts
@@ -10394,7 +10749,7 @@ class CsrArtifactBuilder {
     const artifact = await this.#loadCsrArtifact();
     const csrBasePaths = [...akanConfig2.basePaths];
     const htmlEntries = csrBasePaths.length > 0 ? csrBasePaths : ["index"];
-    await rm(this.#outputDir, { recursive: true, force: true });
+    await rm2(this.#outputDir, { recursive: true, force: true });
     await mkdir5(path24.join(this.#app.cwdPath, ".akan/generated/csr"), { recursive: true });
     const generatedHtmlFiles = Object.fromEntries(htmlEntries.map((basePath2) => this.#createHtmlFile(basePath2)));
     const result = await Bun.build({
@@ -11128,7 +11483,7 @@ class DevChangePlanner {
 }
 var uniqueResolved = (files) => [...new Set(files.map((file) => path27.resolve(file)))].sort();
 // pkgs/@akanjs/devkit/frontendBuild/devGeneratedIndexSync.ts
-import { mkdir as mkdir6, readdir as readdir2, readFile, rm as rm2, stat as stat3, writeFile } from "fs/promises";
+import { mkdir as mkdir6, readdir as readdir2, readFile, rm as rm3, stat as stat3, writeFile } from "fs/promises";
 import path28 from "path";
 var BARREL_FACETS2 = new Set(["common", "srvkit", "ui", "webkit"]);
 var FACET_SOURCE_FILE_RE = /\.(ts|tsx)$/;
@@ -11211,7 +11566,7 @@ class DevGeneratedIndexSync {
     if (content === null) {
       if (!await exists(indexPath))
         return false;
-      await rm2(indexPath, { force: true });
+      await rm3(indexPath, { force: true });
       return true;
     }
     const current = await readFile(indexPath, "utf8").catch(() => null);
@@ -12358,7 +12713,7 @@ class ApplicationBuildRunner {
     await this.#app.getPageKeys({ refresh: true });
     const { typecheckDir, tsconfigPath } = await this.#writeTypecheckTsconfig({ incremental });
     if (clean)
-      await rm3(path37.join(typecheckDir, "tsconfig.tsbuildinfo"), { force: true });
+      await rm4(path37.join(typecheckDir, "tsconfig.tsbuildinfo"), { force: true });
     await this.#checkProjectInChildProcess(tsconfigPath);
   }
   async#runPhase(id, label, task, summarize, options = {}) {
@@ -12558,7 +12913,7 @@ void run().catch((error) => {
   }
 }
 // pkgs/@akanjs/devkit/applicationReleasePackager.ts
-import { cp, mkdir as mkdir9, rm as rm4 } from "fs/promises";
+import { cp, mkdir as mkdir9, rm as rm5 } from "fs/promises";
 import path38 from "path";
 
 // pkgs/@akanjs/devkit/uploadRelease.ts
@@ -12665,7 +13020,7 @@ class ApplicationReleasePackager {
     const platformVersion = akanConfig2.mobile.version;
     const buildRoot = `${this.#app.workspace.workspaceRoot}/releases/builds/${this.#app.name}`;
     if (await FileSys.dirExists(buildRoot))
-      await rm4(buildRoot, { recursive: true, force: true });
+      await rm5(buildRoot, { recursive: true, force: true });
     await mkdir9(buildRoot, { recursive: true });
     if (rebuild || !await FileSys.dirExists(`${this.#app.dist.cwdPath}/backend`))
       await this.#build();
@@ -12674,7 +13029,7 @@ class ApplicationReleasePackager {
     await mkdir9(buildPath, { recursive: true });
     await cp(`${this.#app.dist.cwdPath}/backend`, `${buildPath}/backend`, { recursive: true });
     await cp(this.#app.dist.cwdPath, buildRoot, { recursive: true });
-    await rm4(`${buildRoot}/frontend/.next`, { recursive: true, force: true });
+    await rm5(`${buildRoot}/frontend/.next`, { recursive: true, force: true });
     const releaseRoot = this.#app.workspace.workspaceRoot;
     const releaseArchivePath = path38.relative(releaseRoot, `${releaseRoot}/releases/builds/${this.#app.name}-release.tar.gz`).split(path38.sep).join("/");
     await this.#app.workspace.spawn("tar", ["-zcf", releaseArchivePath, "-C", buildRoot, "./"], { cwd: releaseRoot });
@@ -12690,7 +13045,7 @@ class ApplicationReleasePackager {
       `${this.#app.workspace.workspaceRoot}/releases/builds/${this.#app.name}-appBuild.zip`,
       "./csr"
     ]);
-    await rm4("./csr", { recursive: true, force: true });
+    await rm5("./csr", { recursive: true, force: true });
   }
   async#writeSourceArchive({ readme }) {
     const sourceRoot = `${this.#app.workspace.workspaceRoot}/releases/sources/${this.#app.name}`;
@@ -12701,7 +13056,7 @@ class ApplicationReleasePackager {
     await Promise.all([".next", "ios", "android", "public/libs"].map(async (path39) => {
       const targetPath = `${sourceRoot}/apps/${this.#app.name}/${path39}`;
       if (await FileSys.dirExists(targetPath))
-        await rm4(targetPath, { recursive: true, force: true });
+        await rm5(targetPath, { recursive: true, force: true });
     }));
     const syncPaths = [".husky", ".gitignore", "package.json"];
     await Promise.all(syncPaths.map((path39) => cp(`${this.#app.workspace.cwdPath}/${path39}`, `${sourceRoot}/${path39}`, { recursive: true })));
@@ -12716,7 +13071,7 @@ class ApplicationReleasePackager {
       const maxRetry = 3;
       for (let i = 0;i < maxRetry; i++) {
         try {
-          await rm4(sourceRoot, { recursive: true, force: true });
+          await rm5(sourceRoot, { recursive: true, force: true });
         } catch {}
       }
     }
@@ -12805,11 +13160,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";
@@ -12945,7 +13304,7 @@ class Builder {
   }
 }
 // pkgs/@akanjs/devkit/capacitorApp.ts
-import { cp as cp2, mkdir as mkdir11, readFile as readFile2, rm as rm5, writeFile as writeFile2 } from "fs/promises";
+import { cp as cp2, mkdir as mkdir11, readFile as readFile2, rm as rm6, writeFile as writeFile2 } from "fs/promises";
 import os from "os";
 import path41 from "path";
 import { select as select2 } from "@inquirer/prompts";
@@ -13156,7 +13515,7 @@ var rootCapacitorConfigFilenames = [
 ];
 var rootCapacitorConfigPaths = (appRoot) => rootCapacitorConfigFilenames.map((file) => path41.join(appRoot, file));
 async function clearRootCapacitorConfigs(appRoot) {
-  await Promise.all(rootCapacitorConfigPaths(appRoot).map((file) => rm5(file, { force: true })));
+  await Promise.all(rootCapacitorConfigPaths(appRoot).map((file) => rm6(file, { force: true })));
 }
 async function writeRootCapacitorConfig(appRoot, content) {
   await clearRootCapacitorConfigs(appRoot);
@@ -13177,6 +13536,7 @@ var getLocalIP = () => {
 var isRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var asString = (value) => typeof value === "string" ? value : undefined;
 var firstString = (...values) => values.find((value) => typeof value === "string");
+var resolveIosApnsEnvironment = ({ operation }) => operation === "release" ? "production" : "development";
 var scoreIosDeviceTarget = (target) => {
   const state = target.state?.toLowerCase() ?? "";
   return (state.includes("available") ? 4 : 0) + (state.includes("wired") ? 2 : 0) + (state.includes("paired") ? 1 : 0);
@@ -13482,6 +13842,8 @@ function materializeCapacitorConfig(target, { operation, localServerUrl, localIp
   const experimentalConfig = isRecord2(experimental) ? experimental : undefined;
   const pluginsConfig = isRecord2(plugins) ? plugins : {};
   const keyboardPluginConfig = isRecord2(pluginsConfig.Keyboard) ? pluginsConfig.Keyboard : {};
+  const pushNotificationsPluginConfig = isRecord2(pluginsConfig.PushNotifications) ? pluginsConfig.PushNotifications : {};
+  const usesPushNotifications = target.permissions?.includes("push") ?? false;
   const config = {
     ...capacitorConfig,
     appId,
@@ -13490,6 +13852,12 @@ function materializeCapacitorConfig(target, { operation, localServerUrl, localIp
     plugins: {
       CapacitorCookies: { enabled: true },
       ...pluginsConfig,
+      ...usesPushNotifications || isRecord2(pluginsConfig.PushNotifications) ? {
+        PushNotifications: {
+          ...usesPushNotifications ? { presentationOptions: ["badge", "sound", "alert"] } : {},
+          ...pushNotificationsPluginConfig
+        }
+      } : {},
       Keyboard: {
         resize: "none",
         ...keyboardPluginConfig
@@ -13561,9 +13929,9 @@ class CapacitorApp {
     await mkdir11(this.targetRoot, { recursive: true });
     if (regenerate) {
       if (!platform || platform === "ios")
-        await rm5(path41.join(this.app.cwdPath, this.iosRootPath), { recursive: true, force: true });
+        await rm6(path41.join(this.app.cwdPath, this.iosRootPath), { recursive: true, force: true });
       if (!platform || platform === "android")
-        await rm5(path41.join(this.app.cwdPath, this.androidRootPath), { recursive: true, force: true });
+        await rm6(path41.join(this.app.cwdPath, this.androidRootPath), { recursive: true, force: true });
     }
     const project = this.project;
     await this.project.load();
@@ -13585,7 +13953,7 @@ class CapacitorApp {
     await this.#prepareTargetAssets();
     await this.#prepareExternalFiles("ios");
     await this.#applyIosMetadata();
-    await this.#applyPermissions();
+    await this.#applyPermissions({ operation, env });
     await this.#applyDeepLinks("ios", { operation, env });
     await this.project.commit();
     await this.#generateAssets({ operation, env });
@@ -13728,7 +14096,7 @@ ${error.message}`;
     await this.#prepareTargetAssets();
     await this.#prepareExternalFiles("android");
     await this.#applyAndroidMetadata();
-    await this.#applyPermissions();
+    await this.#applyPermissions({ operation, env });
     await this.#applyDeepLinks("android", { operation, env });
     await this.project.commit();
     await this.#generateAssets({ operation, env });
@@ -13862,7 +14230,7 @@ ${error.message}`;
     const htmlSource = path41.join(this.app.dist.cwdPath, "csr", targetHtmlFilename(this.target));
     if (!await Bun.file(htmlSource).exists())
       throw new Error(`CSR html for mobile target '${this.target.name}' not found: ${htmlSource}`);
-    await rm5(this.targetWebRoot, { recursive: true, force: true });
+    await rm6(this.targetWebRoot, { recursive: true, force: true });
     await mkdir11(this.targetWebRoot, { recursive: true });
     await Bun.write(path41.join(this.targetWebRoot, "index.html"), this.#injectMobileTargetMeta(await Bun.file(htmlSource).text()));
   }
@@ -13943,7 +14311,7 @@ ${error.message}`;
     await this.project.android.setVersionCode(this.target.buildNum);
     await this.project.android.setAppName(this.target.appName);
   }
-  async#applyPermissions() {
+  async#applyPermissions({ operation, env }) {
     for (const permission of this.target.permissions ?? []) {
       if (permission === "camera")
         await this.addCamera();
@@ -13952,7 +14320,7 @@ ${error.message}`;
       else if (permission === "location")
         await this.addLocation();
       else if (permission === "push")
-        await this.addPush();
+        await this.addPush({ operation, env });
     }
   }
   async#applyDeepLinks(platform, { operation, env }) {
@@ -13971,7 +14339,7 @@ ${error.message}`;
         await this.#setUrlSchemesInIos(schemes);
       }
       if (domains.length > 0)
-        await this.#setAssociatedDomainsInIos(domains);
+        await this.#setAssociatedDomainsInIos(domains, { operation, env });
       return;
     }
     if (platform === "android") {
@@ -14065,12 +14433,64 @@ ${error.message}`;
     this.#setPermissionsInAndroid(["ACCESS_COARSE_LOCATION", "ACCESS_FINE_LOCATION"]);
     this.#setFeaturesInAndroid(["android.hardware.location.gps"]);
   }
-  async addPush() {
+  async addPush({ operation, env }) {
     await this.#setPermissionInIos({
       userNotificationsUsageDescription: "$(PRODUCT_NAME) uses notifications to keep you updated."
     });
+    await Promise.all([
+      this.project.ios.updateInfoPlist(this.iosTargetName, "Debug", { UIBackgroundModes: ["remote-notification"] }),
+      this.project.ios.updateInfoPlist(this.iosTargetName, "Release", { UIBackgroundModes: ["remote-notification"] }),
+      this.#writeEntitlementsInIos(this.target.deepLinks?.domains ?? [], { operation, env }),
+      this.#ensurePushAppDelegateInIos()
+    ]);
     this.#setPermissionsInAndroid(["POST_NOTIFICATIONS"]);
   }
+  async#ensurePushAppDelegateInIos() {
+    const appDelegatePath = path41.join(this.app.cwdPath, this.iosProjectPath, "App/AppDelegate.swift");
+    if (!await Bun.file(appDelegatePath).exists())
+      return;
+    const editor = await FileEditor.create(appDelegatePath);
+    let content = editor.getContent();
+    if (!content.includes("import FirebaseCore")) {
+      content = content.replace("import Capacitor", `import Capacitor
+import FirebaseCore`);
+    }
+    if (!content.includes("import FirebaseMessaging")) {
+      content = content.replace("import FirebaseCore", `import FirebaseCore
+import FirebaseMessaging`);
+    }
+    if (!content.includes("FirebaseApp.configure()")) {
+      content = content.replace(/\n(\s*)return true/, `
+$1FirebaseApp.configure()
+
+$1return true`);
+    }
+    if (!content.includes("didRegisterForRemoteNotificationsWithDeviceToken")) {
+      const delegateMethods = `
+    func application(_ application: UIApplication,
+                     didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
+        Messaging.messaging().apnsToken = deviceToken
+        NotificationCenter.default.post(
+            name: .capacitorDidRegisterForRemoteNotifications,
+            object: deviceToken
+        )
+    }
+
+    func application(_ application: UIApplication,
+                     didFailToRegisterForRemoteNotificationsWithError error: Error) {
+        NotificationCenter.default.post(
+            name: .capacitorDidFailToRegisterForRemoteNotifications,
+            object: error
+        )
+    }
+`;
+      content = content.replace(`
+    func applicationWillResignActive`, `${delegateMethods}
+    func applicationWillResignActive`);
+    }
+    if (content !== editor.getContent())
+      await editor.setContent(content).save();
+  }
   async#setPermissionInIos(permissions) {
     const updateNs = Object.fromEntries(Object.entries(permissions).map(([key, value]) => [`NS${capitalize5(key)}`, value]));
     await Promise.all([
@@ -14088,25 +14508,35 @@ ${error.message}`;
       this.project.ios.updateInfoPlist(this.iosTargetName, "Release", { CFBundleURLTypes: urlTypes })
     ]);
   }
-  async#setAssociatedDomainsInIos(domains) {
+  async#setAssociatedDomainsInIos(domains, { operation, env }) {
+    await this.#writeEntitlementsInIos(domains, { operation, env });
+  }
+  async#writeEntitlementsInIos(domains, runConfig) {
     const entitlementsRelPath = "App/App.entitlements";
     const entitlementsPath = path41.join(this.app.cwdPath, this.iosProjectPath, entitlementsRelPath);
     const values = domains.map((domain) => `applinks:${domain}`);
+    const usesPush = this.target.permissions?.includes("push") ?? false;
+    const apsEnvironment = resolveIosApnsEnvironment(runConfig);
     const body = [
       '<?xml version="1.0" encoding="UTF-8"?>',
       '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
       '<plist version="1.0">',
       "<dict>",
-      "  <key>com.apple.developer.associated-domains</key>",
-      "  <array>",
-      ...values.map((value) => `    <string>${value}</string>`),
-      "  </array>",
+      ...usesPush ? ["  <key>aps-environment</key>", `  <string>${apsEnvironment}</string>`] : [],
+      ...values.length > 0 ? [
+        "  <key>com.apple.developer.associated-domains</key>",
+        "  <array>",
+        ...values.map((value) => `    <string>${value}</string>`),
+        "  </array>"
+      ] : [],
       "</dict>",
       "</plist>",
       ""
     ].join(`
 `);
-    await writeFile2(entitlementsPath, body);
+    const currentBody = await Bun.file(entitlementsPath).exists() ? await Bun.file(entitlementsPath).text() : undefined;
+    if (currentBody !== body)
+      await writeFile2(entitlementsPath, body);
     await this.#setCodeSignEntitlementsInIos(entitlementsRelPath);
   }
   async#setCodeSignEntitlementsInIos(entitlementsRelPath) {
@@ -14210,7 +14640,7 @@ ${filter}$1`);
     for (const permission of permissions) {
       if (this.#hasPermissionInAndroid(permission)) {
         this.app.logger.info(`${permission} already exists in android`);
-        return this;
+        continue;
       }
       this.app.logger.info(`Adding ${permission} to android`);
       this.project.android.getAndroidManifest().injectFragment("manifest", `<uses-permission android:name="android.permission.${permission}" />`);
@@ -14226,7 +14656,7 @@ ${filter}$1`);
     return Array.from(usesPermission).map((permission) => permission.getAttribute("android:name"));
   }
   #hasPermissionInAndroid(permission) {
-    return this.#getPermissionsInAndroid().includes(permission);
+    return this.#getPermissionsInAndroid().includes(`android.permission.${permission}`);
   }
 }
 // pkgs/@akanjs/devkit/commandDecorators/targetMeta.ts
@@ -15322,6 +15752,42 @@ var CONVENTION_SUFFIXES = [
   ".signal.ts",
   ".store.ts"
 ];
+var PAGE_RESERVED_EXPORTS = new Set([
+  "pageConfig",
+  "head",
+  "metadata",
+  "generateHead",
+  "generateMetadata",
+  "fonts",
+  "manifest",
+  "theme",
+  "reconnect",
+  "wsConnect",
+  "layoutStyle",
+  "gaTrackingId"
+]);
+var RULE_FIXES = {
+  "akan.global.duplicate-exported-function-name": "Rename one of the exports, or if they are the same thing, extract it into one shared module and import it in both places.",
+  "akan.global.duplicate-exported-function-body": "Extract the shared implementation into a single exported helper and import it, instead of copying the body.",
+  "akan.file.recommended-max-lines": "Split the file by responsibility \u2014 move Zones, Utils, or subcomponents into sibling files.",
+  "akan.file.max-lines": "Break the file into smaller focused modules; keep one primary responsibility per file.",
+  "akan.file.placeholder-export": "Remove the placeholder export; generated indexes should only re-export real modules.",
+  "akan.file.dictionary-stale-text": "Replace the scaffold text with real localized copy for this dictionary entry.",
+  "akan.file.global-declaration": "Move the global declaration into an approved low-level integration file (e.g. webkit) and keep it isolated.",
+  "akan.file.window-augmentation": "Move the Window augmentation into an approved browser integration file and keep it isolated.",
+  "akan.file.prototype-mutation": "Avoid prototype mutation, or isolate it in an approved low-level integration file.",
+  "akan.file.class-export-global-declaration": "Move the helper to a sibling file and import it into the class module.",
+  "akan.file.component-internal-declaration": "Move the type or helper to a type/util file in ui/, webkit/, or common/ by purpose. If it is the component's props, declare it as `interface <Component>Props`.",
+  "akan.file.component-export": "Move the value or type to a util/constant/type file in ui/, webkit/, or common/ and import it. Adding `export` is not a valid fix \u2014 only PascalCase components and their `<Component>Props` interface belong here.",
+  "akan.layout.app-root-file": "Move the file into a conventional app folder (common, env, lib, page, private, public, script, srvkit, ui, or webkit).",
+  "akan.layout.lib-root-file": "Move the file into a domain module folder under lib/; keep lib root limited to generated support facets.",
+  "akan.layout.module-ui-file": "Rename the file to an allowed module UI name, or move it to ui/ if it is not a module component."
+};
+function getRuleFix(rule) {
+  if (rule.startsWith("akan.convention"))
+    return "Keep only the model's allowed declarations in this file; move other logic to the matching domain file (service, document, store, etc.).";
+  return RULE_FIXES[rule];
+}
 
 class AkanQualityScanner {
   async scan(workspaceRoot) {
@@ -15330,13 +15796,14 @@ class AkanQualityScanner {
     const warnings = [
       ...this.#scanGlobalQuality(sourceFiles),
       ...sourceFiles.flatMap((sourceFile2) => this.#scanSingleFileQuality(sourceFile2)),
+      ...sourceFiles.flatMap((sourceFile2) => this.#scanComponentQuality(sourceFile2)),
       ...sourceFiles.flatMap((sourceFile2) => this.#scanConventionQuality(sourceFile2)),
       ...sourceFiles.flatMap((sourceFile2) => this.#scanLayoutQuality(sourceFile2))
     ];
     return {
       workspaceRoot,
       scannedFiles: sourceFiles.length,
-      warnings: warnings.sort(compareWarnings),
+      warnings: warnings.map((warning) => ({ ...warning, fix: warning.fix ?? getRuleFix(warning.rule) })).sort(compareWarnings),
       suggestedRules: SUGGESTED_RULES
     };
   }
@@ -15386,7 +15853,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({
@@ -15457,6 +15925,49 @@ class AkanQualityScanner {
     }
     return warnings;
   }
+  #scanComponentQuality(sourceFile2) {
+    if (!isComponentDeclarationFile(sourceFile2.file))
+      return [];
+    const isPage = isPageRouteFile(sourceFile2.file);
+    const declarations = getComponentFileDeclarations(sourceFile2.sourceFile);
+    const compoundComponentNames = getCompoundComponentNames(sourceFile2.sourceFile);
+    const componentNames = declarations.filter((declaration) => declaration.exported && isComponentValueKind(declaration.kind)).filter((declaration) => isPascalCaseName(declaration.name)).map((declaration) => declaration.name);
+    const allowedComponentNames = new Set([...componentNames, ...compoundComponentNames]);
+    const allowedPropsInterfaces = new Set([...allowedComponentNames].map((name) => `${name}Props`));
+    const warnings = [];
+    for (const declaration of declarations) {
+      if (declaration.isDefaultExport)
+        continue;
+      if (declaration.kind === "interface" && allowedPropsInterfaces.has(declaration.name))
+        continue;
+      if (declaration.exported) {
+        if (isAllowedComponentExport(declaration, isPage))
+          continue;
+        warnings.push({
+          rule: "akan.file.component-export",
+          scope: "file",
+          severity: "warning",
+          file: sourceFile2.file,
+          line: declaration.line,
+          message: `Component file exports ${declaration.kind} "${declaration.name}", which is not a PascalCase component${isPage ? " or reserved route export" : ""}.`
+        });
+        continue;
+      }
+      if (isComponentValueKind(declaration.kind) && compoundComponentNames.has(declaration.name))
+        continue;
+      if (isRestrictedInternalKind(declaration.kind)) {
+        warnings.push({
+          rule: "akan.file.component-internal-declaration",
+          scope: "file",
+          severity: "warning",
+          file: sourceFile2.file,
+          line: declaration.line,
+          message: `Component file declares non-exported ${declaration.kind} "${declaration.name}". Only "interface <Component>Props" may stay internal.`
+        });
+      }
+    }
+    return warnings;
+  }
   #scanConventionQuality(sourceFile2) {
     const suffix = CONVENTION_SUFFIXES.find((candidate) => sourceFile2.file.endsWith(candidate));
     if (!suffix)
@@ -15532,6 +16043,8 @@ function formatQualityWarnings(warnings) {
     if (warning.locations?.length) {
       lines.push(...warning.locations.map(({ file, line }) => `  note: related location ${formatQualityLocation(file, line)}`));
     }
+    if (warning.fix)
+      lines.push(`  fix: ${warning.fix}`);
     return lines;
   });
 }
@@ -15540,6 +16053,7 @@ function formatQualityLocation(file, line) {
 }
 function getExportedFunctionLikes(sourceFile2) {
   const declarations = [];
+  const nameExempt = isPageRouteFile(sourceFile2.file) || isUiComponentFile(sourceFile2.file);
   for (const statement of sourceFile2.sourceFile.statements) {
     if (ts11.isFunctionDeclaration(statement) && statement.name && isExported(statement)) {
       declarations.push({
@@ -15547,7 +16061,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: nameExempt || isConventionDuplicateNameExempt(sourceFile2.file, false)
       });
     }
     if (ts11.isClassDeclaration(statement) && statement.name && isExported(statement)) {
@@ -15556,7 +16071,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: nameExempt || isConventionDuplicateNameExempt(sourceFile2.file, isEnumClassStatement(sourceFile2.sourceFile, statement))
       });
     }
     if (ts11.isVariableStatement(statement) && isExported(statement)) {
@@ -15568,16 +16084,127 @@ 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: nameExempt || isConventionDuplicateNameExempt(sourceFile2.file, false)
         });
       }
     }
   }
   return declarations;
 }
+function isPageRouteFile(file) {
+  const segments = file.split("/");
+  return (segments[0] === "apps" || segments[0] === "libs") && segments[2] === "page";
+}
+function isUiComponentFile(file) {
+  const segments = file.split("/");
+  return (segments[0] === "apps" || segments[0] === "libs") && segments[2] === "ui";
+}
+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);
 }
+function isComponentDeclarationFile(file) {
+  if (!file.endsWith(".tsx"))
+    return false;
+  const segments = file.split("/");
+  const [root, , area] = segments;
+  if (root !== "apps" && root !== "libs")
+    return false;
+  if (area === "lib" || area === "ui")
+    return true;
+  return root === "apps" && area === "page";
+}
+function getComponentFileDeclarations(sourceFile2) {
+  const reExportedNames = new Set;
+  for (const statement of sourceFile2.statements) {
+    if (ts11.isExportDeclaration(statement) && statement.exportClause && ts11.isNamedExports(statement.exportClause)) {
+      for (const element of statement.exportClause.elements)
+        reExportedNames.add((element.propertyName ?? element.name).text);
+    }
+  }
+  const declarations = [];
+  for (const statement of sourceFile2.statements) {
+    const isDefaultExport = isDefaultExportStatement(statement);
+    const inlineExported = isExported(statement);
+    const add = (name, kind, line) => declarations.push({ name, kind, line, exported: inlineExported || reExportedNames.has(name), isDefaultExport });
+    if (ts11.isInterfaceDeclaration(statement))
+      add(statement.name.text, "interface", getLine(sourceFile2, statement));
+    else if (ts11.isTypeAliasDeclaration(statement))
+      add(statement.name.text, "type", getLine(sourceFile2, statement));
+    else if (ts11.isEnumDeclaration(statement))
+      add(statement.name.text, "enum", getLine(sourceFile2, statement));
+    else if (ts11.isFunctionDeclaration(statement) && statement.name)
+      add(statement.name.text, "function", getLine(sourceFile2, statement));
+    else if (ts11.isClassDeclaration(statement) && statement.name)
+      add(statement.name.text, "class", getLine(sourceFile2, statement));
+    else if (ts11.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts11.isIdentifier(declaration.name))
+          continue;
+        const kind = isFunctionLikeInitializer(declaration.initializer) ? "function" : "variable";
+        add(declaration.name.text, kind, getLine(sourceFile2, declaration));
+      }
+    }
+  }
+  return declarations;
+}
+function getCompoundComponentNames(sourceFile2) {
+  const names = new Set;
+  for (const statement of sourceFile2.statements) {
+    if (!ts11.isExpressionStatement(statement))
+      continue;
+    const { expression } = statement;
+    if (!ts11.isBinaryExpression(expression) || expression.operatorToken.kind !== ts11.SyntaxKind.EqualsToken)
+      continue;
+    if (!ts11.isPropertyAccessExpression(expression.left) || !isPascalCaseName(expression.left.name.text))
+      continue;
+    names.add(expression.left.name.text);
+    if (ts11.isIdentifier(expression.right) && isPascalCaseName(expression.right.text))
+      names.add(expression.right.text);
+  }
+  return names;
+}
+function isComponentValueKind(kind) {
+  return kind === "variable" || kind === "function" || kind === "class";
+}
+function isRestrictedInternalKind(kind) {
+  return kind === "interface" || kind === "type" || kind === "function";
+}
+function isAllowedComponentExport(declaration, isPage) {
+  if (isComponentValueKind(declaration.kind) && isPascalCaseName(declaration.name))
+    return true;
+  return isPage && PAGE_RESERVED_EXPORTS.has(declaration.name);
+}
+function isPascalCaseName(name) {
+  return /^[A-Z]/.test(name) && !/^[A-Z0-9_]+$/.test(name);
+}
+function isDefaultExportStatement(statement) {
+  if (ts11.isExportAssignment(statement))
+    return !statement.isExportEquals;
+  return !!(ts11.getCombinedModifierFlags(statement) & ts11.ModifierFlags.Default);
+}
 function getPlaceholderExportWarnings(sourceFile2) {
   if (!sourceFile2.file.endsWith("/index.ts") && !sourceFile2.file.endsWith("/index.tsx"))
     return [];
@@ -15593,11 +16220,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",
@@ -15718,10 +16341,8 @@ function getConventionDescription(suffix, modelName) {
 }
 function getLibRootFile(file) {
   const segments = file.split("/");
-  if (segments[0] === "libs" && segments.length === 4 && segments[2] === "lib")
+  if ((segments[0] === "libs" || segments[0] === "apps") && segments.length === 4 && segments[2] === "lib")
     return segments[3];
-  if (segments[0] === "apps" && segments.length === 5 && segments[2] === "lib")
-    return segments[4];
   return null;
 }
 function getModuleUiWarning(file) {
@@ -15862,26 +16483,61 @@ var targetPaths = {
   "agents-md": "AGENTS.md",
   claude: "CLAUDE.md"
 };
-var targetTitle = {
-  cursor: "Akan Cursor Rules",
-  "agents-md": "Akan Agent Rules",
-  claude: "Akan Claude Rules"
+var AGENT_BLOCK_START = "<!-- akan:agent:start -->";
+var AGENT_BLOCK_END = "<!-- akan:agent:end -->";
+var SAMPLE_ARTIFACTS = [
+  { probe: "lib/task/task.constant.ts", target: "lib/task", label: "sample database module" },
+  { probe: "lib/_noti/noti.service.ts", target: "lib/_noti", label: "sample service module" },
+  {
+    probe: "lib/__scalar/workHistory/workHistory.dictionary.ts",
+    target: "lib/__scalar/workHistory",
+    label: "sample scalar module"
+  },
+  { probe: "page/task/_index.tsx", target: "page/task", label: "sample task pages" }
+];
+var DEFAULT_INDEX_MARKER = "Akan.js template";
+var renderSampleCleanup = async (workspace, appNames) => {
+  const items = [];
+  for (const appName of appNames) {
+    for (const artifact2 of SAMPLE_ARTIFACTS) {
+      if (await workspace.exists(`apps/${appName}/${artifact2.probe}`)) {
+        items.push(`- \`apps/${appName}/${artifact2.target}\` \u2014 ${artifact2.label}; delete it once you no longer need the reference.`);
+      }
+    }
+    const indexPath = `apps/${appName}/page/_index.tsx`;
+    if (await workspace.exists(indexPath)) {
+      const content = await workspace.readFile(indexPath).catch(() => "");
+      if (content.includes(DEFAULT_INDEX_MARKER)) {
+        items.push(`- \`${indexPath}\` \u2014 default Akan landing page; replace it with your own home page.`);
+      }
+    }
+  }
+  if (items.length === 0)
+    return "";
+  return `## Start Clean (Remove Scaffolded Samples)
+
+This workspace was scaffolded with reference samples so the Akan conventions are visible in real code. They are
+not part of your product. Before building real features, remove the samples below and run \`akan sync <app>\`:
+
+${items.join(`
+`)}
+
+Keep a sample only while you are still learning its pattern; delete it once your own modules cover the same ground.
+
+`;
 };
-var renderAgentRules = async (workspace, target) => {
+var renderManagedBlock = async (workspace) => {
   const context = await AkanContextAnalyzer.analyze(workspace);
   const frameworkGuide = await Prompter.getInstruction("framework");
-  return `# ${targetTitle[target]}
-
-This file is generated by \`akan agent install ${target}\`.
-
-## Workspace
+  const sampleCleanup = await renderSampleCleanup(workspace, context.apps.map((app) => app.name));
+  return `## Workspace
 
 - Repo: ${context.repoName}
 - Apps: ${context.apps.map((app) => app.name).join(", ") || "none"}
 - Libraries: ${context.libs.map((lib) => lib.name).join(", ") || "none"}
 - Packages: ${context.pkgs.map((pkg) => pkg.name).join(", ") || "none"}
 
-## Akan Module Abstracts
+${sampleCleanup}## Akan Module Abstracts
 
 - Before changing a domain, service, or scalar module, read its \`*.abstract.md\` file first.
 - Update the abstract when business invariants, workflows, or public behavior change.
@@ -15903,6 +16559,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
 
@@ -15911,20 +16568,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;
@@ -17807,8 +18519,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,
@@ -17999,8 +18710,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." }
   ],
@@ -18072,9 +18793,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: [
@@ -18188,8 +18924,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."]
@@ -19386,6 +20121,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")) {
@@ -19584,6 +20325,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
@@ -19801,7 +20742,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
@@ -19852,14 +20795,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,
@@ -19868,9 +20815,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);
@@ -20162,13 +21115,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));
@@ -20177,11 +21143,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 });
@@ -20220,7 +21190,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"]
@@ -20605,7 +21575,7 @@ class LibraryCommand extends command("library", [LibraryScript], ({ public: targ
 }
 
 // pkgs/@akanjs/cli/localRegistry/localRegistry.runner.ts
-import { mkdir as mkdir13, rm as rm6 } from "fs/promises";
+import { mkdir as mkdir13, rm as rm7 } from "fs/promises";
 import path47 from "path";
 import { Logger as Logger19 } from "akanjs/common";
 var defaultLocalRegistryUrl = "http://127.0.0.1:4873";
@@ -20648,13 +21618,13 @@ class LocalRegistryRunner extends runner("localRegistry") {
     try {
       await workspace.spawn("docker", ["rm", "-f", containerName], { stdio: "inherit" });
     } catch {}
-    await rm6(path47.join(workspace.workspaceRoot, ".akan/verdaccio"), { recursive: true, force: true });
+    await rm7(path47.join(workspace.workspaceRoot, ".akan/verdaccio"), { recursive: true, force: true });
     Logger19.info("Local registry storage has been reset");
   }
   async smoke(workspace, { registryUrl } = {}) {
     const registry = this.getRegistryUrl(registryUrl);
     const smokeRoot = path47.join(workspace.workspaceRoot, ".akan/e2e");
-    await rm6(path47.join(smokeRoot, smokeRepoName), { recursive: true, force: true });
+    await rm7(path47.join(smokeRoot, smokeRepoName), { recursive: true, force: true });
     await workspace.spawn(process.execPath, [
       "dist/pkgs/create-akan-workspace/index.js",
       smokeRepoName,
@@ -20992,7 +21962,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;
@@ -21038,6 +22010,7 @@ import path48 from "path";
 var defaultWorkspacePeerDependencies = new Set([
   "@react-spring/web",
   "@use-gesture/react",
+  "chance",
   "croner",
   "daisyui",
   "react",