@uipath/skills 1.197.0-preview.0 → 1.197.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "uipath",
       "source": "./",
       "description": "UiPath plugin for Claude Code — custom skills, agents, hooks, and MCP servers for UiPath workflows, UI automation, UI testing and UiPath troubleshoot",
-      "version": "1.197.0",
+      "version": "1.197.1",
       "author": {
         "name": "UiPath"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "uipath",
-  "version": "1.197.0",
+  "version": "1.197.1",
   "description": "UiPath plugin for Claude Code — custom skills, agents, hooks, and MCP servers for UiPath RPA workflows, UI automation, UI testing, Python coded agents and UiPath troubleshoot",
   "author": {
     "name": "UiPath"
@@ -30,5 +30,8 @@
     "openai-agents",
     "troubleshoot"
   ],
-  "skills": "./skills/"
+  "skills": "./skills/",
+  "agents": [
+    "./skills/uipath-rpa/agents/uipath-project-discovery-agent.md"
+  ]
 }

package/CODEOWNERS

@@ -8,9 +8,6 @@
 # Hooks
 /hooks/ @DragosUnguru @RaduAna-Maria
 
-# Plugin agents
-/agents/ @RaduAna-Maria
-
 # Plugin-namespaced slash commands (e.g., /uipath:install-permissions)
 /commands/ @DragosUnguru @tmatup
 
@@ -66,6 +63,11 @@
 /tests/tasks/uipath-agents/lowcode/guardrails/ @apetraru-uipath @valentinabojan @ctiliescuuipath
 /tests/tasks/uipath-agents/coded/guardrails/ @apetraru-uipath @valentinabojan @ctiliescuuipath
 
+# Functions skill (Python Coded Functions — Phase 1; JS HTTP/background Phase 2/3)
+/skills/uipath-functions/ @AlexBizon @UiPath/team-coded-agents
+/tests/tasks/uipath-functions/ @AlexBizon @UiPath/team-coded-agents
+/tests/tasks/activation/uipath-functions.jsonl @AlexBizon @UiPath/team-coded-agents
+
 # Planner skill (PDD → SDD design + multi-skill task planning)
 /skills/uipath-planner/ @RaduAna-Maria
 /tests/tasks/uipath-planner/ @RaduAna-Maria

package/README.md

@@ -95,6 +95,7 @@ Every skill's maturity is tracked in [`assets/skill-status.json`](assets/skill-s
 | `uipath-coded-apps` | Preview |
 | `uipath-connector-builder` | In-development |
 | `uipath-feedback` | Stable |
+| `uipath-functions` | Preview |
 | `uipath-governance` | In-development |
 | `uipath-human-in-the-loop` | In-development |
 | `uipath-ixp` | In-development |

package/assets/skill-status.json

@@ -73,6 +73,11 @@
       },
       "last_synced": null
     },
+    "uipath-functions": {
+      "status": "preview",
+      "confluence": { "page_id": null, "url": null },
+      "last_synced": null
+    },
     "uipath-governance": {
       "status": "in-development",
       "confluence": {

package/hooks/send-telemetry.sh

@@ -11,8 +11,8 @@
 # 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 opt-in; value sanitization stays the hook's responsibility because
-# the CLI and skills ship co-versioned.
+# 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
@@ -23,9 +23,20 @@
 #   ENVELOPE (top-level)  -> toolName, toolUseId, sessionId, permissionMode,
 #                            durationMs, effortLevel (effort.level), agentType
 #   tool_input            -> skillName, uipSubcommand (command), fileExtension
-#                            (file_path), subagentType
+#                            (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
@@ -37,9 +48,9 @@
 # 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.
-#                               Send ONLY when explicitly set to "0". Unset
-#                               (default) or "1" -> do not send. Privacy-first
-#                               default-off; absent is treated as disabled.
+#                               Opt-out: send by DEFAULT. Skip ONLY when set to
+#                               "1". Unset (default) or "0" -> send. Absent is
+#                               treated as enabled.
 
 set +e
 
@@ -64,13 +75,22 @@ extract_fields() {
                 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")
+        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)
@@ -88,7 +108,7 @@ extract_fields() {
           if (c == "\"") {
             instr = 0
             if (isval) {
-              if (buffering) print pkey "\t" cur
+              if (buffering) print outkey(pkey, pdepth, ctx) "\t" cur
               pend = 0; isval = 0
             } else {
               laststr = cur
@@ -137,7 +157,7 @@ extract_fields() {
             if (c==","||c=="}"||c=="]"||c==" "||c=="\t"||c=="\n"||c=="\r") break
             lit = lit c; i++
           }
-          if (interesting(pkey, pdepth, ctx)) print pkey "\t" lit
+          if (interesting(pkey, pdepth, ctx)) print outkey(pkey, pdepth, ctx) "\t" lit
           pend = 0; continue                      # leave delimiter for the main loop
         }
         i++
@@ -190,12 +210,15 @@ is_uipath_call() {
     Skill)
       case "$skill" in uipath:*|uipath-*) return 0 ;; esac
       ;;
-    Agent)
-      # UiPath agents or Claude's built-in agent types only — NOT custom agents
-      # from other plugins (`<plugin>:<name>`) or user-defined ones.
+    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) return 0 ;;
+        general-purpose|Explore|Plan|claude|claude-code-guide|statusline-setup|fork|default) return 0 ;;
       esac
       ;;
     Bash|PowerShell)
