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

skills/uipath-platform/references/orchestrator/run-jobs.md

@@ -92,7 +92,7 @@ Key options:
 | `--specific-priority <1-100>` | Numeric priority override (mutually exclusive with `--job-priority`). Use when you need fine-grained ordering inside the same priority bucket. |
 | `--robot-size <Small\|Standard\|Medium\|Large>` | Cloud robot sizing for serverless runtimes |
 | `--input-arguments <json>` | Default input arguments (merged with per-job inputs) |
-| `--environment-variables <json>` | Default environment variables (merged with per-job env) |
+| `--environment-variables <pairs>` | Default environment variables — newline-separated `KEY=VALUE` pairs, **not** JSON (merged with per-job env) |
 | `--tags <list>` | Comma-separated tags for filtering |
 | `--hidden-for-attended` / `--visible-for-attended` | Toggle visibility to attended robot users |
 | `--auto-create-triggers` / `--no-auto-create-triggers` | Auto-create connected triggers on deploy |
@@ -115,6 +115,13 @@ uip or processes resources <process-key-guid> --output json
 # plus --healing-agent / --no-healing-agent (Autopilot for Robots toggle).
 uip or processes update <process-key-guid> --description "Updated description" --output json
 
+# Environment variables are newline-separated KEY=VALUE pairs, not JSON.
+uip or processes update <process-key-guid> --environment-variables $'API_HOST=api.example.com\nRETRIES=3' --output json
+
+# Pass '' to clear them (Orchestrator reads an empty body as "leave them alone",
+# so the CLI sends a bare newline to make the clear actually happen).
+uip or processes update <process-key-guid> --environment-variables '' --output json
+
 # Walk the package version history (every package version this release ever pointed at)
 uip or processes version-history <process-key-guid> --output json
 
@@ -154,7 +161,7 @@ Key options:
 - `--user-keys <guids>` / `--machine-keys <guids>` — comma-separated GUIDs to pin the job to specific identities. With `--strategy ModernJobsCount` they restrict the candidate pool; with `Specific` they're required.
 - `--healing-agent` — enable Autopilot for Robots (Healing Agent) just for this job, regardless of the process-level `--healing-agent` setting on `processes update`. Useful for one-off self-healing without flipping the process default.
 - `--reference <text>` — user-set reference (free-form string) attached to the job. Useful for correlation with external systems.
-- `--environment-variables <json>` — JSON object of per-job environment variables. Merged on top of folder-/process-level env.
+- `--environment-variables <pairs>` — per-job environment variables as newline-separated `KEY=VALUE` pairs (same shape as the process-level flag, **not** JSON). Merged on top of folder-/process-level env. Malformed lines are rejected before the job is submitted.
 - `--run-as-me` — run under the caller's identity instead of resolving an unattended robot account in the folder.
 - `--wait-for-completion` + `--timeout <seconds>` (default 300) + `--poll-interval <seconds>` (default 5) — poll until the job reaches a terminal state.
 - `--output-dir <path>` + `--no-download` — when `--wait-for-completion` is set, the CLI downloads the job's `OutputFile` to this directory automatically. Pass `--no-download` to opt out.

skills/uipath-platform/references/orchestrator/setup-environment.md

@@ -146,6 +146,15 @@ uip or roles delete <role-key> --output json
 
 `roles user-permissions` is the right command for "what can this user actually do here" debugging; it accounts for inherited folder roles and tenant overrides. `roles user-roles` is the inverse — given a user, which role assignments exist.
 
+For the forward lookup — "who holds this role" — use `roles users list`:
+
+```bash
+# Principals assigned to a role (users, groups, robots, external apps)
+uip or roles users list <role-key> --output json
+```
+
+`Pagination.Total` is the role's full membership count, so a role with no assignees returns `Data: []` and `Total: 0`. Auditing a whole tenant is therefore one call per role, not a directory sweep per principal.
+
 ### Step 4: Import Users from Identity Service
 
 Principals are managed in Identity Service (IS), not in Orchestrator. `users import` is the **single integration point** between IS and the tenant: it references an existing IS principal and provisions the matching tenant user record. Everything downstream (`users assign`, `users assign-roles`, `roles assign`, etc.) takes the resolved Orchestrator user-key — no further IS round-trips. (The legacy `users create` / `users delete` commands are gone — they called endpoints reserved for `ProvisionType=Manual`, which is not how cloud or IS-backed users are managed.)

skills/uipath-solution/references/develop-solution.md

@@ -168,6 +168,30 @@ When a name (e.g. `orders` queue) exists in multiple cloud folders, refresh pref
 
 The placeholder `solution_folder` (and `.`) in a binding's folder field means "no folder" / tenant scope — they're not real cloud folders.
 
