@uipath/skills 1.200.0 → 1.201.0-preview.433

package/skills/uipath-api-workflow/references/operating-published-workflows.md

@@ -53,15 +53,26 @@ uip api-workflow validate ./Workflow.json --output json   # static: schema + sem
 uip api-workflow run ./Workflow.json --no-auth --output json  # runtime: expression / logic
 ```
 
-Faults that only surface in cloud (auth, connection state, real vendor responses, trigger wiring) are diagnosed from the deployed job:
+Faults that only surface in cloud (auth, connection state, real vendor responses, trigger wiring) are diagnosed from the deployed job. **`uip or jobs get` is the only surface that carries the fault** — verified end-to-end against a deliberately-faulting deployed API workflow (alpha, uip 1.200.0):
 
 ```bash
-uip or jobs get <jobId> --output json                  # status + fault summary
-uip or jobs logs <jobId> --output json                 # execution logs for the run
-uip traces spans get --job-key <jobKey> --output json  # span-level execution trace (also accepts a <trace-id> positional)
+uip or jobs get <jobId> --output json   # THE diagnostic: Data.State + Data.Info
 ```
 
-> `uip or jobs traces` is documented Agent-type-process-only — for an API-workflow job use `uip traces spans get --job-key <jobKey>` instead.
+`Data.State` is `Faulted`; `Data.Info` carries the runtime message, e.g.
+`"Worker operation failed: <the error your JavaScript or connector activity raised>"`.
+Read `Info` first — for an API workflow it is usually the whole answer.
+
+Two surfaces that look useful and are NOT, for API-workflow jobs:
+
+| Command | What it actually returns |
+|---------|--------------------------|
+| `uip or jobs logs <jobId>` | Lifecycle lines only — `"Workflow started"` / `"Workflow completed"`, both at level `Info`. It reports **`Workflow completed` even for a Faulted job** and never carries the error. Do not diagnose from it, and never read "completed" as success. |
+| `uip traces spans get --job-key <jobKey>` | Fails with `"Error retrieving trace ID for job"`. API-workflow jobs have no span/trace surface. |
+
+> **Diagnose before you tear down.** Uninstalling the deployment destroys its job records — `uip or jobs get <jobId>` then returns `Result: Failure` with an empty `State`. Capture what you need while the deployment still stands.
+
+> For per-activity detail the local loop is stronger than anything in cloud: reproduce with `uip api-workflow run <Workflow.json> --no-auth --output json`, which names the failing activity. Cloud gives you the fault message; local gives you its position.
 
 Map the surfaced error back to a fix using the category catalog in [troubleshooting.md](troubleshooting.md) (Structure > Expression > Activity Config > Logic). For deep, multi-signal root-cause investigations (what changed, cross-run comparison, incident correlation), hand off to **uipath-troubleshoot**.
 
@@ -71,4 +82,4 @@ Map the surfaced error back to a fix using the category catalog in [troubleshoot
 |------|--------------------------|-------------------------|
 | **Build** | `init`, edit, `validate`, `registry resolve`/`stub`, `pack` | — |
 | **Operate** | `run` (local execution) | `uip or jobs start <process-key>`/`list`/`stop`, `uip or triggers` (need `--folder-path`/`--folder-key`), `uip is connections` |
-| **Diagnose** | `validate` → `run --no-auth` loop, `uip is connections ping` | `uip or jobs logs`/`get`, `uip traces spans get --job-key`, uipath-troubleshoot |
+| **Diagnose** | `validate` → `run --no-auth` loop, `uip is connections ping` | `uip or jobs get` — `Data.Info` carries the fault; `jobs logs` and `traces spans get` do NOT work for API-workflow jobs. Then uipath-troubleshoot |

package/skills/uipath-automationhub/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: uipath-automationhub
+description: "Publish and read business processes in UiPath Automation Hub via the Open API, using the user's cloud login — no admin OpenAPI token needed. PUBLISH an approved process and its PDD/SDD documents (schema-driven payload, base64 file upload or link) to AH as the system of record — e.g. a process captured/approved by Process Scribe. GET a process back by id or search, list its attached documents, and DOWNLOAD their file bytes (e.g. for dedup / related-idea lookups or retrieving a published PDD). Authenticates with the user's cloud bearer token and NEVER sends the admin `x-ah-openapi-auth` header. Routes by intent to `references/publish-process.md` (publish/create/upload) or `references/get-process.md` (get/read/fetch/list), over the shared auth + endpoint catalog in `references/api-endpoints.md`. Structured to extend to more Automation Hub Open API operations."
+allowed-tools: Bash, Read, AskUserQuestion
+user-invocable: true
+---
+
+# UiPath Automation Hub — Open API Assistant
+
+Work with business processes in UiPath Automation Hub (AH) through the AH Open API, authenticating with the **user's cloud access token** — the user does **not** need an admin-generated OpenAPI token. This one skill covers both writing a process to AH and reading one back; pick the flow below.
+
+## Step 0: Read the API reference
+
+Always read [`references/api-endpoints.md`](references/api-endpoints.md) first. It is the shared source of truth for the cloud-token auth model, the base/gateway URL, the exact headers (**and which header to never send**), and every endpoint the flows use.
+
+## Authentication (shared — both flows)
+
+Resolve the cloud token + base URL + org + tenant in this **priority order**:
+
+1. **Runtime env-auth (preferred — how UiPath Delegate provides it).** If `UIPATH_CLI_AUTH_TOKEN` is set (with `UIPATH_CLI_ENABLE_ENV_AUTH=true`), use it as the bearer and take org/tenant from `UIPATH_CLI_ORGANIZATION_NAME` / `UIPATH_CLI_TENANT_NAME` (and the `..._ID` variants). Base URL defaults to `https://cloud.uipath.com`. *(If a parent `uip` process instead exported `UIPATH_ACCESS_TOKEN` + `UIPATH_URL` — the `{base}/{org}/{tenant}` shape — use those.)*
+2. **Logged-in `uip` session.** Otherwise, if the user has run `uip login`, read `~/.uipath/.auth` (JSON: `accessToken`, `baseUrl`, `organizationName`, `tenantName`).
+3. **User-provided (last resort).** Ask the user to paste a cloud bearer token plus their **org** and **tenant** slugs (the two path segments after the host in their AH URL).
+
+Use whatever you resolved as `$ACCESS_TOKEN`, `$BASE_URL`, `$ORG`, `$TENANT` in the flows.
+
+**Gateway URL** (every request):
+
+```
+{baseUrl}/{org}/{tenant}/automationhub_/api/v1/openapi
+```
+
+The platform injects tenant-routing headers from the `{org}/{tenant}` segments — always use this gateway URL.
+
+**Header rules (do not regress these):**
+
+- Send `Authorization: Bearer <cloud access token>` on every request (and `Content-Type: application/json` on POSTs).
+- **NEVER** send `x-ah-openapi-auth` or `x-ah-openapi-app-key`. Those route to the admin-token path and reject a cloud token with **401** — never add them to "fix" a 401.
+- Never fall back to an admin OpenAPI token. If no token resolves, stop and explain the skill needs the user's cloud session (`uip login`) or a host-provided token.
+- Cloud tokens are short-lived. On a **401**, if the token came from `~/.uipath/.auth`, tell the user to run `uip login` again, re-resolve, and retry.
+
+## Routing — pick the flow by intent
+
+Classify what the user wants, then follow the matching reference. All flows share the Authentication section above and the endpoint catalog in `references/api-endpoints.md`.
+
+| The user wants to... | Follow |
+|---|---|
+| **Publish / create / upload** a process (+ its PDD/SDD documents) to AH | [`references/publish-process.md`](references/publish-process.md) |
+| **Get / read / fetch / list** a process (+ its documents) from AH | [`references/get-process.md`](references/get-process.md) |
+| Shared **auth + endpoint catalog** (base URL, headers, every endpoint, error codes) | [`references/api-endpoints.md`](references/api-endpoints.md) |
+| _(future AH Open API operation — add a row here)_ <!-- uip-check-skip --> | _add `references/<operation>.md` and route to it_ |
+
+To add a new capability (e.g. a future AH `uip` CLI surface or another Open API operation), keep this skill's product shape: add one `references/<operation>.md`, add a row above, and reuse this shared Authentication section — do not create a new per-operation skill.
+
+## Notes
+
+- **Cloud token only** — authorization is the user's real AH permissions; you see and can do exactly what their AH role allows.
+- The publish flow fetches the idea-flow schema live, so it adapts automatically if fields change on the tenant.
+- **Open dependency:** in a hosted runtime (e.g. Process Scribe/Delegate) the cloud token is expected via the environment (Authentication, option 1). Confirm the runtime provides `UIPATH_CLI_AUTH_TOKEN` (or an equivalent) before relying on it in production.

