docs(uipath-solution): document resource add and resource remove

[alexenica]

Split: cross-skill command-list cross-references (agents / maestro-case / maestro-flow / platform) moved to #1055 so this PR stays scoped to uipath-solution and only needs merlot/orange/RaduAna review.

Summary

Two atomic resource-mutation verbs just landed in the CLI (UiPath/cli#2221):

• `uip solution resource add --source local|cloud --kind --name ` — virtual stub or cloud import in one call, idempotent.
• `uip solution resource remove ` — atomic delete.

This PR wires both into the Operate half of `uipath-solution` so the skill's docs match the new CLI surface.

What changed

• `develop-solution.md` — Step 9 (add) + Step 10 (remove) with full contract: flag table, output shape, idempotency semantics, ambiguous-cloud-match candidate format, relationship to `refresh`. Renumbers upload → 11 / delete → 12. Updates flow diagram, `--solution-folder` note, cheat sheet.
• `solution-overview.md` — command tree gets the two new verbs.
• `scenarios.md` — triage rows pointing at the new commands for single-resource create / delete intents.
• `scenarios/manual-edits.md` — opening reframed: create / delete are now CLI-covered; only field-level updates still require a manual edit or SW round-trip.
• `scenarios/virtual-resource.md` — adds the no-bindings path (`resource add --source local`) alongside the binding-driven flow.
• `SKILL.md` — command list in description + Develop reference row.

Test plan

• Markdown links between renumbered steps and new anchors checked.
• No test asserts the old step numbering; `resource_list_smoke.yaml` only exercises `resource list` and remains valid.
• Reviewers: spot-check that an agent reading just Step 9 / Step 10 has enough to call `add` / `remove` correctly (required flags, idempotency, ambiguous match) without flipping back to `--help`.

🤖 Generated with Claude Code

[github-actions]

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

---

PR Review: docs(uipath-solution): document resource add and resource remove

• Read review criteria and project conventions
• Read full diff and existing PR comments
• Read each changed file in full context
• Apply skill-specific and structural checks
• Post review findings

---

Summary

Adds documentation for two new atomic CLI commands (uip solution resource add and uip solution resource remove) across 6 files in the uipath-solution skill. The bulk of the content lands in develop-solution.md as Step 9 and Step 10, with supporting cross-references in the scenarios index, virtual-resource scenario, manual-edits scenario, solution-overview command tree, and the SKILL.md description.

Change-by-Change Review

1. skills/uipath-solution/SKILL.md — description + reference table

Severity: OK

Description updated from resource refresh to resource refresh|add|remove — correctly extends the command list. Character count is 750, well under the 1024 cap. The Develop reference row updated to mention the new commands. Clean.

2. skills/uipath-solution/references/operate/develop-solution.md — Step 9 + Step 10 (bulk of the PR)

Severity: Low

Well-structured. Step 9 (add) covers both --source local and --source cloud modes with full flag table, output shape, idempotency semantics, ambiguous-cloud-match error format, and the comparison table with refresh. Step 10 (remove) documents the positional key argument, output, failure mode, and the critical binding-persistence caveat. Renumbering of upload → Step 11, delete → Step 12 is clean.

Specific observations:

• Line 31: add / remove are described as "the atomic, idempotent siblings" in the flow diagram paragraph, but remove is not idempotent in the usual sense — calling it twice on the same key produces Failure + Resource not found in solution on the second call (line 323). add is genuinely idempotent (returns "Unchanged"). Calling both "idempotent" could mislead an agent into not checking the result of remove. Consider rewording to something like "add is idempotent; remove is atomic (fails cleanly if the key doesn't exist)."
  Fix this →

• Line 383: The "Always verify state after every mutation" gotcha now mentions add, remove, and refresh. The verification script checks .uipx project entries and resources/solution_folder/{package,process}/ — but resource add/remove operate on resource files (e.g., resources/solution_folder/queue/, asset/), not project entries. The existing verification commands (grep ProjectRelativePath, ls package/ process/) wouldn't catch a resource-level mutation failure. This is pre-existing (the gotcha was about project mutations), but now that it name-drops add/remove, an agent following it literally would run irrelevant checks. Consider adding a resource-level sanity check like uip solution resource list --source local --output json or noting that the .uipx/resources agreement check applies to project mutations, while resource mutations should be verified with resource list.
  Fix this →

3. skills/uipath-solution/references/operate/solution-overview.md — command tree

Severity: OK

add and remove correctly added to the resource subtree with accurate one-line descriptions. get changed from └── to ├── to accommodate new siblings. Clean.

4. skills/uipath-solution/references/operate/scenarios.md — triage rows

Severity: OK

Three new triage rows for add-local, add-cloud, and remove-by-key. Links point to the correct anchors (#step-9-add-a-resource-atomically, #step-10-remove-a-resource). Inline CLI snippets give agents enough to act without clicking through. Well placed between the existing virtual-resource and manual-edits rows.

5. skills/uipath-solution/references/operate/scenarios/manual-edits.md — reframe opening

Severity: OK

Opening paragraph correctly reframed: create/delete are now CLI-covered; only field-level updates remain as manual-edit territory. The Step 9–10 link resolves to the correct anchor. Closing sentence reinforces the routing. Clean.

6. skills/uipath-solution/references/operate/scenarios/virtual-resource.md — no-bindings path

Severity: OK

New bullet block clearly presents the two paths (from a binding vs. atomic add). The develop-solution.md Step 9 link is correct. "Same end state on disk; same deploy behavior" is a valuable clarification for agents. Clean.

What's Missing

• No new test task for resource add / resource remove. The existing tests/tasks/uipath-solution/operate/ directory covers resource list but not the new mutation commands. Given that this is a docs-only change documenting CLI commands that require a live Orchestrator tenant, this is understandable but worth flagging as a gap. Severity: Medium (per repo policy for new capabilities lacking test coverage).
• No error-handling guidance in Step 10. Step 9 has an explicit "Ambiguous cloud match" subsection showing the agent what to do on failure. Step 10 mentions the Failure / Resource not found case but doesn't prescribe a recovery action (e.g., "verify the key with resource list --source local, then retry with the correct key"). Minor gap — an agent can figure it out, but the skill's pattern is to be explicit about error paths.

Area Ratings

Area	Status	Notes
Frontmatter	OK	Description under 1024 chars (750), name matches folder, new commands added to command list
E2E Tests	Issue (Medium)	No test task for resource add / resource remove — existing tasks still valid but don't cover new capabilities
Skill Body	OK	SKILL.md reference table updated correctly
References & Assets	OK (Low nits)	All links resolve, no orphaned files, no cross-skill references. Two low-severity accuracy nits in develop-solution.md
Repo Hygiene	OK	CODEOWNERS already covers /skills/uipath-solution/. No secrets, no cross-skill deps, changes scoped to one skill

Issues for Manual Review

• CLI command accuracy: Verify that --source, --kind, --name, --type, --folder-path, --cloud-key flags on resource add and the positional <resource-key> on resource remove match the actual CLI surface from UiPath/cli#2221. Automated review cannot verify CLI flag correctness against the actual tool.
• Output shape: The JSON response bodies (lines 248–263 for add, lines 310–320 for remove) and the ambiguous-match error (lines 271–276) should be spot-checked against actual CLI output.
• Idempotency semantics for remove: Line 31 claims both add and remove are "idempotent" but Step 10 (line 323) says remove on a missing key returns Failure. Confirm whether the CLI team intends remove to be idempotent (return success on already-removed key) or fail-on-missing.

Conclusion

Clean, well-organized documentation PR. The new content follows the skill's existing patterns (flag tables, output shapes, comparison tables, cheat sheet entries, cross-references from scenario files). Two low-severity nits: (1) the "idempotent siblings" label may overstate remove's behavior, and (2) the verify-after-mutation gotcha could benefit from a resource-level check now that it name-drops add/remove. The missing test task is the only medium-severity gap, and it's consistent with the repo's current test coverage posture. Recommend approve with nits.