@uipath/skills 1.195.0

package/skills/uipath-admin/references/tenant-management.md

@@ -0,0 +1,308 @@
+# Tenant Management
+
+Multi-step workflows for managing tenants and their services via `uip admin tenants`. For per-command flag tables, output codes, and single-command examples, see [tenants-commands.md](tenants-commands.md).
+
+## Concept
+
+A tenant lives inside an organization. Each tenant has its own lifecycle status (`Enabled`, `Disabled`, `Updating`, `Deleted`) and its own service provisioning surface.
+
+> **Two `status` fields, don't confuse them.** Tenant *lifecycle* status (`Enabled` / `Disabled` / `Updating` / `Deleted`) lives on the tenant record. Async *operation* status (`Pending` / `Running` / `InProgress` / `Succeeded` / `Failed` / `Cancelled`) lives on the `operationId` response. The poll endpoint reports operation status; the tenant `status` only flips after the operation reaches `Succeeded`.
+
+- **Tenant lifecycle is async.** `create`, `update`, `delete`, `enable`, `disable` all return an `operationId`. Auto-poll per the [shared Polling procedure](organization-management.md#polling-procedure-auto-poll-then-hand-off) (3 × 5 s, then ask the user). Every async workflow below assumes this procedure — `(poll)` in a step means "follow the shared procedure".
+- **Service provisioning is synchronous.** `services add`, `enable`, `disable`, `remove` return immediately. No polling required.
+- **Soft-delete only.** No hard-delete flag. Reversible via the restore flow.
+- **Positional tenant id defaults to the login tenant.** Convenient for read ops; dangerous for destructive ops — always pass the explicit `<TENANT_ID>` for `delete`, `disable`, and `services remove`.
+
+## Workflow: Resolve a Tenant UUID by Name
+
+Standard pattern across `uip admin`:
+
+```bash
+uip admin tenants list --filter "<NAME>" --output json
+```
+
+Extract `id` from the result before calling `get`, `update`, `delete`, `enable`, `disable`, or `services` commands that take an explicit tenant id.
+
+## Workflow: List Tenants — Surface Lifecycle Status
+
+When showing tenants to the user, always include each tenant's `status` (`Enabled`, `Disabled`, `Updating`, or `Deleted`). A `Deleted` tenant is soft-deleted and still visible until purged — call this out so the user knows it is recoverable but not active.
+
+```bash
+uip admin tenants list --output json
+uip admin tenants list --status Enabled --output json
+```
+
+For each row: tenant name, UUID (so the user can copy it into the next command), region, status. If the user asked "what tenants exist?" do not silently filter out `Disabled` or `Deleted` tenants — show all and label them.
+
+## Workflow: List Tenant Services — Provisioned vs. Available
+
+Two distinct surfaces — never merge them:
+
+| Verb | Returns | Has lifecycle status? |
+|---|---|---|
+| `tenants services list` | **Provisioned** service instances on the tenant (what currently exists) | Yes — `Enabled`, `Disabled`, or `Deleted` (soft-deleted) |
+| `tenants services list-available --region <R>` | **Catalog** of service types that *can* be provisioned in that region | No — catalog entries are not provisioned |
+
+### Currently provisioned on a tenant (with status)
+
+```bash
+uip admin tenants services list --tenant-id <TENANT_ID> --output json
+```
+
+Surface to the user as **"Provisioned services on tenant `<TENANT_NAME>`"**. Per row: service type, **status** (`Enabled` / `Disabled` / `Deleted`), region. Flag any soft-deleted (`Deleted`) entries explicitly — they are removed but still recoverable.
+
+If the result is empty, say so explicitly. Do not show an empty table.
+
+Optional filters (client-side):
+
+```bash
+uip admin tenants services list --tenant-id <TENANT_ID> --service orchestrator --output json
+uip admin tenants services list --tenant-id <TENANT_ID> --region "<REGION>" --output json
+```
+
+If `--tenant-id` is omitted, the CLI uses the **login tenant**. Always resolve and state which tenant the listing covers so the user is not guessing.
+
+### Available to provision on a tenant (catalog only)
+
+```bash
+uip admin tenants services list-available --region "<REGION>" --output json
+```
+
+Surface to the user as **"Available service catalog for region `<REGION>`"**. Do NOT add a status column — catalog entries have no lifecycle state. The catalog is **region-aware**: a service can appear in one region's catalog and not another's.
+
+### When the user's intent is ambiguous
+
+If the user says "show services on this tenant" without specifying, run both `services list` and `services list-available --region <TENANT_REGION>` and present them in two clearly labeled sections.
+
+## Mutation Echo Rules
+
+Before any tenant lifecycle or tenant-service mutation, echo the resolved target back so the user knows exactly which resource will change:
+
+| Mutation | Echo this |
+|---|---|
+| `tenants create` | `Organization: <ORG_NAME>` + `New tenant name: <NAME>` + `Region: <REGION>` |
+| `tenants update / enable / disable / delete` | `Tenant: <TENANT_NAME> (<TENANT_UUID>)` + the action. If `<TENANT_ID>` was omitted and the CLI defaults to the login tenant, state: `Tenant: <LOGIN_TENANT_NAME> (login-tenant default)` and confirm with the user before any destructive verb. |
+| `services add / enable / disable / remove` | `Tenant: <TENANT_NAME>` + `Service: <SERVICE_TYPE>` + (for `add`) `Region: <TENANT_REGION>`. For multi-service `--file` payloads, list every service. |
+
+Resolve UUIDs to names — never leave a raw `tenantId` in the echo. `tenants get <TENANT_ID> --output json` gives you both name and region.
+
+## Workflow: Create a Tenant
+
+Run as a **wizard** — never accept a single-shot "create tenant X" and submit. Collect each required field interactively, validate it before moving on, and echo a confirmation summary before calling the API. Skip a step only if the user has already supplied that exact value in their request.
+
+### Step 1 — Tenant name
+
+Ask the user for the display name, then validate **client-side** before doing anything else:
+
+- Alphanumeric only (no `-`, `_`, spaces, or special chars).
+- Must start with a letter.
+- 2–32 chars.
+
+If the name fails, push back and ask for a corrected one. Do not call the API to "see what happens".
+
+### Step 2 — Region
+
+Fetch the available regions for the org and present them as a numbered list:
+
+```bash
+uip admin organizations regions list --output json
+```
+
+Render a numbered Markdown list (`1. Europe`, `2. UnitedStates`, ...) and ask the user to reply with a digit. Do not assume a default region.
+
+### Step 3 — Environment (optional)
+
+Ask the user to pick an environment tag — numbered list of `Production`, `NonProduction`, `Development`, or "skip". If the user skips, omit the field from the body.
+
+### Step 4 — Services
+
+Fetch the region-specific catalog and apply the **default-provision filter** (`provisioningMode === "Implicit"` AND `isVisible === true` AND `isAlwaysProvision === false`):
+
+```bash
+uip admin tenants services list-available --region "<REGION>" --output json \
+  --output-filter "[?provisioningMode=='Implicit' && isVisible==\`true\` && isAlwaysProvision==\`false\`].name"
+```
+
+> Filter root is the `Data` array itself — start the expression with `[?...]`, NOT `Data[?...]`.
+
+Present the resulting service names as a numbered list. Ask the user to confirm the default set, remove unwanted entries, or add Explicit services on request. The catalog is region-aware — never hardcode the default set.
+
+Catalog metadata cheatsheet (for deciding what to surface):
+- `isAlwaysProvision === true` → platform-pinned, auto-provisioned, don't list as a choice.
+- `isVisible === false` → platform-internal, don't surface.
+- `provisioningMode === "Explicit"` → optional opt-in, offer only on request.
+
+### Step 5 — Confirm and submit
+
+Echo the resolved values per the [Mutation echo rules](#mutation-echo-rules) (organization, name, region, plus the resolved environment + services list) and wait for the user's go-ahead.
+
+Then write `./tenant.json` and submit. **Always use `--file`** — the inline path (`--name --region --environment`) does not populate the required `services` field and returns `HTTP 400: The Services field is required.`
+
+```bash
+uip admin tenants create --file ./tenant.json --output json
+```
+
+`./tenant.json` is a `CreateTenantRequestDto`. The `services` field is a **plain string array of catalog `name` values** (e.g. `taskmining`, `du`) — NOT a `{name: true}` map; that's the `services add` shape and OMS rejects it on create with `services.<name>.services: Cannot deserialize ... IList<string>`:
+
+```json
+{
+  "name": "<TENANT_NAME>",
+  "region": "<REGION>",
+  "environment": "<ENV>",
+  "services": ["<SERVICE_NAME>", "<SERVICE_NAME>", "..."]
+}
+```
+
+Platform-pinned services (`isAlwaysProvision === true`) are added automatically regardless of what's in `services[]`; don't list them.
+
+### Step 6 — Poll the operation
+
+Response includes both the new tenant `id` and an `operationId`. Poll the operation until it reaches a terminal status (`Succeeded` / `Failed` / `Cancelled`):
+
+```bash
+uip admin organizations operation get <OPERATION_ID> --output json
+```
+
+Same command applies to every async tenant verb — `create`, `update`, `delete`, `enable`, `disable`. Follow the [shared polling procedure](organization-management.md#polling-procedure-auto-poll-then-hand-off): auto-poll 3 × 5 s, then hand off to the user with a numbered menu if still in-progress. Never indefinite-loop.
+
+## Workflow: Update a Tenant
+
+Two shapes:
+
+- **Inline** for simple fields (`--name`, `--region`, `--environment`).
+- **File** for `services{}`, `customProperties`, `color` — pass `--file ./tenant-patch.json` (TenantUpdateDto).
+
+Response includes `operationId`. `(poll)`
+
+## Workflow: Enable or Disable a Tenant
+
+Tenant activation toggle. Both verbs are **async** — capture the `operationId`. `(poll)`
+
+### Enable
+
+```bash
+uip admin tenants enable <TENANT_ID> --output json
+```
+
+Activates a `Disabled` tenant. Idempotent — calling on an already-`Enabled` tenant is a safe no-op.
+
+### Disable
+
+Disabling a tenant blocks all access to its services until re-enabled. **Confirm with the user before running.**
+
+1. Resolve the tenant id explicitly. Do not rely on the login-tenant default for disable.
+2. Confirm with user. State explicitly: *"This will block all access to tenant `<NAME>` until re-enabled."*
+3. Disable, recording an audit reason:
+   ```bash
+   uip admin tenants disable <TENANT_ID> --reason "<FREE_TEXT_REASON>" --output json
+   ```
+4. Capture `operationId`. `(poll)`
+
+`--reason` is optional but recommended — it lands in the audit trail.
+
+## Workflow: Soft-Delete a Tenant
+
+1. Resolve the tenant id explicitly. Do not rely on the login-tenant default.
+2. Confirm with user.
+3. Run `tenants delete <TENANT_ID>`.
+4. Capture `operationId`. `(poll)` Reversible via the restore flow.
+
+## Workflow: Add Tenant Services
+
+Synchronous — no polling.
+
+### Single service (inline)
+
+```bash
+uip admin tenants services add \
+  --tenant-id <TENANT_ID> \
+  --service <SERVICE_TYPE> \
+  --output json
+```
+
+### Multiple services (`--file`)
+
+`add-services.json`:
+
+```json
+{ "services": { "orchestrator": true, "studio": true } }
+```
+
+All file entries must be `true` (use `services remove` for `false`).
+
+```bash
+uip admin tenants services add --tenant-id <TENANT_ID> --file ./add-services.json --output json
+```
+
+## After a Service Mutation — Verify Post-State
+
+`services add / enable / disable / remove` return 200 OK / `Success` regardless of whether server-side state actually changed. After every mutation, re-list and confirm:
+
+```bash
+uip admin tenants services list --tenant-id <TENANT_ID> --output json
+```
+
+Or, when you need a single service's status, filter the tenant record:
+
+```bash
+uip admin tenants get <TENANT_ID> --output-filter "tenantServiceInstances[?serviceType=='<SVC>']" --output json
+```
+
+Surface the resulting `status` to the user. For `disable`, confirm the row now reads `Disabled`; for `remove`, confirm it reads `Disabled` / `Deleted` rather than disappearing silently. See [tenants-commands.md — Concepts](tenants-commands.md#concepts) for the list of services where `disable` / `remove` is a no-op despite the Success code.
+
+## Workflow: Soft-Remove Tenant Services
+
+Synchronous. Server-side soft-delete (no hard-delete option).
+
+> **Pre-flight: prompt the user if the target service cannot actually be removed.** The CLI returns Success on every `services remove` call, but for a fixed set of services the server-side state never changes (`isAlwaysProvision === true` or otherwise platform-pinned). **Before sending the call, check the target list against this set and tell the user — do not silently submit a no-op.**
+>
+> **Cannot be removed (any call is a server-side no-op):**
+> - Orchestrator (`orchestrator`)
+> - Maestro (`maestro`)
+> - Integration Service (`connections`)
+> - Data Fabric (`dataservice`)
+> - Insights (`insights`)
+> - Test Manager (`testmanager`)
+>
+> If any of those appears in the user's request, render: *"Service `<X>` cannot be removed via the CLI — it's pinned by the platform. The call will return Success but the service will stay provisioned. To deprovision, revoke the org entitlement via the UiPath Portal. Continue anyway, or skip `<X>`?"* On "skip", drop it from the file/flag; on "continue anyway", run the call AND warn in the post-state summary that the verification will show the service still present.
+
+### Single service
+
+```bash
+uip admin tenants services remove \
+  --tenant-id <TENANT_ID> \
+  --service <SERVICE_TYPE> \
+  --output json
+```
+
+### Multiple services
+
+`remove-services.json`:
+
+```json
+{ "services": { "orchestrator": false, "studio": false } }
+```
+
+All file entries must be `false`.
+
+```bash
+uip admin tenants services remove --tenant-id <TENANT_ID> --file ./remove-services.json --output json
+```
+
+## Workflow: Disable Tenant Services
+
+Synchronous. **Pre-flight: prompt the user if the target service cannot actually be disabled.** Same pattern as `remove`: the CLI returns Success but the server-side `status` never flips.
+
+> **Cannot be disabled (any call is a server-side no-op):**
+> - Integration Service (`connections`)
+> - Data Fabric (`dataservice`)
+> - Insights (`insights`)
+>
+> If any of those appears in the user's request, render: *"Service `<X>` cannot be disabled via the CLI — it's pinned by the platform. The call will return Success but the service will stay `Enabled`. To deprovision, revoke the org entitlement via the UiPath Portal. Continue anyway, or skip `<X>`?"* On "skip", drop it; on "continue anyway", proceed and warn in the post-state summary.
+
+```bash
+uip admin tenants services disable \
+  --tenant-id <TENANT_ID> \
+  --service <SERVICE_TYPE> \
+  --output json
+```

package/skills/uipath-admin/references/tenants-commands.md

@@ -0,0 +1,354 @@
+# Tenants CLI Command Reference
+
+Complete reference for all `uip admin tenants` commands — tenant lifecycle and tenant-level service provisioning (Organization Management Service / OMS).
+
+For organization commands, see [organizations-commands.md](organizations-commands.md). For workflow-level guidance, see [tenant-management.md](tenant-management.md).
+
+## Global Flags
+
+Every command accepts these flags (omitted from per-command tables):
+
+| Flag | Description |
+|------|-------------|
+| `--output <format>` | Output format: `json`, `table`, `yaml`, `plain` (default: json) |
+| `--output-filter <expression>` | JMESPath expression to filter output |
+| `--log-level <level>` | Log level: `debug`, `info`, `warn`, `error` (default: info) |
+| `--log-file <path>` | Write logs to file instead of stderr |
+| `--login-validity <minutes>` | Override token validity — forces refresh if token expires within this window |
+
+Organization is resolved automatically from the active login session.
+
+## Prerequisites
+
+```bash
+uip login status --output json
+```
+
+If not logged in: `uip login`.
+
+## Concepts
+
+- **Async vs synchronous.** Tenant lifecycle (`create`, `update`, `delete`, `enable`, `disable`) is async — every mutation returns an `operationId`. `list` / `get` and all `services` subcommands are synchronous (200 OK with no body for service mutations).
+- **Single poll endpoint.** All async OMS operations are polled through `uip admin organizations operation get <OPERATION_ID>` — there is no `tenants operation get`.
+- **Soft-delete only.** `tenants delete` has no hard-delete flag. Reversible via the restore flow.
+- **Login-tenant default.** `tenants get`, `update`, `delete`, `enable`, `disable` accept the tenant id positionally — omit it to target the login tenant. Convenient for read ops; **always pass an explicit `<TENANT_ID>` for `delete`, `disable`, and `services remove`** to avoid targeting the wrong tenant.
+- **Region matters at create.** `tenants create` requires `--region`; run `organizations regions list` first to confirm acceptable values.
+- **Tenant service catalog is region-aware.** `tenants services list-available --region <REGION>` returns a per-region catalog.
+- **Service capability gaps — disable / remove are not universal.** Some services accept the call and return `Success` but the state never changes server-side:
+  - **Disable not honored** (no-op): Integration Service (`connections`), Data Fabric (`dataservice`), Insights (`insights`).
+  - **Remove not honored** (rejected or no-op): Orchestrator (`orchestrator`), Maestro (`maestro`), Integration Service (`connections`), Data Fabric (`dataservice`), Insights (`insights`), Test Manager (`testmanager`).
+
+  **Pre-flight: warn the user before submitting.** Don't silently issue a no-op. Render: *"Service `<X>` cannot be {disabled|removed} via the CLI — it's pinned by the platform. The call will return Success but the service will stay {Enabled|provisioned}. To deprovision, revoke the org entitlement via the UiPath Portal. Continue anyway, or skip `<X>`?"* Skip → drop from the call. Continue → run AND warn in the post-state summary.
+
+  Because the CLI returns 200 OK either way, the success code is never proof of state change. After any `services disable` / `services remove`, verify with `tenants get <TENANT_ID> --output-filter "tenantServiceInstances[?serviceType=='<SVC>']"` and inspect the `status` field on the returned instance.
+
+---
+
+## Tenant Lifecycle — `uip admin tenants`
+
+### `tenants list`
+
+List tenants in the caller's organization.
+
+```bash
+uip admin tenants list --output json
+uip admin tenants list --filter "<NAME_FRAGMENT>" --output json
+uip admin tenants list --status Enabled --service orchestrator --output json
+uip admin tenants list --include-services --output json
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--filter <fragment>` | No | Case-insensitive substring match on tenant name (client-side) |
+| `--service <type>` | No | Only tenants with the given service provisioned |
+| `--status <status>` | No | Exact match on lifecycle status (`Enabled`, `Disabled`, `Updating`, `Deleted`) |
+| `--environment <env>` | No | Filter by environment tag (client-side) |
+| `--include-services` | No | Return each tenant's `services` array inline (saves a second call) |
+
+**Output code:** `OmsTenantsList`.
+
+### `tenants get`
+
+Fetch a tenant by id (or the login tenant if omitted).
+
+```bash
+uip admin tenants get <TENANT_ID> --output json
+uip admin tenants get --output json
+```
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `<TENANT_ID>` | No | Tenant UUID — defaults to login tenant |
+
+**Output code:** `OmsTenantGet`.
+
+### `tenants create`
+
+Create a new tenant. **Async** — returns both the new `id` and an `operationId`.
+
+> **`--file` is required in practice.** The server marks the `services` field required on `CreateTenantRequestDto`, but the inline path (`--name --region --environment`) does not populate it — a pure inline call returns `HTTP 400: The Services field is required.` Use a JSON file with the full body for any real create.
+
+```bash
+uip admin tenants create --file ./tenant.json --output json
+```
+
+`./tenant.json` (`CreateTenantRequestDto`):
+
+```json
+{
+  "name": "<TENANT_NAME>",
+  "region": "<REGION>",
+  "environment": "<ENV>",
+  "services": ["<SERVICE_NAME>", "<SERVICE_NAME>", "..."]
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Tenant display name. Alphanumeric, 2–32 chars, starts with a letter. |
+| `region` | Yes | Provisioning region — resolve via `organizations regions list`. |
+| `environment` | No | Environment tag: `Production`, `NonProduction`, or `Development`. |
+| `services` | **Yes** | **Plain string array of service names** to provision (catalog `name` field, e.g. `taskmining`, `du`). NOT a `{name: true}` map — that's the `services add` shape; OMS rejects it on create. Resolve via the **Default-provision filter** in the `services list-available` section below — the catalog is region-aware, never hardcode names. Platform-pinned services (`isAlwaysProvision === true`) are added automatically regardless. |
+| `customProperties` | No | Free-form key/value bag carried with the tenant. |
+| `color` | No | UI color tag. |
+| `isDefaultTenant` | No | Mark as the org's default tenant. |
+
+**Output code:** `OmsTenantCreated`.
+
+### `tenants update`
+
+Patch editable fields on a tenant. **Async** — returns `operationId`.
+
+```bash
+uip admin tenants update <TENANT_ID> \
+  --name "<NEW_NAME>" \
+  --region "<NEW_REGION>" \
+  --environment "<NEW_ENV>" \
+  --output json
+```
+
+| Argument/Flag | Required | Description |
+|---------------|----------|-------------|
+| `<TENANT_ID>` | No | Tenant UUID — defaults to login tenant |
+| `--name <name>` | No | New display name |
+| `--region <region>` | No | New region |
+| `--environment <env>` | No | New environment tag |
+| `--file <path>` | Alternative | Full `TenantUpdateDto` body (required for `services{}`, `customProperties`, `color`) |
+
+At least one field flag (or `--file`) is required. **Output code:** `OmsTenantUpdated`.
+
+### `tenants delete`
+
+Soft-delete a tenant. **Async** — returns `operationId`. No hard-delete flag.
+
+```bash
+uip admin tenants delete <TENANT_ID> --output json
+```
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `<TENANT_ID>` | No | Tenant UUID — defaults to login tenant. **Always pass explicitly for delete.** |
+
+Confirm with user. Restoration goes through the support / restore flow.
+
+**Output code:** `OmsTenantDeleted`.
+
+### `tenants enable`
+
+Activate a tenant. **Async** — returns `operationId`.
+
+```bash
+uip admin tenants enable <TENANT_ID> --output json
+```
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `<TENANT_ID>` | No | Tenant UUID — defaults to login tenant |
+
+**Output code:** `OmsTenantEnabled`.
+
+### `tenants disable`
+
+Disable a tenant. **Async** — returns `operationId`.
+
+```bash
+uip admin tenants disable <TENANT_ID> --reason "<FREE_TEXT_REASON>" --output json
+```
+
+| Argument/Flag | Required | Description |
+|---------------|----------|-------------|
+| `<TENANT_ID>` | No | Tenant UUID — defaults to login tenant. **Always pass explicitly for disable.** |
+| `--reason <text>` | No | Free-text reason — recorded with the action for audit |
+
+**Output code:** `OmsTenantDisabled`.
+
+---
+
+## Tenant-Level Services — `uip admin tenants services`
+
+All service subcommands are **synchronous** (200 OK with no body, no polling).
+
+> **`list` vs `list-available` are different sets — never merge them.** `services list` returns the **currently provisioned** tenant instances (each with a `status`: `Enabled` / `Disabled` / `Deleted`). `services list-available --region <R>` returns the **region-aware catalog** of provisionable service types (no status). Always present them as two clearly labeled sections. See [tenant-management.md — List Tenant Services](tenant-management.md#workflow-list-tenant-services--provisioned-vs-available).
+
+> **Always name the tenant before any service mutation.** `services add/enable/disable/remove` default `--tenant-id` to the **login tenant** — silently. Resolve `<TENANT_ID>` to a name (`tenants get <ID> --output json`) and echo it to the user before running the command, especially for `remove`.
+
+### `services list`
+
+List **currently provisioned** tenant-level service instances. Each row carries a lifecycle `status` — `Enabled`, `Disabled`, or `Deleted` (soft-deleted). Surface the status field in any presentation; flag `Deleted` entries explicitly.
+
+```bash
+uip admin tenants services list --output json
+uip admin tenants services list --tenant-id <TENANT_ID> --output json
+uip admin tenants services list --service orchestrator --output json
+uip admin tenants services list --region "<REGION>" --output json
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--tenant-id <id>` | No | Tenant UUID — defaults to login tenant |
+| `--service <type>` | No | Filter by service type (client-side) |
+| `--region <region>` | No | Filter by region (client-side) |
+
+All filters are client-side. **Output code:** `OmsTenantServicesList`.
+
+### `services list-available`
+
+List the **catalog** of services that can be provisioned for a tenant in a given region. **Region-aware** — the catalog varies by region. Catalog only: entries are not provisioned and have no lifecycle status. Do not show a status column when surfacing results.
+
+```bash
+uip admin tenants services list-available --region "<REGION>" --output json
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--region <region>` | Yes | Provisioning region — required |
+
+Each catalog entry carries provisioning metadata. The agent uses these fields to decide what to propose by default on `tenants create`:
+
+| Field | Meaning | Effect on tenant-create defaults |
+|---|---|---|
+| `provisioningMode` | `Implicit` (auto-provisioned when listed) or `Explicit` (must be deliberately added) | **Defaults set:** filter to `Implicit` only. `Explicit` services are optional opt-ins — offer only on user request. |
+| `isVisible` | `true` if the service is end-user-facing | **Defaults set:** filter to `true`. `false` services are platform-internal (don't surface in any user-facing list). |
+| `isAlwaysProvision` | `true` if the platform automatically provisions this service on every tenant | **Defaults set:** filter to `false`. `true` services are auto-provisioned by the platform — no need to include in the user's choice; they will be there regardless. |
+| `supportedRegions[]`, `defaultRegion`, `entitlement`, `serviceLicenseStatus` | informational | — |
+
+**Default-provision filter** (use for new-tenant proposals): `provisioningMode === "Implicit" && isVisible === true && isAlwaysProvision === false`. Run the filter command below for the target region to get the current set — the catalog is region-aware, never hardcode names. Render the result as the default services on `tenants create`; let the user remove unwanted entries and add Explicit services explicitly. Pass the confirmed catalog `name` values as a string array in the create body's `services` field (NOT the `id` field).
+
+Filter command (note: filter root is the `Data` array itself — use `[?...]`, NOT `Data[?...]`):
+
+```bash
+uip admin tenants services list-available --region "<REGION>" --output json \
+  --output-filter "[?provisioningMode=='Implicit' && isVisible==\`true\` && isAlwaysProvision==\`false\`].name"
+```
+
+**Output code:** `OmsTenantServicesAvailable`.
+
+### `services add`
+
+Provision one or more services on a tenant. **Synchronous.**
+
+```bash
+uip admin tenants services add \
+  --tenant-id <TENANT_ID> \
+  --service <SERVICE_TYPE> \
+  --output json
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--tenant-id <id>` | No | Tenant UUID — defaults to login tenant. **Always pass explicitly for service mutations on non-login tenants.** |
+| `--service <type>` | Yes (inline) | Single service type |
+| `--file <path>` | Alternative | JSON body for multiple services |
+
+`--file ./add-services.json`:
+
+```json
+{ "services": { "orchestrator": true, "studio": true } }
+```
+
+All file entries must be `true` (use `services remove` for `false`).
+
+**Output code:** `OmsTenantServicesAdded`.
+
+### `services enable`
+
+Enable a single service instance on a tenant. **Synchronous.**
+
+```bash
+uip admin tenants services enable \
+  --tenant-id <TENANT_ID> \
+  --service <SERVICE_TYPE> \
+  --output json
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--tenant-id <id>` | No | Tenant UUID — defaults to login tenant. **Always pass explicitly for non-login tenants.** |
+| `--service <type>` | Yes | Service type |
+
+**Output code:** `OmsTenantServiceEnabled`.
+
+### `services disable`
+
+Disable a single service instance on a tenant. **Synchronous.**
+
+```bash
+uip admin tenants services disable \
+  --tenant-id <TENANT_ID> \
+  --service <SERVICE_TYPE> \
+  --output json
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--tenant-id <id>` | No | Tenant UUID — defaults to login tenant. **Always pass explicitly for non-login tenants.** |
+| `--service <type>` | Yes | Service type |
+
+**Output code:** `OmsTenantServiceDisabled`.
+
+> **Not supported on every service.** Integration Service (`connections`), Data Fabric (`dataservice`), and Insights (`insights`) accept the call and return `OmsTenantServiceDisabled` / `Success`, but the service-side `status` never flips to `Disabled`. Verify with `tenants get <TENANT_ID> --output-filter "tenantServiceInstances[?serviceType=='<SVC>']"` and warn the user upfront if they target one of these services.
+
+### `services remove`
+
+Soft-remove one or more services from a tenant. **Synchronous.** Server-side soft-delete (no hard-delete option).
+
+```bash
+uip admin tenants services remove \
+  --tenant-id <TENANT_ID> \
+  --service <SERVICE_TYPE> \
+  --output json
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--tenant-id <id>` | No | Tenant UUID — defaults to login tenant. **Always pass explicitly for service-remove on non-login tenants.** |
+| `--service <type>` | Yes (inline) | Single service type |
+| `--file <path>` | Alternative | JSON body for multiple services |
+
+`--file ./remove-services.json`:
+
+```json
+{ "services": { "orchestrator": false, "studio": false } }
+```
+
+All file entries must be `false`.
+
+**Output code:** `OmsTenantServicesRemoved`.
+
+> **Not supported on every service.** Orchestrator (`orchestrator`), Maestro (`maestro`), Integration Service (`connections`), Data Fabric (`dataservice`), Insights (`insights`), and Test Manager (`testmanager`) cannot be soft-removed — the CLI may return `Success` but the service stays provisioned. Verify with `tenants get` and warn the user upfront if they target one of these services.
+
+---
+
+## Error Handling
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `tenant not found` | Invalid tenant UUID | Resolve via `tenants list --filter <NAME>` |
+| `region not allowed` | `--region` not in available regions | Run `organizations regions list` and use a returned value |
+| `service not available in region` | Service type not in regional catalog | Run `tenants services list-available --region <REGION>` first |
+| `service already provisioned` | Trying to `add` a service that exists | Use `enable` instead, or list current state with `services list` |
+| Operation stuck `Updating` | Async op pending or failed | Poll `organizations operation get <OPERATION_ID>` for status / error |
+| Destructive op targeted login tenant unintentionally | `<TENANT_ID>` omitted | Always pass an explicit tenant id for `delete`, `disable`, `services remove` |
+| `services disable` returned `Success` but `status` still `Enabled` | Service does not support disable (Integration Service, Data Fabric, Insights) | Expected — service-side limitation, not a CLI bug. Inform the user the service cannot be disabled |
+| `services remove` returned `Success` but instance still present | Service does not support remove (Orchestrator, Maestro, Integration Service, Data Fabric, Insights, Test Manager) | Expected — service-side limitation. Inform the user the service cannot be soft-removed |
+| Auth error | Login expired | `uip login status`, then `uip login` |