@dforge-core/dforge-mcp 0.2.4 → 0.2.14

package/package.json

@@ -1,48 +1,49 @@
 {
-  "name": "@dforge-core/dforge-mcp",
-  "version": "0.2.4",
-  "description": "MCP server for dForge module authoring. Exposes 34 scaffold/patch/validate/pack/install tools and schema resources so AI agents (Claude Code, Cursor, Zed) can create and ship dForge modules.",
-  "license": "MIT",
-  "homepage": "https://github.com/iash44/dForge-core",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/dforge-core/dforge-mcp.git"
-  },
-  "bin": {
-    "dforge-mcp": "dist/server.js",
-    "dforge-install-skills": "scripts/install-skills.mjs"
-  },
-  "files": [
-    "dist/",
-    "docs/",
-    "resources/",
-    "skills/",
-    "scripts/install-skills.mjs",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "main": "dist/server.js",
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "build": "tsup",
-    "sync-schemas": "node scripts/vendor-schemas.cjs",
-    "prepublishOnly": "node scripts/vendor-schemas.cjs && tsup",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "install-skills": "node scripts/install-skills.mjs"
-  },
-  "dependencies": {
-    "@dforge-core/dforge-cli": "^0.2.12",
-    "@dforge-core/metadata": "^0.0.13",
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@types/node": "^22.20.1",
-    "tsup": "^8.5.1",
-    "typescript": "^6.0.3",
-    "vitest": "^3.2.7"
-  }
+	"name": "@dforge-core/dforge-mcp",
+	"version": "0.2.14",
+	"description": "MCP server for dForge module authoring. Exposes 34 scaffold/patch/validate/pack/install tools and schema resources so AI agents (Claude Code, Cursor, Zed) can create and ship dForge modules.",
+	"license": "MIT",
+	"homepage": "https://github.com/iash44/dForge-core",
+	"packageManager": "pnpm@11.22.0+sha512.1ff870c4c6133dfd88fb2afc46dd13d47f09c9794b438c6fdb47ca98caf3bc16381ee0be93a091b8e3824cf01f889f46d7d9e20910fb0be1ab0fb5baa80dd621",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/dforge-core/dforge-mcp.git"
+	},
+	"bin": {
+		"dforge-mcp": "dist/server.js",
+		"dforge-install-skills": "scripts/install-skills.mjs"
+	},
+	"files": [
+		"dist/",
+		"docs/",
+		"resources/",
+		"skills/",
+		"scripts/install-skills.mjs",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"main": "dist/server.js",
+	"engines": {
+		"node": ">=18"
+	},
+	"scripts": {
+		"build": "tsup",
+		"sync-schemas": "node scripts/vendor-schemas.cjs",
+		"prepublishOnly": "node scripts/vendor-schemas.cjs && tsup",
+		"typecheck": "tsc --noEmit",
+		"test": "vitest run",
+		"install-skills": "node scripts/install-skills.mjs"
+	},
+	"dependencies": {
+		"@dforge-core/dforge-cli": "^0.2.14",
+		"@dforge-core/metadata": "^0.0.15",
+		"@modelcontextprotocol/sdk": "^1.30.0",
+		"zod": "^4.4.3"
+	},
+	"devDependencies": {
+		"@types/node": "^26.2.0",
+		"tsup": "^8.5.1",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.10"
+	}
 }

package/resources/docs/conventions.md

@@ -869,6 +869,10 @@ For `dropdown` fields, define available options in `params.options`:
 
 Both formats can be mixed in the same array, but this is not recommended.
 
+**Action / report parameters carry the same option list.** A `dropdown` param declares its choices in the DSL (`method: dropdown required "Method" options=[bank_transfer:Bank transfer, cash:Cash]`) or, for report params, under `params.options` in JSON — the identical `{value, label, icon, color}` shape. Bare codes (`options=bank_transfer,cash`) render as raw codes in **every** locale, English included, so label them. Per-locale labels go under `actions.<cd>.params.<param_cd>.options` / `reports.<cd>.params.<param_cd>.options`.
+
+**Prefer a shared column domain over restating a list.** When the choices are the same set a column uses — the usual case, since the param's value normally ends up written to that column — bind the param to the domain instead: `method: domain payment_method required "Method"` in the DSL, `{"domain": "fin.payment_method"}` for a report param. The options and their translations then live in exactly one place for the column and every parameter on it. Keep inline `options=` for a list that belongs to one parameter and matches no column. See the `column-domains.md` and `translations.md` skill references.
+
 ---
 
 ## Version Management

