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

package/{workspace.command-3q1d6kk4.js → workspace.command-5f2nmmd5.js}

@@ -1,55 +1,55 @@
 // @bun
 import {
   ContextScript
-} from "./index-p69fcwe1.js";
-import"./index-6npsfpxr.js";
-import"./index-c94nq3c1.js";
-import"./index-pfrt7qwh.js";
-import"./index-60a3jfcz.js";
-import"./index-hrwzz2wf.js";
+} from "./index-866yqz3y.js";
+import"./index-5fe016p2.js";
+import"./index-k7sm38v6.js";
+import"./index-7w5vv8jk.js";
+import"./index-97cw8sg1.js";
+import"./index-xrdrttjb.js";
+import"./index-ss469dec.js";
+import"./index-4z05haak.js";
 import {
   CloudScript
-} from "./index-mn96y1nk.js";
+} from "./index-y59x51f1.js";
 import {
   getLatestPackageVersion,
   getNpmRegistryUrl
-} from "./index-p6txr1ss.js";
+} from "./index-bwt525ne.js";
 import {
   PackageScript
-} from "./index-meh7mmz9.js";
-import"./index-wrrb8rxk.js";
-import"./index-ss469dec.js";
-import"./index-mterpj70.js";
+} from "./index-7zd96bng.js";
+import"./index-zgkey4d0.js";
 import {
   GlobalConfig
-} from "./index-0cj2zxbm.js";
+} from "./index-sh01r3pm.js";
 import {
   AgentScript
-} from "./index-nfxq39kj.js";
-import"./index-jn9vfpwz.js";
-import"./index-m4kpmmtj.js";
-import"./index-qp089jp0.js";
+} from "./index-xe3ychw5.js";
+import"./index-24h5bqpj.js";
+import"./index-5em412h5.js";
+import"./index-j37qq1f2.js";
 import {
   ApplicationScript
-} from "./index-nx1vbtsc.js";
-import"./index-76rn3g2c.js";
+} from "./index-7etegaht.js";
 import {
   LibraryScript
-} from "./index-exhpp31y.js";
+} from "./index-6bs24rb4.js";
+import"./index-76rn3g2c.js";
 import {
   Exec,
   Workspace,
   command,
   runner,
   script
-} from "./index-jkynkyfk.js";
+} from "./index-8rr621r2.js";
 import"./index-fgc8r6dj.js";
 import {
   ThemeValidator,
   countBlocking,
   formatStyleContract
 } from "./index-xjd3rqzj.js";
-import"./index-bjpxzr6s.js";
+import"./index-5vy2jzar.js";
 import {
   AppExecutor,
   LibExecutor,
@@ -59,29 +59,30 @@ import {
   collectScopeRecipeSources,
   extractAgentBlock,
   renderScopeAgentBlock
-} from "./index-47qxw1tz.js";
+} from "./index-90zyjrby.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,34 +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: `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.
-- 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.

package/templates/workspaceRoot/.cursor/rules/application-test-commands.mdc.template

@@ -1,16 +0,0 @@
----
-description: Application test commands after source changes
-alwaysApply: true
----
-
-# Application Test Commands
-
-- After changing application source code, test the app with `bun run akan start <appName>`.
-- Test production build generation with `bun run akan build <appName>`.
-- To test a built artifact locally, run it from the generated app directory with the required Akan runtime environment variables.
-
-```bash
-cd dist/apps/<appName> && USE_AKANJS_PKGS=true AKAN_PUBLIC_REPO_NAME=akansoft AKAN_PUBLIC_SERVE_DOMAIN="akanjs.com" AKAN_PUBLIC_APP_NAME=seon AKAN_PUBLIC_ENV=local AKAN_PUBLIC_OPERATION_MODE=local SERVER_MODE=federation AKAN_PUBLIC_BASE_PATHS=operator,office,homepage bun main.js
-```
-
-- Adjust `<appName>`, `AKAN_PUBLIC_APP_NAME`, and `AKAN_PUBLIC_BASE_PATHS` to match the app being tested.

package/templates/workspaceRoot/.cursor/rules/change-scope.mdc.template

@@ -1,12 +0,0 @@
----
-description: Keep edits scoped and avoid unrelated churn
-alwaysApply: true
----
-
-# Change Scope
-
-- Keep edits scoped to the requested task and the directly related files.
-- Do not reformat unrelated files or rewrite nearby code just for style.
-- Do not revert or overwrite unrelated user changes in a dirty working tree.
-- Prefer established nearby patterns over introducing a new abstraction.
-- Add new abstractions only when they remove real duplication or match an existing project pattern.

