@uipath/skills 1.195.0

package/skills/uipath-maestro-flow/references/diagnose/references/failure-modes.md

@@ -0,0 +1,283 @@
+# Failure Modes — Pattern Catalog
+
+Lookup table for known recurring failure modes in Maestro Flow projects. Each entry: what the failure looks like, why it happens, how to fix it, where to read more. Use this when you have an error symptom in hand and want to identify the pattern.
+
+> **Hot-path triage:** if you have a failed run and need to investigate from scratch, start at [troubleshooting-guide.md](troubleshooting-guide.md) (the priority ladder: incidents → variables → flow correlation → traces). This document is the **lookup catalog** — read it after the ladder identifies a known pattern, or when the symptom matches an entry below.
+
+## Index
+
+| Pattern | Symptom | Cause |
+|---|---|---|
+| [MST-9107](#mst-9107--js-prefix-missing) | Activity input bound to literal string `"vars.X.output.Y"` | Missing `=js:` prefix on a `$vars` reference. `flow validate` catches this — pre-`expression-prefix-validator` cli still ships the literal at runtime. |
+| [MST-9972](#mst-9972--variablesnodes-missing-vars-resolves-to-undefined) | `Cannot read property 'output' of undefined` on a downstream node | Direct-authored `.flow` skipped `variables.nodes[]`; `flow validate` accepts it but the BPMN has no process-level variable declaration for the upstream node. |
+| [MST-9061](#mst-9061--misshapen-rectangle-nodes-in-studio-web) | Nodes render as oblong rectangles, not squares | `flow format` not run before publish |
+| [HITL `completed` port unwired](#hitl-completed-port-unwired) | Flow hangs indefinitely after a HITL node | No outgoing edge from the node's `completed` source port |
+| [Reused reference ID](#reused-reference-id--cross-connection-id-leakage) | Connector node faults silently at runtime | Reference ID copied from a prior flow's connection |
+| [Single-nested layout](#single-nested-layout) | Studio Web upload fails; `flow init` auto-registration is skipped | `uip maestro flow init` was run outside a solution directory |
+| [Missing `bindings[]` on resource node](#missing-bindings-on-resource-node) | `Folder does not exist or the user does not have access to the folder` | Top-level `bindings[]` entries not added for a `uipath.core.*` resource node |
+| [`flow validate` passes, `flow debug` faults](#flow-validate-passes-flow-debug-faults) | Local validation green, cloud run red | Multiple causes — narrower than before (MST-9107 + expression-ref linting now catch a large slice statically). See entry for the residual triage path. |
+
+---
+
+## MST-9107 — `=js:` prefix missing
+
+### Symptom
+
+A connector, HTTP, or end node receives the literal string `"vars.X.output.Y"` as its input value at runtime instead of the resolved value.
+
+`flow validate` flags this as an error today (cli-side `expression-prefix-validator`, emitted with a remediation hint pointing at the `=js:`-prefixed form). Pre-validator cli versions miss it and the failure surfaces only at `flow debug` or in deployed runs — if you see the symptom without a corresponding validate error, your cli is older than the fix.
+
+Example: input field set to literal `"vars.createEntityRecord1.output.Id"` instead of the entity's actual ID.
+
+### Cause
+
+The `=js:` prefix was omitted on a `$vars` / `$metadata` / `$self` reference inside a value field. The serializer rewrites `$vars` → `vars` whether or not the prefix is present, so a missing `=js:` yields a string that **looks like** an unevaluated expression but is actually a literal.
+
+There is also no `nodes.X.output.Y` syntax — that is an invented form that silently ships as a literal string. `flow validate` flags this same way (rewriting the suggested fix to the `=js:$vars.X.output.Y` form).
+
+### Fix
+
+Add `=js:` to every `$vars`/`$metadata`/`$self` reference in:
+
+- Connector `inputs.detail.bodyParameters` / `queryParameters` / `pathParameters`
+- HTTP `url` / `headers` / `body`
+- End node output `source`
+- Variable update `expression`
+- Loop `collection`
+- Subflow `inputs.<id>.source`
+
+Do **not** add `=js:` to condition expressions (decision `expression`, switch case `expression`, HTTP branch `conditionExpression`) — those are evaluated as JavaScript automatically.
+
+### Reference
+
+[shared/node-output-wiring.md](../../shared/node-output-wiring.md) — canonical per-node-type field reference.
+
+---
+
+## MST-9972 — `variables.nodes[]` missing → `$vars.X.output` resolves to undefined
+
+### Symptom
+
+A downstream script or expression reads `$vars.<sourceNodeId>.output` and gets `undefined` at runtime. Common shapes: `Cannot read property 'output' of undefined`, `Cannot read properties of undefined (reading '<field>')`, or a connector activity receiving an empty / undefined input that an upstream node should have populated. `uip maestro flow validate` accepts the file without complaint. The upstream node's own incident shows it ran successfully.
+
+### Cause
+
+The `.flow` file is missing `variables.nodes[]` entries for the upstream node. The BPMN emitter walks `variables.nodes[]` to write the process-level `<uipath:inputOutput id="<nodeId>.<outputId>">` declarations the runtime needs — without them, the activity's local `output` value has no process variable to flow into, and downstream `$vars` reads fail.
+
+This happens almost exclusively on **direct-authored** `.flow` files: `uip maestro flow node add` and the canvas / Studio Web save path both auto-populate `variables.nodes[]`. `Edit` / `Write` authoring does not, and pre-fix `uip maestro flow format` did not regenerate it either. Adding an `outputs` block on the action-node instance does **not** fix this — for action nodes the BPMN emitter reads the manifest's `outputDefinition`, not the instance block, so authoring the instance block has no runtime effect.
+
+### Fix
+
+Run `uip maestro flow format <ProjectName>.flow --output json`. Post-MST-9972 the format command regenerates `variables.nodes[]` from `nodes[]` + `definitions[]` (matching `node add` and canvas behavior). On older CLI versions, add the entries manually:
+
+```json
+"variables": {
+  "nodes": [
+    {
+      "id": "<nodeId>.output",
+      "type": "object",
+      "binding": { "nodeId": "<nodeId>", "outputId": "output" }
+    },
+    {
+      "id": "<nodeId>.error",
+      "type": "object",
+      "binding": { "nodeId": "<nodeId>", "outputId": "error" }
+    }
+  ]
+}
+```
+
+One entry per declared output (trigger nodes: `output` only; action nodes: `output` + `error`; end / terminate: none).
+
+### Reference
+
+[shared/file-format.md — Node outputs](../../shared/file-format.md#node-outputs), [author/CAPABILITY.md rule #14](../../author/CAPABILITY.md), [editing-operations-json.md — Pre-flight Checklist step 5–6](../../author/references/editing-operations-json.md#pre-flight-checklist).
+
+---
+
+## MST-9061 — Misshapen rectangle nodes in Studio Web
+
+### Symptom
+
+After publish or debug upload, Studio Web renders nodes as oblong rectangles (e.g., 200×80) instead of square tiles. Layout looks visually broken even though the flow runs correctly.
+
+### Cause
+
+`uip maestro flow format` was not run before publishing or debugging. Hand-written or stale `layout` data with non-96 dimensions remains in the `.flow` file and Studio Web renders it as-is.
+
+### Fix
+
+Run format before any publish or debug operation:
+
+```bash
+uip maestro flow format <ProjectName>.flow --output json
+```
+
+Format:
+
+- Sets every non-`stickyNote` node's `size` to `{ "width": 96, "height": 96 }`
+- Arranges nodes horizontally with ELK at `nodeSpacing: 96`
+- Recurses into subflows and rewrites `subflows[<id>].layout`
+- Preserves sticky note custom sizes
+
+### Reference
+
+[author capability](../../author/CAPABILITY.md) — see "Always run `flow format` after edits" in critical rules; [shared/cli-commands.md — uip maestro flow format](../../shared/cli-commands.md#uip-maestro-flow-format).
+
+---
+
+## HITL `completed` port unwired
+
+### Symptom
+
+Flow execution reaches a HITL QuickForm node, the human task is created and completed, but the flow blocks indefinitely afterward. No further nodes execute.
+
+### Cause
+
+The HITL node's `completed` output handle has no outgoing edge — there is no consumer for the `completed` port event.
+
+### Fix
+
+Add an edge from the HITL node's `completed` port to the next node in the flow. After running `uip maestro flow hitl add`, always wire the `completed` port before validating.
+
+### Reference
+
+[Author HITL plugin reference](../../author/references/plugins/hitl/impl.md) — full HITL node reference including port wiring requirements.
+
+---
+
+## Reused reference ID — cross-connection ID leakage
+
+### Symptom
+
+A connector node passes `flow validate` and `node configure` cleanly. At runtime (`flow debug` or deployed run), the node faults silently with no resolvable error.
+
+Common scenarios:
+
+- A `parentFolderId` from one Outlook mailbox used in a flow connected to a different Outlook mailbox
+- A Slack channel ID from one workspace used in a flow connected to a different Slack workspace
+- A Jira project key copied from a prior session
+
+### Cause
+
+Reference IDs (mailbox folders, Slack channels, Jira projects, Google Sheets, etc.) are **scoped to the specific authenticated account behind the connection**. They are not portable across connections, even when the connection points to the same connector type.
+
+### Fix
+
+Always re-resolve reference IDs against the connection bound to the current flow. Never paste a value you saw in another flow or session:
+
+```bash
+uip is resources run list <connector-key> <objectName> --connection-id <CURRENT_CONNECTION_ID> --output json
+```
+
+### Reference
+
+- [Author connector plugin — Step 4](../../author/references/plugins/connector/impl.md)
+- [Author connector-trigger plugin — Step 3](../../author/references/plugins/connector-trigger/impl.md)
+
+---
+
+## Single-nested layout
+
+### Symptom
+
+`uip solution upload` rejects the project. `flow init` returned without a `Data.SolutionRegistration` block (auto-registration walks up looking for the nearest `.uipx`; when the project is created outside the solution, it finds none and skips silently). Studio Web upload fails with structural errors. Packaging fails.
+
+The `.flow` file lives at `<Project>/<Project>.flow` (single-nested) instead of the required `<Solution>/<Project>/<Project>.flow` (double-nested).
+
+### Cause
+
+`uip maestro flow init` was run from outside a solution directory — from a bare cwd, from the user's home directory, or from the parent of the solution.
+
+### Fix
+
+Delete the partial scaffold. Restart in the correct order — `flow init` from inside the solution directory will auto-register the project with the `.uipx`, so the explicit `uip solution project add` step is no longer needed.
+
+```bash
+uip solution init "<SolutionName>" --output json
+cd <SolutionName>
+uip maestro flow init <ProjectName> --output json
+# Confirm Data.SolutionRegistration.Status is "Registered" in the JSON response.
+# Only if Status is "Skipped" / "Failed" do you need:
+#   uip solution project add <SolutionName>/<ProjectName> <SolutionName>/<SolutionName>.uipx
+```
+
+After running, verify the file exists at the double-nested path. The `cd <SolutionName>` above persists across Bash calls, so anchor the check with `$(pwd)` instead of repeating `<SolutionName>/`:
+
+```bash
+ls "$(pwd)/<ProjectName>/<ProjectName>.flow"
+```
+
+A relative `ls "<SolutionName>/<ProjectName>/<ProjectName>.flow"` here resolves to `<SolutionName>/<SolutionName>/<ProjectName>/<ProjectName>.flow` (triple-nested) and reports "no such file" even on a correctly-scaffolded solution — a false negative that turns a healthy layout into a fake bug.
+
+If the absolute path doesn't exist, the `init` step was wrong — do not try to patch the layout by hand.
+
+### Reference
+
+[Author greenfield journey — Step 2](../../author/references/greenfield.md) — the canonical scaffold sequence.
+
+---
+
+## Missing `bindings[]` on resource node
+
+### Symptom
+
+`uip maestro flow validate` passes locally. At `uip maestro flow debug` (or in deployed runs), the resource node faults with:
+
+```text
+Folder does not exist or the user does not have access to the folder.
+```
+
+The error mentions a folder, but the actual cause is a missing binding entry.
+
+### Cause
+
+For `uipath.core.*` resource nodes (rpa, agent, flow, agentic-process, api-workflow, hitl), the registry definition carries `model.context[]` with `<bindings.{name}>` placeholders. The runtime rewrites these to `=bindings.{id}` at BPMN emit by matching `(resourceKey, name)` against the **top-level `bindings[]` array** in the `.flow` file. Without those entries, the placeholder never resolves and the runtime treats the binding as missing — surfacing as the folder-not-found error.
+
+`flow validate` checks JSON schema and cross-references; it does not validate that resource-node `model.context[]` entries are matched by top-level `bindings[]` entries.
+
+### Fix
+
+Add two entries to the top-level `bindings[]` array per resource node — `name` and `folderPath` — with `resourceKey` matching the definition's `model.bindings.resourceKey`. See the relevant resource plugin's `impl.md` for the exact shape ([rpa](../../author/references/plugins/rpa/impl.md), [agent](../../author/references/plugins/agent/impl.md), [flow](../../author/references/plugins/flow/impl.md), [agentic-process](../../author/references/plugins/agentic-process/impl.md), [api-workflow](../../author/references/plugins/api-workflow/impl.md), [hitl](../../author/references/plugins/hitl/impl.md)).
+
+### Reference
+
+[shared/file-format.md — Bindings](../../shared/file-format.md#bindings--orchestrator-resource-bindings-top-level-bindings)
+
+---
+
+## `flow validate` passes, `flow debug` faults
+
+### Symptom
+
+Local `uip maestro flow validate` returns `Result: Success`. The same flow fails at `uip maestro flow debug` with a runtime error.
+
+### Cause
+
+Multiple. `flow validate` runs a JSON schema check, cross-reference checks, expression-reference linting, and a small set of structural rules.
+
+**Caught** (validate exits non-zero, with a precise field path and remediation hint):
+
+- Missing `=js:` prefix on `$vars`/`$metadata`/`$self` (MST-9107) — emitted by cli-side `expression-prefix-validator`
+- Invented `nodes.<id>.output.<...>` syntax (MST-9107 variant) — same validator, suggests `=js:$vars.<id>.output.<...>` as the fix
+- References to unknown variable IDs or node IDs in `=js:` expressions (`EXPR_UNRESOLVED_REF`) — flow-schema `expression-ref` rule
+- Output-path walks that descend into a declared primitive (`type: "string"` etc.) or a schema closed with `additionalProperties: false` (`EXPR_INVALID_OUTPUT_PATH`) — flow-schema `expression-ref` rule
+- Missing End-node output mappings for declared `out` variables (`MISSING_OUTPUT_MAPPING`, **warning** severity) — flow-schema `output-mapping` rule
+- Connector `inputs.detail.configuration` missing, empty, missing the `essentialConfiguration` envelope, or containing invalid JSON inside the `=jsonString:` prefix — emitted with a shape hint pointing at `uip maestro flow node configure`. Re-run that command rather than hand-editing.
+
+**Not caught** — these still surface only at `flow debug` or in deployed runs:
+
+- Reused reference IDs → see [Reused reference ID](#reused-reference-id--cross-connection-id-leakage)
+- Missing top-level `bindings[]` entries on resource nodes → see [Missing `bindings[]` on resource node](#missing-bindings-on-resource-node)
+- HITL `completed` port unwired → see [HITL `completed` port unwired](#hitl-completed-port-unwired)
+- Stale `layout` data → see [MST-9061](#mst-9061--misshapen-rectangle-nodes-in-studio-web) (cosmetic, not faulting)
+- Output-path walks against **open** output schemas — HTTP response bodies, script returns, free-text agent output. The deep-path walker is permissive by design: it skips when the producer's schema doesn't authoritatively declare the field's structure, so e.g. `=js:$vars.fetchWeather.output.body.current_weather` against an HTTP node that declares only `output: { type: "object" }` passes validate and faults only when the runtime response doesn't have that path.
+- Wrong-direction reads (reading an `out`-only variable) — currently a runtime concern; the direction discriminator isn't yet threaded into the validator context.
+
+### Fix
+
+Triage via the diagnostic priority ladder in [troubleshooting-guide.md](troubleshooting-guide.md). Match the incident message and faulting element to the patterns above.
+
+### Reference
+
+[troubleshooting-guide.md](troubleshooting-guide.md) — start there for any "passes locally, fails in cloud" scenario.

package/skills/uipath-maestro-flow/references/diagnose/references/troubleshooting-guide.md

@@ -0,0 +1,115 @@
+# Troubleshooting Failed Flows
+
+Diagnostic workflow for failed debug runs and deployed process runs. All commands require `uip login`.
+
+> **`--folder-key` is required.** All `instance` and `incident get` commands require `--folder-key <FOLDER_KEY>`. Get the folder key from `uip or folders list --output json` or from the job/process context.
+
+## Diagnostic priority
+
+Investigate in this order — each step adds context, stop when you have enough to diagnose the root cause:
+
+1. Incidents (error message + faulting element)
+2. Runtime variables (data state at failure)
+3. Flow definition correlation (map element to `.flow` node)
+4. Traces (last resort — verbose full timeline)
+
+## Step 1 — Get the instance ID
+
+The debug output (`Data.instanceId`) or `job status` response contains the instance ID. If you only have a job key:
+
+```bash
+uip maestro flow job status <JOB_KEY> --output json
+```
+
+Parse the instance ID and folder key from the response.
+
+## Step 2 — Fetch incidents
+
+Failed flows always have an incident. Start here — incidents give you the error category, message, and the faulting element.
+
+```bash
+uip maestro flow instance incidents <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json
+```
+
+Drill into a specific incident for full detail:
+
+```bash
+uip maestro flow incident get <INCIDENT_ID> --folder-key <FOLDER_KEY> --output json
+```
+
+To get a cross-process incident overview:
+
+```bash
+uip maestro flow incident summary --output json
+```
+
+## Step 3 — Fetch runtime variable state
+
+Get the variable values at the time of failure to understand what data each node was working with:
+
+```bash
+uip maestro flow instance variables <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json
+```
+
+Scope to a specific element (node or subflow):
+
+```bash
+uip maestro flow instance variables <INSTANCE_ID> --folder-key <FOLDER_KEY> --parent-element-id <ELEMENT_ID> --output json
+```
+
+## Step 4 — Correlate with the flow definition
+
+Use the incident's faulting element ID and the variable state to locate the failure point in the `.flow` file. Map the element ID to the corresponding node, check its `inputs`, upstream edges, and the variable values flowing into it.
+
+If the local `.flow` file may differ from what was deployed, fetch the deployed BPMN definition:
+
+```bash
+uip maestro flow instance asset <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json
+```
+
+Additional instance inspection commands:
+
+```bash
+uip maestro flow instance element-executions <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json  # per-element execution details
+uip maestro flow instance cursors <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json             # current execution cursor positions
+```
+
+## Step 5 — Traces (last resort)
+
+Traces are verbose but contain the full execution timeline. Use them only when incidents and variables are insufficient:
+
+```bash
+uip maestro flow job traces <JOB_KEY> --output json
+```
+
+> **Always use CLI commands for troubleshooting — never call the underlying APIs directly.**
+
+## CLI command reference
+
+### uip maestro flow instance
+
+Inspect and manage Flow process instances. **Requires `uip login`.** All subcommands require `--folder-key <FOLDER_KEY>` (`-f` shorthand).
+
+```bash
+uip maestro flow instance list --output json                                                        # list all instances
+uip maestro flow instance get <INSTANCE_ID> -f <FOLDER_KEY> --output json                           # get instance details
+uip maestro flow instance incidents <INSTANCE_ID> -f <FOLDER_KEY> --output json                     # get incidents for a failed instance
+uip maestro flow instance variables <INSTANCE_ID> -f <FOLDER_KEY> --output json                     # get runtime variable values
+uip maestro flow instance variables <INSTANCE_ID> -f <FOLDER_KEY> --parent-element-id <ELEMENT_ID> --output json  # scope to a specific element
+uip maestro flow instance element-executions <INSTANCE_ID> -f <FOLDER_KEY> --output json            # get per-element execution details
+uip maestro flow instance asset <INSTANCE_ID> -f <FOLDER_KEY> --output json                         # get the deployed BPMN definition
+uip maestro flow instance cursors <INSTANCE_ID> -f <FOLDER_KEY> --output json                       # get current execution cursor positions
+```
+
+> **Lifecycle commands** (`pause` / `resume` / `cancel` / `retry`) are operate concerns — see the [Operate manage guide](../../operate/references/manage.md).
+
+### uip maestro flow incident
+
+Get incident details for failed flows. **Requires `uip login`.**
+
+```bash
+uip maestro flow incident summary --output json                                    # get incident summaries across all processes
+uip maestro flow incident get <INCIDENT_ID> --folder-key <FOLDER_KEY> --output json # get full details for a specific incident
+```
+
+Use `instance incidents <INSTANCE_ID>` to get incidents scoped to a specific run, then `incident get <INCIDENT_ID>` for full detail on a specific incident.

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

@@ -0,0 +1,132 @@
+# Evaluate — Design and run Flow evaluations
+
+Capability index for `uip maestro flow eval` — evaluator CRUD (7 types), eval set CRUD with entry-point pinning, data point management with file attachments, and Studio Web run start/status/results/list/compare. Local CRUD is offline; runs require `uip login` and a Flow solution that already exists in Studio Web.
+
+> **Where you came from / where to go next.** Evaluate is downstream of Operate (ship the flow → evaluate it on Studio Web) and feeds back into Author (failing eval → fix the `.flow` → re-ship → re-evaluate). Build/edit lives in [author/CAPABILITY.md](../author/CAPABILITY.md); publish/deploy lives in [operate/CAPABILITY.md](../operate/CAPABILITY.md); fault triage on a debug or process run 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, **plain-English narration + granular `TodoWrite` (opt-in — silent by default; engage when the user asks for verbosity)**. The rules below are evaluate-scoped and apply on top.
+
+## When to use this capability
+
+- Add or remove data points (test cases) on a Flow eval set
+- Create evaluators (`exact-match`, `json-similarity`, `contains`, `llm-judge-*` types) for a Flow project
+- Create or remove eval sets, link them to evaluators, pin entry points
+- Add, list, or remove simulations on data points (`uip maestro flow eval simulation`)
+- Start an eval run on Studio Web, poll its status, fetch detailed results
+- Compare two eval runs to verify a change improved scores without regressions
+
+For agent (`agent.json`) evaluations read the `uipath-agents` skill. For BPMN evaluations read the `uipath-maestro-bpmn` skill — this capability covers Flow only.
+
+## Critical rules
+
+1. **Check Flow eval CLI availability once.** Run `uip maestro flow eval --help --output json` before using eval commands. If it returns `unknown command 'eval'`, the installed CLI does not expose Flow eval yet. Stop, report that the user needs a CLI/tool version with Flow eval support, and do not spend turns searching npm packages or source bundles.
+2. **Never run `uip solution upload` automatically as part of an eval workflow.** The eval run requires the Flow solution to already exist in Studio Web, but uploading from the local working tree clobbers whatever is on Studio Web. If the project was pulled from Studio Web (`uip agent pull`), edited locally in VS Code, or scaffolded on disk and never uploaded, an unprompted upload will overwrite or push unintended state. Ask the user explicitly before any `uip solution upload` — see [upload-safety.md](references/upload-safety.md).
+3. **`--path` accepts a Flow project directory OR a solution directory containing exactly one Flow project.** If the solution holds multiple Flow projects, point `--path` at the specific project directory.
+4. **Local CRUD does not require login.** `add`, `remove`, `list` (data points / eval sets / evaluators) edit JSON on disk. Only `uip maestro flow eval run *` requires `uip login` and an existing Studio Web solution.
+5. **Pin a model on every LLM-judge evaluator.** Empty/missing `model` produces a cryptic 500 from the LLM gateway after retries. Pass `--model <name>` on `evaluator add` or set `model` in the JSON.
+6. **Declare input variables before adding data points with `--inputs`.** `eval add` validates input keys against the Flow's declared input variables and fails fast on unknown keys. Add missing input variables first (for example, `uip maestro flow variable add My.flow name --direction in --type string --output json`) or change the data point input JSON to match the Flow schema.
+7. **Let the CLI manage evaluator references.** Eval sets store `evaluatorRefs` as the evaluator file refs produced by `evaluator add` (for example, `greeting-match-1234abcd.json`). If the set should use every evaluator that already exists, omit `--evaluators` so the CLI writes those generated file refs. If you must pass `--evaluators`, pass the evaluator id or generated file base/ref from `evaluator add/list` — never the display name alone (`greeting-match`), because Studio Web does not resolve display-name refs.
+8. **Pre-empt timeouts on `run start --wait`.** The CLI blocks until the run reaches a terminal state or `--timeout` elapses. `--timeout` only stops local blocking — the run continues server-side; query progress with `eval run status <run_id>`.
+
+## Quick Start
+
+Standard workflow: scaffold evaluators → create eval set → add data points → confirm project is in Studio Web → run.
+
+```bash
+# 1. Add an evaluator (local; no login required)
+uip maestro flow eval evaluator add greeting-quality \
+  --type llm-judge-output \
+  --model gpt-4.1-2025-04-14 \
+  --path ./MySolution/MyFlow --output json
+
+# 2. Create an eval set, pin the entry point, and let the CLI attach
+#    all current evaluators by generated file ref
+uip maestro flow eval set add "Smoke Tests" \
+  --entry-point /Main.bpmn#start \
+  --path ./MySolution/MyFlow --output json
+
+# 3. Add data points (test cases)
+#    The `message` key must already be declared as a Flow input variable.
+uip maestro flow eval add hello-test \
+  --set "Smoke Tests" \
+  --inputs '{"message":"hello"}' \
+  --expected '{"reply":"Hello! How can I help you?"}' \
+  --path ./MySolution/MyFlow --output json
+
+# 4. Confirm the solution is in Studio Web
+#    DO NOT auto-run `uip solution upload`. Ask the user. See upload-safety.md.
+
+# 5. Start the run and wait
+uip maestro flow eval run start \
+  --set "Smoke Tests" \
+  --path ./MySolution/MyFlow \
+  --wait --timeout 600 --output json
+
+# 6. Inspect failures
+uip maestro flow eval run results <eval_set_run_id> \
+  --set "Smoke Tests" \
+  --only-failed --verbose \
+  --path ./MySolution/MyFlow --output json
+```
+
+## Workflow
+
+| Journey | Read |
+| --- | --- |
+| Look up any `uip maestro flow eval` subcommand syntax, flags, defaults, output codes | [commands-reference.md](references/commands-reference.md) |
+| Choose among the 7 evaluator types, write custom prompts, hand-write evaluator JSON | [evaluators-guide.md](references/evaluators-guide.md) |
+| Create eval sets, add data points, map `--inputs`/`--expected`/`--criteria` to evaluator types, attach files | [eval-sets-guide.md](references/eval-sets-guide.md) |
+| Start a Studio Web run, poll status, read results, export CSV/JSON, compare two runs | [running-guide.md](references/running-guide.md) |
+| Decide whether to call `uip solution upload` (almost always: don't auto-run; ask first) | [upload-safety.md](references/upload-safety.md) |
+
+## Common tasks
+
+| I need to... | Read these |
+| --- | --- |
+| **Add an evaluator** | [evaluators-guide.md](references/evaluators-guide.md) + [commands-reference.md — Evaluators](references/commands-reference.md#evaluators) |
+| **Pick the right evaluator type** | [evaluators-guide.md — When to Pick Each Type](references/evaluators-guide.md#when-to-pick-each-type) |
+| **Create an eval set and pin an entry point** | [eval-sets-guide.md — Eval Set Lifecycle](references/eval-sets-guide.md#eval-set-lifecycle) |
+| **Add a data point with file attachments** | [eval-sets-guide.md — `--input-file`](references/eval-sets-guide.md#--input-file-keypath) |
+| **Set per-data-point criteria for trajectory evaluators** | [eval-sets-guide.md — `--criteria`](references/eval-sets-guide.md#--criteria) |
+| **Add a simulation to a data point** | [eval-sets-guide.md — Simulations](references/eval-sets-guide.md#simulations-on-data-points) + [commands-reference.md — Simulations](references/commands-reference.md#simulations) |
+| **Start a Studio Web eval run** | [running-guide.md — Start a Run](references/running-guide.md#start-a-run) |
+| **Poll run status without `--wait`** | [running-guide.md — Check Status](references/running-guide.md#check-status) |
+| **Inspect only failed data points** | [running-guide.md — Detailed Results](references/running-guide.md#detailed-results) (`--only-failed --verbose`) |
+| **Compare two runs side-by-side** | [running-guide.md — Compare Two Runs](references/running-guide.md#compare-two-runs) |
+| **Decide whether to call `uip solution upload`** | [upload-safety.md](references/upload-safety.md) |
+| **Look up the `eval` subcommand tree, flags, defaults, output codes** | [commands-reference.md](references/commands-reference.md) |
+| **My eval run failed** | [running-guide.md — Failure Detection](references/running-guide.md#failure-detection); for flow-level faults [diagnose/CAPABILITY.md](../diagnose/CAPABILITY.md) |
+
+## Anti-patterns
+
+- **Don't auto-run `uip solution upload`.** Even when an eval run errors with "solution not found in Studio Web", stop and ask the user — see [upload-safety.md](references/upload-safety.md). The local project may be ahead of, or diverged from, Studio Web.
+- **Don't hand-write `evaluatorRefs` unless you are repairing an eval set.** Prefer the default all-evaluators behavior so the CLI writes generated file refs, or pass generated evaluator ids/file refs explicitly. Do not pass evaluator display names to `--evaluators`.
+- **Don't pass `--type` in PascalCase.** Only kebab-case is accepted: `exact-match`, `json-similarity`, `contains`, `llm-judge-output`, `llm-judge-strict-json`, `llm-judge-trajectory`, `llm-judge-trajectory-simulation`.
+- **Don't depend on a specific `--wait` polling cadence.** Treat `--wait` as a black-box block; if you need precise progress, omit it and call `eval run status` yourself.
+- **Don't compare runs from different eval sets.** `eval run compare` aligns by data-point name within the set; cross-set deltas are meaningless.
+- **Don't omit `--model` on LLM-judge evaluators.** The cloud worker fail-fasts before calling the LLM gateway.
+- **Don't run evals during `flow debug`.** `debug` is a separate Studio Web session; evals run against the deployed/published solution. Mixing them produces confusing run IDs.
+
+## Completion Output
+
+After a run completes, report:
+
+1. **Eval set run ID** and aggregate score (from `run status`)
+2. **Failed data points** (from `run results --only-failed --verbose`)
+3. **Comparison delta** vs the previous run (`run compare`) if one exists
+4. **Suggested next step** — fix the agent/flow, re-run, or accept the result. Do NOT suggest `uip solution upload` unless the user has explicitly asked to publish edits.
+
+## References
+
+### Evaluate-scoped
+
+- [commands-reference.md](references/commands-reference.md) — every `uip maestro flow eval` subcommand, flags, defaults, output `Code` enum
+- [evaluators-guide.md](references/evaluators-guide.md) — 7 evaluator types mapped to internal `uipath-*` IDs, JSON shapes, template variables
+- [eval-sets-guide.md](references/eval-sets-guide.md) — eval set + data point CRUD, `--inputs`/`--expected`/`--criteria`/`--input-file`/`--search-text`, simulations
+- [running-guide.md](references/running-guide.md) — run start/status/results/list/compare, JMESPath `--output-filter`, failure detection
+- [upload-safety.md](references/upload-safety.md) — the `solution upload` rule
+
+### Cross-capability (shared)
+
+- [shared/cli-commands.md](../shared/cli-commands.md) — flat CLI lookup including `eval` subcommands
+- [shared/cli-conventions.md](../shared/cli-conventions.md) — login states, `--output json`, JSON output shape