diff --git a/skills/uipath-rpa/SKILL.md b/skills/uipath-rpa/SKILL.md index 35d2e93584..ed2311ce42 100644 --- a/skills/uipath-rpa/SKILL.md +++ b/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...` — 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 "" --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 `` 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 `` 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 "`, 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). diff --git a/skills/uipath-rpa/assets/codedworkflow-template.md b/skills/uipath-rpa/assets/codedworkflow-template.md index 995d096873..e26e36e14b 100644 --- a/skills/uipath-rpa/assets/codedworkflow-template.md +++ b/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. --- diff --git a/skills/uipath-rpa/references/cli-reference.md b/skills/uipath-rpa/references/cli-reference.md index a607cfef80..99e2f3b4e0 100644 --- a/skills/uipath-rpa/references/cli-reference.md +++ b/skills/uipath-rpa/references/cli-reference.md @@ -386,6 +386,8 @@ uip rpa run --file-path "" --skip-build --log-level Verbose --output json `--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 diff --git a/skills/uipath-rpa/references/coded/operations-guide.md b/skills/uipath-rpa/references/coded/operations-guide.md index 11c3d8c8df..acd5f457b2 100644 --- a/skills/uipath-rpa/references/coded/operations-guide.md +++ b/skills/uipath-rpa/references/coded/operations-guide.md @@ -393,6 +393,9 @@ The UIA package guide (`{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.A **Key reminders:** - Add `using .ObjectRepository;` to any file referencing `Descriptors.*` - After target configuration, re-read `ObjectRepository.cs` — Studio regenerates it. Search for the reference IDs returned by `uia-configure-target` to find the exact `Descriptors...` paths. +- **Regenerating `ObjectRepository.cs`.** Write the coded stub before the first `uip rpa` command of the session (SKILL.md § Capture-First Fast Path step 2), so the host loads the project with a `.cs` present. Per-file `validate` then regenerates the file: after capture run `uip rpa validate --file-path ".cs" --project-dir "" --output json` once, then read it. `uip rpa get-object-repository --project-dir "" --output json` lists what the OR holds, as OR names, not C# members. +- **The coded base partials are a first-load snapshot.** `CodedWorkflow.cs` (service accessors — `uiAutomation`, `excel`, …) and `WorkflowRunnerService.cs` (`workflows.X` cross-calls) are generated from the packages and workflow files present when the host first loads the project, and do NOT refresh in-session (only `ObjectRepository.cs` does). So install every activity package **and** write the stub before that first `uip rpa` command. Install a package or add a cross-called workflow afterward and its member is missing (`CS0103 'uiAutomation'`, or `workflows` lacks the method) — a plain restart does not fix it: delete `.local/.codedworkflows/`, restart the headless host, then `validate`. +- **Every Object Repository target is `Descriptors...`.** Do not substitute the `string target` overloads (`app.TypeInto("First Name Input", …)`) or a constants class of OR names when `ObjectRepository.cs` is missing — regenerate it. String overloads are for target names computed at runtime only. Projects with no Object Repository by design (test suites, runtime-computed selectors) use the selector-only path — package coded authoring guide § Selector-Only Targets — with selectors captured by the UIA CLI, never typed. --- @@ -432,6 +435,8 @@ Detailed coding rules, best practices, anti-patterns, and troubleshooting for co **CRITICAL: Only include `using` statements for namespaces actually used in the file.** Adding usings for packages not in `project.json` will cause compile errors. +**Ignore editor "unnecessary using" hints.** A UiPath project has no `.csproj`, so IDE diagnostics on a `.cs` (`Using directive is unnecessary` / IDE0005) run without the project's references. `uip rpa validate` / `build` is the only compile verdict. There are no implicit or global usings: `System` supplies `Exception`, `TimeSpan`; `System.Collections.Generic` → `List`, `IDictionary`; `UiPath.CodedWorkflows` → `[Workflow]`, `[TestCase]`, `LogLevel`, `IBeforeAfterRun`, `CodedWorkflowBase`. + **Minimal using statements** (always safe in any workflow/test case file): ```csharp using System; @@ -452,9 +457,13 @@ using UiPath.Testing.Enums; // only if using testing enums using UiPath.Testing.Activities.TestData; // only if using test data queues // If using uiAutomation.* service (UiPath.UIAutomation.Activities package): -using UiPath.UIAutomationNext.API.Contracts; -using UiPath.UIAutomationNext.API.Models; -using UiPath.UIAutomationNext.Enums; +using UiPath.UIAutomationNext.API.Contracts; // IUiAutomationAppService +using UiPath.UIAutomationNext.API.Models; // UiTargetApp, TargetAppOptions, TypeIntoOptions and other *Options, TargetAnchorableModel, TargetAppModel, RuntimeTarget +using UiPath.UIAutomationNext.Enums; // NAppOpenMode, NAppCloseMode, NInteractionMode, NCheckStateMode, NEmptyFieldMode — the N* option enums (trigger enums: UiPath.UIAutomationNext.Triggers) +// `using var app = uiAutomation.Open(...)` needs only the Models/Enums usings above. + +// If a field, property, or parameter is declared as IElementDescriptor / IScreenDescriptor: +using UiPath.CodedWorkflows.DescriptorIntegration; // If using Object Repository descriptors (Descriptors.App.Screen.Element): using .ObjectRepository; // e.g. using RoboticEnterpriseFramework.ObjectRepository; @@ -512,8 +521,8 @@ UiPath ships first-class types for the patterns coded workflows most commonly ne | **`UiPath.Robot.Activities.BusinessException`** | `UiPath.Robot.Activities` | Same role as `BusinessRuleException` in robot-side custom activity packages. | Same — do not define your own. | | **`UiPath.Core.Activities.Storage.IResource` / `ILocalResource`** | `UiPath.Core.Activities.Storage` (in `UiPath.System.Activities`) | File / folder handles passed to activities that need an `IResource`. | Pass raw `string` paths or hand-roll a `LocalResource` constructor (the constructor is internal — see § IResource / ILocalResource below). | | **`UiPath.Orchestrator.Client.Models.QueueItemDto`** and related | `UiPath.Orchestrator.Client.Models` (in `UiPath.System.Activities`) | Queue-item shape returned by `GetTransactionItem` / pushed via `AddQueueItem`. | Define a project-local queue-item record that diverges from Orchestrator's schema. | -| **OR descriptors `Descriptors...`** | Generated into `/.local/.codedworkflows/ObjectRepository.cs` | UI element targeting in coded UI automation. | Hand-roll selector strings or `TargetAppModel` instances; bypass the Object Repository. | -| **`UiPath.CodedWorkflows.CodedWorkflow`** | `UiPath.CodedWorkflows` (built into the runtime) | Base class for `[Workflow]` and `[TestCase]` classes. | Inherit from a custom base; the Studio wrapper generation depends on this exact type. | +| **OR descriptors `Descriptors...`** | Generated into `/.local/.codedworkflows/ObjectRepository.cs` | UI element targeting in coded UI automation. | Type selector strings from memory; pass OR element names as strings (`app.Click("Submit Button")`) or through a constants class. Selector-only path (CLI-captured selectors into `TargetAppModel` / `Target.FromSelector`): package coded authoring guide § Selector-Only Targets. | +| **`CodedWorkflow`** | Generated partial in the project namespace (`.local/.codedworkflows/CodedWorkflow.cs`), deriving from `UiPath.CodedWorkflows.CodedWorkflowBase` | Base class for `[Workflow]` and `[TestCase]` classes. | Inherit from a custom base; the Studio wrapper generation depends on this exact type. | #### Throwing `BusinessRuleException` correctly @@ -552,11 +561,11 @@ Four built-in Workflow Analyzer rules with scope `Coded Workflow` run as Roslyn - **ALWAYS search for existing .cs files BEFORE generating new code** — Learn from existing patterns - Read at least 5 existing workflow files (or all if fewer) to understand project conventions - **When writing UI automation code** — the UIA package guide (`{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md`) MUST be read IN FULL first (SKILL.md Rule 7). Follow its **Finding Descriptors** hierarchy in strict order. Do NOT write any UI code until descriptors are resolved: - 1. Read `ObjectRepository.cs` — use existing descriptors if present. An empty `public static class Descriptors { }` does NOT mean "nothing registered"; it means Studio has not generated yet. Generation fires on an Object Repository write, and only when a Studio Desktop **window** is open on the project and a `[Workflow]`/`[TestCase]` `.cs` is already on disk; `validate`/`build` never trigger it. Write the coded stub before capture to avoid this; if already stuck, re-issue any write via the OR CLI. Member names are not the OR names verbatim, and the app segment is not always the app name — re-read the file before concluding a descriptor is missing or guessing its identifier. Preconditions, recovery, and naming transforms: the package guide's § Step 1 and § Descriptor Naming + 1. Read `ObjectRepository.cs` — use existing descriptors if present. A missing file or an empty `public static class Descriptors { }` does NOT mean "nothing registered"; it means Studio has not generated yet — regenerate per [§ Configure UI Targets](#configure-ui-targets-object-repository) before concluding anything, and never author against string target names meanwhile. Member names are not the OR names verbatim, and the app segment is not always the app name — re-read the file before concluding a descriptor is missing or guessing its identifier. Naming transforms: the package guide's § Descriptor Naming 2. Inspect UILibrary/descriptor NuGet packages in `project.json` (e.g. `*.Descriptors`, `*.UILibrary`) using `uip rpa packages inspect`. The tool checks the local NuGet cache automatically. If the package is still not found, read `.metadata` files manually at `~/.nuget/packages///contentFiles/any/any/.objects/` to discover App/Screen/Element hierarchy 3. If descriptors are still missing — use the `uia-configure-target` skill flow (found in the UIA activity-docs) to create targets. This handles capturing the application, discovering elements, generating selectors, improving them, and registering them in the OR. Do NOT manually call the internal `uip rpa uia` CLIs outside of the skill flow. Fallback: the indication commands (see UIA docs) when elements appear only after user interaction (e.g., a compose form that opens after clicking a button) 4. UITask (ScreenPlay) is ONLY for when selectors are genuinely brittle/unreliable — NEVER as a first approach - 5. NEVER bypass Object Repository by constructing `TargetAppModel` with raw URL/BrowserType + 5. Selector-only targets (`TargetAppModel` + `Target.FromSelector`, selectors captured by the UIA CLI) replace descriptors only in the cases the package's coded authoring guide § Selector-Only Targets lists — no Object Repository by design, or runtime-computed selectors. Never as a shortcut around capture, never with hand-typed selectors or a raw URL/BrowserType `TargetAppModel` - Use `uip rpa packages inspect` for API discovery when documentation is unclear ### IResource / ILocalResource — Converting File Paths @@ -635,13 +644,14 @@ C) ### UI Automation -- Never hardcode UI selectors — use Object Repository descriptors +- Never type selectors from memory — Object Repository descriptors by default; CLI-captured selector strings only on the selector-only path (package coded authoring guide § Selector-Only Targets) +- Never pass Object Repository targets by string name or through a constants class of OR names because `ObjectRepository.cs` is missing or empty — regenerate it (§ Configure UI Targets) and use `Descriptors.*` - Never write UI code referencing descriptors without first reading `ObjectRepository.cs` - Never manually craft UI selectors by calling the internal `uip rpa uia` CLIs outside of the `uia-configure-target` skill flow — this skips selector improvement and OR registration - Never skip the target configuration step when a descriptor is missing — use the `uia-configure-target` skill flow (fallback: indication commands per the UIA docs) - Never use UITask (ScreenPlay) as the primary approach — resolve descriptors via Finding Descriptors hierarchy first (Critical Rule #15) - Never skip configuring targets because it "seems tedious" — configure ALL missing elements -- Never construct `TargetAppModel` with raw URL/BrowserType to bypass Object Repository +- Never construct `TargetAppModel` from a raw URL/BrowserType or a hand-typed selector — its `Selector` comes from the UIA CLI's app resolution, and only on the selector-only path - Never skip checking UILibrary/descriptor NuGet packages in `project.json` - Never use an element descriptor on the wrong screen handle — each `UiTargetApp` is bound to its screen. Wrong handle gives `"Target name 'X' is not part of the current screen."` - Never use `SelectItem` on web dropdowns without a `TypeInto` fallback — web `