UiPath · rockymadden · May 1, 2026 · May 1, 2026 · May 1, 2026
@@ -67,7 +67,7 @@ These rules apply across all three capabilities. Each capability index adds capa
 6. **A Flow project MUST live inside a solution** — always scaffold the solution first (`uip solution new <Name>`), then `cd <Name>` and run `uip maestro flow init <Name>`. The correct layout is **always** `<Solution>/<Project>/<Project>.flow` (double-nested). Running `uip maestro flow init` in a bare directory produces a single-nested `<Project>/<Project>.flow` layout that fails Studio Web upload, packaging, and downstream tooling. See [author/greenfield.md](references/author/references/greenfield.md) Step 2.
 7. **Always narrate progress in plain English at each logical step boundary.** One short line per step, in user terms ("checking your tenant login", "adding the Slack node and wiring its inputs", "editing the flow JSON to add the new variable", "running validate") — no flag-level or JSON-structure-level detail. Applies uniformly to `uip` CLI calls, shell builtins (`ls`, `cat`, `cd`, `mkdir`, `find`, `grep`), file edits (Read/Write/Edit), and bulk searches (Glob/Grep). The user should never need to know `bash`, `uip` flags, or `.flow` JSON internals to follow along. See [shared/ux-narration-and-todos.md](references/shared/ux-narration-and-todos.md).
 8. **Use `TodoWrite` for any journey above the trivial threshold; keep granularity per-step, not per-phase.** Standard journeys (greenfield, brownfield with multiple nodes, ship, run, full diagnose) require a granular todo list (~15–25 items). One logical step ≈ one todo. Bash plumbing inside a step (registry lookups, JSON parsing, intermediate file reads) is invisible — do not surface as todos. See [shared/ux-narration-and-todos.md](references/shared/ux-narration-and-todos.md) for granularity rules, threshold table, and pivot rules.
