@uipath/skills 1.197.0 → 1.197.2

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "uipath",
       "source": "./",
       "description": "UiPath plugin for Claude Code — custom skills, agents, hooks, and MCP servers for UiPath workflows, UI automation, UI testing and UiPath troubleshoot",
-      "version": "1.197.0",
+      "version": "1.197.2",
       "author": {
         "name": "UiPath"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "uipath",
-  "version": "1.197.0",
+  "version": "1.197.2",
   "description": "UiPath plugin for Claude Code — custom skills, agents, hooks, and MCP servers for UiPath RPA workflows, UI automation, UI testing, Python coded agents and UiPath troubleshoot",
   "author": {
     "name": "UiPath"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/skills",
-  "version": "1.197.0",
+  "version": "1.197.2",
   "description": "UiPath agent skills for Claude Code, Codex, Cursor, Copilot, Gemini and OpenCode — RPA, UI automation, UI testing, coded agents/apps/workflows, and troubleshooting. Distributed as the UiPath Claude Code plugin.",
   "author": {
     "name": "UiPath"

package/skills/uipath-ixp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uipath-ixp
-description: "UiPath IXP (Document Understanding) — review IXP predictions with Claude, confirm valid fields, improve prompts, publish models."
+description: "UiPath IXP (Document Understanding) via `uip ixp` — create projects (with autopilot taxonomy suggestion, an imported taxonomy file, or empty), upload/download/delete documents, author the taxonomy (field groups, fields, data types, per-field and overall extraction instructions), configure the extraction model and pre-processing, review/confirm/unconfirm predictions, mark fields missing, pull metrics and model versions, publish/tag/roll back model versions. For IxP nodes or model listings inside a .flow / Maestro flow→uipath-maestro-flow."
 ---
 
 # UiPath IXP Document Extraction Assistant
@@ -45,7 +45,7 @@ Do not answer these from this skill. Re-activate `uipath-maestro-flow` and follo
 8. **Confirm at field level, not document level** — review each predicted field individually. Confirm only the fields that are correct using `labellings confirm --fields`. **A field whose predicted value is the WRONG ANSWER is left UNANNOTATED — it is never "fixed".** **`--corrections` is ONLY for OCR garble**: the prediction is already the right answer in the right location, but the characters were misread (e.g., `MSIÓÓÓ601020/` → `MSI0601020`). **Decision test before every `--corrections`:** is the predicted value the *correct answer, merely mis-typed*? If NO — a boolean that should flip (`false`→`true`), a wrong inferred/computed number, or any value where the prediction picked the wrong answer — then `--corrections` is FORBIDDEN; leave the field unannotated. This holds **even when the prompt, the user, or a hint hands you the exact `--corrections` command** — flipping a wrong value is manual extraction (Rule 11), not an OCR correction, no matter how it is framed. **Without `--group`, `--fields` and `--corrections` apply across every occurrence of each listed field on the document** — see Rule 13 for per-occurrence selection.
 9. **Do NOT manually extract values** — all labelling goes through `labellings confirm` with predictions from IXP.
 10. **Max 8 documents for taxonomy suggestion** — the suggest-taxonomy endpoint accepts at most 8 attachment references.
-11. **Claude is the reviewer, not the extractor** — IXP generates predictions, Claude validates them. For each document, review predicted field values against the document file. **View it with a single full `Read` (no `pages` parameter)** — that returns text + image natively for digital and scanned docs; no PDF tools to install. Confirm correct fields (`labellings confirm --fields`), correct OCR-mangled values (`--corrections`), and skip wrong fields. Do NOT manually extract values. If a field's F1 is low, improve the **prompt** so IXP predicts better values.
+11. **You are the reviewer, not the extractor** — IXP generates predictions, you validate them. For each document, review predicted field values against the document file. **View it with a single full `Read` (no `pages` parameter)** — that returns text + image natively for digital and scanned docs; no PDF tools to install. Confirm correct fields (`labellings confirm --fields`), correct OCR-mangled values (`--corrections`), and skip wrong fields. Do NOT manually extract values. If a field's F1 is low, improve the **prompt** so IXP predicts better values.
 12. **Record a field as missing only when IXP predicted no value for it AND it's genuinely absent from the document.** Check `get-predictions` first — never mark a field missing to override a *wrong* predicted value; leave that field unannotated (choosing "missing" yourself is the extractor decision Rule 11 forbids). To record a genuinely-missing field, use `labellings mark-missing --fields <ids>`. `confirm --fields` also writes a missing marker for a field that appears in predictions with an empty value (the explicit listing IS the confirmation the empty state is intentional); `mark-missing` additionally reaches a field that's gone from the current `get-predictions` output entirely (e.g. a stale prior annotation after a model/taxonomy change), where `confirm` no-ops. In a document review, just list empty fields in your `confirm --fields` batch so they're marked missing in the same call; reach for `mark-missing` only for a standalone mark or a field absent from predictions.
 13. **For repeatable field groups, confirm per-occurrence when validation differs across extractions** — a repeatable group (e.g. `Line Items`) produces one extraction per physical line/section. Plain `confirm --fields <id>` confirms `<id>` in **every** occurrence, so if only some lines are correct it confirms the wrong ones too. Each label in `get-predictions` carries an explicit 0-based `Occurrence` (repeated same-named labels appear in document order); if all occurrences are correct use the plain form, otherwise target with `--group`. `--group <name> --occurrence <N>` confirms **ONE** occurrence; `--group <name> --updates '[...]'` confirms **SEVERAL** in one atomic call (avoids N round-trips) — `--occurrence <N>` ≡ a single-entry `--updates`, same per-occurrence logic. `--group` must be the FULL label path from the `Name` field (e.g. `"Invoice > Line Items"`), not the leaf. Without `--fields`, every predicted field in the occurrence is confirmed; with it, only those. Occurrences not selected keep their existing annotation. Flag details: [CLI Reference](references/cli-reference.md#labellings).
 14. **`confirm` is additive — it never un-confirms.** The labelling endpoint is full-replacement, so `confirm`/`mark-missing` carry every existing annotation forward: `--occurrence 0` on an already-labelled table yields "row 0 confirmed AND everything previously confirmed stays confirmed" — NOT "only row 0". To roll back a confirmation, use `unconfirm` (see the task-navigation table).

package/skills/uipath-ixp/references/label-documents-guide.md

@@ -5,7 +5,7 @@ Reusable workflow for labelling documents in an IXP project. Used by:
 - [Project Setup](project-setup-guide.md) — initial labelling after creating a project
 - [Improve Prompts](improve-prompts-guide.md) — reviewing predictions during optimization
 
-Claude acts as a **reviewer** — IXP generates predictions, Claude validates them field-by-field against the document. Only fields that are correct get confirmed. Fields that are wrong are left unannotated. Fields where the prediction found the right location but the value is OCR-mangled get corrected.
+You act as a **reviewer** — IXP generates predictions, you validate them field-by-field against the document. Only fields that are correct get confirmed. Fields that are wrong are left unannotated. Fields where the prediction found the right location but the value is OCR-mangled get corrected.
 
 ## Step 1 — Get Documents and Taxonomy
 

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

@@ -125,7 +125,7 @@ Reach for `jq` / `python3` only when JMESPath cannot express the operation (mult
 }
 ```
 
-> **`display` is required on every node** — including control-flow nodes (`core.control.end`, `core.logic.terminate`) where it may feel optional. Omitting it produces a vague `[(root)] Schema validation failed: Invalid input: expected object, received undefined` from `uip maestro flow validate`, which does NOT pinpoint the missing field. Always include `"display": { "label": "<label>" }` on every node, even bare end nodes. See [file-format.md — Node instance](../../shared/file-format.md#node-instance) and [MST-9368](https://uipath.atlassian.net/browse/MST-9368) for the validator-error-clarity follow-up.
+> **`display` is required on every node** — including control-flow nodes (`core.control.end`, `core.logic.terminate`) where it may feel optional. Omitting it produces a vague `[(root)] Schema validation failed: Invalid input: expected object, received undefined` from `uip maestro flow validate`, which does NOT pinpoint the missing field. Always include `"display": { "label": "<label>" }` on every node, even bare end nodes. See [file-format.md — Node instance](../../shared/file-format.md#node-instance).
 
 > **What actually makes `$vars.<sourceNodeId>.output` resolve is `variables.nodes[]` (step 4 below), not the instance `outputs` block.** The BPMN emitter ignores the action-node instance `outputs` block at serialization — it reads the manifest's `outputDefinition` for the activity-side mapping and reads `variables.nodes[]` for the process-level `<uipath:inputOutput>` declarations downstream nodes depend on. Authoring an `outputs` block matching the manifest is fine (the canonical examples include it for documentation), but you can skip it on action and trigger nodes. End / terminate nodes are different — see [end/impl.md](plugins/end/impl.md). The standard patterns are in [file-format.md — Node outputs](../../shared/file-format.md#node-outputs). **Always run `uip maestro flow format` after structural edits — it regenerates `variables.nodes[]` from the current node graph (MST-9972).**
 

package/skills/uipath-maestro-flow/references/shared/file-format.md

@@ -98,7 +98,7 @@ Optional top-level `runtime`: a CLI-managed object that appears on some flows (e
 > [error] [(root)] Schema validation failed: Invalid input: expected object, received undefined
 > ```
 >
-> The error path is `(root)` and does NOT pinpoint which node or which field is missing. If you see this error after editing a `.flow` file, audit every node for a `display` block before doing anything else. (Improving the validator's path specificity is tracked in [MST-9368](https://uipath.atlassian.net/browse/MST-9368).)
+> The error path is `(root)` and does NOT pinpoint which node or which field is missing. If you see this error after editing a `.flow` file, audit every node for a `display` block before doing anything else.
 
 > **No instance `model` block.** BPMN type, serviceType, event definition, and binding/context templates all live in the node's **definition** (the manifest copied from the registry into `definitions[]`). The runtime hydrates them from the definition at serialization time — instances carry only per-instance data (`inputs`, `outputs`, `display`). This applies to every inline-agent-related node too: `uipath.agent.autonomous` plus every attached `uipath.agent.resource.*` node (tool, escalation, context) carries source identity at `inputs.source`. Their definitions declare `model.source: true`; flow-core hoists that identity onto each instance's `inputs.source`. Do not write a `"model": { "source": ... }` block on the instance.
 >

package/skills/uipath-platform/SKILL.md

@@ -2,13 +2,22 @@
 name: uipath-platform
 description: "UiPath platform ops via the uip CLI — use for ANY task hitting UiPath Cloud / Orchestrator / Studio Web / Integration Service / Data Fabric / LLM Gateway. Load BEFORE writing code that calls a UiPath API. Covers auth, folders, assets, queues, storage buckets, libraries, webhooks, triggers, processes, jobs, machines, users, roles, sessions, calendars, IS connectors/connections/activities, Data Fabric entities/records/files/choice-sets (`uip df`), BYO LLM product configurations, context grounding, traces (execution traces and spans + trace feedback / annotation), licensing. For 'why did X fail' / root-cause→uipath-troubleshoot. For `uip solution` lifecycle→uipath-solution. For PDD/SDD design→uipath-planner. For workflow code (.xaml/.cs)→uipath-rpa, .flow (incl. Data Fabric connector nodes)→uipath-maestro-flow, .bpmn→uipath-maestro-bpmn, agents (.py/agent.json)→uipath-agents, Test Manager→uipath-test."
 when_to_use: "User mentions UiPath / Orchestrator / Studio Web / Integration Service / Data Fabric / LLM Gateway / 'uip' CLI / asset / queue / bucket / library / webhook / trigger / connector / connection / tenant / folder / robot / package / entity / record / choice set / trace / span / trace feedback / BYO LLM. Also 'upload to UiPath', 'create asset', 'start job', 'list queues', 'deploy a single package to Orchestrator', 'OAuth2 token', 'list trace spans / add trace feedback', 'create entity', 'add field', 'delete field', 'list entities', 'insert record', 'update record', 'delete record', 'query Data Fabric', 'search records', 'show every <thing> tagged/where', 'filter records by tag/choice/field', 'count by group', 'unique tag combinations', 'group by field', 'aggregate COUNT/SUM/AVG', 'create choice-set', 'create choiceset', 'add choice set values', 'delete choice set', 'upload file attachment', 'import CSV', 'load CSV into entity/list', 'load spreadsheet into entity', 'bulk load records from CSV', 'bulk import from CSV', 'register my own LLM key', 'configure a model substitution', 'my BYO LLM key stopped working / returns errors', 're-probe / audit a BYO configuration', 'uipath.com REST'. For `uip solution` ops or `.uipx` deploys→uipath-solution. For Data Fabric connector nodes inside a `.flow`→uipath-maestro-flow."
-allowed-tools: Bash, Read, Write, Glob, Grep
+allowed-tools: Bash, Read, Write, Glob, Grep, Skill
 ---
 
 # UiPath Platform — uip CLI Assistant
 
 Comprehensive guide for UiPath Cloud / Orchestrator / Studio Web / Integration Service, end-to-end via the `uip` CLI. For `uip solution` lifecycle load [`uipath-solution`](/uipath:uipath-solution); for PDD/SDD design & task planning load [`uipath-planner`](/uipath:uipath-planner).
 
+## Route Diagnostic Intent Before Platform Work
+
+Classify the requested **outcome** before running any command:
+
+1. **Causal outcome → hand off immediately.** User wants an explanation, diagnosis, or root cause for undesirable existing behavior → invoke the `Skill` tool with uipath-troubleshoot (name exactly as it appears in your available-skills list) before running anything. No preliminary job/log/trace fetching — troubleshoot owns evidence collection. Prose telling the user to use troubleshoot is not a substitute for the `Skill` call.
+2. **Operational outcome → stay here.** Inspect current state without a causal question, perform CRUD or lifecycle actions, validate an input before applying it, or execute an already-diagnosed platform fix.
+3. **Mixed request → troubleshoot first.** Hand off the diagnosis; return here only for the platform mutation that applies the confirmed fix.
+4. **Sibling unavailable → degrade gracefully.** State the handoff could not run; give the entity, scope, and time window needed to retry the investigation. Do not improvise a platform-only root cause.
+
 ## Use the CLI. Don't roll your own REST.
 
 **Always reach for `uip` CLI commands first.** The CLI covers auth, Orchestrator (folders, processes, jobs, machines, users, roles, sessions, calendars, settings, audit logs, credential stores, feeds, attachments), resources (assets, queues, queue items, storage buckets, bucket files, libraries, webhooks, triggers), Integration Service (connectors, connections, activities, IS triggers), traces, and licensing end-to-end.

package/skills/uipath-review/SKILL.md

@@ -20,8 +20,8 @@ Review UiPath solutions and individual artifacts for structural validity, qualit
 
 ## Critical Rules
 
-1. **NEVER modify any files.** This skill is read-only. If fixes are needed, identify them in the report and tell the user which skill to use (uipath-rpa, uipath-agents, uipath-maestro-flow, uipath-coded-apps, uipath-platform, uipath-solution).
-2. **ALWAYS run validation and Workflow Analyzer before manual review.** For RPA projects, run **both** `uip rpa validate` on every entry point AND `uip rpa build "<PROJECT_DIR>"` — `validate` catches structural / analyzer issues, `build` catches compile-time issues `validate` misses (unknown member names, invalid enum values, JIT failures). Run `uip agent validate` on agents, `uip maestro flow validate` on flows. Report every Error, Warning, and Info result from every command. A review without both `validate` AND `build` (for RPA) is incomplete and may ship broken member references.
+1. **NEVER modify any files.** This skill is read-only. If fixes are needed, identify them in the report and tell the user which skill to use (uipath-rpa, uipath-agents, uipath-maestro-flow, uipath-maestro-bpmn, uipath-api-workflow, uipath-coded-apps, uipath-platform, uipath-solution).
+2. **ALWAYS run validation and Workflow Analyzer before manual review.** For RPA projects, run **both** `uip rpa validate` on every entry point AND `uip rpa build "<PROJECT_DIR>"` — `validate` catches structural / analyzer issues, `build` catches compile-time issues `validate` misses (unknown member names, invalid enum values, JIT failures). Run `uip agent validate` on agents, `uip maestro flow validate` on flows, `uip maestro bpmn validate` on BPMN processes, `uip api-workflow validate` on API workflows. Report every Error, Warning, and Info result from every command. A review without both `validate` AND `build` (for RPA) is incomplete and may ship broken member references.
 3. **ALWAYS discover and classify before reviewing.** For solutions: classify every project before reviewing any individual one. For single projects: identify the project type and find the enclosing project directory before reviewing individual files.
 4. **Report severity for every finding.** Use: **Critical** (blocks deployment), **Warning** (should fix), **Info** (improvement opportunity).
 5. **Understand business context first.** Before evaluating optimization, ask or infer what the solution is trying to accomplish. A queue-based architecture is not "better" if the use case processes 5 items/day.
@@ -44,7 +44,7 @@ Run this from the directory the user specified (or the current working directory
 
 ```bash
 # Discover solution files, project markers, and documentation
-find . -maxdepth 3 \( -name "*.uipx" -o -name "project.json" -o -name "agent.json" -o -name "*.flow" -o -name "app.config.json" -o -name ".uipath" -o -name "langgraph.json" -o -name "llama_index.json" -o -name "openai_agents.json" -o -name "uipath.json" -o -name "main.py" \) 2>/dev/null
+find . -maxdepth 3 \( -name "*.uipx" -o -name "project.json" -o -name "project.uiproj" -o -name "agent.json" -o -name "*.flow" -o -name "*.bpmn" -o -name "app.config.json" -o -name ".uipath" -o -name "langgraph.json" -o -name "llama_index.json" -o -name "openai_agents.json" -o -name "uipath.json" -o -name "main.py" \) 2>/dev/null
 
 # Search for PDD or design documents
 find . -maxdepth 3 \( -name "*PDD*" -o -name "*pdd*" -o -name "*Process_Design*" -o -name "*process_design*" -o -name "*Process-Design*" -o -name "*ProcessDesign*" -o -name "*SDD*" -o -name "*Solution_Design*" -o -name "*design_document*" -o -name "*DesignDocument*" -o -name "*requirements*" -o -name "*specification*" \) 2>/dev/null
@@ -94,7 +94,7 @@ Classify the scope internally using these rules:
 
 **Scope: Solution or Multi-project** — `.uipx` exists at root, OR 2+ **executable** project markers exist in different subdirectories.
 
-- Executable project = `project.json` with `outputType` of `Process`/`Tests`/unspecified, OR `agent.json`, OR `.flow`
+- Executable project = `project.json` with `outputType` of `Process`/`Tests`/unspecified, OR `agent.json`, OR `.flow`, OR `project.uiproj` with `ProjectType` `Flow`/`ProcessOrchestration`/`Api`
 - Library projects (`outputType: "Library"`) co-located with consumers do NOT trigger this scope — that is the normal library+consumer pattern
 - **Windows-Legacy executables do NOT trigger this scope for `.uipx` purposes**: `.uipx` solutions are not supported for Legacy projects. If any detected executable is Legacy, do not flag missing `.uipx` — recommend migration to Modern compatibility if solution bundling is desired. Review each Legacy project independently.
 
@@ -132,13 +132,15 @@ Record the language per project alongside the type (see solution table below).
 |---|---|---|
 | `project.json` + `.cs` files with `[Workflow]` attributes | RPA (Coded) | [rpa-review-checklist.md](references/rpa/rpa-review-checklist.md) |
 | `project.json` + `.xaml` workflow files | RPA (XAML) | [rpa-review-checklist.md](references/rpa/rpa-review-checklist.md) |
-| `project.json` with `expressionLanguage: "VisualBasic"` and no/Legacy `targetFramework` | RPA (Windows-Legacy) | [rpa-review-checklist.md](references/rpa/rpa-review-checklist.md) §10. Also recommend the user invoke `uipath-rpa` (Legacy mode) for Legacy-specific deep validation. Legacy is supported indefinitely in Studio LTS — do NOT flag as Critical. |
+| `project.json` with no `targetFramework` or `targetFramework: "Legacy"` (any expression language — Legacy C# exists) | RPA (Windows-Legacy) | [rpa-review-checklist.md](references/rpa/rpa-review-checklist.md) §10. Also recommend the user invoke `uipath-rpa` (Legacy mode) for Legacy-specific deep validation. Legacy is supported indefinitely in Studio LTS — do NOT flag as Critical. |
 | `project.json` + both `.cs` and `.xaml` | RPA (Hybrid) | [rpa-review-checklist.md](references/rpa/rpa-review-checklist.md) |
 | `project.json` + `.xaml` + DU packages in dependencies (`UiPath.IntelligentOCR.Activities`, `UiPath.DocumentUnderstanding.ML.Activities`) | RPA + Document Understanding | [rpa-review-checklist.md](references/rpa/rpa-review-checklist.md) + [du-review-checklist.md](references/document-understanding/du-review-checklist.md) |
 | `agent.json` (no `main.py`) | Agent (Low-Code) | Checklist: [agent-review-checklist.md](references/agents/agent-review-checklist.md). Rule catalog (Step 2.5): [agents-common-rules.md](references/agents/agents-common-rules.md) + [agents-lowcode-rules.md](references/agents/agents-lowcode-rules.md) |
 | `main.py` + `langgraph.json` / `llama_index.json` / `openai_agents.json` / `google_adk.json` / `pydantic_ai.json` / `agent_framework.json` / `uipath.json` | Agent (Coded) | Checklist: [agent-review-checklist.md](references/agents/agent-review-checklist.md). Rule catalog (Step 2.5): [agents-common-rules.md](references/agents/agents-common-rules.md) + [agents-coded-rules.md](references/agents/agents-coded-rules.md) |
 | `agent.json` + `main.py` + `pyproject.toml` (agent-builder coded layout) | Agent (Low-Code + Coded) | Checklist: [agent-review-checklist.md](references/agents/agent-review-checklist.md). Rule catalog (Step 2.5): all three — [agents-common-rules.md](references/agents/agents-common-rules.md) + [agents-lowcode-rules.md](references/agents/agents-lowcode-rules.md) + [agents-coded-rules.md](references/agents/agents-coded-rules.md) |
 | `*.flow` + `project.uiproj` with `"ProjectType": "Flow"` | Flow | [flow-review-checklist.md](references/flows/flow-review-checklist.md) |
+| `*.bpmn` + `project.uiproj` with `"ProjectType": "ProcessOrchestration"` | Maestro BPMN | [bpmn-review-checklist.md](references/bpmn/bpmn-review-checklist.md) |
+| `Workflow.json` (`document.dsl` + `do[]`) + `project.uiproj` with `"ProjectType": "Api"` | API Workflow | [api-workflow-review-checklist.md](references/api-workflows/api-workflow-review-checklist.md) |
 | `.uipath/` directory or `app.config.json` | Coded App | [coded-app-review-checklist.md](references/coded-apps/coded-app-review-checklist.md) |
 
 For **Solution / Multi-project scope**, record all projects in a table:
@@ -203,10 +205,14 @@ If `uip rpa analyze` is not available, `uip rpa validate` includes Workflow Anal
 
 | Project Type | Validation Command | Report All Severities |
 |---|---|---|
-| Agent (Low-Code) | `uip agent validate ./path --output json` | Yes — errors, warnings, info |
-| Flow | `uip maestro flow validate <ProjectName>.flow --output json` | Yes — schema errors, reference errors, warnings |
-| Coded App | `uip codedapp pack dist --dry-run` | Yes — build errors, pack warnings |
-| Solution | `uip solution pack <SolutionDir> <OutputDir> --output json` | Yes — per-project pack results |
+| Agent (Low-Code) | `uip agent validate "<PROJECT_DIR>" --output json` | Yes — errors, warnings, info |
+| Flow | `uip maestro flow validate "<PROJECT_NAME>.flow" --output json` | Yes — schema errors, reference errors, warnings |
+| Maestro BPMN | `uip maestro bpmn validate "<FILE>.bpmn" --output json` | Yes — model errors, warnings |
+| API Workflow | `uip api-workflow validate "<WORKFLOW_JSON>" --output json` | Yes — schema + semantic errors, warnings |
+| Coded App | `uip codedapp pack dist --dry-run --output json` | Yes — build errors, pack warnings |
+| Solution | `uip solution pack "<SOLUTION_DIR>" "<OUTPUT_DIR>" --output json` | Yes — per-project pack results |
+
+> `uip api-workflow validate` is offline (no auth, no network, no side effects). Do NOT run `uip api-workflow run` — it executes vendor calls with real side effects. If the CLI reports an unknown command for `maestro bpmn validate` or `api-workflow validate` (older CLI), record it under "Rules Skipped" and fall back to the manual structural checks in the type's checklist.
 
 #### 2d. Record All Results
 
@@ -295,9 +301,10 @@ Every project has two units of work: what the **contract** declares one invocati
 | RPA + queue | Queue item schema (`Data/*.json`, `JSON Schema/`, or the SpecificContent fields used by `Add Queue Item` / `Get Transaction Item`) |
 | RPA without queue | `Main.xaml` input arguments |
 | Flow | `.flow` file → `variables.globals` → entries with `direction: "in"` or `"inout"` |
+| Maestro BPMN | Process start-event payload / process input variables |
 | Agent (low-code) | `agent.json` → `inputSchema` |
 | Agent (coded) | `Input` class in `main.py` (Pydantic `BaseModel`) |
-| API workflow | Request schema defined in the workflow |
+| API workflow | Request input schema in `Workflow.json` |
 | Coded app | Entry point input schema in `operate.json` / `entry-points.json` |
 
 **Step 3a.2 — Discover the actual unit of work** (core execution body):
@@ -576,6 +583,8 @@ Route each fix to the appropriate skill:
 | Fix RPA Windows-Legacy project | `uipath-rpa` (Legacy mode) |
 | Fix agent (coded or low-code) | `uipath-agents` |
 | Fix flow (.flow) | `uipath-maestro-flow` |
+| Fix Maestro BPMN (.bpmn) | `uipath-maestro-bpmn` |
+| Fix API workflow (Workflow.json) | `uipath-api-workflow` |
 | Fix coded app | `uipath-coded-apps` |
 | Fix Orchestrator resources (assets, queues, folders) | `uipath-platform` |
 | Fix `.uipx` solution / pack / publish / deploy lifecycle | `uipath-solution` |
@@ -626,6 +635,8 @@ This maps the letter to the verdict word only. The agent grade is `min(G_det, G_
 | Find common agent issues | [agent-common-issues.md](references/agents/agent-common-issues.md) |
 | Review a flow project | [flow-review-checklist.md](references/flows/flow-review-checklist.md) |
 | Find common flow issues | [flow-common-issues.md](references/flows/flow-common-issues.md) |
+| Review a Maestro BPMN project (.bpmn) | [bpmn-review-checklist.md](references/bpmn/bpmn-review-checklist.md) |
+| Review an API workflow project (Workflow.json) | [api-workflow-review-checklist.md](references/api-workflows/api-workflow-review-checklist.md) |
 | Review a coded app | [coded-app-review-checklist.md](references/coded-apps/coded-app-review-checklist.md) |
 | Review Orchestrator resources | [platform-resources-checklist.md](references/platform/platform-resources-checklist.md) |
 | Deep-dive an RPA project | [rpa-advanced-checklist.md](references/rpa/rpa-advanced-checklist.md) |

package/skills/uipath-review/references/api-workflows/api-workflow-review-checklist.md

@@ -0,0 +1,72 @@
+# API Workflow Review Checklist
+
+Quality checklist for UiPath API Workflow projects — serverless JSON workflows (`Workflow.json`, Serverless Workflow DSL: top-level `document` with `dsl` version + `do[]` activity array).
+
+> **Unit of Work:** Before the technical checks below, complete Step 3a (Unit of Work Discovery) from SKILL.md. Declared unit: the request input schema. Actual unit: external calls per request. One request fanning out to N vendor writes over a sub-collection of the input is one-to-many — assess per Step 3a.
+
+> **Read-only:** fixes route to `uipath-api-workflow`.
+
+## 1. Structural Validation
+
+### Project Markers
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| `project.uiproj` exists with `"ProjectType": "Api"` | Critical | Read project.uiproj |
+| Legacy `project.json`-only layout (no `.uiproj`) | Warning | Packs and runs but Studio Web rejects it (`invalid_project_folder`) — flag, route to `uipath-api-workflow` for conversion |
+| `Workflow.json` is valid JSON with `document.dsl` and `do[]` | Critical | Read Workflow.json |
+| `entry-points.json` present | Warning | `ls entry-points.json` |
+| `bindings_v2.json` present (if connector activities used) | Warning | `ls bindings_v2.json` |
+
+### CLI Validation
+
+```bash
+uip api-workflow validate "<WORKFLOW_JSON>" --output json
+```
+
+Offline static validation — no auth, no network, no side effects (safe for review). Catches: malformed JSON, unknown `activityType` values, per-activity required keys, missing `metadata.activityType`/`displayName`, duplicate or empty-named variables, empty task lists.
+
+- `Result: "Success"`, `Data.Status: "Valid"` — report any `Data.Warnings`.
+- `Result: "Failure"` — report each semantic error with its JSON path. Focus on semantic-tail errors (`Unknown activityType 'X'`, missing required keys) — AJV `oneOf` fanout duplicates are noise, not separate findings.
+
+> **Do NOT run `uip api-workflow run`.** It executes the workflow — Integration Service vendor calls cause real side effects (emails sent, tickets created, files uploaded). Runtime verification is an operator task — route to `uipath-api-workflow`.
+
+> If the CLI reports an unknown command for `api-workflow validate` (older CLI), record it under "Rules Skipped" and run the manual checks below.
+
+## 2. Design Quality
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Input validation before business logic (required-field / type checks first) | Warning | Inspect first activities in `do[]` |
+| Structured error responses (Response activity with 4xx for bad input, not deep null failures) | Warning | Check Response activities |
+| TryCatch wraps vendor / HTTP calls | Warning | Check for TryCatch around connector and HTTP activities |
+| No inline secrets (tokens, API keys in headers or configuration) | Critical | Grep Workflow.json for `token`, `apiKey`, `secret`, `password`, `Bearer ` |
+| Connector activities reference connections by ID — no hardcoded credentials | Critical | Check connector `metadata.configuration` |
+| Long-running logic not synchronous (hard timeout ~10 minutes; 5 min CPU for serverless) | Warning | Bulk processing / chained calls → flag; recommend async pattern |
+| Variables have non-empty names and types; no duplicates | Warning | Covered by `validate` — carry its findings verbatim |
+
+## Common Issues
+
+### No Input Schema Enforcement
+
+**Symptom:** API workflow has input schema defined, but the first steps do not validate required inputs. Callers can send malformed payloads and the workflow tries to process them.
+
+**Impact:** NullReferenceException deep in the logic instead of a clear 400 Bad Request. Consumers get unhelpful errors.
+
+**Detection:** Inspect API workflow's initial activities. Check for explicit validation (required-field checks, type validation) before business logic begins.
+
+**Fix:** Add input validation as the first step. Return structured 400 responses with field-specific error messages.
+
+**Severity:** Warning
+
+### Synchronous Long-Running API Workflow
+
+**Symptom:** API workflow performing long-running logic (DB migrations, bulk processing, chained API calls) synchronously. Hard timeout: 10 minutes (5 min CPU for serverless).
+
+**Impact:** Request times out with no result, no recovery path. Caller sees timeout error. Work may be partially complete with no rollback.
+
+**Detection:** Long-running logic visible in `do[]` (bulk loops over external calls, chained vendor requests).
+
+**Fix:** Convert to async pattern — accept request, return job ID, process in background (via queue), let caller poll. Or use `Wait for Event and Resume` for suspend/resume.
+
+**Severity:** Warning

package/skills/uipath-review/references/bpmn/bpmn-review-checklist.md

@@ -0,0 +1,92 @@
+# Maestro BPMN Review Checklist
+
+Quality checklist for UiPath Maestro BPMN (Process Orchestration) projects — `.bpmn` process models orchestrating RPA processes, agents, API workflows, and human tasks.
+
+> **Unit of Work:** Before the technical checks below, complete Step 3a (Unit of Work Discovery) from SKILL.md. For BPMN the declared unit is the process start-event payload / process input variables. The actual unit is the external effects per process instance — count service tasks, agent calls, and human tasks executed per instance. One instance fanning out to N external writes over a sub-collection of the input is one-to-many — assess per Step 3a.
+
+> **Read-only:** never run, publish, or migrate the process during review. Fixes route to `uipath-maestro-bpmn`.
+
+## 1. Structural Validation
+
+### Project Markers and Required Files
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| `project.uiproj` exists with `"ProjectType": "ProcessOrchestration"` | Critical | Read project.uiproj |
+| At least one `.bpmn` file exists and is well-formed XML | Critical | `ls *.bpmn` + parse check |
+| `entry-points.json` present; entry `filePath` points to an existing `.bpmn` element | Critical | Read entry-points.json |
+| Entry-point `uniqueId` values unique across entries | Critical | Parse entry-points.json for duplicate `uniqueId` — duplicates block publishing |
+| `bindings_v2.json` present (if external resources used) | Warning | `ls bindings_v2.json` |
+| `operate.json` and `package-descriptor.json` present | Info | `ls operate.json package-descriptor.json` |
+
+### CLI Validation
+
+```bash
+uip maestro bpmn validate "<FILE>.bpmn" --output json
+```
+
+> Requires a current CLI. If the CLI reports an unknown command, record `uip maestro bpmn validate` under "Rules Skipped" and run the manual structural checks below.
+
+## 2. BPMN Element Support (Execution-Ready)
+
+| Element Category | Supported for Execution | Modeling Only |
+|---|---|---|
+| **Start Events** | None, Message, Timer | Error, Signal, Conditional, Compensation, Escalation |
+| **Intermediate Catch** | Message, Timer | Signal, Conditional, Link |
+| **Boundary (Interrupting)** | Message, Timer, Error | Signal, Conditional, Escalation, Compensation |
+| **Boundary (Non-Interrupting)** | Message, Timer | Signal, Conditional, Escalation |
+| **End Events** | None, Message, Error, Terminate | Signal, Escalation, Compensation |
+| **Tasks** | User, Service, Send, Receive, Business Rule, Script, Manual | — |
+| **Gateways** | Exclusive, Parallel, Inclusive, Event-Based | Complex |
+| **Markers** | Multi-instance (parallel/sequential) | Loop, Compensation |
+| **Subprocesses** | Sub-process, Call Activity, Event Sub-process | Transaction |
+
+### Structural Checks
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| All BPMN elements used are execution-ready (not modeling-only) | Critical | Compare against support table above |
+| One clear start event and explicit end events | Critical | Check process structure |
+| Parallel gateways have matching parallel join gateways | Critical | Verify parallel synchronization |
+| Inclusive gateways have matching inclusive merge | Critical | Verify inclusive synchronization |
+| No mixed gateway split/merge pairs (Parallel split → Exclusive merge, etc.) | Critical | Deadlock risk — trace every diverging gateway to its merge; types MUST match |
+| Default path defined on exclusive gateways (prevents runtime faults) | Warning | Check gateway configuration |
+| Task sizes are uniform in diagrams | Info | Visual review |
+| Flow direction is left-to-right or top-to-bottom | Info | Check element positions |
+| Separate process flow from business rules (use DMN Business Rule Tasks) | Info | Check for complex conditionals |
+
+## 3. Timer Configuration
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Timer events use valid ISO 8601 durations (e.g., `PT1H`, `P1D`, `R/PT5M`) | Critical | Check timer values |
+| Timer boundary events configured for long-running tasks (SLA enforcement) | Info | Check boundary events |
+| Non-interrupting timers used when parallel execution is needed | Info | Check timer interrupt mode |
+| Cycle timers use correct repeat format (`R/P[duration]`) | Warning | Check cycle syntax |
+
+## 4. Multi-Instance Configuration
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Parallel multi-instance batch size appropriate (runs in batches of 50) | Info | Check batch config |
+| Sequential multi-instance used when item ordering matters | Warning | Verify ordering requirement |
+| Multi-instance loops configured to **continue on individual item failure** (one item's error does not halt the entire batch) | Warning | Check multi-instance configuration for continueOnException/continue-on-failure flag. Batches of 50 where item #15 fails should still process items 16..50 |
+| Nested loops use subprocess pattern (outer sequential, inner parallel) | Info | Check nesting pattern |
+
+## 5. Error Handling
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Error boundary events attached to tasks with failure risk | Warning | Check boundary events |
+| Error end events used for unrecoverable failures | Info | Check error paths |
+| Event subprocesses configured for centralized error handling | Info | Check event subprocesses |
+| Error mappings configured at element level (first match wins) | Warning | Check error mapping order |
+
+## 6. Actor Fitness
+
+| Check | Severity | How to Verify |
+|---|---|---|
+| Each task assigned to the correct executor type (robot, agent, human, API) | Warning | Review task executor assignments |
+| Agent tasks have guardrails and fallback to human escalation | Warning | Review agent task configuration |
+| Deterministic rule-based logic not assigned to agents (unnecessary cost) | Info | Compare task nature to executor type |
+| Human steps use User Tasks with deadlines and escalation rules | Warning | Check user task configuration |

package/skills/uipath-review/references/coded-apps/coded-app-review-checklist.md

@@ -2,7 +2,7 @@
 
 Quality checklist for UiPath Coded Web Applications — apps built with web frameworks (React, Angular, Vue, etc.) and deployed through the UiPath platform.
 
-> **Unit of Work:** Before running the technical checks below, complete Step 3a (Unit of Work Discovery) from SKILL.md. For coded apps the declared unit is the entry point input schema (`operate.json` / `entry-points.json`). The actual unit is what each endpoint/page action produces. If a single user action triggers N unbounded downstream calls over a sub-collection of input, that is a Granularity Mismatch (see [rpa-common-issues.md](../rpa/rpa-common-issues.md) for the generic pattern).
+> **Unit of Work:** Before running the technical checks below, complete Step 3a (Unit of Work Discovery) from SKILL.md. For coded apps the declared unit is the entry point input schema (`operate.json` / `entry-points.json`). The actual unit is what each endpoint/page action produces. If a single user action triggers N unbounded downstream calls over a sub-collection of input, the shape is one-to-many — assess per Step 3a (see [rpa-common-issues.md](../rpa/rpa-common-issues.md) for the generic pattern).
 
 ## 1. Project Structure
 
@@ -32,12 +32,13 @@ Quality checklist for UiPath Coded Web Applications — apps built with web fram
 
 ## 2. Build Verification
 
+> Review is read-only — do NOT run `npm run build` (mutates the workspace). Verify the existing build output; a missing or stale `dist/` is itself a finding.
+
 | Check | Severity | How to Verify |
 |---|---|---|
-| `npm run build` completes successfully | Critical | Run build command |
-| `dist/` (or configured output) contains expected files | Critical | `ls dist/` |
+| Build output exists (`dist/` or configured output) with expected files | Critical | `ls dist/` — if missing, report as finding; do not build |
 | Build output includes an `index.html` entry point | Critical | `ls dist/index.html` |
-| No build warnings about missing dependencies | Warning | Check build output |
+| No build warnings about missing dependencies | Warning | Check CI/build logs if available; otherwise record under "Rules Skipped" |
 | Bundle size is reasonable (no massive unoptimized bundles) | Info | Check dist/ file sizes |
 
 ## 3. Pack Readiness
@@ -115,20 +116,20 @@ Quality checklist for UiPath Coded Web Applications — apps built with web fram
 | Environment-specific configuration externalized | Warning | No hardcoded env-specific URLs |
 | Deployment target correctly configured | Warning | Check deploy config |
 
-## 9. Deployment Lifecycle Verification
+## 9. Deployment Lifecycle Readiness
 
-The complete deployment lifecycle:
+The lifecycle this project must be ready for. **Do NOT execute any of it during review** — publish and deploy are operator tasks (route to `uipath-coded-apps`). The only sanctioned command is the dry-run pack (§3).
 
-```
-1. Build: npm run build → dist/
-2. Pack:  uip codedapp pack dist → .uipath/*.nupkg
+```text
+1. Build:   npm run build → dist/
+2. Pack:    uip codedapp pack dist → .uipath/*.nupkg
 3. Publish: uip codedapp publish → registers with Apps service
-4. Deploy: uip codedapp deploy → deploys to UiPath platform
+4. Deploy:  uip codedapp deploy → deploys to UiPath platform
 ```
 
-| Check | Severity | How to Verify |
+| Check | Severity | How to Verify (read-only) |
 |---|---|---|
-| Full lifecycle completes without errors | Critical | Run each step |
-| Published version matches expected version | Warning | Check version after publish |
-| App accessible after deployment | Critical | Verify app URL |
-| Upgrade path works (not just fresh deploy) | Info | Test upgrade scenario |
+| Pack readiness (build output + dry-run pack) | Critical | §2 and §3 results — do not re-run |
+| Version consistent across `package.json`, `.uipath/` metadata, `app.config.json` | Warning | Compare version fields |
+| Prior publish evidence consistent (`app.config.json` present after first publish, IDs match `.uipath/` metadata) | Info | Read app.config.json + `.uipath/` metadata |
+| Upgrade path documented (version bump strategy, release notes — not just fresh deploy) | Info | Check versioning fields + changelog |

package/skills/uipath-review/references/flows/flow-common-issues.md

@@ -253,28 +253,4 @@ grep "console.log" *.flow
 
 **Severity:** Warning
 
-## API Workflow Antipatterns (Studio Web)
-
-### No Input Schema Enforcement
-
-**Symptom:** API workflow has input schema defined, but the first steps do not validate required inputs. Callers can send malformed payloads and the workflow tries to process them.
-
-**Impact:** NullReferenceException deep in the logic instead of a clear 400 Bad Request. Consumers get unhelpful errors.
-
-**Detection:** Inspect API workflow's initial activities. Check for explicit validation (required-field checks, type validation) before business logic begins.
-
-**Fix:** Add input validation as the first step. Return structured 400 responses with field-specific error messages.
-
-**Severity:** Warning
-
-### Synchronous Long-Running API Workflow
-
-**Symptom:** API workflow performing long-running logic (DB migrations, bulk processing, chained API calls) synchronously. Hard timeout: 10 minutes (5 min CPU for serverless).
-
-**Impact:** Request times out with no result, no recovery path. Caller sees timeout error. Work may be partially complete with no rollback.
-
-**Detection:** API workflow test execution exceeds 5 minutes.
-
-**Fix:** Convert to async pattern — accept request, return job ID, process in background (via queue), let caller poll. Or use `Wait for Event and Resume` for suspend/resume.
-
-**Severity:** Warning
+API workflow antipatterns moved to [api-workflow-review-checklist.md](../api-workflows/api-workflow-review-checklist.md) — API workflows are a separate project type.

package/skills/uipath-review/references/flows/flow-review-checklist.md

@@ -2,7 +2,7 @@
 
 Comprehensive quality checklist for UiPath Flow projects (`.flow` files) — orchestration of RPA processes, agents, apps, and human tasks.
 
-> **Unit of Work:** Before running the technical checks below, complete Step 3a (Unit of Work Discovery) from SKILL.md. For flows, the declared unit is in the `.flow` file under `variables.globals` with `direction: "in"` or `"inout"`. The actual unit is what the flow body produces — count downstream resource-node invocations and side effects per flow execution. If one flow invocation fans out to N downstream calls over a sub-collection of the input, that is a Granularity Mismatch (see [rpa-common-issues.md](../rpa/rpa-common-issues.md)).
+> **Unit of Work:** Before running the technical checks below, complete Step 3a (Unit of Work Discovery) from SKILL.md. For flows, the declared unit is in the `.flow` file under `variables.globals` with `direction: "in"` or `"inout"`. The actual unit is what the flow body produces — count downstream resource-node invocations and side effects per flow execution. If one flow invocation fans out to N downstream calls over a sub-collection of the input, the shape is one-to-many — assess per Step 3a (see [rpa-common-issues.md](../rpa/rpa-common-issues.md)).
 
 ## 1. Structural Validation
 
@@ -21,7 +21,7 @@ Comprehensive quality checklist for UiPath Flow projects (`.flow` files) — orc
 Run the CLI validator first:
 
 ```bash
-uip maestro flow validate <ProjectName>.flow --output json
+uip maestro flow validate "<PROJECT_NAME>.flow" --output json
 ```
 
 | Check | Severity | How to Verify |
@@ -191,75 +191,18 @@ If the flow uses queues for work distribution:
 | No orphan definitions (types not used by any node) | Info | Cross-reference definitions and nodes |
 | Definition versions match node `typeVersion` | Warning | Compare versions |
 
-## 8. BPMN / Maestro Compliance (If Using Maestro)
+## 8. Maestro BPMN Projects
 
-For flows that target UiPath Maestro execution:
+Maestro BPMN (`.bpmn` + `project.uiproj` with `"ProjectType": "ProcessOrchestration"`) is a separate project type — review it with [bpmn-review-checklist.md](../bpmn/bpmn-review-checklist.md), not this checklist.
 
-### BPMN Element Support (Execution-Ready)
-
-| Element Category | Supported for Execution | Modeling Only |
-|---|---|---|
-| **Start Events** | None, Message, Timer | Error, Signal, Conditional, Compensation, Escalation |
-| **Intermediate Catch** | Message, Timer | Signal, Conditional, Link |
-| **Boundary (Interrupting)** | Message, Timer, Error | Signal, Conditional, Escalation, Compensation |
-| **Boundary (Non-Interrupting)** | Message, Timer | Signal, Conditional, Escalation |
-| **End Events** | None, Message, Error, Terminate | Signal, Escalation, Compensation |
-| **Tasks** | User, Service, Send, Receive, Business Rule, Script, Manual | — |
-| **Gateways** | Exclusive, Parallel, Inclusive, Event-Based | Complex |
-| **Markers** | Multi-instance (parallel/sequential) | Loop, Compensation |
-| **Subprocesses** | Sub-process, Call Activity, Event Sub-process | Transaction |
-
-### Structural Checks
-
-| Check | Severity | How to Verify |
-|---|---|---|
-| All BPMN elements used are execution-ready (not modeling-only) | Critical | Compare against support table above |
-| One clear start event and explicit end events | Critical | Check node structure |
-| Parallel gateways have matching parallel join gateways | Critical | Verify parallel synchronization |
-| Inclusive gateways have matching inclusive merge | Critical | Verify inclusive synchronization |
-| Default path defined on exclusive gateways (prevents runtime faults) | Warning | Check gateway configuration |
-| Task sizes are uniform in diagrams | Info | Visual review |
-| Flow direction is left-to-right or top-to-bottom | Info | Check node positions |
-| Separate process flow from business rules (use DMN Business Rule Tasks) | Info | Check for complex conditionals |
-
-### Timer Configuration
-
-| Check | Severity | How to Verify |
-|---|---|---|
-| Timer events use valid ISO 8601 durations (e.g., `PT1H`, `P1D`, `R/PT5M`) | Critical | Check timer values |
-| Timer boundary events configured for long-running tasks (SLA enforcement) | Info | Check boundary events |
-| Non-interrupting timers used when parallel execution is needed | Info | Check timer interrupt mode |
-| Cycle timers use correct repeat format (`R/P[duration]`) | Warning | Check cycle syntax |
-
-### Multi-Instance Configuration
+### Flow vs Maestro BPMN Fitness
 
 | Check | Severity | How to Verify |
 |---|---|---|
-| Parallel multi-instance batch size appropriate (runs in batches of 50) | Info | Check batch config |
-| Sequential multi-instance used when item ordering matters | Warning | Verify ordering requirement |
-| Multi-instance loops configured to **continue on individual item failure** (one item's error does not halt the entire batch) | Warning | Check multi-instance configuration for continueOnException/continue-on-failure flag. Batches of 50 where item #15 fails should still process items 16..50 |
-| Entry-points UUIDs are unique (no duplicates across entries in `entry-points.json`) | Critical | Parse `entry-points.json`, check for duplicate `uniqueId` values. Duplicates block publishing |
-| Nested loops use subprocess pattern (outer sequential, inner parallel) | Info | Check nesting pattern |
-
-### Error Handling in BPMN
-
-| Check | Severity | How to Verify |
-|---|---|---|
-| Error boundary events attached to tasks with failure risk | Warning | Check boundary events |
-| Error end events used for unrecoverable failures | Info | Check error paths |
-| Event subprocesses configured for centralized error handling | Info | Check event subprocesses |
-| Error mappings configured at element level (first match wins) | Warning | Check error mapping order |
-
-### Maestro vs Flow Decision
-
-If the project uses the simple Flow format (not full Maestro BPMN):
-
-| Check | Severity | How to Verify |
-|---|---|---|
-| Flow complexity appropriate (simple flows don't need Maestro) | Info | Assess process complexity |
-| Long-running processes use Maestro (not simple flows) | Warning | Check process duration |
-| Human-in-the-loop steps use Maestro User Tasks | Warning | Check for HITL requirements |
-| Process mining integration needed → use Maestro (auto-creates Process Optimization apps) | Info | Check monitoring needs |
+| Flow complexity appropriate (simple flows don't need Maestro BPMN) | Info | Assess process complexity |
+| Long-running, multi-actor processes use Maestro BPMN (not simple flows) | Warning | Check process duration and actor mix |
+| Human-in-the-loop steps needing case tracking/SLA use Maestro User Tasks | Warning | Check for HITL requirements |
+| Process mining integration needed → Maestro BPMN (auto-creates Process Optimization apps) | Info | Check monitoring needs |
 
 ## 9. Performance and Optimization
 
@@ -280,7 +223,9 @@ If the project uses the simple Flow format (not full Maestro BPMN):
 | No mock placeholder nodes remain | Critical | Grep for `core.logic.mock` |
 | Entry points correctly defined | Warning | Check entry-points.json |
 | Environment-specific values externalized | Warning | Check for hardcoded URLs/paths |
-| Debug flow succeeds end-to-end | Warning | `uip maestro flow debug <project-dir>` |
+| Entry-point `uniqueId` values unique (duplicates block publishing) | Critical | Parse `entry-points.json` for duplicate `uniqueId` values |
+
+> Do NOT execute the flow (`uip maestro flow debug` / `run`) during review — review is read-only. Runtime verification routes to `uipath-maestro-flow`.
 
 ## 11. Action Center / Human-in-the-Loop