@uipath/skills 1.195.0

package/skills/uipath-troubleshoot/references/products/agents/playbooks/llm-insufficient-information.md

@@ -0,0 +1,78 @@
+---
+confidence: medium
+---
+
+# LLM Call Failed — Insufficient Information in Prompt
+
+## Context
+
+What this looks like:
+- Agent job faults mid-run; `uip agent run status <job-id> --output json` shows `Faulted`
+- `uip traces spans get <trace-id> --output json` contains a span with `SPANTYPE: completion` or `agentRun` whose `ATTRIBUTES.error` is a JSON string starting with `{"detail":"Insufficient information..."}` or `{"detail":"Insufficient information to <action>..."}`
+- The error detail names a missing piece of context: recipient, topic, date range, scope, etc.
+
+What can cause it:
+- Agent system prompt is too open-ended — the LLM cannot infer required parameters from the user's message alone
+- User invocation omits a required input field that the agent's instructions assume will be present
+- Agent is invoked programmatically with a sparse or template payload that lacks inline context
+- The agent's task description tells the LLM to perform an action but provides no data to act on
+
+What to look for:
+- The `detail` field in the error JSON names the missing information — use this to identify whether it is a prompt design issue or a caller input issue
+- Whether the failure is consistent (every invocation) vs. intermittent (some inputs work) — consistent means the system prompt is the root cause; intermittent means the input payload varies
+
+## Investigation
+
+1. Get the job trace ID:
+
+   ```bash
+   uip agent run status <job-id> --output json \
+     --output-filter "traceId"
+   ```
+
+2. Pull spans and find the failing `completion` or `agentRun` span:
+
+   ```bash
+   uip traces spans get <trace-id> --output json \
+     --output-filter "spans[?attributes.error != null].{name: name, spanType: spanType, error: attributes.error}"
+   ```
+
+3. Parse the `error` field — it is a JSON string. Extract the `detail` value:
+
+   ```bash
+   uip traces spans get <trace-id> --output json \
+     --output-filter "spans[?attributes.error != null].attributes.error" \
+     | jq -r '.[] | fromjson | .detail'
+   ```
+
+   The detail names the missing information (e.g., `"The request does not specify which releases or their scope"`).
+
+4. Determine whether the missing context should come from the **system prompt** or the **caller's input**:
+   - If the missing info is structural (always required for the agent's purpose) → system prompt issue
+   - If the missing info varies per invocation (e.g., a recipient, a date) → input schema issue
+
+## Resolution
+
+**If the system prompt is too vague — improve it:**
+- Edit `agent.json` → `messages[0].content`: add explicit instructions covering the missing context named in the `detail` field; add constraints or clarification prompts (e.g., "If the user does not specify X, ask for clarification before proceeding")
+- Validate and republish:
+
+  ```bash
+  uip agent validate --output json
+  uip agent migrate --output json  # upgrades agent.json to the latest schema version; skip if validate reports no schema version change
+  uip agent publish --output json
+  ```
+
+**If a required input is missing from the caller's payload:**
+- Inspect the declared input schema: open `agent.json` locally, check `inputSchema`
+- If the parameter exists but the caller omitted it — fix the caller or add a default in the schema
+- If the parameter does not exist in the schema — add it:
+
+  ```bash
+  uip agent input add --name "<param-name>" --type string --required true --output json
+  uip agent publish --output json
+  ```
+
+**If the agent is invoked with a sparse programmatic payload:**
+- Ensure all required `inputSchema` fields are populated before calling `uip agent run start`
+- Pass missing context as inline input arguments rather than relying on the LLM to infer them

package/skills/uipath-troubleshoot/references/products/agents/summary.md

@@ -0,0 +1,9 @@
+# Agents Playbooks
+
+Covers errors from `uip agent` (low-code agents). Primary investigation surface: `uip traces spans get <trace-id> --output json`.
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| Input Schema Validation Failure | High | `agent.json failed schema validation` (Variant A: config schema) or `Data failed json schema validation DynamicType_0 BatchJson` (Variant B: input payload). Faults at agent startup before any LLM call. | [input-schema-validation-failure.md](./playbooks/input-schema-validation-failure.md) |
+| Context Grounding Index Not Found | High | `ContextGroundingIndex not found Code: AGENT_RUNTIME.UNEXPECTED_ERROR` on a `contextGroundingTool` span. Grounding index deleted or mis-referenced after publish. | [context-grounding-index-not-found.md](./playbooks/context-grounding-index-not-found.md) |
+| LLM Call Failed — Insufficient Information | Medium | `{"detail":"Insufficient information..."}` on a `completion` or `agentRun` span. System prompt too vague or required input missing from caller payload. | [llm-insufficient-information.md](./playbooks/llm-insufficient-information.md) |

package/skills/uipath-troubleshoot/references/products/integration-service/investigation_guide.md

@@ -0,0 +1,50 @@
+# Integration Service Investigation Guide
+
+## Data Correlation
+
+Before using any fetched data, verify it matches the user's reported problem:
+
+- **Connection identity** — the connection name and connector type match what the error message or user referenced
+- **Folder** — connections can be folder-scoped; verify you're looking at the connection in the correct folder
+- **Connector vs Connection** — a connector is the template (e.g., "uipath-microsoft365-o365"), a connection is an authenticated instance. Errors reference connections, not connectors.
+- **Caller context** — determine whether the connection was called from an Orchestrator workflow, a Maestro BPMN process, or a Studio debug session. The calling identity (user vs robot account) affects permissions.
+
+If the data doesn't match: **discard it**. Do NOT use unrelated data as a proxy. Report the mismatch and ask for clarification.
+
+## First Step: Identify the Connection AND its Ownership
+
+Always identify the specific connection AND determine where it lives before doing anything else. From the project's connection resource file (see "Connection Resource File" in [overview.md](./overview.md) for path pattern and field reference), you must answer four questions:
+
+- **Which connector?**
+- **Who owns the connection?**
+- **Where is the connection bound?**
+- **What is the connection ID?**
+
+Together these answers determine whether the connection is in the runner's workspace, in a different user's workspace, or in a folder the runner cannot reach. **Always extract and compare them — do not stop after just the connector name.**
+
+For the field-by-field extraction checklist for a specific error pattern, see the matched playbook's Investigation section — the playbook is authoritative for which fields and which comparisons matter for that error.
+
+If no source code is available, the error message usually names the connection. Use `uip is connections list` to find it by name, then `uip is connections ping <connection-id>` to check its status. Without the resource file, ownership cannot be confirmed without asking the user.
+
+**Do NOT infer the connector from the activity package name** — activity packages and connectors have different naming conventions (e.g., `UiPath.MicrosoftOffice365.Activities` uses connector "Microsoft OneDrive & SharePoint"). Always resolve from connection resource files or the connections API.
+
+If the connection identity is still unclear, ask the user which connection or connector is involved.
+
+## Domain-Specific Data Gathering
+
+After the Orchestrator job data bundle (job details, logs, traces) is collected and the connection is identified:
+
+1. **Connection status** — `uip is connections ping <connection-id>` to check if it's active
+2. **Connection details** — `uip is connections list` to find connector type, status, and folder scope
+3. **Connection resource file** — if source code is available, read the connection resource JSON from the project (see "Connection Resource File" in [overview.md](./overview.md) for path pattern)
+
+## Testing Prerequisites
+
+When testing hypotheses for Integration Service issues, gather and verify these before drawing conclusions:
+
+1. **Connection status** — ping the connection to check if it's active and enabled (`uip is connections ping <id>`)
+2. **Connection details** — list the connection to see its connector type, status, and folder scope
+3. **Caller identity** — determine if the caller is a user (debug mode) or robot account (deployed mode). Robot accounts may lack permissions the user has.
+4. **Folder permissions** — verify the caller has access to the folder where the connection resides. For Maestro triggers, the robot account needs "Triggers" permission, not just "Connections.View".
+5. **OAuth token state** — if the connection uses OAuth, check whether the token may have expired or been revoked. A ping failure after a period of working correctly suggests token expiry.
+6. **External service availability** — if the connection pings successfully but operations fail, the issue may be on the external service side (API changes, rate limits, outages)

package/skills/uipath-troubleshoot/references/products/integration-service/overview.md

@@ -0,0 +1,73 @@
+# Integration Service
+
+Connector platform that provides pre-built integrations with third-party services (Salesforce, Outlook, SAP, Slack, etc.). Manages OAuth connections, exposes activities for use in automations and BPMN processes, and provides event-based triggers.
+
+Integration Service is used by both Orchestrator (standalone automations) and Maestro (BPMN service tasks). Connection failures here surface as errors in whichever product initiated the call.
+
+## Organization Model
+
+```
+Organization (cloud.uipath.com)
+  └── Tenant
+        └── Connectors             ← Pre-built integration templates (Salesforce, Outlook, etc.)
+              └── Connections      ← Authenticated instances of a connector (folder-scoped)
+                    ├── Activities ← Operations available on the connector
+                    ├── Resources  ← Objects the connector can interact with
+                    └── Triggers   ← Event subscriptions (CREATED, UPDATED, DELETED)
+```
+
+## Dependencies
+
+- **Identity Server** — OAuth token management and user/robot identity resolution
+- **Orchestrator** — folder-scoped permissions, robot account access to connections
+- **Maestro** — BPMN processes invoke IS connections via service tasks; trigger events start BPMN instances
+- **External Services** — the third-party APIs that connectors wrap (Salesforce, O365, etc.)
+
+## Features
+
+- **Connectors** — pre-built integration templates for third-party services
+- **Connections** — authenticated instances of a connector, scoped to a tenant (optionally folder-scoped)
+- **Activities** — operations exposed by connectors for use in workflows and BPMN processes
+- **Resources** — objects and records within the external service (list, get, create, update, delete)
+- **Triggers** — event-based subscriptions that can start Orchestrator jobs or Maestro instances
+- **OAuth Management** — create, re-authenticate, and ping connections via OAuth flows
+
+## Connection Resource File
+
+Projects and solutions store connection references as JSON files. The location depends on whether the project is standalone or part of a solution — **always check both layouts**:
+
+| Layout | Path pattern |
+|--------|--------------|
+| Standalone project | `<project-root>/connection/<connector-key>/<owner>.json` |
+| Solution (single folder) | `<project-root>/resources/solution_folder/connection/<connector-key>/<owner>.json` |
+| Solution (multi-folder) | `<project-root>/resources/<folder-name>/connection/<connector-key>/<owner>.json` |
+
+Each `<connector-key>` subfolder contains one JSON file per connection, named after the connection's `resource.name` (typically the owner's email or username).
+
+**When investigating, glob `**/connection/<connector-key>/*.json` from the project root** — that catches all three layouts in one read. Do NOT assume the standalone path; solutions are common and the resource file may be several directories deep under `resources/`.
+
+Key fields:
+
+| Field | What it is | Use for |
+|-------|-----------|---------|
+| `spec.connectorName` | Human-readable connector display name (e.g., "Microsoft OneDrive & SharePoint") | **Always use this as the display name.** Do NOT guess from activity package names — they differ. |
+| `spec.connectorKey` | Connector key (e.g., `uipath-microsoft-onedrive`) | CLI queries: `uip is connectors get <key>`, `uip is connections list <key>` |
+| `resource.key` | Connection ID (UUID) | Match against connection IDs in workflow XAML |
+| `resource.name` | Connection owner (usually an email) | Identify who created the connection |
+| `spec.authenticationType` | How the connection authenticates | "AuthenticateAfterDeployment" means the user must authenticate after creating the connection |
+| `resource.folders` | Folder bindings | Which folder the connection is scoped to |
+
+## CLI
+
+```
+uip is connectors list|get              — browse available connectors
+uip is connections list|create|ping|edit — manage authenticated connections
+uip is activities list <connector-key>   — list connector activities (--triggers for trigger-only)
+uip is resources list|describe|run       — interact with connector resources
+uip is triggers objects|describe         — explore trigger metadata
+```
+
+Key commands for troubleshooting:
+- `uip is connections list [connector-key] --folder-key <key>` — list connections in a folder
+- `uip is connections ping <connection-id>` — check if a connection is active and enabled
+- `uip is connections list --connection-id <id>` — get details for a specific connection

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/connection-auth-expired.md

