@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-platform/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: uipath-platform
-description: "UiPath platform ops via the uip CLI — use this skill for ANY task hitting UiPath Cloud / Orchestrator / Studio Web / Integration Service / LLM Gateway. Load BEFORE writing any code that calls a UiPath API. Covers auth, folders, assets, queues, storage buckets, bucket files, libraries, webhooks, triggers, processes, jobs, machines, users, roles, sessions, calendars, IS connectors/connections/activities, BYO LLM product configurations (`uip llm-configuration byo-connections` — register / audit / re-probe tenant-owned OpenAI / Azure OpenAI / Bedrock / Vertex / Anthropic keys), traces, licensing. For 'why did X fail' / root-cause / error investigations→uipath-troubleshoot. For `uip solution` lifecycle→uipath-solution. For PDD/SDD design & task planning→uipath-planner. For workflow code (.xaml/.cs)→uipath-rpa, .flow→uipath-maestro-flow, .bpmn→uipath-maestro-bpmn, agents (.py/agent.json)→uipath-agents, Test Manager→uipath-test."
-when_to_use: "User mentions UiPath / Orchestrator / Studio Web / Integration Service / LLM Gateway / 'uip' CLI / asset / queue / bucket / library / webhook / trigger / connector / connection / tenant / folder / robot / package / BYO LLM. Also 'upload to UiPath', 'create asset', 'start job', 'list queues', 'deploy a single package to Orchestrator', 'OAuth2 token', 'register my own LLM key', 'configure a model substitution', 'my BYO LLM key stopped working / returns errors', 're-probe / audit a BYO configuration', 'uipath.com REST'. For `uip solution` ops or `.uipx` deploys→uipath-solution."
+description: "UiPath platform ops via the uip CLI — use for ANY task hitting UiPath Cloud / Orchestrator / Studio Web / Integration Service / Data Fabric / LLM Gateway. Load BEFORE writing code that calls a UiPath API. Covers auth, folders, assets, queues, storage buckets, libraries, webhooks, triggers, processes, jobs, machines, users, roles, sessions, calendars, IS connectors/connections/activities, Data Fabric entities/records/files/choice-sets (`uip df`), BYO LLM product configurations, context grounding, traces (execution traces and spans + trace feedback / annotation), licensing. For 'why did X fail' / root-cause→uipath-troubleshoot. For `uip solution` lifecycle→uipath-solution. For PDD/SDD design→uipath-planner. For workflow code (.xaml/.cs)→uipath-rpa, .flow (incl. Data Fabric connector nodes)→uipath-maestro-flow, .bpmn→uipath-maestro-bpmn, agents (.py/agent.json)→uipath-agents, Test Manager→uipath-test."
+when_to_use: "User mentions UiPath / Orchestrator / Studio Web / Integration Service / Data Fabric / LLM Gateway / 'uip' CLI / asset / queue / bucket / library / webhook / trigger / connector / connection / tenant / folder / robot / package / entity / record / choice set / trace / span / trace feedback / BYO LLM. Also 'upload to UiPath', 'create asset', 'start job', 'list queues', 'deploy a single package to Orchestrator', 'OAuth2 token', 'list trace spans / add trace feedback', 'create entity', 'add field', 'delete field', 'list entities', 'insert record', 'update record', 'delete record', 'query Data Fabric', 'search records', 'show every <thing> tagged/where', 'filter records by tag/choice/field', 'count by group', 'unique tag combinations', 'group by field', 'aggregate COUNT/SUM/AVG', 'create choice-set', 'create choiceset', 'add choice set values', 'delete choice set', 'upload file attachment', 'import CSV', 'load CSV into entity/list', 'load spreadsheet into entity', 'bulk load records from CSV', 'bulk import from CSV', 'register my own LLM key', 'configure a model substitution', 'my BYO LLM key stopped working / returns errors', 're-probe / audit a BYO configuration', 'uipath.com REST'. For `uip solution` ops or `.uipx` deploys→uipath-solution. For Data Fabric connector nodes inside a `.flow`→uipath-maestro-flow."
 allowed-tools: Bash, Read, Write, Glob, Grep
 ---
 
@@ -21,18 +21,31 @@ If you find yourself about to `curl` `https://cloud.uipath.com/...` — stop. Se
 - "create an asset" → `uip or assets create` (NOT a `POST /odata/Assets`)
 - "start a job for a process" → `uip or jobs start <process-key>` (NOT `POST /odata/Jobs/UiPath.Server.Configuration.OData.StartJobs`)
 - "configure an Integration Service connection" → `uip is connections create <connector-key>` (NOT a hand-rolled OAuth flow)
