@akanjs/cli 2.3.6-rc.0 → 2.3.6-rc.2

package/incrementalBuilder.proc.js

@@ -4136,8 +4136,11 @@ var shouldRestartBackendByDevPlan = (message) => {
     return null;
   if (message.devPlan.actions.includes("report-error"))
     return false;
+  if (message.devPlan.actions.includes("restart-builder"))
+    return false;
   return message.devPlan.actions.includes("restart-backend");
 };
+var shouldRestartBuilderByDevPlan = (message) => message.devPlan?.actions.includes("restart-builder") ?? false;
 var shouldRestartDevHostByDevPlan = (message) => message.devPlan?.actions.includes("restart-dev-host") ?? message.kinds.includes("config");
 var RESTART_ROLE_ORDER = ["server", "shared", "barrel", "config"];
 var generationValue = (generation) => generation ?? -1;
@@ -4557,6 +4560,14 @@ class AkanAppHost {
     this.#sendToBackend(message);
   }
   async#handleInvalidate(message) {
+    if (shouldRestartBuilderByDevPlan(message)) {
+      try {
+        await this.#restartDevChildren(message);
+      } catch (err) {
+        this.#recordDevHostRestartFailure(message, err);
+      }
+      return;
+    }
     if (shouldRestartDevHostByDevPlan(message)) {
       this.#recordDevHostRestartRequired(message);
       return;
@@ -4567,6 +4578,27 @@ class AkanAppHost {
     }
     this.#sendToBackend(message);
   }