@@ -0,0 +1,35 @@
+---
+confidence: high
+---
+
+# Connection Authentication Expired
+
+## Context
+
+What this looks like:
+- Connection was previously working but now fails
+- Ping returns inactive/error status
+- OAuth-related errors (401 Unauthorized, token expired, refresh failed)
+- Maestro error code 102002 (IntSvcOperationFailed) with auth-related details
+
+What can cause it:
+- OAuth access token expired and refresh token is also expired or revoked
+- User who created the connection revoked app access in the external service
+- External service rotated or invalidated credentials
+- Connection was created with short-lived credentials that were not renewed
+
+What to look for:
+- Connection was working at some point (rules out misconfiguration)
+- Time gap between last successful use and first failure
+
+## Investigation
+
+1. **Read the connection resource file** — if source code is available, find and read the connection JSON (see "Connection Resource File" in [overview.md](../overview.md)) to get the connector name and connection ID
+2. `uip is connections ping <connection-id>` — confirm the connection is inactive
+3. Check when the connection last worked successfully (from job/instance history in triage evidence)
+
+## Resolution
+
+- Re-authenticate the connection via `uip is connections edit <connection-id>` or through the Integration Service UI
+- If the external service revoked access, re-authorize the app in the external service settings before re-authenticating
+- For connections used in production, consider setting up monitoring or alerts for connection health

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/connection-invalid.md

