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

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

@@ -1,6 +1,6 @@
 # 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).
+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.
 
@@ -18,6 +18,8 @@ For complex flows, produce a plan before building. Reference [planning-arch.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."
@@ -50,7 +52,7 @@ Steps 0–6 are **logical phases**, not separate turns. A typical greenfield bui
 
 ## 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 -->
+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.
 
@@ -73,9 +75,9 @@ When you do need it, emit `uip login status --output json` as a parallel `Bash`
 
 ## 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.
+> **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.
+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)
@@ -99,7 +101,7 @@ Tail-append one `node add` per CLI-owned node (`uipath.connector.*`, `uipath.con
 
 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`.
+> **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.
 
@@ -156,7 +158,7 @@ uip solution projects add \
   <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/references/failure-modes.md — Single-nested layout](../../diagnose/references/failure-modes.md#single-nested-layout).
+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
 
@@ -187,7 +189,15 @@ Equivalent: use the absolute project dir reported by `flow init` in `Data.Path`
 
 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.
 
-See [shared/file-format.md](../../shared/file-format.md) for the full project structure.
+**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]**
 
@@ -220,7 +230,9 @@ Then pick the first match down this ladder:
 3. **No connector at all** → `core.action.http.v2` (manual mode).
 4. **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).
+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).
+
+**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)
 
@@ -254,7 +266,7 @@ Run from inside the flow project directory. Returns the same manifest format as
    - Edit `edges[]` — wire `trigger → <httpNode> → end`. End-node `outputs` mapping goes here too if you declared an `out` variable in `variables.globals`.
    - 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.
 
