@salesforce/afv-skills 1.40.0 → 1.41.0

package/skills/service-itsm-agentic-setup-cmdb-configure/SKILL.md

@@ -134,15 +134,41 @@ CMDB runs on an ITOM tenant that must reach status `PROVISIONED` (asynchronous).
    ```text
    dispatch_readonly({ "url": "/services/data/v67.0/connect/tenantProvisioningStatus", "method": "GET" })
    ```
-   - If `status` is already `PROVISIONED` → skip to Layer 2.
-2. **Trigger provisioning** (write) — only if not already provisioned/in-progress. Confirm with the
+   Branch on `status`:
+   - `PROVISIONED` → already done; skip to Layer 2 (no trigger, no poll).
+   - `UNPROVISIONED` → no job has run; go to step 2 and **trigger** it. Do **not** wait or poll on
+     this state — waiting never starts provisioning and just burns the budget.
+   - `PROVISIONING_IN_PROGRESS` → a job is already running; **skip the trigger** and go straight to
+     the poll in step 3.
+   - `FAILED` → treat as the FAILED case in step 3 (surface the reason; do not retry via API).
+2. **Trigger provisioning** (write) — only when step 1 showed `UNPROVISIONED`. Confirm with the
    user first:
    ```text
    dispatch({ "url": "/services/data/v67.0/connect/tenantProvisioningStatus", "method": "POST" })
    ```
-3. **Poll** the GET until `status == PROVISIONED`. This is async and can take several minutes. Poll
-   **every 30 seconds for up to 10 minutes** (≈20 attempts). Tell the user provisioning is in
-   progress on each poll. Exit the loop as soon as:
+   After the trigger returns, tell the user provisioning has started and **typically takes 2+
+   minutes**, so there is nothing to check yet.
+3. **Poll** the GET until `status == PROVISIONED`. This is async and reliably takes **2+ minutes**
+   (measured completion clusters right around **~2 min 40 s**), so an immediate poll is a guaranteed
+   no-op. **Anchor all timing on the response's `triggeredAt`, not on when this run started** — the
+   job may have been triggered by an earlier run (the `PROVISIONING_IN_PROGRESS` entry from step 1).
+   Parse `triggeredAt` as a UTC epoch and compute `elapsed = max(0, now − triggeredAt)` — clamp to
+   `≥ 0` so a clock skew (or a server-vs-agent timezone mismatch) can't yield a negative `elapsed`
+   (waits forever) or a false timeout. **If `triggeredAt` is missing or unparseable** (the trigger
+   POST response may not have populated it yet, or an in-progress row from an earlier run may omit
+   it), fall back to anchoring on this run's start — treat `elapsed = 0` and wait the full ~2-min
+   floor, so a branch always fires deterministically. Then:
+   - `elapsed < ~2 min` → wait until ~2 min after `triggeredAt` before the first check (skips the
+     guaranteed-useless early polls), then poll every 30 seconds.
+   - `~2 min ≤ elapsed < 10 min` → **poll immediately** (the initial wait has already passed — do not
+     wait a fresh 2 min), then every 30 seconds.
+   - `elapsed ≥ 10 min` → **do not start a fresh wait**; treat it as the timeout case below (report
+     the last-seen status and let the user decide).
+
+   The overall budget is **10 minutes from `triggeredAt`** (≈16 checks after the ~2-min floor). The
+   ~2-min floor is a floor, not an extra delay — it brackets the typical ~2:40 completion within a
+   poll or two; do not stretch it longer. Do not poll during the initial wait. Exit the loop as soon
+   as:
    - `status == PROVISIONED` → success, advance to Layer 2.
    - `status == FAILED` → stop immediately. Do NOT retry via the API — surface the failure to the
      user in plain language with three things:
@@ -158,6 +184,17 @@ CMDB runs on an ITOM tenant that must reach status `PROVISIONED` (asynchronous).
    - the 10-minute window elapses → stop, report the last-seen status, and let the user decide
      whether to keep waiting (re-run) or investigate. Never spin past the 10-minute bound.
 
+   **Polling in the background (runtime-permitting).** Provisioning is a multi-minute wait, so the
+   user should not have to sit idle. **If — and only if — the executing runtime supports backgrounded
+   work** (e.g. an agent runtime that can spawn a detached sub-agent or a scheduled wake-up), delegate
+   the wait-then-poll loop to a background task so the user can keep working, and report the outcome
+   (`PROVISIONED` / `FAILED` / timed-out) when it finishes. **If the runtime is a single-threaded turn**
+   (the ADK / Agentforce / headless-360 production path is single-threaded — a poll loop blocks the
+   conversation there), poll **inline** instead. Either way: (a) tell the user up front it takes a few
+   minutes, and (b) give a resume path — if they step away and the turn ends, they can re-run this
+   skill and Layer 1 picks up from the current status (an already `PROVISIONED` tenant skips straight
+   to Layer 2). Never *require* a background primitive the runtime may not have.
+
 ### Layer 2 — Enable the CMDB feature (this lifts the 403 gate)
 
 The feature api name is `service-cloud-itsm-cmdb-integration`.
@@ -198,7 +235,8 @@ The feature api name is `service-cloud-itsm-cmdb-integration`.
 | Read before every write; verify after every write | Tenant + feature are async/stateful; the POST response can lag the real state |
 | Confirm the target org and each write with the user | These are real, hard-to-reverse changes on a live org |
 | Do not advance past a failed or blocked layer | Later layers depend on earlier ones and will 403 |
