@uipath/skills 1.204.0 → 1.204.1

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

@@ -0,0 +1,420 @@
+# Greenfield — Create a New Flow
+
+End-to-end journey for creating a Flow project from scratch. Author terminates at `validate` + `format`. To publish, run, or debug after this, see [operate/CAPABILITY.md](../operate/CAPABILITY.md).
+
+> **Brownfield edits use a different journey.** If the `.flow` file already exists, see [brownfield.md](brownfield.md) instead.
+
+## Scope gate — count what the request names
+
+Count the steps the request names: services, systems, documents, decisions, approvals, schedules, computations. A domain or an outcome ("shipment tracking", "our onboarding") is not a step, and neither is the project name.
+
+**Zero steps → scaffold only.** Run Steps 0–2 in full, then 5–6. Drop the whole Step 3 tail from the T1 chain — no `node add`, no `registry pull`, no `registry get`, no `registry search`, no `uip is connections list`, no `uip df entities list`. The chain's placeholder `core.action.http.v2` is a node the request never asked for; do not copy the chain verbatim. Leave the flow exactly as Step 2 produced it; a bare manual trigger passes `validate` and `format`. Report what the flow should do as **Open Questions** in the [Completion Output](#completion-output).
+
+That is the finished deliverable, not a stall: a non-interactive run ([SKILL.md rule #5](../../SKILL.md)) ends the same way rather than inventing a pipeline from the domain word.
+
+**Zero steps:** "Automate our shipment tracking with a new UiPath Flow project called ShipmentTracker" → scaffold, validate, stop.
+
+**Three steps:** "Build a flow that watches a SharePoint folder, extracts invoices with IxP and POSTs to SAP" → build all of it.
+
+**Borderline — two steps:** "Check the weather for the Bellevue office and tell me if it's a nice day" → outcome-shaped, but it names a lookup and a threshold decision. Build it. An outcome sitting next to a step does not cancel the step.
+
+## Should you plan first?
+
+For complex flows, produce a plan before building. Reference [planning-arch.md](planning-arch.md) and [planning-impl.md](planning-impl.md) for the node type catalog, port reference, wiring rules, and topology patterns.
+
+**Plan when:**
+- The flow has 5+ nodes with branching or parallel paths
+- The flow uses connectors or resources that need discovery
+- The user's requirements are ambiguous and you need to confirm the approach
+
+**Don't plan when:**
+- Adding/editing a single node in an existing flow (use [brownfield.md](brownfield.md))
+- The flow is a straightforward linear pipeline (trigger → action → action → end)
+- The user has already described the exact topology they want
+
+**Skipping the plan never skips the node choice.** Two outcomes (*if … otherwise …*) = a `core.logic.decision` node with both `true`/`false` ports wired — never a Script ternary ([decision/planning.md](plugins/decision/planning.md)); three or more outcomes → `core.logic.switch`; a named external service → the Step 3 registry ladder below.
+
+### Examples
+
+**Plan:** "Build a flow that receives a Jira ticket, classifies it with an AI agent, routes urgent tickets to Slack and non-urgent to a queue, and logs everything to a Google Sheet."
+→ Multiple services, branching logic, connector discovery needed. Plan first.
+
+**Don't plan:** "Create a flow that calls an API and sends the result to Slack."
+→ Linear pipeline, user knows what they want. Build directly, ask questions inline if needed. **"Build directly" skips the plan doc, not the registry search** — you still `registry search` each named service and pick a node type via the Step 3 ladder.
+
+**Judgment call:** "Build me a flow that processes invoices."
+→ Ambiguous requirements. Ask clarifying questions; plan if answers reveal complexity.
+
+## Three-turn execution map
+
+Steps 0–6 are **logical phases**, not separate turns. A typical greenfield build collapses to **three assistant turns** (universal SKILL.md rule #10). Each step heading below carries a `[T1]` / `[T2]` / `[T3]` tag — emit every tool call inside the same Turn as one assistant message.
+
+| Turn | Steps | What you emit in ONE assistant message |
+|---|---|---|
+| **T1 — Setup + discovery** | 0, 1, 2, 3 | One chained `Bash` (scaffold + register + pull + `node add` for each CLI-owned node) **+** parallel `Bash` (one `registry get` per OOTB type you'll inline) **+** parallel `Read` (plugin `impl.md`s). **If existing `.uipx` solutions are present, the Step 2 gate fires first in its own turn** — resolve it before this chain. |
+| **T2 — Read + author** | 4 | One `Read` of the `.flow` **+** a batch of `Edit` calls (or one `Write` if ≥70% of nodes change). Claude Code serializes Edits on the same file, so they don't race |
+| **T3 — Finalize** | 5, 6 | One chained `Bash` (`node configure && validate && format`). On validate failure: one Edit turn, then re-chain `validate && format` |
+
+### Batching anti-patterns
+
+- **One CLI per turn.** Never issue `solution init`, then `cd`, then `flow init` as three separate Bash calls — chain with `&&`, the `cd` included as its own segment. Same for `node configure && validate && format`.
+- **Sequential `registry get`s.** Emit every `registry get` as a parallel `Bash` in one message alongside the T1 scaffold chain.
+- **Pre-reading a fallback walkthrough before the ladder resolves.** T1's "parallel `Read` (plugin `impl.md`s)" covers node types the Step 3 ladder has already selected. A connector gap is not selected until `uip is connectors metadata` returns; See [Select the node type for each external service](#select-the-node-type-for-each-external-service-runs-even-when-full-planning-is-skipped).
+- **Validating after every Edit.** Validate once at the end of T3 (or after a recovery Edit). Intermediate states are expected to be invalid.
+- **Re-reading the `.flow` every turn.** `Read` once at the start of T2; subsequent `Edit`s in the same conversation don't need re-reading unless an external command (e.g., `node configure`, `format`) rewrites the file between Edits.
+- **`Edit` in the same turn as a `Bash` that mutates the same file.** Parallel tool calls race — separate them across turns.
+- **Two parallel `Edit`s anchored to the same byte range.** Same-file Edits serialize in execution order; if Edit N's `old_string` overlaps text that Edit N-1's substitution removed or shifted, Edit N fails with "string not found." Use the [per-array anchor pattern](#anchoring-parallel-flow-edits--anchor-on-what-you-read-not-on-key-order) — anchor each Edit on its target array's own opening key, never on key order or a shared boundary.
+
+## Step 0 — Resolve the `uip` binary and detect command prefix **[T1]**
+
+See [shared/cli-conventions.md](../shared/cli-conventions.md) for binary resolution, version detection, and the `uip maestro flow` vs `uip flow` command prefix rule. All commands below are written in the `uip maestro flow` form. <!-- uip-check-skip -->
+
+This probe is read-only — emit as a parallel `Bash` alongside the Step 2 scaffold chain. It does not need its own turn.
+
+## Step 1 — Check login status **[T1 — only if needed]**
+
+Greenfield steps 2–6 work without login (`flow init`, `validate`, `format`, registry OOTB nodes, `Edit` / `Write` edits). Login is required only when the registry needs tenant-specific connector/resource nodes, or before handing off to Operate.
+
+```bash
+uip login status --output json
+```
+
+If not logged in and you need tenant nodes:
+
+```bash
+uip login                                          # interactive OAuth (opens browser)
+uip login --authority https://alpha.uipath.com     # non-production environments
+```
+
+When you do need it, emit `uip login status --output json` as a parallel `Bash` inside T1.
+
+## Step 2 — Create a solution, THEN a Flow project inside it **[T1]**
+
+> **A Flow project cannot exist outside a solution** (universal rule in [SKILL.md](../../SKILL.md)). Run `uip maestro flow init` (Step 2b) outside a solution and it now **auto-scaffolds** one — `<Project>Solution/<Project>Solution.uipx` with the project nested at `<Project>Solution/<Project>/` (response carries `Data.AutoCreatedSolution`). Still scaffold or select the solution first (Step 2a) so you set the solution name yourself rather than the auto `<Project>Solution`, and so discovery is unambiguous. The solution and project names are independent — they need not match. The correct layout is **always** `<Solution>/<Project>/<Project>.flow` (double-nested — see the tree after Step 2c). Passing `--skip-solution-registration` opts out of both auto-scaffold and registration, leaving a bare single-nested layout that fails Studio Web upload and packaging.
+
+Check for existing solutions with `find . -maxdepth 2 -type f -name '*.uipx' -print` (each solution is its own folder — `<Solution>/<Solution>.uipx` — so a bare `*.uipx` glob misses them). If any are found, **STOP before the T1 chain — do not run `uip solution init` yet** — and ask the user which solution to use per the dropdown question rule in [SKILL.md](../../SKILL.md) (rules #5 and #6): one option per discovered `.uipx`, a **"Create a new solution"** option, and **"Something else"** last. Rule #5 owns the ask mechanism (structured `AskUserQuestion` where the runtime offers it, a numbered chat list otherwise, recommended-option fallback when non-interactive) — do not re-specify a tool here. Applies even when the user wants a new solution. If none are found, create a new one automatically.
+
+- If the user specifies an existing `.uipx` file path or solution name, use that (skip to Step 2b)
+- Otherwise, create a new solution (Step 2a)
+
+### Canonical T1 chain — issue this as ONE `Bash` call
+
+This is the consolidated command that does Steps 2a + 2b + Step 3 + (optionally) one `node add` per CLI-owned node, in one chained Bash. `node add` signature is `<file> <node-type>` (file first):
+
+```bash
+uip solution init "<SolutionName>" --output json \
+  && cd "<SolutionName>" \
+  && uip maestro flow init "<ProjectName>" --output json \
+  && cd "<ProjectName>" \
+  && uip maestro flow registry pull \
+  && uip maestro flow node add "<ProjectName>.flow" core.action.http.v2 --label "<NodeLabel>" --output json
+```
+
+> **One creation path — never drop the `cd`.** `uip solution init "<SolutionName>"` → `cd "<SolutionName>"` → `uip maestro flow init "<ProjectName>"`, one chain. Without the `cd`, `flow init` runs in the old directory and auto-scaffolds a duplicate `<ProjectName>Solution/` (1-node husk). Never let auto-scaffold create the solution. Finish with exactly one `project.uiproj` — delete strays.
+
+> **Building a Maestro Automate?** Add `--automate` to the `flow init` segment and change nothing else:
+>
+> ```bash
+> && uip maestro flow init "<ProjectName>" --automate --output json \
+> ```
+>
+> Only when the request names **Maestro Automate** as the product. The bare verb does not count — "automate invoice intake with a Flow" asks for a Flow. Anything else, including no signal, leaves the flag off. Steps 3-6 are identical either way — the flag changes the packaged `runtimeOptions.profile`, not how you author the `.flow`. See [SKILL.md rule #6](../../SKILL.md#critical-rules-universal).
+
+Tail-append one `node add` per CLI-owned node (`uipath.connector.*`, `uipath.connector.trigger.*`, `core.action.http.v2`). Each `node add` returns the new node `id` in `Data` — capture it from the chained output for T2/T3. Drop the trailing `node add` segment when the flow is OOTB-only. `core.action.http.v2` in the example stands in for whichever CLI-owned type the Step 3 ladder selected — for a connector that has no curated activity, that is the generated `uipath.connector.custom.<key>.<slug>` node when the connector reports `V4Compatible: true`, and Managed HTTP only when it does not.
+
+In the SAME assistant message (parallel to this chain): emit one `Bash` per OOTB `registry get <NODE_TYPE>` you'll need in T2 (always `core.control.end` — see Step 4), and parallel `Read` calls for any plugin `impl.md`s you'll consult.
+
+> **Older `solution-tool` (< 1.0.0)** used `solution new` (see [.claude/rules/cli-renames.md](../../../../.claude/rules/cli-renames.md)). If `solution init` returns `unknown command`, substitute `solution new`.
+
+The sub-steps below describe what each command in the chain does and how to verify the result.
+
+### 2a. Create a new solution
+
+```bash
+uip solution init "<SolutionName>" --output json
+```
+
+Creates `<cwd>/<SolutionName>/<SolutionName>.uipx`. **`cd` into the new solution directory before Step 2b.**
+
+> **Naming convention:** In **pure greenfield** (no existing solutions), default the solution name to the project name unless the user specifies otherwise. When solutions already exist and the user chooses "Create a new solution", **ask for the new solution's name** — do not reuse the project name (SKILL.md rule #6). The two names are independent.
+
+### 2b. Create the Flow project inside the solution folder
+
+```bash
+cd <directory>/<SolutionName> && uip maestro flow init <ProjectName> --output json
+```
+
+Append `--automate` for a Maestro Automate project (SKILL.md rule #6). The rest of this step, and Steps 3-6, are unchanged.
+
+The `cd` puts the project inside the solution you just created. Skip it and `flow init` won't find that solution (discovery walks **up**, not down into `<SolutionName>/`) — it auto-scaffolds a **second, separate** `<ProjectName>Solution/` beside your empty `<SolutionName>/`, leaving two solutions. The project no longer single-nests, but `cd` first to land in the right one.
+
+> **Bash session state persists across tool calls.** This `cd` is **not scoped to one Bash invocation** — your cwd remains inside `<SolutionName>/` for every subsequent `Bash` call until you `cd` somewhere else. Plan the rest of Step 2 (and Steps 3–6) accordingly: either keep using paths relative to the solution dir, or anchor with `$(pwd)` / the absolute `Data.Path` returned by `flow init`. Do NOT prefix later commands with the original `<directory>/<SolutionName>/...` — that would resolve as `<SolutionName>/<directory>/<SolutionName>/...` and look like a layout bug when it isn't.
+
+`--output json` is required so Step 2c can inspect `Data.SolutionRegistration.Status` to confirm the project was auto-registered with the parent solution.
+
+### 2c. Verify the project is registered in the solution
+
+When `uip maestro flow init` is run from inside a solution directory (Step 2b), it **auto-registers** the project with the nearest parent `.uipx`. Run outside any solution, it **auto-scaffolds** `<Project>Solution/` and registers the project in it — the response then also carries `Data.AutoCreatedSolution` (`{ Name, Path, SolutionFile }`) and `Status: Registered`. Pass `--skip-solution-registration` to opt out of both (Status `OptedOut`, bare single-nested layout). The success envelope always reports the outcome in `Data.SolutionRegistration`:
+
+```json
+{
+  "Result": "Success",
+  "Code": "FlowInit",
+  "Data": {
+    "Status": "Created successfully",
+    "Path": ".../<SolutionName>/<ProjectName>",
+    "SolutionRegistration": {
+      "Status": "Registered",                     // or "AlreadyRegistered"
+      "Solution": ".../<SolutionName>.uipx",
+      "Project": "<ProjectName>/project.uiproj",
+      "ProjectId": "<uuid>"
+    }
+  }
+}
+```
+
+If `Data.SolutionRegistration.Status` is `Registered` or `AlreadyRegistered`, **you are done** with this step — proceed to the layout check. If it is `OptedOut`, you passed `--skip-solution-registration` and the skip was intentional.
+
+**Fallback** — when `Status` is `Skipped` (ambiguous discovery — e.g. multiple `.uipx`), `Failed` (the `.uipx` write failed), or `NotInSolution` (rare — auto-scaffold did not run and no parent `.uipx` was found): wire the project manually.
+
+```bash
+uip solution projects add \
+  <directory>/<SolutionName>/<ProjectName> \
+  <directory>/<SolutionName>/<SolutionName>.uipx
+```
+
+If you ended up with a bare single-nested layout (e.g. `--skip-solution-registration` was passed), **delete the partial scaffold and restart from Step 2a** — do not try to patch the layout by hand. See [diagnose/failure-modes.md — Single-nested layout](../diagnose/failure-modes.md#single-nested-layout).
+
+### Expected layout after Steps 2a–2c
+
+```
+<cwd>/
+└── <SolutionName>/                    ← from `uip solution init`
+    ├── <SolutionName>.uipx
+    └── <ProjectName>/                 ← from `uip maestro flow init` (run from inside <SolutionName>/)
+        ├── <ProjectName>.flow         ← the file you edit
+        ├── project.uiproj
+        ├── bindings_v2.json
+        ├── entry-points.json
+        ├── operate.json
+        └── package-descriptor.json
+```
+
+**Self-check — run this before Step 3:**
+
+After Step 2b your cwd is inside `<SolutionName>/` (the `cd` persists). Verify the flow file using a `$(pwd)`-anchored absolute path so the check is robust to that cwd drift:
+
+```bash
+ls "$(pwd)/<ProjectName>/<ProjectName>.flow"
+```
+
+Equivalent: use the absolute project dir reported by `flow init` in `Data.Path` and append `/<ProjectName>.flow`. Either form gives an absolute path that doesn't depend on the current cwd.
+
+> **Don't write `<SolutionName>/<ProjectName>/<ProjectName>.flow` here.** From inside `<SolutionName>/` that resolves to `<SolutionName>/<SolutionName>/<ProjectName>/<ProjectName>.flow` (triple-nested) and the `ls` will fail even though the layout is correct. That false negative wastes turns chasing a non-bug.
+
+If the file does not exist at the absolute double-nested path, Step 2 is wrong. Delete the partial scaffold and restart from Step 2a — do not try to patch the layout by hand.
+
+**Then assert it is the only one.** `cd` does not persist between tool calls, so a later `uip maestro flow init` issued outside the solution auto-scaffolds `<Project>Solution/` beside the real project rather than failing. Nothing warns you: `flow validate` passes on either file, and the duplicate surfaces only when something globs and resolves to two.
+
+```bash
+find . -name project.uiproj -o -name '*.flow' | sort   # expect exactly one of each
+```
+
+More than one → **delete the stray scaffold.** Do not `mv` it into place — that leaves the original where it was, so you end up with two.
+
+See [shared/file-format.md](../shared/file-format.md) for the full project structure.
+
+## Step 3 — Refresh the registry **[T1 — chained tail of Step 2]**
+
+This is already the last segment of the [canonical T1 chain](#canonical-t1-chain--issue-this-as-one-bash-call) above. Standalone:
+
+```bash
+uip maestro flow registry pull                          # refresh local cache (expires after 30 min)
+```
+
+**Parallel `registry get`** — in the same T1 assistant message, emit one separate `Bash` per OOTB node type whose definition you'll inline in T2. **Always fetch `core.control.end`** — `flow init` does not scaffold one (see Step 4):
+
+```bash
+uip maestro flow registry get core.control.end --output json
+```
+
+> **Auth note**: Without `uip login`, registry shows OOTB nodes only. After login, tenant-specific connector and resource nodes are also available. **In-solution sibling projects** are always available via `--local` without login — see below.
+
+### Select the node type for each external service (runs even when full planning is skipped)
+
+Calling a named external service (Slack, open-meteo, Stripe, any REST API)? **Search first — never guess the node type from the brand name:**
+
+```bash
+uip maestro flow registry search "<service>" --output json --output-filter "[*].{NodeType:NodeType,DisplayName:DisplayName,Description:Description,AvailableOnTenant:AvailableOnTenant}"
+```
+
+Then pick the first match down this ladder:
+
+1. **Curated connector activity** (`uipath.connector.<key>.<op>` in the results) → use it.
+2. **Connector exists but no activity for what you need, and `uip is connectors metadata <key>` reports `V4Compatible: true`** → a generated non-catalog activity ([connector/planning.md — decision order](plugins/connector/planning.md#decision-order), authored per [connector/impl-inline.md](plugins/connector/impl-inline.md)).
+3. **Connector exists but no activity, not `V4Compatible`** → `core.action.http.v2` (connector mode).
+4. **No connector at all** → `core.action.http.v2` (manual mode).
+5. **No API** (desktop app) → [rpa](plugins/rpa/planning.md).
+
+Manual HTTP is the **bottom of the ladder** — only the search returning no connector authorizes it. Picking it without searching is the brand-name shortcut forbidden by [SKILL.md rule #3](../../SKILL.md#critical-rules-universal).
+
+**Resolve rung 2 vs 3 before you open either walkthrough.** When the search shows the connector but no activity for the operation, the fallback is undecided until one more discovery call returns. Emit it in T1 alongside the search and the connections list:
+
+```bash
+uip is connectors metadata <connector-key> --output json --output-filter "[0].Flags"
+```
+
+Read the flag off the `Flags` object the filter returns — the CLI emits it as **`V4Compatible`** (capital `V`), so a filter that names `V4Compatible` returns `Data: []` and reads as "flag absent", which misroutes a rung-2 connector to Managed HTTP. Then open only the walkthrough the flag selects — [connector/impl-inline.md](plugins/connector/impl-inline.md) when it is `true`, [http/impl-connector.md](plugins/http/impl-connector.md) when it is `false` or absent. Do not pre-read the Managed HTTP guide on the guess that the gap will land at rung 3: a fallback doc already in context steers the build toward that node type before the flag has been read. The `core.action.http.v2` in the [canonical T1 chain](#canonical-t1-chain--issue-this-as-one-bash-call) is a placeholder for whichever CLI-owned node the ladder selected, not the default fallback.
+
+**Branching is a node, not a Script.** A requirement phrased as *if … otherwise …* (two outcomes) is a `core.logic.decision` node with both `true`/`false` ports wired ([decision/planning.md](plugins/decision/planning.md)); three or more outcomes → `core.logic.switch`. Do not fold the branch into a Script ternary — the branch must exist as a node in the graph.
+
+### Document-extraction step — route it to IxP (runs even when full planning is skipped)
+
+Pulling **named fields out of documents** (PDFs, scans, receipts, invoices, contracts, forms) is a document-extraction step — its node is an **IxP node** (`uipath.ixp.*`). It's easy to miss because the fetch/post steps around it are ordinary nodes, but the extraction in between is its own node. **Always land a node for it — never leave it out:**
+
+- **Model published** → land the real `uipath.ixp.*` node (skeleton is fine; defer config to Open Questions).
+- **No model published** (`registry search "uipath.ixp"` → `Data: []`) → land a `core.logic.mock`.
+
+See [plugins/ixp/impl.md — Landing the node when you cannot fully configure it](plugins/ixp/impl.md#landing-the-node-when-you-cannot-fully-configure-it).
+
+**In-solution discovery (no login required):**
+
+```bash
+uip maestro flow registry list --local --output json     # discover sibling projects in the same .uipx solution
+uip maestro flow registry search "<keyword>" --local --output json  # keyword search across in-solution nodes
+uip maestro flow registry get "<node-type>" --local --output json  # get full manifest for a local node
+```
+
+Run from inside the flow project directory. Returns the same manifest format as the tenant registry. Use `--local` to wire in-solution resources (RPA, agents, flows, API workflows) without publishing them first. `search --local` omits `AvailableOnTenant` — drop it from `--output-filter` projections.
+
+## Step 4 — Build the flow **[T2]**
+
+> **`flow init` scaffolds ONLY the manual trigger (`start` / `core.trigger.manual`) with zero edges.** Every other user-owned node — **including the End node** — is yours to add via `Edit` / `Write`. Any HTTP / connector / connector-trigger node you `node add`-ed in T1 is already in `nodes[]` and `definitions[]` but has empty `inputs.detail` (filled in T3) and is not wired yet.
+
+### T2 batch — issue these in ONE assistant message
+
+1. **One `Read`** of `<ProjectName>.flow` — required before any Edit/Write; T1's chained Bash mutated the file and Claude Code's file-state tracker does not auto-refresh on external mutations.
+2. **A batch of parallel `Edit` calls** — **exactly one per top-level array you touch**, each carrying EVERY new entry for that array. Never one `Edit` per node; node count does not change the call count. Same-file Edits serialize in execution order, so each `old_string` must anchor to text NO OTHER parallel Edit modifies. Use the **per-array anchor pattern** below.
+   - Edit `nodes[]` — every user-owned node in one call, End included.
+   - Edit `definitions[]` — one entry per unique `type:typeVersion`, pasted verbatim from T1's `registry get` output.
+   - Edit `edges[]` — the whole wiring in one call.
+   - Edit `variables.globals` — every `in` / `out` variable the flow declares. Needed before an End node can map an output to one.
+   - Edit `layout.nodes` — placeholder `{ position: { x: 0, y: 0 }, size: { width: 96, height: 96 }, collapsed: false }` per new node; `format` rewrites both position and size (by node shape) in T3.
+
+   **≥70% of `nodes[]` new → one `Write` of the whole file instead.** That is the normal greenfield shape, and neither node count nor file size disqualifies it (see [editing-operations.md — Tool Selection Ladder](editing-operations.md#tool-selection-ladder)). Below that threshold the per-array `Edit` batch is cheaper, because a whole-file `Write` re-emits the file.
+
+   Two conditions when T1 ran `node add`. First, carry forward **verbatim** from the `Read` every key `node add` touched for each CLI-owned node — the node object, its `definitions[]` entry, its `bindings[]` rows, its `layout.nodes` entry, and its `variables.nodes` bindings ([CAPABILITY.md — Node ownership](CAPABILITY.md#node-ownership--who-authors-the-node) tabulates them). `variables.nodes` is the one `node configure` does not regenerate, and `flow validate` reports `Valid` without it, so a `Write` that drops it leaves the flow silently missing what makes `$vars.<id>.output` resolve until T3's trailing `format` regenerates it ([CAPABILITY.md](CAPABILITY.md#critical-rules) rule 14). Carry it forward rather than relying on that repair. Second, leave T3's `node configure` as the last write to touch `inputs.detail` / `bindings[]` — T3's `validate && format` still chain after it, and `format` touches neither. `node add` leaves `inputs.detail` empty and the `bindings[]` rows unresolved (`resourceKey: ""`), so a `Write` before `configure` costs nothing as long as those keys survive it. A `Write` AFTER `configure` clobbers the filled values, invisibly to `flow validate` — `Edit` in place there, or re-run `configure`. See [CAPABILITY.md — Node ownership](CAPABILITY.md#node-ownership--who-authors-the-node).
+
+#### Anchoring parallel `.flow` Edits — anchor on what you Read, not on key order
+
+> **Do not assume a top-level key order.** The CLI does not guarantee which keys are present or in what sequence — fixtures show `runtime` before `nodes` on one flow and absent on another, and `bindings` / `variables` / `solutionId` / `projectId` / `metadata` appear in varying positions. Any anchor of the form "closing `]` + the NEXT top-level key" is coupled to that ordering and will silently break across CLI versions or between flows. **Anchor on the target array's OWN key instead — you just `Read` the file at the top of T2, so anchor to text that read actually contains.**
+
+Anchor each Edit using its target array's own opening key, located in the text you just Read — not adjacency to a neighbor key. The catch: `"nodes": [` and `"edges": [` are NOT unique in the file. They recur **inside inline `definitions[]`** (an HTTP v2 / agent / subprocess definition embeds its own nested `nodes`/`edges`) **and inside any `subflows.<id>` block** (each subflow holds its own `nodes`/`edges`) — so even a small flow can carry several copies. The reliable, version-independent discriminator is **indentation: the top-level array sits at 2-space indent; every nested one is deeper.** `"definitions": [` and the top-level `"layout": {` appear once each, so they need no disambiguation.
+
+| Edit target | Anchor on (from the text you Read) | How to insert |
+|---|---|---|
+| Append to `nodes[]` | The **2-space-indented** `\n  "nodes": [` (the top-level array — deeper-indented `"nodes": ["` inside definitions do not match the two-leading-space prefix) plus the `start` node's opening `{ "id": "start"`. | Insert the new node object as the first element, immediately after the `[`: `\n    { new node JSON },`. Head-insertion keeps `old_string` clear of the array's closing `]`. |
+| Append to `edges[]` | The **2-space-indented** `\n  "edges": [`. A newly generated scaffold commonly has `\n  "edges": []`; the 2-space prefix distinguishes it from nested `edges` arrays. | When empty, replace `\n  "edges": []` with `\n  "edges": [\n    { new edge JSON }\n  ]`. When non-empty, anchor through the first edge and insert the new edge as the first element. |
+| Append to `definitions[]` | `"definitions": [` plus the first definition's opening bytes. Top-level `definitions[]` is the only one in the file, so this is reliably unique. | Insert the new definition right after the opening `[`, as the first element. Never anchor on whatever key follows `definitions` — that key varies (`runtime`, `bindings`, `variables`, `layout`, depending on CLI version and what the flow contains). |
+| Add to `variables.globals` | `"variables": {` — the only top-level occurrence. `globals` may be absent on a fresh scaffold, in which case anchor on `"variables": {\n    "nodes": [` and insert `"globals": [ ... ],\n    ` before it. | Insert each variable object at the array head. `node add` writes `variables.nodes`, never `globals`, so the two never collide. |
+| Add an entry to `layout.nodes` | `"layout": {\n    "nodes": {\n      "start":` — `start` is the always-present trigger and the first key under `layout.nodes` in newly generated flows. The top-level `"layout": {` is the only one. | `"layout":` + `"start":` jointly disambiguate. Insert `"<newId>": { ... },\n      ` before `"start":`. CLI-owned nodes added via `node add` already have a `layout.nodes` entry — only add entries for nodes you author by hand (e.g. End). |
+
+**Why head-insertion.** Inserting the new element right after the array's opening `[` means the `old_string` never includes the array's closing `]` — so it cannot collide with a closing `]` from a nested object (`form.sections[].fields[]`), and it never references a sibling top-level key whose position is not guaranteed. JSON array element order is not semantically significant for `nodes` / `edges` / `definitions`, so head vs. tail insertion is equivalent; `flow format` normalizes layout regardless.
+
+**Disjointness rule.** Two parallel Edits MUST anchor on DIFFERENT top-level arrays — nodes-Edit on the top-level `nodes[]`, edges-Edit on the top-level `edges[]`, definitions-Edit on `definitions[]`, layout-Edit on `layout.nodes`. Because each anchors on its own array (not a shared boundary), the parallel Edits never overlap — provided each anchor is unique first (see below).
+
+**Pre-flight uniqueness check.** Before submitting an Edit, confirm your `old_string` appears **exactly once** in the file you Read. `"definitions": [` and the top-level `"layout": {` are reliably unique. `"nodes": [` and `"edges": [` are NOT — they recur inside inline definitions and subflows, so anchor on the **2-space-indented** occurrence and extend through the first element's opening (e.g. `"id": "start"`) until the match count is one. Never anchor on a bare bracket shape, and never assume the first textual occurrence is the top-level one.
+
+**Safer fallback when in doubt:** serialize the Edits across two turns. One extra turn is cheaper than a failed-Edit recovery loop (which forces a re-Read, a re-derived anchor, and a re-submit).
+
+See [shared/file-format.md — Top-level structure](../shared/file-format.md#top-level-structure) for which top-level keys exist and the note that their order is not guaranteed.
+
+> **Intra-turn ordering.** If a parallel `Edit` fails with "file not read," split `Read` into its own turn (cost: +1 turn).
+
+### Node ownership recap
+
+> **Before each node, 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`.**
+
+Edit `<ProjectName>.flow` directly in the project root. The `bindings_v2.json` file is also in the project root for resource bindings.
+
+> **Tool selection by ownership.** Use `Edit` for in-place changes to user-owned nodes; `Write` when ≥70% of nodes change **and `node configure` has not run yet** (a full-file `Write` after it clobbers connector / managed-HTTP `bindings[]` — see the Step 4 `Write` note above). For CLI-owned nodes (above), use `uip maestro flow node add` + `node configure` — see the relevant plugin's `impl.md` for the full configuration workflow. Inline-agent project scaffolding uses `uip agent init --inline-in-flow`, but inline-agent flow node/wiring edits are direct `.flow` JSON (the agent node itself is user-owned).
+
+Read [editing-operations.md](editing-operations.md) for strategy selection and per-operation recipes.
+
+> **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).
+
+For each node type, follow the relevant plugin's `impl.md` for node-specific inputs, JSON structure, and configuration. The operations guides cover the mechanics (how to add/remove/wire); the plugins cover the semantics (what inputs and model fields each node type needs).
+
+## Step 5 — Validate **[T3 — chain with Step 6, plus any T1 `node configure`]**
+
+### Canonical T3 chain — issue this as ONE `Bash` call
+
+```bash
+uip maestro flow node configure "<ProjectName>.flow" "<httpNodeId>" --detail '<DETAIL_JSON>' --output json \
+  && uip maestro flow validate "<ProjectName>.flow" --output json \
+  && uip maestro flow format "<ProjectName>.flow" --output json
+```
+
+`<DETAIL_JSON>` is node-type-specific — the schema is owned by each CLI-owned node's plugin, not duplicated here: HTTP → [http/impl.md](plugins/http/impl.md#critical-use-node-configure), connectors → [connector/impl.md](plugins/connector/impl.md), connector triggers → [connector-trigger/impl.md](plugins/connector-trigger/impl.md). Tail-append one `node configure` per CLI-owned node added in T1, using the node IDs captured from T1's chained output. Drop the entire `node configure` segment if no CLI-owned nodes exist.
+
+> **The plugin `impl.md` is authoritative — follow its full procedure, not just its `--detail` schema, and let it override this turn map.** A plugin may prescribe steps the three-turn collapse does not show — most importantly a **pre-`configure` live fetch** whose output you must read before you can author `--detail` (the value depends on the live response, so it cannot be guessed or copied from a doc example). When `impl.md` defines such a step, run it in its **own turn before T3** and build `--detail` from its result; do not batch it into the chain, skip it, or hand-author the payload. An empty or static base response is expected for these steps and is not a signal the step is unavailable. This is general to every CLI-owned node type — defer to the owning `impl.md` rather than assuming static config.
+
+**On validate failure:** one `Edit` turn to fix, then re-chain `validate && format` in one Bash. Do not validate after every individual Edit during T2 — intermediate states are expected to be invalid.
+
+> **A passing exit code with warnings is NOT done.** `flow validate` returns 0 even when `Data.Warnings` is non-empty — read the warnings, don't just check the exit code. Three classes are build failures, not advisories:
+>
+> | Warning | What it means at debug time | Resolve by |
+> | --- | --- | --- |
+> | `mentions the "<connector>" connector keyword but uses the generic Managed HTTP type core.action.http.v2 with no connection binding` | The flow took the brand-name shortcut and runs against an undefined endpoint | Switch to the connector node (see [SKILL.md rule #3](../../SKILL.md#critical-rules-universal) and the anti-pattern list) |
+> | `declares no inputs in its agent.json \`inputSchema\`, but the flow node binds N inputs … these bindings are silently dropped` | The inline agent never receives the flow's data, so its output is unrelated to the run. Nothing faults, and with an empty `outputSchema` the fields downstream nodes read come back `undefined` | Add the warning's named keys to `inputSchema.properties` **and** read each one as `{{input.<key>}}` in `messages[].content` — a key no prompt token reads never reaches the model, and `refresh` regenerates `contentTokens` without adding the reference. Then `uip agent refresh --inline-in-flow` and `uip agent validate --inline-in-flow` ([inline-agent/impl.md § Wiring Flow Variables into Agent Prompts](plugins/inline-agent/impl.md#wiring-flow-variables-into-agent-prompts)) |
+> | `Expression at this field is not valid JavaScript` / `[EXPRESSION_DIAGNOSTIC] Cannot find name '…'` | The expression throws or evaluates to garbage | Fix the syntax before debug |
+>
+> Treat all three as a build failure for your own definition of "done."
+
+### Common error categories
+
+- **Missing targetPort** — every edge needs a `targetPort` string
+- **Missing definition** — every `type:typeVersion` in nodes needs a matching `definitions` entry
+- **Invalid node/edge references** — `sourceNodeId`/`targetNodeId` must reference existing node `id`s
+- **Duplicate IDs** — node and edge `id`s must be unique
+
+## Step 6 — Format node layout **[T3 — chained tail of Step 5]**
+
+This is the last segment of the [canonical T3 chain](#canonical-t3-chain--issue-this-as-one-bash-call) above. After validation passes, format must run before publishing or debugging (see "Always run `flow format` after edits" in [the Author capability index](CAPABILITY.md)). Format:
+
+- Arranges nodes horizontally (left-to-right) using ELK with `nodeSpacing: 96`, anchored to the leftmost node's original position
+- Sets each non-stickyNote node's `size` by its canvas shape so Studio Web renders it correctly: inline agents (`shape: rectangle`) → `{ "width": 288, "height": 96 }`, containers (loops/groups) → `{ "width": 560, "height": 320 }`, everything else (incl. referenced `uipath.core.agent.<guid>`) → `{ "width": 96, "height": 96 }` (skipping this leaves stale dimensions intact and produces misshapen nodes)
+- Recurses into subflows and rewrites `subflows[<id>].layout`
+- Backfills missing `position`/`size` entries
+
+Standalone (only if not chained from Step 5):
+
+```bash
+uip maestro flow format <ProjectName>.flow --output json
+```
+
+## Completion Output
+
+When you finish building the flow, report to the user:
+
+1. **File path** of the `.flow` file created
+2. **What was built** — summary of nodes added, edges wired, and logic implemented
+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, and which skill to use
+6. **Missing connections** — any connector nodes that need connections the user must create
+7. **Open Questions** — every step the request left undecided, each prefixed `**[REQUIRED]**` or `**[OPTIONAL]**`. On the scaffold-only path ([Scope gate](#scope-gate--count-what-the-request-names)) there are no decided steps, so state the outcome the user asked for and ask which steps it needs — the scaffold records no intent on its own
+8. **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** | 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 (e.g., "just leave it", "pack but don't publish", "upload to a different tenant"). |
+
+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 of these actions without explicit user selection. Once the option is settled, read [operate/CAPABILITY.md](../operate/CAPABILITY.md) and follow that capability's flow — do not run operate commands from inside this doc.