@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-governance/scripts/synthesize-formdata.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+
+const args = {};
+for (let i = 2; i < process.argv.length; i++) {
+    if (process.argv[i].startsWith("--")) args[process.argv[i].slice(2)] = process.argv[++i];
+}
+for (const r of ["catalog", "product", "clause-ids", "out"]) {
+    if (!args[r]) { console.error(`error: --${r} is required`); process.exit(2); }
+}
+
+function readJson(p) {
+    try { return JSON.parse(fs.readFileSync(p, "utf8")); }
+    catch (e) { console.error(`error reading ${p}: ${e.message}`); process.exit(2); }
+}
+
+function setNested(obj, dotted, value) {
+    const segs = dotted.split(".");
+    let cur = obj;
+    for (let i = 0; i < segs.length - 1; i++) {
+        if (cur[segs[i]] == null || typeof cur[segs[i]] !== "object") cur[segs[i]] = {};
+        cur = cur[segs[i]];
+    }
+    cur[segs.at(-1)] = value;
+}
+
+const raw = readJson(args["catalog"]);
+// Normalize: CLI output is PascalCase; accept both PascalCase and camelCase.
+const data = raw?.PackId || raw?.packId ? raw : (raw?.Data ?? raw);
+function pick(obj, ...keys) { for (const k of keys) if (obj[k] !== undefined) return obj[k]; }
+const catalog = {
+    clauses: (pick(data, "Clauses", "clauses") ?? []).map(c => ({
+        clauseId: pick(c, "ClauseId", "clauseId"),
+        editorialPolicies: (pick(c, "EditorialPolicies", "editorialPolicies") ?? []).map(ep => ({
+            productIdentifier: pick(ep, "ProductIdentifier", "productIdentifier"),
+            contributions: (pick(ep, "Contributions", "contributions") ?? []).map(cn => {
+                const req = pick(cn, "Required", "required") ?? {};
+                return {
+                    key: pick(cn, "Key", "key"),
+                    required: {
+                        eq:       pick(req, "Eq",       "eq"),
+                        gte:      pick(req, "Gte",      "gte"),
+                        lte:      pick(req, "Lte",      "lte"),
+                        contains: pick(req, "Contains", "contains"),
+                        notEmpty: pick(req, "NotEmpty", "notEmpty"),
+                        exists:   pick(req, "Exists",   "exists"),
+                    },
+                };
+            }),
+        })),
+    })),
+};
+const targetProduct = args["product"];
+const targetClauseIds = new Set(args["clause-ids"].split(",").map(s => s.trim()).filter(Boolean));
+
+const formData = {};
+const warnings = [];
+let count = 0;
+
+for (const clause of catalog.clauses) {
+    if (!targetClauseIds.has(clause.clauseId)) continue;
+    for (const ep of clause.editorialPolicies) {
+        if (ep.productIdentifier !== targetProduct) continue;
+        for (const { key, required } of ep.contributions) {
+            if (!required) continue;
+            if (required.eq !== undefined)             { setNested(formData, key, required.eq);        count++; }
+            else if (required.gte !== undefined)       { setNested(formData, key, required.gte);       count++; }
+            else if (required.lte !== undefined)       { setNested(formData, key, required.lte);       count++; }
+            else if (Array.isArray(required.contains)) { setNested(formData, key, required.contains);  count++; }
+            else if (required.notEmpty === true)       warnings.push(`"${key}": notEmpty — value is org-specific; configure manually`);
+            else if (required.exists === true)         warnings.push(`"${key}": exists — access policy check, not a formData key`);
+            else warnings.push(`"${key}": unknown operator ${JSON.stringify(required)}`);
+        }
+    }
+}
+
+if (count === 0) {
+    console.error(`error: no contributions for product "${targetProduct}" in clauses [${[...targetClauseIds].join(", ")}]`);
+    process.exit(3);
+}
+
+warnings.forEach(w => console.warn(`  ⚠ ${w}`));
+fs.mkdirSync(path.dirname(path.resolve(args["out"])), { recursive: true });
+fs.writeFileSync(args["out"], JSON.stringify(formData, null, 2));
+process.stdout.write(`SYNTHESIZED: ${path.resolve(args["out"])} (${count} contributions)\n`);

package/skills/uipath-human-in-the-loop/SKILL.md

@@ -34,14 +34,18 @@ See [references/hitl-patterns.md](references/hitl-patterns.md) for the full busi
 
 1. **Confirm schema with the user before writing anything for quickform type.** Show the designed schema and wait for explicit confirmation.
 2. **Always wire the `completed` handle.** A HITL node with no outgoing edge on `completed` blocks the flow forever. Only `completed` is available as an output handle — **not** `output`, `success`, or any other name. This is true even when inserting into an existing flow whose other nodes use `"sourcePort": "output"`.