@@ -0,0 +1,53 @@
+---
+confidence: high
+---
+
+# Connection Invalid or No Access
+
+## Context
+
+What this looks like:
+- Error message: "connection [name] is invalid or you do not have access"
+- Maestro error code 102002 (IntSvcOperationFailed) or 102008 (GetConnectionInvalidInputError)
+- Process fails immediately when trying to use an Integration Service connection
+
+What can cause it:
+- Connection does not exist in the folder where the process runs
+- Connection exists in a different user's personal workspace — the process was published with a connection that belongs to another user and is not accessible from the runner's workspace
+- Connection exists but is disabled or in an error state
+- Robot account (deployed mode) lacks folder permissions to access the connection — debug mode works because it runs under the user's identity
+- Connection was deleted or renamed after the process was published
+- Folder bindings (`bindings_v2.json`) point to a different folder than where the connection resides
+
+What to look for:
+- The connection name and connector key in the error message or project files
+- Whether the issue occurs in debug mode, deployed mode, or both
+- Whether the process was published from a different user's workspace
+
+## Investigation
+
+> **Hard precondition for steps 2–4:** before running any CLI command or drawing any conclusion, you MUST complete step 1 — either read the connection resource file or explicitly record that no project source is available. CLI evidence (`ping` returning 404, empty `connections list`) is **not sufficient** to distinguish "deleted connection" from "cross-workspace ownership"; only the resource file disambiguates them. Skipping step 1 makes any conclusion at step 2/3 ambiguous and forces the depth-verifier to reject the hypothesis.
+
+1. **Read the connection resource file** — if source code is available, glob `**/connection/<connector-key>/*.json` from the project root to handle all project layouts (standalone, single-folder solution, multi-folder solution — see "Connection Resource File" in [overview.md](../overview.md)). If multiple files match, pick the one whose `resource.key` matches the connection ID in the error. From the file, extract every one of:
+   - `spec.connectorName` — the exact display name to use in findings (do NOT guess from the activity package name)
+   - `spec.connectorKey` — for CLI queries
+   - `resource.name` — the **connection owner**. If this is an email, the connection lives in that user's personal workspace; if it differs from the runner's identity, the connection is cross-workspace.
+   - `resource.folders[*].fullyQualifiedName` — the **folder binding**. Compare against the runner's job folder; if they differ, the connection is in a different folder than where the process runs.
+   - `resource.key` — the connection ID (UUID). Cross-check against the connection ID in the runtime error and in the workflow source (XAML/code).
+   - `spec.authenticationType` — `"AuthenticateAfterDeployment"` means the user must authenticate after creating the connection.
+
+   Record these six values in evidence. If the glob returns zero results AND the project source path is confirmed accessible, only then mark the resource file as "absent" and proceed; the conclusion at the end MUST acknowledge ownership could not be determined and recommend the user provide the resource file.
+
+2. `uip is connections list <connector-key> --folder-key <folder-key>` — check if a connection for that connector exists in the runner's folder. **Only meaningful after step 1**: combined with the resource file's `resource.folders` and `resource.name`, this confirms whether the offending connection lives in a different folder/user than the runner.
+
+3. If found: `uip is connections ping <connection-id>` — verify it is active and enabled
+
+4. **Cross-reference workflow binding** — if the workflow source is available, confirm the connection ID in the activity (`ConnectionId`/`ConnectionKey` attributes in XAML, or equivalent in coded workflows) matches `resource.key` from step 1. A mismatch means the runtime error connection ID is hard-bound elsewhere.
+
+## Resolution
+
+- **If connection not found in folder:** tell the user to create a new connection using the exact `connectorName` from step 1 (e.g., "Create a new **Microsoft OneDrive & SharePoint** connection"). If `authenticationType` is "AuthenticateAfterDeployment", tell the user they will need to authenticate the connection after creating it.
+- **If connection belongs to a different user's workspace:** the runner needs their own connection. Create a new connection in the runner's workspace for the same connector, then update the workflow to reference the new connection ID and republish. For shared processes, consider deploying to a shared folder with a shared connection instead of personal workspaces.
+- **If connection found but ping fails:** re-authenticate the connection via `uip is connections edit <connection-id>` or through the UI
+- **If connection is active but error persists in deployed mode:** check that the robot account has permissions in the folder where the connection resides — it needs at least "Connections.View" permission
+- **If this is a solution:** check `bindings_v2.json` to verify the folder binding for connections points to the correct folder. Add folder bindings so the connection resolves per-user when deployed.

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/operation-failed.md

