fix(uipath-rpa): coded UIA — headless ObjectRepository.cs regeneration, editor using hints, CodedWorkflow.cs restart fix, selector-only targets

skills/uipath-rpa/SKILL.md

@@ -39,7 +39,7 @@ Before doing any work, check `.claude/rules/project-context.md` in the project d
 
 Before creating or modifying anything, determine which project to work with. See [references/environment-setup.md](references/environment-setup.md) for the full procedure.
 
-**Quick check:** Find `project.json` to establish `{projectRoot}`. That's it — no Studio Desktop check needed for the standard loop. `uip rpa` auto-launches a headless Studio (UiPath.Studio.Helm NuGet) on first call. Studio Desktop is required only for `files diff`, `focus-activity`, and regenerating coded UI automation's `ObjectRepository.cs` (the `Descriptors.*` class — see Rule 7 and [environment-setup.md](references/environment-setup.md)).
+**Quick check:** Find `project.json` to establish `{projectRoot}`. That's it — no Studio Desktop check needed for the standard loop. `uip rpa` auto-launches a headless Studio (UiPath.Studio.Helm NuGet) on first call. Studio Desktop is required only for `files diff` and `focus-activity`. Coded UI automation's `ObjectRepository.cs` (the `Descriptors.*` class) regenerates on per-file `validate` once a `[Workflow]`/`[TestCase]` `.cs` is on disk (§ Capture-First Fast Path step 2; [coded/operations-guide.md § Configure UI Targets](references/coded/operations-guide.md#configure-ui-targets-object-repository)).
 
 ## Project Type Detection
 
@@ -75,7 +75,7 @@ For modern projects, determine whether this is a **coded** or **XAML** project:
 
 ### UI Automation Boundaries
 
-For any task whose business behavior is "open an app/browser, click, type, scrape visible UI, submit a form, or verify UI state", the interaction layer MUST be UiPath UI Automation — `NApplicationCard` plus UIA activities (XAML), or `uiAutomation.Open`/`Attach` plus Object Repository descriptors (coded). Do NOT substitute `InvokeCode`, PowerShell, Selenium, Playwright, Chrome DevTools Protocol, raw DOM JavaScript, HTTP form posts, or external browser-driver scripts. The coded fallback rows above apply only to non-UI helper logic (data transforms, parsing, DTOs, calculations, API-only integrations).
+For any task whose business behavior is "open an app/browser, click, type, scrape visible UI, submit a form, or verify UI state", the interaction layer MUST be UiPath UI Automation — `NApplicationCard` plus UIA activities (XAML), or `uiAutomation.Open`/`Attach` plus Object Repository descriptors — or, where the package's coded authoring guide § Selector-Only Targets allows it, CLI-captured selectors via `TargetAppModel` / `Target.FromSelector` — (coded). Do NOT substitute `InvokeCode`, PowerShell, Selenium, Playwright, Chrome DevTools Protocol, raw DOM JavaScript, HTTP form posts, or external browser-driver scripts. The coded fallback rows above apply only to non-UI helper logic (data transforms, parsing, DTOs, calculations, API-only integrations).
 
 If target configuration is unavailable, fall back to the documented UIA indication path — never to an external browser automation shortcut.
 
@@ -105,11 +105,11 @@ When the request is "automate this dialog/form" or "build a UI test from these m
 **Fast-path order for capture-first tasks:**
 
 1. **Read per Rule 7** — [uia-starter-guide.md](references/uia-starter-guide.md) and the UIA package's core guide (`{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md`), both IN FULL, plus the target-capture orchestration reference the core guide mandates.
-2. **Pre-flight Window Baseline** — list top-level windows once; decide whether to launch the app (package guide § Window Baseline).
-2a. **[Coded mode only] Write the workflow stub before capture** — an empty `[Workflow] public void Execute() { }` class. Studio generates `ObjectRepository.cs` descriptors only when a coded file is already on disk at the moment the Object Repository is written, so the stub makes the capture flow's own registration the trigger and you read real member names before writing the body. Preconditions and recovery: the coded authoring guide's § Step 1.
-3. **Inventory targets from manual steps** (Test Manager test case, PDD, or written script). Each "Click X" / "Enter Y" / "Select Z" / "Verify W" step maps to one OR element. Group by screen state (package guide § Capturing from Manual Test Steps), and decide every element and screen name now — apply them verbatim during capture.
-4. **Capture all targets** screen by screen via `uia-configure-target` and screen advancement (package guide § Multi-Step UI Flows). Authoring only at screen boundaries — never between capture calls within a screen.
-5. **Then enter authoring phase:** integrate project-context discovery (already dispatched if the precondition required it — at-most-once, never a second spawn), read your mode's authoring guide (Rule 7), write code, validate.
+2. **[Coded mode only] Install packages + write the stub, before the first `uip rpa` command** — install every activity package the workflow needs, and add an empty `[Workflow] public void Execute() { }` class (namespace per Rule 17), before the window baseline or any other `uip rpa` call. The host generates `.local/.codedworkflows/` from the packages and coded files present when it first loads the project; load it stub-less and authoring hits `CS0246 'CodedWorkflow'` (cleared only by a host restart). Only `ObjectRepository.cs` refreshes on later `validate` — `CodedWorkflow.cs`'s service accessors (`uiAutomation`, …) and the `workflows.X` cross-call methods are that first-load snapshot, so a later package install or new cross-called workflow needs a regen ([coded/operations-guide.md § Configure UI Targets](references/coded/operations-guide.md#configure-ui-targets-object-repository)).
+3. **Pre-flight Window Baseline** — list top-level windows once; decide whether to launch the app (package guide § Window Baseline).
+4. **Inventory targets from manual steps** (Test Manager test case, PDD, or written script). Each "Click X" / "Enter Y" / "Select Z" / "Verify W" step maps to one OR element. Group by screen state (package guide § Capturing from Manual Test Steps), and decide every element and screen name now — apply them verbatim during capture.
+5. **Capture all targets** screen by screen via `uia-configure-target` and screen advancement (package guide § Multi-Step UI Flows). Authoring only at screen boundaries — never between capture calls within a screen.
+6. **Then enter authoring phase:** integrate project-context discovery (already dispatched if the precondition required it — at-most-once, never a second spawn), read your mode's authoring guide (Rule 7), write code, validate. Coded: `validate` once to regenerate `ObjectRepository.cs`, read it, and reference every target as `Descriptors.<App>.<Screen>.<Element>` — member names come from that file, never from the OR names passed at capture. Never author against string target names while the file is missing.
 
 Skip this path when the task has no UI surface (data transforms, IS connector calls, headless file/email automation). Also skip it when the task HAS a UI surface but **no live app to capture against** (app not installed, no GUI, capture deferred to a developer) — there is nothing to capture, so use the § Placeholder-Selector Stub Pattern above instead. The Window Baseline does not tell you if the app is installed and has a GUI — validate that separately (e.g. look for the executable on disk) or ask the user.
 
@@ -151,7 +151,7 @@ On Windows PowerShell, `&` doesn't background — use `Start-Process powershell.
 6a. **Pre-edit verification gate.** Two authoring actions are hard to roll back once `build` fails — verify before serialization, not after.
    - **Removing a dependency** — grep the project for usages before deleting an entry. A package may be the sole supplier of an activity used elsewhere (`MergePDFs` lives in the IntelligentOCR.StudioWeb family).
    - **Writing a new activity tag** — confirm via `uip rpa activities find --query "<verb>" --output json` and use the returned `ClassName`. Do not derive tag names from Studio display names. See [common-pitfalls.md § Common Activity Name Confusions](references/xaml/common-pitfalls.md).
-7. **[UIA] Before writing ANY UIA activity (XAML `<uix:N*>` or coded `uiAutomation.*` / `Descriptors.*`), MUST read [references/uia-starter-guide.md](references/uia-starter-guide.md) — via a two-step read, never a plain full Read: (1) Grep `^## Conditional Policies` on it, (2) Read with `limit` set to that line; the two policy sections below the marker load only when their stated condition applies.** Then the UIA package's core guide it mandates (`{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md`) IN FULL, and — before authoring — your mode's authoring guide IN FULL (routed from the core guide's § Documentation). No exceptions for "simple" UIs. Skipping this rule is the most common cause of hallucinated selectors, wrong target XML, and missing OR descriptors. NEVER hand-write selectors — use `uia-configure-target` exclusively (the package guide explains how). The package guide exists only after the package is installed — verify [uia-starter-guide.md § UIA Prerequisites](references/uia-starter-guide.md) first (Rule 7a); if the package is installed but the guide file is absent, the installed version predates it — treat as below the minimum version. The starter guide owns the skill-side UIA policies: run/debug procedure + runtime selector recovery, the stub-mode deliverable pattern, and UI Library publishing.
+7. **[UIA] Before writing ANY UIA activity (XAML `<uix:N*>` or coded `uiAutomation.*` / `Descriptors.*`), MUST read [references/uia-starter-guide.md](references/uia-starter-guide.md) — via a two-step read, never a plain full Read: (1) Grep `^## Conditional Policies` on it, (2) Read with `limit` set to that line; the two policy sections below the marker load only when their stated condition applies.** Then the UIA package's core guide it mandates (`{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md`) IN FULL, and — before authoring — your mode's authoring guide IN FULL (routed from the core guide's § Documentation). No exceptions for "simple" UIs. Skipping this rule is the most common cause of hallucinated selectors, wrong target XML, and missing OR descriptors. NEVER hand-write selectors — use `uia-configure-target` exclusively (the package guide explains how); the coded selector-only path skips only the Object Repository registration, not the capture. The package guide exists only after the package is installed — verify [uia-starter-guide.md § UIA Prerequisites](references/uia-starter-guide.md) first (Rule 7a); if the package is installed but the guide file is absent, the installed version predates it — treat as below the minimum version. The starter guide owns the skill-side UIA policies: run/debug procedure + runtime selector recovery, the stub-mode deliverable pattern, and UI Library publishing.
 7a. **[UIA] Verify UIA prerequisites before invoking `uia-configure-target`.** The minimum version and the prerequisite check live in [uia-starter-guide.md § UIA Prerequisites](references/uia-starter-guide.md) — run that check first (do not hardcode the version from memory; that section is the only source of truth). If `UiPath.UIAutomation.Activities` is below the minimum or `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md` is absent (Rule 7 treats a missing guide as below-minimum), the `uip rpa uia` CLI is unavailable — and **both** target capture and indication depend on it, so indication is *not* a fallback when the package itself is missing. Ask the user to install/upgrade per that section. If they decline or the package cannot be installed, fall back to the **Placeholder-Selector Stub Pattern** (§ above) — real activities with `TODO Indicate` markers need no CLI. Never silently route to a non-existent skill path. Use indication capture only when a compatible UIA package *is* installed but `uia-configure-target` cannot see the element; record `UI capture: indication-only` in the plan header to skip `uia-configure-target` in that case. **Runtime failure counts too:** when the package is present but the UIA snapshot CLI's live scans fail persistently (driver/COM errors on every scan), first rule out a locked or non-interactive Windows session (`LogonUI` running = lock screen) — that needs an unlock, not a fallback. Only if scans still fail on an unlocked interactive session, treat capture as unavailable and use the Placeholder-Selector Stub Pattern.
 8. **Use `--output json`** on all CLI commands whose output is parsed programmatically.
 8a. **A `run` / `debug start` verdict comes from `Data` — NEVER from the outer `Result` alone, and NEVER from a log line's level — and `Data`'s shape depends on the backend that ran the workflow; identify it by its keys.** Headless Studio (Helm — no Studio Desktop instance has the project open): `Data` is `{output, hasErrors, errorMessage, profiling, debugState, debugDetails}`; passed only when `hasErrors` is `false`, `errorMessage` is `null`, and `debugState` is `null` or `"Completed"`; a faulted `run` returns outer `Result: "Failure"` with those fields JSON-encoded in `Message`; a faulted `debug start` returns `Result: "Success"` with `debugState: "Suspended"` and the exception in `debugDetails` — the session is still alive and must be cancelled or continued. Studio Desktop (the project is open in a running Studio): `Data` is `{output, errors, logEntries, debugState}`; passed only when `errors` is empty AND `output` is `"Session ended"` — a missing entry point returns `Result: "Success"` with `errors: []` and `output: "Failed to open the file <path>"`, so both conditions are needed. Reading `Result: "Success"` as a verdict reports broken workflows as green on both backends. A successful workflow may emit `Log Message` activities at `Error` or `Warning` level as observability — on Helm they stream as `[Level]` lines above the envelope, on Desktop they are `logEntries` entries — and they are workflow-emitted data, not failures; treating them as a failure signal flips green runs to "failed" and burns retries on healthy workflows. **Read the verdict from the envelope as printed: no `--output-filter` on `run` / `debug start` (the two backends have different keys, and a filter naming a key the current backend lacks fails the call after the workflow has already run), and never `| tail` / `| head` the payload — on Helm the log lines precede the envelope, on Desktop the verdict fields precede a long `logEntries`, so either cut drops something this rule needs** ([cli-reference.md § Capturing the verdict](references/cli-reference.md#capturing-the-verdict)). Field meanings: [cli-reference.md § Reading run / debug results](references/cli-reference.md#reading-run--debug-results) and [debugging.md § Output Format](references/debugging.md#output-format).

skills/uipath-rpa/assets/codedworkflow-template.md

@@ -2,7 +2,7 @@
 
 Ready-to-use templates for UiPath coded files — workflows, test cases, helper/utility classes, and Before/After hooks. Replace placeholders in `{{PLACEHOLDER}}` format.
 
-> **Using statements:** These templates include only the minimal required usings. Add service-specific usings based on actual usage — see [operations-guide.md § Coding Guidelines](../references/coded/operations-guide.md#coding-guidelines) for the full mapping.
+> **Using statements:** These templates include only the minimal required usings — keep them even when an editor flags them as unnecessary; only `uip rpa validate` / `build` decide. Add service-specific usings based on actual usage — see [operations-guide.md § Coding Guidelines](../references/coded/operations-guide.md#coding-guidelines) for the full mapping.
 
 ---
 

skills/uipath-rpa/references/cli-reference.md

@@ -206,7 +206,7 @@
 
 Read the project's UI **Object Repository** — the saved hierarchy of applications, screens, and elements (selectors/targets) that UI Automation activities bind to. Two read commands cover the project's own entries and those exposed by referenced libraries; both require an open project.
 
 > **Both verbs are top-level and hyphenated.** There is no `uip rpa object-repository` group — it returns `Unknown command: object-repository`, Studio running or not. Distinct from the UIA OR CLI, which writes entries and has no `get`.
 
 - **Project Object Repository** — `uip rpa get-object-repository` returns the project's *own* Object Repository as a JSON tree of applications → screens → elements, each entry carrying `name`, `description`, `type`, and `reference`. Entries inherited from referenced libraries are **excluded** (use the library command below for those). Takes no arguments beyond the standard `--project-dir`.
 
@@ -386,6 +386,8 @@
 
 `--skip-build` executes the existing compiled artifact — any edit since the last successful `build` is silently ignored. Use bare `run` after edits.
 
+**[Coded] Don't pair `build` with a default `run`/`debug start`.** `build` deletes `.local/.codedworkflows/WorkflowRunnerService.cs`, so a default `run`/`debug start` afterward re-validates the now-inconsistent generated set and fails `CS0246 'WorkflowRunnerService' does not exist in the namespace`. Use either **`build` → `run`/`debug start --skip-build`** (runs the built artifact) or a **bare `run`/`debug start`** (builds internally).
+
 **When to run:**
 1. Workflow has no compilation errors but you want to verify runtime behavior
 2. Workflow involves file I/O, API calls, or data transformations that could fail at runtime
@@ -429,9 +431,9 @@
 
 ```bash
 # Focus a specific activity by its IdRef (from the error output):
 uip rpa focus-activity --activity-id "Assign_1"
 # Focus all activities sequentially (useful for walkthrough):
 uip rpa focus-activity
 ```
 
 This is especially useful when:
@@ -493,7 +495,7 @@
 
 Output JSON includes the package `Id` (the package name Orchestrator stores) and `Version`. Hold on to the `Id` — `uip tm testcases link-automation` takes it as `--package-name`; `uip or processes create` takes it as `--package-key` (with `--package-version` separately).
 
 > **There is no `uip or packages publish` or `uip rpa publish`.** Agents that try those names get "unknown command". Pack writes a file; upload pushes that file. Two commands, two domains (`rpa`, `or`).
 
 ### Discovery cheatsheet
 
@@ -534,7 +536,7 @@
 | `timeout`, `ETIMEDOUT` | Cold Helm NuGet restore (30–90 s) or long operation. | Raise both limits together: shell `timeoutSeconds` toward its documented max, and `uip rpa --timeout <timeoutSeconds − 30> <command>` — the shell timeout must exceed `--timeout` by ≥ 30 s or the shell kills the CLI before it can cancel cleanly. For `validate`, also try `--skip-validation`. |
 | `not authenticated`, `401`, `403` | Auth required for cloud features. | `uip login`, then retry. |
 | `package not found`, `version not available` | Wrong package ID or version. | Verify via `uip rpa activities find`; omit `version` to auto-resolve latest. |
 | `project not found`, `no project open` | Wrong `--project-dir` or project not open. | Verify the path points at the `project.json` folder; if it persists, `uip rpa project open --project-dir "<PROJECT_DIR>"`. For Desktop-only verbs, check instances with the hidden `uip rpa instances list --output json` and run `uip rpa studio start` if none is up. |
 | `not in the project folder` (in `validate`) | Absolute `--file-path` + separator mismatch. | Pass `--file-path` relative to the project root (see [validate](#validate)). |
 | `Studio is busy`, `operation in progress` | Studio processing a prior request. | Wait a few seconds, retry. |
 | Unrecognized error | Unknown | Re-run with `--verbose` for debug detail, then inform the user. |