@uipath/skills 1.195.0

package/skills/uipath-solution/references/operate/pack-and-deploy.md

@@ -0,0 +1,328 @@
+# Pack & Deploy
+
+Pack a solution into a deployable package, publish to the feed, and deploy to Orchestrator with optional configuration.
+
+> For full option details on any command, use `--help` (e.g., `uip solution deploy run --help`).
+
+## When to Use
+
+- Deploying automations to staging or production environments
+- CI/CD pipelines that pack, publish, and deploy on every merge
+- Multi-environment promotion (dev -> staging -> production)
+
+## Prerequisites
+
+- Authenticated (`uip login`)
+- Solution developed and ready to pack (see [develop-solution.md](develop-solution.md))
+- Solution state verified — `.uipx` and `resources/solution_folder/` agree on the project set (see [develop-solution.md - Always verify state after every mutation](develop-solution.md#always-verify-state-after-every-mutation))
+
+## Flow
+
+```mermaid
+graph LR
+    A[solution pack] --> B[solution publish]
+    B --> C[deploy config get]
+    C --> D[config set / link]
+    D --> E["deploy run<br/>(auto-activate by default)"]
+    B --> E
+    E --> F[deploy status]
+    E --> G[deploy list]
+    E -->|--skip-activate| H[deploy activate]
+```
+
+---
+
+## Step 1: Pack the Solution
+
+Build a deployable .zip from a solution directory:
+
+```bash
+uip solution pack ./MySolution ./output --output json
+
+# With explicit name and version
+uip solution pack ./MySolution ./output --name "MySolution" --version "2.0.0" --output json
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `<solutionPath>` | Directory containing a `.uipx` or `.uis` file (required) | -- |
+| `<output-path>` | Directory where the .zip will be written (required positional, no default — omitting it errors with `missing required argument 'output-path'`) | -- |
+| `--name <name>` | Override the package name | Name from `.uipx` |
+| `--version <version>` | Set the package version | `1.0.0` |
+
+The output is a `.zip` file named `<name>.<version>.zip` written under `<output-path>/` (e.g., `MySolution.2.0.0.zip`). Run `solution resource refresh` first (from inside the solution dir, or with `--solution-folder <path>`) to ensure the solution's artefact files and debug overwrites are up to date — they're bundled into the package.
+
+## Step 2: Publish to the Solution Feed
+
+Upload the packed .zip so it appears in the UiPath solution feed:
+
+```bash
+uip solution publish ./output/MySolution.2.0.0.zip --output json
+
+# Target a specific tenant
+uip solution publish ./output/MySolution.2.0.0.zip --tenant "Production" --output json
+```
+
+After publishing, the package is visible via `uip solution packages list` and available for deployment.
+
+## Step 3 (Alternative): Upload to Studio Web
+
+If the goal is browser-based editing rather than deployment, use `upload` instead of `publish`:
+
+```bash
+uip solution upload ./MySolution --output json
+```
+
+This uploads to Studio Web for collaborative editing. It does **not** place the package on the solution feed and cannot be used with `deploy run`.
+
+`upload` always lands the solution in Studio Web's **Cloud workspace** tab, not the Local tab. SW's Local tab is a separate registration for solutions whose source of truth is a tracked local folder — populated by SW-initiated flows (creating a solution from the SW UI, or downloading a cloud solution to local) or by Studio Desktop signing into the same tenant. `uip solution upload` does not address the Local tab. Authoring with `uip solution new` then `upload` produces a Cloud-tab solution; the local folder on disk has no live link to either tab afterward — edits in one place do not propagate to the other without a re-upload (Cloud) or a download (Local).
+
+## Step 4: Deploy to Orchestrator
+
+Deploy the published package. By default this creates a new Orchestrator folder, provisions all solution resources, **and activates the deployment** in one call:
+
+```bash
+uip solution deploy run -n "InvoiceAutomation-v2" \
+  --package-name "MySolution" --package-version "2.0.0" \
+  --folder-name "MySolutionFolder" --output json
+```
+
+A successful run returns `Status: DeploymentSucceeded` and `ActivationStatus: SuccessfulActivate`. If the package requires configuration before it can activate, deploy still succeeds but activation surfaces an explicit error pointing at `deploy activate <name>` — fix the config and retry the activate.
+
+To skip auto-activation (legacy behaviour — leaves the deployment in `Inactive (Ready to activate)`):
+
+```bash
+uip solution deploy run … --skip-activate --output json
+```
+
+Key options:
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-n, --name <name>` | Deployment name (required) | -- |
+| `--package-name <name>` | Published solution package name (required) | -- |
+| `--package-version <version>` | Package version to deploy (required) | -- |
+| `--folder-name <name>` | New Orchestrator folder to create (required) | -- |
+| `--parent-folder-path <path>` | Parent folder under which the new folder is created | -- |
+| `--parent-folder-key <key>` | Parent folder key (GUID, alternative to `--parent-folder-path`) | -- |
+| `--config-file <path>` | Configuration file from `deploy config get` | -- |
+| `--skip-activate` | Skip the post-deploy activation; leaves the deployment in `Inactive (Ready to activate)` | (off — auto-activate) |
+| `--timeout <seconds>` | Polling timeout, applied per phase (deploy and, when not skipped, activate) | 360 |
+| `--poll-interval <ms>` | Polling interval used during both phases | 5000 |
+| `--login-validity <minutes>` | Minimum minutes left on the access token before the CLI proactively refreshes it before the deploy starts. Useful for long deploys close to token expiry. | 10 |
+| `-t, --tenant <name>` | Tenant override | Current tenant |
+
+## Step 5: Check Deployment Status
+
+The `deploy run` command returns a pipeline deployment ID. Use it to check progress:
+
+```bash
+uip solution deploy status <pipeline-deployment-id> --output json
+```
+
+The CLI also falls back to the persistent `searchSearchDeployments22` record if the pipeline service has already recycled the in-flight tracking ID — so a deployment that finishes while the CLI is between polls is still surfaced as `DeploymentSucceeded` rather than a polling failure.
+
+## Step 6: List Deployments
+
+```bash
+uip solution deploy list --output json
+uip solution deploy list --folder-path "Shared" --limit 20 --sort-by "Name" --sort-order "Ascending" --output json
+```
+
+Options: `--folder-path`, `--limit` (default 50), `--sort-by`, `--sort-order` (`Ascending`/`Descending`).
+
+---
+
+## Configuration Workflow
+
+The deploy config is a plain JSON file that lists every resource the package exposes, along with its default properties and an optional `linkToResource` directive. It controls two things at deploy time:
+
+- **Per-resource properties** — queue retry count, retention periods, conflict-resolution behaviour, etc.
+- **Link vs. install** — whether each resource is bound to an existing Orchestrator/Apps entity (`linkToResource` set) or provisioned fresh in the deployment folder (no `linkToResource`).
+
+The CLI exposes `get` / `set` / `link` / `unlink` for the common edits, but the file is just JSON — you can also open it in an editor and modify any field directly. Pass the file to `deploy run --config-file <path>` to apply.
+
+### File Structure
+
+`deploy config get` writes a top-level `resources` array. Each entry looks like:
+
+```jsonc
+{
+  "kind": "bucket",                                   // resource kind
+  "name": "test",                                     // resource name in the solution
+  "resourceKey": "19f344d2-...",                      // solution-resource key (cloud GUID for resources imported from RCS)
+  "folderPaths": ["solution_folder"],                 // folders the resource lives in inside the solution
+  "configuration": { /* kind-specific properties */ },
+  "linkToResource": {                                 // optional — present only when linked
+    "name": "ProductionBucket",
+    "folderPath": "Shared/Production"
+  }
+}
+```
+
+Only `linkToResource` toggles link vs. install. Everything else under `configuration` is forwarded to the resource at deploy time and can be edited freely — change retention periods, conflict-fixing actions, queue/process settings, or the kind-specific nested fields (e.g. an index's `storageBucketReference`, a process's `retentionBucketRef`) by writing to the JSON directly. Some `configuration` fields cross-reference other resources by `resourceKey`; when you edit link state on one resource, align those cross-refs on its dependents by hand if the topology changes.
+
+### Fetch the Default Configuration
+
+```bash
+uip solution deploy config get "MySolution" -d config.json --output json
+
+# For a specific version (latest is used if omitted)
+uip solution deploy config get "MySolution" -d config.json --package-version "2.0.0" --output json
+```
+
+The fetched file already contains every resource with default values — no manual scaffolding required.
+
+### Set a Resource Property
+
+```bash
+uip solution deploy config set config.json MyQueue maxNumberOfRetries 5
+```
+
+Arguments: `<config-file> <resource-name> <property> <value>`. Property names match the keys under `configuration` (visible in the file).
+
+### Set a Property for All Resources
+
+```bash
+uip solution deploy config set config.json --all conflictFixingAction UseExisting
+```
+
+`--all` is restricted to `conflictFixingAction` — the field that controls what happens when a resource with the same name already exists in the target folder.
+
+### Link to an Existing Orchestrator Resource
+
+Add `linkToResource` so the deployment binds to an existing entity instead of creating a new one:
+
+```bash
+uip solution deploy config link config.json MyQueue \
+  --name ProductionQueue --folder-path "Shared/Production"
+```
+
+Effect on the file: appends `linkToResource: { name, folderPath }` to the matched resource entry. The `--name` / `--folder-path` arguments must point to a real Orchestrator/Apps resource — the deployment fails if it doesn't exist.
+
+When the same resource name appears multiple times in the config (different kinds), pass `resourceKey` instead of `name` to disambiguate. The CLI surfaces the available keys in the error message.
+
+### Unlink a Resource
+
+Remove the link so the resource is provisioned fresh in the deployment folder:
+
+```bash
+uip solution deploy config unlink config.json MyQueue
+```
+
+Effect on the file: deletes the `linkToResource` field. The unlink command requires a `linkToResource` to already exist — to start from a default-install config, simply leave (or never add) the field.
+
+### Editing the Config File Directly
+
+Every change the CLI makes is a small edit to the JSON, and the file isn't restricted to the fields `set` / `link` / `unlink` know about. Any property under `configuration`, any cross-reference (e.g. `storageBucketReference.key`), or any new top-level resource entry can be edited or added by hand when the built-in commands don't cover the case. Validate by running `deploy run --config-file <path>` — the deploy fails fast if a referenced resource doesn't exist.
+
+### Deploy with Configuration
+
+Pass the customized config file to `deploy run`:
+
+```bash
+uip solution deploy run -n "InvoiceAutomation-Prod" \
+  --package-name "MySolution" --package-version "2.0.0" \
+  --folder-name "ProdFolder" --parent-folder-path "Production" \
+  --config-file config.json --output json
+```
+
+Without `--config-file`, the deployment uses package defaults. With `--config-file`, every resource is provisioned exactly as the file describes — fresh-install for any entry without `linkToResource`, bound for any entry with one.
+
+---
+
+## CI/CD Example (GitHub Actions)
+
+```yaml
+name: Deploy UiPath Solution
+on:
+  push:
+    branches: [main]
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm install -g @uipath/cli
+      - run: uip login --client-id "${{ secrets.UIPATH_CLIENT_ID }}" --client-secret "${{ secrets.UIPATH_CLIENT_SECRET }}" --tenant "${{ secrets.UIPATH_TENANT }}" --output json
+      - run: uip solution pack ./MySolution ./output --version "1.0.${{ github.run_number }}" --output json
+      - run: uip solution publish ./output/MySolution.*.zip --output json
+      - run: uip solution deploy run -n "MySolution-${{ github.run_number }}" --package-name "MySolution" --package-version "1.0.${{ github.run_number }}" --folder-name "MySolution" --config-file deploy-config.json --output json
+```
+
+---
+
+## Environment Promotion
+
+Pack once, then publish and deploy to each environment in sequence:
+
+```bash
+uip solution pack ./MySolution ./output --version "1.2.0" --output json
+
+# Staging
+uip login tenant set "Staging" --output json
+uip solution publish ./output/MySolution.1.2.0.zip --output json
+uip solution deploy run -n "MySolution-Staging" --package-name "MySolution" --package-version "1.2.0" \
+  --folder-name "MySolution" --config-file staging-config.json --output json
+
+# Production (after validation)
+uip login tenant set "Production" --output json
+uip solution publish ./output/MySolution.1.2.0.zip --output json
+uip solution deploy run -n "MySolution-Prod" --package-name "MySolution" --package-version "1.2.0" \
+  --folder-name "MySolution" --config-file production-config.json --output json
+```
+
+---
+
+## Version Bumping
+
+Always increment the version when republishing (patch for fixes, minor for features, major for breaking changes). The solution feed rejects duplicate name+version pairs.
+
+---
+
+## Variations and Gotchas
+
+### `publish` vs `upload`
+
+These are different commands with different destinations:
+
+| Command | Destination | Purpose |
+|---------|-------------|---------|
+| `solution publish` | Solution feed | For deployment via `deploy run` |
+| `solution upload` | Studio Web | For browser-based editing |
+
+### `deploy run` Creates a New Folder
+
+`--folder-name` specifies a folder to **create**, not an existing folder to deploy into. If the folder already exists, deployment will fail. Use `--parent-folder-path` to set the parent folder where the new folder is created.
+
+### `--parent-folder-path` is the Parent
+
+On `deploy run`, `--parent-folder-path` is the **parent** folder, not the deployment folder itself. The deployment folder is `--folder-name`, created inside `--parent-folder-path`. To produce a nested layout like `Shared/Nica/Solution`, pre-create `Shared/Nica` (or use a previous deploy to make it) and pass `--parent-folder-path "Shared/Nica" --folder-name "Solution"`.
+
+### Config `link` Connects to Existing Resources
+
+`config link` does not copy or move a resource. It writes a `linkToResource` directive that points the deployment at an existing Orchestrator/Apps resource instead of creating a new one. The linked resource must already exist in the specified folder when `deploy run` executes.
+
+### Cross-Resource References Don't Auto-Update
+
+Some resources reference others through `configuration` fields (an index's `storageBucketReference.key` pointing at a bucket, a process's `retentionBucketRef`, etc.). `link` / `unlink` only touch the targeted resource — they do not rewrite cross-references on its dependents. When you change link state for a resource that other entries point at, open the config file and align the cross-reference fields by hand.
+
+### Config `set --all` is Limited
+
+The `--all` flag on `config set` only works with `conflictFixingAction`. It cannot be used to set arbitrary properties across all resources.
+
+### `deploy list --limit` and Folder Filtering
+
+Folder filtering with `--folder-path` happens **after** fetching `--limit` results. If your deployment is missing from the list, increase `--limit` to ensure the server returns enough results before filtering.
+
+### Units Mismatch
+
+`--poll-interval` is in **milliseconds** (default 5000ms = 5s). `--timeout` is in **seconds** (default 360s = 6min). Do not confuse the two.
+
+---
+
+## Related
+
+- [develop-solution.md](develop-solution.md) -- Create and structure a solution from scratch
+- [scenarios.md](scenarios.md) -- Recipes for same-name resources, cross-refs, shared cloud entities, virtual assets at deploy
+- [activate-and-manage.md](activate-and-manage.md) -- Activate deployments, uninstall, manage packages

package/skills/uipath-solution/references/operate/scenarios/failure-modes.md

@@ -0,0 +1,14 @@
+# Cross-cutting failure modes
+
+Symptoms that don't fit a single scenario but bite often enough to call out. Use this as triage when you don't yet know which scenario applies.
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `[1009] <kind> <name>: Invalid argument 'Value'` at deploy | Virtual resource without `value` set ([virtual-resource](virtual-resource.md)) | `deploy config set <file> <name> value <val>` or `deploy config link <file> <name> --name <existing>` |
+| `Folder already exists` at deploy | `--folder-name` collides with an existing folder under `--parent-folder-path` | Pick a different `--folder-name`, or `solution deploy uninstall <existing>` first |
+| Suffix `_N` keeps growing on re-refresh (`_1`, `_2`, `_3`...) | Old CLI version (pre-suffix-amplification fix) | Upgrade `@uipath/cli` to a build that ships the SDK bump (`resource-builder-sdk` ≥ `2025.11.0-alpha3780`); the current refresh is idempotent on cloud key |
+| Tool dialog in Studio Web doesn't open for one of two same-name tools | SW UI bug — affects pure-SW solutions too ([same-name-across-folders](same-name-across-folders.md)) | Verified at deploy/runtime — ignore the UI symptom; check the tool resolves correctly via `resource list --source remote` after deploy |
+| Refresh imports 0 of N bindings, no warnings | `bindings_v2.json` not at expected path (project root, not nested) | Move file to `<ProjectName>/bindings_v2.json`; `agent validate` regenerates it for agent projects |
+| `processKey` collision on `solution publish` | Republishing same name+version | Bump version (`solution pack --version 1.0.1 …`); the feed rejects duplicate `name+version` pairs |
+
+> See the individual scenario files for setup, root-cause walkthroughs, and verification steps.

package/skills/uipath-solution/references/operate/scenarios/intra-solution-references.md

@@ -0,0 +1,61 @@
+# Cross-reference inside the same solution
+
+A coordinator agent (or flow, or process) needs to invoke another agent in the **same solution**. Both projects ship together, neither exists in cloud yet at refresh time.
+
+## Setup
+
+Solution has `Coordinator/` (agent) and `Worker/` (agent). Coordinator's `agent.json` declares a tool whose `referenceKey` should resolve to Worker — but Worker isn't on cloud, so its cloud key doesn't exist.
+
+```
+MySolution/
+├── MySolution.uipx
+├── Coordinator/
+│   ├── agent.json
+│   ├── resources/WorkerTool/resource.json
+│   └── bindings_v2.json
+├── Worker/
+│   └── agent.json
+└── resources/solution_folder/
+    ├── process/agent/Coordinator.json    (auto on add)
+    └── process/agent/Worker.json         (auto on add)
+```
+
+The right `referenceKey` for the Worker tool is the **solution-resource key** of `Worker.json` (read from `uip solution resource list --kind Process --source local --output json`), **not** the `projectId` from `.uipx`.
+
+```jsonc
+// Coordinator/resources/WorkerTool/resource.json
+{
+  "$resourceType": "tool",
+  "name": "WorkerTool",
+  "type": "agent",
+  "location": "solution",                              // ← intra-solution, not "external"
+  "referenceKey": "<solution-resource-key-of-Worker>", // from `resource list --kind Process --source local`
+  "properties": {
+    "processName": "Worker",
+    "folderPath": "solution_folder"
+  }
+}
+```
+
+## What happens at refresh + pack
+
+- `solution project add` writes `Worker.json` and `Coordinator.json` under `resources/solution_folder/process/agent/` with stable solution-resource keys (UUIDs minted by the SDK at add time).
+- `resource refresh` doesn't re-mint those keys — they're stable for the life of the solution.
+- At pack, the Coordinator's `runtimeDependencies` entry for the Worker tool carries the same solution-resource key as `referenceKey`. Orchestrator's deploy pipeline resolves intra-solution links by matching this key to a sibling resource in the deployment.
+
+## Gotchas
+
+- **Don't put the cloud key of a different (already-published) Worker** if you intend to ship Worker as part of this solution. `referenceKey` to a cloud key skips the intra-solution link and points the runtime at the cloud copy — which may or may not exist in the target tenant at deploy time.
+- **The solution-resource key is stable across refreshes within an instance** but **regenerates if you delete and re-create the solution** (`solution init` → mint fresh UUIDs). Hard-coding the key in `resource.json` survives normal refresh cycles but breaks if anyone wipes-and-recreates. If that's a risk, rebuild the file from `resource list --kind Process --source local` output as part of CI.
+- **`location` must be `"solution"`, not `"external"`** for intra-solution tools. SW UI shows external-tool dialogs differently and won't render the link state correctly.
+- **Worker → Coordinator cycles**: nothing prevents you from declaring a tool in Worker that points back at Coordinator. The runtime supports it; if the agent prompts loop, that's an authoring issue, not a deploy one.
+
+## Verify
+
+```bash
+uip solution resource list --kind Process --source local --output json
+```
+
+The keys you see here are what `referenceKey` should be in any `location: "solution"` tool resource file.
+
+> See: [develop-solution.md — Step 6: List Resources](../develop-solution.md#step-6-list-resources).

package/skills/uipath-solution/references/operate/scenarios/manual-edits.md

@@ -0,0 +1,132 @@
+# Manual edits when the CLI doesn't cover the case
+
+The CLI now covers the full resource CRUD: **create** ([Step 9: `solution resource add`](../develop-solution.md#step-9-add-a-resource-atomically)), **delete** ([Step 10: `solution resource remove`](../develop-solution.md#step-10-remove-a-resource)), and **update** ([Step 11: `solution resource edit`](../develop-solution.md#step-11-edit-a-resource)). `edit` patches an existing resource's `spec` through the SDK — it even renames (with duplicate protection), so the old "rename is Studio-Web-only" rule no longer holds.
+
+**Reach for `solution resource edit` first** for any spec-field change. The SDK validates against kind metadata: it silently skips unknown / reference / read-only properties, and identity fields (`key`, `kind`, `type`, `apiVersion`, `dependencies`, `folders`) live outside `spec` so `edit` can't touch them at all.
+
+This page is now the **last resort** — for the narrow cases `edit` *won't* cover:
+
+1. **Edit in Studio Web** — `solution upload`, edit in the SW UI, re-export. Use when you need to change a reference/relationship field the SDK won't let `edit` write.
+2. **`solution deploy config set` / `link` / `unlink`** — for changes that only need to apply at deploy time (per-environment values, link state). Touches only the deploy config file, not the solution-level resources.
+3. **Hand-edit the JSON directly** — the escape hatch when none of the above fit. Works, but **not ideal** — no validation, the SDK can silently undo your change on the next refresh if it conflicts with what bindings re-derive, and structural mistakes corrupt the solution. Use only when you understand which fields the SDK leaves alone.
+
+This page covers (3) — what's safe to hand-edit and what's not. For everyday spec changes prefer `solution resource edit`; for creating or deleting a whole resource, `solution resource add` / `remove`.
+
+## What the SDK actually compares
+
+`addOrUpdateResourceToSolutionAsync` calls `compareResourceSpecs` to decide if a resource is `Unchanged` / `Updated`. That comparison **looks at `resource.spec` only** (with reference and secret properties excluded). Top-level fields on `resource` (`name`, `key`, `kind`, `description`, `folders`, etc.) are not part of the spec compare — but most of them carry identity or relationship semantics that other parts of the system rely on.
+
+## Solution-level resource files (`resources/solution_folder/<kind>/<name>.json`)
+
+Open the file. The shape is roughly:
+
+```jsonc
+{
+  "docVersion": "1.0.0",
+  "resource": {
+    "key": "11de87d3-...",                // identity — never edit
+    "name": "MyResource",                 // identity — never edit
+    "kind": "asset",                      // identity — never edit
+    "type": "stringAsset",                // identity — never edit
+    "apiVersion": "orchestrator.uipath.com/v1",  // managed — never edit
+    "description": "...",                 // free text — safe to edit
+    "isOverridable": true,                // SW link UI toggle — safe but stays `true` in practice
+    "dependencies": [...],                // SDK-managed cross-refs — never edit
+    "runtimeDependencies": [...],         // computed at pack — never edit
+    "files": [...],                       // SDK-managed — never edit
+    "folders": [{ "fullyQualifiedName": "solution_folder" }],  // edit moves the resource — risky (see below)
+    "spec": {
+      "name": "MyResource",               // duplicate of top-level — must stay in sync if you ever edit name
+      "type": "Text",                     // identity — never edit
+      "value": "",                        // safe to edit (asset value, queue config, bucket retention, etc.)
+      "scope": "global",                  // safe but rarely needs editing
+      ...                                 // see kind-specific guidance below
+    },
+    "locks": []                           // SDK-managed — never edit
+  }
+}
+```
+
+| Editable | Why | Caveats |
+|---|---|---|
+| `resource.description` | Free-text, not referenced by anything | None |
+| `resource.spec.<runtime-config>` | The reason most edits exist (asset `value`, queue retry/auto-retry, bucket `tags`/`retentionPeriod`/`retentionAction`, process `tags`/`retentionPeriod`/`hiddenForAttendedUser`/`alwaysRunning`/`autoStartProcess`) | These DO trigger `Updated` on next refresh. That's fine — the next refresh just re-saves with your edited spec. Don't edit reference fields (anything ending in `Reference`, `Ref`, `Key`) by hand. |
+| `resource.spec.tags` | List of strings, no relationships | None |
+| `resource.isOverridable` | Toggle for whether SW lets bindings link this | Setting to `false` blocks SW link UI — usually leave `true` |
+
+| **Don't edit** | Why |
+|---|---|
+| `resource.key` | Cross-references everywhere; rename breaks bindings and dependent resources |
+| `resource.name` | Bindings find resources by name; rename without updating bindings → bindings unresolved at deploy. SW or `solution upload` round-trip is the only safe way to rename |
+| `resource.kind` / `resource.type` / `apiVersion` | Identity — switching kind is "delete + create new", do that explicitly |
+| `resource.spec.name` / `resource.spec.type` | Must match top-level; SDK's `compareResourceSpecs` flags any drift |
+| `resource.dependencies` | SDK rebuilds these at refresh from `bindings_v2.json`; manual edits get overwritten |
+| `resource.runtimeDependencies` | Recomputed at every pack — manual edits lost on next pack |
+| `resource.files`, `resource.locks` | Managed; never appear in user-edit scenarios |
+| `resource.folders` | Moves the resource. For a *cloud-imported* resource the folder is `solution_folder` (placeholder) — editing it doesn't change cloud location, only confuses sync. For a *virtual* resource that you authored at a non-`solution_folder` folder, edit at the binding (`bindings_v2.json`) and let refresh re-create — don't edit the resource file directly |
+| `resource.spec.<reference-fields>` | E.g. `storageBucketReference`, `retentionBucketRef`. The SDK rewrites these when the target's link state changes; hand-edits get clobbered. (Also see [SOL-7051](https://uipath.atlassian.net/browse/SOL-7051) — the rewrite isn't always applied automatically; that's a known bug, not a license to hand-edit dependents arbitrarily) |
+
+### Examples — safe edits
+
+```jsonc
+// asset/stringAsset/MyAsset.json — set a default value
+"spec": { "name": "MyAsset", "type": "Text", "scope": "global",
+          "value": "https://api.production.example.com" }   // ← edit this
+
+// queue/Queue/OrdersQueue.json — change retry count
+"spec": { ..., "maxNumberOfRetries": 5, ... }                // ← edit this
+
+// process/api/MyApi.json — change retention
+"spec": { ..., "retentionPeriod": 14, ... }                  // ← edit this
+
+// bucket/Bucket/Storage.json — adjust tags
+"spec": { ..., "tags": [{ "name": "Env", "value": "prod" }], ... }
+```
+
+After any solution-level edit, run a sanity check:
+
+```bash
+uip solution resource list --kind <kind> --solution-folder . --source local --output json
+```
+
+The list should show your resource with the new spec. If `resource refresh` reverts the change on the next run, you edited a field the bindings re-derive — back out and use the deploy-config path or SW UI instead.
+
+## Deploy config files (`deploy-config.json`)
+
+Same principle, looser rules. The deploy config is **per-deployment**, not per-solution — editing it doesn't mutate the solution itself, only what `solution deploy run` provisions. Three editing paths:
+
+1. **`uip solution deploy config set <file> <resource> <prop> <value>`** — preferred. Validated, scoped, idempotent.
+2. **`uip solution deploy config link/unlink <file> <resource> ...`** — for binding to existing cloud resources or removing the binding.
+3. **Manual JSON edits** — fall back to this when the CLI doesn't cover what you need (e.g. nested cross-reference fields like `configuration.storageBucketReference.key`, or adding a fresh `linkToResource` block from scratch). Same shape as the SDK writes:
+
+```jsonc
+{
+  "resources": [
+    {
+      "kind": "asset",
+      "name": "MyAsset",
+      "resourceKey": "11de87d3-...",
+      "folderPaths": ["solution_folder"],
+      "configuration": {
+        "value": "manually-edited-value",   // ← safe to edit by hand
+        "description": "...",                // ← safe
+        "tags": [...]                        // ← safe
+      },
+      "linkToResource": {                    // ← safe to add/remove/edit by hand
+        "name": "ProductionAsset",
+        "folderPath": "Shared/Production"
+      }
+    }
+  ]
+}
+```
+
+**Manual editing of the deploy config is not ideal** — there's no schema validation in the CLI, and a bad edit fails server-side at `deploy run` (often with a generic `ValidationFailed`). But it's the pragmatic escape hatch when:
+
+- You need to set a nested property `config set` doesn't expose (e.g. `configuration.storageBucketReference.key` to work around [SOL-7051](https://uipath.atlassian.net/browse/SOL-7051)).
+- You're scripting a config transform (CI step injecting per-environment secrets, etc.) and want a single JSON-patch step instead of N CLI calls.
+- The CLI surface is missing a flag for the field you need.
+
+In those cases: edit the file, run `uip solution deploy run --config-file <path>`, and let the deploy validation catch any structural mistakes. Deploy errors come back fast and verbose enough to localize the bad field.
+
+> See: [pack-and-deploy.md — Configuration Workflow](../pack-and-deploy.md#configuration-workflow) for the standard `set`/`link`/`unlink` flow.

package/skills/uipath-solution/references/operate/scenarios/same-name-across-folders.md

@@ -0,0 +1,57 @@
+# Same-name resource across cloud folders
+
+You have two tools (or two bindings, or two project references) that target a resource with **the same name in different cloud folders**. Most common case: an agent with two API Workflow tools, both called "API Workflow", living in `Shared/Solution 50` and `Shared/DependenciesSolution`. RCS is happy with this — names are unique per folder, not globally — but the solution flattens both into a single `resources/solution_folder/process/api/` directory.
+
+## Setup
+
+Two bindings in the agent's `bindings_v2.json`, same `value.name.defaultValue`, different `value.folderPath.defaultValue`:
+
+```json
+{
+  "version": "2.0",
+  "resources": [
+    { "resource": "process", "key": "API Workflow",
+      "value": { "name": { "defaultValue": "API Workflow" },
+                 "folderPath": { "defaultValue": "Shared/Solution 50" } },
+      "metadata": { "subType": "api", "bindingsVersion": "2.2", "solutionsSupport": "true" } },
+    { "resource": "process", "key": "API Workflow",
+      "value": { "name": { "defaultValue": "API Workflow" },
+                 "folderPath": { "defaultValue": "Shared/DependenciesSolution" } },
+      "metadata": { "subType": "api", "bindingsVersion": "2.2", "solutionsSupport": "true" } }
+  ]
+}
+```
+
+Each tool's `resource.json` carries the cloud key in `referenceKey` and the cloud FQN in `properties.folderPath`.
+
+## What happens at `solution resource refresh`
+
+```
+Synced 2 resources (0 already in solution)
+```
+
+The SDK applies `addResourceWithUniqueName`: the first import lands as `API_Workflow.json` with the first cloud key; the second hits a name conflict and is **suffixed** to `API_Workflow_1.json` with the second cloud key.
+
+```
+resources/solution_folder/process/api/
+├── API_Workflow.json     (key=6337a36e..., name="API Workflow")
+└── API_Workflow_1.json   (key=5aaddd83..., name="API Workflow_1")  ← suffix added by SDK
+```
+
+The `_1` suffix is **expected and stable** — re-running refresh does not bump it further. Tool resource files are not touched; their `referenceKey` still points at the right cloud GUID.
+
+## Gotchas
+
+- **Tool dialogs in Studio Web may show only one tool** opening correctly. This is an SW UI bug present even on solutions authored entirely in Studio Web — confirmed by inspecting raw `Solution.uis` exports. The packed and deployed runtime is unaffected: the agent's `runtimeDependencies` carry distinct `resourceKey` + cloud `folderKey` per tool, so Orchestrator dispatches to the correct cloud workflow.
+- **Tool-agent dedup collapses bindings in the agent's nupkg** to one entry per `processName`. The packed `content/bindings_v2.json` shows a single `key: "API Workflow"` even though the agent has two tools. This is shared with Studio Web's server-side pack output. Don't try to fix it at the bindings layer — the deploy-time resolution path uses `tool.referenceKey → solution resource → debug_overwrites → cloud folder`, not the collapsed binding.
+- **Don't rename `processName` on the second tool by hand to dodge the collapse.** It changes the agent's call signature without rewriting the agent code/prompt that references the tool, and the next `agent validate` will revert it.
+
+## Verify
+
+```bash
+uip solution resource list --kind Process --solution-folder ./MySolution --source local --output json
+```
+
+You should see two `process`/`api` entries with **different keys** but matching the cloud GUIDs you wanted (compare against `uip maestro flow registry search "API Workflow"`).
+
+> See: [develop-solution.md — Step 7: Refresh Resources](../develop-solution.md#step-7-refresh-resources).

package/skills/uipath-solution/references/operate/scenarios/shared-cloud-resource.md

@@ -0,0 +1,41 @@
+# Shared cloud resource across projects
+
+Two (or more) projects in the solution declare a binding to the **same cloud resource** — typically a shared queue, asset, or storage bucket that multiple agents/processes read from.
+
+## Setup
+
+`ProjectA/bindings_v2.json` and `ProjectB/bindings_v2.json` both contain:
+
+```json
+{ "resource": "queue", "key": "OrdersQueue",
+  "value": { "name": { "defaultValue": "OrdersQueue" },
+             "folderPath": { "defaultValue": "Shared/Production" } },
+  "metadata": { "subType": "queue", "bindingsVersion": "2.2", "solutionsSupport": "true" } }
+```
+
+Same name, same folder, same cloud GUID.
+
+## What happens at refresh
+
+```
+Synced 1 resources (0 already in solution)
+```
+
+(Or `Imported: 1, Skipped: 1` depending on iteration order.) The first project's binding triggers `addOrUpdateResourceToSolutionAsync`, which imports `OrdersQueue` into the solution with its cloud GUID as the solution-resource key. The second project's binding hits the same cloud GUID — already in `knownResourceKeys` from the first import — and **skips silently**. No suffix, no duplicate, no error.
+
+## Gotchas
+
+- **The skip is idempotent across refreshes** for cloud-imported resources. If you ever see two `OrdersQueue.json` entries (without distinct cloud keys), something else is wrong — most likely a binding's `folderPath` placeholder differs (`solution_folder` vs `Shared/Production`) and the second binding falls through the [virtual-creation path](virtual-resource.md) instead of the import path.
+- **Refresh does NOT update the resource's local config** if the cloud-side definition changed (e.g. queue retry count edited in OR after import). Refresh is import-only by design; mutations are reserved for explicit local edits via SW UI or a future `solution resource update` CLI command.
+- **At deploy, both projects' runtime dependencies point at the same `resourceKey`.** This is correct — they share the cloud resource. The deploy folder gets one queue (or one link to an existing one if you've used `deploy config link`).
+- **At publish/upload time you cannot have two solution-level entries with the same cloud key.** If you accidentally produce that state by hand-editing files, `pack` rejects with a duplicate-key error.
+
+## Verify
+
+```bash
+uip solution resource list --source local --kind Queue --output json | jq '.Data[] | select(.Name == "OrdersQueue")'
+```
+
+Exactly one entry, with a key that matches the cloud GUID returned by `uip resource queue get OrdersQueue --folder-path "Shared/Production"`.
+
+> See: [develop-solution.md — Step 7: Refresh Resources](../develop-solution.md#step-7-refresh-resources).