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

package/skills/uipath-maestro-flow/references/shared/cli-conventions.md

@@ -1,31 +1,32 @@
 # CLI Conventions
 
-Shared conventions for the `uip` CLI that apply across **all three capabilities** (Author, Operate, Diagnose). Read this first when invoking any `uip` command — every capability assumes these mechanics.
+Shared conventions for the `uip` CLI across Author, Operate, and Diagnose. Read this before invoking any `uip` command.
 
-## 1. Resolve the `uip` binary and detect command prefix
+## 1. Resolve `uip` and detect the command prefix
 
-The `uip` CLI is installed via npm. Resolve the binary (it may not be on PATH in nvm environments) and detect the command namespace.
+Resolve the npm-installed binary, which may be absent from PATH in nvm environments:
 
 ```bash
 UIP=$(command -v uip 2>/dev/null || echo "$(npm root -g 2>/dev/null | sed 's|/node_modules$||')/bin/uip")
 CURRENT=$($UIP --version 2>/dev/null | awk '{print $NF}')
 ```
 
-If `uip` is not found at all, install it:
+If `uip` is not found, run:
 
 ```bash
 npm install -g @uipath/cli@latest
 ```
 
-If `npm install -g` fails with a permission error, prompt the user to re-run with appropriate privileges — do not retry automatically.
+If global installation fails with a permission error, prompt the user to rerun it with appropriate privileges; do not retry automatically.
 
-### Command prefix by version
+Use `uip maestro flow` for CLI version **≥ 0.3.4** and `uip flow` for versions **< 0.3.4**: <!-- uip-check-skip -->
 
 | Installed version | Command prefix | Example |
 | --- | --- | --- |
 | **≥ 0.3.4** | `uip maestro flow` | `uip maestro flow init MyProject` |
 | **< 0.3.4** | `uip flow` | `uip flow init MyProject` <!-- uip-check-skip --> |
 
+
 ```bash
 MIN_VERSION="0.3.4"
 if [ "$(printf '%s\n%s\n' "$MIN_VERSION" "$CURRENT" | sort -V | head -n1)" = "$MIN_VERSION" ]; then
@@ -36,11 +37,11 @@ fi
 echo "Using: $FLOW_CMD (CLI version $CURRENT)"
 ```
 
-> **All commands across this skill are written as `uip maestro flow ...` (the ≥ 0.3.4 form).** If version detection above returns < 0.3.4, replace `uip maestro flow` with `uip flow`. Arguments and flags are identical — only the prefix differs. See UiPath/cli#841 for background on the restructuring. <!-- uip-check-skip -->
+Run all commands below with `uip maestro flow ...`; if detection returns < 0.3.4, replace only that prefix with `uip flow`. Arguments and flags are identical. See UiPath/cli#841. <!-- uip-check-skip -->
 
-## 2. Always use `--output json`
+## 2. Use JSON output
 
-All `uip` commands support structured JSON output. Use `--output json` whenever output is parsed programmatically — every reference doc and recipe in this skill assumes it.
+Run programmatically parsed commands with `--output json`:
 
 ```bash
 uip maestro flow validate <ProjectName>.flow --output json
@@ -48,78 +49,68 @@ uip maestro flow registry list --output json
 uip maestro flow instance incidents <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json
 ```
 
-> **Anti-pattern: `--format json` does NOT exist.** The flag is `--output json`. Using `--format json` produces `error: unknown option '--format'` and exit code 3 on every `uip` subcommand — not a helpful message pointing at `--output`.
-
-The `--localstorage-file` warning that appears in some environments is benign and can be ignored.
+Do not use `--format json`; it does not exist and produces `error: unknown option '--format'` with exit code 3 on every `uip` subcommand. Ignore the benign `--localstorage-file` warning when it appears.
 
 ## 3. Prefer `--output-filter` for extraction
 
