@uipath/skills 1.196.0 → 1.197.0-preview.0

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)

package/skills/uipath-admin/references/identity-troubleshoot-guide.md

@@ -0,0 +1,251 @@
+# Identity & Authorization Troubleshooting Guide
+
+Common investigation playbooks for identity, access, and security issues. Each starts from a user-reported symptom and resolves to a diagnosis using `uip admin` commands.
+
+> Every command assumes the user has run `uip login`. Every command uses `--output json`.
+
+---
+
+## Playbook 1 — "User can't access resource X"
+
+**Symptom:** "Alice can't publish to the Finance folder" / "Bob gets 403 on the API" / "The new contractor has no access to anything"
+
+**Root causes (most → least common):**
+1. Missing role assignment at the correct scope
+2. Role exists but lacks the specific permission
+3. User not in the expected group
+4. User account disabled or not yet activated
+
+### Step 1 — Resolve the principal
+
+```bash
+uip admin users list --search "<EMAIL_OR_NAME>" --output json
+```
+
+Extract the user's `id` (GUID) and `isActive` status. If `isActive` is `false`, the user is deactivated — that's the diagnosis. Otherwise proceed.
+
+### Step 2 — Check effective access
+
+```bash
+uip admin authorization check-access <USER_GUID> --scope Tenant --output json
+```
+
+Or for folder-level:
+
+```bash
+uip admin authorization check-access <USER_GUID> --scope Folder --folder-id <FOLDER_UUID> --output json
+```
+
+Inspect `Data.roleAssignments[]` — each entry shows `roleName`, `scopeType`, and `securityPrincipalType` (`direct` = assigned to the user; `inherited` or `Group` = inherited from a group). Look for whether the needed permission (e.g., `Publish`) appears anywhere. If absent, that's the gap.
+
+### Step 3 — List current role assignments
+
+```bash
+uip admin authorization roles assignments list --identity-id <USER_GUID> --output json
+```
+
+Compare the user's assignments against what's needed. Check `ownerServiceName` and `scopeType` — a role scoped to `Organization` won't grant folder-level permissions.
+
+### Step 4 — Check group membership
+
+```bash
+uip admin groups list --output json
+```
+
+For each relevant group, check if the user is a member. If the user should inherit permissions via a group but isn't in it, that's the gap:
+
+```bash
+uip admin groups members list <GROUP_ID> --output json
+```
+
+### Step 5 — Diagnose and recommend
+
+Present findings as:
+- **Principal:** `<displayName> (<email>) — <id>`
+- **Current access:** list of roles + scopes
+- **Missing:** specific role or permission needed
+- **Fix:** "Assign role X at scope Y" or "Add user to group Z"
+
+---
+
+## Playbook 2 — "Suspicious login activity"
+
+**Symptom:** "Failed login attempts" / "Account may be compromised" / "Unknown logins from strange locations"
+
+**Scope: `org`.** Login events (User Login, Robot Login, External App Login) are org-level audit events under Identity → Authentication.
+
+### Step 1 — Resolve the user
+
+```bash
+uip admin users list --search "<EMAIL>" --output json
+```
+
+Extract the `id` for `--user-id` filtering.
+
+### Step 2 — Discover login event types
+
+```bash
+uip admin audit org sources --output json > /tmp/sources.json
+```
+
+Extract the User Login type GUID:
+```bash
+jq -r '.Data[] | select(.name == "Identity") | .eventTargets[] | select(.name == "Authentication") | .eventTypes[] | select(.name == "User Login") | .id' /tmp/sources.json
+```
+
+### Step 3 — Query login events
+
+```bash
+uip admin audit org events \
+  --user-id <USER_GUID> \
+  --type    <USER_LOGIN_TYPE_GUID> \
+  --from-date <START_ISO8601> \
+  --to-date   <END_ISO8601> \
+  --limit 100 \
+  --output json
+```
+
+### Step 4 — Analyze
+
+For each event in `Data.auditEvents[]`, check:
+- `status` — `0` = Success, `1` = Failure
+- `clientInfo` — parse JSON string for `ipAddress` and `ipCountry`
+- `createdOn` — timestamp (UTC)
+
+Flag: multiple failures from different IPs, logins from unexpected countries, or logins outside business hours.
+
+---
+
+## Playbook 3 — "Role misconfiguration"
+
+**Symptom:** "Custom role doesn't grant what it should" / "User has a role but still can't do X"
+
+### Step 1 — Inspect the role
+
+```bash
+uip admin authorization roles list --output json
+```
+
+Find the role by name, then:
+
+```bash
+uip admin authorization roles get <ROLE_ID> --output json
+```
+
+Check `actions[]` — these are the permission strings (e.g., `OR.Folders.Create`). Compare against the Permission Catalog:
+
+```bash
+uip admin authorization permissions list --service <SERVICE> --output json
+```
+
+### Step 2 — Verify scope alignment
+
+The role's `scopeType` (Organization / TenantGlobal / Tenant / Project) must match the assignment scope. A role scoped to `Organization` cannot be assigned at `Folder` scope. Check the assignment:
+
+```bash
+uip admin authorization roles assignments list --identity-id <USER_GUID> --output json
+```
+
+Verify `ownerServiceName` matches the scope-path service segment (Rule 17 from SKILL.md).
+
+### Step 3 — Diagnose
+
+Common misconfigurations:
+- **Scope mismatch:** role is `Tenant` but user needs folder-level access → create a `Project`-scoped role or use Orchestrator folder roles instead (`uip or roles`)
+- **Missing actions:** role omits required permissions → `roles update` with the full action set (re-fetch first — Rule 12)
+- **Wrong service:** role's `ownerServiceName` doesn't match the target service
+
+---
+
+## Playbook 4 — "IP restriction lockout"
+
+**Symptom:** "Can't access the platform from new office" / "All users blocked" / "IP restriction locked us out"
+
+### Step 1 — Check enforcement status
+
+```bash
+uip admin ip-restriction enforcement get --output json
+```
+
+If `isEnabled` is `false`, IP restriction is not the cause — look elsewhere.
+
+### Step 2 — Check caller's IP
+
+```bash
+uip admin ip-restriction my-ip --output json
+```
+
+Returns `Data.ipAddress` — the public IP the platform sees for the caller.
+
+### Step 3 — List allowed ranges
+
+```bash
+uip admin ip-restriction ip-ranges list --output json
+```
+
+Compare the caller's IP against every entry's CIDR range. If the IP is not covered by any entry, that's the lockout cause.
+
+### Step 4 — Check bypass rules
+
+```bash
+uip admin ip-restriction bypass-rules list --output json
+```
+
+Bypass rules exempt specific URL patterns from IP restriction. If the affected access is via an API endpoint matching a bypass pattern, the IP restriction should not apply — investigate other causes.
+
+### Step 5 — Resolution options
+
+- **Add the new IP/CIDR:** `ip-ranges create --name "<LOCATION>" --cidr <CIDR> --output json`
+- **Disable enforcement temporarily:** `ip-restriction enforcement disable --output json` (if accessible from an allowed IP)
+- **Platform recovery:** if fully locked out, use the Portal recovery flow (no CLI bypass exists — Rule 32)
+
+---
+
+## Playbook 5 — "PAT or external app not working"
+
+**Symptom:** "API calls return 401" / "PAT stopped working" / "External app can't authenticate"
+
+### Step 1 — List PATs or external apps
+
+For PATs:
+```bash
+uip admin pat list --output json
+```
+
+Check `expiration` — expired PATs return 401 silently. If the token is absent from the list, it was revoked (revocation is a hard delete — no `isRevoked` flag exists).
+
+For external apps:
+```bash
+uip admin external-apps list --output json
+```
+
+### Step 2 — Verify scopes
+
+PATs and external apps are scoped — if the API call requires `OR.Execution` but the token only has `OR.Folders.Read`, the call fails.
+
+For external apps, check the declared scopes against the API endpoint's requirement. For PATs, re-create with the correct `--scope`.
+
+### Step 3 — Check audit for revocation
+
+Query org audit for recent identity events — a PAT or app secret may have been revoked:
+
+```bash
+uip admin audit org sources --output json
+# Find Identity source → PersonalAccessTokens or ExternalApps target
+uip admin audit org events \
+  --source <IDENTITY_SOURCE_GUID> \
+  --from-date <RECENT_WINDOW> \
+  --to-date <NOW> \
+  --limit 50 \
+  --output json
+```
+
+---
+
+## Cross-reference
+
+- Audit event investigation workflows → [audit-workflow-guide.md](audit-workflow-guide.md)
+- Role management (create/update custom roles) → [authorization/role-management.md](authorization/role-management.md)
+- Role assignment scope validation → [authorization/role-assignment-management.md](authorization/role-assignment-management.md)
+- Permission catalog lookup → [authorization/permission-catalog.md](authorization/permission-catalog.md)
+- IP restriction management → [ip-restriction/ip-restriction-commands.md](ip-restriction/ip-restriction-commands.md)

