@akanjs/cli 3.0.0-alpha.3 → 3.0.0-alpha.5

package/{index-nm6wghb6.js → index-mn96y1nk.js}

@@ -1,10 +1,10 @@
 // @bun
 import {
   CloudRunner
-} from "./index-zasydjxd.js";
+} from "./index-p6txr1ss.js";
 import {
   PackageScript
-} from "./index-k95xkh4p.js";
+} from "./index-meh7mmz9.js";
 import {
   AiSession,
   CloudApi,
@@ -12,13 +12,13 @@ import {
 } from "./index-0cj2zxbm.js";
 import {
   ApplicationScript
-} from "./index-e16gnn26.js";
+} from "./index-nx1vbtsc.js";
 import {
   script
-} from "./index-8hsbnyes.js";
+} from "./index-jkynkyfk.js";
 import {
   PkgExecutor
-} from "./index-hgna5rjy.js";
+} from "./index-47qxw1tz.js";
 
 // pkgs/@akanjs/cli/cloud/cloud.script.ts
 import { Logger } from "akanjs/common";

package/{index-t3723f99.js → index-mterpj70.js}

@@ -5,7 +5,7 @@ import {
 } from "./index-76rn3g2c.js";
 import {
   CommandExecutionError
-} from "./index-hgna5rjy.js";
+} from "./index-47qxw1tz.js";
 
 // pkgs/@akanjs/devkit/capacitorApp.ts
 import { cp, mkdir, readFile, rm, writeFile } from "fs/promises";

package/{index-ej426mcr.js → index-nfxq39kj.js}

@@ -1,14 +1,14 @@
 // @bun
 import {
   AkanContextAnalyzer
-} from "./index-a00jg8x8.js";
+} from "./index-jn9vfpwz.js";
 import {
   Prompter
-} from "./index-tdbas9r0.js";
+} from "./index-qp089jp0.js";
 import {
   runner,
   script
-} from "./index-8hsbnyes.js";
+} from "./index-jkynkyfk.js";
 import {
   AGENT_BLOCK_END,
   AGENT_BLOCK_START,
@@ -16,7 +16,7 @@ import {
   LibExecutor,
   renderRecipeEntries,
   upsertAgentBlock
-} from "./index-hgna5rjy.js";
+} from "./index-47qxw1tz.js";
 import {
   collectRecipeSources,
   scanRecipes

package/{index-e16gnn26.js → index-nx1vbtsc.js}

@@ -4,11 +4,11 @@ import {
 } from "./index-76rn3g2c.js";
 import {
   LibraryScript
-} from "./index-7c6k4yvg.js";
+} from "./index-exhpp31y.js";
 import {
   runner,
   script
-} from "./index-8hsbnyes.js";
+} from "./index-jkynkyfk.js";
 import {
   HmrWatcher,
   WatchRootResolver
@@ -18,7 +18,7 @@ import {
   LibExecutor,
   PkgExecutor,
   WorkspaceExecutor
-} from "./index-hgna5rjy.js";
+} from "./index-47qxw1tz.js";
 import {
   __require
 } from "./index-r24hmh0q.js";
@@ -1898,9 +1898,9 @@ function openBrowser(url) {
 }
 
 // pkgs/@akanjs/cli/application/application.runner.ts
-var loadBuildRunner = async () => (await import("./applicationBuildRunner-ct2pxyvw.js")).ApplicationBuildRunner;
+var loadBuildRunner = async () => (await import("./applicationBuildRunner-n1svrwgt.js")).ApplicationBuildRunner;
 var loadReleasePackager = async () => (await import("./applicationReleasePackager-gg8ccbeh.js")).ApplicationReleasePackager;
-var loadCapacitorApp = async () => (await import("./capacitorApp-4r9sm3qg.js")).CapacitorApp;
+var loadCapacitorApp = async () => (await import("./capacitorApp-yyw35vg4.js")).CapacitorApp;
 var loadAbstractCompactor = async () => (await import("./abstractCompactor-e5yq60qz.js")).AbstractCompactor;
 var loadPrompts = async () => await import("@inquirer/prompts");
 

