@salesforce/afv-skills 1.40.0 → 1.41.0

package/skills/service-itsm-agentic-setup-fulfiller-agent-configure/references/action-availability.md

@@ -0,0 +1,51 @@
+# Action-availability preflight + activate-result classification
+
+The Fulfiller template's Agent Script references `svc_itsm_intelligence__*` invocable actions via `source:` and `target: generatePromptResponse://...`. `activate` returns **HTTP 200** with `{success:false, messages:[{... "does not exist"}]}` (silent-failure body) when any referenced action isn't surfaced for the running user by `/actions/custom/generatePromptResponse`. Two helpers catch this — one before the write, one after.
+
+## Phase 2c — `scripts/classify-action-availability.mjs`
+
+Called on the **create path only** — after Phase 2 (idempotency) returns `exists:false`, and before Phase 3 (confirm-to-write). An already-existing **Active** agent (ALREADY-CREATED) skips this gate entirely: its actions are already wired, so re-checking availability would wrongly park a no-op run. A reactivation (Phase 2b) relies on the activate-result classifier below rather than this preflight. Reads:
+- `/tmp/agent-templates.json` (Phase-1 capture — the decoded template `agentScript` is the source of truth for the referenced actions).
+- `/tmp/generate-prompt-response.json` — a fresh GET of `/services/data/v67.0/actions/custom/generatePromptResponse` (the two response shapes are `{actions:[{name,...}]}` and `{actions:{<name>:{...}}}`; the classifier handles both).
+
+Invocation:
+
+```bash
+sf api request rest "/services/data/v67.0/actions/custom/generatePromptResponse" \
+  --method GET --target-org <alias> > /tmp/generate-prompt-response.json 2>/tmp/generate-prompt-response.err || true
+node "<skill_dir>/scripts/classify-action-availability.mjs" \
+  /tmp/agent-templates.json "IT Service Fulfiller" /tmp/generate-prompt-response.json
+```
+
+Emits `{ referenced, present, missing, verdict, reasons }`. Branching:
+
+| verdict | Meaning | Caller action |
+|---|---|---|
+| `READY` | `missing.length === 0` | Continue to Phase 3 (confirm-to-write) |
+| `NOT-READY` | ≥1 referenced action absent from `generatePromptResponse` | Offer permset hand-off (below) — no writes |
+| `CANNOT-CONFIRM` | `generatePromptResponse` returned an unexpected shape | Surface reasons; proceed with caution — Phase 6 activate-result will catch a silent-failure body |
+
+**Hand-off wording on `NOT-READY`** (via `AskUserQuestion`):
+
+> "`missing.length` invocable action(s) referenced by the Fulfiller template are not available on this org for your user (e.g. `<first 3 of missing>`). Run `service-itsm-agentic-setup-itsm-agentforce-permset-assign` to assign the ITSM Intelligence permission set (if installed) or to route you to the content-bundle step (if the package isn't installed)?" (options: **Yes, resolve action availability** / **No, stop here**)
+
+- On **Yes**: delegate to `service-itsm-agentic-setup-itsm-agentforce-permset-assign`, then re-run Phase 2c.
+- On **No**: stop and report missing actions verbatim — no writes.
+
+## Phase 2b / Phase 6 — `scripts/classify-activate-result.mjs`
+
+Called on both the create-path activate (`POST /nextgen-authoring/bundle-versions/<id>/activate`) and the reactivation activate (`POST /connect/bot-versions/<id>/activation`). Reads the response body captured to a file. Emits `{ verdict, success, isActivated, messages, reasons }`.
+
+| Body shape | verdict | Handling |
+|---|---|---|
+| empty stdout | `PASS` | Documented success — fall through to Phase 7 verify |
+| `{"success":true, ...}` | `PASS` | Fall through to Phase 7 verify |
+| `{"success":false, "messages":[...]}` | `FAIL` | Do NOT report CREATED — surface `messages[]` verbatim; if a message names a missing invocable action, offer the same Phase-2c hand-off (`service-itsm-agentic-setup-itsm-agentforce-permset-assign`) |
+| Connect error array `[{errorCode, message}]` | `FAIL` | Surface verbatim and stop |
+| Unparseable body | `CANNOT-CONFIRM` | Fall through to Phase 7 SOQL verify — let it decide |
+
+The classifier's "does the message name a missing invocable action" test matches `/does not exist|not found|no such action|invocable action/i`.
+
+## Why both phases exist
+
+Phase 2c catches the failure **before** create+publish+activate — expensive to unwind after the bundle exists. Phase 6/2b is the belt-and-braces: on rare org state changes between Phase 2c and the activate call (permset revoked mid-flow), the activate body is the only surviving signal that Phase 2c's verdict is stale. Never trust HTTP 200 alone on activate.

package/skills/service-itsm-agentic-setup-fulfiller-agent-configure/references/cli-invocation.md

