@akanjs/cli 3.0.0-alpha.8 → 3.0.0-alpha.9

package/templates/workspaceRoot/biome.json.template

@@ -1,49 +1,12 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.5.2/schema.json",
-  "vcs": {
-    "enabled": true,
-    "clientKind": "git",
-    "useIgnoreFile": false
-  },
+  "$schema": "https://biomejs.dev/schemas/2.4.4/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",
@@ -53,209 +16,5 @@
       "!!**/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/**",
-        "!apps/akan/env/**"
-      ],
-      "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": ["**/*.store.ts"],
-      "plugins": ["./node_modules/@akanjs/devkit/lint/no-return-in-store-action.grit"]
-    },
-    {
-      "includes": ["**/*.signal.ts"],
-      "plugins": ["./node_modules/@akanjs/devkit/lint/no-redeclare-predefined-endpoint.grit"]
-    },
-    {
-      "includes": [
-        "**/ui/**/*.ts",
-        "**/ui/**/*.tsx",
-        "**/webkit/**/*.ts",
-        "**/webkit/**/*.tsx",
-        "**/common/**/*.ts",
-        "**/page/**/*.tsx",
-        "**/*.constant.ts",
-        "**/*.store.ts",
-        "**/*.Template.tsx",
-        "**/*.Unit.tsx",
-        "**/*.Util.tsx",
-        "**/*.View.tsx",
-        "**/*.Zone.tsx",
-        "!**/*.test.ts",
-        "!**/*.test.tsx",
-        "!**/*.spec.ts",
-        "!**/*.spec.tsx"
-      ],
-      "plugins": ["./node_modules/@akanjs/devkit/lint/no-bang-comment-in-client.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"]
-    },
-    {
-      "includes": [
-        "apps/**/*.ts",
-        "apps/**/*.tsx",
-        "libs/**/*.ts",
-        "libs/**/*.tsx",
-        "!**/*.test.ts",
-        "!**/*.test.tsx",
-        "!**/*.spec.ts",
-        "!**/*.spec.tsx"
-      ],
-      "plugins": [
-        "./node_modules/@akanjs/devkit/lint/no-raw-palette-class.grit",
-        "./node_modules/@akanjs/devkit/lint/no-arbitrary-color.grit",
-        "./node_modules/@akanjs/devkit/lint/no-daisyui-legacy-class.grit",
-        "./node_modules/@akanjs/devkit/lint/no-inline-color.grit",
-        "./node_modules/@akanjs/devkit/lint/no-interpolated-arbitrary-class.grit"
-      ]
-    }
-  ]
+  }
 }

package/{workflow.command-91wmvm8k.js → workflow.command-2ygfqt4f.js}

@@ -1,32 +1,33 @@
 // @bun
 import {
   WorkflowRunner
-} from "./index-5pmx7bkg.js";
+} from "./index-qzdjd4ct.js";
+import {
+  ScalarScript
+} from "./index-y4vkyhvv.js";
 import {
   PrimitiveScript
-} from "./index-bz2sfzzt.js";
+} from "./index-3vta1tqa.js";
 import {
   ModuleScript
-} from "./index-vtj3zps1.js";
-import"./index-4hek879p.js";
-import {
-  ScalarScript
-} from "./index-gmy45vz2.js";
+} from "./index-jhpa13zj.js";
 import"./index-ss469dec.js";
+import"./index-xmmzf150.js";
 import"./index-0cj2zxbm.js";
-import"./index-mssqn2sq.js";
+import"./index-774gcx29.js";
 import {
   createWorkflowStepRegistry
-} from "./index-2c3e2xh8.js";
-import"./index-7myvn0f0.js";
+} from "./index-rxkpk7n4.js";
+import"./index-j37qq1f2.js";
 import {
   Workspace,
   command,
   script
-} from "./index-6rhabeev.js";
-import"./index-vg0sj9nc.js";
+} from "./index-kdh76j26.js";
+import"./index-z8ptfkzv.js";
 import"./index-mxvakhsm.js";
 import"./index-xys926f2.js";
