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

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

@@ -33,8 +33,9 @@ Every node in a `.flow` file has exactly one author. The validator enforces this
 | Agents | `uipath.agent.autonomous` (inline; after `uip agent init --inline-in-flow`) |
 | Voice | `core.trigger.voice`, `uipath.agent.voice` (inline; after `uip agent init --inline-in-flow --conversational`), `uipath.conversational.voice.create-outgoing-call`, `uipath.conversational.voice.end-call` |
 | Resource nodes | `uipath.core.rpa-workflow.*`, `uipath.core.agent.*`, `uipath.core.flow.*`, `uipath.core.agentic-process.*`, `uipath.core.api-workflow.*`, `uipath.core.human-task.*` |
-| Document extraction | `uipath.ixp.*` — the extraction step must always land a node ([ixp/impl.md](references/plugins/ixp/impl.md#landing-the-node-when-you-cannot-fully-configure-it)) |
+| Document extraction | `uipath.ixp.*` — the extraction step must always land a node ([ixp/impl.md](plugins/ixp/impl.md#landing-the-node-when-you-cannot-fully-configure-it)) |
 | Queue | `core.action.queue.create`, `core.action.queue.create-and-wait` |
+| Data Fabric | `core.datafabric.read`, `core.datafabric.create`, `core.datafabric.update`, `core.datafabric.delete` — `inputs.entityConfig` is plain JSON, not an envelope ([data-fabric/impl.md](plugins/data-fabric/impl.md)) |
 
 **CLI-owned nodes (`uip maestro flow node add` + `uip maestro flow node configure`):**
 
@@ -42,14 +43,14 @@ Every node in a `.flow` file has exactly one author. The validator enforces this
 | --- | --- | --- |
 | Connector activities | `uipath.connector.<key>.<op>` | `inputs.detail` is a `=jsonString:essentialConfiguration` envelope. Validate rejects hand-authored shapes. |
 | Connector triggers | `uipath.connector.trigger.<key>.<trigger>` | Same envelope + product-managed `bindings_v2.json` derivation. |
-| Wait for events (mid-flow) | `uipath.connector.event.<key>.<event>` | Same envelope and event metadata as a trigger, but placed mid-flow (has an `input` port) instead of as the start node. See [connector-trigger/impl.md — Wait for events](references/plugins/connector-trigger/impl.md#wait-for-events-uipathconnectoreventkeyevent). |
+| Wait for events (mid-flow) | `uipath.connector.event.<key>.<event>` | Same envelope and event metadata as a trigger, but placed mid-flow (has an `input` port) instead of as the start node. See [connector-trigger/impl.md — Wait for events](plugins/connector-trigger/impl.md#wait-for-events-uipathconnectoreventkeyevent). |
 | Managed HTTP | `core.action.http.v2` | Same envelope. |
 
 For CLI-owned nodes:
 
 - Use `uip maestro flow node add` to insert the node and copy the definition into `definitions[]`.
 - Use `uip maestro flow node configure --detail '{...}'` to populate `inputs.detail` and `bindings[]`.
-- Subsequent edits to `inputs.detail` are also CLI-only — re-run `node configure` (it's a full rebuild; see [connector/impl.md](references/plugins/connector/impl.md)).
+- Subsequent edits to `inputs.detail` are also CLI-only — re-run `node configure` (it's a full rebuild; see [connector/impl.md](plugins/connector/impl.md)).
 - **Never `Write` (full-file rewrite) a flow that contains CLI-owned nodes** — it silently clobbers their `bindings[]` / `inputs.detail`, leaving a corrupted connection binding that `flow validate` passes but `flow debug` fails on. `Edit` user-owned nodes in place; if a `Write` is unavoidable, re-run `node configure` for every CLI-owned node as the **last** write to touch `inputs.detail` / `bindings[]` (a later `Write` re-clobbers what `configure` just fixed).
 - You may still `Edit` the node's `display.label`, edges, layout, and outputs — those are not part of the envelope.
 
@@ -58,10 +59,10 @@ If you find yourself hand-writing `inputs.detail`, a `=jsonString:` blob, or `bi
 ## Critical rules
 
 1. **Always validate node types against the registry before building.** Use `registry search`/`list` for discovery and `registry get` for detailed metadata and definitions.
-2. **ALWAYS follow the relevant plugin in [plugins/](references/plugins/) for every node type.** Each plugin has a `planning.md` (when to use, selection heuristics, ports) and `impl.md` (registry validation, JSON structure, CLI commands, configuration, debug). For connector nodes, the [connector](references/plugins/connector/impl.md) plugin covers connection binding, enriched metadata, and field resolution — required before building. Without this, node configuration will be wrong — errors that `flow validate` does not catch.
+2. **ALWAYS follow the relevant plugin in [plugins/](plugins/) for every node type that has one.** Two node types have no plugin directory and never have: `core.logic.mock` is documented in [editing-operations-json.md](editing-operations-json.md#replace-a-mock-with-a-real-resource-node), and `core.trigger.manual` in [scheduled-trigger/planning.md](plugins/scheduled-trigger/planning.md). Read those instead — do not construct a `plugins/<name>/impl.md` path that is not listed in [plugins/](plugins/); it does not exist and the read will fail. Each plugin has a `planning.md` (when to use, selection heuristics, ports) and `impl.md` (registry validation, JSON structure, CLI commands, configuration, debug). For connector nodes, the [connector](plugins/connector/impl.md) plugin covers connection binding, enriched metadata, and field resolution — required before building. Without this, node configuration will be wrong — errors that `flow validate` does not catch.
 3. **Read the relevant Integration Service reference doc before any `uip is ...` call.** Two non-overlapping contracts:
    - **Read [/uipath:uipath-platform — connections.md](../../../uipath-platform/references/integration-service/connections.md) before any `uip is connections ...` call.** Applies to every connector activity, connector trigger, and managed HTTP node in connected mode. Single source of truth for command syntax, selection (including the personal-workspace auto-select rule), folder scoping, BYOA filtering, empty-result recovery, and ping verification. **If no healthy connection exists after following its recovery flow, STOP** and surface it in **Open Questions** during planning.
-   - **Read [/uipath:uipath-platform — resources.md](../../../uipath-platform/references/integration-service/resources.md) before any `uip is resources run ...` call.** Applies to every reference-field lookup (Slack user IDs, Jira project keys, Outlook folder IDs, etc.). Single source of truth for the `Data.Pagination.HasMore` / `NextPageToken` contract and the `--query "nextPage=<token>"` loop. **Complete the pagination loop before reporting not-found** — do NOT abandon mid-loop to try alternative endpoints, `where=` filters the connector may not support, or asking the user. Plugin files cover node-specific configuration that follows connection binding: [connector/impl.md](references/plugins/connector/impl.md), [connector-trigger/impl.md](references/plugins/connector-trigger/impl.md), [http/impl-connector.md](references/plugins/http/impl-connector.md).
+   - **Read [/uipath:uipath-platform — resources.md](../../../uipath-platform/references/integration-service/resources.md) before any `uip is resources run ...` call.** Applies to every reference-field lookup (Slack user IDs, Jira project keys, Outlook folder IDs, etc.). Single source of truth for the `Data.Pagination.HasMore` / `NextPageToken` contract and the `--query "nextPage=<token>"` loop. **Complete the pagination loop before reporting not-found** — do NOT abandon mid-loop to try alternative endpoints, `where=` filters the connector may not support, or asking the user. Plugin files cover node-specific configuration that follows connection binding: [connector/impl.md](plugins/connector/impl.md), [connector-trigger/impl.md](plugins/connector-trigger/impl.md), [http/impl-connector.md](plugins/http/impl-connector.md).
 4. **Edit `<ProjectName>.flow` only** — other generated files (`bindings_v2.json`, `entry-points.json`, `operate.json`, `package-descriptor.json`) are managed by the CLI and may be overwritten. To declare flow inputs/outputs, add variables in the `.flow` file (see [shared/file-format.md](../shared/file-format.md)).
 5. **`targetPort` is required on every edge** — `validate` rejects edges without it.
 6. **Every node type needs a `definitions` entry** — copy from `uip maestro flow registry get <node-type>` output. Never hand-write definitions. The definition is the sole source for BPMN type (`model.type`), serviceType, event definitions, and binding/context templates — none of that belongs on the instance.
@@ -69,10 +70,10 @@ If you find yourself hand-writing `inputs.detail`, a `=jsonString:` blob, or `bi
 8. **Validate once at the end** — run `uip maestro flow validate` only after all nodes, edges, and configuration are complete. Do not validate after each individual node add or edit — intermediate states are expected to be invalid.
 9. **Author variables with `Edit` against the `.flow` file** — use `Edit` to add/remove/update entries in the `variables` section. `variables.variableUpdates` is `Edit`-only; there is no CLI command for it. Globals do have a CLI surface (`uip maestro flow variable add|list|remove`), but it is scoped to declaring eval inputs — see [shared/variables-and-expressions.md](../shared/variables-and-expressions.md#variable-management-via-cli).
 10. **Every `out` variable must be mapped on every reachable End node** — missing output mappings cause runtime errors. See [shared/variables-and-expressions.md](../shared/variables-and-expressions.md).
-11. **`=js:` prefix is REQUIRED on every `$vars`/`$metadata`/`$self` reference in a value field** — not on condition expressions (decision, switch, HTTP branch), which are auto-evaluated as JS. Without it, the BPMN runtime sees a literal string and `flow validate` fails with MST-9107. See [shared/node-output-wiring.md](../shared/node-output-wiring.md) for the canonical rule and per-node-type field reference, and [shared/variables-and-expressions.md](../shared/variables-and-expressions.md) for the expression system.
+11. **`=js:` prefix is REQUIRED on every `$vars`/`$metadata`/`$self` reference in a value field** — not on condition expressions (decision, switch, HTTP branch), which are auto-evaluated as JS. Without it, the BPMN runtime sees a literal string and `flow validate` fails. See [shared/node-output-wiring.md](../shared/node-output-wiring.md) for the canonical rule and per-node-type field reference, and [shared/variables-and-expressions.md](../shared/variables-and-expressions.md) for the expression system.
 12. **Always run `flow format` after edits** — `uip maestro flow format <ProjectName>.flow` is the canonical layout step. 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 (`subflows[<id>].layout`). Skipping format is the most common cause of misshapen nodes in Studio Web.
 13. **Don't hand-write `layout.nodes` or `subflows[<id>].layout`** — these are owned by `flow format`. When authoring nodes, any placeholder `position` is fine (e.g. `{ x: 0, y: 0 }`); format rewrites it on save. Sticky notes (`type: "stickyNote"`) are the one exception — format preserves their custom size and position. See [shared/file-format.md — Layout](../shared/file-format.md#layout).
-14. **Every data-producing node MUST have a matching `variables.nodes[]` entry — this is what makes `$vars.<sourceNodeId>.output` resolve.** The BPMN emitter walks `variables.nodes[]` to write the process-level `<uipath:inputOutput>` declarations the runtime needs. The instance `outputs` block is **only** consumed by BPMN serialization on end-style nodes (to map workflow-level `out` variables); for action / trigger nodes it is documentation, not behavior. Skipping `variables.nodes[]` produces a flow that passes `flow validate` but resolves `$vars.<sourceNodeId>.output` to `undefined` at runtime (MST-9972). **Always run `uip maestro flow format` after structural edits — it regenerates `variables.nodes[]` from `nodes[]` + `definitions[]`** (matching what `uip maestro flow node add` and the canvas save path do), so this becomes self-healing as long as you `format`. See [shared/file-format.md — Node outputs](../shared/file-format.md#node-outputs).
+14. **Every data-producing node MUST have a matching `variables.nodes[]` entry — this is what makes `$vars.<sourceNodeId>.output` resolve.** The BPMN emitter walks `variables.nodes[]` to write the process-level `<uipath:inputOutput>` declarations the runtime needs. The instance `outputs` block is **only** consumed by BPMN serialization on end-style nodes (to map workflow-level `out` variables); for action / trigger nodes it is documentation, not behavior. Skipping `variables.nodes[]` produces a flow that passes `flow validate` but resolves `$vars.<sourceNodeId>.output` to `undefined` at runtime. **Always run `uip maestro flow format` after structural edits — it regenerates `variables.nodes[]` from `nodes[]` + `definitions[]`** (matching what `uip maestro flow node add` and the canvas save path do), so this becomes self-healing as long as you `format`. See [shared/file-format.md — Node outputs](../shared/file-format.md#node-outputs).
 15. **Node instances have no `model` block** — BPMN type, serviceType, version, event definitions, and binding/context templates live in the node's **definition** (in the top-level `definitions[]` array, copied verbatim from `registry get`). The runtime hydrates these from the definition at serialization time. Instance-specific identity fields live under `inputs`: `entryPointId`, `isDefaultEntryPoint` (triggers), `color`/`content` (sticky notes), and `source` (every inline-agent-related node — both `uipath.agent.autonomous` and every attached `uipath.agent.resource.*` node use `inputs.source = <UUID>`; their definitions declare `model.source: true` and flow-core hoists onto the instance).
 16. **Error handling is off by default — never enable it on a node that handles no stated failure.** Leave `inputs.errorHandlingEnabled` unset and add no `error` edge unless the requirements say what should happen when that node fails ("if the call fails…", "return X for invalid input", "handle timeouts"). An unhandled failure must fault the flow. When you do wire an `error` edge, it must reach a terminal the caller can distinguish from success — never the next happy-path node or the success End node. Without this, a failed run reports success. See [shared/file-format.md — Implicit error port on action nodes](../shared/file-format.md#implicit-error-port-on-action-nodes).
 17. **Never invent the business meaning or format of a named output — elicit it.** When a request names an output (`caseKey`, `severity`, `status`, `ticketId`, …) but does not define how its value is derived, treat that as a business decision, not a coding choice — whether an identifier passes through unchanged or is reformatted (prefixed, combined, recomputed) is the user's rule to state, not yours to guess. Ask before building ([SKILL.md rule #5](../../SKILL.md#critical-rules-universal) — dropdown + "Something else"), or state your assumption explicitly and get confirmation. A guessed format produces a flow that passes `flow validate` yet returns the wrong value at runtime — the validator checks structure, never business correctness.
@@ -81,47 +82,48 @@ If you find yourself hand-writing `inputs.detail`, a `=jsonString:` blob, or `bi
 
 | Journey | Read |
 | --- | --- |
-| Create a new flow from scratch | [greenfield.md](references/greenfield.md) |
-| Edit an existing flow | [brownfield.md](references/brownfield.md) |
+| Create a new flow from scratch | [greenfield.md](greenfield.md) |
+| Edit an existing flow | [brownfield.md](brownfield.md) |
 
 ## Common tasks
 
 | I need to... | Read these |
 | --- | --- |
-| **Create a new flow** | [greenfield.md](references/greenfield.md) |
-| **Edit an existing flow** | [brownfield.md](references/brownfield.md) + [editing-operations.md](references/editing-operations.md) |
-| **Add/remove/wire nodes and edges** | [editing-operations.md](references/editing-operations.md) (strategy selection) + relevant plugin's `impl.md` (node-specific inputs) |
-| **Generate a flow plan** | [planning-arch.md](references/planning-arch.md) + [planning-impl.md](references/planning-impl.md) |
-| **Choose the right node type** | [planning-arch.md — Plugin Index](references/planning-arch.md#plugin-index) + relevant plugin's `planning.md` |
+| **Create a new flow** | [greenfield.md](greenfield.md) |
+| **Edit an existing flow** | [brownfield.md](brownfield.md) + [editing-operations.md](editing-operations.md) |
+| **Add/remove/wire nodes and edges** | [editing-operations.md](editing-operations.md) (strategy selection) + relevant plugin's `impl.md` (node-specific inputs) |
+| **Generate a flow plan** | [planning-arch.md](planning-arch.md) + [planning-impl.md](planning-impl.md) |
+| **Choose the right node type** | [planning-arch.md — Plugin Index](planning-arch.md#plugin-index) + relevant plugin's `planning.md` |
 | **Understand the .flow JSON format** | [shared/file-format.md](../shared/file-format.md) |
 | **Look up CLI commands** | [shared/cli-commands.md](../shared/cli-commands.md) |
-| **Add a Script node** | [plugins/script/impl.md](references/plugins/script/impl.md) |
-| **Wire nodes with edges** | [editing-operations.md](references/editing-operations.md) + [shared/file-format.md — Standard ports](../shared/file-format.md) |
+| **Add a Script node** | [plugins/script/impl.md](plugins/script/impl.md) |
+| **Wire nodes with edges** | [editing-operations.md](editing-operations.md) + [shared/file-format.md — Standard ports](../shared/file-format.md) |
 | **Find the right node type** | Run `uip maestro flow registry search <keyword> --output json --output-filter "[*].{NodeType:NodeType,DisplayName:DisplayName,Description:Description,AvailableOnTenant:AvailableOnTenant}"` — see [shared/cli-conventions.md §3](../shared/cli-conventions.md#3-prefer---output-filter-for-extraction) for the extraction pattern and Data-shape pin |
-| **Work with connector nodes** | [plugins/connector/](references/plugins/connector/) + [/uipath:uipath-platform](/uipath:uipath-platform) for Integration Service |
-| **Manage variables and expressions** | [shared/variables-and-expressions.md](../shared/variables-and-expressions.md) + [Edit/Write: Variable Operations](references/editing-operations-json.md#variable-operations) |
+| **Work with connector nodes** | [plugins/connector/](plugins/connector/) + [/uipath:uipath-platform](/uipath:uipath-platform) for Integration Service |
+| **Manage variables and expressions** | [shared/variables-and-expressions.md](../shared/variables-and-expressions.md) + [Edit/Write: Variable Operations](editing-operations-json.md#variable-operations) |
 | **Write `=js:` expressions** | [shared/variables-and-expressions.md](../shared/variables-and-expressions.md) |
 | **Wire one node's output into another node's input** | [shared/node-output-wiring.md](../shared/node-output-wiring.md) |
-| **Orchestrate RPA, agents, apps** | Relevant resource plugin: [rpa](references/plugins/rpa/), [agent](references/plugins/agent/), [agentic-process](references/plugins/agentic-process/), [flow](references/plugins/flow/), [api-workflow](references/plugins/api-workflow/), [hitl](references/plugins/hitl/) |
-| **Embed an AI agent tightly coupled to this flow** | [plugins/inline-agent/](references/plugins/inline-agent/) |
-| **Build a voice agent flow (answer or place phone calls)** | [plugins/inline-voice-agent/](references/plugins/inline-voice-agent/) — `uipath.agent.voice` plus the nodes that start, place, and end the call |
-| **Extract structured fields from documents** | [plugins/ixp/](references/plugins/ixp/) — IxP extraction models for PDFs, scanned forms, receipts, invoices, contracts |
-| **List IxP models / runtime projects available in flow** | [plugins/ixp/impl.md — Listing Published Models](references/plugins/ixp/impl.md#listing-published-models) — read-only registry search, no `.flow` scaffold or edits |
-| **Create a resource that doesn't exist yet** | Use `core.logic.mock` placeholder — see [Edit/Write: Replace a mock](references/editing-operations-json.md#replace-a-mock-with-a-real-resource-node) + relevant plugin's `impl.md` |
-| **Add data transform nodes** | [plugins/transform/impl.md](references/plugins/transform/impl.md) |
-| **Add an LLM batch transform over CSV rows** | [plugins/batch-transform/impl.md](references/plugins/batch-transform/impl.md) — `uipath.pattern.batch-transform`, gated by tenant flag `canvas.nodes.batch-transform` |
-| **Summarize / synthesize one document with optional citations** | [plugins/summarize/impl.md](references/plugins/summarize/impl.md) — `uipath.pattern.deep-rag`, gated by tenant flag `canvas.nodes.summarize` |
-| **Create a subflow** | [plugins/subflow/impl.md](references/plugins/subflow/impl.md) + [Edit/Write: Create a subflow](references/editing-operations-json.md#create-a-subflow) |
-| **Add a delay or scheduled trigger** | [plugins/delay/](references/plugins/delay/) or [plugins/scheduled-trigger/](references/plugins/scheduled-trigger/) |
-| **Use queue nodes** | [plugins/queue/impl.md](references/plugins/queue/impl.md) |
+| **Orchestrate RPA, agents, apps** | Relevant resource plugin: [rpa](plugins/rpa/), [agent](plugins/agent/), [agentic-process](plugins/agentic-process/), [flow](plugins/flow/), [api-workflow](plugins/api-workflow/), [hitl](plugins/hitl/) |
+| **Embed an AI agent tightly coupled to this flow** | [plugins/inline-agent/](plugins/inline-agent/) |
+| **Build a voice agent flow (answer or place phone calls)** | [plugins/inline-voice-agent/](plugins/inline-voice-agent/) — `uipath.agent.voice` plus the nodes that start, place, and end the call |
+| **Extract structured fields from documents** | [plugins/ixp/](plugins/ixp/) — IxP extraction models for PDFs, scanned forms, receipts, invoices, contracts |
+| **List IxP models / runtime projects available in flow** | [plugins/ixp/impl.md — Listing Published Models](plugins/ixp/impl.md#listing-published-models) — read-only registry search, no `.flow` scaffold or edits |
+| **Create a resource that doesn't exist yet** | Use `core.logic.mock` placeholder — see [Edit/Write: Replace a mock](editing-operations-json.md#replace-a-mock-with-a-real-resource-node), then the `impl.md` of the plugin for the node that *replaces* the mock (`core.logic.mock` has no plugin of its own) |
+| **Add data transform nodes** | [plugins/transform/impl.md](plugins/transform/impl.md) |
+| **Add an LLM batch transform over CSV rows** | [plugins/batch-transform/impl.md](plugins/batch-transform/impl.md) — `uipath.pattern.batch-transform`, gated by tenant flag `canvas.nodes.batch-transform` |
+| **Summarize / synthesize one document with optional citations** | [plugins/summarize/impl.md](plugins/summarize/impl.md) — `uipath.pattern.deep-rag`, gated by tenant flag `canvas.nodes.summarize` |
+| **Create a subflow** | [plugins/subflow/impl.md](plugins/subflow/impl.md) + [Edit/Write: Create a subflow](editing-operations-json.md#create-a-subflow) |
+| **Add a delay or scheduled trigger** | [plugins/delay/](plugins/delay/) or [plugins/scheduled-trigger/](plugins/scheduled-trigger/) |
+| **Use queue nodes** | [plugins/queue/impl.md](plugins/queue/impl.md) |
+| **Read or write Data Fabric entity records** | [plugins/data-fabric/impl.md](plugins/data-fabric/impl.md) — `core.datafabric.read` / `create` / `update` / `delete`, each gated by its own `canvas.nodes.*-entity` tenant flag |
 
 ## Anti-patterns
 
 - **Prefer running `uip maestro flow init` from inside the solution you named** — run outside one it auto-scaffolds `<Project>Solution/`, but the auto name won't match your chosen solution name. Never pass `--skip-solution-registration` for a project you intend to upload (it leaves a bare single-nested layout). See [SKILL.md rule #6](../../SKILL.md#critical-rules-universal) for the required double-nested `<Solution>/<Project>/<Project>.flow` layout and the self-check.
 - **Never guess node schemas** — use `registry get` for all node types. Guessed port names or input fields cause silent wiring failures.
 - **Never guess the value or format of a business output** — when a request names an output (`caseKey`, `ticketId`, `severity`, …) without saying how to derive it, elicit the rule ([SKILL.md rule #5](../../SKILL.md#critical-rules-universal)) or confirm your assumption before building. Inventing a format — e.g. prefixing an id that should pass through unchanged — yields a flow that passes `flow validate` but returns the wrong business outcome at runtime. See rule #17 above.
-- **Never skip capability discovery for connector nodes** — run `registry search` to confirm the connector exists and what operations it supports before building. See [connector/planning.md](references/plugins/connector/planning.md). Skipping this is the #1 cause of designing around a connector that doesn't exist or an operation it doesn't support.
-- **Never replace a registered connector operation with `core.logic.mock` because configuration cannot run** — if `registry search` / `registry get` finds `uipath.connector.<connector-key>.<operation>`, add that real connector node via `uip maestro flow node add`. Missing live connections, missing tenant access, or prompts that ask you to only plan `--detail` mean: run `node add`, write the planned `--detail` payload to a sidecar file (e.g. `<nodeId>.detail.json`), and surface "configure pending" as an Open Question. **Do not leave a partial `inputs.detail` on the node** — the validator rejects hand-authored envelopes, and the node will not pass `flow validate` until `node configure` is run. Studio Web and reviewers need the real connector key in the `.flow`; the agent must report this explicitly rather than letting the user discover it via a later validation failure. See [§ Node ownership](#node-ownership--who-authors-the-node) and [connector/impl.md — No-Live-Tenant / Planned Configuration](references/plugins/connector/impl.md#no-live-tenant--planned-configuration).
+- **Never skip capability discovery for connector nodes** — run `registry search` to confirm the connector exists and what operations it supports before building. See [connector/planning.md](plugins/connector/planning.md). Skipping this is the #1 cause of designing around a connector that doesn't exist or an operation it doesn't support.
+- **Never replace a registered connector operation with `core.logic.mock` because configuration cannot run** — if `registry search` / `registry get` finds `uipath.connector.<connector-key>.<operation>`, add that real connector node via `uip maestro flow node add`. Missing live connections, missing tenant access, or prompts that ask you to only plan `--detail` mean: run `node add`, write the planned `--detail` payload to a sidecar file (e.g. `<nodeId>.detail.json`), and surface "configure pending" as an Open Question. **Do not leave a partial `inputs.detail` on the node** — the validator rejects hand-authored envelopes, and the node will not pass `flow validate` until `node configure` is run. Studio Web and reviewers need the real connector key in the `.flow`; the agent must report this explicitly rather than letting the user discover it via a later validation failure. See [§ Node ownership](#node-ownership--who-authors-the-node) and [connector/impl.md — No-Live-Tenant / Planned Configuration](plugins/connector/impl.md#no-live-tenant--planned-configuration).
 - **Never set `inputs.errorHandlingEnabled: true` on a node with no outgoing `error` edge** — the flag is CLI-owned (`edge add --source-port error` and `flow format` derive it from the error edges actually present). A hand-set flag with no handler suppresses the node's fault, so the failure is swallowed and the run reports success. See rule #16 above.
 - **Never route an `error` port back into the happy path** — an error edge into the next happy-path node, or into the same End node the success path reaches, makes every failed run report `Completed` with success-shaped outputs. Send it to a distinct End node with an error/status output, to `core.logic.terminate`, or to a branch that genuinely recovers.
 - **Never edit `content/*.bpmn`** — it is auto-generated from the `.flow` file and will be overwritten.
@@ -130,56 +132,57 @@ If you find yourself hand-writing `inputs.detail`, a `=jsonString:` blob, or `bi
 - **Never put any `model` block on node instances** — BPMN type, serviceType, event definition, binding templates, and context templates all live in the node's **definition** (copied verbatim from `registry get` into `definitions[]`). Instances carry only per-instance data: `inputs`, `outputs`, `display`. Identity fields like `entryPointId` / `isDefaultEntryPoint` (triggers) and `color` / `content` (sticky notes) live under `inputs`. This applies to every inline-agent-related node too: `uipath.agent.autonomous` plus every attached `uipath.agent.resource.*` node (tool, escalation, context) carries source identity at `inputs.source = <UUID>`. Their definitions declare `model.source: true`; flow-core hoists onto the instance.
 - **Never author `model.context[]` on resource-node instances** — resource-node instances have no `model` block. For `uipath.core.*` resource nodes (rpa, agent, flow, agentic-process, api-workflow, hitl), the definition (from `registry get`) already carries `model.context[]` with `<bindings.{name}>` placeholders. Your job is to add matching entries to the top-level `bindings[]` array — two entries per resource node (`name` + `folderPath`) with `resourceKey` matching the definition's `model.bindings.resourceKey`. At BPMN emit, the runtime rewrites `<bindings.{name}>` → `=bindings.{id}` via `(resourceKey, name)` matching. Without the top-level `bindings[]` entries, `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." See the resource plugin's `impl.md`.
 - **Never put a `ui` block on node instances** — position and size belong in the top-level `layout.nodes` object. Nodes with `"ui": { "position": ... }` use the wrong format and may not render correctly in Studio Web.
-- **Never skip `flow format` before publish or debug** — without it, hand-written `layout` data renders as misshapen rectangles in Studio Web (the MST-9061 failure mode). See rule #12 above for the format step.
+- **Never skip `flow format` before publish or debug** — without it, hand-written `layout` data renders as misshapen rectangles in Studio Web. See rule #12 above for the format step.
 - **Never validate after every individual edit** — intermediate flow states (e.g., node added but not yet wired) are expected to be invalid. Run `uip maestro flow validate` once after the full build is complete.
 - **Never use `console.log` in script nodes** — `console` is not available in the Jint runtime. Use `return { debug: value }` to inspect values.
 - **Never forget output mapping on End nodes** — every `out` variable in `variables.globals` must have a `source` expression in every reachable End node's `outputs`. Missing mappings cause silent runtime failures.
 - **Never update `in` variables** — only `inout` variables can be modified via `variableUpdates`. Input variables are read-only after flow start.
 - **Never reference parent-scope `$vars` inside a subflow** — subflows have isolated scope. Pass values explicitly via subflow inputs.
-- **Never use `core.action.http` (v1)** — the v1 node is deprecated for all HTTP requests (both connector-authenticated and manual). For connector-auth, v1's `authenticationType: "connection"` input does not pass IS credentials at runtime. Use `core.action.http.v2` (Managed HTTP Request) for every HTTP node. See [http/planning.md](references/plugins/http/planning.md).
-- **Never hand-write `definitions[]` or `inputs.*` for managed HTTP nodes** — use `uip maestro flow node add` (with `--input` for `branches` / `timeout` / `retryCount`) and `uip maestro flow node configure` (for `inputs.detail`). These are the only supported authoring paths. Hand-written `definitions[]` strips required manifest fields; hand-written `inputs.detail` misses `essentialConfiguration` and fails at runtime. See [http/impl.md](references/plugins/http/impl.md).
-- **Never write `$vars.X` (or `$metadata.X`, `$self.X`) without `=js:` in value fields** — `flow validate` flags this as MST-9107. See rule #11 above and [shared/node-output-wiring.md](../shared/node-output-wiring.md) for the per-node-type field reference.
-- **Never reuse a reference ID (mailbox folder, Slack channel, Jira project, Google Sheet, etc.) from a prior flow or session** — reference IDs are scoped to the specific authenticated account behind the connection. A `parentFolderId` from one Outlook mailbox is invalid in another; a Slack channel ID from one workspace is invalid in another. A reused ID passes `flow validate` and `node configure` cleanly, then faults silently at runtime with no resolvable error. Always re-resolve via `uip is resources run list <connector-key> <objectName> --connection-id <CURRENT_CONNECTION_ID> --output json` against the connection bound to this flow — do not paste a value you saw in another flow. See [connector/impl.md — Step 4](references/plugins/connector/impl.md) and [connector-trigger/impl.md — Step 3](references/plugins/connector-trigger/impl.md).
-- **Never include `[*]` literally in a connector `bodyParameters` / `queryParameters` / `pathParameters` key** — `[*]` in `requestFields[].name` is an array marker. Strip it and pass a `=js:` expression returning the array (e.g. `"fields.labels[*]"` → `"fields.labels": "=js:(['a', 'b'])"`). Never a literal JSON array — it validates but does not bind. Supported only when `[*]` is the name suffix; `[*]. See [connector/impl.md — Step 6b](references/plugins/connector/impl.md) for the full table including expression-value handling.
+- **Never use `core.action.http` (v1)** — the v1 node is deprecated for all HTTP requests (both connector-authenticated and manual). For connector-auth, v1's `authenticationType: "connection"` input does not pass IS credentials at runtime. Use `core.action.http.v2` (Managed HTTP Request) for every HTTP node. See [http/planning.md](plugins/http/planning.md).
+- **Never hand-write `definitions[]` or `inputs.*` for managed HTTP nodes** — use `uip maestro flow node add` (with `--input` for `branches` / `timeout` / `retryCount`) and `uip maestro flow node configure` (for `inputs.detail`). These are the only supported authoring paths. Hand-written `definitions[]` strips required manifest fields; hand-written `inputs.detail` misses `essentialConfiguration` and fails at runtime. See [http/impl.md](plugins/http/impl.md).
+- **Never write `$vars.X` (or `$metadata.X`, `$self.X`) without `=js:` in value fields** — `flow validate` flags this as an error. See rule #11 above and [shared/node-output-wiring.md](../shared/node-output-wiring.md) for the per-node-type field reference.
+- **Never reuse a reference ID (mailbox folder, Slack channel, Jira project, Google Sheet, etc.) from a prior flow or session** — reference IDs are scoped to the specific authenticated account behind the connection. A `parentFolderId` from one Outlook mailbox is invalid in another; a Slack channel ID from one workspace is invalid in another. A reused ID passes `flow validate` and `node configure` cleanly, then faults silently at runtime with no resolvable error. Always re-resolve via `uip is resources run list <connector-key> <objectName> --connection-id <CURRENT_CONNECTION_ID> --output json` against the connection bound to this flow — do not paste a value you saw in another flow. See [connector/impl.md — Step 4](plugins/connector/impl.md) and [connector-trigger/impl.md — Step 3](plugins/connector-trigger/impl.md).
+- **Never include `[*]` literally in a connector `bodyParameters` / `queryParameters` / `pathParameters` key** — `[*]` in `requestFields[].name` is an array marker. Strip it and pass a `=js:` expression returning the array (e.g. `"fields.labels[*]"` → `"fields.labels": "=js:(['a', 'b'])"`). Never a literal JSON array — it validates but does not bind. Supported only when `[*]` is the name suffix; `[*]. See [connector/impl.md — Step 6b](plugins/connector/impl.md) for the full table including expression-value handling.
 
 ## References
 
 ### Author-scoped
 
-- [greenfield.md](references/greenfield.md) — create-new-flow journey
-- [brownfield.md](references/brownfield.md) — edit-existing-flow journey
-- [editing-operations.md](references/editing-operations.md) — strategy selection (user-owned nodes via Edit / Write vs CLI-owned nodes via `uip maestro flow node`)
-- [editing-operations-json.md](references/editing-operations-json.md) — Edit / Write recipes (default)
-- [editing-operations-cli.md](references/editing-operations-cli.md) — CLI-owned node procedures
-- [planning-arch.md](references/planning-arch.md) — capability discovery, plugin index, topology design
-- [planning-impl.md](references/planning-impl.md) — registry lookups, connection binding, wiring rules
-- [plugins/](references/plugins/) — per-node-type planning + impl docs:
-  - [connector](references/plugins/connector/) — IS connector nodes (incl. Data Fabric activities)
-  - [connector-trigger](references/plugins/connector-trigger/)
-  - [script](references/plugins/script/) — Jint ES2020 JavaScript
-  - [http](references/plugins/http/) — `core.action.http.v2` (Managed HTTP Request)
-  - [decision](references/plugins/decision/) — binary if/else
-  - [switch](references/plugins/switch/) — multi-way branching
-  - [loop](references/plugins/loop/) — collection iteration
-  - [merge](references/plugins/merge/) — parallel branch sync
-  - [end](references/plugins/end/) — graceful flow completion
-  - [terminate](references/plugins/terminate/) — abort on fatal error
-  - [transform](references/plugins/transform/) — declarative filter/map/group-by
-  - [batch-transform](references/plugins/batch-transform/) — LLM-powered row-by-row CSV enrichment (`uipath.pattern.batch-transform`)
-  - [summarize](references/plugins/summarize/) — single-document synthesis / Q&A with optional citations (`uipath.pattern.deep-rag`)
-  - [delay](references/plugins/delay/) — duration or date-based pause
-  - [subflow](references/plugins/subflow/) — reusable node groups
-  - [scheduled-trigger](references/plugins/scheduled-trigger/) — recurring schedule
-  - [rpa](references/plugins/rpa/) — published RPA processes
-  - [agentic-process](references/plugins/agentic-process/) — published orchestration processes
-  - [flow](references/plugins/flow/) — published flows as subprocesses
-  - [api-workflow](references/plugins/api-workflow/) — published API functions
-  - [hitl](references/plugins/hitl/) — human input via UiPath Apps
-  - [agent](references/plugins/agent/) — published AI agent resources
-  - [inline-agent](references/plugins/inline-agent/) — autonomous agent embedded in flow
-  - [inline-voice-agent](references/plugins/inline-voice-agent/) — voice agent on a live phone call (inbound/outbound) + the trigger, create-call, and end-call nodes
-  - [ixp](references/plugins/ixp/) — published IxP document-extraction models (PDFs, scanned forms, receipts, invoices, contracts)
-  - [queue](references/plugins/queue/) — Orchestrator queue item creation
+- [greenfield.md](greenfield.md) — create-new-flow journey
+- [brownfield.md](brownfield.md) — edit-existing-flow journey
+- [editing-operations.md](editing-operations.md) — strategy selection (user-owned nodes via Edit / Write vs CLI-owned nodes via `uip maestro flow node`)
+- [editing-operations-json.md](editing-operations-json.md) — Edit / Write recipes (default)
+- [editing-operations-cli.md](editing-operations-cli.md) — CLI-owned node procedures
+- [planning-arch.md](planning-arch.md) — capability discovery, plugin index, topology design
+- [planning-impl.md](planning-impl.md) — registry lookups, connection binding, wiring rules
+- [plugins/](plugins/) — per-node-type planning + impl docs:
+  - [connector](plugins/connector/) — IS connector nodes (incl. the `uipath-uipath-dataservice` entity activities; see [data-fabric](plugins/data-fabric/))
+  - [connector-trigger](plugins/connector-trigger/)
+  - [script](plugins/script/) — Jint ES2020 JavaScript
+  - [http](plugins/http/) — `core.action.http.v2` (Managed HTTP Request)
+  - [decision](plugins/decision/) — binary if/else
+  - [switch](plugins/switch/) — multi-way branching
+  - [loop](plugins/loop/) — collection iteration
+  - [merge](plugins/merge/) — parallel branch sync
+  - [end](plugins/end/) — graceful flow completion
+  - [terminate](plugins/terminate/) — abort on fatal error
+  - [transform](plugins/transform/) — declarative filter/map/group-by
+  - [batch-transform](plugins/batch-transform/) — LLM-powered row-by-row CSV enrichment (`uipath.pattern.batch-transform`)
+  - [summarize](plugins/summarize/) — single-document synthesis / Q&A with optional citations (`uipath.pattern.deep-rag`)
+  - [delay](plugins/delay/) — duration or date-based pause
+  - [subflow](plugins/subflow/) — reusable node groups
+  - [scheduled-trigger](plugins/scheduled-trigger/) — recurring schedule
+  - [rpa](plugins/rpa/) — published RPA processes
+  - [agentic-process](plugins/agentic-process/) — published orchestration processes
+  - [flow](plugins/flow/) — published flows as subprocesses
+  - [api-workflow](plugins/api-workflow/) — published API functions
+  - [hitl](plugins/hitl/) — human input via UiPath Apps
+  - [agent](plugins/agent/) — published AI agent resources
+  - [inline-agent](plugins/inline-agent/) — autonomous agent embedded in flow
+  - [inline-voice-agent](plugins/inline-voice-agent/) — voice agent on a live phone call (inbound/outbound) + the trigger, create-call, and end-call nodes
+  - [ixp](plugins/ixp/) — published IxP document-extraction models (PDFs, scanned forms, receipts, invoices, contracts)
+  - [queue](plugins/queue/) — Orchestrator queue item creation
+  - [data-fabric](plugins/data-fabric/) — native Data Fabric entity record CRUD (`core.datafabric.*`); tenant flags default to off
 
 ### Cross-capability (shared)
 

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

@@ -0,0 +1,90 @@
+# Brownfield — Edit an Existing Flow
+
+Recipe-driven journey for targeted changes to an existing `.flow` file. Authoring ends at `validate` + `format`. For publishing, running, or debugging, see [operate/CAPABILITY.md](../operate/CAPABILITY.md).
+
+> **Greenfield (creating a new flow) uses a different journey.** If the `.flow` file does not exist, see [greenfield.md](greenfield.md).
+
+## Converting an existing project to Maestro
+
+There is no automatic project-to-flow conversion. Re-host only orchestration:
+
+1. Keep coded/RPA components and agents as resource nodes; do not rewrite them into Maestro. Use `uipath.core.rpa-workflow.*` and `uipath.core.agent.*`; see the relevant plugin's `planning.md`.
+2. Lift ordering, waits, and branches into explicit trigger → steps → decisions → end topology.
+3. Make sleeps, polling, and "check again later" first-class Maestro wait, delay, HITL, or `create-and-wait` nodes.
+4. Publish executors or keep them in-solution, then resolve them with `registry list --local` for in-solution projects.
+
+The result should be a thin flow delegating work to existing artifacts. Author it as greenfield ([greenfield.md](greenfield.md)), discovering artifacts during [planning-arch.md](planning-arch.md). Apply [Is Maestro the Right Home?](planning-arch.md#before-you-build-is-maestro-the-right-home): migrate for long waits, human approvals, parallel branches, or per-case visibility; do not migrate short, fully automated, fire-once scripts when orchestration overhead is not worthwhile.
+
+## Read this first
+
+Before each node added or modified, 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: run `uip maestro flow node add` + `uip maestro flow node configure`, never Edit. Hand-writing these will fail `flow validate`; this also applies when adding a connector node to an existing flow.
+
+Read [editing-operations.md](editing-operations.md) and the strategy selection matrix before modifying. Use `Edit` for in-place user-owned changes; use `Write` only when ≥70% of nodes change. For CLI-owned nodes, follow the plugin's `impl.md` configuration workflow (`node add` + `node configure`).
+
+**Self-check before every mutation:** name the tool. If it is not `Edit`, `Write`, or `uip maestro flow ...`, STOP and ask the user under the dropdown question rule in [SKILL.md](../../SKILL.md). Treat `python`, `node`, `jq`, `sed`, `awk`, and shell heredocs as last resorts requiring explicit user approval after surfacing trade-offs. See [editing-operations.md — Tool Selection Ladder](editing-operations.md#tool-selection-ladder).
+
+## Common edits
+
+Make all edits first. Then run `uip maestro flow validate` once, followed by `uip maestro flow format`; do not validate intermediate invalid states.
+
+For edits touching multiple top-level arrays, follow [parallel same-file Edit rules](editing-operations.md#parallel-same-file-edits): anchor each Edit on its array's opening key, never on top-level key order.
+
+| Edit | Required operation and guide |
+|---|---|
+| **Change a script body or node inputs** | Use `Edit` on `inputs`; do not delete/re-add because node IDs and `$vars` expressions must remain stable. Script nodes must return an object (`return { key: value }`). See [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 node; wire upstream → new → downstream. See [Edit/Write: Insert a node](editing-operations-json.md#insert-a-node-between-two-existing-nodes). |
+| **Move / reorder a node** | Re-wire the edges, then re-point every `$vars.<node>` read inside the moved node (a Decision's `expression`, a script body, input fields) to a node that still runs **before** it; a reference to a node that now runs later evaluates against nothing at runtime (`[400302]`/`[400300]`) even though `flow validate` passes. Nodes the branches rejoin at read the Decision as `$vars.<decisionId>.matchedCaseId` (see [decision/impl.md — Outputs](plugins/decision/impl.md#outputs)). See [Edit/Write: Delete an edge](editing-operations-json.md#delete-an-edge) and [Edit/Write: Update node inputs](editing-operations-json.md#update-node-inputs). |
+| **Add a branch (decision node)** | Remove an edge; add the decision; wire true/false branches. See [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. See [Edit/Write: Remove a node](editing-operations-json.md#remove-a-node-and-reconnect). |
+| **Remove an edge** | Find and remove its edge ID. See [Edit/Write: Delete an edge](editing-operations-json.md#delete-an-edge). |
+| **Add a workflow variable** | Use `Edit` on `variables.globals` (Edit-only). For `out` variables, map every End node. See [shared/variables-and-expressions.md](../shared/variables-and-expressions.md) and [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) and [Edit/Write: Add a variable update](editing-operations-json.md#add-a-variable-update). |
+| **Create a subflow** | Add a `core.subflow` parent and `subflows.{nodeId}` with nested nodes, edges, and variables (`Edit`-only, or `Write` for template scaffolding). See [Edit/Write: Create a subflow](editing-operations-json.md#create-a-subflow) and [subflow/impl.md](plugins/subflow/impl.md). |
+| **Add a scheduled trigger** | Replace `core.trigger.manual` with `core.trigger.scheduled`. See [Edit/Write: Replace trigger](editing-operations-json.md#replace-manual-trigger-with-scheduled-trigger) and [scheduled-trigger/impl.md](plugins/scheduled-trigger/impl.md). |
+| **Add a connector trigger** | Remove the manual trigger; add and configure the connector trigger with a connection. Use [CLI: Replace trigger](editing-operations-cli.md#replace-manual-trigger-with-connector-trigger) and [connector-trigger/impl.md](plugins/connector-trigger/impl.md). |
+| **Add a resource node** | Discover through the registry (`--local` for in-solution, or tenant registry for published); add with `Edit`; wire edges. Use the relevant plugin's `impl.md` and [editing-operations-json.md](editing-operations-json.md). |
+| **Add an inline agent node** | Embed `uipath.agent.autonomous` with an inline agent definition in the flow project. See [inline-agent/planning.md](plugins/inline-agent/planning.md) for inline versus published selection and [inline-agent/impl.md](plugins/inline-agent/impl.md) for scaffolding, JSON, 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`. See [inline-voice-agent/planning.md](plugins/inline-voice-agent/planning.md) for the two topologies and trunk requirements, and [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 the human approval/review/enrichment checkpoint and wire its `completed` port. See [Edit/Write: Add a node](editing-operations-json.md) and [hitl/impl.md](plugins/hitl/impl.md). |
+
+OOTB structural CRUD uses Edit/Write only; there is no CLI opt-in path for other flow-graph edits.
+
+## After edits
+
+1. Run `uip maestro flow validate <ProjectName>.flow --output json`. Fix errors and re-validate.
+2. Run `uip maestro flow format <ProjectName>.flow --output json`. Run it before publish or debug (see "Always run `flow format` after edits" in [the Author capability index](CAPABILITY.md)); without it, stale or hand-edited `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`, run:
+
+```bash
+uip maestro flow migrate <ProjectName>.flow --output json
+```
+
+`migrate` is lossless, walks the per-version migration chain (for example, `=js:` expression strings become rich expression objects), and bumps the file to the current version. Then run `flow format` and `flow validate`; both should pass. `flow validate` does not re-serialize and therefore does not check the version guard enforced by `format`/`debug`/`pack`. When this refusal appears, always migrate; do not assume the edit was wrong.
+
+## Completion Output
+
+When editing finishes, report:
+
+1. **File path** of the edited `.flow` file
+2. **What changed** — nodes/edges added, removed, or modified
+3. **Validation status** — whether `flow validate` passes, or remaining unresolvable errors
+4. **Format status** — confirm `flow format` was run
+5. **Mock placeholders** — every `core.logic.mock` node needing replacement
+6. **Missing connections** — connector nodes requiring connections the user must create
+7. **What's next** — ask the user using the dropdown below (see the dropdown question rule in [SKILL.md](../../SKILL.md))
+
+### What's next dropdown
+
+Authoring ends here. For any selected option, read [operate/CAPABILITY.md](../operate/CAPABILITY.md) and follow that capability's flow; do not run operate commands from this document.
+
+| Option | What it does |
+|---|---|
+| **Publish to Studio Web** | 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. Consent comes from the mandate, not from this menu — see the `flow debug` rule in [SKILL.md](../../SKILL.md). Selecting it here is the user asking for a run. |
+| **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. |
+
+When the original request already named the next step ("publish it", "deploy to Orchestrator", "run debug and iterate"), that instruction **is** the selection — act on it and skip the menu. Show the menu only when the next step was left unspecified, and then do not run any option without explicit user selection.

package/skills/uipath-maestro-flow/references/author/{references/editing-operations-cli.md → editing-operations-cli.md}

@@ -71,7 +71,7 @@ uip maestro flow edge add <ProjectName>.flow <SOURCE_NODE_ID> <TARGET_NODE_ID> -
 - Inserts edge into `edges` array with a generated `id`
 - Sets `targetPort` (required — validate rejects edges without it)
 
-See each plugin's `planning.md` or [file-format.md — Standard ports](../../shared/file-format.md) for port names by node type.
+See each plugin's `planning.md` or [file-format.md — Standard ports](../shared/file-format.md) for port names by node type.
 
 ### Remove an edge
 
@@ -104,12 +104,17 @@ uip maestro flow node configure <ProjectName>.flow <NODE_ID> \
 
 The `--detail` JSON schema differs between connector activity nodes, connector trigger nodes, and managed HTTP nodes — see [connector/impl.md](plugins/connector/impl.md), [connector-trigger/impl.md](plugins/connector-trigger/impl.md), and [http/impl.md](plugins/http/impl.md) for the exact fields.
 
-**Shell quoting tip:** For complex `--detail` JSON, write it to a temp file:
+**Shell quoting — write the JSON to a file first.** Never hand-escape quotes inside the shell command. `--detail` takes inline JSON only; there is no file flag. Write the payload with a quoted heredoc, then substitute the file:
 
 ```bash
-uip maestro flow node configure <file> <nodeId> --detail "$(cat /tmp/detail.json)" --output json
+cat > /tmp/detail.json <<'EOF'
+{"connectionId": "<CONNECTION_ID>", "folderKey": "<FOLDER_KEY>", "method": "POST", "endpoint": "/Account"}
+EOF
+uip maestro flow node configure <ProjectName>.flow <NODE_ID> --detail "$(cat /tmp/detail.json)" --output json
 ```
 
+`<<'EOF'` (quoted delimiter) stops the shell from touching the body, so `=js:` expressions, backticks, `${...}`, and nested quotes reach the CLI byte for byte. Nesting an `=js:` expression inside `--detail '<json>'` instead doubles its backslashes; the saved expression then faults at runtime with `[400300] Error evaluating expression … Invalid or unexpected token`, and a stray quote aborts the command with a shell parse error (`zsh: parse error`, `bash: syntax error near unexpected token`).
+
 ### Configure a managed HTTP node
 
 After adding a `core.action.http.v2` node, configure it with target connector and connection details:
@@ -179,7 +184,7 @@ These operations require the `Edit` tool. Use the [Edit / Write strategy guide](
 
 1. **Any non-carve-out structural edit** — node/edge CRUD, scheduled triggers, HITL QuickForm nodes, inline-agent nodes, non-connector resources, and graph rewiring
 2. **Node input updates** — the CLI does not have a `node update` command; use `Edit` to preserve node IDs and `$vars.{nodeId}` references
-3. **Workflow variables while authoring** — updating `variables.globals` in place, and any `subType`/`schema`/`defaultValue` change. There *is* a CLI surface for declaring globals (`uip maestro flow variable add|list|remove`), but it is scoped to declaring eval inputs — see [variables-and-expressions.md § Variable Management via CLI](../../shared/variables-and-expressions.md#variable-management-via-cli)
+3. **Workflow variables while authoring** — updating `variables.globals` in place, and any `subType`/`schema`/`defaultValue` change. There *is* a CLI surface for declaring globals (`uip maestro flow variable add|list|remove`), but it is scoped to declaring eval inputs — see [variables-and-expressions.md § Variable Management via CLI](../shared/variables-and-expressions.md#variable-management-via-cli)
 4. **Variable updates** — add/modify `variables.variableUpdates` entries. No CLI command exists for these
 5. **Output mapping on End nodes** — add `outputs` object with `source` expressions
 6. **Subflows** — create `subflows.{nodeId}` with nested nodes, edges, variables