docs(coded-apps): correct deploy, publish, auth & asset guidance in coded apps skill [APPS-35786]

[ninja-shreyash]

Summary

Closes the APPS-35786 runbook. Each of the 10 gotchas was verified against the live env (codedapp-tool 1.197) or CLI source before deciding if the skill needed a change. Docs-only — no CLI change required.

Points

#	Gotcha	Status	Fix
1	Re-publish same version → version already exists	✅	Corrected message + cause (upload OK, registration rejects dupe)
2	--reuse-client removed; clientId from uipath.json	✅	pack copies uipath.json verbatim; dropped dead flag
3	Deploy non-interactive → pass --folder-key	✔️ already covered	Rule 11
4	Folder name→key; list 50/page; filters need --all	✅	Server-side --all --name + exact-Name match
5	Omit --path-name on upgrade	✅ +corrected	Not always fatal — only a taken/reused slug → routing name must be unique; new slug rewrites URL
6	Don't pass -v; has not been published yet	✅	Indexing-lag row (CLI retries ~15s; wait/rerun)
7	Stale vanity path → hard-refresh	⚪ non-issue	index.html is no-cache; assets content-hashed — normal reload works
8	Login reads full config; headless scope; staging authority	✅	Session model (org/tenant/base/token from uip login, not .env); kept Apps.Read Apps.Write gotcha
9	Reserved words in URL path-name	⚪ non-issue	uipath reserved, microsoft not (ticket stale); CLI error is self-explanatory + list is volatile
10	Import bundled assets, not public//hardcoded	✅	Rule 9 extended

Plus two bonus doc-bug fixes found while testing: publish -v was wrongly documented as "Latest" (it's the first unsorted readdir match), and .env was wrongly listed as the auth source (it's the uip login session).

Verification

Live (popoc/adetenant, alpha): full pack→publish→deploy upgrade cycles; --path-name matrix (same/new/reserved slug × fresh/upgrade) mapping the success ↔ routing name must be unique boundary (5, 9); curl -I cache headers on the deployed URL (7); reserved-word probes (9); all commands ran flagless off the login session (8).

CLI source (codedapp-tool, read-only): deploy.ts (fresh-vs-upgrade branch, uniqueness check, retry [1,2,4,8]s), publish.ts (findPackageByName first-match), resolve-credentials.ts/env-config.ts (flag→session→alt precedence).

🤖 Generated with Claude Code

[github-actions]

Claude finished @ninja-shreyash's task in 4m 24s —— View job

---

PR Review: fix(coded-apps): close deploy/publish/auth doc gaps from APPS-35786

• Read review criteria and project conventions
• Read full diff and changed files
• Check skill structure and cross-skill dependencies
• Verify links and references
• Check for secrets/tokens/personal paths
• Post review findings

---

Summary

Corrects several documentation inaccuracies in the coded-apps skill around auth session model (.env → uip login session), publish -v semantics, --reuse-client removal, --path-name routing behavior, folder resolution with --all --name, and catalog indexing lag troubleshooting. Changes are scoped to three files within skills/uipath-coded-apps/. Verified against CLI source per the PR description.

Change-by-Change Review

1. skills/uipath-coded-apps/SKILL.md (+3/-3)

Severity: Low (with one Medium note)

The three changes are accurate and well-targeted:

• Rule 9 (line 43): Asset bundler guidance added — import via bundler, not public/ or hardcoded /-rooted paths. Correct and addresses a real deploy-time 404 trap.
• Rule 11 (line 45): Folder resolution updated to use --all --name with exact-match filtering and personal workspace carve-out. Correct and significantly more robust than the old "list + match" approach.
• Troubleshooting table (line 192): Error message corrected to the actual CLI output. Good.

Medium note: The Quick Deploy step 5 (line 168) still says uip or folders list --output json without --all --name. This is a terse summary that defers to the reference, but an agent following Quick Deploy literally would hit the old pagination-blind pattern. Consider updating to match Rule 11, or at minimum adding (see Rule 11) as a pointer.

2. skills/uipath-coded-apps/references/commands-reference.md (+29/-29)

