@uipath/skills 1.197.2 → 1.198.0-preview.21

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

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

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

@@ -2,7 +2,7 @@
 
 All commands use `uip ixp` prefix. Always append `--output json` when parsing output programmatically.
 
-> **Destructive commands require `-y, --yes`.** Every irreversible `uip ixp` command (all `delete`s and `fields change-type`) gates on `-y/--yes`; the CLI never prompts. `--confirm-data-loss` is accepted but is a **deprecated no-op** — it does NOT satisfy the confirmation, so always pass `-y/--yes`.
+> **Destructive commands require `-y, --yes`.** Every irreversible `uip ixp` command (all `delete`s and `fields change-type`) gates on `-y/--yes`; the CLI never prompts. Always pass `-y/--yes`.
 
 ## Projects
 
@@ -76,13 +76,28 @@ Manage the reusable type definitions (entity_defs) that fields reference via `fi
 | `uip ixp data-types rename <project-name> --name <name> --new-name <name> --output json` | Rename a data type. Existing field references (via `field_type_id`) stay intact. |
 | `uip ixp data-types delete <project-name> --name <name> -y --output json` | Delete a data type. **IRREVERSIBLE** — any field referencing it via `field_type_id` will break. `-y, --yes` is **required** (the CLI never prompts). |
 
+### Default data types
+
+Every IXP project ships with the built-in data types below (the project's `entity_defs` from `projects get-taxonomy` are the authoritative list). **Before `data-types add`, or before choosing a field's `--type` (in `fields add` / `groups add`), check the existing `entity_defs` and reuse a matching default.** A redundant custom type (e.g. a `Currency Amount` when `Monetary Quantity` already exists) splits annotations across two types and forfeits the default's pre-trained model. Add a new data type only when it carries something no default does — a `Choice`, or a reusable concept that needs its own tailored extraction instructions — not as a clone of a default.
+
+| Default type | `--kind` | `--input-value` | Reuse for |
+|--------------|----------|-----------------|-----------|
+| `Exact Text` | `text` | `exact-match` | Text copied verbatim from the document — names, IDs, addresses, codes |
+| `Inferred Text` | `text` | `inferred` | Text derived/computed, not appearing verbatim in the document |
+| `Number` | `number` | — | Counts, quantities, plain numbers |
+| `Date` | `date` | — | Dates |
+| `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 …`).
+
 ## Groups
 
 Manage field groups (label_defs) — the document type containers for fields. To edit fields **inside** an existing group, use the `fields` subject below.
 
 | Command | Description |
 |---------|-------------|
-| `uip ixp groups add <project-name> --name <group-name> --instructions <text> --fields <json> --output json` | Create a new field group with its fields. `--instructions` describes what document/section the group covers (the model sees it during extraction). `--fields` is a JSON array `[{"name":"...","type":"<type-name>","instructions":"..."}]` — **put ALL of the new group's fields in this one array (batch); do NOT create the group then add its fields one at a time.** Every entry must include `name`, `type`, and a non-empty `instructions`. `type` resolves against the project's `entity_defs`. To add a field to an **already-existing** group, use `fields add` instead. |
+| `uip ixp groups add <project-name> --name <group-name> --instructions <text> --fields <json> --output json` | Create a new field group with its fields. `--instructions` describes what document/section the group covers (the model sees it during extraction). `--fields` is a JSON array `[{"name":"...","type":"<type-name>","instructions":"..."}]` — **put ALL of the new group's fields in this one array (batch); do NOT create the group then add its fields one at a time.** Every entry must include `name`, `type`, and a non-empty `instructions`. `type` resolves against the project's `entity_defs` — reuse a [default data type](#default-data-types) before inventing a new one. To add a field to an **already-existing** group, use `fields add` instead. |
 | `uip ixp groups delete <project-name> --name <group-name> -y --output json` | Delete a field group. **IRREVERSIBLE** — deletes all annotations on all fields in the group. `-y, --yes` is **required** (the CLI never prompts). |
 | `uip ixp groups rename <project-name> --name <group-name> --new-name <name> --output json` | Rename a field group. Preserves all fields and annotations. |
 | `uip ixp groups update-prompts <project-name> --updates <json> --output json` | Bulk-update field group (label_def) instructions. `--updates` is a JSON array `[{"name":"<group>","instructions":"..."}]` matched by group name. Existing fields are preserved. Unmatched names are reported in the response without failing the command. |
@@ -93,7 +108,7 @@ Structural edits to a field within an existing field group. For instruction-only
 
 | Command | Description |
 |---------|-------------|
-| `uip ixp fields add <project-name> --group <field-group-name> --field <name> --type <type-name> --instructions <text> --output json` | Add a new field to an **existing** field group. `--type` is the name of an entity_def in the project's taxonomy (see `projects get-taxonomy`). `--instructions` is required — describe what to extract and where it appears. |
+| `uip ixp fields add <project-name> --group <field-group-name> --field <name> --type <type-name> --instructions <text> --output json` | Add a new field to an **existing** field group. `--type` is the name of an entity_def in the project's taxonomy (see `projects get-taxonomy`) — reuse a [default data type](#default-data-types) (e.g. `Monetary Quantity` for a currency amount) before adding a custom one. `--instructions` is required — describe what to extract and where it appears. |
 | `uip ixp fields delete <project-name> --group <field-group-name> --field <name> -y --output json` | Remove a field from a field group. `-y, --yes` is **required** (the CLI never prompts). |
 | `uip ixp fields rename <project-name> --group <field-group-name> --field <name> --new-name <name> --output json` | Rename a field. Preserves `field_id` and existing annotations. |
 | `uip ixp fields change-type <project-name> --group <field-group-name> --field <name> --type <type-name> -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). |

package/skills/uipath-maestro-bpmn/references/cli-conventions.md

@@ -25,6 +25,8 @@ particular, there is **no** `uip maestro bpmn validate` command — see
 [Validation](structural-bpmn.md#validation). Validation is done with the bundled
 offline validator, not a CLI.
 
+> **Don't conclude "it doesn't exist" from truncated discovery output.** A row past a cutoff reads exactly like a missing row. Two cutoffs bite here: `registry list` defaults to **30** — pass `--limit -1` for the full set — and piping `registry search`/`is connections list` through `head`/`tail`/`grep -m`/a pager drops everything past the cap. To check existence, narrow the query (keyword to `registry search`, `--all-folders` to connection lists) rather than capping rows; cap only data already known complete.
+
 ## Output parsing
 
 Whenever a CLI result is parsed programmatically, pass `--output json`. If a