@@ -366,9 +389,10 @@ EOF
 
 # --- main ------------------------------------------------------------------
 main() {
-  # Send only when telemetry is explicitly NOT disabled (=0). `uip track`
-  # enforces the same gate on its side; we short-circuit here too.
-  [ "${UIPATH_TELEMETRY_DISABLED:-1}" = "0" ] || exit 0
+  # 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)"
@@ -411,8 +435,8 @@ main() {
   # `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 opt-in and never-fail (exits 0, emits nothing when
-  # telemetry is off); piping to it is harmless even if the CLI is absent.
+  # 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/skills",
-  "version": "1.197.0-preview.0",
+  "version": "1.197.1",
   "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-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), 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)."
+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). For deterministic Python Coded Functions (`uip functions`, `uipath.json` functions map, no agent runtime/LLM)→uipath-functions."
 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
@@ -20,13 +20,14 @@ user-invocable: true
 
 Determine the agent mode before proceeding:
 
-1. **Check for existing project files** in the working directory:
-   - `pyproject.toml` with `uipath` dependency + `.py` files → **Coded**
+1. **First — confirm this is an agent, not a Coded Function.** If `uipath.json` declares a `functions` map (e.g. `"functions": {"main": "main.py:main"}`), the project is a **Python Coded Function**, not an agent. Stop here and use the [`uipath-functions`](/uipath:uipath-functions) skill instead. Functions are deterministic, do not reason via LLM, and have a distinct lifecycle (`uip functions new/init/pack/publish/run`).
+2. **Check for existing agent project files** in the working directory:
+   - `pyproject.toml` + `.py` files + a framework dep (`uipath-langchain`, `uipath-llamaindex`, or `uipath-openai-agents`) → **Coded**. The framework package already declares `uipath` as a dependency, so an explicit `uipath` entry is not required.
    - `agent.json` with `"type": "lowCode"` + `project.uiproj`, AND no `pyproject.toml` → **Low-code**
-2. **No existing project found** → ask the user:
+3. **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.
+4. 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:**
 
@@ -63,7 +64,7 @@ Determine the agent mode before proceeding:
 | 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 |
-| 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 |
+| 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 SDK docs first (authoritative for scope/placement)**; also fetch catalog + list for relevance/entitlement — 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) |

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

