@salesforce/afv-skills 1.44.0 → 1.45.0

package/skills/service-itsm-agentic-setup-agent-runtime-access-assign/references/cli-invocation.md

@@ -0,0 +1,205 @@
+# CLI Invocation — service-itsm-agentic-setup-agent-runtime-access-assign
+
+Every read and write uses the **Salesforce CLI (`sf`)** against the CLI's stored
+session for `--target-org <alias>`. **Never extract the access token** from
+`sf org display` — hand-building a raw HTTP request bypasses the CLI session and
+leaks a bearer token into shell context.
+
+## `--json` rule
+
+- `sf data query` **takes** `--json` → `{status, result:{records:[...]}}` envelope. That is what the classifier scripts expect.
+- `sf api request rest` does **not** — its raw stdout body is already JSON. Passing `--json` errors on some endpoints.
+- `sf org assign permset` **takes** `--json` → `result:{successes:[...], failures:[...]}`.
+
+## Phase 1 — discovery reads
+
+Platform feature permsets (see `permset-topology.md` for the fixed six Names):
+
+```bash
+sf data query \
+  -q "SELECT Id, Name, Label, LicenseId FROM PermissionSet WHERE Name IN ('EinsteinGPTPromptTemplateUser','EinsteinGPTPromptTemplateManager','GenieUserEnhancedSecurity','GenieAdmin','UnifiedCatalogCommunityUser','UnifiedCatalogAdmin')" \
+  --target-org <alias> --json
+```
+
+Activated agents (an agent is activated iff the `BotVersions` child returns ≥1 row):
+
+```bash
+sf data query \
+  -q "SELECT Id, DeveloperName, MasterLabel, (SELECT Status FROM BotVersions WHERE Status='Active') FROM BotDefinition WHERE Type='InternalCopilot'" \
+  --target-org <alias> --json
+```
+
+## Phase 2 — identity read
+
+```bash
+sf api request rest "/services/data/v67.0/" --method GET --target-org <alias>
+```
+
+`identity` is a URL ending in `/<orgId>/<userId>`; take the trailing `005…`
+segment via `scripts/resolve-target-user.mjs`. Do NOT call `USER_ID()` (Apex-only)
+or `/chatter/users/me` (403 when Chatter is off).
+
+The resolver returns only `{ userId, identity, verdict }` — it carries no name. To
+label the running-user option **"Me — <name>"** (fall back to just **"Me"** if this
+returns nothing), read the name explicitly. Then query active org users with the
+fields the ranker needs (`Profile.Name`, `Profile.UserLicense.Name`) and hand them
+to `rank-candidate-users.mjs`, which filters out service/integration/bot/agent
+accounts and returns up to five real candidates ranked for the `<audience>`
+(`fulfiller` ⇒ standard-license users first; `employee` ⇒ Unified Employee users
+first; `any` ⇒ input order):
+
+The running-user query also selects `Profile.Name` + `Profile.UserLicense.Name` —
+the Unified Catalog gate (Phase 3) needs the target user's license/profile:
+
+```bash
+sf data query -q "SELECT Name, Profile.Name, Profile.UserLicense.Name FROM User WHERE Id = '<userId>'" \
+  --target-org <alias> --json > /tmp/itsm-running-user.json 2>/dev/null || true
+
+sf data query -q "SELECT Id, Name, Username, Profile.Name, Profile.UserLicense.Name FROM User WHERE IsActive = true ORDER BY LastLoginDate DESC NULLS LAST LIMIT 25" \
+  --target-org <alias> --json > /tmp/itsm-candidate-users.json 2>/dev/null || true
+
+node "<skill_dir>/scripts/rank-candidate-users.mjs" /tmp/itsm-candidate-users.json <audience> <userId>
+```
+
+The `AskUserQuestion` picker takes at most four options, so offer **"Me — <name>"**
+(recommended) plus the **top three** ranked candidates; its built-in **"Other"**
+free-text option covers any username not listed. Determine `<audience>` from the
+agent this grant is for (named in the request/handoff, or the Phase-1 activated
+set) — a Fulfiller agent is run by IT staff (standard license), an Employee agent
+by end employees (Unified Employee).
+
+Named user (or any chosen/typed option) — also select the profile + license so the
+Unified Catalog gate can run for this user. **Capture each selected user to its own
+file**, keyed by username — never a single shared path: the target-user picker is a
+multi-select, so a fixed file would clobber earlier users and mis-gate them against
+the last user's license/profile:
+
+```bash
+# Run once per selected user; each writes a distinct, username-keyed file.
+sf data query -q "SELECT Id, Username, Name, IsActive, Profile.Name, Profile.UserLicense.Name FROM User WHERE Username = '<username>'" \
+  --target-org <alias> --json > "/tmp/itsm-target-user-<username>.json"
+```
+
+## Phase 3 — Unified Catalog per-user tier gate
+
+The Unified Catalog PSLs are license-**shape** gated: the Community User tier can
+be held only by a **Unified Employee** user and the Admin tier only by a **System
+Administrator**. Before asking the Unified Catalog tier, run the gate **once per
+selected target user** against **that user's own capture**
+(`/tmp/itsm-running-user.json` for the running user,
+`/tmp/itsm-target-user-<username>.json` for each named user) plus the Phase-1
+availability capture, and **retain each user's `offer[]`/`omit` with that user's
+assignment plan** — never reuse one user's result for another. Offer only the tiers
+in `offer[]`, and on `omit` skip Unified Catalog for that user as "not applicable for
+this user's license/profile — skipped":
+
+```bash
+node "<skill_dir>/scripts/classify-platform-permset-availability.mjs" /tmp/itsm-platform-permsets.json > /tmp/itsm-availability.json
+# Running user:
+node "<skill_dir>/scripts/gate-unified-catalog-tiers.mjs" /tmp/itsm-availability.json /tmp/itsm-running-user.json
+# Each named user — against that user's own capture:
+node "<skill_dir>/scripts/gate-unified-catalog-tiers.mjs" /tmp/itsm-availability.json "/tmp/itsm-target-user-<username>.json"
+```
+
+## Phase 4 — idempotency reads
+
+Agent Access permset + its existing `BotDefinition` grants (second query only
+when the permset exists — else pass `NO-PERMSET` to the classifier):
+
+```bash
+sf data query -q "SELECT Id, Name, Label FROM PermissionSet WHERE Name='Agent_Access'" \
+  --target-org <alias> --json > /tmp/agent-access.json
+
+sf data query -q "SELECT SetupEntityId FROM SetupEntityAccess WHERE ParentId='<permsetId>' AND SetupEntityType='BotDefinition'" \
+  --target-org <alias> --json > /tmp/sea.json
+```
+
+Per user + permset (feature tier or `Agent_Access`). PSLA query only when the
+selected tier's `needsPsl:true`:
+
+```bash
+sf data query -q "SELECT Id FROM PermissionSetAssignment WHERE AssigneeId='<userId>' AND PermissionSetId='<permsetId>'" \
+  --target-org <alias> --json > /tmp/psa.json
+
+sf data query -q "SELECT Id FROM PermissionSetLicenseAssign WHERE AssigneeId='<userId>' AND PermissionSetLicenseId='<licenseId>'" \
+  --target-org <alias> --json > /tmp/psla.json
+```
+
+## Phase 6 — writes
+
+**Create `Agent_Access`** (only if `needsCreate`). `Name` is the API name;
+`Label` is the display label:
+
+```bash
+sf api request rest "/services/data/v67.0/sobjects/PermissionSet" \
+  --method POST \
+  --body '{"Name":"Agent_Access","Label":"Agent Access"}' \
+  --target-org <alias>
+```
+
+Response: `{"id":"0PS...","success":true,"errors":[]}`. Capture `id` — it is the
+`ParentId` for the grants.
+
+**Grant each chosen agent** (`SetupEntityId` = the `BotDefinition` Id). Send
+`ParentId` + `SetupEntityId` ONLY — `SetupEntityType` is not creatable:
+
+```bash
+sf api request rest "/services/data/v67.0/sobjects/SetupEntityAccess" \
+  --method POST \
+  --body '{"ParentId":"<permsetId>","SetupEntityId":"<botDefinitionId>"}' \
+  --target-org <alias>
+```
+
+`DUPLICATE_VALUE` here ⇒ that agent is already granted; treat as success.
+
+**PSL first, then permset** for a license-gated feature tier (`needsPsl:true`).
+Use the selected tier's own `LicenseId` as `PermissionSetLicenseId`:
+
+```bash
+sf api request rest "/services/data/v67.0/sobjects/PermissionSetLicenseAssign" \
+  --method POST \
+  --body '{"AssigneeId":"<userId>","PermissionSetLicenseId":"<licenseId>"}' \
+  --target-org <alias>
+
+# Running user (the default target): OMIT --on-behalf-of; the command assigns to
+# the authenticated user.
+sf org assign permset --name "<permsetName>" --target-org <alias> --json
+# A NAMED target user: pass their resolved <username> — NOT a 005 Id.
+sf org assign permset --name "<permsetName>" --on-behalf-of "<username>" \
+  --target-org <alias> --json
+```
+
+> **`--on-behalf-of` resolves by `Username`/alias, not a `005…` user Id.** Passing
+> a user Id fails to match. For the running user (the default target) omit the flag
+> entirely; for a named user pass the `<username>` resolved by the
+> `WHERE Username=` query. Do **not** substitute a `$USERNAME` shell variable — in
+> zsh it is a read-only builtin bound to the OS user and will silently mis-target.
+
+**`Agent_Access` assignment** per user (standalone — no PSL):
+
+```bash
+# Running user (default): OMIT --on-behalf-of.
+sf org assign permset --name "Agent_Access" --target-org <alias> --json
+# Named user: --on-behalf-of "<username>" (Username, never a 005 Id).
+sf org assign permset --name "Agent_Access" --on-behalf-of "<username>" \
+  --target-org <alias> --json
+```
+
+`sf org assign permset` response: `result.successes[]` / `result.failures[]`; a
+`failure.message` matching `Duplicate id`/`already has` is idempotent success.
+
+## Phase 7 — verify read-backs
+
+Re-run the Phase-4 `PermissionSetAssignment` / `PermissionSetLicenseAssign`
+queries for each target user, and the `SetupEntityAccess` query for
+`Agent_Access`, and confirm each intended row is now present.
+
+## Common error responses (surface verbatim)
+
+| Status / errorCode | Meaning | Handling |
+|---|---|---|
+| `400 DUPLICATE_VALUE` on any POST | Row already exists | Idempotent success; not a failure |
+| `400 INSUFFICIENT_ACCESS` on a PSL POST | Seat exhausted | STOP that write; tell the user no seats are available |
+| `400`/`404` on `SetupEntityAccess` POST with `SetupEntityType` in body | Field not creatable | Remove `SetupEntityType`; send `ParentId`+`SetupEntityId` only |
+| `401 Unauthorized` | CLI session expired | `sf org login web --alias <alias>` and retry |
+| `404 Not Found` on `sf org assign permset` | Permset name absent on this org | Re-run Phase 1 discovery; org state may have changed |

