@dforge-core/dforge-mcp 0.1.10 → 0.1.13

package/CHANGELOG.md

@@ -4,6 +4,114 @@ All notable changes to `@dforge-core/dforge-mcp`. This project uses semver-ish
 `0.1.0-rc.N` pre-release tags; the published version is set at publish time via
 the release workflow, so committed `package.json` versions are placeholders.
 
+## 0.1.12
+
+> Release prerequisite: publish `@dforge-core/metadata@0.0.10` first (adds the
+> `domains.schema.json` schema + the domain-backed column branch in
+> `entity.schema.json`), then `pnpm install` + `sync-schemas` here so the
+> vendored schemas match.
+
+### Skill
+
+- **Column domains** — new `references/column-domains.md`: a reusable field type
+  (base datatype + control + shared option list) declared in `domains.json` and
+  referenced from a column via a single `"domain": "module_cd.domain_cd"` key
+  instead of restating the type. Covers the owned-field rules (restating a
+  domain-owned field fails install), scalar-only constraint, cross-module
+  dependency requirement, and the localize-once payoff. Added to the SKILL
+  loading-policy table and cross-linked from `field-types.md`.
+- **Document extraction / OCR** — new `references/document-extraction.md`: the
+  `ocrExtract()` forms (v1 raw string, v2 inline `schema` + `{ mode: 'extract' }`,
+  v2 `{ profile }`), the `logic/extraction_profiles.json` registry (profile
+  lifecycle + `detect` rules), and the `detectDocument(rawText)` doc-type
+  auto-detect built-in. The DSL reference (`dforge://docs/dsl`) gains an
+  "External integration → Document extraction" section documenting both built-ins.
+- **Dropdown / domain option localization** (`translations.md`): per-option labels
+  are translatable (opt-in) under `entities.<e>.fields.<f>.options` (value-keyed,
+  string shorthand or `{label,icon,color}` partial override — `value` never
+  translated), and a column domain's label + shared option labels are translated
+  once under a top-level `domains` section, inherited by every consuming column.
+- **Formulas** (`formulas.md`) — corrected against the real parser and runtime,
+  after a reported `F` column that rendered empty on every row with no error
+  anywhere. The doc had documented functions the engine never implemented
+  (`ISNULL`, `NULLIF`, `MOD`, `LTRIM`, `RTRIM`) — since the parser accepts any
+  `NAME(...)` as a call, those installed cleanly and then rendered blank. They
+  are implemented now, and an unknown function is rejected at module install.
+  Also fixed: `==`, `%` and `"double-quoted strings"` are **parse errors**
+  (four examples used them); `CONTAINS`/`STARTS_WITH`/`ENDS_WITH` are infix
+  operators, not functions; and the documented `CASE` signature was actually
+  `SWITCH`'s — `CASE([priority], 'high', 3, …)` returns `'high'` for every row,
+  because the real `CASE` takes condition/result pairs. Adds the previously
+  undocumented `LEFT`/`RIGHT`/`FROUND`/`MID`/`INDEX_OF`/`SPLIT` and the
+  conversion functions, so the list now matches the engine exactly, plus notes
+  on date comparison, 0-based string indexing, and out-of-domain math. Every
+  function is now implemented client-side *and* SQL-side, so a column reads the
+  same in a grid and in a report.
+
+### Resources
+
+- New `dforge://schema/domains` (JSON Schema for `domains.json`).
+- New `dforge://reference/column-domains` and `dforge://reference/document-extraction`.
+
+### Schema
+
+- Re-vendored `entity.schema.json` — adds the "Domain-backed column" branch
+  (`required: ["domain"]`, forbidding restatement of domain-owned fields) and the
+  `domain` field property.
+- Vendored `domains.schema.json` (new) from `@dforge-core/metadata@0.0.10`.
+
+## 0.1.11
+
+> Release prerequisite: publish `@dforge-core/metadata@0.0.9` first (adds the
+> `avatar`/`markdown` field types to the runtime registry — until then the field
+> tools reject them), then `pnpm install` + `sync-schemas` here.
+
+### Skill
+
+- **Action DSL: `select()` / `update()` / `delete()` documented.**
+  `select('module.entity', {columns, filter, orderBy, limit, offset})` is the
+  structured multi-row read: canonical `{c,o,v}`/`{g,i}` filter JSON (same
+  operators as data views), one-hop nav paths `'ref.target as alias'` that emit
+  LEFT JOINs, **fail-loud** semantics (unknown column/operator/nav path throws —
+  unlike UI filters, which drop the condition), and no folder row-filter/column
+  security (it hits the table directly; filter nav paths instead of `R`
+  columns). `update()`/`delete()` take a scalar PK **or** a `{col: val}` object
+  key (string ids coerced to the PK storage type; array and null keys rejected).
+  `query()` is repositioned as the escape hatch (aggregates, multi-hop joins,
+  CTEs, `FOR UPDATE`). New real example: `comm.dispatch_messages` (cron-scan
+  `select()` + scalar-key `update()`). Also documents `exit(message?, level?)` —
+  the DSL's early-return — and the rule to always qualify entity codes
+  (`update('comm.message', …)`) (`action-dsl.md`, `jobs.md`, `SKILL.md`).
+- **Formula date family completed + SQL-time parity** (`formulas.md`). Adds the
+  missing `WEEKDAY`, `DATE`, and period-boundary functions (`STARTMONTH`,
+  `ENDMONTH`, `STARTQUARTER`, `ENDQUARTER`, `STARTYEAR`, `ENDYEAR`,
+  `STARTNEXTMONTH` — optional arg defaults to today) and corrects
+  `DATEADD`/`DATEDIFF` signatures (string-literal units `'DAY'`/`'HOUR'`/
+  `'MINUTE'`/`'SECOND'`/`'MONTH'`/`'YEAR'`; `DATEDIFF(d1, d2, unit)` = `d2 − d1`).
+  The whole family now evaluates identically client-side and SQL-time (reports,
+  filters, sorts) — the server SQL translator gained the full set, so
+  `DATEDIFF([due_date], TODAY(), 'DAY')` no longer comes back NULL in reports.
+- **Field types** (`field-types.md`): added `avatar` (initials circle +
+  optional photo via `params.imageColumn`), `markdown` (Write/Preview editor,
+  distinct from `richtext` WYSIWYG — the alias table previously mapped
+  `markdown` → `richtext`, now wrong), and `list` (card-list rendering of a 1:N
+  set, sibling of `grid`).
+
+### Resources
+
+- **`dforge://reference/dsl` (`resources/docs/dsl-reference.md`) caught up with the
+  engine**: documents `select()`, `update()`, `delete()` (previously absent — the
+  reference stopped at `query()`/`insert()`), plus `entityLink()`, the
+  qualify-entity-codes rule, and scalar-vs-object key semantics.
+
+### Schema
+
+- **`entity.schema.json` re-vendored** (from `@dforge-core/metadata@0.0.9`):
+  `fieldTypeCd` enum gains `avatar`, `markdown`, `list`; `refFilter` description
+  now documents `@[field]` dynamic placeholders (resolved against the current
+  record at option load; an unset placeholder drops the condition, and lookups
+  re-resolve options on every open).
+
 ## 0.1.10
 
 ### Schema

