@dforge-core/dforge-mcp 0.1.0-rc.9 → 0.1.1

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

@@ -0,0 +1,206 @@
+# Formula Engine Reference
+
+Formulas are used in:
+
+- **Formula columns** (`columnType: "F"`) — computed values
+- **Action `canExecute:` blocks** — availability checks
+- **Default values** — a setting's `formula` (e.g. `"formula": "TODAY()"`) or a formula (`F`) column. Note: entity *data* columns have **no** `default`/`defaultValue` key — model a default with an `F` column or set it in action/trigger logic.
+- **Filter expressions** (partially)
+- **Validation expressions** (partially)
+
+> These are **formula** contexts: date helpers are uppercase `TODAY()` / `NOW()` here. Action
+> `execute:` blocks are **not** a formula context — they run as JavaScript and use lowercase
+> `now()` (see `action-dsl.md`).
+
+The same grammar applies everywhere.
+
+## Basic syntax
+
+- **Field references**: `[column_name]` — the value of another column on the same entity
+- **Navigation**: `[reference_column].[field]` — traverse a reference to a related entity's field
+- **Literals**: numbers (`42`, `3.14`), strings (`'hello'` or `"hello"`), booleans (`true`, `false`), null (`null`)
+- **Operators**: `+`, `-`, `*`, `/`, `%`, `==`, `!=`, `<`, `>`, `<=`, `>=`, `AND`, `OR`, `NOT`
+- **Function calls**: `FUNCTION_NAME(arg1, arg2, ...)` — uppercase by convention
+- **Parentheses** for grouping
+
+## Examples
+
+```
+[first_name] + ' ' + [last_name]
+
+[quantity] * [unit_price]
+
+[account].[name]
+
+[account].[billing_address].[country]
+
+[status] == "active" AND [balance] > 0
+
+CASE([priority], "high", 3, "medium", 2, "low", 1, 0)
+
+IF([total] > 1000, "large", "small")
+
+COALESCE([nickname], [first_name], "Unknown")
+
+FORMAT([created_date], "yyyy-MM-dd")
+```
+
+## Built-in functions
+
+### String functions
+
+- `CONCAT(a, b, ...)` — concatenate strings
+- `LEN(s)` — string length
+- `UPPER(s)`, `LOWER(s)` — case conversion
+- `TRIM(s)`, `LTRIM(s)`, `RTRIM(s)` — whitespace removal
+- `SUBSTRING(s, start, len)` — substring
+- `REPLACE(s, find, with)` — replace substring
+- `CONTAINS(s, find)` — boolean substring check
+- `STARTSWITH(s, prefix)`, `ENDSWITH(s, suffix)` — boolean
+- `FORMAT(value, pattern)` — format dates/numbers
+
+### Number functions
+
+- `ABS(n)`, `ROUND(n, digits)`, `FLOOR(n)`, `CEIL(n)`, `CEILING(n)`
+- `MIN(a, b)`, `MAX(a, b)` — binary min/max
+- `POW(base, exp)`, `SQRT(n)`
+- `MOD(a, b)` — modulo
+
+### Date functions
+
+- `TODAY()` — current date
+- `NOW()` — current datetime with timezone
+- `YEAR(d)`, `MONTH(d)`, `DAY(d)` — date parts
+- `HOUR(dt)`, `MINUTE(dt)`, `SECOND(dt)` — time parts
+- `DATEADD(d, count, unit)` — add time (unit: `day`, `month`, `year`, `hour`, `minute`)
+- `DATEDIFF(a, b, unit)` — difference between dates
+
+### Logical functions
+
+- `IF(cond, then, else)` — ternary
+- `CASE(expr, val1, result1, val2, result2, ..., default)` — multi-branch
+- `COALESCE(a, b, c, ...)` — first non-null
+- `NULLIF(a, b)` — null if equal, else a
+- `ISNULL(x)` — boolean null check
+
+### Aggregation (on set columns)
+
+- `COUNT([set_column])` — count related rows
+- `SUM([set_column].[field])` — sum a child field over a set
+- `AVG`, `MIN`, `MAX` similarly
+
+Put set aggregations in a **Formula (`F`) column** — they evaluate at query time and may reference
+any child column, including the child's own formula columns, e.g. `SUM([lines].[line_total])`.
+
+> ⛔ Do **not** put a `SUM([set].[field])` in a **Generated (`G`)** column unless `field` is a
+> *physical* (`D`) column. A `G` aggregate is maintained by a DB trigger that reads the child's
+> `OLD`/`NEW` physical values; aggregating a virtual `F` child fails at install with
+> `db_error: column old.<field> does not exist`. See `column-types.md` → "Roll-up totals over child rows".
+
+## Navigation (dot notation)
+
+`[reference].[field]` traverses a reference column to a target entity:
+
+```
+[account].[name]                         -- contact's account's name
+[owner].[email]                          -- owner user's email
+[account].[primary_contact].[phone]      -- chained
+```
+
+Navigation works through `columnType: "R"` columns (reference columns). Chains of length 1 are **synchronous** and resolved instantly. Chains of length ≥ 2 are **asynchronous** — the formula engine resolves them after the initial data load.
+
+## Sync vs async formulas
+
+- **Sync formula**: pure local math, no navigation, or one-level navigation that can be JOINed. Evaluated on load and on every edit to a dependency.
+- **Async formula**: multi-hop navigation. Evaluated after the initial data load, re-evaluated when dependencies change.
+
+You don't declare which is which — the engine detects it from the formula's AST.
+
+## Setting references
+
+In modules that use settings, formulas can reference setting values with `$[SettingName]` syntax:
+
+```
+[total] * $[VAT_Rate]
+```
+
+## Validation and CHECK constraints
+
+Check constraints use a subset of the formula grammar. The server parses them to AST and converts to SQL. Common patterns:
+
+```
+[quantity] > 0
+[end_date] >= [start_date]
+[email] LIKE '%@%'
+```
+
+## Examples — full formula columns
+
+### Full name
+
+```json
+"full_name": {
+    "columnType": "F",
+    "fieldTypeCd": "text",
+    "baseDatatypeCd": "string",
+    "flags": "V",
+    "orderNum": 25,
+    "formula": "[first_name] + ' ' + [last_name]",
+    "description": "Full Name"
+}
+```
+
+### Line total (quantity × price)
+
+```json
+"line_total": {
+    "columnType": "F",
+    "fieldTypeCd": "currency",
+    "baseDatatypeCd": "number",
+    "flags": "V",
+    "orderNum": 60,
+    "formula": "[quantity] * [unit_price]",
+    "description": "Line Total"
+}
+```
+
+### Customer country (via navigation)
+
+```json
+"customer_country": {
+    "columnType": "F",
+    "fieldTypeCd": "text",
+    "baseDatatypeCd": "string",
+    "flags": "V",
+    "orderNum": 70,
+    "formula": "[account].[billing_country]",
+    "description": "Customer Country"
+}
+```
+
+### Days since created
+
+```json
+"days_open": {
+    "columnType": "F",
+    "fieldTypeCd": "number",
+    "baseDatatypeCd": "number",
+    "flags": "V",
+    "orderNum": 200,
+    "formula": "DATEDIFF([created_date], NOW(), 'day')",
+    "description": "Days Open"
+}
+```
+
+## Common mistakes
+
+- Using `column_name` without brackets — **wrong**. Always `[column_name]`.
+- Inventing functions like `HAS_PERMISSION()`, `IS_ADMIN()`, `GET_USER()` — **do not exist**. Do not use unless confirmed to exist in the actual dForge engine.
+- Using JavaScript syntax like `row.field` or `this.field` — **wrong**. Only `[field]`.
+- Forgetting `baseDatatypeCd` on formula columns — **required**. Without it, filters and SQL don't work.
+- Using SQL syntax like `SELECT`, `JOIN`, `WHERE` — **wrong**. Formulas are expressions, not queries.
+- String concatenation with commas — **wrong**. Use `+` or `CONCAT()`.
+
+## Reference
+
+This file covers the most common formula functions and patterns. If you encounter an edge case not covered here, ask the user to check their dForge version's formula documentation.

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

