@uipath/skills 1.195.0

package/skills/uipath-rpa/references/legacy/cli-reference.md

@@ -0,0 +1,363 @@
+# CLI Tool Reference
+
+Complete reference for all `uip rpa-legacy` CLI commands and error recovery patterns.
+
+**The CLI is fully self-documenting.** Append `--help` at any level to discover commands, subcommands, and parameters:
+```bash
+uip rpa-legacy --help                      # all rpa-legacy subcommands
+uip rpa-legacy find-activities --help      # parameters for a specific command
+uip rpa-legacy validate --help             # parameters for validate
+```
+
+**Key difference from `uip rpa`:** The `rpa-legacy` CLI is standalone — it does **not** require Studio Desktop IPC. It uses UiRobot directly for execution and resolves project dependencies independently.
+
+---
+
+## Path and Output Rules
+
+- **Always use absolute paths** — store `{projectRoot}` at Phase 0, pass it to every command. **Never use `cd`.**
+- **Always use `--output json`** for programmatic parsing (global option on all `uip` subcommands).
+- **NEVER suppress stderr** (`2>/dev/null`) — error details are in the JSON output on stderr when exit code is non-zero.
+- Check the `Result` field in output: `"Success"` or `"Failure"`.
+- On failure, read `Message` and `Instructions` for diagnostics.
+
+```
+WRONG:  cd "C:/Projects/MyProject" && uip rpa-legacy validate . --output json
+RIGHT:  uip rpa-legacy validate "C:/Projects/MyProject" --output json
+RIGHT:  uip rpa-legacy validate "C:/Projects/MyProject/Main.xaml" --output json
+```
+
+---
+
+## File Operations (Built-in Tools)
+
+| Action | How | Key Parameters |
+|--------|-----|----------------|
+| **Explore project files** | `Glob` with `**/*.xaml` pattern | Project root directory |
+| **Find files by pattern** | `Glob` with pattern (e.g., `**/*Mail*.xaml`) | Glob pattern, path |
+| **Search XAML content** | `Grep` with regex pattern across `.xaml` files | Pattern, file/directory path |
+| **Read file contents** | `Read` tool | File path, offset, limit |
+| **Read project definition** | `Read` tool on `{projectRoot}/project.json` | File path |
+| **Create new workflow file** | `Write` tool — create a new `.xaml` file | File path, XAML content |
+| **Edit existing workflow** | `Edit` tool — exact string replacement in `.xaml` files | File path, old_string, new_string |
+
+---
+
+## Activity Discovery Tools
+
+| Action | How | Key Parameters |
+|--------|-----|----------------|
+| **Search for activities** | `Bash`: `uip rpa-legacy find-activities <project-path> --query "..." --output json` | `<project-path>` (required), `--query`, `--tags`, `--limit` (default 50) |
+| **Search with type info** | `Bash`: `uip rpa-legacy find-activities <project-path> --query "..." --include-type-definitions --output json` | Adds full type definitions for argument types |
+| **Inspect a .NET type** | `Bash`: `uip rpa-legacy type-definition <project-path> --type "FullyQualifiedTypeName" --output json` | `<project-path>` (required), `--type` (full or simple name) |
+| **Search NuGet for packages** | `Bash`: `uip rpa-legacy find-package --query "..." --output json` | `--query` (required), `--limit` (default: 50) |
+
+### find-activities
+
+Searches for available activities in the project's installed NuGet dependencies. Returns activity names, arguments (in/out with types), **ready-to-use XAML snippet**, **xmlns declaration**, and optionally full type definitions.
+
+**Always use the returned `XamlSnippet` as your starting point** for activity XAML instead of constructing from scratch. The snippet has correct element names, namespaces, and property names for the installed package version.
+
+```bash
+# Multi-word search (ranked by relevance)
+uip rpa-legacy find-activities "C:/Projects/MyLegacyProject" --query "Excel Read Range" --output json
+
+# Exact match when you know the name
+uip rpa-legacy find-activities "C:/Projects/MyLegacyProject" --query "ReadRange" --exact --output json
+
+# Find with type definitions (enums, classes)
+uip rpa-legacy find-activities "C:/Projects/MyLegacyProject" --query "invoke code" --include-type-definitions --output json
+```
+
+**Output per activity:**
+```json
+{
+  "DisplayName": "SendMail",
+  "ClassName": "SendMail",
+  "Namespace": "UiPath.Mail.SMTP.Activities",
+  "TypeFullName": "UiPath.Mail.SMTP.Activities.SendMail",
+  "Arguments": [
+    { "Name": "To", "Direction": "In", "Type": "String" },
+    { "Name": "Result", "Direction": "Out", "Type": "String" }
+  ],
+  "XmlnsPrefix": "umsa",
+  "XmlnsDeclaration": "xmlns:umsa=\"clr-namespace:UiPath.Mail.SMTP.Activities;assembly=UiPath.Mail.Activities\"",
+  "XamlSnippet": "<umsa:SendMail\n    To=\"[toValue]\"\n    Result=\"[result]\" />"
+}
+```
+
+With `--include-type-definitions`, output includes `TypeDefinitions` array with enum values, class properties, etc.
+
+| Parameter | Description |
+|-----------|-------------|
+| `<project-path>` | Path to project.json or folder containing it (required, positional) |
+| `--query <search>` | Filter activities by name, description, or category |
+| `--tags <tags>` | Comma-separated category tags to filter by |
+| `-l, --limit <count>` | Maximum results to return (default: 50) |
+| `--include-type-definitions` | Include full type definitions for argument types (enums, classes, interfaces) |
+| `--exact` | Only return activities whose ClassName or DisplayName exactly matches the query (case-insensitive) |
+
+**Query tips:**
+- **Multi-word queries work** with relevance scoring: `"Excel Read Range"` splits into words, scores matches independently, with bonuses when all words match
+- **CamelCase boundaries detected**: `"SendHotkey"`, `"ExcelReadRange"` match correctly
+- **Use `--exact`** when you know the exact activity name — avoids irrelevant results (e.g., `--query "If" --exact` returns only the WF4 If activity, not 17 unrelated matches)
+
+### type-definition
+
+Inspects any .NET type from the project's NuGet dependencies — enum values, properties, methods, constructors, and base types.
+
+```bash
+# Inspect an enum type
+uip rpa-legacy type-definition "C:/Projects/MyLegacyProject" --type "UiPath.Mail.Activities.MailFolder" --output json
+
+# Inspect a class
+uip rpa-legacy type-definition "C:/Projects/MyLegacyProject" --type "System.Net.Mail.MailMessage" --output json
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `<project-path>` | Path to project.json or folder containing it (required, positional) |
+| `--type <name>` | Full or simple name of the type to inspect |
+| `--timeout <seconds>` | Timeout in seconds |
+
+### find-package
+
+Searches all configured NuGet feeds for packages by name or description. Use when known packages don't cover a capability.
+
+```bash
+uip rpa-legacy find-package --query "UiPath.Excel" --limit 10 --output json
+uip rpa-legacy find-package --query "barcode" --output json
+```
+
+**Output per package:**
+```json
+{
+  "Id": "UiPath.Excel.Activities",
+  "Version": "2.24.4",
+  "Description": "Excel automation activities",
+  "Authors": "UiPath",
+  "Source": "Official"
+}
+```
+
+Activity packages (tagged `UiPathActivities`) are returned first. Searches all enabled v3 feeds in parallel.
+
+| Parameter | Description |
+|-----------|-------------|
+| `--query <search>` | Search term to match against package name and description (required) |
+| `-l, --limit <count>` | Maximum results (default: 50) |
+
+After finding a package, add it to `dependencies` in project.json. Then `find-activities` will index its activities.
+
+---
+
+## Validation Tools
+
+| Action | How | Key Parameters |
+|--------|-----|----------------|
+| **Validate file** | `Bash`: `uip rpa-legacy validate <xaml-path> --output json` | Single file validation |
+| **Validate project** | `Bash`: `uip rpa-legacy validate <project-path> --output json` | Whole-project validation |
+
+### validate
+
+Checks a XAML workflow file or entire project for compilation errors — missing arguments, broken references, type mismatches.
+
+Accepts: XAML file path, project.json path, or project folder path.
+
+```bash
+# Validate a specific file (use during iteration — one activity at a time)
+uip rpa-legacy validate "C:/Projects/MyLegacyProject/Main.xaml" --output json
+
+# Validate entire project (use before completing — final check)
+uip rpa-legacy validate "C:/Projects/MyLegacyProject" --output json
+
+# Save results to file
+uip rpa-legacy validate "C:/Projects/MyLegacyProject" --result-path "C:/output/errors.json"
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `<path>` | XAML file, project.json, or project folder (required, positional) |
+| `--result-path <path>` | Write validation results to a JSON file instead of stdout |
+
+**Workflow:** Use per-file validation during development (faster, focused). Use project-level validation as a final step before completing the task.
+
+---
+
+## Package & Debug Tools
+
+| Action | How | Key Parameters |
+|--------|-----|----------------|
+| **Package project (optional)** | `Bash`: `uip rpa-legacy pack <project-path> -o <output-dir>` | `<project-path>` (required), `-o` output dir |
+| **Debug workflow** | `Bash`: `uip rpa-legacy debug <xaml-path>` | `<xaml-path>` (required), `-i` input args |
+
+### pack
+
+Packages an RPA project into a deployable `.nupkg` file. **Optional** — not required for debugging (legacy RPA can be debugged directly).
+
+```bash
+# Basic pack
+uip rpa-legacy pack "C:/Projects/MyLegacyProject" -o "C:/output"
+
+# Pack with version
+uip rpa-legacy pack "C:/Projects/MyLegacyProject" -o "C:/output" --version "1.2.0"
+
+# Auto-version
+uip rpa-legacy pack "C:/Projects/MyLegacyProject" -o "C:/output" --auto-version
+
+# With release notes
+uip rpa-legacy pack "C:/Projects/MyLegacyProject" -o "C:/output" --version "1.2.0" --release-notes "Bug fixes and improvements"
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `<project-path>` | Path to the RPA project or project.json (required, positional) |
+| `-o, --output <path>` | Output directory for the generated .nupkg |
+| `-v, --version <version>` | Package version |
+| `--auto-version` | Auto-generate package version |
+| `--output-type <type>` | Force output type (Process\|Library\|Tests\|Objects) |
+| `--split-output` | Split output into runtime and design libraries |
+| `--repository-url <url>` | Source repository URL |
+| `--repository-commit <sha>` | Source repository commit SHA |
+| `--repository-branch <branch>` | Source repository branch |
+| `--repository-type <type>` | Source repository type |
+| `--project-url <url>` | Automation Hub project URL |
+| `--release-notes <text>` | Release notes for the package |
+| `--timeout <seconds>` | Timeout in seconds |
+
+### debug
+
+Executes a XAML workflow locally via UiRobot. Logs stream to console in real time. Returns structured JSON result with output arguments (success) or error diagnostics (failure).
+
+**Always validate before debugging** — don't debug a file with compilation errors.
+
+```bash
+# Basic execution
+uip rpa-legacy debug "C:/Projects/MyLegacyProject/Main.xaml"
+
+# With input arguments
+uip rpa-legacy debug "C:/Projects/MyLegacyProject/Main.xaml" -i '{"in_FilePath": "C:\\data.xlsx", "in_Count": 5}'
+
+# Programmatic: suppress streaming logs, capture result to file
+uip rpa-legacy debug "C:/Projects/MyLegacyProject/Main.xaml" \
+  -i '{"in_FilePath": "C:\\data.xlsx"}' \
+  --result-path /tmp/result.json \
+  --log-level error
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `<xaml-path>` | Full path to the XAML workflow file to execute (required, positional) |
+| `-i, --input <json>` | Input arguments as a JSON string |
+| `--result-path <path>` | Write full result JSON to file (persists after command exits) |
+| `--timeout <seconds>` | Execution timeout in seconds (0 = no timeout); kills robot process if exceeded |
+| `--robot-path <path>` | Path to UiRobot.exe (auto-detected if not provided) |
+| `--log-level <level>` | Global log level: `debug\|info\|warn\|error` (default: info) |
+
+**Exit codes:** 0 = success, 1 = failure.
+
+**Success output:**
+```json
+{
+  "Result": "Success",
+  "Code": "RpaLegacyDebug",
+  "Data": {
+    "XamlPath": "C:\\MyProject\\Main.xaml",
+    "Status": "Execution completed",
+    "Output": { "out_Result": "Done", "out_RowCount": 42 }
+  }
+}
+```
+`Output` is only present when the workflow has Out arguments with values.
+
+**Failure output:**
+```json
+{
+  "Result": "Failure",
+  "Message": "System.IO.FileFormatException: File contains corrupted data.",
+  "Data": {
+    "Error": {
+      "ExceptionType": "System.IO.FileFormatException",
+      "Message": "File contains corrupted data.",
+      "ActivityDisplayName": "Read Stock Data",
+      "ActivityType": "ReadRange",
+      "XamlFile": "Main.xaml",
+      "StackTrace": [
+        "at ReadRange \"Read Stock Data\"",
+        "at Sequence \"Initialize and Read Data\""
+      ]
+    },
+    "ErrorLog": [
+      {
+        "Timestamp": "2026-03-21T16:30:37",
+        "Level": "Error",
+        "Message": "Read Stock Data: File contains corrupted data."
+      }
+    ]
+  }
+}
+```
+
+**Reading failure diagnostics:**
+- `Error.ActivityDisplayName` + `Error.XamlFile` → locate the problem
+- `Error.ExceptionType` + `Error.Message` → understand it
+- `Error.StackTrace` → full call chain
+- `ErrorLog` → all error-level robot log entries (useful when multiple things failed)
+
+**Fix-and-retry loop:** edit XAML → validate → debug again.
+
+**Caution:** `debug` executes the workflow — it performs real actions (clicks, emails, file writes). Only use when safe to run, or with mock input data.
+
+---
+
+## Documentation Search
+
+| Action | How | Key Parameters |
+|--------|-----|----------------|
+| **Search UiPath docs** | `Bash`: `uip docsai ask "your question" --output json` | `<query>` (required) |
+
+### docsai ask
+
+Searches official UiPath documentation and returns relevant answers including best practices, guidelines, troubleshooting steps, and configuration details. Use as a fallback when bundled activity reference docs and CLI discovery tools are insufficient.
+
+```bash
+# Best practices and guidelines
+uip docsai ask "best practices for error handling in legacy UiPath workflows" --output json
+
+# Troubleshooting
+uip docsai ask "ExcelApplicationScope validation error ActivityAction body" --output json
+
+# Platform concepts
+uip docsai ask "Orchestrator queue item priority and deadline" --output json
+
+# Configuration details
+uip docsai ask "REFramework MaxRetryNumber and retry logic" --output json
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `<query>` | The question to ask (required, positional) |
+| `-t, --tenant <tenant-name>` | Tenant (optional, defaults to auth value) |
+
+**When to use:** Bundled activity docs and `find-activities`/`type-definition` don't cover the topic; you need best practices, guidelines, or troubleshooting from official UiPath documentation; you encounter an unfamiliar error.
+
+**If docsai is also insufficient**, use `WebSearch` to search the broader community: UiPath Forum (`forum.uipath.com`), Stack Overflow, GitHub public repos, Reddit (`r/UiPath`). Always verify web-sourced information against the project's actual configuration before applying.
+
+---
+
+## CLI Error Recovery
+
+When `uip rpa-legacy` commands fail, diagnose by error category:
+
+| Error Pattern | Cause | Recovery |
+|---------------|-------|----------|
+| `"project not found"`, `"project.json not found"` | Wrong project path | Verify `<project-path>` points to the folder containing `project.json` |
+| `"file not found"` | Wrong XAML path | Verify `<xaml-path>` is a full path to an existing `.xaml` file |
+| `"package not found"`, `"version not available"` | Missing NuGet dependency | Ask the user to install the package in Studio, or check the NuGet feeds |
+| `"not authenticated"`, 401, 403 | Auth required for cloud features | Run `uip login` and re-try |
+| `"UiRobot not found"` | UiRobot.exe not installed or not in PATH | Pass `--robot-path` explicitly, or ask user to install UiPath Robot |
+| `"timeout"`, `"ETIMEDOUT"` | Command took too long | Increase `--timeout` value |
+| `"compilation error"` in validate | XAML has errors | Parse the error details, fix the XAML, re-validate |
+| Any unrecognized error | Unknown | Use `--log-level debug` for debug details, inform the user |
+
+**General strategy:** Do NOT retry the same failing command in a loop. Diagnose the root cause, apply the recovery action, then retry once. If it fails again, inform the user.

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

@@ -0,0 +1,318 @@
+# 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
+
+### String Operations
+```vb
+"Hello " + variable + " World"              ' Concatenation
+String.IsNullOrEmpty(myVar)                  ' Null/empty check
+If(myVar Is Nothing, "default", myVar.ToString())  ' Null coalesce
+myString.Contains("search")                  ' Contains
+myString.Replace("old", "new")               ' Replace
+myString.Split({";"c}, StringSplitOptions.RemoveEmptyEntries)  ' Split
+```
+
+### Type Conversions
+```vb
+CInt(stringVar)                ' String to Integer
+CDbl(stringVar)                ' String to Double
+CDate(stringVar)               ' String to Date
+CType(objVar, String)          ' Object to specific type
+DirectCast(objVar, DataTable)  ' Object to DataTable
+```
+
+### DateTime
+```vb
+DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss")
+DateTime.Now.AddDays(7)
+(endDate - startDate).TotalDays
+```
+
+### Collections
+```vb
+New String() {"item1", "item2"}              ' Array
+New List(Of String) From {"a", "b"}          ' List
+New Dictionary(Of String, Object) From {{"key", "value"}}  ' Dictionary
+```
+
+### DataTable Access
+```vb
+row("ColumnName").ToString()                 ' Cell by name
+row(0).ToString()                            ' Cell by index
+Convert.ToInt32(row("Amount"))               ' Typed value
+dt.Select("[Status] = 'Active'")             ' Filter (returns DataRow[])
+dt.AsEnumerable().Where(Function(r) r("Col").ToString() = "Val").CopyToDataTable()  ' LINQ
+```
+
+### Error Handling
+```vb
+' Use Try-Catch activity (not code)
+' BusinessRuleException → skip item
+' System.Exception → retry/escalate
+' Always set ContinueOnError=False on HTTP Request
+```
+
+For the complete reference with DataTable operations, file paths, Orchestrator patterns, and deprecated activity mappings, see [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
+
+| Deprecated | Replacement |
+|-----------|-------------|
+| `OpenWorkbook` | `Excel Application Scope` |
+| `CloseWorkbook` | (scope handles cleanup) |
+| `ExcelForEachRow` (v1) | `For Each Row in Data Table` |
+| `KeywordBasedClassifier` | `IntelligentKeywordClassifier` |
+| `OutlookForEachMail` | `For Each Email` |