+- "attach a file to a Data Fabric record" → `uip df files upload <entity-id> <record-id> <field-name> --file <path>` (NOT `records insert` / `records update` with the file value — the platform silently strips FILE columns and returns Success, see `references/data-fabric/data-fabric.md` Rule 6)
 
 ## When to Use This Skill
 
 Load this skill BEFORE writing any code that talks to UiPath. Specific triggers:
 
-- **Auth & tenant**: login, logout, switch tenant, `~/.uipath/.auth`, OAuth token, organization
+- **Auth & tenant**: login, logout, switch tenant, named login profiles via `--profile <name>`, `~/.uipath/.auth`, OAuth token, organization
 - **Orchestrator core**: folders (`list/get/create/edit/move/delete/runtimes`), processes/releases, jobs (`start/stop/logs/traces/healing-data`), packages (`upload/download/versions`), machines, users / roles / sessions (incl. DirectoryUser/DirectoryGroup/DirectoryRobot/DirectoryExternalApplication), licenses, calendars, settings, audit logs, credential stores, feeds, attachments
 - **Resources (Orchestrator-scoped)**: assets (text/integer/bool/credential), queues + queue items, storage buckets + bucket files (`upload/download/get-download-url/get-upload-url`), libraries (`.nupkg`), webhooks (HMAC signing), triggers (time/queue/api)
 - **Integration Service**: connectors, connections (OAuth flow), activities, IS triggers, agent-workflow reference resolution
