@akanjs/cli 2.3.9 → 2.3.10-rc.1

package/incrementalBuilder.proc.js

@@ -744,6 +744,44 @@ var DEFAULT_AKAN_IMAGE_CONFIG = {
   fetchTimeoutMs: 7000,
   maxRemoteBytes: 25 * 1024 * 1024
 };
+var normalizeIndexPath = (indexPath) => {
+  const normalized = indexPath?.trim();
+  if (!normalized)
+    return;
+  const path2 = `/${normalized.replace(/^\/+|\/+$/g, "")}`;
+  return path2 === "/" ? "/" : path2;
+};
+var normalizeStringList = (values) => {
+  const normalized = values?.map((value) => value.trim()).filter(Boolean) ?? [];
+  return normalized.length > 0 ? [...new Set(normalized)] : undefined;
+};
+var normalizeDeepLinkDomain = (domain) => {
+  const normalized = domain.trim();
+  if (!normalized)
+    return "";
+  try {
+    const url = new URL(normalized.includes("://") ? normalized : `https://${normalized}`);
+    return url.host.toLowerCase();
+  } catch {
+    return normalized.replace(/^https?:\/\//, "").replace(/\/+$/g, "").toLowerCase();
+  }
+};
+var normalizeDeepLinks = (deepLinks) => {
+  if (!deepLinks)
+    return;
+  const schemes = normalizeStringList(deepLinks.schemes);
+  const domains = normalizeStringList(deepLinks.domains?.map(normalizeDeepLinkDomain));
+  const teamId = deepLinks.ios?.teamId?.trim();
+  const sha256CertFingerprints = normalizeStringList(deepLinks.android?.sha256CertFingerprints);
+  if (!schemes && !domains && !teamId && !sha256CertFingerprints)
+    return;
+  return {
+    ...schemes ? { schemes } : {},
+    ...domains ? { domains } : {},
+    ...teamId ? { ios: { teamId } } : {},
+    ...sha256CertFingerprints ? { android: { sha256CertFingerprints } } : {}
+  };
+};
 
 class AkanAppConfig {
   app;
@@ -757,6 +795,7 @@ class AkanAppConfig {
   i18n;
   publicEnv;
   mobile;
+  secrets;
   baseDevEnv;
   libs;
   domains = new Set;
@@ -783,11 +822,16 @@ class AkanAppConfig {
     process.env.AKAN_PUBLIC_DEFAULT_LOCALE = this.i18n.defaultLocale;
     process.env.AKAN_PUBLIC_LOCALES = this.i18n.locales.join(",");
     this.publicEnv = config?.publicEnv ?? [];
+    this.secrets = config?.secrets ?? [];
     this.mobile = this.#resolveMobileConfig(config.mobile);
     this.docker = this.#makeDockerContent(config?.docker ?? {});
   }
   #resolveMobileConfig(mobile) {
-    const { targets: rawTargets, ...rawMobile } = mobile ?? {};
+    const {
+      targets: rawTargets,
+      indexPath: _indexPath,
+      ...rawMobile
+    } = mobile ?? {};
     const appName = rawMobile.appName ?? this.app.name;
     const appId = rawMobile.appId ?? `com.${this.app.name}.app`;
     const version = rawMobile.version ?? "0.0.1";
@@ -800,6 +844,8 @@ class AkanAppConfig {
       const target = rawTarget;
       const fallbackBasePath = !rawTargets && this.basePaths.has(name) ? name : undefined;
       const basePath2 = (target.basePath ?? fallbackBasePath)?.replace(/^\/+|\/+$/g, "") || undefined;
+      const indexPath = normalizeIndexPath(target.indexPath);
+      const deepLinks = normalizeDeepLinks(target.deepLinks);
       if (basePath2 && !this.basePaths.has(basePath2)) {
         throw new Error(`Mobile target '${name}' uses unknown basePath '${basePath2}' in apps/${this.app.name}/akan.config.ts`);
       }
@@ -808,6 +854,8 @@ class AkanAppConfig {
         ...target,
         name,
         basePath: basePath2,
+        indexPath,
+        deepLinks,
         appName: target.appName ?? appName,
         appId: target.appId ?? appId,
         version: target.version ?? version,
@@ -2746,8 +2794,8 @@ class Executor {
       return filePath;
     if (filePath.startsWith("."))
       return path7.join(this.cwdPath, filePath);
-    const baseParts = this.cwdPath.split("/").filter(Boolean);
-    const targetParts = filePath.split("/").filter(Boolean);
+    const baseParts = this.cwdPath.split(/[\\/]/).filter(Boolean);
+    const targetParts = filePath.split(/[\\/]/).filter(Boolean);
     let overlapLength = 0;
     for (let i = 1;i <= Math.min(baseParts.length, targetParts.length); i++) {
       let isOverlap = true;
@@ -2759,8 +2807,7 @@ class Executor {
       if (isOverlap)
         overlapLength = i;
     }
-    const result = overlapLength > 0 ? `/${[...baseParts, ...targetParts.slice(overlapLength)].join("/")}` : `${this.cwdPath}/${filePath}`;
-    return result.replace(/\/+/g, "/");
+    return path7.join(this.cwdPath, ...targetParts.slice(overlapLength));
   }
   async mkdir(dirPath) {
     const writePath = this.getPath(dirPath);
@@ -10225,6 +10272,7 @@ import path24 from "path";
 // pkgs/@akanjs/devkit/frontendBuild/pagesEntrySourceGenerator.ts
 import fs3 from "fs";
 import path23 from "path";
+import { pathToFileURL } from "url";
 import ts8 from "typescript";
 
 class PagesEntrySourceGenerator {
@@ -10237,8 +10285,8 @@ class PagesEntrySourceGenerator {
   }
   generate() {
     const lines = this.#pageEntries.map(({ key, moduleAbsPath }) => {
-      const absPath = path23.resolve(moduleAbsPath);
-      return `  ${JSON.stringify(key)}: () => import(${JSON.stringify(absPath)}),`;
+      const specifier = pathToFileURL(path23.resolve(moduleAbsPath)).href;
+      return `  ${JSON.stringify(key)}: () => import(${JSON.stringify(specifier)}),`;
     });
     return `export const pages = {
 ${lines.join(`
@@ -10251,8 +10299,8 @@ ${lines.join(`
   }
   generateStatic() {
     const imports = this.#pageEntries.map(({ moduleAbsPath }, index) => {
-      const absPath = path23.resolve(moduleAbsPath);
-      return `import * as page${index} from ${JSON.stringify(absPath)};`;
+      const specifier = pathToFileURL(path23.resolve(moduleAbsPath)).href;
+      return `import * as page${index} from ${JSON.stringify(specifier)};`;
     });
     const entries = this.#pageEntries.map(({ key, moduleAbsPath }, index) => {
       const isAsyncDefault = PagesEntrySourceGenerator.#hasAsyncDefaultExport(moduleAbsPath);
@@ -12116,7 +12164,14 @@ class SsrBaseArtifactBuilder {
       basePaths: [...akanConfig2.basePaths],
       branches: [...akanConfig2.branches],
       i18n: akanConfig2.i18n,
-      imageConfig: akanConfig2.images
+      imageConfig: akanConfig2.images,
+      deepLinkAssociations: Object.values(akanConfig2.mobile.targets).filter((target) => (target.deepLinks?.domains?.length ?? 0) > 0).map((target) => ({
+        targetName: target.name,
+        appId: target.appId,
+        domains: target.deepLinks?.domains ?? [],
+        iosTeamId: target.deepLinks?.ios?.teamId,
+        androidSha256CertFingerprints: target.deepLinks?.android?.sha256CertFingerprints
+      }))
     };
     await Bun.write(path35.join(this.#absArtifactDir, "base-artifact.json"), `${JSON.stringify(artifact, null, 2)}
 `);
@@ -12125,11 +12180,11 @@ class SsrBaseArtifactBuilder {
   }
   async#buildRuntimeClientEntries() {
     const akanServerPath = await this.#resolveAkanServerPath();
-    const rscClientEntry = `${akanServerPath}/rscClient.tsx`;
-    const rscSegmentOutletEntry = `${akanServerPath}/rscSegmentOutlet.tsx`;
+    const rscClientEntry = path35.resolve(akanServerPath, "rscClient.tsx");
+    const rscSegmentOutletEntry = path35.resolve(akanServerPath, "rscSegmentOutlet.tsx");
     const vendorEntries = VENDOR_SPECIFIERS.map((specifier) => ({
       specifier,
-      absPath: `${akanServerPath}/vendor/${specifier.replaceAll("/", "-").replaceAll(".", "-")}.ts`
+      absPath: path35.resolve(akanServerPath, "vendor", `${specifier.replaceAll("/", "-").replaceAll(".", "-")}.ts`)
     }));
     const entries = [rscClientEntry, rscSegmentOutletEntry, ...vendorEntries.map((v) => v.absPath)];
     const clientBundle = await new ClientEntriesBundler({ app: this.#app, entries, command: this.#command }).bundle();
@@ -12890,7 +12945,7 @@ class Builder {
   }
 }
 // pkgs/@akanjs/devkit/capacitorApp.ts
-import { cp as cp2, mkdir as mkdir11, rm as rm5 } from "fs/promises";
+import { cp as cp2, mkdir as mkdir11, readFile as readFile2, rm as rm5, writeFile as writeFile2 } from "fs/promises";
 import os from "os";
 import path41 from "path";
 import { select as select2 } from "@inquirer/prompts";
@@ -13404,11 +13459,12 @@ function materializeCapacitorConfig(target, { operation, localServerUrl, localIp
   const {
     name,
     basePath: _basePath,
+    indexPath: _indexPath,
     version: _version,
     buildNum: _buildNum,
     assets: _assets,
     permissions: _permissions,
-    links: _links,
+    deepLinks: _deepLinks,
     files: _files,
     appId,
     appName,
@@ -13530,7 +13586,7 @@ class CapacitorApp {
     await this.#prepareExternalFiles("ios");
     await this.#applyIosMetadata();
     await this.#applyPermissions();
-    await this.#applyLinks();
+    await this.#applyDeepLinks("ios", { operation, env });
     await this.project.commit();
     await this.#generateAssets({ operation, env });
     this.app.verbose(`syncing iOS`);
@@ -13673,12 +13729,13 @@ ${error.message}`;
     await this.#prepareExternalFiles("android");
     await this.#applyAndroidMetadata();
     await this.#applyPermissions();
-    await this.#applyLinks();
+    await this.#applyDeepLinks("android", { operation, env });
     await this.project.commit();
     await this.#generateAssets({ operation, env });
     await this.#ensureAndroidAssetsDir();
     await this.#ensureAndroidDebugKeystore();
     await this.#spawnMobile("npx", ["cap", "sync", "android"], { operation, env });
+    await this.#setDeepLinksInAndroid(this.target.deepLinks?.schemes ?? [], this.target.deepLinks?.domains ?? []);
   }
   async#updateAndroidBuildTypes() {
     const appGradle = await FileEditor.create(path41.join(this.app.cwdPath, this.androidRootPath, "app/build.gradle"));
@@ -13811,7 +13868,11 @@ ${error.message}`;
   }
   #injectMobileTargetMeta(html) {
     const basePath2 = this.target.basePath?.replace(/^\/+|\/+$/g, "") ?? "";
-    const script = `<script>window.__AKAN_MOBILE_TARGET__=${JSON.stringify({ name: this.target.name, basePath: basePath2 })};</script>`;
+    const script = `<script>window.__AKAN_MOBILE_TARGET__=${JSON.stringify({
+      name: this.target.name,
+      basePath: basePath2,
+      indexPath: this.target.indexPath
+    })};</script>`;
     if (html.includes("window.__AKAN_MOBILE_TARGET__"))
       return html;
     return html.replace(/<\/head\s*>/i, `${script}
@@ -13894,25 +13955,48 @@ ${error.message}`;
         await this.addPush();
     }
   }
-  async#applyLinks() {
-    const links = this.target.links;
-    if (!links)
+  async#applyDeepLinks(platform, { operation, env }) {
+    const deepLinks = this.target.deepLinks;
+    if (!deepLinks)
       return;
-    const schemes = links.schemes ?? [];
-    if (schemes.length > 0) {
-      await this.#setPermissionInIos({
-        appTransportSecurity: ""
-      });
+    const schemes = deepLinks.schemes ?? [];
+    const domains = deepLinks.domains ?? [];
+    if (domains.length > 0)
+      this.#assertDeepLinkVerificationConfig(platform, { operation, env });
+    if (platform === "ios") {
+      if (schemes.length > 0) {
+        await this.#setPermissionInIos({
+          appTransportSecurity: ""
+        });
+        await this.#setUrlSchemesInIos(schemes);
+      }
+      if (domains.length > 0)
+        await this.#setAssociatedDomainsInIos(domains);
+      return;
+    }
+    if (platform === "android") {
       for (const scheme of schemes) {
         this.project.android.getAndroidManifest().injectFragment("activity", `<intent-filter><action android:name="android.intent.action.VIEW" /><category android:name="android.intent.category.DEFAULT" /><category android:name="android.intent.category.BROWSABLE" /><data android:scheme="${scheme}" /></intent-filter>`);
       }
+      for (const domain of domains) {
+        const pathPrefix = resolveMobilePath(this.target, "/");
+        this.project.android.getAndroidManifest().injectFragment("activity", `<intent-filter android:autoVerify="true"><action android:name="android.intent.action.VIEW" /><category android:name="android.intent.category.DEFAULT" /><category android:name="android.intent.category.BROWSABLE" /><data android:scheme="https" android:host="${domain}" android:pathPrefix="${pathPrefix}" /></intent-filter>`);
+      }
+      await this.#setDeepLinksInAndroid(schemes, domains);
     }
-    for (const domain of links.associatedDomains ?? []) {
-      this.app.logger.info(`Configure iOS associated domain manually if needed: ${domain}`);
+  }
+  #assertDeepLinkVerificationConfig(platform, { operation, env }) {
+    const deepLinks = this.target.deepLinks;
+    if (!deepLinks?.domains?.length)
+      return;
+    if (platform === "ios" && !deepLinks.ios?.teamId) {
+      throw new Error(`Mobile target '${this.target.name}' uses deepLinks.domains but is missing deepLinks.ios.teamId in apps/${this.app.name}/akan.config.ts`);
     }
-    for (const host of links.androidHosts ?? []) {
-      const pathPrefix = resolveMobilePath(this.target, "/");
-      this.project.android.getAndroidManifest().injectFragment("activity", `<intent-filter android:autoVerify="true"><action android:name="android.intent.action.VIEW" /><category android:name="android.intent.category.DEFAULT" /><category android:name="android.intent.category.BROWSABLE" /><data android:scheme="https" android:host="${host}" android:pathPrefix="${pathPrefix}" /></intent-filter>`);
+    if (platform === "android" && !deepLinks.android?.sha256CertFingerprints?.length) {
+      const message = `Mobile target '${this.target.name}' uses deepLinks.domains but is missing deepLinks.android.sha256CertFingerprints in apps/${this.app.name}/akan.config.ts`;
+      if (operation === "release" || env === "main")
+        throw new Error(message);
+      this.app.logger.warn(message);
     }
   }
   async#commandEnv(operation, env) {
@@ -13933,6 +14017,8 @@ ${error.message}`;
     const params = new URLSearchParams({ csr: "true", akanMobileTarget: this.target.name });
     if (basePath2)
       params.set("akanMobileBasePath", basePath2);
+    if (this.target.indexPath)
+      params.set("akanMobileIndexPath", this.target.indexPath);
     return `http://${ip}:${port}/${pathname}?${params}`;
   }
   async#clearRootCapacitorConfigs() {
@@ -13992,6 +14078,112 @@ ${error.message}`;
       this.project.ios.updateInfoPlist(this.iosTargetName, "Release", updateNs)
     ]);
   }
+  async#setUrlSchemesInIos(schemes) {
+    const urlTypes = schemes.map((scheme) => ({
+      CFBundleURLName: this.target.appId,
+      CFBundleURLSchemes: [scheme]
+    }));
+    await Promise.all([
+      this.project.ios.updateInfoPlist(this.iosTargetName, "Debug", { CFBundleURLTypes: urlTypes }),
+      this.project.ios.updateInfoPlist(this.iosTargetName, "Release", { CFBundleURLTypes: urlTypes })
+    ]);
+  }
+  async#setAssociatedDomainsInIos(domains) {
+    const entitlementsRelPath = "App/App.entitlements";
+    const entitlementsPath = path41.join(this.app.cwdPath, this.iosProjectPath, entitlementsRelPath);
+    const values = domains.map((domain) => `applinks:${domain}`);
+    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>",
+      "</dict>",
+      "</plist>",
+      ""
+    ].join(`
+`);
+    await writeFile2(entitlementsPath, body);
+    await this.#setCodeSignEntitlementsInIos(entitlementsRelPath);
+  }
+  async#setCodeSignEntitlementsInIos(entitlementsRelPath) {
+    const pbxprojPath = path41.join(this.app.cwdPath, this.iosProjectPath, "App.xcodeproj/project.pbxproj");
+    const lines = (await readFile2(pbxprojPath, "utf8")).split(`
+`);
+    let changed = false;
+    for (let index = 0;index < lines.length; index++) {
+      const line = lines[index] ?? "";
+      if (!line.includes(`PRODUCT_BUNDLE_IDENTIFIER = ${this.target.appId};`))
+        continue;
+      let start = index;
+      while (start >= 0 && !lines[start]?.includes("buildSettings = {"))
+        start--;
+      let end = index;
+      while (end < lines.length && !/^\s*\};\s*$/.test(lines[end] ?? ""))
+        end++;
+      const settings = lines.slice(start, end + 1);
+      if (settings.some((setting) => setting.includes("CODE_SIGN_ENTITLEMENTS")))
+        continue;
+      const indent = line.match(/^\s*/)?.[0] ?? "";
+      lines.splice(index, 0, `${indent}CODE_SIGN_ENTITLEMENTS = ${entitlementsRelPath};`);
+      index++;
+      changed = true;
+    }
+    if (changed)
+      await writeFile2(pbxprojPath, lines.join(`
+`));
+  }
+  async#setUrlSchemesInAndroid(schemes) {
+    const manifestPath = path41.join(this.app.cwdPath, this.androidRootPath, "app/src/main/AndroidManifest.xml");
+    let manifest = await readFile2(manifestPath, "utf8");
+    let changed = false;
+    for (const scheme of schemes) {
+      if (manifest.includes(`android:scheme="${scheme}"`))
+        continue;
+      const filter = [
+        "            <intent-filter>",
+        '                <action android:name="android.intent.action.VIEW" />',
+        '                <category android:name="android.intent.category.DEFAULT" />',
+        '                <category android:name="android.intent.category.BROWSABLE" />',
+        `                <data android:scheme="${scheme}" />`,
+        "            </intent-filter>"
+      ].join(`
+`);
+      manifest = manifest.replace(/(\s*<\/activity>)/, `
+${filter}$1`);
+      changed = true;
+    }
+    if (changed)
+      await writeFile2(manifestPath, manifest);
+  }
+  async#setDeepLinksInAndroid(schemes, domains) {
+    await this.#setUrlSchemesInAndroid(schemes);
+    const manifestPath = path41.join(this.app.cwdPath, this.androidRootPath, "app/src/main/AndroidManifest.xml");
+    let manifest = await readFile2(manifestPath, "utf8");
+    let changed = false;
+    const pathPrefix = resolveMobilePath(this.target, "/");
+    for (const domain of domains) {
+      if (manifest.includes(`android:host="${domain}"`) && manifest.includes('android:scheme="https"'))
+        continue;
+      const filter = [
+        '            <intent-filter android:autoVerify="true">',
+        '                <action android:name="android.intent.action.VIEW" />',
+        '                <category android:name="android.intent.category.DEFAULT" />',
+        '                <category android:name="android.intent.category.BROWSABLE" />',
+        `                <data android:scheme="https" android:host="${domain}" android:pathPrefix="${pathPrefix}" />`,
+        "            </intent-filter>"
+      ].join(`
+`);
+      manifest = manifest.replace(/(\s*<\/activity>)/, `
+${filter}$1`);
+      changed = true;
+    }
+    if (changed)
+      await writeFile2(manifestPath, manifest);
+  }
   #setFeaturesInAndroid(features) {
     for (const feature of features) {
       if (this.#hasFeatureInAndroid(feature)) {
@@ -15074,7 +15266,7 @@ ${document}
 }
 // pkgs/@akanjs/devkit/qualityScanner.ts
 import { createHash } from "crypto";
-import { readdir as readdir3, readFile as readFile2, stat as stat4 } from "fs/promises";
+import { readdir as readdir3, readFile as readFile3, stat as stat4 } from "fs/promises";
 import path43 from "path";
 import ignore2 from "ignore";
 import ts11 from "typescript";
@@ -15163,7 +15355,7 @@ class AkanQualityScanner {
     const gitIgnorePath = path43.join(workspaceRoot, ".gitignore");
     if (!await Bun.file(gitIgnorePath).exists())
       return [];
-    return (await readFile2(gitIgnorePath, "utf8")).split(/\r?\n/);
+    return (await readFile3(gitIgnorePath, "utf8")).split(/\r?\n/);
   }
   async#walkTargetFiles(workspaceRoot, currentPath, ignoreFilter, files) {
     const entries = await readdir3(currentPath, { withFileTypes: true });
@@ -15183,7 +15375,7 @@ class AkanQualityScanner {
   }
   async#readSourceFile(workspaceRoot, file) {
     const absolutePath = path43.join(workspaceRoot, file);
-    const content = await readFile2(absolutePath, "utf8");
+    const content = await readFile3(absolutePath, "utf8");
     return {
       file,
       absolutePath,

package/index.js

@@ -742,6 +742,44 @@ var DEFAULT_AKAN_IMAGE_CONFIG = {
   fetchTimeoutMs: 7000,
   maxRemoteBytes: 25 * 1024 * 1024
 };
+var normalizeIndexPath = (indexPath) => {
+  const normalized = indexPath?.trim();
+  if (!normalized)
+    return;
+  const path2 = `/${normalized.replace(/^\/+|\/+$/g, "")}`;
+  return path2 === "/" ? "/" : path2;
+};
+var normalizeStringList = (values) => {
+  const normalized = values?.map((value) => value.trim()).filter(Boolean) ?? [];
+  return normalized.length > 0 ? [...new Set(normalized)] : undefined;
+};
+var normalizeDeepLinkDomain = (domain) => {
+  const normalized = domain.trim();
+  if (!normalized)
+    return "";
+  try {
+    const url = new URL(normalized.includes("://") ? normalized : `https://${normalized}`);
+    return url.host.toLowerCase();
+  } catch {
+    return normalized.replace(/^https?:\/\//, "").replace(/\/+$/g, "").toLowerCase();
+  }
+};
+var normalizeDeepLinks = (deepLinks) => {
+  if (!deepLinks)
+    return;
+  const schemes = normalizeStringList(deepLinks.schemes);
+  const domains = normalizeStringList(deepLinks.domains?.map(normalizeDeepLinkDomain));
+  const teamId = deepLinks.ios?.teamId?.trim();
+  const sha256CertFingerprints = normalizeStringList(deepLinks.android?.sha256CertFingerprints);
+  if (!schemes && !domains && !teamId && !sha256CertFingerprints)
+    return;
+  return {
+    ...schemes ? { schemes } : {},
+    ...domains ? { domains } : {},
+    ...teamId ? { ios: { teamId } } : {},
+    ...sha256CertFingerprints ? { android: { sha256CertFingerprints } } : {}
+  };
+};
 
 class AkanAppConfig {
   app;
@@ -755,6 +793,7 @@ class AkanAppConfig {
   i18n;
   publicEnv;
   mobile;
+  secrets;
   baseDevEnv;
   libs;
   domains = new Set;
@@ -781,11 +820,16 @@ class AkanAppConfig {
     process.env.AKAN_PUBLIC_DEFAULT_LOCALE = this.i18n.defaultLocale;
     process.env.AKAN_PUBLIC_LOCALES = this.i18n.locales.join(",");
     this.publicEnv = config?.publicEnv ?? [];
+    this.secrets = config?.secrets ?? [];
     this.mobile = this.#resolveMobileConfig(config.mobile);
     this.docker = this.#makeDockerContent(config?.docker ?? {});
   }
   #resolveMobileConfig(mobile) {
-    const { targets: rawTargets, ...rawMobile } = mobile ?? {};
+    const {
+      targets: rawTargets,
+      indexPath: _indexPath,
+      ...rawMobile
+    } = mobile ?? {};
     const appName = rawMobile.appName ?? this.app.name;
     const appId = rawMobile.appId ?? `com.${this.app.name}.app`;
     const version = rawMobile.version ?? "0.0.1";
@@ -798,6 +842,8 @@ class AkanAppConfig {
       const target = rawTarget;
       const fallbackBasePath = !rawTargets && this.basePaths.has(name) ? name : undefined;
       const basePath2 = (target.basePath ?? fallbackBasePath)?.replace(/^\/+|\/+$/g, "") || undefined;
+      const indexPath = normalizeIndexPath(target.indexPath);
+      const deepLinks = normalizeDeepLinks(target.deepLinks);
       if (basePath2 && !this.basePaths.has(basePath2)) {
         throw new Error(`Mobile target '${name}' uses unknown basePath '${basePath2}' in apps/${this.app.name}/akan.config.ts`);
       }
@@ -806,6 +852,8 @@ class AkanAppConfig {
         ...target,
         name,
         basePath: basePath2,
+        indexPath,
+        deepLinks,
         appName: target.appName ?? appName,
         appId: target.appId ?? appId,
         version: target.version ?? version,
@@ -2744,8 +2792,8 @@ class Executor {
       return filePath;
     if (filePath.startsWith("."))
       return path7.join(this.cwdPath, filePath);
-    const baseParts = this.cwdPath.split("/").filter(Boolean);
-    const targetParts = filePath.split("/").filter(Boolean);
+    const baseParts = this.cwdPath.split(/[\\/]/).filter(Boolean);
+    const targetParts = filePath.split(/[\\/]/).filter(Boolean);
     let overlapLength = 0;
     for (let i = 1;i <= Math.min(baseParts.length, targetParts.length); i++) {
       let isOverlap = true;
@@ -2757,8 +2805,7 @@ class Executor {
       if (isOverlap)
         overlapLength = i;
     }
-    const result = overlapLength > 0 ? `/${[...baseParts, ...targetParts.slice(overlapLength)].join("/")}` : `${this.cwdPath}/${filePath}`;
-    return result.replace(/\/+/g, "/");
+    return path7.join(this.cwdPath, ...targetParts.slice(overlapLength));
   }
   async mkdir(dirPath) {
     const writePath = this.getPath(dirPath);
@@ -10223,6 +10270,7 @@ import path24 from "path";
 // pkgs/@akanjs/devkit/frontendBuild/pagesEntrySourceGenerator.ts
 import fs3 from "fs";
 import path23 from "path";
+import { pathToFileURL } from "url";
 import ts8 from "typescript";
 
 class PagesEntrySourceGenerator {
@@ -10235,8 +10283,8 @@ class PagesEntrySourceGenerator {
   }
   generate() {
     const lines = this.#pageEntries.map(({ key, moduleAbsPath }) => {
-      const absPath = path23.resolve(moduleAbsPath);
-      return `  ${JSON.stringify(key)}: () => import(${JSON.stringify(absPath)}),`;
+      const specifier = pathToFileURL(path23.resolve(moduleAbsPath)).href;
+      return `  ${JSON.stringify(key)}: () => import(${JSON.stringify(specifier)}),`;
     });
     return `export const pages = {
 ${lines.join(`
@@ -10249,8 +10297,8 @@ ${lines.join(`
   }
   generateStatic() {
     const imports = this.#pageEntries.map(({ moduleAbsPath }, index) => {
-      const absPath = path23.resolve(moduleAbsPath);
-      return `import * as page${index} from ${JSON.stringify(absPath)};`;
+      const specifier = pathToFileURL(path23.resolve(moduleAbsPath)).href;
+      return `import * as page${index} from ${JSON.stringify(specifier)};`;
     });
     const entries = this.#pageEntries.map(({ key, moduleAbsPath }, index) => {
       const isAsyncDefault = PagesEntrySourceGenerator.#hasAsyncDefaultExport(moduleAbsPath);
@@ -12114,7 +12162,14 @@ class SsrBaseArtifactBuilder {
       basePaths: [...akanConfig2.basePaths],
       branches: [...akanConfig2.branches],
       i18n: akanConfig2.i18n,
-      imageConfig: akanConfig2.images
+      imageConfig: akanConfig2.images,
+      deepLinkAssociations: Object.values(akanConfig2.mobile.targets).filter((target) => (target.deepLinks?.domains?.length ?? 0) > 0).map((target) => ({
+        targetName: target.name,
+        appId: target.appId,
+        domains: target.deepLinks?.domains ?? [],
+        iosTeamId: target.deepLinks?.ios?.teamId,
+        androidSha256CertFingerprints: target.deepLinks?.android?.sha256CertFingerprints
+      }))
     };
     await Bun.write(path35.join(this.#absArtifactDir, "base-artifact.json"), `${JSON.stringify(artifact, null, 2)}
 `);
@@ -12123,11 +12178,11 @@ class SsrBaseArtifactBuilder {
   }
   async#buildRuntimeClientEntries() {
     const akanServerPath = await this.#resolveAkanServerPath();
-    const rscClientEntry = `${akanServerPath}/rscClient.tsx`;
-    const rscSegmentOutletEntry = `${akanServerPath}/rscSegmentOutlet.tsx`;
+    const rscClientEntry = path35.resolve(akanServerPath, "rscClient.tsx");
+    const rscSegmentOutletEntry = path35.resolve(akanServerPath, "rscSegmentOutlet.tsx");
     const vendorEntries = VENDOR_SPECIFIERS.map((specifier) => ({
       specifier,
-      absPath: `${akanServerPath}/vendor/${specifier.replaceAll("/", "-").replaceAll(".", "-")}.ts`
+      absPath: path35.resolve(akanServerPath, "vendor", `${specifier.replaceAll("/", "-").replaceAll(".", "-")}.ts`)
     }));
     const entries = [rscClientEntry, rscSegmentOutletEntry, ...vendorEntries.map((v) => v.absPath)];
     const clientBundle = await new ClientEntriesBundler({ app: this.#app, entries, command: this.#command }).bundle();
@@ -12888,7 +12943,7 @@ class Builder {
   }
 }
 // pkgs/@akanjs/devkit/capacitorApp.ts
-import { cp as cp2, mkdir as mkdir11, rm as rm5 } from "fs/promises";
+import { cp as cp2, mkdir as mkdir11, readFile as readFile2, rm as rm5, writeFile as writeFile2 } from "fs/promises";
 import os from "os";
 import path41 from "path";
 import { select as select2 } from "@inquirer/prompts";
@@ -13402,11 +13457,12 @@ function materializeCapacitorConfig(target, { operation, localServerUrl, localIp
   const {
     name,
     basePath: _basePath,
+    indexPath: _indexPath,
     version: _version,
     buildNum: _buildNum,
     assets: _assets,
     permissions: _permissions,
-    links: _links,
+    deepLinks: _deepLinks,
     files: _files,
     appId,
     appName,
@@ -13528,7 +13584,7 @@ class CapacitorApp {
     await this.#prepareExternalFiles("ios");
     await this.#applyIosMetadata();
     await this.#applyPermissions();
-    await this.#applyLinks();
+    await this.#applyDeepLinks("ios", { operation, env });
     await this.project.commit();
     await this.#generateAssets({ operation, env });
     this.app.verbose(`syncing iOS`);
@@ -13671,12 +13727,13 @@ ${error.message}`;
     await this.#prepareExternalFiles("android");
     await this.#applyAndroidMetadata();
     await this.#applyPermissions();
-    await this.#applyLinks();
+    await this.#applyDeepLinks("android", { operation, env });
     await this.project.commit();
     await this.#generateAssets({ operation, env });
     await this.#ensureAndroidAssetsDir();
     await this.#ensureAndroidDebugKeystore();
     await this.#spawnMobile("npx", ["cap", "sync", "android"], { operation, env });
+    await this.#setDeepLinksInAndroid(this.target.deepLinks?.schemes ?? [], this.target.deepLinks?.domains ?? []);
   }
   async#updateAndroidBuildTypes() {
     const appGradle = await FileEditor.create(path41.join(this.app.cwdPath, this.androidRootPath, "app/build.gradle"));
@@ -13809,7 +13866,11 @@ ${error.message}`;
   }
   #injectMobileTargetMeta(html) {
     const basePath2 = this.target.basePath?.replace(/^\/+|\/+$/g, "") ?? "";
-    const script = `<script>window.__AKAN_MOBILE_TARGET__=${JSON.stringify({ name: this.target.name, basePath: basePath2 })};</script>`;
+    const script = `<script>window.__AKAN_MOBILE_TARGET__=${JSON.stringify({
+      name: this.target.name,
+      basePath: basePath2,
+      indexPath: this.target.indexPath
+    })};</script>`;
     if (html.includes("window.__AKAN_MOBILE_TARGET__"))
       return html;
     return html.replace(/<\/head\s*>/i, `${script}
@@ -13892,25 +13953,48 @@ ${error.message}`;
         await this.addPush();
     }
   }
-  async#applyLinks() {
-    const links = this.target.links;
-    if (!links)
+  async#applyDeepLinks(platform, { operation, env }) {
+    const deepLinks = this.target.deepLinks;
+    if (!deepLinks)
       return;
-    const schemes = links.schemes ?? [];
-    if (schemes.length > 0) {
-      await this.#setPermissionInIos({
-        appTransportSecurity: ""
-      });
+    const schemes = deepLinks.schemes ?? [];
+    const domains = deepLinks.domains ?? [];
+    if (domains.length > 0)
+      this.#assertDeepLinkVerificationConfig(platform, { operation, env });
+    if (platform === "ios") {
+      if (schemes.length > 0) {
+        await this.#setPermissionInIos({
+          appTransportSecurity: ""
+        });
+        await this.#setUrlSchemesInIos(schemes);
+      }
+      if (domains.length > 0)
+        await this.#setAssociatedDomainsInIos(domains);
+      return;
+    }
+    if (platform === "android") {
       for (const scheme of schemes) {
         this.project.android.getAndroidManifest().injectFragment("activity", `<intent-filter><action android:name="android.intent.action.VIEW" /><category android:name="android.intent.category.DEFAULT" /><category android:name="android.intent.category.BROWSABLE" /><data android:scheme="${scheme}" /></intent-filter>`);
       }
+      for (const domain of domains) {
+        const pathPrefix = resolveMobilePath(this.target, "/");
+        this.project.android.getAndroidManifest().injectFragment("activity", `<intent-filter android:autoVerify="true"><action android:name="android.intent.action.VIEW" /><category android:name="android.intent.category.DEFAULT" /><category android:name="android.intent.category.BROWSABLE" /><data android:scheme="https" android:host="${domain}" android:pathPrefix="${pathPrefix}" /></intent-filter>`);
+      }
+      await this.#setDeepLinksInAndroid(schemes, domains);
     }
-    for (const domain of links.associatedDomains ?? []) {
-      this.app.logger.info(`Configure iOS associated domain manually if needed: ${domain}`);
+  }
+  #assertDeepLinkVerificationConfig(platform, { operation, env }) {
+    const deepLinks = this.target.deepLinks;
+    if (!deepLinks?.domains?.length)
+      return;
+    if (platform === "ios" && !deepLinks.ios?.teamId) {
+      throw new Error(`Mobile target '${this.target.name}' uses deepLinks.domains but is missing deepLinks.ios.teamId in apps/${this.app.name}/akan.config.ts`);
     }
-    for (const host of links.androidHosts ?? []) {
-      const pathPrefix = resolveMobilePath(this.target, "/");
-      this.project.android.getAndroidManifest().injectFragment("activity", `<intent-filter android:autoVerify="true"><action android:name="android.intent.action.VIEW" /><category android:name="android.intent.category.DEFAULT" /><category android:name="android.intent.category.BROWSABLE" /><data android:scheme="https" android:host="${host}" android:pathPrefix="${pathPrefix}" /></intent-filter>`);
+    if (platform === "android" && !deepLinks.android?.sha256CertFingerprints?.length) {
+      const message = `Mobile target '${this.target.name}' uses deepLinks.domains but is missing deepLinks.android.sha256CertFingerprints in apps/${this.app.name}/akan.config.ts`;
+      if (operation === "release" || env === "main")
+        throw new Error(message);
+      this.app.logger.warn(message);
     }
   }
   async#commandEnv(operation, env) {
@@ -13931,6 +14015,8 @@ ${error.message}`;
     const params = new URLSearchParams({ csr: "true", akanMobileTarget: this.target.name });
     if (basePath2)
       params.set("akanMobileBasePath", basePath2);
+    if (this.target.indexPath)
+      params.set("akanMobileIndexPath", this.target.indexPath);
     return `http://${ip}:${port}/${pathname}?${params}`;
   }
   async#clearRootCapacitorConfigs() {
@@ -13990,6 +14076,112 @@ ${error.message}`;
       this.project.ios.updateInfoPlist(this.iosTargetName, "Release", updateNs)
     ]);
   }
+  async#setUrlSchemesInIos(schemes) {
+    const urlTypes = schemes.map((scheme) => ({
+      CFBundleURLName: this.target.appId,
+      CFBundleURLSchemes: [scheme]
+    }));
+    await Promise.all([
+      this.project.ios.updateInfoPlist(this.iosTargetName, "Debug", { CFBundleURLTypes: urlTypes }),
+      this.project.ios.updateInfoPlist(this.iosTargetName, "Release", { CFBundleURLTypes: urlTypes })
+    ]);
+  }
+  async#setAssociatedDomainsInIos(domains) {
+    const entitlementsRelPath = "App/App.entitlements";
+    const entitlementsPath = path41.join(this.app.cwdPath, this.iosProjectPath, entitlementsRelPath);
+    const values = domains.map((domain) => `applinks:${domain}`);
+    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>",
+      "</dict>",
+      "</plist>",
+      ""
+    ].join(`
+`);
+    await writeFile2(entitlementsPath, body);
+    await this.#setCodeSignEntitlementsInIos(entitlementsRelPath);
+  }
+  async#setCodeSignEntitlementsInIos(entitlementsRelPath) {
+    const pbxprojPath = path41.join(this.app.cwdPath, this.iosProjectPath, "App.xcodeproj/project.pbxproj");
+    const lines = (await readFile2(pbxprojPath, "utf8")).split(`
+`);
+    let changed = false;
+    for (let index = 0;index < lines.length; index++) {
+      const line = lines[index] ?? "";
+      if (!line.includes(`PRODUCT_BUNDLE_IDENTIFIER = ${this.target.appId};`))
+        continue;
+      let start = index;
+      while (start >= 0 && !lines[start]?.includes("buildSettings = {"))
+        start--;
+      let end = index;
+      while (end < lines.length && !/^\s*\};\s*$/.test(lines[end] ?? ""))
+        end++;
+      const settings = lines.slice(start, end + 1);
+      if (settings.some((setting) => setting.includes("CODE_SIGN_ENTITLEMENTS")))
+        continue;
+      const indent = line.match(/^\s*/)?.[0] ?? "";
+      lines.splice(index, 0, `${indent}CODE_SIGN_ENTITLEMENTS = ${entitlementsRelPath};`);
+      index++;
+      changed = true;
+    }
+    if (changed)
+      await writeFile2(pbxprojPath, lines.join(`
+`));
+  }
+  async#setUrlSchemesInAndroid(schemes) {
+    const manifestPath = path41.join(this.app.cwdPath, this.androidRootPath, "app/src/main/AndroidManifest.xml");
+    let manifest = await readFile2(manifestPath, "utf8");
+    let changed = false;
+    for (const scheme of schemes) {
+      if (manifest.includes(`android:scheme="${scheme}"`))
+        continue;
+      const filter = [
+        "            <intent-filter>",
+        '                <action android:name="android.intent.action.VIEW" />',
+        '                <category android:name="android.intent.category.DEFAULT" />',
+        '                <category android:name="android.intent.category.BROWSABLE" />',
+        `                <data android:scheme="${scheme}" />`,
+        "            </intent-filter>"
+      ].join(`
+`);
+      manifest = manifest.replace(/(\s*<\/activity>)/, `
+${filter}$1`);
+      changed = true;
+    }
+    if (changed)
+      await writeFile2(manifestPath, manifest);
+  }
+  async#setDeepLinksInAndroid(schemes, domains) {
+    await this.#setUrlSchemesInAndroid(schemes);
+    const manifestPath = path41.join(this.app.cwdPath, this.androidRootPath, "app/src/main/AndroidManifest.xml");
+    let manifest = await readFile2(manifestPath, "utf8");
+    let changed = false;
+    const pathPrefix = resolveMobilePath(this.target, "/");
+    for (const domain of domains) {
+      if (manifest.includes(`android:host="${domain}"`) && manifest.includes('android:scheme="https"'))
+        continue;
+      const filter = [
+        '            <intent-filter android:autoVerify="true">',
+        '                <action android:name="android.intent.action.VIEW" />',
+        '                <category android:name="android.intent.category.DEFAULT" />',
+        '                <category android:name="android.intent.category.BROWSABLE" />',
+        `                <data android:scheme="https" android:host="${domain}" android:pathPrefix="${pathPrefix}" />`,
+        "            </intent-filter>"
+      ].join(`
+`);
+      manifest = manifest.replace(/(\s*<\/activity>)/, `
+${filter}$1`);
+      changed = true;
+    }
+    if (changed)
+      await writeFile2(manifestPath, manifest);
+  }
   #setFeaturesInAndroid(features) {
     for (const feature of features) {
       if (this.#hasFeatureInAndroid(feature)) {
@@ -15072,7 +15264,7 @@ ${document}
 }
 // pkgs/@akanjs/devkit/qualityScanner.ts
 import { createHash } from "crypto";
-import { readdir as readdir3, readFile as readFile2, stat as stat4 } from "fs/promises";
+import { readdir as readdir3, readFile as readFile3, stat as stat4 } from "fs/promises";
 import path43 from "path";
 import ignore2 from "ignore";
 import ts11 from "typescript";
@@ -15161,7 +15353,7 @@ class AkanQualityScanner {
     const gitIgnorePath = path43.join(workspaceRoot, ".gitignore");
     if (!await Bun.file(gitIgnorePath).exists())
       return [];
-    return (await readFile2(gitIgnorePath, "utf8")).split(/\r?\n/);
+    return (await readFile3(gitIgnorePath, "utf8")).split(/\r?\n/);
   }
   async#walkTargetFiles(workspaceRoot, currentPath, ignoreFilter, files) {
     const entries = await readdir3(currentPath, { withFileTypes: true });
@@ -15181,7 +15373,7 @@ class AkanQualityScanner {
   }
   async#readSourceFile(workspaceRoot, file) {
     const absolutePath = path43.join(workspaceRoot, file);
-    const content = await readFile2(absolutePath, "utf8");
+    const content = await readFile3(absolutePath, "utf8");
     return {
       file,
       absolutePath,
@@ -17184,7 +17376,10 @@ ${chalk7.green("\u27A4")} Authentication Required`));
       ...appNames.map((appName) => `apps/${appName}/env`),
       ...libNames.map((libName) => `libs/${libName}/env`)
     ];
-    const envFilePaths = (await Promise.all(envDirs.map(async (envDir) => (await workspace.readdir(envDir)).filter((fileName) => envFilePattern.test(fileName)).map((fileName) => `${envDir}/${fileName}`)))).flat().sort();
+    const defaultEnvFilePaths = (await Promise.all(envDirs.map(async (envDir) => (await workspace.readdir(envDir)).filter((fileName) => envFilePattern.test(fileName)).map((fileName) => `${envDir}/${fileName}`)))).flat();
+    await this.#syncSecretGitignore(workspace, appNames);
+    const customSecretPaths = await this.#gatherCustomSecretFiles(workspace, appNames);
+    const envFilePaths = [...new Set([...defaultEnvFilePaths, ...customSecretPaths])].sort();
     await workspace.mkdir("local");
     await workspace.remove("local/env.tar");
     if (envFilePaths.length === 0)
@@ -17195,6 +17390,52 @@ ${chalk7.green("\u27A4")} Authentication Required`));
     Logger15.info(`Archived ${envFilePaths.length} environment files to local/env.tar`);
     return { files: envFilePaths, path: "local/env.tar" };
   }
+  async#gatherCustomSecretFiles(workspace, appNames) {
+    const secretPaths = await Promise.all(appNames.map(async (appName) => {
+      const config = await AppExecutor.from(workspace, appName).getConfig();
+      const secretGlobs = config.secrets ?? [];
+      if (secretGlobs.length === 0)
+        return [];
+      const appDir = path45.join(workspace.workspaceRoot, "apps", appName);
+      return secretGlobs.flatMap((pattern) => Array.from(new Bun.Glob(pattern).scanSync({ cwd: appDir, onlyFiles: true })).map((match) => `apps/${appName}/${match.split(path45.sep).join("/")}`));
+    }));
+    return secretPaths.flat();
+  }
+  async#syncSecretGitignore(workspace, appNames) {
+    const patterns = (await Promise.all(appNames.map(async (appName) => {
+      const config = await AppExecutor.from(workspace, appName).getConfig();
+      return (config.secrets ?? []).map((pattern) => `apps/${appName}/${pattern.replace(/^\/+/, "")}`);
+    }))).flat();
+    const uniquePatterns = [...new Set(patterns)].sort();
+    const existing = await workspace.exists(".gitignore") ? await workspace.readFile(".gitignore") : "";
+    const nextContent = this.#applySecretGitignoreBlock(existing, uniquePatterns);
+    if (nextContent === existing)
+      return;
+    await workspace.writeFile(".gitignore", nextContent);
+    Logger15.info(uniquePatterns.length ? `Synced ${uniquePatterns.length} secret pattern(s) from akan.config.ts to .gitignore` : "Removed managed secret patterns from .gitignore");
+  }
+  #applySecretGitignoreBlock(content, patterns) {
+    const beginMarker = "# akan:secrets (managed by akan.config.ts \u2014 do not edit)";
+    const endMarker = "# akan:secrets:end";
+    const lines = content.split(`
+`);
+    const beginIdx = lines.indexOf(beginMarker);
+    const endIdx = lines.indexOf(endMarker);
+    const stripped = beginIdx !== -1 && endIdx !== -1 && endIdx >= beginIdx ? [...lines.slice(0, beginIdx), ...lines.slice(endIdx + 1)] : [...lines];
+    while (stripped.length && stripped[stripped.length - 1]?.trim() === "")
+      stripped.pop();
+    if (patterns.length === 0)
+      return stripped.length ? `${stripped.join(`
+`)}
+` : "";
+    const body = stripped.length ? `${stripped.join(`
+`)}
+
+` : "";
+    return `${body}${[beginMarker, ...patterns, endMarker].join(`
+`)}
+`;
+  }
 }
 
 // pkgs/@akanjs/cli/cloud/cloud.script.ts
@@ -17474,7 +17715,7 @@ class RepairRunner extends runner("repair") {
 }
 
 // pkgs/@akanjs/cli/workflow/workflow.runner.ts
-import { mkdir as mkdir12, readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
+import { mkdir as mkdir12, readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
 import path46 from "path";
 import { capitalize as capitalize8 } from "akanjs/common";
 
@@ -18116,7 +18357,7 @@ var defaultValidationExecutor = (workspace) => async (command3) => {
     };
   }
 };
-var readJsonFile = async (filePath) => JSON.parse(await readFile3(resolvePath(filePath), "utf8"));
+var readJsonFile = async (filePath) => JSON.parse(await readFile4(resolvePath(filePath), "utf8"));
 var planInputString2 = (plan2, key) => {
   const value = plan2.inputs[key];
   return typeof value === "string" ? value : "";
@@ -18213,7 +18454,7 @@ class WorkflowRunner extends runner("workflow") {
     if (out) {
       const outPath = resolvePath(out);
       await mkdir12(path46.dirname(outPath), { recursive: true });
-      await writeFile2(outPath, jsonText(plan2));
+      await writeFile3(outPath, jsonText(plan2));
     }
     return format === "json" ? jsonText(plan2) : renderWorkflowPlan(plan2);
   }
@@ -18231,7 +18472,7 @@ class WorkflowRunner extends runner("workflow") {
     };
     let plan2;
     try {
-      const parsed = JSON.parse(await readFile3(resolvePath(planPath), "utf8"));
+      const parsed = JSON.parse(await readFile4(resolvePath(planPath), "utf8"));
       if (!isWorkflowPlan2(parsed)) {
         const report = failedApplyReport("unknown", [
           {
@@ -20822,6 +21063,12 @@ class WorkspaceRunner extends runner("workspace") {
       dict,
       overwrite
     });
+    created.push(...await workspace.applyTemplate({
+      basePath: ".",
+      template: "workspaceRoot/CLAUDE.md.template",
+      dict,
+      overwrite
+    }));
     if (!cursorRules)
       return created;
     return [
@@ -21116,7 +21363,9 @@ class WorkspaceCommand extends command("workspace", [WorkspaceScript], ({ public
       ...registry ? { registryUrl: registry } : {}
     });
   }),
-  generateAgentRules: target({ desc: "Generate AGENTS.md and optional Cursor rules for Akan coding agents" }).option("overwrite", Boolean, { desc: "Overwrite existing agent rule files", default: false }).option("cursorRules", Boolean, { desc: "Generate .cursor/rules/akan.mdc", default: true }).with(Workspace).exec(async function(overwrite, cursorRules, workspace) {
+  generateAgentRules: target({
+    desc: "Generate AGENTS.md, CLAUDE.md, and optional Cursor rules for Akan coding agents"
+  }).option("overwrite", Boolean, { desc: "Overwrite existing agent rule files", default: false }).option("cursorRules", Boolean, { desc: "Generate .cursor/rules/akan.mdc", default: true }).with(Workspace).exec(async function(overwrite, cursorRules, workspace) {
     await this.workspaceScript.generateAgentRules(workspace, { overwrite, cursorRules });
   }),
   lint: target({ desc: "Lint and fix code in a specific app/lib/pkg" }).with(Exec).option("fix", Boolean, { default: true }).with(Workspace).exec(async function(exec2, fix, workspace) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "2.3.9",
+  "version": "2.3.10-rc.1",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -34,7 +34,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.3.9",
+    "akanjs": "2.3.10-rc.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/templates/workspaceRoot/CLAUDE.md.template

@@ -0,0 +1,3 @@
+# <%= repoName %> — Claude Code Guide
+
+@AGENTS.md