@tailor-platform/erp-kit 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/erp-kit",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Opinionated ERP toolkit for building business applications on Tailor Platform",
   "license": "MIT",
   "bin": {
@@ -26,15 +26,18 @@
     "@mockoon/commons-server": "^9.0.0",
     "chalk": "^5.4.1",
     "fast-glob": "^3.3.3",
+    "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-to-string": "^4.0.0",
     "politty": "^0.4.0",
     "zod": "4.3.6"
   },
   "devDependencies": {
     "@tailor-platform/function-kysely-tailordb": "0.1.3",
-    "@tailor-platform/function-types": "0.8.1",
+    "@tailor-platform/function-types": "0.8.2",
     "@tailor-platform/sdk": "1.17.1",
+    "@types/mdast": "^4.0.4",
     "@types/node": "^25.1.0",
-    "eslint": "9.39.2",
+    "eslint": "9.39.4",
     "kysely": "0.28.10",
     "tsup": "^8.0.0",
     "typescript": "^5.7.3",
@@ -43,7 +46,7 @@
   },
   "peerDependencies": {
     "@tailor-platform/function-kysely-tailordb": "0.1.3",
-    "@tailor-platform/function-types": "0.8.1",
+    "@tailor-platform/function-types": "0.8.2",
     "@tailor-platform/sdk": "1.17.1",
     "kysely": "0.28.10"
   },
@@ -52,9 +55,7 @@
   },
   "scripts": {
     "build": "tsup",
-    "generate": "pnpm generate:primitives && pnpm generate:user-management",
-    "generate:primitives": "cd src/modules/primitives && tailor-sdk generate",
-    "generate:user-management": "cd src/modules/user-management && tailor-sdk generate",
+    "generate": "for dir in src/modules/*/; do [ -f \"$dir/tailor.config.ts\" ] && (cd \"$dir\" && echo \"Generating $dir...\" && tailor-sdk generate); done",
     "lint": "eslint --cache .",
     "lint:fix": "eslint --cache --fix .",
     "typecheck": "tsc --noEmit",
@@ -64,6 +65,8 @@
     "test:user-management": "vitest run src/modules/user-management/",
     "test:shared": "vitest run src/modules/shared/",
     "mock:start": "node dist/cli.js mock start",
-    "mock:validate": "node dist/cli.js mock validate"
+    "mock:validate": "node dist/cli.js mock validate",
+    "doc:gen": "POLITTY_DOCS_UPDATE=true vitest run src/cli.doc.test.ts",
+    "doc:check": "vitest run src/cli.doc.test.ts"
   }
 }

package/schemas/module/command.yml

@@ -35,6 +35,7 @@ structure:
       # Error handling - REQUIRED
       # How errors are handled
       - heading: "## Error Scenarios"
+        description: "Use UPPER_SNAKE_CASE error codes to identify each scenario.\ne.g. `- **ITEM_NOT_FOUND**: Specified item ID does not exist`"
         lists:
           - min: 0
             type: unordered

package/schemas/module/model.yml

@@ -37,6 +37,20 @@ structure:
                 type: unordered
                 min_items: 0
 
