@dforge-core/dforge-mcp 0.1.0-rc.10 → 0.1.0-rc.12

package/dist/server.js

@@ -31381,8 +31381,12 @@ function modulePaths(moduleDir) {
     menus: path3.join(root, "ui", "menus.json"),
     actions: path3.join(root, "ui", "actions.json"),
     reports: path3.join(root, "ui", "reports.json"),
+    queries: path3.join(root, "ui", "queries.json"),
+    printTemplates: path3.join(root, "ui", "print_templates.json"),
     roles: path3.join(root, "security", "roles.json"),
     jobs: path3.join(root, "logic", "jobs.json"),
+    triggers: path3.join(root, "logic", "triggers.json"),
+    webhooks: path3.join(root, "logic", "webhooks.json"),
     settings: path3.join(root, "settings.json")
   };
 }
@@ -31932,6 +31936,158 @@ function computeDepth(folder, current = 1) {
   return childDepths.length === 0 ? current : Math.max(...childDepths);
 }
 
+// src/tools/behavior.ts
+var triggerAddSchema = {
+  moduleDir: external_exports.string(),
+  code: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Trigger code, unique within the module."),
+  entity: external_exports.string().describe(
+    "Entity whose events fire this trigger. Cross-module dotted form supported ('fin.invoice')."
+  ),
+  event: external_exports.enum(["insert", "update", "delete", "status_change", "any"]).describe(
+    "insert/update/delete are obvious. status_change fires only when status field changes value. 'any' fires for all insert/update/delete."
+  ),
+  action: external_exports.string().describe("Action code to invoke. Cross-module dotted form ('module.action') supported."),
+  description: external_exports.string().optional(),
+  condition: external_exports.string().optional().describe(
+    "Optional formula expression (same shape as canExecute) using `[field]` syntax. Single-line boolean. If omitted, trigger fires on every matching event."
+  ),
+  params: external_exports.record(external_exports.string(), external_exports.unknown()).optional().describe(
+    "Static params merged into the action invocation alongside auto-injected record_id."
+  ),
+  async: external_exports.boolean().default(false).describe(
+    "When true, the action runs in background (recommended for slow actions). When false, runs in the same transaction \u2014 action failure rolls back the original DB change."
+  )
+};
+function triggerAdd(args) {
+  const { paths, manifest } = loadManifest(args.moduleDir);
+  const file2 = readJsonOrDefault(
+    paths.triggers,
+    { triggers: [] }
+  );
+  if (file2.triggers.some((t) => t.code === args.code)) {
+    throw new Error(`Trigger '${args.code}' already exists.`);
+  }
+  const entry = {
+    code: args.code,
+    entity: args.entity,
+    event: args.event,
+    action: args.action,
+    async: args.async
+  };
+  if (args.description) entry.description = args.description;
+  if (args.condition) entry.condition = args.condition;
+  if (args.params) entry.params = args.params;
+  file2.triggers.push(entry);
+  return makeResult(
+    `Added trigger '${args.code}' on ${args.entity}.${args.event} \u2192 action '${args.action}'${args.async ? " (async)" : ""}.`,
+    {
+      [rel(paths.root, paths.triggers)]: jsonText(file2),
+      "manifest.json": jsonText(withTodayStamp(manifest))
+    }
+  );
+}
+var jobAddSchema = {
+  moduleDir: external_exports.string(),
+  code: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Job code, unique within the module."),
+  action: external_exports.string().describe(
+    "Action code to invoke on schedule. MUST NOT use record-context (`[field]`) syntax \u2014 scheduled jobs run as system user with no current record. Wrap record-context actions in a thin action that queries first."
+  ),
+  schedule: external_exports.string().describe(
+    "5-field cron expression (minute hour day-of-month month day-of-week). Evaluated in the tenant's time zone (auth.tenant.time_zone) or per-job override."
+  ),
+  timeout: external_exports.number().int().min(1).max(3600).describe(
+    "Hard kill timeout in seconds. Required. If > 300, you must also set `class: 'long_running'`."
+  ),
+  description: external_exports.string().optional(),
+  concurrency: external_exports.number().int().min(1).default(1).describe("Max overlapping executions. Default 1 (skip new fire if previous still running)."),
+  jobClass: external_exports.enum(["standard", "long_running"]).default("standard").describe(
+    "Required to be 'long_running' when timeout > 300. Affects scheduler thread-pool routing."
+  ),
+  paused: external_exports.boolean().default(false)
+};
+function jobAdd(args) {
+  if (args.timeout > 300 && args.jobClass !== "long_running") {
+    throw new Error(
+      "Jobs with timeout > 300s must set jobClass: 'long_running' \u2014 see logic/jobs.json convention."
+    );
+  }
+  const { paths, manifest } = loadManifest(args.moduleDir);
+  const file2 = readJsonOrDefault(
+    paths.jobs,
+    { jobs: [] }
+  );
+  if (file2.jobs.some((j) => j.code === args.code)) {
+    throw new Error(`Job '${args.code}' already exists.`);
+  }
+  const entry = {
+    code: args.code,
+    action: args.action,
+    schedule: args.schedule,
+    timeout: args.timeout,
+    concurrency: args.concurrency,
+    class: args.jobClass
+  };
+  if (args.description) entry.description = args.description;
+  if (args.paused) entry.paused = true;
+  file2.jobs.push(entry);
+  return makeResult(
+    `Added job '${args.code}' (schedule '${args.schedule}', timeout ${args.timeout}s) \u2192 action '${args.action}'.`,
+    {
+      [rel(paths.root, paths.jobs)]: jsonText(file2),
+      "manifest.json": jsonText(withTodayStamp(manifest))
+    }
+  );
+}
+var webhookAddSchema = {
+  moduleDir: external_exports.string(),
+  code: external_exports.string().regex(/^[a-z][a-z0-9_]*$/).describe("Subscription code, unique within the module."),
+  entity: external_exports.string().describe("Entity whose events fire this webhook."),
+  event: external_exports.enum(["insert", "update", "delete", "status_change", "any"]).describe("Same event taxonomy as triggers."),
+  endpointUrl: external_exports.string().url().describe("Destination URL \u2014 receives POST with the payload."),
+  description: external_exports.string().optional(),
+  condition: external_exports.string().optional().describe("Optional formula filter; fires only when true. Same shape as trigger condition."),
+  payload: external_exports.object({
+    include: external_exports.array(external_exports.string()).optional().describe("Whitelist of field codes to include. Omit to send all fields."),
+    exclude: external_exports.array(external_exports.string()).optional().describe("Blacklist (applied after include). Use for stripping sensitive cols."),
+    includeOld: external_exports.boolean().optional().describe(
+      "For update/status_change events, also include the pre-change record as `old`."
+    )
+  }).optional().describe(
+    "Payload shape. If omitted, sends full new record. The platform always wraps in `{ event, entity, record, old?, occurred_at }`."
+  ),
+  headers: external_exports.record(external_exports.string(), external_exports.string()).optional().describe(
+    "Extra HTTP headers (e.g. authentication tokens). Use `getSecret(...)` semantics: header values starting with `$secret:` are resolved at fire time."
+  )
+};
+function webhookAdd(args) {
+  const { paths, manifest } = loadManifest(args.moduleDir);
+  const file2 = readJsonOrDefault(
+    paths.webhooks,
+    { subscriptions: [] }
+  );
+  if (file2.subscriptions.some((s) => s.code === args.code)) {
+    throw new Error(`Webhook subscription '${args.code}' already exists.`);
+  }
+  const entry = {
+    code: args.code,
+    entity: args.entity,
+    event: args.event,
+    endpointUrl: args.endpointUrl
+  };
+  if (args.description) entry.description = args.description;
+  if (args.condition) entry.condition = args.condition;
+  if (args.payload) entry.payload = args.payload;
+  if (args.headers) entry.headers = args.headers;
+  file2.subscriptions.push(entry);
+  return makeResult(
+    `Added webhook subscription '${args.code}' on ${args.entity}.${args.event} \u2192 POST ${args.endpointUrl}.`,
+    {
+      [rel(paths.root, paths.webhooks)]: jsonText(file2),
+      "manifest.json": jsonText(withTodayStamp(manifest))
+    }
+  );
+}
+
 // src/resources/index.ts
 var fs5 = __toESM(require("fs"));
 var path7 = __toESM(require("path"));
