@uipath/skills 1.195.0

package/skills/uipath-maestro-flow/references/evaluate/references/running-guide.md

@@ -0,0 +1,215 @@
+# Running Flow Evaluations
+
+`uip maestro flow eval run *` — start, monitor, inspect, and compare evaluation runs. All run commands require `uip login` and a Flow solution that already exists in Studio Web.
+
+> **Before running any of these:** read [upload-safety.md](upload-safety.md). The skill must NOT auto-run `uip solution upload` to satisfy the "solution must be in Studio Web" prerequisite. If the solution isn't in Studio Web, ask the user.
+
+## Start a Run
+
+```bash
+uip maestro flow eval run start \
+  --set "<set_name>" \
+  --path <flow_project> \
+  [--entry-point <entry>] \
+  [--solution-id <id>] \
+  [--project-id <id>] \
+  [--folder-key <key>] \
+  [--debug-mode <mode>] \
+  [--wait [--timeout <seconds>]] \
+  --output json
+```
+
+### Resolution order for `--solution-id` / `--project-id`
+
+The CLI auto-resolves these from project metadata in the working tree (typically `SolutionStorage.json` and the parent `.uipx`). Pass `--solution-id` or `--project-id` explicitly only when the working tree does not have those IDs (e.g., a freshly scaffolded local project that has never been uploaded).
+
+If the auto-resolution fails AND you have not passed explicit IDs, the start command will error. Do NOT respond by running `uip solution upload` automatically — see [upload-safety.md](upload-safety.md) for the right action.
+
+### `--folder-key`
+
+The Orchestrator folder key that scopes the run. Defaults to the user's personal workspace. Pass an explicit folder key when the eval should run in a shared/team folder.
+
+### `--wait` and `--timeout`
+
+Without `--wait`, the command returns immediately with `EvalSetRunId`. With `--wait`, the CLI blocks until the run reaches a terminal state (`Completed` or `Failed`) or `--timeout` elapses (default 600s, hardcoded by the CLI).
+
+`--timeout` only stops the local CLI from blocking. The server-side run continues regardless. Query progress with:
+
+```bash
+uip maestro flow eval run status <eval_set_run_id> \
+  --set "<set_name>" --path <flow_project> --output json
+```
+
+Polling cadence is not part of the public CLI contract — do not depend on a specific interval.
+
+### Output (no `--wait`)
+
+```json
+{
+  "Code": "MaestroFlowEvalRunStarted",
+  "Data": {
+    "EvalSetRunId": "a1b2c3d4-...",
+    "EvalSetName": "Smoke Tests",
+    "DataPoints": 3,
+    "Evaluators": 2
+  }
+}
+```
+
+### Output (`--wait`, on completion)
+
+The CLI emits a summary plus per-data-point results. Use `run results` for the same data on a completed run.
+
+## Check Status
+
+```bash
+uip maestro flow eval run status <eval_set_run_id> \
+  --set "<set_name>" \
+  --path <flow_project> \
+  --output json
+```
+
+```json
+{
+  "Code": "MaestroFlowEvalRunStatus",
+  "Data": {
+    "EvalSetRunId": "a1b2c3d4-...",
+    "Status": "Completed",
+    "Score": 0.86,
+    "Duration": "42.5s"
+  }
+}
+```
+
+Status values: `Pending`, `Running`, `Completed`, `Failed`. `Completed` and `Failed` are terminal.
+
+## Detailed Results
+
+```bash
+uip maestro flow eval run results <eval_set_run_id> \
+  --set "<set_name>" \
+  --path <flow_project> \
+  [--only-failed] \
+  [--verbose] \
+  [--export-format json|csv] \
+  --output json
+```
+
+Per-data-point fields: `DataPoint`, `Status`, `EvaluatorScores`, `Duration`, `Error` (plus `Justifications` when `--verbose`).
+
+### `--only-failed`
+
+Filter to data points that errored or scored a hard failure. Triage faster on large sets.
+
+### `--verbose`
+
+Include the LLM judge's free-text justification per evaluator. Essential when a score is surprising.
+
+### `--export-format <json|csv>`
+
+Write results to a file alongside the project (e.g., `eval-results-<timestamp>.json` or `.csv`). Useful for archiving or feeding into a dashboard.
+
+### Filtering with `--output-filter`
+
+`--output-filter` takes a JMESPath expression and applies it to the JSON payload before printing. Useful for triage:
+
+```bash
+# Show only data points named "checkout-flow"
+uip maestro flow eval run results <run_id> \
+  --set "Smoke Tests" --path ./MySolution/MyFlow --output json \
+  --output-filter 'Data.Results[?DataPoint==`checkout-flow`]'
+
+# Show only score and name per row
+uip maestro flow eval run results <run_id> \
+  --set "Smoke Tests" --path ./MySolution/MyFlow --output json \
+  --output-filter 'Data.Results[*].{name: DataPoint, score: Score}'
+```
+
+## List Past Runs
+
+```bash
+uip maestro flow eval run list \
+  --set "<set_name>" \
+  --path <flow_project> \
+  --output json
+```
+
+Per-row: `EvalSetRunId`, `Status`, `Score`, `DataPoints`, `Duration`, `CreatedAt`.
+
+## Compare Two Runs
+
+```bash
+uip maestro flow eval run compare <run_id_a> \
+  --compare-to <run_id_b> \
+  --set "<set_name>" \
+  --path <flow_project> \
+  --output json
+```
+
+Output:
+
+```json
+{
+  "Code": "MaestroFlowEvalRunComparison",
+  "Data": {
+    "RunA": { "Id": "...", "Score": 0.86, "Status": "Completed" },
+    "RunB": { "Id": "...", "Score": 0.80, "Status": "Completed" },
+    "ScoreDelta": 0.06,
+    "DataPoints": [
+      {
+        "DataPoint": "hello-test",
+        "ScoreA": 1.0, "ScoreB": 0.9, "Delta": "+0.1",
+        "StatusA": "Completed", "StatusB": "Completed"
+      }
+    ]
+  }
+}
+```
+
+`compare` aligns by data point `name` within the eval set. Comparing runs from different eval sets is not supported — the deltas would be meaningless.
+
+Use `compare` after each prompt or flow change to verify the change improved scores without regressing other data points.
+
+## Workflow Example
+
+```bash
+# 1. Verify the solution is in Studio Web (do NOT auto-upload — see upload-safety.md)
+#    If unsure, list runs first; absence of any error here implies the solution exists.
+uip maestro flow eval run list --set "Smoke Tests" --path ./MySolution/MyFlow --output json
+
+# 2. Start the run, block on completion
+uip maestro flow eval run start \
+  --set "Smoke Tests" \
+  --path ./MySolution/MyFlow \
+  --wait --timeout 600 --output json
+
+# 3. Inspect failures with justifications
+uip maestro flow eval run results <run_id> \
+  --set "Smoke Tests" \
+  --only-failed --verbose \
+  --path ./MySolution/MyFlow --output json
+
+# 4. After fixing the flow, re-run and compare
+uip maestro flow eval run start --set "Smoke Tests" --path ./MySolution/MyFlow --wait --output json
+uip maestro flow eval run compare <new_run_id> --compare-to <old_run_id> \
+  --set "Smoke Tests" --path ./MySolution/MyFlow --output json
+```
+
+## Failure Detection
+
+A data point is considered failed when any of these are true:
+
+- `Status` is `Failed`
+- `Error` is non-null
+- Any evaluator score type is `error`
+- An exact-match evaluator returned `false`
+
+Use `--only-failed` to filter to these rows. Use `--verbose` to read the justifications.
+
+## Anti-patterns
+
+- **Don't auto-run `uip solution upload`** when `eval run start` errors with a missing-solution error. Stop and ask the user — see [upload-safety.md](upload-safety.md).
+- **Don't depend on `--wait`'s polling cadence.** Treat as a black-box block.
+- **Don't compare runs from different eval sets.** `compare` aligns by data point name; cross-set deltas are meaningless.
+- **Don't rely on aggregate `Score` alone.** Inspect per-evaluator scores. A 0.86 aggregate can mask a high-similarity-but-wrong-trajectory failure.
+- **Don't keep retrying `eval run status` while `--wait` is still blocking from another shell.** Pick one — either `--wait` or polling status — to avoid race conditions on the same run ID.

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

