@uipath/skills 1.204.0 → 1.204.1

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

@@ -0,0 +1,117 @@
+# RPA Node — Implementation
+
+RPA nodes invoke RPA processes using `uipath.core.rpa-workflow.{key}`.
+
+## Discovery
+
+**Published (tenant registry):**
+
+```bash
+uip maestro flow registry pull --force
+uip maestro flow registry search "uipath.core.rpa-workflow" --output json
+```
+
+Run `registry pull --force` first. Search the **node-type token** `uipath.core.rpa-workflow`, not the process name. Select the published workflow by `resourceKey` / folder path and description. `registry search` matches the Orchestrator **release name**, often unrelated to the process name or folder; match the folder path inside `resourceKey`, not a name keyword.
+
+Treat an empty result as non-authoritative until you confirm that you searched the node-type token, refreshed the registry, and scanned returned folder paths and descriptions rather than only display names. Do not use the local-scaffold fallback after only a name-search miss.
+
+**In-solution (local, no login required):** Run these inside the flow project directory to discover sibling RPA projects in the same `.uipx` solution:
+
+```bash
+uip maestro flow registry list --local --output json
+uip maestro flow registry get "<node-type>" --local --output json
+```
+
+## Registry Validation
+
+```bash
+uip maestro flow registry get "uipath.core.rpa-workflow.{key}" --output json
+uip maestro flow registry get "uipath.core.rpa-workflow.{key}" --local --output json
+```
+
+Confirm:
+
+- Input port: `input`
+- Output port: `output`
+- `model.serviceType`: `Orchestrator.StartJob`
+- `model.bindings.resourceSubType`: `Process`
+- `model.bindings.resourceKey`: the `<FolderPath>.<ResourceName>` string used to scope binding resolution
+- `inputDefinition`: may contain typed input fields; check `properties`
+- `outputDefinition`: always `error` (`source: "=Error"`); processes with output arguments also declare `output` (`source: "=this"`). Do not author `output` on the instance: the converter injects `=this`, and `$vars.{nodeId}.output` carries the process return value.
+
+## Adding and Editing
+
+For step-by-step add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the JSON structure below for node-specific `inputs`.
+
+### Node instance (`nodes[]`)
+
+The instance carries per-instance data (`inputs`, `outputs`, `display`); BPMN type, serviceType, version, and binding/context templates come from `definitions[]`.
+
+```json
+{
+  "id": "processInvoices",
+  "type": "uipath.core.rpa-workflow.invoice-process-abc123",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Process Invoices" },
+  "inputs": {
+    "documentPath": "=js:$vars.fileLocation",
+    "batchSize": 50
+  },
+  "outputs": {
+    "error": {
+      "type": "object",
+      "description": "Error information if the RPA process fails",
+      "source": "=Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+Declare `error` only; `output` is derived. If authored, the converter copies its `source` verbatim, so values such as `"=result.response"` resolve to null at runtime even when `flow validate` passes. See [file-format.md § Node outputs](../../../shared/file-format.md#node-outputs).
+
+### Top-level `bindings[]`
+
+Add one entry per `(resourceKey, propertyAttribute)` pair as a sibling of `nodes`/`edges`/`definitions`. Share entries across instances referencing the same RPA process; do not duplicate them.
+
+```json
+"bindings": [
+  {
+    "id": "bProcessInvoicesName",
+    "name": "name",
+    "type": "string",
+    "resource": "process",
+    "resourceKey": "Finance/Automation.Invoice Processor",
+    "default": "Invoice Processor",
+    "propertyAttribute": "name",
+    "resourceSubType": "Process"
+  },
+  {
+    "id": "bProcessInvoicesFolderPath",
+    "name": "folderPath",
+    "type": "string",
+    "resource": "process",
+    "resourceKey": "Finance/Automation.Invoice Processor",
+    "default": "Finance/Automation",
+    "propertyAttribute": "folderPath",
+    "resourceSubType": "Process"
+  }
+]
+```
+
+For resolution mechanics and why these entries are required, see [file-format.md — Bindings](../../../shared/file-format.md#bindings--orchestrator-resource-bindings-top-level-bindings).
+
+## If the RPA Process Is Genuinely Not Published
+
+Use this path only after completing the empty-result confirmation in [Discovery](#discovery) and only when no sibling RPA project provides the process. Tell the user to create the RPA project inside the same solution using `uipath-rpa`. After it exists as a sibling in the `.uipx` solution, run `uip maestro flow registry list --local --output json` and wire it directly; publishing is not required.
+
+A freshly scaffolded RPA project has no implementation. The wired flow may pass `flow validate` but fault during debug or execution (`Robot.JobUnexpectedExitCode`) until `uipath-rpa` fills in the workflow. A validated flow is not necessarily a working one.
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Node type not found in registry | Searched by process name (matches release name, not folder), process not published, or registry stale | Search the `uipath.core.rpa-workflow` token and match on folder path — not a name keyword. If in same solution: run `registry list --local`. Otherwise: run `uip login` then `uip maestro flow registry pull --force` |
+| Input schema mismatch | Inputs don't match `inputDefinition` | Run `registry get` and check required inputs in `inputDefinition.properties` |
+| Process execution failed | Underlying RPA process errored | Check `$vars.{nodeId}.error` for details |
+| Mock placeholder still in flow | Process not yet replaced | Follow the mock replacement workflow above |

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

@@ -0,0 +1,61 @@
+# RPA Node — Planning
+
+RPA nodes invoke RPA processes (XAML or coded C# workflows) from within a flow. Published processes appear in the registry after `uip login` + `uip maestro flow registry pull`. **In-solution** (unpublished) processes in sibling projects are discovered via `--local` — no login or publish required.
+
+## Node Type Pattern
+
+`uipath.core.rpa-workflow.{key}`
+
+## When to Use
+
+Use an RPA node when the flow needs desktop/browser automation via a published RPA process.
+
+### Selection Heuristics
+
+| Situation | Use RPA? |
+| --- | --- |
+| Desktop/browser automation via a published RPA process | Yes |
+| Target system has a REST API | No — use [Connector](../connector/planning.md) or [HTTP](../http/planning.md) |
+| RPA process in the same solution but not yet published | Yes — use `--local` discovery (see below) |
+| RPA process does not exist yet | Create it in the same solution with `uipath-rpa`, then use `--local` discovery |
+| Need AI reasoning, not desktop automation | No — use [Agent](../agent/planning.md) |
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` | `output`, `error` |
+
+The `error` port is the implicit error port shared with all action nodes — see [Implicit error port on action nodes](../../../shared/file-format.md#implicit-error-port-on-action-nodes).
+
+## Output Variables
+
+- `$vars.{nodeId}.output` — the RPA process return value (structure depends on the process)
+- `$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.rpa-workflow" --output json
+```
+
+Requires `uip login`. Only published processes from your tenant appear.
+
+**In-solution (local, no login required):**
+
+```bash
+uip maestro flow registry list --local --output json
+uip maestro flow registry get "<node-type>" --local --output json
+```
+
+Run from inside the flow project directory. Discovers sibling RPA projects in the same `.uipx` solution.
+
+## Planning Annotation
+
+In the architectural plan:
+
+- If the process exists: note as `resource: <name> (rpa-workflow)`
+- If it does not exist: note as `[CREATE NEW] <description>` with skill `uipath-rpa`

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

@@ -0,0 +1,56 @@
+# Scheduled Trigger — Implementation
+
+## Node Type
+
+`core.trigger.scheduled`
+
+## Registry Validation
+
+Run `uip maestro flow registry get core.trigger.scheduled --output json`.
+
+Confirm that the definition has no input port, output port `output`, and the required input `timerValue`. Set the node instance `typeVersion` to the response `version` field; do not hardcode it because this node has advanced past `1.0`.
+
+## JSON Structure
+
+### Repeating Interval
+
+```json
+{
+  "id": "scheduledStart",
+  "type": "core.trigger.scheduled",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Every Hour" },
+  "inputs": {
+    "entryPointId": "<uuid>",
+    "timerType": "timeCycle",
+    "timerValue": "R/PT1H"
+  },
+  "outputs": {
+    "output": {
+      "type": "object",
+      "description": "The return value of the trigger.",
+      "source": "=result.response",
+      "var": "output"
+    }
+  }
+}
+```
+
+### Cron Expression
+
+Same node with a clock-aligned `timerValue`: `"timerValue": "0 0 9 ? * MON-FRI"` (weekdays at 09:00).
+
+Do not add BPMN type (`bpmn:StartEvent`) or event definition (`bpmn:TimerEventDefinition`) to the instance; they come from the `core.trigger.scheduled` entry in `definitions[]`.
+
+## Replacing Manual Trigger with Scheduled
+
+Use [Edit/Write: Replace manual trigger with scheduled trigger](../../editing-operations-json.md#replace-manual-trigger-with-scheduled-trigger) for the step-by-step procedure, supplying the node-specific `inputs` above.
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Cycle expression must be either an ISO 8601 repeating interval or a Quartz cron expression | Malformed `timerValue` | Use `R/P[duration]` (e.g. `R/PT1H`) or a 6-7 field cron (e.g. `0 0 9 ? * MON-FRI`) |
+| `[REQUIRED_FIELD] "timerValue" is required` | Cycle expression written to `timerPreset` | `core.trigger.scheduled` has no `timerPreset` input — put the cycle expression in `timerValue` |
+| BPMN timer event not emitted | `core.trigger.scheduled` definition wrong or missing | Re-copy from `uip maestro flow registry get core.trigger.scheduled --output json` — the definition carries `model.eventDefinition: "bpmn:TimerEventDefinition"` |
+| Two triggers in flow | Both manual and scheduled triggers exist | Remove one — flows must have exactly one trigger |

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

@@ -0,0 +1,93 @@
+# Scheduled Trigger — Planning
+
+## Node Type
+
+`core.trigger.scheduled`
+
+## When to Use
+
+Use a Scheduled Trigger to start the flow on a recurring schedule instead of manual invocation.
+
+### Selection Heuristics
+
+| Situation | Use Scheduled Trigger? |
+| --- | --- |
+| Flow runs on a recurring schedule (hourly, daily, weekly) | Yes |
+| Flow is started on demand by a user or API call | No — use `core.trigger.manual` |
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| — (none) | `output` |
+
+## Key Inputs
+
+| Input | Required | Description |
+| --- | --- | --- |
+| `timerValue` | Yes | The cycle expression — ISO 8601 repeating interval or Quartz cron |
+| `timerType` | Yes | Always `timeCycle` for scheduled triggers |
+
+Set both. The definition's `required` array names only `timerValue`, so a flow
+without `timerType` passes `validate`, but `model.values` maps
+`timerType -> inputs.timerType` to build the BPMN timer event. Omitting it
+leaves the event without its cycle type.
+
+The definition the registry serves (1.2) has no `timerPreset` input. Every
+frequency, common or not, goes in `timerValue`.
+
+## Cycle Expression Formats
+
+### ISO 8601 Repeating Interval
+
+`R/P[duration]` — `R` means repeat indefinitely, followed by duration.
+
+| Value | Frequency |
+| --- | --- |
+| `R/PT5M` | Every 5 minutes |
+| `R/PT15M` | Every 15 minutes |
+| `R/PT30M` | Every 30 minutes |
+| `R/PT1H` | Every hour |
+| `R/PT6H` | Every 6 hours |
+| `R/PT12H` | Every 12 hours |
+| `R/P1D` | Daily |
+| `R/P1W` | Weekly |
+
+Any other interval uses the same form: `R/PT10M` (every 10 min), `R/P2D` (every 2 days).
+
+Exactly one duration unit, non-zero, and in range: `Y` 1-9999, `M` 1-12, `W` 1-52, `D` 1-31, `H` 1-23, `T…M` 1-59, `S` 1-59.
+
+| Rejected | Why | Instead |
+| --- | --- | --- |
+| `R/PT24H` | out of range | `R/P1D` |
+| `R/PT0H` | zero, never fires | any non-zero interval |
+| `R/PT2H30M` | two units | not expressible as an interval — see below |
+
+An interval may be anchored to a start instant: `R/2026-05-14T09:00:00Z/P1W`.
+
+### Quartz Cron
+
+Six or seven whitespace-separated fields. Use it for a clock-aligned schedule
+an interval cannot express: a fixed time of day, a set of weekdays, a day of
+the month.
+
+Examples: `0 0 9 ? * MON-FRI` (weekdays at 09:00), `0 0 2 1 * ? *` (02:00 on the 1st)
+
+Put `?` in day-of-month or day-of-week, never a value in both.
+
+`validate` checks cron field shape only, never semantics: `0 0 12 * * *` (no
+`?`) and even `ABC ABC ABC ABC ABC ABC` pass it. Read the expression back field
+by field before shipping.
+
+Cron does not extend the set of *periods* available. An arbitrary period is
+expressible in neither form: the interval takes one in-range unit and no single
+cron expression carries a sub-hour period across the hour boundary. Every 2.5
+hours and every 90 minutes have no representation here — pick a period one of
+the two forms accepts (`R/PT2H`, `R/PT3H`) and say so, rather than shipping a
+cron that silently fires on a different cadence.
+
+## Key Rules
+
+- Every flow must have exactly one trigger node
+- Replaces `core.trigger.manual` — do not have both
+- The trigger is always the first node in the topology

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

@@ -0,0 +1,98 @@
+# Script Node — Implementation
+
+## Node Type
+
+`core.action.script`
+
+## Registry validation
+
+```bash
+uip maestro flow registry get core.action.script --output json
+```
+
+Confirm: input port `input`, output port `success`, required input `script` (string, non-empty). See [Action Node Structure — Registry validation](../../../shared/action-nodes.md#registry-validation) for the shared pattern.
+
+## JSON structure
+
+Follow the [Action Node Structure — Standard JSON skeleton](../../../shared/action-nodes.md#standard-json-skeleton). The script-specific input is a single `script` string:
+
+```json
+{
+  "inputs": {
+    "script": "const items = $vars.fetchData.output.body.items;\nconst total = items.reduce((sum, i) => sum + i.amount, 0);\nreturn { total, count: items.length };"
+  }
+}
+```
+
+## Adding and editing
+
+See [Action Node Structure — Adding and editing procedures](../../../shared/action-nodes.md#adding-and-editing-procedures). The script node uses the standard input port `input` and output port `success`; no plugin-specific wiring.
+
+## Script rules
+
+1. **Top-level body — no `function main()` wrapper.** Node runs the `script` text directly (as a function body); a wrapper is never called → `output` null. Read workflow variables via `$vars.<variableId>` and upstream node outputs via `$vars.<nodeId>.output`; end with top-level `return {…}`. Not a coded Function: no `main`, no injected args.
+   - Correct: `const n = $vars.ixp1.output.field; return { n };`
+   - Wrong: `function main({ ixp1 }) { … }`
+2. **Must `return` an object** — `return { key: value }`, not a bare scalar. The return value becomes `$vars.<nodeId>.output`.
+3. **`$vars` is a global** — use it directly: `return { upper: $vars.customerName.toUpperCase() }`
+4. **JavaScript ES2020 (Jint engine)** — see [variables-and-expressions.md](../../../shared/variables-and-expressions.md) for supported features and Jint constraints.
+5. **No `console.log`** — `console` is not available. Use `return { debug: value }` to inspect values.
+6. **No external calls** — use the HTTP node or a connector node for API calls.
+7. **30-second timeout** — long-running computations will be killed.
+8. **Never name a variable `aggregate`** — reserved host global. On any `Identifier 'X' has already been declared`, rename `X`.
+9. **Never default an upstream output to `{}`.** `const ctx = $vars.x.output || {}` widens the type to `T | {}`, so every `ctx.field` read warns `Property 'field' does not exist on type '{}'`. Read the output directly; if the upstream node may not have run, chain `?.` to the leaf and `??` only a scalar or array leaf, never an intermediate object: `const items = $vars.x?.output?.body?.items ?? [];`
+
+## Common patterns
+
+### Transform and return
+
+```javascript
+const items = $vars.fetchData.output.body.items;
+const filtered = items.filter(i => i.status === "active");
+return { items: filtered, count: filtered.length };
+```
+
+### Build a payload for a downstream node
+
+```javascript
+return {
+  subject: `Order ${$vars.orderId} - Confirmation`,
+  body: `Your order of ${$vars.orderTotal} has been processed.`,
+  recipient: $vars.customerEmail
+};
+```
+
+### Error check from upstream
+
+```javascript
+const error = $vars.httpCall.error;
+if (error) {
+  return { hasError: true, message: error.message };
+}
+return { hasError: false, data: $vars.httpCall.output.body };
+```
+
+### Reading a file-typed variable
+
+A `file` variable (bound via `uip maestro flow debug --attachment <id>=<path>`) hydrates as an **object**, not a string. Read the uploaded file's name from `.FullName`:
+
+```javascript
+const doc = $vars.start.output.inputDoc; // file variable → object
+return { fileName: doc.FullName };        // .FullName, not .name/.fileName
+```
+
+Property access is **case-sensitive** — these casings resolve: `.FullName`, `.ID` (uppercase, not `.Id`), `.MimeType`, `.Metadata.size` (nested, lowercase `size`). `.name` / `.fileName` do not exist. See [variables-and-expressions.md — Runtime shape of a `file` variable](../../../shared/variables-and-expressions.md#file-input).
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Script did not return a value | Missing `return` statement | Add `return { ... }` |
+| `output` is `null` but script has a `return` | `return` is inside an uncalled `function main(){}` wrapper | Remove wrapper; code + `return` at top level (rule 1) |
+| Return value is not an object | Returned a scalar (`return 42`) | Wrap in object: `return { value: 42 }` |
+| `$vars.nodeId` is undefined | Upstream node not connected or wrong ID | Check edges and node IDs |
+| Timeout after 30s | Script too expensive | Simplify logic or split into multiple scripts |
+| `console is not defined` | Used `console.log()` | Remove — use `return { debug: val }` instead |
+| `fetch is not defined` | Tried to make HTTP call | Use an HTTP node or connector node instead |
+| `[300501] Error invoking script task` with `Unexpected token` | Malformed JavaScript — `flow validate` does not parse script bodies, so syntax errors surface only at runtime | Check with `node -e "new Function(<script>)"` before validate |
+| `Identifier 'X' has already been declared` | `X` collides with a runtime-injected global (known: `aggregate`) | Rename `X` (e.g. `agg`) |

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

@@ -0,0 +1,42 @@
+# Script Node — Planning
+
+## Node Type
+
+`core.action.script`
+
+## When to Use
+
+Use a Script node for custom logic, data transformation, computation, or formatting that does not require an external call.
+
+### Selection Heuristics
+
+| Situation | Use Script? |
+| --- | --- |
+| Custom logic, string manipulation, computation | Yes |
+| Standard map/filter/group-by on a collection | No — use [Transform](../transform/planning.md) |
+| Ambiguous input that needs reasoning or judgment | No — use [Agent](../agent/planning.md) |
+| Calling an external API | No — use [HTTP](../http/planning.md) or [Connector Activity](../connector/planning.md) |
+| Natural language generation | No — use [Agent](../agent/planning.md) |
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` | `success`, `error` |
+
+- `success` — primary output; fires when the script returns normally.
+- `error` — implicit error port shared with all action nodes. Fires on uncaught script exceptions, returned non-object values, or timeout. See [Implicit error port on action nodes](../../../shared/file-format.md#implicit-error-port-on-action-nodes).
+
+## Output Variables
+
+- `$vars.{nodeId}.output` — the return value (must be an object)
+- `$vars.{nodeId}.error` — error object if the script fails
+
+## Key Constraints
+
+- JavaScript only (ES2020 via Jint) — not TypeScript, not Python
+- Must `return` an object: `return { key: value }` (not a bare scalar)
+- No browser/DOM APIs (`fetch`, `document`, `window`, `setTimeout` are unavailable)
+- Cannot make HTTP calls or access external systems
+- 30-second execution timeout
+- `$vars` is available as a global

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

@@ -0,0 +1,164 @@
+# Subflow Node — Implementation
+
+## Node Type and Registry Validation
+
+`core.subflow`
+
+Run:
+
+```bash
+uip maestro flow registry get core.subflow --output json
+```
+
+Confirm input port `input` and output ports `output` and `error`. Set the node instance `typeVersion` to the response's `version` field; do not hardcode it.
+
+## Parent Node JSON
+
+```json
+{
+  "id": "subflow1",
+  "type": "core.subflow",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Add Numbers", "icon": "layers" },
+  "inputs": { "a": 2, "b": 3 },
+  "outputs": {
+    "error": {
+      "type": "object",
+      "description": "Error information if the subflow fails",
+      "source": "=Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+Declare `error` only; `output` is derived. Do not author `output`: the converter copies its `source` verbatim, so `"=result.response"` resolves to null at runtime although `flow validate` passes. See [file-format.md § Node outputs](../../../shared/file-format.md#node-outputs).
+
+## Subflow Definition
+
+Store definitions in a top-level `subflows` object keyed by the parent node ID. Each definition contains `nodes`, `edges`, `variables`, and `layout`:
+
+```json
+{
+  "subflows": {
+    "subflow1": {
+      "nodes": [
+        {
+          "id": "subflow1Start",
+          "type": "core.trigger.manual",
+          "typeVersion": "1.0",
+          "display": { "label": "Start" },
+          "inputs": { "entryPointId": "<unique-uuid>", "isDefaultEntryPoint": true },
+          "outputs": {
+            "output": {
+              "type": "object",
+              "description": "Data passed when manually triggering the workflow.",
+              "source": "null",
+              "var": "output"
+            }
+          }
+        },
+        {
+          "id": "script1",
+          "type": "core.action.script",
+          "typeVersion": "1.0",
+          "display": { "label": "Add Numbers" },
+          "inputs": { "script": "return { result: $vars.subflow1Start.output.a + $vars.subflow1Start.output.b };" },
+          "outputs": {
+            "output": { "type": "object", "description": "The return value of the script", "source": "=result.response", "var": "output" },
+            "error": { "type": "object", "description": "Error information if the script fails", "source": "=Error", "var": "error" }
+          }
+        },
+        {
+          "id": "subflow1End",
+          "type": "core.control.end",
+          "typeVersion": "1.0",
+          "display": { "label": "End" },
+          "inputs": {},
+          "outputs": { "result": { "source": "=js:$vars.script1.output.result" } }
+        }
+      ],
+      "edges": [
+        { "id": "sf-e1", "sourceNodeId": "subflow1Start", "sourcePort": "output", "targetNodeId": "script1", "targetPort": "input" },
+        { "id": "sf-e2", "sourceNodeId": "script1", "sourcePort": "success", "targetNodeId": "subflow1End", "targetPort": "input" }
+      ],
+      "variables": {
+        "globals": [
+          { "id": "a", "direction": "in", "type": "number", "defaultValue": 0, "triggerNodeId": "subflow1Start" },
+          { "id": "b", "direction": "in", "type": "number", "defaultValue": 0, "triggerNodeId": "subflow1Start" },
+          { "id": "result", "direction": "out", "type": "number", "defaultValue": 0 }
+        ],
+        "nodes": []
+      },
+      "layout": {
+        "nodes": {
+          "subflow1Start": { "position": { "x": 200, "y": 144 }, "size": { "width": 96, "height": 96 }, "collapsed": false },
+          "script1": { "position": { "x": 400, "y": 144 }, "size": { "width": 96, "height": 96 }, "collapsed": false },
+          "subflow1End": { "position": { "x": 600, "y": 144 }, "size": { "width": 96, "height": 96 }, "collapsed": false }
+        }
+      }
+    }
+  }
+}
+```
+
+## Passing a Flow Input Into the Subflow
+
+Set `triggerNodeId` on the parent's `in` variable when forwarding trigger input. Run `uip maestro flow validate`; do not treat **Valid** as proof that this is configured. Without `triggerNodeId`, `flow debug` shows an empty trigger output, forwards `null`, and may fault in the subflow (for example, `Cannot read property 'split' of null`).
+
+```json
+{
+  "variables": {
+    "globals": [
+      { "id": "text", "direction": "in", "type": "string", "defaultValue": "", "triggerNodeId": "start" },
+      { "id": "reversedText", "direction": "out", "type": "string", "defaultValue": "" }
+    ]
+  },
+  "nodes": [
+    {
+      "id": "start",
+      "type": "core.trigger.manual",
+      "typeVersion": "1.0",
+      "inputs": { "entryPointId": "<uuid>", "isDefaultEntryPoint": true },
+      "outputs": { "output": { "type": "object", "description": "Data passed when manually triggering the process.", "source": "null", "var": "output" } }
+    },
+    {
+      "id": "reverseSubflow",
+      "type": "core.subflow",
+      "typeVersion": "<DEFINITION_VERSION>",
+      "inputs": { "text": "=js:$vars.start.output.text" }
+    }
+  ]
+}
+```
+
+Value flow is: caller input `text` → parent `start` through the parent's `triggerNodeId` → `$vars.start.output.text` → subflow input `text` → the subflow's `in` variable → `$vars.<subflowStart>.output.text`. Parent and subflow `in` variables are independent; set `triggerNodeId` for each.
+
+## Subflow Rules
+
+1. Every subflow must have its own Start node (`core.trigger.manual`) and End node (`core.control.end`).
+2. Subflow `variables.globals` with `direction: "in"` map to parent node `inputs`.
+3. Subflow `in` variables must set `triggerNodeId` to the subflow Start node ID, enabling `$vars.{startNodeId}.output.{varId}`.
+4. Subflow `variables.globals` with `direction: "out"` map to parent node outputs and are accessible as `$vars.{subflowNodeId}.output` in the parent.
+5. Parent-scope `$vars` are not visible inside the subflow; pass values explicitly through inputs.
+6. Define inline `outputs` on every subflow node: Start needs `outputs.output`; Script nodes need `outputs.output` and `outputs.error`.
+7. Subflows may be nested up to 3 levels.
+8. Each subflow has its own `nodes`, `edges`, `variables`, and `layout` sections — and only those four. There is no per-subflow `definitions` array: `core.subflow` and every node type used inside a subflow take their entry in the flow's single top-level `definitions[]`. A `definitions` array under `subflows.<id>` is ignored. `flow validate` reports the omission at ``[subflows[<id>].nodes[<nodeId>].type] Node type `<type>:<version>` has no matching definition``.
+9. Put subflow node positions in that subflow's `layout.nodes`, not the top-level `layout.nodes`; scopes are independent.
+10. When the parent forwards an external input, its `in` variable must also set `triggerNodeId` to the parent trigger node ID. `uip maestro flow validate` does not detect this omission; the value silently arrives `null`. See [Passing a Flow Input Into the Subflow](#passing-a-flow-input-into-the-subflow).
+
+## Creating a Subflow
+
+For the procedure, see [Edit/Write: Create a subflow](../../editing-operations-json.md#create-a-subflow). Use the structures above for node-specific fields.
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| `$vars.inputData` undefined inside subflow script | Missing `triggerNodeId` on a subflow `in` variable, or direct use of `$vars.{varId}` | Set `triggerNodeId: "{startNodeId}"` on each `in` variable and use `$vars.{startNodeId}.output.{varId}` |
+| Subflow script receives `null`, such as `Cannot read property 'split' of null` | Parent `in` variable lacks `triggerNodeId`, leaving parent trigger output empty | Set `triggerNodeId: "{parentStartNodeId}"` on the parent flow's `in` variable |
+| `$vars.parentNode` undefined inside subflow | Parent scope is inaccessible | Pass values through subflow `in` variables |
+| Subflow output is null | End node lacks output mapping | Map all `out` variables in the End node's `outputs` |
+| Script output is null | Script lacks inline `outputs` | Add `outputs.output` and `outputs.error` inline |
+| Missing Start/End node | Required trigger or end is absent | Add `core.trigger.manual` with `outputs` and `entryPointId`, plus `core.control.end` |
+| Nesting limit exceeded | More than 3 levels of nesting | Flatten the structure or use resource nodes for deeper composition |

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

@@ -0,0 +1,35 @@
+# Subflow Node — Planning
+
+## Node Type
+
+`core.subflow`
+
+## When to Use
+
+Use a Subflow node to group related steps into a drillable container with isolated variable scope. A subflow belongs to one node in one flow and cannot be called from anywhere else.
+
+### Selection Heuristics
+
+| Situation | Use Subflow? |
+| --- | --- |
+| Group related steps into a container | Yes |
+| Encapsulate logic with its own variable scope | Yes |
+| Simple sequential steps that don't need isolation | No — wire nodes directly |
+| Call a published flow as a subprocess | No — use [Flow](../flow/planning.md) |
+| Same logic needed in 2+ places or flows | No. Make it its own flow project in the solution and call it with [Flow](../flow/planning.md) |
+
+## Ports
+
+| Input Port | Output Port(s) |
+| --- | --- |
+| `input` | `output`, `error` |
+
+The `error` port is the implicit error port shared with all action nodes — see [Implicit error port on action nodes](../../../shared/file-format.md#implicit-error-port-on-action-nodes).
+
+## Key Properties
+
+- Subflows have their own `nodes`, `edges`, and `variables` stored in `subflows.{nodeId}`
+- Parent-scope `$vars` are **not** visible inside the subflow — pass values explicitly via inputs
+- Subflow inputs map to `direction: "in"` variables; outputs map to `direction: "out"` variables
+- Nesting supported up to 3 levels deep
+- Every subflow must have its own Start node (`core.trigger.manual`) and End node (`core.control.end`)