@uipath/skills 1.197.2 → 1.198.0-preview.21

package/skills/uipath-connector-builder/references/auth.md

@@ -23,9 +23,8 @@ encrypted — e.g. an OAuth user token (`TEXTFIELD`) or a Google service-account
 
 ## Auth types (`auth set --auth-type`)
 
-All 14 types are supported. `init --auth` is sugar for the two most common (`oauth2`,
-`customApiKey`) at create time; everything else (and the full flag surface) goes through
-`auth set`.
+All 19 types are supported. `init --auth <type>` accepts any of them inline at create
+time (handy for `none`); type-specific flags beyond init's OAuth sugar go through `auth set`.
 
 | auth-type               | Use when                                        |
 |-------------------------|-------------------------------------------------|
@@ -33,16 +32,21 @@ All 14 types are supported. `init --auth` is sugar for the two most common (`oau
 | oauth2Pkce              | OAuth 2.0 Authorization Code + PKCE.            |
 | oauth2ClientCredentials | OAuth 2.0 Client Credentials (no user).         |
 | oauth2Password          | OAuth 2.0 Resource Owner Password.              |
+| oauth2PrivateKeyJwt     | OAuth 2.0 Private Key JWT (signed client assertion, e.g. Epic FHIR). |
 | oauth1                  | OAuth 1.0a / Token-Based Authentication (TBA).  |
 | basic                   | HTTP Basic (username + password).               |
-| jwtOauth                | JWT-bearer OAuth.                               |
-| jwtOauth2               | JWT-bearer OAuth 2.0.                           |
+| jwtOauth                | OAuth 2.0 JWT Bearer (service accounts — Salesforce, Box). |
+| jwtOauth2               | Same contract as jwtOauth (legacy alias — prefer jwtOauth). |
 | custom                  | A custom static authorization header.           |
 | customApiKey            | Vendor uses a static API key (header or query). |
 | personalAccessToken     | Personal access token authorization header.     |
 | awsv4                   | AWS Signature v4.                               |
 | googleServiceAccount    | Google service-account JSON.                    |
 | rsaCertificate          | RSA private-key certificate.                    |
+| none                    | Open/unauthenticated API (webhooks, public endpoints). |
+| firstPartyService       | UiPath internal service — platform-injected service identity. |
+| fpsUserDelegatedAccess  | UiPath internal service — acts as the connection's user. |
+| fpsRobotAccess          | UiPath internal service — robot access token.   |
 
 Per-type config key sets (which secrets, which URLs) are in
 [configuration.md](configuration.md) §"Auth as configuration".
@@ -97,6 +101,114 @@ uip is connectors builder auth set --auth-type oauth2 \
   --required-scopes read --preselected-scopes read,write
 ```
 
+## JWT Bearer (jwtOauth / jwtOauth2)
+
+The connector holds the token URL and the SHAPE of the JWT assertion; the connection user
+supplies the client id/secret, the signing key (`jwt.base64.encoded.key` — PKCS#8 PEM or
+base64), and any user-specific claim values. The runtime builds the assertion from every
+config keyed `jwt.claim.<name>` (payload) / `jwt.header.<name>` (header) — declare each with
+a repeatable flag:
+
+```bash
+uip is connectors builder auth set --auth-type jwtOauth \
+  --token-url https://login.salesforce.com/services/oauth2/token \
+  --jwt-claim aud=https://login.salesforce.com \
+  --jwt-claim iss \
+  --jwt-claim sub \
+  --scope 'api refresh_token'
+```
+
+- `--token-url` is REQUIRED (the assertion is exchanged there for an access token).
+- `--jwt-claim name=value` pre-fills the claim (still editable at connection time);
+  `--jwt-claim name` (bare) creates it required-and-empty — the connection user fills it
+  (e.g. Salesforce `iss` = consumer key, `sub` = username).
+- Label/hint the connection-form field inline: `--jwt-claim 'iss;label=Consumer Key;hint=The connected app consumer key'`
+  — without a label the field renders as "JWT claim 'iss'".
+- `--jwt-header kid=...` for assertion headers, same syntax (label/hint work too).
+- The runtime ALSO requires `oauth.api.key` (client id) and `oauth.api.secret` — the bundle
+  ships both as connection-form fields. For Salesforce-style flows where iss == client id,
+  the user enters the same value twice; that is the platform contract, not a bug.
+- jwtOauth intentionally creates NO `oauthOnTokenRefresh` resource — there is no refresh
+  token; the runtime signs a fresh assertion when the access token expires. Do not add one.
+- `jwt.base64.encoded.key` (the signing key) is `internal: true, configScreenType: none`
+  BY DESIGN — every catalog jwt connector (Box, Salesforce, uipath-http) ships it that way
+  and the IS connection UI renders the private-key field for jwt flows itself. Do NOT
+  "fix" it to `pre`.
+- Typical claim sets: Salesforce `iss`/`sub` + `aud=https://login.salesforce.com`;
+  Box `iss`/`sub` + `aud=<token url>` + `box_sub_type=enterprise`.
+- NEVER write `jwt.oauth.*` config keys (consumer.key/private.key/username) — nothing in
+  the platform reads them; a connector built with them can never authenticate.
+
+## OAuth 2.0 Private Key JWT (oauth2PrivateKeyJwt)
+
+Client-credentials-style flow where the client authenticates with a SIGNED ASSERTION
+instead of a client secret (Epic FHIR is the catalog reference):
+
+```bash
+uip is connectors builder auth set --auth-type oauth2PrivateKeyJwt \
+  --token-url https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token
+```
+
+The bundle ships `oauth.api.key` (client id), `jwk.private.key`, `jwk.kid` as
+connection-form fields — the user pastes the registered key + kid at connection time.
+
+## UiPath First Party Service (firstPartyService / fpsUserDelegatedAccess / fpsRobotAccess)
+
+INTERNAL-ONLY — connectors that call UiPath's own services (Orchestrator, Data Fabric,
+Apps…). There are NO credential fields: the platform injects the caller's identity at
+runtime. Choose the flavor by whose token the connector should act with: the service
+(`firstPartyService`), the connection's user (`fpsUserDelegatedAccess`), or a robot
+(`fpsRobotAccess`).
+
+```bash
+uip is connectors builder init --name "My Service" \
+  --base-url 'https://{host}/{account}/{tenant}/myservice_'
+uip is connectors builder auth set --auth-type firstPartyService \
+  --scope MyServiceApiUserAccess
+```
+
+- `--scope` = the first-party scope the platform token is minted with (e.g.
+  `OrchestratorApiUserAccess`, `DataService`); it lands hidden on `oauth.scope` — an
+  authoring-time value, never a connection-form field.
+- base.url follows `https://{host}/{account}/{tenant}/<service>_` — `auth set` binds those
+  three placeholders to the platform headers (`x-forwarded-host`,
+  `x-uipath-internal-accountid`, `x-uipath-internal-tenantid`) automatically, CONVERTING
+  any user-fillable configs + configuration-type bindings a prior `init --base-url` seeded
+  (they show up under `ConfigChanges.removed`). Either command order works.
+- VERIFY with `auth get`: `FpsBindings` lists each placeholder and the header it resolves
+  from (`boundToHeader: null` = broken), and `ConnectionFormFields: []` proves no
+  user-facing fields. `validate` errors on any FPS connector whose placeholders are
+  user-fillable or configuration-bound.
+- `auth set` also seeds hidden RUNTIME bookkeeping entries (`oauth.user.token`,
+  `oauth.user.refresh_time`, `oauth.user.refresh_interval`, `oauth.basic.header`; the
+  delegated type adds `oauth.user.refresh_token`) — token storage the platform writes at
+  runtime, never credential fields. Leave them alone.
+
+## No authentication (none)
+
+```bash
+uip is connectors builder auth set --auth-type none
+```
+
+Records `authentication.type:"none"` with zero credential configs — for open APIs and
+webhook-style connectors (catalog: http-webhook, generic-webhooks). `validate` requires SOME
+auth type on every connector, so run this even when the API needs no credentials.
+
+## AWS Signature v4 (awsv4)
+
+```bash
+uip is connectors builder init --name "Amazon Connect" \
+  --base-url 'https://connect.{aws.region}.amazonaws.com'
+uip is connectors builder auth set --auth-type awsv4 --aws-service-name connect
+```
+
+The bundle ships `aws.api.key` / `aws.api.secret` / `aws.region` as connection-form fields
+plus hidden `aws.service.name` / `aws.host`. `--aws-service-name` sets the per-service
+SigV4 constant (e.g. `polly`, `connect`) — no `state patch` needed. Put `{aws.region}` in
+base.url — the CLI binds it to the region config automatically, and `auth set` silently
+replaces the generic placeholder config `init` seeded with the canonical AWS one (no
+`--force` required).
+
 ## customApiKey
 
 ```bash
@@ -139,10 +251,11 @@ rather than hand-editing `configuration[]`.
 `--validation-vendor-path <path>` (with optional `--validation-method`, default GET) seeds
 a `provisionAuthValidation` system resource — one read-only call at connection creation that
 rejects bad creds immediately. The probe must be read-only and must not change vendor data,
-so keep it GET. Every non-OAuth/JWT auth type (any whose name isn't `oauth*`/`jwt*` — `basic`,
-`custom`, `customApiKey`, `personalAccessToken`, `awsv4`, `googleServiceAccount`,
-`rsaCertificate`) has no token exchange to catch bad creds, so `validate` flags it as missing
-there. Details: [system-resources.md](system-resources.md) §provisionAuthValidation.
+so keep it GET. Credential auth types with no token exchange (`basic`, `custom`,
+`customApiKey`, `personalAccessToken`, `awsv4`, `googleServiceAccount`, `rsaCertificate`)
+get a `validate` warning when it is missing. OAuth/JWT flows (token exchange catches bad
+creds), `none` (no credentials), and the FPS family (platform identity) are exempt —
+`validate` does not ask for a probe there. Details: [system-resources.md](system-resources.md) §provisionAuthValidation.
 
 ## System (lifecycle) resources — `auth system`
 
@@ -150,15 +263,26 @@ Lifecycle/auth-flow endpoints with no SR file (provisionAuthValidation, onProvis
 oauthOnTokenRefresh, …) are wired with `auth system create --type <type>` / `auth system list`.
 The full type list, override-path rules, and flags: [system-resources.md](system-resources.md).
 
-## Base URL derived from a token response (e.g. Salesforce `instance_url`)
+## Base URL derived from a token response
 
-There is NO vendor-specific base-url flag (`init --base-url` is STATIC only). When the vendor
-returns the API host in its token response, it is skill-guided: a `postRequest` hook reads +
-validates the host (https scheme, allowlisted), then persists it into THIS connection's config
+There is no service-specific base-url flag (`init --base-url` is STATIC only). When the token
+response returns the API host or another per-connection value, use the generic hook pattern:
+a `postRequest` hook reads + validates the value (scheme, host/id shape, allowlist where applicable), then persists it into THIS connection's config
 at runtime via `done({configuration})` — NOT `state patch` (that baking-time edit would set one
 org's URL as everyone's default). Full pattern: [hooks.md](hooks.md) §"Pattern: base URL …
 derived from a token response".
 
+## Verifying auth setup — `auth get`
+
+`auth get` returns the full auth read model in one call: the type(s), every auth-related
+config entry (key, label, hint, screen type, hidden/required/encrypted flags, defaults
+with secrets redacted), `ConnectionFormFields` (EVERY visible config across the whole
+connector — the literal connection form; `[]` = empty form), whether
+`oauthOnTokenRefresh` / `provisionAuthValidation` exist, `FpsBindings` (FPS
+placeholder→header map), and `TemplateBindings` (each non-FPS base.url `{placeholder}`
+with whether its backing config entry + path-param binding exist). Use it instead of
+stitching `state query` calls.
+
 ## Re-running auth set
 
 Idempotent on identical inputs (returns `unchanged`). If a new input would modify an

package/skills/uipath-connector-builder/references/configuration.md

@@ -83,14 +83,20 @@ connector; the tenant user supplies the real secret at connection time. Key sets
 - **OAuth2** (16 entries — canonical list; `auth set` writes all of them):
   `oauth.api.key`, `oauth.api.secret` (PASSWORD, encrypt, isPrivate), `oauth.callback.url`
   (auto-set, do NOT hardcode), `oauth.authorization.url`, `oauth.token.url`,
-  `oauth.token.refresh.url`, `oauth.token.revoke.url`, `oauth.scope`,
-  `oauth.basic.header`, `oauth.user.token`, `oauth.user.refresh.token`,
-  `oauth.user.refresh.interval` (sec, default 3600), plus auto-set internals
-  `oauth.user.refresh.time`, `oauth.decode.authorization.code`, `authentication.time`,
+  `oauth.token.refresh_url`, `oauth.token.revoke_url`, `oauth.scope`,
+  `oauth.basic.header`, `oauth.user.token`, `oauth.user.refresh_token`,
+  `oauth.user.refresh_interval` (sec, default 3600), plus auto-set internals
+  `oauth.user.refresh_time`, `oauth.decode.authorization.code`, `authentication.time`,
   `expires_in`. Sets `authentication.type:"oauth2"`, `typeOauth:true`.
+  NOTE the underscore in the last segment of the four refresh/revoke keys
+  (`refresh_url`, `refresh_token`, `refresh_time`, `refresh_interval`) — the
+  all-dots spellings are dead keys the runtime never reads.
 - **OAuth2 PKCE** adds `oauth.pkce.code.challenge.verifier`, `oauth.pkce.code.challenge`,
   `oauth.pkce.code.challenge.method` (`"S256"`).
 - **OAuth2 Client Credentials**: subset — no auth URL, no refresh token.
+- **oauth2PrivateKeyJwt** (client authenticates with a signed assertion, e.g. Epic FHIR):
+  `oauth.api.key`, `oauth.token.url`, `jwk.private.key` (TEXTAREA, encrypt), `jwk.kid` —
+  the connection user supplies the key + kid. `typeOauth:true`.
 - **customApiKey** (the on-disk type for any "API key" auth — the UI labels it "API key",
   but never use periodic's bare `apiKey`): one PASSWORD secret config (default
   `custom.api.key`, encrypt, isPrivate, `groupBy:"customApiKey"`) + one `type:"value"`
@@ -98,9 +104,25 @@ connector; the tenant user supplies the real secret at connection time. Key sets
   `authentication.type:"customApiKey"`, `typeOauth:false`. CLI flow + flags:
   [auth.md](auth.md) §customApiKey.
 - **basic**: `username`, `password` (PASSWORD, encrypt).
-- **jwtOauth**: `jwt.oauth.consumer.key`, `jwt.oauth.private.key`, `jwt.oauth.username`,
-  `jwt.oauth.token.url`, `jwt.oauth.scope`. `typeOauth:true`.
-- **awsv4**: `aws.api.key`, `aws.api.secret`, `aws.region`, `aws.service.name`, `aws.host`.
+- **jwtOauth / jwtOauth2** (OAuth 2.0 JWT Bearer): `oauth.api.key`, `oauth.api.secret`,
+  `oauth.callback.url`, `oauth.token.url`, `jwt.base64.encoded.key` (TEXTAREA — the signing
+  key, PKCS#8 PEM or base64), plus one `jwt.claim.<name>` config per assertion claim and
+  `jwt.header.<name>` per assertion header (the runtime builds the JWT from every config
+  with those prefixes — Salesforce ships `jwt.claim.iss/sub/aud`). Wire claims with
+  `auth set --jwt-claim` / `--jwt-header` ([auth.md](auth.md) §"JWT Bearer"). `typeOauth:true`.
+  (The old `jwt.oauth.*` keys are read by NOTHING — never write them.)
+- **awsv4**: `aws.api.key`, `aws.api.secret`, `aws.region` (user-filled), `aws.service.name`
+  (hidden, per-service constant like `connect`), `aws.host` (hidden). Put the region in the
+  base URL as `https://<service>.{aws.region}.amazonaws.com` — the CLI binds `{aws.region}`
+  to the config automatically.
+- **none**: no auth configs at all — `authentication.type:"none"` only (open APIs, webhooks).
+- **firstPartyService / fpsUserDelegatedAccess / fpsRobotAccess** (UiPath internal services
+  ONLY): no user credentials — the platform injects the caller's identity. `oauth.scope`
+  (hidden) carries the service scope (set via `auth set --scope`). base.url uses
+  `https://{host}/{account}/{tenant}/<service>_` and the CLI binds those three placeholders
+  to the internal headers `x-forwarded-host` / `x-uipath-internal-accountid` /
+  `x-uipath-internal-tenantid` (`type:"header"` path params) — they are NOT connection-form
+  fields. `fpsUserDelegatedAccess` adds `oauth.user.refresh_token`.
 
 ## Multi-auth (groupControl)
 An `authentication.type` COMBO with `"groupControl": true` plus per-type config entries

