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

package/templates/workspaceRoot/CLAUDE.md.template

@@ -1,3 +1,22 @@
 # <%= repoName %> — Claude Code Guide
 
 @AGENTS.md
+
+## Comments — Overrides Your Default
+
+Write **no comments** unless the comment passes the test below. This is the rule agents break most often here, so it
+is repeated outside the guide: a diff that adds a comment the test rejects is a diff to redo.
+
+Before typing `//`, `/*`, or a doc block, ask — **does this sentence carry a fact that is nowhere in the code?**
+
+- Restates the identifier, the signature, or the line under it → delete it.
+- Labels a section (`// helpers`, `// state`) or narrates a step (`// fetch the user`, `// then save`) → delete it.
+- JSDoc on an ordinary function, or a why/how preamble on ordinary logic → delete it.
+- Explains the edit you just made, for whoever reads the diff → say it in your reply, not in the file.
+- Names a vendor or protocol quirk, an infrastructure constraint, a library gotcha, security reasoning, a math
+  derivation, a domain field's business meaning, a state transition, or why an obvious alternative was rejected →
+  keep it, one line.
+
+That keep-list is exact — `Comments` in the guide is the full version. "It aids readability" and "this logic is
+subtle" are not on it: rename or split the code instead. When you edit an existing file, match its density; if the
+surrounding code carries none, your diff carries none.

package/templates/workspaceRoot/biome.json.template

