@uipath/skills 1.201.0-preview.621 → 1.202.0-preview.635

package/skills/uipath-admin/references/authorization/check-access.md

@@ -1,54 +1,36 @@
 # Check Access (Effective Permissions)
 
-Conceptual guide and scope-specific workflows for `uip admin authorization check-access`. For the full flag/argument table and output code, see [authorization-commands.md — Check Access](authorization-commands.md#check-access--uip-admin-authorization-check-access).
+Guide for `uip admin authorization check-access`. See [authorization-commands.md — Check Access](authorization-commands.md#check-access--uip-admin-authorization-check-access) for the complete flag/argument table and output codes.
 
-## Concept
+## Purpose and Output
 
-`check-access` is the **Policy Decision Point (PDP)**. It answers: *"What can this principal actually do at this scope, right now?"*
+`check-access` is the Policy Decision Point (PDP): it reports what a principal can do at a scope now. Unlike `roles assignments list`, which reads PAP catalog assignments, it evaluates effective access, including server-side role catalogs managed by `orchestrator`, `dataservice`, `insights`, `taskmining`, `testmanager`, `automationops`, `casemanagement`, and `processmining`. The catalog still exposes those roles and assignments through `roles list --service <svc>` and `roles assignments list --service <svc>`, but the PDP is authoritative for resolved permissions.
 
-Unlike `roles assignments list` (which reads stored assignments from the PAP catalog), `check-access` evaluates **effective** access — it folds in server-side rules from services that manage their own role catalogs (`orchestrator`, `dataservice`, `insights`, `taskmining`, `testmanager`, `automationops`, `casemanagement`, `processmining`) that the PAP catalog alone may not reflect. The catalog *does* surface these services' roles and assignments (`roles list --service <svc>` / `roles assignments list --service <svc>`), but the PDP is the source of truth for "what permissions resolve right now".
+Returned `Data` includes `roleAssignments.results[]` effective roles. Each row contains `roleId`, `roleName`, `serviceName` (display-name form), `roleType`, and nested `roleAssignments[]` entries for underlying grants. It also includes `grantedServicesMetadata` (services with any access) and `grantedRolesMetadata` (roles contributing to the result).
 
-Returned `Data`:
+Inspect every nested `roleAssignments[]` entry; do not collapse paths:
 
-- `roleAssignments.results[]` — list of effective roles the principal has at the scope. Each row is a role with metadata (`roleId`, `roleName`, `serviceName` (display-name form), `roleType`) **and a nested `roleAssignments[]` array** recording each underlying grant.
-- `grantedServicesMetadata` — services the principal has any access to.
-- `grantedRolesMetadata` — roles contributing to the result.
+| Entry | Report label |
+|---|---|
+| `securityPrincipalType: "User"` and `securityPrincipalId == queried-user-id` | `direct` |
+| `securityPrincipalType: "Group"` | `inherited from <Group displayName>` |
+| `securityPrincipalType: "Robot"` or `"ExternalApplication"` | `via <Robot\|ExternalApplication> <name>` |
 
-## Direct vs. Inherited — Always Surface the Distinction
+For group entries, resolve `securityPrincipalId` with `uip admin groups get <id> --output json`, cache lookups within one report, and treat the entry as a group of which the user is a member. Explain that revoking a direct grant targets the user’s assignment; revoking an inherited grant requires changing group membership or the group’s role binding.
 
-`check-access` aggregates effective permissions from **direct** user grants AND grants the user **inherits via group membership**. The user needs to see which is which — revoking a direct grant means targeting the user's own assignment; revoking an inherited grant means changing group membership (or the group's role binding).
+Group roles by the response’s `serviceName`, verbatim. When only `ownerServiceName` is available from `roles get`, translate it using [authorization-commands.md — Service display-name mapping](authorization-commands.md#service-display-name-mapping). Include scope and service span where useful:
 
-For every role in `roleAssignments.results[]`, inspect the nested `roleAssignments[]`:
+```text
+Effective access for <user> at tenant <tenant> — spans <N> services: <service labels>
 
-| Nested entry | Interpretation | Label to render |
-|---|---|---|
-| `securityPrincipalType: "User"` AND `securityPrincipalId == queried-user-id` | Role assigned directly to this user | `direct` |
-| `securityPrincipalType: "Group"` | Role assigned to a group the user is a member of | `inherited from <Group displayName>` — resolve the `securityPrincipalId` via `uip admin groups get <id> --output json` (cache lookups within one report) |
-| `securityPrincipalType: "Robot"` / `"ExternalApplication"` | Cross-principal grant (rare on a user `check-access`) | `via <Robot\|ExternalApplication> <name>` |
-
-Multiple entries under one role's `roleAssignments[]` mean the user has the role via multiple paths — list **all** of them; do not collapse.
-
-### Example presentation
-
-```
-Effective access for alice@example.com at tenant Prod-East — spans 3 services: IXP, Orchestrator, Apps
-
-IXP (ownerServiceName: Reinfer)
-  • IXP Tenant Admin     — inherited from Tenant Admins
-  • IXP Project Reader   — direct
-
-Orchestrator
-  • Orchestrator Folder Admin — inherited from Tenant Admins
-
-Apps
-  • App User — direct
+<service label>
+  • <role> — direct
+  • <role> — inherited from <group>
 ```
 
-The response's `serviceName` field is already the display name (e.g., `"IXP"`, `"Data Service"`) — surface verbatim. When you only have `ownerServiceName` from a companion `roles get`, translate via [authorization-commands.md — Service display-name mapping](authorization-commands.md#service-display-name-mapping-cli-ownerservicename--user-facing-label).
-
-## Identity Argument
+## Identity and Scope
 
-The principal is the **positional** first argument — UUID, name, or email. The CLI resolves names and emails via the identity API.
+The principal is the positional first argument: UUID, name, or email. The CLI resolves names and emails through the identity API; there is no `--identity-id` flag. Run:
 
 ```bash
 uip admin authorization check-access <USER_GUID>
@@ -56,50 +38,44 @@ uip admin authorization check-access alice@example.com
 uip admin authorization check-access "Alice Smith"
 ```
 
-There is no `--identity-id` flag. With `--file`, the identity is set in the request body (`SecurityPrincipalId`) and the positional argument is omitted.
+With `--file`, omit the positional argument and set the identity in the request body as `SecurityPrincipalId`.
 
-## Choosing the Scope
+`--scope` accepts only `Tenant` (default) or `Folder`:
 
-`check-access --scope` accepts only **`Tenant`** (default) or **`Folder`** — narrower than the scope vocab on `roles create` or `roles assignments create`.
+| Scope | Use | Required flags beyond identity |
+|---|---|---|
+| `Tenant` | Per-tenant access | `--tenant-id <GUID>` optional; defaults to the login tenant |
+| `Folder` | Folder-scoped access | `--scope Folder --folder-id <FOLDER_ID>`; `--tenant-id` is the owning tenant’s `ParentId` and defaults to the login tenant |
 
-| Scope | When to use | Required flags beyond identity |
-|-------|-------------|--------------------------------|
-| `Tenant` (default if omitted) | Per-tenant access | `--tenant-id <GUID>` optional (defaults to login tenant) |
-| `Folder` | Folder-scoped access | `--scope Folder --folder-id <FOLDER_ID>`. `--tenant-id` becomes the owning tenant ParentId (defaults to login tenant) |
+`--folder-id` replaces the older `--scope-id` / `--parent-folder-id` pair. For Folder scope, `--folder-id` is the folder’s `Id` and `--tenant-id` is its owning tenant’s `ParentId`. Do not use `Organization` or `Project` scope.
 
-> **No `Organization` / `Project` scope on `check-access`.** The PDP doesn't expose those directly. To approximate:
-> - **Org-wide entitlement check** — loop `check-access <USER> --tenant-id <TID>` over every tenant (`tenants list`), then aggregate `grantedRolesMetadata` per service.
-> - **Project-level access** — use `--scope Folder` with the project's owning folder, or filter the default `Tenant` result to the service that owns the project (`--service documentunderstanding` etc.).
+For org-wide entitlement, run `check-access <USER> --tenant-id <TID>` for every tenant from `tenants list` and aggregate `grantedRolesMetadata` per service. For project-level access, use `--scope Folder` with the owning folder, or filter the default `Tenant` result to the owning service with `--service documentunderstanding` (or the relevant service).
 
-> `--folder-id` replaces the older `--scope-id` / `--parent-folder-id` pair. For Folder scope, `--folder-id` is the Folder's `Id` and `--tenant-id` is the owning tenant's `ParentId`.
+## Workflows
 
-## Workflow: Check a User's Effective Access at the Login Tenant
+Run the following for login-tenant access; the default scope is `Tenant` and the default tenant is the login tenant:
 
 ```bash
 uip admin authorization check-access <USER_GUID> --output json
 ```
 
-Default scope is `Tenant`, default tenant is the login tenant.
-
-## Workflow: Check Across Tenants
+Run the following for another tenant:
 
 ```bash
 uip admin authorization check-access <USER_GUID> --tenant-id <OTHER_TENANT_ID> --output json
 ```
 
-## Workflow: Restrict to One Service
-
-Especially useful for services that manage their own roles, where the PAP catalog may not reflect server-side rules:
+Run the following to restrict evaluation to one service, especially when server-side service roles may not appear in the PAP catalog:
 
 ```bash
 uip admin authorization check-access <USER_GUID> --service orchestrator --output json
 ```
 
-Known service names: `apps, authz, automationops, casemanagement, dataservice, documentunderstanding, identity, insights, licensing, oms, orchestrator, platform, processmining, reinfer, studio, taskmining, testmanager`. Other names are accepted free-form (passed through verbatim as `ServiceName`).
+Use these known service names: `apps, authz, automationops, casemanagement, dataservice, documentunderstanding, identity, insights, licensing, oms, orchestrator, platform, processmining, reinfer, studio, taskmining, testmanager`. Other names are accepted free-form and passed verbatim as `ServiceName`.
 
-> **`--service centralizedaccess` is not in the list.** `check-access` does pass arbitrary `--service` values through verbatim, but the PDP has no separate "centralizedaccess" service to score — querying it returns no useful access info. For the multi-service / Centralized Access view, omit `--service` and let the default Tenant evaluation return every role the principal holds across services.
+Do not use `--service centralizedaccess`: although arbitrary values pass through, the PDP has no separate `centralizedaccess` service and returns no useful access information. Omit `--service` for the multi-service / Centralized Access view.
 
-## Workflow: Folder Scope
+Run the following for Folder scope:
 
 ```bash
 uip admin authorization check-access <USER_GUID> \
@@ -108,11 +84,11 @@ uip admin authorization check-access <USER_GUID> \
   --output json
 ```
 
-`--tenant-id` defaults to the login tenant for the ParentId; override only when targeting a folder in a different tenant.
+`--tenant-id` defaults to the login tenant’s `ParentId`; override it only for a folder in another tenant.
 
-## Workflow: Advanced — File-Based Request
+## File-Based Request
 
-Use `--file <PATH>` for filters not exposed inline (e.g. `RoleNameStartsWith`). With `--file`, omit the positional identity and the inline scope flags — they're set in the body.
+Run `--file <PATH>` when using filters not exposed inline, such as `RoleNameStartsWith`. Omit the positional identity and inline scope flags; put them in the body.
 
 `check-access.json`:
 
@@ -128,7 +104,7 @@ Use `--file <PATH>` for filters not exposed inline (e.g. `RoleNameStartsWith`).
 }
 ```
 
-For Folder scope, `Value.Id` is the folder UUID and `Value.ParentId` is the owning tenant UUID.
+For Folder scope, `Value.Id` is the folder UUID and `Value.ParentId` is the owning tenant UUID. Run:
 
 ```bash
 uip admin authorization check-access --file ./check-access.json --output json
@@ -136,4 +112,4 @@ uip admin authorization check-access --file ./check-access.json --output json
 
 ## Resolving Principal IDs
 
-If you only have a UUID and want to verify the identity exists first, or if you need IDs for non-User principals, see [role-assignment-management.md — Resolving Principal IDs](role-assignment-management.md#resolving-principal-ids).
+To verify a UUID or obtain IDs for non-User principals, see [role-assignment-management.md — Resolving Principal IDs](role-assignment-management.md#resolve-principals-before-mutation).

package/skills/uipath-admin/references/authorization/grant-permissions.md

@@ -1,44 +1,40 @@
 # Grant Permission(s) to a Principal
 
-Workflow for the ad-hoc **"grant me X"** / **"give <PRINCIPAL> permissions Y, Z"** request — a shortcut over the full Create-Role + Create-Assignment pair, optimized for the common case where the user names *permissions*, not a role shape.
+Workflow for ad-hoc **"grant me X"** / **"give <PRINCIPAL> permissions Y, Z"** requests: a shortcut over Create-Role + Create-Assignment when the user names permissions rather than a role shape.
 
 For per-command flag tables and output codes, see [authorization-commands.md](authorization-commands.md). For shared role-shape concepts (Centralized Access, service-inference rules, scope modes), see [role-management.md](role-management.md).
 
 ## When to Use This Workflow
 
-The user names **one or more permissions** without naming a role or a scope. Examples:
+Use when the user names permissions without naming a role or scope, such as *"grant me DOCUMENTUNDERSTANDING.PROJECTS.READ"*, *"give alice DU projects read and update"*, or *"what's the minimal grant for licensing reads?"* If the user names a role shape first, use [role-management.md — Workflow: Create a Custom Role](role-management.md#workflow-create-a-custom-role); its Step 1a-1d substeps cover the role-first path.
 
-- *"grant me DOCUMENTUNDERSTANDING.PROJECTS.READ"*
-- *"give alice DU projects read and update"*
-- *"what's the minimal grant for licensing reads?"*
-
-If the user names a **role shape first** (e.g., *"create a tenant role for DU"*, *"make a custom role with DU permissions"*), use [role-management.md — Workflow: Create a Custom Role](role-management.md#workflow-create-a-custom-role) instead — those Step 1a-1d substeps cover the role-first entry path.
-
-> **Sibling workflow.** [Step 1b of Workflow: Create a Custom Role](role-management.md#step-1b--hoist-check-prefer-the-umbrella-when-permissions-overlap) is the binary (service vs. umbrella) form of the same scope-selection problem this workflow solves with a full N-scope intersection (Steps G2-G3). Keep them in sync if either changes.
-
-> **Never skip the scope menu.** The same permission name (e.g., `DOCUMENTUNDERSTANDING.PROJECTS.UPDATE`) almost always appears in *both* the service catalog *and* the Tenant / TenantGlobal umbrella catalogs. Defaulting to `--service <svc>` silently locks the role to one service and loses the multi-service reuse the umbrella offers. Always probe every applicable scope and let the user pick.
+> **Sibling workflow.** [Step 1b of Workflow: Create a Custom Role](role-management.md#step-1b--hoist-overlapping-permissions-to-the-umbrella) is the binary service-versus-umbrella form of the scope-selection problem solved here with a full N-scope intersection (Steps G2-G3). Keep them synchronized.
+>
+> **Never skip the scope menu.** A permission may appear in both service and Tenant / TenantGlobal umbrella catalogs. Do not default to `--service <svc>`; probe every applicable scope and let the user choose.
 
 ## Step G1 — Identify the permission(s)
 
-Resolve the user's wording to one or more concrete permission `name` values (e.g., "DU projects update" → `DOCUMENTUNDERSTANDING.PROJECTS.UPDATE`; "DU projects read and update" → `[…PROJECTS.READ, …PROJECTS.UPDATE]`). If any token is ambiguous (no exact match), grep the catalog:
+Resolve the wording to exact permission `name` values. If any token is ambiguous or has no exact match, run:
 
 ```bash
 uip admin authorization permissions list --output json \
   --output-filter "Data[?contains(name, '<TOKEN>')].{name:name,resourceType:resourceType,scopeType:scopeType}"
 ```
 
-If multiple candidates remain for any token, render a numbered Markdown menu and stop until disambiguated. End of this step: a confirmed list of one or more permission `name` strings.
+If multiple candidates remain for any token, render a numbered Markdown menu and stop until the user disambiguates. End with one or more confirmed permission `name` strings.
 
 ## Step G2 — Probe which scopes admit each permission
 
-Always run the Tenant and TenantGlobal probes; gate the other two on the permission set. The CLI tells you which scopes each permission is valid in:
+Run the Tenant and TenantGlobal probes always; run the other probes conditionally:
 
 | Probe | Run when |
 |---|---|
 | `permissions list --scope Tenant` | Always |
 | `permissions list --scope TenantGlobal` | Always |
-| `permissions list --service <SERVICE>` | Every selected permission shares the same service prefix (one probe per distinct prefix) |
-| `permissions list --scope Organization` | Any selected permission has an org-scope service prefix (e.g., `APPS.*`, `IDENTITY.*`) |
+| `permissions list --service <SERVICE>` | Every selected permission shares one service prefix; run one per distinct prefix |
+| `permissions list --scope Organization` | Any selected permission has an org-scope service prefix, such as `APPS.*` or `IDENTITY.*` |
+
+Run:
 
 ```bash
 uip admin authorization permissions list --scope Tenant --output json > tenant.json
@@ -47,44 +43,37 @@ uip admin authorization permissions list --service <SERVICE> --output json > svc
 uip admin authorization permissions list --scope Organization --output json > org.json            # conditional
 ```
 
-Membership rule: a permission is "valid in scope X" iff its `name` appears in the catalog returned for that scope. Many tenant-services share the same catalog between `--scope Tenant` and `--scope TenantGlobal` — treat them as two distinct menu options.
-
-## Step G2.5 — Compute the intersection of valid scopes/services across all selected permissions
-
-A role can hold a permission only if **every** permission in the set is valid at that role shape. Build the intersection across **five** candidate shapes — four umbrella scopes (Tenant, TenantGlobal, Organization, Project) **plus** the Service shape (`--service <SERVICE>`, scope inferred). The Service shape is always a row in the matrix when every selected permission shares one service prefix — never drop it silently just because an umbrella also admits the perm.
+A permission is valid in scope X iff its `name` appears in that scope's catalog. Treat Tenant and TenantGlobal as distinct menu options even when their catalogs match.
 
-1. For each candidate permission, record the set of shapes where it appears: e.g., `DOCUMENTUNDERSTANDING.PROJECTS.UPDATE = {Tenant, TenantGlobal, Service:documentunderstanding}`.
-2. **Intersect** the shape-sets across all candidates. The result is the set of role shapes the role can take.
+## Step G2.5 — Compute the intersection of valid scopes/services
 
-Branch on the intersection:
+Build each permission's shape-set and intersect the five candidate shapes: Tenant, TenantGlobal, Organization, Project, and Service (`--service <SERVICE>`, scope inferred). Include Service whenever all selected permissions share one service prefix, even if an umbrella also admits them. Record shapes such as `{Tenant, TenantGlobal, Service:documentunderstanding}`; the intersection is the permissible role-shape set.
 
 | Intersection | Action |
-|--------------|--------|
-| **Empty** (no shape holds all candidates) | The permissions cannot live on one role. Surface the per-permission scope matrix to the user and offer: (a) split into multiple roles by scope group, (b) drop the outliers, (c) reconsider the set. Do not silently downshift to a single role that omits permissions. |
-| **One shape** | Skip the menu — proceed to Step G4 with that shape. State the resolution in the summary. |
+|---|---|
+| **Empty** | Show the per-permission scope matrix and offer (a) split into multiple roles by scope group, (b) drop outliers, or (c) reconsider the set. Never silently omit permissions or downshift to one incomplete role. |
+| **One shape** | Skip the menu, proceed to Step G4, and state the resolved shape. |
 | **≥2 shapes** | Render the matrix and menu in Step G3. |
 
-> **Project-scope-only permissions** (e.g., `DOCUMENTUNDERSTANDING.DOCUMENTTYPE.*`) have **no umbrella** — they appear *only* in `permissions list --scope Project --service <svc>`. If every candidate is Project-scope and they share the same service, the intersection is `{Project:<service>}`; skip the menu and use `--scope Project --service <svc>`. If the set mixes Project with Tenant/Org, the intersection is empty — apply the split rule above.
-
-## Step G3 — Render the intersection matrix and scope menu (Tenant Recommended when present)
+**Project-scope-only permissions** (for example, `DOCUMENTUNDERSTANDING.DOCUMENTTYPE.*`) have no umbrella and appear only in `permissions list --scope Project --service <svc>`. If all candidates are Project-scope and share a service, the intersection is `{Project:<service>}`; skip the menu and use `--scope Project --service <svc>`. If Project is mixed with Tenant or Organization, the intersection is empty and the split rule applies.
 
-When the intersection has ≥2 shapes, render **two artifacts**: a presence matrix (so the user sees why each option is offered) followed by a numbered menu (so the user replies with a digit). Mark **Tenant** as Recommended when present. Show only shapes that survived the intersection — never list an option the role can't take.
+## Step G3 — Render the intersection matrix and scope menu
 
-**Decide which rows to render before drafting either artifact:**
+When the intersection has ≥2 shapes, render the presence matrix first, then a numbered menu. Show only intersection survivors; never offer an invalid shape. Mark Tenant **Recommended** when present. Decide rows as follows:
 
 | Row in `Scope/Service` column | Owning service for the created role | Render when |
 |---|---|---|
-| Tenant | `CentralizedAccess` | Intersection includes `Tenant`. Mark **Recommended**. |
-| TenantGlobal | `CentralizedAccess` | Intersection includes `TenantGlobal`. |
-| Organization | `CentralizedAccess` | Intersection includes `Organization` (i.e., every selected permission has an org-scope service prefix). |
-| Service | `<SERVICE>` (e.g., `DocumentUnderstanding`) | Intersection includes the service catalog AND every selected permission shares one service prefix. Omit when permissions span multiple services or are cross-cutting (e.g., `AUTHZ.*`). |
-| Project | `<SERVICE>` | Intersection is `{Project:<service>}` only — handled by the project-only branch in Step G2.5; usually not shown alongside umbrella rows. |
+| Tenant | `CentralizedAccess` | Intersection includes `Tenant`; mark **Recommended** |
+| TenantGlobal | `CentralizedAccess` | Intersection includes `TenantGlobal` |
+| Organization | `CentralizedAccess` | Intersection includes `Organization`, meaning every selected permission has an org-scope service prefix |
+| Service | `<SERVICE>` (for example, `DocumentUnderstanding`) | Intersection includes the service catalog and every selected permission shares one service prefix; omit for multi-service or cross-cutting permissions such as `AUTHZ.*` |
+| Project | `<SERVICE>` | Intersection is `{Project:<service>}` only; normally handled by the Project-only branch in Step G2.5 rather than shown with umbrella rows |
 
-> **Owning Service** is the value `roles get` will return as `ownerServiceName` after creation — umbrella scopes (no `--service`) resolve to `CentralizedAccess`; a service-shape role resolves to the named service. See [role-management.md — Step 6](role-management.md#step-6--summarize-highlight-the-resolved-service).
+**Owning Service** is the `ownerServiceName` returned by `roles get`: umbrella scopes without `--service` resolve to `CentralizedAccess`; service-shape roles resolve to the named service. See [role-management.md — Step 6](role-management.md#step-6--summarize-the-resolved-service).
 
-**Artifact 1 — Intersection matrix.** First column is `Scope/Service`; second column is `Owning Service`; third column is presence (✅ for shapes in the intersection, ❌ for shapes that were probed but excluded). Always include the **Service** row when every selected permission shares one service prefix — its absence was the gap that motivated this column layout. Example for `DOCUMENTUNDERSTANDING.PROJECTS.UPDATE` (single perm, single service):
+**Artifact 1 — Intersection matrix.** Use columns `Scope/Service`, `Owning Service`, and `Perm present?`; use ✅ for intersection shapes and ❌ for probed but excluded shapes. Always include the Service row when all selected permissions share one service prefix:
 
-```
+```markdown
 | Scope/Service | Owning Service        | Perm present? |
 |---------------|-----------------------|---------------|
 | Tenant        | CentralizedAccess     | ✅            |
@@ -94,9 +83,9 @@ When the intersection has ≥2 shapes, render **two artifacts**: a presence matr
 | Project       | DocumentUnderstanding | ❌            |
 ```
 
-**Artifact 2 — Numbered menu** built from the ✅ rows above, renumbered from `1`:
+**Artifact 2 — Numbered menu.** Build it from the ✅ rows and renumber from `1`. Identify the permission(s), explain that they are valid in multiple role shapes, state each shape's binding, owning service, and create flags, and end with “Reply with the digit of your choice.” Use this structure:
 
-```
+```markdown
 `<PERMISSION_NAME_1>` (+ N more) are valid in multiple role shapes. Pick:
 
 1. **Tenant** (Recommended) — multi-service role bound to one tenant. Owning service: `CentralizedAccess`. Built with `--scope Tenant` and no `--service`. Reusable across every tenant-service in this tenant.
@@ -107,26 +96,26 @@ When the intersection has ≥2 shapes, render **two artifacts**: a presence matr
 Reply with the digit of your choice.
 ```
 
-**Why Tenant is the default recommendation:** the Tenant-shape role can bundle additional tenant-scope permissions from any other service later (`LICENSING.*`, `IDENTITY.*`, etc.) without re-authoring; the service-shape role cannot. The Service option is still listed (with its `Owning Service` made explicit) so the user can deliberately pick strict service isolation when that's what they want.
+Recommend Tenant because it can later bundle tenant-scope permissions from other services (`LICENSING.*`, `IDENTITY.*`, etc.) without re-authoring; still list Service for deliberate isolation.
 
 ## Step G4 — Map the pick to the create-call shape
 
 | Pick | `roles create` flags |
-|------|----------------------|
+|---|---|
 | Tenant | `--scope Tenant` (no `--service`; `--tenant-id` defaults to login) |
 | TenantGlobal | `--scope TenantGlobal` (no `--service`) |
 | Organization | `--scope Organization` (no `--service`) |
 | Service | `--service <SERVICE>` (no `--scope`; registry infers) |
 | Project | `--scope Project --service <SERVICE>` |
 
-Author `actions.json` as a JSON array containing **every** permission `name` confirmed in Step G1 — not just one. Then run [Steps 2-5 of Workflow: Create a Custom Role](role-management.md#step-2--suggest-a-role-name) (name suggestion, action-file authoring, create, verify). After the role exists, run [Workflow: Create a Single Assignment](role-assignment-management.md#workflow-create-a-single-assignment) — including the [Echo-before-mutate protocol](role-assignment-management.md#echo-before-mutate-protocol) for the principal.
+Author `actions.json` as a JSON array containing **every** permission `name` confirmed in Step G1. Then run [Steps 2-5 of Workflow: Create a Custom Role](role-management.md#step-2--suggest-a-role-name): name suggestion, action-file authoring, create, and verify. After the role exists, run [Workflow: Create a Single Assignment](role-assignment-management.md#create-one-assignment), including the [Echo-before-mutate protocol](role-assignment-management.md#echo-before-mutate-protocol) for the principal.
 
 ## Step G5 — Summarize: state the resolved scope, service, and full permission list
 
 In the post-create / post-assign summary, include:
 
-- The scope path the assignment landed on.
-- The resolved `--service` value (or "no `--service` — multi-service <scope> role" when omitted).
-- The **full list of permissions** in the role — not just the one the user named first. This matters when the role bundles several permissions; silently omitting some from the summary hides the actual grant scope.
+- The scope path where the assignment landed.
+- The resolved `--service` value, or “no `--service` — multi-service <scope> role” when omitted.
+- The **full list of permissions** in the role, not only the first named permission.
 
-Same rule as [Step 6 of Workflow: Create a Custom Role](role-management.md#step-6--summarize-highlight-the-resolved-service).
+Apply the same rule as [Step 6 of Workflow: Create a Custom Role](role-management.md#step-6--summarize-the-resolved-service).

package/skills/uipath-admin/references/authorization/permission-catalog.md

@@ -4,36 +4,34 @@ Conceptual guide for the read-only catalog at `uip admin authorization permissio
 
 ## Concept
 
-The catalog is the master list of permission definitions across all services. Permissions are referenced **by `name`** (the dotted string, e.g. `STUDIO.X.Y`) when authoring custom roles — see [role-management.md — Workflow: Create a Custom Role](role-management.md#workflow-create-a-custom-role).
-
-Each permission record:
+The catalog is the master list of permission definitions. Custom roles reference permissions by `name` (the dotted string, such as `STUDIO.X.Y`); see [role-management.md — Workflow: Create a Custom Role](role-management.md#workflow-create-a-custom-role).
 
 | Field | Example | Used for |
 |-------|---------|----------|
-| `id` | UUID | Internal — not required for role authoring |
-| `name` | `IDENTITY.GROUP.UPDATE` | **What goes into `roles create --file ./actions.json`** |
+| `id` | UUID | Internal; not required for role authoring |
+| `name` | `IDENTITY.GROUP.UPDATE` | **Value in `roles create --file ./actions.json`** |
 | `namespace` | `IDENTITY` | Grouping / display |
 | `serviceDisplayName` | `Identity Service` | Grouping / display |
 | `resourceType` | `Group` | Grouping / display |
 | `resourceAction` | `Update` | Grouping / display |
 | `resourceGroup` | `Identity` | Grouping / display |
-| `scopeType` | `ORGANIZATION` / `TENANT` / `PROJECT` / `ANY` | Determines which role-scope mode the permission belongs in |
+| `scopeType` | `ORGANIZATION` / `TENANT` / `PROJECT` / `ANY` | Determines the role-scope mode |
 
 > The `--file` payload for `roles create`/`roles update` is a **JSON array of permission `name` strings**, not UUIDs. The CLI resolves names to ids server-side.
 
 ## Scope Behavior
 
-Each service registers its permissions at a specific scope. Examples:
+Each service registers permissions at a specific scope:
 
-- Studio permissions register at `Tenant` (per the service registry — `--service studio` infers `Tenant`).
-- Apps permissions register at `Organization`.
-- Document Understanding registers Project-shape permissions (queryable with `--scope Project --service documentunderstanding`).
+- Studio registers at `Tenant`; `--service studio` therefore infers `Tenant`.
+- Apps registers at `Organization`.
+- Document Understanding registers Project-shape permissions; query them with `--scope Project --service documentunderstanding`.
 
-Passing `--scope <TYPE>` may surface or hide service-specific entries depending on where the service registered.
+`--scope <TYPE>` may surface or hide entries according to service registration.
 
 ## `--service` Infers Scope
 
-When you call `permissions list` with `--service <NAME>` and **no `--scope`**, the CLI consults the service registry and applies the inferred scope automatically. To override, pass both `--service` and `--scope` explicitly (used by Project-shape services like Document Understanding and Reinfer).
+With `--service <NAME>` and no `--scope`, `permissions list` consults the service registry and applies the inferred scope. Override it by passing both flags, as required for Project-shape services such as Document Understanding and Reinfer.
 
 ```bash
 uip admin authorization permissions list --service studio --output json
@@ -42,9 +40,9 @@ uip admin authorization permissions list --service documentunderstanding --scope
 
 ### `--service` serviceNames and How to Re-Derive Them
 
-`--service <NAME>` is right when the caller names the service ("which permissions does Orchestrator contribute?"). It is wrong for locating a permission whose owning service you do not know — use [Find the Permission Governing an Action](#workflow-find-the-permission-governing-an-action) instead.
+Use `--service <NAME>` when the caller names the service. When the owning service is unknown, use [Find the Permission Governing an Action](#workflow-find-the-permission-governing-an-action).
 
-The value `--service` takes is a **`serviceName`** — the API filter this flag sets, equal to the catalog `Namespace` lowercased and to `lowercase(OwnerServiceName)` from `roles list`. All 22 (verified against `uip` 1.201.0):
+`--service` takes a **`serviceName`**: the API filter equal to catalog `Namespace` lowercased and to `lowercase(OwnerServiceName)` from `roles list`. All 22, verified against `uip` 1.201.0:
 
 ```
 apps  audit  authz  automationops  casemanagement  communicationsmining  cx
@@ -53,33 +51,33 @@ licensing  oms  orchestrator  platform  processmining  reinfer  relay  studio
 taskmining  testmanager
 ```
 
-`centralizedaccess` is the one namespace with **no** usable `serviceName`. `CENTRALIZEDACCESS` permissions (the platform Administration page) are reachable only via `--scope Tenant` or an unfiltered list.
+`centralizedaccess` is the only namespace without a usable `serviceName`. Reach `CENTRALIZEDACCESS` permissions, including the platform Administration page, only with `--scope Tenant` or an unfiltered list.
 
-Derive the `serviceName` from `Namespace` or `OwnerServiceName`, never from `ServiceDisplayName`: `reinfer` works and `ixp` does not (`REINFER` / `Reinfer` displays as "IXP"); `casemanagement` works and `maestro` does not (displays as "Maestro").
+Derive `serviceName` from `Namespace` or `OwnerServiceName`, never `ServiceDisplayName`: `reinfer` works and `ixp` does not (`REINFER` / `Reinfer` displays as “IXP”); `casemanagement` works and `maestro` does not (displays as “Maestro”).
 
 #### Re-derive the List When a `serviceName` Is Rejected
 
-Never guess a replacement `serviceName`, and never trust the `Known services:` roster printed by `check-access --help` — it is a stale 18-entry mirror that omits `audit`, `communicationsmining`, `cx`, `governedinference`, and `relay`. Ask the catalog:
+Never guess a replacement `serviceName`, and never trust the `Known services:` roster from `check-access --help`; it is a stale 18-entry mirror omitting `audit`, `communicationsmining`, `cx`, `governedinference`, and `relay`. Run the catalog query, choose a real `serviceName`, and retry the original command:
 
 ```bash
 uip admin authorization permissions list --output plain --output-filter "[].Namespace" \
   | tr '[:upper:]' '[:lower:]' | sort -u | grep -v '^centralizedaccess$'
 ```
 
-`--output plain` emits one bare value per line, so this needs no `jq` and the ~210 KB catalog never reaches the transcript. Run it, pick the real `serviceName`, retry the original command.
+`--output plain` emits one bare value per line, so no `jq` is needed and the approximately 210 KB catalog does not reach the transcript.
 
 ## Cross-Cutting `authz` Permissions
 
-`AUTHZ` holds 14 permissions: 10 at `ScopeType: ANY` — the only `ANY` rows in the whole catalog — plus 4 at `ORGANIZATION`. `ANY` matches every scope filter, so **every** `--service` slice returns those 10 alongside the service's own rows: `--service studio` yields `STUDIO` + `AUTHZ`, `--service identity` yields `IDENTITY` + `AUTHZ`. `--service authz` adds the 4 `ORGANIZATION` rows.
+`AUTHZ` has 14 permissions: 10 at `ScopeType: ANY`—the only `ANY` rows in the catalog—and 4 at `ORGANIZATION`. `ANY` matches every scope filter, so every `--service` slice includes those 10 alongside that service's rows: `--service studio` yields `STUDIO` + `AUTHZ`; `--service identity` yields `IDENTITY` + `AUTHZ`; `--service authz` adds the 4 `ORGANIZATION` rows.
 
-A slice is a **role-shape slice**, never a namespace filter, and never returns another namespace's rows. Two consequences:
+A slice is a **role-shape slice**, not a namespace filter, and never returns another namespace's rows:
 
-1. **A slice returning only those 10 `AUTHZ` rows means the `--service` / `--scope` pair matched nothing of that service** — e.g. `--service apps --scope Project`. That floor, not `Data: []`, is the "wrong slice" signal.
-2. **A valid `serviceName` at the wrong scope hides real permissions.** `--service documentunderstanding` returns 17 rows at its inferred `Tenant` scope; `--scope Project` returns 49. Never rule a permission out from one slice — drop `--service` and re-query.
+1. A slice containing only the 10 `AUTHZ` rows means the `--service` / `--scope` pair matched none of that service—for example, `--service apps --scope Project`. This floor, not `Data: []`, signals the wrong slice.
+2. A valid `serviceName` at the wrong scope hides real permissions. `--service documentunderstanding` returns 17 rows at its inferred `Tenant` scope and 49 at `--scope Project`. Never rule out a permission from one slice; remove `--service` and re-query.
 
 ## Workflow: Find the Permission Governing an Action
 
-Use this when diagnosing a 403 or mapping a UI surface ("the Administration page", "the Studio settings tab") to its permission name. Search the **whole** catalog — do not pre-filter by `--service`:
+Use this for a 403 or to map a UI surface, such as an Administration page or Studio settings tab, to its permission name. Search the **whole** catalog; do not pre-filter by `--service`. Run:
 
 ```bash
 uip admin authorization permissions list --output json \
@@ -94,29 +92,29 @@ uip admin authorization permissions list --output json \
 
 Rules:
 
-1. **When searching, always filter.** An unfiltered list is ~500 records / ~210 KB of JSON — past most agents' tool-output limit, so it truncates and the record you need can be present but unread. Never conclude "not found" from a truncated list. (Filtering is for *finding* one permission. When the goal is to hand over the whole catalog, or one named service's slice, list it unfiltered or with `--service` and save it complete — see [Find Permission Names for Role Authoring](#workflow-find-permission-names-for-role-authoring).)
-2. **`--output-filter` JMESPath `contains` is case-sensitive.** `Name` is UPPERCASE; `Description`, `ResourceType`, and `ResourceGroup` are sentence/Pascal case. `contains(Description, 'Administration')` returns `[]` while `contains(Description, 'administration')` matches.
-3. Search `Name` on an UPPERCASE keyword first, then widen to `Description` in lowercase:
+1. **Always filter when searching.** An unfiltered list is approximately 500 records / 210 KB of JSON and may exceed tool-output limits, so truncation can hide the needed record. Never conclude “not found” from truncated output. For handing over the whole catalog or a named service's complete slice, list unfiltered or with `--service` and save it complete; see [Find Permission Names for Role Authoring](#workflow-find-permission-names-for-role-authoring).
+2. **`--output-filter` JMESPath `contains` is case-sensitive.** `Name` is UPPERCASE; `Description`, `ResourceType`, and `ResourceGroup` use sentence/Pascal case. `contains(Description, 'Administration')` returns `[]`; `contains(Description, 'administration')` matches.
+3. Search `Name` with an UPPERCASE keyword first, then widen to lowercase `Description`. Run:
    ```bash
    uip admin authorization permissions list --output json \
      --output-filter "[?contains(Name, 'ADMIN') || contains(Description, 'admin')]"
    ```
-4. Narrow by role shape with `--scope`, never a guessed `--service`. Scope matters: `--scope Tenant` surfaces the Administration page permission, `--scope Organization` does not — so try the unfiltered catalog before ruling a permission out.
-5. Read `ScopeType` off the hit — it dictates the role scope needed to grant it (`TENANT` → a `Tenant`- or `TenantGlobal`-shape role). See [role-management.md](role-management.md).
+4. Narrow by role shape with `--scope`, never with a guessed `--service`. Scope matters: `--scope Tenant` surfaces the Administration page permission, while `--scope Organization` does not. Try the unfiltered catalog before ruling out a permission.
+5. Read `ScopeType` from the hit; it determines the role scope needed to grant it (`TENANT` → a `Tenant`- or `TenantGlobal`-shape role). See [role-management.md](role-management.md).
 
 ## Workflow: Find Permission Names for Role Authoring
 
-To build a custom role's actions file:
+To build a custom role actions file:
 
-1. List candidate permissions for the target service:
+1. List candidate permissions for the target service. Run:
    ```bash
    uip admin authorization permissions list --service <SERVICE> --output json
    ```
-2. Extract `name` values for the actions the role should grant (e.g. `STUDIO.X.Y`, `IDENTITY.GROUP.READ`).
-3. Write them to `actions.json` as a flat string array:
+2. Extract `name` values for the actions the role should grant, such as `STUDIO.X.Y` or `IDENTITY.GROUP.READ`.
+3. Write a flat string array to `actions.json`:
    ```json
    ["STUDIO.X.Y", "STUDIO.A.B", "IDENTITY.GROUP.READ"]
    ```
-4. Pass via `--file ./actions.json` to `roles create` or `roles update`. See [role-management.md](role-management.md).
+4. Pass it with `--file ./actions.json` to `roles create` or `roles update`. See [role-management.md](role-management.md).
 
-When the user is selecting permissions interactively, present them as a **single numbered table grouped by `serviceDisplayName`** with columns `# | Service | Permission | Scope | Description` — see [role-management.md — Step 3](role-management.md#step-3--present-permissions-as-a-numbered-menu). Map the user's picked numbers to permission `name` strings internally; never ask the user to copy UUIDs.
+For interactive selection, present one numbered table grouped by `serviceDisplayName`, with columns `# | Service | Permission | Scope | Description`; see [role-management.md — Step 3](role-management.md#step-3--present-a-numbered-permission-menu). Map selected numbers to permission `name` strings internally; never ask the user to copy UUIDs.