@uipath/skills 1.201.0-preview.621 → 1.202.0-preview.635

package/skills/uipath-rpa/references/uia-starter-guide.md

@@ -1,11 +1,43 @@
 # UIA Starter Guide
 
-Read this file IN FULL before any UI-automation work (Rule 7). Then:
+Read this file from the top THROUGH § Runtime Selector Failure Recovery before any UI-automation work (Rule 7), then STOP — the § Conditional Policies marker below it gates two sections read only when their condition applies. Then:
 
-1. **Verify prerequisites** — minimum package version and upgrade-consent rules: SKILL.md § UIA Prerequisites. If the package cannot be installed, use the [Placeholder-Selector Stub Pattern](#placeholder-selector-stub-pattern) below.
-2. **Read the UIA package's authoring guide IN FULL** — `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md`, including the mode-specific section (For Coded Workflows or For XAML Workflows). It owns authoring — window baseline, target capture, common pitfalls, control-specific interaction, Application Card patterns — and routes to the package's task guides and references. It ships with the package: if the package is installed but the file is absent, the installed version predates it — treat as below the minimum version (SKILL.md § UIA Prerequisites).
+1. **Verify prerequisites** — minimum package version and upgrade-consent rules: [§ UIA Prerequisites](#uia-prerequisites) below. If the package cannot be installed, use the [Placeholder-Selector Stub Pattern](#placeholder-selector-stub-pattern) below.
+2. **Read the UIA package's core guide IN FULL** — `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md`. It owns the shared UIA law — window baseline, the mandatory target-generation gate, terminology, common pitfalls, control-specific interaction, reading values — and its § Documentation routes to everything else, including the per-mode authoring guides. **Before authoring UIA activities, additionally read your mode's authoring guide IN FULL** (XAML or coded, routed from § Documentation) — during capture-only phases neither mode guide is needed yet. The core guide ships with the package: if the package is installed but the file is absent, the installed version predates it — treat as below the minimum version (§ UIA Prerequisites).
 
-The sections below are the UIA policies this skill owns: running/debugging UIA workflows, the deliverable shape when live capture is unavailable, and publishing Object Repository descriptors as a shared UI Library.
+The sections below are the UIA policies this skill owns: prerequisites and upgrade consent, running/debugging UIA workflows, the deliverable shape when live capture is unavailable, and publishing Object Repository descriptors as a shared UI Library.
+
+---
+
+## UIA Prerequisites
+
+**Required package:** `UiPath.UIAutomation.Activities` — minimum version (`<MIN_VERSION>`): **`26.10.2`**, from the official UiPath NuGet feed (no prerelease flag needed). The `uip rpa uia` CLI, the package docs, and the UIA skills require `<MIN_VERSION>` or newer — before any UIA work, check the installed version in `project.json` under `dependencies`. Do not hardcode the version from memory; this section is the only source of truth.
+
+**Upgrades require explicit user consent.** Never install or upgrade UIA silently. Consent comes from one of:
+
+- **Plan-mode:** approval of a plan whose Task 0 names the upgrade explicitly — both package ID and version. Plan approval IS the consent — do NOT re-ask at execution time.
+- **Interactive mode (no plan):** a direct prompt before `packages install` runs.
+
+| Scenario | Behavior |
+|---|---|
+| No UIA installed, request needs UIA | Ask before installing `<MIN_VERSION>` from the official UiPath feed. |
+| Major-version upgrade (e.g. `25.x` → `26.x`) | Ask. Breaking changes are possible across major versions. |
+| Minor / patch / build upgrade | Ask before installing the newer build. |
+| Already at or above `<MIN_VERSION>` | Proceed without prompting. |
+
+Discovery (non-mutating, no consent required):
+
+```bash
+uip rpa packages versions --package-id UiPath.UIAutomation.Activities --include-prerelease --project-dir "$PROJECT_DIR" --output json
+```
+
+Install / upgrade (mutating — only after consent per the table above):
+
+```bash
+uip rpa packages install --packages 'id=UiPath.UIAutomation.Activities,version=<MIN_VERSION>' --project-dir "$PROJECT_DIR" --output json
+```
+
+Omit `,version=<MIN_VERSION>` to resolve the latest compatible build (at or above `<MIN_VERSION>`).
 
 ---
 
@@ -16,11 +48,11 @@ The sections below are the UIA policies this skill owns: running/debugging UIA w
 **Every debug run** must follow this procedure to prevent stale windows from accumulating or being reused in a dirty state:
 
 1. **Record the window baseline** — list top-level windows via the UIA snapshot CLI and note which w-refs and titles are already present. Procedure: the package guide's § Window Baseline (`{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md`).
-2. **Run the workflow:**
+2. **Run the workflow** — always with `--output-filter`, so one call returns the verdict and the workflow's own log instead of hundreds of trace lines (filter expression and the `| tail` trap: [cli-reference.md § Capturing the verdict](cli-reference.md#capturing-the-verdict)):
    ```bash
-   uip rpa debug start --file-path "<FILE>" --project-dir "<PROJECT_DIR>" --output json
+   uip rpa debug start --file-path "<FILE>" --project-dir "<PROJECT_DIR>" --output json --output-filter "<verdict filter>"
    ```
-   If the run fails, [Runtime Selector Failure Recovery](#runtime-selector-failure-recovery) spawns the `uia-improve-selector` subagent — this is the **only** correct recovery path. Do not hand-edit selectors in the XAML file.
+   If the run fails, follow [Runtime Selector Failure Recovery](#runtime-selector-failure-recovery) — this is the **only** correct recovery path. Do not hand-edit selectors in the XAML file.
 3. **When done** (success or failure) — **cancel the debug session:**
    ```bash
    uip rpa execution cancel --project-dir "<PROJECT_DIR>" --output json
@@ -49,13 +81,19 @@ When a workflow fails at runtime with a selector error:
 1. **The app is already in the right state.** The debug session paused at the failing activity, so the app's current DOM reflects the state that activity needs to target.
 2. **Identify the failing element** -- read the error to find which descriptor/element failed.
 3. **Read the window selector** -- from the Object Repository files, find the screen's selector that scopes the failing element.
-4. **Run the `uia-improve-selector` skill in recover mode.** Read the package's improve-selector guide (routed from the package guide § Documentation), pick the appropriate invocation form for this context, run the staging CLI command from that form, spawn a subagent with the Agent tool to run the skill in recover mode against the staged folder, then run the write-back CLI command from the same form to persist the recovered selector.
+4. **Follow the package's recover selector guide** - check ui-automation-guide.md for information on how to perform the recovery. If nothing relevant is found there, check uia-improve-selector-guide.md.
 5. **Clean up and re-run** -- follow the procedure above (stop, diff, close leaked windows, re-run).
 
 Repeat until the workflow completes successfully. Each failure advances the app to the next problematic state, making recovery self-correcting.
 
+**Recovery circuit breaker — two attempts per element.** When the SAME element fails at runtime after two recovery cycles, do not run a third: elements that keep failing recovery typically remount (dialogs, popups, re-rendered panes), and selector hardening cannot converge on them. Re-route that one element instead: re-run the capture flow for it with the CV/semantic fallback enabled (the capture flow's fallback chain owns the mechanics), re-link, and continue the run loop. Count attempts per element, not per run — three failures of one element across runs is the same signal.
+
 ---
 
+## Conditional Policies — read when the condition applies
+
+**Do NOT read past this marker in the initial read.** Read [§ Placeholder-Selector Stub Pattern](#placeholder-selector-stub-pattern) IN FULL the moment a workflow must ship WITHOUT live app access (app not installed, no GUI, capture deferred, or the UIA package cannot be installed — Rule 7a fallback). Read [§ Object Repository as a Published UI Library](#object-repository-as-a-published-ui-library) IN FULL when the task involves publishing or consuming shared Object Repository descriptors.
+
 ## Placeholder-Selector Stub Pattern
 
 Sometimes you must generate a UI automation workflow without live app access — the app is not installed on the build machine, the agent has no GUI, the user has explicitly deferred target capture to a developer who will run Indicate later, or the UIA package cannot be installed (Rule 7a). In that case, the workflow ships with placeholder selectors. The pattern below is the **only** acceptable shape. It requires no UIA package or CLI — that is the point.

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

@@ -566,12 +566,11 @@ Activity-level mechanics below. For the expression/code layer (LINQ filter/sort/
 - **Assert activities** require `BookmarkResumptionHelper` extension (added via `metadata.RequireExtension<BookmarkResumptionHelper>()` in CacheMetadata)
 - **TakeScreenshotInCaseOfSucceedingAssertion** and **TakeScreenshotInCaseOfFailingAssertion** are `[RequiredArgument]` on assert activities even though they default to `false`
 
-## Enum-Valued Properties Are a `validate` Blind Spot
+## Enum-Valued Properties Fail the Whole File, Not Just the Activity
 
-Activity properties typed as enums (e.g. `Operator`, `ClickType`, `KeyModifiers`, `EmptyFieldMode`, comparison/filter strategies) are checked at compile time against the activity's enum, **not** during `validate` static analysis. An invalid identifier on an enum-typed attribute returns "no diagnostics found" from `validate` and surfaces only at `build` / `CacheMetadata` time. Two consequences:
+Activity properties typed as enums (e.g. `Operator`, `ClickType`, `KeyModifiers`, `EmptyFieldMode`, comparison/filter strategies) accept only the exact members declared for the installed package version. An invalid identifier is a **deserialization** failure, not a localized property error: `validate` reports `Could not load <file>: 'Failed to create a '<Prop>' from the text '<value>''` and the entire activity tree fails to load, so a single bad enum value blocks the file — and blocks Object Repository linking against it, which needs the file to deserialize.
 
-1. Always read `{projectRoot}/.local/docs/packages/<PackageId>/activities/<Activity>.md` for the exact, package-version-specific enum members before authoring an enum-valued attribute. Do not infer values from naming intuition or from prose in this skill.
-2. Always run `uip rpa build` after `validate` clears — it is the only validator that catches invalid enum identifiers (see [../cli-reference.md § Validation Iteration Loop](../cli-reference.md#validation-iteration-loop)).
+Always read `{projectRoot}/.local/docs/packages/<PackageId>/activities/<Activity>.md` for the exact, package-version-specific enum members before authoring an enum-valued attribute. Do not infer values from naming intuition or from prose in this skill.
 
 ## Package Version Changes Break XAML
 

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

@@ -10,7 +10,7 @@ For any activity property typed `InArgument<T>` or `OutArgument<T>`:
 - **Literal value with a direct type converter** (string literal on `<String>`, enum, number, boolean, `TimeSpan`, `{x:Null}`) → attribute form is safe.
 - **Anything non-literal** (variable reference, concatenation, method call, property access) → use the child-element form with `<CSharpValue>` (read) or `<CSharpReference>` (write).
 
-The XAML attribute parser defaults to VB for expression-bearing attribute values, **regardless of the project's expression language**. At runtime, the VB JIT is disabled on non-Legacy projects — so attribute-form expressions fail with `JIT compilation is disabled for non-Legacy projects`. Full failure modes: [§ C# Expression Pitfalls](#c-expression-pitfalls) below.
+The XAML attribute parser does not treat an attribute value as a C# expression, **regardless of the project's expression language**. On a property whose type accepts a string (`InArgument<Object>` above all) the text is kept as a literal, so the workflow validates, builds, and runs while using the expression's source text as its value. Full failure modes: [§ C# Expression Pitfalls](#c-expression-pitfalls) below.
 
 ## Property-surface sourcing
 
@@ -123,16 +123,15 @@ Which properties exist on a given activity, the `<Activity>.md` lookup order, an
 
 ## C# Expression Pitfalls
 
-Failure modes in scope: all pass static `validate` validation — they only surface at `CacheMetadata` time under `uip rpa build` or `uip rpa run`.
+Failure modes in scope: none of these are reported by `validate` or `build`. The worst of them produces no error at all.
 
-## Attribute-form expressions fail at runtime
+## Attribute-form input expressions silently become literals
 
-Any non-literal attribute value on an `InArgument<T>` / `OutArgument<T>` property (e.g. `Message="logMessage"`, `TextString="statusText"`) is deserialized as `VisualBasicValue<T>` by the XAML attribute parser — regardless of the project's `expressionLanguage`. On non-Legacy projects the VB JIT is disabled, so these fail at runtime:
+A non-literal attribute value on an `InArgument<T>` property whose `T` accepts a string — `Object` above all — is **not** parsed as an expression. `<ui:LogMessage Message="calcResult" />` deserializes the text `calcResult` as a literal value, so `validate` reports no diagnostics, `build` succeeds, the run succeeds, and the activity emits the string `calcResult` instead of the variable's contents.
 
-```
-System.InvalidOperationException: JIT compilation is disabled for non-Legacy projects.
-ExpressionToCompile { Code = "logMessage" ... } should have been compiled by the Studio Compiler.
-```
+There is no exception and no warning anywhere in the gate. The only symptom is wrong output, which is why a smoke test must have its **output inspected** rather than merely exiting clean.
+
+Where `T` has no string conversion, the same mistake surfaces loudly instead — as a deserialization failure naming the property (see `OutArgument<T>` below). Do not rely on that: the `Object` case is the common one, and it is silent.
 
 **Fix:** use `<CSharpValue>` (read) or `<CSharpReference>` (write) child-element form for anything non-literal.
 

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

@@ -2,6 +2,89 @@
 
 Core concepts for UiPath workflow XAML files, the authoring workflow (Discovery → Generate/Edit → Validate & Fix → Response), and rules for generating and/or editing XAML content.
 
+**Read contract (Rule 22) — mechanical:** Grep `^## Catalogs` on this file for its line number, then Read this file with `limit` set to that line — everything ABOVE the marker is the mandatory full read. The two catalog sections below the marker (§ Common Editing Operations, § XAML Reference Examples) load per-entry only: Grep `^###`, Read the entries matching the operation or activity at hand; unsure → read it. A full-file Read that includes the catalogs means this contract was skipped.
+
+## Critical Rules — XAML (Rules 16–21a, 24)
+
+Mandatory for all XAML authoring and editing. Cited as "Rule N" across this skill. Rule 22 (the read-in-full mandate that brings you to this file) and Rule 23 (`expressionLanguage`/`targetFramework` immutability) live in SKILL.md § XAML-Specific Rules; Common Rules 1–12 are also in SKILL.md.
+
+16. **[XAML] Activity docs are the source of truth** — check `{projectRoot}/.local/docs/packages/{PackageId}/` first. Always.
+17. **[XAML] MUST understand project structure** — read `project.json`, check expression language, scan existing patterns. NEVER generate XAML blind.
+18. **[XAML] Batch-author, single gate** — author the complete workflow in one pass, sourcing each activity card → memory → Rule 21 triple (precedence in [execution-maps-guide.md](../execution-maps-guide.md)). Then per-file `validate` to clean, then one project `build` (Common Rule 3 cadence, 5-attempt caps unchanged); for observable-output workflows the gate ends with one `run` + output check ([execution-maps-guide.md § Gate ≠ runtime proof](../execution-maps-guide.md#gate--runtime-proof)). On failure: fix by error category (Rule 19); card-covered activities stay card-sourced — a gate failure does NOT reopen `activities find`/`get-default-xaml`; >2 errors with ambiguous origin → bisect (stub out half the new activities, re-validate).
+19. **[XAML] Fix errors by category** — Package → Structure → Type → Activity Properties → Logic.
+20. **[XAML] Flowchart node structure + ViewState both decide whether a Flowchart renders.** **Structure first:** every `FlowStep`/`FlowDecision`/`FlowSwitch` MUST be a direct child of `<Flowchart>` (only direct children are added to the `Flowchart.Nodes` collection), wired through `Flowchart.StartNode`/`FlowStep.Next`/branches with `<x:Reference>`+`x:Name`. NEVER build the flow as a nested chain — one `FlowStep` physically nested inside the previous one's `<FlowStep.Next>` — because nested-only steps are absent from `Flowchart.Nodes` and the designer renders almost nothing, regardless of ViewState. **Then ViewState:** when generating new Flowchart/StateMachine/ProcessDiagram workflows, per-node ViewState is MANDATORY — `ShapeLocation`+`ShapeSize` on every node (`ConnectorLocation` optional, Studio auto-routes). Without it Studio stacks every node at (0,0) so they overlap into what looks like a single node, and Studio does NOT auto-arrange on open (see [canvas-layout-guide.md](canvas-layout-guide.md)). When editing existing files, do NOT modify ViewState on nodes you are not changing. For Sequences, ViewState is optional.
+21. **[XAML] Reading `<Activity>.md` from `{PROJECT_DIR}/.local/docs/packages/...` is a precondition for `activities get-default-xaml` — for every activity not on the common-activity card.**
+    - **Card-listed activities and patterns:** consult [common-activity-card.md](../common-activity-card.md) and [common-pattern-card.md](../common-pattern-card.md) first — as a lookup, not a full read: Grep `^### ` on the card to list its entries with line numbers, then Read only the entries matching activities/patterns in the plan (an entry ends at the next `###`). Read a card end-to-end only when the plan needs more than 5 of its entries. On a card hit, author from the card entry alone — skip `activities find`, skip `activities get-default-xaml`, skip the per-activity MD read. Precedence: card → agent memory ([execution-maps-guide.md § Cross-session memory](../execution-maps-guide.md#cross-session-memory)) → full triple. A memory hit substitutes for the triple only; `validate`/`build` still gate.
+    - **All other activities:** (1) `activities find` → class name, (2) **read `<Activity>.md` first** and extract a property checklist (required + use-case-relevant), (3) `activities get-default-xaml` → starter element, (4) **diff your checklist against the starter and add what's missing** — an empty checklist means you skipped step 2, go back.
+    - **Doc lookup order:** primary `{PROJECT_DIR}/.local/docs/packages/<PackageId>/activities/<Activity>.md`; fallback `../activity-docs/<PackageId>/<closest-version>/<Activity>.md` for older package versions where `.local/docs` is empty. **Exception — `UiPath.UIAutomation.Activities` has no bundled fallback:** `.local/docs` (present only after the package is installed) is its sole activity-doc source. If it is absent, do not hunt for a bundled copy — follow Rule 7a (install with consent per [uia-starter-guide.md § UIA Prerequisites](../uia-starter-guide.md), or use the Placeholder-Selector Stub Pattern — [uia-starter-guide.md](../uia-starter-guide.md)).
+    - **Trigger activities are special — read BOTH docs.** When the class name ends in `Trigger`, the namespace contains `.Triggers`, or the description mentions "starts a job" / "Monitor Events" / "Trigger Scope", also read the bundled `../activity-docs/<PackageId>/<closest-version>/activities/<Activity>.md` **and** the package's bundled `overview.md`. The auto-generated `.local/docs` version is sparse for triggers; the bundled hand-written docs carry placement guidance (entry-point vs. `ui:TriggerScope`), deployment context, and cross-cutting namespace/assembly gotchas that the extractor does not capture. See Common Rule 12 (SKILL.md) and [trigger-pattern-guide.md](../trigger-pattern-guide.md).
+    - **Skip-tax — concrete:** `activities get-default-xaml` omits any property whose value equals the type default. For `NGetText` the starter is literally `<uix:NGetText HealingAgentBehavior="SameAsCard" />` with **zero** output properties — authoring from this alone produces `NGetText.Value="..."`, which does not exist; the output member is `TextString`. The whole file then fails to deserialize (`Cannot set unknown member`), which also blocks Object Repository linking against it. For `NTypeInto` that's 2 of 20 properties hidden.
+    - **Self-extending the card — "this activity feels simple, I'll add it to the card mentally" — is the failure mode.** The card is the only allowlist; for non-card activities the MD read is the only check.
+    - Full procedure: § Activity Property Surface in this file.
+21a. **[XAML] Built-in workflow activities: use the card only for this allowlist.** Fast-path card activities are: `Sequence`, `If`, `Switch<T>`, `TryCatch`, `While`, `DoWhile`, `ForEach<T>`, `Assign`, `LogMessage`, `WriteLine`, `Delay`, `Throw`, `Rethrow`. If the activity is on this list, Grep [common-activity-card.md](../common-activity-card.md) for its `^### ` heading, Read that entry, and author from it (Rule 21 lookup procedure). If it is not on this list, check [common-pattern-card.md](../common-pattern-card.md) next (same lookup: Grep `^### `, Read the matching entry) — its patterns cover e.g. text-file read/append/write, file copy, CSV, DataTable→CSV, queue publish, retry wrap, `InvokeWorkflowFile`, InvokeCode rows, HTTP→JSON — and follow full Rule 21 only when BOTH cards miss. `Pick`, `Parallel`, and `ParallelForEach<T>` are intentionally on neither card; use full Rule 21. Studio's "While" / "Do While" / "For Each" toolbox items emit UiPath wraps (`UiPath.Core.Activities.InterruptibleWhile` / `InterruptibleDoWhile` / `UiPath.Core.Activities.ForEach<T>`), not the framework `System.Activities.Statements.While`/`DoWhile`/`ForEach<T>`.
+24. **[XAML] Wrap every container-activity body/branch in `<Sequence>` — even single-activity bodies.** Studio's designer expects the wrap as a drop zone; Studio's emitter produces it. `validate` and `build` accept the bare form, so neither catches missing wrappers. Applies to creation and editing alike. Slots include `If.Then`/`If.Else`, `While`/`DoWhile` body, `ForEach.Body`, `TryCatch.Try`/`Catch`/`Finally`, `Switch.Default` + each case, `PickBranch.Trigger`/`Action`, `NApplicationCard.Body`. Full table with examples: § Container Activity Bodies — Wrap in Sequence in this file.
+
+## XAML Task Navigation & Quick Reference
+
+### Task Navigation — XAML
+
+| I need to... | Read |
+|-------------|------|
+| **Create XAML test case (Given-When-Then)** | [testing-guide.md § XAML Test Case Structure](../testing-guide.md) — remember: register in `fileInfoCollection` (Common Rule 10) |
+| **Use mock testing** | [testing-guide.md § Mock Testing (WIP)](../testing-guide.md) — requires CLI command not yet available |
+| **Use XAML test activities** | [testing-guide.md § XAML Test Activities](../testing-guide.md) |
+| **Use execution templates** | [testing-guide.md § Execution Templates](../testing-guide.md) |
+| **Use a common activity** (`Sequence` / `If` / `Switch<T>` / `TryCatch` / `While` / `DoWhile` / `ForEach<T>` / `Assign` / `LogMessage` / `WriteLine` / `Delay` / `Throw` / `Rethrow`) | [common-activity-card.md](../common-activity-card.md) — Rule 21a lookup |
+| **Author a common multi-activity pattern** (text file read/append/write · file copy · CSV · DataTable→CSV · queue publish · retry wrap · invoke workflow · InvokeCode rows · HTTP→JSON) | [common-pattern-card.md](../common-pattern-card.md) — Rule 21a lookup, alongside the activity card, not instead of it |
+| **Create/edit Flowchart** | [canvas-layout-guide.md](canvas-layout-guide.md) — § Flowchart Structure & Wiring, then § Flowchart Layout |
+| **Create StateMachine** | § State Machine in this file → [canvas-layout-guide.md § State Machine Layout](canvas-layout-guide.md#4-state-machine-layout) |
+| **Create/edit Long Running Workflow (ProcessDiagram)** | [long-running-workflow-guide.md](long-running-workflow-guide.md) → [canvas-layout-guide.md](canvas-layout-guide.md) |
+| **Build multi-screen UIA XAML workflow** | The package's XAML authoring guide § Multi-Screen Authoring (routed from the core guide's § Documentation; Rule 7); default to author-once-after-capture with a single `validate`+`build` gate (Rule 18); per-screen authoring interleave only on long captures (5+ screens). Turn structure: [execution-maps-guide.md § Journey: UIA capture + build](../execution-maps-guide.md#journey-uia-capture--build-xaml) |
+| **Use Data Fabric entities** | [activity-docs overview](../activity-docs/UiPath.DataService.Activities/overview.md) |
+| **Query Data Fabric with filters** | [data-service-filter-builder-guide.md](../activity-docs/UiPath.DataService.Activities/guides/data-service-filter-builder-guide.md) → [QueryEntityRecords](../activity-docs/UiPath.DataService.Activities/activities/QueryEntityRecords.md) |
+| **Call an IS connector (XAML)** | [is-connector-xaml-guide.md](../is-connector-xaml-guide.md) — includes connector discovery + connection lifecycle |
+| **Build an event-triggered workflow** (O365 / Gmail / Salesforce / Jira / Slack / ServiceNow / time / queue / file watcher / UI click) | [trigger-pattern-guide.md](../trigger-pattern-guide.md) → `activity-docs/{PackageId}/{closest}/activities/<TriggerActivity>.md` |
+| **Read or edit an existing `ui:TriggerScope` workflow** | [trigger-pattern-guide.md § Reading and Editing Existing TriggerScope XAML](../trigger-pattern-guide.md) |
+| **Troubleshoot XAML errors** | [common-pitfalls.md](common-pitfalls.md) (Rule 22 lookup procedure) → [cli-reference.md § Validation Iteration Loop](../cli-reference.md#validation-iteration-loop) |
+
+### Expression Language
+
+Check `expressionLanguage` in `project.json`. VB.NET uses `[brackets]` for expressions; C# uses `CSharpValue<T>` / `CSharpReference<T>` — canonical C# binding forms per property: [csharp-activity-binding-guide.md](csharp-activity-binding-guide.md). Default for new XAML projects is VB.NET.
+
+### Key CLI Commands
+
+| Command | Purpose |
+|---------|---------|
+| `activities find --query "<keyword>"` | Discover activities by keyword |
+| `activities get-default-xaml --activity-class-name "<class>"` | Get starter XAML for an activity |
+| `analyzer-rules list --project-dir "<dir>"` | List enabled Workflow Analyzer rules — on demand only (user asks about project rules, or repeated violations of one rule family); `validate`/`build` enforce the rules without it |
+| `validate --file-path "<file>"` | Per-file deep validation (structure, references, analyzer rules, unknown members, invalid enums, expression compilation) |
+| `build "<PROJECT_DIR>"` | Whole-project compile + packaging gate — every workflow, including files `validate` was never pointed at ([cli-reference.md § What each phase covers](../cli-reference.md#what-each-phase-covers)) — run after `validate` is clean |
+
+### Common Activities
+
+| Activity | Package | Purpose |
+|----------|---------|---------|
+| **UI automation** (Use Application/Browser, Click, Type Into, Get Text, Select Item, …) | `UiPath.UIAutomation.Activities` | **Never author from memory or from this row.** Selectors and targets are captured, not hand-written — read the UIA package guide (`{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md`) in full first (Rule 7). |
+| If | built-in | Conditional branching |
+| Assign | built-in | Set variable/argument values |
+| For Each | built-in | Iterate over a collection |
+| Invoke Workflow File | built-in | Call another workflow file |
+| Create Entity Record | `UiPath.DataService.Activities` | Create a Data Fabric entity record |
+| Query Entity Records | `UiPath.DataService.Activities` | Query Data Fabric records with filters — see [filter builder guide](../activity-docs/UiPath.DataService.Activities/guides/data-service-filter-builder-guide.md) |
+
+### Related XAML References
+
+- [common-pitfalls.md](common-pitfalls.md) — Activity gotchas, scope requirements, property conflicts (Rule 22 lookup procedure)
+- [csharp-activity-binding-guide.md](csharp-activity-binding-guide.md) — Canonical C# binding forms per common activity property + § C# Expression Pitfalls
+- [canvas-layout-guide.md](canvas-layout-guide.md) — Flowchart node vocabulary, structure & wiring, forbidden nested-chain pattern + Flowchart/State Machine/LRW canvas layout with ViewState
+- [long-running-workflow-guide.md](long-running-workflow-guide.md) — LRW package dependency, node vocabulary, gateway patterns, suspend/resume persistence
+- [jit-custom-types-schema.md](jit-custom-types-schema.md) — JIT custom type discovery
+- [../reframework-guide.md](../reframework-guide.md) — REFramework execution modes, SetTransactionStatus queue-guard fix, Config.xlsx leftover trap
+- [../data-manipulation-guide.md](../data-manipulation-guide.md) — DataTable LINQ, strings, RegEx, DateTime, type conversion, collections, JSON; VB + C# forms
+- [../error-handling-guide.md](../error-handling-guide.md) — exception taxonomy, Try/Catch discipline, Retry Scope, Global Exception Handler, transaction boundaries, retry ownership
+- [../library-authoring-guide.md](../library-authoring-guide.md) — Reusable libraries: public-workflow contract, layout sidecar, error contract, SemVer, pack & publish
+
 ## Authoring Workflow
 
 Discovery-first approach with iterative error-driven refinement. Always understand before acting, start simple, validate continuously.
@@ -58,7 +141,7 @@ Every `activities/{ActivityName}.md` follows: Header → Metadata → Properties
 |-----------|--------|
 | **Know package + activity name** | `Read` `{projectRoot}/.local/docs/packages/{PackageId}/activities/{ActivityName}.md` |
 | **Know package, not activity** | `Read` the `overview.md`, then read the identified activity doc |
-| **Don't know package** | `Glob` with `**/*.md` in `{projectRoot}/.local/docs/packages/`. `.local/` is gitignored — use `Glob` + `Read`, not `Grep` |
+| **Don't know package** | `ls {projectRoot}/.local/docs/packages/` via Bash to list installed package doc folders, then `ls` the candidate's `activities/` and `Read` the file by path. NOT `Glob`/`Grep` — both skip gitignored `.local/`; a miss from either proves nothing |
 | **Docs exist but activity undocumented** | Use other docs as structural reference, fall back to `activities get-default-xaml` |
 | **No docs for package** | Update the package first — this often adds docs. **Caution:** major version jumps (e.g., 23.x → 26.x) may deprecate activities — prefer minor/patch updates. If still no docs, fall back to Steps 1.4-1.7 |
 | **Package not installed** | Install it first — both docs and `activities get-default-xaml` require it |
@@ -146,7 +229,7 @@ For end-to-end authoring of `ConnectorActivity` XAML (connection + type ID + Con
 
 ### Phase 3: Validate & Fix Loop
 
-**MUST** repeat until 0-error state from **both** `validate` and `build`, or max 5 fix attempts per loop. After 5 attempts, stop and present remaining errors to the user. The canonical two-phase loop (per-file `validate` → project-level `build`), the errors `build` catches that `validate` misses, and the smoke-test procedure: [../cli-reference.md § Validation Iteration Loop](../cli-reference.md#validation-iteration-loop) — read it before your first fix iteration.
+**MUST** repeat until 0-error state from **both** `validate` and `build`, or max 5 fix attempts per loop. After 5 attempts, stop and present remaining errors to the user. The canonical two-phase loop (per-file `validate` → project-level `build`), what each phase covers, and the smoke-test procedure: [../cli-reference.md § Validation Iteration Loop](../cli-reference.md#validation-iteration-loop) — read it before your first fix iteration.
 
 ```bash
 uip rpa validate --file-path "Workflows/MyWorkflow.xaml" --output json
@@ -357,9 +440,9 @@ Never construct activity XAML from memory. Two sources, in this order:
 1. **`<Activity>.md`** — authoritative property surface: which properties exist, types, defaults, descriptions, required-scope rules.
 2. **`uip rpa activities get-default-xaml --activity-class-name "<FullClassName>"`** — starter element with correct namespaces, assembly references, and any properties whose values differ from the type default.
 
-**Where `<Activity>.md` lives:** primary `{PROJECT_DIR}/.local/docs/packages/<PackageId>/activities/<Activity>.md` (auto-generated on install; `Glob` + `Read`, not `Grep` — `.local/` is gitignored); fallback `skills/uipath-rpa/references/activity-docs/<PackageId>/<closest-version>/<Activity>.md` (pick the version folder closest to installed) — routing table: [§ Step 1.2](#step-12-discover-activity-documentation-primary-source). **Neither exists:** the package is third-party or unusual — document that, fall back to `activities find` + `activities get-default-xaml` alone, and warn the user the property surface may be incomplete.
+**Where `<Activity>.md` lives:** primary `{PROJECT_DIR}/.local/docs/packages/<PackageId>/activities/<Activity>.md` (auto-generated on install; Read the exact path directly — a failed Read IS the existence check; `Glob` and `Grep` both skip gitignored `.local/`, so a miss from either proves nothing); fallback `../activity-docs/<PackageId>/<closest-version>/<Activity>.md` (pick the version folder closest to installed) — routing table: [§ Step 1.2](#step-12-discover-activity-documentation-primary-source). **Neither exists:** the package is third-party or unusual — document that, fall back to `activities find` + `activities get-default-xaml` alone, and warn the user 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 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.
+> **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 the file fails to deserialize with `Cannot set unknown member 'UiPath.UIAutomationNext.Activities.NGetText.Value'`, taking the whole activity tree and any Object Repository linking with it. 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:**
 
@@ -411,6 +494,50 @@ When editing XAML:
 ### Validate After Every Change
 Run `uip rpa validate` after every XAML modification. Do not batch multiple edits without validation — catching errors early is much easier than debugging compound issues.
 
+## Property Binding: Attributes vs Child Elements
+
+XAML properties can be set in two ways: as XML attributes or as child elements. Both are valid XAML, but some properties only work reliably in one form.
+
+### Attribute Syntax (Inline)
+```xml
+<ui:LogMessage Message="[myVar]" Level="Info" />
+```
+
+### Child Element Syntax (Property Element)
+```xml
+<ui:SomeActivity>
+  <ui:SomeActivity.Result>
+    <OutArgument x:TypeArguments="x:String">[outputVar]</OutArgument>
+  </ui:SomeActivity.Result>
+</ui:SomeActivity>
+```
+
+### When to Use Which
+
+**Simple values** (strings, enums, booleans, VB expressions in brackets) almost always work as attributes:
+```xml
+DisplayName="My Activity" Message="[variable]" Level="Info"
+```
+
+**Output properties** (`OutArgument`, `Result`) may require child element syntax. Some activities accept `Result="[var]"` as an attribute; others only work with the expanded child element form. If an attribute-form output binding causes a validation error, try the child element form.
+
+**Complex objects** (BackupSlot, MailboxArgument, ActivityAction, dictionaries) always require child element syntax — they cannot be expressed as a single attribute value.
+
+**Strings containing literal `[` or `]`** (e.g., UIA special-key tokens like `[k(enter)]`, `[d(ctrl)]`, `[u(ctrl)]`) require child element syntax. The attribute form `Foo="[&quot;…[k(enter)]&quot;]"` runs correctly because the runtime VB compiler reads quoted string literals correctly, but the literal brackets inside the string collide with the outer `[ … ]` VB expression markers and the value will not render in Studio. See [common-pitfalls.md § NTypeInto `Text` with literal `[k(...)]` special-key tokens](common-pitfalls.md#ntypeinto-text-with-literal-k-special-key-tokens).
+
+### Version-Sensitive Properties
+
+Properties may exist in one package version but not another. If `validate` reports "Could not find member 'PropertyName'":
+1. The property may not exist in the installed package version — remove it
+2. The property may have been renamed between versions — check examples from the same package version
+3. Use `uip rpa activities get-default-xaml` output as the authoritative set of properties for the installed version
+
+---
+
+## Catalogs — Grep-gated (Rule 22 read contract)
+
+**Do NOT read past this marker in the initial full read.** The two sections below are per-operation / per-activity catalogs. Lookup procedure: Grep `^###` on this file to list their entries with line numbers, then Read ONLY the entries matching the operation or activity at hand. Unsure whether an entry applies → read it.
+
 ## Common Editing Operations
 
 Common operations for editing and managing workflow XAML files.
@@ -535,7 +662,7 @@ Expressions use explicit `<CSharpValue>` (for read/evaluate) or `<CSharpReferenc
 
 **Expression-tree limits**: each C# expression compiles as a lambda expression tree — no statements, no `out var` (`TryParse`), no optional-argument overloads (`CS0854`), and no calls into the project's coded source file types ([common-pitfalls.md § C# XAML Expressions Compile as Expression Trees](common-pitfalls.md)). When a transform outgrows single expressions, escalate per [data-manipulation-guide.md § Exception](../data-manipulation-guide.md) — Invoke Code, or a coded workflow via Invoke Workflow File.
 
-**Stronger rule for attribute-form bindings on `InArgument<T>` / `OutArgument<T>`:** in XAML projects with `expressionLanguage: CSharp`, any **non-literal** attribute value (`Message="variableName"`, `Text="&quot;Hello &quot; + name"`) is also deserialized as a `VisualBasicValue<T>` and fails at runtime with `JIT compilation is disabled for non-Legacy projects`. The attribute parser defaults to VB regardless of the project's expression language. Use `<CSharpValue>` / `<CSharpReference>` child elements for anything that isn't a plain literal. See [csharp-activity-binding-guide.md](csharp-activity-binding-guide.md) (includes § C# Expression Pitfalls).
+**Stronger rule for attribute-form bindings on `InArgument<T>` / `OutArgument<T>`:** in XAML projects with `expressionLanguage: CSharp`, any **non-literal** attribute value (`Message="variableName"`, `Text="&quot;Hello &quot; + name"`) is not evaluated as an expression. Where the property type accepts a string the text survives as a literal and the workflow validates, builds, and runs with the wrong value and no error; where it does not, the file fails to deserialize. Use `<CSharpValue>` / `<CSharpReference>` child elements for anything that isn't a plain literal. See [csharp-activity-binding-guide.md](csharp-activity-binding-guide.md) (includes § C# Expression Pitfalls).
 
 **Safe attribute-form values** (no expression evaluator involved, type converter handles them directly):
 - Literal strings on `InArgument<String>`: `Text="Book trip"`, `DisplayName="Open file"`
@@ -742,40 +869,3 @@ Shows a package-based activity with `ConnectionId` for Integration Service.
 
 The generic IS `ConnectorActivity` pattern — activity shape, worked example, editing rules, JIT-generated assemblies: [../is-connector-xaml-guide.md](../is-connector-xaml-guide.md).
 
-## Property Binding: Attributes vs Child Elements
-
-XAML properties can be set in two ways: as XML attributes or as child elements. Both are valid XAML, but some properties only work reliably in one form.
-
-### Attribute Syntax (Inline)
-```xml
-<ui:LogMessage Message="[myVar]" Level="Info" />
-```
-
-### Child Element Syntax (Property Element)
-```xml
-<ui:SomeActivity>
-  <ui:SomeActivity.Result>
-    <OutArgument x:TypeArguments="x:String">[outputVar]</OutArgument>
-  </ui:SomeActivity.Result>
-</ui:SomeActivity>
-```
-
-### When to Use Which
-
-**Simple values** (strings, enums, booleans, VB expressions in brackets) almost always work as attributes:
-```xml
-DisplayName="My Activity" Message="[variable]" Level="Info"
-```
-
-**Output properties** (`OutArgument`, `Result`) may require child element syntax. Some activities accept `Result="[var]"` as an attribute; others only work with the expanded child element form. If an attribute-form output binding causes a validation error, try the child element form.
-
-**Complex objects** (BackupSlot, MailboxArgument, ActivityAction, dictionaries) always require child element syntax — they cannot be expressed as a single attribute value.
-
-**Strings containing literal `[` or `]`** (e.g., UIA special-key tokens like `[k(enter)]`, `[d(ctrl)]`, `[u(ctrl)]`) require child element syntax. The attribute form `Foo="[&quot;…[k(enter)]&quot;]"` runs correctly because the runtime VB compiler reads quoted string literals correctly, but the literal brackets inside the string collide with the outer `[ … ]` VB expression markers and the value will not render in Studio. See [common-pitfalls.md § NTypeInto `Text` with literal `[k(...)]` special-key tokens](common-pitfalls.md#ntypeinto-text-with-literal-k-special-key-tokens).
-
-### Version-Sensitive Properties
-
-Properties may exist in one package version but not another. If `validate` reports "Could not find member 'PropertyName'":
-1. The property may not exist in the installed package version — remove it
-2. The property may have been renamed between versions — check examples from the same package version
-3. Use `uip rpa activities get-default-xaml` output as the authoritative set of properties for the installed version

package/skills/uipath-solution/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: uipath-solution
-description: "Always invoke for `.uipx` files. UiPath Solution lifecycle via the `uip solution` CLI: init/restore/pack/publish/deploy/activate/upload, projects add|import|remove, resources refresh|add|remove|edit. Also DIAGNOSE solution-lifecycle failures: pack/publish/deploy/activate errors, stale or missing bindings, unimported/unset/unresolved resources, deploy error codes (e.g. `[1009] Invalid argument 'Value'`), publish name+version/processKey collisions, and `uip solution` 'unknown command' after the new→init rename. Bundles multiple automation projects (RPA/Flow/Case/Agents/API Workflows/AppV2 Coded and Coded Action apps) into one deployable `.uipx`. For PDD→SDD design (sdd.md/pdd.md) & multi-skill task derivation→uipath-planner. For non-solution Orchestrator/IS/resources/auth/traces→uipath-platform. For .xaml/.cs→uipath-rpa. For .flow→uipath-maestro-flow. For .bpmn→uipath-maestro-bpmn. For agent.json and .py agents→uipath-agents. For standalone coded-app deploy (no parent .uipx)→uipath-coded-apps."
-when_to_use: "User mentions .uipx / 'uip solution' / 'pack the solution' / 'publish the solution' / 'deploy the solution' / 'activate' / multi-project / Solution scope / Solution Folder. Fires for 'create a new solution', 'add project/resource to solution', 'add a queue/asset/bucket/connection to the solution', 'import a cloud queue/asset', 'edit/remove a resource', 'change a queue/asset field', 'set an asset value in the solution'. Also fires to DIAGNOSE solution problems: 'why did my solution pack/publish/deploy fail', 'pack ships stale/old bindings', 'my resource edit didn't take effect', 'refresh imported 0 bindings', deploy fails '[1009] Invalid argument Value', publish 'name+version / processKey collision', 'uip solution new: unknown command', 'coded app missing from the .uipx / not packed'. (Solution build-time/CLI faults belong here; faulted Orchestrator JOBS at runtime → uipath-troubleshoot.) Load BEFORE editing .uipx or running uip solution commands. For PDD→SDD design→uipath-planner; for an 'architect then deploy' two-phase request, run uipath-planner first, then return here to pack/deploy."
+description: "Always invoke for `.uipx` files. UiPath Solution lifecycle via the `uip solution` CLI: init/restore/pack/publish/deploy/activate/upgrade/upload, projects add|import|remove, resources refresh|add|remove|edit, feeds list plus `--feed` / `--personal-workspace` targeting. Also DIAGNOSE solution-lifecycle failures: pack/publish/deploy/activate errors, stale or missing bindings, unimported/unset/unresolved resources, deploy error codes (e.g. `[1009] Invalid argument 'Value'`), publish name+version/processKey collisions, a redeploy blocked because the deployment already exists (use `deploy upgrade`), a feed rejected as 'not an available publish location', a feed-published package missing from `packages list`, and `uip solution` 'unknown command' after the new→init rename. Bundles multiple automation projects (RPA/Flow/Case/Agents/API Workflows/AppV2 Coded and Coded Action apps) into one deployable `.uipx`. For PDD→SDD design (sdd.md/pdd.md) & multi-skill task derivation→uipath-planner. For non-solution Orchestrator/IS/resources/auth/traces→uipath-platform. For .xaml/.cs→uipath-rpa. For .flow→uipath-maestro-flow. For .bpmn→uipath-maestro-bpmn. For agent.json and .py agents→uipath-agents. For standalone coded-app deploy (no parent .uipx)→uipath-coded-apps."
+when_to_use: "User mentions .uipx / 'uip solution' / 'pack the solution' / 'publish the solution' / 'deploy the solution' / 'activate' / multi-project / Solution scope / Solution Folder. Fires for 'create a new solution', 'add project/resource to solution', 'add a queue/asset/bucket/connection to the solution', 'import a cloud queue/asset', 'edit/remove a resource', 'change a queue/asset field', 'set an asset value in the solution', 'upgrade a deployment to a newer version', 'change the deployed version without losing my configuration', 'publish/deploy to a folder feed or Personal Workspace', 'which feeds can I publish to'. Also fires to DIAGNOSE solution problems: 'why did my solution pack/publish/deploy fail', 'pack ships stale/old bindings', 'my resource edit didn't take effect', 'refresh imported 0 bindings', deploy fails '[1009] Invalid argument Value', publish 'name+version / processKey collision', 'uip solution new: unknown command', 'coded app missing from the .uipx / not packed'. (Solution build-time/CLI faults belong here; faulted Orchestrator JOBS at runtime → uipath-troubleshoot.) Load BEFORE editing .uipx or running uip solution commands. For PDD→SDD design→uipath-planner; for an 'architect then deploy' two-phase request, run uipath-planner first, then return here to pack/deploy."
 ---
 
 # UiPath Solution — `uip solution` lifecycle
@@ -42,15 +42,18 @@ uip solution init --help --output json
 | `uip solution init <NAME>` | `uip solution new <NAME>` |
 | `uip solution deploy run --parent-folder-path <PATH>` | `uip solution deploy run --folder-path <PATH>` |
 | `uip solution deploy run --parent-folder-key <KEY>` | `uip solution deploy run --folder-key <KEY>` |
+| `uip solution projects <VERB>` | `uip solution project <VERB>` (singular still works post-rename, but is hidden and deprecated) |
+| `uip solution resources <VERB>` | `uip solution resource <VERB>` |
+| `uip solution projects import <PATH>` | `uip solution project import --source <PATH>` |
 
-All other `solution` subcommands (`pack`, `publish`, `deploy activate/status/uninstall`, `upload`, `resource …`, `project add/import`) are unchanged on both surfaces.
+All other `solution` subcommands (`pack`, `publish`, `deploy activate/status/uninstall`, `upload`, `resources …`, `projects add/remove/list`) are unchanged on both surfaces.
 
 ## Critical Rules
 
 1. **Probe the CLI surface before the first `uip solution` command in a session.** Run `uip solution init --help --output json`. `Success` = post-rename CLI (default); `unknown command` = pre-rename CLI — translate via the fallback table above. Re-probe on any later `unknown command` error.
 2. **Always use `--output json`** for `uip solution` commands whose output you parse. JSON is compact and stable; the default for non-interactive runs.
 3. **Use the CLI, never roll your own REST for solution operations.** Hand-rolled HTTP calls miss the `X-UIPATH-OrganizationUnitId` header, OData filter shape, pagination envelope, and `pipelinesInstall` deploy semantics. Only fall through to REST after confirming no `uip solution` command covers the task.
-4. **Never hand-edit `resources/solution_folder/`.** It's auto-generated by `uip solution projects add` / `import` and auto-cleaned by `project remove`. Manual edits desync from `.uipx` and produce silent failure modes. See [scenarios/manual-edits.md](references/scenarios/manual-edits.md).
+4. **Never hand-edit `resources/solution_folder/`.** It's auto-generated by `uip solution projects add` / `import` and auto-cleaned by `projects remove`. Manual edits desync from `.uipx` and produce silent failure modes. See [scenarios/manual-edits.md](references/scenarios/manual-edits.md).
 5. **`.uipx` and `resources/solution_folder/` must always agree on the project set.** Diffing them is the fastest way to detect corrupted state. If they disagree, fix via `uip solution projects add/remove` — never by editing either side directly.
 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. **AppV2 coded apps register in `.uipx` when authored inside a solution.** `uip codedapp init` is the solution-side scaffolding entry point — run it from **inside a `.uipx` solution**. It writes `project.uiproj` (`ProjectType: "AppV2"`) + `webAppManifest.json`, nests source under `source/dist/`, and auto-registers as `Type: "AppV2"` — emitting `resources/solution_folder/app/{Coded,CodedAction}/`. `uip solution projects add` / `uip solution projects import` cover existing AppV2 folders too — both read `webAppManifest.config.isActionApp` to pick `Coded` / `CodedAction` subType (defaults `Coded` for legacy folders with no manifest). `uip solution pack` bundles them; `uip solution deploy run` provisions them. Standalone coded apps are a **different** lifecycle — scaffold them with `npx create-vite@latest` (not `uip codedapp init`), keep a flat `dist/` at the project root, and deploy via `uip codedapp pack` → `uip codedapp publish` → `uip codedapp deploy`. See [/uipath:uipath-coded-apps](/uipath:uipath-coded-apps).
@@ -90,8 +93,8 @@ This skill is the terminal step of an SDD-driven build: after `uipath-planner` p
 |------|---------|
 | [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 / 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 |
+| [Pack and Deploy](references/pack-and-deploy.md) | `restore / pack / publish / deploy run / feeds list`, targeting a non-tenant feed (`--feed` / `--personal-workspace`), deploy configs, CI/CD pipeline patterns |
+| [Activate and Manage](references/activate-and-manage.md) | `deploy activate / status / upgrade / uninstall`, in-place version upgrades, environment management |
 | [Scenarios Index](references/scenarios.md) | Failure modes and edge cases — manual edits, shared resources, virtual resources, name collisions |
 
 ## Anti-patterns

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

@@ -65,24 +65,29 @@ uip solution deploy list --output json
 
 ## Upgrade a Deployment In Place
 
-> **Preview command.** Available only on prerelease (preview/alpha) CLI builds.
-
 `deploy run` fails with HTTP 400 when a deployment for the solution **already exists** — you can't redeploy over it, you have to upgrade it in place (the same as the Orchestrator UI's "Upgrade" button). `deploy upgrade` does that from the CLI, so you don't have to open the UI:
 
 ```bash
-# Upgrade to the newest published version (default)
+# Upgrade to the newest published version (default), waiting for it to finish
 uip solution deploy upgrade <deployment-key> --output json
 
 # A deployment in your Personal Workspace feed
 uip solution deploy upgrade <deployment-key> --personal-workspace --output json
+
+# Start it and return immediately
+uip solution deploy upgrade <deployment-key> --no-wait --output json
 ```
 
-Find `<deployment-key>` with `uip solution deploy list`. On success the output is `Code: SolutionDeployUpgrade`, `Data: { Status: "UpgradeInitiated", DeploymentName, FromVersion, ToVersion }`.
+Find `<deployment-key>` with `uip solution deploy list`. On success the output is `Code: SolutionDeployUpgrade`, `Data: { Status, DeploymentName, FromVersion, ToVersion, VersionChangeKey }`. `Status` is the deployment operation status — `Successful` once the upgrade landed, or `Draft` with `--no-wait`.
 
 **Behavior and limits:**
-- It **initiates** the upgrade — the deployment's version moves to the target, but the operation lands in a `Draft`/in-progress state. Track completion with `uip solution deploy list` (the deployment shows the new version and its operation state).
+- The deployment's **existing configuration is preserved** — values already set on the deployment carry over instead of being reset to the package defaults, so an upgrade does not regenerate a credential asset's secret. Resources the new version adds are created. This is the reason to use `deploy upgrade` rather than uninstall-and-redeploy.
+- **The upgrade takes two server steps, and the command does both.** The upgrade call only *queues* the move: it creates a second deployment record (operation `VersionChange`, status `Draft`) and leaves the live version alone. Nothing advances that draft on its own — it sits in `Draft` indefinitely — so the command then installs it. `VersionChangeKey` in the output is that new record's key; it is **not** the key you passed in.
+- By default the command **waits** for the install to reach a terminal state (`--timeout <seconds>`, default 300; `--poll-interval <ms>`, default 5000). Pass `--no-wait` to return as soon as the install is accepted.
+- A failed install reports the server's reason (for example `Solution folder not found` when the deployment's solution folder was deleted), not a bare `Failed`.
+- After a successful upgrade the deployment can land in `ReadyToActivate` rather than `Active`. Check with `uip solution deploy list` and run `uip solution deploy activate <deployment-name>` if activation is pending.
 - Only the **latest** published version is a valid target today. Omit `--version` to take the newest; passing an older `--version` is rejected.
-- The deployment must be a healthy, successfully-installed one. A deployment that never installed cleanly is rejected by the server.
+- The deployment must be a healthy, successfully-installed one. A deployment that never installed cleanly is rejected by the server. Re-running an upgrade that is already queued fails with `Another upgrade has already started for this deployment`.
 
 ## Step 3: Uninstall a Deployment