package/{index-1pvex4az.js → index-p69fcwe1.js}

@@ -1,22 +1,22 @@
 // @bun
 import {
   RepairRunner
-} from "./index-mr5s7mqd.js";
+} from "./index-6npsfpxr.js";
 import {
   WorkflowRunner
-} from "./index-2q1f5j9k.js";
+} from "./index-c94nq3c1.js";
 import {
   PrimitiveScript
-} from "./index-bekddz9q.js";
+} from "./index-pfrt7qwh.js";
 import {
   ModuleScript
-} from "./index-yzmhasdb.js";
+} from "./index-60a3jfcz.js";
 import {
   ScalarScript
-} from "./index-ec09pws3.js";
+} from "./index-wrrb8rxk.js";
 import {
   isPlaceholderAppId
-} from "./index-t3723f99.js";
+} from "./index-mterpj70.js";
 import {
   AkanContextAnalyzer,
   akanMcpInstallConfigPaths,
@@ -27,17 +27,17 @@ import {
   renderDoctorText,
   resourceList,
   upsertCodexMcpServerBlock
-} from "./index-a00jg8x8.js";
+} from "./index-jn9vfpwz.js";
 import {
   buildAkanModuleContextIndex,
   createWorkflowBaselineSummary,
   createWorkflowStepRegistry,
   jsonText,
   toolingRolloutGate
-} from "./index-rzwcpcc3.js";
+} from "./index-m4kpmmtj.js";
 import {
   Prompter
-} from "./index-tdbas9r0.js";
+} from "./index-qp089jp0.js";
 import {
   getMobileTargets
 } from "./index-76rn3g2c.js";
@@ -45,10 +45,10 @@ import {
   CommandContainer,
   runner,
   script
-} from "./index-8hsbnyes.js";
+} from "./index-jkynkyfk.js";
 import {
   AppExecutor
-} from "./index-hgna5rjy.js";
+} from "./index-47qxw1tz.js";
 
 // pkgs/@akanjs/cli/context/context.script.ts
 import { Logger } from "akanjs/common";

package/{index-zasydjxd.js → index-p6txr1ss.js}

@@ -7,14 +7,14 @@ import {
 } from "./index-0cj2zxbm.js";
 import {
   openBrowser
-} from "./index-e16gnn26.js";
+} from "./index-nx1vbtsc.js";
 import {
   runner
-} from "./index-8hsbnyes.js";
+} from "./index-jkynkyfk.js";
 import {
   AppExecutor,
   WorkspaceExecutor
-} from "./index-hgna5rjy.js";
+} from "./index-47qxw1tz.js";
 
 // pkgs/@akanjs/cli/cloud/cloud.runner.ts
 import path from "path";

package/{index-bekddz9q.js → index-pfrt7qwh.js}

@@ -1,7 +1,7 @@
 // @bun
 import {
   ModuleScript
-} from "./index-yzmhasdb.js";
+} from "./index-60a3jfcz.js";
 import {
   addFieldUiPolicyForType,
   coerceFieldDefault,
@@ -34,15 +34,15 @@ import {
   sourceFile,
   validationCommandsForTarget,
   viaBuilderParameterName
-} from "./index-rzwcpcc3.js";
+} from "./index-m4kpmmtj.js";
 import {
   script
-} from "./index-8hsbnyes.js";
+} from "./index-jkynkyfk.js";
 import {
   AppExecutor,
   LibExecutor,
   ModuleExecutor
-} from "./index-hgna5rjy.js";
+} from "./index-47qxw1tz.js";
 
 // pkgs/@akanjs/cli/primitive/primitive.script.ts
 import { capitalize } from "akanjs/common";

package/{index-tdbas9r0.js → index-qp089jp0.js}