package/resources/docs/dsl-reference.md

@@ -59,10 +59,56 @@ Common field types + their extra keys:
 | `date` | (none) | `due_date: date required "Due"` |
 | `dateTime` | (none) | `scheduled_at: dateTime required "Scheduled at"` |
 | `boolean` | (none) | `urgent: boolean optional "Urgent?"` |
-| `dropdown` | `options` | `priority: dropdown required "Priority" options=low,medium,high` |
+| `dropdown` | `options` | `priority: dropdown required "Priority" options=[low:Low, medium:Medium, high:High]` |
 | `lookup` | (use ref form instead — see below) | |
 | `file` | `accept` | `attachment: file optional "Attachment" accept=.pdf,.png` |
 
+### Dropdown options — label them, or prefer a domain
+
+`options=low,medium,high` stores bare codes, and the dialog then shows `low` / `medium` /
+`high` in **every** locale, English included. Give each choice a label:
+
+```dsl
+params:
+    // value:Label — wrap the list in [ ] (or " ") when a label contains a space,
+    // because the trailing key=value scan is whitespace-delimited.
+    method:   dropdown required "Method" options=[bank_transfer:Bank transfer, cash:Cash]
+
+    // JSON form — for values with commas, or to set icon/color.
+    priority: dropdown required "Priority" options=[{"value":"high","label":"High","color":"#c00"},"normal"]
+```
+
+An option object must carry a non-empty string `value` — that's the stored code and the key
+translations match on. Per-locale labels go under
+`actions.<cd>.params.<param_cd>.options` (see `translations.md`).
+
+### Domain form (borrow a shared option list)
+
+```
+paramName: domain domainCd [required|optional] ["description"]
+```
+
+```dsl
+params:
+    payment_method: domain payment_method required "Payment method for this batch"
+    status:         domain fin.doc_status optional "Status"   // module-qualified
+```
+
+**Prefer this whenever the choices are (or could be) the same list a column uses** — which
+is the usual case, since the param's value normally ends up written to that column. The
+param takes its control and options from the `column_domain`, so the list and its
+translations are authored **once** instead of restated in the DSL and drifting from the
+column's.
+
+- The param keeps its **own caption**; only the choices come from the domain.
+- Nothing may follow the description: `options=`, `min=` and friends are a compile error
+  here — the domain owns them.
+- An unknown domain code fails the install; it never degrades to an empty dropdown.
+- Report params take the same binding as JSON: `{"domain": "fin.payment_method", "label": "…"}`.
+
+Use inline `options=` only when the list belongs to that one parameter and matches no
+column (a run mode, an export format).
+
 ### Reference form (FK to another entity)
 
 ```
@@ -355,7 +401,7 @@ the server translates to an exact `::bigint` SQL literal.
 #### `info(message, opts?)`, `warn(message, opts?)`
 Queue user-facing toast. `opts.links: [{entity, id}]` adds "open record" buttons.
 
-A message is a **receipt for work the action did**, not a way to publish a computed value. An action whose only output is `info('<some computed number>')` stores nothing — it can't be audited, re-read or reported on, and the value arrives unformatted. Build a report, a formula column, or an action that writes a result record instead. See `dforge://reference/action-dsl`, *When an action is the wrong tool*.
+A message is a **receipt for work the action did**, not a way to publish a computed value. An action whose only output is `info('<some computed number>')` stores nothing — it can't be audited, re-read or reported on, and the value arrives unformatted. Build a **record report** (a report with an `entities` attachment: it lands on the same record toolbar, but shows the numbers *and* the rows behind them, re-read live on every open), a formula column, or an action that writes a result record instead. Do not compute in DSL what a report dataset already aggregates. See `dforge://reference/action-dsl`, *When an action is the wrong tool*, and `dforge://reference/reports`.
 
 ```dsl
 info('Created PO ' + po.po_number, {

package/resources/schemas/data-views.schema.json

@@ -247,11 +247,51 @@
 			"additionalProperties": false
 		},
 
+		"calculatedMember": {
+			"type": "object",
+			"description": "A synthetic, read-only member of a pivot-like view — a row (default) or column derived by a formula over other members at each cross-axis position. Platform-generic: any pivot-like surface consumes the same shape, so a module declares the metric in config with no platform code change. Pure presentation — no storage, evaluated client-side by the stock formula engine.",
+			"required": ["key", "label", "refs", "formula"],
+			"properties": {
+				"key": { "type": "string", "description": "Stable render key. Must not collide with a real member key." },
+				"axis": { "type": "string", "enum": ["row", "column"], "default": "row", "description": "Which axis the member is added to. A calculated ROW is a formula over other rows evaluated once per column; a calculated COLUMN is the transpose." },
+				"label": { "type": "string", "description": "Member label shown in the row/column head." },
+				"field": { "type": "string", "description": "Value field the refs read. Defaults to the surface's first value field." },
+				"refs": {
+					"type": "object",
+					"description": "Formula bracket-alias → referenced member identity on the same axis.",
+					"additionalProperties": { "type": "string" }
+				},
+				"formula": { "type": "string", "description": "Formula over the aliases, e.g. `[gp] / [rev] * 100`. Same `[name]` syntax as column formulas. A non-finite result (÷0, missing denominator) renders empty." },
+				"position": {
+					"description": "Placement on the axis. Defaults to the end.",
+					"oneOf": [
+						{ "type": "object", "required": ["after"], "properties": { "after": { "type": "string", "description": "Key of the member to place this one after." } }, "additionalProperties": false },
+						{ "type": "object", "required": ["at"], "properties": { "at": { "type": "string", "enum": ["end"] } }, "additionalProperties": false }
+					]
+				},
+				"depth": { "type": "integer", "minimum": 0, "description": "Indent depth (row members only; 0 = top level)." },
+				"format": {
+					"type": "object",
+					"description": "Display format for the result.",
+					"properties": {
+						"style": { "type": "string", "enum": ["number", "percent"], "default": "number" },
+						"decimals": { "type": "integer", "minimum": 0, "default": 1 }
+					},
+					"additionalProperties": false
+				}
+			},
+			"additionalProperties": false
+		},
 		"matrixViewConfig": {
 			"type": "object",
 			"description": "Matrix (pivot) view: rowAxis × colAxis grid with a value-source cell entity holding one record per (rowKey, colKey).",
 			"required": ["rowAxis", "colAxis", "cell"],
 			"properties": {
+				"calculatedMembers": {
+					"type": "array",
+					"description": "Synthetic read-only members derived by formula over OTHER members' values (e.g. a Gross Margin % row). Spliced into the rendered axis; never loaded or saved.",
+					"items": { "$ref": "#/$defs/calculatedMember" }
+				},
 				"rowAxis": {
 					"description": "Row axis values: an entity's records ('dataset') or a column's dropdown options ('dropdown').",
 					"oneOf": [

package/resources/schemas/manifest.schema.json

@@ -133,6 +133,12 @@
 			"items": { "type": "string", "pattern": "^[a-z]{2,3}(-[A-Z]{2})?$" },
 			"description": "Non-English locales the package promises to translate. Each entry MUST match a translations/<locale>.json file, and every translatable resource (entity/field labels, folders, views, menus + items, actions + params, reports + datasets + params, settings) MUST have a label in that file. English is the default — don't list 'en' or 'en-US'."
 		},
+		"features": {
+			"type": "array",
+			"items": { "type": "string", "enum": ["report-security"] },
+			"uniqueItems": true,
+			"description": "Opt-in platform behaviours this package was authored for. Absent or empty = the pre-feature behaviour for all of them, so a module written before a feature existed keeps working until its author declares it and republishes. Unknown names are REJECTED at package load, never ignored — a misspelled feature would silently leave the old behaviour in place while the manifest claims otherwise. Values: 'report-security' = this module's reports require 'E' on their sec_object; declare the matching \"report:<code>\": \"E\" grants in security/roles.json first, or the reports go dark for every role."
+		},
 		"created": {
 			"type": "string",
 			"format": "date",

package/resources/schemas/reports.schema.json

@@ -24,10 +24,42 @@
 					"description": "Map of dataset code → dataset definition. Panels reference datasets by code via `datasetCd`.",
 					"additionalProperties": { "$ref": "#/$defs/dataset" }
 				},
+				"reloadInterval": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Auto-refresh interval in seconds. Omit (or 0) for no auto-refresh."
+				},
 				"parameters": {
 					"type": "object",
-					"description": "Report-level parameters (alternative to per-dataset `params`). Map of param code → param definition.",
+					"description": "Report-level parameter declarations — the canonical home for a parameter, and the only one that fits a parameter several datasets use. Parameters are report-scoped throughout the platform: one `param_set` per report, `report.params.save` in the authoring API, and `report.get` flattens per-dataset defaults report-wide before use. A parameter declared under a dataset's `params` is shorthand for declaring it here; the installer merges both into one set, with this block winning on a code collision.",
 					"additionalProperties": { "$ref": "#/$defs/paramDef" }
+				},
+				"entities": {
+					"type": "array",
+					"description": "Record-report attachments: entities this report can be opened from, with the mapping from report parameter to source column on that entity. Each entry becomes one `dForge.entity_report` row. See docs/business-logic/record-reports.md.",
+					"items": { "$ref": "#/$defs/entityAttachment" }
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"entityAttachment": {
+			"type": "object",
+			"description": "One (entity, report) attachment. The binding is per-attachment, not per-report — the same report can attach to several entities with different parameter mappings.",
+			"required": ["entityCd"],
+			"properties": {
+				"entityCd": {
+					"type": "string",
+					"description": "Entity the report attaches to, qualified `module.entity` for anything outside the declaring module. The owning module must be this module or a declared dependency."
+				},
+				"params": {
+					"type": "object",
+					"description": "Parameter mapping: report param code → source column on the entity. Stored as `entity_report.param_map` and resolved server-side from the record's PK. Source columns are limited to the PK, reference (`R`) columns, and bounded scalars (number, date/datetime, bool, dropdown/radio/flags code); source and target must be type-compatible. Params left unmapped keep their normal behaviour (default value, or prompt the user).",
+					"additionalProperties": { "type": "string" }
+				},
+				"orderNum": {
+					"type": "integer",
+					"description": "Sort position in the record's combined action + report menu."
 				}
 			},
 			"additionalProperties": false
@@ -228,7 +260,7 @@
 				},
 				"params": {
 					"type": "object",
-					"description": "Dataset-level parameters (alternative to top-level `parameters`)",
+					"description": "Parameters declared on this dataset — shorthand for the report-level `parameters` block, convenient when exactly one dataset uses the parameter. Either way the parameter is REPORT-scoped: `ReportRegistrar` merges the report-level block and every dataset's `params` into the report's one `param_set`, so a parameter declared here serves the whole report (the param bar, saved param sets, `@param` filters in any dataset, and record-report `entities[].params` mappings). On a code collision the report-level block wins. Declare a parameter used by several datasets at report level — there is no meaningful dataset to attribute it to.",
 					"additionalProperties": { "$ref": "#/$defs/paramDef" }
 				}
 			},
@@ -314,41 +346,38 @@
 
 		"paramDef": {
 			"type": "object",
-			"required": ["fieldTypeCd"],
+			"not": { "required": ["fieldTypeCd", "domain"] },
 			"properties": {
 				"fieldTypeCd": {
 					"type": "string",
-					"description": "Field type code (see settings.schema.json for the common list)"
+					"description": "Field type code (see settings.schema.json for the common list). Omit when `domain` is set — the domain supplies the control. May also be omitted entirely: a param declaring neither key installs as `text` (ReportRegistrar.DefaultParamFieldTypeCd). The one rejected combination is declaring both."
+				},
+				"domain": {
+					"type": "string",
+					"description": "Column domain (`domain_cd` or `module_cd.domain_cd`) the parameter borrows its control and option list from. The options and their translations stay on the domain, so a list shared with an entity column is authored once. The DSL equivalent for action params is `paramCd: domain <domainCd>`.",
+					"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*(\\.[a-zA-Z_][a-zA-Z0-9_]*)?$"
 				},
 				"label": { "type": "string" },
 				"orderNum": {
 					"type": "integer",
 					"description": "Display order of the parameter in the report's parameter form. Read by ReportRegistrar (paramDef.OrderNum); falls back to declaration order when omitted."
 				},
+				"columnType": {
+					"type": "string",
+					"enum": ["R"],
+					"description": "Declares a REFERENCE parameter: its submitted value is the whole picked record rather than the bare key. The JSON counterpart of the action DSL's `paramCd: ref <entityCd>`, stored in the same `param.column_type`. Optional — omitting it (a plain `lookup`) submits the key, which is what a filter comparing against a reference column needs, since the server destructures a key object across every key column and ignores non-key fields. Declare \"R\" when the report wants the record itself, not just its identity."
+				},
 				"required": {
 					"type": "boolean",
 					"default": false,
-					"description": "Whether the user must provide a value (older modules also use `isRequired`)"
-				},
-				"isRequired": {
-					"type": "boolean",
-					"description": "Alternate spelling of `required` used by some modules. Prefer `required` for new code."
+					"description": "Whether the user must provide a value. Stored inverted as `param.is_nullable`. There is no `isRequired` spelling — `ReportParamDef` reads this key only."
 				},
 				"default": {
 					"description": "Default value applied if the user doesn't provide one"
 				},
-				"link": {
-					"type": "object",
-					"description": "Entity link for lookup-type params (alternative to nesting under `params.link`). Shape: { entity: '<code>', otherKey?: '<column>' }.",
-					"properties": {
-						"entity": { "type": "string" },
-						"otherKey": { "type": "string" }
-					},
-					"additionalProperties": false
-				},
 				"params": {
 					"type": "object",
-					"description": "Field-type-specific params (e.g. lookup → { link: { entity, otherKey } })"
+					"description": "Field-type-specific params, nested under this key — there is no top-level `link`. A `lookup` param needs `{ \"link\": { \"entity\": \"<code>\", \"otherKey\": \"<column>\" } }`; `otherKey` auto-fills from the target's PK when omitted. Without `params.link` a lookup param installs, warns, and has no autocomplete."
 				}
 			},
 			"additionalProperties": false

