@akanjs/cli 2.4.1 → 2.4.2-rc.1

package/{module.command-29wvnb56.js → module.command-vwahdkzr.js}

@@ -1,21 +1,21 @@
 // @bun
 import {
   ModuleScript
-} from "./index-h6pevatb.js";
-import"./index-qacv44mm.js";
+} from "./index-tnngmzgf.js";
+import"./index-f1x6fe2e.js";
 import"./index-ss469dec.js";
 import {
   renderPrimitiveReport
-} from "./index-2v10yr8g.js";
-import"./index-eqxmxan6.js";
-import"./index-5vvwc0cz.js";
+} from "./index-ckywhpvp.js";
+import"./index-ehjhzg5y.js";
+import"./index-nsj2ftxj.js";
 import {
   Module,
   Sys,
   command
-} from "./index-phj3ewxv.js";
-import"./index-0t7pwff2.js";
-import"./index-61keag0s.js";
+} from "./index-en4zpzdm.js";
+import"./index-s6nk9815.js";
+import"./index-67546d0j.js";
 import"./index-6pz1j0zj.js";
 import"./index-r24hmh0q.js";
 

package/{package.command-46r1dncm.js → package.command-wkwd5x5p.js}

@@ -1,15 +1,15 @@
 // @bun
 import {
   PackageScript
-} from "./index-p9f1rpbp.js";
+} from "./index-31e8cwjq.js";
 import {
   Pkg,
   Workspace,
   command
-} from "./index-phj3ewxv.js";
-import"./index-0t7pwff2.js";
-import"./index-x53a5nya.js";
-import"./index-61keag0s.js";
+} from "./index-en4zpzdm.js";
+import"./index-s6nk9815.js";
+import"./index-46tjzh6s.js";
+import"./index-67546d0j.js";
 import"./index-6pz1j0zj.js";
 import"./index-r24hmh0q.js";
 

package/package.json

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

package/{page.command-vxvqdzc0.js → page.command-9w85hrg0.js}

@@ -1,14 +1,14 @@
 // @bun
 import {
   PageScript
-} from "./index-qacv44mm.js";
+} from "./index-f1x6fe2e.js";
 import {
   App,
   Module,
   command
-} from "./index-phj3ewxv.js";
-import"./index-0t7pwff2.js";
-import"./index-61keag0s.js";
+} from "./index-en4zpzdm.js";
+import"./index-s6nk9815.js";
+import"./index-67546d0j.js";
 import"./index-6pz1j0zj.js";
 import"./index-r24hmh0q.js";
 

package/{primitive.command-yk622wmt.js → primitive.command-2hnr8h7f.js}

@@ -1,21 +1,21 @@
 // @bun
 import {
   PrimitiveScript
-} from "./index-m04as81s.js";
-import"./index-h6pevatb.js";
-import"./index-qacv44mm.js";
+} from "./index-mpj63mbw.js";
+import"./index-tnngmzgf.js";
+import"./index-f1x6fe2e.js";
 import"./index-ss469dec.js";
 import {
   renderPrimitiveReport
-} from "./index-2v10yr8g.js";
-import"./index-eqxmxan6.js";
-import"./index-5vvwc0cz.js";
+} from "./index-ckywhpvp.js";
+import"./index-ehjhzg5y.js";
+import"./index-nsj2ftxj.js";
 import {
   Workspace,
   command
-} from "./index-phj3ewxv.js";
-import"./index-0t7pwff2.js";
-import"./index-61keag0s.js";
+} from "./index-en4zpzdm.js";
+import"./index-s6nk9815.js";
+import"./index-67546d0j.js";
 import"./index-6pz1j0zj.js";
 import"./index-r24hmh0q.js";
 

package/{quality.command-p0mb5xwt.js → quality.command-4kerz7mh.js}

@@ -4,9 +4,9 @@ import {
   command,
   runner,
   script
-} from "./index-phj3ewxv.js";
-import"./index-0t7pwff2.js";
-import"./index-61keag0s.js";
+} from "./index-en4zpzdm.js";
+import"./index-s6nk9815.js";
+import"./index-67546d0j.js";
 import"./index-6pz1j0zj.js";
 import"./index-r24hmh0q.js";
 

package/{repair.command-nptckp6w.js → repair.command-zmwshmvr.js}

@@ -1,16 +1,16 @@
 // @bun
 import {
   RepairRunner
-} from "./index-81epkybm.js";
-import"./index-eay4t1te.js";
-import"./index-2v10yr8g.js";
+} from "./index-xjkjcbhd.js";
+import"./index-xdf6rxyt.js";
+import"./index-ckywhpvp.js";
 import {
   Workspace,
   command,
   script
-} from "./index-phj3ewxv.js";
-import"./index-0t7pwff2.js";
-import"./index-61keag0s.js";
+} from "./index-en4zpzdm.js";
+import"./index-s6nk9815.js";
+import"./index-67546d0j.js";
 import"./index-6pz1j0zj.js";
 import"./index-r24hmh0q.js";
 

package/{routeSourceValidator-wbhmbwpj.js → routeSourceValidator-cncd92fv.js}

