@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-troubleshoot/references/activity-packages/cv-activities/investigation_guide.md

@@ -0,0 +1,43 @@
+# Computer Vision (CV) Activities Investigation Guide
+
+## Data Correlation
+
+Before using any fetched data, verify it matches the user's reported problem:
+
+- **Activity** — the faulted activity's namespace and class match the reported failure (e.g., `UiPath.CV.Activities.CvClickWithDescriptor`). CV Click / CV Type Into / CV Get Text / CV Element Exists run different post-find paths; the scope (`CVScope`) faults before any of them. Don't treat one CV activity's evidence as another's.
+- **Display names are narrative, not evidence** — activity display names, process names, and workflow comments describe intent; they never confirm or eliminate a hypothesis. Decide from exception type, message text, the `*_ComputerVision` runtime dump, traces, and output values. Repro/test workflows carry display names that assert a cause — weigh only the recorded behavior.
+- **Descriptor target** — the descriptor target/anchors in evidence are the ones the user reports (the same friendly/label text, the same table cell). A descriptor copied from a different activity or workflow is different evidence. Confirm whether the descriptor is recorder-captured, a variable, or programmatically built — it routes invalid-descriptor causes.
+- **Scope (`CVScope`)** — the enclosing scope in evidence is the one wrapping the reported activity, with the same `Server` / `UseLocalServer` / `OCREngine` / `CvMethod` / `Target` config. A different scope = a different session, a different target window, a different server = unrelated data.
+- **Workflow file** — if the project has multiple workflows, the error originates from the workflow the user is asking about, not a different `.xaml` / `.cs` using the same CV activity.
+- **Timestamp** — the failure occurred during the time window the user reported. The `*_ComputerVision` dump and traces are timestamped; match the dump to the failed run. Load-bearing whenever the screen, window state, or server health may have changed between runs.
+
+If the data doesn't match: **discard it**. Do NOT use unrelated data as a proxy. Report the mismatch and ask for clarification.
+
+## Cross-Cutting Error Classes
+
+Many CV failures are **not specific to one activity** — they come from the shared session/server/find layer and can surface from any CV activity. The exception **type** plus the **message text** is the primary router (server errors all share `System.ArgumentException`; `ElementNotFoundException` covers plain not-found, scroll-exhausted, and cell sentences). The leading `[Error code: <N>]` is informational — match the text, not the HTTP digits. When the class is cross-cutting (server/auth/throttle), investigate the scope/server/network rather than over-focusing on the faulted activity's descriptor.
+
+Route by message / signature:
+
+- `Element not found` (`UiPath.CV.ElementNotFoundException`), or `CV Element Exists` returning `false`, after a find attempt → [cv-element-not-found](./playbooks/cv-element-not-found.md).
+- `Scrolled the entire screen, but element was not found` (`ElementNotFoundException`, `ScrollDirection != None`) → [cv-scroll-search-failures](./playbooks/cv-scroll-search-failures.md).
+- A cell sentence — `Could not find table. Cell targeting supports only tables as target`, `Invalid column number <n>`, `Table only contains <count> columns and column number is <n>`, `Invalid row number <n>`, `No row in column <c> had a text containing <v>`, etc. (`ElementNotFoundException`, descriptor targets a cell) → [cv-cell-targeting-failures](./playbooks/cv-cell-targeting-failures.md).
+- `Invalid Descriptor` / `Reason: Target must be set` / `Reason: Invalid image reference or value` (`UiPath.CV.InvalidDescriptorException`, thrown before any find) → [cv-invalid-descriptor](./playbooks/cv-invalid-descriptor.md).
+- `[Error code: 401]` auth, `[Error code: 403]`/5xx unreachable, `[Error code: 429]` throttling, `[Error code: 413]` payload, OCR word limit (cloud `The ComputerVision server has hit the maximum number of words...` or local `UiPath.ComputerVision.LocalServer has hit the maximum number of words...`), `Error while sending request.` / `Response from server is not valid.` transport (`System.ArgumentException`, on a child's first refresh) → [cv-server-auth-throttling-network](./playbooks/cv-server-auth-throttling-network.md).
+- Fault **at scope entry** before any child ran — `Please make sure you have UiPath.ComputerVision.LocalServer package installed...`, `Server or OCR engine is required.`, `The target Element was not specified for this activity.`, AVX2 / VC++ local-server prerequisites, `Activity is valid only inside a CV Screen Scope` → [cv-scope-setup-failures](./playbooks/cv-scope-setup-failures.md).
+- Element **was found**, then a raw driver/`COMException`, `Value cannot be null. (Parameter 'Secure')`, or an unwrapped non-CV exception on the click/type → [cv-action-failed-after-find](./playbooks/cv-action-failed-after-find.md).
+- `CV Get Text` returned empty / `null` / stale / partial / wrong text **without faulting** → [cv-get-text-empty-or-wrong-result](./playbooks/cv-get-text-empty-or-wrong-result.md).
+- **No exception** but wrong/empty/default output, false-positive/negative `CV Element Exists`, `OutRegion = (0,0,0,0)`, `ContinueOnError`/`InRegion` suppression → [cv-silent-failures-and-false-results](./playbooks/cv-silent-failures-and-false-results.md).
+
+## Testing Prerequisites
+
+When testing hypotheses for Computer Vision Activities issues, gather and verify these before drawing conclusions:
+
+1. **Activity identity and properties** — capture the class name and display name from the workflow source or stack trace, plus the input properties that address the target: `Descriptor` (and whether it targets a cell — `Target.CellExtraInfo`), `MethodType` (CV Get Text: OCR vs `ClipboardRow`/`ClipboardAll`), `Text` (CV Type Into), `RefreshBefore`, `ScrollDirection` / `NumberOfScrolls` / `DelayScreenshotAfterScroll`, `DelayBefore`. The playbook will name the subset that matters.
+2. **Package version** — `UiPath.ComputerVision.Activities` version, and the activity's `Version` / `FeatureVersion` property. `Version < V3` disables cell targeting; messages, friendly mappings, and behavior shift across versions.
+3. **`TimeoutMS`** — the configured find timeout. Timeout expiry surfaces as `ElementNotFoundException`, not a timeout type. Note: the `Scroll = true` scrollable-extraction phase and scroll-reset are NOT bounded by `TimeoutMS`.
+4. **`ContinueOnError`** — on the failing activity AND on the enclosing `CVScope`. Either being `true` suppresses every exception to a default output and enables the whole silent-failure class.
+5. **`InRegion`** — whether it is bound. A set `InRegion` bypasses descriptor matching and screen analysis entirely (false-positive Exists, wrong-coordinate clicks); trace whether its source is stale.
+6. **Scope config: server URL vs LocalServer** — read the enclosing `CVScope`: `Server`+`ApiKey` (cloud) vs `UseLocalServer` (local server), `OCREngine`, `CvMethod`, `ScrollOffset`, `Target` selector + `WaitForReady`. Also check **project settings** — `UseLocalServer`, `Server`, and `CvMethod` can be set there and override empty scope-level values. For LocalServer, confirm the package on the **failing** machine, not the dev machine.
+7. **Run timestamp** — exact time the activity executed. Required to match the `*_ComputerVision` dump and traces to the failed run, and for any investigation where the screen, window state, or server health changed between runs.
+8. **Runtime dump `*_ComputerVision` JSON availability** — locate the timestamped dump written by `RuntimeDumpInfoService` just before a find throws (or swallows) `ElementNotFoundException`. It captures the descriptor, scraped/detected text, detected elements, detected tables, the selector, and the screenshot at failure time — the primary forensic artifact distinguishing "UI changed" from "screen blank" from "OCR degraded". A dump exists only when the **find** failed; its absence with a faulted activity means the failure was after the match (action path) or before it (descriptor/scope).

package/skills/uipath-troubleshoot/references/activity-packages/cv-activities/overview.md

@@ -0,0 +1,57 @@
+# Computer Vision (CV) Activities
+
+Activities from the `UiPath.ComputerVision.Activities` package. They target UI elements by **visual analysis of a screenshot** instead of selectors — built for virtualized/Citrix/RDP, image-based, and remote desktops where standard selectors are unavailable. Every CV activity runs inside a **CV Screen Scope** (`CVScope`) container that resolves the target window and builds a CV session; the analysis itself runs on a CV server (cloud or local) plus an OCR engine.
+
+## How CV Targeting Works
+
+1. **Screenshot.** The scope captures a screenshot of the target window (a clipped clone of the scope root element).
+2. **CV server analysis.** The screenshot is sent to the CV server (`Server`+`ApiKey` cloud endpoint, or `UseLocalServer` local server). The server detects UI elements (controls, text via OCR, tables) and returns their regions.
+3. **Descriptor matching with anchors.** The activity's `Descriptor` (a target + optional anchors) is matched against the detected elements. `Anchor2Service` locates the target and each anchor individually, then validates the **geometric relationship** between them — a match requires both the elements and their relative positions to hold.
+4. **Action at screenshot-derived coordinates.** The matched region yields **coordinates**, not a live element. The activity clicks / types / reads text at those coordinates with hardware events forced (`SimulateClick`/`SimulateType`/`SendWindowMessages` are disabled internally). Because it acts on coordinates, anything that moves the window between analysis and action lands the action in the wrong place.
+
+The find runs with retries until `TimeoutMS`; `ScrollDirection != None` adds scroll-search (scroll + re-analyze). Failures originate at any layer — scope setup, server analysis call, descriptor matching, or the post-find action — and knowing which layer threw narrows the investigation.
+
+## Key Activity Types
+
+| Display Name | Class Name |
+|---|---|
+| CV Screen Scope | `CVScope` |
+| CV Click | `CvClickWithDescriptor` |
+| CV Type Into | `CvTypeIntoWithDescriptor` |
+| CV Get Text | `CvGetTextWithDescriptor` |
+| CV Element Exists | `CvElementExistsWithDescriptor` |
+
+`CV Element Exists` is special: it catches `ElementNotFoundException` internally and returns `Result = false` rather than faulting. Server, descriptor, and scope errors still throw from it.
+
+## Exception Types
+
+- **`UiPath.CV.ElementNotFoundException`** — the descriptor (target/anchors) did not match within `TimeoutMS`. Message is usually the literal `Element not found`. **Timeout expiry surfaces as this type, NOT `TimeoutException`** — there is no separate timeout exception. The scroll-exhausted variant (`Scrolled the entire screen, but element was not found`) and the nine cell-targeting sentences are also this type.
+- **`UiPath.CV.InvalidDescriptorException`** — the `Descriptor` argument is null-`Target`, has broken image references, or failed to parse/evaluate. Thrown **before any find attempt**, synchronously when the activity resolves the descriptor.
+- **`System.ArgumentException`** — CV **server** errors. Built by `CVSessionData.Compute` via `cvData.ToErrorMessageWithCode()` when the analysis response is null, carries an `Error`/`LocalServerError`, or has `OCRWordLimitPassed = true`. Carries `[Error code: <N>]` text — auth (401), unreachable/forbidden (403/5xx), throttling (429), payload too large (413), OCR word limit. Also the type for the local-server-package-missing scope-setup error.
+
+## Common Failure Patterns
+
+### Find (descriptor matching)
+
+- **Element not found** — `ElementNotFoundException` / `Element not found` after the retry loop exhausts `TimeoutMS`. UI changed since design time, wrong screen state, broken anchor geometry, DPI/scale mismatch, scope refresh failure, or silent OCR degradation.
+- **Invalid descriptor** — `InvalidDescriptorException`. Null `Target`, image references unresolvable across copied descriptors, or expression parse failure. Mostly hits programmatically built / copied / hand-edited descriptors, not recorder-captured ones.
+- **Cell-targeting failures** — `ElementNotFoundException` carrying one of nine cell-specific sentences (`Could not find table...`, `Invalid column number <n>`, `Table only contains <count> columns...`, `No row in column <c> had a text containing <v>`, etc.). Table not detected, index out of range / `< 1` (1-based), name/value mismatch, or old `FeatureVersion` (< V3) with cell targeting disabled.
+- **Scroll-search failures** — `Scrolled the entire screen, but element was not found`. Wrong scroll axis, scroll point off the scrollable pane, `NumberOfScrolls` too large, silent scroll skip on a non-driver scope root, or genuine absence.
+
+### Server (analysis call)
+
+- **Auth / unreachable / throttling / payload / word-limit / network** — `System.ArgumentException` with `[Error code: <N>]` text. 401 auth, 403/5xx unreachable, 429 rate limit, 413 payload, OCR word limit, or transport (`Error while sending request.` / masking `Response from server is not valid.`). Surfaces lazily on the first child activity's first refresh, not at scope entry.
+
+### Scope (setup)
+
+- **Scope setup failures** — fault at scope entry before any child runs: LocalServer package missing, scope window selector did not resolve, root element selector unreadable (`COMException` → `The target Element was not specified for this activity.`), missing server/OCR config, AVX2/VC++ local-server prerequisites, design-time placement constraints.
+
+### Silent (no fault)
+
+- **Silent failures / false results** — no exception, wrong/empty/default output. `ContinueOnError = true` swallows every exception to a default; `InRegion` bypasses CV entirely (false-positive Exists, wrong-coordinate clicks); `CV Element Exists` converts infrastructure failures to `Result = false`; `CvMethod` disables a detection family.
+- **Action failed after find** — element found, then the click/type failed: window moved (stale coordinates), focus stolen, input blocked (locked/RDP/UAC), null `SecureString` (`Value cannot be null. (Parameter 'Secure')`), or an unwrapped non-CV exception.
+- **Get Text empty/stale/wrong** — `CV Get Text` returned without fault but text is empty/stale/partial/wrong: silent OCR scrape failure, stale OCR cache (`RefreshBefore = false`), region clipping, OCR language mismatch, or clipboard mode on a non-editable target.
+
+## Package
+
+NuGet: `UiPath.ComputerVision.Activities`

package/skills/uipath-troubleshoot/references/activity-packages/cv-activities/playbooks/cv-action-failed-after-find.md

@@ -0,0 +1,100 @@
+---
+confidence: medium
+---
+
+# CV — Click/type failed after the element was found (focus, stale coordinates, blocked input, SecureString)
+
+## Context
+
+The CV match **succeeded** — the descriptor resolved to a region — but the subsequent click or keystroke failed or landed in the wrong place. CV activities click/type at screenshot-derived coordinates on a clipped clone of the scope root, with hardware events forced (`SimulateClick`/`SimulateType`/`SendWindowMessages` are disabled internally). Anything that moves the window or steals focus **between analysis and action** clicks/types in the wrong place — often with **no error** — or surfaces a raw driver/COM exception that carries **no CV resource key**.
+
+Affected activities: **CV Click** (`CvClickWithDescriptor`), **CV Type Into** (`CvTypeIntoWithDescriptor`), and **CV Get Text** (`CvGetTextWithDescriptor`) in clipboard mode (`MethodType = ClipboardRow`/`ClipboardAll`, which click + select + Ctrl+C).
+
+What this looks like — match on the symptom class, not a single string:
+
+- **A driver/COM exception with NO `UiPath.CV.*` type and NO CV resource key.** The message is passed through verbatim from the UI driver (`COMException` / `UiNode`-level errors out of `UiElement.Click_Normalized` / `WriteText`). There is no `Element not found`, no `Invalid Descriptor` — the find already passed. `UninitializedNodeException` is remapped to `ElementNotSetException` (`The target Element was not specified for this activity.`).
+- `Value cannot be null. (Parameter 'Secure')` — **CV Type Into only.** `ArgumentNullException` on parameter name `Secure`. Thrown before any keystroke when `Text` is a secure `CvString` built from a **null** `SecureString`.
+- An exception with its **original type and message preserved** (e.g. `InvalidOperationException`), unwrapped from the find task. CV unwraps and rethrows the find task's inner exception as-is — a non-CV type here is the underlying fault, not a CV error.
+- **No error at all** — the click/type/clipboard read appeared to run, but the wrong control was hit, the field stayed empty, or `OutRegion`/`Result` is empty/`null`/stale. CV Click's `OutRegion` comes back `(0,0,0,0)` (`Rectangle.Empty`); clipboard-mode CV Get Text returns `null` or stale text. Clicks, selection keystrokes, and the clipboard read all swallow `COMException` internally — a failed action still "succeeds."
+
+What can cause it (ordered most → least common in unattended/RDP fleets):
+
+- **Window moved/resized/redrawn between analysis and action.** CV clicks **coordinates**, not a live element. Any reflow, popup, animation, or focus shift after the screenshot moves the target out from under the resolved rectangle. The click/keystroke lands on whatever is now there — usually **no error**.
+- **Input blocked / no interactive desktop.** Hardware events require an interactive, unlocked, foreground desktop. Locked session, RDP window minimized, secure desktop (UAC consent prompt), or another `SetForegroundWindow` race blocks or misroutes the input. Surfaces as a raw driver/COM exception **or** silently does nothing.
+- **Focus stolen between find and type/Ctrl+C.** Another window grabbed focus after the match; keystrokes (or the clipboard select+copy) go to the wrong window. Clipboard mode degrades **silently** to empty/stale `Result`.
+- **Null `SecureString` (CV Type Into).** `Text` bound to a secure string that was never assigned — e.g. an upstream Get Credential failed and was ignored. Deterministic `ArgumentNullException(Secure)`. Plain-text `null` is **safe** (coalesced to empty), so this is secure-input only.
+- **Clipboard mode on a non-editable target.** The Ctrl+C selection sequence only works on keyboard-selectable editable text. On a label/static target it selects nothing; `Result` is empty with no error. Design-time raises the warning `The Select methods only work on editable text...`.
+- **Malformed special-key sequence in `Text` (CV Type Into).** Unbalanced `[k(...)]` syntax surfaces from `WriteText` as a driver-level error, not a CV error.
+
+> **Different cause, do not apply this playbook:**
+> - `Element not found` / `Scrolled the entire screen, but element was not found` (`UiPath.CV.ElementNotFoundException`) — the find itself failed; the action was never reached. Use [./cv-element-not-found.md](./cv-element-not-found.md) (and [./cv-scroll-search-failures.md](./cv-scroll-search-failures.md) for the scroll variant).
+> - `Invalid Descriptor` / `Target must be set` / `Invalid image reference or value` (`UiPath.CV.InvalidDescriptorException`) — thrown before any find. Use [./cv-invalid-descriptor.md](./cv-invalid-descriptor.md).
+> - Server/auth/throttling errors (`System.ArgumentException` carrying a server error code, 401/403/429/5xx, OCR word limit) raised during a session refresh — find-pipeline failure, not the action. Use [./cv-server-auth-throttling-network.md](./cv-server-auth-throttling-network.md).
+> - `Activity is valid only inside a CV Screen Scope`, or scope-setup faults (local-server prerequisite, scope window selector not found) — the scope never started, so no find/action ran. Use [./cv-scope-setup-failures.md](./cv-scope-setup-failures.md).
+> - `The target Element was not specified for this activity.` **at scope entry, before any child ran** (the faulted activity is the `CV Screen Scope`, not a child) — the scope-side variant, remapped from a root-selector `COMException` or a null scope `Target`. Use [./cv-scope-setup-failures.md](./cv-scope-setup-failures.md). This playbook's variant of the same message fires only **after** a child's find succeeded.
+> - CV Get Text returns empty/stale text in **OCR mode** (no clicks/clipboard involved) — different mechanism. Use [./cv-get-text-empty-or-wrong-result.md](./cv-get-text-empty-or-wrong-result.md).
+> - General `ContinueOnError`/`InRegion` silent-result traps not specific to a post-find action: [./cv-silent-failures-and-false-results.md](./cv-silent-failures-and-false-results.md).
+
+## Investigation
+
+1. **Confirm the find succeeded.** A timestamped `*_ComputerVision` runtime dump JSON is written **only** when the find throws `ElementNotFoundException`. If no such dump exists for this run but the activity still faulted/misbehaved, the failure is **after** the match — this playbook applies. If the dump exists, route to [./cv-element-not-found.md](./cv-element-not-found.md).
+2. **Read the exception type.** If it is `UiPath.CV.*` (`ElementNotFoundException`, `InvalidDescriptorException`) or a `System.ArgumentException` with a server code, leave this playbook (see routing block). A raw `COMException` / driver / `ElementNotSetException` / `ArgumentNullException(Secure)`, or an unwrapped non-CV type, stays here.
+3. **For `Value cannot be null. (Parameter 'Secure')`:** confirm the activity is CV Type Into and the `Text` argument is a secure string. This is Branch A — deterministic, no further screen investigation needed.
+4. **Determine if there was an exception at all.** No exception + wrong/empty result + `ContinueOnError = false` ⇒ the action ran but missed (Branch B/C silent path). Check `OutRegion` (CV Click: `(0,0,0,0)` = swallowed failure or `ContinueOnError`) and `Result` (CV Get Text clipboard: `null`/stale).
+5. **Check `ContinueOnError`.** If `true`, exceptions are suppressed and outputs stay at defaults — a "successful" run can hide a driver failure. Inspect execution logs for traced-but-swallowed `COMException`/driver exceptions. Do not trust the result while `ContinueOnError = true`.
+6. **Reconstruct the screen/window state at action time.** From logs, screenshots, and environment: was the session interactive and unlocked? Was the target window foreground, not minimized, not on another desktop? Did a popup/UAC prompt/animation fire between analysis and action? Unattended + RDP + locked/disconnected session is the dominant pattern.
+7. **For clipboard-mode CV Get Text:** confirm `MethodType` (`ClipboardRow`/`ClipboardAll`) and whether the target is an editable input box. Check the design-time warning `The Select methods only work on editable text...`. A non-editable target yields empty `Result` silently.
+8. **For CV Type Into driver faults:** inspect `Text` for unbalanced `[k(...)]` special-key syntax before blaming the environment.
+
+## Resolution
+
+Walk the branches; pick the first whose evidence holds. Name the evidence that rules a branch **out** — do not recommend a fix the evidence does not support.
+
+### Branch A — Null `SecureString` (CV Type Into)
+
+**Evidence.** `System.ArgumentNullException`, parameter `Secure`, message `Value cannot be null. (Parameter 'Secure')`; the activity is `CvTypeIntoWithDescriptor` and `Text` is a secure string. Thrown before any keystroke. **Ruled out** if the type is not `ArgumentNullException` or the parameter is not `Secure` — plain-text `null` never throws this (it coalesces to empty), so do not chase this branch for a non-secure `Text`.
+
+**Fix.** Ensure the `SecureString` is populated before the activity runs. Trace the upstream source (Get Credential / asset / orchestrator credential) — a failure there that was ignored leaves the variable null. Fix the credential retrieval; do not work around it by switching to plain text for a secret. *(Edits the workflow — see Post-presentation actions.)*
+
+### Branch B — Stale coordinates: window moved/redrew between analysis and action
+
+**Evidence.** No exception (or a driver exception), and the action hit the wrong place or did nothing. Logs/screenshots show the target window moved, resized, scrolled, or a popup/animation rendered after the CV analysis. Common with dynamic web pages, async-loading panels, and notification toasts. **Ruled out** if the window was provably static (no reflow, single static dialog) — then look at Branch C (focus/input).
+
+**Fix.** Stabilize the screen before the action so coordinates stay valid: add a wait/`Element Exists`-style settle before the CV activity, increase `DelayBefore` so the screen quiesces before the find, disable animations/transitions on the target app, and avoid reusing a stale `InRegion`/`OutRegion` rectangle from an earlier activity after the screen has changed. *(Edits the workflow — see Post-presentation actions.)*
+
+### Branch C — Input blocked or focus stolen (no interactive/foreground desktop)
+
+**Evidence.** Raw driver/`COMException` out of the click/type, **or** silent no-op, on an **unattended/RDP** robot. Session was locked, RDP window minimized, a UAC/secure-desktop prompt was up, or another process grabbed foreground between find and action. Clipboard-mode degrades to empty/stale `Result` here. **Ruled out** on an attended, unlocked, foreground session with no competing app — then revisit Branch B.
+
+**Fix.**
+- Keep the session interactive and unlocked for the whole job — use an unattended runtime that holds an active console session; never run CV against a locked or minimized RDP window. Do not minimize/lock the RDP client during execution.
+- Eliminate the focus thief — suppress notifications/popups, or bring the target window to the foreground immediately before the action.
+- Suppress UAC/secure-desktop interruptions on the robot machine (admin/policy) so they don't seize the desktop mid-action.
+- For clipboard-mode CV Get Text, confirm the target is editable text; if not, switch `MethodType` to OCR (clipboard select cannot work on non-editable targets). *(App/policy fixes are environment-side; any `MethodType`/property change edits the workflow — see Post-presentation actions.)*
+
+### Branch D — Malformed special-key sequence in `Text` (CV Type Into)
+
+**Evidence.** Driver-level error out of `WriteText` and `Text` contains `[k(...)]` special-key syntax that is unbalanced/invalid. **Ruled out** if `Text` is plain literal text with no `[k(...)]` tokens.
+
+**Fix.** Correct the special-key syntax in `Text` (balanced `[k(...)]`). *(Edits the workflow — see Post-presentation actions.)*
+
+### Branch E — Unwrapped non-CV exception from the find task
+
+**Evidence.** The exception's type and message are not from `UiPath.CV.*` and not a known driver/COM signature — e.g. `InvalidOperationException` surfaced verbatim. CV unwraps and rethrows the find task's inner exception as-is.
+
+**Fix.** Treat the surfaced exception on its own terms — it is the genuine underlying fault (its message/type is authoritative), not a CV-layer error. Diagnose by that exception, not by this playbook's CV mechanics. If it points outside the activity package, escalate accordingly.
+
+## Post-presentation actions
+
+This resolution is **interactive** whenever a fix edits user source files — Branch A (credential wiring), Branch B (add wait / change `DelayBefore` / drop a stale `InRegion`), Branch C (`MethodType` change), and Branch D (`Text` edit) all touch the workflow. The orchestrator MUST call `AskUserQuestion` before any edit.
+
+1. **Sharing a file path is not approval.** A path given so you could read the project does not authorize editing it. Issue a separate `AskUserQuestion` before any write.
+2. **Never bundle "gather input" with "apply fix" in one option.** Split into two steps: gather the input, then surface the concrete diff and confirm separately.
+3. **Surface the diff before asking.** Include the file path, the activity `IdRef` or line, the current value, and the proposed value (e.g. `CvTypeIntoWithDescriptor` `DelayBefore` `300` → `1500`; or the `Text`/credential binding change). Vague approvals are not enough.
+4. **One question per file/fix.** If multiple files are touched, list each or ask file-by-file. Do not silently propagate a change to side-channel files.
+5. **Environment/policy fixes are recommendations, not edits** — keeping the session unlocked, suppressing UAC/notifications, or running an interactive unattended runtime are operator actions; present them as recommendations.
+6. **If interactive approval is unavailable or errors, do not edit.** Present the diff as a recommendation and stop. A recommendation-only close is acceptable; a silent edit is never.
+
+## Stop / escalate
+
+Stop and escalate when: the SecureString is confirmed populated yet `ArgumentNullException(Secure)` persists; the session is provably interactive, unlocked, and foreground with no focus thief and no screen movement, yet the click/type still faults or misses; or the surfaced exception is an unwrapped non-CV type (Branch E) whose root cause lies outside `UiPath.CV.Activities`. In those cases the cause is outside this activity's post-find action path — escalate (UI driver, target-app stability, robot/desktop environment, or the upstream component that produced the unwrapped exception) rather than continue under this playbook.

package/skills/uipath-troubleshoot/references/activity-packages/cv-activities/playbooks/cv-cell-targeting-failures.md

@@ -0,0 +1,111 @@
+---
+confidence: high
+---
+
+# CV — Table cell-targeting failures (table not detected, row/column mismatch, old FeatureVersion)
+
+## Context
+
+What this looks like — the descriptor targets a table **cell** (`CellExtraInfo` set on `Descriptor.Target`), the find runs, retries to `TimeoutMS`, then faults with `UiPath.CV.ElementNotFoundException` carrying **one of nine cell-specific messages** (not the generic `Element not found`). One shared `FindCell` implementation raises all of them; the LAST cell error hit before timeout is rethrown via `ExceptionDispatchInfo`, so the author sees the specific cell message describing the final mismatch.
+
+Match verbatim (variable parts parameterized as `<n>`):
+
+- `Could not find table. Cell targeting supports only tables as target` — matched area is not a CV-detected **table**.
+- `Table only contains <count> columns and column number is <n>` — `ColumnIndex` exceeds the detected column count.
+- `Invalid column number <n>` — `ColumnIndex < 1` (index is **1-based**; `0` triggers this).
+- `Table does not have any column with column name containing <name>` — `ColumnName` matched no header (exact → Levenshtein → contains all failed).
+- `Table only contains <count> rows and row number is <n>` — `RowIndex` exceeds the detected row count.
+- `Invalid row number <n>` — `RowIndex < 1` (1-based).
+- `Table only contains <count> columns and cell number is <n>` — `RowSearchColumnIndex` (the search column for row-by-value) exceeds the column count.
+- `Invalid cell number <n>` — `RowSearchColumnIndex < 1` (1-based).
+- `No row in column <columnIndex> had a text containing <value>` — row-search value matched no cell in that search column. `<columnIndex>` is the **search column number**, not the value.
+
+> **Pattern-matching trap:** the column/row "out of range" messages and the "invalid" (`< 1`) messages are distinct strings keyed on different conditions — `Table only contains <count> columns…` means the table was detected but is smaller than the index, while `Invalid column number 0` means a 1-based index was supplied as `0` or negative. Route on which sentence appears, not on "column problem" generically.
+
+What activities can produce this:
+- **CV Click** (`CvClickWithDescriptor`) — `Descriptor` whose target is a table cell.
+- **CV Type Into** (`CvTypeIntoWithDescriptor`) — same.
+- **CV Get Text** (`CvGetTextWithDescriptor`) — same (cell descriptor also drives a double-click extraction path).
+- **CV Element Exists** (`CvElementExistsWithDescriptor`) — produces the same `ElementNotFoundException` internally, but the activity **catches it and returns `Result = false`**. The informative cell message is **lost at the workflow level** — visible only in the trace / CV runtime dump. See the silent-result trap in Investigation step 5.
+
+What can cause it:
+- **Old `Version` (FeatureVersion) — cell targeting disabled.** When the activity's `Version` property is below **V3**, `Feature.CellTargeting` is off; analysis falls back to `LegacyTableDetection` and the cell is never resolved against a modern table. The find returns null and faults with the **generic `Element not found`** message — NOT a cell-specific sentence. This is the trap: a correct cell descriptor on a downlevel `Version` looks like a plain not-found, not a cell error.
+- **Table not detected as a table by the CV server.** The target area was matched, but the CV model did not classify it as a `Table`, so `GetTables` returns nothing for that area → `Could not find table. Cell targeting supports only tables as target`. Caused by rendering/border/styling changes, low resolution, or a grid the model reads as plain text.
+- **Row/column index out of range.** The table is smaller than the descriptor's `ColumnIndex` / `RowIndex` / `RowSearchColumnIndex` (columns added/removed, fewer rows rendered than expected, header row counted or not).
+- **1-based index supplied as 0 (or negative).** Cell indices are 1-based. `0` yields `Invalid column number 0` / `Invalid row number 0` / `Invalid cell number 0`.
+- **Column-name / row-search-value mismatch.** `ColumnName` or `RowSearchValue` did not match the extracted header / cell text under exact, then Levenshtein-threshold, then contains matching. Header renamed, OCR misread, whitespace, or different language.
+- **Row-index targeting after scrolling.** `RowIndex` cell targeting combined with a scrolled-to table is inherently unreliable — design-time emits the `ScrollWithRowIndex` warning. After scrolling, the row the model indexes may not be the row the author counted.
+
+> **Different cause, do not apply this playbook:**
+> - Generic `Element not found` with **no** cell sentence AND `Version >= V3` and a non-cell (image/control) target — the descriptor target itself never matched. Use [cv-element-not-found.md](./cv-element-not-found.md).
+> - `Element not found` where the descriptor IS a cell but `Version < V3` is the suspected cause is handled **here** (Branch C below) — confirm `Version` before routing to cv-element-not-found.
+> - `Descriptor or InputRegion is required`, `InvalidDescriptorException`, null `Target`, broken image refs — the descriptor never built. Use [cv-invalid-descriptor.md](./cv-invalid-descriptor.md).
+> - Element was found, then the click/type failed (focus, stale coordinates, blocked input) — use [cv-action-failed-after-find.md](./cv-action-failed-after-find.md).
+> - CV server / auth / throttling / OCR word-limit `System.ArgumentException` with a server error code — use [cv-server-auth-throttling-network.md](./cv-server-auth-throttling-network.md).
+> - `CvElementExistsWithDescriptor` returning `false` for a cell config error, or any `ContinueOnError`/`InRegion` swallow — use [cv-silent-failures-and-false-results.md](./cv-silent-failures-and-false-results.md) for the false-result mechanics; return here for the cell descriptor fix itself.
+> - Scrolled the whole screen / scroll never reached the pane — use [cv-scroll-search-failures.md](./cv-scroll-search-failures.md).
+> - CV Get Text returned empty/stale/wrong text after the cell WAS found — use [cv-get-text-empty-or-wrong-result.md](./cv-get-text-empty-or-wrong-result.md).
+
+## Investigation
+
+1. **Read the exact exception message** from the job log / trace. Confirm it is `ElementNotFoundException` AND carries one of the nine cell sentences above. The specific sentence is the rethrown LAST mismatch after retries — it names the precise failing check.
+2. **Confirm the descriptor targets a cell.** Inspect the faulted activity's `Descriptor` — `Target.CellExtraInfo` must be set (`UseColumnIndex`/`ColumnIndex`, `ColumnName`, `UseRowIndex`/`RowIndex`, `RowSearchColumnIndex`/`RowSearchValue`). No `CellExtraInfo` → this is not a cell-targeting failure; route to cv-element-not-found.
+3. **Read the activity's `Version` property** from XAML. `Version < V3` (V1/V2/None, or a hand-edited XAML that lost the attribute) with a cell descriptor → Branch C, even if the message is the generic `Element not found`. This is the silent old-version trap and must be ruled out before treating it as a table-detection or index problem.
+4. **Map the message to its check** to pick the branch (decision tree below). Each sentence corresponds to exactly one failing condition in `FindCell`.
+5. **For `CvElementExistsWithDescriptor` returning `false`:** the cell message is swallowed. Pull it from the **CV runtime dump** (`*_ComputerVision` timestamped JSON written before the find gives up) or the activity trace span — that is the only place the `Invalid column number 0` / `Table only contains…` text survives. Do NOT conclude "element absent" from `Result = false` when the descriptor is a cell config — a config error and a genuinely-missing cell both return `false`.
+6. **Check `ScrollDirection` + `RowIndex`.** If `ScrollDirection != None` and the cell uses `UseRowIndex`, the design-time `ScrollWithRowIndex` warning applies — row indices over scrolled tables drift.
+
+## Resolution
+
+Walk the decision tree. Choose the first branch whose evidence holds. Fixes that edit the descriptor/`Version` in the workflow are **interactive** — see Post-presentation actions.
+
+### Branch A — Target is not detected as a table
+
+Evidence: message is `Could not find table. Cell targeting supports only tables as target`. The area matched, but `GetTables` found no table for it.
+
+Fix: the CV model did not classify the target as a `Table`. Re-validate the descriptor against the live screen — re-indicate the table so the model captures it as a table element. If borders/gridlines/styling changed, or resolution is low, restore the conditions under which the table is detectable. Confirm the indicated region actually encloses a tabular structure, not a styled list. No index change will help until the table is detected.
+
+### Branch B — Index out of range or `< 1`
+
+Evidence:
+- `Table only contains <count> columns and column number is <n>` / `…rows and row number is <n>` / `…columns and cell number is <n>` → the table is smaller than the supplied index.
+- `Invalid column number <n>` / `Invalid row number <n>` / `Invalid cell number <n>` with `<n>` `0` or negative → 1-based index supplied as `0`.
+
+Fix:
+- **For "only contains <count>…":** the actual table has `<count>` columns/rows. Correct the descriptor's `ColumnIndex` / `RowIndex` / `RowSearchColumnIndex` to be `<= <count>`. If the table genuinely gained/lost columns, the structure changed — re-confirm the intended cell.
+- **For "Invalid … number 0":** indices are **1-based**. Change `0` to `1` (first column/row). Never use `0` for a CV cell index.
+
+### Branch C — Old FeatureVersion (cell targeting disabled)
+
+Evidence: descriptor has `CellExtraInfo` (step 2 confirmed) AND `Version < V3` (step 3). Message is typically the **generic `Element not found`**, NOT a cell sentence — because legacy table detection never matches the cell. Confirmed by Test `ActivityWithUiNode_WithCellDescriptor_OldVersion_Throws`.
+
+Fix: set the activity's `Version` (FeatureVersion) to **V3 or later** so `Feature.CellTargeting` is enabled. Re-validate after the bump. Rule this branch OUT — and do NOT bump `Version` — when `Version` already reads V3+; in that case the generic `Element not found` is a real not-found (route to cv-element-not-found), not a cell-targeting trap.
+
+### Branch D — Column-name or row-search-value mismatch
+
+Evidence:
+- `Table does not have any column with column name containing <name>` → `ColumnName` matched no header.
+- `No row in column <columnIndex> had a text containing <value>` → `RowSearchValue` matched no cell in search column `<columnIndex>`.
+
+Fix: the configured name/value did not match the extracted text under exact, Levenshtein, or contains matching. Compare the descriptor's `ColumnName` / `RowSearchValue` against the **actual extracted table text** in the CV dump. Correct for renamed headers, OCR misreads, whitespace, casing beyond threshold, or language. If the header is volatile, switch to index-based targeting (`UseColumnIndex` / `UseRowIndex`) instead of name/value.
+
+### Branch E — Row-index targeting over a scrolled table
+
+Evidence: `Table only contains <count> rows and row number is <n>` or a wrong cell hit, AND `ScrollDirection != None` with `UseRowIndex` (step 6; design-time `ScrollWithRowIndex` warning present).
+
+Fix: row indices over scrolled tables are unreliable — the model re-indexes from the visible window after scrolling. Prefer **row-by-value** targeting (`RowSearchColumnIndex` + `RowSearchValue`) so the row is identified by content, not position, or remove the scroll dependency so the full table is in view before the find.
+
+## Post-presentation actions
+
+Branches A–E all end in a **workflow source edit** (descriptor `CellExtraInfo` change, `Version` bump, scroll/targeting change). This resolution path is **interactive**.
+
+1. The orchestrator MUST call `AskUserQuestion` before any edit: print the exact file path, the activity `IdRef`, the property (e.g. `Version`, `Descriptor.Target.CellExtraInfo.ColumnIndex`), and the current → proposed value.
+2. **Sharing a file path is not approval.** A path the user gave for reading does not authorize editing — issue a separate `AskUserQuestion` before writing.
+3. Never bundle "gather input" with "apply fix" in one option — split into gather, then surface the concrete diff and confirm.
+4. The apply-fix question must show the concrete diff (file, `IdRef`/line, current value, proposed value). Vague approvals are not enough.
+5. One question per file/fix; list every file touched (XAML plus any Object Repository mirror).
+6. If interactive approval is unavailable or errors: present the diff as a recommendation and stop. A recommendation-only close is acceptable; a silent edit never is.
+
+## Stop / escalate
+
+If the table IS detected (no `Cell targeting supports only tables` message), `Version >= V3`, the indices are within the detected `<count>` and `>= 1`, the column-name / row-search-value matches the extracted text, and no scrolled-row-index combination is present — yet the cell still cannot be resolved, the cause is outside cell targeting. Pull the CV runtime dump to confirm what the model extracted, then escalate (CV model table-extraction accuracy for this layout, or a server/analysis fault per [cv-server-auth-throttling-network.md](./cv-server-auth-throttling-network.md)) rather than continue under this playbook. Do NOT keep mutating indices once the dump shows the extracted table matches the descriptor.

package/skills/uipath-troubleshoot/references/activity-packages/cv-activities/playbooks/cv-element-not-found.md

@@ -0,0 +1,125 @@
+---
+confidence: medium
+---
+
+# CV — Element Not Found (descriptor match failed within timeout)
+
+## Context
+
+What this looks like — the job faults with `UiPath.CV.ElementNotFoundException`. The message is almost always the parameterless literal:
+
+- `Element not found` — the canonical not-found signal. Emitted by `RuntimeFindService.FindWithRetry` after the retry loop exhausts `TimeoutMS` without a descriptor match. **Timeout expiry surfaces as `ElementNotFoundException`, NOT a `TimeoutException`** — there is no separate timeout exception type. Do not look for `TimeoutException`; do not conclude "this is not a timeout" from its absence.
+
+The same `Element not found` text covers three structurally different root causes (genuine mismatch, scope-refresh failure, OCR degradation). The Resolution decision tree below keys on observable evidence to tell them apart.
+
+> Trace-only message variant: the scope-refresh path additionally traces `Could not get screenshot` before the `ElementNotFoundException`. This line appears in the execution trace/log, not in the activity fault message. Its presence routes to Branch B.
+
+What activities can produce this error:
+
+- **CV Click** (`CvClickWithDescriptor`) — `Descriptor` argument; faults when the target/anchors never match.
+- **CV Type Into** (`CvTypeIntoWithDescriptor`) — `Descriptor` argument; same find pipeline before typing.
+- **CV Get Text** (`CvGetTextWithDescriptor`) — `Descriptor` argument; same find pipeline before reading text.
+- **CV Element Exists** (`CvElementExistsWithDescriptor`) — does NOT fault. It catches `ElementNotFoundException` internally and returns `Result = false`. Every cause below becomes a `false` Result here, with `OutRegion` left unset. The error message is visible only in the trace / CV dump, never at the workflow level.
+- **CV Screen Scope** (`CVScope`) — produces this indirectly: the scope's session refresh (root re-resolution / screenshot) throws `ElementNotFoundException` that surfaces through the child find activity (Branch B).
+
+What can cause it (ordered most → least common):
+
+- **UI changed since design time.** Target text/label/icon differs, element moved or was removed, layout shifted, theme/DPI change. The descriptor's target (or an anchor) no longer matches any region in the CV + OCR analysis of the screen.
+- **Wrong screen state at run time.** App window not foreground/visible, page not loaded yet, a dialog covering the target, or the workflow reached the activity before the expected content rendered.
+- **Anchor geometry broke.** Descriptor has anchors that are no longer co-located with the target — `Anchor2Service` finds the target and anchors individually but the geometric relationship no longer holds, so no match is returned.
+- **Scale / DPI mismatch.** `DesignTimeScaleFactor` differs from `RootElementScaleFactor` (different monitor scaling between design and run machine), shifting matched geometry.
+- **Timeout too short.** Slow-rendering screen never finishes within `TimeoutMS` — surfaces as `ElementNotFoundException`, not a timeout error.
+- **Scope root lost / screenshot failed during refresh.** Target window closed, minimized, navigated away, or the session is locked/disconnected so the screenshot is null. The scope cannot produce a screen to analyze (Branch B).
+- **OCR engine silently degraded.** The configured OCR engine threw or returned null during refresh; the failure is swallowed and OCR returns zero text elements, so every text-based target/anchor has no candidate region and never matches (Branch C).
+
+What to look for:
+
+- **The pre-throw runtime dump JSON is the primary forensic artifact.** Before throwing, `RuntimeFindService` writes a timestamped `*_ComputerVision` dump file via `RuntimeDumpInfoService`. It captures the descriptor, the scraped text, the detected elements, detected tables, the selector, and the screenshot at failure time. Locate and read this file first — it tells you what the CV server actually saw at the moment of failure (which distinguishes "UI changed" from "screen was empty/blank").
+
+> **Different cause, do not apply this playbook:**
+> - Message is `Scrolled the entire screen, but element was not found` — scroll-search exhausted, not a plain find timeout. Use [cv-scroll-search-failures.md](./cv-scroll-search-failures.md).
+> - Message is a cell-targeting sentence (`Could not find table. Cell targeting supports only tables as target`, `Invalid column number <n>`, `Table only contains <n> columns and column number is <m>`, `No row in column <c> had a text containing <v>`, etc.) — descriptor targets a table cell. Although the type is still `ElementNotFoundException`, the *last* cell error is rethrown verbatim, so you will see the cell sentence, not `Element not found`. Use [cv-cell-targeting-failures.md](./cv-cell-targeting-failures.md).
+> - Message is `Invalid Descriptor` / `Reason: Target must be set` / `Reason: Invalid image reference or value` — `InvalidDescriptorException`, thrown before any find attempt (descriptor evaluation/validation), not after a timeout. Use [cv-invalid-descriptor.md](./cv-invalid-descriptor.md).
+> - The activity did NOT fault but a click/type landed on the wrong spot, or `CvElementExistsWithDescriptor` returned an unexpected `true`/`false` — the element was found (or `InRegion`/`ContinueOnError` bypassed the find). Use [cv-silent-failures-and-false-results.md](./cv-silent-failures-and-false-results.md).
+> - The fault is a CV **server** error — `401`/`403`/`5xx`, `429`/`TooManyRequests`, payload/word-limit, or a network error during analysis. The find never completed because the analysis call failed. Use [cv-server-auth-throttling-network.md](./cv-server-auth-throttling-network.md).
+> - The CV Screen Scope itself failed to set up (target window never resolved, missing local-server prerequisite, missing server/OCR config) — the scope never produced a session. Use [cv-scope-setup-failures.md](./cv-scope-setup-failures.md).
+> - A click/type fault that occurred *after* the element was found (focus loss, stale coordinates, blocked input, SecureString) — find succeeded, action failed. Use [cv-action-failed-after-find.md](./cv-action-failed-after-find.md).
+> - `CV Get Text` returned empty/stale/wrong text without faulting — find succeeded, extraction misbehaved. Use [cv-get-text-empty-or-wrong-result.md](./cv-get-text-empty-or-wrong-result.md).
+
+## Investigation
+
+1. **Confirm the message and type.** `UiPath.CV.ElementNotFoundException` with message `Element not found`. If the message is a scroll, cell, or invalid-descriptor sentence, stop and route via the negative-match block above. For `CvElementExistsWithDescriptor`, there is no fault — the symptom is `Result = false`; proceed using the dump and trace.
+2. **Locate the `*_ComputerVision` runtime dump JSON** written just before the throw (timestamped, matching the failed run). Read the descriptor, the scraped/detected text, the detected elements, and the screenshot.
+3. **Inspect the dump screenshot.** Decide which branch the evidence supports:
+   - Screenshot shows the expected application screen, but the target is absent / different / moved → Branch A (genuine mismatch).
+   - Screenshot is blank, black, truncated, shows the desktop/lock screen, or is missing, and/or the trace shows `Could not get screenshot` → Branch B (scope refresh failed).
+   - Screenshot shows the correct screen with the target text clearly visible, but the dump's detected/scraped text is empty or missing that text → Branch C (OCR degraded).
+4. **Read the trace** around the failure for `Could not get screenshot` (Branch B signal) and for any OCR-engine error/warning that was logged before degradation (Branch C corroboration).
+5. **Capture the activity's `Descriptor` and key properties** from the workflow: `TimeoutMS`, `ScrollDirection` (if set, the negative-match scroll playbook applies once it actually scrolls), `InRegion` (if bound, the descriptor is bypassed — different playbook), and the `Version` / `FeatureVersion`.
+6. **Capture scope/environment context.** The `CVScope` `Target` selector and `WaitForReady`, whether the run is unattended, whether the session could be locked/minimized, and the CV method / OCR engine configured on the scope.
+
+## Resolution
+
+Walk the decision tree. Choose the first branch whose evidence holds. Do not apply a branch whose ruling-out evidence is present.
+
+> **Not applicable — do NOT recommend:** the **Healing Agent** and selector-improvement remedies (`selector-failure-*` playbooks) are **UIA-selector** features. They do NOT apply to CV `Cv*WithDescriptor` activities, which match a visual **descriptor**, not a UIA selector. The fix for a CV find failure is descriptor **re-indication** (Branch A) / scope or OCR correction (Branches B/C) — never selector healing. Recommending Healing Agent here is a misattribution.
+
+### Branch A — Genuine descriptor mismatch (UI changed, anchors moved, DPI scale mismatch)
+
+**Evidence (required to apply):** the dump screenshot shows the expected application screen rendered normally, AND the target is absent, visually changed, or relocated relative to its anchors. OCR/detected text in the dump is populated (rules out Branch C). No `Could not get screenshot` trace (rules out Branch B).
+
+**Fixes:**
+- **UI changed.** Re-indicate the target against the current screen to regenerate the descriptor. If only a label/text drifted, loosen the descriptor's text/fuzzy matching for the volatile part.
+- **Anchor geometry broke.** Re-pick anchors that remain stable relative to the target, or reduce reliance on anchors if the target alone is now distinctive.
+- **Scale/DPI mismatch.** Make the run-machine display scaling match design time, or re-indicate on the run-machine resolution. Do NOT just raise `TimeoutMS` — geometry, not time, is the problem.
+- **Wrong screen state.** Add an explicit readiness gate before the activity (wait for a stable anchor element / page-loaded indicator) so the target is present when the find runs.
+- **Timeout too short — only if the screen is slow-rendering.** Raise `TimeoutMS`. Apply this ONLY when the dump shows the screen still mid-render (partial content) at failure; raising the timeout when the UI genuinely changed wastes the whole window and still fails.
+
+### Branch B — Scope root lost / screenshot failed during refresh
+
+**Evidence (required to apply):** the dump screenshot is blank/black/desktop/lock-screen or missing, AND/OR the trace contains `Could not get screenshot` before the `ElementNotFoundException`. The scope could not produce a valid screen to analyze, so the find could never match.
+
+**Root cause is one of:**
+- **Target application/window closed or navigated away** mid-scope (between scope setup and this activity).
+- **Window minimized** — the element region is empty, so the screenshot is null.
+- **Scope root selector no longer matches** (window title changed), so the root element could not be re-created from its cached selector within the timeout.
+- **Locked/disconnected session** preventing screen capture (common on unattended robots where the session locks).
+
+**Fixes:**
+- Ensure the target window stays open, foreground, and non-minimized for the duration of the CV Screen Scope — add a check/restore step before the failing activity if an earlier step may close or background it.
+- If the scope-window title drifts, relax the `CVScope` `Target` selector (wildcard the volatile part) so its root re-resolves.
+- For unattended runs, keep the session interactive (do not let it lock/disconnect); CV screenshot capture needs a live, unlocked desktop.
+
+> Anti-fabrication: for `CvElementExistsWithDescriptor`, a closed/minimized/locked target silently returns `Result = false` — indistinguishable at the workflow level from a genuine "element does not exist." Do NOT report `Result = false` as "element confirmed absent" until the dump screenshot proves the screen was actually captured. A blank screenshot means the check is meaningless, not negative.
+
+### Branch C — OCR engine silently degraded (text-based descriptors fail as not-found)
+
+**Evidence (required to apply):** the descriptor's target or anchors are text-based, the dump screenshot clearly shows that text on screen, BUT the dump's detected/scraped text is empty or missing it. Optionally an OCR-engine error/warning was logged before the find timed out. The OCR failure is swallowed (returns null → zero text elements), so text matches never find a candidate.
+
+**Root cause is one of:**
+- **OCR engine misconfiguration** — wrong `ApiKey`/endpoint for the configured engine (e.g. UiPath Screen OCR), or the engine package missing at runtime.
+- **CV method excludes OCR** — `CVScope.CvMethod` not set to a mode that runs OCR, so no text elements are produced.
+- **Language/accents mismatch** producing zero recognized words.
+
+**Fixes:**
+- Verify and correct the `CVScope.OCREngine` configuration (engine selected, `ApiKey`/endpoint valid; Screen OCR inherits the scope `ApiKey` only when its own key is empty). Confirm the engine package is present on the run machine.
+- Ensure `CVScope.CvMethod` includes OCR when the descriptor relies on text targets/anchors.
+- If text recognition is unreliable for the content's language/font, switch the descriptor to image- or control-based targeting instead of text.
+
+## Post-presentation actions
+
+This resolution is **interactive** — every applicable fix edits user source files (the activity `Descriptor`, `TimeoutMS`, `CVScope` `Target`/`OCREngine`/`CvMethod` properties, or adds a readiness/check activity). Before any edit, the orchestrator MUST call `AskUserQuestion`. Rules:
+
+1. **Sharing a file path is not approval.** A path the user gave for reading the workflow does not authorize editing it. Issue a separate `AskUserQuestion` before any write.
+2. **Never bundle "gather input" with "apply fix" in one option.** Split into two steps: gather the input, then surface the concrete diff and confirm separately.
+3. **Surface the diff before asking.** Include the file path, the activity `IdRef`/line, the current value, and the proposed value (e.g. the `Descriptor` re-indication, the `TimeoutMS` change, the `CVScope.OCREngine` correction).
+4. **One question per file/fix.** If multiple files are touched (workflow plus an Object Repository mirror), list every file or ask file-by-file. Do not silently propagate the change to side-channel files.
+5. **If interactive approval is unavailable or errors, do not edit.** Present the diff as a recommendation and stop. A recommendation-only close is acceptable; a silent edit is never.
+
+## Stop / escalate
+
+Escalate (do not continue under this playbook) when:
+
+- The dump screenshot shows the expected screen with the target plainly present and unchanged, OCR text is populated, the descriptor still matches at design time against the same screen, scaling matches, and the timeout was ample — the failure is then outside the descriptor/find path (CV server model regression or driver issue); escalate with the `*_ComputerVision` dump attached.
+- Branch B evidence holds but the window is confirmed open, foreground, non-minimized, the session is live, and the scope selector resolves — the screenshot failure is environmental/driver-level; escalate rather than keep editing the workflow.
+- Branch C evidence holds but the OCR engine is correctly configured, packaged, and `CvMethod` includes OCR — escalate the OCR engine/runtime, do not keep changing the descriptor.