package/skills/service-itsm-agentic-setup-agent-runtime-access-assign/references/helper-contracts.md

@@ -0,0 +1,236 @@
+# Helper Script Contracts — service-itsm-agentic-setup-agent-runtime-access-assign
+
+All seven scripts are deterministic, side-effect-free JSON classifiers (A9). Each
+reads one or more `sf data query --json` / `sf api request rest` captures and
+emits a single JSON object to stdout. Exit is `0` on any parseable body — the
+verdict is carried in the payload. Exit `2` is a usage error (missing args); the
+scripts never exit non-zero on a workflow-blocking condition — that is the
+caller's job based on the emitted `verdict`.
+
+## `scripts/classify-platform-permset-availability.mjs`
+
+Which platform features are provisioned, and each tier's `present` + `needsPsl`.
+
+### Input
+
+1. `permsets.json` — `sf data query --json` capture of `PermissionSet` filtered
+   to the six known feature-tier `Name` values (see `permset-topology.md`).
+
+### Output
+
+```json
+{
+  "features": [
+    { "feature": "Prompt Templates",
+      "tiers": {
+        "use":   { "tier":"use",   "name":"EinsteinGPTPromptTemplateUser",    "displayLabel":"Prompt Template User",    "present":true, "Id":"0PS…", "LicenseId":"0PL…", "needsPsl":true },
+        "admin": { "tier":"admin", "name":"EinsteinGPTPromptTemplateManager", "displayLabel":"Prompt Template Manager", "present":true, "Id":"0PS…", "LicenseId":"0PL…", "needsPsl":true }
+      },
+      "anyPresent": true }
+  ],
+  "provisionedFeatures": ["Prompt Templates","Data Cloud"],
+  "absentFeatures": ["Unified Catalog"],
+  "verdict": "ASSIGNABLE",
+  "reasons": ["..."]
+}
+```
+
+- `displayLabel` prefers the org's own `Label`; falls back to a canonical label only when the row is absent.
+- `needsPsl` is per row (`LicenseId !== null`). Read it from the SELECTED tier.
+
+| verdict | Meaning | Caller action |
+|---|---|---|
+| `ASSIGNABLE` | ≥1 feature provisioned | Ask a tier per provisioned feature; skip + report absent features |
+| `NONE-PROVISIONED` | no feature permset present | Report it; still continue to the Agent Access concern |
+| `CANNOT-CONFIRM` | query envelope unparseable | Surface `reasons[]` verbatim and stop |
+
+**Never auto-select a tier.** Present use/agent vs admin and let the user pick.
+
+## `scripts/gate-unified-catalog-tiers.mjs`
+
+Per **target user**, which **Unified Catalog** tiers are eligible to offer — or
+whether to omit Unified Catalog for that user. The Unified Catalog PSLs are
+license-**shape** gated (not seat-gated): the Community User tier can be held only
+by a **Unified Employee**-licensed user, and the Admin tier is meaningful only for
+a **System Administrator**. Offering a tier the user's license/profile can never
+hold is a hard write-time failure, so this gate runs *before* the tier prompt.
+
+### Input (two positional args)
+
+1. `availability.json` — the `classify-platform-permset-availability.mjs` output
+   capture (carries the Unified Catalog `use`/`admin` tier objects with
+   `present`/`Id`/`LicenseId`/`needsPsl`).
+2. `user.json` — a `sf data query --json` capture of the **one** target user,
+   selecting `Profile.Name` and `Profile.UserLicense.Name`.
+
+### Output
+
+```json
+{
+  "feature": "Unified Catalog",
+  "provisioned": true,
+  "user": { "profile":"System Administrator", "license":"Salesforce", "unifiedEmployee":false, "sysAdmin":true },
+  "offer": [ { "tier":"admin", "name":"UnifiedCatalogAdmin", "Id":"0PS…", "LicenseId":"0PL…", "needsPsl":true } ],
+  "omit": false,
+  "note": "..."
+}
+```
+
+- `offer[]` is the subset of **present** UC tiers this user is eligible for: `use`
+  (`UnifiedCatalogCommunityUser`) only when `unifiedEmployee`; `admin`
+  (`UnifiedCatalogAdmin`) only when `sysAdmin`. Feed those tier objects straight to
+  the tier prompt / write path.
+- `omit:true` (empty `offer[]`) ⇒ do **not** present Unified Catalog for this user;
+  report it "not applicable for this user's license/profile — skipped" (never a
+  failed write). Run the gate **once per target user**, each against **that user's
+  own capture file** (the target-user picker is a multi-select — capture each user to
+  a distinct `/tmp/itsm-target-user-<username>.json`, never a shared path that a later
+  lookup would clobber), and retain each user's result with that user's assignment
+  plan — different users can differ.
+- Fails **closed**: an unreadable availability or user capture ⇒ `omit:true` (better
+  to skip than to offer a tier that will fail); the reason is in `note`. Always exits
+  `0` on parseable bodies; exit `2` only on missing argv.
+
+## `scripts/resolve-target-user.mjs`
+
+Extracts the running user's `005…` Id from the API-root `identity` URL.
+
+### Input
+
+1. `api-root.json` — capture of `sf api request rest "/services/data/v67.0/" --method GET`.
+
+### Output
+
+`{ userId, identity, verdict: "RESOLVED" | "CANNOT-CONFIRM", reasons }`. The
+trailing path segment must match `^005[A-Za-z0-9]{12}([A-Za-z0-9]{3})?$` (15 or
+18 chars). Any other shape ⇒ `CANNOT-CONFIRM` (surface verbatim; do NOT fall back
+to prose parsing).
+
+## `scripts/rank-candidate-users.mjs`
+
+Up to five real, non-service candidate users to OFFER as selectable options when
+the caller did not name a target user. A presentation aid, never a gating decision.
+
+### Input (three positional args)
+
+1. `users.json` — `sf data query --json` capture selecting active users with
+   `Id, Name, Username, Profile.Name, Profile.UserLicense.Name`.
+2. `audience` — `fulfiller` | `employee` | `any` (anything else ⇒ `any`). A
+   Fulfiller agent is run by IT staff on a **standard** license; an Employee agent
+   by end employees on a **Unified Employee** license — the matching cohort is
+   surfaced first.
+3. `runningUserId` (optional) — the "Me" user, excluded from candidates (it is
+   offered separately as the recommended option).
+
+### Output
+
+```json
+{
+  "candidates": [ { "Id":"005…", "Name":"Ada Lovelace", "Username":"ada@example.com", "profile":"Standard User", "cohort":"standard" } ],
+  "audience": "fulfiller",
+  "total": 3,
+  "note": "Offering 3 candidate(s), standard cohort first (audience: fulfiller)."
+}
+```
+
+- Service/integration/bot/agent accounts (matched on profile, license, username,
+  or display name) are filtered out; `candidates[]` is capped at five.
+- `cohort` is `unified-employee` when the user's Unified Employee **license**
+  (`Profile.UserLicense.Name`) matches — or, defensively, their `Profile.Name` — else
+  `standard`. The license is the authoritative signal, so a custom profile carrying
+  the license still ranks as Unified Employee. The audience-matching cohort is ranked
+  first; input order (the query orders by most-recent login) is preserved within a cohort.
+- Empty `candidates[]` (no non-service humans, or an unreadable capture) ⇒ offer
+  **"Me"** plus the free-text **"Other"** option only. Always exits `0` on a
+  parseable body; exit `2` only on missing argv.
+- The `AskUserQuestion` picker takes ≤4 options, so offer **"Me"** plus the **top
+  three** candidates; the rest stay reachable via **"Other"**.
+
+## `scripts/classify-activated-agents.mjs`
+
+The activated-agent candidate list for the `Agent_Access` grants.
+
+### Input
+
+1. `bot-definitions.json` — capture of the `BotDefinition` + `(SELECT Status FROM BotVersions WHERE Status='Active')` query.
+
+### Output
+
+```json
+{
+  "agents": [ { "Id":"0Xx…", "DeveloperName":"IT_Service_Fulfiller_Agent", "MasterLabel":"IT Service Fulfiller Agent", "active": true } ],
+  "activatedAgents": [ { "Id":"0Xx…", "DeveloperName":"…", "MasterLabel":"…" } ],
+  "inactiveAgents": [],
+  "verdict": "AGENTS-FOUND" | "NONE-ACTIVE" | "CANNOT-CONFIRM",
+  "reasons": ["..."]
+}
+```
+
+An agent is `active` iff its `BotVersions` child subquery returns ≥1 row. Only
+`activatedAgents[]` are offered for the multi-select.
+
+| verdict | Meaning | Caller action |
+|---|---|---|
+| `AGENTS-FOUND` | ≥1 activated agent | Present `activatedAgents[]` for multi-select |
+| `NONE-ACTIVE` | no activated agent (none exist, or none active) | Report it; if features are also `NONE-PROVISIONED`, stop |
+| `CANNOT-CONFIRM` | query envelope unparseable | Surface `reasons[]` verbatim and stop |
+
+## `scripts/classify-agent-access-state.mjs`
+
+Whether `Agent_Access` must be created and which chosen agents still need a grant.
+
+### Input (three positional args)
+
+1. `agent-access-permset.json` — `PermissionSet WHERE Name='Agent_Access'` capture.
+2. `sea-existing.json` **OR** the sentinel `NO-PERMSET`:
+   - permset present ⇒ pass the `SetupEntityAccess WHERE ParentId=<permsetId> AND SetupEntityType='BotDefinition'` capture.
+   - permset absent ⇒ pass `NO-PERMSET` (no parent to query yet).
+3. `chosenAgentIds-csv` — comma-separated `BotDefinition` Ids the user selected.
+
+### Output
+
+```json
+{
+  "permsetExists": false, "permsetId": null,
+  "chosenAgentIds": ["0Xx…","0Xx…"],
+  "grantedAgentIds": [], "missingAgentIds": ["0Xx…","0Xx…"],
+  "needsCreate": true, "needsGrants": true,
+  "verdict": "NEEDS-WORK" | "ALREADY-COMPLETE" | "CANNOT-CONFIRM",
+  "reasons": ["..."]
+}
+```
+
+| verdict | Meaning | Caller action |
+|---|---|---|
+| `NEEDS-WORK` | permset missing and/or ≥1 chosen agent ungranted | Confirm-to-write, then create (if `needsCreate`) + grant each `missingAgentIds` |
+| `ALREADY-COMPLETE` | permset exists and grants every chosen agent | No `SetupEntityAccess` write; still assign the permset to the user(s) if needed |
+| `CANNOT-CONFIRM` | envelope unparseable, or a contradictory `NO-PERMSET`/empty-chosen input | Surface `reasons[]` verbatim and stop |
+
+## `scripts/classify-assignment-state.mjs`
+
+Per user + permset idempotency (feature tier OR `Agent_Access`).
+
+### Input (two positional args)
+
+1. `psa-existing.json` — `PermissionSetAssignment` capture for the target user + permset Id.
+2. `psla-existing.json` **OR** the sentinel `NO-PSL`:
+   - selected tier `needsPsl:true` ⇒ pass the `PermissionSetLicenseAssign` capture.
+   - standalone (`Agent_Access`, or any `needsPsl:false` tier) ⇒ pass `NO-PSL`; `licenseAssigned` is reported `null`.
+
+### Output
+
+`{ permsetAssigned, licenseAssigned, needsWrite, verdict, reasons }`.
+
+| verdict | Meaning | Caller action |
+|---|---|---|
+| `NEEDS-WRITE` | permset (or, when `needsPsl:true`, its license) missing | Confirm-to-write, then assign (PSL first if `needsPsl:true`; permset only if `false`) |
+| `ALREADY-ASSIGNED` | all applicable rows present | Skip the write; go to verify |
+| `CANNOT-CONFIRM` | a query envelope was unparseable | Surface `reasons[]` verbatim and stop |
+
+## Why deterministic classifiers?
+
+Every decision that gates a write or a success report lives in a script, not in
+prose. Model interpretation of `records[].length === 0` is a documented source of
+false-positive skips ("empty, so nothing exists — proceed") when the real cause
+was an auth failure that returned an empty envelope. The scripts distinguish a
+real empty result from a failed read and carry the difference in the verdict.