@@ -0,0 +1,82 @@
+# Upload Safety: Do Not Auto-Run `uip solution upload`
+
+The eval run requires the Flow solution to exist in Studio Web. The temptation, when an eval run errors with a missing-solution or missing-IDs error, is to "fix" it with `uip solution upload`. **Don't.**
+
+## The Rule
+
+**The skill must NEVER run `uip solution upload` automatically as part of an evaluation workflow. Always ask the user first.**
+
+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 agent pull` 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 `SolutionId` from the local working tree. 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. **`SolutionStorage.json` is missing or has no `SolutionId`.** The local working tree has not been linked to a Studio Web solution. `uip solution 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.
+
+## 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
+```
+
+If this returns successfully (even with zero past runs), the solution is in Studio Web. If it errors with a missing-solution or auth error, treat the solution as not-yet-uploaded — and follow the rule above.
+
+Alternatively, `eval run start` itself will fail fast with a clear error. Either way: **read-only probe first; ask before upload.**
+
+## When the User Explicitly Asks to Upload
+
+If the user tells the skill to upload (e.g., "go ahead and upload the solution"), the skill is allowed to run:
+
+```bash
+uip solution upload <SolutionDir> --output json
+```
+
+In that response:
+
+1. Echo the command back so the user can see exactly what is being run.
+2. Run it and report the `SolutionId` and `DesignerUrl` from the output.
+3. Then proceed with the eval run.
+
+Even with explicit consent, do not chain `solution upload` automatically into the next step — surface the result first.
+
+## Anti-patterns
+
+- **Don't run `uip solution upload` as part of "fixing" an eval-run error.** Ask first.
+- **Don't infer consent from a vague instruction like "make the eval work."** That is not consent to upload; it is a request to diagnose.
+- **Don't auto-retry an eval run after a failed solution-resolution by attempting `uip solution upload` and re-running.** That doubles down on the wrong action.
+- **Don't run `uip solution upload` while another user might be editing the solution on Studio Web.** Even with explicit consent, warn the user that overwriting concurrent edits is a possible outcome.
+- **Don't combine `flow debug` and `eval run` in the same session against the same solution.** Each carries its own Studio Web debug session; mixing them confuses run IDs and may trigger unexpected uploads.

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

@@ -0,0 +1,76 @@
+# 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 resource 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, AskUserQuestion dropdown pattern, solution layout, **plain-English narration + granular `TodoWrite` (opt-in — silent by default; engage when the user asks for verbosity)**. The rules below are 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 resource refresh`)
+
+## Critical rules
+
+1. **Always run `uip solution resource refresh <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.
+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. 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](references/ship.md) |
+| Run a flow on demand or check progress | [run.md](references/run.md) |
+| Intervene in a running instance | [manage.md](references/manage.md) |
+
+## Common tasks
+
+| I need to... | Read these |
+| --- | --- |
+| **Publish a flow to Studio Web** | [ship.md — Path 1](references/ship.md#path-1--studio-web-upload-default) |
+| **Deploy a flow to Orchestrator** (only if explicitly requested) | [ship.md — Path 2](references/ship.md#path-2--orchestrator-deploy-explicit-only) + [/uipath:uipath-solution](/uipath:uipath-solution) |
+| **Sync solution resource declarations** | [ship.md — Pre-flight](references/ship.md#pre-flight) (the `uip solution resource refresh` step) |
+| **Debug a flow end-to-end** | [run.md — Debug](references/run.md#debug--controlled-end-to-end-run) |
+| **Pass input arguments to `flow debug`** | [run.md — Debug](references/run.md#debug--controlled-end-to-end-run) (the `--inputs` flag) |
+| **Bind local files to file-typed inputs** | [run.md — Debug](references/run.md#debug--controlled-end-to-end-run) and [run.md — Process run](references/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](references/run.md#process-run--trigger-a-deployed-process) |
+| **Check status of a running job** | [run.md — Job inspection](references/run.md#job-inspection--status-and-traces) |
+| **Stream verbose execution traces** | [run.md — Job inspection](references/run.md#job-inspection--status-and-traces) (use sparingly — see [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md)) |
+| **Pause a running instance** | [manage.md](references/manage.md) |
+| **Resume a paused instance** | [manage.md](references/manage.md) |
+| **Cancel an instance** | [manage.md](references/manage.md) |
+| **Retry a faulted instance** | [manage.md](references/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 resource 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.** Use `uip maestro flow validate` for correctness checking; debug is for end-to-end execution against real systems.
+- **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](references/ship.md) — Studio Web upload (default) and Orchestrator deploy (explicit)
+- [run.md](references/run.md) — debug, process run, job status/traces
+- [manage.md](references/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 resource refresh`, `flow pack`, `flow debug`, `flow process`, `flow job`, `flow instance`
+- [shared/cli-conventions.md](../shared/cli-conventions.md) — login states, FOLDER_KEY, UIPCLI_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/references/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/references/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/references/run.md