-3. **Always add the definition entry when inserting into an existing flow.** Before writing the node, check `workflow.definitions[]` for `"nodeType": "uipath.human-in-the-loop"`. If absent, append the full definition entry (with `handleConfiguration` including the `completed` handle). Skipping the definition means the `completed` handle is invisible to the runtime and the wiring check fails.
+3. **Always add the definition entry when inserting into an existing flow.** Before writing the node, check `workflow.definitions[]` for the correct `nodeType` for the selected path (`"uipath.human-in-the-loop.quick-form"` for QuickForm, `"uipath.human-in-the-loop.coded-action-app"` for app-based). If absent, append the full definition entry (with `handleConfiguration` including the `completed` handle). Skipping the definition means the `completed` handle is invisible to the runtime and the wiring check fails.
 4. **Regenerate `variables.nodes` after adding the node.** Replace the entire `workflow.variables.nodes` array — do not append. See the reference docs for the algorithm.
 5. **Validate after every change.** Run `uip maestro flow validate <file> --output json` after writing the node and edges. The `uip` CLI does not accept `--format`; using it produces `error: unknown option '--format'` and exit code 3.
 6. **Read the existing `.flow` file before adding.** Understand which nodes already exist and where the HITL checkpoint belongs in the flow.
-7. **The definition entry is added once.** Check `workflow.definitions` — if `uipath.human-in-the-loop` is already there, do not add it again.
+7. **The definition entry is added once per node type.** Check `workflow.definitions` — if an entry with the matching `nodeType` is already there, do not add it again.
 8. **Check existing node IDs before generating a new one.** Read `workflow.nodes[*].id` from the `.flow` file and pick the next available suffix (e.g. `invoiceReview1`, then `invoiceReview2`).
 9. **Never report a failed validation as done.** If `uip maestro flow validate` returns errors, diagnose from the JSON output and fix before reporting to the user.
-10. **Output fields are accessed by `field.id`, not `field.variable`.** The runtime result object uses field IDs as keys — `$vars.<nodeId>.output.<fieldId>`. The `variable` property creates a separate workflow-global variable (`$vars.{variable}`) but does NOT change the key used in the output object.
+10. **Output fields are accessed by `field.id`, not `field.variable`.** The runtime result object uses field IDs as keys — `$vars.<nodeId>.output.<fieldId>`. The `variable` property only creates a workflow-global alias; it does NOT change the key used in the node output object, and it is NOT how downstream scripts read the value.
+    - WRONG: `$vars.legalApproval` — this is the global alias path, not the script access path
+    - WRONG: `$vars.<nodeId>.output.legalApproval` — this uses the variable name as the key
+    - RIGHT: `$vars.<nodeId>.output.approved` — uses `field.id` ("approved") as the key
+    In every downstream script, use `$vars.<nodeId>.output.<fieldId>` where `<fieldId>` is the `id` you gave the field in the schema — never the `variable` name.
 11. **Input field binding paths use the upstream output key, not the HITL field's own `id`.** These are two different things: the HITL field `id` identifies the form field (always lowercase); the binding path key is the name used in the upstream script's `return` statement (preserves camelCase). If a script returns `{ supplierName: "Acme" }`, the correct binding is `vars.fetchSupplier.output.supplierName` — writing `suppliername` (the field `id`) produces a path that does not exist at runtime. The form field will be blank; `flow validate` will not catch it. Always derive the binding key from the upstream script source, not from the HITL schema you are designing.
 12. **Downstream scripts must access `$vars.<nodeId>.output`.** Any script node that runs after the HITL node must read `$vars.<nodeId>.output` (the result object) — do not rely solely on `$vars.<nodeId>.status`. Concrete example: `const output = $vars.reviewNode1.output; const reason = output.reason;`. This is required even when the primary routing uses `status`.
 
@@ -107,7 +111,7 @@ Read the existing `.flow` file to understand current nodes and edges. Use the Re
 2. **What the human needs to see** — data produced by upstream nodes
 3. **What the human must provide back** — data needed by downstream nodes
 4. **What actions they can take** — the named outcome buttons
-5. **Form type**: QuickForm (`inputs.type = "quick"`, inline schema) or AppTask (`inputs.type = "custom"`, deployed coded app)?
+5. **Form type**: QuickForm (inline schema, node type `uipath.human-in-the-loop.quick-form`) or AppTask (deployed coded app, node type `uipath.human-in-the-loop.coded-action-app`)?
 
 ---
 
