@uipath/skills 1.195.0

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

@@ -0,0 +1,121 @@
+# Connectors
+
+Connectors are pre-built integrations to external applications. Each connector has a unique key (e.g., `uipath-salesforce-sfdc`, `uipath-servicenow-servicenow`). A connector contains **connections** (authenticated sessions), **activities** (pre-built actions), and **resources** (object types with CRUD operations).
+
+> 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 show this to the user (e.g., "Salesforce", "Slack") |
+| **`Key`** | **Yes** | Unique key used in all subsequent commands (e.g., `uipath-salesforce-sfdc`) — also shown to users since it's human-readable |
+| `Active` | **Yes** | Whether the connector is active |
+| `DapCompatible` | Optional | Whether it supports Data Access Policy |
+| `Id` | Internal | Connector UUID — never show to the user |
+
+---
+
+## HTTP Connector Fallback
+
+When no native connector exists for a vendor, use the HTTP connector (`uipath-uipath-http`) to call REST APIs directly.
+
+```bash
+# Search for vendor → not found → fall back to HTTP connector
+uip is connectors list --filter "apify" --output json
+# → No connectors found
+
+# List HTTP connections and look for one named after the vendor
+uip is connections list "uipath-uipath-http" --output json
+```
+
+The HTTP connector supports generic HTTP requests (GET, POST, PUT, PATCH, DELETE) to any REST API. The connection stores the authentication configuration (API keys, OAuth tokens, base URL).
+
+### When to use HTTP fallback
+
+- The vendor is not in the connector catalog
+- The vendor has a REST API
+- You need to call a custom/internal API
+
+### HTTP request format
+
+The HTTP connector has a single resource: `http-request`.
+
+```bash
+uip is resources run create "uipath-uipath-http" "http-request" \
+  --connection-id "<id>" \
+  --body '{"method": "GET", "url": "https://api.example.com/v2/resource"}' \
+  --output json
+```
+
+Body fields:
+
+| Field | Description |
+|---|---|
+| `method` | HTTP method: GET, POST, PUT, PATCH, DELETE |
+| `url` | Full URL to call |
+| `headers` | Optional request headers (object) |
+| `query` | Optional query parameters (object) |
+| `body` | Optional request body (for POST/PUT/PATCH) |
+
+---
+
+## Connector Disambiguation
+
+When a connector/registry search returns multiple results for the same user intent, **never silently pick the first match**. Apply this short ladder before binding:
+
+1. **Classify each result by connector key prefix.**
+   - `uipath-<vendor>-<service>` = **catalog** — UiPath-shipped IS catalog connector. Default choice.
+   - `custom-entity-*` = **custom** — tenant-built via Connector Builder. Use only when no catalog match exists, or the user explicitly names one.
+   - `uipath-mock-*` = **mock** — internal dev artifact. Filter from results, treat as if absent.
+
+   Connector keys typically appear inside richer activity / node-type strings such as `uipath.connector.<key>.<op>`, `uipath.connector.trigger.<key>.<op>`, or `uipath.agent.resource.tool.connector.<key>.<op>` — extract the `<key>` segment for classification.
+
+2. **Intent-match by reading each result's `Description`.** Drop catalog candidates whose described operation does not match the user's intent. Example: a "pull user data from Databricks" prompt drops `uipath-databricks-databricks.query-a-serving-endpoint` (AI inference) and keeps `uipath-uipath-jdbc.execute-query-synchronously` (SQL).
+
+3. **Count what's left after steps 1–2.**
+   - 1 catalog candidate → take it silently.
+   - >1 catalog candidates with different keys → AskUser. Use option label `<DisplayName> · <connector-key>` and put each candidate's `Description` in the option description — that text is the user's primary signal.
+   - 0 catalog, only custom → STOP. Surface in the consumer skill's Open Questions. Never silently bind to a custom-entity connector.
+
+4. **Lock the choice** in the consumer skill's planning notes. Never re-derive per node within the same flow / agent / run.
+
+For the database-SQL special case (a single intent satisfied by either a per-vendor catalog connector or the JDBC gateway), see [JDBC Gateway — Database SQL Intent](#jdbc-gateway--database-sql-intent) below.
+
+---
+
+## JDBC Gateway — Database SQL Intent
+
+When the user names a database (Snowflake, Databricks, Postgres, Oracle, SQL Server, Redshift, MySQL, BigQuery, etc.) for a SQL operation, two paths can satisfy the same intent:
+
+1. **Native database connector** — e.g. `uipath-snowflake-snowflake`. Vendor-specific. May not expose SQL at all (e.g. `uipath-databricks-databricks` only exposes AI serving endpoints — its SQL search hit is the JDBC gateway, not the native key).
+2. **JDBC gateway** — `uipath-uipath-jdbc` (Database Hub) with `Execute Query Synchronously` plus `*-record` CRUD activities, fronting any JDBC-compatible DB via tenant-registered connections.
+
+> **Lifecycle**: read each candidate's lifecycle from the consumer skill's registry / discovery response (`Tags` / status field) and surface it to the user when binding. The JDBC gateway has historically been PREVIEW — do not assume GA. Hard-coded lifecycle labels in this doc would rot; always defer to the registry.
+
+### Discovery
+
+A keyword search by DB name (run via the consumer skill's discovery API) returns BOTH paths because the gateway's `Description` text names every supported DB. **Do not dismiss `uipath-uipath-jdbc.*` results** because the key looks unrelated — the cross-reference is registry-surfaced.
+
+For the JDBC connection-side probe (platform-native, same regardless of consumer):
+
+```bash
+uip is connections list "uipath-uipath-jdbc" --output json
+```
+
+### Connection identity
+
+For the rules on inferring a JDBC connection's target DB from its `name` (since `jdbcUrl` / `driverClass` are not exposed by `connections list`), and the explicit-user-named-connection override, see [connections.md — Identifying a JDBC Connection's Target DB](connections.md#identifying-a-jdbc-connections-target-db). The Decision matrix below assumes each JDBC connection has been classified as "name-matched" or "ambiguously named" using that guide.
+
+### Decision
+
+After dropping intent-mismatched candidates per [Connector Disambiguation](#connector-disambiguation) above:
+
+| Confident paths remaining | Action |
+|---|---|
+| Exactly one (native SQL connector, OR a single name-matched JDBC connection) | Take it silently. Disclose lifecycle from the discovery response. |
+| Native SQL connector AND a name-matched JDBC connection | **AskUser**. Option labels: `Native <DB> · <key>` / `JDBC gateway · <name> — likely <DB>`. Append the registry lifecycle (e.g. ` · PREVIEW`) per option. |
+| No native, only ambiguously-named JDBC connections (e.g. `DH-Conn-001`) | **AskUser**, flag each option as "purpose unknown, please confirm". |
+| No native and no JDBC connection | Fall back via the consumer skill's HTTP-fallback or placeholder patterns, or instruct the user to create a JDBC connection (`uip is connections create "uipath-uipath-jdbc"`). Do not silently STOP. |

package/skills/uipath-platform/references/integration-service/http-request.md

@@ -0,0 +1,116 @@
+# Managed HTTP Request - Concept + `http-request` Authoring Helper
+
+This doc covers two things every agent authoring a Managed HTTP Request needs to know:
+1. What Managed HTTP Request is, and the two modes it runs in.
+2. How to use the `http-request` CLI command to fill in the values Managed HTTP Request needs.
+
+Consumers: Maestro Flow, Maestro BPMN, API Workflows, Case Management, etc. Each consumer surfaces Managed HTTP Request differently (as a node, an activity, a tool call, …) and uses its own type identifier and configuration schema - the concept and the rules below are the same. For the exact node/activity type identifier and how to configure it, see your consumer's own authoring docs.
+
+## What is Managed HTTP Request?
+
+A built-in way to make an HTTP call from a UiPath automation when there's no curated activity for it. Runs in two modes - **connector mode** and **manual mode**:
+
+| Mode | When | `url` | Auth |
+|---|---|---|---|
+| **Connector** | Connector exists for the vendor but the specific operation is not curated | **Relative** to the connection's vendor base URL | Applied automatically from the bound connection |
+| **Manual** | No connector exists, or public API with no auth needed | **Full URL** | You supply all headers, including auth |
+
+## Connector-Mode Rules
+
+- `url` must be **relative**. Wrong: `"url": "https://example.atlassian.net/rest/api/2/issue"`. Right: `"url": "/issue"`.
+- The connection's base URL is prepended automatically.
+- The auth header is applied automatically - do not set `Authorization`.
+- Get the exact vendor base URL for a connection via (so you can compose the relative `url` correctly):
+
+```bash
+uip is connections base-url "<connection-id>" --output json
+# → { "Data": { "BaseUrl": "https://api.atlassian.com/ex/jira/<site>/rest/api/2" } }
+```
+
+## Manual-Mode Rules
+
+- `url` is the **fully qualified URL**.
+- No connection is bound - you supply everything needed to make the call: URL, headers (including auth if needed), query params, and body.
+
+## Authoring Helper: `http-request` command
+
+Authoring a Managed HTTP Request payload requires concrete vendor values - IDs, field names, endpoint paths. Use `http-request` command to call any vendor API directly through the connection - same auth, same base URL the Managed HTTP Request will use at runtime.
+
+### When the Agent Needs `http-request` command
+
+Use `http-request` command to resolve any of the following before authoring the Managed HTTP Request payload:
+
+- **Identifier lookups.** Resolve a human-friendly name to the vendor's internal ID. Examples: project key from a project name, channel ID from a channel name, user ID from email/name, custom-field IDs.
+- **Required and optional fields** the vendor expects in the request body
+- **Endpoint paths, query params, pagination tokens** before committing to a payload
+- **Vendor error responses** for unsupported parameters or permissions
+
+### Command
+
+```bash
+uip is resources run create "<connector-key>" http-request \
+  --connection-id "<id>" \
+  --body '{"method":"<method>","url":"<relative-path>"}' --output json
+```
+
+| `body` field | Required | Notes |
+|---|---|---|
+| `method` | Yes | Uppercase HTTP verb |
+| `url` | Yes | **Relative** to the connection's vendor base URL (same convention as Managed HTTP Request connector mode) |
+| `headers` | No | Extra headers. Do NOT set `Authorization`. |
+| `body` | For POST/PUT/PATCH | **Stringified** JSON. Only `application/json` is supported today - non-JSON content types (form-urlencoded, XML, multipart, plain text) are not. |
+
+`http-request` command uses the same connection that Managed HTTP Request will use at runtime, so auth + base URL are applied automatically - same convention as Managed HTTP Request itself.
+
+### Read-Only During Authoring
+
+When using the `http-request` command, use `GET` method only, as `POST` / `PATCH` / `PUT` / `DELETE` mutate vendor state, often irreversibly.
+
+Exception: the user asks you to actually run the operation now, not just author it.
+
+## Worked Example: Jira Create Issue
+
+User wants to create a Jira issue. Before composing the Managed HTTP Request payload, the agent needs the project key, issue type ID, and required custom fields. All resolved via `http-request` command GETs.
+
+```bash
+# 1. Resolve project key (user said "Engineering project").
+uip is resources run create uipath-atlassian-jira http-request \
+  --connection-id "<id>" \
+  --body '{"method":"GET","url":"/project/search?query=Engineering"}' --output json
+# → key "ENG"
+
+# 2. For project ENG, get available issue types + required custom fields.
+uip is resources run create uipath-atlassian-jira http-request \
+  --connection-id "<id>" \
+  --body '{"method":"GET","url":"/issue/createmeta?projectKeys=ENG&expand=projects.issuetypes.fields"}' \
+  --output json
+# → match "Task" → id "10001"; required custom field: customfield_10010 (Story Points)
+```
+
+3. (Optional) Confirm resolved values with the user.
+
+4. Compose the Managed HTTP Request payload. The actual configuration command and schema are consumer-specific — the request body Managed HTTP Request will send to Jira at runtime looks like:
+
+```json
+{
+  "method": "POST",
+  "url": "/issue",
+  "body": {
+    "fields": {
+      "project": { "key": "ENG" },
+      "issuetype": { "id": "10001" },
+      "summary": "Fix coder evals",
+      "customfield_10010": 3
+    }
+  }
+}
+```
+
+All steps 1-2 are GETs because we are in the authoring phase. The POST to `/issue` happens at runtime, performed by Managed HTTP Request - never by CLI during authoring.
+
+## Critical Rules
+
+1. **Do NOT set the `Authorization` header manually in connector mode.** Auth is applied automatically by the connection. Setting it yourself can leak or override the token.
+2. **Do NOT use an absolute URL in connector-mode `url`.** Wrong: `"url": "https://example.atlassian.net/rest/api/2/project"`. Right: `"url": "/project"`.
+3. **Do NOT issue writes via CLI during authoring.** See "Read-Only During Authoring" above.
+4. **Do NOT guess the base URL.** Use `uip is connections base-url <connection-id>`.

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

@@ -0,0 +1,83 @@
+# Integration Service
+
+Interact with external services through UiPath Integration Service — discover connectors, manage connections, and execute operations via the `uip` CLI.
+
+> Full command syntax and options: [uip-commands.md — Integration Service](../uip-commands.md#integration-service-is). Domain-specific usage patterns are shown inline in each reference file.
+
+## Prerequisites
+
+- `uip` must be authenticated (`uip login`)
+- Correct folder context must be set if using folder-scoped connections (`--folder-key`)
+
+## Core Principles
+
+1. **Always follow the workflow** — Connector → Connection → Ping → Discover → Resolve References → Execute
+2. **Never fabricate IDs or values** — Always list real data (command output) before using IDs, keys, or names. Select from command output only.
+3. **Resolve reference fields before create/update** — Describe output includes `referenceFields` — list the referenced object to get valid IDs before executing.
+4. **Use `--refresh` once if results are unexpected** — The `list` subcommands cache locally. Retry **once** with `--refresh` when: results are empty, a recently created item is missing, or the user says data should exist. If still empty after refresh, inform the user the data does not exist — do not loop.
+5. **Always ping** — Verify every connection before use, even if it reports "Enabled"
+6. **Always ask, never auto-select** — Always present connections and reference values to the user for confirmation, even if there is only one option. Recommend the default but let the user confirm.
+7. **Always use `--output json`** for commands whose output you need to parse or act on.
+8. **Use `--operation` on describe** — `is resources describe` returns a compact summary of all operations and fields. Use `--operation Create` to filter to just that operation and reduce output size.
+
+---
+
+## Navigation
+
+| When to load | File | For |
+|---|---|---|
+| Always (first) | This file | Principles, routing, error recovery |
+| Any IS task | [agent-workflow.md](agent-workflow.md) | Step-by-step workflow with checklist |
+| Step 1: connector not found | [connectors.md](connectors.md) | HTTP fallback, connector response fields |
+| Step 2: connection selection | [connections.md](connections.md) | Selection logic (native + HTTP), response fields |
+| Step 4: discover activities | [activities.md](activities.md) | Activity discovery, trigger activities, activities vs resources |
+| Steps 4–6: resources | [resources.md](resources.md) | Describe, execute CRUD, pagination, vendor error recovery |
+| Step 5: resolve references | [reference-resolution.md](reference-resolution.md) | Simple refs, dependency chains, inferring, required field validation |
+| Managed HTTP Request authoring | [http-request.md](http-request.md) | Concept, two modes (connector / manual), `http-request` CLI helper, worked example |
+| Trigger metadata | [triggers.md](triggers.md) | Trigger objects, trigger field metadata, trigger workflow |
+
+---
+
+## Display Preferences — Names Over UUIDs
+
+**Always show human-readable names when presenting information to the user. Never surface raw UUIDs or internal keys unless the user explicitly asks for technical details.**
+
+UUIDs and keys are internal identifiers for CLI commands — the agent must use them in `--connection-id`, `--folder-key`, etc., but must **never** relay them to the user as the primary identifier.
+
+| CLI field | Show to user | Use internally (CLI args) |
+|---|---|---|
+| `Name` | **Yes** — always the primary identifier | — |
+| `Id` | No — use `Name` instead | `--connection-id` |
+| `ConnectorName` | **Yes** — show the vendor name | — |
+| `ConnectorKey` | No — use `ConnectorName` instead | first arg to `is connections list` |
+| `Folder` | **Yes** — show the folder name | — |
+| `FolderKey` | No — use `Folder` instead | `--folder-key` |
+| `Owner` | **Yes** — show the owner email | — |
+
+### When confirming a selection
+
+- **Good**: "Using connection **bai.li** (Slack, default, enabled) in **Shared** folder."
+- **Bad**: "Using connection fb06f30e-cde8-4e4a-a534-29cb485971d4."
+- **Good**: "Found 2 connections in the **Shared** folder."
+- **Bad**: "Found 2 connections in folder 692bbf4e-5754-4bdc-8ec6-d8e3a986dea2."
+
+## How to Present Choices
+
+When multiple options exist, present them clearly using **names, not UUIDs**:
+- **Connections**: "Which connection? 1) **Salesforce Prod** (default, enabled, Shared folder) 2) **Salesforce Dev** (enabled, Shared folder)"
+- **Reference fields**: "Which department? 1) Engineering 2) Sales"
+
+## Error Recovery
+
+| Problem | Recovery |
+|---|---|
+| Ping returns non-enabled | Run `is connections edit <id>` to re-authenticate, then ping again. If still fails, ask user to choose another connection or create new. |
+| List returns empty after `--refresh` | Inform user the data does not exist. Do not retry. Suggest checking permissions or folder context. |
+| Reference field lookup returns empty | Inform user — the referenced object has no records. Ask if they want to create one or use a different value. |
+| Execute fails with error | Read `Instructions` — the CLI passes through the raw vendor error body. Use it to diagnose and fix. See [agent-workflow.md — Error Recovery](agent-workflow.md#error-recovery). |
+| Describe returns error | Metadata gap — skip describe, attempt execute directly. See [resources.md — Describe Failures](resources.md#describe-failures). |
+| Create fails with read-only field error | Parse the vendor error in `Instructions` for the field name. Remove it from `--body` and retry. |
+| Connector not found | Fall back to HTTP connector (`uipath-uipath-http`). See [connectors.md](connectors.md#http-connector-fallback). |
+| No trigger objects for operation | Check operation name (CREATED/UPDATED/DELETED, uppercase). Verify connector supports events (`hasEvents` in connector list). See [triggers.md](triggers.md). |
+| Trigger metadata empty | Check object name matches exactly from `triggers objects` output. Try with `--connection-id` for custom fields. See [triggers.md](triggers.md). |
+| Execute fails with 403 (scope) | Connection is Enabled but lacks optional scopes for this activity. Re-authorize with broader scopes via `is connections edit <id>`. See [connections.md](connections.md). |

package/skills/uipath-platform/references/integration-service/reference-resolution.md

@@ -0,0 +1,316 @@
+# Reference Resolution
+
+How to resolve reference fields — fields whose values must be looked up from another resource before create/update operations.
+
+> Full command syntax and options: [uip-commands.md — Integration Service](../uip-commands.md#integration-service-is). Domain-specific usage patterns are shown inline below.
+
+## Contents
+- Reference IDs Are Connection-Scoped (CRITICAL)
+- Reference Fields (CRITICAL)
+- Scope Filtering (CRITICAL)
+- Search References (filterPattern)
+- Field Dependency Chains
+- Inferring References Without Describe
+- Static Reference-Value Labeling
+- Validate Required Fields Before Executing
+
+---
+
+## Reference IDs Are Connection-Scoped (CRITICAL)
+
+Every reference ID resolves only within the account authenticated by the connection used to resolve it. A `MailFolder` ID from one Outlook mailbox is invalid in another. A Slack channel ID from one workspace is invalid in another. A Jira project ID from one Atlassian site is invalid in another.
+
+**Never carry a reference ID from one flow, one connection, or one session into another.** Always re-run `uip is resources run list` against the `--connection-id` bound to the current flow — even if you believe you already know the ID from a prior task or earlier in the same session.
+
+A reused reference ID:
+- Passes `uip is resources describe` / `node configure` / `flow validate` cleanly (no API call checks the value against the connection).
+- Faults at runtime when the connector tries to use the ID against a mailbox/workspace/site that does not contain it.
+- Surfaces as a silent fault or generic "no matching resource" error — hard to diagnose without tracing back to the authoring step.
+
+**Rule:** resolve every reference ID fresh, against the current connection, every time. Treat any ID from your context or memory as unverified until re-listed.
+
+---
+
+## Reference Fields (CRITICAL)
+
+Some fields in the describe `requestFields` have a `reference` section — their value must be looked up from another resource before executing.
+
+### Reference structure
+
+```json
+{
+  "name": "channel",
+  "type": "string",
+  "displayName": "Channel name/ID",
+  "required": true,
+  "reference": {
+    "objectName": "curated_channels?types=public_channel,private_channel",
+    "lookupNames": ["name", "id"],
+    "lookupValue": "id",
+    "path": "/curated_channels?fields=id,name"
+  }
+}
+```
+
+| Property | Meaning |
+|---|---|
+| **`reference.objectName`** | The resource to list (use as `<object>` in `execute list`). May include query params. |
+| **`reference.lookupNames`** | Fields to match the user's input against (e.g., match "general" against `name`) |
+| **`reference.lookupValue`** | The field to extract as the resolved value (e.g., `id`) |
+| **`reference.path`** | The API path — use `reference.objectName` for the list call |
+| **`reference.filterPattern`** | Search endpoint pattern — substitute the user's input into `{filter}` and pass as `--query`. See [Search References](#search-references-filterpattern). |
+| **`reference.childPath`** | Scoped child path — used for drill-down references (e.g., folder subfolders) |
+
+### Resolution workflow
+
+```bash
+# 1. Describe → find fields with "reference" in requestFields
+uip is resources describe "<connector-key>" "<resource>" \
+  --connection-id "<id>" --operation Create --output json
+
+# 2. For each reference field, list the referenced object
+#    Use reference.objectName as the object name (including any query params)
+uip is resources run list "<connector-key>" "<reference.objectName>" \
+  --connection-id "<id>" --output json
+
+# 3. Match the user's input against reference.lookupNames in the results
+#    Extract reference.lookupValue as the resolved ID
+
+# 4. Execute with resolved IDs (not display names)
+uip is resources run create "<connector-key>" "<resource>" \
+  --connection-id "<id>" --body '{"channel": "<resolved-id>"}' --output json
+```
+
+### Example: Resolving a Slack channel (list reference)
+
+User says: "Send a message to #general"
+
+1. **Describe** returns `channel` field with `reference.objectName: "curated_channels?types=public_channel,private_channel"`
+2. **List** the referenced object:
+   ```bash
+   uip is resources run list "uipath-salesforce-slack" \
+     "curated_channels?types=public_channel,private_channel" \
+     --connection-id "<id>" --output json
+   ```
+3. **Match** "general" against `lookupNames` (`name` field) in results → find `{ "name": "general", "id": "C02CAP3LAAG" }`
+4. **Use** the `lookupValue` (`id`) → `"C02CAP3LAAG"` in the `--body`
+
+**Present options to the user** when multiple matches exist. Always use the resolved `lookupValue` (not display names) in `--body` or `--query`.
+
+---
+
+## Scope Filtering (CRITICAL)
+
+`uip is resources run list <connector> <reference-object>` may return BOTH global entries (`scope: null`) and project-scoped entries (`scope.type: "PROJECT"`) — often with the **same display name**. Picking the first match by `.name` silently picks the wrong scope.
+
+**Concrete failure:** Jira issuetype "Task" exists globally as `id=3` and per-project as `id=10659` scoped to project `10851`. Selecting `id=10659` for a different project fails at runtime.
+
+### Rule
+
+When picking a reference value for a curated cascade root field (e.g. `fields.issuetype.id` on Jira), ALWAYS inspect `.scope`:
+
+- `scope: null` → globally applicable, safe.
+- `scope.type: "PROJECT"` → valid only when the cascade parent (e.g. `fields.project.key`/`id`) matches `scope.project.id`.
+
+### jq filter
+
+```bash
+uip is resources run list "<connector>" "<reference-object>" \
+  --connection-id "<id>" --output json \
+| jq '.Data | map(select(.scope == null or .scope.project.id == "<target-project-id>"))'
+```
+
+Apply the same filter to any reference whose entries carry `scope` — not just Jira.
+
+---
+
+## Search References (filterPattern)
+
+Some reference fields point to **search endpoints** that require user input as a query parameter. These have a `filterPattern` property with a `{filter}` placeholder.
+
+### Search reference structure
+
+```json
+{
+  "name": "productId",
+  "displayName": "Product ID",
+  "description": "ID of the product to which the ticket is mapped",
+  "required": false,
+  "reference": {
+    "objectName": "search_products",
+    "lookupNames": ["productCode", "id"],
+    "lookupValue": "id",
+    "path": "/search_products",
+    "filterPattern": "productCode={filter}"
+  }
+}
+```
+
+### How to detect
+
+If `reference.filterPattern` exists, the reference is a **search endpoint** — a plain `list` call without the filter will return no results or an error.
+
+### Resolution workflow (search)
+
+1. **Get the user's search input** — the value they want to look up (e.g., product name, code)
+2. **Substitute into filterPattern** — replace `{filter}` with the user's input
+3. **Pass as `--query`** when listing the referenced object:
+
+```bash
+# filterPattern: "productCode={filter}"
+# User input: "Widget Pro"
+uip is resources run list "<connector-key>" "search_products" \
+  --connection-id "<id>" --query "productCode=Widget Pro" --output json
+```
+
+4. **Match results** against `lookupNames` and extract `lookupValue` as usual
+
+### Example: Resolving a Zoho Desk product
+
+User says: "Create a ticket for product Widget Pro"
+
+1. **Describe** returns `productId` with `reference.filterPattern: "productCode={filter}"`
+2. **Search** with user input:
+   ```bash
+   uip is resources run list "uipath-zoho-desk" "search_products" \
+     --connection-id "<id>" --query "productCode=Widget Pro" --output json
+   ```
+   → `{ "productCode": "WP-100", "id": "1892000000056007" }`
+3. **Use** the `lookupValue` (`id`) → `"1892000000056007"` in `--body`
+
+> **If the user doesn't provide a search term**, ask them. Search references cannot be resolved without user input — do NOT call the search endpoint with an empty filter.
+
+---
+
+## Field Dependency Chains
+
+Some reference fields **depend on other fields** — the child field's valid values are scoped by the parent field's selection. Dependencies are expressed in `reference.path` templates containing `{otherField}` variables that must be substituted.
+
+### How to detect dependencies
+
+Check if `reference.path` contains `{fieldName}` template variables. If so, that field depends on the referenced field. Resolve the parent first.
+
+**CRITICAL: If a parent field value is NOT in the user's prompt, you MUST ask the user for it BEFORE attempting to resolve any child fields.** Do not resolve child fields without a scoped parent — the results will be wrong or ambiguous.
+
+### Dependency chain example
+
+A resource has two reference fields with a dependency chain:
+
+```
+Field A → no template variables in path    → resolve first (list resource, pick value)
+Field B → path contains {Field A}          → resolve after A (list scoped by A's value)
+```
+
+**Wrong** — listing Field B's resource globally returns duplicates from all scopes.
+
+**Correct** — resolve Field A first, then list Field B's resource scoped to Field A's resolved value:
+
+```bash
+# Step 1: Resolve Field A (no dependencies)
+uip is resources run list "<connector-key>" "<resource-a>" \
+  --connection-id "<id>" --output json
+# → pick value
+
+# Step 2: Resolve Field B scoped to Field A's value
+uip is resources run list "<connector-key>" "<resource-a>/<resolved-value>/sub-resource" \
+  --connection-id "<id>" --output json
+# → only values valid for this scope
+```
+
+### General rule
+
+When resolving reference fields:
+1. **Sort fields by dependency** — fields with no `{template}` in their reference path come first
+2. **Resolve parent fields** — list the parent resource, pick the value
+3. **Substitute into child path** — replace `{parentField}` in the child's reference path with the resolved value
+4. **Resolve child fields** — list the scoped resource using the substituted path
+
+This pattern applies across all connectors wherever child fields are scoped by parent selections.
+
+---
+
+## Inferring References Without Describe
+
+When describe metadata is unavailable (see [resources.md — Describe Failures](resources.md#describe-failures)), infer reference fields from naming conventions:
+
+- Fields ending in **`Id`** (e.g., `PromotionId`, `AccountId`) typically reference the object with the matching base name (`Promotion`, `Account`).
+- List the inferred object to resolve the ID: `is resources run list "<connector-key>" "<base-name>" --connection-id "<id>" --output json`
+- Match the user's value by `Name` or `DisplayName` in the results.
+
+---
+
+## Static Reference-Value Labeling
+
+When baking a **static value** for a field that has a `.reference` block (any connector — Jira `fields.project.key`/`fields.issuetype.id`, Slack `send_as`/`channel`, Outlook `outputTimezone`/`calendarID`, etc.), the AgentHub edit-UI cannot resolve the display label on its own and renders the raw scalar. Persist labels alongside the bound values via `designTimeMetadata.designTimeLookups`.
+
+### Persisted shape
+
+```jsonc
+"designTimeMetadata": {
+  "designTimeLookups": {
+    "<dotted-field-name>": "<displayName> - <value>"
+    // e.g. "fields.project.key": "Orchestrator - OR"
+    // e.g. "fields.issuetype.id": "Task - 3"
+    // e.g. "send_as": "Bot - bot"
+    // e.g. "channel": "general - C02CAP3LAAG"
+  }
+}
+```
+
+- Shape is `Record<string, string>`. NOT the array-of-`{id,title}` form that the FE library's TypeScript types may suggest — that is the internal Redux shape, different from persistence.
+- Key = the same dotted field name used in `staticValues.<bucket>.<field>`.
+- Value = `"<displayName> - <baked-value>"` (literal ` - ` separator).
+
+### Resolving `displayName`
+
+```bash
+uip is resources run list "<connector>" "<reference.objectName>" \
+  --connection-id "<id>" --output json
+```
+
+Match the baked value against `lookupValue` (from the field's `reference` block). Take `lookupNames[0]` from the matching entry as `displayName`.
+
+### Cascade-scoped references
+
+When `reference.path` contains `{parent.field}` placeholders (e.g. Jira `fields.issuetype.id` → `/project/{fields.project.key}/issuetypes`), the reference is logically scoped to a parent value but the CLI's `run list` does not accept a parent-context flag. `reference.objectName` in this case names the path's root (`project`), not the leaf collection you actually want.
+
+Two-step resolution:
+
+1. **Pick the leaf object.** Take the last path segment singular form. For `/project/{fields.project.key}/issuetypes` use `issuetype` (drop trailing `s` if present).
+2. **List the leaf object and filter by scope.** Many connectors return both global (`scope: null`) and parent-scoped rows in the same listing:
+   ```bash
+   uip is resources run list "<connector>" "<leaf-object>" \
+     --connection-id "<id>" --output json
+   ```
+   - If your baked value resolves to a global entry, pick the row with `scope: null`.
+   - If it resolves to a parent-scoped entry, pick the row whose `scope.<parentType>.<id>` matches the baked parent value (resolved through its own reference first).
+   - Match by `reference.lookupValue` as in the flat case. Take `reference.lookupNames[0]` as the label.
+
+Concrete Jira example — baked `fields.project.key="OR"`, `fields.issuetype.id="3"`:
+- Project: `run list … project` → match `key=OR` → `name="Orchestrator"` → `"Orchestrator - OR"`.
+- Issuetype: `run list … issuetype` returns ~400+ rows. `id=3` matches `name="Task"` → `"Task - 3"`.
+
+**Jira issuetype scope caveat.** The CLI surfaces every issuetype row with `scope: null` even when Jira itself project-scopes the type (the connector flattens scope). Filtering by `scope` is therefore unreliable for Jira issuetype disambiguation. When multiple rows share a display name (e.g., several `Epic` entries at different ids), verify the candidate id by re-running the cascade describe with `(project.key, issuetype.id)` — a successful describe means the id is valid for that project. Other connectors that return scope honestly still match by `scope.<parentType>.<id>` as described above.
+
+Do NOT re-issue `uip is resources describe -f <parent>=<value>` solely for label resolution — the cascade is intended for required-field expansion. For Jira `curated_create_issue` specifically, omit `--action`; passing it triggers `No api-type ObjectAction matched for fields [...]`.
+
+### Applies to
+
+Every connector with reference-typed fields. Emit one `designTimeLookups` entry per static reference value baked into `staticValues` — Jira, Slack, Outlook, Salesforce, ServiceNow, Workday, and so on.
+
+---
+
+## Validate Required Fields Before Executing
+
+After resolving references, **check every required field** from the describe response against what the user provided. This is a hard gate — do NOT execute until all required fields have values.
+
+**Process:**
+1. Collect all fields where `required: true` from the describe output
+2. For each required field, check if the user's prompt contains a value for it
+3. If any required field is missing, **ask the user** before proceeding:
+   - List the missing fields with their `displayName` and `description`
+   - For reference fields, explain what kind of value is expected
+   - Wait for the user's response before continuing
+4. Only after all required fields are accounted for, proceed to execute
+
+> **Do NOT guess or skip missing required fields.** A missing required field will cause a runtime error. It is always better to ask than to assume.