@@ -0,0 +1,345 @@
+# CLI invocation reference — Create the IT Service Fulfiller Agent
+
+This skill uses the **Salesforce CLI (`sf`)** as its only transport:
+`sf api request rest` for the NGA Connect API reads/writes, `sf data query` for the
+`BotDefinition` idempotency + verify SOQL, and two Node helper scripts for the
+deterministic decisions. It extracts no access tokens.
+
+The agent is created as a **Next-Gen Authoring (NGA) native agent** via the
+`/nextgen-authoring/*` Connect API — **not** via the legacy
+`/connect/service-itsm/createAgent` route. That legacy route creates a
+Setup-page bot that shows an external-link icon in Agentforce Studio and is
+also listed on the old Setup > Agentforce Agents page; the NGA bundle pipeline
+below produces an agent that is native to Agentforce Studio's Agents list with
+no external-link icon, matching the platform's own "IT Service Employee Agent".
+
+## Why `sf api request rest` / `sf data query`, never curl + token
+
+Both commands authenticate using the CLI's stored session for the
+`--target-org` alias — the CLI mints/refreshes the token internally and never
+exposes it. **Do not** do:
+
+<!-- skill-validate: ignore -->
+```bash
+# FORBIDDEN — leaks a bearer token into shell context, bypasses the CLI session
+TOKEN=$(sf org display --json -o <alias> | jq -r '.result.accessToken')
+curl -X POST -H "Authorization: Bearer $TOKEN" .../nextgen-authoring/bundles
+```
+
+Every call this skill makes is a plain `/services/data/v67.0/...` Connect API or
+`/query` path — exactly what `sf api request rest` and `sf data query` proxy.
+There is no reason to fall back to curl.
+
+## Target org, API version, and the `--json` split
+
+- **Target org**: always `--target-org <alias>` (or `-o <alias>`). Resolve the
+  alias from the user or the default org (`sf config get target-org`).
+- **API version**: pinned in the URL path (`/services/data/v67.0/...`). Do not
+  hand-edit it below `metadata.minApiVersion` (`67.0`).
+- **`--json` rule** — the two commands differ:
+  - `sf api request rest` prints the **raw** Connect response body to stdout;
+    do **not** add `--json` (it is unsupported on some Connect endpoints and
+    errors). The stdout body is already JSON.
+  - `sf data query --json` **does** wrap results in a `{status, result:{records[]}}`
+    envelope — that envelope is exactly what `scripts/classify-agent-existence.mjs`
+    expects. Always pass `--json` to `sf data query`.
+
+## Thread the collected developerName / label through the create body
+
+The `<developerName>` and `<label>` are collected from the user (defaults
+`IT_Service_Fulfiller_Agent` / `IT Service Fulfiller Agent`). The **same**
+`<developerName>` must appear in the `createBundleWithVersion` body's outer
+`apiName` AND its `resourceContent`'s internal `config.developer_name` —
+otherwise the bundle's outer identity diverges from the script's internal
+identity. The idempotency and verify reads do **not** key on `<developerName>`:
+they query `BotDefinition` by the template's `botDefinitionId` (idempotency) or
+the publish response's `publishedBotId` (verify) — see the Enumerate/Verify
+sections below for why an Id-keyed read is the only reliable guard.
+
+## The source content — the legacy template's `agentScript` field
+
+The legacy `agent-templates` read (still used, read-only) returns each
+template's full **Agent Script** (AFScript) in an `agentScript` field,
+HTML-entity-encoded (sometimes double-encoded). This is the SAME content
+format an NGA bundle version's `resourceContent` expects — there is no
+separate "NGA template catalog" endpoint; the fix simply routes this existing
+read's content into the NGA bundle pipeline instead of the legacy
+`createAgent` call.
+
+```text
+GET /services/data/v67.0/connect/service-itsm/agent-templates?agentType=AgentforceEmployeeAgent
+```
+
+Response: `{data:[{id, masterLabel, agentScript, isInstalled, isActivated, botDefinitionId, ...}]}`.
+The classifier (`scripts/classify-preflight.mjs`) finds the item whose
+`masterLabel` matches `"IT Service Fulfiller"` and confirms `agentScript` is a
+non-empty string. `scripts/build-create-body.mjs` re-reads the same captured
+file, re-locates the match, and does the actual decode + substitution (see
+below) — the classifier only confirms presence, it does not re-emit the ~70KB
+script content on stdout.
+
+## The NGA Connect API
+
+All three calls live under `/nextgen-authoring/`, owning team **Agentforce
+Platform**. Org access check: `NextGenAuthoring.orgHasNextGenAgentAuthoringEnabled
+&& NextGenAuthoring.userCanAccessNextGenAgentAuthoring`. User access check:
+`NextGenAuthoring.userCanAccessAuthoringBundle` (create) /
+`NextGenAuthoring.userCanEditAuthoringBundle` (publish/activate).
+
+| Route | Method | Purpose |
+|-------|--------|---------|
+| `/services/data/v67.0/nextgen-authoring/bundles` | POST | `createBundleWithVersion` — create the bundle + its first DRAFT version from an Agent Script |
+| `/services/data/v67.0/nextgen-authoring/bundle-versions/{bundleVersionId}/publish` | POST | `publishBundleVersion` — publish the version, creating the underlying `BotDefinition`/`BotVersion` |
+| `/services/data/v67.0/nextgen-authoring/bundle-versions/{bundleVersionId}/activate` | POST | `activateBundleVersion` — activate the published version |
+| `/services/data/v67.0/nextgen-authoring/bundles` | GET | List bundles (optional post-hoc check for `isLegacy:false`) |
+
+> **The legacy `createAgent` / `create-agents` / `activate-agents` routes under
+> `/connect/service-itsm/` are NOT part of this flow.** They create a
+> Setup-page bot with an external-link icon in Agentforce Studio — the wrong
+> kind of agent. Do not fall back to them even on an NGA-route error; surface
+> the error and stop instead.
+
+## Preflight — Studio access + template's Agent Script presence (one classifier)
+
+Capture both reads, then let `scripts/classify-preflight.mjs` make the
+deterministic decisions (do not read `hasAccess` or search `data[]` in prose — A9):
+
+```bash
+sf api request rest "/services/data/v67.0/agentforce-studio/access/Agents" \
+  --method GET --target-org <alias> > ${SCRATCH_DIR}/studio-access.json 2>${SCRATCH_DIR}/studio-access.err || true
+sf api request rest "/services/data/v67.0/connect/service-itsm/agent-templates?agentType=AgentforceEmployeeAgent" \
+  --method GET --target-org <alias> > ${SCRATCH_DIR}/agent-templates.json 2>${SCRATCH_DIR}/agent-templates.err || true
+node "<skill_dir>/scripts/classify-preflight.mjs" ${SCRATCH_DIR}/studio-access.json ${SCRATCH_DIR}/agent-templates.json "IT Service Fulfiller"
+```
+
+**Studio access** body: `{ "hasAccess": true, "productName": "Agents" }`. The
+classifier maps `hasAccess=true`→PASS, `false`→FAIL (offer the hand-off to
+`service-itsm-agentic-setup-agentforce-studio-validate`), a **confirmed** `404`
+(gate not wired, expected on scratch orgs)→CANNOT-CONFIRM (does not block — a
+successful create/publish/activate is authoritative), and any other parseable
+error body (`401`/`403`/unexpected)→**ERROR** (surface the raw response and
+stop — do not treat an auth/permission failure as an unwired gate). The
+product in the path must be `Agents` (any other value ⇒ `400 Invalid product name`).
+
+**agent-templates**: the `agentType` query param is **required** — omitting it
+returns `400 MISSING_ARGUMENT: agentType`; the value is `AgentforceEmployeeAgent`
+(a wrong value returns an empty `data[]`). The classifier finds the item whose
+`masterLabel` matches the label arg ("IT Service Fulfiller") and confirms its
+`agentScript` field is a non-empty string — that field, not `id`, is what
+Phase 4 consumes. Empty/no-match `data[]` ⇒ `template.signal=FAIL`; a `404` ⇒
+CANNOT-CONFIRM — hand off to the readiness check; a match with no/empty
+`agentScript` ⇒ CANNOT-CONFIRM (nothing to build the NGA bundle from).
+
+Classifier output:
+
+```json
+{
+  "studio":   { "hasAccess": true, "signal": "PASS|FAIL|CANNOT-CONFIRM|ERROR", "reason": "..." },
+  "template": { "present": true, "id": "svc_itsm_intelligence__ITSrvcMgmtFulfiller", "hasAgentScript": true, "botDefinitionId": "0Xx...", "signal": "PASS|FAIL|CANNOT-CONFIRM", "reason": "..." },
+  "verdict": "READY | NOT-READY | CANNOT-CONFIRM | ERROR",
+  "reasons": ["..."]
+}
+```
+
+`template.botDefinitionId` is copied from the matched `agent-templates` row. **`botDefinitionId` is the PRIMARY Phase-2 idempotency key**, but the Fulfiller is never pre-provisioned and this skill's create path never stamps `templateName`, so its template `botDefinitionId` is `null` on every run — the collected `<developerName>` is therefore the guard that actually protects repeat runs. Carry `<developerName>` into the Phase-2 read as the fallback key. (`isInstalled`/`isActivated` are no longer emitted: they ride the same AgentTemplate join as `botDefinitionId`, so they read false for self-created agents and nothing consumes them.)
+
+`verdict=ERROR` (`studio.signal="ERROR"` — a parseable non-404 Studio-access
+error, e.g. `401`/`403`) ⇒ surface the raw error and stop; takes priority over
+template state so a present template cannot outrun a failed prerequisite read.
+`verdict=NOT-READY` (studio FAIL or template FAIL) ⇒ hand off / stop.
+`verdict=READY` ⇒ proceed to Phase 2. It exits `0` on usable args.
+
+## Enumerate the existing agent — SOQL on `BotDefinition` BY Id (falling back to DeveloperName)
+
+Idempotency is keyed **PRIMARILY** on the template's `botDefinitionId` (from the
+Phase-1 row) and **FALLS BACK** to the collected `<developerName>`. If the
+Fulfiller agent already exists under a `DeveloperName` that differs from this
+skill's default guess `IT_Service_Fulfiller_Agent`, a name-only read
+false-negatives (`exists:false`) and the create then collides on `apiName` with
+`DUPLICATE_VALUE`. `botDefinitionId` is the platform's authoritative link from
+the template to the `BotDefinition` it was instantiated into — but it is
+back-filled onto the template row **only** for pre-provisioned agents, and the
+Fulfiller is never pre-provisioned: this skill's create path never stamps
+`templateName`, so its template `botDefinitionId` stays `null` on the first run
+and every run after. The `DeveloperName`-keyed fallback is therefore the guard
+that actually protects repeat runs here — never short-circuit straight to create
+when `botDefinitionId` is absent.
+
+- **`botDefinitionId` empty/null** (the normal Fulfiller case — template row
+  never joined) ⇒ fall back to a DeveloperName-keyed read and let the classifier
+  match on it:
+  ```bash
+  sf data query -q "SELECT Id,DeveloperName,MasterLabel,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE DeveloperName='<developerName>'" \
+    --target-org <alias> --json > ${SCRATCH_DIR}/bot-existing.json 2>${SCRATCH_DIR}/bot-existing.err || true
+  node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "" "<developerName>"
+  ```
+- **`botDefinitionId` present** (a pre-provisioned instantiation, if any — never
+  the normal Fulfiller case) ⇒ read the `BotDefinition` by Id **`OR` by the
+  collected `<developerName>`** in one query, then classify. The `OR DeveloperName=`
+  clause catches a **dangling** link — a `botDefinitionId` whose target row was
+  since deleted: the by-Id half returns nothing, the live same-name agent still
+  surfaces, and the classifier falls back to it (`matchedBy:"developerName"`)
+  rather than concluding `exists:false` and colliding with `DUPLICATE_VALUE`:
+  ```bash
+  sf data query -q "SELECT Id,DeveloperName,MasterLabel,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'" \
+    --target-org <alias> --json > ${SCRATCH_DIR}/bot-existing.json 2>${SCRATCH_DIR}/bot-existing.err || true
+  node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId>" "<developerName>"
+  ```
+
+Only when **both** `botDefinitionId` and `<developerName>` are absent does the
+classifier return `exists:false` without reading a query file — in practice the
+collected `<developerName>` is always present, so the fallback read always runs.
+
+The `BotVersions` subquery (child relationship on `BotDefinition`) is what lets
+the classifier see the latest version's `Status` — omit it and
+`latestVersionStatus`/`needsActivation` come back `null`/`false` even when the
+existing agent is actually inactive. The classifier prints
+`{ exists, count, matchedBy, agentId, botDefinitionId, developerName, latestVersionId, latestVersionStatus, needsActivation }`
+(`matchedBy` is `"botDefinitionId"` | `"developerName"` | `null`; `developerName`
+is the ACTUAL live agent's DeveloperName read from the record — surface it in the
+report instead of the collected guess):
+- `exists:false` ⇒ proceed to create.
+- `exists:true` and `needsActivation:false` (latest version `Active`) ⇒
+  **ALREADY-CREATED** (skip the entire create/publish/activate sequence).
+- `exists:true` and `needsActivation:true` (latest version `Inactive`) ⇒ do
+  **not** create a duplicate — take the reactivation path documented in
+  `references/reactivation.md` (direct `BotVersion` activation, skips
+  create + publish).
+- **Exit 3** ⇒ the query itself failed (auth error, malformed SOQL) — surface
+  the raw CLI error and stop; do **not** assume the agent is absent.
+
+Any existing-agent hit here is a `matchedBy:"developerName"` fallback (the
+Fulfiller's template `botDefinitionId` is always `null`), so Phase 7 verifies the
+agent using the classifier's returned live `agentId` / `botDefinitionId` — the
+actual matched `BotDefinition.Id` — **never** the Phase-1 template
+`botDefinitionId`, so the verify read never degrades to `WHERE Id=''` and never
+false-fails after a successful skip or reactivation.
+
+Use the skill's **absolute** `<skill_dir>` in the `node` invocation — a bare
+`./scripts/...` resolves against the shell CWD, not the skill dir.
+
+## Create the NGA bundle — `createBundleWithVersion`
+
+```bash
+node "<skill_dir>/scripts/build-create-body.mjs" ${SCRATCH_DIR}/agent-templates.json "IT Service Fulfiller" "<developerName>" "<label>" ${SCRATCH_DIR}/create-bundle-body.json
+sf api request rest "/services/data/v67.0/nextgen-authoring/bundles" \
+  --method POST \
+  --body @${SCRATCH_DIR}/create-bundle-body.json \
+  --target-org <alias> > ${SCRATCH_DIR}/create-bundle.json 2>${SCRATCH_DIR}/create-bundle.err || true
+```
+
+`build-create-body.mjs` re-reads `${SCRATCH_DIR}/agent-templates.json` (the SAME file
+captured in Phase 1), re-locates the item whose `masterLabel` matches
+`"IT Service Fulfiller"`, and:
+1. Fully HTML-decodes its `agentScript` — named entities (`&amp;`, `&quot;`,
+   `&#39;`, `&lt;`, `&gt;`) AND numeric entities (`&#(\d+);` →
+   `String.fromCharCode`), applied in a loop (up to 4 passes) to fully unwind
+   double-encoding. A naive single-pass decode leaves artifacts (e.g.
+   `&amp;quot;`, an undecoded `&#92;` for a literal backslash) that break
+   AFScript parsing.
+2. Substitutes the script's `config.developer_name` / `config.agent_label`
+   with the collected `<developerName>` / `<label>` via a regex replace on the
+   `developer_name: "..."` / `agent_label: "..."` lines. If either
+   substitution doesn't land (pattern not found), the script exits 3 rather
+   than silently building a body with the wrong internal identity.
+3. Writes `{ apiName: <developerName>, label: <label>, assets: [{ resourceName:
+   "agentDefinition", resourceType: "agentDefinition", sections: [],
+   resourceContent: <decoded+substituted script> }] }` to the output path.
+
+Response on success — a bundle-version detail:
+
+```json
+{
+  "apiName": "IT_Service_Fulfiller_Agent",
+  "label": "IT Service Fulfiller Agent",
+  "bundleId": "1bY...",
+  "id": "1bZ...",
+  "versionStatus": "DRAFT",
+  "assets": [ { "resourceName": "agentDefinition", "resourceType": "agentDefinition", "resourceContent": "...", "sections": [] } ],
+  "publishedBotId": null,
+  "publishedBotVersionId": null
+}
+```
+
+**Capture `id` — that is the `bundleVersionId`** used in the publish/activate
+calls below. `bundleId` is the bundle's own Id, not the version's; passing it
+to `/bundle-versions/{...}` returns a 404.
+
+Common errors:
+
+| HTTP | Error code | Meaning | Action |
+|------|-----------|---------|--------|
+| 403 / 404 | `FUNCTIONALITY_NOT_ENABLED` / not found | NGA authoring namespace not provisioned on the org | Trigger the Phase-1 hand-off — `AskUserQuestion` → on Yes delegate to `service-itsm-agentic-setup-agentforce-studio-validate` |
+| (script exit 3) | — | `build-create-body.mjs` couldn't find the template / its `agentScript` / couldn't substitute developer_name or agent_label in `${SCRATCH_DIR}/agent-templates.json` | Surface the script's stderr verbatim; re-verify Phase 1's `template.hasAgentScript:true` rather than hand-typing a body |
+
+## Publish the bundle version — `publishBundleVersion`
+
+```bash
+sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/publish" \
+  --method POST --body '{}' \
+  --target-org <alias> > ${SCRATCH_DIR}/publish-bundle.json 2>${SCRATCH_DIR}/publish-bundle.err || true
+```
+
+Path param only — the body is ignored by the endpoint but `--body '{}'` is
+still required (see Gotchas). Response on success:
+
+```json
+{ "lastPublishedOn": "2026-08-05T01:22:54.278Z", "publishedBotId": "0Xx...", "publishedBotVersionId": "0X9..." }
+```
+
+This is the call that creates the underlying `BotDefinition`/`BotVersion`. An
+error here means the DRAFT version failed platform-side validation.
+
+## Activate the bundle version — `activateBundleVersion`
+
+```bash
+sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/activate" \
+  --method POST --body '{}' \
+  --target-org <alias> > ${SCRATCH_DIR}/activate-bundle.json 2>${SCRATCH_DIR}/activate-bundle.err || true
+```
+
+Success returns an **empty response body** (`EmptyRepresentation`) — do not
+treat empty stdout as a failure signal. Check the CLI exit code, then confirm
+success via the Phase-7 `BotDefinition`/`BotVersion` verify read, not by
+parsing this call's output.
+
+## Verify the agent is live — SOQL on `BotDefinition` BY Id
+
+```bash
+sf data query -q "SELECT Id,DeveloperName,MasterLabel,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<verifyId>'" \
+  --target-org <alias> --json > ${SCRATCH_DIR}/bot-verify.json 2>${SCRATCH_DIR}/bot-verify.err || true
+node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-verify.json "<verifyId>"
+```
+
+The verify `<verifyId>` is the create path's **`publishedBotId`** (captured from
+the Phase-5 publish response) or, on the ALREADY-CREATED / reactivation path, the
+**live matched Id the Phase-2 classifier returned** (its `botDefinitionId` /
+`agentId` output — the actual `BotDefinition.Id` of the matched record) — **not**
+the Phase-1 template `botDefinitionId`, which is always `null` for the Fulfiller,
+so on any existing-agent hit (always a `matchedBy:"developerName"` fallback)
+using it would run the verify as `WHERE Id=''` and falsely report failure after a
+successful skip/activation. Never the collected `<developerName>`.
+Confirm `exists:true` with `count:1`, and — whether the create or the
+reactivation path was taken — `latestVersionStatus:"Active"`. `exists:false`
+after a successful activate ⇒ report the discrepancy verbatim, do not fabricate
+success. Optionally cross-check
+`GET /services/data/v67.0/nextgen-authoring/bundles` for an entry with
+`apiName=<developerName>` and `isLegacy:false` — this is the same shape as the
+platform's own "IT Service Employee Agent" entry and confirms the created
+agent is NGA-native (no external-link icon in Agentforce Studio).
+
+## Idempotency semantics
+
+The full `ALREADY-CREATED` / `ACTIVATED` / `CREATED` verdict table (Phase-2
+classifier signal → verdict) — plus the note on how the Phase-2 SOQL read turns
+the server's `DeveloperName`-keyed duplicate rejection into a graceful skip —
+lives in `references/reactivation.md`.
+
+## Errors and gotchas
+
+The response-body error codes each phase can return (auth,
+`FUNCTIONALITY_NOT_ENABLED`, missing `agentType`, build-script exit codes,
+empty-response semantics) and the recurring foot-guns (legacy-`createAgent`,
+`--body '{}'`, `bundleId` vs `bundleVersionId`, multi-pass HTML decode,
+threading the collected `<developerName>`, token+curl, …) live in
+`references/error-taxonomy.md`.

