@uipath/skills 1.200.0 → 1.201.0-preview.433

package/skills/uipath-insights/references/jobs-commands-guide.md

@@ -6,18 +6,21 @@ Complete reference for `uip insights jobs` subcommands with response shapes and
 
 Every subcommand accepts these filter options:
 
-```
---time-range <minutes>         Relative time range (e.g. 1440 = 24h, 43200 = 30d)
+```text
+--time-range <minutes>         Relative time range (60 = 1h, 1440 = 24h, 10080 = 7d, 43200 = 30d)
 --started-after <epoch-ms>     Absolute start time as Unix epoch milliseconds
 --started-before <epoch-ms>    Absolute end time as Unix epoch milliseconds
 --folder-key <guid>            Folder key filter (repeatable)
 --process-name <name>          Process name filter (repeatable)
 --machine-name <name>          Machine name filter (repeatable)
 --timezone-offset <minutes>    Client timezone offset from UTC
---output <format>              Output format: json, yaml, table (always use json)
 ```
 
-**Time range rule:** Either `--time-range` OR both `--started-after` and `--started-before` must be provided. Omitting both causes a validation error.
+`--output <format>` is a global CLI option available on every command: `table`, `json`, `yaml`, `plain`. Always use `json`.
+
+**Time range rule:** Either `--time-range` OR both `--started-after` and `--started-before` must be provided. Omitting both is rejected locally with a `Failure` envelope and exit 1.
+
+Jobs commands take no `--limit` or `--offset`. A jobs response is complete for its time window.
 
 **Repeatable options:** `--folder-key`, `--process-name`, and `--machine-name` can be specified multiple times:
 ```bash
@@ -29,7 +32,7 @@ uip insights jobs summary --time-range 1440 \
 
 ## Response Envelope
 
-All commands return:
+All `jobs` subcommands return:
 ```json
 {
   "Result": "Success",
@@ -38,62 +41,163 @@ All commands return:
 }
 ```
 
+There is no `Pagination` field and no `Instructions` field on a successful jobs response. Both appear on `filter-*` commands only.
+
+`Code` identifies the subcommand that produced the response:
+
+| Subcommand | `Code` |
+|---|---|
+| `summary` | `InsightsJobsSummary` |
+| `completed-timeline` | `InsightsJobsCompletedTimeline` |
+| `uncompleted-timeline` | `InsightsJobsUncompletedTimeline` |
+| `top-failures` | `InsightsJobsTopFailures` |
+| `failures-by-reason` | `InsightsJobsFailuresByReason` |
+| `process-details` | `InsightsJobsProcessDetails` |
+| `failure-details` | `InsightsJobsFailureDetails` |
+
 On error:
 ```json
 {
   "Result": "Failure",
   "Message": "<error description>",
   "Instructions": "<how to fix>",
-  "ErrorCode": "unknown_error"
+  "ErrorCode": "unknown_error",
+  "Retry": "RetryWillNotFix"
 }
 ```
 
+Branch on `Retry` as described in SKILL.md Critical Rule 8, rather than on the wording of `Message`.
+
+On a failure the command emits itself, `ErrorCode` is always `unknown_error`, including auth and permission failures, because the HTTP status never reaches the field. Read the status out of `Message`, which carries it as `API request failed: <status> <statusText> - <body>`. Do not branch on `ErrorCode` here. A jobs `Message` without that prefix carries no HTTP status: it is local validation, a session problem, or a transport failure such as `fetch failed` or an unparseable body.
+
+A rejected flag is a different shape. Commander catches it before the command runs and returns `Result: ValidationError` with `ErrorCode: invalid_argument` and exit 3.
+
+`filter-*` HTTP failures report a specific `ErrorCode` such as `authentication_required` or `permission_denied`. A malformed `filter-*` response still reports `unknown_error`.
+
 ## Response Data Shape
 
-All endpoints return the same `JobsResponse` shape. Fields are populated or null depending on the endpoint:
+Null, empty, or zero across every field on a `Success` response means the query matched no rows. It is not a failure, and it does not on its own prove that no jobs ran. See the last row of Troubleshooting for the causes and what to report.
+
+All endpoints return the same shape. Which fields are populated depends on the endpoint.
+
+**Keys inside `Data` are PascalCase on the wire.** The CLI PascalCases every `Data` key before printing, so read `JobsCount`, not `jobsCount`. The type below is the SDK's `JobsResponse` in its camelCase source form. Every field is optional, so a field the endpoint does not populate may be absent or null.
 
 ```typescript
 interface JobsResponse {
-  jobState: string[] | null;
-  robotName: string[] | null;
-  processName: string[] | null;
-  jobCount: number[] | null;
-  jobCountByTime: number[][] | null;
-  folderName: string[] | null;
-  folderKey: string[] | null;
-  machineName: string[] | null;
-  hostMachineName: string[] | null;
-  machineKey: string[] | null;
-  machineStatus: string[] | null;
-  timestamp: string[] | null;
-  processExceptionType: string[] | null;
-  processExceptionReason: string[] | null;
-  startTime: string[] | null;
-  endTime: string[] | null;
-  utilizationTime: string[] | null;
-  duration: number[] | null;
-  successRate: number[] | null;
-  averageProcessingTime: number | null;
-  jobsCount: number | null;
-  successfulJobsCount: number | null;
-  jobAggregate: number[][] | null;
-  creationTime: string[] | null;
-  folderId: string[] | null;
-  jobKey: string[] | null;
+  jobState?: string[];
+  robotName?: string[];
+  processName?: string[];
+  jobCount?: number[];
+  jobCountByTime?: number[][];
+  folderName?: string[];
+  folderKey?: string[];
+  machineName?: string[];
+  hostMachineName?: string[];
+  machineKey?: string[];
+  machineStatus?: string[];
+  timestamp?: string[];
+  processExceptionType?: string[];
+  processExceptionReason?: string[];
+  startTime?: string[];
+  endTime?: string[];
+  utilizationTime?: string[];
+  duration?: number[];
+  successRate?: number[];
+  averageProcessingTime?: number;
+  jobsCount?: number;
+  successfulJobsCount?: number;
+  jobAggregate?: number[][];
+  creationTime?: string[];
+  folderId?: string[];
+  jobKey?: string[];
 }
 ```
 
