@uipath/skills 1.195.0

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

@@ -0,0 +1,89 @@
+# Local virtual asset / queue without cloud counterpart
+
+You're shipping a **brand-new** asset (or queue, or bucket) as part of the solution — it doesn't exist in the target tenant yet. You want it provisioned at deploy time, with a value you'll set per environment.
+
+There are two paths to create a virtual resource:
+
+- **From a binding** — write the resource into `bindings_v2.json` (typically via the owning product: Maestro Flow / Case, Studio Web, agent scaffold), then `solution resource refresh` reconciles it into a virtual stub. The flow this page covers.
+- **Atomically, no binding** — `uip solution resource add --source local --kind <kind> --name <name>` (see [develop-solution.md Step 9](../develop-solution.md#step-9-add-a-resource-atomically)). Useful when no project consumes the resource yet (CI provisioning ahead of code), or when an agent is mutating one resource at a time and doesn't want to touch any binding file. Same end state on disk; same deploy behavior. Offline-friendly (no auth round-trip).
+
+## Setup
+
+A binding to a resource that **isn't** in cloud:
+
+```json
+{ "resource": "asset", "key": "ApiBaseUrl",
+  "value": { "name": { "defaultValue": "ApiBaseUrl" },
+             "folderPath": { "defaultValue": "solution_folder" } },
+  "metadata": { "subType": "StringAsset", "bindingsVersion": "2.2", "solutionsSupport": "true" } }
+```
+
+The `folderPath: "solution_folder"` placeholder signals "this resource lives inside the solution, not in a specific cloud folder." Use a real cloud FQN (`"Shared/Production"`) only if you want the asset deployed to that exact folder during `deploy run`.
+
+## What happens at refresh
+
+```
+Synced 1 resources (0 already in solution)
+```
+
+RCS lookup fails (resource doesn't exist), the sync falls through to `createVirtualResourceAsync`, and the asset is created **as a virtual stub** with a local UUID:
+
+```
+resources/solution_folder/asset/stringAsset/ApiBaseUrl.json
+```
+
+The stub has `value: ""` (or the type's placeholder default — `false` for boolean, `0` for number).
+
+## Idempotency on re-refresh
+
+Re-running `solution resource refresh` is a no-op for virtuals at the same `(kind, folder, name)` — the second pass detects the existing stub and skips:
+
+```
+Synced 0 resources (1 already in solution)
+```
+
+If two bindings point at the same name in **different non-`solution_folder` cloud folders**, both create stubs and the second is suffixed `_1` (same SDK uniqueness algorithm as [same-name-across-folders](same-name-across-folders.md)).
+
+## What happens at deploy
+
+`solution deploy run --config-file <path>` validates the deployment config server-side. A virtual asset with no value fails fast:
+
+```
+[1009] asset ApiBaseUrl: Invalid argument 'Value'
+```
+
+This is **expected** — you must either set a value or link the asset to an existing cloud one before deploy. Two options:
+
+```bash
+# Option A: set a value (e.g. environment-specific)
+uip solution deploy config set deploy-config.json ApiBaseUrl value "https://api.production.example.com"
+
+# Option B: link to an existing cloud asset
+uip solution deploy config link deploy-config.json ApiBaseUrl \
+  --name ProductionApiUrl --folder-path "Shared/Production"
+
+# Then deploy
+uip solution deploy run -n MyDeployment --package-name MySolution --package-version 1.0.0 \
+  --folder-name MySolution --parent-folder-path Shared --config-file deploy-config.json
+```
+
+## Gotchas
+
+- **`folderPath: "solution_folder"` vs `"."` vs a real cloud FQN** — all three normalize to "no specific cloud folder" *for the binding*, but the resulting virtual has different `folders[0].fullyQualifiedName` on disk. Stick with `"solution_folder"` (Studio Web's convention) unless you have a reason.
+- **Don't set the asset value in `bindings_v2.json` thinking it'll flow through.** Bindings carry name + folder. The value lives in the deploy config (per-environment) or, for virtuals, comes from `deploy config set`.
+- **Type-specific required fields** beyond `value`: bucket needs `storageContainer`, others have their own. Refresh fills these with type-appropriate placeholders (empty string / 0 / false). Same `[1009] Invalid argument` deploy error if left at placeholder.
+- **A virtual asset has no `referenceKey` in any tool resource file** — bindings reference virtuals by name + folder, not by key. Don't try to copy a stub's UUID into a tool's `referenceKey`.
+- **Virtuals are not pushed to RCS by `solution upload`.** Upload writes the solution to Studio Web; the virtual remains local until deploy turns it into a real cloud resource (or you link it to an existing one).
+
+## Verify
+
+```bash
+# Virtual exists locally
+uip solution resource list --source local --kind Asset --output json
+
+# Deploy config has the resource and its `configuration.value`
+uip solution deploy config get MySolution -d deploy-config.json --output json
+jq '.resources[] | select(.name == "ApiBaseUrl")' deploy-config.json
+```
+
+> See: [pack-and-deploy.md — Configuration Workflow](../pack-and-deploy.md#configuration-workflow).

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

@@ -0,0 +1,51 @@
+# Solution Scenarios
+
+Real multi-project recipes that the step-by-step files don't cover head-on. Each scenario has the setup, the behavior to expect, the gotcha that bites, and a fix. Read these before starting on a complex solution — most of them surface during `solution resource refresh` or `solution deploy run`.
+
+> All scenarios assume you've already read [develop-solution.md](develop-solution.md) and [pack-and-deploy.md](pack-and-deploy.md). Each file links back to the relevant step.
+
+---
+
+## Symptom triage
+
+Land here from a grep on an error message? Pick the matching row.
+
+| You see... | Open |
+|---|---|
+| Suffix `_1` (or `_N`) on a resource file you didn't ask for | [same-name-across-folders](scenarios/same-name-across-folders.md) |
+| Tool dialog in Studio Web won't open for one of two same-name tools | [same-name-across-folders](scenarios/same-name-across-folders.md) |
+| `referenceKey` for an in-solution tool — do I use the cloud key or something else? | [intra-solution-references](scenarios/intra-solution-references.md) |
+| Two projects bind the same cloud resource (queue/asset/bucket) — what does refresh do? | [shared-cloud-resource](scenarios/shared-cloud-resource.md) |
+| `[1009] <kind> <name>: Invalid argument 'Value'` at deploy | [virtual-resource](scenarios/virtual-resource.md) |
+| New asset/queue not on cloud — how do I ship it as part of the solution? | [virtual-resource](scenarios/virtual-resource.md) |
+| `Synced 0 resources (1 already in solution)` on re-refresh | [virtual-resource](scenarios/virtual-resource.md) (idempotency section) |
+| I want to add one virtual queue / asset / bucket without going through bindings | `uip solution resource add --source local --kind <kind> --name <name>` — see [develop-solution.md Step 9](develop-solution.md#step-9-add-a-resource-atomically) |
+| I want to import one existing remote resource into the solution | `uip solution resource add --source remote --kind <kind> --name <name> --folder-path <folder>` — see [develop-solution.md Step 9](develop-solution.md#step-9-add-a-resource-atomically) |
+| I want to delete a single resource by key | `uip solution resource remove <resource-key>` — see [develop-solution.md Step 10](develop-solution.md#step-10-remove-a-resource) |
+| I want to change a field on an existing resource's spec | `uip solution resource edit <resource-key> --patch '{...}'` — see [develop-solution.md Step 11](develop-solution.md#step-11-edit-a-resource) |
+| I edited a spec field but `refresh` didn't pick it up | Expected — `refresh` never overwrites a resource already in the solution. Use `resource edit` to mutate spec. |
+| `resource edit` silently ignored a property I passed | The SDK skips unknown / reference / read-only props by design — see [manual-edits](scenarios/manual-edits.md) for what's editable vs not |
+| My hand-edit got reverted on the next refresh | [manual-edits](scenarios/manual-edits.md) (the SDK re-derives bindings) |
+| Other deploy / refresh failures (folder collision, suffix amplification, missing bindings, version collision) | [failure-modes](scenarios/failure-modes.md) |
+
+---
+
+## Scenarios
+
+| File | When you need it |
+|---|---|
+| [same-name-across-folders](scenarios/same-name-across-folders.md) | Two bindings target a resource with the same name in different cloud folders. The SDK suffixes the second one `_1`. |
+| [intra-solution-references](scenarios/intra-solution-references.md) | A coordinator project needs to invoke a sibling project that ships in the same solution and isn't on cloud yet. |
+| [shared-cloud-resource](scenarios/shared-cloud-resource.md) | Two projects bind the same cloud resource (typically a shared queue/asset/bucket). Refresh dedups silently. |
+| [virtual-resource](scenarios/virtual-resource.md) | Brand-new asset/queue/bucket shipped with the solution — no cloud counterpart yet. Refresh creates a virtual stub; deploy needs a value or link. |
+| [manual-edits](scenarios/manual-edits.md) | The CLI doesn't cover the field you need to edit. What's safe to hand-edit on solution-level files and deploy configs, what isn't. |
+| [failure-modes](scenarios/failure-modes.md) | Cross-cutting symptom→cause→fix table for deploy and refresh failures that don't fit a single scenario. |
+
+---
+
+## Related
+
+- [solution-overview.md](solution-overview.md) — Overview, lifecycle diagram, command tree
+- [develop-solution.md](develop-solution.md) — Step-by-step: new, project add, refresh, list
+- [pack-and-deploy.md](pack-and-deploy.md) — Step-by-step: pack, publish, deploy, configuration
+- [activate-and-manage.md](activate-and-manage.md) — Activate, uninstall, manage packages

package/skills/uipath-solution/references/operate/solution-overview.md

@@ -0,0 +1,125 @@
+# Solutions (`uip solution`)
+
+Create, pack, publish, deploy, and manage UiPath solution packages.
+
+> For full option details on any command, use `--help` (e.g., `uip solution deploy run --help`).
+
+---
+
+## What is a Solution?
+
+A UiPath Solution is a container that groups multiple automation projects (processes, libraries, tests) into a single deployable unit. Solutions enable:
+
+- **Bundled deployment** -- Deploy multiple projects together as one package
+- **Version management** -- Track and version the entire solution as a single entity
+- **Configuration management** -- Apply environment-specific configuration at deploy time
+- **Multi-environment promotion** -- Move solutions through dev, staging, and production
+
+### Solution File Structure
+
+```
+MySolution/
+├── MySolution.uipx                       <- Manifest. Source of truth: project list + IDs + StudioMinVersion.
+├── <ProjectName>/
+│   ├── project.uiproj OR project.json    <- Required for add/import. Type auto-detected.
+│   ├── bindings.json                     <- Agent runtime bindings. NOT scanned by refresh.
+│   ├── bindings_v2.json                  <- Solution refresh reads this (if it exists).
+│   └── ...
+├── <AnotherProjectName>/                 <- A solution can host many projects side-by-side.
+│   ├── project.uiproj OR project.json
+│   ├── bindings_v2.json
+│   └── ...
+├── resources/                            <- Auto-generated on add/import. NEVER hand-edit.
+│   └── solution_folder/
+│       ├── package/<name>.json           <- Auto-created on add. NOT cleaned by `project remove`.
+│       └── process/{process,flow}/<name>.json   <- Auto-created on add. Auto-cleaned on remove.
+└── userProfile/<user-uuid>/              <- Appears after first `project remove`.
+```
+
+> `.uipx` and `resources/solution_folder/` must always agree on the set of projects. Diffing them is the fastest way to detect a corrupted state — see [develop-solution.md - Field-tested gotchas](develop-solution.md#field-tested-gotchas).
+>
+> The `.uipx` also carries a `StudioMinVersion` field (e.g. `2025.10.0`). If users hit a version-mismatch when opening the solution, that's the constraint to check.
+
+> **Coded apps are not registered in `.uipx`.** UiPath Coded Web Apps and Coded Action Apps have no `project.uiproj` / `project.json` — `uip solution project add` does not apply, and they are not packed by `uip solution pack`. They deploy independently via `uip codedapp publish` / `deploy`. A coded app directory can sit alongside a solution but is not part of its manifest. See [/uipath:uipath-coded-apps](/uipath:uipath-coded-apps).
+
+---
+
+## Solution Lifecycle
+
+```mermaid
+graph LR
+    A[init] --> B[project add]
+    B --> C[resource refresh]
+    C --> D[pack]
+    D --> E[publish]
+    E --> F["deploy run<br/>(auto-activate by default)"]
+    F -->|--skip-activate| G[activate]
+    C --> H[upload]
+```
+
+Two distinct distribution paths from the same solution source:
+- **`pack` → `publish` → `deploy run`** — promotes a versioned package to Orchestrator.
+- **`upload`** — pushes the solution to Studio Web for browser-based debugging only. Does not produce a published package and cannot be deployed via `deploy run`.
+
+Always run `resource refresh` before either path so the bundled artefact files and `userProfile/<userId>/debug_overwrites.json` reflect the current cloud state.
+
+---
+
+## Command Tree
+
+```
+uip solution
+  ├── init <name>                         Create a new solution directory with .uipx manifest
+  │                                        (pre-rename CLIs expose this as `new`; see SKILL.md Operate-half "CLI Surface Probe")
+  ├── delete <solution-id>                Delete a solution from Studio Web
+  ├── upload <path>                       Upload solution to Studio Web
+  ├── pack <solution> <output>            Pack into a deployable .zip package
+  ├── publish <package>                   Upload packed solution to UiPath
+  ├── project
+  │     ├── add <project-path> [solutionFile]   Register an existing subfolder in .uipx
+  │     ├── remove <project-path> [solutionFile] Unregister a project from .uipx
+  │     ├── import --source <path>              Copy external project into solution and register
+  │     └── list                                List projects registered in the local .uipx (no backend call)
+  ├── resource
+  │     ├── list                          List local, remote, or all resources (--solution-folder, default cwd)
+  │     ├── refresh                       Sync resource declarations from project bindings (--solution-folder, default cwd)
+  │     ├── get <resource-key>            Get full configuration for a single resource — local or remote (--solution-folder, default cwd)
+  │     ├── add                           Add one resource atomically: --source local|remote --kind <kind> --name <name>
+  │     ├── remove <resource-key>         Delete one resource from the solution by key (offline, no auth)
+  │     └── edit <resource-key>           Patch an existing resource's spec via --patch '<json>' (or '-' for stdin)
+  ├── deploy
+  │     ├── run -n <name>                 Deploy a published solution package (auto-activates by default; pass --skip-activate to opt out)
+  │     ├── status <id>                   Check deployment status
+  │     ├── list                          List deployments
+  │     ├── activate <name>               Activate a deployment (only needed after --skip-activate or to retry a failed auto-activation)
+  │     ├── uninstall <name>              Uninstall a deployment
+  │     └── config
+  │           ├── get <package-name>      Fetch default deploy config
+  │           ├── set <file> ...          Set a resource property in config
+  │           ├── link <file> <resource>  Link to an existing Orchestrator resource
+  │           └── unlink <file> <resource> Remove a resource link
+  └── packages
+        ├── list                          List published solution packages
+        ├── download <name> [version]      Download a published solution package .zip
+        └── delete <name> <version>       Delete a specific package version
+```
+
+---
+
+## Workflow References
+
+Each workflow doc covers a multi-command choreography for a specific goal. Load the one that matches your task.
+
+| Workflow | File | Covers |
+|----------|------|--------|
+| Develop a Solution | [develop-solution.md](develop-solution.md) | Create, add projects, manage resources, upload |
+| Pack & Deploy | [pack-and-deploy.md](pack-and-deploy.md) | Pack, publish, deploy run, deploy config |
+| Activate & Manage | [activate-and-manage.md](activate-and-manage.md) | Activate, uninstall, packages list/delete |
+| Scenarios | [scenarios.md](scenarios.md) | Multi-project recipes — same-name across folders, intra-solution cross-refs, shared cloud resources, virtual assets at deploy |
+
+---
+
+## Related
+
+- **Orchestrator** (`uip or`) — folders, processes, jobs, machines → [`uipath-orchestrator`](../orchestrator/orchestrator.md)
+- **Resources** (`uip resource`) — assets, queues, buckets used by solutions → [`uipath-resources`](../resources/resources.md)

package/skills/uipath-tasks/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: uipath-tasks
+description: "UiPath Action Center human-in-the-loop tasks via `uip tasks` — list, assign, complete approval/validation tasks. For authoring HITL nodes in flows/agents→uipath-human-in-the-loop. For Orchestrator→uipath-platform, codedapp→uipath-coded-apps. Skip Document Understanding."
+when_to_use: "User says 'approve task', 'pending approval', 'pending action item', 'review action', 'list my tasks', 'reassign task' in an Orchestrator/Action Center context. NOT for TaskCreate/TaskUpdate (general session-task tracking) or Document Understanding validation."
+user-invocable: true
+---
+
+# UiPath Tasks (Action Center) — Agent Skill
+
+> **Preview** — skill is under active development; surface and behavior may change.
+
+Action Center is UiPath's human-in-the-loop platform. Tasks represent work items
+that require human input — form approvals, document validation, data labeling, and more.
+
+All operations go through `uip tasks <verb> --output json`.
+
+---
+
+## Login & Tenant Setup
+
+**Default to Production. Only switch environment/org/tenant when explicitly stated in the request.**
+
+- If the request mentions no environment → use the current session (defaults to prod `cloud.uipath.com`)
+- If the request explicitly names an environment/org/tenant → check `uip login status` and re-login if needed
+
+When switching is required:
+1. Check current login: `uip login status --output json` — verify `UIPATH_URL`, `Organization`, and `Tenant`
+2. Re-login with `--authority` only if environment differs:
+   - Alpha: `uip login --authority https://alpha.uipath.com --tenant <tenant>`
+   - Staging: `uip login --authority https://staging.uipath.com --tenant <tenant>`
+   - Production: `uip login --tenant <tenant>` (default, no `--authority` needed)
+3. If already on the right environment but wrong tenant: `uip login tenant set <tenant-name>`
+
+```bash
+# Check current environment, org, and tenant
+uip login status --output json
+
+# Login to Alpha with a specific tenant
+uip login --authority https://alpha.uipath.com --tenant MyTenant
+
+# List all available tenants (after login)
+uip login tenant list --output json
+
+# Switch tenant within the same environment
+uip login tenant set MyTenant
+```
+
+> **Critical:** The `--tenant` flag on `tasks` commands does NOT switch the active session tenant.
+> The environment is determined by `UIPATH_URL` in the auth file — always confirm with `login status` before running `tasks` commands.
+
+---
+
+## When to Use
+
+- Listing or inspecting Action Center tasks across folders
+- Assigning, reassigning, or unassigning tasks to users
+- Completing tasks with action outcomes and data payloads
+- Querying which users have task permissions in a folder
+
+> **Not in scope:** Orchestrator queues or queue items (use `uip or`), Document Understanding model training, or Action Center app development (use `uip codedapp`).
+
+---
+
+## Task Types
+
+| Type | CLI value | Description |
+|------|-----------|-------------|
+| Form task | `FormTask` | Form-based approval/action task |
+| External task | `ExternalTask` | Generic external task |
+| App task | `AppTask` | Action Center app-based task |
+| Document validation | `DocumentValidationTask` | Document Understanding validation |
+| Document classification | `DocumentClassificationTask` | Document Understanding classification |
+| Data labeling | `DataLabelingTask` | Data labeling task |
+
+---
+
+## Task Statuses & Priorities
+
+| Status | Meaning |
+|--------|---------|
+| `Unassigned` | Created but not assigned to any user |
+| `Pending` | Assigned, awaiting completion |
+| `Completed` | Completed with an action/outcome |
+
+| Priority | Level |
+|----------|-------|
+| `Low` | Low |
+| `Medium` | Medium (default) |
+| `High` | High |
+| `Critical` | Critical |
+
+---
+
+## Quick Start
+
+```bash
+# Check login and active tenant
+uip login status --output json
+
+# Switch tenant if needed
+uip login tenant set <tenant-name>
+
+# List all tasks across folders
+uip tasks list --output json
+
+# Get details of a specific task
+uip tasks get <task-id> --output json
+
+# Assign a task to a user
+uip tasks assign <task-id> --user alice@company.com --output json
+
+# Complete a task
+uip tasks complete <task-id> --type ExternalTask --folder-id <folder-id> --output json
+```
+
+---
+
+## Critical Rules
+
+1. **Always resolve org and tenant first.** If the user specifies an org/environment and tenant, run `uip login status` to check the active tenant, then `uip login tenant set <tenant>` to switch if needed. Never assume the active tenant matches the user's intent.
+
+2. **Task IDs are numeric.** Unlike other UiPath services that use GUIDs, Action Center uses numeric task IDs. Use `tasks list` to discover task IDs.
+
+3. **Folder ID is required for complete.** Tasks are scoped to folders. Use `--folder-id` when completing tasks.
+
+4. **Complete requires `--type`.** The API routes to different endpoints per task type. Always include `--type` when completing a task. Use `tasks get` to check the task type first.
+
+5. **FormTask and AppTask require `--action` and `--data` for completion.** Other task types allow optional action and data.
+
+6. **Assign accepts `--user-id` or `--user` (email).** Use `tasks users <folder-id>` to discover assignable users and their IDs.
+
+7. **Always discover before acting.** Use `tasks list` or `tasks get` to inspect task state before performing assign/complete operations.
+
+8. **Do not complete already-completed tasks.** Check the task `status` field — if it is `Completed`, inform the user.
+
+---
+
+## Task Navigation
+
+| Task | Commands to use |
+|------|----------------|
+| List all tasks | `tasks list` |
+| List tasks in a folder | `tasks list --folder-id <id>` |
+| List tasks as admin | `tasks list --as-admin` |
+| Get task details | `tasks get <task-id>` |
+| Get task with type hint | `tasks get <task-id> --task-type FormTask --folder-id <id>` |
+| Assign a task | `tasks assign <task-id> --user <email>` |
+| Assign by user ID | `tasks assign <task-id> --user-id <id>` |
+| Reassign a task | `tasks reassign <task-id> --user <email>` |
+| Unassign a task | `tasks unassign <task-id>` |
+| Complete a task | `tasks complete <task-id> --type <type> --folder-id <id>` |
+| Complete with action | `tasks complete <task-id> --type FormTask --folder-id <id> --action "Approve" --data '{...}'` |
+| List assignable users | `tasks users <folder-id>` |
+
+---
+
+## Workflow: Discover → Plan → Act → Verify
+
+**Always follow this pattern:**
+
+1. **Discover** — list tasks, get details, find assignable users
+2. **Plan** — determine the operation (assign, complete, etc.)
+3. **Act** — execute the operation
+4. **Verify** — re-read the task to confirm the state change
+
+```bash
+# 0. Ensure correct tenant
+uip login status --output json
+uip login tenant set <tenant-name>   # only if needed
+
+# 1. Discover
+uip tasks list --output json
+uip tasks get <task-id> --output json
+
+# 2. Plan — determine the task type, folder ID, and action needed
+
+# 3. Act — assign a task
+uip tasks assign <task-id> --user alice@company.com --output json
+
+# 4. Verify
+uip tasks get <task-id> --output json
+```
+
+---
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Not logged in` | Auth expired | `uip login` |
+| `HTTP 401` | Invalid token | Re-login |
+| `HTTP 403` | Permission denied | Ensure account has Action Center permissions in the folder |
+| `Missing assignee` | Neither `--user-id` nor `--user` provided | Add `--user <email>` or `--user-id <id>` |
+| `Task not found` | Wrong task ID | Run `tasks list` to get correct ID |
+| Completion fails | Wrong `--type` | Use `tasks get` to check the actual task type |
+| Completion fails for FormTask | Missing `--action` or `--data` | FormTask and AppTask require both `--action` and `--data` |
+| Cannot assign | User lacks permissions in folder | Run `tasks users <folder-id>` to list eligible users |
+
+---
+
+## References
+
+For deeper guidance, read these files only when needed:
+
+- `references/task-lifecycle.md` — Listing and getting tasks, type-hint endpoint routing, and the full discover→assign→complete workflow
+- `references/task-completion.md` — Completion endpoint routing, required fields per task type
+- `references/task-assignment.md` — Assign, reassign, unassign patterns and user discovery
+- `references/action-center-urls.md` — Canonical Action Center URL patterns; **read this before constructing or sharing any task deep-link** (the portal-UI misclassifies tenant-less URLs as "Orchestrator not enabled")

package/skills/uipath-tasks/references/action-center-urls.md

@@ -0,0 +1,152 @@
+# Action Center URL patterns
+
+Reference guidance for constructing Action Center / Orchestrator task URLs.
+**The tenant slug is mandatory in every form.** Without it, the portal-UI
+parser interprets the next URL segment as the tenant name and routes to
+the "Orchestrator is not enabled for this tenant" page even when the
+service is fully enabled — sending the user down a wrong support path
+(admin/license escalation instead of "fix your URL").
+
+## The two canonical patterns
+
+There are two URL forms in active use. Always use the one that matches your
+target surface; both require all four segments below.
+
+### 1. Action Center inbox deep-link
+
+```text
+https://{host}/{org}/{tenant}/orchestrator_/actions/inbox/{taskKey}
+```
+
+* **When to use:** linking to a *task in the inbox* — the form a user sees
+  in Action Center's task-list landing.
+* **Example:**
+  `https://cloud.uipath.com/popoc/DefaultTenant/orchestrator_/actions/inbox/abc-123-def-456`
+
+### 2. Action Center standalone task URL
+
+```text
+https://{host}/{org}/{tenant}/actions_/current-task/tasks/{taskId}
+```
+
+* **When to use:** linking *directly to a single task* (typically from
+  Coded Action Apps, notification emails, or the standalone task page).
+  This is the form documented in `uipath-coded-apps/references/patterns.md`.
+* **Example:**
+  `https://cloud.uipath.com/popoc/DefaultTenant/actions_/current-task/tasks/42`
+* **Embed variant:** prefix `embed_/` for iframe rendering:
+  `https://cloud.uipath.com/embed_/popoc/DefaultTenant/actions_/current-task/tasks/42`
+
+## Mandatory segments
+
+Every URL above MUST include:
+
+| Segment    | Source                                                | Notes |
+|------------|-------------------------------------------------------|-------|
+| `{host}`   | UI host (NOT the API host — see "Environment mapping" below) | `cloud.uipath.com`, `staging.uipath.com`, `alpha.uipath.com` |
+| `{org}`    | Organization name or ID                               | URL-encode if it contains spaces/unicode. |
+| `{tenant}` | Tenant **name** (e.g. `DefaultTenant`)                | **Mandatory.** Never substitute a path keyword like `actions` here. |
+| `{taskKey}` or `{taskId}` | From `uip tasks get` / `uip tasks list` JSON | Use `Key` (string GUID) for inbox; numeric `Id` for standalone. |
+
+## Anti-pattern: missing tenant slug
+
+```text
+❌ https://alpha.uipath.com/popoc/orchestrator_/actions/inbox/<taskKey>
+                          ^^^^^^^
+                          tenant slug missing
+```
+
+The portal-UI parser interprets `actions` (the next segment) as the tenant
+name, then redirects to:
+
+```text
+/portal_/unregistered?serviceType=orchestrator&organizationName=popoc&tenantName=actions
+```
+
+…rendering "Orchestrator is not enabled for this tenant." This is wrong:
+the service is enabled; only the URL is malformed. **Always include the
+tenant.** If you don't know it, run `uip login status --output json` and
+read `tenantName` from the response before constructing the URL.
+
+## Environment mapping (API host ≠ UI host)
+
+The Action Center URLs above use the **UI host**, which differs from the
+API host that backs `uip` CLI calls. Never paste an API host into one of
+these URLs.
+
+| API host                   | UI host                    |
+|----------------------------|----------------------------|
+| `api.uipath.com`           | `cloud.uipath.com`         |
+| `staging.api.uipath.com`   | `staging.uipath.com`       |
+| `alpha.api.uipath.com`     | `alpha.uipath.com`         |
+| `gov.api.uipath.com`       | `gov.uipath.com`           |
+
+If `uip login status` reports a base URL of `https://alpha.api.uipath.com`,
+strip the `api.` prefix before building an Action Center URL.
+
+> **Note:** the table covers the four common public environments. Regional
+> (e.g. EU-specific) and private/dedicated cloud hosts may use different
+> prefixes. When in doubt, take the host from `uip login status --output
+> json` and apply the same `api.X → X` transformation; if the base URL
+> already lacks the `api.` prefix, use it verbatim.
+
+## Agent guidance: when surfacing a task URL to the user
+
+If your skill needs to print or hand off an Action Center URL:
+
+1. **Resolve `{org}` and `{tenant}` from the live login session**, not from
+   memory or the conversation. Run `uip login status --output json` and
+   read `organizationName` (or `organizationId` as fallback) and
+   `tenantName`. Treat any `null`/missing tenant as a hard error — do not
+   construct the URL.
+2. **URL-encode** any segment that may contain spaces or unicode (org
+   names, tenant names, taskKey strings).
+3. **Map API host → UI host** if the login's base URL is the API host.
+4. **Choose the form** based on the destination: inbox-with-list-context
+   (`/orchestrator_/actions/inbox/{taskKey}`) vs. direct-task-view
+   (`/actions_/current-task/tasks/{taskId}`).
+5. **Self-check before handing off** — before printing the URL, validate
+   that it matches the canonical pattern (`/orchestrator_/actions/inbox/`
+   or `/actions_/current-task/tasks/`) and that **all four segments**
+   (`{host}`, `{org}`, `{tenant}`, `{taskKey}` or `{taskId}`) are present
+   and non-empty. If any segment is missing, refuse to emit the URL and
+   tell the user which piece of context you couldn't resolve. Then hand
+   the URL off to the user for click-through verification — if they land
+   on the `/portal_/unregistered` "Orchestrator is not enabled" page,
+   that's the missing-tenant symptom and the URL is malformed (re-check `{tenant}`).
+
+## CLI-side helpers (for tool authors)
+
+The `uip` CLI ships canonical builders in `@uipath/common`. If you're
+extending the CLI rather than constructing URLs by hand from a skill,
+import these:
+
+> **Availability:** these helpers ship in `@uipath/common` once the
+> companion CLI PR ([UiPath/cli#1565](https://github.com/UiPath/cli/pull/1565))
+> lands. If your `bun install` predates that merge, the imports below
+> will not resolve — pull a fresh `@uipath/common`, or hand-build the
+> URL following the canonical patterns above (the runtime contract is
+> identical).
+
+```typescript
+import {
+    buildActionCenterInboxUrl,
+    buildActionCenterTaskUrl,
+    buildOrchestratorUrl,
+} from "@uipath/common";
+
+const inboxUrl = buildActionCenterInboxUrl(uiHost, org, tenant, taskKey);
+//   → https://cloud.uipath.com/popoc/DefaultTenant/orchestrator_/actions/inbox/<taskKey>
+
+const taskUrl = buildActionCenterTaskUrl(uiHost, org, tenant, taskId);
+//   → https://cloud.uipath.com/popoc/DefaultTenant/actions_/current-task/tasks/42
+```
+
+All three helpers throw if `tenant` (or `org` / `baseUrl`) is empty —
+this is the runtime backstop for the tenant-required contract. See
+`packages/common/src/orchestrator-urls.ts` in the [CLI repo](https://github.com/UiPath/cli).
+
+## Related
+
+* `uipath-coded-apps/references/patterns.md` — already documents the
+  standalone form for Coded Action App developers (React/TypeScript).