docs(solution,platform): five UV fixes — env-var format, role lookup, connection repoint, deploy folder

[alexenica]

Doc side of the whole batch, consolidated into one PR. Pairs with UiPath/cli#3329.

Claims here were checked against live behaviour on alpha via the paired CLI branch, not written from the diff.

uipath-platform — environment variables format

--environment-variables was documented as a JSON object. Orchestrator stores newline-separated KEY=VALUE; the JSON shape was silently discarded. Corrected for processes create/update, with the clear-them example, and for jobs start (which was flagged as unconfirmed in an earlier revision — the CLI now validates the same format there).

uipath-platform — roles users list

UV-15580 made this usable as the forward "who holds this role" lookup, so it is documented next to user-roles/user-permissions, including that Pagination.Total is the real membership count. The old workaround — sweeping every principal — is no longer needed.

uipath-solution — repointing a connection

UV-15516 asked for this under "SKILL-DOC GAP". Refresh is not changing: a prune was prototyped and rejected, so the documented behaviour is what actually happens — repointing imports the new connection as <name>_1 and leaves the old resource in place, unreferenced but still listed and still in debug_overwrites.json. Cleanup is a manual uip solution resources remove <old-key>, and the section says why refresh does not do it: it never removes resources, so it cannot silently drop something added on purpose.

Also corrects the two places that claimed refresh "never overwrites" without qualification, and documents the ticket's secondary finding — an Enabled, pingable connection can still be missing from the Resource Catalog because RCS indexing is per folder.

uipath-solution — deploy run and folders

Two corrections, both from UV-15346:

1. The doc said deployment fails if the folder already exists. It does not — Orchestrator collision-renames (MySolution → MySolution 1) and deploys there. That wrong sentence is the whole trap: the reporter expected success or an error and got eight new empty folders.
2. Deploying into a pre-existing folder is impossible, and the reason is now stated: PipelinesInstallRequest takes solutionRootFolderName — a name, not a folder key — so the target cannot be addressed. An API-contract limitation, not a missing flag.

Adds the two workarounds (preferred: let deploy create the folder, then provision into what it returns), and documents the RequestedFolderName + FolderNote signal the CLI now emits on a rename, so readers know it is detectable rather than silent.

🤖 Generated with Claude Code

[github-actions]

Claude finished @alexenica's task in 2m 2s —— View job

---

PR Review: docs(solution) — connection-repoint prune and role member lookup

• Read review criteria and project conventions
• Read full diff
• Read full changed files for surrounding context
• Check skill-specific rules (links, cross-references, secrets)
• Post review findings

---

Summary

Docs-only PR documenting two CLI behavior changes: (1) the connection-repoint prune in solution resources refresh and (2) the now-usable roles users list forward lookup. Both changes are scoped to their owning skills with no cross-skill dependencies.

Change-by-Change Review

1. skills/uipath-platform/references/orchestrator/setup-environment.md (+9/-0)

Severity: OK

Adds the roles users list forward-lookup paragraph after the existing user-permissions/user-roles inverse lookups (line 149–156). Well-placed — completes the three-way lookup triangle (what can user do → which roles does user have → who holds this role). The code block uses --output json consistently, and the Pagination.Total note gives agents the right field to check for membership count. The comment in the code block (# Principals assigned to a role (users, groups, robots, external apps)) earns its keep — roles users list could easily be misread as returning only human users.

2. skills/uipath-solution/references/develop-solution.md (+16/-2)

Severity: OK

Three coherent edits:

• Pruned row in the output table (line 137): links to the new anchor — correct, the anchor #repointing-a-connection resolves to the ### Repointing a connection heading at line 172.
• New "Repointing a connection" subsection (lines 172–183): clearly scopes the prune: connection-only, name-match or <name>_N variant, no-binding-references-left condition. The "deliberately narrow" paragraph prevents agents from over-generalizing the prune to other resource kinds.
• Two "never overwrites" corrections (lines 185 and 367): old text said refresh "never overwrites a resource" — new text scopes to "never overwrites the spec of a resource" and adds the orphan-repoint caveat with a back-link. Both instances are corrected consistently.

The Resource Catalog indexing caveat (line 183) is a useful edge-case doc — an Enabled connection that isn't folder-indexed would otherwise be a confusing silent failure.

What's Missing

Nothing identified.

Area Ratings

Area	Status	Notes
Frontmatter	OK	No frontmatter changes in this PR
E2E Tests	OK	Doc-only changes to existing reference files — no new CLI workflows or capabilities that warrant new test tasks (the commands already existed, just weren't fully documented)
Skill Body	OK	No SKILL.md changes
References & Assets	OK	Both reference files are internally consistent; all anchor links resolve; no cross-skill references
Repo Hygiene	OK	No secrets, no personal paths, changes scoped to the two relevant skills

Issues for Manual Review

• The roles users list and connection-prune behaviors are documented from alpha testing per the PR description. Verify these match the GA CLI release if the paired CLI branch hasn't merged yet.

Conclusion

Clean PR. Both additions fill documented skill gaps (UV-15516 and UV-15580), are well-scoped, internally consistent, and follow the repo's token-optimized writing style. No issues found — approve.

---