@@ -1,7 +1,7 @@
 // @bun
 import {
   getDirname
-} from "./index-hgna5rjy.js";
+} from "./index-47qxw1tz.js";
 
 // pkgs/@akanjs/devkit/prompter.ts
 import fsPromise from "fs/promises";

package/{index-ec09pws3.js → index-wrrb8rxk.js}

@@ -9,14 +9,14 @@ import {
   createPassedPrimitiveReport,
   generatedFilesForSync,
   scalarChangedFiles
-} from "./index-rzwcpcc3.js";
+} from "./index-m4kpmmtj.js";
 import {
   Prompter
-} from "./index-tdbas9r0.js";
+} from "./index-qp089jp0.js";
 import {
   runner,
   script
-} from "./index-8hsbnyes.js";
+} from "./index-jkynkyfk.js";
 
 // pkgs/@akanjs/cli/scalar/scalar.prompt.ts
 import { input } from "@inquirer/prompts";

package/index.js

@@ -4,8 +4,8 @@ import {
   getTargetCommandNames,
   getTargetMetas,
   runCommands
-} from "./index-8hsbnyes.js";
-import"./index-hgna5rjy.js";
+} from "./index-jkynkyfk.js";
+import"./index-47qxw1tz.js";
 import"./index-mxvakhsm.js";
 import"./index-67546d0j.js";
 import {
@@ -17,22 +17,22 @@ import path from "path";
 
 // pkgs/@akanjs/cli/commandModules.ts
 var commandModules = {
-  workspace: async () => (await import("./workspace.command-fpda0evj.js")).WorkspaceCommand,
-  agent: async () => (await import("./agent.command-yv00p0s0.js")).AgentCommand,
-  application: async () => (await import("./application.command-0qsczf4k.js")).ApplicationCommand,
-  library: async () => (await import("./library.command-ebdj1vnm.js")).LibraryCommand,
-  localRegistry: async () => (await import("./localRegistry.command-gb178ne8.js")).LocalRegistryCommand,
-  package: async () => (await import("./package.command-t93p4jkj.js")).PackageCommand,
-  module: async () => (await import("./module.command-9c1bnsx4.js")).ModuleCommand,
-  page: async () => (await import("./page.command-k3k0meh2.js")).PageCommand,
-  context: async () => (await import("./context.command-8d9e3k6b.js")).ContextCommand,
-  cloud: async () => (await import("./cloud.command-dxfv18sa.js")).CloudCommand,
-  guideline: async () => (await import("./guideline.command-3jbkxzh6.js")).GuidelineCommand,
-  scalar: async () => (await import("./scalar.command-7a2jtv33.js")).ScalarCommand,
-  primitive: async () => (await import("./primitive.command-de6nktdt.js")).PrimitiveCommand,
-  quality: async () => (await import("./quality.command-z5kth2wa.js")).QualityCommand,
-  repair: async () => (await import("./repair.command-ehf2g112.js")).RepairCommand,
-  workflow: async () => (await import("./workflow.command-e0tt0vk2.js")).WorkflowCommand
+  workspace: async () => (await import("./workspace.command-3q1d6kk4.js")).WorkspaceCommand,
+  agent: async () => (await import("./agent.command-b0fcx3r2.js")).AgentCommand,
+  application: async () => (await import("./application.command-cgmy00gd.js")).ApplicationCommand,
+  library: async () => (await import("./library.command-aa1g8nsa.js")).LibraryCommand,
+  localRegistry: async () => (await import("./localRegistry.command-kshva1ck.js")).LocalRegistryCommand,
+  package: async () => (await import("./package.command-9qv6vr9s.js")).PackageCommand,
+  module: async () => (await import("./module.command-b1zzgqde.js")).ModuleCommand,
+  page: async () => (await import("./page.command-k16pw244.js")).PageCommand,
+  context: async () => (await import("./context.command-b5heat2a.js")).ContextCommand,
+  cloud: async () => (await import("./cloud.command-1m7hfdpk.js")).CloudCommand,
+  guideline: async () => (await import("./guideline.command-9ew6aqhm.js")).GuidelineCommand,
+  scalar: async () => (await import("./scalar.command-hs3nwzv1.js")).ScalarCommand,
+  primitive: async () => (await import("./primitive.command-s60dn1ae.js")).PrimitiveCommand,
+  quality: async () => (await import("./quality.command-p3vaze52.js")).QualityCommand,
+  repair: async () => (await import("./repair.command-mfv749ha.js")).RepairCommand,
+  workflow: async () => (await import("./workflow.command-z0e0fk0z.js")).WorkflowCommand
 };
 var commandModuleIds = Object.keys(commandModules);
 

package/{library.command-ebdj1vnm.js → library.command-aa1g8nsa.js}

@@ -1,13 +1,13 @@
 // @bun
 import {
   LibraryScript
-} from "./index-7c6k4yvg.js";
+} from "./index-exhpp31y.js";
 import {
   Lib,
   Workspace,
   command
-} from "./index-8hsbnyes.js";
-import"./index-hgna5rjy.js";
+} from "./index-jkynkyfk.js";
+import"./index-47qxw1tz.js";
 import"./index-mxvakhsm.js";
 import"./index-67546d0j.js";
 import"./index-r24hmh0q.js";