package/dist/server.js

@@ -31180,6 +31180,7 @@ var AGG_TYPE_LIST = Object.values(AggType);
 // node_modules/@dforge-core/metadata/dist/field-types.js
 var fieldTypes = [
   { cd: "text", name: "Text", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
+  { cd: "avatar", name: "Avatar Name", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
   { cd: "email", name: "Email", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
   { cd: "phone", name: "Phone", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
   { cd: "url", name: "URL", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
@@ -31198,6 +31199,7 @@ var fieldTypes = [
   { cd: "color", name: "Color Picker", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: 20, precision: null, useStringInFilter: false },
   { cd: "image", name: "Image", columnType: "D", baseDatatypeCd: "binary", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: false },
   { cd: "file", name: "File", columnType: "D", baseDatatypeCd: "binary", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: false },
+  { cd: "markdown", name: "Markdown", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
   { cd: "richtext", name: "Rich Text Editor", columnType: "D", baseDatatypeCd: "string", supportedAgg: null, maxLen: null, precision: null, useStringInFilter: true },
   { cd: "lookup", name: "Lookup", columnType: "R", baseDatatypeCd: "guid", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: true },
   { cd: "user", name: "User Picker", columnType: "D", baseDatatypeCd: "cuid", supportedAgg: "C", maxLen: null, precision: null, useStringInFilter: false },
@@ -31355,7 +31357,7 @@ function expandTraits(traitCds, entityName) {
 
 // node_modules/@dforge-core/metadata/dist/derive.js
 var NUMERIC_TOTAL = 18;
-var TEXT_BACKED = /* @__PURE__ */ new Set(["textarea", "richtext", "code"]);
+var TEXT_BACKED = /* @__PURE__ */ new Set(["textarea", "markdown", "richtext", "code"]);
 var DB_DATATYPE_OVERRIDE = {
   file: "jsonb",
   image: "jsonb"
@@ -34364,6 +34366,11 @@ var resources = [
     "Entity JSON schema",
     "JSON Schema for entity files under entities/*.json (description, dbObject, toString, traits, fields)."
   ),
+  schema(
+    "domains",
+    "Column domains JSON schema",
+    'JSON Schema for domains.json \u2014 reusable column domains (base datatype + control + sizing + shared option list) referenced from a field via "domain": "module_cd.domain_cd".'
+  ),
   schema(
     "data-views",
     "Data view JSON schema",
@@ -34442,6 +34449,7 @@ var resources = [
   reference("field-types", "Field types \u2014 fieldTypeCd (UI control) vs dbDatatype (SQL type), and the correct value for each. Load before adding any field."),
   reference("flags", "Column flags \u2014 only V/I/E/M/H; valid combos (VEM/VE/V/EM/I) and why 'VEMHI' is invalid. Load before setting any flags."),
   reference("column-types", "The FK + Reference two-column pattern (the #1 source of broken modules) and Set columns. Load before any relation."),
+  reference("column-domains", "Column domains: a reusable field type (datatype + control + shared option list) referenced via a single `domain` key. Use when the same enum/type repeats across columns. Load before authoring domains.json or a domain-backed column."),
   reference("formulas", "Formula columns (columnType 'F'): baseDatatypeCd, no dbDatatype, flags 'V', and the formula expression grammar."),
   reference("traits", "Entity traits (identity, audit, audit-full, ...). identity \u2192 PK is '{entity}_id'; don't redefine trait columns."),
   reference("data-views", "Data views: dataSources array, columns, the order string-array ('order': ['-col','col']), and specialized view configs."),
@@ -34453,6 +34461,7 @@ var resources = [
   reference("settings", "Module settings shape."),
   reference("jobs", "Scheduled jobs: cron, timeout, jobClass, and the no-record-context constraint."),
   reference("number-sequences", "Number sequences for reference numbers / codes."),
+  reference("document-extraction", "OCR / document extraction: ocrExtract() (v2 schema-driven + profile forms), logic/extraction_profiles.json, and the detectDocument() doc-type auto-detect built-in. Load before wiring any OCR/intake action."),
   reference("print-templates", "Liquid HTML print templates."),
   reference("translations", "Translation files: locale-keyed, every trait-provided field needs an entry."),
   reference("queries", "Pre-built saved queries."),

package/package.json

@@ -1,45 +1,45 @@
 {
-	"name": "@dforge-core/dforge-mcp",
-	"version": "0.1.10",
-	"description": "MCP server for dForge module authoring. Exposes scaffold/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"
-	},
-	"files": [
-		"dist/",
-		"docs/",
-		"resources/",
-		"skills/",
-		"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"
-	},
-	"dependencies": {
-		"@dforge-core/dforge-cli": "^0.2.7",
-		"@dforge-core/metadata": "^0.0.8",
-		"@modelcontextprotocol/sdk": "^1.29.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.1.13",
+  "description": "MCP server for dForge module authoring. Exposes scaffold/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"
+  },
+  "files": [
+    "dist/",
+    "docs/",
+    "resources/",
+    "skills/",
+    "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"
+  },
+  "dependencies": {
+    "@dforge-core/dforge-cli": "^0.2.7",
+    "@dforge-core/metadata": "^0.0.10",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.7"
+  }
 }

package/resources/docs/conventions.md

@@ -562,7 +562,7 @@ Cron-driven action fires. Each entry pairs an existing action (declared in `ui/a
 - `schedule` — five fields, minute granularity (sub-minute schedules are rejected at install)
 - `timeout` — required, in seconds, range `(0, 3600]`
 - `timeout > 300` requires `"class": "long_running"` (the standard pool is capped at 300s)
-- Referenced action must NOT use `[field]` or `for x in records` — scheduled fires have no record context. Install fails fast if it does. Use `query()` / `insert()` for table-level work.
+- Referenced action must NOT use `[field]` or `for x in records` — scheduled fires have no record context. Install fails fast if it does. Use `select()` / `insert()` / `update()` for table-level work.
 - Max 50 jobs per module
 - Optional `timeZone` (IANA name) overrides `auth.tenant.time_zone` for that job
 - Use `paused: true` to freeze a job during incidents — admin "Run now" still works while the cron path is silent

package/resources/docs/dsl-reference.md

@@ -130,10 +130,13 @@ execute:
 
 ---
 
-## Built-in functions (30)
+## Built-in functions
 
 All exposed by `ActionScriptEngine.cs` as host globals — no `import` needed.
 
+> **Entity codes: always qualify** (`'comm.message'`, not `'message'`) in every data
+> built-in, even inside the owning module.
+
 ### Database & data
 
 #### `query(sql, params?) → array`
@@ -168,6 +171,46 @@ var po = insert('purchase_order', { supplier_id: params[supplier].supplier_id })
 insert('po_line', { po_id: po.purchase_order_id, product_id: [product_id], qty: 1 })
 ```
 
+#### `select(entityCd, opts?) → array`
+Structured multi-row read — the counterpart to `insert()`/`update()`/`delete()`; prefer
+it over `query()` for row-shaped reads. `opts` (all optional): `columns` (paths; a
+one-hop nav path `'ref.target as alias'` LEFT JOINs the referenced entity; formula
+columns translate to SQL; default = all physical columns), `filter` (canonical
+`{c,o,v}`/`{g,i}` filter JSON, nav paths allowed), `orderBy` (`'-'` prefix =
+descending; default = PK), `limit`, `offset`. **Fail-loud:** an unknown column,
+operator, or nav path throws instead of silently dropping the condition. Hits the
+table directly (no folder row-filter / column security); a plain reference (`R`)
+column can't be selected or string-filtered — use the FK column or a nav path.
+`query()` remains the escape hatch (aggregates, multi-hop joins, CTEs, `FOR UPDATE`).
+
+```dsl
+var queued = select('comm.message', {
+    columns: ['message_id', 'to_addr', 'to_point.value as point_value', 'subject'],
+    filter: { g: 'and', i: [
+        { c: 'status', o: '=', v: 'queued' },
+        { c: 'channel', o: '=', v: 'email' }
+    ] },
+    orderBy: ['message_id'],
+    limit: 10
+})
+```
+
+#### `update(entityCd, key, fields) → int`
+Update the row(s) matched by `key`; returns rows affected. Refreshes update-phase
+server defaults (audit `last_updated` / `last_updated_by`) and coerces values like
+`insert()`. `key` is a scalar PK (`update('task', 42, {…})`) or an object
+(`{ task_id: 42 }`; multiple entries for a compound key). Scalar string ids are
+coerced to the PK storage type (snowflake-as-string binds `int8`). A null key
+**throws**; array keys are rejected — loop and mutate per id.
+
+```dsl
+update('comm.message', msg.message_id, { status: 'sent', sent_at: now() })
+```
+
+#### `delete(entityCd, key) → int`
+Delete the row(s) matched by `key`; returns rows affected. Same key shapes and
+rules as `update()`.
+
 #### `getRecord(entityCd, key) → record`
 Fetch a single record by key. **Throws** a localized "not found" error if no row
 matches — the safe default for a lookup that should always resolve (e.g. an FK you
@@ -374,8 +417,45 @@ var result = callService('studio.validate', { module_cd: [module_cd] })
 if (!result.isValid) { error('Validation failed: ' + result.errors[0]) }
 ```
 
+### Document extraction (OCR)
+
+Full guide + intake patterns: `dforge://reference/document-extraction`.
+
+#### `ocrExtract(fileField, endpointBaseUrl, schemaOrHints?, opts?) → string | object`
+Send a file to the OCR service and get structured fields back. Three forms:
+
+- **v1 (raw):** `ocrExtract([doc_file], getSetting('ocr_endpoint_url'))` → JSON **string** (you `JSON.parse`). Optional third arg = hints (array | string | object).
+- **v2 inline schema:** `ocrExtract([doc_file], url, schema, { mode: 'extract' })` → **parsed** `{ fields, confidence?, unmatched, raw_text, meta }`.
+- **v2 profile:** `ocrExtract([doc_file], url, null, { profile: 'module_cd.profile_cd' })` → same parsed shape, schema from `logic/extraction_profiles.json`.
+
+v2 is selected **only** by `opts.mode` (`'extract' | 'summary' | 'raw'`) or `opts.profile` — a bare schema object without `opts.mode` stays on the v1 (raw string) contract. `opts.profile` implies `mode: 'extract'` and is mutually exclusive with an inline `schema`.
+
+```dsl
+var r = ocrExtract([doc_file], getSetting('ocr_endpoint_url'), null, { profile: 'proc.bill_of_lading' })
+insert('bill_of_lading', { bl_no: r.fields.bl_no, issue_date: r.fields.issue_date })
+```
+
+#### `detectDocument(rawText) → object | null`
+Score a document's text against every reachable extraction profile's `detect` rules and return the best match at/above its threshold: `{ profile, docType, score }` (profile module-qualified, ready for `ocrExtract(..., { profile })`) — or `null`. Advisory: malformed rules are skipped, let the human confirm.
+
+```dsl
+var det = detectDocument(data.raw_text)     // { profile: 'proc.bill_of_lading', docType: 'bill_of_lading', score } | null
+if (det != null) { var r = ocrExtract([doc_file], getSetting('ocr_endpoint_url'), null, { profile: det.profile }) }
+```
+
 ### Utility
 
+#### `entityLink(entityCd, record, description?) → link value`
+Build a clickable link to any entity record for storing in an `entitylink` (jsonb)
+column. `record` is a row object (e.g. from `insert()` / `getRecord()`); its PK
+columns are stored as **strings** so snowflake/cuid ids > 2^53 stay exact. Optional
+`description` sets the display text.
+
+```dsl
+var task = insert('workspace.task', { title: 'Follow up' })
+insert('workspace.task_note', { link: entityLink('workspace.task', task, task.title) })
+```
+
 #### `flush()`
 Commit pending changes mid-script AND broadcast SSE updates to connected clients. **Async / background actions only** — in sync actions, everything commits at the end automatically.
 

package/resources/schemas/entity.schema.json

@@ -120,10 +120,10 @@
 				"fieldTypeCd": {
 					"type": "string",
 					"enum": [
-						"text", "email", "phone", "url", "textarea", "number", "currency", "percent",
+						"text", "avatar", "email", "phone", "url", "textarea", "number", "currency", "percent",
 						"checkbox", "date", "datetime", "time",
 						"dropdown", "flags", "tags", "json", "hidden", "color", "image", "file",
-						"richtext", "lookup", "user", "grid", "entitylink", "code"
+						"markdown", "richtext", "lookup", "user", "grid", "list", "entitylink", "code"
 					],
 					"description": "UI field type code from field_type table"
 				},
@@ -210,7 +210,7 @@
 					"description": "On a self-referencing reference column (R column whose link.entity is the owning entity), set true to ALLOW parent/child cycles. When absent the self-reference is treated as an acyclic hierarchy and DB-level guards reject loops. Ignored on non-self-referencing columns."
 				},
 				"refFilter": {
-					"description": "Filter criteria for reference lookups"
+					"description": "Filter criteria for reference lookups. Condition values support @[field] placeholders resolved against the current record at lookup time (e.g. {\"c\":\"channel\",\"o\":\"eq\",\"v\":\"@[channel]\"} narrows options to rows matching the record's own channel); a condition whose placeholder is unset is dropped rather than matching nothing."
 				}
 			},
 			"oneOf": [

package/skills/dforge-mcp-author/SKILL.md

@@ -64,6 +64,7 @@ The phase column below indicates the **typical** use. During a backtrack, the ba
 |---|---|---|
 | Add any field | `dforge://reference/field-types`, `dforge://reference/flags`, `dforge://example/entities/todo_item.json` | — |
 | Add a Reference or Set column | `dforge://reference/column-types` (FK+Reference pattern), `dforge://example/entities/todo_item.json` | — |
+| Reuse a field type / enum across columns (a `domain`) | `dforge://reference/column-domains` | `dforge://schema/domains` |
 | Add a formula column | `dforge://reference/formulas` | — |
 | Add a trait | `dforge://reference/traits` | — |
 | Add a data view (grid / list) | `dforge://reference/data-views`, `dforge://example/ui/data_views.json` | — |
@@ -78,6 +79,8 @@ The phase column below indicates the **typical** use. During a backtrack, the ba
 | Add security roles or folders | `dforge://reference/security`, `dforge://reference/filters`, `dforge://example/security/roles.json` | — |
 | Add a report | `dforge://reference/reports` | `dforge://schema/reports` |
 | Add a print template | `dforge://reference/print-templates` | — |
+| Wire OCR / document extraction (`ocrExtract` / `detectDocument`) | `dforge://reference/document-extraction` | `dforge://docs/dsl` (built-ins) |
+| Localize dropdown options / a column domain | `dforge://reference/translations` (§Dropdown option labels / §Column domain labels) | — |
 | Add translations | `dforge://reference/translations` | — |
 | Add a number sequence | `dforge://reference/number-sequences` | — |
 | Add module settings | `dforge://reference/settings` | — |
@@ -274,7 +277,7 @@ For each trigger, propose: entity + event + (optional) condition formula + targe
 Load the "scheduled job" row from the Loading policy table (`dforge://reference/jobs` + `dforge://schema/jobs`).
 
 Constraints baked into the tool:
-- Action MUST NOT use record-context (`[field]`) syntax — jobs run as system user with NO current record. Wrap any record-context action in a thin job-friendly action that uses `query()` to fetch the records it needs.
+- Action MUST NOT use record-context (`[field]`) syntax — jobs run as system user with NO current record. Wrap any record-context action in a thin job-friendly action that uses `select()` (or `query()`) to fetch the records it needs.
 - `timeout` is required, ≤ 3600s.
 - If `timeout > 300`, you MUST set `jobClass: 'long_running'`.
 

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

@@ -106,11 +106,68 @@ var note = params[note]             // no quotes around param name in this DSL
 | Function | Returns | Description |
 |---|---|---|
 | `insert('entity', { field: value, … })` | Inserted row object | Insert a new record. Returns the full row including auto-filled columns (PK, audit, number sequences). Access returned fields with `result.field_name`. |
-| `query('SQL', { arg: value })` | Array of row objects | Execute parameterized SQL. Use `@argName` placeholders. Schema-qualified table names (`crm.contact`). Access row fields with `row.field_name` or `row['field_name']`. |
-| `getRecord('entity', key)` | Row object | Fetch a single record by key (qualified `module.entity` supported). `key` is a scalar PK or an object for a compound key (`{ col_a: 1, col_b: 'x' }`). Access fields with `rec.field_name` (or `rec.get('field_name')`). **Throws** a localized "not found" error if absent. |
+| `select('entity', opts?)` | Array of row objects | Structured multi-row read — see "select()" below. `opts` = `{columns, filter, orderBy, limit, offset}`, all optional. Prefer over `query()` for row-shaped reads. |
+| `update('entity', key, { field: value, … })` | Rows affected (number) | Update the row(s) matched by `key`. Refreshes update-phase server defaults (audit `last_updated` / `last_updated_by`) and coerces values like `insert()`. |
+| `delete('entity', key)` | Rows affected (number) | Delete the row(s) matched by `key`. |
+| `query('SQL', { arg: value })` | Array of row objects | Execute parameterized SQL. Use `@argName` placeholders. Schema-qualified table names (`crm.contact`). Access row fields with `row.field_name` or `row['field_name']`. **Escape hatch** — prefer `select()`/`update()`/`delete()` when the structured shape fits. |
+| `getRecord('entity', key)` | Row object | Fetch a single record by key. Access fields with `rec.field_name` (or `rec.get('field_name')`). **Throws** a localized "not found" error if absent. |
 | `getRecordOrNull('entity', key)` | Row object or `null` | Like `getRecord`, but returns `null` instead of throwing when the row is absent — use for an expected-absence lookup, guarded with `if (rec == null)`. |
 | `preloadRef('fk_column')` | Row object | Load the referenced record for a FK column. Access its fields with `ref.get('field')`. |
 
+> **Entity codes: always qualify.** Every data built-in (`select`, `insert`, `update`, `delete`,
+> `getRecord`, `nextNumber`) accepts a qualified `module.entity` code — write `update('comm.message', …)`,
+> not `update('message', …)`, even inside the owning module. It reads unambiguously and keeps the
+> script correct if it's ever moved to a bridge module.
+
+> **Keys: scalar or object.** In `update()` / `delete()` / `getRecord()` / `getRecordOrNull()`,
+> `key` is either a scalar PK value (`update('task', 42, {…})` — single-column PK only) or an
+> object (`{ task_id: 42 }`; multiple entries for compound keys). Scalar **string** ids are coerced
+> to the PK's storage type, so a snowflake id carried as a string binds as `int8`, not text. A
+> `null` key **throws** (a `col = NULL` predicate can never match), and array keys are rejected —
+> loop and mutate per id instead.
+
+### select() — structured multi-row reads
+
+The read counterpart to `insert()`/`update()`/`delete()`. Entity codes are metadata-validated,
+values are parameterized and type-coerced per column, and reference navigation replaces
+hand-written LEFT JOINs. A bare `select('entity')` reads every physical column of every row,
+ordered by PK.
+
+```javascript
+var queued = select('comm.message', {
+    columns: ['message_id', 'to_addr', 'to_point.value as point_value', 'subject'],
+    filter: { g: 'and', i: [
+        { c: 'status', o: '=', v: 'queued' },
+        { c: 'channel', o: '=', v: 'email' },
+        { g: 'or', i: [
+            { c: 'to_addr', o: '!null' },
+            { c: 'to_point.value', o: '!null' }
+        ] }
+    ] },
+    orderBy: ['message_id'],
+    limit: 10
+})
+// queued = [{ message_id: 123, to_addr: null, point_value: 'a@b.c', subject: '…' }, …]
+```
+
+| Option | Shape | Notes |
+|---|---|---|
+| `columns` | array of strings | Column paths. A one-hop nav path `'ref.target'` LEFT JOINs the referenced entity; `' as alias'` renames the key in the returned rows (avoids bracket-indexed `row['ref.target']` access). Formula columns are translated to SQL. Defaults to all physical columns. |
+| `filter` | object | The platform's canonical filter JSON — `{c, o, v}` conditions inside `{g, i}` groups, same operators as data views (`=`, `!=`, `>`, `in`, `start`, `contains`, `null`, `!null`, `between`, …; see `filters.md`). Nav paths work here too. |
+| `orderBy` | array of strings | Column paths; `'-'` prefix for descending (`['-message_id']`). Defaults to the PK for deterministic results. |
+| `limit` / `offset` | int | Positive / non-negative. |
+
+- **Fail-loud:** unlike UI filters (which drop untranslatable conditions with a warning),
+  `select()` **throws** on an unknown column, unknown operator, or unresolvable nav path — a
+  silently narrowed filter in an action means processing the wrong rows.
+- **Low-level:** like the other data built-ins, `select()` hits the table directly — no folder
+  row-filter, column security, or reference display machinery. A plain reference (`R`) column has
+  no value here; select its FK column or a nav path (the error message says which). String
+  operators on a reference column are rejected for the same reason — filter a nav path like
+  `'customer.company_name'` instead.
+- `query()` remains the escape hatch for anything this shape can't express: aggregates, multi-hop
+  joins, CTEs, `FOR UPDATE`.
+
 ### Messaging
 
 | Function | Description |
@@ -118,6 +175,7 @@ var note = params[note]             // no quotes around param name in this DSL
 | `error('message')` | **Abort** the action and show an error to the user. Rolls back all changes. |
 | `warn('message')` | Show a warning but continue execution. |
 | `info('message')` | Show an informational message. |
+| `exit('message'?, 'level'?)` | **Stop the script early without error** — changes made so far are kept. Level `'info'` (default) or `'warn'` styles the message. This is the DSL's early-return: a bare `return` is not valid at the top level of `execute:`. |
 | `notify(userId, 'message')` | Send an in-app notification to a specific user. First arg is a user ID (typically `[owner_id]` or similar). |
 
 ### Email
@@ -315,6 +373,42 @@ execute:
     info('Received ' + poLines.length + ' line(s) from PO ' + [po_number])
 ```
 
+> The two `query()` reads and the raw `query('UPDATE …')` above predate `select()`/`update()` —
+> today each would be a structured call (`select('wms.stock', { filter: … })`,
+> `update('wms.stock', stockId, { quantity: newQty })`).
+
+### select() + update() with a scalar key (cron-scan dispatch)
+
+From `modules/comm/logic/actions/dispatch_messages.dsl` (a scheduled-job action — no record context):
+
+```
+execute:
+    var queued = select('comm.message', {
+        columns: ['message_id', 'to_addr', 'to_point.value as point_value', 'subject', 'body_html', 'body_text', 'attempt_count'],
+        filter: { g: 'and', i: [
+            { c: 'status', o: '=', v: 'queued' },
+            { c: 'channel', o: '=', v: 'email' }
+        ] },
+        orderBy: ['message_id'],
+        limit: 10
+    })
+
+    if (queued.length == 0) {
+        exit('No queued messages', 'info')
+    }
+
+    for (var i = 0; i < queued.length; i++) {
+        var msg = queued[i]
+        sendEmail(msg.to_addr || msg.point_value, msg.subject, msg.body_html || msg.body_text || '')
+
+        update('comm.message', msg.message_id, {
+            status: 'sent',
+            sent_at: now(),
+            attempt_count: (msg.attempt_count || 0) + 1
+        })
+    }
+```
+
 ## Execution modes
 
 Actions run in one of two modes, declared in `ui/actions.json`:
@@ -376,10 +470,12 @@ In `ui/actions.json`:
 
 ## SQL in query() — important notes
 
-1. **Table names are schema-qualified** within the module: `crm.contact`, `wms.stock_movement`, `fin.invoice`. Use the module code as the schema prefix.
+`query()` is the **escape hatch** — reach for it only when the structured built-ins can't express the read/write (aggregates, multi-hop joins, CTEs, `FOR UPDATE`). For row-shaped work prefer `select()` / `insert()` / `update()` / `delete()`: they validate entity codes against metadata, coerce values per column, and (for `insert`/`update`) maintain auto-fill and audit columns.
+
+1. **Table names are schema-qualified** within the module: `crm.contact`, `wms.stock_movement`, `fin.invoice`. Use the module code as the schema prefix. (Module codes with a hyphen, e.g. `crm-fin`, cannot be schema-qualified in raw SQL — another reason to use the structured built-ins, which accept the qualified `module.entity` code.)
 2. **Use `@param` placeholders** for values — NEVER concatenate user input into SQL strings. The engine auto-parameterizes.
 3. **SELECT, INSERT, UPDATE, DELETE all work** via `query()`. For reads, it returns row arrays. For writes, it executes the statement.
-4. **`insert()` is preferred over `query('INSERT ...')`** for inserting into module entities — it handles auto-fill (PKs, audit, number sequences). Use raw `query('INSERT ...')` only for cross-module or system tables.
+4. **`insert()` is preferred over `query('INSERT ...')`**, `update()`/`delete()` over `query('UPDATE/DELETE ...')`, and `select()` over `query('SELECT ...')` for module entities — raw SQL skips auto-fill (PKs, audit, number sequences) and metadata validation.
 
 ## Common mistakes
 
@@ -387,7 +483,10 @@ In `ui/actions.json`:
 - Writing `params["note"]` — **also wrong in DSL syntax**. Use `params[note]` without quotes.
 - Writing `update [status] = 'Draft'` (declarative style) — **wrong**. Use `[status] = 'Draft'` (assignment).
 - Writing `insert('entity', field1, value1)` (positional args) — **wrong**. Use `insert('entity', { field: value })` (object).
-- Writing `query('entity', filter)` (filter object) — **wrong**. `query()` takes raw SQL strings with `@param` placeholders.
+- Writing `query('entity', filter)` (filter object) — **wrong**. `query()` takes raw SQL strings with `@param` placeholders. A structured read is `select('entity', { filter: … })`.
+- Passing an **array of ids** as the `key` of `update()`/`delete()` — **rejected**. Loop over the ids and mutate one at a time.
+- Selecting or string-filtering a plain reference (`R`) column in `select()` — **throws**. Use the FK column or a nav path (`'customer.company_name'`).
+- Unqualified entity codes (`update('message', …)`) — works inside the owning module but **always prefer the qualified form** (`update('comm.message', …)`).
 - Forgetting `var` in loops — `for (i = 0; ...)` creates a global. Always `for (var i = 0; ...)`.
 - Using ES6 syntax (`const`, `let`, `=>`, template literals) — **may not work**. Jint supports ES5.1 primarily. Stick to `var`, `function`, string concatenation with `+`.
 - Calling `TODAY()` or `NOW()` (uppercase) inside `execute:` — **wrong**, they're undefined there and install fails with `'TODAY' is not defined`. Use lowercase **`now()`** in `execute:`; `TODAY()`/`NOW()` are formula-only (`canExecute:`, formula columns).

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,16 +10,20 @@ 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 |
 |---|---|---|---|---|
 | `text` | `string` | Single-line text | `varchar` (with `maxLen`) | `maxLen` |
+| `avatar` | `string` | Person/company name rendered as an initials circle; optional photo. | `varchar` | `imageColumn` (an `image` column on the same entity to use as the photo) |
 | `email` | `string` | Email address. Client-side format validation. | `varchar` 250 | — |
 | `phone` | `string` | Phone/telephone. | `varchar` 50 | — |
 | `url` | `string` | Web URL. | `varchar` 500 | — |
 | `textarea` | `string` | Multi-line plain text. | `text` | `defaultLines`, `maxLines` |
-| `richtext` | `string` | Rich text editor (HTML). | `text` | — |
+| `markdown` | `string` | Markdown editor (Write/Preview tabs), rendered sanitized. | `text` | — |
+| `richtext` | `string` | Rich text WYSIWYG editor, stores sanitized HTML. | `text` | — |
 | `code` | `string` | Code editor with syntax highlighting. | `text` | `language` |
 | `dropdown` | `string` | Fixed list of options. | `varchar` | `options: ["a","b",…]` or `[{value,label,icon,color}]` |
 | `flags` | `string` | Multiple checkboxes with letter flags. | `varchar` | `optionSets`, `style: "buttons"` |
@@ -67,6 +71,7 @@ Source of truth: `server/database/system-modules/metadata/seed-data/field_types.
 | `lookup` | `guid` | `R` | Reference to another entity (always paired with a hidden FK column — see SKILL.md "FK+Reference pattern") |
 | `user` | `cuid` | `D` | User picker. Writes a user ID directly, no paired FK needed. |
 | `grid` | `set` | `S` | Detail grid of related records (1:N backwards reference). Used with `link` declaring the relation. |
+| `list` | `set` | `S` | Detail list — same 1:N set as `grid`, rendered as a card list instead of a table. |
 | `entitylink` | `json` | `D` | Polymorphic link to any entity (stores `{entity, id}` pair). Populate from action DSL with the `entityLink('entityCd', record, description?)` built-in (see `action-dsl.md`). |
 
 ## JSON
@@ -137,7 +142,8 @@ These are the field type names LLMs tend to invent. **They are all wrong.**
 | `picture`, `photo` | `image` |
 | `attachment` | `file` |
 | `multiline` | `textarea` |
-| `richText`, `markdown` | `richtext` |
+| `md` | `markdown` |
+| `richText`, `wysiwyg`, `html` | `richtext` |
 | `userPicker` | `user` |
 | `phoneNumber` | `phone` |
 

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,38 +55,99 @@ 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
 
 - `TODAY()` — current date
 - `NOW()` — current datetime with timezone
-- `YEAR(d)`, `MONTH(d)`, `DAY(d)` — date parts
+- `YEAR(d)`, `MONTH(d)`, `DAY(d)` — date parts (`MONTH` is 1-based)
 - `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
+- `WEEKDAY(d)` — day of week, `0` = Sunday
+- `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. **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`
 
@@ -122,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/jobs.md

@@ -62,7 +62,7 @@ Scheduled actions run with **no record bound**. Specifically:
 - `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()`:
+**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 `select()` / `insert()` / `update()`:
 
 ```
 execute:
@@ -132,7 +132,7 @@ 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()`.
+- **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 `select()`/`insert()`/`update()`.
 - **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.

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: