@uipath/skills 1.204.0 → 1.204.1

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

@@ -0,0 +1,403 @@
+# Loop Node — Implementation
+
+## Node Type
+
+`core.logic.loop`
+
+## Registry Validation
+
+```bash
+uip maestro flow registry get core.logic.loop --output json
+```
+
+Confirm the handles, required input `collection`, and the `outputDefinition` keys. Set the node instance `typeVersion` to the `version` field from this response — do not hardcode it.
+
+The loop is a **container** node, so its handles split across two boundaries:
+
+| Boundary | Handle | Direction | Purpose |
+| --- | --- | --- | --- |
+| outer | `input` | target | Entry from upstream |
+| outer | `success` | source | Exit after all iterations complete |
+| outer | `error` | source | Error path (when `errorHandlingEnabled`) |
+| inner | `start` | source | Into the loop body (first body node) |
+| inner | `continue` | target | Return from last body node |
+| inner | `break` | target | Early exit (when `breakEnabled`) |
+
+> There is no `output` port and no `loopBack` port. `output` is an output **variable** (`$vars.<loopId>.output`), not a handle. Wiring either name is a hard `flow validate` error — `Edge references undeclared source handle "output" on node "<loopId>" … rewire to one of: success, error, start`.
+
+## JSON Structure
+
+### Loop node
+
+```json
+{
+  "id": "loop1",
+  "type": "core.logic.loop",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Loop over items" },
+  "inputs": {
+    "collection": "=js:$vars.fetchData.output.body.items",
+    "parallel": false
+  }
+}
+```
+
+> **Collection source shape depends on the node type.** Connector `list` activities return the bare array — `"collection": "=js:$vars.searchIssuesByJql1.output"`, NOT `.output.issues` / `.output.items`. HTTP nodes differ — envelope preserved: `.output.body.<key>` as above. See [connector/impl.md — Connector output shape](../connector/impl.md).
+
+Set `"parallel": true` to execute all iterations concurrently.
+
+### Loop body nodes — `parentId` required
+
+Every node inside the loop body **must** have `"parentId"` set to the loop node's ID. Without this, the runtime does not know the node is part of the loop and variableUpdates will not fire per-iteration.
+
+```json
+{
+  "id": "processItem",
+  "type": "core.action.script",
+  "typeVersion": "1.0",
+  "display": { "label": "Process item" },
+  "inputs": {
+    "script": "return $vars.product * $vars.loop1.currentItem"
+  },
+  "parentId": "loop1"
+}
+```
+
+> **Critical:** If you omit `parentId`, the node executes outside the loop context. State variables will not update across iterations and loop outputs like `currentItem` will be inaccessible.
+
+## 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` and `parentId`.
+
+### CLI carve-out nodes inside a loop
+
+When adding a CLI carve-out node (connector, connector trigger, or managed HTTP) inside a loop, pass `--parent` to set `parentId` automatically:
+
+```bash
+uip maestro flow node add <FLOW_PATH> core.action.http.v2 --label "Fetch data" --parent <LOOP_ID> --output json
+uip maestro flow node add <FLOW_PATH> <CONNECTOR_NODE_TYPE> --label "Get record" --parent <LOOP_ID> --output json
+```
+
+`--parent` validates the parent node exists and sets `parentId` on the new node. For non-carve-out node types (script, end, etc.), set `"parentId"` directly in the JSON — see the examples above.
+
+## Wiring
+
+Loop nodes have a specific wiring pattern — four edges:
+
+| Edge | Source | Source port | Target | Target port |
+| --- | --- | --- | --- | --- |
+| Enter the loop | upstream node | that node's own output port (`output` on a manual trigger, `success` on an action node) | `<loopId>` | `input` |
+| Into the body | `<loopId>` | `start` | first body node | `input` |
+| Back from the body | last body node | `success` | `<loopId>` | `continue` |
+| Exit the loop | `<loopId>` | `success` | downstream node | `input` |
+
+See [editing-operations.md](../../editing-operations.md) for edge add procedures.
+
+## Accessing Loop Variables Inside Body
+
+Inside the loop body, access the current item via `$vars.<loopId>.currentItem`:
+
+```javascript
+// In a Script node inside the loop body (parentId must be set to the loop node)
+const item = $vars.loop1.currentItem;
+const iteration = $vars.loop1.currentIteration;
+return { processed: item.name.toUpperCase(), position: iteration };
+```
+
+| Variable | Description |
+| --- | --- |
+| `$vars.<loopId>.currentItem` | The item being processed in this iteration |
+| `$vars.<loopId>.currentIteration` | 1-based iteration number |
+| `$vars.<loopId>.collection` | The full collection being iterated |
+
+> **Do not use `iterator.currentItem`.** The correct access pattern is `$vars.<loopId>.currentItem` where `<loopId>` is the loop node's `id` (e.g., `$vars.loop1.currentItem`).
+
+> **There is no `currentIndex`.** The registry's `outputDefinition` for `core.logic.loop` exposes `currentIteration`, and it starts at 1 — not 0. Nothing rejects the wrong name: a `variables.nodes` entry bound to `outputId: "currentIndex"` passes `flow validate`, because bindings are not checked against the node's declared outputs. Confirm the output names with `uip maestro flow registry get core.logic.loop --output json`.
+
+### Required node variables for loop outputs
+
+For `$vars.<loopId>.currentItem` etc. to resolve, you must add corresponding entries to `variables.nodes`:
+
+```json
+{
+  "variables": {
+    "nodes": [
+      {
+        "id": "loop1.currentItem",
+        "type": "any",
+        "description": "The current item being iterated in the loop",
+        "binding": { "nodeId": "loop1", "outputId": "currentItem" }
+      },
+      {
+        "id": "loop1.currentIteration",
+        "type": "number",
+        "description": "The current iteration number (1-based)",
+        "binding": { "nodeId": "loop1", "outputId": "currentIteration" }
+      },
+      {
+        "id": "loop1.collection",
+        "type": "array",
+        "description": "The collection being iterated over",
+        "binding": { "nodeId": "loop1", "outputId": "collection" }
+      },
+      {
+        "id": "loop1.output",
+        "type": "array",
+        "description": "Aggregated results from all loop iterations",
+        "binding": { "nodeId": "loop1", "outputId": "output" }
+      }
+    ]
+  }
+}
+```
+
+## Aggregated loop output (`$vars.<loopId>.output`)
+
+After the loop completes, `$vars.<loopId>.output` is an array with **one entry per iteration**. Each entry is **keyed by body node id**, with that node's outputs nested underneath — it is NOT the body node's bare return value.
+
+For a loop `multiplyNumbers` over `[13, 15, 17]` whose body node `multiplyCurrent` is a Script returning `{ number: <n> }`:
+
+```json
+[
+  { "multiplyCurrent": { "output": { "number": 13 } } },
+  { "multiplyCurrent": { "output": { "number": 15 } } },
+  { "multiplyCurrent": { "output": { "number": 17 } } }
+]
+```
+
+So a downstream Script reads a per-iteration value as `item.<bodyNodeId>.output.<field>`:
+
+```javascript
+// CORRECT
+return { product: $vars.multiplyNumbers.output.reduce((p, item) => p * item.multiplyCurrent.output.number, 1) };
+
+// WRONG — item.number is undefined; 1 * undefined === NaN
+return { product: $vars.multiplyNumbers.output.reduce((p, item) => p * item.number, 1) };
+```
+
+With multiple body nodes, every node that ran in that iteration appears as a sibling key (`{ "fetchData1": { "output": … }, "processItem1": { "output": … } }`), alongside `<bodyNodeId>.error`.
+
+> **`flow validate` cannot catch this.** The wrong accessor is valid JS over an `any`-typed array — it validates clean and silently produces `NaN`/`undefined` at runtime. Confirm the shape with one `uip maestro flow debug` run before wiring downstream consumers.
+
+## State Accumulation with variableUpdates
+
+To accumulate state across loop iterations (counters, running totals), use an `inout` variable with a `variableUpdate` on the body node:
+
+```json
+{
+  "variables": {
+    "globals": [
+      {
+        "id": "runningTotal",
+        "direction": "inout",
+        "type": "number",
+        "defaultValue": 0
+      }
+    ],
+    "variableUpdates": {
+      "bodyNode": [
+        {
+          "variableId": "runningTotal",
+          "expression": {
+            "type": "jsExpression",
+            "expression": "$vars.bodyNode.output",
+            "fieldType": "number"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+The variableUpdate fires after each iteration, so the `inout` variable carries the accumulated value into the next iteration.
+
+> **`expression` is an object, not a `=js:` string.** `{ "type": "jsExpression", "expression": "<bare JS, no =js: prefix>", "fieldType": "<target variable's type>" }`. The legacy string form fails `flow validate` with `[MIGRATION] Workflow migration failed at 1.9→1.10 … Offending field(s): variables.variableUpdates.<nodeId>.0.expression` and `"Retry": "RetryWillNotFix"`. Write it with `Edit` — there is no CLI command for variable updates. See [shared/variables-and-expressions.md § Variable Updates](../../../shared/variables-and-expressions.md#variable-updates-variableupdates).
+
+> **Critical:** The variableUpdate expression **cannot** access loop iteration variables like `$vars.<loopId>.currentItem`. These are only available inside the body node's script. The variableUpdate must reference the body node's output (e.g., `$vars.bodyNode.output`). If you need to compute using `currentItem`, do the computation in the script and reference the script's output in the variableUpdate.
+
+## Complete Example — Loop with State Accumulation
+
+A flow that iterates over a collection, accumulates a result in an `inout` variable via a Script body node, and outputs the final value.
+
+```json
+{
+  "nodes": [
+    {
+      "id": "start",
+      "type": "core.trigger.manual",
+      "typeVersion": "1.0",
+      "display": { "label": "Manual trigger" },
+      "inputs": { "entryPointId": "..." }
+    },
+    {
+      "id": "loop1",
+      "type": "core.logic.loop",
+      "typeVersion": "<DEFINITION_VERSION>",
+      "display": { "label": "Loop" },
+      "inputs": { "collection": "=js:$vars.inputItems", "parallel": false }
+    },
+    {
+      "id": "bodyScript",
+      "type": "core.action.script",
+      "typeVersion": "<DEFINITION_VERSION>",
+      "display": { "label": "Process item" },
+      "inputs": {
+        "script": "return $vars.accumulator + $vars.loop1.currentItem;"
+      },
+      "parentId": "loop1"
+    },
+    {
+      "id": "end1",
+      "type": "core.control.end",
+      "typeVersion": "1.0",
+      "display": { "label": "End" },
+      "inputs": {},
+      "outputs": {
+        "result": { "source": "=js:$vars.accumulator" }
+      }
+    }
+  ],
+  "edges": [
+    { "id": "e1", "sourceNodeId": "start", "sourcePort": "output", "targetNodeId": "loop1", "targetPort": "input" },
+    { "id": "e2", "sourceNodeId": "loop1", "sourcePort": "start", "targetNodeId": "bodyScript", "targetPort": "input" },
+    { "id": "e3", "sourceNodeId": "bodyScript", "sourcePort": "success", "targetNodeId": "loop1", "targetPort": "continue" },
+    { "id": "e4", "sourceNodeId": "loop1", "sourcePort": "success", "targetNodeId": "end1", "targetPort": "input" }
+  ],
+  "variables": {
+    "globals": [
+      { "id": "inputItems", "direction": "in", "type": "array", "defaultValue": [], "triggerNodeId": "start" },
+      { "id": "accumulator", "direction": "inout", "type": "number", "defaultValue": 0 },
+      { "id": "result", "direction": "out", "type": "number" }
+    ],
+    "nodes": [
+      { "id": "loop1.currentItem", "type": "any", "binding": { "nodeId": "loop1", "outputId": "currentItem" } },
+      { "id": "loop1.currentIteration", "type": "number", "binding": { "nodeId": "loop1", "outputId": "currentIteration" } },
+      { "id": "loop1.collection", "type": "array", "binding": { "nodeId": "loop1", "outputId": "collection" } },
+      { "id": "loop1.output", "type": "array", "binding": { "nodeId": "loop1", "outputId": "output" } },
+      { "id": "bodyScript.output", "type": "any", "binding": { "nodeId": "bodyScript", "outputId": "output" } },
+      { "id": "bodyScript.error", "type": "object", "binding": { "nodeId": "bodyScript", "outputId": "error" } }
+    ],
+    "variableUpdates": {
+      "bodyScript": [
+        {
+          "variableId": "accumulator",
+          "expression": {
+            "type": "jsExpression",
+            "expression": "$vars.bodyScript.output",
+            "fieldType": "number"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+Key points in this pattern:
+- `bodyScript` has `"parentId": "loop1"` — places it inside the loop
+- Script accesses `$vars.loop1.currentItem` for the current iteration value
+- `variableUpdate` on `bodyScript` writes the script's return value back to `accumulator`, using the object `expression` form with `fieldType` matching `accumulator`'s declared `number` type
+- `accumulator` is `inout` so it persists across iterations
+- End node maps the final accumulated value to the `out` variable — also map `accumulator` itself, or `flow validate` warns `MISSING_OUTPUT_MAPPING` for the unmapped `inout` global
+- Body edges use the loop's inner handles — `start` out, `continue` back — not `output`/`loopBack`
+
+> **Prefer this pattern over post-processing `$vars.loop1.output`** when you need a running total. If you do consume the aggregate array instead, read each entry as `item.<bodyNodeId>.output.<field>` — see [Aggregated loop output](#aggregated-loop-output-varsloopidoutput).
+
+## Complete Example — Multi-Node Loop Body (HTTP + Script)
+
+Loop over items, fetch data per-iteration via HTTP, process with a script. Both body nodes have `parentId`.
+
+```json
+{
+  "nodes": [
+    {
+      "id": "start",
+      "type": "core.trigger.manual",
+      "typeVersion": "1.0",
+      "display": { "label": "Manual trigger" },
+      "inputs": { "entryPointId": "..." }
+    },
+    {
+      "id": "loop1",
+      "type": "core.logic.loop",
+      "typeVersion": "<DEFINITION_VERSION>",
+      "display": { "label": "For each item" },
+      "inputs": {
+        "collection": "=js:[{ name: 'A', id: 1 }, { name: 'B', id: 2 }]",
+        "parallel": false
+      }
+    },
+    {
+      "id": "fetchData1",
+      "type": "core.action.http.v2",
+      "typeVersion": "<DEFINITION_VERSION>",
+      "display": { "label": "Fetch data" },
+      "inputs": { "branches": [], "timeout": "PT15M", "retryCount": 0, "detail": {} },
+      "parentId": "loop1"
+    },
+    {
+      "id": "processItem1",
+      "type": "core.action.script",
+      "typeVersion": "<DEFINITION_VERSION>",
+      "display": { "label": "Process item" },
+      "inputs": {
+        "script": "return { name: $vars.loop1.currentItem.name, value: $vars.fetchData1.output.body.result };"
+      },
+      "parentId": "loop1"
+    },
+    {
+      "id": "end1",
+      "type": "core.control.end",
+      "typeVersion": "1.0",
+      "display": { "label": "End" },
+      "inputs": {},
+      "outputs": { "results": { "source": "=js:$vars.loop1.output" } }
+    }
+  ],
+  "edges": [
+    { "id": "e1", "sourceNodeId": "start", "sourcePort": "output", "targetNodeId": "loop1", "targetPort": "input" },
+    { "id": "e2", "sourceNodeId": "loop1", "sourcePort": "start", "targetNodeId": "fetchData1", "targetPort": "input" },
+    { "id": "e3", "sourceNodeId": "fetchData1", "sourcePort": "default", "targetNodeId": "processItem1", "targetPort": "input" },
+    { "id": "e4", "sourceNodeId": "processItem1", "sourcePort": "success", "targetNodeId": "loop1", "targetPort": "continue" },
+    { "id": "e5", "sourceNodeId": "loop1", "sourcePort": "success", "targetNodeId": "end1", "targetPort": "input" }
+  ],
+  "variables": {
+    "globals": [
+      { "id": "results", "direction": "out", "type": "array" }
+    ],
+    "nodes": [
+      { "id": "loop1.currentItem", "type": "any", "binding": { "nodeId": "loop1", "outputId": "currentItem" } },
+      { "id": "loop1.currentIteration", "type": "number", "binding": { "nodeId": "loop1", "outputId": "currentIteration" } },
+      { "id": "loop1.collection", "type": "array", "binding": { "nodeId": "loop1", "outputId": "collection" } },
+      { "id": "loop1.output", "type": "array", "binding": { "nodeId": "loop1", "outputId": "output" } },
+      { "id": "fetchData1.output", "type": "object", "binding": { "nodeId": "fetchData1", "outputId": "output" } },
+      { "id": "fetchData1.error", "type": "object", "binding": { "nodeId": "fetchData1", "outputId": "error" } },
+      { "id": "processItem1.output", "type": "any", "binding": { "nodeId": "processItem1", "outputId": "output" } },
+      { "id": "processItem1.error", "type": "object", "binding": { "nodeId": "processItem1", "outputId": "error" } }
+    ]
+  }
+}
+```
+
+- Both `fetchData1` and `processItem1` have `"parentId": "loop1"` — omitting it on either causes null outputs at runtime while validation passes
+- HTTP body uses `start`/`default` ports; script returns via `success`/`continue`
+- `detail` on HTTP node is abbreviated — populate via `uip maestro flow node configure`
+- `results` receives the aggregate array verbatim, so each entry looks like `{ "fetchData1": { "output": … }, "processItem1": { "output": … } }` — both body nodes as sibling keys. Flatten it in a Script node after the loop if the consumer expects bare values. See [Aggregated loop output](#aggregated-loop-output-varsloopidoutput).
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Collection is empty or null | Expression evaluates to null/undefined | Check `collection` expression and upstream output |
+| `$vars.loop1.currentItem` is undefined | Missing node variable binding or missing `parentId` | Add `loop1.currentItem` to `variables.nodes` and set `parentId` on body nodes |
+| `$vars.loop1.currentIndex` is undefined | The output is named `currentIteration` (1-based); there is no `currentIndex`, and a binding to it still validates | Use `$vars.<loopId>.currentIteration` and subtract 1 if you need a 0-based index |
+| `flow validate` fails: `[MIGRATION] … 1.9→1.10 … Offending field(s): variables.variableUpdates.<nodeId>.0.expression` | `variableUpdates[].expression` written as a legacy `=js:` string | Rewrite with `Edit` as `{ "type": "jsExpression", "expression": "<bare JS>", "fieldType": "<target variable type>" }` |
+| `flow validate` fails: `[variables.variableUpdates.<nodeId>[0].expression] Invalid input` | The expression object is malformed — missing one of the three keys, carrying an extra key, or an unknown `type` | Use exactly `type` + `expression` + `fieldType`; the object is strict |
+| `flow validate` fails: `Edge references undeclared source handle "output"` / `target handle "loopBack"` | Loop body wired to ports that do not exist | Use the inner handles: `start` out of the loop, `continue` back into it |
+| State variable not updating across iterations | Body node missing `parentId` | Add `"parentId": "<loopId>"` to every node inside the loop body |
+| State variable becomes `NaN` | variableUpdate expression uses `$vars.<loopId>.currentItem` | Loop variables are not available in variableUpdate expressions. Do the computation in the script and reference `$vars.<bodyNodeId>.output` in the variableUpdate |
+| Downstream value is `NaN`/`undefined` after reducing `$vars.<loopId>.output` | Entries are keyed by body node id, not the body's bare return value | Read `item.<bodyNodeId>.output.<field>`, not `item.<field>` — see [Aggregated loop output](#aggregated-loop-output-varsloopidoutput) |
+| Infinite loop | Edges wired incorrectly | Ensure only the body's `continue` edge creates the cycle, not arbitrary edges |
+| No output after loop | Missing `success` edge | Wire the `success` port to the next downstream node |
+| Per-item step runs once, after the last iteration | Step wired off the outer `success` port instead of inside the body | Set `"parentId": "<loopId>"` on the step and splice it into the body just before the edge into `continue` (empty body: `start` → step → `continue`). Wire `success` to the step's former downstream node |

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

@@ -0,0 +1,60 @@
+# Loop Node — Planning
+
+## Node Type
+
+`core.logic.loop`
+
+## When to Use
+
+Use a Loop node to iterate over a collection of items. Supports sequential and parallel execution.
+
+### Selection Heuristics
+
+| Situation | Use Loop? |
+| --- | --- |
+| Process each item in an array | Yes |
+| Run the same operation on multiple inputs concurrently | Yes (with `parallel: true`) |
+| Simple data transformation on a collection | No — use [Transform](../transform/planning.md) |
+| Distribute work items to robots | No — use [Queue](../queue/planning.md) |
+
+## Ports
+
+The loop is a container node, so its handles split across an outer and an inner boundary.
+
+| Boundary | Input Port(s) | Output Port(s) |
+| --- | --- | --- |
+| outer | `input` | `success`, `error` |
+| inner | `continue`, `break` | `start` |
+
+- `start` — feeds the first node inside the loop body
+- `continue` — receives the edge returning from the last node inside the loop body
+- `break` — early exit from inside the body (only when `breakEnabled`)
+- `success` — fires after all iterations complete
+- `error` — implicit error port shared with all action nodes; fires when the loop or an iteration throws. See [Implicit error port on action nodes](../../../shared/file-format.md#implicit-error-port-on-action-nodes).
+
+> Aggregated results are an output **variable** (`$vars.<loopId>.output`), not a port.
+
+## Key Inputs
+
+| Input | Required | Description |
+| --- | --- | --- |
+| `collection` | Yes | Expression pointing to an array (e.g., `$vars.fetchData.output.body.items`) |
+| `parallel` | No | `true` to execute all iterations concurrently (default: sequential) |
+
+## Loop Variables (available inside loop body only)
+
+- `$vars.<loopId>.currentItem` — the item being processed in this iteration
+- `$vars.<loopId>.currentIteration` — 1-based iteration number (there is no `currentIndex`)
+- `$vars.<loopId>.collection` — the full collection
+
+Where `<loopId>` is the loop node's `id` (e.g., `$vars.loop1.currentItem`).
+
+After the loop, `$vars.<loopId>.output` holds one entry per iteration, each keyed by body node id — plan a flattening step if a downstream consumer needs bare values.
+
+## Wiring Rules
+
+- The loop body starts from the loop node's inner `start` port
+- The last node in the loop body connects back to the loop's inner `continue` port
+- After all iterations, execution continues once from the outer `success` port. Per-item steps go in the body, never after `success`
+- Do not create cycles except through the `continue` handle
+- **Every node inside the loop body must have `"parentId": "<loopId>"`** — without this, variableUpdates will not fire per-iteration and loop variables will be inaccessible

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

@@ -0,0 +1,43 @@
+# Merge Node — Implementation
+
+## Node Type
+
+`core.logic.merge`
+
+## Registry Validation
+
+Run:
+
+```bash
+uip maestro flow registry get core.logic.merge --output json
+```
+
+Confirm that input port `input` accepts multiple connections and output port `output` exists. Set the node instance `typeVersion` to the response's `version` field; do not hardcode it.
+
+## JSON Structure
+
+```json
+{
+  "id": "joinBranches",
+  "type": "core.logic.merge",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Join Branches" },
+  "inputs": {}
+}
+```
+
+## Adding, Editing, and Wiring
+
+For add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the JSON structure above for node-specific `inputs`.
+
+- `input` accepts multiple incoming edges, one per parallel branch. All branches must reach the merge before execution continues.
+- `output` has one outgoing edge to the next downstream node.
+
+See [editing-operations.md](../../editing-operations.md) for edge-add procedures.
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Merge never completes | One parallel branch has no path to the merge node | Ensure all forked branches reach the merge |
+| Unexpected execution order | Branches are assumed to complete in order | Merge waits for all branches; do not depend on arrival order |

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

@@ -0,0 +1,24 @@
+# Merge Node — Planning
+
+## Node Type
+
+`core.logic.merge`
+
+## Use
+
+Use a Merge node to synchronize two or more parallel branches before continuing. It waits for all incoming paths to complete.
+
+- Use it when parallel branches must rejoin or after one node forks into multiple downstream branches.
+- Do not use it for sequential pipelines; wire nodes directly.
+- Do not use it to join the `true`/`false` branches of one Decision (or the cases of one Switch); wire both ports straight into the next node, which accepts several incoming edges. A Merge waits for ALL inputs and a Decision emits exactly one, so the run would hang forever; `flow validate` refuses this shape.
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` (accepts multiple connections) | `output` |
+
+## Wiring Rules
+
+- Connect each parallel branch's terminal node to the Merge node's `input` port; multiple incoming edges may use the same port.
+- Execution continues from `output` only after all incoming paths complete.

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

@@ -0,0 +1,82 @@
+# Queue Node — Implementation
+
+## Node Types
+
+| Node Type | Description |
+| --- | --- |
+| `core.action.queue.create` | Fire-and-forget queue item creation |
+| `core.action.queue.create-and-wait` | Create queue item and wait for result |
+
+## Registry Validation
+
+```bash
+uip maestro flow registry get core.action.queue.create --output json
+uip maestro flow registry get core.action.queue.create-and-wait --output json
+```
+
+Confirm: input port `input`, output port `success`. Set each node instance's `typeVersion` to the `version` field from the matching response — do not hardcode it.
+
+## JSON Structure
+
+```json
+{
+  "id": "enqueueItem",
+  "type": "core.action.queue.create",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Enqueue Invoice" },
+  "inputs": {
+    "queue": "InvoiceProcessingQueue",
+    "itemData": "=js:JSON.stringify({ orderId: $vars.order.id, amount: $vars.order.total })",
+    "priority": "High",
+    "reference": "=js:$vars.order.id",
+    "deferDate": "2026-04-01T10:00:00Z",
+    "dueDate": "2026-04-07T17:00:00Z"
+  },
+  "outputs": {
+    "error": {
+      "type": "object",
+      "description": "Error information if the queue operation fails",
+      "source": "=Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+## 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`.
+
+## Wait Variant
+
+`core.action.queue.create-and-wait` blocks execution until the queue item is processed by a robot. The processed result is available via `$vars.{nodeId}.output`.
+
+```json
+{
+  "id": "processAndWait",
+  "type": "core.action.queue.create-and-wait",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Process and Wait" },
+  "inputs": {
+    "queue": "InvoiceProcessingQueue",
+    "itemData": "=js:JSON.stringify({ invoiceId: $vars.invoiceId })"
+  },
+  "outputs": {
+    "error": {
+      "type": "object",
+      "description": "Error information if the queue operation fails",
+      "source": "=Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Queue not found | Queue name doesn't match Orchestrator | Verify queue name in Orchestrator |
+| `itemData` invalid | Not valid JSON | Ensure `JSON.stringify()` wraps the data object |
+| Queue item stuck | No robot available to process | Check Orchestrator robot allocation |
+| Wait timeout | Robot took too long to process item | Check queue processing time and robot availability |

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

@@ -0,0 +1,44 @@
+# Queue Node — Planning
+
+## Node Types
+
+| Node Type | Description |
+| --- | --- |
+| `core.action.queue.create` | Create a queue item and continue immediately (fire-and-forget) |
+| `core.action.queue.create-and-wait` | Create a queue item and wait for processing to complete |
+
+## When to Use
+
+Use Queue nodes to distribute work items to robots via Orchestrator queues.
+
+### Selection Heuristics
+
+| Situation | Use Queue? |
+| --- | --- |
+| Distribute work to robots — fire-and-forget | Yes (`create`) |
+| Distribute work and need the result before continuing | Yes (`create-and-wait`) |
+| Direct process invocation with known inputs | No — use [RPA Workflow](../rpa/planning.md) |
+| Iterate over items sequentially in the flow | No — use [Loop](../loop/planning.md) |
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` | `success` |
+
+## Key Inputs
+
+| Input | Required | Description |
+| --- | --- | --- |
+| `queue` | Yes | Orchestrator queue name |
+| `itemData` | No | JSON payload for the queue item |
+| `priority` | No | `Low`, `Normal` (default), `High` |
+| `reference` | No | Tracking reference string |
+| `deferDate` | No | ISO 8601 — earliest time to process |
+| `dueDate` | No | ISO 8601 — deadline for processing |
+
+## Common Pattern — Fan-Out to Queue
+
+```text
+Manual Trigger -> Script (split batch) -> Loop -> Queue Create (per item) -> End Loop -> End
+```