@uipath/skills 1.199.0 → 1.200.0

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

@@ -149,7 +149,7 @@ VB.NET expressions use bracket notation `[expression]` inline in attributes:
 
 **XML escaping required inside expressions:** `<` → `&lt;`, `>` → `&gt;`, `"` → `&quot;`, `&` → `&amp;`
 
-**Throw.Exception quote escaping gotcha:** Fully-qualified class names + complex string expressions with multiple `&quot;` in `Throw.Exception` can cause compiler errors. Use short-form class names (`BusinessRuleException` not `UiPath.Core.Activities.BusinessRuleException`) and for complex messages, assign to a variable first then throw with the variable. See [common-pitfalls.md](./common-pitfalls.md#vbnet-quote-escaping-in-throwexception-critical-for-xaml-generation) for the full pattern.
+**Throw.Exception quote escaping gotcha:** Fully-qualified class names + complex string expressions with multiple `&quot;` in `Throw.Exception` can cause compiler errors. Use short-form class names (`BusinessRuleException` not `UiPath.Core.Activities.BusinessRuleException`) and for complex messages, assign to a variable first then throw with the variable. See [§ VB.NET Quote Escaping in Throw.Exception](#vbnet-quote-escaping-in-throwexception-critical-for-xaml-generation) for the full pattern.
 
 For comprehensive VB.NET expression patterns (strings, dates, collections, DataTables), see [activity-docs/_PATTERNS.md](./activity-docs/_PATTERNS.md).
 
@@ -454,4 +454,269 @@ xmlns:ucsvact="clr-namespace:UiPath.CSV.Activities;assembly=UiPath.Excel.Activit
 7. **Never add trailing `<x:Reference>` for Flowchart child nodes** — FlowStep/FlowDecision/FlowSwitch nodes defined inline as direct children of `<Flowchart>` must NOT be re-listed with `<x:Reference>` at the end. Only use `<x:Reference>` inside property elements (`Flowchart.StartNode`, `FlowStep.Next`, `FlowDecision.True/False`, etc.) to create cross-references
 8. **State Machine needs exactly one `IsFinal="True"` state** for proper termination
 9. **Legacy uses `assembly=mscorlib`** — not `assembly=System.Private.CoreLib` (which is .NET 6+)
-10. **Scope activities require `ActivityAction<T>` body** — `ExcelApplicationScope`, `ExcelProcessScopeX`, `ExcelApplicationCard`, `WordApplicationScope`, etc. do NOT accept direct children. They require a `.Body` property with `ActivityAction<T>` and `DelegateInArgument`. See [common-pitfalls.md](./common-pitfalls.md#scope-activities-require-activityaction-body-critical-for-xaml-generation) for the complete template.
+10. **Scope activities require `ActivityAction<T>` body** — `ExcelApplicationScope`, `ExcelProcessScopeX`, `ExcelApplicationCard`, `WordApplicationScope`, etc. do NOT accept direct children. They require a `.Body` property with `ActivityAction<T>` and `DelegateInArgument`. See [§ Scope Activities Require ActivityAction Body](#scope-activities-require-activityaction-body-critical-for-xaml-generation) for the complete template.
+
+---
+
+## Common Pitfalls & Quick Reference
+
+Essential gotchas, required scopes, and VB.NET patterns for legacy UiPath RPA workflows.
+
+For the complete gotchas list, see [activity-docs/_COMMON-PITFALLS.md](./activity-docs/_COMMON-PITFALLS.md).
+For the complete VB.NET cheat sheet, see [activity-docs/_PATTERNS.md](./activity-docs/_PATTERNS.md).
+
+---
+
+### Flowcharts/StateMachines Without ViewState
+
+**Severity: HIGH.** Missing ViewState causes Studio to stack all nodes at (0,0) — unusable. Every Flowchart/StateMachine node needs `ShapeLocation` + `ShapeSize`. **Required xmlns:** `xmlns:av="http://schemas.microsoft.com/winfx/2006/xaml/presentation"`
+
+See [activity-docs/_XAML-GUIDE.md](./activity-docs/_XAML-GUIDE.md) for coordinate systems, standard sizes, layout algorithms, connector formulas, and complete examples.
+
+---
+
+### Required Parent Scopes
+
+These classic activities **must** be placed inside a specific parent scope:
+
+| Activities | Required Parent Scope |
+|-----------|----------------------|
+| Excel Interop (ExcelReadRange, ExcelWriteCell, etc.) | `Excel Application Scope` |
+| Excel Modern (ReadRangeX, WriteRangeX, etc.) | `ExcelApplicationCard` inside `ExcelProcessScopeX` |
+| PowerPoint Interop (InsertSlide, InsertText, etc.) | `PowerPoint Application Scope` |
+| Word Interop (AppendText, ReplaceText, etc.) | `Word Application Scope` |
+| FTP activities (Download, Upload, Delete, etc.) | `FTP Session` (WithFtpSession) |
+| Java activities (InvokeJavaMethod, LoadJar, etc.) | `Java Scope` |
+| Python activities (RunScript, InvokeMethod, etc.) | `Python Scope` |
+| Terminal activities (GetField, SetField, SendKeys, etc.) | `Terminal Session` |
+| Office 365 activities (SendMail, CreateEvent, etc.) | `Microsoft Office 365 Scope` |
+| SAP BAPI activities (InvokeSapBapi) | `SAP Application Scope` |
+| SharePoint activities (GetListItems, UploadFile, etc.) | `SharePoint Application Scope` |
+
+---
+
+### Scope Activities Require ActivityAction Body (CRITICAL for XAML Generation)
+
+Scope activities (Excel Application Scope, ExcelProcessScopeX, ExcelApplicationCard, Word Application Scope, etc.) do **NOT** accept direct children. They require an `ActivityAction<T>` body wrapper with a `DelegateInArgument`. `RetryScope` follows the same wrap-the-body rule but uses a bare `ActivityAction` (no `x:TypeArguments`, no `DelegateInArgument`) — see the per-activity table below. Placing activities directly inside the scope element will fail validation.
+
+**Wrong — direct children (fails validation):**
+```xml
+<ueab:ExcelApplicationCard WorkbookPath="file.xlsx">
+  <ueab:ReadRangeX ... />  <!-- WRONG -->
+</ueab:ExcelApplicationCard>
+```
+
+**Correct — ActivityAction body wrapper:**
+```xml
+<ueab:ExcelApplicationCard WorkbookPath="file.xlsx" DisplayName="Use Excel File">
+  <ueab:ExcelApplicationCard.Body>
+    <ActivityAction x:TypeArguments="ue:IWorkbookQuickHandle">
+      <ActivityAction.Argument>
+        <DelegateInArgument x:TypeArguments="ue:IWorkbookQuickHandle" Name="Excel" />
+      </ActivityAction.Argument>
+      <Sequence DisplayName="Do">
+        <!-- Child activities go here, using Excel handle -->
+        <ueab:ReadRangeX Range="[Excel.Sheet(&quot;Sheet1&quot;).Range(&quot;A1:A20&quot;)]" />
+      </Sequence>
+    </ActivityAction>
+  </ueab:ExcelApplicationCard.Body>
+</ueab:ExcelApplicationCard>
+```
+
+#### Common Scope Body Patterns
+
+| Activity | Body TypeArgument | DelegateInArgument Name | Notes |
+|----------|-------------------|------------------------|-------|
+| `ExcelProcessScopeX` | `ui:IExcelProcess` | `ExcelProcessScopeTag` | Outer Excel scope |
+| `ExcelApplicationCard` | `ue:IWorkbookQuickHandle` | `Excel` | Inner Excel scope (inside ExcelProcessScopeX) |
+| `ExcelApplicationScope` | `ue:WorkbookApplication` | `ExcelWorkbookScope` | Classic Interop scope |
+| `ForEachRow` | `ActivityAction(sd:DataRow)` | `row` | Iterates DataTable rows |
+| `WordApplicationScope` | (Word handle type) | `WordApplicationScope` | Word COM scope |
+| `PowerPointApplicationScope` | (PowerPoint handle type) | `PowerPointApplication` | PowerPoint COM scope |
+| `TryCatch` | (special — `Catches` collection) | — | Not ActivityAction, but has nested body structure |
+| `Parallel` | (multiple `Branches`) | — | Each branch is a separate Sequence |
+| `RetryScope` | _(none — bare `<ActivityAction>`)_ | — | Body property is `.ActivityBody` (not `.Body`); `ActivityAction` takes no type argument or `DelegateInArgument` |
+
+**`find-activities` now returns `Body` info** when an activity requires an `ActivityAction<T>` body — check the output before writing XAML for scope activities.
+
+**Key xmlns required:**
+- `xmlns:ue="clr-namespace:UiPath.Excel;assembly=UiPath.Excel.Activities"`
+- `xmlns:ueab="clr-namespace:UiPath.Excel.Activities.Business;assembly=UiPath.Excel.Activities"`
+- `xmlns:ui="http://schemas.uipath.com/workflow/activities"`
+- `xmlns:sd="clr-namespace:System.Data;assembly=System.Data"` (for ForEachRow DataRow type)
+
+**Nested scopes:** Modern Excel requires TWO levels: `ExcelProcessScopeX` → `ExcelApplicationCard` → activities. Each level has its own `ActivityAction` body.
+
+**Always check `find-activities` output** for body pattern info before using scope activities.
+
+---
+
+### Dangerous Defaults (Source Code Verified)
+
+#### ContinueOnError Defaults to TRUE
+These activities **silently swallow all errors** by default:
+
+| Activity | Package | Impact |
+|----------|---------|--------|
+| `NetHttpRequest` / `HttpClient` (HTTP Request) | Web | HTTP 500/timeout → empty response, no error |
+| `Data Scraping` wizard output | UIAutomation | Extraction failure → empty DataTable |
+
+**Always** set `ContinueOnError=False` on HTTP Request activities.
+
+#### ContinueOnError in Library Workflows
+**NEVER** use `ContinueOnError=True` in Library workflows. Library consumers cannot know which errors are silently swallowed. Always let exceptions propagate from libraries — the consuming process decides how to handle them.
+
+#### Excel AutoSave Causes Performance Disasters
+`AutoSave=true` (default) on `ExcelApplicationScope` means every Write Cell triggers a disk write. In loops with 1000 operations, that's 1000 saves.
+
+**Fix:** Set `AutoSave=false`, add a single `Save Workbook` at the end.
+
+#### OpenBrowser Defaults to Internet Explorer
+`BrowserType` defaults to `IE` in source code. **Always explicitly set** BrowserType to Chrome, Firefox, or Edge.
+
+#### HTTP Request Very Short Timeout
+Legacy `HttpClient` (also called `NetHttpRequest` internally) timeout is only 6,000-10,000ms. Both are often too low for production APIs.
+
+**Fix:** Set `TimeoutMS` to 30,000-60,000ms.
+
+---
+
+### VB.NET Quote Escaping in Throw.Exception (CRITICAL for XAML Generation)
+
+The `Throw.Exception` attribute wraps the bracket expression in `VisualBasicValue<Exception>`. When fully-qualified class names are combined with complex string expressions containing multiple `&quot;`, the VB.NET compiler can reject the expression — even though the same `&quot;` escaping works fine in simpler attributes like `LogMessage.Message`.
+
+#### What fails
+
+```xml
+<!-- FAILS: Fully-qualified name + complex string concatenation -->
+<Throw Exception="[New UiPath.Core.Activities.BusinessRuleException(&quot;Invalid amount: &quot; &amp; amount.ToString(&quot;F2&quot;) &amp; &quot; for &quot; &amp; txId)]" />
+
+<!-- FAILS: String.Format with multiple &quot; inside brackets -->
+<Throw Exception="[New UiPath.Core.Activities.BusinessRuleException(String.Format(&quot;Invalid amount: {0} for {1}&quot;, amount, txId))]" />
+```
+
+#### What works
+
+**Approach 1: Short-form class name + simple expression (recommended for simple messages)**
+```xml
+<!-- Works: Short name (namespace already imported) + simple concatenation -->
+<Throw Exception="[New BusinessRuleException(&quot;Invalid amount for &quot; &amp; txId)]" />
+```
+
+**Approach 2: Variable for message, then Throw (recommended for complex messages)**
+```xml
+<!-- Best practice from codebase: construct message in a variable, then throw -->
+<Assign DisplayName="Build Error Message">
+  <Assign.To>
+    <OutArgument x:TypeArguments="x:String">[errorMessage]</OutArgument>
+  </Assign.To>
+  <Assign.Value>
+    <InArgument x:TypeArguments="x:String">["Invalid amount: " &amp; amount.ToString("F2") &amp; " for transaction " &amp; txId]</InArgument>
+  </Assign.Value>
+</Assign>
+<Throw Exception="[New BusinessRuleException(errorMessage)]" />
+```
+
+#### Rules
+
+1. **Always use short-form class names** in `Throw.Exception` — `BusinessRuleException` not `UiPath.Core.Activities.BusinessRuleException`. Ensure `UiPath.Core.Activities` is in the namespace imports.
+2. **For complex messages, use the variable approach** — Assign the message string to a variable first, then pass the variable to the exception constructor.
+3. **For simple messages, inline is fine** — `[New BusinessRuleException(&quot;simple message&quot;)]` works.
+4. **Same rules apply to all exception types** — `Exception`, `BusinessRuleException`, `ArgumentException`, etc.
+
+#### Why this happens
+
+`Throw.Exception` compiles the bracket expression via `VisualBasicValue<Exception>`. The combination of a long fully-qualified type path + embedded `&quot;` string literals with concatenation operators creates ambiguity for the VB.NET expression compiler. Shorter expressions or variable references avoid this.
+
+---
+
+### Top Gotchas by Package
+
+#### Excel
+- **Zombie EXCEL.EXE processes** after workflow crashes — use Kill Process in Finally block
+- **Dates read as serial numbers** — set `PreserveFormat=true` or convert with `DateTime.FromOADate()`
+- **Empty DataTable from Read Range** — verify sheet name, use `""` for entire used range
+- **Write Range strips formatting** — use Write Cell in loops for small updates
+
+#### UIAutomation
+- **TypeInto missing/wrong characters** — escape `{`, `}`, `[`, `]`, `+`, `^`, `%`, `~` with `{{}`, `{+}` etc.
+- **EmptyField ignored with SimulateType** — only works with hardware events or SendWindowMessages
+- **Selectors work in Studio, fail on Robot** — use SimulateClick/SimulateType, avoid `idx` attribute
+- **Dynamic selectors break** — use wildcards `*` for dynamic parts, prefer `AutomationId`
+
+#### Mail
+- **SMTP auth fails with Gmail/M365** — use App Passwords or OAuth2, not "Less Secure Apps"
+- **SSL/TLS port mismatch** — Port 587 = STARTTLS, Port 465 = implicit SSL, Port 25 = unencrypted
+- **Multiple recipients** — use semicolons `;` not commas
+
+#### Web
+- **HTTP Request ContinueOnError=TRUE by default** — errors silently swallowed
+- **Legacy HttpClient 6-second timeout** — increase to 30-60 seconds
+
+#### PDF
+- **ReadPDFText returns empty** — PDF is scanned images, use Read PDF With OCR instead
+- **Text out of order** — set `PreserveFormatting=true`
+
+#### GenericValue
+- **String comparison instead of numeric** — `"10" > "9"` returns False. Use `CInt()` explicitly.
+- **Boolean conversion trap** — ANY non-null, non-empty string converts to `True`
+- **Null converts to 0** — `GenericValue(null)` → int returns `0`, → DateTime returns `DateTime.MinValue`
+
+**Recommendation:** Avoid GenericValue entirely. Use strongly-typed variables.
+
+---
+
+### VB.NET Quick Reference
+
+Complete VB.NET cheat sheet — string/type/DateTime/collection/DataTable operations, file paths, Orchestrator patterns: [activity-docs/_PATTERNS.md](./activity-docs/_PATTERNS.md).
+
+---
+
+### Common XAML Generation Mistakes
+
+These are patterns the agent is likely to produce incorrectly. Check for them after generating XAML.
+
+#### Hallucination-Prone Activity Names
+
+| Wrong (invented) | Correct | Package |
+|---|---|---|
+| `ReadExcel`, `WriteExcel` | `ExcelReadRange`, `ExcelWriteRange` | Excel |
+| `SendEmail` | `SendSmtpMailMessage`, `SendOutlookMailMessage` | Mail |
+| `OpenBrowserActivity` | `OpenBrowser` | UIAutomation |
+| `ReadPdf` | `ReadPDFText`, `ReadPDFWithOCR` | PDF |
+| `HttpRequest` | `HttpClient` (also known as `NetHttpRequest`) | Web |
+
+**Rule:** NEVER guess activity names. Run `find-activities` to get the exact class name.
+
+#### Nesting Errors
+
+| Mistake | Fix |
+|---|---|
+| Multiple children directly inside `If.Then` or `If.Else` | Wrap in a single `Sequence` |
+| Activities directly inside `ForEach` body | Use `ActivityAction` wrapper (see Scope Activities section above) |
+| Activities directly inside scope activities (Excel, Word, etc.) | Use `ActivityAction<T>` body pattern |
+| ViewState referencing nodes that don't exist in the workflow | Remove orphaned ViewState entries, or add the missing nodes |
+
+#### Expression Language Mismatches
+
+| Mistake | Symptom | Fix |
+|---|---|---|
+| C# operators (`!=`, `&&`, `\|\|`) in VB.NET project | Compilation error | Use `<>`, `AndAlso`, `OrElse` |
+| C# string interpolation `$"..."` in VB.NET project | Compilation error | Use `String.Format` or `&` concatenation |
+| VB.NET `[bracket]` expressions in C# project | Compilation error | Use `<mca:CSharpValue>` or `<mca:CSharpReference>` |
+
+#### Security Anti-Patterns
+
+| Anti-Pattern | Risk | Fix |
+|---|---|---|
+| Password stored in `String` variable | Visible in logs and memory dumps | Use `SecureString` type |
+| Hardcoded API keys or JWT tokens in XAML | Credentials in source control | Use Orchestrator Credential assets |
+| Hardcoded URLs in activity properties | Breaks across environments | Use Config.xlsx Settings or Orchestrator Text assets |
+| Empty Catch blocks (`Catch ex As Exception` with no body) | Silent failures, impossible to debug | At minimum, add `Log Message` with `ex.Message` |
+| Timeout values as magic numbers (`30000`) | Unclear intent, hard to tune | Use Config.xlsx Constants with descriptive names |
+
+---
+
+### Deprecated Activity → Replacement
+
+Full mapping table: [activity-docs/_PATTERNS.md § Deprecated Activities](./activity-docs/_PATTERNS.md).

package/skills/uipath-rpa/references/library-authoring-guide.md

@@ -23,7 +23,7 @@ Boundaries:
 |------|-------|
 | Start new projects from a standard baseline | Project templates — [environment-setup.md § Template Selection](environment-setup.md) |
 | Share UI selectors across projects | UI Libraries — [uia-starter-guide.md § Object Repository as a Published UI Library](uia-starter-guide.md) |
-| Reuse logic inside one project | Separate workflow file — [project-structure-guide.md § Designing for Reuse](project-structure-guide.md) |
+| Reuse logic inside one project | Separate workflow file — [environment-setup.md § Designing for Reuse](environment-setup.md#designing-for-reuse) |
 
 ## Creating and Structuring
 
@@ -131,7 +131,7 @@ Rules:
 Each public workflow is an API surface. Apply every rule:
 
 1. **Name workflows verb-noun PascalCase, no spaces** — `SendNotificationEmail.xaml`, `DownloadInvoices.xaml`. The file name becomes the activity name in the consumer's panel.
-2. **Public arguments: PascalCase, NO `in_`/`out_`/`io_` prefixes** — `InvoiceId`, `RecipientEmail`, `NotificationResult`. Argument names become activity property names; prefixes become noise on the property grid. This inverts the process-workflow convention: workflows invoked via Invoke Workflow File keep directional prefixes ([project-structure-guide.md § Designing for Reuse](project-structure-guide.md)); library public workflows drop them.
+2. **Public arguments: PascalCase, NO `in_`/`out_`/`io_` prefixes** — `InvoiceId`, `RecipientEmail`, `NotificationResult`. Argument names become activity property names; prefixes become noise on the property grid. This inverts the process-workflow convention: workflows invoked via Invoke Workflow File keep directional prefixes ([environment-setup.md § Designing for Reuse](environment-setup.md#designing-for-reuse)); library public workflows drop them.
 3. **Describe every public argument** via its `sap2010:Annotation.AnnotationText` — descriptions ship as property tooltips. For display names, placeholders, widgets, and grouping, add the layout sidecar ([§ Activity Layout](#activity-layout--the-sidecar-file)).
 4. **Expect — and keep — the analyzer naming warnings.** `build`/`pack` emit `Argument <Name> does not respect the set pattern ^in_...` for prefix-free library arguments. The warning is non-blocking. Do NOT rename arguments to silence it.
 5. **Return application handles.** A workflow that opens or attaches to an app outputs the window/browser object; downstream public workflows accept it as an input argument instead of reopening.
@@ -166,7 +166,8 @@ uip rpa pack "<PROJECT_DIR>" "<OUTPUT_DIR>" --output json
 uip or libraries upload --file "<OUTPUT_DIR>/<LIBRARY_NAME>.<VERSION>.nupkg" --output json
 ```
 
-- Libraries upload to the tenant-scoped **libraries feed** — not the per-folder processes feed that [publishing-guide.md](publishing-guide.md) covers with `uip or packages upload`. There is no `uip rpa publish`.
+- Libraries upload to the tenant-scoped **libraries feed** — not the per-folder processes feed that [cli-reference.md § Pack & Publish to Orchestrator](cli-reference.md#pack--publish-to-orchestrator) covers with `uip or packages upload`. There is no `uip rpa publish`.
+- `<OUTPUT_DIR>` must be OUTSIDE the project directory tree — `pack` refuses an output path inside the project. Use a sibling directory (e.g. `dist/`).
 - `--feed-id <FEED_ID>` targets a non-default feed.
 - Verify the publish:
 

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

@@ -17,19 +17,7 @@ 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).
+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. Commands, ordering constraints (`connect` before `set-default-project`, server switches clearing the default project), and `reloadHint` handling: [cli-reference.md § Test Manager](cli-reference.md#test-manager). 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).
 
 ---
 
@@ -111,21 +99,7 @@ If the workflow has arguments, pass them in the `InvokeWorkflowFile.Arguments` d
 
 Register every XAML test case in `designOptions.fileInfoCollection` — this is **Common Rule 10** in SKILL.md and applies to both XAML and coded test cases. Test cases live **only** in `fileInfoCollection`, never in `entryPoints` — `entryPoints` is for executable workflow files in Process projects (e.g. `Main.xaml`), and test cases are not workflow entry points regardless of project type.
 
-```json
-{
-  "designOptions": {
-    "fileInfoCollection": [
-      {
-        "editingStatus": "InProgress",
-        "testCaseId": "<UNIQUE_GUID>",
-        "testCaseType": "TestCase",
-        "executionTemplateInvokeIsolated": false,
-        "fileName": "TestCase.xaml"
-      }
-    ]
-  }
-}
-```
+Copy-paste JSON snippet (including `publishAsTestCase` for coded test cases and `dataVariationFilePath` for data-driven): [../assets/json-template.md](../assets/json-template.md).
 
 **Required keys per entry:**
 

package/skills/uipath-rpa/references/trigger-pattern-guide.md

@@ -205,7 +205,7 @@ Applies to all integration triggers, and to local triggers placed at root.
 
 1. **Author** — place trigger as the first activity of root `Sequence`, bind output to variable, write handler. Per-file `validate` clean.
 2. **Build** — `uip rpa build "<PROJECT_DIR>" --output json` clean.
-3. **Publish** — `.nupkg` to Orchestrator (see [publishing-guide.md](publishing-guide.md)). On publish, Orchestrator detects the trigger from the workflow's activity registration and exposes it as a Process/Time/Queue Trigger candidate.
+3. **Publish** — `.nupkg` to Orchestrator (see [cli-reference.md § Pack & Publish to Orchestrator](cli-reference.md#pack--publish-to-orchestrator)). On publish, Orchestrator detects the trigger from the workflow's activity registration and exposes it as a Process/Time/Queue Trigger candidate.
 
 **`uip rpa run` is NOT a meaningful smoke test for entry-point triggers.** The CLI executes the workflow once in-process, which does not exercise Orchestrator subscription or the connector's webhook/polling lifecycle. A clean `run` only proves the handler XAML compiles and the trigger activity can be instantiated.
 

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

@@ -6,6 +6,142 @@ How to generate ViewState for Flowchart, State Machine, and Long Running Workflo
 - **Sequences**: ViewState is optional — Studio auto-stacks children vertically. Only `IsExpanded=True` matters.
 - **Flowcharts, State Machines, ProcessDiagrams**: ViewState is **mandatory** for usable layout. Without it, Studio stacks all nodes at (0,0).
 
+## Flowchart Structure & Wiring
+
+### When to Use a Flowchart
+
+Branching logic with multiple decision points, loops, and back-edges. Best when the flow is a graph rather than a straight sequence. For straight-line steps use a `Sequence`; for state-driven processes use a State Machine; for BPMN-style event-driven long waits use a Long Running Workflow (ProcessDiagram).
+
+### Node Vocabulary
+
+| Node | Purpose | Successor wiring |
+|------|---------|------------------|
+| `FlowStep` | Wraps **exactly one** activity (which may be a container). The unit of work. | `FlowStep.Next` → one node |
+| `FlowDecision` | Boolean branch. `Condition` plus `True`/`False` targets. | `FlowDecision.True` / `.False` → one node each |
+| `FlowSwitch<T>` | Multi-way branch keyed by an expression. | `Default` plus one target per case |
+
+A `FlowStep` wraps one activity. If that activity is a container (`Sequence`, `NApplicationCard`, `TryCatch`), its children stay nested and are NOT separate nodes. See [§ What Counts as a Node](#what-counts-as-a-node).
+
+### Wiring
+
+**Rule:** every `FlowStep`/`FlowDecision`/`FlowSwitch` is a **direct child of `<Flowchart>`** with an `x:Name`. Links between nodes are made with `<x:Reference>__ReferenceIDn</x:Reference>` inside property elements — never by physically nesting one node inside another.
+
+```xml
+<Flowchart DisplayName="My Flowchart" sap2010:WorkflowViewState.IdRef="Flowchart_1">
+  <Flowchart.StartNode>
+    <x:Reference>__ReferenceID0</x:Reference>
+  </Flowchart.StartNode>
+  <FlowStep x:Name="__ReferenceID0">
+    <ui:LogMessage DisplayName="Step 1" />
+    <FlowStep.Next>
+      <x:Reference>__ReferenceID1</x:Reference>
+    </FlowStep.Next>
+  </FlowStep>
+  <FlowDecision x:Name="__ReferenceID1">
+    <FlowDecision.Condition>
+      <CSharpValue x:TypeArguments="x:Boolean">condition</CSharpValue>
+    </FlowDecision.Condition>
+    <FlowDecision.True>
+      <x:Reference>__ReferenceID0</x:Reference>
+    </FlowDecision.True>
+    <!-- FlowDecision.False omitted = end of flow -->
+  </FlowDecision>
+</Flowchart>
+```
+
+### Where `<x:Reference>` Goes
+
+`<x:Reference>` is used ONLY inside property elements to create cross-references between nodes:
+
+| Property Element | Container | Purpose |
+|-----------------|-----------|---------|
+| `Flowchart.StartNode` | Flowchart | Points to the first node |
+| `FlowStep.Next` | Flowchart | Links to the next node |
+| `FlowDecision.True` / `.False` | Flowchart | Branch targets |
+| `Transition.To` | State Machine | Transition destination state |
+| `StateMachine.InitialState` | State Machine | Starting state (attribute form: `{x:Reference ...}`) |
+| `ProcessDiagram.StartNode` | ProcessDiagram | Points to start event |
+| `EventNode.Next` / `TaskNode.Next` | ProcessDiagram | Links to next node |
+| `DecisionNode.True` / `.False` | ProcessDiagram | Branch targets |
+
+### Node Registration
+
+Only nodes in the `Flowchart.Nodes` collection render — and that collection is built from the **direct children** of `<Flowchart>`. A node that is not a direct child is never registered, so the designer does not draw it, regardless of ViewState. The same registration rules apply to `<StateMachine>` (States) and `<upa:ProcessDiagram>` and its node types (`EventNode`, `TaskNode`, `DecisionNode`, `SwitchNode<T>`, `SplitNode`, `MergeNode`, `SubProcessNode`, `EndNode`, `BoundaryNode`).
+
+Two cases:
+
+1. **Direct children** of the container — already registered. Do NOT also add a trailing `<x:Reference>`.
+2. **Inline definitions** inside a property element (e.g., a `FlowStep` written inside `<FlowDecision.True>`) — MUST add a trailing `<x:Reference>` entry as a direct child of the container to register them.
+
+**Correct — inline node registered with trailing `<x:Reference>`:**
+```xml
+<Flowchart>
+  <Flowchart.StartNode>
+    <x:Reference>__ReferenceID0</x:Reference>
+  </Flowchart.StartNode>
+  <FlowDecision x:Name="__ReferenceID0">        <!-- direct child — no trailing ref -->
+    <FlowDecision.True>
+      <FlowStep x:Name="__ReferenceID1">         <!-- inline definition -->
+        ...
+      </FlowStep>
+    </FlowDecision.True>
+  </FlowDecision>
+  <x:Reference>__ReferenceID1</x:Reference>      <!-- register inline node -->
+</Flowchart>
+```
+
+**Wrong — re-listing a direct child:**
+```xml
+<Flowchart>
+  <FlowStep x:Name="__ReferenceID0">             <!-- direct child -->
+    ...
+  </FlowStep>
+  <x:Reference>__ReferenceID0</x:Reference>      <!-- WRONG — already a direct child -->
+</Flowchart>
+```
+
+#### Forbidden — nested FlowStep chains
+
+Do NOT build the flow by physically nesting each `FlowStep` inside the previous one's `<FlowStep.Next>` (a deep chain with 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 successors by reference (as in [§ Wiring](#wiring)) and keep every step a direct child.
+
+**Wrong** — Step 2 nested inside Step 1's `.Next`; `Flowchart.Nodes` holds only Step 1, so Step 2 never renders:
+```xml
+<Flowchart sap2010:WorkflowViewState.IdRef="Flowchart_1">
+  <Flowchart.StartNode>
+    <x:Reference>__ReferenceID0</x:Reference>
+  </Flowchart.StartNode>
+  <FlowStep x:Name="__ReferenceID0">
+    <ui:LogMessage DisplayName="Step 1" />
+    <FlowStep.Next>
+      <FlowStep>                              <!-- WRONG — nested, not registered -->
+        <ui:LogMessage DisplayName="Step 2" />
+      </FlowStep>
+    </FlowStep.Next>
+  </FlowStep>
+</Flowchart>
+```
+
+#### `__ReferenceID` Gotchas
+
+- `__ReferenceID` values must be unique within the entire XAML file — duplicate IDs cause deserialization errors. When adding nodes manually, use a number higher than any existing one (Studio auto-renumbers on copy-paste; manual XAML editing doesn't).
+- When copying from flowchart to sequence, elements may be ordered backwards due to node ordering in XAML.
+- `x:Reference` can only refer to elements with `x:Name` in the same XAML file — cross-file references are not supported.
+
+### 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.
+
+### Condition Expressions
+
+`FlowDecision.Condition` and `FlowSwitch` expressions follow the project's expression language:
+
+- **C# projects:** `<CSharpValue x:TypeArguments="x:Boolean">condition</CSharpValue>`
+- **VB projects:** `<mva:VisualBasicValue x:TypeArguments="x:Boolean" ExpressionText="condition" />`
+
+Structure first, then coordinates: ViewState positions a node **only after** it is registered — see [§ 3. Flowchart Layout](#3-flowchart-layout) below and SKILL.md Rule 20.
+
+---
+
 ---
 
 ## 1. Required XAML Namespaces
@@ -68,7 +204,7 @@ 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.
+Node vocabulary, structure & wiring, and node registration: [§ Flowchart Structure & Wiring](#flowchart-structure--wiring) above. This section covers layout coordinates and ViewState only.
 
 ### What Counts as a Node
 
@@ -79,11 +215,6 @@ One node per top-level step → separate boxes. One step's children nested → s
 ### 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)
@@ -276,33 +407,9 @@ FlowDecision:  (270, 220)     60x60
   True branch:  (100, 330)    200x60     (left)
   False branch: (400, 330)    200x60     (right)
 ```
-
 ### Node Registration
 
-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.
+See [§ Node Registration](#node-registration) at the top of this file — structure and registration come before coordinates.
 
 ---
 
@@ -422,7 +529,7 @@ End State:          (164, 385)      229x110 (IsFinal=True)
 
 ### Node Registration
 
-States defined inline inside `Transition.To` need `<x:Reference>` registration as direct children of `<StateMachine>`, same as Flowchart pattern.
+States defined inline inside `Transition.To` need `<x:Reference>` registration as direct children of `<StateMachine>`. See [§ Node Registration](#node-registration).
 
 ---
 
@@ -644,7 +751,7 @@ EventNode (start)  →  TaskNode 1  →  DecisionNode  →  TaskNode 2  →  End
 
 ### Node Registration
 
-Same rules as Flowchart — nodes defined inline within property elements (e.g., `TaskNode` inside `EventNode.Next`) need trailing `<x:Reference>` entries as direct children of `<upa:ProcessDiagram>`. See [common-pitfalls.md § x:Reference](common-pitfalls.md#xreference--__referenceid-naming) for the full rules.
+Same rules as Flowchart — inline nodes need trailing `<x:Reference>` entries as direct children of `<upa:ProcessDiagram>`. See [§ Node Registration](#node-registration).
 
 ---