@uipath/skills 1.198.0-preview.21 → 1.199.0-preview.106

package/skills/uipath-troubleshoot/references/products/api-workflows/playbooks/expression-reference-error.md

@@ -0,0 +1,32 @@
+---
+confidence: high
+---
+
+# `<name> is not defined` at Runtime (Expression Reference Error)
+
+## Context
+
+What this looks like:
+- Run fails with `ReferenceError: <name> is not defined` (e.g. `currentItem is not defined`, `PASS is not defined`)
+- `uip api-workflow validate` reports `Status: Valid` — static validation does NOT resolve JS identifier bindings, so this class of fault only surfaces at run time
+
+What can cause it:
+- **Loop iterator without `$` prefix.** A ForEach declares `for.each: "currentItem"`, but the body references it as `${currentItem}` instead of `${$currentItem}`. The executor binds the iterator as the global `$currentItem` — the `$` is part of the identifier — so the unprefixed name has no binding. Same for `for.at` (`$currentItemIndex`) and `catch.as` (`$error`).
+- **Reading the iterator from the wrong place.** `$context.variables.<iteratorName>` — the executor does not put the iterator there.
+- **Unwrapped string literal after a Studio Web save.** An `Assign.set` / `Response` / If `when` literal written as `"PASS"` is normalized by the designer to `"${PASS}"`, turning the literal into a bare identifier reference that has no binding. (Author-side fix belongs to `uipath-api-workflow`; here it explains the runtime error.)
+
+What to look for:
+- The exact undefined name in the error vs. the `for.each` / `for.at` / `catch.as` declarations
+- Whether the failing expression uses a plain word where a `$`-prefixed identifier or a `${'literal'}` was intended
+
+## Investigation
+
+1. Reproduce: `uip api-workflow run <Workflow.json> --no-auth --input-arguments '<inputs>' --output json` — note the undefined `<name>`.
+2. Grep the workflow for `<name>` and compare against the enclosing loop's `for.each`/`for.at` (or catch's `as`). If the declaration is `"currentItem"` and the usage is `${currentItem}`, the `$` prefix is missing.
+3. If `<name>` is a value the author intended as a literal string (e.g. `PASS`), it is an unwrapped-literal fault — the reference should be `${'PASS'}`.
+
+## Resolution
+
+- **If a loop iterator / index / catch var:** prefix every reference with `$` — `${$currentItem}`, `${$currentItemIndex}`, `${$error}`. The `$` is a literal character in the identifier, not expression syntax. Re-run to confirm.
+- **If an unwrapped literal:** wrap it as a JS string inside the expression — `${'PASS'}`. Numbers/booleans and real references (`${$context.variables.X}`) need no change.
+- Always re-run AND re-validate after the fix. For the full authoring rules, the `uipath-api-workflow` skill owns the designer-roundtrip catalog.

package/skills/uipath-troubleshoot/references/products/api-workflows/playbooks/output-undefined.md

@@ -0,0 +1,39 @@
+---
+confidence: medium
+---
+
+# `$context.outputs.<Activity>` Is Undefined Downstream
+
+## Context
+
+Each activity's output is read downstream as `$context.outputs.<Activity>`, where `<Activity>` is the activity's output name (defaults to its id, e.g. `HTTP_1`, `For_Each_1`).
+
+What this looks like — two symptom shapes, same fault family:
+- **Hard crash** — `Cannot read properties of undefined (reading '<Activity>')`: `$context.outputs` itself doesn't exist because no upstream activity has exported yet. The `(reading '<Activity>')` fragment names the key the reader expected.
+- **Silent `undefined`** — `$context.outputs` exists (some activity has exported) but the key doesn't match: If-conditions that read a prior activity's output always evaluate false, JS_Invoke scripts return empty, a Response field comes back empty — no hard error.
+
+What can cause it:
+- **Producing activity did not `export`.** Every non-Assign activity must propagate state with `{ ...$context, outputs: { ...$context?.outputs, "<Activity>": $output } }`. Without it, its output never lands in `$context.outputs` — and if no other activity has exported either, `$context.outputs` never comes into existence and the downstream read crashes instead of returning `undefined`.
+- **Connector (IntSvc-kind) output read at the root instead of `.content`.** A `UiPath.IntSvc` activity wraps the vendor payload under `.content` — the data is at `$context.outputs.<Activity>.content.<field>`, not `$context.outputs.<Activity>.<field>`. List-shaped ops put the array at `.content` (`.content[0].<field>`).
+- **Slot key vs. export-bucket key mismatch (connector activities only).** For connector activities the `do`-array slot key and the `$context.outputs.<Activity>` export-bucket key can differ (e.g. slot `GetNewestEmail_1` / bucket `getNewestEmail_1`). Reading the wrong one returns `undefined`.
+- **Wrong input accessor.** Reading a workflow input as `$input.<name>` instead of `$workflow.input.<name>` — `$input` is the *previous activity's* output for any non-first activity.
+
+What to look for:
+- Whether the referenced `<Activity>` actually has an `export` block, and whether it's a connector activity (check `call: "UiPath.IntSvc"`/`"UiPath.Http"`)
+- Whether the read goes through `.content` for connector outputs
+
+## Investigation
+
+1. Reproduce: `uip api-workflow run <Workflow.json> --no-auth --output json` and log the full output of the producing activity once to inspect its real shape.
+2. Confirm the producing activity has an `export.as` that spreads `...$context?.outputs` and writes its own key.
+3. For connector activities, two checks:
+   - **Read key:** the key in the downstream `$context.outputs.<Activity>` read must equal the key string written inside the producing activity's `export.as` (`outputs: { ..., "<Activity>": $output }`) — not the activity's `do`-array slot key, which can differ from it for connector activities.
+   - **Read path:** connector output is a wrapper — the read must go through `.content`: `$context.outputs.<Activity>.content.<field>`.
+4. For input reads, confirm the accessor is `$workflow.input.<name>`.
+
+## Resolution
+
+- **If missing export:** add the standard outputs export to the producing activity; re-run.
+- **If connector output:** read through `.content` — `$context.outputs.<Activity>.content.<field>` (or `.content[0].<field>` for arrays).
+- **If key mismatch:** regenerate the activity stub (`uip api-workflow registry stub --output json`) and use its `Data.ExportBucketKey` verbatim in `export.as` and in every downstream reference.
+- **If wrong accessor:** switch `$input.<name>` → `$workflow.input.<name>`, and confirm the input is declared in `input.schema` (or has a default) and was passed via `--input-arguments`.