@@ -1,215 +1,21 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.5.2/schema.json",
-  "vcs": {
-    "enabled": true,
-    "clientKind": "git",
-    "useIgnoreFile": false
-  },
+  "$schema": "https://biomejs.dev/schemas/2.5.8/schema.json",
+  "extends": ["@akanjs/devkit/biome.base.json"],
   "files": {
     "includes": [
       "**/*.ts",
       "**/*.tsx",
       "**/*.json",
       "**/*.jsonc",
-      "!**/env.client.local.ts",
-      "!**/env.client.debug.ts",
-      "!**/env.client.develop.ts",
-      "!**/env.client.main.ts",
-      "!**/env.client.testing.ts",
-      "!**/env.server.local.ts",
-      "!**/env.server.develop.ts",
-      "!**/env.server.main.ts",
-      "!**/env.server.testing.ts",
-      "!**/env.server.type.ts",
-      "!apps/*/lib/cnst.ts",
-      "!apps/*/lib/dict.ts",
-      "!apps/*/lib/db.ts",
-      "!apps/*/lib/srv.ts",
-      "!apps/*/lib/st.ts",
-      "!apps/*/lib/sig.ts",
-      "!apps/*/lib/useClient.ts",
-      "!apps/*/lib/useServer.ts",
-      "!apps/*/client.ts",
-      "!apps/*/server.ts",
-      "!apps/*/lib/*/index.tsx",
-      "!libs/*/lib/cnst.ts",
-      "!libs/*/lib/dict.ts",
-      "!libs/*/lib/db.ts",
-      "!libs/*/lib/srv.ts",
-      "!libs/*/lib/st.ts",
-      "!libs/*/lib/sig.ts",
-      "!libs/*/lib/useClient.ts",
-      "!libs/*/lib/useServer.ts",
-      "!libs/*/client.ts",
-      "!libs/*/server.ts",
-      "!libs/*/index.ts",
-      "!libs/*/lib/*/index.tsx",
       "!infra/master/createRecords.ts",
       "!pkgs/contract/env.ts",
       "!!**/node_modules",
       "!!**/dist",
       "!!**/.akan",
+      "!!**/.claude",
       "!!**/dump",
       "!!**/local",
       "!!**/ios/DerivedData"
     ]
-  },
-  "formatter": {
-    "enabled": true,
-    "indentStyle": "space",
-    "indentWidth": 2,
-    "lineWidth": 120
-  },
-  "linter": {
-    "enabled": true,
-    "rules": {
-      "preset": "recommended",
-      "suspicious": {
-        "noConsole": {
-          "level": "error",
-          "options": {
-            "allow": ["assert", "error", "info", "warn"]
-          }
-        },
-        "noArrayIndexKey": "off",
-        "noShadowRestrictedNames": "off",
-        "noUnnecessaryConditions": {
-          "level": "error"
-        }
-      },
-      "correctness": {
-        "noUnusedFunctionParameters": "off",
-        "noUnusedImports": {
-          "level": "error",
-          "fix": "safe"
-        },
-        "useParseIntRadix": "off",
-        "useExhaustiveDependencies": "off",
-        "useHookAtTopLevel": "off"
-      },
-      "nursery": {
-        "useSortedClasses": {
-          "level": "error",
-          "fix": "safe",
-          "options": {
-            "attributes": ["classList"],
-            "functions": ["clsx", "cn"]
-          }
-        }
-      },
-      "a11y": "off",
-      "complexity": {
-        "noStaticOnlyClass": "off"
-      },
-      "style": {
-        "useTemplate": {
-          "level": "warn",
-          "fix": "safe"
-        }
-      }
-    },
-    "domains": {
-      "project": "recommended",
-      "react": "recommended",
-      "test": "recommended",
-      "types": "all"
-    }
-  },
-  "javascript": {
-    "parser": {
-      "unsafeParameterDecoratorsEnabled": true
-    },
-    "formatter": {
-      "quoteStyle": "double"
-    }
-  },
-  "assist": {
-    "enabled": true,
-    "actions": {
-      "source": {
-        "organizeImports": "on"
-      }
-    }
-  },
-  "overrides": [
-    {
-      "includes": [
-        "apps/**/*.ts",
-        "apps/**/*.tsx",
-        "libs/**/*.ts",
-        "libs/**/*.tsx",
-        "!**/*.test.ts",
-        "!**/*.test.tsx",
-        "!**/*.spec.ts",
-        "!**/*.spec.tsx",
-        "!**/*.constant.ts",
-        "!**/common/**"
-      ],
-      "plugins": ["./node_modules/@akanjs/devkit/lint/no-throw-raw-error.grit"]
-    },
-    {
-      "includes": ["**/page/**/*.ts", "**/page/**/*.tsx", "**/*.Unit.tsx", "**/*.View.tsx"],
-      "plugins": [
-        "./node_modules/@akanjs/devkit/lint/no-import-client-functions.grit",
-        "./node_modules/@akanjs/devkit/lint/no-use-client-in-server.grit"
-      ]
-    },
-    {
-      "includes": ["**/page/**/*.ts", "**/page/**/*.tsx"],
-      "plugins": ["./node_modules/@akanjs/devkit/lint/non-scalar-props-restricted.grit"]
-    },
-    {
-      "includes": ["**/*.constant.ts", "**/*.document.ts", "**/*.service.ts", "**/*.store.ts"],
-      "plugins": ["./node_modules/@akanjs/devkit/lint/no-js-private-class-method.grit"]
-    },
-    {
-      "includes": ["**/*.signal.ts"],
-      "plugins": ["./node_modules/@akanjs/devkit/lint/no-redeclare-predefined-endpoint.grit"]
-    },
-    {
-      "includes": [
-        "**/*.constant.ts",
-        "**/*.dictionary.ts",
-        "**/*.document.ts",
-        "**/*.service.ts",
-        "**/*.signal.ts",
-        "**/*.store.ts",
-        "**/*.Template.tsx",
-        "**/*.Unit.tsx",
-        "**/*.Util.tsx",
-        "**/*.View.tsx",
-        "**/*.Zone.tsx"
-      ],
-      "plugins": ["./node_modules/@akanjs/devkit/lint/no-deep-internal-import.grit"]
-    },
-    {
-      "includes": [
-        "**/page/**/*.ts",
-        "**/page/**/*.tsx",
-        "**/index.ts",
-        "**/index.tsx",
-        "**/cnst.ts",
-        "**/db.ts",
-        "**/dict.ts",
-        "**/option.ts",
-        "**/sig.ts",
-        "**/srv.ts",
-        "**/st.ts",
-        "**/*.constant.ts",
-        "**/*.dictionary.ts",
-        "**/*.document.ts",
-        "**/*.service.ts",
-        "**/*.signal.ts",
-        "**/*.signal.test.ts",
-        "**/*.service.test.ts",
-        "**/*.store.ts",
-        "**/*.Template.tsx",
-        "**/*.Unit.tsx",
-        "**/*.Util.tsx",
-        "**/*.View.tsx",
-        "**/*.Zone.tsx"
-      ],
-      "plugins": ["./node_modules/@akanjs/devkit/lint/no-import-external-library.grit"]
-    }
-  ]
+  }
 }