@@ -12,6 +12,8 @@ Both workflows are driven by live data — the catalog (`uip agent guardrails ca
 
 ## Step 0 — Fetch Catalog, Available Validators, and SDK Docs (MANDATORY — do this before any analysis)
 
+> Full three-fetch mandate applies to **Recommend mode**. In **Validate mode** of an existing guardrail the SDK docs are the authoritative, sufficient source for a validator's scope/stage — `catalog` (relevance metadata) and `list` (tenant entitlement) are recommended cross-checks, not a hard prerequisite for a scope/placement fix. See [Validate Mode](#validate-mode).
+
 ### Catalog (cacheable — 30-minute TTL)
 
 The catalog is the same for all tenants (authored metadata, rarely changes). Cache it locally for 30 minutes to avoid redundant calls.
@@ -219,7 +221,7 @@ Report to the user:
 
 Use when the agent already has guardrails and the user asks whether they are correctly configured or appropriate.
 
-**Before any validation, run all three Step 0 fetches** (catalog with cache, guardrails list without cache, SDK docs via WebFetch). The SDK docs are the authoritative source for which Python class corresponds to which `validator_id` and which scopes/stages each class supports.
+**Fetch the SDK docs first (WebFetch) — they are the authoritative source** for which Python class corresponds to which `validator_id` and which scopes/stages each class supports; a scope/placement diagnosis is grounded there. Also run the `catalog` and `list` fetches to support the Relevance (`when_not_to_use`) and entitlement checks below — recommended, but not a hard prerequisite once the SDK docs settle the scope question.
 
 For each existing guardrail discovered in the Python file (Step 1 from Recommend Mode):
 
@@ -238,7 +240,7 @@ From the SDK docs and the catalog, look up the validator class referenced in the
 
 ### Actionability Check
 
-1. From the catalog entry, read `allowed_scopes` and the per-scope allowed stages.
+1. Read the validator's allowed scopes and per-scope stages from the **SDK docs** (authoritative for coded); cross-check against the `catalog` entry's `allowed_scopes` when it was fetched.
 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.
@@ -270,7 +272,7 @@ python3 -c "import ast; ast.parse(open('graph.py').read())"
 
 ## Critical Rules
 
-1. **Always fetch catalog first** (use cache if fresh); **always fetch guardrails list second** (no cache); **always fetch the two SDK doc pages via WebFetch third** (no cache). All three are required before any analysis or code edit.
+1. **Recommend mode / net-new adds:** fetch catalog first (use cache if fresh), guardrails list second (no cache), and the two SDK doc pages via WebFetch third (no cache) — all three required before any analysis or code edit. **Validate mode of an existing guardrail:** the SDK docs are the authoritative, sufficient grounding for a scope/placement fix; still fetch catalog + list for the Relevance and entitlement checks, but they are not a hard prerequisite.
 2. **If `GuardrailCatalogUnavailable`** → surface the message and stop. Do not fall back to guessing or hardcoded recommendations.
 3. **Only recommend `Available` validators**. Mention `Unauthorised` ones to the user so they can contact their administrator.
 4. **Every recommendation must cite** the catalog entry's `when_to_use` or a specific `use_cases` item that matched the agent's context. Do not recommend a guardrail without explaining why it applies.

package/skills/uipath-agents/references/coded/lifecycle/build.md

@@ -45,6 +45,7 @@ Load capability references **only if the task requires them** — do not preload
 
 ## Additional Instructions
 
+- **File/document input → `Attachment`, never a filesystem path string.** If the prompt says the agent "takes a CSV/PDF/file as input" (or similar), read `../capabilities/file-attachments.md` before defining the `Input` model. A `str` path field runs locally with `uip codedagent run` but breaks on Studio Web/Orchestrator, where no such path exists in the container.
 - **Select a framework before writing any code.** Infer from the prompt if possible (tools/orchestration → LangGraph, RAG → LlamaIndex, simple LLM → OpenAI Agents, no LLM → Coded Function). If ambiguous, ask the user to choose.
 - **Structured input contract → not OpenAI Agents.** OpenAI Agents always require a `messages` input field and cannot express an input contract without it (see `../frameworks/openai-agents-integration.md` § Input). When the user needs a strict typed/structured input (e.g. a single named field, no `messages`), choose LangGraph (custom `StateGraph` with arbitrary input state) instead. Do NOT silently fall back to a Coded Function to satisfy the input shape — a Coded Function produces `ProjectType: Function`, not a coded agent, so it does not fulfill a request for an agent.
 - **Read ONLY the single framework reference** for the selected framework before writing code. Do NOT read other framework references or capability references unless the task explicitly requires that capability.

package/skills/uipath-agents/references/coded/lifecycle/setup.md

@@ -94,7 +94,7 @@ Edit the scaffolded `main.py`'s `Input` / `Output` models and `async def main` t
 ```
 
 **Key fields:**
-- **`runtimeOptions.isConversational`** - Set `true` for conversational/chat agents
+- **`runtimeOptions.isConversational`** - scaffold defaults to `false` (single-shot). Building a chat/conversational agent? Flip to `true` BEFORE `uip codedagent init` so `entry-points.json` gets the chat shape. See [conversational-agents](../capabilities/conversational-agents.md).
 - **`packOptions`** - Control which files are included when packaging for deployment
 - **`functions`** - Entrypoint mappings (format: `"file_path:function_name"`)
 

package/skills/uipath-agents/references/coded/quickstart.md

@@ -313,14 +313,15 @@ Execute the following in order, end-to-end, in one pass — do not pause for con
 
 ## Framework Selection
 
-Infer the framework from the user's prompt when possible. If ambiguous, ask them to choose:
+> **First — is this an agent at all?** If the task is deterministic logic with no LLM reasoning (validate data, call an API with custom auth, transform records, upload/download files), it's a **Python Coded Function** — not an agent. Use the [`uipath-functions`](/uipath:uipath-functions) skill instead of this one. Coded Functions use typed I/O (`@dataclass`, Pydantic `BaseModel`, or a thin Python class with typed annotations) and a `functions` map in `uipath.json`; what distinguishes an agent is LLM reasoning and a framework graph.
 
-1. **Coded Function** — Plain Python with `Input`/`Output` models. No LLM. Best for deterministic logic.
-2. **LangGraph** — StateGraph with conditional routing, tool use, interrupts. Best for complex LLM agents.
-3. **LlamaIndex** — Workflow with events and RAG support. Best for knowledge retrieval.
-4. **OpenAI Agents** — Lightweight agent with tools and handoffs. Best for simple LLM agents; lacks HITL, process invocation, and state persistence.
+If the task needs LLM reasoning, infer the framework from the user's prompt when possible. If ambiguous, ask them to choose:
 
-**Inference hints:** mentions of tools/tool calling, multi-step, or orchestration → LangGraph. RAG or knowledge retrieval → LlamaIndex. Simple handoffs or lightweight LLM → OpenAI Agents. No LLM needed → Coded Function. Summarize / research / synthesize over PDF or TXT (incl. bucket files, attachments) → not a framework choice — see [capabilities/deeprag/planning.md](capabilities/deeprag/planning.md). Per-row CSV extraction → see [capabilities/batch-transform/planning.md](capabilities/batch-transform/planning.md). When in doubt, ask.
+1. **LangGraph** (recommended — best integrated with the UiPath ecosystem) — StateGraph with conditional routing, tool use, interrupts. Best for complex LLM agents.
+2. **LlamaIndex** — Workflow with events and RAG support. Most complete LangGraph alternative.
+3. **OpenAI Agents** — Lightweight agent with tools and handoffs. Best for simple LLM agents; lacks HITL, process invocation, and state persistence.
+
+**Inference hints:** mentions of tools/tool calling, multi-step, or orchestration → LangGraph. Simple handoffs or lightweight LLM → OpenAI Agents. No LLM needed → not an agent — use [`uipath-functions`](/uipath:uipath-functions). Summarize / research / synthesize over PDF or TXT (incl. bucket files, attachments) → not a framework choice — see [capabilities/deeprag/planning.md](capabilities/deeprag/planning.md). Per-row CSV extraction → see [capabilities/batch-transform/planning.md](capabilities/batch-transform/planning.md). When in doubt, ask.
 
 **Always tell the user which framework you selected and why** before proceeding to build. Example: "I'll use **LangGraph** for this agent since it involves tool calling and multi-step orchestration."
 

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

@@ -119,6 +119,8 @@ When a validator supports **more than one scope** (e.g. `pii_detection` allows A
 
 Concretely: **PII detection meant to stop the agent handling personal data goes at `selector.scopes: ["Agent"]`, not `["Llm"]`** — both are listed in `AllowedScopes` for `pii_detection`, but Agent · PRE blocks the run earlier (before the LLM call) and covers the whole agent, not just one model invocation. Only drop to a narrower scope when the validator does not support the broader one (`prompt_injection` and `user_prompt_attacks` are Llm-only, so Llm · PRE is the earliest available for them) or when the user explicitly asks for a narrower scope.
 
+> **Conversational agents: this entire table is autonomous-only.** Built-in validators (any `$guardrailType: "builtInValidator"` — the validators returned by `uip agent guardrails list`) are **not usable on conversational agents** (`agent.json` → `metadata.isConversational: true` / `settings.engine: "conversational-v1"`). Do NOT recommend or author any `builtInValidator` for a conversational agent. The only guardrails that run are `$guardrailType: "custom"` deterministic rules (word/number/boolean/always) scoped to a `Tool`. If the user asks for built-in-style detection (PII, harmful content, injection) on a conversational agent, explain it is autonomous-only and offer a Custom deterministic Tool guardrail or an autonomous agent. Detect `isConversational` before applying the preference table. See [../../critical-rules/conversational-critical-rules.md](../../critical-rules/conversational-critical-rules.md) Critical Rule 1.
+
 Always confirm the chosen scope is in the validator's `AllowedScopes` from the guardrails list — never assume a scope the catalog/SDK does not permit.
 
 ### Step 5 — Choose the Action
@@ -218,7 +220,7 @@ If the user asks to fix identified issues: apply corrections to `agent.json`, ru
 4. **Every recommendation must cite** the catalog entry's `when_to_use` or a specific `use_cases` item that matched the agent's context. Do not recommend a guardrail without explaining why it applies.
 5. **Never recommend two validators with the same `security_category` at the same scope and stage** (e.g. `prompt_injection` + `user_prompt_attacks` at Llm PRE). De-duplicate per Step 3: drop catalog-deprecated entries, keep the best fit, mention the alternative. Derive the grouping and deprecation from the catalog's own fields — do not hardcode validator names.
 6. **Default the action to the catalog example's `action_type`; never silently downgrade `block` → `log`.** Security-critical guardrails (`adversarial_input`, `content_safety`) default to `{"$actionType": "block"}`. If you use `{"$actionType": "log"}` for a guardrail whose catalog default is `block`, state it and the reason in the report (Step 5).
-7. **Block as early as possible — pick the outermost scope the validator allows.** For input protection (PII, jailbreak, injection) prefer `selector.scopes: ["Agent"]` over `["Llm"]` over `["Tool"]`, so the run halts before the LLM call. PII meant to stop the agent handling personal data goes at **Agent**, not Llm. Only narrow when the validator is scope-restricted (e.g. `prompt_injection` / `user_prompt_attacks` are Llm-only) or the user asks for a narrower scope. See Step 4.
+7. **Block as early as possible — pick the outermost scope the validator allows.** For input protection (PII, jailbreak, injection) prefer `selector.scopes: ["Agent"]` over `["Llm"]` over `["Tool"]`, so the run halts before the LLM call. PII meant to stop the agent handling personal data goes at **Agent**, not Llm. Only narrow when the validator is scope-restricted (e.g. `prompt_injection` / `user_prompt_attacks` are Llm-only) or the user asks for a narrower scope. See Step 4. **Exception — conversational agents: built-in validators are NOT usable at all** (Critical Rule 1); this whole preference is autonomous-only. Detect `isConversational` first — if true, do not author any `builtInValidator`; conversational agents run only Custom deterministic `Tool` guardrails.
 8. **For Tool scope**: verify the tool exists in `resources/` before writing `matchNames`. If the agent has no tool resources, do not add a Tool-scoped guardrail.
 9. **Correctness validation uses `uip agent guardrails list` output** — `Parameters[].Type`, `Options`, `KeySource`, `Min`, `Max`, `Step` are the authoritative source for all parameter rules. Do not hardcode validator-specific knowledge.
 10. **The cache file is `.guardrails-catalog-cache.json`** in the working directory. Add it to `.gitignore` if one exists.

package/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md

@@ -8,11 +8,11 @@ Two types exist:
 - **`custom`** — deterministic rules you define (word matching, number comparison, boolean checks, universal triggers)
 - **`builtInValidator`** — UiPath Guardrails API validators (PII detection, harmful content, prompt injection, IP protection, user prompt attacks)
 
-> **Autonomous agents:** All guardrails are configured at the `agent.json` root `guardrails` array. **Conversational agents:** see § Conversational Support below — the runtime-effective location is each tool's `resources/<Tool>/resource.json` → `guardrail.policies[]`.
+> **Autonomous agents:** All guardrails are configured at the `agent.json` root `guardrails` array. **Conversational agents:** the `agent.json` root `guardrails[]` is **authoritative** (source for the Studio Web UI and both runtimes); each Tool-scoped guardrail is also mirrored into the tool's `resources/<Tool>/resource.json` → `guardrail.policies[]` — see § Conversational Support below.
 
 ## Conversational Support
 
-**Status: Tool-scoped only, per-tool resource files are authoritative.** Conversational agents support guardrails with `selector.scopes: ["Tool"]` only — DO NOT use `"Agent"` or `"Llm"`.
+**Status: Custom (deterministic) `Tool`-scoped guardrails ONLY. No built-in validators.** Built-in validators (any `$guardrailType: "builtInValidator"` — the validators returned by `uip agent guardrails list`; see the [Validators Quick Reference](#validators-quick-reference)) are autonomous-only — the conversational runtime never runs them, at any scope. The only guardrails that run are `$guardrailType: "custom"` deterministic rules (word/number/boolean/always) with `selector.scopes: ["Tool"]`. Write each as the **same object (same `id`) in two places** — the `agent.json` root `guardrails[]` is **authoritative** (source for the Studio Web UI and both runtimes); the tool's `resources/<Tool>/resource.json` → `guardrail.policies[]` is its **mirror**. Write both (the CLI doesn't auto-sync), but a guardrail present only in the tool resource is invisible in Studio Web and does not run on the Unified (Python) runtime. `"Agent"` and `"Llm"` scopes are not available. If asked for PII / harmful-content / injection detection, explain built-in validators are autonomous-only and offer a Custom Tool guardrail or an autonomous agent instead.
 
 This restriction is enforced as [../../critical-rules/conversational-critical-rules.md](../../critical-rules/conversational-critical-rules.md) Critical Rule 1.
 
@@ -34,7 +34,7 @@ Every guardrail object in the `guardrails` array shares these base fields:
 
 The `selector` field controls where the guardrail applies.
 
-> **Conversational agents — use `["Tool"]` ONLY. `"Agent"` and `"Llm"` are NOT available; DO NOT use them.** (see [../../critical-rules/conversational-critical-rules.md](../../critical-rules/conversational-critical-rules.md) Rule 1).
+> **Conversational agents — Custom (deterministic) `Tool` guardrails ONLY; no `builtInValidator` at all. `"Agent"`/`"Llm"` scopes are NOT available.** (see [../../critical-rules/conversational-critical-rules.md](../../critical-rules/conversational-critical-rules.md) Rule 1).
 
 ```json
 "selector": {
@@ -102,7 +102,7 @@ Each entry in the `Data` array contains:
 
 Do not hardcode assumptions about scope/stage support or availability.
 
-> **Conversational override** (see [../../critical-rules/conversational-critical-rules.md](../../critical-rules/conversational-critical-rules.md) Critical Rule 1)**.** `AllowedScopes` describes what the validator's schema accepts — it is **not** the set of scopes valid for the runtime you're targeting. For low-code conversational agents, **intersect `AllowedScopes` with `["Tool"]`** before writing `selector.scopes`. If the validator does not list `"Tool"` in `AllowedScopes`, it cannot be used in a conversational agent — do not substitute `"Agent"` or `"Llm"` as a workaround — those scopes are not available for conversational agents.
+> **Conversational override** (see [../../critical-rules/conversational-critical-rules.md](../../critical-rules/conversational-critical-rules.md) Critical Rule 1)**.** `AllowedScopes` describes what a **built-in validator's** schema accepts — but built-in validators are **not usable at all** on conversational agents (they are autonomous-only). Do NOT author any `builtInValidator` guardrail for a conversational agent, at any scope. The only guardrails the conversational runtime runs are `$guardrailType: "custom"` deterministic rules scoped to `Tool`.
 
 ## Actions
 
@@ -569,24 +569,24 @@ Built-in validators call the UiPath Guardrails API. They have a `validatorType`
 
 ### Validators Quick Reference
 
-> **For conversational agents (see [../../critical-rules/conversational-critical-rules.md](../../critical-rules/conversational-critical-rules.md) Critical Rule 1): use `"Tool"` only — DO NOT use the `Agent` and `Llm` entries below.** The Scopes column is the validator's schema-level support, not the conversational runtime's support: `Agent`/`Llm` are not available for conversational agents.
+> **These are all `builtInValidator` guardrails — autonomous-only. NONE are usable on conversational agents** (see [../../critical-rules/conversational-critical-rules.md](../../critical-rules/conversational-critical-rules.md) Critical Rule 1); the conversational runtime runs only Custom deterministic `Tool` guardrails. The table below describes autonomous support.
 
 | Validator | Scopes (autonomous) | Conversational | Stages | Supported Actions |
 |-----------|---------------------|----------------|--------|-------------------|
-| `pii_detection` | Agent, Llm, Tool | **Tool only** | Pre + Post | Block, Log, Escalate |
-| `prompt_injection` | Llm | **Not usable** (no Tool scope) | Pre only | Block, Log, Escalate |
-| `harmful_content` | Agent, Llm, Tool | **Tool only** | Pre + Post | Block, Log, Escalate |
-| `intellectual_property` | Llm, Agent | **Not usable** (no Tool scope) | Post only | Block, Log, Escalate |
-| `user_prompt_attacks` | Llm | **Not usable** (no Tool scope) | Pre only | Block, Log, Escalate |
+| `pii_detection` | Agent, Llm, Tool | **Not usable** (autonomous-only) | Pre + Post | Block, Log, Escalate |
+| `prompt_injection` | Llm | **Not usable** (autonomous-only) | Pre only | Block, Log, Escalate |
+| `harmful_content` | Agent, Llm, Tool | **Not usable** (autonomous-only) | Pre + Post | Block, Log, Escalate |
+| `intellectual_property` | Llm, Agent | **Not usable** (autonomous-only) | Post only | Block, Log, Escalate |
+| `user_prompt_attacks` | Llm | **Not usable** (autonomous-only) | Pre only | Block, Log, Escalate |
 
-Run `uip agent guardrails list --output json` to get the authoritative list. Only use validators where `Status` is `"Available"`. Use the output to populate `validatorType`, `selector.scopes`, and `validatorParameters` fields. **For conversational agents, intersect `AllowedScopes` with `["Tool"]` — if `"Tool"` is not in the validator's `AllowedScopes`, the validator cannot be used in a conversational agent.**
+Run `uip agent guardrails list --output json` to get the authoritative list. Only use validators where `Status` is `"Available"`. Use the output to populate `validatorType`, `selector.scopes`, and `validatorParameters` fields. **These built-in validators are autonomous-only — do NOT author any of them on a conversational agent (they will not run at any scope). Conversational agents use Custom deterministic `Tool` guardrails only.**
 **How to map `uip agent guardrails list` output to guardrail JSON:**
 
 | CLI field | Maps to |
 |-----------|---------|
 | `Status` | Gate check — only proceed if `"Available"` |
 | `Validator` | `validatorType` value |
-| `AllowedScopes` | Valid values for `selector.scopes` (autonomous). **Conversational: intersect with `["Tool"]`** — see [../../critical-rules/conversational-critical-rules.md](../../critical-rules/conversational-critical-rules.md) Critical Rule 1. |
+| `AllowedScopes` | Valid values for `selector.scopes` (autonomous only — built-in validators are not usable on conversational agents; see [../../critical-rules/conversational-critical-rules.md](../../critical-rules/conversational-critical-rules.md) Critical Rule 1). |
 | `GuardrailStages[scope]` | Valid execution stages for that scope |
 | `Parameters[].Id` | `validatorParameters[].id` |
 | `Parameters[].Type` | `validatorParameters[].$parameterType` |
@@ -981,7 +981,7 @@ Add the `guardrails` array at the agent.json root level alongside `settings`, `m
 4. **Do not add `intellectual_property` to Tool scope** — only `"Llm"` and `"Agent"` scopes are supported.
 5. **Do not add `intellectual_property` to PreExecution stage** — PostExecution only.
 6. **Do not omit `matchNames` when `Tool` is in `scopes`** — always explicitly list the target tool names. See [matchNames — "All Tools" Behavior](#matchnames--all-tools-behavior).
-7. **Do not use `filter` action on built-in validators** — `"$actionType": "filter"` is only supported on deterministic rules. All built-in validators (`pii_detection`, `intellectual_property`, `prompt_injection`, `user_prompt_attacks`, `harmful_content`) support only `block`, `log`, and `escalate`.
+7. **Do not use `filter` action on built-in validators** — `"$actionType": "filter"` is only supported on deterministic (`custom`) rules. Every built-in validator (`$guardrailType: "builtInValidator"`) supports only `block`, `log`, and `escalate` (see the [Validators Quick Reference](#validators-quick-reference) § Supported Actions).
 8. **Do not use odd numbers or floats for `harmfulContentEntityThresholds`** — only `0`, `2`, `4`, `6` are valid severity values. Values like `3` or `2.5` cause validation errors.
 9. **Do not add a built-in validator without first running `uip agent guardrails list --output json`** — always fetch the list, verify the validator exists, and confirm `Status` is `"Available"`. Adding an `Unauthorised` or non-existent validator causes runtime failures.
 10. **Do not use Action Center apps with `Type: "VB Action"` or `Type: "Coded"` as escalation targets** — only entries with `Type: "Workflow Action"` can back a guardrail escalation. Always filter `uip solution resources list --kind App` results by this type.
@@ -1002,15 +1002,15 @@ Use when adding input/output safeguards (PII detection, harmful content blocking
 
 > **MANDATORY: Read this file BEFORE writing any guardrail JSON.** The guardrail schema uses discriminator fields (`$actionType`, `$parameterType`, `$ruleType`, `$selectorType`) that cannot be guessed. PII detection uses `$guardrailType: "builtInValidator"` with `validatorType: "pii_detection"` — NOT `$guardrailType: "pii"`. Parameters use `id` (not `name`) and require `$parameterType`. Actions use `$actionType` (not `type`). PII entities are PascalCase (`"Email"`, not `"email_address"`). There is no `pattern`, `target`, or `message` field.
 >
-> **MANDATORY: Run `uip agent guardrails list --output json` before writing any guardrail**, regardless of type. The command gives you the exact `$parameterType` values, parameter `id` names, and allowed scopes — values you cannot safely derive from the type name alone. Skipping it leads to invalid parameter shapes that fail schema validation.
+> **MANDATORY for `builtInValidator` guardrails: run `uip agent guardrails list --output json` before writing one.** The command gives you the exact `$parameterType` values, parameter `id` names, and allowed scopes — values you cannot safely derive from the type name alone. Skipping it leads to invalid parameter shapes that fail schema validation. **Custom guardrails (`$guardrailType: "custom"`) do NOT need this step** — their rules (word/number/boolean/always), operators, and actions are fully specified here in this reference and use no validator catalog. Only run `guardrails list` for a custom guardrail if you are unsure whether the request should instead use a built-in validator.
 
-### Step 0 — Fetch available validators (mandatory for ALL guardrail types)
+### Step 0 — Fetch available validators (mandatory for `builtInValidator` guardrails; skip for custom-only)
 
 ```bash
 uip agent guardrails list --output json
 ```
 
-Build a lookup of `{ validatorId: status }` from `Data`. Required for both custom and built-in guardrails — confirms the correct parameter shapes and scope/stage constraints for the guardrail you are about to write.
+Build a lookup of `{ validatorId: status }` from `Data`. Required before adding any built-in validator — confirms the correct parameter shapes and scope/stage constraints. Skip this step when the guardrail is purely custom (deterministic rules); the validator catalog does not apply to custom rules.
 
 ### Step 1 — Verify existing agent
 

package/skills/uipath-agents/references/lowcode/capabilities/inline-in-flow/inline-in-flow.md

@@ -73,8 +73,8 @@ Generate a unique UUID (e.g., `5029c8a8-799b-426a-803f-c4ec75255439`). Create a
 
 Same schema as a standalone agent (see [../../agent-definition.md](../../agent-definition.md)), with these conventions:
 - `projectId` matches the folder name UUID
-- `inputSchema.properties` stays empty `{}` for prompt-only flow-data references. Prompts reference upstream flow nodes directly via `{{ $vars.<flowNodeId>.output[.<field>] }}` in `messages[].content`, mirrored in `contentTokens[]` as `{ "type": "variable", "rawString": " $vars.<flowNodeId>.output[.<field>] " }` (leading and trailing space inside `rawString`). See the `uipath-maestro-flow` skill's [inline-agent prompt-wiring guide](../../../../../uipath-maestro-flow/references/author/references/plugins/inline-agent/impl.md#wiring-flow-variables-into-agent-prompts).
-- `messages` have empty `content` and `contentTokens` initially. Set prompts in `messages[].content`, then build `messages[].contentTokens[]` as a parallel list: one `{ "type": "simpleText", "rawString": "..." }` per literal text segment, one `{ "type": "variable", "rawString": " $vars.<flowNodeId>.output[.<field>] " }` per `{{ ... }}` reference.
+- `inputSchema.properties`: one `<triggerNodeId>__output__<global>` key per flow input — **mandatory**. See [§ Wiring Flow Inputs Into an Inline Agent](#wiring-flow-inputs-into-an-inline-agent-required).
+- `messages[].content`: reference inputs as `{{input.<triggerNodeId>__output__<global>}}` (the `input.` form). Then run `uip agent refresh` to regenerate `contentTokens` from `content` — don't hand-author them. See [§ Wiring Flow Inputs Into an Inline Agent](#wiring-flow-inputs-into-an-inline-agent-required).
 - `guardrails: []` at root level — can be populated with guardrail objects. See [../guardrails/guardrails.md](../guardrails/guardrails.md)
 - No `metadata.targetRuntime` field
 
@@ -126,6 +126,24 @@ features/
 resources/
 ```
 
+## Wiring Flow Inputs Into an Inline Agent (required)
+
+**The CLI does not derive the input wiring** — you author it; `refresh` only regenerates `contentTokens` from `content` (it does not fill `inputSchema` or `agentInputVariables`). `flow validate` *does* catch a prompt↔schema mismatch (a `{{input.K}}` that's malformed or names a key not in `inputSchema`), but **not** a missing/wrong node `agentInputVariables` binding — that delivery gap surfaces only at `flow debug`.
+
+This skill authors the **`agent.json` side** (flatten rule: `$vars.<trigger>.output.<var>` → `<trigger>__output__<var>`):
+- `inputSchema.properties` — one `<trigger>__output__<var>` key per input (mandatory; binds the delivered `JobArguments` into the agent's `input`). Empty schema → the agent sees the literal `input.<key>` token even when the value arrived.
+- `messages[].content` — reference each input as `{{input.<trigger>__output__<var>}}` (the `input.` form, **not** `$vars`), plus a real system prompt. `content` is the source of truth; run `uip agent refresh` to generate the matching `contentTokens` from it (don't hand-author them).
+
+```json
+"inputSchema": { "properties": {
+  "start__output__disputeSummary": { "type": "string", "description": "Bound from $vars.start.output.disputeSummary" }
+} },
+"messages": [{ "role": "user",
+  "content": "Write a billing resolution email for this dispute:\n{{input.start__output__disputeSummary}}" }]
+```
+
+The **flow side** — the trigger global and the node `agentInputVariables[]` binding (the only thing the converter turns into `JobArguments`) — is authored through the `uipath-maestro-flow` skill (Critical Rule 15). The full four-piece contract, the converter behavior, and the `content`↔`contentTokens` invariant + validator errors all live there: [inline-agent prompt-wiring guide § Wiring Flow Variables into Agent Prompts](../../../../../uipath-maestro-flow/references/author/references/plugins/inline-agent/impl.md#wiring-flow-variables-into-agent-prompts).
+
 ## Refresh and Validate Inline Agent
 
 ```bash
@@ -133,7 +151,9 @@ uip agent refresh "<FlowProjectDir>/<projectId>" --inline-in-flow --output json
 uip agent validate "<FlowProjectDir>/<projectId>" --inline-in-flow --output json
 ```
 
-`--inline-in-flow` skips `entry-points.json` and `project.uiproj` checks. Refresh regenerates `entry-points.json` and `bindings_v2.json`; validate is read-only.
+`--inline-in-flow` skips the `entry-points.json` / `project.uiproj` checks. In inline mode `refresh` regenerates `messages[].contentTokens` (from `content`) and `bindings_v2.json` — **not** `entry-points.json` (standalone only). `validate` is read-only (it flags `contentTokens` drift but doesn't repair it — fix by re-running `refresh`).
+
+**Verify at `flow debug`, not after refresh:** `refresh` never fills `inputSchema` — it is non-empty only because you authored it (`DerivedFiles: 0` is normal and does **not** mean input is missing). The end-to-end check (run `uip maestro flow debug` and confirm the agent resolves the input rather than echoing the literal `input.<key>` token) is owned by the `uipath-maestro-flow` skill — see its [inline-agent guide § Debug](../../../../../uipath-maestro-flow/references/author/references/plugins/inline-agent/impl.md#debug).
 
 For inline agents with external capabilities (tools, contexts, memory spaces, or escalations), pass `--bindings-target` to **`refresh`** after all flow graph edits:
 

package/skills/uipath-agents/references/lowcode/critical-rules/conversational-critical-rules.md

@@ -4,13 +4,13 @@ These rules are the canonical source for rules specific to low-code conversation
 
 ## Critical Rules
 
-1. **Conversational agents support only Tool-scoped guardrails.** `selector.scopes` for conversational must be `["Tool"]` only — `"Agent"` and `"Llm"` scopes are not available. Author conversational guardrails in each affected tool's `resources/<Tool>/resource.json` under `guardrail.policies[]` (runtime-effective) AND mirror them at `agent.json` root `guardrails[]` (Studio Web display). See [../capabilities/guardrails/guardrails.md § Conversational Support](../capabilities/guardrails/guardrails.md#conversational-support).
+1. **Conversational agents support ONLY Custom (deterministic) guardrails scoped to a Tool.** Built-in validators (any `$guardrailType: "builtInValidator"` — the validators returned by `uip agent guardrails list`) are **autonomous-only**. Author only `$guardrailType: "custom"` deterministic rules (word/number/boolean/always) with `selector.scopes: ["Tool"]` at the `agent.json` root `guardrails[]` (authoritative for UI + runtime), mirrored into each affected tool's `resources/<Tool>/resource.json` → `guardrail.policies[]`. Write both (the CLI doesn't auto-sync), but treat the root as the source of truth — a guardrail only in the tool resource is invisible in Studio Web and does not run on the Unified (Python) runtime. `"Agent"` and `"Llm"` scopes are not available. If asked for PII / harmful-content / injection detection on a conversational agent, explain built-in validators are autonomous-only and offer a Custom deterministic Tool guardrail. See [../capabilities/guardrails/guardrails.md § Conversational Support](../capabilities/guardrails/guardrails.md#conversational-support).
 
 ## What NOT to Do
 
 1. **Do not add properties to the `outputSchema` of a conversational agent.** After initialization, leave `outputSchema` empty. The conversational agent runtime streams responses/tool-call events during the execution, so the final output is not relevant for the end-user in the conversation.
 
-2. **Do not set `selector.scopes` to anything other than `["Tool"]` for guardrails on a conversational agent, and do not put the guardrail only in `agent.json` root `guardrails[]`** — Agent- and Llm-scoped guardrails are not honored by the conversational runtime. The runtime reads guardrails from each tool's `resources/<Tool>/resource.json` → `guardrail.policies[]`; the `agent.json` root array is a Studio Web display mirror. Write to the tool resource (and mirror to agent.json root), per Critical Rule 1.
+2. **Do not author any `builtInValidator` guardrail on a conversational agent, and do not set `selector.scopes` to anything other than `["Tool"]`.** Built-in validators (any `$guardrailType: "builtInValidator"`) are autonomous-only; Agent- and Llm-scoped guardrails are likewise not honored. Author the Custom `Tool` guardrail at the `agent.json` root `guardrails[]` (authoritative for UI + runtime) and mirror it into the tool's `resources/<Tool>/resource.json` → `guardrail.policies[]`; a guardrail only in the tool resource is invisible in Studio Web and does not run on the Unified (Python) runtime, per Critical Rule 1.
 
 3. **Do not remove the user-message `messages[1]`, despite it being irrelevant for Conversational Agents.** Simply leave the message content fields blank. The runtime or other APIs may currently require its presence, so it should be simply left untouched with empty content after the conversational agent project is initialized.
 

package/skills/uipath-agents/references/lowcode/project-lifecycle.md

@@ -115,6 +115,15 @@ uip agent refresh [path] --output json
 
 **Workflow:** run `uip agent refresh` to apply writes and regenerate derived files, then `uip agent validate` to verify the project is clean. For routine edits with no schema migration pending, refresh is still needed to keep `entry-points.json` and `bindings_v2.json` in sync.
 
+### Common refresh / validate errors
+
+`refresh` and `validate` share the same static checks. Two errors are easy to misread — resolve at the source, do not spelunk the CLI schema:
+
+| Error (in `Data.Errors[]`) | Cause | Fix |
+|---|---|---|
+| `resources/<Folder>/resource.json: folder must be named after the resource name "<Name>" (found "<Folder>")` | Resource folder name must exactly equal the resource's `name` field — case- and whitespace-sensitive (`Count Sources`, not `CountSources`). | Rename the folder to match `name` verbatim, spaces included. |
+| `resources/<Name>/resource.json: Invalid input` (no field path) | A required field on that tool resource is missing or malformed. The path-less message does not name it. Most common cause: the required `guardrail` object is absent (every tool resource requires it, schema V21+). | Add `"guardrail": { "policies": [] }` to the resource. If already present, diff the resource against a CLI-generated one (`uip agent tool add`) for the missing/mistyped field. |
+
 ### `uip agent memory`
 
 Manage low-code agent memory space features and seed items. These commands write `features/{FeatureName}/feature.json`; run refresh and validate afterwards to regenerate bindings.

package/skills/uipath-agents/references/lowcode/prompting/conversational-agent-prompting-guide.md

@@ -108,7 +108,7 @@ User message: `""` — left blank. The Conversational Service injects the user t
 | `settings.temperature` | `0` | Raise for open-ended brainstorming or casual chats. Keep `0` for factual support flows. |
 | `settings.maxTokens` | `64000` | Set ≤ the model's `MaxTokens` cap — see [model-selection-guide.md](../model-selection-guide.md#1-discover-primary-path). |
 | `settings.model` | `anthropic.claude-sonnet-4-5-20250929-v1:0` | **Always verify** — discover + select per [model-selection-guide.md](../model-selection-guide.md). |
-| `guardrails` | `[]` | Tool-scope only; mirror in tool `resource.json`. See [capabilities/guardrails/guardrails.md](../capabilities/guardrails/guardrails.md) ([critical-rules/conversational-critical-rules.md](../critical-rules/conversational-critical-rules.md) Critical Rule 1). |
+| `guardrails` | `[]` | Custom (deterministic) Tool guardrails only — no built-in validators; mirror in tool `resource.json`. See [capabilities/guardrails/guardrails.md](../capabilities/guardrails/guardrails.md) ([critical-rules/conversational-critical-rules.md](../critical-rules/conversational-critical-rules.md) Critical Rule 1). |
 
 ## Anti-patterns
 
@@ -118,6 +118,6 @@ User message: `""` — left blank. The Conversational Service injects the user t
 - **Populating `outputSchema`** — runtime streams events; populated schemas never get filled and confuse the agent ([critical-rules/conversational-critical-rules.md](../critical-rules/conversational-critical-rules.md) Anti-pattern 1).
 - **Templating data into the user message** — the user message content stays blank; per-exchange context goes into the **system prompt** via `inputSchema` templating.
 - **Adding `messages` or `uipath__*` to `inputSchema`** — reserved names; runtime injects ([critical-rules/conversational-critical-rules.md](../critical-rules/conversational-critical-rules.md) Anti-patterns 4 and 5).
-- **Using `Agent` or `Llm` guardrail scopes** — silently ignored; only Tool-scope guardrails apply ([critical-rules/conversational-critical-rules.md](../critical-rules/conversational-critical-rules.md) Critical Rule 1).
+- **Using built-in validator guardrails (PII, harmful content, etc.) or `Agent`/`Llm` scopes** — built-in validators are autonomous-only and silently ignored; conversational agents support only Custom deterministic `Tool`-scoped guardrails ([critical-rules/conversational-critical-rules.md](../critical-rules/conversational-critical-rules.md) Critical Rule 1).
 - **Defining citation-generation format in the system prompt** — agent runtime wraps citation formatting around the prompt; redefining it conflicts or confuses citation generation (see § 1 callout).
 - **Cargo-culted `temperature`** — copying a nonzero temperature into a deterministic, factual-based conversation task.