docs(uipath-rpa): make headless Studio the default in skill docs [PILOT-4918]

[gabrielavaduva]

Jira: PILOT-4918

Summary

Recent rpa-tool releases ship a headless Studio (codename Helm — UiPath.Studio.Helm.{Platform} NuGet) that auto-resolves and auto-launches on first call. The uipath-rpa skill still walked every agent through "Step 0.2: Verify Studio is Running" with list-instances/start-studio, which is no longer needed for the standard authoring loop.

This PR rewrites the skill docs to reflect the headless-default model. Studio Desktop is now flagged as required only for the two commands that genuinely need its UI:

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

focus-activity is in turn a prerequisite for the activity-targeted debug commands TestActivity, StartDebuggingFromHere, and activity-targeted ToggleBreakpoint — those recipes now carry a Studio-Desktop callout and a headless fallback.

Files touched

• `SKILL.md` — Step 0 simplified; no Studio Desktop check in the default flow.
• `references/environment-setup.md` — replaced "Verify Studio is Running" with a "Studio Desktop vs headless Studio" preamble; added an "Edge case: requiring Studio Desktop" section at the bottom.
• `references/cli-reference.md` — added "Studio Desktop vs headless Studio (Helm)" section listing the two Studio-Desktop-only commands; reframed `list-instances`/`start-studio`/`focus-activity` as edge cases; rewrote IPC connection-refused recovery row.
• `references/debugging.md` — added "Studio Desktop vs headless" section; per-recipe Studio-Desktop callouts on workflows feat(EvalsBreakdown): break down eval skill #1–feat(CodedAgents): single skill #3.
• `references/validation-guide.md` — flagged the Studio Desktop requirement on the "Focus Activity for Debugging" section.
• `references/coded/coding-guidelines.md` — dropped `--studio-dir` from the `get-errors` example; rewrote three Common Issues rows.
• `references/coded/operations-guide.md` — dropped `--studio-dir` from the `create-project` example.
• `references/xaml/common-pitfalls.md` — rewrote "Studio IPC connection failures" recovery steps to be headless-aware.

Terminology

Aligned with the rest of the repo: "Studio" generically (Helm IS Studio), "Studio Desktop" only when UI matters, "headless Studio" / "Helm" only where load-bearing (auto-launch, cold-cache timeout).

Test plan

• On a clean machine without Studio Desktop installed, follow the skill's quick-start and confirm `uip rpa create-project` / `get-errors` / `build` / `run-file` succeed via headless Studio.
• Confirm `uip rpa diff` and `uip rpa focus-activity` still surface clear guidance to run `start-studio` first.
• Verify all relative links resolve (`environment-setup.md#edge-case-requiring-studio-desktop` from `debugging.md` and `validation-guide.md`).
• Skim for stale "Studio is running" / "list-instances" guidance; should only appear in the edge-case sections.

🤖 Generated with Claude Code

[github-actions]

Claude finished @gabrielavaduva's task in 3m 19s —— View job

---

Summary

This PR rewrites the uipath-rpa skill docs to make headless Studio (Helm) the default, removing the mandatory "verify Studio is running" step from the standard authoring loop. Studio Desktop is now flagged as required only for diff and focus-activity. The change is well-scoped across 8 files, terminology is aligned, and the edge-case guidance is actionable.

Change-by-Change Review

1. skills/uipath-rpa/SKILL.md (+4/−4)

OK

Step 0 header and body correctly simplified. "Quick check" paragraph is clear and actionable — agent knows it only needs project.json. The Common Rule #1 update (check explicit path, project name, then CWD for project.json) correctly removes the list-instances step. Good.

2. skills/uipath-rpa/references/environment-setup.md (+38/−36)

Medium — UIA boundary + minor duplication source

