@uipath/skills 1.196.0 → 1.197.0-preview.0

package/skills/uipath-admin/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uipath-admin
-description: "UiPath Admin via `uip admin` — Identity Server (users, groups, robot accounts, external OAuth2 apps, secrets), Authorization (custom roles, role assignments, permission catalog, effective-access via check-access PDP), OMS (org read/update, tenant lifecycle, service provisioning, regions, async operation polling), IP Restriction (allowlist, enforcement switch, bypass rules, lockout safety), Audit (event sources, paginated queries, ZIP or single-CSV exports — login history, compliance dumps, who-did-what-when-where on a resource). For Orchestrator-specific roles/permissions/folders/jobs→uipath-platform. For RPA workflows→uipath-rpa."
+description: "UiPath Admin via `uip admin` — Identity Server (users, groups, robot accounts, external OAuth2 apps, secrets), Authorization (custom roles, role assignments, permission catalog, effective-access via check-access PDP), OMS (org read/update, tenant lifecycle, service provisioning, regions, async operation polling), IP Restriction (allowlist, enforcement switch, bypass rules, lockout safety), Audit (event sources, paginated queries, day-wise-JSON-folder or single-CSV exports — login history, compliance dumps, who-did-what-when-where on a resource). Troubleshoot: diagnose access-denied, investigate login failures, role misconfiguration, IP lockout, PAT/app auth issues. For Orchestrator-specific roles/permissions/folders/jobs→uipath-platform. For RPA workflows→uipath-rpa."
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
 ---
 
@@ -49,9 +49,9 @@ Administrative operations on UiPath via `uip admin` — Identity Server, Authori
 
 Activate on both **explicit audit requests** and **natural-language investigation intent** — users rarely say "audit events" by name.
 
-- **Explicit** — `uip admin audit` commands; list sources / targets / types; query, filter, paginate, or export events; CSV/ZIP dump of audit history for a window.
+- **Explicit** — `uip admin audit` commands; list sources / targets / types; query, filter, paginate, or export events; CSV or per-day-JSON dump of audit history for a window.
 - **Query audit events** — list event sources, filter events by source / target / type / user / status / time window at org or tenant scope
-- **Export audit events** — chunked download from the long-term store (one call per UTC day, atomic abort on any chunk failure) as a ZIP of day-wise JSON files (default) or a single merged CSV via `--file-format csv`
+- **Export audit events** — chunked download from the long-term store (one call per UTC day, atomic abort on any chunk failure) as a folder of day-wise JSON files (default) or a single merged CSV via `--file-format csv`
 - **Membership / license phrasings** — "who joined / left the organization", "who was made an admin", "license changes", "cross-tenant audit"
 - **Sign-in / authentication phrasings** — "failed/successful logins", "login history for user X", "who's been signing in"
 - **Tenant-activity phrasings** — "what happened on tenant X", "asset/queue/folder edits", "queue items processed", "job failures", "Action Center task changes", "Apps / AgentHub / Document Understanding / Integration Service / Test Manager activity"
