@uipath/skills 1.195.0

package/skills/uipath-maestro-flow/.maintenance/check-versions.sh

@@ -0,0 +1,160 @@
+#!/bin/bash
+# Verify this skill never pins a .flow version as authoritative in prose, and
+# never hardcodes the top-level .flow `version` literal.
+# Usage: bash .maintenance/check-versions.sh [file1.md ...]
+# Output: BAD lines per violation, then "lines_checked=N violations=M" summary.
+#
+# Rationale: the .flow top-level `version` and node `typeVersion` are owned by
+# `uip maestro flow init` / `uip maestro flow registry get`. Hardcoding them in
+# docs rots silently when the CLI/registry advances (e.g. core.action.http.v2
+# 2.0 -> 2.1, core.trigger.scheduled 1.0 -> 1.1, top-level 1.1 -> 1.2). The rule
+# is: reference the live command, never pin the number as "current"/"required".
+#
+# Two violation classes (both high-confidence — chosen to NOT re-flag the many
+# legitimate illustrative `"typeVersion": "1.0"` JSON examples that are governed
+# by an adjacent registry-sourcing note):
+#
+#   1. PROSE-PIN  — prose that states a version as current or mandatory, e.g.
+#      `currently "1.1"`, `the registry currently emits "1.0"`, `must be "2.0"`,
+#      `use version "1.0"`. These claims go stale.
+#   2. TOPLEVEL   — a hardcoded top-level `.flow` `"version": "x.y"` literal.
+#      Top-level version must always be the `uip maestro flow init` placeholder
+#      (e.g. `"<version from \`uip maestro flow init\`>"`), never a number.
+#
+# Explicitly NOT flagged:
+#   - `"typeVersion": "x.y"` literals in node JSON examples (legitimate when
+#     paired with a sourcing note; too many true-illustrative cases to flag).
+#   - `bindings_v2.json` `"version": "2.0"` — a fixed schema constant, not a
+#     .flow version. Distinguished by the surrounding `"resources"` key.
+#
+# Skipping: add `<!-- version-check-skip -->` anywhere on a line to suppress it
+# (e.g. a historical/version-comparison note that documents an old literal on
+# purpose). For table rows, place the marker inside a cell.
+#
+# Scans SKILL.md + references/**/*.md. Skips .maintenance/ and root scratch
+# files (PLAN.md, PR_BODY.md). Exits non-zero if any violation is found.
+
+set -e
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT" || exit 1
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "python3 not found on PATH" >&2
+  exit 2
+fi
+
+FILES=("$@")
+if [ "${#FILES[@]}" -eq 0 ]; then
+  while IFS= read -r f; do
+    FILES+=("$f")
+  done < <({ [ -f SKILL.md ] && echo "./SKILL.md"; /usr/bin/find ./references -type f -name '*.md' 2>/dev/null; } | /usr/bin/sort)
+fi
+
+if [ "${#FILES[@]}" -eq 0 ]; then
+  echo ""
+  echo "lines_checked=0 violations=0"
+  exit 0
+fi
+
+python3 - "${FILES[@]}" <<'PY'
+import re, sys
+
+files = sys.argv[1:]
+
+SKIP_MARKER = "<!-- version-check-skip -->"
+
+# A quoted version literal: "1.0", "1.1", "2.0", "1.0.0", etc.
+VER = r'"\d+\.\d+(?:\.\d+)?"'
+
+# Class 1 — PROSE-PIN: a version literal stated as current / mandatory.
+# Two sub-patterns (note: docs wrap versions in backticks, e.g. `"1.1"`, so the
+# gap class must NOT exclude backticks):
+#   (a) a pinning verb followed within a short window by a version literal —
+#       `currently "1.1"`, `the registry currently emits "1.0"`, `must be "2.0"`.
+#   (b) an inline assignment of a version field to a literal in prose —
+#       `typeVersion: "2.0"`, `version: "1.1"` (the original http/impl.md:27 bug
+#       had no pin-verb — it just stated `typeVersion: "2.0"`).
+PROSE_PIN_VERB = re.compile(
+    r'(currently|current\b|must be|use version|emits|emit|is currently|as of)'
+    r'[^\n]{0,40}?' + VER,
+    re.IGNORECASE,
+)
+PROSE_PIN_ASSIGN = re.compile(
+    r'(typeVersion|version)\s*[:=]\s*' + VER,
+    re.IGNORECASE,
+)
+
+def prose_pin(line):
+    return PROSE_PIN_VERB.search(line) or PROSE_PIN_ASSIGN.search(line)
+
+# Class 2 — TOPLEVEL: a hardcoded top-level `.flow` `"version": "x.y"`.
+# Only the .flow document's OWN top-level version is in scope — NOT
+# `definitions[].version` (node manifest versions), NOT eval-file `version`,
+# NOT `bindings_v2.json` `version`, NOT `connectorDetail.configuration.version`.
+# We identify a true top-level .flow version by its sibling keys: a real .flow
+# object has `"nodes"` and `"edges"` (and usually `"name"`) within a few lines.
+# Definitions entries instead carry `"nodeType"`; bindings_v2 carries
+# `"resources"`; eval files carry `"evaluatorRefs"` / `"evaluatorTypeId"` /
+# `"evaluations"`. Presence of any of those disqualifies the match.
+TOPLEVEL = re.compile(r'"version"\s*:\s*' + VER)
+
+_FLOW_SIBLINGS = ('"nodes"', '"edges"')
+_DISQUALIFY = ('"nodeType"', '"resources"', '"evaluatorRefs"',
+               '"evaluatorTypeId"', '"evaluations"', '"connectorDetail"')
+
+def is_flow_toplevel_version(lines, idx):
+    # Look at a window around the `"version"` line for the discriminating keys,
+    # bounded to the current fenced block so it never bleeds into an adjacent
+    # JSON example (e.g. a following `definitions` entry with `"nodeType"`).
+    lo = idx - 1
+    while lo >= 0 and not lines[lo].strip().startswith("```"):
+        lo -= 1
+    lo += 1
+    hi = idx + 1
+    while hi < len(lines) and not lines[hi].strip().startswith("```"):
+        hi += 1
+    window = "\n".join(lines[lo:hi])
+    if any(k in window for k in _DISQUALIFY):
+        return False
+    return all(k in window for k in _FLOW_SIBLINGS)
+
+lines_checked = 0
+violations = 0
+
+for path in files:
+    try:
+        with open(path, encoding="utf-8") as fh:
+            lines = fh.read().splitlines()
+    except OSError:
+        continue
+
+    in_fence = False
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        # Track fenced code blocks so PROSE-PIN only fires on real prose.
+        if stripped.startswith("```"):
+            in_fence = not in_fence
+            continue
+        lines_checked += 1
+        if SKIP_MARKER in line:
+            continue
+
+        # Class 1: prose only (outside fences).
+        if not in_fence and prose_pin(line):
+            print(f"BAD  {path}:{i+1}  PROSE-PIN — version stated as current/required; reference `registry get`/`flow init` instead")
+            print(f"       {stripped[:140]}")
+            violations += 1
+            continue
+
+        # Class 2: top-level `.flow` "version" literal — JSON examples only,
+        # and only when the surrounding object is a genuine .flow document.
+        if in_fence and TOPLEVEL.search(line) and is_flow_toplevel_version(lines, i):
+            print(f"BAD  {path}:{i+1}  TOPLEVEL — hardcoded top-level `.flow` `version` literal; use the `uip maestro flow init` placeholder")
+            print(f"       {stripped[:140]}")
+            violations += 1
+
+print()
+print(f"lines_checked={lines_checked} violations={violations}")
+sys.exit(1 if violations else 0)
+PY