@@ -140,11 +144,11 @@ Wait for confirmation. Do not proceed to schema design until the user confirms.
 
 Present the user with three options. Do not choose on their behalf or perform any registry search.
 
-| # | Option | `inputs.type` value | Description |
+| # | Option | Node type | Description |
 |---|---|---|---|
-| 1 | **QuickForm** | `"quick"` | Inline typed form — fields rendered by Action Center from the schema you design here |
-| 2 | **New Coded Action App** | `"custom"` | Scaffold a new React + TypeScript app inside the solution — full UI control |
-| 3 | **Existing Deployed App** | `"custom"` | Reference an app already deployed to Orchestrator |
+| 1 | **QuickForm** | `uipath.human-in-the-loop.quick-form` | Inline typed form — fields rendered by Action Center from the schema you design here |
+| 2 | **New Coded Action App** | `uipath.human-in-the-loop.coded-action-app` | Scaffold a new React + TypeScript app inside the solution — full UI control |
+| 3 | **Existing Deployed App** | `uipath.human-in-the-loop.coded-action-app` | Reference an app already deployed to Orchestrator |
 
 > **If the user's request is purely business-oriented** (no mention of a deployed app, coded action app, or custom UI): skip the question and proceed directly with QuickForm. Do not ask. Say: "I'll use QuickForm — it's inline, no deployment step needed, and works for most approval and review tasks."
 
@@ -174,36 +178,37 @@ Present the user with three options. Do not choose on their behalf or perform an
 
 ---
 
-## Step 4b — Schema Design Resilience (QuickForm only)
+## Step 4b — Schema Design Rules (QuickForm only)
 
-Apply these checks while designing the schema before confirming with the user.
+Apply these rules unconditionally while designing the schema.
 
-### Data type warnings
+### Field direction
 
-Flag these patterns and confirm before proceeding:
+Pick direction based on what the human does with the field:
 
-| Field description contains | Suggest type | Warning to show |
-|---|---|---|
-| "amount", "price", "cost", "total", "quantity", "count", "score", "percentage" | `number` | "I'm using `number` for `<field>` — confirm that's correct, or tell me if it should be text." |
-| "date", "deadline", "due", "scheduled" | `date` | "I'm using `date` for `<field>` — confirm, or use `text` if the format varies." |
-| "approved", "enabled", "active", "is ", "flag" | `boolean` | "I'm using `boolean` (true/false) for `<field>` — confirm, or use `text` if you need more than two states." |
+| Signal | Direction |
+|---|---|
+| "can see", "shown to", "read-only", "displays", "context for reviewer" | `input` |
+| "fills in", "enters", "types", "selects", "required decision", "approves" | `output` |
+| "can edit", "can correct", "pre-filled but editable", "suggested value the reviewer can adjust" | `inOut` |
+
+`inOut` means the field is pre-populated from an upstream node AND the human can modify it before submitting. The runtime exposes it under `$vars.<nodeId>.output.<fieldId>` the same as an output field.
+
+### Field types
+
+Use the JS/JSON type that fits the field: `string`, `number`, `boolean`, `date`, or `file`. These are the only valid values — do not use `text`.
 
 ### Vague or incomplete schema descriptions
 
 If the user says something like "just add some fields" or "use whatever makes sense":
 
 1. Infer sensible defaults from the upstream data and downstream needs visible in the `.flow` file.
-2. Show the proposed schema explicitly before writing: "Here's what I'm proposing — let me know if you want to change anything."
-3. If there are no upstream nodes to bind to (flow is just a trigger), use output-direction fields only and note: "There are no upstream nodes to pull data from, so the reviewer will fill in all fields from scratch."
+2. If there are no upstream nodes to bind to (flow is just a trigger), use output-direction fields only.
 
 ### Empty field labels block validation
 
 Every field in `inputs.schema.fields` must have a non-empty `label`. `flow validate` emits `HITL_QUICK_FORM_FIELD_LABEL_REQUIRED` (error severity) for each field with an empty or whitespace-only `label` — Debug and Publish are blocked until all labels are filled in. Never generate a field with `"label": ""` or omit the `label` key.
 
-### Partial confirmation
-
-If the user says "yes but change X" or gives conditional approval, apply the change and re-show the full updated schema for final confirmation before writing. Never write with an unresolved change.
-
 ---
 
 ## Step 5 — Write the Node Directly
