@uipath/skills 1.195.0

package/skills/uipath-platform/references/integration-service/agent-workflow.md

@@ -0,0 +1,286 @@
+# Agent Workflow
+
+Follow these steps in order when the user asks to interact with an external service.
+
+## Contents
+- Progress Checklist
+- Step 1: Find the Connector
+- Step 2: Find a Connection
+- Step 3: Ping the Connection
+- Step 4: Discover Capabilities
+- Step 4T: Trigger Metadata (if trigger workflow)
+- Step 5: Resolve Reference Fields
+- Step 5a: Validate Required Fields
+- Step 6: Execute
+- Error Recovery
+- Happy-Path Example (CRUD)
+- Happy-Path Example (Triggers)
+
+## Progress Checklist
+
+Copy and track progress:
+
+```
+- [ ] Step 1: Find connector (get Key)
+- [ ] Step 2: Find connection (get Id — present options, recommend default)
+- [ ] Step 3: Ping connection (confirm Enabled)
+- [ ] Step 4: Discover capabilities (activities first, then resources)
+- [ ] Step 4T: (Triggers only) Get trigger objects → get trigger metadata
+- [ ] Step 5: Resolve reference fields (if any)
+- [ ] Step 5a: Validate all required fields have values
+- [ ] Step 6: Execute operation
+```
+
+## Step 1: Find the Connector
+
+```bash
+uip is connectors list --filter "<vendor>" --output json
+```
+
+| Outcome | Action |
+|---|---|
+| Native connector found | Use its **`Key`**. Proceed to Step 2. |
+| Not found | Fall back to HTTP connector (`uipath-uipath-http`). See [connectors.md — HTTP Connector Fallback](connectors.md#http-connector-fallback). |
+
+## Step 2: Find a Connection
+
+```bash
+uip is connections list "<connector-key>" --output json
+```
+
+- **Always present options using names, not UUIDs** — show `Name`, `Owner`, `Folder`, `State`, and `IsDefault`. Never show `Id` or `FolderKey` to the user. Recommend the default enabled connection (`IsDefault: Yes`, `State: Enabled`) but let the user confirm or choose another.
+- **HTTP fallback**: Match connection by vendor **Name** (case-insensitive substring). Present matches to user.
+- **None**: Ask user to create via `is connections create "<connector-key>"`.
+
+> **Do NOT auto-select a connection silently.** Even if there is exactly one default enabled connection, present it to the user: "I found connection **<Name>** by <Owner> in **<Folder>** folder (default, enabled). Should I use this one?"
+
+See [connections.md — Selecting a Connection](connections.md#selecting-a-connection) for full selection logic.
+
+## Step 3: Ping the Connection
+
+```bash
+uip is connections ping "<connection-id>" --output json
+```
+
+| Result | Action |
+|---|---|
+| `Enabled` | Healthy. Proceed to Step 4. |
+| Fails | Run `is connections edit <id>` to re-authenticate, then ping again. If still fails, ask user to choose another or create new. |
+
+## Step 4: Discover Capabilities
+
+**4a. Check activities first** — activities are pre-built actions (e.g., "Send Email", "Create Invoice") that may directly accomplish the task:
+
+```bash
+uip is activities list "<connector-key>" --output json
+```
+
+| Outcome | Action |
+|---|---|
+| Matching activity found for the user's task | Use the activity. See [activities.md](activities.md) for details. |
+| No matching activity | Proceed to Step 4b (resources). |
+
+**4b. List resources** — if no activity matches, discover CRUD-capable objects. **Always pass `--connection-id`** to include custom objects, and **`--operation`** to filter to the intended action:
+
+```bash
+uip is resources list "<connector-key>" \
+  --connection-id "<id>" --operation <Create|List|Retrieve|Update|Delete|Replace> --output json
+```
+
+**4c. Describe the target resource** — get field metadata for the matched object:
+
+```bash
+# All operations + all fields
+uip is resources describe "<connector-key>" "<object>" \
+  --connection-id "<id>" --output json
+
+# Filter to a single operation (reduces output size)
+uip is resources describe "<connector-key>" "<object>" \
+  --connection-id "<id>" --operation <Create|List|Retrieve|Update|Delete|Replace> --output json
+```
+
+Without `--operation`, returns a list of `availableOperations` with a hint to use `--operation`. With `--operation`, returns per-operation detail: `requestFields` (what to send), `responseFields` (what comes back), and `parameters` (path/query params). Results are cached locally — subsequent calls for the same object are instant.
+
+> **Always use `--operation`** to get field-level detail (e.g., `--operation Create`). Without it you only see which operations exist.
+
+| Describe outcome | Action |
+|---|---|
+| Returns `requestFields` + `responseFields` + `parameters` | Use field metadata. Check `required` flags and `reference` sections. Proceed to Step 5. |
+| Returns `availableOperations` (no `--operation`) | Pick the operation you need, re-run with `--operation`. |
+| Returns error or empty | **Metadata gap** — skip describe, proceed to Step 5 with inferred fields. See [resources.md — Describe Failures](resources.md#describe-failures). |
+
+**Always pass `--connection-id`** for connection-specific metadata including custom fields.
+
+## Step 4T: Trigger Metadata (if user needs trigger/event configuration)
+
+If the user's task involves **event triggers** (e.g., "when a record is created", "listen for updates"), discover trigger metadata instead of (or in addition to) CRUD resources.
+
+**4T-a. List trigger activities** to see what events the connector supports:
+
+```bash
+uip is activities list "<connector-key>" --triggers --output json
+```
+
+Present trigger activities to the user. Note the **Operation** field (e.g., CREATED, UPDATED, DELETED).
+
+**4T-b. For CREATED/UPDATED/DELETED operations** — get available trigger objects:
+
+```bash
+uip is triggers objects "<connector-key>" "<OPERATION>" \
+  --connection-id "<id>" --output json
+```
+
+Present objects to the user and let them choose.
+
+**4T-c. Get trigger field metadata** for the selected object:
+
+```bash
+uip is triggers describe "<connector-key>" "<OPERATION>" "<object-name>" \
+  --connection-id "<id>" --output json
+```
+
+**4T-d. For non-CRUD trigger operations** — skip 4T-b. Use the activity's **ObjectName** as the `<object-name>` and go directly to 4T-c.
+
+| Trigger outcome | Action |
+|---|---|
+| Trigger activities found | Present to user, proceed to 4T-b or 4T-c based on operation type |
+| No trigger activities | Connector doesn't support events. Inform user. |
+| No objects for operation | Verify operation name is uppercase (CREATED/UPDATED/DELETED). Check connector `hasEvents`. |
+
+See [triggers.md](triggers.md) for full trigger domain reference and response fields.
+
+## Step 5: Resolve Reference Fields
+
+**When describe succeeded:** Check output for reference fields. If none exist, skip to Step 5a. For each reference field: list the referenced object, collect valid IDs, and present options to the user.
+
+**When describe was unavailable (metadata gap):** Infer references from the user's request — fields ending in `Id` (e.g., `PromotionId`) typically reference the object with the matching base name (`Promotion`). List that object to resolve the ID before executing.
+
+See [reference-resolution.md — Reference Fields](reference-resolution.md#reference-fields-critical) and [reference-resolution.md — Field Dependency Chains](reference-resolution.md#field-dependency-chains).
+
+## Step 5a: Validate Required Fields
+
+After resolving references, **check every required field** against what the user provided. This is a hard gate — do NOT execute until all required fields have values. If any are missing, ask the user.
+
+See [reference-resolution.md — Validate Required Fields Before Executing](reference-resolution.md#validate-required-fields-before-executing).
+
+## Step 6: Execute
+
+```bash
+uip is resources execute <verb> "<connector-key>" "<object>" \
+  --connection-id "<id>" --body '{"field": "value"}' --output json
+```
+
+See [resources.md — Execute Operations](resources.md#execute-operations) for the verb table and options.
+
+### Pagination (list operations)
+
+`execute list` may not return all results. Check `Data.Pagination.HasMore` / `NextPageToken`, paginate with `--query "nextPage=<token>"`, stop early on match. See [resources.md#pagination](resources.md#pagination) for the full protocol, anti-patterns, and offset/limit fallback.
+
+---
+
+## Error Recovery
+
+When Step 6 returns a `Failure` result, follow this loop instead of retrying blindly or giving up. The CLI returns the HTTP status in `Message` and the raw vendor error body in `Instructions`.
+
+### Recovery Loop
+
+```
+Execute → Success? → Done
+  ↓ Failure
+Step 6a: Read the failure response
+  - Message — HTTP status (e.g., "400 Bad Request")
+  - Instructions — raw vendor error body (WHAT failed)
+  ↓
+Step 6b: Diagnose using discovery
+  - Field not found → run `is resources describe --operation <op>` to get valid field names
+  - Invalid value → run `is resources execute list` on the referenced object to get valid values
+  - Vendor 400 "X is required" but `describe` marked X `required=False` → IS schema and vendor validators disagree; treat vendor as authoritative, list the parent resource and add the missing field (e.g., Jira project-level required `components_arrayRemap_name` is `required=False` in `describe`)
+  - Auth error → run `is connections edit <id>` to re-authenticate, then ping again
+  - Scope error → inform user, connection needs broader permissions
+  - Read-only field → remove the field from --body and retry
+  ↓
+Step 6c: Correct and retry (max 2 retries)
+  - Apply the specific fix from 6b
+  - Re-execute with the corrected query/body
+  - If still failing after 2 retries → present the error, attempted fixes, and suggested manual fix to the user
+```
+
+### Rules
+
+1. **Max 2 semantic retries** — each retry must address a specific diagnosed issue. Not blind retries.
+2. **Never retry the same query unchanged** — if you can't identify what to fix, escalate to the user.
+3. **Discover before guessing** — use `describe` and `list` to find correct field names and values. Do not hallucinate.
+4. **Escalate with context** — when presenting to the user, show: original query, error message, what was tried, and the suggested manual fix.
+
+---
+
+## Happy-Path Example (CRUD)
+
+```bash
+# 1. Find connector
+uip is connectors list --filter "salesforce" --output json
+# → Key: "uipath-salesforce-sfdc"
+
+# 2. Find connection
+uip is connections list "uipath-salesforce-sfdc" --output json
+# → Id: "abc-123", IsDefault: Yes, State: Enabled
+
+# 3. Ping
+uip is connections ping "abc-123" --output json
+# → Status: Enabled
+
+# 4a. Check activities first
+uip is activities list "uipath-salesforce-sfdc" --output json
+# → No matching activity for "create contact" → fall back to resources
+
+# 4b. List resources with operation
+uip is resources list "uipath-salesforce-sfdc" \
+  --connection-id "abc-123" --operation Create --output json
+# → includes "Contact"
+
+# 4c. Describe the target resource
+uip is resources describe "uipath-salesforce-sfdc" "Contact" \
+  --connection-id "abc-123" --operation Create --output json
+# → requestFields: [{name: "LastName", required: true}, {name: "FirstName", required: false}, ...]
+# → responseFields: [{name: "Id"}, {name: "LastName"}, ...]
+
+# 5. No reference fields (no fields with "reference" section) → skip resolution
+# 5a. All required fields (LastName) have values → proceed
+
+# 6. Execute
+uip is resources execute create "uipath-salesforce-sfdc" "Contact" \
+  --connection-id "abc-123" --body '{"LastName": "Doe", "FirstName": "Jane"}' --output json
+```
+
+---
+
+## Happy-Path Example (Triggers)
+
+```bash
+# 1. Find connector
+uip is connectors list --filter "salesforce" --output json
+# → Key: "uipath-salesforce-sfdc"
+
+# 2. Find connection
+uip is connections list "uipath-salesforce-sfdc" --output json
+# → Id: "228624", IsDefault: Yes, State: Enabled
+
+# 3. Ping
+uip is connections ping "228624" --output json
+# → Status: Enabled
+
+# 4T-a. List trigger activities
+uip is activities list "uipath-salesforce-sfdc" --triggers --output json
+# → Trigger activities with Operation: CREATED, UPDATED, DELETED
+
+# 4T-b. Get objects for CREATED operation
+uip is triggers objects "uipath-salesforce-sfdc" CREATED \
+  --connection-id "228624" --output json
+# → [AccountHistory, Contact, Lead, ...]
+# → User picks "AccountHistory"
+
+# 4T-c. Get trigger metadata (fields) for AccountHistory
+uip is triggers describe "uipath-salesforce-sfdc" CREATED "AccountHistory" \
+  --connection-id "228624" --output json
+# → Returns eventParameters, filterFields, outputFields
+```

package/skills/uipath-platform/references/integration-service/connections.md

@@ -0,0 +1,256 @@
+# Connections
+
+Connections are authenticated sessions for a specific connector. They store credentials and tokens, and can be shared across automations within a folder.
+
+> Full command syntax and options: [uip-commands.md — Integration Service](../uip-commands.md#integration-service-is). Domain-specific usage patterns are shown inline below.
+
+---
+
+## Response Fields
+
+| Field | Show to user? | Description |
+|---|---|---|
+| **`Name`** | **Yes** | Display name — always use this as the primary identifier when presenting to the user (e.g., "Salesforce Prod", "bai.li") |
+| **`State`** | **Yes** | `Enabled` or other status. Only Enabled connections can be used. |
+| **`IsDefault`** | **Yes** | `Yes` or `No`. Recommend the default connection but always let the user confirm. |
+| **`Owner`** | **Yes** | Who created the connection (email) |
+| **`Folder`** | **Yes** | Folder name this connection belongs to (e.g., "Shared", "Personal") |
+| `ConnectorName` | **Yes** | Human-readable connector name (e.g., "Slack", "Salesforce") |
+| `ByoaConnection` | **Yes** | `Yes` or `No`. BYOA (Bring Your Own Account) connection — customer registered their own OAuth app with the external service. Required for some webhook triggers. |
+| `Id` | Internal | Connection UUID — use only in `--connection-id` CLI args, never show to user |
+| `ConnectorKey` | Internal | Connector key — use only in CLI args |
+| `FolderKey` | Internal | Folder UUID — use only in `--folder-key` CLI args, never show to user |
+| `ElementInstanceId` | Internal | Numeric instance ID — use only in `--element-instance-id` for `uip is webhooks config` |
+
+---
+
+## Command Syntax
+
+`<connector-key>` is a **positional argument**, not a flag:
+
+```bash
+# Correct — always pass --all-folders for discovery (see Folder Scoping below)
+uip is connections list "uipath-salesforce-slack" --all-folders --output json
+
+# WRONG — there is no --connector-key flag
+uip is connections list --connector-key "uipath-salesforce-slack"
+```
+
+**Always pass a connector key.** Running `uip is connections list` with no arg returns a noisy, paginated list across every connector in the tenant and is not a useful survey step.
+
+**Wrong key?** If the call errors with "connector not found" or returns empty unexpectedly, look up the correct key:
+
+```bash
+uip is connectors list --filter "<vendor>" --output json
+```
+
+Connector keys are prefixed by source — `uipath-<vendor>-<service>` for catalog connectors, `custom-entity-*` for tenant-built. See [connectors.md — Connector Disambiguation](connectors.md#connector-disambiguation) for the full classification ladder.
+
+---
+
+## Selecting a Connection
+
+### Connector-Specific Overrides
+
+**Before applying the auto-select rule below, check this table.** If the connector key (and node-type pattern, where listed) matches an entry, read the linked file and follow its rules. Override supersedes the auto-select rule.
+
+| Connector key | Applies when | Override action | Detail |
+|---|---|---|---|
+| `uipath-microsoft-teams` | `send-bot-*` activity node types | Ask user; warn that bot scope is required | [uipath-microsoft-teams.md → Connection Selection Override](connector-overrides/uipath-microsoft-teams.md#connection-selection-override) |
+| `uipath-salesforce-slack` | Webhook trigger node types (allow-list — excludes `button-clicked`) | Ask user; filter `--byoa` from the start | [uipath-salesforce-slack.md → Connection Selection Override](connector-overrides/uipath-salesforce-slack.md#connection-selection-override) |
+
+To add a new override, see [connector-overrides/README.md](connector-overrides/README.md).
+
+---
+
+**Auto-select rule (no prompt) — when all three hold:**
+
+- `IsDefault: Yes`
+- `State: Enabled`
+- `Folder` is the user's personal workspace
+
+Bind silently and skip the presentation steps below.
+
+Detect the user's personal workspace once per session — list all folders and filter for the personal type:
+
+```bash
+uip or folders list --all --output json
+# → Data: [{ Name, Key, Path, Description, Type, ParentKey }]
+# Filter entries where Type == "Personal"
+```
+
+Match `connection.FolderKey` against the personal workspace's `Key`. If the call returns multiple personal workspaces (admin tenant) or no match, fall through to the presentation flow.
+
+**Otherwise — present connections to the user.** Recommend the default but let the user confirm.
+
+### Folder Scoping (`--all-folders`)
+
+**Always pass `--all-folders` when discovering connections.** Without it, the CLI returns the active folder only — producing false "no connections found" results when the connection exists in another folder you can see. After the user picks a connection, capture its `FolderKey` from the response for downstream binding; do not pass `--folder-key` during discovery.
+
+- `--all-folders`: spans every folder you have access to. Works with or without a `<connector-key>` positional.
+- **Mutually exclusive with `--folder` / `--folder-key`** — passing both fails with `Result: Failure`, `Message: "Conflicting folder flags..."`, exit code 1.
+
+### For Native Connectors
+
+1. List connections for the connector across all folders:
+
+   ```bash
+   uip is connections list "<connector-key>" --all-folders --output json
+   ```
+
+2. Present all enabled connections to the user using **Name, Owner, and Folder** (never UUIDs), **recommending** the default (`IsDefault: Yes`, `State: Enabled`):
+   - "I found these connections: 1) **Salesforce Prod** by user@example.com (default, enabled, Shared folder) ← recommended 2) **Salesforce Dev** by admin@example.com (enabled, Shared folder). Which should I use?"
+3. If only one enabled connection exists, still confirm: "I found connection **<Name>** by <Owner> in **<Folder>** folder (default, enabled). Should I use this one?"
+4. **Verify health — ping after every selection** (auto-select and user-confirmed alike):
+
+   ```bash
+   uip is connections ping "<connection-id>" --output json
+   ```
+
+   If ping fails or reports not Enabled, follow step 5.
+
+5. If not enabled (from list `State` or ping result) → prompt user to re-authenticate via `is connections edit <id>`, then re-ping.
+
+6. **No connections in step 1 — bypass the cache before concluding none exist:**
+   1. Retry with `--refresh`:
+      ```bash
+      uip is connections list "<connector-key>" --all-folders --refresh --output json
+      ```
+   2. If still empty, prompt user to create one via `uip is connections create "<connector-key>"`.
+
+### For BYOA Connections (Webhook Triggers)
+
+BYOA (Bring Your Own Account) connections use an OAuth app the customer registered with the external service (e.g., a Slack app they own). Some webhook triggers require BYOA; many do not. **The requirement is per event object, not per connector** — read it from the `triggers objects` response.
+
+**Decision flow:**
+
+1. Get any enabled connection — needed only as `--connection-id` for the next call:
+
+   ```bash
+   uip is connections list "<connector-key>" --all-folders --output json
+   ```
+
+2. Query trigger objects and read the `byoaConnection` flag for the matching event:
+
+   ```bash
+   uip is triggers objects "<connector-key>" "<OPERATION>" \
+     --connection-id "<id>" --output json
+   ```
+
+3. **If `byoaConnection: true`** — the connection from step 1 is not usable. Filter to BYOA across all folders:
+
+   ```bash
+   uip is connections list "<connector-key>" --byoa --all-folders --output json
+   ```
+
+   If empty, retry with `--refresh` to bypass the CLI cache:
+
+   ```bash
+   uip is connections list "<connector-key>" --byoa --all-folders --refresh --output json
+   ```
+
+   If still empty, **stop and tell the user**: "This trigger requires a BYOA connection for `<connector-key>`. None found. Create one in the Integration Service portal or with `uip is connections create "<connector-key>"`, then re-run."
+
+4. **If `byoaConnection: false`** — use the connection from step 1. Verify health with `uip is connections ping "<id>" --output json`.
+
+> Connector-specific OAuth-app setup instructions (e.g., what permissions a Slack app needs) come from the trigger's `design.textBlocks` field in the `triggers objects` response. Surface that text to the user verbatim — do not invent service-specific guidance.
+
+For webhook URL retrieval after the trigger is configured, see [triggers.md — Webhook URL Retrieval](triggers.md#webhook-url-retrieval).
+
+### For HTTP Fallback
+
+1. List connections for `uipath-uipath-http`
+2. Look for a connection whose **Name** contains the target vendor (case-insensitive substring match, e.g., "Apify" matches "Apify", "Apify - Prod", "My Apify Connection")
+3. Present matches to the user. If multiple matches → let them choose.
+4. If no match → present all existing HTTP connections and ask the user to choose, or offer to create a new one
+
+> **Note:** Name-based matching is best-effort. If connection names don't follow vendor naming conventions, present all HTTP connections to the user.
+
+---
+
+## Folder Scoping
+
+`uip is connections list <connector-key>` defaults to filtering by the **current** folder context — results from other folders (including the user's personal workspace) are silently excluded. Empty response on the filtered side looks like:
+
+```json
+{"Message":"No connections found for connector '<connector-key>'."}
+```
+
+even though a connection exists in another folder.
+
+**Cross-folder pattern** — pass `--folder` explicitly:
+
+```bash
+uip is connections list "<connector-key>" --folder "<folder-name-or-key>" --output json
+```
+
+**Enumerate every folder** — iterate folders and list per folder:
+
+```bash
+uip or folders list --output json
+# → for each folder, call:
+uip is connections list "<connector-key>" --folder "<folder-name-or-key>" --output json
+```
+
+> If the user reports "connection exists in my personal workspace but CLI can't see it", suspect default folder filtering — re-list with `--folder` set to that workspace before creating a new connection.
+
+---
+
+## Identifying a JDBC Connection's Target DB
+
+For the JDBC gateway connector (`uipath-uipath-jdbc`, "Database Hub"), `connections list` does **not** expose `jdbcUrl` or `driverClass` — config is intentionally hidden. The only signal for "what DB does this JDBC connection point to?" is the connection **`name`**.
+
+Match case-insensitively (weak signal — surface as "likely &lt;DB&gt;", never "is &lt;DB&gt;"):
+
+| DB | Substrings in `connection.name` |
+|---|---|
+| Snowflake | `snowflake`, `sf` |
+| Databricks | `databricks`, `dbx` |
+| Postgres | `postgres`, `postgresql`, `pg` |
+| MySQL | `mysql` |
+| SQL Server | `sqlserver`, `mssql` |
+| Oracle | `oracle` |
+| Redshift | `redshift` |
+| BigQuery | `bigquery`, `bq` |
+
+If the user explicitly named a connection in their prompt (e.g. "use the `pat_databricks` connection"), that overrides name-matching — bind it directly.
+
+Used by the [connectors.md — JDBC Gateway](connectors.md#jdbc-gateway--database-sql-intent) decision matrix.
+
+---
+
+## Getting a Connection's Vendor Base URL
+
+`uip is connections base-url <connection-id>` returns the exact vendor base URL the connection uses for proxied calls (e.g., raw `http-request` calls, Managed HTTP Request in connector mode). Manual-mode invocations don't use it. The connection must be Enabled.
+
+```bash
+uip is connections base-url "<connection-id>" --output json
+# → { "Result": "Success", "Code": "ConnectionBaseUrl",
+#     "Data": { "ConnectionId": "<id>", "BaseUrl": "https://..." } }
+```
+
+Examples across connectors:
+
+| Connector | Returned `BaseUrl` |
+|---|---|
+| `uipath-atlassian-jira` | `https://api.atlassian.com/ex/jira/<site-id>/rest/api/2` |
+| `uipath-microsoft-outlook365` | `https://graph.microsoft.com/v1.0` |
+| `uipath-uipath-marketo` | `https://<account>.mktorest.com/rest` |
+
+Use this whenever you need to compose a relative `url` for `http-request` or Managed HTTP Request in connector mode. See [http-request.md](http-request.md).
+
+---
+
+## Scope-Related Errors
+
+A connection can be `Enabled` but lack optional OAuth scopes needed for specific activities. This typically surfaces as a **403 Forbidden** error during execute.
+
+**Symptoms:**
+- Connection pings successfully (`State: Enabled`)
+- Execute fails with 403 or a vendor-specific "insufficient permissions" error
+- The same operation works with a different connection that has broader scopes
+
+**Recovery:**
+1. Inform the user that the connection may need broader OAuth scopes for this activity
+2. Re-authorize with broader scopes: `uip is connections edit <connection-id>`
+3. After re-auth, ping again to verify, then retry the operation

package/skills/uipath-platform/references/integration-service/connector-overrides/README.md

@@ -0,0 +1,45 @@
+# Connector Overrides
+
+Per-connector override files. Each `<connector-key>.md` aggregates all overrides that apply to one connector, organized as H2 sections by override type. Currently one override type is defined (Connection Selection); more may be added.
+
+---
+
+## Connection Selection Override
+
+Connector-specific carve-outs from the auto-select rule in [../connections.md — Selecting a Connection](../connections.md#selecting-a-connection). 99% of connectors follow the default rule (silent auto-select when the default enabled connection lives in the user's personal workspace). Entries here are operations where the default rule fails because the bound connection cannot satisfy operation-specific requirements (e.g., bot scope, BYOA).
+
+### How the override fires
+
+1. Extract the connector key from the node type — `uipath.connector.<key>.<op>`, `uipath.connector.trigger.<key>.<op>`.
+2. Look up the key in the Connector-Specific Overrides table in [../connections.md](../connections.md#connector-specific-overrides).
+3. If the entry's scope (node-type pattern or operation list) matches, read the linked file and follow its rules. Override supersedes the auto-select rule.
+4. No match → proceed to the auto-select rule.
+
+### File schema (Connection Selection section of a connector file)
+
+The `## Connection Selection Override` section of a connector file follows this shape:
+
+- **`## Connection Selection Override`** — H2 heading for this override type.
+- **`### When this override applies`** — node-type pattern or operation list. Multiple scopes on one connector → H4 sub-sections.
+- **`### Override behavior`** — auto-select disabled (default for all overrides), list filter (optional), post-selection verification (optional), recovery on empty.
+- **`### Why`** — one-paragraph rationale.
+- **`### User-facing presentation`** — exact prefix wording the agent uses when presenting the list.
+
+The connector file's H1 is `# <Connector Display Name> — Connector Overrides` with `**Connector key:** <kebab-case-key>` directly below.
+
+---
+
+## How to add a new override
+
+1. Add `<connector-key>.md` in this directory using the schema above.
+2. Add a row to the Connector-Specific Overrides table in [../connections.md](../connections.md#connector-specific-overrides).
+3. Specify the node-type pattern precisely — overrides are operation-scoped, not blanket connector-wide.
+
+## File naming
+
+`<connector-key>.md` — kebab-case connector key as it appears in `uip is connectors list`. Multiple override scopes for one connector live in the same file as H4 sub-sections under the relevant H3.
+
+## Existing overrides
+
+- [uipath-microsoft-teams.md](uipath-microsoft-teams.md) — `send-bot-*` activities require bot scope.
+- [uipath-salesforce-slack.md](uipath-salesforce-slack.md) — Trigger node types require BYOA.

package/skills/uipath-platform/references/integration-service/connector-overrides/uipath-microsoft-teams.md

@@ -0,0 +1,29 @@
+# Microsoft Teams — Connector Overrides
+
+**Connector key:** `uipath-microsoft-teams`
+
+## Connection Selection Override
+
+### When this override applies
+
+Send-bot-* activity node types:
+
+- `uipath.connector.uipath-microsoft-teams.send-bot-channel-message`
+- `uipath.connector.uipath-microsoft-teams.send-bot-direct-message`
+
+Non-bot Teams activities (`send-channel-message`, `send-individual-chat-message`, `create-channel`, etc.) follow the default auto-select rule.
+
+### Why
+
+Send-bot-* activities post messages from a Teams bot identity, not from the user. The connection must be authorized with the Teams bot scope. The personal-workspace default connection is typically authorized without that scope, so silent auto-select binds a connection that fails at runtime with a 403. Asking the user up front lets them pick a bot-scoped connection (or re-authorize the default).
+
+### Behavior
+
+- **Auto-select:** disabled — always present connections to the user.
+- **List filter:** none. Use the standard `uip is connections list "uipath-microsoft-teams" --all-folders --output json`.
+- **Post-selection verification:** ping. No CLI flag exposes bot-scope state at bind time — verification is deferred to runtime (a 403 surfaces missing scope, then the [Scope-Related Errors](../connections.md#scope-related-errors) recovery applies).
+- **Recovery on empty:** standard native-connector recovery (`--refresh`, then prompt to create via `uip is connections create "uipath-microsoft-teams"` — user must consent to the Teams bot scope during OAuth).
+
+### User-facing presentation
+
+Prefix the connection list with: "These activities post messages from a Teams **bot** identity, so the connection needs the bot scope authorized. Pick a connection that has it. If none does, re-authorize via `uip is connections edit <id>` and grant the bot scope during OAuth."

package/skills/uipath-platform/references/integration-service/connector-overrides/uipath-salesforce-slack.md

@@ -0,0 +1,43 @@
+# Slack — Connector Overrides
+
+**Connector key:** `uipath-salesforce-slack`
+
+## Connection Selection Override
+
+### When this override applies
+
+Slack webhook trigger node types — explicit allow-list (not a blanket `.trigger.*` wildcard):
+
+- `uipath.connector.trigger.uipath-salesforce-slack.message-received-in-slack`
+- `uipath.connector.trigger.uipath-salesforce-slack.channel-message-posted`
+- `uipath.connector.trigger.uipath-salesforce-slack.chat-message-posted`
+- `uipath.connector.trigger.uipath-salesforce-slack.chat-message-updated`
+- `uipath.connector.trigger.uipath-salesforce-slack.reaction-added-in-slack`
+- `uipath.connector.trigger.uipath-salesforce-slack.member-joined-a-slack-channel`
+- `uipath.connector.trigger.uipath-salesforce-slack.channel-created-in-slack`
+- `uipath.connector.trigger.uipath-salesforce-slack.webhook-event-received-real-time-`
+
+**Override exceptions:**
+
+- `uipath.connector.trigger.uipath-salesforce-slack.button-clicked` — the BYOA requirement depends on the app/configuration. Follow the default native-connector flow, then the existing BYOA detection via `triggers objects` ([../connections.md — For BYOA Connections](../connections.md#for-byoa-connections-webhook-triggers)) handles it.
+- Non-trigger Slack activities (`send-message-to-channel`, `create-channel`, etc.) follow the default auto-select rule.
+
+### Why
+
+Slack webhook triggers require a Bring-Your-Own-App (BYOA) connection — backed by a Slack app the customer registered with their own OAuth credentials. The personal-workspace default connection is not guaranteed to be BYOA, so silent auto-select can bind a non-BYOA connection that the runtime rejects when the trigger fires.
+
+### Behavior
+
+- **Auto-select:** disabled — always present connections to the user.
+- **List filter:** `--byoa` from the start. Do not call `triggers objects` first to discover the BYOA requirement — every Slack trigger needs BYOA.
+
+  ```bash
+  uip is connections list "uipath-salesforce-slack" --byoa --all-folders --output json
+  ```
+
+- **Post-selection verification:** ping the chosen connection.
+- **Recovery on empty:** follow the BYOA empty-list recovery in [../connections.md — For BYOA Connections](../connections.md#for-byoa-connections-webhook-triggers) (`--byoa --all-folders --refresh`, then prompt to create a BYOA connection).
+
+### User-facing presentation
+
+Prefix the connection list with: "Slack triggers require a **BYOA** (Bring-Your-Own-App) connection — one backed by a Slack app you registered yourself. Listing only BYOA connections. Pick one, or create a new BYOA connection if none exist."