package/skills/uipath-maestro-flow/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: uipath-maestro-flow
+description: "Always invoke for `.flow` files OR when the user asks what IxP / document-extraction models are available in Maestro. UiPath Maestro Flow (.flow) — build, edit, run, debug, fix, evaluate. Create, connect nodes; connector, approval, script, subflow, ixp; list IxP / document-extraction models for a flow; triggers, schedules; validate. Upload, publish, manage runs, instances. Diagnose errors, incidents, traces. Design eval sets, evaluators, run Studio Web evals via `uip maestro flow eval`. `uip maestro flow` CLI. For C#/XAML→uipath-rpa. For agents→uipath-agents."
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
+---
+
+# UiPath Flow Skill
+
+Comprehensive guide for creating, editing, validating, debugging, publishing, diagnosing, and evaluating UiPath Flow projects using the `uip` CLI and `.flow` file format. The skill is organized into four capabilities — **Author**, **Operate**, **Diagnose**, **Evaluate** — each with its own index doc.
+
+## When to use this skill
+
+**Author** — building or editing a `.flow` file. Read [references/author/CAPABILITY.md](references/author/CAPABILITY.md).
+
+- Create a new Flow project (`uip maestro flow init`)
+- Edit a `.flow` file — add nodes, edges, variables, subflows, transforms, triggers
+- Explore available node types via the registry
+- Validate or format a Flow file locally
+- Apply Node ownership — Edit/Write for user-owned nodes, CLI for CLI-owned nodes (see Author capability)
+- Configure connector, connector-trigger, or managed HTTP nodes; scaffold inline-agent projects
+- Plan a complex flow before building
+
+**Operate** — publishing, running, or managing a deployed flow. Read [references/operate/CAPABILITY.md](references/operate/CAPABILITY.md).
+
+- Push a flow to Studio Web (`uip solution upload`)
+- Deploy a flow to Orchestrator (`uip maestro flow pack` + `uip solution publish`)
+- Debug a flow end-to-end against real systems
+- Trigger a deployed process
+- Check job status or stream traces
+- Pause, resume, cancel, or retry a running instance
+
+**Diagnose** — investigating a failed or misbehaving run. Read [references/diagnose/CAPABILITY.md](references/diagnose/CAPABILITY.md).
+
+- Triage a failed `flow debug` or deployed process run
+- Read incidents, runtime variables, deployed BPMN
+- Recognize known failure modes (MST-9107, MST-9061, HITL-stuck, reused reference IDs, single-nested layout)
+
+**Evaluate** — designing and running evaluations against a deployed flow. Read [references/evaluate/CAPABILITY.md](references/evaluate/CAPABILITY.md).
+
+- Create evaluators (`exact-match`, `json-similarity`, `contains`, `llm-judge-*`) for a Flow project
+- Create eval sets, add data points (test cases), pin entry points
+- Start Studio Web eval runs, poll status, fetch results, compare runs
+- Decide whether to call `uip solution upload` (almost always: don't auto-run; ask first)
+
+## Capability router
+
+| I want to...                                                 | Read                                                                                             |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| Create a new flow or edit an existing one                    | [references/author/CAPABILITY.md](references/author/CAPABILITY.md)                               |
+| Publish, deploy, debug, or manage a flow's lifecycle         | [references/operate/CAPABILITY.md](references/operate/CAPABILITY.md)                             |
+| Diagnose a failed or misbehaving flow run                    | [references/diagnose/CAPABILITY.md](references/diagnose/CAPABILITY.md)                           |
+| Design and run evaluations (`uip maestro flow eval`)         | [references/evaluate/CAPABILITY.md](references/evaluate/CAPABILITY.md)                           |
+| Look up CLI command syntax                                   | [references/shared/cli-commands.md](references/shared/cli-commands.md)                           |
+| Look up CLI conventions (`--output json`, `--output-filter`, login, FOLDER_KEY) | [references/shared/cli-conventions.md](references/shared/cli-conventions.md)                     |
+| Understand the `.flow` JSON format                           | [references/shared/file-format.md](references/shared/file-format.md)                             |
+| Understand variables and `=js:` expressions                  | [references/shared/variables-and-expressions.md](references/shared/variables-and-expressions.md) |
+| Wire one node's output into another node's input             | [references/shared/node-output-wiring.md](references/shared/node-output-wiring.md)               |
+| Look up action-node boilerplate shared across plugin `impl.md`s | [references/shared/action-nodes.md](references/shared/action-nodes.md)                           |
+| Narrate progress + maintain todos (opt-in — when user wants verbosity) | [references/shared/ux-narration-and-todos.md](references/shared/ux-narration-and-todos.md)       |
+
+## Critical rules (universal)
+
+These rules apply across all three capabilities. Each capability index adds capability-scoped rules on top.
+
+1. **ALWAYS use `--output json` and prefer `--output-filter` for extraction** on all `uip` commands when parsing output programmatically. `--output-filter <jmespath>` is a global CLI flag applied to the `Data` envelope before printing — write expressions starting at `Data` (no `Data.` prefix). Canonical recipe: `uip maestro flow registry search <keyword> --output json --output-filter "[*].{NodeType:NodeType,DisplayName:DisplayName,Description:Description,AvailableOnTenant:AvailableOnTenant}"`. `registry search` returns `Data` as a **flat array of PascalCase objects** (`NodeType`, `DisplayName`, `Description`, `AvailableOnTenant`) — NOT `Data.Nodes`, lowercase `type`, or lowercase `category`. External parsers (`python3 -c`, `jq`) remain valid for transforms JMESPath cannot express; reach for them only after the shape is verified. Full mechanics, fall-back guidance, and shape-inspection probes: [cli-conventions.md §3](references/shared/cli-conventions.md#3-prefer---output-filter-for-extraction).
+2. **Do NOT run `flow debug` without explicit user consent** — debug executes the flow for real (sends emails, posts messages, calls APIs).
+3. **Resource discovery order — search before creating.** When the prompt references an existing resource by name ("use the X agent", "call the Y API workflow", "invoke the Z RPA process"), follow this order strictly before deciding the resource doesn't exist:
+   1. **Tenant registry search** — `uip maestro flow registry search "<name>" --output json`. Requires `uip login`; returns published resources.
+   2. **In-solution local discovery** — `uip maestro flow registry list --local --output json`. No login required; returns sibling projects in the same `.uipx` solution.
+   3. **Only then create/scaffold** — scaffold an inline agent, mock, or create-new-resource only when both searches return no match AND either the user explicitly asks to embed/inline/create, or no published resource can satisfy the requirement.
+
+   The words "coded" and "low-code" describe the _implementation style_ of a published agent — they are NOT synonyms for "inline". `uipath.agent.autonomous` (inline) is only correct when the user explicitly asks to embed/inline/create a new agent inside this flow. Only use `core.logic.mock` when the resource is **not** in the same solution and not yet published. See the relevant resource plugin's `impl.md` (e.g., [rpa](references/author/references/plugins/rpa/impl.md), [agent](references/author/references/plugins/agent/impl.md)).
+
+   **The same "search before deciding it doesn't exist" discipline applies to connector connections.** The connector key MUST come from a `registry search` node type (`uipath.connector.<connector-key>.<activity>`) — never inferred from the service's brand name. The registry key is frequently prefixed or qualified differently than the product name, so a guessed key silently misses the real connector. Any `uip is connections list` used for discovery MUST pass `--all-folders`. An empty result from an unverified key or without `--all-folders` is a false negative, never authoritative — do not conclude "no connection exists" or ask the user to create one until both hold.
+
+   **It also applies to ANY external service named in the prompt — not just in-tenant resources.** Before picking a node type for a named service (Slack, open-meteo, Stripe, any REST API), run `uip maestro flow registry search "<service>" --output json` and follow the [Selecting External Service Nodes](references/author/references/planning-arch.md#selecting-external-service-nodes) ladder (connector → managed HTTP → RPA). Manual `core.action.http.v2` is the bottom of that ladder, chosen only after a search finds no connector — never a first guess from the brand name. This holds even when full planning is skipped (see [greenfield.md — Select the node type for each external service](references/author/references/greenfield.md#select-the-node-type-for-each-external-service-runs-even-when-full-planning-is-skipped)).
+
+4. **Never invoke other skills automatically** — when a flow needs an RPA process, agent, or app, identify the gap and provide handoff instructions. Let the user decide when to switch skills.
+5. **Always present user questions as a dropdown with a "Something else" escape hatch** — Whenever this skill needs a decision from the user (which solution to use, publish vs debug vs deploy, which connector to pick, which trigger type, which resource to bind, etc.), use the `AskUserQuestion` tool with the enumerated choices as options AND include **"Something else"** as the last option so the user can supply free-form string input. Never ask open-ended questions in chat when a finite set of sensible defaults exists. If the user picks "Something else", parse their string answer and continue.
+6. **A Flow project MUST live inside a solution** — always scaffold the solution first (`uip solution init <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. **Narrate progress in plain English only when the user has opted into verbosity — silent by default.** Engage when the user asks for narration / progress ("walk me through it", "show your steps", "verbose", "be detailed") or signals a verbosity preference; otherwise work quietly and surface only decisions, failures, consent gates, and the final result. When engaged: one short line per logical step, in user terms ("checking your tenant login", "adding the Slack node and wiring its inputs", "running validate") — no flag-level or JSON-structure-level detail, applied uniformly across `uip` CLI calls, shell builtins, file edits, and bulk searches. See [shared/ux-narration-and-todos.md](references/shared/ux-narration-and-todos.md) §When to engage.
+8. **Maintain a user-facing `TodoWrite` list only when the user has opted into progress tracking / verbosity.** In silent mode there is no user-facing todo list (the agent MAY track privately). When engaged: any journey above the trivial threshold gets a granular list — one logical step ≈ one todo, granularity per-step not per-phase. The count emerges from the journey's actual steps; do not target a number. 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 the engage triggers, granularity rules, threshold table, and pivot rules.
+9. **Every node has exactly one author — Edit/Write or CLI, never both.** Connector activities (`uipath.connector.<key>.<op>`), connector triggers (`uipath.connector.trigger.<key>.<trigger>`), wait for events (`uipath.connector.event.<key>.<event>` — a mid-flow event wait, configured exactly like a trigger), and managed HTTP (`core.action.http.v2`) are CLI-owned — use `uip maestro flow node add` + `uip maestro flow node configure`. Every other node type — triggers, control flow, logic, HITL, patterns, agents, resource nodes, queue — is user-owned: author the `.flow` JSON directly with `Edit` / `Write`. `inputs.detail` on CLI-owned nodes is a `=jsonString:essentialConfiguration` envelope that the validator rejects when hand-authored. Inline-agent CLI is limited to agent project lifecycle (`uip agent init / validate / migrate --inline-in-flow`); the `uipath.agent.autonomous` flow node itself is user-owned. Scripting languages (`python`, `node`, `jq`, `sed`, `awk`, inline shell heredocs) are a last resort for user-owned edits and require explicit user approval after the trade-offs (state bypass, opaque diff, no interruption point) are surfaced. **Canonical source of truth:** [author/CAPABILITY.md — Node ownership](references/author/CAPABILITY.md#node-ownership--who-authors-the-node) (full table); [author/editing-operations.md — Tool Selection Ladder](references/author/references/editing-operations.md#tool-selection-ladder) (per-operation ladder).
+10. **Batch tool calls into one assistant turn whenever data dependencies allow — minimize wall-clock round-trips.** A typical greenfield build is **3 turns**, not 10+: (T1) one chained `Bash` for scaffold + registry pull + CLI-owned `node add`, in parallel with `registry get` and `Read` calls for any extra discovery; (T2) one `Read` of the scaffolded `.flow` in parallel with the `Edit` / `Write` calls that add the End node and wire edges; (T3) one chained `Bash` for `node configure && validate && format`. Within an assistant message: chain sequential `uip` calls with `&&` in a single `Bash`, and emit independent `Bash` / `Read` / `Edit` calls as parallel tool uses. Only split turns where a later call truly depends on an earlier call's stdout or on a file mutation. See [author/references/greenfield.md — Three-turn execution map](references/author/references/greenfield.md#three-turn-execution-map) for the canonical pattern.
+
+## Anti-patterns (universal)
+
+- **Never use `--format json` on any `uip` command** — the flag is `--output json` (rule #1). `--format` produces `error: unknown option '--format'` and exit code 3 on every `uip` subcommand, not a helpful message pointing you at `--output`.
+- **Avoid piping `uip ... --output json` to `python3 -c` / `jq` for simple field extraction** — use `--output-filter` instead (rule #1). The common failure mode: the agent assumes `Data.Nodes` (or another nested shape) and the external parser silently returns `[]` against `Data`'s actual flat array, prompting a second and third retry with different access paths. `--output-filter` does not rescue a wrong-shape guess by itself — a valid expression that doesn't match (e.g. `"Nodes"` against the flat array) still returns `Data: []` with exit 0; only an *invalid* expression (bad syntax, or a type error like `keys(@)` on an array) exits non-zero. The fix is the pinned shape in rule #1, so you write the right expression on call #1. Reserve external parsers for transforms JMESPath cannot express (multi-step joins, format conversion); when in doubt, verify the shape first — see [cli-conventions.md §3](references/shared/cli-conventions.md#3-prefer---output-filter-for-extraction) for the `type(@)` first-probe sequence (note: `keys(@)` throws on arrays, so use `type(@)` first).
+- **Never run `flow debug` as a validation step** — debug executes the flow with real side effects (rule #2). Use `flow validate` for checking correctness.
+- **Never silently pick the first match from `uip maestro flow registry search`.** When a search returns multiple connectors for the same intent, apply the canonical Connector Disambiguation ladder via [connector/planning.md — Disambiguation](references/author/references/plugins/connector/planning.md#disambiguation--when-search-returns-multiple-connectors-for-the-same-intent), which defers to the Integration Service rules.
+- **Never conclude "no connection exists" from a bare `uip is connections list`** — discovery requires `--all-folders` and a connector key derived from `registry search`, not a brand name (rule #3). Without both, "No connections found" is a false negative; do not surface it as an Open Question or ask the user to create one.
+- **Never write `customFieldsRequestDetails.parameterValues` as a JSON object map** — Studio Web's TS port emits `Map<string,string|null>` via `Array.from(entries())`, so the on-wire shape is `[[key, value], ...]` tuples. Object-form `{key: value}` is rejected by the CLI at validate time. Inner keys are camelCase (`objectActionName`, `parameterValues`), not PascalCase. See [connector/impl.md Step 6c](references/author/references/plugins/connector/impl.md).
+- **Never issue setup or finalization CLI calls one-per-turn.** Each separate Bash call adds a model round-trip — the dominant wall-clock cost. Chain them per rule #10 and the [Three-turn execution map](references/author/references/greenfield.md#three-turn-execution-map).
+
+> **Trouble?** If something didn't work as expected, use `/uipath-feedback` to send a report.

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

@@ -0,0 +1,181 @@
+# Author — Create and edit `.flow` files
+
+Capability index for building new flows (greenfield) and editing existing flows (brownfield). Author owns everything that happens on disk, locally, without `uip login`. Authoring journeys terminate at `validate` + `format`; from there, hand off to [operate/CAPABILITY.md](../operate/CAPABILITY.md) to publish, run, or debug.
+
+> **Where you came from / where to go next.** Author is upstream of Operate (build the flow → ship it) and upstream of Diagnose only via Operate (build → run → diagnose). Publish/run/lifecycle lives in [operate/CAPABILITY.md](../operate/CAPABILITY.md); fault triage lives in [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md).
+>
+> **Inherits universal rules from [SKILL.md](../../SKILL.md)** — `--output json` + prefer `--output-filter` for extraction, no `flow debug` without consent, resource discovery order, never invoke other skills automatically, AskUserQuestion dropdown pattern, solution layout, **plain-English narration + granular `TodoWrite` (opt-in — silent by default; engage when the user asks for verbosity)**. The rules below are author-scoped and apply on top.
+
+## When to use this capability
+
+- Create a new Flow project with `uip maestro flow init`
+- Edit a `.flow` file — adding nodes, edges, or logic
+- Explore available node types via the registry
+- Validate a Flow file locally
+- Manage variables, subflows, expressions, and output wiring
+- Apply Node ownership — who authors the node (see § below)
+- Configure connector, connector-trigger, or managed HTTP nodes; scaffold inline-agent projects
+- Plan a complex flow before building
+
+## Node ownership — who authors the node
+
+Every node in a `.flow` file has exactly one author. The validator enforces this.
+
+**User-owned nodes (Edit / Write directly):**
+
+| Category | Node types |
+| --- | --- |
+| Triggers | `core.trigger.manual`, `core.trigger.scheduled` |
+| Control flow | `core.logic.decision`, `core.logic.switch`, `core.logic.loop`, `core.logic.merge`, `core.control.end`, `core.logic.terminate`, `core.subflow` |
+| Logic | `core.action.script`, `core.action.transform`, `core.logic.delay`, `core.logic.mock` |
+| Human-in-the-loop | `uipath.human-in-the-loop` (inline + app-task forms) |
+| Patterns | `uipath.pattern.batch-transform`, `uipath.pattern.deep-rag` |
+| Agents | `uipath.agent.autonomous` (inline; after `uip agent init --inline-in-flow`) |
+| Resource nodes | `uipath.core.rpa-workflow.*`, `uipath.core.agent.*`, `uipath.core.flow.*`, `uipath.core.agentic-process.*`, `uipath.core.api-workflow.*`, `uipath.core.human-task.*` |
+| Queue | `core.action.queue.create`, `core.action.queue.create-and-wait` |
+
+**CLI-owned nodes (`uip maestro flow node add` + `uip maestro flow node configure`):**
+
+| Category | Node types | Why |
+| --- | --- | --- |
+| 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). |
+| 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)).
+- You may still `Edit` the node's `display.label`, edges, layout, and outputs — those are not part of the envelope.
+
+If you find yourself hand-writing `inputs.detail`, a `=jsonString:` blob, or `bindings[]` entries for a connector node — stop. Use the CLI.
+
+## 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. **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 AskUserQuestion. 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.md](references/plugins/http/impl.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.
+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** — 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.
+12. **Always run `flow format` after edits** — `uip maestro flow format <ProjectName>.flow` is the canonical layout step. Format arranges nodes horizontally, sets every node's `size` to `{ "width": 96, "height": 96 }`, and recurses into subflows (`subflows[<id>].layout`). Skipping format 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 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).
+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).
+
+## Workflow
+
+| Journey | Read |
+| --- | --- |
+| Create a new flow from scratch | [greenfield.md](references/greenfield.md) |
+| Edit an existing flow | [brownfield.md](references/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` |
+| **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) |
+| **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) |
+| **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/) |
+| **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) |
+
+## Anti-patterns
+
+- **Never run `uip maestro flow init` outside a solution directory** — 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 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 edit `content/*.bpmn`** — it is auto-generated from the `.flow` file and will be overwritten.
+- **Never use `core.logic.mock` when the resource is in the same solution** — use `--local` discovery instead. Mock placeholders are only for resources that are not in the current solution and not yet published.
+- **Never hand-write `definitions` entries** — always copy from registry output. Hand-written definitions have wrong port schemas and cause validation failures.
+- **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 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 `inputs.detail` for managed HTTP nodes** — run `uip maestro flow node configure` to populate the `inputs.detail` structure, generate `bindings_v2.json`, and create the connection resource file. Hand-written configurations miss the `essentialConfiguration` block and fail at runtime.
+- **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, not part of the wire key. Strip it and pass an array value of the field's `dataType` (e.g. `"fields.labels[*]"` → `"fields.labels": ["a", "b"]`). Supported only when `[*]` is the name suffix; `[*].` (segments after) is not authorable. `flow validate` misses this; runtime rejects the key. See [connector/impl.md — Step 6b](references/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
+    - [connector/data-fabric](references/plugins/connector/data-fabric/) — Data Fabric entity activities (Query / Create / Update / Delete / Get by ID)
+  - [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
+  - [ixp](references/plugins/ixp/) — published IxP document-extraction models (PDFs, scanned forms, receipts, invoices, contracts)
+  - [queue](references/plugins/queue/) — Orchestrator queue item creation
+
+### Cross-capability (shared)
+
+- [shared/file-format.md](../shared/file-format.md) — `.flow` JSON schema
+- [shared/cli-commands.md](../shared/cli-commands.md) — flat CLI lookup
+- [shared/cli-conventions.md](../shared/cli-conventions.md) — CLI mechanics every capability needs
+- [shared/variables-and-expressions.md](../shared/variables-and-expressions.md) — variable system + `=js:` Jint expressions
+- [shared/node-output-wiring.md](../shared/node-output-wiring.md) — canonical `=js:$vars.X.output.Y` rule

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

@@ -0,0 +1,77 @@
+# Brownfield — Edit an Existing Flow
+
+Recipe-driven journey for targeted changes to an existing `.flow` file. Author terminates at `validate` + `format`. To publish, run, or debug after edits, see [operate/CAPABILITY.md](../../operate/CAPABILITY.md).
+
+> **Greenfield (creating a new flow) uses a different journey.** If the `.flow` file does not yet exist, see [greenfield.md](greenfield.md) instead.
+
+## Read this first
+
+> **Before each node you add or modify, classify it as user-owned or CLI-owned (see [CAPABILITY.md — Node ownership](../CAPABILITY.md#node-ownership--who-authors-the-node)). Connector activities, connector triggers, and `core.action.http.v2` are CLI-only — use `uip maestro flow node add` + `uip maestro flow node configure`, never Edit. Hand-writing these will fail `flow validate`.** The same risk applies when *adding* a connector node to an existing flow as when building a new one.
+
+**[editing-operations.md](editing-operations.md)** — `Edit` is the default tool for in-place changes to user-owned nodes; `Write` only when ≥70% of nodes change. For CLI-owned nodes use the relevant plugin's `impl.md` configuration workflow (`node add` + `node configure`). Read the strategy selection matrix before any modification.
+
+> **Self-check before each mutation:** name the tool you're about to use. If the answer isn't `Edit`, `Write`, or `uip maestro flow ...` — STOP and ask the user via `AskUserQuestion` (per the dropdown rule in [SKILL.md](../../../SKILL.md)). `python`, `node`, `jq`, `sed`, `awk`, and shell heredocs are a last resort and require explicit user approval after you've surfaced the trade-offs. See [editing-operations.md — Tool Selection Ladder](editing-operations.md#tool-selection-ladder).
+
+## Common edits
+
+For each edit, run `uip maestro flow validate` once after **all** edits are complete, then `uip maestro flow format`. Do not validate after each individual change — intermediate states are expected to be invalid.
+
+When a single edit touches more than one top-level array (e.g. insert-a-node hits `nodes`, `edges`, and `definitions`), follow the [parallel same-file Edit rules](editing-operations.md#parallel-same-file-edits) — anchor each Edit on its own array's opening key, never on top-level key order.
+
+| Edit | Description | Guide |
+|------|-------------|-------|
+| **Change a script body or node inputs** | Use `Edit` to modify the node's `inputs` in-place. Do not delete + re-add — that changes the node ID and breaks `$vars` expressions. Script nodes must return an object (`return { key: value }`). | [Edit/Write: Update node inputs](editing-operations-json.md#update-node-inputs) |
+| **Add a node between two existing nodes** | Remove the connecting edge, add the new node, wire upstream → new → downstream. | [Edit/Write: Insert a node](editing-operations-json.md#insert-a-node-between-two-existing-nodes) |
+| **Add a branch (decision node)** | Remove an edge, add a decision node, wire true/false branches. | [Edit/Write: Insert a decision branch](editing-operations-json.md#insert-a-decision-branch) |
+| **Remove a node** | Remove the node, sweep edges/definitions/variables, reconnect upstream to downstream. | [Edit/Write: Remove a node](editing-operations-json.md#remove-a-node-and-reconnect) |
+| **Remove an edge** | Find the edge ID, remove it. | [Edit/Write: Delete an edge](editing-operations-json.md#delete-an-edge) |
+| **Add a workflow variable** | Use `Edit` to modify `variables.globals` in the `.flow` file (Edit-only). For `out` variables, map on every End node. See [shared/variables-and-expressions.md](../../shared/variables-and-expressions.md). | [Edit/Write: Add a workflow variable](editing-operations-json.md#add-a-workflow-variable) |
+| **Update a state variable** | Use `Edit` to add a `variableUpdates` entry for `inout` variables (Edit-only). See [shared/variables-and-expressions.md](../../shared/variables-and-expressions.md). | [Edit/Write: Add a variable update](editing-operations-json.md#add-a-variable-update) |
+| **Create a subflow** | Add a `core.subflow` parent node + `subflows.{nodeId}` with nested nodes/edges/variables (`Edit`-only, or `Write` if scaffolding from template). | [Edit/Write: Create a subflow](editing-operations-json.md#create-a-subflow) + [subflow/impl.md](plugins/subflow/impl.md) |
+| **Add a scheduled trigger** | Replace `core.trigger.manual` with `core.trigger.scheduled`. | [Edit/Write: Replace trigger](editing-operations-json.md#replace-manual-trigger-with-scheduled-trigger) + [scheduled-trigger/impl.md](plugins/scheduled-trigger/impl.md) |
+| **Add a connector trigger** | Remove manual trigger, add connector trigger, configure with connection. | [CLI: Replace trigger](editing-operations-cli.md#replace-manual-trigger-with-connector-trigger) + [connector-trigger/impl.md](plugins/connector-trigger/impl.md) |
+| **Add a resource node** | Discover via registry (`--local` for in-solution, or tenant registry for published), add via `Edit`, wire edges. | Relevant plugin's `impl.md` + [editing-operations-json.md](editing-operations-json.md) |
+| **Add an inline agent node** | Embed a `uipath.agent.autonomous` node with an inline agent definition living inside the flow project. | [inline-agent/planning.md](plugins/inline-agent/planning.md) for selection vs a published agent, [inline-agent/impl.md](plugins/inline-agent/impl.md) for scaffolding, direct `.flow` JSON structure, and validation. |
+| **Add a HITL QuickForm node** | Insert a human approval/review/enrichment checkpoint. Wire the `completed` port after adding. | [Edit/Write: Add a node](editing-operations-json.md) + [hitl/impl.md](plugins/hitl/impl.md) |
+
+The table intentionally routes OOTB structural CRUD to Edit/Write only. There is no CLI opt-in path for non-carve-out flow graph edits.
+
+## After edits
+
+1. **Validate** — `uip maestro flow validate <ProjectName>.flow --output json`. Fix any errors and re-validate.
+2. **Format** — `uip maestro flow format <ProjectName>.flow --output json`. Required before publish or debug (see "Always run `flow format` after edits" in [the Author capability index](../CAPABILITY.md)) — without format, hand-edited or stale `layout` data renders as misshapen rectangles in Studio Web.
+
+## "Refusing to serialize a vX workflow" — migrate first
+
+If `flow format`, `flow debug`, or `flow pack` fails with `[inMemoryWorkflowToFileFormat] Refusing to serialize a vX workflow to the v<current> file format`, the `.flow` file predates the current schema version. Recover with one command:
+
+```bash
+uip maestro flow migrate <ProjectName>.flow --output json
+```
+
+`migrate` is lossless — it walks the per-version migration chain (e.g. `=js:` expression strings become rich expression objects) and bumps the file to the current version. Re-run `flow format` and `flow validate` afterward; both should now pass. **A passing `flow validate` does NOT imply `format`/`debug`/`pack` will pass** — `validate` never re-serializes the workflow, so it skips the version guard those commands enforce. When you see the refusal, always migrate; never assume the edit was wrong.
+
+## Completion Output
+
+When you finish editing the flow, report to the user:
+
+1. **File path** of the `.flow` file edited
+2. **What changed** — summary of nodes/edges added, removed, or modified
+3. **Validation status** — whether `flow validate` passes (or remaining errors if unresolvable)
+4. **Format status** — confirm `flow format` was run
+5. **Mock placeholders** — list any `core.logic.mock` nodes that need to be replaced
+6. **Missing connections** — any connector nodes that need connections the user must create
+7. **What's next** — use `AskUserQuestion` to present the dropdown below (see the AskUserQuestion dropdown rule in [SKILL.md](../../../SKILL.md))
+
+### What's next dropdown
+
+Authoring terminates here. Each option below hands off to Operate — read [operate/CAPABILITY.md](../../operate/CAPABILITY.md) for the command sequence.
+
+| Option | What it does |
+| --- | --- |
+| **Publish to Studio Web** (default) | Push the solution to Studio Web so the user can visualize, edit, and publish from the browser. |
+| **Debug the solution** | Execute the flow end-to-end against real systems. Confirm consent first — debug has real side effects (see the consent-before-debug rule in [SKILL.md](../../../SKILL.md)). |
+| **Deploy to Orchestrator** | Pack and publish directly to Orchestrator (bypasses Studio Web). Only when explicitly chosen — see [/uipath:uipath-platform](/uipath:uipath-platform). |
+| **Something else** | Last option. Accept free-form string input and act on it. |
+
+Do not run any of these actions without explicit user selection. Once the user picks an option, read [operate/CAPABILITY.md](../../operate/CAPABILITY.md) and follow that capability's flow — do not run operate commands from inside this doc.