package/skills/uipath-agents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uipath-agents
-description: "End-to-end work with UiPath Agents of all types: build, integrate with UiPath Products (e.g., Orchestrator, Flow, Maestro), design with UiPath Tools (e.g., Agent Builder/Studio Web), and deploy. Covers Coded Agents (e.g., LangGraph, LlamaIndex, OpenAI Agents) and Low-Code Agents (`agent.json` / Agent Builder). Excludes coded functions / Functions SDK (separate skill)."
+description: "End-to-end work with UiPath Agents of all types: build, integrate with UiPath Products (e.g., Orchestrator, Flow, Maestro), design with UiPath Tools (e.g., Agent Builder/Studio Web), deploy, and configure/validate. Covers Coded Agents (e.g., LangGraph, LlamaIndex, OpenAI Agents) and Low-Code Agents (`agent.json` / Agent Builder). Excludes coded functions / Functions SDK (separate skill)."
 when_to_use: "Must use when user mentions or implies any Agent lifecycle phase - e.g., auth, design, scaffold, Studio Web sync, flow integration, editing, pack/deploy/version bump, eval, debug, tracing, guardrails, memory spaces, bindings, attachments. Example requests: 'create/build a UiPath agent', 'build a low-code / Agent Builder agent', 'add agent memory spaces', 'build a coded / Python agent (LangGraph / LlamaIndex / OpenAI Agents)', 'scaffold an agent project', 'run / debug / evaluate / deploy my agent'."
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion, WebFetch
 user-invocable: true