package/templates/workspaceRoot/.cursor/rules/client-server-boundaries.mdc.template

@@ -1,18 +0,0 @@
----
-description: Client/server boundary conventions for Akan apps
-globs: apps/**/*.{ts,tsx},libs/**/*.{ts,tsx},pkgs/akanjs/**/*.{ts,tsx}
-alwaysApply: false
----
-
-# Client Server Boundaries
-
-- Use `"use client";` at the top of client component files.
-- Be careful when importing client-only code from page or layout modules.
-- Keep page props serializable unless the existing route pattern clearly allows otherwise.
-- Let server page/layout files own route-level concerns: `usePage`, headers, static layout, and `akanjs/ui` `Tab` composition.
-- Keep interactive loading, submit/import actions, local form inputs, and `router.push` inside client `Util`, `Template`, or `Zone` components.
-- Prefer server-rendered `Tab` shells for static mode selection; put one client component inside each `Tab.Panel` instead of managing the selected mode with extra `useState`.
-- In domain UI the boundary is mechanical, not a judgment call: `Template`, `Zone`, and `Util` are always client components with `"use client"` on line 1; `Unit` and `View` are always server components and never carry the directive. `usePage()` is still legal in server files.
-- Preserve established domain file roles such as `.document.ts`, `.service.ts`, `.store.ts`, `.constant.ts`, and `.client.ts`.
-- When unsure, inspect nearby files in the same app or package before introducing a new boundary pattern.
-- The boundary is only half the rule: how *little* ends up on the client is the other half. See `ssr-first.mdc`.

package/templates/workspaceRoot/.cursor/rules/coding-comments.mdc.template

@@ -1,25 +0,0 @@
----
-description: Do not narrate code; document only what the code cannot say
-alwaysApply: true
----
-
-# Comments
-
-Do not narrate code. Do document the thing the code cannot say. Both halves are the rule.
-
-- Never add a comment that restates the identifier, the signature, or the control flow.
-- Prefer clear names and structure so ordinary logic needs no explanation.
-- Do not add JSDoc, section banners, or "why/how" comments for ordinary logic.
-- Comment density tracks the layer, not the author: pages carry none, product `lib/` and `ui/` code stays under 1 %, and `srvkit/` adapters and `guards.ts` carry as much as the external constraints require.
-- A comment is warranted for: a vendor spec or protocol quirk; an infrastructure constraint; a third-party library gotcha; security reasoning; why a rule that looks arbitrary is correct; a math derivation; a domain field's business meaning; a state transition above a document chain method; why an obvious alternative was rejected.
-- In-code markers:
-  1. `TODO` — unfinished work that must be tracked in-code
-  2. `FIXME` — known broken or incorrect behavior that must be fixed
-  3. `XXX` — dangerous / surprising hazard that a reader must not miss
-  4. `//!` — disabled or must-fix code
-  5. `//?` — an explanatory aside
-  6. `//*` — a design note
-  7. Deletion caution — warn why removing a line or block would break something non-obvious
-- Keep allowed comments one short line when possible.
-- Every suppression carries 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.

package/templates/workspaceRoot/.cursor/rules/coding-style.mdc.template