-| Poll tenant provisioning every 30s for up to 10 min (≈20 attempts) | It is async; never spin past the 10-min bound — exit on PROVISIONED/FAILED, else report status and let the user decide |
+| Anchor poll timing on the response's `triggeredAt` (parse as UTC epoch; elapsed = max(0, now − triggeredAt)), not on this run's start; ~2-min floor before the first check, then every 30s, 10-min total budget from `triggeredAt`. If `triggeredAt` is missing/unparseable, fall back to this run's start (elapsed = 0) | Provisioning reliably takes 2+ min (measured ~2:40), so earlier polls are guaranteed no-ops. A `PROVISIONING_IN_PROGRESS` entry may have been triggered by an earlier run — if already past the ~2-min floor, poll immediately; if already past 10 min, report a timeout rather than waiting a fresh 2 min. Clamp elapsed to ≥ 0 so clock skew / timezone mismatch can't wait forever or false-timeout; the fallback keeps a branch firing when the timestamp is absent. Never spin past the 10-min bound |
+| Background the poll loop only where the runtime supports it; else poll inline — never require a background primitive | The user shouldn't sit idle for a multi-minute wait, but the production headless-360/ADK path is a single-threaded turn; a skill that mandates a background poller breaks there. Always give a re-run resume path |
 | On `FAILED`, never retry via API — decode the reason, give the Setup URL, ask for a manual retry | The API trigger has already failed; the user can retry from the CMDB provisioning Setup page, which surfaces the real error and any manual remediation |
 | Never expose internal jargon to the user | Keep record IDs, org IDs, HTTP status codes (403/500/…), API error codes (`FUNCTIONALITY_NOT_ENABLED`, …), endpoint names (`bundleListView`, `tenantProvisioningStatus`), developer names (`ITSrvcsCnfgMgmnt`, `CMDBEnabled`), and tooling internals (`dispatch`, `headless-360`) out of user-facing output. Translate to plain language; use human-readable names and statuses |
 
@@ -247,7 +285,7 @@ yet"), rather than echoing the code.
 | `403 FUNCTIONALITY_NOT_ENABLED` on CMDB reads **while feature `status != ENABLED`** | Feature not yet enabled (Layer 2 incomplete) | Finish Layer 2; the gate lifts only after the feature is ENABLED |
 | `403 FUNCTIONALITY_NOT_ENABLED` on `bundleListView` **while feature `status == ENABLED`** | Feature IS enabled; the running user lacks CMDB permission sets (`bundleListView` also enforces user-level access) | Not a Layer 2 failure — this is Layer 3; run `service-itsm-agentic-setup-cmdb-access-assign` to grant the user CMDB access |
 | Feature enable blocked (`enableBlockedReasons` non-empty) | Missing dependency the org still needs | Relay each reason; resolve those first, then retry |
-| Tenant stuck `NOT_PROVISIONED` / long-running | Provisioning is async | It can take minutes; keep polling or retry the trigger |
+| Tenant stuck `UNPROVISIONED` / `PROVISIONING_IN_PROGRESS` / long-running | Provisioning is async | It typically takes ~2–3 min; keep polling within the 10-min budget or retry the trigger |
 | Tenant `FAILED` | Provisioning job failed Salesforce-side | Share the decoded failure reason + the org's `/lightning/setup/CMDBProvisionalSettings/home` link and ask the user to retry provisioning manually there; escalate to Salesforce support only if the manual retry also fails |
 | `dispatch*` auth error | headless-360 MCP session not authenticated / token expired | Re-authenticate the headless-360 MCP connection and confirm the session points at the intended org |
 

package/skills/service-itsm-agentic-setup-cmdb-configure/references/mcp-invocation.md

@@ -83,8 +83,20 @@ user to confirm CMDB is licensed before proceeding.
 dispatch_readonly({ "url": "/services/data/v67.0/connect/tenantProvisioningStatus", "method": "GET" })
 ```
 
-Response includes `status` (e.g. `NOT_PROVISIONED`, `IN_PROGRESS`, `PROVISIONED`, `FAILED`),
-`triggeredAt`, `callbackReceivedAt`. If `status == PROVISIONED`, skip to Layer 2.
+Response includes `status` (observed values: `UNPROVISIONED`, `PROVISIONING_IN_PROGRESS`,
+`PROVISIONED`, `FAILED`), plus `triggeredAt` and `callbackReceivedAt` (the two timestamps the poll
+logic uses for elapsed-time math). Each status maps to a distinct action — **do not poll a status
+that has not been triggered:**
+
+| `status` | Meaning | Action |
+|----------|---------|--------|
+| `PROVISIONED` | Tenant already provisioned | Skip to Layer 2 — do not trigger, do not poll |
+| `UNPROVISIONED` | No provisioning job has run | **Trigger** (confirmed POST below), then poll. Never wait/poll on this state — waiting never starts the job and just burns the budget |
+| `PROVISIONING_IN_PROGRESS` | A job is already running | **Do not re-trigger** — go straight to wait/poll |
+| `FAILED` | Last job failed | Terminal — surface the reason, do not retry via API (see below) |
+
+Only `PROVISIONED` and `FAILED` are terminal. `UNPROVISIONED` requires the trigger; only
+`PROVISIONING_IN_PROGRESS` (i.e. *after* a trigger) is a "keep waiting" state.
 
 ### Trigger provisioning (write — confirm with the user first)
 
@@ -93,11 +105,38 @@ dispatch({ "url": "/services/data/v67.0/connect/tenantProvisioningStatus", "meth
 ```
 
 No request body. Response echoes the status object. Provisioning is **asynchronous** — the callback
-arrives later.
+arrives later. After the trigger, tell the user provisioning has started and typically takes **2+
+minutes**.
 
 ### Poll until PROVISIONED
 
-Re-issue the GET above **every 30 seconds for up to 10 minutes** (≈20 attempts). Exit the loop on:
+Provisioning reliably takes **2+ minutes** (measured completion on a licensed org clustered around
+**~2 min 40 s** — `callbackReceivedAt − triggeredAt`), so an immediate poll is a guaranteed no-op
+(confirmed: a re-check ~1 s after the trigger still read `PROVISIONING_IN_PROGRESS`). *Caveat: the
+~2:40 figure is a single on-org sample. It is used only as a floor — it skips guaranteed no-op polls
+and never shortens the 10-min budget, so a slower org is still handled — but re-measure it across a
+few CMDB-licensed orgs before treating it as canonical, so a naturally slower org isn't misread as
+anomalous.* **Anchor timing
+on the response's `triggeredAt`, not on when this run started** — you may enter here on a
+`PROVISIONING_IN_PROGRESS` job triggered by an earlier run, whose `triggeredAt` is already minutes
+old. Parse `triggeredAt` as a UTC epoch and compute `elapsed = max(0, now − triggeredAt)` — clamp
+to `≥ 0` so a server-vs-agent timezone mismatch or clock skew can't produce a negative `elapsed`
+(waits forever) or a false timeout. **If `triggeredAt` is missing or unparseable** (the POST
+response may not have populated it yet, or an earlier-run in-progress row may omit it), fall back to
+this run's start — treat `elapsed = 0` and serve the full ~2-min floor — so a branch always fires:
+
+- `elapsed < ~2 min` → wait until ~2 min after `triggeredAt`, then poll every 30 s.
+- `~2 min ≤ elapsed < 10 min` → **poll immediately** (initial wait already satisfied — do not wait a
+  fresh 2 min), then every 30 s.
+- `elapsed ≥ 10 min` → **do not start a fresh wait**; report the last-seen status as a timeout (see
+  the elapsed-window case below).
+
+The overall budget is **10 minutes from `triggeredAt`** (≈16 checks after the ~2-min floor). The
+~2-min floor skips the useless early polls yet still brackets the typical ~2:40 completion within a
+poll or two; do not stretch it longer. Do not poll during the initial wait. Where the runtime
+supports backgrounded work, run this wait-then-poll loop as a background task so the user can keep
+working; on a single-threaded turn (the production headless-360 / ADK path), poll inline. Exit the
+loop on:
 
 - `status == PROVISIONED` → success; advance to Layer 2.
 - `status == FAILED` → stop. Do NOT retry via the API. Surface to the user, in plain language:
@@ -112,7 +151,8 @@ Re-issue the GET above **every 30 seconds for up to 10 minutes** (≈20 attempts
 - 10-minute window elapsed → stop, report the last-seen status, let the user decide whether to
   keep waiting or investigate.
 
-Never spin past the 10-minute bound. Report progress to the user on each poll.
+Never spin past the 10-minute bound. If the user steps away and the turn ends, they can re-run the
+skill — Layer 1 resumes from the current status (an already `PROVISIONED` tenant skips to Layer 2).
 
 ---
 

package/skills/service-itsm-agentic-setup-configure/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: service-itsm-agentic-setup-configure
+description: "Top-level orchestrator for setting up IT Service Management (ITSM) in Salesforce Service Cloud. Use when the user asks to set up ITSM, configure service management, enable ITSM capabilities, wants a guided walkthrough, or asks what is needed to get ITSM running. Presents a multi-select track menu and delegates to domain sub-orchestrators — Incident Management, Agentforce for ITSM (Studio + Fulfiller), CMDB, and Microsoft Teams (IT Desk / IT Service / Swarming). Any prerequisites (such as the Incident Management master switch for Track 1) are owned and enforced inside the relevant sub-orchestrator, not at this level. Triggers on: set up ITSM, configure service management, ITSM setup, get ITSM running, walkthrough, set up CMDB / Teams / Agentforce for ITSM. DO NOT TRIGGER when: the user asks about a specific feature directly (e.g., the priority matrix alone), asks only about Case management, wants to create a single user, or asks general ITSM questions without setup intent."
+metadata:
+  version: "1.2"
+  domains: ["Service"]
+  relatedSkills:
+    - "service-itsm-agentic-setup-agentforce-coordinate"
+    - "service-itsm-agentic-setup-cmdb-coordinate"
+    - "service-itsm-agentic-setup-incident-management"
+    - "service-itsm-teams-coordinate"
+allowed-tools: Read AskUserQuestion
+---
+
+# ITSM Setup Orchestrator
+
+Top-level coordinator for setting up IT Service Management in Salesforce Service Cloud. Guides the user through the available ITSM setup tracks by delegating to specialized domain sub-orchestrators.
+
+## Goal
+
+Present the user with the available ITSM setup tracks, help them understand what each covers, invoke the appropriate sub-orchestrator, and track overall progress until the environment is configured.
+
+## Setup Tracks
+
+Only tracks with a working sub-orchestrator appear in the menu — use the **Track menu** template in `examples/output-templates.md`.
+
+## Sub-Orchestrators
+
+| # | Track | Sub-Orchestrator Skill | Features |
+|---|-------|------------------------|----------|
+| 1 | Incident Management | `service-itsm-agentic-setup-incident-management` | SLA & Milestones |
+| 2 | Agentforce for ITSM | `service-itsm-agentic-setup-agentforce-coordinate` | Agentforce Studio enablement, Fulfiller Agent lifecycle, Employee Agent lifecycle |
+| 3 | CMDB (Configuration Management Database) | `service-itsm-agentic-setup-cmdb-coordinate` | CMDB feature enablement, CMDB Foundation bundle, User CMDB access |
+| 4 | Microsoft Teams Integration | `service-itsm-teams-coordinate` | Teams for Employee Service enablement, IT Desk checklist, IT Service checklist, Swarming |
+
+Additional ITSM setup tracks (e.g. employee provisioning) will be added here as their sub-orchestrators become available.
+
+## Behavior
+
+### 1. Extract context from conversation
+
+Before presenting tracks, scan chat history for:
+
+- Whether the user has already configured any Incident Management features (mark as in progress or done)
+- Whether the org-level Incident Management master switch has already been confirmed on
+- Any preferences or constraints mentioned (e.g., "we only need the priority matrix", "we just want CMDB")
+- The target org (if mentioned)
+- Any specific features mentioned that narrow the scope
+
+### 2. Present the available tracks as a multi-select
+
+Emit the **Track menu** template from `examples/output-templates.md` AND, in the same response, a single `AskUserQuestion` call with `multiSelect: true` whose options mirror the rendered rows — the table is the visual view; the tool call is how the selection is collected. Both MUST appear together, never one without the other. Do NOT show tracks that have no working sub-orchestrator. Selecting one track is valid; selecting several enqueues them for sequential handling in step 3.
+
+The menu MUST also include a **"Full guided setup"** option in addition to the per-track rows. Selecting it expands to *every* available track (all rows currently rendered in the table, in dependency order — see the "Sub-Orchestrators" table above). Treat it as if the user had selected every track in one interaction; step 3's sequential-confirmation loop still runs per-track, so the user can bail between any two tracks. Full guided setup is mutually exclusive with per-track selections — if the user picks it alongside individual tracks, treat it as "Full guided setup" and ignore the per-track picks. Emitting only per-track rows without the Full guided setup option violates this rule.
+
+Do NOT run any org-level prerequisites at this level — each sub-orchestrator owns its own prerequisites (e.g., the Incident Management sub-orchestrator handles the master-switch confirmation internally). Delegating without pre-checking keeps this orchestrator agnostic about domain-specific dependencies and avoids prompting the user to change org state for a track they did not select.
+
+### 3. Delegate to the selected sub-orchestrators in order
+
+Handle the selections sequentially in the order the user listed them (or, if no order was expressed, in track number order). For each track, invoke the matching sub-orchestrator; that skill handles its own internal menu, prerequisites, and feature selection. When it returns, update the tracked status and move to the next selected track. Do not re-present the full track menu between selected tracks — the user already committed to that set in step 2.
+
+### 4. After each sub-orchestrator completes
+
+When the user returns from a sub-orchestrator:
+
+1. **Update track status** — mark it as "Done"
+2. **Move to the next selected track** if one remains
+
+### 5. Offer additional tracks after the selected set completes
+
+After the last track in the user's selection completes, ask whether they want to configure any of the remaining tracks. If yes, run step 2 again with the *remaining* tracks only. If not, go to step 6.
+
+### 6. Completion summary
+
+When the user says they're finished (or every available track is `Done`), present the **Completion summary** template from `examples/output-templates.md`.
+
+---
+
+## Rules
+
+- ALWAYS show "(via service-itsm-agentic-setup-configure)" in the setup header
+- ALWAYS present the track menu as a multi-select — accept a set of one or more tracks in a single interaction
+- ALWAYS pair the rendered track-menu table with an `AskUserQuestion` (`multiSelect: true`) call in the same response — the table is the visual view; the tool call is the selection channel. Emitting the table alone breaks the selection channel; emitting the tool call alone hides the visual view
+- ALWAYS include a **"Full guided setup"** option in the track menu (in addition to the per-track rows). It expands to every available track in dependency order — the sequential-confirmation loop still runs per-track so the user can stop between any two tracks. Full guided setup is mutually exclusive with per-track selections; if picked with individual tracks, treat it as Full guided setup and ignore the per-track picks
+- NEVER run domain-level prerequisites (such as the Incident Management master switch) at this level — each sub-orchestrator owns and runs its own prerequisites, so users who did not select the relevant track are never prompted for unrelated org-level changes
+- NEVER show a track that has no working sub-orchestrator
+- NEVER configure a feature directly — always delegate to the sub-orchestrator (delegating through the domain orchestrator ensures its menu, progress tracking, and per-feature confirmations are applied; configuring directly bypasses that state and leaves the setup inconsistent)
+- Track progress across the conversation
+- Do not show Salesforce record IDs in any output — use human-readable names only
+- If the user asks about a specific feature directly (e.g., "set up the priority matrix", "just enable CMDB"), you may skip the Behavior step 2 track menu and delegate directly to the corresponding sub-orchestrator; the sub-orchestrator will handle its own prerequisites as needed
+- If the user asks for a setup area that is not yet available (e.g. employee provisioning, major incident management), tell them it is not yet available in this orchestrator and will be added as its sub-orchestrator merges
+
+---
+
+## Verification checklist
+
+Before emitting any menu or summary in this skill, mentally confirm each of the following. If any box is unchecked, adjust the output before sending.
+
+- [ ] The header line ends with `(via service-itsm-agentic-setup-configure)`
+- [ ] Only tracks with a working sub-orchestrator are shown; placeholder tracks are hidden
+- [ ] The track menu is presented as a multi-select (single-select is only acceptable when the user has already named a specific track directly)
+- [ ] The track menu emitted BOTH the ASCII table AND an `AskUserQuestion` (`multiSelect: true`) presenting the same options in the same response — never one without the other
+- [ ] The track menu included a **"Full guided setup"** option in addition to the per-track rows; if the user selected it, all available tracks were enqueued in dependency order with per-track confirmation between them
+- [ ] Each track row's `Status` column reflects the actual tracked state from the conversation (`Not done`, `In progress`, or `Done`) — not a hard-coded default
+- [ ] For a completion summary, the header line and closing line are chosen by the rubric in `examples/output-templates.md` (all `Done` → *Complete*; any `Not done`/`In progress` → *Finished*)
+- [ ] No org-level prerequisites are being run at this level — the selected sub-orchestrator handles its own prerequisites
+- [ ] The next action delegates to a sub-orchestrator, never directly to a feature child skill
+- [ ] No Salesforce record IDs appear in the output — human-readable names only
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|--------------|
+| `examples/output-templates.md` | Behavior steps 2 and 6 — track menu (multi-select) and completion summary text blocks |

package/skills/service-itsm-agentic-setup-configure/examples/output-templates.md

@@ -0,0 +1,64 @@
+# Output Templates — service-itsm-agentic-setup-configure
+
+Emit one of these text blocks at the corresponding step in the workflow. Only tracks with a
+working sub-orchestrator appear.
+
+## Track menu (Behavior step 2)
+
+```text
+ITSM Setup (via service-itsm-agentic-setup-configure)
+
+┌───┬──────────────────────────┬──────────────────────────────────────────────────────┬──────────┐
+│ # │ Track                    │ What it covers                                       │ Status   │
+├───┼──────────────────────────┼──────────────────────────────────────────────────────┼──────────┤
+│ 1 │ Incident Management      │ Configure Incident Management features — currently   │ Not done │
+│   │                          │ SLA & Milestones and Priority Matrix                 │          │
+│ 2 │ Agentforce for ITSM      │ Enable Agentforce Studio (org-level Agentforce and   │ Not done │
+│   │                          │ Einstein GenAI) and create/activate the IT Service   │          │
+│   │                          │ Fulfiller and Employee agents                        │          │
+│ 3 │ CMDB                     │ Enable the Configuration Management Database         │ Not done │
+│   │                          │ feature, deploy the CMDB Foundation content bundle,  │          │
+│   │                          │ and grant users CMDB access                          │          │
+│ 4 │ Microsoft Teams          │ Enable Microsoft Teams for ITSM — IT Desk and IT     │ Not done │
+│   │                          │ Service checklists, plus Swarming for agent          │          │
+│   │                          │ collaboration                                        │          │
+│ A │ Full guided setup        │ Run every available track in dependency order —      │ —        │
+│   │                          │ per-track confirmation between them so you can stop  │          │
+│   │                          │ any time. Mutually exclusive with per-track picks.   │          │
+└───┴──────────────────────────┴──────────────────────────────────────────────────────┴──────────┘
+
+Reply with the numbers of the tracks you want to set up (one or more, e.g. `1` or `1, 3`), or `A` for the full guided setup.
+```
+
+## Completion summary (Behavior step 6)
+
+The completion summary fires either (a) after every track completes, or (b) when the user says
+they are finished — even if some tracks are still `Not done`. When rendering:
+
+- Substitute each track's row with its actual tracked status: `Done`, `In progress`, or `Not done`.
+  Do NOT hard-code `Done`.
+- Choose the header line based on whether every track is `Done`:
+  - All tracks `Done` → `ITSM Setup — Complete`
+  - Any track still `Not done` or `In progress` → `ITSM Setup — Finished`
+- Choose the closing line based on state:
+  - All `Done` → `Your ITSM setup is complete.`
+  - Otherwise → `You have finished the tracks you selected. The remaining tracks can be resumed later by re-invoking this orchestrator.`
+
+Example — user finished after only Incident Management and Agentforce (the two tracks they chose to set up in this session; CMDB and Microsoft Teams stayed `Not done`):
+
+```text
+ITSM Setup — Finished
+(via service-itsm-agentic-setup-configure)
+
+┌──────────────────────────┬──────────┐
+│ Track                    │ Status   │
+├──────────────────────────┼──────────┤
+│ Incident Management      │ Done     │
+│ Agentforce for ITSM      │ Done     │
+│ CMDB                     │ Not done │
+│ Microsoft Teams          │ Not done │
+└──────────────────────────┴──────────┘
+
+You have finished the tracks you selected. The remaining tracks can be resumed
+later by re-invoking this orchestrator.
+```

package/skills/service-itsm-agentic-setup-employee-agent-configure/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: service-itsm-agentic-setup-employee-agent-configure
+description: "Create and activate an IT Service Employee agent as a Next-Gen Authoring (NGA) native agent from an ITSM Employee agent template's Agent Script, via the Salesforce CLI (sf): read the template, check idempotency, create the NGA bundle then publish and activate, verify live. Defaults to the broad IT Service Employee template; when the user names a specialized Employee template (Password Manager Assistance, Certificate Management, Onboarding, Hardware Request, and ~47 others catalogued in references/specialized-templates.md — all under the `svc_emp_intelligence__` namespace), pins that one instead. Idempotent per developer name. TRIGGER when the user asks to create/set up/provision/activate the Employee agent, the IT Service Employee agent, or a specialized Employee agent (password manager, certificate, onboarding, hardware request, etc.). DO NOT TRIGGER: prerequisite checks (service-itsm-agentic-setup-agentforce-studio-validate), CMDB CRUD, Fulfiller setup (service-itsm-agentic-setup-fulfiller-agent-configure)."
+metadata:
+  version: "2.1"
+  domains: ["Service", "Agentforce"]
+  minApiVersion: "67.0"
+  relatedSkills:
+    - "service-itsm-agentic-setup-agentforce-studio-configure"
+    - "service-itsm-agentic-setup-agentforce-studio-validate"
+    - "service-itsm-agentic-setup-fulfiller-agent-configure"
+  cliTools:
+    - tool: ["node"]
+      semver: ">=18.0.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  accessCheck:
+    - type: "license"
+      value: "Agentforce"
+allowed-tools: |
+  Bash
+  Read
+  Write
+  AskUserQuestion
+---
+
+# Create an IT Service Employee Agent (broad or specialized)
+
+Create and activate an **IT Service Employee Agent** as a **Next-Gen Authoring (NGA) native agent** — Agent-Script-based (`AiAuthoringBundleDefVer`/bundle), appearing natively in Agentforce Studio's Agents list with no external-link icon — entirely through the **Salesforce CLI (`sf`)**. **This skill does not call the legacy `/connect/service-itsm/createAgent`**; instead it reuses a shipped ITSM Employee template's `agentScript` field and feeds it into the NGA bundle pipeline: `POST /nextgen-authoring/bundles` → `POST /nextgen-authoring/bundle-versions/{id}/publish` → `POST /nextgen-authoring/bundle-versions/{id}/activate`. Commands: `sf api request rest` for Connect API GET/POST; `sf data query` for the SOQL idempotency + verify reads.
+
+`GET /connect/service-itsm/agent-templates?agentType=AgentforceEmployeeAgent` returns the **broad** `IT Service Employee` template plus ~47 **specialized** Employee templates under the `svc_emp_intelligence__` namespace as siblings in `data[]`. Every specialized template ships the same `agentScript` shape with the same `config.developer_name`/`config.agent_label` substitution points, so the same NGA sequence works for any of them — **only the `masterLabel` that Phases 1 and 4 pin against changes.** Full catalog + namespace filter + disambiguation rules live in `references/specialized-templates.md`.
+
+Helper scripts (invoked via `Bash`) hold every JSON-parsing / decision rule so the model never eyeballs a response body (A9): `classify-preflight.mjs`, `classify-agent-existence.mjs`, `build-create-body.mjs` (HTML-decodes + substitutes the template's `agentScript` and writes the body to a JSON file so large content and free-text quotes never hit an inline shell string), `render-report.mjs` (deterministic report renderer).
+
+**Template selection (before Phase 1).** Resolve the `<masterLabel>` this run pins: (1) no specialization named ⇒ pin `IT Service Employee` (id `svc_emp_intelligence__ItEmployeeAssistance`) — the backwards-compatible default; (2) user names a specialization ⇒ keyword-match against `references/specialized-templates.md`, single unambiguous match ⇒ pin that `masterLabel` and derive `developerName` from `id` after `__` (snake-cased); ambiguous ⇒ `AskUserQuestion` keyed on `id`; (3) **filter `data[]` to `svc_emp_intelligence__` only** — `svc_itsm_intelligence__*` (Fulfiller) redirects to `service-itsm-agentic-setup-fulfiller-agent-configure`, other namespaces are out of scope. The resolved `<masterLabel>` is the single knob passed to `classify-preflight.mjs` (Phase 1) and `build-create-body.mjs` (Phase 4).
+
+**Prerequisites.** Creation assumes the org-level Agentforce for IT Service prerequisites are already satisfied (Agentforce Studio access + `service-cloud-requestor-agent` + `service-cloud-it-service-employee-agent`). If Phase 1 detects Studio is not accessible — or if any write returns `403 FUNCTIONALITY_NOT_ENABLED` — this skill **offers** to delegate to `service-itsm-agentic-setup-agentforce-studio-validate` (employee path) then resume; on "no", stops. This skill never enables features itself — enablement is a Setup-UI/admin action.
+
+## Scope
+
+- **In scope**: Reading `agent-templates`; extracting an Employee template's Agent Script (broad default or a user-named specialization from `references/specialized-templates.md` — all under `svc_emp_intelligence__`); creating the Employee agent as an **NGA-native agent** via `createBundleWithVersion` → `publish` → `activate`; SOQL-verifying live; idempotent skip on duplicate developer name — all via `sf`.
+- **Out of scope**: The Fulfiller agent (`service-itsm-agentic-setup-fulfiller-agent-configure`); enabling org-level feature toggles (validated by `service-itsm-agentic-setup-agentforce-studio-validate`); low-level topic/action authoring; perm-set assignment; content-bundle deployment; CMDB CRUD; Discovery / Service Graph; the legacy `createAgent` route; any `data[]` entry outside `svc_emp_intelligence__`.
+
+---
+
+## Preconditions
+
+If any of these are unmet, `sf` surfaces an auth error or a `401`/`403`/`404`; **surface the raw error verbatim and stop — do not fabricate state**.
+
+1. **`sf` CLI authenticated** to the target org (`sf org display -o <alias>` shows Connected). All calls use `--target-org <alias>`; never extract the access token by hand.
+2. **API v67.0+** — pinned in the URL path; do not hand-edit below the minimum.
+3. **ITSM features + templates provisioned** — resolved template must be present. If `agent-templates` returns nothing or the routes 404, run `service-itsm-agentic-setup-agentforce-studio-validate` (agent path `employee`).
+4. **`node` ≥ 18** on PATH.
+
+---
+
+## Operations at a glance
+
+| Concern | Command | Notes |
+|---------|---------|-------|
+| Studio access (precondition read) | `sf api request rest "/services/data/v67.0/agentforce-studio/access/Agents" --method GET -o <alias>` | `hasAccess=false` ⇒ prereq hand-off |
+| List agent templates + Agent Script (read) | `sf api request rest "/services/data/v67.0/connect/service-itsm/agent-templates?agentType=AgentforceEmployeeAgent" --method GET -o <alias>` | `agentType=AgentforceEmployeeAgent` required; confirms resolved `<masterLabel>` template + non-empty `agentScript` |
+| Enumerate existing agent + latest version status (read) | `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>'" -o <alias> --json` | Keyed PRIMARILY on the template's `botDefinitionId` (Phase-1 row); the `OR DeveloperName=` clause is both the null-`botDefinitionId` fallback AND the guard for a dangling Id link (deleted target). Classified by `scripts/classify-agent-existence.mjs`; Active latest ⇒ ALREADY-CREATED; Inactive latest ⇒ offer reactivation |
+| **Create the NGA bundle** (write) | `sf api request rest "/services/data/v67.0/nextgen-authoring/bundles" --method POST --body @<body-file> -o <alias>` | Body built by `scripts/build-create-body.mjs`; response `id` = the bundle **version** Id |
+| **Publish the bundle version** (write) | `sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/publish" --method POST --body '{}' -o <alias>` | Returns `publishedBotId`/`publishedBotVersionId` — creates the underlying `BotDefinition`/`BotVersion` |
+| **Activate the bundle version** (write) | `sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/activate" --method POST --body '{}' -o <alias>` | Empty response on success; agent is now live and NGA-native |
+| **Activate an existing inactive version** (write) | `sf api request rest "/services/data/v67.0/connect/bot-versions/<latestVersionId>/activation" --method POST --body '{"status":"Active"}' -o <alias>` | Reactivation path only (Phase 2b) — skips create/publish |
+| Verify agent is live (read) | `sf data query -q "SELECT ... FROM BotDefinition WHERE Id='<verifyId>'" -o <alias> --json` | `<verifyId>` = create path's `publishedBotId` (Phase-5) or the Phase-2 classifier's returned live matched Id (its `botDefinitionId`/`agentId`) on ALREADY-CREATED / reactivation — not the null Phase-1 template `botDefinitionId`, never the collected developerName; confirm `BotDefinition` present + latest version Active |
+
+Full command shapes and the ITSM Connect API reference live in `references/cli-invocation.md`; the reactivation-path call + idempotency verdict table live in `references/reactivation.md`; the response-body error codes and recurring gotchas live in `references/error-taxonomy.md`.
+
+> **Never extract the access token.** Use `sf api request rest` / `sf data query` directly — they use the CLI's stored session for the target org. Do **not** pull the `accessToken` out of `sf org display` and hand-build an HTTP request with it; that bypasses the CLI session and leaks a bearer token into shell context.
+
+> **`--json` rule.** `sf data query` **takes** `--json` (results come back in a `.result.records[]` envelope — that's what the classifier expects). `sf api request rest` does **not** — omit `--json` there; its raw stdout body is already JSON.
+
+---
+
+## Clarifying Questions
+
+Collect from the user (ask only what is not already in conversation context):
+
+| Field | Default |
+|-------|---------|
+| Target org | Default org (`sf config get target-org`) |
+| Template (`masterLabel`) | `IT Service Employee` (broad umbrella, id `svc_emp_intelligence__ItEmployeeAssistance`). If the user hints at a specialization (password manager, certificate, onboarding, hardware request, etc.), resolve via `references/specialized-templates.md`; ambiguous ⇒ `AskUserQuestion` keyed on `id` |
+| Developer name | Broad: `IT_Service_Employee_Agent`. Specialized: substring after `__` in the picked `id`, snake-cased (e.g. `PasswordManagerAssistance` → `Password_Manager_Assistance`) |
+| Label | Broad: `IT Service Employee Agent`. Specialized: the picked template's `masterLabel` verbatim (e.g. `Password Manager Assistance`) |
+| Confirm the write | **REQUIRED** — present resolved template + developerName + label, then require "yes" via `AskUserQuestion` |
+
+The collected `<masterLabel>`, `<developerName>`, `<label>` are threaded through every call — `<masterLabel>` selects the row in `agent-templates.data[]` (which also carries the `botDefinitionId` idempotency key); `<developerName>`/`<label>` are used in the `createBundleWithVersion` body (both outer `apiName`/`label` AND the substituted internal `config.developer_name`/`config.agent_label`). The **idempotency + verify reads key PRIMARILY on the template's `botDefinitionId`** (or, after a fresh create, the publish response's `publishedBotId`) and **fall back to the collected `<developerName>`** when that is null. A hardcode/collect mismatch on the create body diverges the bundle's outer identity from the script's internal identity.
+
+**Idempotency**: keyed PRIMARILY on the **template's `botDefinitionId`** (Phase-1 `agent-templates` row — the platform's authoritative template→`BotDefinition` link) and FALLING BACK to the collected `<developerName>`. The Phase-2 read is `BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'` (the `OR` half is both the null-`botDefinitionId` fallback AND the guard for a **dangling** Id link — one whose target `BotDefinition` was deleted — so a stale link can't slip through to create), + latest `BotVersion.Status`. Outcomes: no match on either key ⇒ create; `Active` ⇒ ALREADY-CREATED (skip write); `Inactive` ⇒ Phase-2b reactivation offer. **Why both keys:** the broad agent ships pre-provisioned as `IT_Service_Employee` ≠ the guess `IT_Service_Employee_Agent`, so `botDefinitionId` catches it — but an agent this skill creates never back-fills `botDefinitionId` (the create path omits `templateName`), so its template row stays null and the `developerName` fallback is what catches a repeat run. The server does reject a duplicate `DeveloperName` at publish (unique-constraint → bundle cleanup), but only this read turns a repeat into a graceful skip instead of a `DUPLICATE_VALUE`.
+
+---
+
+## Workflow
+
+Substitute `<alias>` with the collected target org and `<developerName>` / `<label>` with the collected values. Full command shapes + per-phase verdict-branch handling live in `references/workflow-detail.md` — the phase summary below names each step and its load-bearing rule; the reference file holds the exact `sf` / `node` invocations to copy.
+
+0. **Phase 0 — Establish `${SCRATCH_DIR}`.** Before any phase writes a transient JSON file, invoke the deterministic helper (path is skill-root-qualified so it resolves regardless of the shell's CWD): `SCRATCH_DIR="$(node "<skill_dir>/scripts/create-scratch-dir.mjs" "${outputDir:-}")"`. The helper picks the base dir (`${TMPDIR}`, else `/tmp`, else the harness `${outputDir}` last-resort — scratch stays OUT of the scored `${outputDir}` tree) and emits the created dir's absolute path on stdout. Every subsequent phase writes its transient JSON under `${SCRATCH_DIR}`; the durable `${outputDir}/report.md` stays under the harness dir.
+1. **Phase 1 — Preflight.** Capture the Studio-access read + `agent-templates` read (with the **required** `agentType=AgentforceEmployeeAgent` query param), then classify via `scripts/classify-preflight.mjs "<masterLabel>"` — pass the resolved `<masterLabel>` (`"IT Service Employee"` for the broad path or the picked specialization's `masterLabel`). The classifier also emits `template.botDefinitionId` from the matched row — **capture it; it is the primary Phase-2 idempotency key (the collected `<developerName>` is the fallback key).** Branch on `verdict`: `READY` ⇒ Phase 2; `NOT-READY` ⇒ prerequisite hand-off via `AskUserQuestion` (delegate to `service-itsm-agentic-setup-agentforce-studio-validate` employee path on "yes"); `ERROR` ⇒ surface + stop; `studio.signal="CANNOT-CONFIRM"` (confirmed 404) does not block.
+2. **Phase 2 — Idempotency (primary key `botDefinitionId`, fallback key `<developerName>`).** Take `template.botDefinitionId` from Phase 1. **Present** ⇒ SOQL `BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'` (+ `BotVersions` subquery — required, else `needsActivation` is permanently false; the `OR` clause makes a **dangling** Id link — deleted target — fall back to the live same-name agent instead of a false `exists:false` → duplicate create). **Empty/null** ⇒ do NOT skip to create; fall back to `WHERE DeveloperName='<developerName>'` (a self-created agent's template row is never back-filled, so its `botDefinitionId` stays null even though the agent exists). Either way classify via `scripts/classify-agent-existence.mjs ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId-or-empty>" "<developerName>"`. Branch: `exists:false` ⇒ Phase 3 (create); `exists:true` + `needsActivation:false` ⇒ **ALREADY-CREATED** (skip to Phase 7); `exists:true` + `needsActivation:true` ⇒ Phase 2b. Non-zero exit ⇒ surface CLI error; never assume absent. **Why both keys:** `botDefinitionId` catches the pre-provisioned `IT_Service_Employee` (≠ the guess `IT_Service_Employee_Agent`); the `developerName` fallback catches self-created repeats — a miss on both re-creates and hits `DUPLICATE_VALUE`.
+3. **Phase 2b — Reactivation offer.** `AskUserQuestion`: _"Employee agent `<developerName>` exists but latest version is Inactive. Activate it?"_. On **Yes**: `POST /connect/bot-versions/<latestVersionId>/activation` with `{"status":"Active"}` — skips Phases 3–6, straight to Phase 7. Aggregate verdict is **ACTIVATED**, not CREATED. On **No**: stop, no writes.
+4. **Phase 3 — Confirm-to-Write (REQUIRED, create path only).** If `${outputDir}` was provided, first render the checkpoint file via `render-report.mjs` with `verdict:"PENDING CONFIRMATION"` (skip for interactive runs). THEN raise the `AskUserQuestion` gate presenting developerName + label + "NGA-native from the Employee template's Agent Script". Proceed **only** on explicit "yes"; on "no" (including "hold off on activation" / "not yet" / any decline of the atomic chain), re-render with `verdict:"DECLINED"` and a one-line `reason`.
+5. **Phase 4 — Create.** `scripts/build-create-body.mjs ${SCRATCH_DIR}/agent-templates.json "<masterLabel>" "<developerName>" "<label>" ${SCRATCH_DIR}/create-bundle-body.json` (helper re-reads Phase-1 templates JSON, HTML-decodes the matched `agentScript`, substitutes internal `config.developer_name`/`config.agent_label`, writes body to file — pass the same `<masterLabel>` used in Phase 1), then `POST /nextgen-authoring/bundles --body @${SCRATCH_DIR}/create-bundle-body.json`. **Capture response `id`** — that is the `bundleVersionId` for Phases 5–6, not `bundleId`. `403 FUNCTIONALITY_NOT_ENABLED`/`404` ⇒ trigger the Phase-1 hand-off; build-script exit 3 ⇒ surface stderr.
+6. **Phase 5 — Publish.** `POST /nextgen-authoring/bundle-versions/<bundleVersionId>/publish --body '{}'` (empty body required). Success: `{ lastPublishedOn, publishedBotId, publishedBotVersionId }` — this call creates the underlying `BotDefinition`/`BotVersion`. Any error ⇒ surface verbatim; never activate an unpublished version.
+7. **Phase 6 — Activate.** `POST /nextgen-authoring/bundle-versions/<bundleVersionId>/activate --body '{}'`. Success returns an **empty body** — check exit code, do not parse a payload.
+8. **Phase 7 — Verify.** SOQL `BotDefinition WHERE Id='<id>'` (+ `BotVersions` subquery) and classify — `<id>` is the create path's `publishedBotId` (captured from Phase 5) 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 null on a `matchedBy:"developerName"` fallback hit → the verify would run `WHERE Id=''` and falsely report failure after a successful skip/activation). Confirm `exists:true, count:1, latestVersionStatus:"Active"`. Any discrepancy ⇒ report verbatim, do not fabricate success.
+9. **Phase 8 — Aggregate verdict.** Emit CREATED / ALREADY-CREATED / ACTIVATED / FAILED (ACTIVATED on the Phase-2b path) + `BotDefinition` Id / bundle `id` by re-invoking `render-report.mjs` — the single source of report text. If `${outputDir}` was provided, overwrite `${outputDir}/report.md`; otherwise emit stdout as the turn-side report.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| All calls go through `sf api request rest` / `sf data query`; **never extract the access token** | Leaks a bearer token into shell context; the CLI's stored session is the correct surface |
+| Idempotency + verify reads key PRIMARILY on the template's `botDefinitionId` (Phase-1 row) / the publish `publishedBotId`, falling back to the collected `<developerName>`; that same `<developerName>`/`<label>` also thread through the create body (outer `apiName`/`label` AND the substituted `config.developer_name`/`config.agent_label`) | `botDefinitionId` catches the pre-provisioned `IT_Service_Employee` (≠ the guessed `IT_Service_Employee_Agent`, so a name-only read would false-negative → `DUPLICATE_VALUE`); but self-created agents never back-fill it, so the `<developerName>` fallback catches those. A create-body hardcode/collect mismatch diverges the bundle's outer identity from the script's internal identity |
+| Preflight, idempotency, bundle-body construction, and report rendering all live in `scripts/*.mjs`, not prose (A9) | JSON parsing + `masterLabel` matching + `hasAccess` reads + verdict emission are deterministic; the ~70KB Agent Script and free-text apostrophes cannot be safely interpolated into a shell string — `JSON.stringify` in the helper escapes them |
+| Three-call sequence: `createBundleWithVersion` → `publish` → `activate`, in that order, on the SAME captured `bundleVersionId` (response `id`, not `bundleId`) | Platform enforces DRAFT → published → active; response-body / empty-body / `--json` / `agentType` / HTML-decode gotchas live in `references/error-taxonomy.md` |
+| Resolve `<masterLabel>` BEFORE Phase 1; filter `data[]` to `svc_emp_intelligence__` only; disambiguate ambiguous keywords via `AskUserQuestion` keyed on `id` | Label-similar pairs exist; other namespaces belong to other flows (`svc_itsm_intelligence__*` → Fulfiller skill) |
+| Enumerate `BotDefinition` **with the `BotVersions` subquery**; skip create when Active; offer Phase-2b reactivation when Inactive — never silent skip, never duplicate create | Subquery is what distinguishes Active/Inactive; the server rejects a duplicate `DeveloperName` at publish (unique-constraint → bundle cleanup) but not the pre-provisioned broad agent, so this read is what turns a repeat into a graceful skip instead of a hard error |
+| **REQUIRED confirm-to-write checkpoint** before create sequence or reactivation call | Both change live org state — explicit user approval required |
+| On `hasAccess=false` / `403 FUNCTIONALITY_NOT_ENABLED`, offer the readiness hand-off — never enable features here; never call legacy `/connect/service-itsm/createAgent` | Enablement is a Setup-UI/admin action; `createAgent` produces a Setup-page bot with an external-link icon (wrong kind of agent for this skill) |
+| Report exact CLI response text on any error | Enables support to diagnose failures |
+
+---
+
+## Verification Checklist
+
+- [ ] Resolved `<masterLabel>` before Phase 1 (broad default or specialization from `references/specialized-templates.md`, `data[]` filtered to `svc_emp_intelligence__`, disambiguated on `id`).
+- [ ] Preflight classified by `classify-preflight.mjs` (PASS or documented CANNOT-CONFIRM); hand-off offered on FAIL; raw error surfaced on ERROR.
+- [ ] Idempotency keyed on the template's `botDefinitionId` (Phase-1 row) with the collected developerName as fallback; `BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'` (the `OR` covers both a null and a dangling `botDefinitionId`) + latest `BotVersion.Status` (subquery present) read + classified before any write.
+- [ ] If `needsActivation:true`, Phase-2b reactivation offer presented — no silent skip, no duplicate create.
+- [ ] Explicit user confirmation at Phase 3 (create) or Phase 2b (reactivation) before any write.
+- [ ] Bundle body built by `build-create-body.mjs`, POSTed via `--body @<file>` with the collected `developerName`/`label`; or write correctly skipped.
+- [ ] Same `bundleVersionId` (response `id`) used for publish + activate; reactivation used `POST /connect/bot-versions/<id>/activation`; legacy `createAgent` never called.
+- [ ] Phase-7 verify confirmed `BotDefinition` present + latest version Active.
+- [ ] Access token never extracted; final verdict + `BotDefinition`/bundle Id reported.
+
+---
+
+## Output Format
+
+The report layout is generated deterministically by `scripts/render-report.mjs` — the single source of report text for both the chat turn and the harness's `${outputDir}/report.md`. Never hand-compose the layout in prose (A9); always shell out to the helper. Full rendered shape, report-state JSON schema, and checkpoint-write rules live in `references/report-format.md`.
+
+Terminal verdicts: `CREATED | ALREADY-CREATED | ACTIVATED | PENDING CONFIRMATION | DECLINED | FAILED`. When `${outputDir}` is set, write at Phase 2, Phase 6 (or Phase 2b), and Phase 8 — each write overwrites the same file. Skip these writes in interactive/chat surfaces.
+
+---
+
+## Reference File Index
+
+- `references/specialized-templates.md` — catalog + namespace filter + `id`-based disambiguation (before Phase 1 on any specialization).
+- `references/workflow-detail.md` — exact `sf`/`node` commands + full verdict-branch narrative per phase.
+- `references/cli-invocation.md` — command shapes, never-extract-token rule, ITSM Connect API reference, helper-script contracts.
+- `references/reactivation.md` — Phase-2b activation call + full idempotency verdict table.
+- `references/report-format.md` — rendered shape, phase-state JSON schema, three-checkpoint write policy.
+- `references/error-taxonomy.md` — response-body error codes + recurring foot-guns (any non-2xx / empty body / script non-zero exit).