@uipath/skills 1.204.0 → 1.204.1

package/skills/uipath-maestro-flow/references/author/plugins/decision/impl.md

@@ -0,0 +1,83 @@
+# Decision Node — Implementation
+
+## Node Type
+
+`core.logic.decision`
+
+## Registry Validation
+
+```bash
+uip maestro flow registry get core.logic.decision --output json
+```
+
+Confirm: input port `input`, output ports `true` and `false`, required input `expression`. Set the node instance `typeVersion` to the `version` field from this response — do not hardcode it.
+
+## JSON Structure
+
+```json
+{
+  "id": "checkStatus",
+  "type": "core.logic.decision",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Check Status" },
+  "inputs": {
+    "expression": "$vars.fetchData.output.statusCode === 200"
+  }
+}
+```
+
+## Adding / Editing
+
+For step-by-step add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the JSON structure above for the node-specific `inputs`.
+
+## Expression Examples
+
+```javascript
+// Simple comparison
+$vars.fetchData.output.statusCode === 200
+
+// Boolean field
+$vars.processData.output.isValid
+
+// Compound condition
+$vars.httpCall.output.statusCode === 200 && $vars.httpCall.output.body.count > 0
+
+// String check
+$vars.classify.output.category === "urgent"
+
+// Null check
+$vars.lookupUser.output.user !== null
+```
+
+## Wiring
+
+Output ports: `true` and `false`. Both branches must be wired. See [editing-operations.md](../../editing-operations.md) for edge add procedures.
+
+## Outputs
+
+`registry get` shows a Decision declaring two outputs, `matchedCase` and `matchedCaseId`, and `flow format` writes them into `variables.nodes[]`. **Ignore both. Neither is ever assigned at runtime.**
+
+They are synthetic. The scope resolver suppresses a gateway's outputs for every reader except the gateway itself, and the flow→BPMN serializer emits no writer for them — a Decision compiles to a gateway whose branch choice lives on the outgoing sequence flows' `conditionExpression`, never in a variable. They hold real values only in the Studio Web canvas, which evaluates gateways client-side. Because the variable is *declared* but never assigned, a downstream read fails **silently**: `undefined` flows into the reader's own logic and yields a wrong result instead of a fault.
+
+| What you write | What happens |
+| --- | --- |
+| `$vars.<decisionId>.matchedCaseId` or `.matchedCase` | validate passes with `[EXPRESSION_DIAGNOSTIC] Property '<decisionId>' does not exist on type '{…}'`; reads `undefined` at runtime |
+| `$vars.<decisionId>.output.matchedCaseId` | validate **fails**: `node "<decisionId>" has no output named "output" — its outputs are: matchedCase, matchedCaseId` |
+
+> That second message then recommends `$vars.<decisionId>.matchedCaseId`. Take only half of it: drop the `.output.` segment **and** stop reading the gateway. The cross-reference check reads the registry's declared outputs and does not know the scope resolver suppresses them.
+
+To act on which branch ran, use one of:
+
+- **Recompute the condition** from a node upstream of the Decision, which is still in scope — `$vars.getWeather.output.tempF > 60` rather than the Decision's result. Cheapest when the condition's inputs are still reachable.
+- **Write an `inout` global on each branch** with [`variables.variableUpdates`](../../editing-operations-json.md#add-a-variable-update), then read `$vars.<globalId>` where the branches rejoin. Use this when the condition cannot be recomputed. Map the global on every End node or it raises `MISSING_OUTPUT_MAPPING`.
+
+This holds whether or not the branches rejoin, and applies identically to [Switch](../switch/impl.md#outputs).
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Expression does not evaluate to boolean | Expression returns non-boolean value | Ensure expression uses comparison operators (`===`, `>`, etc.) |
+| `$vars.nodeId` is undefined | Upstream node not connected or wrong ID | Check edges and node IDs |
+| `[400302] Error evaluating outgoing flow expression from gateway` | `expression` reads a node that runs *after* the Decision (typical after moving the Decision earlier in the flow) | Point `expression` at a node that still runs before the Decision (e.g. the HTTP node's `$vars.<node>.output…`), not at the node the branches lead to |
+| Only one branch wired | Missing true or false edge | Add the missing edge — both branches are required |

package/skills/uipath-maestro-flow/references/author/plugins/decision/planning.md

@@ -0,0 +1,38 @@
+# Decision Node — Planning
+
+## Node Type
+
+`core.logic.decision`
+
+## When to Use
+
+Use a Decision node for binary branching (if/else) based on a boolean condition.
+
+### Selection Heuristics
+
+| Situation | Use Decision? |
+| --- | --- |
+| Two-path branch based on a boolean condition | Yes |
+| Three or more paths | No — use [Switch](../switch/planning.md) |
+| Branch on HTTP response status codes | No — use [HTTP](../http/planning.md) built-in branches |
+| Branch requires reasoning on ambiguous input | No — use [Agent](../agent/planning.md) |
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` | `true`, `false` |
+
+## Key Inputs
+
+| Input | Required | Description |
+| --- | --- | --- |
+| `expression` | Yes | Boolean JavaScript expression (e.g., `$vars.fetchData.output.statusCode === 200`) |
+| `trueLabel` | No | Custom label for the true branch |
+| `falseLabel` | No | Custom label for the false branch |
+
+## Wiring Rules
+
+- Decision nodes produce exactly **two** outgoing edges: one from `true`, one from `false`
+- Both branches must lead to a downstream node (no dangling branches)
+- Each branch typically ends at its own End node or merges back into a shared path

package/skills/uipath-maestro-flow/references/author/plugins/delay/impl.md

@@ -0,0 +1,38 @@
+# Delay Node — Implementation
+
+## Node Type
+
+`core.logic.delay`
+
+## Registry Validation
+
+Run `uip maestro flow registry get core.logic.delay --output json`.
+
+Confirm input port `input`, output port `output`, and required inputs `timerType` and `timerPreset`. Set the node instance `typeVersion` to the response `version` field; do not hardcode it.
+
+## JSON Structure
+
+```json
+{
+  "id": "<id>",
+  "type": "core.logic.delay",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "<label>" },
+  "inputs": { "timerType": "<timerType>", "timerPreset": "<preset>" }
+}
+```
+
+- Duration preset: use `timerType: "timeDuration"` and `timerPreset: "<preset>"` (for example, `"PT15M"`).
+- Custom duration: use `timerPreset: "custom"` and add `timerValue` as an ISO 8601 duration (for example, `"P1DT5H30M"`).
+- Wait until a date: use `timerType: "timeDate"`, `timerPreset: "custom"`, and `timerDate` as an ISO 8601 datetime or `=js:` expression (for example, `"=js:$vars.scheduledDate"`).
+
+For step-by-step add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). BPMN type and event definition come from `definitions[]`.
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Invalid timer value | Malformed ISO 8601 string | Check format: `P[n]Y[n]M[n]W[n]DT[n]H[n]M[n]S` |
+| Missing `timerValue` | `timerPreset: "custom"` but no `timerValue` | Add `timerValue` with ISO 8601 duration |
+| Missing `timerDate` | `timerType: "timeDate"` but no `timerDate` | Add `timerDate` with ISO 8601 datetime or `=js:` expression |
+| BPMN timer event not emitted | Wrong `core.logic.delay` definition in `definitions[]` | Re-copy from `uip maestro flow registry get core.logic.delay --output json` — the definition carries `model.eventDefinition: "bpmn:TimerEventDefinition"` |

package/skills/uipath-maestro-flow/references/author/plugins/delay/planning.md

@@ -0,0 +1,53 @@
+# Delay Node — Planning
+
+## Node Type
+
+`core.logic.delay`
+
+## When to Use
+
+Use a Delay node to pause execution for a duration or until a specific date.
+
+### Selection Heuristics
+
+| Situation | Use Delay? |
+| --- | --- |
+| Fixed duration pause (wait 15 minutes, wait 1 day) | Yes |
+| Wait until a specific date/time | Yes |
+| Wait for external work to complete | No — use [Queue](../queue/planning.md) (`create-and-wait`) |
+| Wait for human input | No — use [HITL](../hitl/planning.md) |
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` | `output` |
+
+## Key Inputs
+
+| Input | Required | Description |
+| --- | --- | --- |
+| `timerType` | Yes | `timeDuration` or `timeDate` |
+| `timerPreset` | Yes | Preset value or `custom` |
+| `timerValue` | Conditional | Required when `timerPreset: "custom"` (ISO 8601 duration) |
+| `timerDate` | Conditional | Required when `timerType: "timeDate"` (ISO 8601 datetime or `=js:` expression) |
+
+## Duration Presets
+
+| Preset Value | Duration |
+| --- | --- |
+| `PT5M` | 5 minutes |
+| `PT15M` | 15 minutes |
+| `PT30M` | 30 minutes |
+| `PT1H` | 1 hour |
+| `PT6H` | 6 hours |
+| `PT12H` | 12 hours |
+| `P1D` | 1 day |
+| `P1W` | 1 week |
+| `custom` | Use `timerValue` for custom ISO 8601 duration |
+
+## ISO 8601 Duration Format
+
+`P[n]Y[n]M[n]W[n]DT[n]H[n]M[n]S`
+
+Examples: `PT30S` (30 seconds), `PT2H30M` (2.5 hours), `P3DT12H` (3 days 12 hours)

package/skills/uipath-maestro-flow/references/author/plugins/end/impl.md

@@ -0,0 +1,56 @@
+# End Node — Implementation
+
+## Node Type
+
+`core.control.end`
+
+## Registry Validation
+
+Run `uip maestro flow registry get core.control.end --output json`. Confirm input port `input` and no output ports. Set the node instance `typeVersion` to the response `version` field; do not hardcode it.
+
+## JSON Structure
+
+Without output variables:
+
+```json
+{
+  "id": "<END_NODE_ID>",
+  "type": "core.control.end",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "<LABEL>" },
+  "inputs": {}
+}
+```
+
+When the workflow declares `out` variables, map every one on every End node:
+
+```json
+{
+  "id": "<END_NODE_ID>",
+  "type": "core.control.end",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "<LABEL>" },
+  "inputs": {},
+  "outputs": {
+    "<VAR_ID>": {
+      "source": "=js:$vars.<UPSTREAM_NODE>.output.<FIELD>"
+    }
+  }
+}
+```
+
+Each `outputs` key must match a variable `id` in `variables.globals` with `direction: "out"`.
+
+## Adding / Editing
+
+For step-by-step add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the JSON structure above for node-specific `inputs` and `outputs`.
+
+Add output mappings with `Edit` against the `.flow` file; see [Edit/Write: Add output mapping](../../editing-operations-json.md#add-output-mapping-on-an-end-node).
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Missing output mapping | An `out` variable is not mapped on this End node | Add `outputs.{varId}.source` for every `out` variable |
+| Output expression unresolvable | The `$vars` reference points to an unreachable node | Ensure the node is upstream and connected via edges |
+| Runtime silent failure | A reachable End node lacks an output mapping | Check **all** End nodes, not just the primary path |

package/skills/uipath-maestro-flow/references/author/plugins/end/planning.md

@@ -0,0 +1,28 @@
+# End Node — Planning
+
+## Node Type
+
+`core.control.end`
+
+## When to Use
+
+Use an End node for graceful workflow completion. Each terminal path in the flow needs its own End node.
+
+### Selection Heuristics
+
+| Situation | Use End? |
+| --- | --- |
+| Normal completion of an execution path | Yes |
+| Fatal error — abort everything immediately | No — use [Terminate](../terminate/planning.md) |
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` | — (none) |
+
+## Key Rules
+
+- A flow can have multiple End nodes (one per terminal path)
+- Every `out` variable in `variables.globals` **must** be mapped on **every** reachable End node via `outputs`
+- End nodes only terminate their own path — other parallel branches continue

package/skills/uipath-maestro-flow/references/author/plugins/flow/impl.md

@@ -0,0 +1,107 @@
+# Flow Node — Implementation
+
+Flow nodes invoke other flows as subprocesses. Pattern: `uipath.core.flow.{key}`.
+
+## Discovery
+
+### Published (tenant registry)
+
+```bash
+uip maestro flow registry pull --force
+uip maestro flow registry search "uipath.core.flow" --output json
+```
+
+### In-solution (sibling projects)
+
+```bash
+uip maestro flow registry list --local --output json
+uip maestro flow registry get "<node-type>" --local --output json
+```
+
+## Registry Validation
+
+```bash
+# Published
+uip maestro flow registry get "uipath.core.flow.{key}" --output json
+
+# In-solution
+uip maestro flow registry get "uipath.core.flow.{key}" --local --output json
+```
+
+Confirm:
+
+- Input port: `input`
+- Output port: `output`
+- `model.serviceType` — `Orchestrator.StartAgenticProcess` (shared with agentic-process nodes; `resourceSubType: "Flow"` differentiates)
+- `model.bindings.resourceSubType` — `Flow`
+- `model.bindings.resourceKey` — the `<FolderPath>.<FlowName>` string used to scope binding resolution
+- `inputDefinition` — typically empty
+- `outputDefinition.error` — error schema
+
+## Adding / Editing
+
+For step-by-step add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the JSON structure below for the node-specific `inputs`.
+
+## JSON Structure
+
+### Node instance (inside `nodes[]`)
+
+The instance carries only per-instance data (`inputs`, `outputs`, `display`). BPMN type, serviceType, version, and binding/context templates come from the definition in `definitions[]`.
+
+```json
+{
+  "id": "validateData",
+  "type": "uipath.core.flow.629edef0-8ce8-428e-a922-3f8bf19ea682",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Validate Data" },
+  "inputs": {},
+  "outputs": {
+    "error": {
+      "type": "object",
+      "description": "Error information if the flow fails",
+      "source": "=Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+**Declare `error` only — `output` is derived.** Authoring it makes the converter copy your `source` verbatim; `"=result.response"` then resolves to null at runtime while `flow validate` passes. See [file-format.md § Node outputs](../../../shared/file-format.md#node-outputs).
+
+### Top-level `bindings[]` entries (sibling of `nodes`/`edges`/`definitions`)
+
+Add one entry per `(resourceKey, propertyAttribute)` pair. Share entries across node instances that reference the same flow — do NOT create duplicates.
+
+```json
+"bindings": [
+  {
+    "id": "bValidateDataName",
+    "name": "name",
+    "type": "string",
+    "resource": "process",
+    "resourceKey": "Shared.Validate Data Flow",
+    "default": "Validate Data Flow",
+    "propertyAttribute": "name",
+    "resourceSubType": "Flow"
+  },
+  {
+    "id": "bValidateDataFolderPath",
+    "name": "folderPath",
+    "type": "string",
+    "resource": "process",
+    "resourceKey": "Shared.Validate Data Flow",
+    "default": "Shared",
+    "propertyAttribute": "folderPath",
+    "resourceSubType": "Flow"
+  }
+]
+```
+
+> For the resolution mechanics and why these entries are required, see [file-format.md — Bindings](../../../shared/file-format.md#bindings--orchestrator-resource-bindings-top-level-bindings).
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Node type not found in registry | Flow not published or registry stale | Run `uip login` then `uip maestro flow registry pull --force`; for in-solution flows use `--local` |
+| Flow execution failed | Underlying flow errored | Check `$vars.{nodeId}.error` for details |

package/skills/uipath-maestro-flow/references/author/plugins/flow/planning.md

@@ -0,0 +1,58 @@
+# Flow Node — Planning
+
+Flow nodes invoke other flows as subprocesses from within a flow. Published flows appear in the registry after `uip login` + `uip maestro flow registry pull`. **In-solution** (unpublished) flows in sibling projects are discovered via `--local` — no login or publish required.
+
+## Node Type Pattern
+
+`uipath.core.flow.{key}`
+
+## When to Use
+
+Use a Flow node when you need to call another published flow as a subprocess.
+
+### Selection Heuristics
+
+| Situation | Use Flow? |
+| --- | --- |
+| Call another published flow as a subprocess | Yes |
+| Group related steps with isolated scope (within same project) | No — use [Subflow](../subflow/planning.md) |
+| Invoke a published orchestration process | No — use [Agentic Process](../agentic-process/planning.md) |
+| Flow not yet published but in the same solution | Yes — discover with `--local` (no login or publish needed) |
+| Flow does not exist yet | Create it in the same solution with `uipath-maestro-flow`, then use `--local` discovery |
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` | `output` |
+
+## Output Variables
+
+- `$vars.{nodeId}.error` — error details if execution fails (`code`, `message`, `detail`, `category`, `status`)
+
+## Discovery
+
+### Published (tenant registry)
+
+```bash
+uip maestro flow registry pull --force
+uip maestro flow registry search "uipath.core.flow" --output json
+```
+
+Requires `uip login`. Only published flows from your tenant appear.
+
+### In-solution (sibling projects)
+
+```bash
+uip maestro flow registry list --local --output json
+uip maestro flow registry get "<node-type>" --local --output json
+```
+
+No login or publish required. Discovers unpublished flows in sibling projects within the same solution.
+
+## Planning Annotation
+
+In the architectural plan:
+
+- If the flow exists: note as `resource: <name> (flow)`
+- If it does not exist: note as `[CREATE NEW] <description>` with skill `uipath-maestro-flow`

package/skills/uipath-maestro-flow/references/author/plugins/hitl/impl.md

@@ -0,0 +1,181 @@
+# HITL Node — Implementation
+
+Choose one checkpoint: an inline QuickForm or an existing deployed Action Center app.
+
+## Option 1 — `uipath.human-in-the-loop.quick-form` (Inline Schema — OOTB)
+
+Preferred: no registry pull, app publishing, or tenant dependency. Write the node directly into the `.flow` file as JSON.
+
+For schema design, node writing, JSON examples, and schema conversion rules, see [`uipath-human-in-the-loop` skill — hitl-node-quickform.md](../../../../../uipath-human-in-the-loop/references/hitl-node-quickform.md). Skills are self-contained: this cross-skill reference is for documentation context only — per Critical Rule 4, offer the handoff and let the user choose. This guide covers implementation-phase topology resolution only, not schema design or node writing.
+
+For add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). **Use `Edit` / `Write` for HITL node authoring.** Do not use the dedicated HITL CLI for this non-carve-out structural edit. Wire one output edge per outcome — port `outcome-<outcome.id>` for each entry in `inputs.schema.outcomes[]` — never a single shared port.
+
+### Quick reference
+
+```json
+{
+  "id": "hitlReview1",
+  "type": "uipath.human-in-the-loop.quick-form",
+  "typeVersion": "1.0",
+  "display": { "label": "Invoice Review" },
+  "inputs": {
+    "schema": {
+      "schemaId": "<uuid>",
+      "fields": [
+        { "id": "invoiceid", "label": "Invoice ID", "type": "text", "direction": "input", "binding": "vars.fetchInvoice.output.invoiceId" },
+        { "id": "amount", "label": "Amount", "type": "number", "direction": "input", "binding": "vars.fetchInvoice.output.amount" },
+        { "id": "decision", "label": "Decision", "type": "text", "direction": "output", "variable": "vars.decision" }
+      ],
+      "outcomes": [
+        { "id": "approve", "name": "Approve", "type": "string", "isPrimary": true, "action": "Continue" },
+        { "id": "reject", "name": "Reject", "type": "string", "isPrimary": false, "action": "End" }
+      ]
+    },
+    "recipient": { "channels": ["Email", "ActionCenter"], "connections": {}, "assignee": { "type": "group" } },
+    "priority": "Low"
+  },
+  "outputs": {
+    "output": {
+      "type": "object",
+      "description": "Task result data",
+      "source": "=result",
+      "var": "output",
+      "properties": {
+        "decision": { "type": "string" },
+        "Action": { "type": "string", "enum": ["Approve", "Reject"], "default": "Approve" }
+      }
+    },
+    "status": {
+      "type": "string",
+      "description": "Task completion status",
+      "source": "=result.Action",
+      "var": "status",
+      "enum": ["Approve", "Reject"],
+      "default": "Approve"
+    }
+  }
+}
+```
+
+Rules:
+- Input fields use `binding: "vars.<nodeId>.output.<field>"` (raw path; no `=js:$` prefix) and no `variable`.
+- Output fields use `variable: "vars.<globalName>"` (`vars.` required) and no `binding`.
+- InOut fields use both properties in those formats.
+- Use `schemaId` (not `id`) at schema level and generate a fresh UUID.
+- `priority` is `"Low"` | `"Medium"` | `"High"`, default `Low`. No `Critical` on this node, unlike an Action Center case task. Take the value from the request, not from the literal in either option's example: explicit high-urgency language — "urgent", "high priority", "critical", "ASAP", a named or breached SLA — selects `High`; reserve `Medium` for mild or unquantified urgency, `Low` when none is expressed. The value must land in the node; acknowledging the urgency in conversation is not enough.
+- `typeVersion` — always `"1.0"` for this node. **Do not run `registry get` to derive this value; do not use `"1.1"` or any other version.** The OOTB HITL node version is stable at `1.0`.
+- Do not include a `model` block on node instances; only the definition carries it.
+- `outputs` contains only `output` (with `properties` for output/inOut fields plus `Action`) and `status` (with outcome `enum`/`default`). Do not add per-field `custom: true` entries.
+- Ports: `input` (target) → one `outcome-<outcome.id>` port per outcome (source), derived from `inputs.schema.outcomes[].id` verbatim — never lowercase it, never hardcode a port name. Every outcome needs a non-empty string `id`; one without gets no handle at all and any edge drawn to it is a no-op. `outcome-completed` is the port for a zero-outcome node, or for a real outcome whose `id` is literally `completed` — it is not a reserved string, so it is never a shared exit standing in for several outcomes. Wire every outcome port — an unwired one blocks that branch indefinitely.
+- Outputs are `$vars.{nodeId}.output` (object keyed by field `id`), `$vars.{nodeId}.output.{fieldId}`, `$vars.{nodeId}.status` (selected outcome name), and `$vars.{globalId}` (workflow-global alias from `field.variable` with `vars.` stripped). **Do not use the alias in scripts; use `$vars.{nodeId}.output.{fieldId}`.**
+
+## Option 2 — App-Based HITL (`uipath.human-in-the-loop.coded-action-app`)
+
+Use an existing deployed Action Center app as the task form.
+
+### Discovery
+
+**Run:**
+
+```bash
+uip solution resources list --kind App --output json
+```
+
+Filter returned Action Center app types (`vB Action`, `workflow Action`, `Coded Action`, `JS Action`) by app name. **Run:**
+
+```bash
+uip solution resources get <key> --output json
+```
+
+If the CLI is unavailable, use:
+
+```
+GET {BASE_URL}/{ORG}/studio_/backend/api/resourcebuilder/solutions/{SOLUTION_ID}/resources/search
+  ?kind=app&pageSize=25&projectKey={PROJECT_KEY}&includeSolutionResources=true
+  &types=VB%20Action&types=Workflow%20Action&types=Coded%20Action&types=CodedAction&types=JS%20Action
+```
+
+For app search → retrieve-configuration → resource files → reference registration → debug overwrites, see **[hitl-node-apptask.md](../../../../../uipath-human-in-the-loop/references/hitl-node-apptask.md)**.
+
+### Quick reference
+
+```json
+{
+  "id": "invoiceReview1",
+  "type": "uipath.human-in-the-loop.coded-action-app",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Invoice Review" },
+  "inputs": {
+    "recipient": { "channels": ["ActionCenter"], "connections": {}, "assignee": { "type": "group" } },
+    "app": {
+      "displayName": "Invoice Approval",
+      "name": "Invoice Approval",
+      "key": "<app.key>",
+      "folderPath": "Shared",
+      "inputSchema": {
+        "type": "object",
+        "properties": { "<paramName>": { "type": "string" } }
+      },
+      "outputSchema": {
+        "type": "object",
+        "properties": { "<outputName>": { "type": "string" } }
+      }
+    },
+    "appInputBindings": {
+      "<inputParamName>": "=vars.<nodeId>.output.<field>",
+      "<inputParamName2>": "=metadata.InstanceId"
+    },
+    "priority": "Medium"
+  },
+  "outputs": {
+    "output": {
+      "type": "object",
+      "description": "Task result data",
+      "source": "=result",
+      "var": "output",
+      "properties": { "Action": { "type": "string", "enum": ["Submit"], "default": "Submit" } }
+    },
+    "status": {
+      "type": "string",
+      "description": "Task completion status",
+      "source": "=result.Action",
+      "var": "status",
+      "enum": ["Submit"],
+      "default": "Submit"
+    }
+  }
+}
+```
+
+Rules:
+- Fill `typeVersion` with the version returned by `uip maestro flow registry get <appKey>` for the specific deployed app. Unlike QuickForm, AppTask versions vary by app definition.
+- `inputs.app.inputSchema` and `outputSchema` are JSON Schema objects (`{ "type": "object", "properties": { ... } }`), not arrays.
+- `inputs.appInputBindings` maps names from `inputSchema.properties` to `"=vars.<path>"` expressions (with `=` and no `js:`). Without these bindings, input fields are blank.
+- `priority` follows Option 1's rule above — derived from the request, not the `"Medium"` literal in the example.
+- Do not add `inputs.schema` to this node — its outcomes come from the deployed app (`inputs.app`), not a schema block. Adding one flips the port from the static `completed` handle this node type actually uses to a schema-derived `outcome-<id>` handle, which does not match what the app produces.
+- Ports: `input` (target) → `completed` (source). Unlike QuickForm, this port stays static regardless of the app's own outcomes.
+
+### If the app does not exist
+
+Record `[CREATE NEW] <description>` in the node table and use `core.logic.mock` as a placeholder. The app is out of scope; use the `uipath-coded-apps` skill to build it.
+
+## Common pattern
+
+```text
+Manual Trigger -> RPA Process (extract) -> HITL (review, outcomes: Approve/Reject) ->
+  outcome-approve: Script (submit) -> End
+  outcome-reject: End
+```
+
+Branch directly off each outcome's own handle. Do not insert a Decision node after a HITL node to re-derive the branch from `$vars.{nodeId}.status` — the outcome handles already are the branch points.
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Node type not found in registry (Option 2) | App not published or registry stale | If in same solution: `uip maestro flow registry list --local`. Otherwise: `uip login` then `uip maestro flow registry pull --force` |
+| Task never completes | Human has not submitted the form | Check task assignment in Orchestrator |
+| Output missing expected fields | App form does not match expected schema | Verify app form fields match what the flow expects |
+| An outcome port unwired (Option 1) | Missing edge on one of the `outcome-<outcome.id>` handles | Wire every outcome's own port; an unwired outcome port blocks the flow indefinitely on that branch |
+| Wired `outcome-completed` as if it were a shared exit for several outcomes (Option 1) | Confused the zero-outcome placeholder for a real port | Check `inputs.schema.outcomes` — if any entry's `id` isn't literally `completed`, rewire to `outcome-<outcome.id>` per outcome instead |
+| Run never finishes; instance stays `Running` until the timeout, ports all wired | A HITL node sits in a flow nothing will attend — no assignee, or an unattended run (schedule, `flow debug`, eval) | Confirm a human will open the task. If the run is unattended, use a mechanism that completes on its own — see [planning.md](planning.md#when-to-select) |