@@ -0,0 +1,39 @@
+---
+confidence: medium
+---
+
+# Operation Failed
+
+## Context
+
+What this looks like:
+- Integration Service activity returns an error during execution
+- Maestro error codes: 102002 (IntSvcOperationFailed), 102003 (IntSvcBadRequest), 102004 (IntSvcMethodNotSupported), 102010 (IntSvcArgumentsError)
+- The connection is active but the specific operation fails
+
+What can cause it:
+- Invalid or missing input parameters for the activity
+- The external service API changed or deprecated the endpoint
+- The operation requires fields or permissions not available with the current connection scope
+- Rate limiting or quota exceeded on the external service
+- Resource referenced in the operation does not exist in the external service
+
+What to look for:
+- The specific error code and message detail
+- Whether the same operation worked before (regression vs misconfiguration)
+- Whether other operations on the same connector succeed (isolates operation vs connection issue)
+
+## Investigation
+
+1. **Read the connection resource file** — if source code is available, find and read the connection JSON (see "Connection Resource File" in [overview.md](../overview.md)) to identify the connector and connection
+2. `uip is connections ping <connection-id>` — confirm the connection is healthy
+3. `uip is activities list <connector-key>` — verify the activity exists and is supported
+4. `uip is resources describe <connector-key> <object-name>` — check required fields and operations
+5. Check if the external service API has changed or if rate limits apply
+
+## Resolution
+
+- **If bad request / invalid input:** fix the input parameters to match the activity's required schema (use `uip is resources describe` for field definitions)
+- **If method not supported:** the connector may not support this operation — check connector documentation or use a different activity
+- **If external service changed:** update the activity configuration to match the new API schema
+- **If rate limited:** implement retry logic or reduce call frequency

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/trigger-not-firing.md

