@uipath/skills 1.199.0 → 1.200.0

package/skills/uipath-rpa/references/coded/codedworkflow-reference.md

@@ -11,7 +11,7 @@ All workflow and test case files inherit from `CodedWorkflow`, which provides bu
 | `DelayAsync(TimeSpan time)` / `DelayAsync(int delayMs)` | Pause execution asynchronously |
 | `BuildClient(string scope = "Orchestrator", bool force = true)` | Build an authenticated `HttpClient` for Orchestrator or custom scopes |
 | `GetRunningJobInformation()` | Returns `IRunningJobInformation` with current job context: job ID, process name/version, tenant, folder, organization, robot name, and more (see [IRunningJobInformation](#irunningjobinformation-properties) below) |
-| `RunWorkflow(string workflowFilePath, IDictionary<string, object> inputArguments = null, TimeSpan? timeout = null, bool isolated = false, InvokeTargetSession targetSession = InvokeTargetSession.Current)` | **Fallback method:** Invoke workflow by string path. Use `workflows.MyWorkflow()` instead when possible |
+| `RunWorkflow(string workflowFilePath, IDictionary<string, object> inputArguments = null, TimeSpan? timeout = null, bool isolated = false, InvokeTargetSession targetSession = InvokeTargetSession.Current)` | **Fallback method:** Invoke workflow by string path. Use `workflows.MyWorkflow()` instead when possible — fall back here when the generated typed accessors are stale or misbehaving after a signature change (rebuild first) |
 | `RunWorkflowAsync(...)` | Async version of `RunWorkflow` (same limitations apply) |
 
 ## Invoking Other Workflows
@@ -272,4 +272,160 @@ namespace MyProject
 | Shared helper methods for all workflows | `partial class CodedWorkflow` (no hooks) |
 | All of the above | Combine patterns in one or more partial files |
 
-Code templates: [assets/before-after-hooks-template.md](../../assets/before-after-hooks-template.md)
+Code templates: [assets/codedworkflow-template.md § Before/After Hooks Templates](../../assets/codedworkflow-template.md#beforeafter-hooks-templates)
+
+---
+
+## Inspect NuGet Package Tool (On-Demand API Discovery)
+
+Use this when `.local/docs/packages/<PackageId>/coded/coded-api.md` doesn't cover an API, when the user has a different package version, or when you need ground-truth method signatures. Bundled fallback: `references/activity-docs/<PackageId>/<closest-version>/coded/` in this skill ships per-package coded docs (`<service>.md` overview, `api.md` / `windows-api.md` + `portable-api.md` signatures, `examples.md`) for the major UiPath packages — read those when `.local/docs` has no coded docs for the package, picking the version folder closest to the installed one.
+
+### How to Run
+
+The `packages inspect` verb is built into the UiPath CLI. No separate build step is needed.
+
+#### Inspect a package from a NuGet feed
+```bash
+uip rpa packages inspect --package-name <PackageName> --package-version <Version> [--feed-url <NuGetV3FeedUrl>]
+```
+
+When `--feed-url` is omitted, the tool downloads from the UiPath Official feed first and falls back to nuget.org.
+
+#### Inspect a local .nupkg file
+```bash
+uip rpa packages inspect --nupkg-path <path/to/package.nupkg>
+```
+
+Use this when the package is already cached locally (e.g. from a private feed) or when you have a `.nupkg` file on disk.
+
+### Examples
+
+```bash
+# Inspect Excel activities from UiPath feed
+uip rpa packages inspect --package-name UiPath.Excel.Activities --package-version 3.3.1
+# Inspect a specific version the user has
+uip rpa packages inspect --package-name UiPath.System.Activities --package-version 25.12.2
+# Inspect from a custom feed
+uip rpa packages inspect --package-name MyPackage --package-version 1.0.0 --feed-url https://my-feed/v3/index.json
+# Inspect third-party package from nuget.org
+uip rpa packages inspect --package-name CsvHelper --package-version 33.0.1
+# Inspect a local .nupkg file directly
+uip rpa packages inspect --nupkg-path ~/.nuget/packages/csvhelper/33.0.1/csvhelper.33.0.1.nupkg
+```
+
+### Finding the Latest Stable Version
+
+When you don't know the version of a UiPath package, query the UiPath Official NuGet feed to find the latest stable (non-preview) version:
+
+```bash
+UIPATH_FEED="https://uipath.pkgs.visualstudio.com/5b98d55c-1b14-4a03-893f-7a59746f1246/_packaging/1c781268-d43d-45ab-9dfc-0151a1c740b7/nuget/v3/flat2" && bun -e "const p=process.argv[1];const r=await fetch(p+'/index.json');const d=await r.json();console.log(d.versions.find(v=>v.indexOf('preview')<0))" "$UIPATH_FEED/<package-name-lowercase>"
+```
+
+Replace `<package-name-lowercase>` with the package ID in lowercase (e.g. `uipath.microsoftoffice365.activities`).
+
+**Examples:**
+```bash
+# Latest stable UiPath.MicrosoftOffice365.Activities → 3.6.10
+... "$UIPATH_FEED/uipath.microsoftoffice365.activities"
+
+# Latest stable UiPath.System.Activities → 25.12.2
+... "$UIPATH_FEED/uipath.system.activities"
+```
+
+**Notes:**
+- The feed returns versions in descending order (newest first); the one-liner picks the first non-preview entry
+- Package names in the URL **must be lowercase**
+- This feed is public for version listing but requires authentication for package downloads (Studio handles this automatically when restoring dependencies)
+
+---
+
+### When to Use
+
+- **First**, check for pre-generated coded API docs at `{projectRoot}/.local/docs/packages/{PackageId}/coded/coded-api.md` — these contain service API signatures and usage for coded workflows. Use `packages inspect` only when these docs are missing or insufficient.
+- You encounter an unknown activity/method not in reference files
+- The user's `project.json` has a different package version than reference docs
+- You need exact method signatures, parameter types, or enum values
+- You're unsure about the correct API and want to verify against the actual package
+- You need to find and evaluate a third-party NuGet package for use in a coded workflow
+
+### Output
+
+Structured markdown listing all public types, methods, properties, enums, delegates, and events from the package DLLs. The tool performs framework-aware DLL selection and recursive dependency resolution (up to depth 2).
+
+### Requirements & Notes
+
+- Requires `uip` to be available on PATH
+- Downloads from the UiPath Official feed first, then falls back to nuget.org — so it works with **any** NuGet package, not just UiPath ones
+- The tool automatically checks the local NuGet cache at `~/.nuget/packages/` when a package cannot be downloaded
+- For local `.nupkg` files (e.g. packages from private feeds already cached locally), use `--nupkg-path` to skip the download entirely
+- Some packages are metapackages with no DLLs (e.g. `Humanizer`). If you get "No DLLs found", try the `.Core` sub-package (e.g. `Humanizer.Core`)
+
+---
+
+## Third-Party NuGet Packages
+
+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=<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/integration-service-guide.md

@@ -99,12 +99,12 @@ Typed handle to a specific IS connector + connection. Constructed by the auto-ge
    # → copy the "Id" field of the target connection
    ```
 
-### Step 1 — Resolve metadata using the uipath-platform skill
+### Step 1 — Resolve connector metadata
 
-Before writing the coded workflow, resolve the connector metadata using the `uipath-platform` skill. The full CLI commands and output interpretation are covered in those reference files:
+Before writing the coded workflow, resolve the connector metadata with the `uip is` CLI (drill into flags with `uip is <group> --help`; when the `uipath-platform` skill is available, delegate deep Integration Service questions to it):
 
-- **Find connector key and list connections:** [connectors.md](../../../uipath-platform/references/integration-service/connectors.md) and [connections.md](../../../uipath-platform/references/integration-service/connections.md)
-- **Discover activities/resources and run describe:** [activities.md](../../../uipath-platform/references/integration-service/activities.md) and [resources.md](../../../uipath-platform/references/integration-service/resources.md)
+- **Find connector key and list connections:** `uip is connectors list --output json`, then `uip is connections list <connector-key> --output json`
+- **Discover activities/resources and run describe:** `uip is activities list <connector-key> --output json`, `uip is resources list <connector-key> --output json`, `uip is resources describe <connector-key> <object-name> --operation <Op> --output json`
 
 The describe response tells you:
 
@@ -257,7 +257,8 @@ var response = await conn.ExecuteAsync(config, request);
 Run `uip rpa validate` on the written workflow file until 0 errors. Cap at 5 fix attempts.
 
 ```bash
-uip rpa validate --file-path "<WORKFLOW_FILE>" --project-dir "<PROJECT_DIR>" --output json```
+uip rpa validate --file-path "<WORKFLOW_FILE>" --project-dir "<PROJECT_DIR>" --output json
+```
 
 ---
 

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

@@ -25,15 +25,15 @@ Read: <PROJECT_DIR>/Main.xaml          # or TestCase.xaml for test projects
 - 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
+- See [../environment-setup.md § Designing Project Structure](../environment-setup.md#designing-project-structure) 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) — respect the four Error-severity coded analyzer rules while authoring: [coding-guidelines.md § Coded Workflow Analyzer Rules](coding-guidelines.md#coded-workflow-analyzer-rules)
+- Generate `.cs` files (workflows, test cases, source files) — respect the four Error-severity coded analyzer rules while authoring: [§ Coded Workflow Analyzer Rules](#coded-workflow-analyzer-rules)
 - 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)
+- If test project and shared setup is needed, create a `partial class CodedWorkflow` source file that implements `IBeforeAfterRun` (see [codedworkflow-template.md § Before/After Hooks Templates](../../assets/codedworkflow-template.md))
 
 **6. Validate each file** (Critical Rule #14) — run the validation loop on every `.cs` file until it compiles cleanly
 
@@ -41,6 +41,8 @@ Read: <PROJECT_DIR>/Main.xaml          # or TestCase.xaml for test projects
 
 ## Add a Workflow File to Existing Project
 
+> Before writing code, read [§ Coding Guidelines](#coding-guidelines) below — using-statement mapping, analyzer rules, anti-patterns.
+
 **Steps:**
 1. Read existing `project.json` to get project name (for namespace), `outputType`, and current entry points
 2. Create the new `.cs` file:
@@ -69,6 +71,8 @@ Read: <PROJECT_DIR>/Main.xaml          # or TestCase.xaml for test projects
 
 ## Add a Test Case File
 
+> Before writing code, read [§ Coding Guidelines](#coding-guidelines) below — using-statement mapping, analyzer rules, anti-patterns.
+
 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.
@@ -177,7 +181,7 @@ public void Execute()
 ```
 
 **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.
+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 [codedworkflow-template.md § Before/After Hooks Templates](../../assets/codedworkflow-template.md) for the full template.
 
 ## Add a Coded Source File (Helper Class / Model / Utility)
 
@@ -416,4 +420,268 @@ Canonical CLI: `uip rpa packages install`. Do NOT hand-edit `project.json` `depe
 - `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).
+**Third-party NuGet packages:** same CLI — pass the public NuGet package ID as `id`. See [codedworkflow-reference.md § Third-Party NuGet Packages](codedworkflow-reference.md#third-party-nuget-packages).
+
+---
+
+## Coding Guidelines
+
+Detailed coding rules, best practices, anti-patterns, and troubleshooting for coded workflows.
+
+### Using Statements Rules
+
+**CRITICAL: Only include `using` statements for namespaces actually used in the file.** Adding usings for packages not in `project.json` will cause compile errors.
+
+**Minimal using statements** (always safe in any workflow/test case file):
+```csharp
+using System;
+using System.Collections.Generic;
+using UiPath.CodedWorkflows;
+```
+
+**Add based on actual usage** — only include these when the file uses the corresponding types/services AND the package is in `project.json`:
+```csharp
+// If using system.* service (UiPath.System.Activities package):
+using UiPath.Core;
+using UiPath.Core.Activities.Storage;       // only if using storage APIs
+using UiPath.Orchestrator.Client.Models;    // only if using Orchestrator models
+
+// If using testing.* service (UiPath.Testing.Activities package):
+using UiPath.Testing;
+using UiPath.Testing.Enums;                 // only if using testing enums
+using UiPath.Testing.Activities.TestData;   // only if using test data queues
+
+// If using uiAutomation.* service (UiPath.UIAutomation.Activities package):
+using UiPath.UIAutomationNext.API.Contracts;
+using UiPath.UIAutomationNext.API.Models;
+using UiPath.UIAutomationNext.Enums;
+
+// If using Object Repository descriptors (Descriptors.App.Screen.Element):
+using <ProjectNamespace>.ObjectRepository;  // e.g. using RoboticEnterpriseFramework.ObjectRepository;
+// OR if descriptors come from a UILibrary NuGet package (not the project's own OR):
+// using <PackageNamespace>.ObjectRepository;  // e.g. using MultipleApps.Descriptors.ObjectRepository;
+// CRITICAL: Without this, you get CS0103: The name 'Descriptors' does not exist in the current context
+// NOTE: When descriptors come from a UILibrary package, use the PACKAGE namespace, not the project namespace
+
+// If using excel.* service (UiPath.Excel.Activities package):
+using UiPath.Excel;
+using UiPath.Excel.Activities;
+using UiPath.Excel.Activities.API;
+using UiPath.Excel.Activities.API.Models;
+
+// If using word.* service (UiPath.Word.Activities package):
+using UiPath.Word;
+using UiPath.Word.Activities;
+using UiPath.Word.Activities.API;
+using UiPath.Word.Activities.API.Models;
+
+// If using powerpoint.* service (UiPath.Presentations.Activities package):
+using UiPath.Presentations;
+using UiPath.Presentations.Activities;
+using UiPath.Presentations.Activities.API;
+using UiPath.Presentations.Activities.API.Models;
+
+// If using mail.* service (UiPath.Mail.Activities package):
+using UiPath.Mail.Activities.Api;
+
+// If using office365.* service (UiPath.MicrosoftOffice365.Activities package):
+using UiPath.MicrosoftOffice365.Activities.Api;
+
+// If using google.* service (UiPath.GSuite.Activities package):
+using UiPath.GSuite.Activities.Api;
+
+// Standard .NET (add as needed):
+using System.Data;           // DataTable
+using System.Linq;           // LINQ
+using System.IO;             // file operations
+using System.Text.RegularExpressions;  // regex
+```
+
+**When adding a file that uses a service:**
+1. Check `project.json` to confirm the required package is listed in `dependencies` — add it if missing
+2. Add only the `using` statements needed for the types actually referenced in the file
+3. Add the entry point to `project.json` (**Process projects only** — Tests and Library projects do not use `entryPoints`). Add `fileInfoCollection` for test case files (all project types)
+
+### Platform types — do not reinvent
+
+UiPath ships first-class types for the patterns coded workflows most commonly need (exceptions, queue items, credentials, OR descriptors). **Always import the platform type instead of defining a project-local equivalent.** A project-local `BusinessRuleException`, custom queue-item record, or hand-rolled credential helper diverges from Orchestrator behaviour and breaks integration with platform features that expect the canonical types.
+
+| Platform type | Namespace / package | Use for | Do NOT do this instead |
+|---|---|---|---|
+| **`UiPath.Core.BusinessRuleException`** | `UiPath.Core` (in `UiPath.System.Activities`) | Business-rule violations that must NOT be retried by REFramework / Orchestrator (e.g., invalid input data, validation failure, missing required field). Orchestrator marks the queue item as `Failed` with no retry. | Define a project-local `class BusinessRuleException : Exception { … }`. |
+| **`UiPath.Robot.Activities.BusinessException`** | `UiPath.Robot.Activities` | Same role as `BusinessRuleException` in robot-side custom activity packages. | Same — do not define your own. |
+| **`UiPath.Core.Activities.Storage.IResource` / `ILocalResource`** | `UiPath.Core.Activities.Storage` (in `UiPath.System.Activities`) | File / folder handles passed to activities that need an `IResource`. | Pass raw `string` paths or hand-roll a `LocalResource` constructor (the constructor is internal — see § IResource / ILocalResource below). |
+| **`UiPath.Orchestrator.Client.Models.QueueItemDto`** and related | `UiPath.Orchestrator.Client.Models` (in `UiPath.System.Activities`) | Queue-item shape returned by `GetTransactionItem` / pushed via `AddQueueItem`. | Define a project-local queue-item record that diverges from Orchestrator's schema. |
+| **OR descriptors `Descriptors.<App>.<Screen>.<Element>`** | Generated into `<PROJECT_DIR>/.local/.codedworkflows/ObjectRepository.cs` | UI element targeting in coded UI automation. | Hand-roll selector strings or `TargetAppModel` instances; bypass the Object Repository. |
+| **`UiPath.CodedWorkflows.CodedWorkflow`** | `UiPath.CodedWorkflows` (built into the runtime) | Base class for `[Workflow]` and `[TestCase]` classes. | Inherit from a custom base; the Studio wrapper generation depends on this exact type. |
+
+#### Throwing `BusinessRuleException` correctly
+
+```csharp
+using UiPath.Core;     // brings BusinessRuleException into scope
+
+if (!System.Text.RegularExpressions.Regex.IsMatch(hash, @"^[0-9a-f]{40}$"))
+{
+    throw new BusinessRuleException(
+        $"Computed hash '{hash}' does not match expected SHA1 format (40 lowercase hex chars).");
+}
+```
+
+`BusinessRuleException` is recognised by REFramework's `SetTransactionStatus` and by Orchestrator's queue-item lifecycle — items failed with this exception are marked **Failed** and not retried automatically. A project-local exception with the same name is just an `Exception` from REFramework's point of view and triggers the system-error retry path instead.
+
+#### When you MAY define a project-local type
+
+Project-local types are appropriate for **domain DTOs** that have no platform equivalent — `InvoiceLineItem`, `CustomerRecord`, `WorkItem` — and belong in Coded Source Files. The rule above applies to platform-provided types only: do not reinvent exceptions, queue-item shapes, credential handles, file-resource handles, or OR descriptors.
+
+### Coded Workflow Analyzer Rules
+
+Four built-in Workflow Analyzer rules with scope `Coded Workflow` run as Roslyn analyzers over the project's `.cs` files. All four are **Error** severity and enabled by default — a violation fails `uip rpa analyze`, `build`, and `pack`, and Studio flags the same violations as validation errors. Author to satisfy them up front:
+
+| Rule | Trigger | Fix |
+|------|---------|-----|
+| **ST-NMG-017** — Class name matches default namespace | A class declared inside the project's default namespace has the same name as that namespace (generated from the project name) — e.g. class `Invoicing` in project `Invoicing`. Applies to every class, including Coded Source Files. | Rename the class (and its file to match) — e.g. `InvoicingWorkflow` |
+| **ST-DBP-010** — Multiple `[Workflow]`/`[TestCase]` | More than one `[Workflow]` or `[TestCase]` attribute in the same **file** (the two attribute kinds count together) | One entry-point attribute per file — move each extra entry point to its own file |
+| **ST-REL-001** — Mismatched InOut argument types | An entry-point input parameter collapses into an InOut argument (its name matches a return-tuple element, or it is literally named `Output` with a single non-void return) but the input and returned types differ | Make the input parameter type and the returned type identical |
+| **ST-USG-017** — Invalid parameter modifier | `out` or `ref` modifier on a `[Workflow]`/`[TestCase]` method parameter | Use return values or tuples for outputs instead |
+
+> Older CLI versions listed these rules in `analyzer-rules list` but did not execute them headlessly — only Studio flagged the violations. Do not treat a clean `analyze`/`build`/`pack` from an older CLI as proof these rules pass; fix violations at authoring time regardless.
+
+### Best Practices
+
+### API Discovery
+- **ALWAYS search for existing .cs files BEFORE generating new code** — Learn from existing patterns
+- Read at least 5 existing workflow files (or all if fewer) to understand project conventions
+- **When writing UI automation code** — the UIA package guide (`{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md`) MUST be read IN FULL first (SKILL.md Rule 7). Follow its **Finding Descriptors** hierarchy in strict order. Do NOT write any UI code until descriptors are resolved:
+  1. Read `ObjectRepository.cs` — use existing descriptors if present
+  2. Inspect UILibrary/descriptor NuGet packages in `project.json` (e.g. `*.Descriptors`, `*.UILibrary`) using `uip rpa packages inspect`. The tool checks the local NuGet cache automatically. If the package is still not found, read `.metadata` files manually at `~/.nuget/packages/<package-name>/<version>/contentFiles/any/any/.objects/` to discover App/Screen/Element hierarchy
+  3. If descriptors are still missing — use the `uia-configure-target` skill flow (found in the UIA activity-docs) to create targets. This handles capturing the application, discovering elements, generating selectors, improving them, and registering them in the OR. Do NOT manually call the internal `uip rpa uia` CLIs outside of the skill flow. Fallback: the indication commands (see UIA docs) when elements appear only after user interaction (e.g., a compose form that opens after clicking a button)
+  4. UITask (ScreenPlay) is ONLY for when selectors are genuinely brittle/unreliable — NEVER as a first approach
+  5. NEVER bypass Object Repository by constructing `TargetAppModel` with raw URL/BrowserType
+- Use `uip rpa packages inspect` for API discovery when documentation is unclear
+
+### IResource / ILocalResource — Converting File Paths
+
+Many activities (O365, GSuite, Mail, file operations) require `IResource` or `ILocalResource` instead of a string path. NEVER pass a raw string where `IResource` is expected — it will fail at runtime. NEVER try to construct `LocalResource(string)` directly — the constructor is internal.
+
+| Method | Signature | Use when |
+|--------|-----------|----------|
+| `GetResourceForLocalPath` | `system.GetResourceForLocalPath(string path, PathType pathType)` → `IResource` | You have a path and need an `IResource` (no existence check needed) |
+| `PathExists` (with out param) | `system.PathExists(string path, PathType pathType, out ILocalResource resource)` → `bool` | You need to verify the file exists AND get an `ILocalResource` |
+
+```csharp
+// Direct conversion — preferred when you know the file exists
+IResource file = system.GetResourceForLocalPath(@"C:\Reports\report.pdf", PathType.File);
+IResource folder = system.GetResourceForLocalPath(@"C:\Archive", PathType.Folder);
+
+// With existence check
+if (system.PathExists(@"C:\Reports\report.pdf", PathType.File, out ILocalResource localFile))
+{
+    // use localFile
+}
+```
+
+`PathType` values: `PathType.File`, `PathType.Folder`
+
+### Code Quality
+- **Start simple, iterate** — Create minimal working version first, then refine
+- **NEVER use C# `out` or `ref` keywords in `[Workflow]` methods** — The auto-generated `*+Activity.cs` wrapper does not handle them correctly. Symptoms: analyzer error ST-USG-017 at `analyze`/`build`/`pack`, 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
+- **Only include using statements for packages in project.json** — Adding unused usings causes compile errors
+- **Match input parameter names exactly** — Execute method signature must match `--input` arguments (case-sensitive)
+- **Escape backslashes in paths** — Use `C:\\path\\file.txt` not `C:\path\file.txt` in input arguments
+- **Resolve paths portably** — accept file/dir paths as arguments and resolve relative to the run-time working directory (`Directory.GetCurrentDirectory()`, `Path.Combine`); a machine-specific absolute path baked into code or a default value breaks on every other machine
+
+### Validation Loop (Critical Rule #14)
+uip rpa validate --file-path "<FILE>" --project-dir "<PROJECT_DIR>" --output json
+Full loop (phases, exit criteria, error recovery): [../cli-reference.md § Validation Iteration Loop](../cli-reference.md#validation-iteration-loop)
+
+### Error Handling
+- **Fix compilation errors methodically** — Categorize: Syntax → Type → Logic. Use the validation loop above to iterate until clean.
+- **Retry on execution failures** — Attempt to fix and retry up to 2 times before asking user
+- **Analyze errors carefully** — Read error messages, identify root cause, make targeted fixes
+- **Fix one thing at a time** — When a runtime error occurs, identify the root cause, fix ONLY that, and re-run. Never bundle a speculative "improvement" (e.g., switching from TypeInto to KeyboardShortcut) with the actual fix (e.g., correcting a selector). Changing two things at once makes it impossible to verify which change resolved the issue — or whether the speculative change introduced a new one.
+- **Don't give up too early** — But stop after 2 failed retries and present the user with options:
+```
+Workflow execution failed after 2 retry attempts.
+
+**Error Details:** <specific error message and location>
+**Suggested Fix:** <analysis of what went wrong>
+**Next Steps:** Would you like me to:
+A) <recommended fix approach>
+B) <alternative approach>
+C) <user-driven approach>
+```
+
+### File Operations
+- **ALWAYS use Read tool before Edit tool** — Understand current state before making changes
+- **Prefer editing over creating new files** — Build on existing work, avoid file bloat
+- **Use Glob for file discovery** — Never guess file locations
+
+### Anti-Patterns (What NOT to Do)
+
+> Many of these reinforce SKILL.md Critical Rules. They are grouped by category for quick scanning.
+
+### Project & Code Structure
+
+- Never manually write `project.json` or `project.uiproj` when creating a new project — use `uip rpa init` (Critical Rule #1)
+- Never generate C# code without first searching for existing .cs files (API Discovery)
+- Never edit files without reading them first
+- Never skip the `[Workflow]` or `[TestCase]` attribute on the Execute method (Critical Rule #4)
+- Never put more than one `[Workflow]`/`[TestCase]` attribute in the same file — analyzer error ST-DBP-010 (see § Coded Workflow Analyzer Rules)
+- Never name a class the same as the project — analyzer error ST-NMG-017 (see § Coded Workflow Analyzer Rules)
+- Never forget to inherit from `CodedWorkflow` (except Coded Source Files) (Critical Rule #3)
+- Never add `using` statements for packages not in `project.json` — causes CS errors
+- Never guess service method names — verify with existing code or `uip rpa packages inspect`
+- Never hardcode machine-specific absolute paths as argument defaults or literals — resolve relative to the run-time working directory (see § Code Quality)
+
+### UI Automation
+
+- Never hardcode UI selectors — use Object Repository descriptors
+- Never write UI code referencing descriptors without first reading `ObjectRepository.cs`
+- Never manually craft UI selectors by calling the internal `uip rpa uia` CLIs outside of the `uia-configure-target` skill flow — this skips selector improvement and OR registration
+- Never skip the target configuration step when a descriptor is missing — use the `uia-configure-target` skill flow (fallback: indication commands per the UIA docs)
+- Never use UITask (ScreenPlay) as the primary approach — resolve descriptors via Finding Descriptors hierarchy first (Critical Rule #15)
+- Never skip configuring targets because it "seems tedious" — configure ALL missing elements
+- Never construct `TargetAppModel` with raw URL/BrowserType to bypass Object Repository
+- Never skip checking UILibrary/descriptor NuGet packages in `project.json`
+- Never use an element descriptor on the wrong screen handle — each `UiTargetApp` is bound to its screen. Wrong handle gives `"Target name 'X' is not part of the current screen."`
+- Never use `SelectItem` on web dropdowns without a `TypeInto` fallback — web `<select>` elements often fail with `"Cannot select item"`
+- Never forget `using <ProjectNamespace>.ObjectRepository;` (or `using <PackageName>.ObjectRepository;` for UILibrary packages) when referencing `Descriptors.*`
+
+### Object Repository / Indicate Commands
+
+- Never assume `.objects/` subdirectories mean a valid App exists — verify `.metadata` files are present
+- Never cache or reuse AppVersion references across OR resets — always re-read `.objects/` metadata
+- Never run indicate commands from outside the project directory — cwd must contain `project.json`
+- Never use camelCase flags — all `uip rpa` CLI flags use kebab-case (e.g., `--foo-bar`, not `--fooBar`)
+
+### Validation & Execution
+
+- Never assume create/edit succeeded without running the validation loop (Critical Rule #14)
+- Never continue retrying indefinitely — stop after 5 validation fix attempts or 2 runtime execution retries
+- Never make unrelated changes during retry — identify the root cause, fix only that, re-run and verify. Never bundle a speculative "improvement" with the actual fix (e.g., fixing a broken selector AND switching from TypeInto to KeyboardShortcut in the same edit). One change, one re-run.
+- Never execute a workflow with parameters without providing `--input` arguments
+- Never use parameter names in `--input` that don't match the Execute method signature (case-sensitive)
+
+### Shell & Environment
+
+- Never redirect output to `nul` — use `> /dev/null 2>&1` instead (`nul` creates a literal file on Windows)
+- Never use Windows shell commands (`del`, `dir`, `copy`) in bash — use `rm`, `ls`, `cp`
+
+### Common Issues and Fixes
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| **"Studio X.X.X does not have interop support"** | Surfaces only when running against Studio Desktop and the auto-detected install is too old (< 26.2). Headless Studio is unaffected. | Pass `--studio-dir "<STUDIO_DIR>"` pointing to a 26.2+ build, or drop the Studio Desktop override and let the command run headless |
+| **No Studio instances found** | Only relevant for `diff` / `focus-activity` — they need Studio Desktop. Every other command runs headless and doesn't need a Desktop instance. | Run `uip rpa studio start --project-dir "<PROJECT_DIR>"` if you actually need Studio Desktop; otherwise re-run the command — headless Studio relaunches automatically |
+| **Stale pipe / ENOENT** | Studio instance crashed or was closed | The tool retries automatically; if persistent, re-run the command (headless) or restart Studio Desktop |
+| **Workflow cannot be found** | Entrypoint not in project.json | Verify project.json entrypoint has the file listed (Process projects only — Tests and Library projects do not use `entryPoints`) |
+| **Service property not available** | Missing package dependency | Install the required package via `uip rpa packages install --project-dir "<PROJECT_DIR>" --packages id=<PACKAGE_ID> --output json` (no `add-dependency` command exists; do not hand-edit `project.json`) |
+| **Timeout** | Studio took too long to start. First headless call on a cold NuGet cache can take 30–90 s. | Increase timeout: `--timeout 600` |
+| **"Target name 'X' is not part of the current screen"** | Element descriptor used on wrong screen handle | Use the `UiTargetApp` handle from `Open`/`Attach` for the screen that owns the element |
+| **"Cannot select item. It was not found among existing items"** | The `Item` value doesn't match any option (wrong text/casing) — not a control-type limitation | Read the control's `items` attribute via the interact CLI (SelectItem usage guide, routed from the UIA package guide § Documentation) and pass one of those values verbatim. `SelectItem` drives any control whose `items` lists options (any UI stack); use `TypeInto` only for type-ahead combos or controls with no `items`. |
+| **`packages inspect` cannot find UILibrary package** | Package is on a private/local NuGet feed | Use `--nupkg-path` to inspect the local `.nupkg` directly, or read `.metadata` files manually from `~/.nuget/packages/<name>/<version>/contentFiles/any/any/.objects/` |
+| **Studio rejects manually created project** | Missing metadata dirs, wrong schema/version | Always use `uip rpa init` instead of writing `project.json` manually |
+| **`CS0103` on an Execute default parameter value** | Default values are copied verbatim into the generated `*+Activity.cs` wrapper, where class consts/fields are out of scope | Use self-contained compile-time literals as defaults (`"output"`, `2`, `null`) — never a reference to a const, static, or member |
+| **Argument default ignored — empty string arrives instead** | `--input-arguments key=` (empty value) passes `""`, which OVERRIDES the declared default | Omit the flag entirely to use the method's default value |
+| **Runs invoke stale code after a signature change** | Generated wrapper (`*+Activity.cs` / WorkflowRunnerService) not regenerated | Re-run `uip rpa build` after changing an Execute signature; never hand-patch generated files under `.local/` |
+| **Nondeterministic errors confined to `.local/` generated files** (`WorkflowRunnerService.cs` missing/stale, CS errors in `.local/install/<Class>+<Method>Activity.cs`; project `validate` or `run` flips between clean and failing with unchanged sources) | CLI codegen destroys/regenerates the coded-workflow wrappers unreliably; a cached headless Studio instance holds stale state | Errors that live only under `.local/` are cache corruption, NOT source defects — judge project health by `build` + per-file `validate` on authored sources. Recover surgically, in order: (1) delete only the stale generated wrappers under `.local/install/` (and a corrupt `WorkflowRunnerService.cs` if present); (2) kill the headless Studio host process — it relaunches on the next command; (3) run `uip rpa build` ONCE to regenerate; (4) execute with `uip rpa run --skip-build` per workflow/test from then on. Do NOT `rm -rf .local/` wholesale — a full cold restore destabilizes codegen further and re-pays the 30–90 s NuGet restore per run. Do NOT add `[TestCase]` files to `entryPoints` while debugging this (Rule 15 forbids it regardless). Resilience option when tests keep tripping the flaky proxy: keep pure logic in a Coded Source File (Rule 19) and assert on the shared function directly — the trade-off is losing integration coverage of the workflow proxy itself. |

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

@@ -181,7 +181,7 @@ Both XAML workflows (via typed arguments) and coded workflows (via direct refere
 ## 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
+- [coded/operations-guide.md § Coding Guidelines](coded/operations-guide.md#coding-guidelines) — C# coding rules and common issues
+- [xaml/xaml-basics-and-rules.md](xaml/xaml-basics-and-rules.md) — XAML authoring workflow, anatomy, 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
+- [environment-setup.md § Designing Project Structure](environment-setup.md#designing-project-structure) — Project layout examples including hybrid