@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-admin/references/audit-workflow-guide.md

@@ -172,9 +172,9 @@ For each event:
 
 ## Investigation 3 — "Give me an audit dump for January"
 
-**User asks:** "Export everything for compliance for Q4." / "I need the full audit log for January for the security review." / "Pull last month's events for tenant X as a ZIP."
+**User asks:** "Export everything for compliance for Q4." / "I need the full audit log for January for the security review." / "Pull last month's events for tenant X as JSON files."
 
-**Approach:** `export` straight to a file. Default is a ZIP of day-wise JSON files; add `--file-format csv` for a single merged CSV when the user wants a flat, spreadsheet/Excel-friendly dump. No need to query `events` first unless the user wants a preview. Match the `--output-file` extension to the format (`.zip` / `.csv`).
+**Approach:** `export` straight to disk. Default (`json`) writes a **folder** of day-wise JSON files; add `--file-format csv` for a single merged CSV when the user wants a flat, spreadsheet/Excel-friendly dump. No need to query `events` first unless the user wants a preview. Pass `--output-path` a **base directory** — the CLI creates a uniquely-named `audit_<from>_<to>_<generated-at>` folder (`json`) or `.csv` (`csv`) inside it; don't hand-craft the per-export name.
 
 ### Step 1 — Confirm scope and window
 
@@ -183,11 +183,11 @@ If the user is ambiguous about scope, ask once. For compliance reviews, **both**
 ### Step 2 — Export
 
 ```bash
-# Tenant scope — most events (default ZIP of day-wise JSON files)
+# Tenant scope — most events (default json: a uniquely-named folder of day-wise JSON files under the base dir)
 uip admin audit tenant export \
   --from-date 2026-01-01 \
   --to-date   2026-02-01 \
-  --output-file ./audit-tenant-2026-01.zip \
+  --output-path ./audit-exports \
   --output json
 
 # Tenant scope as a single merged CSV (flat, Excel-friendly)
@@ -195,52 +195,53 @@ uip admin audit tenant export \
   --from-date 2026-01-01 \
   --to-date   2026-02-01 \
   --file-format csv \
-  --output-file ./audit-tenant-2026-01.csv \
+  --output-path ./audit-exports \
   --output json
 
 # Org scope — admin events (memberships, license, tenant lifecycle)
 uip admin audit org export \
   --from-date 2026-01-01 \
   --to-date   2026-02-01 \
-  --output-file ./audit-org-2026-01.zip \
+  --output-path ./audit-exports \
   --output json
 ```
 
-The CLI issues one HTTP call per UTC day under the hood. ZIP aggregates the daily responses into a flat ZIP; CSV parses the same daily JSON and merges every event into one CSV. `Days` and `NonEmptyDays` in the result tell you how many calendar days had data; for CSV, `Events` reports the total row count.
+The CLI issues one HTTP call per UTC day under the hood, then creates a uniquely-named `audit_<from>_<to>_<generated-at>` output under `--output-path`: `json` writes a folder of one JSON file per UTC day; `csv` parses the same daily JSON and merges every event into one `.csv`. The result's `Path` is the generated folder/file (and `GeneratedAt` its timestamp); `Days`/`NonEmptyDays` say how many calendar days had data; `json` reports `Files`, `csv` reports `Events`.
 
 ### Step 3 — Verify the export
 
-**ZIP** — list the per-day entries:
+**JSON (default)** — the export created a generated folder under the base dir; list its per-day files:
 
 ```bash
-unzip -l ./audit-tenant-2026-01.zip
+ls ./audit-exports/*/        # the generated audit_<from>_<to>_<generatedAt>/ folder
 ```
 
-Typical layout (one entry per UTC day with events):
+Typical layout (the base dir holds one generated folder; one file per UTC day with events):
 
 ```
-audit-tenant-2026-01.zip
-├── 2026-01-01.txt
-├── 2026-01-02.txt
-├── ...
-└── 2026-01-31.txt
+audit-exports/
+└── audit_2026-01-01_2026-02-01_20260617T112630/
+    ├── 2026-01-01.json
+    ├── ...
+    └── 2026-01-31.json
 ```
 
