@dforge-core/dforge-mcp 0.1.11 → 0.2.0

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

@@ -0,0 +1,94 @@
+# Column Domains Reference
+
+A **column domain** is a reusable, named field type — a base datatype, a control, sizing, and a shared option list under one code. Columns reference it instead of restating the definition. Use one whenever the same enum or typed column repeats across entities (a `Draft/Posted/Reversed` status, a currency code, a priority, an account type).
+
+Lives in: `domains.json` at the module root (a flat map `domain_cd → definition`).
+
+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.
+
+## `domains.json`
+
+```json
+{
+    "doc_status": {
+        "description": "Document Status",
+        "baseDatatypeCd": "string",
+        "dbDatatype": "varchar",
+        "maxLen": 20,
+        "fieldTypeCd": "dropdown",
+        "params": {
+            "options": [
+                { "value": "draft", "label": "Draft" },
+                { "value": "posted", "label": "Posted", "color": "#0a0" }
+            ]
+        }
+    }
+}
+```
+
+| Key | Required | Notes |
+|---|---|---|
+| `baseDatatypeCd` | **yes** | What a consuming column's DDL is generated from (`string`, `number`, `date`, …). |
+| `description` | no | Label. Localizable — see below. |
+| `dbDatatype` | no | Physical Postgres type; omit to infer from `fieldTypeCd`. |
+| `fieldTypeCd` | no | Control (`dropdown`, `text`, `number`, …). |
+| `maxLen` / `precision` | no | Sizing for string / numeric domains. |
+| `params` | no | Shared field-type config — most importantly `options` for `dropdown`/`radio`/`flags`. |
+
+## Using a domain in an entity
+
+A column swaps its whole type block for a single `domain` key — qualified as `module_cd.domain_cd`, or bare for a domain in the current module (unqualified resolves the current module first, then tenant-created domains):
+
+```json
+"status": {
+    "domain": "fin.doc_status",
+    "flags": "VEM",
+    "orderNum": 40,
+    "description": "Status"
+}
+```
+
+The column keeps what is genuinely its own — `description` (its label), `flags`, `orderNum`, `isNullable`, `isPk`, `columnGroupCd`. The domain supplies the rest.
+
+## 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.
+2. **Scalar columns only.** A reference (`R`) or set (`S`) column can't use a domain — it has no datatype for the domain to supply. Drop the `domain` key on those.
+3. **Declare the dependency for cross-module use.** `"domain": "fin.doc_status"` resolves by looking the domain up in the installed tenant, so declare `fin` in the manifest `dependencies` — dependencies drive install order, and without it nothing guarantees `fin` is installed first, so the resolve fails with "references unknown column domain".
+
+## Localizing a domain (and its options)
+
+Translate a domain **once** in `translations/<locale>.json` under a top-level `domains` section — its label and its per-option labels flow to every consuming column:
+
+```json
+"domains": {
+    "doc_status": {
+        "label": "Belegstatus",
+        "options": { "draft": "Entwurf", "posted": { "label": "Gebucht", "color": "#0a0" } }
+    }
+}
+```
+
+An option override is a partial merged over the base — a bare string is shorthand for `{ "label": … }`; `value` is the stored code and is never translated. See `translations.md` ("Dropdown option localization").
+
+## 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.
+
+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).
+
+## When NOT to use a domain
+
+- A one-off column whose type/options appear nowhere else — inline it (`fieldTypeCd` + `params.options`) and skip the indirection.
+- Anything non-scalar (references, sets, formulas).
+
+## Common mistakes
+
+- Putting `params.options` on the column **and** naming a `domain` → install error. Options belong on the domain.
+- 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/document-extraction.md

