UiPath · gabrielavaduva · Apr 28, 2026 · Apr 28, 2026
@@ -43,11 +43,11 @@ Before doing any work, check if `.claude/rules/project-context.md` exists in the
    - `AGENTS.md` at project root — read by UiPath Autopilot in Studio Desktop. If `AGENTS.md` already exists, look for `<!-- PROJECT-CONTEXT:START -->` / `<!-- PROJECT-CONTEXT:END -->` markers and replace only between them; if no markers exist, append the fenced block at the end
 4. Then proceed with the skill workflow
 
-## Step 0: Resolve PROJECT_DIR and Environment
+## Step 0: Resolve PROJECT_DIR
 
-Before creating or modifying anything, determine which project to work with and ensure Studio is running. See [references/environment-setup.md](references/environment-setup.md) for the full procedure.
+Before creating or modifying anything, determine which project to work with. See [references/environment-setup.md](references/environment-setup.md) for the full procedure.
 
-**Quick check:** Find `project.json` to establish `{projectRoot}`, run `uip rpa list-instances --output json` to verify Studio, and `uip rpa open-project` if needed.
+**Quick check:** Find `project.json` to establish `{projectRoot}`. That's it — no Studio Desktop check needed. `uip rpa` auto-launches a headless Studio (UiPath.Studio.Helm NuGet) on first call. Studio Desktop is required only for `diff` and `focus-activity`.
 
 ## Project Type Detection
 
@@ -86,7 +86,7 @@ For the full decision flowchart, InvokeCode extraction rules, and detailed hybri
 
 ### Common Rules (Both Modes)
 
-1. **NEVER create a project without confirming none exists.** Follow Step 0 resolution: check explicit path, project name, running Studio instances, then CWD. Only create when confirmed no project matches AND user explicitly requests creation.
+1. **NEVER create a project without confirming none exists.** Follow Step 0 resolution: check explicit path, project name, then CWD for `project.json`. Only create when confirmed no project matches AND user explicitly requests creation.
 2. **ALWAYS use `uip rpa create-project`** to create new projects — never write `project.json` or scaffolding manually.
 3. **ALWAYS list project analyzer rules before generating workflows, validate files as you go, AND verify the project builds before declaring done.** Three-phase validation:
    - **Pre-generation** (before creating or editing any workflow file — `.cs` with `[Workflow]`/`[TestCase]`, or `.xaml`): `uip rpa get-analyzer-rules --project-dir "<PROJECT_DIR>" --output json` to list the enabled Workflow Analyzer rules. Apply every `error` and `warning` rule during authoring so generated code passes `analyze` and `build` on the first attempt. Run once at the start of the task; re-run only when project dependencies change (a newly added package can ship its own `MA-*` rules).

@@ -4,6 +4,28 @@ CLI reference for `uip rpa` -- communicates with UiPath Studio over named pipes
 
 > **Installation is automatic.** Do NOT attempt to install `uip` manually or instruct the user to install it.
 
