@uipath/skills 1.196.0 → 1.197.0

package/hooks/send-telemetry.sh

@@ -0,0 +1,445 @@
+#!/bin/bash
+# PostToolUse telemetry hook for the UiPath skills plugin.
+#
+# Reads the hook JSON payload from stdin, decides whether the tool call is
+# attributable to THIS plugin (skill gate), resolves the UiPath environment
+# (alpha / staging / prod), and pipes one flat JSON object to `uip track`,
+# which forwards it through the CLI's own telemetry tracker as a single
+# uip.skills.tool-use Application Insights event. Calls from other plugins or
+# bare Claude Code are dropped.
+#
+# The CLI (see UiPath/cli#2600) owns transport, the App Insights connection,
+# the event name, the authenticated cloud identity, and the `source:
+# "skills-plugin"` dimension. This hook only derives + sanitizes fields and
+# gates on the opt-out flag; value sanitization stays the hook's responsibility
+# because the CLI and skills ship co-versioned.
+#
+# REGION-SCOPED EXTRACTION (see extract_fields): the payload embeds free-form
+# customer content (prompts, command lines, stdout/stderr, file contents). A
+# naive grep over the whole payload mis-extracts fields when that content
+# contains JSON-shaped text (`"success":false`, `uip solution publish`,
+# `.flow"`, `"resolvedModel":"..."`). So a single string-aware awk pass walks
+# the JSON once and pulls each field ONLY from the region it lives in:
+#   ENVELOPE (top-level)  -> toolName, toolUseId, sessionId, permissionMode,
+#                            durationMs, effortLevel (effort.level), agentType
+#   tool_input            -> skillName, uipSubcommand (command), fileExtension
+#                            (file_path), subagentType (subagent_type, or
+#                            agent_type for a Codex spawn_agent call)
+#   tool_response         -> outcome (interrupted/success), subagentModel
+#                            (resolvedModel)
+#
+# CROSS-AGENT: registered as a PostToolUse hook, this also runs under other
+# coding agents that honor hooks.json (e.g. Codex). Codex's envelope matches
+# Claude's (hook_event_name, tool_name, tool_use_id, session_id,
+# permission_mode, tool_input/{command,file_path}), so Bash-`uip` and file
+# attribution work unchanged. Differences handled / accepted: agent spawns use
+# `spawn_agent` + tool_input.agent_type (see is_uipath_call + outkey); Codex
+# omits duration_ms / effort.level (-> durationMs null, effortLevel "") and
+# serializes tool_response as a JSON STRING, not an object, so success /
+# interrupted / resolvedModel are absent and outcome is ok|unknown only.
+# Only derived, low-cardinality, PII-free values ever leave the machine.
+#
+# Non-blocking by contract: registered as an async hook in hooks.json
+# ("async": true), so Claude Code runs it in the background and never waits for
+# it. Always exits 0, swallows every error, and pipes to `uip track` in a
+# detached subshell. Cross-platform (macOS, Linux, Windows via Git Bash /
+# MSYS). Pure bash + grep/sed/awk — no jq, node, or python.
+#
+# Structure: pure helpers + side-effecting procedures (below), driven by main()
+# (bottom). Configuration is env only:
+#   UIPATH_TELEMETRY_DISABLED   Gate. Reuses the uip CLI's variable name.
+#                               Opt-out: send by DEFAULT. Skip ONLY when set to
+#                               "1". Unset (default) or "0" -> send. Absent is
+#                               treated as enabled.
+
+set +e
+
+# schemaVersion of the emitted event. Bump on ANY change to the key set so App
+# Insights can segment events emitted with older/churned schemas.
+SCHEMA_VERSION=1
+
+# --- extraction ------------------------------------------------------------
+
+# extract_fields: one string-aware awk pass over the payload (stdin). Prints
+# `key<TAB>value` lines, each field pulled ONLY from its region (see header),
+# so embedded customer content can never false-match a top-level field. String
+# values are emitted raw (escapes left as-is) and single-line (valid JSON
+# escapes control chars, so a real TAB never appears inside a value). Large,
+# uninteresting value strings (stdout, file contents, prompts) are scanned but
+# never buffered, so this stays O(n) without the awk O(n^2) string-concat trap.
+extract_fields() {
+  awk '
+    function interesting(k, d, c) {
+      if (d == 1)
+        return (k=="tool_name"||k=="tool_use_id"||k=="session_id"|| \
+                k=="permission_mode"||k=="duration_ms"||k=="agent_type"|| \
+                k=="hook_event_name")
+      if (d == 2 && c == "input")
+        return (k=="skill"||k=="command"||k=="file_path"||k=="subagent_type"|| \
+                k=="agent_type")
+      if (d == 2 && c == "response")
+        return (k=="interrupted"||k=="success"||k=="resolvedModel")
+      if (d == 2 && c == "effort")
+        return (k=="level")
+      return 0
+    }
+    # outkey: remap a JSON key to the field name read_fields expects. Codex
+    # spawn_agent carries the spawned type in tool_input.agent_type; normalize
+    # it to subagent_type so it lands in the same field as Claude (tool_input.
+    # subagent_type) and never collides with the envelope agent_type (agentType).
+    function outkey(k, d, c) {
+      if (d == 2 && c == "input" && k == "agent_type") return "subagent_type"
+      return k
+    }
+    { buf = buf $0 "\n" }
+    END {
+      n = length(buf)
+      depth = 0; instr = 0; esc = 0
+      pend = 0; pkey = ""; pdepth = 0       # pending value after a key + colon
+      ctx = ""                              # region at depth 2: input/response/effort/other
+      laststr = ""                          # last closed string (candidate key)
+      cur = ""; buffering = 0; isval = 0
+      i = 1
+      while (i <= n) {
+        c = substr(buf, i, 1)
+        if (instr) {
+          if (esc)          { if (buffering) cur = cur c; esc = 0; i++; continue }
+          if (c == "\\")    { if (buffering) cur = cur c; esc = 1; i++; continue }
+          if (c == "\"") {
+            instr = 0
+            if (isval) {
+              if (buffering) print outkey(pkey, pdepth, ctx) "\t" cur
+              pend = 0; isval = 0
+            } else {
+              laststr = cur
+            }
+            cur = ""; buffering = 0; i++; continue
+          }
+          if (buffering) cur = cur c
+          i++; continue
+        }
+        if (c == "\"") {
+          instr = 1; cur = ""
+          if (pend) { isval = 1; buffering = interesting(pkey, pdepth, ctx) }
+          else      { isval = 0; buffering = 1 }   # key strings are small
+          i++; continue
+        }
+        if (c == ":") {
+          pkey = laststr; pdepth = depth; pend = 1
+          if (depth == 1 && laststr == "tool_response") print "tool_response_seen\t1"
+          i++; continue
+        }
+        if (c == "{") {
+          if (pend) {
+            if (pdepth == 1) {
+              if (pkey == "tool_input")        ctx = "input"
+              else if (pkey == "tool_response") ctx = "response"
+              else if (pkey == "effort")        ctx = "effort"
+              else                              ctx = "other"
+            }
+            pend = 0
+          }
+          depth++; i++; continue
+        }
+        if (c == "[") {
+          if (pend) { if (pdepth == 1) ctx = "other"; pend = 0 }
+          depth++; i++; continue
+        }
+        if (c == "}" || c == "]") {
+          depth--; if (depth <= 1) ctx = ""; pend = 0; i++; continue
+        }
+        if (c == ",")  { pend = 0; i++; continue }
+        if (c == " " || c == "\t" || c == "\n" || c == "\r") { i++; continue }
+        if (pend) {                               # literal value: number/true/false/null
+          lit = ""
+          while (i <= n) {
+            c = substr(buf, i, 1)
+            if (c==","||c=="}"||c=="]"||c==" "||c=="\t"||c=="\n"||c=="\r") break
+            lit = lit c; i++
+          }
+          if (interesting(pkey, pdepth, ctx)) print outkey(pkey, pdepth, ctx) "\t" lit
+          pend = 0; continue                      # leave delimiter for the main loop
+        }
+        i++
+      }
+    }
+  '
+}
+
+# read_fields: parse extract_fields output ($1) into the field globals. The
+# while loop runs in the current shell (here-doc, not a pipe), so the
+# assignments persist.
+read_fields() {
+  event=""; tool=""; tool_use_id=""; session_id=""; permission_mode=""
+  duration_ms=""; agent_type=""; skill=""; command=""; file_path=""
+  subagent_type=""; interrupted=""; success=""; resolved_model=""
+  effort_level=""; response_seen=""
+  local k v
+  while IFS="$(printf '\t')" read -r k v; do
+    case "$k" in
+      hook_event_name)    event="$v" ;;
+      tool_name)          tool="$v" ;;
+      tool_use_id)        tool_use_id="$v" ;;
+      session_id)         session_id="$v" ;;
+      permission_mode)    permission_mode="$v" ;;
+      duration_ms)        duration_ms="$v" ;;
+      agent_type)         agent_type="$v" ;;
+      skill)              skill="$v" ;;
+      command)            command="$v" ;;
+      file_path)          file_path="$v" ;;
+      subagent_type)      subagent_type="$v" ;;
+      interrupted)        interrupted="$v" ;;
+      success)            success="$v" ;;
+      resolvedModel)      resolved_model="$v" ;;
+      level)              effort_level="$v" ;;
+      tool_response_seen) response_seen="1" ;;
+    esac
+  done <<EOF
+$1
+EOF
+}
+
+# --- relevance gate --------------------------------------------------------
+
+# is_uipath_call: 0 if this call is attributable to the plugin, else 1. No
+# "active plugin" field exists, so attribute per-call from tool_input signals
+# only (command / file_path), so stdout or prompt content can never
+# over-attribute.
+is_uipath_call() {
+  case "$tool" in
+    Skill)
+      case "$skill" in uipath:*|uipath-*) return 0 ;; esac
+      ;;
+    Agent|spawn_agent)
+      # UiPath agents, or a built-in/generic agent type — NOT custom agents from
+      # other plugins (`<plugin>:<name>`) or user-defined ones. Claude Code spawns
+      # via `Agent` + tool_input.subagent_type; Codex via `spawn_agent` +
+      # tool_input.agent_type (the awk normalizes that to subagent_type). `default`
+      # is Codex's generic agent — the equivalent of Claude's general-purpose/claude.
+      case "$subagent_type" in
+        uipath:*|uipath-*) return 0 ;;
+        general-purpose|Explore|Plan|claude|claude-code-guide|statusline-setup|fork|default) return 0 ;;
+      esac
+      ;;
+    Bash|PowerShell)
+      printf '%s' "$command" \
+        | grep -Eq '(^|[\\"[:space:];|&(])(uip|rpa-tool)[[:space:]]|\$UIP\b' && return 0
+      ;;
+    Edit|Write|Read|Glob|Grep)
+      printf '%s' "$file_path" \
+        | grep -Eiq '\.(cs|flow|xaml|uipx|bpmn)$|(^|[/\\])(agent|caseplan|project|app\.config|action-schema)\.json$' && return 0
+      ;;
+  esac
+  return 1
+}
+
+# --- environment resolution ------------------------------------------------
+
+# cache_val <file> <key>: emit a cached value stripped to a safe charset. Parses
+# the cache as DATA — never `source` it, so a tampered cache can't execute
+# arbitrary shell in this hook's context.
+cache_val() {
+  grep -E "^$2=" "$1" 2>/dev/null | head -1 | cut -d= -f2- | tr -cd 'A-Za-z0-9:._/-'
+}
+
+# resolve_environment: set env_name + base_url from `uip login status` (~0.5s),
+# cached per-user for 1h so only one tool call per hour pays the cost. The cache
+# dir is per-user, owner-only (NOT world-writable /tmp), so another local user
+# can't pre-create the file. chmod is a no-op on Windows but harmless.
+resolve_environment() {
+  local cache_dir cache ttl now _ts status_json
+  cache_dir="${XDG_CACHE_HOME:-$HOME/.cache}/uipath-telemetry"
+  mkdir -p "$cache_dir" 2>/dev/null && chmod 700 "$cache_dir" 2>/dev/null
+  cache="$cache_dir/env.cache"
+  ttl=3600
+  now="$(date +%s 2>/dev/null || echo 0)"
+
+  env_name="unknown"; base_url=""; _ts=0
+  if [ -f "$cache" ]; then
+    _ts="$(cache_val "$cache" _ts)"
+    env_name="$(cache_val "$cache" env_name)"
+    base_url="$(cache_val "$cache" base_url)"
+    case "$_ts" in *[!0-9]*|"") _ts=0 ;; esac   # non-numeric -> treat as stale
+  fi
+
+  [ "$(( now - _ts ))" -ge "$ttl" ] || return 0
+
+  status_json="$(uip login status --output json 2>/dev/null)"
+  base_url="$(printf '%s' "$status_json" \
+    | grep -oE '"BaseUrl"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')"
+  case "$base_url" in
+    *alpha.uipath.com*)   env_name="alpha" ;;
+    *staging.uipath.com*) env_name="staging" ;;
+    *cloud.uipath.com*)   env_name="prod" ;;
+    "")                   env_name="unknown" ;;
+    *)                    env_name="other" ;;
+  esac
+  {
+    echo "_ts=$now"
+    echo "env_name=$env_name"
+    echo "base_url=$base_url"
+  } > "$cache" 2>/dev/null
+}
+
+# --- field derivation ------------------------------------------------------
+
+# derive_fields: set skill_name, uip_subcommand, file_ext from the parsed
+# tool_input values (so stdout content can't leak in).
+derive_fields() {
+  skill_name=""; uip_subcommand=""; file_ext=""
+  case "$tool" in
+    Skill)
+      skill_name="$skill"
+      ;;
+    Bash|PowerShell)
+      # e.g. "solution publish" from "uip solution publish --output json".
+      uip_subcommand="$(printf '%s' "$command" \
+        | grep -oE '(uip|\$UIP)[[:space:]]+[a-z][a-z-]*([[:space:]]+[a-z][a-z-]*)?' \
+        | head -1 | sed -E 's/^(uip|\$UIP)[[:space:]]+//')"
+      ;;
+    Edit|Write|Read|Glob|Grep)
+      file_ext="$(printf '%s' "$file_path" | grep -oE '\.[A-Za-z0-9]+$' | head -1)"
+      case "$file_path" in
+        *agent.json)    file_ext="agent.json" ;;
+        *caseplan.json) file_ext="caseplan.json" ;;
+      esac
+      ;;
+  esac
+}
+
+# compute_outcome: print outcome from the tool_response region ONLY — content
+# never flips it.
+#   interrupted == true -> interrupted (takes precedence)
+#   success     == false -> failure
+#   tool_response present, no failure signal -> ok (Read/Edit/Write/most MCP)
+#   no tool_response at all -> unknown
+compute_outcome() {
+  if   [ "$interrupted" = "true" ];  then printf 'interrupted'
+  elif [ "$success" = "false" ];     then printf 'failure'
+  elif [ -n "$response_seen" ];      then printf 'ok'
+  else                                    printf 'unknown'
+  fi
+}
+
+# model_family <resolvedModel>: print the low-cardinality family and drop the
+# context-window marker (e.g. claude-opus-4-8[1m] -> opus). Empty when absent
+# (plain main-loop call); `other` for an unrecognized family.
+model_family() {
+  case "$1" in
+    "")       printf '' ;;
+    *opus*)   printf 'opus' ;;
+    *sonnet*) printf 'sonnet' ;;
+    *haiku*)  printf 'haiku' ;;
+    *fable*)  printf 'fable' ;;
+    *)        printf 'other' ;;
+  esac
+}
+
+# read_skills_version: skills/CLI co-version from version-manifest.json (NOT
+# git, NOT the plugin package version). The CLI's own app version already rides
+# the tracker as application_Version, so no separate cliVersion is sent.
+read_skills_version() {
+  grep -oE '"skillsVersion"[[:space:]]*:[[:space:]]*"[^"]*"' \
+    "${CLAUDE_PLUGIN_ROOT:-.}/version-manifest.json" 2>/dev/null \
+    | head -1 | sed 's/.*"\([^"]*\)"$/\1/'
+}
+
+# san: sanitize free-ish text to keep the assembled JSON valid and bounded.
+# Strips anything outside a safe charset (so no quotes / backslashes / control
+# chars / pipes survive) and caps length.
+san() { printf '%s' "$1" | tr -c 'A-Za-z0-9:._/ -' '_' | cut -c1-120; }
+
+# build_event_json: assemble the canonical, ordered, flat JSON from the
+# (already sanitized) field globals + dur_json + SCHEMA_VERSION. The key set is
+# defined ONCE here and assembled by iteration (fixed order, every key always
+# emitted). Each row is `name|type|value`: `s` -> JSON string, `n` -> JSON
+# number/literal. Sanitized values cannot contain `|` (san maps it to `_`).
+build_event_json() {
+  local spec json sep fkey ftyp fval
+  spec="schemaVersion|n|$SCHEMA_VERSION
+toolName|s|$tool
+skillName|s|$skill_name
+uipSubcommand|s|$uip_subcommand
+fileExtension|s|$file_ext
+environment|s|$env_name
+baseUrl|s|$base_url
+outcome|s|$outcome
+permissionMode|s|$permission_mode
+effortLevel|s|$effort_level
+skillsVersion|s|$skills_ver
+toolUseId|s|$tool_use_id
+sessionId|s|$session_id
+subagentModel|s|$subagent_model
+subagentType|s|$subagent_type
+agentType|s|$agent_type
+durationMs|n|$dur_json"
+  json="{"; sep=""
+  while IFS='|' read -r fkey ftyp fval; do
+    [ -n "$fkey" ] || continue
+    case "$ftyp" in
+      n) json="$json$sep\"$fkey\":$fval" ;;
+      *) json="$json$sep\"$fkey\":\"$fval\"" ;;
+    esac
+    sep=","
+  done <<EOF
+$spec
+EOF
+  printf '%s}' "$json"
+}
+
+# --- main ------------------------------------------------------------------
+main() {
+  # Opt-out: send by default; skip only when telemetry is explicitly disabled
+  # (UIPATH_TELEMETRY_DISABLED=1 or =true). Matches the CLI's isTelemetryDisabled()
+  # gate, so `uip track` and this hook short-circuit on the same values.
+  case "${UIPATH_TELEMETRY_DISABLED:-0}" in 1|true) exit 0 ;; esac
+
+  payload="$(cat)"
+  read_fields "$(printf '%s' "$payload" | extract_fields)"
+
+  [ "$event" = "PostToolUse" ] || exit 0
+  is_uipath_call || exit 0
+
+  resolve_environment
+  derive_fields
+
+  outcome="$(compute_outcome)"
+  # durationMs is a JSON number. Emit JSON null (not 0) when absent, so a missing
+  # value doesn't skew latency aggregations. The CLI drops a null-valued
+  # property, so a missing duration records as "no data". Stays unquoted.
+  case "$duration_ms" in ''|*[!0-9]*) dur_json="null" ;; *) dur_json="$duration_ms" ;; esac
+  subagent_model="$(model_family "$resolved_model")"
+  skills_ver="$(read_skills_version)"
+
+  # Sanitize every string field before assembly.
+  tool="$(san "$tool")"
+  skill_name="$(san "$skill_name")"
+  uip_subcommand="$(san "$uip_subcommand")"
+  file_ext="$(san "$file_ext")"
+  env_name="$(san "$env_name")"
+  base_url="$(san "$base_url")"
+  outcome="$(san "$outcome")"
+  permission_mode="$(san "$permission_mode")"
+  effort_level="$(san "$effort_level")"
+  skills_ver="$(san "$skills_ver")"
+  tool_use_id="$(san "$tool_use_id")"
+  session_id="$(san "$session_id")"
+  subagent_model="$(san "$subagent_model")"
+  subagent_type="$(san "$subagent_type")"
+  agent_type="$(san "$agent_type")"
+
+  # Hand off to the CLI telemetry tracker. The CLI hard-codes the event name
+  # (uip.skills.tool-use), stamps source: "skills-plugin", attaches the
+  # authenticated cloud identity + CLI app version, and owns transport + flush;
+  # it drops any non-scalar value (so a null durationMs disappears). Send no
+  # `event` key, no envelope, and no `source` (the CLI overrides it).
+  #
+  # Detached subshell ( cmd & ) survives this hook's exit so the agent never
+  # waits. `uip track` is never-fail (exits 0, emits nothing when telemetry is
+  # opted out); piping to it is harmless even if the CLI is absent.
+  ( printf '%s' "$(build_event_json)" | uip track >/dev/null 2>&1 & )
+
+  exit 0
+}
+
+main

package/hooks/suggest-permissions.sh

@@ -9,6 +9,12 @@ if [ -z "${CLAUDE_PLUGIN_ROOT:-}" ]; then
   exit 0
 fi
 
+# Codex exposes Claude-compatible plugin environment variables for hook
+# compatibility. This nudge is Claude-specific, so keep Codex sessions silent.
+if [ -n "${PLUGIN_ROOT:-}" ]; then
+  exit 0
+fi
+
 # Candidate settings files, most-to-least specific.
 candidates=()
 if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then

package/package.json

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

package/skills/uipath-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. |