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

package/skills/uipath-maestro-flow/references/author/references/brownfield.md

@@ -1,93 +0,0 @@
-# Brownfield — Edit an Existing Flow
-
-Recipe-driven journey for targeted changes to an existing `.flow` file. Author terminates at `validate` + `format`. To publish, run, or debug after edits, see [operate/CAPABILITY.md](../../operate/CAPABILITY.md).
-
-> **Greenfield (creating a new flow) uses a different journey.** If the `.flow` file does not yet exist, see [greenfield.md](greenfield.md) instead.
-
-## Converting an existing project to Maestro
-
-A frequent request: *"Can my existing project — e.g. a low-code agent plus a coded (C#) RPA rule engine — become a Maestro flow, and what would the structure look like?"*
-
-There is **no automatic "turn this project into a flow" conversion, and you shouldn't want one.** You don't rewrite the project into a flow — you **re-host the orchestration and keep the parts**:
-
-1. **Keep the executors as-is.** Existing coded/RPA components and any existing agent stay their own artifacts. They are **not** rewritten into Maestro — they become **resource nodes** the flow calls (`uipath.core.rpa-workflow.*`, `uipath.core.agent.*`). See the relevant plugin's `planning.md`.
-2. **Lift only the orchestration into Maestro.** The control flow currently implicit in the rule engine (what runs first, what waits, what branches) becomes the explicit flow topology — trigger → steps → decisions → end.
-3. **Make every wait a first-class node.** Anything the old code did with sleeps, polling loops, or "check again later" becomes a Maestro wait/delay/HITL/`create-and-wait` node — that visibility is the whole reason to move.
-4. **Publish (or keep in-solution), then reference.** Each executor is published or kept as a sibling project so the flow's registry resolves it (`registry list --local` for in-solution).
-
-Resulting structure: a **thin flow** that is mostly trigger + waits + branches, delegating the real work to the existing RPA and agent artifacts. To author it, treat the flow as greenfield ([greenfield.md](greenfield.md)) with those artifacts discovered as resource nodes during [planning-arch.md](planning-arch.md).
-
-> **Migrate when** the project has long waits, human approvals, parallel branches, or needs per-case visibility. **Don't migrate** a short, fully-automated, fire-once script — Maestro adds orchestration overhead it won't repay. Apply the [Is Maestro the Right Home?](planning-arch.md#before-you-build-is-maestro-the-right-home) gate first.
-
-## Read this first
-
-> **Before each node you add or modify, classify it as user-owned or CLI-owned (see [CAPABILITY.md — Node ownership](../CAPABILITY.md#node-ownership--who-authors-the-node)). Connector activities, connector triggers, and `core.action.http.v2` are CLI-only — use `uip maestro flow node add` + `uip maestro flow node configure`, never Edit. Hand-writing these will fail `flow validate`.** The same risk applies when *adding* a connector node to an existing flow as when building a new one.
-
-**[editing-operations.md](editing-operations.md)** — `Edit` is the default tool for in-place changes to user-owned nodes; `Write` only when ≥70% of nodes change. For CLI-owned nodes use the relevant plugin's `impl.md` configuration workflow (`node add` + `node configure`). Read the strategy selection matrix before any modification.
-
-> **Self-check before each mutation:** name the tool you're about to use. If the answer isn't `Edit`, `Write`, or `uip maestro flow ...` — STOP and ask the user (per the dropdown question rule in [SKILL.md](../../../SKILL.md)). `python`, `node`, `jq`, `sed`, `awk`, and shell heredocs are a last resort and require explicit user approval after you've surfaced the trade-offs. See [editing-operations.md — Tool Selection Ladder](editing-operations.md#tool-selection-ladder).
-
-## Common edits
-
-For each edit, run `uip maestro flow validate` once after **all** edits are complete, then `uip maestro flow format`. Do not validate after each individual change — intermediate states are expected to be invalid.
-
-When a single edit touches more than one top-level array (e.g. insert-a-node hits `nodes`, `edges`, and `definitions`), follow the [parallel same-file Edit rules](editing-operations.md#parallel-same-file-edits) — anchor each Edit on its own array's opening key, never on top-level key order.
-
-| Edit | Description | Guide |
-|------|-------------|-------|
-| **Change a script body or node inputs** | Use `Edit` to modify the node's `inputs` in-place. Do not delete + re-add — that changes the node ID and breaks `$vars` expressions. Script nodes must return an object (`return { key: value }`). | [Edit/Write: Update node inputs](editing-operations-json.md#update-node-inputs) |
-| **Add a node between two existing nodes** | Remove the connecting edge, add the new node, wire upstream → new → downstream. | [Edit/Write: Insert a node](editing-operations-json.md#insert-a-node-between-two-existing-nodes) |
-| **Add a branch (decision node)** | Remove an edge, add a decision node, wire true/false branches. | [Edit/Write: Insert a decision branch](editing-operations-json.md#insert-a-decision-branch) |
-| **Remove a node** | Remove the node, sweep edges/definitions/variables, reconnect upstream to downstream. | [Edit/Write: Remove a node](editing-operations-json.md#remove-a-node-and-reconnect) |
-| **Remove an edge** | Find the edge ID, remove it. | [Edit/Write: Delete an edge](editing-operations-json.md#delete-an-edge) |
-| **Add a workflow variable** | Use `Edit` to modify `variables.globals` in the `.flow` file (Edit-only). For `out` variables, map on every End node. See [shared/variables-and-expressions.md](../../shared/variables-and-expressions.md). | [Edit/Write: Add a workflow variable](editing-operations-json.md#add-a-workflow-variable) |
-| **Update a state variable** | Use `Edit` to add a `variableUpdates` entry for `inout` variables (Edit-only). See [shared/variables-and-expressions.md](../../shared/variables-and-expressions.md). | [Edit/Write: Add a variable update](editing-operations-json.md#add-a-variable-update) |
-| **Create a subflow** | Add a `core.subflow` parent node + `subflows.{nodeId}` with nested nodes/edges/variables (`Edit`-only, or `Write` if scaffolding from template). | [Edit/Write: Create a subflow](editing-operations-json.md#create-a-subflow) + [subflow/impl.md](plugins/subflow/impl.md) |
-| **Add a scheduled trigger** | Replace `core.trigger.manual` with `core.trigger.scheduled`. | [Edit/Write: Replace trigger](editing-operations-json.md#replace-manual-trigger-with-scheduled-trigger) + [scheduled-trigger/impl.md](plugins/scheduled-trigger/impl.md) |
-| **Add a connector trigger** | Remove manual trigger, add connector trigger, configure with connection. | [CLI: Replace trigger](editing-operations-cli.md#replace-manual-trigger-with-connector-trigger) + [connector-trigger/impl.md](plugins/connector-trigger/impl.md) |
-| **Add a resource node** | Discover via registry (`--local` for in-solution, or tenant registry for published), add via `Edit`, wire edges. | Relevant plugin's `impl.md` + [editing-operations-json.md](editing-operations-json.md) |
-| **Add an inline agent node** | Embed a `uipath.agent.autonomous` node with an inline agent definition living inside the flow project. | [inline-agent/planning.md](plugins/inline-agent/planning.md) for selection vs a published agent, [inline-agent/impl.md](plugins/inline-agent/impl.md) for scaffolding, direct `.flow` JSON structure, and validation. |
-| **Add voice nodes** | Turn a flow into a phone conversation: a `uipath.agent.voice` inline conversational agent wired to a live call, plus the trigger, create-call, and end-call nodes. Binding an inbound number happens at deploy time, not in the `.flow`. | [inline-voice-agent/planning.md](plugins/inline-voice-agent/planning.md) for the two topologies and trunk requirements, [inline-voice-agent/impl.md](plugins/inline-voice-agent/impl.md) for node JSON, `callContext` wiring, and number binding. |
-| **Add a HITL QuickForm node** | Insert a human approval/review/enrichment checkpoint. Wire the `completed` port after adding. | [Edit/Write: Add a node](editing-operations-json.md) + [hitl/impl.md](plugins/hitl/impl.md) |
-
-The table intentionally routes OOTB structural CRUD to Edit/Write only. There is no CLI opt-in path for non-carve-out flow graph edits.
-
-## After edits
-
-1. **Validate** — `uip maestro flow validate <ProjectName>.flow --output json`. Fix any errors and re-validate.
-2. **Format** — `uip maestro flow format <ProjectName>.flow --output json`. Required before publish or debug (see "Always run `flow format` after edits" in [the Author capability index](../CAPABILITY.md)) — without format, hand-edited or stale `layout` data renders as misshapen rectangles in Studio Web.
-
-## "Refusing to serialize a vX workflow" — migrate first
-
-If `flow format`, `flow debug`, or `flow pack` fails with `[inMemoryWorkflowToFileFormat] Refusing to serialize a vX workflow to the v<current> file format`, the `.flow` file predates the current schema version. Recover with one command:
-
-```bash
-uip maestro flow migrate <ProjectName>.flow --output json
-```
-
-`migrate` is lossless — it walks the per-version migration chain (e.g. `=js:` expression strings become rich expression objects) and bumps the file to the current version. Re-run `flow format` and `flow validate` afterward; both should now pass. **A passing `flow validate` does NOT imply `format`/`debug`/`pack` will pass** — `validate` never re-serializes the workflow, so it skips the version guard those commands enforce. When you see the refusal, always migrate; never assume the edit was wrong.
-
-## Completion Output
-
-When you finish editing the flow, report to the user:
-
-1. **File path** of the `.flow` file edited
-2. **What changed** — summary of nodes/edges added, removed, or modified
-3. **Validation status** — whether `flow validate` passes (or remaining errors if unresolvable)
-4. **Format status** — confirm `flow format` was run
-5. **Mock placeholders** — list any `core.logic.mock` nodes that need to be replaced
-6. **Missing connections** — any connector nodes that need connections the user must create
-7. **What's next** — ask the user, presenting the dropdown below (see the dropdown question rule in [SKILL.md](../../../SKILL.md))
-
-### What's next dropdown
-
-Authoring terminates here. Each option below hands off to Operate — read [operate/CAPABILITY.md](../../operate/CAPABILITY.md) for the command sequence.
-
-| Option | What it does |
-| --- | --- |
-| **Publish to Studio Web** (default) | Push the solution to Studio Web so the user can visualize, edit, and publish from the browser. |
-| **Debug the solution** | Execute the flow end-to-end against real systems. Confirm consent first — debug has real side effects (see the consent-before-debug rule in [SKILL.md](../../../SKILL.md)). |
-| **Deploy to Orchestrator** | Pack and publish directly to Orchestrator (bypasses Studio Web). Only when explicitly chosen — see [/uipath:uipath-platform](/uipath:uipath-platform). |
-| **Something else** | Last option. Accept free-form string input and act on it. |
-
-Do not run any of these actions without explicit user selection. Once the user picks an option, read [operate/CAPABILITY.md](../../operate/CAPABILITY.md) and follow that capability's flow — do not run operate commands from inside this doc.

package/skills/uipath-maestro-flow/references/author/references/editing-operations-json.md

@@ -1,545 +0,0 @@
-# Flow Editing Operations — Edit / Write Strategy
-
-All flow file modifications via the `Edit` and `Write` tools (read-modify-write of the `.flow` JSON file). This strategy gives full control over every field but requires manual management of definitions, variables, and edge integrity.
-
-> **Apply every recipe in this file with the `Edit` tool (default) or the `Write` tool (only when ≥70% of nodes change).** Each recipe shows the JSON payload that goes into the `new_string` parameter of an `Edit` call. `python`, `node`, `jq`, `sed`, `awk`, and shell heredocs are a last resort for mutations and require explicit user approval after you've surfaced the trade-offs — see SKILL.md rule on scripted mutations and [editing-operations.md — Why not Python / Node / jq / sed?](editing-operations.md#why-not-python--node--jq--sed).
->
-> **When to use this strategy:** Edit / Write is required for all non-carve-out `.flow` edits. Use Flow CLI only for connector activity, connector-trigger, and managed HTTP carve-outs documented by their plugins. Inline-agent project lifecycle uses `uip agent init --inline-in-flow` / `uip agent refresh --inline-in-flow` / `uip agent validate --inline-in-flow`, but the `uipath.agent.autonomous` node and edges are authored with this guide. See [editing-operations.md](editing-operations.md) for the strategy selection matrix.
-
----
-
-## Key Differences from CLI
-
-When editing the `.flow` file with `Edit` / `Write`, **you** are responsible for everything the CLI normally handles:
-
-| Concern | CLI handles | Edit / Write — you must |
-|---------|------------|------------------------|
-| Definitions | Auto-copied from registry cache | Copy the returned node definition object from `uip maestro flow registry get` into `definitions` array |
-| Node variables | Auto-added to `variables.nodes` | Add output variable entries manually (or accept that `variables.nodes` may need regeneration) |
-| Edge cleanup on delete | Auto-removes connected edges | Find and remove all edges referencing the deleted node |
-| Orphan cleanup | Auto-removes unused definitions and orphaned bindings | Remove definitions no longer referenced by any node; remove connector bindings only when no remaining node uses that connector |
-| `targetPort` | Auto-set | Set `targetPort` on every edge (validate rejects without it) |
-| `bindings_v2.json` | Auto-managed by `node configure` | Prefer the CLI carve-out for connector/managed HTTP configuration; if using the documented fallback, author top-level `.flow` `bindings[]` and only touch generated files when the plugin explicitly says to |
-
----
-
-## Pre-flight Checklist
-
-Before editing the `.flow` file, ensure each of the following is handled. These are the concerns the CLI used to manage automatically; under the Edit / Write default, **you** are responsible for them.
-
-1. **Locate the canonical `.flow` file.** Before any `Edit` / `Write`, find the flow project directory — it is the directory that contains `project.uiproj`. The canonical `.flow` lives **next to** that `project.uiproj`, not at the solution root. Commands like `uip solution init <Name>` + `uip maestro flow init <Name>` create nested paths (`<Name>/<Name>/project.uiproj`); the `.flow` you must edit is `<Name>/<Name>/<Name>.flow`, not `<Name>/<Name>.flow`. Run `find . -name project.uiproj -type f` and pin every `Edit` / `Write` call to the sibling file. `uip maestro flow validate <PATH>.flow` will accept a misplaced file, so validation alone does **not** confirm the right target — only the colocation with `project.uiproj` does.
-2. **Definitions and versions.** For every new node type, run `uip maestro flow registry get <type> --output json`. Copy the returned node definition object **verbatim** into `definitions[]` — one entry per unique `type:typeVersion`. Depending on CLI/plugin version, the node definition may appear as `Data.Node` or as the top-level object containing fields such as `nodeType`, `version`, and `handleConfiguration`; copy that node object, not the surrounding `Result` / `Code` envelope. Then set each node instance's `typeVersion` to match the copied definition's `version` exactly — string match, no normalization. Never hand-write or paraphrase definitions (see "Every node type needs a `definitions` entry" in [the Author capability index](../CAPABILITY.md)). For node types with a documented `uip maestro flow node add` carve-out (managed HTTP, connector activities, connector triggers), use the CLI — see [http/impl.md — Step 1](plugins/http/impl.md#add-the-node).
-3. **Unique node ID.** Pick a camelCase ID that does not collide with existing node IDs. Prefer meaningful names (`fetchUsers`, `filterActive`) since they become part of every `$vars.<nodeId>.*` expression.
-4. **`sourcePort` and `targetPort` on every edge.** Omitting `targetPort` is the #1 validation error (see "`targetPort` is required on every edge" in [the Author capability index](../CAPABILITY.md)). Use `sourcePort`, never `sourceHandle`; `sourceHandle` is not part of the `.flow` edge schema and produces a precise schema error such as `[error] [edges[N].sourcePort] Invalid input: expected string, received undefined` (the path tells you exactly which edge entry is missing the `sourcePort` key). Look up ports in the relevant plugin's `planning.md` or in [file-format.md — Standard ports](../../shared/file-format.md). If an edge uses `sourcePort: "error"`, the source node must also have `inputs.errorHandlingEnabled: true`; `uip maestro flow format` self-heals this, but direct JSON edits must set it. Only those nodes — setting the flag on a node with no `error` edge swallows its failures (see [file-format.md — Default: off](../../shared/file-format.md#default-off--enable-only-for-a-failure-the-flow-actually-handles)).
-5. **Node outputs block (End / Terminate only).** End-style nodes consume their `outputs` block at runtime to map workflow-level `out` variables — see [end/impl.md](plugins/end/impl.md). For action / trigger nodes the instance `outputs` block is **not** consumed by BPMN serialization; the runtime reads the manifest's `outputDefinition` instead. Authoring an action-node `outputs` block matching the manifest is fine and is what the canonical examples show, but adding it does **not** make `$vars.<sourceNodeId>.output` resolve downstream — that contract is `variables.nodes[]` (next item).
-6. **`variables.nodes[]` (REQUIRED for every data-producing node — this is what powers `$vars.X.output`).** For each data-producing node, add an entry per output (`output` for action / trigger nodes, plus `error` for action nodes). The BPMN emitter walks `variables.nodes[]` to write the process-level `<uipath:inputOutput id="<nodeId>.<outputId>">` declarations the runtime needs; without them, downstream `$vars.<sourceNodeId>.output` resolves to `undefined` even though `flow validate` passes (MST-9972). The shape per entry: `{ "id": "<nodeId>.<outputId>", "type": "object", "binding": { "nodeId": "<nodeId>", "outputId": "<outputId>" } }`. After your edits, **`uip maestro flow format` regenerates this block from `nodes[]` + `definitions[]`** — running format makes any direct-authored omission self-healing.
-7. **On delete — cascade manually.** Remove the node from `nodes`. Then sweep `edges[]` for any with matching `sourceNodeId`/`targetNodeId`. Then prune `definitions[]` if this was the last user of the type. Then check `bindings_v2.json` — but only remove a connector binding if no remaining node uses the same connector (bindings are shared at the connector level).
-
-> **Anti-pattern: editing a `.flow` that is not colocated with `project.uiproj`.**
-> A `.flow` file outside the flow project directory is invisible to `uip maestro flow debug`, to the Studio solution, and to any checker that discovers the project via `**/project.uiproj`. It will still pass `uip maestro flow validate <PATH>.flow` because that command only checks JSON-schema correctness of the file you hand it — it does not verify the file is the project's canonical flow. Always edit the `.flow` that sits next to `project.uiproj`.
-
----
-
-## Edit Tooling
-
-Direct JSON edits use four mechanics. Pick by operation class — same pattern, different tool. The CLI has no `node update` command (see [editing-operations-cli.md § Operations Not Supported by CLI](editing-operations-cli.md#operations-not-supported-by-cli)), so structural mutations of node `inputs`, definition swaps, and array splices are done through direct `.flow` authoring.
-
-| Operation class | Mechanic | When to use |
-|----|----|----|
-| Surgical leaf-value change (single string/number/bool) | `Edit` | One unique substring in the file. Whitespace-sensitive — re-`Read` first if the file was just rewritten. |
-| New node, new edge, new definition entry, new variable | `Read` whole file → reconstruct in chat → `Write` whole file | Adding self-contained sub-objects. Preserves field order; risks dropping fields on files >1000 lines. |
-| Replace nested object in array; insert nested fields; idempotent splice | `Edit` / `Write`; `python3` heredoc only after explicit user approval | Surgical structural mutation. Prefer direct authoring first; use a script only when the user has accepted the state-bypass and diff-review trade-off. |
-| One-shot extraction or single-field mutation from CLI JSON output | `jq` | Reading `--output json` results. Faster than spawning Python for read-only paths. |
-
-### Canonical heredoc recipe
-
-When the user explicitly approves a scripted structural rewrite, use this shape. Substitute the node-type guard, the field path, and the new value:
-
-```bash
-python3 - <<'PY'
-import json
-flow = json.load(open("<FILE>.flow"))
-# Mutate flow here — splice arrays, set nested fields, replace objects.
-# Example: insert/overwrite a field on every node of a given type
-for node in flow["nodes"]:
-    if node.get("type") == "<NODE_TYPE>":
-        node.setdefault("inputs", {})["<FIELD>"] = "<VALUE>"
-json.dump(flow, open("<FILE>.flow", "w"), indent=2)
-PY
-uip maestro flow validate <FILE>.flow --output json
-```
-
-`json.dump(..., indent=2)` matches the file's existing 2-space indent — `flow format` normalizes layout but does not re-indent unrelated structure, so preserve the canonical 2-space indent on writes.
-
-### `--output-filter` for extracting CLI JSON
-
-Read-only extractions on `--output json` results — use the CLI's built-in JMESPath filter, no external parser needed. Expressions start at the `Data` envelope (no `Data.` prefix). See [shared/cli-conventions.md §3](../../shared/cli-conventions.md#3-prefer---output-filter-for-extraction) for the full pattern.
-
-```bash
-uip solution upload --output json --output-filter "Url"
-uip maestro flow registry get <node-type> --output json --output-filter "Node"
-```
-
-Reach for `jq` / `python3` only when JMESPath cannot express the operation (multi-step joins, format conversion, conditional output computed from multiple fields).
-
-### Why scripting is approval-gated
-
-- `Edit` on nested JSON is fragile. Indented sibling fields, trailing commas, and quote styles all break the exact-match constraint. One byte of drift, no edit applied.
-- Whole-file `Write` is lossy — every field has to round-trip through chat, and large `.flow` files (>500 lines once layout, definitions, and bindings settle) blow the read budget. Use `Write` only for new flows or full reshapes; on a flow with connector / managed-HTTP nodes it silently clobbers CLI-owned `bindings[]` / `inputs.detail` (invisible to `flow validate`) — `Edit` in place instead.
-- `python3 -c` / heredoc is a fallback for structural rewrites that are too brittle for `Edit` and too large for safe whole-file `Write`. Use it only after surfacing the trade-offs and getting explicit user approval.
-
----
-
-## Primitive Operations
-
-> **Multiple `Edit`s in one turn?** Several recipes below touch more than one top-level array at once (Add a node hits `nodes[]`, `definitions[]`, `variables.nodes`, and `layout.nodes`). Same-file `Edit`s serialize and must not share an anchor — anchor each on its target array's OWN opening key (never on top-level key order, which is not guaranteed) and watch for `"nodes": [` / `"edges": [` recurring inside `definitions[]` and `subflows.<id>`. Full rules: [editing-operations.md — Parallel same-file Edits](editing-operations.md#parallel-same-file-edits).
-
-### Add a node
-
-**Tool:** `Edit` (insert into `nodes[]` + `definitions[]` + `variables.nodes` + `layout.nodes`)
-
-1. Run `uip maestro flow registry get <node-type> --output json` and copy the returned node definition object (`Data.Node` or the top-level node object, depending on CLI/plugin version)
-2. Use `Edit` to add a node entry to the `nodes` array:
-
-```json
-{
-  "id": "<UNIQUE_NODE_ID>",
-  "type": "<NODE_TYPE>",
-  "typeVersion": "<DEFINITION_VERSION>",
-  "display": { "label": "<LABEL>" },
-  "inputs": {},
-  "outputs": {
-    "error": {
-      "type": "object",
-      "description": "Error information if the <node type> fails",
-      "source": "=Error",
-      "var": "error"
-    }
-  }
-}
-```
-
-> **Loop body nodes — set `parentId`.** When adding a node inside a `core.logic.loop` body, add `"parentId": "<LOOP_NODE_ID>"` to the node object. Without it, the runtime executes the node outside the loop context — `$vars.<loopId>.currentItem` is inaccessible and per-iteration state does not update. This applies to **every** node type inside the loop (HTTP, script, connector, etc.). See [loop/impl.md](plugins/loop/impl.md).
-
-**Orchestrator-job nodes (api-workflow, rpa-workflow, agent, agentic-process, function): declare `error` only (`source: "=Error"`) — `output` is derived.** The converter copies an authored `source` verbatim there, and injects `{name: "output", type: "jsonSchema", source: "=this", var: "output"}` only when a non-empty `outputs` omits `output`. So authoring `output` with `"=result.response"` on one of those leaves `$vars.{nodeId}.output` null at runtime while `flow validate` passes. Every other node type ignores the instance `outputs` block (DAP nodes — connector, HTTP, triggers — `Intsvc.*` — and script/transform take outputs from the manifest; inline agents have theirs overwritten; queue nodes never read it), so `error`-only stays a safe default everywhere and a manifest-matching `output` entry is harmless documentation. Downstream reads `$vars.{nodeId}.output` in every case.
-
-> **`display` is required on every node** — including control-flow nodes (`core.control.end`, `core.logic.terminate`) where it may feel optional. Omitting it produces a vague `[(root)] Schema validation failed: Invalid input: expected object, received undefined` from `uip maestro flow validate`, which does NOT pinpoint the missing field. Always include `"display": { "label": "<label>" }` on every node, even bare end nodes. See [file-format.md — Node instance](../../shared/file-format.md#node-instance).
-
-> **What actually makes `$vars.<sourceNodeId>.output` resolve is `variables.nodes[]` (step 4 below), not the instance `outputs` block.** The BPMN emitter ignores the action-node instance `outputs` block at serialization — it reads the manifest's `outputDefinition` for the activity-side mapping and reads `variables.nodes[]` for the process-level `<uipath:inputOutput>` declarations downstream nodes depend on. Authoring an `outputs` block matching the manifest is fine (the canonical examples include it for documentation), but you can skip it on action and trigger nodes. **Exception — Orchestrator-job nodes** (api-workflow, rpa-workflow, agent, agentic-process, function): the converter DOES read their instance `outputs` and copies each `source` verbatim into `model.outputDefinition`, so a wrong `source` there (e.g. `=result.response`) breaks the downstream variable. Declare `error` only and let `output` be injected. End / terminate nodes are different — see [end/impl.md](plugins/end/impl.md). The standard patterns are in [file-format.md — Node outputs](../../shared/file-format.md#node-outputs). **Always run `uip maestro flow format` after structural edits — it regenerates `variables.nodes[]` from the current node graph (MST-9972).**
-
-> **No instance `model` block.** BPMN type, serviceType, event definition, and binding/context templates are provided by the definition in `definitions[]` (copied verbatim from the registry). Instance-specific identity fields live under `inputs`: `entryPointId`/`isDefaultEntryPoint` for triggers, `color`/`content` for sticky notes, and `source` for every inline-agent-related node — `uipath.agent.autonomous` plus every attached `uipath.agent.resource.*` node (tool, escalation, context) writes the inline agent's `projectId` (autonomous) or resource UUID (resource nodes) at `inputs.source`. Their definitions declare `model.source: true`; flow-core hoists source identity onto the instance — no `"model": { "source": ... }` block is written. See [file-format.md — Instance-specific identity fields](../../shared/file-format.md#instance-specific-identity-fields).
-
-> **No `ui` block on nodes.** Do NOT put `position`, `size`, or `collapsed` on the node. Add a layout entry instead (step 5).
-
-3. Add the definition to `definitions` (if this type is not already present):
-   - Paste the returned node definition object from the registry response
-   - Set the node instance `typeVersion` to the pasted definition's exact `version`
-   - One definition per unique `type:typeVersion` — not one per node instance
-
-> **Resource nodes — extra step.** If the node type is one of `uipath.core.rpa-workflow.*`, `uipath.core.agent.*`, `uipath.core.flow.*`, `uipath.core.agentic-process.*`, `uipath.core.api-workflow.*`, or `uipath.core.human-task.*`:
-> 1. The instance stays minimal — just `inputs`/`outputs`/`display`.
-> 2. Add matching entries to the top-level `bindings[]` array (sibling of `nodes`/`edges`/`definitions`): two entries per resource (`name` + `folderPath`) with `resourceKey` exactly matching the definition's `model.bindings.resourceKey`.
->
-> The BPMN emit layer rewrites the definition's `<bindings.{name}>` placeholders to `=bindings.{id}` by matching on `(resourceKey, name)`. Without matching entries in top-level `bindings[]`, `uip maestro flow validate` passes but `uip maestro flow debug` fails with "Folder does not exist or the user does not have access to the folder." The definition stays verbatim from the registry — do NOT rewrite `<bindings.*>` placeholders inside it. See the relevant plugin's `impl.md` for the exact JSON.
-
-4. Add node output variables to `variables.nodes` (REQUIRED — the BPMN emitter reads this to declare process-level variables. `uip maestro flow format` regenerates this block from `nodes[]` + `definitions[]`, so running format after edits will self-heal an omitted entry; running validate alone does not. Without it, downstream `$vars.<sourceNodeId>.output` resolves to `undefined` at runtime — MST-9972):
-
-```json
-[
-  {
-    "id": "<NODE_ID>.output",
-    "type": "object",
-    "description": "<Output description>",
-    "binding": {
-      "nodeId": "<NODE_ID>",
-      "outputId": "output"
-    }
-  },
-  {
-    "id": "<NODE_ID>.error",
-    "type": "object",
-    "description": "Error information if the node fails",
-    "binding": {
-      "nodeId": "<NODE_ID>",
-      "outputId": "error"
-    }
-  }
-]
-```
-
-5. Add a placeholder layout entry for the node in the top-level `layout.nodes` object — `flow format` rewrites both `position` and `size` on save:
-
-```json
-"layout": {
-  "nodes": {
-    "<UNIQUE_NODE_ID>": {
-      "position": { "x": 0, "y": 0 },
-      "size": { "width": 96, "height": 96 },
-      "collapsed": false
-    }
-  }
-}
-```
-
-**Layout rule:** Don't compute coordinates by hand — run `uip maestro flow format <ProjectName>.flow` after edits. Format arranges nodes horizontally, sets each node's size by its canvas shape (inline agents → 288×96, containers → 560×320, everything else → 96×96), and recurses into subflows.
-
-### Delete a node
-
-**Tool:** `Edit` (remove from `nodes[]` + dependent edges + orphaned definitions + `variables.nodes` + `variableUpdates`)
-
-1. Use `Edit` to remove the node object from `nodes`
-2. Remove **all edges** where `sourceNodeId` or `targetNodeId` equals the node's `id`
-3. If no other node uses the same `type`, remove the definition from `definitions`
-4. Remove the node's entry from `variables.nodes`
-5. Remove any `variableUpdates` entries keyed by the node's `id`
-6. If the node is a connector node, remove its binding from `bindings_v2.json` **only if no other node in the flow uses the same connector**. Bindings are shared at the connector level (keyed by `metadata.Connector`), not per node.
-
-### Add an edge
-
-**Tool:** `Edit` (insert into `edges[]` with `targetPort`)
-
-Use `Edit` to add an edge object to the `edges` array:
-
-```json
-{
-  "id": "edge_<SOURCE_NODE_ID>_<SOURCE_PORT>_<TARGET_NODE_ID>_<TARGET_PORT>",
-  "sourceNodeId": "<SOURCE_NODE_ID>",
-  "sourcePort": "<SOURCE_PORT>",
-  "targetNodeId": "<TARGET_NODE_ID>",
-  "targetPort": "<TARGET_PORT>"
-}
-```
-
-**Critical:** the edge `id` MUST match the pattern above — never a bare UUID or any id starting with a digit.
-
-**Critical:** `targetPort` is required on every edge. Omitting it produces a validation error.
-
-**Critical:** the outgoing port field is named `sourcePort`, not `sourceHandle`. `sourceHandle` is a UI/runtime term, not valid `.flow` JSON.
-
-**Critical:** for `sourcePort: "error"`, also set `inputs.errorHandlingEnabled: true` on the source node. Without the flag, Studio Web hides the source handle and `uip maestro flow validate` fails. The converse is equally strict: **never set the flag on a node that has no `error` edge** — it suppresses the node's fault and the run reports success while the work failed. See [file-format.md — Default: off](../../shared/file-format.md#default-off--enable-only-for-a-failure-the-flow-actually-handles).
-
-**Edge ID:** `edge_<SOURCE_NODE_ID>_<SOURCE_PORT>_<TARGET_NODE_ID>_<TARGET_PORT>`.
-
-See each plugin's `planning.md` or [file-format.md — Standard ports](../../shared/file-format.md) for port names by node type.
-
-### Delete an edge
-
-**Tool:** `Edit`
-
-Use `Edit` to remove the edge object from the `edges` array by its `id`.
-
-### Update node inputs
-
-**Tool:** `Edit` (in-place value tweak — preserves node ID and `$vars`)
-
-Use `Edit` to modify the `inputs` object of the target node in-place. No need to delete and re-add.
-
-```json
-{
-  "id": "checkStatus",
-  "type": "core.logic.decision",
-  "inputs": {
-    "expression": "$vars.fetchData.output.statusCode === 200"
-  }
-}
-```
-
-This is a key advantage of `Edit` — input updates are a single field edit, not the delete + re-add pattern required by the CLI.
-
----
-
-## Variable Operations
-
-These are `Edit`-only — the CLI does not support variable management. There is no fallback strategy.
-
-### Add a workflow variable
-
-**Tool:** `Edit`
-
-Use `Edit` to add an entry to `variables.globals`:
-
-```json
-{
-  "id": "<VARIABLE_ID>",
-  "direction": "in|out|inout",
-  "type": "string|number|boolean|object|array|file",
-  "defaultValue": "<OPTIONAL_DEFAULT>",
-  "description": "<OPTIONAL_DESCRIPTION>"
-}
-```
-
-For `out` variables: add output mapping to **every reachable End node** (see below).
-For `inout` variables: add `variableUpdates` entries on nodes that modify the state.
-Attachment-carrying inputs MUST use `"type": "file"` — `"object"` breaks attachment binding and faults IxP extraction with `[430002]` (see [plugins/ixp/impl.md#debug](plugins/ixp/impl.md#debug)).
-
-See [variables-and-expressions.md](../../shared/variables-and-expressions.md) for the full schema, type system, and scoping rules.
-
-### Add output mapping on an End node
-
-**Tool:** `Edit`
-
-Use `Edit` to map every `out` variable in `variables.globals` on every reachable End node:
-
-```json
-{
-  "id": "doneSuccess",
-  "type": "core.control.end",
-  "typeVersion": "1.0.0",
-  "display": { "label": "Done" },
-  "inputs": {},
-  "outputs": {
-    "<VARIABLE_ID>": {
-      "source": "=js:<EXPRESSION>"
-    }
-  }
-}
-```
-
-Each key in `outputs` must match a variable `id` from `variables.globals` where `direction: "out"`. Missing mappings cause silent runtime failures.
-
-### Add a variable update
-
-**Tool:** `Edit`
-
-Use `Edit` to add an entry to `variables.variableUpdates.<NODE_ID>`:
-
-```json
-{
-  "variables": {
-    "variableUpdates": {
-      "<NODE_ID>": [
-        {
-          "variableId": "<INOUT_VARIABLE_ID>",
-          "expression": {
-            "type": "jsExpression",
-            "expression": "<BARE_JS_NO_PREFIX>",
-            "fieldType": "<TARGET_VARIABLE_TYPE>"
-          }
-        }
-      ]
-    }
-  }
-}
-```
-
-Only `inout` variables can be updated. `in` variables are read-only.
-
-> **`expression` is an object here, not a `=js:` string** — unlike `inputs` and End-node `outputs[].source`, which still accept the string form. Set `fieldType` to the target variable's declared `type` (`integer` → `number`); `flow validate` does not cross-check it against the variable, so a mismatch passes silently. The string form does not: it fails with `[MIGRATION] Workflow migration failed at 1.9→1.10 … Offending field(s): variables.variableUpdates.<NODE_ID>.0.expression`.
-
-> **There is no CLI command for variable updates.** `Edit` is the only way to write them.
-
----
-
-## Composite Operations
-
-### Insert a node between two existing nodes
-
-**Tool:** `Edit` × 3 (delete old edge, add new node, add 2 new edges)
-
-1. Use `Edit` to remove the edge connecting the two nodes from the `edges` array
-2. Use `Edit` to add the new node to `nodes` (with definition in `definitions`)
-3. Use `Edit` to add two new edges:
-   - upstream → new node (using upstream's output port → new node's `input`)
-   - new node → downstream (using new node's output port → downstream's `input`)
-
-### Insert a decision branch
-
-**Tool:** `Edit` × 3 (delete old edge, add decision node, add 3 new edges)
-
-1. Use `Edit` to remove the edge where the branch should go
-2. Use `Edit` to add the decision node to `nodes` with `inputs.expression`
-3. Use `Edit` to add three edges:
-   - upstream → decision (target port: `input`)
-   - decision → true branch (source port: `true`, target port: `input`)
-   - decision → false branch (source port: `false`, target port: `input`)
-
-### Remove a node and reconnect
-
-**Tool:** `Edit` × 4 (delete node, sweep edges, prune orphan definitions, add reconnect edge)
-
-1. Record the node's upstream and downstream connections from `edges`
-2. Use `Edit` to remove the node from `nodes`
-3. Use `Edit` to remove all edges referencing the node
-4. Use `Edit` to clean up orphaned definitions
-5. Use `Edit` to add a new edge connecting upstream directly to downstream
-
-### Replace a mock with a real resource node
-
-**Tool:** `Edit` (multiple calls — replace node, edges, definitions, bindings, variables)
-
-1. Get the resource node manifest — check in-solution first, then tenant registry:
-   ```bash
-   # In-solution (preferred — no login required):
-   uip maestro flow registry get "<RESOURCE_NODE_TYPE>" --local --output json
-
-   # Tenant registry (if not in solution):
-   uip maestro flow registry get "<RESOURCE_NODE_TYPE>" --output json
-   ```
-2. Record the mock node's connected edges
-3. Remove the mock node from `nodes`
-4. Remove all edges referencing the mock
-5. Add the real resource node to `nodes` with:
-   - Correct `type` and `typeVersion`
-   - `inputs` with resolved field values
-   - `outputs` block (action nodes: `output` + `error`)
-   - No `model` block — binding/context templates come from the definition
-6. Copy the definition from registry into `definitions`
-7. Add entries to the top-level `bindings[]` array — two per resource (`name` + `folderPath`), with `resourceKey` matching the definition's `model.bindings.resourceKey`
-8. Re-create all edges using the new node's `id`
-9. Add node variables to `variables.nodes`
-10. Validate: `uip maestro flow validate <ProjectName>.flow --output json`
-
-### Replace manual trigger with scheduled trigger
-
-**Tool:** `Edit` × 2 (start node in-place, swap definition)
-
-Use `Edit` to modify the start node in-place (no delete/re-add needed):
-
-1. Change `type` from `core.trigger.manual` to `core.trigger.scheduled`
-2. Add timer inputs (keep the existing `entryPointId` in `inputs`):
-   ```json
-   "inputs": {
-     "entryPointId": "<existing-uuid>",
-     "timerType": "timeCycle",
-     "timerPreset": "R/PT1H"
-   }
-   ```
-3. Update the definition in `definitions`:
-   - Remove the `core.trigger.manual` definition
-   - Add the `core.trigger.scheduled` definition from `uip maestro flow registry get core.trigger.scheduled --output json` (the new definition carries the correct `model.type` and `model.eventDefinition`)
-4. Validate: `uip maestro flow validate <ProjectName>.flow --output json`
-
-### Create a subflow
-
-**Tool:** `Edit` (or `Write` if scaffolding from template)
-
-1. Use `Edit` to add a `core.subflow` parent node to `nodes`:
-   ```json
-   {
-     "id": "<SUBFLOW_NODE_ID>",
-     "type": "core.subflow",
-     "typeVersion": "1.0.0",
-     "display": { "label": "<LABEL>" },
-     "inputs": {
-       "<IN_VAR>": "=js:<EXPRESSION>"
-     },
-     "outputs": {
-       "error": {
-         "type": "object",
-         "description": "Error information if the subflow fails",
-         "source": "=Error",
-         "var": "error"
-       }
-     }
-   }
-   ```
-
-2. Use `Edit` to add a `subflows.<SUBFLOW_NODE_ID>` entry with its own nodes, edges, variables, and layout:
-   ```json
-   {
-     "subflows": {
-       "<SUBFLOW_NODE_ID>": {
-         "nodes": [
-           { "id": "sfStart", "type": "core.trigger.manual", ... },
-           { "id": "sfEnd", "type": "core.control.end", ... }
-         ],
-         "edges": [ ... ],
-         "variables": {
-           "globals": [
-             { "id": "<IN_VAR>", "direction": "in", "type": "...", "triggerNodeId": "sfStart" },
-             { "id": "<OUT_VAR>", "direction": "out", "type": "..." }
-           ],
-           "nodes": []
-         },
-         "layout": {
-           "nodes": {
-             "sfStart": { "position": { "x": 200, "y": 144 }, "size": { "width": 96, "height": 96 }, "collapsed": false },
-             "sfEnd":   { "position": { "x": 400, "y": 144 }, "size": { "width": 96, "height": 96 }, "collapsed": false }
-           }
-         }
-       }
-     }
-   }
-   ```
-
-3. Subflow's `in` variables must match the parent node's `inputs` keys
-4. Map all `out` variables on the subflow's End node `outputs`
-5. Parent-scope `$vars` are NOT visible inside the subflow — pass values via inputs
-6. Subflow node positions go in the **subflow's own** `layout.nodes` — not in the top-level `layout.nodes`. Each subflow has an independent layout scope.
-
-See [subflow/impl.md](plugins/subflow/impl.md) for the full JSON structure and rules.
-
----
-
-## Connector Node Configuration (Edit / Write fallback)
-
-When not using `uip maestro flow node configure`, use `Edit` to set up the following manually:
-
-### 1. `inputs.detail` on the node
-
-**Tool:** `Edit`
-
-```json
-{
-  "inputs": {
-    "detail": {
-      "connectionId": "<CONNECTION_UUID>",
-      "folderKey": "<FOLDER_KEY>",
-      "method": "<HTTP_METHOD>",
-      "endpoint": "<API_PATH>",
-      "bodyParameters": { "<FIELD>": "<VALUE>" },
-      "queryParameters": { "<FIELD>": "<VALUE>" },
-      "pathParameters": { "<PLACEHOLDER>": "<VALUE>" }
-    }
-  }
-}
-```
-
-Source `method`, `endpoint`, and `bodyParameters` / `queryParameters` / `pathParameters` field names from either of these (both read the same upstream IS metadata):
-
-From `uip maestro flow registry get <node-type> --connection-id <id> --output json`:
-- `method` ← `connectorMethodInfo.method`
-- `endpoint` ← `connectorMethodInfo.path`
-- `bodyParameters.<name>` ← `inputDefinition.fields[].name`
-- `queryParameters.<name>` ← `connectorMethodInfo.parameters[]` where `type: query`
-- `pathParameters.<name>` ← `connectorMethodInfo.parameters[]` where `type: path` (must match a `{placeholder}` in `endpoint`)
-
-From `uip is resources describe <connector-key> <objectName> --connection-id <id> --operation <Op> --output json`:
-- `method` ← `availableOperations[].method`
-- `endpoint` ← `availableOperations[].path`
-- `bodyParameters.<name>` ← `requestFields[].name`
-- `queryParameters.<name>` ← `parameters[]` where `type: query`
-- `pathParameters.<name>` ← `parameters[]` where `type: path` (must match a `{placeholder}` in `endpoint`)
-
-### 2. Connection binding in `bindings_v2.json`
-
-**Tool:** `Edit` (or `Write` for a fresh `bindings_v2.json`)
-
-```json
-{
-  "version": "2.0",
-  "resources": [
-    {
-      "resource": "Connection",
-      "key": "<CONNECTION_UUID>",
-      "id": "Connection<CONNECTION_UUID>",
-      "value": {
-        "ConnectionId": {
-          "defaultValue": "<CONNECTION_UUID>",
-          "isExpression": false,
-          "displayName": "<CONNECTOR_KEY> connection"
-        }
-      },
-      "metadata": {
-        "ActivityName": "<ACTIVITY_DISPLAY_NAME>",
-        "BindingsVersion": "2.2",
-        "DisplayLabel": "<CONNECTOR_KEY> connection",
-        "UseConnectionService": "true",
-        "Connector": "<CONNECTOR_KEY>"
-      }
-    }
-  ]
-}
-```
-
-See [connector/impl.md](plugins/connector/impl.md) for the full schema and multi-connector examples.