+## Studio Desktop vs headless Studio (Helm)
+
+`uip rpa` connects to one of two flavors of Studio behind the same IPC contract:
+
+- **Headless Studio (Helm) — default.** Ships as a NuGet package (`UiPath.Studio.Helm.{Platform}`) and auto-launches on first use. **No Studio Desktop install needed.** First call on a cold NuGet cache may sit near-silent for 30–90 s while `dotnet restore` runs; raise `--timeout` to ≥ 180 for that call.
+- **Studio Desktop.** The interactive UI. Used automatically only by commands with UI side effects.
+
+### Which commands need Studio Desktop
+
+Only these two — they do not work headless:
+
+| Command | Why |
+|---------|-----|
+| `uip rpa diff` | Opens an interactive diff window in Studio's UI |
+| `uip rpa focus-activity` | Highlights an activity in Studio's active workflow designer |
+
+For these, run `uip rpa start-studio --project-dir "<PROJECT_DIR>"` first if Studio Desktop is not already up.
+
+Everything else — `create-project`, `open-project`, `close-project`, `run-file`, `stop-execution`, `get-errors`, `build`, `get-analyzer-rules`, `find-activities`, `get-default-activity-xaml`, `get-versions`, `inspect-package`, `install-or-update-packages`, `list-data-fabric-entities`, `install-data-fabric-entities`, `search-templates`, `indicate-application`, `indicate-element`, all `uia` subcommands, all `uip is` subcommands — runs headless with no Studio Desktop required.
+
+To force Studio Desktop for any command, set `UIPATH_RPA_TOOL_USE_STUDIO=1`. Not recommended for the standard authoring loop.
+
 > **This guide may not list every available command.** The CLI is self-documenting -- append `--help` at any level to progressively discover commands, subcommands, and parameters:
 
 ```bash
@@ -21,22 +43,22 @@ Every `uip rpa` invocation accepts these flags:
 | Option | Description | Default |
 |--------|-------------|---------|
 | `--project-dir <path>` | Project directory to match against running Studio instances | Current working directory |
-| `--studio-dir <path>` | Path to Studio installation directory | Auto-detected (see below) |
-| `--timeout <seconds>` | Timeout in seconds for Studio resolution | `300` |
+| `--studio-dir <path>` | Path to Studio Desktop installation (only used when Studio Desktop is in use) | Auto-detected (see below) |
+| `--timeout <seconds>` | Timeout in seconds for Studio resolution (raise to ≥ 180 on a cold Helm NuGet cache) | `300` |
 | `--verbose` | Enable verbose/debug logging | Off |
 | `--output <format>` | Output format: `json`, `table`, `yaml`, `plain` | `table` |
 
 > **Always use `--output json`** when calling `uip rpa` commands programmatically. The `table` format pads columns and can produce extremely large output (100KB+). JSON is compact and machine-readable.
 
 ### STUDIO_DIR Resolution
 
-`--studio-dir` is optional -- omit it by default and let `uip` auto-detect Studio. Only provide it explicitly if auto-detection fails, using the first match:
+`--studio-dir` is **only consulted when Studio Desktop is in use** (i.e. you ran `start-studio`, called `diff`/`focus-activity`, or set `UIPATH_RPA_TOOL_USE_STUDIO=1`). Headless Studio (Helm) ignores it. When Studio Desktop is needed and auto-detection fails, the resolution waterfall is:
 
 1. Environment variable `UIPATH_STUDIO_DIR` if set.
 2. Default install: `C:\Program Files\UiPath\Studio` (or `x86` variant) if `UiPathStudio.exe` exists there.
 3. Dev build: Studio source tree build output (e.g. `<repo-root>\Output\bin\Debug`).
 
-> **Error `"Studio X.X.X does not have interop support"` or `"Requires Studio 26.2+"`** means the detected Studio is too old. Stop calling `uip rpa` commands and inform the user to update Studio.
+> **Error `"Studio X.X.X does not have interop support"` or `"Requires Studio 26.2+"`** means the detected Studio Desktop is too old. This affects only the two Studio-only tools (`diff`, `focus-activity`) and any explicitly forced Studio runs. Inform the user to update Studio Desktop.
 
 ### PROJECT_DIR Resolution
 
@@ -59,22 +81,24 @@ Located at `{projectRoot}/.local/docs/packages/{PackageId}/`.
 
 ---
 
-## Commands -- Studio Management
+## Commands -- Studio Desktop Management (edge cases only)
+
+> Skip this section unless you need to invoke `diff` or `focus-activity`. Every other command auto-launches headless Studio (Helm) when needed.
 
 ### list-instances
 
-List running UiPath Studio instances and their IPC status.
+List running Studio Desktop instances and their IPC status. Hidden diagnostic command — does **not** report the auto-launched headless Studio (Helm) instances.
 
 ```bash
 uip rpa list-instances --output json```
 
-No command-specific options.
+No command-specific options. An empty `Data` array does NOT mean `uip rpa` won't work — headless Studio starts on demand.
 
 ---
 
 ### start-studio
 
-Ensure a Studio instance is running. Resolution waterfall:
+Ensure a **Studio Desktop** instance is running. Only required before invoking `diff` or `focus-activity`, or when forcing Studio Desktop with `UIPATH_RPA_TOOL_USE_STUDIO=1`. Resolution waterfall:
 1. Match by `--project-dir` -- reuse if available, wait if busy
 2. Use an idle instance (no project loaded)
 3. Start a new instance via `--studio-dir` -- poll until available
@@ -106,7 +130,7 @@ uip rpa create-project --name "<NAME>" --location "<PARENT_DIR>" --output json``
 
 ### open-project
 
-Open an existing project in Studio. Only needed when explicitly loading a project that isn't already open (e.g. after `create-project`, or when switching projects). Most commands (`validate`, `run-file`) auto-resolve a Studio instance, so this is rarely required.
+Open an existing project in Studio. Only needed when explicitly loading a project that isn't already open (e.g. after `create-project`, or when switching projects). Most commands (`validate`, `run-file`) auto-resolve a Studio instance and open the project automatically, so this is rarely required.
 
 ```bash
 uip rpa open-project --project-dir "<PROJECT_DIR>" --output json```
@@ -476,11 +500,11 @@ When `uip` commands fail, diagnose by error category:
 
 | Error Pattern | Cause | Recovery |
 |---------------|-------|----------|
-| `"connection refused"`, `"EPIPE"`, `"pipe not found"` | Studio IPC not available | Run `uip rpa start-studio`, then `uip rpa open-project --project-dir "..."` |
-| `"timeout"`, `"ETIMEDOUT"` | Command took too long | Increase timeout: `uip rpa --timeout 600 <command>`, or use `--skip-validation` for `get-errors` |
+| `"connection refused"`, `"EPIPE"`, `"pipe not found"` | Studio IPC not available. Headless Studio (Helm): NuGet restore failed or process exited. Studio Desktop: not running. | Re-run the command — headless Studio relaunches automatically. If it persists, raise `--timeout` and check the Helm restore output for NuGet errors. Only run `uip rpa start-studio` if the failing command is `diff`/`focus-activity` or `UIPATH_RPA_TOOL_USE_STUDIO=1` is set. |
+| `"timeout"`, `"ETIMEDOUT"` | Command took too long. Cold Helm NuGet restore can take 30–90 s. | Raise the timeout: `uip rpa --timeout 600 <command>`. For `get-errors`, also try `--skip-validation`. |
 | `"not authenticated"`, `401`, `403` | Auth required for cloud features | Run `uip login` and re-try |
 | `"package not found"`, `"version not available"` | Wrong package ID or version | Verify package name via `uip rpa find-activities`; omit `version` to auto-resolve latest |
-| `"project not found"`, `"no project open"` | Wrong project-dir or project not open | Verify `--project-dir` path, run `uip rpa open-project` |
+| `"project not found"`, `"no project open"` | Wrong project-dir or project not open in Studio | Verify `--project-dir` path, run `uip rpa open-project` |
 | `"file not found"` in `get-errors` | Wrong `--file-path` (must be relative to project) | Use path relative to project root, not absolute |
 | `"Studio is busy"`, `"operation in progress"` | Studio is processing a previous request | Wait a few seconds and retry the command |
 | Any unrecognized error | Unknown | Check `--verbose` flag: `uip rpa --verbose <command>` for debug details, inform the user |
@@ -554,7 +578,7 @@ uip rpa get-workflow-example --key "<BLOB_PATH>" --output json```
 
 ### focus-activity
 