package/skills/dforge-mcp-author/references/action-dsl.md

@@ -11,11 +11,14 @@ An action exists to **change something**. Its message is a receipt for work that
 
 Do **not** write an action whose `execute:` block only reads data, computes a value and reports it with `info()`. The result is a line of text that is never stored: it can't be audited, referenced, re-read or reported on, and every reader has to re-run the action to see it again. The value also reaches the user unformatted — a raw `query()` result carries no column metadata, so money renders as `1000.0099999999999` instead of `1,000.01`.
 
+**Do not compute in the DSL what a report can compute.** Sums, ratios, ageing buckets, exposure, "how much is outstanding" — a report dataset already does aggregation, formatting, drill-through and row caps, and it re-reads live data every time it opens. DSL arithmetic over `select()` results reproduces that badly, once, in a place nothing else can reuse. Reach for the DSL when the number has to be **written down** or has to **stop** something; reach for a report when it has to be **looked at**.
+
 If you are about to write a `check_…`, `calculate_…` or `show_…` action, build one of these instead:
 
 | What's actually needed | Build this |
 |---|---|
-| The user needs to **see** current numbers | A **report** or a data view — both are metadata-driven, so values format correctly, and the user can return to them any time without re-running anything. |
+| The user needs to **see** current numbers **for the record they're on** | A **record report** — a report with an `entities` attachment, which puts it on that record's toolbar and feeds its params from the record. This is the direct replacement for a `check_…` action: same entry point, but the user sees the open invoices and the ageing, not just "FAILED". See `references/reports.md`. |
+| The user needs to **see** current numbers generally | A **report** or a data view — both are metadata-driven, so values format correctly, and the user can return to them any time without re-running anything. |
 | A derived value **belongs to the record** | A **formula column** (`columnType: "F"`) or a roll-up — computed on read, visible on the card and in grids, filterable and sortable. |
 | The **verdict itself matters** (approvals, credit checks, compliance) | An action that **writes a result record** — e.g. `credit_check(customer, checked_at, limit, outstanding, projected, verdict, checked_by)`. Now it's auditable and reportable, and `info()` becomes a legitimate receipt with a link to the new row. |
 | The check must **block** something | A **trigger** with `async: false`, or a `canExecute:` guard on the action being gated — enforcement, not narration. |
