@uipath/skills 1.197.0 → 1.197.2

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/selector-failure-healing-fix.md

@@ -21,7 +21,7 @@ What can cause it:
 - Authoring-time selector mistake against a stable element (typo, wrong attribute value, copy-paste error) — the live element is unchanged but the workflow's selector never matched
 - Element temporarily obscured by a popup or overlapping window (HA may emit a `dismiss-popup` fix instead of `update-target`)
 
-This playbook applies whenever HA recovery data is present for the failing activity, regardless of which specific cause above produced the failure. The cause label affects the user-facing narrative; the **remediation procedure (present HA's recommendation, ask whether to apply it) is the same for all of them** and is the authoritative resolution path even when the cause is later refined (e.g., depth-verifier identifies an authoring typo rather than UI drift).
+This playbook applies whenever HA recovery data is present for the failing activity, regardless of which specific cause above produced the failure. The cause label affects the user-facing narrative; the **remediation procedure (present HA's recommendation, ask whether to apply it) is the same for all of them** and is the authoritative resolution path even when the cause is later refined (e.g., verification identifies an authoring typo rather than UI drift).
 
 ## Investigation
 
@@ -34,7 +34,7 @@ This playbook applies whenever HA recovery data is present for the failing activ
 3. Compare failed vs recommended selector and note which attributes changed (text, index, role, ancestry, etc.).
 4. Record the recovery channel, the detection's `InferMethod` / confidence score, and whether self-healing actually applied the fix at runtime (`RecoverySuccessful`). These determine the warning attached to the apply-fix prompt.
 
-Persist the exact failed and recovered selector strings to the evidence file for this hypothesis (e.g., as `failed_selector_xml`, `recovered_partial_selector_xml`, `recovered_fuzzy_partial_selector_xml`). The orchestrator's Resolution phase will read them back to drive the `AskUserQuestion` apply-fix flow — they MUST be present verbatim, not paraphrased.
+Persist the exact failed and recovered selector strings verbatim in notes.md (e.g., as `failed_selector_xml`, `recovered_partial_selector_xml`, `recovered_fuzzy_partial_selector_xml`). The Resolution phase will read them back to drive the `AskUserQuestion` apply-fix flow — they MUST be present verbatim, not paraphrased.
 
 ## Resolution
 
@@ -42,4 +42,4 @@ Follow the fix-application procedures in [interpretations/healing-agent-data.md]
 - For `update-target` (self-healing) or `InferredRecoveryInfo.RecoveredTarget` (recommendation-only): use `uia-improve-selector` skill if available, otherwise direct XAML edit. When the data is `InferredRecoveryInfo` or `RecoverySuccessful: false`, attach the runtime-not-validated warning to the apply-fix prompt.
 - For `dismiss-popup` / `RecoveredExternally`: create a Click activity before the failing activity, validate the workflow compiles.
 
-This resolution path is **interactive** — it requires `AskUserQuestion` to be called by the orchestrator at the end of the troubleshooting to (a) print the Failed / Recovered Partial / Recovered Fuzzy selectors as plain text, (b) ask the user whether to apply the fix and which selector variant. The presenter must emit a `## Post-presentation actions` block declaring this interactive step; the orchestrator must execute it before closing the investigation. Do not collapse this into a generic "fix the selector" recommendation — the recovered selector text and the apply-fix prompt are part of the documented resolution.
+This resolution path is **interactive** — it requires `AskUserQuestion` to be called at the end of the troubleshooting to (a) print the Failed / Recovered Partial / Recovered Fuzzy selectors as plain text, (b) ask the user whether to apply the fix and which selector variant. Execute this interactive step per `references/presenting.md` § Interactive resolutions before closing the investigation. Do not collapse this into a generic "fix the selector" recommendation — the recovered selector text and the apply-fix prompt are part of the documented resolution.

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

@@ -14,7 +14,7 @@ Before using any fetched data, verify it matches the user's reported problem:
 
 If the data doesn't match: **discard it**. Do NOT use unrelated data as a proxy. Report the mismatch and ask for clarification.
 
-## What to Capture
+## Domain-Specific Data Gathering
 
 1. **Workflow source** — read the `WordApplicationScope` node from the `.xaml` to capture the literal document `Path` expression, `CreateIfNotExists`, `Password`, and whether the scope runs visible or unattended. Property-panel summaries truncate; the XAML is authoritative.
 2. **Word installed + bitness** — whether desktop Word is installed on the execution host (`Control Panel > Programs and Features`, or `HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\winword.exe`), and the Office bitness (`File > Account > About Word`) versus the robot process bitness.

package/skills/uipath-troubleshoot/references/activity-packages/word-activities/playbooks/replace-text-silent-no-substitution.md

@@ -18,6 +18,8 @@ What to look for:
 - Whether the placeholder was edited in place in the template (a tell: it was typed with corrections).
 - Whether part of the placeholder carries different formatting from the rest.
 
+> **Workflow-source guard:** in workflow XAML, an activity attribute value wrapped in square brackets (e.g. `Replace="[employeeName]"`) is an **expression binding** to a variable — correct configuration, not a defect. Never report it as a bug and never propose removing the brackets; stripping them converts the binding into the literal text and BREAKS a working workflow. The defect in this failure class lives in the Word template's XML runs, not in the activity's property syntax.
+
 ## Investigation
 
 1. Confirm the activity reports success and the `Search` value exactly matches the on-screen placeholder (character-for-character, including brackets and case).

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

@@ -0,0 +1,26 @@
+# App Events (Workflow Events) Activities
+
+Activities from the `UiPath.WorkflowEvents.Activities` package. These are **internal** machinery that connects a **UiPath App** (or a Studio Web app preview) to the robot that runs the App's workflows — they are marked `[Internal]` and a user never drags them onto a canvas. They appear only inside a process that an App invokes.
+
+So the user-visible failure is **"a job invoked by my App faulted"** — the faulted activity name (`HandleAppRequest`, `AppRequestTrigger`, `InitializeHubConnection`) shows up in the job error / trace spans, **not** in the user's project. Treat the activity as the location the fault surfaced, not a control the user can edit.
+
+## Two connection modes
+
+A UiPath App talks to the robot over one of two channels; the same activities run on both:
+
+- **RobotJS** (legacy, default) — a local message channel between the App host and the robot via the executor's `WorkflowCommunication`.
+- **SignalR** (modern, Studio Web) — a SignalR hub connection over WebSockets / Server-Sent Events / long-polling. `InitializeHubConnection` sets it up; the trigger and handler ride it.
+
+## Exceptions propagate raw
+
+These activities do **NOT** wrap failures in a package-specific exception type. They surface raw .NET framework exceptions (`NullReferenceException`, `TimeoutException`, `IOException`, `InvalidOperationException`, `AggregateException`) from the SignalR / HTTP / transport / runtime layer. So the **faulted activity class plus the exception class** — not a unique message string — is the primary discriminator. The same exception type on two different activities is a different investigation.
+
+## Key activity types
+
+- **Initialize Apps Hub Connection** (`NetCore.Activities.InitializeHubConnection`) — Studio Web only. At workflow start it resolves the Apps/Orchestrator resource URL and an access token, then kicks off the SignalR hub connection. The hub `StartConnectionAsync` runs on a background thread whose errors are **logged, not thrown** — so a job-faulting `System.AggregateException` comes from the **synchronous** bootstrap (resource-URL / token acquisition, or an invalid session/URL → `WorkflowApplicationException`), wrapped by the async-activity framework. Unwrap the inner exception.
+- **Apps Request Trigger** (`AppRequestTrigger`) — waits for the App to send invoke-workflow requests and periodic heartbeats over the channel. A missed heartbeat is handled gracefully (it signals "connection lost", no fault). The activity **faults** when the request-listener leg cannot establish or loses the channel — `TimeoutException` (SignalR connection never established), `IOException` (transport/pipe dropped while awaiting a request), or `InvalidOperationException` (SignalR client in an invalid state). These are channel/transport failures, not the user's workflow logic.
+- **Handle Apps Request** (`HandleAppRequest`) — runs the workflow the App invoked and sends the result back over the channel. The invoked workflow's own exception is **captured and returned to the App**, not rethrown — so a job-faulting `System.NullReferenceException` at this activity is almost always a **null dereference inside the App-invoked workflow** (or a required input argument the App did not supply), surfaced through the Apps invocation machinery. Investigate the invoked workflow, not the package internals.
+
+## Package
+
+Namespace / assembly: `UiPath.WorkflowEvents.Activities` (with the Studio-Web-only `NetCore.Activities.InitializeHubConnection`). Ships with the UiPath Apps / Studio Web runtime, not as a toolbox package users add.

package/skills/uipath-troubleshoot/references/activity-packages/workflowevents-activities/playbooks/app-request-trigger-connection-lost.md

@@ -0,0 +1,40 @@
+---
+confidence: medium
+---
+
+# Apps Request Trigger — Connection / Transport Lost (Timeout / IOException / InvalidOperation)
+
+## Context
+
+What this looks like — a job invoked by a **UiPath App** faults at `AppRequestTrigger` (display name **Apps Request Trigger**) with one of:
+
+- `System.TimeoutException` — message `SignalR connection did not establish within 60 seconds. Current state: <state>` (SignalR mode). The hub connection never reached `Connected` while the trigger waited.
+- `System.IO.IOException` — the underlying transport (SignalR socket, or the RobotJS pipe) dropped while the trigger was awaiting a request from the App.
+- `System.InvalidOperationException` — the SignalR client was driven in an invalid state (e.g. invoked on a connection that is not connected / was disposed).
+
+`AppRequestTrigger` is internal Apps machinery the user never placed. It waits for the App to send invoke-workflow requests and heartbeats. A **missed heartbeat is handled gracefully** (it signals "connection lost" without faulting); the job faults only when the request-listener leg cannot establish or loses the channel and rethrows the error through the trigger's bookmark. All three signatures are the same root domain: **the App↔robot channel failed**, not the user's workflow logic.
+
+What can cause it:
+- **The App never connected within the timeout** — the App instance closed, crashed, or was never opened against this run; or the SignalR hub was unreachable, so the connection stayed un-established for 60s (`TimeoutException`).
+- **Network / transport drop** — the WebSocket/long-polling transport (or the local RobotJS pipe) was interrupted mid-wait by a network fluctuation, proxy/idle timeout, or the App host going away (`IOException`).
+- **Invalid channel state** — the hub connection was lost/disposed and an operation was attempted on it, or a reconnect left the client in a non-connected state (`InvalidOperationException`).
+
+What to look for:
+- **Which exception type** — it selects the branch (establish-timeout vs transport-drop vs invalid-state).
+- **Whether the App instance was alive** for the run — a closed/crashed App or one never opened is the most common cause of the establish-timeout.
+- **Connection mode** — SignalR (Studio Web / modern Apps) vs RobotJS (legacy). The `SignalR connection did not establish` message is SignalR mode; a RobotJS pipe drop surfaces as `IOException`.
+- **Network conditions on the robot host** — proxy, idle-socket, or firewall behavior that severs long-lived connections.
+
+## Investigation
+
+1. **Confirm the signature + activity.** `uip or jobs get <job-key> --output json` → `Info` shows `System.TimeoutException` / `System.IO.IOException` / `System.InvalidOperationException`; the faulted activity is `AppRequestTrigger`.
+2. **Read the message and branch:** the `SignalR connection did not establish within 60 seconds` text → establish-timeout; a transport/IO phrase → connection drop; an invalid-operation message → invalid hub state.
+3. **Check the App side** — was the App instance open and connected for this run, or did it close / fail to open? An App that is not connected can never complete the handshake.
+4. **Check the robot host's connectivity** to the SignalR hub (network fluctuation, proxy, idle-connection timeout) for the transport-drop and timeout branches.
+
+## Resolution
+
+- **Establish-timeout (`TimeoutException`):** ensure the UiPath App is actually open and connected to this run before/while the workflow waits; confirm the robot host can reach the SignalR hub (network/proxy/firewall). The trigger waits 60s — a connection that never forms means the App side never attached, not that the timeout is too short.
+- **Transport drop (`IOException`):** treat as an environmental connection loss — verify network stability between the robot host and the hub, and proxy/idle-socket timeouts that sever long-lived connections; re-run once connectivity is stable. Recurring drops on the same network path point at the proxy/firewall.
+- **Invalid channel state (`InvalidOperationException`):** the channel was lost/disposed before the operation — resolve the underlying disconnect (as for the transport-drop branch); if it reproduces deterministically on a specific App/runtime version, capture the trace and report it as an Apps runtime issue.
+- These are platform/transport failures — do not look for a fix inside the user's workflow logic.

package/skills/uipath-troubleshoot/references/activity-packages/workflowevents-activities/playbooks/handle-app-request-null-reference.md

@@ -0,0 +1,34 @@
+---
+confidence: medium
+---
+
+# Handle Apps Request — Null Reference (NullReferenceException)
+
+## Context
+
+What this looks like:
+- A job invoked by a **UiPath App** faults with `System.NullReferenceException: Object reference not set to an instance of an object.`, and the faulted activity is `HandleAppRequest` (display name **Handle Apps Request**).
+- `HandleAppRequest` is internal Apps machinery — the user never placed it. It runs the workflow the App invoked and returns the result. The invoked workflow's own exception is **captured and returned to the App, not rethrown**, so a job-faulting NRE at this activity is almost always raised **inside the App-invoked workflow**, surfaced here through the invocation layer.
+
+What can cause it:
+- **A null dereference in the App-invoked workflow.** A variable, argument, or object inside the workflow the App ran evaluates to `Nothing` and is dereferenced (the classic in-workflow NRE) — the App invocation is just the entry point.
+- **A required input argument the App did not supply.** The App passes input arguments by name; a `null`/missing value the workflow then dereferences faults the same way. Mismatched argument name or type between the App's binding and the workflow's `In` arguments leaves the argument unset.
+- **A wrong or missing workflow file binding.** The App points at a workflow whose argument contract differs from what the App sends, so a value the workflow assumes is present is null.
+
+What to look for:
+- **No SignalR / hub / transport phrase** in the message — a pure NRE means the failure is in workflow execution, not the channel. A channel/transport fault surfaces on `AppRequestTrigger` instead (see [app-request-trigger-connection-lost.md](./app-request-trigger-connection-lost.md)).
+- **The invoked workflow's name and its `In` arguments** vs. what the App binds — the decisive signal.
+- **The faulting frame in the stack** — it points inside the invoked workflow's activities, not the WorkflowEvents package internals.
+
+## Investigation
+
+1. **Confirm the signature + activity.** `uip or jobs get <job-key> --output json` → `Info` shows `System.NullReferenceException`; the faulted activity is `HandleAppRequest`.
+2. **Identify the invoked workflow.** From traces (`uip or jobs traces <job-key> --output json`) read the workflow file the App invoked and the input arguments delivered to it.
+3. **Read the faulting frame.** The stack points inside the invoked workflow — find which variable/argument was dereferenced.
+4. **Compare the App's argument bindings to the workflow's `In` arguments** — name and type must match, and every value the workflow dereferences must be supplied non-null.
+
+## Resolution
+
+- **If the null originates in the invoked workflow's logic:** fix it in that workflow — assign the variable before use, or guard the null path (validate / default it) before the dereference. This is an ordinary in-workflow NRE; investigate it as one.
+- **If a required input argument arrives null:** correct the App's binding so it supplies the value, and align the argument name/type with the workflow's `In` argument. Add a guard in the workflow for the missing-input case.
+- **If the App points at the wrong workflow / a changed contract:** repoint the App at the intended workflow, or update the workflow's argument contract to match what the App sends.

package/skills/uipath-troubleshoot/references/activity-packages/workflowevents-activities/playbooks/initialize-hub-connection-aggregate-failure.md

@@ -0,0 +1,40 @@
+---
+confidence: medium
+---
+
+# Initialize Apps Hub Connection — Aggregate Exception (AggregateException)
+
+## Context
+
+What this looks like:
+- A Studio Web app-workflow run faults at `InitializeHubConnection` (display name **Initialize Apps Hub Connection**) with `System.AggregateException` and the message `One or more errors occurred. (<inner message>)`.
+- `InitializeHubConnection` is internal Studio Web machinery the user never placed. At workflow start it resolves the Apps/Orchestrator resource URL and an access token, then starts the SignalR hub connection. It is an async activity, so a failure in its **synchronous bootstrap** surfaces wrapped in an `AggregateException` — the real cause is the inner exception.
+- Note: the actual hub `StartConnectionAsync` runs on a **background thread that logs (not throws)** its errors, so a job-faulting `AggregateException` is **not** the raw socket connect failing — it is the bootstrap before that (resource-URL / token / session validation). Unwrap the inner exception.
+
+What can cause it (read the inner exception):
+- **Inner `WorkflowApplicationException` — `SignalR: Invalid SessionId: <id> OR Orchestrator Url: <url>`.** The session id or the resolved resource URL was blank when the activity validated them. Indicates the Apps/Studio Web session context or the resource-URL resolution did not produce a usable value.
+- **Inner resource-URL / token-acquisition failure.** `runtime.AccessProvider.GetResourceUrl(...)` / `GetAccessToken(...)` threw — the robot could not resolve the Apps or Orchestrator endpoint, or could not obtain an access token (auth / connectivity / permission).
+- **Inner transport/HTTP failure during bootstrap** — a network failure while resolving the hub endpoint.
+
+What to look for:
+- **`InnerException` / `InnerExceptions` type and message** — the decisive signal; the `AggregateException` wrapper text alone is not enough.
+- **The `SignalR: Invalid SessionId ... OR Orchestrator Url ...` phrase** — points at blank session/URL context rather than a transport failure.
+- **Whether the run is a Studio Web app preview / Apps-invoked run** — this activity only runs in that context; a normal Orchestrator job never executes it.
+
+## Investigation
+
+1. **Confirm the signature + activity.** `uip or jobs get <job-key> --output json` → `Info` shows `System.AggregateException`; the faulted activity is `InitializeHubConnection`.
+2. **Unwrap the inner exception.** Read the inner type/message from the `Info` stack and from `uip or jobs traces <job-key> --output json` / `uip traces spans get --job-key <job-key> --output json`. This selects the branch.
+3. **Branch on the inner cause:**
+   - `WorkflowApplicationException: SignalR: Invalid SessionId ... OR Orchestrator Url ...` → blank session/URL context.
+   - resource-URL / token failure → endpoint resolution or auth failure.
+   - transport/HTTP → network failure reaching the endpoint.
+4. **Confirm the execution context** — that the run is a Studio Web app preview / Apps invocation (the only context where this activity runs).
+
+## Resolution
+
+- **Resolve by inner cause, not the wrapper.** Map the unwrapped inner exception to its fix.
+- **Invalid session / resource URL (`WorkflowApplicationException`):** the Apps/Studio Web session context did not provide a session id or a resolvable resource URL — re-launch the app preview / Apps run from Studio Web so a valid session is established, and confirm the tenant's Apps service URL resolves for this robot. A blank URL points at resource-URL resolution, not the user's workflow.
+- **Resource-URL / token-acquisition failure:** verify the robot can reach the Apps/Orchestrator endpoints and that the run has the rights/connectivity to obtain an access token (network, proxy, and the account's permissions).
+- **Transport/HTTP inner failure:** treat as an environmental connectivity issue to the hub endpoint; re-run once the robot host's connectivity is stable.
+- This activity is platform machinery — the fix is in the session/endpoint/auth context, not in the user's workflow logic.

package/skills/uipath-troubleshoot/references/activity-packages/workflowevents-activities/summary.md

@@ -0,0 +1,9 @@
+# App Events (Workflow Events) Activities Playbooks
+
+**Package overview:** [overview.md](./overview.md) — what `UiPath.WorkflowEvents.Activities` is (internal UiPath Apps / Studio Web ↔ robot machinery), the RobotJS vs SignalR connection modes, and how each activity faults. These activities propagate raw .NET framework exceptions (no package-specific wrapper), so the **faulted activity class + exception class** is the primary discriminator. The user experiences these as **a job invoked by a UiPath App faulting** — the activity name appears in the job error / traces, not in their project.
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| Handle Apps Request — Null Reference | Medium | A UiPath-App-invoked job faults at `HandleAppRequest` with `System.NullReferenceException: Object reference not set to an instance of an object.`. The activity captures and returns the invoked workflow's own exception rather than rethrowing, so a job-faulting NRE here is a null dereference **inside the App-invoked workflow** or a required input argument the App did not supply. No SignalR/transport phrase = failure is in workflow execution, not the channel. | [handle-app-request-null-reference.md](./playbooks/handle-app-request-null-reference.md) |
+| Apps Request Trigger — Connection / Transport Lost | Medium | A UiPath-App-invoked job faults at `AppRequestTrigger` with `System.TimeoutException` (`SignalR connection did not establish within 60 seconds. Current state: <state>`), `System.IO.IOException` (transport/RobotJS pipe dropped while awaiting a request), or `System.InvalidOperationException` (SignalR client in an invalid state). All are App↔robot channel/transport failures — the App never connected within the timeout, a network/transport drop, or a lost/disposed hub. A missed heartbeat is handled gracefully (no fault). | [app-request-trigger-connection-lost.md](./playbooks/app-request-trigger-connection-lost.md) |
+| Initialize Apps Hub Connection — Aggregate Exception | Medium | A Studio Web app-workflow run faults at `InitializeHubConnection` with `System.AggregateException` (`One or more errors occurred. (<inner>)`). The background `StartConnectionAsync` logs (not throws), so the fault is the synchronous bootstrap — unwrap the inner: `WorkflowApplicationException: SignalR: Invalid SessionId: <id> OR Orchestrator Url: <url>` (blank session/URL context), a resource-URL/token-acquisition failure, or a transport/HTTP failure. | [initialize-hub-connection-aggregate-failure.md](./playbooks/initialize-hub-connection-aggregate-failure.md) |

package/skills/uipath-troubleshoot/references/escalation.md

@@ -0,0 +1,98 @@
+# Escalation — Competitive Hypotheses
+
+Load this file only when a SKILL.md escalation trigger fires. The fast path handles one dominant playbook match; escalation handles ambiguity: no match, co-equal matches, deep cross-domain chains, exhausted decision trees, or contradicted matches.
+
+## 1. Enumerate candidates
+
+Draft 2–4 candidate hypotheses in `.local/investigations/notes.md`:
+
+1. **One candidate per candidate playbook.** Candidates come from playbook grep matches, the no-signature routing table in `references/summary.md` (for silent failures), and cross-domain signals. Never draft a candidate from a playbook already eliminated by contradicting evidence — record eliminations in notes.md with the disproving datum.
+2. **Always add one "originating fault is upstream/elsewhere" candidate** — the possibility that every matched playbook describes a consequence and the true origin is a domain or entity not yet fetched. This candidate's probe follows the strongest cross-domain signal (wrapped inner exception, child job key, connection ID, parent instance).
+3. **Fault-signal-first ordering.** If any explicit fault signal exists (exception stack, error code, faulted state, incident), the candidate explaining what CAUSED that fault ranks first. Persistence, propagation, cleanup, or recovery-gap candidates rank after it.
+4. Each candidate records: description, source playbook path, supporting signals (a candidate with zero supporting signals is speculation — do not draft it), `to_confirm` evidence, and `to_eliminate` evidence. One candidate = one playbook at signature level; do NOT split a playbook's "What can cause it" list into separate candidates — those are branches its decision tree resolves.
+
+## 2. Probe in parallel
+
+Spawn one read-only probe subagent per candidate (2–4, concurrently, in one message). Probes gather evidence; they never conclude for you, never present, never ask the user.
+
+Probe prompt template — fill every {slot}:
+
+```
+Gather evidence for ONE troubleshooting hypothesis. Read-only: you fetch data and report; you do not conclude the investigation, modify files, or ask the user anything.
+
+Hypothesis: {description}
+Playbook: {absolute path} — read its ## Context and ## Investigation sections first.
+Confirm items: {to_confirm list}
+Eliminate items: {to_eliminate list — you MUST attempt every one; elimination evidence is first-class}
+
+Rules:
+1. Run ONLY uip commands documented in the playbook's ## Investigation section or the product overview's CLI section ({overview path}). No --help discovery, no guessed flags, no REST/curl workarounds.
+2. Redirect every CLI response: `uip ... --output json > .local/investigations/raw/h{n}-{command-name}.json`. Read back only needed fields. Before fetching, check .local/investigations/raw/ — reuse existing fetches of the same entity. (Probes deliberately use `>` uniformly — narrower than Invariant 4's conditional `tee` — to keep probe context minimal.)
+3. Every datum must match the reported entity, folder/tenant, and time window. Empty ≠ absent — verify the container exists. Live state ≠ historical state for incidents older than 24h.
+4. Max 2 retries per command; after 3 distinct command failures, stop and report the failures.
+5. Data unavailable → report the gap. Never invent or substitute.
+
+Return (structured): per confirm/eliminate item — supported / contradicted / no data, with the raw file path and the specific field values; open gaps; any signal pointing at a DIFFERENT domain or entity (report it — do not chase more than one hop).
+```
+
+Probes may run concurrently because each writes to its own `raw/h{n}-*` namespace and nothing else.
+
+### Serial fallback — no subagent tool
+
+Harness has no subagent-spawning tool → execute each probe yourself, sequentially, in this context. Same protocol, same budget; only the execution changes:
+
+1. Take candidates in §1 rank order. Per candidate, execute the probe-prompt rules verbatim (read-only, documented commands only, `raw/h{n}-*` namespace, retry caps).
+2. **Close each probe before opening the next**: write its structured return block (per confirm/eliminate item — supported / contradicted / no data, raw file + field; open gaps; cross-domain signals) into notes.md under `## Probe h{n}`. Adjudication reads ONLY these blocks — not your memory of the fetches.
+3. A probe surfacing a different-domain signal still stops at one hop — record it for adjudication; do not chase it mid-probe.
+4. Do not adjudicate early. A dominant-looking first probe does not skip the remaining candidates — elimination evidence from later probes is what separates siblings.
+5. **Single-candidate collapse:** when only one viable candidate exists (the upstream/elsewhere candidate has no concrete signal to chase), the probe round collapses to targeted fetches for that candidate's confirm/eliminate items. The structure still applies: per-item verdicts in notes.md, then the verifier.
+
+Then adjudicate per §3 unchanged.
+
+## 3. Adjudicate
+
+You (not the probes) decide, in notes.md:
+
+1. **Eliminate first.** A candidate with any contradicted `to_eliminate` item is out — record the disproving datum.
+2. **Upstream precedence.** A propagation/persistence/state-transition candidate cannot win while an upstream "why did the presupposed condition occur" candidate is untested or supported. If the upstream probe surfaced a new domain signal, follow it: re-grep the playbooks, and if it matches a new playbook, run that playbook's decision tree (fast-path §5) before concluding.
+3. **Runtime-evidence gate.** For runtime failures, the winning candidate needs ≥1 runtime datum (logs, job records, instance state, incidents) that passes correlation. Design-time evidence alone proves a defect exists, not that it caused this failure. All runtime queries empty while the user reports active failures = contradiction — wrong scope; re-verify scope or ask the user, do not conclude.
+4. Apply the SKILL.md verification checklist to the winner.
+
+No candidate survives → present findings and ruled-out candidates per `presenting.md` ("no root cause found" terminal). Do not loop generating new candidates more than once — a second full round requires new evidence or new user input.
+
+## 4. Fresh-eyes verifier (conditional)
+
+Spawn ONE read-only verifier subagent before presenting when ANY of:
+
+- The conclusion's confidence is medium or low
+- The winning branch is the playbook's default/fallback branch (the tree's "none of the above")
+- Co-equal candidates were adjudicated (trigger 2 fired)
+
+Verifier prompt template:
+
+```
+Verify a troubleshooting conclusion with fresh eyes. Read-only: no CLI, no file edits. Read .local/investigations/notes.md, the raw files it references, and the playbook at {path}.
+
+Conclusion under test: {cause statement + chosen resolution branch}
+
+Check:
+1. Specific cause named — the conclusion names ONE item from the playbook's "What can cause it" list (## Context), verbatim or tight paraphrase — not a category, not a vague generalization.
+2. Evidence pinned — the cited raw data contains a datum that singles out THIS cause from its siblings in the same list. Symptom-level data that fits multiple causes is not enough.
+3. Resolution alignment — the chosen fix is the ## Resolution branch keyed to that exact cause.
+4. Causal precedence — list every event the conclusion treats as given and ask "why did that occur?". A persistence/state-transition narrative presupposes an upstream condition ("state X didn't transition" presupposes "X was entered for a reason worth investigating"). Any unexplained upstream event that notes.md does not address → fail this check.
+
+Return: verdict `verified` or `shallow`; per failed check: whether the gap is FACTUAL (missing datum — a targeted re-fetch could fix it; name the exact datum) or TEXTUAL (imprecise cause naming / wrong branch label — re-fetching cannot fix it); one line per gap.
+```
+
+Route on the verdict:
+
+- `verified` → present.
+- `shallow` with factual gaps → ONE targeted re-fetch of the named datum (yourself or a single probe), then re-check. Still failing → treat as textual.
+- `shallow` with textual gaps → present at reduced confidence with the gap named. **Cause label and remediation path are separable**: an imprecise cause name does NOT invalidate the matched playbook's `## Resolution` procedure — an interactive resolution (e.g., apply recovered selector) still runs; never switch to another playbook's resolution just because it names the cause better. Only a resolution-alignment gap (check 3) changes the fix branch.
+
+No subagent tool → run the verifier's four checks yourself: re-read notes.md and every raw file the conclusion cites, answer each check in writing in notes.md under `## Self-verify`, then route on the verdict as above. Independence is lost — compensate by presenting at one confidence level lower than the adjudication assigned unless every check passes with a cited datum.
+
+## Boundaries
+
+- Probes and the verifier never talk to the user; every user question is asked by you, directly, after they return.
+- Total spawn budget per investigation: one probe round (2–4 probes) + optionally one verifier + at most one factual re-fetch round. Beyond that, present what is known with gaps named. The budget counts probes, not subagents — serial-fallback probes consume it identically.

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

@@ -13,6 +13,46 @@ Before using any fetched data, verify it matches the user's reported problem:
 
 If the data doesn't match: **discard it**. Do NOT use unrelated data as a proxy. Report the mismatch and ask for clarification.
 
+## Output Capture
+
+Every `uip` data-gathering command follows two patterns — lean context AND an audit trail:
+
+1. **Filter at the source with `--output-filter`** — pull only the fields you need. Do NOT fetch the full response and slice it (`[:3000]` etc.); that silently drops information.
+2. **Capture to `raw/`, matching the tool to the payload size:**
+   - **Small / filtered result** → `| tee .local/investigations/raw/<command>.json`: saves the file AND echoes the (already-small) result for immediate use the same turn.
+   - **Heavy or unfilterable result** (dense traces, full logs/stacks, `errorDetails`, or the fallback below) → `> .local/investigations/raw/<command>.json`, then read back only the fields/lines you need. Do NOT `tee` a full unfiltered response — it loads the whole body into context.
+
+   Run `mkdir -p .local/investigations/raw` once before the first fetch — neither `tee` nor `>` creates the directory and will otherwise drop the file silently.
+
+**Filter-failure fallback.** If `--output-filter` returns empty, an error, or an uninterpretable shape (usually a field name that drifted from the current CLI schema), retry the SAME command ONCE without `--output-filter` to see the actual shape. Capture that unfiltered retry with `>` (not `tee`) and read back only the fields you need; note the stale filter in your evidence summary. Do NOT silently swallow filter errors.
+
+**Anti-patterns:** `tee`-ing a full unfiltered response (dumps the whole body into context — use `>` + selective read-back); `| head -c N` or byte/character slicing (drops required fields); fetching the unfiltered full response when 2–3 fields suffice (bloats context); inventing JSONpath field names (use only documented filters; on failure apply the fallback above).
+
+## Signal-Extraction Cheatsheet
+
+Where each signal kind lives (fetch per the domain's `investigation_guide.md`; exact commands are documented there and in playbook `## Investigation` sections):
+
+| Signal kind | Where to find it |
+|---|---|
+| exception (class/FQN) | Job record `Info` field; error-level job logs; trace span error attributes; Maestro incident body. Unwrap `System.AggregateException` / `--->` chains — the INNER exception is the routable signal |
+| message / message-key | Verbatim friendly message in job `Info` / logs; localization resource keys quoted in UIA exception details |
+| error-code | Message text (`DAP-*`, `#NNNN`, `AADSTS*`, HRESULTs like `0x8004027D`); Maestro incident code (e.g. `170002`); job `PendingReasons.ErrorCodes` |
+| http-status | Message text ("Bad Gateway", "429"); trace span attributes |
+| state | Job `State` + `PendingReasons`; Maestro instance status + incident open/closed; connection status |
+| faulting activity + package | `[Name]` prefix in error log message bodies; span names; exception FQN prefix maps to the owning package (see `references/summary.md` domain namespaces) |
+| package versions | `project.json` dependencies (source-required); job record package version fields |
+
+## Locating Project Source & Resource Files
+
+A UiPath project ships in one of two layouts, and a named source or resource file (workflow, code, manifest, or a connection/asset/queue/bucket resource) may sit in either. Resolve BOTH before concluding a file is absent — this applies to every product, not just the one that named the file:
+
+- **Standalone** — resources inline under the project dir (e.g. `<project>/connection/<connector>/*.json`).
+- **Solution** — the project sits under a subdir and resources are hoisted into a solution wrapper at the **solution root**: the working directory, which is the *parent* of the named project dir — NOT inside it. E.g. from the working directory `resources/solution_folder/connection/<connector>/*.json`; likewise `resources/solution_folder/{package,process,asset,queue,bucket}/...`.
+
+**Search from the working-directory root, not only under a named project subdir.** When the user points you at a project dir (e.g. `./MyProject/`), the solution resources live beside it — one level up — at `./resources/solution_folder/...`. So look both **inside the named project** (standalone layout) AND **in the working-directory root / one level up from the project** (solution layout).
+
+When a playbook names a file at one layout's path and it is not there, check the other layout — including the solution root above the project dir — before treating it as missing. If neither resolves: data gap — ask the user for the correct path. Absence from one layout is NOT absence.
+
 ## Interpreting Query Results
 
 - **Empty results or 404** — before concluding an entity doesn't exist, verify the container (folder, tenant, instance) is still accessible. If the container was deleted or returns 404, all scoped queries are unreliable. Widen the search (different folder, broader time window, different state filters) or flag as a data gap and ask the user. Never treat empty results from an inaccessible container as proof of absence.
@@ -37,7 +77,7 @@ Before starting any investigation, establish what the user expects from the trou
 2. **If you cannot infer**, present the user with the options you identified (e.g., "Are you looking for the root cause, a quick fix, or help understanding why this happens intermittently?") and let them choose
 3. **If you have no options**, ask the user directly what outcome they need from this investigation
 
-Do NOT begin triage or hypothesis generation until the expected outcome is clear. It determines what depth of investigation is appropriate and what a useful resolution looks like.
+Do NOT begin the investigation until the expected outcome is clear. It determines what depth of investigation is appropriate and what a useful resolution looks like.
 
 ## Tool Boundary — uip CLI Only
 

package/skills/uipath-troubleshoot/references/knowledge-base-guide.md

@@ -6,8 +6,10 @@ This document describes how the troubleshooting knowledge base is structured, wh
 
 ```
 references/
-  summary.md                            <- Entry point. Routes agents to the correct product.
+  summary.md                            <- Domain descriptions, CLI entry points, no-signature routing.
   investigation_guide.md                <- Generic investigation rules (all products).
+  presenting.md                         <- Resolution formatting, fix assembly, approval gate.
+  escalation.md                         <- Competitive-hypothesis protocol (probes, verifier).
   templates/                            <- Templates for creating new playbooks.
   products/{id}/                        <- One folder per product.
     overview.md                         <- (optional) Product overview and dependencies.
@@ -39,11 +41,11 @@ Each product has different concerns. UI Automation needs to verify the correct a
 
 ### presentation.md (optional)
 
-Product-specific display rules for how to format entity names, IDs, and labels in user-facing output. Defines how to refer to the product's entities (e.g., connections by display name, jobs by process name, instances by BPMN process name). The presenter agent discovers and reads these directly based on the domains in `state.json.scope.domain`.
+Product-specific display rules for how to format entity names, IDs, and labels in user-facing output. Defines how to refer to the product's entities (e.g., connections by display name, jobs by process name, instances by BPMN process name). Read at presentation time (`references/presenting.md` § 1) for every domain in the causal chain.
 
 ### summary.md (required)
 
-The playbook index. Lists all playbooks for this product, organized by confidence level. This is how agents discover which playbooks exist and their confidence. Every new playbook must be added here.
+The playbook index. Lists all playbooks for this product, organized by confidence level. Runtime routing greps playbook files directly; this index is the browse and fallback surface (family-playbook routing, escalation, silent failures). Every new playbook must be added here.
 
 ### playbooks/ (required)
 
@@ -75,36 +77,32 @@ All playbooks use the same three headers:
 
 | Section | What goes here | Who reads it |
 |---------|---------------|-------------|
-| `## Context` | What the issue is, what causes it, what to look for. Always present. | Generator (to produce hypotheses — 1 for high-confidence, 2-5 for medium/low). Tester (for understanding). |
-| `## Investigation` | Steps to troubleshoot or verify. Can be absent for low-confidence playbooks. | Tester (follows steps if present, reasons freely if absent). |
-| `## Resolution` | Known fixes. Can be absent if the fix depends on what the investigation finds. | Presenter (assembles fixes for the user). |
+| `## Context` | What the issue is, what causes it, what to look for. Always present. | The investigator, to confirm the match fits the evidence and learn the cause list. |
+| `## Investigation` | Steps to troubleshoot or verify. Can be absent for low-confidence playbooks. | The investigator (follows steps in decision-tree order if present, reasons freely if absent). Escalation probes inherit these as their only allowed commands. |
+| `## Resolution` | Known fixes. Can be absent if the fix depends on what the investigation finds. | Presentation phase (`references/presenting.md` assembles fixes for the user). |
 
 Template: `templates/playbook-template.md`
 
-> **Note:** The canonical confidence-level behavior table (how each agent acts per confidence level) is in `agents/shared.md`. Keep this guide aligned with that table.
+### Greppable Signatures
 
-### Cross-Product References
-
-Playbooks may reference other product domains (e.g., an Orchestrator playbook mentioning "ProcessOrchestration" or "BPMN", a Maestro playbook referencing child Orchestrator jobs). When writing playbooks, use explicit product names when describing cross-domain behavior — the scope checker agent detects these references and flags missing domains for the orchestrator to expand scope.
-
-## How Agents Use This
-
-### Triage
+Routing greps playbook files directly, so a playbook is reachable only if its `## Context` quotes the failure's signals verbatim:
 
-Reads `summary.md` to find the right product, then reads the product's `summary.md` to find ALL matching playbooks. Records every match with its confidence in `state.json`. Multiple playbooks may describe the same issue — all are recorded. Triage does NOT read playbook contents or do cross-domain expansion — the scope checker handles domain detection separately.
+1. Quote in "What this looks like" the exact strings the real failure produces — exception class (FQN), verbatim message fragments, localization resource keys, error codes, HTTP statuses. Never paraphrase; trim placeholder segments.
+2. When two playbooks share a signal (same exception class, same message), each body must state its discriminator and explicitly redirect to the sibling playbook for the other case ("NOT for X → other-playbook.md").
+3. A playbook with no crisp greppable signal (silent failure, hang, wrong result) is a last resort — a distinctive log line or state combination is still a signature. Such playbooks are reachable only via the no-signature routing table in `references/summary.md` and the domain's `summary.md`.
+4. `confidence` (frontmatter) is a cap on root-cause certainty, not a routing rank.
 
-### Hypothesis Generation
-
-The generator reads `## Context` from matched playbooks and produces hypotheses per the confidence-level behavior table in `agents/shared.md`. Hypotheses are tested in confidence order (high first).
-
-### Testing
+### Cross-Product References
 
-The tester reads `## Context` for understanding, then scopes work per the confidence-level behavior table in `agents/shared.md`.
+Playbooks may reference other product domains (e.g., an Orchestrator playbook mentioning "ProcessOrchestration" or "BPMN", a Maestro playbook referencing child Orchestrator jobs). Use explicit product names when describing cross-domain behavior — cross-domain signals (entity keys, exception namespaces) are what route the investigator across the domain boundary.
 
-### Investigation Guides
+## How the Investigator Uses This
 
-The investigation guide (generic + product-specific) tells agents how to verify their data is correct before drawing conclusions. Applied regardless of playbook confidence.
+1. **Route** — greps the playbook corpus with extracted signals; loads only the matched playbook plus its domain's `investigation_guide.md`.
+2. **Walk** — confirms the match against `## Context`, executes `## Investigation` in decision-tree order, verifies the cause against the "What can cause it" list before presenting.
+3. **Escalate** — on ambiguity, `references/escalation.md` drafts one candidate per plausible playbook; probes gather evidence using only commands documented in the playbook or product overview.
+4. **Investigation guides** (generic + product-specific) define how to verify data correlation before drawing conclusions. Applied regardless of playbook confidence.
 
 ## Creating New Content
 
-Template is in `references/templates/playbook-template.md`. Copy it, set the `confidence` field in the frontmatter (high, medium, or low), fill in the sections, and add the entry to the product's `summary.md`. The summary's Confidence column must match the playbook's frontmatter.
+Template is in `references/templates/playbook-template.md`. Copy it, set the `confidence` field, quote the failure's verbatim signature strings in `## Context` per Greppable Signatures above, fill in the sections, and add the entry to the product's `summary.md` (Confidence column must match the frontmatter).

package/skills/uipath-troubleshoot/references/presenting.md

@@ -0,0 +1,143 @@
+# Presenting the Resolution
+
+Rules for the final user-facing resolution — formatting, entity naming, cross-domain fix completeness, evidence gating, and interactive fixes. Load this file when the verification checklist has passed (or a reduced-confidence / diagnostic-recommendation terminal applies) and you are ready to present.
+
+## Inputs
+
+- `.local/investigations/notes.md` — anchor, signals, matched playbook(s), branch decisions, checklist verdicts
+- `.local/investigations/raw/` — authoritative field values; quote entity names and values from here
+- Matched playbook(s) — `## Resolution` sections
+- `uip docsai ask "<question>" --source docs|technical_solution_articles` — for domains missing a playbook resolution
+
+## 1. Load presentation rules
+
+For each domain in the causal chain, read `references/products/{domain}/presentation.md` or `references/activity-packages/{domain}/presentation.md` if it exists. These define entity naming and field labels.
+
+## 2. Assemble fixes across all domains
+
+Classify each domain in the causal chain: **root cause domain** (failure originated) or **propagation domain** (failure surfaced or was relayed).
+
+### Root cause domain
+
+1. Matched playbook's `## Resolution` — if present, use the branch keyed to the verified cause.
+2. No `## Resolution` — run `uip docsai ask` targeted at the domain's fix. Use the result if concrete and actionable.
+3. Docsai returns nothing useful — write: "No documented fix found for the {domain} layer — check UiPath documentation or consult UiPath support."
+
+### Propagation domains
+
+For each domain that relayed or surfaced the fault:
+
+1. Matched playbook's `## Resolution` — if present, use it.
+2. Otherwise run `uip docsai ask` for that domain's error-handling / resilience patterns. Frame the query around the domain's role, not the specific root cause (e.g., "error boundary events for service tasks in Maestro", "retry policies for faulted jobs in Orchestrator", "fallback configuration for Integration Service connectors").
+3. Concrete pattern found → include as a preventive fix for that layer, citing the docsai result.
+4. Nothing useful → write: "No documented error handling pattern found for the {domain} layer — check UiPath documentation for resilience options."
+
+Do NOT write "No configuration change needed" for a propagation domain. Every domain in the causal chain gets either a fix or an explicit no-documented-pattern note.
+
+### Source gating
+
+Every fix step cites its source (playbook section, docsai result, or raw data file).
+
+- Preserve docsai URLs — full URL, not just a title.
+- Step with no documented source → drop it, or mark `[Unverified]` visibly.
+- Undocumented field/setting behavior → do NOT include. Write: "Check UiPath documentation for [{field/setting}] behavior before proceeding."
+
+### Discriminator carry
+
+The final answer states the discriminating datum, not just the verdict:
+
+- Name the datum that separates the confirmed cause from its sibling causes (the same evidence the verification checklist pinned) — "the recovered label matches the unchanged live button, so this is a mistyped selector, not a page change", not just "fix the selector".
+- Upstream "why" unproven after the checklist AND after every reachable evidence source is exhausted — including workflow source present in the working directory (check its top level; if the project is there, read it, do not enumerate around it) → enumerate the candidate explanations ranked by evidence (most likely first, one line each, each tagged by what would confirm it) instead of only flagging the gap. Enumeration is never a substitute for reading available source.
+
+## 3. Format
+
+```
+Root Cause: {description}
+
+What went wrong: {one sentence}
+
+Why: {root cause explanation — trace the full causal chain across all domains}
+
+Evidence:
+
+### {Domain} (Root Cause)
+- {bullets — quote specific field values, error messages, IDs, timestamps, state, per this domain's presentation rules}
+
+### {Domain} (Propagation)
+- {bullets}
+
+Immediate fix:
+
+### {Domain} (Root Cause)
+1. {What to do — concrete action with exact navigation path or command}
+  - Why: {cite evidence that makes this step necessary}
+  - Where: {exact file, UI path, setting, or command}
+  - Who: {RPA developer | admin | platform team | process owner}
+  - Source: {playbook path or docsai URL}
+
+### {Domain} (Propagation)
+1. {same structure}
+
+Preventive fix:
+
+1. {Domain} -- {What to change — concrete action}
+  - Why: {cite specific evidence showing the gap this fix addresses}
+  - Where: {exact file, UI path, setting}
+  - Who: {RPA developer | admin | platform team}
+  - Source: {playbook path or docsai URL}
+2. {next domain, same structure}
+```
+
+**Reduced-confidence terminal** (checklist gap survived the re-fetch): present the same structure, name the gap explicitly next to the cause statement, and lead the Immediate fix with the playbook's diagnostic recommendation (e.g., a byte-compare snippet) instead of a guessed branch. Recommending the discriminating diagnostic IS the deliverable when evidence cannot separate sibling causes — never silently pick one.
+
+**No root cause found**: present what was investigated and ruled out (from notes.md), and recommend providing more data or opening a UiPath support ticket.
+
+## 4. Apply presentation rules
+
+Check every entity name against the presentation guides and raw data:
+
+- Display names from raw data, not API property names or paraphrases
+- IDs only where needed for commands
+- UI labels, not API field names
+
+## 5. Investigation summary table
+
+| # | What was checked | Verdict | Key Evidence | Resolution |
+|---|------------------|---------|--------------|------------|
+
+One row per playbook/branch/candidate checked (from notes.md), including eliminated ones.
+
+## 6. Interactive resolutions — the approval gate
+
+If a matched playbook's `## Resolution` is **interactive** — it prescribes printing concrete values and asking the user before applying a fix (the Healing Agent apply-fix flow via `activity-packages/ui-automation/interpretations/healing-agent-data.md` is the canonical example) — execute this protocol after presenting. This applies even when the cause label was refined or downgraded: cause label and remediation path are separable; the playbook's remediation procedure remains authoritative.
+
+For each interactive action, in order:
+
+1. **Print the user-facing data as plain text** — NOT inside AskUserQuestion options or previews. E.g. for a selector fix:
+
+   ```
+   Failed selector:
+   {failed_selector_xml from raw data}
+
+   Recovered Partial selector:
+   {recovered_partial_selector_xml — or "(not available)"}
+
+   Recovered Fuzzy selector:
+   {recovered_fuzzy_partial_selector_xml — or "(not available)"}
+   ```
+
+2. **Print required warnings verbatim.** E.g. when `OrchestratorEnableHeal=false`: "Healing Agent was running in recommendation-only mode (OrchestratorEnableHeal=false) — the recovered selector was inferred from the UI tree after the failure but was not validated at runtime. There is no guarantee it will work." Analogous wording for `RecoverySuccessful=false`.
+
+3. **Ask via AskUserQuestion** — the exact apply/dismiss question, plus a project-path follow-up if the path is not already known.
+
+4. **On accept:** follow the playbook's linked procedure (e.g., `activity-packages/ui-automation/interpretations/healing-agent-data.md` § Applying `update-target` Fixes: prefer a package-provided skill like `uia-improve-selector` under `<PROJECT_DIR>/.local/docs/packages/`; otherwise edit the XAML activity matched by `ActivityRefId` with the playbook's XAML Selector Encoding rules; then validate with `uip rpa validate --file-path "<WORKFLOW_FILE>" --output json`). **After applying, the confirmation message must restate the confirmed root cause and the complete resolution** — it must stand alone as the investigation's summary for a user returning to only that message; never let it read as if the applied edit were the primary or only fix.
+
+5. **On decline or non-answer: do not modify files.** If AskUserQuestion is unavailable, present the proposed edit as plain text and stop — never fall through to editing.
+
+Pull every value from raw data. A required value missing (e.g., `recovered_partial_selector_xml`) → do NOT fabricate; surface the action as blocked, naming the missing evidence, and offer it as a follow-up.
+
+## Boundaries
+
+- Do NOT fabricate fix steps from undocumented field behavior — cite sources or flag `[Unverified]`.
+- `uip docsai ask` is the only CLI command this phase may add beyond what the playbook documents.
+- Diagnosis is autonomous; **mutation of user source files requires explicit in-channel approval** — no exceptions.