@uipath/skills 1.200.0 → 1.201.0-preview.433

package/skills/uipath-coded-apps/references/commands-reference.md

@@ -23,10 +23,10 @@ uip codedapp push [project-id] [options]
 | `[project-id]` | WebApp Project ID | From `UIPATH_PROJECT_ID` env var |
 | `--build-dir <dir>` | Build output directory | `dist` |
 | `--ignore-resources` | Skip importing referenced resources | `false` |
-| `--base-url <url>` | UiPath base URL | From `.env` |
-| `--org-id <id>` | Organization ID | From `.env` |
-| `--tenant-id <id>` | Tenant ID | From `.env` |
-| `--access-token <token>` | Access token | From `.env` |
+| `--base-url <url>` | UiPath base URL | From `uip login` session |
+| `--org-id <id>` | Organization ID | From `uip login` session |
+| `--tenant-id <id>` | Tenant ID | From `uip login` session |
+| `--access-token <token>` | Access token | From `uip login` session |
 
 **Examples:**
 
@@ -71,10 +71,10 @@ uip codedapp pull [project-id] [options]
 | `[project-id]` | WebApp Project ID | From `UIPATH_PROJECT_ID` env var |
 | `--overwrite` | Allow overwriting existing local files without prompting | `false` |
 | `--target-dir <dir>` | Local directory to write pulled files | Current directory |
-| `--base-url <url>` | UiPath base URL | From `.env` |
-| `--org-id <id>` | Organization ID | From `.env` |
-| `--tenant-id <id>` | Tenant ID | From `.env` |
-| `--access-token <token>` | Access token | From `.env` |
+| `--base-url <url>` | UiPath base URL | From `uip login` session |
+| `--org-id <id>` | Organization ID | From `uip login` session |
+| `--tenant-id <id>` | Tenant ID | From `uip login` session |
+| `--access-token <token>` | Access token | From `uip login` session |
 
 **Examples:**
 
@@ -115,11 +115,10 @@ uip codedapp pack <dist> [options]
 | `--main-file <file>` | Main entry file | `index.html` |
 | `--content-type <type>` | Content type: `webapp`, `library`, `process` | `webapp` |
 | `--dry-run` | Preview packaging without creating the file | `false` |
-| `--reuse-client` | Reuse existing clientId from uipath.json | `false` |
-| `--base-url <url>` | UiPath base URL | From `.env` |
-| `--org-id <id>` | Organization ID | From `.env` |
-| `--tenant-id <id>` | Tenant ID | From `.env` |
-| `--access-token <token>` | Access token | From `.env` |
+| `--base-url <url>` | UiPath base URL | From `uip login` session |
+| `--org-id <id>` | Organization ID | From `uip login` session |
+| `--tenant-id <id>` | Tenant ID | From `uip login` session |
+| `--access-token <token>` | Access token | From `uip login` session |
 
 **Examples:**
 
@@ -168,14 +167,14 @@ uip codedapp publish [options]
 | Option | Description | Default |
 |--------|-------------|---------|
 | `-n, --name <name>` | Package name (non-interactive selection) | Auto-select or prompted |
-| `-v, --version <version>` | Package version (requires `--name`) | Latest |
+| `-v, --version <version>` | Package version (requires `--name`). Selects the **first** matching `.nupkg` in unsorted `readdir` order — NOT the highest version. Always pass when multiple versions of the same name sit in `.uipath/`. | First name match |
 | `-t, --type <type>` | App type: `Web` or `Action` | `Web` |
 | `--uipath-dir <dir>` | Directory containing `.nupkg` files | `./.uipath` |
-| `--base-url <url>` | UiPath base URL | From `.env` |
-| `--org-id <id>` | Organization ID | From `.env` |
-| `--tenant-id <id>` | Tenant ID | From `.env` |
-| `--tenant-name <name>` | Tenant name (required for registration) | From `.env` |
-| `--access-token <token>` | Access token | From `.env` |
+| `--base-url <url>` | UiPath base URL | From `uip login` session |
+| `--org-id <id>` | Organization ID | From `uip login` session |
+| `--tenant-id <id>` | Tenant ID | From `uip login` session |
+| `--tenant-name <name>` | Tenant name (required for registration) | From `uip login` session |
+| `--access-token <token>` | Access token | From `uip login` session |
 
 **Examples:**
 
@@ -232,12 +231,13 @@ uip codedapp deploy [options]
 |--------|-------------|---------|
 | `-n, --name <name>` | App name | From `.uipath/app.config.json` or prompted |
 | `-v, --version <version>` | Target a specific **published** version (different semantic from `pack`/`publish` `-v`, which is the package version) | Latest |
-| `--base-url <url>` | UiPath base URL | From `.env` |
-| `--org-id <id>` | Organization ID | From `.env` |
-| `--org-name <name>` | Organization name (used for app URL) | From `.env` |
-| `--tenant-id <id>` | Tenant ID | From `.env` |
+| `--path-name <slug>` | URL slug (routing name). First deploy sets it (defaults to sanitized app name); on upgrade, **omit to keep the URL** — re-passing a taken or previously-used slug fails with `routing name must be unique` | Sanitized app name |
+| `--base-url <url>` | UiPath base URL | From `uip login` session |
+| `--org-id <id>` | Organization ID | From `uip login` session |
+| `--org-name <name>` | Organization name (used for app URL) | From `uip login` session |
+| `--tenant-id <id>` | Tenant ID | From `uip login` session |
 | `--folder-key <key>` | UiPath folder key | From `UIPATH_FOLDER_KEY` env var |
-| `--access-token <token>` | Access token | From `.env` |
+| `--access-token <token>` | Access token | From `uip login` session |
 
 **Examples:**
 
