@uipath/solution-tool 1.203.0-preview.212 → 1.204.0-preview.211

package/dist/templates/AGENTS.md

@@ -49,7 +49,7 @@ You must manage membership via the CLI, never by editing the manifest. All these
 | Unregister a project (does not delete the project files on disk) | `uip solution projects remove <project-path> [<solution-file>]` |
 | List projects in the solution | `uip solution projects list` |
 
-The `uip ...` scaffolders (`agent init`, `maestro flow init`, `maestro bpmn init`, `maestro case init`, `api-workflow init`, `codedapp init`, and `function init` for Python functions only) **auto-register** the new project when run inside a solution directory — they walk up for the enclosing `.uipx` and add it to `Projects[]` automatically, so a separate `project add` is not needed. Pass `--skip-solution-registration` to scaffold standalone without registering; the output's `Data.SolutionRegistration.Status` is then `OptedOut`. The full set of `Status` values is: `Registered` / `AlreadyRegistered` (added in this run / already present), `NotInSolution` (no enclosing `.uipx` found), `OptedOut` (`--skip-solution-registration` passed), `Skipped` (a candidate solution was found but registration was not safe to attempt — e.g. multiple `.uipx` in one directory, or the project sits outside the solution dir), and `Failed` (manifest read/parse/write error).
+The `uip ...` scaffolders (`agent init`, `maestro flow init`, `maestro bpmn init`, `maestro case init`, `api-workflow init`, `codedapp init`, `rules init`, and `function init` for Python functions only) **auto-register** the new project when run inside a solution directory — they walk up for the enclosing `.uipx` and add it to `Projects[]` automatically, so a separate `project add` is not needed. Pass `--skip-solution-registration` to scaffold standalone without registering; the output's `Data.SolutionRegistration.Status` is then `OptedOut`. The full set of `Status` values is: `Registered` / `AlreadyRegistered` (added in this run / already present), `NotInSolution` (no enclosing `.uipx` found), `OptedOut` (`--skip-solution-registration` passed), `Skipped` (a candidate solution was found but registration was not safe to attempt — e.g. multiple `.uipx` in one directory, or the project sits outside the solution dir), and `Failed` (manifest read/parse/write error).
 
 ## Project Types
 
@@ -66,14 +66,14 @@ A solution can contain multiple projects of different types. The table below lis
 | `AppV2` | Coded App — web application | `uip codedapp init <path>` | `uipath-coded-apps` |
 | `Function` | UiPath Function (JS / TS / Python) | `uip function new [name]` | `uipath-functions` |
 | `Api` | API Workflow project | `uip api-workflow init <name>` | `uipath-api-workflow` |
-| `BusinessRules` | Business rule — one or more DMN decisions. Ships as a `.uirule`: an archive holding the project's `.dmn` files and the `entry-points.json` that names which decisions a caller may invoke and with what arguments. Not wrapped in a `.nupkg`, and the solution's `businessRule` resource points at it by file name. A project with no `entry-points.json` still ships as a bare `.dmn`, which exposes no arguments. `restore` and `validate` are no-ops for this type. | no CLI scaffolding — authored in Studio Web | none |
+| `BusinessRules` | Business rule — one or more DMN decisions. Ships as a `.uirule`: an archive holding the project's `.dmn` files and the `entry-points.json` that names which decisions a caller may invoke and with what arguments. Not wrapped in a `.nupkg`, and the solution's `businessRule` resource points at it by file name. A project with no `entry-points.json` still ships as a bare `.dmn`, which exposes no arguments. `restore` and `validate` are no-ops for this type. | `uip rules init <name>` | none |
 | `Entity` | Data Fabric entity project — one folder per project, one `.entity` pointer file per entity; the schema itself lives in `resources/solution_folder/entity/native/<Name>.json`. Emits no package: the entity resources are the deployable payload, so `solution pack` validates the project instead of building it. | no CLI scaffolding — entity projects are modelled in the UiPath VS Code extension. Do not hand-write the `.entity` file or its resource: the pointer and the schema must stay in step, and `solution pack` fails if they do not. | `uipath-platform` (covers `uip df` entities, records and choice sets) |
 | `Connector` | Integration Service connector | no CLI scaffolding — use `uip is connectors` to list / get / export existing connectors | `uipath-connector-builder` |
 | `WebApp` | Legacy low-code UiPath App (the coded variant is `AppV2`) | no CLI scaffolding | none |
 
 Install the skills with `uip skills install`. The general-purpose `uipath-platform` skill covers what isn't in a type-specific skill, and `uipath-solution` covers the solution lifecycle itself.
 
-`BusinessRules`, `Library` and `Tests` projects declare no solution resources — `uip solution resources refresh` skips them instead of minting anything.
+A `BusinessRules` project gets its `businessRule` resource when it is added to the solution; `Library` and `Tests` projects declare no solution resources. `uip solution resources refresh` skips all three.
 
 **`Library` is not a project type here.** A library is a reusable `.nupkg` consumed as a NuGet dependency, so `projects add` / `import` reject it and auto-registration returns `SolutionRegistration.Status: "Skipped"`. Publish it on its own (`uip rpa pack <project-dir> <output-path>`, then `uip or libraries upload --file <nupkg-path>`) and either reference it from a project's dependencies or attach it to this solution as a resource: `uip solution resources add --source remote --kind Library --name <library-name>`.
 
@@ -96,8 +96,9 @@ Run `uip login` first — most steps below need an authenticated session, includ
 # 1. Authenticate
 #    Interactive (browser OAuth):
 uip login
