@uipath/skills 1.204.0 → 1.204.1

package/skills/uipath-maestro-flow/references/evaluate/upload-safety.md

@@ -0,0 +1,94 @@
+# Upload Safety: Do Not Auto-Run `uip solution upload`
+
+Never run `uip solution upload` automatically during an evaluation workflow. Always ask the user first. This applies to locally created, Studio Web-downloaded, VS Code-authored, or otherwise divergent solutions, including when the CLI reports `solution-id could not be resolved` or a similar error.
+
+`uip solution upload` creates or overwrites the solution matched by the local `SolutionId` in Studio Web. Automatic upload can publish work in progress, overwrite concurrent Studio Web changes, or silently discard remote changes because local and remote state is not merged.
+
+## Read-Only Resolution Check
+
+This applies regardless of whether:
+
+- The local project was created via `uip maestro flow init` and never uploaded.
+- The local project was downloaded from Studio Web via `uip solution download` and edited locally.
+- The user is working in a VS Code-authored solution / personal workspace and the project may not match what is on Studio Web.
+- The CLI errors with `solution-id could not be resolved` or any variant.
+
+## Why
+
+`uip solution upload` is a write operation against Studio Web. It either creates a new solution or **overwrites** the existing one matched by the `SolutionId` in the local `.uipx` (bundling generates `SolutionStorage.json` from it; that file is read back only for a direct `.uis` upload) — the overwrite needs no flag and raises no prompt. The replaced contents are recorded as a restorable version (skipped entirely with `--no-snapshot`), but recovery is browser-only, after the fact, by the user — and it does not undo failure mode 1 below. None of this is a reason to skip asking. Three concrete failure modes if the skill auto-uploads:
+
+1. **The user is iterating locally** in VS Code or the filesystem and intended to test something **before** publishing. Auto-upload pushes work-in-progress to Studio Web where teammates and triggers may pick it up.
+2. **The user pulled the solution from Studio Web** to edit a small piece. Auto-upload sends the partial local state back, potentially **overwriting** changes another user made on Studio Web in the meantime.
+3. **The local solution diverged from Studio Web** (e.g., a teammate edited the solution on Studio Web while the dev was working locally). Auto-upload silently discards the remote-side changes — they are not merged.
+
+In all three cases the user loses work or surprises a teammate. The cost of pausing to ask is one prompt; the cost of an unwanted upload can be hours of recovery.
+
+## What To Do Instead
+
+When `eval run start` cannot resolve the solution:
+
+1. **Stop and ask the user.** Use plain language: "Your Flow solution doesn't appear to be in Studio Web (or its IDs aren't resolvable from the local working tree). I can't run an eval until it is. How do you want to proceed?"
+2. **Offer the options explicitly:**
+   - **Upload now** — the user runs (or asks the skill to run) `uip solution upload <SolutionDir> --output json`. They acknowledge that this will write to Studio Web.
+   - **Pass IDs explicitly** — the user provides `--solution-id` and `--project-id` for an existing Studio Web solution. The skill plumbs them through to `eval run start`.
+   - **Cancel** — they meant to test something else (e.g., `flow debug`).
+3. **Wait for an explicit decision.** Do not infer one from context, prior commands, or comments in the project.
+
+## How to Detect "Local Workspace or VS Code"
+
+There is no single CLI flag that says "this project is local-only." The signals to weigh, in priority order:
+
+1. **The `.uipx` carries an id Studio Web has never seen** (a fresh `solution init`, never uploaded). The upload would CREATE a new solution; the user might not want a new tenant entry.
+2. **`.vscode/` directory exists in the solution root.** Strong signal that the dev is authoring in VS Code; assume they are iterating locally.
+3. **The directory is under a workspace path the user has indicated they edit locally** (`~/Code/...`, `~/dev/...`, etc., or any path that is not the default Studio Web download location). Treat as local-first.
+4. **`uip solution upload` has never been recorded** in the recent shell history or in the conversation. If the skill cannot point to a prior explicit upload, do not assume the project is in Studio Web.
+
+If ANY of these signals is true, skip auto-upload entirely and ask.
+
+None of these signals separates a first import from an overwrite of a live solution: an id from a downloaded or copied project names a solution the upload would replace, and the local tree alone cannot tell the two apart. Treat both as writes to ask about.
+
+## How to Detect "Solution Already in Studio Web"
+
+The cheapest check is to attempt a read-only run command before doing anything else:
+
+```bash
+uip maestro flow eval run list --set "<set_name>" --path <flow_project> --output json
+```
+
+A successful response, including zero past runs, indicates that the solution is in Studio Web. A missing-solution or auth error means it is not uploaded for this workflow; ask before uploading. If `eval run start` fails with a resolution error, never auto-upload or retry by uploading.
+
+## If Evaluation Cannot Resolve the Solution
+
+1. Stop and ask: "Your Flow solution doesn't appear to be in Studio Web (or its IDs aren't resolvable from the local working tree). I can't run an eval until it is. How do you want to proceed?"
+2. Offer:
+   - **Upload now** — the user runs, or explicitly asks the skill to run, `uip solution upload <SolutionDir> --output json`; state that this writes to Studio Web.
+   - **Pass IDs explicitly** — the user provides `--solution-id` and `--project-id` for an existing Studio Web solution; pass them through to `eval run start`.
+   - **Cancel** — they intended to test something else, such as `flow debug`.
+3. Wait for an explicit decision. Never infer consent from context, prior commands, or project comments.
+
+## Local-Workspace Signals
+
+Treat the project as local-first and skip auto-upload if any signal is present:
+
+1. `SolutionStorage.json` is missing or has no `SolutionId`; upload would create a new solution.
+2. A `.vscode/` directory exists in the solution root.
+3. The directory is under a user-indicated local workspace path, such as `~/Code/...` or `~/dev/...`, rather than the default Studio Web download location.
+4. No prior `uip solution upload` appears in recent shell history or the conversation; without a recorded explicit upload, do not assume the project is in Studio Web.
+
+## Explicit Upload Consent
+
+When the user explicitly asks to upload, you may run:
+
+```bash
+uip solution upload <SolutionDir> --output json
+```
+
+Before running it, echo the exact command and warn that concurrent Studio Web edits may be overwritten. Afterward, report `SolutionId` and `DesignerUrl` from the output, surface the result, and only then proceed with the eval run. Do not silently chain the upload into the next step.
+
+## Anti-Patterns
+
+- Do not run `uip solution upload` to fix an eval-run error.
+- Do not treat "make the eval work" as upload consent.
+- Do not auto-retry an eval after solution resolution fails by uploading and rerunning.
+- Do not upload while another user may be editing the solution on Studio Web without warning about possible overwrites, even with consent.
+- Do not combine `flow debug` and `eval run` in one session against the same solution; each has its own Studio Web debug session, and mixing them can confuse run IDs and trigger unexpected uploads.

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