package/skills/service-itsm-agentic-setup-fulfiller-agent-configure/references/error-taxonomy.md

@@ -0,0 +1,44 @@
+# Error taxonomy and gotchas — Create the IT Service Fulfiller Agent
+
+Split from `references/cli-invocation.md` — that file documents the per-phase
+CLI call shapes and the classifier contracts; this file collects the errors
+those calls can return and the recurring foot-guns.
+
+## Error taxonomy
+
+- **Auth error / `401 Unauthorized`** — the org session is expired or the alias
+  is wrong. Re-run `sf org login web` for the target org; there is no token to
+  refresh by hand.
+- **`401`/`403`/unexpected error body on the Phase-1 Studio-access read** — the
+  preflight classifier maps this to `studio.signal="ERROR"` / `verdict="ERROR"`
+  (distinct from a confirmed 404 gate). Surface the raw response and stop —
+  do not proceed to Phase 2 even if the template read succeeded.
+- **`403`/`404` on `createBundleWithVersion` / `publish` / `activate`** — the
+  NGA authoring namespace isn't provisioned or enabled on the org. Trigger the
+  Phase-1 hand-off offer.
+- **`400 MISSING_ARGUMENT: agentType`** on `agent-templates` — the required
+  `agentType` query param was omitted; pass `AgentforceEmployeeAgent`.
+- **Build-script exit 3** — the template, its `agentScript`, or a successful
+  `developer_name`/`agent_label` substitution wasn't found in the captured
+  `agent-templates.json`; surface stderr, don't hand-author a body.
+- **Classifier exit 3** on a `sf data query` read — the SOQL query failed
+  (auth/malformed); surface the raw CLI error, do not treat as NOT-EXISTS.
+- **Empty stdout from `activate`** — this is the SUCCESS response
+  (`EmptyRepresentation`), not a failure; confirm via the Phase-7 verify SOQL.
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| Legacy `createAgent` produces the wrong kind of agent | Never call `/connect/service-itsm/createAgent` — it creates a Setup-page bot with an external-link icon in Agentforce Studio. Use the three `/nextgen-authoring/*` calls in `references/cli-invocation.md` |
+| `sf api request rest --method POST` with no `--body` flag | Fails with `No 'mode' found in 'body' entry`, even for `publish`/`activate` which ignore the body — always pass `--body '{}'` explicitly |
+| `sf api request rest --json` errors | Don't pass `--json` there — the raw stdout body is already JSON. `--json` is for `sf data query` (which needs the `.result.records[]` envelope) |
+| Confusing `bundleId` with `bundleVersionId` | The `createBundleWithVersion` response's `id` field is the bundle **version** Id used in publish/activate; `bundleId` is the parent bundle's Id and 404s if passed to `/bundle-versions/{...}` |
+| Naive single-pass HTML-entity decode leaves compile errors | `"` (double-encoded) and `\` (numeric, backslash) require a multi-pass decode covering both named and numeric entities — see `build-create-body.mjs` |
+| Bundle's outer `apiName` diverging from the script's internal `config.developer_name` | Always substitute both via `build-create-body.mjs` before the create call — a divergence is exactly the kind of mismatch that produces confusing platform behavior |
+| Hardcoding `IT_Service_Fulfiller_Agent` in one call but collecting it in another | Thread the collected `<developerName>` through the idempotency SOQL, the bundle body (outer + internal), AND the verify SOQL — a mismatch creates the wrong agent |
+| Bare `./scripts/classify-agent-existence.mjs` "not found" | Use the skill's absolute `<skill_dir>` in the `node` invocation |
+| `agent-templates` → `400 MISSING_ARGUMENT: agentType` | The `agentType` query param is required — pass `AgentforceEmployeeAgent` |
+| `agent-templates` returns empty `data[]` | Wrong `agentType` value — use `AgentforceEmployeeAgent`; empty results are not the same as "not provisioned" |
+| Treating `activate`'s empty response as a failure | It's the documented success response (`EmptyRepresentation`) — verify via the Phase-7 SOQL instead of parsing this call's stdout |
+| Tempted to token+curl for any of the three writes | Never — `sf api request rest --method POST --body @<file>` (or `--body '{}'`) handles auth for `/services/data/...` writes; token extraction is forbidden |

package/skills/service-itsm-agentic-setup-fulfiller-agent-configure/references/reactivation.md

@@ -0,0 +1,63 @@
+# Reactivation path — activating an existing inactive IT Service Fulfiller Agent
+
+Split from `references/cli-invocation.md` — this file documents the direct
+`BotVersion` activation call used when the Phase-2 classifier reports the agent
+already exists but its latest version is `Inactive`. `cli-invocation.md` covers
+the create/publish/activate happy path; this file covers "skip create/publish,
+just reactivate what's already there".
+
+## When this path fires
+
+`scripts/classify-agent-existence.mjs` (called with the template's
+`botDefinitionId` as the PRIMARY idempotency key and the collected
+`DeveloperName` as the FALLBACK — see `cli-invocation.md` → "Enumerate the
+existing agent") returns
+`{ exists:true, needsActivation:true, latestVersionId, latestVersionStatus:"Inactive" }`.
+That means a `BotDefinition` matching the collected `DeveloperName` (the
+Fulfiller's template `botDefinitionId` is null, so the fallback is what matches)
+already exists from a prior run of this skill but its most-recent `BotVersion` is
+inactive; creating a new bundle would produce a duplicate. Instead, flip the
+existing version to `Active`.
+
+## Activate an existing inactive version — `POST /connect/bot-versions/{id}/activation`
+
+```bash
+sf api request rest "/services/data/v67.0/connect/bot-versions/<latestVersionId>/activation" \
+  --method POST --body '{"status":"Active"}' \
+  --target-org <alias> > ${SCRATCH_DIR}/activate-existing.json 2>${SCRATCH_DIR}/activate-existing.err || true
+```
+
+`<latestVersionId>` is the captured `latestVersionId` from the Phase-2
+classifier output — **not** a bundle version id. This is a direct
+`BotVersion` activation toggle that bypasses the NGA bundle pipeline entirely,
+because the `BotDefinition`/`BotVersion` records already exist. Skips create
+(Phase 4) and publish (Phase 5) — go straight to activate, then verify.
+
+## Verify — same SOQL as the happy path
+
+Run the Phase-7 verify read (see `cli-invocation.md` → "Verify the agent is
+live"). Confirm `exists:true` with `count:1` **and**
+`latestVersionStatus:"Active"`. If `latestVersionStatus` is still `Inactive`
+after a successful activation call, report the discrepancy verbatim — do not
+fabricate success.
+
+## Idempotency semantics
+
+| Signal | Verdict |
+|--------|---------|
+| Neither the template's `botDefinitionId` nor the collected `DeveloperName` matches a live `BotDefinition` — classifier returns `exists:false` | proceed to CREATE |
+| Phase-2 classifier returns `exists:true` and `needsActivation:false` (latest version `Active`), matched by `botDefinitionId` or the `DeveloperName` fallback | ALREADY-CREATED (skip create/publish/activate entirely) |
+| Phase-2 classifier returns `exists:true` and `needsActivation:true` (latest version `Inactive`), user confirms reactivation, and the bot-version activation call succeeds | ACTIVATED (skip create/publish entirely — direct `BotVersion` activation only) |
+| `createBundleWithVersion` → `publish` → `activate` all succeed and Phase-7 classifier (keyed on the publish `publishedBotId`) confirms `exists:true` with `latestVersionStatus:"Active"` | CREATED |
+
+The server-side create path **does** reject a duplicate, but keyed on
+`DeveloperName`, not `apiName`: a pre-validation lookup
+(`lookupBotDefinitionIdByDeveloperName`) plus a publish-time `BotDefinition`
+DeveloperName unique-constraint catch that cleans up the orphaned bundle version.
+That guard fires when the `DeveloperName` being created already exists, so it
+catches a repeat run of this skill — but only as a hard error. The Phase-2 read
+is what makes the repeat graceful: because the Fulfiller is never pre-provisioned
+and this skill's create path never stamps `templateName`, the template's
+`botDefinitionId` is always `null`, so the read falls back to the collected
+`DeveloperName` to detect the existing agent and offer ALREADY-CREATED /
+reactivation instead of letting the create call fail with `DUPLICATE_VALUE`.

package/skills/service-itsm-agentic-setup-fulfiller-agent-configure/references/report-format.md

@@ -0,0 +1,44 @@
+# Report Format — Fulfiller Agent Create & Activate
+
+The report layout is generated deterministically by `scripts/render-report.mjs` — the single source of report text for both the chat-turn response and the harness's `${outputDir}/report.md` file, so the two never diverge. Never hand-compose the layout, field placement, stage rows, or next-step wording in prose (authoring standard A9); always shell out to the helper.
+
+## Rendered shape
+
+```text
+# Fulfiller Agent — Create & Activate
+
+IT Service Fulfiller Agent Creation (via service-itsm-agentic-setup-fulfiller-agent-configure)
+
+Org:      <org-alias> (API v67.0)
+Agent:    <developerName> ("<label>") — NGA-native bundle
+
+  Preflight  ......................... Studio hasAccess=<true|false|cannot-confirm>; template agentScript present=<yes|no>
+  Enumerate  ......................... target agent exists before write=<yes|no>; latest version status=<Active|Inactive|n/a>
+  Confirm-to-write ................... user-confirmed=<true|false>
+  Create bundle ...................... <bundleVersionId=... | ALREADY-CREATED | skipped (reactivation path) | pending confirmation | skipped | FAILED>
+  Publish ............................ <publishedBotId=... | skipped | pending confirmation | FAILED>
+  Activate ........................... <succeeded (created) | succeeded (reactivated existing) | skipped | pending confirmation | FAILED>
+  Verify ............................. <BotDefinition present: yes|no; latest version Active: yes|no | skipped | pending>
+
+Verdict: CREATED | ALREADY-CREATED | ACTIVATED | PENDING CONFIRMATION | DECLINED | FAILED
+Reason:  <plain-language explanation naming the atomicity constraint, the idempotency decision, and any decline/skip reasoning — the caller populates this before invoking the helper, so it can be as rubric-facing as the situation warrants without repeating raw API calls>
+
+Next steps:
+  - <helper-generated line keyed off the verdict>
+```
+
+The helper enforces a validated verdict set and picks the `Next steps` line from the verdict, so the file never drifts from that shape.
+
+## Checkpoint writes (harness / non-interactive runs)
+
+When `${outputDir}` is provided (via the harness's generated-file location directive), invoke the helper at three checkpoints so a report always exists even when a run parks at a confirmation gate:
+
+1. **Before Phase 3's confirmation gate** — verdict `PENDING CONFIRMATION` with Preflight + Enumerate rows populated; the helper marks Confirm-to-write / Create / Publish / Activate as `pending confirmation` and Verify as `skipped`. On the user's "no" at the gate, re-render with verdict `DECLINED` and a one-line `reason` naming the decline (the helper flips write rows to `skipped`).
+2. **After Phase 6 (or the Phase-2b reactivation activation)** — verdict is still not the final verdict yet; the helper is re-invoked with the create-succeeded (or reactivation-succeeded) state and Verify `pending`.
+3. **After Phase 8** — verdict `CREATED` / `ALREADY-CREATED` / `ACTIVATED` / `FAILED` with all rows filled in.
+
+Each invocation overwrites `${outputDir}/report.md`, so the last state on disk is always the most complete. Skip these writes when running interactively for a user in a chat surface — write only when `${outputDir}` was passed as an explicit destination.
+
+## Interactive runs
+
+When talking to the user in a chat surface, the assistant may still add turn-side narrative context above or below the helper output (raw command traces, error diagnostics, remediation walkthroughs, "why this is blocking" prose) — the *report* is what the helper emits, the *turn* can be as rich as the situation warrants. Only the report file has the strict shape.