@uipath/skills 1.201.0-preview.621 → 1.202.0-preview.635

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

@@ -0,0 +1,241 @@
+# Transform Node — Implementation
+
+## Node Types and Registry Validation
+
+Supported node types:
+
+- `core.action.transform` — generic; chains operations
+- `core.action.transform.filter` — filter only
+- `core.action.transform.map` — map only
+- `core.action.transform.group-by` — group-by only
+
+Run:
+
+```bash
+uip maestro flow registry get core.action.transform --output json
+uip maestro flow registry get core.action.transform.filter --output json
+uip maestro flow registry get core.action.transform.map --output json
+uip maestro flow registry get core.action.transform.group-by --output json
+```
+
+Confirm each definition has input port `input`, output ports `output` and `error`, and required inputs `collection` and `operations`. Set each instance's `typeVersion` to the matching response's `version`; do not hardcode it.
+
+For add, delete, and wiring procedures, see [editing-operations.md](../../editing-operations.md). Use the node-specific `inputs` and `model` structures below.
+
+Every transform uses this output schema:
+
+```json
+"outputs": {
+  "output": {
+    "type": "object",
+    "description": "The return value of the transform",
+    "source": "=result.response",
+    "var": "output"
+  },
+  "error": {
+    "type": "object",
+    "description": "Error information if the transform fails",
+    "source": "=Error",
+    "var": "error"
+  }
+}
+```
+
+## Collection Input and Output Shape
+
+`inputs.collection` is a transform-specific path containing the array. Use a plain path:
+
+```json
+"collection": "$vars.orders.output.items"
+```
+
+Never use `=js:` or an inline array literal:
+
+```json
+"collection": "=js:$vars.orders.output.items"
+```
+
+```json
+"collection": "=js:[{\"title\":\"Example\"}]"
+```
+
+The runtime resolves the path as a lookup such as `vars.orders.output.items`; `=js:` and inline JSON/JS literals resolve to an empty collection. For static data, put the array in a workflow variable `defaultValue` or emit it from an upstream static-data/script node, then reference that variable or node output.
+
+A transform's `$vars.<transformNode>.output` is a bare array: filter returns surviving elements, map returns mapped elements, and group-by returns group objects (`{<groupByField>, <alias>…}`). Chain transforms from `.output`, never `.output.items`; `.items` becomes `undefined` and silently yields empty input. `.items`/`.body.items` below refer only to HTTP-body or variable shapes.
+
+```json
+"collection": "$vars.filterHighViewDays.output"
+```
+
+In a Script node, read an element field as `$vars.groupByNode.output[0].totalViews`.
+
+## Generic Transform (`core.action.transform`)
+
+Operations run in order; each feeds the next.
+
+```json
+{
+  "id": "transformChain",
+  "type": "core.action.transform",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Process Employees" },
+  "inputs": {
+    "collection": "$vars.fetchData.output.body.employees",
+    "operations": [
+      {
+        "id": "op1", "type": "filter",
+        "config": {
+          "operation": "and",
+          "filters": [
+            { "id": "f1", "field": "active", "condition": "equals", "value": true }
+          ]
+        }
+      },
+      {
+        "id": "op2", "type": "map",
+        "config": {
+          "keepOriginalFields": false,
+          "mappings": [
+            { "id": "m1", "field": "name", "transformation": "uppercase", "renameTo": "fullName" },
+            { "id": "m2", "field": "salary", "transformation": "copy", "renameTo": "" }
+          ]
+        }
+      }
+    ]
+  },
+  "outputs": {
+    "output": { "type": "object", "description": "The return value of the transform", "source": "=result.response", "var": "output" },
+    "error": { "type": "object", "description": "Error information if the transform fails", "source": "=Error", "var": "error" }
+  }
+}
+```
+
+## Filter (`core.action.transform.filter`)
+
+```json
+{
+  "id": "filterActive",
+  "type": "core.action.transform.filter",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Filter Active Orders" },
+  "inputs": {
+    "collection": "$vars.orders.output.items",
+    "operations": [
+      {
+        "id": "op1", "type": "filter",
+        "config": {
+          "operation": "and",
+          "filters": [
+            { "id": "f1", "field": "status", "condition": "equals", "value": "active" },
+            { "id": "f2", "field": "amount", "condition": "greater_equal", "value": 100 }
+          ]
+        }
+      }
+    ]
+  },
+  "outputs": {
+    "output": { "type": "object", "description": "The return value of the transform", "source": "=result.response", "var": "output" },
+    "error": { "type": "object", "description": "Error information if the transform fails", "source": "=Error", "var": "error" }
+  }
+}
+```
+
+Conditions: `equals`, `not_equals`, `greater_than`, `less_than`, `greater_equal`, `less_equal`, `contains`, `starts_with`, `ends_with`, `is_null`, `is_not_null`.
+
+Operations: `and` (all conditions), `or` (any condition).
+
+`filter.value` is literal-only. It does not evaluate `$vars`, `=js:`, or brace templates; `"$vars.threshold"`, `"=js:$vars.threshold"`, and `"{$vars.threshold}"` are compared as literal strings and silently produce an empty result. Use literal scalars such as `500`, `"active"`, or `true`. For dynamic thresholds, filter in a [Script](../script/impl.md) node or hoist the literal into the flow design. `field` accepts dot-paths such as `order.amount`.
+
+## Map (`core.action.transform.map`)
+
+```json
+{
+  "id": "mapFields",
+  "type": "core.action.transform.map",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Normalize Names" },
+  "inputs": {
+    "collection": "$vars.rawData.output.items",
+    "operations": [
+      {
+        "id": "op1", "type": "map",
+        "config": {
+          "keepOriginalFields": false,
+          "mappings": [
+            { "id": "m1", "field": "firstName", "transformation": "uppercase", "renameTo": "name" },
+            { "id": "m2", "field": "email", "transformation": "lowercase", "renameTo": "" },
+            { "id": "m3", "field": "dept", "transformation": "copy", "renameTo": "department" }
+          ]
+        }
+      }
+    ]
+  },
+  "outputs": {
+    "output": { "type": "object", "description": "The return value of the transform", "source": "=result.response", "var": "output" },
+    "error": { "type": "object", "description": "Error information if the transform fails", "source": "=Error", "var": "error" }
+  }
+}
+```
+
+Transformations: `copy`, `uppercase`, `lowercase`, `trim`.
+
+`keepOriginalFields: false` outputs only mapped fields; `true` passes through unmapped fields. `renameTo` changes the field name; `""` keeps the original name.
+
+## Group By (`core.action.transform.group-by`)
+
+```json
+{
+  "id": "groupByDept",
+  "type": "core.action.transform.group-by",
+  "typeVersion": "<DEFINITION_VERSION>",
+  "display": { "label": "Group by Department" },
+  "inputs": {
+    "collection": "$vars.employees.output.items",
+    "operations": [
+      {
+        "id": "op1", "type": "groupBy",
+        "config": {
+          "groupByField": "department",
+          "aggregations": [
+            { "id": "a1", "field": "", "operation": "count", "alias": "headcount" },
+            { "id": "a2", "field": "salary", "operation": "sum", "alias": "totalSalary" },
+            { "id": "a3", "field": "salary", "operation": "average", "alias": "avgSalary" },
+            { "id": "a4", "field": "salary", "operation": "min", "alias": "minSalary" },
+            { "id": "a5", "field": "salary", "operation": "max", "alias": "maxSalary" },
+            { "id": "a6", "field": "name", "operation": "collect", "alias": "names" },
+            { "id": "a7", "field": "name", "operation": "first", "alias": "firstHire" }
+          ]
+        }
+      }
+    ]
+  },
+  "outputs": {
+    "output": { "type": "object", "description": "The return value of the transform", "source": "=result.response", "var": "output" },
+    "error": { "type": "object", "description": "Error information if the transform fails", "source": "=Error", "var": "error" }
+  }
+}
+```
+
+Aggregation operations:
+
+| Operation | Description | `field` required |
+| --- | --- | --- |
+| `count` | Number of items in group | No |
+| `sum` | Sum of numeric field | Yes |
+| `average` | Average of numeric field | Yes |
+| `min` | Minimum value | Yes |
+| `max` | Maximum value | Yes |
+| `collect` | Array of all field values | Yes |
+| `first` | First item's field value | Yes |
+| `last` | Last item's field value | Yes |
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Filter passes all items through | Wrong condition name, such as `greater` instead of `greater_than` | Use exact names: `equals`, `not_equals`, `greater_than`, `less_than`, `greater_equal`, `less_equal`, `contains`, `starts_with`, `ends_with`, `is_null`, `is_not_null` |
+| Filter silently returns empty array | `value` contains an unresolved expression; Transform compares it as a literal string | Use a literal scalar such as `"value": 500`; for dynamic thresholds, use a Script node |
+| Collection is null/empty | `collection` uses `=js:` or an inline array literal | Use a plain path such as `"$vars.loadCatalog.output.catalog"` or `"$vars.catalog"`; store static arrays in a variable default or upstream node |
+| Map output missing fields | `keepOriginalFields: false` and the field is unmapped | Add the field to mappings or set `keepOriginalFields: true` |
+| GroupBy produces empty groups | No items match `groupByField` | Check that `groupByField` matches the actual data fields |
+| Chained transform gets empty input although upstream had rows | Used `$vars.<transform>.output.items`; transform output is a bare array | Use `$vars.<transform>.output`; see [Output Shape](#collection-input-and-output-shape) |

package/skills/uipath-maestro-flow/references/author/{references/plugins → plugins}/transform/planning.md

@@ -29,7 +29,7 @@ All transform variants share the same port layout:
 | --- | --- |
 | `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).
+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
 

package/skills/uipath-maestro-flow/references/diagnose/CAPABILITY.md

@@ -1,69 +1,71 @@
 # Diagnose — Investigate failed or misbehaving flow runs
 
-Capability index for postmortem on a failed `flow debug` or deployed process run. Diagnose owns the diagnostic priority ladder (incidents → runtime variables → flow correlation → traces) and the catalog of known recurring failure modes (MST-9107, MST-9061, HITL-stuck, reused reference IDs, single-nested layout). Requires `uip login`.
+Capability index for postmortem on a failed `flow debug` or deployed process run. Diagnose owns the diagnostic priority ladder (incidents → runtime variables → flow correlation → traces) and recurring failure modes (missing `=js:`, misshapen nodes, HITL-stuck, reused reference IDs, single-nested layout). Requires `uip login`.
 
-> **Where you came from / where to go next.** Diagnose is downstream of Operate (run faulted → diagnose) and points back to Author for the underlying fix (diagnose → re-author → re-ship). Re-running and lifecycle live in [operate/CAPABILITY.md](../operate/CAPABILITY.md); building/editing the `.flow` file lives in [author/CAPABILITY.md](../author/CAPABILITY.md).
+> **Navigation.** Diagnose follows Operate when a run faults and points to Author for the fix. Re-running and lifecycle are in [operate/CAPABILITY.md](../operate/CAPABILITY.md); building or editing `.flow` files is in [author/CAPABILITY.md](../author/CAPABILITY.md).
 >
-> **Inherits universal rules from [SKILL.md](../../SKILL.md)** — `--output json` + prefer `--output-filter` for extraction, no `flow debug` without consent, never invoke other skills automatically, dropdown question pattern, **plain-English narration + granular progress list (opt-in — silent by default; engage when the user asks for verbosity)**. The rules below are diagnose-scoped and apply on top.
+> **Inherited rules:** use `--output json` and prefer `--output-filter` for extraction; do not run `flow debug` without consent; never invoke other skills automatically; use the dropdown question pattern; provide plain-English narration and a granular progress list only when the user asks for verbosity, and remain silent by default. These rules apply in addition to the rules below.
 
 ## When to use this capability
 
-- Triage a failed `flow debug` or deployed process run
-- Read incidents to identify the error category, message, and faulting element
-- Inspect runtime variable state at the time of failure
-- Map a faulting element ID back to a node in the `.flow` file
-- Stream verbose traces for execution timeline
-- Recognize known failure modes (MST-9107 missing `=js:`, MST-9061 format skipped, etc.)
+- Triage a failed `flow debug` or deployed process run.
+- Read incidents for the error category, message, and faulting element.
+- Inspect runtime variables at failure time.
+- Map a faulting element ID to a `.flow` node.
+- Stream verbose execution traces.
+- Recognize known failures, including missing `=js:` and format skips.
 
 ## Critical rules
 
-1. **Investigate in priority order — incidents → variables → flow correlation → traces.** Each step adds context; stop when you have enough to identify the root cause. Skipping ahead to traces is the most common mistake — they are verbose and last-resort. See [troubleshooting-guide.md](references/troubleshooting-guide.md).
-2. **Always include `--folder-key <FOLDER_KEY>` (`-f` shorthand) on `instance` and `incident get` commands.** Without it the command rejects the request before reaching the API. Get the folder key from `uip or folders list --output json` or from the job/process context. See [shared/cli-conventions.md](../shared/cli-conventions.md#6---folder-key-requirement).
-3. **Never call the underlying APIs directly — always use `uip` CLI commands.** The `instance` and `incident` subcommands are the supported diagnostic surface; direct API calls are not.
-4. **When the local `.flow` may differ from the deployed BPMN, fetch the deployed asset.** Use `uip maestro flow instance asset <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json` to see what actually ran. Do not assume your local file matches.
+0. **Read the faulted `flow debug` response before any other call — never re-run debug to "see the error again".** See [troubleshooting-guide.md — Step 0](troubleshooting-guide.md#step-0--read-the-cause-in-the-debug-output-you-already-have).
+1. **Investigate in order: incidents → variables → flow correlation → traces.** Stop when the root cause is identified; traces are verbose and last-resort. See [troubleshooting-guide.md](troubleshooting-guide.md).
+2. **Always include `--folder-key <FOLDER_KEY>` (`-f` shorthand) on `instance` and `incident get` commands.** Run `uip or folders list --output json` to obtain the folder key, or obtain it from the job/process context. See [shared/cli-conventions.md](../shared/cli-conventions.md#6---folder-key-requirement).
+3. **Never call underlying APIs directly.** Run supported `uip` CLI commands; `instance` and `incident` are the diagnostic surface.
+4. **When the local `.flow` may differ from the deployed BPMN, fetch the deployed asset.** Run `uip maestro flow instance asset <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json` and correlate against what actually ran.
 
 ## Workflow
 
 | Journey | Read |
 | --- | --- |
-| Triage a failed run (priority ladder) | [troubleshooting-guide.md](references/troubleshooting-guide.md) |
-| Look up a known failure mode | [failure-modes.md](references/failure-modes.md) |
+| Triage a failed run (priority ladder) | [troubleshooting-guide.md](troubleshooting-guide.md) |
+| Look up a known failure mode | [failure-modes.md](failure-modes.md) |
 
 ## Common tasks
 
-| I need to... | Read these |
+| Need | Read |
 | --- | --- |
-| **Triage a failed flow run** | [troubleshooting-guide.md](references/troubleshooting-guide.md) |
-| **Find the error message and faulting element** | [troubleshooting-guide.md — Step 2 Fetch incidents](references/troubleshooting-guide.md#step-2--fetch-incidents) |
-| **See data state at the time of failure** | [troubleshooting-guide.md — Step 3 Fetch runtime variable state](references/troubleshooting-guide.md#step-3--fetch-runtime-variable-state) |
-| **Map a faulting element ID to a `.flow` node** | [troubleshooting-guide.md — Step 4 Correlate with the flow definition](references/troubleshooting-guide.md#step-4--correlate-with-the-flow-definition) |
-| **Pull verbose execution timeline** | [troubleshooting-guide.md — Step 5 Traces](references/troubleshooting-guide.md#step-5--traces-last-resort) |
-| **Identify a `vars.X.output.Y` literal-string failure** | [failure-modes.md — MST-9107](references/failure-modes.md#mst-9107--js-prefix-missing) |
-| **Identify misshapen Studio Web nodes** | [failure-modes.md — MST-9061](references/failure-modes.md#mst-9061--misshapen-rectangle-nodes-in-studio-web) |
-| **Diagnose a hung HITL node** | [failure-modes.md — HITL `completed` port unwired](references/failure-modes.md#hitl-completed-port-unwired) |
-| **Diagnose a connector silent fault** | [failure-modes.md — Reused reference ID](references/failure-modes.md#reused-reference-id--cross-connection-id-leakage) |
-| **Diagnose a publish/upload structural error** | [failure-modes.md — Single-nested layout](references/failure-modes.md#single-nested-layout) |
-| **Diagnose `Folder does not exist` on a resource node** | [failure-modes.md — Missing `bindings[]` on resource node](references/failure-modes.md#missing-bindings-on-resource-node) |
-| **Triage "validate passes, debug faults"** | [failure-modes.md — `flow validate` passes, `flow debug` faults](references/failure-modes.md#flow-validate-passes-flow-debug-faults) |
-| **Look up `instance` / `incident` CLI syntax** | [shared/cli-commands.md](../shared/cli-commands.md) + [troubleshooting-guide.md — CLI command reference](references/troubleshooting-guide.md#cli-command-reference) |
+| Triage a failed flow run | [troubleshooting-guide.md](troubleshooting-guide.md) |
+| Read the cause out of a faulted `flow debug` response | [troubleshooting-guide.md — Step 0](troubleshooting-guide.md#step-0--read-the-cause-in-the-debug-output-you-already-have) |
+| Find the error message and faulting element | [troubleshooting-guide.md — Step 2 Fetch incidents](troubleshooting-guide.md#step-2--fetch-incidents) |
+| See data state at failure time | [troubleshooting-guide.md — Step 3 Fetch runtime variable state](troubleshooting-guide.md#step-3--fetch-runtime-variable-state) |
+| Map a faulting element ID to a `.flow` node | [troubleshooting-guide.md — Step 4 Correlate with the flow definition](troubleshooting-guide.md#step-4--correlate-with-the-flow-definition) |
+| Pull verbose execution timeline | [troubleshooting-guide.md — Step 5 Traces](troubleshooting-guide.md#step-5--traces-last-resort) |
+| Identify a `vars.X.output.Y` literal-string failure | [failure-modes.md — `=js:` prefix missing](failure-modes.md#js-prefix-missing) |
+| Identify misshapen Studio Web nodes | [failure-modes.md — misshapen nodes](failure-modes.md#misshapen-rectangle-nodes-in-studio-web) |
+| Diagnose a hung HITL node | [failure-modes.md — HITL `completed` port unwired](failure-modes.md#hitl-completed-port-unwired) |
+| Diagnose a connector silent fault | [failure-modes.md — Reused reference ID](failure-modes.md#reused-reference-id--cross-connection-id-leakage) |
+| Diagnose a publish/upload structural error | [failure-modes.md — Single-nested layout](failure-modes.md#single-nested-layout) |
+| Diagnose `Folder does not exist` on a resource node | [failure-modes.md — Missing `bindings[]` on resource node](failure-modes.md#missing-bindings-on-resource-node) |
+| Triage "validate passes, debug faults" | [failure-modes.md — `flow validate` passes, `flow debug` faults](failure-modes.md#flow-validate-passes-flow-debug-faults) |
+| Look up `instance` / `incident` CLI syntax | [shared/cli-commands.md](../shared/cli-commands.md) + [troubleshooting-guide.md — CLI command reference](troubleshooting-guide.md#cli-command-reference) |
 
 ## Anti-patterns
 
-- **Never start with traces.** They are verbose and contain the full execution timeline — useful only when incidents and variables are insufficient. Start with incidents (Step 2 of the priority ladder).
-- **Never call the underlying APIs directly.** Always use `uip maestro flow instance` / `incident` / `job` subcommands. Direct API calls bypass the supported diagnostic surface.
-- **Never assume the local `.flow` matches the deployed BPMN.** If there's any chance the deployed flow differs (a republish since the local edit, a different branch, a different solution version), fetch `instance asset` to see what actually ran. Otherwise your correlation between faulting element and `.flow` node will mislead you.
-- **Never skip the `--folder-key` flag** on `instance` or `incident get` commands. The command rejects the request before reaching the API; the failure looks like a CLI error but is really a missing argument.
+- **Do not start with traces.** Start with incidents (Step 2), then variables, flow correlation, and traces only if needed.
+- **Do not call underlying APIs directly.** Run `uip maestro flow instance` / `incident` / `job` subcommands.
+- **Do not assume the local `.flow` matches the deployed BPMN.** If a republish, branch, or solution-version difference is possible, run `instance asset` before correlating IDs.
+- **Do not omit `--folder-key`** from `instance` or `incident get`; the command rejects the request before reaching the API.
 
 ## References
 
 ### Diagnose-scoped
 
-- [troubleshooting-guide.md](references/troubleshooting-guide.md) — diagnostic priority ladder (incidents → variables → flow correlation → traces) and full `instance` / `incident` CLI reference
-- [failure-modes.md](references/failure-modes.md) — pattern catalog for known recurring failures: MST-9107, MST-9061, HITL-stuck, reused reference IDs, single-nested layout, "validate passes / debug faults"
+- [troubleshooting-guide.md](troubleshooting-guide.md) — diagnostic priority ladder (incidents → variables → flow correlation → traces) and full `instance` / `incident` CLI reference
+- [failure-modes.md](failure-modes.md) — recurring failures: missing `=js:`, misshapen nodes, HITL-stuck, reused reference IDs, single-nested layout, and "validate passes / debug faults"
 
 ### Cross-capability (shared)
 
 - [shared/cli-commands.md](../shared/cli-commands.md) — flat CLI lookup including `instance` / `incident` / `job` subcommands
 - [shared/cli-conventions.md](../shared/cli-conventions.md) — `--folder-key` requirement, login state, JSON output shape
-- [shared/file-format.md](../shared/file-format.md) — to correlate faulting element IDs back to `.flow` nodes
-- [shared/node-output-wiring.md](../shared/node-output-wiring.md) — referenced from MST-9107 failure mode
+- [shared/file-format.md](../shared/file-format.md) — correlate faulting element IDs to `.flow` nodes
+- [shared/node-output-wiring.md](../shared/node-output-wiring.md) — referenced from the `=js:` prefix-missing failure mode

package/skills/uipath-maestro-flow/references/diagnose/{references/failure-modes.md → failure-modes.md}

@@ -8,19 +8,19 @@ Lookup table for known recurring failure modes in Maestro Flow projects. Each en
 
 | Pattern | Symptom | Cause |
 |---|---|---|
-| [MST-9107](#mst-9107--js-prefix-missing) | Activity input bound to literal string `"vars.X.output.Y"` | Missing `=js:` prefix on a `$vars` reference. `flow validate` catches this — pre-`expression-prefix-validator` cli still ships the literal at runtime. |
-| [MST-9972](#mst-9972--variablesnodes-missing-vars-resolves-to-undefined) | `Cannot read property 'output' of undefined` on a downstream node | Direct-authored `.flow` skipped `variables.nodes[]`; `flow validate` accepts it but the BPMN has no process-level variable declaration for the upstream node. |
-| [MST-9061](#mst-9061--misshapen-rectangle-nodes-in-studio-web) | Nodes render at the wrong size for their shape | `flow format` not run before publish |
+| [`=js:` prefix missing](#js-prefix-missing) | Activity input bound to literal string `"vars.X.output.Y"` | Missing `=js:` prefix on a `$vars` reference. `flow validate` catches this — pre-`expression-prefix-validator` cli still ships the literal at runtime. |
+| [`variables.nodes[]` missing](#variablesnodes-missing--varsxoutput-resolves-to-undefined) | `Cannot read property 'output' of undefined` on a downstream node | Direct-authored `.flow` skipped `variables.nodes[]`; `flow validate` accepts it but the BPMN has no process-level variable declaration for the upstream node. |
+| [Misshapen nodes in Studio Web](#misshapen-rectangle-nodes-in-studio-web) | Nodes render at the wrong size for their shape | `flow format` not run before publish |
 | [HITL `completed` port unwired](#hitl-completed-port-unwired) | Flow hangs indefinitely after a HITL node | No outgoing edge from the node's `completed` source port |
 | [Run reports `Completed`, work not done](#run-reports-completed-but-the-work-never-happened) | Run finishes `Completed`, but the API call / node it depended on failed | `inputs.errorHandlingEnabled: true` on a node with no handler, or an `error` edge routed back into the happy path |
 | [Reused reference ID](#reused-reference-id--cross-connection-id-leakage) | Connector node faults silently at runtime | Reference ID copied from a prior flow's connection |
 | [Single-nested layout](#single-nested-layout) | Studio Web upload fails; `flow init` auto-registration is skipped | `uip maestro flow init` was run with `--skip-solution-registration` (opts out of auto-scaffold + registration) |
 | [Missing `bindings[]` on resource node](#missing-bindings-on-resource-node) | `Folder does not exist or the user does not have access to the folder` | Top-level `bindings[]` entries not added for a `uipath.core.*` resource node |
-| [`flow validate` passes, `flow debug` faults](#flow-validate-passes-flow-debug-faults) | Local validation green, cloud run red | Multiple causes — narrower than before (MST-9107 + expression-ref linting now catch a large slice statically). See entry for the residual triage path. |
+| [`flow validate` passes, `flow debug` faults](#flow-validate-passes-flow-debug-faults) | Local validation green, cloud run red | Multiple causes — narrower than before (the missing-`=js:` validator + expression-ref linting now catch a large slice statically). See entry for the residual triage path. |
 
 ---
 
-## MST-9107 — `=js:` prefix missing
+## `=js:` prefix missing
 
 ### Symptom
 
@@ -51,11 +51,11 @@ Do **not** add `=js:` to condition expressions (decision `expression`, switch ca
 
 ### Reference
 
-[shared/node-output-wiring.md](../../shared/node-output-wiring.md) — canonical per-node-type field reference.
+[shared/node-output-wiring.md](../shared/node-output-wiring.md) — canonical per-node-type field reference.
 
 ---
 
-## MST-9972 — `variables.nodes[]` missing → `$vars.X.output` resolves to undefined
+## `variables.nodes[]` missing → `$vars.X.output` resolves to undefined
 
 ### Symptom
 
@@ -69,7 +69,7 @@ This happens almost exclusively on **direct-authored** `.flow` files: `uip maest
 
 ### Fix
 
-Run `uip maestro flow format <ProjectName>.flow --output json`. Post-MST-9972 the format command regenerates `variables.nodes[]` from `nodes[]` + `definitions[]` (matching `node add` and canvas behavior). On older CLI versions, add the entries manually:
+Run `uip maestro flow format <ProjectName>.flow --output json`. Current CLI versions regenerate `variables.nodes[]` from `nodes[]` + `definitions[]` (matching `node add` and canvas behavior). On older CLI versions, add the entries manually:
 
 ```json
 "variables": {
@@ -92,11 +92,11 @@ One entry per declared output (trigger nodes: `output` only; action nodes: `outp
 
 ### Reference
 
-[shared/file-format.md — Node outputs](../../shared/file-format.md#node-outputs), [author/CAPABILITY.md rule #14](../../author/CAPABILITY.md), [editing-operations-json.md — Pre-flight Checklist step 5–6](../../author/references/editing-operations-json.md#pre-flight-checklist).
+[shared/file-format.md — Node outputs](../shared/file-format.md#node-outputs), [author/CAPABILITY.md rule #14](../author/CAPABILITY.md), [editing-operations-json.md — Pre-flight Checklist step 5–6](../author/editing-operations-json.md#pre-flight-checklist).
 
 ---
 
-## MST-9061 — Misshapen rectangle nodes in Studio Web
+## Misshapen rectangle nodes in Studio Web
 
 ### Symptom
 
@@ -123,7 +123,7 @@ Format:
 
 ### Reference
 
-[author capability](../../author/CAPABILITY.md) — see "Always run `flow format` after edits" in critical rules; [shared/cli-commands.md — uip maestro flow format](../../shared/cli-commands.md#uip-maestro-flow-format).
+[author capability](../author/CAPABILITY.md) — see "Always run `flow format` after edits" in critical rules; [shared/cli-commands.md — uip maestro flow format](../shared/cli-commands.md#uip-maestro-flow-format).
 
 ---
 
@@ -143,7 +143,7 @@ Add an edge from the HITL node's `completed` port to the next node in the flow.
 
 ### Reference
 
-[Author HITL plugin reference](../../author/references/plugins/hitl/impl.md) — full HITL node reference including port wiring requirements.
+[Author HITL plugin reference](../author/plugins/hitl/impl.md) — full HITL node reference including port wiring requirements.
 
 ---
 
@@ -209,8 +209,8 @@ Re-run `uip maestro flow validate` and `uip maestro flow format` after either fi
 
 ### Reference
 
-- [shared/file-format.md — Default: off](../../shared/file-format.md#default-off--enable-only-for-a-failure-the-flow-actually-handles) and [Do not swallow the failure](../../shared/file-format.md#do-not-swallow-the-failure)
-- [Author capability — rule #16](../../author/CAPABILITY.md#critical-rules)
+- [shared/file-format.md — Default: off](../shared/file-format.md#default-off--enable-only-for-a-failure-the-flow-actually-handles) and [Do not swallow the failure](../shared/file-format.md#do-not-swallow-the-failure)
+- [Author capability — rule #16](../author/CAPABILITY.md#critical-rules)
 
 ---
 
@@ -240,8 +240,8 @@ uip is resources run list <connector-key> <objectName> --connection-id <CURRENT_
 
 ### Reference
 
-- [Author connector plugin — Step 4](../../author/references/plugins/connector/impl.md)
-- [Author connector-trigger plugin — Step 3](../../author/references/plugins/connector-trigger/impl.md)
+- [Author connector plugin — Step 4](../author/plugins/connector/impl.md)
+- [Author connector-trigger plugin — Step 3](../author/plugins/connector-trigger/impl.md)
 
 ---
 
@@ -280,7 +280,7 @@ If the absolute path doesn't exist, the `init` step was wrong — do not try to
 
 ### Reference
 
-[Author greenfield journey — Step 2](../../author/references/greenfield.md) — the canonical scaffold sequence.
+[Author greenfield journey — Step 2](../author/greenfield.md) — the canonical scaffold sequence.
 
 ---
 
@@ -304,11 +304,11 @@ For `uipath.core.*` resource nodes (rpa, agent, flow, agentic-process, api-workf
 
 ### Fix
 
-Add two entries to the top-level `bindings[]` array per resource node — `name` and `folderPath` — with `resourceKey` matching the definition's `model.bindings.resourceKey`. See the relevant resource plugin's `impl.md` for the exact shape ([rpa](../../author/references/plugins/rpa/impl.md), [agent](../../author/references/plugins/agent/impl.md), [flow](../../author/references/plugins/flow/impl.md), [agentic-process](../../author/references/plugins/agentic-process/impl.md), [api-workflow](../../author/references/plugins/api-workflow/impl.md), [hitl](../../author/references/plugins/hitl/impl.md)).
+Add two entries to the top-level `bindings[]` array per resource node — `name` and `folderPath` — with `resourceKey` matching the definition's `model.bindings.resourceKey`. See the relevant resource plugin's `impl.md` for the exact shape ([rpa](../author/plugins/rpa/impl.md), [agent](../author/plugins/agent/impl.md), [flow](../author/plugins/flow/impl.md), [agentic-process](../author/plugins/agentic-process/impl.md), [api-workflow](../author/plugins/api-workflow/impl.md), [hitl](../author/plugins/hitl/impl.md)).
 
 ### Reference
 
-[shared/file-format.md — Bindings](../../shared/file-format.md#bindings--orchestrator-resource-bindings-top-level-bindings)
+[shared/file-format.md — Bindings](../shared/file-format.md#bindings--orchestrator-resource-bindings-top-level-bindings)
 
 ---
 
@@ -324,8 +324,8 @@ Multiple. `flow validate` runs a JSON schema check, cross-reference checks, expr
 
 **Caught** (validate exits non-zero, with a precise field path and remediation hint):
 
-- Missing `=js:` prefix on `$vars`/`$metadata`/`$self` (MST-9107) — emitted by cli-side `expression-prefix-validator`
-- Invented `nodes.<id>.output.<...>` syntax (MST-9107 variant) — same validator, suggests `=js:$vars.<id>.output.<...>` as the fix
+- Missing `=js:` prefix on `$vars`/`$metadata`/`$self` — emitted by cli-side `expression-prefix-validator`
+- Invented `nodes.<id>.output.<...>` syntax (same failure class) — same validator, suggests `=js:$vars.<id>.output.<...>` as the fix
 - References to unknown variable IDs or node IDs in `=js:` expressions (`EXPR_UNRESOLVED_REF`) — flow-schema `expression-ref` rule
 - Output-path walks that descend into a declared primitive (`type: "string"` etc.) or a schema closed with `additionalProperties: false` (`EXPR_INVALID_OUTPUT_PATH`) — flow-schema `expression-ref` rule
 - Missing End-node output mappings for declared `out` variables (`MISSING_OUTPUT_MAPPING`, **warning** severity) — flow-schema `output-mapping` rule
@@ -336,7 +336,7 @@ Multiple. `flow validate` runs a JSON schema check, cross-reference checks, expr
 - Reused reference IDs → see [Reused reference ID](#reused-reference-id--cross-connection-id-leakage)
 - Missing top-level `bindings[]` entries on resource nodes → see [Missing `bindings[]` on resource node](#missing-bindings-on-resource-node)
 - HITL `completed` port unwired → see [HITL `completed` port unwired](#hitl-completed-port-unwired)
-- Stale `layout` data → see [MST-9061](#mst-9061--misshapen-rectangle-nodes-in-studio-web) (cosmetic, not faulting)
+- Stale `layout` data → see [Misshapen rectangle nodes](#misshapen-rectangle-nodes-in-studio-web) (cosmetic, not faulting)
 - Output-path walks against **open** output schemas — HTTP response bodies, script returns, free-text agent output. The deep-path walker is permissive by design: it skips when the producer's schema doesn't authoritatively declare the field's structure, so e.g. `=js:$vars.fetchWeather.output.body.current_weather` against an HTTP node that declares only `output: { type: "object" }` passes validate and faults only when the runtime response doesn't have that path.
 - Wrong-direction reads (reading an `out`-only variable) — currently a runtime concern; the direction discriminator isn't yet threaded into the validator context.
 

package/skills/uipath-maestro-flow/references/diagnose/{references/troubleshooting-guide.md → troubleshooting-guide.md}

@@ -8,11 +8,70 @@ Diagnostic workflow for failed debug runs and deployed process runs. All command
 
 Investigate in this order — each step adds context, stop when you have enough to diagnose the root cause:
 
+0. The failed `flow debug` response you already have (incident + fault detail, no extra call)
 1. Incidents (error message + faulting element)
 2. Runtime variables (data state at failure)
 3. Flow definition correlation (map element to `.flow` node)
 4. Traces (last resort — verbose full timeline)
 
+## Step 0 — Read the cause in the debug output you already have
+
+A faulted `uip maestro flow debug` response already carries the incident and the fault detail. **Do not re-run `flow debug` before you read them.** An unchanged re-run re-uploads the solution and repeats the same fault against real systems.
+
+The response can exceed 200,000 characters. `"Result": "Failure"` and `Context.ErrorCode` (the numeric incident code) sit in the first 1,000 characters; the cause sits tens of thousands of characters deeper. Reading the head of the output and stopping tells you that the run failed, not why. Never report a faulted run as "incomplete" — report the fault code and the detail.
+
+Two fields hold the cause:
+
+| Field | JSON path |
+|---|---|
+| Fault code + faulting element | `Data.incidents[].dependentFaultCode`, `.elementId`, `.errorCode`, `.errorDetails` |
+| Fault detail (the real message) | `Data.variables.elements[].outputs.Error.detail`, `.code` |
+
+### Redirect stdout to a file, then extract
+
+Logs go to stderr and JSON to stdout, so redirect stdout to keep the full response. Keep stderr visible — on a poll-budget overrun it carries the only instanceId (see [cli-conventions.md §7](../shared/cli-conventions.md#7-use-uip_log_levelinfo-for-debug-runs)).
+
+```bash
+UIP_LOG_LEVEL=info uip maestro flow debug <PROJECT_DIR> --output json > /tmp/flow-debug.json
+```
+
+Wait for the process to exit before reading the file. `flow debug` prints its JSON only when it exits, so an empty file means the run is still going — see [operate/run.md — Debug](../operate/run.md#debug--controlled-end-to-end-run).
+
+Extract both fields:
+
+```bash
+jq -r '.Data.incidents[] | "\(.elementId) \(.errorCode) \(.dependentFaultCode) \(.errorDetails)"' /tmp/flow-debug.json
+jq -r '.Data.variables.elements[] | select(.outputs.Error) | "\(.elementId) \(.outputs.Error.code) \(.outputs.Error.detail)"' /tmp/flow-debug.json
+```
+
+Without `jq`:
+
+```bash
+python3 - /tmp/flow-debug.json <<'EOF'
+import json, sys
+data = json.load(open(sys.argv[1]))["Data"]
+for incident in data.get("incidents", []):
+    print(incident["elementId"], incident["errorCode"], incident["dependentFaultCode"], incident["errorDetails"])
+for element in data.get("variables", {}).get("elements", []):
+    error = element.get("outputs", {}).get("Error")
+    if error:
+        print(element["elementId"], error["code"], error["detail"])
+EOF
+```
+
+The CLI applies `--output-filter` only when a command succeeds; a faulted run prints the whole envelope.
+
+### Match the fault code
+
+Match `dependentFaultCode`, or the failure marker on a run that never started, to a known cause:
+
+| Fault marker | Cause and fix |
+|---|---|
+| `dependentFaultCode: AGENT_STARTUP.INPUT_VALIDATION_ERROR` | Declared `type` does not match the bound node's real output shape — the runtime strict-validates agent inputs. `detail` names the failing key and the real type (for example `input_type=list`). See [author/plugins/inline-agent/impl.md — Anti-patterns](../author/plugins/inline-agent/impl.md#anti-patterns). |
+| `Stage: prepare-custom-debug` with `HttpStatus: 500`, and no `Data.incidents` | Debug was pointed at a shared folder with `--folder-path` or `--folder-key`. The server fails to prepare the run and no instance starts, so there is no incident to read. Re-run `flow debug` without the flag. See [operate/run.md — Debug](../operate/run.md#debug--controlled-end-to-end-run). |
+
+No match, or `detail` is not enough → `uip maestro flow debug-instance incidents <INSTANCE_ID> --output json` returns the full backend payload (incidentId, errorDetails, AI summary). For a deployed process run, continue with Step 1.
+
 ## Step 1 — Get the instance ID
 
 The debug output (`Data.instanceId`) or `job status` response contains the instance ID. If you only have a job key:
@@ -101,7 +160,7 @@ uip maestro flow instance asset <INSTANCE_ID> -f <FOLDER_KEY> --output json
 uip maestro flow instance cursors <INSTANCE_ID> -f <FOLDER_KEY> --output json                       # get current execution cursor positions
 ```
 
-> **Lifecycle commands** (`pause` / `resume` / `cancel` / `retry`) are operate concerns — see the [Operate manage guide](../../operate/references/manage.md).
+> **Lifecycle commands** (`pause` / `resume` / `cancel` / `retry`) are operate concerns — see the [Operate manage guide](../operate/manage.md).
 
 ### uip maestro flow incident