@@ -100,6 +100,45 @@ class RouteSourceValidator {
     if (exported.has("metadata") && exported.has("generateMetadata")) {
       throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${filePath}`);
     }
+    return { devOnly: RouteSourceValidator.#readDevOnly(sourceFile, filePath) };
+  }
+  static #readDevOnly(sourceFile, filePath) {
+    for (const statement of sourceFile.statements) {
+      if (!ts.isVariableStatement(statement))
+        continue;
+      const isExported = ts.getModifiers(statement)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+      if (!isExported)
+        continue;
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts.isIdentifier(declaration.name) || declaration.name.text !== "pageConfig")
+          continue;
+        const initializer = RouteSourceValidator.#unwrapExpression(declaration.initializer);
+        if (!initializer || !ts.isObjectLiteralExpression(initializer))
+          continue;
+        for (const property of initializer.properties) {
+          if (!ts.isPropertyAssignment(property))
+            continue;
+          const name = property.name;
+          const key = ts.isIdentifier(name) ? name.text : ts.isStringLiteral(name) ? name.text : null;
+          if (key !== "devOnly")
+            continue;
+          const value = RouteSourceValidator.#unwrapExpression(property.initializer);
+          if (value?.kind === ts.SyntaxKind.TrueKeyword)
+            return true;
+          if (value?.kind === ts.SyntaxKind.FalseKeyword)
+            return false;
+          throw new Error(`[route-convention] pageConfig.devOnly must be a literal true or false in ${filePath} \u2014 the build reads it without evaluating the module`);
+        }
+      }
+    }
+    return false;
+  }
+  static #unwrapExpression(expression) {
+    let current = expression;
+    while (current && (ts.isAsExpression(current) || ts.isSatisfiesExpression(current) || ts.isParenthesizedExpression(current))) {
+      current = current.expression;
+    }
+    return current;
   }
   static validateOverridesSourceExports(source, filePath) {
     const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);

package/{scalar.command-bss14hez.js → scalar.command-9kanb73t.js}

@@ -1,19 +1,19 @@
 // @bun
 import {
   ScalarScript
-} from "./index-d2e2y85b.js";
+} from "./index-cp26p7qd.js";
 import"./index-ss469dec.js";
 import {
   renderPrimitiveReport
-} from "./index-2v10yr8g.js";
-import"./index-eqxmxan6.js";
-import"./index-5vvwc0cz.js";
+} from "./index-ckywhpvp.js";
+import"./index-ehjhzg5y.js";
+import"./index-nsj2ftxj.js";
 import {
   Sys,
   command
-} from "./index-phj3ewxv.js";
-import"./index-0t7pwff2.js";
-import"./index-61keag0s.js";
+} from "./index-en4zpzdm.js";
+import"./index-s6nk9815.js";
+import"./index-67546d0j.js";
 import"./index-6pz1j0zj.js";
 import"./index-r24hmh0q.js";
 

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

@@ -14,4 +14,30 @@ alwaysApply: false
 - 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 `pkgs/akanjs/server/src/routeTree.tsx` and nearby routes for the expected pattern.
+- 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

@@ -17,3 +17,17 @@ alwaysApply: false
 - 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/client-server-boundaries.mdc.template

@@ -12,6 +12,6 @@ alwaysApply: false
 - 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, `Template`, `Zone`, and `Util` components are usually client components; `Unit` and `View` components are usually server components.
+- 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.

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

@@ -1,19 +1,25 @@
 ---
-description: Never comment in code except TODO/FIXME/XXX or deletion warnings
+description: Do not narrate code; document only what the code cannot say
 alwaysApply: true
 ---
 
 # Comments
 
-- Never add comments in code by default.
-- Prefer clear names and structure so the code needs no explanation.
-- Do not narrate what the code already says.
+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.
-- Comments are allowed only for these purposes:
+- 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. Deletion caution — warn why removing a line or block would break something non-obvious
+  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,5 +1,5 @@
 ---
-description: Coding style conventions for classes and functions
+description: Coding style conventions for classes, functions, files, and types
 globs: **/*.{ts,tsx}
 alwaysApply: false
 ---
@@ -8,7 +8,7 @@ alwaysApply: false
 
 - 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`; `*.service.ts` files are the main exception where `private` methods are encouraged.
+- 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.
@@ -17,8 +17,28 @@ alwaysApply: false
 - 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.
+- 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/lint-enforced-rules.mdc.template

@@ -0,0 +1,18 @@
+---
+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

@@ -0,0 +1,61 @@
+---
+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

@@ -0,0 +1,15 @@
+---
+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

@@ -0,0 +1,21 @@
+---
+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.

package/templates/workspaceRoot/.cursor/rules/scalar-modeling.mdc.template

@@ -7,8 +7,52 @@ alwaysApply: false
 # Scalar Modeling
 
 - Define Akan models in `.constant.ts` files with `via` from `akanjs/constant`.
-- Import custom scalar helpers such as `ID`, `Int`, `Float`, `JSON`, `Upload`, `Any`, `enumOf`, or `dayjs` from `akanjs/base` when the model needs them.
 - Use `Int` for whole-number counts and quantities; use `Float` only for values that need decimals.
-- Use `ID` for document references and prefer explicit structured fields over `JSON` unless the content is genuinely flexible.
+- Use `ID` for document references and prefer explicit structured fields over `Any` unless the content is genuinely flexible.
 - For date defaults, prefer a function such as `default: () => dayjs()` so the value is created at runtime.
-- Follow the established model layering pattern: `Input`, `Object`, `Light<Model>`, full `<Model>`, and `<Model>Insight` when the domain needs those views.
+- Follow the established model layering pattern in this order: `Input`, `Object`, `Light<Model>`, full `<Model>`, and `<Model>Insight`. Write all five, and write `<Model>Insight` even when it is empty.
+- Put display and predicate logic on the `Light<Model>` class (`isNew()`, `canWrite(user?)`, `formatTimes()`) rather than in a util module — the Light class is the one both server and client hold. 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.
+
+## Scalar & Field Type Reference
+
+- **Import from `akanjs/base`** (real classes/helpers, not globals): `Int`, `Float`, `ID`, `Any`, `Upload`, `enumOf`, and the `dayjs` factory. There is **no `JSON` scalar** — use `Any` for open/flexible payloads.
+- **Use the JS globals directly (no import needed)**: `String`, `Boolean`, `Date`. They are monkey-patched to behave like scalars, so `field(String)` typechecks.
+- **`Number` is not a valid field/body type.** `NumberConstructor` is intentionally not augmented, so `field(Number)` / `.body("x", Number)` fails to typecheck. Use `Int` or `Float` instead.
+- Runtime resolution of every scalar (globals included) goes through `PrimitiveRegistry` by `refName` (`pkgs/akanjs/base/primitiveRegistry.ts`).
+
+## Text Search Fields — the `text` role
+
+- A field joins the full-text index by declaring one of five roles: `field(String, { text: "title" })`, and likewise
+  `"desc"`, `"tag"`, `"thumb"`, `"filter"`. Nothing else opts a field in, and there is no per-model switch.
+- Pick the role by what the value *is*, because `bm25` weights them positionally (`title` 10, `tag` 3, `desc` 1,
+  `filter` 0): `title` is the one line a human scans for, `desc` is prose, `tag` is a keyword list, `filter` is a
+  scoping value (status, owner, role) that must be matchable but must never outrank a real title hit.
+- `thumb` is mirrored for rendering a hit and is **not** indexed — never expect it to match.
+- **A `secret`, `hidden`, or `resolve()` field with `text` throws at class-build time**, not at query time. That is
+  deliberate: the mirror is plaintext, so an indexed secret would leak through search. Do not work around it. The
+  same throw covers a `text` field *underneath* one of those — a scalar's own field is reachable through its parent,
+  so `f.secret(Noti)` where `Noti.label` carries a role is rejected at the parent, not silently indexed.
+- The role works on a relation too (`image: field(File, { text: "thumb" })`) and on an array (`playing: field([String],
+  { text: "tag" })`); an array of objects indexes by leaf key, including an array leaf (`works[*].tags`). A field
+  inside a `Map` indexes nothing: there is no fixed path to extract it from.
+- Declaring roles is all the wiring there is. Mirror rows are maintained by SQL triggers — not document hooks —
+  because `updateOneByQuery` and friends fire no hooks, and most searchable-field mutations go through exactly that
+  path.
+- Search runs on sqlite/libsql only. `q.search()` against Postgres throws, loudly, rather than returning every row.
+- `AKAN_SEARCH_ENABLED=0` switches the index off process-wide; unset means on. It never deletes mirror data, and
+  re-enabling reconciles every ref. **Give every process the same value** — a process cannot drop triggers for models
+  it does not mount, so a mixed fleet leaves stale triggers behind.
+- The tokenizer is `AKAN_SEARCH_TOKENIZER` (or `database.search.tokenizer`, which wins), defaulting to
+  `unicode61 remove_diacritics 2`. Changing it rebuilds the index from the mirror on the next boot — the model
+  tables are never re-read — so it is a safe knob, unlike a `text` role change, which re-reads every row. The
+  rebuild takes no cross-process claim, so a fleet restarted at once repeats it in every process; stagger the
+  restart when the mirror is large.
+
+## Image & File Fields
+
+- **Do not declare `Upload` as a model field.** `Upload` is a signal-body-only primitive. Models reference the `File` model instead.
+- Declare an image/file field as a relation to `File`: `image: field(File).optional()` for one, `images: field([File])` for many (see `libs/shared/lib/user/user.constant.ts`, `libs/shared/lib/banner/banner.constant.ts`).
+- The store then auto-generates an `upload<Field>On<Model>(fileList)` action that calls the framework upload mutation and polls file status until it leaves `"uploading"` (`pkgs/akanjs/store/action.ts`).
+- Storage is wired through the `StorageAdaptor` DI role (default `BlobStorage`, `pkgs/akanjs/service/predefinedAdaptor/storage.adaptor.ts`); the reference implementation is the `file` lib (`libs/shared/lib/file/*`). Do not hand-roll data-URL fallbacks.