@salesforce/afv-skills 1.44.0 → 1.46.0

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

@@ -20,16 +20,21 @@
 //
 // Emits a single JSON object to stdout:
 //   { studio: { hasAccess, signal, reason },
-//     template: { present, id, hasAgentScript, botDefinitionId, signal, reason },
+//     template: { present, id, hasAgentScript, botDefinitionId, masterLabel, signal, reason },
 //     verdict, reasons: [...] }
 // `botDefinitionId` is copied from the matched agent-templates row and passed to
 // the Phase-2 idempotency read as the PRIMARY key (the platform's authoritative
-// template→BotDefinition link); the collected developerName is the FALLBACK key
-// there. See classify-agent-existence.mjs for why. (The template row's
-// `isInstalled`/`isActivated` flags are NOT emitted: they ride the same
-// AgentTemplate join as botDefinitionId, so for agents this skill creates — which
-// never stamp `templateName` — they read false even after the agent exists, and
-// nothing downstream consumes them.)
+// template→BotDefinition link); `id` (the template's OOTB namespaced API name) is
+// passed as the AgentTemplate fallback key — it matches `BotDefinition.AgentTemplate`
+// on the pre-provisioned broad `IT_Service_Employee` agent regardless of its
+// DeveloperName, so it is THE key that catches it — and the collected developerName
+// is the last fallback (the guard for self-created agents, which carry a null
+// AgentTemplate). `masterLabel` is echoed only for the report's display label; it
+// is NOT an idempotency key (a display name is renamable and non-unique). See
+// classify-agent-existence.mjs for why. (The template row's `isInstalled`/`isActivated`
+// flags are NOT emitted: they ride the same AgentTemplate join as botDefinitionId,
+// so for agents this skill creates — which never stamp `templateName` — they read
+// false even after the agent exists, and nothing downstream consumes them.)
 // where signal is PASS | FAIL | CANNOT-CONFIRM | ERROR and verdict is
 // READY | NOT-READY | CANNOT-CONFIRM | ERROR. Exit is always 0 on usable args.
 // ERROR (studio only) means the Studio-access read returned a parseable but
@@ -117,16 +122,19 @@ function classifyTemplate(res, masterLabel) {
   }
   // Idempotency identity carried by the matched row — the platform's own link
   // from this template to the BotDefinition it was instantiated into. A populated
-  // botDefinitionId is the reliable idempotency signal for PRE-PROVISIONED agents
-  // (see classify-agent-existence.mjs): it means the agent already exists
-  // regardless of what DeveloperName this skill would have guessed. Agents this
-  // skill creates never stamp `templateName`, so their row's botDefinitionId stays
-  // null — the Phase-2 read falls back to a DeveloperName key for that case.
+  // botDefinitionId is a direct link for PRE-PROVISIONED agents; for the broad
+  // Employee agent it is null, so the template's own `id` (matched against
+  // `BotDefinition.AgentTemplate` in Phase 2) is what catches the pre-provisioned
+  // `IT_Service_Employee` regardless of what DeveloperName this skill would have
+  // guessed (see classify-agent-existence.mjs). Agents this skill creates never
+  // stamp `templateName`, so they carry BOTH a null row botDefinitionId AND a null
+  // AgentTemplate — the Phase-2 read falls back to the collected DeveloperName key
+  // for that case.
   const botDefinitionId = typeof match.botDefinitionId === 'string' && match.botDefinitionId.trim() ? match.botDefinitionId : null;
   if (!match.agentScript || typeof match.agentScript !== 'string' || !match.agentScript.trim()) {
     return { present: true, id: match.id ?? null, hasAgentScript: false, botDefinitionId, signal: 'CANNOT-CONFIRM', reason: `Matched "${masterLabel}" (id=${match.id}) but it had no agentScript field — the NGA bundle create needs the template's Agent Script content.` };
   }
-  return { present: true, id: match.id ?? null, hasAgentScript: true, botDefinitionId, signal: 'PASS', reason: `Template "${masterLabel}" present (id=${match.id}) with a non-empty agentScript${botDefinitionId ? `; already instantiated (botDefinitionId=${botDefinitionId})` : '; not yet instantiated (no botDefinitionId — the Phase-2 read falls back to DeveloperName)'} — feed it to scripts/build-create-body.mjs for the NGA bundle create.` };
+  return { present: true, id: match.id ?? null, hasAgentScript: true, botDefinitionId, signal: 'PASS', reason: `Template "${masterLabel}" present (id=${match.id}) with a non-empty agentScript${botDefinitionId ? `; already instantiated (botDefinitionId=${botDefinitionId})` : '; not yet instantiated (no botDefinitionId — the Phase-2 read keys on AgentTemplate=id, then DeveloperName)'} — feed it to scripts/build-create-body.mjs for the NGA bundle create.` };
 }
 
 const [studioPath, templatePath, rawLabel] = process.argv.slice(2);