@@ -0,0 +1,149 @@
+# Scheduled Jobs Reference
+
+A scheduled job is **a cron schedule + an action** declared in `logic/jobs.json`. The `dForge.Scheduler` worker process fires the action on schedule. No new DSL surface — jobs reuse existing actions.
+
+Lives in: `logic/jobs.json` at the module root. Schema: [`docs/schemas/jobs.schema.json`](../../../docs/schemas/jobs.schema.json). Full guide: [`docs/business-logic/jobs.md`](../../../docs/business-logic/jobs.md).
+
+## Structure
+
+```json
+{
+    "jobs": [
+        {
+            "code": "nightly_invoice_run",
+            "description": "Generate recurring invoices for active subscriptions.",
+            "action": "generate_invoices",
+            "schedule": "0 2 * * *",
+            "timeout": 600,
+            "class": "long_running",
+            "concurrency": 1,
+            "timeZone": "Europe/Zurich"
+        }
+    ]
+}
+```
+
+## Field reference
+
+| Field            | Required | Default      | Notes                                                                                                                                |
+| ---------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `code`           | Yes      |              | Unique within the module. `^[a-z][a-z0-9_]*$`.                                                                                       |
+| `action`         | Yes      |              | Action `code` from this module's `ui/actions.json`. Cross-module references are rejected — wrap in a local action.                   |
+| `schedule`       | Yes      |              | Five-field cron (minute granularity). Sub-minute schedules rejected.                                                                 |
+| `timeout`        | Yes      |              | Hard timeout in seconds. Range `(0, 3600]`. **No implicit default.** `timeout > 300` requires `class: "long_running"`.               |
+| `class`          | No       | `"standard"` | `"standard"` (≤ 300 s) or `"long_running"` (≤ 3600 s). Explicit opt-in for heavy jobs.                                               |
+| `concurrency`    | No       | `1`          | Max parallel runs `[1, 5]`. `1` = single-instance.                                                                                   |
+| `idempotencyKey` | No       |              | Template like `"{job_cd}:{run.month}"`. Successful run with same key blocks re-dispatch.                                             |
+| `timeZone`       | No       | tenant tz    | IANA name. Falls back to `auth.tenant.time_zone`.                                                                                    |
+| `params`         | No       | `{}`         | Static parameters passed to the action as `__params`. For runtime values, use folder-scoped module settings.                         |
+| `enabled`        | No       | `true`       | `false` fully disables — no scheduler, no manual trigger.                                                                            |
+| `paused`         | No       | `false`      | Soft pause. Scheduler skips, but "Run now" still works.                                                                              |
+| `description`    | No       |              | Human-readable description.                                                                                                          |
+
+**Hard cap: 50 jobs per module.**
+
+## Cron — five fields
+
+```
+minute  hour  day-of-month  month  day-of-week
+
+0 2 * * *      # daily at 02:00 in the job's tz
+*/15 * * * *   # every 15 minutes
+0 9 * * 1-5    # 09:00 weekdays
+0 0 1 * *      # midnight on the first of each month
+```
+
+## Writing the action
+
+Scheduled actions run with **no record bound**. Specifically:
+
+- `user_id = 0` (system user sentinel)
+- No `folder_id` — query / insert against the tenant DB directly
+- `notify()` writes to inbox only (no live SSE in Phase 1)
+- `sendEmail()` raw mode only in Phase 1
+
+**Record context is forbidden.** The install pipeline rejects any action whose compiled DSL references `[field]` or `for x in records { … }` — those compile to `__r.` / `__records.` which would `ReferenceError` at fire time. Refactor to operate via `query()` / `insert()`:
+
+```
+execute:
+    let cutoff = now() - days(30)
+    let drafts = query("SELECT invoice_id FROM invoice WHERE status = 'draft' AND created_date < @cutoff",
+                       { cutoff: cutoff })
+    for d in drafts {
+        callAction('archive_invoice', { invoice_id: d.invoice_id })
+    }
+```
+
+Hide the action from the UI with `canExecute: false` — the scheduler bypasses the check:
+
+```
+canExecute:
+    false
+
+execute:
+    // cron-only logic
+```
+
+## Reference example (the `chore` module)
+
+**`logic/jobs.json`**
+```json
+{
+    "jobs": [
+        {
+            "code": "tick",
+            "description": "Smoke test — fires every minute.",
+            "action": "log_tick",
+            "schedule": "* * * * *",
+            "timeout": 30
+        }
+    ]
+}
+```
+
+**`ui/actions.json`**
+```json
+{
+    "log_tick": {
+        "description": "Insert a chore_log row marking a scheduler tick",
+        "label": "Log Tick",
+        "icon": "bi-clock-history",
+        "entityCode": "chore_log",
+        "executionMode": "single",
+        "script": "log_tick",
+        "isTransacted": true,
+        "orderNum": 10
+    }
+}
+```
+
+**`logic/actions/log_tick.dsl`**
+```
+execute:
+    insert('chore_log', {
+        ran_at: now(),
+        message: 'Scheduler tick',
+        source: 'cron'
+    })
+```
+
+Full source: [`modules/chore/`](../../../modules/chore/).
+
+## Common mistakes
+
+- **Cross-module action reference.** A job in `crm` cannot reference an action in `fin`. Declare a thin `crm.run_fin_thing` action in your own module and bind the job to that.
+- **Record-bound action.** Any `[field]` or `for x in records` in the DSL fails install — the action has no record at fire time. Refactor to `query()`/`insert()`.
+- **Missing `timeout`.** Required, no default. Pick 30 s if you don't know; bump when you have evidence.
+- **`timeout > 300` without `class: "long_running"`.** Install fails. Heavy jobs are an explicit opt-in.
+- **Sub-minute cron.** The scheduler ticks every 60 s. Anything finer is dishonest — declare a minute cron.
+- **Renaming `code` between versions.** Treats it as a new job and leaves the old `scheduled_job` row orphaned until uninstall (actually reaped on upgrade — but you lose `job_run` history). Keep `code` stable.
+- **"Schedule this 5 minutes from now" pattern.** There is no per-call `schedule()`. Use a cron-scan job that watches a queue table — see [memory: cron-scan pattern](../../../docs/business-logic/jobs.md#when-to-use-a-job-vs-a-trigger).
+- **Confusing `enabled` and `paused`.** `enabled: false` → "Run now" no-ops. `paused: true` → cron skips but "Run now" works. Use `paused` for incident response; use `enabled: false` when you mean "turn this off entirely".
+
+## Reference
+
+- Full developer guide: [`docs/business-logic/jobs.md`](../../../docs/business-logic/jobs.md)
+- JSON Schema: [`docs/schemas/jobs.schema.json`](../../../docs/schemas/jobs.schema.json)
+- Reference module: [`modules/chore/`](../../../modules/chore/)
+- Source (registrar): `server/src/dForge.Admin/Services/ModuleInstall/JobRegistrar.cs`
+- Source (scheduler worker): `server/src/dForge.Scheduler/SchedulerWorker.cs`

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

@@ -0,0 +1,123 @@
+# Module Manifest Reference
+
+Every dForge module has a `manifest.json` at its root. This file declares the module's identity, version, dependencies, and the list of files that make up the package.
+
+## Minimal example
+
+```json
+{
+    "packageFormat": 1,
+    "moduleId": "10000000-0000-0000-0000-000000000001",
+    "code": "my_module",
+    "version": "0.1.0",
+    "dbSchemaVersion": "0.0.1",
+    "displayName": "My Module",
+    "description": "A module that does a thing.",
+    "author": { "name": "Your Name" },
+    "license": "MIT",
+    "category": "other",
+    "tags": ["tag1", "tag2"],
+    "icon": "bi-box",
+    "dependencies": {
+        "admin": ">=0.0.1"
+    },
+    "created": "2026-04-08",
+    "updated": "2026-04-08",
+    "entities": {
+        "my_entity": "./entities/my_entity.json"
+    }
+}
+```
+
+## Required fields
+
+| Field | Type | Description |
+|---|---|---|
+| `packageFormat` | number | Package format version. Always `1` for now. |
+| `moduleId` | UUID | Globally unique module identifier. Generate a fresh UUID for new modules; never reuse. |
+| `code` | string | Short identifier, lowercase, letters+digits+underscores. **Becomes the DB schema name.** Cannot be changed after install. |
+| `version` | semver | Module version. Bump on every release. |
+| `dbSchemaVersion` | semver | Schema version. Bump when the DB schema changes (column add/remove, new entity, etc.). |
+| `displayName` | string | Human-readable name shown in the UI and marketplace. |
+| `description` | string | One-line summary of what the module does. |
+
+## Optional but recommended
+
+| Field | Type | Description |
+|---|---|---|
+| `author` | object | `{name, email?, url?}` |
+| `license` | string | SPDX identifier (e.g. `"MIT"`, `"Apache-2.0"`) |
+| `category` | string | Marketplace category slug (e.g. `"sales"`, `"hr"`, `"other"`) |
+| `tags` | string[] | Search tags |
+| `icon` | string | Bootstrap icon name (e.g. `"bi-briefcase"`) or similar |
+| `dependencies` | object | Map of `module_code → semver range` |
+| `created`, `updated` | ISO date | Timestamps |
+
+## Content declarations
+
+The manifest lists every file in the package by logical key. The installer reads each path relative to the manifest.
+
+| Key | Type | Shape |
+|---|---|---|
+| `entities` | object | `{ "entity_code": "./entities/entity.json" }` |
+| `entityViews` | object | `{ "view_name": "./ui/entity_views/view.json" }` (optional) |
+| `dataViews` | string | path to `./ui/data_views.json` (or object with per-view files) |
+| `menus` | string | path to `./ui/menus.json` |
+| `actions` | object | Actions defined in `./ui/actions.json`, DSL in `./logic/actions/*.dsl` |
+| `reports` | object | `{ "report_code": "./ui/reports/report.json" }` |
+| `settings` | string | path to `./settings.json` |
+| `security` | object | `{ "roles": "./security/roles.json", "folders": "./ui/folders.json" }` |
+| `seedData` | array | List of paths to seed files, in install order |
+| `supportedLocales` | string[] | IETF locale tags that the module ships translations for, e.g. `["de-DE", "uk-UA"]`. Files are **auto-discovered** at `./translations/{locale}.json` — there is no per-file manifest entry. English (`en`/`en-*`) is the default and must not be listed. |
+| `printTemplates` | object | `{ "template_code": "./print_templates/template.scriban" }` |
+| `webhooks` | string | path to `./webhooks.json` |
+
+## Dependencies
+
+Dependencies are a map of module codes to semver ranges. The installer checks that all listed dependencies are installed with compatible versions before installing your module.
+
+```json
+"dependencies": {
+    "admin": ">=0.0.1",
+    "fin": ">=0.1.0 <0.2.0"
+}
+```
+
+**Always depend on `admin`** unless you have a very unusual module — admin provides the user/role system every other module needs.
+
+**For bridge modules** (`crm-fin`, `wms-fin`, etc.), depend on both sides:
+
+```json
+"dependencies": {
+    "admin": ">=0.0.1",
+    "crm": ">=0.1.0",
+    "fin": ">=0.1.0"
+}
+```
+
+## Extension entities
+
+Modules can extend entities owned by other modules. Declare these in `entities` with dotted keys:
+
+```json
+"entities": {
+    "my_extra_entity": "./entities/my_extra_entity.json",
+    "fin.invoice": "./entities/fin.invoice.json"  // extends fin's invoice
+}
+```
+
+The extension file has `"extends": "fin.invoice"` inside. See MODULE_CONVENTIONS.md for details.
+
+## What NOT to put in the manifest
+
+- **Do not** add a `translations` key (e.g. `"translations": { "en-US": "..." }`). There is **no** such manifest field — translation files are auto-discovered at `./translations/{locale}.json`, and non-English locales are declared in `supportedLocales` (English is never listed). The manifest schema is `additionalProperties: false`, so a stray `translations` key fails install.
+- **Do not** put entity definitions inline. Always reference external files.
+- **Do not** list sample or test files — only content that ships with the module.
+- **Do not** include `system: true` unless this is a dForge platform module (`admin`, `metadata`). Regular modules omit it (defaults to `false`).
+- **Do not** hardcode absolute paths. Everything is relative to the manifest.
+
+## Versioning notes
+
+- Bump `version` on every release (bug fix, feature add, etc.).
+- Bump `dbSchemaVersion` **only** when the DB schema changes. If you added an action but no new columns, `version` goes up but `dbSchemaVersion` stays the same.
+- The installer uses `dbSchemaVersion` to decide whether to run migrations.

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

@@ -0,0 +1,164 @@
+# Menus Reference
+
+Menus define the module's navigation tree. Shown in the sidebar when the module is installed.
+
+Lives in: `ui/menus.json`
+
+## Structure — root wrapper with `items`, then nested dictionaries with `children`
+
+**The real format** (from all reference modules — CRM, HR, Fin, WMS):
+
+```json
+{
+    "todo_menu": {
+        "label": "Todos",
+        "items": {
+            "lists": {
+                "orderNum": 1,
+                "label": "Lists",
+                "icon": "list-ul",
+                "children": {
+                    "all_lists": {
+                        "itemType": "V",
+                        "dataViewCode": "todo_list_grid",
+                        "orderNum": 1,
+                        "label": "All Lists",
+                        "icon": "list-ul"
+                    }
+                }
+            },
+            "items": {
+                "orderNum": 2,
+                "label": "Items",
+                "icon": "check2-square",
+                "children": {
+                    "all_items": {
+                        "itemType": "V",
+                        "dataViewCode": "todo_item_grid",
+                        "orderNum": 1,
+                        "label": "All Items",
+                        "icon": "check-square"
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+Structure: **root key** → `label` + `items` → **section nodes** (with `children`) → **leaf nodes** (with `itemType` + data view/report code).
+
+## Item types (leaf nodes only)
+
+| `itemType` | Description | Required field |
+|---|---|---|
+| `"V"` | Data view | `dataViewCode` |
+| `"R"` | Report | `reportCode` |
+| `"D"` | Dashboard | `dashboardCode` |
+| `"A"` | Action | `actionCode` |
+
+**Section nodes** (with `children`) **omit `itemType`**. Only leaf items have it.
+
+## Icons
+
+In `ui/menus.json`, icons use Bootstrap icon names **without the `bi-` prefix**:
+
+- `"graph-up-arrow"` (not `"bi-graph-up-arrow"`)
+- `"people"` (not `"bi-people"`)
+- `"briefcase"` (not `"bi-briefcase"`)
+- `"receipt"`, `"building"`, `"calendar-event"`, `"box-seam"`, etc.
+
+**Note:** This no-prefix rule applies to module menu definitions. In other contexts, such as action registration, the icon value may need the full Bootstrap class name **with** the `bi-` prefix (for example, `"bi-graph-up-arrow"`). Always follow the format required by the specific configuration you are editing.
+See https://icons.getbootstrap.com/ for the full catalog. Common choices:
+
+- `people` — users/contacts
+- `briefcase` — work/business
+- `building` — companies/accounts
+- `cart` — sales/orders
+- `graph-up` — reports/analytics
+- `gear` — settings
+- `receipt` — invoices/quotes
+- `calendar-event` — activities/dates
+- `box-seam` — products/items
+- `kanban` — pipeline/board views
+
+## Real example from CRM module
+
+```json
+{
+    "crm_menu": {
+        "label": "Sales CRM",
+        "items": {
+            "sales": {
+                "orderNum": 1,
+                "label": "Sales",
+                "icon": "graph-up-arrow",
+                "children": {
+                    "leads": {
+                        "itemType": "V",
+                        "dataViewCode": "leads",
+                        "orderNum": 1,
+                        "label": "Leads",
+                        "icon": "person-plus"
+                    },
+                    "opportunities": {
+                        "itemType": "V",
+                        "dataViewCode": "opportunities",
+                        "orderNum": 3,
+                        "label": "Opportunities",
+                        "icon": "trophy"
+                    },
+                    "sales_pipeline_report": {
+                        "itemType": "R",
+                        "reportCode": "sales_pipeline",
+                        "orderNum": 6,
+                        "label": "Sales Pipeline Report",
+                        "icon": "file-earmark-bar-graph"
+                    }
+                }
+            },
+            "customers": {
+                "orderNum": 3,
+                "label": "Customers",
+                "icon": "people",
+                "children": {
+                    "accounts": {
+                        "itemType": "V",
+                        "dataViewCode": "accounts",
+                        "orderNum": 1,
+                        "label": "Accounts",
+                        "icon": "building"
+                    },
+                    "contacts": {
+                        "itemType": "V",
+                        "dataViewCode": "contacts",
+                        "orderNum": 3,
+                        "label": "Contacts",
+                        "icon": "person-lines-fill"
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+## Required rules
+
+1. **Root wrapper key** (e.g. `"crm_menu"`) with a `label` and `items` property.
+2. **`items`** contains the section nodes, **not** direct leaf items at the top level.
+3. **`dataViewCode`**, not `viewCode`. The wrong name silently fails.
+4. **Section nodes have `children`**, leaf nodes have `itemType` + code.
+5. **`orderNum` controls display order** within a level.
+6. **`label` is required** on every node.
+7. **`icon` is optional** but recommended. Use Bootstrap icon names **without** `bi-` prefix.
+
+## Common mistakes
+
+- Skipping the root wrapper (no `{root_key: {label, items}}`) — **wrong**. All reference modules use this structure.
+- Using arrays like `"children": [...]` — **wrong**. Must be a dictionary.
+- Using `viewCode` instead of `dataViewCode` — **wrong**.
+- Putting `itemType: "V"` on a section node with `children` — **wrong**. Omit `itemType` on sections.
+- Using `"bi-people"` as the icon — **wrong in module menus**. Use `"people"` (no prefix).
+- Forgetting `label` — **required**.
+- Putting leaf items directly inside `items` without a section wrapper — **technically works** but doesn't match conventions.