@@ -13,6 +13,7 @@ user-invocable: true
 - Treat "build/create/scaffold/implement a UiPath agent" as the full One-Prompt Flow by default. Do not stop after file creation or local run unless the user explicitly says to stop there.
 - A normal completion point is after smoke eval and the mandatory Delivery fork question. A final build summary before that is premature unless run/eval is blocked or the user opted out.
 - **Probe the `solution` verb once per session before the first scaffold or deploy.** Run `uip solution init --help --output json`. Result `Success` → use `solution init` and `solution deploy run --parent-folder-path` / `--parent-folder-key` (post-rename, default). `unknown command` / non-zero exit → CLI predates the rename; substitute `uip solution new <Name>` and `--folder-path` / `--folder-key` (same arguments otherwise) wherever this skill calls those.
+- **Greenfield coded agents — scaffold with `uip codedagent new`, never hand-author the project.** Building a NEW coded agent from scratch: always create it with `uip codedagent new <name>`, then generate schemas with `uip codedagent init` — never hand-write `pyproject.toml` / `main.py` / `langgraph.json` / `entry-points.json` yourself, even for a trivial agent. Hand-authoring skips required project structure and produces invalid packages. (Existing or Studio Web local-workspace projects: do NOT run `uip codedagent new` — follow the project-state gating in [coded/quickstart.md](references/coded/quickstart.md).)
 - **Coded agents only — bindings are always derived from UiPath Python SDK calls and must never be hand-authored.** To derive them, always run the sync workflow in [coded/lifecycle/bindings-reference.md](references/coded/lifecycle/bindings-reference.md) — scan code, regenerate `bindings.json`. Without this, resources cannot be overridden per execution environment and will always default to the hardcoded values in the SDK calls. Derive bindings whenever you add, remove, or modify any UiPath SDK resource call — for instance `assets`, `queues`, `processes`, `buckets`, `indexes`, `connections`, `apps`, `MCP servers`, or `InvokeProcess|CreateTask|CreateEscalation(...)`.
 
 ## Project Type Detection