@@ -155,11 +163,19 @@ process.stdout.write(JSON.stringify({
     id: template.id,
     hasAgentScript: template.hasAgentScript,
     // Idempotency identity (from the matched agent-templates row): the Phase-2
-    // read uses botDefinitionId as the PRIMARY key and the collected developerName
-    // as the FALLBACK. A populated botDefinitionId is the load-bearing "agent
-    // already exists" signal for pre-provisioned agents; null just means this
-    // template row was never joined (e.g. a self-created agent) — not "no agent".
+    // read uses botDefinitionId as the PRIMARY key, `id` (the template's namespaced
+    // API name) as the AgentTemplate key, and the collected developerName as the
+    // last fallback. A populated botDefinitionId is a direct "agent already exists"
+    // link; null just means this template row was never joined (e.g. a self-created
+    // agent) — not "no agent". `id` is the load-bearing catcher for the
+    // pre-provisioned broad `IT_Service_Employee`, whose DeveloperName differs from
+    // this skill's collected guess: it matches `BotDefinition.AgentTemplate`, the
+    // platform-stamped source template. `masterLabel` is echoed only for the
+    // report's display label (NOT an idempotency key). The workflow passes
+    // botDefinitionId, `id`, and the collected developerName to
+    // classify-agent-existence.mjs from this single source.
     botDefinitionId: template.botDefinitionId ?? null,
+    masterLabel,
     signal: template.signal,
     reason: template.reason,
   },

package/skills/service-itsm-agentic-setup-employee-agent-configure/scripts/render-report.mjs

@@ -148,13 +148,19 @@ if (
 
 const reason = String(state.reason ?? '').trim();
 
+// The "set up access" next step below is the handoff to the
+// `service-itsm-agentic-setup-agent-runtime-access-assign` skill (declared in
+// this skill's metadata.relatedSkills). We deliberately surface it in plain
+// admin language ("grant this agent's runtime access") rather than by raw skill
+// name — the routing metadata carries the linkage, so the user-facing report
+// stays friendly while the relationship remains discoverable.
 const NEXT_STEPS = {
   'CREATED':
-    'The IT Service Employee agent is live as an NGA-native agent (no external-link icon in Agentforce Studio). No new agent was provisioned beyond the one just created. Verify end-to-end in Agentforce Studio\'s Agents list.',
+    'The IT Service Employee agent is live as an NGA-native agent (no external-link icon in Agentforce Studio). No new agent was provisioned beyond the one just created. Verify end-to-end in Agentforce Studio\'s Agents list. **Next — set up access:** before anyone can use the agent, the user needs the runtime permissions the agent\'s actions use (Prompt Templates, Data Cloud, or Unified Catalog, depending on what is provisioned). Just ask to **grant this agent\'s runtime access** and those feature permissions — plus an "Agent Access" permission set covering the agent — will be set up for the user(s) you choose.',
   'ALREADY-CREATED':
-    'The IT Service Employee agent was already present and active — no new agent was provisioned. Verify end-to-end in Agentforce Studio\'s Agents list.',
+    'The IT Service Employee agent was already present and active — no new agent was provisioned. Verify end-to-end in Agentforce Studio\'s Agents list. **Next — set up access:** before anyone can use the agent, the user needs the runtime permissions the agent\'s actions use (Prompt Templates, Data Cloud, or Unified Catalog, depending on what is provisioned). Just ask to **grant this agent\'s runtime access** and those feature permissions — plus an "Agent Access" permission set covering the agent — will be set up for the user(s) you choose.',
   'ACTIVATED':
-    'The existing IT Service Employee agent was found inactive and has been activated — no new agent was provisioned. Verify end-to-end in Agentforce Studio\'s Agents list.',
+    'The existing IT Service Employee agent was found inactive and has been activated — no new agent was provisioned. Verify end-to-end in Agentforce Studio\'s Agents list. **Next — set up access:** before anyone can use the agent, the user needs the runtime permissions the agent\'s actions use (Prompt Templates, Data Cloud, or Unified Catalog, depending on what is provisioned). Just ask to **grant this agent\'s runtime access** and those feature permissions — plus an "Agent Access" permission set covering the agent — will be set up for the user(s) you choose.',
   'PENDING CONFIRMATION':
     'The run is paused at the confirm-to-write gate. In this skill, create + publish + activate happen as one atomic sequence gated by a single confirmation — there is no supported create-only or publish-without-activate mode, and no partial "create-only" mode of any kind. Re-run and reply "yes" when you are ready for the agent to go live.',
   'DECLINED':

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

@@ -2,10 +2,11 @@
 name: service-itsm-agentic-setup-fulfiller-agent-configure
 description: "Create and activate the IT Service Fulfiller agent as a Next-Gen Authoring (NGA) native agent from the shipped ITSM Fulfiller template's Agent Script, using the Salesforce CLI (sf): read the template, check idempotency, create the NGA bundle then publish and activate it, then verify it is live. Idempotent per developer name. The Fulfiller agent is the IT-technician-facing assistant for incident triage, case summarization, field updates, and related-record automations. Use when asked to create the Fulfiller agent, set up the IT Service Fulfiller agent, provision the fulfiller assistant, or activate the Fulfiller agent. Triggers: create fulfiller agent, set up fulfiller agent, provision fulfiller agent, activate fulfiller agent. DO NOT TRIGGER: checking org prerequisites (service-itsm-agentic-setup-agentforce-studio-validate), or CMDB CRUD."
 metadata:
-  version: "3.5"
+  version: "3.7"
   domains: ["Service", "Agentforce"]
   minApiVersion: "67.0"
   relatedSkills:
+    - "service-itsm-agentic-setup-agent-runtime-access-assign"
     - "service-itsm-agentic-setup-agentforce-studio-configure"
     - "service-itsm-agentic-setup-agentforce-studio-validate"
     - "service-itsm-agentic-setup-employee-agent-configure"
@@ -63,7 +64,7 @@ If any of these are unmet, `sf` surfaces an auth error or a `401`/`403`/`404`; *
 |---------|---------|-------|
 | Studio access (precondition read) | `sf api request rest "/services/data/v67.0/agentforce-studio/access/Agents" --method GET -o <alias>` | `hasAccess=false` ⇒ prerequisite 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 Fulfiller template + non-empty `agentScript` |
-| Enumerate the 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 (the normal Fulfiller case) 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 |
+| Enumerate the existing agent + latest version status (read) | `sf data query -q "SELECT Id,DeveloperName,MasterLabel,AgentTemplate,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'" -o <alias> --json` | Keyed PRIMARILY on the template's `botDefinitionId` (Phase-1 row); `OR AgentTemplate=` is a defensive fallback that would catch a live agent instantiated from the OOTB source template (`svc_itsm_intelligence__ITSrvcMgmtFulfiller` = Phase-1 `template.id`) regardless of its DeveloperName; `OR DeveloperName=` is the real guard here — the normal Fulfiller case (never pre-provisioned; null `AgentTemplate`) 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 |
@@ -102,7 +103,7 @@ Full command shapes and the ITSM Connect API reference live in `references/cli-i
 | Activate | POST `.../bundle-versions/<id>/activate` (create path) OR POST `.../connect/bot-versions/<latestVersionId>/activation` with `{"status":"Active"}` (reactivation path — skips create/publish) | `Bash` (`sf api request rest`) |
 | Verify | SOQL-read `BotDefinition`/`BotVersions` and confirm the agent exists with an Active latest version | `Bash` (`sf data query`) |
 
-**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 — the normal Fulfiller case — AND the guard for a **dangling** Id link whose target `BotDefinition` was deleted, so a stale link can't slip through to create), + latest `BotVersion.Status` (classified by the helper script). Outcomes: no match on either key ⇒ `exists:false` ⇒ create; `latestVersionStatus:"Active"` ⇒ **ALREADY-CREATED** (skip the write, fall through to Phase 7 verification); `needsActivation:true` (latest version `Inactive`) ⇒ **offer to activate the existing version instead of creating a new agent** (Phase 2b) rather than silently skipping or duplicating. **Why the fallback matters:** the Fulfiller is never pre-provisioned and this skill's create path never stamps `templateName`, so the template's `botDefinitionId` is always `null` — the `<developerName>`-keyed fallback is the guard that actually catches a repeat run; short-circuiting straight to create on a null `botDefinitionId` would re-create and collide with `DUPLICATE_VALUE`. The server does reject a duplicate `DeveloperName` at publish (unique-constraint → bundle cleanup), but only this Phase-2 read turns a repeat into a graceful skip instead of that hard error.
+**Idempotency**: keyed PRIMARILY on the **template's `botDefinitionId`** (Phase-1 `agent-templates` row — the platform's authoritative template→`BotDefinition` link), FALLING BACK first to the **BotDefinition's `AgentTemplate`** (the OOTB namespaced source template = Phase-1 `template.id`) and then to the collected `<developerName>`. The Phase-2 read is `BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'` (the `OR AgentTemplate=` half is a defensive key that would catch a live agent instantiated from the source template regardless of its `DeveloperName`; the `OR DeveloperName=` half is both the null-`botDefinitionId` fallback — the normal Fulfiller case — AND the guard for a **dangling** Id link whose target `BotDefinition` was deleted), + latest `BotVersion.Status` (classified by the helper script). Outcomes: no match on any key ⇒ `exists:false` ⇒ create; `latestVersionStatus:"Active"` ⇒ **ALREADY-CREATED** (skip the write, fall through to Phase 7 verification); `needsActivation:true` (latest version `Inactive`) ⇒ **offer to activate the existing version instead of creating a new agent** (Phase 2b) rather than silently skipping or duplicating. **Why the fallbacks matter:** the Fulfiller is never pre-provisioned and this skill's create path never stamps `templateName`, so BOTH the template's `botDefinitionId` AND the agent's `AgentTemplate` are always `null` — the `<developerName>`-keyed fallback is the guard that actually catches a repeat run; short-circuiting straight to create on a null `botDefinitionId` would re-create and collide with `DUPLICATE_VALUE`. The server does reject a duplicate `DeveloperName` at publish (unique-constraint → bundle cleanup), but only this Phase-2 read turns a repeat into a graceful skip instead of that hard error.
 
 ---
 
@@ -117,7 +118,7 @@ Collect from the user (ask only what is not already in conversation context):
 | Label | User-facing label for the agent | `IT Service Fulfiller Agent` |
 | Confirm the write | Explicit confirmation before the create/publish/activate sequence | **REQUIRED** — present the developerName + label and require "yes" via `AskUserQuestion` |
 
-The **idempotency read keys PRIMARILY on the template's `botDefinitionId`** (Phase-1 row) and FALLS BACK to the collected `<developerName>` when that is null; the verify read keys on the publish response's `publishedBotId` (create path) or the template's `botDefinitionId` (ALREADY-CREATED / reactivation). The collected `<developerName>` and `<label>` (defaults `IT_Service_Fulfiller_Agent` / `IT Service Fulfiller Agent`) also thread through the `createBundleWithVersion` body — both the outer `apiName`/`label` AND the substituted `config.developer_name`/`config.agent_label` inside the Agent Script. Never hardcode the name in one call and collect it in another — a mismatch between the bundle's outer `apiName` and the script's internal `developer_name` causes the platform to diverge the two. Creating an agent provisions a live, activated agent on the org; the user must explicitly approve the write.
+The **idempotency read keys PRIMARILY on the template's `botDefinitionId`** (Phase-1 row) and FALLS BACK to the BotDefinition's `AgentTemplate` (defensive — null on the never-pre-provisioned Fulfiller) and then to the collected `<developerName>`, the guard that actually catches a repeat here, when that is null; the verify read keys on the publish response's `publishedBotId` (create path) or the template's `botDefinitionId` (ALREADY-CREATED / reactivation). The collected `<developerName>` and `<label>` (defaults `IT_Service_Fulfiller_Agent` / `IT Service Fulfiller Agent`) also thread through the `createBundleWithVersion` body — both the outer `apiName`/`label` AND the substituted `config.developer_name`/`config.agent_label` inside the Agent Script. Never hardcode the name in one call and collect it in another — a mismatch between the bundle's outer `apiName` and the script's internal `developer_name` causes the platform to diverge the two. Creating an agent provisions a live, activated agent on the org; the user must explicitly approve the write.
 
 ---
 
@@ -126,8 +127,8 @@ The **idempotency read keys PRIMARILY on the template's `botDefinitionId`** (Pha
 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}`.** 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:-}")"`. 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 on stdout. All transient JSON lands 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) into `${SCRATCH_DIR}/agent-templates.json`, then classify via `scripts/classify-preflight.mjs "IT Service Fulfiller"`. 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` 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>'` with the `BotVersions` subquery (subquery is required — otherwise `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** (the normal Fulfiller case — the template row is never back-filled) ⇒ do NOT skip to create; fall back to `BotDefinition WHERE DeveloperName='<developerName>'` (a self-created agent from a prior run has a null template `botDefinitionId` but still exists). Either way classify via `scripts/classify-agent-existence.mjs ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId-or-empty>" "<developerName>"`. Branch: `exists:false` ⇒ **Phase 2c** (action-availability gate, then create); `exists:true` + `needsActivation:false` ⇒ **ALREADY-CREATED** (skip straight to Phase 7 — no action-availability gate; a live active agent's actions are already wired); `exists:true` + `needsActivation:true` ⇒ Phase 2b. Non-zero exit ⇒ surface CLI error; never assume absent. **Why the fallback:** the Fulfiller is never pre-provisioned, so `botDefinitionId` is always null — a missing developerName check would re-create and hit `DUPLICATE_VALUE`.
+1. **Phase 1 — Preflight.** Capture the Studio-access read into `${SCRATCH_DIR}/studio-access.json` and the `agent-templates` read (with the **required** `agentType=AgentforceEmployeeAgent` query param) into `${SCRATCH_DIR}/agent-templates.json`, then classify by passing **both file paths, then the label** (that arg order): `node "<skill_dir>/scripts/classify-preflight.mjs" ${SCRATCH_DIR}/studio-access.json ${SCRATCH_DIR}/agent-templates.json "IT Service Fulfiller"`. The classifier emits `template.botDefinitionId`, `template.id`, and `template.masterLabel` from the matched row — **capture all three; `botDefinitionId` is the primary Phase-2 idempotency key, `template.id` (the BotDefinition's `AgentTemplate`) the first fallback, and `<developerName>` the last fallback; `masterLabel` is the report's display label, not a key.** Branch on `verdict`: `READY` ⇒ Phase 2; `NOT-READY` ⇒ prerequisite hand-off via `AskUserQuestion` (delegate to `service-itsm-agentic-setup-agentforce-studio-validate` on "yes"); `ERROR` ⇒ surface + stop; `studio.signal="CANNOT-CONFIRM"` (confirmed 404) does not block.
+2. **Phase 2 — Idempotency (primary key `botDefinitionId`, fallbacks `AgentTemplate` then `<developerName>`).** Take `template.botDefinitionId` and `template.id` from Phase 1. **Present `botDefinitionId`** ⇒ SOQL `BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'` with the `BotVersions` subquery (subquery is required — otherwise `needsActivation` is permanently false; the `OR` clauses make a **dangling** Id link — deleted target — fall back to the live agent instead of a false `exists:false` → duplicate create). **Empty/null `botDefinitionId`** (the normal Fulfiller case — the template row is never back-filled) ⇒ do NOT skip to create; read `BotDefinition WHERE AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'` (a self-created agent from a prior run carries a null `AgentTemplate`, so `DeveloperName` is what recovers it; `AgentTemplate` would catch a hypothetical instantiated-from-template agent under any DeveloperName). `<agentTemplate>` is Phase-1 `template.id`. Either way classify via `node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId-or-empty>" "<developerName>" "<agentTemplate>"`. Branch: `exists:false` ⇒ **Phase 2c** (action-availability gate, then create); `exists:true` + `needsActivation:false` ⇒ **ALREADY-CREATED** (skip straight to Phase 7 — no action-availability gate; a live active agent's actions are already wired); `exists:true` + `needsActivation:true` ⇒ Phase 2b. Non-zero exit ⇒ surface CLI error; never assume absent. **Why the fallbacks:** the Fulfiller is never pre-provisioned, so `botDefinitionId` and `AgentTemplate` are always null — a missing developerName check would re-create and hit `DUPLICATE_VALUE`.
 3. **Phase 2b — Reactivation offer.** `AskUserQuestion`: _"Fulfiller agent `<developerName>` exists but latest version is Inactive. Activate it?"_. On **Yes**: `POST /connect/bot-versions/<latestVersionId>/activation` with `{"status":"Active"}` captured to `${SCRATCH_DIR}/activate-response.json`, then `node "<skill_dir>/scripts/classify-activate-result.mjs" ${SCRATCH_DIR}/activate-response.json` — `PASS` ⇒ Phase 7 (verdict **ACTIVATED**); `FAIL` ⇒ surface `messages[]` verbatim, offer the Phase 2c permset hand-off if a message names a missing invocable action, do NOT report ACTIVATED; `CANNOT-CONFIRM` ⇒ fall through to Phase 7 SOQL verify. On **No**: stop, no writes.
 4. **Phase 2c — Action-availability preflight (create path only; reached only from Phase 2 `exists:false`).** Capture `sf api request rest "/services/data/v67.0/actions/custom/generatePromptResponse" --method GET` to `${SCRATCH_DIR}/generate-prompt-response.json`, then `node "<skill_dir>/scripts/classify-action-availability.mjs" ${SCRATCH_DIR}/agent-templates.json "IT Service Fulfiller" ${SCRATCH_DIR}/generate-prompt-response.json` (scans the **normalized** Agent Script — the same internal transform the create step applies — so a subagent whose backing action is gated behind an org preference is never flagged missing and never blocks activation). Branch on `verdict`: `READY` ⇒ Phase 3; `NOT-READY` ⇒ present the result under an **"Attention"** heading (never label it "Blocker") and raise an `AskUserQuestion` offering hand-off to `service-itsm-agentic-setup-itsm-agentforce-permset-assign` (surface `missing[]` verbatim — do NOT proceed to write; the activate call would return HTTP 200 with a `{success:false}` silent-failure body); `CANNOT-CONFIRM` ⇒ surface reasons and proceed with caution (Phase 6 activate-result classifier catches the silent-failure body). Full contract in `references/action-availability.md`.
 5. **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 Fulfiller template's Agent Script". Proceed **only** on explicit "yes"; on "no", re-render with `verdict:"DECLINED"`.
@@ -158,7 +159,7 @@ Substitute `<alias>` with the collected target org and `<developerName>` / `<lab
 ## Verification Checklist
 
 - [ ] 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.
+- [ ] Idempotency keyed on the template's `botDefinitionId` (Phase-1 row) with the BotDefinition's `AgentTemplate` (Phase-1 `template.id`) as a defensive first fallback and the collected developerName as the real guard; `BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' OR DeveloperName='<developerName>'` (the `OR`s cover a null/dangling `botDefinitionId` and — for the never-pre-provisioned Fulfiller with a null `AgentTemplate` — a self-created repeat by DeveloperName) + 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.

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

@@ -135,13 +135,13 @@ Classifier output:
 ```json
 {
   "studio":   { "hasAccess": true, "signal": "PASS|FAIL|CANNOT-CONFIRM|ERROR", "reason": "..." },
-  "template": { "present": true, "id": "svc_itsm_intelligence__ITSrvcMgmtFulfiller", "hasAgentScript": true, "botDefinitionId": "0Xx...", "signal": "PASS|FAIL|CANNOT-CONFIRM", "reason": "..." },
+  "template": { "present": true, "id": "svc_itsm_intelligence__ITSrvcMgmtFulfiller", "hasAgentScript": true, "botDefinitionId": "0Xx...", "masterLabel": "IT Service Fulfiller", "signal": "PASS|FAIL|CANNOT-CONFIRM", "reason": "..." },
   "verdict": "READY | NOT-READY | CANNOT-CONFIRM | ERROR",
   "reasons": ["..."]
 }
 ```
 
-`template.botDefinitionId` is copied from the matched `agent-templates` row. **`botDefinitionId` is the PRIMARY Phase-2 idempotency key**, but the Fulfiller is never pre-provisioned and this skill's create path never stamps `templateName`, so its template `botDefinitionId` is `null` on every run — the collected `<developerName>` is therefore the guard that actually protects repeat runs. Carry `<developerName>` into the Phase-2 read as the fallback key. (`isInstalled`/`isActivated` are no longer emitted: they ride the same AgentTemplate join as `botDefinitionId`, so they read false for self-created agents and nothing consumes them.)
+`template.botDefinitionId`, `template.id`, and `template.masterLabel` are copied from the matched `agent-templates` row. **`botDefinitionId` is the PRIMARY Phase-2 idempotency key**, but the Fulfiller is never pre-provisioned and this skill's create path never stamps `templateName`, so BOTH its template `botDefinitionId` AND the agent's `AgentTemplate` are `null` on every run — the collected `<developerName>` (the last fallback) is therefore the guard that actually protects repeat runs; `template.id` (the BotDefinition's `AgentTemplate`) is carried as a defensive first fallback. Carry `template.id` and `<developerName>` into the Phase-2 read as the fallback keys; `masterLabel` is the report's display label, not an idempotency key. (`isInstalled`/`isActivated` are no longer emitted: they ride the same AgentTemplate join as `botDefinitionId`, so they read false for self-created agents and nothing consumes them.)
 
 `verdict=ERROR` (`studio.signal="ERROR"` — a parseable non-404 Studio-access
 error, e.g. `401`/`403`) ⇒ surface the raw error and stop; takes priority over
@@ -149,55 +149,66 @@ template state so a present template cannot outrun a failed prerequisite read.
 `verdict=NOT-READY` (studio FAIL or template FAIL) ⇒ hand off / stop.
 `verdict=READY` ⇒ proceed to Phase 2. It exits `0` on usable args.
 
-## Enumerate the existing agent — SOQL on `BotDefinition` BY Id (falling back to DeveloperName)
+## Enumerate the existing agent — SOQL on `BotDefinition` BY Id (falling back to AgentTemplate, then DeveloperName)
 
 Idempotency is keyed **PRIMARILY** on the template's `botDefinitionId` (from the
-Phase-1 row) and **FALLS BACK** to the collected `<developerName>`. If the
-Fulfiller agent already exists under a `DeveloperName` that differs from this
-skill's default guess `IT_Service_Fulfiller_Agent`, a name-only read
-false-negatives (`exists:false`) and the create then collides on `apiName` with
-`DUPLICATE_VALUE`. `botDefinitionId` is the platform's authoritative link from
-the template to the `BotDefinition` it was instantiated into — but it is
-back-filled onto the template row **only** for pre-provisioned agents, and the
-Fulfiller is never pre-provisioned: this skill's create path never stamps
-`templateName`, so its template `botDefinitionId` stays `null` on the first run
-and every run after. The `DeveloperName`-keyed fallback is therefore the guard
-that actually protects repeat runs here — never short-circuit straight to create
-when `botDefinitionId` is absent.
+Phase-1 row), **FALLS BACK** first to the BotDefinition's `AgentTemplate` (the
+OOTB namespaced source template = Phase-1 `template.id`), and then to the
+collected `<developerName>`. If the Fulfiller agent already exists under a
+`DeveloperName` that differs from this skill's default guess
+`IT_Service_Fulfiller_Agent`, a name-only read false-negatives (`exists:false`)
+and the create then collides on `apiName` with `DUPLICATE_VALUE` — the
+`DeveloperName`-keyed fallback recovers that live agent. `botDefinitionId` is the
+platform's authoritative link from the template to the `BotDefinition` it was
+instantiated into — but it is back-filled onto the template row **only** for
+pre-provisioned agents, and the Fulfiller is never pre-provisioned: this skill's
+create path never stamps `templateName`, so BOTH its template `botDefinitionId`
+AND the agent's `AgentTemplate` stay `null` on the first run and every run after.
+The `DeveloperName`-keyed fallback is therefore the guard that actually protects
+repeat runs here; the `AgentTemplate` key — which would catch a live agent
+instantiated from the source template regardless of its `DeveloperName`, far more
+reliably than a display name — is carried as a defensive/symmetric key that keeps
+this classifier identical to the Employee one (where `AgentTemplate` IS the
+load-bearing catcher). Never short-circuit straight to create when
+`botDefinitionId` is absent.
 
 - **`botDefinitionId` empty/null** (the normal Fulfiller case — template row
-  never joined) ⇒ fall back to a DeveloperName-keyed read and let the classifier
-  match on it:
+  never joined) ⇒ fall back to an `AgentTemplate` **`OR` `DeveloperName`** read and
+  let the classifier match on either:
   ```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>'" \
+  sf data query -q "SELECT Id,DeveloperName,MasterLabel,AgentTemplate,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE AgentTemplate='<agentTemplate>' 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 "" "<developerName>"
+  node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "" "<developerName>" "<agentTemplate>"
   ```
 - **`botDefinitionId` present** (a pre-provisioned instantiation, if any — never
   the normal Fulfiller case) ⇒ read the `BotDefinition` by Id **`OR` by the
-  collected `<developerName>`** in one query, then classify. The `OR DeveloperName=`
-  clause catches a **dangling** link — a `botDefinitionId` whose target row was
-  since deleted: the by-Id half returns nothing, the live same-name agent still
-  surfaces, and the classifier falls back to it (`matchedBy:"developerName"`)
-  rather than concluding `exists:false` and colliding with `DUPLICATE_VALUE`:
+  template's `AgentTemplate` `OR` by the collected `<developerName>`** in one
+  query, then classify. The `OR AgentTemplate=` clause would catch a live agent by
+  its platform-stamped source template (`matchedBy:"agentTemplate"`) regardless of
+  its DeveloperName. The `OR DeveloperName=` clause catches a **dangling**
+  link — a `botDefinitionId` whose target row was since deleted: the by-Id half
+  returns nothing, the live same-name agent still surfaces, and the classifier
+  falls back to it (`matchedBy:"developerName"`) rather than concluding
+  `exists:false` and colliding with `DUPLICATE_VALUE`:
   ```bash
-  sf data query -q "SELECT Id,DeveloperName,MasterLabel,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'" \
+  sf data query -q "SELECT Id,DeveloperName,MasterLabel,AgentTemplate,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' 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>"
+  node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId>" "<developerName>" "<agentTemplate>"
   ```
 
-Only when **both** `botDefinitionId` and `<developerName>` are absent does the
-classifier return `exists:false` without reading a query file — in practice the
-collected `<developerName>` is always present, so the fallback read always runs.
+Only when **all** of `botDefinitionId`, `<agentTemplate>`, and `<developerName>`
+are absent does the classifier return `exists:false` without reading a query
+file — in practice the collected `<developerName>` and `template.id` (AgentTemplate)
+are always present, so the fallback read always runs.
 
 The `BotVersions` subquery (child relationship on `BotDefinition`) is what lets
 the classifier see the latest version's `Status` — omit it and
 `latestVersionStatus`/`needsActivation` come back `null`/`false` even when the
 existing agent is actually inactive. The classifier prints
 `{ exists, count, matchedBy, agentId, botDefinitionId, developerName, latestVersionId, latestVersionStatus, needsActivation }`
-(`matchedBy` is `"botDefinitionId"` | `"developerName"` | `null`; `developerName`
-is the ACTUAL live agent's DeveloperName read from the record — surface it in the
-report instead of the collected guess):
+(`matchedBy` is `"botDefinitionId"` | `"agentTemplate"` | `"developerName"` | `null`;
+`developerName` is the ACTUAL live agent's DeveloperName read from the record —
+surface it in the report instead of the collected guess):
 - `exists:false` ⇒ proceed to create.
 - `exists:true` and `needsActivation:false` (latest version `Active`) ⇒
   **ALREADY-CREATED** (skip the entire create/publish/activate sequence).

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

@@ -9,12 +9,14 @@ just reactivate what's already there".
 ## When this path fires
 
 `scripts/classify-agent-existence.mjs` (called with the template's
-`botDefinitionId` as the PRIMARY idempotency key and the collected
-`DeveloperName` as the FALLBACK — see `cli-invocation.md` → "Enumerate the
-existing agent") returns
+`botDefinitionId` as the PRIMARY idempotency key, the BotDefinition's
+`AgentTemplate` — the template's OOTB source id — as the first FALLBACK, and the
+collected `DeveloperName` as the last FALLBACK —
+see `cli-invocation.md` → "Enumerate the existing agent") returns
 `{ exists:true, needsActivation:true, latestVersionId, latestVersionStatus:"Inactive" }`.
 That means a `BotDefinition` matching the collected `DeveloperName` (the
-Fulfiller's template `botDefinitionId` is null, so the fallback is what matches)
+Fulfiller's template `botDefinitionId` AND `AgentTemplate` are both null, so the
+`DeveloperName` fallback is what matches)
 already exists from a prior run of this skill but its most-recent `BotVersion` is
 inactive; creating a new bundle would produce a duplicate. Instead, flip the
 existing version to `Active`.

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

@@ -26,10 +26,10 @@ sf api request rest "/services/data/v67.0/connect/service-itsm/agent-templates?a
 node "<skill_dir>/scripts/classify-preflight.mjs" ${SCRATCH_DIR}/studio-access.json ${SCRATCH_DIR}/agent-templates.json "IT Service Fulfiller"
 ```
 
-The classifier prints `{ studio:{hasAccess,signal}, template:{present,id,hasAgentScript,botDefinitionId,signal}, verdict, reasons }`:
+The classifier prints `{ studio:{hasAccess,signal}, template:{present,id,hasAgentScript,botDefinitionId,masterLabel,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**, but the Fulfiller is never pre-provisioned and this skill's create path never stamps `templateName`, so its template `botDefinitionId` is `null` on every run — the collected `<developerName>` is the guard that actually fires. Capture `botDefinitionId` for Phase 2 and carry the collected `<developerName>` as the fallback key.
+- **`template.botDefinitionId` is the PRIMARY Phase-2 idempotency key**, but the Fulfiller is never pre-provisioned and this skill's create path never stamps `templateName`, so its template `botDefinitionId` is `null` on every run — the collected `<developerName>` and the template's `masterLabel` are the guards that actually fire. Capture `botDefinitionId` for Phase 2 and carry the collected `<developerName>` (first fallback) and `template.masterLabel` (second fallback) as the fallback keys.
 - `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**:
@@ -42,22 +42,22 @@ The classifier prints `{ studio:{hasAccess,signal}, template:{present,id,hasAgen
 
 ## 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, but it is back-filled **only** for pre-provisioned agents — and the Fulfiller is never pre-provisioned: this skill's create path never stamps `templateName`, so its template `botDefinitionId` is `null` on the first run and every run after. The `DeveloperName`-keyed fallback is therefore the guard that actually catches repeat runs (if the agent already exists under a `DeveloperName` matching the collected `<developerName>`, a name-only miss would let the create fail with `DUPLICATE_VALUE`), so never short-circuit to create when `botDefinitionId` is absent.
+Idempotency is keyed **PRIMARILY** on the template's `botDefinitionId` (captured in Phase 1), **FALLS BACK** first to the BotDefinition's `AgentTemplate` (the OOTB namespaced source template = Phase-1 `template.id`), and then to the collected `<developerName>`. The `botDefinitionId` is the platform's authoritative link from the `agent-templates` row to the `BotDefinition` it was instantiated into, but it is back-filled **only** for pre-provisioned agents — and the Fulfiller is never pre-provisioned: this skill's create path never stamps `templateName`, so BOTH its template `botDefinitionId` AND the agent's `AgentTemplate` are `null` on the first run and every run after. The `DeveloperName`-keyed fallback is therefore the guard that actually catches repeat runs (if the agent already exists under a `DeveloperName` matching the collected `<developerName>`, a name-only miss would let the create fail with `DUPLICATE_VALUE`); the `AgentTemplate` key — which would recover a live agent instantiated from the source template regardless of its `DeveloperName`, far more reliably than a display name — is carried as a defensive/symmetric key that keeps this classifier identical to the Employee one (where `AgentTemplate` IS the load-bearing catcher). Never short-circuit to create when `botDefinitionId` is absent.
 
-- **`template.botDefinitionId` is empty/null** (the normal Fulfiller case) ⇒ 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:
+- **`template.botDefinitionId` is empty/null** (the normal Fulfiller case) ⇒ fall back to an `AgentTemplate` **`OR` `DeveloperName`** read (do **not** short-circuit to create — a self-created agent from a prior run carries a null `AgentTemplate`, so `DeveloperName` is what recovers it). 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>'" \
+  sf data query -q "SELECT Id,DeveloperName,MasterLabel,AgentTemplate,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE AgentTemplate='<agentTemplate>' 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 "" "<developerName>"
+  node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "" "<developerName>" "<agentTemplate>"
   ```
-- **`template.botDefinitionId` is present** (a pre-provisioned instantiation, if any — never the normal Fulfiller case) ⇒ read the `BotDefinition` by Id **`OR` by the collected `<developerName>`** in one query, 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`:
+- **`template.botDefinitionId` is present** (a pre-provisioned instantiation, if any — never the normal Fulfiller case) ⇒ read the `BotDefinition` by Id **`OR` by the template's `AgentTemplate` `OR` by the collected `<developerName>`** in one query, INCLUDING its latest version's status, then classify. The `OR AgentTemplate=` clause would catch a live agent by its platform-stamped source template (`matchedBy:"agentTemplate"`) regardless of its DeveloperName. The `OR DeveloperName=` clause 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>'" \
+  sf data query -q "SELECT Id,DeveloperName,MasterLabel,AgentTemplate,(SELECT Id,Status FROM BotVersions ORDER BY VersionNumber DESC LIMIT 1) FROM BotDefinition WHERE Id='<botDefinitionId>' OR AgentTemplate='<agentTemplate>' 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>"
+  node "<skill_dir>/scripts/classify-agent-existence.mjs" ${SCRATCH_DIR}/bot-existing.json "<botDefinitionId>" "<developerName>" "<agentTemplate>"
   ```
 
-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, surface it in the report rather than the collected guess:
+The classifier prints `{ exists, count, matchedBy, agentId, botDefinitionId, developerName, latestVersionId, latestVersionStatus, needsActivation }` — `matchedBy` is `"botDefinitionId"` | `"agentTemplate"` | `"developerName"` | `null`, and `developerName` is the ACTUAL live agent's DeveloperName read from the record, 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.