git:20260827.30a14f8 to git:20260902.c78a25d

---

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, 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

Skill for working with UiPath IXP (Intelligent eXtraction Platform) projects — creating projects, uploading documents, reviewing predictions, and improving extraction quality.

## When to Use This Skill

- User asks to create an IXP project, upload documents, or train a document extraction model

- 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>`)

## When NOT to Use This Skill — defer to uipath-maestro-flow

This skill covers standalone IXP-project work. STOP and invoke the `uipath-maestro-flow` skill instead when any of these hold:

- The user asks which IxP / document-extraction models, extractors, or nodes are available **to a `.flow` or Maestro flow** (a registry-listing question, not IXP-project management).

- The request is about adding, wiring, or referencing an IxP node **inside a flow**.

- The working context is a `.flow` file or a Maestro flow rather than a standalone IXP project.

Do not answer these from this skill. Re-activate `uipath-maestro-flow` and follow the commands it documents. This overrides Critical Rule 1.

## Critical Rules

1. **Verify `uip ixp` syntax before running a command** — use a targeted lookup in [CLI Reference](references/cli-reference.md) and copy the exact subcommand and options; never guess. If the request is not covered, report that the skill has no documented CLI path rather than improvising. Do NOT use curl, call REST APIs directly, or explore source code. (Exception: defer flow/Maestro registry questions to `uipath-maestro-flow` — see *When NOT to Use This Skill* above.)

2. **Run workflows end-to-end automatically** — do NOT ask the user to do individual steps.

3. **Always use `--output json`** when parsing CLI output programmatically.

4. **Use `/tmp/ixp/<project-name>/` as the working directory with this structure:**

```

/tmp/ixp/<project-name>/

├── docs/ # Document files (<document-id>.pdf, .png, …) — downloaded once, reused across sessions

├── taxonomies/ # Taxonomy snapshots (v1.json, v2.json, …) — new version after each update-prompts

└── prompts/ # Instruction update payloads (field_updates.json, group_updates.json, …)