• UIA boundary (line 7): The new intro paragraph names indicate-application/element explicitly: "…indicate-application/element, the uia group, etc. all work headless." Per CLAUDE.md boundary rules, indicate-application and indicate-element are listed as forbidden UIA subcommands in the skill files. The fix is trivial — replace with "the indication commands" or just drop them (they're already covered by "the uia group"). Fix this →
• The Step 0.1–0.3 renumbering and the new "Edge case: requiring Studio Desktop" section at the bottom are clean. Resolution order correctly collapses from 4 steps to 3.
• --studio-dir dropped from both create-project examples — correct.

3. skills/uipath-rpa/references/cli-reference.md (+37/−13)

Medium — UIA boundary + duplication

• UIA boundary (line 25): The "Everything else" paragraph enumerates indicate-application, indicate-element by name. Same violation as environment-setup.md. Replace with "the indication commands" or simply remove them from the list — the sentence already ends with "all uia subcommands, all uip is subcommands". Fix this →
• Duplication (lines 8–27): The "Studio Desktop vs headless Studio (Helm)" section duplicates the table and explanation from environment-setup.md § Edge case: requiring Studio Desktop almost verbatim. Per reference pointer discipline, this file should carry bridge content (1–2 sentences tying CLI context to the concept) + a link to environment-setup.md, not a full standalone section. Currently there is no cross-reference to environment-setup.md at all — the cli-reference acts as if it's the sole authority.
• The --studio-dir and --timeout description updates in the Global Options table are accurate and helpful.
• The error troubleshooting table rewrites (lines 500–508) are correct and actionable — the "Re-run the command" recovery for headless is the right default.
• The list-instances / start-studio section re-framing as edge-case-only is clean.

4. skills/uipath-rpa/references/debugging.md (+29/−9)

Medium — duplication

• Duplication (lines 7–19): The "Studio Desktop vs headless" section duplicates the diff / focus-activity table from both cli-reference.md and environment-setup.md. It does link to environment-setup.md#edge-case-requiring-studio-desktop (good), but the preceding table and explanation still fully restate the content. Per reference pointer discipline, the debugging-specific content (which debug commands need Studio Desktop: TestActivity, StartDebuggingFromHere, targeted ToggleBreakpoint) is the unique bridge material; the generic "which commands need Studio Desktop" table should be a pointer.
• The per-recipe callouts (Workflows feat(EvalsBreakdown): break down eval skill #1–feat(CodedAgents): single skill #3) are well-placed — agents get the Studio Desktop warning right before the code block where it matters.
• The best-practices updates at the bottom (lines 371–377) correctly add "Studio Desktop required" to each focus-activity-dependent tip.

5. skills/uipath-rpa/references/validation-guide.md (+3/−1)

OK

Clean callout with cross-reference to environment-setup.md#edge-case-requiring-studio-desktop. Includes the right fallback ("Skip this step entirely on headless-only setups — get-errors already includes the IdRef and file:line"). This is how the other files should handle it.

6. skills/uipath-rpa/references/coded/coding-guidelines.md (+5/−5)

OK

• --studio-dir dropped from the get-errors example (line 123) — correct, matches the headless-first model.
• Common Issues table rewrites are accurate. "No Studio instances found" correctly scoped to diff/focus-activity only.
• "Stale pipe / ENOENT" recovery correctly distinguishes headless (re-run) vs Desktop (restart).

7. skills/uipath-rpa/references/coded/operations-guide.md (+1/−1)

OK

--studio-dir dropped from create-project example. Minimal, correct change.

8. skills/uipath-rpa/references/xaml/common-pitfalls.md (+6/−5)

OK

IPC connection failure recovery steps correctly rewritten as headless-first. Step 4 is properly scoped as "Studio Desktop only" with the right conditions.

What's Missing

• No new capabilities were introduced (this is a terminology/guidance change only), and existing test tasks (before_after_hooks.yaml, coded_test_case.yaml) don't reference list-instances or start-studio, so test coverage is unaffected.
• Nothing else identified.

Area Ratings

Area	Status	Notes
Frontmatter	OK	Unchanged — no frontmatter edits
E2E Tests	OK	Existing tests unaffected by guidance changes
Skill Body	OK	SKILL.md changes are minimal and correct
References & Assets	Medium	UIA boundary violation (2 files name forbidden subcommands); Studio Desktop table duplicated in 3 files
Repo Hygiene	OK	No cross-skill refs, no secrets, changes scoped to uipath-rpa, CODEOWNERS not needed

Issues for Manual Review

• CLI command accuracy: The claim that indicate-application and indicate-element work headless should be verified against the actual tool — the reviewer can confirm these don't require Studio Desktop's UI context (indication typically involves screen interaction).
• UIPATH_RPA_TOOL_USE_STUDIO=1 env var: This env var is referenced in 4 files. Verify it's a real, supported env var in the rpa-tool — it wasn't in the docs before this PR.
• Cold cache timeout ("30–90 s"): The specific range appears in 4 files. Verify this is accurate for the shipping Helm NuGet package.

Conclusion

Approve with minor fixes. The headless-first rewrite is well-executed — the new guidance is clear, actionable, and correctly scopes Studio Desktop to the two commands that genuinely need it. Two small issues to address:

1. Must fix (Medium): Remove indicate-application and indicate-element from the explicit command lists in environment-setup.md:7 and cli-reference.md:25 — they're forbidden UIA subcommands per the repo's boundary rules and are already covered by "the uia group" / "all uia subcommands".
2. Should fix (Medium): The "which commands need Studio Desktop" table (diff + focus-activity) is fully duplicated in cli-reference.md, debugging.md, and environment-setup.md. Consider making environment-setup.md the authority, with the other two files carrying bridge content + a link (as validation-guide.md already does well).

---

[RaduAna-Maria]

Actually, does the --use-studio flag still exist in rpa-tool and it does something? It is still referenced in many files

[gabrielavaduva]

Actually, does the --use-studio flag still exist in rpa-tool and it does something? It is still referenced in many files

@RaduAna-Maria actually no, it is ignored, I had a cleanup PR for this #258 maybe it has some leftovers I'll check