-Each `.txt` is a JSON array of audit events with **PascalCase** keys (`Id`, `CreatedOn`, `OrganizationId`, `ActorId`, `ActorName`, `EventType`, …) — different from the camelCase shape returned by the live `events` endpoint. Note this in the user's hand-off if they're going to feed the dump into other tooling.
+Each `.json` file is a JSON array of audit events with **PascalCase** keys (`Id`, `CreatedOn`, `OrganizationId`, `ActorId`, `ActorName`, `EventType`, …) — different from the camelCase shape returned by the live `events` endpoint. Note this in the user's hand-off if they're going to feed the dump into other tooling.
 
-**CSV** — inspect the header and row count:
+**CSV** — find the generated file, then inspect the header and row count:
 
 ```bash
-head -1 ./audit-tenant-2026-01.csv          # shared header (PascalCase columns)
-python3 -c "import csv; print(sum(1 for _ in csv.reader(open('./audit-tenant-2026-01.csv'))) - 1, 'rows')"
+csv=$(ls ./audit-exports/audit_*.csv | head -1)   # the generated audit_<from>_<to>_<generatedAt>.csv
+head -1 "$csv"                                      # shared header (PascalCase columns)
+python3 -c "import csv,sys; print(sum(1 for _ in csv.reader(open(sys.argv[1]))) - 1, 'rows')" "$csv"
 ```
 