-## Per-Endpoint Key Fields
+## Commands
+
+### summary
+
+Get job KPIs: total count, successful count, and average processing time.
+
+```bash
+uip insights jobs summary --time-range 1440 --output json
+```
+
+**Key Data fields:** `JobsCount`, `SuccessfulJobsCount`, `AverageProcessingTime`
+
+**Use when:** User asks "how are my automations doing?" or "what's my job success rate?"
+
+### completed-timeline
+
+Get completed jobs over time, grouped by job state.
+
+```bash
+uip insights jobs completed-timeline --time-range 1440 --output json
+```
+
+**Key Data fields:** `JobState`, `JobCountByTime`, `Timestamp`
+
+**Use when:** User asks for job completion trends or when most jobs run.
+
+### uncompleted-timeline
+
+Get running and pending jobs over time.
+
+```bash
+uip insights jobs uncompleted-timeline --time-range 1440 --output json
+```
+
+**Key Data fields:** `JobState`, `JobCountByTime`, `Timestamp`
+
+**Use when:** User asks whether jobs are stuck or how many jobs are still running.
+
+### top-failures
+
+Get processes ranked by failure count.
+
+```bash
+uip insights jobs top-failures --time-range 43200 --output json
+```
 
-| Endpoint | Code | Key Data Fields |
-|----------|------|-----------------|
-| `summary` | `InsightsJobsSummary` | `jobsCount`, `successfulJobsCount`, `averageProcessingTime` |
-| `completed-timeline` | `InsightsJobsCompletedTimeline` | `jobState`, `jobCountByTime`, `timestamp` |
-| `uncompleted-timeline` | `InsightsJobsUncompletedTimeline` | `jobState`, `jobCountByTime`, `timestamp` |
-| `top-failures` | `InsightsJobsTopFailures` | `processName`, `jobCountByTime` |
-| `failures-by-reason` | `InsightsJobsFailuresByReason` | `processExceptionReason`, `processName`, `robotName`, `jobsCount` |
-| `process-details` | `InsightsJobsProcessDetails` | `processName`, `jobAggregate` |
-| `failure-details` | `InsightsJobsFailureDetails` | `processName`, `machineName`, `processExceptionReason`, `startTime`, `endTime` |
+**Key Data fields:** `ProcessName`, `JobCountByTime`
+
+**Use when:** User asks which processes fail most.
+
+### failures-by-reason
+
+Get job failures grouped by exception reason, with total job count for context.
+
+```bash
+uip insights jobs failures-by-reason --time-range 1440 --output json
+```
+
+**Key Data fields:** `ProcessExceptionReason`, `ProcessName`, `RobotName`, `JobsCount`
+
+**Use when:** User asks why jobs are failing or what the common error messages are.
+
+### process-details
+
+Get per-process job counts by state.
+
+```bash
+uip insights jobs process-details --time-range 1440 --output json
+```
+
+**Key Data fields:** `ProcessName`, `JobAggregate`
+
+**Use when:** User asks for per-process statistics or which process has the most faulted jobs.
+
+### failure-details
+
+Get detailed failure information for investigation.
+
+```bash
+uip insights jobs failure-details --time-range 1440 --output json
+```
+
+**Key Data fields:** `ProcessName`, `MachineName`, `ProcessExceptionReason`, `StartTime`, `EndTime`
+
+**Use when:** User asks for recent failure details or which machines are affected.
 
 ## Example: Summary
 
@@ -103,19 +207,19 @@ $ uip insights jobs summary --time-range 1440 --output json
   "Result": "Success",
   "Code": "InsightsJobsSummary",
   "Data": {
-    "jobsCount": 142,
-    "successfulJobsCount": 135,
-    "averageProcessingTime": 45.7,
-    "jobState": null,
-    "processName": null,
+    "JobsCount": 142,
+    "SuccessfulJobsCount": 135,
+    "AverageProcessingTime": 45.7,
+    "JobState": null,
+    "ProcessName": null,
     ...
   }
 }
 ```
 
 Deriving metrics:
-- **Failure rate:** `(jobsCount - successfulJobsCount) / jobsCount * 100`
-- **Success rate:** `successfulJobsCount / jobsCount * 100`
+- **Failure rate:** `(JobsCount - SuccessfulJobsCount) / JobsCount * 100`
+- **Success rate:** `SuccessfulJobsCount / JobsCount * 100`
 
 ## Example: Top Failures with Filter
 
@@ -127,14 +231,53 @@ $ uip insights jobs top-failures --time-range 43200 \
   "Result": "Success",
   "Code": "InsightsJobsTopFailures",
   "Data": {
-    "processName": ["Invoice_Processing", "Email_Parser", "Data_Upload"],
-    "jobCountByTime": [[23, 15, 8]],
+    "ProcessName": ["Invoice_Processing", "Email_Parser", "Data_Upload"],
+    "JobCountByTime": [[23, 15, 8]],
     ...
   }
 }
 ```
 