package/skills/uipath-connector-builder/references/debugging.md

@@ -23,7 +23,7 @@ exits non-zero on failure). All run under `uip is connectors builder`.
   false when it should be true.
 - **Token exchange fails**: wrong `oauth.token.url`; vendor expects/rejects
   `oauth.basic.header`; creds in wrong place (body vs header).
-- **Works then fails after expiry**: `oauth.token.refresh.url` unset, refresh interval too
+- **Works then fails after expiry**: `oauth.token.refresh_url` unset (NOTE underscore — the all-dots key is dead), refresh interval too
   long, or wrong param mapping in `oauthOnTokenRefresh`.
 - **API key unauthorized**: wrong header name, missing prefix (`Bearer `/`Token `), or key
   sent as query when the vendor wants a header. Re-run `auth set --auth-type customApiKey`.

package/skills/uipath-connector-builder/references/standard-resources.md

@@ -57,6 +57,28 @@ defines `GET`/`GETBYID`); a write-only activity keeps its base path. A per-metho
 is derived from the canonical resource path. Only model GETBYID for TRUE by-id endpoints,
 not a search/list-by-filter endpoint.
 
+### nested / parent-id vendor paths (mid-path `{token}`)
+A path variable is bound on TWO sides: element-side `{name}` in the internal `path`, vendor-side
+`{vendorName}` in the `vendorPath`. When a `{token}` sits **only in the vendor path** — a
+parent-scoped sub-collection like `--vendor-path /issue/{issueId}/comment` whose internal slug is the
+flat `/comments` — it CANNOT be `type:"path"`: element-service looks for the segment in the flat
+element URL, doesn't find it, and 400s **"required parameter '<name>' not found"** at request time
+(reads/writes on comments/transitions/assignee/attachments all fail). `activity create` now emits the
+right shape automatically:
+
+- **query→path (default for a vendor-only token):** internal `/comments`, param
+  `{ name:"issueId", type:"query", vendorName:"issueId", vendorType:"path" }`. Element-service takes the
+  value as a query param and interpolates it into the vendor template. This is how shipped connectors
+  (e.g. Jira `curated_add_comment`) declare parent ids. Callers pass it at run time via
+  `uip is resources run … --query issueId=<id>`.
+- **path→path (token in the internal path):** pass `--resource-path /comments/{id}` so `{id}` is a real
+  element URL segment → `type:"path"`. If the internal and vendor tokens differ in name, the param is
+  `{ name:"id", vendorName:"issueId", type:"path", vendorType:"path" }` (name↔internal, vendorName↔vendor);
+  the CLI can't auto-derive a differing pair, so author it with `activity param create`.
+
+`validate` now flags both failure modes: a `type:"path"` param whose `{name}` is missing from the
+internal path, and a `{token}` in the vendorPath with no param sending it (unbound → 404).
+
 ## metadata.events
 `{ "eventMode": ["polling"] }` — `trigger create` sets this. Full `eventMode` value set:
 [events.md](events.md) §"SR-level event metadata".