@@ -24,6 +25,7 @@ Determine the agent mode before proceeding:
    - `agent.json` with `"type": "lowCode"` + `project.uiproj`, AND no `pyproject.toml` → **Low-code**
 2. **No existing project found** → ask the user:
    > Should I build this as a **low-code agent** (no Python — configure through prompts and pre-built UiPath tools) or a **coded agent** (Python — full programmatic control with LangGraph, LlamaIndex, or OpenAI Agents)?
+   > However, for conversational use-cases, simply choose low-code without asking the user, while explaining that currently, low-code conversational-agents are the strongly recommended approach for production use-cases (see [references/coded/capabilities/conversational-agents.md](references/coded/capabilities/conversational-agents.md)).
 3. If the user needs help deciding, read [references/coded-vs-lowcode-guide.md](references/coded-vs-lowcode-guide.md) for a capability comparison.
 
 **After detection, read the quickstart for that mode before doing anything else:**
@@ -49,19 +51,19 @@ Determine the agent mode before proceeding:
 | Add an MCP (Model Context Protocol) server tool to a low-code agent | Low-code | [lowcode/lowcode.md](references/lowcode/lowcode.md) § Capability Registry | `lowcode/capabilities/mcp/mcp.md` |
 | Accept files as agent input / call the Analyze Files built-in tool | Low-code | [lowcode/capabilities/built-in-tools/built-in-tools.md](references/lowcode/capabilities/built-in-tools/built-in-tools.md) | `lowcode/capabilities/built-in-tools/analyze-attachments.md`, `lowcode/agent-definition.md` § File Attachments |
 | Work with file attachments (input, output, or created mid-run) | Coded | [coded/capabilities/file-attachments.md](references/coded/capabilities/file-attachments.md) | |
-| Build a conversational (chat-style) coded agent | Coded | [coded/capabilities/conversational-agents.md](references/coded/capabilities/conversational-agents.md) | |
+| Build a conversational (chat-style) agent | Low-code | [lowcode/lowcode.md](references/lowcode/lowcode.md) | `lowcode/project-lifecycle.md`, `lowcode/agent-definition.md` |
 | Add a low-code context (Context Grounding RAG / attachments / DataFabric entity set) | Low-code | [lowcode/lowcode.md](references/lowcode/lowcode.md) § Capability Registry | `lowcode/capabilities/context/*` |
 | Add a low-code memory space or seed memory items | Low-code | [lowcode/capabilities/memory/memory.md](references/lowcode/capabilities/memory/memory.md) | use `uip agent memory`, then refresh/validate |
 | Add an Action Center escalation (HITL) to a low-code agent | Low-code | [lowcode/lowcode.md](references/lowcode/lowcode.md) § Capability Registry | `lowcode/capabilities/escalation/escalation.md` |
 | Add guardrails (PII, harmful content, custom rules) to a low-code agent | Low-code | [lowcode/lowcode.md](references/lowcode/lowcode.md) § Capability Registry | `lowcode/capabilities/guardrails/guardrails.md` |
