@akanjs/devkit 2.3.11-rc.1 → 2.3.11-rc.10

package/akanApp/akanApp.host.ts

@@ -11,6 +11,7 @@ const BACKEND_RESTART_DEBOUNCE_MS = 120;
 const BACKEND_GRACEFUL_TIMEOUT_MS = 3000;
 const BACKEND_RECOVERY_BASE_DELAY_MS = 1_000;
 const BACKEND_RECOVERY_MAX_DELAY_MS = 30_000;
+const BACKEND_STDERR_TAIL_LIMIT = 40;
 const BUILDER_READY_TIMEOUT_MS = 150000;
 const BUILDER_START_MAX_ATTEMPTS = 3;
 const SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
@@ -270,6 +271,7 @@ export class AkanAppHost {
   #pendingRestartReason: BackendRestartReason | null = null;
   #backendStartStatus: { generation?: number; files: string[] } | null = null;
   #backendBuildStatusGeneration = 0;
+  #backendStderrTail: string[] = [];
   #lastGoodFrontend: LastGoodFrontendState = {};
   #buildStatusByPhase = new Map<BuildPhase, DevBuildStatus>();
   #pendingBuildStatusReplay: DevBuildStatus[] = [];
@@ -321,6 +323,7 @@ export 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"],
@@ -351,6 +354,38 @@ export class AkanAppHost {
     });
     this.#backend = backend;
     this.logger.verbose(`backend spawned pid=${backend.pid}`);
