@akanjs/cli 2.3.9-rc.9 → 2.3.10-rc.0

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,
@@ -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)}
 `);
@@ -12502,6 +12557,7 @@ void run().catch((error) => {
 }
 // pkgs/@akanjs/devkit/applicationReleasePackager.ts
 import { cp, mkdir as mkdir9, rm as rm4 } from "fs/promises";
+import path38 from "path";
 
 // pkgs/@akanjs/devkit/uploadRelease.ts
 import { HttpClient as HttpClient2, Logger as Logger9 } from "akanjs/common";
@@ -12617,13 +12673,9 @@ class ApplicationReleasePackager {
     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 this.#app.workspace.spawn("tar", [
-      "-zcf",
-      `${this.#app.workspace.workspaceRoot}/releases/builds/${this.#app.name}-release.tar.gz`,
-      "-C",
-      buildRoot,
-      "./"
-    ]);
+    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 });
     await this.#writeCsrZipIfPresent();
     return { platformVersion };
   }
@@ -12644,22 +12696,18 @@ class ApplicationReleasePackager {
     await cp(this.#app.dist.cwdPath, `${sourceRoot}/apps/${this.#app.name}`, { recursive: true });
     const libDeps = ["social", "shared", "platform", "util"];
     await Promise.all(libDeps.map((lib) => cp(`${this.#app.workspace.cwdPath}/libs/${lib}`, `${sourceRoot}/libs/${lib}`, { recursive: true })));
-    await Promise.all([".next", "ios", "android", "public/libs"].map(async (path38) => {
-      const targetPath = `${sourceRoot}/apps/${this.#app.name}/${path38}`;
+    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 });
     }));
     const syncPaths = [".husky", ".gitignore", "package.json"];
-    await Promise.all(syncPaths.map((path38) => cp(`${this.#app.workspace.cwdPath}/${path38}`, `${sourceRoot}/${path38}`, { recursive: true })));
+    await Promise.all(syncPaths.map((path39) => cp(`${this.#app.workspace.cwdPath}/${path39}`, `${sourceRoot}/${path39}`, { recursive: true })));
     await this.#writeSourceTsconfig(sourceRoot, libDeps);
     await Bun.write(`${sourceRoot}/README.md`, readme);
-    await this.#app.workspace.spawn("tar", [
-      "-zcf",
-      `${this.#app.workspace.cwdPath}/releases/sources/${this.#app.name}-source.tar.gz`,
-      "-C",
-      sourceRoot,
-      "./"
-    ]);
+    const sourceCwd = this.#app.workspace.cwdPath;
+    const sourceArchivePath = path38.relative(sourceCwd, `${sourceCwd}/releases/sources/${this.#app.name}-source.tar.gz`).split(path38.sep).join("/");
+    await this.#app.workspace.spawn("tar", ["-zcf", sourceArchivePath, "-C", sourceRoot, "./"], { cwd: sourceCwd });
   }
   async#resetSourceRoot(sourceRoot) {
     if (await FileSys.dirExists(sourceRoot)) {
@@ -12741,20 +12789,20 @@ class ApplicationReleasePackager {
   }
 }
 // pkgs/@akanjs/devkit/applicationTestPreload.ts
-import path38 from "path";
+import path39 from "path";
 var SIGNAL_TEST_PRELOAD_PATH = "test/signalTest.preload.ts";
 async function resolveSignalTestPreloadPath(target) {
   const candidates = [];
   const addResolvedPackageCandidate = (basePath2) => {
     try {
-      candidates.push(path38.join(path38.dirname(Bun.resolveSync("akanjs/package.json", basePath2)), SIGNAL_TEST_PRELOAD_PATH));
+      candidates.push(path39.join(path39.dirname(Bun.resolveSync("akanjs/package.json", basePath2)), SIGNAL_TEST_PRELOAD_PATH));
     } catch {}
   };
   addResolvedPackageCandidate(target.cwdPath);
   addResolvedPackageCandidate(process.cwd());
-  addResolvedPackageCandidate(path38.dirname(Bun.main));
+  addResolvedPackageCandidate(path39.dirname(Bun.main));
   addResolvedPackageCandidate(import.meta.dir);
-  candidates.push(path38.join(target.cwdPath, "../../node_modules/akanjs", SIGNAL_TEST_PRELOAD_PATH), path38.join(target.cwdPath, "../../pkgs/akanjs", SIGNAL_TEST_PRELOAD_PATH), path38.join(process.cwd(), "node_modules/akanjs", SIGNAL_TEST_PRELOAD_PATH), path38.join(process.cwd(), "pkgs/akanjs", SIGNAL_TEST_PRELOAD_PATH), path38.join(path38.dirname(Bun.main), "../../akanjs", SIGNAL_TEST_PRELOAD_PATH), path38.resolve(import.meta.dir, "../../akanjs", SIGNAL_TEST_PRELOAD_PATH));
+  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)]) {
     if (await Bun.file(candidate).exists())
       return candidate;
@@ -12764,7 +12812,7 @@ async function resolveSignalTestPreloadPath(target) {
 // pkgs/@akanjs/devkit/builder.ts
 import { existsSync as existsSync2 } from "fs";
 import { mkdir as mkdir10 } from "fs/promises";
-import path39 from "path";
+import path40 from "path";
 var SKIP_ENTRY_DIR_SET = new Set(["node_modules", "dist", "build", ".git", ".next"]);
 var assetExtensions = [".css", ".md", ".js", ".png", ".ico", ".svg", ".json", ".template"];
 var assetLoader = Object.fromEntries(assetExtensions.map((ext) => [ext, "file"]));
@@ -12781,14 +12829,14 @@ class Builder {
   #globEntrypoints(cwd, pattern) {
     const glob = new Bun.Glob(pattern);
     return Array.from(glob.scanSync({ cwd, onlyFiles: true })).filter((relativePath) => {
-      const segments = relativePath.split(path39.sep);
+      const segments = relativePath.split(path40.sep);
       return !segments.some((segment) => SKIP_ENTRY_DIR_SET.has(segment));
-    }).map((rel) => path39.join(cwd, rel));
+    }).map((rel) => path40.join(cwd, rel));
   }
   #globFiles(cwd, pattern = "**/*.*") {
     const glob = new Bun.Glob(pattern);
     return Array.from(glob.scanSync({ cwd, onlyFiles: true })).filter((relativePath) => {
-      const segments = relativePath.split(path39.sep);
+      const segments = relativePath.split(path40.sep);
       return !segments.some((segment) => SKIP_ENTRY_DIR_SET.has(segment));
     });
   }