package/templates/workspaceRoot/docs/AI-DEVELOPMENT.md.template

@@ -49,8 +49,11 @@ See `docs/GENERATED.md` for the generated file list.
 
 `AGENTS.md` holds the full style guide. The rules agents break most often:
 
-- **Never hand-order Tailwind classes** — the linter sorts them, including inside `clsx()`, and its output looks
+- **Never hand-order Tailwind classes** — the linter sorts them, including inside `cn()`, and its output looks
   unnatural on purpose.
+- **Never use a colour outside the semantic vocabulary** — `bg-red-500`, `bg-[#3b82f6]` and `text-base-content`
+  compile to no CSS at all, so the element renders unstyled with no error. Use `bg-primary`, `text-foreground/70`
+  and the other tokens defined in `page/*/styles.css`.
 - **Never `throw new Error`** — throw `new Err("<module>.error.<key>")` with an `[en, ko]` entry in the module
   dictionary. `common/` cannot import `Err`, so keep throwing code out of it.
 - **Never import a third-party package** from a page, a barrel, or a module file. Re-export it through a one-line

package/{typeChecker-kravn7ns.js → typeChecker-g6bh0xfv.js}

@@ -2,7 +2,7 @@
 import {
   TypeChecker
 } from "./index-wnp7hwq7.js";
-import"./index-r24hmh0q.js";
+import"./index-yb2wsc7f.js";
 export {
   TypeChecker
 };

package/typecheck.proc.js

@@ -2,7 +2,7 @@
 import {
   TypeChecker
 } from "./index-wnp7hwq7.js";
-import"./index-r24hmh0q.js";
+import"./index-yb2wsc7f.js";
 
 // pkgs/@akanjs/devkit/typecheck/typecheck.proc.ts
 import { Logger } from "akanjs/common";

package/{workflow.command-e0tt0vk2.js → workflow.command-g2cgcgxn.js}

@@ -1,34 +1,35 @@
 // @bun
 import {
   WorkflowRunner
-} from "./index-2q1f5j9k.js";
+} from "./index-3dp7x6rc.js";
+import {
+  ScalarScript
+} from "./index-x33gnap3.js";
 import {
   PrimitiveScript
-} from "./index-bekddz9q.js";
+} from "./index-9jsnb4vw.js";
 import {
   ModuleScript
-} from "./index-yzmhasdb.js";
-import"./index-bbkek1bp.js";
-import {
-  ScalarScript
-} from "./index-ec09pws3.js";
+} from "./index-mykmf6wd.js";
 import"./index-ss469dec.js";
-import"./index-0cj2zxbm.js";
-import"./index-a00jg8x8.js";
+import"./index-qc0tnhs2.js";
+import"./index-sh01r3pm.js";
+import"./index-g9e2fhw2.js";
 import {
   createWorkflowStepRegistry
-} from "./index-rzwcpcc3.js";
-import"./index-tdbas9r0.js";
+} from "./index-tsmjxph2.js";
+import"./index-j37qq1f2.js";
 import {
   Workspace,
   command,
   script
-} from "./index-8hsbnyes.js";
-import"./index-hgna5rjy.js";
+} from "./index-n706txcv.js";
+import"./index-8vkkm7v0.js";
 import"./index-mxvakhsm.js";
 import"./index-xys926f2.js";
+import"./index-1577bej2.js";
 import"./index-67546d0j.js";
-import"./index-r24hmh0q.js";
+import"./index-yb2wsc7f.js";
 
 // pkgs/@akanjs/cli/workflow/workflow.script.ts
 import { Logger } from "akanjs/common";

package/{workspace.command-fpda0evj.js → workspace.command-f7jerqb2.js}