+          - heading: "### Query Definitions"
+            description: |
+              Definitions of queries this domain model supports.
+              Should match with the queries defined in modules/**/docs/queries/*.md and link to them.
+              For Stateful models or models with isActive, follow the status-aware naming convention:
+                - get{Entity}: single lookup, returns any status
+                - list{Status}{Entities}: business use case with status baked into the name (e.g., listActiveItems)
+                - list{Entities}: unfiltered, returns all statuses
+                - search{Entities}: admin/exploratory with parametric status filter
+            lists:
+              - min: 0
+                type: unordered
+                min_items: 0
+
           - heading: "### Models"
             description: |
               Actual database models necessary for the domain model.

package/schemas/module/query.yml

@@ -0,0 +1,53 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
+
+structure:
+  - heading:
+      expr: "filename == heading"
+    children:
+      # What this query does - REQUIRED
+      - heading: "## Overview"
+
+      # Business rules - REQUIRED
+      # Rules, constraints, and validation logic
+      - heading: "## Business Rules"
+        allow_additional: true
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+      # How it works - REQUIRED
+      # Step-by-step flow or workflow
+      - heading: "## Process Flow"
+        code_blocks:
+          - lang: mermaid
+            min: 1
+
+      # External dependencies - OPTIONAL
+      # Queries from other modules that this query depends on
+      - heading: "## External Dependencies"
+        description: "e.g. `- [inventory::getStockLevel](../../inventory/queries/getStockLevel.md) - Get current stock level`"
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+      # Error handling - REQUIRED
+      # How errors are handled
+      - heading: "## Error Scenarios"
+        description: "Use UPPER_SNAKE_CASE error codes to identify each scenario.\ne.g. `- **ITEM_NOT_FOUND**: Specified item ID does not exist`"
+        lists:
+          - min: 0
+            type: unordered
+            min_items: 1
+
+# Link validation
+links:
+  validate_internal: true
+  validate_files: true
+
+# Heading rules
+heading_rules:
+  no_skip_levels: true
+  unique: true
+  max_depth: 4

package/skills/{app-compose-1-requirement-analysis → erp-kit-app-1-requirements}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: app-compose-1-requirement-analysis
+name: erp-kit-app-1-requirements
 description: Create Tier 1-2 documentation (requirements, actors, business-flow) for examples/. Use when starting a new application or documenting high-level requirements and workflows.
 ---
 
@@ -82,7 +82,7 @@ pnpm run app:doc:check
 
 ## Next Step
 
-After completing Tier 1-2, use `/app-compose-2-requirements-breakdown` to create Tier 3 documentation.
+After completing Tier 1-2, use `/erp-kit-app-2-breakdown` to create Tier 3 documentation.
 
 ## References
 

package/skills/{app-compose-2-requirements-breakdown → erp-kit-app-2-breakdown}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: app-compose-2-requirements-breakdown
-description: Create Tier 3 documentation (stories, screens) by breaking down business flows. Use after completing Tier 1-2 documentation with app-compose-1-requirement-analysis.
+name: erp-kit-app-2-breakdown
+description: Create Tier 3 documentation (stories, screens) by breaking down business flows. Use after completing Tier 1-2 documentation with erp-kit-app-1-requirements.
 ---
 
 # Requirements Breakdown Workflow
@@ -85,7 +85,7 @@ pnpm run app:doc:check
 
 ## Next Step
 
-After completing Tier 3, use `/app-compose-3-doc-review` to validate documentation parity.
+After completing Tier 3, use `/erp-kit-app-3-doc-review` to validate documentation parity.
 
 ## References
 

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

@@ -1,5 +1,5 @@
 ---
-name: app-compose-3-doc-review
+name: erp-kit-app-3-doc-review
 description: Review documentation parity between Tier 2 (business flows, actors) and Tier 3 (stories, screens). Use when validating that all business flow steps have corresponding stories, and that screens are properly linked.
 ---
 
@@ -109,7 +109,7 @@ examples/<app-name>/docs/actors/*.md                  # Actors
 
 ## Next Step
 
-After fixing all issues, use `/app-compose-4-design-mock` to create visual UI mockups from screen specifications.
+After fixing all issues, use `/erp-kit-app-4-design` to create visual UI mockups from screen specifications.
 
 ## References
 

package/skills/{app-compose-4-design-mock → erp-kit-app-4-design}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: app-compose-4-design-mock
-description: Create design mockups from screen specifications using .pen files. Use after completing documentation review with app-compose-3-doc-review. Generates visual UI mockups with shadcn components.
+name: erp-kit-app-4-design
+description: Create design mockups from screen specifications using .pen files. Use after completing documentation review with erp-kit-app-3-doc-review. Generates visual UI mockups with shadcn components.
 ---
 
 # Design Mockup Workflow
@@ -245,7 +245,7 @@ mcp__pencil__get_screenshot(filePath: "docs/design.pen", nodeId: "{frame-id}")
 
 ## Next Step
 
-After completing design mockups, use `/app-compose-5-design-mock-review` to review and validate the mockups against screen specifications.
+After completing design mockups, use `/erp-kit-app-5-design-review` to review and validate the mockups against screen specifications.
 
 ## References
 

package/skills/{app-compose-5-design-mock-review → erp-kit-app-5-design-review}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: app-compose-5-design-mock-review
-description: Review design mockups (.pen files) against screen specifications. Use after completing design mockups with app-compose-4-design-mock. Validates visual consistency, detects regressions, and fixes layout issues.
+name: erp-kit-app-5-design-review
+description: Review design mockups (.pen files) against screen specifications. Use after completing design mockups with erp-kit-app-4-design. Validates visual consistency, detects regressions, and fixes layout issues.
 ---
 
 # Design Mockup Review Workflow
@@ -10,7 +10,7 @@ Review visual design mockups against Tier 3 screen documentation. Detect and fix
 ## Prerequisites
 
 - `docs/screen/*.md` (screen specifications)
-- `docs/design.pen` (design mockups from app-compose-4-design-mock)
+- `docs/design.pen` (design mockups from erp-kit-app-4-design)
 
 ## Workflow Phases
 
@@ -280,7 +280,7 @@ Look for `iconFontName` property in sidebar menu items. Icons use Lucide icon fo
 
 ## Next Step
 
-After completing design review, use `/app-compose-6-implementation-spec` to create Tier 4 documentation (resolvers).
+After completing design review, use `/erp-kit-app-6-impl-spec` to create Tier 4 documentation (resolvers).
 
 ## References
 

package/skills/{app-compose-6-implementation-spec → erp-kit-app-6-impl-spec}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: app-compose-6-implementation-spec
-description: Create Tier 4 documentation (resolvers) for GraphQL operations. Use after completing design review with app-compose-5-design-mock-review.
+name: erp-kit-app-6-impl-spec
+description: Create Tier 4 documentation (resolvers) for GraphQL operations. Use after completing design review with erp-kit-app-5-design-review.
 ---
 
 # Implementation Spec Workflow
@@ -72,7 +72,7 @@ ls modules/<module-name>/docs/commands/
 **If modules don't exist:**
 
 1. **Identify needed modules** - Group resolver operations by domain
-2. **Create module docs first** - Use `1-module-docs` skill
+2. **Create module docs first** - Use `erp-kit-module-1-docs` skill
 3. **Return to Tier 4** - After modules have documented commands
 
 ```

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.