package/skills/uipath-troubleshoot/references/products/api-workflows/playbooks/publish-deploy-failure.md

@@ -0,0 +1,38 @@
+---
+confidence: medium
+---
+
+# API Workflow Pack / Publish / Deploy Fails (or Doesn't Appear in Studio Web)
+
+## Context
+
+What this looks like:
+- `uip solution pack` / `publish` / `deploy` returns a failure, or
+- Everything succeeds but the published API project is invisible / not editable in Studio Web, and a direct import fails with `Failed to import new projects at the overwrite operations`
+
+What can cause it:
+- **Wrong project type string** — packager error `No CLI tool mapping found for project type 'X'`; API workflow projects must declare `Type: "Api"` (case-sensitive).
+- **Publishing the wrong artifact** — `"Invalid file type. Expected a .zip file"` when a `.nupkg` is passed instead of the wrapping `.zip` from `uip solution pack`.
+- **Auth / naming** — publish 401/403 (not logged in, wrong tenant, insufficient role) or 409 name+version conflict (a package with that name+version already exists).
+- **Stale generated files** — hand-committed or old-CLI `operate.json` / `package-descriptor.json` cause a descriptor mismatch; they are generated by pack and must not be committed.
+- **Missing `project.uiproj`** — the on-disk API workflow project is `project.uiproj` + `Workflow.json` + `entry-points.json` (`uip api-workflow init` scaffolds exactly this). If the `.uiproj` is missing, the package still deploys but Studio Web won't open it — Studio Web requires a `project.uiproj` to recognize a folder as a project. Studio Web always writes it, so this only happens when a project was hand-assembled instead of scaffolded with `uip api-workflow init`. **Fixing the shape is an authoring task — see the `uipath-api-workflow` skill.**
+
+What to look for:
+- The exact CLI error string and stage (pack vs publish vs deploy vs Studio Web open)
+- Whether the project folder has `project.uiproj` + `Workflow.json` (present for any `init`-scaffolded project)
+
+## Investigation
+
+1. Re-run the failing step with `--output json` and read the error: `uip solution pack <dir> <out> --output json` / `uip solution publish <zip> --output json`.
+2. Confirm auth for publish/deploy: `uip login status --output json`; verify `--tenant` matches the target.
+3. For the "invisible in Studio Web" case, check the project shape: does the folder contain `project.uiproj` (`ProjectType: "Api"`, `MainFile: "Workflow.json"`)?
+4. For descriptor mismatches, check whether `operate.json` / `package-descriptor.json` were committed by hand.
+
+## Resolution
+
+- **If wrong type:** set `Type: "Api"` exactly in the project/solution manifest; re-pack.
+- **If wrong artifact:** publish the `.zip` from `uip solution pack`, not the inner `.nupkg`.
+- **If 401/403:** `uip login`, confirm tenant + role. **If 409:** bump `--version` and re-pack/publish.
+- **If stale generated files:** delete `operate.json` + `package-descriptor.json` and re-pack (the packager regenerates them).
+- **If runtime-only shape:** re-scaffold with `uip api-workflow init` and move the workflow content in, or convert in place (add `project.uiproj` + `entry-points.json`, preserve the project `Id`/`Type`). The authoring fix belongs to the `uipath-api-workflow` skill.
+- **Cross-reference:** for solution lifecycle mechanics and deploy error codes, see the **Solutions** / **Orchestrator** surfaces.

package/skills/uipath-troubleshoot/references/products/api-workflows/playbooks/run-not-successful.md

@@ -0,0 +1,37 @@
+---
+confidence: medium
+---
+
+# API Workflow Run Returns a Non-Successful Status
+
+## Context
+
+What this looks like:
+- `uip api-workflow run` (local) or an Orchestrator API-process job (cloud) returns a failure — `Result: "Failure"` with a `Message`/`Instructions`, or job status `Faulted`
+- Usually an activity threw during execution and the workflow did not reach its `Response` — but a `Faulted` job with a clean-looking run can also be a deliberate `Response` outcome (see `markJobAsFailed` below)
+
+What can cause it:
+- **Expression fault** — invalid `${...}` syntax, a reference to an undefined variable in strict mode, or a loop iterator / catch variable referenced without its `$` prefix (see [expression-reference-error.md](./expression-reference-error.md))
+- **Undefined upstream output** — an activity reads `$context.outputs.<Activity>` but the producing activity did not `export` (see [output-undefined.md](./output-undefined.md))
+- **JS_Invoke fault** — missing `return`, a runtime error in the script body, or reading context through `arguments[0]` (the runtime passes nothing to the script)
+- **Loop fault** — DoWhile condition variable never updated (infinite loop), missing `#Body`, wrong export pattern
+- **Deliberate `markJobAsFailed`** — a `Response` activity with `markJobAsFailed: true` reports the Orchestrator job as `Faulted` even though every activity ran and the response body was returned. The run itself did not error — the workflow chose to fail the job (e.g. a business-rule branch). Check the reached `Response` before assuming an activity threw.
+- **Connection fault** (cloud only, IntSvc/Http-kind activities) — see [connection-auth-failure.md](./connection-auth-failure.md)
+
+What to look for:
+- Whether the fault reproduces locally with `run --no-auth` (structure/expression/logic) or only in cloud (auth/connection/vendor/scope)
+- The failing activity's key (`taskName`) in the error — isolates which activity threw
+
+## Investigation
+
+1. Reproduce and read the executor output: `uip api-workflow run <Workflow.json> --no-auth --output json`. Read `Instructions` first — it often names the fix.
+2. If it reproduces locally, triage in category order **Structure > Expression > Activity Config > Logic** (see [investigation_guide.md](../investigation_guide.md)). Run `uip api-workflow validate <Workflow.json> --output json` to catch structural/schema faults the run may mask.
+3. If it runs clean locally but the cloud job is `Faulted`, pull the job evidence: `uip or jobs get <job-key> --output json`, then `uip or jobs logs <job-key> --output json` and `uip traces spans get --job-key <job-key> --output json`. If the logs show the workflow reached its `Response` with no activity error, check the reached `Response` for `markJobAsFailed: true` — the job status is driven by that flag, not by a thrown activity. Compare a passing run vs. the faulting run to see which branch set it.
+4. Reduce to a minimal repro — isolate the failing activity and confirm each upstream activity `export`s its output.
+
+## Resolution
+
+- **If it reproduces locally:** fix the faulting activity per its category (expression / output / loop / JS_Invoke playbook), then re-run AND re-validate until both pass.
+- **If it only fails in cloud:** the shape is sound — pursue connection state, tenant/folder scope, or the real vendor response via the job logs/traces (route to [connection-auth-failure.md](./connection-auth-failure.md) for auth-shaped errors).
+- **If a `Response` set `markJobAsFailed: true`:** the run is behaving as authored — the job is failed on purpose. Confirm the business rule is correct; if the fail was unintended, fix the branch/condition that reaches that `Response` (author-side, `uipath-api-workflow`), don't chase a runtime error that isn't there.
+- **If the executor `Instructions` names a fix:** apply it directly; the executor's guidance is usually exact.