@@ -1,48 +1,48 @@
 // @bun
 import {
   ContextScript
-} from "./index-1pvex4az.js";
-import"./index-mr5s7mqd.js";
-import"./index-2q1f5j9k.js";
-import"./index-bekddz9q.js";
-import"./index-yzmhasdb.js";
-import"./index-bbkek1bp.js";
+} from "./index-0h212yqe.js";
+import"./index-xyrb7pk5.js";
+import"./index-3dp7x6rc.js";
+import"./index-x33gnap3.js";
+import"./index-9jsnb4vw.js";
+import"./index-mykmf6wd.js";
+import"./index-ss469dec.js";
+import"./index-qc0tnhs2.js";
 import {
   CloudScript
-} from "./index-nm6wghb6.js";
+} from "./index-becx1t0k.js";
 import {
   getLatestPackageVersion,
   getNpmRegistryUrl
-} from "./index-zasydjxd.js";
+} from "./index-t71zvmt9.js";
 import {
   PackageScript
-} from "./index-k95xkh4p.js";
-import"./index-ec09pws3.js";
-import"./index-ss469dec.js";
-import"./index-t3723f99.js";
+} from "./index-33zce8gt.js";
+import"./index-mz5jtaq7.js";
 import {
   GlobalConfig
-} from "./index-0cj2zxbm.js";
+} from "./index-sh01r3pm.js";
 import {
   AgentScript
-} from "./index-ej426mcr.js";
-import"./index-a00jg8x8.js";
-import"./index-rzwcpcc3.js";
-import"./index-tdbas9r0.js";
+} from "./index-k6fvbcj1.js";
+import"./index-g9e2fhw2.js";
+import"./index-tsmjxph2.js";
+import"./index-j37qq1f2.js";
 import {
   ApplicationScript
-} from "./index-e16gnn26.js";
-import"./index-76rn3g2c.js";
+} from "./index-8d2sv6pw.js";
 import {
   LibraryScript
-} from "./index-7c6k4yvg.js";
+} from "./index-73rnbwgg.js";
+import"./index-76rn3g2c.js";
 import {
   Exec,
   Workspace,
   command,
   runner,
   script
-} from "./index-8hsbnyes.js";
+} from "./index-n706txcv.js";
 import"./index-fgc8r6dj.js";
 import {
   ThemeValidator,
@@ -59,29 +59,30 @@ import {
   collectScopeRecipeSources,
   extractAgentBlock,
   renderScopeAgentBlock
-} from "./index-hgna5rjy.js";
+} from "./index-8vkkm7v0.js";
 import"./index-mxvakhsm.js";
 import {
   collectRecipeSources,
   scanRecipes
 } from "./index-xys926f2.js";
+import"./index-1577bej2.js";
 import"./index-46tjzh6s.js";
 import {
   FileSys
 } from "./index-67546d0j.js";
-import"./index-r24hmh0q.js";
-
-// pkgs/@akanjs/cli/workspace/workspace.script.ts
-import path2 from "path";
-import { Logger } from "akanjs/common";
+import"./index-yb2wsc7f.js";
 
 // pkgs/@akanjs/cli/workspace/workspace.runner.ts
 import path from "path";
