docs(uipath-platform/solution): expand resource refresh + deploy gotchas

[alexenica]

Summary

• resource refresh now explains the actual mechanism (binding discovery, referenceKey disambiguation from agent's resource.json, .uipx project reconcile, per-user debug_overwrites)
• New "App resources" subsection documenting the 4 artefact files refresh produces + what triggers Studio Web's "App is no longer available" warning (version drift vs Apps semVersion)
• Moved App to the non-virtualizable list alongside Process/Connection
• pack docs the required <outputPath> positional + the <name>_<version>.zip output naming
• deploy run warns about false-positive polling failures (pipeline ID expires post-completion → 404s on deploy status) and recommends solution deploy list as the fallback truth source
• solution.md lifecycle clarifies the two distribution paths (pack/publish/deploy vs upload) and notes that upload is debug-only

Test plan

• Manually verified each rule against the corresponding CLI behaviour while debugging uip solution resource refresh and uip solution deploy run end-to-end on agent solutions
• Skill content stays in sync with the latest solution-tool changes (PR UiPath/cli#1146)

[github-actions]

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

---

PR Review: docs(uipath-platform/solution): expand resource refresh + deploy gotchas

• Read review criteria and project conventions
• Read full diff and existing PR conversation
• Read full changed files for context
• Apply skill-specific checks (links, cross-refs, secrets)
• Post review findings

---

Summary

Expands resource refresh documentation with internal mechanism details (binding discovery, cloud GUID resolution, .uipx reconciliation, per-user debug overwrites), adds App resource artefact docs, documents pack positional arg and _ naming, and warns about deploy run polling false-positives. Also clarifies the two distribution paths (pack/publish/deploy vs upload) in solution.md.

Change-by-Change Review

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

Severity: OK

Solid expansion. The "What refresh actually does" section (lines 101–108) gives agents the mechanistic detail needed to debug refresh failures. Folder disambiguation (lines 124–127), bindings_v2.json locations (lines 199–205), and per-user debug overwrites (lines 207–209) are all valuable for agent reasoning.

Moving App to the non-virtualizable list (line 194) is correct and consistent with the new App resources subsection.

One minor note: the code block at lines 115–119 has no language identifier. Consider adding a plain ```text fence for consistency with the repo's markdown standards.

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

Severity: Medium — naming inconsistency

The PR changes the documented zip naming convention from <name>.<version>.zip to <name>_<version>.zip (line 51). However, all existing code examples still use the old dot separator:

Line	Current	Should be
58	MySolution.2.0.0.zip	MySolution_2.0.0.zip
61	MySolution.2.0.0.zip	MySolution_2.0.0.zip
205	MySolution.*.zip	Glob still works, but inconsistent with docs
220	MySolution.1.2.0.zip	MySolution_1.2.0.zip
226	MySolution.1.2.0.zip	MySolution_1.2.0.zip

An agent following the naming docs will produce _-separated names, but an agent reading the CI or environment-promotion examples will produce .-separated names. This creates a contradiction that can cause publish to reference a non-existent file.

Fix this →

Severity: Medium — deploy polling duplication

The polling false-positive warning now appears in two places in the same file:

1. Blockquote under Step 5 (lines 109–114)
2. Gotchas subsection "Polling false-positives on deploy run" (lines 259–260)

Both convey the same information. Per Reference Pointer Discipline, one should be the authoritative copy and the other a bridge. Recommend keeping the Gotchas section as the full explanation (it's where agents look for troubleshooting) and shortening the Step 5 blockquote to a one-liner pointing there, e.g.:

Heads up: polling can false-positive on long deployments — see Polling false-positives in Gotchas.

The --folder-path expansion (line 256) adding the nested folder example is helpful — good addition.

3. skills/uipath-platform/references/solution/solution.md

Severity: OK

The mermaid diagram update adding the C --> H[upload] edge (line 43) correctly reflects the two distribution paths. The explanatory paragraph (lines 45–49) is concise and adds real disambiguation value between pack→publish→deploy vs upload.

The resource refresh reminder on line 49 is light enough — single sentence with the specific files that need to be current. Acceptable bridge content (not duplicating the mechanism from develop-solution.md).

What's Missing

• Zip naming in code examples not updated — the <name>_<version>.zip convention from line 51 is not reflected in the publish/CI/promotion examples (see detailed finding above).
• No text language identifier on the code block at develop-solution.md:115 — minor, but repo standards require language identifiers on all fenced code blocks.

Area Ratings

Area	Status	Notes
Frontmatter	OK	No frontmatter changes in this PR
E2E Tests	OK	No new CLI workflows added; existing uipath-platform test coverage is out of scope for this docs-only change
Skill Body	OK	Changes scoped to reference files, not SKILL.md
References & Assets	Issue	Zip naming inconsistency across examples (Medium); polling warning duplication (Medium)
Repo Hygiene	OK	CODEOWNERS exists for /skills/uipath-platform/. No secrets, no cross-skill refs, no binary files. All relative links resolve.

Issues for Manual Review

• Zip naming truth: does uip solution pack actually produce <name>_<version>.zip (underscore) or <name>.<version>.zip (dot)? The PR changes the documented convention but I can't verify the CLI's actual output. If the CLI uses dots, the old examples were correct and line 51 should be reverted instead.
• Pipeline ID expiry: the 404 behavior on deploy status after completion is documented as a known gotcha — worth confirming this matches the latest CLI version behavior, as server-side TTL could change.

Conclusion

Good documentation expansion — the refresh mechanism details and App resource docs fill a real knowledge gap for agents working with solutions. Two medium issues to address before merge: (1) update the zip filename examples to match the new _ naming convention (or revert if the CLI actually uses .), and (2) deduplicate the polling false-positive warning. Otherwise ready to go.