```

At the start of any workflow: `mkdir -p /tmp/ixp/<project-name>/{docs,taxonomies,prompts}`. If the directory already exists from a previous session, **reuse existing files** — do not re-download documents that are already present. Do NOT use the Write tool for `/tmp/ixp/` paths — on Windows it resolves to a different location than bash.

5. **Use heredocs for `--updates`** — for `fields update-prompts --updates` and `groups update-prompts --updates`, use heredocs (`cat > /tmp/ixp/<project-name>/prompts/field_updates.json << 'EOF' ... EOF`) then `"$(cat /tmp/ixp/<project-name>/prompts/field_updates.json)"`.

6. **Never use `UID` as a variable name** — it is a readonly shell variable. Use `DOC_ID`, `DOCUMENT_ID`, etc.

7. **Always use the project `Name`, never the `Title`** — the `project list` output has both `Name` (e.g., `my_invoices-f1afa9ef-ixp`) and `Title` (e.g., `My_Invoices`). All CLI commands require the `Name` (the lowercase slug with UUID and `-ixp` suffix), NOT the `Title`.

8. **Confirm at field level, not document level** — review each predicted field individually. Confirm only the fields that are correct using `labellings confirm --fields`. **Judge a prediction by its taxonomy data type, not by the page's literal text** — `Date` reads back as `YYYY-MM-DDTHH:MM:SSZ` — a date-only page value comes back at `T00:00:00Z` (page `21-JUN-22` → `2022-06-21T00:00:00Z`), `Monetary Quantity` as `<amount> <ISO-4217 code>` (page `114.91` → `114.91 AUD`). Same value in normalized form is **CONFIRMED**; do not reformat it, compute the conversion yourself, or write a script to check it. Full mapping: [CLI Reference § Normalized output formats](references/cli-reference.md#normalized-output-formats). **Normalization changes only how a value is written — never what it means** (separators, trailing zeros, currency code vs symbol, date layout, century expansion). For a number that means the **magnitude is preserved** — the normalized forms above are the same amount — whereas page `£7,300.00` predicted as `£730.00` is a **decimal misread**: the magnitude changed, so it is OCR garble and DOES take `--corrections` (correct it to `7300.00`). Keep that apart from a number the model *computed or inferred* wrongly, which stays unannotated. **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, a normalized date or amount you want back in the page's format, or any value where the prediction picked the wrong answer — then `--corrections` is FORBIDDEN; leave the field unannotated. Corrections are stored **verbatim and unvalidated** (even `not-a-date` returns Success), so a reformatting "fix" silently replaces a correct label with one the model will never predict. 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. **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` — 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` is the group's `Name` copied **verbatim** from `get-predictions` (e.g. `"Line Items"`) — never a name you assembled yourself. 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 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).

21. **`get-metrics` defaults to LATEST, not LIVE — always name the version you report.** A project keeps accumulating trained versions long after its live one was pinned, and the latest can score *worse* than what's deployed — so a bare `get-metrics` pairs the latest version's numbers with the live version identity you read from `list-models`. Resolve the version FIRST (`list-models` → `Tags[]` Name=`live`, else highest `Models[]` `Pinned: true`, else latest), pass it as `get-metrics --model-version <N>`, and state which version the scores belong to.

## Quick Start

1. Run `uip ixp projects list --output json` to see existing projects

2. To create a new project: follow [Project Setup Guide](references/project-setup-guide.md)

3. To improve an existing project: follow [Improve Prompts Guide](references/improve-prompts-guide.md)

4. To label documents on an existing project: follow [Label Documents Guide](references/label-documents-guide.md)

If the user provides a taxonomy file, use `--skip-taxonomy` and `import-taxonomy` (Option B in the Project Setup guide).

## Task Navigation

| User request | Action |

|-------------|--------|

| "Create an IXP project" / "Upload documents to a new project" | [Project Setup Guide](references/project-setup-guide.md) — **new** projects only (uploads + taxonomy in one call). For **existing** projects, see the "Upload a document" row below. |

| "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** — publish pins the version, and `--tag` moves the `live`/`staging` tag, which selects the version the DU framework serves (including to DU activities that call through it). Callers that resolve models from an Orchestrator folder — Maestro Flow among them — see only `deployments create` (the "Deploy this model to a folder" row below). 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** — when the user names a folder instead of giving its key, resolve the name through that same `folders list`; ask only when no folder was identified at all. `--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> --model-version <N> --output json` — **always name the version.** Without `--model-version` the CLI returns the **latest trained** version, which is not necessarily the published/live one; get the live version from `list-models` first (see "How is this project performing?"). |

| "List projects" | `uip ixp projects list --output json` |

| "Configure the model" | `uip ixp projects configure-model <project-name> [options] --output json` |

| "What model / pre-processing does this project use?" / "Query the model settings" | `uip ixp projects get-taxonomy <project-name> --output json` — the configured extraction model and pre-processing are under `Data.dataset._model_config`: `model_version` is the `--model` value (e.g. `gemini_2_5_flash`), and `input_config` must be inverted to the `none`/`table_mini`/`table` token (`null` = not configured, so report the project default — **not** `none`). There is **no `get-model-config`**, and `configure-model` is a read-modify-write: never call it to find out the current settings, it rewrites them. Do NOT answer from `list-models`' `ModelName` — that's the labeller family (`gemini_ixp`), not a `--model` value, and it says nothing about pre-processing. Inversion table: [CLI Reference § Reading the current model and pre-processing](references/cli-reference.md#reading-the-current-model-and-pre-processing). |

| "Delete a project" / "Remove this project" | `uip ixp projects delete <project-name> -y --output json` — **permanent and irreversible**; removes the project's documents, taxonomy, and trained models. Requires `-y/--yes` (the CLI never prompts). |

| "Upload a document" / "Add documents to an existing project" | `uip ixp documents upload <project-name> <file> --output json` — see [CLI Reference § Uploading documents](references/cli-reference.md#uploading-documents-to-an-existing-project). One file per call; loop for multiple. For brand-new projects use `projects create` instead. |

| "Delete a document" / "Remove a document" | `uip ixp documents delete <project-name> <document-id> -y --output json` — irreversible, triggers retrain. `-y/--yes` is required (the CLI never prompts). To delete by filename, look up the `DocumentId` via `documents list` (the `Filename` field shows the original upload name). |

| "Add / delete / rename a field group" | `uip ixp groups {add,delete,rename} <project-name> --name <name> ... --output json` — see [CLI Reference § Groups](references/cli-reference.md#groups). `groups add` requires `--instructions` and `--fields '<json>'` — pass **all** of the new group's fields in that one `--fields` array (batch); do NOT create the group then add fields one at a time (use `fields add` only for an already-existing group). `delete` requires `-y/--yes` (the CLI never prompts). |

| "Add / edit / rename / delete a data type" | `uip ixp data-types {add,update-instructions,rename,delete} <project-name> --name <name> ... --output json` — see [CLI Reference § Data Types](references/cli-reference.md#data-types). `add` requires `--kind` (text/date/money/number/boolean/choice) and `--instructions`. `--input-value` (exact-match/inferred) is required only for `--kind text` and `--kind choice`; the other kinds don't have this property and the CLI rejects the flag for them. `delete` requires `-y/--yes` (the CLI never prompts); deleting a data type breaks any field referencing it. **Reuse a default data type before adding a custom one (Critical Rule 17)** — most needs map to a built-in (e.g. currency → `Monetary Quantity`). |

| "Add / delete / rename / retype a field" | `uip ixp fields {add,delete,rename,change-type} <project-name> --group <name> --field <name> ... --output json` — see [CLI Reference § Fields](references/cli-reference.md#fields). `delete` requires `-y/--yes`; `change-type` deletes annotations and also requires `-y/--yes`. |

| "Move a field to another group" / "this field belongs under X" | There is **no move command** — `--group` addresses a field, it never reparents one. Read the field's `type` and `instructions` from `projects get-taxonomy`, then `fields add` into the target group, then `fields delete <source> -y`. **Add before deleting**, so a failed add leaves the field where it was. Both groups must already exist; a move never creates one. **IRREVERSIBLE** — the recreated field gets a new `field_id`, so its confirmed labels do NOT follow it; say so before starting. **Never move a field via `get-taxonomy` → edit → `import-taxonomy`**: the import *merges*, so the field ends up in **both** groups. Full recipe: [CLI Reference § Moving a field](references/cli-reference.md#moving-a-field-to-a-different-field-group). |

| "Fix an OCR-garbled value" / "Confirm with a correction" | `uip ixp labellings confirm <project-name> <document-id> --fields <ids> --corrections '[{"field_id":"<id>","value":"<fixed>"}]' --output json` — confirms the listed fields and records the corrected value for the garbled one (include the corrected field's id in `--fields`). **`--corrections` is only for OCR garble** — the prediction is already the right answer in the right location, merely misread (e.g. `MSIÓÓÓ601020/` → `MSI0601020`); never use it to flip a wrong prediction, that field stays unannotated (Critical Rule 8). For one occurrence of a repeatable group add `--group <name> --occurrence <N>`; in the batched `--group <name> --updates '[…]'` form each entry takes `"corrections": {"<field_id>": "<value>"}` (an object keyed by field id, not the flat array). See [CLI Reference](references/cli-reference.md#labellings). |

| "Mark a field as missing for a document" | `uip ixp labellings mark-missing <project-name> <document-id> --fields <ids> --output json` — marks the listed fields missing; use when a field is genuinely absent and IXP predicted no value for it. Listing the field in `labellings confirm --fields` records the same missing marker when the field appears in predictions with an empty value. **Only mark a field missing if IXP also predicted nothing for it** — never to override a wrong prediction. See Critical Rule 12. |

| "Undo / unconfirm a wrong confirmation" | `uip ixp labellings unconfirm <project-name> <document-id> --fields <ids> --output json` — rolls back an earlier `confirm` or `mark-missing` for the listed fields (`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 roll back specific occurrences, add `--group` with `--occurrence <N>` or `--updates '[…]'` (mirrors `confirm` — see the row below and Critical Rule 14). |

| "Confirm one line item / extraction" / "Confirm only this occurrence" | `uip ixp labellings confirm <project-name> <document-id> --group <name> --occurrence <N> [--fields <ids>] --output json` — targets one specific extraction of a repeatable field group (0-based index **from the latest `get-predictions`**). Without `--fields`, confirms every predicted field in that occurrence; with `--fields`, only those. Other occurrences untouched. Confirming renumbers the group on the next read (the confirmed row moves to `Occurrence` 0) — so batch multiple occurrences into one `--updates '[…]'` call rather than chaining `--occurrence` calls off a single read. See Critical Rules 13 and 18. |

| "Unconfirm one line item / extraction" / "Roll back only this occurrence" | `uip ixp labellings unconfirm <project-name> <document-id> --group <name> --occurrence <N> [--fields <ids>] --output json` — rolls back one specific extraction of a repeatable field group (0-based index, same as `get-predictions`/`confirm`). Without `--fields`, unconfirms every annotated field in that occurrence; with `--fields`, only those. Other occurrences untouched. **Re-read `get-predictions` first** — on a partly-confirmed group the confirmed rows sort to the front, so the index that confirmed a row is usually not the index that rolls it back (Critical Rule 18). For several occurrences in one call, use `--updates '[…]'` instead. See Critical Rule 14. |

