@uipath/skills 1.204.0 → 1.204.1

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

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

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

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

@@ -0,0 +1,190 @@
+# Flow Editing Operations — CLI Carve-Outs
+
+This is **not** a structural editing guide. Use direct `.flow` authoring via [editing-operations-json.md](editing-operations-json.md) for OOTB node/edge/variable CRUD, trigger swaps, output mapping, subflows, inline-agent node/wiring, non-connector resources, and in-place updates.
+
+> **When to use this file:** only for CLI-managed carve-outs documented by a plugin: connector activities, connector triggers, and managed HTTP nodes (both `node add` and `node configure`). If you landed here while adding/removing/wiring OOTB nodes, inline-agent nodes, non-connector resources, or other structural graph elements, go back to the Edit / Write guide.
+
+The primitive commands below are support commands for carve-out workflows only. They are not an opt-in path for non-carve-out structural edits.
+
+---
+
+## Primitive Commands for Carve-Out Workflows
+
+### Add a node
+
+```bash
+uip maestro flow node add <ProjectName>.flow <node-type> --output json \
+  --input '<INPUT_JSON>' \
+  --label "<LABEL>" \
+  --position <X>,<Y> \
+  --parent <PARENT_NODE_ID>
+```
+
+**What the CLI handles automatically:**
+- Inserts node into `nodes` array with a generated `id`
+- Copies the definition from the local registry cache into `definitions` (one per unique type)
+- Adds node output variables to `variables.nodes`
+
+**Flags:**
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--input` | No | JSON object of node-specific inputs (expression, script, URL, etc.). Omit for nodes with no inputs (merge, end, terminate). |
+| `--label` | No | Display label shown on the canvas |
+| `--position` | No | `x,y` coordinates. Any value is fine (e.g. `0,0`) — `flow format` rewrites positions on save. |
+| `--parent` | No | ID of an existing container node (e.g. a `core.logic.loop`). Sets `parentId` on the new node, placing it inside that container. Required for every node in a loop body — see [loop/impl.md](plugins/loop/impl.md). |
+| `--output json` | Yes (for parsing) | Structured JSON response with the assigned node `id` |
+
+**Shell quoting tip:** If `--input` JSON contains special characters (quotes, braces, `$vars`), write it to a temp file and pass `--input "$(cat /tmp/input.json)"`.
+
+### Remove a node
+
+```bash
+uip maestro flow node remove <ProjectName>.flow <NODE_ID>
+uip maestro flow node remove <ProjectName>.flow <NODE_ID> --output json
+```
+
+**What the CLI handles automatically:**
+- Removes the node from `nodes`
+- Removes all connected edges
+- Removes orphaned definitions (definitions no longer referenced by any node)
+- Removes orphaned bindings (connector bindings are shared at the connector level — a binding is only orphaned when no remaining node uses that connector)
+- Removes node variables from `variables.nodes`
+
+### List nodes
+
+```bash
+uip maestro flow node list <ProjectName>.flow --output json
+```
+
+Returns all nodes with their `id`, `type`, and `display.label`. Use this to discover node IDs before wiring edges or removing nodes.
+
+### Add an edge
+
+```bash
+uip maestro flow edge add <ProjectName>.flow <SOURCE_NODE_ID> <TARGET_NODE_ID> --output json \
+  --source-port <PORT> \
+  --target-port <PORT>
+```
+
+**What the CLI handles automatically:**
+- Inserts edge into `edges` array with a generated `id`
+- Sets `targetPort` (required — validate rejects edges without it)
+
+See each plugin's `planning.md` or [file-format.md — Standard ports](../shared/file-format.md) for port names by node type.
+
+### Remove an edge
+
+```bash
+uip maestro flow edge remove <ProjectName>.flow <EDGE_ID>
+uip maestro flow edge remove <ProjectName>.flow <EDGE_ID> --output json
+```
+
+### List edges
+
+```bash
+uip maestro flow edge list <ProjectName>.flow --output json
+```
+
+Returns all edges with `id`, `sourceNodeId`, `sourcePort`, `targetNodeId`, `targetPort`.
+
+### Configure a connector node
+
+After adding a connector node with `node add`, configure it with connection details:
+
+```bash
+uip maestro flow node configure <ProjectName>.flow <NODE_ID> \
+  --detail '<DETAIL_JSON>'
+```
+
+**What the CLI handles automatically:**
+- Populates `inputs.detail` (connectionId, method, endpoint, bodyParameters, etc.)
+- Creates connection binding entries in `bindings_v2.json`
+- Creates connection resource files under `resources/solution_folder/connection/`
+
+The `--detail` JSON schema differs between connector activity nodes, connector trigger nodes, and managed HTTP nodes — see [connector/impl.md](plugins/connector/impl.md), [connector-trigger/impl.md](plugins/connector-trigger/impl.md), and [http/impl.md](plugins/http/impl.md) for the exact fields.
+
+**Shell quoting — write the JSON to a file first.** Never hand-escape quotes inside the shell command. `--detail` takes inline JSON only; there is no file flag. Write the payload with a quoted heredoc, then substitute the file:
+
+```bash
+cat > /tmp/detail.json <<'EOF'
+{"connectionId": "<CONNECTION_ID>", "folderKey": "<FOLDER_KEY>", "method": "POST", "endpoint": "/Account"}
+EOF
+uip maestro flow node configure <ProjectName>.flow <NODE_ID> --detail "$(cat /tmp/detail.json)" --output json
+```
+
+`<<'EOF'` (quoted delimiter) stops the shell from touching the body, so `=js:` expressions, backticks, `${...}`, and nested quotes reach the CLI byte for byte. Nesting an `=js:` expression inside `--detail '<json>'` instead doubles its backslashes; the saved expression then faults at runtime with `[400300] Error evaluating expression … Invalid or unexpected token`, and a stray quote aborts the command with a shell parse error (`zsh: parse error`, `bash: syntax error near unexpected token`).
+
+### Configure a managed HTTP node
+
+After adding a `core.action.http.v2` node, configure it with target connector and connection details:
+
+```bash
+uip maestro flow node configure <ProjectName>.flow <NODE_ID> \
+  --detail '{
+    "authentication": "connector",
+    "targetConnector": "<TARGET_CONNECTOR_KEY>",
+    "connectionId": "<TARGET_CONNECTION_ID>",
+    "folderKey": "<FOLDER_KEY>",
+    "method": "GET",
+    "path": "/api/endpoint",
+    "query": {"param1": "value1"}
+  }'
+```
+
+**What the CLI handles automatically:**
+- Wraps your fields into the full `inputs.detail` structure (connector: `uipath-uipath-http`, bodyParameters, configuration)
+- Generates `bindings_v2.json` with the target connector's connection
+- Creates a connection resource file under `resources/solution_folder/connection/`
+
+See [http/impl.md](plugins/http/impl.md) for the full configuration workflow and JSON structure.
+
+### Validate
+
+```bash
+uip maestro flow validate <ProjectName>.flow --output json
+```
+
+Run **once** after all nodes, edges, and configuration are complete. Do not validate after each individual edit — intermediate states are expected to be invalid.
+
+---
+
+## Carve-Out Composite Operations
+
+These combine primitives only for workflows that are themselves carve-outs. Do not use them for non-carve-out structural edits; use [editing-operations-json.md](editing-operations-json.md) instead.
+
+### Replace manual trigger with connector trigger
+
+1. Remove the manual trigger (also removes its edges and orphaned definition):
+   ```bash
+   uip maestro flow node remove <ProjectName>.flow start --output json
+   ```
+2. Add the connector trigger node:
+   ```bash
+   uip maestro flow node add <ProjectName>.flow <TRIGGER_NODE_TYPE> \
+     --label "<LABEL>" --position 200,144 --output json
+   ```
+3. Re-wire edge from the new trigger to the next node:
+   ```bash
+   uip maestro flow edge add <ProjectName>.flow <NEW_TRIGGER_ID> <NEXT_NODE_ID> \
+     --source-port output --target-port input --output json
+   ```
+4. Configure the trigger with connection and event parameters:
+   ```bash
+   uip maestro flow node configure <ProjectName>.flow <NEW_TRIGGER_ID> --detail '<TRIGGER_DETAIL_JSON>'
+   ```
+
+See [connector-trigger/impl.md](plugins/connector-trigger/impl.md) for the full `--detail` schema.
+
+---
+
+## Operations Not Supported by CLI
+
+These operations require the `Edit` tool. Use the [Edit / Write strategy guide](editing-operations-json.md) for:
+
+1. **Any non-carve-out structural edit** — node/edge CRUD, scheduled triggers, HITL QuickForm nodes, inline-agent nodes, non-connector resources, and graph rewiring
+2. **Node input updates** — the CLI does not have a `node update` command; use `Edit` to preserve node IDs and `$vars.{nodeId}` references
+3. **Workflow variables while authoring** — updating `variables.globals` in place, and any `subType`/`schema`/`defaultValue` change. There *is* a CLI surface for declaring globals (`uip maestro flow variable add|list|remove`), but it is scoped to declaring eval inputs — see [variables-and-expressions.md § Variable Management via CLI](../shared/variables-and-expressions.md#variable-management-via-cli)
+4. **Variable updates** — add/modify `variables.variableUpdates` entries. No CLI command exists for these
+5. **Output mapping on End nodes** — add `outputs` object with `source` expressions
+6. **Subflows** — create `subflows.{nodeId}` with nested nodes, edges, variables