-The `processName` array and `jobCountByTime[0]` array are parallel — index 0 of both corresponds to the same process.
+The `ProcessName` array and `JobCountByTime[0]` array are parallel: index 0 of both corresponds to the same process.
+
+## Absolute Time Ranges
+
+**Treat `--started-before` as exclusive.** For "July 1 through July 5 inclusive", pass July 1 00:00:00 UTC and July 6 00:00:00 UTC. Resolve both boundaries before writing the command. The CLI forwards the value unchanged, so the boundary is a backend behavior and is not confirmed against a live tenant.
+
+Resolve exact date boundaries to epoch milliseconds before running a Jobs command. Run the date conversion separately, read its output, then pass literal values to `uip`. Do not embed shell substitutions or variables in the Insights command. The `date` flags differ between macOS and Linux, so a substitution that fails silently turns the flag into garbage, queries the wrong window, and leaves the logged command showing a range that was never asked for.
+
+```bash
+# Linux
+date -u -d "2026-07-01 00:00:00" +%s000
+date -u -d "2026-07-06 00:00:00" +%s000
+
+# macOS
+date -u -j -f "%Y-%m-%d %H:%M:%S" "2026-07-01 00:00:00" +%s000
+date -u -j -f "%Y-%m-%d %H:%M:%S" "2026-07-06 00:00:00" +%s000
+```
+
+Then use the literal results:
+
+```bash
+uip insights jobs summary \
+  --started-after 1782864000000 \
+  --started-before 1783296000000 \
+  --output json
+```
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `Not logged in. …` | No active session, or it expired | Tell the user to run `uip login`, or follow the hint the message carries |
+| `Tenant not provided and UIPATH_TENANT_NAME not set. …` | A session exists but no tenant is selected | Tell the user to run `uip login tenant set <tenant>`, or `uip login` to re-select one. The message names both |
+| `A time range is required.` | Neither `--time-range` nor both halves of `--started-after`/`--started-before` was passed | Add `--time-range 1440`, or pass both absolute bounds |
+| `API request failed: 401 …` | The session is expired, missing, or scoped to another tenant | Tell the user to re-login, then confirm the active tenant |
+| `API request failed: 403 …` | The caller has no permission on the folders in scope | Check folder assignments in Orchestrator admin |
+| `API request failed: 5xx …` | Backend fault | Report it with the time window and filters. Do not retry automatically |
+| Every `Data` field null, empty, or zero on a `Success` response | No rows matched: narrow window, no visible folders, or the wrong tenant | Widen `--time-range` (43200 covers 30 days), confirm the tenant, then report what the result does not prove |
+
+A missing time range cannot reach the server. The command rejects it locally and exits 1 before it builds a session or sends a request, so the envelope is `Result: Failure` with `ErrorCode: unknown_error` and never an HTTP status.
 
 ## API Details
 

package/skills/uipath-ixp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uipath-ixp
-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. DO NOT TRIGGER during .flow / Maestro Flow work — discovering or listing IxP / document-extraction models, extractors, or nodes available to Maestro Flow, and adding or wiring an IxP node, belong to uipath-maestro-flow even when they sound like IXP model management."
+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, deploy a trained version to an Orchestrator folder and move an existing deployment to another version (`deployments create`/`upgrade`/`list`). DO NOT TRIGGER during .flow / Maestro Flow work — discovering or listing IxP / document-extraction models, extractors, or nodes available to Maestro Flow, and adding or wiring an IxP node, belong to uipath-maestro-flow even when they sound like IXP model management."
 ---
 
 # UiPath IXP Document Extraction Assistant
@@ -13,6 +13,7 @@ Skill for working with UiPath IXP (Intelligent eXtraction Platform) projects —
 - User asks to label, review, or confirm document predictions
 - User asks to improve extraction scores, prompts, or field instructions
 - User asks to publish or manage IXP model versions
+- User asks to deploy a trained model version to an Orchestrator folder, move a deployment to another version, or list where a project is deployed (`deployments create` / `upgrade` / `list`)
 - User provides a taxonomy file to import into a project
 - User asks for the project taxonomy at a specific trained model version — what the schema looked like when version N was published (use `deployments get-taxonomy <project-name> --version <N>`)
 
@@ -49,10 +50,12 @@ Do not answer these from this skill. Re-activate `uipath-maestro-flow` and follo
 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` — an index into **that read**, not a stable row id (Rule 18); 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).
-15. **F1 reflects confirmed labels, not document truth — never blind-confirm.** F1/`ProjectScore` measure prediction-vs-confirmed-label agreement, so a wrong value you confirm becomes the "right" answer and scores 1.00. A perfect score is **not** evidence the values are correct. Before confirming, sanity-check each value against the document. The per-document no-`--fields` form (confirm all predicted fields on one document) is fine once you've reviewed them all. If the user explicitly says every predicted field in named documents was reviewed and is correct, accept that review and confirm those documents without refetching predictions. Never run `confirm` without a document-id — that confirms every document at once, bypassing review. See [Label Documents Guide](references/label-documents-guide.md) §2c.
+15. **F1 reflects confirmed labels, not document truth — never blind-confirm.** F1/`ProjectScore` measure prediction-vs-confirmed-label agreement, so a wrong value you confirm becomes the "right" answer and scores 1.00. A perfect score is **not** evidence the values are correct. Before confirming, sanity-check each value against the document. The per-document no-`--fields` form (confirm all predicted fields on one document) is fine once you've reviewed them all. If the user explicitly says every predicted field in named documents was reviewed and is correct, accept that review and confirm those documents without re-reviewing them field by field (still pin the version — Rule 19). Never run `confirm` without a document-id — that confirms every document at once, bypassing review. See [Label Documents Guide](references/label-documents-guide.md) §2c.
 16. **Ambiguous entity reference → ask, never guess.** Projects (Titles), field groups, fields, and data types share one namespace in user speech ("rename subscriptions"). Before any mutation (`update-title`, `rename`, `delete`, `change-type`), resolve which entity KIND the user means. If the name matches more than one kind — in the user's own context or in `projects list` / taxonomy output — STOP and ask which one, explicitly listing every matching candidate and its kind. Do NOT pick one, and do NOT mutate several candidates "to cover all cases". When the user can't be asked interactively, surface the question through whatever channel the task provides and stop.
 17. **Reuse the built-in data types before adding new ones.** Every IXP project ships with default data types — `Exact Text`, `Inferred Text`, `Number`, `Date`, `Monetary Quantity`, `Boolean` (the project's `entity_defs` from `projects get-taxonomy` are the authoritative list). Before `data-types add` or picking a field's `--type`, reuse a matching default — e.g. `Monetary Quantity` for a currency amount, never a hand-rolled clone (`Currency Amount`). Add a new type only when no default covers it: a project-specific `Choice`, or a concept needing its own tailored extraction instructions. Never add one just to reformat — the pre-trained defaults keep their fixed output format regardless of instructions. Mapping: [CLI Reference § Default data types](references/cli-reference.md#default-data-types).
 18. **`Occurrence` is scoped to the read that produced it — re-read predictions after every per-occurrence write.** The server pairs annotations with predictions and returns **matched pairs first**, so confirming one row of a repeatable group moves that row to `Occurrence` 0 on the next read and renumbers the rest (the IXP UI shows it first too). Nothing is lost — the row keeps its own values and page location — but the indices you read *before* the write no longer identify the same rows. So: confirm/unconfirm every target in ONE `--updates` call (all its indices resolve against the same read), and when sequential per-occurrence calls are unavoidable, re-run `get-predictions` between them and re-locate each row by its field values, never by the index you saw earlier. Only fully-unannotated and fully-annotated documents read back in document order. Report rows to the user by value ("the freight-surcharge line"), not by index.
+19. **Confirm against the version you reviewed — pass `--model-version`.** Confirming triggers a retrain, so predictions can drift between your `get-predictions` read and your `confirm`. Pass the read's `ModelVersion` as `confirm -m <N>`; if a retrain changed the version since, the confirm is rejected (`PredictionVersionChangedError`) rather than stamping values you never reviewed as ground truth. On that error, re-read `get-predictions`, re-review, and confirm against the new version. Confirming on a user-supplied review (Rule 15) is no exemption: pin the `ModelVersion` the user names, or run one `get-predictions` to capture it — a read for the version alone is not a re-review.
+20. **`DeploymentName` ≠ `DeploymentTitle`, and `create` never repoints.** `deployments create --title` sets a free-form `DeploymentTitle`; the name the **runtime** resolves is `DeploymentName`, which the backend slugs and suffixes per deployment (`invoices` → `invoices-08963f00-ixp`) and which **cannot be predicted from the request** — read it off the create response or `deployments list`, never construct it. `create` only ever ADDS: repointing an existing deployment to another version is `deployments upgrade <project-name> <deployment-name>`, which takes `DeploymentName` (passing a title there is a `404`). Run `deployments list` before every `upgrade`. Upgrading changes which model version **every runtime caller of that folder and name** gets — confirm intent before touching a shared folder. See [CLI Reference § Deployments](references/cli-reference.md#deployments).
 
 ## Quick Start
 
@@ -71,10 +74,13 @@ If the user provides a taxonomy file, use `--skip-taxonomy` and `import-taxonomy
 | "Import this taxonomy" / provides a taxonomy file | [Project Setup Guide](references/project-setup-guide.md) — Option B (`--skip-taxonomy` + `import-taxonomy`) |
 | "Label documents" / "Review predictions" | [Label Documents Guide](references/label-documents-guide.md) |
 | "Improve scores" / "Fix prompts" / "Improve F1" | [Improve Prompts Guide](references/improve-prompts-guide.md) |
