Skip to content

docs(uipath-solution): carry the traps the slimmed CLI briefing drops - #4968

Open
vlad-uipath wants to merge 3 commits into
mainfrom
docs/uipath-solution-traps-from-cli-briefing
Open

vlad-uipath wants to merge 3 commits into
mainfrom
docs/uipath-solution-traps-from-cli-briefing

Conversation

@vlad-uipath

@vlad-uipath vlad-uipath commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Follow-up to UiPath/cli#6237 (UiPath/cli#5009). That PR cuts the AGENTS.md that uip solution init scaffolds from 121 KB to 11 KB. What's left is a one-line Traps list that points here for the detail. This PR adds that detail to uipath-solution and fixes statements the skill had wrong.

Added

  • references/pack-build-guide.md (new, linked from SKILL.md). It covers:
    • reading Data.Projects on a failed pack
    • dependency feeds (--feed-folder, --nuget-sources-config-path, and why a bare --exclude-configured-sources usually breaks restore)
    • signing
    • analyzer and governance: pack exits 0 when AutomationOps can't be asked; the export-with-envelope rule
    • the coded-app build inside solution pack
    • member package ids
    • solution cleanup (no prompt, and the feeds decide what it deletes)
  • develop-solution.md:
    • Data.ResourcesPending
    • Flow bindings come from the .flow
    • refresh warnings
    • a failed Resource Catalog lookup is not "not found", plus the CI pattern
    • resources add / remove / edit --patch rules
    • debugging is not deploying
    • Studio Web upload 401/403 and 20039. A 401/403 whose challenge is invalid_token is worth one fresh login; any other is about grants. Only an external app's 401 becomes permission_denied (a user's keeps authentication_required). A SolutionId from another tenant answers 404, not 401/403
    • resources remove: the three refusals by code (project artefact, referenced, hidden), and a coded app's source/uipath_resources.ts adds a removed resource back on refresh or pack
  • pack-and-deploy.md: the deploy list folder filters and publish 409, which leads with uip solution publish <zip> --package-version <new> (the CLI's own 409 instructions), then re-packing.
  • activate-and-manage.md: deploy upgrade --config-file, feed-search failures, and when an external app can act on a non-tenant feed (a feed check that gets no answer is network_error / RetryLater, not a refusal).
  • failure-modes.md: 12 new rows, and the publish row now covers 409.

The governance, --exclude-configured-sources and publish 409 traps are stated once (pack-build guide, Version Bumping) and linked from the other places.

Fixed (each checked against current uip solution … --help):

  • deploy upgrade takes --config-file. The skill said it takes no config file.
  • resources add --name is optional with --cloud-key. On remote, --type must match the resource's type; it does more than override.
  • resources remove accepts compound keys, not only GUIDs.
  • deploy list --folder-path / --folder-key filter on the server, so Total counts matches.
  • The pack --name default is the solution folder name (or the .uis name), not the .uipx name.
  • The packages delete examples were missing the required --yes.
  • External-app upgrade of a folder-feed or Personal Workspace deployment: allowed by key when the server echoes the feed header, otherwise refused. The CLI's own --help still says "always refused"; that will be raised on the CLI side.

Studio Web allowlist. tests/scripts/studioweb-browser-commands.json gets 5 allow entries with reasons, for passages that describe Node-CLI-only commands:

  • solution pack and solution cleanup in the pack-build guide
  • codedapp init (prose)
  • tools install (ResourcesPending)
  • rpa debug start in the debugging paragraph

The alternative is Studio Web flavor overrides for those passages. Happy to switch if reviewers prefer that.

Checks

  • Pass, after the rebase onto main and the review fixes: skills:validate, skills:check-links, studioweb-browser-commands.test.mjs (20/20), and the pre-commit description check. check-sensitive-content.py --strict reports findings only in files this PR does not touch.
  • check-skill-verbs.py: 35 findings against 34 on main. The extra one is a false positive on tools install codedapp, the same kind as the existing tools install rpa.
  • skills:test: two packaging tests fail the same way on unmodified main.

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @vlad-uipath's task in 2m 3s —— View job


Summary

This PR adds the detail that the slimmed AGENTS.md scaffold now leaves out. It adds a new pack-build-guide.md and new gotchas in develop, pack, activate and failure-modes. It also fixes several CLI claims the skill had wrong: deploy upgrade --config-file, resources add --name/--type, compound keys for resources remove, server-side filtering in deploy list, the pack --name default, and the missing --yes on packages delete. The content is accurate as far as I can check and well organised. One flavor issue should be fixed before merge, and there is some duplication worth trimming.

Change-by-Change Review

1. SKILL.md: debug line and Pack Build Guide row ship to the Studio Web flavor

Medium

  • SKILL.md:108 is a new sentence outside any flavor block: "refresh, then run the lead project's own debug command…". The Studio Web overrides say resources refresh is Node-CLI-only (skill-flavors/studioweb/uipath-solution/SKILL.md, develop-solution-row, and references/develop-solution.md:21-22). Studio Web agents now get a routing instruction that contradicts their own flavor.
  • SKILL.md:153: the new Pack Build Guide row also reaches Studio Web, whose override says "No pack, restore, login, or upload steps in Studio Web." The allowlist entries quiet studioweb-browser-commands.test.mjs, but the agent still gets routed to the Node-only guide.
  • On your allowlist-vs-override question: keep the allowlist for statements inside pack-build-guide.md, develop-solution.md's ResourcesPending note and the debug block. For the two SKILL.md routing lines, use sparse overrides. Following .claude/rules/skill-structure.md § Flavor-Aware Skill Edits:
    • Wrap line 108 in a debug-or-run block. The Studio Web override drops the refresh and points at the Debug button or the project's debug command.
    • Wrap the row in a pack-build-guide-row block with an empty Studio Web override.
    • Then run npm run skills:validate && npm run skills:build and inspect the studioweb tree.

Fix this →

2. references/pack-and-deploy.md:83, :85: restate the linked guide

Medium (Reference Pointer Discipline)

Both paragraphs repeat the mechanism that pack-build-guide.md § Dependency feeds and § Governance does not gate a build already explain:

  • adds, does not replace
  • a bare --exclude-configured-sources usually fails the restore
  • exits 0, stderr warning, --log-level error hides it

Two copies will drift apart. Cut each to a single bridging sentence plus the link. For example: "To control where dependencies resolve from, see Dependency feeds." and "pack exits 0 even when governance could not be enforced; see Governance does not gate a build." The new option rows at :68-73 already link correctly.

Fix this →

3. Publish-409 / "never delete to reuse a version" rule stated three times

Low

The rule appears in full at pack-and-deploy.md:509 and is paraphrased at activate-and-manage.md:295 and in the failure-modes.md:23 row. Keep the full statement in § Version Bumping and leave a link elsewhere. The failure-modes row is fine as a symptom pointer.

4. activate-and-manage.md: deploy upgrade --config-file, feed-search failures, external-app upgrade

OK

The new § Change a live deployment's configuration is clear. The numbered rules (pin --version, keep only changed resources) prevent the expensive mistakes. The cross-link from pack-and-deploy.md:418 resolves. The old "deploy upgrade takes no config file" claim has been removed from both places.

5. develop-solution.md: ResourcesPending, Flow bindings, refresh warnings, failed lookups, remove/edit rules, debug, upload refusals

OK

Good additions. The table for failed Resource Catalog lookups and the CI pattern are prescriptive. The tables of remove refusals and upload failures give the agent a stop condition ("retrying never helps").

6. references/pack-build-guide.md (new)

OK

  • Kebab-case -guide.md, reachable from SKILL.md, every anchor I checked resolves.
  • Placeholders use <UPPER_SNAKE>. env.SIGNING_PASSWORD keeps the secret out of the docs.
  • The cleanup section correctly treats the missing prompt as a hazard, telling the agent to commit first and then run --dry-run.

7. failure-modes.md: 11 new rows

OK. Each row links to the authoritative section instead of restating it.

8. tests/scripts/studioweb-browser-commands.json

OK. All 5 entries give reasons. See item 1 for which of them would be better as overrides.

What's Missing

  • Studio Web flavor overrides for the two SKILL.md routing additions (item 1).
  • Tests. Several behaviours are new and none has a task: deploy upgrade --config-file as a configuration change, reading Data.Projects on a failed pack, and governance passing without enforcement. The best candidate is a diagnose_*_integration task for "change a live deployment's connection link without uninstalling", since the old skill taught the wrong answer there. Under the repo guidelines this counts as Medium, but it doesn't need to block this PR.

Area Ratings

Area Status Notes
Frontmatter OK Unchanged
E2E Tests Issue New capabilities have no task (see What's Missing)
Skill Body Issue SKILL.md:108 and :153 leak into the Studio Web flavor
References & Assets Issue Pointer duplication at pack-and-deploy.md:83,85; links and anchors resolve
Repo Hygiene OK Changes stay in this skill; no secrets or personal paths; no cross-skill links

Issues for Manual Review

  • Flag-level CLI claims. assets/uip-catalog-snapshot.json lists verbs only, so I could confirm the verbs (solution cleanup, deploy upgrade, agent debug, maestro flow|case debug, rpa debug start, tools install) but none of the flags. These still need checking against --help:
    • --feed-folder, --exclude-configured-sources
    • --signing-certificate-password env.<VAR>, --signing-timestamp-server
    • --skip-build, cleanup --skip-imports
    • deploy list --operation-status / --activation-status / --folder-key
    • --governance-product and its hidden alias --automation-ops-profile
  • External-app upgrade wording (activate-and-manage.md:155) deliberately contradicts the CLI's current --help ("always refused"). Please link the CLI issue once it is filed, so a later reviewer doesn't "fix" this back.
  • Debug commands in Studio Web. Is uip maestro flow debug / uip rpa debug start actually exposed in the browser host? That decides what the Studio Web debug-or-run override from item 1 should say.

Conclusion

Request changes (minor). The content is a clear improvement and fixes real errors. Before merge, add the two Studio Web flavor blocks (item 1) and trim the restated paragraphs in pack-and-deploy.md (item 2). Item 3 and the tests can follow later.

vlad-uipath and others added 3 commits November 19, 2026 22:41
The CLI's scaffolded AGENTS.md shrinks to a one-line Traps list that points
here, so the full detail behind each trap now lives in the skill: pack
governance, dependency feeds, signing, coded-app builds, member package
ids and cleanup (new pack-build-guide.md); Flow bindings, refresh warnings,
failed Resource Catalog lookups, resources add/remove/edit rules, debugging
vs deploying and Studio Web upload refusals (develop-solution.md); deploy
list folder filters and publish 409 (pack-and-deploy.md); upgrade
--config-file, feed-search failures and external-app feed upgrades
(activate-and-manage.md); and matching failure-mode rows.

Fixes stale statements: deploy upgrade does take --config-file; resources
add --name is optional with --cloud-key and --type must match on remote;
resources remove takes compound keys; deploy list folder filters run
server-side; pack --name defaults to the solution folder name; packages
delete needs --yes.

Refs UiPath/cli#5009

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…here the tenant has the host libraries feed

Matches UiPath/cli#6163: the tenant's library feeds stay in use, so the
official packages resolve where the tenant includes UiPath-Official.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…aps review found

- Upload 401/403: a challenge of invalid_token is worth one fresh login.
  Any other refusal is about grants; only an external app's 401 becomes
  permission_denied, a user's keeps authentication_required. A SolutionId
  from another tenant answers 404, not 401/403, so it is no longer named
  as a cause.
- Publish 409: lead with publish --package-version, then re-pack.
- External-app upgrade: a feed check that gets no answer is network_error
  / RetryLater, not a refusal.
- resources remove: name the hidden-resource refusal, and say that a
  coded app's source/uipath_resources.ts adds a removed resource back.
- Link to the governance, --exclude-configured-sources and 409 traps
  instead of repeating them; uppercase the deploy upgrade placeholders.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vlad-uipath
vlad-uipath force-pushed the docs/uipath-solution-traps-from-cli-briefing branch from 83f03ea to be37e82 Compare November 19, 2026 20:45

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant