@uipath/skills 1.195.0

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

@@ -0,0 +1,113 @@
+# CLI Commands Reference
+
+All commands use `uip ixp` prefix. Always append `--output json` when parsing output programmatically.
+
+## Projects
+
+| Command | Description |
+|---------|-------------|
+| `uip ixp projects list --output json` | List all IXP projects |
+| `uip ixp projects get <project-name> --output json` | Get a project |
+| `uip ixp projects create "<name>" <folder-path> [-d "<description>"] [--skip-taxonomy] --output json` | Create project and upload supported docs in `<folder-path>` (top-level only — sub-folders are not scanned; see [Supported document files](#supported-document-files)). By default suggests+imports taxonomy. `-d` provides context for better taxonomy suggestion. Use `--skip-taxonomy` to create a blank project (import taxonomy separately). Use `ProjectName` from output. |
+| `uip ixp projects import-taxonomy <project-name> <file> --output json` | Import taxonomy from a local JSON file. Accepts `{ field_types, label_group }` or `{ entity_defs, label_groups }` format. |
+| `uip ixp projects update-title <project-name> "<new-title>" --output json` | Update the display title of a project |
+| `uip ixp projects update-prompt <project-name> --prompt "<text>" --output json` | Update the project's **Overall extraction instructions** — the taxonomy-wide prompt the model sees on every extraction (the field at the top of the IXP UI's Manage Taxonomy page). Distinct from per-field-group prompts (`groups update-prompts`) and per-field prompts (`fields update-prompts`). Replaces the existing value. |
+| `uip ixp projects get-taxonomy <project-name> --output json` | Get taxonomy (entity_defs + label_groups with field definitions) |
+| `uip ixp projects get-metrics <project-name> --output json` | Get validation metrics — `FieldGroups[]` (per-group) and `Fields[]` (per-field F1/Precision/Recall) |
+| `uip ixp projects configure-model <project-name> [options] --output json` | Configure extraction model. Options: `--model` (gemini_2_5_flash/gemini_2_5_pro/gpt_4o_2024_05_13) and `--preprocessing` (none/table_mini/table). |
+| `uip ixp projects list-models <project-name> --output json` | List all model versions and tags. Returns `Models[]` (Version, Pinned, TrainedTime) and `Tags[]` (Name, Version). |
+| `uip ixp projects publish <project-name> --output json` | Publish (pin) the latest model version. Options: `--model-version <N>` (specific version, default: latest), `--description "<text>"` (set description), `--tag <name>` (assign tag: "live", "staging", or custom). |
+
+## Documents
+
+| Command | Description |
+|---------|-------------|
+| `uip ixp documents list <project-name> [-l <limit>] [--offset <n>] --output json` | List documents — returns `[{ DocumentId, AttachmentRef, Filename }]`. `Filename` is the original upload filename. Paginated: defaults to 50 items per page (max 10000). Pass `-l` for larger pages or `--offset` to skip ahead. |
+| `uip ixp documents download <project-name> <document-id> -o <path> --output json` | Download the original document file (PDF/PNG/JPG/etc.). The CLI auto-corrects the file extension to match the actual content; use the response `Path` field as the resolved location. |
+| `uip ixp documents upload <project-name> <file> --output json` | Upload a single document file to an existing project. See [Uploading documents](#uploading-documents-to-an-existing-project) below for validation, output shape, and the multi-file loop pattern. |
+| `uip ixp documents delete <project-name> <document-id> --output json` | Delete a document (and its labellings) from a project. Irreversible — triggers a retrain. |
+
+### Supported document files
+
+Both `projects create` (bulk folder upload) and `documents upload` (single file) validate against the same extension whitelist, case-insensitive:
+
+`.pdf`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.tif`, `.tiff`, `.bmp`
+
+Validation differs by command:
+
+- `documents upload` rejects an unsupported file with `Unsupported file type "<ext>"` before any network call.
+- `projects create` scans only the top level of `<folder-path>` (sub-folders are ignored), silently skips unsupported files, and fails only when **no** supported files exist (`No supported documents found in <folder>`).
+
+Each upload triggers a retrain — wait ~2 min before reading metrics or predictions for new docs.
+
+### Uploading documents to an existing project
+
+`uip ixp documents upload <project-name> <file> --output json` pushes one document to an existing project.
+
+For supported extensions, validation error strings, and retrain timing, see [Supported document files](#supported-document-files) above.
+
+Returns `{ ProjectName, FileName, AttachmentRef, DocumentId }` (Code: `IxpDocumentsUpload`). Capture `DocumentId` for later `documents download` or `labellings confirm` calls.
+
+**Multiple files** — one file per call; loop the command:
+
+```bash
+cd "<folder-with-docs>"
+for f in *.pdf *.png *.jpg *.jpeg *.gif *.tif *.tiff *.bmp; do
+    [ -e "$f" ] || continue   # skip unmatched glob patterns
+    uip ixp documents upload <project-name> "$f" --output json
+done
+```
+
+**When NOT to use this:** for filling a brand-new project, prefer `projects create <name> <folder-path>` — uploads the whole folder and suggests a taxonomy in one call.
+
+## Data Types
+
+Manage the reusable type definitions (entity_defs) that fields reference via `field_type_id`. In the IXP UI, these are the project's "Data Types".
+
+| Command | Description |
+|---------|-------------|
+| `uip ixp data-types add <project-name> --name <name> --kind <text\|date\|money\|number\|boolean\|choice> --instructions <text> [--input-value <exact-match\|inferred>] [--choices <json>] --output json` | Create a new data type. `--kind` selects the underlying data shape; `text` is the default Text type. `--input-value` is **required for `--kind text` and `--kind choice`, forbidden for `date`, `money`, `number`, and `boolean`** — those kinds don't expose the "Exact match" / "Inferred" radio in the IXP UI, so the CLI rejects the flag when the kind doesn't support it. `exact-match` marks the value as appearing verbatim in the document; `inferred` is for computed/derived values that don't have a visible location. `--choices` is **required when `--kind choice`** and forbidden otherwise. JSON array of `{"value":"<canonical>","alternates":["<alt1>",...]}`; `value` is the canonical display name (model output); `alternates` is optional (defaults to `[]`) and lists alternate spellings the model maps to `value`. |
+| `uip ixp data-types update-instructions <project-name> --name <name> --instructions <text> --output json` | Replace the instructions on an existing data type. Name, kind, and input-value stay the same. |
+| `uip ixp data-types rename <project-name> --name <name> --new-name <name> --output json` | Rename a data type. Existing field references (via `field_type_id`) stay intact. |
+| `uip ixp data-types delete <project-name> --name <name> --confirm-data-loss --output json` | Delete a data type. **IRREVERSIBLE** — any field referencing it via `field_type_id` will break. `--confirm-data-loss` is required. |
+
+## Groups
+
+Manage field groups (label_defs) — the document type containers for fields. To edit fields **inside** an existing group, use the `fields` subject below.
+
+| Command | Description |
+|---------|-------------|
+| `uip ixp groups add <project-name> --name <group-name> --instructions <text> --fields <json> --output json` | Create a new field group with instructions and at least one field. `--instructions` describes what document/section the group covers (the model sees it during extraction). `--fields` is a JSON array `[{"name":"...","type":"<type-name>","instructions":"..."}]` (1-32 entries); every entry must include `name`, `type`, and a non-empty `instructions`. `type` resolves against the project's `entity_defs`. |
+| `uip ixp groups delete <project-name> --name <group-name> --confirm-data-loss --output json` | Delete a field group. **IRREVERSIBLE** — deletes all annotations on all fields in the group. `--confirm-data-loss` is required. |
+| `uip ixp groups rename <project-name> --name <group-name> --new-name <name> --output json` | Rename a field group. Preserves all fields and annotations. |
+| `uip ixp groups update-prompts <project-name> --updates <json> --output json` | Bulk-update field group (label_def) instructions. `--updates` is a JSON array `[{"name":"<group>","instructions":"..."}]` matched by group name. Existing fields are preserved. Unmatched names are reported in the response without failing the command. |
+
+## Fields
+
+Structural edits to a field within an existing field group. For instruction-only edits use `fields update-prompts` (see below). To create the group itself, use `groups add` above.
+
+| Command | Description |
+|---------|-------------|
+| `uip ixp fields add <project-name> --group <field-group-name> --field <name> --type <type-name> --instructions <text> --output json` | Add a new field to an **existing** field group. `--type` is the name of an entity_def in the project's taxonomy (see `projects get-taxonomy`). `--instructions` is required — describe what to extract and where it appears. |
+| `uip ixp fields delete <project-name> --group <field-group-name> --field <name> --output json` | Remove a field from a field group. |
+| `uip ixp fields rename <project-name> --group <field-group-name> --field <name> --new-name <name> --output json` | Rename a field. Preserves `field_id` and existing annotations. |
+| `uip ixp fields change-type <project-name> --group <field-group-name> --field <name> --type <type-name> --confirm-data-loss --output json` | Change a field's type. **IRREVERSIBLE** — the server creates a new field under the hood, so all existing annotations for that field are deleted. `--confirm-data-loss` is required. |
+| `uip ixp fields update-prompts <project-name> --updates <json> --output json` | Bulk-update per-field extraction instructions. `--updates` is a JSON array `[{"name":"<field>","instructions":"..."}]` matched by `moon_form` field name (across all field groups). Existing field definitions are preserved. Unmatched names are reported in the response without failing the command. |
+
+## Labellings
+
+| 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 predicted labels with `FieldId`, `FieldName`, and `FormattedValue`. |
+| `uip ixp labellings confirm <project-name> <document-id> [--fields <ids>] [--corrections <json>] --output json` | Confirm predictions for a document. Without `--fields`, confirms every predicted field that has content. `--fields "id1,id2,id3"` 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> --field-group <name> --updates <json> --output json` | Per-occurrence confirm for a repeatable field group. Use when the field group has N occurrences on a document and you want to confirm only some of them (legacy `--fields` confirms a field_id across every occurrence). `--updates` is a JSON array `[{"occurrence":<0-based-index>,"fields":["<field_id>",…],"corrections":{"<field_id>":"<value>"}}]`; un-selected fields in a selected occurrence carry forward any existing annotation. Mutually exclusive with `--fields`/`--corrections`. |
+| `uip ixp labellings unconfirm <project-name> <document-id> --fields <ids> --output json` | Roll back confirmations on a document — the listed fields go back to un-annotated state. Use when an earlier `confirm` was a mistake. Every other annotation on the document is carried forward. Returns `Unmatched` for IDs that weren't annotated to begin with. |
+| `uip ixp labellings mark-missing <project-name> <document-id> --fields <ids> --output json` | Fallback for marking fields as missing **when `confirm --fields` is a no-op** — this happens when the field has a prior annotation but doesn't appear in the current prediction (model behavior or taxonomy changed between iterations). `confirm` only reaches fields in `fg.prediction.fields`; `mark-missing` also reaches fields in `fg.annotation.fields`, so it can overwrite a stale annotation with a missing marker. For the common case where IXP predicted an empty value, use `confirm --fields` instead. **Only use for fields where IXP itself predicted no value.** If IXP predicted a wrong value, leave the field unannotated instead. Returns `Unmatched` for any IDs not found in the document's annotation OR prediction. |
+
+## Deployments
+
+For working with runtime (deployed) IXP models — separate from the training workflow above.
+
+| Command | Description |
+|---------|-------------|
+| `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 the model version number from `projects list-models`. Output mirrors `projects get-taxonomy` — `EntityDefs[]` + `LabelGroups[]` — pinned to the snapshot the version was trained on. |

package/skills/uipath-ixp/references/improve-prompts-guide.md

@@ -0,0 +1,283 @@
+# Improve Prompts Guide
+
+Iterative optimization loop for improving extraction quality on an existing IXP project. Runs multiple iterations automatically, rolling back if scores regress.
+
+## What Prompts CAN and CANNOT Fix
+
+Before starting, understand the limits of prompt iteration:
+
+**Prompts CAN fix:**
+
+- Fields where the model extracts the wrong value (precision problems) — better instructions clarify what to extract
+- Fields where the model misses the value entirely (recall problems) — location hints help the model find the field
+- Ambiguous fields where the model picks the wrong candidate — negative examples and disambiguation rules help
+
+**Neither prompts nor reviewing can fix:**
+
+- **OCR quality issues** — if the OCR consistently garbles a field's text, no instruction will fix it. However, during the review step, OCR-mangled predictions can be corrected using `labelling confirm --corrections` (keeps the reference, fixes the text). If many fields are OCR-mangled across multiple documents, report this to the user as a data quality issue rather than burning prompt iterations.
+- **Missing fields** — if a field simply doesn't exist in the documents, no instruction will conjure it.
+
+## How prompt updates work
+
+Prompts live at two levels and are edited by two separate commands:
+
+- **`uip ixp fields update-prompts <project> --updates <json>`** — per-field instructions (e.g., "Invoice Number", "Invoice Date"). Match by field name.
+- **`uip ixp groups update-prompts <project> --updates <json>`** — field group (label_def) instructions (e.g., "Invoice", "Line Items"). Match by label_def name.
+
+Each command fetches the taxonomy, merges the supplied updates against the current state, and sends one wire call per affected label_def — preserving every definition you didn't change. When you need to update both fields and group instructions in the same iteration, run the two commands back-to-back.
+
+**Aligning group and field instructions.** Each label_def (e.g., "Invoice") has its OWN `instructions` field that the model sees alongside per-field instructions. If the group instruction says "Extract only fields visible on the first page" but a per-field instruction says "Found in the summary table on page 2", the model gets contradictory signals. When updating field instructions, also update the parent group instruction with `groups update-prompts` if it contradicts.
+
+## Before Starting
+
+The user may specify a max number of iterations (default: 3). Track:
+
+- **Baseline metrics** — the per-field F1 scores before any changes
+- **Previous iteration metrics** — the per-field F1 scores from the last successful iteration
+- **Previous instructions** — the per-field (field) instructions from the last successful iteration (for rollback)
+
+Do NOT re-read the taxonomy or sample documents between iterations — use what you already have. Only re-read metrics after each instruction update + retrain cycle. This assumes no one modifies the taxonomy or documents externally during the loop. If the user mentions changes were made in the web UI, re-fetch the taxonomy and document list before continuing.
+
+## Step 1 — Setup (once, before the loop)
+
+### 1a. Get baseline metrics
+
+If documents were just labelled (or uploaded, or the taxonomy was edited), wait ~2 minutes for the resulting retrain to complete before reading metrics. Reading mid-retrain captures *pre*-change scores and corrupts every downstream comparison.
+
+```bash
+mkdir -p /tmp/ixp/<project-name>/{docs,text,taxonomies,prompts}
+uip ixp projects get-metrics <project-name> --output json
+```
+
+Note the `ModelVersion` from this baseline read — later iterations check that it advances after each `fields update-prompts` / `groups update-prompts` (see step 2e). If the value here looks identical to a known pre-labelling version, the retrain may still be in flight; wait another 60 seconds and re-fetch.
+
+Save the full per-field `Fields` array as `baseline_metrics`. This is the starting point you compare against.
+
+**Correlating metrics to field names:** The metrics `Fields` array returns `FieldId` but not the field name. To map them, join against the taxonomy's `field` entries:
+
+- For each metric entry: `FieldGroup` = label_def name, `FieldId` = the field's `field_id`
+- Find the matching field entry in the taxonomy where `field_id == FieldId` — its `name` is the human-readable field name
+
+Build this mapping once and reuse it throughout the loop.
+
+### 1b. Check model configuration
+
+If many fields have low scores across the board, the model configuration may be wrong (e.g., no table pre-processing for table-heavy documents). View sample documents and check if the current config matches the document type. If not, reconfigure:
+
+```bash
+uip ixp projects configure-model <project-name> \
+  --model gemini_2_5_flash \
+  --preprocessing <none|table_mini|table> \
+  --output json
+```
+
+See the [Project Setup Guide](project-setup-guide.md) Step 2 for the decision table.
+
+### 1c. Get taxonomy
+
+```bash
+uip ixp projects get-taxonomy <project-name> --output json
+```
+
+Save to `/tmp/ixp/<project-name>/taxonomies/v1.json`. This includes `label_defs` with their fields and current `instructions`. These per-field instructions are what you'll be iterating on. Increment the version after each prompt update (v2, v3, …).
+
+The field `name` (e.g., `"Invoice Number"`, `"Description"`) is what you pass to `fields update-prompts --updates`.
+
+### 1d. Read sample documents (2-3 documents)
+
+```bash
+uip ixp documents list <project-name> --output json
+
+# For each sample document:
+uip ixp documents download <project-name> <document-id> -o /tmp/ixp/<project-name>/docs/sample --output json
+```
+
+The `download` command auto-detects format and appends the correct extension — read the resolved `Path` from the response. View the document with the **Read tool** (handles PDF, PNG, JPG, etc.). Files persist across sessions — check for existing files before downloading.
+
+### 1e. Check for unlabelled documents
+
+Compare the document list against the metrics. If the metrics show fewer `ValidatedDocuments` than the total document count, some documents have no confirmed labellings (e.g., newly added documents). Review and label them first using the [Label Documents Guide](label-documents-guide.md), then wait ~2 minutes for retrain and re-fetch metrics before starting the loop.
+
+---
+
+## Step 2 — Optimization Loop
+
+Repeat the following for each iteration (up to max iterations):
+
+### 2a. Diagnose fields and field groups
+
+Use the current metrics (baseline on first iteration, post-relabel metrics on subsequent iterations). The metrics include both `FieldGroups` (per-group scores) and `Fields` (per-field scores).
+
+**Field group diagnosis:** Check `FieldGroups` first. If an entire group has low F1, the group-level instructions may need updating with `--groups` rather than fixing individual fields.
+
+**Per-field diagnosis:** Identify individual fields with F1 < 0.7 as targets. Diagnose each:
+
+1. **Classify the action:**
+   - `Documents = 0` AND `F1 = 0` → **SKIP**
+   - `Documents < 1` → **SKIP**
+   - Otherwise → **REFINE**
+
+2. **Diagnose the problem type** (use F1 as primary signal with few documents):
+   - `Precision < Recall` significantly → **PRECISION** — model extracts wrong values
+   - `Recall < Precision` significantly → **RECALL** — model misses the field
+   - Otherwise → **BOTH** — rewrite entirely
+
+Print a diagnosis summary showing each field group's score and each field's name, F1, precision/recall, and diagnosis.
+
+If no fields need REFINE, stop — the project is already at target quality.
+
+### 2a-check. Check for labelling gaps (before writing instructions)
+
+For each REFINE field with **Recall < 0.5**, check whether the problem is a bad prompt or a missing label:
+
+1. Look at the sample document images you already have from Step 1d
+2. For each low-recall field, check: **can you see this field's value in the document?**
+   - If yes, the model may have predicted it correctly but it wasn't confirmed in a previous round → re-fetch predictions and review those fields again
+   - If the field is genuinely not visible in the document → it's a prompt/recall issue, handle with instruction changes
+
+**If you find previously skipped predictions that are actually correct**, confirm them now using `labelling confirm --fields` for those specific documents and fields. Wait ~2 minutes for retrain and re-fetch metrics before continuing.
+
+**If no labelling gaps are found**, proceed directly to writing instructions.
+
+### 2b. Write improved instructions
+
+For each field marked REFINE, rewrite its `instructions`:
+
+- **PRECISION** → Be more specific about WHAT to extract and what NOT to extract
+- **RECALL** → Better describe WHERE to find the field
+- **BOTH** → Full rewrite — what, where, what to avoid
+
+**Instruction quality standards:**
+
+Focus on **what** to extract and **where** to find it. Do NOT specify format — the entity_def (field type) already handles that.
+
+- **Minimum length**: 120+ characters. Short instructions like "Extract the date" are too vague.
+- **Location hint**: describe WHERE in the document (section, header area, table, near a label). Keywords: "section", "header", "table", "top of", "labeled", "near".
+- **Real example**: include an actual value from the documents (e.g., "Example: '2106732'", "Example: 'SINV0077023'").
+- **Disambiguation**: if similar fields exist, clarify what NOT to extract (e.g., "Do NOT confuse with PO Number").
+- **No format patterns**: do NOT include "Format: MM/DD/YYYY" or similar — the entity_def type (Date, Monetary, Text) already defines the format. Adding format in instructions creates conflicting signals.
+
+**Good instruction** (145 chars):
+> "The unique invoice identifier, found in the header area near the top-right, labeled 'Invoice #' or 'Invoice Number'. Example: '2106732'."
+
+**Bad instruction** (25 chars):
+> "Extract the invoice number"
+
+**For fields visible in documents** — include location and a real example from the actual documents.
+**For fields NOT visible** — use a generic instruction with no example: "Extract [what] from this document, as it appears on the page."
+
+**Additional rules:**
+
+1. NEVER reference specific page numbers — use section headings or labels
+2. Each instruction targets one specific field (e.g., "Invoice Number", "Invoice Date")
+3. On iteration 2+, do NOT repeat the same instruction that failed last time — try a different approach (different wording, different location hints, add negative examples)
+
+### 2c. Update instructions
+
+Use **field names** for `--fields` and **label_def names** for `--groups`:
+
+```bash
+cat > /tmp/ixp/<project-name>/prompts/field_updates.json << 'FIELDS_EOF'
+[
+  {"name": "Invoice Number", "instructions": "The unique document identifier, found in the header area top-right. Example: 2106732, QC006."},
+  {"name": "Invoice Date", "instructions": "The date the invoice was issued. Use the exact format as written in the document. Found near the invoice number."}
+]
+FIELDS_EOF
+
+uip ixp fields update-prompts <project-name> \
+  --updates "$(cat /tmp/ixp/<project-name>/prompts/field_updates.json)" \
+  --output json
+
+# If group instructions also need updating, run a second command.
+cat > /tmp/ixp/<project-name>/prompts/group_updates.json << 'GROUPS_EOF'
+[
+  {"name": "Invoice", "instructions": "General invoice header fields including number, dates, payment terms, and totals."}
+]
+GROUPS_EOF
+
+uip ixp groups update-prompts <project-name> \
+  --updates "$(cat /tmp/ixp/<project-name>/prompts/group_updates.json)" \
+  --output json
+```
+
+The second call is optional — skip it if the group instructions don't need changing.
+
+**Post-update verification:** After the update, re-fetch the taxonomy, save it as the next version, and verify that field counts per label_def are unchanged:
+
+```bash
+uip ixp projects get-taxonomy <project-name> --output json > /tmp/ixp/<project-name>/taxonomies/v<N>.json
+```
+
+Compare the number of fields in each updated label_def against the previous version. If any fields are missing, **STOP the workflow immediately** and report to the user — the taxonomy was corrupted and needs manual restoration. The previous taxonomy version has the old instructions for rollback.
+
+### 2d. Review and confirm predictions for all documents
+
+Wait ~2 minutes for the model to retrain with the updated instructions, then review predictions for all documents using the [Label Documents Guide](label-documents-guide.md). The updated prompts should produce better predictions — review each document's predictions against the actual content and confirm the correct ones. Documents with incorrect predictions are skipped (their old labels remain).
+
+### 2e. Wait and get new metrics
+
+Wait ~2 minutes for the model to retrain with the new labellings, then:
+
+```bash
+uip ixp projects get-metrics <project-name> --output json
+```
+
+If `ModelVersion` hasn't advanced since the last check, wait another 60 seconds and retry.
+
+### 2f. Compare and decide
+
+Compare the new per-field F1 scores against the **previous iteration** scores.
+
+**Selective regression check:** For each field you updated this iteration, check if F1 dropped by more than 0.1:
+
+- **Regressed fields** (F1 dropped >0.1): roll back ONLY those fields' instructions to the previous iteration's version. Keep the improved instructions for fields that gained or held steady.
+- **Improved/unchanged fields**: keep their new instructions.
+
+If any fields regressed, do a selective rollback:
+
+```bash
+# Only include the regressed fields, not the whole iteration
+cat > /tmp/ixp/<project-name>/prompts/rollback.json << 'FIELDS_EOF'
+[{"name": "Vendor Address", "instructions": "previous instruction for this field only"}]
+FIELDS_EOF
+
+uip ixp fields update-prompts <project-name> \
+  --updates "$(cat /tmp/ixp/<project-name>/prompts/rollback.json)" \
+  --output json
+```
+
+Wait ~2 minutes for retrain. On the next iteration, try a **different approach** for the regressed fields only (different wording, shorter instruction, fewer examples).
+
+**Rollback caveat:** Rollback restores the previous instructions but the model needs to retrain. Expect only **partial recovery** — prefer small-scope iterations (few fields at a time).
+
+**No regression:** Accept the iteration. Update `previous_metrics` and `previous_instructions` with the new values.
+
+**Stopping criteria — stop the loop if:**
+
+- All fields meet the user's target F1 (default: 0.7)
+- Max iterations reached
+- No fields improved in the last 2 consecutive iterations (diminishing returns)
+
+---
+
+## Step 3 — Final Report
+
+After the loop ends, print a summary:
+
+```text
+Optimization complete after N iterations.
+
+Field               | Baseline F1 | Final F1 | Change
+--------------------|-------------|----------|-------
+Invoice Number      | 0.450       | 0.820    | +0.370
+Description         | 0.300       | 0.650    | +0.350
+Bill-To Name        | 0.900       | 0.900    | (unchanged)
+Vendor Address      | 0.600       | 0.400    | -0.200 (rolled back)
+
+Overall project score: X.XX → Y.YY
+Iterations: N total, M with rollbacks
+Fields still below target (F1 < 0.7): [list]
+Labelling gaps fixed: [list any fields re-labelled in 2a-check]
+```
+
+If fields still need work, suggest the user run another round with more iterations.

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

@@ -0,0 +1,175 @@
+# Label Documents Guide
+
+Reusable workflow for labelling documents in an IXP project. Used by:
+
+- [Project Setup](project-setup-guide.md) — initial labelling after creating a project
+- [Improve Prompts](improve-prompts-guide.md) — reviewing predictions during optimization
+
+Claude acts as a **reviewer** — IXP generates predictions, Claude validates them field-by-field against the document. Only fields that are correct get confirmed. Fields that are wrong are left unannotated. Fields where the prediction found the right location but the value is OCR-mangled get corrected.
+
+## Step 1 — Get Documents and Taxonomy
+
+```bash
+mkdir -p /tmp/ixp/<project-name>/{docs,text,taxonomies,prompts}
+uip ixp documents list <project-name> --output json
+uip ixp projects get-taxonomy <project-name> --output json
+```
+
+Save the taxonomy to `/tmp/ixp/<project-name>/taxonomies/v1.json` (increment the version on each re-fetch).
+
+From the taxonomy, review the field groups and field types so you understand what each predicted field represents.
+
+## Step 2 — Process Each Document
+
+For each document from the list, process one at a time: get predictions, download image/text, review, confirm.
+
+### 2a. Get predictions for this document
+
+```bash
+uip ixp labellings get-predictions <project-name> <document-id> --output json
+```
+
+This returns the document's predicted `Labels` (grouped by field group name), each containing `Fields` with `FieldId`, `FieldName`, and `FormattedValue`.
+
+### 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.
+- **Otherwise, download:**
+
+```bash
+uip ixp documents download <project-name> <document-id> -o /tmp/ixp/<project-name>/docs/<document-id> --output json
+```
+
+Use the document ID as the filename. Pass `-o` **without an extension** — the CLI detects the actual format (PDF, PNG, JPG, …) from the file content and appends the correct extension. Read the resolved `Path` from the response and use that for the next step. Files persist across sessions — check for existing files before downloading.
+
+### 2c. Review predictions field-by-field
+
+Use the **Read tool** to view the document file (the Read tool handles PDF, PNG, JPG, etc. natively), then review each predicted field against the document:
+
+1. **Look at the document** to understand the layout and where field values appear.
+2. **For each predicted field**, assign one of four verdicts:
+   - **CONFIRMED** — the predicted value matches what is in the document. Minor OCR-level differences (capitalization, whitespace) are acceptable.
+   - **CORRECTED** — **OCR-mangled values only.** The prediction found the right field in the right location, the bytes-on-page are correct, but the text was garbled in transcription (e.g., `MSIÓÓÓ601020/` instead of `MSI0601020`, `lNGRAM` instead of `INGRAM`). The reference is correct, only the literal characters need fixing. Do NOT use CORRECTED for booleans that came back with the wrong answer, inferred/computed values that came back wrong, or any case where IXP picked the wrong source on the page — those are NOT CONFIRMED.
+   - **MISSING** — IXP predicted **no value** (empty `FormattedValue`) AND the field is genuinely absent from the document. Both conditions must hold. If IXP predicted a value but the field isn't actually in the document, that's NOT CONFIRMED, not MISSING — Critical Rule 12 forbids overriding a non-empty prediction with "missing".
+   - **NOT CONFIRMED** — the prediction is wrong for any reason other than OCR mangling. Covers: wrong literal value on the right field, wrong-source extraction, hallucinated value, boolean came back with the wrong answer, inferred/computed value came back wrong, predicted a value the document doesn't contain. Left unannotated. Do NOT try to "fix" these with `--corrections` — `--corrections` is OCR-only (see Critical Rule 8). Improve the prompt instead.
+3. **Report your verdict for every field.** Print a table per document:
+
+```text
+Document: <document-id>
+
+Field                    | Verdict       | Reason
+-------------------------|---------------|-----------------------------------------------
+Invoice Number           | CORRECTED     | OCR mangled "MSIÓÓÓ601020/" → "MSI0601020", top-right of page 1
+Invoice Date             | CONFIRMED     | Predicted "2018-02-28" matches document
+Vendor Address           | NOT CONFIRMED | Predicted "123 Main St" but actual is "456 Oak Ave", top-left of page 1
+Has Signature            | NOT CONFIRMED | Predicted "false" but signature visible bottom-right (boolean came back wrong — NOT CORRECTED)
+Total After Tax          | NOT CONFIRMED | Predicted "$1100.00" but Subtotal+Tax = "$1210.00" (inferred value wrong — NOT CORRECTED)
+Terms of Payment         | MISSING       | IXP predicted no value AND field not visible in document
+Discount                 | MISSING       | IXP predicted no value AND no discount section on the page
+Line Items > Description | CONFIRMED     | Predicted "Widget A" matches row 1 in the table
+```
+
+For **CORRECTED** fields: state the mangled predicted value, the corrected value, and where it appears. The mistake must be at the character level — same field, same location, garbled bytes.
+For **MISSING** fields: state that the prediction was empty AND describe how you verified the field is absent (e.g., "no payment-terms section anywhere in the document").
+For **NOT CONFIRMED** fields: state the predicted value, the actual value (if visible) and location. Includes any non-OCR mistake — wrong source, wrong boolean, wrong inferred value, hallucination, value the document doesn't contain. **Do NOT use `--corrections` to fix these** — improve the field's prompt instructions instead.
+
+4. **Build two lists from the table:**
+   - **Submit field IDs** — all CONFIRMED + CORRECTED + MISSING fields (one combined list — the CLI applies the right semantic per field based on IXP's prediction)
+   - **Corrections JSON** — only CORRECTED fields: `[{"field_id":"...","value":"corrected text"}]`
+
+### 2d. Confirm and correct
+
+Submit confirmed, corrected, and missing fields for this document — all in one `confirm` call.
+
+**If there are corrections:**
+
+```bash
+uip ixp labellings confirm <project-name> <document-id> \
+  --fields "<all_submitted_ids>" \
+  --corrections '[{"field_id":"<id>","value":"<corrected_value>"}]' \
+  --output json
+```
+
+The `--fields` list includes CONFIRMED, CORRECTED, and MISSING field IDs together — the CLI writes the right annotation per field based on IXP's prediction (content → confirm, content with override → correct, empty → missing marker). The `--corrections` JSON overrides the predicted value for corrected fields while keeping their document references (bounding boxes).
+
+**If there are no corrections (all approved fields are exact matches):**
+
+```bash
+uip ixp labellings confirm <project-name> <document-id> \
+  --fields "<field_id_1>,<field_id_2>,<field_id_3>" --output json
+```
+
+If ALL predicted fields for a document are correct with no corrections needed, you can omit `--fields` to confirm everything:
+
+```bash
+uip ixp labellings confirm <project-name> <document-id> --output json
+```
+
+**If there are missing fields**, include their IDs in the same `--fields` list as the CONFIRMED and CORRECTED IDs. The `confirm` command applies one uniform rule per listed field: if IXP predicted content, the content is confirmed; if IXP predicted nothing, a missing marker is written. No separate call needed.
+
+```bash
+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>"}]' \
+  --output json
+```
+
+**Only include a field in the `--fields` list for the MISSING case when IXP itself predicted nothing for it** — see Critical Rule 12. If IXP predicted a wrong value, omit the field entirely (don't list it).
+
+Use `labellings mark-missing` only as a fallback when `confirm --fields` is a no-op for a field you expected it to handle — typically a field with a prior annotation that the current prediction no longer includes (e.g., model behavior changed after a retrain). Verify by re-running `labellings get-predictions <project-name> <document-id>` and checking whether the field appears in the Fields[] array: if yes, `confirm --fields` is the right tool; if no, `mark-missing` reaches the stale annotation that `confirm` can't.
+
+### 2e. Move to the next document
+
+Repeat steps 2a–2d for all documents in the list.
+
+### Removing a document from the project
+
+If a document is unusable (wrong document type, corrupted, duplicate), delete it instead of confirming or skipping:
+
+```bash
+uip ixp documents delete <project-name> <document-id> --output json
+```
+
+`<document-id>` is the `DocumentId` from `documents list` (e.g., `3453547f3538febd.1fc885607f2aac621f8f2d3ef1847f22`). Pass it whole. Do NOT pass the AttachmentRef or the Filename.
+
+**Finding the DocumentId:**
+
+| You have | How to get the DocumentId |
+|----------|---------------------------|
+| Filename (e.g., `invoice-001.pdf`) | `uip ixp documents list <project-name> --output json --output-filter "[?Filename=='invoice-001.pdf'].DocumentId \| [0]" --output plain` |
+| A distinctive predicted field value (e.g., Invoice Number `MSI0601020`) | Run `uip ixp labellings get-predictions <project-name> --output json`, find the document whose `Labels[].Fields[].FormattedValue` matches, take its `DocumentId` |
+| 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.
+
+Deletion is irreversible and triggers a model retrain. Do NOT use deletion to skip documents you simply don't want to label — leave those unconfirmed instead.
+
+## Step 3 — Summary
+
+After processing all documents, track progress and errors:
+
+- Do NOT stop on the first error — continue with remaining documents
+- If a download or text fetch fails, skip the document and note the failure
+- If confirmation fails, log the error and UID, then continue
+
+At the end, report a full summary:
+
+```text
+Labelling complete.
+
+Documents: N processed, M confirmed, K skipped (no predictions)
+Fields: X confirmed, Y corrected, W marked missing, Z not confirmed
+
+OCR Corrections Applied:
+  Doc <uid-1>: Invoice Number "MSIÓÓÓ601020/" → "MSI0601020"
+  Doc <uid-1>: Vendor Name "INGRAM NTCRO INC" → "INGRAM MICRO INC"
+  Doc <uid-3>: Bill-To Address "123 Mam St" → "123 Main St"
+
+Marked Missing (IXP predicted empty AND field absent from document):
+  Doc <uid-2>: Terms of Payment
+  Doc <uid-4>: Discount
+
+Not Confirmed (skipped):
+  Doc <uid-3>: Total Amount — predicted "500.00" but actual is "5000.00" (bottom-right, page 1)
+  Doc <uid-5>: Vendor Address — predicted "123 Main St" but actual is "456 Oak Ave"
+```