@@ -274,11 +274,11 @@ uip codedapp deploy -n my-webapp --folder-key my-folder-key
 
 ## Common Options
 
-All cloud commands accept these override options (values default to `.env` file):
+Cloud commands resolve base URL, org, tenant, and access token from your `uip login` session automatically (any login type) — you don't pass them. Pass the corresponding flag only to override a session value.
 
 | Option | Description |
 |--------|-------------|
-| `--base-url <url>` | UiPath base URL |
-| `--org-id <id>` | Organization ID |
-| `--tenant-id <id>` | Tenant ID |
-| `--access-token <token>` | Access token |
+| `--base-url <url>` | UiPath base URL (from `uip login` session) |
+| `--org-id <id>` | Organization ID (from `uip login` session) |
+| `--tenant-id <id>` | Tenant ID (from `uip login` session) |
+| `--access-token <token>` | Access token (from `uip login` session) |

package/skills/uipath-coded-apps/references/create-action-app.md

@@ -13,6 +13,8 @@ The data contract is defined in `action-schema.json`.
 
 > **Document Understanding validation app?** If the user wants a human-review form for DU extraction results (correct fields, edit tables, approve a document), embed the **Validation Station widget** instead of generating a custom form. Follow [widgets/validation-station.md](widgets/validation-station.md) — it replaces the `src/components/Form.tsx` produced by Q4 below.
 
+> **Reviewer needs to see a PDF beside the form** (display-only — not DU validation)? Embed the **PDF Viewer widget** in the document pane instead of hand-rolling pdf.js — see [widgets/pdf-viewer.md](widgets/pdf-viewer.md).
+
 ---
 
 ## Pre-flight: Collect Required Information
@@ -402,6 +404,8 @@ Edit `Form.css` only for **structural** Q5 changes the tokens can't express —
 
 The document source was already settled in **Q3-doc** (direct file input → Attachments, file path (string) input → Buckets, Data Fabric attachment → Entities + Attachments). If it was not — e.g. the user only said "load a PDF from a storage bucket" — go back and ask Q3-doc first; that phrasing does not pick a path. Fetching the bytes for any of those is straightforward — get the file from the service, build a blob URL (`URL.createObjectURL(blob)`), and pass it to the viewer below as `fileUrl`. The part agents get wrong is the **rendering** inside Action Center's sandboxed iframe — that is what the example below exists to get right.
 
+> **Prefer the PDF Viewer widget when installable.** `@uipath/ui-widgets-pdf-viewer` replaces this hand-rolled DocumentTab — packaged pdf.js worker (no CDN fetch to be blocked by CSP), bucket/Data Fabric/URL/blob sources without manual byte-fetching, toolbar, password prompts. Follow [widgets/pdf-viewer.md](widgets/pdf-viewer.md), which starts with the required publish-status check. Use the DocumentTab pattern below only when the widget is not yet published/installable.
+
 #### Anti-pattern warning — ALWAYS enforce
 
 > **If the user's code or plan uses `<embed>`, `<object>`, `<iframe src="...">`, or any browser-native PDF embedding tag to display PDFs, stop and warn them:**

package/skills/uipath-coded-apps/references/create-web-app.md