-| Add guardrails to a coded agent | Coded | [coded/capabilities/guardrails/guardrails.md](references/coded/capabilities/guardrails/guardrails.md) | fetch official docs via WebFetch, ask middleware vs decorator, read agent code, write Python |
+| Add a new guardrail to a coded agent | Coded | [coded/capabilities/guardrails/guardrails.md](references/coded/capabilities/guardrails/guardrails.md) | fetch official docs via WebFetch, ask middleware vs decorator, read agent code, write Python |
 | Add escalation guardrail (escalate action / Action Center app) | Low-code | [lowcode/capabilities/guardrails/guardrails.md](references/lowcode/capabilities/guardrails/guardrails.md) § escalate — Hand Off to Action Center | Run `uip solution resources list --kind App --source remote --output json` to confirm app exists |
 | Recommend guardrails for a low-code agent based on its context | Low-code | [lowcode/capabilities/guardrails/guardrails-recommend.md](references/lowcode/capabilities/guardrails/guardrails-recommend.md) | fetch catalog + list, analyze agent context, apply + validate |
 | Recommend guardrails for a specific scope or tool | Low-code | [lowcode/capabilities/guardrails/guardrails-recommend.md](references/lowcode/capabilities/guardrails/guardrails-recommend.md) § Scoped or Tool-Specific Filtering | filter candidates by scope or tool name after catalog analysis |
 | Validate whether existing guardrails are correctly configured | Low-code | [lowcode/capabilities/guardrails/guardrails-recommend.md](references/lowcode/capabilities/guardrails/guardrails-recommend.md) § Validate Mode | check correctness, actionability, and relevance per guardrail |
 | Recommend guardrails for a coded agent based on its context | Coded | [coded/capabilities/guardrails/guardrails-recommend.md](references/coded/capabilities/guardrails/guardrails-recommend.md) | fetch catalog + list + SDK docs, analyze agent code, apply + verify |
 | Recommend guardrails for a specific scope or tool (coded) | Coded | [coded/capabilities/guardrails/guardrails-recommend.md](references/coded/capabilities/guardrails/guardrails-recommend.md) § Scope and Tool Filtering | filter candidates by `@tool` function or scope after catalog analysis |
-| Validate whether existing coded guardrails are correctly configured | Coded | [coded/capabilities/guardrails/guardrails-recommend.md](references/coded/capabilities/guardrails/guardrails-recommend.md) § Validate Mode | check correctness, actionability, and relevance per guardrail |
+| Check, validate, diagnose, or fix whether an existing coded guardrail is correctly configured (placement / scope) | Coded | [coded/capabilities/guardrails/guardrails-recommend.md](references/coded/capabilities/guardrails/guardrails-recommend.md) § Validate Mode | **fetch catalog + list + SDK docs first**, then check correctness, actionability, and relevance — fix in place |
 | Embed a low-code agent inline in a flow, or wire a multi-agent solution | Low-code | [lowcode/lowcode.md](references/lowcode/lowcode.md) § Capability Registry | `lowcode/capabilities/inline-in-flow/inline-in-flow.md`, `lowcode/capabilities/process/solution-agent.md` |
 | Run low-code evaluations | Low-code | [lowcode/evaluations/evaluate.md](references/lowcode/evaluations/evaluate.md) | `lowcode/evaluations/evaluators.md`, `lowcode/evaluations/evaluation-sets.md`, `lowcode/evaluations/running-evaluations.md` |
 | Run offline evals for a published Orchestrator package | Low-code | [lowcode/evaluations/orchestrator-eval-run.md](references/lowcode/evaluations/orchestrator-eval-run.md) | Use `uip or eval run-offline-evals` (requires package published to Orchestrator) |
@@ -74,6 +76,7 @@ Determine the agent mode before proceeding:
 | Summarize / research / synthesize over PDF or TXT (DeepRAG, low-code) | Low-code | [context-grounding-patterns.md](references/context-grounding-patterns.md) | [lowcode/capabilities/built-in-tools/deeprag/planning.md](references/lowcode/capabilities/built-in-tools/deeprag/planning.md) |
 | Process CSV rows with LLM per row (BatchTransform, coded) | Coded | [context-grounding-patterns.md](references/context-grounding-patterns.md) | [coded/capabilities/batch-transform/planning.md](references/coded/capabilities/batch-transform/planning.md) |
 | Process CSV rows with LLM per row (BatchTransform, low-code) | Low-code | [context-grounding-patterns.md](references/context-grounding-patterns.md) | [lowcode/capabilities/built-in-tools/batch-transform/planning.md](references/lowcode/capabilities/built-in-tools/batch-transform/planning.md) |
+| Manage context-grounding indexes from the CLI (list / create / ingest / search) | Platform | [`uipath-platform/references/context-grounding/index-management.md`](../uipath-platform/references/context-grounding/index-management.md) | `uip context-grounding` — cross-cutting CLI, owned by `uipath-platform` |
 
 ## Resources
 

