@uipath/skills 1.197.0 → 1.197.2

package/skills/uipath-rpa/references/debugging.md

@@ -6,15 +6,19 @@ This is a powerful complement to `validate` (static validation). While `validate
 
 ## Studio Desktop vs headless
 
-Most debugging works on **headless Studio** with no Studio Desktop install: `run`, `debug start` (with workflow-level breakpoint), all stepping verbs (`debug step-over`, `debug step-into`, `debug step-out`), `debug continue`, `debug break`, `debug resume`, `debug continue-retry`, `debug continue-ignore`, `execution cancel`, `debug restart-from-top`.
+Most debugging works on **headless Studio** with no Studio Desktop install: `run`, `debug start` (including **activity-targeted breakpoints via `--breakpoints`**), all stepping verbs (`debug step-over`, `debug step-into`, `debug step-out`), `debug continue`, `debug break`, `debug resume`, `debug continue-retry`, `debug continue-ignore`, `debug state`, `debug set-breakpoints`, `execution cancel`, `debug restart-from-top`.
 
-**Studio Desktop is required** for any flow that targets a specific activity, because activity targeting goes through `uip rpa focus-activity` and that tool only runs against Studio Desktop:
+On the headless backend, every debug command **returns at the next stable state** — paused at an activity, suspended on an exception, or completed — carrying `DebugState` / `DebugDetails` in the result, so you always learn where execution stands from the command's own response. See [The stable-state debug loop](#the-stable-state-debug-loop-headless).
+
+**Studio Desktop is required** for any flow that targets the *focused* activity, because focusing goes through `uip rpa focus-activity` and only Studio Desktop has a designer to focus:
 
 | Command | Why it needs Studio Desktop |
 |---------|------------------------------|
-| `debug test-activity` | Operates on the focused activity — requires `focus-activity` first |
-| `debug start-from-here` | Operates on the focused activity — requires `focus-activity` first |
-| `debug toggle-breakpoint` *targeted to a specific activity* | Targeting requires `focus-activity` first. Without focusing, the breakpoint toggles on the whole workflow (still works headless) |
+| `debug test-activity` | Operates on the focused activity — requires `focus-activity` first. Headless rejects the command |
+| `debug start-from-here` | Operates on the focused activity — requires `focus-activity` first. Headless rejects the command |
+| `debug toggle-breakpoint` | Toggles on the focused activity/line — requires `focus-activity` first. Headless rejects the command; set headless breakpoints with `--breakpoints` on `debug start` (or `debug set-breakpoints` mid-session), which target activities by IdRef with no focusing step |
+
+> **`focus-activity` on headless is a silent no-op** — it returns `success: true` but focuses nothing (there is no designer). Do NOT use it to "target" an activity for a headless debug flow and do not treat its success as confirmation: on headless, the focus-dependent verbs above fail with `Unknown command` regardless, and activity targeting goes through `--breakpoints` instead.
 
 Before invoking any of the above, run `uip rpa studio start --project-dir "<PROJECT_DIR>" --output json` and ensure the project is open in Studio Desktop. See [environment-setup.md § Edge case: requiring Studio Desktop](environment-setup.md#edge-case-requiring-studio-desktop).
 
@@ -26,7 +30,7 @@ Before invoking any of the above, run `uip rpa studio start --project-dir "<PROJ
 
 ```bash
 uip rpa run         --file-path <relative-path> [--input-arguments key=value]... [--log-level <level>] [--skip-build] [--output json]
-uip rpa debug start --file-path <relative-path> [--input-arguments key=value]... [--log-level <level>] [--skip-build] [--output json]
+uip rpa debug start --file-path <relative-path> [--input-arguments key=value]... [--breakpoints item]... [--log-level <level>] [--skip-build] [--output json]
 ```
 
 `debug test-activity` and `debug start-from-here` operate on the currently focused activity (no `--file-path`):
