@uipath/skills 1.195.0

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

@@ -0,0 +1,275 @@
+# CodedWorkflow Base Class Reference
+
+All workflow and test case files inherit from `CodedWorkflow`, which provides built-in methods and service access. The `CodedWorkflow` class is a **partial class** — you can extend it in a Coded Source File (see "Extending CodedWorkflow with Before/After Hooks" below).
+
+## Built-in Methods (available in any workflow/test case via `this`)
+
+| Method | Description |
+|--------|-------------|
+| `Log(string message, LogLevel level = LogLevel.Info, IDictionary<string, object> additionalLogFields = null)` | Output log messages with optional level and custom fields. Valid `LogLevel` values: `Trace`, `Verbose`, `Info`, `Warn`, `Error`, `Fatal`. Note: `LogLevel.Warning` does not exist — use `LogLevel.Warn` |
+| `Delay(TimeSpan time)` / `Delay(int delayMs)` | Pause execution synchronously |
+| `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 |
+| `RunWorkflowAsync(...)` | Async version of `RunWorkflow` (same limitations apply) |
+
+## Invoking Other Workflows
+
+**Recommended:** Use the strongly-typed `workflows` property to invoke other workflows in your project:
+
+```csharp
+// Invoke workflow with strongly-typed parameters
+var result = workflows.ProcessInvoice(invoiceId: "INV-001", amount: 1500.00m);
+Log($"Processing completed: {result.success}");
+```
+
+**Benefits of `workflows.MyWorkflow()`:**
+- **Type-safe:** Compile-time checking of workflow names and parameters
+- **IntelliSense:** Auto-completion for workflow names and parameters
+- **Refactor-friendly:** Renaming workflows/parameters updates all references
+- **Dynamic updates:** Automatically adapts when workflows change
+
+**Default parameters:** Workflows with default parameter values can be invoked with or without those arguments — omitted parameters use their defaults:
+```csharp
+// If ProcessData has: Execute(string source, int maxRows = 100, bool verbose = false)
+workflows.ProcessData(source: "invoices.csv");                          // maxRows=100, verbose=false
+workflows.ProcessData(source: "invoices.csv", maxRows: 500);           // verbose=false
+workflows.ProcessData(source: "invoices.csv", maxRows: 500, verbose: true);  // all explicit
+```
+
+**Fallback (string-based):** For dynamic scenarios where workflow name isn't known at compile time:
+
+```csharp
+// Only use when workflow name is determined at runtime
+string workflowPath = GetWorkflowPathFromConfig();
+var result = RunWorkflow(workflowPath, new Dictionary<string, object>
+{
+    { "invoiceId", "INV-001" },
+    { "amount", 1500.00m }
+});
+```
+
+> **Return value:** `RunWorkflow` returns `IDictionary<string, object>`. Argument direction is determined by the `Execute` method signature:
+>
+> - **Single return value** (`public string Execute(int a, int b)`) — the result is stored under the key `"Output"`. Access it as `result["Output"]`.
+> - **Multiple outputs via tuple** (`public (string a, string b) Execute()`) — each tuple member becomes a separate key: `result["a"]`, `result["b"]`. These are Out arguments.
+> - **InOut arguments** — when a parameter name appears in both the input parameters and the return tuple, it is an InOut argument. Example: `public (string a, string b) Execute(string b, int c)` — `a` is Out, `b` is InOut (same name in input and output), `c` is In.
+>
+> For same-project workflows, prefer the type-safe `workflows.MyWorkflow()` property — it returns the declared return type directly and avoids this dictionary lookup.
+
+## Service Properties (injected based on installed packages)
+
+Services are accessed as properties on `this`: `system.GetAsset(...)`, `excel.ReadRange(...)`, `testing.VerifyExpression(...)`, etc. See the Service-to-Package mapping in SKILL.md.
+
+## Integration Service Connections
+
+> **Two IS connection patterns exist in coded workflows.** This section covers first-party package connections (Office365, GSuite) where Studio auto-generates `ConnectionsManager.cs` / `ConnectionsFactory.cs`. For raw IS connectors (Jira, Salesforce, custom) that use `CodedConnectorConfiguration` + agent-generated `ISConnections.cs`, see [integration-service-guide.md](integration-service-guide.md).
+
+When packages that use Integration Service connections are installed (e.g. `UiPath.MicrosoftOffice365.Activities`, `UiPath.GSuite.Activities`), Studio auto-generates two files in `.codedworkflows/`:
+
+- **`ConnectionsManager.cs`** — Exposes a typed property for each connection category (e.g. `O365Mail`, `Excel`, `OneDrive`, `Gmail`, etc.)
+- **`ConnectionsFactory.cs`** — Contains factory classes with typed properties for each configured connection instance
+
+These are injected via the `connections` property on `CodedWorkflow`.
+
+### How It Works
+
+1. **Configure connections** in UiPath Automation Cloud → Integration Service
+2. **Studio detects them** and generates typed accessors in `.codedworkflows/`
+3. **Access in code** via `connections.<FactoryName>.<ConnectionName>`
+
+### Example: ConnectionsManager.cs (auto-generated)
+
+```csharp
+public class ConnectionsManager
+{
+    public ExcelFactory Excel { get; set; }
+    public O365MailFactory O365Mail { get; set; }
+    public OneDriveFactory OneDrive { get; set; }
+
+    public ConnectionsManager(ICodedWorkflowsServiceContainer resolver)
+    {
+        Excel = new ExcelFactory(resolver);
+        O365Mail = new O365MailFactory(resolver);
+        OneDrive = new OneDriveFactory(resolver);
+    }
+}
+```
+
+### Example: ConnectionsFactory.cs (auto-generated)
+
+```csharp
+public class O365MailFactory
+{
+    // Connection name derived from Integration Service display name
+    public MailConnection My_Workspace_user_company_com { get; set; }
+
+    public O365MailFactory(ICodedWorkflowsServiceContainer resolver)
+    {
+        My_Workspace_user_company_com = new MailConnection("9e26a554-...", resolver);
+    }
+}
+
+public class OneDriveFactory
+{
+    public OneDriveConnection Shared_tenant_onmicrosoft_com { get; set; }
+
+    public OneDriveFactory(ICodedWorkflowsServiceContainer resolver)
+    {
+        Shared_tenant_onmicrosoft_com = new OneDriveConnection("22530bcf-...", resolver);
+    }
+}
+```
+
+### Usage Pattern
+
+```csharp
+// Step 1: Get the connection from the auto-generated factory
+var mailConnection = connections.O365Mail.My_Workspace_user_company_com;
+
+// Step 2: Get a sub-service from the connection-based service
+var mailService = office365.Mail(mailConnection);
+
+// Step 3: Call methods on the sub-service
+mailService.SendEmail("recipient@example.com", "Subject", "Body");
+```
+
+### Connection Types by Package
+
+| Package | Connection Class | Factory Name | Used By |
+|---------|-----------------|--------------|---------|
+| `UiPath.MicrosoftOffice365.Activities` | `MailConnection` | `O365Mail` | `office365.Mail()`, `office365.Calendar()` |
+| `UiPath.MicrosoftOffice365.Activities` | `ExcelConnection` | `Excel` | `office365.Excel()` |
+| `UiPath.MicrosoftOffice365.Activities` | `OneDriveConnection` | `OneDrive` | `office365.OneDrive()`, `office365.Sharepoint()` |
+| `UiPath.GSuite.Activities` | `GmailConnection` | `Gmail` | `google.Gmail()`, `google.Calendar()` |
+| `UiPath.GSuite.Activities` | `DriveConnection` | `GoogleDrive` | `google.Drive()` |
+| `UiPath.GSuite.Activities` | `SheetsConnection` | `GoogleSheets` | `google.Sheets()` |
+| `UiPath.GSuite.Activities` | `DocsConnection` | `GoogleDocs` | `google.Docs()` |
+
+### Important Notes
+
+- Connection names in the factory are sanitized versions of the Integration Service display name (spaces/special chars replaced with `_`)
+- The connection ID (GUID) is embedded in the factory — it references the specific Integration Service connection
+- If a connection is **not authorized** or the token is expired, you get `ConnectionHttpException: Connection [...] failed to authorize` at runtime — re-authorize in Automation Cloud → Integration Service
+- The `connections` property is always available on `CodedWorkflow` regardless of installed packages, but the factory properties (`.O365Mail`, `.OneDrive`, etc.) only exist when the corresponding package is installed and connections are configured
+
+## The `workflows` Property (Strongly-Typed Workflow Invocation)
+
+The `workflows` property provides strongly-typed access to all workflows in your project:
+
+```csharp
+// Invoke workflows with IntelliSense and compile-time checking
+var result1 = workflows.ReadInvoices(folderPath: "/data/invoices");
+var result2 = workflows.ValidateInvoices(invoices: result1.invoiceList);
+var result3 = workflows.PostToERP(validInvoices: result2.validInvoices);
+```
+
+Each workflow in your project becomes a method on the `workflows` object with parameters matching the workflow's input arguments and return values matching output arguments. This is the **recommended approach** for invoking workflows.
+
+## The `services` Property
+
+The `services` property provides access to:
+- `services.Container` — dependency injection container for resolving custom services
+- `OrchestratorClientService` (via `BuildClient`) — Orchestrator API interaction
+- `WorkflowInvocationService` (via `RunWorkflow`) — fallback for dynamic workflow invocation
+- `OutputLoggerService` (via `Log`) — logging
+
+## IRunningJobInformation Properties
+
+`GetRunningJobInformation()` returns an `IRunningJobInformation` instance (from `UiPath.Robot.Activities.Api`). Key properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `JobId` | `Guid` | Current job identifier |
+| `ProcessName` | `string` | Running process name |
+| `ProcessVersion` | `string` | Running process version |
+| `OrganizationId` | `string` | Organization identifier |
+| `TenantId` | `string` | Tenant identifier |
+| `TenantName` | `string` | Tenant display name |
+| `FolderId` | `long?` | Orchestrator folder numeric ID |
+| `FolderName` | `string` | Orchestrator folder display name |
+| `FolderKey` | `Guid` | Orchestrator folder GUID key |
+| `RobotName` | `string` | Executing robot name |
+| `UserEmail` | `string` | Logged-in user's email |
+| `InitiatedBy` | `string` | What started the job (`"Orchestrator"`, `"Studio"`, `"Assistant"`, etc.) |
+
+### Usage Example
+
+```csharp
+var jobInfo = GetRunningJobInformation();
+Log($"Org: {jobInfo.OrganizationId}, Tenant: {jobInfo.TenantName}, Folder: {jobInfo.FolderName}");
+```
+
+## Before/After Hooks (IBeforeAfterRun)
+
+Any class inheriting from `CodedWorkflow` can implement `IBeforeAfterRun` to add setup/teardown logic. Two approaches:
+
+**Per-file:** Implement directly on a workflow or test case — hooks run only for that file:
+```csharp
+public class TestLoginFlow : CodedWorkflow, IBeforeAfterRun
+{
+    public void Before(BeforeRunContext context) { Log("Starting " + context.RelativeFilePath); }
+    public void After(AfterRunContext context) { Log("Finished " + context.RelativeFilePath); }
+
+    [TestCase]
+    public void Execute() { /* Before() already ran, After() runs after */ }
+}
+```
+
+**Project-wide:** Use a `partial class CodedWorkflow` — hooks apply to every workflow and test case:
+```csharp
+// CodedWorkflowHooks.cs — Coded Source File (no entry point)
+using UiPath.CodedWorkflows;
+
+namespace MyProject
+{
+    public partial class CodedWorkflow : IBeforeAfterRun
+    {
+        public void Before(BeforeRunContext context) { Log("Starting " + context.RelativeFilePath); }
+        public void After(AfterRunContext context) { Log("Finished " + context.RelativeFilePath); }
+    }
+}
+```
+
+## Extending CodedWorkflow with Partial Classes
+
+The auto-generated `CodedWorkflow` is a `partial class`. You can extend it to add shared methods, properties, or constants available to all workflows and test cases — with or without hooks:
+
+```csharp
+// CodedWorkflowExtensions.cs — Coded Source File (no entry point)
+using UiPath.CodedWorkflows;
+
+namespace MyProject
+{
+    public partial class CodedWorkflow
+    {
+        protected string GetEnvironmentUrl()
+        {
+            var env = system.GetAsset("Environment").ToString();
+            return env == "prod" ? "https://app.example.com" : "https://staging.example.com";
+        }
+    }
+}
+```
+
+### Key Points
+
+- **`IBeforeAfterRun`** is an interface — any `CodedWorkflow`-derived class can implement it
+- **`partial class CodedWorkflow`** is a C# feature — extends the auto-generated class for all files in the project
+- **They combine:** use `partial class CodedWorkflow : IBeforeAfterRun` when you want hooks on every file
+- **Use `IBeforeAfterRun` on individual files** when only specific workflows/test cases need setup/teardown
+- **Use `partial class CodedWorkflow`** (without hooks) to add shared methods, properties, or constants
+- **Context objects** (`BeforeRunContext`, `AfterRunContext`) provide `RelativeFilePath`, `WorkflowFilePath`, etc.
+- **After() runs even on failure** — guaranteed cleanup
+
+### When to Use Which
+
+| Scenario | Pattern |
+|----------|---------|
+| One test case needs its own setup/teardown | `IBeforeAfterRun` on the class |
+| All test cases share the same setup/teardown | `partial class CodedWorkflow : IBeforeAfterRun` |
+| 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)

package/skills/uipath-rpa/references/coded/coding-guidelines.md

@@ -0,0 +1,240 @@
+# Coding Guidelines Reference
+
+Detailed coding rules, best practices, anti-patterns, and troubleshooting for UiPath 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.
+
+## 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** — [ui-automation-guide.md](../ui-automation-guide.md) MUST be read IN FULL first. Follow the **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: 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
+
+### Validation Loop (Critical Rule #14)
+uip rpa validate --file-path "<FILE>" --project-dir "<PROJECT_DIR>" --output json
+@../validation-guide.md
+
+### 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 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`
+
+### 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"** | `SelectItem` fails on web dropdowns | Use `TypeInto` instead of `SelectItem` for web `<select>` elements |
+| **`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 |

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

@@ -0,0 +1,80 @@
+# Inspect NuGet Package Tool (On-Demand API Discovery)
+
+Use this when the static reference files (`references/<service>/examples.md`) don't cover an API, when the user has a different package version, or when you need ground-truth method signatures.
+
+## 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`)