docs(solution): correct what deploy run does when the folder name is taken

[alexenica]

UV-15346. Docs-only — the CLI needs no change here, and the reason is the point.

What was wrong

pack-and-deploy.md said: "If the folder already exists, deployment will fail."

It doesn't. Orchestrator collision-renames the new folder (MySolution → MySolution 1) and deploys there. deploy-run-service.ts already compensates for this — it reads the resolved folder back precisely because the name it asked for may not be the name it got (UV-15393).

That wrong sentence is the whole trap in UV-15346. The reporter ran deploy run ~8 times expecting either success or an error, got 8 new empty folders, and every deployment landed away from the folder that actually held the assets, the IXP folder-deployment and the assigned robot — so runtime resolution failed on missing resources.

What the doc now says

• Re-running with a taken name neither fails nor reuses: it collision-renames and accumulates MySolution 1, MySolution 2, …
• Trust Data.FolderPath in the response over the name passed in.
• Deploying into a pre-existing folder is not possible, and why: PipelinesInstallRequest takes solutionRootFolderName — a name, not a folder key — plus an optional parent path. There is no field that can address an existing folder, so this is an API-contract limitation, not a missing CLI flag.
• The two workarounds, with the preferred one first: let deploy run create the folder and provision into what it returns (keeps the solution deployment intact), or bind each piece with or packages upload + or processes create --folder-key <existing> (loses the solution grouping).
• The --folder-name row in the options table now points at that section instead of implying a plain create.

Verification

Read from the source of truth rather than from the ticket: the six fields of PipelinesInstallRequest in packages/pipelines-sdk, and the collision-rename comment plus resolveInstalledFolder fallback in deploy-run-service.ts.

Not verified live: I did not run two real deploys against the same folder name to watch the rename happen. The API contract settles the "can it target an existing folder" question on its own, and the rename behaviour is already documented in the CLI's own workaround and was observed 8 times by the reporter. Flagging it so the claim's basis is clear.

Paired CLI work for the other two tickets in this batch: UiPath/cli#3350.

🤖 Generated with Claude Code

[github-actions]

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

---

Review: PR #2412

• Read review criteria and project conventions
• Read full diff
• Read full changed file for context
• Verify relative links resolve
• Check for cross-skill references, secrets, paths
• Post review

---

Summary

Docs-only fix: corrects the deploy run folder-collision behavior description in pack-and-deploy.md. The old doc claimed deployment fails when --folder-name is taken; the new doc accurately describes Orchestrator's collision-rename behavior and adds workarounds with CLI examples.

Change-by-Change Review

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

Severity: OK

The change replaces a one-sentence incorrect claim (line 317 old: "If the folder already exists, deployment will fail") with an expanded, accurate section covering:

• Line 125: Options table row updated with inline cross-reference to the new heading — the anchor #deploy-run-always-creates-a-new-folder resolves correctly to the heading on line 318. Good that the table now alerts agents before they reach the Gotchas section.
• Line 318: Heading renamed from deploy run Creates a New Folder → deploy run Always Creates a New Folder — better signals the "no reuse" behavior.
• Lines 320–324: Collision-rename behavior and API-contract limitation are clearly explained. The solutionRootFolderName detail gives agents enough context to understand why the limitation exists, not just that it does.
• Lines 326–341: Two workarounds with copy-paste CLI examples using --output json per repo convention. Option A vs B trade-off is clear. Comments inside the code block are appropriate here — they provide step-specific guidance that the surrounding prose doesn't duplicate.

Content quality:

• Prescriptive and agent-friendly — states facts directly, no hedging.
• CLI commands include --output json where output is parsed.
• Placeholders use appropriate style (<id>, <ver>, <existing-folder-key>). Minor note: these use <lowercase> rather than the <UPPER_SNAKE_CASE> convention documented in .claude/rules/content-quality.md, but this matches the style already used throughout this file (e.g., <name>, <path>, <key> in the options table), so it's consistent within the file.
• No cross-skill references, no secrets, no personal paths.
• All relative links (develop-solution.md, scenarios.md, activate-and-manage.md) resolve to existing files.

The prose is slightly longer than the token-optimization rules prefer in a few spots (e.g., "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"), but the detail is load-bearing — it describes the exact failure scenario that motivated the bug report, so trimming it would lose the "why it matters" context agents need to avoid the trap.

What's Missing

Nothing identified. This is a scoped correctness fix to an existing reference doc. No new CLI workflows or commands are introduced, so no new test coverage is needed.

Area Ratings

Area	Status	Notes
Frontmatter	OK	Not modified; no impact
E2E Tests	OK	Docs-only change; existing deploy tests (deploy_round_trip_e2e.yaml, deploy_list_smoke.yaml) cover the deploy run command
Skill Body	OK	Not modified
References & Assets	OK	Factual correction with accurate workarounds and proper internal anchoring
Repo Hygiene	OK	No secrets, no cross-skill deps, scoped to one file

Issues for Manual Review

• API-contract claim accuracy: The doc asserts PipelinesInstallRequest takes solutionRootFolderName (a name, not a folder key) and therefore cannot target an existing folder. The PR description says this was verified against packages/pipelines-sdk source. Reviewers with access to that SDK should confirm the field list hasn't changed.
• Collision-rename sequence: The doc says Orchestrator appends 1, 2, etc. The PR author noted this was not live-verified but was observed 8 times by the original reporter. Worth confirming the exact naming pattern if precision matters.

Conclusion

Clean, well-scoped docs fix. The correction is important — the old text actively misled agents into expecting a failure that never comes, causing the exact trap described in UV-15346. The new content is accurate (per the stated source verification), actionable, and follows repo conventions. Approve.

---

[alexenica]

Consolidated into #2383 — one PR per repo, as requested. Same commit, cherry-picked onto that branch.