+import"./index-1577bej2.js";
 import"./index-67546d0j.js";
 import"./index-r24hmh0q.js";
 

package/{workspace.command-wa10mfd9.js → workspace.command-88m0zs64.js}

@@ -1,48 +1,48 @@
 // @bun
 import {
   ContextScript
-} from "./index-w6wbb612.js";
-import"./index-ztpw544k.js";
-import"./index-5pmx7bkg.js";
-import"./index-bz2sfzzt.js";
-import"./index-vtj3zps1.js";
-import"./index-4hek879p.js";
+} from "./index-5sn5w2mt.js";
+import"./index-jf2ya7r2.js";
+import"./index-qzdjd4ct.js";
+import"./index-y4vkyhvv.js";
+import"./index-3vta1tqa.js";
+import"./index-jhpa13zj.js";
+import"./index-ss469dec.js";
+import"./index-xmmzf150.js";
 import {
   CloudScript
-} from "./index-js368gk9.js";
+} from "./index-82jrh4hj.js";
 import {
   getLatestPackageVersion,
   getNpmRegistryUrl
-} from "./index-p3f4q532.js";
+} from "./index-4m0bphac.js";
 import {
   PackageScript
-} from "./index-azv0xjb5.js";
-import"./index-gmy45vz2.js";
-import"./index-ss469dec.js";
-import"./index-xhgtkekh.js";
+} from "./index-gcv8ncfh.js";
+import"./index-779ske1y.js";
 import {
   GlobalConfig
 } from "./index-0cj2zxbm.js";
 import {
   AgentScript
-} from "./index-gex7c8kd.js";
-import"./index-mssqn2sq.js";
-import"./index-2c3e2xh8.js";
-import"./index-7myvn0f0.js";
+} from "./index-eyyf2149.js";
+import"./index-774gcx29.js";
+import"./index-rxkpk7n4.js";
+import"./index-j37qq1f2.js";
 import {
   ApplicationScript
-} from "./index-5dw57f0d.js";
-import"./index-76rn3g2c.js";
+} from "./index-62955kn5.js";
 import {
   LibraryScript
-} from "./index-a1e0j63x.js";
+} from "./index-d43t8af2.js";
+import"./index-76rn3g2c.js";
 import {
   Exec,
   Workspace,
   command,
   runner,
   script
-} from "./index-6rhabeev.js";
+} from "./index-kdh76j26.js";
 import"./index-fgc8r6dj.js";
 import {
   ThemeValidator,
@@ -59,12 +59,13 @@ import {
   collectScopeRecipeSources,
   extractAgentBlock,
   renderScopeAgentBlock
-} from "./index-vg0sj9nc.js";
+} from "./index-z8ptfkzv.js";
 import"./index-mxvakhsm.js";
 import {
   collectRecipeSources,
   scanRecipes
 } from "./index-xys926f2.js";
+import"./index-1577bej2.js";
 import"./index-46tjzh6s.js";
 import {
   FileSys
@@ -77,6 +78,11 @@ import { Logger } from "akanjs/common";
 
 // pkgs/@akanjs/cli/workspace/workspace.runner.ts
 import path from "path";
+
+// pkgs/@akanjs/devkit/biomeBase.ts
+var biomeVersion = "2.4.4";
+
+// pkgs/@akanjs/cli/workspace/workspace.runner.ts
 var defaultWorkspacePeerDependencies = new Set([
   "@react-spring/web",
   "@use-gesture/react",
@@ -113,17 +119,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 +140,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 +164,7 @@ class WorkspaceRunner extends runner("workspace") {
       },
       devDependencies: {
         ...rootPackageJson.devDependencies,
-        "@biomejs/biome": latestBiomeVersion,
+        "@biomejs/biome": biomeVersion,
         "@types/bun": latestTypesBunVersion,
         "@akanjs/devkit": akanVersion,
         ...typescript ? { typescript } : {}
@@ -372,6 +372,8 @@ 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 } = {}) {

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.