@@ -1,44 +0,0 @@
----
-description: Coding style conventions for classes, functions, files, and types
-globs: **/*.{ts,tsx}
-alwaysApply: false
----
-
-# Coding Style
-
-- For large units of work, prefer declaring a class and running the flow through an instance instead of scattering many standalone functions.
-- Prefer class methods or `static` methods over unrelated top-level helper functions when the logic belongs to a class-level workflow.
-- Prefer ECMAScript `#private` fields and methods over TypeScript `private`, except in the four suffixes where `#private` is lint-banned (`*.constant.ts`, `*.document.ts`, `*.service.ts`, `*.store.ts`) — those use TypeScript `private`. `#private` is the house style under `srvkit/`, including `adapt()` classes.
-- In files that declare a class, avoid top-level functions or variables when they can reasonably live inside the class.
-- Prefer `const` function expressions over `function` declarations unless hoisting, overloads, generators, or framework conventions make `function` the better fit.
-- Prefer declaring only one class per file; split the file when two or more class declarations are needed.
-- For class-centered modules, prefer noun-style filenames that match the primary class name, such as `RouteClientBuilder.ts`, instead of verb-style wrapper filenames like `buildRouteClient.ts`.
-- Avoid keeping exported functions that only instantiate a class and immediately call one method. Prefer migrating callers to instantiate the class directly.
-- Except for React component files or convention files, TypeScript filenames should use camelCase.
-- In React components, keep one-off `className` strings inline. Only extract class name constants when the class is reused, conditionally composed, or too large to read comfortably in JSX.
-
-# File Size And Duplication
-
-- Keep files small. The house median is well under 50 lines; split a component before it reaches ~150 lines rather than adding section comments.
-- Ship every scaffold file even when it is empty — `export class XInternal extends internal(srv.x, () => ({})) {}`, empty dictionary stages, the `// state` / `// action` markers in an empty store. They mark where things go.
-- Never add a sibling helper file inside `lib/<model>/`. Helpers go to `common/`, `webkit/`, `srvkit/`, or `ui/`.
-- Prefer duplication to premature abstraction at the leaf. Near-identical sibling modules and per-vendor pages are deliberately copied, not parameterised. Copy the file and change the literals; share enums by import only.
-
-# TypeScript Shape
-
-- Use `interface` for object shapes and `type` only for unions and aliases.
-- Declare `interface <ComponentName>Props` immediately above the component with no blank line between, and put `className?: string` first. Name it for the component (`CardProps`, `WorldProps`), never for the model. Do not export it unless a sibling imports it.
-- Never use a non-null assertion. Narrow with `?.`, an early return, or a type predicate such as `.filter((id): id is string => !!id)`.
-- Escape with `as unknown as T`. Never `as any`.
-- Never annotate a component's return type. Annotate a helper only when the return is a union, a tuple, or a type predicate.
-- Use `as const` on every `enumOf(...)` array, every `via(Model, [...] as const, …)` Light tuple, and every module-scope lookup map. Never use the TypeScript `enum` keyword.
-- Async functions carry no `Async` suffix.
-
-# Test Code
-
-- Write TypeScript tests with Bun's test runner and import `describe`, `expect`, and `test` from `bun:test`.
-- Keep tests colocated with the source they cover using `*.test.ts` or `*.spec.ts`, following the existing nearby pattern.
-- Prefer focused behavior tests for public contracts and edge cases over implementation-detail assertions.
-- Split signal tests in two. `<model>.signal.spec.ts` holds reusable fixtures built on `sampleOf(cnst.XInput)` with explicit `Promise<cnst.X>` return types and **no assertions**. `<model>.signal.test.ts` holds the assertions: `describe("<Model> Signal")`, `let` fixtures at describe scope, one `beforeAll`, story-ordered `it`s, and negatives via `await expect(p).rejects.toThrow()`.
-- `lib/user/user.signal.spec.ts` is the one place agent types are re-exported and re-typed; import `UserAgent` / `AdminAgent` from there rather than from the shared lib directly.
-- A placeholder `it` with a descriptive title is an acceptable floor. Write a real suite when the behaviour is security-relevant.

package/templates/workspaceRoot/.cursor/rules/domain-module-conventions.mdc.template

@@ -1,17 +0,0 @@
----
-description: Akan domain module file roles and naming conventions
-globs: apps/**/lib/**/*.{ts,tsx},libs/**/lib/**/*.{ts,tsx}
-alwaysApply: false
----
-
-# Domain Module Conventions
-
-- Organize business concepts as domain folders under `lib/`; keep related schema, service, signal, store, and UI files together.
-- Use lowercase logic files such as `<model>.constant.ts`, `<model>.document.ts`, `<model>.service.ts`, `<model>.signal.ts`, `<model>.dictionary.ts`, and `<model>.store.ts`.
-- Use PascalCase React component files such as `<Model>.Template.tsx`, `<Model>.Unit.tsx`, `<Model>.View.tsx`, `<Model>.Zone.tsx`, and `<Model>.Util.tsx`.
-- Treat `constant.ts`, `dictionary.ts`, and `signal.ts` as shared contract files that should avoid platform-specific dependencies.
-- Keep backend persistence/query logic in `.document.ts` and domain business orchestration in `.service.ts`.
-- Keep frontend state in `.store.ts`; use `Template` for forms, `Unit` for list/card items, `View` for details, `Zone` for composed page sections, and `Util` for domain-specific UI helpers.
-- Move reusable workflow state and actions from client UI into `<model>.store.ts` when they span loading state, selected lists, messages, or multi-step actions; consume them as `st.use.someState()` and `st.do.someAction()`.
-- Keep `Util` components thin when a store action exists: render controls, call `st.do.*`, read `st.use.*`, and leave orchestration in the store.
-- When adding or formalizing a public workflow such as importing an existing project, update the module `*.abstract.md` with the invariant or behavior change.

