@uipath/skills 1.197.2 → 1.198.0

package/skills/uipath-insights/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: uipath-insights
+description: "UiPath Insights job monitoring via `uip insights` — query job execution metrics, failure analysis, and process performance. Covers job KPIs, failure reasons, completion trends, process breakdowns. For Orchestrator job start/stop/logs→uipath-platform, root-cause analysis of specific errors→uipath-troubleshoot, RPA workflow authoring→uipath-rpa."
+when_to_use: "User says 'job failures', 'automation health', 'job success rate', 'processing time', 'which processes fail the most', 'failure reasons', 'job trends', 'how many jobs ran', 'insights dashboard', 'job metrics', 'job KPIs', 'job performance', 'uncompleted jobs', 'pending jobs', 'faulted jobs', 'job timeline', 'process details'. Also 'uip insights', 'insights jobs'. NOT for starting/stopping jobs (uipath-platform), NOT for root-cause debugging of a specific job error (uipath-troubleshoot), NOT for queue metrics (not yet supported)."
+allowed-tools: Bash, Read
+---
+
+# UiPath Insights — Job Monitoring Agent Skill
+
+Insights provides analytics and monitoring for UiPath automation execution. This skill covers **job monitoring** — querying aggregated job execution data for dashboards, health checks, and failure investigation.
+
+All operations go through `uip insights jobs <subcommand> --output json`.
+
+---
+
+## When to Use
+
+- Checking overall automation health (how many jobs ran, how many succeeded)
+- Investigating job failures (which processes fail most, what are the failure reasons)
+- Monitoring job execution trends over time (completed/uncompleted timelines)
+- Getting per-process performance breakdowns
+- Drilling into specific failure details for investigation
+
+> **Not in scope:** Starting, stopping, or managing individual jobs (use `uip or jobs` via uipath-platform). Root-cause debugging of a specific job's error (use uipath-troubleshoot). Queue item metrics, robot utilization, or dashboard CRUD (not yet available in CLI).
+
+---
+
+## Login & Tenant Setup
+
+**Default to Production. Only switch environment/org/tenant when explicitly stated in the request.**
+
+- If the request mentions no environment, use the current session (defaults to prod `cloud.uipath.com`)
+- If the request explicitly names an environment/org/tenant, check `uip login status` and re-login if needed
+
+```bash
+# Check current environment, org, and tenant
+uip login status --output json
+
+# Login to a specific environment
+uip login --authority https://alpha.uipath.com --tenant MyTenant
+
+# Switch tenant within the same environment
+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:
+   - `--time-range 60` — last 1 hour
+   - `--time-range 1440` — last 24 hours
+   - `--time-range 10080` — last 7 days
+   - `--time-range 43200` — last 30 days
+
+2. **Always use `--output json`.** All commands return a JSON envelope: `{ Result: "Success", Code: "<code>", Data: { ... } }`. Parse the `Data` field for the actual metrics.
+
+3. **Filter options are repeatable.** `--folder-key`, `--process-name`, and `--machine-name` can be specified multiple times to filter by several values: `--process-name "ProcessA" --process-name "ProcessB"`.
+
+4. **Empty data is normal.** If no jobs ran in the time window, the response will have `Data` with null/zero/empty fields. This is not an error.
+
+5. **Start with summary, then drill down.** For any investigation, start with `summary` to get the big picture, then use specific subcommands to investigate areas of concern.
+
+---
+
+## Command Reference
+
+All commands share these filter options:
+
+| Option | Description |
+|--------|-------------|
+| `--time-range <minutes>` | Relative time range in minutes |
+| `--started-after <epoch-ms>` | Absolute start time (Unix epoch ms) |
+| `--started-before <epoch-ms>` | Absolute end time (Unix epoch ms) |
+| `--folder-key <guid>` | Filter by folder key (repeatable) |
+| `--process-name <name>` | Filter by process name (repeatable) |
+| `--machine-name <name>` | Filter by machine name (repeatable) |
+| `--timezone-offset <minutes>` | Client timezone offset from UTC |
+
+### summary
+
+Get job KPIs: total count, successful count, and average processing time.
+
+```bash
+uip insights jobs summary --time-range 1440 --output json
+```
+
+**Key Data fields:** `jobsCount`, `successfulJobsCount`, `averageProcessingTime`
+
+**Use when:** User asks "how are my automations doing?" or "what's my job success rate?"
+
+### completed-timeline
+
+Get completed jobs over time, grouped by job state (successful, faulted, stopped, etc.).
+
+```bash
+uip insights jobs completed-timeline --time-range 1440 --output json
+```
+
+**Key Data fields:** `jobState`, `jobCountByTime`, `timestamp`
+
+**Use when:** User asks "show me job completion trends" or "when do most jobs run?"
+
+### uncompleted-timeline
+
+Get running and pending jobs over time.
+
+```bash
+uip insights jobs uncompleted-timeline --time-range 1440 --output json
+```
+
+**Key Data fields:** `jobState`, `jobCountByTime`, `timestamp`
+
+**Use when:** User asks "are there stuck jobs?" or "how many jobs are still running?"
+
+### top-failures
+
+Get processes ranked by failure count.
+
+```bash
+uip insights jobs top-failures --time-range 43200 --output json
+```
+
+**Key Data fields:** `processName`, `jobCountByTime`
+
+**Use when:** User asks "which processes fail the most?" or "what's causing failures?"
+
+### failures-by-reason
+
+Get job failures grouped by exception reason, with total job count for context.
+
+```bash
+uip insights jobs failures-by-reason --time-range 1440 --output json
+```
+
+**Key Data fields:** `processExceptionReason`, `processName`, `robotName`, `jobsCount`
+
+**Use when:** User asks "why are jobs failing?" or "what are the common error messages?"
+
+### process-details
+
+Get per-process job breakdown with counts by state.
+
+```bash
+uip insights jobs process-details --time-range 1440 --output json
+```
+
+**Key Data fields:** `processName`, `jobAggregate`
+
+**Use when:** User asks "show me per-process stats" or "which process has the most faulted jobs?"
+
+### failure-details
+
+Get detailed failure information for drill-down investigation.
+
+```bash
+uip insights jobs failure-details --time-range 1440 --output json
+```
+
+**Key Data fields:** `processName`, `machineName`, `processExceptionReason`, `startTime`, `endTime`
+
+**Use when:** User asks "show me the details of recent failures" or "which machines are failing?"
+
+---
+
+## Workflow: Investigate Job Health
+
+Follow this pattern when a user asks about automation health or job failures:
+
+```bash
+# 1. Check login
+uip login status --output json
+
+# 2. Get the big picture — how many jobs ran? how many succeeded?
+uip insights jobs summary --time-range 1440 --output json
+
+# 3. If success rate is low, find which processes fail most
+uip insights jobs top-failures --time-range 1440 --output json
+
+# 4. Find out WHY they're failing
+uip insights jobs failures-by-reason --time-range 1440 --output json
+
+# 5. Drill into specific failure details
+uip insights jobs failure-details --time-range 1440 --output json
+
+# 6. For time-based trends, check timelines
+uip insights jobs completed-timeline --time-range 10080 --output json
+```
+
+**Present findings clearly:** After gathering data, summarize for the user:
+- Total jobs vs successful jobs (derive failure rate)
+- Top failing processes by name
+- Most common failure reasons
+- Which machines are affected
+- Whether failures are trending up or down
+
+---
+
+## Workflow: Filter by Folder or Process
+
+When the user asks about a specific folder or process:
+
+```bash
+# Filter by folder
+uip insights jobs summary --time-range 1440 --folder-key "abc-123-def" --output json
+
+# Filter by process name
+uip insights jobs top-failures --time-range 43200 --process-name "Invoice_Processing" --output json
+
+# Combine filters
+uip insights jobs failures-by-reason --time-range 1440 \
+  --folder-key "abc-123-def" \
+  --process-name "Invoice_Processing" \
+  --output json
+```
+
+To discover available folder keys, use `uip or folders list --output json` (from the uipath-platform skill).
+
+---
+
+## Workflow: Absolute Time Range
+
+When the user specifies an exact date range instead of "last N hours":
+
+```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
+```
+
+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
+```
+
+---
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Not logged in` | Auth expired | `uip login` |
+| `time range is required` | Missing `--time-range` or `--started-after`/`--started-before` | Add `--time-range 1440` (or your preferred window) |
+| `API request failed: 401` | Token doesn't have Insights access | Re-login; ensure the org has Insights enabled |
+| `API request failed: 403` | User has no folder permissions | Check folder assignments in Orchestrator Admin |
+| `API request failed: 500` | Server error (often missing time range on older deployments) | Ensure time range is provided in the request body |
+| All Data fields are null/zero | No jobs ran in the given time window | Widen the `--time-range` (try 43200 for 30 days) |
+
+---
+
+## 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 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.
+- **Don't use this skill for root-cause debugging.** "Why did job X fail with error Y?" is a troubleshooting question — hand off to uipath-troubleshoot. This skill answers "which processes fail the most and what are the common reasons."
+
+---
+
+## References
+
+For deeper guidance, read these files only when needed:
+
+- [`references/jobs-commands-guide.md`](references/jobs-commands-guide.md) — Full command reference with all options, response shapes, and example outputs
+- [`references/investigation-playbook-guide.md`](references/investigation-playbook-guide.md) — Step-by-step playbooks for common investigation scenarios

package/skills/uipath-insights/references/investigation-playbook-guide.md

@@ -0,0 +1,145 @@
+# Insights — Investigation Playbooks
+
+Step-by-step playbooks for common job monitoring scenarios. Each playbook shows the exact commands to run and how to interpret the results.
+
+## Playbook 1: "How healthy are my automations?"
+
+User asks about overall automation health, success rates, or general status.
+
+```bash
+# Step 1: Get the summary KPIs
+uip insights jobs summary --time-range 1440 --output json
+
+# Step 2: Interpret the results
+# - jobsCount: total jobs in the time window
+# - successfulJobsCount: jobs that completed successfully
+# - averageProcessingTime: mean execution time in seconds
+#
+# Failure rate = (jobsCount - successfulJobsCount) / jobsCount * 100
+#
+# Thresholds (rules of thumb):
+#   < 5% failure rate  → healthy
+#   5-15% failure rate → needs attention
+#   > 15% failure rate → investigate immediately
+```
+
+If the failure rate is concerning, move to Playbook 2.
+
+## Playbook 2: "Which processes are failing?"
+
+User wants to know what's breaking.
+
+```bash
+# Step 1: Get processes ranked by failure count (use 30 days for a broader view)
+uip insights jobs top-failures --time-range 43200 --output json
+
+# Step 2: Get the failure reasons
+uip insights jobs failures-by-reason --time-range 43200 --output json
+
+# Step 3: Present findings as a table:
+# | Process Name | Failure Count | Top Reason |
+# |---|---|---|
+# | Invoice_Processing | 23 | ApplicationException: File not found |
+# | Email_Parser | 15 | TimeoutException: SMTP server unreachable |
+```
+
+## Playbook 3: "Why did this specific process fail?"
+
+User asks about failures in a specific process.
+
+```bash
+# Step 1: Filter failures to that process
+uip insights jobs failures-by-reason --time-range 1440 \
+  --process-name "Invoice_Processing" --output json
+
+# Step 2: Get detailed failure info (machine, timestamps, error messages)
+uip insights jobs failure-details --time-range 1440 \
+  --process-name "Invoice_Processing" --output json
+
+# Step 3: Check if it's a recent regression with the timeline
+uip insights jobs completed-timeline --time-range 10080 \
+  --process-name "Invoice_Processing" --output json
+
+# Step 4: Present findings:
+# - Most common error reason
+# - Which machines are affected
+# - When failures started (trend direction)
+# - Recommended next steps
+```
+
+## Playbook 4: "Are there stuck or long-running jobs?"
+
+User asks about jobs that haven't completed.
+
+```bash
+# Step 1: Check uncompleted jobs
+uip insights jobs uncompleted-timeline --time-range 1440 --output json
+
+# Step 2: Get the summary to compare completed vs uncompleted
+uip insights jobs summary --time-range 1440 --output json
+
+# Step 3: If many uncompleted, check per-process breakdown
+uip insights jobs process-details --time-range 1440 --output json
+```
+
+## Playbook 5: "Compare this week vs last week"
+
+User wants to see if things are getting better or worse.
+
+```bash
+# This week (last 7 days)
+uip insights jobs summary --time-range 10080 --output json
+
+# For last week, use absolute timestamps
+# Calculate: last Monday to this Monday in epoch ms
+uip insights jobs summary \
+  --started-after <last-monday-epoch-ms> \
+  --started-before <this-monday-epoch-ms> \
+  --output json
+
+# Compare jobsCount, successfulJobsCount, and averageProcessingTime
+# between the two results
+```
+
+## Playbook 6: "Show me jobs for a specific folder"
+
+User asks about a specific Orchestrator folder.
+
+```bash
+# Step 1: Find the folder key (requires uipath-platform)
+uip or folders list --output json
+# Look for the folder's Key (GUID) in the output
+
+# Step 2: Query insights with folder filter
+uip insights jobs summary --time-range 1440 \
+  --folder-key "abc-123-def" --output json
+
+uip insights jobs top-failures --time-range 1440 \
+  --folder-key "abc-123-def" --output json
+```
+
+## Interpreting Array Data
+
+Several endpoints return parallel arrays. The same index across arrays corresponds to the same entity:
+
+```json
+{
+  "processName": ["ProcessA", "ProcessB", "ProcessC"],
+  "jobCountByTime": [[10, 5, 2]]
+}
+```
+
+This means:
+- ProcessA had 10 failures
+- ProcessB had 5 failures
+- ProcessC had 2 failures
+
+## When to Hand Off to Other Skills
+
+| Situation | Hand off to |
+|---|---|
+| User wants to start/stop/restart a specific job | `uipath-platform` (`uip or jobs start`) |
+| User wants to read the logs of a failed job | `uipath-platform` (`uip or jobs logs`) |
+| User wants to debug why a specific job error happened | `uipath-troubleshoot` |
+| User wants to find a folder key to filter by | `uipath-platform` (`uip or folders list`) |
+| User wants to fix the code that's causing failures | `uipath-rpa` or `uipath-agents` |

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

@@ -0,0 +1,144 @@
+# Insights Jobs — Command Reference
+
+Complete reference for `uip insights jobs` subcommands with response shapes and examples.
+
+## Shared Options
+
+Every subcommand accepts these filter options:
+
+```
+--time-range <minutes>         Relative time range (e.g. 1440 = 24h, 43200 = 30d)
+--started-after <epoch-ms>     Absolute start time as Unix epoch milliseconds
+--started-before <epoch-ms>    Absolute end time as Unix epoch milliseconds
+--folder-key <guid>            Folder key filter (repeatable)
+--process-name <name>          Process name filter (repeatable)
+--machine-name <name>          Machine name filter (repeatable)
+--timezone-offset <minutes>    Client timezone offset from UTC
+--output <format>              Output format: json, yaml, table (always use json)
+```
+
+**Time range rule:** Either `--time-range` OR both `--started-after` and `--started-before` must be provided. Omitting both causes a validation error.
+
+**Repeatable options:** `--folder-key`, `--process-name`, and `--machine-name` can be specified multiple times:
+```bash
+uip insights jobs summary --time-range 1440 \
+  --process-name "ProcessA" \
+  --process-name "ProcessB" \
+  --output json
+```
+
+## Response Envelope
+
+All commands return:
+```json
+{
+  "Result": "Success",
+  "Code": "<CommandCode>",
+  "Data": { ... }
+}
+```
+
+On error:
+```json
+{
+  "Result": "Failure",
+  "Message": "<error description>",
+  "Instructions": "<how to fix>",
+  "ErrorCode": "unknown_error"
+}
+```
+
+## Response Data Shape
+
+All endpoints return the same `JobsResponse` shape. Fields are populated or null depending on the endpoint:
+
+```typescript
+interface JobsResponse {
+  jobState: string[] | null;
+  robotName: string[] | null;
+  processName: string[] | null;
+  jobCount: number[] | null;
+  jobCountByTime: number[][] | null;
+  folderName: string[] | null;
+  folderKey: string[] | null;
+  machineName: string[] | null;
+  hostMachineName: string[] | null;
+  machineKey: string[] | null;
+  machineStatus: string[] | null;
+  timestamp: string[] | null;
+  processExceptionType: string[] | null;
+  processExceptionReason: string[] | null;
+  startTime: string[] | null;
+  endTime: string[] | null;
+  utilizationTime: string[] | null;
+  duration: number[] | null;
+  successRate: number[] | null;
+  averageProcessingTime: number | null;
+  jobsCount: number | null;
+  successfulJobsCount: number | null;
+  jobAggregate: number[][] | null;
+  creationTime: string[] | null;
+  folderId: string[] | null;
+  jobKey: string[] | null;
+}
+```
+
+## Per-Endpoint Key Fields
+
+| Endpoint | Code | Key Data Fields |
+|----------|------|-----------------|
+| `summary` | `InsightsJobsSummary` | `jobsCount`, `successfulJobsCount`, `averageProcessingTime` |
+| `completed-timeline` | `InsightsJobsCompletedTimeline` | `jobState`, `jobCountByTime`, `timestamp` |
+| `uncompleted-timeline` | `InsightsJobsUncompletedTimeline` | `jobState`, `jobCountByTime`, `timestamp` |
+| `top-failures` | `InsightsJobsTopFailures` | `processName`, `jobCountByTime` |
+| `failures-by-reason` | `InsightsJobsFailuresByReason` | `processExceptionReason`, `processName`, `robotName`, `jobsCount` |
+| `process-details` | `InsightsJobsProcessDetails` | `processName`, `jobAggregate` |
+| `failure-details` | `InsightsJobsFailureDetails` | `processName`, `machineName`, `processExceptionReason`, `startTime`, `endTime` |
+
+## Example: Summary
+
+```bash
+$ uip insights jobs summary --time-range 1440 --output json
+{
+  "Result": "Success",
+  "Code": "InsightsJobsSummary",
+  "Data": {
+    "jobsCount": 142,
+    "successfulJobsCount": 135,
+    "averageProcessingTime": 45.7,
+    "jobState": null,
+    "processName": null,
+    ...
+  }
+}
+```
+
+Deriving metrics:
+- **Failure rate:** `(jobsCount - successfulJobsCount) / jobsCount * 100`
+- **Success rate:** `successfulJobsCount / jobsCount * 100`
+
+## Example: Top Failures with Filter
+
+```bash
+$ uip insights jobs top-failures --time-range 43200 \
+    --folder-key "a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
+    --output json
+{
+  "Result": "Success",
+  "Code": "InsightsJobsTopFailures",
+  "Data": {
+    "processName": ["Invoice_Processing", "Email_Parser", "Data_Upload"],
+    "jobCountByTime": [[23, 15, 8]],
+    ...
+  }
+}
+```
+
+The `processName` array and `jobCountByTime[0]` array are parallel — index 0 of both corresponds to the same process.
+
+## API Details
+
+- **Base URL:** `{host}/{orgId}/{tenantName}/insightsrtm_/api/v1.0/InsightsJobs/{endpoint}`
+- **Method:** POST (all endpoints)
+- **Auth:** Bearer token + `X-UiPath-Internal-AccountName` + `X-UiPath-Internal-TenantName` headers
+- **The CLI handles all of this.** Do not construct raw API calls — use `uip insights jobs <subcommand>`.

package/skills/uipath-ixp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uipath-ixp
-description: "UiPath IXP (Document Understanding) via `uip ixp` — create projects (with autopilot taxonomy suggestion, an imported taxonomy file, or empty), upload/download/delete documents, author the taxonomy (field groups, fields, data types, per-field and overall extraction instructions), configure the extraction model and pre-processing, review/confirm/unconfirm predictions, mark fields missing, pull metrics and model versions, publish/tag/roll back model versions. For IxP nodes or model listings inside a .flow / Maestro flow→uipath-maestro-flow."
+description: "UiPath IXP (Document Understanding) via `uip ixp` — create projects (with autopilot taxonomy suggestion, an imported taxonomy file, or empty), upload/download/delete documents, author the taxonomy (field groups, fields, data types, per-field and overall extraction instructions), configure the extraction model and pre-processing, review/confirm/unconfirm predictions, mark fields missing, pull metrics and model versions, publish/tag/roll back model versions. DO NOT TRIGGER during .flow / Maestro Flow work — discovering or listing IxP / document-extraction models, extractors, or nodes available to Maestro Flow, and adding or wiring an IxP node, belong to uipath-maestro-flow even when they sound like IXP model management."
 ---
 
 # UiPath IXP Document Extraction Assistant
@@ -50,6 +50,8 @@ Do not answer these from this skill. Re-activate `uipath-maestro-flow` and follo
 13. **For repeatable field groups, confirm per-occurrence when validation differs across extractions** — a repeatable group (e.g. `Line Items`) produces one extraction per physical line/section. Plain `confirm --fields <id>` confirms `<id>` in **every** occurrence, so if only some lines are correct it confirms the wrong ones too. Each label in `get-predictions` carries an explicit 0-based `Occurrence` (repeated same-named labels appear in document order); if all occurrences are correct use the plain form, otherwise target with `--group`. `--group <name> --occurrence <N>` confirms **ONE** occurrence; `--group <name> --updates '[...]'` confirms **SEVERAL** in one atomic call (avoids N round-trips) — `--occurrence <N>` ≡ a single-entry `--updates`, same per-occurrence logic. `--group` must be the FULL label path from the `Name` field (e.g. `"Invoice > Line Items"`), not the leaf. Without `--fields`, every predicted field in the occurrence is confirmed; with it, only those. Occurrences not selected keep their existing annotation. Flag details: [CLI Reference](references/cli-reference.md#labellings).
 14. **`confirm` is additive — it never un-confirms.** The labelling endpoint is full-replacement, so `confirm`/`mark-missing` carry every existing annotation forward: `--occurrence 0` on an already-labelled table yields "row 0 confirmed AND everything previously confirmed stays confirmed" — NOT "only row 0". To roll back a confirmation, use `unconfirm` (see the task-navigation table).
 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; 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 (project / group / field / data type). 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).
 
 ## Quick Start
 
@@ -68,7 +70,7 @@ If the user provides a taxonomy file, use `--skip-taxonomy` and `import-taxonomy
 | "Import this taxonomy" / provides a taxonomy file | [Project Setup Guide](references/project-setup-guide.md) — Option B (`--skip-taxonomy` + `import-taxonomy`) |
 | "Label documents" / "Review predictions" | [Label Documents Guide](references/label-documents-guide.md) |
 | "Improve scores" / "Fix prompts" / "Improve F1" | [Improve Prompts Guide](references/improve-prompts-guide.md) |