package/skills/uipath-troubleshoot/references/products/api-workflows/summary.md

@@ -0,0 +1,14 @@
+# API Workflows Playbooks
+
+Covers **why a UiPath API Workflow failed** — the JSON workflows run by `uip api-workflow run` and published to Orchestrator as API processes. Primary investigation surfaces: `uip api-workflow validate` / `run --no-auth` (local repro), `uip is connections ping` (connection health), and `uip or jobs get`/`logs` + `uip traces spans get --job-key` (cloud runs).
+
+**Overview:** [overview.md](./overview.md) — dependencies, evidence surfaces, fault families
+**Investigation guide:** [investigation_guide.md](./investigation_guide.md) — reproduce-locally-first, category order, connection verification, cloud-job correlation
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| Run returns non-Successful status | Medium | Executor returns `Result: "Failure"` or the Orchestrator job faults: an activity threw, OR a `Response` deliberately set `markJobAsFailed: true`. Triage by category (Structure > Expression > Activity Config > Logic); reproduce with `run --no-auth`. | [run-not-successful.md](./playbooks/run-not-successful.md) |
+| `<name> is not defined` at runtime | High | `ReferenceError` while `validate` still reports Valid. Loop iterator referenced without its `$` prefix (`currentItem` vs `$currentItem`), or an unwrapped string literal normalized to `${literal}` after a Studio Web save. | [expression-reference-error.md](./playbooks/expression-reference-error.md) |
+| `$context.outputs.<Activity>` undefined | Medium | Producing activity missing its `export`, connector output read at the root instead of `.content`, slot-key-vs-export-bucket-key mismatch, or `$input.<name>` used instead of `$workflow.input.<name>`. Silent `undefined` on key mismatch; crashes `Cannot read properties of undefined` when `$context.outputs` doesn't exist at all. | [output-undefined.md](./playbooks/output-undefined.md) |
+| Connector call 401/403 in cloud | Medium | Runs locally, fails once published. **401** (`Invalid Element token`): wrong activity kind (Http kind at a vendor connection), stale connection listing, or tenant/folder mismatch. **403 Forbidden**: broken/disabled or under-scoped connection — reads as `Result: "Failure"` / `not enabled` on `is connections ping`. | [connection-auth-failure.md](./playbooks/connection-auth-failure.md) |
+| Pack / publish / deploy fails, or invisible in Studio Web | Medium | Wrong `Type`, publishing the `.nupkg` not the `.zip`, 401/403/409 on publish, stale generated descriptors, or a project scaffolded by hand without the `project.uiproj` + `Workflow.json` shape (deploys but won't open in Studio Web — authoring concern owned by `uipath-api-workflow`). | [publish-deploy-failure.md](./playbooks/publish-deploy-failure.md) |

package/skills/uipath-troubleshoot/references/products/assistant/investigation_guide.md

@@ -0,0 +1,71 @@
+# UiPath Assistant Investigation Guide
+
+Read `overview.md` for the two-log architecture and evidence model before this guide.
+
+## Rules for this domain
+
+1. **Anchor on the reported symptom before opening any log.** A log is a wall of noise; know what you are looking for first. If the user hasn't said what happened, ask in one sentence: what they tried, what they saw, roughly when.
+2. **A stack trace with a function name beats log grepping.** If the user can paste one (e.g. `at InteractiveConnectFlow.SignIn`), use it to route straight to the matching playbook via `summary.md`.
+3. **Never grep blindly for "error".** Every archive holds hundreds of benign errors (offline-state noise, expected shutdown IPC timeouts). Correlate to the anchored symptom, not to the string `error`.
+4. **Mind the timezones.** `Robot.log` is machine-local with an offset (e.g. `+03:00`); `combined.log` is usually UTC. Convert before correlating timestamps across the two files.
+5. **Never speculate past the evidence.** A timeout means "timeout — likely network"; do not guess DNS vs proxy vs firewall without data. Ask for `curl`/network output instead.
+6. **Never assume the archive is complete.** Users often paste only the first N lines. If the symptom should have left a trace and you can't find it, ask for the full file.
+
+## Step 1 — Ask for high-value artifacts if the archive is thin
+
+`combined.log` captures only main-process logs. These often pinpoint the cause in seconds when the log alone can't:
+
+- **DevTools console output** — renderer-side errors, unhandled rejections, stack traces with function names (never reach `combined.log`).
+- **HAR file / Network tab** — failed HTTP calls with status codes, request/response bodies, timings.
+- **Screenshot / recording** of the error toast or dialog, plus the **exact on-screen error text** (usually more specific than what reached disk).
+
+## Step 2 — Scan combined.log first
+
+The Electron/Assistant side: user clicks, IPC routes invoked, UI state transitions. Fastest way to see *what the user did* and *how the app responded*.
+
+Look for:
+- The IPC route matching the reported action — `/robot/interactiveConnectSignIn` (sign-in), `/robot/connectToServer` (orchestrator connect), `/process/start` (run a process).
+- The `result` field on `Finished running handler` lines — `false` / `null` / missing often means a silent failure.
+- Repeated identical calls within seconds → the user clicking over and over because nothing happens.
+- `channel/*/robotUserStatus` and `channel/*/robotStatus` messages — Offline/Connected state transitions.
+- Any `error` / `isError: true` entries **on the anchored route** (Rule 3).
+
+Note the timestamps of the failing actions — you will correlate them with `Robot.log`.
+
+## Step 3 — Cross-reference Robot.log
+
+The native Robot service (C#/.NET). Apply the timezone rule (Rule 4) before matching timestamps.
+
+Look for:
+- `[ERROR]` entries near the failing-action timestamp.
+- Stack traces with `UiPath.Service.*` or `UiPath.RobotJS.*` namespaces — the class name (e.g. `InteractiveConnectFlow.SignIn`, `CloudConnectFlow.TryOpenFlow`) tells you exactly which flow failed.
+- The failing HTTP endpoint — note the host. `cloud.uipath.com` (production), another UiPath cloud environment, or an on-prem Orchestrator URL tells you which environment the app is pointed at.
+
+Route the exception class/endpoint to the matching playbook via `summary.md`.
+
+## Step 4 — Attribute the flow and decide the next action
+
+If `Robot.log` names a class/method (e.g. `InteractiveConnectFlow.SignIn`), use the flow name and namespace (`overview.md` § Reading the named flow) to attribute the failure to a layer and route to the matching playbook via `summary.md`.
+
+Then split on where the root cause lives:
+
+- **User-side cause** (network, VPN/proxy/firewall, DNS, wrong environment, tenant/license/assignment) — the playbook's resolution steps apply; give the user the exact fix and commands to verify.
+- **Product-side cause** — the evidence points at a defect inside the Assistant or Robot itself, not anything the user controls. Capture the exact trace (flow name, exception, timestamps) and report it to UiPath support; do not speculate past what the log shows.
+
+## Data correlation
+
+Before concluding from any log line, verify it matches the reported problem:
+
+- **Symptom** — the route/exception is the action the user reported (sign-in vs connect vs start), not a nearby unrelated error.
+- **Timestamp** — the line falls in the window the user described, after the timezone conversion (Rule 4).
+- **Environment** — the endpoint host matches the tenant the user is on.
+
+If it doesn't match: discard it and keep looking. Do not attribute the failure to the first `[ERROR]` you find.
+
+## Presenting
+
+Deliver a concise report (see also `references/presenting.md`):
+1. **Root cause** — one specific sentence (e.g. "DNS resolution of `cloud.uipath.com` timing out — VPN not connected").
+2. **Evidence** — the specific log line(s) with file path and line number; clickable links where possible (`[Robot.log:1229](file:///.../Robot.log)`).
+3. **What to try** — ordered by likelihood, with exact commands where applicable (`curl`, `nslookup`, etc.).
+4. **Any UX bug worth filing separately** — e.g. a silent 30s failure with no error toast, even when the underlying cause is external.

package/skills/uipath-troubleshoot/references/products/assistant/overview.md

@@ -0,0 +1,44 @@
+# UiPath Assistant (Desktop)
+
+Windows desktop app end users run to sign in, connect to Orchestrator, and start/stop the automations (processes) assigned to them. When it fails, the user exports a **diagnostic archive** and shares it — this domain diagnoses that archive.
+
+## Architecture
+
+Two layers, two logs:
+
+```
+UiPath Assistant (Electron)
+  ├── Angular renderer        ← the UI the user clicks (DevTools console lives here)
+  └── main process            ← IPC routing, app lifecycle          → combined.log
+        │  (local IPC)
+        ▼
+  UiPath Robot service (native .NET)                                → Robot.log
+        │  (HTTPS)
+        ▼
+  Orchestrator · Identity/cloud · NuGet feeds
+```
+
+- **`combined.log`** — Electron/main-process side: user clicks, which IPC route was invoked, `result` fields, UI status transitions. Usually UTC. Shows *what the user did* and *how the app responded*.
+- **`Robot.log`** — native Robot service (C#/.NET): the actual sign-in / connect / package / process work. **Machine-local time with an offset** (e.g. `+03:00`) — convert before correlating with `combined.log`.
+
+## Evidence model
+
+Diagnosis is **on-disk log files + the reported symptom** — there is **no `uip` CLI job/trace/log surface** for the Assistant desktop app (unlike Orchestrator jobs). The "raw data" is the archive files the user already shared, plus higher-value artifacts you ask for (DevTools console, HAR, screenshots). Do not fabricate `uip` commands for this domain.
+
+Archive shape: an `ExportDiagnoseArchive` folder (or a loose `combined.log` / `Robot.log`) produced by the Assistant's **Help → Export diagnostic data** action.
+
+## Dependencies
+
+- **Orchestrator** — the tenant the Assistant connects to; process list, job start. 4xx/5xx here → cross-reference the `orchestrator` domain.
+- **Identity / cloud** — OAuth/OIDC sign-in (`/identity_/*`, `/discovery_*`). Auth failures surface here.
+- **NuGet feeds** — process packages download from Orchestrator/feed on first start. Feed-unreachable → `NU1101` / package errors.
+- **Network** — VPN, proxy, firewall, DNS between the machine and cloud/on-prem Orchestrator.
+
+## Reading the named flow
+
+`Robot.log` traces name the flow that failed (class/method, e.g. `InteractiveConnectFlow.SignIn`, `CloudConnectFlow.TryOpenFlow`) — that name, plus the namespace, tells you which layer to attribute the failure to without needing product source:
+
+- **`UiPath.Service.*` / `UiPath.RobotJS.*`** in `Robot.log` — the native Robot service (sign-in, Orchestrator connect, package/process work).
+- **IPC routes** in `combined.log` (`/robot/*`, `/process/*`) — the Assistant Electron app.
+
+Use the flow name to route to the right playbook via `summary.md` and to describe the failing step precisely in your report. If the evidence points at a defect inside the Assistant or Robot itself — not the user's network, configuration, or tenant — capture the exact trace and report it to UiPath support.

package/skills/uipath-troubleshoot/references/products/assistant/playbooks/assistant-crash.md

@@ -0,0 +1,38 @@
+---
+confidence: low
+---
+
+# Assistant Crashes or Closes Unexpectedly
+
+## Context
+
+The Assistant window closes, goes white/blank, or freezes then dies — with or without an error. Low confidence: crashes have many causes and `combined.log` alone rarely captures the fatal frame.
+
+What this looks like:
+- `combined.log` ends abruptly with no clean shutdown line, or shows a main-process exception just before it stops.
+- The **renderer** side (where most crashes originate) is not in `combined.log` — you need the **DevTools console** for an unhandled rejection / `Uncaught` error with a stack trace and function name.
+- `Robot.log` usually keeps running (separate process) unless the crash is Robot-service-side.
+
+What can cause it:
+1. **Renderer exception** — an unhandled error/rejection in the Angular UI (blank window or immediate close). Evidence lives in DevTools console, not `combined.log`.
+2. **Main-process exception** — an uncaught exception in the Electron main process → `combined.log` shows it as the last line.
+3. **Robot-service crash** — the native service died; `Robot.log` ends with a fatal trace and the Assistant loses its backend.
+4. **Environment** — GPU/driver (white screen), out-of-memory, or antivirus killing the process — no in-app trace; corroborate with Windows Event Viewer.
+
+What to look for:
+- **Is it reproducible on a specific action?** If so, treat it as that action's failure first (sign-in / connect / start) — the crash may be a symptom, not the root.
+- Which process died — Assistant (Electron) vs Robot service — decides `combined.log`/DevTools vs `Robot.log`.
+
+## Investigation
+
+1. Anchor: does the crash follow a specific action? If yes, run that action's playbook first; a crash on sign-in/connect/start is usually the underlying failure surfacing.
+2. Read the **tail** of `combined.log` — a main-process exception on the last line → cause 2; a clean-then-gone tail with a blank UI → cause 1, **ask for the DevTools console** (the renderer stack is the whole answer).
+3. If `Robot.log` ends with a fatal trace at the crash time (timezone-convert) → cause 3; route the exception class via `summary.md`.
+4. If no app-side trace anywhere → cause 4; ask for **Windows Event Viewer** (Application log) entries for `UiPath.Assistant` / `.NET Runtime` at the crash time, and GPU/AV details.
+
+## Resolution
+
+- **Cause 1 (renderer):** capture the DevTools stack (component/service name + error); apply a workaround for the specific error and report the crash to UiPath support with the stack.
+- **Cause 2 (main process):** capture the `combined.log` exception (handler + stack) and report it to UiPath support.
+- **Cause 3 (Robot service):** route the `Robot.log` fatal exception via `summary.md`; if it maps to sign-in/connect/start, fix that root cause.
+- **Cause 4 (environment):** disable GPU acceleration for the white-screen/driver case, raise available memory, or add an AV exclusion for the Assistant/Robot executables per the Event Viewer evidence.

package/skills/uipath-troubleshoot/references/products/assistant/playbooks/orchestrator-connection-failure.md

@@ -0,0 +1,43 @@
+---
+confidence: medium
+---
+
+# Assistant Cannot Connect to Orchestrator
+
+## Context
+
+The user is signed in but the Assistant cannot reach/attach to its Orchestrator tenant — stays Offline, "Connecting…" never resolves, or drops to disconnected. Distinct from sign-in (`sign-in-failure.md`): the identity step succeeded, the Orchestrator attach did not.
+
+What this looks like:
+- `combined.log`: `/robot/connectToServer` invoked (often repeated); `Finished running handler` with `result: false`/`null`; `robotStatus` transitions to Offline/Disconnected.
+- `Robot.log`: a trace in `CloudConnectFlow` (e.g. `CloudConnectFlow.TryOpenFlow`) or the connect path; `TaskCanceledException` / `HttpClient.Timeout`, `HttpRequestException`, or an HTTP `401` / `403` against an Orchestrator URL (`/odata/*`, `/api/*`).
+- The Orchestrator host in `Robot.log` — cloud (`cloud.uipath.com`) or an on-prem URL.
+
+What can cause it:
+1. **Orchestrator unreachable** — `TaskCanceledException` / `HttpClient.Timeout` / `HttpRequestException` reaching the Orchestrator host: network (VPN/proxy/firewall/DNS), or on-prem Orchestrator down.
+2. **Machine/robot not authorized** — `401` / `403`: the machine key / robot is not registered to the tenant/folder, or the license/robot assignment is missing.
+3. **Wrong Orchestrator URL** — the connect target host is not the tenant the user belongs to (stale or mistyped on-prem URL).
+4. **TLS/certificate** — on-prem with a self-signed or untrusted cert: TLS handshake failure in the connect trace.
+
+What to look for:
+- Transport error vs HTTP status — same split as sign-in; it decides cause 1 vs 2.
+- Whether sign-in itself succeeded (rules this in vs `sign-in-failure.md`).
+
+## Investigation
+
+1. Confirm sign-in succeeded (`interactiveConnectSignIn` result true earlier in `combined.log`); if not, go to `sign-in-failure.md` first.
+2. Find `/robot/connectToServer` in `combined.log` and note the timestamp and `result`.
+3. In `Robot.log` (timezone-convert), read the `CloudConnectFlow` trace at that timestamp:
+   - Transport exception, no HTTP status → cause 1.
+   - `401` / `403` from the Orchestrator host → cause 2.
+   - TLS/cert error → cause 4.
+   - Endpoint host ≠ expected tenant → cause 3.
+4. For a `401`/`403` (cause 2), the Orchestrator side is the authority — cross-reference the `orchestrator` domain (machine/robot registration, license) before concluding.
+5. For cause 1, ask the user to `curl -v https://<orchestrator-host>/api/status` from the machine to isolate DNS / proxy / firewall / server-down.
+
+## Resolution
+
+- **Cause 1 (unreachable):** restore connectivity to the Orchestrator host (VPN, proxy/firewall allowlist, DNS); for on-prem, confirm the Orchestrator service is up. Re-test with the `curl` above.
+- **Cause 2 (`401`/`403`):** register/assign the machine and robot to the correct tenant/folder and confirm an available license — resolve via the `orchestrator` domain, then reconnect.
+- **Cause 3 (wrong URL):** correct the Orchestrator URL in Assistant → Preferences and reconnect.
+- **Cause 4 (TLS/cert):** install the on-prem Orchestrator's certificate chain into the machine trust store (or fix the server cert); reconnect.

package/skills/uipath-troubleshoot/references/products/assistant/playbooks/process-missing-or-unstartable.md

@@ -0,0 +1,41 @@
+---
+confidence: medium
+---
+
+# Process Missing or Won't Start in the Assistant
+
+## Context
+
+The Assistant is signed in and connected, but a process the user expects is not listed, or clicking it fails to start.
+
+What this looks like:
+- **Missing:** the process list is empty or short; `combined.log` shows the list fetched with few/zero entries; `robotStatus` is Connected.
+- **Won't start:** `combined.log` shows `/process/start` invoked with `result: false`/`null`, often repeated.
+- `Robot.log` on a start attempt: package restore/download errors — `NU1101` ("Unable to find package"), NuGet feed URLs, or a download `TaskCanceledException`/`HttpRequestException`; or a launch error before the workflow runs.
+
+What can cause it:
+1. **Package feed unreachable** — `NU1101` / feed timeout: the process package cannot be downloaded from Orchestrator/the NuGet feed (network, or feed misconfigured).
+2. **Not assigned / wrong folder scope** — the process is not assigned to this user's robot, or lives in a folder the user's robot isn't in → it never appears (missing case).
+3. **License / robot type mismatch** — no attended license, or the robot type can't run this process.
+4. **Package/dependency error at launch** — the package downloads but a missing dependency or corrupt package fails the launch (error in `Robot.log` before first activity).
+
+What to look for:
+- Missing vs won't-start — the two split cause 2/3 (missing) from cause 1/4 (start fails).
+- On a start failure, whether `Robot.log` shows a **download** error (`NU1101`, feed URL) vs a **launch** error after download.
+
+## Investigation
+
+1. Anchor: missing from the list, or listed-but-won't-start? Note the exact process name.
+2. **Missing:** in `combined.log` confirm the process-list fetch returned few/zero entries while Connected → the list is authoritative, so the process isn't assigned/in scope for this robot → cross-reference the `orchestrator` domain (process assignment, folder, license).
+3. **Won't start:** find `/process/start` in `combined.log`, note the timestamp, then read `Robot.log` (timezone-convert) at that point:
+   - `NU1101` / feed URL / download timeout → cause 1.
+   - Download succeeded, then a dependency/corrupt-package error → cause 4.
+   - License/robot-type error → cause 3.
+4. For cause 1, capture the feed host and ask the user to `curl -v <feed-url>` from the machine to separate network from feed config.
+
+## Resolution
+
+- **Cause 1 (feed unreachable):** restore access to the package feed (network/proxy/firewall), or fix the feed URL/credentials in Orchestrator; retry start.
+- **Cause 2 (assignment/scope):** assign the process to the user's robot and confirm the robot is in the process's folder — resolve via the `orchestrator` domain; the process then appears.
+- **Cause 3 (license/type):** allocate an attended license / correct the robot type for the user; reconnect and retry.
+- **Cause 4 (package/dependency):** republish the package with its dependencies resolved (or fix the corrupt version); clear the local package cache and retry.

package/skills/uipath-troubleshoot/references/products/assistant/playbooks/sign-in-failure.md

@@ -0,0 +1,42 @@
+---
+confidence: medium
+---
+
+# Assistant Sign-In Fails
+
+## Context
+
+The user clicks sign in to UiPath cloud/Identity from the Assistant and it never completes — spins, returns to the signed-out state, or shows an auth error toast.
+
+What this looks like:
+- `combined.log`: the `/robot/interactiveConnectSignIn` IPC route invoked, often repeated within seconds; `Finished running handler` with `result: false`/`null`; `robotUserStatus` stays Offline.
+- `Robot.log`: a stack trace in `InteractiveConnectFlow.SignIn` (namespace `UiPath.Service.*`); a failing call to `/identity_/*` or `/discovery_*`; `HttpRequestException`, `TaskCanceledException`, or an HTTP `401` / `403`.
+- Exact on-screen text if the user can supply it (e.g. "We couldn't sign you in").
+
+What can cause it:
+1. **Cloud/Identity unreachable** — `HttpRequestException` / `TaskCanceledException` on `/discovery_*` or `/identity_/*`: DNS, VPN, proxy, or firewall between the machine and Identity.
+2. **Auth rejected** — `401` / `403` from Identity: expired/invalid token, MFA/Conditional Access the desktop flow can't satisfy, or the account lacks tenant access.
+3. **Wrong/stale environment** — the endpoint host in `Robot.log` is not the tenant the user expects (e.g. a non-production environment for a production user), or a stale cached URL.
+4. **Browser-callback not returned** — the system browser completed sign-in but the redirect never reached the Assistant (default-browser/protocol-handler issue) — the DevTools console / no callback line is the tell.
+
+What to look for:
+- Which endpoint host `Robot.log` calls, and whether it resolves at all.
+- Whether the failure is a transport error (cause 1) or an HTTP status (cause 2) — that split drives everything.
+
+## Investigation
+
+1. Anchor: confirm the user was signing in (not connecting to an already-signed-in Orchestrator — that is `orchestrator-connection-failure.md`).
+2. In `combined.log`, find `/robot/interactiveConnectSignIn` and its `result`. Note the timestamp.
+3. In `Robot.log` (timezone-convert first), read the `InteractiveConnectFlow.SignIn` trace near that timestamp. Classify the failure:
+   - Transport exception (`TaskCanceledException` / `HttpRequestException`, no HTTP status) → cause 1.
+   - HTTP `401` / `403` → cause 2.
+   - Endpoint host ≠ expected tenant → cause 3.
+   - No server-side trace at all, but the browser opened → cause 4; ask for DevTools console.
+4. For cause 1, ask the user to `curl -v https://<host>/identity_/.well-known/openid-configuration` (or `nslookup <host>`) from the same machine to separate DNS / proxy / firewall.
+
+## Resolution
+
+- **Cause 1 (unreachable):** restore connectivity to the endpoint host — connect VPN, whitelist the host in the proxy/firewall, or fix DNS. Re-test with the `curl` above before retrying sign-in.
+- **Cause 2 (`401`/`403`):** confirm the account has access to the tenant and is not blocked by MFA/Conditional Access for the desktop flow; sign out fully and back in to refresh the token. If Conditional Access blocks it, exempt the desktop app flow per org policy.
+- **Cause 3 (wrong environment):** point the Assistant at the correct Orchestrator/cloud URL (Assistant → Preferences → Orchestrator settings) and sign in again.
+- **Cause 4 (callback lost):** set the correct default browser / re-register the `uipath://` protocol handler; retry. File a UX bug if the app hangs silently instead of surfacing the lost callback.

package/skills/uipath-troubleshoot/references/products/assistant/summary.md

@@ -0,0 +1,18 @@
+# UiPath Assistant Playbooks
+
+**Overview:** [overview.md](./overview.md) — the two-log architecture (`combined.log` / `Robot.log`) and evidence model (on-disk logs, no `uip` CLI surface)
+**Investigation guide:** [investigation_guide.md](./investigation_guide.md) — anchor-on-symptom rules, high-value artifacts to request, combined.log-first scan, Robot.log timezone correlation, flow attribution and escalation
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| Sign-in fails | Medium | Signed-out stays signed-out. `combined.log` `/robot/interactiveConnectSignIn` `result: false`; `Robot.log` `InteractiveConnectFlow.SignIn` — transport error (`TaskCanceledException`/`HttpRequestException`) on `/identity_`/`/discovery_`, or HTTP `401`/`403`, wrong environment, or lost browser callback | [sign-in-failure.md](./playbooks/sign-in-failure.md) |
+| Cannot connect to Orchestrator | Medium | Signed in but stays Offline. `combined.log` `/robot/connectToServer` `result: false`; `Robot.log` `CloudConnectFlow` — Orchestrator unreachable (`HttpClient.Timeout`/`TaskCanceledException`), `401`/`403` (machine/robot not authorized), wrong URL, or TLS/cert | [orchestrator-connection-failure.md](./playbooks/orchestrator-connection-failure.md) |
+| Process missing or won't start | Medium | Process not listed, or `/process/start` fails. `Robot.log` package errors (`NU1101`, feed timeout), not-assigned/wrong-folder scope, license/robot-type mismatch, or a package/dependency launch error | [process-missing-or-unstartable.md](./playbooks/process-missing-or-unstartable.md) |
+| Crashes or closes unexpectedly | Low | Window closes/blanks/freezes. Renderer exception (DevTools console, not `combined.log`), main-process exception (`combined.log` tail), Robot-service crash (`Robot.log`), or environment (GPU/OOM/AV) | [assistant-crash.md](./playbooks/assistant-crash.md) |
+
+## No-signature routing
+
+| Symptom | Entry |
+|---|---|
+| Assistant hangs on an action with no error toast and no clear log trace | Anchor on the action (sign-in / connect / start), run that playbook, and treat the silent hang as a UX bug to file (investigation guide § Presenting, item 4) |
+| Archive has an expected trace missing | The user likely pasted a truncated file — ask for the full `combined.log` / `Robot.log` (investigation guide Rule 6) |

package/skills/uipath-troubleshoot/references/products/coded-apps/overview.md

@@ -0,0 +1,49 @@
+# Coded Apps
+
+UiPath Coded Apps — custom web front-ends (**coded web apps**) and Action Center form apps (**coded action apps**) built in TypeScript/React and calling UiPath APIs through the `@uipath/uipath-typescript` SDK. Scaffolded, packed, published, and deployed with `uip codedapp`.
+
+Unlike server-side products, a coded app runs **in the user's browser**. Most failures surface as an OAuth redirect error, a failed HTTP call, or a broken deployed URL — not as a faulted job with a trace.
+
+## Runtime & Auth Model
+
+- **SDK config comes from `<meta name="uipath:*">` tags**, not from code. `new UiPath()` reads `clientId`, `scope`, `orgName`, `tenantName`, `baseUrl`, `redirectUri` from those tags. Locally the tags are injected from **`uipath.json`** (project root, committed) — the single config source.
+- **Auth is browser OAuth 2.0 Authorization Code + PKCE.** The External Application backing a coded app is a **non-confidential (public) client** with **user-delegated scopes**. The app redirects to UiPath, the user signs in, and the SDK exchanges the code for a token via `sdk.completeOAuth()`.
+- **API host is the API subdomain** (`api.uipath.com`), NOT the portal domain (`cloud.uipath.com`). The portal domain does not return browser CORS headers.
+- **Deployed apps** are served under a platform-routed URL, so the app must be built with a **relative** Vite base (`base: './'`) and read its route prefix from `getAppBase()` — an absolute or hardcoded base breaks asset/routing resolution after deploy.
+
+## Dependencies
+
+- **Identity Server** — issues the OAuth token; owns the External Application (redirect URIs, scopes). Inspect/fix with `uip admin external-apps`.
+- **Orchestrator / Data Fabric / Maestro / Action Center** — the APIs the SDK services call; each call needs a matching OAuth scope.
+- **Apps service** — hosts and routes the deployed app; registered by `uip codedapp publish` / `deploy`.
+
+## CLI
+
+```
+uip codedapp push [project-id]        — push local source to Studio Web
+uip codedapp pull [project-id]        — pull project files from Studio Web
+uip codedapp pack <dist>              — package build output into .nupkg
+uip codedapp publish                  — upload .nupkg + register the app
+uip codedapp deploy                   — deploy or upgrade the app (registers prod redirect URI)
+uip admin external-apps get <client-id>       — registered redirect URIs + scopes of the OAuth client
+uip admin external-apps update <client-id>    — add/replace redirect URIs (--redirect-uri) or scopes (--user-scope)
+```
+
+Key commands for troubleshooting:
+- `uip admin external-apps get <client-id> --output json` — the External Application state: what redirect URIs and scopes are actually registered. Compare against what `uipath.json` requests.
+- `uip admin external-apps update <client-id> --redirect-uri '<full-list>' --output json` — register a redirect URI. **`--redirect-uri` and `--user-scope` REPLACE the existing list** — always pass the complete desired set (existing + new), read first from `get`.
+- `uip admin external-apps update <client-id> --user-scope '<full-list>' --output json` — register scopes.
+
+## Evidence Sources
+
+There is **no runtime job/trace/log CLI** for a deployed coded app. Diagnosis is current-state + the error signature the user reports:
+
+| Source | What it tells you |
+|--------|-------------------|
+| Error string the user pastes | OAuth error param (`redirect_uri_mismatch`, `invalid_scope`), HTTP status (401/403/404), CORS message, deploy output |
+| `uipath.json` (project root) | What the app **requests**: `clientId`, `scope`, `baseUrl`, `redirectUri` |
+| `uip admin external-apps get <client-id>` | What the External Application **allows**: registered redirect URIs and scopes |
+| `.uipath/app.config.json` | Deploy result: `appUrl`, `systemName` (present only after a successful `deploy`) |
+| `vite.config.ts` | `base` and `server.port` — governs deployed routing and local dev URL |
+
+The mismatch between what the app *requests* (`uipath.json`) and what the client *allows* (`external-apps get`) is the root of most coded-app auth failures.

package/skills/uipath-troubleshoot/references/products/coded-apps/playbooks/action-app-form-data-not-loading.md

@@ -0,0 +1,66 @@
+---
+confidence: medium
+---
+
+# Action App: Form Data Not Loading
+
+## Context
+
+Applies to coded **action** apps (Action Center form apps built with `@uipath/coded-action-app`), not web apps.
+
+What this looks like:
+- The action app renders but the form is blank — fields that should be pre-filled from the task stay empty
+- `codedActionAppService.getTask()` resolves to `null`/`undefined`, or rejects, and the app has no visible error
+- Console may show an error thrown from `@uipath/coded-action-app` `getTask`, or nothing at all (silent failure — soft signature)
+
+What can cause it:
+- `getTask()` failed and the app swallowed it — no `.catch()` / error handling, so the empty form is the only symptom
+- The app was opened **outside an Action Center context** (directly by URL) — `getTask()` requires the Action Center host that injects the task context
+- The `@uipath/coded-action-app` package is missing from the app
+- The app was published as type `Web` instead of `Action` (`uip codedapp publish -t Action`), so it is not wired into Action Center
+
+What to look for:
+- Whether `getTask()` has error handling at all — an unlogged rejection presents identically to "no data"
+- Whether the app is being opened from an Action Center task assignment vs. directly
+- Whether the package is installed and the app was published as `Action`
+
+## Investigation
+
+1. Confirm error handling exists on the task load. If the code calls `getTask()` without a `.catch`, add logging to surface the real error:
+
+   ```typescript
+   codedActionAppService.getTask()
+     .then((task) => { console.log('Task loaded:', task); if (task?.data) setFormData(task.data as FormData); })
+     .catch((err) => console.error('getTask failed:', err));
+   ```
+
+   Read the console output — the thrown error usually names the cause directly.
+
+2. Confirm the app is opened from an Action Center task (an assigned action item), not by pasting the app URL. `getTask()` returns no task without the Action Center context.
+
+3. Confirm the package is installed:
+
+   ```bash
+   grep -n "@uipath/coded-action-app" package.json
+   ```
+
+4. Confirm the app was published as an Action app (not Web) — an action app published as `Web` never receives a task context. Re-publish with `-t Action` if wrong (see Resolution).
+
+## Resolution
+
+- **If `getTask()` fails silently:** add the `.catch` + logging above so the error is visible, then fix the underlying cause it reports.
+
+- **If opened outside Action Center:** open the app from its Action Center task assignment. Direct-URL access cannot supply a task.
+
+- **If the package is missing:** install it, then rebuild and republish:
+
+  ```bash
+  npm install @uipath/coded-action-app --@uipath:registry=https://registry.npmjs.org
+  ```
+
+- **If published as the wrong type:** republish and deploy as an action app:
+
+  ```bash
+  uip codedapp publish -t Action
+  uip codedapp deploy
+  ```