@uipath/skills 1.201.0-preview.621 → 1.202.0-preview.635

package/skills/uipath-platform/references/integration-service/reference-resolution.md

@@ -6,6 +6,7 @@ How to resolve reference fields — fields whose values must be looked up from a
 
 ## Contents
 - Reference IDs Are Connection-Scoped (CRITICAL)
+- When the Lookup Call Fails (CRITICAL)
 - Reference Fields (CRITICAL)
 - Scope Filtering (CRITICAL)
 - Search References (filterPattern)
@@ -31,6 +32,33 @@ A reused reference ID:
 
 ---
 
+## When the Lookup Call Fails (CRITICAL)
+
+The rules above assume `uip is resources run list` returns. When the call itself fails — `403`/`401` (expired, revoked, or reauthorization-required grant), a `5xx`, or a connector error — you have **no ID**, and there is no value you may write in its place.
+
+**Never substitute:**
+
+| Substitute | Why it is wrong |
+|---|---|
+| The display name you searched by | `reference.lookupValue` names the field to write; `lookupNames` only names the fields to match *against*. |
+| A vendor "well-known" alias | Accepted by some vendor APIs directly, but the connector stores what you write and the field is typed as an ID. |
+| An ID from context, memory, or another connection | See [Reference IDs Are Connection-Scoped](#reference-ids-are-connection-scoped-critical). |
+| A plausible-looking placeholder | Passes `describe` / `node configure` / `flow validate`; faults at runtime. |
+
+Every one of these produces an artifact that validates clean and fails later, with the original cause no longer visible.
+
+**Do this instead:**
+
+1. Retry per [agent-workflow.md — Error Recovery](agent-workflow.md#error-recovery) (max 2 semantic retries).
+2. On an auth failure, ping the connection (`uip is connections ping <id>`) to confirm the diagnosis.
+3. If it still fails, **stop and report**: name the connection, the object you could not list, and the vendor error. The fix is the user's (reauthorize, widen scopes, wait out an outage), not a value you choose.
+
+Non-interactively (CI/headless), stop and report the blocked step. Do not proceed with a value you could not verify.
+
+Say the resolve failed. Reporting a substituted value as "resolved" hides the fault from the only person who can fix it.
+
+---
+
 ## Reference Fields (CRITICAL)
 
 Entries in the describe `requestFields` AND `parameters` (query/path parameters) can have a `reference` section — their value must be looked up from another resource before executing. Scan both arrays: on some connectors the activity's primary input is a path parameter with a reference, and scanning only `requestFields` misses it.

package/skills/uipath-platform/references/integration-service/resources.md

@@ -66,6 +66,17 @@ Returns the full field breakdown for the specified operation:
 
 Results are cached locally. Use `--refresh` to bypass cache after re-auth or schema changes.
 
+### `--activity-version`
+
+Pass `--activity-version 4.0.0` only when the activity's `configuration` JSON reports `"version":"4.0.0"`. Otherwise do not pass the flag at all. Any value other than `1.0.0` (the default) or `4.0.0` fails with `Invalid --activity-version value`. `4.0.0` responses cache under a separate key (`<activity-name>.v4.schema.json`), so switching never serves the other version's metadata.
+
+The resource argument follows the same rule: `4.0.0` activities are addressed by **activity name** — pass the `activityName` from the `configuration` JSON (`4.0.0` metadata has no `objectName`). Everything else uses the object name.
+
+```bash
+uip is resources describe <connector-key> <object-name> --output json
+uip is resources describe <connector-key> <activity-name> --activity-version 4.0.0 --output json
+```
+
 ---
 
 ## Describe Failures

package/skills/uipath-platform/references/integration-service/triggers.md

@@ -169,10 +169,10 @@ Trigger filters narrow which events fire the trigger (e.g. only emails from a sp
 These steps assume the consuming skill has already loaded the trigger's `filterFields.fields` array (the source command varies by surface — e.g. maestro-flow uses `flow registry get`).
 
 1. For each user-intent condition, pick a matching `name` from `filterFields.fields` — using an unknown field name will be rejected by the CLI at configure time.
-2. Choose an operator based on the user's intent and the field type (see the operator table in the consuming skill — e.g. [uipath-maestro-flow > connector-trigger](../../../uipath-maestro-flow/references/author/references/plugins/connector-trigger/impl.md#supported-operators)).
+2. Choose an operator based on the user's intent and the field type (see the operator table in the consuming skill — e.g. [uipath-maestro-flow > connector-trigger](../../../uipath-maestro-flow/references/author/plugins/connector-trigger/impl.md#supported-operators)).
 3. Build one leaf per condition; place multiple conditions under the same `groupOperator` (`0` for AND, `1` for OR).
 4. If you need mixed AND/OR logic, use nested `groups` (same shape as the root tree).
-5. **Wrap string values in a `value` object** with `value`, `rawString` (verbatim user-entered text including quotes for strings), and `isLiteral: true` — passing a bare string fails validation. Expression values (`isLiteral: false`) are not yet supported by the CLI port.
+5. **Wrap string values in a `value` object** with `value`, `rawString` (verbatim user-entered text including quotes for strings), and `isLiteral` — passing a bare string fails validation. A filter-tree leaf operand may be dynamic (`isLiteral: false`, compiled to a `{var_…}` placeholder plus `filterVariables`), but `eventParameters` must be literals, because a trigger is evaluated before any flow run exists.
 6. If `filterFields` is empty or absent, the trigger does not support filtering — omit `filter` entirely. Do not invent an "empty" expression.
 
 ### Mandatory filter parameters

package/skills/uipath-platform/references/licensing/diagnose/CAPABILITY.md

@@ -0,0 +1,80 @@
+# Diagnose — Investigate Licensing State Failures
+
+Capability index for diagnosing licensing symptoms via `uip platform`: entitlement gaps, allocation changes that did not take effect, and consumption reports that read wrong.
+
+> **Where you came from / where to go next.** Diagnose is downstream of Operate (a user lost access, an allocation did
+> not apply, a report read wrong). Fixes — `tenants licenses set`, `users licenses set`, `groups rules set` — are Operate
+> actions requiring explicit user consent after root cause analysis.
+>
+> **Scope boundary.** This capability diagnoses **licensing state**: which layer holds (or fails to hold) an entitlement,
+> and why a licensing command's result differs from what the user expected. It does NOT diagnose runtime faults that
+> merely *mention* a license (a job stuck Pending, Studio failing to start, a robot not connecting). For those the
+> licensing layer is one hypothesis among many — establish the entitlement facts here, then hand the runtime causal chain
+> to `uipath-troubleshoot`.
+>
+> **Inherits universal rules from [SKILL.md](../../../SKILL.md).** Use `uip platform ... --output json` for all diagnostic reads.
+
+## When to use this capability
+
+- A user or group lost (or never gained) a license bundle they should hold.
+- `tenants licenses set` reported success but `get` shows unchanged units.
+- A product code is absent from `get` output entirely.
+- Seat or unit totals do not reconcile against the purchased pool.
+- A consumables report reads zero, or lower/higher than the user expects.
+- An allocation cannot be applied because the code will not route to a tenant.
+- Determine whether a reported access failure is a licensing cause at all, before escalating.
+
+## Critical rules
+
+1. **Diagnose reads; Operate mutates.** Never run a `set` command while diagnosing — a `set` is an overlay that destroys the evidence of the prior state. Read first, present findings, let the user authorize the fix. Re-running the user's own `set` to "reproduce" the symptom is still a mutation. A CLI that appears disconnected is not permission to try it: an unauthenticated command is not guaranteed to fail, and if the credentials do resolve you have mutated production while diagnosing. To explain what a `set` did, read `get` and cite the documented semantics or `set --help` — never execute it.
+2. **Identify the layer before running anything.** Licensing is four independent layers (see [troubleshooting-guide.md](references/troubleshooting-guide.md#step-1-identify-the-layer)). A symptom answered at the wrong layer produces a confident wrong answer.
+3. **Read `get` before reasoning about `set`.** `quantity` is absolute, not a delta, and absent codes keep their current value. Without the starting state you cannot tell an ineffective `set` from a correctly-applied no-op.
+4. **Treat an absent row as a window question first.** `tenants licenses get` returns only products whose active interval contains the current time. Absent ≠ never allocated.
+5. **`consumed` and consumables totals lag.** Accountant-side aggregation is minutes behind job completion. Never conclude "nothing ran" from a fresh zero.
+6. **Do not infer seat-consumption semantics that the workflow guides do not document.** When reconciliation needs a rule that is not written down, say so and fall back to the portal or the REST APIs — do not derive it.
+7. **Do not expose private data.** Redact tenant URLs, account GUIDs, user emails, and tokens in summaries.
+
+## Workflow
+
+| Journey | Read |
+|---------|------|
+| Triage a licensing symptom (sequential ladder) | [references/troubleshooting-guide.md](references/troubleshooting-guide.md) |
+| Recognize a known failure pattern (lookup) | [references/failure-modes.md](references/failure-modes.md) |
+
+## Common tasks
+
+| I need to... | Read |
+|---|---|
+| Work out which licensing layer owns the symptom | [troubleshooting guide → Step 1](references/troubleshooting-guide.md#step-1-identify-the-layer) |
+| Investigate why a user lacks a bundle | [troubleshooting guide → Step 3](references/troubleshooting-guide.md#step-3-walk-the-user-bundle-layer) |
+| Diagnose an allocation that did not take effect | [failure modes → Allocation reported success but units unchanged](references/failure-modes.md#allocation-reported-success-but-units-unchanged) |
+| Explain a product code missing from `get` | [failure modes → Product code absent from get output](references/failure-modes.md#product-code-absent-from-get-output) |
+| Diagnose a zero or unexpected consumables figure | [failure modes → Consumables report reads zero or wrong](references/failure-modes.md#consumables-report-reads-zero-or-wrong) |
+| Explain why a code will not route to a tenant | [failure modes → Product code will not route](references/failure-modes.md#product-code-will-not-route-to-the-tenant) |
+| Reconcile seats against the purchased pool | [failure modes → Unit totals do not reconcile](references/failure-modes.md#unit-totals-do-not-reconcile) |
+| Decide whether licensing is the cause at all | [troubleshooting guide → Step 5](references/troubleshooting-guide.md#step-5-decide-whether-licensing-is-the-cause) |
+
+## Anti-patterns
+
+- **Never re-run the user's failed `set` to reproduce the symptom.** The command they described is the one command you must not run. Quote it in your write-up; do not execute it, and do not treat an offline or unauthenticated environment as a safe place to try it.
+- **Never run `set` to "test" a hypothesis.** `users licenses set` replaces the user's direct bundles and `groups rules set` replaces the whole rule — a diagnostic `set` silently revokes entitlements.
+- **Never conclude "no license" from the user-bundle layer alone.** Unattended runtime comes from the tenant allocation, not a user bundle; the two are separate license types.
+- **Never read a fresh `consumed: 0` as proof no work ran.** Check the window and the aggregation lag first.
+- **Never compare a scoped consumables figure to an account-wide one.** Under `--tenant`, `consumedFromOrgWithoutTenant` is suppressed to zero by design.
+- **Never claim a group member holds a bundle without checking `orphan`.** Orphaned rows still consume a lease until the rule is re-applied.
+- **Never guess a tenant key or bundle code.** Resolve them first — the resolver requires exactly one match.
+
+## References
+
+### Diagnose-scoped
+
+- [troubleshooting-guide.md](references/troubleshooting-guide.md) — layer-first triage ladder
+- [failure-modes.md](references/failure-modes.md) — recurring failure patterns
+
+### Cross-capability
+
+- [licensing.md](../licensing.md) — license hierarchy, product codes, response envelope
+- [tenant-allocations.md](../tenant-allocations.md) — tenant layer commands, field reference, error table
+- [user-licenses-allocations.md](../user-licenses-allocations.md) — user/group layer commands, code resolution, error table
+- [consumables-report.md](../consumables-report.md) — consumption modes, flag reference, error table
+- [../../orchestrator/setup-environment.md](../../orchestrator/setup-environment.md) — `uip or licenses`, the Orchestrator license-slot layer

package/skills/uipath-platform/references/licensing/diagnose/references/failure-modes.md

@@ -0,0 +1,147 @@
+# Failure Modes — Licensing
+
+Named failure patterns with symptom → cause → investigation → fix. Match the user's symptom to a pattern, then follow the investigation steps.
+
+These are keyed by **symptom** — what the user reports. For patterns keyed by **CLI error message** (you already have the error text in hand), use the `Error Conditions` table in the owning workflow guide instead: [tenant-allocations.md](../../tenant-allocations.md#error-conditions), [user-licenses-allocations.md](../../user-licenses-allocations.md#error-conditions), [consumables-report.md](../../consumables-report.md#error-conditions).
+
+All investigation commands are read-only. Never run a `set` while diagnosing.
+
+---
+
+## Allocation Reported Success But Units Unchanged
+
+**Symptom:** User ran `tenants licenses set`, it returned success, but `get` shows the old numbers — or numbers they did not expect.
+
+**Causes:**
+1. `quantity` treated as a delta — it is absolute, so `5` set the tenant to 5 rather than adding 5
+2. Codes omitted from the input file kept their previous quantity — `set` is an overlay, not a replace
+3. Applied to a different tenant than the one being inspected
+4. The value did apply, but a bundle window means `get` no longer returns that row
+5. Only some codes in the input routed; the rest were rejected per-code
+
+**Investigation:**
+1. Read current state: `uip platform tenants licenses get "<TENANT_KEY>" --output json`
+2. Ask for the exact input file used, and diff its codes against the `get` output — separate "code absent from input" (expected to be unchanged) from "code present in input but unchanged" (the real failure)
+3. Confirm the tenant key in the `set` command matches the one being inspected
+4. If a code is missing entirely rather than unchanged, switch to [Product code absent from get output](#product-code-absent-from-get-output)
+
+**Fix:** Cause 1 → re-issue with the intended absolute total. Cause 2 → include the code explicitly, with `quantity: 0` to zero it out. Cause 3 → re-issue against the correct tenant key. Cause 4 → see the window pattern below. Cause 5 → see the routing pattern below. Present the corrected `set` command; do not run it.
+
+---
+
+## Product Code Absent From `get` Output
+
+**Symptom:** A product the user knows is purchased and allocated does not appear in `tenants licenses get` at all.
+
+**Causes:**
+1. Bundle window — `get` returns only products whose active interval contains the current time. An expired bundle is hidden even with `allocated > 0` historically
+2. The code was never provisioned on this tenant's service licenses
+3. The SKU is not on the account at all
+
+**Investigation:**
+1. `uip platform tenants licenses get "<TENANT_KEY>" --output json` — note that every returned row carries `startDate` / `endDate`, so the returned rows tell you what "currently active" means for this account
+2. Check whether the same code appears for a different tenant — present elsewhere means provisioned on the account, absent on this tenant
+3. Attempting to allocate it will surface a routing error naming the cause — see the next pattern rather than guessing
+
+**Fix:** Cause 1 → renewal or window question; the CLI cannot extend a window. Causes 2 and 3 → the SKU must be provisioned through the portal first; `set` cannot introduce a new code. In all three, state that this is a provisioning action outside the CLI.
+
+---
+
+## Product Code Will Not Route To The Tenant
+
+**Symptom:** `tenants licenses set` fails for a specific code, complaining it cannot be routed, or that routing is ambiguous.
+
+**Causes:**
+1. The code is not already present on the tenant's service licenses — `set` adjusts existing codes, it cannot introduce new ones
+2. The same code exists on more than one of the tenant's service licenses, so the target is ambiguous
+
+**Investigation:**
+1. `uip platform tenants licenses get "<TENANT_KEY>" --output json` — a code absent here cannot be routed by `set`
+2. Distinguish the two: "cannot route" means absent; "ambiguous routing" means duplicated across service types, and the error names the service types involved
+
+**Fix:** Cause 1 → provision the SKU on the tenant through the portal, then re-run `set`. Cause 2 → the duplicate allocation must be resolved in the portal or via support; the CLI cannot disambiguate. Neither is fixable from the CLI — say so plainly rather than retrying.
+
+---
+
+## User Lacks A Bundle They Should Hold
+
+**Symptom:** One person cannot use a product others can, or reports losing access they previously had.
+
+**Causes:**
+1. Never assigned — no direct grant and no group rule covers them
+2. A later `users licenses set` replaced their direct bundles; anything absent from that input was revoked
+3. A `groups rules set` replaced the group rule, dropping the bundle for every member
+4. A group rule `quota` is filled, so this member gets no lease
+5. Their group row is `orphan: true` — the lease is consumed but not effective for them
+6. Account seats are exhausted, so no new lease could be granted
+
+**Investigation:**
+1. `uip platform users licenses get "<USER_EMAIL>" --output json` — read `source` on each row (`direct` vs `group`) and `leasedAt` for when it was granted
+2. If the expected code is absent, read the rule rather than the user: `uip platform groups rules details "<GROUP_NAME>" --output json` — check entitled bundles, `quota`, and the member's `orphan` flag. The rule header is on **stderr**
+3. Check seat availability: `uip platform users licenses available --output json`
+4. Compare `leasedAt` on their surviving bundles — a cluster of identical timestamps points to a bulk `set` that replaced their prior grants
+
+**Fix:** Cause 1 → assign directly or add to the group. Cause 2 → re-issue `users licenses set` with the **full** intended bundle list, not just the missing one. Cause 3 → re-issue `groups rules set` with the full rule. Cause 4 → raise the quota or grant directly. Cause 5 → re-apply the rule or fully remove the departed user to release the lease. Cause 6 → free seats or purchase more. Present the command; do not run it.
+
+---
+
+## Consumables Report Reads Zero Or Wrong
+
+**Symptom:** A consumption report shows zero, or a figure the user says is too low or too high.
+
+**Causes:**
+1. Aggregation lag — `consumed` and consumable totals are minutes behind job completion
+2. Window mismatch — with no `--start-date`/`--end-date`, every consumable uses **its own** bundle window, so rows in one summary can span different date ranges
+3. Scope suppression — under `--tenant`, `consumedFromOrgWithoutTenant` is deliberately zero; only tenant-pool and org-pool figures are populated
+4. Non-recursive folders — in `folders` mode, `consumedBySelf` excludes child folders, so a parent looks emptier than the subtree
+5. Comparing point-in-time totals as if they were running totals — `consumedAmount` and `consumedBySelf` are totals over the requested range
+6. Wrong unit — the code is not an active consumable in this organization, or is a runtime code rather than a consumable
+7. Reading a scoped figure against an account-wide expectation
+
+**Investigation:**
+1. Re-run with the window stated explicitly so every row shares one range:
+   ```bash
+   uip platform licenses consumables get --mode summary \
+     --start-date "<YYYY-MM-DD>" --end-date "<YYYY-MM-DD>" --output json
+   ```
+2. Compare scoped against unscoped — run once with `--tenant` and once without, and attribute the difference to suppression rather than to missing consumption
+3. For a per-day view, all four flags are required: `--mode daily --tenant <T> --unit <CODE> --start-date <D> --end-date <D>`
+4. Confirm the unit is a consumable at all — runtime codes (`UNATT`, `RU`, `TEU`) are allocated, not consumed; `PLTU` appears on both axes and is a common source of confusion
+5. For `folders` mode, sum the children yourself before comparing to a tenant total
+
+**Fix:** Cause 1 → re-query after the lag; do not report zero as fact. Causes 2, 3, 5, 7 → the number is correct, the comparison is not; explain the semantics. Cause 4 → reconstruct the tree and roll up. Cause 6 → pick a code from the list the CLI returns.
+
+---
+
+## Unit Totals Do Not Reconcile
+
+**Symptom:** Allocated plus available does not match what the user believes was purchased.
+
+**Causes:**
+1. Units reserved by other tenants are being overlooked — the identity is `totalUnitsInAccount = allocated + availableForAllocation + allocatedAcrossOtherTenants`
+2. Comparing across bundle windows — only currently-active products are returned
+3. Comparing a consumption figure against an allocation figure; `consumed` is a subset of `allocated`, not an addend
+4. Conflating separate license types — tenant runtime units and per-seat user bundles are different pools and never sum together
+5. Leases consumed by `orphan: true` group rows, which are held without being effective
+
+**Investigation:**
+1. `uip platform tenants licenses get "<TENANT_KEY>" --output json` — verify the four-field identity holds per code. If it does, the arithmetic is right and the user's expectation is what needs correcting
+2. Enumerate every tenant to account for `allocatedAcrossOtherTenants` rather than inferring it
+3. For seats, use `uip platform users licenses available --output json`, and count group leases via `groups rules details` including orphaned rows
+
+**Fix:** Causes 1–4 → walk the user through the identity with their own numbers; no change is needed. Cause 5 → re-apply the rule or remove departed users to release leases. If the identity genuinely does not hold, the CLI cannot explain it — escalate to the portal or the License Resource Manager REST API and say so.
+
+---
+
+## Reported As Licensing, Caused Elsewhere
+
+**Symptom:** A runtime failure the user attributes to licensing — job stays Pending, Studio starts unlicensed, robot will not connect.
+
+**Cause:** The licensing layer they checked is not the one that runtime path draws on, or licensing is not involved at all.
+
+**Investigation:**
+1. Map the runtime path to its layer: unattended job → tenant allocation (`UNATT`, `RU`, `PLTU`); Studio/attended → user bundle (`RPADEVPRONU`, `ATTUNU`); folder-scoped robot slot → `uip or licenses`, a different surface
+2. Confirm presence or absence at that layer only, capturing the output as evidence
+3. Note that a current snapshot cannot prove entitlement state during an incident older than 24 hours
+
+**Fix:** Entitlement absent → licensing is the cause; present the layer, evidence, and recommended `set`. Entitlement present → licensing is excluded; hand the causal chain to `uipath-troubleshoot` along with the evidence gathered so it is not re-fetched. Do not keep digging in licensing once the entitlement is confirmed present.

package/skills/uipath-platform/references/licensing/diagnose/references/troubleshooting-guide.md

@@ -0,0 +1,125 @@
+# Licensing Diagnostic Ladder
+
+Layer-first triage for licensing symptoms. Work through in order — stop when you have enough to diagnose. Every command is read-only.
+
+## Step 1: Identify the Layer
+
+Licensing is four independent layers. An entitlement can be present at one and absent at the next, so the first job is deciding which layer the symptom belongs to — not which command to run.
+
+```
+Account (organization)          totalUnitsInAccount — the purchased pool
+  └── Tenant allocation         units reserved per tenant   → uip platform tenants licenses
+  └── User bundle               per-seat entitlement        → uip platform users licenses / groups rules
+        └── Group rule lease     inherited, optional quota
+  └── Orchestrator slot         user/robot license slot     → uip or licenses  (separate surface)
+```
+
+Tenant allocations and user bundles are **separate license types**, not a hierarchy: an unattended job draws on the tenant's runtime allocation (`UNATT`, `RU`, `PLTU`); a developer opening Studio draws on a user bundle (`RPADEVPRONU`). A user with every bundle cannot make an unattended job run, and a fully allocated tenant cannot get a developer into Studio.
+
+| Symptom | Layer | Next step |
+|---------|-------|-----------|
+| "User can't use <product>", bundle missing for one person | User bundle | Step 3 |
+| "Group members don't have their license" | User bundle → group rule | Step 3 |
+| "No seats left", "can't assign any more" | Account pool → user bundle | Step 2, then Step 3 |
+| "Set the allocation but nothing changed" | Tenant allocation | Step 4, then [failure-modes → Allocation reported success](failure-modes.md#allocation-reported-success-but-units-unchanged) |
+| "Code missing from the output" | Tenant allocation → bundle window | [failure-modes → Product code absent](failure-modes.md#product-code-absent-from-get-output) |
+| "Can't allocate that product to the tenant" | Tenant allocation → routing | [failure-modes → Code will not route](failure-modes.md#product-code-will-not-route-to-the-tenant) |
+| "Report shows zero", "numbers look wrong" | Consumption reporting | [failure-modes → Consumables reads zero or wrong](failure-modes.md#consumables-report-reads-zero-or-wrong) |
+| "Totals don't add up to what we bought" | Account pool | [failure-modes → Totals do not reconcile](failure-modes.md#unit-totals-do-not-reconcile) |
+| "License slot not assigned in the folder" | Orchestrator slot | [setup-environment.md](../../../orchestrator/setup-environment.md) — `uip or licenses`, not `uip platform` |
+| Job Pending/faulted, Studio won't start, robot won't connect | **Not established yet** | Step 5 — establish entitlement facts, then hand off |
+
+## Step 2: Establish the Account Pool Baseline
+
+Every unit question resolves against the purchased pool. Read it once, from any tenant:
+
+```bash
+uip platform tenants licenses get "<TENANT_KEY>" --output json
+```
+
+Each row carries the account-level totals alongside the tenant's own:
+
+| Field | Use in diagnosis |
+|-------|------------------|
+| `totalUnitsInAccount` | The purchased pool. Equals `allocated + availableForAllocation + allocatedAcrossOtherTenants` — if it does not, stop and see [failure-modes → Totals do not reconcile](failure-modes.md#unit-totals-do-not-reconcile) |
+| `availableForAllocation` | Units still free anywhere in the account. `0` means the pool is exhausted — no tenant can gain units without another losing them |
+| `allocatedAcrossOtherTenants` | Units held by other tenants — the source of units if this tenant needs more |
+| `allocated` | Reserved for this tenant |
+| `consumed` | Subset of `allocated` actually in use. Lags real-time by minutes |
+
+For seat-based (user bundle) questions, the equivalent baseline is:
+
+```bash
+uip platform users licenses available --output json
+```
+
+## Step 3: Walk the User-Bundle Layer
+
+Resolve the person, then read what they actually hold. The resolver is a **starts-with** match and requires exactly one hit — pass a full email when a name is ambiguous.
+
+```bash
+uip platform users licenses get "<USER_EMAIL_OR_NAME_PREFIX>" --output json
+```
+
+Read `source` on every returned row:
+
+- `"direct"` — granted by `users licenses set` on this user.
+- `"group"` — leased through a group rule. The user's own record is not where the grant lives; the rule is.
+
+Branch on what you find:
+
+| Finding | Meaning | Next |
+|---------|---------|------|
+| Expected code present | The entitlement exists at this layer. The symptom is elsewhere | Step 5 |
+| No rows at all | User holds no bundles — never assigned, or a `set` replaced them | Check whether a group should be granting it (below) |
+| Code absent, others present | A prior `users licenses set` replaced the direct bundles — it replaces, not merges | Confirm intent with the user before re-adding |
+| Code present via `group` but product still unusable | Entitlement is fine at this layer | Step 5 |
+
+When a group is supposed to be the source, read the rule — not the user:
+
+```bash
+uip platform groups rules get --output json
+uip platform groups rules details "<GROUP_NAME>" --output json
+```
+
+On `details`, check in this order:
+
+1. **Is the code in the rule's entitled bundles at all?** If not, the rule was replaced — `groups rules set` replaces the whole rule, dropping any bundle absent from the input.
+2. **Is there a `quota`, and is it filled?** A quota caps how many members can hold the bundle; members beyond it do not get a lease.
+3. **Is the user's row `orphan: true`?** Orphaned rows still consume a lease until the rule is re-applied or the user is fully removed — so a lease can be consumed by someone who no longer benefits from it.
+4. **Is `useExternalLicense` set?** It is informational, set outside these commands — do not treat it as a grant you can change here.
+
+> The rule header (entitled bundles, quotas) is written to **stderr**; the JSON on stdout is the member list. When piping to `jq` you will lose the header — read both streams.
+
+## Step 4: Walk the Tenant-Allocation Layer
+
+```bash
+uip platform tenants licenses get "<TENANT_KEY>" --output json
+```
+
+Compare against what the user believes they set:
+
+| Observation | Interpretation |
+|-------------|----------------|
+| `allocated` differs from the value in their input file | The `set` did not apply, or applied to a different tenant. See [failure-modes → Allocation reported success](failure-modes.md#allocation-reported-success-but-units-unchanged) |
+| `allocated` matches, user expected it to be higher | `quantity` is absolute, not additive — their value replaced the old one rather than adding to it |
+| Code they set is absent from output | Bundle window, or the code never routed. See [failure-modes → Product code absent](failure-modes.md#product-code-absent-from-get-output) |
+| A code they did **not** include still has its old value | Correct behavior — `set` is an overlay. Codes absent from the input keep their current quantity |
+| `consumed` > 0 but `allocated` reduced below it | Over-committed: jobs are using more than the new reservation. Flag this explicitly to the user |
+| `availableForAllocation: 0` | Pool exhausted — the requested increase was impossible, not merely rejected |
+
+## Step 5: Decide Whether Licensing Is the Cause
+
+For a runtime symptom (job Pending or faulted, Studio unlicensed, robot not connecting), licensing is **one hypothesis**. This capability's job is to settle that hypothesis with facts, then stop.
+
+Establish and record:
+
+1. The relevant layer for that runtime path — unattended job → tenant allocation; Studio/attended → user bundle; folder-scoped robot slot → `uip or licenses`.
+2. Whether the entitlement is present at that layer, with the command output as evidence.
+3. Whether `availableForAllocation` or a quota was exhausted at the time — noting that a current snapshot cannot prove state during an incident older than 24 hours.
+
+Then:
+
+- **Entitlement genuinely absent** → licensing is the cause. Present the layer, the evidence, and the exact `set` command as a recommendation. Do not run it.
+- **Entitlement present** → licensing is excluded. Say so, hand the runtime causal chain to `uipath-troubleshoot`, and pass along the evidence you gathered so it is not re-fetched.
+- **Cannot tell from the CLI** → the operation may not be covered. Fall back to the License Resource Manager / License Accountant REST APIs ([licensing.md → REST API Fallback](../../licensing.md#rest-api-fallback)) or the portal. Say which, and why the CLI was insufficient.

package/skills/uipath-platform/references/licensing/licensing.md

@@ -22,6 +22,8 @@ All `uip platform` licensing commands share a set of cross-cutting options:
 
 **Response envelope.** All commands emit `{Result, Code, Data, ...}`. `Code` identifies the payload (`TenantLicenses`, `UserLicensesSet`, `GroupRules`, `LicensesConsumablesSummary`, etc.). Paginated commands add a `Pagination` block — increment `--offset` by `--limit` until `Returned < Limit`.
 
+**Saving a response to a file.** When asked to save command output, write the raw envelope and nothing else — `uip platform ... --output json > available.json`. Never prepend a heading, summary table, or commentary to the file, and never hand-assemble it from what you read: the artifact must parse as JSON on its own. Put the human-readable narrative in your reply or report file, not in the JSON artifact.
+
 ---
 
 ## Workflow References
@@ -31,6 +33,7 @@ All `uip platform` licensing commands share a set of cross-cutting options:
 | Tenant Allocations | [tenant-allocations.md](tenant-allocations.md) | `tenants licenses get/set` — allocate license units to tenant pools |
 | User & Group Licenses | [user-licenses-allocations.md](user-licenses-allocations.md) | `users licenses get/set/available`, `groups rules get/details/set` — assign bundles directly or via group rules |
 | Consumables Report | [consumables-report.md](consumables-report.md) | `licenses consumables get --mode {summary,daily,folders}` — consumption reporting. `get` is mandatory; summary/daily/folders are `--mode` values, not subcommands (there is no `licenses summary` verb) |
+| Diagnose | [diagnose/CAPABILITY.md](diagnose/CAPABILITY.md) | Symptom-first triage — entitlement gaps, allocations that did not take effect, reports that read wrong. Layer-first ladder + failure-mode lookup |
 
 ---
 

package/skills/uipath-platform/references/licensing/user-licenses-allocations.md

@@ -206,6 +206,10 @@ Returns one row per `(group, bundle)` pair:
 
 ### Drill into One Group
 
+One command answers "who in group X holds which bundle". Do not reconstruct that answer from
+`uip admin groups members list` plus a `users licenses get` per member: that returns each member's
+*direct* leases, loses the `orphan` and `quota` fields entirely, and costs one call per user.
+
 ```bash
 uip platform groups rules details "<GROUP_NAME_PREFIX>" --output json
 
@@ -311,6 +315,7 @@ Both mechanisms can co-exist for the same user; rows appear with separate `sourc
 - **Sort order is case-sensitive.** `Asc`/`Desc` only. `asc`, `ASC`, or `ascending` are all rejected.
 - **`orphan: true` rows** still consume a lease until the rule is re-applied or the user is fully removed.
 - **`useExternalLicense`** in `groups rules get` is informational — set externally, not via these commands.
+- **`uip admin groups` does not answer licensing questions.** It lists group membership; it knows nothing about bundles or leases. Any question of the form "who in this group holds which bundle" is `groups rules details`.
 - **Group rule summary goes to stderr.** When piping `groups rules details` output, the rule header (entitled bundles, quotas) is on `stderr` so the JSON on `stdout` stays clean for `jq`.
 
 ---

package/skills/uipath-platform/references/orchestrator/run-jobs.md

@@ -107,8 +107,9 @@ Key options:
 # Get one process by key (cross-folder; resolved through the release lookup)
 uip or processes get <process-key-guid> --output json
 
-# Validation report — what does the runtime see when it tries to start this process?
-# Returns missing tools, missing assets, missing connections, schema mismatches.
+# Validation report — is everything this process needs actually present in its folder?
+# One row per resource the package declares (Queue, Asset, Bucket, Connection, Process,
+# EventTrigger, HttpTrigger, Entity, MCPServer, IXP, ProcessExecutionSettings, ...).
 uip or processes resources <process-key-guid> --output json
 
 # Edit fields after creation. Same flag set as `processes create` minus name/package-key/package-version,
@@ -135,6 +136,14 @@ uip or processes rollback <process-key-guid> --output json
 uip or processes delete <process-key-guid> --yes --output json
 ```
 
+> `processes resources` is the pre-flight check before `jobs start`. Read `ValidationResult` per row:
+> `Success` = the resource exists in the folder (`ResourceId` names it), `NotFound` = it is missing and
+> `ValidationError` says which one ("This queue cannot be found in the folder"), `Unknown` = not
+> folder-validated (connections, execution settings). Filter for the broken ones with
+> `--output-filter "[?ValidationResult=='NotFound']"`. The answer is release-specific: resource
+> overwrites configured on that process are applied first, so a resource pointed at a different
+> target than the package default still reports `Success`.
+
 `processes update` uses `Mapper.Map<ReleaseDto, UiRelease>(dto)` server-side, which means missing fields on the request body are nulled. The CLI works around this by spreading `currentRelease` as the baseline before applying overrides — but if you build the body yourself by hand, `tags`, `arguments`, `videoRecordingSettings`, `targetFramework`, `robotSize`, `resourceOverwrites`, `remoteControlAccess`, `targetRuntime`, `publisherLicense`, etc. will silently get nulled.
 
 ## Step 4: Start Job

package/skills/uipath-platform/references/traces/feedback.md

@@ -37,14 +37,14 @@ uip traces feedback create \
 | `--category` | No | Repeatable. Built-in values: `"Output"`, `"Agent Error"`, `"Agent Plan Execution"` |
 | `--agent-id` | No | Agent reference GUID |
 | `--agent-version` | No | Max 100 chars |
-| `--tenant` | No | Defaults to authenticated tenant |
+| `--profile <name>` | No | Named login profile. Other tenant: `uip login tenant set <tenant>` first (`--tenant` is deprecated) |
 
 ## get
 
-`--folder-key` is optional. Positional `<id>` required.
+Positional `<id>` and `--folder-key` required.
 
 ```bash
-uip traces feedback get <feedback-id> --output json
+uip traces feedback get <feedback-id> --folder-key <folder-key> --output json
 ```
 
 ## list
@@ -88,7 +88,7 @@ uip traces feedback list detailed \
   --output json
 ```
 
-Additional flags over `list`: `--since <duration>`, `--after <ISO>`, `--before <ISO>`, `--category-id <guid>` (repeatable), `--sort-by <createdAt|updatedAt>`, `--sort-order <asc|desc>`. Max 200 items.
+Additional flags over `list`: `--since <duration>`, `--after <ISO>`, `--before <ISO>`, `--category-id <guid>` (repeatable), `--sort-by <createdAt|updatedAt>` (default `createdAt`), `--sort-order <asc|desc>` (default `desc`). Max 200 items.
 
 ## update
 

package/skills/uipath-platform/references/traces/traces.md

@@ -41,7 +41,7 @@ uip traces spans get --job-key <job-key> --output json
 | `--job-key <guid>` | Orchestrator job key — alternative to trace-id |
 | `--folder-path <path>` | Folder path for context |
 | `--folder-key <guid>` | Folder key for context |
-| `-t, --tenant <name>` | Tenant override |
+| `--profile <name>` | Named login profile. Other tenant: `uip login tenant set <tenant>` first (`--tenant` is deprecated) |
 
 ## Related
 

package/skills/uipath-process-mining/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: uipath-process-mining
-description: "UiPath Process Mining via `uip pm` — build and operate a process app end-to-end from a CSV / event log: templates, data mapping, upload, ingest, the dbt (Snowflake) transformation layer, publish, and query it (metrics, percentiles, RCA). Covers `uipath.custom`, the `Cases.sql` optional-column gotcha, Case-linked data-model tables (add-table + re-ingest), the apply-not-reingest fix loop, fixing a wrong mapping in place via `apps data-mapping get|update` (no app rebuild), and editing the app model via `apps model fields` — a field's data kind / calculated fields, including the numeric→duration mismatch that locks dashboards open (DNA-46960). For Orchestrator/Data Fabric/Integration Service→uipath-platform. For `.flow`/Maestro→uipath-maestro-flow. For IXP→uipath-ixp."
-when_to_use: "User mentions process mining, a process app, an event log, `uip pm`, mining a CSV/log, ingesting data into one, dbt/SQL transformations, steps-to-resolution / throughput / variant / rework analysis, or querying one. Also 'build a process app from this data', 'ingest this log', 'fix my Cases.sql', 'why can't I query my custom table', 'add a table to the data model', 'group by X average Y', 'fix/change/read my data mapping', 'wrong date format in the mapping', 'change a field's data kind', 'set a field to duration', 'add a calculated field/metric', 'my dashboards won't open', 'Must be duration not numeric (DNA-46960)'. For Orchestrator/Data Fabric→uipath-platform; `.flow`→uipath-maestro-flow; IXP→uipath-ixp."
+description: "UiPath Process Mining via `uip pm` — build and operate a process app end-to-end from a CSV / event log: templates, data mapping, upload, ingest, the dbt (Snowflake) transformation layer, publish, and query it (metrics, percentiles, RCA). Covers `uipath.custom`, the `Cases.sql` optional-column gotcha, Case-linked data-model tables (add-table + re-ingest), the apply-not-reingest fix loop, fixing a wrong mapping in place via `apps data-mapping get|update` (no app rebuild), and editing the app model via `apps model fields` — a field's data kind / calculated fields, including the numeric→duration mismatch that locks dashboards open. For Orchestrator/Data Fabric/Integration Service→uipath-platform. For `.flow`/Maestro→uipath-maestro-flow. For IXP→uipath-ixp."
+when_to_use: "User mentions process mining, a process app, an event log, `uip pm`, mining a CSV/log, ingesting data into one, dbt/SQL transformations, steps-to-resolution / throughput / variant / rework analysis, or querying one. Also 'build a process app from this data', 'ingest this log', 'fix my Cases.sql', 'why can't I query my custom table', 'add a table to the data model', 'group by X average Y', 'fix/change/read my data mapping', 'wrong date format in the mapping', 'change a field's data kind', 'set a field to duration', 'add a calculated field/metric', 'my dashboards won't open', 'Must be duration not numeric'. For Orchestrator/Data Fabric→uipath-platform; `.flow`→uipath-maestro-flow; IXP→uipath-ixp."
 allowed-tools: Bash, Read, Write, Glob, Grep
 ---
 
@@ -24,7 +24,7 @@ references for the full detail.
 - **Author the transformation layer** — edit the dbt (Snowflake) SQL models that produce the process model, then re-run.
 - **Query a process app** — pull numbers out: aggregate group-by + metrics, raw detail rows, percentiles, root-cause analysis, process insights.
 - **Expose custom analysis** — surface your own analytical table (a weekly aggregate, an impact study) as a queryable entity.
-- **Edit the app model** — change a field's data kind, add calculated fields, or fix a data-kind mismatch that locks dashboards open (DNA-46960).
+- **Edit the app model** — change a field's data kind, add calculated fields, or fix a data-kind mismatch that locks dashboards open.
 - **Manage the app lifecycle** — stages (dev → published), RBAC, deletion.
 
 ## App lifecycle
@@ -47,11 +47,11 @@ An app moves through: **create** (from a template + data mapping) → **load** (
 
 7. **Query field ids come from `query info`, not column names.** `query run`/`percentile` bodies take the hashed `F__<Table>__<Col>__<hash>` ids. Prefer the sugar: `query run <app> --group-by <col> --metric <col>:<fn>` resolves human names for you (fn ∈ `average|count|sum|min|max`).
 
-8. **Develop on `dev` with a data subset; publish the full dataset.** The `dev` stage is for iterating on the mapping and transformations — keep it fast by loading a **small representative subset** of the data. Once the model is right, **publish** so the **published** stage carries the **full** dataset for the dashboards and sharing. Query/transform against `--stage dev`; consumers read the **published dashboards**. Note CLI `query --stage published` is currently unreachable (no `uip pm` path completes a published-stage ingestion) — do CLI querying on `dev` ([`references/lifecycle-and-rbac.md`](references/lifecycle-and-rbac.md)).
+8. **Develop on `dev` with a data subset; publish the full dataset.** The `dev` stage is for iterating on the mapping and transformations — keep it fast by loading a **small representative subset** of the data. Once the model is right, **publish** so the **published** stage carries the **full** dataset for the dashboards and sharing. Iterate with `--stage dev`; consumers read the **published dashboards**. `query --stage published` works once that stage has a completed ingestion — after `apps publish` reports `IngestionNeeded: true`, run `ingestions create <app> --stage published --wait`. Querying published is optional, not a required step ([`references/lifecycle-and-rbac.md`](references/lifecycle-and-rbac.md)).
 
 9. **RBAC is folder/role-based at the platform layer, not the process app itself.** A process app lives in a folder; who can view vs. edit vs. publish is governed by Orchestrator/Identity roles and folder assignments — configure it with [`uipath-admin`](/uipath:uipath-admin) (roles, role assignments, effective-access) and [`uipath-platform`](/uipath:uipath-platform) (folders). See [`references/lifecycle-and-rbac.md`](references/lifecycle-and-rbac.md). `uip pm` itself does not grant access.
 
-10. **Edit a field's data kind / calculated fields with `apps model fields` — and a data-kind mismatch can lock the app open.** Change a field's kind (e.g. numeric→duration), rename it, or add a calculated field with `uip pm apps model fields set <app> <field> [--kind|--display-name|--expression]` (the **semantic** model; dev-only, and **no `--etag`** — it merges into the version it just read, so a lost race is fixed by re-running it; a whole-document `apps model update` does require `--etag`). Relational/arithmetic operators require both operands to share a data kind, so flipping a field to `duration` while a metric / calculated field / dashboard filter still compares it to a `numeric` constant persists an invalid model that throws at dashboard open — the *"Must be duration, not numeric, for the 'lt' input"* lockout (DNA-46960), which leaves only the data-upload module reachable. `fields set`/`update` validate and refuse such an edit with a hint; fix an already-broken app by making the comparison consistent (re-type the field or the constant). Full surface + the data-kind rule in [`references/model-editing.md`](references/model-editing.md).
+10. **Edit a field's data kind / calculated fields with `apps model fields` — and a data-kind mismatch can lock the app open.** Change a field's kind (e.g. numeric→duration), rename it, or add a calculated field with `uip pm apps model fields set <app> <field> [--kind|--display-name|--expression]` (the **semantic** model; dev-only, and **no `--etag`** — it merges into the version it just read, so a lost race is fixed by re-running it; a whole-document `apps model update` does require `--etag`). Relational/arithmetic operators require both operands to share a data kind, so flipping a field to `duration` while a metric / calculated field / dashboard filter still compares it to a `numeric` constant persists an invalid model that throws at dashboard open — the *"Must be duration, not numeric, for the 'lt' input"* lockout, which leaves only the data-upload module reachable. `fields set`/`update` validate and refuse such an edit with a hint; fix an already-broken app by making the comparison consistent (re-type the field or the constant). Full surface + the data-kind rule in [`references/model-editing.md`](references/model-editing.md).
 
 ## Quick Start
 
@@ -76,7 +76,7 @@ reference for the decision; drop into the CLI reference for the mechanics it use
 | [`references/pre-flight.md`](references/pre-flight.md) | before any upload — encoding/delimiter/date-format/empty-row checks and the minimal `mapping.json` recipe; **also** the post-create mapping fix loop (`apps data-mapping get`/`update`) and its failure modes |
 | [`references/transformations.md`](references/transformations.md) | authoring/fixing dbt models — the `Cases.sql` patch, apply-vs-run, pm_utils macros, Snowflake identifier quoting |
 | [`references/data-model.md`](references/data-model.md) | exposing a custom table to `query`/dashboards — the case-centric add-table pattern (DataModelDto + re-ingest) and the Tags/Due_dates decision table |
-| [`references/model-editing.md`](references/model-editing.md) | editing the app model — a field's **data kind** (e.g. numeric→duration), calculated fields, the two models (semantic `apps model` vs structural `apps data-model`), and the data-kind comparison rule that locks an app open (DNA-46960) |
+| [`references/model-editing.md`](references/model-editing.md) | editing the app model — a field's **data kind** (e.g. numeric→duration), calculated fields, the two models (semantic `apps model` vs structural `apps data-model`), and the data-kind comparison rule that locks an app open |
 | [`references/querying.md`](references/querying.md) | pulling numbers out — the aggregate body AST, the `--group-by/--metric` sugar, the `AggregationFunction` enum, and the event-table restriction |
 | [`references/lifecycle-and-rbac.md`](references/lifecycle-and-rbac.md) | dev vs published stages, publishing, and where process-app RBAC is configured |