-#    Non-interactive (CI / CD) with client credentials:
-uip login --client-id <ID> --client-secret <SECRET> --tenant <TENANT>
+#    Non-interactive (CI / CD) with client credentials — read the values from
+#    environment variables so the secret stays out of shell history:
+uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET --tenant <TENANT>
 
 # 1a. (Optional) Restore project dependencies before packing. Resolves NuGet
 #     deps (including authenticated Orchestrator feeds) so pack can compile.
@@ -133,7 +134,7 @@ uip solution deploy run \
     --config-file config.json
 
 # 7. The deploy returns a pipeline deployment ID — track it:
-uip solution deploy status <pipeline-deployment-id>
+uip solution deploy status <pipeline-deployment-id>    # that run's progress and errors; a deployment name or key gives the record's state instead
 
 # 8. List every deployment in the active tenant
 uip solution deploy list
@@ -141,17 +142,19 @@ uip solution deploy list
 
 `deploy run` also takes `--parent-folder-key <key>` in place of `--parent-folder-path`, and `--personal-workspace` to deploy into your Personal Workspace instead of the tenant.
 
-**A Personal Workspace deploy does not wait.** A tenant deploy polls until the install reaches a terminal state and reports `Status: "DeploymentSucceeded"`. `--personal-workspace` goes through a different endpoint that answers as soon as the install is accepted, so it reports `Status: "DeploymentStarted"` plus a `NextSteps` line and returns while the install is still running. Anything you do to that deployment next — `deploy uninstall`, `deploy activate`, an upgrade — is refused with `HTTP 400 … cannot be uninstalled` (or the equivalent) for as long as the operation is in progress.
+**Listing one folder's deployments.** `uip solution deploy list --folder-path <path>` (or `--folder-key <key>`) lists the deployments installed into that folder. The Solutions search does the filtering, so `--limit`, `--offset` and `Pagination.Total` all count matching deployments: page with `--offset <previous Offset + Returned>` while `Pagination.HasMore` is true. The match is on the folder's **full path** (`Shared/Finance`, not `Finance`), exact and not case-sensitive, and deployments in its subfolders are **not** included — list each subfolder with its own call. `FolderPath` is the folder the deployment was installed *into*; a row's `FolderKey` is the deployment's own solution folder one level below it, so passing that key to `--folder-key` matches no deployment — use the key of the `FolderPath` folder instead.
 
-Add `--wait` when the next step needs the deployment settled:
+**Every deploy waits, and validates first.** `deploy run` — tenant, `--personal-workspace` or `--feed` — goes through the Pipelines install, which validates the package against the target *before* it schedules the install, then polls the run to a terminal state and reports `Status: "DeploymentSucceeded"` with `DeploymentKey`, `PipelineDeploymentId` and `InstanceId`. A validation failure ends in `Status: ValidationFailed` with the per-resource errors in `Instructions`, and nothing is installed. `--timeout <seconds>` (default 360) bounds each polling phase; running out exits `2` with `ErrorCode: timeout` and `Retry: RetryLater` — "may still be running", so check `uip solution deploy status <pipeline-deployment-id>` rather than treating it as a failed install. `--wait` is accepted for backwards compatibility and does nothing. Deploying into a Personal Workspace or a folder feed needs a **user session**: under an external app's client-credentials token, `--personal-workspace` is refused before anything is requested and `--feed` is refused once it resolves to a feed other than the tenant feed (`ErrorCode: permission_denied`), because the server ignores the feed header on that token type and the install would otherwise land on the tenant feed under the requested name. A `--feed` that names the tenant feed is fine from CI/CD, as is omitting the flag. Reading a feed is the same: `deploy list` and `deploy status` with `--personal-workspace` or a folder-feed `--feed` refuse an external app (`ErrorCode: permission_denied`) instead of showing the tenant feed's records under that feed's name. A session whose kind cannot be read from its token is refused the same way; `uip login` records an interactive login as a user session.
 
-```bash
-uip solution deploy run ... --personal-workspace --wait --timeout 300
-```
+**Upgrading in place.** `uip solution deploy upgrade <deployment-key>` (the `Key` from `deploy list`) or `uip solution deploy upgrade --name <deployment-name> --package-name <pkg>` moves an existing deployment to another published version of its package (newest by default, or `--version <version>`) and keeps the values already set on it. Both forms work from a CI/CD pipeline signed in as an external app. With a key, the deployment's name, package and feed are read from the server, so no `--package-name` or `--personal-workspace` is needed, and the result also carries `FromVersion` and `InstallDeploymentKey` — the key that stays the same across upgrades, so store that one rather than `DeploymentKey`, which changes with every upgrade. It uses the same Pipelines install, so it validates before it installs: on success it reports `Status: "DeploymentSucceeded"`, `Operation`, `DeploymentStatus`, `Actions`, `ToVersion`, `PipelineDeploymentId` and `DeploymentKey`; on a validation failure it reports the errors and the deployment stays on its current version. `--no-wait` returns `Status: "Accepted"` as soon as the install is queued. An external app can only upgrade tenant-feed deployments: the server ignores the feed header on client-credentials requests, so a Personal Workspace or folder-feed deployment is refused and needs a user session.
+
+**Key or name — how the two forms differ.** The key form makes one extra Pipelines call, the deployment lookup, and needs nothing else: it works on any server that has that lookup. On a server without it, a user session reads the key through the Solutions API instead (tenant feed, or your Personal Workspace with `--personal-workspace`; a folder-feed deployment needs the name form) and the result carries no `FromVersion`; an external app gets `ErrorCode: not_found`, and the message points at the name form. The name form needs `--package-name` because the install route is addressed by name and nothing name-keyed in Pipelines reports a deployment's package; with `--version` as well it makes no version lookup. It does check the name exists first (the same route would otherwise treat an unknown name as a fresh install and create a deployment), so a typo fails with `ErrorCode: not_found` instead of deploying. A name whose deployment was *uninstalled* is caught the same way — the CLI checks the deployment search, which an external app can read only on servers that serve the Pipelines search — so from CI/CD on an older server address such a deployment by key, which reads its status. Find the key, the name and the package with `uip solution deploy list`.
+
+**`Operation` tells you what actually happened.** The endpoint is unified, so asking for the version already deployed is a *configuration change*, not a version move. `Operation: "VersionChange"` means the version moved; `"ConfigurationChange"` means it did not. Check it rather than assuming `DeploymentSucceeded` implies a new version. `DeploymentStatus` says whether the new version runs: `SuccessfulActivate` means it does; `SuccessfulInstall` with `SetupActivation` in `Actions` means it is installed but the previous version keeps running until activation is set up (`uip solution deploy activate`, or Setup activation in Orchestrator).
 