-   `Write` of the whole file is allowed but token-costly on flows >~10 nodes — only fall back to `Write` when ≥70% of nodes change AND the file is small (see [editing-operations.md — Tool Selection Ladder](editing-operations.md#tool-selection-ladder)). **Never `Write` a flow that already has connector / connector-trigger / managed-HTTP nodes** — the rewrite clobbers their CLI-owned `bindings[]` / `inputs.detail` (invisible to `flow validate`); `Edit` in place, or re-run `node configure` as the last write. See [CAPABILITY.md — Node ownership](../CAPABILITY.md#node-ownership--who-authors-the-node).
+   `Write` of the whole file is allowed but token-costly on flows >~10 nodes — only fall back to `Write` when ≥70% of nodes change AND the file is small (see [editing-operations.md — Tool Selection Ladder](editing-operations.md#tool-selection-ladder)). **Never `Write` a flow that already has connector / connector-trigger / managed-HTTP nodes** — the rewrite clobbers their CLI-owned `bindings[]` / `inputs.detail` (invisible to `flow validate`); `Edit` in place, or re-run `node configure` as the last write. 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
 
@@ -277,13 +289,13 @@ Anchor each Edit using its target array's own opening key, located in the text y
 
 **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.
+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`.**
+> **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.
 
@@ -291,7 +303,7 @@ Edit `<ProjectName>.flow` directly in the project root. The `bindings_v2.json` f
 
 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).
+> **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).
 
@@ -311,7 +323,7 @@ uip maestro flow node configure "<ProjectName>.flow" "<httpNodeId>" --detail '<D
 
 **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. The connector-keyword warning (`node "…" mentions the "<connector>" connector keyword but uses the generic Managed HTTP type core.action.http.v2 with no connection binding`) means the flow took the brand-name shortcut and will run against an undefined endpoint at debug time — resolve it by switching to the connector before reporting the flow complete (see [SKILL.md rule #3](../../../SKILL.md#critical-rules-universal) and the anti-pattern list). Treat this class of warning as a build failure for your own definition of "done."
+> **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. The connector-keyword warning (`node "…" mentions the "<connector>" connector keyword but uses the generic Managed HTTP type core.action.http.v2 with no connection binding`) means the flow took the brand-name shortcut and will run against an undefined endpoint at debug time — resolve it by switching to the connector before reporting the flow complete (see [SKILL.md rule #3](../../SKILL.md#critical-rules-universal) and the anti-pattern list). Treat this class of warning as a build failure for your own definition of "done."
 
 ### Common error categories
 
@@ -322,10 +334,10 @@ uip maestro flow node configure "<ProjectName>.flow" "<httpNodeId>" --detail '<D
 
 ## 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:
+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 — the MST-9061 failure mode)
+- 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
 
@@ -345,17 +357,17 @@ When you finish building the flow, report to the user:
 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. **What's next** — ask the user, presenting the dropdown below (see the dropdown question rule in [SKILL.md](../../../SKILL.md))
+7. **What's next** — ask the user, presenting the dropdown below (see the dropdown question rule in [SKILL.md](../../SKILL.md))
 
 ### What's next dropdown
 
-Authoring terminates here. Each option below hands off to Operate — read [operate/CAPABILITY.md](../../operate/CAPABILITY.md) for the command sequence.
+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)). |
+| **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"). |
 
-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.
+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.

package/skills/uipath-maestro-flow/references/author/planning-arch.md

@@ -0,0 +1,342 @@
+# Planning Phase 1: Discovery & Architectural Design
+
+Discover capabilities, then design flow topology: node types, edges, inputs, and outputs. Produce a **mermaid diagram** and structured tables for review before implementation.
+
+> **Registry rules:** `registry search` and `registry list` are allowed for discovery. Run `registry get` once for every OOTB action node type used (`core.action.http`, `core.action.http.v2`, `core.action.script`, `core.action.transform`, queue actions, etc.); this provides real schemas, ports, and required fields. Defer `registry get` for connector nodes requiring `--connection-id` and resource nodes requiring `--local` or published-resource resolution to [Planning Phase 2: Implementation](planning-impl.md).
+
+## Before You Build: Is Maestro the Right Home?
+
+Run this gate before designing topology. Maestro fits long-running cases requiring one durable instance, multiple waits, branching, parallelism, SLAs, cross-product composition, or per-case visibility. A single-wait, mostly linear process may be simpler as a queue + Action Center state machine; if so, stop and hand off to [/uipath:uipath-rpa](/uipath:uipath-rpa) + [/uipath:uipath-platform](/uipath:uipath-platform).
+
+Ask: **Where does the case live now, and where should it live between steps?**
+
+| Factor | Maestro flow | Queue + Action Center |
+| --- | --- | --- |
+| Waits | Several waits, branches, or parallel paths | One human or external wait |
+| Visibility | Need exact current case location | Queue status is sufficient |
+| Topology | Branching, fan-out/merge, SLAs | Mostly linear |
+| Ownership | Team accepts orchestration as an artifact | RPA-only team with queue infrastructure |
+| Composition | RPA, agents, connectors, humans | RPA + Action Center |
+| Overhead | Justified by lifecycle complexity | Not justified for one-shot work |
+
+A single-wait lifecycle is valid queue + Action Center; multi-wait, branched, or visibility-critical lifecycles favor Maestro. For existing RPA projects, keep executors and lift only orchestration; see [brownfield.md — Converting an existing project to Maestro](brownfield.md#converting-an-existing-project-to-maestro).
+
+## Process
+
+1. Analyze the user's requirements.
+2. **Discover capabilities** when connector or resource nodes are needed; run `registry search` / `registry list` (see [Capability Discovery](#capability-discovery)).
+3. Select node types from the [Plugin Index](#plugin-index); read each relevant `planning.md` for heuristics, ports, and key inputs.
+4. Define edges using [Wiring Rules](#wiring-rules) and plugin port documentation.
+5. Identify suspected inputs and outputs for every node.
+6. Generate a mermaid diagram.
+7. Validate mermaid syntax using [Mermaid Validation Rules](#mermaid-validation-rules).
+8. Present the plan for review.
+9. Iterate until approved, then hand off to [Planning Phase 2: Implementation](planning-impl.md).
+
+## Capability Discovery
+
+Run discovery when connector or resource nodes are needed; skip it for OOTB-only flows. Discovery confirms connectors, operations, and published or in-solution resources before topology selection.
+
+```bash
+# Registry should already be refreshed (greenfield.md Step 3 runs `registry pull`)
+uip maestro flow registry search <keyword> --output json
+uip maestro flow registry search outlook --output json
+uip maestro flow registry search "invoice process" --output json
+uip maestro flow registry search agent --output json
+uip maestro flow registry list --output json
+
+# Run `get` for every OOTB action node type used:
+uip maestro flow registry get core.action.script --output json
+# Repeat for transform, queue actions, and every other OOTB action type.
+# `core.action.http.v2` is a managed-HTTP connector node, not OOTB; discover it via
+# [http/planning.md](plugins/http/planning.md).
+```
+
+Without `uip login`, the registry shows OOTB nodes only. If connectors or resources are required, run `uip login status --output json` first. For sibling projects in the same `.uipx` solution, run from the flow project directory:
+
+```bash
+uip maestro flow registry list --local --output json
+uip maestro flow registry search "<keyword>" --local --output json
+```
+
+Prefer in-solution resources over mocks. `--local` omits `AvailableOnTenant`; an empty `search --local` is not authoritative, so confirm with `list --local` before treating a resource as absent.
+
+### Check Connector Connections
+
+For every discovered connector, follow [plugins/connector/planning.md](plugins/connector/planning.md). Never guess a connector key; use the key from registry search. Run:
+
+```bash
+uip is connections list "<connector-key>" --all-folders --output json
+```
+
+`--all-folders` is mandatory; plain `uip is connections list "<connector-key>"` is forbidden for discovery. Record a connection only when `IsDefault: Yes` and `State: Enabled`.
+
+Treat an empty result as suspicious. Treat it as a real absence only when: (a) the key came from `registry search`, (b) `--all-folders` was used, and (c) a `--refresh` retry was also empty. Only then put the gap in **Open Questions**; do not ask about connection creation before verification. See [connector/impl.md](plugins/connector/impl.md) for the shared empty-result recovery path.
+
+Record:
+
+- **Connectors:** existence, available operations from node type names, and healthy connection availability. Defer field details to Phase 2.
+- **Resources:** check `list --local` or `search --local` first, then tenant registry; record whether each RPA process, agent, or flow exists. Defer schemas to Phase 2.
+- **Gaps:** use `core.action.http.v2` manual mode when no connector exists; use `--local` resources when unpublished but in solution; use `core.logic.mock` when a resource is neither in solution nor published; flag connectors lacking connections after verified empty results.
+
+Run `registry get` for OOTB actions during discovery. Defer connector `registry get --connection-id` and resource `registry get --local` or published resolution to Phase 2.
+
+## Plugin Index
+
+Read the relevant plugin `planning.md` when selecting a type.
+
+### Triggers
+
+| Node Type | Plugin | Select when |
+| --- | --- | --- |
+| `core.trigger.manual` | inline | On-demand user or API start |
+| `core.trigger.scheduled` | [scheduled-trigger](plugins/scheduled-trigger/planning.md) | Recurring schedule |
+| IS connector trigger | [connector-trigger](plugins/connector-trigger/planning.md) | External event; type `uipath.connector.trigger.<key>.<trigger>` |
+| `core.trigger.voice` | [inline-voice-agent](plugins/inline-voice-agent/planning.md) | Flow starts when a phone call arrives on a bound number (inbound voice topology) |
+
+Every flow has exactly one trigger, first in topology. IS connector triggers replace manual or scheduled triggers. `core.trigger.manual` has no inputs and output port `output`.
+
+### Actions
+
+| Node Type | Plugin | Select when |
+| --- | --- | --- |
+| `core.action.script` | [script](plugins/script/planning.md) | Custom logic, computation, formatting, transformation |
+| `core.action.http.v2` | [http](plugins/http/planning.md) | REST API; connector or manual mode; replaces deprecated `core.action.http` |
+| `core.action.transform` | [transform](plugins/transform/planning.md) | Declarative map, filter, or group-by |
+| Wait for events | [connector-trigger](plugins/connector-trigger/planning.md) | Mid-flow external event; type `uipath.connector.event.<key>.<event>` with `input` |
+| `uipath.pattern.batch-transform` | [batch-transform](plugins/batch-transform/planning.md) | Append LLM-generated columns to CSV rows; gated by `canvas.nodes.batch-transform` |
+| `uipath.pattern.deep-rag` (Summarize) | [summarize](plugins/summarize/planning.md) | Synthesis/Q&A over one document with optional citations; gated by `canvas.nodes.summarize` |
+| `core.logic.delay` | [delay](plugins/delay/planning.md) | Duration or date wait |
+| `core.action.queue.create` | [queue](plugins/queue/planning.md) | Fire-and-forget robot work |
+| `core.action.queue.create-and-wait` | [queue](plugins/queue/planning.md) | Robot work with result wait |
+| `core.datafabric.read` | [data-fabric](plugins/data-fabric/planning.md) | Read one record or a filtered list from a Data Fabric entity; gated by `canvas.nodes.read-entity` |
+| `core.datafabric.create` | [data-fabric](plugins/data-fabric/planning.md) | Insert a record and return the stored row; gated by `canvas.nodes.create-entity` |
+| `core.datafabric.update` | [data-fabric](plugins/data-fabric/planning.md) | Patch named columns on one record; gated by `canvas.nodes.update-entity` |
+| `core.datafabric.delete` | [data-fabric](plugins/data-fabric/planning.md) | Delete one record; gated by `canvas.nodes.delete-entity` |
+| `uipath.human-in-the-loop.quick-form` | [hitl](plugins/hitl/planning.md) | Inline human review, approval, or data entry |
+| `uipath.conversational.voice.create-outgoing-call` | [inline-voice-agent](plugins/inline-voice-agent/planning.md) | Dial an outbound phone call and emit its `callContext` (outbound voice topology) |
+| `uipath.conversational.voice.end-call` | [inline-voice-agent](plugins/inline-voice-agent/planning.md) | End the active call in a voice flow |
+
+### Control Flow
+
+| Node Type | Plugin | Select when |
+| --- | --- | --- |
+| `core.logic.decision` | [decision](plugins/decision/planning.md) | Binary boolean branch |
+| `core.logic.switch` | [switch](plugins/switch/planning.md) | Three or more ordered cases |
+| `core.logic.loop` | [loop](plugins/loop/planning.md) | Iterate collection |
+| `core.logic.merge` | [merge](plugins/merge/planning.md) | Synchronize parallel branches |
+| `core.control.end` | [end](plugins/end/planning.md) | Graceful completion; one per terminal path |
+| `core.logic.terminate` | [terminate](plugins/terminate/planning.md) | Immediate fatal abort |
+| `core.subflow` | [subflow](plugins/subflow/planning.md) | Reusable isolated-scope group |
+
+### Connector Nodes
+
+Connector nodes are Integration Service nodes, not built-in. They appear after `uip login` and `uip maestro flow registry pull`. Use [connector](plugins/connector/planning.md) when a pre-built connector exists. In Phase 1 record `connector: <service-name>` and intended operation; Phase 2 resolves exact type, connection, and fields.
+
+### Agent Nodes
+
+| Type | Plugin | Select when |
+| --- | --- | --- |
+| `uipath.agent.autonomous` | [inline-agent](plugins/inline-agent/planning.md) | Low-code agent scaffolded inside this flow via `uip agent init --inline-in-flow`, tightly coupled, not independently reused |
+| `uipath.core.agent.{key}` | [agent](plugins/agent/planning.md) | Separate in-solution or published agent, reusable and independently versioned |
+| `uipath.agent.voice` | [inline-voice-agent](plugins/inline-voice-agent/planning.md) | AI agent that converses in real time on a live phone call — an inline conversational agent (`settings.voice` in its `agent.json`) wired to a `callContext` |
+
+See [inline-agent/planning.md — Inline vs Published Agent Decision Table](plugins/inline-agent/planning.md#inline-vs-published-agent-decision-table).
+
+### Resource Nodes
+
+| Category | Type | Plugin |
+| --- | --- | --- |
+| RPA Process | `uipath.core.rpa-workflow.{key}` | [rpa](plugins/rpa/planning.md) |
+| Agent | `uipath.core.agent.{key}` | [agent](plugins/agent/planning.md) |
+| Agentic Process | `uipath.core.agentic-process.{key}` | [agentic-process](plugins/agentic-process/planning.md) |
+| Flow | `uipath.core.flow.{key}` | [flow](plugins/flow/planning.md) |
+| API Workflow | `uipath.core.api-workflow.{key}` | [api-workflow](plugins/api-workflow/planning.md) |
+| Human Task | `uipath.core.human-task.{key}` | [hitl](plugins/hitl/planning.md) |
+| Document Extraction | `uipath.ixp.{modelName}.{fullyQualifiedName}` | [ixp](plugins/ixp/planning.md) |
+
+IxP has a two-segment tail, unlike other resource types' single `{key}` tail; both segments are sanitized at registry emit time. See [plugins/ixp/planning.md](plugins/ixp/planning.md).
+
+### Placeholders
+
+Use `core.logic.mock` for TBD steps, missing resources, or prototypes; it has `input` -> `output`.
+
+## Selecting External Service Nodes
+
+Prefer, in order:
+
+1. A curated Integration Service connector ([connector](plugins/connector/planning.md)).
+2. `core.action.http.v2` connector mode when the connector lacks the activity, or manual mode for APIs without connectors ([http](plugins/http/planning.md)).
+3. An RPA workflow only when there is no API, such as a desktop app or terminal ([rpa](plugins/rpa/planning.md)).
+
+**Data Fabric is not on this ladder.** Entity records have two paths — the `uipath-uipath-dataservice` connector activities and the native `core.datafabric.*` nodes — and availability decides, not preference. The native flags default to off, so **when `registry get core.datafabric.<op>` answers "Node not found", or search reports `AvailableOnTenant: false`, build with the connector activities**: do not retry, do not `uip tools update`, and never hand-write a `definitions[]` entry for a node the registry will not return. Rationale and the federated-entity case in [data-fabric/planning.md — Native node vs Data Service connector](plugins/data-fabric/planning.md#native-node-vs-data-service-connector--availability-decides).
+
+## Standard Port Reference
+
+Every edge requires `sourcePort` and `targetPort`.
+
+| Node Type | Inputs | Outputs |
+| --- | --- | --- |
+| `core.trigger.manual` | — | `output` |
+| `core.trigger.scheduled` | — | `output` |
+| `uipath.connector.trigger.*` | — | `output` |
+| `core.trigger.voice` | — | `output` |
+| `uipath.connector.event.*` | `input` | `output`, `error` |
+| `core.action.script` | `input` | `success`, `error` |
+| `core.action.http.v2` | `input` | `default`, `error`, `branch-{id}` dynamic per `inputs.branches` |
+| `core.action.transform` | `input` | `output`, `error` |
+| `uipath.pattern.batch-transform` | `input` | `output`, `error` |
+| `uipath.pattern.deep-rag` | `input` | `output`, `error` |
+| `core.logic.delay` | `input` | `output` |
+| `core.logic.decision` | `input` | `true`, `false` |
+| `core.logic.switch` | `input` | `case-{id}` dynamic per case, `default` |
+| `core.logic.loop` | outer `input`; inner `continue`, `break` | outer `success`, `error`; inner `start` |
+| `core.logic.merge` | multiple `input` | `output` |
+| `core.control.end` | `input` | — |
+| `core.logic.terminate` | `input` | — |
+| `core.subflow` | `input` | `output`, `error` |
+| `core.logic.mock` | `input` | `output` |
+| `uipath.agent.autonomous` | `input` | `success`, `error`, `tool`, `context`, `escalation` |
+| `uipath.agent.voice` | `input` | `success`, `error`, `tool`, `context`, `escalation` |
+| `uipath.conversational.voice.create-outgoing-call` | `input` | `success`, `error` |
+| `uipath.conversational.voice.end-call` | `input` | `success`, `error` |
+| `uipath.core.agent.*` | `input` | `output`, `error` |
+| `uipath.core.rpa-workflow.*` | `input` | `output`, `error` |
+| `uipath.core.human-task.*` | `input` | `output`, `error` |
+| `uipath.core.flow.*` | `input` | `output`, `error` |
+| `uipath.core.agentic-process.*` | `input` | `output`, `error` |
+| `uipath.core.api-workflow.*` | `input` | `output`, `error` |
+| `uipath.ixp.*` | `input` | `success`, `error` |
+| `uipath.connector.*` | `input` | `output`, `error` |
+| `core.action.queue.create` | `input` | `success` |
+| `core.action.queue.create-and-wait` | `input` | `success` |
+| `core.datafabric.read` | `input` | `output` |
+| `core.datafabric.create` | `input` | `output` |
+| `core.datafabric.update` | `input` | `output` |
+| `core.datafabric.delete` | `input` | `output` (sequencing only — the node produces no data) |
+| `uipath.human-in-the-loop.quick-form` | `input` | `completed` |
+| `uipath.core.human-task.{key}` | `input` | `output` |
+
+`error` is an implicit source port on action nodes with `supportsErrorHandling: true`, off by default. Wire it only when requirements specify failure behavior; otherwise the node faults the flow. This differs from HTTP `inputs.branches` and content-based decision/switch routing. See [Implicit error port on action nodes](../shared/file-format.md#implicit-error-port-on-action-nodes).
+
+## Wiring Rules
+
+1. Connect source output ports to target input ports.
+2. Triggers have no input and are sources only.
+3. End/Terminate nodes have no output and are targets only.
+4. Every non-trigger node has at least one incoming edge.
+5. Every non-terminal node has at least one outgoing edge.
+6. Decisions have exactly one `true` and one `false` edge.
+7. Switches have one edge per case and optionally `default`.
+8. A loop's inner `start` feeds the body, the last body node returns to `continue`, and outer `success` continues after all iterations.
+9. Merge accepts one input per parallel path.
+10. Do not create cycles except through Loop's `continue` handle.
+11. No dangling nodes: every node appears in the edge table as source or target.
+12. Add an `error` edge only for a specified failure fallback. Do not set `inputs.errorHandlingEnabled: true` without an error edge. When an error edge exists, set `inputs.errorHandlingEnabled: true`; CLI edge-add/format commands do this automatically, while direct JSON edits must include it. See [Implicit error port on action nodes](../shared/file-format.md#implicit-error-port-on-action-nodes).
+
+Error handlers must produce a distinguishable failure terminal: a distinct End mapping an error/status `out`, `core.logic.terminate`, or a recovery path that rejoins only after valid data is obtained. Never route failure into the happy path or success End. Use Decision/Switch for successful-content routing, not failure detection. Plan required error edges in Phase 1.
+
+## Common Topology Patterns
+
+- **Linear:** `Trigger -> Action A -> Action B -> End`
+- **Conditional:** `Trigger -> Fetch -> Decision`; connect `true` and `false` to separate paths and terminals.
+- **Parallel:** `Trigger -> Prepare`; fork to actions; join at `Merge`; continue to End.
+- **Loop:** `Trigger -> Fetch List -> Loop`; `start` enters the body, the body returns to `continue`, and `success` exits to summary and End.
+- **Mixed orchestration:** Maestro owns state, waits, branches, and SLAs; RPA performs mechanical legacy-system work; agents reason; humans approve. Reference separate published or in-solution artifacts rather than rebuilding them in the flow.
+- **Scheduled batch:** `Scheduled Trigger -> HTTP -> Loop`; loop body creates queue items; outer success summarizes and ends.
+
+### No-API Source
+
+A source with no API or connector cannot trigger Maestro directly. Use a scheduled RPA bot outside the flow to scrape it and add queue items or upload bucket files; the Maestro flow consumes the queue or scheduled bucket drop. Queue is best for separate cases; bucket is best for batches. Polling latency is at least the scraper interval; real-time is unavailable. Prefer a connector trigger when an event, webhook, or connector exists. The scraper belongs to [/uipath:uipath-rpa](/uipath:uipath-rpa) with scheduling from [/uipath:uipath-platform](/uipath:uipath-platform); only the consuming flow belongs here.
+
+## Output Format
+
+Generate `<SolutionName>.uipath.flow.arch.plan.md` in the **solution directory**, the folder containing `.uipx`, not the project subfolder. The plan covers the entire solution.
+
+### 1. Summary
+
+Write 2–3 sentences describing the end-to-end flow.
+
+### 2. Flow Diagram (Mermaid)
+
+Use a complete diagram with all nodes, edges, branches, and port labels. Use `graph LR`, never `graph TD` or `flowchart`. Use `subgraph` for flows with 10+ nodes. Labels must be plain alphanumeric and spaces only: no `>`, `<`, `(`, `)`, `[`, `]`, `{`, `}`, `:`, `;`, `?`, `&`, or quotes. Do not put node types in labels. Use only `(text)`, `[text]`, and `{text}` shapes: triggers and terminals rounded, actions/connectors/placeholders rectangular, decisions/switches diamonds. Do not use quotes inside delimiters.
+
+### 3. Node Table
+
+| # | Node ID | Name | Category | Node Type | Inputs | Outputs | Notes |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | trigger | Manual Trigger | trigger | `core.trigger.manual` | — | Trigger event | — |
+
+Include one row per node. Use short alphanumeric or underscore IDs matching the diagram. Inputs are best guesses; use `<PLACEHOLDER>` for URLs, IDs, and connection details Phase 2 must resolve. Outputs describe values downstream nodes consume via `$vars.{nodeId}.*`. Notes identify Phase 2 concerns.
+
+### 4. Edge Table
+
+| # | Source Node | Source Port | Target Node | Target Port | Condition/Label |
+| --- | --- | --- | --- | --- | --- |
+| 1 | trigger | output | nextNode | input | — |
+
+Every node except the trigger must be a target; every node except End/Terminate must be a source. Ports must match [Standard Port Reference](#standard-port-reference). Include error edges exactly when requirements specify failure fallbacks, and ensure they reach a distinguishable failure terminal.
+
+### 5. Inputs & Outputs
+
+| Direction | Name | Type | Description |
+| --- | --- | --- | --- |
+| `in` | inputName | `string` | Input description |
+| `out` | outputName | `number` | Output description |
+| `inout` | stateName | `array` | State description |
+
+Include all flow inputs, outputs, and inout state.
+
+### 6. Connector Summary (omit if no connectors)
+
+| Node ID | Service | Intended Operation | Phase 2 Action |
+| --- | --- | --- | --- |
+| nodeId | Service | Operation | Resolve connector key, bind connection, resolve IDs and fields |
+
+### 7. Open Questions (omit if none)
+
+Prefix each item with `**[REQUIRED]**` or `**[OPTIONAL]**`. Include unresolved user decisions and verified missing connections/resources.
+
+## Mermaid Validation Rules
+
+Before presenting the plan, validate every rule:
+
+1. First line is `graph LR`, not `flowchart`.
+2. Node IDs contain only `[a-zA-Z0-9_]`; use `fetchData`, not `fetch-data` or `fetch.data`.
+3. IDs must not start with or equal reserved words: `end`, `subgraph`, `graph`, `flowchart`, `direction`, `click`, `style`, `classDef`, `class`, `linkStyle`, `callback`, `default`. Avoid IDs such as `endWarm`, `defaultPath`, and `styleNode`.
+4. Labels have no quotes or prohibited special characters; replace `>` / `<` with words like over/under.
+5. Shapes are only `(text)`, `[text]`, and `{text}`. Do NOT use `([text])` (stadium), `{{text}}` (hexagon), or other extended shapes.
+6. Edges use `-->` or `-->|label|`; empty labels such as `-->||` are invalid. Write `A -->|success| B`, not `A -->success B` or `A --success--> B`.
+7. Subgraph IDs are unique and do not collide with node IDs.
+8. Every `subgraph` has a matching `end`.
+9. Do not use semicolons.
+10. Do not put blank lines inside the mermaid block.
+11. Every defined node is connected; every node-table node appears in the diagram; every edge-table edge appears in the diagram.
+12. Decisions show `true` and `false`; switches show every case and optional `default`; loops show the body and `continue`; parallel branches fork and converge at Merge.
+
+## Node Selection Heuristics
+
+- **External service:** curated `uipath.connector.<key>.<operation>` -> [connector](plugins/connector/planning.md); connector without activity -> `core.action.http.v2` connector mode; no connector but REST API -> `core.action.http.v2` manual mode; no API -> [rpa](plugins/rpa/planning.md) or `core.logic.mock` if unpublished.
+- **Branch:** two paths -> [decision](plugins/decision/planning.md); three or more -> [switch](plugins/switch/planning.md); HTTP response-status branch -> [http](plugins/http/planning.md) built-in branches.
+- **Transform:** map/filter/group-by -> [transform](plugins/transform/planning.md); custom computation or strings -> [script](plugins/script/planning.md).
+- **End:** normal completion -> [end](plugins/end/planning.md); fatal abort -> [terminate](plugins/terminate/planning.md).
+- **Wait:** duration or date -> [delay](plugins/delay/planning.md); external robot result -> [queue](plugins/queue/planning.md) `create-and-wait`.
+- **Human:** approval or data entry -> [hitl](plugins/hitl/planning.md), or `core.logic.mock` if unavailable.
+- **Agent:** tightly coupled low-code agent inside flow -> [inline-agent](plugins/inline-agent/planning.md), `uipath.agent.autonomous`; coded or separate in-solution/published agent -> [agent](plugins/agent/planning.md), `uipath.core.agent.{key}`.
+- **LLM over CSV/document:** CSV row columns -> [batch-transform](plugins/batch-transform/planning.md), `uipath.pattern.batch-transform`; one-document synthesis/Q&A/citations -> [summarize](plugins/summarize/planning.md), `uipath.pattern.deep-rag`; multi-step tool reasoning -> inline or published agent; ordinary reshaping -> transform.
+- **Document extraction:** variable-layout PDF, scan, photo, or attachment -> [ixp](plugins/ixp/planning.md), `uipath.ixp.{modelName}.{fullyQualifiedName}`; structured source -> script or transform; free-form reasoning -> agent; untrained IxP model -> `core.logic.mock` plus Open Question.
+- **Missing capability:** use `core.logic.mock`; identify the needed artifact and owning skill (`uipath-rpa` for desktop/browser or coded C# workflows, `uipath-agents` for agents). Phase 2 replaces the mock if published.
+
+## Handoff to Phase 2
+
+After explicit user approval, [Planning Phase 2: Implementation](planning-impl.md) must:
+
+1. Validate every node type with `uip maestro flow registry get`; read each plugin's `impl.md`.
+2. Resolve connector and resource nodes using relevant `impl.md` files, including [connector](plugins/connector/impl.md) and [rpa](plugins/rpa/impl.md).
+3. Confirm resources are published and obtain definitions.
+4. Validate required fields against user values.
+5. Replace `<PLACEHOLDER>` values with resolved IDs.
+6. Replace `core.logic.mock` nodes with real resources when available.
+7. Finalize implementation-ready details.
+
+**Do not proceed to Phase 2 until the user explicitly approves the architectural plan.**