-One header row, then every event across all days as a data row (same PascalCase column names as the ZIP's JSON keys). The row count should match `Events` in the result envelope.
+One header row, then every event across all days as a data row (same PascalCase column names as the JSON files' keys). The row count should match `Events` in the result envelope.
 
 Edge cases the CLI handles automatically — surface in your hand-off only if they appear:
 
-- **Nested ZIPs**: when a single day's response is itself a ZIP-of-ZIPs, inner files are renamed `<inner>_<outer>.txt` rather than collapsed.
-- **Same-name collisions**: duplicate basenames across days get an `_<YYYY-MM-DD>` suffix (and `_<YYYY-MM-DD>_2`, `_3`, … if needed) to keep entries unique.
+- **Nested ZIPs**: when a single day's server response is itself a ZIP-of-ZIPs, inner files are flattened into the folder as `<inner>_<outer>.json` rather than collapsed.
+- **Same-name collisions**: duplicate basenames across days get an `_<YYYY-MM-DD>` suffix (and `_<YYYY-MM-DD>_2`, `_3`, … if needed) to keep filenames unique.
 
 ### Step 4 — Hand off
 
@@ -291,7 +292,7 @@ If the user wants more depth on any one event type, drill in with Investigation
 |---|---|
 | "who" / "did" + a verb on a resource | **1** — Who did X to Y |
 | "logged in" / "login" / "authenticated" / a user's email | **2** — Login history |
-| "export" / "dump" / "ZIP" / "CSV" / a date range | **3** — Date-range dump |
+| "export" / "dump" / "JSON" / "CSV" / a date range | **3** — Date-range dump |
 | "overview" / "what's happening" / "recent activity" / "audit summary" | **4** — Overview |
 
 Two or more signals? Run them in sequence and stitch the results in the final report. Don't make the user re-ask.
@@ -301,14 +302,14 @@ Two or more signals? Run them in sequence and stitch the results in the final re
 - **`tenant` events without an active tenant fail loudly.** If `uip login` has no tenant selected, every tenant-scoped command throws. Either re-`uip login` and pick a tenant, or pass `--tenant-id <guid>` on every call.
 - **`events` cursor pagination is chronologically reversed from intuition.** `next` = newer (often null), `previous` = older (the typical "load more"). The CLI tool follows `previous` automatically when you bump `--limit > 200` — don't re-implement this in the agent.
 - **Date-only ISO strings are interpreted as UTC midnight.** `--from-date 2026-01-01` means `2026-01-01T00:00:00Z`. To capture the full final day in `--to-date`, use `2026-02-01` (exclusive next day) or `2026-01-31T23:59:59.999Z`.
-- **Export format depends on `--file-format`.** The default `zip` holds one **JSON** file per UTC day (not CSV) with **PascalCase** keys; `--file-format csv` produces a single merged **CSV** whose header uses those same PascalCase field names. Both differ from the camelCase live `events` endpoint — don't paste an export into a parser expecting the live shape. In the CSV, `Status` is numeric (`0`/`1`) and `ClientInfo` is a JSON-stringified cell.
+- **Export format depends on `--file-format`.** The default `json` writes one **JSON** file per UTC day (named `<YYYY-MM-DD>.json`) into a generated subfolder under `--output-path`, with **PascalCase** keys; `--file-format csv` produces a single merged **CSV** whose header uses those same PascalCase field names. Both differ from the camelCase live `events` endpoint — don't paste an export into a parser expecting the live shape. In the CSV, `Status` is numeric (`0`/`1`) and `ClientInfo` is a JSON-stringified cell.
 - **Org sources and tenant sources are different sets.** Don't reuse a GUID from `org sources` in a `tenant events` query — the filter will silently match nothing.
 
 ## Output Etiquette — after an audit query or export
 
 After every `events` or `export` call, surface the following before waiting for the user's next-step choice. Do not chain mutations.
 
-1. **Operation & result** — e.g. `Found 47 audit events on tenant T in the last 7 days`, `Wrote 123,456 bytes to /path/to/audit.zip (3 days, 2 non-empty)`, or for CSV `Wrote 98,765 bytes to /path/to/audit.csv (1,234 events across 3 days, 2 non-empty)`.
+1. **Operation & result** — e.g. `Found 47 audit events on tenant T in the last 7 days`, `Wrote 27 JSON files (123,456 bytes) to /path/to/audit-jan/ (31 days, 27 non-empty)`, or for CSV `Wrote 98,765 bytes to /path/to/audit.csv (1,234 events across 31 days, 27 non-empty)`.
 2. **Scope used** (`org` or `tenant`) and any `--tenant-id` override.
 3. **Time window** — explicit ISO bounds, even if they came from a relative phrase ("last 7 days").
 4. **Filters applied** — sources, types, users, status.

package/skills/uipath-admin/references/diagnose/CAPABILITY.md

@@ -0,0 +1,74 @@
+# Diagnose — Investigate Identity, Authorization & Platform Failures
+
+Capability index for diagnosing identity/auth failures, permission denials, IP restriction lockouts, and tenant operation issues via `uip admin`.
+
+> **Where you came from / where to go next.** Diagnose is downstream of Operate (a user, app, or tenant operation failed
+> or behaved unexpectedly). Source fixes — role changes, user provisioning, config updates — are Operate actions requiring
+> explicit user consent after root cause analysis.
+>
+> **Inherits universal rules from [SKILL.md](../../SKILL.md).** Use `uip admin ... --output json` for all diagnostic reads.
+
+## When to use this capability
+
+- Investigate login failures (user can't sign in, auth errors).
+- Diagnose external app OAuth2 flow failures (scope mismatch, expired secret, wrong grant type).
+- Triage robot account authentication confusion (identity vs credential model).
+- Investigate PAT rejection (expired, revoked, insufficient scopes).
+- Diagnose SMTP email delivery failures (invitations not sending).
+- Investigate HTTP 403 / permission denied errors (missing role, wrong scope).
+- Triage role assignments not taking effect (ownerServiceName/scope-path mismatch).
+- Diagnose IP restriction lockout or unexpected enforcement behavior.
+- Investigate stuck or failed tenant lifecycle operations.
+- Identify service provisioning no-ops (platform-pinned services).
+
+## Critical rules
+
+1. **Diagnose reads; Operate mutates.** Do not create/delete users, assign roles, or toggle enforcement while diagnosing — present findings and let the user decide the fix.
+2. **Use the CLI as the diagnostic interface.** Run `uip admin ... --output json` for all reads.
+3. **Resolve principals before investigating.** Use `users list --search`, `groups list`, `robot-accounts list`, or `external-apps get` to resolve names to IDs before deeper queries.
+4. **Route to audit for historical investigation.** Login events are org-scoped (`audit org events`); tenant activity is tenant-scoped (`audit tenant events`). See [audit-workflow-guide.md](../audit-workflow-guide.md).
+5. **Use check-access as the primary authorization diagnostic.** The PDP (`check-access`) is the source of truth for effective permissions — it folds in server-side rules that `roles assignments list` alone may not reflect. See [check-access.md](../authorization/check-access.md).
+6. **Do not expose private data.** Redact tenant URLs, secrets, tokens, and user credentials in summaries.
+
+## Workflow
+
+| Journey | Read |
+|---------|------|
+| Triage an identity/auth failure (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 |
+|---|---|
+| Investigate why a user can't log in | [troubleshooting guide → Step 1](references/troubleshooting-guide.md#step-1-identify-the-failure-domain) |
+| Diagnose HTTP 403 / permission denied | [troubleshooting guide → Step 3](references/troubleshooting-guide.md#step-3-check-effective-access) |
+| Check why a role assignment isn't working | [failure modes → Role assignment not taking effect](references/failure-modes.md#role-assignment-not-taking-effect) |
+| Diagnose an external app OAuth2 failure | [failure modes → External app OAuth2 failing](references/failure-modes.md#external-app-oauth2-flow-failing) |
+| Investigate PAT rejection | [failure modes → PAT rejected](references/failure-modes.md#pat-rejected) |
+| Diagnose SMTP delivery failure | [failure modes → SMTP not delivering](references/failure-modes.md#smtp-emails-not-delivering) |
+| Recover from IP restriction lockout | [failure modes → IP restriction lockout](references/failure-modes.md#ip-restriction-lockout) |
+| Investigate a stuck tenant operation | [failure modes → Tenant operation stuck](references/failure-modes.md#tenant-operation-stuck-or-failed) |
+
+## Anti-patterns
+
+- **Never assign/revoke roles while diagnosing.** Present findings first; let the user authorize mutations.
+- **Never retry auth failures.** On 401, the token is missing required scopes — tell user to `uip logout && uip login`.
+- **Never assume audit scope.** Login events are org-scoped; resource events are tenant-scoped. Ask if ambiguous (Rule 23).
+- **Never guess principal IDs.** Always resolve via `users list --search` or equivalent before high-risk operations.
+- **Never start with traces when check-access can answer the question.** The PDP is faster and more authoritative.
+
+## References
+
+### Diagnose-scoped
+
+- [troubleshooting-guide.md](references/troubleshooting-guide.md) — diagnostic priority ladder
+- [failure-modes.md](references/failure-modes.md) — recurring failure patterns
+
+### Cross-capability
+
+- [authorization/check-access.md](../authorization/check-access.md) — effective access PDP
+- [audit-workflow-guide.md](../audit-workflow-guide.md) — audit investigation playbooks
+- [identity-commands.md](../identity-commands.md) — CLI reference for identity operations
+- [ip-restriction/enforcement-management.md](../ip-restriction/enforcement-management.md) — enforcement toggle + lockout safety
+- [tenants-commands.md](../tenants-commands.md) — tenant lifecycle + async operations

package/skills/uipath-admin/references/diagnose/references/failure-modes.md

@@ -0,0 +1,228 @@
+# Failure Modes — Identity, Authorization & Platform
+
+Named failure patterns with symptom → cause → investigation → fix. Match the user's symptom to a pattern, then follow the investigation steps.
+
+---
+
+## User Cannot Log In
+
+**Symptom:** User reports login failure — `uip login` returns error, Portal/UI login redirects or rejects.
+
+**Causes:**
+1. User not provisioned (never invited or deleted)
+2. Bad credentials (password expired or incorrect)
+3. IP restriction blocking the user's IP
+4. Account locked (too many failed attempts)
+5. No org access (user exists in identity but not assigned to org)
+
+**Investigation:**
+1. Verify user exists: `uip admin users list --search "<USER_EMAIL>" --output json`
+2. If found, check login history at **org** scope:
+   ```bash
+   uip admin audit org events --user-id "<USER_ID>" --status "Failure" \
+     --from-date "<7_DAYS_AGO>" --to-date "<TODAY>" --output json
+   ```
+3. Check IP restriction: `uip admin ip-restriction enforcement get --output json`
+
+**Fix:** Cause 1 → invite user. Cause 2 → user resets password via Portal. Cause 3 → add IP to allowlist. Cause 4 → wait or admin unlock via Portal. Cause 5 → re-invite.
+
+---
+
+## External App OAuth2 Flow Failing
+
+**Symptom:** CI/CD pipeline or integration returns auth errors using external app Client ID.
+
+**Causes:**
+1. Grant type / scope mismatch — `client_credentials` with `--user-scope` (or vice versa)
+2. Secret expired or never generated
+3. Redirect URI mismatch (authorization_code flow)
+4. Non-confidential app used with `--app-scope` (rejected)
+5. Scopes don't cover the required API
+
+**Investigation:**
+1. Inspect app config: `uip admin external-apps get "<CLIENT_ID>" --output json`
+2. Check `resources` list for scope registration vs grant type
+3. For `authorization_code` flow, verify redirect URI matches exactly
+
+**Fix:** Cause 1 → recreate with correct scope type. Cause 2 → `external-apps generate-secret "<CLIENT_ID>" --output json` (secret shown only once). Cause 3 → `external-apps update --redirect-uri`. Cause 4 → use confidential app for app-only scopes. Cause 5 → update scopes (note: `--app-scope` on update **replaces** all scopes).
+
+---
+
+## Robot Account Not Authenticating
+
+**Symptom:** Automation fails with "robot not authenticated" or similar credential errors.
+
+**Causes:**
+1. Robot account does not exist
+2. Confusion between robot account (identity) and robot credentials (Orchestrator)
+3. Robot account not in the correct groups
+
+**Investigation:**
+1. Verify robot exists: `uip admin robot-accounts list --search "<ROBOT_NAME>" --output json`
+2. Check group membership: `uip admin groups list --output json`, then `groups members list "<GROUP_ID>" --output json`
+
+**Fix:** Cause 1 → create robot account. Cause 2 → robot accounts are **identities only** — they don't carry API credentials (Client ID + Secret). For API access, create an **external app** instead. For unattended execution, Orchestrator provisions credentials via machine connection. Cause 3 → add to appropriate group.
+
+---
+
+## PAT Rejected
+
+**Symptom:** API call with a personal access token returns 401 or 403.
+
+**Causes:**
+1. Token expired
+2. Token revoked
+3. Scope mismatch (token scopes don't cover the API)
+4. Per-user token limit reached (new token couldn't be created)
+
+**Investigation:**
+1. List tokens: `uip admin pat list --output json`
+2. Check `expiration` — if past today, token is expired
+3. If the token is **absent from the list**, it was revoked (revocation is a hard delete — there is no `isRevoked` flag)
+4. Compare `scopes` against the API being called
+
+**Fix:** Cause 1 → regenerate: `pat regenerate "<PAT_ID>" --output json`. Cause 2 → create new token (revoked tokens are deleted, not recoverable). Cause 3 → create new token with correct scopes. Cause 4 → revoke unused tokens first: `pat revoke "<PAT_ID>" --output json`.
+
+---
+
+## SMTP Emails Not Delivering
+
+**Symptom:** Platform invitation emails, password resets, or notifications not received.
+
+**Causes:**
+1. SMTP not configured (never set up or deleted)
+2. Connection refused (wrong host/port or firewall)
+3. Authentication failure (wrong credentials)
+4. SSL/TLS mismatch
+5. DNS resolution failure
+
+**Investigation:**
+1. Check config: `uip admin smtp get --output json`
+2. Test delivery: `uip admin smtp test --recipient "<TEST_EMAIL>" --output json`
+3. Branch on test result error message
+
+**Fix:** Update config with correct values: `uip admin smtp update --host "<HOST>" --port <PORT> --secure <true|false> --user "<USER>" --password "<PASS>" --output json`. Re-test after each change.
+
+---
+
+## User Gets HTTP 403 (Permission Denied)
+
+**Symptom:** User or integration receives 403 when calling a platform API or performing a UI action.
+
+**Causes:**
+1. No role at all for the required service
+2. Role exists but at wrong scope (org vs tenant vs folder)
+3. Role missing the specific permission action
+4. Cross-service confusion (Orchestrator role ≠ DU access)
+
+**Investigation:**
+1. Resolve user: `uip admin users list --search "<USER_EMAIL>" --output json`
+2. Check effective access: `uip admin authorization check-access "<USER_ID>" --output json`
+3. Narrow to service: `uip admin authorization check-access "<USER_ID>" --service <SERVICE> --output json`
+4. Compare against required permission: `uip admin authorization permissions list --service <SERVICE> --output json`
+5. Label each result as `direct` or `inherited from <Group>` — see [check-access.md](../../authorization/check-access.md)
+
+**Fix:** Cause 1 → assign a role for the service. Cause 2 → re-assign at correct scope. Cause 3 → update custom role actions or assign additional role. Cause 4 → assign role owned by the correct service.
+
+---
+
+## Role Assignment Not Taking Effect
+
+**Symptom:** Admin assigned a role but the principal still cannot perform the expected action.
+
+**Causes:**
+1. `ownerServiceName` / scope-path mismatch (Rule 17) — most common
+2. Role assigned at wrong scope level (TenantGlobal vs Tenant vs Folder)
+3. Role missing the needed permission action
+4. Assignment at wrong tenant
+
+**Investigation:**
+1. Verify assignment exists: `uip admin authorization roles assignments list --filter "<PRINCIPAL_NAME>" --output json`
+2. Inspect role: `uip admin authorization roles get "<ROLE_ID>" --output json` — check `ownerServiceName` and `scopeType`
+3. Validate Rule 17: `CentralizedAccess` → no service segment in scope-path; any other value → path must include `lowercase(ownerServiceName)`
+4. Verify via PDP: `uip admin authorization check-access "<PRINCIPAL_ID>" --output json`
+
+**Fix:** Cause 1 → re-create assignment with correct scope-path matching ownerServiceName. Cause 2 → re-assign at correct scope. Cause 3 → update role actions. Cause 4 → re-assign at correct tenant.
+
+---
+
+## Cross-Service Permission Confusion
+
+**Symptom:** "I have a role in Orchestrator but can't access DU projects" or "CentralizedAccess role doesn't grant service-specific permissions."
+
+**Cause:** Permissions are service-scoped — an Orchestrator role does NOT grant DU, IXP, or other service access.
+
+**Investigation:**
+1. Check without service filter: `uip admin authorization check-access "<USER_ID>" --output json`
+2. Check with service filter: `uip admin authorization check-access "<USER_ID>" --service documentunderstanding --output json`
+3. Compare — the missing service's permissions will be absent
+4. Check role's `ownerServiceName` to confirm it belongs to the wrong service
+
+**Fix:** Assign a role owned by the correct service, or create a new custom role scoped to that service.
+
+---
+
+## IP Restriction Lockout
+
+**Symptom:** User or admin locked out of org after enabling IP restriction enforcement.
+
+**Causes:**
+1. Caller's IP not in allowlist when enforcement was enabled
+2. Allowlist entry expired or was deleted
+
+**Investigation:**
+1. Attempt: `uip admin ip-restriction enforcement get --output json`
+2. If succeeds → caller is not locked out; other users are. Check: `ip-ranges list --output json` and compare IPs
+3. If fails → caller IS locked out. Recovery: access from an in-allowlist IP, or Portal recovery flow
+
+**Fix:** Once recovered: `enforcement disable --output json`, fix allowlist, then re-enable with pre-flight safety check (Rule 31).
+
+---
+
+## Enforcement Not Blocking as Expected
+
+**Symptom:** IP restriction is supposedly enabled but unwanted IPs can still access the org.
+
+**Causes:**
+1. Enforcement not actually enabled
+2. Overly permissive CIDR entry (e.g., `0.0.0.0/0`)
+3. Bypass rule too broad (regex matches all traffic)
+
+**Investigation:**
+1. `uip admin ip-restriction enforcement get --output json`
+2. `uip admin ip-restriction ip-ranges list --output json` — check for broad CIDRs
+3. `uip admin ip-restriction bypass-rules list --output json` — check regex patterns
+
+**Fix:** Cause 1 → enable enforcement. Cause 2 → narrow or remove overly permissive entries. Cause 3 → tighten bypass rule regex.
+
+---
+
+## Tenant Operation Stuck or Failed
+
+**Symptom:** `tenants create/update/delete/enable/disable` returned `operationId` but operation hasn't completed.
+
+**Causes:**
+1. Region unavailable or at capacity
+2. Required services not available in region
+3. Backend timeout (transient)
+4. Quota exceeded
+
+**Investigation:**
+1. Poll: `uip admin organizations operation get "<OPERATION_ID>" --output json`
+2. Interpret status: `Pending`/`Queued`/`Creating`/`Updating`/`Enabling`/`Disabling`/`Deleting`/`InProgress` → still in progress (auto-poll 3× at 5s, Rule 18). `Failed` → inspect `Data.error` / `Data.message`. Terminal success statuses are verb-specific: `Created`/`Updated`/`Enabled`/`Disabled`/`Deleted`/`Done` → verify with `tenants get "<TENANT_ID>" --output json`
+
+**Fix:** Cause 1 → try different region: `organizations regions list --output json`. Cause 2 → check catalog: `tenants services list-available --region "<REGION>" --output json`. Cause 3 → retry. Cause 4 → contact support. Do NOT auto-retry failed mutations.
+
+---
+
+## Service Provisioning No-Op
+
+**Symptom:** `tenants services disable` or `remove` returned Success but service still shows Enabled.
+
+**Cause:** Always-provisioned services return Success on `disable`/`remove` but the state never changes. The always-provision list is configuration-driven and varies by deployment — always re-list after mutating to confirm the actual state changed.
+
+**Investigation:**
+1. Verify state: `uip admin tenants services list --tenant-id "<TENANT_ID>" --output json`
+2. Compare state before and after the mutation — if unchanged, the service is always-provisioned
+
+**Fix:** CLI cannot disable/remove always-provisioned services. Redirect to UiPath Portal. Always re-list after any service mutation (Rule 22).

package/skills/uipath-admin/references/diagnose/references/troubleshooting-guide.md

@@ -0,0 +1,106 @@
+# Diagnostic Priority Ladder
+
+Sequential triage workflow for identity, authorization, and platform failures. Work through in order — stop when you have enough to diagnose.
+
+## Step 1: Identify the Failure Domain
+
+Determine which area the symptom belongs to based on user description:
+
+| Symptom | Domain | Next step |
+|---------|--------|-----------|
+| "Can't log in", auth error, login rejected | Identity — login | Step 2 (resolve user) |
+| "403", "permission denied", "access denied" | Authorization — access | Step 3 (check-access) |
+| "Token not working", "PAT rejected" | Identity — PAT | Step 2 (resolve user), then [failure-modes → PAT rejected](failure-modes.md#pat-rejected) |
+| "OAuth failing", "client_credentials error" | Identity — external app | [failure-modes → OAuth2 failing](failure-modes.md#external-app-oauth2-flow-failing) |
+| "Robot not authenticating" | Identity — robot account | [failure-modes → Robot account](failure-modes.md#robot-account-not-authenticating) |
+| "Emails not sending", "SMTP broken" | Identity — SMTP | [failure-modes → SMTP](failure-modes.md#smtp-emails-not-delivering) |
+| "Locked out", "can't access org" | IP restriction | [failure-modes → IP lockout](failure-modes.md#ip-restriction-lockout) |
+| "Tenant create stuck", "operation not completing" | OMS — tenant ops | [failure-modes → Tenant operation](failure-modes.md#tenant-operation-stuck-or-failed) |
+| "Service still enabled after remove" | OMS — services | [failure-modes → Service no-op](failure-modes.md#service-provisioning-no-op) |
+
+## Step 2: Resolve the Principal
+
+Before any deeper investigation, resolve the named user/app/robot to its ID:
+
+```bash
+uip admin users list --search "<USER_EMAIL_OR_NAME>" --output json
+```
+
+For robot accounts:
+```bash
+uip admin robot-accounts list --search "<ROBOT_NAME>" --output json
+```
+
+For external apps:
+```bash
+uip admin external-apps get "<CLIENT_ID>" --output json
+```
+
+If the principal is not found → they were never provisioned or were deleted. This is the root cause.
+
+## Step 3: Check Effective Access
+
+For any permission-related symptom (403, "can't do X", role not working), the PDP is the primary diagnostic tool:
+
+```bash
+uip admin authorization check-access "<USER_ID>" --output json
+```
+
+To narrow to a specific service:
+```bash
+uip admin authorization check-access "<USER_ID>" --service orchestrator --output json
+```
+
+Interpret the results:
+- Label each role as `direct` or `inherited from <Group>` by inspecting `roleAssignments[].securityPrincipalType`
+- Compare effective permissions against the required permission for the denied action
+- Check `ownerServiceName` on each role — cross-service grants don't apply (Orchestrator role ≠ DU access)
+
+See [check-access.md](../../authorization/check-access.md) for full interpretation guide.
+
+## Step 4: Check Audit History
+
+For historical investigation (login failures, "who changed X", "when did access break"):
+
+Login events are **org-scoped** (not tenant-scoped):
+```bash
+uip admin audit org sources --output json
+uip admin audit org events \
+  --user-id "<USER_ID>" --status "Failure" \
+  --from-date "<START>" --to-date "<END>" \
+  --output json
+```
+
+Resource changes (roles, assets, folders) are **tenant-scoped**:
+```bash
+uip admin audit tenant sources --output json
+uip admin audit tenant events \
+  --from-date "<START>" --to-date "<END>" \
+  --output json
+```
+
+See [audit-workflow-guide.md](../../audit-workflow-guide.md) for scope routing rules.
+
+## Step 5: Inspect Configuration
+
+For config-related failures (SMTP, IP restriction, tenant services), read the current state:
+
+```bash
+uip admin smtp get --output json
+uip admin ip-restriction enforcement get --output json
+uip admin ip-restriction ip-ranges list --output json
+uip admin tenants services list --tenant-id "<TENANT_ID>" --output json
+```
+
+Compare actual config against expected. For SMTP, run a test:
+```bash
+uip admin smtp test --recipient "<TEST_EMAIL>" --output json
+```
+
+## Outputs
+
+After completing the relevant steps, present:
+1. **Root cause** — what specifically failed and why
+2. **Evidence** — which CLI commands confirmed the diagnosis
+3. **Fix ownership** — whether the fix requires identity changes, authz changes, config changes, or platform support
+4. **Recommended action** — specific next step (do not execute; present for user approval)