@@ -36,13 +40,15 @@ uip rpa debug test-activity     [--input-arguments key=value]... [--input-variab
 uip rpa debug start-from-here   [--input-arguments key=value]... [--input-variables key=value]... [--log-level <level>] [--output json]
 ```
 
-All other `debug` verbs (`break`, `continue`, `resume`, `continue-retry`, `continue-ignore`, `step-into`, `step-over`, `step-out`, `toggle-breakpoint`, `restart-from-top`) take no parameters — they operate on the active debug session.
+The mid-session verbs (`break`, `continue`, `resume`, `continue-retry`, `continue-ignore`, `step-into`, `step-over`, `step-out`, `state`) operate on the active debug session and take only the optional `--wait-timeout-seconds`. `debug set-breakpoints` takes `--breakpoints`. `debug toggle-breakpoint` and `debug restart-from-top` take no parameters.
 
 | Parameter | Description |
 |-----------|-------------|
 | `--file-path` | Workflow file to run (relative to project root). Applies to `run` and `debug start` only |
 | `--input-arguments` | Project-level input arguments as repeatable `key=value` pairs (`=` string, `:=` raw JSON; see [cli-reference.md § Passing structured inputs](cli-reference.md#passing-structured-inputs)). Only for `run`, `debug start`, `debug test-activity`, and `debug start-from-here` (see [Input Variables vs Input Arguments](#input-variables-vs-input-arguments)) |
 | `--input-variables` | Workflow-level variable values as repeatable `key=value` pairs (values are VB/C# expressions — always `=`). Only for `debug test-activity` and `debug start-from-here` (see [Input Variables vs Input Arguments](#input-variables-vs-input-arguments)) |
+| `--breakpoints` | Activity breakpoints for XAML debugging (headless backend). One array item per flag occurrence, comma-separated `key=value` inside an item: `--breakpoints 'workflowFile=Main.xaml,activityIdRef=Assign_1'`. Keys: `workflowFile` (required; workflow path relative to the project root), `activityIdRef` (the target activity's `sap2010:WorkflowViewState.IdRef` attribute value from the XAML — the stable way to address an activity you can read straight from the file), optional `condition` (VB/C# expression; breaks only when it evaluates to True), `hitCount:=N` (break only on exactly the Nth hit), `enabled` (defaults to true). Whole payload from a file: `--breakpoints-file breakpoints.json`. Used by `debug start` (initial set) and `debug set-breakpoints` (replaces the running session's whole set) |
+| `--wait-timeout-seconds` | Maximum seconds a mid-session verb waits for the next stable state before returning `DebugState: "Running"` instead of hanging. Default 120 (0 for `debug state`, making it an instant probe). Headless backend only |
 | `--log-level` | Minimum log level: `Verbose`, `Trace` (default), `Information`, `Warning`, `Error`, `Critical` |
 | `--skip-build` | Skip the pre-run build step (use only when you've just built) |
 | `--output` | Output format: `json` (recommended), `table`, `yaml`, `plain` |
@@ -53,23 +59,61 @@ All other `debug` verbs (`break`, `continue`, `resume`, `continue-retry`, `conti
 | Verb | When to Use | What It Does |
 |------|-------------|--------------|
 | `run` | Run without debugging | Executes the workflow to completion. The default authoring loop verb |
-| `debug start` | Begin a debug session | Starts execution in debug mode. Pauses at the first breakpoint (or at the first activity if a breakpoint is set on the workflow itself). Returns current execution state |
+| `debug start` | Begin a debug session | Starts execution in debug mode and **returns at the first stable state**: `Paused` at a breakpoint (pass `--breakpoints` to set them), `Suspended` on an unhandled exception, or `Completed` if nothing interrupts the run. The response's `DebugState` / `DebugDetails` say where execution stands; the session stays alive for the mid-session verbs |
 | `debug test-activity` | Test one activity in isolation | Isolates the currently focused activity and executes it in a temporary test workflow. **Requires `focus-activity` first → Studio Desktop required** (see [Studio Desktop vs headless](#studio-desktop-vs-headless)). Use `--input-variables` to set variable values and `--input-arguments` to set argument values |
 | `debug start-from-here` | Debug from a specific activity | Starts a debugging session from the currently focused activity, skipping all preceding activities. **Requires `focus-activity` first → Studio Desktop required** (see [Studio Desktop vs headless](#studio-desktop-vs-headless)). Use `--input-variables` to set variable values and `--input-arguments` to set argument values |
-| `debug toggle-breakpoint` | Set/remove breakpoints | Toggles a breakpoint on the currently focused activity (XAML) or line (.cs). Use `uip rpa focus-activity` to focus beforehand — **activity-targeted toggling requires Studio Desktop**. For XAML, cycles through 3 states: **enabled → disabled → no breakpoint**. For .cs, cycles through 2 states: **breakpoint → no breakpoint**. If no activity/line is focused, toggles on the entire workflow (works on Helm) |
-| `debug step-over` | Execute one activity and pause | Executes the current activity, then pauses at the next sibling activity. Does not enter child scopes (e.g., stays at the For Each level, doesn't step into its body) |
-| `debug step-into` | Drill into child activities | Executes and pauses at the first child activity inside the current scope. Use to enter loops, sequences, Try-Catch blocks, etc. |
-| `debug step-out` | Exit the current scope | Continues execution until the current scope completes, then pauses at the parent level. Use to leave a loop body or nested sequence |
-| `debug continue` | Run to next breakpoint | Resumes execution until the next breakpoint is hit or an exception occurs |
-| `debug break` | Pause execution | Pauses a running debug session at the current point of execution |
+| `debug toggle-breakpoint` | Set/remove breakpoints interactively (Studio Desktop only) | Toggles a breakpoint on the currently focused activity (XAML) or line (.cs). Use `uip rpa focus-activity` to focus beforehand. For XAML, cycles through 3 states: **enabled → disabled → no breakpoint**. For .cs, cycles through 2 states: **breakpoint → no breakpoint**. **Not available headless** (rejected as an unknown command) — use `--breakpoints` on `debug start` or `debug set-breakpoints` instead |
+| `debug step-over` | Execute one activity and pause | Executes the current activity, then pauses at the next sibling activity. Does not enter child scopes (e.g., stays at the For Each level, doesn't step into its body). Returns the new paused state with locals |
+| `debug step-into` | Drill into child activities | Executes and pauses at the first child activity inside the current scope. Use to enter loops, sequences, Try-Catch blocks, etc. Returns the new paused state with locals |
+| `debug step-out` | Exit the current scope | Continues execution until the current scope completes, then pauses at the parent level. Use to leave a loop body or nested sequence. Returns the new paused state with locals |
+| `debug continue` | Run to next breakpoint | Resumes execution and returns at the next stable state — the next breakpoint (`Paused`), an exception (`Suspended`), or the end of the run (`Completed`) |
+| `debug break` | Pause execution | Pauses a running debug session at the next executed activity and returns the paused state with locals |
+| `debug state` | Inspect without side effects | Reports the session's current `DebugState` (`Running`, `Paused`, `Suspended`, `Completed`, or `None` when no session is active) plus the last captured details. Instant by default; pass `--wait-timeout-seconds` to long-poll a running session for its next stable state |
+| `debug set-breakpoints` | Change breakpoints mid-session | Replaces the active session's **whole** breakpoint set with the `--breakpoints` payload. For a new session, pass `--breakpoints` on `debug start` instead |
 | `debug resume` | Resume from suspended state | Resumes execution when the workflow is in a suspended (not just paused) state |
 | `debug continue-retry` | Retry after exception | Resumes execution and **retries the current activity** that caused the exception. Use when you've fixed the underlying issue (e.g., network timeout) and want to try again |
-| `debug continue-ignore` | Skip past exception | Resumes execution and **ignores the exception** on the current activity. Use when the error is non-critical and you want to proceed |
+| `debug continue-ignore` | Skip past exception | Resumes execution and **ignores the exception** on the current activity, pausing at the next activity. Use when the error is non-critical and you want to proceed |
 | `execution cancel` | End the session | Cancels the currently active execution — works for both `run` and `debug start` |
 | `debug restart-from-top` | Start over | Restarts execution from the beginning of the workflow without ending the debug session. Breakpoints are preserved |
 
 ---
 
+## The stable-state debug loop (headless)
+
+On the headless backend, debugging is a synchronous request/response loop: **every command returns when execution reaches the next stable state**, and the response tells you exactly where things stand. No command hangs waiting for a human — if nothing stable is reached within `--wait-timeout-seconds`, the response says `Running` and how to proceed.
+
+`DebugState` values in the response:
+
+| `DebugState` | Meaning | What to do next |
+|---|---|---|
+| `Paused` | Stopped at a breakpoint or after a step/break. `DebugDetails` carries the current activity (name, id, workflow file) and a snapshot of in-scope variables, arguments, and properties | Inspect `DebugDetails`, then `step-over` / `step-into` / `step-out` / `continue`, or `execution cancel` |
+| `Suspended` | Stopped on an unhandled exception; the session is still alive. `DebugDetails` carries the exception type, message, faulting activity, and locals | `continue` to propagate the exception, `continue-retry` to re-run the faulted activity, `continue-ignore` to skip it, or `execution cancel` |
+| `Completed` | The run finished. The response is the normal run result (`Output`, `HasErrors`, `ErrorMessage`) | Read the run result; the session is gone |
+| `Running` | The wait timed out before a stable state was reached — execution is still going | Poll with `debug state`, send `debug break` to pause at the next activity, or `execution cancel` |
+| `None` | No debug session is active | Start one with `debug start` |
+
+The canonical loop:
+
+```bash
+# Start with breakpoints on the activities you care about — returns Paused at the first hit
+uip rpa debug start --file-path Main.xaml \
+  --breakpoints 'workflowFile=Main.xaml,activityIdRef=Assign_1' --output json
+
+# Inspect DebugDetails (activity + locals), then advance — each call returns the next state
+uip rpa debug step-over --output json
+uip rpa debug continue  --output json
+
+# If a response says Suspended, decide on the exception:
+uip rpa debug continue-ignore --output json   # or continue-retry / continue / execution cancel
+
+# Not sure what's happening? Probe without side effects:
+uip rpa debug state --output json
+```
+
+Breakpoints are addressed by `activityIdRef` — the `sap2010:WorkflowViewState.IdRef` attribute you can read directly from the XAML you authored — so no `focus-activity` (and no Studio Desktop) is needed. Conditional breakpoints (`condition`) and hit counts (`hitCount:=N`) are evaluated by the runtime.
+
+---
+
 ## Input Variables vs Input Arguments
 
 These serve different purposes and apply to different scopes:
@@ -134,14 +178,14 @@ For `debug test-activity` and `debug start-from-here`, both `--input-arguments`
 
 ## Output Format
 
-`run` and `debug start` return a JSON envelope with `Data.runResult` as a JSON-encoded string. Parse `runResult` separately. It has exactly three fields:
+`run` and `debug start` return a JSON envelope with `Data.runResult` as a JSON-encoded string. Parse `runResult` separately:
 
 ```json
 {
   "Result": "Success",
   "Code": "ToolResult",
   "Data": {
-    "runResult": "{\"Output\":\"...\",\"HasErrors\":false,\"ErrorMessage\":null}"
+    "runResult": "{\"output\":\"...\",\"hasErrors\":false,\"errorMessage\":null,\"debugState\":\"Completed\",\"debugDetails\":null}"
   }
 }
 ```
@@ -150,26 +194,35 @@ Inside `runResult`:
 
 | Field | Type | Meaning |
 |-------|------|---------|
-| `Output` | `string` | Workflow's serialized output arguments JSON. `""` for non-`Start*` commands and on debug-command responses (`debug step-over`, `debug continue`, etc.). **Carries the workflow's data, not a verdict.** |
-| `HasErrors` | `bool` | `true` iff execution did not complete with `Succeeded` (compile failure, validation failure, unhandled exception, cancellation, timeout). `false` otherwise. |
-| `ErrorMessage` | `string?` | Formatted error chain when `HasErrors: true`; `null` otherwise. |
+| `Output` | `string` | Workflow's serialized output arguments JSON, populated when the run completes. **Carries the workflow's data, not a verdict.** |
+| `HasErrors` | `bool` | `true` iff execution finished without `Succeeded` (compile failure, validation failure, unhandled exception that ended the run, cancellation, timeout). `false` otherwise — including while `Suspended` on an exception, because the session is still alive and the outcome undecided. |
+| `ErrorMessage` | `string?` | Formatted error chain when `HasErrors: true`. On debug responses it may instead carry **guidance** (e.g. which commands apply in a `Suspended` state) with `HasErrors: false`. `null` otherwise. |
+| `DebugState` | `string?` | Debug sessions only (`null` on plain `run`): `Paused`, `Suspended`, `Running`, `Completed`, or `None`. See [The stable-state debug loop](#the-stable-state-debug-loop-headless). |
+| `DebugDetails` | `string?` | Debug sessions only: JSON snapshot for the state — current activity + locals when `Paused`; exception type/message/activity + locals when `Suspended`; `null` otherwise. |
 | `Profiling` | `object?` | Present only when `--profiling` was passed on a start command and collection succeeded. Single field `OutputDirectory` — absolute path to the run's `*.uistat` and screenshot folder (verifies UI automation correctness and workflow performance). `null` / omitted otherwise. See [Profiling Workflow Performance](#profiling-workflow-performance). |
 
 Workflow log output (`Log Message` activity, system traces) is **streamed in real time** during execution on a separate channel. It is NOT embedded in `runResult`.
 
-> **`Result` (outer) — equivalently `HasErrors` (inner) — is the only success/failure signal.** `Result: "Success"` already accounts for compile failures, validation failures, and unhandled runtime exceptions. **Do NOT use streamed log entries' `Level` as a failure signal** — workflow `Log Message` activities emit at any level, and successful runs commonly include `Error` / `Warning` entries from the workflow's own logging. Treating log levels as a verdict flips green runs to "failed".
+> **For completed runs, `Result` (outer) — equivalently `HasErrors` (inner) — is the only success/failure signal.** `Result: "Success"` already accounts for compile failures, validation failures, and unhandled runtime exceptions. **Do NOT use streamed log entries' `Level` as a failure signal** — workflow `Log Message` activities emit at any level, and successful runs commonly include `Error` / `Warning` entries from the workflow's own logging. Treating log levels as a verdict flips green runs to "failed". In an active debug session, check `DebugState` first: `Suspended` means an exception is waiting for your decision even though `HasErrors` is still `false`.
 
 Examples:
 
 ```jsonc
-// Successful run — workflow logged a warning, but HasErrors is false
-{ "Output": "{\"resultCode\":\"OK\"}", "HasErrors": false, "ErrorMessage": null }
+// Successful completed run — workflow logged a warning, but hasErrors is false
+{ "output": "{\"resultCode\":\"OK\"}", "hasErrors": false, "errorMessage": null, "debugState": "Completed", "debugDetails": null }
+
+// Failed completed run — compile or runtime failure ended the session
+{ "output": "", "hasErrors": true, "errorMessage": "Source: HttpRequest_1\nMessage: ...", "debugState": "Completed", "debugDetails": null }
 
-// Failed run — compile or runtime failure
-{ "Output": "", "HasErrors": true, "ErrorMessage": "Source: HttpRequest_1\nMessage: ..." }
+// Paused at a breakpoint — current activity + locals in debugDetails
+{ "output": "", "hasErrors": false, "errorMessage": null, "debugState": "Paused",
+  "debugDetails": "{\"Activity\":\"Assign x\",\"ActivityId\":\"1.5\",\"WorkflowFile\":\"...\\Main.xaml\",\"Locals\":{...}}" }
 
-// Debug-command response (`debug step-over` / `debug continue` / etc.) — empty success
-{ "Output": "", "HasErrors": false, "ErrorMessage": null }
+// Suspended on an exception — session alive, hasErrors still false, errorMessage carries guidance
+{ "output": "", "hasErrors": false,
+  "errorMessage": "Execution suspended on an unhandled exception; the session is still alive. Send Continue..., ContinueRetry..., ContinueIgnore..., or Stop...",
+  "debugState": "Suspended",
+  "debugDetails": "{\"ExceptionType\":\"System.InvalidOperationException\",\"Message\":\"...\",\"Activity\":\"Throw\",\"Locals\":{...}}" }
 ```
 
 ---
@@ -190,34 +243,40 @@ Examples:
 
 ### 1. Quick Breakpoint Debug Session
 
-The most common pattern: set a breakpoint on the focused activity, start debugging, inspect state, then continue or step through.
-
-> **Studio Desktop required** for activity-targeted breakpoints (the `focus-activity` step). Skip step 1 to set a workflow-level breakpoint instead — that path runs headless.
+The most common pattern: start debugging with breakpoints on the activities you suspect, inspect the state each pause returns, then step or continue. Runs fully headless — breakpoints are addressed by the activity's `IdRef` straight from the XAML, no focusing step.
 
 ```bash
-# 1. Focus the activity you want to break at (Studio Desktop only — skip to break at the workflow level)
-uip rpa focus-activity --activity-id "Assign_1"
-
-# 2. Toggle a breakpoint on the focused activity
-uip rpa debug toggle-breakpoint --output json
-
-# 3. Start debugging — execution pauses at the breakpoint
-uip rpa debug start --file-path "GetStockPrices.xaml" --output json
+# 1. Start debugging with a breakpoint — returns Paused at the breakpoint,
+#    with the current activity and locals in DebugDetails
+uip rpa debug start --file-path "GetStockPrices.xaml" \
+  --breakpoints 'workflowFile=GetStockPrices.xaml,activityIdRef=Assign_1' \
+  --output json
 
-# 4. Inspect the response: HasErrors / ErrorMessage / Output (workflow output args).
-#    Variable values seen during the run are observed via streamed log entries.
-# Then step through or continue:
+# 2. Read DebugDetails: current activity + variables/arguments/properties snapshot.
+#    Then step through — each call returns the next paused state with fresh locals:
 uip rpa debug step-over --output json
 
-# 5. When done, cancel the session
+# 3. Or run to the next breakpoint / completion:
+uip rpa debug continue --output json
+
+# 4. When done, cancel the session (skip if the last response was already Completed)
 uip rpa execution cancel --output json
 ```
 
+Conditional breakpoints and hit counts work the same way:
+
+```bash
+--breakpoints 'workflowFile=Main.xaml,activityIdRef=Assign_1,condition=count > 3'
+--breakpoints 'workflowFile=Main.xaml,activityIdRef=Click_2,hitCount:=3'
+```
+
+> On Studio Desktop, the interactive alternative is `focus-activity` + `debug toggle-breakpoint` (see [Studio Desktop vs headless](#studio-desktop-vs-headless)).
+
 ### 2. Test a Single Activity in Isolation
 
 Use `debug test-activity` to run just the currently focused activity without executing the entire workflow. Useful for verifying an activity works with specific inputs.
 
-> **Studio Desktop required** — `focus-activity` and `debug test-activity` both rely on it. On a headless-only setup, fall back to a workflow-level `debug start` with a breakpoint placed earlier in the file.
+> **Studio Desktop required** — `focus-activity` and `debug test-activity` both rely on it (headless rejects `debug test-activity`, and `focus-activity` silently no-ops). On a headless-only setup, fall back to `debug start --breakpoints 'workflowFile=<file>,activityIdRef=<IdRef>'` — pause right at the activity, inspect its inputs in `DebugDetails`, then step over it and check the result.
 
 ```bash
 # 1. Focus the activity to test (Studio Desktop required)
@@ -240,7 +299,7 @@ uip rpa debug test-activity \
 
 Use `debug start-from-here` to skip straight to the activity you care about, avoiding stepping through earlier activities.
 
-> **Studio Desktop required** — `focus-activity` and `debug start-from-here` both rely on it. On a headless-only setup, use plain `debug start` with a workflow-level breakpoint near the activity instead.
+> **Studio Desktop required** — `focus-activity` and `debug start-from-here` both rely on it (headless rejects `debug start-from-here`, and `focus-activity` silently no-ops). On a headless-only setup, use `debug start --breakpoints 'workflowFile=<file>,activityIdRef=<IdRef>'` — the run starts from the top, but pauses at the activity you care about with locals in hand.
 
 ```bash
 # 1. Focus the activity to start from (Studio Desktop required)
@@ -262,27 +321,28 @@ uip rpa execution cancel --output json
 
 ### 4. Exception Investigation
 
-When `debug continue` or a step verb hits an exception, the debugger pauses and returns the exception details. You can inspect the state, then decide how to proceed.
+When execution hits an unhandled exception in a debug session, the command that was running returns `DebugState: "Suspended"` — the session is alive and waiting for your decision. `DebugDetails` carries the exception type, message, faulting activity, and a locals snapshot.
 
 ```bash
-# Start debugging and continue to let it run
+# Start debugging — if an exception fires, the response comes back Suspended
 uip rpa debug start --file-path "MyWorkflow.xaml" --output json
-uip rpa debug continue --output json
 
-# If an unhandled exception occurs, HasErrors flips to true and ErrorMessage carries
-# the formatted exception chain (source activity, type, message, stack trace).
-# - Read ErrorMessage for the canonical failure diagnostic
-# - Cross-reference streamed log entries for variable state and trace context
-#   leading up to the failure
+# Inspect the Suspended response:
+# - debugDetails → exception type + message + faulting activity + locals at the fault
+# - hasErrors stays false — the outcome is not decided yet
+# - errorMessage carries the guidance on which commands apply
 
 # Then choose how to proceed:
 # Option A: Retry the failed activity (e.g., transient network error)
 uip rpa debug continue-retry --output json
 
-# Option B: Ignore the exception and continue past it
+# Option B: Ignore the exception and continue past it (pauses at the next activity)
 uip rpa debug continue-ignore --output json
 
-# Option C: Cancel and fix the root cause
+# Option C: Propagate the exception (the run fails; response is Completed with hasErrors: true)
+uip rpa debug continue --output json
+
+# Option D: Cancel and fix the root cause
 uip rpa execution cancel --output json
 ```
 
@@ -418,11 +478,12 @@ A practical example — a workflow makes an HTTP request and tries to deserializ
 
 - **Always use `--output json`** for debug verbs when you need to parse the output programmatically. The structured output makes it easy to inspect variables and identify exceptions.
 - **Set breakpoints strategically** — place them just before the activity you suspect is failing, not at the very start. This avoids stepping through dozens of unrelated activities.
-- **Use `focus-activity` before `debug toggle-breakpoint`** to target a specific activity by its IdRef — Studio Desktop required. Without focusing first, the breakpoint is set on whatever activity or workflow is currently focused, which on a headless-only run means the entire workflow.
+- **Prefer `--breakpoints` on `debug start`** — it targets specific activities by their XAML `IdRef` with no focusing step and runs headless. Use `focus-activity` + `debug toggle-breakpoint` only for interactive sessions on Studio Desktop.
+- **Never let a debug response go unread** — every command returns `DebugState`; branch on it (`Paused` → inspect and step, `Suspended` → decide on the exception, `Running` → poll `debug state` or `break`, `Completed` → read the run result).
 - **Use `debug test-activity` for quick feedback** — it runs a single activity in isolation, which is faster than debugging the entire workflow. Studio Desktop required (depends on `focus-activity`). Pre-set variables with `--input-variables` so the activity has the data it needs.
 - **Use `debug start-from-here` to skip setup** — when the bug is deep in the workflow, skip straight to the relevant activity instead of stepping through the entire flow. Studio Desktop required (depends on `focus-activity`). Pre-set variables with `--input-variables` to simulate the state the activity would have received from preceding activities.
 - **Prefer `debug step-over` for quick inspection** — it moves one activity at a time without descending into scopes. Use `debug step-into` only when you need to examine what happens inside a loop iteration or nested sequence.
-- **Check variables after each step** — read the streamed log entries (and workflow `Log Message` output) to see the current state of in-scope variables. The runResult itself only carries `Output` (workflow output args), `HasErrors`, and `ErrorMessage`.
+- **Check variables after each step** — every `Paused`/`Suspended` response carries a locals snapshot (in-scope variables, arguments, current activity properties) in `DebugDetails`; streamed log entries remain useful for values the workflow logged along the way.
 - **Use `debug continue-retry` for transient errors** — if the exception is a network timeout or rate limit, retrying may succeed without any code changes.
 - **Use `debug continue-ignore` cautiously** — it skips the exception, which may leave variables in an unexpected state for downstream activities.
 - **Cancel the session when done** — always issue `execution cancel` to cleanly end the run or debug session.

package/skills/uipath-rpa/references/environment-setup.md

@@ -171,7 +171,7 @@ Pass `--target-framework` and `--expression-language` here too (Rule 2a) — a t
 2. **Read the scaffolded files** — the command generates starter files. Read them before making changes so you build on valid defaults
 3. Proceed with the skill workflow using the new project root
 
-> **Batch the post-`init` prerequisites.** Step 2 here, the analyzer-rules list (SKILL.md Rule 3), `packages install` for known-needed packages, and the first `activities find` all depend only on the project existing — emit them as parallel tool calls in one message, not one per turn. They share the warmed Studio host. See SKILL.md § Call Batching.
+> **Batch the post-`init` prerequisites.** Step 2 here, `packages install` for known-needed packages, and the first `activities find` all depend only on the project existing — emit them as parallel tool calls in one message, not one per turn. They share the warmed Studio host. See SKILL.md § Call Batching.
 
 ## Edge case: requiring Studio Desktop
 
@@ -180,7 +180,7 @@ Two `uip rpa` commands need a running Studio Desktop instance — they have UI s
 | Command | Why it needs Studio |
 |---------|---------------------|
 | `uip rpa files diff` | Opens an interactive diff window in Studio's UI; finishes when the user closes the window. |
-| `uip rpa focus-activity` | Selects/highlights an activity in Studio's active workflow designer. |
+| `uip rpa focus-activity` | Selects/highlights an activity in Studio's active workflow designer. ⚠️ Against headless it **silently succeeds without doing anything** (there is no designer) — a `success: true` from a headless session does NOT mean anything was focused. |
 
 When (and only when) you need to run one of these, ensure Studio Desktop is up:
 

package/skills/uipath-rpa/references/ui-automation-guide.md

@@ -33,7 +33,7 @@ When the source is a Test Manager test case, a PDD, or any written list of "Clic
 2. **Group by screen state.** Sort steps into screen batches — every step before an action that advances the UI (submit, navigate, dialog confirm) belongs to the current screen; the next batch starts after the advance.
 3. **Build the checklist** — three columns per row: `manual step → element name → screen`. Lock the count before opening the app. If the user later adds requirements, capture deltas, do not re-inventory the whole thing.
 4. **Capture screen by screen.** Pre-flight Window Baseline (above) → run `uia-configure-target` for the current screen's batch → register each element in the Object Repository before advancing → use the UIA interact CLI to advance → repeat. The "Complete-then-advance" rule from [uia-configure-target-workflows.md § Multi-Step UI Flows](uia-configure-target-workflows.md) is mandatory; never advance with elements still un-registered.
-5. **Then code.** With every checklist row registered in the Object Repository, write the `.cs` / `.xaml` workflow that calls them in step order. Authoring-phase prerequisites (analyzer rules, project context discovery) run NOW, not earlier.
+5. **Then code.** With every checklist row registered in the Object Repository, write the `.cs` / `.xaml` workflow that calls them in step order. Authoring-phase prerequisites (project context discovery) run NOW, not earlier.
 
 > Coverage check: after capture, every checklist row must have a matching `Descriptors.<App>.<Screen>.<Element>` path (coded) or Object Repository reference (XAML). Rows without a match indicate a missed capture or an obsolete manual step — reconcile before writing code.
 
@@ -274,7 +274,7 @@ Install the UI Library as a package dependency; its descriptors appear under **U
 
 ## Running UI Automation Workflows
 
-**Always use `uip rpa debug start`** (not `uip rpa run`) when running workflows with UI automation. A debug session pauses on error instead of tearing down the application, leaving the UI state available for inspection.
+**Always use `uip rpa debug start`** (not `uip rpa run`) when running workflows with UI automation. A debug session pauses on error instead of tearing down the application, leaving the UI state available for inspection. The command returns as soon as that happens — `DebugState: "Suspended"` with the exception and locals in `DebugDetails` — so act on the response instead of waiting for the run to end (see [debugging.md § The stable-state debug loop](debugging.md#the-stable-state-debug-loop-headless)).
 
 **Every debug run** must follow this procedure to prevent stale windows from accumulating or being reused in a dirty state:
 
@@ -293,6 +293,16 @@ Install the UI Library as a package dependency; its descriptors appear under **U
 
 Skipping steps 4-5 causes the next run's open-if-not-open behavior to reuse a stale window in whatever state it was left in, or -- if the selector doesn't match -- to spawn a duplicate instance.
 
+### Advanced Debugging — Profiling
+
+For advanced debugging, add `--profiling` to collect insightful per-activity execution data, timings, and before- and after-execution screenshots:
+
+```bash
+uip rpa debug start --file-path "<FILE>" --project-dir "<PROJECT_DIR>" --output json --profiling
+```
+
+Use the before-execution screenshot to confirm the application/element started in the correct state, and the after-execution one to validate the expected outcome. Each screenshot's filename is recorded in the run's `.uistat` file; the image sits in the `Screenshots` folder in the same directory as that `.uistat` file. See [debugging.md § Profiling Workflow Performance](debugging.md#profiling-workflow-performance) for details.
+
 ### Runtime Selector Failure Recovery
 
 "UI element not found", "UI element is invalid", element not on screen -- these surface at runtime, not during static validation. They occur when a selector was captured against one app state but the DOM changed by the time the activity executes.

package/skills/uipath-rpa/references/uia-prerequisites.md

@@ -1,10 +1,10 @@
 # UiAutomation Prerequisites
 
 **Required package:** `UiPath.UIAutomation.Activities`
-**Minimum version (`<MIN_VERSION>`):** `26.4.1-preview`
-**Source feed:** the official UiPath NuGet feed — the same feed Studio resolves by default. Prerelease / preview builds of `UiPath.UIAutomation.Activities` are published there alongside stable releases. Installing them is a normal supported path, not a third-party workaround.
+**Minimum version (`<MIN_VERSION>`):** `26.10.0`
+**Source feed:** the official UiPath NuGet feed — the same feed Studio resolves by default.
 
-> **Prerelease required.** `<MIN_VERSION>` is a preview — stable releases of `UiPath.UIAutomation.Activities` do NOT yet ship the `uia-configure-target` skill content. Install the prerelease build explicitly. `uip rpa packages versions` MUST be invoked with `--include-prerelease` (the flag defaults to `false`), otherwise the required preview is filtered out of the listing and the agent will report "no upgrade available" against a feed that actually has it.
+> **Stable release.** `<MIN_VERSION>` is a stable GA build — it ships the `uia-configure-target` skill content and resolves from the official feed without any prerelease flag. Querying with `--include-prerelease` is still fine (it surfaces newer preview builds), but it is not needed to reach `<MIN_VERSION>`.
 
 The `uip rpa uia` CLI used by `uia-configure-target` requires `UiPath.UIAutomation.Activities` at `<MIN_VERSION>` or newer. Before configuring any target, check the installed version in `project.json` under `dependencies`.
 
@@ -17,10 +17,10 @@ Never upgrade UIA silently. Every upgrade requires explicit user consent before
 
 | Scenario | Behavior |
 |---|---|
-| No UIA installed, request needs UIA | Ask before installing `<MIN_VERSION>`. Disclose that it is a prerelease build from the official UiPath feed. |
+| No UIA installed, request needs UIA | Ask before installing `<MIN_VERSION>` from the official UiPath feed. |
 | Major-version upgrade (e.g. `25.x` → `26.x`) | Ask. Note that breaking changes are possible across major versions. |
-| Minor-version upgrade (e.g. `26.3.x` → `26.4.x`) | Ask. Note that the minimum required for `uia-configure-target` is a preview. |
-| Patch / build upgrade within the preview band | Ask before installing the newer preview build. |
+| Minor-version upgrade (e.g. `26.4.x` → `26.10.x`) | Ask before installing the newer build. |
+| Patch / build upgrade within the `26.10.x` band | Ask before installing the newer build. |
 | Already at or above `<MIN_VERSION>` | Proceed without prompting. |
 
 If the user declines, do NOT install. Warn that `uip rpa uia` commands will fail without UIA at `<MIN_VERSION>` and fall back to indication authoring — [uia-configure-target-workflows.md](uia-configure-target-workflows.md) MUST be read IN FULL first (see § Indication Fallback). Record `UI capture: indication-only` in the plan header so downstream tasks do not route to `uia-configure-target`.
@@ -39,4 +39,4 @@ Install / upgrade (mutating — only after consent per the table above; substitu
 uip rpa packages install --packages 'id=UiPath.UIAutomation.Activities,version=<MIN_VERSION>' --project-dir "$PROJECT_DIR" --output json
 ```
 
-`packages install` accepts the beta version directly via the `version` field — no separate prerelease flag is needed once the version string is specified explicitly.
+`packages install` resolves `<MIN_VERSION>` directly via the `version` field — no prerelease flag is needed, since it is a stable release. Omit `,version=<MIN_VERSION>` to resolve the latest compatible build (which will be at or above `<MIN_VERSION>`).

package/skills/uipath-rpa/references/validation-guide.md

@@ -2,23 +2,20 @@
 
 Fix-one-thing discipline, the validation iteration loop, smoke test procedure, and RPA-specific fix procedures.
 
-## Pre-generation: List Analyzer Rules
+## On demand: List Analyzer Rules
 
-Before creating or editing any workflow file (`.cs` with `[Workflow]`/`[TestCase]`, or `.xaml`), list the enabled Workflow Analyzer rules so generated code satisfies them on the first attempt instead of round-tripping through `validate` fixes:
+`validate` and `build` already enforce the project's enabled Workflow Analyzer rules — violations come back with the rule ID, severity, and recommendation, so the normal authoring loop needs **no** rule pre-fetch. Do NOT run `analyzer-rules list` as an authoring prerequisite: the unscoped call enumerates every rule across every package and can take a minute or more, and most of its output never affects the code you write.
 
-```bash
-uip rpa analyzer-rules list --project-dir "<PROJECT_DIR>" --output json
-```
+Run it **only on demand**:
 
-Apply every rule whose `severity` is `error` or `warning` during authoring. `info` rules are advisory.
+1. The **user asks** about the project's best-practice / analyzer rules ("what rules does this project enforce?", "list the analyzer rules", "why is UI-REL-001 firing?").
+2. **Repeated violations of the same rule family** across `validate`/`build` iterations — reading the full rule set (scoped, see below) lets you author against it instead of fixing violations one by one.
 
-**When to run:**
-1. Once at the start of every task that will generate or edit a workflow file.
-2. Re-run after adding or updating a NuGet package — package-shipped rules (`MA-*`) change with the dependency set.
+```bash
+uip rpa analyzer-rules list --project-dir "<PROJECT_DIR>" --scope "<Activity|Workflow|Coded Workflow|Project>" --output json
+```
 
-**When NOT to run:**
-1. Pure read-only / Q&A tasks that do not produce or modify workflow files.
-2. Edits that only touch non-workflow files (`project.json`, docs, plain `.cs` source files without workflow attributes).
+Prefer a `--scope` matching what you're authoring — scoped calls return in seconds; unscoped can take a minute+. Apply `error` and `warning` rules; `info` rules are advisory. If you do consult the rules and then add or update a NuGet package, the package-shipped (`MA-*`) rules may have changed with the dependency set.
 
 Rule prefixes and full schema: [cli-reference.md § analyzer-rules list](cli-reference.md).
 

package/skills/uipath-solution/references/scenarios/manual-edits.md

@@ -64,7 +64,7 @@ Open the file. The shape is roughly:
 | `resource.runtimeDependencies` | Recomputed at every pack — manual edits lost on next pack |
 | `resource.files`, `resource.locks` | Managed; never appear in user-edit scenarios |
 | `resource.folders` | Moves the resource. For a *cloud-imported* resource the folder is `solution_folder` (placeholder) — editing it doesn't change cloud location, only confuses sync. For a *virtual* resource that you authored at a non-`solution_folder` folder, edit at the binding (`bindings_v2.json`) and let refresh re-create — don't edit the resource file directly |
-| `resource.spec.<reference-fields>` | E.g. `storageBucketReference`, `retentionBucketRef`. The SDK rewrites these when the target's link state changes; hand-edits get clobbered. (Also see [SOL-7051](https://uipath.atlassian.net/browse/SOL-7051) — the rewrite isn't always applied automatically; that's a known bug, not a license to hand-edit dependents arbitrarily) |
+| `resource.spec.<reference-fields>` | E.g. `storageBucketReference`, `retentionBucketRef`. The SDK rewrites these when the target's link state changes; hand-edits get clobbered. (Known bug: the rewrite isn't always applied automatically - that's not a license to hand-edit dependents arbitrarily) |
 
 ### Examples — safe edits
 
@@ -123,7 +123,7 @@ Same principle, looser rules. The deploy config is **per-deployment**, not per-s
 
 **Manual editing of the deploy config is not ideal** — there's no schema validation in the CLI, and a bad edit fails server-side at `deploy run` (often with a generic `ValidationFailed`). But it's the pragmatic escape hatch when:
 
-- You need to set a nested property `config set` doesn't expose (e.g. `configuration.storageBucketReference.key` to work around [SOL-7051](https://uipath.atlassian.net/browse/SOL-7051)).
+- You need to set a nested property `config set` doesn't expose (e.g. `configuration.storageBucketReference.key` to work around the reference-field rewrite bug noted above).
 - You're scripting a config transform (CI step injecting per-environment secrets, etc.) and want a single JSON-patch step instead of N CLI calls.
 - The CLI surface is missing a flag for the field you need.