@@ -0,0 +1,40 @@
+---
+confidence: medium
+---
+
+# Trigger Not Firing
+
+## Context
+
+What this looks like:
+- Integration Service trigger is configured but events don't start jobs or Maestro instances
+- External events occur but no corresponding execution is created
+- Trigger appears configured correctly in the UI
+
+What can cause it:
+- Connection used by the trigger is inactive or expired
+- Robot account lacks "Triggers" permission in the folder (not just "Connections.View")
+- Trigger subscription was not created or was deleted in the external service
+- Event payload doesn't match the trigger's expected schema or object type
+- For Maestro: the trigger was configured in debug mode with `debug_overwrites.json` bindings that don't apply in deployed mode
+
+What to look for:
+- Check connection status for the trigger's connector
+- Check folder permissions for the robot account
+- Check if the trigger subscription exists in the external service
+- Compare debug vs deployed trigger configuration
+
+## Investigation
+
+1. **Read the connection resource file** — if source code is available, find and read the connection JSON (see "Connection Resource File" in [overview.md](../overview.md)) to identify the connector and connection
+2. `uip is connections ping <connection-id>` — verify the connection is active
+3. Check folder permissions for the robot account — verify "Triggers" permission exists
+4. `uip is triggers objects <connector-key> <operation>` — verify the trigger object type is correct
+5. Check if the issue is debug-only or deploy-only (identity and bindings differ)
+
+## Resolution
+
+- **If connection inactive:** re-authenticate via `uip is connections edit <connection-id>`
+- **If permission missing:** grant "Triggers" permission to the robot account in the target folder
+- **If trigger object mismatch:** reconfigure the trigger with the correct object type and operation
+- **If debug-vs-deploy issue:** verify `bindings_v2.json` folder bindings match the folder where the connection and trigger are configured

package/skills/uipath-troubleshoot/references/products/integration-service/presentation.md

@@ -0,0 +1,14 @@
+# Integration Service Presentation Rules
+
+When a connection resource file is available (see "Connection Resource File" in [overview.md](./overview.md) for field reference):
+
+- **Connections** — display as `resource.name` + `spec.connectorName`. Format: "**{resource.name}** ({spec.connectorName})". Show `resource.key` (connection ID) only when needed for commands.
+- **Connectors** — use `spec.connectorName`, never `spec.connectorKey` or activity package names
+- **Connection owner** — use `resource.name`
+- **Connection type** — use `spec.authenticationType` when describing how the user needs to authenticate
+
+When no connection resource file is available, resolve from the connections API (`uip is connections list`).
+
+General rules:
+- **Do NOT infer connector names from activity package names** — they differ. Always resolve from the connection resource file or the connections API.
+- **Activities** — use the activity display name from the connector, not the internal operation ID

package/skills/uipath-troubleshoot/references/products/integration-service/summary.md