@@ -0,0 +1,113 @@
+# Document Extraction Reference (OCR)
+
+dForge turns uploaded documents (PDFs, scans, photos) into structured records via a generic OCR service plus a per-module **field schema**. The load-bearing principle: **OCR is schema-agnostic, the module owns the schema.** The platform service is a write-once "document + schema → fields" engine; every new document type is a new schema in *your* module, never a change to the service.
+
+Two DSL built-ins do the work, both host functions callable from `logic/actions/*.dsl`:
+
+- `ocrExtract(...)` — send a file to the OCR endpoint, get structured fields back.
+- `detectDocument(rawText)` — score a document's text against your profiles' detect rules to guess its type.
+
+The OCR endpoint URL is a module setting (commonly `ocr_endpoint_url`), read with `getSetting('ocr_endpoint_url')`.
+
+## `ocrExtract()`
+
+Three forms, from raw to managed:
+
+**v1 — raw bundle** (back-compat; returns a JSON **string**, you `JSON.parse` it):
+```
+var raw = ocrExtract([doc_file], getSetting('ocr_endpoint_url'))        // hints optional (array | string | object)
+```
+
+**v2 — inline schema** (explicit opt-in via `opts.mode`; returns the **parsed** object):
+```
+var r = ocrExtract([doc_file], getSetting('ocr_endpoint_url'), schema, { mode: 'extract' })
+// r → { fields, confidence?, unmatched, raw_text, meta }
+```
+
+**v2 — extraction profile** (the managed path; schema lives in a row, not inline):
+```
+var r = ocrExtract([doc_file], getSetting('ocr_endpoint_url'), null, { profile: 'proc.bill_of_lading' })
+```
+
+Notes:
+- v2 is selected **only** by `opts.mode` (`'extract' | 'summary' | 'raw'`) or `opts.profile`. A bare object third arg *without* `opts.mode` stays on the v1 hints contract — so passing a schema object alone does **not** switch to v2.
+- `opts.profile` implies `mode: 'extract'` and is mutually exclusive with an inline `schema`. Unqualified profile codes resolve the action's own module first, then tenant-created rows. Missing/inactive profiles fail loudly.
+- The parsed response is `{ fields, confidence?, unmatched, raw_text, meta }` — map `r.fields.<name>` straight into `insert()`.
+
+## The `schema:` block (inline)
+
+Declare the field schema next to the mapping, in a `schema:` block in the action `.dsl`. It compiles verbatim into `var schema = {…}`, so it's a **JS object-literal body** — entries comma-separated, **string values quoted** (`type: 'string'`, not `type: string`, which fails the compile with `'string' is not defined`):
+
+```
+schema:
+  bl_no:        { type: 'string', description: "Bill of lading number (label 'B.L. No.')" },
+  container_no: { type: 'string', description: 'ISO 6346 container number' },
+  issue_date:   { type: 'date' }
+
+execute:
+  var r = ocrExtract([doc_file], getSetting('ocr_endpoint_url'), schema, { mode: 'extract' })
+  var bl = insert('bill_of_lading', { bl_no: r.fields.bl_no, issue_date: r.fields.issue_date })
+  if (r.fields.container_no != null) {
+    insert('container', { bill_of_lading_id: bl.bill_of_lading_id, container_no: r.fields.container_no })
+  }
+```
+
+Each field descriptor carries a `type` (`string` | `date` | `number` | …) and an optional `description` — the human-language hint the recognizer/LLM uses to find it. Keep descriptions concrete ("label 'B.L. No.'", "ISO 6346 container number").
+
+## Extraction profiles — `logic/extraction_profiles.json`
+
+The managed evolution of the inline `schema:` block: the same field schema stored as a row in `dForge.extraction_profile` (a platform-managed entity), so it's editable in the admin UI and reusable across actions. Mirrors the print-template lifecycle.
+
+```json
+{
+    "bill_of_lading": {
+        "description": "Ocean bill of lading",
+        "docType": "bill_of_lading",
+        "schema": {
+            "bl_no":        { "type": "string", "description": "Bill of lading number (label 'B.L. No.')" },
+            "container_no": { "type": "string", "description": "ISO 6346 container number" },
+            "issue_date":   { "type": "date" }
+        },
+        "detect": {
+            "signals": [
+                { "regex": "bill of lading", "weight": 3 },
+                { "regex": "B/?L\\s*No", "weight": 2 }
+            ],
+            "threshold": 4
+        }
+    }
+}
+```
+
+- **Keyed by `profile_cd`** (no `.` — it collides with the `module.profile` qualified form).
+- **Registered on install** by `(module_id, profile_cd)`; profiles dropped from the manifest are **reaped** on upgrade; uninstall removes the module's rows. Tenant-created profiles (`module_id IS NULL`) are authored in the admin UI and never touched by install.
+- Reference at runtime with `ocrExtract(..., null, { profile: 'module_cd.profile_cd' })`.
+
+## `detectDocument()` — doc-type auto-detect
+
+A profile's optional `detect` rules let the platform guess a document's type before you extract. `detectDocument(rawText)` scores every reachable profile's `signals` (case-insensitive regexes, summed weights, per-pattern timeout) and returns the best profile at/above its `threshold`:
+
+```
+execute:
+  var det = detectDocument(data.raw_text)     // → { profile: 'proc.bill_of_lading', docType: 'bill_of_lading', score } | null
+  if (det != null && det.docType != null) { [doc_type] = det.docType }
+  var r = ocrExtract([doc_file], getSetting('ocr_endpoint_url'), null, { profile: det.profile })
+```
+
+- Returns `{ profile, docType, score }` (the profile code is already module-qualified, ready to pass to `ocrExtract`) or `null`.
+- **Advisory by design** — malformed rules are skipped, and the returned type is a suggestion; let the human confirm before committing an irreversible mapping.
+- `rawText` is typically `ocrExtract`'s `raw_text` (or a v1 raw bundle's text) from a first pass.
+
+## Typical intake flow
+
+1. User uploads a file to an intake record (a `file`/`image` column).
+2. An action runs OCR once to get `raw_text`, calls `detectDocument(raw_text)` to suggest the type, and stores the suggestion for the user to confirm.
+3. On confirm, `ocrExtract(..., { profile })` returns structured `fields`; the action `insert()`s the target record(s), applying resolution transforms (`lookupRef`, `matchCatalog`, `parseMoney`) for anything that needs turning into a DB ref.
+
+## Common mistakes
+
+- Passing a schema object as the third arg **without** `{ mode: 'extract' }` — that's still v1 (raw string), not v2.
+- Unquoted values in a `schema:` block (`type: string`) — compile fails; quote them.
+- A `profile_cd` containing `.` — rejected (reserved for the `module.profile` form).
+- Treating `detectDocument` as authoritative — it's advisory; confirm the type before an irreversible write.
+- Forgetting the OCR endpoint is a **setting** — read it with `getSetting(...)`, don't hardcode.