package/templates/workspaceRoot/.cursor/rules/format-lint.mdc.template

@@ -1,12 +0,0 @@
----
-description: Formatting and linting conventions
-alwaysApply: true
----
-
-# Formatting And Linting
-
-- Use Biome as the formatter and linter.
-- Format with `bun run akan lint <appName>` from the repo root.
-- Keep formatting consistent with `biome.json`: 2-space indentation, 120 line width, and double quotes for JS/TS.
-- Avoid adding new `console` usage except accepted methods such as `console.error`, `console.info`, and `console.warn`.
-- Do not make broad formatting-only changes in unrelated files.

package/templates/workspaceRoot/.cursor/rules/lint-enforced-rules.mdc.template

@@ -1,18 +0,0 @@
----
-description: Lint rules that break the build, including several whose correct output looks wrong
-alwaysApply: true
----
-
-# Lint-Enforced Rules (These Break The Build)
-
-Enforced by `biome.json` and the Akan grit plugins registered in `biome.json`. Several of them produce output that looks wrong; do not "fix" it back.
-
-- **Never hand-order Tailwind classes.** `nursery/useSortedClasses` is an error and also sorts the string arguments to `clsx()` and `cva()`. Sorter output such as `font-bold text-2xl text-base-content` or `border-base-content/5 border-t` is correct. Write the classes in any order, run the formatter, leave the result.
-- **Never `throw new Error`.** Throw `new Err("<module>.error.<key>")` and register the key as `[en, ko]` in that module's dictionary `.error({})`. Import `Err` from `"../dict"` on the server and from `"@libs/<lib>/client"` or `"@apps/<app>/client"` in UI. `no-throw-raw-error.grit` exempts `*.test.ts`, `*.spec.ts`, `*.constant.ts`, and `common/**` — `common/` has no legal `Err` import path, so keep throwing code out of it.
-- **Never import a third-party package** from `page/**`, from any barrel, or from any `*.{constant,dictionary,document,service,signal,store}.ts` / `*.{Template,Unit,Util,View,Zone}.tsx` (`no-import-external-library.grit`). Re-export the symbol through a lib first. One-line re-export shims such as `libs/<lib>/base/<pkg>.ts` and `libs/<lib>/webkit/<hook>.ts` exist for exactly this reason — they are load-bearing, not cruft. Do not delete them.
-- **`#private` is banned in exactly four file suffixes:** `*.constant.ts`, `*.document.ts`, `*.service.ts`, and `*.store.ts` (`no-js-private-class-method.grit`). The rule is scoped by file path, not by class shape, so `#private` remains the house style everywhere under `srvkit/`, including `adapt()` adapter classes.
-- **No `console.log` / `console.debug`.** Only `assert`, `error`, `info`, and `warn` are allowed. Server code uses the injected `this.logger.*` or `new Logger("ClassName")`.
-- **Never redeclare a generated CRUD endpoint name** in `*.signal.ts` (`no-redeclare-predefined-endpoint.grit`).
-- **No deep imports past a barrel** (`no-deep-internal-import.grit`). Cross-module constant references such as `../map/map.constant` are the sanctioned exception.
-- **Server-component discipline** is enforced on `page/**`, `*.Unit.tsx`, and `*.View.tsx` (`no-import-client-functions.grit`, `no-use-client-in-server.grit`, `non-scalar-props-restricted.grit`).
-- `noArrayIndexKey` and `useExhaustiveDependencies` are **off** on purpose: `key={idx}` for embedded scalars and short dependency arrays are intentional, not oversights.

package/templates/workspaceRoot/.cursor/rules/module-file-playbook.mdc.template

