@dforge-core/dforge-mcp 0.1.0-rc.12 → 0.1.0-rc.13

package/skills/dforge-mcp-author/references/settings.md

@@ -0,0 +1,120 @@
+# Module Settings Reference
+
+Module settings are **configurable values** scoped to a module. Tenant admins set them; module code reads them at runtime. Values inherit through the folder tree (child folder overrides parent, parent overrides module default).
+
+Lives in: `settings.json` at the module root.
+
+## Structure
+
+Settings use the **same field type system as entity columns**. Each setting is like a single column with a default value.
+
+```json
+{
+    "company_name": {
+        "fieldTypeCd": "text",
+        "baseDatatypeCd": "string",
+        "description": "Company name displayed on documents",
+        "defaultValue": "Your Company Name"
+    },
+    "invoice_prefix": {
+        "fieldTypeCd": "text",
+        "baseDatatypeCd": "string",
+        "description": "Prefix for auto-generated invoice numbers",
+        "defaultValue": "INV-"
+    },
+    "default_currency": {
+        "fieldTypeCd": "dropdown",
+        "baseDatatypeCd": "string",
+        "description": "Default currency code for documents",
+        "defaultValue": "USD",
+        "params": {
+            "options": ["USD", "EUR", "GBP", "CHF"]
+        }
+    },
+    "allow_negative_stock": {
+        "fieldTypeCd": "checkbox",
+        "baseDatatypeCd": "bool",
+        "description": "Allow operations that result in negative stock",
+        "defaultValue": false
+    },
+    "company_logo": {
+        "fieldTypeCd": "image",
+        "description": "Shown on printed documents"
+    }
+}
+```
+
+## Reading settings
+
+From formulas, reference settings with `$[setting_name]`:
+
+```
+[total] * (1 + $[vat_rate] / 100)
+```
+
+From DSL actions (check your dForge version for exact syntax):
+
+```
+execute:
+    rate = settings.vat_rate
+    tax = [total] * rate / 100
+```
+
+From number sequence patterns:
+
+```
+"pattern": "$[invoice_prefix]-{yyyy}-{seq:4}"
+```
+
+## Folder-scoped inheritance
+
+Settings resolve at runtime through the folder hierarchy:
+
+1. The folder the user is currently in → its override (if any)
+2. Parent folder → override (if any)
+3. ... up the tree ...
+4. Module default (from `settings.json`)
+
+This means different folders can have different VAT rates, different prefixes, different currencies — without any code changes.
+
+## Field types supported in settings
+
+Any field type that makes sense for a single scalar value:
+
+- `text`, `textarea`, `richtext`, `code`
+- `number`, `currency`, `percent`
+- `checkbox`
+- `date`, `datetime`, `time`
+- `dropdown`, `flags`, `color`, `tags`
+- `image`, `file`
+- `json`
+- `user` (if you want to store a reference to a specific user)
+
+**Not supported** as settings:
+
+- `lookup` (reference to an entity row) — use a `text` setting holding a code instead
+- `grid` (set) — settings are single values
+
+## Params
+
+Settings support the same `params` as entity columns:
+
+- `options` (for `dropdown` and `flags`)
+- `min`, `max` (for `number`)
+- `currency` (for `currency`)
+- `maxLen` (for `text`)
+
+## Declaring setting access in roles
+
+By default, only the module/tenant admin can change settings. If you want specific roles to read or modify settings, grant appropriate rights on the settings objects in `security/roles.json` (check your dForge version for the exact naming).
+
+## Common mistakes
+
+- Forgetting to declare `defaultValue` (the key is `defaultValue`, not `default`) — missing setting values cause runtime errors when formulas reference them.
+- Using `lookup` as a setting field type — unsupported.
+- Hardcoding values that should be settings — makes the module non-configurable. Any string/number that might vary per deployment is a good candidate for a setting.
+- Reading a setting that doesn't exist — returns null, which causes formula errors. Always provide a default.
+
+## Reference
+
+This file covers the module package format for settings. If you need details on the runtime resolution API (`settings.get`, `settings.list`, `settings.set`, `settings.clear`), ask the user to check their dForge version's settings documentation.

package/skills/dforge-mcp-author/references/traits.md