@@ -237,7 +242,7 @@ uip maestro flow validate <file> --output json
 
 Step 4c must be completed first — app name confirmed, solution directory located, SDK tarball identified, schema designed and confirmed.
 
-Scaffold the project directory and all source files, add the project to the solution, write the solution resource files, then write the HITL node with `inputs.type = "custom"` and `inputs.app` referencing the new app (`appSystemName: null` since the app has not been deployed yet).
+Scaffold the project directory and all source files, add the project to the solution, write the solution resource files, then write the HITL node (type `uipath.human-in-the-loop.coded-action-app`) with `inputs.app` referencing the new app (`appSystemName: null` since the app has not been deployed yet).
 
 Full project template, UUID generation, solution CLI commands, resource file templates, node JSON, and post-creation build steps: **[How to scaffold a new Coded Action App](references/hitl-node-coded-action-app.md)**
 
@@ -251,7 +256,7 @@ uip maestro flow validate <file> --output json
 
 Step 4b must be completed first — app resolved, configuration retrieved. Then:
 
-Resolve the solution context (`.uipx` file), write solution resource files, register the app reference, merge `debug_overwrites.json`, then write the node JSON with `inputs.type = "custom"` and `inputs.app` populated from the Step 3b configuration.
+Resolve the solution context (`.uipx` file), write solution resource files, register the app reference, merge `debug_overwrites.json`, then write the node JSON (type `uipath.human-in-the-loop.coded-action-app`) with `inputs.app` populated from the Step 3b configuration.
 
 App search/selection, retrieve-configuration, resource file writing, complete node JSON with `appInputBindings`: **[How to wire an existing deployed Action App](references/hitl-node-apptask.md)**
 

package/skills/uipath-human-in-the-loop/references/hitl-node-apptask.md

@@ -1,6 +1,6 @@
 # HITL AppTask Node — Direct JSON Reference
 
-The AppTask variant uses a deployed coded app (Studio Web) as the task form. Same node type as QuickForm (`uipath.human-in-the-loop`), same three output handles. Difference: `inputs.type = "custom"` and `inputs.app` points to the deployed app.
+The AppTask variant uses a deployed coded app (Studio Web) as the task form. Node type: `uipath.human-in-the-loop.coded-action-app`. Same three handles (`input`, `completed`) as QuickForm. Difference from QuickForm: `inputs.app` points to the deployed app (no inline schema).
 
 ---
 