package/skills/uipath-agents/references/coded/capabilities/context-grounding.md

@@ -17,6 +17,8 @@ Before using context grounding, you must first create an index in your Orchestra
 
 Once indexed, you can reference the index by name in your agent code.
 
+To create, ingest, poll, search, or delete the index from the CLI instead of the Orchestrator UI, see [uipath-platform/references/context-grounding/index-management.md](../../../../uipath-platform/references/context-grounding/index-management.md).
+
 ## Folder Targeting
 
 Context Grounding indexes live in Orchestrator folders. Pass a folder identifier whenever the index is not in the default folder resolved from your auth context — otherwise the service may return `400 FolderKey required`. `ContextGroundingRetriever` accepts `folder_path` or `folder_key`; `ContextGroundingVectorStore` accepts `folder_path`.

package/skills/uipath-agents/references/coded/capabilities/conversational-agents.md

@@ -1,5 +1,7 @@
 # Conversational Agents
 
+> **Coded conversational agents are currently not intended for production use-cases.** For conversational use-cases, use **low-code conversational agents** by referring to [../../lowcode/lowcode.md](../../lowcode/lowcode.md). Only use coded conversational agents if the user is strongly requesting to use coded agents and the agent will only be tested and ran on a local machine.
+
 Chat-style coded agents where the UiPath runtime feeds **one message per turn** and threads history across turns.
 
 Supported on **LangGraph** and **LlamaIndex**. Coded Function and OpenAI Agents are not conversational.

package/skills/uipath-agents/references/coded/capabilities/guardrails/guardrails-recommend.md

@@ -160,12 +160,14 @@ Always confirm the chosen scope is in the validator's `allowed_scopes` from the
 
 ### Step 6 — Choose the Action
 