@@ -227,6 +227,16 @@ Method signatures come from the installed types (`node_modules/@uipath/uipath-ty
 
 If the user wants a **Document Understanding validation UI** (review/correct extraction results), embed the Validation Station widget — see [widgets/validation-station.md](widgets/validation-station.md). Required scope: `OR.Buckets` (plus `OR.Tasks` if the widget completes an Action Center task on save). Add to the `scope` field in `uipath.json` during Step 4.
 
+More prebuilt `@uipath/ui-widgets-*` components — prefer these over hand-rolled UI, and add each widget's scopes to `uipath.json` during Step 4 ([oauth-scopes.md](oauth-scopes.md) § Widgets):
+
+| Widget | Use for | Guide |
+|--------|---------|-------|
+| Conversational Agent chat | Chat UI over a conversational agent (streaming, attachments, history) | [widgets/conversational-agent-chat.md](widgets/conversational-agent-chat.md) |
+| DataTable | CRUD grid over a Data Fabric entity | [widgets/datatable.md](widgets/datatable.md) |
+| Multi-file upload | Upload files to a storage bucket | [widgets/multi-file-upload.md](widgets/multi-file-upload.md) |
+| PDF viewer | Display PDFs from buckets, entity attachments, or URLs | [widgets/pdf-viewer.md](widgets/pdf-viewer.md) |
+| External auth | Sign-in buttons for external IdPs (Google/SAML) — NOT UiPath login | [widgets/external-auth.md](widgets/external-auth.md) |
+
 When implementing specific SDK services, read the corresponding reference:
 
 | Service | Reference |

package/skills/uipath-coded-apps/references/debug.md

@@ -497,6 +497,22 @@ Check the browser console for the error. Common causes: missing `@uipath/coded-a
 
 After fixing, rebuild (`npm run build`) and re-deploy (`uip codedapp deploy`). If 404 persists, check that `deploy` returned a valid `appUrl` in `.uipath/app.config.json`.
 
+### `publish` / `deploy` Fails Under a Client-Credentials Login
+
+These are **CLI session** scope failures — distinct from the app's own runtime scopes in `uipath.json` (see [`invalid_scope` Error in Auth URL](#invalid_scope-error-in-auth-url) for that). The session scope comes from `--scope` on `uip login`; the fix is always to re-login requesting `OR.Default` (Orchestrator) **and** `Apps.Read Apps.Write` (Apps service) together:
+
+```bash
+uip login --client-id <id> --client-secret <secret> \
+  --organization <org> --tenant <tenant> \
+  --scope "OR.Default Apps.Read Apps.Write"
+```
+
+| Symptom | Cause |
+|---------|-------|
+| Package upload succeeds, then `publish`'s "Registering coded app" step fails with `401` | Session scope is missing `Apps.Read Apps.Write` — registration hits the Apps service, not Orchestrator |
+| `uip or folders list` returns zero rows with `Result: Success`, and `deploy` then rejects a correct `--folder-key` as *"not found among folders accessible to your account"* | Session scope is missing `OR.Default`. Granular Orchestrator scopes (`OR.Folders`/`OR.Execution`/`OR.Administration`) authenticate and publish, but do not cover the folder lookup `deploy` validates against — so the misleading error is about the token, not the GUID |
+| `uip login` itself fails with `invalid_scope` | A requested name is not granted on the External Application. Matching is exact, not hierarchical — requesting `OR.Folders` against an `OR.Folders.Read` grant is rejected. `OR.Default` is auto-granted, so the app itself needs only `Apps.Read` + `Apps.Write` |
+
 ---
 
 ## External Application Setup

package/skills/uipath-coded-apps/references/oauth-client-setup.md

@@ -24,6 +24,8 @@ Needed inputs: app name, redirect URI(s), required OAuth scopes (from [oauth-sco
 
 The CLI takes **flat, comma-separated scope names** (e.g. `OR.Assets,OR.Tasks.Read`) — no portal resource-label grouping. Identity resolves each scope to its resource. Coded web apps use the browser PKCE (authorization_code) flow, so they need **`--user-scope`** (delegated), and a non-confidential client:
 
+> **Delimiter trap — `uipath.json` vs CLI.** The `scope` field in `uipath.json` is **space**-separated; `--user-scope`/`--app-scope` are **comma**-separated. Never paste the `uipath.json` string into the CLI: a space-separated list is sent as ONE scope name and fails with `HTTP 400: ... Not all scopes=<your whole list> are present in database` — even though every individual name is valid. Convert spaces → commas first.
+
 - `--non-confidential` — public client, no secret (required for browser PKCE).
 - Non-confidential apps support `--user-scope` only. Do NOT pass `--app-scope` with `--non-confidential` — the CLI rejects it.
 - `--redirect-uri` is required for non-confidential / `--user-scope` apps.
@@ -90,7 +92,7 @@ Fall back to the [Manual portal steps](#manual-portal-fallback) only when:
 - the signed-in identity lacks external-app admin permission (`403`) — hand the manual steps to an org admin, OR
 - the CLI genuinely lacks the verb (`uip admin external-apps --help` shows nothing — very old CLI; prefer upgrading).
 
-A missing scope name (`scope not found`) is NOT a fallback trigger — fix the name via `uip admin scopes list` and retry.
+A missing scope name (`scope not found` / `Not all scopes=<list> are present in database`) is NOT a fallback trigger. If the rejected `scopes=` string contains **spaces**, the delimiter is the bug — comma-separate and retry (see [Scope model](#scope-model--cli-vs-portal)). Otherwise fix the name via `uip admin scopes list` and retry.
 
 ## Manual portal fallback
 

package/skills/uipath-coded-apps/references/oauth-scopes.md

@@ -56,7 +56,42 @@ Scopes required by `@uipath/ui-widgets-*` React components. The widget's own run
 
 See [widgets/validation-station.md](widgets/validation-station.md) for the full integration guide.
 
-> **TODO:** Document scopes for the remaining widgets when their integration guides land in `references/widgets/`:
-> - `@uipath/ui-widgets-conversational-agent-chat`
-> - `@uipath/ui-widgets-datatable`
-> - `@uipath/ui-widgets-multi-file-upload`
+### Conversational Agent Chat (`@uipath/ui-widgets-conversational-agent-chat`)
+
+| Required Scope | Why |
+|----------------|-----|
+| `OR.Execution OR.Folders OR.Jobs ConversationalAgents` | Agent resolution, conversation create/list, WebSocket session, attachment upload — the Conversational Agent bundle above. |
+| `Traces.Api` | The widget's feedback flow (`createFeedback` on thumbs up/down). Omitting it breaks feedback silently. |
+
+See [widgets/conversational-agent-chat.md](widgets/conversational-agent-chat.md) for the full integration guide.
+
+### DataTable (`@uipath/ui-widgets-datatable`)
+
+| Required Scope | Why |
+|----------------|-----|
+| `DataFabric.Schema.Read` | Widget reads the entity schema to build columns. |
+| `DataFabric.Data.Read` | Record listing, choice-set/foreign-key resolution, file download. |
+| `DataFabric.Data.Write` | Commit/insert/delete flows and file upload/remove — the grid ships with editing enabled. Omit only if every column is set `editable: false`. |
+
+See [widgets/datatable.md](widgets/datatable.md) for the full integration guide.
+
+### Multi-File Upload (`@uipath/ui-widgets-multi-file-upload`)
+
+| Required Scope | Why |
+|----------------|-----|
+| `OR.Buckets` | Widget uploads files to a storage bucket — a write; read-only `OR.Buckets.Read` is insufficient. |
+
+See [widgets/multi-file-upload.md](widgets/multi-file-upload.md) for the full integration guide.
+
+### PDF Viewer (`@uipath/ui-widgets-pdf-viewer`)
+
+| Required Scope | Why |
+|----------------|-----|
+| `OR.Buckets.Read` (or `OR.Buckets`) | Bucket sources — the widget resolves a read URI and fetches the document. |
+| `DataFabric.Data.Read` | Entity sources — the widget downloads the record's file attachment. |
+
+Only the scope for the source shape(s) the app actually uses; `url`/`data` sources need no scopes. See [widgets/pdf-viewer.md](widgets/pdf-viewer.md) for the full integration guide.
+
+### External Auth (`@uipath/ui-widgets-external-auth`)
+
+No UiPath scopes — the widget makes no UiPath API calls (it starts logins at external IdPs). See [widgets/external-auth.md](widgets/external-auth.md).

package/skills/uipath-coded-apps/references/pack-publish-deploy.md

@@ -45,7 +45,6 @@ uip codedapp pack dist -n my-webapp --version 1.0.0 -a "My Team" --description "
 | `--main-file <file>` | Main entry file | `index.html` |
 | `--content-type <type>` | `webapp`, `library`, or `process` | `webapp` |
 | `--dry-run` | Preview without creating | `false` |
-| `--reuse-client` | Reuse clientId from `uipath.json` | `false` |
 
 ### Content Types
 
@@ -69,9 +68,7 @@ The `.nupkg` includes auto-generated UiPath metadata files:
 
 ### OAuth Client ID
 
-Pack manages the `uipath.json` SDK config file, which includes the OAuth client ID for the deployed app:
-- First pack: creates a new non-confidential client ID
-- Subsequent packs: use `--reuse-client` to keep the existing client ID from `uipath.json`
+`pack` **copies `uipath.json` verbatim** into the package — it does **not** create, mint, or modify the OAuth client ID. The `clientId` is set once at **scaffold time** (from the External Application) and carried through unchanged by every pack. `uipath.json` is the single source of truth — ensure its `clientId` is correct before packing.
 
 ### Dry Run
 
@@ -112,7 +109,7 @@ uip codedapp publish -n my-webapp --version 1.0.0
 | Option | Description | Default |
 |--------|-------------|---------|
 | `-n, --name <name>` | Package name (skip interactive selection) | Auto or prompted |
-| `-v, --version <version>` | Package version (requires `--name`) | Latest |
+| `-v, --version <version>` | Package version (requires `--name`). Selects the **first** matching `.nupkg` in unsorted `readdir` order — NOT the highest version. Always pass when multiple versions of the same name sit in `.uipath/`, else publish may pick an old already-published version → `already exists`. | First name match |
 | `-t, --type <type>` | App type: `Web` or `Action` | `Web` |
 | `--uipath-dir <dir>` | Directory containing `.nupkg` files | `./.uipath` |
 
@@ -128,11 +125,13 @@ uip codedapp publish -n my-webapp --version 1.0.0
 ### What Happens Internally
 
 1. Selects the `.nupkg` file (auto-select, by name, or interactive)
-2. Uploads the package to Orchestrator via the OData API — needs Orchestrator scopes (`OR.Folders`, `OR.Execution`, `OR.Administration`, or `OR.Default`)
+2. Uploads the package to Orchestrator via the OData API — needs `OR.Default`
 3. Registers the coded app with the UiPath Apps service — needs `Apps.Read Apps.Write`
 4. Creates `.uipath/app.config.json` with registration metadata
 
-> **Steps 2 and 3 hit different services with different scope requirements.** The `uip login` session `--scope` must cover **both**. If it has only Orchestrator scopes, step 2 succeeds and step 3 silently 401s ("Registering coded app" fails). Interactive `uip login` grants a broad default that includes both; client-credentials logins must list `Apps.Read Apps.Write` explicitly. These are the *CLI session* scopes — separate from the runtime OAuth scopes in `uipath.json`.
+> **Steps 2 and 3 hit different services with different scope requirements.** The `uip login` session `--scope` must cover **both services** — Orchestrator for step 2, the Apps service for step 3. Interactive `uip login` grants a broad default that includes both; client-credentials logins must request `OR.Default Apps.Read Apps.Write` explicitly, and granular Orchestrator scopes are not a substitute for `OR.Default`. These are the *CLI session* scopes — separate from the runtime OAuth scopes in `uipath.json`. For the failure signatures when either scope set is missing, see [debug.md](debug.md#publish--deploy-fails-under-a-client-credentials-login).
+
+> **`pack`/`publish`/`deploy` read org, tenant, base URL, and token from your `uip login` session** — you don't pass `--org-id`, `--tenant-id`, `--base-url`, or set a `.env` for them. Any `uip login` populates the session (interactive or client-credential). This is the *CLI session* config — distinct from `orgName`/`tenantName`/`baseUrl` in `uipath.json`, which configure the deployed app's **runtime SDK** calls, not the CLI.
 
 ### App Config File
 
@@ -187,8 +186,9 @@ uip codedapp deploy -n my-webapp
 |--------|-------------|---------|
 | `-n, --name <name>` | App name | From `app.config.json` or prompted |
 | `-v, --version <version>` | Target a **specific published version** (different semantic from `pack`/`publish`'s `-v`). **Prefer omitting it** — let it default to Latest. Passing a version that the catalog hasn't finished indexing yields a misleading `"...has not been published yet"` error. | Latest |
+| `--path-name <slug>` | URL slug (routing name). **First deploy sets it**; on **upgrade** it's optional — omit to keep the current URL. See "Routing Name on Upgrade" below. | Sanitized app name |
 | `--folder-key <key>` | UiPath folder **key** (GUID, not the name). **Always pass explicitly** — see below. | From `UIPATH_FOLDER_KEY` env var, else interactive (avoid) |
-| `--org-name <name>` | Organization name (for app URL) | From `.env` |
+| `--org-name <name>` | Organization name (for app URL) | From `uip login` session |
 
 ### Fresh Deploy vs. Upgrade
 
@@ -202,6 +202,20 @@ The command resolves the app name from:
 2. `.uipath/app.config.json` (created by `publish`)
 3. Interactive prompt (fallback)
 
+Deploy picks fresh-vs-upgrade purely on whether the app is **already deployed** (matched by display title) — **not** on the version. `-v` only selects which published version an upgrade targets.
+
+### Routing Name (`--path-name`) on Upgrade
+
+`--path-name` sets the app's **URL slug** (routing name). How it's treated depends on the fresh-vs-upgrade path above:
+
+- **First deploy:** creates the slug. Omitted → defaults to the sanitized app name. If the slug is already taken → `routing name must be unique`.
+- **Upgrade, `--path-name` omitted:** routing name unchanged; app keeps its current URL. **Default and safest — use this for a normal upgrade.**
+- **Upgrade, current slug re-passed:** no-op, accepted.
+- **Upgrade, new unused slug:** routing name is **rewritten** — the app's URL **changes**.
+- **Upgrade, slug taken by another app (or one this app previously used and moved off):** ❌ `routing name must be unique`. Vacated slugs were **not** reusable in testing — treat prior routing names as reserved.
+
+> **On upgrade, omit `--path-name` unless you deliberately want to change the URL.** Re-passing a slug the app no longer owns fails with `routing name must be unique`.
+
 ### Folder Key
 
 The `deploy` command requires a folder **key** (GUID), not a folder name. Users typically know the folder name only — resolve the key via `uip or folders list` before calling `deploy`.
@@ -215,7 +229,7 @@ Resolution order:
 
 #### Resolving folder name → folder key
 
-When the user provides a folder **name** (e.g., `"Shared"`), resolve it to a key with `uip or folders list --output json` and match on the `Name` field (or `Path` for nested paths).
+When the user provides a folder **name** (e.g., `"Shared"`), resolve it with the **server-side `--name` filter** — do **not** fetch the full list and match client-side. The plain list is **paginated at 50 per page**, so a folder beyond the first page is silently missed. `--name` (contains match), `--path` (prefix), and `--type` all **require `--all`**.
 
 > **Prerequisite:** `uip or ...` commands require the Orchestrator tool. Run `uip tools list` first; if `orchestrator-tool` is missing, install it once: `uip tools install @uipath/orchestrator-tool`.
 
@@ -223,10 +237,10 @@ When the user provides a folder **name** (e.g., `"Shared"`), resolve it to a key
 # 0. Ensure the Orchestrator tool is installed (idempotent — skip if already present)
 uip tools list --output json | grep -q '"orchestrator-tool"' || uip tools install @uipath/orchestrator-tool
 
-# 1. List folders the current user has access to (includes Personal, Solution, Standard)
-uip or folders list --output json > /tmp/folders.json
+# 1. Filter by name server-side (--name is a CONTAINS match, and requires --all)
+uip or folders list --all --name "Shared" --output json > /tmp/folders.json
 
-# 2. Resolve "Shared" → key (GUID)
+# 2. Pick the EXACT-name match — --name may return several; never blindly take .Data[0]
 FOLDER_KEY=$(python3 -c "
 import json
 with open('/tmp/folders.json') as f:
@@ -239,11 +253,12 @@ print(match['Key'] if match else '')
 uip codedapp deploy -n my-webapp --folder-key "$FOLDER_KEY"
 ```
 
-If the name is ambiguous (multiple matches) or not found, surface an error to the user — do NOT fall through to interactive selection.
+If the exact name is ambiguous (multiple exact matches) or not found, surface an error — do NOT fall through to interactive selection.
 
-`uip or folders list` returns folders the **current user** has access to (personal workspaces, solution folders, and standard folders). Add `--all` if you need every folder in the tenant — but for `deploy` resolution, the default view is what you want.
+- `--all` covers **Standard + Solution** folders. A **personal workspace** is *not* in `--all` — resolve it from the default `uip or folders list --output json` where `Type == "Personal"` (or `uip or folders list --all --type personal`).
+- For a nested folder, use `--path "<prefix>"` (also requires `--all`).
 
-Each folder JSON object includes: `Key` (GUID — pass this to `--folder-key`), `Name`, `Path`, `Description`, `Type` (`Personal` / `Solution` / `Standard`), `ParentKey`.
+Each folder JSON object includes: `Key` (GUID — pass this to `--folder-key`), `Name`, `Path`, `Type` (`Personal` / `Solution` / `Standard`), `ParentKey`.
 
 #### Storing the resolved key
 
@@ -311,10 +326,10 @@ uip codedapp deploy
 
 ```bash
 # Non-interactive flow with explicit options — every flag passed, no prompts.
-# --scope MUST include Apps.Read Apps.Write, or publish's "Registering coded app"
-# step 401s even though the package upload succeeds (see publish internals above).
+# --scope MUST name OR.Default (Orchestrator) AND Apps.Read Apps.Write
+# (Apps-service registration in publish) — neither set covers the other.
 uip login --client-id $CLIENT_ID --client-secret $CLIENT_SECRET \
-  --scope "OR.Folders OR.Execution OR.Administration Apps.Read Apps.Write"
+  --scope "OR.Default Apps.Read Apps.Write"
 npm run build
 uip codedapp pack dist -n my-webapp --version $VERSION
 uip codedapp publish -n my-webapp --version $VERSION
@@ -341,9 +356,10 @@ uip codedapp deploy -n my-webapp --folder-key "$FOLDER_KEY"
 | Problem | Cause | Solution |
 |---------|-------|----------|
 | `No packages found` | Missing `.nupkg` | Run `uip codedapp pack` first |
-| `Version already exists` | Same version published | Bump version: `-v 2.0.0` |
-| `App not found` on deploy | App not published | Run `uip codedapp publish` first |
+| `Published app with package name '<name>' and version '<version>' already exists` (HTTP 400 on publish) | That name+version is already published — the upload step succeeds (`Package already exists … proceeding`), then **registration** rejects the duplicate | Bump `--version` and re-publish |
+| `App not found` on deploy | App genuinely not published | Run `uip codedapp publish` first |
+| `has not been published yet` / `still being indexed` right after a successful publish | Catalog **indexing lag** — not a missing package | CLI auto-retries ~15s (1/2/4/8s backoff). If it still fails, **wait a few seconds and rerun `deploy`**. If you passed `-v <version>`, drop it — deploy defaults to Latest. |
 | `Folder key required` / deploy hangs on prompt | Missing folder key | Resolve via `uip or folders list --output json`, then run `uip codedapp deploy --folder-key <key> ...` (or `UIPATH_FOLDER_KEY=<key>` env-var prefix). |
 | `Missing tenant name` on publish | `UIPATH_TENANT_NAME` not set | Set in `.env` or pass `--tenant-name` |
 | `dist/ not found` | App not built | Run `npm run build` |
-| Pack shows wrong clientId | Stale `uipath.json` | Use `--reuse-client` or delete `uipath.json` |
+| Pack shows wrong clientId | Stale `uipath.json` | `pack` copies `uipath.json` verbatim — fix `clientId` there. |

package/skills/uipath-coded-apps/references/sdk/conversational-agent.md

@@ -2,6 +2,8 @@
 
 Signatures/params/examples for services, event-helper classes, options, enums: `dist/conversational-agent/index.d.ts`. Per-method scopes: shipped `docs/oauth-scopes.md`. This file covers only what neither can express.
 
+> **Building a chat UI with a conversational agent?** The `@uipath/ui-widgets-conversational-agent-chat` widget ships the complete chat experience (streaming, attachments, history, feedback) — embed it instead of hand-wiring: [../widgets/conversational-agent-chat.md](../widgets/conversational-agent-chat.md). Use this file when the widget's UI cannot express the requirement.
+
 > **Scope fork warning:** scopes differ per METHOD GROUP inside this one service (agent reads vs conversation create/update vs sessions vs feedback vs user settings each need a different scope set). Never assume service-uniform scopes — check the shipped per-method table; task-level bundles: [../oauth-scopes.md](../oauth-scopes.md).
 
 ## Session Lifecycle (WebSocket)

package/skills/uipath-coded-apps/references/sdk/data-fabric.md

@@ -4,6 +4,8 @@ Signatures/params/examples: `dist/entities/index.d.ts` (trigger-event behavior d
 
 > **Scope pairing warning:** schema introspection (`entities.getAll()` / `getById()`) and record I/O sit in different scope pairs — `DataFabric.Schema.Read` vs `DataFabric.Data.Read` / `DataFabric.Data.Write`. This file mandates schema introspection before writes and filters, so an app with only Data scopes 403s on the introspection step. Check the shipped table per method.
 
+> **Building a CRUD grid over one entity?** Embed the DataTable widget instead of hand-wiring ag-Grid + record I/O — [../widgets/datatable.md](../widgets/datatable.md). The traps below still apply to any direct SDK calls the host app makes around it.
+
 ## Anti-shapes & gotchas (read first)
 
 Data Fabric does NOT behave like a typical RDBMS. These server behaviors are invisible to both the types and the JSDoc. Before writing analytics, filters, or update logic, call `entities.getById(id)` and inspect `fields[].name` + `fieldDataType.name`. Pick your data strategy from what's actually there — do NOT assume.

package/skills/uipath-coded-apps/references/sdk/orchestrator.md

@@ -66,6 +66,8 @@ export const fetchDetailByKey: MetricDetailByKeyFn = async (sdk, agentName) => {
 
 `getFiles` (folder-aware `BucketFile` items, regex filtering) vs `getFileMetaData` (flat `BlobItem` list by `prefix`): prefer **`getFiles`** for directory-style browsing. Neither method's JSDoc mentions the other. Note `JobGetResponse.process` is populated only via `expand` (its JSDoc, unlike `machine`/`robot`, does not say so).
 
+Bucket UI shortcuts: uploading files → Multi-File Upload widget ([../widgets/multi-file-upload.md](../widgets/multi-file-upload.md)); displaying a bucket PDF → PDF Viewer widget ([../widgets/pdf-viewer.md](../widgets/pdf-viewer.md)).
+
 ## Attachments Service
 
 Cross-artifact role the types don't show: Coded Action Apps resolve a `type: "file"` input — the file reference handed in by the automation (Maestro / Agent / RPA) — into bytes via `Attachments.getById()` → `blobFileAccess` (signed URL + headers). `Jobs.getOutput()` uses the same service internally for file-type outputs (see scope pairing warning above). When `blobFileAccess.requiresAuth` is `true`, pass `blobFileAccess.headers` on the download request.

package/skills/uipath-coded-apps/references/widgets/conversational-agent-chat.md

@@ -0,0 +1,90 @@
+# Conversational Agent Chat Widget
+
+React chat interface for UiPath **Conversational Agents**: streaming responses, file attachments, tool-call visualization, conversation history, and thumbs-up/down feedback — all prebuilt.
+
+Package: [`@uipath/ui-widgets-conversational-agent-chat`](https://www.npmjs.com/package/@uipath/ui-widgets-conversational-agent-chat). Full prop/API surface lives in the package README — this file covers only the integration steps that are easy to get wrong inside a Coded App.
+
+## When to Use
+
+- User asks to **chat with / talk to / embed a chat for** a conversational agent inside a coded app.
+- Replaces a hand-rolled chat UI over the SDK's session/exchange events. Do **not** rebuild streaming, attachments, history, or feedback from scratch — the widget already wires all of it. Hand-roll with [../sdk/conversational-agent.md](../sdk/conversational-agent.md) only when the widget's UI genuinely cannot fit (e.g., fully custom message rendering).
+
+**Two exports.** `ConversationalAgentChat` — chat with a known agent (`agentId`). `ConversationalAgentPickerChat` — lists all agents the SDK session can access, user picks one, chat opens; use when `agentId`/`folderId` are not known up front.
+
+## Critical Rules
+
+1. **Peer versions are hard requirements.** `react >= 19.2.0`, `react-dom >= 19.2.0`, `@uipath/uipath-typescript >= 1.5.5` — note the SDK floor is **higher** than other widgets. Verify `package.json` before installing.
+2. **Import the stylesheet once** or the chat renders unstyled: `import '@uipath/ui-widgets-conversational-agent-chat/ConversationalAgentChat.css'`.
+3. **Body needs `light` or `dark` class** for theming.
+4. **Reuse the app's initialized `UiPath` instance** (`useAuth()` in web apps). Do not construct a second SDK for the widget.
+5. **Required scopes:** `OR.Execution OR.Folders OR.Jobs ConversationalAgents Traces.Api` — the Conversational Agent bundle in [../oauth-scopes.md](../oauth-scopes.md). `Traces.Api` covers the feedback (thumbs up/down) flow; omitting it breaks feedback silently.
+6. **`agentId` is the numeric agent release id, not the agent name.** Pass `folderId` whenever known — when omitted, the widget lists all agents to resolve it (extra calls, slower first paint).
+7. **Give the widget a bounded-height container.** It fills its parent; an auto-height parent collapses the chat. Wrap in a fixed-height or flex-sized element (e.g. `height: '80vh'` or a `flex: 1` pane).
+8. **No special `vite.config.ts` setup.** Unlike Validation Station, no asset-copy plugins or `optimizeDeps.exclude` needed. PDF attachment previews run pdf.js on the main thread inside the widget — no worker config.
+
+## Install
+
+From inside the scaffolded app directory:
+
+```bash
+npm install @uipath/ui-widgets-conversational-agent-chat --@uipath:registry=https://registry.npmjs.org
+```
+
+Registry flag forces the public npm registry (skill default — users may have `@uipath` scoped to GitHub Packages).
+
+## Key Props
+
+Full tables in the package README. Inside a coded app you usually only touch:
+
+### `ConversationalAgentChat`
+
+| Prop | Required | Notes |
+|------|----------|-------|
+| `sdk` | Yes | Initialized `UiPath` instance from `useAuth()`. |
+| `agentId` | No* | Numeric agent release id. *Required unless `existingConversationId` is provided. |
+| `folderId` | No | Folder the agent lives in. Pass when known — avoids a resolve-by-listing round trip. |
+| `existingConversationId` | No | Open an existing conversation instead of creating one on first message. |
+| `inputSchema` | No | Overrides the schema derived from the resolved agent (e.g., in-progress draft agents). |
+| `isDebugMode` | No | Debug flow: opens an empty conversation up front; submits update it instead of creating new ones. |
+| `externalUserId` | No | Sent as `x-uipath-external-user-id`. Only for app-scoped external-app tokens; omit for standard user tokens. |
+
+### `ConversationalAgentPickerChat`
+
+| Prop | Required | Notes |
+|------|----------|-------|
+| `sdk` | Yes | Changing it refetches the agent list and resets the UI. |
+| `theme` / `locale` / `readOnly` / `overrideLabels` | No | Passthrough to the inner chat. |
+| `onAgentSelected` | No | `(agent) => void` — telemetry/routing hook when the user picks an agent. |
+
+Picker behavior: lists agents via `new ConversationalAgent(sdk).getAll()`, one row per agent; clicking opens the chat with that agent's `id`/`folderId`; "Back" returns to the list without refetching. To switch tenants, rebuild the `UiPath` instance and pass the new one as `sdk`.
+
+## Integration: Web App
+
+```typescript
+import { ConversationalAgentChat } from '@uipath/ui-widgets-conversational-agent-chat';
+import '@uipath/ui-widgets-conversational-agent-chat/ConversationalAgentChat.css';
+import { useAuth } from '../hooks/useAuth';
+
+function AgentChatPage({ agentId, folderId }: { agentId: number; folderId: number }) {
+  const { sdk } = useAuth();
+
+  return (
+    <div style={{ height: '80vh' }}>
+      <ConversationalAgentChat sdk={sdk} agentId={agentId} folderId={folderId} />
+    </div>
+  );
+}
+
+export default AgentChatPage;
+```
+
+Agent id unknown at build time? Either render `ConversationalAgentPickerChat` (user picks), or resolve programmatically with the SDK (`new ConversationalAgent(sdk).getAll()` → match on name → pass `id` + `folderId`; import from `@uipath/uipath-typescript/conversational-agent`).
+
+## Anti-patterns
+
+- **Do not hand-roll the chat UI with `startSession()`/`onExchangeStart` when this widget fits.** [../sdk/conversational-agent.md](../sdk/conversational-agent.md) is for custom UIs the widget cannot express.
+- **Do not construct a second `UiPath` SDK** for the widget. Reuse the app's authenticated instance.
+- **Do not pass the agent name as `agentId`** — it is the numeric release id.
+- **Do not skip the CSS import** — the widget renders but looks broken (unstyled Apollo components).
+- **Do not set `externalUserId` for normal user-token sessions** — it is only for app-scoped external application auth.
+- **Do not drop `Traces.Api` from the scope** because "the app doesn't use traces" — the widget's feedback buttons need it.

package/skills/uipath-coded-apps/references/widgets/datatable.md

@@ -0,0 +1,97 @@
+# DataTable Widget
+
+React datatable (ag-Grid) over a single **Data Fabric entity**: CRUD, inline editing with diff review, master-detail grouping by foreign key, choice sets, file fields, filtering/sorting/pagination — all prebuilt.
+
+Package: [`@uipath/ui-widgets-datatable`](https://www.npmjs.com/package/@uipath/ui-widgets-datatable). Full prop/API surface lives in the package README — this file covers only the integration steps that are easy to get wrong inside a Coded App.
+
+## When to Use
+
+- User asks to **browse, edit, or manage records** of a Data Fabric entity in a grid/table.
+- Replaces a hand-rolled ag-Grid/table + entity CRUD plumbing. Do **not** rebuild this UI from scratch — the widget already handles schema-driven columns, per-field-type editors, diff/commit, choice-set and foreign-key resolution, and file upload/download.
+- For custom read-only tables over *non-entity* data (Jobs, Tasks, etc.), use the standard table patterns in [../patterns.md](../patterns.md) instead — this widget only renders Data Fabric entities.
+
+## Critical Rules
+
+1. **Peer versions are hard requirements.** `react >= 19.2.0`, `react-dom >= 19.2.0`, `@uipath/uipath-typescript >= 1.4.1`.
+2. **Import the stylesheet once** or the grid renders unstyled: `import '@uipath/ui-widgets-datatable/DataTable.css'`.
+3. **Body needs `light` or `dark` class** for theming.
+4. **`entityId` is the entity UUID, not the display name.** Resolve it via `new Entities(sdk).getAll()` at runtime or `uip df entities list --output json` at build time. Passing the friendly name fails. See [../sdk/data-fabric.md](../sdk/data-fabric.md).
+5. **Required scopes:** `DataFabric.Schema.Read DataFabric.Data.Read` to display; add `DataFabric.Data.Write` because the grid ships with editing enabled (commit/insert/delete/file upload 403 without it). See [../oauth-scopes.md](../oauth-scopes.md).
+6. **There is no global read-only prop.** To present a read-only grid, disable editing per column via `columnConfig` (`editable: false`) — otherwise users can edit cells and the commit fails or writes data you didn't intend.
+7. **`columnConfig` keys are column display names**, not entity field names (e.g. `"Edition Name"`, not `editionName`).
+8. **The widget already paginates** (ag-Grid, `pageSize` default 50) — this satisfies the skill's table-pagination rule. Do not wrap it in your own pagination or fetch records yourself; there is no prop to inject rows — the widget fetches from the entity itself.
+9. **Reuse the app's initialized `UiPath` instance** (`useAuth()`); do not construct a second SDK.
+10. **No special `vite.config.ts` setup** — no asset plugins or `optimizeDeps` changes needed.
+
+## Install
+
+From inside the scaffolded app directory:
+
+```bash
+npm install @uipath/ui-widgets-datatable --@uipath:registry=https://registry.npmjs.org
+```
+
+Registry flag forces the public npm registry (skill default — users may have `@uipath` scoped to GitHub Packages).
+
+## Key Props
+
+| Prop | Required | Notes |
+|------|----------|-------|
+| `sdk` | Yes | Initialized `UiPath` instance from `useAuth()`. |
+| `entityId` | Yes | Data Fabric entity **UUID**. |
+| `pageSize` | No | Rows per page (default 50). |
+| `showIdColumn` | No | Show the record Id column. |
+| `columnConfig` | No | `Record<displayName, ColDef>` — ag-Grid column overrides (width, `editable: false`, cell styles, class rules). |
+| `rowClassRules` | No | ag-Grid conditional row classes, e.g. `{ 'row-alert': p => p.data.status === 'Failed' }`. |
+| `customPaddingForExpandedRow` | No | Pixel padding for expanded rows in group-by mode. |
+
+## Built-in Flows (what the toolbar does)
+
+Know these so you don't duplicate them in the host app:
+
+- **Read** — loads schema + records on mount (`expansionLevel: 2`, choice sets pre-fetched); **Refresh** reloads.
+- **Update** — cell edits are tracked, **Show Diff (N)** opens original-vs-edited review with per-field revert, **Commit Changes** calls `updateRecords`.
+- **Create** — **Add Row** pins an empty row on top; **Insert Records** persists, **Discard** drops them.
+- **Delete** — checkbox selection → **Delete Records** → confirm dialog.
+- **Group by** — pick a foreign-key column; rows nest under master records. Inline editing and row selection are **disabled in group-by mode**.
+- **Field types** — text/multiline/number/date/boolean/single- and multi-choice sets/foreign keys handled automatically; DateTime renders read-only; File fields get upload/open/download/remove controls.
+
+## Integration: Web App
+
+```typescript
+import { DataTable } from '@uipath/ui-widgets-datatable';
+import '@uipath/ui-widgets-datatable/DataTable.css';
+import { useAuth } from '../hooks/useAuth';
+
+function RecordsPage({ entityId }: { entityId: string }) {
+  const { sdk } = useAuth();
+
+  return (
+    <DataTable
+      sdk={sdk}
+      entityId={entityId}
+      pageSize={50}
+      columnConfig={{ 'Created At': { editable: false } }}
+    />
+  );
+}
+
+export default RecordsPage;
+```
+
+Entity UUID unknown up front? List entities and let the user pick:
+
+```typescript
+import { Entities } from '@uipath/uipath-typescript/entities';
+
+const entities = await new Entities(sdk).getAll(); // [{ id, name, displayName }, ...]
+```
+
+## Anti-patterns
+
+- **Do not rebuild an entity CRUD grid by hand** (ag-Grid + `getAllRecords` + custom editors) when this widget fits.
+- **Do not pass the entity display name as `entityId`** — UUID only.
+- **Do not fetch records yourself and expect to feed them in** — there is no `rows`/`data` prop; the widget owns fetching.
+- **Do not ship with `DataFabric.Data.Read` only while editing is enabled** — edits fail at commit with 403; either add `DataFabric.Data.Write` or set columns `editable: false`.
+- **Do not key `columnConfig` by field name** — keys are display names.
+- **Do not seed or migrate data through the widget** — for bulk writes use the SDK/CLI directly; see [../sdk/data-fabric.md](../sdk/data-fabric.md) for choice-value translation traps.