@uipath/skills 1.195.0

package/skills/uipath-governance/references/access-policy/resource-lookup-guide.md

@@ -0,0 +1,289 @@
+# Resource Lookup Guide
+
+How to resolve human-readable process / folder / user names into the UUIDs the access-policy JSON requires. Run these when the user says things like "the Invoice Agent", "the Production Flow in Shared", or "the build-bot service account" without supplying a UUID — never guess a UUID, and never ask the user to leave the chat to find one unless the lookup returns no match.
+
+> For full option details on any command, use `--help` (e.g., `uip or processes list --help`).
+
+> **When to use this guide**
+>
+> - Phase 1 ([planning-arch.md](./planning-arch.md)) — the **Resources** / **Actor Process** / **Actor Identity** summary references a specific named entity but the user did not supply its UUID.
+> - Phase 2 ([planning-impl.md](./planning-impl.md)) — composing a `selectors[].values`, `executableRule.values[].values`, or `actorRule.values[].values` array that needs specific UUIDs.
+> - Update flow, when the user wants to add a specific process or identity to an existing block.
+
+All commands assume the user is already logged in (`uip login status --output json`). Every command uses `--output json` so the agent can parse the result programmatically.
+
+---
+
+## Common flags (every `uip or ... list` command)
+
+> **Scope.** This flag table applies to the `uip or` commands documented below (§1 Processes, §2 Folders) only. The `uip admin` commands used in §3 (Users, Groups, Robots) and §4 (Resource Catalog tags) follow the `uip admin` flag conventions documented under [/uipath:uipath-admin — identity-commands.md](../../../uipath-admin/references/identity-commands.md) — notably, `uip admin groups list` should not pass `--organization` because it should use current login organization.
+
+`--output json`, `--limit`, `--offset`, `--sort-by`, and `--login-validity` are shared with `uip gov access-policy` — see [access-policy-commands.md § Common flags](./access-policy-commands.md#common-flags-shared-across-uip-list-commands) for the canonical descriptions. The `uip or`-only flags below extend that set:
+
+| Flag | Purpose |
+|------|---------|
+| `--output-filter <expr>` | JMESPath filter on the JSON response (e.g. `"Data[?contains(Name, 'Invoice')].Key"`). |
+| `--all-fields` | Returns the full DTO instead of the curated summary — use when you need a field not shown by default (e.g. confirming the exact `ProcessType` string). |
+| `--tenant <name>` | Override the tenant selected during `uip login`. Rarely needed. |
+
+> Default `--limit` for `uip or ... list` is 50 (max typically 1000); `uip gov access-policy list` defaults to 20.
+
+### Pagination
+
+List responses include a `Pagination` block with `Returned`, `Limit`, `Offset`, and `HasMore`. When `HasMore == true`, increment `--offset` by `--limit` and fetch again until `HasMore == false` or `Returned < Limit`. If the user's tenant has hundreds of processes, prefer a **server-side filter** (`--process-type`, `--name`) over paging through everything.
+
+---
+
+## 1. Processes (Resource or Actor Process UUIDs)
+
+`uip or processes list` returns Orchestrator processes filtered by folder and process type. The returned `Key` field is the UUID you paste into the policy JSON.
+
+### The two-step lookup — folders first, processes second
+
+**Processes are folder-scoped** — `uip or processes list` **requires** `--folder-path` (or `--folder-key`). If the user has not said which folder the process lives in, do NOT guess a folder name. Run folder discovery first, present the folder list, and ask the user to pick before searching for the process.
+
+```mermaid
+graph LR
+    A[uip or folders list] --> B{User picks folder}
+    B --> C[uip or processes list --folder-path &lt;PATH&gt; --process-type &lt;TYPE&gt; --name &lt;SUBSTR&gt;]
+    C --> D{User picks process}
+    D --> E[Key UUID → policy JSON]
+```
+
+**Step 1 — list folders.** See [§ 2 Folders](#2-folders) for the command and filter patterns. Grab `FullyQualifiedName` (e.g. `"Shared"`, `"Prod/Agents"`) for the next step.
+
+**Step 2 — list processes in that folder:**
+
+```bash
+uip or processes list \
+  --folder-path "<FOLDER_PATH>" \
+  --process-type "<ORCHESTRATOR_PROCESS_TYPE>" \
+  --name "<SUBSTRING>" \
+  --limit 50 \
+  --output json
+```
+
+| Flag | Required? | Purpose |
+|------|-----------|---------|
+| `--folder-path "<PATH>"` **or** `--folder-key "<UUID>"` | **Yes (one of)** | Mandatory. Processes are folder-scoped; the command fails without it. Use `FullyQualifiedName` from `uip or folders list` for `--folder-path`. |
+| `--process-type "<TYPE>"` | Recommended | Filters server-side by Orchestrator `ProcessType` — narrows to the right access-policy block (see mapping below). Note the Orchestrator value is **different** from the access-policy enum. |
+| `--name "<SUBSTRING>"` | Optional | Case-insensitive substring match on the process name. Use whenever the user named the process ("the Invoice agent" → `--name "Invoice"`). |
+
+### Access-policy type → Orchestrator `--process-type`
+
+The access-policy `resourceType` / `executableRule.values[].type` enums are **not the same strings** as Orchestrator's `ProcessType`. You must translate before passing `--process-type`. The table below is the authoritative mapping (confirmed against the `ProcessType` field returned by the Releases API):
+
+| Access-policy type | Orchestrator `--process-type` value | Block(s) | Notes |
+|--------------------|-------------------------------------|----------|-------|
+| `Agent` | `Agent` | Selection Rule, Actor Process Rule | Same string on both sides. |
+| `AgenticProcess` | `ProcessOrchestration` | Selection Rule, Actor Process Rule | **Rename** — Orchestrator calls maestro / agentic processes `ProcessOrchestration`. |
+| `RPAWorkflow` | `Process` | **Selection Rule only** — not valid as Actor Process | **Rename** — Orchestrator's legacy RPA process is just `Process`. |
+| `APIWorkflow` | `Api` | **Selection Rule only** — not valid as Actor Process | **Rename** — Orchestrator uses `Api`, not `ApiWorkflow`. |
+| `CaseManagement` | `CaseManagement` | Selection Rule, Actor Process Rule | **Unconfirmed** — likely same string but not verified against the Releases API. Re-run with `--all-fields` on first use to confirm, and update this row if it drifts. |
+| `Flow` | `Flow` | Selection Rule, Actor Process Rule | **Unconfirmed** — likely same string but not verified against the Releases API. Re-run with `--all-fields` on first use to confirm, and update this row if it drifts. |
+
+> **Verify if in doubt.** If a lookup returns zero rows for a `--process-type` value and the user is sure the process exists, re-run with `--all-fields` (and drop `--process-type`), then inspect the `ProcessType` string in the response to confirm the exact enum the tenant uses. Fix the mapping row here if you find a drift.
+
+### Response shape (default)
+
+```json
+{
+  "Code": "ProcessList",
+  "Data": [
+    {
+      "Key": "c3d4e5f6-0000-0000-0000-000000000001",
+      "Name": "InvoiceProcessing",
+      "ProcessKey": "InvoiceProcessing",
+      "ProcessVersion": "1.0.2",
+      "Description": "",
+      "IsLatestVersion": true
+    }
+  ]
+}
+```
+
+- `Key` — the **process UUID** to paste into the policy JSON. Use it as `selectors[].values[i]` when this process is the Resource being protected, or as `executableRule.values[j].values[i]` when this process is the Actor Process. This is the API-expected identifier — **not** the folder UUID, **not** `ProcessKey` (which is a dotted string identifier, not a UUID), and **not** `ProcessVersion`.
+- `Name` — the human-readable name. Present this to the user when asking them to confirm a match.
+- `ProcessKey` / `ProcessVersion` — informational only. The access-policy API does not accept these in `values`.
+
+> **"Process" vs "Release".** The CLI says "process"; the Orchestrator REST API calls it a "Release". Same entity. `Key` from `processes list` equals the `Key` from `/odata/Releases` — both are valid process UUIDs to paste into the policy.
+
+### Presenting matches to the user
+
+When multiple candidates come back, show them as a compact table and ask the user to pick. **Never silently pick the first row.**
+
+```text
+Found 3 processes matching "Invoice" in folder "Shared":
+
+  #  Name                          Version   Key (UUID)
+  1  InvoiceProcessing             1.0.2     c3d4e5f6-0000-...-0001
+  2  InvoiceProcessing-staging     1.0.1     c3d4e5f6-0000-...-0002
+  3  InvoiceApproval               0.9.0     c3d4e5f6-0000-...-0003
+
+Which one do you want to add to the policy? (1 / 2 / 3 / none)
+```
+
+If no matches, report the miss plainly and offer to broaden the search (drop `--name`, switch folder, drop `--process-type`) before giving up.
+
+### Get a single process by UUID
+
+Use this to confirm a UUID the user already supplied (e.g. from a previous policy or an Orchestrator URL):
+
+```bash
+uip or processes get "<PROCESS_UUID>" --output json
+```
+
+No folder context required — the UUID is globally unique.
+
+---
+
+## 2. Folders
+
+Folders are **tenant-scoped**. Run this first when the user names a folder ("the Shared folder", "Prod/Agents") without giving the exact path, or when `processes list` fails with a folder-not-found error.
+
+```bash
+uip or folders list --output json
+```
+
+Parse `.Data[]` for `FullyQualifiedName` (e.g. `"Shared"`, `"Prod/Agents"`) and `Key` (the UUID). Either value works as `--folder-path` / `--folder-key` on subsequent calls. Prefer `--folder-path` in chat transcripts — it is human-readable.
+
+Filter client-side with `--output-filter` when the tenant has many folders:
+
+```bash
+uip or folders list \
+  --output json \
+  --output-filter "Data[?contains(FullyQualifiedName, 'Prod')]"
+```
+
+---
+
+## 3. Users (Actor Identity UUIDs)
+
+For the `actorRule.values[].type: "User"` entry, resolve user names / emails to UUIDs with `uip admin users list` (Identity Server — see [/uipath:uipath-admin — user-management.md](../../../uipath-admin/references/user-management.md)):
+
+```bash
+uip admin users list --search "<NAME_OR_EMAIL>" --output json
+```
+
+`--search` matches both `userName` and `email` server-side. Response: `Data` is an array; each entry has camelCase fields `id` (UUID), `userName`, `email`, `name`, `surname`, `displayName`, `groupIds[]`. Take the matching record's `id` as the User UUID for `actorRule.values[]`.
+
+When you need to enumerate all users (no name yet), omit `--search` and page through with `--limit`/`--offset`.
+
+> **"Only me" intent.** `uip admin users` has no `current`/`me` subcommand. When the user says "only me" / "just my account", ask them to confirm their email or display name, then resolve via `uip admin users list --search "<EMAIL>" --output json`. Do not assume — different IdP profiles may share a name.
+
+### Robots resolve to `type: User`
+
+A robot is a kind of user in the UiPath identity model (Critical Rule #16). To use a robot in `actorRule`, the policy emits `type: "User"` with the robot's identity UUID, never `type: "Robot"`. Resolve via Identity Server's robot-accounts list:
+
+```bash
+uip admin robot-accounts list --search "<ROBOT_NAME>" --output json
+```
+
+Response: `Data` is an array; each entry has `id` (UUID), `name`, `displayName`, `creationTime`, `groupIds[]`. Take the matching record's `id` directly — it is the same UUID the access-policy server expects under `type: "User"`. **Emit `type: "User"`** in the policy JSON — see [plugins/actor/impl.md — Example E](./plugins/actor/impl.md#e-robot-only-trigger-resolves-to-user).
+
+If `uip admin robot-accounts list --search` returns nothing for the named robot, ask the user to confirm the robot name (or supply the UUID directly from the Admin portal). Never invent a UUID.
+
+### Groups (uip admin fallback)
+
+`Group` is supported in `actorRule.values[].type` but has no `uip or` wrapper today. Resolve via Identity Server instead:
+
+```bash
+uip admin groups list --output json
+```
+
+Response: `Data` is an array; each entry has `id` (UUID), `name`, `displayName`, `type` (numeric — `0` is custom, non-zero is built-in), `creationTime`. The command has **no `--search` flag** — filter client-side:
+
+```bash
+uip admin groups list \
+  --output json \
+  --output-filter "Data[?contains(displayName, 'Ops')]"
+```
+
+Take the matching record's `id` as the Group UUID for `actorRule.values[]`. See [/uipath:uipath-admin — group-management.md](../../../uipath-admin/references/group-management.md) for the broader group workflow. Only surface as an Open question on the Phase 1 Spec when the admin lookup returns nothing and the user cannot supply a GUID. Never fabricate.
+
+### ExternalApplication — not supported
+
+`ExternalApplication` is not a valid `actorRule.values[].type` today (Critical Rule #16). If the user names a service principal / S2S app / registered application, refuse and route them to one of these workarounds:
+- Use the `User` account that the application authenticates as.
+- Use a `Group` containing the application's identity.
+- Omit the Actor Identity rule entirely so the policy applies regardless of identity.
+
+---
+
+## 4. Resource Catalog tags
+
+Resource Catalog tags are tenant-scoped labels that feed `selectors[].tags.values[]` and `executableRule.tags.values[]` (see [plugins/tags/impl.md](./plugins/tags/impl.md)). A policy that references a tag name not present in the **policy's tenant** silently matches nothing at runtime — always verify before approving the Spec.
+
+### Default call
+
+```bash
+uip admin rcs tag list --output json
+```
+
+With no `--tenant`, the command targets the tenant in the current `uip login` context — and that is **also** the tenant the access policy will be authored in (the policy's `tenantId` is read from `~/.uipath/.auth`). This default is the only mode that proves a tag will resolve at evaluation time. Run it before approving any Spec or update that introduces a tag the user named; if the tag is missing from `Data.value[].displayName`, prompt the user to pick a returned tag, or to add the missing one to the Resource Catalog of the policy's tenant before retrying. Never invent a tag, and never silently substitute a near-match.
+
+| Flag | Required? | Purpose |
+|------|-----------|---------|
+| `--type Label\|KeyValue` | Optional | Defaults to `Label` (the type used by `tags.values[]` in `ToolUsePolicy` access policies). Pass `KeyValue` only when the user is asking about key/value tags, which the access-policy schema does **not** consume. |
+| `--starts-with <PREFIX>` | Optional | Server-side prefix filter (case-insensitive on `normalizedName`). Use whenever the user named a tag substring ("anything starting with prod"). |
+| `--limit <N>` | Optional | Page size (default `100`). |
+| `--offset <N>` | Optional | Row offset (default `0`). |
+| `--tenant <NAME>` | Optional | **Targets a different tenant in the same organization.** Do NOT pass this when verifying tags for the policy under construction — see [Tenant alignment](#tenant-alignment) below. |
+
+### Response shape
+
+```json
+{
+  "Code": "RcsTagList",
+  "Data": {
+    "count": 2,
+    "value": [
+      { "displayName": "Production", "normalizedName": "production" },
+      { "displayName": "Development", "normalizedName": "development" }
+    ]
+  }
+}
+```
+
+- `displayName` — the value to paste into `tags.values[]` in the policy JSON. The existing skill examples (e.g. `Production`, `Development`, `PII`) all use this form verbatim.
+- `normalizedName` — informational; what `--starts-with` matches against. Do not put this into the policy JSON.
+
+### Tenant alignment
+
+The access-policy `tenantId` is read from `~/.uipath/.auth` (`UIPATH_TENANT_ID`) and pinned at `create` time — the policy can only ever resolve tags from **that** tenant at evaluation.
+
+- **Default (no `--tenant`)** — verify tags for the in-flight policy. Use this for every Phase 1 / Phase 2 confirmation prompt.
+- **`--tenant <OTHER_NAME>`** — comparison only (e.g. "do these tag names also exist in our staging tenant?"). Never use a result from another tenant as evidence that a tag will work in the policy's tenant. If the user explicitly asks to check a different tenant, run the call but surface a one-line warning: `Tags from <OTHER_NAME> do not affect a policy authored in <POLICY_TENANT>; copy the tag in the Resource Catalog of <POLICY_TENANT> if it is missing there.`
+
+To recover the policy's tenant name (for the warning above) without echoing the bearer token:
+
+```bash
+grep "^UIPATH_TENANT_NAME=" ~/.uipath/.auth | cut -d= -f2
+```
+
+---
+
+## 5. When the lookup still cannot resolve the name
+
+1. **Surface the miss** — tell the user exactly which query you ran and what came back empty. Include the folder, `--process-type`, and `--name` values you used.
+2. **Suggest broadening the search** — drop `--process-type`, drop `--name`, try a parent folder.
+3. **Never fabricate a UUID.** If the lookup fails and the user cannot supply one, pause the flow and treat the missing UUID as a blocking **Open question** on the Phase 1 Spec (see [planning-arch.md](./planning-arch.md) — Open questions).
+
+---
+
+## 6. Recap — one command per lookup type
+
+> Processes are folder-scoped — always run [§ 2 Folders](#2-folders) first if you do not know the folder path. Translate the access-policy type to the Orchestrator `--process-type` using the [mapping table above](#access-policy-type--orchestrator---process-type) before calling `processes list`.
+
+| I need to find... | Command |
+|-------------------|---------|
+| A folder path / UUID by display name | `uip or folders list --output json` → filter on `FullyQualifiedName` |
+| A process / agent / flow / case-management UUID by name | `uip or processes list --folder-path "<PATH>" --process-type "<ORCHESTRATOR_TYPE>" --name "<SUBSTR>" --output json` — paste the response's `Key` into `values[]`. Do not use `ProcessKey` (dotted string), `ProcessVersion`, or the folder UUID. |
+| All processes of a given access-policy type in a folder | `uip or processes list --folder-path "<PATH>" --process-type "<ORCHESTRATOR_TYPE>" --output json` — paste each row's `Key` into `values[]`. |
+| Details on a specific process UUID | `uip or processes get "<UUID>" --output json` |
+| A user UUID by username / email | `uip admin users list --search "<TERM>" --output json` — paste the matched row's `id` into `actorRule.values[]`. |
+| The currently authenticated user's UUID | Ask the user to confirm their email / display name (no `current` subcommand on `uip admin`), then `uip admin users list --search "<TERM>" --output json`. |
+| A Resource Catalog tag name (for `tags.values[]`) | `uip admin rcs tag list --output json` — paste each row's `displayName` into `tags.values[]`. Do NOT pass `--tenant` when verifying tags for the policy under construction (see [§ 4 Tenant alignment](#tenant-alignment)). |
+| A robot's identity UUID (for `actorRule`, `type: "User"`) | `uip admin robot-accounts list --search "<NAME>" --output json` — paste the matched row's `id` into `actorRule.values[]`. Same UUID space as `uip admin users`; emit as `type: "User"`. |
+| A group UUID | `uip admin groups list --output json` — filter client-side on `displayName`; paste `id` into `actorRule.values[]` (see [§ 3 Groups](#groups-uip-admin-fallback)). Falls back to an Open question only if the lookup returns nothing. |
+| An external application UUID | **Not supported** by access policies today (Critical Rule #16) — route to a `User` or `Group` workaround |

package/skills/uipath-governance/references/access-policy/sample-policy-guide.md

@@ -0,0 +1,119 @@
+# Sample Access Policy — Starter Reference
+
+Use this canonical sample when the user has **no concrete intent** ("I want to create an access policy", "help me set one up") **or has gaps** (missing resource type, no caller, no actor identity, no name). Show the **Spec narrative** plus the **JSON definition** as a starter so the user can either adopt it as-is or point at the parts they want to change. The sample seeds the **Policy Spec** that Phase 1 ([planning-arch.md](./planning-arch.md)) iterates with the user.
+
+> **When to use this guide.** Phase 1 routes here when the user's request cannot be classified into Resource / Actor Process / Actor Identity / tag phrases — i.e., when intent analysis would otherwise have no defaults to draw from. Do NOT use it when the user has already described a specific policy.
+
+---
+
+## Sample Spec narrative (natural-language description)
+
+> **"Only the 'Order Processing' Maestro can invoke Production Agents"**
+>
+> This is a **tool-use policy** in **simulation mode** that allows a specific Maestro — "Order Processing" — running on behalf of a specific user to invoke any Agent tagged `Production`.
+>
+> - **What is being protected:** all Agents that carry the `Production` tag.
+> - **Who/what is allowed to call them:** the Maestro named "Order Processing," but only when it is executed by the designated user.
+> - **Effect:** `Allow` — the matching call is permitted.
+> - **Status:** `Simulated` — the policy is evaluated and logged but not yet enforced, so violations are surfaced for review without blocking real traffic.
+>
+> **Intent:** lock down Production-tagged Agents so they can only be driven by the sanctioned Maestro orchestration. Running it in simulation first lets the team verify the rule matches real traffic before flipping enforcement on.
+
+---
+
+## Sample policy — JSON definition
+
+```json
+{
+    "policyType": "ToolUsePolicy",
+    "organizationId": "<ORG_UUID>",
+    "tenantId": "<TENANT_UUID>",
+    "name": "Only the \"Order Processing\" Maestro can invoke Production Agents",
+    "description": "Restrict tool-use of Production-tagged Agents so the only allowed caller is the \"Order Processing\" Maestro in Shared/Solution_Maestro_demo.",
+    "selectors": [
+        {
+            "resourceType": "Agent",
+            "values": ["*"],
+            "operator": "Or",
+            "tags": {
+                "values": ["Production"],
+                "operator": "Or"
+            }
+        }
+    ],
+    "executableRule": {
+        "values": [
+            {
+                "type": "AgenticProcess",
+                "values": ["<AGENTIC_PROCESS_UUID>"],
+                "operator": "Or"
+            }
+        ]
+    },
+    "actorRule": {
+        "values": [
+            {
+                "type": "User",
+                "values": ["<USER_UUID>"],
+                "operator": "Or"
+            }
+        ]
+    },
+    "enforcement": "Allow",
+    "status": "Simulated"
+}
+```
+
+> Replace `<ORG_UUID>` and `<TENANT_UUID>` from `~/.uipath/.auth` (Critical Rule #3). Replace `<AGENTIC_PROCESS_UUID>` and `<USER_UUID>` via [resource-lookup-guide.md](./resource-lookup-guide.md) once the user names a real process and user (Critical Rule #15). Resolve every `<…_UUID>` during Phase 1 — before the Spec is approved and Phase 2 composes the JSON. Never let a placeholder flow into the working file.
+
+---
+
+## How the sample seeds the Spec Components Table
+
+The row meanings, allowed values, and defaults live in [planning-arch.md § Spec output format](./planning-arch.md#spec-output-format) — do not duplicate them here. The sample only supplies the **values** below; pre-fill them into the canonical table when the user adopts or adapts the sample.
+
+| Row | Sample value |
+|---|---|
+| 1 (Policy name) | `Only the "Order Processing" Maestro can invoke Production Agents` |
+| 2 (Description) | one-sentence summary of the narrative above |
+| 3 (Status) | `Simulated` |
+| 4 (Enforcement) | `Allow` |
+| 5 (Resource type) | `Agent` |
+| 6 (Resource scope) | `all` |
+| 7 (Resource tag filter) | Any-of `[Production]` |
+| 8 (Actor Process type) | `Maestro` |
+| 9 (Actor Process scope) | one specific UUID — resolve via [resource-lookup-guide.md](./resource-lookup-guide.md) |
+| 10 (Actor Process tag filter) | `(none)` |
+| 11 (Actor Identity type) | `User` |
+| 12 (Actor Identity scope) | one specific UUID — resolve via [resource-lookup-guide.md](./resource-lookup-guide.md) |
+
+---
+
+## How to present the sample
+
+When intent is missing or thin, show the user **both** the Spec narrative and the JSON definition above (do not paraphrase — keep them verbatim so the user can compare to the file the skill will create), then ask the user to pick one of three paths:
+
+```
+This is a common access-policy shape — protect a tagged Resource, allow exactly one Actor Process, and narrow it to one Actor Identity.
+
+Pick one to continue:
+  1. Use this sample as-is (I'll just resolve the org/tenant/process/user UUIDs).
+  2. Use this sample but adapt some rows (tell me which Spec rows you want to change — Resource, Actor Process, Actor Identity, tag filter, name, status). Enforcement is always `Allow` and cannot be changed (Critical Rule #2).
+  3. Describe your own policy from scratch and I'll build the Spec with you.
+```
+
+Map the user's reply:
+
+- **Option 1** → seed the Spec Components Table from the [mapping table above](#how-the-sample-seeds-the-spec-components-table) — every row pre-filled. Run [resource-lookup-guide.md](./resource-lookup-guide.md) to resolve the Maestro and User UUIDs (do NOT keep `<…_UUID>` placeholders). Read `~/.uipath/.auth` for `organizationId` / `tenantId` (Critical Rule #3). Continue to the [planning-arch.md](./planning-arch.md) Review gate — explicit `yes` is still required.
+- **Option 2** → seed the Spec Components Table from the sample for rows the user did NOT change; mark the rows they want to change as `(missing)` and re-enter the [planning-arch.md](./planning-arch.md) iteration loop on those rows only.
+- **Option 3** → drop the sample, return to [planning-arch.md](./planning-arch.md) intent analysis with the user's full description and build the Spec from scratch.
+
+---
+
+## Anti-patterns
+
+- Do NOT silently start composing JSON when the user has not picked one of the three options. The sample is a prompt, not an approved Spec.
+- Do NOT submit the sample to `uip gov access-policy create` with `<…_UUID>` placeholders intact — every UUID must be resolved first (Critical Rule #3 + Critical Rule #15).
+- Do NOT emit `enforcement: "Deny"` when adapting the sample — `"Deny"` is **not authorable** (Critical Rule #2). Keep `enforcement: "Allow"` and reframe any Deny intent: ask what should be **allowed** and target that set, or use `operator: "None"` on tags / values to express "everything except X" (Critical Rule #2).
+- Do NOT leave `status: "Simulated"` out when the user picks Option 1 or doesn't say otherwise — Simulated is the safe default for newly created policies (Critical Rule #13).
+- Do NOT skip the Phase 1 review gate just because the user picked Option 1. The user must still explicitly approve the Spec before Phase 2 composes the working file (Critical Rule #6).

package/skills/uipath-governance/references/aops-policy/aops-governance-recipes-guide.md

@@ -0,0 +1,226 @@
+# Governance Recipes Guide
+
+Common governance intents mapped to the product policy and fields that implement them. Use these as **priors** for Mode A auto-fill in [configure-aops-policy-data-guide.md](./configure-aops-policy-data-guide.md) — always grep the live `form-template-locale-resource.json` for the listed keywords to confirm the field keys still exist in the current template version before writing values.
+
+> **How to use this file.** When the user's intent matches a recipe, apply its field mapping first, then fall back to general locale grep for anything unmapped. Do NOT hard-code these keys without verifying them in the current template — product fields drift between template versions (22.4, 23.10, 24.10.1, ...).
+
+---
+
+## Prerequisites that shape every recipe
+
+These platform-level conditions affect whether a deployed policy actually takes effect. Verify them before creating policies, and surface them to the user if unmet:
+
+1. **Interactive Sign-In is required on the client.** Studio / StudioX / Assistant must be connected to Orchestrator via Interactive Sign-In for a cloud-deployed policy to apply. A machine running under an unattended/service account without interactive login will not pick up the policy. If the user asks "why isn't my policy taking effect?", check this first.
+2. **Runtime governance is off until the tenant's first Robot policy is deployed.** All RT-* runtime rules (R1–R3 below) require runtime governance to be enabled at the tenant level. The Automation Ops UI shows a banner "Runtime governance is disabled" until the first Robot policy is deployed — enabling it is tenant-wide from that moment (see R4).
+3. **Enforcing a Studio governance policy disables every built-in Analyzer rule by default.** Once a Studio policy is enforced, the default rule set does not ship with it — each rule must be listed explicitly in `Analyzer.EmbeddedRulesConfig.Rules` with `IsEnabled: true`. Silently enforcing governance without enumerating rules is a common reason CoEs report "our analyzer got quieter after we rolled out governance" (see S3).
+4. **Legacy file-based governance is overridden on deployment.** An Automation Ops policy supersedes any local or JSON governance file on the developer's machine. If the org already has a legacy JSON governance file, import it via the Automation Ops UI before rolling out a new policy so existing rules are not lost.
+
+---
+
+## How recipes are structured
+
+Each recipe lists:
+
+- **Intent keywords** — user phrases that trigger it (feed these to `Grep` against the locale resource).
+- **Product** — the `product.name` to pass to `--product-name` on `create`.
+- **Fields** — candidate component `key`s and the values that implement the rule.
+- **Notes** — empty-parameter warnings, license-type compatibility, template-version hints.
+
+Field names below reflect the doc's example JSON; the live `form-template.json` for your tenant may use slightly different keys. Always verify against the bootstrapped schema.
+
+---
+
+## Assistant recipes
+
+### A1 — Minimize Assistant while a process is running
+
+- **Intent keywords:** "stop Assistant popping up", "Assistant keeps appearing", "Assistant pops up during runs", "minimize Assistant while running", "don't interrupt users when a bot runs"
+- **Product:** Assistant policy
+- **Fields:** `MinimizeAssistantWhileRunning: true` (under Feature Toggles).
+- **Notes:** Requires users to sign into Assistant with interactive sign-in for the policy to apply. No parameters — simple toggle.
+
+### A2 — Auto-launch Assistant at Windows startup
+
+- **Intent keywords:** "Assistant should start with Windows", "launch Assistant automatically", "make sure users never miss a scheduled job"
+- **Product:** Assistant policy
+- **Fields:** `AutoLaunchAssistant: true`.
+- **Notes:** Opposite intent (do NOT auto-launch) → `false`.
+
+### A3 — Disable the UiPath Marketplace widget
+
+- **Intent keywords:** "disable Marketplace widget", "stop users installing from Marketplace", "block community automations in Assistant", "only allow vetted automations"
+- **Product:** Assistant policy
+- **Fields:** `Widgets.UiPath.Marketplace.Widget: false`.
+- **Notes:** All-or-nothing — there is no per-item allow-list for Marketplace. To offer specific Marketplace automations, download, vet, and republish through Orchestrator or Automation Hub instead.
+
+### A4 — Block custom widgets and external widget feeds
+
+- **Intent keywords:** "only allow official widgets", "block custom widgets", "don't let users add widget feeds"
+- **Product:** Assistant policy
+- **Fields:**
+  - `Widgets.AllowCustomWidgets: false`
+  - `Widgets.UseOfficialWidgetFeed: false` (only Orchestrator feed allowed).
+- **Notes:** Useful as a pair when the goal is "no widget installs outside corporate-hosted feed."
+
+### A5 — Curate individual widget availability
+
+- **Intent keywords:** "enable Apps widget", "disable Automation Store widget", "show only the Apps widget in Assistant"
+- **Product:** Assistant policy
+- **Fields:** individual toggles under `Widgets`, e.g. `UiPath.Apps.Widget`, `UiPath.AutomationStore.Widget`.
+- **Notes:** After deploying, users may need to sign out/in of Assistant for new widgets to appear. Apps widget also requires at least one published App to be visible.
+
+---
+
+## Robot (Runtime Analyzer) recipes
+
+### R1 — RT-UIA-001 application/URL allow-list
+
+- **Intent keywords:** "only allow automating Outlook and Excel", "block automation of cmd.exe / regedit / Start Menu", "restrict which apps robots can automate", "whitelist these applications"
+- **Product:** Robot policy
+- **Fields:** `RT-UIA-001` rule under `RuntimeAnalyzer`:
+  - `AllowedApplications: ["outlook.exe", "excel.exe", ...]` (allow-list mode)
+  - `BlockedApplications: ["cmd.exe", "regedit.exe", ...]` (block-list mode)
+  - `Action: "Error"` (default — stops the robot at runtime on violation)
+- **Notes:** **Do NOT deploy RT-UIA-001 with empty lists — it enforces nothing.** If the user names apps, populate the list; if they don't, surface that the rule will be a no-op and ask what to include. Test in a non-production tenant first; an overly tight allow-list can halt production jobs.
+
+### R2 — RT-UIA-001 web URL allow/block-list
+
+- **Intent keywords:** "only allow internal domains", "block automation of gmail.com / facebook.com", "restrict web automation to *.internalcompany.com"
+- **Product:** Robot policy
+- **Fields:** `RT-UIA-001`:
+  - `AllowedURLs: ["*.internalcompany.com"]` (allow-list)
+  - `BlockedURLs: ["*facebook.com*", "*gmail.com*"]` (block-list)
+  - `Action: "Error"`
+- **Notes:** Same empty-list warning as R1. Use broad patterns carefully — `*gmail.com*` is safer than a bare `gmail.com` to avoid matching unrelated substrings.
+
+### R3 — RT-OUT-001 email recipient blocklist
+
+- **Intent keywords:** "block robots from emailing gmail/yahoo", "stop bots emailing external domains", "no robot emails outside @mycompany.com", "prevent data leak via email"
+- **Product:** Robot policy
+- **Fields:** `RT-OUT-001` rule under `RuntimeAnalyzer`:
+  - `BlockedEmails: ["*@gmail.com", "*@yahoo.com"]` (pattern list)
+  - `Action: "Error"`
+- **Notes:** Same empty-list warning — `BlockedEmails: []` enforces nothing. Blocks the specific Mail / GSuite / Office365 activity packages the rule covers; other email channels (API-based integrations) are not caught by this rule.
+
+### R4 — Enable runtime governance (prerequisite)
+
+- **Intent keywords:** (any runtime-rule intent above) — and the tenant has never deployed a Robot policy.
+- **Product:** Robot policy
+- **Notes:** Runtime governance is off until the first Robot policy is deployed to the tenant. The Automation Ops UI surfaces a "Runtime governance is disabled" banner; the agent should warn the user before the first deployment so they know the effect is tenant-wide from that moment on.
+
+---
+
+## Studio (design-time) recipes
+
+### S1 — Gate Publish/Run on Workflow Analyzer
+
+- **Intent keywords:** "enforce analyzer before publish", "block publish if analyzer errors", "require clean analyzer before running"
+- **Product:** Studio policy (`Development` or equivalent)
+- **Fields:** `Design.EnforceAnalyzerBeforePublish: true`, `Design.EnforceAnalyzerBeforeRun: true`.
+- **Notes:** With these on, any Analyzer rule at `ErrorLevel: "Error"` stops publish/run. Pair with specific rule configs (S3).
+
+### S2 — Require release notes and source-control check-in
+
+- **Intent keywords:** "require release notes on publish", "must check in before publish", "enforce versioning discipline"
+- **Product:** Studio policy
+- **Fields:** `Design.EnforceReleaseNotes: true`, `Design.EnforceCheckInBeforePublish: true`.
+
+### S3 — Enable and configure Workflow Analyzer rules
+
+- **Intent keywords:** "enforce naming conventions", "require camelCase variables", "block hardcoded credentials", "enforce our coding standards"
+- **Product:** Studio policy
+- **Fields:** `Analyzer.EmbeddedRulesConfig.Rules` — array of `{Id, IsEnabled, Parameters, ErrorLevel}`. Well-known rule IDs:
+  - `ST-NMG-001` — variable / argument / activity naming regex. Parameter: `Regex` (e.g. `^[a-z][A-Za-z0-9]*$`).
+  - `ST-SEC-*` — security rules (hardcoded credentials, untrusted sources).
+  - `ST-USG-027` — Required Packages. Parameter: `Packages` — semicolon- or version-suffixed list (e.g. `MyCompany.CustomRulesPackage>=1.0.0`). Used to force developers to include a custom NuGet-packaged analyzer rule.
+- **Notes:**
+  - **Built-in rules are DISABLED by default once governance is enforced.** Every rule you want active must appear in the array with `IsEnabled: true` and a valid `ErrorLevel`. If the user asks you to "enforce Workflow Analyzer" without naming rules, do NOT deploy — ask which rules matter, or apply a CoE baseline (e.g. `ST-NMG-001`, `ST-SEC-*`, `ST-USG-027`) and confirm with the user before saving.
+  - `Analyzer.AllowEdit: false` (default) prevents local overrides. Set to `true` only if the user explicitly wants developers to toggle rules locally.
+  - Set `ErrorLevel: "Error"` for blocking issues, `"Warning"` for stylistic ones. Pair `Error` rules with S1 (`EnforceAnalyzerBeforePublish`) so violations actually block publish.
+  - Runtime rules (R1–R3) are a safety net — always pair with design-time Studio rules so violations are caught at design time first, not only at runtime.
+
+### S4 — Source-control repository whitelist
+
+- **Intent keywords:** "only allow our corporate GitHub", "whitelist these repositories", "block pushing to unauthorized repos"
+- **Product:** Studio policy
+- **Fields:** `SourceControl.AllowedRepositories: ["https://github.com/MyOrg/Repo1.git", ...]`, `SourceControl.AllowEditRepositories: false`.
+- **Notes:** `AllowEditRepositories: false` prevents developers from adding repos; the `AllowedRepositories` list is exhaustive.
+
+### S5 — Restrict package sources (feeds)
+
+- **Intent keywords:** "block public Marketplace feed", "only allow internal NuGet", "no external packages", "use only our vetted feed"
+- **Product:** Studio policy
+- **Fields:**
+  - `Feeds.OfficialFeed: false` (disable UiPath public feed)
+  - `Feeds.MarketplaceFeed: false`
+  - `Feeds.AllowUserDefinedFeeds: false`
+  - `Feeds.CustomFeeds: ["OrchestratorTenantFeed"]` (or an internal URL)
+- **Notes:** Pair with S3 `ST-USG-027` to force a custom NuGet-packaged analyzer rule to be included in every project.
+
+### S6 — Export analyzer results for CI/CD
+
+- **Intent keywords:** "capture analyzer output", "save analysis results for audits", "feed analyzer results into pipelines"
+- **Product:** Studio policy
+- **Fields:** `Design.ExportAnalyzerResults: true`.
+- **Notes:** Each analyzer run writes a JSON report into the project folder; a CI job can aggregate these.
+
+---
+
+## StudioX (Citizen Developer) recipes
+
+### X1 — Hide the developer panel from citizen devs
+
+- **Intent keywords:** "lock down StudioX", "citizen devs shouldn't see developer activities", "hide advanced activities"
+- **Product:** StudioX policy (`Business` or equivalent)
+- **Fields:** `ShowDeveloperPanel: false`.
+
+### X2 — Hide specific activities from StudioX
+
+- **Intent keywords:** "hide Execute Macro", "block WriteRange for business users", "remove these activities from StudioX"
+- **Product:** StudioX policy
+- **Fields:** `ActivitiesToHide: "UiPath.Excel.Activities.Business.WriteRangeX, UiPath.Core.Activities.ExecuteMacro"` (comma-separated activity namespaces).
+
+### X3 — Prevent StudioX as an ad-hoc runtime
+
+- **Intent keywords:** "stop users running the same automation repeatedly in StudioX", "force promotion to Orchestrator", "limit consecutive runs"
+- **Product:** StudioX policy
+- **Fields:** `PermittedConsecutiveRunsWithNoChange: 2` (or similar low integer). After the cap, further runs from StudioX are blocked.
+
+### X4 — Force projects off the local PC
+
+- **Intent keywords:** "don't let citizen devs save to C:", "all projects must go to Orchestrator personal workspace", "no local project storage"
+- **Product:** StudioX policy
+- **Fields:** `AllowSavingProjectLocally: false`.
+- **Notes:** Ensure a valid Orchestrator personal workspace or shared location is configured via the Locations tab in the same policy — otherwise users can't save anywhere.
+
+---
+
+## Deployment recipe — precedence and narrowest scope
+
+When the user asks for a scope-limited rule:
+
+- "Apply to one user only" → deploy at **user** level. Overrides group and tenant for that user.
+- "Apply to the X team / group" → deploy at **group** level. Overrides tenant for group members.
+- "Apply to everyone in this tenant" → deploy at **tenant** level (with a `(product, license type)` key). Base-layer default.
+- "Exception for team X that ignores the tenant rule" → deploy a different policy at group level; tenant-level rule still applies to non-members.
+
+Order of effective resolution: **User > Group > Tenant > (no policy)**. See [aops-policy-deploy-guide.md — Deployment precedence](./aops-policy-deploy-guide.md#deployment-precedence) for the decision flow.
+
+---
+
+## Anti-patterns
+
+- Do NOT write runtime-rule policies (RT-UIA-001, RT-OUT-001) with empty parameter arrays — the rule is enabled by default but enforces nothing until populated. Surface this to the user if their intent didn't list any apps / URLs / emails.
+- Do NOT assume a recipe's field `key`s match the live template without grepping. Template versions (22.4 → 23.10 → 24.10.1) occasionally rename or add fields. Verify against `form-template-locale-resource.json` before writing.
+- Do NOT deploy an Assistant-product policy to a license type that doesn't include Assistant (e.g. `Unattended Robot` → Robot only). See [license-type list output](./aops-policy-commands.md#uip-gov-aops-policy-license-type-list) for the product coverage per license type.
+- Do NOT pair "block Marketplace widget" with "allow these specific Marketplace items" — the toggle is all-or-nothing. Re-host vetted automations in a controlled feed instead.
+- Do NOT assume enforcing a Studio policy activates the default Workflow Analyzer rule set. Governance turns EVERY built-in rule off by default — you must enumerate each rule in `Analyzer.EmbeddedRulesConfig.Rules` with `IsEnabled: true`. An empty `Rules` array = zero analyzer enforcement.
+- Do NOT deploy a cloud policy expecting it to apply to clients that aren't Interactively Signed-In to Orchestrator. Unattended / service-account Studio or Assistant installs ignore cloud policies — the user must use Interactive Sign-In.
+
+---
+
+## Related references
+
+- [configure-aops-policy-data-guide.md](./configure-aops-policy-data-guide.md) — Mode A auto-fill consumes these recipes as priors before general locale grep.
+- [aops-policy-deploy-guide.md](./aops-policy-deploy-guide.md) — user / group / tenant precedence and license-type compatibility.
+- [aops-policy-commands.md — license-type list](./aops-policy-commands.md#uip-gov-aops-policy-license-type-list) — authoritative mapping of license type `name` → products.