-With `--wait` the command polls the deployment to a terminal state inside `--timeout`, reports `Status: "DeploymentSucceeded"` and drops `NextSteps` (there is nothing left to check). A terminal failure exits `1` as `Deployment '<name>' failed (OperationStatus: Failed): <reason>`, where the reason is the server's validation result (`the server reported no reason.` when it gives none). Still running when the timeout expires exits `2` with `ErrorCode: timeout` and `Retry: RetryLater` — "may still be running", so retry or check `deploy list` rather than treating it as a failed install. Without `--wait` nothing changes, so poll `uip solution deploy list` yourself if you skip it.
+**A rejected attempt leaves a pending draft.** When a `deploy run` or `deploy upgrade` stops at `ValidationFailed` (or a conflict or scheduling error), nothing is installed and the live version keeps running, but the attempt stays behind as a *draft* — its key is the `deploymentKey` in the failure's `Instructions`. While the draft exists it owns the deployment, as in the Orchestrator UI (which offers only "continue editing" and "delete draft"): re-running the same `deploy run` with a corrected `--config-file` and the **draft's** version re-validates it with the new file (settings and resource links the file does not name keep the rejected values). Any other version is refused before anything is sent (`ErrorCode: invalid_argument`) — including the version that is live now, which the server would otherwise answer by installing the draft's version instead. Under an external app that check only warns and the deploy goes ahead — and the server then runs the draft, installing the draft's version — so from CI/CD ask only for the draft's version, or discard the draft first. `deploy upgrade` sends no configuration, so it refuses a deployment with a pending draft (`ErrorCode: invalid_argument`, naming the draft's key and version) rather than re-run the rejected attempt; once the cause is fixed, `uip solution deploy upgrade <draft-or-deployment-key> --discard-draft` deletes the draft and upgrades the live version with its own configuration, and reports the deleted key as `DiscardedDraftKey`. Address the deployment by key for this from CI/CD — on an older server the name form can only find the draft with a user session. A draft still being validated cannot be discarded yet (`Retry: RetryLater`). A Setup activation started in Orchestrator and left unfinished is a draft too, of the live version: both commands refuse while it exists and name it as such — finish it in Orchestrator, or discard it the same way. A deployment whose *first* install never completed has nothing to upgrade: fix and re-run its `deploy run`, or delete the draft in Orchestrator.
 
-**One deployment per package.** `deploy run` always creates a *new* deployment in a *new* Orchestrator folder — it never updates an existing one, and it cannot deploy into a folder that already exists (Orchestrator renames the folder instead, `MySolution` -> `MySolution 1`). So if the package is already deployed, the command stops and lists the existing deployments rather than quietly adding another folder. That check is best-effort, not a guarantee: it reads the Solutions search, which needs a user session, so a CI job signed in with an application (client-credentials) account deploys without it, and a failed lookup only logs a warning. In automation, track what you have already deployed instead of relying on the stop. To ship a new version, upgrade the existing deployment in place with `uip solution deploy upgrade <deployment-key>`; to start over, `deploy uninstall` first. Pass `--yes` only when you really do want a second, independent copy. While you are still iterating, validate locally (`solution pack --dry-run`) instead of deploying each attempt.
+**One deployment per package.** `deploy run` always creates a *new* deployment in a *new* Orchestrator folder — it never updates an existing one, and it cannot deploy into a folder that already exists (Orchestrator renames the folder instead, `MySolution` -> `MySolution 1`). So if the package is already deployed, the command stops and lists the existing deployments rather than quietly adding another folder. That check is best-effort, not a guarantee: a failed lookup only logs a warning, and a CI job signed in with an application (client-credentials) account is never stopped by it — an existing deployment is reported as a warning and the deploy goes ahead (on servers without the Pipelines deployment search the check is skipped, with a warning). In automation, track what you have already deployed instead of relying on the stop. To ship a new version, upgrade the existing deployment in place with `uip solution deploy upgrade <deployment-key>`; to start over, `deploy uninstall`, then `deploy delete` to clear the record it leaves in `deploy list` (that record does not block a redeploy — `blocksRedeploy` lets an uninstalled deployment through — so the delete is housekeeping, not a prerequisite). Pass `--yes` only when you really do want a second, independent copy, and give it a different `--name`: the install is keyed on the deployment name, so re-using an existing one updates that deployment in place instead. While you are still iterating, validate locally (`solution pack --dry-run`) instead of deploying each attempt.
 
 **Activation lifecycle.** `deploy run` activates by default. To split the steps:
 
