@akanjs/cli 2.3.1-rc.3 → 2.3.1-rc.4

package/templates/workspaceRoot/AGENTS.md.template

@@ -7,7 +7,7 @@ the framework generate the repeated surfaces.
 
 - `apps/<app>` contains application pages, app UI, app domain modules, env files, and `akan.config.ts`.
 - `libs/<lib>` contains shared domain and utility code reused by apps.
-- `apps/<app>/page` contains file-routed pages. Index pages use `_index.tsx`; nested layouts use `_layout.tsx`.
+- `apps/<app>/page` contains server-side file-routed pages. Index pages use `_index.tsx`; nested layouts use `_layout.tsx`. routeName.tsx becomes /routeName and [modelId].tsx becomes /[modelId].
 - `apps/<app>/lib/<model>` contains database-backed domain modules.
 - `apps/<app>/lib/_<service>` contains service modules that are not database document models.
 - `apps/<app>/lib/__scalar/<scalar>` contains reusable scalar/value types.
@@ -20,10 +20,6 @@ Do not hand-edit generated Akan files. Regenerate them through Akan scan, lint,
 CLI command instead.
 
 Common generated files include:
-
-- `apps/*/akan.app.json`
-- `libs/*/akan.lib.json`
-- `pkgs/*/akan.pkg.json`
 - `apps/*/client.ts`
 - `apps/*/server.ts`
 - `apps/*/lib/cnst.ts`
@@ -34,11 +30,11 @@ Common generated files include:
 - `apps/*/lib/sig.ts`
 - `apps/*/lib/useClient.ts`
 - `apps/*/lib/useServer.ts`
+- `apps/*/lib/*/index.ts`
 - `apps/*/ui/index.ts`
 - `apps/*/webkit/index.ts`
 - `apps/*/srvkit/index.ts`
 - `apps/*/common/index.ts`
-- module `index.ts` and `index.tsx` files generated by scan
 
 ## Domain Module Responsibilities
 
@@ -52,11 +48,11 @@ Use the local module shape before adding a new abstraction.
 - `<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.
-- `<Model>.Unit.tsx` owns list/item UI.
-- `<Model>.View.tsx` owns detail UI.
-- `<Model>.Zone.tsx` owns page/container integration.
-- `<model>.Util.tsx` owns small module UI helpers.
+- `<Model>.Template.tsx` owns form-oriented UI. 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'.
 
 ## Agent Workflow
 
@@ -73,12 +69,43 @@ Use the local module shape before adding a new abstraction.
 
 Run commands from the workspace root unless a task says otherwise.
 
+### Module Addition Workflow
+
+When adding a new database-backed domain module (e.g., product, user):
+
+```bash
+# 1. Scaffold the module with Akan CLI (creates constant, service, signal, store, document files)
+akan create-module <module-name> --app <%= appName %>
+
+# 2. Start dev server with HMR and type checking at http://localhost:8282
+akan start <%= appName %>
+```
+
+### Change Verification Workflow
+
+After any code change, run these in order:
+
 ```bash