@@ -0,0 +1,10 @@
+# Integration Service Playbooks
+
+**Investigation guide:** [investigation_guide.md](./investigation_guide.md) — data correlation rules and testing prerequisites for Integration Service investigations
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| Connection Invalid or No Access | High | "connection is invalid or you do not have access" — connection missing, disabled, or caller lacks permissions | [connection-invalid.md](./playbooks/connection-invalid.md) |
+| Connection Authentication Expired | High | Connection was working but now fails — OAuth token expired or revoked | [connection-auth-expired.md](./playbooks/connection-auth-expired.md) |
+| Trigger Not Firing | Medium | IS trigger configured but events not starting jobs/instances — subscription, permissions, or event mismatch | [trigger-not-firing.md](./playbooks/trigger-not-firing.md) |
+| Operation Failed | Medium | IS activity returns error during execution — bad request, unsupported method, or input validation | [operation-failed.md](./playbooks/operation-failed.md) |

package/skills/uipath-troubleshoot/references/products/llm-gateway/overview.md

@@ -0,0 +1,64 @@
+# LLM Gateway
+
+The LLM Gateway is the UiPath service that routes agent / product LLM calls to a model — either the platform default or a tenant-owned (BYO) provider key. It exposes a single CLI surface for configuration management: `uip llm-configuration byo-connections`. There is **no first-class CLI for per-request gateway logs** — diagnosis is current-state + trace-evidence only.
+
+A BYO LLM product configuration is the record that says: "for product `P` and feature `F`, route LLM calls through Integration Service connection `C` to model `M` via vendor `V`". When agent calls fail with model / provider errors, the BYO record is one of three places to look — the others are the underlying IS connection and tenant-wide AI Trust Layer policy.
+
+## Organization Model
+
+```
+Tenant
+  └── BYO LLM Product Configuration       ← one per (product, operationGroupName)
+        ├── product                       ← e.g. agents, agenthub, jarvis, ixp, uipath-ecs
+        ├── operationGroupName (feature)  ← e.g. agenthub-llm-call, agents-design-eval-deploy
+        ├── enabled                       ← gates whether this record is honored
+        ├── llmConfigurations[]           ← model mappings
+        │     ├── llmName / llmIdentifier  ← what the customer registered
+        │     ├── connectorType            ← OpenAi / AzureOpenAi / AmazonWebServices / GoogleVertex / OpenAiV1Compatible
+        │     ├── apiFlavor                ← OpenAiResponses / OpenAiChatCompletions / AwsBedrockInvoke / ...
+        │     └── connectionId             ← Integration Service connection UUID (the credentials)
+        └── validation (server-side probes, last write)
+              └── modelName: {isAvailable, isCompatible, isModelNameSimilar}
+```
+
+## Dependencies
+
+- **Integration Service** — every BYO configuration points at an IS connection (`connectionId`) for credentials. If the IS connection is disabled, revoked, or rotated, the BYO config's runtime calls fail. See [Integration Service playbooks](../integration-service/summary.md).
+- **AI Trust Layer (Governance)** — tenant-wide policies on allowed providers / blocked models can override BYO routing at runtime. See `uip gov aops-policy` and [`uipath-governance`](/uipath:uipath-governance).
+- **Agent / product runtime** — the consumer of the LLM call (agents, agenthub, jarvis, IXP). The agent's trace spans are the only per-request evidence available.
+- **LLM Observability traces** — `uip traces spans get <trace-id>` returns spans with the model + provider that was actually invoked. Owned by `uipath-agents` / this skill, not the LLM Gateway CLI itself.
+
+## Features
+
+- **BYO LLM product configurations** — register tenant-owned LLM keys against UiPath product features. Six verbs: `list`, `get`, `create`, `update`, `delete`, `list-product-configs`.
+- **Server-side validation probes** — `create` and `update` always run `POST .../validate`. The probe summary is keyed by model and reports `isAvailable` / `isCompatible` / `isModelNameSimilar`. This is **mandatory and the only diagnostic exposed at write time**.
+- **Connection-detail resolution** — `get --force-refresh` and `list --include-connection-details` re-resolve the underlying IS connection state. This is the primary read-time diagnostic.
+
+## CLI
+
+```
+uip llm-configuration byo-connections list                          — list all BYO configs for the tenant
+uip llm-configuration byo-connections list --include-connection-details  — list with IS connection state resolved
+uip llm-configuration byo-connections get <id> --force-refresh      — fetch one config and re-resolve connection details
+uip llm-configuration byo-connections list-product-configs          — discover allowed (product, feature, model, connector, api-flavor) combinations
+uip llm-configuration byo-connections create / update / delete      — mutate (write-time validation is mandatory)
+```
+
+Key commands for troubleshooting:
+
+- `uip llm-configuration byo-connections get <id> --force-refresh --output json` — re-resolve the underlying connection state for a single BYO config
+- `uip llm-configuration byo-connections list --include-connection-details --output json` — tenant audit: every BYO config + the live state of its IS connection
+- `uip llm-configuration byo-connections list-product-configs --product <p> --feature <f> --output json` — confirm the saved mapping still matches the product's current allowed-model catalog
+- `uip llm-configuration byo-connections update <id> --<same-fields>` — idempotent re-write that forces a fresh server-side probe; surfaces current `isAvailable` / `isCompatible`
+- `uip gov aops-policy deployed-policy resolve --product AITrustLayer ... --output json` — resolve the tenant-effective AI Trust Layer policy when calls are blocked by governance
+- `uip traces spans get <trace-id> --output json` — read the actual model + provider invoked on a failing agent call
+
+## What the CLI does NOT expose
+
+There is **no** `uip llm-configuration logs`, **no** per-request gateway invocation history, **no** time-series probe results, and **no** vendor-side error history without re-probing. If a runtime issue cannot be explained by current state or trace evidence, the next step is a support ticket with the trace ID — not further CLI investigation.
+
+## See Also
+
+- Configuration reference (Build / Operate / Diagnose flows): [`uipath-platform` → `references/llmgateway/byo-connections.md`](/uipath:uipath-platform)
+- AI Trust Layer policy authoring + `deployed-policy resolve` diagnostics: [`uipath-governance`](/uipath:uipath-governance)
+- Trace inspection for the consuming agent: [`uipath-agents`](/uipath:uipath-agents)