package/{localRegistry.command-gb178ne8.js → localRegistry.command-kshva1ck.js}

@@ -2,27 +2,27 @@
 import {
   CloudRunner,
   getNpmRegistryUrl
-} from "./index-zasydjxd.js";
+} from "./index-p6txr1ss.js";
 import {
   PackageScript
-} from "./index-k95xkh4p.js";
+} from "./index-meh7mmz9.js";
 import"./index-0cj2zxbm.js";
 import {
   ApplicationScript
-} from "./index-e16gnn26.js";
+} from "./index-nx1vbtsc.js";
 import"./index-76rn3g2c.js";
-import"./index-7c6k4yvg.js";
+import"./index-exhpp31y.js";
 import {
   Workspace,
   command,
   runner,
   script
-} from "./index-8hsbnyes.js";
+} from "./index-jkynkyfk.js";
 import"./index-fgc8r6dj.js";
 import"./index-bjpxzr6s.js";
 import {
   PkgExecutor
-} from "./index-hgna5rjy.js";
+} from "./index-47qxw1tz.js";
 import"./index-mxvakhsm.js";
 import"./index-46tjzh6s.js";
 import"./index-67546d0j.js";

package/{module.command-9c1bnsx4.js → module.command-b1zzgqde.js}

@@ -1,20 +1,20 @@
 // @bun
 import {
   ModuleScript
-} from "./index-yzmhasdb.js";
-import"./index-bbkek1bp.js";
+} from "./index-60a3jfcz.js";
+import"./index-hrwzz2wf.js";
 import"./index-ss469dec.js";
 import"./index-0cj2zxbm.js";
 import {
   renderPrimitiveReport
-} from "./index-rzwcpcc3.js";
-import"./index-tdbas9r0.js";
+} from "./index-m4kpmmtj.js";
+import"./index-qp089jp0.js";
 import {
   Module,
   Sys,
   command
-} from "./index-8hsbnyes.js";
-import"./index-hgna5rjy.js";
+} from "./index-jkynkyfk.js";
+import"./index-47qxw1tz.js";
 import"./index-mxvakhsm.js";
 import"./index-67546d0j.js";
 import"./index-r24hmh0q.js";

package/{package.command-t93p4jkj.js → package.command-9qv6vr9s.js}

@@ -1,13 +1,13 @@
 // @bun
 import {
   PackageScript
-} from "./index-k95xkh4p.js";
+} from "./index-meh7mmz9.js";
 import {
   Pkg,
   Workspace,
   command
-} from "./index-8hsbnyes.js";
-import"./index-hgna5rjy.js";
+} from "./index-jkynkyfk.js";
+import"./index-47qxw1tz.js";
 import"./index-mxvakhsm.js";
 import"./index-46tjzh6s.js";
 import"./index-67546d0j.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "3.0.0-alpha.3",