| "Set overall extraction instructions" / "Update project prompt" | `uip ixp projects update-prompt <project-name> --prompt "<text>" --output json` — replaces the taxonomy-wide prompt (the "Overall extraction instructions" field in the IXP UI). Distinct from `fields update-prompts` (per-field) and `groups update-prompts` (per-field-group). |

| "How is this project performing?" / "What's the F1?" | Resolve the live version with `uip ixp projects list-models <project-name> --output json`, then `uip ixp projects get-metrics <project-name> --model-version <live-version> --output json` (Critical Rule 21). If Data is `{ Metrics: null }` the model isn't validated yet — report that and stop. If the call instead returns `Result: Failure` with `ErrorCode: not_found` (a project with no trained model yet, e.g. no confirmed labellings), treat it the same way — report "no metrics yet" and stop. Otherwise Data is flat; report in order: (1) which version the scores belong to + `TrainedTime`; (2) overall `ProjectScore`/`ProjectScoreQuality`; (3) per-group scores from `FieldGroups[]` (F1/Precision/Recall); (4) per-field scores from `Fields[]`, sorted lowest-F1 first — F1 **with** its `Precision`/`Recall` (a low F1 means the opposite fix depending on which side is short), plus `Annotations` (the sample size behind the F1) and `ErrorRate` (= errors/`Annotations` — it counts misses, so it is **not** `1 - Precision`). Ignore the `Quality` labels (derived, inconsistent scales — [Improve Prompts Guide § What get-metrics returns](references/improve-prompts-guide.md#what-get-metrics-returns-and-which-values-decide)). State numbers plainly; no "good enough" judgement unless asked; route low scores to [Improve Prompts Guide](references/improve-prompts-guide.md). Answer from these calls only — no ad-hoc discovery (Critical Rule #1). |