-9. **Scripting languages (`python`, `node`, `jq`, `sed`, `awk`, inline shell heredocs) are a last resort for mutating a `.flow` file, `bindings_v2.json`, or any other file under a Flow project — and require explicit user approval.** Default mutation tools: `Edit`, `Write`, `uip maestro flow node {add,delete,configure}`, `uip maestro flow edge {add,delete}`, `uip maestro flow variable {add,...}`. Reading with `cat`, `jq`, or a Python one-liner is fine when output is parsed. **Mutating is the regulated path.** Scripted mutations bypass the CLI's auto-managed `definitions[]` / `variables.nodes` / layout state and produce opaque diffs that are not reviewable line-by-line. If a mutation feels too coordinated for a sequence of `Edit` calls, use `Write` for a wholesale rewrite (only when ≥70% of nodes change) or stop and ask the user. Only fall back to a scripting language after the user has been told the trade-offs (state bypass, opaque diff, no interruption point) and has explicitly approved that path for the specific change. See [author/editing-operations.md — Tool Selection Ladder](references/author/references/editing-operations.md#tool-selection-ladder) for the per-operation tool ladder and the rationale.
+9. **Default to `Edit` / `Write` for every mutation of a `.flow` file, `bindings_v2.json`, or any other file under a Flow project.** The `uip maestro flow node` / `edge` / `variable` CLI is a **carve-out**, not a co-default — use it only for connector, connector-trigger, and inline-agent nodes (where `node configure` auto-populates `inputs.detail` + `bindings_v2.json`), or when the user explicitly requests CLI. Use `Write` for wholesale rewrites only when ≥70% of nodes change. Scripting languages (`python`, `node`, `jq`, `sed`, `awk`, inline shell heredocs) are a last resort and require explicit user approval after the trade-offs (state bypass, opaque diff, no interruption point) have been surfaced. See [author/editing-operations.md — Tool Selection Ladder](references/author/references/editing-operations.md#tool-selection-ladder) for the per-operation tool ladder and the rationale.
 
 ## Anti-patterns (universal)
 

@@ -20,20 +20,21 @@ Capability index for building new flows (greenfield) and editing existing flows
 ## 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.
-3. **ALWAYS check for existing connections** before using a connector node — if no connection exists, tell the user before proceeding. See [connector/impl.md](references/plugins/connector/impl.md) for connection binding details.
-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 <nodeType>` 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.
-7. **Script nodes must `return` an object** — `return { key: value }`, not a bare scalar.
-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. **Manage variables with `Edit` against the `.flow` file** — there are no CLI commands for variable management. Use `Edit` to add/remove/update entries in the `variables` section of the `.flow` file. See [shared/variables-and-expressions.md](../shared/variables-and-expressions.md).
-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.** That includes connector node `inputs.detail.bodyParameters` / `queryParameters` / `pathParameters`, HTTP `url`/`headers`/`body`, end node output `source`, variable update `expression`, loop `collection`, and subflow `inputs.<id>.source`. Without `=js:`, the BPMN runtime sees a literal string (e.g. `"vars.X.output.Id"`) — `flow validate` does not catch this; it manifests at runtime as the wrong value bound to the activity input (MST-9107). Do NOT use `=js:` on condition expressions (decision `expression`, switch case `expression`, HTTP branch `conditionExpression`) — those are always evaluated as JS automatically. 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 underlying expression system.
-12. **Always run `flow tidy` after edits** — `uip maestro flow tidy <ProjectName>.flow` is the canonical layout step. Tidy arranges nodes horizontally, sets every node's `size` to `{ "width": 96, "height": 96 }`, and recurses into subflows (`subflows[<id>].layout`). Skipping tidy is the most common cause of misshapen rectangles in Studio Web.
-13. **Don't hand-write `layout.nodes` or `subflows[<id>].layout`** — these are owned by `flow tidy`. When authoring nodes, any placeholder `position` is fine (e.g. `{ x: 0, y: 0 }`); tidy rewrites it on save. Sticky notes (`type: "stickyNote"`) are the one exception — tidy preserves their custom size and position. See [shared/file-format.md — Layout](../shared/file-format.md#layout).
-14. **Every node that produces data MUST have `outputs` on the node instance** — Without an `outputs` block, downstream `$vars` references will not resolve at runtime. Action nodes need `output` + `error`; trigger nodes need `output` only; end/terminate nodes do not use this pattern. See [shared/file-format.md — Node outputs](../shared/file-format.md#node-outputs). **Wrong:** relying on `outputDefinition` in `definitions` alone. **Right:** `outputs` on the node instance itself.
-15. **Node instances have no `model` block** — BPMN type, serviceType, version, event definitions, and all 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), `source` (inline agents), `color`/`content` (sticky notes).
+2. **Default to `Edit` / `Write` for every `.flow` mutation.** Use the `uip maestro flow node` / `edge` / `variable` CLI **only** for the carve-outs called out in [editing-operations.md](references/editing-operations.md) (connector, connector-trigger, inline-agent), or when the user explicitly requests CLI. Edit/Write produces a reviewable line-by-line diff; the CLI returns an opaque "node added" response.
+3. **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.
+4. **ALWAYS check for existing connections** before using a connector node — if no connection exists, tell the user before proceeding. See [connector/impl.md](references/plugins/connector/impl.md) for connection binding details.
+5. **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)).
+6. **`targetPort` is required on every edge** — `validate` rejects edges without it.
+7. **Every node type needs a `definitions` entry** — copy from `uip maestro flow registry get <nodeType>` 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.
+8. **Script nodes must `return` an object** — `return { key: value }`, not a bare scalar.
+9. **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.
+10. **Manage variables with `Edit` against the `.flow` file** — there are no CLI commands for variable management. Use `Edit` to add/remove/update entries in the `variables` section of the `.flow` file. See [shared/variables-and-expressions.md](../shared/variables-and-expressions.md).
+11. **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).
+12. **`=js:` prefix is REQUIRED on every `$vars`/`$metadata`/`$self` reference in a value field.** That includes connector node `inputs.detail.bodyParameters` / `queryParameters` / `pathParameters`, HTTP `url`/`headers`/`body`, end node output `source`, variable update `expression`, loop `collection`, and subflow `inputs.<id>.source`. Without `=js:`, the BPMN runtime sees a literal string (e.g. `"vars.X.output.Id"`) — `flow validate` does not catch this; it manifests at runtime as the wrong value bound to the activity input (MST-9107). Do NOT use `=js:` on condition expressions (decision `expression`, switch case `expression`, HTTP branch `conditionExpression`) — those are always evaluated as JS automatically. 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 underlying expression system.
+13. **Always run `flow tidy` after edits** — `uip maestro flow tidy <ProjectName>.flow` is the canonical layout step. Tidy arranges nodes horizontally, sets every node's `size` to `{ "width": 96, "height": 96 }`, and recurses into subflows (`subflows[<id>].layout`). Skipping tidy is the most common cause of misshapen rectangles in Studio Web.
+14. **Don't hand-write `layout.nodes` or `subflows[<id>].layout`** — these are owned by `flow tidy`. When authoring nodes, any placeholder `position` is fine (e.g. `{ x: 0, y: 0 }`); tidy rewrites it on save. Sticky notes (`type: "stickyNote"`) are the one exception — tidy preserves their custom size and position. See [shared/file-format.md — Layout](../shared/file-format.md#layout).
+15. **Every node that produces data MUST have `outputs` on the node instance** — Without an `outputs` block, downstream `$vars` references will not resolve at runtime. Action nodes need `output` + `error`; trigger nodes need `output` only; end/terminate nodes do not use this pattern. See [shared/file-format.md — Node outputs](../shared/file-format.md#node-outputs). **Wrong:** relying on `outputDefinition` in `definitions` alone. **Right:** `outputs` on the node instance itself.
+16. **Node instances have no `model` block** — BPMN type, serviceType, version, event definitions, and all 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), `source` (inline agents), `color`/`content` (sticky notes).
 
 ## Workflow
 
@@ -79,7 +80,7 @@ Capability index for building new flows (greenfield) and editing existing flows
 - **Never put a `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), `source` (inline agents), and `color` / `content` (sticky notes) live under `inputs`.
 - **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 tidy` before publish or debug** — tidy is the only thing that guarantees square 96×96 nodes and a clean horizontal layout in Studio Web. Hand-written `layout` data with non-96 sizes (e.g., `{ width: 200, height: 80 }`) renders as misshapen rectangles until tidy normalizes the file (the MST-9061 failure mode). See rule #12 above.
+- **Never skip `flow tidy` before publish or debug** — tidy is the only thing that guarantees square 96×96 nodes and a clean horizontal layout in Studio Web. Hand-written `layout` data with non-96 sizes (e.g., `{ width: 200, height: 80 }`) renders as misshapen rectangles until tidy normalizes the file (the MST-9061 failure mode). See rule #13 above.
 - **Never omit `outputs` on nodes that produce data** — action nodes need `output` + `error`, trigger nodes need `output`. The `outputDefinition` in `definitions` is for the registry schema, not for runtime binding — without `outputs` on the node instance, `$vars` references downstream will fail silently.
 - **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.

@@ -23,7 +23,7 @@ Pre-populate these via `TodoWrite` when entering this journey. The list is edit-
 
 **[editing-operations.md](editing-operations.md)** — `Edit` / `Write` is the default for all edits — the `Edit` tool for in-place changes, `Write` only when ≥70% of nodes change. CLI is used only for connector, connector-trigger, and inline-agent nodes (carve-outs), or when you explicitly request it. 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 `uip maestro flow ...`, `Edit`, or `Write` — STOP and ask the user. `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).
+> **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. `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
 

@@ -146,6 +146,8 @@ Use `Edit` to add an edge object to the `edges` array:
 
 **Critical:** `targetPort` is required on every edge. Omitting it produces a validation error.
 
+**Edge ID:** generate a UUID (matches CLI behavior) or use `e-<sourceNodeId>-<targetNodeId>` if uniqueness across the flow is guaranteed. Short, hand-picked names risk collision when the same source/target pair gets a second edge later.
+
 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