@uipath/skills 1.199.0 → 1.200.0

package/skills/uipath-human-in-the-loop/SKILL.md

@@ -83,7 +83,7 @@ find . -name "*.bpmn" -maxdepth 4 | head -3
 |---|---|---|
 | `.flow` file | **Flow** | Write node JSON directly — see reference docs |
 | `agent.json` | **Low Code Agent** | Escalation CLI in-flight — guide manually for now |
-| `.bpmn` (Maestro) | **Maestro** | Not yet — guide user manually |
+| `.bpmn` (Maestro) | **Maestro** | Write the `UserTask` XML directly — see Step 5 Surface: Maestro |
 
 **If the user mentioned a specific file path**, use that directly.
 
@@ -296,7 +296,9 @@ response = interrupt(CreateTask(
 
 ### Surface: Maestro
 
-The Maestro HITL CLI is not yet available. Guide the user to add the HITL node manually in the Maestro process designer using the schema from Step 5. In Maestro, field names in `outputs`/`inOuts` must exactly match declared process variable names and types.
+QuickForm and coded-action-app HITL nodes are both supported on Maestro BPMN processes — `uipath.human-in-the-loop.quick-form` and `uipath.human-in-the-loop.coded-action-app` are registered element types in the BPMN validator ([bpmn-spec.json](../uipath-maestro-bpmn/validator/bpmn-spec.json)), same node-type strings as the Flow surface. Write the node directly into the `.bpmn` XML as a `bpmn:UserTask` with a `uipath:activity` extension element (see the `Actions.HITL` extension type in the validator spec for the app-based/coded-action-app XML shape and context fields — `appId`, `appVersion`, `actions`, `key`, `taskTitle`).
+
+Design the schema per Step 4b, confirm it with the user, then validate frequently (`uip maestro bpmn validate <file>.bpmn --output json`) while wiring the node so any shape mistakes surface immediately rather than at deploy time. In Maestro, field names in `outputs`/`inOuts` must exactly match declared process variable names and types.
 
 ---
 

package/skills/uipath-insights/SKILL.md

@@ -47,7 +47,7 @@ uip login tenant set MyTenant
 
 ## Critical Rules
 
-1. **A time range is always required.** Every `uip insights jobs` command needs either `--time-range <minutes>` (relative) or both `--started-after <epoch-ms>` and `--started-before <epoch-ms>` (absolute). Without one, the command fails. Common values:
+1. **A time range is always required.** Every `uip insights jobs` command needs either `--time-range <minutes>` (relative) or both `--started-after <epoch-ms>` and `--started-before <epoch-ms>` (absolute). Without one, the command fails. For absolute ranges, pass literal epoch-millisecond numbers, resolved beforehand (see Workflow: Absolute Time Range). Common values:
    - `--time-range 60` — last 1 hour
    - `--time-range 1440` — last 24 hours
    - `--time-range 10080` — last 7 days
@@ -220,29 +220,26 @@ To discover available folder keys, use `uip or folders list --output json` (from
 
 ## Workflow: Absolute Time Range
 
-When the user specifies an exact date range instead of "last N hours":
+When the user specifies an exact date range instead of "last N hours", use `--started-after`/`--started-before` (not `--time-range`).
+
+**Two steps, two separate command invocations.** Resolve the dates to epoch milliseconds first, read the numbers from the output, then write the literal numbers into the `uip` command. Never embed `$(date ...)` substitutions or shell variables in `uip insights` flag values — if `date` fails silently (macOS and Linux flags differ), the flag becomes garbage and the query runs against the wrong window, and the logged command no longer shows what range was actually queried.
 
 ```bash
-# Convert dates to epoch milliseconds
-# Example: 2026-07-01 00:00:00 UTC to 2026-07-06 00:00:00 UTC
-uip insights jobs summary \
-  --started-after 1782691200000 \
-  --started-before 1783123200000 \
-  --output json
+# Step 1 — resolve each boundary to epoch ms at UTC midnight (run this alone, read the output):
+date -u -d "2026-07-01 00:00:00" +%s000   # Linux  → 1782864000000
+date -u -d "2026-07-06 00:00:00" +%s000   # Linux  → 1783296000000
+date -u -j -f "%Y-%m-%d %H:%M:%S" "2026-07-01 00:00:00" +%s000   # macOS → 1782864000000
 ```
 
-Compute epoch milliseconds in bash:
 ```bash
-# macOS
-START=$(date -j -f "%Y-%m-%d" "2026-07-01" +%s)000
-END=$(date -j -f "%Y-%m-%d" "2026-07-06" +%s)000
-
-# Linux
-START=$(date -d "2026-07-01" +%s)000
-END=$(date -d "2026-07-06" +%s)000
-
-uip insights jobs summary --started-after "$START" --started-before "$END" --output json
+# Step 2 — run each subcommand with the literal resolved values:
+uip insights jobs summary --started-after 1782864000000 --started-before 1783296000000 --output json
 ```
+```bash
+uip insights jobs completed-timeline --started-after 1782864000000 --started-before 1783296000000 --output json
+```
+
+The end boundary is exclusive: "July 1st to July 5th" inclusive means `--started-after` = July 1 00:00:00 UTC and `--started-before` = July 6 00:00:00 UTC.
 
 ---
 
@@ -262,6 +259,8 @@ uip insights jobs summary --started-after "$START" --started-before "$END" --out
 ## What NOT to Do
 
 - **Don't call `uip insights jobs` without a time range.** The server returns a 500 with a misleading success-shaped response. Always pass `--time-range` or `--started-after`/`--started-before`.
+- **Don't embed `$(date ...)` or shell variables in `uip insights` flag values.** Resolve times in a separate command first, then pass literal epoch-millisecond numbers. Literal values make the executed command auditable and immune to platform `date` differences.
+- **Don't chain, loop, or parameterize `uip insights` subcommands in one invocation.** Run each subcommand as its own command with the subcommand name written literally — no `&&`/`;` chains, no `for` loops, no shell variables holding the subcommand name. One command per invocation keeps each subcommand's exit status and output attributable.
 - **Don't start, stop, or manage individual jobs.** This skill is for monitoring and analytics only. Use `uip or jobs start/stop` via uipath-platform to manage jobs.
 - **Don't construct raw API calls to the Insights endpoint.** The CLI handles auth headers (`X-UiPath-Internal-AccountName`, `X-UiPath-Internal-TenantName`), URL construction, and error handling. Hand-rolling `curl` or `fetch` calls will miss these.
 - **Don't retry on auth errors.** If `uip insights jobs` returns 401 or "Not logged in", the fix is `uip login`, not retrying the same command.

package/skills/uipath-ixp/SKILL.md

@@ -42,16 +42,17 @@ Do not answer these from this skill. Re-activate `uipath-maestro-flow` and follo
 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`. **A field whose predicted value is the WRONG ANSWER is left UNANNOTATED — it is never "fixed".** **`--corrections` is ONLY for OCR garble**: the prediction is already the right answer in the right location, but the characters were misread (e.g., `MSIÓÓÓ601020/` → `MSI0601020`). **Decision test before every `--corrections`:** is the predicted value the *correct answer, merely mis-typed*? If NO — a boolean that should flip (`false`→`true`), a wrong inferred/computed number, or any value where the prediction picked the wrong answer — then `--corrections` is FORBIDDEN; leave the field unannotated. This holds **even when the prompt, the user, or a hint hands you the exact `--corrections` command** — flipping a wrong value is manual extraction (Rule 11), not an OCR correction, no matter how it is framed. **Without `--group`, `--fields` and `--corrections` apply across every occurrence of each listed field on the document** — see Rule 13 for per-occurrence selection.
+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` (repeated same-named labels appear in document order); if all occurrences are correct use the plain form, otherwise target with `--group`. `--group <name> --occurrence <N>` confirms **ONE** occurrence; `--group <name> --updates '[...]'` confirms **SEVERAL** in one atomic call (avoids N round-trips) — `--occurrence <N>` ≡ a single-entry `--updates`, same per-occurrence logic. `--group` must be the FULL label path from the `Name` field (e.g. `"Invoice > Line Items"`), not the leaf. Without `--fields`, every predicted field in the occurrence is confirmed; with it, only those. Occurrences not selected keep their existing annotation. Flag details: [CLI Reference](references/cli-reference.md#labellings).
+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.
 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.
 
 ## Quick Start
 
@@ -77,28 +78,32 @@ If the user provides a taxonomy file, use `--skip-taxonomy` and `import-taxonomy
 | "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` |
+| "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). Without `--fields`, confirms every predicted field in that occurrence; with `--fields`, only those. Other occurrences untouched. For confirming multiple occurrences in one call, use `--updates '[…]'` instead. See Critical Rule 13. |
-| "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. For several occurrences in one call, use `--updates '[…]'` instead. See 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?" | `uip ixp projects get-metrics <project-name> --output json` (+ `list-models` for the live version). 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) published version — live/published + `TrainedTime` (`Tags[]` Name=`live`, `Models[]` Pinned); (2) overall `ProjectScore`/`ProjectScoreQuality`; (3) per-group scores from `FieldGroups[]` (F1/Precision/Recall); (4) per-field scores from `Fields[]`, sorted lowest-F1 first. State numbers plainly; no "good enough" judgement unless asked; route low scores to [Improve Prompts Guide](references/improve-prompts-guide.md). Answer from these two 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 — live/published + `TrainedTime` from `list-models`; (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). |
+| "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 |
 |---------|-------|-----|
-| Metrics don't change after a prompt update | Re-evaluation hasn't completed | Wait ~2 minutes for retrain. |
-| ModelVersion doesn't advance | Retrain still in progress | Any change to model inputs (labellings OR instructions) triggers a full retrain. Wait ~2 min then retry. |
+| 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. |
 
 ## Unsupported Capabilities
 

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

@@ -11,18 +11,41 @@ All commands use `uip ixp` prefix. Always append `--output json` when parsing ou
 | `uip ixp projects list [-l <limit>] [--offset <n>] --output json` | List IXP projects — returns a paged envelope `Data: { Projects: [{ Id, Name, Title, CreatedAt }], Total, Offset, Limit }` (rows under `Projects`, **not** a bare array). `-l, --limit` defaults 50 (range 1-10000); `--offset` defaults 0 to page. |
 | `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 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. **Merges — it never replaces**: entries you omit are kept and a posted `field_id` is ignored, so it cannot remove, move, or replace anything (a re-imported edit returns `{"status":"ok"}` and silently leaves duplicates). Use it to seed a project that has no taxonomy; change an existing one with the targeted `groups`/`fields`/`data-types` commands. |
 | `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` | Export the raw IXP taxonomy artifact. Data is `{ status, dataset: { entity_defs, label_groups } }` — read `entity_defs` and `label_groups` under `dataset`. Intended for re-import (see `import-taxonomy`), not a human-readable view. |
+| `uip ixp projects get-taxonomy <project-name> --output json` | Export the raw IXP taxonomy artifact. Data is `{ status, dataset: { entity_defs, label_groups } }` — read `entity_defs` and `label_groups` under `dataset`. Intended for re-import (see `import-taxonomy`), not a human-readable view. `dataset` also carries `_model_config`, the only read path for the configured extraction model and pre-processing — see [Reading the current model and pre-processing](#reading-the-current-model-and-pre-processing). |
 | `uip ixp projects get-metrics <project-name> [--model-version <N>] --output json` | Get validation metrics. **Validated model →** flat Data: `ProjectScore`, `ProjectScoreQuality`, `ValidatedDocuments`, `ModelVersion`, plus per-group `FieldGroups[]` (`FieldGroup`, `F1`, `Precision`, `Recall`, `ErrorRate`, `Documents`) and per-field `Fields[]` (`FieldGroup`, `FieldId`, `F1`, `Precision`, `Recall`, `ErrorRate`, `Documents`, `Annotations`, `Quality`). **Trained but not yet validated →** Data is `{ Metrics: null }` (not an error). **No trained model yet (e.g. a project with no confirmed labellings) →** the call returns a failure envelope `Result: Failure` with `ErrorCode: not_found` (no `Data`), NOT `{ Metrics: null }` — treat it as "no metrics yet". Defaults to the latest version; pass `--model-version <N>` (`-m`, `latest` or an integer) to scope to a specific trained version. |
-| `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`, `ModelName`, `Pinned`, `TrainedTime`, `Description`), `Tags[]` (`Name`, `Version`, `UpdatedAt`), and `MaxPublished`. |
+| `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). To read the current settings, see [Reading the current model and pre-processing](#reading-the-current-model-and-pre-processing). |
+| `uip ixp projects list-models <project-name> --output json` | List all model versions and tags. Returns `Models[]` (`Version`, `ModelName`, `Pinned`, `TrainedTime`, `Description`), `Tags[]` (`Name`, `Version`, `UpdatedAt`), and `MaxPublished`. `ModelName` is the trained labeller's **family** (e.g. `gemini_ixp`, `gemini_pro_ixp`) — it is never a `--model` value like `gemini_2_5_flash`, so it does not answer "which extraction model is configured" (see [Reading the current model and pre-processing](#reading-the-current-model-and-pre-processing)). |
 | `uip ixp projects publish <project-name> [--model-version <N>] [--tag <live\|staging>] --output json` | Publish a model version — defaults to the latest; pass `-m, --model-version <N>` to pick a specific one. `-d, --description "<text>"` sets a description; `--tag <live\|staging>` tags the published version. |
 | `uip ixp projects unpublish <project-name> --model-version <N> --output json` | Unpublish a model version — it stays trained and listable; only its published status is removed. `--model-version` is **required**. Errors if the version isn't found or isn't currently published. To change which version is live, `publish` a different one instead. |
 | `uip ixp projects untag <project-name> --tag <live\|staging> --output json` | Remove a tag by **name** (`--tag` is **required**; tag names are unique within a project, so this is unambiguous even when one version holds several tags). The version the tag pointed at stays published; only that tag is cleared. Errors if no version carries the tag. Only `untag` removes a tag — `publish` without `--tag` leaves the existing tag untouched. To switch `live`→`staging`, `publish --tag staging` instead. |
 | `uip ixp projects delete <project-name> -y --output json` | **Permanently** delete a project — its documents, taxonomy, and trained models. **Irreversible.** `-y, --yes` is **required**; the command refuses to run without it (the CLI never prompts). |
 
+### Reading the current model and pre-processing
+
+There is **no `get-model-config` command** — `configure-model` only writes. The configured extraction model and pre-processing are in the taxonomy artifact under `Data.dataset._model_config`:
+
+```bash
+uip ixp projects get-taxonomy <project-name> --output json
+```
+
+**Model** — `_model_config.model_version` holds the `--model` value verbatim (e.g. `gemini_2_5_flash`). Report that one. Do **not** report `list-models`' `ModelName`: that is the trained labeller's family (`gemini_ixp`) and carries no pre-processing information at all.
+
+**Pre-processing** — `_model_config.input_config` stores the underlying mode, not the `none|table_mini|table` token, so invert it:
+
+| `input_config` | `--preprocessing` |
+|----------------|-------------------|
+| `null` | never configured — report it as *not configured* (the project uses the IXP default), **not** as `none` |
+| `{"mode": "image_only"}` | `none` |
+| `{"mode": "text_plus_image", "text_config": {"kind": "uipath_cv_table_only"}}` | `table_mini` |
+| `{"mode": "text_plus_image", "text_config": {"kind": "gemini_table_only"}}` | `table` |
+
+The remaining `_model_config` keys (`kind`, `flags`, `attribution_method`, `temperature`, `top_p`, `seed`, `system_prompt_override`, `iterative_config`) have no `uip ixp` flag — mention them only if the user asks.
+
+`_model_config` reflects the project's **current** setting, not the setting a given trained version was built with — so report it as the project's configuration, not as a property of the published version.
+
 ## Documents
 
 | Command | Description |
@@ -43,7 +66,7 @@ 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.
+Each upload triggers a retrain — wait it out before reading metrics or predictions for new docs, under the bounded wait in [Improve Prompts Guide § Waiting for retrain](improve-prompts-guide.md#waiting-for-retrain).
 
 ### Uploading documents to an existing project
 
@@ -89,7 +112,20 @@ Every IXP project ships with the built-in data types below (the project's `entit
 | `Monetary Quantity` | `money` | — | Any currency / monetary amount — total, subtotal, tax, unit price, freight |
 | `Boolean` | `boolean` | — | True / false values |
 
-`Date`, `Number`, and `Monetary Quantity` carry pre-trained models with a fixed output format (e.g. `Monetary Quantity` normalises `"1M USD"`, `"USD 1000000"`, and `"1,000,000 usd"` all to `1,000,000.00 USD`) — instructions cannot change their formatting, so a hand-rolled equivalent is strictly worse. `Choice` is the only `--kind` with no default: choice types are always project-specific (`data-types add --kind choice --choices …`).
+`Date`, `Number`, `Monetary Quantity`, and `Boolean` carry pre-trained models with a fixed output format (below) — instructions cannot change their formatting, so a hand-rolled equivalent is strictly worse. `Choice` is the only `--kind` with no default: choice types are always project-specific (`data-types add --kind choice --choices …`).
+
+### Normalized output formats
+
+`get-predictions` reports these types in the type's normalized form, never the page's literal text. A plain `confirm` stores that same normalized string as the label.
+
+| Type | `FormattedValue` | Page → prediction |
+|------|------------------|-------------------|
+| `Date` | `YYYY-MM-DDTHH:MM:SSZ` — a date-only page value comes back at `T00:00:00Z` | `21-JUN-22` → `2022-06-21T00:00:00Z` |
+| `Monetary Quantity` | `<amount> <ISO-4217 code>` — no thousands separator, decimals as written on the page (not fixed to 2), currency appended even when the page shows none | `114.91` → `114.91 AUD`; `8.0700` → `8.0700 USD` |
+| `Number` | bare numeric string, no unit or separator | `29311577` → `29311577` |
+| `Boolean` | `True` / `False` | — |
+
+`--corrections` neither normalizes nor validates — the string you send is stored verbatim (`21-JUN-22`, even `not-a-date`, all return Success). Sending the page's format replaces a correct label with one the model will never predict and drops the field's F1. Reformatting is never a reason to use `--corrections` (Critical Rule 8).
 
 ## Groups
 
@@ -114,19 +150,45 @@ Structural edits to a field within an existing field group. For instruction-only
 | `uip ixp fields change-type <project-name> --group <field-group-name> --field <name> --type <type-name> -y --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. `-y, --yes` is **required** (the CLI never prompts). |
 | `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. |
 
+### Moving a field to a different field group
+
+There is **no move/reparent command**. Every field command takes its group as `--group`, which only addresses the field — it cannot change which group owns it. A move is two `fields` calls against the existing groups, in this order:
+
+1. `uip ixp projects get-taxonomy <project-name> --output json` — read the field's current `type` and `instructions` so they can be carried over. In `Data.dataset`, the field is a `moon_form` entry under its group's `label_def`; its type is the `entity_defs[]` entry whose `id` matches the entry's **`field_type_id`** (NOT its `field_id`, which is the field's own identity and matches no `entity_def`).
+2. `uip ixp fields add <project-name> --group <target-group> --field <name> --type <type-name> --instructions <text> --output json` — recreate it in the target group.
+3. `uip ixp fields delete <project-name> --group <source-group> --field <name> -y --output json` — remove it from the source group.
+
+Add before deleting: if the add fails, the field is still in its original group. Both groups must already exist — a move never creates one. Creating the target group first, if the user asked for a group that isn't there yet, is a separate `groups add` step you should confirm with them.
+
+**IRREVERSIBLE** — `fields add` mints a new `field_id`, so the field's confirmed labels do not follow it into the new group. Tell the user before starting; documents must be re-reviewed for that field.
+
+**Do NOT move a field by editing the taxonomy and re-importing it.** `projects import-taxonomy` **merges** — it does not replace. Fields you omit from a posted group are kept, and a posted `field_id` is ignored (the backend mints a new one), so the import returns `{"status":"ok"}` while leaving the field in **both** groups as two separate fields. Do not use `groups delete` + `groups add` either: that destroys every other field in the group along with its annotations.
+
 ## 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 `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. |
+| `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`. 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`. |
+| `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 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`) 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> [--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`. |
 | `uip ixp labellings mark-missing <project-name> <document-id> --fields <ids> --output json` | Mark the listed fields as missing (`--fields` has short alias `-f`; annotated with no value and no location) — use when a field is genuinely absent from the document and IXP predicted no value for it. Unlike `confirm --fields`, it also marks a field that's gone from the current predictions entirely (e.g. a stale prior annotation after a model/taxonomy change), which `confirm` can't reach. **Only for fields where IXP 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. |
 
+### Occurrence numbering and read order
+
+`Occurrence` is the row's position in the read that reported it, not a stable row id — a repeatable group's rows have no per-row identifier in the contract (`field_group.id` is the taxonomy group id and is identical for every row).
+
+The server pairs annotations with predictions and returns the **matched pairs first**, then the unmatched predictions. Confirming one row therefore moves it to `Occurrence` 0 on the next read and shifts the others down (the IXP UI shows it first too). The row's values and page location are unchanged — only its position in the read moves. Document order holds only for a group with no annotations, or one where every row is annotated.
+
+So an `Occurrence` value is invalidated by any write to its group:
+
+- confirm/unconfirm every target row in ONE `--updates` call — all indices in a call resolve against the same read;
+- between sequential per-occurrence calls, re-run `get-predictions` and re-locate each row by its field values;
+- never carry an index across a write.
+
 ## 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.

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

@@ -38,20 +38,34 @@ The user may specify a max number of iterations (default: 3). Track:
 
 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.
 
+## Waiting for retrain
+
+Every change to model inputs — labellings, instructions, document upload/delete, taxonomy edits — triggers a full retrain. Metrics read mid-retrain are *pre*-change scores and corrupt every downstream comparison, so wait before each metrics read.
+
+**Bounded wait. Poll on a fixed interval; never poll indefinitely:**
+
+1. Record `ModelVersion` from the last metrics read BEFORE the change.
+2. Wait 2 minutes, then read `uip ixp projects get-metrics <project-name> --output json`.
+3. `ModelVersion` **greater than** the recorded value → retrain is done, proceed. Any increment counts. Do NOT wait for a specific number: queued input changes can bump the version by more than one, so waiting for exactly *N*+1 polls until the budget dies when the server jumps straight to *N*+2.
+4. Otherwise repeat step 2 — **2 minutes between checks, 5 checks in total** (10 minutes). Do NOT use a single long sleep, and do NOT escalate or shorten the interval between checks.
+5. Still unchanged after the 5th check → **stop polling** and report that the retrain did not complete. Metrics you carry forward predate the change: label them as such, never present them as the post-change measurement, and never roll back instructions on a comparison against them.
+
+A read that fails counts against the budget like any other attempt, and never restarts it.
+
 ## 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.
+If documents were just labelled (or uploaded, or the taxonomy was edited), wait out the resulting retrain before reading metrics — apply the bounded wait in [Waiting for retrain](#waiting-for-retrain).
 
 ```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.
+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; re-fetch under the bounded wait in [Waiting for retrain](#waiting-for-retrain), then proceed with whatever it returns.
 
-Save the full per-field `Fields` array as `baseline_metrics`. This is the starting point you compare against. (For a validated model, get-metrics Data is flat — `Fields`/`FieldGroups`/`ValidatedDocuments` are top-level. An unvalidated model returns `Data: { Metrics: null }` instead — wait for retrain and re-fetch.)
+Save the full per-field `Fields` array as `baseline_metrics`. This is the starting point you compare against. (For a validated model, get-metrics Data is flat — `Fields`/`FieldGroups`/`ValidatedDocuments` are top-level. An unvalidated model returns `Data: { Metrics: null }` instead — re-fetch under the bounded wait above.)
 
 **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:
 
@@ -96,7 +110,7 @@ The `download` command auto-detects format and appends the correct extension —
 
 ### 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.
+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 re-fetch metrics under the bounded wait in [Waiting for retrain](#waiting-for-retrain) before starting the loop.
 
 ---
 
@@ -135,7 +149,7 @@ For each REFINE field with **Recall < 0.5**, check whether the problem is a bad
    - 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 you find previously skipped predictions that are actually correct**, confirm them now using `labelling confirm --fields` for those specific documents and fields, then re-fetch metrics under the bounded wait in [Waiting for retrain](#waiting-for-retrain) before continuing.
 
 **If no labelling gaps are found**, proceed directly to writing instructions.
 
@@ -212,17 +226,17 @@ Compare the number of fields in each updated label_def against the previous vers
 
 ### 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).
+Wait out the retrain triggered by the updated instructions ([Waiting for retrain](#waiting-for-retrain)), 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:
+Wait out the retrain triggered by the new labellings ([Waiting for retrain](#waiting-for-retrain)), 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.
+If `ModelVersion` hasn't advanced since the last check, keep re-reading under that same bounded budget. When the budget runs out, record the metrics you have and move on to step 2f — do NOT stall the iteration waiting for a version bump.
 
 ### 2f. Compare and decide
 
@@ -246,7 +260,7 @@ uip ixp fields update-prompts <project-name> \
   --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).
+Wait out the retrain ([Waiting for retrain](#waiting-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).
 

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

@@ -29,7 +29,7 @@ For each document from the list, process one at a time: get predictions, downloa
 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`.
+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).
 
 ### 2b. Download the document file
 
@@ -48,8 +48,8 @@ Use the **Read tool** to view the document file (read the whole document in one
 
 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.
+   - **CONFIRMED** — the predicted value matches what is in the document, literally or in its data type's normalized form. Minor OCR-level differences (capitalization, whitespace) are acceptable, as is any difference that is purely the type's normalization — a `Date` reads back as `2022-06-21T00:00:00Z` for a page showing `21-JUN-22`, a `Monetary Quantity` as `114.91 AUD` for a page showing `114.91`. Compare the values by reading them; do not write a script to convert or check formats. See [CLI Reference § Normalized output formats](cli-reference.md#normalized-output-formats).
+   - **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`, or a misread digit in a number — page `£7,300.00` predicted as `£730.00`). The reference is correct, only the literal characters need fixing. **A number whose magnitude differs from the page is OCR garble, never type normalization** (Rule 8). Do NOT use CORRECTED to restore a page's date or amount formatting, 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:
@@ -69,7 +69,7 @@ Discount                 | MISSING       | IXP predicted no value AND no discoun
 Line Items > Description | CONFIRMED     | Predicted "Widget A" matches row 1 in the table
 ```
 
-**Repeatable field groups produce one extraction per row.** `get-predictions` returns one label per row, each with an explicit 0-based `Occurrence` — `Line Items` on a multi-line invoice has N entries indexed 0..N-1 (read `Occurrence` directly; it equals document order). When validation differs across rows, give per-occurrence verdicts:
+**Repeatable field groups produce one extraction per row.** `get-predictions` returns one label per row, each with an explicit 0-based `Occurrence` — `Line Items` on a multi-line invoice has N entries indexed 0..N-1. Read `Occurrence` directly — on an unlabelled document it matches document order, but once part of the group is confirmed it does not (see [Occurrence numbers are read-scoped](#occurrence-numbers-are-read-scoped)), so match rows to the document by their values, not by index. When validation differs across rows, give per-occurrence verdicts:
 
 ```text
 Line Items > Description (occurrence 0) | CONFIRMED     | "Widget A" matches line 1
@@ -140,7 +140,17 @@ uip ixp labellings confirm <project-name> <document-id> \
   --group "Line Items" --occurrence 2 --fields c4e1907a3b8f25d6 --output json
 ```
 
-Occurrences not targeted carry forward whatever annotation they already had (so wrong predictions in untouched occurrences stay unannotated). For batching many occurrences in one call, use `--updates '[…]'` — see [CLI Reference § Labellings](cli-reference.md#labellings). See Critical Rule 13.
+Occurrences not targeted carry forward whatever annotation they already had (so wrong predictions in untouched occurrences stay unannotated).
+
+**Confirm all the correct rows in one `--updates` call, not one `--occurrence` call per row** — every index in a single call resolves against the same read, whereas the second of two sequential calls is working from indices the first one invalidated ([Occurrence numbers are read-scoped](#occurrence-numbers-are-read-scoped)):
+
+```bash
+uip ixp labellings confirm <project-name> <document-id> \
+  --group "Line Items" --updates '[{"occurrence":0},{"occurrence":2,"fields":["c4e1907a3b8f25d6"]}]' \
+  --output json
+```
+
+See [CLI Reference § Labellings](cli-reference.md#labellings) and Critical Rule 13.
 
 **Per-occurrence unconfirm.** `unconfirm` takes the same `--group`/`--occurrence`/`--updates` flags, so a wrong confirmation can be rolled back at the same granularity. `unconfirm --fields a7c3e9105f2b4d86` (no `--group`) removes `a7c3e9105f2b4d86` from **every** occurrence; scope it to one line with `--group "Line Items" --occurrence 2`, or several at once with `--group "Line Items" --updates '[…]'`, using the same 0-based indices. Without `--fields`, every annotated field in the targeted occurrence(s) is rolled back; with `--fields`, only those. See Critical Rule 14.
 
@@ -150,10 +160,28 @@ uip ixp labellings unconfirm <project-name> <document-id> \
   --group "Line Items" --occurrence 2 --output json
 ```
 
+Take the index from a **fresh** `get-predictions`: on a partly-confirmed group, the index that confirmed a row is usually not the index that rolls it back.
+
 ### 2e. Move to the next document
 
 Repeat steps 2a–2d for all documents in the list.
 
+### Occurrence numbers are read-scoped
+
+`get-predictions` does not return a repeatable group's rows in a fixed order. The server pairs each annotation with its prediction and lists the **matched pairs first**, then the still-unmatched predictions. So on a partly-confirmed group:
+
+- confirmed rows sort to the front — confirm the third row of four and it reads back as `Occurrence` 0, with the other three shifted to 1, 2, 3;
+- the same holds in the IXP UI, which shows the confirmed row first;
+- nothing is lost or mis-assigned: the confirmed row keeps its own values and page location, it is only positioned differently in the read.
+
+Only two states read back in document order: a document with no annotations on the group, and one where every row is annotated.
+
+The consequence for labelling: **an `Occurrence` value is only valid for the read that produced it, and any write to that group invalidates it.** So
+
+- put every occurrence you want to confirm (or unconfirm) in ONE `--updates` call — all of its indices resolve against the same read;
+- if sequential per-occurrence calls are unavoidable, re-run `get-predictions` between them and re-locate each row by its field values;
+- never reuse an index across a write, and report rows to the user by value ("the row with Description `Widget B`"), not as "row 3".
+
 ### Removing a document from the project
 
 If a document is unusable (wrong document type, corrupted, duplicate), delete it instead of confirming or skipping:

package/skills/uipath-maestro-bpmn/SKILL.md

@@ -112,12 +112,12 @@ For registry-evidence-only tasks, be command-first and time-boxed:
    serializer's lower-camel BPMN element (`<bpmn:sendTask>`,
    `<bpmn:receiveTask>`) while preserving the `uipath:*` payload exactly.
 3. **Assemble.** Author directly from the complete minimal file in
-   [references/structural-bpmn.md](references/structural-bpmn.md#a-complete-minimal-file-author-from-this-not-from-fixtures)
+   [references/structural-bpmn.md](references/structural-bpmn.md#a-complete-minimal-file-author-from-this-not-from-examples)
    plus each node's `xmlTemplate` (fill placeholders only). That skeleton already
-   shows variables, the entry point, a branch, and the diagram. **Do not read the
-   validator's `test/fixtures/`, task fixtures, or generated package files to
-   infer authoring patterns** — fixture spelunking is the top reason authoring
-   runs out of time. Add only the structural pieces your process needs (extra
+   shows variables, the entry point, a branch, and the diagram. **Do not
+   reverse-engineer authoring patterns from task fixtures or generated package
+   files** — fixture spelunking is the top reason authoring runs out of time.
+   Add only the structural pieces your process needs (extra
    gateways, events, boundary events, containers, multi-instance markers,
    expression/error mappings, retry attributes), then generate one
    `BPMNShape`/`BPMNEdge` per node and flow. For local authoring prompts, use the
@@ -155,19 +155,21 @@ For registry-evidence-only tasks, be command-first and time-boxed:
    metadata shape in
    [references/shared/local-metadata-regeneration-guide.md](references/shared/local-metadata-regeneration-guide.md#minimal-local-metadata-shape).
    Do not copy CLI scaffold metadata shapes into a synthetic local project.
-4. **Validate.** There is **no** `uip maestro bpmn validate` CLI command. Run the
-   bundled validator — it reconstructs the canvas model and runs every
-   PO.Frontend rule:
+4. **Validate.** Run the CLI validator — it runs the full PO.Frontend canvas
+   rule set (structural rules plus variable, method-call, input-type, and
+   event-object checks) offline, plus deploy-readiness checks:
 
    ```bash
-   cd skills/uipath-maestro-bpmn/validator && npm install --silent
-   node validate-bpmn.mjs <file.bpmn>   # prints VALID (exit 0) or the errors (exit 1)
+   uip maestro bpmn validate <file.bpmn> --output json
    ```
 
-   A well-formed-XML parse is the secondary fallback if Node is unavailable. See
+   Exit 0 = valid; exit 1 = validation failed (the envelope lists each issue
+   with its rule code). Warnings are reported but do not fail the run. Validate
+   once; fix only error-severity findings. Do not re-validate in a loop chasing
+   warnings. If `validate` reports "unknown command" or clearly skips the
+   structural rules, the installed CLI predates them — update it (see
+   [references/cli-conventions.md](references/cli-conventions.md)). See
    [references/structural-bpmn.md#validation](references/structural-bpmn.md#validation).
-   Validate once; fix only ERROR-severity findings (warnings do not block import).
-   Do not re-validate in a loop chasing warnings.
 
 ## Operate and diagnose
 
@@ -252,7 +254,6 @@ and honestly surfaced to the user as gaps when asked.
 | Runtime expressions, `vars.`/`bindings.`/`iterator.`, `=js:` (Jint) syntax | [references/expression-authoring.md](references/expression-authoring.md) |
 | CLI conventions and the side-effect boundary | [references/cli-conventions.md](references/cli-conventions.md) |
 | Keeping content public-safe | [references/public-safety.md](references/public-safety.md) |
-| Bundled offline validator (every PO.Frontend rule) | [validator/README.md](validator/README.md) |
 | Package, upload, publish, run, or manage instances | [references/operate/CAPABILITY.md](references/operate/CAPABILITY.md) |
 | Diagnose a failed or misbehaving run | [references/diagnose/CAPABILITY.md](references/diagnose/CAPABILITY.md) |
 | Project layout and generated package files | [references/shared/project-layout.md](references/shared/project-layout.md) |