+    if (this.withInk) {
+      // Ink mode pipes backend stdio to keep the TUI clean; drain the pipes and surface
+      // them through the logger so runtime errors are not silently swallowed.
+      void this.#forwardBackendStream(backend.stderr as unknown as ReadableStream<Uint8Array> | undefined, "stderr");
+      void this.#forwardBackendStream(backend.stdout as unknown as ReadableStream<Uint8Array> | undefined, "stdout");
+    }
+  }
+  #recordBackendStderr(chunk: string) {
+    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: ReadableStream<Uint8Array> | undefined | null, kind: "stdout" | "stderr") {
+    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 {
+      // The stream closes when the backend exits; nothing further to surface here.
+    }
   }
   #nextBackendBuildStatusGeneration(generation?: number): number {
     if (typeof generation === "number") {
@@ -482,6 +517,9 @@ export class AkanAppHost {
     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:\n${this.#backendStderrTail.join("\n")}`);
+    }
     this.#backendRecoveryTimer = setTimeout(() => {
       this.#backendRecoveryTimer = null;
       if (this.#backend) return;

package/akanConfig/akanConfig.ts

@@ -171,9 +171,7 @@ export class AkanAppConfig implements AppConfigResult {
       targets: rawTargets,
       indexPath: _indexPath,
       ...rawMobile
-    } = (mobile ?? {}) as DeepPartial<AkanMobileConfig> & {
-      indexPath?: unknown;
-    };
+    } = (mobile ?? {}) as DeepPartial<AkanMobileConfig> & { indexPath?: unknown };
     const appName = rawMobile.appName ?? this.app.name;
     const appId = rawMobile.appId ?? `com.${this.app.name}.app`;
     const version = rawMobile.version ?? "0.0.1";

package/akanContext.ts

@@ -119,6 +119,10 @@ export type JsonRpcRequest = {
 export type McpFraming = "content-length" | "newline";
 export type AkanMcpMode = "readonly" | "plan" | "apply";
 
+// Coding-agent tools that can host the Akan MCP server. Cursor and Claude Code both read a JSON
+// `mcpServers` map; Codex reads a TOML `[mcp_servers.<name>]` table.
+export type AkanMcpInstallTarget = "cursor" | "claude" | "codex";
+
 export type CursorMcpConfig = {
   mcpServers?: Record<string, unknown>;
 };
@@ -133,17 +137,79 @@ export const resourceList = [
 ];
 
 export const cursorMcpConfigPath = ".cursor/mcp.json";
+// Claude Code reads project-scoped MCP servers from `.mcp.json` at the workspace root.
+export const claudeMcpConfigPath = ".mcp.json";
+// Codex reads project-scoped config (trusted projects) from `.codex/config.toml`.
+export const codexMcpConfigPath = ".codex/config.toml";
+
+export const akanMcpInstallTargets: AkanMcpInstallTarget[] = ["cursor", "claude", "codex"];
+
+export const akanMcpInstallConfigPaths: Record<AkanMcpInstallTarget, string> = {
+  cursor: cursorMcpConfigPath,
+  claude: claudeMcpConfigPath,
+  codex: codexMcpConfigPath,
+};
 
+// `akan mcp` resolves the workspace from process.cwd(), so every launcher must run it from the
+// workspace root. Cursor expands its own ${workspaceFolder} variable. Claude Code does not guarantee
+// the server's cwd but sets CLAUDE_PROJECT_DIR in its environment, so we cd into that at runtime.
+// Codex inherits its own launch cwd (it also discovers .codex/config.toml from cwd), so it runs the
+// command directly and must be started from the workspace root.
 const cursorWorkspaceFolder = "$" + "{workspaceFolder}";
+const claudeProjectDir = "$CLAUDE_PROJECT_DIR";
+
+const akanMcpCommand = (mode: AkanMcpMode, { cd }: { cd?: string } = {}) =>
+  cd ? `cd "${cd}" && akan mcp --mode ${mode}` : `akan mcp --mode ${mode}`;
 
 export const createAkanCursorMcpServer = (mode: AkanMcpMode = "readonly") => ({
   type: "stdio",
   command: "bash",
-  args: ["-lc", `cd "${cursorWorkspaceFolder}" && akan mcp --mode ${mode}`],
+  args: ["-lc", akanMcpCommand(mode, { cd: cursorWorkspaceFolder })],
+});
+
+export const createAkanClaudeMcpServer = (mode: AkanMcpMode = "readonly") => ({
+  type: "stdio",
+  command: "bash",
+  args: ["-lc", akanMcpCommand(mode, { cd: claudeProjectDir })],
 });
 
+// JSON-config targets (Cursor, Claude Code) share the same `mcpServers` entry shape.
+export const createAkanMcpServer = (target: "cursor" | "claude", mode: AkanMcpMode = "readonly") =>
+  target === "cursor" ? createAkanCursorMcpServer(mode) : createAkanClaudeMcpServer(mode);
+
 export const akanCursorMcpServer = createAkanCursorMcpServer();
 
+// Codex config is TOML and we have no TOML serializer, so we build the `[mcp_servers.akan]` table as text.
+export const codexMcpServerTableHeader = "[mcp_servers.akan]";
+export const createAkanCodexMcpServerBlock = (mode: AkanMcpMode = "readonly") =>
+  `${codexMcpServerTableHeader}\ncommand = "bash"\nargs = ["-lc", "${akanMcpCommand(mode)}"]\n`;
+
+// A TOML table runs from its header until the next top-level `[header]` or EOF. We upsert only the
+// akan table and preserve everything else in the file, mirroring the JSON merge behavior.
+const codexAkanTablePattern = /^\[mcp_servers\.akan\][^\n]*\n(?:(?!\[)[^\n]*(?:\n|$))*/m;
+
+export const upsertCodexMcpServerBlock = (
+  existing: string,
+  block: string,
+  { force = false }: { force?: boolean } = {},
+) => {
+  const nextBlock = block.endsWith("\n") ? block : `${block}\n`;
+  const match = existing.match(codexAkanTablePattern);
+  if (!match) {
+    if (!existing.trim()) return nextBlock;
+    return `${existing.replace(/\s*$/, "")}\n\n${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);
+  // The matched table absorbed its trailing blank line, so re-insert one before any following table.
+  const separator = after && !after.startsWith("\n") ? "\n" : "";
+  return `${before}${nextBlock}${separator}${after}`;
+};
+
 export const renderDoctorText = (result: AkanDoctorResult) => {
   const lines = [`Akan doctor status: ${result.status}`];
   if (result.diagnostics.length === 0) {
@@ -189,7 +255,6 @@ const generatedFiles = [
   "*/lib/cnst.ts",
   "*/lib/db.ts",
   "*/lib/dict.ts",
-  "*/lib/option.ts",
   "*/lib/sig.ts",
   "*/lib/srv.ts",
   "*/lib/st.ts",

package/applicationTestPreload.ts

@@ -32,9 +32,14 @@ export async function resolveSignalTestPreloadPath(target: SignalTestPreloadTarg
     path.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}.\nProbed paths:\n${uniqueCandidates
+      .map((candidate) => `  - ${candidate}`)
+      .join("\n")}`,
+  );
 }

package/artifact/implicitRootLayout.ts

@@ -16,6 +16,38 @@ async function appHasStModule(appCwdPath: string): Promise<boolean> {
 
 const IMPLICIT_LAYOUT_DIR = path.join(".akan", "generated", "root-layouts");
 const IMPLICIT_DICT_DIR = path.join(".akan", "generated", "dict");
+const IMPLICIT_OVERRIDES_DIR = path.join(".akan", "generated", "overrides");
+const OVERRIDES_KEY_RE = /^\.\/(.+\/)?_overrides\.(tsx|ts|jsx|js)$/;
+
+/**
+ * A `_overrides.tsx` manifest is a plain, server-safe module (`export default override({ Modal: BrandModal })`)
+ * with no `"use client"` directive. The `UiOverrideProvider` that consumes it is a client component, so the
+ * build emits a `"use client"` wrapper layout that reads the manifest's default map and mounts the provider
+ * around the subtree. As a normal `"use client"` module the wrapper participates in client-entry discovery and
+ * the RSC client manifest, so the server (as a client reference) and the client (as the real component) both
+ * resolve it — and the author never writes `"use client"`.
+ */
+async function writeGeneratedOverridesLayoutFile(opts: {
+  appCwdPath: string;
+  key: string;
+  userAbsPath: string;
+}): Promise<string> {
+  const filename = `${opts.key.replace(/^\.\//, "").replace(/[^a-zA-Z0-9]+/g, "_")}.tsx`;
+  const absPath = path.join(path.resolve(opts.appCwdPath), IMPLICIT_OVERRIDES_DIR, filename);
+  const userRel = path.relative(path.dirname(absPath), opts.userAbsPath).split(path.sep).join("/");
+  const userSpecifier = userRel.startsWith(".") ? userRel : `./${userRel}`;
+  const source = `"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, source);
+  return absPath;
+}
 
 interface RootBoundary {
   sourceKey: string | null;
@@ -261,12 +293,25 @@ export async function resolveSsrPageEntries(opts: {
       return segments !== null && isRootBoundarySegments(segments, basePaths);
     }),
   );
-  const base = opts.pageKeys
-    .filter((key) => !rootLayoutKeys.has(key))
-    .map((key) => ({
-      key,
-      moduleAbsPath: path.resolve(absPageDir, key),
-    }));
+  const base = await Promise.all(
+    opts.pageKeys
+      .filter((key) => !rootLayoutKeys.has(key))
+      .map(async (key) => {
+        const userAbsPath = path.resolve(absPageDir, key);
+        // `_overrides.tsx` is served through a generated `"use client"` wrapper layout that mounts the provider,
+        // so the author writes no directive; the raw manifest becomes a build seed so its slot components (and
+        // the manifest itself) enter the client graph / RSC client manifest.
+        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),

package/artifact/routeSeedIndex.ts

@@ -50,7 +50,9 @@ export function computeRouteSeedIndex(pageEntries: PageEntry[]): RouteSeedIndex
   for (const { key, moduleAbsPath, seedAbsPaths } of pageEntries) {
     const parsed = parseRouteModuleKey(key);
     const files = [path.resolve(moduleAbsPath), ...(seedAbsPaths ?? []).map((seed) => path.resolve(seed))];
-    if (parsed.kind === "layout") {
+    if (parsed.kind === "layout" || parsed.kind === "overrides") {
+      // Overrides seed the client graph like layouts: every route under the prefix must pull the generated
+      // `"use client"` override wrapper (and its slot components) into the client bundle / RSC client manifest.
       const prefix = parsed.routeSegments.join("/");
       const prev = layoutsByPrefix.get(prefix) ?? [];
       layoutsByPrefix.set(prefix, [...prev, ...files]);

package/capacitorApp.ts

@@ -26,6 +26,7 @@ interface RunIosConfig extends RunConfig {
 interface PrepareConfig extends RunConfig {}
 
 type MobileCommandEnv = Record<string, string | undefined>;
+type IosApnsEnvironment = "development" | "production";
 
 export type IosRunTargetKind = "device" | "simulator";
 export interface IosRunTarget {
@@ -130,6 +131,9 @@ const asString = (value: unknown) => (typeof value === "string" ? value : undefi
 
 const firstString = (...values: unknown[]) => values.find((value): value is string => typeof value === "string");
 
+const resolveIosApnsEnvironment = ({ operation }: Pick<RunConfig, "operation" | "env">): IosApnsEnvironment =>
+  operation === "release" ? "production" : "development";
+
 const scoreIosDeviceTarget = (target: IosRunTarget) => {
   const state = target.state?.toLowerCase() ?? "";
   return (state.includes("available") ? 4 : 0) + (state.includes("wired") ? 2 : 0) + (state.includes("paired") ? 1 : 0);
@@ -486,6 +490,10 @@ export function materializeCapacitorConfig(
   const experimentalConfig = isRecord(experimental) ? experimental : undefined;
   const pluginsConfig = isRecord(plugins) ? plugins : {};
   const keyboardPluginConfig = isRecord(pluginsConfig.Keyboard) ? pluginsConfig.Keyboard : {};
+  const pushNotificationsPluginConfig = isRecord(pluginsConfig.PushNotifications)
+    ? pluginsConfig.PushNotifications
+    : {};
+  const usesPushNotifications = target.permissions?.includes("push") ?? false;
   const config: CapacitorConfig = {
     ...capacitorConfig,
     appId,
@@ -494,6 +502,14 @@ export function materializeCapacitorConfig(
     plugins: {
       CapacitorCookies: { enabled: true },
       ...pluginsConfig,
+      ...(usesPushNotifications || isRecord(pluginsConfig.PushNotifications)
+        ? {
+            PushNotifications: {
+              ...(usesPushNotifications ? { presentationOptions: ["badge", "sound", "alert"] } : {}),
+              ...pushNotificationsPluginConfig,
+            },
+          }
+        : {}),
       Keyboard: {
         resize: "none",
         ...keyboardPluginConfig,
@@ -587,7 +603,7 @@ export 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 });
@@ -749,7 +765,7 @@ export class CapacitorApp {
     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 });
@@ -975,12 +991,12 @@ export class CapacitorApp {
     await this.project.android.setVersionCode(this.target.buildNum);
     await this.project.android.setAppName(this.target.appName);
   }
-  async #applyPermissions() {
+  async #applyPermissions({ operation, env }: Pick<RunConfig, "operation" | "env">) {
     for (const permission of this.target.permissions ?? []) {
       if (permission === "camera") await this.addCamera();
       else if (permission === "contacts") await this.addContact();
       else if (permission === "location") await this.addLocation();
-      else if (permission === "push") await this.addPush();
+      else if (permission === "push") await this.addPush({ operation, env });
     }
   }
   async #applyDeepLinks(platform: "ios" | "android", { operation, env }: Pick<RunConfig, "operation" | "env">) {
@@ -996,7 +1012,7 @@ export class CapacitorApp {
         });
         await this.#setUrlSchemesInIos(schemes);
       }
-      if (domains.length > 0) await this.#setAssociatedDomainsInIos(domains);
+      if (domains.length > 0) await this.#setAssociatedDomainsInIos(domains, { operation, env });
       return;
     }
     if (platform === "android") {
@@ -1103,12 +1119,58 @@ export class CapacitorApp {
     this.#setPermissionsInAndroid(["ACCESS_COARSE_LOCATION", "ACCESS_FINE_LOCATION"]);
     this.#setFeaturesInAndroid(["android.hardware.location.gps"]);
   }
-  async addPush() {
+  async addPush({ operation, env }: Pick<RunConfig, "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 = path.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\nimport FirebaseCore");
+    }
+    if (!content.includes("import FirebaseMessaging")) {
+      content = content.replace("import FirebaseCore", "import FirebaseCore\nimport FirebaseMessaging");
+    }
+    if (!content.includes("FirebaseApp.configure()")) {
+      content = content.replace(/\n(\s*)return true/, "\n$1FirebaseApp.configure()\n\n$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("\n    func applicationWillResignActive", `${delegateMethods}\n    func applicationWillResignActive`);
+    }
+
+    if (content !== editor.getContent()) await editor.setContent(content).save();
+  }
   async #setPermissionInIos(permissions: { [key: string]: string }) {
     const updateNs = Object.fromEntries(
       Object.entries(permissions).map(([key, value]) => [`NS${capitalize(key)}`, value]),
@@ -1128,24 +1190,37 @@ export class CapacitorApp {
       this.project.ios.updateInfoPlist(this.iosTargetName, "Release", { CFBundleURLTypes: urlTypes }),
     ]);
   }
-  async #setAssociatedDomainsInIos(domains: string[]) {
+  async #setAssociatedDomainsInIos(domains: string[], { operation, env }: Pick<RunConfig, "operation" | "env">) {
+    await this.#writeEntitlementsInIos(domains, { operation, env });
+  }
+  async #writeEntitlementsInIos(domains: string[], runConfig: Pick<RunConfig, "operation" | "env">) {
     const entitlementsRelPath = "App/App.entitlements";
     const entitlementsPath = path.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("\n");
-    await writeFile(entitlementsPath, body);
+    const currentBody = (await Bun.file(entitlementsPath).exists())
+      ? await Bun.file(entitlementsPath).text()
+      : undefined;
+    if (currentBody !== body) await writeFile(entitlementsPath, body);
     await this.#setCodeSignEntitlementsInIos(entitlementsRelPath);
   }
   async #setCodeSignEntitlementsInIos(entitlementsRelPath: string) {
@@ -1236,7 +1311,7 @@ export class CapacitorApp {
     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
@@ -1253,6 +1328,6 @@ export class CapacitorApp {
     return Array.from(usesPermission).map((permission) => permission.getAttribute("android:name"));
   }
   #hasPermissionInAndroid(permission: string) {
-    return this.#getPermissionsInAndroid().includes(permission);
+    return this.#getPermissionsInAndroid().includes(`android.permission.${permission}`);
   }
 }

package/executors.test.ts

@@ -140,7 +140,7 @@ describe("Executor filesystem helpers", () => {
     expect(await readFile(path.join(root, "workspace/.env"), "utf8")).toContain("AKAN_PUBLIC_REPO_NAME");
     expect(await readFile(path.join(root, "workspace/.vscode/settings.json"), "utf8")).toContain("typescript.tsdk");
     expect(await readFile(path.join(root, "workspace/.cursor/rules/akan.mdc"), "utf8")).toContain(
-      "Akan.js Workspace Rules",
+      "Akan workspace agent guide",
     );
     expect(await readFile(path.join(root, "workspace/AGENTS.md"), "utf8")).toContain("sample Agent Guide");
     expect(await readFile(path.join(root, "workspace/docs/AI-DEVELOPMENT.md"), "utf8")).toContain(

package/executors.ts

@@ -10,6 +10,7 @@ import {
 import { readFileSync } from "node:fs";
 import { copyFile, mkdir, readdir as readDirEntries, stat } from "node:fs/promises";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 import {
   capitalize,
   isRouteSourceFile,
@@ -23,6 +24,11 @@ import chalk from "chalk";
 import ts from "typescript";
 import { AkanAppConfig, AkanLibConfig, decreaseBuildNum, increaseBuildNum } from "./akanConfig";
 import { FileSys } from "./fileSys";
+import {
+  createFirebaseMessagingServiceWorker,
+  type FirebaseClientEnvConfig,
+  normalizeFirebaseClientConfig,
+} from "./firebaseMessagingSw";
 import { getDirname } from "./getDirname";
 import { Linter } from "./linter";
 import { AppInfo, LibInfo, PkgInfo, WorkspaceInfo } from "./scanInfo";
@@ -256,6 +262,43 @@ function validateRouteSourceExports(
   }
 }
 
+/**
+ * Statically enforces that a `_overrides.tsx` route file is a logic-free activation manifest: a plain module
+ * (no `"use client"` — the framework generates the client wrapper) that only imports components and binds them
+ * to slots through a single `export default override({ Modal: BrandModal })`. It must not declare components
+ * inline or run logic — that keeps the override contract a thin binding layer rather than a second place to
+ * author UI. Slot names and value types are validated at compile time by `override`.
+ */
+function validateOverridesSourceExports(source: string, filePath: string) {
+  const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const fail = (message: string): never => {
+    throw new Error(`[route-convention] ${message}: ${filePath}`);
+  };
+  let defaultOverride: ts.ExportAssignment | null = null;
+  for (const statement of sourceFile.statements) {
+    // A "use client" directive is unnecessary (the framework wraps the manifest) but harmless if present.
+    if (ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression)) continue;
+    // The manifest imports the app components it binds; imports and type-only decls carry no runtime logic.
+    if (ts.isImportDeclaration(statement)) continue;
+    if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) continue;
+    if (ts.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 (
+    !ts.isCallExpression(expression) ||
+    !ts.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 })"`,
+    );
+}
+
 export class Executor {
   static verbose = false;
   static setVerbose(verbose: boolean) {
@@ -1392,6 +1435,12 @@ export class AppExecutor extends SysExecutor {
       ...routeEnv,
       ...(devPort ? { PORT: devPort, AKAN_PUBLIC_CLIENT_PORT: devPort, AKAN_PUBLIC_SERVER_PORT: devPort } : {}),
     });
+    // `start` spawns subprocesses that carry `env`, but `build` runs its phases in this same process and
+    // reads `process.env` directly. Publish the resolved env here so SSR/CSR bundling (fed by getPublicEnv,
+    // which filters to AKAN_PUBLIC_*) sees AKAN_PUBLIC_APP_NAME — otherwise SSR throws
+    // "environment variable AKAN_PUBLIC_APP_NAME is required". Only AKAN_PUBLIC_* is baked into bundles, so
+    // this does not leak non-public env.
+    if (type === "build") Object.assign(process.env, env);
     return { env };
   }
   #publicEnv: Record<string, string> | null = null;
@@ -1454,7 +1503,9 @@ export 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();
@@ -1497,8 +1548,28 @@ export class AppExecutor extends SysExecutor {
       writeLib: write,
     })) as AppInfo;
     if (write) await this.syncAssets(scanInfo.getScanResult().libDeps);
+    if (write) await this.#syncFirebaseMessagingSw();
     return scanInfo;
   }
+  //* firebase config 가 있으면 public/firebase-messaging-sw.js 를 1회 생성한다(있으면 스킵).
+  //* 서버 동적 라우트를 대체하는 정적 파일. env.client 파생이라 gitignore 되고 env 별로 재생성된다.
+  async #syncFirebaseMessagingSw() {
+    const swRelPath = "public/firebase-messaging-sw.js";
+    if (await FileSys.fileExists(this.getPath(swRelPath))) return;
+    const envClientPath = path.join(this.cwdPath, "env", "env.client.ts");
+    if (!(await FileSys.fileExists(envClientPath))) return;
+    let firebaseConfig: FirebaseClientEnvConfig | null = null;
+    try {
+      const envUrl = pathToFileURL(envClientPath);
+      envUrl.searchParams.set("t", String(Date.now()));
+      const envModule = (await import(envUrl.href)) as { env?: { firebase?: unknown } };
+      firebaseConfig = normalizeFirebaseClientConfig(envModule.env?.firebase);
+    } catch {
+      return;
+    }
+    if (!firebaseConfig) return;
+    await this.writeFile(swRelPath, createFirebaseMessagingServiceWorker(firebaseConfig), { overwrite: false });
+  }
   async increaseBuildNum() {
     await increaseBuildNum(this);
   }