+
+// pkgs/@akanjs/devkit/biomeBase.ts
+var biomeVersion = "2.5.8";
+
+// pkgs/@akanjs/cli/workspace/workspace.runner.ts
 var defaultWorkspacePeerDependencies = new Set([
   "@react-spring/web",
   "@use-gesture/react",
   "chance",
-  "croner",
   "react",
   "react-dom",
   "react-icons",
@@ -93,6 +94,7 @@ var defaultWorkspacePeerDependencies = new Set([
   "tailwindcss",
   "typescript"
 ]);
+var defaultMaxDiagnostics = 200;
 
 class WorkspaceRunner extends runner("workspace") {
   async generateAgentRules(workspace, { overwrite = false, cursorRules = true } = {}) {
@@ -113,17 +115,14 @@ class WorkspaceRunner extends runner("workspace") {
       dict,
       overwrite
     }));
-    if (!cursorRules)
-      return created;
-    return [
-      ...created,
-      ...await workspace.applyTemplate({
+    if (cursorRules)
+      created.push(...await workspace.applyTemplate({
         basePath: ".cursor/rules",
         template: "workspaceRoot/.cursor/rules/akan.mdc.template",
         dict,
         overwrite
-      })
-    ];
+      }));
+    return created;
   }
   async createWorkspace(repoName, appName, {
     dirname = ".",
@@ -137,10 +136,7 @@ class WorkspaceRunner extends runner("workspace") {
     const normalizedRegistryUrl = registryUrl ? getNpmRegistryUrl(registryUrl) : undefined;
     const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot, repoName });
     const templateSpinner = workspace.spinning(`Creating workspace template files in ${dirname}/${repoName}...`);
-    const [latestBiomeVersion, latestTypesBunVersion] = await Promise.all([
-      getLatestPackageVersion("@biomejs/biome", "latest", normalizedRegistryUrl),
-      getLatestPackageVersion("@types/bun", "latest", normalizedRegistryUrl)
-    ]);
+    const latestTypesBunVersion = await getLatestPackageVersion("@types/bun", "latest", normalizedRegistryUrl);
     await workspace.applyTemplate({
       basePath: ".",
       template: "workspaceRoot",
@@ -164,7 +160,7 @@ class WorkspaceRunner extends runner("workspace") {
       },
       devDependencies: {
         ...rootPackageJson.devDependencies,
-        "@biomejs/biome": latestBiomeVersion,
+        "@biomejs/biome": biomeVersion,
         "@types/bun": latestTypesBunVersion,
         "@akanjs/devkit": akanVersion,
         ...typescript ? { typescript } : {}
@@ -236,17 +232,28 @@ class WorkspaceRunner extends runner("workspace") {
     }
     throw new Error(`[workspace] failed to locate akanjs package.json from ${import.meta.dir}`);
   }
-  async lint(exec, workspace, { fix = true } = {}) {
+  async lint(exec, workspace, { fix = true, maxDiagnostics = defaultMaxDiagnostics } = {}) {
+    const configPath = await WorkspaceRunner.resolveBiomeConfigPath(workspace);
     await workspace.spawn("./node_modules/.bin/biome", [
       "check",
       ...fix ? ["--write"] : [],
       "--no-errors-on-unmatched",
+      `--max-diagnostics=${maxDiagnostics > 0 ? maxDiagnostics : "none"}`,
+      ...configPath ? ["--config-path", configPath] : [],
       exec.cwdPath
     ]);
     await this.#enforceStyleContract(exec);
     await this.#enforceRecipeGate(exec);
     await this.#enforceAgentsIndex(exec);
   }
+  static async resolveBiomeConfigPath(workspace) {
+    for (const fileName of ["biome.json", "biome.jsonc"]) {
+      const configPath = path.join(workspace.workspaceRoot, fileName);
+      if (await Bun.file(configPath).exists())
+        return configPath;
+    }
+    return null;
+  }
   async#enforceAgentsIndex(exec) {
     if (!(exec instanceof SysExecutor))
       return;
@@ -314,6 +321,8 @@ AKAN_PUBLIC_LOG_LEVEL=debug
 }
 
 // pkgs/@akanjs/cli/workspace/workspace.script.ts
+import path2 from "path";
+import { Logger } from "akanjs/common";
 class WorkspaceScript extends script("workspace", [
   WorkspaceRunner,
   ApplicationScript,
@@ -372,30 +381,33 @@ class WorkspaceScript extends script("workspace", [
   async generateAgentRules(workspace, { overwrite = false, cursorRules = true } = {}) {
     const spinner = workspace.spinning("Generating agent rules...");
     const files = await this.workspaceRunner.generateAgentRules(workspace, { overwrite, cursorRules });
+    if (files.some((file) => file.filePath.endsWith("AGENTS.md")))
+      await this.agentScript.agent(workspace, "install", "agents-md", { force: overwrite });
     spinner.succeed(`Agent rules ready (${files.length} file${files.length === 1 ? "" : "s"})`);
   }
-  async lint(exec, workspace, { fix = true } = {}) {
+  async lint(exec, workspace, { fix = true, maxDiagnostics } = {}) {
     if (exec instanceof AppExecutor)
       await this.applicationScript.sync(exec);
     else if (exec instanceof LibExecutor)
       await this.libraryScript.syncLibrary(exec);
     const spinner = workspace.spinning(`Linting${fix ? " with fix" : ""}...`);
     try {
-      await this.workspaceRunner.lint(exec, workspace, { fix });
+      await this.workspaceRunner.lint(exec, workspace, { fix, maxDiagnostics });
       spinner.succeed("Lint completed with no errors");
     } catch (error) {
       spinner.fail("Lint failed with errors");
       throw error;
     }
   }
-  async lintAll(workspace, { fix = true } = {}) {
+  async lintAll(workspace, { fix = true, maxDiagnostics } = {}) {
     const [appNames, libNames, pkgNames] = await workspace.getExecs();
+    const options = { fix, maxDiagnostics };
     await Promise.all(appNames.map((appName) => this.applicationScript.sync(AppExecutor.from(workspace, appName))));
     await Promise.all(libNames.map((libName) => this.libraryScript.syncLibrary(LibExecutor.from(workspace, libName))));
     await Promise.all([
-      ...appNames.map((appName) => this.workspaceRunner.lint(AppExecutor.from(workspace, appName), workspace, { fix })),
-      ...libNames.map((libName) => this.workspaceRunner.lint(LibExecutor.from(workspace, libName), workspace, { fix })),
-      ...pkgNames.filter((pkgName) => pkgName !== "contract").map((pkgName) => this.workspaceRunner.lint(PkgExecutor.from(workspace, pkgName), workspace, { fix }))
+      ...appNames.map((appName) => this.workspaceRunner.lint(AppExecutor.from(workspace, appName), workspace, options)),
+      ...libNames.map((libName) => this.workspaceRunner.lint(LibExecutor.from(workspace, libName), workspace, options)),
+      ...pkgNames.filter((pkgName) => pkgName !== "contract").map((pkgName) => this.workspaceRunner.lint(PkgExecutor.from(workspace, pkgName), workspace, options))
     ]);
   }
   async syncAll(workspace) {
@@ -477,11 +489,17 @@ class WorkspaceCommand extends command("workspace", [WorkspaceScript], ({ public
   }).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(exec, fix, workspace) {
-    await this.workspaceScript.lint(exec, workspace, { fix });
+  lint: target({ desc: "Lint and fix code in a specific app/lib/pkg" }).with(Exec).option("fix", Boolean, { default: true }).option("maxDiagnostics", Number, {
+    desc: "How many diagnostics Biome prints before truncating (0 for no limit)",
+    default: defaultMaxDiagnostics
+  }).with(Workspace).exec(async function(exec, fix, maxDiagnostics, workspace) {
+    await this.workspaceScript.lint(exec, workspace, { fix, maxDiagnostics });
   }),
-  lintAll: target({ desc: "Lint and fix code in all apps and libraries" }).option("fix", Boolean, { default: true }).with(Workspace).exec(async function(fix, workspace) {
-    await this.workspaceScript.lintAll(workspace, { fix });
+  lintAll: target({ desc: "Lint and fix code in all apps and libraries" }).option("fix", Boolean, { default: true }).option("maxDiagnostics", Number, {
+    desc: "How many diagnostics Biome prints before truncating (0 for no limit)",
+    default: defaultMaxDiagnostics
+  }).with(Workspace).exec(async function(fix, maxDiagnostics, workspace) {
+    await this.workspaceScript.lintAll(workspace, { fix, maxDiagnostics });
   }),
   syncAll: target({ desc: "Sync dependencies and configuration for all apps and libraries" }).with(Workspace).exec(async function(workspace) {
     await this.workspaceScript.syncAll(workspace);

package/templates/workspaceRoot/.cursor/rules/akan-page-routing.mdc.template

@@ -1,43 +0,0 @@
----
-description: Akan page routing conventions
-globs: apps/**/page/**/*.{ts,tsx,js,jsx}
-alwaysApply: false
----
-
-# Akan Page Routing
-
-- `apps/<app>/page` may contain route modules only. Do not add helper logic or component-only files there.
-- Route source files under `page/` must use `.tsx`. Do not add `logic.ts`, `.js`, or `.jsx` files under `page/`.
-- Route pages use `_index.tsx`; layouts use `_layout.tsx`.
-- Reserved `_*.tsx` route filenames are limited to `_index.tsx` and `_layout.tsx`; do not add files like `_Component.tsx` or `_helper.tsx`.
-- Page filenames must not start with an uppercase letter. Move helper components like `Component.tsx` to app `ui`, `common`, or `lib` instead.
-- Dynamic segments use `[id]`; route groups use directories like `(user)`, `(public)`, `(tab)`, or `(detail)`.
-- Page modules should usually export `default`, `pageConfig`, `head`, `generateHead`, or `Loading`.
-- Prefer `export default function Page` or `export default async function Page` for page components.
-- Before changing route behavior, check nearby routes for the expected pattern.
-
-## Page Body Shape
-
-```tsx
-interface PageProps {
-  params: { taskId: string };
-}
-
-export default async function Page({ params }: PageProps) {
-  const { l } = usePage();
-  getSelf({ unauthorize: "/signin" });
-  const { taskId } = params;
-  const [{ task }] = await Promise.all([fetch.viewTask(taskId)]);
-  return <Task.View.General task={task} />;
-}
-
-export const pageConfig = { transition: "stack" } satisfies PageConfig;
-```
-
-- There is no `loader=` / `render=` page prop. Pages are `export default async function Page`.
-- Declare `interface PageProps { params: {...}; searchParams?: {...} }` immediately above the default export.
-- Body order: `usePage()`, auth, destructure params, fetch, return.
-- Run independent fetches through `Promise.all`, even when there is only one.
-- Gate auth at `_layout.tsx`; repeating `getSelf({ unauthorize: "/signin" })` in the page is fine and common.
-- Keep `async` even when nothing is awaited — it marks a real server page.
-- No `useState`, no `useEffect`, and no comments in page files.

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

@@ -1,33 +0,0 @@
----
-description: sync-enforced Akan app/lib layout and generated index conventions
-globs: apps/**/*,libs/**/*
-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`.
-- 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.
-- Database module UI files are limited to `<Model>.Template.tsx`, `<Model>.Unit.tsx`, `<Model>.Util.tsx`, `<Model>.View.tsx`, and `<Model>.Zone.tsx`.
-- Service module UI files are limited to `<Service>.Util.tsx` and `<Service>.Zone.tsx`.
-- Scalar module UI files are limited to `<Scalar>.Template.tsx` and `<Scalar>.Unit.tsx`.
-- Module `*.test.ts`, `*.test.tsx`, `*.spec.ts`, and `*.spec.tsx` files are allowed.
-- `ui/index.ts`, `webkit/index.ts`, `srvkit/index.ts`, `common/index.ts`, and module `lib/**/index.ts` files are generated by `akan sync`; do not hand-edit or track them.
-- Generated facet indexes export only 1-depth files/folders with `export * from "./name";`.
-
-## Layer Placement
-
-| Folder | Admission test | Naming |
-|---|---|---|
-| `common/` | pure, isomorphic, zero-dependency; may import only sibling `common/*` and `akanjs/base`. Cannot import `Err`, so keep throwing code out of it. | camelCase file, filename equals the single export |
-| `webkit/` | touches `window` / `navigator` / Capacitor, or is a React hook | `use<Thing>.tsx` — `.tsx` even with no JSX |
-| `srvkit/` | touches `node:*`, `Bun`, `process.env`, a secret, or a server SDK | camelCase file, PascalCase class |
-| `ui/` | renders JSX and is not bound to one model | PascalCase component, camelCase sidecar (`swipeCard.util.ts`) |
-
-- Hooks return a named object of async closures, never a tuple.
-- Only layer-root `index.ts` barrels are generated. A `ui/<Folder>/index.tsx` that builds a namespace is hand-written source; the distinguishing test is that a generated barrel contains nothing but `export * from "./X";` lines.
-- `ui/<Folder>/index_.tsx` (trailing underscore) is the `"use client"` + `lazy()` boundary, with a server-safe `index.tsx` beside it. Collapsing the pair into one file breaks RSC.
-- Never add a sibling helper file inside `lib/<model>/`; helpers belong in one of the folders above.