@salesforce/afv-skills 1.40.0 → 1.41.0

package/skills/service-itsm-agentic-setup-employee-agent-configure/references/specialized-templates.md

@@ -0,0 +1,148 @@
+# Specialized Employee agent template catalog (ITSM)
+
+The Employee side of `GET /connect/service-itsm/agent-templates?agentType=AgentforceEmployeeAgent`
+returns the **broad** IT Service Employee template plus specialized templates
+as siblings in `data[]`. This catalog lists only entries under the
+`svc_emp_intelligence__` namespace — the namespace this skill instantiates.
+Every entry ships the same shape — `id`, `masterLabel`, `description`,
+`topicsCount`, `actionsCount`, and a full `agentScript` YAML — and every one
+of them carries the same `config.developer_name`/`config.agent_label`
+substitution points the NGA bundle flow rewrites. That means **the same
+create/publish/activate sequence used for the broad template works for any
+specialized template** — the only difference is the `masterLabel` (and thus
+the `id`) that Phases 1 and 4 pin against.
+
+This reference is the picker menu for the specialization branch. The SKILL
+body stays under budget by delegating the catalog here.
+
+## Selection rules
+
+1. **Key on `id`.** Present via `AskUserQuestion` keyed on `id` when a
+   keyword match returns multiple `svc_emp_intelligence__` templates — labels
+   like `Application Password Reset Assistance` vs `System Password Reset
+   Assistance` are close enough that a label-only picker can misread a
+   partial user phrase.
+2. **Ignore everything outside `svc_emp_intelligence__`.** The
+   `agent-templates` endpoint's `data[]` includes entries from other
+   namespaces (e.g. `svc_itsm_intelligence__`, `EmpSvcAgent__`,
+   `svc_itom_intelligence__`, `EmployeeCopilot__`, `agentforce_runtime_insights__`,
+   `approval_intelligence__`, `revcloud_insight_agent__`, `Slack__`,
+   `svc_coex_intel__`, `EmpSvcMcpAgent__`). These are NOT specialized
+   Employee templates instantiable by this skill and MUST NOT appear in
+   the picker — filter `data[]` to `id`s starting with `svc_emp_intelligence__`.
+   If the user asks for one of the `svc_itsm_intelligence__*` entries,
+   redirect to `service-itsm-agentic-setup-fulfiller-agent-configure`; the
+   rest are outside this skill's scope entirely.
+3. **Default developerName / label.** When the user picks a specialized
+   template by `id`, derive:
+   - `developerName` = the substring after `__` in `id`, snake-cased and
+     truncated ≤ 40 chars (e.g. `PasswordManagerAssistance` →
+     `Password_Manager_Assistance`). A user override still wins.
+   - `label` = the template's `masterLabel` verbatim (e.g.
+     `Password Manager Assistance`). A user override still wins.
+4. **Everything else is unchanged.** Phase 2's idempotency SOQL still keys
+   on the collected `<developerName>`; Phase 4 still passes the collected
+   `<masterLabel>` to `scripts/build-create-body.mjs`; Phases 5–7 are
+   byte-identical.
+
+## Category — Access & Identity
+
+| Template `id` | Label | What it does |
+|---|---|---|
+| `svc_emp_intelligence__APIKeyAssistance` | API Key Assistance | Provision and manage API keys / auth tokens for internal + external services. |
+| `svc_emp_intelligence__ApplicationPasswordResetAssistance` | Application Password Reset Assistance | Reset passwords for software applications specifically (app-level, not network). |
+| `svc_emp_intelligence__CertificateManagementAssistance` | Certificate Management Assistance | Manage the lifecycle of digital certificates and SSL credentials. |
+| `svc_emp_intelligence__OktaUserManagementAssistance` | Okta User Management Assistance | Manage Okta user accounts, groups, and account statuses. |
+| `svc_emp_intelligence__PasswordManagerAssistance` | Password Manager Assistance | Manage credentials in corporate password managers (update, delete, sync). |
+| `svc_emp_intelligence__PrivilegeAccessAssistance` | Privilege Access Assistance | Elevated privileges + hardware access rights lifecycle. |
+| `svc_emp_intelligence__SSOAssistance` | SSO Assistance | Report login failures and troubleshoot identity-protected service access. |
+| `svc_emp_intelligence__SystemAndFileAccessAssistance` | System and File Access Assistance | File shares, DB privileges, AD group management, revocation. |
+| `svc_emp_intelligence__SystemPasswordResetAssistance` | System Password Reset Assistance | Reset network / system passwords + MFA settings. |
+
+## Category — Devices & Endpoints
+
+| Template `id` | Label | What it does |
+|---|---|---|
+| `svc_emp_intelligence__DeviceReturnAssistance` | Device Return Assistance | Return corporate hardware (upgrades, repairs, offboarding). |
+| `svc_emp_intelligence__DeviceSecurityAssistance` | Device Security Assistance | MDM enrollment + rapid threat response. |
+| `svc_emp_intelligence__DeviceTroubleshootingAssistance` | Device Troubleshooting Assistance | Troubleshoot HW issues, install monitoring agents. |
+| `svc_emp_intelligence__EndpointAssistance` | Endpoint Assistance | Workstation health monitoring + inventory. |
+| `svc_emp_intelligence__HardwareRequestAssistance` | Hardware Request Assistance | Request new/loaner hardware (laptops, peripherals, docks). |
+| `svc_emp_intelligence__LaptopRefreshAssistance` | Laptop Refresh Assistance | Scheduled laptop / monitor replacements. |
+| `svc_emp_intelligence__LostDeviceAssistance` | Lost Device Assistance | Report lost/stolen devices, execute remote sanitization. |
+
+## Category — Software & Applications
+
+| Template `id` | Label | What it does |
+|---|---|---|
+| `svc_emp_intelligence__ApplicationSupportAssistance` | Application Support Assistance | KB troubleshooting for third-party platforms; escalate to incident. |
+| `svc_emp_intelligence__GoogleWorkspaceAssistance` | Google Workspace Assistance | Provision Workspace resources, manage groups, data transfer. |
+| `svc_emp_intelligence__InternalApplicationsAssistance` | Internal Applications Assistance | Support proprietary / in-house apps. |
+| `svc_emp_intelligence__JiraAssistance` | Jira Assistance | Provision access, automate issue creation with custom fields. |
+| `svc_emp_intelligence__LicenseAuditAssistance` | License Audit Assistance | Track user entitlements, reclaim unused licenses. |
+| `svc_emp_intelligence__Office365SupportAssistance` | Office 365 Support Assistance | Diagnose Outlook/Teams/OneDrive/Office issues. |
+| `svc_emp_intelligence__ProjectManagementToolAssistance` | Project Management Tool Assistance | Provision Asana/Trello/Miro boards. |
+| `svc_emp_intelligence__SalesforceHelpAssistance` | Salesforce Help Assistance | Salesforce user lifecycle + platform troubleshooting. |
+| `svc_emp_intelligence__SharepointAssistance` | Sharepoint Assistance | SharePoint site lifecycle + permissions. |
+| `svc_emp_intelligence__SoftwareAssistance` | Software Assistance | Software installations, updates, license renewals, evaluations. |
+
+## Category — Infrastructure & Networking
+
+| Template `id` | Label | What it does |
+|---|---|---|
+| `svc_emp_intelligence__CloudResourcesAssistance` | Cloud Resources Assistance | Provision VMs / storage, dev stacks, infra ops. |
+| `svc_emp_intelligence__DataBackupAssistance` | Data Backup Assistance | Ad-hoc backups + VM backup schedules. |
+| `svc_emp_intelligence__InfrastructureProvisioningAssistance` | Infrastructure Provisioning Assistance | Provisioning-focused: VMs, test envs. |
+| `svc_emp_intelligence__LogAccessAssistance` | Log Access Assistance | Secure retrieval of system/app/infra logs. |
+| `svc_emp_intelligence__NetworkingAssistance` | Networking Assistance | Network connectivity, VPN, network resource permissions. |
+| `svc_emp_intelligence__ServerStatusAssistance` | Server Status Assistance | Monitor CI health via CMDB. |
+
+## Category — Workplace & Facilities
+
+| Template `id` | Label | What it does |
+|---|---|---|
+| `svc_emp_intelligence__AudiovisualSupportAssistance` | Audiovisual Support Assistance | AV support — meeting-room HW, connectivity, calibration. |
+| `svc_emp_intelligence__BadgeAccessAssistance` | Badge Access Assistance | Physical badge issuance / replacement / troubleshooting. |
+| `svc_emp_intelligence__FacilitiesAssistance` | Facilities Assistance | Non-IT: climate, cleaning, physical maintenance. |
+| `svc_emp_intelligence__GuestCheckinAssistance` | Guest Check-in Assistance | Guest registration + visitor Wi-Fi. |
+| `svc_emp_intelligence__OfficeRelocationAssistance` | Office Relocation Assistance | IT infra moves + HW logistics for relocations. |
+| `svc_emp_intelligence__PhoneAssistance` | Phone Assistance | Corporate telephony + desk-phone HW. |
+| `svc_emp_intelligence__PrinterAssistance` | Printer Assistance | Printing issues + printer installs + supplies. |
+
+## Category — Communications & Collaboration
+
+| Template `id` | Label | What it does |
+|---|---|---|
+| `svc_emp_intelligence__DistributionListAssistance` | Distribution List Assistance | Slack/Teams workspaces, email lists, shared mailboxes. |
+| `svc_emp_intelligence__MobilePlanAssistance` | Mobile Plan Assistance | Cellular plans, roaming, data add-ons. |
+
+## Category — Employee Lifecycle & HR
+
+| Template `id` | Label | What it does |
+|---|---|---|
+| `svc_emp_intelligence__OffboardingAssistance` | Offboarding Assistance | Offboarding intake. |
+| `svc_emp_intelligence__OnboardingAssistance` | Onboarding Assistance | New-hire onboarding intake. |
+| `svc_emp_intelligence__VendorEmployeeAssistance` | Vendor Employee Assistance | External partner / contractor access lifecycle. |
+
+## Category — Analytics, Approvals, Knowledge
+
+| Template `id` | Label | What it does |
+|---|---|---|
+| `svc_emp_intelligence__AnalyticsWorkspaceAssistance` | Analytics Workspace Assistance | Tableau site provisioning + workspace access. |
+| `svc_emp_intelligence__ITApprovalAssistance` | IT Approval Assistance | Approve/reject pending IT requests in-chat. |
+| `svc_emp_intelligence__ITPolicyAssistance` | IT Policy Assistance | Company policy Q&A + exception requests. |
+| `svc_emp_intelligence__KnowledgeAssistance` | Knowledge Assistance | KB search + summarization. |
+| `svc_emp_intelligence__CorporateCardManagementAssistance` | Corporate Card Management Assistance | Corporate credit card requests / admin. |
+
+## Category — Security & Compliance
+
+| Template `id` | Label | What it does |
+|---|---|---|
+| `svc_emp_intelligence__SecurityAssistance` | Security Assistance | Report incidents (phishing/breach), security training + exceptions. |
+
+## Category — Ticketing (broad self-service)
+
+| Template `id` | Label | What it does |
+|---|---|---|
+| `svc_emp_intelligence__TicketManagementAssistance` | Ticket Management Assistance | Broad ticket lifecycle: status, reopens, comments, intake. |
+| `svc_emp_intelligence__ItEmployeeAssistance` | IT Service Employee | **Default / broad** — the umbrella IT-Service Employee assistant. This is the SKILL's default when no specialization is requested. |