@@ -0,0 +1,77 @@
+# Operate — Ship, run, and manage deployed flows
+
+Capability index for the lifecycle of a flow as a deployed asset. Operate owns everything that touches the cloud — `solution resources refresh`, Studio Web upload, Orchestrator deploy, `flow debug`, `process run`, `job status/traces`, and `instance` lifecycle (pause, resume, cancel, retry). Requires `uip login`.
+
+> **Where you came from / where to go next.** Operate is downstream of Author (build the flow → ship it) and upstream of Diagnose (run faults → diagnose). Build/edit lives in [author/CAPABILITY.md](../author/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, 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 operate-scoped and apply on top.
+
+## When to use this capability
+
+- Push a flow to Studio Web (`uip solution upload`)
+- Deploy a flow to Orchestrator (`uip maestro flow pack` + `uip solution publish`)
+- Run a flow end-to-end via `uip maestro flow debug` (cloud round-trip with real side effects)
+- Trigger a deployed process via `uip maestro flow process run`
+- Check job status or stream traces with `uip maestro flow job status` / `job traces`
+- Manage a running instance — pause, resume, cancel, or retry
+- Refresh solution resources after binding changes (`uip solution resources refresh`)
+
+## Critical rules
+
+1. **Always run `uip solution resources refresh --solution-folder <SolutionDir>` before `solution upload` or `flow debug`.** Stale resource declarations cause runtime binding failures even when the local `.flow` is correct. The refresh syncs connection and process resource declarations from the project's `bindings_v2.json` files into the solution. `refresh` has no positional solution argument; omit `--solution-folder` only when the current directory is already the solution root.
+2. **Default to Studio Web when the user says "publish" without specifier.** "Publish" → `uip solution upload <SolutionDir>`. Only run `uip maestro flow pack` + `uip solution publish` when the user explicitly asks to deploy to Orchestrator. Pass the exact solution root path (the directory containing the `.uipx` file), or `.` when already in that directory; do not pass the solution name while the shell is inside a nested project folder. The Orchestrator path bypasses Studio Web — the user cannot visualize or edit the flow there.
+3. **Always include `--folder-key <FOLDER_KEY>` (`-f` shorthand) on `instance` commands.** Without it the command rejects the request before reaching the API. Get the folder key from `uip or folders list --output json` or from the job/process context. See [shared/cli-conventions.md](../shared/cli-conventions.md#6---folder-key-requirement).
+4. **Always report Studio Web URL and Instance ID as the first two lines of any debug summary.** Parse `Data.studioWebUrl` and `Data.instanceId` from the JSON output. Use `<not returned by CLI>` if missing — never omit the line. Users need these immediately, not buried below status text.
+
+## Workflow
+
+| Journey | Read |
+| --- | --- |
+| Publish a flow (Studio Web default, Orchestrator on request) | [ship.md](ship.md) |
+| Run a flow on demand or check progress | [run.md](run.md) |
+| Intervene in a running instance | [manage.md](manage.md) |
+
+## Common tasks
+
+| I need to... | Read these |
+| --- | --- |
+| **Publish a flow to Studio Web** | [ship.md — Path 1](ship.md#path-1--studio-web-upload-default) |
+| **Deploy a flow to Orchestrator** (only if explicitly requested) | [ship.md — Path 2](ship.md#path-2--orchestrator-deploy-explicit-only) + [/uipath:uipath-solution](/uipath:uipath-solution) |
+| **Sync solution resource declarations** | [ship.md — Pre-flight](ship.md#pre-flight) (the `uip solution resources refresh` step) |
+| **Debug a flow end-to-end** | [run.md — Debug](run.md#debug--controlled-end-to-end-run) |
+| **Debug a chat flow** | `flow debug` cannot drive a conversation headlessly. On a flow starting with `core.trigger.conversation` it uploads, returns `Code: FlowDebugStudioWebHandoff` with `Data.studioWebUrl`, and starts no run. Chat from either Studio Web (open that URL; `--open-in-browser` does it for you) or the UiPath Maestro VS Code extension. `--timeout` does nothing here. See [author/plugins/conversational-agent/impl.md](../author/plugins/conversational-agent/impl.md#debug--the-cli-hands-off) |
+| **Pass input arguments to `flow debug`** | [run.md — Debug](run.md#debug--controlled-end-to-end-run) (the `--inputs` flag) |
+| **Bind local files to file-typed inputs** | [run.md — Debug](run.md#debug--controlled-end-to-end-run) and [run.md — Process run](run.md#process-run--trigger-a-deployed-process) (same `--attachment <variableId>=<localPath>` flag on both, repeatable; `--attachment` overrides `--inputs` on key collisions) |
+| **Trigger a deployed process** | [run.md — Process run](run.md#process-run--trigger-a-deployed-process) |
+| **Check status of a running job** | [run.md — Job inspection](run.md#job-inspection--status-and-traces) |
+| **Stream verbose execution traces** | [run.md — Job inspection](run.md#job-inspection--status-and-traces) (use sparingly — see [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md)) |
+| **Pause a running instance** | [manage.md](manage.md) |
+| **Resume a paused instance** | [manage.md](manage.md) |
+| **Cancel an instance** | [manage.md](manage.md) |
+| **Retry a faulted instance** | [manage.md](manage.md) (after diagnosing root cause via [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md)) |
+| **Look up `solution` / `flow pack` / `flow debug` / `process` / `job` / `instance` CLI syntax** | [shared/cli-commands.md](../shared/cli-commands.md) |
+| **My flow run failed** | [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md) |
+
+## Anti-patterns
+
+- **Never run `solution upload` without `solution resources refresh` first.** Stale resource declarations cause runtime binding failures.
+- **Never default to Orchestrator deploy when the user said "publish".** "Publish" → Studio Web upload. Confirm explicitly before running `flow pack` + `solution publish`.
+- **Never run `flow debug` as a validation step, and never re-run a completed one to reshape its output.** Each run re-uploads the solution and executes the flow again against real systems; extract report fields from the payload the completed run already returned, and when that run faulted, read the cause from it first — see [diagnose/troubleshooting-guide.md — Step 0](../diagnose/troubleshooting-guide.md#step-0--read-the-cause-in-the-debug-output-you-already-have). Use `uip maestro flow validate` for correctness checking.
+- **Never `retry` a faulted instance without diagnosing the root cause first.** Triage via [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md) — read incidents, runtime variables, and the deployed asset. Then decide whether to retry, cancel, or re-author.
+- **Never start diagnosis from `job traces`.** Traces are last-resort verbose output. Begin with incidents — see [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md) for the priority ladder.
+
+## References
+
+### Operate-scoped
+
+- [ship.md](ship.md) — Studio Web upload (default) and Orchestrator deploy (explicit)
+- [run.md](run.md) — debug, process run, job status/traces
+- [manage.md](manage.md) — instance lifecycle (pause, resume, cancel, retry)
+
+### Cross-capability (shared)
+
+- [shared/cli-commands.md](../shared/cli-commands.md) — flat CLI lookup including `solution upload`, `solution resources refresh`, `flow pack`, `flow debug`, `flow process`, `flow job`, `flow instance`
+- [shared/cli-conventions.md](../shared/cli-conventions.md) — login states, FOLDER_KEY, UIP_LOG_LEVEL, JSON output shape
+- [shared/variables-and-expressions.md](../shared/variables-and-expressions.md) — `--inputs` JSON shape for `flow debug`
+
+For Orchestrator deployment via `uip solution publish`, see [/uipath:uipath-solution](/uipath:uipath-solution).

package/skills/uipath-maestro-flow/references/operate/manage.md

@@ -0,0 +1,39 @@
+# Manage — Instance Lifecycle
+
+Intervene in a running or faulted Flow instance: pause, resume, cancel, retry. All commands require `uip login` and `--folder-key <FOLDER_KEY>` (`-f` shorthand).
+
+> **Stub-with-content.** This guide ships with the canonical command list. Use-case framing (when to pause vs cancel, retry semantics, partial-flow recovery) is a TODO for a future expansion.
+
+## Pre-flight
+
+1. **Logged in.** `uip login status --output json` returns success.
+2. **Folder key resolved.** Get it from `uip or folders list --output json` or from the job/process context. See [shared/cli-conventions.md — `--folder-key` requirement](../shared/cli-conventions.md#6---folder-key-requirement).
+3. **Instance ID known.** From a debug run (`Data.instanceId`), `flow job status` response, or `instance list`.
+
+## Lifecycle commands
+
+```bash
+uip maestro flow instance pause <INSTANCE_ID> -f <FOLDER_KEY> --output json    # pause a running instance
+uip maestro flow instance resume <INSTANCE_ID> -f <FOLDER_KEY> --output json   # resume a paused instance
+uip maestro flow instance cancel <INSTANCE_ID> -f <FOLDER_KEY> --output json   # cancel an instance
+uip maestro flow instance retry <INSTANCE_ID> -f <FOLDER_KEY> --output json    # retry a faulted instance
+```
+
+| Command | What it does |
+| --- | --- |
+| `pause` | Pause a running instance. |
+| `resume` | Resume a paused instance. |
+| `cancel` | Cancel an instance. |
+| `retry` | Retry a faulted instance. Use after fixing the underlying issue. |
+
+> **Runtime semantics** (when each takes effect, recoverability, partial-flow behavior) are not documented in this skill. Run `uip maestro flow instance <subcommand> --help` for any options the CLI exposes; consult Orchestrator docs for the underlying lifecycle model.
+
+## What's next
+
+- **Need to inspect why an instance faulted before deciding pause/cancel/retry?** Triage via [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md) first — get incidents and runtime variables before intervening.
+- **Need to look up the full `instance` CLI surface?** See [shared/cli-commands.md](../shared/cli-commands.md) and the [Diagnose troubleshooting guide — CLI command reference](../diagnose/troubleshooting-guide.md#cli-command-reference).
+
+## Anti-patterns
+
+- **Never `retry` a faulted instance without diagnosing the root cause first.** Triage via [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md) — read incidents, runtime variables, and the deployed asset. Then decide whether to retry, cancel, or re-author.
+- **Never skip the `--folder-key` flag.** Without it the command rejects before reaching the API.

package/skills/uipath-maestro-flow/references/operate/run.md

@@ -0,0 +1,121 @@
+# Run — Execute a Flow
+
+Execute a flow on demand and monitor progress. Three modes: **debug** (controlled re-run with full Studio Web visibility), **process run** (trigger a deployed process), **job inspection** (status and traces). All require `uip login`.
+
+## Pre-flight
+
+1. **Logged in.** `uip login status --output json` returns success. See [shared/cli-conventions.md — Login state](../shared/cli-conventions.md#5-login-state).
+2. **For debug runs: solution resources refreshed.** Always run before `flow debug` so connection and process resource declarations are in sync with project bindings:
+
+   ```bash
+   uip solution resources refresh --solution-folder <SolutionDir> --output json
+   ```
+
+## Debug — controlled end-to-end run
+
+> **Consent comes from the mandate.** `flow debug` executes the flow for real — sends emails, posts messages, calls APIs. Run it when the request is for a flow that works; ask when the request stops at build or validate, and with nobody to ask report the flow as unverified rather than letting a passing validate stand as the result. Never debug a solution this run did not scaffold: debug overwrites the Studio Web solution matching the local `.uipx` `SolutionId`. See rule #2 in [SKILL.md](../../SKILL.md).
+
+```bash
+UIP_LOG_LEVEL=info uip maestro flow debug <path-to-project-dir> --output json
+```
+
+The argument is the **project directory path** (the folder containing `project.uiproj`). Use `<ProjectName>/` from the solution dir, or `.` if already inside the project dir.
+
+> **Never run `flow debug` in the background.** It takes 1 to 5 minutes and prints its JSON only at exit.
+> 1. Run it in the foreground with a tool timeout of at least 10 minutes (most agent shells kill a command after 1 to 2 minutes).
+> 2. If the tool returns "still running", poll that same process until it exits. Do not read the output file yet — empty means still running.
+> 3. If stdout ends with `Debug polling timed out after <N>s`, the flow is still running on the server. Take the `instanceId` from stderr and run `uip maestro flow debug-instance status <INSTANCE_ID> --output json`.
+> 4. Never start a second debug while the first is running — it uploads and executes the flow again.
+> 5. Re-run debug only after you changed the flow.
+
+> **Do not pass `--folder-path` or `--folder-key` to `flow debug`.** Debug provisions into your personal workspace. A shared or team folder fails with `HTTP 500` at `Stage: prepare-custom-debug` and no instance starts. Shared resources the flow uses (indexes, buckets, connections) reach the run through `uip solution resources refresh`, not through the debug folder. Use the flag only when your account has no personal workspace or the flow needs folder-scoped assets or queues that exist only in that folder.
+
+Pass input arguments when the flow has input parameters:
+
+```bash
+UIP_LOG_LEVEL=info uip maestro flow debug <path-to-project-dir> --output json \
+  --inputs '{"numberA": 5, "numberB": 7}'
+```
+
+Build those inputs from real records, never from invented values — an invented key matches no record, every lookup returns `[]`, and the run faults on empty data. Read the entity `Id` from `uip df entities list --output json`, then a live record from `uip df records list <ENTITY_ID> --output json`.
+
+Bind local files to file-typed input variables with `--attachment <variableId>=<localPath>` (repeatable). `<variableId>` (left of `=`) must match the `id` of a `variables.globals[]` entry with `direction:"in"` and `type:"file"`:
+
+```bash
+# Replace <variableId> and <localPath> placeholders below with your own values.
+UIP_LOG_LEVEL=info uip maestro flow debug <path-to-project-dir> --output json \
+  --attachment <variableId>=<localPath> \
+  --attachment <variableId>=<localPath>
+```
+
+> **Pre-flight.** Confirm each `<variableId>` exists in the flow's `variables.globals[]` with `direction:"in"` and `type:"file"`. See [shared/cli-commands.md — Pre-flight](../shared/cli-commands.md#pre-flight---attachment-binding).
+
+> **Reading the bound file.** At runtime a `file` variable is an object — a Script node reads the uploaded name via `$vars.{triggerNodeId}.output.{id}.FullName`. See [shared/variables-and-expressions.md — Runtime shape of a `file` variable](../shared/variables-and-expressions.md#file-input).
+
+### Reporting debug runs to the user
+
+The CLI response includes a **Studio Web URL** (where the user inspects the run) and an **instanceId** (for log/trace correlation). Parse both from the JSON output — typically `Data.studioWebUrl` and `Data.instanceId` — and **always show them as the first two lines of the summary**:
+
+```text
+Studio Web URL: <url>
+Instance ID: <instanceId>
+
+<run status, node traces, errors, etc.>
+```
+
+If either value is missing from the response, emit the label with `<not returned by CLI>` rather than dropping the line. Do not bury these values below the run summary — the user should see them immediately without scrolling.
+
+### When the run faults
+
+`Data.finalStatus: "Faulted"` means the run failed, and the cause is already in that same response — read it there. Redirect stdout to a file and extract the cause from the file; on a faulted run the CLI ignores `--output-filter` and prints the whole envelope, so the filter is not a way to shrink it:
+
+```bash
+UIP_LOG_LEVEL=info uip maestro flow debug <path-to-project-dir> --output json > /tmp/flow-debug.json
+```
+
+Extraction commands and fault-code lookup: [diagnose/troubleshooting-guide.md — Step 0](../diagnose/troubleshooting-guide.md#step-0--read-the-cause-in-the-debug-output-you-already-have).
+
+See [shared/cli-commands.md — uip maestro flow debug](../shared/cli-commands.md#uip-maestro-flow-debug) for additional options.
+
+## Process run — trigger a deployed process
+
+For flows already deployed to Orchestrator (via [ship.md](ship.md) → Orchestrator path):
+
+```bash
+uip maestro flow process list --output json                           # discover deployed processes
+uip maestro flow process run <process-key> <folder-key> --output json # trigger a run
+```
+
+Pass input arguments and/or bind file-typed input variables:
+
+```bash
+# Replace <variableId> and <localPath> placeholders below with your own values.
+uip maestro flow process run <process-key> <folder-key> --output json \
+  --inputs '{"numberA": 5, "numberB": 7}' \
+  --attachment <variableId>=<localPath>
+```
+
+> **Pre-flight.** Confirm each `<variableId>` exists in the flow's `variables.globals[]` with `direction:"in"` and `type:"file"` — see [shared/cli-commands.md — Pre-flight](../shared/cli-commands.md#pre-flight---attachment-binding). On `process run` only: `--attachment` overrides `--inputs` on key collisions; `--validate` accepts pre-uploaded attachment references for file-typed slots (passes the JSON-schema check even though the slot's nominal type is `string`).
+
+Run `uip maestro flow process --help` for all subcommands and options.
+
+## Job inspection — status and traces
+
+```bash
+uip maestro flow job status <job-key> --output json   # check status of a running or completed job
+uip maestro flow job traces <job-key> --output json   # stream the verbose execution timeline
+```
+
+> **Traces are verbose** and contain the full execution timeline. Use them only when needed for diagnosis — start from incidents first via [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md).
+
+## What's next
+
+- **Run failed?** Triage via [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md) — start with incidents, escalate to traces only if needed.
+- **Need to intervene in a running instance** (pause, resume, cancel, retry)? See [manage.md](manage.md).
+
+## Anti-patterns
+
+- **Never substitute `flow debug` for `flow validate` as the structural check.** Use `uip maestro flow validate` for schema and graph correctness; debug is the end-to-end run rule #2 mandates, and skipping it leaves the flow unverified.
+- **Never re-run a completed `flow debug` to re-read or reshape its output.** Each run re-uploads the solution and executes the flow again for real. Extract the report fields from the payload the completed run already returned — see [Reporting debug runs](#reporting-debug-runs-to-the-user). For a faulted run, read the cause first — see [When the run faults](#when-the-run-faults).
+- **Never skip `solution resources refresh` before debug.** Stale resource declarations cause runtime binding failures even when the local `.flow` is correct.
+- **Never start diagnosis from `job traces`.** Traces are last-resort — see [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md) for the priority ladder.

package/skills/uipath-maestro-flow/references/operate/ship.md

@@ -0,0 +1,57 @@
+# Ship — Publish a Flow
+
+Publish journey for a Flow project. Two paths: **Studio Web upload** (default) and **Orchestrator deploy** (only when explicitly requested). Both require `uip login`.
+
+> **When to use which path:** if the user says "publish" without specifying where, default to Studio Web. Only use Orchestrator deploy when the user explicitly asks to deploy to Orchestrator. Studio Web upload lets the user visualize, inspect, edit, and publish from the browser; Orchestrator deploy puts the flow directly into a process, bypassing Studio Web — the user cannot visualize or edit it there.
+
+## Pre-flight
+
+Before either publish path, ensure:
+
+1. **Authoring is complete.** `uip maestro flow validate` passes and `uip maestro flow format` was run. If not, send the user back to [author/CAPABILITY.md](../author/CAPABILITY.md).
+2. **Logged in.** `uip login status --output json` returns success. See [shared/cli-conventions.md — Login state](../shared/cli-conventions.md#5-login-state).
+3. **Solution resources are refreshed.** Always run this before `solution upload` or `solution publish` so that connection and process resource declarations are in sync with the project bindings:
+
+   ```bash
+   uip solution resources refresh --solution-folder <SolutionDir> --output json
+   ```
+
+   `<SolutionDir>` is the solution directory (containing the `.uipx` file). The command has no positional solution argument; omit `--solution-folder` only when the current directory is already the solution root.
+
+## Path 1 — Studio Web upload (default)
+
+After `solution resources refresh`, upload the solution to Studio Web:
+
+```bash
+uip solution upload <SolutionDir> --output json
+```
+
+`uip solution upload` accepts the solution directory directly — no intermediate bundling step required. Use the exact solution root path (or `.` from inside the solution root). If your shell is inside the nested flow project folder, pass the absolute solution root path or `..`; do not pass the solution name again, because that resolves to a child path that does not exist. If the project was created with `uip maestro flow init`, it already lives inside a solution directory. The command pushes it to Studio Web where the user can visualize, inspect, edit, and publish from the browser.
+
+**Share the Studio Web URL with the user** when the upload succeeds.
+
+## Path 2 — Orchestrator deploy (explicit only)
+
+Use this path **only when the user explicitly asks to deploy to Orchestrator.** Otherwise, default to Studio Web.
+
+Pack the flow project into a `.nupkg` then publish via the platform skill:
+
+```bash
+# 1. Refresh solution resources
+uip solution resources refresh --solution-folder <SolutionDir> --output json
+
+# 2. Pack
+uip maestro flow pack <project-path> <OutputDir>
+```
+
+For `uip solution publish` and the rest of the deployment workflow, see [/uipath:uipath-solution](/uipath:uipath-solution). See [shared/cli-commands.md — uip maestro flow pack](../shared/cli-commands.md#uip-maestro-flow-pack) for `pack` flags.
+
+## Anti-patterns
+
+- **Never run `solution upload` without `solution resources refresh` first.** Stale resource declarations cause runtime binding failures (the deployed flow can't find its connections).
+- **Never default to Orchestrator deploy when the user said "publish".** "Publish" without specifier means Studio Web. When the target is ambiguous, ask the user with **Studio Web upload** / **Orchestrator deploy** / **Something else** as options before running `flow pack` + `solution publish`. See the dropdown question rule in [SKILL.md](../../SKILL.md).
+- **Never publish a flow that hasn't been validated and formatted.** `flow validate` catches schema errors; `flow format` ensures Studio Web renders nodes correctly. Both are author-side gates — see [author/CAPABILITY.md](../author/CAPABILITY.md).
+
+## What's next
+
+After Studio Web upload, the user typically wants to **debug** the flow end-to-end against real systems. See [run.md](run.md). After Orchestrator deploy, the user typically wants to **trigger and monitor** the deployed process — also [run.md](run.md).

package/skills/uipath-maestro-flow/references/shared/action-nodes.md

@@ -0,0 +1,100 @@
+# Action Node Structure
+
+Reference boilerplate shared by every action-node `impl.md`. Plugin docs should link here and specify only the registry type string, plugin-specific inputs and rules, debug entries, and node-type configuration workflows.
+
+## Registry validation
+
+Before authoring, run:
+
+```bash
+uip maestro flow registry get <node-type> --output json
+```
+
+`registry get` returns the manifest at `Data.Node`; do not inspect `Data` directly as the node manifest.
+
+```json
+{
+  "Data": {
+    "Node": {
+      "nodeType": "core.action.script",
+      "version": "1.0",
+      "handleConfiguration": [
+        { "position": "left", "handles": [{ "id": "input", "type": "target" }] },
+        { "position": "right", "handles": [{ "id": "success", "type": "source" }] }
+      ],
+      "inputDefinition": {},
+      "outputDefinition": {}
+    }
+  }
+}
+```
+
+Inspect `Data.Node.handleConfiguration` for input and output port names; it is an array of position groups, not a map with a top-level `handles` field. Inspect `Data.Node.inputDefinition` for required inputs, `Data.Node.outputDefinition` for downstream payloads, and `Data.Node.model.serviceType` where applicable. Each plugin `impl.md` records what to confirm for its node type.
+
+## Standard JSON skeleton
+
+Every action-node instance uses this base shape:
+
+```json
+{
+  "id": "<nodeId>",
+  "type": "<node-type>",
+  "typeVersion": "<version>",
+  "display": { "label": "<Label>" },
+  "inputs": { /* plugin-specific — see plugin impl.md */ },
+  "outputs": {
+    "output": {
+      "type": "object",
+      "description": "<plugin-specific description>",
+      "source": "=result.response",
+      "var": "output"
+    },
+    "error": {
+      "type": "object",
+      "description": "Error information if the action fails.",
+      "source": "=Error",
+      "var": "error"
+    }
+  }
+}
+```
+
+`outputs.output` documents the success payload referenced downstream as `=js:$vars.{nodeId}.output`; `outputs.error` documents the failure shape. Runtime faults route to the implicit `error` port. See [Implicit error port on action nodes](file-format.md#implicit-error-port-on-action-nodes).
+
+For action nodes, the instance `outputs` block is documentation, not the runtime contract. The matching `variables.nodes[]` entry exposes process-level `$vars.{nodeId}.output`; see [file-format.md — Node outputs](file-format.md#node-outputs). The BPMN emitter ignores the instance `outputs` block at serialization because the manifest's `outputDefinition` drives activity-side mapping.
+
+**Exceptions:** Orchestrator-job nodes (api-workflow, rpa-workflow, agent, agentic-process, function) have their instance `outputs` read by the converter, which copies each `source` verbatim. A wrong `source` (for example, `=result.response`) breaks `$vars.{nodeId}.output`; declare `error` only there. End / terminate nodes also have their instance `outputs` consumed to map workflow-level `out` variables.
+
+**Data Fabric entity nodes (`core.datafabric.*`) carry no instance `outputs` block at all** — the canvas writes none, so author `inputs` only and let `flow format` regenerate `variables.nodes[]`. They are also the one action-node family with **no `error` port**: none declares `supportsErrorHandling`, so the skeleton's `outputs.error` and the implicit error port in [Standard ports](#standard-ports) do not apply to them. See [data-fabric/impl.md](../author/plugins/data-fabric/impl.md#no-error-port).
+
+`uip maestro flow format` regenerates `variables.nodes[]` from the current node graph, so running format after structural edits self-heals an omitted entry.
+
+## Standard ports
+
+| Direction | Common name(s) | Notes |
+| --- | --- | --- |
+| Input (target) | `input` | Every action node accepts one input edge on `input`. |
+| Output (success, source) | `output`, `default`, or `success` | The name varies by plugin; `registry get` is authoritative. |
+| Output (error, source) | `error` | Implicit on action nodes that declare `supportsErrorHandling`, via `outputs.error`. The `core.datafabric.*` family does not — it has no `error` port. |
+
+Plugins may add dynamic source ports, such as HTTP `branch-{id}` from `inputs.branches`; document these in the plugin's `impl.md`.
+
+## Adding and editing procedures
+
+Use [editing-operations.md](../author/editing-operations.md) and [editing-operations-json.md](../author/editing-operations-json.md) for step-by-step add, delete, and wiring instructions. Plugin `impl.md` files should describe only node-type-specific inputs and wiring patterns.
+
+## Migrating a plugin to reference this template
+
+Keep in the plugin:
+
+- registry type string and `typeVersion`;
+- plugin-specific input fields;
+- plugin-specific configuration workflows, such as `node configure` for HTTP/connector nodes;
+- plugin-specific rules, common patterns, and debug table.
+
+Replace with a link here:
+
+- generic JSON skeleton;
+- generic `outputs` block (`=result.response` / `=result.Error`);
+- generic registry-validation prose;
+- generic "Adding / Editing" cross-reference.