package/skills/dforge-mcp-author/references/field-types.md

@@ -10,6 +10,8 @@ Source of truth: `server/database/system-modules/metadata/seed-data/field_types.
 >
 > Reference (`columnType: "R"`) and formula (`columnType: "F"`) columns never get a `dbDatatype` at all.
 
+> **Repeating the same type across columns?** If several columns share a datatype + control + option list (a `Draft/Posted/…` status, a currency, a priority), define a **column domain** once and reference it with a single `domain` key instead of restating `fieldTypeCd` + `params.options` each time — the options (and their translations) are then authored once for all consumers. See `dforge://reference/column-domains`.
+
 ## String-backed
 
 | `fieldTypeCd` | `baseDatatypeCd` | Description | Common `dbDatatype` | Params |

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

@@ -18,11 +18,14 @@ The same grammar applies everywhere.
 
 - **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
+- **Literals**: numbers (`42`, `3.14`), strings in **single quotes** (`'hello'`; embed a quote by doubling it: `'it''s'`), booleans (`true`, `false`), null (`null`). Double quotes are **not** string delimiters — `"hello"` is a lex error
+- **Operators**: `+`, `-`, `*`, `/`, `=`, `!=`, `<`, `>`, `<=`, `>=`, `AND`, `OR`, `NOT`, `IN`, `BETWEEN … AND …`, `CONTAINS`, `STARTS_WITH`, `ENDS_WITH`. Equality is a **single** `=` — `==` is a syntax error. There is no `%` operator; use `MOD(a, b)`
+- **Function calls**: `FUNCTION_NAME(arg1, arg2, ...)` — uppercase by convention. Only the functions listed below exist; any other name is rejected at module install (see "Unknown functions" below)
 - **Parentheses** for grouping
 