package/skills/uipath-automationhub/references/api-endpoints.md

@@ -0,0 +1,140 @@
+# Automation Hub Open API — Reference (cloud-token auth)
+
+> This skill authenticates with the **user's UiPath cloud access token** — **not** an admin-generated OpenAPI token. This is the AH Open API's `automation-cloud` mode: send the bearer token and **do not** send `x-ah-openapi-auth`.
+
+This is the shared auth + endpoint catalog for both flows — [`publish-process.md`](publish-process.md) (write) and [`get-process.md`](get-process.md) (read).
+
+## Authentication
+
+### Getting the cloud token + org/tenant (in priority order)
+
+1. **Runtime env-auth (preferred — this is how UiPath Delegate provides it).** The runtime runs `uip` in a virtual shell with `UIPATH_CLI_ENABLE_ENV_AUTH=true` and sets `UIPATH_CLI_AUTH_TOKEN` (the user's cloud bearer token) plus `UIPATH_CLI_ORGANIZATION_NAME` / `UIPATH_CLI_TENANT_NAME` (and `..._ID` variants). If `UIPATH_CLI_AUTH_TOKEN` is set, use it as the bearer and take org/tenant from those vars. Base URL defaults to `https://cloud.uipath.com` unless the environment specifies another. *(If a parent `uip` process instead exported `UIPATH_ACCESS_TOKEN` + `UIPATH_URL` — the `{base}/{org}/{tenant}` shape — use those.)*
+2. **Logged-in `uip` session.** Otherwise, if the user has run `uip login`, read `~/.uipath/.auth` (JSON). Use its `accessToken`, `baseUrl`, `organizationName`, `tenantName`. If the file is missing or has no `accessToken`, tell the user to run `uip login` (and `uip login tenant set <name>` to pick the tenant).
+3. **User-provided (last resort).** Ask the user to paste a cloud bearer token plus their **org** and **tenant** slugs (the two path segments after the host in their AH URL).
+
+Never fall back to an admin OpenAPI token. If none of the above yields a token, stop and explain that the skill needs the user's cloud session (`uip login`) or a host-provided token.
+
+### Base URL
+
+```
+{baseUrl}/{org}/{tenant}/automationhub_/api/v1/openapi
+```
+
+e.g. `https://cloud.uipath.com/acme/prod/automationhub_/api/v1/openapi`. Always use this **gateway** URL — the platform injects the tenant-routing headers from the `{org}/{tenant}` segments. (Local dev: base `http://localhost:3002`, path `/api/v1/openapi`, and you must confirm how org/tenant are supplied locally.)
+
+### Headers (every request)
+
+| Header | Value | When |
+|--------|-------|------|
+| `Authorization` | `Bearer <cloud access token>` | always |
+| `Content-Type` | `application/json` | POST only |
+
+**Do NOT send** `x-ah-openapi-auth` or `x-ah-openapi-app-key`. Sending `x-ah-openapi-auth: openapi-token` routes to the admin-token path and rejects a cloud token with **401**.
+
+### Token expiry
+
+Cloud access tokens are short-lived. If any call returns **401** and the token came from `~/.uipath/.auth`, tell the user to run `uip login` again (or re-provide a token) and retry.
+
+## Endpoints used by this skill
+
+### GET `/idea-flows`
+All idea flows (workflow types) on the tenant. Each element has `Idea flow name` (e.g. "Business Process") and `Idea flow ID` (number). Response wrapped as `{ message, statusCode, data: [...] }`. *(Used by the publish flow.)*
+
+### GET `/idea-schema?idea_flow_id={id}`
+Full JSON schema for an idea flow + a ready-made `user_inputs` template. Response wrapped as `{ status: "success", data: {...} }`:
+- `data.properties.schema.properties` — field definitions, 3-level nested (Assessment Type > Section > Question); enums carry `answer_option` codes + labels in `custom_properties`.
+- `data.user_inputs` — the exact POST body template ("fill in the blanks"). Most fields wrap as `{ "value": <v> }`; owner/submitter questions take a direct string (no wrapper); questions with no example are omitted.
+
+*(Used by the publish flow.)*
+
+### POST `/idea-from-schema`
+Create a process from the schema. **Use this, not `POST /automations`** (the `/automations` alias 404s in some deployments).
+
+Body:
+```json
+{ "idea_flow_id": <id>, "user_inputs": { "<AssessmentType>": { "<section-ahid>": { "<question-key>": { "value": "<v>" } } } } }
+```
+**Do not POST `data.user_inputs` verbatim** — its example values are placeholders that the API rejects. Replace each with a real value; in particular resolve a **valid** `OVERVIEW_CATEGORY` id (the template's `1` → `Invalid Category Id`) and real `answer_option` codes (a placeholder code → backend `co_question_answer_option_value` crash).
+
+**Required fields (Business Process, `idea_flow_id`=7), verified live** — note the backend enforces owner + submitter even though the schema's `required` flags omit them:
+
+| Key | Section | Shape |
+|---|---|---|
+| `OVR-OVERVIEW_NAME` | `ah-section-ovr-0-0` | `{"value":"…"}` |
+| `OVR-OVERVIEW_DESCRIPTION` | `ah-section-ovr-0-0` | `{"value":"…"}` |
+| `OVR-OVERVIEW_CATEGORY` | `ah-section-ovr-0-0` | `{"value":<valid id>}` |
+| `OVR-PROCESS_DOCUMENTS` | `ah-section-ovr-0-0` | `{"value":["<answer_option code>"]}` |
+| `OVR-PROCESS_OWNER` | `ah-section-ovr-0-0` | `"<email>"` (direct string) |
+| `OVR-OVERVIEW_PROCESS_SUBMITTER` | `ah-section-ovr-0-1` | `"<email>"` (direct string) |
+
+When a required field is missing the API may return `errorDetails: {}` (no field named) with `"Please fill in all the required information"` — usually the un-flagged owner/submitter, but **tenant admins can mark additional questions required** (commonly "Applications used"/"Thin applications used"); diff the payload against every `required`-flagged question in the live schema.
+
+**Response 201** — the standard envelope with the created process **nested under `data`**: `{ "message": "Resource Created", "statusCode": 201, "data": { "process_id": …, "process_uuid": …, "process_name": … } }`. Read **`data.process_id`** — it is NOT at the top level. If you received a 201 the process WAS created — never re-POST because a field read came back undefined; re-read the response instead. *(Used by the publish flow.)*
+
+### POST `/automations/{process_id}/documents`
+Attach a document to a process — **by uploaded bytes (`file`) or by link (`embed_link`)**. Governed by `open-api-service` `ProcessDocumentValidator` (`src/api/v1/services/processDocumentValidator.class.ts`; schema `src/models/schema/processDocumentRequest.schema.ts`). **Required fields, verified against the validator source:**
+
+```json
+{
+  "document_title": "…",
+  "document_description": "…",
+  "document_type_id": 1,
+  "file": { "file_name": "…", "mimetype": "…", "file_content": "<base64>", "file_encoding": "base64" }
+}
+```
+
+- `document_title` (**not** `document_name`), `document_description`, `document_type_id` are all required by the schema.
+- **`document_type_id` values are fixed platform-wide** (from `tenant-service` `file.constants.js` — never guess):
+
+  | id | Type | id | Type |
+  |---|---|---|---|
+  | 1 | PDD (Process Definition Document) | 7 | INF (Input File) |
+  | 2 | SDD (Solution Design Document) | 8 | OUF (Output File) |
+  | 3 | DSD (Development Specification Document) | 9 | MISC ("Misc." — anything else) |
+  | 4 | SOP (Standard Operating Procedure) | 10 | TCD (Task Capture Document — **special**: accepts only `zip`/`ssp` uploads, **no embed_link**) |
+  | 5 | DWI (Detailed Work Instructions) | 11 | ASC (Automation Source Code) |
+  | 6 | PM (Process Map) | | |
+
+  Pick by the document's kind: PDD → `1`, SDD → `2`; when unsure, default to `9` (MISC).
+- Plus **exactly one** of `file` or `embed_link` — an XOR enforced in the handler, not the schema. Sending both, or neither, 400s with `"One and only one of embed_link or file need to be specified."`
+- **`file` — byte upload, the default.** Validated by `EncodedFileValidator`: `file_name`, `mimetype`, `file_content`, `file_encoding` are all required and must be non-empty, and `file_encoding` must be `base64` — the only accepted value. No mimetype allowlist. The JSON body limit is **300mb**, so a PDD-sized `.docx` or `.md` fits with room to spare.
+- **`embed_link`** — use only when the document already lives at a URL and the bytes are not available.
+
+Returns the standard envelope with the created id **nested under `data`** — read **`data.document_id`**. *(Used by the publish flow.)*
+
+### POST `/automations/{process_id}/media`  *(not needed for documents)*
+A separate byte-upload route taking the same `EncodedFileValidator` shape. Documents do **not** need it — `/documents` accepts `file` directly.
+
+### GET `/hierarchy`
+The tenant's category tree (verified live): `data.levels` (level names) + `data.categories[]`, each with `category_id`, `category_name`, `category_is_active`, and nested `subcategories`. **This is how to resolve a valid `OVERVIEW_CATEGORY` id** — it works even on a tenant with zero processes. Only pick nodes with **`category_is_active: 1`** — `0` means archived and the write will be rejected or hidden. *(Used by the publish flow.)*
+
+### GET `/users?limit=<n>`
+The Automation Hub users on the tenant (verified live): paged envelope with the list under **`data.users[]`**; each entry carries **`user_email`**, `user_first_name`/`user_last_name`, and `user_is_active`. **This is how to resolve a valid owner/submitter email** — both must be provisioned AH users (prefer `user_is_active: 1`), and this endpoint is the ground truth. *(Used by the publish flow.)*
+
+### GET `/appinventory?limit=<n>`
+The tenant's application inventory (paged; entries carry the application id, name, version, language). **This is the valid-answer set for tenant-required application questions** ("Applications used", "Thin applications used") in the publish flow. *(Used by the publish flow when the tenant requires application questions.)*
+
+### GET `/automations?search=<text>&limit=<n>&offset=<n>`
+Search/list processes. Returns a paged list (results under a resource key, e.g. `processes`, or a bare array). Use to resolve a name → `process_id`. *(Used by the get flow.)*
+
+### GET `/automations/{id}`
+Fetch one process by numeric id (or slug). Returns the full process record (can be ~300 fields; project to the ones you need for display). *(Used by the get flow.)*
+
+### GET `/automations/{process_id}/documents`
+List a process's documents (key `documents`). Each entry carries `document_id`, `document_title`, `document_type_id`, and **either** a `file_id` (file-backed — downloadable) **or** an `embed_link` (link-backed — nothing to download; show the URL). *(Used by both flows.)*
+
+### GET `/download/file/{file_id}`
+Download a file-backed document's **bytes**. `{file_id}` is the `file_id` from the documents list — **not** the `document_id`. The response body is the raw file — save it with `curl -o <path>`; there is no JSON envelope. Link-backed documents (`file_id` absent) cannot be downloaded — present their `embed_link` instead. *(Used by the get flow.)*
+
+### GET `/automations/{id}/components`  *(optional)*
+Linked components for the process.
+
+## Errors
+
+| Status | Meaning |
+|--------|---------|
+| 400 | Validation — missing required field, invalid enum, empty `user_inputs`, missing `OVERVIEW_NAME` |
+| 401 | Unauthorized — token missing/expired, or `x-ah-openapi-auth` was wrongly sent |
+| 403 | Forbidden — the user lacks the AH permission (authorization = the user's real AH role) |
+| 404 | Wrong URL, or AH not enabled on the tenant |
+| 409 | Duplicate process name |

package/skills/uipath-automationhub/references/get-process.md

@@ -0,0 +1,69 @@
+# Get a Process from Automation Hub
+
+Fetches one process (by id or search) and its documents from Automation Hub, authenticating with the **user's cloud token** — no admin OpenAPI token required. Read-only: this flow never writes.
+
+> Auth, base/gateway URL, headers (and the header to **never** send), and the read endpoints are defined in [`api-endpoints.md`](api-endpoints.md). Resolve `$ACCESS_TOKEN` / `$BASE_URL` / `$ORG` / `$TENANT` via the shared **Authentication** section in [`../SKILL.md`](../SKILL.md) before starting.
+
+## Step 1: Resolve the process
+
+- If the caller gives a **process id**, use it directly.
+- Otherwise search by name:
+  ```bash
+  curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
+    "$BASE_URL/$ORG/$TENANT/automationhub_/api/v1/openapi/automations?search=$QUERY&limit=20"
+  ```
+  If one clear match → use its `process_id`. If several → show a short list (name + id + owner) and ask the user to pick. If none → tell the user and stop.
+
+## Step 2: Fetch the process
+
+```bash
+curl -s -w "\n%{http_code}" -H "Authorization: Bearer $ACCESS_TOKEN" \
+  "$BASE_URL/$ORG/$TENANT/automationhub_/api/v1/openapi/automations/$PROCESS_ID"
+```
+- **200** → keep the record; project to the useful fields for display (name, status/phase, category, owner, description). The raw record is large — don't dump it all unless asked.
+- **401** → re-authenticate. **403** → the user can't view this process. **404** → no such process.
+
+## Step 3: Fetch the documents
+
+```bash
+curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
+  "$BASE_URL/$ORG/$TENANT/automationhub_/api/v1/openapi/automations/$PROCESS_ID/documents"
+```
+
+The list is under **`data.documents[]`** (standard envelope). Each entry carries `document_id`, `document_title`, `document_type_id`, and **either** a `file_id` (file-backed) **or** an `embed_link` (link-backed). *(Optional: `/automations/$PROCESS_ID/components` for linked components.)*
+
+## Step 3b: Download a document (when the caller wants the bytes)
+
+Only **file-backed** documents can be downloaded, and the endpoint takes the **`file_id`** — not the `document_id`:
+
+```bash
+curl -s -w "%{http_code}" -H "Authorization: Bearer $ACCESS_TOKEN" \
+  -o "<destination-path>" \
+  "$BASE_URL/$ORG/$TENANT/automationhub_/api/v1/openapi/download/file/$FILE_ID"
+```
+
+- The response body is the **raw file** (no JSON envelope) — always save with `-o`; pick the filename from `document_title` or ask the user.
+- **200** → confirm the file exists and is non-empty before reporting success.
+- A **link-backed** document (`file_id` absent) has nothing to download — present its `embed_link` to the user instead. Never invent a download URL for it.
+- Do not guess other paths (`/documents/{id}/download`, `/files/{id}`, …) — `/download/file/{file_id}` is the only download route.
+
+## Step 4: Present
+
+```
+Process: <name>  (process_id: <id>)
+  Status:   <phase/status>
+  Category: <category>
+  Owner:    <owner>
+  View:     {baseUrl}/{org}/{tenant}/automationhub_/automation-profile/{process_slug}/documentation
+Documents:
+  - PDD  (document_id 12, file_id 42 — downloadable)
+  - SDD  (document_id 13, embed_link — link only)
+```
+
+Offer to return the raw JSON, download the documents, or fetch components if relevant.
+
+## Notes
+
+- **Cloud token only** — never send `x-ah-openapi-auth` / `x-ah-openapi-app-key`. You see exactly what the user's AH permissions allow.
+- Read-only: this flow never writes. To create/attach, use the [`publish-process.md`](publish-process.md) flow.
+- **Open dependency:** in a hosted runtime (Process Scribe/Delegate) the cloud token is expected via the environment (see the shared Authentication section). Confirm the runtime provides it before relying on it in production.

package/skills/uipath-automationhub/references/publish-process.md

@@ -0,0 +1,171 @@
+# Publish a Process to Automation Hub
+
+Creates one process in Automation Hub from a schema-driven payload and attaches its documents (PDD/SDD). Authenticates with the **user's cloud token** — the user does **not** need an admin-generated OpenAPI token.
+
+> Auth, base/gateway URL, headers (and the header to **never** send), and every endpoint below are defined in [`api-endpoints.md`](api-endpoints.md). Resolve `$ACCESS_TOKEN` / `$BASE_URL` / `$ORG` / `$TENANT` via the shared **Authentication** section in [`../SKILL.md`](../SKILL.md) before starting.
+
+## Step 1: Verify connectivity (and fetch the idea flows)
+
+Verify the resolved token with a cheap call — this also fetches the idea flows you need next:
+
+```bash
+curl -s -w "\n%{http_code}" \
+  -H "Authorization: Bearer $ACCESS_TOKEN" \
+  "$BASE_URL/$ORG/$TENANT/automationhub_/api/v1/openapi/idea-flows"
+```
+
+- **200** → save the `data` array (reused in Step 2) and tell the user "Connected to Automation Hub."
+- **401** → token missing/expired: if it came from `~/.uipath/.auth`, ask the user to run `uip login` again; re-resolve and retry. **Never** add `x-ah-openapi-auth` to "fix" a 401 — that routes to the admin-token path and guarantees failure.
+- **403** → the user is authenticated but lacks AH access on this tenant.
+- **404 / network** → wrong URL or AH not enabled; confirm the org/tenant.
+
+Do not proceed until you have a 200.
+
+## Step 2: Pick the idea flow
+
+From the saved `/idea-flows` `data` array:
+1. Default to the entry whose `Idea flow name` contains "Business Process" (case-insensitive) and take its `Idea flow ID`.
+2. If the caller specified a different flow, use that. If neither is found, list the available names + IDs and ask the user which to use. If none exist, tell the user Business Process flows may not be enabled and stop.
+
+Store `idea_flow_id`.
+
+## Step 3: Fetch the schema
+
+```bash
+curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
+  "$BASE_URL/$ORG/$TENANT/automationhub_/api/v1/openapi/idea-schema?idea_flow_id=$IDEA_FLOW_ID"
+```
+
+Parse `data.properties.schema.properties` for the field catalog (Assessment Type > Section > Question; note types, required flags, enum `answer_option` codes/labels) and keep `data.user_inputs` as the payload template. The process-name question (key contains `OVERVIEW_NAME`) is **required**.
+
+> ⚠️ **Do NOT POST `data.user_inputs` verbatim.** The template ships **example/placeholder values that the API rejects** — e.g. `OVERVIEW_CATEGORY: 1` (→ `Invalid Category Id`), a placeholder `PROCESS_DOCUMENTS` answer-option that triggers a backend `co_question_answer_option_value` crash, and `First.last@example.com` owner/submitter emails. Treat the template as **shape only** and replace every value with a real one (below).
+
+## Step 4: Collect the inputs, then assemble the payload
+
+**Collect every required input BEFORE the first POST** — do not discover gaps one 400 at a time.
+
+First, **enumerate the tenant's actual required set from the live schema** (Step 3): walk `data.properties.schema.properties` and collect every question whose `required` flag is set — tenant admins can mark **additional** questions required (commonly "Applications used" and "Thin applications used"), so the baseline table below is the *minimum*, never the whole list. Add the two questions the backend enforces without flagging (owner + submitter). Then resolve a value for **each** required question: from the caller's supplied data (e.g. a Process Scribe hand-off object), from the discovery recipes below, or via `AskUserQuestion` — never by inventing one.
+
+The six baseline inputs:
+
+| Input | How to resolve when not supplied |
+|---|---|
+| Process **name** | Ask the user. Non-empty; a duplicate name 409s. |
+| **Description** | Ask the user, or derive from the supplied material and confirm. |
+| **Category id** | `GET /hierarchy` → pick from `data.categories[]` (`category_id`, `category_name`, nested `subcategories`) — **only nodes with `category_is_active: 1`** (0 = archived). One clear fit → propose it; several plausible → `AskUserQuestion` with the names. **Never send the template's `1`.** (Works on an empty tenant — do not depend on an existing process.) |
+| **Documentation** answer code | The `PROCESS_DOCUMENTS` question's own `enum` in the schema — match by **label** (e.g. "Standard Operating Procedure") and send that `answer_option` code. Never reuse the template's placeholder code. |
+| **Owner email** | `GET /users` → the list is under `data.users[]`, the field is **`user_email`** (prefer `user_is_active: 1`); a non-listed address 400s (`Cannot identify owner by email`). Default to the signed-in user — confirm which listed email is theirs. |
+| **Submitter email** | Same recipe as owner; usually the same person. |
+
+**Tenant-required application questions** ("Applications used", "Thin applications used", and similar): the valid answers are the tenant's application inventory — `GET /appinventory` (paged; entries carry the app id, name, version, language). Match what the caller's material names, but if the documents leave the systems unconfirmed, `AskUserQuestion` with the inventory entries — **never record an application the material does not support**. Follow that question's own schema shape for how the selected entries are encoded in `user_inputs`.
+
+Then build `user_inputs` using the template's **structure** but the **collected values**:
+- Place each value in its `AssessmentType > section > question` slot.
+- Follow the template's wrapping per field: most are `{ "value": <v> }`; owner/submitter questions take a **direct string** (no `value` wrapper).
+- Convert enum labels to their `answer_option` codes taken from that field's own `enum` in the schema — **never** reuse the template's placeholder code. Send integers as numbers.
+
+**Required fields for `idea_flow_id` = Business Process** (verified live — the backend enforces owner + submitter even though the schema's `required` flags do **not** list them):
+
+| Question (key) | Section | Shape | Value |
+|---|---|---|---|
+| `OVR-OVERVIEW_NAME` | `ah-section-ovr-0-0` | `{"value": "<name>"}` | process name, non-empty |
+| `OVR-OVERVIEW_DESCRIPTION` | `ah-section-ovr-0-0` | `{"value": "<desc>"}` | description |
+| `OVR-OVERVIEW_CATEGORY` | `ah-section-ovr-0-0` | `{"value": <int>}` | **valid** category id |
+| `OVR-PROCESS_DOCUMENTS` | `ah-section-ovr-0-0` | `{"value": ["<answer_option code>"]}` | code from the field's `enum` |
+| `OVR-PROCESS_OWNER` | `ah-section-ovr-0-0` | `"<email>"` (direct string) | real AH user |
+| `OVR-OVERVIEW_PROCESS_SUBMITTER` | `ah-section-ovr-0-1` | `"<email>"` (direct string) | real AH user |
+
+Include only sections that have at least one populated field. Show the user a concise preview (name + key fields, and "show raw JSON" on request) and get a confirm before writing.
+
+## Step 5: Create the process
+
+```bash
+curl -s -w "\n%{http_code}" -X POST \
+  -H "Authorization: Bearer $ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "$PAYLOAD" \
+  "$BASE_URL/$ORG/$TENANT/automationhub_/api/v1/openapi/idea-from-schema"
+```
+where `$PAYLOAD` is `{ "idea_flow_id": <id>, "user_inputs": { … } }`.
+
+- **201** → the envelope is `{ "message": "Resource Created", "statusCode": 201, "data": { … } }` — read **`data.process_id`** (it is nested, NOT top-level). Keep it for Step 6. A 201 means the process WAS created: if a field read comes back undefined, re-read the response — **never re-POST** (that creates a duplicate and 409s).
+- **400** → fix and retry. The message shapes seen live:
+  - `errorDetails: { "<question>": ["An answer selection is required…"] }` → that required field is missing/empty; add it.
+  - `errorDetails: {}` with `"Please fill in all the required information"` → a required field the API **won't name** is missing. Check in order: (1) owner (`OVR-PROCESS_OWNER`) / submitter (`OVR-OVERVIEW_PROCESS_SUBMITTER`) — enforced but never flagged; (2) **diff your payload against every `required`-flagged question in the live schema** — tenant admins add required questions (e.g. "Applications used" / "Thin applications used"), and a payload missing any of them gets this same generic 400. Fill the gaps (Step 4 recipes), then retry once.
+  - `"Invalid Category Id."` → `OVERVIEW_CATEGORY` isn't a real category on this tenant (see Step 4).
+  - `Cannot set properties of undefined (setting 'co_question_answer_option_value')` → an enum field carries an invalid `answer_option` code (you left a template placeholder in). Use a code from that field's `enum`.
+- **401** → re-authenticate. **409** → duplicate name; ask the user for a new name or stop.
+
+## Step 6: Attach documents (PDD/SDD)
+
+Attach each document the caller supplies — **default to all of them**; never silently skip a supplied file. The one exception: if two supplied files appear to be the *same document in different formats*, ask which to attach — as part of the single up-front clarifying round (Step 4), not a separate round. **Upload the bytes** — the endpoint takes a base64 `file` object directly, so nothing needs hosting first. Fall back to `embed_link` only when the caller has a URL instead of bytes.
+
+```bash
+curl -s -w "\n%{http_code}" -X POST \
+  -H "Authorization: Bearer $ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "$DOC_PAYLOAD" \
+  "$BASE_URL/$ORG/$TENANT/automationhub_/api/v1/openapi/automations/$PROCESS_ID/documents"
+```
+
+Build `$DOC_PAYLOAD` per `ProcessDocumentValidator`:
+
+```json
+{
+  "document_title": "PDD - <name>",
+  "document_description": "<desc>",
+  "document_type_id": <int>,
+  "file": {
+    "file_name": "<name>.docx",
+    "mimetype": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "file_content": "<base64 of the file bytes>",
+    "file_encoding": "base64"
+  }
+}
+```
+
+- `document_title`, `document_description`, `document_type_id` are all required (the field is `document_title`, **not** `document_name`).
+- **`document_type_id` comes from the fixed platform table in [`api-endpoints.md`](api-endpoints.md)** — PDD → `1`, SDD → `2`, otherwise `9` (MISC). Never guess other ids.
+- Supply **exactly one** of `file` or `embed_link` — an XOR enforced in the handler, not the JSON schema. Both, or neither, 400s with `"One and only one of embed_link or file need to be specified."`
+- **`file` (default).** Base64-encode the file and send `file_name`, `mimetype`, `file_content`, `file_encoding`. `file_encoding` must be the literal `base64` — any other value fails with `"Invalid file."`, as does an empty `file_name`, `mimetype`, or `file_content`. Body limit is 300mb.
+- Common mimetypes: `.docx` → `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `.md` → `text/markdown`, `.pdf` → `application/pdf`.
+- Generate the base64 without loading the file into the conversation:
+
+```bash
+base64 -i "<FILE_PATH>" | tr -d '\n'   # macOS/Linux; use `base64 -w0 "<FILE_PATH>"` on GNU coreutils
+```
+
+- **`embed_link` (alternative).** Use only when the caller has a URL and no bytes: replace the `file` object with `"embed_link": "https://…"`. Never invent a URL.
+
+Record each returned id — it is nested: read **`data.document_id`** from the response envelope. On 400, surface the validation message and continue with the remaining documents.
+
+## Step 7: Verify, then report
+
+**Verify before claiming success** — read the process back and confirm the documents landed:
+
+```bash
+curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
+  "$BASE_URL/$ORG/$TENANT/automationhub_/api/v1/openapi/automations/$PROCESS_ID/documents"
+```
+
+Check every attached `document_id` appears (file-backed entries also carry a `file_id`). If one is missing, report it as failed — never report a document as attached without seeing it in this list.
+
+Then summarize. The report **MUST end with both View deep links** — they are not optional; a publish report without them is incomplete. The URL segment is `process_slug`: take it from the 201's `data.process_slug`, and **if you no longer have it, fetch it** — `GET /automations/{process_id}` returns the record with `process_slug`. URL-encode it. Emit the links only after the verification read-back above succeeded:
+
+```
+Published to Automation Hub:
+  Process: <name>  (process_id: <id>)
+  Documents: PDD ✓ (doc 12, file 42), SDD ✓ (doc 13, file 43)
+  View process:   {baseUrl}/{org}/{tenant}/automationhub_/automation-profile/{process_slug}
+  View documents: {baseUrl}/{org}/{tenant}/automationhub_/automation-profile/{process_slug}/documentation
+```
+
+Always build the links from the **same org/tenant** the process was created on — never another tenant's segments.
+
+## Notes
+
+- **Cloud token only** — never send `x-ah-openapi-auth` / `x-ah-openapi-app-key`. Authorization is the user's real AH permissions.
+- **Always** `POST /idea-from-schema` (not `/automations`) and **always** include `idea_flow_id`.
+- The schema is fetched live, so the flow adapts automatically if fields change on the tenant.
+- Idempotency: AH is the system of record for the *approved* process — publish once after approval. A duplicate name returns 409; decide up front whether to update-in-place (out of scope here) or treat as an error.
+- To read a process back, use the [`get-process.md`](get-process.md) flow.

package/skills/uipath-coded-apps/SKILL.md

@@ -14,7 +14,7 @@ Build, debug, and deploy UiPath Coded Web Applications and Coded Action Apps usi
 - User wants to **build, debug, or deploy** a UiPath Coded Web App or Coded Action App
 - User asks about `uip codedapp` commands, `.uipath/` directory, `app.config.json`, or `action-schema.json`
 - User wants to **scaffold** a new React/Vue frontend for UiPath Cloud or an Action Center form
-- User wants to embed the **Document Understanding Validation Station** widget for human review of DU extraction results
+- User asks for app UI that a **prebuilt UiPath widget** covers: review/correct Document Understanding extraction results (Validation Station), chat with a conversational agent, browse/edit a Data Fabric entity in a grid, upload files to a storage bucket, display a PDF, or sign in with an external IdP (Google/SAML)
 - User wants to **push/pull source** between local and Studio Web
 - User wants to use the `@uipath/uipath-typescript` SDK from a coded app
 - User wants to run the **full pipeline** (build → pack → publish → deploy)
@@ -28,7 +28,12 @@ Build, debug, and deploy UiPath Coded Web Applications and Coded Action Apps usi
 | **Coded Web App** | React/Vue/other frontend hosted on UiPath CDN | User-facing app accessed via a URL |
 | **Coded Action App** | React form wired to UiPath Action Center | Rendered inside human task reviews in Maestro/Agent workflows |
 
-> **Coded apps are not registered in `.uipx` solutions.** They have no `project.uiproj` / `project.json`, so `uip solution projects add` does not apply. A coded app can live alongside a solution directory but deploys independently via `uip codedapp publish` (and `uip codedapp deploy`), not via `uip solution pack` / `publish` / `deploy`.
+> **Two lifecycles, two scaffolding entry points.**
+>
+> - **Standalone coded app**: scaffold with `npx create-vite@latest` (see [create-web-app.md](references/create-web-app.md) / [create-action-app.md](references/create-action-app.md)). No `project.uiproj` / `webAppManifest.json` — those are solution-membership artefacts and standalone apps don't need them. Deploy via `uip codedapp pack` → `uip codedapp publish` (`-t Action` for action apps) → `uip codedapp deploy`. This is the classic single-app lifecycle covered by the rest of this skill.
+> - **In-solution coded app**: run `uip codedapp init` from **inside a `.uipx` solution**. Init writes `project.uiproj` (`ProjectType: "AppV2"`) + `webAppManifest.json`, nests runtime + build artefacts under `source/dist/`, auto-registers the project as `Type: "AppV2"` in the `.uipx`, and emits `resources/solution_folder/app/{Coded,CodedAction}/`. From then on the app is part of the solution — `uip solution pack` bundles its `.nupkg` and `uip solution deploy run` provisions it in the deployment folder. **Do not** run `uip codedapp pack` / `publish` / `deploy` on a coded app that's already registered in `.uipx` — that bypasses the solution's deploy config (external client ID, routing name, action schema) and double-registers the package. `uip solution projects add` / `uip solution projects import` register existing AppV2 folders too, reading `webAppManifest.config.isActionApp` to pick the `Coded` / `CodedAction` subType. For the solution-side lifecycle see [/uipath:uipath-solution](/uipath:uipath-solution).
+>
+> **`uip codedapp init` is for solutions only.** It is not the scaffolding entry point for a standalone coded app — use `create-vite` for that.
 
 ## Critical Rules
 
@@ -40,9 +45,9 @@ Build, debug, and deploy UiPath Coded Web Applications and Coded Action Apps usi
 6. **Action apps require `-t Action` on publish.** Run `uip codedapp publish -t Action` (not the default `Web` type).
 7. **Never handle access tokens manually.** Do not pass, print, parse, source, or set cached access tokens. Use `uip login` and supported `uip codedapp` commands; the CLI manages authentication.
 8. **Base URL must use the API subdomain.** `https://api.uipath.com` not `https://cloud.uipath.com`. See the table below.
-9. **`vite.config.ts` must always set `base: './'`.** The platform handles URL routing — apps must use relative asset paths. Do not use a routing name or a sub-path here.
+9. **`vite.config.ts` must always set `base: './'`.** The platform handles URL routing — apps must use relative asset paths. Do not use a routing name or a sub-path here. **Import static assets through the bundler** (`import logo from './assets/logo.png'`) so Vite fingerprints and base-rewrites them. Do NOT place them in `public/` or reference them by a hardcoded `/`-rooted path — those bypass base rewriting and 404 after deploy under the non-root mount.
 10. **Use `getAppBase()` from `@uipath/uipath-typescript` for any absolute URL constructed at runtime** — router basename, image `src`, `fetch` paths. Deployed apps mount at a non-root prefix; `/`-rooted paths work locally but 404 after deploy. Vite's `base: './'` only fixes import-time references.
-11. **`uip codedapp deploy` must run non-interactively.** Pass the folder key as `--folder-key <GUID>` (or as `UIPATH_FOLDER_KEY=<GUID>` env-var prefix — either works). The interactive folder picker fails in non-TTY contexts (CI, agent shells). If the user provides a folder **name**, resolve it to a key with `uip or folders list --output json` and match on the `Name` field (output rows are `{ Key, Name, Path, Description, Type, ParentKey }`). A **personal workspace** is the row with `Type == "Personal"` — resolve its `Key` the same way. To deploy into a **new** folder, create it first with `uip or folders create "<NAME>" --output json` and read `Data.Key`. The `uip or ...` commands require the Orchestrator tool — install once via `uip tools install @uipath/orchestrator-tool` (check first with `uip tools list`).
+11. **`uip codedapp deploy` must run non-interactively.** Pass the folder key as `--folder-key <GUID>` (or as `UIPATH_FOLDER_KEY=<GUID>` env-var prefix — either works). The interactive folder picker fails in non-TTY contexts (CI, agent shells). If the user provides a folder **name**, resolve it with the server-side filter `uip or folders list --all --name "<name>" --output json` and pick the row whose `Name` **exactly** equals the target, then read its `Key` (the plain list is paginated 50/page and `--name` is a *contains* match requiring `--all`, so never just take the first row). A **personal workspace** is not in `--all` — resolve it from the default `uip or folders list --output json` where `Type == "Personal"`. To deploy into a **new** folder, create it first with `uip or folders create "<NAME>" --output json` and read `Data.Key`. The `uip or ...` commands require the Orchestrator tool — install once via `uip tools install @uipath/orchestrator-tool` (check first with `uip tools list`).
 12. **Guard against text overflow in every UI.** See [patterns.md](references/patterns.md) "Preventing Text Overflow".
 13. **Inspect the DF schema before writing analytics, filters, or seeds.** Run `uip df entities get <ENTITY_ID> --output json` to inspect fields and types. At runtime, use `entities.getById(<id>)` from the app's authenticated session. DF doesn't behave like a typical RDBMS; see [sdk/data-fabric.md](references/sdk/data-fabric.md) "Anti-shapes & gotchas".
 14. **Every list call returns ONE page — even with no options. There is no "give me everything" path.** Applies to `getAll`, `getAllRecords`, `queryRecordsById`, `getFileMetaData`, etc. `getAll()` with no options does NOT return all rows; the SDK sends no `pageSize` and the **server** applies its own cap, wrapped in a misleadingly-named `NonPaginatedResponse`. To list every row from a source that may exceed the cap, you MUST loop the cursor: `while (page.hasNextPage) { page = await getAll({ cursor: page.nextCursor }) }` and accumulate `items`. Reading `result.items.length` after a single call is almost always a bug. See [sdk/pagination.md](references/sdk/pagination.md).
@@ -80,6 +85,11 @@ Build, debug, and deploy UiPath Coded Web Applications and Coded Action Apps usi
 | **Package and deploy** | [references/pack-publish-deploy.md](references/pack-publish-deploy.md) |
 | **Full CLI command reference** | [references/commands-reference.md](references/commands-reference.md) |
 | **Embed the DU Validation Station widget** | [references/widgets/validation-station.md](references/widgets/validation-station.md) |
+| **Embed the Conversational Agent chat widget** | [references/widgets/conversational-agent-chat.md](references/widgets/conversational-agent-chat.md) |
+| **Embed the Data Fabric DataTable widget** | [references/widgets/datatable.md](references/widgets/datatable.md) |
+| **Embed the multi-file bucket upload widget** | [references/widgets/multi-file-upload.md](references/widgets/multi-file-upload.md) |
+| **Embed the PDF viewer widget** | [references/widgets/pdf-viewer.md](references/widgets/pdf-viewer.md) |
+| **Add external IdP sign-in buttons (Google/SAML)** | [references/widgets/external-auth.md](references/widgets/external-auth.md) |
 | **OAuth scopes for SDK services** | [references/oauth-scopes.md](references/oauth-scopes.md) |
 | **SDK: Import paths & subpath exports** | [references/sdk/imports.md](references/sdk/imports.md) |
 | **SDK: Assets, Queues, Buckets, Processes, Jobs, Attachments** | [references/sdk/orchestrator.md](references/sdk/orchestrator.md) |
@@ -123,19 +133,22 @@ uip login status --output json         # check if logged in
 uip login                              # interactive OAuth (opens browser)
 uip login --authority https://alpha.uipath.com   # non-production environments
 
-# Client-credentials (headless/CI) — MUST include Apps.Read Apps.Write or publish's
-# "Registering coded app" step fails with 401 even though package upload succeeds.
-# OR.Default alone is NOT sufficient — it covers Orchestrator but not the Apps service.
+# Client-credentials (headless/CI) — scope MUST name one Orchestrator scope AND
+# the two Apps-service scopes. Neither set covers the other:
+#   OR.Default            → Orchestrator
+#   Apps.Read Apps.Write  → Apps-service registration in `uip codedapp publish`
+# Do NOT substitute granular Orchestrator scopes (OR.Folders/OR.Execution/
+# OR.Administration) for OR.Default.
 uip login \
   --client-id <id> \
   --client-secret <secret> \
   --organization <org> \
   --tenant <tenant> \
-  --scope "OR.Folders OR.Execution OR.Administration Apps.Read Apps.Write" \
+  --scope "OR.Default Apps.Read Apps.Write" \
   --authority https://alpha.uipath.com   # omit --authority for production
 ```
 
-> **The `uip login` session scope is separate from the app's runtime OAuth scopes.** The scopes in `uipath.json` are what the *deployed app* requests at runtime (see [oauth-scopes.md](references/oauth-scopes.md)). The `--scope` on `uip login` above is what the *CLI session* needs to call the Apps registration API during `uip codedapp publish`. `uip codedapp publish` does two things: uploads the package (needs Orchestrator scopes) **and** registers the coded app (needs `Apps.Read Apps.Write`). Omitting the Apps scopes lets the upload succeed but silently 401s the registration.
+> **The `uip login` session scope is separate from the app's runtime OAuth scopes.** The scopes in `uipath.json` are what the *deployed app* requests at runtime (see [oauth-scopes.md](references/oauth-scopes.md)). The `--scope` on `uip login` above is what the *CLI session* needs to call the Apps registration API during `uip codedapp publish`. `uip codedapp publish` does two things: uploads the package (needs `OR.Default`) **and** registers the coded app (needs `Apps.Read Apps.Write`). For what each failure looks like, see [debug.md](references/debug.md#publish--deploy-fails-under-a-client-credentials-login).
 
 ## SDK Config (web app)
 
@@ -161,7 +174,7 @@ To change any of these values, edit `uipath.json`.
 
 **Do NOT pause between steps to ask "should I continue?" — execute the full pipeline. Only stop if you need auth credentials or an app name.**
 
-1. **Auth** — `uip login status --output json`. If not logged in, ask the user for their environment and run `uip login`. If using **client credentials** (headless/CI), always include `Apps.Read Apps.Write` in `--scope` — required by the Apps service registration inside `uip codedapp publish`. `OR.Default` alone covers Orchestrator (package upload) but not Apps registration; omitting them causes a silent 401 on the second half of publish.
+1. **Auth** — `uip login status --output json`. If not logged in, ask the user for their environment and run `uip login`. With **client credentials** (headless/CI), use `--scope "OR.Default Apps.Read Apps.Write"` — all three names are required: `OR.Default` for Orchestrator, `Apps.Read` and `Apps.Write` for the Apps-service registration in `uip codedapp publish`. The External Application itself needs only `Apps.Read` and `Apps.Write`; `OR.Default` is auto-granted and not portal-selectable, so name it in `--scope`. If publish or deploy then fails, see [debug.md](references/debug.md#publish--deploy-fails-under-a-client-credentials-login).
 2. **Build** — `npm run build`. Verify `ls dist/`.
 3. **Pack** — `uip codedapp pack dist -n <name> --version <version>`. Produces `.uipath/<name>.<version>.nupkg`. Bump version if previously published.
 4. **Publish** — `uip codedapp publish` (add `-t Action` for action apps). Verify `cat .uipath/app.config.json`.
@@ -189,7 +202,7 @@ See [references/debug.md](references/debug.md) for detailed diagnosis steps.
 |-------|-------|-----|
 | `Not authenticated` | No valid session | Run `uip login` |
 | `dist/ not found` | App not built | Run `npm run build` |
-| `Version already exists` | Same version re-published | Bump version in `pack` |
+| `Published app with package name '<name>' and version '<version>' already exists` | Same name+version already published (registration rejects duplicates) | Bump `--version` and re-publish |
 | `Folder key required` / deploy hangs on prompt | Missing folder for CLI deploy | Resolve folder name → key via `uip or folders list --output json` (match on `Name`, read `Key`), then run `uip codedapp deploy --folder-key <GUID> ...`. See [pack-publish-deploy.md](references/pack-publish-deploy.md#folder-key). |
 | `No packages found` | No `.nupkg` in `.uipath/` | Run `pack` first |
 | Login fails / redirect error | OAuth misconfiguration | See [debug.md](references/debug.md) |