@uipath/skills 1.197.2 → 1.198.0-preview.21

package/skills/uipath-rpa/references/coded/coding-guidelines.md

@@ -235,6 +235,6 @@ C) <user-driven approach>
 | **Service property not available** | Missing package dependency | Install the required package via `uip rpa packages install --project-dir "<PROJECT_DIR>" --packages id=<PACKAGE_ID> --output json` (no `add-dependency` command exists; do not hand-edit `project.json`) |
 | **Timeout** | Studio took too long to start. First headless call on a cold NuGet cache can take 30–90 s. | Increase timeout: `--timeout 600` |
 | **"Target name 'X' is not part of the current screen"** | Element descriptor used on wrong screen handle | Use the `UiTargetApp` handle from `Open`/`Attach` for the screen that owns the element |
-| **"Cannot select item. It was not found among existing items"** | `SelectItem` fails on web dropdowns | Use `TypeInto` instead of `SelectItem` for web `<select>` elements |
+| **"Cannot select item. It was not found among existing items"** | The `Item` value doesn't match any option (wrong text/casing) — not a control-type limitation | Read the control's `items` attribute (via the interact CLI, see the UIA cli-reference) and pass one of those values verbatim. `SelectItem` drives any control whose `items` lists options (any UI stack); use `TypeInto` only for type-ahead combos or controls with no `items`. |
 | **`packages inspect` cannot find UILibrary package** | Package is on a private/local NuGet feed | Use `--nupkg-path` to inspect the local `.nupkg` directly, or read `.metadata` files manually from `~/.nuget/packages/<name>/<version>/contentFiles/any/any/.objects/` |
 | **Studio rejects manually created project** | Missing metadata dirs, wrong schema/version | Always use `uip rpa init` instead of writing `project.json` manually |

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).
 
 ---
 
@@ -507,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/uia-prerequisites.md

@@ -1,10 +1,10 @@
 # UiAutomation Prerequisites
 
 **Required package:** `UiPath.UIAutomation.Activities`
-**Minimum version (`<MIN_VERSION>`):** `26.10.0`
-**Source feed:** the official UiPath NuGet feed — the same feed Studio resolves by default.
+**Minimum version (`<MIN_VERSION>`):** `26.4.1-preview`
+**Source feed:** the official UiPath NuGet feed — the same feed Studio resolves by default. Prerelease / preview builds of `UiPath.UIAutomation.Activities` are published there alongside stable releases. Installing them is a normal supported path, not a third-party workaround.
 
-> **Stable release.** `<MIN_VERSION>` is a stable GA build — it ships the `uia-configure-target` skill content and resolves from the official feed without any prerelease flag. Querying with `--include-prerelease` is still fine (it surfaces newer preview builds), but it is not needed to reach `<MIN_VERSION>`.
+> **Prerelease required.** `<MIN_VERSION>` is a preview — stable releases of `UiPath.UIAutomation.Activities` do NOT yet ship the `uia-configure-target` skill content. Install the prerelease build explicitly. `uip rpa packages versions` MUST be invoked with `--include-prerelease` (the flag defaults to `false`), otherwise the required preview is filtered out of the listing and the agent will report "no upgrade available" against a feed that actually has it.
 
 The `uip rpa uia` CLI used by `uia-configure-target` requires `UiPath.UIAutomation.Activities` at `<MIN_VERSION>` or newer. Before configuring any target, check the installed version in `project.json` under `dependencies`.
 
@@ -17,10 +17,10 @@ Never upgrade UIA silently. Every upgrade requires explicit user consent before
 
 | Scenario | Behavior |
 |---|---|
-| No UIA installed, request needs UIA | Ask before installing `<MIN_VERSION>` from the official UiPath feed. |
+| No UIA installed, request needs UIA | Ask before installing `<MIN_VERSION>`. Disclose that it is a prerelease build from the official UiPath feed. |
 | Major-version upgrade (e.g. `25.x` → `26.x`) | Ask. Note that breaking changes are possible across major versions. |
-| Minor-version upgrade (e.g. `26.4.x` → `26.10.x`) | Ask before installing the newer build. |
-| Patch / build upgrade within the `26.10.x` band | Ask before installing the newer build. |
+| Minor-version upgrade (e.g. `26.3.x` → `26.4.x`) | Ask. Note that the minimum required for `uia-configure-target` is a preview. |
+| Patch / build upgrade within the preview band | Ask before installing the newer preview build. |
 | Already at or above `<MIN_VERSION>` | Proceed without prompting. |
 
 If the user declines, do NOT install. Warn that `uip rpa uia` commands will fail without UIA at `<MIN_VERSION>` and fall back to indication authoring — [uia-configure-target-workflows.md](uia-configure-target-workflows.md) MUST be read IN FULL first (see § Indication Fallback). Record `UI capture: indication-only` in the plan header so downstream tasks do not route to `uia-configure-target`.