@@ -12796,17 +12844,17 @@ class Builder {
     const out = [];
     for (const p of additionalEntryPoints) {
       if (p.includes("*")) {
-        const rel = p.startsWith(`${cwd}/`) || p.startsWith(`${cwd}${path39.sep}`) ? p.slice(cwd.length + 1) : p;
+        const rel = p.startsWith(`${cwd}/`) || p.startsWith(`${cwd}${path40.sep}`) ? p.slice(cwd.length + 1) : p;
         out.push(...this.#globEntrypoints(cwd, rel));
       } else
-        out.push(path39.isAbsolute(p) ? p : path39.join(cwd, p));
+        out.push(path40.isAbsolute(p) ? p : path40.join(cwd, p));
     }
     return out;
   }
   #getBuildOptions({ bundle = false, additionalEntryPoints = [] } = {}) {
     const cwd = this.#executor.cwdPath;
     const entrypoints = [
-      ...bundle ? [path39.join(cwd, "index.ts")] : this.#globEntrypoints(cwd, "**/*.{ts,tsx}"),
+      ...bundle ? [path40.join(cwd, "index.ts")] : this.#globEntrypoints(cwd, "**/*.{ts,tsx}"),
       ...this.#resolveAdditionalEntrypoints(cwd, additionalEntryPoints)
     ];
     return {
@@ -12827,9 +12875,9 @@ class Builder {
     for (const relativePath of this.#globFiles(cwd)) {
       if (relativePath === "package.json")
         continue;
-      const sourcePath = path39.join(cwd, relativePath);
-      const targetPath = path39.join(this.#distExecutor.cwdPath, relativePath);
-      await mkdir10(path39.dirname(targetPath), { recursive: true });
+      const sourcePath = path40.join(cwd, relativePath);
+      const targetPath = path40.join(this.#distExecutor.cwdPath, relativePath);
+      await mkdir10(path40.dirname(targetPath), { recursive: true });
       await Bun.write(targetPath, Bun.file(sourcePath));
     }
   }
@@ -12840,13 +12888,13 @@ class Builder {
       return withoutFormatDir;
     if (!hasDotSlash && withoutFormatDir === publishedPath)
       return publishedPath;
-    const parsed = path39.posix.parse(withoutFormatDir);
+    const parsed = path40.posix.parse(withoutFormatDir);
     if (![".js", ".mjs", ".cjs"].includes(parsed.ext))
       return withoutFormatDir;
-    const withoutExt = path39.posix.join(parsed.dir, parsed.name);
+    const withoutExt = path40.posix.join(parsed.dir, parsed.name);
     const sourcePath = withoutExt.startsWith("./") ? withoutExt.slice(2) : withoutExt;
     const sourceCandidates = [`${sourcePath}.ts`, `${sourcePath}.tsx`];
-    const matchedSource = sourceCandidates.find((candidate) => existsSync2(path39.join(this.#executor.cwdPath, candidate)));
+    const matchedSource = sourceCandidates.find((candidate) => existsSync2(path40.join(this.#executor.cwdPath, candidate)));
     if (!matchedSource)
       return withoutFormatDir;
     return hasDotSlash ? `./${matchedSource}` : matchedSource;
@@ -12895,9 +12943,9 @@ 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 path40 from "path";
+import path41 from "path";
 import { select as select2 } from "@inquirer/prompts";
 import { MobileProject } from "@trapezedev/project";
 import { capitalize as capitalize5 } from "akanjs/common";
@@ -13104,13 +13152,13 @@ var rootCapacitorConfigFilenames = [
   "capacitor.config.js",
   "capacitor.config.json"
 ];
-var rootCapacitorConfigPaths = (appRoot) => rootCapacitorConfigFilenames.map((file) => path40.join(appRoot, file));
+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 })));
 }
 async function writeRootCapacitorConfig(appRoot, content) {
   await clearRootCapacitorConfigs(appRoot);
-  await Bun.write(path40.join(appRoot, "capacitor.config.json"), content);
+  await Bun.write(path41.join(appRoot, "capacitor.config.json"), content);
 }
 var getLocalIP = () => {
   const interfaces = os.networkInterfaces();
@@ -13219,13 +13267,13 @@ function buildIosNativeRunCommand({
   scheme = "App",
   configuration = "Debug"
 }) {
-  const derivedDataPath = path40.join(appRoot, "ios/DerivedData", device.id);
+  const derivedDataPath = path41.join(appRoot, "ios/DerivedData", device.id);
   const productPlatform = device.kind === "device" ? "iphoneos" : "iphonesimulator";
   const destination = device.kind === "device" ? `id=${device.xcodebuildId ?? device.id}` : `platform=iOS Simulator,id=${device.id}`;
   return {
     configuration,
     derivedDataPath,
-    appPath: path40.join(derivedDataPath, "Build/Products", `${configuration}-${productPlatform}`, "App.app"),
+    appPath: path41.join(derivedDataPath, "Build/Products", `${configuration}-${productPlatform}`, "App.app"),
     xcodebuildArgs: [
       "-project",
       "App.xcodeproj",
@@ -13409,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,
@@ -13435,7 +13484,7 @@ function materializeCapacitorConfig(target, { operation, localServerUrl, localIp
     ...capacitorConfig,
     appId,
     appName,
-    webDir: path40.posix.join(".akan", "mobile", name, "www"),
+    webDir: path41.posix.join(".akan", "mobile", name, "www"),
     plugins: {
       CapacitorCookies: { enabled: true },
       ...pluginsConfig,
@@ -13492,10 +13541,10 @@ class CapacitorApp {
   constructor(app, target) {
     this.app = app;
     this.target = target;
-    this.targetRootPath = path40.posix.join(".akan", "mobile", this.target.name);
-    this.targetRoot = path40.join(this.app.cwdPath, this.targetRootPath);
-    this.targetWebRoot = path40.join(this.targetRoot, "www");
-    this.targetAssetRoot = path40.join(this.targetRoot, "assets");
+    this.targetRootPath = path41.posix.join(".akan", "mobile", this.target.name);
+    this.targetRoot = path41.join(this.app.cwdPath, this.targetRootPath);
+    this.targetWebRoot = path41.join(this.targetRoot, "www");
+    this.targetAssetRoot = path41.join(this.targetRoot, "assets");
     this.project = new MobileProject(this.app.cwdPath, {
       android: { path: this.androidRootPath },
       ios: { path: this.iosProjectPath }
@@ -13510,9 +13559,9 @@ class CapacitorApp {
     await mkdir11(this.targetRoot, { recursive: true });
     if (regenerate) {
       if (!platform || platform === "ios")
-        await rm5(path40.join(this.app.cwdPath, this.iosRootPath), { recursive: true, force: true });
+        await rm5(path41.join(this.app.cwdPath, this.iosRootPath), { recursive: true, force: true });
       if (!platform || platform === "android")
-        await rm5(path40.join(this.app.cwdPath, this.androidRootPath), { recursive: true, force: true });
+        await rm5(path41.join(this.app.cwdPath, this.androidRootPath), { recursive: true, force: true });
     }
     const project = this.project;
     await this.project.load();
@@ -13535,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`);
@@ -13635,7 +13684,7 @@ ${textError instanceof Error ? textError.message : ""}`);
     const xcodebuildArgs = noAllowProvisioningUpdates ? command.xcodebuildArgs : [...command.xcodebuildArgs.slice(0, -1), "-allowProvisioningUpdates", ...command.xcodebuildArgs.slice(-1)];
     try {
       await this.#spawn("xcodebuild", xcodebuildArgs, {
-        cwd: path40.join(this.app.cwdPath, this.iosProjectPath),
+        cwd: path41.join(this.app.cwdPath, this.iosProjectPath),
         env: mobileEnv
       });
       const devicectlId = runTarget.devicectlId ?? runTarget.id;
@@ -13660,7 +13709,7 @@ ${textError instanceof Error ? textError.message : ""}`);
     return isRecord2(this.target.ios) && typeof this.target.ios.scheme === "string" ? this.target.ios.scheme : "App";
   }
   async#getIosDevelopmentTeam() {
-    const pbxprojPath = path40.join(this.app.cwdPath, this.iosProjectPath, "App.xcodeproj/project.pbxproj");
+    const pbxprojPath = path41.join(this.app.cwdPath, this.iosProjectPath, "App.xcodeproj/project.pbxproj");
     if (!await Bun.file(pbxprojPath).exists())
       return;
     return (await Bun.file(pbxprojPath).text()).match(/DEVELOPMENT_TEAM = ([^;]+);/)?.[1]?.trim();
@@ -13678,15 +13727,16 @@ ${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(path40.join(this.app.cwdPath, this.androidRootPath, "app/build.gradle"));
+    const appGradle = await FileEditor.create(path41.join(this.app.cwdPath, this.androidRootPath, "app/build.gradle"));
     const buildTypesBlock = `
       debug {
         applicationIdSuffix ".debug"
@@ -13730,7 +13780,7 @@ ${error.message}`;
     const gradleCommand = isWindows ? "gradlew.bat" : "./gradlew";
     await this.app.spawn(gradleCommand, [assembleType === "apk" ? "assembleRelease" : "bundleRelease"], {
       stdio: "inherit",
-      cwd: path40.join(this.app.cwdPath, this.androidRootPath),
+      cwd: path41.join(this.app.cwdPath, this.androidRootPath),
       env: await this.#commandEnv("release", env)
     });
   }
@@ -13738,10 +13788,10 @@ ${error.message}`;
     await this.#spawnMobile("npx", ["cap", "open", "android"], { operation: "local", env: "local" });
   }
   async#ensureAndroidAssetsDir() {
-    await mkdir11(path40.join(this.app.cwdPath, this.androidAssetsPath), { recursive: true });
+    await mkdir11(path41.join(this.app.cwdPath, this.androidAssetsPath), { recursive: true });
   }
   async#ensureAndroidDebugKeystore() {
-    const keystorePath = path40.join(this.app.cwdPath, this.androidRootPath, "app/debug.keystore");
+    const keystorePath = path41.join(this.app.cwdPath, this.androidRootPath, "app/debug.keystore");
     if (await Bun.file(keystorePath).exists())
       return;
     await this.#spawn("keytool", [
@@ -13780,7 +13830,7 @@ ${error.message}`;
     await this.#spawnMobile("npx", args, { operation, env }, { stdio: "inherit" });
   }
   async#assertAndroidReleaseSigningConfig() {
-    const gradlePropertiesPath = path40.join(this.app.cwdPath, this.androidRootPath, "gradle.properties");
+    const gradlePropertiesPath = path41.join(this.app.cwdPath, this.androidRootPath, "gradle.properties");
     const gradleProperties = await Bun.file(gradlePropertiesPath).exists() ? await Bun.file(gradlePropertiesPath).text() : "";
     const missingKeys = getMissingAndroidReleaseSigningKeys({ gradleProperties });
     if (missingKeys.length > 0)
@@ -13807,16 +13857,20 @@ ${error.message}`;
     await this.#prepareAndroid({ operation: "release", env: "main" });
   }
   async prepareWww() {
-    const htmlSource = path40.join(this.app.dist.cwdPath, "csr", targetHtmlFilename(this.target));
+    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 mkdir11(this.targetWebRoot, { recursive: true });
-    await Bun.write(path40.join(this.targetWebRoot, "index.html"), this.#injectMobileTargetMeta(await Bun.file(htmlSource).text()));
+    await Bun.write(path41.join(this.targetWebRoot, "index.html"), this.#injectMobileTargetMeta(await Bun.file(htmlSource).text()));
   }
   #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}
@@ -13832,7 +13886,7 @@ ${error.message}`;
     });
     const content = `${JSON.stringify(config, null, 2)}
 `;
-    await Bun.write(path40.join(this.targetRoot, "capacitor.config.json"), content);
+    await Bun.write(path41.join(this.targetRoot, "capacitor.config.json"), content);
     return content;
   }
   async#prepareTargetAssets() {
@@ -13840,11 +13894,11 @@ ${error.message}`;
       return;
     await mkdir11(this.targetAssetRoot, { recursive: true });
     if (this.target.assets.icon)
-      await cp2(path40.join(this.app.cwdPath, this.target.assets.icon), path40.join(this.targetAssetRoot, "icon.png"), {
+      await cp2(path41.join(this.app.cwdPath, this.target.assets.icon), path41.join(this.targetAssetRoot, "icon.png"), {
         force: true
       });
     if (this.target.assets.splash)
-      await cp2(path40.join(this.app.cwdPath, this.target.assets.splash), path40.join(this.targetAssetRoot, "splash.png"), {
+      await cp2(path41.join(this.app.cwdPath, this.target.assets.splash), path41.join(this.targetAssetRoot, "splash.png"), {
         force: true
       });
   }
@@ -13852,11 +13906,11 @@ ${error.message}`;
     const files = this.target.files?.[platform];
     if (!files)
       return;
-    const platformRoot = path40.join(this.app.cwdPath, platform === "ios" ? this.iosRootPath : this.androidRootPath);
+    const platformRoot = path41.join(this.app.cwdPath, platform === "ios" ? this.iosRootPath : this.androidRootPath);
     await Promise.all(Object.entries(files).map(async ([to, from]) => {
-      const targetPath = path40.join(platformRoot, to);
-      await mkdir11(path40.dirname(targetPath), { recursive: true });
-      await cp2(path40.join(this.app.cwdPath, from), targetPath, { force: true });
+      const targetPath = path41.join(platformRoot, to);
+      await mkdir11(path41.dirname(targetPath), { recursive: true });
+      await cp2(path41.join(this.app.cwdPath, from), targetPath, { force: true });
     }));
   }
   async#generateAssets({ operation, env }) {
@@ -13866,7 +13920,7 @@ ${error.message}`;
       "@capacitor/assets",
       "generate",
       "--assetPath",
-      path40.posix.join(this.targetRootPath, "assets"),
+      path41.posix.join(this.targetRootPath, "assets"),
       "--iosProject",
       this.iosProjectPath,
       "--androidProject",
@@ -13899,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) {
@@ -13938,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() {
@@ -13997,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)) {
@@ -14076,7 +14261,7 @@ var Pkg = createInternalArgToken("Pkg");
 var Module = createInternalArgToken("Module");
 var Workspace = createInternalArgToken("Workspace");
 // pkgs/@akanjs/devkit/commandDecorators/command.ts
-import path41 from "path";
+import path42 from "path";
 import { confirm, input as input2, select as select3 } from "@inquirer/prompts";
 import { Logger as Logger10 } from "akanjs/common";
 import chalk6 from "chalk";
@@ -14580,7 +14765,7 @@ var runCommands = async (...commands) => {
     process.exit(1);
   });
   const __dirname2 = getDirname(import.meta.url);
-  const packageJsonCandidates = [`${path41.dirname(Bun.main)}/package.json`, `${__dirname2}/../package.json`];
+  const packageJsonCandidates = [`${path42.dirname(Bun.main)}/package.json`, `${__dirname2}/../package.json`];
   let cliPackageJson = null;
   for (const packageJsonPath of packageJsonCandidates) {
     if (!await FileSys.fileExists(packageJsonPath))
@@ -14860,8 +15045,8 @@ var scanModuleSpecifiers = (source2, filePath, includeExports) => {
   return importSpecifiers;
 };
 var parseTsConfig = (tsConfigPath = "./tsconfig.json") => {
-  const configFile = ts10.readConfigFile(tsConfigPath, (path42) => {
-    return ts10.sys.readFile(path42);
+  const configFile = ts10.readConfigFile(tsConfigPath, (path43) => {
+    return ts10.sys.readFile(path43);
   });
   return ts10.parseJsonConfigFileContent(configFile.config, ts10.sys, realpathSync(tsConfigPath).replace(/[^/\\]+$/, ""));
 };
@@ -15077,6 +15262,571 @@ ${document}
 `;
   }
 }
+// pkgs/@akanjs/devkit/qualityScanner.ts
+import { createHash } from "crypto";
+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";
+var MAX_FILE_LINES = 2000;
+var PLACEHOLDER_EXPORT_NAMES = new Set([
+  "aa",
+  "dumb",
+  "dumb2",
+  "someBaseLogic",
+  "someCommonLogic",
+  "someFrontendLogic",
+  "someBackendLogic"
+]);
+var SUGGESTED_RULES = [
+  "Keep generated scanSync index files out of hand-written changes; generated indexes should only contain one-depth export statements.",
+  "Generated Akan index files should not contain placeholder exports such as aa, dumb, dumb2, or some*Logic.",
+  "Dictionary text should not contain scaffold wording, misspellings, or stale copied domain nouns.",
+  "Warn earlier on very long Akan files: 500 lines for services, 800 lines for Template/Zone files, and 1000 lines for Util files.",
+  "Global declarations, Window augmentation, and prototype mutation should stay in explicitly approved low-level integration files.",
+  "Keep app root folders small and conventional: application code belongs under common, env, lib, page, private, public, script, srvkit, ui, or webkit.",
+  "Keep apps/*/lib and libs/*/lib root files limited to generated support facets such as cnst.ts, db.ts, dict.ts, sig.ts, srv.ts, st.ts, useClient.ts, and useServer.ts.",
+  "Use domain module folders consistently: lib/<model> for database modules, lib/_<service> for service modules, and lib/__scalar/<scalar> for scalar modules.",
+  "Keep module UI filenames predictable: database modules use <Model>.Template/Unit/Util/View/Zone.tsx, service modules use <Service>.Util/Zone.tsx, and scalar modules use <Scalar>.Template/Unit.tsx.",
+  "Move shared app utilities to apps/*/common instead of creating apps/*/base.",
+  "Avoid large mixed-purpose class files; class export files should import helpers from neighboring utility files instead of declaring them inline."
+];
+var APP_ROOT_FILES = new Set([
+  "akan.app.json",
+  "akan.config.ts",
+  "capacitor.config.ts",
+  "client.ts",
+  "main.ts",
+  "package.json",
+  "server.ts",
+  "tsconfig.json"
+]);
+var LIB_ROOT_FILES = new Set([
+  "cnst.ts",
+  "db.ts",
+  "dict.ts",
+  "option.ts",
+  "sig.ts",
+  "srv.ts",
+  "st.ts",
+  "useClient.ts",
+  "useServer.ts"
+]);
+var CONVENTION_SUFFIXES = [
+  ".constant.ts",
+  ".dictionary.ts",
+  ".document.ts",
+  ".service.ts",
+  ".signal.ts",
+  ".store.ts"
+];
+
+class AkanQualityScanner {
+  async scan(workspaceRoot) {
+    const targetFiles = await this.#collectTargetFiles(workspaceRoot);
+    const sourceFiles = await Promise.all(targetFiles.map((file) => this.#readSourceFile(workspaceRoot, file)));
+    const warnings = [
+      ...this.#scanGlobalQuality(sourceFiles),
+      ...sourceFiles.flatMap((sourceFile2) => this.#scanSingleFileQuality(sourceFile2)),
+      ...sourceFiles.flatMap((sourceFile2) => this.#scanConventionQuality(sourceFile2)),
+      ...sourceFiles.flatMap((sourceFile2) => this.#scanLayoutQuality(sourceFile2))
+    ];
+    return {
+      workspaceRoot,
+      scannedFiles: sourceFiles.length,
+      warnings: warnings.sort(compareWarnings),
+      suggestedRules: SUGGESTED_RULES
+    };
+  }
+  async#collectTargetFiles(workspaceRoot) {
+    const ignoreFilter = ignore2().add(await this.#readGitIgnore(workspaceRoot));
+    const files = [];
+    for (const targetRoot of ["apps", "libs"]) {
+      const absoluteTargetRoot = path43.join(workspaceRoot, targetRoot);
+      if (!await isDirectory(absoluteTargetRoot))
+        continue;
+      await this.#walkTargetFiles(workspaceRoot, absoluteTargetRoot, ignoreFilter, files);
+    }
+    return files.sort();
+  }
+  async#readGitIgnore(workspaceRoot) {
+    const gitIgnorePath = path43.join(workspaceRoot, ".gitignore");
+    if (!await Bun.file(gitIgnorePath).exists())
+      return [];
+    return (await readFile3(gitIgnorePath, "utf8")).split(/\r?\n/);
+  }
+  async#walkTargetFiles(workspaceRoot, currentPath, ignoreFilter, files) {
+    const entries = await readdir3(currentPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const absolutePath = path43.join(currentPath, entry.name);
+      const relativePath = toPosix(path43.relative(workspaceRoot, absolutePath));
+      if (shouldSkipPath(relativePath, entry.isDirectory(), ignoreFilter))
+        continue;
+      if (entry.isDirectory()) {
+        await this.#walkTargetFiles(workspaceRoot, absolutePath, ignoreFilter, files);
+        continue;
+      }
+      if ((relativePath.endsWith(".ts") || relativePath.endsWith(".tsx")) && !relativePath.endsWith(".d.ts")) {
+        files.push(relativePath);
+      }
+    }
+  }
+  async#readSourceFile(workspaceRoot, file) {
+    const absolutePath = path43.join(workspaceRoot, file);
+    const content = await readFile3(absolutePath, "utf8");
+    return {
+      file,
+      absolutePath,
+      content,
+      sourceFile: ts11.createSourceFile(file, content, ts11.ScriptTarget.Latest, true, getScriptKind(file))
+    };
+  }
+  #scanGlobalQuality(sourceFiles) {
+    const exportedFunctionLikes = sourceFiles.flatMap((sourceFile2) => getExportedFunctionLikes(sourceFile2));
+    const warnings = [];
+    for (const [name, declarations] of groupBy(exportedFunctionLikes, (declaration) => declaration.name)) {
+      if (declarations.length < 2)
+        continue;
+      warnings.push({
+        rule: "akan.global.duplicate-exported-function-name",
+        scope: "global",
+        severity: "warning",
+        message: `Exported function or class name "${name}" is declared in ${declarations.length} files.`,
+        locations: declarations.map(({ file, line }) => ({ file, line }))
+      });
+    }
+    const declarationsWithBody = exportedFunctionLikes.filter((declaration) => declaration.bodyFingerprint);
+    for (const [fingerprint, declarations] of groupBy(declarationsWithBody, (declaration) => declaration.bodyFingerprint ?? "")) {
+      const uniqueNames = new Set(declarations.map((declaration) => declaration.name));
+      if (declarations.length < 2 || uniqueNames.size < 2 || fingerprint === "")
+        continue;
+      warnings.push({
+        rule: "akan.global.duplicate-exported-function-body",
+        scope: "global",
+        severity: "warning",
+        message: `Exported functions/classes share the same implementation body: ${declarations.map((declaration) => declaration.name).join(", ")}.`,
+        locations: declarations.map(({ file, line }) => ({ file, line }))
+      });
+    }
+    return warnings;
+  }
+  #scanSingleFileQuality(sourceFile2) {
+    const warnings = [];
+    const lineCount = sourceFile2.content.split(/\r?\n/).length;
+    const recommendedLineLimit = getRecommendedLineLimit(sourceFile2.file);
+    if (recommendedLineLimit && lineCount > recommendedLineLimit) {
+      warnings.push({
+        rule: "akan.file.recommended-max-lines",
+        scope: "file",
+        severity: "warning",
+        file: sourceFile2.file,
+        message: `File has ${lineCount} lines. Recommended limit for this file type is ${recommendedLineLimit} lines.`
+      });
+    }
+    if (lineCount > MAX_FILE_LINES) {
+      warnings.push({
+        rule: "akan.file.max-lines",
+        scope: "file",
+        severity: "warning",
+        file: sourceFile2.file,
+        message: `File has ${lineCount} lines. Keep single files under ${MAX_FILE_LINES} lines.`
+      });
+    }
+    warnings.push(...getPlaceholderExportWarnings(sourceFile2));
+    warnings.push(...getDictionaryTextWarnings(sourceFile2));
+    warnings.push(...getGlobalMutationWarnings(sourceFile2));
+    const exportedClassNames = getExportedClassNames(sourceFile2.sourceFile);
+    if (exportedClassNames.length === 0)
+      return warnings;
+    const allowedInterfaceNames = new Set(exportedClassNames.map((name) => `${name}Options`));
+    for (const declaration of getTopLevelDeclarations(sourceFile2)) {
+      if (declaration.kind === "class" && exportedClassNames.includes(declaration.name))
+        continue;
+      if (declaration.kind === "interface" && allowedInterfaceNames.has(declaration.name))
+        continue;
+      warnings.push({
+        rule: "akan.file.class-export-global-declaration",
+        scope: "file",
+        severity: "warning",
+        file: sourceFile2.file,
+        line: declaration.line,
+        message: `Class export files should not declare top-level ${declaration.kind} "${declaration.name}". Move helpers to another file and import them.`
+      });
+    }
+    return warnings;
+  }
+  #scanConventionQuality(sourceFile2) {
+    const suffix = CONVENTION_SUFFIXES.find((candidate) => sourceFile2.file.endsWith(candidate));
+    if (!suffix)
+      return [];
+    const modelName = toPascalCase(path43.basename(sourceFile2.file, suffix));
+    const warnings = [];
+    for (const declaration of getTopLevelDeclarations(sourceFile2)) {
+      if (isAllowedConventionDeclaration(suffix, modelName, declaration))
+        continue;
+      warnings.push({
+        rule: `akan.convention${suffix.replace(".ts", "")}`,
+        scope: "convention",
+        severity: "warning",
+        file: sourceFile2.file,
+        line: declaration.line,
+        message: `${path43.basename(sourceFile2.file)} should not declare top-level ${declaration.kind} "${declaration.name}". Allowed declarations: ${getConventionDescription(suffix, modelName)}.`
+      });
+    }
+    return warnings;
+  }
+  #scanLayoutQuality(sourceFile2) {
+    const segments = sourceFile2.file.split("/");
+    const warnings = [];
+    if (segments[0] === "apps" && segments.length === 3 && !APP_ROOT_FILES.has(segments[2])) {
+      warnings.push({
+        rule: "akan.layout.app-root-file",
+        scope: "layout",
+        severity: "warning",
+        file: sourceFile2.file,
+        message: `Unexpected app root file "${segments[2]}". Keep application code in conventional app folders.`
+      });
+    }
+    const libRootFile = getLibRootFile(sourceFile2.file);
+    if (libRootFile && !LIB_ROOT_FILES.has(libRootFile)) {
+      warnings.push({
+        rule: "akan.layout.lib-root-file",
+        scope: "layout",
+        severity: "warning",
+        file: sourceFile2.file,
+        message: `Unexpected lib root file "${libRootFile}". Keep direct lib root files limited to generated support facets.`
+      });
+    }
+    const moduleUiWarning = getModuleUiWarning(sourceFile2.file);
+    if (moduleUiWarning)
+      warnings.push(moduleUiWarning);
+    return warnings;
+  }
+}
+function formatQualityScanResult(result) {
+  const sections = [
+    "Akan Code Quality Scan",
+    `workspace: ${result.workspaceRoot}`,
+    `scanned files: ${result.scannedFiles}`,
+    `warnings: ${result.warnings.length}`,
+    "",
+    "Warnings:",
+    "",
+    ...formatQualityWarnings(result.warnings),
+    "",
+    "Suggested quality rules:",
+    "",
+    ...result.suggestedRules.map((rule) => `  - ${rule}`)
+  ];
+  return sections.join(`
+`);
+}
+function formatQualityWarnings(warnings) {
+  if (warnings.length === 0)
+    return ["No warnings found."];
+  return warnings.flatMap((warning) => {
+    const location = formatQualityLocation(warning.file, warning.line);
+    const lines = [`${location} - warning ${warning.rule}: ${warning.message}`];
+    if (warning.locations?.length) {
+      lines.push(...warning.locations.map(({ file, line }) => `  note: related location ${formatQualityLocation(file, line)}`));
+    }
+    return lines;
+  });
+}
+function formatQualityLocation(file, line) {
+  return `${file ?? "<global>"}:${line ?? 1}:1`;
+}
+function getExportedFunctionLikes(sourceFile2) {
+  const declarations = [];
+  for (const statement of sourceFile2.sourceFile.statements) {
+    if (ts11.isFunctionDeclaration(statement) && statement.name && isExported(statement)) {
+      declarations.push({
+        name: statement.name.text,
+        kind: "function",
+        file: sourceFile2.file,
+        line: getLine(sourceFile2.sourceFile, statement),
+        bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, statement.body)
+      });
+    }
+    if (ts11.isClassDeclaration(statement) && statement.name && isExported(statement)) {
+      declarations.push({
+        name: statement.name.text,
+        kind: "class",
+        file: sourceFile2.file,
+        line: getLine(sourceFile2.sourceFile, statement),
+        bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, statement)
+      });
+    }
+    if (ts11.isVariableStatement(statement) && isExported(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts11.isIdentifier(declaration.name) || !isFunctionLikeInitializer(declaration.initializer))
+          continue;
+        declarations.push({
+          name: declaration.name.text,
+          kind: "function-variable",
+          file: sourceFile2.file,
+          line: getLine(sourceFile2.sourceFile, declaration),
+          bodyFingerprint: getBodyFingerprint(sourceFile2.sourceFile, declaration.initializer)
+        });
+      }
+    }
+  }
+  return declarations;
+}
+function getExportedClassNames(sourceFile2) {
+  return sourceFile2.statements.filter((statement) => ts11.isClassDeclaration(statement) && !!statement.name).filter((statement) => isExported(statement)).map((statement) => statement.name.text);
+}
+function getPlaceholderExportWarnings(sourceFile2) {
+  if (!sourceFile2.file.endsWith("/index.ts") && !sourceFile2.file.endsWith("/index.tsx"))
+    return [];
+  return getTopLevelDeclarations(sourceFile2).filter((declaration) => declaration.exported && PLACEHOLDER_EXPORT_NAMES.has(declaration.name)).map((declaration) => ({
+    rule: "akan.file.placeholder-export",
+    scope: "file",
+    severity: "warning",
+    file: sourceFile2.file,
+    line: declaration.line,
+    message: `Generated or barrel index file should not export placeholder "${declaration.name}".`
+  }));
+}
+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" }
+  ];
+  return stalePatterns.flatMap(({ pattern, label }) => findPatternLines(sourceFile2.content, pattern).map((line) => ({
+    rule: "akan.file.dictionary-stale-text",
+    scope: "file",
+    severity: "warning",
+    file: sourceFile2.file,
+    line,
+    message: `Dictionary text appears to contain ${label}.`
+  })));
+}
+function getGlobalMutationWarnings(sourceFile2) {
+  const warnings = [];
+  for (const statement of sourceFile2.sourceFile.statements) {
+    if (ts11.isModuleDeclaration(statement) && statement.name.getText(sourceFile2.sourceFile) === "global") {
+      warnings.push({
+        rule: "akan.file.global-declaration",
+        scope: "file",
+        severity: "warning",
+        file: sourceFile2.file,
+        line: getLine(sourceFile2.sourceFile, statement),
+        message: "Global declarations require an explicit low-level integration allowlist."
+      });
+    }
+    if (ts11.isInterfaceDeclaration(statement) && statement.name.text === "Window") {
+      warnings.push({
+        rule: "akan.file.window-augmentation",
+        scope: "file",
+        severity: "warning",
+        file: sourceFile2.file,
+        line: getLine(sourceFile2.sourceFile, statement),
+        message: "Window augmentation should be isolated to approved browser integration files."
+      });
+    }
+    if (ts11.isExpressionStatement(statement) && statement.expression.getText(sourceFile2.sourceFile).includes(".prototype.")) {
+      warnings.push({
+        rule: "akan.file.prototype-mutation",
+        scope: "file",
+        severity: "warning",
+        file: sourceFile2.file,
+        line: getLine(sourceFile2.sourceFile, statement),
+        message: "Prototype mutation should be avoided or isolated to approved low-level integration files."
+      });
+    }
+  }
+  return warnings;
+}
+function getTopLevelDeclarations(sourceFile2) {
+  return sourceFile2.sourceFile.statements.flatMap((statement) => getTopLevelDeclaration(sourceFile2.sourceFile, statement));
+}
+function getTopLevelDeclaration(sourceFile2, statement) {
+  const line = getLine(sourceFile2, statement);
+  if (ts11.isClassDeclaration(statement) && statement.name) {
+    return [{ name: statement.name.text, kind: "class", line, exported: isExported(statement), node: statement }];
+  }
+  if (ts11.isFunctionDeclaration(statement) && statement.name) {
+    return [{ name: statement.name.text, kind: "function", line, exported: isExported(statement), node: statement }];
+  }
+  if (ts11.isInterfaceDeclaration(statement)) {
+    return [{ name: statement.name.text, kind: "interface", line, exported: isExported(statement), node: statement }];
+  }
+  if (ts11.isTypeAliasDeclaration(statement)) {
+    return [{ name: statement.name.text, kind: "type", line, exported: isExported(statement), node: statement }];
+  }
+  if (ts11.isEnumDeclaration(statement)) {
+    return [{ name: statement.name.text, kind: "enum", line, exported: isExported(statement), node: statement }];
+  }
+  if (ts11.isVariableStatement(statement)) {
+    return statement.declarationList.declarations.filter((declaration) => ts11.isIdentifier(declaration.name)).map((declaration) => ({
+      name: declaration.name.text,
+      kind: "variable",
+      line: getLine(sourceFile2, declaration),
+      exported: isExported(statement),
+      node: statement
+    }));
+  }
+  if (ts11.isExportDeclaration(statement)) {
+    return [{ name: "export declaration", kind: "export", line, exported: true, node: statement }];
+  }
+  return [];
+}
+function isAllowedConventionDeclaration(suffix, modelName, declaration) {
+  if (suffix === ".dictionary.ts")
+    return isExportedConst(declaration) && declaration.name === "dictionary";
+  if (suffix === ".constant.ts")
+    return isAllowedConstantDeclaration(modelName, declaration);
+  if (suffix === ".document.ts")
+    return declaration.kind === "class" && [`${modelName}Filter`, modelName, `${modelName}Model`].includes(declaration.name);
+  if (suffix === ".service.ts")
+    return declaration.kind === "class" && declaration.name === `${modelName}Service`;
+  if (suffix === ".signal.ts")
+    return declaration.kind === "class" && [`${modelName}Internal`, `${modelName}Slice`, `${modelName}Endpoint`].includes(declaration.name);
+  if (suffix === ".store.ts")
+    return declaration.kind === "class" && declaration.name === `${modelName}Store`;
+  return false;
+}
+function isAllowedConstantDeclaration(modelName, declaration) {
+  if (declaration.kind !== "class")
+    return false;
+  if ([`${modelName}Input`, `${modelName}Object`, modelName, `Light${modelName}`, `${modelName}Insight`].includes(declaration.name))
+    return true;
+  if (!ts11.isClassDeclaration(declaration.node))
+    return false;
+  const heritageClause = declaration.node.heritageClauses?.find((clause) => clause.token === ts11.SyntaxKind.ExtendsKeyword);
+  const expression = heritageClause?.types[0]?.expression;
+  return !!expression && expression.getText().startsWith("enumOf(");
+}
+function getConventionDescription(suffix, modelName) {
+  if (suffix === ".dictionary.ts")
+    return "export const dictionary";
+  if (suffix === ".constant.ts")
+    return `${modelName}Input, ${modelName}Object, ${modelName}, Light${modelName}, ${modelName}Insight, or enumOf classes`;
+  if (suffix === ".document.ts")
+    return `${modelName}Filter, ${modelName}, or ${modelName}Model`;
+  if (suffix === ".service.ts")
+    return `${modelName}Service`;
+  if (suffix === ".signal.ts")
+    return `${modelName}Internal, ${modelName}Slice, or ${modelName}Endpoint`;
+  return `${modelName}Store`;
+}
+function getLibRootFile(file) {
+  const segments = file.split("/");
+  if (segments[0] === "libs" && 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) {
+  if (!file.endsWith(".tsx"))
+    return null;
+  const moduleInfo = getModuleInfo(file);
+  if (!moduleInfo)
+    return null;
+  const { moduleName, fileName, kind } = moduleInfo;
+  const pascalName = toPascalCase(moduleName.replace(/^_+/, ""));
+  const allowedSuffixes = kind === "database" ? ["Template", "Unit", "Util", "View", "Zone"] : kind === "service" ? ["Util", "Zone"] : ["Template", "Unit"];
+  const allowedFileNames = new Set(allowedSuffixes.map((suffix) => `${pascalName}.${suffix}.tsx`));
+  if (allowedFileNames.has(fileName) || fileName.endsWith(".test.tsx") || fileName.endsWith(".spec.tsx"))
+    return null;
+  return {
+    rule: "akan.layout.module-ui-file",
+    scope: "layout",
+    severity: "warning",
+    file,
+    message: `Unexpected ${kind} module UI filename "${fileName}". Expected one of: ${[...allowedFileNames].join(", ")}.`
+  };
+}
+function getModuleInfo(file) {
+  const segments = file.split("/");
+  const libIndex = segments.indexOf("lib");
+  if (libIndex < 0)
+    return null;
+  const moduleName = segments[libIndex + 1];
+  if (moduleName === "__scalar") {
+    if (segments.length !== libIndex + 4)
+      return null;
+    return { moduleName: segments[libIndex + 2], fileName: segments[libIndex + 3], kind: "scalar" };
+  }
+  if (segments.length !== libIndex + 3)
+    return null;
+  const fileName = segments[libIndex + 2];
+  if (moduleName.startsWith("__")) {
+    const scalarName = moduleName === "__scalar" ? segments[libIndex + 2] : moduleName;
+    return { moduleName: scalarName, fileName, kind: "scalar" };
+  }
+  if (moduleName.startsWith("_"))
+    return { moduleName, fileName, kind: "service" };
+  return { moduleName, fileName, kind: "database" };
+}
+function isExportedConst(declaration) {
+  return declaration.exported && ts11.isVariableStatement(declaration.node) && (declaration.node.declarationList.flags & ts11.NodeFlags.Const) !== 0;
+}
+function isExported(node) {
+  return !!ts11.getCombinedModifierFlags(node) && !!(ts11.getCombinedModifierFlags(node) & ts11.ModifierFlags.Export);
+}
+function isFunctionLikeInitializer(node) {
+  return !!node && (ts11.isArrowFunction(node) || ts11.isFunctionExpression(node));
+}
+function getBodyFingerprint(sourceFile2, node) {
+  if (!node)
+    return;
+  const normalizedBody = node.getText(sourceFile2).replace(/\s+/g, " ").trim();
+  if (normalizedBody.length < 80)
+    return;
+  return createHash("sha256").update(normalizedBody).digest("hex");
+}
+function shouldSkipPath(relativePath, isDirectory, ignoreFilter) {
+  const ignorePath = isDirectory ? `${relativePath}/` : relativePath;
+  return relativePath === ".git" || relativePath.includes("/.git/") || relativePath.includes("/node_modules/") || ignoreFilter.ignores(relativePath) || ignoreFilter.ignores(ignorePath);
+}
+async function isDirectory(absolutePath) {
+  try {
+    return (await stat4(absolutePath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function getScriptKind(file) {
+  return file.endsWith(".tsx") ? ts11.ScriptKind.TSX : ts11.ScriptKind.TS;
+}
+function getLine(sourceFile2, node) {
+  return sourceFile2.getLineAndCharacterOfPosition(node.getStart(sourceFile2)).line + 1;
+}
+function getRecommendedLineLimit(file) {
+  if (file.endsWith(".service.ts"))
+    return 500;
+  if (file.endsWith(".Template.tsx") || file.endsWith(".Zone.tsx"))
+    return 800;
+  if (file.endsWith(".Util.tsx"))
+    return 1000;
+  return null;
+}
+function findPatternLines(content, pattern) {
+  return content.split(/\r?\n/).flatMap((line, index) => pattern.test(line) ? [index + 1] : []);
+}
+function toPascalCase(value) {
+  return value.replace(/(^|[-_./])([a-zA-Z0-9])/g, (_, __, char) => char.toUpperCase()).replace(/[-_./]/g, "");
+}
+function toPosix(value) {
+  return value.split(path43.sep).join("/");
+}
+function groupBy(items, getKey) {
+  const grouped = new Map;
+  for (const item of items) {
+    const key = getKey(item);
+    grouped.set(key, [...grouped.get(key) ?? [], item]);
+  }
+  return grouped;
+}
+function compareWarnings(a, b) {
+  return a.scope.localeCompare(b.scope) || (a.file ?? "").localeCompare(b.file ?? "") || (a.line ?? 0) - (b.line ?? 0) || a.rule.localeCompare(b.rule);
+}
 // pkgs/@akanjs/devkit/selectModel.ts
 import { select as select5 } from "@inquirer/prompts";
 // pkgs/@akanjs/devkit/streamAi.ts
@@ -16038,7 +16788,7 @@ class ApplicationCommand extends command("application", [ApplicationScript], ({
 import { Logger as Logger16 } from "akanjs/common";
 
 // pkgs/@akanjs/cli/package/package.runner.ts
-import path42 from "path";
+import path44 from "path";
 import { Logger as Logger14 } from "akanjs/common";
 var {$: $2 } = globalThis.Bun;
 
@@ -16058,11 +16808,11 @@ class PackageRunner extends runner("package") {
   }
   async#getInstalledPackageJson() {
     const packageJsonCandidates = [
-      `${path42.dirname(Bun.main)}/package.json`,
+      `${path44.dirname(Bun.main)}/package.json`,
       `${process.cwd()}/node_modules/akanjs/package.json`
     ];
     try {
-      packageJsonCandidates.unshift(Bun.resolveSync("akanjs/package.json", path42.dirname(Bun.main)));
+      packageJsonCandidates.unshift(Bun.resolveSync("akanjs/package.json", path44.dirname(Bun.main)));
     } catch {}
     for (const packageJsonPath of packageJsonCandidates) {
       if (!await Bun.file(packageJsonPath).exists())
@@ -16071,7 +16821,7 @@ class PackageRunner extends runner("package") {
       if (packageJson.name === "akanjs" || packageJson.name === "@akanjs/cli")
         return packageJson;
     }
-    throw new Error(`[package] failed to locate akanjs package.json from ${path42.dirname(Bun.main)}`);
+    throw new Error(`[package] failed to locate akanjs package.json from ${path44.dirname(Bun.main)}`);
   }
   async createPackage(workspace, pkgName) {
     await workspace.applyTemplate({ basePath: `pkgs/${pkgName}`, template: "pkgRoot", dict: { pkgName } });
@@ -16246,7 +16996,7 @@ class PackageScript extends script("package", [PackageRunner]) {
 }
 
 // pkgs/@akanjs/cli/cloud/cloud.runner.ts
-import path43 from "path";
+import path45 from "path";
 import { confirm as confirm4, input as input5, select as select8 } from "@inquirer/prompts";
 import { Logger as Logger15, sleep } from "akanjs/common";
 import chalk7 from "chalk";
@@ -16517,7 +17267,7 @@ ${chalk7.green("\u27A4")} Authentication Required`));
     await Promise.all(akanPkgs.map(async (library) => {
       Logger15.info(`Publishing ${library}@${nextVersion} to ${registry ?? "npm"}...`);
       await workspace.spawn("npm", ["publish", "--tag", tag, ...this.#getRegistryArgs(registry), ...this.#getLocalRegistryAuthArgs(registry)], {
-        cwd: path43.join(workspace.workspaceRoot, "dist/pkgs", library),
+        cwd: path45.join(workspace.workspaceRoot, "dist/pkgs", library),
         env: this.#getRegistryEnv(registry),
         stdio: "inherit"
       });
@@ -16571,11 +17321,12 @@ ${chalk7.green("\u27A4")} Authentication Required`));
   async downloadEnv(cloudApi2, workspace, workspaceId) {
     await workspace.mkdir("local");
     const localPath = await cloudApi2.downloadEnv(workspaceId);
-    await workspace.spawn("tar", ["-xf", localPath], { cwd: workspace.workspaceRoot });
+    const relativePath = path45.relative(workspace.workspaceRoot, localPath).split(path45.sep).join("/");
+    await workspace.spawn("tar", ["-xf", relativePath], { cwd: workspace.workspaceRoot });
     await workspace.remove(localPath);
   }
   async uploadEnv(cloudApi2, workspaceId, filePath) {
-    const file = new File([Bun.file(filePath)], path43.basename(filePath));
+    const file = new File([Bun.file(filePath)], path45.basename(filePath));
     await cloudApi2.uploadEnv(workspaceId, file);
   }
   async downloadEnvByScp(workspace) {
@@ -16625,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)
@@ -16636,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
@@ -16667,14 +17467,14 @@ class CloudScript extends script("cloud", [CloudRunner, ApplicationScript, Packa
   }
   async uploadEnv(workspace) {
     const workspaceId = workspace.getWorkspaceId({ allowEmpty: true });
-    const { path: path44 } = await this.cloudRunner.gatherEnvFiles(workspace);
+    const { path: path46 } = await this.cloudRunner.gatherEnvFiles(workspace);
     if (workspaceId) {
       await this.login(workspace);
       const cloudApi2 = await CloudApi.fromHost(workspace);
-      await this.cloudRunner.uploadEnv(cloudApi2, workspaceId, path44);
+      await this.cloudRunner.uploadEnv(cloudApi2, workspaceId, path46);
       return;
     }
-    await this.cloudRunner.uploadEnvByScp(workspace, path44);
+    await this.cloudRunner.uploadEnvByScp(workspace, path46);
   }
   async deployAkan(workspace, { test = true, registryUrl } = {}) {
     const akanPkgs = await this.cloudRunner.getAkanPkgs(workspace);
@@ -16915,8 +17715,8 @@ class RepairRunner extends runner("repair") {
 }
 
 // pkgs/@akanjs/cli/workflow/workflow.runner.ts
-import { mkdir as mkdir12, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
-import path44 from "path";
+import { mkdir as mkdir12, readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
+import path46 from "path";
 import { capitalize as capitalize8 } from "akanjs/common";
 
 // pkgs/@akanjs/cli/workflows/shared.ts
@@ -17459,7 +18259,7 @@ var workflowSpecs = [
 ];
 
 // pkgs/@akanjs/cli/workflow/workflow.runner.ts
-var resolvePath = (filePath) => path44.isAbsolute(filePath) ? filePath : path44.join(process.cwd(), filePath);
+var resolvePath = (filePath) => path46.isAbsolute(filePath) ? filePath : path46.join(process.cwd(), filePath);
 var isRecord3 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var isWorkflowPlan2 = (value) => {
   if (!isRecord3(value))
@@ -17557,7 +18357,7 @@ var defaultValidationExecutor = (workspace) => async (command3) => {
     };
   }
 };
-var readJsonFile = async (filePath) => JSON.parse(await readFile2(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 : "";
@@ -17653,8 +18453,8 @@ class WorkflowRunner extends runner("workflow") {
     const plan2 = createWorkflowPlan(spec, compactWorkflowInputs(inputs));
     if (out) {
       const outPath = resolvePath(out);
-      await mkdir12(path44.dirname(outPath), { recursive: true });
-      await writeFile2(outPath, jsonText(plan2));
+      await mkdir12(path46.dirname(outPath), { recursive: true });
+      await writeFile3(outPath, jsonText(plan2));
     }
     return format === "json" ? jsonText(plan2) : renderWorkflowPlan(plan2);
   }
@@ -17672,7 +18472,7 @@ class WorkflowRunner extends runner("workflow") {
     };
     let plan2;
     try {
-      const parsed = JSON.parse(await readFile2(resolvePath(planPath), "utf8"));
+      const parsed = JSON.parse(await readFile4(resolvePath(planPath), "utf8"));
       if (!isWorkflowPlan2(parsed)) {
         const report = failedApplyReport("unknown", [
           {
@@ -19477,14 +20277,14 @@ class GuidelinePrompt extends Prompter {
   async#getScanFilePaths(matchPattern, { avoidDirs = ["node_modules", ".next"], filterText } = {}) {
     const glob = new Bun.Glob(matchPattern);
     const paths = [];
-    for await (const path45 of glob.scan({ cwd: this.workspace.workspaceRoot, absolute: true })) {
-      if (avoidDirs.some((dir) => path45.includes(dir)))
+    for await (const path47 of glob.scan({ cwd: this.workspace.workspaceRoot, absolute: true })) {
+      if (avoidDirs.some((dir) => path47.includes(dir)))
         continue;
-      const fileContent = await FileSys.readText(path45);
+      const fileContent = await FileSys.readText(path47);
       const textFilter = filterText ? new RegExp(filterText) : null;
       if (filterText && !textFilter?.test(fileContent))
         continue;
-      paths.push(path45);
+      paths.push(path47);
     }
     return paths;
   }
@@ -19804,7 +20604,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 path45 from "path";
+import path47 from "path";
 import { Logger as Logger19 } from "akanjs/common";
 var defaultLocalRegistryUrl = "http://127.0.0.1:4873";
 var containerName = "akan-verdaccio";
@@ -19822,8 +20622,8 @@ class LocalRegistryRunner extends runner("localRegistry") {
       Logger19.info(`Local registry is already running at ${registry}`);
       return registry;
     } catch {}
-    const configPath2 = path45.join(workspace.workspaceRoot, "pkgs/@akanjs/cli/localRegistry/verdaccio.yaml");
-    const storagePath = path45.join(workspace.workspaceRoot, ".akan/verdaccio/storage");
+    const configPath2 = path47.join(workspace.workspaceRoot, "pkgs/@akanjs/cli/localRegistry/verdaccio.yaml");
+    const storagePath = path47.join(workspace.workspaceRoot, ".akan/verdaccio/storage");
     await mkdir13(storagePath, { recursive: true });
     await workspace.spawn("docker", [
       "run",
@@ -19846,13 +20646,13 @@ class LocalRegistryRunner extends runner("localRegistry") {
     try {
       await workspace.spawn("docker", ["rm", "-f", containerName], { stdio: "inherit" });
     } catch {}
-    await rm6(path45.join(workspace.workspaceRoot, ".akan/verdaccio"), { recursive: true, force: true });
+    await rm6(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 = path45.join(workspace.workspaceRoot, ".akan/e2e");
-    await rm6(path45.join(smokeRoot, smokeRepoName), { recursive: true, force: true });
+    const smokeRoot = path47.join(workspace.workspaceRoot, ".akan/e2e");
+    await rm6(path47.join(smokeRoot, smokeRepoName), { recursive: true, force: true });
     await workspace.spawn(process.execPath, [
       "dist/pkgs/create-akan-workspace/index.js",
       smokeRepoName,
@@ -19869,12 +20669,12 @@ class LocalRegistryRunner extends runner("localRegistry") {
       stdio: "inherit"
     });
     await workspace.spawn("akan", ["typecheck", smokeAppName], {
-      cwd: path45.join(smokeRoot, smokeRepoName),
+      cwd: path47.join(smokeRoot, smokeRepoName),
       env: { ...process.env, AKAN_NPM_REGISTRY: registry, NPM_CONFIG_REGISTRY: registry },
       stdio: "inherit"
     });
     await workspace.spawn("akan", ["build", smokeAppName], {
-      cwd: path45.join(smokeRoot, smokeRepoName),
+      cwd: path47.join(smokeRoot, smokeRepoName),
       env: { ...process.env, AKAN_NPM_REGISTRY: registry, NPM_CONFIG_REGISTRY: registry },
       stdio: "inherit"
     });
@@ -20053,8 +20853,46 @@ class PrimitiveCommand extends command("primitive", [PrimitiveScript], ({ public
 })) {
 }
 
-// pkgs/@akanjs/cli/repair/repair.script.ts
+// pkgs/@akanjs/cli/quality/quality.script.ts
 import { Logger as Logger22 } from "akanjs/common";
+
+// pkgs/@akanjs/cli/quality/quality.runner.ts
+class QualityRunner extends runner("quality") {
+  async scan(workspace) {
+    return await new AkanQualityScanner().scan(workspace.workspaceRoot);
+  }
+}
+
+// pkgs/@akanjs/cli/quality/quality.script.ts
+class QualityScript extends script("quality", [QualityRunner]) {
+  async scan(workspace, format = "text") {
+    const spinner2 = workspace.spinning("Scanning Akan code quality...");
+    const result = await this.qualityRunner.scan(workspace);
+    spinner2.succeed(`Quality scan completed (${result.scannedFiles} files, ${result.warnings.length} warnings)`);
+    Logger22.rawLog(format === "json" ? JSON.stringify(result, null, 2) : formatQualityScanResult(result));
+  }
+}
+
+// pkgs/@akanjs/cli/quality/quality.command.ts
+class QualityCommand extends command("quality", [QualityScript], ({ public: target }) => ({
+  quality: target({ desc: "Scan apps and libs for Akan code quality warnings" }).arg("action", String, {
+    desc: "quality action",
+    default: "scan",
+    enum: ["scan"]
+  }).option("format", String, {
+    desc: "output format",
+    default: "text",
+    enum: ["text", "json"]
+  }).with(Workspace).exec(async function(action, format, workspace) {
+    if (action !== "scan")
+      throw new Error(`Unknown quality action: ${action}. Use "scan".`);
+    await this.qualityScript.scan(workspace, format);
+  })
+})) {
+}
+
+// pkgs/@akanjs/cli/repair/repair.script.ts
+import { Logger as Logger23 } from "akanjs/common";
 class RepairScript extends script("repair", [RepairRunner]) {
   async repair(kind, {
     workspace,
@@ -20063,7 +20901,7 @@ class RepairScript extends script("repair", [RepairRunner]) {
     target = null,
     format = "markdown"
   }) {
-    Logger22.rawLog(await this.repairRunner.repair(kind, {
+    Logger23.rawLog(await this.repairRunner.repair(kind, {
       workspace,
       app,
       module,
@@ -20103,12 +20941,12 @@ class RepairCommand extends command("repair", [RepairScript], ({ public: target
 }
 
 // pkgs/@akanjs/cli/scalar/scalar.command.ts
-import { Logger as Logger23, lowerlize as lowerlize3 } from "akanjs/common";
+import { Logger as Logger24, lowerlize as lowerlize3 } from "akanjs/common";
 class ScalarCommand extends command("scalar", [ScalarScript], ({ public: target }) => ({
   createScalar: target({ desc: "Create a new scalar type (simple data model without DB)" }).arg("scalarName", String, { desc: "name of scalar" }).with(Sys).option("ai", Boolean, { default: false, desc: "use ai to create scalar" }).option("format", String, { flag: "o", desc: "output format", default: "markdown", enum: ["markdown", "json"] }).exec(async function(scalarName, sys3, ai, format) {
     const name = lowerlize3(scalarName.replace(/ /g, ""));
     const report = ai ? await this.scalarScript.createScalarWithAi(sys3, name) : await this.scalarScript.createScalar(sys3, name);
-    Logger23.rawLog(renderPrimitiveReport(report, format));
+    Logger24.rawLog(renderPrimitiveReport(report, format));
   }),
   removeScalar: target({ desc: "Remove a scalar type from an app or library" }).arg("scalarName", String, { desc: "name of scalar" }).with(Sys).exec(async function(scalarName, sys3) {
     await this.scalarScript.removeScalar(sys3, scalarName);
@@ -20117,7 +20955,7 @@ class ScalarCommand extends command("scalar", [ScalarScript], ({ public: target
 }
 
 // pkgs/@akanjs/cli/workflow/workflow.script.ts
-import { Logger as Logger24 } from "akanjs/common";
+import { Logger as Logger25 } from "akanjs/common";
 class WorkflowScript extends script("workflow", [WorkflowRunner, ModuleScript, ScalarScript, PrimitiveScript]) {
   async workflow(action, workflow2, inputs, {
     format = "markdown",
@@ -20126,23 +20964,23 @@ class WorkflowScript extends script("workflow", [WorkflowRunner, ModuleScript, S
     workspace
   } = {}) {
     if (action === "list") {
-      Logger24.rawLog(this.workflowRunner.list({ format }));
+      Logger25.rawLog(this.workflowRunner.list({ format }));
       return;
     }
     if (!workflow2)
       throw new Error(`Workflow name is required for "${action}".`);
     if (action === "explain") {
-      Logger24.rawLog(this.workflowRunner.explain(workflow2, { format }));
+      Logger25.rawLog(this.workflowRunner.explain(workflow2, { format }));
       return;
     }
     if (action === "plan") {
-      Logger24.rawLog(await this.workflowRunner.plan(workflow2, inputs, { format, out }));
+      Logger25.rawLog(await this.workflowRunner.plan(workflow2, inputs, { format, out }));
       return;
     }
     if (action === "apply") {
       if (!workspace)
         throw new Error("Workspace is required for workflow apply.");
-      Logger24.rawLog(await this.workflowRunner.apply(workflow2, {
+      Logger25.rawLog(await this.workflowRunner.apply(workflow2, {
         dryRun,
         format,
         workspace,
@@ -20160,13 +20998,13 @@ class WorkflowScript extends script("workflow", [WorkflowRunner, ModuleScript, S
     if (action === "validate") {
       if (!workspace)
         throw new Error("Workspace is required for workflow validate.");
-      Logger24.rawLog(await this.workflowRunner.validate(workflow2, { format, workspace }));
+      Logger25.rawLog(await this.workflowRunner.validate(workflow2, { format, workspace }));
       return;
     }
     if (action === "report") {
       if (!workspace)
         throw new Error("Workspace is required for workflow report.");
-      Logger24.rawLog(await this.workflowRunner.report(workflow2, { format, workspace }));
+      Logger25.rawLog(await this.workflowRunner.report(workflow2, { format, workspace }));
       return;
     }
     throw new Error(`Unknown workflow action: ${action}. Use list, explain, plan, apply, validate, or report.`);
@@ -20190,11 +21028,11 @@ class WorkflowCommand extends command("workflow", [WorkflowScript], ({ public: t
 }
 
 // pkgs/@akanjs/cli/workspace/workspace.script.ts
-import path47 from "path";
-import { Logger as Logger25 } from "akanjs/common";
+import path49 from "path";
+import { Logger as Logger26 } from "akanjs/common";
 
 // pkgs/@akanjs/cli/workspace/workspace.runner.ts
-import path46 from "path";
+import path48 from "path";
 var defaultWorkspacePeerDependencies = new Set([
   "@react-spring/web",
   "@use-gesture/react",
@@ -20225,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 [
@@ -20245,7 +21089,7 @@ class WorkspaceRunner extends runner("workspace") {
     owner = ""
   }) {
     const cwdPath = process.cwd();
-    const workspaceRoot = path46.join(cwdPath, dirname2, repoName);
+    const workspaceRoot = path48.join(cwdPath, dirname2, repoName);
     const normalizedRegistryUrl = registryUrl ? getNpmRegistryUrl(registryUrl) : undefined;
     const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot, repoName });
     const templateSpinner = workspace.spinning(`Creating workspace template files in ${dirname2}/${repoName}...`);
@@ -20301,9 +21145,9 @@ class WorkspaceRunner extends runner("workspace") {
   }
   async#getCliPackageJson() {
     const packageJsonCandidates = [
-      path46.join(import.meta.dir, "../package.json"),
-      path46.join(import.meta.dir, "package.json"),
-      path46.join(path46.dirname(Bun.main), "package.json")
+      path48.join(import.meta.dir, "../package.json"),
+      path48.join(import.meta.dir, "package.json"),
+      path48.join(path48.dirname(Bun.main), "package.json")
     ];
     try {
       packageJsonCandidates.unshift(Bun.resolveSync("@akanjs/cli/package.json", import.meta.dir));
@@ -20319,9 +21163,9 @@ class WorkspaceRunner extends runner("workspace") {
   }
   async#getAkanPackageJson() {
     const packageJsonCandidates = [
-      path46.join(import.meta.dir, "../../../akanjs/package.json"),
-      path46.join(process.cwd(), "pkgs/akanjs/package.json"),
-      path46.join(path46.dirname(Bun.main), "node_modules/akanjs/package.json")
+      path48.join(import.meta.dir, "../../../akanjs/package.json"),
+      path48.join(process.cwd(), "pkgs/akanjs/package.json"),
+      path48.join(path48.dirname(Bun.main), "node_modules/akanjs/package.json")
     ];
     try {
       packageJsonCandidates.unshift(Bun.resolveSync("akanjs/package.json", import.meta.dir));
@@ -20335,13 +21179,13 @@ class WorkspaceRunner extends runner("workspace") {
     }
     let current = import.meta.dir;
     for (let depth = 0;depth < 6; depth++) {
-      const packageJsonPath = path46.join(current, "package.json");
+      const packageJsonPath = path48.join(current, "package.json");
       if (await Bun.file(packageJsonPath).exists()) {
         const packageJson = await FileSys.readJson(packageJsonPath);
         if (packageJson.name === "akanjs")
           return packageJson;
       }
-      const parent = path46.dirname(current);
+      const parent = path48.dirname(current);
       if (parent === current)
         break;
       current = parent;
@@ -20418,11 +21262,11 @@ class WorkspaceScript extends script("workspace", [
     } catch (_) {
       gitSpinner.fail("Git repository initialization failed. It's not fatal, you can commit manually");
     }
-    const workspacePath2 = path47.join(dirname2, repoName);
-    Logger25.rawLog(`
+    const workspacePath2 = path49.join(dirname2, repoName);
+    Logger26.rawLog(`
 \uD83C\uDF89 Welcome aboard! Workspace created in ${dirname2}/${repoName}`);
-    Logger25.rawLog(`\uD83D\uDE80 Run \`cd ${workspacePath2} && akan start ${appName}\` to start the development server.`);
-    Logger25.rawLog(`
+    Logger26.rawLog(`\uD83D\uDE80 Run \`cd ${workspacePath2} && akan start ${appName}\` to start the development server.`);
+    Logger26.rawLog(`
 \uD83D\uDC4B Happy coding!`);
   }
   async generateAgentRules(workspace, { overwrite = false, cursorRules = true } = {}) {
@@ -20519,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) {
@@ -20538,4 +21384,4 @@ class WorkspaceCommand extends command("workspace", [WorkspaceScript], ({ public
 }
 
 // pkgs/@akanjs/cli/index.ts
-runCommands(WorkspaceCommand, AgentCommand, ApplicationCommand, LibraryCommand, LocalRegistryCommand, PackageCommand, ModuleCommand, PageCommand, ContextCommand, CloudCommand, GuidelineCommand, ScalarCommand, PrimitiveCommand, RepairCommand, WorkflowCommand);
+runCommands(WorkspaceCommand, AgentCommand, ApplicationCommand, LibraryCommand, LocalRegistryCommand, PackageCommand, ModuleCommand, PageCommand, ContextCommand, CloudCommand, GuidelineCommand, ScalarCommand, PrimitiveCommand, QualityCommand, RepairCommand, WorkflowCommand);