package/skills/uipath-troubleshoot/references/products/llm-gateway/playbooks/byo-connection-dead.md

@@ -0,0 +1,59 @@
+---
+confidence: high
+---
+
+# BYO LLM Call Failing — Underlying IS Connection Dead
+
+## Context
+
+What this looks like:
+- Agent / product LLM call was previously working and now fails with auth-shaped errors (401, 403, "invalid credentials", "API key not valid")
+- Errors reference the vendor (OpenAI / Azure OpenAI / Bedrock / Vertex / Anthropic) directly, not the UiPath platform
+- A BYO LLM product configuration is registered for the failing product / feature
+- The configuration's `enabled: true`
+
+What can cause it:
+- The Integration Service connection's OAuth token expired and refresh failed
+- The connection owner revoked the app in the external service
+- The vendor rotated or invalidated the API key
+- The IS connection was disabled or deleted in the connections folder
+
+What to look for:
+- The BYO config has not been edited since the breakage began
+- A time gap between last successful LLM call and first failure
+- The IS connection referenced by `connectionId` is not in `Enabled` state when resolved live
+
+## Investigation
+
+1. **Identify the BYO configuration** for the failing (product, feature). If the user gave a trace ID, read `uip traces spans get <trace-id> --output json` first to confirm the model + provider the call was attempting (or attempted to fall back to).
+
+   ```bash
+   uip llm-configuration byo-connections list \
+     --output json --output-filter "Data[?product=='<product>' && operationGroupName=='<feature>']"
+   ```
+
+2. **Re-resolve the underlying IS connection state.** `--force-refresh` bypasses cached connection details and re-queries Integration Service:
+
+   ```bash
+   uip llm-configuration byo-connections get <id> --force-refresh --output json
+   ```
+
+   Inspect the resolved fields: `connectionState`, `enabled` (on the connection, not the BYO record), and connector identity. Any value other than `Enabled` confirms the hypothesis.
+
+3. **Optional cross-check — ping the IS connection directly.** If you have the `connectionId` from step 2, route to the [Integration Service connection-auth-expired playbook](../../integration-service/playbooks/connection-auth-expired.md) for the re-authentication path. The IS layer owns the OAuth recovery.
+
+## Resolution
+
+- Re-authenticate the IS connection: `uip is connections edit <connection-id>` (or via the Integration Service UI). See [Integration Service playbook](../../integration-service/playbooks/connection-auth-expired.md) for the full re-auth flow.
+- Once the IS connection is back to `Enabled`, re-probe the BYO config by issuing an idempotent `update` — this forces a fresh server-side validation:
+
+  ```bash
+  uip llm-configuration byo-connections update <id> \
+    --llm-name <same> --llm-identifier <same> \
+    --connector-type <same> --api-flavor <same> \
+    --connection-id <same> --output json
+  ```
+
+  Expect `isAvailable: true` / `isCompatible: true` in the validation block.
+- If the external service revoked the app, re-authorize it in the vendor's settings before re-authenticating the connection.
+- For BYO configs used in production, audit periodically: `uip llm-configuration byo-connections list --include-connection-details --output-filter "Data[?connectionState!='Enabled']"`.

