@tailor-platform/erp-kit 0.1.2 → 0.2.1

package/skills/erp-kit-app-5-implementation/references/frontend.md

@@ -0,0 +1,242 @@
+# Frontend Implementation Patterns
+
+## Table of Contents
+
+- [Frontend Scaffold](#frontend-scaffold)
+- [Frontend Pages](#frontend-pages)
+
+---
+
+## Frontend Scaffold
+
+```
+frontend/
+├── src/
+│   ├── main.tsx, App.tsx, index.css
+│   ├── graphql/
+│   │   ├── index.ts                      # gql.tada setup
+│   │   └── generated/                    # Placeholder until backend deploy
+│   ├── lib/
+│   │   ├── auth-client.ts
+│   │   └── utils.ts                      # cn() utility
+│   ├── providers/
+│   │   └── graphql-provider.tsx          # urql client with DPoP auth
+│   ├── components/
+│   │   ├── ui/                           # shadcn/Radix primitives
+│   │   └── composed/                     # empty-state, error-fallback, loading
+│   └── pages/
+│       └── <domain>/
+│           ├── page.tsx                  # Module redirect (REQUIRED)
+│           └── <entity>/
+│               ├── page.tsx              # ListView
+│               ├── components/<entities>-table.tsx
+│               ├── create/page.tsx + components/create-<entity>-form.tsx
+│               └── [id]/
+│                   ├── page.tsx          # DetailView
+│                   ├── components/<entity>-detail.tsx, <entity>-actions.tsx
+│                   └── edit/page.tsx + components/edit-<entity>-form.tsx
+├── scripts/generate-graphql.mjs
+├── package.json, vite.config.ts, tsconfig.json, eslint.config.js
+└── components.json
+```
+
+`package.json` key dependencies and scripts:
+
+```json
+{
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "generate": "node --env-file=.env ./scripts/generate-graphql.mjs",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@tailor-platform/app-shell": "...",
+    "gql.tada": "...",
+    "urql": "...",
+    "react-hook-form": "...",
+    "@hookform/resolvers": "...",
+    "zod": "...",
+    "tailwindcss": "...",
+    "lucide-react": "..."
+  },
+  "devDependencies": {
+    "@tailor-platform/app-shell-vite-plugin": "...",
+    "@tailor-platform/sdk": "...",
+    "@tailwindcss/vite": "...",
+    "vite": "...",
+    "typescript": "..."
+  }
+}
+```
+
+`scripts/generate-graphql.mjs` — fetches the GraphQL schema from the deployed backend:
+
+```js
+import { execSync } from "node:child_process";
+const url = process.env.VITE_TAILOR_APP_URL;
+execSync(`pnpm gql-tada generate schema "${url}/query"`);
+execSync("pnpm gql-tada generate output");
+```
+
+Before deployment, create empty placeholders for `src/graphql/generated/schema.graphql` and `graphql-env.d.ts` so the project compiles. After backend deployment, configure `.env` with `VITE_TAILOR_APP_URL` and `VITE_TAILOR_CLIENT_ID`, then run `pnpm generate` to regenerate them.
+
+---
+
+## Frontend Pages
+
+### GraphQL Setup
+
+All operations use gql.tada for type safety:
+
+```ts
+import { graphql, type FragmentOf, readFragment } from "@/graphql";
+```
+
+Built-in queries (`gqlOperations: "query"`) generate:
+
+- `<Entity>(id: ID!)` — get by ID
+- `<entities>` — list with connection pattern (`edges { node { ... } }`)
+
+Mutations are defined by custom resolvers.
+
+### ListView
+
+Key points:
+
+- Query uses connection pattern: `edges { node { ...Fragment } }`
+- Two-level fragments: row fragment for items, table fragment for the connection
+- `EmptyState` when `edges.length === 0`
+- Columns map to screen spec's "Required Columns"
+- `Layout` with title and create action button
+
+### DetailView
+
+Key points:
+
+- Two-column `Layout`: detail on left, actions on right
+- `useParams()` to get entity ID from route
+- `DescriptionCard` from `@tailor-platform/app-shell` for key-value fields:
+
+```tsx
+<DescriptionCard
+  data={resource}
+  title="Overview"
+  columns={3}
+  fields={[
+    { key: "name", label: "Name", meta: { copyable: true } },
+    {
+      key: "status",
+      label: "Status",
+      type: "badge",
+      meta: { badgeVariantMap: { ACTIVE: "success" } },
+    },
+    { key: "createdAt", label: "Created At", type: "date", meta: { dateFormat: "medium" } },
+  ]}
+/>
+```
+
+Field types: `"text"` (default), `"badge"`, `"money"`, `"date"`, `"link"`, `"address"`, `"reference"`, `"divider"`
+
+### Form Pattern
+
+Create and edit forms share the same structure:
+
+- **React Hook Form + Zod** for validation with `zodResolver`
+- **urql `useMutation`** for GraphQL mutations
+- **Navigate `".."`** to go back to list after success
+- Edit form pre-fills `defaultValues` from existing entity via fragment
+
+#### Field Type Mapping
+
+| Field Type | Component                 | Zod Schema                      |
+| ---------- | ------------------------- | ------------------------------- |
+| Text       | `<Input />`               | `z.string()`                    |
+| Textarea   | `<textarea />`            | `z.string()`                    |
+| Dropdown   | `<Select />`              | `z.string()` or `z.enum([...])` |
+| Date       | `<Input type="date" />`   | `z.string()` (ISO format)       |
+| Number     | `<Input type="number" />` | `z.coerce.number()`             |
+| Checkbox   | `<Checkbox />`            | `z.boolean()`                   |
+
+#### Validation
+
+- **Required: Yes** → `.min(1, "Field is required")` (string) / `.positive()` (number)
+- **Required: No** → `.optional()`
+
+### Shared Component Patterns
+
+#### Fragment Collocation
+
+Each component defines and exports its own GraphQL fragment. The parent page imports it and includes it in the query:
+
+```tsx
+// components/user-card.tsx
+export const UserCardFragment = graphql(`
+  fragment UserCard on User {
+    id
+    name
+    email
+  }
+`);
+
+export const UserCard = ({ user }: { user: FragmentOf<typeof UserCardFragment> }) => {
+  const data = readFragment(UserCardFragment, user);
+  return <div>{data.name}</div>;
+};
+
+// page.tsx
+const UserQuery = graphql(
+  `
+    query User($id: ID!) {
+      user(id: $id) {
+        ...UserCard
+      }
+    }
+  `,
+  [UserCardFragment],
+);
+```
+
+#### App.tsx
+
+- `AuthGuard` is not exported from app-shell — implement it yourself, pass via `guardComponent` prop
+- `GraphQLProvider` needs `authClient` prop to attach DPoP auth headers
+- Required env vars: `VITE_TAILOR_APP_URL`, `VITE_TAILOR_CLIENT_ID`
+- Auth client: create once in `src/lib/auth-client.ts` using `createAuthClient({ appUri, clientId })`
+- Sidebar: use `SidebarGroup` + `SidebarItem` for custom ordering
+
+#### Module-level page.tsx (required)
+
+Every module directory must have a `page.tsx` that redirects to the first child. Use **absolute paths** to avoid double-path bugs:
+
+```tsx
+useEffect(() => {
+  void navigate("/item-management/item", { replace: true });
+}, [navigate]);
+```
+
+#### Page conventions
+
+Every page component must:
+
+1. Be the **default export** of `page.tsx`
+2. Set `appShellPageProps` with at least `meta.title`
+
+#### Common imports
+
+```tsx
+import {
+  Layout,
+  Link,
+  useParams,
+  useNavigate,
+  type AppShellPageProps,
+} from "@tailor-platform/app-shell";
+import { useQuery, useMutation } from "urql";
+import { graphql, type FragmentOf, readFragment } from "@/graphql";
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+```

package/skills/{mock-scenario → erp-kit-mock-scenario}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: mock-scenario
+name: erp-kit-mock-scenario
 description: Scaffold a new Mockoon mock scenario with CRUD routes, error scenarios, and registry updates
 ---
 

package/skills/{1-module-docs → erp-kit-module-1-docs}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: 1-module-docs
+name: erp-kit-module-1-docs
 description: Create ERP module documentation following framework schemas. Use when starting a new module, documenting an existing module, or when user asks to create module docs, feature docs, or design module features. Guides collaborative research, scoping, and iterative feature breakdown.
 ---
 
@@ -108,4 +108,4 @@ pnpm run module:doc:check
 
 ## References
 
-- [Module structure](references/structure.md)
+- [Module structure](../erp-kit-module-shared/references/structure.md)

package/skills/{2-module-feature-breakdown → erp-kit-module-2-feature-breakdown}/SKILL.md

@@ -1,16 +1,16 @@
 ---
-name: 2-module-feature-breakdown
-description: Use when breaking down a feature spec into model and command documentation. Triggers on feature implementation planning, creating model docs, creating command docs, or when user references model.yml/command.yml schemas.
+name: erp-kit-module-2-feature-breakdown
+description: Use when breaking down a feature spec into model, command, and query documentation. Triggers on feature implementation planning, creating model docs, creating command docs, creating query docs, or when user references model.yml/command.yml schemas.
 ---
 
-# Feature Breakdown to Model/Command Docs
+# Feature Breakdown to Model/Command/Query Docs
 
-Convert feature specifications into structured model and command documentation following framework schemas.
+Convert feature specifications into structured model, command, and query documentation following framework schemas.
 
 ## When to Use
 
 - User has a feature spec (e.g., `docs/features/*.md`) and wants implementation docs
-- User asks to create model or command documentation
+- User asks to create model, command, or query documentation
 - User references `model.yml` or `command.yml` schemas
 
 ## Workflow
@@ -25,14 +25,16 @@ Read the feature spec and identify:
 
 - **Models**: Entities with state, fields, relationships
 - **Commands**: Operations that change state (look for verbs in state diagrams)
+- **Queries**: Read-only operations for external consumers — lookups, conversions, aggregations. See [CQRS read rule](../erp-kit-module-shared/references/commands.md#command-side-reads-cqrs-separation)
 
 ### 2. Scaffold
 
-For each model and command, scaffold the documentation files using `erp-kit` CLI:
+For each model, command, and query, scaffold the documentation files using `erp-kit` CLI:
 
 ```bash
 erp-kit scaffold --modules-root modules model <module-name> <model-name>
 erp-kit scaffold --modules-root modules command <module-name> <command-name>
+erp-kit scaffold --modules-root modules query <module-name> <query-name>
 ```
 
 ### 3. Populate
@@ -56,6 +58,9 @@ Schemas are bundled in `@tailor-platform/erp-kit` (model.yml, command.yml).
 | Verb in state diagram | Command doc                      |
 | CRUD operation        | Command doc                      |
 | Validation logic      | Command doc Business Rules       |
+| Data lookup           | Query doc                        |
+| Unit/currency convert | Query doc                        |
+| Computed aggregation  | Query doc                        |
 
 ## Validation
 
@@ -67,6 +72,5 @@ pnpm run module:doc:check
 
 ## References
 
-- [Module structure](references/structure.md)
-- [Model patterns](references/models.md)
-- [Command patterns](references/commands.md)
+- [Command naming convention](references/naming.md)
+- [Module structure](../erp-kit-module-shared/references/structure.md)

package/skills/erp-kit-module-2-feature-breakdown/references/naming.md

@@ -0,0 +1,59 @@
+# Command Naming Convention
+
+Commands use imperative `{verb}{Entity}` format. Use this canonical verb vocabulary when scaffolding commands.
+
+## Canonical Verbs
+
+| Verb               | Meaning                                             | Example                  |
+| ------------------ | --------------------------------------------------- | ------------------------ |
+| `create`           | Insert new entity                                   | `createItem`             |
+| `update`           | Modify existing entity fields                       | `updateItem`             |
+| `delete`           | Permanently remove entity (hard delete)             | `deleteItem`             |
+| `activate`         | Enable entity (inactive → active)                   | `activateUnit`           |
+| `deactivate`       | Soft-disable entity (active → inactive, reversible) | `deactivateUnit`         |
+| `reactivate`       | Re-enable after deactivation                        | `reactivateItem`         |
+| `assign...To...`   | Create a relationship between entities              | `assignRoleToUser`       |
+| `remove...From...` | Remove a relationship between entities              | `removeItemFromTaxonomy` |
+| `revoke...From...` | Remove permission/right (RBAC/security domain only) | `revokeRoleFromUser`     |
+| `set`              | Configure a singular value or reference             | `setBaseCurrency`        |
+| `move`             | Change position or parent in a hierarchy            | `moveTaxonomyNode`       |
+| `log`              | Append-only audit/event record                      | `logAuditEvent`          |
+
+## Choosing the Right Verb
+
+- **`delete` vs `deactivate`**: Use `delete` only for permanent removal. Use `deactivate` for soft-disable where the record is preserved.
+- **`remove...From...` vs `revoke...From...`**: Use `revoke` only in security/RBAC contexts (permissions, roles). Use `remove` for all other relationship unlinking.
+- **`assign...To...`**: Always use `assign` to create relationships, never `add...To...`.
+- **`activate` vs `reactivate`**: Use `reactivate` when the command specifically re-enables a previously deactivated entity and the distinction matters for business logic. Otherwise use `activate`.
+
+## Banned Verbs
+
+Do not use these — use the canonical alternative instead:
+
+| Banned                  | Use instead               |
+| ----------------------- | ------------------------- |
+| `archive` / `unarchive` | `deactivate` / `activate` |
+| `disable` / `enable`    | `deactivate` / `activate` |
+| `add...To...`           | `assign...To...`          |
+| `unlink`                | `remove...From...`        |
+
+## Domain-Specific Verbs
+
+If a feature requires a verb not in this table and the domain experts use it naturally (e.g., `approve`, `reject`, `cancel`, `close`, `submit`), it can be used. Document the rationale in the command doc.
+
+## Feature Operation → Command Name
+
+| Feature Operation    | Expected Command Doc | Notes                          |
+| -------------------- | -------------------- | ------------------------------ |
+| "Create X" / "Add X" | `createX`            | Never `addX`                   |
+| "Update X"           | `updateX`            |                                |
+| "Delete X"           | `deleteX`            | Hard delete only               |
+| "Deactivate X"       | `deactivateX`        | Soft-disable (reversible)      |
+| "Activate X"         | `activateX`          | Enable entity                  |
+| "Reactivate X"       | `reactivateX`        | Re-enable after deactivation   |
+| "Set default X"      | `setDefaultX`        | Singular value/reference       |
+| "Assign X to Y"      | `assignXToY`         | Never `addXToY`                |
+| "Remove X from Y"    | `removeXFromY`       | Generic relationship unlinking |
+| "Revoke X from Y"    | `revokeXFromY`       | RBAC/security domain only      |
+| "Move X"             | `moveX`              | Hierarchy position change      |
+| "Log X"              | `logX`               | Append-only audit/event        |

package/skills/{3-module-doc-review → erp-kit-module-3-doc-review}/SKILL.md

@@ -1,15 +1,15 @@
 ---
-name: 3-module-review
-description: Review feature parity between feature documentation and command/model documentation. Use when validating that all feature scenarios are covered by command docs, and that all required models exist.
+name: erp-kit-module-3-doc-review
+description: Review feature parity between feature documentation and command/model/query documentation. Use when validating that all feature scenarios are covered by command docs, all read operations have query docs, and that all required models exist.
 ---
 
 # Feature Parity Review Workflow
 
-Review **documentation consistency** between feature specs and command/model docs.
+Review **documentation consistency** between feature specs and command/model/query docs.
 
 ## Purpose
 
-Verify that feature documentation (high-level business requirements) is properly covered by command documentation (command specifications) and model documentation (data structures).
+Verify that feature documentation (high-level business requirements) is properly covered by command documentation (write operations), query documentation (read operations), and model documentation (data structures).
 
 ```
 Feature Docs (What)  →  Command Docs (How)  →  Model Docs (With What)
@@ -17,18 +17,22 @@ Feature Docs (What)  →  Command Docs (How)  →  Model Docs (With What)
   Scenarios              Business Rules          Data Structures
   Process Flows          Error Scenarios         Relationships
   Test Cases             Process Flows           Constraints
+                         Query Docs (Read)
+                             ↓
+                         Lookups, Conversions
+                         Aggregations
 ```
 
 ## When to Use
 
-- After writing feature documentation, check for gaps in command/model documentation
-- After writing command/model documentation, verify consistency with features
+- After writing feature documentation, check for gaps in command/model/query documentation
+- After writing command/model/query documentation, verify consistency with features
 - Quality check during documentation review
 
 ## Workflow
 
 ```
-FEATURE DOCS → COMMAND DOCS → MODEL DOCS → COMPARE → REPORT
+FEATURE DOCS → COMMAND DOCS → QUERY DOCS → MODEL DOCS → COMPARE → REPORT
 ```
 
 ## Step-by-Step
@@ -49,7 +53,15 @@ Read ALL command docs:
 modules/<module-name>/docs/commands/*.md
 ```
 
-### 3. Read Model Documentation
+### 3. Read Query Documentation
+
+Read ALL query docs:
+
+```
+modules/<module-name>/docs/queries/*.md
+```
+
+### 4. Read Model Documentation
 
 Read ALL model docs:
 
@@ -57,7 +69,7 @@ Read ALL model docs:
 modules/<module-name>/docs/models/*.md
 ```
 
-### 4. Feature → Command Parity Check
+### 5. Feature → Command Parity Check
 
 For each feature's scenarios and test cases:
 
@@ -75,7 +87,23 @@ For each feature's scenarios and test cases:
 3. Verify corresponding command doc exists
 4. Map feature test cases to command business rules / error scenarios
 
-### 5. Feature → Model Parity Check
+### 6. Feature → Query Parity Check
+
+For each read operation implied by the feature:
+
+| Check Item      | Question                                                              |
+| --------------- | --------------------------------------------------------------------- |
+| Query existence | Does a query doc exist for lookups, conversions, or aggregations?     |
+| Input coverage  | Are all lookup dimensions documented (by id, by unique field, by FK)? |
+| Error handling  | Are error scenarios for missing data documented?                      |
+
+#### How to Check
+
+1. Identify read-only operations in the feature: "look up", "get", "list", "convert", "calculate"
+2. Verify corresponding query doc exists in `docs/queries/`
+3. Check that query docs have error scenarios where applicable
+
+### 7. Feature → Model Parity Check
 
 For each entity mentioned in feature:
 
@@ -85,7 +113,7 @@ For each entity mentioned in feature:
 | State management | Do feature state transitions match model state transitions?        |
 | Relationships    | Are relationships shown in feature defined in model relationships? |
 
-### 6. Command → Model Consistency Check
+### 8. Command → Model Consistency Check
 
 For each command doc:
 
@@ -94,7 +122,7 @@ For each command doc:
 | Target model               | Does a model doc exist for the model that command operates on? |
 | State transition alignment | Do state changes by command match model state transitions?     |
 
-### 7. Report Findings
+### 9. Report Findings
 
 ```markdown
 ## Feature Parity Review Report
@@ -142,6 +170,12 @@ For each command doc:
 | <feature-2> | <cmd-f>          | <purpose description> |
 | <feature-2> | <cmd-g>          | <purpose description> |
 
+#### Missing Query Docs
+
+| Feature     | Expected Query | Purpose               |
+| ----------- | -------------- | --------------------- |
+| <feature-1> | <query-a>      | <purpose description> |
+
 #### Missing Model Docs
 
 (none found)
@@ -162,6 +196,7 @@ For each command doc:
 | Aspect                     | Status | Details                                     |
 | -------------------------- | ------ | ------------------------------------------- |
 | Feature → Command Coverage | ⚠️     | X/Y features have complete command coverage |
+| Feature → Query Coverage   | ⚠️     | X/Y read operations have query docs         |
 | Feature → Model Coverage   | ✅     | All required models documented              |
 | Test Case Coverage         | ⚠️     | X/Y test cases mapped to business rules     |
 | Documentation Consistency  | ⚠️     | N inconsistencies found                     |
@@ -186,6 +221,12 @@ For each command doc:
 - **Implicit commands**: Feature scenario requires helper command not documented
 - **Default handling**: Feature mentions "default" selection but no setDefault command
 
+### Feature → Query
+
+- **Missing query docs**: Feature implies read operation but no query doc exists
+- **Missing conversions**: Feature mentions unit/currency conversion but no query doc
+- **Missing lookups**: Feature requires data retrieval not covered by a query doc
+
 ### Feature → Model
 
 - **Missing models**: Feature references entity with no model doc
@@ -218,19 +259,36 @@ For each command doc:
 
 ### Expected Command Docs for Feature
 
-| Feature Operation | Expected Command Doc |
-| ----------------- | -------------------- |
-| "Add X"           | addX / createX       |
-| "Update X"        | updateX              |
-| "Delete X"        | deleteX              |
-| "Set default X"   | setDefaultX          |
-| "Activate X"      | activateX            |
-| "Deactivate X"    | deactivateX          |
-| "Assign X to Y"   | assignXToY           |
-| "Remove X from Y" | removeXFromY         |
+See [command naming convention](../erp-kit-module-2-feature-breakdown/references/naming.md) for the full rule, disambiguation guide, and banned verbs.
+
+| Feature Operation    | Expected Command Doc | Notes                          |
+| -------------------- | -------------------- | ------------------------------ |
+| "Create X" / "Add X" | `createX`            | Never `addX`                   |
+| "Update X"           | `updateX`            |                                |
+| "Delete X"           | `deleteX`            | Hard delete only               |
+| "Deactivate X"       | `deactivateX`        | Soft-disable (reversible)      |
+| "Activate X"         | `activateX`          | Enable entity                  |
+| "Reactivate X"       | `reactivateX`        | Re-enable after deactivation   |
+| "Set default X"      | `setDefaultX`        | Singular value/reference       |
+| "Assign X to Y"      | `assignXToY`         | Never `addXToY`                |
+| "Remove X from Y"    | `removeXFromY`       | Generic relationship unlinking |
+| "Revoke X from Y"    | `revokeXFromY`       | RBAC/security domain only      |
+| "Move X"             | `moveX`              | Hierarchy position change      |
+| "Log X"              | `logX`               | Append-only audit/event        |
+
+**Banned verbs** — flag as naming violation if found:
+`archive`, `unarchive`, `disable`, `enable`, `add...To...`, `unlink`
+
+### Expected Query Docs for Feature
+
+| Feature Operation | Expected Query Doc  |
+| ----------------- | ------------------- |
+| "Get X"           | GetX                |
+| "Look up X by Y"  | GetX (with Y input) |
+| "List X by Y"     | ListXsByY           |
+| "Convert X"       | ConvertX            |
+| "Calculate X"     | CalculateX          |
 
 ## References
 
-- [Model patterns](references/models.md)
-- [Command patterns](references/commands.md)
-- [Testing patterns](references/testing.md)
+For implementation patterns (models, commands, testing), see erp-kit-module-4-tdd.

package/skills/erp-kit-module-4-tdd/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: erp-kit-module-4-tdd
+description: Use when implementing features in any module under modules/. Triggers on TDD workflow, domain command implementation, adding new database models, creating test fixtures, or implementing business logic commands.
+---
+
+# TDD Implementation for Module Development
+
+Guide for implementing features in modules using Test-Driven Development.
+
+## When to Use
+
+- Implementing new domain commands in any module
+- Implementing read-only queries in any module
+- Adding database models with `@tailor-platform/sdk`
+- Creating tests with `@tailor-platform/erp-kit` testing utilities
+- Implementing business logic (CRUD, state transitions, relationships)
+
+## Workflow
+
+```
+DOCS → MODELS → GENERATE → FIXTURES → TESTS → IMPLEMENT → EXPORT → VERIFY
+```
+
+## Step-by-Step
+
+### 1. Write Command/Query Docs
+
+Write markdown specs under `docs/commands/*.md` and `docs/queries/*.md`. These are the source of truth for error scenarios, permissions, and generated code. See erp-kit-module-1-docs, erp-kit-module-2-feature-breakdown, and erp-kit-module-3-doc-review for documentation workflow.
+
+### 2. Database Models (`db/`)
+
+**Read [models rules](references/models.md) and [db-relations rules](references/db-relations.md) before writing any model.**
+
+Key patterns: factory function, `db.fields.timestamps()`, `.description()` on fields, `.relation()` for foreign keys.
+
+### 3. Generate Code
+
+**Read [generated code rules](references/generated-code.md) for what gets generated and what you write by hand.**
+
+```bash
+# Generate kysely types from models
+pnpm generate
+
+# Generate errors, permissions, and command/query shells from docs
+erp-kit module generate code --root <root> <module>
+```
+
+Generated `.generated.ts` files provide: error classes, permission definitions, and command/query shells. Never edit these files.
+
+### 4. Test Fixtures (`testing/fixtures.ts`)
+
+**Read [testing rules](../erp-kit-module-shared/references/testing.md) before writing fixtures or tests.**
+
+### 5. Write Tests First (`command/*.test.ts`)
+
+Same reference: [testing rules](../erp-kit-module-shared/references/testing.md).
+
+Key patterns: `createMockDb<DB>()`, fixed IDs `"entity-1"`, cover all doc branches.
+
+### 6. Implement Commands (`command/*.ts`)
+
+**Read [commands rules](../erp-kit-module-shared/references/commands.md) before implementing.**
+
+Key patterns: export `run` function, generated shell wraps with `defineCommand(permissions.xxx, run)`, generic `CF` for custom fields, validate → query → mutate.
+
+### 7. Implement Queries (`query/*.ts`)
+
+**Read [queries rules](../erp-kit-module-shared/references/queries.md) before implementing.**
+
+Key patterns: `defineQuery`, `ReadonlyDB<DB>`, `QueryContext`. Generated queries handle simple lookups; write custom queries for joins, aggregations, complex filters.
+
+### 8. Export (`index.ts`)
+
+**Read [exports rules](references/exports.md) for export order.**
+
+### 9. Verify
+
+```bash
+pnpm generate   # Regenerate types if models changed
+pnpm lint       # Check code style
+pnpm typecheck  # Verify TypeScript types
+pnpm test       # Run all tests
+```
+
+## References
+
+- [Module structure](../erp-kit-module-shared/references/structure.md)
+- [Model patterns](references/models.md)
+- [Database relations](references/db-relations.md)
+- [Command patterns](../erp-kit-module-shared/references/commands.md)
+- [Query patterns](../erp-kit-module-shared/references/queries.md)
+- [Generated code](references/generated-code.md)
+- [Testing patterns](../erp-kit-module-shared/references/testing.md)
+- [Export order](references/exports.md)