@@ -281,11 +281,10 @@ Merge rules:
 ```json
 {
   "id": "invoiceReview1",
-  "type": "uipath.human-in-the-loop",
+  "type": "uipath.human-in-the-loop.coded-action-app",
   "typeVersion": "1.0",
   "display": { "label": "Invoice Review" },
   "inputs": {
-    "type": "custom",
     "recipient": {
       "channels": ["ActionCenter"],
       "connections": {},
@@ -382,7 +381,42 @@ Maps app parameter names to binding expressions. Format: `"=vars.<path>"` (with
 
 ## Definition Entry
 
-Same definition as QuickForm — see [hitl-node-quickform.md](hitl-node-quickform.md) for the full definition block. Add it once to `workflow.definitions`, deduplicated by `nodeType`.
+AppTask uses a **separate** definition entry — `nodeType` is `"uipath.human-in-the-loop.coded-action-app"`, not `"uipath.human-in-the-loop.quick-form"`. Add it once to `workflow.definitions`, deduplicated by `nodeType`.
+
+```json
+{
+  "nodeType": "uipath.human-in-the-loop.coded-action-app",
+  "version": "1.0",
+  "category": "human-task",
+  "description": "App-based human task using a deployed coded action app",
+  "tags": ["human-task", "hitl", "human-in-the-loop", "coded-action-app", "approval"],
+  "sortOrder": 28,
+  "display": {
+    "label": "App Task",
+    "icon": "users",
+    "shape": "square"
+  },
+  "handleConfiguration": [
+    {
+      "position": "left",
+      "handles": [{ "id": "input", "type": "target", "handleType": "input" }],
+      "visible": true
+    },
+    {
+      "position": "right",
+      "handles": [
+        { "id": "completed", "type": "source", "handleType": "output", "showButton": true, "constraints": { "forbiddenTargetCategories": ["trigger"] } }
+      ],
+      "visible": true
+    }
+  ],
+  "model": { "type": "bpmn:UserTask", "serviceType": "Actions.HITL" },
+  "outputDefinition": {
+    "output": { "type": "object", "description": "Task result data", "source": "=result", "var": "output" },
+    "status": { "type": "string", "description": "Task completion status", "source": "=result.Action", "var": "status" }
+  }
+}
+```
 
 ---
 

package/skills/uipath-human-in-the-loop/references/hitl-node-coded-action-app.md

@@ -273,12 +273,11 @@ All values below come directly from the `ParsedActionSchema` assembled in Step 4
 ```json
 {
   "id": "<NODE_ID>",
-  "type": "uipath.human-in-the-loop",
+  "type": "uipath.human-in-the-loop.coded-action-app",
   "typeVersion": "1.0.0",
   "display": { "label": "<LABEL>" },
   "ui": { "position": { "x": 474, "y": 144 } },
   "inputs": {
-    "type": "custom",
     "channels": [],
     "recipient": {
       "channels": ["ActionCenter"],
@@ -318,7 +317,7 @@ All values below come directly from the `ParsedActionSchema` assembled in Step 4
 "recipient": { "channels": ["ActionCenter"], "assignee": { "type": "group", "value": "Finance Team" } }
 ```
 
-**Definition entry** — same as QuickForm. See [hitl-node-quickform.md](hitl-node-quickform.md) for the full definition block. Add once to `workflow.definitions`, deduplicated by `nodeType`.
+**Definition entry** — uses `nodeType: "uipath.human-in-the-loop.coded-action-app"` (NOT the QuickForm nodeType). See [hitl-node-apptask.md](hitl-node-apptask.md#definition-entry) for the full definition block. Add once to `workflow.definitions`, deduplicated by `nodeType`.
 
 **Edge wiring** — wire `completed` (only handle available in v1.0). See [hitl-node-quickform.md](hitl-node-quickform.md) for edge format.
 

package/skills/uipath-human-in-the-loop/references/hitl-node-quickform.md

@@ -1,6 +1,6 @@
 # HITL QuickForm Node — Direct JSON Reference
 
-The agent writes the `uipath.human-in-the-loop` node directly into the `.flow` file as JSON. **Direct JSON is the default.** A CLI opt-in is available when the user explicitly requests it, or as a fallback if direct JSON writing fails — see [CLI reference: uip maestro flow hitl add](../../uipath-maestro-flow/references/shared/cli-commands.md#uip-maestro-flow-hitl-add).
+The agent writes the `uipath.human-in-the-loop.quick-form` node directly into the `.flow` file as JSON. **Direct JSON is the default.** A CLI opt-in is available when the user explicitly requests it, or as a fallback if direct JSON writing fails — see [CLI reference: uip maestro flow hitl add](../../uipath-maestro-flow/references/shared/cli-commands.md#uip-maestro-flow-hitl-add).
 
 ---
 
@@ -69,7 +69,7 @@ Also read `workflow.variables.globals`. Each entry has an `id` that maps directl
 | Node output | `vars.<nodeId>.output.<field>` | `=js:$vars.<nodeId>.output.<field>` |
 | Flow global (`direction: "in"`) | `vars.<globalId>` | `=js:$vars.<globalId>` |
 
-> **`binding` vs `variable` prefix rule:** `binding` (input/inOut fields) uses the full path starting with `vars.` because it references an existing variable path. `variable` (output/inOut fields) is just a **name** with no prefix — it declares a new global variable, not a reference to an existing one.
+> **`binding` vs `variable` prefix rule:** `binding` (input/inOut fields) uses the full path starting with `vars.` because it references an existing variable path. `variable` (output/inOut fields) uses `vars.<name>` — the `vars.` prefix is required; it declares the global variable name.
 
 For the full variable system, see → [How $vars paths are constructed in Flow](../../uipath-maestro-flow/references/shared/variables-and-expressions.md)
 
@@ -85,7 +85,7 @@ The node schema uses `fields[]` entries inside `inputs.schema`. Use these concep
 | Output field | `"output"` | Write | Data the automation needs back |
 | InOut field | `"inOut"` | Read + modify | Data the human can see and optionally correct |
 
-**Supported field types:** `text` (maps from `string`), `number`, `boolean`, `date`
+**Supported field types:** `string`, `number`, `boolean`, `date`, `file`
 
 **Design rules:**
 - Input fields: everything the human needs to decide — IDs, amounts, context; bind to upstream node output via `binding`
@@ -102,11 +102,10 @@ The node schema uses `fields[]` entries inside `inputs.schema`. Use these concep
 ```json
 {
   "id": "invoiceReview1",
-  "type": "uipath.human-in-the-loop",
+  "type": "uipath.human-in-the-loop.quick-form",
   "typeVersion": "1.0",
   "display": { "label": "Invoice Review" },
   "inputs": {
-    "type": "quick",
     "title": "Invoice Review",
     "recipient": {
       "channels": ["Email", "ActionCenter"],
@@ -120,7 +119,7 @@ The node schema uses `fields[]` entries inside `inputs.schema`. Use these concep
         {
           "id": "invoiceid",
           "label": "Invoice ID",
-          "type": "text",
+          "type": "string",
           "direction": "input",
           "binding": "vars.fetchInvoice.output.invoiceId"
         },
@@ -134,17 +133,17 @@ The node schema uses `fields[]` entries inside `inputs.schema`. Use these concep
         {
           "id": "notes",
           "label": "Notes",
-          "type": "text",
+          "type": "string",
           "direction": "output",
-          "variable": "notes",
+          "variable": "vars.notes",
           "required": false
         },
         {
           "id": "decision",
           "label": "Decision",
-          "type": "text",
+          "type": "string",
           "direction": "output",
-          "variable": "decision",
+          "variable": "vars.decision",
           "required": true
         }
       ],
@@ -186,17 +185,18 @@ The node schema uses `fields[]` entries inside `inputs.schema`. Use these concep
 
 ## Definition Entry
 
-Every `.flow` file must have one definition entry for `uipath.human-in-the-loop` in `workflow.definitions`. Add it exactly once — deduplicate by `nodeType`.
+Every `.flow` file must have one definition entry for `uipath.human-in-the-loop.quick-form` in `workflow.definitions`. Add it exactly once — deduplicate by `nodeType`.
 
 ```json
 {
-  "nodeType": "uipath.human-in-the-loop",
+  "nodeType": "uipath.human-in-the-loop.quick-form",
   "version": "1.0",
   "category": "human-task",
-  "tags": ["human-task", "hitl", "human-in-the-loop", "approval"],
-  "sortOrder": 50,
+  "description": "Fast inline approvals with inline debug",
+  "tags": ["human-task", "hitl", "human-in-the-loop", "quick-form", "approval"],
+  "sortOrder": 27,
   "display": {
-    "label": "Human in the Loop",
+    "label": "Quick Form",
     "icon": "users",
     "shape": "square"
   },
@@ -222,7 +222,6 @@ Every `.flow` file must have one definition entry for `uipath.human-in-the-loop`
   ],
   "model": { "type": "bpmn:UserTask", "serviceType": "Actions.HITL" },
   "inputDefaults": {
-    "type": "quick",
     "schema": {
       "fields": [],
       "outcomes": [{ "id": "submit", "name": "Submit", "type": "string", "isPrimary": true, "action": "Continue" }]
@@ -279,7 +278,63 @@ The HITL node exposes two outputs (`output`, `status`). After adding it, **compl
 
 Include entries for **all** nodes in the flow, not just the HITL node. Replace the entire array — do not append. Add one `output` entry and one `status` entry per HITL node — no per-field entries. Output and inOut field values from the task are accessible via `$vars.<nodeId>.output.<fieldId>` at runtime (fields are embedded in the output object, not exposed as separate node variables).
 
-Output-direction and inOut-direction fields are also materialized as workflow-level globals in `variables.globals` with `direction: "inout"` — these are accessible directly as `$vars.<field.variable>` without a node prefix (e.g. `variable: "decision"` → `$vars.decision`).
+> **Scripts must always use `$vars.<nodeId>.output.<fieldId>`.** The `field.variable` property declares a name for the global alias — do NOT use that name directly in scripts. `$vars.decision` (global alias) and `$vars.<nodeId>.output.decision` (field ID access) are different paths and only the field ID path is reliable in script nodes. See Critical Rule 10 in SKILL.md.
+
+---
+
+## Canonical Field Shape (reference)
+
+This is the exact JSON a correctly authored QuickForm `fields[]` entry looks like for each direction. Use this as ground truth when writing or reviewing HITL nodes.
+
+```json
+{
+  "fields": [
+    {
+      "id": "invoiceid",
+      "type": "number",
+      "label": "Invoice ID",
+      "direction": "input",
+      "binding": "vars.fetchInvoice1.output.invoiceId"
+    },
+    {
+      "id": "vendorname",
+      "type": "string",
+      "label": "Vendor Name",
+      "direction": "input",
+      "binding": "vars.fetchInvoice1.output.vendorName"
+    },
+    {
+      "id": "approveddate",
+      "type": "date",
+      "label": "Approved Date",
+      "direction": "output",
+      "variable": "vars.approvedDate"
+    },
+    {
+      "id": "approved",
+      "type": "boolean",
+      "label": "Approved",
+      "direction": "output",
+      "variable": "vars.approved"
+    }
+  ],
+  "outcomes": [
+    {
+      "id": "submit",
+      "name": "Submit",
+      "type": "string",
+      "action": "Continue",
+      "isPrimary": true
+    }
+  ]
+}
+```
+
+**Key rules this sample encodes:**
+- `type`: always a JS/JSON type — `string`, `number`, `boolean`, `date`, or `file`. Never `"text"`.
+- `variable`: always `"vars.<name>"` — the `vars.` prefix is required.
+- `binding`: input/inOut fields only; raw path (`vars.<nodeId>.output.<field>`), no `=js:$` prefix.
+- Output/inOut fields have `variable`; input fields do not.
 
 ---
 
@@ -293,9 +348,9 @@ The agent translates the user's business description into the `fields[]` and `ou
 |---|---|
 | field `id` | lowercase label, spaces→`-`, strip non-alphanumeric. `"Invoice ID"` → `"invoiceid"`, `"Due Date"` → `"due-date"` |
 | `direction` | `inputs[]` items → `"input"`, `outputs[]` → `"output"`, `inOuts[]` → `"inOut"` |
-| field `type` | `"string"` → `"text"`, `"number"` → `"number"`, `"boolean"` → `"boolean"`, `"date"` → `"date"` |
+| field `type` | Use the JS/JSON type: `string`, `number`, `boolean`, `date`, or `file` |
 | `binding` | **Input / inOut fields only.** Format: `"vars.<nodeId>.output.<field>"` for node outputs; `"vars.<globalId>"` for flow globals. **No `=js:$` prefix** — HITL binding is a raw path, not an expression. |
-| `variable` | **Output / inOut fields only** — absent on input fields. Format: `"<name>"` (**no** `vars.` prefix — just the variable name). Defaults to the camelCase of the field `id` if not specified. |
+| `variable` | **Output / inOut fields only** — absent on input fields. Format: `"vars.<name>"` (always include the `vars.` prefix). Defaults to `"vars.<camelCase id>"` if not specified. |
 | `required` | omit if false; set `true` for mandatory outputs |
 | `outcomes[0]` | `isPrimary: true`, `action: "Continue"` |
 | `outcomes[1+]` | `isPrimary: false`, `action: "End"` |
@@ -307,7 +362,7 @@ Business description: *"Reviewer sees invoice ID and amount, clicks Approve or R
 
 ```json
 "fields": [
-  { "id": "invoiceid", "label": "Invoice ID", "type": "text",   "direction": "input", "binding": "vars.fetchData1.output.invoiceId" },
+  { "id": "invoiceid", "label": "Invoice ID", "type": "string",   "direction": "input", "binding": "vars.fetchData1.output.invoiceId" },
   { "id": "amount",    "label": "Amount",     "type": "number", "direction": "input", "binding": "vars.fetchData1.output.amount" }
 ],
 "outcomes": [
@@ -322,8 +377,8 @@ Business description: *"Human sees the AI-drafted email, can edit it, then click
 
 ```json
 "fields": [
-  { "id": "recipient",  "label": "Recipient",  "type": "text", "direction": "input", "binding": "vars.draft1.output.recipient" },
-  { "id": "emailbody",  "label": "Email Body", "type": "text", "direction": "inOut", "binding": "vars.draft1.output.body", "variable": "emailBody" }
+  { "id": "recipient",  "label": "Recipient",  "type": "string", "direction": "input", "binding": "vars.draft1.output.recipient" },
+  { "id": "emailbody",  "label": "Email Body", "type": "string", "direction": "inOut", "binding": "vars.draft1.output.body", "variable": "vars.emailBody" }
 ],
 "outcomes": [
   { "id": "send",    "name": "Send",    "type": "string", "isPrimary": true,  "action": "Continue" },
@@ -337,9 +392,9 @@ Business description: *"Agent couldn't extract vendor name or cost center. Human
 
 ```json
 "fields": [
-  { "id": "rawextract",  "label": "Raw Extract",  "type": "text", "direction": "input",  "binding": "vars.extract1.output.rawText" },
-  { "id": "vendorname",  "label": "Vendor Name",  "type": "text", "direction": "output", "variable": "vendorName",  "required": true },
-  { "id": "costcenter",  "label": "Cost Center",  "type": "text", "direction": "output", "variable": "costCenter", "required": true }
+  { "id": "rawextract",  "label": "Raw Extract",  "type": "string", "direction": "input",  "binding": "vars.extract1.output.rawText" },
+  { "id": "vendorname",  "label": "Vendor Name",  "type": "string", "direction": "output", "variable": "vars.vendorName",  "required": true },
+  { "id": "costcenter",  "label": "Cost Center",  "type": "string", "direction": "output", "variable": "vars.costCenter", "required": true }
 ],
 "outcomes": [
   { "id": "submit", "name": "Submit", "type": "string", "isPrimary": true, "action": "Continue" }
@@ -352,9 +407,9 @@ Business description: *"If agent confidence is low, escalate. Human sees reasoni
 
 ```json
 "fields": [
-  { "id": "reasoning",       "label": "Agent Reasoning",  "type": "text",   "direction": "input",  "binding": "vars.classify1.output.reasoning" },
+  { "id": "reasoning",       "label": "Agent Reasoning",  "type": "string",   "direction": "input",  "binding": "vars.classify1.output.reasoning" },
   { "id": "confidencescore", "label": "Confidence Score", "type": "number", "direction": "input",  "binding": "vars.classify1.output.score" },
-  { "id": "notes",           "label": "Notes",            "type": "text",   "direction": "output", "variable": "notes" }
+  { "id": "notes",           "label": "Notes",            "type": "string",   "direction": "output", "variable": "vars.notes" }
 ],
 "outcomes": [
   { "id": "retry",    "name": "Retry",    "type": "string", "isPrimary": true,  "action": "Continue" },
@@ -376,17 +431,20 @@ After the HITL node, downstream nodes can reference:
 | `$vars.<nodeId>.output` | object | All `output` and `inOut` field values keyed by **field `id`** |
 | `$vars.<nodeId>.output.<fieldId>` | varies | Individual field value using the field's `id` (e.g. `$vars.invoiceReview1.output.decision`) |
 | `$vars.<nodeId>.status` | string | Selected outcome name (e.g. `"Approve"`, `"Reject"`) |
-| `$vars.<globalId>` | varies | Workflow-global variable for output/inOut fields — accessible without node prefix. The `globalId` equals `field.variable` directly (e.g. `variable: "notes"` → `$vars.notes`) |
+| `$vars.<globalId>` | varies | Workflow-global variable for output/inOut fields. `globalId` is `field.variable` with `vars.` stripped (e.g. `variable: "vars.notes"` → `$vars.notes`). **Do not use this path in scripts — use `$vars.<nodeId>.output.<fieldId>` instead.** |
 
-> **`fieldId` not `variable`**: The output object properties are keyed by the field's `id` (e.g. `"decision"`), not by the `variable` property. The `variable` property (`"approvalResult"`) creates a separate workflow-global variable (`$vars.approvalResult`) — it does not change the key used in the output object. If a field has `"id": "dec1"` and `"variable": "approvalResult"`, access it via the object as `$vars.nodeId.output.dec1`, or directly as `$vars.approvalResult`.
+> **`fieldId` not `variable`**: The output object properties are keyed by the field's `id` (e.g. `"decision"`), not by the `variable` property. The `variable` property (`"approvalResult"`) creates a separate workflow-global variable (`$vars.approvalResult`) — it does not change the key used in the output object. If a field has `"id": "dec1"` and `"variable": "vars.approvalResult"`, access it via the object as `$vars.nodeId.output.dec1`, or directly as `$vars.approvalResult`.
 >
-> **Common mistake:** A field with `"id": "approved"` and `"variable": "legalApproval"` must be read as `$vars.<nodeId>.output.approved` — **not** `$vars.<nodeId>.output.legalApproval`. Using the `variable` name as the key produces `undefined` at runtime; `flow validate` does not catch it.
+> **Common mistake:** A field with `"id": "approved"` and `"variable": "vars.legalApproval"` must be read as `$vars.<nodeId>.output.approved` — **not** `$vars.<nodeId>.output.legalApproval`. Using the `variable` name as the key produces `undefined` at runtime; `flow validate` does not catch it.
 
-**In a downstream script node:**
+**In a downstream script node** — always access inline using `$vars.<nodeId>.output.<fieldId>`, not by destructuring:
 ```javascript
-const output = $vars.invoiceReview1.output;
-// Access by field ID, not variable name
+// Correct — field ID inline access
+const vendorName = $vars.invoiceReview1.output.vendorName;
+const costCenter = $vars.invoiceReview1.output.costCenter;
 if ($vars.invoiceReview1.status === "approve") {
-  await updateSystem(output.vendorName, output.costCenter);
+  await updateSystem(vendorName, costCenter);
 }
+// Wrong — do NOT destructure first:
+// const output = $vars.invoiceReview1.output;  // then output.vendorName misses the node path
 ```