-| "Publish the model" / "Tag as live" | `uip ixp projects publish <project-name> --output json` — publishes the latest version, untagged. Add `--tag <live\|staging>` to also tag it. See [cli-reference](references/cli-reference.md) for `--model-version`/`--description`. |
+| "Publish the model" / "Tag as live" | `uip ixp projects publish <project-name> --output json` — publishes the latest version, untagged. Add `--tag <live\|staging>` to also tag it. See [cli-reference](references/cli-reference.md) for `--model-version`/`--description`. **Publishing does not deploy the model to an Orchestrator folder** — folder/environment binding is a product-side step with no `uip ixp` (or other CLI) equivalent, so publishing is the last step this skill performs. Don't chain a folder deployment onto it, deploy locally, or improvise another path. Only when the user explicitly asks to deploy to a folder/environment do you hand that back to them (it's done in-product) — see the "Deploy this model" row under [Unsupported Capabilities](#unsupported-capabilities). Deploying to a folder is what makes the model available to downstream consumers such as Maestro Flow. |
 | "Roll back to a previous version" / "Restore version N" | `uip ixp projects publish <project-name> --model-version <N> --output json` — re-publishes an earlier version. Get available versions from `uip ixp projects list-models <project-name> --output json`. |
 | "Unpublish a model" / "Take a model out of production" | `uip ixp projects unpublish <project-name> --model-version <N> --output json` — removes a version from the published set (it stays trained/listable). `--model-version` is required; find published versions via `list-models` (`Pinned: true`). To change which version is live, `publish` a different one instead. |
 | "Remove the live/staging tag" / "Untag a version" | `uip ixp projects untag <project-name> --tag <live\|staging> --output json` — removes the named tag (the version it pointed at stays published). **`untag` is the only way to remove a tag** — do NOT `unpublish` or re-`publish` to clear it (`unpublish` removes publication, not the tag; `publish` without `--tag` leaves the existing tag untouched). To switch `live`→`staging`, `publish --tag staging` instead. |
@@ -79,8 +81,9 @@ If the user provides a taxonomy file, use `--skip-taxonomy` and `import-taxonomy
 | "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. |
+| "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`. |
+| "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. |