@uipath/skills 1.199.0 → 1.200.0

package/skills/uipath-rpa/references/environment-setup.md

@@ -171,7 +171,7 @@ Pass `--target-framework` and `--expression-language` here too (Rule 2a) — a t
 2. **Read the scaffolded files** — the command generates starter files. Read them before making changes so you build on valid defaults
 3. Proceed with the skill workflow using the new project root
 
-> **Batch the post-`init` prerequisites.** Step 2 here, `packages install` for known-needed packages, and the first `activities find` all depend only on the project existing — emit them as parallel tool calls in one message, not one per turn. They share the warmed Studio host. See SKILL.md § Call Batching.
+> **Batch the post-`init` prerequisites.** Step 2 here, `packages install` for known-needed packages, and the first `activities find` all depend only on the project existing — emit them as parallel tool calls in one message, not one per turn. They share the warmed Studio host. See SKILL.md § Execution Maps and [execution-maps-guide.md](execution-maps-guide.md).
 
 ## Edge case: requiring Studio Desktop
 
@@ -192,3 +192,311 @@ uip rpa studio start --project-dir "{projectRoot}" --output json   # launches St
 If `studio start` cannot resolve Studio's install directory from the registry, pass `--studio-dir` pointing to the Studio installation root.
 
 You can also force Studio Desktop for any other command by setting `UIPATH_RPA_TOOL_USE_STUDIO=1`, but this is not needed for the standard authoring loop and gives up the headless benefits.
