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

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

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

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

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

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

@@ -1,19 +0,0 @@
----
-description: Lint rules that break the build, including several whose correct output looks wrong
-alwaysApply: true
----
-
-# Lint-Enforced Rules (These Break The Build)
-
-Enforced by `biome.json` and the Akan grit plugins registered in `biome.json`. Several of them produce output that looks wrong; do not "fix" it back.
-
-- **Never hand-order Tailwind classes.** `nursery/useSortedClasses` is an error and also sorts the string arguments to `cn()`. 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`, `common/**`, and `apps/akan/env/**` — `common/` and `env/` have no legal `Err` import path, so keep throwing code out of them.
-- **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 return a value from a store action** (`no-return-in-store-action.grit`). Every method of a `store(...)` class dispatches through `st.do.<action>()`, which is typed `void` / `Promise<void>`, so the value is unreachable — write it into state with `this.set({ ... })`. A bare `return;` guard, a `return` inside a nested callback, a getter, and a `static` helper are all still fine.
-- **Never redeclare a generated CRUD endpoint name** in `*.signal.ts` (`no-redeclare-predefined-endpoint.grit`).
-- **No deep imports past a barrel** (`no-deep-internal-import.grit`). Cross-module constant references such as `../map/map.constant` are the sanctioned exception.
-- **Server-component discipline** is enforced on `page/**`, `*.Unit.tsx`, and `*.View.tsx` (`no-import-client-functions.grit`, `no-use-client-in-server.grit`, `non-scalar-props-restricted.grit`).
-- `noArrayIndexKey` and `useExhaustiveDependencies` are **off** on purpose: `key={idx}` for embedded scalars and short dependency arrays are intentional, not oversights.

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

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

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

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

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

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

package/templates/workspaceRoot/.cursor/rules/repo-overview.mdc.template

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

@@ -1,99 +0,0 @@
----
-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`.
-- 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 `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 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.
-
-### Cascade Remove — the `cascade` option
-
-**The value names the direction, and getting it wrong is a data loss.** The two actions can sit on the same field
-shape, so `cascade` never means "related" — it means one of exactly these:
-
-- `removeRef` — *when I am removed, remove what this field points at.* Declared on the relation the owner holds:
-  `image: field(File, { cascade: "removeRef" })`, arrays included. Only a relation accepts it; a primitive, a bare
-  `ID`, and a scalar each fail the class build, because none of them names a document to remove.
-- `removeWith` — *when what this field points at is removed, remove me.* Declared on the child's own reference to
-  its owner, so the owner never learns about its children and a lib model can be extended by an app's. Three forms:
-  a relation (`agentSession: field(AgentSession, { cascade: "removeWith" })`), an id with `ref`
-  (`field(ID, { ref: "agentSession", cascade: "removeWith" })`), or a polymorphic id with `refPath`
-  (`field(ID, { refPath: "parentType", cascade: "removeWith" })`). An array, a Map, `ref` together with `refPath`,
-  and a field naming no owner each fail the class build.
-- **A `refPath` must name an `enumOf` field.** A free-form owner type is unknowable at build time, so every model's
-  removal would have to sweep the polymorphic table on the chance it is the owner. The enum names the candidates and
-  the reverse index reaches only them.
-- **A cascade goes through the target's service, never its model** — unless it provably makes no difference. The
-  service path is what runs the target's `_postRemove`, which is where a module puts the side effect the removal has
-  to carry (`FileService._postRemove` deletes the stored blob there).
-- **Bulk is decided at boot, per target model, for both directions.** When the target has no `remove` schema hook, no
-  `_pre`/`_postRemove` (its own or a lib's), no cascade of its own, and no children, one `removeManyByQuery` leaves
-  exactly the rows the loop would, so the framework takes it. Adding a `_postRemove` to that model silently flips it
-  back to one document at a time — the boot log (`info` summary, `verbose` per edge) is the only place that shows.
-- **The plan is sealed after every service is live**, so a `listenPost("remove")` registered in `onInit` still counts
-  and a `removeRef` target the app never mounted fails the boot rather than the first removal. An unmounted
-  `removeWith` owner fails the boot too; an unmounted `refPath` candidate only warns, since that list spans optional
-  modules by design.
-- **Nothing checks whether another document still references the same target.** `File` in particular is deduped by
-  `origin`, so two parents can share one row; declaring `removeRef` says the field owns its target exclusively, and
-  that judgement is the declaring model's to make.
-- Removal is soft (`removedAt`) but the storage delete a `_postRemove` performs is not — a cascade is not
-  restorable, and reviving the owner does not revive what went with it.
-- A `removeWith` declaration **auto-creates its index** (`{ removedAt, fk }`, or `{ removedAt, typeKey, fk }` when
-  polymorphic). Every non-base field lives in the `_doc` JSON column, so the lookup would otherwise scan the table
-  on every owner removal.
-- **Query-level removes fire no hooks and therefore no cascade.** `removeManyByQuery` / `updateManyByQuery`, the generated `remove<Filter>` / `update<Filter>`, and the facade's `removeById` / `updateById` stamp
-  `removedAt` in one atomic UPDATE, so nothing downstream runs. Remove one document at a time when it cascades.
-- Cascades are **idempotent**: `removedAt IS NULL` is ANDed into every query-level write, so a retry after a partial
-  failure re-stamps nothing. Cycles are cut by a visited set carried down the whole chain, with a depth cap of 16.

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

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

@@ -1,83 +0,0 @@
----
-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.
-
-## Guards And Transports
-
-- Guards run on both HTTP and websocket calls. Read the caller with `context.get<T>("account")` (`pkgs/akanjs/signal/signalContext.ts`) instead of branching on `getHttpContext()` / `getWebSocketContext()`.
-- Slice-level `guards` only reach the generated query/mutation endpoints. A `pubsub`/`message` endpoint is unguarded unless it declares its own `guards` in its signal option.
-- A pubsub room is authorized once, at subscribe. When a socket's credential changes the framework re-runs each room's guards and unsubscribes the ones that now fail (`SignalResolver.revalidateWsRooms`), so guards must stay side-effect free and safe to re-run.
-- A websocket carries its credential in the handshake snapshot on `ws.data` (`AppWsData`); clients that hold the token in memory send it with `fetch.setJwt(...)`, which forwards an auth frame over the socket.
-
-## Authorization Defaults
-
-- **Every `slice()` takes an explicit `{ guards: {…} }` second argument, and `root:` is always `Admin`.**
-- **Every custom `mutation` / `query` / `message` names its own `guards: [...]` array.** Never rely on the slice default. `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.
-- Services re-check ownership even when a guard already gated the call — two independent gates.
-- Guard class shape, fail-closed rules, and the `static name = "User"` requirement live in the srvkit adapters and guards rule.
-
-## Service Method Shape
-
-- 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.
-- `XInternal` → `XSlice` → `XEndpoint` are all declared even when empty, and `exec` is a one-liner delegating to the service.
-
-## Signal Body Types
-
-- `.body(...)` / `.param(...)` args accept `ConstantFieldTypeInput` only: scalars, model refs, or `enumOf(...)`.
-- Numbers must use `Int` or `Float` — `Number` is rejected (`pkgs/akanjs/signal/endpointInfo.ts`).
-- `Upload` is valid only inside a mutation flagged for file upload: `mutation([cnst.File], { fileUpload: true }).body("files", [Upload])` (see `libs/shared/lib/file/file.signal.ts`). It is not a model field type.
-
-## Reserved Endpoint Names
-
-- Auto-generated CRUD endpoints (e.g. `create<Model>`, `update<Model>`, `remove<Model>`) already exist for every model. Do not declare an `Endpoint`/`Slice` with a name that collides with them.
-- The service layer surfaces such a collision as a typecheck error, but the signal layer can pass sync/typecheck/build and fail only at runtime — so treat name collisions as errors regardless of whether the build is green.
-
-## Slices, Queries, and Hydration
-
-- A slice's `exec` returns a `QueryOf` (an opaque query descriptor, `pkgs/akanjs/constant/types.ts`); you **cannot** chain `.sort()`/`.limit()` on it.
-- Apply ordering/paging via the store `init` fetch option instead: `initX(..., { sort, page, limit })` (`pkgs/akanjs/fetch/fetchType/sliceFetch.type.ts`).
-- Generated list accessors like `listBy(...)` return `Promise<Doc[]>`. For a chainable builder (`.sort().skip().limit().select()`) use the model facade's `findMany`/`findOne` (`FindManyChain`, `pkgs/akanjs/document/into.ts`).
-- **Hydrated vs raw:** server queries return hydrated `cnst.<Model>` instances (with `set`/`save`/`refresh`); client fetch results are raw `GetStateObject` plain data (functions stripped, `pkgs/akanjs/base/types.ts`).
-
-## Text Search In A Filter — `q.search()`
-
-- Text search is a filter query node like any other: `bySearch: filter().arg("text", String).query((text, q) =>
-  q.search(text, { prefix: true }))`. The generated `listBySearch` / `countBySearch` / `queryBySearch` /
-  `insightBySearch` come for free — you do **not** need a slice to make search usable.
-- **Only add a search slice when the model's data is safe to enumerate.** A filter is server-side; a slice is a
-  client-callable endpoint, so on a model whose slice `get:` is `Public` a search slice hands anyone a way to walk the
-  table. Leave that decision to the mounting app.
-- `q.search()` compiles to a JOIN, not a WHERE fragment, so it **must sit at an AND position**. Nesting it under
-  `q.any()` or `q.not()` throws, and it is rejected in `updateOneByQuery` / `updateManyByQuery` — a query-level write
-  takes no join, so ignoring the node would silently widen the write to every other matching row.
-- Blank or whitespace-only input matches **nothing**. Never "fix" that into a passthrough: a passthrough turns a
-  search endpoint into a full listing.
-- Order by relevance with the built-in `relevance` sort key. It is an empty sort map, which the store reads as
-  "unspecified": score order when a search join is present, `createdAt` descending otherwise. That fallback is the
-  compiler's own, not a model-defined default — redefining `latest` on the model does not change it.
-- **A slice endpoint never reaches "unspecified".** The resolver fills `latest` before the query is built, so a
-  client asking for the score order has to name `relevance`; leaving `sort` off gets `latest`, not relevance.
-- Scope a search with `columns` (`q.search(text, { columns: ["title"] })`) and re-weight with `weights`, a tuple of
-  finite numbers positional over `["title", "desc", "tag", "filter"]`.
-
-## Service / Signal Injection
-
-- Injected dependencies resolve by field-name convention: a field named `<refName>Service` resolves to the service registered under `<refName>`, and `<refName>Signal` likewise (`pkgs/akanjs/service/injectInfo.ts`).
-- The `Service`/`Signal` suffix is required — the injector strips it to derive the registry lookup key. Name the field after the target refName plus the suffix, not arbitrarily.
-- Preference order inside a service: `service<srv.XService>()` for another module's service · `plug(AdapterClass)` or `plug(StorageAdaptorRole)` for an adapter · `use<T>()` only to reach an `option.ts`-registered legacy singleton · `env(...)` for config.
-- New adapters are `adapt("name" as const, ({ use, env, plug, memory }) => ({…}))` classes in `srvkit/` that self-register — do not add them to `lib/option.ts`. See the srvkit adapters and guards rule.

package/templates/workspaceRoot/.cursor/rules/srvkit-adapters-and-guards.mdc.template

@@ -1,50 +0,0 @@
----
-description: srvkit adapter (adapt/plug), guard, and error-handling conventions
-globs: apps/**/srvkit/**/*.ts,libs/**/srvkit/**/*.ts
-alwaysApply: false
----
-
-# Adapters — `adapt()` And `plug()`
-
-An injected singleton is an `adapt()` class in `srvkit/`. Write new adapters this way.
-
-```ts
-export class AdminNoti extends adapt("adminNoti" as const, ({ use, env, plug, memory }) => ({
-  discordApi: use<DiscordApi>(),
-  workspaceRoot: env(() => `~/build/${getEnv().environment}`),
-  masterHost: plug(MasterHost),
-  tokenMap: memory(Map, { of: String }),
-})) {}
-```
-
-- Inject it with `plug(TheClass)` from a service or from another adapter. Destructure only the injectors you use, and write the registration key `as const`.
-- **Do not register an `adapt()` class in `lib/option.ts`.** It self-registers, and `plug(Class)` uses the class itself as the token. `option.ts` is now only for legacy constructor-style adapters and for widening the options type.
-- `this.logger` is provided; never construct a `Logger` inside an `adapt()` class. Lifecycle work goes in `override async onInit()`.
-- `#private` is the house style here — the `#private` lint ban covers only `*.constant.ts`, `*.document.ts`, `*.service.ts`, and `*.store.ts`.
-- **`adapt()` is for singletons only.** A per-use value object stays a plain class you `new` at the call site. Ask whether there is exactly one per process that a service needs injected; if not, it is a plain class.
-- **Legacy shape — recognise it, do not copy it.** Plain classes with `constructor(options: XOptions)`, registered in `lib/option.ts` as `options.x ? new XApi(options.x) : null` and injected with `use<T>()`, still work. Migrate one to `adapt()` only when you are already changing it.
-- Preference order inside a service: `service<srv.XService>()` for another module's service · `plug(AdapterClass)` or `plug(StorageAdaptorRole)` for an adapter · `use<T>()` only to reach an `option.ts`-registered legacy singleton · `env(...)` for config.
-
-Conventions that hold for both shapes:
-
-- Route every remote call through one private `#api<T>(path, init?)` with `signal: AbortSignal.timeout(20_000)`.
-- Paginate with `for (let page = 1; ; page += 1)` broken by `if (pageItems.length < 100) break;`.
-- Resolve secrets as `process.env.X ?? options.x ?? deterministicGenerator(...)` **inside a function**, never at module scope.
-- Extend a function by appending an optional trailing parameter with a default, never by changing arity.
-- Parameters: up to three required primitives positional; optional flags in a trailing `{ … } = {}`; four or more parameters, or any two same-typed strings, in one named destructured object.
-- Release locks in `finally`. Load heavy optional dependencies through a module-level memoized promise (`sharpLoad ??= import("sharp")`).
-
-# Guards (`srvkit/guards.ts`)
-
-- Resource guards are `Can<Verb><Model>` classes that `implements Guard` with an `async canPass(context)`.
-- They **fail closed**: no resource named ⇒ `false`; a load that throws ⇒ `logger.warn` then `false`. Admin bypass goes first.
-- Keep `static name = "User";` on guard classes. `fetch` serializes guard names and the API explorer filters on them; it looks like dead code, and deleting it breaks the UI. Comment it so the next reader knows.
-- Guards ship with the library that owns the model and are imported by its own signals through the package path, so a mounting app inherits authorization and cannot forget it.
-- Services re-check ownership even when a guard already gated the call — two independent gates.
-- This file earns real comments: explain what would leak without each guard.
-
-# Error Placement
-
-- State-machine preconditions throw in `document.ts`; cross-document rules throw in `service.ts`; request-level policy belongs in signal guards.
-- Best-effort code returns a sentinel (`null`, `undefined`, `[0, 0]`, `{}`). There are no Result/Either wrappers.
-- `try/catch` is rare and always converts an exception into a decision, never swallows one. Guards catch → `logger.warn` → `return false`; adapters catch → `logger.error` → `return null`; UI uses `try/finally` to reset a spinner. A bodyless `catch {}` is acceptable only with a one-line reason.