+  "version": "3.0.0-alpha.5",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -34,7 +34,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.3",
+    "akanjs": "3.0.0-alpha.5",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/{page.command-k3k0meh2.js → page.command-k16pw244.js}

@@ -1,13 +1,13 @@
 // @bun
 import {
   PageScript
-} from "./index-bbkek1bp.js";
+} from "./index-hrwzz2wf.js";
 import {
   App,
   Module,
   command
-} from "./index-8hsbnyes.js";
-import"./index-hgna5rjy.js";
+} from "./index-jkynkyfk.js";
+import"./index-47qxw1tz.js";
 import"./index-mxvakhsm.js";
 import"./index-67546d0j.js";
 import"./index-r24hmh0q.js";

package/{primitive.command-de6nktdt.js → primitive.command-s60dn1ae.js}

@@ -1,20 +1,20 @@
 // @bun
 import {
   PrimitiveScript
-} from "./index-bekddz9q.js";
-import"./index-yzmhasdb.js";
-import"./index-bbkek1bp.js";
+} from "./index-pfrt7qwh.js";
+import"./index-60a3jfcz.js";
+import"./index-hrwzz2wf.js";
 import"./index-ss469dec.js";
 import"./index-0cj2zxbm.js";
 import {
   renderPrimitiveReport
-} from "./index-rzwcpcc3.js";
-import"./index-tdbas9r0.js";
+} from "./index-m4kpmmtj.js";
+import"./index-qp089jp0.js";
 import {
   Workspace,
   command
-} from "./index-8hsbnyes.js";
-import"./index-hgna5rjy.js";
+} from "./index-jkynkyfk.js";
+import"./index-47qxw1tz.js";
 import"./index-mxvakhsm.js";
 import"./index-67546d0j.js";
 import"./index-r24hmh0q.js";

package/{quality.command-z5kth2wa.js → quality.command-p3vaze52.js}

@@ -7,8 +7,11 @@ import {
   command,
   runner,
   script
-} from "./index-8hsbnyes.js";
-import"./index-hgna5rjy.js";
+} from "./index-jkynkyfk.js";
+import {
+  appRootAllowedFiles,
+  libFacetRootAllowedFiles
+} from "./index-47qxw1tz.js";
 import"./index-mxvakhsm.js";
 import"./index-67546d0j.js";
 import"./index-r24hmh0q.js";
