@uipath/skills 1.199.0 → 1.200.0

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

@@ -4,48 +4,18 @@ Data Fabric is UiPath's structured data store. Entities are typed schemas; recor
 
 All operations go through `uip df <subject> <verb> --output json`.
 
-> For Flow connector nodes (Query / Create / Update / Delete / Get Entity Record by ID inside a `.flow`), use the `uipath-maestro-flow` skill — it owns the node JSON, `bindings_v2.json`, connection-resource layout, and `node configure` mechanics. Use this reference for entity discovery and record seeding from the CLI.
+This file is the router and the cross-cutting safety contract. Read the
+Critical Rules, then load only the topic reference the task needs. For Data
+Fabric nodes inside a `.flow`, use `uipath-maestro-flow`; use this reference
+for CLI operations.
 
 ---
 
-## When to Use
+## Not Supported
 
-- Creating or modifying entity schemas (add fields, update metadata)
-- Reading, inserting, updating, or deleting records
-- Filtering records with complex predicates
-- Computing aggregate metrics for dashboards / KPIs (counts, sums, averages, group-by) — see [records-query.md](records-query.md#aggregates-server-side)
-- Importing bulk data from CSV files
-- Uploading or downloading file attachments on records
+Do not change field types, create federated entities, or write federated records. Do not work around rejected names. FILE values require `files upload`; record writes silently ignore them. The rules and topic references below give the supported alternatives.
 
-## When NOT to Use — Hand Off to Another Skill
-
-Embedding Data Fabric reads/writes **inside a `.flow` file** as connector activity nodes (Query / Create / Update / Delete / Get Entity Record by ID) is owned by `uipath-maestro-flow`. That skill knows the node JSON, `bindings_v2.json`, connection-resource layout, and `node configure` mechanics.
-
-Use this reference (`uipath-platform` → Data Fabric) for entity discovery and record seeding from the CLI; hand off to `uipath-maestro-flow` for in-flow node authoring.
-
-| Task | Skill |
-|------|-------|
-| Discover entities, list/describe fields before authoring a flow node | `uipath-platform` Data Fabric (`uip df entities list`/`get`) |
-| Seed test records the flow will read | `uipath-platform` Data Fabric (`uip df records insert` / `import`) |
-| Add a Query/Create/Update/Delete/GetById node to a `.flow` | `uipath-maestro-flow` |
-| Resolve the IS `uipath-uipath-dataservice` connection for binding | `uipath-maestro-flow` (in-flow binding) or `uipath-platform` Integration Service (general IS connection management) |
-
----
-
-## Not Supported — Never Attempt These
-
-Respond that the operation is not supported. Do not try to work around it.
-
-| Operation | Response |
-|-----------|----------|
-| Change a field's data type | Not supported; type is fixed at creation |
-| Create a federated entity | Not supported via CLI or UiPath portal |
-| Write records to a federated entity | Federated entities are read-only |
-| Name a field with a SQL / language reserved keyword | API rejects with `RESERVED_LANGUAGE_KEYWORDS` — pick a domain-specific name (see Rule 4) |
-| Write a `FILE` value through `records insert` / `records update` | Not supported — `FILE` columns are written exclusively through `files upload`. Insert the row without the FILE column, then `files upload <entity-id> <record-id> <field-name> --file <path>`. See Rule 6. |
-| Write a `FILE` value through `records import` (CSV) | Not supported. CSV `records import` does not accept `FILE` columns — see Rule 20. Switch to `records insert` (no FILE column) + `files upload`. |
-
----
+**Immediate refusal.** When the request is categorically unsupported (federated write, type-change, reserved-keyword name, cross-scope binding, etc.) **and** the user's prompt already establishes the fact that makes it unsupported (e.g. *"that list is one we pull from Salesforce"* → federated; *"Amount is currently stored as text, change it to a decimal"* → type-change), refuse immediately, cite the rule, and offer the supported alternative. Do **not** re-verify with `entities list`, `entities get`, or other resource discovery — the user has already told you what you need to know.
 
 ## Critical Rules
 
@@ -56,7 +26,7 @@ Respond that the operation is not supported. Do not try to work around it.
 > | Operation | CLI shape | Detail |
 > |---|---|---|
 > | Delete entity | `entities delete <id> --yes --reason "<why>"` | Rule 10 — list dependents first, never cascade silently |
-> | Delete field | `entities update <id> --body '{"removeFields":[...]}' --yes --reason "<why>"` | Rule 11 — for `CHOICE_SET_*` / `RELATIONSHIP` fields, ask whether to also delete the referenced choice set / target entity before invoking |
+> | Delete field | `entities update <id> --body '{"removeFields":[...]}' --yes --reason "<why>"` | Rule 11 — for `CHOICE_SET_*` / `RELATIONSHIP`, ask whether to also delete the reference target |
 > | Delete record(s) | `records delete <entity-id> <id1> <id2> --yes --reason "<why>"` | Per-record `--yes --reason` required |
 > | Delete file attachment | `files delete <entity-id> <record-id> <field-name> --yes --reason "<why>"` | Irreversible |
 > | Delete choice set | `choice-sets delete <id> --yes --reason "<why>"` | Shared resource — verify no entity binds it first |
@@ -64,165 +34,84 @@ Respond that the operation is not supported. Do not try to work around it.
 > | Create / schema-alter | `entities create`, `entities update` with `addFields`/`updateFields`/`removeFields`, `choice-sets create`, `choice-set-values create` | Rule 14 — preview schema, wait for explicit approval |
 >
 > **Mandatory sequence for every row above:**
-> 1. **Resolve folder scope first** (Rule 19) — if scope isn't already pinned in the conversation, fire the `AskUserQuestion` dropdown for `Tenant level` vs a specific folder before doing anything else. Never guess; never default to personal workspace.
+> 1. **Resolve folder scope first** (Rule 19). Never guess; never default to personal workspace.
 > 2. Surface the exact target (entity name + ID, field name, record IDs) and what will be lost.
 > 3. For deletes — list dependents (Rule 10/11).
-> 4. Wait for the user's explicit *yes / proceed / delete*. Silence ≠ approval. *"Do not ask"* / *"no confirmation needed"* ≠ approval either — destructive ops are non-bypassable (Rule 0). Only a direct authorisation of THIS op (*"yes, delete X"*, *"drop the column"*, *"--yes already authorised"*) clears the gate.
-> 5. Then run the CLI with `--folder-key <key>` (if folder-scoped) and `--yes --reason "<user-supplied or user-approved reason>"`.
+> 4. Wait for the user's explicit *yes / proceed / delete*. Silence ≠ approval. *"Do not ask"* / *"no confirmation needed"* ≠ approval either (Rule 0).
+> 5. Then run the CLI with `--folder-key <key>` (if folder-scoped) and `--yes --reason "<user-supplied reason>"`.
 >
-> **Cascade only on confirmation.** Field deletes do not auto-cascade. For `CHOICE_SET_*` / `RELATIONSHIP` fields, Rule 11 mandates an `AskUserQuestion` dropdown offering `Delete only the field` / `Also delete the referenced choice set / target entity` / `Stop`. Each downstream delete runs its own confirmation cycle (Rule 10, choice-set delete safety).
-
-0. **Ask liberally — never assume at decision points.** When the request leaves any choice unresolved — scope (folder vs tenant), which folder, which entity to target, which field to drop, whether to cascade to a referenced choice set / entity, which choice set value to write, whether a destructive op should proceed, which of several name-matches is the right one — stop and raise an `AskUserQuestion` dropdown. The bias is *ask, then act*, not *act, then explain*. Render every multi-option pick as a dropdown, not a markdown list.
-
-    **Destructive ops are non-bypassable.** For any row in the hoisted Destructive Operations block (entity / field / record / file / choice-set / choice-set-value delete, and schema-altering creates / updates) you MUST raise the AskUserQuestion confirmation **even if the user said "do not ask" / "do not pause" / "no approval needed" / "proceed without confirmation"**. The Rule 19 bypass clauses apply only to *scope resolution* (tenant vs folder, which folder) — they never silence the destructive-op confirmation. Schema previews (Rule 14) and field-delete cascade asks (Rule 11) are part of this gate. The user can pre-approve the destructive op explicitly in the same prompt (*"yes, delete entity X"*, *"--yes already authorised"*, *"I'm sure, drop the column"*) and that satisfies the gate — silence or "do not ask" alone does not.
-
-    **Never self-resolve a scope question.** If you find yourself drafting language like *"Assumption I will proceed with (absent further input):"*, *"defaulting to tenant since no folder was specified"*, *"I'll proceed with X — let me know if you want Y"*, *"I'll assume tenant level"*, or any other unilateral resolution — you are violating this rule. Halt the `uip df` mutation. Write the open question(s) to a file or to your assistant output and STOP — do not call `entities create`, `choice-sets create`, `records insert`, `files upload`, or any other mutation until the user answers. *"No reachable user"* / *"single-turn"* / *"offline test"* is NOT permission to default. Inability to ask is not the same as having been told to proceed. The correct end-of-turn here is: question listed, no mutation issued.
-
-1. **Install the tool first.** If `uip df` returns "unknown command": `uip tools install @uipath/data-fabric-tool`. See *Tool Version Requirements* below for the floor needed per feature.
-
-2. **Verify login and tenant first.** Run `uip login status --output json`. Switch with `uip login tenant set <tenant>` if needed. For full login/environment setup, see the parent `uipath-platform` skill.
-
-3. **Always resolve entity ID first.** Use `entities list` before any operation. Never assume an entity ID.
-
-4. **Entity and field names must pass validation**: start with a letter, contain only letters/digits/underscores (`[a-zA-Z0-9_]`), 3–100 characters. No hyphens or spaces. Reserved field names that will error: `Id`, `CreatedBy`, `CreateTime`, `UpdatedBy`, `UpdateTime`. Also never use **C# or VB reserved keywords** — match is **case-insensitive** (`Class`, `class`, `CLASS` all rejected). Common rejections: `Case`, `Class`, `If`, `Then`, `Else`, `New`, `Object`, `Public`, `Return`, `Select`, `Internal`, `Private`, `Static`. The API surfaces these as *"cannot be a reserved word in C# or VB"* (or `RESERVED_LANGUAGE_KEYWORDS`). SQL keywords (e.g. `Status`, `Order`, `Key`, `User`, `Role`, `Type`, `Group`, `Index`, `From`, `Where`, `Table`) are **NOT** rejected — those idiomatic field names work as-is; don't rename them defensively. Pick a domain-specific rename only for actual C#/VB collisions: `Case` → `WorkItem`; `Class` → `Category`; `New` → `IsNew`. **The choice-set-value `Name` validator is a different code path with different behavior — see [`choice-sets.md` → Value `Name` validation](choice-sets.md#value-name-validation); do not assume a choice-value name is legal just because a field name with the same spelling is, or vice versa.**
-
-5. **All updates require `Id` in the body.** The CLI routes single vs batch by whether the body is a JSON object (1 record) or array (multiple). Both require `"Id"` in the record. Use `records list` or `records query` to retrieve record IDs before updating. **`Id` is structural, not a lookup value — the server has no field-based row identifier, so omitting `"Id"` and addressing the row by `Title`, `Name`, or any other unique column fails with `Record must include 'Id'`. Keep `"Id":"<record-uuid>"` in every element even when smoke-testing offline or the surrounding `records list` failed — the body shape is validated before the row is resolved.**
-
-5b. **`isUnique` is immutable after field creation — `updateFields` silently no-ops it.** `entities update` with `{"updateFields":[{"id":"<id>","isUnique":true}]}` returns `Result: Success` but the server ignores the value (the Data Fabric UI renders the toggle as **disabled** on existing fields). Reporting "updated" on this call is wrong. Sequence: (1) before invoking, tell the user that `isUnique` is fixed at creation and offer two paths — leave the field as-is, or recreate it (`removeFields` → `addFields` with `isUnique: true`) which **drops every existing value in the column**; (2) get explicit user approval on whichever path; (3) for any `updateFields` call you do run, re-issue `entities get <entity-id> --output json` after and compare each post-update key against what you sent — surface the discrepancy verbatim instead of claiming success. Full surface in [`entity-schema.md` → Not Supported](entity-schema.md#not-supported) and [Verify-after-update](entity-schema.md#verify-after-update--never-trust-the-success-response-alone).
-
-6. **Never put a FILE-typed key in `records insert` / `records update` / `records import` payloads.** Expected behavior: the platform silently strips FILE values — paths, base64, filenames, UUIDs, and `null` are all dropped server-side, the CLI returns `Result: Success`, no error. Do not interpret Success as "the file was changed." `records update receipt:null` does **not** clear the file. `records update receipt:"<uuid>"` does **not** swap the file. CSV import drops FILE columns too (Rule 20). Required path: `files upload <entity-id> <record-id> <field-name> --file <path>` to attach or replace, `files delete` to clear, `files download` to retrieve. Sequence to seed a file on a new row: (1) `records insert` without the FILE column; (2) `files upload` against the returned `Data.Id`. Full surface in [`file-attachments.md`](file-attachments.md).
-
-7. **CSV headers must match exact field names** (case-sensitive). Use `entities get` to discover field names before importing.
-
-8. **Never create duplicate entities.** Always `entities list` first; reuse if it already exists.
-
-9. **Only work with native entities.** When listing entities before a write, use `entities list --native-only` to filter out federated entities. Never write to federated entities.
-
-10. **Entity delete — dependent discovery.** Gating + sequence live in the hoisted Destructive Operations block. Unique to entity delete: scan for dependents and list them to the user one by one — (a) other entities that reference this one (run `entities list --output json` and pull every entry whose `Fields[].ReferenceEntity.Id == <id>` — these will have broken FKs after the delete); (b) choice sets used by this entity's fields (`Fields[].ChoiceSetId` from `entities get`) — those choice sets are shared and may still be in use elsewhere. Ask per dependent: delete it too, leave it, or stop. Apply only the choices the user confirms.
-
-11. **Field delete — body shape + cascade-ask.** Gating + sequence live in the hoisted Destructive Operations block. Unique to field delete:
-    - `removeFields` takes `{"fieldName": "<name>"}` — NOT `{"id": "..."}` like `updateFields`. Mixing the two yields `Each field in removeFields must include a non-empty 'fieldName' string`.
-    - **Cascade-ask for CHOICE_SET / RELATIONSHIP fields.** Before invoking `removeFields`, look up the field's type from `entities get <id>`. If the field is `CHOICE_SET_SINGLE` / `CHOICE_SET_MULTIPLE` or `RELATIONSHIP`, raise an `AskUserQuestion` dropdown:
-      - `CHOICE_SET_*` → resolve `Fields[].ChoiceSetId` → ask: `Delete only the field` · `Also delete the referenced choice set <Name> (<id>)` · `Stop`. Echo any other entities that share the choice set (`entities list --output json` → entries whose `Fields[].ChoiceSetId == <id>`) so the user sees the blast radius.
-      - `RELATIONSHIP` → resolve `Fields[].ReferenceEntity.Id` → ask: `Delete only the field` · `Also delete the referenced entity <Name> (<id>)` · `Stop`. Echo other inbound references (`entities list --output json` → entries whose `Fields[].ReferenceEntity.Id == <id>`) so the user sees what else will break.
-      - If the user picks `Also delete …`, run the choice-set-delete or entity-delete flow (Rule 10 / [`choice-sets.md` → Delete a choice set](choice-sets.md#delete-a-choice-set)) with its own dependent-discovery and approval cycle. Apply only what the user confirms.
-    - `FILE` field delete drops only the column — the field's `referenceEntityId` points at the FILE storage entity, which is platform-managed, not user-owned. Do **not** offer to delete it.
-    - **Ambiguous-phrasing examples — confirm the intent before acting:**
-      - *"remove the references of the choice set from these entities"* → `removeFields` on each entity, then ask whether to also delete the now-unreferenced choice set.
-      - *"clear out the choice-set link from Order"* → `removeFields` on `Order`, then run the cascade-ask above.
-      - *"unhook the Customer relationship from Invoice"* → `removeFields` on `Invoice`, then ask whether to also delete `Customer`.
-      - *"delete the file column from Receipts"* → `removeFields` on `Receipts`. Do not offer cascading.
-
-12. **Complex field types need extra config and lookups.** `CHOICE_SET_*` needs `choiceSetId`; `RELATIONSHIP` needs `referenceEntityId` + `referenceFieldId`; `FILE` needs neither — server auto-wires (see [`entity-schema.md` → FILE Fields](entity-schema.md#file-fields)). When the user describes a link to another row ("each order has a Customer"), the type is `RELATIONSHIP` — never substitute `STRING` or `UUID`. Target entity must exist first. Full shape in [`entity-schema.md`](entity-schema.md#supported-field-types).
+> **Cascade only on confirmation.** For `CHOICE_SET_*` / `RELATIONSHIP` field deletes, Rule 11 mandates a dropdown offering `Delete only the field` / `Also delete the referenced choice set / target entity` / `Stop`. Each downstream delete runs its own confirmation cycle.
 
-12b. **Only pick UI-compatible field types.** `entities create` / `addFields` accept `INTEGER`, `BIG_INTEGER`, `FLOAT`, `DOUBLE`, `UUID`, `DATETIME` (no-TZ) as *field data types* but the Data Fabric UI renders those columns broken. Never emit any of the six as a **field type** — substitute per [`entity-schema.md` → UI-broken types](entity-schema.md#ui-broken-types--do-not-use). This ban is scoped to the field-type slot only; it does NOT restrict the word "integer" in prose contexts where an integer is genuinely correct — e.g. `CHOICE_SET_*` stores record values as integer `NumberId`s (Rule 15), `AUTO_NUMBER` generates integers, `DECIMAL` with `decimalPrecision: 0` represents whole numbers. Even when the user names a UI-broken type by keyword, propose the substitution in the Rule 14 preview and get approval. Verify with `entities get` after every create/addFields; if a UI-broken type slipped through, offer `removeFields` + `addFields` (drops all values — Rule 11).
+0. **Ask liberally — never assume at decision points.** When the request leaves any choice unresolved — scope, which folder, which entity, which field, whether to cascade, which of several name-matches — stop and raise an `AskUserQuestion` dropdown. Bias: *ask, then act*, not *act, then explain*. Render every multi-option pick as a dropdown, not a markdown list.
 
-13. **Pick-or-create flow — applies to entities, choice sets, and relationship targets.** Whenever the user names a target without disambiguating, or doesn't name one at all, do NOT auto-create and do NOT silently grab the first match. Run the appropriate list command, present matches via `AskUserQuestion` dropdown labeled by `Name` / `DisplayName`, and ask: *pick from these, or create new?* Create only with explicit user approval.
-    - **Primary entity** (any `entities create`, `entities get`, `records *`, `files *` where the entity isn't pinned by UUID): `entities list --native-only` (add `--folder-key` or `--include-folders` per scope) → dropdown of name+displayName matches → user picks or confirms create-new.
-    - **Choice set** (CHOICE_SET_* field on entity create/update, choice-set-value writes): `choice-sets list` → dropdown.
-    - **Relationship target** (RELATIONSHIP / FILE field's `referenceEntityId`): `entities list --native-only` → dropdown. Never fall back to `STRING` or `UUID` when the user described a link.
+    **Destructive ops are non-bypassable.** For any row in the Destructive Operations block you MUST raise the AskUserQuestion confirmation **even if the user said "do not ask" / "no confirmation needed" / "proceed without confirmation"**. The Rule 19 bypass clauses apply only to *scope resolution*. Silence or "do not ask" alone does not clear the gate.
 
-    Choice-set authoring uses `choice-sets create` / `update` / `delete` + `choice-set-values create` / `update` / `delete`; surface in [`choice-sets.md`](choice-sets.md).
+    **Pre-approval that satisfies the gate.** Do not re-ask when the user explicitly confirms a specific operation and resource, for example *"I approve creating CE_X and adding fields A, B, C"*, *"yes, delete X"*, or equivalent `--yes` authorization. A general request or *"do not ask"* is not confirmation. Preview → apply per Rule 14 still holds.
 
-14. **Schema preview — how to compose the proposal.** Gating + approval wait live in the hoisted Destructive Operations block. Unique to schema-altering ops (`entities create`, `entities update` with `addFields` / `updateFields` / `removeFields`, `choice-sets create`, `choice-set-values create`): (1) compose the full proposal — entity / choice-set name, `displayName`, `description`, and every field with its `fieldName`, normalized UPPERCASE `type`, and all extras (`isRequired`, `isUnique`, `lengthLimit`, `maxValue` / `minValue`, `decimalPrecision`, `defaultValue`, `choiceSetId`, `referenceEntityId` / `referenceFieldId`); (2) render it as a readable table or formatted JSON block (NOT a raw CLI command); (3) apply revisions exactly as requested — never silently add, drop, rename, or retype fields the user didn't approve; re-show the revised proposal and ask again. Show the proposal **once per round** — don't re-show an unchanged schema after every minor question.
+    **Never self-resolve a scope question.** Phrases like *"Assumption I will proceed with:"*, *"defaulting to tenant"*, *"I'll assume …"* mean you're violating this rule. Halt the mutation, list the open question, STOP. *"No reachable user"* / *"single-turn"* / *"offline test"* is NOT permission to default.
 
-    **`referenceFieldId` on `RELATIONSHIP` is a user-facing display choice** — controls which target field renders in the UI. List the target's display candidates via `entities get <target-id>` and raise an `AskUserQuestion` dropdown; never silently default to `Id`. Stored value is always the target UUID regardless. This dropdown fires only for `RELATIONSHIP` — FILE has no such choice (Rule 12).
+1. **Install the tool first.** If `uip df` returns "unknown command": `uip tools install @uipath/data-fabric-tool@latest`.
 
-    **CSV / sample-data inference — confirm every inferred type.** When field types are inferred from a source file (CSV, Excel, JSON sample) rather than spelled out by the user, first run the Rule 13 pick-or-create probes (`entities list --native-only`, `choice-sets list`) so `RELATIONSHIP` / `CHOICE_SET_*` alternatives are grounded in what exists. Then write the proposal, flagging every type as **inferred**, and raise an `AskUserQuestion` to confirm or override before `entities create`. One row per column: `header` → `inferred type` → `sample value(s)`. Rule 12b applies to the whole proposal — do not mention any UI-broken type name anywhere in it (no candidate list, no exclusions callout, no explanatory prose); use only the UI-compatible substitutes. Also confirm `isRequired` / `isUnique` / `lengthLimit` per column; do not infer these from CSV sparsity. Silence on a CSV import ≠ approval (Rule 0).
+2. **Verify login and tenant first.** Run `uip login status --output json`. Switch with `uip login tenant set <tenant>` if needed. Full login setup lives in the parent `uipath-platform` skill.
 
-15. **Choice / relationship record values use lookup tokens, not labels.** Choice value → integer `NumberId` (single) or array of `NumberId`s (multi), from `choice-sets list-values`. Relationship value → target record's UUID `Id` regardless of which field was bound as `referenceFieldId`. Filter / `groupBy` use the same tokens; `CHOICE_SET_MULTIPLE` filtering has special operator semantics — see [`records-query.md`](records-query.md#filtering-on-choice-set-fields).
-
-16. **Answer with `records query`, not from memory.** Counts, sums, filters, lookups — issue a fresh `records query` (or `records list`) and use the server's response. Do not reuse cached insert responses, IDs you generated earlier, or values from previous tool results. Exception: the `Id` returned by the same `records insert` you just made.
-
-17. **`records query` filters.** Body shape, per-type support, and unsupported-operator handling: [filter contract](filter-platform-contract.md). Only these `operator` tokens: `=` `!=` `>` `<` `>=` `<=` `contains` `not contains` `startswith` `endswith` `in` `not in`; 400 thrown for -> `equals`/`==`/`like`. `value` is always a JSON string. On unsupported operator/type or missing value, don't run — ask (Rule 18). **Return all fields by default** — omit `selectedFields` unless a subset is requested. **Aggregate aliases are PascalCased in the response** — `alias: "total"` comes back as key `"Total"` on each row of `Data.Items`; parse by the PascalCase key, not the alias you sent.
-
-18. **When a request isn't supported OR the upstream system returns an error, stop and confirm with the user — never silently substitute.** Triggers (not exhaustive): a filter operator unsupported for the field type / not in the symbol list / missing a value (see [filter contract → Unsupported operator](filter-platform-contract.md#unsupported-operator-or-missing-value)); an unknown `fieldName`; a nonexistent or federated entity; a missing CLI verb or unsupported operation (see *Not Supported*); cross-entity joins or value forms the API can't serve; ANY 4xx/5xx, validation error, `RESERVED_LANGUAGE_KEYWORDS`, constraint-violation, or quota response from the API.
-    Sequence: (1) surface the full upstream message verbatim — never swallow it; (2) state precisely what isn't supported or what failed (cite the rule / schema / error code); (3) propose a concrete next step keyed to the error — e.g. unknown `fieldName` → list the entity's real same-type fields from `entities get` and ask which; `RESERVED_LANGUAGE_KEYWORDS` → suggest a domain-specific rename; constraint violation → show the allowed range; missing dependency → list candidates via `entities list` / `choice-sets list` and offer pick-or-create (Rule 13); (4) apply **only** what the user approves, never your own fallback. If nothing works, error out and recommend the right sibling skill (`uipath-maestro-flow` / `uipath-rpa` / `uipath-agents` / `uipath-test`) — don't fabricate or return a degraded result.
-
-19. **Resolve folder scope up front; pass `--folder-key` on folder-scoped targets.** Data Fabric entities and choice sets live either at the tenant level or inside an Orchestrator folder. Every `uip df` command that touches a row accepts `--folder-key <GUID>`; `entities list` and `choice-sets list` also accept `--include-folders` (mutually exclusive with `--folder-key`). See [Folder Scope](#folder-scope) for the matrix. Required on folder-scoped writes (entity/record/file/choice-set create/update/delete) and recommended on folder-scoped reads. Lists default to **tenant-only** — pass `--folder-key` or `--include-folders` to see folder rows.
+3. **Always resolve entity ID first.** Use `entities list` before any operation. Never assume an entity ID.
 
-    **Mandatory scope-prompt flow.** If the user requests any `entities` / `records` / `files` / `choice-sets` / `choice-set-values` operation (create / update / delete / get / list / insert / upload / download / import / query) and has **not** specified the scope in this conversation, stop. Do not guess, do not default to personal workspace, do not default to tenant. Ask via `AskUserQuestion` with two dropdown questions:
+4. **Schema name rules.** Entity and choice-set names allow letters, digits, and underscores; field names allow letters and digits only. All are 3–100 characters and start with a letter. Reserved system field names are matched case-insensitively: `Id`, `CreatedBy`, `CreateTime`, `UpdatedBy`, `UpdateTime`, `RecordOwner`. C#/VB keywords are rejected case-insensitively; the CLI also rejects live-confirmed SQL-reserved words such as `Order` and `Group`, while ordinary names such as `Status` and `Key` are accepted. **Choice-set value `Name` uses a different validator** — see [`choice-sets.md` → Value Name validation](choice-sets.md#value-name-validation). Full rules: [`entity-schema.md` → Name Validation](entity-schema.md#name-validation).
 
-    1. **Scope** — options: `Tenant level (no --folder-key)` · `Folder-scoped`.
-    2. **If folder-scoped**, ask a second `AskUserQuestion` dropdown — options: `Provide folder GUID` · `List accessible folders`. Skip this sub-prompt if the prompt already supplies a folder GUID inline.
-       - **`Provide folder GUID`** — accept the GUID via the user's free-text reply (or the `Other` text input on the same dropdown) and use it as `--folder-key`. Do **not** call `uip or folders list`.
-       - **`List accessible folders`** — pre-fetch `uip or folders list --output json` first, then render the accessible folders as a single-select dropdown — label each option `<Name> — <Path>`, stash the `Key` as the option payload, and use that as `--folder-key` for every subsequent call this turn. If more than 4 folders return, narrow first — ask whether the user wants Personal / Shared / Solution / Standard folders, or accept a free-text name filter, then re-prompt with the filtered list. Never render the raw folder list as plain markdown — always a selectable dropdown.
+5. **`records update` requires `"Id"` in every element** (single or batch). Body shape is validated before the row is resolved, so a body missing `"Id"` fails with `Record must include 'Id'` even offline. See [`records-query.md` → Update Records](records-query.md#update-records).
 
-    Cache the folder list within the turn to avoid refetching. Echo the chosen scope back in the next message before any irreversible call. Scope persists across follow-up turns unless the user switches. Tenant prompting is rarely needed — `uip login status` shows the active tenant; only call `uip login tenant set <tenant>` after the user explicitly asks for a different one.
+5b. **`isUnique` is immutable after field creation.** `updateFields` returns `Result: Success` but silently no-ops the value. To change it: `removeFields` → `addFields` with `isUnique: true` (**drops every existing value in the column**). Verify every `updateFields` call by re-reading `entities get` and comparing. Full surface: [`entity-schema.md` → Not Supported](entity-schema.md#not-supported) + [Verify-after-update](entity-schema.md#verify-after-update--never-trust-the-success-response-alone).
 
-    **Bypass clauses — skip the AskUserQuestion flow when ANY of these hold.** The agent must still announce the chosen scope (one line) in the response so the user can correct.
-    - The prompt explicitly says some variant of *"do not ask"*, *"do not pause"*, *"no approval / confirmation / feedback needed"*, or *"proceed without confirmation"* — proceed at **tenant level** unless folder context is mentioned inline. **This bypass covers scope only.** Destructive-op confirmations (entity / field / record / file / choice-set / choice-set-value delete, schema-altering create / update, field-delete cascade-ask) still fire — see Rule 0.
-    - The prompt names a folder inline (*"in the Shared folder"*, *"in folder X"*, *"--folder-key <guid>"*, *"in personal workspace"*) — proceed with that folder; do **not** ask which folder.
-    - The prompt explicitly states tenant scope (*"tenant level"*, *"do NOT pass any folder flag"*, *"no folder"*, *"at the root"*) — proceed at tenant level.
-    - The prompt provides a folder GUID, a `folder_a_id`/`folder_b_id` variable, or instructions to derive folder IDs from another command — proceed using the derived folder; if none is available, fall through to tenant.
-    - The request is a pure tenant-wide discovery read (`entities list` / `choice-sets list` with no specific entity ID in mind) — default to `--include-folders` and announce. Asking adds no value for a survey.
+6. **Never put a FILE-typed key in `records insert` / `records update` / `records import` payloads.** Silently stripped — paths, base64, UUIDs, `null` all dropped; CLI returns `Result: Success`. Required path: insert the row without the FILE column, then `files upload <entity-id> <record-id> <field-name> --file <path>` (also used for replace); `files delete` to clear; `files download` to retrieve. Full surface: [`file-attachments.md`](file-attachments.md).
 
-    When a bypass triggers, write one sentence at the top of the response stating which scope you picked and why (*"Proceeding at tenant level — prompt said 'do not pause'."* / *"Using folder Shared (key c4359cde-…) — prompt referenced it."*). The user can redirect in the next turn.
+7. **CSV headers must match `Fields[].DisplayName`** (case-sensitive), not internal `Name`. Discover via `entities get`. See [`bulk-import.md`](bulk-import.md).
 
-20. **`records import` does not support complex field types — surface this to the user before invoking.** `records import` accepts Basic types only — `CHOICE_SET_SINGLE`, `CHOICE_SET_MULTIPLE`, `RELATIONSHIP`, `FILE`, and `AUTO_NUMBER` are **not supported**. The CSV header is accepted but the column values are ignored (no error, no `ErrorFileLink` entry — `null` in every row, or row failure if the field is `isRequired` without a `defaultValue`). Sequence: (1) run `entities get <entity-id>` and list every field whose type is in the unsupported set above; (2) tell the user verbatim which columns are not supported by import and why; (3) offer the alternative — `records insert --file <json>` with a JSON-array body handles all types except `FILE` (use `files upload` for those — Rule 6). See [`records-query.md` → Writing choice-set and relationship values](records-query.md#writing-choice-set-and-relationship-values) for the value form; (4) only invoke `records import` after the user confirms they accept the unsupported columns being skipped OR want to switch to `records insert`. This is platform behavior, not a bug — do not attempt to work around it.
+8. **Never create duplicate entities.** Always `entities list` first; reuse if it already exists. Entity and choice-set `displayName` values must also be unique. If the user does not provide one, derive a collision-resistant display name from the requested `Name`, not a generic label. On `409` / `RetryWillNotFix`, do not repeat the same create or treat an environment ID from the error as a resource ID; surface the conflict and ask for a different name or display name.
 
-21. **`MULTILINE_MAX` fields — marker reads, no filter/sort.** `records list` / `records query` return a size marker starting `HasValue=true Length=N` (live form: `"HasValue=true Length=20000 — call Get Entity Record By Id activity to retrieve content"`) for `MULTILINE_MAX` fields, never the content — full value only via `records get <entity-id> <record-id>`. Never display or persist the marker as data; never echo it back through `records update` — the server accepts it as a normal value and silently destroys the real content; omit the key instead. The type takes no filter or sort — 400: *"Field '<name>' is of type MULTILINE_MAX and cannot be used in filters."* / *"Sort field '<name>' … cannot be used for sorting."*; surface verbatim (Rule 18). Capacity: `lengthLimit` is a UTF-16 **byte** budget (max 131072 ≈ 65,536 chars). A 400 on `entities create` / `addFields` naming this type: surface it verbatim, don't retry or silently substitute `MULTILINE_TEXT` (Rule 18). Full contract: [`entity-schema.md` → MULTILINE_MAX fields](entity-schema.md#multiline_max-fields) + [`records-query.md`](records-query.md#multiline_max-fields--marker-vs-full-content).
+9. **Only work with native entities.** Use `entities list --native-only` before any write. Federated entities are read-only.
 
----
+10. **Entity delete — dependent discovery.** Gating lives in the Destructive Operations block. Scan for inbound references (`entities list --output json` → `Fields[].ReferenceEntity.Id == <id>`) and choice sets used by the entity's fields (`Fields[].ChoiceSetId`). Ask per dependent: delete, leave, or stop. Full sequence: [`entity-schema.md` → Deleting an Entity](entity-schema.md#deleting-an-entity).
 
-## Tool Version Requirements
+11. **Field delete — `removeFields` uses `{"fieldName":"…"}`** (NOT `id` like `updateFields`). For `CHOICE_SET_*` / `RELATIONSHIP` fields, raise a cascade-ask dropdown before invoking (`Delete only the field` / `Also delete the referenced choice set / target entity` / `Stop`) and echo other bindings so the user sees blast radius. `FILE` field delete drops only the column — never offer to delete the platform-managed storage entity. Full sequence: [`entity-schema.md` → Deleting a Field](entity-schema.md#deleting-a-field).
 
-| Feature | Required `@uipath/data-fabric-tool` |
-|---------|--------------------------------------|
-| `entities` / `records` CRUD, `query` with filters/sort, `records import`, `files` | `0.9.0+` |
-| Server-side `aggregates` and `groupBy` on `records query` | `1.0.1+` |
-| `--folder-key` threaded through every entity/record/file/choice-set command + `--include-folders` on `entities list` / `choice-sets list` | `1.197.0+` (now on `latest`) |
-| `MULTILINE_MAX` field type (schema create + full-content `records get`) | `1.198.0+` (first version bundling SDK `1.5.2`). Not yet on `latest` (still `1.197.0`, whose bundle predates the type) — until promoted, install the preview: `uip tools install @uipath/data-fabric-tool@1.198.0-preview.80` |
+12. **Complex fields need extra config and lookups.** `CHOICE_SET_*` needs `choiceSetId`; `RELATIONSHIP` needs `referenceEntityId` + `referenceFieldId`; `FILE` needs neither (server auto-wires). When the user describes a link ("each order has a Customer"), the type is `RELATIONSHIP` — never substitute `STRING` or `UUID`. Target entity must exist first. Full shape: [`entity-schema.md` → Supported Field Types](entity-schema.md#supported-field-types).
 
-Upgrade with `uip tools install @uipath/data-fabric-tool@latest` when a feature appears to silently no-op (e.g. aggregate body keys returning raw record lists).
+12b. **UI-broken types — never emit as a field type.** `INTEGER`, `BIG_INTEGER`, `FLOAT`, `DOUBLE`, `UUID`, `DATETIME` are accepted by the API but render broken in the Data Fabric UI. Substitute per [`entity-schema.md` → UI-broken types](entity-schema.md#ui-broken-types--do-not-use). Rule 14 preview must not name any of the six anywhere in the proposal.
 
----
+13. **Pick-or-create flow — applies to entities, choice sets, and relationship targets.** When the user names a target without disambiguating, or doesn't name one at all, do NOT auto-create and do NOT silently grab the first match. Run the appropriate list command, present matches via dropdown, ask *pick from these or create new?*. Create only with explicit approval.
+    - **Primary entity**: `entities list --native-only` (+ `--folder-key` or `--include-folders` per scope) → dropdown → user picks or confirms create-new.
+    - **Choice set** (CHOICE_SET_* field, choice-set-value writes): `choice-sets list` → dropdown.
+    - **Relationship target** (RELATIONSHIP): `entities list --native-only` → dropdown. Never fall back to `STRING`/`UUID`. `FILE` does not use this flow — the server auto-wires its storage entity (Rules 6/12).
 
-## Quick Start
+    **Bounded discovery.** For each unresolved choice, make one focused discovery pass before asking or skipping; do not repeatedly re-list the same unchanged resources or search the filesystem for documentation. Never inspect installed CLI package source or create temporary probe entities to infer supported schema or command syntax; use this reference and `--help`. Pagination needed to complete that pass and post-mutation reads used to verify changed state are allowed. For an **optional** resource where the request says to use one if available and otherwise skip, inspect once; if no clear match exists, skip it and continue without creating probes. Do not run extra mutation experiments beyond the scenarios the user requested.
 
-```bash
-# List entities (use --native-only before any write)
-uip df entities list --native-only --output json
+14. **Schema preview — compose, render, wait.** Before every `entities create` / `entities update` with `addFields`/`updateFields`/`removeFields` / `choice-sets create` / `choice-set-values create`: (1) compose the full proposal — entity name, `displayName`, `description`, every field with UPPERCASE `type` and all extras (`isRequired`, `isUnique`, `lengthLimit`, `maxValue`/`minValue`, `decimalPrecision`, `defaultValue`, `choiceSetId`, `referenceEntityId`/`referenceFieldId`); (2) render as a table or formatted JSON block, NOT a raw CLI command; (3) apply revisions exactly — never silently add, drop, rename, or retype what the user didn't approve.
 
-# Get entity schema (field names and types)
-uip df entities get <entity-id> --output json
+    **`referenceFieldId` on `RELATIONSHIP` is a user-facing display choice.** List target's display candidates via `entities get <target-id>` and raise a dropdown; never silently default to `Id`. Fires only for `RELATIONSHIP` (FILE has no such choice).
 
-# List records (first page)
-uip df records list <entity-id> --limit 50 --output json
+    **CSV / sample-data inference — confirm every inferred type.** Run Rule 13 probes first so complex-field alternatives are grounded. For every column, label the chosen type **inferred** and name plausible alternatives; parseable timestamps, decimals, `0`/`1`, and UUID-shaped text are not self-confirming. Dropdown-confirm before `entities create`. Rule 12b applies to the whole proposal. Silence on a CSV import ≠ approval.
 
-# Insert one record
-uip df records insert <entity-id> --body '{"Name":"Alice","Score":95}' --output json
+15. **Choice / relationship record values use lookup tokens, not labels.** Choice value → integer `NumberId` (single) or array of `NumberId`s (multi), from `choice-sets list-values`. Relationship value → target record's UUID `Id`. Filter / `groupBy` use the same tokens; `CHOICE_SET_MULTIPLE` filtering has special operator semantics — see [`records-query.md` → Filtering on Choice-Set Fields](records-query.md#filtering-on-choice-set-fields).
 
-# Query with a filter
-uip df records query <entity-id> \
-  --body '{"filterGroup":{"logicalOperator":0,"queryFilters":[{"fieldName":"Status","operator":"=","value":"active"}]}}' \
-  --output json
+16. **Answer with `records query`, not from memory.** Counts, sums, filters, lookups — issue a fresh `records query` and use the server's response. Do not reuse cached values from previous turns or tool results. Exception: the `Id` returned by the same `records insert` you just made.
 
-# Aggregate query — count of records per Status (server-side groupBy)
-uip df records query <entity-id> \
-  --body '{"selectedFields":["Status"],"groupBy":["Status"],"aggregates":[{"function":"COUNT","field":"Id","alias":"total"}]}' \
-  --output json
-```
+17. **`records query` filters.** Body shape + per-type support + unsupported-operator handling: [`filter-platform-contract.md`](filter-platform-contract.md). Operator whitelist: `=` `!=` `>` `<` `>=` `<=` `contains` `not contains` `startswith` `endswith` `in` `not in`; `equals` / `==` / `like` are rejected. `value` is a JSON string except `null` for empty checks. **Aggregate aliases return PascalCased in the response** — `alias: "total"` comes back as key `"Total"` on each row. **Return all fields by default** — omit `selectedFields` unless a subset is requested.
 
-For Complex types field shapes and value formats, see [`entity-schema.md`](entity-schema.md#supported-field-types) and [`records-query.md`](records-query.md#filtering-on-choice-set-fields).
+18. **Never hide or silently substitute after an error.** Surface the upstream message verbatim and state what failed. If a read-only request has one unambiguous correction (for example, the server names the required body property), apply it and report the correction; otherwise ask. Always ask before an alternative mutation; for an intentional negative probe, run only the requested variant and stop after capturing its result. Independent requested operations may continue when they do not depend on the failed result; run multi-probe error checks as separate shell calls so every response is retained. Detailed error shapes live in the relevant topic reference.
 
-### `records query` body schema — exact keys (agents commonly mis-guess)
+19. **Resolve folder scope up front; pass `--folder-key` on folder-scoped targets.** Every `uip df` command that touches a row accepts `--folder-key <GUID>`; `entities list` and `choice-sets list` also accept `--include-folders` (mutually exclusive). See [Folder Scope](#folder-scope) for the matrix. Required on folder-scoped writes; recommended on folder-scoped reads. Lists default to **tenant-only**.
 
-The CLI accepts a strict schema. These are the four most-missed keys:
+    **Mandatory scope-prompt flow.** If scope isn't pinned in the conversation, stop and ask via `AskUserQuestion`: (1) `Tenant level (no --folder-key)` vs `Folder-scoped`; (2) if folder-scoped and no GUID inline, offer `Provide folder GUID` (user-typed) or `List accessible folders` (pre-fetch `uip or folders list --output json`, dropdown labelled `<Name> — <Path>`, narrow first if >4). Resolve this before Rule 13's scope-specific pick-or-create discovery. Cache the folder list within the turn; echo the chosen scope back in the next message. Scope persists across follow-up turns unless the user switches.
 
-| Position | Correct | Common wrong guess |
-|---|---|---|
-| Entity ID | positional: `uip df records query <entity-id>` | `--entity-id <id>` (no such flag) |
-| Wrap object | `filterGroup` | `filter`, `where`, `query` |
-| Boolean operator | `logicalOperator: 0` (AND) or `1` (OR) — **integer** | `"AND"` / `"OR"` (string) |
-| Filter list | `queryFilters: [...]` | `filters`, `conditions` |
-| Per-filter field key | `fieldName: "..."` | `field`, `name`, `column` |
+    **Bypass clauses — skip the AskUserQuestion when ANY of these hold** (still announce the chosen scope in one line):
+    - Prompt says *"do not ask"* / *"no confirmation needed"* / *"proceed without confirmation"* — proceed at **tenant level** unless folder context is mentioned inline. Scope only; destructive-op gates still fire (Rule 0).
+    - Prompt names a folder inline or supplies a folder GUID / `folder_a_id`-style variable — proceed with that folder.
+    - Prompt explicitly states tenant scope (*"tenant level"*, *"no folder"*, *"at the root"*).
+    - Pure tenant-wide discovery read — default to `--include-folders` and announce.
 
-`CHOICE_SET_MULTIPLE` value forms:
-- `contains` / `not contains` → bare-NumberId **string** (`"1"`, not `"[1]"`)
-- `=` / `!=` → JSON-array **string** (`"[1,3]"`, not bare `"1"`)
+20. **`records import` supports Basic types only.** `CHOICE_SET_*`, `RELATIONSHIP`, `FILE`, `AUTO_NUMBER` columns are ignored on import — optional columns land as `null`; **`isRequired` columns without a `defaultValue` fail the whole row** (`ErrorFileLink` entry per row). Sequence: (1) `entities get` → list unsupported columns; (2) tell the user which columns will be skipped, and which rows will fail because a required unsupported column has no default; (3) offer `records insert --file <json>` (+ `files upload` for FILE) as the alternative; (4) invoke only after explicit confirmation. See [`bulk-import.md` → Complex Field Types Not Supported](bulk-import.md#complex-field-types-not-supported).
 
-Full per-type operator support matrix: [`filter-platform-contract.md`](filter-platform-contract.md).
+21. **`MULTILINE_MAX` — marker reads, no filter/sort.** `records list` / `records query` return a size marker (`HasValue=true Length=N`) — full value only via `records get`. Never echo the marker back through `records update` — the server accepts it as a normal value and destroys the real content; omit the key instead. No filter/sort support (400). `lengthLimit` is a UTF-16 byte budget (max 131072 ≈ 65,536 chars). Full contract: [`entity-schema.md` → MULTILINE_MAX](entity-schema.md#multiline_max-fields) + [`records-query.md` → MULTILINE_MAX](records-query.md#multiline_max-fields--marker-vs-full-content).
 
 ---
 
@@ -230,129 +119,49 @@ Full per-type operator support matrix: [`filter-platform-contract.md`](filter-pl
 
 Entities and choice sets are either tenant-level or folder-scoped. Records and files inherit the parent entity's scope.
 
-**Flags (CLI ≥ `1.197.0`):**
+**Flags:**
 
-- `--folder-key <GUID>` — scope the call to that folder. Pass the Orchestrator folder key (`uip or folder list --output json` → `Key`), NOT the folder display name.
-- `--include-folders` — on `entities list` / `choice-sets list` only. Returns tenant + every folder the caller can see, in one response. **Mutually exclusive with `--folder-key`** — passing both errors out.
+- `--folder-key <GUID>` — scope the call to that folder. Pass the Orchestrator folder `Key` from `uip or folders list --output json`.
+- `--include-folders` — on `entities list` / `choice-sets list` only. Returns tenant + every visible folder. **Mutually exclusive with `--folder-key`**.
 
 **Per-command behavior:**
 
 | Command(s) | `--folder-key` effect |
 |---|---|
-| `entities list`, `choice-sets list` | Filter mode: omit both flags → tenant only (default); `--folder-key <key>` → that folder only; `--include-folders` → tenant + all visible folders. Each returned row carries `folderId` / `FolderId` — keep it for follow-up calls. |
-| `entities create`, `choice-sets create` | **Scope-bound** — required for folder placement. Omit to create at tenant level. The created row's `folderId` matches. |
-| `entities get / update / delete`, `records *`, `files *`, `choice-sets list-values / update / delete`, `choice-set-values create / update / delete` | Forwarded as `X-UIPATH-FolderKey`. Required on folder-scoped targets; tenant-scoped targets accept any key (server resolves by UUID). Pass it defensively on every destructive op. |
+| `entities list`, `choice-sets list` | Filter mode. Omit both → tenant only. `--folder-key <key>` → that folder only. `--include-folders` → tenant + all visible folders. |
+| `entities create`, `choice-sets create` | **Scope-bound** — required for folder placement. Omit → tenant. |
+| `entities get / update / delete`, `records *`, `files *`, `choice-sets list-values / update / delete`, `choice-set-values *` | Required on folder-scoped targets. |
 
-**Cross-folder references on RELATIONSHIP / FILE / CHOICE_SET_\* fields:** allowed only between same-scope-class targets. **For `RELATIONSHIP` and `FILE` fields, whenever the target is folder-scoped, the field MUST include `referenceFolderKey: <target-folder-guid>` — even when the target lives in the same folder as the parent.** Omitting it on a same-folder binding fails with the misleading *"Cannot create relationship field from folder-level entity to tenant-level entity ('')"* (the server treats missing `referenceFolderKey` as "target is tenant" and trips the cross-scope block). **For `CHOICE_SET_*` fields**, do NOT pass `referenceFolderKey` — the backend resolves the choice-set's folder server-side from `choiceSetId` alone. Tenant ↔ tenant works without `referenceFolderKey`. **Crossing tenant ↔ folder is NOT allowed** for any of the three field types — a folder-scoped entity cannot bind a tenant-level user-authored choice set or relationship target, and vice versa. **Exception: tenant-level system entities** (e.g. `EntityAttachment` for FILE; `User`, which every entity's `CreatedBy` / `UpdatedBy` already reference) are platform-managed and remain bindable from folder-scoped parents. Full matrix in [`entity-schema.md` → Cross-folder references](entity-schema.md#cross-folder-references).
-
-If a verb returns `unknown option '--folder-key'`, the installed tool is older than `1.197.0` — see *Tool Version Requirements* above.
+**Cross-folder references** on `RELATIONSHIP` / `CHOICE_SET_*` fields are restricted to the same scope class. `RELATIONSHIP` requires `referenceFolderKey` when its target is folder-scoped, including same-folder bindings; choice sets resolve scope from `choiceSetId`. `FILE` is auto-wired and takes no reference fields. Full matrix: [`entity-schema.md` → Cross-folder references](entity-schema.md#cross-folder-references).
 
 ---
 
 ## Task Navigation
 
-| Task | Commands to use |
-|------|----------------|
-| Explore what entities exist (tenant) | `entities list` → `entities get <id>` |
-| Explore entities in a specific folder | `entities list --folder-key <folder-guid>` |
-| Explore tenant + every folder's entities in one shot | `entities list --include-folders` |
-| Explore only native entities | `entities list --native-only` |
-| Manage choice sets | `choice-sets list [--folder-key <…> \| --include-folders]` / `list-values <id> [--folder-key <…>]` / `create [--folder-key <…>]` / `update [--folder-key <…>]` / `delete [--folder-key <…>]`; values via `choice-set-values create` / `update` / `delete` (all accept `--folder-key`) — full surface in [`choice-sets.md`](choice-sets.md) |
-| Create a new entity | `entities create <name> [--folder-key <folder-guid>] --body '{"fields":[{"fieldName":"Title","type":"STRING"}]}'` — omit `--folder-key` for tenant scope. Complex-field extras (`choiceSetId`, `referenceEntityId`, `referenceFieldId`, `referenceFolderKey`) and the tenant↔folder rule are in [`entity-schema.md`](entity-schema.md#supported-field-types). |
-| Update entity / add fields | `entities update <id> --body '{"addFields":[{"fieldName":"NewField","type":"STRING"}]}'` |
-| Update existing field metadata | `entities update <id> --body '{"updateFields":[{"id":"<field-uuid>","displayName":"New Label","isRequired":true}]}'` — body uses `id` (lowercase); the response key is `Id` (different case, same value) |
-| Update entity metadata | `entities update <id> --body '{"displayName":"New Name","description":"desc"}'` |
-| Delete an entity | `entities delete <id> [--folder-key <…>]` — see Destructive Operations block + Rule 10 |
-| Delete a field | `entities update <id> --body '{"removeFields":[{"fieldName":"<name>"}]}'` — `removeFields` uses `fieldName`, NOT `id` (Rule 11) |
-| Read records (first page) | `records list <entity-id> --limit 50` |
-| Read records (next page) | `records list <entity-id> --cursor <NextCursor.Value>` — extract the inner `Value` from the previous response's `Data.NextCursor` object; passing the whole object errors |
-| Get one record | `records get <entity-id> <record-id>` |
-| Insert one record | `records insert <entity-id> --body '{...}'` (or `--file`). Choice / relationship value formats: see [`records-query.md`](records-query.md#writing-choice-set-and-relationship-values) |
-| Batch insert | `records insert <entity-id> --body '[{...},{...}]'` |
-| Update one record | `records update <entity-id> --body '{"Id":"<record-id>","field":"val"}'` |
-| Batch update | `records update <entity-id> --body '[{"Id":"<id1>","field":"val"},{"Id":"<id2>","field":"val"}]'` |
-| Delete records | `records delete <entity-id> <id1> <id2> [--folder-key <…>]` — IDs are positional varargs (separate args, NOT space-joined). See Destructive Operations block |
-| Filter/search records | `records query <entity-id> --body '{...}'`. Choice / relationship filter operators: see [`records-query.md`](records-query.md#filtering-on-choice-set-fields) |
-| Aggregate / group-by metrics | `records query <entity-id> --body '{"aggregates":[{"function":"COUNT","field":"Id","alias":"total"}],"groupBy":["FieldName"]}'` |
-| Bulk import from CSV (Basic field types only — `CHOICE_SET_*`, `RELATIONSHIP`, `FILE`, and `AUTO_NUMBER` are **not supported** by `records import`; **surface this to the user before invoking — Rule 20**) | `records import <entity-id> --file data.csv [--folder-key <…>]` |
-| Bulk seed records that include complex fields | `records insert <entity-id> --file records.json` with a JSON array body |
-| Upload file to record | `files upload <entity-id> <record-id> <field-name> --file path` |
-| Download file | `files download <entity-id> <record-id> <field-name> --destination path` |
-| Delete file | `files delete <entity-id> <record-id> <field-name> [--folder-key <…>]` — see Destructive Operations block |
-
----
-
-## Field Types
-
-Pass the exact UPPERCASE `EntityFieldDataType`. UI-compatible set + substitutions for user-named UI-broken types + advanced constraints (`lengthLimit`, `maxValue`/`minValue`, `decimalPrecision`) all live in [`entity-schema.md` → Supported Field Types](entity-schema.md#supported-field-types). Rules 12 and 12b enforce the choice.
-
----
-
-## Workflow: Discover → Act → Verify
-
-1. **Discover** — list entities, get schema, check existing records
-2. **Act** — create/insert/update
-3. **Verify** — re-read to confirm the operation succeeded
-
-```bash
-uip df entities list --native-only --output json
-uip df entities get <entity-id> --output json
-uip df records insert <entity-id> --body '{"Name":"Alice","Score":95}' --output json
-uip df records list <entity-id> --limit 50 --output json
-# Records live in Data.Items (NOT Data.Records). Stop when Data.HasNextPage is false.
-# NextCursor is an object — unwrap Data.NextCursor.Value and pass that to --cursor.
-uip df records list <entity-id> --cursor <NextCursor.Value> --output json
-```
-
----
-
-## Query Request Format
-
-Pass the query body via `--body` or `--file`; pagination uses `--limit` / `--cursor` / `--offset` CLI flags, never body keys (see [Pagination](#pagination) below). The body shape, operators, per-type support, and response shape live in [`filter-platform-contract.md`](filter-platform-contract.md); query-only extras (`selectedFields`, `sortOptions`) are documented in [`records-query.md`](records-query.md).
-
-## Pagination
-
-`records list` / `records query` paginate via `--limit`, `--cursor`, `--offset`. See [`records-query.md`](records-query.md).
+| Task | Where |
+|------|-------|
+| Explore entities | `entities list` (`--folder-key`, `--include-folders`, or `--native-only` as needed) → `entities get <id>` |
+| Choice sets — full CRUD (sets and values) | [`choice-sets.md`](choice-sets.md) |
+| Create / update / delete entity, add/remove/update fields | [`entity-schema.md`](entity-schema.md) |
+| Read / filter / paginate / sort records | [`records-query.md`](records-query.md) + [`filter-platform-contract.md`](filter-platform-contract.md) |
+| Insert / update / delete records | [`records-query.md`](records-query.md) |
+| Aggregates / group-by | [`records-query.md` → Aggregates](records-query.md#aggregates-server-side) |
+| Bulk CSV import | [`bulk-import.md`](bulk-import.md) |
+| File attachments (upload / download / delete) | [`file-attachments.md`](file-attachments.md) |
 
 ---
 
-## Troubleshooting
+## Troubleshooting (cross-cutting only)
 
-> **Any error not in this table → Rule 18.** (Surface verbatim, propose options keyed to the error, apply only what the user confirms.)
+For topic-specific errors, use the relevant reference. Cross-cutting failures:
 
 | Error | Cause | Fix |
 |-------|-------|-----|
-| `unknown command: df` | Tool not installed | `uip tools install @uipath/data-fabric-tool` |
-| `Not logged in` | Auth expired | `uip login` |
-| `HTTP 401` | Invalid token | Re-login; ensure `DataServiceApiUserAccess` scope is present |
+| `unknown command: df` | Tool not installed | `uip tools install @uipath/data-fabric-tool@latest` |
+| `Not logged in` / `HTTP 401` | Auth expired or invalid token | `uip login`; ensure `DataServiceApiUserAccess` scope is present |
 | `HTTP 403` | Permission denied | Ensure account has Data Fabric permissions |
-| `Entity not found` | Wrong entity ID | Run `entities list` to get correct ID |
-| `Record must include 'Id'` | Update body missing Id | Every record passed to `records update` must include `"Id": "<record-id>"` — both single and batch |
-| `Each field must include a 'fieldName' string` | Invalid field in `entities create` | Use `{"fieldName":"myfield"}` not `{"name":"myfield"}` |
-| `Entity name resolution failed` | Query/import with bad ID | Verify entity exists with `entities list` |
-| Import errors in CSV | Header mismatch | Run `entities get` and check exact field names (case-sensitive) |
-| `records import` succeeded but choice / relationship / file / auto-number column is `null` on every row | Complex field types are **not supported** by `records import` (Basic types only) — current Data Fabric platform behavior | Re-seed those columns via `records insert` with a JSON body (FILE fields additionally require `files upload` — Rule 6). Surface the limitation **before** invoking import next time — see Rule 20 and [`bulk-import.md`](bulk-import.md) |
-| Write to federated entity | Entity is read-only | Use `--native-only`; federated entities cannot be written to |
-| `cannot be a reserved word in C# or VB` (alias: `RESERVED_LANGUAGE_KEYWORDS`) | Entity or field name collides with a C# / VB reserved keyword (e.g. `Case`, `Class`, `New`, `Return`, `Internal`). SQL keywords like `Status` / `Order` / `Key` are **not** rejected. | Surface the rejected name + the error to the user. Offer a domain-specific rename: `Case` → `WorkItem` / `Matter`; `Class` → `Category`; `New` → `IsNew`. Apply only the user-confirmed rename. See Rule 4. |
-| `Choiceset member name must only contain alphanumeric characters, start with alphabetic characters and not be C# keyword` | Choice-set value `Name` validator (separate code path from Rule 4 — case-SENSITIVE lowercase match, incomplete keyword list). Lowercase tokens like `class`, `new`, `case` are rejected; the same word capitalized (`New`) or words not on its list (`select`) can slip through. | Namespace the system `Name` with a lowercase suffix (`internal_audit`, `new_lead`) and keep `DisplayName` unchanged. Do not rely on title-case to bypass — the entity / field validator (case-insensitive) would still reject it elsewhere. Full rule + the related `NumberId`-ordering caveat: [`choice-sets.md` → Value `Name` validation](choice-sets.md#value-name-validation). |
-| Constraint violation (`"outside of allowed range"`, `"exceeds lengthLimit"`, etc.) | Write value broke `minValue` / `maxValue` / `lengthLimit` / `decimalPrecision` | Surface the full error to the user, show the allowed range from `entities get`, and ask what value to use — never silently clamp. See Rule 18. |
-| `referenceEntityId` missing on RELATIONSHIP/FILE field | Field defined with names instead of UUIDs | Pass `referenceEntityId` as a UUID; `RELATIONSHIP` also needs `referenceFieldId`. See Rule 12. |
-| `Cannot read properties of undefined (reading 'sqlTypeName')` | Field `type` value didn't match a known `EntityFieldDataType` enum — almost always lowercase / mixed-case (e.g. `"boolean"` instead of `"BOOLEAN"`) | Case-fold to the UPPERCASE enum from the type table — see [`entity-schema.md` → Normalizing user-facing type names](entity-schema.md#normalizing-user-facing-type-names) |
-| `Each field in removeFields must include a non-empty 'fieldName' string` | `removeFields` was called with `{"id": "..."}` (the shape `updateFields` uses) instead of `{"fieldName": "..."}` | Re-emit with `{"fieldName": "<exact field name>"}` — see Rule 11 |
-| `unknown option '--folder-key'` or `unknown option '--include-folders'` | Installed `@uipath/data-fabric-tool` predates `1.197.0` (folder-key fan-out) | Upgrade: `uip tools install @uipath/data-fabric-tool@alpha` until `1.197.0+` is promoted to `latest`. See *Tool Version Requirements* |
-| `--folder-key and --include-folders are mutually exclusive` | Both flags passed on `entities list` / `choice-sets list` | Pick one: `--folder-key <key>` for a single folder, OR `--include-folders` for tenant + every folder you can see |
-| Entity / choice set just created via `--folder-key <X>` doesn't appear in `entities list` / `choice-sets list` | Lists default to tenant-only | Re-run with `--folder-key <X>` (same key) or `--include-folders` |
-| `MULTILINE_MAX` field shows `HasValue=true Length=N — call Get Entity Record By Id …` in `records list` / `query` | Expected — list/query return a size marker, not content (Rule 21) | Full value via `records get <entity-id> <record-id>`. Never persist or write back the marker |
-| *"Field '<name>' is of type MULTILINE_MAX and cannot be used in filters."* / *"Sort field '<name>' … cannot be used for sorting."* (400) | Type supports no filter/sort operators (Rule 21) | Surface verbatim; offer `records get` + client-side evaluation only with user approval |
-| Insert rejected: *"value … is N bytes, exceeds the 131072-byte limit configured for this MULTILINE_MAX field"* | `lengthLimit` is a UTF-16 **byte** budget — 2 bytes per char, so 131072 ⇒ ~65,536 chars max | Surface the limit; ask the user whether to truncate or store elsewhere — never silently clamp (Rule 18) |
-
----
-
-## References
+| `unknown option '--folder-key'` / `unknown option '--include-folders'` | Installed tool is outdated | `uip tools install @uipath/data-fabric-tool@latest`; if still missing, surface as unsupported |
+| `--folder-key and --include-folders are mutually exclusive` | Both flags passed on `entities list` / `choice-sets list` | Pick one |
+| Entity / choice set created via `--folder-key <X>` doesn't appear in list | Lists default to tenant-only | Re-run with `--folder-key <X>` or `--include-folders` |
 
-- [`entity-schema.md`](entity-schema.md) — Field definitions, supported types, schema update patterns, choice-set + relationship field shapes
-- [`choice-sets.md`](choice-sets.md) — Full choice-set CRUD (`list`/`list-values`/`create`/`update`/`delete` plus `choice-set-values create`/`update`/`delete`), look up `NumberId`s, add CHOICE_SET fields to entities, write choice values on records
-- [`records-query.md`](records-query.md) — Query filter syntax, pagination, sorting, choice/relationship semantics on read & write
-- [`filter-platform-contract.md`](filter-platform-contract.md) — Filter body structure, per-type operator support matrix, and what to do when a request needs an unsupported operator
-- [`file-attachments.md`](file-attachments.md) — File field upload/download/delete file
-- [`bulk-import.md`](bulk-import.md) — CSV format requirements and the Basic-fields-only limitation (complex types — `CHOICE_SET_*`, `RELATIONSHIP`, `FILE`, `AUTO_NUMBER` — are **not supported** by `records import`; use `records insert` with a JSON body, plus `files upload` for FILE)
+Any error not in this table → Rule 18. Topic-specific error tables live in the topic references.