-When extracting one field or a projection from `uip --output json`, use `--output-filter '<jmespath>'`. The CLI exposes `--output-filter <expression>` as a global flag on every subcommand; it applies a [JMESPath](https://jmespath.org/) expression to the `Data` envelope **before** printing. Write expressions starting at `Data` — do **not** prefix them with `Data.`.
+Prefer `--output-filter '<jmespath>'` for field or projection extraction. It is a global flag on every subcommand, applies to the `Data` envelope before printing, and expressions start at `Data` (never `Data.`).
 
-**Canonical example (broad discovery)** — list all nodes matching a keyword with the standard projection:
+Run broad discovery with:
 
 ```bash
 uip maestro flow registry search slack --output json \
   --output-filter "[*].{NodeType:NodeType,DisplayName:DisplayName,Description:Description,AvailableOnTenant:AvailableOnTenant}"
 ```
 
-This is the form used in the connector skill — see [Cross-references](#cross-references) below — and is the right starting point when you want to inspect what's available.
-
-**Narrow query** — once you know the connector namespace, filter to a single connector's activities:
+Run a narrowed connector query with:
 
 ```bash
 uip maestro flow registry search slack --output json \
   --output-filter "[?starts_with(NodeType,'uipath.connector.uipath-salesforce-slack.')].{NodeType:NodeType,DisplayName:DisplayName}"
 ```
 
-`registry search` returns `Data` as a **flat array of PascalCase objects** — `NodeType`, `Category`, `DisplayName`, `Description`, `Version`, `Tags`, `AvailableOnTenant`. Not `Data.Nodes`, not lowercase `type`/`category`; those shapes do not exist. Knowing the shape lets you write the right expression on call #1 — which is the actual protection. Do **not** rely on `--output-filter` to *catch* a wrong-shape guess: a syntactically valid expression that simply doesn't match (e.g. `--output-filter "Nodes"` or `"Nodes[*].NodeType"` against the flat array) returns `Data: []` with **exit 0** — the same silent trap as `python3`/`jq` (see the silent-`[]` note below). Only an *invalid* expression fails loudly with exit 3: a syntax error, or a type error such as `keys(@)` on an array.
+Treat `registry search` as returning `Data` as a flat array of PascalCase objects: `NodeType`, `Category`, `DisplayName`, `Description`, `Version`, `Tags`, `AvailableOnTenant`. It does not return `Data.Nodes` or lowercase `type`/`category`.
 
-> **Never `head`/`tail`/`grep -m`/pager a discovery query** (`registry search`, `is connectors list`, any `list`/`search`). A row past the cutoff reads exactly like a row that doesn't exist — the same false-absence trap as the silent `[]`, self-inflicted. To check existence, push the predicate into `--output-filter` so the result is *all* matches and already small; cap rows only on data already known complete or already filtered.
->
-> ```bash
-> uip … registry search slack --output json --output-filter "[?contains(NodeType,'get-channel-info')].NodeType"   # right: every match
-> uip … registry search slack --output json --output-filter "[*].{…}" | head -100                                # wrong: hides matches past line 100
-> ```
+Do not use `head`, `tail`, `grep -m`, or a pager on discovery queries (`registry search`, `is connectors list`, or any `list`/`search`). Test existence with a predicate in `--output-filter` and return all matches:
+
+```bash
+uip … registry search slack --output json --output-filter "[?contains(NodeType,'get-channel-info')].NodeType"   # right: every match
+uip … registry search slack --output json --output-filter "[*].{…}" | head -100                                # wrong: hides matches past line 100
+```
 
-### When to fall back to `python3` / `jq`
+> **Exception — any command that fails.** The CLI applies `--output-filter` only on the success path; a `Result: "Failure"` envelope prints whole. This bites hardest on a faulted `flow debug` (200 KB and more) — redirect stdout to a file and extract from the file, see [diagnose/troubleshooting-guide.md — Step 0](../diagnose/troubleshooting-guide.md#step-0--read-the-cause-in-the-debug-output-you-already-have).
 
-`--output-filter` is the preferred extraction mechanism, but it is not a general-purpose transformation tool. Fall back to `python3 -c` or `jq` when JMESPath cannot express the operation:
+Treat `Data: []` with exit 0 as a valid but mismatched expression, not proof of absence. Only invalid syntax or type errors fail with exit 3.
 
-- Multi-step joins across two CLI calls.
-- Format conversion (JSON → CSV, JSON → env-var assignments).
-- Conditional output that depends on a value computed from multiple fields.
+Use `python3 -c` or `jq` only when JMESPath cannot perform a multi-step join across CLI calls, JSON-to-CSV or JSON-to-env-var conversion, or conditional output based on multiple fields. Verify the shape first:
 
-Before reaching for an external parser, verify the JSON shape. The CLI roots `--output-filter` expressions at `Data`, so:
+- Run `--output-filter "type(@)"`; it returns `"array"` or `"object"`.
+- For an object, run `--output-filter "keys(@)"`.
+- For an array, run `--output-filter "[0]"` or `--output-filter "[0] | keys(@)"`.
+- Do not run `keys(@)` directly on an array; it fails with `Filter 'keys(@)' failed to evaluate: Invalid type: keys() expected argument 1 to be of type (object) but received type array instead`.
+- If an expected value is `Data: []`, check field-name casing.
 
-- **Check whether `Data` is array or object first** — `--output-filter "type(@)"` returns `"array"` or `"object"`. `keys(@)` throws on arrays (`Filter 'keys(@)' failed to evaluate: Invalid type: keys() expected argument 1 to be type (object) but received type array instead`), so use `type(@)` as the first probe.
-- **If `type(@)` returned `"object"`:** `--output-filter "keys(@)"` lists the top-level field names at `Data`.
-- **If `type(@)` returned `"array"`:** `--output-filter "[0]"` shows the first row, or `--output-filter "[0] | keys(@)"` lists the keys of one row.
-- **Watch for silent `[]`** — when the JMESPath path doesn't match anything, the CLI returns `Data: []` with `Result: "Success"`. That's the exact silent-failure mode the docs are designed to surface. If you got `Data: []` and were expecting a value, double-check field-name casing — **and note casing differs by command:**
-  - `registry search` / `list` (and most `uip … --output json` commands) return **PascalCase** keys → filter `[*].NodeType`, `[*].DisplayName`.
-  - `registry get` returns the node definition **verbatim** (it is pasted straight into the `.flow`), so its keys keep the manifest's own casing — predominantly **camelCase**: `Node.nodeType`, `Node.inputDefinition`, `Node.supportsErrorHandling`, `Node.form.sections[…]`. A few nested *runtime-output* schemas are PascalCase because the engine emits them that way (e.g. Summarize's `content.Text` / `content.Citations`) — match whatever the manifest actually declares, not a normalized form.
-  - When unsure, probe before guessing: `--output-filter "keys(@)"` (object) or `--output-filter "[0] | keys(@)"` (array).
+`registry search` and `list` (and most `uip … --output json` commands) use PascalCase keys such as `[*].NodeType` and `[*].DisplayName`. `registry get` returns the node definition verbatim for pasting into `.flow`; its keys are predominantly camelCase: `Node.nodeType`, `Node.inputDefinition`, `Node.supportsErrorHandling`, and `Node.form.sections[…]`. Some nested runtime-output schemas are PascalCase, such as Summarize's `content.Text` and `content.Citations`. Match the manifest rather than assuming normalized casing. When uncertain, probe with `--output-filter "keys(@)"` for objects or `--output-filter "[0] | keys(@)"` for arrays.
 
-Most agent-side retry loops on `uip --output json` parsing come from guessing the shape wrong; verify, then parse.
+Verify the shape before parsing; most parsing retries result from an incorrect shape guess.
 
 ### Cross-references
 
-The broad-discovery recipe above is used in [author/references/plugins/connector/planning.md](../author/references/plugins/connector/planning.md) (§ Discovery) for connector discovery and [author/references/plugins/connector/impl.md](../author/references/plugins/connector/impl.md) for connection-resource lookup. Keep the three in sync on the **preference** (always `--output-filter`) and the **shape pin** (`registry search` Data is a flat array of PascalCase objects); each file may pick a projection appropriate to its task.
+Keep the broad-discovery recipe aligned with [author/plugins/connector/planning.md](../author/plugins/connector/planning.md) (§ Discovery) for connector discovery and [author/plugins/connector/impl.md](../author/plugins/connector/impl.md) for connection-resource lookup. Both files use the `--output-filter` preference and the `registry search` flat-array/PascalCase shape; each may use a task-specific projection.
 
-## 4. CLI output JSON shape
+## 4. Check the JSON response shape
 
-Every `uip` command returns one of two response shapes:
+Every `uip` command returns one of these shapes:
 
-**Success:**
 ```json
 { "Result": "Success", "Code": "FlowValidate", "Data": { ... } }
 ```
 
-**Failure:**
 ```json
-{ "Result": "Failure", "Message": "...", "Instructions": "Found N error(s): ..." }
+{ "Result": "Failure", "Message": "...", "Instructions": "Found N error(s): ...", "Data": { ... } }
 ```
 
-Always check `Result` first. On failure, `Message` and `Instructions` carry the diagnostic detail.
+Always check `Result` first. On failure, use `Message` and `Instructions` for diagnostics. A failure envelope may still carry `Data` — `flow debug` returns the full run payload on a fault.
 
 ## 5. Login state
 
@@ -129,15 +120,15 @@ Always check `Result` first. On failure, `Message` and `Instructions` carry the
 | **Operate** | **Yes** — `solution upload`, `solution resources refresh`, `flow debug`, `flow pack`, `process run`, `job status`, `job traces` all require `uip login` |
 | **Diagnose** | **Yes** — `instance incidents`, `instance variables`, `instance asset`, `incident get`, `incident summary` all require `uip login` |
 
-Tenant-specific connector and resource nodes in the registry also require login. Without login, registry shows OOTB nodes only. **In-solution sibling projects** are always available via `--local` without login.
+Tenant-specific connector and resource nodes require login; without it, the registry shows OOTB nodes only. In-solution sibling projects are always available with `--local` without login.
 
-Check login status:
+Check login by running:
 
 ```bash
 uip login status --output json
 ```
 
-Log in interactively (opens browser):
+Log in interactively by running:
 
 ```bash
 uip login
@@ -146,30 +137,28 @@ uip login --authority https://alpha.uipath.com    # non-production environments
 
 ## 6. `--folder-key` requirement
 
-All `uip maestro flow instance` and `uip maestro flow incident get` commands require `--folder-key <FOLDER_KEY>` (`-f` shorthand). Without it, the command rejects the request before reaching the API.
+Run all `uip maestro flow instance` and `uip maestro flow incident get` commands with `--folder-key <FOLDER_KEY>` (or `-f`). Without it, the request is rejected before reaching the API.
 
-Get the folder key:
+Get the folder key by running:
 
 ```bash
 uip or folders list --output json
 ```
 
-Or pull it from the job/process context (e.g., `Data.folderKey` on a job status response, or from the debug output's surrounding metadata).
+Alternatively obtain it from job/process context, such as `Data.folderKey` in a job-status response or surrounding debug metadata.
 
-## 7. `UIPCLI_LOG_LEVEL=info` for debug runs
+## 7. Use `UIP_LOG_LEVEL=info` for debug runs
 
-Set `UIPCLI_LOG_LEVEL=info` on `flow debug` invocations to surface progress and diagnostic detail in the CLI output. Without it, debug runs return only the final result.
+Run debug with `UIP_LOG_LEVEL=info`:
 
 ```bash
-UIPCLI_LOG_LEVEL=info uip maestro flow debug <path-to-project-dir> --output json
+UIP_LOG_LEVEL=info uip maestro flow debug <path-to-project-dir> --output json
 ```
 
-The env var has no effect on other subcommands.
+Capture stderr as well as stdout. At `info`, stderr reports the `jobKey`, `instanceId`, and Studio Web URL. If polling exceeds its budget, stdout may contain only `Debug polling timed out after <N>s`; stderr is then the only way to identify the instance and inspect it with `uip maestro flow debug-instance incidents <instanceId>`.
 
-## 8. Global options
+Use `UIP_LOG_LEVEL`, not `UIPCLI_LOG_LEVEL`; the latter is silently ignored. `--log-level <level>` is the equivalent global flag. The setting applies to every `uip` command.
 
-All `uip` commands support `--output json|yaml|table` and `--help`. Run any command with `--help` to discover all available options for that subcommand.
+## 8. Global options
 
-```bash
-uip maestro flow <subcommand> --help
-```
+Run `uip maestro flow <subcommand> --help` to discover subcommand options. All `uip` commands support `--output json|yaml|table` and `--help`.

package/skills/uipath-maestro-flow/references/shared/file-format.md

@@ -16,6 +16,7 @@ The `.flow` file is a JSON document at `<ProjectName>.flow` in the project root.
 - [Minimal working example — dice roller](#minimal-working-example--dice-roller)
 - [entry-points.json — auto-generated, do not edit](#entry-pointsjson--auto-generated-do-not-edit)
 - [Bindings — Orchestrator resource bindings (top-level `bindings[]`)](#bindings--orchestrator-resource-bindings-top-level-bindings)
+- [Bindings — Data Fabric entity bindings](#bindings--data-fabric-entity-bindings)
 - [Bindings — connector connection binding](#bindings--connector-connection-binding)
 
 ## Top-level structure
@@ -36,7 +37,7 @@ The `.flow` file is a JSON document at `<ProjectName>.flow` in the project root.
 }
 ```
 
-> **Key order is NOT guaranteed — never anchor edits on it.** The skeleton above is illustrative; the CLI does not commit to a stable top-level key sequence or to which optional keys are present. Real flows vary: `runtime` may appear (and has been observed *before* `nodes`, not after `definitions`) or be absent entirely; `bindings`, `variables`, `solutionId`, `projectId`, and a trailing `metadata` object surface in different positions depending on CLI version and what the flow contains. When editing a `.flow`, anchor each `Edit` on the **target array's own key** (`"nodes": [`, `"edges": [`, `"definitions": [`, or `layout.nodes`) located in the text you just `Read` — never on "the key that follows X." See [greenfield.md — Anchoring parallel `.flow` Edits](../author/references/greenfield.md#anchoring-parallel-flow-edits--anchor-on-what-you-read-not-on-key-order).
+> **Key order is NOT guaranteed — never anchor edits on it.** The skeleton above is illustrative; the CLI does not commit to a stable top-level key sequence or to which optional keys are present. Real flows vary: `runtime` may appear (and has been observed *before* `nodes`, not after `definitions`) or be absent entirely; `bindings`, `variables`, `solutionId`, `projectId`, and a trailing `metadata` object surface in different positions depending on CLI version and what the flow contains. When editing a `.flow`, anchor each `Edit` on the **target array's own key** (`"nodes": [`, `"edges": [`, `"definitions": [`, or `layout.nodes`) located in the text you just `Read` — never on "the key that follows X." See [greenfield.md — Anchoring parallel `.flow` Edits](../author/greenfield.md#anchoring-parallel-flow-edits--anchor-on-what-you-read-not-on-key-order).
 
 Optional top-level `runtime`: a CLI-managed object that appears on some flows (e.g. after `uip maestro flow node add` for an HTTP/connector node) and is absent on others. It is not user-authored — do not add, remove, or anchor on it. Its presence and position are not guaranteed.
 
@@ -46,7 +47,7 @@ Optional top-level `runtime`: a CLI-managed object that appears on some flows (e
 
 `solutionId` and `projectId` may also appear at the top level — these are auto-populated by the project scaffold and packaging. Preserve the generated values.
 
-> **`bindings[]`** holds Orchestrator resource references for `uipath.core.*` resource nodes (rpa, agent, flow, agentic-process, api-workflow, hitl) and for connector-node connections. See [Bindings — Orchestrator resource bindings](#bindings--orchestrator-resource-bindings-top-level-bindings) below and the [connector plugin](../author/references/plugins/connector/impl.md) for the connector-binding shape.
+> **`bindings[]`** holds Orchestrator resource references for `uipath.core.*` resource nodes (rpa, agent, flow, agentic-process, api-workflow, hitl) and for connector-node connections. See [Bindings — Orchestrator resource bindings](#bindings--orchestrator-resource-bindings-top-level-bindings) below and the [connector plugin](../author/plugins/connector/impl.md) for the connector-binding shape.
 
 ## Project structure (generated scaffold)
 
@@ -134,7 +135,7 @@ Example — manual start trigger:
 
 ### Node outputs
 
-`$vars.<sourceNodeId>.<outputId>` resolution at runtime is driven by **`variables.nodes[]`**, not by the node instance's `outputs` block. The BPMN emitter walks `variables.nodes[]` to write the process-level `<uipath:inputOutput id="<nodeId>.<outputId>">` declarations the runtime needs; the action-node instance `outputs` block is ignored at serialization (the manifest's `outputDefinition` supplies the activity-side mapping). End / terminate nodes are the exception — their instance `outputs` block IS consumed to map workflow-level `out` variables. See [end/impl.md](../author/references/plugins/end/impl.md).
+`$vars.<sourceNodeId>.<outputId>` resolution at runtime is driven by **`variables.nodes[]`**, not by the node instance's `outputs` block. The BPMN emitter walks `variables.nodes[]` to write the process-level `<uipath:inputOutput id="<nodeId>.<outputId>">` declarations the runtime needs; the action-node instance `outputs` block is ignored at serialization (the manifest's `outputDefinition` supplies the activity-side mapping). End / terminate nodes are the exception — their instance `outputs` block IS consumed to map workflow-level `out` variables. See [end/impl.md](../author/plugins/end/impl.md).
 
 The canonical recipe for a data-producing node is therefore:
 
@@ -142,7 +143,7 @@ The canonical recipe for a data-producing node is therefore:
 - `variables.nodes[]` entry per output: `{ "id": "<nodeId>.<outputId>", "type": "object", "binding": { "nodeId": "<nodeId>", "outputId": "<outputId>" } }`.
 - Optional instance `outputs` block matching the manifest — harmless and matches the canonical examples below for clarity, but **not** what controls runtime variable visibility.
 
-Skipping `variables.nodes[]` produces a flow that passes `flow validate` but resolves `$vars.<sourceNodeId>.output` to `undefined` at runtime (MST-9972). `uip maestro flow format` regenerates `variables.nodes[]` from `nodes[]` + `definitions[]`, so always run it after structural edits — the omission becomes self-healing.
+Skipping `variables.nodes[]` produces a flow that passes `flow validate` but resolves `$vars.<sourceNodeId>.output` to `undefined` at runtime. `uip maestro flow format` regenerates `variables.nodes[]` from `nodes[]` + `definitions[]`, so always run it after structural edits — the omission becomes self-healing.
 
 When you DO author the instance `outputs` block (for documentation / parity with manifest schema), use the shape below. Each output entry has:
 
@@ -185,7 +186,7 @@ Trigger nodes (manual, scheduled, connector triggers) have a single output — n
 }
 ```
 
-End/terminate nodes do **not** use this pattern — their `outputs` maps workflow-level output variables (see the [Author end plugin reference](../author/references/plugins/end/impl.md)).
+End/terminate nodes do **not** use this pattern — their `outputs` maps workflow-level output variables (see the [Author end plugin reference](../author/plugins/end/impl.md)).
 
 ## Layout
 
@@ -221,7 +222,7 @@ Each key in `layout.nodes` is a node `id`. `flow format` creates an entry for ev
 - Skips `stickyNote` nodes from layout (they keep their custom position and size)
 - Recurses into every subflow and rewrites its `subflows[<id>].layout` map
 
-**Subflow layout is scoped.** Each subflow entry in `subflows[<id>]` has its **own** `layout.nodes` map for the nodes inside that subflow — they do NOT live in the top-level `layout.nodes`. Format handles both passes. See the [Author subflow plugin reference](../author/references/plugins/subflow/impl.md).
+**Subflow layout is scoped.** Each subflow entry in `subflows[<id>]` has its **own** `layout.nodes` map for the nodes inside that subflow — they do NOT live in the top-level `layout.nodes`. Format handles both passes. See the [Author subflow plugin reference](../author/plugins/subflow/impl.md).
 
 ## Edge — both ports required
 
@@ -269,7 +270,7 @@ Copy the returned node definition object into your `definitions` array. Dependin
 
 > The BPMN type for each node (e.g., `bpmn:StartEvent`, `bpmn:ScriptTask`) lives in the `definitions` entry copied from `uip maestro flow registry get`. Instances do not carry the BPMN type.
 
-For full details on each node (ports, inputs, outputs, when to use), see the [Author planning architecture guide](../author/references/planning-arch.md). For implementation resolution (registry lookups, connection binding, reference field resolution), see the [Author planning implementation guide](../author/references/planning-impl.md).
+For full details on each node (ports, inputs, outputs, when to use), see the [Author planning architecture guide](../author/planning-arch.md). For implementation resolution (registry lookups, connection binding, reference field resolution), see the [Author planning implementation guide](../author/planning-impl.md).
 
 Discover all available types:
 ```bash
@@ -292,7 +293,7 @@ uip maestro flow registry search <keyword>
 | `core.control.end` | — | `input` |
 | `core.logic.terminate` | — | `input` |
 
-Connector activities, agent nodes, and RPA nodes follow the same pattern as the generic action nodes above: a primary source port plus an implicit `error` port.
+Connector activities, agent nodes, and RPA nodes follow the same pattern as the generic action nodes above: a primary source port plus an implicit `error` port. The `core.datafabric.*` nodes are the exception — `input` and `output` only.
 
 Verify exact ports for any node type:
 ```bash
@@ -303,7 +304,7 @@ uip maestro flow registry get <node-type> --output json
 
 ## Implicit error port on action nodes
 
-Any node with `supportsErrorHandling: true` in the registry exposes an implicit `error` source port for catching node-level failures. This applies to HTTP, Script, Transform (all variants), connector activities, agent nodes, and RPA nodes — essentially every action node.
+Any node with `supportsErrorHandling: true` in the registry exposes an implicit `error` source port for catching node-level failures. This applies to HTTP, Script, Transform (all variants), connector activities, agent nodes, and RPA nodes — most action nodes, but not all: the `core.datafabric.*` family does not declare it and has no `error` port ([data-fabric/impl.md](../author/plugins/data-fabric/impl.md#no-error-port)). Check the registry rather than assuming.
 
 The port is **not** listed in the registry's `handleConfiguration`. Studio Web only exposes it when the source node has `inputs.errorHandlingEnabled: true`; when the flow contains an outgoing edge with `sourcePort: "error"` from that node, the serializer emits a BPMN boundary error event attached to the node. Because of this gate, `uip maestro flow validate` reports an error when a node has an outgoing `sourcePort: "error"` edge but `inputs.errorHandlingEnabled` is not `true` — so the inconsistency is caught before publish rather than surfacing as a hidden edge in Studio Web.
 
@@ -325,7 +326,7 @@ An `error` edge must not rejoin the happy path. When it does, every failure walk
 | ✗ | The next node on the happy path | Failure is invisible; downstream nodes run on missing data |
 | ✗ | The same End node the success path reaches | Success path's output mappings run against the failed node's empty output |
 | ✓ | A **distinct** End node mapping an error/status `out` variable | Caller can tell failure from success |
-| ✓ | `core.logic.terminate` | Aborts the flow when recovery is impossible — see [terminate/impl.md](../author/references/plugins/terminate/impl.md) |
+| ✓ | `core.logic.terminate` | Aborts the flow when recovery is impossible — see [terminate/impl.md](../author/plugins/terminate/impl.md) |
 | ✓ | A recovery branch that rejoins **only after obtaining valid data** — a retry that succeeded, or a fallback source that returned data | Downstream runs on real data, not on the failed node's empty output |
 
 ```text
@@ -510,6 +511,8 @@ The packaging/debug step derives `entry-points.json` from these variable declara
 
 The top-level `bindings` array (a sibling of `nodes`, `edges`, `definitions`, `variables`, `layout`) holds resource-reference indirections for **Orchestrator resource nodes** — RPA workflows, agents, flows, agentic processes, API workflows, and HITL apps.
 
+Folder-scoped Data Fabric entities also write rows into this same array, but resolve them by a **different rule**. Everything in this section describes the Orchestrator-resource form; see [Bindings — Data Fabric entity bindings](#bindings--data-fabric-entity-bindings) below for how the `Entity` kind differs.
+
 Each resource node needs two binding entries (one for `name`, one for `folderPath`). The node instance itself has no binding or context data — just `inputs`. The definition (copied verbatim from the registry) carries `model.context[]` templates like `<bindings.name>` and `<bindings.folderPath>`. At BPMN emit time the runtime rewrites those placeholders to `=bindings.<id>` by matching the placeholder name against a workflow-level binding, scoped by the definition's `model.bindings.resourceKey`.
 
 ```json
@@ -550,10 +553,28 @@ Each resource node needs two binding entries (one for `name`, one for `folderPat
 
 **Definitions stay verbatim.** Do NOT rewrite `<bindings.*>` placeholders inside the `definitions` entry — the definition is the authoring template. See "Every node type needs a `definitions` entry" in [author/CAPABILITY.md](../author/CAPABILITY.md).
 
-See each resource plugin's `impl.md` for the full JSON per node type: [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).
+See each resource plugin's `impl.md` for the full JSON per node type: [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).
 
 **Not to be confused with `bindings_v2.json`.** That file holds connector connection bindings for Integration Service nodes — a separate system. A flow may have both: a top-level `bindings[]` for resource references and a `bindings_v2.json` file for connector connections.
 
+## Bindings — Data Fabric entity bindings
+
+A **folder-scoped** Data Fabric entity (`core.datafabric.*` nodes) writes two rows into the same top-level `bindings[]` array, but they are not Orchestrator resource bindings and most of the rules in the section above do not carry over:
+
+| Aspect | Orchestrator resource nodes | Data Fabric `Entity` |
+| --- | --- | --- |
+| `resource` | `process`, `agent`, … | `Entity` — capitalized; a lowercase row is ignored by packaging, so deploy emits no override |
+| Matched by | `(resourceKey, name)` | `(resourceKey, propertyAttribute)`, falling back to `name` only when `propertyAttribute` is absent |
+| `name` holds | the placeholder name (`name` / `folderPath`) | a **display label** — the entity name, and `<entityName>Folder` for the folder row |
+| `propertyAttribute` | `name` / `folderPath` | `name` / **`folderKey`** — never `folderPath` |
+| `resourceSubType` | required, mirrors the definition | **absent** — Entity bindings have no definition-side `model.bindings` |
+
+The value is in `default` for both forms. There is also no `<bindings.{name}>` placeholder to rewrite: the entity has no definition-side `model.context[]`, and the serializer emits `bindings.<id>` tokens directly into the `=datafabric[...]` expression it builds.
+
+`folderKey` rather than `folderPath` is load-bearing. The platform's deploy-time override for an `Entity` resource carries `{ name, folderPath, folderKey }` and rewrites binding defaults by `propertyAttribute`; a `folderPath` row receives the Orchestrator FQN, which the Data Fabric query rejects even in the source org.
+
+Tenant-scoped entities need no bindings at all — they serialize as a dotted literal. See [data-fabric/impl.md — Folder-scoped entities and bindings](../author/plugins/data-fabric/impl.md#folder-scoped-entities-and-bindings) for the full JSON and when to hand-author it.
+
 ## Bindings — connector connection binding
 
 When a flow uses connector nodes, the runtime needs to know **which authenticated connection** to use for each connector. This is configured in `content/bindings_v2.json`.

package/skills/uipath-maestro-flow/references/shared/node-output-wiring.md

@@ -1,101 +1,58 @@
 # Wiring Node Outputs to Downstream Inputs
 
-How to reference one node's output (or any `$vars.*` value) from another node's input fields. This is the **single source of truth** for `=js:` expression rules in `.flow` JSON. All node-type plugins (connector, http, script, decision, end, etc.) defer to this file.
+Use this reference whenever a `.flow` JSON field references a previous node output, workflow variable, or `$metadata.*` / `$self.*`. It is the source of truth for `=js:` expressions; node-type plugins defer to it.
 
-> **Read this before** writing any field that needs to reference a previous node's output, a workflow variable, or any other `$vars.*` / `$metadata.*` value. Skipping `=js:` is the #1 cause of "the value at runtime was the literal string `vars.X.output.Id`" failures (MST-9107).
+## Core rule
 
----
+In value-typed fields, every `$vars.*`, `$metadata.*`, or `$self.*` reference must start with `=js:`. Otherwise, runtime treats the rewritten value as a literal. A missing prefix is silent: the serializer rewrites `$vars`→`vars` with or without `=js:`, so `flow validate` passes and the file looks plausible, but at runtime the BPMN engine sees a plain string and never evaluates it.
 
-## The Rule (one sentence)
+Use `$vars.<sourceNodeId>.output.<field>`—never `nodes.X.output.Y`. `<sourceNodeId>` is the producing node's `id`; `output` is the standard output port (`error` is the error port); `<field>` is the output path.
 
-**Any string that references `$vars.*`, `$metadata.*`, or `$self.*` MUST start with `=js:`. Otherwise it is a literal string at runtime.**
-
----
-
-## What Goes Wrong Without `=js:`
-
-The Flow runtime serializes string fields into BPMN. The serializer rewrites the canvas-form tokens (`$vars` → `vars`) **whether or not the `=js:` prefix is present**. This means a missing prefix is silent — `flow validate` passes, the file looks plausible, but at runtime the BPMN engine sees a plain string and never evaluates it.
-
-Three failure modes observed in agent-generated `.flow` files:
-
-| What the agent wrote | What ships to runtime | Result |
-|---|---|---|
-| `"nodes.createEntityRecord1.output.Id"` | `"nodes.createEntityRecord1.output.Id"` | Literal string — invented `nodes.` prefix has no meaning. |
-| `"$vars.createEntityRecord1.output.Id"` | `"vars.createEntityRecord1.output.Id"` | Literal string — `$vars` rewritten to `vars` but no `=js:` so never evaluated. |
-| `"=js:$vars.createEntityRecord1.output.Id"` | `"=js:vars.createEntityRecord1.output.Id"` | Evaluates correctly. |
-
-**There is no "nodes.X.output.Y" syntax.** Variable references always use `$vars.*`.
-
----
-
-## The Canonical Pattern
-
-```
-"=js:$vars.<sourceNodeId>.output.<field>"
+```text
+=js:$vars.fetchUser1.output
+=js:$vars.createRecord1.output.Id
+=js:$vars.queryRecords1.output[0].Id
+=js:$vars.fetchUser1.output.id === $vars.input.userId
+=js:$metadata.instanceId
+=js:`Hello ${$vars.userName}`
 ```
 
-- `<sourceNodeId>` — the `id` value of the node that produces the output
-- `output` — the literal string `output` (the standard output port; use `error` for errors)
-- `<field>` — the field path within the output object
+Static values do not need `=js:`. For mixed strings, use `=js:` with JavaScript template literals and `${}`.
 
-### Examples
+## Where `=js:` applies
 
-| What you want | Expression |
-|---|---|
-| The whole output object | `=js:$vars.fetchUser1.output` |
-| One field from a single-record output | `=js:$vars.createEntityRecord1.output.Id` |
-| A field from the first record of a query result (array) | `=js:$vars.queryEntityRecords1.output[0].Id` |
-| Filter on a value from a previous node | `=js:$vars.fetchUser1.output.id === $vars.input.userId` |
-| A static value (no variables) | `"HDFC Bank"` (no prefix needed) |
-| A built-in metadata value | `=js:$metadata.instanceId` |
-| A literal that contains a variable | `` =js:`Hello ${$vars.userName}` `` |
-
----
-
-## Where the Rule Applies
-
-`=js:` is **required** in every field below when the value references `$vars`, `$metadata`, or `$self`:
-
-| Node / context | Field | Required `=js:`? |
+| Context | Field | Rule |
 |---|---|---|
-| **Connector activity nodes** (`uipath.connector.<connector-key>.<activity>`) | `inputs.detail.bodyParameters.*` (all values) | **YES** |
-| | `inputs.detail.queryParameters.*` (all values) | **YES** |
-| | `inputs.detail.pathParameters.*` (all values) | **YES** |
-| **Managed HTTP** (`core.action.http.v2`) | `inputs.detail.bodyParameters.url` / `headers` / `query` / `body` — both manual and connector mode store dynamic fields here in the `.flow` JSON, regardless of how the CLI's `--detail` flag accepts them at the top level | **YES** |
-| **Custom HTTP** (`core.action.http`) | `inputs.url` / `headers` / `body` / `queryParams` (deprecated; prefer `core.action.http.v2`) | **YES** |
-| **HTTP branches** | `inputs.branches[].conditionExpression` | **NO** — already JS, do not prefix |
-| **Decision** (`core.logic.decision`) | `inputs.expression` | **NO** — already JS, do not prefix |
-| **Switch** (`core.logic.switch`) | `inputs.cases[].expression` | **NO** — already JS, do not prefix |
-| **End nodes** (`core.control.end`) | `outputs.<varId>.source` | **YES** |
-| **Variable updates** | `variables.variableUpdates.<nodeId>[].expression` | **NO** — not a string field. Write the object form `{ "type": "jsExpression", "expression": "<bare JS>", "fieldType": "<target variable type>" }`. A `=js:` string fails `flow validate` at the 1.9→1.10 migration. See [variables-and-expressions.md § Variable Updates](variables-and-expressions.md#variable-updates-variableupdates). |
-| **Loop nodes** (`core.logic.loop`) | `inputs.collection` | **YES** |
-| **Subflow nodes** (`core.subflow`) | `inputs.<inputId>.source` | **YES** |
-| **Script nodes** (`core.action.script`) | `inputs.script` body — `$vars.*` is read inside JS, no `=js:` wrapping | **NO** — the body is already JS |
-| **Voice `callContext`** (`uipath.agent.voice`, `uipath.conversational.voice.end-call`) | `inputs.callContext` — a structured binding object `{ "type": "jsExpression", "expression": "$vars.<originNodeId>.output.callContext", "fieldType": ... }`, never a bare string. `fieldType` is `"object"` on the voice agent and `"string"` on the end-call node. | **NO** — the expression sits unprefixed inside the object's `expression` field. See [author/plugins/inline-voice-agent/impl.md § The `callContext` wiring rule](../author/references/plugins/inline-voice-agent/impl.md#the-callcontext-wiring-rule). |
-| **Inline-agent prompt** (`uipath.agent.autonomous` `agent.json` `messages[].content`) | Tokens reference upstream flow nodes directly: `{{ $vars.<flowNodeId>.output[.<field>] }}` (spaced braces). Mirror in `contentTokens[]` as `{ "type": "variable", "rawString": " $vars.<flowNodeId>.output[.<field>] " }` — `rawString` must include leading and trailing space. Never `{{input.<id>}}` and never bare `{{name}}`. | **NO** — `{{ ... }}` tokens, not `=js:`. See [author/references/plugins/inline-agent/impl.md § Wiring Flow Variables into Agent Prompts](../author/references/plugins/inline-agent/impl.md#wiring-flow-variables-into-agent-prompts). Encoding note: a read `agent.json` may use the flat `__` input keys or a newer nested (dotted-key) form — author flat, read both (see the impl.md encoding note). |
-
-**Rule of thumb:** If the field is *value-typed* (anything other than a hardcoded condition), `=js:` is required for `$vars`/`$metadata`/`$self` references. The two condition fields (Decision, Switch) and the script body are the only exceptions — they are always parsed as JS regardless.
-
----
-
-## Connector Node Wiring — Quick Reference
-
-For connector nodes (`uipath.connector.*`), the most common wiring patterns:
+| Connector activity nodes (`uipath.connector.<connector-key>.<activity>`) | `inputs.detail.bodyParameters.*`, `queryParameters.*`, `pathParameters.*` | **YES** |
+| Managed HTTP (`core.action.http.v2`) | `inputs.detail.bodyParameters.url`, `headers`, `query`, `body` | **YES**; dynamic fields are stored here in `.flow` JSON in both manual and connector mode, regardless of how the CLI `--detail` flag accepts them at the top level |
+| Custom HTTP (`core.action.http`) | `inputs.url`, `headers`, `body`, `queryParams` | **YES**; deprecated, prefer `core.action.http.v2` |
+| HTTP branches | `inputs.branches[].conditionExpression` | **NO**; already JS |
+| Decision (`core.logic.decision`) | `inputs.expression` | **NO**; already JS |
+| Switch (`core.logic.switch`) | `inputs.cases[].expression` | **NO**; already JS |
+| End nodes (`core.control.end`) | `outputs.<varId>.source` | **YES** |
+| Variable updates | `variables.variableUpdates.<nodeId>[].expression` | **NO**; use `{ "type": "jsExpression", "expression": "<bare JS>", "fieldType": "<target variable type>" }`. A `=js:` string fails `flow validate` at the 1.9→1.10 migration. See [variables-and-expressions.md § Variable Updates](variables-and-expressions.md#variable-updates-variableupdates). |
+| Loop nodes (`core.logic.loop`) | `inputs.collection` | **YES** |
+| Subflow nodes (`core.subflow`) | `inputs.<inputId>.source` | **YES** |
+| Script nodes (`core.action.script`) | `inputs.script` body | **NO**; the body is already JS and reads `$vars.*` directly |
+| **Voice `callContext`** (`uipath.agent.voice`, `uipath.conversational.voice.end-call`) | `inputs.callContext` — a structured binding object `{ "type": "jsExpression", "expression": "$vars.<originNodeId>.output.callContext", "fieldType": ... }`, never a bare string. `fieldType` is `"object"` on the voice agent and `"string"` on the end-call node. | **NO** — the expression sits unprefixed inside the object's `expression` field. See [author/plugins/inline-voice-agent/impl.md § The `callContext` wiring rule](../author/plugins/inline-voice-agent/impl.md#the-callcontext-wiring-rule). |
+| **Inline-agent prompt** (`uipath.agent.autonomous` / `uipath.agent.voice` `agent.json` `messages[].content`) | Tokens use the flattened delivery key, never the flow expression: `{{input.<flowNodeId>__output__<field>}}`. The key is delivered by the node's `inputs.agentInputVariables[]` binding (`=$vars.<flowNodeId>.output.<field>`) and declared in `inputSchema.properties`. Mirror in `contentTokens[]` as `{ "type": "variable", "rawString": "input.<flowNodeId>__output__<field>" }` — `rawString` is brace-free with no added spaces, and `uip agent refresh` regenerates it, so never hand-author it. **Never a raw `{{ $vars.… }}`** (nothing rewrites agent.json prompt text — the model receives it literally) and never a bare `{{name}}`. | **NO** — `{{ ... }}` tokens, not `=js:`. See [author/plugins/inline-agent/impl.md § Wiring Flow Variables into Agent Prompts](../author/plugins/inline-agent/impl.md#wiring-flow-variables-into-agent-prompts). Encoding note: a read `agent.json` may use the flat `__` input keys or a newer nested (dotted-key) form — author flat, read both (see the impl.md encoding note). |
+
+Do not add `=js:` to Decision, Switch, or HTTP branch conditions, script bodies, variable-update expressions, or inline-agent tokens; these formats are parsed separately.
+
+## Connector and HTTP wiring
 
 ```jsonc
 "inputs": {
   "detail": {
     "method": "POST",
     "endpoint": "/v2/{entityName}/UpdateEntityRecord",
-    "pathParameters": {
-      "entityName": "BankDetails"
-    },
+    "pathParameters": { "entityName": "Entity" },
     "queryParameters": {
-      "recordId": "=js:$vars.createEntityRecord1.output.Id",
+      "recordId": "=js:$vars.createRecord1.output.Id",
       "expansionLevel": "3"
     },
     "bodyParameters": {
-      "BankName": "HDFC Bank",
+      "Name": "static-value",
       "AccountId": "=js:$vars.queryAccounts1.output[0].Id",
       "Notes": "=js:`Created from flow run ${$metadata.instanceId}`"
     }
@@ -103,37 +60,25 @@ For connector nodes (`uipath.connector.*`), the most common wiring patterns:
 }
 ```
 
-- **Static values** (`"HDFC Bank"`, `"3"`) — no prefix, written as plain JSON values.
-- **Variable references** (`$vars.X.output.Y`) — **always** wrap with `=js:`.
-- **Mixed strings** (template literals) — wrap the whole expression in `=js:` and use JS template literal syntax with `${ }`.
-
-Plugin-specific path fields are not value fields. **Always** follow the plugin reference when it says a field stores a path string. Notable exception: Transform `inputs.collection` must be a path such as `"$vars.orders.output.items"`, without `=js:`.
-
----
-
-## Anti-Patterns (Never Write These)
-
-1. **Never invent a `nodes.X.output.Y` syntax.** It does not exist. All variable references use `$vars`.
-2. **Never write `$vars.X.output.Y` without `=js:`** in an expression value field. The `$vars→vars` rewrite happens regardless of prefix, leaving you with a literal string `"vars.X.output.Y"` at runtime — looks like an expression, isn't one. For plugin path fields such as Transform `inputs.collection`, use the plugin-specific path format instead.
-3. **Never wrap conditions** (Decision, Switch, HTTP branch) in `=js:`. Those are parsed as JS automatically.
-4. **Never use `{ }` template interpolation in connector or HTTP activity inputs.** The flow-layer template runner skips these fields. The `$` is stripped and `{vars.X}` ships literally to the IS runtime. Use `=js:` and JS template literals (`` `…${$vars.X}…` ``) instead.
-5. **Never quote `=js:` itself in an expression.** `"=js:$vars.X"` is correct. `"\"=js:$vars.X\""` is a string containing the prefix.
-
----
+Plugin-specific path fields are not value fields; follow the plugin reference. In particular, Transform `inputs.collection` must be a path such as `"$vars.orders.output.items"`, without `=js:`.
 
-## Why The Engine Works This Way
+## Never do this
 
-The flow-workbench serializer (`expression-transform.ts`) walks every string in node data and rewrites `$vars` → `vars` so the BPMN runtime sees engine-form tokens. It does **not** check for the `=js:` prefix when doing this rewrite — the prefix is what tells the BPMN engine to actually evaluate the result as JavaScript. Without it, the BPMN engine treats the string as a literal value and binds it to the activity input as-is.
+1. **Never invent `nodes.X.output.Y`;** use `$vars` references.
+2. **Never write `$vars.X.output.Y` without `=js:`** in an expression value field. The `$vars→vars` rewrite still occurs, producing a literal. Use the plugin-specific format for path fields such as Transform `inputs.collection`.
+3. **Never wrap Decision, Switch, or HTTP branch conditions in `=js:`.** They already parse JS.
+4. **Never use `{ }` template interpolation in connector or HTTP activity inputs.** The flow-layer template runner skips these fields; the `$` is stripped and `{vars.X}` ships literally to the IS runtime. Use `=js:` with JS template literals instead.
+5. **Never quote `=js:` itself in an expression.** `"=js:$vars.X"` is correct; `"\"=js:$vars.X\""` is a string containing the prefix.
 
-For variable updates only, `bpmn-moddle.ts` has a fallback (`ensureJsPrefix`) that warns and auto-prefixes. There is **no equivalent fallback for connector/HTTP activity inputs** — values pass through verbatim. Always include `=js:` explicitly.
+## Runtime and migration behavior
 
----
+`expression-transform.ts` rewrites `$vars` → `vars` in every node-data string, whether or not `=js:` is present. The prefix tells the BPMN engine to evaluate the result; without it, the rewritten value remains literal. `bpmn-moddle.ts` has an `ensureJsPrefix` fallback only for variable updates. Connector and HTTP activity inputs have no equivalent fallback, so write `=js:` explicitly.
 
-## Validation Tip
+## Validation
 
-When debugging a flow whose output is the literal string `vars.X.output.Y` (or `nodes.X.output.Y`, or any other unevaluated expression) instead of the expected value:
+When a flow outputs literal `vars.X.output.Y`, `nodes.X.output.Y`, or another unevaluated expression:
 
-1. Open the `.flow` file
-2. Search for the literal token in the failed field — `grep '"vars\.' <project>.flow` or `grep '"\$vars\.' <project>.flow`
-3. For each match in `bodyParameters`, `queryParameters`, `pathParameters`, end-node `source`, or any value field, prepend `=js:`
-4. Re-run `uip maestro flow validate` and re-debug
+1. Open the `.flow` file.
+2. Search for the token: `grep '"vars\.' <project>.flow` or `grep '"\$vars\.' <project>.flow`.
+3. In `bodyParameters`, `queryParameters`, `pathParameters`, end-node `source`, and other value fields, prepend `=js:` to each variable reference.
+4. Run `uip maestro flow validate` and re-debug.