-akan start <app-name>
-akan build <app-name>
-akan test <app-or-lib-or-pkg>
-akan lint <app-or-lib-or-pkg>
-akan lint-all
+# 1. Fast lint check — Akan.js conventions and Biome rules
+akan lint <%= appName %>
+
+# 2. Type-only check — catches server/client boundary violations and import errors
+akan typecheck <%= appName %>
+
+# 3. Test — Run the test code (lib/*/*.signal.test.ts or others)
+akan test <%= appName %>
+
+# 4. Full production build — bundles the app, runs all type/lint checks combined
+akan build <%= appName %>
+```
+
+### Other Frequently Used Commands
+
+```bash
+akan create-scalar <scalar-name> --app <%= appName %>    # Add a scalar module (lib/__scalar/<scalar-name>/)
+akan create-service <service-name> --app <%= appName %>       # Add a service module (lib/_<service-name>/)
+akan test <%= appName %>                             # Run the test code (lib/*/*.signal.test.ts or others)
+akan lint <%= appName %>                             # Lint only (no typecheck)
 ```
 
 For the default generated app, start with:
@@ -86,3 +113,430 @@ For the default generated app, start with:
 ```bash
 akan start <%= appName %>
 ```
+
+### The Essential Loop: Edit → Scan → Check
+
+Almost every Akan.js change follows this pattern. **Missing step 2 is the #1 cause of agent confusion.**
+
+1. **Edit** — Create or modify source files in the correct location.
+   ```
+   vi apps/<%= appName %>/lib/task/task.constant.ts  # e.g., add a priority field
+   ```
+
+2. **Scan** — Regenerate barrel files so Akan discovers your change. This regenerates:
+   `cnst.ts`, `db.ts`, `srv.ts`, `sig.ts`, `st.ts`, `dict.ts`, `useClient.ts`, `useServer.ts`,
+   `ui/index.ts`, `webkit/index.ts`, `srvkit/index.ts`, `common/index.ts`, and all module `index.ts` files.
+   ```
+   akan scan app <%= appName %>
+   ```
+   **CRITICAL**: Scan after EVERY file add, delete, or rename. Without scan, other modules cannot
+   `import * as cnst from "../cnst"` and find your new model.
+
+3. **Check** — Verify your change compiles and lints.
+   ```
+   akan start <%= appName %>   # dev server with live feedback (preferred)
+   akan lint <%= appName %>    # quick lint-only check
+   ```
+
+   If `akan scan` gives errors, try:
+   - `akan build <%= appName %>` — full rebuild catches type errors scan may miss
+   - Re-run `akan create-model <name> --app <%= appName %>` if the scaffold is corrupted
+
+## Quick Decision Matrix — "Where do I put this code?"
+
+| You want to... | Create in... | Run after... |
+|----------------|-------------|--------------|
+| Define a new database-backed noun (e.g., User, Product) | `lib/<model>/` → constant, document, service, signal, store, dictionary, abstract | `akan scan app <name>` |
+| Add a pure workflow / integration (e.g., Payment, Email) | `lib/_<service>/` → service, signal, store, dictionary, abstract | `akan scan app <name>` |
+| Add a reusable value type (e.g., Address, WorkHistory) | `lib/__scalar/<type>/` → constant, dictionary, abstract | `akan scan app <name>` |
+| Create a new URL-visitable page | `page/` → `_index.tsx`, `_layout.tsx`, `[param]/_index.tsx` | Rebuild (akan start auto-detects) |
+| Add a form or reusable UI component | `ui/` → PascalCase `.tsx` with `"use client"` if needed | `akan scan app <name>` |
+| Add a React hook or browser helper | `webkit/` → camelCase `.ts` with `"use client"` | `akan scan app <name>` |
+| Add a server-only guard, middleware, or adaptor | `srvkit/` → PascalCase `.ts` | `akan scan app <name>` |
+| Add a pure helper (no DOM, no server API) | `common/` → camelCase `.ts` | `akan scan app <name>` |
+
+## Anti-patterns: Never Do These
+
+| Don't | Why | Do Instead |
+|-------|-----|------------|
+| Edit `cnst.ts`, `db.ts`, `srv.ts`, `sig.ts`, `st.ts`, `dict.ts`, `useClient.ts`, `useServer.ts`, or any `index.ts` | These are **generated by `akan scan`**. Your changes will be overwritten. | Edit the source files in `lib/<model>/` directories and run `akan scan` |
+| Create a file without running scan | New files won't appear in barrel exports. Imports like `import * as cnst from "../cnst"` will fail. | Always run `akan scan app <name>` after creating, renaming, or deleting any module file |
+| Use JS `#private` methods in service classes | Akan's build system rejects `#private`. Use TypeScript `private` keyword instead. | `private _methodName()` — never `#_methodName()` |
+| Use `console.log()` | Biome lint forbids `console.log`. Only `console.error`, `console.info`, `console.warn` are allowed. | Use one of the three allowed console methods |
+| Import server APIs (`fs`, `Bun`, `process.env`) in `ui/`, `webkit/`, or `common/` | Server-only imports in client code cause build failures. | Keep server dependencies in `lib/`, `srvkit/`, or `private/` only |
+| Skip running `akan scan` after deleting a file | Deleted files remain referenced in barrel exports, causing import errors everywhere. | Run `akan scan app <name>` after every file add, remove, or rename |
+| Use "use client" or `useState`/`useEffect` in pages/*.tsx, *.Unit.tsx, and *.View.tsx files | Server code cannot use React hooks. Wrap in a separate `"use client"` component. | Move hook logic to `webkit/` or a `"use client"` UI component |
+| Use `<a>` tag for internal navigation between pages | Akan.js uses `<Link>` from `akanjs/ui` for client-side navigation — avoids full page reloads. | `import { Link } from "akanjs/ui"` and use `<Link href="/task">...</Link>` |
+
+## Generated File Tracker (Quick Reference)
+
+These files are regenerated by `akan scan` and overwritten on every scan. **Do not hand-edit them.**
+
+| File | Generated From | Purpose |
+|------|---------------|---------|
+| `apps/*/lib/cnst.ts` | All `*/lib/*/**.constant.ts` | Barrel for all constants |
+| `apps/*/lib/dict.ts` | All `*/lib/*/**.dictionary.ts` | Barrel for all dictionaries |
+| `apps/*/lib/db.ts` | All `*/lib/<model>/*.document.ts` | Barrel for all document models |
+| `apps/*/lib/srv.ts` | All `*/lib/**/**.service.ts` | Barrel for all services |
+| `apps/*/lib/sig.ts` | All `*/lib/**/**.signal.ts` | Barrel for all signals |
+| `apps/*/lib/st.ts` | All `*/lib/**/**.store.ts` | Barrel for all stores |
+| `apps/*/lib/useClient.ts` | Client-safe module re-exports | Client-side import entry |
+| `apps/*/lib/useServer.ts` | Server-only module re-exports | Server-side import entry |
+| `apps/*/client.ts` | App-wide client barrel | The `fetch` and `st` instances |
+| `apps/*/server.ts` | App-wide server barrel | Server-side service resolution |
+| `*/lib/*/index.ts` | Per-module barrel | Module-level re-exports |
+| `*/ui/index.ts` | All UI component files | UI barrel |
+| `*/webkit/index.ts` | All webkit files | Webkit barrel |
+| `*/srvkit/index.ts` | All srvkit files | Srvkit barrel |
+| `*/common/index.ts` | All common files | Common barrel |
+
+## Workflow Recipes
+
+Concrete step-by-step recipes for the most frequent Akan.js changes. Each recipe shows which files to edit
+and in what order. The code examples reference the `task` module in `apps/<%= appName %>/lib/task/` as a
+template; replace `task` with your model name and `Task` with your PascalCase model name.
+
+When editing a file, always read the existing content first. Only change the relevant sections — do not
+rewrite the entire file.
+
+---
+
+### Recipe 1: Adding a New Field to a Model
+
+**Files to edit (in order):** `constant.ts` → `dictionary.ts` → `Template.tsx` → `Unit.tsx` → `akan scan`
+
+```typescript
+// 1. apps/<app>/lib/<model>/<model>.constant.ts
+// Add field to the Input class. Use field() builder with optional defaults
+export class TaskInput extends via((field) => ({
+  title: field(String),
+  priority: field(TaskPriority, { default: "medium" }),  // NEW FIELD
+})) {}
+
+// If the new field should appear in list views, also add it to LightTask:
+export class LightTask extends via(TaskObject, ["title", "priority", "status", "due"] as const, () => ({})) {}
+
+// 2. apps/<app>/lib/<model>/<model>.dictionary.ts
+// Add i18n labels for the new field (and its enum values if any)
+.model<Task>((t) => ({
+  priority: t(["Priority", "우선순위"]),
+}))
+.enum<TaskPriority>("taskPriority", (t) => ({
+  low: t(["Low", "낮음"]),
+  medium: t(["Medium", "보통"]),
+  high: t(["High", "높음"]),
+}))
+
+// 3. apps/<app>/lib/<model>/<Model>.Template.tsx
+// Add a form field using st.do.setXxxOnYyy (auto-generated setter)
+const form = st.use.taskForm();
+<Field.ToggleSelect
+  label={l("task.priority")}
+  items={cnst.TaskPriority}
+  value={form.priority}
+  onChange={st.do.setPriorityOnTask}
+/>
+
+// 4. apps/<app>/lib/<model>/<Model>.Unit.tsx
+// Display the new field in card/list views
+<span className={clsx("badge badge-sm", {
+  "badge-error": task.priority === "high",
+  "badge-warning": task.priority === "medium",
+  "badge-ghost": task.priority === "low",
+})}>{task.priority}</span>
+
+// 5. Regenerate barrels
+// akan scan app <name>
+```
+
+---
+
+### Recipe 2: Injecting a Dependency into a Service
+
+Two patterns: injecting an **adapter** (external client) or injecting another **module's service**.
+
+**A. Adapter injection via `use<>()` (for external clients / global singletons)**
+
+```typescript
+// 1. Create the adapter class in apps/<app>/srvkit/
+// apps/<app>/srvkit/EmailClient.ts
+export class EmailClient {
+  constructor(readonly apiKey: string) {}
+  async send(opts: { to: string; subject: string; body: string }) { /* ... */ }
+}
+
+// 2. Register in apps/<app>/lib/option.ts
+export const option = new AkanOption()
+  .use((options) => ({
+    emailClient: new EmailClient(options.mailerApiKey),
+  }));
+
+// 3. Inject via use<>() in <model>.service.ts
+export class TaskService extends serve(db.task, ({ use }) => ({
+  emailClient: use<EmailClient>(),
+})) {
+  async _postCreate(task: cnst.Task) {
+    await this.emailClient.send({ to: "...", subject: "Task Created", body: `Task "${task.title}" created.` });
+  }
+}
+```
+
+**B. Cross-module service injection via `service<>()` (for other Akan services)**
+
+```typescript
+// In <model>.service.ts — inject another module's service
+import * as srv from "../srv";
+
+export class TaskService extends serve(db.task, ({ service }) => ({
+  notiService: service<srv.NotiService>(),
+})) {
+  async _postCreate(task: cnst.Task) {
+    await this.notiService.send("info", `Task "${task.title}" created`);
+  }
+}
+```
+
+---
+
+### Recipe 3: Creating and Using a Slice
+
+A Slice is a named, filtered data view. Add file entries and connect from a page.
+
+```typescript
+// 1. apps/<app>/lib/<model>/<model>.signal.ts — Define the slice
+export class TaskSlice extends slice(srv.task, (init) => ({
+  inTodo: init()
+    .search("statuses", [cnst.TaskStatus])
+    .exec(function (statuses?) {
+      return this.taskService.queryByStatuses(statuses ?? ["todo", "inProgress"]);
+    }),
+})) {}
+
+// 2. apps/<app>/lib/<model>/<model>.document.ts — Add query filter for slice
+export class TaskFilter extends from(cnst.Task, (filter) => ({
+  query: {
+    byStatuses: filter()
+      .arg("statuses", [cnst.TaskStatus])
+      .query((statuses) => ({ status: { $in: statuses } })),
+  },
+})) {}
+
+// 3. apps/<app>/lib/<model>/<model>.dictionary.ts — Slice labels
+.slice<TaskSlice>((fn) => ({
+  inTodo: fn(["Tasks In Todo", "할 일"]).arg((t) => ({
+    statuses: t(["Statuses", "상태"]),
+  })),
+}))
+
+// 4. In page — Init slice from loader, render with Zone
+loader={async () => {
+  const { taskInitInTodo } = await fetch.initTaskInTodo();
+  return { taskInitInTodo };
+}}
+render={({ data: { taskInitInTodo } }) => (
+  <Task.Zone.Card init={taskInitInTodo} sliceName="taskInTodo" />
+)}
+```
+
+The slice name in code uses camelCase (`inTodo`). In dictionary and components it becomes `"taskInTodo"`.
+
+---
+
+### Recipe 4: Creating a Mutation Endpoint (with Status Workflow)
+
+**Files to edit (in order):** `document.ts` → `service.ts` → `signal.ts` → `dictionary.ts` → `store.ts` → `Util.tsx`
+
+```typescript
+// 1. <model>.document.ts — Document chain method with state validation
+export class TaskDocument extends by(cnst.Task) {
+  start() {
+    if (this.status !== "todo") throw new Err("task.error.cannotStartFromNonTodo");
+    this.status = "inProgress";
+    return this;  // Return this for chaining: task.start().save()
+  }
+}
+
+// 2. <model>.service.ts — Service method wrapping document
+async startTask(taskId: string) {
+  const task = await this.getTask(taskId);
+  return task.start().save();
+}
+
+// 3. <model>.signal.ts — Mutation endpoint
+export class TaskEndpoint extends endpoint(srv.task, ({ mutation }) => ({
+  startTask: mutation(cnst.Task)
+    .param("taskId", String)
+    .exec(async function (taskId) {
+      return await this.taskService.startTask(taskId);
+    }),
+})) {}
+
+// 4. <model>.dictionary.ts — Endpoint + error labels
+.endpoint<TaskEndpoint>((fn) => ({
+  startTask: fn(["Start Task", "작업시작"])
+    .arg((t) => ({ taskId: t(["Task ID", "할 일 ID"]) })),
+}))
+.error({
+  cannotStartFromNonTodo: ["Task can only start from todo status", "할 일 상태에서만 시작 가능"],
+})
+
+// 5. <model>.store.ts — Client-side action with toast feedback
+async startTask(taskId: string) {
+  msg.loading("task.startTaskLoading", { key: "startTask" });
+  const task = await fetch.startTask(taskId);
+  this.setTask(task);  // Auto-generated: updates task state in store
+  msg.success("task.startTaskSuccess", { key: "startTask" });
+}
+
+// 6. <Model>.Util.tsx — Reusable button component
+export const Start = ({ taskId }: { taskId: string }) => (
+  <button className="btn btn-xs btn-primary" onClick={() => st.do.startTask(taskId)}>
+    Start
+  </button>
+);
+```
+
+---
+
+### Recipe 5: Internal Triggers — Interval & Cron
+
+Server-side background jobs. Defined in `internal()` signal, implemented in service.
+
+```typescript
+// 1. <model>.signal.ts — Define triggers
+export class TaskInternal extends internal(srv.task, ({ interval, cron }) => ({
+  cleanupStaleTasks: interval(10000).exec(async function () {
+    await this.taskService.cleanupStaleTasks();
+  }),
+
+  dailyDigest: cron("0 0 * * *").exec(async function () {
+    await this.taskService.sendDailyDigest();
+  }),
+})) {}
+
+// 2. <model>.service.ts — Implement the logic
+async cleanupStaleTasks() {
+  const weekAgo = dayjs().subtract(7, "day").toDate();
+  const stale = await this.taskModel.listDueBefore(weekAgo);
+  for (const task of stale) {
+    await task.remove();
+  }
+}
+```
+
+**Available trigger types:**
+- `interval(ms)` — runs repeatedly at the given interval
+- `cron("min hour dom month dow")` — runs on a schedule
+- `initialize()` — runs once on service startup
+- `process(Return).msg(Type)` — message queue consumer
+
+---
+
+### Recipe 6: Creating an Insight (Aggregation / Dashboard Stats)
+
+Insights display aggregated statistics across model data.
+
+```typescript
+// 1. <model>.constant.ts — Insight class with accumulate rules
+export class TaskInsight extends via(Task, (field) => ({
+  totalCount: field(Int, { default: 0, accumulate: {} }),
+  completedCount: field(Int, { default: 0, accumulate: { status: "completed" } }),
+})) {}
+
+// 2. <model>.dictionary.ts — Insight field labels
+.insight<TaskInsight>((t) => ({
+  totalCount: t(["Total Tasks", "전체 할 일"]),
+  completedCount: t(["Completed", "완료됨"]),
+}))
+
+// 3. <Model>.View.tsx — Display component consuming an Insight model
+export const Stats = ({ taskInsight }: { taskInsight: cnst.TaskInsight }) => (
+  <div className="grid grid-cols-2 gap-4">
+    <div className="stat rounded-lg border border-base-content/10 bg-base-100 p-4">
+      <div className="stat-title text-base-content/60">{l("task.totalCount")}</div>
+      <div className="stat-value text-primary">{taskInsight.totalCount}</div>
+    </div>
+    <div className="stat rounded-lg border border-base-content/10 bg-base-100 p-4">
+      <div className="stat-title text-base-content/60">{l("task.completedCount")}</div>
+      <div className="stat-value text-success">{taskInsight.completedCount}</div>
+    </div>
+  </div>
+);
+
+// 4. <Model>.Zone.tsx — Mount in page via Load.Insight bound to a slice
+export const Insight = ({ sliceName }: { sliceName: string }) => {
+  const insight = st.slice[sliceName].use.taskInsight();
+  if (!insight) return null;
+  return <Task.View.Stats taskInsight={insight} />;
+};
+```
+
+---
+
+### Data Flow Summary
+
+For each business question, follow this chain:
+
+| Question | File Pattern |
+|----------|-------------|
+| What fields does it have? | `constant.ts` — `via()` layers: Input → Object → Light → Model → Insight |
+| How is it stored/searched? | `document.ts` — `from()` filters + `by()` document methods + `into()` model |
+| What business rule should run? | `service.ts` — `serve()` with DI (`use`, `service`, `plug`, `env`, `memory`) |
+| What should a page call? | `signal.ts` — `internal()` (jobs), `endpoint()` (APIs), `slice()` (data views) |
+| What client state is shared? | `store.ts` — `store()` with auto-generated form/insight state + custom actions |
+| What should users see? | `View.tsx` + `Zone.tsx` (detail/container), `Template.tsx` (forms), `Unit.tsx` (cards), `Util.tsx` (buttons) |
+
+## Auto-Generated API Reference
+
+akan scan automatically generates APIs across all layers. Only write custom logic — never hand-write what the framework generates.
+
+### Signal — Endpoint Auto-Generation
+
+| Auto-Generated | Signature | Description |
+|---------------|-----------|-------------|
+| `view[Model](id)` | `fetch.viewTask(id)` | Fetch single model for detail view |
+| `edit[Model](id)` | `fetch.editTask(id)` | Fetch model for edit view |
+| `merge[Model](id, data)` | `fetch.mergeTask(data)` | Create (no id) or update (with id) model |
+| `[model]List[Suffix](args, skip, limit, sort)` | `fetch.taskListInTodo(args)` | Paginated list from slice filter |
+| `[model]Insight[Suffix](args)` | `fetch.taskInsightInTodo(args)` | Aggregated insight from slice query |
+| `init[Model][Suffix](args)` | `fetch.initTaskInTodo(args)` | Initialize slice with list + insight |
+
+**Rule**: Only define `query()`, `mutation()`, `message()`, `pubsub()` endpoints manually when the endpoint needs custom business logic. Standard CRUD is already auto-generated.
+
+### Service — CRUD & Query Auto-Generation
+
+| Auto-Generated | Description |
+|---------------|-------------|
+| `this.<model>Model` | Auto-injected model adaptor |
+| `get<Model>(id)`, `load<Model>(id)` | Single document lookup |
+| `createModel(data)`, `updateModel(id, data)`, `removeModel(id)` | CRUD operations |
+| `list<Query>(args)`, `find<Query>(args)`, `pick<Query>(args)` | Filter-based queries |
+| `exists<Query>(args)`, `count<Query>(args)`, `insight<Query>(args)` | Filter-based helpers |
+| `_preCreate`, `_postCreate`, `_preUpdate`, `_postUpdate`, `_preRemove`, `_postRemove` | Lifecycle hooks (override to add logic) |
+
+**Rule**: Use `_preCreate`/`_postCreate` lifecycle hooks for side effects (e.g., push workHistory entries). Write custom service methods only for multi-model orchestration.
+
+### Store — State & Action Auto-Generation
+
+| Auto-Generated | Description |
+|---------------|-------------|
+| `[model]` (cached full model), `[model]Loading`, `[model]Form`, `[model]Modal` | Base model states |
+| `create[Model](data)`, `update[Model](id, data)`, `remove[Model](id)` | CRUD actions |
+| `new[Model](partial)`, `edit[Model](model)`, `view[Model](model)` | Form/view state actions |
+| `[slice]List`, `[slice]InitList`, `[slice]Insight`, `[slice]Selection` | Slice states |
+| `init[Slice](args)`, `refresh[Slice]()`, `setPageOf[Slice](page)` | Slice actions |
+| `set[Field]On[Model](value)` | Auto-setters for each model field |
+
+**Rule**: Write custom store actions only for toast messages (`msg.loading`/`msg.success`) or multi-step workflows. State fields and CRUD actions are already auto-generated.
+
+### Document — Filter Query Auto-Generation
+
+| Auto-Generated (from Filter definition) | Description |
+|----------------------------------------|-------------|
+| `list[Query](args)`, `listIds[Query](args)` | List documents matching filter |
+| `find[Query](args)`, `findId[Query](args)` | Find one (null if not found) |
+| `pick[Query](args)`, `pickId[Query](args)` | Find one (throw if not found) |
+| `exists[Query](args)`, `count[Query](args)` | Existence check and count |
+| `insight[Query](args)`, `query[Query](args)` | Insight and raw query |
+
+**Rule**: Define `Filter` with `.query()` conditions in `document.ts`. akan scan auto-generates all 10 query helper methods per filter. Write `Document` chain methods only for state transitions with validation.