@@ -159,14 +162,33 @@ With `--wait` the command polls the deployment to a terminal state inside `--tim
 uip solution deploy run --skip-activate ...                      # leaves "Inactive (Ready to activate)"
 uip solution deploy activate <deployment-name>     # activate later
 uip solution deploy uninstall <deployment-name> --yes   # remove the deployment + its resources (--yes required; the CLI never prompts)
+uip solution deploy delete <deployment-name> --yes      # remove what uninstall leaves behind (--yes required)
 ```
 
-`uninstall` and `activate` take the deployment name as a **positional** argument (no `--name` flag). `status` takes the **pipeline deployment ID** (the GUID returned by `deploy run`), also positional.
+`deploy run` reports `ActivationStatus: SuccessfulActivate` when the deployment runs. When the install landed but a resource needs "Setup activation" in Orchestrator first, it is still `Result: Success`, with `ActivationStatus: NeedsSetupToActivate`, `PendingResources` and `NextSteps` — the deployment exists, so do **not** run the deploy again; complete the setup, then `deploy activate`. `ReadyToActivate` in the same place means the install landed and the command could not activate it: run `deploy activate`.
+
+`uninstall`, `delete`, `activate` and `status` take the deployment **name** as a positional argument (no `--name` flag). `status` also accepts a **deployment key** (from `deploy list` or `deploy upgrade` — the form that diagnoses a stale key) or the **pipeline deployment ID** from `deploy run` (that run's progress and errors, `Code: SolutionDeployStatus`); by name or key it answers `Code: SolutionDeployment` and reports the record's `Operation`, `OperationStatus`, `ActivationStatus`, `Actions`, and `NextSteps` when it is not live. A name is found across feeds; a key outside the tenant feed needs `--personal-workspace` or `--feed <name-or-key>`, as with `deploy list`. `Superseded: null` means the CLI could not tell — the chain search failed or holds no row for the key — and the fields are the requested record's own; take the current key from `deploy list`.
+
+**Two status axes.** `OperationStatus: Successful` means the last operation's content landed. `ActivationStatus: Active` means the deployment runs. An upgrade can land `Successful` *and* `NeedsSetupToActivate`: the new version is installed but does not run until "Setup activation" is completed in Orchestrator (Tenant > Solutions > Deployments); the previous version keeps running meanwhile. The UI words the same states differently: `NeedsSetupToActivate` shows as **Inactive (Needs setup)**, `Operation: VersionChange` as **Change version**, `Operation: ActivationSetup` as **Activation setup** — and the UI lists every record of a deployment, where `deploy list` shows only the newest. `deploy upgrade` reports both axes; when not `Active` it adds `PendingResources` (the resources the service flags as needing configuration — Integration Service connections, typically — each with the `Reason` the activation validation gives, such as a connection that needs authenticating) and `NextSteps`. "Setup activation" has no CLI command **on an existing deployment**: `deploy config link` maps a resource to an existing one only in the config file a new `deploy run` consumes, `deploy upgrade` takes no config file, and the `resource`/`resources` verbs edit the solution project, not a deployment. `deploy activate` is refused (`4007 … cannot be activated`) until the setup is done in Orchestrator.
+
+**A key is one record, not the deployment.** Every operation creates a new deployment record with its own key: `deploy run` the Install record, `deploy upgrade` a VersionChange one (`DeploymentKey` in its output; `InstallDeploymentKey` is the one that never changes). `deploy list` shows the newest per deployment. A key from before an upgrade is *superseded*: the Solutions record still answers as it was — old version, `Active`, `Upgrade` offered — but `deploy upgrade <key>` resolves it to the deployment's current generation through the Pipelines lookup and upgrades that, and `deploy status <key>` reports `Superseded: true` with `CurrentDeploymentKey`. Store `InstallDeploymentKey`, or take the current key from `deploy list`.
+
+**`uninstall` and `delete` are never both available.** The service offers one action per state, and `deploy list` tells you which:
+
+| Deployment state | `Actions` | What removes it |
+|---|---|---|
+| Installed | `SetupActivation, Uninstall, Upgrade` | `deploy uninstall` |
+| Uninstalled | `Delete` | `deploy delete` |
+| Never installed (`Draft`, e.g. a failed install) | `Install, Delete` | `deploy delete` |
+
+So a full clean-up of a live deployment is two commands: `uninstall` removes its resources and folder, `delete` then removes the deployment itself. `delete` reads the action list first, and when the record lists actions but not `Delete` it says so and names the command to run instead — it never sends a request the state forbids. A record that lists **no** actions is the exception: nothing is known about it, so the request goes out and the server answers.
 
 `uninstall` waits out an operation that blocks it: when Orchestrator refuses because the deployment still has something running, the CLI polls until that finishes and then sends the request again, all inside `--timeout` (which covers the whole command, the status poll included). If it is still busy when the timeout expires you get exit `2` with `ErrorCode: timeout` and `Retry: RetryLater` — retry later, do not treat it as permanent. A refusal for any other reason (superseded, inactive, unknown name) still fails immediately with exit `1`.
 
 Neither `uninstall` nor `activate` takes a feed flag, and neither needs one: they find the deployment themselves — tenant feed first, then your Personal Workspace, then the folder feeds you can reach — and scope their requests to whatever feed holds it. So the `deploy activate <name>` that `--skip-activate` points you at works the same on a `--personal-workspace` or `--feed` deployment as on a tenant one. The cost is one extra lookup per call, and a name that exists in no feed you can see is reported as not found rather than as a blocked uninstall.
 
+`deploy delete` and `deploy status <name>` (without a feed flag) find a name the same way. All four say "not found" only when every feed answered — with one exception: under an external-app login, `deploy status <guid>` for a GUID that is no deployment key still says "not found" when only the feeds after the tenant could not be searched, or when the tenant search refused the login (401/403), because an app login cannot read those feeds at all. When a feed cannot be searched — the feed service is down or refuses the session, the list of feeds cannot be read or gives a feed no key, or the tenant search itself fails — and no other feed has the name, they fail with a message that names the feeds they could not search instead of calling the name unknown. `ErrorCode` then comes from that failure (`server_error`, `network_error`, `authentication_required`, `permission_denied`, …, or `unknown_error` when it has no known class) and is never `not_found`; `Retry` follows it — `RetryLater` for an outage, `RetryWillNotFix` for a 401 or 403, and also `RetryWillNotFix` when every feed that could not be searched is one the list gives no key, since a retry gets the same list. Do not treat the name as wrong: do what `Instructions` say (log in again, fix the session's access, or retry later). To check one feed yourself, pass `--personal-workspace` or `--feed <name-or-key>` to `deploy status` or `deploy list` — but `--feed` is resolved through the same list of feeds, so when that list is what failed only `--personal-workspace` helps, and `--feed` cannot pick a feed the list gives no key. When the tenant feed refuses an `activate` or `uninstall` for its own reason (401, 403, 409, 422, 429, a 5xx), that failure is reported as it is.
+
 ## Dependency Feeds
 
 Packing an RPA project restores its NuGet dependencies first, so `pack` and `restore` both need to know which feeds to resolve against. So does `cleanup`: deciding that a dependency is *unused* means resolving the dependency graph, so it reads the same feeds. All three take the same three options.
@@ -209,13 +231,13 @@ The analyzer rule configuration comes from whichever governance flag you use. `-
 
 Whenever you are signed in, the tenant is asked first — including when you pass `--governance-file-path`. There are three possible answers and each does something different:
 
-- **The tenant publishes a policy.** That policy is what the analyzer uses. A `--governance-file-path` passed alongside it is refused with exit `1`, naming the file and the product whose policy applies — a flag in your own pipeline does not lift the organisation's policy.
+- **The tenant publishes a policy.** That policy is what the analyzer uses, whatever else you passed. A `--governance-file-path` alongside it is not used; you get a warning and the pack carries on — a flag in your own pipeline does not lift the organisation's policy.
 - **The tenant publishes nothing.** The analyzer uses your `--governance-file-path` if you passed one, otherwise the rules shipped with the WorkflowCompiler.
-- **The question could not be answered** (expired token, no route, the service is down). The pack still succeeds and nothing fails: you get a warning naming the reason (`unauthorized`, `notFound`, `serverError`, `timedOut`, …), and the analyzer uses your `--governance-file-path` if you passed one, otherwise the shipped rules. Not knowing whether you are governed is not a reason to break a build.
+- **The question could not be answered** (expired token, no route, the service is down). The pack still succeeds and nothing fails: you get a warning naming the reason (`unauthorized`, `notFound`, `serverError`, `timedOut`, …), shown only at `--log-level warn` or lower (see below), and the analyzer uses your `--governance-file-path` if you passed one, otherwise the shipped rules. Not knowing whether you are governed is not a reason to break a build.
 
 With no signed-in tenant there is nothing to ask, so a `--governance-file-path` is simply used and an offline pack keeps working.
 
-Note what this means for CI: a pack that could not reach AutomationOps still returns `Result: Success` and exit `0`, so a stage using `--governance-product` as a governance gate goes green while having enforced the shipped defaults. The warning in the log is what tells you which happened — `uip solution pack` reports on governance, it does not enforce it. Strict, fail-closed behaviour belongs to design-time hosts, not to this command.
+Note what this means for CI: a pack that could not reach AutomationOps still returns `Result: Success` and exit `0`, so a stage using `--governance-product` as a governance gate goes green while having enforced the shipped defaults. The warning in the log is what tells you which happened — `uip solution pack` reports on governance, it does not enforce it. That warning is a `warn`-level log line, and the default `--log-level` is `error`, which hides it. A stage that needs to know passes `--log-level warn` and reads stderr. To read it from a file instead, pass `--log-file <path>` together with `--log-level warn`: the level filter runs before a line is sent to the file, so `--log-file` alone still drops the warning. Strict, fail-closed behaviour belongs to design-time hosts, not to this command.
 
 ## Dependency Feeds
 
@@ -349,9 +371,14 @@ A resource is either **virtual** — declared locally now, provisioned when the
 
 ```bash
 uip solution resources add --source local  --kind Queue   --name InvoiceQueue
+uip solution resources add --source local  --kind Asset   --type Credential --name ApiLogin
 uip solution resources add --source remote --kind Process --name Existing --folder-path Shared
 ```
 
+`--type` picks the subtype for kinds that have one. For assets it takes the Orchestrator name (`Text`, `Integer`, `Bool`, `Credential`, `Secret`) or the solution name (`stringAsset`, `integerAsset`, `booleanAsset`, `credentialAsset`, `secretAsset`), case-insensitive. A subtype the kind does not have fails with `ErrorCode: invalid_argument`, and `Instructions` lists the valid ones. A kind with no subtypes (a queue) refuses `--type`; a connection's connector type passes through. An empty `--type ""` is refused for every kind; leave the option out instead. With `--source local`, adding a name that already exists with a different `--type` fails instead of returning the existing one. With `--source remote`, `--type` must match the resource's own type: it narrows same-name matches and never changes what gets imported.
+
+`--name` is checked before anything is written, because a local resource becomes a file under `resources/solution_folder/<kind>/<name>.json`: a blank or whitespace-only name, a name over 256 characters, or one containing path separators, control characters or any of `: * ? " < > |` fails with `Result: Failure` and a `Message` that names the option (`--name must not be blank`, `--name contains unsafe characters`). `uip agent memory add` runs the same check on `--memory-space` when it declares a memory space in the solution.
+
 **Not every kind can be virtual.** Queues, assets and buckets can — the solution creates them on deploy. Kinds that must already exist somewhere (processes, connections, apps, indexes, entities) cannot be conjured from a local declaration; they need `--source remote`, or a `deploy config link` onto an existing resource at deploy time.
 
 `--source local` does **not** enforce that. It succeeds for any kind, prints `Result: Success`, and writes a stub — the check that would catch it is not on this code path. The failure surfaces later, at deploy. Two ways to catch it early:
@@ -368,8 +395,11 @@ uip solution resources list        # everything declared in this solution
 uip solution resources list --source remote --kind app --include-version
                                    # classic Apps in Orchestrator, with the version deployed per folder
 uip solution resources list --search <term>    # filter by name
+uip solution resources list --limit 20 --next-page <cursor>   # the 20 rows after the previous page
 ```
 
+A listing returns at most 50 rows unless you pass `--limit`. Check `Pagination.HasMore` before treating the rows as complete. The resource catalog pages by cursor, so `--offset` accepts only `0`: to get the next page, pass the previous response's `Pagination.NextPage` to `--next-page` with the same filters. If the catalog call fails, the command fails; use `--source local` to list only the solution's own resources.
+
 `--include-version` reads the live `version` of the kinds that carry one (`app`,
 `appVersion`, `package`, `process`). It costs one extra call per resource, so it
 is off by default.
@@ -477,10 +507,13 @@ uip or assets create        # create an asset (see --help)
 
 ## Output Conventions for Agents
 
-Two rules make automation reliable:
+Three rules make automation reliable:
 
 1. **Never redirect or drop stderr.** Errors and confirmations go to stderr — `2>/dev/null` will silently hide failures and produce false retries.
-2. **Use `--output-filter <jmespath>`** to extract specific fields rather than piping JSON through external tools. The expression is applied to the `Data` array — start with `[]`, not with `Data[]`. On list commands with a default `--limit`, an explicit `--limit` is required with `--output-filter` (the filter only sees the records fetched). Example: `uip solution packages list --limit 100 --output-filter "[].name"`.
+2. **Use `--output-filter <jmespath>`** to extract specific fields rather than piping JSON through external tools. The expression is applied to the `Data` array — start with `[]`, not with `Data[]`. On list commands with a default `--limit`, an explicit `--limit` is required with `--output-filter` (the filter only sees the records fetched). Example: `uip solution packages list --limit 100 --output-filter "[].Name"`.
+3. **Match the key casing of the unfiltered output.** Filter keys are case-sensitive and most commands print `Data` keys in PascalCase, so write `[].Name`, not `[].name` — the wrong casing matches nothing and returns `Data: []`. A few commands pass their keys through verbatim (`uip maestro flow registry get` is one, where `Node.inputDefinition.fields` is correct). If you are unsure, run the command once without `--output-filter` and read the keys off the output.
+
+A filter that selects nothing still returns `Result: "Success"` with `Data: []` and exit 0 — that is a valid empty answer, not a failure. Check the `Warning` field and stderr. They say which it was: a field name that does not exist (fix the expression), no record matched or the expression resolved to no value (the answer really is empty), or a name that reads below the top level (`Items[].Name` reads `Name` off an `Items` entry, so only `Items` was checked — an empty `Items` is the usual cause, not a bad name).
 
 Standard success shape: `{ "Result": "Success", "Code": "<CommandCode>", "Data": ... }`.
 Standard failure shape: `{ "Result": "Failure", "Message": "<short>", "Instructions": "<actionable>" }`.
@@ -524,10 +557,17 @@ Adjacent groups commonly used alongside solutions:
 |---|---|
 | `Not authenticated` / 401 | `uip login`, then re-run |
 | `upload` fails with 401/403 and `ErrorCode: permission_denied` | Not a login problem — the token was valid when the call went out, so `uip login` mints the same one. Read `Instructions`: for a session on an external application, check that the app has the Studio Web (`StudioWebS2S`) grants, not only the Orchestrator and Solutions ones; for a user, check Studio Web access in the tenant. Then confirm the `SolutionId` in the `.uipx` belongs to the tenant you are logged into — one from another tenant is refused, not reported missing |
+| `packages list` or `deploy list` fails with `ErrorCode: permission_denied` from a CI/CD pipeline | `packages list` reads the Solutions search, which accepts user sessions only, so an external app's client-credentials token is refused (the message says so). `deploy list` reads the deployment search, which accepts an external app on servers that serve `POST /v1/pipelines/deployments/search`; it is refused only on an older server, or with `--personal-workspace` or a folder `--feed`, whose feed the server ignores for an app. `uip login` with the same app mints the same kind of token; run the listing under a user session. The same goes for `--personal-workspace` on any command: an external app has no Personal Workspace. |
 | Command targets the wrong tenant | `uip login tenant set <tenant>`; verify with `uip login status` |
 | Pack succeeds but publish 409s | Version conflict — bump the version (`uip solution pack . ./out -v <new-version>`) or delete the colliding version with `uip solution packages delete <package-name> <version> --yes` (only if intentional; `--yes` required) |
-| `deploy run` stops because the package is already deployed | Upgrade it in place with `uip solution deploy upgrade <deployment-key>` (running `deploy run` again does not upgrade it), or `uip solution deploy uninstall <name> --yes` first, or pass `--yes` to create a second, separate deployment |
+| `deploy run` stops because the package is already deployed | Upgrade it in place with `uip solution deploy upgrade <deployment-key>` (running `deploy run` again does not upgrade it), or `uip solution deploy uninstall <name> --yes` then `uip solution deploy delete <name> --yes` first, or pass `--yes` with a different `--name` to create a second, separate deployment (re-using the name updates the existing one in place) |
+| `HTTP 400 … cannot be uninstalled` (error `4007`) | The deployment is not uninstallable in its state — superseded, already uninstalled, or left by a failed install. Read `Instructions`: when its `Actions` list offers `Delete`, remove the record with `uip solution deploy delete <name> --yes`. An operation still running is the other cause, and that one clears by itself (`Retry: RetryLater`) |
+| `deploy upgrade` reported `Status: DeploymentSucceeded` but the old version still runs | Read `DeploymentStatus` and `ActivationStatus` in the same output. `SuccessfulInstall` / `NeedsSetupToActivate` means the new version is installed and waits for "Setup activation" in Orchestrator; `PendingResources` names what needs configuring and why (`Reason`, from the activation validation, e.g. `[CNS1072] You will need to authenticate this connection before proceeding further`) and `NextSteps` the step. `ReadyToActivate` means `uip solution deploy activate <name>` is all that is left. Do not run the upgrade again — the content is already there |
+| `Another upgrade has already started for this deployment` (error `4005`) | The key you passed is superseded by a later record; nothing is running. The CLI names the current record — use that key (`uip solution deploy list` shows it). If the current record is already at the version you want, there is nothing to upgrade |
+| `deploy run` succeeded with `ActivationStatus: NeedsSetupToActivate` and the deployment does not run | Expected: the install landed, and a resource needs "Setup activation" in Orchestrator before activation. `PendingResources` names what needs configuring and why (`Reason`, from the activation validation, e.g. `[CNS1072] You will need to authenticate this connection before proceeding further`) and `NextSteps` the step. `Status` may read `ValidationFailed` there: that is the pipeline's word for the activation validation it ran after the install, and `NextSteps` open with its errors. Do not deploy again (the deployment exists); complete the setup, then `uip solution deploy activate <name>` |
+| `deploy activate` refused with `cannot be activated` (error `4007`) on an installed deployment | The deployment needs "Setup activation" first (`ActivationStatus: NeedsSetupToActivate`); `Instructions` list the resources that need configuration. Complete the setup in Orchestrator, then activate. `deploy status <key>` shows the same state |
 | `deploy run` fails on a resource conflict | `uip solution deploy config link config.json <resource> --name <existing> --folder-path <path>` to map to the existing one, or change `conflictFixingAction` via `config set` |
+| The deployment is stuck in `Draft` and `deploy activate` won't take it | Read `Operation` first. `ActivationSetup` + `Draft` is a "Setup activation" someone started in Orchestrator and did not finish — complete it there (the UI lists it as `Activation setup · Draft`); `deploy status <key>` names the resources it waits for. To discard it instead, `uip solution deploy delete <name> --yes` removes the draft alone and the deployment returns to its previous record (still needing setup). `VersionChange` + `Draft` is an upgrade queued and never installed. An `Install` `Draft` is a deploy whose install never completed — validation rejected something. It never advances on its own (a deployment passes through `Draft` for a moment right after you fire the command, but not once the command has returned). The reasons are in the failure's `Instructions` (`Validation:` / `Conflicts:`) on every feed, next to the draft's key; fix them with `uip solution deploy config set` / `deploy config link`, then run your original `uip solution deploy run …` again with `--config-file config.json` added and the **same** `--name` and `--package-version` — it still needs `--package-name` and `--folder-name`. A `Draft` left by an install does not block that rerun; one left by an update of a live deployment needs `--yes`, because the package is already deployed. While a draft exists any other version is refused, `deploy upgrade` included — to drop it instead, run `uip solution deploy upgrade <draft-key> --discard-draft`, or Delete draft in Orchestrator. To look at it, `uip solution deploy list` needs the same `--personal-workspace` / `--feed <name-or-key>` flag the deploy used — plain `deploy list` is tenant-scoped and shows no row for those deployments at all |
 | `Resource not found` after deploy | `uip solution resources refresh` to re-sync from each project's `bindings_v2.json`; if still missing, the resource was never declared in any project |
 | A cloud change (new entity field, changed queue setting) never reaches the solution | Expected: `refresh` is import-only and reports the resource under `Skipped`. Pull it with `uip solution resources edit <resource-key> --source remote --force` |
 | Output looks empty | You may have redirected stderr — confirmations and errors go there. Re-run without `2>` |

package/dist/tool.js

@@ -1,25 +1,34 @@
 import {
   metadata,
   registerCommands
-} from "./packager-tool-f423v35w.js";
-import"./packager-tool-1haahq17.js";
-import"./packager-tool-4kdt8mys.js";
-import"./packager-tool-vas0xg5h.js";
-import"./packager-tool-wtpe9285.js";
-import"./packager-tool-7znqtw3f.js";
-import"./packager-tool-znakt6yw.js";
-import"./packager-tool-k4mskzww.js";
-import"./packager-tool-jz2wbfjz.js";
-import"./packager-tool-grtmkd54.js";
-import"./packager-tool-2p5yh1q9.js";
-import"./packager-tool-7qmx64kz.js";
-import"./packager-tool-bkwnetqn.js";
+} from "./packager-tool-9hj0cfd0.js";
+import"./packager-tool-3enm2h28.js";
+import"./packager-tool-1phh2rfx.js";
+import"./packager-tool-j30xck4w.js";
+import"./packager-tool-ks8spnq8.js";
+import"./packager-tool-40vcj4wv.js";
+import"./packager-tool-482eg22x.js";
+import"./packager-tool-2cntqvdv.js";
+import"./packager-tool-qm24rbae.js";
+import"./packager-tool-9vvdgbay.js";
+import"./packager-tool-vh4ng74p.js";
+import"./packager-tool-5dzjsw5q.js";
+import"./packager-tool-zns6n8zp.js";
+import"./packager-tool-3m36mxn7.js";
+import"./packager-tool-qgaqqq41.js";
+import"./packager-tool-qdtjywsk.js";
+import"./packager-tool-00vh1ktg.js";
+import"./packager-tool-bqre28m1.js";
+import"./packager-tool-83rzavkx.js";
 import"./packager-tool-gdtpsdn7.js";
 import"./packager-tool-53w8skv5.js";
-import"./packager-tool-nzghfa48.js";
-import"./packager-tool-2syrt51a.js";
-import"./packager-tool-3jrq7smt.js";
-import"./packager-tool-0f0wt9vh.js";
+import"./packager-tool-fv7xyzg2.js";
+import"./packager-tool-f5gq77m5.js";
+import"./packager-tool-3fv6zc86.js";
+import"./packager-tool-vmsxq1pc.js";
+import"./packager-tool-5fjp60dk.js";
+import"./packager-tool-gb35b4qs.js";
+import"./packager-tool-zf3929se.js";
 import"./packager-tool-dfrk01gn.js";
 import"./packager-tool-1de529jm.js";
 export {
@@ -27,4 +36,4 @@ export {
   registerCommands
 };
 
-//# debugId=F50F7343D96D9C2C64756E2164756E21
+//# debugId=A619C849012DC6F164756E2164756E21

package/dist/utils/deployment-errors.d.ts

@@ -37,3 +37,60 @@ export declare function extractDeploymentErrors(result: PipelineDeploymentResult
  */
 export declare function formatDeploymentErrorsAsText(summary: DeploymentErrorSummary): string;
 export declare function formatDeploymentFailureDetails(pipelineDeploymentId: string, status: PipelineDeploymentResult): string;
+/**
+ * The errors a pipeline attached to its terminal status, one line per
+ * category (validation, conflicts, conflict fixing, schedule, deployment,
+ * services), each error with its code and the resource it names. Empty when
+ * the status carries none.
+ */
+export declare function formatPipelineErrors(status: PipelineDeploymentResult): string[];
+/**
+ * Does a server error body carry this Automation Solutions error code?
+ *
+ * The code sits either at the top level (`{"errorCode":"0002",…}`) or, on a
+ * ProblemDetails validation failure, inside each field's entries
+ * (`{"errors":{"deploymentName":[{"errorCode":"DeploymentAlreadyInProgress",…}]}}`).
+ * `extractErrorDetails` keeps only the messages of the latter in
+ * `parsedErrors`, so the raw `details` text is what still names the code.
+ */
+export declare function hasServerErrorCode(details: string, code: string): boolean;
+/**
+ * Did the server answer without a problem body? A missing body leaves the
+ * SDK's own error text in `details`; every server answer is JSON. With a 404
+ * this is how a route the server does not have (a bare 404 from the gateway)
+ * reads apart from the route's own not-found, which carries a body.
+ */
+export declare function isBareResponse(details: string): boolean;
+/**
+ * The install route's refusal when the name's newest generation is a Draft
+ * built for another version: a pending attempt stands in the way.
+ */
+export declare const DRAFT_VERSION_MISMATCH_CODE = "DraftDeploymentHasDifferentPackageVersion";
+/**
+ * Terminal statuses the pipeline reaches before it schedules the install. The
+ * attempt's generation is then never promoted: it stays behind as a Draft,
+ * which the install route reuses for the name on the next request.
+ */
+export declare function leavesPendingDraft(status: string): boolean;
+/**
+ * Whether the run's own record says the install landed although the pipeline
+ * did not end at `DeploymentSucceeded`.
+ *
+ * The pipeline runs an activation validation after the install. When it
+ * passes the run ends at `DeploymentSucceeded` with the record
+ * `ReadyToActivate`; when it fails the run ends at `ValidationFailed` with
+ * `deploymentResult.status: SuccessfulInstall` and the record `Successful` /
+ * `NeedsSetupToActivate`, `SetupActivation`, `Uninstall` and `Upgrade`
+ * offered — the install had landed. Measured 2026-09-28 on both `deploy run`
+ * (a fresh install and an in-place move) and `deploy upgrade`, with an
+ * Integration Service connection that needed authentication.
+ * `leavesPendingDraft` is wrong for such a run — nothing is a draft, and the
+ * deployment exists — so a caller reads this first.
+ */
+export declare function installLandedDespiteStatus(status: PipelineDeploymentResult): boolean;
+/**
+ * The first next step for a run {@link installLandedDespiteStatus} describes:
+ * the pipeline's status, why it is not the install's, and the errors it
+ * attached — on one line, since a next step is one.
+ */
+export declare function explainPipelineStatusAfterInstall(status: PipelineDeploymentResult): string;

package/package.json

@@ -2,7 +2,7 @@
     "name": "@uipath/solution-tool",
     "author": "UiPath",
     "license": "SEE LICENSE IN LICENSE.txt",
-    "version": "1.203.0-preview.212",
+    "version": "1.204.0-preview.211",
     "description": "Create, pack, publish, and deploy UiPath Automation Solutions.",
     "repository": {
         "type": "git",
@@ -48,5 +48,5 @@
         "dist"
     ],
     "private": false,
-    "gitHead": "15094ce85cf76c59a54affbed3304febc271f41a"
+    "gitHead": "275e01f1f6098d4c3bc9673f5225f33372822534"
 }