@@ -1,61 +0,0 @@
----
-description: Per-file shape for constant, document, service, signal, store, dictionary, and abstract files
-globs: apps/**/lib/**/*.{ts,tsx,md},libs/**/lib/**/*.{ts,tsx,md}
-alwaysApply: false
----
-
-# Module File Playbook
-
-## `<model>.constant.ts`
-
-Five classes in order with one blank line between them and `enumOf("camelName", [...] as const)` classes above: `XInput → XObject → LightX → X → XInsight`. Write `XInsight` even when it is empty.
-
-- Put display and predicate logic on `LightX` (`isNew()`, `canWrite(user?)`, `formatTimes()`, `isCancellable()`) — the Light class is the one both server and client hold, so shared logic belongs there instead of in a util module. This is the most commonly missed rule in the codebase.
-- Collection-level helpers go `static` on the full model.
-- Defaults are a literal for scalars and a thunk for anything constructed. Arrays are `field([T])`; optional is the postfix `.optional()`.
-- Give any field whose business meaning is not obvious a short trailing comment.
-
-## `<model>.document.ts`
-
-Fixed order: `XFilter extends from(...)` → `X extends by(...)` → `XModel extends into(...)`, with `sort: {}` always present.
-
-- Chain methods validate → mutate → `return this`, and never `save()`; the caller saves, so chains compose (`org.removeUser(id).removeInvite(id).save()`).
-- Put a one-line comment above each chain method stating the transition.
-- Atomic counters live on the Model class with the updater-callback form, returning `!!modifiedCount`.
-- Indexes and derived totals go in `static override _onSchema`, not in the service.
-
-## `<model>.service.ts`
-
-- Keep methods to a few lines: load → chain → `return await ….save()`. Write `return await` explicitly in tail position; do not "optimize" it away.
-- Side effects belong in `override async _preUpdate` / `_postCreate`, not inline.
-- Fire-and-forget is explicitly `void`-ed.
-- Order deliberately: load every referenced document, then save, then notify.
-- Return `null` / `false` for "not allowed" or "not found" and let the signal decide whether that is an error.
-
-## `<model>.signal.ts`
-
-- `XInternal` → `XSlice` → `XEndpoint`, all three declared even when empty. `exec` is a one-liner delegating to the service.
-- Every `slice()` takes an explicit `{ guards: {…} }` second argument, and `root:` is always `Admin`.
-- Every custom `mutation` / `query` / `message` names its own `guards: [...]` array. `Public` belongs on a slice `get:`, never on a mutation.
-- The acting user arrives via `.with(Self)` / `.with(CurrentUserId)` / `.with(Me)`. Never trust a client-supplied id.
-
-## `<model>.store.ts`
-
-- Write a custom action only for a toast, an optimistic update, or a multi-field write; most stores need none, because state and CRUD actions are generated.
-- The body is three lines: `await fetch.X` → `this.setX(...)` → toast. The optimistic shape is mutate the client model, `void fetch.*`, then commit.
-- Use `this.pick(...)` when the value must exist, `this.get()` when it may not, and `this.set({...})` to write.
-- Mutate lists through the collection API (`this.set({ xList: xList.set(x).save() })`), not array spread.
-- **Never `import type { RootStore } from "../st"`** — it crashes `akan build` with a Bun SSR segfault.
-- Store actions do not `try/catch`; let the framework toast the `Err`.
-
-## `<model>.dictionary.ts`
-
-Fixed chain, with empty stages still written: `.of() → .model() → .insight() → .query() → .sort() → .enum() → .slice() → .endpoint() → .error() → .translate()`.
-
-- Every label is `t(["English", "한국어"])`, and nearly every one also carries `.desc([en, ko])`.
-- Name every argument in `.arg()`, including framework-supplied `skip` / `limit` / `sort`.
-- Use `modelDictionary`, `scalarDictionary`, or `serviceDictionary` to match the module kind.
-
-## `<module>.abstract.md`
-
-A title line, one declarative sentence naming what the module owns, a `## Rules` list of two to five invariants the code cannot show, and an optional workflow arrow chain (`draft -> signed -> active -> completed`). Never restate field lists or types. Update it whenever an invariant or workflow changes.

package/templates/workspaceRoot/.cursor/rules/naming-conventions.mdc.template

