@uipath/skills 1.196.0 → 1.197.0

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

@@ -6,6 +6,7 @@ Reference for XAML test automation features in UiPath RPA projects — XAML test
 
 ## Table of Contents
 
+- [Test Manager Setup (CLI)](#test-manager-setup-cli)
 - [XAML Test Case Structure (Given-When-Then)](#xaml-test-case-structure-given-when-then)
 - [Data-Driven Testing](#data-driven-testing)
 - [XAML Test Activities](#xaml-test-activities)
@@ -14,6 +15,24 @@ Reference for XAML test automation features in UiPath RPA projects — XAML test
 
 ---
 
+## Test Manager Setup (CLI)
+
+Linking a project to Test Manager (server connection + default project) can be done headlessly with `uip rpa tm`, without opening Studio — useful before authoring test cases that reference Test Manager test cases. Full verb/flag reference: [cli-reference.md § Test Manager](cli-reference.md). The essentials:
+
+```
+uip rpa tm connect --url "https://<host>/<org>/<tenant>/testmanager_" --project-dir "<PROJECT_DIR>" --output json
+uip rpa tm set-default-project --id <project-guid> --name "<name>" --key "<KEY>" --project-dir "<PROJECT_DIR>" --output json
+uip rpa tm status --project-dir "<PROJECT_DIR>" --output json
+```
+
+Behavior to know when authoring:
+- **`set-default-project` requires a connected server** — run `connect` first, or it is rejected (nothing is written).
+- **Switching to a different server** (`connect` to a different host/org/tenant) **clears the default project** — it belonged to the old server. Re-link one with `set-default-project` afterwards.
+- **`reloadHint` in the output**: if the project is open in a **Studio older than 26.0.197**, the change isn't picked up until the project is reloaded. When you see `reloadHint`, tell the user to **close and reopen the project in Studio**. Studio 26.0.197+ applies the change live (no `reloadHint`).
+- The CLI does **not** validate the project id against the server; obtain a real id from Test Manager (the runtime `uip tm project list` tool can list them).
+
+---
+
 ## XAML Test Case Structure (Given-When-Then)
 
 XAML test cases use a **Given-When-Then** structure — three nested `<Sequence>` elements inside a parent Sequence. The agent generates these directly as XAML.

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

@@ -29,13 +29,13 @@ Do not re-inspect or keep polling after the initial check — subsequent capture
 
 When the source is a Test Manager test case, a PDD, or any written list of "Click X / Enter Y / Select Z / Verify W" steps, treat each interaction step as a capture target before writing any workflow code.
 
-1. **Inventory.** Read every step. Each interaction (`Click`, `Enter`, `Type`, `Select`, `Choose`, `Verify visible`, `Read`) maps to **one** Object Repository element. Note: assertions ("Verify text contains X") still need an OR element to read from.
+1. **Inventory.** Read every step. Each interaction (`Click`, `Enter`, `Type`, `Select`, `Choose`, `Verify visible`, `Read`) maps to **one** Object Repository element. Note: assertions ("Verify text contains X") still need an Object Repository element to read from.
 2. **Group by screen state.** Sort steps into screen batches — every step before an action that advances the UI (submit, navigate, dialog confirm) belongs to the current screen; the next batch starts after the advance.
 3. **Build the checklist** — three columns per row: `manual step → element name → screen`. Lock the count before opening the app. If the user later adds requirements, capture deltas, do not re-inventory the whole thing.
-4. **Capture screen by screen.** Pre-flight Window Baseline (above) → run `uia-configure-target` for the current screen's batch → register each element in the OR before advancing → use the UIA interact CLI to advance → repeat. The "Complete-then-advance" rule from [uia-configure-target-workflows.md § Multi-Step UI Flows](uia-configure-target-workflows.md) is mandatory; never advance with elements still un-registered.
-5. **Then code.** With every checklist row registered in the OR, write the `.cs` / `.xaml` workflow that calls them in step order. Authoring-phase prerequisites (analyzer rules, project context discovery) run NOW, not earlier.
+4. **Capture screen by screen.** Pre-flight Window Baseline (above) → run `uia-configure-target` for the current screen's batch → register each element in the Object Repository before advancing → use the UIA interact CLI to advance → repeat. The "Complete-then-advance" rule from [uia-configure-target-workflows.md § Multi-Step UI Flows](uia-configure-target-workflows.md) is mandatory; never advance with elements still un-registered.
+5. **Then code.** With every checklist row registered in the Object Repository, write the `.cs` / `.xaml` workflow that calls them in step order. Authoring-phase prerequisites (analyzer rules, project context discovery) run NOW, not earlier.
 
-> Coverage check: after capture, every checklist row must have a matching `Descriptors.<App>.<Screen>.<Element>` path (coded) or OR reference (XAML). Rows without a match indicate a missed capture or an obsolete manual step — reconcile before writing code.
+> Coverage check: after capture, every checklist row must have a matching `Descriptors.<App>.<Screen>.<Element>` path (coded) or Object Repository reference (XAML). Rows without a match indicate a missed capture or an obsolete manual step — reconcile before writing code.
 
 ---
 
@@ -46,12 +46,12 @@ When the source is a Test Manager test case, a PDD, or any written list of "Clic
 | Sense | Used in | What it is | Boundary / identity |
 |-------|---------|------------|---------------------|
 | **Capture screen** | XAML Multi-Screen Authoring (below), [uia-configure-target-workflows.md § Multi-Step UI Flows](uia-configure-target-workflows.md) | A distinct UI state that requires its own `uia-configure-target` pass because the app has to be advanced (via the `uip rpa uia interact` CLI) between captures. | Bounded by app advancement — everything captured before the next advance is one capture screen. |
-| **OR screen** | Object Repository CLI, `.objects/` layout, `Descriptors.<App>.<Screen>.<Element>`, [uia-configure-target-workflows.md](uia-configure-target-workflows.md) | A data-model entity in the Object Repository, registered and matched via the OR CLI. | Identified by its window selector. |
-| **Screen handle** (coded only) | "Screen Handle Affinity" under § For Coded Workflows | A runtime `UiTargetApp` returned by `uiAutomation.Open` / `Attach`, bound to one OR screen. | Element descriptors are valid only on the handle for their own OR screen. |
+| **Object Repository screen** | Object Repository CLI, `.objects/` layout, `Descriptors.<App>.<Screen>.<Element>`, [uia-configure-target-workflows.md](uia-configure-target-workflows.md) | A data-model entity in the Object Repository, registered and matched via the Object Repository CLI. | Identified by its window selector. |
+| **Screen handle** (coded only) | "Screen Handle Affinity" under § For Coded Workflows | A runtime `UiTargetApp` returned by `uiAutomation.Open` / `Attach`, bound to one Object Repository screen. | Element descriptors are valid only on the handle for their own Object Repository screen. |
 
-**These senses are independent.** Multiple capture screens can map to one OR screen when they share a window selector (e.g., several URLs under the same browser tab if the window selector is URL-neutral). Conversely, one OR screen can produce many screen handles at runtime (one per `Open`/`Attach` call).
+**These senses are independent.** Multiple capture screens can map to one Object Repository screen when they share a window selector (e.g., several URLs under the same browser tab if the window selector is URL-neutral). Conversely, one Object Repository screen can produce many screen handles at runtime (one per `Open`/`Attach` call).
 
-**The Multi-Screen Authoring section (§ For XAML Workflows) uses the capture-screen sense.** "2 or more distinct screens" there means 2 or more distinct UI states requiring separate captures — regardless of how many OR screen entries end up getting created.
+**The Multi-Screen Authoring section (§ For XAML Workflows) uses the capture-screen sense.** "2 or more distinct screens" there means 2 or more distinct UI states requiring separate captures — regardless of how many Object Repository screen entries end up getting created.
 
 ---
 
@@ -77,7 +77,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.
-- The activity is wired into the workflow's control flow, package dependencies, scope, and OR registration plumbing. The developer's only remaining work is **Indicate**.
+- 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."
 
@@ -157,7 +157,7 @@ What you must NOT do:
 [Workflow]
 public void Execute(string in_Username, string in_Password, out string out_WIID)
 {
-    // TODO[selectors]: replace these with real uiAutomation calls once OR is populated
+    // TODO[selectors]: replace these with real uiAutomation calls once Object Repository is populated
     Log("LoginWorkflow: type username " + in_Username);
     Log("LoginWorkflow: type password");
     Log("LoginWorkflow: click Login");
@@ -199,17 +199,32 @@ When a procedure exists specifically to check something against ground truth, do
 
 ## Common UIA Pitfalls
 
-- **SelectItem on web dropdowns** — `SelectItem` may fail on custom `<select>` elements. Workaround: use `TypeInto` instead.
+- **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).
 - **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.
-- **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.
+- **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).
 - **`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`.
 
 ---
 
+## 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.
+
+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`.
+- **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).
+
+---
+
 ## Configuring Targets (Object Repository)
 
 [uia-configure-target-workflows.md](uia-configure-target-workflows.md) MUST be read IN FULL first — it covers the configure-target workflow, rules, indication fallback, and multi-step UI flows.
@@ -241,7 +256,7 @@ Application (InvoicePortal)
 Precondition: the source project has captured descriptors (`.objects/` content). If it has none, capture targets first ([§ Configuring Targets](#configuring-targets-object-repository)) — there is nothing to promote, and hand-writing descriptors is forbidden.
 
 1. Develop the first process against its **local** Object Repository, configuring targets as usual ([§ Configuring Targets](#configuring-targets-object-repository)).
-2. Promote the reusable descriptors into a dedicated UI Library project — a library project ([library-authoring-guide.md](library-authoring-guide.md)) holding the shared Object Repository; pack and upload per [library-authoring-guide.md § Pack & Publish](library-authoring-guide.md). Concrete OR manipulation steps: `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/`.
+2. Promote the reusable descriptors into a dedicated UI Library project — a library project ([library-authoring-guide.md](library-authoring-guide.md)) holding the shared Object Repository; pack and upload per [library-authoring-guide.md § Pack & Publish](library-authoring-guide.md). Concrete Object Repository manipulation steps: `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/`.
 3. **One UI Library per corporate application** (SAP, Salesforce, Workday) — an update to one app's selectors must not force re-deployment of another's.
 4. New automations against that application consume the UI Library from the start. Process-specific one-off descriptors stay in the local Object Repository.
 
@@ -314,9 +329,9 @@ For coded-specific API: `.local/docs/packages/UiPath.UIAutomation.Activities/`.
 
 ### Screen Handle Affinity (Critical)
 
-> "Screen" in this section means the **OR screen** sense (see § Terminology) — the Object Repository entity addressed as `Descriptors.<App>.<Screen>.<Element>`. It is NOT the capture-screen sense used by the Multi-Screen Authoring section below.
+> "Screen" in this section means the **Object Repository screen** sense (see § Terminology) — the Object Repository entity addressed as `Descriptors.<App>.<Screen>.<Element>`. It is NOT the capture-screen sense used by the Multi-Screen Authoring section below.
 
-**Each `UiTargetApp` handle is bound to a specific OR screen.** Element descriptors can ONLY be used with the handle for the OR screen they belong to. Using a descriptor from OR Screen A on a handle attached to OR Screen B will fail with `"Target name 'X' is not part of the current screen."`.
+**Each `UiTargetApp` handle is bound to a specific Object Repository screen.** Element descriptors can ONLY be used with the handle for the Object Repository screen they belong to. Using a descriptor from Object Repository Screen A on a handle attached to Object Repository Screen B will fail with `"Target name 'X' is not part of the current screen."`.
 
 ```csharp
 // CORRECT — use Home elements on the homeScreen handle
@@ -351,13 +366,15 @@ Each method on `UiTargetApp` accepts targets in multiple forms:
 
 Read `<PROJECT_DIR>/.local/.codedworkflows/ObjectRepository.cs`. This file contains a `Descriptors` class with the hierarchy `Descriptors.<App>.<Screen>.<Element>`.
 
-> **Generation requires Studio Desktop.** `ObjectRepository.cs` is regenerated only when Studio Desktop detects a coded workflow file (`.cs` with `[Workflow]` / `[TestCase]`) and reconciles it against the OR — `uip rpa build` alone does NOT regenerate it. If the file is missing or stale after registering elements:
+> **Generation requires Studio Desktop.** `ObjectRepository.cs` is regenerated only when Studio Desktop detects a coded workflow file (`.cs` with `[Workflow]` / `[TestCase]`) and reconciles it against the Object Repository — `uip rpa build` alone does NOT regenerate it. If the file is missing or stale after registering elements:
 > 1. Confirm Studio Desktop is running against the project (start it with `uip rpa studio start --project-dir "<PROJECT_DIR>"` if needed).
 > 2. Ensure at least one `.cs` coded workflow exists in the project — Studio only triggers regeneration when it sees a coded surface that needs descriptors.
 > 3. Save / re-open the project in Studio Desktop to force a regen pass.
 >
 > A pure-CLI flow with no Studio Desktop attached will not produce `ObjectRepository.cs`. Plan for a Studio Desktop step in any workflow that depends on `Descriptors.*`.
 
+When `ObjectRepository.cs` is missing or stale (see above), enumerate the project's registered apps/screens/elements as JSON with `uip rpa object-repository get` ([cli-reference.md § object-repository](cli-reference.md#object-repository)) — it reads the saved Object Repository without a Studio Desktop regen. Use it to confirm a screen/element exists before authoring; the strongly-typed `Descriptors.<App>.<Screen>.<Element>` reference still comes from `ObjectRepository.cs`.
+
 **Important:** Add the ObjectRepository using statement:
 ```csharp
 using <ProjectNamespace>.ObjectRepository;
@@ -367,6 +384,8 @@ using <ProjectNamespace>.ObjectRepository;
 
 Look in `project.json` → `dependencies` for packages matching `*.UILibrary`, `*.ObjectRepository`, `*.Descriptors`, or `*.UIAutomation`. Inspect with `uip rpa packages inspect`.
 
+To list the apps/screens/elements a library actually exposes — not just its assembly API — read its Object Repository directly with `uip rpa object-repository get-library` ([cli-reference.md § object-repository](cli-reference.md#object-repository)), pointing at the library `.nupkg` path(s).
+
 For UILibrary packages, use the **package** namespace, not the project namespace:
 ```csharp
 using <PackageNamespace>.ObjectRepository;
@@ -395,9 +414,9 @@ For XAML-specific activity details: `.local/docs/packages/UiPath.UIAutomation.Ac
 
 ### Multi-Screen Authoring
 
-> "Screen" in this section means the **capture-screen** sense (see § Terminology) — a distinct UI state that requires its own `uia-configure-target` pass because the app has to be advanced between captures. It is NOT the OR-screen sense. A workflow that ends up with one OR screen entry can still be multi-screen here — what matters is the number of capture passes separated by `uip rpa uia interact` CLI advances, not the number of `.objects/` screen entries that get created.
+> "Screen" in this section means the **capture-screen** sense (see § Terminology) — a distinct UI state that requires its own `uia-configure-target` pass because the app has to be advanced between captures. It is NOT the Object Repository screen sense. A workflow that ends up with one Object Repository screen entry can still be multi-screen here — what matters is the number of capture passes separated by `uip rpa uia interact` CLI advances, not the number of `.objects/` screen entries that get created.
 
-For workflows spanning multiple capture screens, add each screen's activities to the workflow as its targets are registered in the OR. All UI activities belong inside the `NApplicationCard` scope. Validate with `validate` after each batch. [uia-configure-target-workflows.md](uia-configure-target-workflows.md) MUST be read IN FULL first (see § Multi-Step UI Flows for the capture loop and the Complete-then-advance rule).
+For workflows spanning multiple capture screens, add each screen's activities to the workflow as its targets are registered in the Object Repository. All UI activities belong inside the `NApplicationCard` scope. Validate with `validate` after each batch. [uia-configure-target-workflows.md](uia-configure-target-workflows.md) MUST be read IN FULL first (see § Multi-Step UI Flows for the capture loop and the Complete-then-advance rule).
 
 ### Key Concepts
 
@@ -405,6 +424,96 @@ For workflows spanning multiple capture screens, add each screen's activities to
 
 Every UI automation workflow starts with an **Application Card** (`uix:NApplicationCard`) that opens or attaches to a desktop application or web browser. All UI activities (Click, TypeInto, GetText, etc.) must be placed inside an Application Card scope.
 
+> **Default to ONE Application Card — choose simplicity.** A single `ByInstance` card (the default) covers the *entire* application instance: main window, dialogs, pop-ups, menus, and owned child windows. Add a second or nested card **only** to reach a genuinely *different* application (a different process/instance), or when `ByInstance` provably fails to attach to or find an owned window. Do **NOT** add a card per window, per dialog, or per Object Repository screen. More cards = more scope to keep aligned and more failure surface, for no benefit when the windows share one instance.
+
+##### Window Attach Mode
+
+`NApplicationCard` attaches via the `AttachMode` property (type `NAppAttachMode`, default `ByInstance`), which controls where inner activities search for their targets. Change it per the Application Card docs in the package docs (`{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/activities/ApplicationCard.md`).
+
+**`ByInstance` — Application Instance (default, preferred).** The card finds the window from its selector, then attaches to ALL windows of that application instance (main window, dialogs, child windows). Per activity: it locates the target window among the instance's windows using the activity target's **scope selector**, then searches the target inside that window.
+
+Use when the app opens separate windows (e.g. a dialog) — one card covers all of them; no second card needed. An activity whose scope selector targets the dialog window finds its element there.
+
+```xml
+<uix:NApplicationCard AttachMode="ByInstance" DisplayName="Use App (Invoice app)"
+                      sap2010:WorkflowViewState.IdRef="NApplicationCard_1" Version="V2">
+    <uix:NApplicationCard.Body>
+        <Sequence sap2010:WorkflowViewState.IdRef="Sequence_1">
+            <!-- scope selector targets the main window -->
+            <uix:NClick DisplayName="Click New Invoice" sap2010:WorkflowViewState.IdRef="NClick_1" />
+            <!-- scope selector targets the dialog window of the same instance -->
+            <uix:NTypeInto DisplayName="Type amount in dialog" Text="[in_Amount]"
+                           sap2010:WorkflowViewState.IdRef="NTypeInto_1" />
+        </Sequence>
+    </uix:NApplicationCard.Body>
+</uix:NApplicationCard>
+```
+
+**`SingleWindow` — Single Window (only if Application Instance fails).** The card attaches ONLY to the window from its selector. A target in any other window of the same application (parent, child, dialog) is NOT found. The activity target's scope selector is **always** ignored in this mode. Use only when `ByInstance` fails to attach.
+
+```xml
+<uix:NApplicationCard AttachMode="SingleWindow" DisplayName="Use App (single window)"
+                      sap2010:WorkflowViewState.IdRef="NApplicationCard_2" Version="V2">
+    <uix:NApplicationCard.Body>
+        <Sequence sap2010:WorkflowViewState.IdRef="Sequence_2">
+            <!-- only targets in THIS window resolve; scope selector is ignored -->
+            <uix:NClick DisplayName="Click Save" sap2010:WorkflowViewState.IdRef="NClick_2" />
+        </Sequence>
+    </uix:NApplicationCard.Body>
+</uix:NApplicationCard>
+```
+
+##### One application instance = one card (even with multiple Object Repository screens)
+
+The Object Repository registers a separate **screen** for every distinct window selector — a dialog, pop-up, or child window with its own title is captured as its own Object Repository screen. This is expected and does **NOT** mean you need a card per screen. **Object Repository screens ≠ Application Cards.** The number of Object Repository screens is driven by window selectors; the number of cards is driven by how many distinct *applications* you touch.
+
+With `ByInstance`, a single card hosts activities scoped to several Object Repository screens as long as those windows belong to the same application instance. Each activity's scope selector locates the right window *within* the instance — the card's own selector does not need to match any one screen. Owned dialogs and pop-ups are part of the target application, so a correctly scoped activity validates and runs under the one card; you do **not** need a dedicated card to avoid an "indicated element does not belong to the target application/browser" error.
+
+**Example — MS Paint File ▸ Open ▸ Cancel.** Clicking *File* then *Open* spawns the Win32 **Open** dialog (`#32770`), a separate top-level window the Object Repository captures as its own screen (`title='Open'`), distinct from the main window (`title='*Paint*'`). Because the dialog is an owned window of the same `mspaint.exe` instance, all three clicks (File, Open, Cancel) go in **one** `ByInstance` card. The File-menu pop-up needs no card of its own — and neither does the Open dialog. Adding a nested card for the dialog is unnecessary complexity.
+
+Do not nest a card just because the Object Repository captured a second screen, or to "keep scope and selector aligned" — `ByInstance` already aligns each activity to its window by scope selector. Reach for a second card only after the [escalation gate below](#nesting-application-cards) applies.
+
+##### Nesting Application Cards
+
+> **Nest cards only for genuinely different applications** — e.g. copying a value from App A into App B, two separate processes. For dialogs, pop-ups, menus, and child windows of the *same* application instance, use a single `ByInstance` card (see [§ One application instance = one card](#one-application-instance--one-card-even-with-multiple-object-repository-screens)). Reach for a nested card on the same instance **only** if `ByInstance` provably fails to attach to or find the owned window — not because the Object Repository captured it as a separate screen.
+
+Application Cards can nest; a UI Automation activity can run inside any Application Card on its parent chain. To switch back and forth between two applications, nest two Application Cards and put all UI Automation activities inside the bottom-most one, attaching each activity to the correct card.
+
+Each `NApplicationCard` carries a `ScopeGuid`. A child activity attaches to a specific card by setting its `ScopeIdentifier` equal to that card's `ScopeGuid` — this is how an activity inside the inner card targets the outer card's application. Change an activity's attached card per the Application Card docs in the package docs.
+
+**IMPORTANT:** ONLY activities that have a target configured and set can have a `ScopeIdentifier`. If an activity does not have a target, do NOT add `ScopeIdentifier` to it.
+
+Example — copy a value from App A and paste it into App B. Outer card → App A, inner (nested) card → App B; both activities live in the inner card. The read sets `ScopeIdentifier` to App A's `ScopeGuid`; the write sets it to App B's. Repeat to move back and forth — no card re-entry between switches.
+
+```xml
+<uix:NApplicationCard AttachMode="ByInstance" DisplayName="App A (source)"
+                      ScopeGuid="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
+                      sap2010:WorkflowViewState.IdRef="NApplicationCard_1" Version="V2">
+    <uix:NApplicationCard.Body>
+        <Sequence sap2010:WorkflowViewState.IdRef="Sequence_1">
+            <uix:NApplicationCard AttachMode="ByInstance" DisplayName="App B (target)"
+                                  ScopeGuid="bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
+                                  sap2010:WorkflowViewState.IdRef="NApplicationCard_2" Version="V2">
+                <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]"
+                                      ScopeIdentifier="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
+                                      sap2010:WorkflowViewState.IdRef="NGetText_1" Version="V5" />
+                        <!-- ScopeIdentifier = App B card's ScopeGuid → pastes into App B (inner) -->
+                        <uix:NTypeInto DisplayName="Type value into App B" Text="[out_Value]"
+                                       ScopeIdentifier="bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
+                                       sap2010:WorkflowViewState.IdRef="NTypeInto_1" Version="V5" />
+                    </Sequence>
+                </uix:NApplicationCard.Body>
+            </uix:NApplicationCard>
+        </Sequence>
+    </uix:NApplicationCard.Body>
+</uix:NApplicationCard>
+```
+
+> GUIDs above are illustrative placeholders. A card's `ScopeGuid` is generated by `uip rpa activities get-default-xaml` (the starter XAML for `NApplicationCard`) — do not hand-author it. To attach an activity to a card, set the activity's `ScopeIdentifier` to that card's `ScopeGuid`.
+
 #### Target Configuration
 
 [uia-configure-target-workflows.md](uia-configure-target-workflows.md) MUST be read IN FULL first — it covers registering the Application Card's screen and each activity's elements in the Object Repository. Then write plain activities (NApplicationCard, NClick, NTypeInto, ...) with unique `sap2010:WorkflowViewState.IdRef` attributes and no `.Target` children, and attach targets per `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/references/uia-target-attachment-guide.md`.
@@ -427,6 +536,8 @@ Do NOT hand-write `<uix:TargetApp>` or `<uix:TargetAnchorable>` XAML from scratc
 | **Extract Table Data** | Extracts tabular data from a web page or application |
 | **ScreenPlay** | AI-powered UI task execution (last resort — non-deterministic and slow) |
 
+> **Before authoring `TypeInto` / `SelectItem` / `Click`:** reading [§ Control-Specific Interaction Patterns](#control-specific-interaction-patterns) is mandatory.
+
 ### XAML-Specific Pitfalls
 
 - **Missing `xmlns:uix`** — every UIA workflow needs `xmlns:uix="http://schemas.uipath.com/workflow/activities/uix"` on the root `<Activity>` element

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

@@ -18,6 +18,13 @@ Read the SKILL.md, then execute each step of the internal procedure yourself. On
 
 The `uia-configure-target` skill lives at `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/skills/uia-configure-target/` — read `SKILL.md` for the internal procedure and `USAGE.md` for invocation modes (TargetAnchorable, TargetApp, and the batch `|` pattern for multiple elements on the same screen). These are **reference docs to read and follow** — they are NOT invocable as slash commands via the Skill tool.
 
+**Locating the skill file.** The package ID is constant, so the path above is fixed — the reliable way to open it is a direct `Read` of `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/skills/uia-configure-target/SKILL.md`. If you use `Glob` to find it instead, the pattern **must start with** `**/` — `Glob` matches the pattern against each hit's path relative to the working directory, not relative to the `path` argument, so a pattern that begins with a literal folder name matches nothing:
+
+- ✅ `Glob(path=".../UiPath.UIAutomation.Activities", pattern="**/uia-configure-target/SKILL.md")`
+- ❌ `Glob(path=".../UiPath.UIAutomation.Activities", pattern="skills/uia-configure-target/SKILL.md")` — returns "No files found" even though the file exists.
+
+A `Glob` miss is not evidence the skill is absent; never infer availability from it — the installed package version in `project.json` is the source of truth (see [uia-prerequisites.md](uia-prerequisites.md)).
+
 Before invoking, check the unsupported-activities list in `USAGE.md`. If the activity you need to target is on that list, skip `uia-configure-target` for it and use the [Indication Fallback](#indication-fallback) instead.
 
 ## Rules
@@ -78,6 +85,20 @@ The indicated element does not belong to the target application/browser.
 
 The validator compares each child target's `ScopeSelectorArgument` against the parent card's `TargetApp` selector — different `app=` values trigger this error every time, even when the runtime selectors are correct.
 
+> **First, confirm it is actually a separate process.** This whole section applies **only** when the helper runs in a *different process* — a different `app=`. Before nesting anything, compare the secondary window's captured `ScopeSelectorArgument` with the outer card's `TargetApp`: **different `app=` → nest a card (Pattern below); same `app=` → reuse the existing card (next).** A separate top-level window is *not*, by itself, a reason to add a card.
+
+### Same-Process Secondary Windows — Reuse the Card (Do NOT Nest)
+
+Most dialogs, property sheets, Win32 common dialogs (`#32770`: Open / Save / Print / Properties), pop-ups, and child windows belong to the **same process** as the app that spawned them — same `app=`, only a different `cls=` / `title=`. These do **not** get their own card.
+
+With the default `AttachMode="ByInstance"`, one `NApplicationCard` attaches to the **whole application instance**, not a single window. Each child activity finds its target window *within* that instance from its own `ScopeSelectorArgument` — so an activity whose scope selector names the dialog resolves there even though the card's `TargetApp` names the main window. A second card buys nothing and adds another scope to keep aligned.
+
+The `app=`-keyed validation check above does not trip here either: the same `app=` on child and card means no "does not belong to the target application/browser" error. That error is about a different *process*, never a different *window* of the same process.
+
+**Example — MS Paint File ▸ Open ▸ Cancel.** Clicking *File* then *Open* spawns the Win32 **Open** dialog (`#32770`), a separate top-level window the Object Repository captures as its own screen. The *Cancel* button's `ScopeSelectorArgument` is `<wnd app='mspaint.exe' cls='#32770' title='Open' />`, while the Paint card's `TargetApp` is `<wnd app='mspaint.exe' cls='MSPaintApp' title='*Paint*' />`. Same `app=` → the Open dialog is already reachable from the **existing** Paint card under `ByInstance`, so all three clicks (File, Open, Cancel) go in **one** card. The File-menu pop-up needs no card of its own, and neither does the Open dialog. Adding a second card is wrong: do not nest it, and do not claim a single card "would fail validation" — same-process windows pass the `app=` check, and `ByInstance` spans the instance's windows. See [ui-automation-guide.md § One application instance = one card](ui-automation-guide.md#one-application-instance--one-card-even-with-multiple-object-repository-screens).
+
+Use the nested-card pattern below **only** when the secondary window is a genuinely separate process.
+
 ### Pattern: Nest a Second `NApplicationCard` for the Helper Process
 
 Wrap the activities that target the helper process in their own `NApplicationCard` scoped to that process. Use a wildcard title (`title='*'`) when the helper presents multiple sub-dialogs (e.g., "Sign in" → "Enter password" → "Stay signed in?") so a single nested card covers them all.
@@ -126,7 +147,7 @@ Wrap the activities that target the helper process in their own `NApplicationCar
 
 **Rules:**
 
-1. **One `NApplicationCard` per process** — every direct or transitive child activity must target the same `app=` as its enclosing card's `TargetApp`. If activities target two processes, you need two cards.
+1. **One `NApplicationCard` per process — not per window.** Every direct or transitive child activity must target the same `app=` as its enclosing card's `TargetApp`. Two *processes* (different `app=`) need two cards; two *windows* of the same process — dialogs, pop-ups, `#32770` common dialogs — share **one** card under `ByInstance` (see § Same-Process Secondary Windows). Do not add a card just because a secondary top-level window appeared.
 2. **Each card has its own `ScopeGuid`.** Child activities reference their card via `ScopeIdentifier="<that-card's-ScopeGuid>"`. When moving an activity from one card to another, update `ScopeIdentifier` — `validate` will not catch a mismatched value, but the activity will run against the wrong scope at runtime.
 3. **Card-level `HealingAgentBehavior`** uses `NHealingAgentBehavior` (`Job`/`Disabled`/`RecommendationOnly`) — not `SameAsCard`. Details: [ui-automation-guide.md § Common UIA Pitfalls](ui-automation-guide.md).
 4. **Use `title='*'`** on the helper-process card only when multiple sub-dialogs share the same `app=` and you want a single scope to span them. If sub-dialogs have stable, distinct titles AND only the outer `app=` is shared with the host app (rare), prefer a separate card per dialog so failures localize cleanly.

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

@@ -0,0 +1,93 @@
+# UI Elements Interaction Guide
+
+How to *drive* a captured UI element correctly — type-specific handling that selector capture alone does not cover.
+
+**Read [ui-automation-guide.md](ui-automation-guide.md) in full first (Rule 7).** This guide assumes the target is already captured in the Object Repository; it covers interaction technique, not capture.
+
+Patterns are grouped by scope: technology-specific controls first (web), then cross-technology patterns.
+
+---
+
+## Web Controls (`webctrl`)
+
+Applies to browser elements — elements whose captured selector uses the `webctrl` tag.
+
+### Date and formatted date-time inputs
+
+Date / formatted date-time inputs must be driven with a **key-event input method**, so the value typed must match the field's **displayed** format. Detect that format, format the value to match, then type it. Try typing WITHOUT emptying the field first; keep emptying as a fallback.
+
+1. **Use a key-event input method — type the displayed format, not the ISO `value`.** In scope: native `<input type="date">` inputs, and framework date-time pickers that *look* like a date field but are built from a more complex structure (divs/spans or several `<input>` parts). Their displayed format and canonical `value` are frequently **different**: a native `<input type="date">` stores `2026-06-19` but renders `06/19/2026` (en-US locale). Drive them with **Chromium API (`DebuggerApi`)** (preferred for browsers) or **Hardware Events** — these dispatch real key events into the control's segmented / composite UI, so the typed string must match the **rendered** format (e.g. en-US native date input → `MM/DD/YYYY`), NOT the ISO value. You must therefore detect how the field is actually printed — step 2.
+
+   **Do NOT use Simulate for date inputs.** Simulate only sets the element's underlying value; it does not dispatch the `input` / `change` events the control's validation and framework data-binding depend on, so the date often fails to register or commit.
+
+2. **Detect the displayed format at design time — never assume, and never trust `value`.** Resolve it *while authoring* — during capture, when the snapshot's element refs (`e5`, …) are live — and bake the result into the workflow. Do not add a runtime read for a format fixed for the target app. This read determines the value to type; it is NOT selector construction (that stays the `uia-configure-target` flow's job).
+
+   Read from the live element with one of three strategies — **stop at the first that yields the displayed format**. Ordered by typical web reliability; the raw attribute is **last** because `value` reports the canonical/ISO form, which often does not match what is rendered:
+
+   | # | Strategy | Use when | Trade-off |
+   |---|----------|----------|-----------|
+   | 1 | **Inject JavaScript** — interact CLI browser-eval verb, element-scoped (`(el) => …`). Read `type`, `placeholder`, a framework picker's sub-input values / internal state, shadow DOM. For a **native date input** the rendered segments are not in the DOM (`value` is ISO) and a locale guess (`navigator.language` / `Intl`) only reflects the *content-language* preference — which can differ from the browser/OS **UI locale** that actually renders the picker — so treat it as a hint and confirm with strategy 2. | Reliable for framework pickers whose format is exposed in the DOM (`placeholder` / sub-input values). | Web only; fragile to page changes. Locale guess may not match a native date picker. |
+   | 2 | **Screenshot** — interact CLI screenshot verb on the element/window; read the rendered placeholder/value visually. | JS cannot derive it (canvas-rendered, opaque widget), or to read/confirm the rendered order for a **native date input** (the reliable read — strategy 1's locale guess can diverge). | Non-deterministic (visual interpretation). |
+   | 3 | **Read the attribute** — interact CLI attribute-read verbs (`get <ref> <attribute>` for one; `get-all <ref>` to dump all). A `placeholder` (e.g. `MM/DD/YYYY`) is a good explicit hint **when present**. | A `placeholder` / explicit format attribute exists. | Deterministic, but `value` and the accessibility value are the **canonical/ISO** form — they may NOT match the displayed format. Never infer the typing format from `value` alone for a native date input. |
+
+   **Validate the command before running it.** Verb names, positional-argument order, and flags are owned by the package — confirm each against `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/references/cli-reference.md` before use. Do NOT author these commands from memory; names and argument order may differ from this table.
+
+3. **Format the date string to match** the resolved displayed format before typing — e.g. for an en-US native date input, convert ISO `2026-07-01` → `07/01/2026`.
+4. **Type the formatted value — try WITHOUT emptying the field first** (`NTypeInto` property `EmptyField` left false). Emptying is not forbidden: if the field keeps stale/residual content or the value is not replaced cleanly, retry with the field emptied (`EmptyField=true`). Confirm the exact property name/default in `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/activities/NTypeInto.md`.
+
+Why try without emptying first: native date inputs and framework date-time pickers maintain a segmented / internal value. Clearing (`EmptyField`, or `Ctrl+A`+`Delete`) can leave the control in a partial state or trip its validation, so typing the correctly-formatted value over the field usually lets the control's own input handling replace the content cleanly. If it does not — stale value remains, or the input rejects the overlaid text — empty the field and type again.
+
+```xml
+<uix:NTypeInto DisplayName="Type Invoice Date"
+               Text="[formattedDate]"
+               EmptyField="False"
+               sap2010:WorkflowViewState.IdRef="NTypeInto_1" />
+```
+
+```csharp
+// First attempt: EmptyField false → field is not cleared before typing.
+// Fallback if content isn't replaced cleanly: set EmptyField true.
+formScreen.TypeInto(Descriptors.MyApp.Form.InvoiceDate, formattedDate);
+```
+
+### Dropdowns — native `<select>` vs custom widgets
+
+Branch on what the control actually is:
+
+| 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. |
+
+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'`.
+
+---
+
+## All UI Technologies
+
+Patterns that apply to any captured control regardless of UI stack (web, desktop, Java, etc.).
+
+### Buttons disabled during async operations
+
+A button can be present and matched by its selector yet `disabled` while the application validates a form, loads, or refreshes data.
+
+This is distinct from the late-appearing-target case in [§ Common UIA Pitfalls](ui-automation-guide.md): that pitfall is about a target that *appears* after a delay — the UIA activity's target-finding retry already handles appearance. Retry does NOT cover enabled state — the activity finds the disabled button immediately and clicks a dead control. Check App State does not help either: it waits for an element to appear/disappear, not to become enabled.
+
+Mitigation: set `DelayBefore` (and/or `DelayAfter`) on the click so the async operation has time to enable the button before the click fires. These are properties ON the activity — NOT the standalone `Delay` activity the pitfall warns against.
+
+- Use `DelayBefore` only when the button has an observable disabled→enabled transition driven by validation / load / refresh.
+- Keep it as small as reliably works — it is a fixed wait that runs on every execution. It raises the odds the button is enabled at click time; it is not a guarantee.
+
+```xml
+<uix:NClick DisplayName="Click Submit (form validates first)"
+            DelayBefore="1"
+            sap2010:WorkflowViewState.IdRef="NClick_1" />
+```
+
+```csharp
+// Set the click options' delay-before; confirm the option name and unit in
+// {PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/activities/NClick.md
+formScreen.Click(Descriptors.MyApp.Form.Submit, new NClickOptions { DelayBefore = 1 });
+```
+
+Confirm property names, defaults, and time units against the installed `NTypeInto.md` / `NClick.md` activity docs — do not author UIA property surfaces from memory (SKILL.md Rule 21).

package/skills/uipath-rpa/references/xaml/canvas-layout-guide.md

@@ -68,6 +68,22 @@ Every activity should have `sap:VirtualizedContainerService.HintSize` as an attr
 
 ## 3. Flowchart Layout
 
+Node vocabulary, structure & wiring, and node registration: [flowchart-guide.md](flowchart-guide.md). This section covers layout coordinates and ViewState only.
+
+### What Counts as a Node
+
+A node is one `FlowStep` / `FlowDecision` / `FlowSwitch` on the canvas. A `FlowStep` wraps **exactly one** activity — which may be a container (`Sequence`, `NApplicationCard`, `NCheckState`, `TryCatch`). Activities **inside** a container are NOT separate nodes; they stay nested in their parent and never get their own `ShapeLocation`. Promote a step to its own node only when it is a top-level step in the process flow. Example: an `NCheckState`'s `Throw` belongs inside the `IfNotExists` branch — making it a sibling node would change when it runs.
+
+One node per top-level step → separate boxes. One step's children nested → stay inside that box. Do not invert this into "every activity is a node."
+
+### Required vs. Optional ViewState Keys
+
+`ShapeLocation` + `ShapeSize` are the **required** pair on every node — they are what makes nodes render as separate boxes. `ConnectorLocation` (and `TrueConnector`/`FalseConnector`) is **optional**: Studio auto-routes connectors from the source and target node positions. The recipes below include connectors for precise routing, but omitting them is valid — Studio's own saved output omits them entirely.
+
+### No Orphan Nodes
+
+Every node except the start must be reachable: referenced by `Flowchart.StartNode`, a `FlowStep.Next`, or a decision/switch branch. A `FlowStep` with no incoming reference and no `FlowStep.Next` is an orphan — it renders as a disconnected box and is almost always a leftover. Do not generate them.
+
 ### Coordinate System
 
 - **Origin**: Top-left corner (0, 0)
@@ -265,6 +281,27 @@ FlowDecision:  (270, 220)     60x60
 
 All FlowStep/FlowDecision/FlowSwitch nodes must be registered as children of `<Flowchart>`. Direct children are already registered. Nodes defined inline within property elements (e.g., inside `FlowDecision.True`) need a trailing `<x:Reference>` entry at the Flowchart level.
 
+Only nodes in the `Flowchart.Nodes` collection (the direct children) render. ViewState positions a node **only after** it is registered there — coordinates on an unregistered node do nothing.
+
+**Forbidden — nested FlowStep chains.** Do NOT build the flow by physically nesting each `FlowStep` inside the previous one's `<FlowStep.Next>`, leaving only the first node under `<Flowchart.StartNode>`. Nested-only steps never enter `Flowchart.Nodes`, so the designer renders almost nothing — invisible regardless of ViewState. Wire each step's successor with `<FlowStep.Next><x:Reference>__ReferenceIDn</x:Reference></FlowStep.Next>` and keep every `FlowStep` a direct child of `<Flowchart>`:
+
+```xml
+<Flowchart>
+  <Flowchart.StartNode>
+    <x:Reference>__ReferenceID0</x:Reference>
+  </Flowchart.StartNode>
+  <FlowStep x:Name="__ReferenceID0">           <!-- direct child -->
+    <ui:LogMessage DisplayName="Step 1" />
+    <FlowStep.Next>
+      <x:Reference>__ReferenceID1</x:Reference> <!-- link by reference, NOT by nesting -->
+    </FlowStep.Next>
+  </FlowStep>
+  <FlowStep x:Name="__ReferenceID1">           <!-- direct child -->
+    <ui:LogMessage DisplayName="Step 2" />
+  </FlowStep>
+</Flowchart>
+```
+
 See [common-pitfalls.md § x:Reference](common-pitfalls.md#xreference--__referenceid-naming) for the full rules with correct/wrong examples.
 
 ---
@@ -637,10 +674,10 @@ Same rules as Flowchart — nodes defined inline within property elements (e.g.,
 
 ---
 
-## 7. When to Skip ViewState
+## 7. ViewState Is Mandatory for These Canvases
 
-If generating XAML for **execution only** (not for visual display), you can omit all ViewState properties. The workflow will execute correctly. Studio will auto-arrange nodes when the file is first opened.
+Always generate ViewState for **every** node in a Flowchart, State Machine, or ProcessDiagram. Do **not** skip it, even for "execution-only" workflows.
 
-**Trade-off:** The initial layout will be messy — all nodes may overlap at (0,0). For a professional-looking layout, always include ViewState.
+Omitting ViewState does not break execution, but Studio places every node at (0,0). They overlap into what looks like **a single node** — and Studio does **not** auto-arrange on open. The stacked layout persists until a user manually right-clicks → Auto Arrange. A generated workflow that opens as one overlapping node reads as broken.
 
-**Recommended approach:** Generate ViewState for all Flowchart, State Machine, and ProcessDiagram workflows. It adds bulk but produces immediately usable designs.
+The only ViewState you skip: **Sequences** (Studio stacks their children vertically without coordinates) and **nodes you are not editing** in an existing file (leave their ViewState untouched).

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

@@ -438,7 +438,7 @@ Guessed names (e.g. `method`/`path`/`body` for an HTTP operation that actually e
 
 ### `Configuration` Attribute Is Opaque
 
-The `Configuration` attribute on `ConnectorActivity` is a base64 + gzip JSON blob encoding connector + operation identity (`ConnectorKey`, `ObjectName`, `HttpMethod`, `Operation`, `ActivityType`). **Never hand-edit.** Always take the value verbatim from `uip rpa activities get-default-xaml --activity-type-id <GUID> --connection-id <GUID>`.
+The `Configuration` attribute on `ConnectorActivity` is a base64 + gzip JSON blob encoding connector + operation identity (`ConnectorKey`, `ObjectName`, `HttpMethod`, `Operation`, `ActivityType`). **Never hand-edit.** Always take the value verbatim from `uip rpa activities get-default-xaml --activity-type-id <GUID> --connection-id <GUID>`. When an operation's full schema is gated behind prerequisite criteria fields (Jira `project`/`issuetype`, generic record `Type`), re-run that command with `--field-values <criteria>=<value>` to obtain the expanded blob — never splice extra fields into an old blob (see [is-connector-xaml-guide.md § Hidden Secondary Fields](../is-connector-xaml-guide.md)).
 
 ### `FieldObject.Value` Attribute Does Nothing
 
@@ -536,6 +536,8 @@ Use `uip rpa activities get-default-xaml` to get correct xmlns declarations —
 
 ## DataTable Activity Gotchas
 
+Activity-level mechanics below. For the expression/code layer (LINQ filter/sort/group/join/diff, RegEx, DateTime, collections, JSON) see [data-manipulation-guide.md](../data-manipulation-guide.md).
+
 - **LookupDataTable column resolution**: When multiple column identifiers are set (shouldn't happen due to OverloadGroups), only the first non-null is used: `LookupColumnIndex ?? LookupColumnName ?? LookupDataColumn`
 - **FilterDataTable**: Column must exist AND be type-compatible with the filter operator. Filtering a DateTime column with "Contains" fails at CacheMetadata validation.
 - **BuildDataTable**: Uses a security-related allowed types list. DataTables with certain .NET types may fail to serialize/deserialize.
@@ -551,15 +553,22 @@ Use `uip rpa activities get-default-xaml` to get correct xmlns declarations —
        xmlns:s="clr-namespace:System;assembly=mscorlib" -->
   <Variable x:TypeArguments="sd:DataTable" Name="dt" Default="[New System.Data.DataTable()]" />
   ...
-  <InvokeMethod TargetObject="[dt.Columns]" MethodName="Add">
+  <InvokeMethod MethodName="Add">
+    <InvokeMethod.TargetObject>
+      <InArgument x:TypeArguments="sd:DataColumnCollection">[dt.Columns]</InArgument>
+    </InvokeMethod.TargetObject>
     <InArgument x:TypeArguments="x:String">Name</InArgument>
     <InArgument x:TypeArguments="s:Type">[GetType(System.String)]</InArgument>
   </InvokeMethod>
-  <InvokeMethod TargetObject="[dt.Columns]" MethodName="Add">
+  <InvokeMethod MethodName="Add">
+    <InvokeMethod.TargetObject>
+      <InArgument x:TypeArguments="sd:DataColumnCollection">[dt.Columns]</InArgument>
+    </InvokeMethod.TargetObject>
     <InArgument x:TypeArguments="x:String">Amount</InArgument>
     <InArgument x:TypeArguments="s:Type">[GetType(System.Decimal)]</InArgument>
   </InvokeMethod>
   ```
+  `TargetObject` MUST be the typed property-element form (`InArgument x:TypeArguments="sd:DataColumnCollection"`) — the attribute shorthand `TargetObject="[dt.Columns]"` fails validation with `Set property 'InvokeMethod.TargetObject' threw an exception` because overload resolution can't see `Add` on the untyped target.
   **C# XAML** (`expressionLanguage: CSharp`): replace bracket-shorthand expressions with `<CSharpValue x:TypeArguments="T">...</CSharpValue>` / `<CSharpReference x:TypeArguments="T">...</CSharpReference>` wrappers inside the `<InArgument>`/`<Default>` elements. See [csharp-activity-binding-guide.md](csharp-activity-binding-guide.md) for the full binding form per property.
 
   Note the `s:Type` argument — `x:Type` resolves to `TypeExtension` and fails (see § Invalid Use of `x:` Prefix). `assembly=System.Data` works in both targets via .NET type forwarding; `System.Data.Common` is the canonical home in modern .NET but the bundled UiPath docs standardize on `System.Data`.