@@ -60,6 +60,22 @@ Activate on both **explicit audit requests** and **natural-language investigatio
 
 > **Scope routing** (which phrasing → `org` vs `tenant`, and why) lives in [audit-workflow-guide.md → Audit scope disambiguation](references/audit-workflow-guide.md#audit-scope-disambiguation--route-by-user-phrasing). Critical Rule 23 governs the stop-and-ask requirement when scope is ambiguous.
 
+### Troubleshoot
+
+Activate on **access/auth/identity troubleshooting** — users report symptoms, not audit verbs.
+
+- **Diagnose access denied** — "user can't access X", "403 on API", "new hire has no permissions" → resolve principal, check-access, inspect role assignments. Playbook: [identity-troubleshoot-guide.md → Playbook 1](references/identity-troubleshoot-guide.md#playbook-1--user-cant-access-resource-x)
+- **Investigate login failures** — "failed login attempts", "account compromised?", "suspicious sign-ins" → org-scoped audit login-history investigation. Playbook: [identity-troubleshoot-guide.md → Playbook 2](references/identity-troubleshoot-guide.md#playbook-2--suspicious-login-activity)
+- **Diagnose role misconfiguration** — "custom role doesn't work", "user has role but can't do X" → inspect role actions, verify scope alignment. Playbook: [identity-troubleshoot-guide.md → Playbook 3](references/identity-troubleshoot-guide.md#playbook-3--role-misconfiguration)
+- **Diagnose IP restriction lockout** — "can't access platform from new office", "all users blocked" → my-ip + ip-ranges list + enforcement get. Playbook: [identity-troubleshoot-guide.md → Playbook 4](references/identity-troubleshoot-guide.md#playbook-4--ip-restriction-lockout)
+- **Diagnose PAT / external app failures** — "API returns 401", "PAT stopped working", "external app can't authenticate" → check expiry, scopes, audit for revocation. Playbook: [identity-troubleshoot-guide.md → Playbook 5](references/identity-troubleshoot-guide.md#playbook-5--pat-or-external-app-not-working)
+- **Diagnose SMTP email delivery failures** — "invitations not sending", "SMTP broken" → smtp get + smtp test
+- **Investigate stuck tenant operations** — "tenant create not completing", "operation stuck" → poll operation status
+- **Identify service provisioning no-ops** — "service still enabled after remove" → platform-pinned services
+- **Triage robot account authentication issues** — "robot not authenticating" → identity vs credential model confusion
+
+> **Structured diagnose capability index** with failure-mode lookup and diagnostic priority ladder: [diagnose/CAPABILITY.md](references/diagnose/CAPABILITY.md). Quick investigation playbooks: [identity-troubleshoot-guide.md](references/identity-troubleshoot-guide.md).
+
 ## Critical Rules
 
 Each rule is the agent contract. Per-area detail is in the linked reference files.
@@ -107,7 +123,7 @@ Each rule is the agent contract. Per-area detail is in the linked reference file
 27. **Bound the time window, ISO 8601 in UTC.** Don't call `audit <scope> events` without `--from-date` and `--to-date` on a noisy tenant. Accepted formats: date-only (`2026-04-01`) or with time (`2026-04-01T14:30:00Z`). **`--to-date` is inclusive of the exact instant** — to capture a full final day, pass the start of the next day or `T23:59:59.999Z`.
 28. **`--tenant-id` is silently ignored on `org`-scoped audit commands.** If you find yourself reaching for it on `audit org events`, switch to `audit tenant` instead.
 29. **On 401 from audit, do NOT retry.** The token is missing the `Audit.Read` scope; tell the user to `uip logout && uip login`.
-30. **`audit <scope> export` writes a ZIP (default) or a single merged CSV from the long-term store.** `--from-date`, `--to-date`, and `--output-file` are all required; dates per Rule 27. **`--file-format <zip|csv>`** selects the shape: `zip` (default) is one JSON file per UTC day; `csv` merges every event into one CSV — pick `csv` when the user wants a flat spreadsheet/Excel-friendly dump and `zip` for archival or per-day JSON. Match the `--output-file` extension to the format (`.zip` / `.csv`). **Never overwrite a path the user did not explicitly approve** — surface the resolved `--output-file` and confirm before running.
+30. **`audit <scope> export` writes into a base directory (`--output-path`): a uniquely-named folder of day-wise JSON files (default) or a single merged CSV.** `--from-date`, `--to-date`, and `--output-path` are all required; dates per Rule 27. `--output-path` is a **base directory** (created if missing) — **pass a directory only, never a filename or extension**; the CLI creates a uniquely-named `audit_<from>_<to>_<generated-at>` output inside it (folder for `json`, `.csv` for `csv`), so repeated exports of the same window never collide. **Do not hand-craft the per-export name.** **`--file-format <json|csv>`** selects the shape: `json` (default) = a folder of `<YYYY-MM-DD>.json` files; `csv` = one merged CSV — pick `csv` for a flat spreadsheet/Excel-friendly dump, `json` for per-day files. **Confirm the base directory with the user before running**, then report the generated `Path` (and `GeneratedAt`) from the result.
 
 ### IP Restriction
 
@@ -214,3 +230,7 @@ For per-area full checklists, follow the table's inline links: Identity → [ide
 | Audit CLI reference | [references/audit-commands.md](references/audit-commands.md) |
 | Audit investigation workflows (scope disambiguation, who-did-X, login history, date-range dump, overview) | [references/audit-workflow-guide.md](references/audit-workflow-guide.md) |
 | Paginate audit events beyond 200 | [references/audit-commands.md](references/audit-commands.md) + Rule 25 |
+| Troubleshoot access denied, login failures, role misconfig, IP lockout, PAT/app auth | [references/identity-troubleshoot-guide.md](references/identity-troubleshoot-guide.md) |
+| Diagnose capability index (structured) | [references/diagnose/CAPABILITY.md](references/diagnose/CAPABILITY.md) |
+| Failure mode lookup (12 named patterns) | [references/diagnose/references/failure-modes.md](references/diagnose/references/failure-modes.md) |
+| Diagnostic priority ladder (sequential triage) | [references/diagnose/references/troubleshooting-guide.md](references/diagnose/references/troubleshooting-guide.md) |

package/skills/uipath-admin/references/audit-commands.md

@@ -26,7 +26,7 @@ uip admin audit
 |---|---|
 | `audit <scope> sources` | array of `AuditEventSourceDto` |
 | `audit <scope> events` | object `{auditEvents, next, previous}` |
-| `audit <scope> export` | object `{Path, Bytes, Format, Days, NonEmptyDays}` (+ `Events` when `--file-format csv`) |
+| `audit <scope> export` | object `{Path, Format, Bytes, Days, NonEmptyDays}` (+ `Files` for `json`, + `Events` for `--file-format csv`) |
 
 `events` is the one verb that legitimately returns an object — pagination cursors live alongside the rows. Full shape detail per verb in the sections below.
 
@@ -138,22 +138,22 @@ uip admin audit tenant events --from-date 2026-04-22T00:00:00Z --to-date 2026-04
 
 ## uip admin audit `<scope>` export
 
-Export the long-term audit store covering `[--from-date, --to-date]` — as a ZIP of day-wise JSON files (default) or a single merged CSV.
+Export the long-term audit store covering `[--from-date, --to-date]` into a **base directory** (`--output-path`). Each run creates a uniquely-named output inside it — a folder of day-wise JSON files (default) or a single merged CSV — named `audit_<from>_<to>_<generated-at>` (generated-at to the second) so repeated exports of the same window never collide.
 
 ```bash
-# Default — ZIP of one JSON file per UTC day
+# Default (json) — creates ./audit-exports/audit_2026-01-01_2026-02-01_<generatedAt>/ with one JSON file per UTC day
 uip admin audit tenant export \
   --from-date 2026-01-01 \
   --to-date 2026-02-01 \
-  --output-file ./audit-jan.zip \
+  --output-path ./audit-exports \
   --output json
 
-# Single merged CSV of every event
+# Single merged CSV — creates ./audit-exports/audit_2026-01-01_2026-02-01_<generatedAt>.csv
 uip admin audit tenant export \
   --from-date 2026-01-01 \
   --to-date 2026-02-01 \
   --file-format csv \
-  --output-file ./audit-jan.csv \
+  --output-path ./audit-exports \
   --output json
 ```
 
@@ -161,45 +161,49 @@ uip admin audit tenant export \
 
 | Flag | Required | Description |
 |---|---|---|
-| `--output-file <path>` | **yes** | Where to write the export. Parent dir is created if missing; existing file is overwritten. Resolved to absolute internally. Match the extension to `--file-format` (`.zip` / `.csv`). |
+| `--output-path <dir>` | **yes** | **Base directory** for the export (created if missing). **Pass a directory only — never a filename or extension**; the CLI generates the per-export name. A uniquely-named output is created inside it — a folder of day-wise JSON files (`json`) or a single `.csv` (`csv`), named `audit_<from>_<to>_<generated-at>` (generated-at to the second) so repeated exports never collide. Resolved to absolute internally. |
+| `--output-file <dir>` | no | **Deprecated** alias for `--output-path` (kept for backward compatibility; treated as a base directory, not a file). Prefer `--output-path` — using `--output-file` emits a deprecation warning. |
 | `--from-date <iso>` | **yes** | Start of time interval. Both bounds are required by Commander before any HTTP call. |
 | `--to-date <iso>` | **yes** | End of time interval. |
-| `--file-format <zip\|csv>` | no | Output shape. `zip` (default) = one JSON file per UTC day inside a ZIP. `csv` = every event merged into a single RFC 4180 CSV under a shared header. Invalid values fail before any HTTP call with `Invalid --file-format '<v>'. Use 'zip' or 'csv'.` |
+| `--file-format <json\|csv>` | no | Output shape. `json` (default) = a folder holding one `<YYYY-MM-DD>.json` file per UTC day. `csv` = every event merged into a single RFC 4180 CSV under a shared header. Invalid values fail before any HTTP call with `Invalid --file-format '<v>'. Use 'json' or 'csv'.` |
 | `--login-validity <minutes>` | no | Token-refresh hint. |
 | `--tenant-id <guid>` | no | **Tenant scope only.** Override the active tenant. |
 
 **Output `Code`:** `AuditOrgExport` / `AuditTenantExport`.
 
-**Output `Data`:** `Format` echoes the chosen `--file-format`. The CSV path adds `Events` (total rows written, excluding the header); the ZIP path omits it.
+**Output `Data`:** `Format` echoes the chosen `--file-format`. `Path` is the **generated** output created under `--output-path` (the `audit_<from>_<to>_<generatedAt>` folder for `json`, or the `.csv` file for `csv`), and `GeneratedAt` is its ISO generation timestamp. The `json` path also reports `Files` (number of day-wise files written); the `csv` path reports `Events` (total rows, excluding the header).
 
 ```json
-// --file-format zip (default)
+// --file-format json (default) — Path is the generated folder under the base dir
 {
-  "Path": "C:\\absolute\\path\\to\\audit-jan.zip",
+  "Path": "C:\\absolute\\path\\to\\audit-exports\\audit_2026-01-01_2026-02-01_20260617T112630",
+  "Format": "json",
+  "Files": 27,
   "Bytes": 1841,
-  "Format": "zip",
   "Days": 31,
-  "NonEmptyDays": 27
+  "NonEmptyDays": 27,
+  "GeneratedAt": "2026-06-17T11:26:30.000Z"
 }
 
-// --file-format csv
+// --file-format csv — Path is the generated .csv under the base dir
 {
-  "Path": "C:\\absolute\\path\\to\\audit-jan.csv",
-  "Bytes": 98765,
+  "Path": "C:\\absolute\\path\\to\\audit-exports\\audit_2026-01-01_2026-02-01_20260617T112630.csv",
   "Format": "csv",
+  "Bytes": 98765,
   "Days": 31,
   "NonEmptyDays": 27,
-  "Events": 1234
+  "Events": 1234,
+  "GeneratedAt": "2026-06-17T11:26:30.000Z"
 }
 ```
 
 **Implementation notes (worth knowing for diagnostic conversations):**
 
 - Both formats share the same fetch: the CLI issues **one HTTP call per UTC day** inside `[from, to]` and aggregates the per-day responses. Mirrors the `audit-dowload-from-longterm-store.sh` pattern in the AuditService repo.
-- **ZIP (default):** per-day entries land at the **root of the output ZIP** named `<YYYY-MM-DD>.txt` (no folder prefix). Each `.txt` is a JSON array of events with PascalCase keys (`Id`, `CreatedOn`, `EventType`, …).
+- **JSON (default):** a uniquely-named `audit_<from>_<to>_<generated-at>` **folder** is created under `--output-path`, holding one file per UTC day named `<YYYY-MM-DD>.json` (nested-ZIP entries from the server are flattened to `<inner>_<outer>.json`; same-name collisions get an iso-day suffix). The server names the per-day payloads `.txt`; the CLI writes them with a `.json` extension since each is a JSON array of events with PascalCase keys (`Id`, `CreatedOn`, `EventType`, …). Entry names are validated as safe basenames and confirmed to resolve inside the folder before any write (no path traversal / Zip-Slip).
 - **CSV:** the same per-day JSON arrays are parsed and merged into **one** RFC 4180 CSV (CRLF line endings, header row first). Columns follow the long-term-store field order — `Id, CreatedOn, OrganizationId, TenantId, ActorId, ActorName, ActorEmail, ActorDetails, EventType, EventSource, EventTarget, EventDetails, Status, ClientInfo` — with any extra server fields appended (union across events) so no data is dropped. `Status` is the numeric enum (`0`=Success, `1`=Failure); nested objects (e.g. `ClientInfo`) are JSON-stringified into the cell. String cells beginning with `= + - @` (or TAB/CR) are prefixed with a single quote to neutralize spreadsheet formula injection.
-- On any single-day HTTP failure (or, for CSV, a day whose payload is not valid JSON), **no file is written** and the error message identifies which day failed. Earlier successful chunks are not preserved (atomic export).
-- `Days` reports the total number of UTC days requested; `NonEmptyDays` reports how many actually had data. A long export with `NonEmptyDays: 0` means the window was entirely idle, not that the export failed. For CSV, `Events: 0` yields a header-only file.
+- On any single-day HTTP failure (or, for CSV, a day whose payload is not valid JSON), **nothing is written** — for `json` the output folder isn't even created — and the error message identifies which day failed. Earlier successful chunks are not preserved (atomic export).
+- `Days` reports the total number of UTC days requested; `NonEmptyDays` reports how many actually had data. A long export with `NonEmptyDays: 0` means the window was entirely idle, not that the export failed. For `json`, `Files` counts the day-wise files written; for `csv`, `Events: 0` yields a header-only file.
 
 ---
 
@@ -209,7 +213,7 @@ These appear on every command (not just audit) — set at the program level by t
 
 | Flag | Description |
 |---|---|
-| `--output <table\|json\|yaml\|plain>` | Format of the success/failure envelope on stdout. Defaults to `json`. The export file body (ZIP or CSV) is unaffected — `--output` only controls the metadata envelope, NOT `--file-format`. |
+| `--output <table\|json\|yaml\|plain>` | Format of the success/failure envelope on stdout. Defaults to `json`. The exported files (the per-day JSON folder, or the CSV) are unaffected — `--output` only controls the metadata envelope, NOT `--file-format`. |
 | `--output-filter <jmespath>` | JMESPath query applied to the envelope before printing. Useful for `events`/`sources`. Less useful for `export` (envelope is small). |
 | `--log-level <debug\|info\|warn\|error>` | Logger threshold. Logs go to stderr. |
 | `--log-file <path>` | Redirect logs from stderr to a file. |

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