Severity: OK

Bulk replacement of From .env → From uip login session across all command tables (push, pull, pack, publish, deploy). Consistent and correct — the CLI resolves these from the session, not a project .env.

Additional good changes:

• --reuse-client row removed from pack options (line 117-118). Correct — flag was removed from CLI.
• --path-name added to deploy options (line 234). Description matches the new routing-name section in pack-publish-deploy.md.
• publish -v description updated (line 170) with the readdir order caveat. Matches the reference file.
• Common Options section (lines 277-284) rewritten from "override options (values default to .env)" to "resolve from uip login session automatically". Clear improvement.

3. skills/uipath-coded-apps/references/pack-publish-deploy.md (+35/-16)

Severity: Medium (two issues)

The bulk of the changes are excellent — the new routing-name section (lines 209-219), OAuth client ID correction (lines 70-73), session callout (line 136), indexing lag troubleshooting row (line 363), and folder resolution rewrite (lines 234-263) are all well-written and operationally precise.

Issue 1 — Agent flow example contradicts new folder guidance (line 344-346):
The "Agent flow" example at line 344 still uses the old pattern:

FOLDER_KEY=$(uip or folders list --output json \
  | python3 -c "...")

This contradicts the new guidance at line 234 which says "resolve it with the server-side --name filter — do not fetch the full list and match client-side." An agent following this example would hit the exact pagination bug the PR is fixing. This should use --all --name "$USER_FOLDER_NAME" to match the corrected example at line 241-255.

Fix this →

Issue 2 — Missing tenant name troubleshooting row still references .env (line 365):
The troubleshooting row says UIPATH_TENANT_NAME not set | Set in .env or pass --tenant-name. Given the PR's theme of correcting .env → session, this row should clarify that the tenant name resolves from the uip login session — Set in .env is misleading in context. The same row is absent from SKILL.md's troubleshooting table, so it's only here.

Fix this →

What's Missing

• Agent flow example not updated (see Issue 1 above) — the old folder-resolution pattern contradicts the corrected canonical guidance in the same file.
• Quick Deploy step 5 in SKILL.md (line 168) still uses the old folder resolution pattern without --all --name. Minor since it defers to the reference, but a literal-following agent would use the old pagination-blind approach.
• No test coverage changes needed — this PR only corrects documentation accuracy, not new CLI workflows.

Area Ratings

Area	Status	Notes
Frontmatter	OK	No frontmatter changes
E2E Tests	OK	Documentation-only PR; existing tests in tests/tasks/uipath-coded-apps/ cover the workflows
Skill Body	OK	Rule 9 and Rule 11 updates are accurate and well-scoped
References & Assets	Issue	Agent flow example contradicts corrected folder guidance; one troubleshooting row still references .env
Repo Hygiene	OK	Changes scoped to one skill; CODEOWNERS present; no secrets or personal paths

Issues for Manual Review

• Publish -v readdir order claim (commands-reference.md:170, pack-publish-deploy.md:114): The PR states -v selects the "first matching .nupkg in unsorted readdir order — NOT the highest version." This is cited as verified against publish.ts's findPackageByName. Since this is a behavioral claim about internal CLI code, it cannot be verified from the docs alone — the PR author should confirm this still holds in the latest CLI release.
• Personal workspace in --all --type personal (pack-publish-deploy.md:260): The text says personal workspace is "not in --all" but then offers uip or folders list --all --type personal as an alternative. If personal workspaces aren't in --all, the --all --type personal alternative wouldn't return them either. Worth verifying which is correct.

Conclusion

Solid, well-researched PR that fixes real documentation inaccuracies verified against CLI source. The corrections are consistent and well-scoped. Two items need attention before merge: (1) the "Agent flow" example at pack-publish-deploy.md:344 still uses the old folder-list pattern, directly contradicting the new guidance 100 lines above — this is the kind of inconsistency that causes an agent to use the wrong approach; (2) one troubleshooting row still references .env counter to the PR's session-model corrections. Both are straightforward fixes. Recommend addressing those two items, then this is good to merge.

---