package/templates/workspaceRoot/.cursor/rules/ssr-first.mdc.template

@@ -1,59 +0,0 @@
----
-description: SSR-first rendering rules — keep JSX on the server and justify every "use client"
-globs: apps/**/*.tsx,libs/**/*.tsx
-alwaysApply: false
----
-
-# SSR First — Server Rendering Is The Default
-
-Akan is SSR-first. A JSX element rendered on the server ships as HTML and costs nothing to hydrate; an element
-behind `"use client"` ships twice — as markup and as bundled JS that re-runs in the browser. The boundary question
-is not which file *may* be client, it is **how little** ends up on the client side.
-
-- **The default is server. `"use client"` is a cost you justify per component, not a habit.** A component earns the
-  directive only by using a client-only capability: a React hook, a JSX event handler, the store (`st.use.*` /
-  `st.do.*`), a browser global, or a client-only third-party package. Rendering markup, mapping over data, reading a
-  route param, and calling `l()` are server work — `usePage()` and `l()` never force a boundary.
-- The file role decides *where* the boundary sits (`Template`/`Zone`/`Util` are client, `Unit`/`View` are server);
-  it does not decide how much markup sits behind it. A `Zone` that hoards markup is still an SSR regression.
-- Measure with `akan quality ssr` (`--format json` for tooling). It reports the server render share per app and lib.
-  Treat **50% server share as the floor** and a falling share as a regression to justify or revert.
-
-## What `akan quality ssr` Flags
-
-- `akan.ssr.unnecessary-use-client` — the directive is there but nothing in the file needs it. Delete it.
-- `akan.ssr.client-static-component` — a component in a client file renders real markup with zero client-only
-  capability: pure server work sitting in the bundle.
-- `akan.ssr.client-static-markup` — a large subtree wraps one or two interactive touches. Split it.
-- `akan.ssr.client-mount-load` — a `useEffect(…, [])` loads server data the page could fetch first.
-- `akan.ssr.module-missing-server-view` — a module renders only from `Template`/`Zone`/`Util`, with no `Unit`/`View`.
-- `akan.ssr.template-client-state` — a `Template` holds form state in `useState` instead of the store.
-
-A third-party client package and the `ui/<Folder>/index_.tsx` + `lazy()` boundary both justify the directive and are
-not flagged. Interaction-driven `fetch.*` inside an `onClick` is not flagged either — only mount-time loads are.
-
-## Server-Side Implementation Playbook
-
-1. **Wrap the interaction, not the UI.** The smallest useful client component adds one behaviour and renders
-   `children` untouched, so the markup inside never reaches the bundle:
-   `export const ClickWrapper = ({ children, onPick }: ClickWrapperProps) => <div onClick={onPick}>{children}</div>;`
-2. **Split compound components so panels stay on the server.** A tab or accordion needs client state only for
-   *which* part is visible. `Tab` / `Tab.Menus` / `Tab.Menu` / `Tab.Panel` from `akanjs/ui` is the shape: only the
-   provider and menu hold state, and `<Tab.Panel>` renders children as-is, so a server `Unit`/`View` passed in stays
-   server-rendered. Never one client file with a mode `useState` and every panel body inlined.
-3. **Sync state instead of fetching it.** The page calls `fetch.initTaskInTodo()` / `fetch.viewTask(id)` and passes
-   the serializable result into a `Zone`; `Load.Units` / `Load.View` hydrate the store from it. Never a
-   `useEffect(…, [])` that fetches on mount.
-4. **Push the boundary down to the leaf that needs it.** A store-reading `Zone` holds zero markup and delegates to a
-   server `View`: `export const Self = () => <Task.View.General task={st.use.task()} />;`
-5. **Hand the promise across, not the awaited value.** `ClientInit` / `ClientView` are `PromiseOrObject<T>`, so a
-   page may pass an unawaited `fetch.initTaskInTodo()` and `Load.*` resolves it behind a skeleton.
-6. **Use named `ReactNode` slots, not just `children`.** `Layout.Navbar` takes `title`, `back`, `left`, `right`, and
-   `children`, so a client shell composes server content in five places.
-7. **Let the server do the derived work.** Display and predicate logic lives on `LightTask` (`isNew()`,
-   `canWrite(user?)`); enum→class lookups live in a module-scope `as const` map.
-8. **Gate auth on the server.** Check the session in `_layout.tsx` and redirect there, before any HTML is sent.
-9. **Prefer CSS over client state for pure visibility.** A `data-*` attribute plus `group-data-[…]` variants, or
-   `<details>`/`<summary>`, keeps both branches server-rendered.
-10. **Keep the heavy island out of the first load.** Put a large client-only widget behind the
-    `ui/<Folder>/index_.tsx` + `lazy()` pair.

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

@@ -1,16 +0,0 @@
----
-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/myapp/client`, and `@apps/myapp/server`.
-- Let Biome organize imports instead of manually reshuffling unrelated imports.
-- Namespace the generated barrels in backend `.ts` files: `import * as cnst from "../cnst"`, `* as db`, `* as srv`. Use `import type * as srv` in services so the runtime graph stays lazy, and a value import in signals.
-- In `.tsx` files use one flat named import from the package client path (`import { cnst, fetch, st, Task, usePage } from "@apps/myapp/client"`) — never a relative `../` import.
-- Never import a third-party package from a page, a barrel, or a module file; re-export it through a one-line shim in `base/`, `webkit/`, or `ui/` first.