@dforge-core/dforge-mcp 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -4,6 +4,58 @@ 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.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"

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.1.10",
+	"version": "0.1.11",
 	"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",
@@ -32,7 +32,7 @@
 	},
 	"dependencies": {
 		"@dforge-core/dforge-cli": "^0.2.7",
-		"@dforge-core/metadata": "^0.0.8",
+		"@dforge-core/metadata": "^0.0.9",
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"zod": "^4.4.3"
 	},

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
@@ -376,6 +419,17 @@ if (!result.isValid) { error('Validation failed: ' + result.errors[0]) }
 
 ### 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

@@ -274,7 +274,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/field-types.md

@@ -15,11 +15,13 @@ Source of truth: `server/database/system-modules/metadata/seed-data/field_types.
 | `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 +69,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 +140,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

@@ -70,10 +70,15 @@ FORMAT([created_date], "yyyy-MM-dd")
 
 - `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; the argument is optional and defaults 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
 

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.