@dforge-core/dforge-mcp 0.2.4 → 0.2.14

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

@@ -7,7 +7,7 @@ SP files: `logic/reports/rpt_*.sql`
 
 ## Structure
 
-A report has `description`, a `datasets` map, a `layout` object (`{ panels: [...] }`), and optional `parameters`. Panels reference datasets by code via `datasetCd`.
+A report has `description`, a `datasets` map, a `layout` object (`{ panels: [...] }`), optional per-dataset `params`, and an optional `entities` array (record-report attachments). Panels reference datasets by code via `datasetCd`.
 
 ```json
 {
@@ -17,12 +17,18 @@ A report has `description`, a `datasets` map, a `layout` object (`{ panels: [...
             "pipeline": {
                 "caption": "Pipeline Data",
                 "datasetType": "Q",
+                "params": {
+                    "min_amount": { "fieldTypeCd": "number", "label": "Min Amount", "required": false, "default": 0 }
+                },
                 "query": {
                     "entityCd": "opportunity",
                     "columns": ["stage", "amount", "lead_source", "customer.name"],
                     "filter": {
                         "g": "and",
-                        "i": [ { "c": "stage", "o": "nIn", "v": ["Closed Won", "Closed Lost"] } ]
+                        "i": [
+                            { "c": "stage", "o": "nIn", "v": ["Closed Won", "Closed Lost"] },
+                            { "c": "amount", "o": "grEq", "v": "@min_amount" }
+                        ]
                     },
                     "sort": [ { "c": "amount", "d": "desc" } ]
                 }
@@ -38,9 +44,6 @@ A report has `description`, a `datasets` map, a `layout` object (`{ panels: [...
                 },
                 { "vizType": "table", "datasetCd": "pipeline", "title": "Pipeline Detail" }
             ]
-        },
-        "parameters": {
-            "min_amount": { "fieldTypeCd": "number", "label": "Min Amount", "required": false, "default": 0 }
         }
     }
 }
@@ -85,7 +88,7 @@ For SQL the query builder can't express — window functions, CTEs, cross-schema
     "spCd": "rpt_ar_aging",
     "params": {
         "as_of_date": { "fieldTypeCd": "date", "label": "As of Date", "required": true, "default": "=NOW()" },
-        "customer_id": { "fieldTypeCd": "lookup", "label": "Customer", "required": false, "params": { "entityCd": "account" } }
+        "customer_id": { "fieldTypeCd": "lookup", "label": "Customer", "required": false, "params": { "link": { "entity": "account" } } }
     },
     "columnsDef": {
         "customer_name": { "label": "Customer", "fieldTypeCd": "text", "baseDatatypeCd": "string", "width": 200 },
@@ -99,7 +102,7 @@ Key differences from entity datasets:
 - `datasetType: "S"`.
 - `spCd` — the stored-procedure code (the function name **without** the schema prefix; resolved to `sp_id` at install). (**Not** `sp` or `procedureName`.)
 - `columnsDef` — **required** — the platform can't infer columns from a function.
-- Params can be per-dataset or per-report.
+- Params work exactly as they do for an entity dataset, and `datasetType` makes no difference: declare them at report level (`parameters`) or on the dataset (`params`). Report level wins on a code collision.
 
 **Multi-result-set SPs** map extra datasets to the same function via `parentDatasetCd` (the dataset that owns the SP call) + `parentRef` (the named refcursor):
 
@@ -139,25 +142,50 @@ $$;
 
 ## Parameters
 
-Parameters prompt the user before running the report. Declare them per-report (`parameters`) or per-dataset (`params`).
+Parameters prompt the user before running the report.
+
+**Parameters are report-scoped**, so there are two legal declaration sites and they mean the same thing:
+
+- **`parameters`** at report level — the canonical home, and the only one that fits a param several datasets use.
+- **`datasets.<cd>.params`** — shorthand, fine when exactly one dataset uses it. Every module written before this existed uses it, and it stays fully supported.
+
+The installer merges both into the report's single param set (**report level wins** on a code collision), so either way the param serves the whole report: the param bar, saved param sets, `@param` filters in *any* dataset, and record-report mappings.
+
+> Why report-scoped: the declaration is stored once per report (`report.param_set_id` → `param_set`), the authoring API is `report.params.save`, and `report.get` flattens per-dataset defaults report-wide before use. There is no dataset-scoped parameter behaviour to choose between.
 
 ```json
 "parameters": {
-    "start_date": { "fieldTypeCd": "date", "label": "Start Date", "required": true, "default": "=STARTMONTH()" },
-    "region": { "fieldTypeCd": "dropdown", "label": "Region", "params": { "options": ["All", "North", "South"] } },
-    "customer": { "fieldTypeCd": "lookup", "label": "Customer", "params": { "entityCd": "account" } }
+    "customer": { "fieldTypeCd": "lookup", "label": "Customer", "params": { "link": { "entity": "account" } } }
+},
+"datasets": {
+    "sales": {
+        "datasetType": "Q",
+        "params": {
+            "start_date": { "fieldTypeCd": "date", "label": "Start Date", "required": true, "default": "=STARTMONTH()" },
+            "status":   { "domain": "fin.doc_status", "label": "Status" },
+            "region": { "fieldTypeCd": "dropdown", "label": "Region", "params": { "options": [
+                { "value": "north", "label": "North" }, { "value": "south", "label": "South" }
+            ] } }
+        },
+        "query": { "entityCd": "invoice", "columns": ["invoice_number", "total"] }
+    }
 }
 ```
 
 | Property | Description |
 |---|---|
-| `fieldTypeCd` | Control type: `date`, `datetime`, `text`, `number`, `dropdown`, `lookup`, `user`, `checkbox` |
+| `fieldTypeCd` | Control type: `date`, `datetime`, `text`, `number`, `dropdown`, `lookup`, `user`, `checkbox`. Omit when `domain` is set. |
+| `domain` | Column domain (`domain_cd` or `module_cd.domain_cd`) supplying the control **and** the option list. Mutually exclusive with `fieldTypeCd` — declaring both is rejected at install. |
 | `label` | Display label in the parameter dialog |
 | `required` | Whether the user must fill this before running |
 | `default` | Plain value or `=`-prefixed formula (`"=NOW()"`, `"=STARTMONTH()"`, `"=TODAY()"`) |
-| `params` | Extra config — `options` for dropdowns, `entityCd` for lookups |
+| `params` | Extra config — `options` for dropdowns, `link: { entity, otherKey? }` for lookups |
 | `orderNum` | Display order in the parameter form (falls back to declaration order) |
 
+Two spellings that look right and are silently ignored: **`isRequired`** (the key is `required`, so the param installs as optional) and a **top-level `link`** (it must be nested under `params`, so the lookup installs with no autocomplete). Both are validator errors.
+
+**Dropdown params: prefer `domain`, and never ship bare codes.** A list shared with a column belongs on a `column_domain` — bind the param to it and the options plus their translations are authored once (`column-domains.md`). For a list that exists only for this report, write the rich option form (`{ "value": "north", "label": "North" }`); a bare `"options": ["north", "south"]` renders the raw codes in **every** locale, English included. Per-locale labels go under `reports.<cd>.params.<param_cd>.options` (`translations.md`).
+
 Reference a parameter with `@param_code` inside a query filter value:
 
 ```json
@@ -254,14 +282,72 @@ Dashboard KPI/chart *tiles* get the same support via a `sources` map in the tile
 
 `config.chartSize` ∈ `sm | m | l | xl` controls the default chart height (`m` when omitted).
 
+## Record reports (`entities`)
+
+A report can be **attached to an entity** so it opens from a record — the way a print template does — with the record's values feeding its parameters. Add an `entities` array to the report:
+
+```json
+"credit_check": {
+    "description": "Customer Credit Check — limit against outstanding AR and open quotes",
+    "entities": [
+        { "entityCd": "parties.party", "params": { "customer_id": "party_id" }, "orderNum": 45 },
+        { "entityCd": "crm.quote",     "params": { "customer_id": "customer_id" }, "orderNum": 45 }
+    ],
+    "parameters": {
+        "customer_id": {
+            "label": "Customer",
+            "fieldTypeCd": "lookup",
+            "params": { "link": { "entity": "parties.party" } },
+            "required": true
+        }
+    },
+    "layout": { "panels": [ { "vizType": "table", "datasetCd": "open_invoices" } ] },
+    "datasets": {
+        "open_invoices": {
+            "caption": "Open Invoices",
+            "datasetType": "Q",
+            "query": {
+                "entityCd": "invoice",
+                "columns": ["invoice_number", "due_date", "amount_due"],
+                "filter": { "g": "and", "i": [ { "c": "customer_id", "o": "eq", "v": "@customer_id" } ] }
+            }
+        }
+    }
+}
+```
+
+Each entry becomes one attachment row, and the report gains a toolbar entry on that entity's record. Note the two different `params` keys:
+
+- `entities[].params` — the **mapping**: report param code → **source column on the attached entity**.
+- `parameters` / `datasets.<cd>.params` — the param **declaration**. The mapping can only name codes declared in one of those.
+
+| Rule | Detail |
+|---|---|
+| `entityCd` | Qualified `module.entity` for anything outside this module, and that module must be a **declared dependency**. |
+| Source columns | The entity PK, a reference (`R`) column, or a bounded scalar (number, date/datetime, bool, dropdown/radio/flags code). `text`, `json`, `file`/`image` are rejected. |
+| Types | Source and target must be compatible; only `lookup`↔`number` and `date`↔`datetime` widen. A names-only match like `{ "customer_id": "created_date" }` is an error, not a runtime surprise. |
+| One per pair | One attachment per (entity, report). Two entries for the same entity overwrite each other. |
+| Unmapped params | Keep their normal behaviour — default value, or prompt the user. |
+| Mapped params | Are **hidden** on the record-report page. The URL is about this record; pivoting means going back to a record. |
+| Dependency | Declare `"metadata": ">=1.5.0"` — the attachment table ships with the metadata system module, so this is the gate that fails loudly on an older platform instead of the attachment quietly doing nothing. This is metadata's **`version`**; dependency ranges are never checked against `dbSchemaVersion`, so do not use the `1.4.0` of the migration that creates the table. |
+| Rights | Report `E` is still required. A bridge role must grant `E` on the report **and** `S` on the dataset entities. |
+
+There is no `canExecute` on an attachment: if the record exists the report is meaningful for it, and an empty report is a legitimate answer.
+
+> **Prefer a record report over an action that calculates.** See *When an action is the wrong tool* in `references/action-dsl.md`. If the `execute:` block only reads, computes and `info()`s a number, it is not an action — a printed number is never stored, can't be re-read, and shows the verdict without the working. Attach a report instead: it gets you KPI tiles, charts, the underlying rows, drill-through, saved layouts and row caps for free, and the DSL you don't write is DSL that can't drift from the data.
+>
+> Keep it an action when it **changes** something — writing the result to a column, creating a record, or *blocking* a transition. "Explain the number" is a report; "refuse the over-limit quote" is an action or trigger.
+
 ## Grants
 
-Grant report access with the `E` right:
+Grant report access with the `E` right — a **colon** prefix, never a dot:
 
 ```json
-"rights": { "report.sales_pipeline": "E" }
+"rights": { "report:sales_pipeline": "E" }
 ```
 
+A dependency's report is granted with the qualified form, `"report:fin.ar_aging": "E"` — bridge modules need this to grant on a report they attach but do not own.
+
 ## Common mistakes
 
 - Using a bare `"layout": [ ... ]` array — `layout` is an **object**: `"layout": { "panels": [ ... ] }`.
@@ -270,5 +356,11 @@ Grant report access with the `E` right:
 - Using `sp` / `procedureName` for an SP dataset — the field is `spCd`.
 - Forgetting `columnsDef` on an SP dataset — **required**.
 - Forgetting to grant `E` on the report in at least one role — it becomes invisible.
+- Writing the rights key as `report.<code>` — actions/reports/folders take a **colon**: `report:<code>`.
+- Writing `isRequired` instead of `required`, or a top-level `link` instead of `params.link` — both are ignored at install.
+- Declaring both `fieldTypeCd` and `domain` on one param — install rejects the pair rather than picking a winner.
+- Mapping a record-report attachment onto a param no dataset declares, or from a `text`/`json` column — both are rejected.
+- Attaching a report to another module's entity without declaring that module as a dependency.
 - Forgetting `p_folder_uid` / `p_user_id` as the first two SP function params — the call fails.
 - Referencing a parameter as `$param` — use `@param_code` in filters.
+- Writing an action that computes a number and `info()`s it, where a record report would show the working.

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

@@ -82,8 +82,8 @@ Translation files mirror the module's content structure. Each translatable objec
 | `roles` | Role display labels | Role codes (keys from `security/roles.json`, already module-qualified — e.g. `crm.admin`) → `{ label }` |
 | `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 } } }` |
+| `actions` | Action labels, descriptions, param labels **and param dropdown option labels** | Action codes (keys from `ui/actions.json`) → `{ label, desc, params: { param_cd: { label, options: { value: … } } } }` |
+| `reports` | Report dataset captions, param labels **and param dropdown option labels** | Report codes → `{ datasets: { ds_cd: { caption } }, params: { param_cd: { label, options: { value: … } } } }` |
 | `entities.<e>.constraints` | Check/unique constraint violation messages (opt-in — warned, not enforced) | Constraint codes → `{ message }` under the owning entity |
 | `entities.<e>.fields.<f>.options` | Dropdown/radio/flags **option labels** (opt-in) | Option `value` → localized label (string) or `{ label, icon, color }` |
 | `domains` | Column domain labels **and** their shared option labels (opt-in) | Domain codes → `{ label, options: { value: … } }` |
@@ -146,7 +146,33 @@ If a column uses a **domain** (see `column-domains.md`), translate the domain **
 ```
 
 - Keys are domain codes from this module's `domains.json`. The `options` map uses the same value-keyed, partial-override shape as field options above.
-- This is the whole point of domains for localization: the shared option list is authored and translated in one place. Don't also translate the consuming columns' options — they inherit from the domain.
+- This is the whole point of domains for localization: the shared option list is authored and translated in one place. Don't also translate the consuming columns' options — they inherit from the domain. **Nor the params bound to it** — an action or report parameter declared as `domain <domainCd>` inherits from the same place.
+
+### Action / report PARAM option labels ARE translatable (opt-in)
+
+A `dropdown` **parameter** carries per-value labels exactly like a column, and translates them under an `options` map next to the param's `label`:
+
+```json
+"actions": {
+    "distribute_payment": {
+        "params": {
+            "payment_method": {
+                "label": "Zahlungsart",
+                "options": {
+                    "bank_transfer": { "label": "Überweisung" },
+                    "cash": "Bar"
+                }
+            }
+        }
+    }
+}
+```
+
+- Same shape and rules as field options: value-keyed, partial override merged over the base, bare string = `{ "label": … }`, only `label`/`icon`/`color` translatable, `value` never.
+- The same section works for `reports.<report_cd>.params.<param_cd>.options`.
+- A param may translate **only** its options and keep the authored caption — omit `label`.
+- **This requires base labels in the DSL.** `options=bank_transfer,cash` stores bare codes, and the dialog shows `bank_transfer` in *every* locale including English until you write `options=[bank_transfer:Bank transfer, cash:Cash]` (or the JSON object form). See `action-dsl.md`.
+- **Prefer a domain.** If the param's choices are the same list a column uses — which they usually are, since the value normally ends up written to that column — declare the param as `domain <domainCd>` and skip this section entirely: it inherits the domain's translated options. Reach for per-param `options` only when the list belongs to that one parameter and matches no column.
 
 ### Roles ARE translated — and completeness is enforced
 

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

@@ -73,6 +73,9 @@ For each entity:
 - [ ] Each source has `entityCode` and `columns`
 - [ ] `entityCode` points to an entity that exists
 - [ ] Column codes in `columns` all exist on the entity
+- [ ] No `columns` entry is a **set** (`columnType: "S"`) — a 1:N collection has no per-row value to put in a column; show it on the record card instead. **Rejected at validate/pack**
+- [ ] No `columns` entry is a **dotted navigation path** (`owner.email`, `account.company_name`) — a view's column list is matched against the entity's own columns, so a dotted entry resolves to nothing. Add a Reference (`R`) or Formula (`F`) column to the entity and list that. **Rejected at validate/pack**
+- [ ] A listed column does **not** need `V` in its flags — the renderer promotes anything the list names (that is how trait-contributed `created_by_user`, flagged `I`, appears). Listing a non-`V` column is valid intent, not a mistake
 - [ ] The rendered entity has **at least one visible scalar column** (a field with `V` in `flags`, `columnType` not `S`) — a grid/list/kanban/etc. view over an entity whose fields are all hidden (or only sets) is **rejected** at validate/pack and would render "No visible columns configured for this entity." `diagram`/`matrix`/`library` are exempt
 - [ ] If set, `viewType` is from the supported list (`grid`, `list`, `kanban`, `calendar`, `gallery`, `tree-grid`, `diagram`, `master-detail`, `library`, `matrix`)
 - [ ] A `matrix` view has a `viewConfig` with `rowAxis`, `colAxis`, and `cell` (cell `entity` matches the primary `dataSources` entity; `rowKey`/`colKey` are real cell columns)
@@ -89,6 +92,16 @@ For each entity:
 - [ ] Every `reportCode` points to a report that exists
 - [ ] `orderNum` is set on each node for deterministic ordering
 
+## Reports (`ui/reports.json`)
+
+- [ ] Params are declared in the report-level `parameters` block, or under `datasets.<cd>.params` — a param several datasets use belongs at report level (the installer merges both; report level wins on a collision)
+- [ ] Params use `required` (not `isRequired`), and a lookup nests its binding as `params: { link: { entity } }` (not a top-level `link`)
+- [ ] No param declares both `fieldTypeCd` and `domain`
+- [ ] `layout` is an object (`{ "panels": [...] }`), and the chart kind is `config.chartType` with `vizType: "chart"`
+- [ ] Record-report attachments (`entities`): every mapped param code is declared at report level or on a dataset; every source column is the PK, a reference (`R`) column, or a bounded scalar; cross-module `entityCd` is qualified and its module is a declared dependency
+- [ ] A module with attachments declares `"metadata": ">=1.5.0"`
+- [ ] No `check_…` / `calculate_…` action exists that a record report should be
+
 ## Security
 
 - [ ] `security/roles.json` exists (at least one role)

package/skills/dforge-module-build/SKILL.md

@@ -172,9 +172,12 @@ to fill a sub-step** — a pure CRUD module skips Phase 2 entirely (record it wi
 
 **2a Actions.** First check the action is an action at all: it must **change**
 something. If the `execute:` block would only read, compute and `info()` the
-answer, build a report, a formula column, or an action that writes a result
-record instead — a printed number is never stored and can't be re-read
-(`dforge://reference/action-dsl`, *When an action is the wrong tool*). Then load
+answer, build a **record report** (a report with an `entities` attachment — same
+toolbar entry point, but it shows the working and re-reads live data), a formula
+column, or an action that writes a result record instead — a printed number is
+never stored and can't be re-read (`dforge://reference/action-dsl`, *When an
+action is the wrong tool*). Do not compute in DSL what a report dataset already
+aggregates. Then load
 all four resources in the action row — the wrong-field-access /
 wrong-batch-flag / wrong-`ui/actions.json`-property mistakes only surface when
 you cross-check them. Draft the DSL, run
@@ -219,10 +222,31 @@ pointing at the views.
 
 If none fire, skip specialized views for that entity.
 
-**3c. Reports** only when aggregation/grouping isn't covered by views.
+**3c. Reports** only when aggregation/grouping isn't covered by views — or when
+Phase 2a sent you here because the "action" only wanted to show a number.
+
+Params are **report-scoped**: declare them in the report-level `parameters`
+block, or as shorthand under `datasets.<cd>.params` when exactly one dataset uses
+the param. The installer merges both into the report's one param set, report level
+winning on a collision — so a param several datasets share belongs at report level.
+Grant with a **colon** key: `"report:<code>": "E"`.
+
+A report that answers a question *about one record* takes an `entities`
+attachment, which puts it on that record's toolbar with the record's values
+feeding its params:
+
+```json
+"entities": [ { "entityCd": "parties.party", "params": { "customer_id": "party_id" }, "orderNum": 45 } ]
+```
+
+`entities[].params` is the **mapping** (report param → source column), not a
+param declaration. Qualify a cross-module `entityCd` and declare that module as a
+dependency; add `"metadata": ">=1.5.0"` too. Source columns are limited to the
+PK, a reference column, or a bounded scalar. Full rules:
+`dforge://reference/reports`.
 
 **Exit:** every entity has a grid and a menu entry; every specialized view has a
-stated trigger.
+stated trigger; every report's params sit on a dataset.
 
 ## Phase 4 — Polish (mostly optional)