@uipath/skills 1.197.1 → 1.198.0-preview.21

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

@@ -76,7 +76,7 @@ A `Log("LoginWorkflow: type username")` stub:
 
 A real `<uix:NTypeInto>` activity with placeholder selector + `TODO Indicate` marker:
 
-- Build/validate may surface "selector incomplete" warnings — useful, since they tell the developer what is left to do.
+- Build/validate surface the unconfigured targets ("Target or Input UI Element must be set" — hard errors in current packages) — useful, since they tell the developer what is left to do. A stub-mode deliverable therefore does NOT reach a clean `build`; its acceptance bar is that the ONLY remaining validate/build errors are the expected unconfigured-target ones.
 - The activity is wired into the workflow's control flow, package dependencies, scope, and Object Repository registration plumbing. The developer's only remaining work is **Indicate**.
 - The TODO marker is visible in Studio's designer pane and grep-able in the file.
 - The cost of "what does this stub actually need from the developer?" drops from "read this carefully and infer" to "click Indicate on the marked activities."
@@ -199,13 +199,13 @@ When a procedure exists specifically to check something against ground truth, do
 
 ## Common UIA Pitfalls
 
-- **SelectItem on web dropdowns** — use `SelectItem` for native HTML `<select>` elements (deterministic). It fails on custom dropdown widgets (div/`<ul>`/ARIA hierarchies that only *look* like a `<select>`) — there, click to open and click the option, or use `TypeInto`. Detail: [uia-elements-interaction-guide.md § Web Controls](uia-elements-interaction-guide.md).
+- **Choosing SelectItem vs click-to-open for dropdowns/lists** — whether `SelectItem` drives a control is independent of its UI stack, tag, or role (native `<select>`, WinForms/WPF combo, Java/SAP list, ARIA combobox — all candidates). Don't guess from the selector — query the control's `items` attribute via the interact CLI: if it lists options → `SelectItem` drives it (pass one of them), no option-element capture needed; if empty/absent → fall back to click-to-open + click-option (or `TypeInto`). Procedure and syntax: [uia-elements-interaction-guide.md § Dropdowns, lists, and comboboxes](uia-elements-interaction-guide.md).
 - **ScreenPlay overuse** — UITask/ScreenPlay is non-deterministic and slow. Always try proper selectors first.
 - **Wrong Object Repository references** — never copy references from examples or other projects. Always use `uia-configure-target` to generate them for the current application state.
 - **Using `InjectJsScript` instead of standard activities** — do NOT use `InjectJsScript` when standard UI activities (GetText, Click, TypeInto, ExtractTableData, etc.) with configured targets would work. `InjectJsScript` is a last resort — it's hard to debug, fragile to page changes, and bypasses the Object Repository.
 - **Hallucinated keyboard shortcuts instead of UIA targets** — do NOT send keyboard shortcuts (`Ctrl+S`, `Alt+F4`, `Tab` navigation, menu mnemonics, etc.) as a substitute for clicking or typing into a real UI element. `Click` and `TypeInto` against configured targets are deterministic, survive layout changes, and are observable in logs; guessed shortcuts depend on focus, locale, and version. Reserve keyboard shortcuts for genuinely hotkey-only operations (commands with no clickable surface) and confirm the shortcut exists in the live app — never infer from OS convention or muscle memory.
 - **Chaining keystrokes in one `NKeyboardShortcuts` after one navigates away faults on a stale node.** The activity resolves its `Target` **once**; if the first shortcut destroys/replaces that element (a navigation key that changes the view), a second shortcut chained in the same activity (multi-shortcut `Shortcuts` string or `DelayBetweenShortcuts`) hits the stale node and throws `InvalidNodeException: "The UI element is invalid..."`. Example: Explorer `Alt+Up` (go to parent, auto-selecting the current folder) + `Alt+Enter` (open Properties) in one activity targeting "Items View" — `Alt+Up` navigates, then `Alt+Enter` faults on the destroyed node. **Fix:** use **separate** `NKeyboardShortcuts` activities so the follow-up **re-resolves** its target against the new screen, plus a small `DelayBefore` to let it settle.