package/skills/service-itsm-agentic-setup-agent-runtime-access-assign/references/permset-topology.md

@@ -0,0 +1,132 @@
+# Platform Feature Permset Topology + Agent Access Mechanism
+
+This skill grants a **user** two kinds of access after an ITSM agent is
+activated:
+
+1. the **runtime action-execution permissions** the agent's actions call, and
+2. **access to the activated agents themselves** via a custom `Agent_Access`
+   permission set.
+
+## 1. Platform feature permsets (runtime action execution)
+
+Verified live against real orgs. Each feature has a lighter **use/agent** tier
+(enough to *use* the feature at runtime) and a full **admin** tier. All shipped
+tiers observed are **license-gated** (`LicenseId != null` → `needsPsl:true`), but
+the write path never assumes this — it reads `needsPsl` per row.
+
+| Feature | use/agent tier (PermissionSet.Name) | admin tier (PermissionSet.Name) | Notes |
+|---|---|---|---|
+| Prompt Templates | `EinsteinGPTPromptTemplateUser` ("Prompt Template User") | `EinsteinGPTPromptTemplateManager` ("Prompt Template Manager") | both tiers share one PSL (`EinsteinGPTPromptTemplatesPsl`) |
+| Data Cloud | `GenieUserEnhancedSecurity` ("Data Cloud User") | `GenieAdmin` (ships as "Data Cloud Architect" or "Data Cloud Admin") | both tiers share one PSL (`GenieDataPlatformStarterPsl`) |
+| Unified Catalog | `UnifiedCatalogCommunityUser` ("Unified Catalog Community User") | `UnifiedCatalogAdmin` ("Unified Catalog Admin") | tiers are backed by per-tier PSLs (`UnifiedCatalogCommunityUserPsl` / `UnifiedCatalogAdminPsl`). **`UnifiedCatalogAgent` is NOT the human tier** — its shipped Description reads "Enables the *agent* to run service process", i.e. it is the agent's own bot-runtime identity permset, not what a human user assigns to exercise the agent |
+
+### Key facts
+
+- **No single org has all three features.** On a Prompt-Template + Data-Cloud
+  org, the two Unified Catalog rows simply do not exist — the classifier reports
+  Unified Catalog `absent` and the skill skips it. This is expected, not a
+  failure. Detect-if-present / assign-what-is-there / report-the-rest is the
+  whole point of the availability classifier.
+- **Display label comes from the org.** `GenieAdmin` renders as "Data Cloud
+  Architect" on some orgs and "Data Cloud Admin" on others — the classifier
+  prefers the row's own `Label` and falls back to the canonical label only when
+  the row is absent. Never hard-code the label in user-facing text.
+- **`needsPsl` is per row, from `LicenseId`.** The PSL POST uses the selected
+  tier's own `LicenseId` as `PermissionSetLicenseId` — PSL *names* above are for
+  human orientation only and are never queried by name in the write path.
+- **Unified Catalog user tier = `UnifiedCatalogCommunityUser`, not `UnifiedCatalogAgent`.**
+  The three shipped standard permsets and their productized `Description` are:
+  `UnifiedCatalogAgent` = "Enables the **agent** to run service process" (the
+  agent's own bot-runtime identity — a machine tier, not a human one);
+  `UnifiedCatalogCommunityUser` = "Enables the **Community User** to **run**
+  unified catalog service process" (the human RUN tier — what a user, including a
+  Unified Employee user, assigns to exercise the agent's Unified Catalog actions);
+  `UnifiedCatalogAdmin` = "Enables the user to **setup** unified catalog" (the
+  admin/config tier). There is no plain `UnifiedCatalogUser`. So the human tiers
+  are `UnifiedCatalogCommunityUser` (use) + `UnifiedCatalogAdmin` (admin);
+  `UnifiedCatalogAgent` is deliberately excluded (it belongs to the agent's own
+  user, provisioned elsewhere, not to the human being granted access here).
+- `DataCloudAISpecialist` also exists but is not one of this skill's tiers.
+- **Unified Catalog tiers are license-SHAPE gated per target user.** Unlike Prompt
+  Templates and Data Cloud (offered to any user), the two Unified Catalog PSLs can
+  only be held by specific cohorts: `UnifiedCatalogCommunityUser` (the Community
+  User / use tier) requires a **Unified Employee** license, and `UnifiedCatalogAdmin`
+  (the Admin tier) is meaningful only for a **System Administrator**. Offering a UC
+  tier to a user whose license/profile can't hold it is a hard write-time failure
+  (a license-shape limit, not a seat shortage — retrying won't help). So
+  `scripts/gate-unified-catalog-tiers.mjs` runs per target user and offers the
+  Community User tier only to a Unified Employee user, the Admin tier only to a
+  System Administrator, and **omits Unified Catalog entirely** for any other user
+  (reported "not applicable for this user's license/profile — skipped", never a
+  failed write). This gate is Unified-Catalog-specific; the other two features are
+  not cohort-gated.
+
+### Fixed-lookup discovery query (Phase 1)
+
+```sql
+SELECT Id, Name, Label, LicenseId
+FROM PermissionSet
+WHERE Name IN (
+  'EinsteinGPTPromptTemplateUser',
+  'EinsteinGPTPromptTemplateManager',
+  'GenieUserEnhancedSecurity',
+  'GenieAdmin',
+  'UnifiedCatalogCommunityUser',
+  'UnifiedCatalogAdmin'
+)
+```
+
+## 2. Agent access via `Agent_Access` + `SetupEntityAccess`
+
+An Agentforce / NGA agent is a **`BotDefinition`** record with
+`Type = 'InternalCopilot'`. A permission set grants access to a specific agent
+through a **`SetupEntityAccess`** row — exactly like granting Apex-class access:
+
+```text
+SetupEntityAccess {
+  ParentId:      <permission set Id>,   // the Agent_Access permset
+  SetupEntityId: <BotDefinition Id>     // the agent (0Xx… key prefix)
+}
+```
+
+### Load-bearing details (verified via `sf sobject describe`)
+
+- **`PermissionSet` is createable over the standard data API** (`createable:true`)
+  with just `Name` + `Label`. Create `Agent_Access` with a POST to
+  `/sobjects/PermissionSet` — no Tooling API, no Metadata XML, no deploy.
+- **`SetupEntityAccess` is createable** with `ParentId` + `SetupEntityId`
+  (both required, both `createable:true`).
+- **`SetupEntityType` is NOT createable** (`createable:false`, picklist). It is
+  derived from the `SetupEntityId` key prefix (`0Xx` → `BotDefinition`). Sending
+  it in the POST body errors — omit it. It IS filterable on the read, so the
+  idempotency query uses `WHERE ... AND SetupEntityType='BotDefinition'`.
+- `SetupEntityAccess` is **not updateable** — grants are add/remove only, so the
+  idempotent path is "read existing grants, add the missing ones".
+
+### Activated-agent discovery query (Phase 1)
+
+Only agents with an **active** version should be offered — a draft/inactive
+agent has nothing to exercise yet:
+
+```sql
+SELECT Id, DeveloperName, MasterLabel,
+       (SELECT Status FROM BotVersions WHERE Status='Active')
+FROM BotDefinition
+WHERE Type='InternalCopilot'
+```
+
+An agent is activated iff its `BotVersions` child subquery returns ≥1 row.
+
+## Codesearch / verification note
+
+The feature-permset matrix and the `SetupEntityAccess`/`BotDefinition` mechanism
+were verified live. The Unified Catalog **user** tier was corrected from
+`UnifiedCatalogAgent` to `UnifiedCatalogCommunityUser` after the shipped
+`PermissionSet.Description` fields showed `UnifiedCatalogAgent` is the agent's own
+bot-runtime permset ("Enables the agent to run service process"), while
+`UnifiedCatalogCommunityUser` is the human run tier ("Enables the Community User
+to run unified catalog service process"). If the shipped permset Names, their
+`Description`, or the `SetupEntityAccess` create-field set drift on a future
+release, re-verify with `sf sobject describe --sobject SetupEntityAccess` and
+`SELECT Name, Label, Description, LicenseId FROM PermissionSet WHERE Name LIKE 'UnifiedCatalog%'`
+before changing the fixed lists in `scripts/`.