+- **Data Fabric (`uip df`)**: UiPath's structured, typed data store. Surfaces:
+  - **Entities** — schemas with typed columns, per-type constraints (`lengthLimit`, `minValue` / `maxValue`, `decimalPrecision`), choice-set / relationship / file fields, `addFields` / `updateFields` / `removeFields` evolution.
+  - **Records** — insert / update / delete / list / get / `query` with server-side filters, sorting, pagination, group-by, and aggregates (`COUNT`, `SUM`, `AVG`, `MIN`, `MAX`).
+  - **Files** — binary attachments stored on `FILE`-typed fields via `files upload / download / delete` (record-level writes silently strip FILE values; the dedicated verbs are mandatory).
+  - **Choice sets** — shared enumerations consumed by `CHOICE_SET_SINGLE` / `CHOICE_SET_MULTIPLE` fields; values use immutable integer `NumberId`s, not labels.
+  - **Folder scoping** — tenant-level OR folder-scoped via `--folder-key <GUID>` on every write, `--include-folders` on `entities list` / `choice-sets list`.
+  - **CSV bulk import** — `uip df records import <entity-id> --file <path.csv> --output json`. Basic field types only; complex fields (CHOICE_SET, RELATIONSHIP, FILE, AUTO_NUMBER) require `records insert --file <json>`.
+
+  **Before issuing any `uip df` command, load [`references/data-fabric/data-fabric.md`](references/data-fabric/data-fabric.md).** That file carries the Critical Rules (folder-scope prompt flow, irreversible-op gates, complex-field config), the exact request-body schema, the per-type operator support matrix, and routes to topic files: [`entity-schema.md`](references/data-fabric/entity-schema.md), [`records-query.md`](references/data-fabric/records-query.md), [`filter-platform-contract.md`](references/data-fabric/filter-platform-contract.md), [`choice-sets.md`](references/data-fabric/choice-sets.md), [`file-attachments.md`](references/data-fabric/file-attachments.md), [`bulk-import.md`](references/data-fabric/bulk-import.md).
+
+  For Query / Create / Update / Delete / GetById connector nodes **inside a `.flow`**, hand off to `uipath-maestro-flow` — that skill owns the in-flow node JSON, `bindings_v2.json`, and connection-resource layout.
 - **LLM Gateway — BYO product configurations**: `uip llm-configuration byo-connections` (`list / get / create / update / delete / list-product-configs`). Register tenant-owned OpenAI / Azure OpenAI / AWS Bedrock / Google Vertex / Anthropic / OpenAI-compatible keys against UiPath product features (agents, agenthub, jarvis, IXP, agent builder, ECS). Two input shapes: single-mapping (for `AnyModelWithOwnAdditions` features) and repeated `--mapping` (required for `AllModels` / `AnyModel`). Server-side validation is mandatory.
 - **LLM Gateway — diagnose a failing BYO config**: re-probe the underlying IS connection with `byo-connections get <id> --force-refresh`, force a fresh server-side probe with an idempotent `update`, audit the tenant with `list --include-connection-details` filtered on `connectionState != Enabled`, check catalog drift with `list-product-configs`, and cross-reference trace evidence with `uip traces spans get <trace-id>`. The gateway does **not** expose per-request invocation logs via CLI — diagnosis is current-state + trace evidence only. See [`references/llmgateway/byo-connections.md` § Diagnostics](references/llmgateway/byo-connections.md#diagnostics). For tenant-wide AI Trust Layer policy that may be overriding routing, see [uipath-governance](/uipath:uipath-governance).
-- **Traces**: `uip traces spans get [trace-id]` (LLM/agentic execution observability)
+- **Traces**: `uip traces spans get <trace-id>` (LLM/agentic execution observability)
+- **Context grounding**: knowledge indexes for semantic search / RAG — `uip context-grounding` (`list / create` from a bucket or connection `/ ingest / retrieve` to poll ingestion status `/ search / delete`). Agents and flows consume these indexes as tools. See [`references/context-grounding/index-management.md`](references/context-grounding/index-management.md).
 - **Platform licensing**: tenant license allocations, user/group bundle assignments, consumables reporting (`uip platform tenants licenses`, `users licenses`, `groups rules`, `licenses consumables`)
 - **CLI tooling itself**: `uip tools list/search/install`, `uip mcp serve`
 
@@ -40,7 +53,7 @@ For `uip solution` lifecycle (init / pack / publish / deploy / activate / upload
 
 ## Auth token location
 
-The CLI stores credentials at **`~/.uipath/.auth`** after login:
+The default login stores credentials at **`~/.uipath/.auth`**:
 ```
 UIPATH_URL=https://alpha.uipath.com
 UIPATH_ORGANIZATION_NAME=my_org
@@ -50,7 +63,22 @@ UIPATH_ORGANIZATION_ID=...
 UIPATH_TENANT_ID=...
 ```
 
-This token can be reused for direct Orchestrator REST API calls when CLI commands don't cover a use case.
+Named profiles store credentials at **`~/.uipath/profiles/<name>/.auth`**. Use named profiles when the user asks to keep multiple UiPath logins on the same machine:
+
+```bash
+uip login --profile dev --output json
+uip login status --profile dev --output json
+uip login which --profile dev --output json
+```
+
+Rules:
+- `--profile <name>` is a global option. Pass it on every `uip` command that should use that login, for example `uip --profile dev or folders list --output json`.
+- `default` means the built-in unprofiled login and maps back to `~/.uipath/.auth`.
+- Profile names may contain only letters, numbers, `.`, `_`, and `-`. Never use paths like `../prod`.
+- `--profile` and auth-command `--file <folder>` are mutually exclusive. Use one or the other.
+- A missing named profile does not fall back to `~/.uipath/.auth` or Robot credentials. Tell the user to run `uip login --profile <name>`.
+
+These tokens can be reused for direct Orchestrator REST API calls when CLI commands don't cover a use case. If a named profile is active, read the path from `uip login which --profile <name> --output json` rather than assuming `~/.uipath/.auth`.
 
 ## Quick Start
 
@@ -65,11 +93,21 @@ uip login status --output json
 
 If it reports `Logged in`, skip the rest of this step. There is no `--check` flag — `status` is the verification subcommand.
 
+If the user names a profile, check that profile explicitly:
+```bash
+uip login status --profile dev --output json
+```
+
 **Interactive login (browser OAuth2):** `uip login` opens a browser window on the user's machine and blocks until they complete it. In a non-interactive or automated session, do NOT run it yourself — tell the user to run it and wait.
 ```bash
 uip login --output json
 ```
 
+For a named interactive login:
+```bash
+uip login --profile dev --output json
+```
+
 For a custom authority (e.g., alpha.uipath.com):
 ```bash
 uip login --authority "https://alpha.uipath.com/identity_" --it --output json
@@ -118,6 +156,13 @@ Choose the appropriate operation from the Task Navigation table below. For `uip
 | **Debug LLM/agent traces (spans)** | [references/traces/traces.md](references/traces/traces.md) |
 | **Annotate traces with feedback** | [references/traces/feedback.md](references/traces/feedback.md) |
 | **Use Integration Service** | [references/integration-service/integration-service.md](references/integration-service/integration-service.md) |
+| **Use Data Fabric — entities, records, files, choice sets** | [references/data-fabric/data-fabric.md](references/data-fabric/data-fabric.md) |
+| **Build an entity schema / add fields / complex field types** | [references/data-fabric/entity-schema.md](references/data-fabric/entity-schema.md) |
+| **Query records — filters, pagination, aggregates, choice/relationship semantics** | [references/data-fabric/records-query.md](references/data-fabric/records-query.md) |
+| **Filter operator support matrix per field type** | [references/data-fabric/filter-platform-contract.md](references/data-fabric/filter-platform-contract.md) |
+| **Manage choice sets and choice-set values** | [references/data-fabric/choice-sets.md](references/data-fabric/choice-sets.md) |
+| **Upload / download / delete file attachments on records** | [references/data-fabric/file-attachments.md](references/data-fabric/file-attachments.md) |
+| **Bulk import records from CSV** | [references/data-fabric/bulk-import.md](references/data-fabric/bulk-import.md) |
 | **Configure BYO LLM keys (OpenAI / Azure OpenAI / Bedrock / Vertex / Anthropic)** | [references/llmgateway/byo-connections.md](references/llmgateway/byo-connections.md) |
 | **Diagnose / audit / re-probe a BYO LLM configuration** | [references/llmgateway/byo-connections.md#diagnostics](references/llmgateway/byo-connections.md#diagnostics) |
 | **Allocate licenses to tenants** | [references/licensing/tenant-allocations.md](references/licensing/tenant-allocations.md) |
@@ -212,7 +257,7 @@ The UiPath CLI (`uip`) is a unified command-line tool for interacting with the U
 | **Orchestrator** | `or` | Folders, jobs, processes, releases | Available |
 | **Resource** | `resource` | Assets, queues, queue items, storage buckets, bucket files | Available |
 | **Integration Service** | `is` | Connectors, connections, activities, resources | Available |
-| **Test Manager** | `tm` | Test projects, test sets, test cases, executions, reports | Available |
+| **Data Fabric** | `df` | Entities, records, files, choice sets (`@uipath/data-fabric-tool`) | Available |
 | **Tools** | `tools` | CLI tool extension management | Available |
 | **MCP** | `mcp` | Model Context Protocol server | Available |
 | **Coded Agents** | `codedagent` | Python agent lifecycle (setup, exec) | Available |
@@ -226,6 +271,7 @@ Every `uip` command accepts:
 |---|---|---|
 | `--output <format>` | Output format: `table`, `json`, `yaml`, `plain` | `table` (interactive), `json` (non-interactive) |
 | `--output-filter <expression>` | JMESPath expression to filter JSON output | -- |
+| `--profile <name>` | Use a named auth profile from `~/.uipath/profiles/<name>/.auth` | built-in default login |
 | `--verbose` | Enable verbose/debug logging | Off |
 | `--help` / `-h` | Display help for the command | -- |
 | `--version` / `-v` | Display CLI version | -- |
@@ -252,6 +298,7 @@ Every `uip` command accepts:
 - **[Traces — Spans](references/traces/traces.md)** — LLM execution trace observability
 - **[Traces — Feedback](references/traces/feedback.md)** — Annotate traces with sentiment and comments
 - **[Integration Service](references/integration-service/integration-service.md)** — Connectors, connections, activities, resources
+- **[Data Fabric](references/data-fabric/data-fabric.md)** — Entity schemas, records CRUD, query filters and aggregates, choice sets, file attachments, CSV bulk import, folder scoping
 - **[LLM Gateway — BYO Connections](references/llmgateway/byo-connections.md)** — Register tenant-owned LLM keys against UiPath products
 - **[Licensing](references/licensing/licensing.md)** — Tenant allocations, user/group bundles, consumables reporting
 - **[Coded Workflows](/uipath:uipath-rpa)** — Building coded automation projects

package/skills/uipath-platform/references/context-grounding/index-management.md

@@ -0,0 +1,123 @@
+# Managing Context Grounding Indexes — `uip context-grounding` CLI
+
+Operate context-grounding indexes from the terminal: list, create, ingest, poll status, search, delete. Context-grounding indexes back semantic search / RAG over your organization's documents; agents and flows consume them as tools.
+
+## Folder Targeting
+
+Every command needs a folder. Pass `--folder-path "<PATH>"` (e.g. `"Shared"`) or `--folder-key "<UUID>"`, or set `UIPATH_FOLDER_PATH`. Missing folder → `400 "A folder is required for this action."` Permissions live on the folder; missing index permission → `403 "User is missing required index permissions."` (switch folders; personal workspace is the safe default for self-serve).
+
+## JSON Output
+
+Append `--output json` to any command whose output you parse — it is parsed throughout this guide. Equivalent per-command flag: `--format json`. `-o <FILE>` writes the result to a file instead of stdout.
+
+## List Indexes
+
+```bash
+uip context-grounding list --folder-path "<FOLDER_PATH>" --output json
+```
+
+Returns an array of index objects (`id`, `name`, `last_ingestion_status`, `data_source`, …). Use to confirm an index exists and resolve its name before `retrieve` / `search` / `ingest`.
+
+## Create an Index
+
+Creation does **not** ingest — trigger ingestion separately (see [Ingest](#trigger-ingestion)).
+
+### Bucket-backed
+
+```bash
+uip context-grounding create \
+  --index-name "<INDEX_NAME>" \
+  --bucket-source "<BUCKET_NAME>" \
+  --folder-path "<FOLDER_PATH>" \
+  --output json
+```
+
+Optional: `--description "<TEXT>"`, `--file-type pdf` (filter ingested files), `--extraction-strategy LLMV4|NativeV1` (default `LLMV4`).
+
+### Connection-backed (Google Drive / OneDrive / Dropbox / Confluence)
+
+1. Inspect the required JSON shape:
+
+   ```bash
+   uip context-grounding source-schema --type google_drive
+   ```
+
+   Omit `--type` to print all schemas. Types: `google_drive`, `onedrive`, `dropbox`, `confluence`.
+
+2. Write the source config to a file, then:
+
+   ```bash
+   uip context-grounding create \
+     --index-name "<INDEX_NAME>" \
+     --source-file "<CONFIG>.json" \
+     --folder-path "<FOLDER_PATH>" \
+     --output json
+   ```
+
+`--bucket-source` and `--source-file` are mutually exclusive — pick one.
+
+## Trigger Ingestion
+
+Re-index after its source documents change. Runs asynchronously.
+
+```bash
+uip context-grounding ingest --index-name "<INDEX_NAME>" --folder-path "<FOLDER_PATH>" --output json
+```
+
+## Poll Status
+
+`retrieve` returns the full index object including ingestion status. This is how you check whether an index is ready.
+
+```bash
+uip context-grounding retrieve --index-name "<INDEX_NAME>" --folder-path "<FOLDER_PATH>" --output json
+```
+
+Read `last_ingestion_status` from the JSON:
+
+| `last_ingestion_status` | Meaning | Action |
+|---|---|---|
+| `Successful` | Ready | Proceed — search the index |
+| `Failed` | Ingestion failed | Stop; read `last_ingestion_failure_reason` |
+| anything else | In progress | Keep polling |
+
+Polling loop — re-`retrieve` until the status is terminal (`Successful` or `Failed`); cap retries (e.g. 30 polls at a fixed interval) and abort with the failure reason if it never reaches `Successful`. Other useful fields: `last_ingested`, `index_health.overall_health_score`, `data_source`.
+
+## Search an Index
+
+Semantic search over a fully-ingested index.
+
+```bash
+uip context-grounding search \
+  --index-name "<INDEX_NAME>" \
+  --query "<NATURAL_LANGUAGE_QUERY>" \
+  --folder-path "<FOLDER_PATH>" \
+  --limit 5 \
+  --output json
+```
+
+Optional: `--limit <N>` (default 10), `--threshold <0.0-1.0>` (minimum similarity, default 0.0). Returns ranked snippets with scores. Empty results → broaden the query, lower `--threshold`, or confirm ingestion succeeded.
+
+## Delete an Index
+
+```bash
+# Preview without deleting
+uip context-grounding delete --index-name "<INDEX_NAME>" --folder-path "<FOLDER_PATH>" --dry-run --output json
+
+# Delete without the confirmation prompt
+uip context-grounding delete --index-name "<INDEX_NAME>" --folder-path "<FOLDER_PATH>" --confirm --output json
+```
+
+Always `--dry-run` first to confirm the target. `--confirm` skips the interactive prompt — required for non-interactive/agent runs.
+
+## End-to-End: Stand Up a Searchable Index
+
+1. `create --index-name X --bucket-source B --folder-path F` — create empty index.
+2. `ingest --index-name X --folder-path F` — start ingestion.
+3. `retrieve --index-name X --folder-path F` — poll `last_ingestion_status` until `Successful`.
+4. `search --index-name X --query "..." --folder-path F` — query.
+
+## Anti-patterns
+
+- **Searching before ingestion finishes.** `create` does not ingest, and `ingest` is async. Always poll `retrieve` for `last_ingestion_status: Successful` first.
+- **Omitting the folder.** → `400 "A folder is required for this action."` Pass `--folder-path`/`--folder-key` or set `UIPATH_FOLDER_PATH`.
+- **`delete` without `--confirm` in an agent run.** The interactive prompt hangs. Use `--dry-run` to preview, then `--confirm` to execute.

package/skills/uipath-platform/references/data-fabric/bulk-import.md

@@ -0,0 +1,86 @@
+# Bulk Import Reference
+
+> **Creating the entity FROM the CSV?** If no entity exists yet and the user wants one built around the CSV's columns, that's `entities create` — and field types must be **confirmed, not silently inferred**. See [`data-fabric.md` Rule 14 → CSV / sample-data inference](data-fabric.md#critical-rules). Flag every inferred type with the sample value(s) it came from, surface ambiguous columns (date-shaped strings, `0`/`1` flags, UUID-shaped strings, decimal precision) as `AskUserQuestion` dropdowns, and wait for explicit user approval before invoking `entities create`. *Then* `records import` to load the data.
+
+> **⚠ `records import` does not support complex field types — surface this to the user before invoking (data-fabric.md Rule 20).** `CHOICE_SET_SINGLE`, `CHOICE_SET_MULTIPLE`, `RELATIONSHIP`, `FILE`, and `AUTO_NUMBER` columns are **not supported**: the CSV header is accepted but the values are ignored (no error, no `ErrorFileLink` entry — `null` on every imported row, or row failure if the field is `isRequired` without a `defaultValue`). This is current Data Fabric platform behavior, not a bug — do not work around it. Run `entities get <entity-id>` first; if any field is in that set, switch to `records insert --file <json>` (handles all types except `FILE` — use `files upload` for those, see Rule 6). See [Complex Field Types Not Supported](#complex-field-types-not-supported) below.
+
+## Import Records from CSV
+
+```bash
+uip df records import <entity-id> --file data.csv [--folder-key <folder-guid>] --output json
+```
+
+Response: `{ Code: "RecordsImported", Data: { InsertedRecords, TotalRecords, ErrorFileLink? } }`
+
+- `InsertedRecords` — number of rows successfully imported
+- `TotalRecords` — total rows in the CSV (including failures)
+- `ErrorFileLink` — download URL for a CSV of failed rows (only present if there were failures)
+- `--folder-key` — required when the parent entity is folder-scoped (CLI ≥ `1.197.0`)
+
+**Pre-flight check (required by Rule 20):**
+
+```bash
+# Inspect schema before importing — tell the user which columns will be dropped
+uip df entities get <entity-id> --output json
+# Flag every field whose Fields[].fieldDataType.Name ∈ {CHOICE_SET_SINGLE, CHOICE_SET_MULTIPLE, RELATIONSHIP, FILE, AUTO_NUMBER}
+```
+
+## CSV Format Requirements
+
+- **Header row is required** and must exactly match entity field names (case-sensitive)
+- Use `uip df entities get <entity-id> --output json` to discover exact field names before importing
+- System fields (`Id`, `CreatedBy`, `CreateTime`, `UpdatedBy`, `UpdateTime`) must NOT appear in the CSV
+
+### Example CSV
+
+```csv
+Name,Score,Active,CreatedDate
+Alice,95,true,2024-01-15
+Bob,82,true,2024-02-20
+Charlie,74,false,2024-03-05
+```
+
+For an entity with fields: `Name` (STRING), `Score` (DECIMAL, `decimalPrecision: 0`), `Active` (BOOLEAN), `CreatedDate` (DATE).
+
+### Complex Field Types Not Supported
+
+**Complex field types** in Data Fabric are the ones that need extra config or lookup tokens beyond the value itself: `CHOICE_SET_SINGLE`, `CHOICE_SET_MULTIPLE`, `RELATIONSHIP`, `FILE`, and `AUTO_NUMBER`. Everything else is a Basic type.
+
+`records import` is **not supported** for those complex types — it only processes Basic types (use the UI-compatible set from [`entity-schema.md`](entity-schema.md#supported-field-types)). Complex-type columns are accepted in the CSV header but their row values are ignored — no error, nothing in `ErrorFileLink`, just `null` on every imported row (or row failure if the field is `isRequired` without a `defaultValue`).
+
+For entities with any complex field, use `records insert --file <json>` instead — the insert endpoint handles every type except `FILE` (which is exclusively written through `files upload`, data-fabric.md Rule 6). See [`records-query.md`](records-query.md#writing-choice-set-and-relationship-values) for the value form.
+
+## Full Workflow
+
+```bash
+# 1. Discover entity and field names
+uip df entities list --output json
+uip df entities get <entity-id> --output json   # note exact field names
+
+# 2. Create CSV with matching headers
+cat > /tmp/data.csv <<EOF
+Name,Score,Active
+Alice,95,true
+Bob,82,true
+EOF
+
+# 3. Import
+uip df records import <entity-id> --file /tmp/data.csv --output json
+
+# 4. Verify
+uip df records list <entity-id> --output json
+```
+
+## Error Handling
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Import errors in CSV` | Header names don't match field names | Run `entities get` and check exact field names (case-sensitive) |
+| `Entity not found` | Wrong entity ID | Run `entities list` to get correct ID |
+| Row-level errors | Invalid data types (e.g. text in number field) | Check data values match field types |
+
+## Notes
+
+- Partial success is possible: some rows may import while others fail
+- Check `InsertedRecords` vs `TotalRecords` to detect failures; download `ErrorFileLink` for the failed-row CSV
+- Large imports are processed server-side; there is no row limit documented but keep files reasonable in size

package/skills/{uipath-data-fabric/references → uipath-platform/references/data-fabric}/choice-sets.md

@@ -2,20 +2,36 @@
 
 Reusable picklists that back `CHOICE_SET_SINGLE` and `CHOICE_SET_MULTIPLE` entity fields. Full CRUD via CLI — sets and their values.
 
-> **Preview-then-confirm gate (SKILL.md Rule 14).** Before invoking `choice-sets create` or `choice-set-values create`, show the full proposed set — name, displayName, description, and every value (`Name` + `DisplayName`) in creation order — and wait for explicit user approval. Value order matters: `NumberId` is assigned 0-based by creation order and is immutable.
+> **Preview-then-confirm gate (data-fabric.md Rule 14).** Before invoking `choice-sets create` or `choice-set-values create`, show the full proposed set — name, displayName, description, and every value (`Name` + `DisplayName`) in creation order — and wait for explicit user approval. Value order matters: `NumberId` is assigned 0-based by creation order and is immutable.
 
 ## Commands
 
+Every command below accepts `--folder-key <GUID>` for folder-scoped choice sets — required on writes against a folder-scoped set, recommended on reads. `list` additionally accepts `--include-folders` (mutually exclusive with `--folder-key`). See [Folder scope](#folder-scope) below for the picker rules. CLI floor: `@uipath/data-fabric-tool@1.197.0+`.
+
 | Command | Use |
 |---------|-----|
-| `uip df choice-sets list --output json` | Find an existing choice set's `Id` |
-| `uip df choice-sets list-values <choice-set-id> --output json` | Page through values; pagination `{ Items, TotalCount, HasNextPage, … }` (use `--limit` / `--cursor` / `--offset`) |
-| `uip df choice-sets create <name> [--display-name <…>] [--description <…>] --output json` | Create a choice set; response `Code: ChoiceSetCreated`, `Data.Id` |
-| `uip df choice-sets update <choice-set-id> [--display-name <…>] [--description <…>] --output json` | Rename / re-describe the set |
-| `uip df choice-sets delete <choice-set-id> --confirm --reason "<why>" --output json` | Irreversible — `--confirm` and `--reason` are required |
-| `uip df choice-set-values create <choice-set-id> <name> [--display-name <…>] --output json` | Add a value; server assigns `NumberId` (0-based, monotonic by creation order) |
-| `uip df choice-set-values update <choice-set-id> <value-id> "<new display name>" --output json` | Display-name only — `Name` and `NumberId` are immutable |
-| `uip df choice-set-values delete <choice-set-id> --ids <value-id>[,<value-id>…] --confirm --reason "<why>" --output json` | Irreversible — same gating as `choice-sets delete` |
+| `uip df choice-sets list [--folder-key <…> \| --include-folders] --output json` | Find an existing choice set's `Id`. No flags → tenant only; `--folder-key` → that folder only; `--include-folders` → tenant + every visible folder. Each row carries `FolderId`. |
+| `uip df choice-sets list-values <choice-set-id> [--folder-key <…>] --output json` | Page through values; pagination `{ Items, TotalCount, HasNextPage, … }` (use `--limit` / `--cursor` / `--offset`) |
+| `uip df choice-sets create <name> [--folder-key <…>] [--display-name <…>] [--description <…>] --output json` | Create a choice set; response `Code: ChoiceSetCreated`, `Data.Id`. **Scope-bound**: pass `--folder-key` to place inside a folder; omit for tenant level. |
+| `uip df choice-sets update <choice-set-id> [--folder-key <…>] --display-name <…> --description <…> --output json` | Rename / re-describe the set. **Both `--display-name` and `--description` are required on every call** — sending only `--description` returns *"DisplayName is required."*; sending only `--display-name` returns `Internal Server Error`. To change one, re-send the other's current value (run `choice-sets list` first to read it). |
+| `uip df choice-sets delete <choice-set-id> [--folder-key <…>] --yes --reason "<why>" --output json` | Irreversible — `--yes` and `--reason` are required (`--confirm` accepted as deprecated alias) |
+| `uip df choice-set-values create <choice-set-id> <name> [--folder-key <…>] [--display-name <…>] --output json` | Add a value; server assigns `NumberId` (0-based, monotonic by creation order) |
+| `uip df choice-set-values update <choice-set-id> <value-id> "<new display name>" [--folder-key <…>] --output json` | Display-name only — `Name` and `NumberId` are immutable |
+| `uip df choice-set-values delete <choice-set-id> --ids <value-id>[,<value-id>…] [--folder-key <…>] --yes --reason "<why>" --output json` | Irreversible — same gating as `choice-sets delete` |
+
+## Folder scope
+
+Choice sets live at the tenant level or inside a folder. The flag matrix mirrors entities:
+
+| Goal | Flags |
+|---|---|
+| List only tenant-level choice sets | (none) — default |
+| List a single folder's choice sets | `--folder-key <folder-guid>` |
+| List tenant + every folder you can see | `--include-folders` |
+| Create/update/delete a folder-scoped set or value | `--folder-key <folder-guid>` (required) |
+| Read or operate on a tenant-scoped set | `--folder-key` is harmless when passed; the server resolves by UUID |
+
+Bind a folder-scoped choice set to an entity in a different folder by passing only `choiceSetId` — the server resolves the choice-set's folder from that UUID. Do NOT pass `referenceFolderKey` on `CHOICE_SET_*` fields. The tenant ↔ folder boundary still applies (folder parent cannot bind a tenant-level choice set, and vice versa). See [`entity-schema.md` → Cross-folder references](entity-schema.md#cross-folder-references).
 
 ## Use the IDs
 
@@ -25,9 +41,14 @@ Reusable picklists that back `CHOICE_SET_SINGLE` and `CHOICE_SET_MULTIPLE` entit
 
 ## Value `Name` validation
 
-A choice-set value's `Name` must be alphanumeric, start with a letter, and avoid SQL / C# / VB reserved keywords — same rule as entity / field names (**SKILL.md Rule 4**). Domain words that commonly collide: `internal`, `public`, `private`, `class`, `case`, `new`, `default`, `static`, `void`, `event`, `lock`, `object`, `string`, `int`.
+A choice-set value's `Name` must be alphanumeric and start with a letter. The server rejects C# / VB reserved keywords with *"Choiceset member name must … not be C# keyword"* — but this is a **separate code path from the entity/field-name validator (data-fabric.md Rule 4)**, and the two behave differently:
+
+| Aspect | Entity / field name (Rule 4) | Choice-set value `Name` (here) |
+|---|---|---|
+| Case match | **case-insensitive** (`Class`, `class`, `CLASS` all rejected) | **case-sensitive** (`class` rejected, `Class` may pass — empirically verified: `New` accepted while `new` would be rejected) |
+| Keyword list | full C#/VB reserved list — incl. `Select`, `Return`, `New`, `Internal`, … | partial list — some keywords missing (empirically `select` is NOT rejected as a choice-set value, but `Select` IS rejected as a field name) |
 
-When a desired label is reserved, namespace the system `Name` and leave `DisplayName` unchanged: `Name: "internal_audit"` with `DisplayName: "Internal"`. The dropdown shows "Internal"; the validator sees `internal_audit`.
+Do not assume a name is legal in one place because it's legal in the other. The safe, portable convention for choice-set value `Name`s: **all-lowercase, snake_case, namespaced to dodge the C# keyword list outright** — `internal_audit`, `new_lead`, `class_a`. Move the human label to `DisplayName`: `Name: "internal_audit"` with `DisplayName: "Internal"`. The dropdown shows "Internal"; the validator sees `internal_audit`. Lowercase tokens that the choice-value validator does reject: `internal`, `public`, `private`, `class`, `case`, `new`, `default`, `static`, `void`, `event`, `lock`, `object`, `string`, `int`.
 
 ## Sourcing `NumberId` after batch value creates
 
@@ -132,7 +153,7 @@ Never fall back to `STRING`. Never auto-create without confirming the values.
 ## Deleting a choice set
 
 ```bash
-uip df choice-sets delete <choice-set-id> --confirm --reason "<why>" --output json
+uip df choice-sets delete <choice-set-id> [--folder-key <…>] --yes --reason "<why>" --output json
 ```
 
 Irreversible. Before invoking, run `entities list --output json` and find every entity whose `Fields[].ChoiceSetId == <choice-set-id>`. Surface those entities to the user and ask: *"This choice set is used by `<entity>.<field>` — delete it anyway (those fields will break), pick a replacement choice set, or stop?"* Apply only what the user confirms.