@@ -68,12 +90,16 @@ you pass win, unspecified keys are kept, and per-method visibility is deep-merge
 `--type` is required only for a NEW field, optional on a merge.
 
 Core: `name`, `type` (string/integer/number/boolean/date/date-time/object/array),
-`displayName`, `nativeType`, `format`, `description`, `sampleValue`, `primaryKey`
-(`--primary-key`), `sortOrder` (`--sort-order`), `enum` (`--enum '[{"value":"active"}]'`),
-`mask` (`--mask`), `custom`. **`enum` MUST be the object form `[{"value":"x"}]`** — the server
-SR marshaller rejects a bare string array `["x"]` at PUBLISH time even though `validate` passes.
-The CLI auto-normalizes a bare `--enum '["a","b"]'` to the object form, but hand-edited SR/`state
-patch` enums must use `[{"value":…}]`.
+`displayName`, `nativeType` (`--native-type`), `format`, `description`, `sampleValue`,
+`defaultValue` (`--default-value`, scalar or JSON), `primaryKey` (`--primary-key`),
+`sortOrder` (`--sort-order`), `enum` (`--enum`), `enhancedEnum` (`--enhanced-enum`),
+`custom`. **`mask` is a date/number FORMAT PATTERN string** (e.g. `yyyy-MM-dd'T'HH:mm:ssZ`),
+NOT a boolean — set it with `--mask <pattern>`. **`enum` MUST end up as the object form `[{"value":"x"}]`** — the
+server SR marshaller rejects a bare string array `["x"]` at PUBLISH time. Both `--enum` and
+`--fields-file` auto-normalize a bare `["a","b"]` to the object form; and `validate` now FLAGS a
+bare/`!{value}` enum still sitting in an SR (e.g. from a hand `state patch`), so it no longer
+slips through to a publish failure. `--enhanced-enum '[{"name":"Label","value":"V"}]'` writes
+labelled options.
 
 **Method visibility** (`field.method` object) controls request/response per method:
 ```json
@@ -85,22 +111,145 @@ patch` enums must use `[{"value":…}]`.
 Set it with the visibility flags. `--method` is REPEATABLE and the flags
 (`--request`/`--response`/`--required`/`--request-curated`/`--response-curated`) apply to
 EVERY listed method: `--method GET --method POST --response` makes the field a response on