@@ -48,7 +51,7 @@ Each param is one line: `name: type [required] ["Label"]`
 
 ```
 params:
-    new_stage: dropdown required "New Stage"
+    new_stage: dropdown required "New Stage" options=[open:Open, won:Won, lost:Lost]
     note: textarea "Follow-up Note"
     adjustment_qty: number required "Adjustment Quantity"
     reason: text required "Reason"
@@ -58,6 +61,41 @@ Types are a subset of column field types: `text`, `textarea`, `number`, `currenc
 
 Access in execute block: `params[param_name]` (bracket syntax, NOT dot syntax).
 
+#### Dropdown params: label the options, or borrow a domain
+
+A bare `options=open,won,lost` stores codes with no labels, and the dialog shows `open` /
+`won` / `lost` in **every** locale, English included. Two ways to do better, in order of
+preference:
+
+1. **`domain <domainCd>`** — the param borrows a shared `column_domain`:
+
+   ```
+   params:
+       payment_method: domain payment_method required "Payment method for this batch"
+       status:         domain fin.doc_status optional "Status"   // module-qualified
+   ```
+
+   Use this whenever the choices are the same list a column uses — the usual case, since
+   the param's value normally ends up written to that column. Control and options come off
+   the domain, so the list and its translations live in **one** place instead of being
+   restated here and drifting from the column's. The param keeps its own caption. Nothing
+   may follow the description (`options=`, `min=` … are a compile error — the domain owns
+   them), and an unknown domain code fails the install.
+
+2. **Inline labels** — for a list that belongs to this parameter alone (a run mode, an
+   export format) and matches no column:
+
+   ```
+   params:
+       method:   dropdown required "Method" options=[bank_transfer:Bank transfer, cash:Cash]
+       priority: dropdown required "Priority" options=[{"value":"high","label":"High","color":"#c00"},"normal"]
+   ```
+
+   `value:Label` splits on the first colon; wrap the list in `[ ]` (or `" "`) when a label
+   contains a space, since the trailing `key=value` scan is whitespace-delimited. An option
+   object needs a non-empty string `value` — the stored code, and the key translations match
+   on. Per-locale labels: `actions.<cd>.params.<param_cd>.options` (`translations.md`).
+
 ### `canExecute:` — availability formula
 
 A formula expression (same grammar as formula columns) that evaluates to true/false. When false, the action button is hidden or disabled in the UI.

