@uipath/skills 1.195.0

package/skills/uipath-rpa/references/coded/operations-guide.md

@@ -0,0 +1,417 @@
+# Operations Guide
+
+Detailed step-by-step procedures for all operations on UiPath coded workflow projects.
+
+## Initialize a New Coded Project
+
+Use this procedure ONLY when the user explicitly asked for a coded project ("coded", ".cs", "C# workflow"). For ambiguous "create a workflow" / "automate X" requests, default to XAML — see [../coded-vs-xaml-guide.md](../coded-vs-xaml-guide.md).
+
+There is no "create a coded project" command. `init` always scaffolds XAML; coded mode is a post-scaffold step (add `.cs` files, update `entryPoints`). For the canonical `init` documentation — flag semantics, scaffolding behavior, how `--expression-language` works — see [../environment-setup.md § Step 0.3: Creating a New Project](../environment-setup.md#step-03-creating-a-new-project).
+
+### Steps
+
+**1. Scaffold the project** following [../environment-setup.md § Step 0.3](../environment-setup.md#step-03-creating-a-new-project). The command is the same as for an XAML project — the scaffolding is XAML either way. The result is a project with `project.json`, `project.uiproj`, the template's XAML root file (`Main.xaml` / `TestCase.xaml`), and all required metadata directories.
+
+**2. Read the scaffolded files — do NOT overwrite blindly:**
+
+After `init` succeeds, read the generated files to understand the defaults:
+```
+Read: <PROJECT_DIR>/project.json
+Read: <PROJECT_DIR>/Main.xaml          # or TestCase.xaml for test projects
+```
+`project.json` contains valid defaults (correct schema version, runtime options, dependencies) that you should build on rather than replace. Leave the scaffolded XAML in place — `.xaml` and `.cs` workflows coexist freely in the same project.
+
+**3. Analyze the task and plan the file structure:**
+- How many workflow files? (one per logical step or responsibility)
+- Are there shared data models or helpers? (create Coded Source Files)
+- Is this a test project? (create test cases with Given/When/Then structure, optionally add Before/After hooks)
+- See [../project-structure-guide.md](../project-structure-guide.md) for guidelines
+
+**4. Add required dependencies to `project.json`** based on the Service-to-Package mapping. Edit the existing `project.json` — do NOT rewrite the entire file.
+
+**5. Add `.cs` workflow / test case / source files:**
+- Generate `.cs` files (workflows, test cases, source files)
+- For each `.cs` **workflow** file, add an entry to `entryPoints` in `project.json` (**Process projects only** — Tests and Library projects do NOT use `entryPoints`). The existing scaffolded XAML entry can stay alongside.
+- For each `.cs` **test case** file, add an entry to `designOptions.fileInfoCollection` in `project.json` with `editingStatus: "InProgress"`, `testCaseType: "TestCase"`, `publishAsTestCase: true`. Test cases do NOT go in `entryPoints` regardless of project type.
+- If test project and shared setup is needed, create a `partial class CodedWorkflow` source file that implements `IBeforeAfterRun` (see before-after-hooks-template.md)
+
+**6. Validate each file** (Critical Rule #14) — run the validation loop on every `.cs` file until it compiles cleanly
+
+> **Why `init` instead of manual files?** It generates correct schema versions, metadata directories, and default dependencies — manual creation risks subtle errors. See [json-template.md](../../assets/json-template.md) for reference-only templates.
+
+## Add a Workflow File to Existing Project
+
+**Steps:**
+1. Read existing `project.json` to get project name (for namespace), `outputType`, and current entry points
+2. Create the new `.cs` file:
+   - Use the project name as namespace
+   - Class name = file name (without .cs)
+   - Inherit from `CodedWorkflow`
+   - Add `[Workflow]` attribute on the entry-point method. Method name does not have to be `Execute` — any name works. `Execute` is convention; keep it unless the user asks otherwise
+   - Add appropriate `using` statements based on which activities are needed
+3. Argument direction is determined by the entry-point method signature. Single-return OutArgument is named **`"Output"`**. Tuple returns produce one OutArgument per element, named after the element. A tuple element name matching an input parameter name — or, for single returns, an input parameter literally named `"Output"` — collapses into one **`InOutArgument`**:
+
+   | Signature | Example | Argument directions |
+   |-----------|---------|---------------------|
+   | Single return | `public string Execute(int a, int b)` | `a` = In, `b` = In, return = Out named `"Output"` |
+   | Tuple return | `public (string Test, int A) Execute()` | `Test` = Out, `A` = Out |
+   | Tuple + name collision | `public (string a, string b) Execute(string b, int c)` | `a` = Out, `b` = InOut (same name in input and tuple), `c` = In |
+   | Single return + `Output` input | `public string Execute(string Output, int c)` | `Output` = InOut (input named `"Output"` collides with implicit return name), `c` = In |
+   | No return | `public void Execute(string input)` | `input` = In |
+
+   > **NEVER use C# `out` or `ref` keywords** on `Execute` parameters — the auto-generated `*+Activity.cs` wrapper does not handle them correctly. Symptoms: compile error `CS1620`, or runtime `Using 'out' and 'ref' modifiers is not allowed for Coded Workflows executions.` Studio regenerates the wrapper on every save, so manual fixes are reverted. Use return values or tuples for outputs instead.
+4. Update `project.json` (**Process projects only** — skip `entryPoints` for Tests and Library projects):
+   - Add new entry to `entryPoints` array with `filePath`, unique `uniqueId`, `input`, and `output` definitions
+   - If the workflow has parameters, define them in `input`/`output` with `name`, `type`, and `required`
+5. **Validate the file** — Run the validation loop (Critical Rule #14) until the file compiles cleanly before proceeding
+
+## Add a Test Case File
+
+Coded test cases automate and validate application behavior using a structured **Given-When-Then** (Arrange/Act/Assert) pattern. They inherit from `CodedWorkflow` just like workflows, but use the `[TestCase]` attribute.
+
+**Test cases can exist in any project type** — not just `"Tests"` projects. It's common to add test cases directly inside a `"Process"` project for testing purposes.
+
+**Steps:**
+1. Read existing `project.json` to get project name, `outputType`, and current entry points
+2. Create the `.cs` file following the same rules as workflows, but with:
+   - `[TestCase]` attribute instead of `[Workflow]` on the entry-point method (method name does not have to be `Execute` — any name works; keep `Execute` unless the user asks otherwise)
+   - Structured code in three phases: **Arrange**, **Act**, **Assert**
+3. Update `project.json`:
+   - Add entry to `entryPoints` array (**Process projects only** — skip `entryPoints` for Tests and Library projects)
+   - Add entry to `designOptions.fileInfoCollection` with `editingStatus: "InProgress"`, `testCaseType: "TestCase"`, `publishAsTestCase: true`
+4. For data-driven tests, add default parameter values: `public void Execute(string browser = "chrome.exe")`
+   - Optionally create `.variations/` data file for parameterized test data
+   - For CLI-based data sources (variations files, Test Data Queues, Data Service), see [../testing-guide.md § Data-Driven Testing](../testing-guide.md)
+5. **Validate the file** — Run the validation loop (Critical Rule #14) until the file compiles cleanly before proceeding
+6. **Update `editingStatus`** — When the user asks to mark a test case as ready/publishable, update its `editingStatus` in `fileInfoCollection` from `"InProgress"` to `"Publishable"`. Do NOT change this automatically — only when explicitly requested
+
+**Test case structure — Given/When/Then:**
+
+For test cases that validate non-UI logic (most common — call workflows and assert on results):
+```csharp
+using System;
+using UiPath.CodedWorkflows;
+
+namespace MyTestProject
+{
+    public class TestInvoiceCreation : CodedWorkflow
+    {
+        [TestCase]
+        public void Execute()
+        {
+            // GIVEN (Arrange) — set up test data
+            string invoiceId = "INV-001";
+            decimal amount = 1500.00m;
+            Log($"Testing invoice creation for {invoiceId}");
+
+            // WHEN (Act) — call the workflow under test
+            var result = workflows.CreateInvoice(invoiceId: invoiceId, amount: amount);
+
+            // THEN (Assert) — verify expected results
+            testing.VerifyExpression(result.success, "Invoice creation should succeed");
+            testing.VerifyAreEqual("POSTED", result.status, "Invoice should be in POSTED status");
+        }
+    }
+}
+```
+
+For test cases that validate UI behavior (requires descriptors from the Object Repository — read `ObjectRepository.cs` first and add `using <ProjectNamespace>.ObjectRepository;`):
+```csharp
+using System;
+using UiPath.CodedWorkflows;
+using UiPath.UIAutomationNext.API.Contracts;
+using MyTestProject.ObjectRepository;
+
+namespace MyTestProject
+{
+    public class TestInvoiceFormUI : CodedWorkflow
+    {
+        [TestCase]
+        public void Execute()
+        {
+            // GIVEN (Arrange) — open the application to the invoice form
+            // uiAutomation.Open() returns a screen handle; all interactions go through it
+            var formScreen = uiAutomation.Open(Descriptors.InvoiceApp.CreateInvoiceForm);
+            Log("Navigated to invoice creation form");
+
+            // WHEN (Act) — fill in details and submit
+            formScreen.TypeInto(Descriptors.InvoiceApp.CreateInvoiceForm.InvoiceNumberField, "INV-001");
+            formScreen.TypeInto(Descriptors.InvoiceApp.CreateInvoiceForm.AmountField, "1500.00");
+            formScreen.Click(Descriptors.InvoiceApp.CreateInvoiceForm.SubmitButton);
+
+            // THEN (Assert) — attach to confirmation screen and verify message
+            var confirmScreen = uiAutomation.Attach(Descriptors.InvoiceApp.ConfirmationScreen);
+            string message = confirmScreen.GetText(Descriptors.InvoiceApp.ConfirmationScreen.MessageLabel);
+            testing.VerifyExpression(message.Contains("successfully"), "Confirmation message should indicate success");
+        }
+    }
+}
+```
+
+**Assertion methods (via `testing` service):**
+- `testing.VerifyExpression(bool condition, string outputMessage = null)` — assert a boolean condition is true
+- `testing.VerifyAreEqual<T>(T expected, T actual, string outputMessage = null)` — assert equality
+- `testing.VerifyAreNotEqual<T>(T notExpected, T actual, string outputMessage = null)` — assert inequality
+- `testing.VerifyContains(string full, string part, string outputMessage = null)` — assert string containment
+- `testing.VerifyRange(double value, double min, double max, string outputMessage = null)` — assert value in range
+- `testing.SetTestDataQueueItems(...)` — set up test data from data queues
+- `testing.GetTestDataQueueItem(...)` — get next test data item
+
+**Test cases can invoke other workflows:**
+```csharp
+[TestCase]
+public void Execute()
+{
+    // Arrange — call a setup workflow using strongly-typed invocation
+    var setupResult = workflows.SetupTestData(environment: "staging");
+
+    // Act — call the workflow under test
+    var result = workflows.ProcessInvoice(invoiceId: "INV-001");
+
+    // Assert — verify the result with type-safe property access
+    testing.VerifyExpression(result.success, "Invoice processing should succeed");
+    testing.VerifyAreEqual("POSTED", result.status, "Invoice should be posted");
+}
+```
+
+**Shared Before/After hooks for all test cases:**
+Create a Coded Source File (e.g. `CodedWorkflowHooks.cs`) with `public partial class CodedWorkflow : IBeforeAfterRun` — the compiler merges it with the auto-generated CodedWorkflow partial, so all workflows and test cases get the hooks automatically. See `assets/before-after-hooks-template.md` for the full template.
+
+## Add a Coded Source File (Helper Class / Model / Utility)
+
+Coded Source Files are plain `.cs` files that contain reusable classes, models, enums, or utility methods. They are **not** entry points — they cannot be executed independently. Workflows and test cases consume them.
+
+**Key differences from workflow files:**
+- **NO** `CodedWorkflow` base class — they are plain C# classes
+- **NO** `[Workflow]` or `[TestCase]` attribute
+- **NO** entry in `project.json` `entryPoints`
+- Can contain multiple classes per file if logically related (e.g. a models file)
+
+**Steps:**
+1. Read existing `project.json` to get the project name (for namespace)
+2. Create the `.cs` file:
+   - Use the project name as namespace
+   - Class name = file name (without .cs)
+   - Add only the `using` statements the class needs (typically just `System` namespaces)
+   - Do NOT inherit from `CodedWorkflow`
+3. No `project.json` changes needed
+
+**When to create Coded Source Files:**
+- **Data models / DTOs** — classes that represent structured data (e.g. `InvoiceData`, `CustomerRecord`)
+- **Helper/utility classes** — static methods for string manipulation, data transformation, validation
+- **Custom enums** — project-specific enumerations
+- **Constants** — centralized configuration values or magic strings
+- **Extension methods** — reusable extensions for built-in types
+- **Business logic** — complex logic that should be testable/reusable independently from the workflow orchestration
+
+**Example — Data model source file (`InvoiceData.cs`):**
+```csharp
+using System;
+
+namespace MyProject
+{
+    public class InvoiceData
+    {
+        public string InvoiceNumber { get; set; }
+        public string CustomerName { get; set; }
+        public decimal Amount { get; set; }
+        public DateTime DueDate { get; set; }
+        public bool IsOverdue => DueDate < DateTime.Now;
+    }
+}
+```
+
+**Example — Utility source file (`StringHelpers.cs`):**
+```csharp
+using System;
+using System.Text.RegularExpressions;
+
+namespace MyProject
+{
+    public static class StringHelpers
+    {
+        public static string ExtractInvoiceNumber(string text)
+        {
+            var match = Regex.Match(text, @"INV-\d{6}");
+            return match.Success ? match.Value : string.Empty;
+        }
+
+        public static string NormalizeName(string name)
+        {
+            return name?.Trim().ToUpperInvariant() ?? string.Empty;
+        }
+    }
+}
+```
+
+**Using source files from a workflow:**
+```csharp
+// In ProcessInvoices.cs (a workflow)
+[Workflow]
+public void Execute()
+{
+    var invoice = new InvoiceData  // from InvoiceData.cs
+    {
+        InvoiceNumber = StringHelpers.ExtractInvoiceNumber(rawText),  // from StringHelpers.cs
+        CustomerName = StringHelpers.NormalizeName(customerField),
+        Amount = parsedAmount,
+        DueDate = dueDate
+    };
+    Log($"Processing invoice {invoice.InvoiceNumber}, overdue: {invoice.IsOverdue}");
+}
+```
+
+## Edit an Existing Workflow File
+
+**Steps:**
+1. Read the existing `.cs` file to understand current structure
+2. Apply requested changes while preserving:
+   - Namespace (must match project name)
+   - Class structure and base class (`CodedWorkflow`)
+   - Attribute (`[Workflow]` or `[TestCase]`)
+   - Method name (`Execute`)
+3. If parameters changed (added/removed/renamed/retyped) and this is a **Process** project:
+   - Update `project.json` `entryPoints` input/output definitions for this file (Tests and Library projects do not use `entryPoints`)
+4. **Validate the file** — Run the validation loop (Critical Rule #14) until the file compiles cleanly before proceeding
+
+## Remove a Workflow File
+
+**Steps:**
+1. Delete the `.cs` file
+2. Update `project.json`:
+   - **Process projects:** Remove from `entryPoints` array. If it was the `main` file, update `main` field to another entry point
+   - **Tests and Library projects:** No `entryPoints` to update
+   - If Tests project, remove from `fileInfoCollection`
+
+## API Discovery (Before Creating Workflows)
+
+**MANDATORY before generating any C# code**: Learn from existing project patterns first.
+
+This operation helps you understand the project's existing code style, API usage patterns, and conventions before creating new workflows. This ensures consistency across the project.
+
+**Steps:**
+
+1. **Search for existing C# files:**
+   ```
+   Glob pattern: "**/*.cs"
+   Path: <PROJECT_DIR>
+   ```
+
+2. **Count and filter results:**
+   - Count total .cs files returned
+   - Exclude files in `.local\.codedworkflows\` and `.codedworkflows\` from your count
+   - Note: Generated/temporary files in these folders can still be read for API information
+
+3. **Read example files:**
+   - **If 5+ files found**: Read at least 5 diverse examples
+   - **If fewer than 5**: Read all of them
+   - **If 0 files**: Proceed using generic CodedWorkflow patterns from templates
+
+4. **Read generated API files** (if they exist):
+   - `<PROJECT_DIR>\.local\.codedworkflows\ObjectRepository.cs` — UI element descriptors
+   - `<PROJECT_DIR>\.local\.codedworkflows\CodedWorkflow.cs` — available service definitions
+
+5. **Extract patterns:**
+   - Common `using` statements (e.g., `using UiPath.CodedWorkflows;`)
+   - Namespace patterns (e.g., `namespace ProjectName`)
+   - Class structure (inheritance from `CodedWorkflow`)
+   - Service usage patterns (e.g., `excel.UseExcelFile()`, `mail.Outlook()`)
+   - Argument patterns (input parameters, return tuples)
+   - Logging patterns (e.g., `Log("message")`)
+   - Error handling patterns (try-catch blocks)
+   - UI Automation patterns (Object Repository descriptor usage: `Descriptors.App.Screen.Element`)
+
+**Example patterns to look for:**
+
+```csharp
+// Common using statements
+using System;
+using System.Collections.Generic;
+using UiPath.CodedWorkflows;
+
+// Namespace pattern
+namespace MyProjectName
+{
+    // Class structure
+    public class MyWorkflow : CodedWorkflow
+    {
+        [Workflow]
+        public void Execute(string inputParam)
+        {
+            // Logging pattern
+            Log("Starting workflow...");
+
+            // Service usage pattern
+            using (var workbook = excel.UseExcelFile(inputParam))
+            {
+                // Implementation
+            }
+
+            // Error handling pattern
+            try
+            {
+                // Operations
+            }
+            catch (Exception ex)
+            {
+                Log($"Error: {ex.Message}");
+                throw;
+            }
+        }
+    }
+}
+```
+
+**Why API discovery matters:**
+- Ensures code consistency across the project
+- Prevents using incorrect method names or patterns
+- Identifies available services and their usage
+- Discovers project-specific conventions
+- Finds Object Repository selectors for UI automation
+- Reduces compilation errors from wrong API usage
+
+---
+
+## Configure UI Targets (Object Repository)
+
+**This operation applies when writing UI automation code** (any workflow that uses `uiAutomation.*` calls). UI automation uses **Object Repository descriptors** (`Descriptors.App.Screen.Element`) — if required elements are missing, configure them through the `uia-configure-target` skill flow.
+
+**When to use:**
+- The workflow needs a UI element that doesn't exist in `ObjectRepository.cs`
+- The user asks to automate something involving a screen or element not yet in the Object Repository
+
+**Workflow order:** Configure ALL missing targets FIRST, then write the workflow code using real descriptor paths.
+
+[ui-automation-guide.md](../ui-automation-guide.md) MUST be read IN FULL first, and [uia-configure-target-workflows.md](../uia-configure-target-workflows.md) MUST be read IN FULL first — they cover target configuration rules, selector recovery, indication fallback, and multi-step UI flows.
+
+**Key reminders:**
+- Add `using <ProjectNamespace>.ObjectRepository;` to any file referencing `Descriptors.*`
+- After target configuration, re-read `ObjectRepository.cs` — Studio regenerates it. Search for the reference IDs returned by `uia-configure-target` to find the exact `Descriptors.<App>.<Screen>.<Element>` paths.
+
+---
+
+## Add a Dependency
+
+Canonical CLI: `uip rpa packages install`. Do NOT hand-edit `project.json` `dependencies`. **There is no `uip rpa add-dependency` command** — agents that try it get `Unknown command: add-dependency`. See [cli-reference.md § packages install](../cli-reference.md).
+
+**Steps:**
+1. Read `project.json` to check existing dependencies — skip packages already at the desired version.
+2. Run:
+   ```bash
+   uip rpa packages install --project-dir "<PROJECT_DIR>" --packages '[{"id":"<PACKAGE_ID>","version":"<VERSION>"}]' --output json
+   ```
+   Omit `version` to resolve the latest compatible. Pin a version only when there is a known compatibility constraint (see pinned versions below). The CLI writes `project.json` and runs restore — re-read `project.json` afterward if subsequent steps need it.
+3. Only install packages the project actually needs.
+
+**Pinned versions for UiPath activity packages (current v25.x):**
+- `UiPath.System.Activities` → `25.12.2` — system activities (assets, queues, credentials)
+- `UiPath.Testing.Activities` → `25.10.2` — testing and assertions. Pin this exact patch — `25.10.0` and `25.10.1` synthesize a bootloader under `.local/install/` that references `UiPath.Robot.Activities.Api` and breaks the build with CS0234.
+- `UiPath.UIAutomation.Activities` → `25.10.21` — UI automation
+- `UiPath.Excel.Activities` → `3.3.1` — Excel automation
+- `UiPath.Word.Activities` → `2.3.1` — Word automation
+- `UiPath.Presentations.Activities` → `2.3.1` — PowerPoint automation
+- `UiPath.Mail.Activities` → `2.5.10` — Mail automation
+- `UiPath.MicrosoftOffice365.Activities` → `3.6.10` — Microsoft 365 (Graph API: mail, calendar, Excel cloud, OneDrive, SharePoint)
+- `UiPath.GSuite.Activities` → `3.6.10` — Google Workspace (Gmail, Calendar, Drive, Sheets, Docs)
+
+**Third-party NuGet packages:** same CLI — pass the public NuGet package ID as `id`. See [third-party-packages-guide.md](third-party-packages-guide.md).

package/skills/uipath-rpa/references/coded/third-party-packages-guide.md

@@ -0,0 +1,67 @@
+# Using Third-Party NuGet Packages in Coded Workflows
+
+When a user needs functionality that **no UiPath built-in activity provides** (e.g. PDF generation, barcode reading, advanced math, specific file formats), find and use a third-party NuGet package.
+
+## Decision Flow
+
+1. **Consider whether a built-in activity or plain .NET is the better fit** — prefer activities for Orchestrator integration, UI automation, and document handling; prefer .NET for data transforms, HTTP to external APIs, parsing, etc.
+2. **If no built-in activity fits** — search for a well-known .NET NuGet package that provides the capability
+3. **Inspect the package** — run the `uip rpa packages inspect` command with the appropriate flags in order to get exact API signatures before writing code
+4. **Install it** — run `uip rpa packages install --project-dir "<PROJECT_DIR>" --packages '[{"id":"<PACKAGE_ID>","version":"<VERSION>"}]' --output json`. Omit `version` to resolve the latest compatible. Do NOT hand-edit `project.json` `dependencies`. **There is no `uip rpa add-dependency` command.**
+5. **Write C# code using the package** — use the package's API directly in the `Execute` method (no service proxy needed — just `using` + direct API calls)
+
+## How Third-Party Packages Differ from UiPath Activity Packages
+
+- UiPath packages provide services on the `CodedWorkflow` base class (e.g. `excel.ReadRange(...)`)
+- Third-party packages are used as **plain C# libraries** — instantiate classes, call methods directly
+- They do NOT get a service property on `CodedWorkflow`
+- Add them to `project.json` `dependencies` just like UiPath packages: `"PackageName": "[version]"`
+
+## Example — Using CsvHelper in a Coded Workflow
+
+```csharp
+using System;
+using System.Globalization;
+using System.IO;
+using CsvHelper;
+using UiPath.CodedWorkflows;
+
+namespace MyProject
+{
+    public class ProcessCsv : CodedWorkflow
+    {
+        [Workflow]
+        public void Execute(string inputPath)
+        {
+            using var reader = new StreamReader(inputPath);
+            using var csv = new CsvReader(reader, CultureInfo.InvariantCulture);
+            var records = csv.GetRecords<dynamic>().ToList();
+            Log($"Read {records.Count} records from CSV");
+        }
+    }
+}
+```
+
+With `project.json` dependency:
+```json
+{
+  "dependencies": {
+    "CsvHelper": "[33.0.1]"
+  }
+}
+```
+
+## How to Search for Packages
+
+- Use web search to find the best .NET NuGet package for the task
+- Look for packages with high download counts, active maintenance, and .NET 6+ support
+- Common choices:
+  - `CsvHelper` (CSV parsing)
+  - `QuestPDF` (PDF generation)
+  - `ClosedXML` (Excel without UiPath)
+  - `HtmlAgilityPack` (HTML parsing)
+  - `Dapper` (database access)
+  - `RestSharp` (REST APIs)
+  - `Polly` (retry/resilience patterns)
+  - `Newtonsoft.Json` (JSON parsing - already included in most projects)
+- After identifying a package, run the `uip rpa packages inspect` command to discover exact APIs before coding

package/skills/uipath-rpa/references/coded-vs-xaml-guide.md

@@ -0,0 +1,187 @@
+# Coded vs XAML Decision Guide
+
+When to use coded workflows (C#), XAML workflows (low-code), Coded Source Files, or InvokeCode — and how they interact in hybrid projects.
+
+## Mode is a per-workflow choice, not a project setting
+
+`uip rpa init` produces a mode-agnostic project — both `project.uiproj` and `project.json` are scaffolded, and the project can host coded workflows (`.cs`), XAML workflows (`.xaml`), or both. The coded vs XAML decision happens when you add a workflow to the project (or when an existing project's dominant mode dictates the default — see step 1 below).
+
+## Decision Flowchart
+
+Follow top-down. Stop at the first match.
+
+0. **Did the user specify a mode?** ("coded workflow", "XAML workflow", "create a .cs file", "low-code") → **Use what they asked for. Do not second-guess.**
+1. **Check the project's existing mode.** Match it unless there is a clear reason not to:
+   - **XAML-only project** → default to XAML. Only go coded if steps 3-6 below apply.
+   - **Coded-only project** → default to coded. Activities (Excel, Mail, UI automation) are available via services on `CodedWorkflow`.
+   - **Hybrid project** → either mode is fine; pick the one that fits the task best using steps 2-7.
+   - **New project** → **default to XAML.** "Create a workflow", "automate X", "build an automation" all mean XAML. Continue to step 2 ONLY if the user used a coded-specific phrase ("coded workflow", ".cs", "C# workflow") or named a coded-specific trigger (data models, unit tests on business logic, complex algorithmic logic). Otherwise stop here and use XAML.
+2. **Can existing activities handle the task directly?** (read Excel, send email, move file, UI click/type, queue processing, connector calls) → **XAML.** This covers the bulk of RPA work. No coded mode needed.
+3. **Does it define data models, DTOs, enums, or custom classes?** → **Coded Source File** (plain `.cs`, no `CodedWorkflow` base). XAML cannot define types — this is the one case where going hybrid is always justified.
+4. **Does it involve complex algorithmic logic?** (5+ nested branches, LINQ aggregation, regex extraction, REST API pagination/retry, sorting/dedup/fuzzy matching) → **Coded Workflow** for that step. Standard if/else, simple loops, and connector calls are fine in XAML — only escalate when a single XAML workflow grows past ~50 activities.
+5. **Does it need unit tests or assertions on business logic?** → **Coded Workflow** + **Coded Test Case** for the logic under test. UI/integration tests can stay XAML.
+6. **Is it reusable utility code?** (helpers, formatters, validators, extension methods) → **Coded Source File**.
+7. **Default** → XAML.
+
+---
+
+## Use Coded Workflows When
+
+1. **Custom data models** — You need classes with properties to represent business entities (`InvoiceLineItem`, `CustomerRecord`). Without coded source files, you're stuck with `DataTable` or `Dictionary<string, object>` and lose type safety.
+   ```csharp
+   // Coded Source File: OrderModels.cs
+   public class OrderLine { public string ProductId; public decimal Price; public int Qty; }
+   ```
+
+2. **Complex data transformation** — JSON deserialization into typed objects, CSV parsing with conditional logic, LINQ aggregation, regex extraction. Coded gives you full `System.Text.Json`, LINQ, and string interpolation without nested InvokeCode activities.
+
+3. **Heavy branching logic** — Nested if/else-if chains, switch statements with 5+ cases, loops with `break`/`continue`. XAML flowcharts become unreadable past 3-4 decision nodes.
+
+4. **REST API integrations** — Building HTTP requests, handling pagination, managing auth tokens with retry logic. `HttpClient` patterns in C# are far cleaner than chaining HTTP Request + Deserialize JSON activities.
+
+5. **Reusable utility libraries** — Date formatting, validation helpers, encryption, file path manipulation. Define as a Coded Source File, callable from any workflow.
+
+6. **Unit-testable business logic** — Pure functions (input → output, no UI) that need automated assertions. Coded Test Cases can call coded workflows directly.
+
+7. **Algorithm-heavy work** — Sorting, deduplication, fuzzy matching, tree traversal — anything that would require dozens of Assign + If activities in XAML.
+
+---
+
+## Use XAML Workflows When
+
+**XAML is the default for any RPA task that does not explicitly require coded.** The list below covers the typical cases — but if a task is ambiguous, the answer is XAML.
+
+1. **Standard business automation** — Excel, email, PDF, web forms, file ops, SAP, Salesforce, ServiceNow, and other connector-driven work. The pre-built activity packages handle authentication, pagination, and error handling out of the box.
+
+2. **UI automation** — Click, type, scrape, verify on desktop or web. XAML is the default for UI automation; the visual selector builder, recording, and indication tools are built around it. Coded UI automation via `uiAutomation` service exists but is the niche path, not the default.
+
+3. **Simple linear processes** — Read Excel → filter rows → send email → move file. Straight pipelines of 5-10 activities with minimal branching read better as XAML.
+
+4. **Process orchestration** — REFramework, queue-based transaction processing, retry patterns. The XAML templates for these are battle-tested.
+
+5. **Mixed workloads** — When some steps are activity-heavy and others involve light logic. Use XAML for orchestration; extract only the genuinely complex logic into a coded workflow invoked via `Invoke Workflow File`.
+
+---
+
+## InvokeCode: When to Extract
+
+InvokeCode embeds C#/VB code inline in a XAML activity. It works for small snippets but becomes a maintenance problem quickly.
+
+### Extraction Rules
+
+1. **Code exceeds ~15 lines** → extract to a Coded Source File (utility) or Coded Workflow (if it needs `CodedWorkflow` services).
+2. **Code defines classes or types** → extract to a Coded Source File. InvokeCode cannot define reusable types.
+3. **Same code is copy-pasted across multiple XAML files** → extract to a Coded Workflow and invoke it via `Invoke Workflow File`.
+4. **Code needs unit tests** → extract to a Coded Workflow + Coded Test Case.
+5. **Code uses complex .NET APIs** (HttpClient, LINQ, JSON serialization) → extract to a Coded Workflow for better readability and error handling.
+
+### Comparison Table
+
+| Criterion | InvokeCode | Coded Source File | Coded Workflow |
+|-----------|-----------|-------------------|----------------|
+| **Where it lives** | Inline in XAML activity | Standalone `.cs` file | `.cs` file |
+| **Inherits CodedWorkflow** | No | No | Yes |
+| **Access to services** (`excel`, `mail`, etc.) | No | No | Yes |
+| **Can define classes/types** | No | Yes | No (one class per file, must be workflow) |
+| **Reusable across workflows** | No (copy-paste) | Yes (import namespace) | Yes (invoke from any workflow) |
+| **Unit testable** | No | Indirectly | Yes (via Coded Test Case) |
+| **Recommended max size** | ~15 lines | No limit | No limit |
+| **Entry point in project.json** | N/A | No | Process only |
+
+---
+
+## Hybrid Project Patterns
+
+Hybrid projects mix coded and XAML files. The `workflows` property provides strongly-typed access to **all** workflows — both `.cs` and `.xaml` — so there is no friction in cross-invocation.
+
+### Interop Mechanisms
+
+| From | To | Mechanism | Notes |
+|------|----|-----------|-------|
+| XAML | Coded Workflow | Invoke Workflow File (path to `.cs` file) | Arguments via In/Out parameters |
+| Coded | XAML Workflow | `workflows.XamlName()` | Strongly typed, same as coded-to-coded |
+| Coded | Coded Workflow | `workflows.Name()` | Strongly typed |
+| Any | Any (dynamic) | `RunWorkflow("path", dict)` | String-based fallback — use only when path is determined at runtime |
+
+### Pattern 1: XAML Root + Coded Logic
+
+XAML handles sequencing and simple activities. Coded workflows handle complex business logic. Coded Source Files define shared data models.
+
+```
+OrderProcessing/
+├── project.json
+├── Main.xaml                    # XAML: orchestrates the full process
+├── ScrapeOrderPortal.xaml       # XAML: UI automation with selectors
+├── SendConfirmationEmail.xaml   # XAML: Mail activities (straightforward)
+├── ValidateAndTransform.cs      # Coded workflow: 12 validation rules + LINQ transforms
+├── OrderModels.cs               # Coded source file: Order, LineItem, ValidationResult
+└── TransformHelpers.cs          # Coded source file: date parsing, currency conversion
+```
+
+**When to use:** The process has a clear linear flow (orchestrate in XAML) but contains pockets of complex logic (coded workflows) and needs typed data models (coded source files).
+
+### Pattern 2: Coded Root + XAML for Activities
+
+Coded workflow drives the process. XAML workflows wrap activity-heavy steps that are simpler to express visually.
+
+```
+InvoiceProcessor/
+├── project.json
+├── Main.cs                      # Coded: orchestrates, calls all steps
+├── ExtractInvoiceData.cs        # Coded: PDF parsing + JSON deserialization
+├── PostToSAP.xaml               # XAML: SAP connector activities
+├── GenerateReport.xaml           # XAML: Excel activities (write range, format, save)
+├── InvoiceModels.cs             # Coded source file: Invoice, LineItem DTOs
+└── TestExtractInvoice.cs        # Coded test case
+```
+
+**When to use:** The core logic is algorithmic (coded) but some steps are best expressed with pre-built activity packages (SAP, Excel).
+
+### Pattern 3: Shared Data Models
+
+Coded Source Files define typed models that both XAML and coded workflows use via arguments.
+
+```
+// OrderModels.cs — Coded Source File (no CodedWorkflow, no entry point)
+namespace OrderProcessing
+{
+    public class Order
+    {
+        public string OrderId { get; set; }
+        public string CustomerName { get; set; }
+        public List<LineItem> Items { get; set; }
+        public decimal Total => Items?.Sum(i => i.Price * i.Quantity) ?? 0;
+    }
+
+    public class LineItem
+    {
+        public string ProductId { get; set; }
+        public decimal Price { get; set; }
+        public int Quantity { get; set; }
+    }
+}
+```
+
+Both XAML workflows (via typed arguments) and coded workflows (via direct reference) can use these types, eliminating `DataTable` column-name guessing and `Dictionary` key typos.
+
+---
+
+## Anti-Patterns
+
+1. **50+ lines of C# in InvokeCode.** Extract to a Coded Source File or Coded Workflow.
+2. **Using `RunWorkflow("path")` when `workflows.*` is available.** The `workflows` property is strongly typed and works for both `.cs` and `.xaml` files.
+3. **Duplicating logic in both XAML and coded form.** Pick one, invoke it from the other.
+4. **Using `DataTable` or `Dictionary<string, object>` when a typed class would prevent errors.** Create a Coded Source File with a proper class.
+5. **Defaulting to coded for ambiguous requests.** "Create a workflow", "automate X", "build a process" mean XAML. Switch to coded only on explicit coded phrasing or a coded-specific trigger (custom types, complex algorithms, unit tests on business logic).
+6. **Overriding the user's explicit choice.** If the user says "coded workflow", create a coded workflow — do not suggest XAML instead. Same the other way: if the user says "XAML", do not suggest coded.
+7. **Picking coded for UI automation by default.** UI automation defaults to XAML. Coded UI automation via the `uiAutomation` service is the exception, not the rule.
+
+---
+
+## Related References
+
+- [coded/operations-guide.md](coded/operations-guide.md) — How to create coded workflows, test cases, and source files
+- [coded/coding-guidelines.md](coded/coding-guidelines.md) — C# coding rules and common issues
+- [xaml/workflow-guide.md](xaml/workflow-guide.md) — XAML workflow creation and editing
+- [xaml/common-pitfalls.md](xaml/common-pitfalls.md) — InvokeCode language property gotcha
+- [project-structure-guide.md](project-structure-guide.md) — Project layout examples including hybrid