-both. Properties: `response`, `request`, `required`, `requestCurated`, `responseCurated`,
+both. For DIFFERENT visibility per method in one call, use the inline form —
+`--method 'GET=response,response-curated' --method 'POST=request,required'` — and prefix a
+flag with `!` to UNSET it on a merge (`--method 'GET=!request'` writes `request: false`
+over an accidental `true`; no `state patch` needed). Bare and inline `--method` forms mix.
+Properties: `response`, `request`, `required`, `requestCurated`, `responseCurated`,
 `designOverrides`. `requestCurated`/`responseCurated` gate a field's visibility INSIDE a
 curated activity (plain `request`/`response` is not enough); auto-curation sets them from
 the field's request/response side.
 
 **Searchable**: `searchable` (`--searchable`), `searchableOperators`
-(`--searchable-operators '=,!=,like,>,<,>=,<=,in'`), `searchableNames`.
+(`--searchable-operators '=,!=,like,>,<,>=,<=,in'`), `searchableNames` (`--searchable-names`).
 
 **design** object (`--design-position primary|secondary|none`, `--component`, `--hidden`):
 `position`, `component` (FolderPicker, Button, Connectors, Resources, Fields, Processes,
-Queues), `hidden` (what `--hidden` writes — the field-level key is `design.hidden`, NOT
-`isHidden`), `loadByDefault`, `isMultiSelect`, `enableUserOverride`, `dictionaryWidget`,
-`solutionResourceKind`, `fieldActions` (cascading show/hide based on another field's value).
+Queues), `isHidden` (what `--hidden` writes — the key shipped connectors use; a dependent
+dropdown's `--depends-on` writes the same key), `loadByDefault`, `isMultiSelect`,
+`enableUserOverride`, `dictionaryWidget`, `solutionResourceKind`, `fieldActions` (cascading
+show/hide based on another field's value).
+
+### Dropdowns (reference / lookup)
+A dropdown lists rows from a **List resource in this connector** — you choose which field is
+DISPLAYED and which is SENT. A dropdown can live on a **field, a path param, or a query param**, so
+the same flags exist on both `activity field create` and `activity param create`:
+
+```
+--reference-object <name>   target List resource's object name (e.g. teams)
+--reference-path <path>     its list path (e.g. /teams); use {parent} for a dependent dropdown
+--lookup-value <field>      the ONE field sent as the value (e.g. id)
+--lookup-names <csv>        display-candidate fields (e.g. id,displayName)
+--display-pattern <p>       visible label, e.g. "{displayName}" or "{name} - {id}" (combines lookupNames)
+--filter-pattern <p>        server-side type-ahead template with {filter} (optional)
+--load-by-default           populate the list on open;  --multi-select;  --enable-user-override
+```
+
+The reference points at a resource whose GET is `operation:"List"`; `lookupValue`/`lookupNames`
+name fields in that resource's returned records. Raw `--reference '<json>'` (`{objectName,path,
+lookupValue,lookupNames}`) is still accepted as an escape hatch. `objectName`+`path`+`lookupValue`
+are expected; `validate` warns if `lookupValue` is missing.
+
+**Dependent dropdowns** (child list scoped by a parent — e.g. Teams channel depends on team): put
+`{<parentName>}` in the child's `--reference-path` (must equal the parent field/param's name) and
+pass `--depends-on <parentName>`. That injects `design.isHidden` + a show/hide `fieldActions` pair,
+so the child appears only after the parent has a value and its list is filtered by the parent:
+
+```
+activity field create --resource messages --name team_id --reference-object teams \
+  --reference-path /teams --lookup-value id --lookup-names id,displayName \
+  --display-pattern "{displayName}" --load-by-default --method "POST=request,required"
+activity field create --resource messages --name channel_id --depends-on team_id \
+  --reference-object "teams::channels" --reference-path "/teams/{team_id}/channels" \
+  --lookup-value id --lookup-names id,displayName --display-pattern "{displayName}" \
+  --method "POST=request,required"
+```
+
+The parent (`team_id`) must exist as a sibling field/param on the same resource — `validate` warns
+if a dependent path's `{token}` or a rule's `refFieldName` names nothing on the resource.
+
+**Show/hide on a value** (conditional field, not a lookup): `--field-actions '<json>'` is the
+escape hatch — an array of `{ actionType: show|hide|required|optional, rules: [{ type:"field",
+refFieldName:"<other>", refFieldValues:["card"], isCleared:false }] }`. Use `refFieldValues:["*"]`
+for "any value", `isCleared:true` to fire when the ref field is empty; multiple rules in one action
+are ANDed. **`--depends-on` vs `--field-actions`:** use `--depends-on` for a dependent dropdown
+(show once the parent has ANY value — it hard-codes `["*"]`); use `--field-actions` when the child
+should appear only for a SPECIFIC parent value (e.g. `refFieldValues:["task"]`).
+
+**Dropdowns on path / query params** work identically — the same flags exist on `activity param
+create`. For a **path variable** just pass `--type path`: the CLI auto-encodes it as `type:"query"`
++ `vendorType:"path"` when the variable isn't a segment of the flat internal path (element-service
+interpolates it into the vendor path — a literal `type:"path"` there would 400). Example — a `boardId`
+path-param dependent dropdown scoped by `projectId`:
+
+```
+activity param create --resource cards --method POST --name boardId --type path \
+  --reference-object boards --reference-path "/projects/{projectId}/boards" \
+  --lookup-value id --lookup-names id,name --display-pattern "{name}" --depends-on projectId
+```
+
+## Authoring for catalogue parity — the curation layer
+Wiring dropdowns is necessary but NOT sufficient to match a catalogue connector's Studio Web UX.
+Benchmarking generated connectors vs catalogue (Gmail/Outlook/OneDrive) showed the dropdown plumbing
+reaches parity, but four things a blind build usually MISSES — do these to close the gap:
+
+1. **Static / enum-backed pickers.** Not every dropdown is backed by a live vendor list — some are a
+   fixed set of literal choices. Two cases:
+   - **Small closed choice** (writeMode, valueInputOption, operation, role/type) → use
+     `--enum '["A","B"]'` or `--enhanced-enum '[{"name":"Label","value":"V"}]'` on **`field create`
+     OR `param create`** (both support it). This renders a static combo directly — do NOT stand up a
+     helper List resource for these. (Catalogue puts `enum`/`enhancedEnum` right on the field/param.)
+   - **Large / shared / vendor-fetched set** (timezones, currencies) → author a small helper List
+     resource holding that set and point a dropdown at it (`--reference-object timezones
+     --reference-path /timezones`). The catalogue adds a `timezones` picker on every calendar /
+     send-mail activity this way.
+2. **Curated responses, not raw vendor JSON.** Don't leave an activity's output as raw vendor field
+   names. Curate it — friendly output field names + a curated subset — via per-field `responseCurated`
+   + `displayName` (e.g. `EventTitle`/`StartDateTime` instead of `subject`/`start`). Set curated
+   visibility in the `--fields-file` method map; both `responseCurated` and the kebab
+   `response-curated` spelling are accepted (normalized).
+3. **Scope pickers on list / read verbs.** A list activity should offer the folder / calendar /
+   parent **scope** as a dropdown, not just a generic `where` / `pageSize`. e.g. Get Email List →
+   an email-folder picker; Get Event List → a calendar picker.
+4. **Field completeness.** Cover the catalogue's fields, not just the obvious ones (e.g. `Importance`
+   / `ReplyTo` on send-email, `ListColumns` on SharePoint list items).
+
+**Known CLI limits (catalogue-only for now — can't reach 100% here):** there is no hierarchical
+**tree-picker** reference type (the OneDrive drive→folder→file browser) and no **merged/combined**
+picker (sheets+tables+named-ranges in one dropdown); the SR-level `type:"curated"` + `section` /
+`category` grouping isn't settable (activities still surface as standalone via
+`metadata.method.<VERB>.curated`). Don't try to hand-fake these — note them as gaps.
+
+## Bulk field authoring — `--fields` / `--fields-file`
+`activity create --fields '<json-array>'` (inline) or `--fields-file <path>` seeds the whole
+field schema in one shot. Two shapes are accepted: an ARRAY of field objects
+(`[{ "name": "email", ... }]`), OR a name→spec OBJECT map (`{ "email": { ... } }`) where the KEY
+is the field name — the exact shape a standard-resource stores `fields` under, so you can paste a
+real connector's `fields: {…}` object VERBATIM. Each field object uses the SAME keys as above
+(`name` required in the array form; `type` optional — defaults to `string`). This path is **validated and
+normalized before anything is written** (same engine as `field create`): a bad shape fails
+fast with a `ValidationError` listing EVERY problem, rather than silently authoring a broken
+SR that only fails at publish. Specifically it:
+- normalizes a bare `enum: ["a","b"]` → `[{"value":"a"},…]`;
+- accepts per-method visibility under `method` (canonical) OR `methods` (alias) — but not both;
+- requires `objectName`+`path` on a `reference`; requires `name`+`value` on each `enhancedEnum`;
+- checks `design.position` ∈ {primary,secondary,none} and that boolean flags are booleans;
+- REJECTS unknown top-level keys (typo guard) and duplicate field names.
+Example element: `{ "name": "status", "type": "string", "enum": ["open","closed"],
+"searchable": true, "method": { "GET": { "response": true } } }`. `--fields`/`--fields-file`
+carry the full property set (enum, enhancedEnum, reference, searchable*, primaryKey,
+sortOrder, defaultValue, design, …) — none are dropped.
+
+The schema is OPEN: recognized keys are listed by `activity field schema`, but connectors
+carry a vendor long tail (`refName`, `searchableDisplayName`, `isHidden`, …) — those pass
+through with a WARNING, not an error, so real fields are never blocked. Only true
+publish‑breakers hard‑fail: missing `name`, duplicate names, both `method`+`methods`, a
+non‑object `method` map.
 
-**reference** object (lookup dropdown): `{ "lookupNames": ["name"], "lookupValue": "id",
-"path": "/accounts" }` — set via `state patch` (no field flag).
+Don't guess the shape: `activity field schema` prints the exact accepted keys, types,
+visibility methods, and a copy‑pasteable **valid** example (no connector needed). To
+bulk‑add fields to an EXISTING activity, re‑run `activity create --name <same>
+--fields-file <path>` — it MERGES fields into the existing SR (existing fields kept).
 
 ## Rules
 1. Field dict key MUST equal `field.name`. 2. `fields` is top-level. 3. Only methods in

package/skills/uipath-governance/references/cli-cheatsheet.md

@@ -97,7 +97,7 @@ Bare `formData` object, NOT wrapped in `{ "data": ... }`. The CLI adds the wrapp
 
 ## Deployment (tenant / group / user)
 
-> **All `deployment * configure` commands are FULL REPLACE.** The submitted array rewrites the target's assignment list. Always read current state first, merge new entries in, then configure. See [policy-assign.md](policy-assign.md) for the merge-first pattern.
+> **All `deployment * configure` commands are FULL REPLACE.** The submitted array rewrites the target's assignment list. Always read current state first, merge new entries in, then configure. See `policy-assign.md` for the merge-first pattern.
 >
 > **Why this matters:** the previous `assign-tenant` / `assign-group` / `assign-user` commands had a "last deploy wins" bug — sequential single-policy calls each did a full-replace at the API. The new `configure` commands fix this by taking the full assignment list in one atomic call.
 
@@ -173,8 +173,8 @@ This skill uses only the default caller-own mode. The `--tenant-only` and `--use
 | `401 / 403` | Session expired or insufficient perms. | Halt. Ask user to `uip login`. |
 | `404` | Identifier not found. | Halt. Check IDs. (Missing `--input` paths now surface a clear filesystem error, not 404.) |
 | `409` | Duplicate policy name on create. | Halt. V1 = do NOT retry-as-update. (Critical Rule in SKILL.md) |
-| `500` | Often [missing metadata flags on update (known-issue #2)](cli-known-issues.md). | Halt. Re-read policy metadata, pass all flags. |
-| `503` with transient `Instructions` text (`template upgrade`, `connection timeout`, `backend temporarily unavailable`) | AOPS is migrating the policy's Form.io template or a dependency is flapping — typically tens of seconds to minutes. | Do NOT use the default 3s retry. Wait 30s before first retry, 60s before second. Or surface to user and offer `retry now` / `cancel`. Only halt after a third failure or if the `Instructions` text shifts to a non-transient error. See [policy-crud.md UPDATE error map](policy-crud.md#update-recipe). |
+| `500` | Often missing metadata flags on update (known-issue #2). | Halt. Re-read policy metadata, pass all flags. |
+| `503` with transient `Instructions` text (`template upgrade`, `connection timeout`, `backend temporarily unavailable`) | AOPS is migrating the policy's Form.io template or a dependency is flapping — typically tens of seconds to minutes. | Do NOT use the default 3s retry. Wait 30s before first retry, 60s before second. Or surface to user and offer `retry now` / `cancel`. Only halt after a third failure or if the `Instructions` text shifts to a non-transient error. See `policy-crud.md` UPDATE error map. |
 | `5xx` other | Server-side. | Retry once after 3s. Halt on second failure. Surface `Instructions` verbatim. |
 
 All halts write a deploy record (Apply) or patch record (Diagnose).

package/skills/uipath-governance/references/diagnose/references/failure-modes.md

@@ -63,7 +63,7 @@ Named failure patterns with symptom → cause → investigation → fix. Match t
    ```bash
    uip gov aops-policy deployment tenant get "$TENANT_ID" --output json
    ```
-3. Verify the product is included in the target license type (see [aops-policy-deploy-guide.md — License-type → product compatibility](../aops-policy/aops-policy-deploy-guide.md#license-type--product-compatibility)).
+3. Verify the product is included in the target license type (see [aops-policy-deploy-guide.md — License-type → product compatibility](../../aops-policy/aops-policy-deploy-guide.md#license-type--product-compatibility)).
 
 **Fix:** Cause 1 → redeploy to a license type that includes the target product. Cause 2 → deploy to the license type the affected users actually hold. Cause 3 → deploy to all relevant license types.
 
@@ -100,7 +100,7 @@ Named failure patterns with symptom → cause → investigation → fix. Match t
    uip gov access-policy list --filter "status in ('Active')" --output json
    ```
 
-**Fix:** Cause 1 → narrow selector `resourceType`/`tags`. Cause 2 → add the calling user/group to `actorRule`. Cause 3 → add the actor process type to `executableRule`. Cause 4 → adjust tags on the resource or policy. Cause 5 → see [plugins/actor/impl.md — Robot intent](../access-policy/plugins/actor/impl.md) for the User-fallback pattern.
+**Fix:** Cause 1 → narrow selector `resourceType`/`tags`. Cause 2 → add the calling user/group to `actorRule`. Cause 3 → add the actor process type to `executableRule`. Cause 4 → adjust tags on the resource or policy. Cause 5 → see [plugins/actor/impl.md — Robot intent](../../access-policy/plugins/actor/impl.md) for the User-fallback pattern.
 
 ---
 
@@ -133,7 +133,7 @@ Named failure patterns with symptom → cause → investigation → fix. Match t
    ```
 4. Verify the resource's tags in the Resource Catalog match the selector's tag filter.
 
-**Fix:** Cause 1 → broaden selector or add a new policy covering the gap. Cause 2 → update status to `Active`. Cause 3 → correct tags on resource or policy. Cause 4 → reframe deny intent as allow-only (see [plugins/tags/planning.md — Deny-to-Allow flip](../access-policy/plugins/tags/planning.md#deny-to-allow-flip)). Cause 5 → use correct enum values from [plugins/selector/impl.md](../access-policy/plugins/selector/impl.md).
+**Fix:** Cause 1 → broaden selector or add a new policy covering the gap. Cause 2 → update status to `Active`. Cause 3 → correct tags on resource or policy. Cause 4 → reframe deny intent as allow-only (see [plugins/tags/planning.md — Deny-to-Allow flip](../../access-policy/plugins/tags/planning.md#deny-to-allow-flip)). Cause 5 → use correct enum values from [plugins/selector/impl.md](../../access-policy/plugins/selector/impl.md).
 
 ---
 
@@ -165,7 +165,7 @@ Named failure patterns with symptom → cause → investigation → fix. Match t
    uip gov aops-policy deployment user get "$USER_ID" --output json
    ```
 
-**Fix:** Cause 1 → deploy a policy via [aops-policy-deploy-guide.md](../aops-policy/aops-policy-deploy-guide.md). Cause 2 → redeploy to the correct tenant. Cause 3 → use the product `name` (not label) from `product list`. Cause 4 → remove the `null` override or deploy a policy at a broader scope.
+**Fix:** Cause 1 → deploy a policy via [aops-policy-deploy-guide.md](../../aops-policy/aops-policy-deploy-guide.md). Cause 2 → redeploy to the correct tenant. Cause 3 → use the product `name` (not label) from `product list`. Cause 4 → remove the `null` override or deploy a policy at a broader scope.
 
 ---
 
@@ -198,4 +198,4 @@ Named failure patterns with symptom → cause → investigation → fix. Match t
    ```
 4. For Access — check error message in response `Data.errors`.
 
-**Fix:** Cause 1 → use `name` from `product list`. Cause 2 → fix JSON (validate with `jq`). Cause 3 → switch to `enforcement: "Allow"`. Cause 4 → add `"values": ["*"]` to selector entries. Cause 5 → choose a different name. Cause 6 → regenerate from template via [configure-aops-policy-data-guide.md](../aops-policy/configure-aops-policy-data-guide.md).
+**Fix:** Cause 1 → use `name` from `product list`. Cause 2 → fix JSON (validate with `jq`). Cause 3 → switch to `enforcement: "Allow"`. Cause 4 → add `"values": ["*"]` to selector entries. Cause 5 → choose a different name. Cause 6 → regenerate from template via [configure-aops-policy-data-guide.md](../../aops-policy/configure-aops-policy-data-guide.md).