package/skills/dforge-mcp-author/references/column-domains.md

@@ -8,7 +8,7 @@ Schema: `dforge://schema/domains`.
 
 ## Why
 
-Without domains, every "status" column restates the same `fieldTypeCd: "dropdown"` + the full `params.options` list — and, if you localize, the same option translations, once per column. A domain declares that once; every consuming column inherits the type, the control, the options, **and** their translations. Localize `fin.doc_status` a single time and all its uses update together.
+Without domains, every "status" column — and every action param that writes to one — restates the same `fieldTypeCd: "dropdown"` + the full `params.options` list, and, if you localize, the same option translations, once per consumer. A domain declares that once; every consuming column **and parameter** inherits the type, the control, the options, **and** their translations. Localize `fin.doc_status` a single time and all its uses update together.
 
 ## `domains.json`
 
@@ -54,6 +54,24 @@ A column swaps its whole type block for a single `domain` key — qualified as `
 
 The column keeps what is genuinely its own — `description` (its label), `flags`, `orderNum`, `isNullable`, `isPk`, `columnGroupCd`. The domain supplies the rest.
 
+## Using a domain in an action / report param
+
+Parameters consume the same domain, so an action that writes to a domain-backed column offers exactly that column's choices instead of restating them:
+
+```
+params:
+    status: domain fin.doc_status required "New status"
+```
+
+```json
+"status": { "domain": "fin.doc_status", "label": "New status", "required": true }
+```
+
+- **Prefer this over inline `options=`** whenever the param's value ends up on a domain-backed column — otherwise the same enum is authored twice, translated twice, and free to drift (a param option whose code isn't on the column is a value the grid can't label).
+- Install materializes the domain's `fieldTypeCd` onto the param; its datatype and sizing don't apply, because a parameter has no storage. A domain with no `fieldTypeCd` is rejected — the param would have no control to render.
+- The param keeps its **own caption** (`"New status"` above) and translates it under `actions.<cd>.params.<param_cd>.label` as usual. Only the choices come from the domain, options translations included.
+- Nothing may follow the description in the DSL form — `options=`, `min=` and friends are a compile error there, same authority rule columns get. A report param declaring both `domain` and `fieldTypeCd` is rejected for the same reason.
+
 ## Rules (these fail the install)
 
 1. **Don't restate what the domain owns.** Declaring `dbDatatype`, `fieldTypeCd`, `maxLen`, `precision`, `baseDatatypeCd` or `params` alongside `domain` is rejected, naming the conflicting key — it is never silently overridden. Domains are authoritative.
@@ -78,7 +96,7 @@ An option override is a partial merged over the base — a bare string is shorth
 ## How it resolves (mental model)
 
 - **Install** materializes the domain's structural fields (datatype/control/sizing) onto each consuming column, because DDL generation needs them locally.
-- **Runtime** resolves `params` (the options) — and their per-culture overrides — from the domain, not the column. That is what lets a shared list be authored and translated once.
+- **Runtime** resolves `params` (the options) — and their per-culture overrides — from the domain, not the column *or the param*. That is what lets a shared list be authored and translated once.
 
 You don't act on this split; just know that the option list stays on the domain, so **don't** paste `params.options` onto a domain-backed column (the install rejects it).
 
@@ -90,5 +108,6 @@ You don't act on this split; just know that the option list stays on the domain,
 ## Common mistakes
 
 - Putting `params.options` on the column **and** naming a `domain` → install error. Options belong on the domain.
+- Restating a domain's list inline on an action param (`options=…`) instead of binding the param to the domain → compiles, but you now maintain and translate the same enum twice.
 - Using a cross-module domain without declaring the dependency → "unknown column domain" at install.
 - Expecting per-column option overrides — the domain is authoritative in v1; narrow with `optionSets` (which filters by `value`) if you need a conditional subset.

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

@@ -71,6 +71,35 @@ The manifest lists every file in the package by logical key. The installer reads
 | `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` |
+| `features` | string[] | Opt-in platform behaviours this package was authored for, e.g. `["report-security"]`. Absent/empty = the pre-feature behaviour. See **Feature opt-ins** below. |
+
+## Feature opt-ins
+
+`dependencies` answers "does the platform have this?". `features` answers "should this behaviour apply to **my** module?".
+
+They exist for opposite failure modes. A dependency is a hard gate — the module will not install without it. A feature is the reverse: the platform already has the behaviour, but switching it on for every installed module at once would break every package written before it existed. So it stays off per module until the author asks for it.
+
+```json
+"features": ["report-security"]
+```
+
+| Feature | Effect |
+|---|---|
+| `report-security` | This module's reports require the `E` right on their security object — checked when running or opening a report and when reading or changing its saved presets and panel layouts. Without it, a report is reachable by anyone who can read the underlying data. |
+
+**Adopting one is two releases, in order:**
+
+1. Add `"report:<report_code>": "E"` to every role in `security/roles.json` that should reach each report. Bump `version`, install.
+2. Add `"features": ["report-security"]`. Bump `version` again, install.
+
+Do it in the other order and every report in the module denies for every role until the grants land. Both steps need a version bump — a same-version install is skipped, so the tenant would keep the old manifest.
+
+**Rules:**
+
+- Unknown names are **rejected** at package load, not ignored. A misspelled `report-securty` would otherwise leave the old behaviour in place while the manifest claims the protection is on.
+- Casing and surrounding whitespace are normalised; the canonical spelling is lowercase.
+- Removing a feature genuinely removes it on the next install — an opt-in is a migration window, not a one-way door.
+- Installing against an older platform that predates the feature is safe: unknown manifest keys are ignored there, so the module runs the old behaviour.
 
 ## Dependencies