-- **Unnecessary `Delay` activities before UIA actions** — UIA activities (`NClick`, `NTypeInto`, `NSelectItem`, `NGoToUrl`, etc.) have embedded target-finding resilience: they retry the selector lookup for a configurable timeout before failing. A `Delay` placed in front of a UIA activity to "let the UI settle" is almost always redundant and inflates workflow runtime without changing correctness. Include `Delay` only when ALL of: the wait is NOT for a UI element that a following UIA activity will target; a concrete non-retry reason exists (post-action animation with no UIA anchor, fixed-duration business pause, background job the UI doesn't reflect); and the caller can state in one sentence why the next UIA activity's built-in retry is insufficient. A button that is present but **disabled** during async validation/load/refresh is a separate case retry does not cover — use the activity's `DelayBefore`/`DelayAfter` *properties* (not a `Delay` activity): [uia-elements-interaction-guide.md § Web Controls](uia-elements-interaction-guide.md).
+- **Unnecessary `Delay` activities before UIA actions** — UIA activities (`NClick`, `NTypeInto`, `NSelectItem`, `NGoToUrl`, etc.) have embedded target-finding resilience: they retry the selector lookup for a configurable timeout before failing. A `Delay` placed in front of a UIA activity to "let the UI settle" is almost always redundant and inflates workflow runtime without changing correctness. Include `Delay` only when ALL of: the wait is NOT for a UI element that a following UIA activity will target; a concrete non-retry reason exists (post-action animation with no UIA anchor, fixed-duration business pause, background job the UI doesn't reflect); and the caller can state in one sentence why the next UIA activity's built-in retry is insufficient. A button that is present but **disabled** during async validation/load/refresh is a separate case retry does not cover — use the activity's `DelayBefore`/`DelayAfter` *properties* (not a `Delay` activity): [uia-elements-interaction-guide.md § Buttons disabled during async operations](uia-elements-interaction-guide.md).
 - **`Cannot send input ... outside of screen bounds` on hover-revealed elements** — pop-up menu items, autocomplete entries, and dropdown rows that only appear after a hover/click frequently fail under the default input method. Switch the affected activity (or its UIA interact CLI counterpart) to a simulated input method. Available input-method values: `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/references/cli-reference.md`.
 - **`HealingAgentBehavior` enum split between card and child activities.** `NApplicationCard` (Use Application/Browser) accepts `NHealingAgentBehavior` — values `Job`, `Disabled`, `RecommendationOnly`. Child activities (`NClick`, `NTypeInto`, `NCheckState`, etc.) accept `NChildHealingAgentBehavior`, which adds `SameAsCard`. Putting `SameAsCard` on the card itself fails with `Failed to create a 'HealingAgentBehavior' from the text 'SameAsCard'`. When introducing a new card (e.g., a nested card for a sign-in subprocess), set its `HealingAgentBehavior` to `Job`/`Disabled`/`RecommendationOnly` — never copy the value from a child activity. Confirm via `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/activities/common/NHealingAgentBehavior.md` and `NChildHealingAgentBehavior.md`.
 
@@ -213,15 +213,15 @@ When a procedure exists specifically to check something against ground truth, do
 
 ## Control-Specific Interaction Patterns
 
-> **MANDATORY — read and apply before authoring.** Before writing any `TypeInto`, `SelectItem`, or `Click` (XAML `NTypeInto` / `NSelectItem` / `NClick`, or coded `uiAutomation.*`) against a captured target, classify the control. If **any** target is a date / time input, a dropdown, or a button that can be disabled during async work, you MUST read [uia-elements-interaction-guide.md](uia-elements-interaction-guide.md) IN FULL and apply it **before** authoring that activity — the same bar as target capture ([§ Configuring Targets](#configuring-targets-object-repository)). The correct technique is type-specific and documented there: a date field must be typed in its **displayed** format (not ISO) via a key-event method, dropdowns split into native (`SelectItem`) vs. custom (click-to-open), and async-disabled buttons need `DelayBefore`. Apply the documented method up front — do not guess a value (e.g. ISO into a date field) and iterate against the running app.
+> **MANDATORY — read and apply before authoring.** Before writing any `TypeInto`, `SelectItem`, or `Click` (XAML `NTypeInto` / `NSelectItem` / `NClick`, or coded `uiAutomation.*`) against a captured target, classify the control. If **any** target is a date / time input, a dropdown, or a button that can be disabled during async work, you MUST read [uia-elements-interaction-guide.md](uia-elements-interaction-guide.md) IN FULL and apply it **before** authoring that activity — the same bar as target capture ([§ Configuring Targets](#configuring-targets-object-repository)). The correct technique is type-specific and documented there: a date field must be typed in its **displayed** format (not ISO) via a key-event method, for dropdowns/lists you decide by querying the control's `items` attribute (via the interact CLI) rather than by tag/role — items listed → `SelectItem`, none → click-to-open, and async-disabled buttons need `DelayBefore`. Apply the documented method up front — do not guess a value (e.g. ISO into a date field) and iterate against the running app.
 
 After a target is captured, these control types need type-specific handling to drive correctly:
 
 - **Date / formatted date-time inputs** — type the field's **displayed** format (e.g. en-US `MM/DD/YYYY`), not the ISO `value`.
-- **Dropdowns** — native HTML `<select>` → `SelectItem`; custom widgets → click-to-open + click option / `TypeInto`.
+- **Dropdowns / lists / comboboxes** — query the control's `items` attribute (via the interact CLI); items listed → `SelectItem`, none → click-to-open + click option (or `TypeInto`). Independent of tag / role / UI technology.
 - **Buttons disabled during async ops** — present but `disabled` during validation/load/refresh; use the activity's `DelayBefore`/`DelayAfter` properties (not a `Delay` activity).
 
-Patterns are organized by UI technology (currently web controls, `webctrl`): [uia-elements-interaction-guide.md](uia-elements-interaction-guide.md).
+Patterns there cover web-specific controls (date inputs) plus cross-technology ones (dropdowns/lists, async-disabled buttons): [uia-elements-interaction-guide.md](uia-elements-interaction-guide.md).
 
 ---
 
@@ -293,6 +293,16 @@ Install the UI Library as a package dependency; its descriptors appear under **U
 
 Skipping steps 4-5 causes the next run's open-if-not-open behavior to reuse a stale window in whatever state it was left in, or -- if the selector doesn't match -- to spawn a duplicate instance.
 
+### Advanced Debugging — Profiling
+
+For advanced debugging, add `--profiling` to collect insightful per-activity execution data, timings, and before- and after-execution screenshots:
+
+```bash
+uip rpa debug start --file-path "<FILE>" --project-dir "<PROJECT_DIR>" --output json --profiling
+```
+
+Use the before-execution screenshot to confirm the application/element started in the correct state, and the after-execution one to validate the expected outcome. Each screenshot's filename is recorded in the run's `.uistat` file; the image sits in the `Screenshots` folder in the same directory as that `.uistat` file. See [debugging.md § Profiling Workflow Performance](debugging.md#profiling-workflow-performance) for details.
+
 ### Runtime Selector Failure Recovery
 
 "UI element not found", "UI element is invalid", element not on screen -- these surface at runtime, not during static validation. They occur when a selector was captured against one app state but the DOM changed by the time the activity executes.
@@ -497,7 +507,7 @@ Example — copy a value from App A and paste it into App B. Outer card → App
                 <uix:NApplicationCard.Body>
                     <Sequence sap2010:WorkflowViewState.IdRef="Sequence_2">
                         <!-- ScopeIdentifier = App A card's ScopeGuid → reads from App A (outer) -->
-                        <uix:NGetText DisplayName="Get value from App A" Text="[out_Value]"
+                        <uix:NGetText DisplayName="Get value from App A" TextString="[out_Value]"
                                       ScopeIdentifier="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
                                       sap2010:WorkflowViewState.IdRef="NGetText_1" Version="V5" />
                         <!-- ScopeIdentifier = App B card's ScopeGuid → pastes into App B (inner) -->

package/skills/uipath-rpa/references/uia-configure-target-workflows.md

@@ -166,12 +166,12 @@ Workflow steps, response shape, downstream OR regeneration for coded vs XAML, an
 
 Once targets are registered in the OR (via `uia-configure-target` or indication fallback), attach them to XAML activities per `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/references/uia-target-attachment-guide.md`. That doc owns the concrete subcommands, flags, and response shapes for both attachment paths.
 
-**Path-choice policy (this skill's scope — which path to take, not how to invoke it).** The attachment guide describes two paths; they are not interchangeable for agent-authored XAML:
+**Path-choice policy (this skill's scope — which path to take, not how to invoke it).** The attachment guide describes two paths:
 
-- **Embed path — DEFAULT for agent-authored XAML.** Inline the OR-resolved target XAML as a child of the consuming activity element directly in the file you just wrote. Works on cold files — the project does not need to be loaded in Studio's in-memory designer. This is the only path that reliably works for XAML the agent has just generated or just edited from disk.
-- **Link path — only for files already loaded in Studio Desktop's designer.** Resolves an OR entry against an activity reference inside Studio's loaded workflow model. Requires the workflow to be open and parsed by Studio Desktop (not Studio Helm / headless). Use this only when the user has the file open in the designer or an existing Studio session already loaded the project.
+- **Link path — DEFAULT.** Attach OR entries to activities by their `sap2010:WorkflowViewState.IdRef` — screen first, then all element targets in one batched call. The file does not need to be open in Studio.
+- **Embed fallback — per-reference, only on a link failure.** If a link call fails for a specific reference, inline that reference's OR-resolved target XAML as a child of the consuming activity element — scoped to only the failed reference, not the whole screen.
 
-When generating a new XAML file or editing one that has not been opened in Studio Desktop in this session, take the embed path. Do not attempt the link path on cold XAML — it produces resolution failures that look like activity-id / display-name mismatches but are actually "the file isn't in Studio's model yet" (see § CLI Pitfalls).
+Take the link path first. On a link failure for a reference, drop straight to the embed fallback for that one reference — do not iterate through activity-id / display-name variations (see § CLI Pitfalls). The package attachment guide is source-of-truth when it diverges from this skill (per SKILL.md).
 
 ### Multi-Screen Workflows
 
@@ -185,4 +185,4 @@ Runtime symptoms that have wasted entire capture sessions. Canonical flag list,
 - **Selector resolution rejects bare element refs (`Invalid --refs entry`).** Each ref must be paired with the definition file that owns it.
 - **OR element-creation rejects inline JSON.** The OR CLI consumes pre-written per-element definition files only. Generate the definition files first, then invoke create-elements with their paths.
 - **UIA interact actions reject discovery and global flags (`unknown option`).** Interact subcommands accept only interaction-shape flags. Folder, ref, and project-dir style flags belong to other UIA subcommand families.
-- **Link path against a cold XAML file fails with `Could not retrieve the activity from the workflow`.** This means the target file is not loaded in Studio Desktop's in-memory designer model — not that the activity-id, display name, or reference ID are wrong. Stop after the **first** failure; do not iterate through activity-id / display-name / property-name variations. Switch to the embed path (see § Attaching Targets to Workflow Activities). The link path is reserved for files that an active Studio Desktop session has already opened and parsed; XAML the agent has just written from disk does not qualify.
+- **A link call fails with `Could not retrieve the activity from the workflow`.** Not an activity-id / display-name / reference-ID problem — do not iterate on those. Stop after the **first** failure for that reference and use the embed fallback (see § Attaching Targets to Workflow Activities).

package/skills/uipath-rpa/references/uia-elements-interaction-guide.md

@@ -50,22 +50,31 @@ Why try without emptying first: native date inputs and framework date-time picke
 formScreen.TypeInto(Descriptors.MyApp.Form.InvoiceDate, formattedDate);
 ```
 
-### Dropdowns — native `<select>` vs custom widgets
+---
 
-Branch on what the control actually is:
+## All UI Technologies
 
-| Control | How to drive |
-|---------|--------------|
-| **Native `<select>`** (real HTML `<select>` / `<option>`) | `SelectItem`, passing the option text. Deterministic. |
-| **Custom dropdown** (div/`<ul>`/`<li>`/ARIA hierarchy that only *looks* like a dropdown — no `<select>` tag) | `SelectItem` fails. Click to open, then `Click` the option element (capture both as OR targets). Use `TypeInto` for type-ahead / filter combos. |
+Patterns that apply to any captured control regardless of UI stack (web, desktop, Java, etc.).
 
-Tell them apart from the captured selector: a native control's element carries `tag='SELECT'`; a custom widget resolves to `DIV`/`UL`/`LI`/`SPAN`, typically with `role='combobox'` / `'listbox'` / `'option'`.
+### Dropdowns, lists, and comboboxes
 
----
+Whether `SelectItem` (`NSelectItem`) can drive a control does **not** depend on its UI technology,
+tag, or role — a native HTML `<select>`, a WinForms/WPF combo box, a Java list, a SAP dropdown, and
+a div/ARIA combobox are all candidates. **Don't classify it from the captured selector — query the
+control's `items` attribute for its selectable options** (the read verb is in
+`{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/references/cli-reference.md`):
 
-## All UI Technologies
+- **`items` lists options** → the control is selectable; `SelectItem` will drive it — pass one of the
+  listed values. No need to capture the individual option elements or open the list first.
+- **`items` empty/absent** → not a real option-list control. Fall back to click-to-open + click the
+  option (capture both as OR targets), or `TypeInto` for type-ahead / filter combos.
 
-Patterns that apply to any captured control regardless of UI stack (web, desktop, Java, etc.).
+Read the `items` attribute to learn the valid values, and the `selecteditem` / `selecteditems`
+attribute to confirm the result after selecting (the cli-reference above shows how to read them).
+
+The rule is general: verified against a control with no native `<select>` (a Lightning picklist
+rendered as a `role="combobox"` button) and applies identically to desktop, Java, and SAP option
+lists — so an option-list control needs **no option-element capture at all**.
 
 ### Buttons disabled during async operations
 

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

@@ -48,7 +48,7 @@ PHASE 2 — build-clean (per-project, once per edit session):
     3. EXIT to Smoke Test
 ```
 
-**Why both phases.** `validate` is static analysis: catches structural XAML, missing references, analyzer rules, schema violations. `build` is the compiler: catches **unknown member names** (e.g. `NGetText.Value` when the property is `Text`), **invalid enum values** (e.g. `Operator="StartsWith"` when the enum has no such member), **member resolution / CacheMetadata failures**, and attribute-form C# expression JIT failures. `validate` returns "no diagnostics found" for these; `build` flags them at compile time. Per-file `validate` plus one end-of-session `build` covers both error classes — trusting only `validate` ships broken workflows.
+**Why both phases.** `validate` is static analysis: catches structural XAML, missing references, analyzer rules, schema violations. `build` is the compiler: catches **unknown member names** (e.g. `NGetText.Value` when the output member is `TextString` (or legacy `Text`)), **invalid enum values** (e.g. `Operator="StartsWith"` when the enum has no such member), **member resolution / CacheMetadata failures**, and attribute-form C# expression JIT failures. `validate` returns "no diagnostics found" for these; `build` flags them at compile time. Per-file `validate` plus one end-of-session `build` covers both error classes — trusting only `validate` ships broken workflows.
 
 **Target the specific file:** `validate --file-path` validates only the file you changed (faster than whole-project). `build` is project-scoped (no `--file-path`); when it errors, the output names the offending file — re-run `validate --file-path` on it as part of Phase 2's fix loop.
 
@@ -78,7 +78,7 @@ uip rpa build "<PROJECT_DIR>" --log-level Warn --output json
 
 | Error class | Example | Why `validate` misses it |
 |-------------|---------|----------------------------|
-| Unknown member name | `<uix:NGetText Value="[x]" />` (correct: `Text`) | `validate` does not resolve property names against activity assemblies |
+| Unknown member name | `<uix:NGetText Value="[x]" />` (correct: `TextString`) | `validate` does not resolve property names against activity assemblies |
 | Invalid enum value | `Operator="StartsWith"` on `VerifyExpressionWithOperator` (enum has no such member) | Enum membership is checked at CacheMetadata / compile time, not static parse |
 | CacheMetadata / member resolution | Required-extension misses, type-mismatch on `InArgument<T>` | Surfaces only when the runtime instantiates the activity |
 | Attribute-form C# expressions | `Value="x + y"` in `expressionLanguage: CSharp` projects | JIT compiler needs the expression in element form — see [xaml/csharp-expression-pitfalls.md](xaml/csharp-expression-pitfalls.md) |

package/skills/uipath-rpa/references/xaml/common-pitfalls.md

@@ -610,6 +610,10 @@ Activity properties typed as enums (e.g. `Operator`, `ClickType`, `KeyModifiers`
 
 **Prevention:** When using `uip rpa activities get-default-xaml`, the output matches the currently installed package version. Never copy XAML snippets from projects using different package versions.
 
+## UIA `N*` Activities Carry a `Version` — Never Strip It
+
+Every UIA `N*` activity carries a `Version` attribute in its `uip rpa activities get-default-xaml` starter (e.g. `NGetText Version="V5"`, `NApplicationCard Version="V2"`). Dropping it survives BOTH `validate` and `build` and fails only at runtime with `System.InvalidOperationException ... ThrowIfNotInTree` on the activity's argument bindings. Carry over **every** attribute the starter emits. See [csharp-expression-pitfalls.md § `ThrowIfNotInTree` at runtime](csharp-expression-pitfalls.md).
+
 ## Expression Language Mismatch
 
 Every XAML file must use the same expression language as the project (`expressionLanguage` in `project.json`).

package/skills/uipath-rpa/references/xaml/csharp-activity-binding-guide.md

@@ -69,7 +69,9 @@ Which properties exist on a given activity, the `<Activity>.md` lookup order, an
 </uix:NGetText>
 ```
 
-**Scoping requirement:** when `NGetText` sits inside `<uix:NApplicationCard.Body><ActivityAction><Sequence>`, the `statusText` variable must be declared on that inner `Sequence.Variables`, not on an outer one crossing the `ActivityAction` boundary — otherwise runtime throws `ThrowIfNotInTree`. See [csharp-expression-pitfalls.md](csharp-expression-pitfalls.md#throwifnotintree--variable-declared-outside-the-activityaction-scope).
+**Author new Get Text activities with `TextString`** (the typed, current-designer property shown above). **When editing an existing workflow,** note that older ones may bind the output to the legacy non-generic `Text` `OutArgument` (`<uix:NGetText.Text>`) instead — both `Text` and `TextString` are real, functional members (the activity writes the scraped text to both at runtime), so a working `Text` binding is valid and should be left as-is, not rewritten to `TextString`. Only `Value` is a genuine unknown member.
+
+**Scoping requirement:** when `NGetText` sits inside `<uix:NApplicationCard.Body><ActivityAction><Sequence>`, the `statusText` variable must be declared on that inner `Sequence.Variables`, not on an outer one crossing the `ActivityAction` boundary — otherwise runtime throws `ThrowIfNotInTree`. See [csharp-expression-pitfalls.md](csharp-expression-pitfalls.md#throwifnotintree-at-runtime--two-causes).
 
 ### Assign with a C# expression
 

package/skills/uipath-rpa/references/xaml/csharp-expression-pitfalls.md

@@ -23,9 +23,9 @@ ExpressionToCompile { Code = "logMessage" ... } should have been compiled by the
 
 `<uix:NGetText TextString="statusText"/>` raises `Failed to create a 'TextString' from the text 'statusText'` — `TextString` is `OutArgument<String>`, not a plain property, so the XAML parser has no converter for it. Always use the `<OutArgument>` + `<CSharpReference>` child form for output bindings.
 
-## `ThrowIfNotInTree` — variable declared outside the `ActivityAction` scope
+## `ThrowIfNotInTree` at runtime — two causes
 
-`OutArgument<T>` + `<CSharpReference>` bound to a variable declared on a `Sequence` **outside** the `ActivityAction` body passes validation but throws at runtime:
+Same runtime stack, two distinct root causes:
 
 ```
 System.InvalidOperationException: The argument of type 'System.String' cannot be used.
@@ -33,6 +33,11 @@ Make sure that it is declared on an activity.
   at System.Activities.Argument.ThrowIfNotInTree()
 ```
 
-**Typical case:** a UI activity inside `<uix:NApplicationCard.Body><ActivityAction><Sequence>` writes an output to a variable declared on the *outer* `Sequence` rather than the inner one.
+**Cause 1 — variable declared outside the `ActivityAction` scope.** `OutArgument<T>` + `<CSharpReference>` bound to a variable declared on a `Sequence` **outside** the `ActivityAction` body passes validation but throws at runtime.
 
-**Fix:** declare the variable on the `Sequence.Variables` immediately inside the `ActivityAction`, not on a parent `Sequence` outside it.
+- **Typical case:** a UI activity inside `<uix:NApplicationCard.Body><ActivityAction><Sequence>` writes an output to a variable declared on the *outer* `Sequence` rather than the inner one.
+- **Fix:** declare the variable on the `Sequence.Variables` immediately inside the `ActivityAction`, not on a parent `Sequence` outside it.
+
+**Cause 2 — UIA activity authored without its `Version` attribute.** A UIA activity missing the `Version` its `activities get-default-xaml` starter emits (e.g. `NGetText` without `Version="V5"`) throws `ThrowIfNotInTree` at runtime on its argument bindings even when variable scoping is correct. This passes BOTH `validate` AND `build` clean — it surfaces only at run.
+
+- **Diagnosis rule:** when scoping is verified correct, diff the authored activity against its `uip rpa activities get-default-xaml` starter and restore any missing attributes — the starter's `Version` in particular. Never strip an attribute the starter emits.

package/skills/uipath-rpa/references/xaml/workflow-guide.md

@@ -47,7 +47,7 @@ Analyze:
 
 ### Step 1.2: Discover Activity Documentation (Primary Source)
 
-**This is the most important discovery step. Read `<Activity>.md` BEFORE `activities get-default-xaml`, every time, even for activities that look simple.** Installed activity packages ship structured markdown at `{projectRoot}/.local/docs/packages/{PackageId}/activities/<Activity>.md`. The doc is the property surface; the CLI starter is not. `activities get-default-xaml` strips every property at its type default — for `NGetText` that means **all** output properties are absent from the starter, and authoring from the starter produces `NGetText.Value="..."` instead of `NGetText.Text="..."`. `validate` does not catch the wrong member name; only `build` does, after a wasted round-trip.
+**This is the most important discovery step. Read `<Activity>.md` BEFORE `activities get-default-xaml`, every time, even for activities that look simple.** Installed activity packages ship structured markdown at `{projectRoot}/.local/docs/packages/{PackageId}/activities/<Activity>.md`. The doc is the property surface; the CLI starter is not. `activities get-default-xaml` strips every property at its type default — for `NGetText` that means **all** output properties are absent from the starter, and authoring from the starter produces `NGetText.Value="..."` instead of the real output member `NGetText.TextString`. `validate` does not catch the wrong member name; only `build` does, after a wasted round-trip.
 
 **Availability:** Docs exist only for **installed packages** and typically only for **newer package versions**. When the package is not installed, install it first. When docs are missing, update to the latest version, or fall back to `skills/uipath-rpa/references/activity-docs/<PackageId>/<closest-version>/`.
 
@@ -203,7 +203,7 @@ Edit: file_path=... old_string=<exact text> new_string=<modified text>
 
 ### Step 3.1: Check for Errors
 
-Run both validators per iteration. `validate` catches structural / reference / analyzer issues; `build` catches member-name and enum-value mistakes that `validate` misses (e.g. `NGetText.Value` when the property is `Text`, `Operator="StartsWith"` when the enum has no such member). See [../validation-guide.md § Validation Iteration Loop](../validation-guide.md#validation-iteration-loop) for the canonical loop.
+Run both validators per iteration. `validate` catches structural / reference / analyzer issues; `build` catches member-name and enum-value mistakes that `validate` misses (e.g. `NGetText.Value` when the property is `TextString`, `Operator="StartsWith"` when the enum has no such member). See [../validation-guide.md § Validation Iteration Loop](../validation-guide.md#validation-iteration-loop) for the canonical loop.
 
 ```bash
 uip rpa validate --file-path "Workflows/MyWorkflow.xaml" --output json

package/skills/uipath-rpa/references/xaml/xaml-basics-and-rules.md

@@ -236,7 +236,7 @@ Never construct activity XAML from memory. Two sources, in this order:
 2. **Fallback:** `skills/uipath-rpa/references/activity-docs/<PackageId>/<closest-version>/<Activity>.md` — bundled reference set covering the major UiPath packages. Use this when `.local/docs` is empty for that package (older versions don't ship per-activity docs) or when no project directory is in scope yet. Pick the version folder closest to the installed version.
 3. **Neither exists:** the package is third-party or unusual. Document this in your output, fall back to `activities find` + `activities get-default-xaml` alone, and warn the user that the property surface may be incomplete.
 
-> **Skip-tax.** `activities get-default-xaml` omits any property whose value equals the type default (`null`, `0`, `false`, unset). For `NTypeInto`: 2 of 20 properties. For `NClick`: ~3 of ~15. For `NGetText`: every output property — the starter is literally `<uix:NGetText HealingAgentBehavior="SameAsCard" />`, with no `Text` property visible. Authoring from this starter alone is how `NGetText.Value="..."` gets written — `Value` does not exist on that activity (the output is `Text`), `validate` accepts it as static-clean, and `build` finally rejects it as an unknown member. The starter looks complete; it isn't. The MD read is the only way you learn which properties actually exist (`Text`, `ClickType`, `KeyModifiers`, `WaitForReady`, `EmptyFieldMode`, etc.).
+> **Skip-tax.** `activities get-default-xaml` omits any property whose value equals the type default (`null`, `0`, `false`, unset). For `NTypeInto`: 2 of 20 properties. For `NClick`: ~3 of ~15. For `NGetText`: every output property — the starter is literally `<uix:NGetText HealingAgentBehavior="SameAsCard" />`, with no output member visible. Authoring from this starter alone is how `NGetText.Value="..."` gets written — `Value` does not exist on that activity, so `validate` accepts it as static-clean and `build` finally rejects it as an unknown member. The starter looks complete; it isn't. The MD read is the only way you learn which properties actually exist (`TextString`, `ClickType`, `KeyModifiers`, `WaitForReady`, `EmptyFieldMode`, etc.). **When authoring a new Get Text, bind the output to `TextString`** (`OutArgument<string>`) — the typed member the current designer surfaces. But `NGetText` declares **two** real output members: `TextString` and a legacy non-generic `Text` `OutArgument` (backwards-compat — the activity writes the scraped text to both at runtime, and the designer hides whichever the installed version does not use). So a `Text="..."` binding in an existing or older workflow is valid and must not be flagged or "corrected" — only `Value` is a genuine unknown member.
 
 **Workflow — each step depends on the previous step's output:**
 

package/skills/uipath-solution/SKILL.md

@@ -53,7 +53,7 @@ All other `solution` subcommands (`pack`, `publish`, `deploy activate/status/uni
 6. **Run `uip solution resources refresh` before `pack` or `upload`.** Bundled artefact files and `userProfile/<userId>/debug_overwrites.json` must reflect current cloud state. Skipping refresh ships stale bindings.
 7. **Coded apps are NOT registered in `.uipx`.** `uip solution project add` does not apply to coded-app directories; they deploy independently via `uip codedapp publish / deploy`. A coded app folder can sit alongside a solution but is not part of its manifest.
 8. **Verify the artifact after every CLI mutation.** Read `project.json`, `.uipx`, or `uip solution deploy status` output — exit codes lie. Verification is additional; it does not replace requested read-only list commands. If the user asks to show or list registered projects, solution resources, packages, deployments, or statuses, run the matching `uip solution ... list/status --output json` command and then inspect files only as a secondary sanity check.
-9. **For multi-environment promotion, the deploy config (`-c <CONFIG_KEY>`) is the environment selector.** Same `.uipx` deploys to dev/staging/prod via different config keys, not different packages.
+9. **For multi-environment promotion, switch tenants with `uip login tenant set <tenant>` and pass a per-environment deploy config via `--config-file <path>`.** The same packed `.uipx` deploys to dev/staging/prod — the environment differs by the target tenant and the config file (generated with `deploy config get`, edited with `config set` / `config link`), not by a different package. There is no `-c <CONFIG_KEY>` flag.
 
 ## Workflow
 
@@ -61,7 +61,7 @@ The typical lifecycle for a UiPath Solution:
 
 ```
 1. init / project add  → Create solution, register projects (.uipx + resources/solution_folder/)
-2. resource refresh    → Sync bundled artefacts and debug overwrites with cloud state
+2. resources refresh   → Sync bundled artefacts and debug overwrites with cloud state
 3. (optional) restore  → Resolve NuGet deps in place (incl. authenticated Orchestrator feeds); login first
 4. pack                → Produce deployable .zip package
 5. login               → uip login (if not already authenticated)
@@ -87,7 +87,7 @@ This skill is the terminal step of an SDD-driven build: after `uipath-planner` p
 | File | Purpose |
 |------|---------|
 | [Solution Overview](references/solution-overview.md) | What a Solution is, `.uipx` manifest, file structure, lifecycle diagram, command tree |
-| [Develop a Solution](references/develop-solution.md) | `uip solution init / project add / import / remove / resource refresh / resource add / resource remove / resource edit`; field-tested gotchas |
+| [Develop a Solution](references/develop-solution.md) | `uip solution init / project add / import / remove / resources refresh / resources add / resources remove / resources edit`; field-tested gotchas |
 | [Pack and Deploy](references/pack-and-deploy.md) | `restore / pack / publish / deploy run`, deploy configs, CI/CD pipeline patterns |
 | [Activate and Manage](references/activate-and-manage.md) | `deploy activate / status / uninstall`, environment management |
 | [Scenarios Index](references/scenarios.md) | Failure modes and edge cases — manual edits, shared resources, virtual resources, name collisions |
@@ -98,6 +98,6 @@ This skill is the terminal step of an SDD-driven build: after `uipath-planner` p
 2. **Editing `resources/solution_folder/` directly.** It is auto-generated and auto-cleaned. Manual edits desync from `.uipx`. Use `uip solution project add/remove` instead.
 3. **Skipping `uip solution resources refresh` before `pack` or `upload`.** Ships stale bindings and debug-overwrite state.
 4. **Adding a coded-app directory via `uip solution project add`.** Coded apps have no `project.uiproj` / `project.json` and are not packed by `uip solution pack`. Deploy them independently via `uip codedapp publish / deploy`.
-5. **Creating a new `.uipx` per environment instead of using deploy configs.** One solution package promotes to dev/staging/prod via different `-c <CONFIG_KEY>` values. Different `.uipx` files per environment defeats version tracking.
+5. **Creating a new `.uipx` per environment instead of using deploy configs.** One packed solution promotes to dev/staging/prod via a per-environment `--config-file` (and `uip login tenant set` to target the tenant). Different `.uipx` files per environment defeats version tracking.
 6. **Using `uip solution upload` (Studio Web) as a deployment path.** Upload is for browser-based debugging only — it does not produce a published package and cannot be promoted via `deploy run`. Use `pack` → `publish` → `deploy run` for real deploys. `upload` also lands the solution in Studio Web's **Cloud workspace** tab — not the Local tab; SW's Local tab is a separate registration not addressable by `uip solution`.
 7. **Trusting exit codes alone after a mutation.** Always read the artefact (`project.json`, `.uipx`, deploy status) — a non-zero exit may indicate partial state and a zero exit can mask warnings.

package/skills/uipath-solution/references/activate-and-manage.md

@@ -90,17 +90,22 @@ uip solution packages list --output json
 
 # Paginate and sort
 uip solution packages list --limit 20 --sort-by "Name" --sort-order "Ascending" --output json
+uip solution packages list --limit 50 --offset 50 --output json   # page 2
 
-# Filter by name (server-side substring match on the package name)
+# Filter by name (server-side substring match on the package name, case-insensitive)
 uip solution packages list --name "Invoice" --output json
 ```
 
 | Option | Description | Default |
 |--------|-------------|---------|
 | `--limit <n>` | Number of results to return | 50 |
+| `--offset <n>` | Number of results to skip (page start) | 0 |
+| `--name <pattern>` | Server-side substring match on the package name | -- |
 | `--sort-by <field>` | Sort field | -- |
 | `--sort-order <dir>` | `Ascending` or `Descending` | -- |
 
+The response's `Pagination` block reports `Total` (all matches on the server) and `HasMore`. If `HasMore` is `true`, re-run with `--offset <previous offset + Returned>` to fetch the next page — a package missing from the first page is not necessarily absent. The list is tenant-scoped: packages published on another tenant of the same organization do not appear; check the active tenant with `uip login status`.
+
 ## Step 5: Download a Package Version
 
 Download a published solution package .zip from the solution feed:

package/skills/uipath-solution/references/develop-solution.md

@@ -243,7 +243,7 @@ uip solution resources add --source remote --kind Queue --name InvoiceQueue \
 | `--source <source>` | `local`, `remote` | **required** |
 | `--kind <kind>` | Any kind RCS indexes (e.g. Queue, Asset, Bucket, Process, Connection, App, Index, Trigger). Case-insensitive lookup; trimmed and lowerFirstChar-applied before persistence | **required** |
 | `--name <name>` | Resource name (max 256 chars; path separators, control chars, and `: * ? " < > |` are rejected). Per-kind Orchestrator limits are stricter — queues cap at 50 | **required** |
-| `--type <type>` | Resource subtype (e.g. `Text`/`Bool`/`Integer` for Asset, connector type for Connection) | None |
+| `--type <type>` | Resource subtype (e.g. `Text`/`Bool`/`Integer` for Asset, connector type for Connection). On `--source remote` it is inferred from the matched resource when omitted; pass it only to override | None |
 | `--folder-path <path>` | Orchestrator folder for remote lookup. **Not valid with `--source local`** — virtual stubs live under the solution folder | None |
 | `--cloud-key <guid>` | Skip RCS search, import this exact resource key. Only valid with `--source remote`; must be a GUID | None |
 | `--solution-folder <path>` | Path to solution root (must directly contain a `.uipx`) | Current working directory |
@@ -272,17 +272,36 @@ uip solution resources add --source remote --kind Queue --name InvoiceQueue \
 
 ### Ambiguous remote match
 
-When `--source remote` is given without `--cloud-key` and the RCS search returns multiple resources with the same `(kind, name)` across different folders, `add` does **not** guess — it emits a structured error with every candidate inline so an agent can re-call without a separate `resource list`:
+When `--source remote` is given without `--cloud-key` and the RCS search returns multiple resources with the same `(kind, name)`, `add` does **not** guess — it emits a structured error listing every candidate (with its folder, subtype, and key) inline so an agent can re-call without a separate `resources list`:
 
 ```json
 {
   "Result": "Failure",
-  "Message": "Ambiguous match: 3 remote resources matching kind=queue name=InvoiceQueue",
-  "Instructions": "Candidates (use one folder via --folder-path, or pass --cloud-key directly):\n  - Folder=Sales/CRM  Key=8f3a1b2c-...\n  - Folder=Operations/Reporting  Key=21a07d4e-...\n  - Folder=Shared  Key=c0e9f7a3-..."
+  "Message": "Ambiguous match: 2 remote resources matching kind=connection name=orders@example.com",
+  "Instructions": "Candidates (disambiguate with --cloud-key <key>; --folder-path only helps when they are in different folders):\n  - Folder=Shared  Type=uipath-google-gmail  Key=8f3a1b2c-...\n  - Folder=Shared  Type=uipath-google-drive  Key=21a07d4e-..."
 }
 ```
 
-Resolve by re-running with `--folder-path <one-of-the-candidates>` or `--cloud-key <one-of-the-keys>`.
+Two cases produce this:
+
+- **Same name across different folders** — resolve with `--folder-path <one-of-the-candidates>` *or* `--cloud-key <one-of-the-keys>`.
+- **Same name *and* folder, different subtype** (e.g. a `uipath-google-gmail` and a `uipath-google-drive` connection both named `orders@example.com` in the same folder). `--folder-path` can't separate these — only `--cloud-key` will. The `Type` column in each candidate tells them apart.
+
+### `--cloud-key` that can't be resolved
+
+`--cloud-key` skips the name search and looks the resource up by key to recover its source folder (the folder context is required — without it the deploy-time FPS export of connection/app resources fails). If the key resolves to nothing — wrong key, a resource not visible to your user, or (when `--folder-path` is also given) a resource that isn't in that folder — `add` fails clearly instead of importing a folderless resource:
+
+```json
+{
+  "Result": "Failure",
+  "Message": "No remote resource found with key 8f3a1b2c-... in folder \"Sales/CRM\"",
+  "Instructions": "Verify the key via 'uip solution resources list --source remote' (and that --folder-path, if given, matches the resource's folder)."
+}
+```
+
+Distinguish this from a **transient lookup failure**: if the Orchestrator search itself errors (RCS/API outage), `add` reports a separate `"Failed to look up the resource in Orchestrator by key"` instead of the not-found message above. Treat that one as retry-able; treat `"No remote resource found with key …"` as a key/folder to fix.
+
+An *already-imported* key is not an error — the idempotency check runs first, so re-adding it returns `Status: "Unchanged"`. On a successful by-key import the resource's subtype is taken from the match automatically (same as the name-search path), so `--type` is only needed to override it.
 
 ### How it relates to `refresh`
 

package/skills/uipath-solution/references/pack-and-deploy.md

@@ -91,7 +91,7 @@ uip solution upload ./MySolution --output json
 
 This uploads to Studio Web for collaborative editing. It does **not** place the package on the solution feed and cannot be used with `deploy run`. If the `SolutionId` in `.uipx` already exists in Studio Web, `upload` refuses unless `--force` is passed (forcing replaces the cloud project in place and wipes its Studio Web version history).
 
-`upload` always lands the solution in Studio Web's **Cloud workspace** tab, not the Local tab. SW's Local tab is a separate registration for solutions whose source of truth is a tracked local folder — populated by SW-initiated flows (creating a solution from the SW UI, or downloading a cloud solution to local) or by Studio Desktop signing into the same tenant. `uip solution upload` does not address the Local tab. Authoring with `uip solution new` then `upload` produces a Cloud-tab solution; the local folder on disk has no live link to either tab afterward — edits in one place do not propagate to the other without a re-upload (Cloud) or a download (Local).
+`upload` always lands the solution in Studio Web's **Cloud workspace** tab, not the Local tab. SW's Local tab is a separate registration for solutions whose source of truth is a tracked local folder — populated by SW-initiated flows (creating a solution from the SW UI, or downloading a cloud solution to local) or by Studio Desktop signing into the same tenant. `uip solution upload` does not address the Local tab. Authoring with `uip solution init` then `upload` produces a Cloud-tab solution; the local folder on disk has no live link to either tab afterward — edits in one place do not propagate to the other without a re-upload (Cloud) or a download (Local).
 
 ## Step 4: Deploy to Orchestrator
 
@@ -143,9 +143,12 @@ The CLI also falls back to the persistent `searchSearchDeployments22` record if
 ```bash
 uip solution deploy list --output json
 uip solution deploy list --folder-path "Shared" --limit 20 --sort-by "Name" --sort-order "Ascending" --output json
+uip solution deploy list --limit 50 --offset 50 --output json   # page 2
 ```
 
-Options: `--folder-path`, `--limit` (default 50), `--sort-by`, `--sort-order` (`Ascending`/`Descending`).
+Options: `--folder-path`, `--limit` (default 50), `--offset` (default 0), `--sort-by`, `--sort-order` (`Ascending`/`Descending`).
+
+The response's `Pagination` block reports `Total` and `HasMore`; when `HasMore` is `true`, fetch the next page with `--offset`. Note that `--folder-path` filters client-side after the fetch, so with that flag `Returned` counts the filtered rows while `Offset`/`Total` stay server-side — page with `--offset` first, then filter.
 
 ---
 

package/skills/uipath-solution/references/solution-overview.md

@@ -51,7 +51,7 @@ MySolution/
 ```mermaid
 graph LR
     A[init] --> B[project add]
-    B --> C[resource refresh]
+    B --> C[resources refresh]
     C --> D[pack]
     D --> E[publish]
     E --> F["deploy run<br/>(auto-activate by default)"]
@@ -63,7 +63,7 @@ Two distinct distribution paths from the same solution source:
 - **`pack` → `publish` → `deploy run`** — promotes a versioned package to Orchestrator.
 - **`upload`** — pushes the solution to Studio Web for browser-based debugging only. Does not produce a published package and cannot be deployed via `deploy run`.
 
-Always run `resource refresh` before either path so the bundled artefact files and `userProfile/<userId>/debug_overwrites.json` reflect the current cloud state.
+Always run `resources refresh` before either path so the bundled artefact files and `userProfile/<userId>/debug_overwrites.json` reflect the current cloud state.
 
 ---
 

package/version-manifest.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": 1,
-  "skillsVersion": "1.197.1",
-  "targetCli": "^1.197.0"
+  "schemaVersion": 2,
+  "skillsVersion": "1.198.0-preview.21",
+  "targetCli": "^1.198.0"
 }