package/skills/service-itsm-agentic-setup-employee-agent-configure/references/workflow-detail.md

@@ -0,0 +1,169 @@
+# Employee Agent — Workflow Detail
+
+Detailed per-phase command shapes + verdict narrative for `service-itsm-agentic-setup-employee-agent-configure`. Read this alongside the phase headers in `SKILL.md` — the SKILL body holds the load-bearing rules, this file holds the exact commands and branch-by-branch verdict handling.
+
+All calls go through `sf`; substitute `<alias>` with the collected target org and `<developerName>` / `<label>` with the collected values.
+
+## Phase 0 — Establish the per-run scratch directory
+
+Before any phase writes a transient JSON file, invoke `scripts/create-scratch-dir.mjs` — path selection (`${TMPDIR}` → `/tmp` → `${outputDir}` last-resort, keeping transient captures out of the scored `${outputDir}` tree) and the `mkdtemp` call live in the helper so the deterministic logic never sits in prose (A9). Every subsequent phase writes its scratch JSON under `${SCRATCH_DIR}`, so runs never collide and the transient state stays scoped to the run:
+
+```bash
+SCRATCH_DIR="$(node "<skill_dir>/scripts/create-scratch-dir.mjs" "${outputDir:-}")"
+```
+
+The remaining phases reference `${SCRATCH_DIR}` for every transient path (studio-access, agent-templates, bot-existing, create-bundle-body, publish/activate response captures, report-state, verify). The **durable** run artifact — `${outputDir}/report.md` — is still written to the harness-provided directory.
+
+## Phase 1 — Preflight: confirm Studio access + template provisioning
+
+Capture the Studio-access read and the `agent-templates` read, then let `scripts/classify-preflight.mjs` make the deterministic decisions (never parse `hasAccess` or search `data[]` in prose — A9). The `agent-templates` `agentType` query param is **required** with value `AgentforceEmployeeAgent` (a call without it returns `400 MISSING_ARGUMENT: agentType`):
+
+```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 "<masterLabel>"
+```
+
+Pass the resolved `<masterLabel>` — `"IT Service Employee"` for the default broad path, or the picked specialized template's `masterLabel` (e.g. `"Password Manager Assistance"`) for a specialized path. The classifier matches `data[]` case-insensitively on `masterLabel` and confirms the matched row has a non-empty `agentScript`.
+
+The classifier prints `{ studio:{hasAccess,signal}, template:{present,id,hasAgentScript,botDefinitionId,signal}, verdict, reasons }`:
+
+- `template.hasAgentScript:true` confirms the template carries the Agent Script content Phase 4 needs; capture the raw `agent-templates.json` file path — Phase 4 re-reads it directly (via `scripts/build-create-body.mjs`) rather than the classifier re-emitting the full script content.
+- **`template.botDefinitionId` is the PRIMARY Phase-2 idempotency key.** A populated value means this template has already been instantiated into a live `BotDefinition` (the broad Employee agent ships pre-provisioned this way); a `null` value means it has not been created yet OR it was created by this skill (self-created agents never back-fill the template row). Capture `botDefinitionId` for Phase 2, and carry the collected `<developerName>` as the fallback key.
+- `verdict:"READY"` ⇒ continue to Phase 2.
+- `verdict:"ERROR"` because `studio.signal="ERROR"` (the Studio-access read returned a parseable but non-404 error body — e.g. `401`/`403`) ⇒ do NOT proceed — surface the raw error and stop. This is a failed prerequisite read, not an unwired gate; do not let a present template push the verdict to READY.
+- `verdict:"NOT-READY"` because `studio.signal="FAIL"` (`hasAccess=false`) ⇒ do NOT proceed — **offer the prerequisite hand-off**:
+  - Present a single `AskUserQuestion`: _"Agentforce for IT Service prerequisites don't look satisfied on this org. Run `service-itsm-agentic-setup-agentforce-studio-validate` (employee path) to check readiness first?"_ (options: **Yes, check readiness** / **No, stop here**).
+  - On **Yes**: delegate to `service-itsm-agentic-setup-agentforce-studio-validate` (read-only readiness check, `employee` agent path). If it reports NOT-READY, stop and report the missing prerequisite (enablement is a Setup-UI/admin action, outside both skills' write scope). If READY, resume from Phase 2.
+  - On **No**: stop and report the missing prerequisite verbatim — no writes.
+- `verdict:"NOT-READY"` because `template.signal="FAIL"` (empty/no matching template) ⇒ the org is not ITSM-provisioned; hand off to the readiness check.
+- `template.signal="CANNOT-CONFIRM"` because the matched template has no `agentScript` ⇒ the NGA create has nothing to build from; surface this and stop (do not fall back to the legacy `createAgent` route — it is out of scope for this skill).
+- `studio.signal="CANNOT-CONFIRM"` (a **confirmed** `404` — the access-check gate isn't wired on the org, expected on scratch orgs) does **not** block: a successful create/publish/activate is authoritative. A later `403 FUNCTIONALITY_NOT_ENABLED` on the write is the same signal as `hasAccess=false` — trigger the same hand-off offer.
+
+## Phase 2 — Idempotency: does the target agent already exist, and is it active?
+
+Idempotency is keyed **PRIMARILY** on the template's `botDefinitionId` (captured in Phase 1) and **FALLS BACK** to the collected `<developerName>`. The `botDefinitionId` is the platform's authoritative link from the `agent-templates` row to the `BotDefinition` it was instantiated into — it catches the pre-provisioned broad Employee agent (which ships active under DeveloperName `IT_Service_Employee`, never matching the default guess `IT_Service_Employee_Agent`, so a name-only read would false-negative and the create would fail with `DUPLICATE_VALUE`). But that link is back-filled **only** for pre-provisioned agents — an agent this skill creates never stamps `templateName`, so its template `botDefinitionId` stays `null`; for that self-created case the `DeveloperName`-keyed fallback is the guard, so never short-circuit to create when `botDefinitionId` is absent.
+
+- **`template.botDefinitionId` is empty/null** ⇒ fall back to a DeveloperName-keyed read (do **not** short-circuit to create — a self-created agent from a prior run has a null template `botDefinitionId` but still exists). The `BotVersions` subquery is required — omitting it leaves `needsActivation` permanently false and hides the reactivation path:
+  ```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>"
+  ```
+- **`template.botDefinitionId` is present** ⇒ read the `BotDefinition` by Id **`OR` by the collected `<developerName>`** in one query, INCLUDING its latest version's status, then classify. The `OR DeveloperName=` clause is what catches a **dangling** template→BotDefinition link — a `botDefinitionId` whose target row was since deleted: the by-Id half returns nothing, but the live same-name agent still surfaces, so the classifier falls back to it (`matchedBy:"developerName"`) instead of concluding `exists:false` and letting the create collide 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>"
+  ```
+
+The classifier prints `{ exists, count, matchedBy, agentId, botDefinitionId, developerName, latestVersionId, latestVersionStatus, needsActivation }` — `matchedBy` is `"botDefinitionId"` | `"developerName"` | `null`, and `developerName` is the ACTUAL live agent's DeveloperName read from the record (e.g. `IT_Service_Employee`), surface it in the report rather than the collected guess:
+
+- `exists:false` ⇒ proceed to Phase 3 (create path).
+- `exists:true` and `needsActivation:false` (latest version `Active`) ⇒ **ALREADY-CREATED** — skip the write, fall through to Phase 7 verification.
+- `exists:true` and `needsActivation:true` (latest version `Inactive`) ⇒ do **not** create a duplicate agent — go to Phase 2b to offer activating the existing version instead.
+- A non-zero exit (exit 3) means the query itself failed — surface the raw CLI error, do not assume the agent is absent.
+
+## Phase 2b — Reactivation offer (existing agent found inactive)
+
+Present the discovery to the user via `AskUserQuestion`: _"An Employee agent named `<developerName>` already exists but its latest version is Inactive. Activate the existing version instead of creating a new agent?"_ (options: **Yes, activate the existing version** / **No, stop here**).
+
+- On **Yes**: activate the captured `latestVersionId` directly — no create/publish needed since the `BotDefinition`/`BotVersion` already exist:
+  ```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
+  ```
+  On success, skip Phases 3–6 entirely (no create/publish/confirm-to-write for a fresh agent) and go straight to Phase 7 to verify. Report the aggregate verdict as **ACTIVATED** in Phase 8, not CREATED.
+- On **No**: stop and report the current state (agent exists, latest version Inactive) without any writes.
+
+## Phase 3 — Confirm-to-Write Checkpoint (REQUIRED, create path only)
+
+**Before raising the confirmation gate**, if `${outputDir}` was provided (via the harness's generated-file location directive), render the report file via `scripts/render-report.mjs` with `verdict:"PENDING CONFIRMATION"` so it exists even if the harness parks at the question. Skip this write for interactive runs where no `${outputDir}` was passed. Report-state JSON shape lives in `references/report-format.md`.
+
+```bash
+node "<skill_dir>/scripts/render-report.mjs" ${SCRATCH_DIR}/report-state.json "${outputDir}/report.md"
+```
+
+Report-state JSON shape:
+
+```json
+{
+  "org": "<alias>",
+  "template": {"masterLabel": "...", "id": "...", "kind": "broad umbrella"|"specialized"},
+  "developerName": "...",
+  "label": "...",
+  "preflight": {"studioHasAccess": true|false, "templateAgentScriptPresent": true|false},
+  "enumerate": {"existsBeforeWrite": true|false, "latestVersionStatus": "Active"|"Inactive"|"n/a"},
+  "confirmToWrite": "pending",
+  "verdict": "PENDING CONFIRMATION",
+  "reason": "Run is paused at the confirm-to-write gate awaiting the user's explicit \"yes\"."
+}
+```
+
+THEN **present the exact create request** (developerName + label, that this creates an NGA-native agent from the Employee template's Agent Script) and require an explicit "yes" via `AskUserQuestion`. **Proceed to Phase 4 ONLY on an explicit "yes".** On "no" (including "hold off on activation" / "not yet" / any decline of the atomic chain), stop and — if `${outputDir}` was provided — re-render with `verdict:"DECLINED"` and a one-line `reason` naming the user's decline. Never fabricate a partial "create-only" outcome.
+
+## Phase 4 — Create the NGA bundle
+
+Build the `createBundleWithVersion` request body with the helper — it re-reads the Phase-1 `agent-templates.json`, extracts the matched template's `agentScript`, fully HTML-decodes it, and substitutes its internal `config.developer_name` / `config.agent_label` with the **collected** `<developerName>` / `<label>` (so the bundle's outer `apiName` and the script's internal identity match). This also keeps the large script content and any free-text quotes/apostrophes out of an inline shell string:
+
+```bash
+node "<skill_dir>/scripts/build-create-body.mjs" ${SCRATCH_DIR}/agent-templates.json "<masterLabel>" "<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
+```
+
+Pass the same resolved `<masterLabel>` used in Phase 1 — the builder re-reads `${SCRATCH_DIR}/agent-templates.json`, re-locates the row by `masterLabel`, decodes its `agentScript`, and substitutes the collected `<developerName>`/`<label>` into the script's internal `config.developer_name`/`config.agent_label` before writing the bundle body.
+
+On success, the `POST /nextgen-authoring/bundles` response is a bundle-version detail: `{ apiName, label, bundleId, id, versionStatus:"DRAFT", assets:[...], ... }`. **Capture `id` — that is the `bundleVersionId` used in Phases 5 and 6, not `bundleId`.**
+
+- `403 FUNCTIONALITY_NOT_ENABLED` / `404` → trigger the Phase-1 prerequisite hand-off offer (the NGA authoring namespace isn't provisioned on the org).
+- A build-script exit 3 (template or `agentScript` not found in `${SCRATCH_DIR}/agent-templates.json`) → surface the script's stderr verbatim and stop; do not retry with a hand-typed template id.
+
+## Phase 5 — Publish the bundle version
+
+Publish the captured `bundleVersionId` — empty `--body '{}'` required (the CLI rejects a POST with no `--body`):
+
+```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
+```
+
+On success: `{ lastPublishedOn, publishedBotId, publishedBotVersionId }`. This is the call that creates the underlying `BotDefinition`/`BotVersion`. An error here means the DRAFT version failed platform-side validation — surface it verbatim; do not attempt to activate an unpublished version.
+
+## Phase 6 — Activate the bundle version
+
+Activate the same `bundleVersionId`:
+
+```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 body** — do not treat empty stdout as a failure; check the CLI exit code and fall through to Phase 7 to confirm via `BotDefinition`/`BotVersion` state instead of parsing a response payload.
+
+## Phase 7 — Verify the agent is live
+
+Read `BotDefinition` by Id (with `BotVersions` subquery, same shape as Phase 2) and classify. 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 `null` on a `matchedBy:"developerName"` fallback hit — using it would run the verify as `WHERE Id=''` and falsely report failure after a successful skip/activation). Never the collected `<developerName>`:
+
+```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>"
+```
+
+Confirm `exists:true` with `count:1`, and — on the create or reactivation path — `latestVersionStatus:"Active"`. `exists:false` after a successful activate ⇒ report the discrepancy verbatim, do not fabricate success. Optionally cross-check `GET /nextgen-authoring/bundles` for an entry with the collected `apiName` and `isLegacy:false` to confirm the agent is NGA-native (no external-link icon in Agentforce Studio).
+
+## Phase 8 — Aggregate verdict
+
+Report the verdict (CREATED / ALREADY-CREATED / ACTIVATED / FAILED) and the resulting `BotDefinition` Id / bundle `id`. Use **ACTIVATED** when Phase 2b's reactivation path was taken (existing agent found inactive, activated instead of creating new). Emit the final report by re-invoking `scripts/render-report.mjs` with the fully populated phase-state JSON. If `${outputDir}` was provided, overwrite `${outputDir}/report.md`; otherwise emit the helper's stdout as the turn-side report.
+
+```bash
+node "<skill_dir>/scripts/render-report.mjs" ${SCRATCH_DIR}/report-state.json "${outputDir}/report.md"
+```

package/skills/service-itsm-agentic-setup-employee-agent-configure/scripts/build-create-body.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Build the NGA createBundleWithVersion request body from the shipped
+// Employee template's agentScript.
+//
+// The legacy `agent-templates` read already returns the template's full Agent
+// Script (AFScript) content in its `agentScript` field, HTML-entity-encoded
+// (sometimes double-encoded). This script:
+//   1. Locates the matching template item by masterLabel in the
+//      agent-templates response.
+//   2. Fully HTML-decodes `agentScript` (named + numeric entities, multi-pass
+//      to unwind double-encoding).
+//   3. Substitutes the script's internal `config.developer_name` /
+//      `config.agent_label` with the collected <developerName> / <label> —
+//      the bundle's outer apiName must match the script's internal
+//      developer_name or the two diverge (the platform will otherwise
+//      auto-suffix the apiName).
+//   4. Writes the createBundleWithVersion body
+//      { apiName, label, assets: [{ resourceName: "agentDefinition",
+//        resourceType: "agentDefinition", sections: [], resourceContent }] }
+//      to <outPath>.
+//
+// Usage:
+//   node build-create-body.mjs <agent-templates.json> <masterLabel> <developerName> <label> <outPath>
+//
+// Exits 2 on missing/bad args, 3 if the template or its agentScript can't be found.
+
+import { readFileSync, writeFileSync } from 'node:fs';
+
+const [templatesPath, masterLabel, developerName, label, outPath] = process.argv.slice(2);
+if (!templatesPath || !masterLabel || !developerName || !label || !outPath) {
+  process.stderr.write('usage: node build-create-body.mjs <agent-templates.json> <masterLabel> <developerName> <label> <outPath>\n');
+  process.exit(2);
+}
+
+function decodeHtmlEntities(text) {
+  let prev = text;
+  for (let pass = 0; pass < 4; pass += 1) {
+    const next = prev
+      .replace(/&amp;/g, '&')
+      .replace(/&quot;/g, '"')
+      .replace(/&#39;/g, "'")
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&#(\d+);/g, (_, code) => String.fromCharCode(parseInt(code, 10)));
+    if (next === prev) break;
+    prev = next;
+  }
+  return prev;
+}
+
+let templatesData;
+try {
+  templatesData = JSON.parse(readFileSync(templatesPath, 'utf8'));
+} catch {
+  process.stderr.write(`error: could not read/parse ${templatesPath}\n`);
+  process.exit(3);
+}
+
+const items = Array.isArray(templatesData?.data) ? templatesData.data : [];
+// Filter to `svc_emp_intelligence__` first — matches the preflight classifier.
+// The agent-templates response also carries other-namespace entries; some
+// share a masterLabel with an in-namespace entry (e.g. `System Password Reset
+// Assistance`) so a `masterLabel`-only match would silently pick whichever
+// appeared first in `data[]`.
+const inNamespace = items.filter((it) => typeof it?.id === 'string' && it.id.startsWith('svc_emp_intelligence__'));
+const wanted = String(masterLabel).trim().toLowerCase();
+const match = inNamespace.find((it) => String(it?.masterLabel ?? '').trim().toLowerCase() === wanted);
+if (!match) {
+  process.stderr.write(`error: no svc_emp_intelligence__ template with masterLabel "${masterLabel}" found in ${templatesPath}\n`);
+  process.exit(3);
+}
+if (!match.agentScript || typeof match.agentScript !== 'string' || !match.agentScript.trim()) {
+  process.stderr.write(`error: template "${masterLabel}" (id=${match.id}) has no agentScript content\n`);
+  process.exit(3);
+}
+
+// Escapes a value for use as a YAML double-quoted scalar — the agentScript's
+// developer_name/agent_label fields are plain `"..."` strings, so a raw
+// double-quote or backslash in a user-supplied label would otherwise break
+// out of the scalar (e.g. label `Sam "Ops"` -> `agent_label: "Sam "Ops""`).
+function yamlDoubleQuoteEscape(text) {
+  return String(text).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+const decoded = decodeHtmlEntities(match.agentScript);
+const developerNameEscaped = yamlDoubleQuoteEscape(developerName);
+const labelEscaped = yamlDoubleQuoteEscape(label);
+
+const substituted = decoded
+  .replace(/developer_name:\s*"[^"]*"/, () => `developer_name: "${developerNameEscaped}"`)
+  .replace(/agent_label:\s*"[^"]*"/, () => `agent_label: "${labelEscaped}"`);
+
+if (!substituted.includes(`developer_name: "${developerNameEscaped}"`)) {
+  process.stderr.write('error: failed to substitute config.developer_name in the decoded agentScript\n');
+  process.exit(3);
+}
+if (!substituted.includes(`agent_label: "${labelEscaped}"`)) {
+  process.stderr.write('error: failed to substitute config.agent_label in the decoded agentScript\n');
+  process.exit(3);
+}
+
+const body = {
+  apiName: developerName,
+  label,
+  assets: [
+    {
+      resourceName: 'agentDefinition',
+      resourceType: 'agentDefinition',
+      sections: [],
+      resourceContent: substituted,
+    },
+  ],
+};
+
+writeFileSync(outPath, JSON.stringify(body), 'utf8');
+process.stdout.write(outPath + '\n');

package/skills/service-itsm-agentic-setup-employee-agent-configure/scripts/classify-agent-existence.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+// Deterministic idempotency / verification classifier for the Employee-agent create flow.
+//
+// Idempotency for this flow is keyed PRIMARILY on the TEMPLATE's own
+// `botDefinitionId` — the platform's authoritative link from an `agent-templates`
+// row to the live `BotDefinition` it was instantiated into — and FALLS BACK to a
+// `DeveloperName`-keyed read when that row carries no `botDefinitionId`.
+// The broad "IT Service Employee" agent is pre-provisioned+active under
+// DeveloperName `IT_Service_Employee`, which does NOT match this skill's default
+// collected developerName `IT_Service_Employee_Agent`; a DeveloperName-only read
+// false-negatives on THAT agent (exists:false) and the create then collides on
+// `apiName` with `DUPLICATE_VALUE` — hence botDefinitionId is the primary key.
+// But botDefinitionId is back-filled onto the template row ONLY for platform-
+// pre-provisioned agents: the ITSM create path never stamps `templateName`, so
+// agents THIS skill creates keep a null template botDefinitionId forever, and a
+// DeveloperName-keyed read is the reliable guard for them — used as the FALLBACK.
+// (Preflight emits `template.botDefinitionId`; the workflow passes it as the
+// primary key and the collected developerName as the fallback key.)
+//
+// This classifier consumes the raw JSON of a `sf data query ... --json` read of
+// BotDefinition (BY Id primarily, BY DeveloperName on the fallback) and decides
+// whether the agent already exists — and if so, whether its latest BotVersion is
+// Inactive (so the workflow can offer to activate it instead of creating a
+// duplicate). This is the deterministic decision that gates whether the write is
+// skipped — it MUST NOT be interpreted by the model in prose (authoring standard A9).
+//
+// Usage:
+//   node classify-agent-existence.mjs <bot-query.json> <botDefinitionId> [developerName]
+//
+// When <botDefinitionId> is empty, `-`, or the literal `null`/`undefined` (the
+// matched template carries no botDefinitionId), the classifier FALLS BACK to
+// keying on <developerName>, and <bot-query.json> must be a DeveloperName-keyed
+// BotDefinition read: self-created agents are never back-filled with a
+// botDefinitionId (the ITSM create path doesn't stamp `templateName`, so the
+// platform never joins the agent-templates row to its BotDefinition), so
+// DeveloperName is the only idempotency guard left for them. Only when BOTH
+// <botDefinitionId> and <developerName> are absent is exists:false emitted
+// without reading a query file. Otherwise <bot-query.json> is a FILE PATH to the
+// stdout captured from:
+//   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 <org> --json > file.json
+// (The present-id read ORs in DeveloperName so a DANGLING template→BotDefinition
+// link — a botDefinitionId whose target BotDefinition was since deleted — still
+// surfaces the live same-name agent: the classifier tries the Id first, then
+// falls back to the name on the SAME records. The pure FALLBACK read, taken when
+// the template row carries no botDefinitionId at all, keys on
+// `DeveloperName='<developerName>'` only; everything else is identical.
+// `sf data query --json` wraps results in a `.result.records[]` envelope. The
+// BotVersions subquery is required so this classifier can see the latest
+// version's Status — a query without it leaves latestVersionStatus null and
+// needsActivation false, which silently disables the reactivation path.)
+//
+// Emits a single JSON object to stdout:
+//   { exists, count, matchedBy, agentId, botDefinitionId, developerName, latestVersionId, latestVersionStatus, needsActivation }
+// where exists is true|false, developerName is the ACTUAL DeveloperName read
+// from the matched record (e.g. `IT_Service_Employee`) — NOT the collected
+// guess — so the report surfaces the live agent's real identity;
+// latestVersionStatus is "Active"|"Inactive"|null (null means no BotVersion
+// child row was returned), and needsActivation is true only when exists is true
+// AND latestVersionStatus is "Inactive" — the signal to offer activating the
+// existing version instead of creating a new agent. `matchedBy` is
+// "botDefinitionId" | "developerName" | null, recording which key hit. Exit code
+// is always 0 on a parseable body (or when neither key is supplied); the verdict
+// is carried in the payload. On an unparseable/failed query it exits 3 so the
+// workflow surfaces the raw error rather than assuming NOT-EXISTS.
+
+import { readFileSync } from 'node:fs';
+
+const [queryPath, rawBotDefinitionId, rawDeveloperName] = process.argv.slice(2);
+if (!queryPath) {
+  process.stderr.write('usage: node classify-agent-existence.mjs <bot-query.json> <botDefinitionId> [developerName]\n');
+  process.exit(2);
+}
+
+// Salesforce Ids compare on their case-sensitive 15-char base (the trailing 3
+// chars are a case-normalizing checksum), so a 15-char and an 18-char form of
+// the same record compare equal on the first 15 chars.
+function idKey(v) {
+  return String(v ?? '').trim().slice(0, 15);
+}
+
+function notSet(v) {
+  const s = String(v ?? '').trim().toLowerCase();
+  return s === '' || s === '-' || s === 'null' || s === 'undefined';
+}
+
+const botDefinitionId = String(rawBotDefinitionId ?? '').trim();
+const developerName = String(rawDeveloperName ?? '').trim();
+const noId = notSet(botDefinitionId);
+const noName = notSet(developerName);
+
+const NOT_EXISTS = {
+  exists: false,
+  count: 0,
+  matchedBy: null,
+  agentId: null,
+  botDefinitionId: null,
+  developerName: null,
+  latestVersionId: null,
+  latestVersionStatus: null,
+  needsActivation: false,
+};
+
+// Nothing to key on — no botDefinitionId AND no developerName fallback. There is
+// no way to detect an existing agent, so this is the create path. (The workflow
+// should always pass the collected developerName so the fallback below can run;
+// this bare branch only fires when neither key is supplied.)
+if (noId && noName) {
+  process.stdout.write(JSON.stringify(NOT_EXISTS, null, 2) + '\n');
+  process.exit(0);
+}
+
+let data;
+try {
+  const text = readFileSync(queryPath, 'utf8').trim();
+  data = text ? JSON.parse(text) : null;
+} catch {
+  process.stderr.write(`error: could not read/parse ${queryPath}\n`);
+  process.exit(3);
+}
+
+// A failed `sf data query --json` has status !== 0 (e.g. malformed SOQL, auth error).
+// Do NOT treat that as "agent does not exist" — surface it.
+if (!data || (typeof data.status === 'number' && data.status !== 0) || data.result === undefined) {
+  process.stderr.write('error: query did not return a results envelope; surface the raw CLI error and stop\n');
+  process.exit(3);
+}
+
+const records = Array.isArray(data.result?.records) ? data.result.records : [];
+
+// PRIMARY key: the template's `botDefinitionId` (the platform's authoritative
+// template→BotDefinition link) — catches the pre-provisioned broad agent whose
+// live DeveloperName differs from this skill's collected guess.
+// FALLBACK: the collected DeveloperName. Self-created agents are NOT
+// back-filled — the ITSM create path never stamps `templateName`, so the
+// platform never joins the agent-templates row to its BotDefinition and
+// `botDefinitionId` stays null on every later read — so DeveloperName is their
+// only guard. We ALSO fall back to DeveloperName when a PRESENT botDefinitionId
+// matches nothing (a dangling link whose target BotDefinition was deleted): the
+// present-id Phase-2 SOQL reads `WHERE Id=... OR DeveloperName=...`, so a stale
+// link still surfaces the live same-name agent instead of slipping through to the
+// create path and colliding with DUPLICATE_VALUE. Try the Id first, then the
+// name; each filter is self-checking on top of the SOQL WHERE so a wrong-keyed
+// read can't false-positive.
+let matches = [];
+let matchedBy = null;
+if (!noId) {
+  const wantedIdKey = idKey(botDefinitionId);
+  matches = records.filter((r) => idKey(r?.Id) === wantedIdKey);
+  if (matches.length) matchedBy = 'botDefinitionId';
+}
+if (!matches.length && !noName) {
+  // DeveloperName uniqueness is case-insensitive; compare accordingly.
+  const wantedName = developerName.toLowerCase();
+  matches = records.filter((r) => String(r?.DeveloperName ?? '').trim().toLowerCase() === wantedName);
+  if (matches.length) matchedBy = 'developerName';
+}
+const exists = matches.length > 0;
+
+// The BotVersions child subquery (if present in the SOQL) surfaces the latest
+// version's Status so we can tell "already created and active" apart from
+// "already created but inactive" — the latter should offer reactivation
+// instead of a silent ALREADY-CREATED skip. The actual BotVersion status is
+// authoritative over the template's `isActivated` flag.
+const latestVersion = exists ? matches[0]?.BotVersions?.records?.[0] ?? null : null;
+const latestVersionStatus = latestVersion?.Status ?? null;
+const needsActivation = exists && latestVersionStatus === 'Inactive';
+
+process.stdout.write(JSON.stringify({
+  exists,
+  count: matches.length,
+  // Which key matched — `botDefinitionId` (primary) or `developerName` (the
+  // fallback for self-created agents). null when nothing matched.
+  matchedBy: exists ? matchedBy : null,
+  agentId: exists ? (matches[0].Id ?? null) : null,
+  // On a DeveloperName-fallback hit this surfaces the live BotDefinition Id the
+  // template row was missing; on the Id path it echoes the queried id.
+  botDefinitionId: exists ? (matches[0].Id ?? null) : (noId ? null : botDefinitionId),
+  developerName: exists ? (matches[0].DeveloperName ?? null) : null,
+  latestVersionId: latestVersion?.Id ?? null,
+  latestVersionStatus,
+  needsActivation,
+}, null, 2) + '\n');