@@ -404,27 +407,6 @@ var SUGGESTED_RULES = [
   "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",
@@ -703,7 +685,7 @@ class AkanQualityScanner {
   #scanLayoutQuality(sourceFile) {
     const segments = sourceFile.file.split("/");
     const warnings = [];
-    if (segments[0] === "apps" && segments.length === 3 && !APP_ROOT_FILES.has(segments[2])) {
+    if (segments[0] === "apps" && segments.length === 3 && !appRootAllowedFiles.has(segments[2])) {
       warnings.push({
         rule: "akan.layout.app-root-file",
         scope: "layout",
@@ -713,7 +695,7 @@ class AkanQualityScanner {
       });
     }
     const libRootFile = getLibRootFile(sourceFile.file);
-    if (libRootFile && !LIB_ROOT_FILES.has(libRootFile)) {
+    if (libRootFile && !libFacetRootAllowedFiles.has(libRootFile)) {
       warnings.push({
         rule: "akan.layout.lib-root-file",
         scope: "layout",

package/{repair.command-ehf2g112.js → repair.command-mfv749ha.js}

@@ -1,15 +1,15 @@
 // @bun
 import {
   RepairRunner
-} from "./index-mr5s7mqd.js";
-import"./index-a00jg8x8.js";
-import"./index-rzwcpcc3.js";
+} from "./index-6npsfpxr.js";
+import"./index-jn9vfpwz.js";
+import"./index-m4kpmmtj.js";
 import {
   Workspace,
   command,
   script
-} from "./index-8hsbnyes.js";
-import"./index-hgna5rjy.js";
+} from "./index-jkynkyfk.js";
+import"./index-47qxw1tz.js";
 import"./index-mxvakhsm.js";
 import"./index-xys926f2.js";
 import"./index-67546d0j.js";

package/{scalar.command-7a2jtv33.js → scalar.command-hs3nwzv1.js}

@@ -1,18 +1,18 @@
 // @bun
 import {
   ScalarScript
-} from "./index-ec09pws3.js";
+} from "./index-wrrb8rxk.js";
 import"./index-ss469dec.js";
 import"./index-0cj2zxbm.js";
 import {
   renderPrimitiveReport
-} from "./index-rzwcpcc3.js";
-import"./index-tdbas9r0.js";
+} from "./index-m4kpmmtj.js";
+import"./index-qp089jp0.js";
 import {
   Sys,
   command
-} from "./index-8hsbnyes.js";
-import"./index-hgna5rjy.js";
+} from "./index-jkynkyfk.js";
+import"./index-47qxw1tz.js";
 import"./index-mxvakhsm.js";
 import"./index-67546d0j.js";
 import"./index-r24hmh0q.js";

package/templates/lib/useClient.ts

@@ -1,16 +1,22 @@
 import type { AppInfo, LibInfo } from "akanjs";
 
 export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { [key: string]: string } = {}) {
+  const isApp = (scanInfo?.type ?? "lib") === "app";
   return `
 import { makePageProto, registerClientRuntime } from "akanjs/client";
 import { FetchClient } from "akanjs/fetch";
 import * as cnst from "./cnst";
-import { getAllDictionary } from "./dict" with { type: "macro" };
-import type * as dict from "./dict";
+${isApp ? `import { getAllDictionary } from "./dict" with { type: "macro" };\n` : ""}import type * as dict from "./dict";
 import { getSerializedSignal } from "./sig" with { type: "macro" };
 import type * as signal from "./sig";
 
-const dictionary = process.env.AKAN_PUBLIC_RENDER_ENV === "csr" ? getAllDictionary() : {};
+${
+  isApp
+    ? `const dictionary = process.env.AKAN_PUBLIC_RENDER_ENV === "csr" ? getAllDictionary() : {};`
+    : `// dict.ts is cumulative, so a lib dictionary is a subset of the mounting app's. Translator state is global,
+// so the app's seed already resolves l() here — seeding again would ship the same payload a second time.
+const dictionary = {};`
+}
 const pageProto = makePageProto<typeof dict>(dictionary);
 const fetchProto = FetchClient.build<typeof signal>(cnst, getSerializedSignal(), { Err: pageProto.Err });
 export const runtime = registerClientRuntime({ ...pageProto, ...fetchProto }, { scope: ${JSON.stringify(scanInfo?.type ?? "lib")} });

package/templates/workspaceRoot/.cursor/rules/akan-sync-conventions.mdc.template

@@ -6,8 +6,9 @@ alwaysApply: false
 
 # Akan Sync Conventions
 
-- `apps/<appName>` root may only contain these files: `akan.app.json`, `akan.config.ts`, `capacitor.config.ts`, `client.ts`, `main.ts`, `package.json`, `server.ts`, `tsconfig.json`.
-- `apps/<appName>` root may only contain these folders: `.akan`, `android`, `common`, `env`, `ios`, `lib`, `page`, `private`, `public`, `script`, `srvkit`, `ui`, `webkit`.
+- `apps/<appName>` root may only contain these files: `AGENTS.md`, `CLAUDE.md`, `akan.app.json`, `akan.config.ts`, `capacitor.config.ts`, `client.ts`, `main.ts`, `package.json`, `server.ts`, `tsconfig.json`.
+- `apps/<appName>` root may only contain these folders: `.akan`, `android`, `common`, `env`, `ios`, `lib`, `mobile`, `page`, `plugin`, `private`, `public`, `script`, `secrets`, `srvkit`, `ui`, `webkit`.
+- `akan sync` maintains a scoped agent guide per app/lib (`apps/<app>/AGENTS.md` / `libs/<lib>/AGENTS.md`); the `akan:agent` block in it is generated, content outside the markers is hand-editable, and `akan lint` fails when the block is stale.
 - Do not add `apps/*/base`; place shared app utilities under `apps/*/common`.
 - `apps/*/lib` and `libs/*/lib` root files are limited to generated/support files: `cnst.ts`, `db.ts`, `dict.ts`, `option.ts`, `sig.ts`, `srv.ts`, `st.ts`, `useClient.ts`, `useServer.ts`.
 - Domain module folders are `lib/<model>` for database modules, `lib/_<service>` for service modules, and `lib/__scalar/<scalar>` for scalar modules.

package/templates/workspaceRoot/AGENTS.md.template

@@ -260,6 +260,7 @@ final fallback when no CLI command covers the change.
 | Create a file without running sync | New files won't appear in barrel exports. Imports like `import * as cnst from "../cnst"` will fail. | Always run `akan sync <name>` after creating, renaming, or deleting any module file |
 | Use JS `#private` in `*.constant.ts`, `*.document.ts`, `*.service.ts`, or `*.store.ts` | `no-js-private-class-method.grit` bans `#private` in exactly those four file suffixes. The rule is scoped by file path, not class shape — `#private` stays the house style under `srvkit/`, including `adapt()` classes. | `private _methodName()` in those four files; `#methodName()` in `srvkit/` |
 | Use `console.log()` | Biome lint forbids `console.log`. Only `console.error`, `console.info`, `console.warn` are allowed. | Use one of the three allowed console methods, or `this.logger.*` / `new Logger("ClassName")` on the server |
+| Write a `//!` marker in `ui/`, `webkit/`, `common/`, `page/**/*.tsx`, `*.constant.ts`, `*.store.ts`, or a module component file | `no-bang-comment-in-client.grit` bans it. Bun classifies `//!` and `/*!` as legal comments and keeps them through minification, so the note ships to every visitor. | `// FIXME:` in browser-reachable code; `//!` stays legal in server, `srvkit/`, and CLI files |
 | `throw new Error("...")` | `no-throw-raw-error.grit` bans raw errors outside tests, `*.constant.ts`, and `common/`. Raw errors carry no dictionary key, so they cannot be localized or toasted. | `throw new Err("task.error.<key>")` plus an `[en, ko]` entry in the module dictionary's `.error({})` |
 | Hand-order Tailwind classes, or reorder them to "fix" a diff | `useSortedClasses` is an error and also sorts the string arguments to `clsx()` and `cva()`. Sorter output like `font-bold text-2xl` looks wrong but is correct. | Write classes in any order and let `akan lint` sort them |
 | `import` a third-party package inside a page, a barrel, or a module file | `no-import-external-library.grit` covers `page/**`, all barrels, and every `*.{constant,dictionary,document,service,signal,store}.ts` and `*.{Template,Unit,Util,View,Zone}.tsx`. | Re-export the symbol from a one-line shim in `base/`, `webkit/`, or `ui/` first, then import that |
@@ -484,6 +485,9 @@ Do not narrate code. Do document the thing the code cannot say. Both halves are
 - Markers: `TODO` unfinished work · `FIXME` known broken behavior · `XXX` hazard a reader must not miss · `//!`
   disabled or must-fix code · `//?` an explanatory aside · `//*` a design note · deletion caution, warning why
   removing a line would break something non-obvious.
+- `//!` is for server, `srvkit/`, and CLI files only. Bun's bundler treats `//!` and `/*!` as legal comments and
+  keeps them through minification, so in browser-reachable code the note ships verbatim to every visitor. Use
+  `// FIXME:` there — `no-bang-comment-in-client.grit` enforces it.
 - Keep allowed comments to one short line, and give every suppression a reason:
   `// biome-ignore lint/<rule>: <why>`. Never a bare disable block.
 - Match nearby file style: if the surrounding code has few comments, keep it that way.