@@ -0,0 +1,99 @@
+# 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 resource refresh <SolutionDir> --output json
+   ```
+
+## Debug — controlled end-to-end run
+
+> **Confirm consent first.** `flow debug` executes the flow for real — sends emails, posts messages, calls APIs. See the consent-before-debug rule in [SKILL.md](../../../SKILL.md). Do not run without explicit user authorization.
+
+```bash
+UIPCLI_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.
+
+Pass input arguments when the flow has input parameters:
+
+```bash
+UIPCLI_LOG_LEVEL=info uip maestro flow debug <path-to-project-dir> --output json \
+  --inputs '{"numberA": 5, "numberB": 7}'
+```
+
+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.
+UIPCLI_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.
+
+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 run `flow debug` as a validation step.** Use `uip maestro flow validate` for correctness checking; debug is for end-to-end execution.
+- **Never skip `solution resource 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/references/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 resource refresh <SolutionDir> --output json
+   ```
+
+   The argument is the solution directory (containing the `.uipx` file). Defaults to the current directory if omitted.
+
+## Path 1 — Studio Web upload (default)
+
+After `solution resource 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. 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 resource refresh <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 resource 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, confirm via `AskUserQuestion` with **Studio Web upload** / **Orchestrator deploy** / **Something else** as options before running `flow pack` + `solution publish`. See the AskUserQuestion dropdown 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).