@uipath/skills 1.201.0-preview.621 → 1.201.0-preview.637

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/skills",
-  "version": "1.201.0-preview.621",
+  "version": "1.201.0-preview.637",
   "description": "UiPath agent skills for Claude Code, Codex, Cursor, Copilot, Gemini and OpenCode — RPA, UI automation, UI testing, coded agents/apps/workflows, and troubleshooting. Distributed as the UiPath Claude Code plugin.",
   "author": {
     "name": "UiPath"

package/skills/uipath-automationhub/SKILL.md

@@ -68,5 +68,6 @@ Every addition keeps the skill's three invariants: collect inputs before the fir
 ## Notes
 
 - **Cloud token only** — authorization is the user's real AH permissions; you see and can do exactly what their AH role allows.
+- **If Automation Hub isn't available on the tenant, say so plainly and stop** — never let it surface as a generic failure. Two cases with **different remedies**: *not enabled* (only an admin can fix it) and *reachable but never onboarded* (self-service). Signals, and the exact wording to quote verbatim rather than paraphrase, live in one home per transport: [`references/api-endpoints.md`](references/api-endpoints.md) → **Automation Hub not available on this tenant** for the raw-API flows, [`references/cli-commands.md`](references/cli-commands.md) → same heading for the CLI flows.
 - The publish flow fetches the idea-flow schema live, so it adapts automatically if fields change on the tenant.
 - **Open dependency:** in a hosted runtime (e.g. Process Scribe/Delegate) the cloud token is expected via the environment (Authentication, option 1). Confirm the runtime provides `UIPATH_CLI_AUTH_TOKEN` (or an equivalent) before relying on it in production.

package/skills/uipath-automationhub/references/api-endpoints.md

@@ -138,5 +138,27 @@ Linked components for the process.
 | 400 | Validation — missing required field, invalid enum, empty `user_inputs`, missing `OVERVIEW_NAME` |
 | 401 | Unauthorized — token missing/expired, or `x-ah-openapi-auth` was wrongly sent |
 | 403 | Forbidden — the user lacks the AH permission (authorization = the user's real AH role) |
-| 404 | Wrong URL, or AH not enabled on the tenant |
+| 404 | Wrong URL, or AH not available on the tenant — see **Automation Hub not available on this tenant** below |
 | 409 | Duplicate process name |
+
+### Automation Hub not available on this tenant
+
+Two distinct cases, with **different remedies** — don't collapse them, the advice differs:
+
+**1. AH is not enabled for the tenant.** The tenant has no Automation Hub service at all. Signals: a **404** whose body says `not found in organization`, or a **3xx redirect** to `portal_/unregistered` (following it would surface an HTML portal page as a JSON parse error). The user cannot fix this themselves — report exactly:
+
+> Please contact your administrator to enable Automation Hub on this tenant.
+
+**2. AH is reachable but the tenant was never onboarded into it.** The service answers **422 Tenant Lookup Error** on every call. This one *is* self-service — report exactly:
+
+> Automation Hub is reachable for this tenant but has not finished setup. Open Automation Hub in the browser once to complete it, then retry.
+
+In both cases: **stop after reporting** — do not retry, do not fall back to an admin OpenAPI token, and do not attempt the write against another tenant unless the user asks. Quote the message verbatim; don't paraphrase it.
+
+**Making the signals observable from `curl`.** `curl` reports the status but not *where* a 3xx points, so the first call each flow makes against the tenant asks for both:
+
+```bash
+curl -s -w "\n%{http_code} %{redirect_url}" …
+```
+
+The last line is then `<status> <redirect target>`: `%{redirect_url}` is empty on any non-3xx and carries the resolved `Location` on a 3xx — which is what makes the `portal_/unregistered` case above distinguishable from an ordinary redirect. **Never add `-L`.** Following the redirect throws away the one diagnosable signal and hands you an HTML portal page, which then fails as a JSON parse error — exactly the generic failure this section exists to prevent.

package/skills/uipath-automationhub/references/cli-commands.md

@@ -12,6 +12,17 @@ The CLI wraps the same Open API endpoints as [`api-endpoints.md`](api-endpoints.
 
 If a command fails with an authentication error, tell the user to run `uip login` — never ask for or handle a raw token yourself.
 
+## Automation Hub not available on this tenant
+
+The CLI already classifies this for you — read its `Instructions` field:
+
+- `Instructions` mentioning **"not provisioned on this tenant"** → AH is not enabled. Report: *"Please contact your administrator to enable Automation Hub on this tenant."*
+- `Instructions` mentioning **"no tenant record of its own yet"** → reachable but not onboarded. Report: *"Automation Hub is reachable for this tenant but has not finished setup. Open Automation Hub in the browser once to complete it, then retry."*
+
+Either way **stop** — don't retry and don't try another tenant unless asked, and quote the message verbatim rather than paraphrasing it.
+
+> This section is the **canonical wording for the CLI path**; the CLI flows reference it instead of restating it, so each message exists in exactly one place per transport (raw-API twin: [`api-endpoints.md`](api-endpoints.md) → **Automation Hub not available on this tenant**, which also carries the raw signals behind each case). The two homes exist because the CLI files stay self-contained for the day the raw-API fallback retires — keep them in sync if the wording ever changes.
+
 ## Output envelope (every command)
 
 Always pass `--output json`. Success:

package/skills/uipath-automationhub/references/get-process-cli-guide.md

@@ -19,6 +19,8 @@ Fetches one process (by id or search) and its documents, and downloads document
 uip ah automations get $PROCESS_ID --output json
 ```
 
+If the command fails with `Instructions` about AH **not being provisioned** on the tenant, or about the tenant having **no AH record yet**, report the message for the matching case, verbatim, from [`cli-commands.md`](cli-commands.md) → **Automation Hub not available on this tenant**, and stop.
+
 `Data` is the projected record (`Id`, `Name`, `Phase`, `PhaseStatus`, `Tags`, …). Add `--all-fields` only when you need the raw record (e.g. `process_slug` for the deep link). `Failure` with not-found → no such process; auth error → `uip login`.
 
 ## Step 3: Fetch the documents

package/skills/uipath-automationhub/references/get-process.md

@@ -9,19 +9,22 @@ Fetches one process (by id or search) and its documents from Automation Hub, aut
 - If the caller gives a **process id**, use it directly.
 - Otherwise search by name:
   ```bash
-  curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
+  curl -s -w "\n%{http_code} %{redirect_url}" -H "Authorization: Bearer $ACCESS_TOKEN" \
     "$BASE_URL/$ORG/$TENANT/automationhub_/api/v1/openapi/automations?search=$QUERY&limit=20"
   ```
-  If one clear match → use its `process_id`. If several → show a short list (name + id + owner) and ask the user to pick. If none → tell the user and stop.
+  The last line is `<status> <redirect target>` (empty target unless 3xx). Check it **before** the results: a **404 / 3xx to `portal_/unregistered` / 422 tenant lookup** means AH isn't available on this tenant at all — handle it as in Step 2, don't report it as "no match". Never add `-L`.
+
+  On a 200: one clear match → use its `process_id`. If several → show a short list (name + id + owner) and ask the user to pick. If none → tell the user and stop.
 
 ## Step 2: Fetch the process
 
 ```bash
-curl -s -w "\n%{http_code}" -H "Authorization: Bearer $ACCESS_TOKEN" \
+curl -s -w "\n%{http_code} %{redirect_url}" -H "Authorization: Bearer $ACCESS_TOKEN" \
   "$BASE_URL/$ORG/$TENANT/automationhub_/api/v1/openapi/automations/$PROCESS_ID"
 ```
+The last line is `<status> <redirect target>` (empty target unless 3xx) — the target is what separates a `portal_/unregistered` redirect from any other 3xx. Never add `-L`.
 - **200** → keep the record; project to the useful fields for display (name, status/phase, category, owner, description). The raw record is large — don't dump it all unless asked.
-- **401** → re-authenticate. **403** → the user can't view this process. **404** → no such process.
+- **401** → re-authenticate. **403** → the user can't view this process. **404** → no such process — *unless* the body says `not found in organization` (or the call 3xx-redirects to `portal_/unregistered`, or answers **422 tenant lookup**), which means AH itself is not available on this tenant: report the message for the matching case, verbatim, from [`api-endpoints.md`](api-endpoints.md) → **Automation Hub not available on this tenant**, and stop.
 
 ## Step 3: Fetch the documents
 

package/skills/uipath-automationhub/references/publish-process-cli-guide.md

@@ -12,7 +12,7 @@ uip ah idea-flows list --output json
 
 - `Result: Success` → keep `Data` (flow names + ids) and tell the user "Connected to Automation Hub."
 - Auth failure → tell the user to run `uip login` (or, in Delegate, to sign in). Never ask for a raw token.
-- `Failure` mentioning the tenant/enablement → AH is not enabled on this tenant; stop.
+- `Failure` mentioning the tenant/enablement → AH is not available on this tenant. Report the message for the matching case, verbatim, from [`cli-commands.md`](cli-commands.md) → **Automation Hub not available on this tenant** — then **stop**; nothing later in this flow can succeed.
 
 ## Step 2: Pick the idea flow
 

package/skills/uipath-automationhub/references/publish-process.md

@@ -9,15 +9,17 @@ Creates one process in Automation Hub from a schema-driven payload and attaches
 Verify the resolved token with a cheap call — this also fetches the idea flows you need next:
 
 ```bash
-curl -s -w "\n%{http_code}" \
+curl -s -w "\n%{http_code} %{redirect_url}" \
   -H "Authorization: Bearer $ACCESS_TOKEN" \
   "$BASE_URL/$ORG/$TENANT/automationhub_/api/v1/openapi/idea-flows"
 ```
 
+The last line is `<status> <redirect target>` — the target is empty unless the response was a 3xx. Read both: a 3xx alone is ambiguous, a 3xx **to `portal_/unregistered`** is the tenant-not-enabled signal below. Never add `-L`.
+
 - **200** → save the `data` array (reused in Step 2) and tell the user "Connected to Automation Hub."
 - **401** → token missing/expired: if it came from `~/.uipath/.auth`, ask the user to run `uip login` again; re-resolve and retry. **Never** add `x-ah-openapi-auth` to "fix" a 401 — that routes to the admin-token path and guarantees failure.
 - **403** → the user is authenticated but lacks AH access on this tenant.
-- **404 / network** → wrong URL or AH not enabled; confirm the org/tenant.
+- **404 / 3xx to `portal_/unregistered` / 422 tenant lookup** → AH is not available on this tenant. Confirm the org/tenant first; if they're right, report the message for the matching case, verbatim, from [`api-endpoints.md`](api-endpoints.md) → **Automation Hub not available on this tenant** — then **stop**.
 
 Do not proceed until you have a 200.
 

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

@@ -15,7 +15,7 @@ All commands use `uip ixp` prefix. Always append `--output json` when parsing ou
 | `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. `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 TRAINED version, which is NOT necessarily the published/live one** — resolve the version from `list-models` and pass it as `--model-version <N>` whenever you report a score, so the numbers and the version identity match (SKILL.md Critical Rule 21). Field semantics — which values decide and which are derived — are in [Improve Prompts Guide § What get-metrics returns](improve-prompts-guide.md#what-get-metrics-returns-and-which-values-decide). `ErrorRate` is `errors / Annotations` (it counts misses — not `1 - Precision`); the `Quality`/`ProjectScoreQuality` labels use inconsistent scales — never gate on them. |
+| `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`, `Name`, `F1`, `Precision`, `Recall`, `ErrorRate`, `Documents`, `Annotations`, `Quality`). `Name` is the field's display name resolved from the taxonomy — report on it, but compare on `FieldId`, which is the stable key; it is `null` when the service could not resolve it (e.g. the field was deleted after that version was scored). Display names are unique only within a group, so qualify as `<FieldGroup> / <Name>` when two fields share one. Scores are surfaced at the backend's own precision — long tails like `0.824999988079071` are its float32 arithmetic widened to double, not extra accuracy; round when you display them, and compare the raw values. **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 TRAINED version, which is NOT necessarily the published/live one** — resolve the version from `list-models` and pass it as `--model-version <N>` whenever you report a score, so the numbers and the version identity match (SKILL.md Critical Rule 21). **Any version the backend ever scored is readable**, including older ones `list-models` no longer lists — that is what makes a version-to-version comparison possible; `not_found` on a version means the backend never scored it, not that it aged out. Field semantics — which values decide and which are derived — are in [Improve Prompts Guide § What get-metrics returns](improve-prompts-guide.md#what-get-metrics-returns-and-which-values-decide). `ErrorRate` is `errors / Annotations` (it counts misses — not `1 - Precision`); the `Quality`/`ProjectScoreQuality` labels use inconsistent scales — never gate on them. |
 | `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`. **The only read path for the project's live version** — `Tags[]` entry Name=`live`, else the highest `Models[]` with `Pinned: true`; which version a **folder** serves at runtime is a different question — [Deployments](#deployments). `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. |

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

@@ -55,7 +55,7 @@ The values `get-metrics` returns are neither independent nor interchangeable —
 | `ErrorRate` | field, group | **Report — independent of `Precision`.** Wrong extractions over `Annotations`. A wrong value counts **once** (not as a false positive plus a false miss), and a miss counts even though it cannot lower `Precision` — so `Precision` 1.00 can still carry `ErrorRate` 0.20. Report it as the manual-correction burden; diagnose direction from `Precision`/`Recall`. |
 | `Quality` | field | **Ignore.** A coarse label derived from the numbers, on a scale inconsistent with `ProjectScoreQuality` (an `F1` of 1.00 still reads `good` while a `ProjectScore` of 0.91 reads `excellent`). Never gate on it and don't report it per field — if the user asks about the UI's label, explain the scales differ. |
 | `ProjectScoreQuality` | project | **Report on the project line only** (the label the UI shows beside the score) — different scale from field `Quality` (above). |
-| `FieldGroup`, `FieldId` | field | Identity. `FieldId` needs the taxonomy join for a human-readable name (see 1a). |
+| `FieldGroup`, `FieldId`, `Name` | field | Identity. Compare on `FieldId` (stable); report on `Name` (the current display name — `null` for a deleted field, fall back to `FieldId`, see 1a). |
 
 
 ## Waiting for retrain
@@ -89,12 +89,11 @@ Note the `ModelVersion` from this baseline read — later iterations check that
 
 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:
+**Field names:** each `Fields` entry carries both `FieldId` and `Name`, so report and compare fields straight from the metrics — do NOT fetch the taxonomy to build an id→name map. Three rules:
 
-- For each metric entry: `FieldGroup` = label_def name, `FieldId` = the field's `field_id`
-- Find the matching field entry in the taxonomy where `field_id == FieldId` — its `name` is the human-readable field name
-
-Build this mapping once and reuse it throughout the loop.
+- **Compare on `FieldId`, report on `Name`.** `FieldId` is stable; `Name` reflects the taxonomy as it is now, so a field renamed since an older version was scored reads back under its current name.
+- **`Name` is null** when the service could not resolve it (e.g. the field was deleted after that version was scored). Fall back to `FieldId` — never skip the field.
+- **When two fields share a `Name`, qualify it with `FieldGroup`.** Display names are unique only *within* a group, so the same label can sit under two of them — print those rows as `<FieldGroup> / <Name>` or the reader cannot tell which one a score belongs to. This changes how you print the row, nothing else: the comparison still keys on `FieldId`.
 
 ### 1b. Check model configuration
 

package/version-manifest.json

@@ -1,5 +1,5 @@
 {
   "schemaVersion": 2,
-  "skillsVersion": "1.201.0-preview.621",
+  "skillsVersion": "1.201.0-preview.637",
   "targetCli": "^1.201.0"
 }