+
+---
+
+## Project Structure Reference
+
+### Directory Layout
+
+```
+MyProject/
+├── project.json          # Project manifest (name, dependencies, settings)
+├── Main.xaml             # Default entry point (XAML mode) ─┐ typically one
+├── Main.cs               # Default entry point (coded mode) ─┘ or the other
+├── *.xaml                # Additional XAML workflow files
+├── *.cs                  # Coded workflows, test cases, and source files
+├── *.cs.json             # Auto-generated by Studio — do not create manually
+├── .codedworkflows/      # Auto-generated coded workflow support files (ConnectionsFactory.cs, ConnectionsManager.cs, ISConnections.cs, etc.)
+├── .entities/            # Data Fabric entity manifest — EntitiesStore.json. Committed; source of truth for which entities are bound to the project. Managed via uip rpa data-fabric-entities install.
+├── .local/               # Local cache (package restore, compiled artifacts)
+│   ├── install/          # Restored NuGet packages
+│   ├── docs/             # Auto-generated activity documentation
+│   │   └── packages/     # Per-package doc folders
+│   ├── .codedworkflows/  # Auto-generated (ObjectRepository.cs, CodedWorkflow.cs, WorkflowRunnerService.cs)
+│   └── .entities/        # Compiled Data Fabric entity assemblies (DataService.<Namespace>.dll) per install signature. Regenerated on demand — do not edit.
+├── .objects/             # Object Repository metadata (UI element selectors)
+├── .project/             # Project metadata
+│   ├── JitCustomTypesSchema.json  # JIT-compiled custom type definitions
+│   └── PackageBindingsMetadata.json
+├── .screenshots/         # Activity screenshots (auto-generated)
+├── .settings/            # Project-level settings
+├── .autopilot/           # Autopilot service specific files
+│   └── skills/           # Project-specific Autopilot skills
+└── .storage/             # Activity resource storage (bucket-organized)
+    ├── .design/          # Design-time only resources (NOT packed into published package)
+    │   └── <bucket>/     # Named bucket to prevent conflicts
+    └── .runtime/         # Runtime resources (packed into published NuPkg)
+        └── <bucket>/     # Named bucket with resource files
+```
+
+#### Coded-Only Elements
+
+- `.cs` files with `[Workflow]`/`[TestCase]` attributes — executable coded automations
+- `.cs.json` metadata files — auto-generated by Studio for each coded workflow/test case (do not create manually)
+- `.codedworkflows/` — auto-generated support files (only when project has `.cs` files)
+- `.local/.codedworkflows/` — auto-generated `ObjectRepository.cs`, `CodedWorkflow.cs`, etc.
+- `.variations/` — data-driven test parameters (Tests projects only)
+
+#### XAML-Only Elements
+
+- `.xaml` workflow files — visual workflow definitions
+- Expression language configured in `project.json` (`VisualBasic` or `CSharp`)
+
+### project.json Key Fields
+
+```json
+{
+  "name": "MyProject",
+  "description": "",
+  "main": "Main.xaml",
+  "dependencies": {
+    "UiPath.System.Activities": "[24.12.1]"
+  },
+  "schemaVersion": "4.0",
+  "studioVersion": "25.0.0.0",
+  "projectVersion": "1.0.0",
+  "runtimeOptions": {
+    "autoDispose": false,
+    "netFramework": { "targetFramework": "net6.0-windows" },
+    "isPausable": true,
+    "isAttended": false,
+    "requiresUserInteraction": false
+  },
+  "designOptions": {
+    "projectProfile": "Developement",
+    "outputType": "Process",
+    "libraryOptions": {
+      "includeOriginalXaml": false,
+      "privateWorkflows": []
+    }
+  },
+  "expressionLanguage": "VisualBasic",
+  "entryPoints": [
+    {
+      "filePath": "Main.xaml",
+      "uniqueId": "2f510550-3882-4340-9239-53a24d0717f6",
+      "input": [],
+      "output": []
+    }
+  ],
+  "targetFramework": "Windows"
+}
+```
+
+#### Important Fields
+
+| Field | Description |
+|-------|-------------|
+| `name` | Project name (used in package output) |
+| `main` | Entry point workflow file (relative path) |
+| `dependencies` | NuGet package dependencies with version constraints |
+| `expressionLanguage` | `CSharp` or `VisualBasic` — determines expression syntax in XAML. Default `VisualBasic`. Immutable after creation (decide at init — SKILL.md Rule 2a) |
+| `designOptions.outputType` | `Process`, `Library`, or `Tests` |
+| `targetFramework` | `Windows` (.NET 6 Windows-only), `Portable` (Cross-platform .NET 6+), or `Legacy` (Windows - Legacy, .NET Framework 4.6.1). Set explicitly at init (Rule 2a); omitting `--target-framework` yields `Windows` |
+| `entryPoints` | Per-workflow metadata: filePath, uniqueId, input/output definitions (**Process projects only** — Tests and Library projects use empty `[]`) |
+
+### Rules
+
+1. **Use CLI for dependencies**: Always use `uip rpa packages install` to add/update dependencies. Do not manually edit `dependencies` in `project.json`.
+2. **Do not edit `.local/` or `.objects/`**: These are cache directories managed by the build system.
+3. **`main` entry point**: The default entrypoint that gets run if not specified otherwise. `entryPoints` array is only populated for **Process** projects — Tests and Library projects leave it empty (`[]`).
+4. **`--project-dir` awareness and project creation**: [§ Step 0.1](#step-01-establish-project-root) and [§ Step 0.3](#step-03-creating-a-new-project) above.
+
+### Common Activity Packages
+
+| Package ID | Description | Key Activities |
+|------------|-------------|----------------|
+| `UiPath.System.Activities` | Core system activities | Assign, If, ForEach, While, Invoke Workflow, Log Message, Delay |
+| `UiPath.UIAutomation.Activities` | UI interaction | Click, Type Into, Get Text, Open Browser, Use Application/Browser |
+| `UiPath.Excel.Activities` | Excel automation | Read Range, Write Range, Read Cell, Write Cell, Format Range |
+| `UiPath.Mail.Activities` | Email operations | Send Mail, Get Mail, Save Attachments, Forward Mail |
+| `UiPath.Database.Activities` | Database operations | Execute Query, Execute Non Query, Connect, Disconnect |
+| `UiPath.WebAPI.Activities` | HTTP/REST calls | HTTP Request, Deserialize JSON, Serialize JSON |
+| `UiPath.PDF.Activities` | PDF processing | Read PDF Text, Read PDF with OCR, Extract Data From PDF |
+| `UiPath.Word.Activities` | Word automation | Read Text, Replace Text, Insert Image, Export to PDF |
+| `UiPath.Testing.Activities` | Testing and assertions | Verify Expression, Verify Are Equal, Generate Test Data |
+| `UiPath.Presentations.Activities` | PowerPoint automation | Add Slide, Replace Text, Insert Image |
+| `UiPath.IntegrationService.Activities` | Integration Service connector runtime | Generic connector activities for Salesforce, ServiceNow, HubSpot, etc. |
+| `UiPath.Cryptography.Activities` | Encryption/hashing | Encrypt Text, Decrypt Text, Hash File |
+
+### Version Constraints
+
+Dependencies use NuGet version constraint syntax:
+
+| Syntax | Meaning |
+|--------|---------|
+| `[1.0.0]` | Exact version 1.0.0 |
+| `[1.0.0, )` | Version 1.0.0 or higher |
+| `[1.0.0, 2.0.0)` | Between 1.0.0 (inclusive) and 2.0.0 (exclusive) |
+
+---
+
+## Designing Project Structure
+
+When creating a project, **proactively design the right file structure** based on the task complexity. Do not put everything into a single root workflow file. Use your best judgment to split the project into multiple files following good software engineering practices.
+
+For the coded vs XAML decision, see [coded-vs-xaml-guide.md](coded-vs-xaml-guide.md). For new projects, the default is XAML — examples below lead with XAML and note where the coded equivalent differs.
+
+### Guidelines
+
+- **Single simple task** (e.g. "read a CSV and log it") — one workflow file (`Main.xaml` for XAML projects, `Main.cs` for coded) is fine
+- **Multi-step process** (e.g. "read invoices, validate, post to system") — split into multiple workflow files, each handling one step. The root workflow invokes each step
+- **Shared data structures** — extract into a Coded Source File (e.g. `Models.cs`, `InvoiceData.cs`). XAML cannot define types, so a Coded Source File is the right home even in an otherwise XAML project
+- **Repeated logic** — in XAML projects, extract into a reusable XAML workflow. In coded or hybrid projects, extract into a helper Coded Source File (e.g. `ValidationHelpers.cs`)
+- **Test project** — one test case per scenario. Coded test projects optionally use `partial class CodedWorkflow : IBeforeAfterRun` in `CodedWorkflowHooks.cs` for shared setup. XAML test projects use Test Activities for shared setup
+- **Complex domain logic** — isolate business rules so they can be unit-tested and reused (Coded Source File for typed logic, or a separate workflow for activity-driven logic)
+
+### Designing for Reuse
+
+Structure decisions that keep components extractable later.
+
+#### Single responsibility
+
+One workflow file = one meaningful action, named for it (`ProcessInvoice.xaml`, `LoginToApplication.xaml`). Split a workflow when it exceeds ~20-30 activities.
+
+#### Standard folder shape
+
+For multi-step processes, organize by layer:
+
+```
+Project/
+├── Main.xaml              # High-level orchestration only
+├── Framework/             # Init, cleanup, error handling, app open/close
+├── BusinessLogic/         # Process-specific rules and transactions
+├── Utilities/             # Process-agnostic helpers (formatters, screenshots)
+└── Data/                  # Config files, templates
+```
+
+#### Separate business logic from UI components
+
+UI workflows interact with applications and carry zero business rules; business-logic workflows decide and never touch the UI. Make read and write distinct invocable components — `GetCustomerInfo.xaml` and `ChangeCustomerInfo.xaml`, not one `HandleCustomer.xaml`. When the target application's UI changes, only the UI workflows need fixing; when a business rule changes, the UI workflows are untouched. Process-agnostic UI components are also the ones worth promoting to a shared library later.
+
+#### Composition and argument naming
+
+Compose via `Invoke Workflow File` (coded: `workflows.StepName()`). Process workflow arguments use directional prefixes — `in_InvoiceId`, `out_Result`, `io_Browser` — so data flow is visible at every invocation site. Exception: library public workflows drop the prefixes ([library-authoring-guide.md § The Public-Workflow Contract](library-authoring-guide.md)).
+
+#### Layout and scale-out
+
+- Sequence vs Flowchart vs State Machine per workflow: Workflow Types table in SKILL.md § XAML Workflows Quick Reference
+- High-volume transactional work: dispatcher/performer split via queues — [reframework-guide.md § Execution Mode: Queue-Driven](reframework-guide.md)
+
+#### Promotion ladder
+
+Promote logic only as reuse materializes:
+
+1. **Inline** — used once in one workflow
+2. **Separate workflow file** — reused within the project
+3. **Shared library** — reused across projects ([library-authoring-guide.md](library-authoring-guide.md))
+4. **UI Library** — selectors shared across projects ([uia-starter-guide.md § Object Repository as a Published UI Library](uia-starter-guide.md#object-repository-as-a-published-ui-library))
+
+### Example — Invoice Processing Project (XAML)
+
+```
+InvoiceProcessor/
+├── project.json
+├── Main.xaml                  # Root workflow: sequences each step via Invoke Workflow File
+├── ReadInvoices.xaml          # Step 1: reads invoices from Excel
+├── ValidateInvoices.xaml      # Step 2: validates data
+├── PostToERP.xaml             # Step 3: posts to external system
+└── InvoiceData.cs             # Coded source file: typed data model used across XAML steps
+```
+
+`Main.xaml` invokes each step via `Invoke Workflow File`, passing arguments In/Out. `InvoiceData.cs` is included even in this otherwise-XAML project because XAML cannot define types — typed DTOs eliminate `DataTable` column-name guessing.
+
+#### Coded equivalent
+
+```
+InvoiceProcessor/
+├── project.json
+├── Main.cs                    # Root workflow: calls each step via workflows.StepName()
+├── ReadInvoices.cs            # Step 1
+├── ValidateInvoices.cs        # Step 2
+├── PostToERP.cs               # Step 3
+├── InvoiceData.cs             # Coded source file: data model
+└── ValidationHelpers.cs       # Coded source file: validation utilities
+```
+
+`Main.cs` uses strongly-typed workflow invocation:
+
+```csharp
+[Workflow]
+public void Execute(string inputFolder)
+{
+    var readResult = workflows.ReadInvoices(folderPath: inputFolder);
+    Log($"Read {readResult.count} invoices");
+
+    var validateResult = workflows.ValidateInvoices(invoices: readResult.invoiceList);
+    Log($"Valid: {validateResult.validCount}, Invalid: {validateResult.invalidCount}");
+
+    var postResult = workflows.PostToERP(validInvoices: validateResult.validInvoices);
+    Log($"Posted {postResult.successCount} invoices to ERP");
+}
+```
+
+### Example — Test Project
+
+```
+InvoiceTests/
+├── project.json
+├── CodedWorkflowHooks.cs      # Coded test projects only: partial class CodedWorkflow with Before/After hooks
+├── TestLoginFlow.cs           # Test case: login scenario (hooks apply automatically via partial class merge)
+├── TestInvoiceCreation.cs     # Test case: create invoice scenario
+├── TestInvoiceValidation.cs   # Test case: validation rules
+└── TestData.cs                # Source file: shared test constants/fixtures
+```
+
+XAML test projects use `.xaml` test cases instead of `.cs` and Test Activities for shared setup; the rest of the layout is the same.
+
+### Example — Hybrid Project (XAML Root + Coded Logic)
+
+```
+OrderProcessing/
+├── project.json
+├── Main.xaml                  # XAML root workflow: sequences steps, handles retries
+├── ScrapeOrderPortal.xaml     # XAML: UI automation with visual selector builder
+├── SendConfirmationEmail.xaml # XAML: Mail activities (straightforward)
+├── ProcessOrder.cs            # Coded workflow: 12 validation rules + LINQ transforms
+├── OrderModels.cs             # Coded source file: Order, LineItem, ValidationResult DTOs
+├── TransformHelpers.cs        # Coded source file: date parsing, currency conversion
+└── TestProcessOrder.cs        # Coded test case: unit tests for ProcessOrder logic
+```
+
+#### Why hybrid here
+
+- **ScrapeOrderPortal.xaml** — UI automation benefits from XAML's visual selector builder and recording tools
+- **ProcessOrder.cs** — Order validation has 12 business rules with nested conditions; coded C# is clearer and testable
+- **OrderModels.cs** — Typed DTOs used by both XAML (via typed arguments) and coded workflows, eliminating DataTable column-name guessing
+- **SendConfirmationEmail.xaml** — Simple Mail activity, no logic — XAML is the simpler choice
+- **Main.xaml** — Orchestration is linear (scrape → process → email); XAML Sequence is readable
+
+#### Data flow
+
+1. `Main.xaml` invokes `ScrapeOrderPortal.xaml` → returns `DataTable` via Out argument
+2. `Main.xaml` invokes `ProcessOrder.cs` via Invoke Workflow File → passes raw data, returns validated `Order` objects
+3. `Main.xaml` invokes `SendConfirmationEmail.xaml` → passes validated order data
+
+### Project Structure Decision Tree
+
+**First — coded or XAML?** For new projects, default to XAML unless the user explicitly said "coded" or named a coded-specific trigger (custom data models, complex algorithms, unit tests on business logic). See [coded-vs-xaml-guide.md](coded-vs-xaml-guide.md). The root workflow is `Main.xaml` for XAML projects and `Main.cs` for coded projects — substitute accordingly below.
+
+**Is it a single, simple task?**
+- ✅ Yes → Single root workflow
+
+**Is it a multi-step process?**
+- ✅ Yes → A root workflow that invokes each step + separate workflow files for each step
+
+**Does it involve repeated data structures?**
+- ✅ Yes → Extract to Coded Source File (e.g. `Models.cs`, `InvoiceData.cs`). Required even in XAML projects — XAML cannot define types
+
+**Is there shared logic across workflows?**
+- ✅ Yes → Extract to a reusable XAML workflow (XAML projects) or a helper Coded Source File (coded or hybrid projects)
+
+**Is it a test project?**
+- ✅ Yes → One test case file per scenario. Coded test projects optionally use `CodedWorkflowHooks.cs` (partial class CodedWorkflow) for shared setup/teardown
+
+**Does it have complex business rules?**
+- ✅ Yes → Isolate in Coded Source Files for reusability and testability (extract from XAML via `Invoke Workflow File` if needed)
+
+**Does it need both UI automation AND complex non-UI logic?**
+- ✅ Yes → Hybrid: XAML for UI automation + orchestration, Coded for business logic + data models. See [coded-vs-xaml-guide.md](coded-vs-xaml-guide.md)

package/skills/uipath-rpa/references/error-handling-guide.md

@@ -358,7 +358,7 @@ catch (Exception ex)         { Log(ex.ToString(), LogLevel.Error); throw; }
 
 - `throw;` (bare) preserves the stack trace; `throw ex;` resets it — same `CA2200` rule as Rethrow vs Throw-new.
 - Workflow Analyzer rules (`ST-DBP-003`, etc.) apply to `.cs` workflows too.
-- Retry: a plain `for` loop with `try/catch` and a delay, or call a Retry Scope from XAML. C# expression-binding mechanics for XAML activities: [xaml/csharp-activity-binding-guide.md](xaml/csharp-activity-binding-guide.md); coded `using` directives: [coded/coding-guidelines.md](coded/coding-guidelines.md).
+- Retry: a plain `for` loop with `try/catch` and a delay, or call a Retry Scope from XAML. C# expression-binding mechanics for XAML activities: [xaml/csharp-activity-binding-guide.md](xaml/csharp-activity-binding-guide.md); coded `using` directives: [coded/operations-guide.md § Using Statements Rules](coded/operations-guide.md#using-statements-rules).
 
 ---
 

package/skills/uipath-rpa/references/execution-maps-guide.md

@@ -0,0 +1,110 @@
+# Execution Maps — Turn-Budgeted Build Journeys
+
+One dense file, read once per build. Fixes which tool calls go in which assistant turn. Budgets (happy path, incl. final report): **greenfield ≤5 turns, brownfield ≤4**. One repair cycle adds ≤2. Each T-row = ONE assistant message: N tool calls in one message cost 1 turn, one call per message costs N.
+
+> **Tool vocabulary.** Tool names use Claude Code conventions: `Edit` = in-place string replacement, `Write` = full-file write, `Read`/`Glob`/`Grep` = file read/search, `Bash` = shell. On another harness, map each to its equivalent. Harness cannot emit parallel tool calls → keep the same per-turn grouping as consecutive calls; the CLI chains still collapse round-trips.
+
+## Source precedence — every activity you author
+
+1. **Card** — [common-activity-card.md](common-activity-card.md), [common-pattern-card.md](common-pattern-card.md)
+2. **Agent memory** — validated snippet from a prior session (see [§ Cross-session memory](#cross-session-memory))
+3. **Rule 21 triple** — `activities find` → `<Activity>.md` read → `get-default-xaml`, fanned out inside T1/T2
+
+`validate` + `build` gate all three. Card/memory hits skip discovery, never the gate.
+
+## Gate ≠ runtime proof
+
+A clean `validate` + `build` does NOT prove runtime behavior. Known silent failures pass BOTH: `InvokeCode` `Code` in child/CDATA form no-ops, `WriteTextFile` with explicit `Encoding` emits a BOM, a stripped UIA `N*` `Version` fails only at runtime ([xaml/common-pitfalls.md](xaml/common-pitfalls.md)). When the deliverable has observable outputs (files written, entry-point out-arguments) and runs without external systems or UI, the gate turn ends with ONE `uip rpa run` and the report turn checks the actual outputs — see the T3/T4 rows below.
+
+## Sequential gates — never batch across these
+
+- `templates search` → `init` (Rule 2): runs only when the user names a template or domain pattern; its result (possibly an `AskUserQuestion`) picks `--template-package-id`.
+- Rule 2a framework/language question when the request carries no signal.
+- Any `AskUserQuestion` or consent gate.
+- UIA state advances and indication (see [§ Journey: UIA capture + build](#journey-uia-capture--build-xaml)) — capture screens are gated by real application state.
+
+## Journey: Greenfield XAML (no UIA)
+
+Skip the project-discovery subagent — nothing to discover yet (SKILL.md § Skip gate: no `project.json` before T1, only the untouched scaffold after it). Write `project-context.md` + `AGENTS.md` yourself at T4.
+
+| Turn | Emit in ONE assistant message |
+|---|---|
+| **T1 — Scaffold + context** | ONE `Bash` chain: `uip rpa init --name "<NAME>" --location "<PARENT_DIR>" --template-id BlankTemplate --expression-language <VisualBasic\|CSharp> --target-framework <Windows\|Portable> --output json` (Rule 2a — both flags explicit) `&&` `uip rpa analyzer-rules list --project-dir "<PROJECT_DIR>" --output json` `&&` one `uip rpa packages versions --package-id <PackageId> --include-prerelease --project-dir "<PROJECT_DIR>" --output json` per request-known package ∥ parallel `Read` — ALL THREE, never a subset (skipping the pattern card re-opens per-activity discovery): [common-activity-card.md](common-activity-card.md), [common-pattern-card.md](common-pattern-card.md), [xaml/xaml-basics-and-rules.md](xaml/xaml-basics-and-rules.md) (Rule 22) ∥ memory recall (harness has memory) ∥ Rule 21 `activities find` fan-out for off-card activities |
+| **T2 — Author + install** | Design fork FIRST for row-processing tasks: complex bulk row processing (per-row parse + validate + branch + accumulate) escalates to code per [data-manipulation-guide.md § Code vs activity chains](data-manipulation-guide.md) — the pattern card's `ForEach` shapes cover only the simple one-`If`/`Switch` case. Then: one `Write` per workflow file — complete, all activities (Rule 18) ∥ `Read` `project.json` (anchors for the T2/T3 edits; skip re-reading scaffolded `Main.xaml` — the `Write` replaces it) ∥ `Edit` `project.json` (`fileInfoCollection` for test cases, Rule 10; `dependencies` stays CLI-owned via `packages install`) ∥ ONE `Bash`: `uip rpa packages install` for all needed packages at the T1-chosen versions — flag shape per [cli-reference.md § packages install](cli-reference.md#packages-install); it drifts across CLI builds, so on `Invalid packages input` re-check `uip rpa packages install --help` ∥ Rule 21 doc `Read`s + `get-default-xaml` for off-card activities |
+| **T3 — Gate** | ONE `Bash`: `uip rpa validate --file-path "<RELATIVE_FILE>" --project-dir "<PROJECT_DIR>" --output json` per file `&&` `uip rpa build "<PROJECT_DIR>" --output json` `&&` — when outputs are observable and no external system/UI is needed — `uip rpa run` on the entry point (§ Gate ≠ runtime proof). `--file-path` RELATIVE to project dir — absolute paths falsely fail (separator bug, [cli-reference.md § validate](cli-reference.md#validate)) |
+| **T4 — Report** | Check the T3 run's actual outputs against the request (files, out-arguments) BEFORE reporting — wrong/empty output with a clean gate is a silent-failure signature (§ Failure exits) + § Completion Output + write `project-context.md`/`AGENTS.md` + memory save ([§ Cross-session memory](#cross-session-memory)) |
+
+- First chain call pays the cold Helm restore (30–90 s) — the chain hides it behind one turn; do not split to "check progress".
+- `init` can return `success: false` yet create files (partial success) — before retrying, check `project.json` exists ([environment-setup.md](environment-setup.md)).
+- Dependencies land via `packages install` only — never hand-edit `project.json` `dependencies`.
+
+**Repair cycle (validate/build failure):** one turn — `Edit` fixes by error category (Rule 19 — Package first: a skipped `packages install` fails the gate before any activity issue); a gate failure on a card-covered activity does NOT reopen discovery (`activities find`/`get-default-xaml`) — recheck the card entry; next turn — re-run the T3 chain. >2 errors with ambiguous origin → bisect: stub out half the new activities, re-validate. Caps: 5 attempts per loop (Rule 3).
+
+## Journey: Brownfield XAML edit
+
+| Turn | Emit in ONE assistant message |
+|---|---|
+| **T1 — Context** | § Precondition context check — § Skip gate first, then the discovery subagent, which writes `project-context.md` + `AGENTS.md` itself ∥ `Read` `project.json` + target `.xaml` + cards ∥ ONE `Bash`: `analyzer-rules list --project-dir "<PROJECT_DIR>" --output json` ∥ memory recall ∥ off-card `activities find` fan-out |
+| **T2 — Edit** | Batched `Edit`s (anchor each on its own target block — same-file Edits serialize; overlapping anchors fail) ∥ `packages install` `Bash` if new dependencies |
+| **T3 — Gate** | ONE `Bash`: per-file `validate` (relative `--file-path`) `&&` `build` `&&` optional `run` per § Gate ≠ runtime proof |
+| **T4 — Report** | Output check (if T3 ran) + § Completion Output + memory save |
+
+## Journey: Greenfield coded
+
+`init` always scaffolds XAML — same command as above; coded mode = add `.cs` files after ([environment-setup.md](environment-setup.md)).
+
+| Turn | Emit in ONE assistant message |
+|---|---|
+| **T1 — Scaffold + context** | ONE `Bash` chain: `init` (flags as XAML journey) `&&` `analyzer-rules list` `&&` `packages versions` per known package ∥ `Read` [assets/codedworkflow-template.md](../assets/codedworkflow-template.md) + [coded/operations-guide.md § Coding Guidelines](coded/operations-guide.md#coding-guidelines) ∥ memory recall |
+| **T2 — Author + install** | `Write` each `.cs` (Rules 13–19) ∥ `Read` `project.json` ∥ `Edit` `project.json` (`entryPoints` Rule 15, `fileInfoCollection` Rule 10) ∥ `packages install` `Bash` ∥ `Read` `.local/docs/packages/<PackageId>/coded/coded-api.md` for installed services |
+| **T3 — Gate** | ONE `Bash`: per-file `validate` (relative `--file-path`) `&&` `build` `&&` optional `run` per § Gate ≠ runtime proof |
+| **T4 — Report** | Output check (if T3 ran) + § Completion Output + memory save |
+
+## Journey: Brownfield coded edit
+
+Brownfield XAML journey with coded reads: T1 `Read` target `.cs` + `.local/docs/.../coded/coded-api.md` for touched services; T2 `Edit`s ∥ install; T3 gate; T4 report.
+
+## Journey: UIA capture + build (XAML)
+
+Budget shape: **~3 fixed turns + ~3 turns per capture-screen + 2-turn debug cycle.** Capture is serialized ACROSS screens by application state (Complete-then-advance — the target-capture orchestration reference, routed from the UIA package guide) — never try to batch across an advance. Concrete UIA CLI syntax is package-owned — route from the package guide (`{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/ui-automation-guide.md` § Documentation).
+
+| Turn | Emit in ONE assistant message |
+|---|---|
+| **T0 — Reads + pre-flight** | Parallel `Read`: [uia-starter-guide.md](uia-starter-guide.md) + the UIA package guide (Rule 7, both in full) + the target-capture orchestration reference it mandates ∥ prerequisites check (SKILL.md § UIA Prerequisites, Rule 7a) ∥ ONE `Bash`: window baseline via the UIA snapshot CLI ∥ build the element inventory/checklist from the user's manual steps |
+| **Per capture-screen** | (a) capture bundle — run the `uia-configure-target` flow for ALL of this screen's checklist elements in one pass, through OR registration; (b) ONE state advance via the interact CLI — only to reach the next screen, never to test behavior |
+| **T-author — after ALL screens captured** | Scaffold/authoring prerequisites (Capture-First Fast Path order) ∥ batch-author every screen's activities in one pass (Rule 18), embed path for OR target attachment |
+| **T-gate** | ONE `Bash`: per-file `validate` (relative `--file-path`) `&&` `build` |
+| **Debug cycle (consent-gated, [uia-starter-guide.md § Running UI Automation Workflows](uia-starter-guide.md))** | ONE `Bash` chain: window baseline `&&` `debug start` `&&` `execution cancel` `&&` re-list windows; next turn: diff, close stray windows via the interact CLI, report |
+
+- Default is author-once-after-capture — all OR refs are already in conversation. Fall back to per-screen authoring interleave only on long captures (5+ screens) where context pressure is real; the `validate`/`build` gate still runs ONCE at the end either way.
+- Screens after the first (same window): carry the OR screen reference from the previous capture into the next `uia-configure-target` invocation — it skips the OR screen lookup. Invocation shape and argument: the package's `uia-configure-target` invocation guide (routed from the package guide § Documentation).
+- Indication fallback (user physically clicks) and every interact advance are sequential gates — never batched, never parallel.
+- Selector failures at debug time → the `uia-improve-selector` flow (never hand-edit selectors).
+
+## Failure exits
+
+| Symptom | Open |
+|---|---|
+| `validate` structural/reference errors | [cli-reference.md § Validation Iteration Loop](cli-reference.md#validation-iteration-loop) |
+| XAML activity gotcha (property conflicts, scope) | [xaml/common-pitfalls.md](xaml/common-pitfalls.md) |
+| Gate clean but runtime output wrong/empty | [xaml/common-pitfalls.md](xaml/common-pitfalls.md) silent-failure sections: § InvokeCode Code Property — Attribute Form Only, § WriteTextFile Emits a UTF-8 BOM, § UIA `N*` Activities Carry a `Version` |
+| Coded `CS*` errors | [coded/operations-guide.md § Common Issues and Fixes](coded/operations-guide.md#common-issues-and-fixes) |
+| CLI error (`timeout`, `EPIPE`, `401`, `not in the project folder`) | [cli-reference.md § CLI Error Recovery](cli-reference.md#cli-error-recovery) |
+| Card snippet rejected by validate/build | Fall back to Rule 21 triple for that activity; report stale entry via `/uipath-feedback` |
+| UIA selector fails at debug time | `uia-improve-selector` flow per [uia-starter-guide.md § Runtime Selector Failure Recovery](uia-starter-guide.md#runtime-selector-failure-recovery) — never hand-edit |
+
+## Cross-session memory
+
+Harness-conditional: engage only when the harness provides persistent memory; otherwise skip silently.
+
+**Recall — T1 of every journey.** Match saved entries by activity class + package `major.minor`. Hit ⇒ that activity skips the Rule 21 triple. `validate`/`build` still gate.
+
+**Save — after project `build` is clean (T4).** Save only:
+
+1. Validated XAML snippet per off-card activity — key: activity class + package `major.minor` + date.
+2. Error→root-cause→fix triples that cost >1 validate attempt.
+3. Cross-version package gotchas.
+
+**Never save:** project-specific facts (paths, asset names, connections — belong in `project-context.md`), UIA selectors/targets/OR references (per-app), UIA CLI syntax (package-owned, co-versioned), secrets. Process-level UIA lessons (e.g., a failure mode and its fix direction) MAY be saved.
+
+**Expiry:** recalled snippet fails validation → delete/overwrite that entry, fall back to Rule 21 triple.

package/skills/uipath-rpa/references/is-connector-xaml-guide.md

@@ -10,6 +10,19 @@ End-to-end playbook for building a headlessly-runnable IS `ConnectorActivity` XA
 
 **Prefer this over per-product BAF activity packages** (`UiPath.Slack.Activities`, etc.). Those wrap IS internally and use a more complex BAF (Business Activity Framework) XAML shape that is equally fragile to hand-author. The IS `ConnectorActivity` flow below is schema-driven and mechanical.
 
+## Connector Discovery Commands
+
+Explore the connector before writing XAML (requires `uip login` — see Prereq below):
+
+```bash
+uip is connectors list --output json                                # connector keys available to the tenant
+uip is activities list <connector-key> --output json                # activity names + method + operation
+uip is resources list <connector-key> --output json                 # data objects/resources exposed
+uip is resources describe <connector-key> <object-name> --operation Create --output json   # field schema
+```
+
+`resources describe` is the authoritative field schema — full usage in [Step 5](#step-5--read-the-operations-field-schema).
+
 ## Activity Shape
 
 ```xml
@@ -98,6 +111,8 @@ uip is connections list <connector-key> --output json           # list tenant's
 
 If none exist: `uip is connections create <connector-key>` (interactive OAuth). If that can't be done in-session, use a placeholder `00000000-0000-0000-0000-000000000000` and flag it for the user — but the workflow will fail at runtime until a real connection is wired up.
 
+**Verify a connection is active:** `uip is connections ping <connection-id>`. If the ping fails, offer to re-authenticate with `uip is connections edit <connection-id>` (re-runs the OAuth flow for expired/revoked connections).
+
 ### Step 4 — Get the fully-populated default XAML
 
 **This is the unlock step.** With both the type ID and connection ID:
@@ -296,6 +311,30 @@ uip rpa run --file-path "<your-workflow>.xaml" --project-dir "<PROJECT_DIR>" --o
 
 If `HasErrors: true`, the `ErrorMessage` field carries the compile/runtime error.
 
+## ConnectorActivity Editing Rules
+
+What you may and may not touch on an existing `ConnectorActivity`:
+
+| Property | Editable? | Description |
+|----------|-----------|-------------|
+| `Configuration` | **NEVER** | Opaque blob (see Activity Shape above). Obtained only from `activities get-default-xaml`. |
+| `ConnectionId` | Yes (replace GUID) | Swap to a different connection of the same connector type (`uip is connections list`). |
+| `UiPathActivityTypeId` | **NEVER** | Identifies the connector operation. |
+| `DisplayName` | Yes | Human-readable designer name. |
+
+**In `FieldObjects` you CAN:** change input field values inside `FieldObject.Value` (literal or `<CSharpValue>` variable binding).
+
+**You CANNOT:** change field `Name` or `Type` values (schema-defined), alter output field structure (JIT-typed), or add/remove `FieldObject` entries (the set comes from `get-default-xaml` — see § Hidden Secondary Fields for the expansion path).
+
+**JIT-generated assembly names** on output types are unpredictable and connection-specific:
+
+```
+CDF573A04A6_search_r.VeKd1XI2qK1X56UO2Br3Ui3
+^connection(last10)   ^operation   ^content hash
+```
+
+They are derived from SHA-512 hashes of the type schema and generated by the runtime — the corresponding namespace imports and assembly references MUST come from `activities get-default-xaml` output. Never construct them.
+
 ## Operation output is strongly typed
 
 The operation's result is exposed as an output FieldObject named `Jit_<operation>`, typed to a **generated record type** for that object — so downstream expressions that read its members (`record.id`, `records.First().name`) compile, and `uip rpa build` binds the consuming variable to the right type.
@@ -385,7 +424,23 @@ The returned `Configuration` blob now carries the expanded schema, and the previ
 
 ## Gotchas
 
-1. **JIT OutArgument corruption** — When Studio's designer modifies an IS XAML, it can inject a `<OutArgument x:TypeArguments="uiascb:...<op>_Create" />` into the `Jit_<operation>` FieldObject that references a dynamically-compiled Studio-local assembly. Fresh loads (new Studio session, CI) can't resolve that type and fail to compile with `Unable to create activity builder`. **Strip the offending OutArgument back to `<isactr:FieldObject Name="Jit_<op>" Type="FieldArgument" />`** before shipping or running headlessly. Also remove the `xmlns:uiascb` namespace declaration from the root `<Activity>` element if nothing else references it. Tracked as PILOT-4812.
+1. **JIT OutArgument corruption** — When Studio's designer modifies an IS XAML, it can inject a JIT-typed `OutArgument` into the `Jit_<operation>` FieldObject that references a dynamically-compiled Studio-session-local assembly:
+
+   ```xml
+   <isactr:FieldObject Name="Jit_send_message_to_channel_v2" Type="FieldArgument">
+     <isactr:FieldObject.Value>
+       <OutArgument x:TypeArguments="uiascb:send_message_to_channel_v2_Create" />
+     </isactr:FieldObject.Value>
+   </isactr:FieldObject>
+   ```
+
+   On any **fresh load** (new Studio session, Helm, CI) that assembly doesn't exist and compile fails with `Unable to create activity builder ... Cannot create unknown type '{...}OutArgument({...}<op>_Create)'`. **Strip the injected OutArgument back to bare form** before shipping or running headlessly:
+
+   ```xml
+   <isactr:FieldObject Name="Jit_send_message_to_channel_v2" Type="FieldArgument" />
+   ```
+
+   Also remove the `xmlns:uiascb` namespace declaration from the root `<Activity>` element if nothing else references it. Tracked as PILOT-4812.
 2. **Connector-backend errors surface at runtime, not validation** — Things like `channel_not_found`, `not_authed`, rate-limit failures etc. are returned by the connector's backend after the activity calls out. They appear in the `ErrorMessage` of an actual run (with `HasErrors: true`) or in streamed log entries from the workflow's own logging, never from `validate`. Validation can only tell you the XAML is structurally correct and the connection slot is filled — not that the target entity exists or that the bot has permission.
 
 3. **Configuration blob's `ConnectorKey` may be a mock/template — it is not routing metadata** — Decompressing the Configuration blob can reveal `"ConnectorKey": "uipath-mock-<something>"` even when you're targeting the real production connector (e.g. `uipath-microsoft-outlook365`). The typeId encodes the *operation schema*; the `ConnectionId` attribute determines which backend actually gets called at runtime. Don't try to "correct" the blob — it's baked, and any edit invalidates it (`Configuration contains a breaking change`). A mismatch between `ConnectorKey` in the blob and the connection's connector is expected for connectors that share schemas (mocks, legacy vs. v2, etc.) and is not an error.
@@ -405,6 +460,5 @@ The returned `Configuration` blob now carries the expanded schema, and the previ
 
 ## Related References
 
-- [connector-capabilities.md](connector-capabilities.md) — connection lifecycle commands (list, create, ping, edit).
-- [xaml/workflow-guide.md § Step 1.9](xaml/workflow-guide.md) — where this flow slots into the overall XAML phase structure.
-- [xaml/common-pitfalls.md § IS ConnectorActivity](xaml/common-pitfalls.md) — JIT OutArgument, `Configuration` blob opacity, schema-driven field names.
+- [xaml/xaml-basics-and-rules.md § Step 1.9](xaml/xaml-basics-and-rules.md) — where this flow slots into the overall XAML phase structure.
+- [xaml/common-pitfalls.md § Connection Service Pattern](xaml/common-pitfalls.md) — `ConnectionId` requirements for BAF-scope activities (O365/GSuite).

package/skills/uipath-rpa/references/legacy/activity-docs/Excel.md

@@ -19,7 +19,7 @@ Excel automation with three access modes: Portable (file-based, no Excel require
 
 **CRITICAL: Cannot mix patterns in same workflow**
 
-**CRITICAL: Scope activities require `ActivityAction<T>` body** — you cannot place child activities directly inside `ExcelApplicationScope`, `ExcelProcessScopeX`, or `ExcelApplicationCard`. Each requires a `.Body` property containing `ActivityAction` with a `DelegateInArgument`. See [common-pitfalls.md](../common-pitfalls.md#scope-activities-require-activityaction-body-critical-for-xaml-generation) for the complete XAML template and all scope body patterns.
+**CRITICAL: Scope activities require `ActivityAction<T>` body** — you cannot place child activities directly inside `ExcelApplicationScope`, `ExcelProcessScopeX`, or `ExcelApplicationCard`. Each requires a `.Body` property containing `ActivityAction` with a `DelegateInArgument`. See [xaml-basics-and-rules.md](../xaml-basics-and-rules.md#scope-activities-require-activityaction-body-critical-for-xaml-generation) for the complete XAML template and all scope body patterns.
 
 ---
 

package/skills/uipath-rpa/references/legacy/activity-docs/_DU-PROCESS.md

@@ -335,6 +335,4 @@ Supported languages: 26 (EN, DE, FR, ES, RU, ZH, JA, etc.)
 
 ## Sources
 - [UiPath Docs - Document Understanding Process Template](https://docs.uipath.com/document-understanding/automation-suite/2024.10/classic-user-guide/du-process)
-- [UiPath Forum - DU Process Template Announcement](https://forum.uipath.com/t/document-understanding-process-new-studio-template/330234)
 - [UiPath Docs - About DU Process](https://docs.uipath.com/activities/other/latest/document-understanding/about-document-understanding-process-studio-template)
-- Desktop template: `C:\Users\alexandru.roman\Documents\UiPath\legacy_tests\DocumentUnderstandingProcess\`

package/skills/uipath-rpa/references/legacy/activity-docs/_INDEX.md

@@ -11,12 +11,12 @@ Reference documents for writing **legacy** UiPath RPA workflows (XAML). Each fil
 | File | Package | Key Activities |
 |------|---------|----------------|
 | [System.md](System.md) | UiPath.System.Activities | Collections, Text, Dates, Dialogs, Files, PowerShell, Triggers |
-| [UIAutomation.md](UIAutomation.md) | UiPath.UIAutomation.Activities | Click, Type, Find Element, Selectors, Browser/Window scope |
+| [UIAutomation → selector-guide.md](../selector-guide.md#uiautomation-activities-reference) | UiPath.UIAutomation.Activities | Click, Type, Find Element, Selectors, Browser/Window scope |
 | [Excel.md](Excel.md) | UiPath.Excel.Activities | Read/Write Range/Cell, Workbook/Application Scope, CSV, Macros |
 | [Mail.md](Mail.md) | UiPath.Mail.Activities | SMTP, IMAP, POP3, Exchange, Outlook |
 | [Web.md](Web.md) | UiPath.WebAPI.Activities | HTTP Request, SOAP, JSON, XML |
 | [MicrosoftOffice365.md](MicrosoftOffice365.md) | UiPath.MicrosoftOffice365.Activities | Graph API: Mail, Calendar, Excel Online, OneDrive, SharePoint |
-| [Testing.md](Testing.md) | UiPath.Testing.Activities | Assertions, PDF/Text comparison, test data queues |
+| [Testing → testing-guide.md](../testing-guide.md#testing-activities-reference) | UiPath.Testing.Activities | Assertions, PDF/Text comparison, test data queues |
 | [PDF.md](PDF.md) | UiPath.PDF.Activities | Read PDF Text, OCR, Extract Pages, Join, Password |
 | [Word.md](Word.md) | UiPath.Word.Activities | Word COM + Portable, text/image/table operations |
 | [Presentations.md](Presentations.md) | UiPath.Presentations.Activities | PowerPoint COM + OpenXml |

package/skills/uipath-rpa/references/legacy/activity-docs/_PATTERNS.md

@@ -7,7 +7,7 @@ Quick-reference patterns for writing legacy XAML workflows: VB.NET expressions,
 
 ## Required Parent Scopes
 
-See [common-pitfalls.md](../common-pitfalls.md) for the canonical Required Parent Scopes table and ActivityAction body patterns.
+See [xaml-basics-and-rules.md § Common Pitfalls](../xaml-basics-and-rules.md#common-pitfalls--quick-reference) for the canonical Required Parent Scopes table and ActivityAction body patterns.
 
 ---
 

package/skills/uipath-rpa/references/legacy/activity-docs/_REFRAMEWORK.md

@@ -4,7 +4,7 @@
 The REFramework is UiPath's official **State Machine-based project template** for building production-grade automation. It provides built-in retry logic, exception handling, configuration management, and application lifecycle control. It's the standard for transactional, unattended automation.
 
 **Source**: [github.com/UiPath/ReFrameWork](https://github.com/UiPath/ReFrameWork)
-**Current Desktop Template**: Studio 25.10 (verified from `C:\Users\alexandru.roman\Documents\UiPath\legacy_tests\`)
+**Current Desktop Template**: Studio 25.10
 **Available in**: VB.NET (`RoboticEnterpriseFramework-VB`) and C# (`RoboticEnterpriseFramework-Csharp`)
 
 ---
@@ -590,9 +590,4 @@ When starting a new REFramework project:
 
 ## Sources
 - [UiPath REFramework GitHub Repository](https://github.com/UiPath/ReFrameWork)
-- [UiPath Studio Documentation - Robotic Enterprise Framework](https://docs.uipath.com/studio/standalone/2024.10/user-guide/robotic-enterprise-framework)
-- [UiPath Forum - MaxRetryNumber vs MaxConsecutiveSystemExceptions](https://forum.uipath.com/t/re-framwork-maxretrynumber-vs-maxconsecutivesystemexceptions/453279)
-- [UiPath Forum - How would you improve ReFramework?](https://forum.uipath.com/t/how-would-you-improve-reframework/770451)
-- [UiPath Forum - REFramework Best Practices](https://forum.uipath.com/t/reframework-best-practices/182867)
-- [UiPath Forum - REFramework in 2026: Still Best Practice?](https://forum.uipath.com/t/reframework-in-2026-still-best-practice-or-due-for-modernization/5730782)
-- [UiPath Academy - Introduction to REFramework](https://academy.uipath.com/courses/introduction-to-robotic-enterprise-framework)
+- [UiPath Studio Documentation — Robotic Enterprise Framework](https://docs.uipath.com/studio/standalone/2024.10/user-guide/robotic-enterprise-framework)