@@ -31994,7 +32150,17 @@ var resources = [
   schema(
     "webhooks",
     "Webhooks JSON schema",
-    "JSON Schema for ui/webhooks.json \u2014 outbound webhook definitions."
+    "JSON Schema for logic/webhooks.json \u2014 outbound webhook subscriptions: entity + event filter \u2192 POST to endpointUrl with selected fields."
+  ),
+  schema(
+    "triggers",
+    "Triggers JSON schema",
+    "JSON Schema for logic/triggers.json \u2014 intra-tenant DB-event \u2192 action invocation: entity + event + optional condition formula \u2192 fires an action (sync or async)."
+  ),
+  schema(
+    "print-templates",
+    "Print templates JSON schema",
+    "JSON Schema for ui/print_templates.json \u2014 Liquid HTML print templates and reusable snippets, bound to entities for the print menu."
   ),
   schema(
     "settings",
@@ -32146,10 +32312,28 @@ server.tool(
 );
 server.tool(
   "dforge_action_add",
-  "PHASE 3: Add a DSL action targeting an entity. Writes logic/actions/<code>.dsl plus an entry in ui/actions.json. Phase 3 is optional \u2014 only call when business logic genuinely requires custom actions.",
+  "PHASE 2: Add a DSL action targeting an entity. Writes logic/actions/<code>.dsl plus an entry in ui/actions.json. **Load dforge://docs/dsl before authoring.**",
   actionAddSchema,
   envelope(actionAdd)
 );
+server.tool(
+  "dforge_trigger_add",
+  "PHASE 2: Add a trigger that fires an action on a DB event (insert/update/delete/status_change/any) optionally gated by a condition formula. Appends to logic/triggers.json. **Use trigger when the platform should react to data changes WITHOUT user interaction**; use jobs for cron-driven; use webhooks for outbound HTTP.",
+  triggerAddSchema,
+  envelope(triggerAdd)
+);
+server.tool(
+  "dforge_job_add",
+  "PHASE 2: Schedule an existing action to fire on a 5-field cron. Appends to logic/jobs.json. Action must NOT use record-context (`[field]`) syntax \u2014 scheduled jobs run as system user with no current record.",
+  jobAddSchema,
+  envelope(jobAdd)
+);
+server.tool(
+  "dforge_webhook_add",
+  "PHASE 2: Subscribe an outbound HTTP endpoint to a DB event. Appends to logic/webhooks.json. Use for integrations with external systems (Slack, Zapier, custom dashboards).",
+  webhookAddSchema,
+  envelope(webhookAdd)
+);
 server.tool(
   "dforge_view_add",
   "PHASE 4: Add a data view to ui/data_views.json. viewType-specific viewConfig is supplied verbatim \u2014 pull dforge://schema/data-views first to know the shape.",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.1.0-rc.10",
+	"version": "0.1.0-rc.12",
 	"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",

package/resources/docs/conventions.md

@@ -492,7 +492,7 @@ before the install pipeline touches the database.
 - Key is the role code (convention: `module.role-name`)
 - **Property name is `"rights"` (NOT `"entityRights"`)** — this maps to `RoleDef.Rights`
 - Each entry in `rights` maps entity code → rights string
-- Rights characters: `S` (Select), `I` (Insert), `U` (Update), `D` (Delete), `C` (Clone)
+- Rights characters: `S` (Select), `I` (Insert), `U` (Update), `D` (Delete), `C` (Clone) for entities, and `E` (Execute) for actions, reports, and folder access (e.g. `"action:create_quote": "E"`). The roles JSON schema enforces `^[SIUDCE]*$`.
 - Every entity should appear in every role (even if only `"S"` for read-only)
 
 **Common Mistakes:**
@@ -539,7 +539,7 @@ seed-data/
 
 ### 7. Scheduled Jobs (`logic/jobs.json`)
 
-Cron-driven action fires. Each entry pairs an existing action (declared in `ui/actions.json`) with a 5-field cron expression; the `dForge.Scheduler` worker fires it on schedule. Full reference: [module-package-format.md → jobs.json](./module-package-format.md#jobsjson).
+Cron-driven action fires. Each entry pairs an existing action (declared in `ui/actions.json`) with a 5-field cron expression; the `dForge.Scheduler` worker fires it on schedule. Full reference: [Scheduled Jobs](../business-logic/jobs.md). Manifest schema: [`jobs.schema.json`](../schemas/jobs.schema.json).
 
 ```json
 {
@@ -593,13 +593,16 @@ Cron-driven action fires. Each entry pairs an existing action (declared in `ui/a
 	"menus": {
 		"hr_menu": { "label": "Human Resources" }
 	},
-	"roles": {
-		"hr.admin": { "label": "HR Administrator" },
-		"hr.viewer": { "label": "HR Viewer" }
+	"actions": {
+		"approve_leave": { "label": "Approve Leave", "desc": "Approve a leave request" }
 	}
 }
 ```
 
+**Translatable sections (consumed by the installer):** `entities` (+ nested `fields`), `folders`, `views`, `menus` (+ nested `items`), `actions` (+ `params`), `reports` (+ `datasets.caption`, `params`).
+
+**Silently ignored at runtime:** `roles` and `print_templates` — the resource rows have no `res_id`, so translations are reserved for future use. `settings` is validated for completeness (when listed in `supportedLocales`) but the registrar does not display the translated labels, so don't expect localized output. Display names for these come from the source manifest (`description` for roles, `label` for print templates and settings).
+
 ---
 
 ## Entity Definitions (`entities/*.json`)
@@ -922,11 +925,11 @@ When creating a module, ensure:
 - [ ] `roles.json` uses `"rights"` property (not `"entityRights"`)
 - [ ] Seed data files are numbered for FK dependency order (01-, 02-, etc.)
 - [ ] Seed data includes explicit PK UUIDs for cross-entity references
-- [ ] `translations/en-US.json` covers entities, fields, views, menus, folders, roles
+- [ ] `translations/<locale>.json` covers entities (+ fields), folders, views, menus (+ items), actions (+ params), and reports (+ dataset captions, + params) for every locale declared in `manifest.supportedLocales`. Do not include `en`/`en-US`. Sections `roles` and `print_templates` are not displayed even if listed.
 - [ ] Constraints have clear user-facing `message` values
 - [ ] Check constraint `expression` uses standard SQL subset (test in PostgreSQL first)
 - [ ] Number sequences declared as `numberSequence` on entity definitions (auto-fills on INSERT, never manual counting)
-- [ ] Print templates defined in `ui/print_templates.json` with HTML files in `print_templates/`
+- [ ] Print templates defined in `ui/print_templates.json` with HTML files in `print_templates/` (see [Print Templates](../ui/print-templates.md))
 - [ ] Scheduled jobs (if any) declared in `logic/jobs.json` with 5-field cron, explicit `timeout`, and `class: "long_running"` for any `timeout > 300`
 
 ---

package/resources/schemas/entity.schema.json

@@ -46,7 +46,10 @@
 		},
 		"fields": {
 			"type": "object",
-			"description": "Column definitions keyed by column code",
+			"description": "Column definitions keyed by column code. Column codes must start with a letter or underscore and contain only letters, digits, and underscores — a leading `-` is reserved for the sort descending prefix in `view_json.order`.",
+			"propertyNames": {
+				"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
+			},
 			"additionalProperties": {
 				"$ref": "#/$defs/field"
 			}

package/resources/schemas/print-templates.schema.json

@@ -0,0 +1,82 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"title": "dForge Module Print Templates",
+	"description": "Print template declarations for a dForge module package (ui/print_templates.json). Each key is the template_cd; the value declares either a printable template (default) or a reusable snippet pulled into other templates via {% include 'module_cd.snippet_cd' %}.",
+	"type": "object",
+	"additionalProperties": {
+		"type": "object",
+		"properties": {
+			"type": {
+				"type": "string",
+				"enum": ["template", "snippet"],
+				"default": "template",
+				"description": "'template' (default) — a full printable form bound to an entity. 'snippet' — a reusable Liquid partial, module-scoped, no entity binding, included from other templates."
+			},
+			"entityCd": {
+				"type": "string",
+				"description": "Entity code this template renders. Required when type='template'; ignored when type='snippet'. Cross-module form 'module.entity' is supported (e.g. fin-ch ships a template for fin.invoice)."
+			},
+			"description": {
+				"type": "string",
+				"description": "Human-readable label shown in the print menu."
+			},
+			"template": {
+				"type": "string",
+				"description": "Inline Liquid HTML. Either 'template' or 'file' must be set; 'file' takes precedence when both are present."
+			},
+			"file": {
+				"type": "string",
+				"description": "Relative path under the module's print_templates/ directory (e.g. 'invoice.html'). Loaded at install time."
+			},
+			"css": {
+				"type": "string",
+				"description": "Inline CSS, or a filename ending in .css (resolved relative to print_templates/). Snippets typically inherit CSS from the host template and omit this."
+			},
+			"pageSettings": {
+				"type": "object",
+				"description": "Default page geometry applied when the user prints from the UI. Stored as jsonb on the row; the editor lets users tweak per-template.",
+				"properties": {
+					"size": {
+						"type": "string",
+						"enum": ["A4", "letter", "legal"],
+						"default": "A4"
+					},
+					"orientation": {
+						"type": "string",
+						"enum": ["portrait", "landscape"],
+						"default": "portrait"
+					},
+					"margins": {
+						"type": "object",
+						"properties": {
+							"top":    { "type": "string", "description": "CSS length, e.g. '15mm'." },
+							"right":  { "type": "string" },
+							"bottom": { "type": "string" },
+							"left":   { "type": "string" }
+						},
+						"additionalProperties": false
+					}
+				},
+				"additionalProperties": false
+			}
+		},
+		"additionalProperties": false,
+		"allOf": [
+			{
+				"if": { "properties": { "type": { "const": "snippet" } }, "required": ["type"] },
+				"then": {
+					"description": "Snippets must not declare entityCd and their template_cd must not contain '.' (collides with {% include 'module_cd.snippet_cd' %})."
+				},
+				"else": {
+					"required": ["entityCd"]
+				}
+			},
+			{
+				"anyOf": [
+					{ "required": ["file"] },
+					{ "required": ["template"] }
+				]
+			}
+		]
+	}
+}

package/resources/schemas/triggers.schema.json

@@ -0,0 +1,59 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "https://dforge.dev/schemas/triggers.schema.json",
+	"title": "dForge Module Triggers",
+	"description": "Trigger definitions for a dForge module (logic/triggers.json). A trigger watches an entity for an event (insert/update/delete/status_change/any), evaluates an optional formula condition using `[field]` syntax, and fires an action if true. Different from scheduled jobs (cron-driven) and webhooks (outbound HTTP) — triggers are intra-tenant DB-event-driven action invocations.",
+	"type": "object",
+	"required": ["triggers"],
+	"properties": {
+		"triggers": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/trigger" }
+		}
+	},
+	"additionalProperties": false,
+	"$defs": {
+		"trigger": {
+			"type": "object",
+			"required": ["code", "entity", "event", "action"],
+			"properties": {
+				"code": {
+					"type": "string",
+					"pattern": "^[a-z][a-z0-9_]*$",
+					"description": "Trigger code, unique within the module."
+				},
+				"description": {
+					"type": "string",
+					"description": "Human-readable description of what the trigger does and when."
+				},
+				"entity": {
+					"type": "string",
+					"description": "Entity whose events this trigger watches. May be cross-module via dot notation (e.g. 'fin.invoice')."
+				},
+				"event": {
+					"type": "string",
+					"enum": ["insert", "update", "delete", "status_change", "any"],
+					"description": "DB event that fires this trigger. 'status_change' only fires when the entity's status field actually changes value. 'any' fires for all insert/update/delete."
+				},
+				"condition": {
+					"type": "string",
+					"description": "Optional formula expression — same shape as canExecute in action DSL. Uses `[field]` syntax to reference the affected record. Single-line, evaluates to boolean. If omitted, trigger fires for every matching event."
+				},
+				"action": {
+					"type": "string",
+					"description": "Action code to invoke. The action must NOT use record-context (`[field]`) syntax in a way that requires the original triggering record — the trigger passes the record id via params. Cross-module form 'module.action' is supported."
+				},
+				"params": {
+					"type": "object",
+					"description": "Optional static parameters passed to the action at invocation time. Merged with the runtime-injected `record_id` / `record_old` (if event uses old-record diff)."
+				},
+				"async": {
+					"type": "boolean",
+					"default": false,
+					"description": "When true, the action runs in the background — the triggering transaction commits before the action starts. Recommended for slow actions (emails, external API calls). When false, the action runs in the same transaction; failures roll back the original DB change."
+				}
+			},
+			"additionalProperties": false
+		}
+	}
+}

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

@@ -1,6 +1,6 @@
 ---
 name: dforge-mcp-author
-description: Co-pilot for authoring dForge modules via the dforge-mcp tool surface. Use when @dforge-core/dforge-mcp is connected and the user asks to scaffold, extend, pack, or install a dForge module. Drafts and proposes; the user approves at named gates. Walks the user through six phases with explicit gates for confirmation, a deterministic backtrack protocol, a tool-failure protocol, and resume-from-partial-state support.
+description: Co-pilot for authoring dForge modules via the dforge-mcp tool surface. Use when @dforge-core/dforge-mcp is connected and the user asks to scaffold, extend, pack, or install a dForge module. Drafts and proposes; the user approves at named gates. Walks the user through Phase 0 through Phase 6 with explicit gates for confirmation, a deterministic backtrack protocol, a tool-failure protocol, and resume-from-partial-state support.
 ---
 
 # dForge Module Author — Co-pilot
@@ -20,6 +20,9 @@ The phase column below indicates the **typical** use. During a backtrack, the ba
 | `dforge_entity_field_modify` | 1 | Replace one field's spec |
 | `dforge_entity_field_remove` | 1 | Drop one field (warns about dependents) |
 | `dforge_action_add` | 2 | DSL action + ui/actions.json entry |
+| `dforge_trigger_add` | 2 | DB-event trigger in logic/triggers.json |
+| `dforge_job_add` | 2 | Scheduled job in logic/jobs.json |
+| `dforge_webhook_add` | 2 | Outbound webhook in logic/webhooks.json |
 | `dforge_view_add` | 3 | Data view in ui/data_views.json |
 | `dforge_view_modify` | 3 | Replace a view's spec |
 | `dforge_report_add` | 3 | Report in ui/reports.json |
@@ -34,7 +37,7 @@ The phase column below indicates the **typical** use. During a backtrack, the ba
 ## Resources to load once per session
 
 - `dforge://docs/conventions` — naming, FK+Reference pattern, traits, security model
-- `dforge://schema/manifest`, `entity`, `data-views`, `folders`, `menus`, `roles`, `reports`, `settings`, `jobs`, `seed-data` — consult before emitting each file kind
+- `dforge://schema/manifest`, `entity`, `data-views`, `folders`, `menus`, `roles`, `reports`, `settings`, `jobs`, `triggers`, `webhooks`, `seed-data` — consult before emitting each file kind
 
 **If a resource fails to load, halt and notify the user.** Do not invent conventions or schemas from memory.
 
@@ -42,11 +45,11 @@ The phase column below indicates the **typical** use. During a backtrack, the ba
 
 These are absolute. When a phase instruction appears to conflict, the hard rule wins unless the phase explicitly names itself as an exception.
 
-1. **Co-pilot stance.** Draft → propose → user approves → tool call → file write. Never write without confirmation.
-2. **Inspect before patching.** Run `dforge_module_inspect` at session start and after every backtrack. Inspect output is read-only; show a summary and continue without asking confirmation for the inspect itself — confirmation applies only to **write** tools.
+1. **Co-pilot stance.** Draft → propose → user approves → write-tool call → file write. Never write without confirmation. Read-only tools do not need a confirmation gate.
+2. **Inspect before patching.** Run `dforge_module_inspect` at session start and after every backtrack. Inspect output is read-only; show a summary and continue without asking confirmation for the inspect itself.
 3. **One thing at a time when interacting with the user.** Applies to:
    - **Questions.** Ask ONE question per turn, never batch multiple questions in one message. Each subsequent question is informed by prior answers. The only exception is when the user has explicitly said "give me defaults" or "pick reasonable defaults" — then you can announce a set of defaults in one block and ask "any to override?".
-   - **Entities / views / roles / actions / reports.** Propose ONE per turn. Never batch these. (Field batching inside an entity has a narrow exception in Phase 1.)
+   - **Entities / views / roles / actions / reports.** Propose ONE per turn. Never batch these. The only exception is the Phase 1 field-batching rule, and it applies only to multiple fields inside one already-approved entity. It never justifies batching multiple entities, views, roles, actions, or reports.
 4. **Validate-and-reflect every step.** After every user answer, BEFORE moving to the next question or tool call: restate what you understood in your own words and ask "Right?" or "Does that capture it?". Only proceed once the user confirms. If they correct, repeat the restate-and-confirm loop until aligned. **Goal: zero ambiguity going into the next step.** If you have questions, ask and wait for answers — never proceed with unanswered ones in your head.
 5. **Tabs in JSON, trailing newline** — tools already emit this; don't reformat.
 6. **Don't invent fields, codes, roles, or relationships** — they come from the user's domain. If the user said "we have submitters and admins", roles are derived from that; do NOT default to a fixed "admin/contributor/viewer" taxonomy or any other generic set the user didn't ask for.
@@ -135,7 +138,7 @@ At every session start, call `dforge_module_inspect` on the module dir (if it ex
 - `# <module-name> — intake`
 - `## Purpose` (one paragraph)
 - `## Module identity` (code, display name, target path)
-- `## User types` (bullet list — `<type> — <verbs>`. NO role codes, NO rights, NO "Target user roles" table.)
+- `## User types` (bullet list of verb-led sentences describing what each kind of user does. NO role codes, NO rights, NO "Target user roles" table.)
 - `## Dependencies` (which dForge modules)
 - `## Languages`
 - `## Scope / success criteria` (only if mentioned by user)
@@ -175,15 +178,55 @@ A field is **batchable** only if ALL of these are true: scalar primitive (string
 
 **Exit criteria:** every entity has at least PK + audit traits + 1 user-visible field; FK references resolve; manifest's `entities` map reflects reality.
 
-## Phase 2 — Actions (optional, skip-able)
+## Phase 2 — Behavior (optional sub-steps)
 
 **Preconditions:** Phase 1 complete.
 
-Skip entirely if the module is pure CRUD. Do **not** fabricate actions to fill the phase.
+Phase 2 covers four kinds of behavior — all optional, all individually skip-able. Each fires action logic, but the **trigger** differs:
 
-When the user has a real business operation: **load `dforge://docs/dsl`** (the full action DSL reference — block structure, all 30 built-in functions, field-access syntax, batch-mode rules, JS subset, pitfalls), then call `dforge_action_add` per action — one at a time — with the full DSL body. `dforge://docs/conventions` is broader module-level guidance and does NOT cover the DSL grammar — load `docs/dsl` specifically.
+| Sub-step | Fires when | File | Tool | Use when |
+|---|---|---|---|---|
+| 2a Actions | user clicks a button | `ui/actions.json` + `logic/actions/*.dsl` | `dforge_action_add` | bulk operations, business workflows, anything that needs user input via params |
+| 2b Triggers | DB event happens (insert/update/delete/status_change) | `logic/triggers.json` | `dforge_trigger_add` | reactive automation: "when X happens, do Y" without user action |
+| 2c Scheduled jobs | cron timer | `logic/jobs.json` | `dforge_job_add` | periodic work: nightly cleanup, daily summary, hourly poll |
+| 2d Webhooks | DB event happens → POSTs to external URL | `logic/webhooks.json` | `dforge_webhook_add` | integrations: Slack notifications, Zapier, external dashboards, audit log shipping |
 
-**Exit criteria:** every action you added is intended, named, and has params/canExecute/execute blocks. Compilation is validated in Phase 6.
+Skip a sub-step entirely if the user has no need for it. Do NOT fabricate behavior to fill a sub-step. Phase 2 can be completely skipped for pure CRUD modules.
+
+### 2a. Actions — user-triggered
+
+**Load `dforge://docs/dsl`** (the full action DSL reference — block structure, all 30 built-in functions, field-access syntax, batch-mode rules, JS subset, common patterns, anti-patterns) before authoring any DSL. `dforge://docs/conventions` is broader module-level guidance and does NOT cover the DSL grammar.
+
+Call `dforge_action_add` per action — one at a time — with the full DSL body. Confirm with the user before each call.
+
+### 2b. Triggers — DB-event-driven
+
+**Load `dforge://schema/triggers`** for the shape; also re-read the trigger formula rules in `dforge://docs/dsl` (trigger conditions use the same syntax as `canExecute:`: single-line `[field] op value` formulas).
+
+For each trigger, propose: entity + event + (optional) condition formula + target action + async flag. Use `dforge_trigger_add`. Triggers reference EXISTING actions — make sure the action exists first (Phase 2a or scaffolded admin actions).
+
+**Async vs sync:** `async: true` runs the action in the background after the triggering transaction commits — recommended for slow actions (emails, external API calls). `async: false` runs in the same transaction; action failure rolls back the original DB change.
+
+### 2c. Scheduled jobs — cron-driven
+
+**Load `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.
+- `timeout` is required, ≤ 3600s.
+- If `timeout > 300`, you MUST set `jobClass: 'long_running'`.
+
+Use `dforge_job_add` per job.
+
+### 2d. Webhooks — outbound HTTP
+
+**Load `dforge://schema/webhooks`**.
+
+For each webhook: entity + event + endpoint URL + (optional) condition + (optional) payload shape (include/exclude/includeOld). Use `dforge_webhook_add`.
+
+For authenticated endpoints: put bearer tokens / API keys behind `getSecret()` (configure secret in module's secrets), reference in headers as `"Authorization": "$secret:<secret_cd>"` — the platform resolves at fire time.
+
+**Exit criteria for Phase 2:** every action / trigger / job / webhook you added is intended (user-requested, not fabricated to fill space) and references existing entities + actions. Compilation is validated at install in Phase 6.
 
 ## Phase 3 — Views (required) + Reports (optional)
 
@@ -232,7 +275,7 @@ Add reports only when management aggregation/grouping isn't covered by views. `d
 ### 5a. Roles + rights matrix (required)
 
 1. **Inspect first.** Run `dforge_module_inspect` and read the `roles` array. The scaffolder pre-creates `<code>.admin` with `SIUDC` on every entity declared at scaffold time. That role exists already — don't try to re-create it.
-2. **Derive role inventory FROM the intake's user types and verbs — never default to a fixed taxonomy.** Re-read `_brief/00-intake.md`'s "users" section. For each distinct user type, propose ONE role named `<code>.<user-type>` (e.g. intake said "any signed-in user submits + admins triage" → `<code>.user` (covers the "submits" verb) + the existing scaffolded `<code>.admin` (covers triage). If intake mentioned "approvers" or "auditors" or "managers" or any other group, derive roles for those too.) **Forbidden:** spinning up a generic `admin/contributor/viewer` matrix when the user didn't ask for it. The rights set should map to the verbs each user type does, not to a textbook role hierarchy.
+2. **Derive role inventory FROM the intake's user types and verbs — never default to a fixed taxonomy.** Re-read `_brief/00-intake.md`'s `User types` section. For each distinct user type, propose ONE role named `<code>.<user-type>` (e.g. intake said "any signed-in user submits + admins triage" → `<code>.user` (covers the "submits" verb) + the existing scaffolded `<code>.admin` (covers triage). If intake mentioned "approvers" or "auditors" or "managers" or any other group, derive roles for those too.) **Forbidden:** spinning up a generic `admin/contributor/viewer` matrix when the user didn't ask for it. The rights set should map to the verbs each user type does, not to a textbook role hierarchy.
 3. Reflect the proposed role list back to the user before computing rights: "Based on intake, I see these user types → these roles: `<list>`. Right?" Get explicit confirmation. If the user clarifies / adds / removes, re-list and re-confirm.
 4. Show the rights matrix as a table (rows = entities/actions/reports, columns = the confirmed roles, cells = rights string). Each cell explained by the verb-to-right mapping you derived. Get user sign-off on the matrix.
 5. **For new roles**: call `dforge_role_add`. **For amending existing roles** (the scaffolded admin, or grants on actions/reports added in Phases 2-3 that aren't yet in any role): call `dforge_role_right_set` per grant — it's the smallest tool and doesn't conflict with the scaffolded admin role. Calling `dforge_role_add` against an existing role code fails — use `role_right_set` to amend instead.