+### Repointing a connection leaves the old resource behind
+
+Repointing a connector activity to a *different* connection (a different connection GUID) does **not** update the existing connection resource in place. Refresh is import-only, so it imports the new connection as a new resource and leaves the old one alone. Because both carry the same connection display name, the newcomer gets suffixed:
+
+```
+resources/solution_folder/connection/<connector>/<name>.json      # old GUID — now unreferenced
+resources/solution_folder/connection/<connector>/<name>_1.json    # new GUID
+```
+
+`bindings_v2.json` cleanly references only the new GUID, but both resources stay in `resources list` and in `userProfile/<uid>/debug_overwrites.json`, and every subsequent refresh reports `Imported: 1` for the new one.
+
+**Clean it up yourself** — refresh will not, by design:
+
+```bash
+# find the key of the resource for the old connection
+uip solution resources list --output json
+
+uip solution resources remove <old-resource-key> --solution-folder <dir> --output json
+```
+
+This is intentional. Refresh never removes resources, so it cannot silently drop something you added on purpose. The trade-off is that a repoint needs one manual `remove`.
+
+> A connection can be `Enabled` and pingable and still not be importable: the Resource Catalog is indexed per folder, so `refresh` may warn `Connection <guid> not found in Resource Catalog in the required folder "<folder>"` and import nothing. Membership in `uip is connections list` does not guarantee a connection is refresh-resolvable from a given `folderPath`.
+
 > For single-resource mutations that don't need a full project scan, see [Step 9: Add a Resource Atomically](#step-9-add-a-resource-atomically), [Step 10: Remove a Resource](#step-10-remove-a-resource), and [Step 11: Edit a Resource](#step-11-edit-a-resource). `refresh` and these solve different problems — `refresh` reconciles every binding in every project (and **never overwrites** a resource already in the solution); `add`/`remove`/`edit` operate on one resource at a time. To change an existing resource's spec, `edit` is the only path — `refresh` won't.
 
 ## Step 8: Get a Single Resource Configuration
@@ -350,7 +374,7 @@ If the key isn't in the local solution, the command exits with `Failure` and `Re
 
 ## Step 11: Edit a Resource
 
-Change a resource's `spec` properties by key. This is the only command that mutates an existing resource — `refresh` is import-only (it skips resources already in the solution, never overwrites them).
+Change a resource's `spec` properties by key. This is the only command that mutates an existing resource — `refresh` is import-only (it skips resources already in the solution, never overwrites them). Repointing a binding to a different connection is not an edit either: refresh imports the new one and leaves the old behind for you to `remove` — see [Repointing a connection leaves the old resource behind](#repointing-a-connection-leaves-the-old-resource-behind).
 
 ```bash
 # Patch a single spec property

skills/uipath-solution/references/pack-and-deploy.md

@@ -122,7 +122,7 @@ Key options:
 | `-n, --name <name>` | Deployment name (required) | -- |
 | `--package-name <name>` | Published solution package name (required) | -- |
 | `--package-version <version>` | Package version to deploy (required) | -- |
-| `--folder-name <name>` | New Orchestrator folder to create (required) | -- |
+| `--folder-name <name>` | New Orchestrator folder to create (required). Always creates; a taken name is collision-renamed, never reused — see [`deploy run` Always Creates a New Folder](#deploy-run-always-creates-a-new-folder) | -- |
 | `--parent-folder-path <path>` | Parent folder under which the new folder is created | -- |
 | `--parent-folder-key <key>` | Parent folder key (GUID, alternative to `--parent-folder-path`) | -- |
 | `--config-file <path>` | Configuration file from `deploy config get` | -- |
@@ -315,9 +315,43 @@ These are different commands with different destinations:
 | `solution publish` | Solution feed | For deployment via `deploy run` |
 | `solution upload` | Studio Web | For browser-based editing |
 
-### `deploy run` Creates a New Folder
+### `deploy run` Always Creates a New Folder
 
-`--folder-name` specifies a folder to **create**, not an existing folder to deploy into. If the folder already exists, deployment will fail. Use `--parent-folder-path` to set the parent folder where the new folder is created.
+`--folder-name` specifies a folder to **create**, not an existing folder to deploy into. Use `--parent-folder-path` to set the parent folder where the new folder is created.
+
+**Re-running with a name that is already taken does not fail and does not reuse the folder** — Orchestrator collision-renames the new one (`MySolution` → `MySolution 1`) and the deployment lands there. Repeated deploys therefore accumulate `MySolution 1`, `MySolution 2`, …
+
+The CLI resolves the real folder and says so when it differs from what you asked for:
+
+```json
+{
+  "FolderName": "MySolution 4",
+  "FolderPath": "MySolution 4",
+  "RequestedFolderName": "MySolution",
+  "FolderNote": "Requested folder 'MySolution' already existed, so Orchestrator created 'MySolution 4' instead. ..."
+}
+```
+
+`RequestedFolderName` and `FolderNote` appear **only** on a rename, so their presence is the signal to check. Always provision against `Data.FolderPath`, never against the name you passed.
+
+**There is no way to deploy into a pre-existing folder.** The install API takes `solutionRootFolderName` — a name, not a folder key — so the target cannot be addressed. This matters when the folder you want already holds hand-provisioned assets, an IXP folder-deployment, or an assigned robot: the deployment will land somewhere else and runtime resolution then fails on the missing resources.
+
+Two ways around it:
+
+```bash
+# A. Let deploy create the folder FIRST, then provision into it.
+uip solution deploy run --name my-deployment --package-name my-package \
+  --package-version 1.0.0 --folder-name MySolution --output json
+# → read Data.FolderPath / Data.FolderKey from the response, then create the
+#   assets, folder-deploy IXP, and assign the robot into THAT folder.
+
+# B. Skip solution deploy and bind each piece into the existing folder.
+uip or packages upload ./piece.nupkg --output json
+uip or processes create --package-key <id> --package-version <ver> \
+  --folder-key <existing-folder-key> --output json
+```
+
+Option A is preferred — it keeps the solution deployment intact. Option B loses the solution grouping, so use it only when the folder's existing contents cannot be recreated.
 
 ### `--parent-folder-path` is the Parent