@@ -39,4 +39,4 @@ Install / upgrade (mutating — only after consent per the table above; substitu
 uip rpa packages install --packages 'id=UiPath.UIAutomation.Activities,version=<MIN_VERSION>' --project-dir "$PROJECT_DIR" --output json
 ```
 
-`packages install` resolves `<MIN_VERSION>` directly via the `version` field — no prerelease flag is needed, since it is a stable release. Omit `,version=<MIN_VERSION>` to resolve the latest compatible build (which will be at or above `<MIN_VERSION>`).
+`packages install` accepts the beta version directly via the `version` field — no separate prerelease flag is needed once the version string is specified explicitly.

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/scenarios/manual-edits.md

@@ -64,7 +64,7 @@ Open the file. The shape is roughly:
 | `resource.runtimeDependencies` | Recomputed at every pack — manual edits lost on next pack |
 | `resource.files`, `resource.locks` | Managed; never appear in user-edit scenarios |
 | `resource.folders` | Moves the resource. For a *cloud-imported* resource the folder is `solution_folder` (placeholder) — editing it doesn't change cloud location, only confuses sync. For a *virtual* resource that you authored at a non-`solution_folder` folder, edit at the binding (`bindings_v2.json`) and let refresh re-create — don't edit the resource file directly |
-| `resource.spec.<reference-fields>` | E.g. `storageBucketReference`, `retentionBucketRef`. The SDK rewrites these when the target's link state changes; hand-edits get clobbered. (Known bug: the rewrite isn't always applied automatically - that's not a license to hand-edit dependents arbitrarily) |
+| `resource.spec.<reference-fields>` | E.g. `storageBucketReference`, `retentionBucketRef`. The SDK rewrites these when the target's link state changes; hand-edits get clobbered. (Also see [SOL-7051](https://uipath.atlassian.net/browse/SOL-7051) — the rewrite isn't always applied automatically; that's a known bug, not a license to hand-edit dependents arbitrarily) |
 
 ### Examples — safe edits
 
@@ -123,7 +123,7 @@ Same principle, looser rules. The deploy config is **per-deployment**, not per-s
 
 **Manual editing of the deploy config is not ideal** — there's no schema validation in the CLI, and a bad edit fails server-side at `deploy run` (often with a generic `ValidationFailed`). But it's the pragmatic escape hatch when:
 
-- You need to set a nested property `config set` doesn't expose (e.g. `configuration.storageBucketReference.key` to work around the reference-field rewrite bug noted above).
+- You need to set a nested property `config set` doesn't expose (e.g. `configuration.storageBucketReference.key` to work around [SOL-7051](https://uipath.atlassian.net/browse/SOL-7051)).
 - You're scripting a config transform (CI step injecting per-environment secrets, etc.) and want a single JSON-patch step instead of N CLI calls.
 - The CLI surface is missing a flag for the field you need.
 

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/skills/uipath-troubleshoot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: uipath-troubleshoot
-description: "UiPath causal investigation across every product, runtime, and activity package. Use when the primary outcome is an explanation, diagnosis, or root cause for undesirable existing behavior: faults, hangs, regressions, slowdowns, access loss, unexpected state changes, wrong or empty results, silent no-ops, or raw errors. Diagnostic intent outranks surface ownership; invoke even when the prompt names only a job, folder, queue item, connector, connection, activity, trace, flow, agent, or other resource and another UiPath skill supplies inspection commands. Correlates runtime, configuration, history, and source evidence to find the originating fault and fix. For operating resources without causal investigation→uipath-platform; for applying a known source fix→the artifact owner."
-when_to_use: "Trigger when the requested outcome is to explain or investigate undesirable existing UiPath behavior. Infer this from the goal; no exact phrase, product name, exception, or identifier is required. A pasted raw error message, exception stack, or error code with no other request implies this outcome. Do not trigger for pure CRUD/list/start/stop/status, aggregate monitoring, or a direct edit to a known local artifact when no causal investigation is requested."
+description: "UiPath troubleshooting, diagnostics, and root-cause investigations across any UiPath product, feature, runtime, or artifact. Investigates errors, failures, faults, exceptions, regressions, performance problems, unexpected behavior, and silent malfunctions — answers why something failed, broke, stopped, hung, slowed down, returned wrong results, lost access, or stopped working after a change. Also diagnoses failures and faults in Integration Service connectors/connections, Office 365 / Outlook, Google Workspace (GSuite), Excel / Word / PDF activities, Computer Vision, databases / SQL, and HTTP / web activities — route here (not uipath-platform) when the intent is why it failed rather than operating the surface. Walks the available evidence (logs, traces, incidents, status fields, configuration, history) to identify the originating fault and explain what changed. For operating or CRUD on these surfaces→uipath-platform."
+when_to_use: "User asks why something failed, broke, stopped, hung, was stuck, returns wrong results, or behaves unexpectedly in any UiPath system. Triggers: 'why did X fail', 'find the cause', 'find why', 'what changed', 'investigate', 'diagnose', 'debug this', 'triage', 'help me figure out', 'what's wrong', 'root cause', 'fix this error', 'inspect this trace / incident / log / job / instance', 'X worked yesterday but now …'. Also fires on raw error messages, exception stacks, error codes, job / queue IDs, or 'stuck / orphan / zombie' state descriptions."
 ---
 
 # UiPath Troubleshooting Agent
@@ -21,7 +21,7 @@ ALL phases. Never override.
 7. **Live ≠ historical.** Current snapshots (machine status, licenses, connections) cannot prove what happened during incidents older than 24h — context only.
 8. **Symptom ≠ cause.** A matching error string confirms the playbook *match*, not the *cause*. The §6 checklist gates every conclusion.
 9. **No inference from undocumented fields.** Behavior not in a playbook or docsai result → flag as unverified, don't guess.
-10. **Approval gate.** Diagnosis is autonomous; applying a fix is not. **Modifying user source files, or executing a remediation command that changes tenant/platform state (a `## Resolution` step that creates, deletes, or reconfigures a resource), requires explicit approval via `AskUserQuestion`.** Diagnostic commands stay autonomous: reads, and playbook-prescribed idempotent re-validations whose purpose is evidence (e.g. a same-values `update` re-probe). A request for steps or a script is a deliverable, not execution approval — author it, do not run it. On decline or non-answer: do not edit or execute. If AskUserQuestion is unavailable, present the proposed fix as text and stop.
+10. **Approval gate.** Diagnosis is autonomous; **modifying user source files requires explicit approval via `AskUserQuestion`**. On decline or non-answer: do not edit. If AskUserQuestion is unavailable, present the proposed edit as text and stop.
 11. **No ad-hoc code execution.** Playbook-provided diagnostic snippets are recommendations for the user unless the playbook says to run them. Shell for file I/O and uip is fine.
 
 **Tools:** uip CLI (json by default in non-interactive mode). Documentation search: `uip docsai ask "<question>" --source docs` (product docs) or `--source technical_solution_articles` (support KB — known bugs, workarounds).

package/skills/uipath-troubleshoot/references/products/agents/playbooks/context-grounding-index-not-found.md

@@ -67,8 +67,6 @@ What to look for:
   uip context-grounding ingest --index-name "<index-name>" --folder-path "<folder-path>" --output json
   ```
 
-  Ingestion is async: after `ingest`, poll `uip context-grounding retrieve --index-name "<index-name>" --folder-path "<folder-path>" --output json` until `last_ingestion_status` is `Successful` before searching — the index is not queryable earlier.
-
   No agent republish needed — the runtime resolves by name.
 
 **If the index exists but is in a different folder — re-link the agent:**

package/skills/uipath-troubleshoot/references/products/maestro/playbooks/personal-automation-quota.md

@@ -32,7 +32,7 @@ What to look for:
 
 ## Resolution
 
-- **If Personal Automation quota exhausted:** request a license upgrade via the organization admin or UiPath account manager, or wait for the monthly quota reset
+- **If Personal Automation quota exhausted:** request a license upgrade via [self-service license increase](https://uipath.atlassian.net/wiki/spaces/LIC/pages/2834596253), or wait for the monthly quota reset
 - **If Agentic Units expired:** allocate AU from **Admin > Organization > Subscriptions** or contact the UiPath account manager
 - **If recurring:** redesign the workflow to use a tenant-level Unattended robot instead of Personal Automation so quotas come from the shared pool
 

package/version-manifest.json

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