@@ -0,0 +1,153 @@
+# Entity Traits Reference
+
+Traits are **reusable column bundles** that entities inherit. They eliminate boilerplate — instead of declaring PK columns, timestamps, and audit tracking on every entity, you declare `traits: ["identity", "audit"]` and dForge mixes them in automatically.
+
+Declared on an entity:
+
+```json
+{
+    "description": "Contacts",
+    "dbObject": "contact",
+    "toString": "{first_name} {last_name}",
+    "traits": ["identity", "audit"],
+    "fields": {
+        "first_name": { /* ... */ }
+        // No need to declare contact_id, created_date, last_updated, etc.
+    }
+}
+```
+
+Source of truth: `server/database/system-modules/metadata/traits.json`
+
+## All traits
+
+### `identity`
+
+Adds the primary key column named `{entity}_id`.
+
+- Column: `{dbObject}_id` (e.g. `contact_id` for `dbObject: "contact"`)
+- `dbDatatype: "cuid"`, `flags: "I"`, `isPk: true`, `isIdentity: true`
+- Auto-generated on insert
+
+**FK columns pointing to an `identity`-trait entity must use `dbDatatype: "cuid"`.** Do not use `bigint`, `int`, `int8`, or `integer` — `cuid` is the platform's type name even though it is physically stored as int8. Using any other value causes an `ENTITY_COLUMN_IMPORT_ERROR` type-mismatch on install.
+
+**Most entities should use `identity`.** Exceptions: junction tables with composite PKs, extension entities that share a PK with their parent, or entities using the `period` trait (which provides its own PK).
+
+### `audit`
+
+Adds **two timestamp columns** (no user tracking):
+
+- `created_date` (`timestamptz`, formula `NOW()`, auto-set on insert)
+- `last_updated` (`timestamptz`, formula `NOW()`, auto-set on insert and update)
+
+Both columns have `flags: "I"` (internal — not shown in UI by default, managed by the platform).
+
+**Important**: `audit` does NOT add `created_by` / `updated_by` user columns. For user tracking, use `audit-full`.
+
+### `audit-full`
+
+**Includes everything from `audit`** (timestamps) plus adds **four user-tracking columns**:
+
+- `created_by` (cuid, FK to user)
+- `created_by_user` (Reference column, lookup to user — for UI display)
+- `last_updated_by` (cuid, FK to user)
+- `last_updated_by_user` (Reference column, lookup to user — for UI display)
+
+Also adds FK constraints: `FK_{Entity}_CreatedBy` and `FK_{Entity}_LastUpdatedBy`.
+
+Use `audit-full` when you need to know **who** created/modified a record, not just **when**. All four user columns have `flags: "I"` (internal).
+
+**You don't need to declare both `audit` and `audit-full`** — `audit-full` inherits from `audit` automatically.
+
+> **⚠️ `audit-full` + seed data needs handling.** `created_by` and `last_updated_by` are
+> **required** (NOT NULL) cuid FKs to `user`, with **no default formula**. At runtime the platform
+> fills them from the current user, but at **seed** time there is no current user, so a seeded
+> `audit-full` entity fails install: *"Seed data for '<entity>': required column 'created_by'
+> (cuid) is not present in seed records."* (The `audit` timestamps are fine — they default to
+> `NOW()`.) `audit-full` is fully supported — when an entity uses it, pick one of two fixes:
+>
+> 1. **Don't seed that entity (preferred).** Keep `audit-full`, ship it with no seed file. This
+>    matches dForge-core — none of its modules seed user-tracked columns — and suits transactional
+>    entities (orders, movements) that don't need demo rows.
+> 2. **Seed with the System user.** Set `"created_by": 0` and `"last_updated_by": 0` on every seed
+>    record. `user_id = 0` ('System') is a real, always-present row in every tenant (inserted by the
+>    `admin` dependency), so the FK resolves. Use this when you genuinely need `audit-full` **and**
+>    seed data on the same entity:
+>    ```json
+>    { "entityCode": "purchase_order", "records": [
+>        { "purchase_order_id": 1001, "order_number": "PO-2026-0001", "supplier_id": 2001,
+>          "created_by": 0, "last_updated_by": 0 }
+>    ] }
+>    ```
+
+### `soft-delete`
+
+Adds a soft-delete flag:
+
+- `active` (boolean, default `true`, formula `"true"`)
+
+When records are "deleted," they're marked `active = false` instead of being physically removed. This preserves FK integrity and allows recovery.
+
+### `sorting`
+
+Adds a manual sort-order column:
+
+- `order_num` (int4, number, `flags: "VEM"`)
+
+Use for entities where display order matters (menu items, checklist items, FAQ entries).
+
+### `postable`
+
+**Marker trait — adds no columns.** Indicates the entity supports document posting (e.g. invoices that transition from draft to posted state). The actual posting state is managed by `A`-type or `L`-type columns (accumulation/ledger column types).
+
+Use in combination with `accumulation` or `ledger` traits for accounting/registry entities.
+
+### `accumulation`
+
+**Marker trait — adds no columns.** Indicates the entity is an accumulation register. Configuration lives in `A`-type column params (balance entity, dimensions, resources).
+
+Advanced feature for accounting/registry modules.
+
+### `ledger`
+
+**Marker trait — adds no columns.** Indicates the entity uses double-entry bookkeeping. Configuration lives in `L`-type column params (lines, movement entity, balance entity).
+
+Advanced feature for accounting modules.
+
+### `period`
+
+Adds a complete period-entity template with its own PK:
+
+- `period_key` (varchar 20, `isPk: true`, `flags: "VEM"`) — the period identifier (e.g. "2026-Q1")
+- `description` (varchar 100, `flags: "VEM"`)
+- `closed` (boolean, default `false`, `flags: "VEM"`) — whether the period is closed
+- `start_date` (date, `flags: "VEM"`)
+- `end_date` (date, `flags: "VEM"`)
+
+**Do not combine with `identity`** — the `period` trait provides its own PK (`period_key`).
+
+## Which traits to use
+
+| Entity type | Recommended traits |
+|---|---|
+| Most business entities (contacts, orders, products) | `["identity", "audit"]` |
+| Documents / approval workflows (`purchase_order`, `invoice`) | `["identity", "audit"]` by default — dForge-core seeds these with plain `audit` |
+| Entities that need per-row user attribution (who created/changed it) | `["identity", "audit-full"]` — if also seeded, set `created_by`/`last_updated_by: 0` per record (or don't seed it) |
+| Lookup/enum tables (read-only after seeding) | `["identity"]` (no audit needed) |
+| Entities with manual ordering (menu items, steps) | `["identity", "audit", "sorting"]` |
+| Soft-deletable entities (users, accounts) | `["identity", "audit", "soft-delete"]` |
+| Financial documents (invoices) | `["identity", "audit", "postable"]` |
+| Accounting periods (fiscal quarters) | `["period"]` (no `identity` — has its own PK) |
+| Junction/bridge tables | `["identity", "audit"]` |
+
+**Default to `audit`.** Reach for `audit-full` when the user explicitly needs to track *who* changed a row. If such an entity is **also** seeded, handle its required `created_by`/`last_updated_by` with one of the two options above (don't seed it, or set both to the System user `0`).
+
+## Rules
+
+1. **Always declare `traits` as a JSON array**, not a string or object.
+2. **Always include `identity` unless** the entity uses `period` (own PK) or has a manually-declared PK.
+3. **Default to `audit`; use `audit-full` only when the user explicitly needs per-row user attribution.** `audit` is lighter (just timestamps). `audit-full` adds four user columns, two of which (`created_by`, `last_updated_by`) are **required** with no default. If an `audit-full` entity is **seeded**, every seed record must set `created_by` and `last_updated_by` to the System user `0` — otherwise install fails on the missing columns. (Prefer not seeding `audit-full` entities at all; see the `audit-full` section.)
+4. **Don't redefine trait-provided columns.** If you declare `created_date` manually alongside `traits: ["audit"]`, the installer will error.
+5. **Order doesn't matter** inside the `traits` array.
+6. **`postable`, `accumulation`, `ledger` are marker traits** — they don't add columns, they flag the entity for advanced accounting behaviour. Only use them if you're building accounting/registry modules and understand the `A`/`L` column types.
+7. **Don't invent trait names.** Only use the 9 listed above. Check `server/database/system-modules/metadata/traits.json` if in doubt.

package/skills/dforge-mcp-author/references/translations.md

@@ -0,0 +1,158 @@
+# Translations Reference
+
+dForge modules support multi-language translations for user-facing labels — entity names, field labels, view titles, folder names, menu items, action labels and params, and report params/dataset captions.
+
+Lives in: `translations/<locale>.json` (e.g. `translations/en-US.json`, `translations/de-DE.json`)
+
+Locale codes use the `ll-CC` format (language-country): `en-US`, `de-DE`, `fr-FR`, `es-ES`, etc.
+
+## Structure
+
+Translation files mirror the module's content structure. Each translatable object has a `label` (and optionally `desc` for description):
+
+```json
+{
+    "entities": {
+        "contact": {
+            "label": "Contact",
+            "desc": "People at accounts",
+            "fields": {
+                "contact_id": { "label": "Contact ID" },
+                "first_name": { "label": "First Name" },
+                "last_name": { "label": "Last Name" },
+                "email": { "label": "Email" },
+                "phone": { "label": "Phone" },
+                "account": { "label": "Account" },
+                "owner_id": { "label": "Owner" },
+                "created_date": { "label": "Created Date" },
+                "last_updated": { "label": "Last Updated" },
+                "activities": { "label": "Activities" }
+            }
+        }
+    },
+    "folders": {
+        "crm": { "label": "Sales CRM" }
+    },
+    "views": {
+        "contacts": { "label": "Contacts" },
+        "contacts_list": { "label": "Contact List" },
+        "contacts_gallery": { "label": "Contact Cards" }
+    },
+    "menus": {
+        "crm_menu": {
+            "label": "Sales CRM",
+            "items": {
+                "customers": { "label": "Customers" },
+                "contacts": { "label": "Contacts" }
+            }
+        }
+    },
+    "actions": {
+        "create_quote_from_opp": {
+            "label": "Create Quote",
+            "desc": "Create a draft quote from this opportunity",
+            "params": {
+                "discount_pct": { "label": "Discount %" }
+            }
+        }
+    },
+    "reports": {
+        "sales_pipeline": {
+            "datasets": {
+                "opportunities": { "caption": "Open Opportunities" }
+            },
+            "params": {
+                "min_amount": { "label": "Minimum Amount" }
+            }
+        }
+    }
+}
+```
+
+## Top-level sections
+
+| Section | Translates | Keys are |
+|---|---|---|
+| `entities` | Entity labels (`label`, `desc`) and all field labels | Entity codes → `{ label, desc, fields: { field_code: { label } } }` |
+| `folders` | Folder labels | Folder codes (root folder key from `ui/folders.json`) |
+| `views` | Data view labels | View codes (keys from `ui/data_views.json`) |
+| `menus` | Menu node labels (root + nested items) | Menu root key → `{ label, items: { item_code: { label } } }` matching `ui/menus.json` structure |
+| `actions` | Action labels, descriptions, and param labels | Action codes (keys from `ui/actions.json`) → `{ label, desc, params: { param_cd: { label } } }` |
+| `reports` | Report dataset captions and param labels | Report codes → `{ datasets: { ds_cd: { caption } }, params: { param_cd: { label } } }` |
+
+### Sections that are NOT translated (write-time only)
+
+- `roles` — role rows have no `res_id` column. The `roles` key may appear in shipped translation files (e.g. `modules/crm/translations/de-DE.json`) but is **explicitly skipped** by the installer. Role display name comes from `security/roles.json` `description` only. (Comment in [`TranslationRegistrar.cs:248`](../../../server/src/dForge.Admin/Services/ModuleInstall/TranslationRegistrar.cs#L248): "reserved for future use.")
+- `settings` — completeness *is* checked by the validator when listed in `manifest.supportedLocales` (so you'll be forced to ship `settings.<cd>.label` for each declared locale), but the registrar doesn't display those translated labels at runtime. The English `label` in `settings.json` is what users see today.
+- `print_templates` — not currently consumed by the registrar. Template labels come from `ui/print_templates.json`.
+
+If you include these sections, the install succeeds (they're silently ignored) — but you won't see localized output for them, so don't expect it.
+
+## German example (de-DE)
+
+```json
+{
+    "entities": {
+        "contact": {
+            "label": "Kontakt",
+            "desc": "Personen bei Konten",
+            "fields": {
+                "contact_id": { "label": "Kontakt-ID" },
+                "first_name": { "label": "Vorname" },
+                "last_name": { "label": "Nachname" },
+                "email": { "label": "E-Mail" },
+                "phone": { "label": "Telefon" },
+                "account": { "label": "Konto" },
+                "owner_id": { "label": "Besitzer" },
+                "created_date": { "label": "Erstellt am" },
+                "last_updated": { "label": "Zuletzt aktualisiert" }
+            }
+        }
+    },
+    "folders": {
+        "crm": { "label": "Vertrieb CRM" }
+    },
+    "views": {
+        "contacts": { "label": "Kontakte" }
+    },
+    "menus": {
+        "crm_menu": {
+            "label": "Vertrieb CRM",
+            "items": {
+                "customers": { "label": "Kunden" },
+                "contacts": { "label": "Kontakte" }
+            }
+        }
+    },
+    "actions": {
+        "create_quote_from_opp": { "label": "Angebot erstellen" }
+    }
+}
+```
+
+## Manifest declaration
+
+Non-English locales are declared in `supportedLocales` (an array of `ll-CC` tags) — **not** a `translations` object. The manifest schema has no `translations` key and rejects it (`additionalProperties: false`). Translation files are auto-discovered at `translations/<locale>.json`. Ship `translations/en-US.json` as the English base, but do **not** list `en`/`en-US` in `supportedLocales` — it covers the non-English locales only (the schema rejects `en`/`en-US` entries).
+
+```json
+"supportedLocales": ["de-DE", "fr-FR"]
+```
+
+Every listed locale MUST have a matching `translations/<locale>.json` with a label for each translatable resource, or install fails completeness validation.
+
+## Rules
+
+1. **Always provide `en-US`** as the base language. Other languages fall back to it for missing keys.
+2. **Locale format is `ll-CC`** (e.g. `en-US`, `de-DE`, `fr-FR`) — language code + country code, hyphen-separated.
+3. **Translate everything user-visible**: entity labels, every field label (including trait-provided fields like `created_date`, `last_updated`), view names, menu items, action labels, role descriptions, setting labels, folder names.
+4. **Include virtual columns** (references, sets, formulas) in field translations — they appear in the UI just like physical columns.
+5. **Menu translations mirror the `ui/menus.json` structure** — root key → `items` → nested items.
+6. **Missing keys fall back** to the `en-US` value, then to the raw code name. So it's safe to ship partial translations — untranslated items show in English rather than breaking.
+7. **Don't translate column codes** — only the `label` values. Codes stay as-is in all languages.
+8. **File naming**: `translations/<locale>.json` (e.g. `de-DE.json`) — each non-English file must match a locale listed in `supportedLocales`.
+
+## When to create translations
+
+- **Always** create `translations/en-US.json` — even for English-only modules. It ensures all labels are explicitly declared rather than derived from column codes.
+- **On request** create additional languages. The LLM can generate translations from the `en-US` file — the structure is identical, only `label` and `desc` values change.
+- **Include all fields** in each language file, including trait-provided fields (`created_date`, `last_updated`, `created_by`, etc.) — users see these columns and they need labels.

package/skills/dforge-mcp-author/references/validation-checklist.md

@@ -0,0 +1,182 @@
+# Validation Checklist
+
+Run through this checklist **before** declaring a module complete. Do it mentally if there's no validate CLI available; run `dforge validate .` if there is.
+
+## Top install-blockers (scan first)
+
+These five have each caused a real install failure. Check them before the section-by-section pass:
+
+- [ ] **DSL dates** — `execute:` blocks use lowercase `now()`, never `TODAY()`/`NOW()` (formula-only; otherwise install fails `'TODAY' is not defined`)
+- [ ] **Roll-up totals** — a sum over a child set is a Formula (`F`) column with `SUM([set].[field])`, **not** a Generated (`G`) column over a virtual `F`/`R`/`S` child (otherwise `db_error: column old.<field> does not exist`)
+- [ ] **Rights keys** — actions/reports/folders use a **colon** (`action:x`, `report:x`, `folder:x`); entities bare or cross-module-dotted; deny by omitting the key, never `""`
+- [ ] **Manifest** — no `translations` key (auto-discovered; non-English locales go in `supportedLocales`)
+- [ ] **Column defaults** — set via `formula` / `numberSequence` / DSL, never a `defaultValue` key on an entity field
+- [ ] **Seed + traits** — seeded `audit-full` entities set `created_by`/`last_updated_by: 0` (System user) in every record (or use `audit` / don't seed them); otherwise install fails on the missing user columns
+
+## Manifest
+
+- [ ] `manifest.json` exists at the module root
+- [ ] `packageFormat` is set (usually `1`)
+- [ ] `moduleId` is a valid UUID and unique (not copied from another module)
+- [ ] `code` is lowercase, snake_case, letters+digits+underscores only
+- [ ] `version` is valid semver
+- [ ] `dbSchemaVersion` is valid semver
+- [ ] `displayName` and `description` are present
+- [ ] `dependencies` includes `admin` (almost always required)
+- [ ] Every `entities` entry points to a file that exists
+- [ ] Every other content pointer (`dataViews`, `menus`, `security`, etc.) points to existing files
+
+## Entities
+
+For each entity:
+
+- [ ] Has `description`, `dbObject`, `toString`
+- [ ] Has `traits: ["identity", "audit"]` (or a justified exception)
+- [ ] `toString` template uses only column names that exist on the entity
+- [ ] Every column has `fieldTypeCd` (except for formula columns which use `baseDatatypeCd` + `columnType: "F"`)
+- [ ] Every `fieldTypeCd` value is from the official catalog (see `field-types.md`)
+- [ ] Every column has `flags` (valid letters: V, I, E, M, H only — no U, S, or P; see `flags.md` for meanings)
+- [ ] Every column has `orderNum`
+- [ ] Every column has `description`
+
+### FK+Reference pattern
+
+- [ ] Every reference column (`columnType: "R"`) has a paired hidden FK column
+- [ ] The hidden FK column has `flags: "EM"` (not `V`, not `I`)
+- [ ] The reference column has `flags: "VEM"`, `fieldTypeCd: "lookup"`, and a `link` object
+- [ ] `link.entity` points to an entity that exists (in this module or a dependency)
+- [ ] `link.thisKey` matches the FK column name on this entity
+- [ ] `link.otherKey` matches the PK column name on the target entity
+- [ ] The entity's `references` block declares the FK constraint
+
+### Formula columns
+
+- [ ] `columnType: "F"`
+- [ ] Has `baseDatatypeCd` (required)
+- [ ] Has `formula`
+- [ ] Uses only known formula functions (see `formulas.md`)
+- [ ] Does NOT have `dbDatatype` (formula columns are virtual)
+- [ ] Flags is usually `"V"` (read-only)
+
+### Set columns
+
+- [ ] `columnType: "S"`
+- [ ] `fieldTypeCd: "grid"` (or another set renderer)
+- [ ] Has `link` with `entity`, `thisKey`, `otherKey`
+- [ ] `link.otherKey` points to a real FK column on the target entity
+
+## Data views
+
+- [ ] Every data view has `label`, `viewType`, and `dataSources`
+- [ ] `dataSources` is an array, not an object
+- [ ] Each source has `entityCode` and `columns`
+- [ ] `entityCode` points to an entity that exists
+- [ ] Column codes in `columns` all exist on the entity
+- [ ] `viewType` is from the supported list (`grid`, `list`, `kanban`, `gallery`, `tree-grid`, `card`)
+- [ ] Sort uses the view-def-root `order` key — a `string[]` like `["-created_date", "name"]` (leading `-` = descending), NOT `sort` / `[{column_cd, direction}]` (that object shape belongs to queries & reports, not data views)
+
+## Menus
+
+- [ ] Menus are **nested dictionaries** with `children`, NOT arrays
+- [ ] Every node has `label`
+- [ ] Leaf items have `itemType` (`V`, `R`, `D`, or `A`)
+- [ ] Folder nodes do **not** have `itemType`
+- [ ] Leaf items with `itemType: "V"` have `dataViewCode` (NOT `viewCode`)
+- [ ] Every `dataViewCode` points to a data view that exists
+- [ ] Every `reportCode` points to a report that exists
+- [ ] `orderNum` is set on each node for deterministic ordering
+
+## Security
+
+- [ ] `security/roles.json` exists (at least one role)
+- [ ] Every role has `description` and `rights` (both required; no `label` field — display name comes from `description`). The `roles.schema.json` sets `additionalProperties: false`, so any extra field (including `label`) is rejected at install time.
+- [ ] The field name is `rights`, NOT `entityRights`
+- [ ] Rights strings use only valid letters: `SIUDC` for entities, `E` for actions/reports/folders
+- [ ] Entity codes in `rights` all reference real entities (in this module or dependencies)
+- [ ] At least one role has `SIUDC` on every entity (typically an admin role)
+
+## Actions
+
+For each action:
+
+- [ ] Registered in `ui/actions.json` with `label`, `script`, `executionMode`, `entityCode`
+- [ ] DSL file exists at `logic/actions/<script>.dsl`, where `<script>` is the bare filename in the action's `script` field (no path, no `.dsl` extension)
+- [ ] DSL file has `params:`, `canExecute:`, and `execute:` blocks
+- [ ] `canExecute:` is a valid formula expression
+- [ ] `execute:` uses only documented built-in functions
+- [ ] Referenced entities exist
+- [ ] Referenced parameters are declared in `params:`
+
+## Settings
+
+- [ ] `settings.json` exists if the module has any settings
+- [ ] Every setting has `fieldTypeCd`
+- [ ] Every setting has a `defaultValue` (or is explicitly nullable) — note the field is `defaultValue`, not `default`
+- [ ] Field types used are from the supported subset (no `lookup`, no `grid`)
+
+## Seed data
+
+- [ ] Seed files are in `seed-data/` with numbered prefixes (`01-`, `02-`, …)
+- [ ] Seed files are ordered by FK dependency (parents before children)
+- [ ] Seeded `audit-full` entities supply `created_by`/`last_updated_by` — `audit-full` adds these as required (cuid, NOT NULL) columns. Either set both to the System user `0` in every seed record, switch the entity to `audit`, or don't seed it. (The `audit` timestamps need no value — they default to `NOW()`.)
+- [ ] Each seed file has `entityCode` and `records`
+- [ ] Every record has explicit values for NOT NULL columns
+- [ ] PKs are explicit **numeric integers** (e.g. 1001, 1002 — NOT UUID strings, `cuid` is int8)
+
+## Translations
+
+- [ ] `translations/en-US.json` exists
+- [ ] Has `entities` section with `label`, `desc`, and `fields` for every entity
+- [ ] Every field (including trait-provided: `created_date`, `last_updated`, etc.) has a `label`
+- [ ] Has `views` section with labels for every data view
+- [ ] Has `menus` section matching the `ui/menus.json` structure
+- [ ] Has `actions` section with labels for every action
+- [ ] Has `roles` section with labels for every role
+- [ ] Has `settings` section with labels for every setting (if settings exist)
+- [ ] Has `folders` section with label for the root folder
+- [ ] Additional language files (if any) have the same structure as `en-US.json`
+- [ ] Manifest `supportedLocales` lists every non-English locale that has a `translations/<locale>.json` file (English is not listed)
+
+## Versioning
+
+- [ ] `version` in manifest is bumped from previous release (or `"0.1.0"` for new modules)
+- [ ] `dbSchemaVersion` is bumped if any DB schema changed (new entity, new column, changed type)
+- [ ] `dbSchemaVersion` is NOT bumped if only views/menus/actions/translations changed
+
+## Cross-entity consistency
+
+- [ ] Every menu item's `dataViewCode` has a matching entry in `ui/data_views.json`
+- [ ] Every data view's `entityCode` has a matching entity in the module (or a dependency)
+- [ ] Every role's `rights` object codes match real entities/actions/reports
+- [ ] Every action's `entityCode` matches a real entity
+- [ ] Every FK constraint in `references` blocks matches a real target entity
+
+## After validation
+
+- [ ] If a local `dforge validate .` CLI is available, run it and fix any errors
+- [ ] Try to `dforge package .` to build the `.dforge` file — it should succeed
+- [ ] If MCP is connected, run `dry_run_install` to see the generated SQL
+- [ ] Only after dry-run looks clean, `install_module` or `install-to-dev`
+
+## Red flags during review
+
+If you see any of these, stop and investigate:
+
+- An entity with no `traits` and no explicit PK column
+- A reference column without a paired FK column (or vice versa)
+- A column with `fieldTypeCd: "integer"` / `"datePicker"` / `"money"` / `"autocomplete"` / `"boolean"` (wrong names)
+- Flags containing `U`, `S`, or `P` (not valid flag letters)
+- Menus with `children: [...]` (array, not dict)
+- Roles with `entityRights` (wrong key)
+- Data views with root-level `entityCode` (should be inside `dataSources`)
+- Formula columns without `baseDatatypeCd`
+- DSL actions with JavaScript/Python syntax
+- Seed data files without numbered prefixes
+- Seed data using `"entity"` instead of `"entityCode"` (silent failure — installer reads empty entity code)
+- Seed data PKs as UUID strings instead of numeric integers
+- Duplicate column codes in the same entity
+- `orderNum` missing or duplicated across columns
+
+## When the checklist passes
+
+Tell the user what you built, summarize the entity model (e.g. "7 entities: contact, account, opportunity with its line items, quote with lines, activity, product"), list the data views and actions, and describe the security roles. Then ask if they want to install it.