-| "Publish the model" / "Tag as live" | `uip ixp projects publish <project-name> --output json` — publishes the latest version, untagged. Add `--tag <live\|staging>` to also tag it. See [cli-reference](references/cli-reference.md) for `--model-version`/`--description`. **Publishing does not deploy the model to an Orchestrator folder** — folder/environment binding is a product-side step with no `uip ixp` (or other CLI) equivalent, so publishing is the last step this skill performs. Don't chain a folder deployment onto it, deploy locally, or improvise another path. Only when the user explicitly asks to deploy to a folder/environment do you hand that back to them (it's done in-product) — see the "Deploy this model" row under [Unsupported Capabilities](#unsupported-capabilities). Deploying to a folder is what makes the model available to downstream consumers such as Maestro Flow. |
+| "Publish the model" / "Tag as live" | `uip ixp projects publish <project-name> --output json` — publishes the latest version, untagged. Add `--tag <live\|staging>` to also tag it. See [cli-reference](references/cli-reference.md) for `--model-version`/`--description`. **Publishing does not deploy the model to an Orchestrator folder** — publishing makes the version usable *inside* the project; `deployments create` (see the "Deploy this model to a folder" row below) is what makes it callable at runtime by activity packs and Maestro Flow. Do NOT chain a deploy onto a publish unless the user asked to deploy — a deploy needs a folder key and changes what runtime callers get. |
 | "Roll back to a previous version" / "Restore version N" | `uip ixp projects publish <project-name> --model-version <N> --output json` — re-publishes an earlier version. Get available versions from `uip ixp projects list-models <project-name> --output json`. |
 | "Unpublish a model" / "Take a model out of production" | `uip ixp projects unpublish <project-name> --model-version <N> --output json` — removes a version from the published set (it stays trained/listable). `--model-version` is required; find published versions via `list-models` (`Pinned: true`). To change which version is live, `publish` a different one instead. |
 | "Remove the live/staging tag" / "Untag a version" | `uip ixp projects untag <project-name> --tag <live\|staging> --output json` — removes the named tag (the version it pointed at stays published). **`untag` is the only way to remove a tag** — do NOT `unpublish` or re-`publish` to clear it (`unpublish` removes publication, not the tag; `publish` without `--tag` leaves the existing tag untouched). To switch `live`→`staging`, `publish --tag staging` instead. |
+| "Deploy this model to a folder" / "make it callable at runtime" / "deploy version N" | `uip ixp deployments create <project-name> --version <N> --folder-key <guid> [--title <title>] --output json` — deploys a trained version to an Orchestrator folder, making it callable by activity packs and Maestro Flow. `--version` (from `projects list-models`) and `--folder-key` (from `uip or folders list --output json`) are both **required**; `--title` defaults to the project name minus `-ixp`. **`create` never repoints an existing deployment** — a title already deployed in that folder on a different version is a `409`; use `upgrade` (next row). Read `DeploymentName` off the response: it is slugged and suffixed, never the title or the project name. See [cli-reference § Deployments](references/cli-reference.md#deployments). |
+| "Move a deployment to another version" / "upgrade the deployed model" / "that folder is serving an old version" | `uip ixp deployments upgrade <project-name> <deployment-name> --version <N> --folder-key <guid> --output json` — `<deployment-name>` is the `DeploymentName` from `deployments list`, **not** the title (a title there is a `404`). Changes which version **every runtime caller of that folder and name** gets, so confirm intent on a shared folder. **Not a rollback path** — the target version must still appear in `projects list-models`. See [cli-reference § create vs upgrade](references/cli-reference.md#create-vs-upgrade). |
+| "Where is this model deployed?" / "list deployments" / "which folder or version is live at runtime" | `uip ixp deployments list <project-name> --output json` — array of `DeploymentName`, `DeploymentTitle`, `ModelVersion`, `FolderKey`, `DeployedAt`; `[]` for a never-deployed project. **The only reliable source of `DeploymentName`** — run it before any `upgrade`. |
 | "Show metrics" / "What are the scores?" | `uip ixp projects get-metrics <project-name> --output json` |
 | "List projects" | `uip ixp projects list --output json` |
 | "Configure the model" | `uip ixp projects configure-model <project-name> [options] --output json` |
@@ -113,7 +119,7 @@ These requests fall outside the skill. Recognise the request, reply with the sta
 |--------------|-------------------|
 | "Create a model" / "create a project" | **Documents or a taxonomy supplied →** use the [Project Setup Guide](references/project-setup-guide.md) (this skill creates the project from them). **Otherwise →** "I work on existing IXP projects rather than creating them from scratch. Create one in-product: https://docs.uipath.com/ixp/automation-cloud/latest/user-guide/managing-projects — then I can label, review, and improve it." |
 | "Upload these files" / "add documents" | **Project named / already in context →** supported; upload it (see the "Upload a document" row in Task Navigation). **Otherwise →** "Name an existing project and I'll upload it — or upload in-product (e.g. for a new project): https://docs.uipath.com/ixp/automation-cloud/latest/user-guide/building-and-deploying-models." |
-| "Deploy this model" / "push to staging / production / folder / environment / tenant" | "I don't drive deployment to folders, environments, or tenants — that's a product-side flow: https://docs.uipath.com/ixp/automation-cloud/latest/user-guide/building-and-deploying-models. I can publish a model version with `uip ixp projects publish <project-name> --output json`, but binding it to a folder/environment is done in-product." |
+| "Deploy this model" / "push to staging / production / folder / environment / tenant" | **Folder deployment is supported** — deploy with `uip ixp deployments create` (see the "Deploy this model to a folder" row in [Task Navigation](#task-navigation)). If the user NAMES a folder rather than giving its key, resolve the name with `uip or folders list --output json` — ask only when no folder was identified at all. For anything that is not an Orchestrator folder: "I deploy model versions to Orchestrator **folders**. Binding to environments or another tenant is a product-side flow: https://docs.uipath.com/ixp/automation-cloud/latest/user-guide/building-and-deploying-models." Note `projects publish --tag staging\|live` tags a version *inside* the project — it deploys nothing. |
 | "Give X access" / "share this project" / "change roles or permissions" | "Access, roles, and permissions are managed in-product, not through this skill: https://docs.uipath.com/ixp/automation-cloud/latest/overview/managing-access." |
 | "Use this model in my automation / workflow / agent" / "call the extractor from a process" | "Consuming a published model inside an automation is an authoring task outside this skill. See https://docs.uipath.com/ixp/automation-cloud/latest/user-guide/building-and-consuming-a-workflow." |
 | "Mine these emails / communications" / "set up Communications Mining" | "Communications Mining is a separate IXP capability this skill doesn't cover (this skill is document extraction). See https://docs.uipath.com/ixp/automation-cloud/latest/cm-user-guide/introduction-to-uipath-communication-mining." |

package/skills/uipath-ixp/references/cli-reference.md

@@ -168,10 +168,10 @@ Add before deleting: if the add fails, the field is still in its original group.
 
 | Command | Description |
 |---------|-------------|
-| `uip ixp labellings get-predictions <project-name> [document-id] --output json` | Get IXP model predictions for all documents (or a single document). Returns `Data: { ProjectName, TotalDocuments, DocumentsWithPredictions, Predictions[] }`. Each `Predictions[]` entry is one document `{ DocumentId, Labels[] }`; each label is `{ Name, Occurrence, Fields[] }`; each field is `{ FieldId, FieldName, FormattedValue }`. This is the model's **prediction** layer, not the confirmed/annotation layer. Each label carries an explicit `Occurrence` (the value for `--occurrence`/`--updates`); it is 0-based and usually runs 0..N-1 in document order, but do NOT assume it is contiguous or starts at 0 — a single-occurrence group can come back as `Occurrence` 1 with no 0. Always target the actual `Occurrence` value reported here, never a positional guess. **The order is not stable across writes**: the server lists annotation↔prediction matched pairs first, so confirmed rows of a repeatable group sort to the front and the rest renumber — see [Occurrence numbering and read order](#occurrence-numbering-and-read-order). |
-| `uip ixp labellings confirm <project-name> <document-id> [--fields <ids>] [--corrections <json>] --output json` | Confirm predictions for a document. (`--fields` has short alias `-f`; `--corrections` has short alias `-c`.) Without `--fields`, confirms every predicted field that has content. `--fields "a7c3e9105f2b4d86,b2f8a01c7d3e6940"` confirms only those fields, and applies a **single uniform rule**: listed fields with content get confirmed; listed fields whose IXP prediction is empty get a missing marker (the explicit listing IS the confirmation that the empty state is intentional — see Critical Rule 12). `--corrections '[{"field_id":"...","value":"..."}]'` is **only for OCR-mangled values** — same field, same location, garbled bytes. Do NOT use `--corrections` to flip wrong booleans, fix wrong inferred values, or override any non-OCR mistake; those fields must be left unannotated. See Critical Rule 8. Existing missing markers and other annotations carry forward across calls. |
-| `uip ixp labellings confirm <project-name> <document-id> --group <name> --occurrence <N> [--fields <ids>] [--corrections <json>] --output json` | **Single-occurrence form** — confirm ONE occurrence. The ergonomic choice for a single line. `--occurrence` is the 0-based index of the target extraction within `--group`, as reported by the **latest** `get-predictions`. Without `--fields`, confirms every predicted field in that one occurrence; with `--fields`, confirms only those fields there. Other occurrences are untouched. Requires `--group`. Mutually exclusive with `--updates`. The call renumbers the group for subsequent reads ([Occurrence numbering and read order](#occurrence-numbering-and-read-order)), so use `--updates` for more than one row instead of chaining these off one read. |
-| `uip ixp labellings confirm <project-name> <document-id> --group <name> --updates <json> --output json` | **Batched form** — confirm SEVERAL occurrences in ONE atomic call (one request; avoids N round-trips, e.g. a 10-line invoice). `--updates` is a JSON array `[{"occurrence":<0-based-index>,"fields"?:["<field_id>",…],"corrections"?:{"<field_id>":"<value>"}}]`. Per entry: **omit `"fields"`** to confirm every predicted field in that occurrence (same default as `--occurrence` without `--fields`), or list specific IDs; un-selected fields in a selected occurrence carry forward any existing annotation. **`--updates` is the superset** — `--occurrence <N>` ≡ `--updates` with one entry; both share the same per-occurrence logic. Use `--occurrence` for a single line, `--updates` for several together. Mutually exclusive with `--fields`/`--corrections`/`--occurrence`. |
+| `uip ixp labellings get-predictions <project-name> <document-id> --output json` | Get IXP model predictions for one document. Returns `Data: { ProjectName, TotalDocuments, DocumentsWithPredictions, Predictions[] }`. Each `Predictions[]` entry is one document `{ DocumentId, Labels[] }`; each label is `{ Name, Occurrence, Fields[] }`; each field is `{ FieldId, FieldName, FormattedValue }`. This is the model's **prediction** layer, not the confirmed/annotation layer. Each label carries an explicit `Occurrence` (the value for `--occurrence`/`--updates`); it is 0-based and usually runs 0..N-1 in document order, but do NOT assume it is contiguous or starts at 0 — a single-occurrence group can come back as `Occurrence` 1 with no 0. Always target the actual `Occurrence` value reported here, never a positional guess. **The order is not stable across writes**: the server lists annotation↔prediction matched pairs first, so confirmed rows of a repeatable group sort to the front and the rest renumber — see [Occurrence numbering and read order](#occurrence-numbering-and-read-order). Each document also carries `ModelVersion` (the model version that produced its predictions) — capture it and pass it to `confirm -m/--model-version` to guard against a mid-review retrain. |
+| `uip ixp labellings confirm <project-name> <document-id> [--fields <ids>] [--corrections <json>] [--model-version <version>] --output json` | Confirm predictions for a document. (`--fields` has short alias `-f`; `--corrections` has short alias `-c`.) Without `--fields`, confirms every predicted field that has content. `--fields "a7c3e9105f2b4d86,b2f8a01c7d3e6940"` confirms only those fields, and applies a **single uniform rule**: listed fields with content get confirmed; listed fields whose IXP prediction is empty get a missing marker (the explicit listing IS the confirmation that the empty state is intentional — see Critical Rule 12). `--corrections '[{"field_id":"...","value":"..."}]'` is **only for OCR-mangled values** — same field, same location, garbled bytes. Do NOT use `--corrections` to flip wrong booleans, fix wrong inferred values, or override any non-OCR mistake; those fields must be left unannotated. See Critical Rule 8. Existing missing markers and other annotations carry forward across calls. `-m, --model-version <N>` pins the model version you reviewed (the `ModelVersion` from `get-predictions`); if a retrain produced a newer version since, the confirm is rejected (`PredictionVersionChangedError`) instead of stamping drifted values — re-read predictions and review again. |
+| `uip ixp labellings confirm <project-name> <document-id> --group <name> --occurrence <N> [--fields <ids>] [--corrections <json>] [--model-version <version>] --output json` | **Single-occurrence form** — confirm ONE occurrence. The ergonomic choice for a single line. `--occurrence` is the 0-based index of the target extraction within `--group`, as reported by the **latest** `get-predictions`. Without `--fields`, confirms every predicted field in that one occurrence; with `--fields`, confirms only those fields there. Other occurrences are untouched. Requires `--group`. Mutually exclusive with `--updates`. The call renumbers the group for subsequent reads ([Occurrence numbering and read order](#occurrence-numbering-and-read-order)), so use `--updates` for more than one row instead of chaining these off one read. |
+| `uip ixp labellings confirm <project-name> <document-id> --group <name> --updates <json> [--model-version <version>] --output json` | **Batched form** — confirm SEVERAL occurrences in ONE atomic call (one request; avoids N round-trips, e.g. a 10-line invoice). `--updates` is a JSON array `[{"occurrence":<0-based-index>,"fields"?:["<field_id>",…],"corrections"?:{"<field_id>":"<value>"}}]`. Per entry: **omit `"fields"`** to confirm every predicted field in that occurrence (same default as `--occurrence` without `--fields`), or list specific IDs; un-selected fields in a selected occurrence carry forward any existing annotation. **`--updates` is the superset** — `--occurrence <N>` ≡ `--updates` with one entry; both share the same per-occurrence logic. Use `--occurrence` for a single line, `--updates` for several together. Mutually exclusive with `--fields`/`--corrections`/`--occurrence`. |
 | `uip ixp labellings unconfirm <project-name> <document-id> --fields <ids> --output json` | Roll back confirmations on a document (`--fields` has short alias `-f`) — the listed fields go back to un-annotated state. Use when an earlier `confirm` was a mistake (confirm can't un-confirm — Critical Rule 14). Every other annotation on the document is carried forward. **With `--fields` alone, a field id shared across occurrences of a repeatable group is removed from all of them**; to scope the roll-back to specific occurrences, add `--group` (see the two rows below). Returns `Unmatched` for IDs that weren't annotated to begin with. |
 | `uip ixp labellings unconfirm <project-name> <document-id> --group <name> [--occurrence <N>] [--fields <ids>] --output json` | **Per-occurrence form** — roll back specific occurrences of a repeatable group instead of every occurrence a field id appears in. `--group` alone unconfirms every occurrence of the group; add `--occurrence <N>` (0-based, same index as `get-predictions`/`confirm`, taken from a **fresh** read — on a partly-confirmed group the index that confirmed a row is usually not the index that rolls it back) to roll back ONE occurrence. Without `--fields`, unconfirms every annotated field in the targeted occurrence(s); with `--fields`, only those there. Other occurrences are untouched. Mutually exclusive with `--updates`. Mirrors `confirm`'s `--group`/`--occurrence` flags. |
 | `uip ixp labellings unconfirm <project-name> <document-id> --group <name> --updates <json> --output json` | **Batched form** — roll back SEVERAL occurrences in ONE atomic call. `--updates` is a JSON array `[{"occurrence":<0-based-index>,"fields"?:["<field_id>",…]}]`. Per entry: omit `"fields"` to unconfirm every annotated field in that occurrence, or list specific IDs. Occurrences not listed are left as-is. Mutually exclusive with `--fields`/`--occurrence`. |
@@ -191,8 +191,62 @@ So an `Occurrence` value is invalidated by any write to its group:
 
 ## Deployments
 
-For working with runtime (deployed) IXP models — separate from the training workflow above. The `uip ixp` publish and tag commands operate within the project; they do **not** deploy a model to an Orchestrator folder. Making a model available to downstream consumers such as Maestro Flow requires deploying it to a folder — a separate, product-side step done by the user in-product.
+Publishing a version (`projects publish`) makes it usable **inside** the project. Deploying it to an Orchestrator folder is the separate step that makes it callable **at runtime** — activity packs and Maestro Flow address a model by the `{FolderKey, DeploymentName}` pair.
 
 | Command | Description |
 |---------|-------------|
+| `uip ixp deployments create <project-name> --version <N> --folder-key <guid> [--title <title>] --output json` | Deploy a trained model version to an Orchestrator folder. **Only ever adds** — never repoints an existing deployment (see [create vs upgrade](#create-vs-upgrade)). `--version` and `--folder-key` are both **required**; `--title` defaults to the project name minus its `-ixp` suffix. Returns `ProjectName`, `ModelVersion`, `FolderKey`, `DeploymentTitle`, `DeploymentName` (Code: `IxpDeploymentsCreate`). |
+| `uip ixp deployments upgrade <project-name> <deployment-name> --version <N> --folder-key <guid> --output json` | Move an existing deployment to another trained model version. `<deployment-name>` is a positional argument and takes the **`DeploymentName`** from `deployments list` — NOT the title (Code: `IxpDeploymentsUpgrade`). |
+| `uip ixp deployments list <project-name> --output json` | List the project's deployments across every version and folder. **The only reliable source of `DeploymentName`.** `Data` is an array — `[]` for a never-deployed project, never a `{Message: ...}` object, so iterate unconditionally. Each entry carries `DeploymentName`, `DeploymentTitle`, `ModelVersion`, `FolderKey`, `DeployedAt` (Code: `IxpDeploymentsList`). |
 | `uip ixp deployments get-taxonomy <project-name> --version <N> --output json` | Get the project taxonomy (data types + field groups) at a specific trained model version. `--version` is **required** (non-negative integer; 0 is valid; no short alias) — get the number from `projects list-models`. Like `projects get-taxonomy`, the body is the raw IXP dataset artifact in snake_case, under `Data.dataset` (`entity_defs[]` + `label_groups[]`), bound to the snapshot the version was trained on (Code: `IxpDeploymentsGetTaxonomy`). |
+
+### create vs upgrade
+
+Two commands, not one. `create` only adds; `upgrade` moves an existing deployment.
+
+| Existing deployment in the folder | `create` | `upgrade` |
+|---|---|---|
+| none | deploys | `404 [DeploymentNotFoundError]` |
+| same model version | no-op, exit `0` | no-op, exit `0` — `DeployedAt` does not move |
+| different model version | `409 [DeploymentAlreadyExistsError]` | repoints |
+
+Both verbs are no-ops at the same version, so both are safe to re-run from CI. `create` has **no `--force`** — use `upgrade` to repoint.
+
+`upgrade` changes which model version **every runtime caller of that folder and name** gets. Confirm the intent before running it against a shared folder.
+
+`upgrade`'s response echoes the *requested* version without re-reading. Call `list` to prove the move landed.
+
+### DeploymentName vs DeploymentTitle
+
+Distinct fields. Confusing them is the failure mode this command split exists to prevent.
+
+- `--title` sets `DeploymentTitle` — free-form, returned verbatim.
+- `DeploymentName` is the name the **runtime** resolves: the backend slugs the title and appends a per-deployment suffix (`invoices` → `invoices-08963f00-ixp`).
+- The suffix is generated per deployment and **cannot be predicted from the request** — two deployments of the same project in the same folder get different suffixes, and it matches neither the project name's suffix nor the folder key. Read `DeploymentName` off the create response or from `list`; never construct it.
+- A deploy with no `--title` still gets its own suffix. `DeploymentName` is never just the project name.
+- When `create` returns `DeploymentName: null` (the backend had not yet listed the new deployment), get it from `list`.
+- `upgrade` takes `DeploymentName`. Passing a title lands a `404 [DeploymentNotFoundError]`.
+
+### --folder-key
+
+Required on both `create` and `upgrade`; passed in the body, never as a path. The same name can be deployed in several folders, so the folder is part of the deployment identity — there is no tenant-level or default-folder deploy. Get keys from `uip or folders list --output json`. There is no `--folder-path` form, and the key format is not validated client-side (the backend owns what a valid key is), so a malformed key fails server-side.
+
+Omitting either required option fails locally with exit `3` / `Result: ValidationError` before any auth or backend call. `--version 0` is valid — versions are 0-based.
+
+### Deployment errors
+
+| Surfaced error | Meaning | Fix |
+|---|---|---|
+| `409 [DeploymentAlreadyExistsError]` on `create` | The title is already deployed in that folder on a **different** version | Run `upgrade` with the `DeploymentName` from `list` — NOT the title the backend's message quotes |
+| `404 [DeploymentNotFoundError]` on `upgrade` | Name was never deployed, is deployed only in **another** folder, or a *title* was passed where `DeploymentName` belongs | Re-read `DeploymentName` from `list`; verify `--folder-key` |
+| `404 [ModelVersionNotFoundError]` on `upgrade` | `--version` is not deployable (the version is checked before the deployment is looked up) | Pick a version from `projects list-models <project-name> --output json` |
+| `408 Timed out waiting for new model version` on `upgrade` | Upstream IXP timeout. The CLI surfaces it without retrying, and the outcome is **unknown** — the write may or may not have landed | Run `list` and read the version actually being served before retrying. Do not assume either outcome |
+| `409 [AmbiguousDeploymentError]` | More than one deployment matches in the folder | Disambiguate from `list`; carries the same `create` hint as the conflict above |
+
+**Rejected writes are no-ops** — every `409`/`404` above leaves the deployment on its original version with `DeployedAt` untouched.
+
+**Do not branch on `ErrorCode` for these.** A `409` surfaces as `ErrorCode: invalid_argument`, because `400`/`409`/`422` map alike. Branch on `Context.HttpStatus` or the bracketed backend error name.
+
+**`upgrade` is not a rollback path.** Versions leave the deployable list as a project retrains, so a deployment can be serving a version it can no longer be moved back to. Verify the target is in `projects list-models` first.
+
+After a successful deploy, the folder-scoped runtime API takes roughly 15 seconds to resolve the new deployment. A runtime lookup immediately after `create` can miss it.

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

@@ -31,6 +31,8 @@ uip ixp labellings get-predictions <project-name> <document-id> --output json
 
 This returns `Data: { ProjectName, TotalDocuments, DocumentsWithPredictions, Predictions[] }`. Each `Predictions[]` entry is `{ DocumentId, Labels[] }` (for a single-document call, `Predictions[0]`). Each label is `{ Name, Occurrence, Fields[] }`, and each field has `FieldId`, `FieldName`, `FormattedValue`. `Occurrence` is the explicit 0-based index used for `--occurrence`/`--updates`, valid **for this read only** — see [Occurrence numbers are read-scoped](#occurrence-numbers-are-read-scoped).
 
+The response also carries `ModelVersion` — the model version that produced these predictions. Note it: pass it to `confirm --model-version` in step 2d so a retrain mid-review can't silently change the values `confirm` stamps.
+
 ### 2b. Download the document file
 
 - **If the file already exists** in `/tmp/ixp/<project-name>/docs/` from a previous session, reuse it — do NOT re-download.
@@ -89,12 +91,15 @@ For **NOT CONFIRMED** fields: state the predicted value, the actual value (if vi
 
 Submit confirmed, corrected, and missing fields for this document — all in one `confirm` call.
 
+**Pass the version you reviewed.** Add `-m <model_version>` (the `ModelVersion` from step 2a) to every `confirm` call below — the narrowed `--occurrence`/`--updates` forms included. If a retrain landed since you read the predictions, the confirm is rejected with `PredictionVersionChangedError` instead of stamping values you never saw — re-run step 2a, re-review this document, then confirm again.
+
 **If there are corrections:**
 
 ```bash
 uip ixp labellings confirm <project-name> <document-id> \
   --fields "<all_submitted_ids>" \
   --corrections '[{"field_id":"<id>","value":"<corrected_value>"}]' \
+  -m <model_version> \
   --output json
 ```
 
@@ -104,13 +109,13 @@ The `--fields` list includes CONFIRMED, CORRECTED, and MISSING field IDs togethe
 
 ```bash
 uip ixp labellings confirm <project-name> <document-id> \
-  --fields "<field_id_1>,<field_id_2>,<field_id_3>" --output json
+  --fields "<field_id_1>,<field_id_2>,<field_id_3>" -m <model_version> --output json
 ```
 
 If ALL predicted fields for a document are correct with no corrections needed, you can omit `--fields` to confirm every predicted field on **that one document** in a single call:
 
 ```bash
-uip ixp labellings confirm <project-name> <document-id> --output json
+uip ixp labellings confirm <project-name> <document-id> -m <model_version> --output json
 ```
 
 This per-document form is fine **once you've reviewed the document and every field is correct** (2c). What you must NOT do is run `confirm` **without a `<document-id>`** — that confirms every document in the project at once, bypassing the per-document review loop. Confirming unreviewed predictions bakes wrong values into the labels, and because F1 compares predictions against those labels, **the metric reports 1.00 even when the confirmed values are wrong**. F1 alone is never evidence the values are correct.
@@ -121,6 +126,7 @@ This per-document form is fine **once you've reviewed the document and every fie
 uip ixp labellings confirm <project-name> <document-id> \
   --fields "<confirmed_id>,<corrected_id>,<missing_id_1>,<missing_id_2>" \
   --corrections '[{"field_id":"<corrected_id>","value":"<corrected_value>"}]' \
+  -m <model_version> \
   --output json
 ```
 
@@ -133,11 +139,11 @@ Use `labellings mark-missing <project-name> <document-id> --fields <ids>` to rec
 ```bash
 # All predicted fields in occurrence 0:
 uip ixp labellings confirm <project-name> <document-id> \
-  --group "Line Items" --occurrence 0 --output json
+  --group "Line Items" --occurrence 0 -m <model_version> --output json
 
 # Just Quantity in occurrence 2:
 uip ixp labellings confirm <project-name> <document-id> \
-  --group "Line Items" --occurrence 2 --fields c4e1907a3b8f25d6 --output json
+  --group "Line Items" --occurrence 2 --fields c4e1907a3b8f25d6 -m <model_version> --output json
 ```
 
 Occurrences not targeted carry forward whatever annotation they already had (so wrong predictions in untouched occurrences stay unannotated).
@@ -147,6 +153,7 @@ Occurrences not targeted carry forward whatever annotation they already had (so
 ```bash
 uip ixp labellings confirm <project-name> <document-id> \
   --group "Line Items" --updates '[{"occurrence":0},{"occurrence":2,"fields":["c4e1907a3b8f25d6"]}]' \
+  -m <model_version> \
   --output json
 ```
 
@@ -197,7 +204,7 @@ uip ixp documents delete <project-name> <document-id> -y --output json
 | You have | How to get the DocumentId |
 |----------|---------------------------|
 | Filename (e.g., `invoice-001.pdf`) | `uip ixp documents list <project-name> --output json --output-filter "Documents[?Filename=='invoice-001.pdf'].DocumentId \| [0]" --output plain` (rows are under `Documents` — the list is a paged envelope) |
-| A distinctive predicted field value (e.g., Invoice Number `MSI0601020`) | Run `uip ixp labellings get-predictions <project-name> --output json`, find the entry in `Predictions[]` whose `Labels[].Fields[].FormattedValue` matches, take its `DocumentId` |
+| A distinctive predicted field value (e.g., Invoice Number `MSI0601020`) | `uip ixp documents list <project-name> --output json` for the ids, then `uip ixp labellings get-predictions <project-name> <document-id> --output json` per id until a `Labels[].Fields[].FormattedValue` matches. One call per document, so stop at the first match. |
 | Nothing — need to find by content | `uip ixp documents list <project-name> --output json`, then `documents download` candidates and read with the Read tool |
 
 `documents list` returns `Filename` alongside `DocumentId` (the original upload filename, or `null` if none was sent at upload time). When filenames aren't unique within the project, the JMESPath filter returns multiple IDs — review them with `documents download` before deleting.