-The action (`BlockAction` vs `LogAction`) is **not** a free choice — default to the `action_type` in the catalog entry's representative `examples[].config`. For security-critical guardrails (`adversarial_input` — prompt injection / user prompt attacks; `content_safety` — harmful content / IP) the catalog examples use **Block**, because a logged-but-allowed violation provides no actual protection.
+The action (`BlockAction` vs `LogAction` vs `EscalateAction`) is **not** a free choice — default to the `action_type` in the catalog entry's representative `examples[].config`. For security-critical guardrails (`adversarial_input` — prompt injection / user prompt attacks; `content_safety` — harmful content / IP) the catalog examples use **Block**, because a logged-but-allowed violation provides no actual protection.
+
+**`EscalateAction` (human-in-the-loop)** is a third option — recommend it when the user wants a **human to review/approve** a flagged item rather than hard-block it (high-stakes or sensitive content where a person should approve or edit before the run proceeds). It **suspends** the run for review and resumes on Approve (terminates on Reject). **Prerequisite:** the fetched SDK docs expose `EscalateAction`, and a deployed Action App is declared in `bindings.json` via the coded-agent bindings sync workflow — see [guardrails.md § Escalation action (HITL)](guardrails.md#escalation-action-human-in-the-loop). If the user asks for escalation but the SDK docs or Action App are unavailable, say so and fall back to Block/Log rather than authoring a guardrail that fails at runtime.
 
 Rules:
 
 1. **Default to the catalog example's `action_type`.** If it is `Block`, generate `BlockAction(...)`. Do not substitute `LogAction` for a security-critical guardrail on your own initiative.
-2. **Never silently downgrade Block → Log.** A guardrail set to log-only when the user expected blocking is the dangerous failure mode — the agent looks protected but isn't. If you use `LogAction` for any guardrail whose catalog default is `Block`, you **must** state it explicitly in the report and give the reason.
+2. **Never silently downgrade Block → Log** (or a requested escalation → Log/Block). A guardrail set to log-only when the user expected blocking is the dangerous failure mode — the agent looks protected but isn't. If you use `LogAction` for any guardrail whose catalog default is `Block`, you **must** state it explicitly in the report and give the reason. If the user asked for **human review** (escalation) but you author Block/Log instead (e.g. no Action App available), say so explicitly — don't quietly drop the human-in-the-loop step.
 3. **Legitimate reasons to use Log instead of Block** (state which applies):
    - The user explicitly asked for observe-only / audit / "log first, block later" rollout.
    - A high false-positive risk where blocking would break normal operation (e.g. PII `PERSON` entity flagging ordinary words) — log so the user can tune thresholds before enforcing.
@@ -188,7 +190,7 @@ Map catalog parameter shapes to Python:
 | `map-enum` (e.g. `entityThresholds`) | Dict from enum member → number (e.g. `{PIIDetectionEntityType.EMAIL: 0.5}`) — keys must exactly match the `enum-list` parameter's values |
 | `number` (e.g. `threshold`) | Plain `float` / `int` constructor argument |
 
-Use `BlockAction(...)`, `LogAction(severity_level=...)`, or other actions exposed by the SDK docs. Never invent action class names.
+Use `BlockAction(...)`, `LogAction(severity_level=...)`, or `EscalateAction(app_name=..., app_folder_path=..., recipient=...)` for human-in-the-loop review — or any other action the SDK docs expose. Never invent action class names. For `EscalateAction`, the fetched SDK docs must expose the class/parameters, and the Action App must be deployed and declared in `bindings.json` using [../../lifecycle/bindings-reference.md](../../lifecycle/bindings-reference.md) (see [guardrails.md § Escalation action (HITL)](guardrails.md#escalation-action-human-in-the-loop)).
 
 > Read [guardrails.md](guardrails.md) before writing any Python. The middleware spread, decorator stacking, and factory refactor rules cannot be safely inferred.
 
@@ -240,7 +242,7 @@ From the SDK docs and the catalog, look up the validator class referenced in the
 2. Confirm the in-code scope is permitted:
    - Middleware — every `GuardrailScope` in the `scopes=[...]` argument is in `allowed_scopes`.
    - Decorator — the function the `@guardrail` decorates matches the implied scope: `@tool` for Tool scope, LLM factory for LLM scope, agent factory for Agent scope.
-3. Confirm the stage is permitted: `GuardrailExecutionStage.PRE` only where catalog allows pre-execution; `POST` only where catalog allows post-execution.
+3. Confirm the stage is permitted. **Middleware takes no `stage=` argument** — the validator fixes its stage (e.g. `intellectual_property` POST, `user_prompt_attacks` PRE), so do not flag a missing stage. The stage check applies only to the **decorator** `stage=`: `GuardrailExecutionStage.PRE` only where catalog allows pre-execution; `POST` only where catalog allows post-execution.
 4. For Tool-scoped middleware: `tools=[...]` must contain the actual `@tool` Python objects discovered in Step 1 — not strings, not undefined names.
 5. For decorator-style LLM/Agent scope: the decorated function must actually return a `UiPathChat(...)` / `create_agent(...)` — decorating an unrelated function silently no-ops.
 
@@ -282,3 +284,4 @@ python3 -c "import ast; ast.parse(open('graph.py').read())"
 12. **The cache file is `.guardrails-catalog-cache.json`** in the working directory. Add it to `.gitignore` if one exists.
 13. **Class names and enum names come from the SDK docs** — never invent them. The SDK evolves; relying on memory produces stale code. For **import paths**, use the `langchain/guardrails/` page when the agent is LangChain (paths live in `uipath_langchain.guardrails`); for every other framework use the `core/guardrails/` page (paths live in `uipath.platform.guardrails`). See Rule 8.
 14. **Read [guardrails.md](guardrails.md) before writing any Python** — the middleware spread (`*`), decorator placement above `@tool` / factory, factory refactor, and import-source rules are specified there and cannot be safely inferred.
+15. **`EscalateAction` is the human-in-the-loop option only when the SDK docs expose it** — recommend it when the user wants a person to review/approve a flagged item rather than hard-block it. It requires a **deployed Action App** declared in `bindings.json` (`app_name` / `app_folder_path`) through the coded-agent bindings sync workflow; if the docs, app, or binding prerequisite is unavailable, fall back to Block/Log and say so — never silently drop the requested escalation. See Step 6 and [guardrails.md § Escalation action (HITL)](guardrails.md#escalation-action-human-in-the-loop).