+`CONTAINS` / `STARTS_WITH` / `ENDS_WITH` are infix operators, not functions — write
+`[note] CONTAINS 'urgent'`, never `CONTAINS([note], 'urgent')`.
+
 ## Examples
 
 ```
@@ -34,15 +37,17 @@ The same grammar applies everywhere.
 
 [account].[billing_address].[country]
 
-[status] == "active" AND [balance] > 0
+[status] = 'active' AND [balance] > 0
+
+TODAY() > [due_date] AND [total_paid] < [total]
 
-CASE([priority], "high", 3, "medium", 2, "low", 1, 0)
+SWITCH([priority], 'high', 3, 'medium', 2, 'low', 1, 0)
 
-IF([total] > 1000, "large", "small")
+IF([total] > 1000, 'large', 'small')
 
-COALESCE([nickname], [first_name], "Unknown")
+COALESCE([nickname], [first_name], 'Unknown')
 
-FORMAT([created_date], "yyyy-MM-dd")
+FORMAT([created_date], 'yyyy-MM-dd')
 ```
 
 ## Built-in functions
@@ -50,21 +55,27 @@ FORMAT([created_date], "yyyy-MM-dd")
 ### String functions
 
 - `CONCAT(a, b, ...)` — concatenate strings
-- `LEN(s)` — string length
+- `LEN(s)` — string length (`LENGTH` is an alias)
+- `LEFT(s, n)`, `RIGHT(s, n)` — leading / trailing `n` characters
 - `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
+- `SUBSTRING(s, start, end)` — substring by 0-based offsets, `end` exclusive
+- `MID(s, start, len)` — substring by 0-based offset and length
+- `INDEX_OF(s, find)`, `LAST_INDEX_OF(s, find)` — 0-based position, `-1` when absent
+- `SPLIT(s, separator)` — split into a list
+- `REPLACE(s, find, with)` — replace **every** occurrence
+- Substring / prefix / suffix tests are the **operators** `CONTAINS`, `STARTS_WITH`, `ENDS_WITH` (`[note] CONTAINS 'x'`), not functions
+- `FORMAT(date, 'pattern')` — format a **date** as text with .NET-style tokens (case-sensitive: `MM` = month, `mm` = minute): `yyyy`, `yy`, `MM`/`M`, `dd`/`d`, `HH`/`H`, `mm`/`m`, `ss`/`s`; single-letter variants unpadded, other characters pass through. Pattern must be a string literal. Dates only — numbers are not supported. Works client-side and SQL-time (reports)
 
 ### Number functions
 
 - `ABS(n)`, `ROUND(n, digits)`, `FLOOR(n)`, `CEIL(n)`, `CEILING(n)`
-- `MIN(a, b)`, `MAX(a, b)` — binary min/max
+- `MIN(a, b, ...)`, `MAX(a, b, ...)` — smallest / largest argument; nulls are ignored
 - `POW(base, exp)`, `SQRT(n)`
-- `MOD(a, b)` — modulo
+- `MOD(a, b)` — modulo; a zero divisor is null, not an error
+- `TRUNC(n)`, `SIGN(n)`, `EXP(n)`, `LOG(n)` (natural), `LOG10(n)`, `LOG2(n)`, `LOG1P(n)`
+- `FROUND(n)` — round to single (32-bit float) precision
+- Trigonometry: `SIN`, `COS`, `TAN`, `ASIN`, `ACOS`, `ATAN`, `ATAN2(y, x)`, and the hyperbolic `SINH`, `COSH`, `TANH`, `ASINH`, `ATANH`
 
 ### Date functions
 
@@ -76,17 +87,67 @@ FORMAT([created_date], "yyyy-MM-dd")
 - `DATE(y, m, d)` — build a date from parts; `DATE(v)` casts a value to a date
 - `DATEADD(d, count, unit)` — add time; unit is a **string literal**: `'DAY'`, `'HOUR'`, `'MINUTE'`, `'SECOND'`, `'MONTH'`, `'YEAR'` (plural forms accepted)
 - `DATEDIFF(d1, d2, unit)` — difference `d2 − d1` in the given unit (same unit list). `DAY`/`HOUR`/`MINUTE`/`SECOND` floor the elapsed time; `MONTH`/`YEAR` are calendar-component deltas. E.g. days overdue: `DATEDIFF([due_date], TODAY(), 'DAY')`
-- `STARTMONTH(d?)`, `ENDMONTH(d?)`, `STARTQUARTER(d?)`, `ENDQUARTER(d?)`, `STARTYEAR(d?)`, `ENDYEAR(d?)`, `STARTNEXTMONTH(d?)` — period boundaries; the argument is optional and defaults to today
+- `STARTMONTH(d?)`, `ENDMONTH(d?)`, `STARTQUARTER(d?)`, `ENDQUARTER(d?)`, `STARTYEAR(d?)`, `ENDYEAR(d?)`, `STARTNEXTMONTH(d?)` — period boundaries. **Omitting** the argument means today; passing one that is null gives null (a row with no date renders blank, it does not fall back to today)
 
 The whole date family evaluates identically **client-side and SQL-time** (reports, filters, sorts on formula columns) — the SQL translator mirrors the client runtime, including `MONTH` 1-based and `WEEKDAY` 0=Sunday. Unit arguments must be string literals; an unknown unit fails loud with the accepted list.
 
 ### Logical functions
 
-- `IF(cond, then, else)` — ternary
-- `CASE(expr, val1, result1, val2, result2, ..., default)` — multi-branch
+- `IF(cond, then, else)` — ternary (`IIF` is an alias)
+- `CASE(cond1, result1, cond2, result2, ..., default)` — first **condition** that holds wins
+- `SWITCH(expr, val1, result1, val2, result2, ..., default)` — first **value** that matches
+  `expr` wins. Note the difference: `CASE` takes conditions, `SWITCH` takes values to compare
 - `COALESCE(a, b, c, ...)` — first non-null
 - `NULLIF(a, b)` — null if equal, else a
-- `ISNULL(x)` — boolean null check
+- `ISNULL(x)` — boolean **null check** (returns true/false). This is *not* T-SQL's two-arg "replace null with" — that is `COALESCE(x, fallback)`
+
+### Conversion and context functions
+
+- `TEXT(v)` — as text (null becomes `''`)
+- `NUMBER(v)` — as a number, or null when the value isn't numeric (including a blank string)
+- `BOOLEAN(v)` — null, `''` and `0` are false; everything else is true
+- `JSON_GET(json, 'key' [, type])` — read a key out of a JSON column. The optional type is a
+  string literal: `'text'` (default), `'number'`/`'numeric'`, `'int'`/`'integer'`/`'bigint'`,
+  `'bool'`/`'boolean'`, `'date'`, `'datetime'`/`'timestamp'`/`'timestamptz'`
+- `CURRENT_USER_ID()` — the id of the requesting user
+
+### Client-side vs SQL-time evaluation
+
+An `F` column is evaluated **client-side** in grids and cards, but translated to **SQL** when a
+report selects it, or when it is used in a filter or sort. **Every function listed here is
+implemented in both**, so a column reads the same in a grid and in a report; a test executes
+each one against PostgreSQL and diffs the result against the client runtime.
+
+Two deliberate points of agreement, because the engines disagree by nature:
+
+- **Out-of-domain math is null, not an error.** `SQRT(-1)`, `LOG(0)`, `ASIN(2)`, `EXP(1000)`,
+  `POW(0, -1)`, `MOD(x, 0)` — JavaScript would answer NaN or Infinity and PostgreSQL would
+  raise (failing the whole report). Both return null, so the cell renders blank.
+- **String indexing is JavaScript-flavoured, not SQL's.** `SUBSTRING(s, start, end)` and
+  `MID(s, start, len)` take a **0-based** start, and `SUBSTRING`'s third argument is an **end
+  offset**, not a length. `INDEX_OF` / `LAST_INDEX_OF` return a 0-based index, or `-1`.
+
+Known remaining difference: `CONCAT` on a numeric column renders PostgreSQL's declared scale
+(`-3.0`) where the client renders the JavaScript number (`-3`). Use `FORMAT`/`TEXT` when the
+exact rendering matters.
+
+`CURRENT_USER_ID()` needs the requesting user, so it resolves in grids, reports, filters and
+`select()`, but not in a context with no user (an unattended job).
+
+### Unknown functions
+
+The parser treats any `NAME(...)` as a call, so a misspelled or non-existent function is a
+*grammatically valid* formula. Module install rejects it with the offending name (and a "did
+you mean" suggestion where one is close). Before that check existed, such a formula installed
+cleanly and then rendered as an **empty cell on every row**, with no error in the server log,
+the browser console, or the install output.
+
+### Comparing dates
+
+Date comparisons work directly — `TODAY() > [due_date]`, `[due_date] BETWEEN STARTMONTH() AND
+ENDMONTH()`, `[due_date] = TODAY()` — and combine with other conditions through `AND` / `OR`
+like any other boolean. A bare `date` column is treated as a **local calendar date**, matching
+`TODAY()` and `DATE(y, m, d)`.
 
 ### Aggregation over a child set — use a Generated (`G`) column, not `F`
 
@@ -127,6 +188,8 @@ and the JSON shape: `column-types.md` → "Roll-up totals over child rows — us
 
 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.
 
+**SQL-time (reports, filters, sorts):** single-hop navigation (`[ref].[field]`) is translated to a `LEFT JOIN` and computes in reports and query datasets. Multi-hop chains and `$[Setting]` references are **not** available at SQL time — the column returns NULL there and the response carries a warning naming the column. Keep report-bound formulas to single-hop navigation.
+
 ## 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.

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

@@ -85,6 +85,8 @@ Translation files mirror the module's content structure. Each translatable objec
 | `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 } } }` |
 | `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: … } }` |
 
 ### Constraint violation messages ARE translatable (opt-in)
 
@@ -105,6 +107,47 @@ A check/unique constraint declares a user-facing `message` in the entity JSON (`
 - **Opt-in, never mandatory** (unlike roles/labels, which completeness *enforces*). If the manifest lists `supportedLocales` and a constraint `message` has no override for one of those (non-English) locales, install emits a **non-fatal warning** naming the missing `entities.<e>.constraints.<c>.message` keys (printed by the CLI, returned in the marketplace install response). Install still commits with the base message as the fallback. `dforge_module_validate` surfaces the same gap pre-flight as a warning.
 - Only constraints that declare a `message` are scanned; English (`en`/`en-*`) is the base and is never warned; extension entities (`"extends": "..."`) are skipped — their constraint translations belong with the foreign module's files.
 