-Focus an activity in the Studio designer view.
+Focus an activity in the Studio Desktop designer view. **Requires a running Studio Desktop instance** — does not work against headless Studio. Run `uip rpa start-studio --project-dir "<PROJECT_DIR>"` first if Studio Desktop is not already up.
 
 ```bash
 uip rpa focus-activity --activity-id "<IDREF>" --output jsonuip rpa focus-activity --output json```

@@ -120,7 +120,7 @@ if (system.PathExists(@"C:\Reports\report.pdf", PathType.File, out ILocalResourc
 - **Escape backslashes in paths** — Use `C:\\path\\file.txt` not `C:\path\file.txt` in input arguments
 
 ### Validation Loop (Critical Rule #14)
-uip rpa get-errors --file-path "<FILE>" --project-dir "<PROJECT_DIR>" --studio-dir "<STUDIO_DIR>" --output json
+uip rpa get-errors --file-path "<FILE>" --project-dir "<PROJECT_DIR>" --output json
 @../validation-guide.md
 
 ### Error Handling
@@ -197,12 +197,12 @@ C) <user-driven approach>
 
 | Issue | Cause | Fix |
 |-------|-------|-----|
-| **"Studio X.X.X does not have interop support"** | Auto-detected Studio is too old (< 26.2) | Always pass `--studio-dir "<STUDIO_DIR>"` pointing to the dev build |
-| **No Studio instances found** | Studio is not running | Run `uip rpa start-studio --project-dir "<PROJECT_DIR>" --studio-dir "<STUDIO_DIR>"` |
-| **Stale pipe / ENOENT** | Studio instance crashed or was closed | The tool retries automatically; if persistent, restart Studio |
+| **"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 start-studio --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 | Add required package to project.json dependencies |
-| **Timeout** | Studio took too long to start | Increase timeout: `--timeout 600` |
+| **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 |
 | **inspect-package 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/` |

@@ -11,7 +11,7 @@ Creates a complete UiPath coded automation project from scratch. **ALWAYS use `u
 **1. Create the project with `uip rpa create-project`:**
 
 ```bash
-uip rpa create-project --name "<NAME>" --location "<PARENT_DIR>" --studio-dir "<STUDIO_DIR>" --output json```
+uip rpa create-project --name "<NAME>" --location "<PARENT_DIR>" --output json```
 
 **Template options:**
 - `--template-id BlankTemplate` (default) — standard process project