package/skills/uipath-troubleshoot/references/products/llm-gateway/playbooks/byo-routing-bypassed.md

@@ -0,0 +1,86 @@
+---
+confidence: medium
+---
+
+# BYO LLM Routing Bypassed
+
+## Context
+
+What this looks like:
+- A BYO LLM product configuration is registered and `enabled: true`
+- Agent / product LLM calls succeed — but trace spans show the **platform default** model / provider was invoked, not the customer's BYO key
+- The customer expected vendor charges on their own account but is seeing platform charges (or vice versa)
+- No validation error, no auth error — the routing simply did not pick up the BYO record
+
+What can cause it:
+- The BYO record's `enabled` field is `false` (paused but not deleted)
+- The feature's `modelsConfigurationOption` is `AllModels` or `AnyModel`, the BYO config uses single-mapping shorthand, and the gateway falls back to default for any unmapped catalog model
+- An AI Trust Layer policy (tenant-wide governance) blocks the chosen vendor / model and the gateway falls back to default
+- The agent / product call uses a model the BYO config did not map (multi-mapping configs need one entry per catalog model)
+- The call hit a feature / operation group that does NOT have a BYO record at all — only some product features support BYO
+
+What to look for:
+- Trace spans naming a different provider / model than the BYO record declares
+- `enabled: false` on the BYO record
+- `modelsConfigurationOption: AllModels | AnyModel` with fewer `--mapping` entries than catalog `models[]`
+- An AOps `AITrustLayer` policy deployed on the tenant
+- The (product, operationGroupName) on the failing trace does not match any BYO record
+
+## Investigation
+
+1. **Read the failing trace** — confirm which (product, model, provider) the agent actually called and which one was actually invoked:
+
+   ```bash
+   uip traces spans get <trace-id> --output json
+   ```
+
+2. **Confirm the BYO record exists for that (product, feature) and is enabled:**
+
+   ```bash
+   uip llm-configuration byo-connections list \
+     --output json --output-filter "Data[?product=='<product>' && operationGroupName=='<feature>']"
+   ```
+
+   If the result is empty — there is no BYO record for this feature. The platform default is expected behavior, not a bug.
+   If `enabled: false` — re-enable via `byo-connections update <id> --enabled` (or via the UI).
+
+3. **Check feature shape — is this an `AllModels` / `AnyModel` feature with incomplete mapping?**
+
+   ```bash
+   uip llm-configuration byo-connections list-product-configs \
+     --product <product> --feature <feature> --output json
+   ```
+
+   Read `modelsConfigurationOption`. If it's `AllModels` or `AnyModel`, every catalog model must have a `--mapping`. Compare the BYO record's `llmConfigurations[]` against `models[]` from the catalog — any model in `models[]` without a corresponding mapping falls back to default.
+
+4. **Check whether AI Trust Layer policy is overriding routing:**
+
+   ```bash
+   uip gov aops-policy deployed-policy resolve \
+     --product AITrustLayer --license-type <type> --tenant <name> --output json
+   ```
+
+   If a deployed policy blocks the vendor or model the BYO record references, the gateway will fall back to default. Route to [`uipath-governance`](/uipath:uipath-governance) for full AOps policy investigation.
+
+5. **Trace identity match.** Cross-check the trace's `product` / `operationGroupName` fields against the BYO record's identity fields. A common mistake: registering BYO for `agents-design-eval-deploy` while the failing call is for `agents-design-eval-run` — different operation groups, different records.
+
+## Resolution
+
+- **`enabled: false`** — re-enable the BYO record:
+
+  ```bash
+  uip llm-configuration byo-connections update <id> --enabled --output json
+  ```
+
+- **`AllModels` / `AnyModel` incomplete mapping** — re-issue `update` with one `--mapping` per catalog model. `update` is full-PUT, so every mapping the customer wants in the resulting record must be supplied in the call:
+
+  ```bash
+  uip llm-configuration byo-connections update <id> \
+    --mapping '...' --mapping '...' --mapping '...' --output json
+  ```
+
+- **AI Trust Layer policy override** — route to [`uipath-governance`](/uipath:uipath-governance). Either the policy needs to be amended to allow the vendor / model, or the customer needs to pick a different BYO target.
+
+- **No BYO record for the failing feature** — register one via `byo-connections create`, or accept the platform default. See [`uipath-platform` BYO reference](/uipath:uipath-platform).
+
+- **Cannot explain routing from current state + traces** — this is the structural ceiling of the LLM Gateway CLI. There are no per-request gateway invocation logs. Open a support ticket with the failing trace ID and the BYO config ID.