+  async#restartDevChildren(message) {
+    const generation = message.devPlan?.generation ?? message.generation;
+    this.logger.warn(`[dev-host] recycling builder/backend for runtime metadata generation=${generation ?? "(unknown)"} files=${message.files.length}`);
+    if (this.#restartTimer) {
+      clearTimeout(this.#restartTimer);
+      this.#restartTimer = null;
+    }
+    if (this.#backendRecoveryTimer) {
+      clearTimeout(this.#backendRecoveryTimer);
+      this.#backendRecoveryTimer = null;
+    }
+    this.#pendingRestartReason = null;
+    this.#lastGoodFrontend = {};
+    this.#buildStatusByPhase.clear();
+    this.#pendingBuildStatusReplay = [];
+    await this.#stopBackend();
+    this.#stopBuilder();
+    await this.#backendGraph.refresh();
+    await this.#startBuilder();
+    this.#startBackend({ generation, files: message.files });
+  }
   #recordLastGood(message) {
     if (message.type === "pages-updated") {
       if (!shouldReplaceLastGoodMessage(this.#lastGoodFrontend.pages, message))
@@ -4596,6 +4628,20 @@ class AkanAppHost {
       this.#sendOrQueueBuildStatus(status);
     }
   }
+  #recordDevHostRestartFailure(message, err) {
+    const generation = message.devPlan?.generation ?? message.generation ?? this.#nextBackendBuildStatusGeneration();
+    const detail = err instanceof Error ? err.message : String(err);
+    this.logger.warn(`[dev-host] runtime metadata restart failed generation=${generation}: ${detail}`);
+    const status = {
+      generation,
+      phase: "scan",
+      ok: false,
+      files: message.files,
+      message: `Runtime metadata change requires restarting \`akan start\` to apply: ${detail}`
+    };
+    this.#recordBuildStatus(status);
+    this.#sendOrQueueBuildStatus(status);
+  }
   #recordBuildStatus(status) {
     const recovered = shouldMarkBuildPhaseRecovered(this.#buildStatusByPhase, status);
     this.#buildStatusByPhase.set(status.phase, status);
@@ -7509,6 +7555,8 @@ class DevChangePlanner {
       const fileRoles = this.#rolesForFile(file, { isGenerated: generatedSet.has(path25.resolve(file)), reasons });
       for (const role of fileRoles)
         roles.add(role);
+      if (reasons.has("runtime-metadata"))
+        actions.add("restart-builder");
       if (reasons.size > 0)
         reasonByFile[path25.resolve(file)] = [...reasons].sort();
     }
@@ -7561,6 +7609,9 @@ class DevChangePlanner {
       roles.add("shared");
       reasons.add("shared-path");
     }
+    if (isSource && this.#isRuntimeMetadataFile(parts, base)) {
+      reasons.add("runtime-metadata");
+    }
     if (roles.has("server") && roles.has("client")) {
       roles.delete("server");
       roles.delete("client");
@@ -7585,6 +7636,15 @@ class DevChangePlanner {
     const base = path25.basename(abs);
     return parts.includes("common") || SHARED_SUFFIXES2.some((suffix) => base.endsWith(suffix)) || RUNTIME_METADATA_BASENAMES2.has(base);
   }
+  #isRuntimeMetadataFile(parts, base) {
+    const parent = parts.at(-2);
+    if (parent === "lib" && RUNTIME_METADATA_BASENAMES2.has(base))
+      return true;
+    const libIndex = parts.lastIndexOf("lib");
+    if (libIndex < 0 || parts.length <= libIndex + 1)
+      return false;
+    return base.endsWith(".dictionary.ts") || base.endsWith(".signal.ts");
+  }
   #isBarrelFacetChild(parts) {
     if (parts.length < 4)
       return false;

package/index.js

@@ -4134,8 +4134,11 @@ var shouldRestartBackendByDevPlan = (message) => {
     return null;
   if (message.devPlan.actions.includes("report-error"))
     return false;
+  if (message.devPlan.actions.includes("restart-builder"))
+    return false;
   return message.devPlan.actions.includes("restart-backend");
 };
+var shouldRestartBuilderByDevPlan = (message) => message.devPlan?.actions.includes("restart-builder") ?? false;
 var shouldRestartDevHostByDevPlan = (message) => message.devPlan?.actions.includes("restart-dev-host") ?? message.kinds.includes("config");
 var RESTART_ROLE_ORDER = ["server", "shared", "barrel", "config"];
 var generationValue = (generation) => generation ?? -1;
@@ -4555,6 +4558,14 @@ class AkanAppHost {
     this.#sendToBackend(message);
   }
   async#handleInvalidate(message) {
+    if (shouldRestartBuilderByDevPlan(message)) {
+      try {
+        await this.#restartDevChildren(message);
+      } catch (err) {
+        this.#recordDevHostRestartFailure(message, err);
+      }
+      return;
+    }
     if (shouldRestartDevHostByDevPlan(message)) {
       this.#recordDevHostRestartRequired(message);
       return;
@@ -4565,6 +4576,27 @@ class AkanAppHost {
     }
     this.#sendToBackend(message);
   }
+  async#restartDevChildren(message) {
+    const generation = message.devPlan?.generation ?? message.generation;
+    this.logger.warn(`[dev-host] recycling builder/backend for runtime metadata generation=${generation ?? "(unknown)"} files=${message.files.length}`);
+    if (this.#restartTimer) {
+      clearTimeout(this.#restartTimer);
+      this.#restartTimer = null;
+    }
+    if (this.#backendRecoveryTimer) {
+      clearTimeout(this.#backendRecoveryTimer);
+      this.#backendRecoveryTimer = null;
+    }
+    this.#pendingRestartReason = null;
+    this.#lastGoodFrontend = {};
+    this.#buildStatusByPhase.clear();
+    this.#pendingBuildStatusReplay = [];
+    await this.#stopBackend();
+    this.#stopBuilder();
+    await this.#backendGraph.refresh();
+    await this.#startBuilder();
+    this.#startBackend({ generation, files: message.files });
+  }
   #recordLastGood(message) {
     if (message.type === "pages-updated") {
       if (!shouldReplaceLastGoodMessage(this.#lastGoodFrontend.pages, message))
@@ -4594,6 +4626,20 @@ class AkanAppHost {
       this.#sendOrQueueBuildStatus(status);
     }
   }
+  #recordDevHostRestartFailure(message, err) {
+    const generation = message.devPlan?.generation ?? message.generation ?? this.#nextBackendBuildStatusGeneration();
+    const detail = err instanceof Error ? err.message : String(err);
+    this.logger.warn(`[dev-host] runtime metadata restart failed generation=${generation}: ${detail}`);
+    const status = {
+      generation,
+      phase: "scan",
+      ok: false,
+      files: message.files,
+      message: `Runtime metadata change requires restarting \`akan start\` to apply: ${detail}`
+    };
+    this.#recordBuildStatus(status);
+    this.#sendOrQueueBuildStatus(status);
+  }
   #recordBuildStatus(status) {
     const recovered = shouldMarkBuildPhaseRecovered(this.#buildStatusByPhase, status);
     this.#buildStatusByPhase.set(status.phase, status);
@@ -7507,6 +7553,8 @@ class DevChangePlanner {
       const fileRoles = this.#rolesForFile(file, { isGenerated: generatedSet.has(path25.resolve(file)), reasons });
       for (const role of fileRoles)
         roles.add(role);
+      if (reasons.has("runtime-metadata"))
+        actions.add("restart-builder");
       if (reasons.size > 0)
         reasonByFile[path25.resolve(file)] = [...reasons].sort();
     }
@@ -7559,6 +7607,9 @@ class DevChangePlanner {
       roles.add("shared");
       reasons.add("shared-path");
     }
+    if (isSource && this.#isRuntimeMetadataFile(parts, base)) {
+      reasons.add("runtime-metadata");
+    }
     if (roles.has("server") && roles.has("client")) {
       roles.delete("server");
       roles.delete("client");
@@ -7583,6 +7634,15 @@ class DevChangePlanner {
     const base = path25.basename(abs);
     return parts.includes("common") || SHARED_SUFFIXES2.some((suffix) => base.endsWith(suffix)) || RUNTIME_METADATA_BASENAMES2.has(base);
   }
+  #isRuntimeMetadataFile(parts, base) {
+    const parent = parts.at(-2);
+    if (parent === "lib" && RUNTIME_METADATA_BASENAMES2.has(base))
+      return true;
+    const libIndex = parts.lastIndexOf("lib");
+    if (libIndex < 0 || parts.length <= libIndex + 1)
+      return false;
+    return base.endsWith(".dictionary.ts") || base.endsWith(".signal.ts");
+  }
   #isBarrelFacetChild(parts) {
     if (parts.length < 4)
       return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "2.3.6-rc.0",
+  "version": "2.3.6-rc.2",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -34,10 +34,10 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.3.6-rc.0",
+    "akanjs": "2.3.6-rc.2",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
-    "daisyui": "^5.5.20",
+    "daisyui": "5.5.23",
     "dayjs": "^1.11.20",
     "fontaine": "^0.8.0",
     "fonteditor-core": "^2.6.3",

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

@@ -0,0 +1,17 @@
+---
+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 `pkgs/akanjs/server/src/routeTree.tsx` and nearby routes for the expected pattern.

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

@@ -0,0 +1,19 @@
+---
+description: scanSync-enforced Akan app/lib layout and generated index conventions
+globs: apps/**/*,libs/**/*
+alwaysApply: false
+---
+
+# Akan Scan Conventions
+
+- `apps/<appName>` root may only contain these files: `akan.app.json`, `akan.config.ts`, `capacitor.config.ts`, `client.ts`, `main.ts`, `package.json`, `server.ts`, `tsconfig.json`.
+- `apps/<appName>` root may only contain these folders: `.akan`, `android`, `common`, `env`, `ios`, `lib`, `page`, `private`, `public`, `script`, `srvkit`, `ui`, `webkit`.
+- Do not add `apps/*/base`; place shared app utilities under `apps/*/common`.
+- `apps/*/lib` and `libs/*/lib` root files are limited to generated/support files: `cnst.ts`, `db.ts`, `dict.ts`, `option.ts`, `sig.ts`, `srv.ts`, `st.ts`, `useClient.ts`, `useServer.ts`.
+- Domain module folders are `lib/<model>` for database modules, `lib/_<service>` for service modules, and `lib/__scalar/<scalar>` for scalar modules.
+- Database module UI files are limited to `<Model>.Template.tsx`, `<Model>.Unit.tsx`, `<Model>.Util.tsx`, `<Model>.View.tsx`, and `<Model>.Zone.tsx`.
+- Service module UI files are limited to `<Service>.Util.tsx` and `<Service>.Zone.tsx`.
+- Scalar module UI files are limited to `<Scalar>.Template.tsx` and `<Scalar>.Unit.tsx`.
+- Module `*.test.ts`, `*.test.tsx`, `*.spec.ts`, and `*.spec.tsx` files are allowed.
+- `ui/index.ts`, `webkit/index.ts`, `srvkit/index.ts`, `common/index.ts`, and module `lib/**/index.ts` files are generated by scanSync; do not hand-edit or track them.
+- Generated facet indexes export only 1-depth files/folders with `export * from "./name";`.

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

@@ -0,0 +1,16 @@
+---
+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="akamir.com" AKAN_PUBLIC_APP_NAME=seon AKAN_PUBLIC_ENV=local AKAN_PUBLIC_OPERATION_MODE=local SERVER_MODE=federation AKAN_PUBLIC_BASE_PATHS=neul,apptest,seon 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

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

@@ -0,0 +1,17 @@
+---
+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, `Template`, `Zone`, and `Util` components are usually client components; `Unit` and `View` components are usually server components.
+- 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-style.mdc.template

@@ -0,0 +1,24 @@
+---
+description: Coding style conventions for classes and functions
+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`; `*.service.ts` files are the main exception where `private` methods are encouraged.
+- 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.
+
+# 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.

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

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

@@ -0,0 +1,12 @@
+---
+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/repo-overview.mdc.template

@@ -0,0 +1,17 @@
+---
+description: Akan.js monorepo structure and ownership conventions
+alwaysApply: true
+---
+
+# Repo Overview
+
+- Akan.js is a full-stack TypeScript framework for building all-stack applications at once.
+- Write one line and deploy across web, app, server, database, and infrastructure.
+- Akan prioritizes actual business code by abstracting technical implementation details as much as possible.
+- The goal is minimal code, high performance, and type-safe services that can deploy to web, mobile, server, and DB infrastructure together.
+- This is a Bun-first Akan.js monorepo.
+- Main top-level areas are `apps/`, `libs/`, `pkgs/`, and `infra/`.
+- `apps/<app>` contains app-level pages, domain code, UI, env files, and `akan.config.ts`.
+- `libs/*` contains shared domain and utility libraries.
+- `pkgs/akanjs/*` contains framework, runtime, and tooling facets published through the single `akanjs` package. Prefer extending existing Akan facets before adding new framework-level patterns.
+- `infra/` contains Helm, deployment templates, edge configs, and Jenkins env/secret scripts.

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

@@ -0,0 +1,14 @@
+---
+description: Akan scalar and constant model conventions
+globs: **/*.constant.ts
+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.
+- 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.

package/templates/workspaceRoot/.cursor/rules/secrets-and-env.mdc.template

@@ -0,0 +1,13 @@
+---
+description: Secret and environment file safety conventions
+globs: .env,**/.env,**/*.env,infra/**/*,**/*secret*,**/*Secret*,**/*credential*,**/*Credential*
+alwaysApply: false
+---
+
+# Secrets And Env Safety
+
+- Never print, summarize, commit, or expose real secret values, credentials, tokens, private keys, or `.env` contents.
+- If env keys are needed for documentation, list only key names and example placeholders, not live values.
+- Preserve the existing env/secret flow through root scripts such as `bun run downloadEnv`, `bun run uploadEnv`, `bun run downloadSecret`, and `bun run uploadSecret`.
+- When editing infra env or secret scripts, keep Jenkins and deployment assumptions intact unless the task explicitly asks to change them.
+- Treat generated env/secret artifacts as sensitive even when they are not named `.env`.

package/templates/workspaceRoot/.cursor/rules/service-signal-conventions.mdc.template

@@ -0,0 +1,14 @@
+---
+description: Akan service, signal, and adapter conventions
+globs: apps/**/lib/**/*.{service,signal}.ts,libs/**/lib/**/*.{service,signal}.ts,apps/**/server/**/*.ts,libs/**/server/**/*.ts
+alwaysApply: false
+---
+
+# Service And Signal Conventions
+
+- Keep domain business operations in `.service.ts` classes built with `serve(...)`.
+- Keep execution contracts and triggers in `.signal.ts` classes built with `internal(...)`, `slice(...)`, and `endpoint(...)`.
+- Use `Internal` for internal triggers such as init, interval, cron, or queue jobs.
+- Use `Slice` for typed data views that feed client stores and zones; keep each slice focused on one purpose.
+- Use `Endpoint` for query and mutation contracts exposed to callers.
+- Connect external APIs or infrastructure through adapters, usually under `srvkit/`, and inject them into services instead of importing vendor clients directly into domain logic.

package/templates/workspaceRoot/.cursor/rules/typescript-imports.mdc.template

@@ -0,0 +1,13 @@
+---
+description: TypeScript and import conventions
+globs: **/*.{ts,tsx}
+alwaysApply: false
+---
+
+# TypeScript And Imports
+
+- Use Bun and ESM assumptions from the root `tsconfig.json`.
+- Prefer path aliases over deep relative imports when crossing package boundaries.
+- Use `akanjs/*` for framework facets, `@apps/*` for apps, `@libs/*` for shared libs, and `@contract/*` for contract code.
+- Respect existing client/server entrypoints such as `@libs/shared/client`, `@libs/shared/server`, `@apps/puffinplace/client`, and `@apps/puffinplace/server`.
+- Let Biome organize imports instead of manually reshuffling unrelated imports.

package/templates/workspaceRoot/AGENTS.md.template

@@ -47,23 +47,26 @@ Use the local module shape before adding a new abstraction.
 - `<model>.signal.ts` defines typed endpoint contracts.
 - `<model>.document.ts` owns persistence and document queries.
 - `<model>.service.ts` owns business logic.
-- `<model>.store.ts` owns domain state and actions.
-- `<Model>.Template.tsx` owns form-oriented UI. Client components, with 'use client'.
+- `<model>.store.ts` owns reusable workflow state and actions that span loading, selections, messages, or multi-step client actions. Consume stores through generated `st.use.*` state and `st.do.*` actions.
+- `<Model>.Template.tsx` owns form-oriented UI, including local form inputs and submit/import interactions. Client components, with 'use client'.
 - `<Model>.Unit.tsx` owns list/item UI. Server components, no 'use client'.
 - `<Model>.View.tsx` owns detail UI. Server components, no 'use client'.
-- `<Model>.Zone.tsx` owns page/container integration. Client components, with 'use client'.
-- `<model>.Util.tsx` owns small module UI helpers. Client components, with 'use client'.
+- `<Model>.Zone.tsx` owns page/container integration and interactive loading or action flows that need client state. Client components, with 'use client'.
+- `<model>.Util.tsx` owns small module UI helpers, including buttons, import actions, and client-side navigation such as `router.push`. Client components, with 'use client'.
 
 ## Agent Workflow
 
 1. Read the nearby module and convention before creating files. If `*.abstract.md` exists, read it first.
 2. Put new files in the established Akan location instead of adding parallel architecture.
 3. Prefer CLI generation commands for new apps, libraries, modules, scalars, pages, and generated references.
-4. Keep server-only logic out of client surfaces and client-only code out of server imports.
-5. Treat `AKAN_PUBLIC_*` env vars as public. Never put secrets in them.
-6. Add or update tests when behavior, contracts, or CLI output changes.
-7. Update `*.abstract.md` when business invariants, workflows, or public behavior change.
-8. Run the smallest relevant verification command after changes.
+4. Keep page and layout files server-oriented: route-level `usePage`, headers, static layout, and `akanjs/ui` `Tab` composition belong there.
+5. Put interactive loading, submit/import actions, local form state, and `router.push` in client `Util`, `Template`, or `Zone` components.
+6. Prefer `Tab` for static mode selection instead of extra `useState`; render one focused client component inside each `Tab.Panel`.
+7. Keep server-only logic out of client surfaces and client-only code out of server imports.
+8. Treat `AKAN_PUBLIC_*` env vars as public. Never put secrets in them.
+9. Add or update tests when behavior, contracts, or CLI output changes.
+10. Update `*.abstract.md` when business invariants, workflows, or public behavior change.
+11. Run the smallest relevant verification command after changes.
 
 ## Common Commands