@@ -1,15 +0,0 @@
----
-description: Naming conventions for components, methods, slices, booleans, and language choice
-alwaysApply: true
----
-
-# Naming And Language
-
-- Component exports are role names — `Card`, `Sticker`, `General`, `Preview`, `Admin`, `World`, `Mesh`, `Remove`. The model comes from the namespace (`<Floor.Unit.Card>`), so never write `FloorCard`. `Util` exports are the endpoint verb minus the model noun (`Serve`, `Refund`, `Complete`, `Terminate`).
-- Layer the verbs: the document chain method drops the model (`sign()`, `approve()`), the service keeps the bare verb, and the signal, store, and dictionary re-add it (`signScContract`). This keeps custom endpoints clear of generated CRUD and makes `st.do.X` read the same as `fetch.X`.
-- Slice and filter names are prepositional: `inOrg`, `inProject`, `inPeriod`, `byStatuses`, `ofPortfolio`. Never `getXInY`, never `listX`.
-- Handlers are `onX` props taking inline arrows. Do not extract a `handleX`.
-- Booleans are `is*` / `has*` / `can*` / `show*` / `disable*`. Counters are `*Num`, indices are `idx`, collections are `*List` or plural. `SCREAMING_SNAKE` is unused; module-scope tables are camelCase + `as const`.
-- Keep existing domain vocabulary and its typos. Transliterated domain terms and misspelled identifiers already in use are load-bearing — renaming them silently breaks callers that match on the name.
-- Identifiers, type names, endpoint names, and log messages are **English, always**. Everything a user reads goes through `l("model.field")` or `l.trans({ en, ko })` — never a hard-coded string in JSX, never `window.alert`.
-- Dictionary entries are `[en, ko]` pairs, and nearly every label also carries a `.desc([en, ko])` even when it repeats the label. English labels are Title Case, Korean is the plain domain term, and `.error()` Korean ends in `다.`.

package/templates/workspaceRoot/.cursor/rules/react-component-style.mdc.template

@@ -1,21 +0,0 @@
----
-description: React component, form, and Tailwind/daisyUI styling conventions
-globs: **/*.tsx
-alwaysApply: false
----
-
-# React Components And Styling
-
-- Components are `export const X = ({ … }: XProps) => { return (…); };` — arrow const with a block body. `export default` is reserved for pages, layouts, and `lazy()` targets.
-- Never `React.FC`, never `defaultProps`, never `PropsWithChildren`. Defaults go in the destructuring (`prefix = ""`); children are typed `children: ReactNode`.
-- `"use client"` on line 1 above the imports is mechanical by file role: every `.Zone.tsx`, `.Template.tsx`, and `.Util.tsx` has it; no `.Unit.tsx` or `.View.tsx` ever does. `usePage()` is legal in server files.
-- Conditional render is `cond ? <X/> : null`. Never `{cond && <X/>}` — in a `className` context it renders the literal string `"false"`. Early `return null` is for guard clauses only.
-- Never hand-roll loading, empty, or list states. Use `Load.Units` / `Load.View` / `Load.Edit` with `renderItem`, `renderList`, `renderView`, and `renderEmpty`; `<Empty />` for a bare placeholder; and `Model.New` / `Model.Edit` / `Model.SureToRemove` for CRUD modals.
-- Avoid hooks. `useState` is for modal-open, tab, draft-input, and drag state only — never for server data. `useEffect` must be a genuine effect such as subscribe-with-cleanup or one-shot init. Prefer `Tab` over a `useState` mode switch. `.Template.tsx` files contain zero `useState`.
-- Forms are entirely store-driven: `value={xForm.field}` with `onChange={st.do.setFieldOnX}`, the setter passed by reference. Always use `Field.*`, never a bare `<input>` for a model field. Nested rows use `st.do.writeOnX("payments.3.name", v)` plus the generated `add<Field>OnX` / `sub<Field>OnX`.
-- Read with `st.use.*` and write with `st.do.*`. Client components do not call `fetch.*`.
-- Static class strings stay plain strings. Reach for `clsx` only for a conditional or to merge an incoming `className`, and merge the caller last: `clsx("base classes", conditional, className)`. `clsx` comes from `akanjs/client`. No `twMerge`, no `cn()`.
-- Multi-slot components take extra named props (`wrapperClassName`, `bodyClassName`), never a `classNames` object.
-- Use daisyUI semantic tokens with opacity modifiers (`text-base-content/60`, `border-base-content/10`, `bg-base-100/70`, `bg-primary/10`). Never use `dark:` — theming is the daisyUI theme block in `page/*/styles.css`. Raw hex belongs only in marketing surfaces; match the neighbouring files.
-- Hoist enum→class lookups to a module-scope `as const` map typed `{ [key in cnst.XStatus["value"]]: string }`. Do not use `Record<...>`. Escalate the map to `webkit/` when a second module needs it.
-- Use `<Link>` from `akanjs/ui` for internal navigation; `<a>` only for `mailto:` and external links.