| "Describe this project" / "What's in it?" | Three calls, reported in order: (1) identity — `Title`/`Name` from `uip ixp projects get <project-name> --output json`; (2) current model **version** — live/published + `TrainedTime` from `list-models` (the trained version, not the configured extraction model — for that see the row above); (3) taxonomy — label-group/field counts from `uip ixp projects get-taxonomy <project-name> --output json` (raw artifact: counts live under `Data.dataset.label_groups` and `Data.dataset.entity_defs`, snake_case). Fold in performance (above) only if asked. Do NOT page `documents list` (its `Data` is a paged `{ Documents, Total, Offset, Limit }` envelope — use `Total` for a count) or read deployment bindings. Answer from these calls only (Critical Rule #1). |

## Common Pitfalls

| Symptom | Cause | Fix |

|---------|-------|-----|

| Reported score doesn't match what the IXP UI's build page shows | `get-metrics` was called without `--model-version`, so it returned the **latest trained** version while the UI (or your own sentence) named the **live** one | Resolve the version from `list-models` and re-run `get-metrics --model-version <N>`. A project whose live version was pinned a while ago can have many newer trained versions, and the latest may score lower. See Critical Rule 21. |

| Metrics don't change after a prompt update | Re-evaluation hasn't completed | Wait out the retrain — [Improve Prompts Guide § Waiting for retrain](references/improve-prompts-guide.md#waiting-for-retrain). |

| ModelVersion doesn't advance | Retrain still in progress | Any change to model inputs (labellings OR instructions) triggers a full retrain. Re-read metrics under the **bounded** wait in [Improve Prompts Guide § Waiting for retrain](references/improve-prompts-guide.md#waiting-for-retrain) — fixed interval, capped number of checks, then stop. Never poll indefinitely. |

| Field instructions conflict with label_def instructions | `fields update-prompts` only edits per-field instructions, NOT the parent label_def instructions | Before iterating, read the label_def `instructions` and update them with `groups update-prompts` if they contradict the per-field prompts. |

| A confirmed line item now reads back as the first row, or the other rows' `Occurrence` numbers shifted | Expected: the read returns annotation↔prediction matched pairs first, so confirmed rows sort ahead of unconfirmed ones | Nothing to fix — values and page locations are unchanged. Re-run `get-predictions` before the next per-occurrence call and target the row by its values (Critical Rule 18). |

| A second `--occurrence` call landed on the wrong row, or `unconfirm --occurrence N` no-ops | Indices came from a read taken *before* an earlier confirm renumbered the group | Re-read `get-predictions` between per-occurrence writes, or issue them as one `--updates` call. |

| `deployments create` returns `409` | That title is already deployed in that folder on a different version — `create` only ever ADDS | Use `deployments upgrade <project-name> <deployment-name>` instead, taking `<deployment-name>` from `deployments list` (Critical Rule #20). |

| `deployments upgrade` returns `404` | A `DeploymentTitle` was passed where `DeploymentName` is expected — the name is slugged and suffixed (`invoices` → `invoices-08963f00-ixp`), so it cannot be derived from the title | Run `deployments list <project-name> --output json` and pass its `DeploymentName` verbatim. |

## Unsupported Capabilities

These requests fall outside the skill. Recognise the request, reply with the standard response, route the user. Do NOT enter discovery (`uip --help`, grep, source reading) — see Critical Rule #1.

| User request | Standard response |

|--------------|-------------------|

| "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." |

| "Push to an environment / another tenant" / "deploy to staging or production" | **Names an Orchestrator folder (a folder literally called `Production`) →** supported; use the "Deploy this model to a folder" row in [Task Navigation](#task-navigation). **Otherwise →** "IXP has no environment or cross-tenant deploy target — a deployment is a (folder, version) pair inside one tenant." Note `projects publish --tag staging\|live` moves the tag the DU framework (and DU activities calling through it) resolve — for those consumers that IS the staging/live switch; it creates no folder deployment. |

| "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." |

| "Monitor the deployed model" / "how many docs did it process?" / "runtime throughput or incidents" | "Runtime/operational monitoring of a deployed model lives in Orchestrator, not this skill: https://docs.uipath.com/orchestrator/automation-cloud/latest/user-guide/about-monitoring. For design-time scores use `get-metrics` (see 'Show metrics')." |

| "Edit a data type's values" / "add or remove a Choice option" | "The CLI can rename a data type, change its instructions (`data-types update-instructions`), or delete it — but it can't add or remove the **values** of an existing Choice data type. Do that by hand in-product on the Manage Taxonomy page: https://docs.uipath.com/ixp/automation-cloud/latest/user-guide/managing-projects — then continue here." |

## Reference Navigation

- [CLI Commands Reference](references/cli-reference.md) — all `uip ixp` commands with options and output formats

- [Project Setup Guide](references/project-setup-guide.md) — create a new project, review and label documents

- [Improve Prompts Guide](references/improve-prompts-guide.md) — iterative optimization loop with regression detection

- [Label Documents Guide](references/label-documents-guide.md) — reusable workflow for reviewing and confirming predictions