+### Dropdown option labels ARE translatable (opt-in)
+
+The `options` on a `dropdown`/`radio`/`flags` column are the **base (fallback) labels**. To translate the labels a user actually sees, add an `options` map next to the field's `label`, keyed by the option's **value** (the stored code):
+
+```json
+"entities": {
+    "position": {
+        "fields": {
+            "status": {
+                "label": "Status",
+                "options": {
+                    "on_hold": { "label": "In Wartestellung", "color": "#f90" },
+                    "draft":   "Entwurf"
+                }
+            }
+        }
+    }
+}
+```
+
+- An override is a **partial merged over the base** — a bare string is shorthand for `{ "label": … }`; any field it omits (icon/color) falls through to the authored option. Only `label`, `icon`, `color` are translatable; **`value` is the stored code and is never translated** (translations match on it).
+- **Opt-in, never mandatory** — an option with no override keeps its authored label; nothing warns or fails.
+- Resolved once at metadata-load time and cached per culture, so the localized labels show up identically in the grid, the form, **and** print templates (`_fmt.<col>` / bare field refs) — which previously always rendered the base English label.
+- `optionSets` conditional narrowing is unaffected: it filters by `value`, which translation never touches.
+
+### Column domain labels + options ARE translatable (opt-in) — and shared
+
+If a column uses a **domain** (see `column-domains.md`), translate the domain **once** under a top-level `domains` section — its label and per-option labels then flow to *every* column that references it, instead of once per column:
+
+```json
+"domains": {
+    "doc_status": {
+        "label": "Belegstatus",
+        "options": { "draft": "Entwurf", "posted": { "label": "Gebucht", "color": "#0a0" } }
+    }
+}
+```
+
+- 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.
+
 ### Roles ARE translated — and completeness is enforced
 
 Role labels are **required and localized** (this changed — older docs said roles were skipped; they are not). `SecurityRegistrar` gives every role a `res_id`, so `TranslationRegistrar` wires the role label exactly like entities/views/menus: