@salesforce/afv-skills 1.40.0 → 1.41.0

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

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+// Deterministic preflight classifier for the Employee-agent create flow.
+//
+// Two fixed JSON-parsing / decision rules that must not live in model prose
+// (authoring standard A9):
+//   1. Studio access: read `hasAccess` from the agentforce-studio/access/Agents
+//      body → PASS (true) / FAIL (false) / CANNOT-CONFIRM (404 / not wired).
+//   2. Template provisioning: find the agent-templates item whose masterLabel
+//      matches the target ("IT Service Employee"), confirm it carries a non-empty
+//      `agentScript` (the Agent Script YAML fed into the NGA bundle create) → PRESENT
+//      (+hasAgentScript) / ABSENT (empty data[] or no match) / CANNOT-CONFIRM
+//      (404 / not wired).
+//
+// Usage:
+//   node classify-preflight.mjs <studio-access.json> <agent-templates.json> <masterLabel>
+//
+// Both file args are paths to raw `sf api request rest` stdout captures; the
+// files may hold a Connect error array or be empty when the CLI exited non-zero.
+// <masterLabel> is the template's display label (default "IT Service Employee").
+//
+// Emits a single JSON object to stdout:
+//   { studio: { hasAccess, signal, reason },
+//     template: { present, id, hasAgentScript, botDefinitionId, 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.)
+// 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
+// non-404 error body (401/403/unexpected) — that is a failed prerequisite
+// read, not an unwired gate, so it must stop the workflow rather than fall
+// through to a CANNOT-CONFIRM that a present template can outrun to READY.
+
+import { readFileSync } from 'node:fs';
+
+function readJson(path) {
+  try {
+    const text = readFileSync(path, 'utf8').trim();
+    if (!text) return { ok: false };
+    return { ok: true, data: JSON.parse(text) };
+  } catch {
+    return { ok: false };
+  }
+}
+
+function asErrorArray(data) {
+  if (Array.isArray(data)) return data.filter((e) => e && (e.errorCode || e.message));
+  if (data && (data.errorCode || data.message)) return [data];
+  return [];
+}
+
+function isNotFoundError(data) {
+  return asErrorArray(data).some((e) => {
+    const code = String(e?.errorCode ?? '').toUpperCase();
+    const msg = String(e?.message ?? '').toUpperCase();
+    return code.includes('NOT_FOUND') || code.includes('NOT_EXIST') ||
+      msg.includes('NOT FOUND') || msg.includes('DOES NOT EXIST') ||
+      msg.includes('COULD NOT BE FOUND');
+  });
+}
+
+function errorSnippet(errs) {
+  return errs.map((e) => `${e.errorCode ?? 'ERROR'}: ${e.message ?? ''}`.trim()).join(' | ').slice(0, 500);
+}
+
+function classifyStudio(res) {
+  if (!res.ok) {
+    return { hasAccess: null, signal: 'CANNOT-CONFIRM', reason: 'Studio access — no readable body (endpoint not wired / empty). A successful create/publish/activate is authoritative.' };
+  }
+  const d = res.data;
+  const errs = asErrorArray(d);
+  if (errs.length) {
+    if (isNotFoundError(d)) return { hasAccess: null, signal: 'CANNOT-CONFIRM', reason: 'Studio access → 404 (access-check gate not wired on this org). Treat as cannot-confirm; a successful create/publish/activate is authoritative.' };
+    return { hasAccess: null, signal: 'ERROR', reason: `Studio access read failed: ${errorSnippet(errs)} — surface the raw response and stop; do not treat as an unwired gate.` };
+  }
+  if (d?.hasAccess === true) return { hasAccess: true, signal: 'PASS', reason: 'Studio access → hasAccess=true.' };
+  if (d?.hasAccess === false) return { hasAccess: false, signal: 'FAIL', reason: 'Studio access → hasAccess=false — offer the prerequisite readiness hand-off before any write.' };
+  return { hasAccess: null, signal: 'CANNOT-CONFIRM', reason: 'Studio access body had no boolean hasAccess field.' };
+}
+
+function classifyTemplate(res, masterLabel) {
+  if (!res.ok) {
+    return { present: false, id: null, hasAgentScript: false, signal: 'CANNOT-CONFIRM', reason: 'agent-templates — no readable body (endpoint not wired / empty).' };
+  }
+  const d = res.data;
+  if (asErrorArray(d).length) {
+    if (isNotFoundError(d)) return { present: false, id: null, hasAgentScript: false, signal: 'CANNOT-CONFIRM', reason: 'agent-templates → 404 (ITSM Connect namespace not provisioned). Hand off to the readiness check.' };
+    return { present: false, id: null, hasAgentScript: false, signal: 'CANNOT-CONFIRM', reason: 'agent-templates read returned an error body — surface it.' };
+  }
+  const items = Array.isArray(d?.data) ? d.data : null;
+  if (!items) return { present: false, id: null, hasAgentScript: false, signal: 'CANNOT-CONFIRM', reason: 'agent-templates had no data[] array (unexpected shape).' };
+  // Filter to the only namespace this skill instantiates. The endpoint also
+  // returns Fulfiller-side (`svc_itsm_intelligence__*`), Slack, ServiceNow,
+  // Runtime Insights, and other-namespace entries — some carry masterLabels
+  // that collide with in-namespace entries (e.g. `System Password Reset
+  // Assistance` exists in both `svc_emp_intelligence__` and `EmpSvcAgent__`).
+  // A `masterLabel`-only match would silently pick whichever appeared first
+  // in `data[]`; filtering first pins the choice to the correct namespace.
+  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) {
+    return {
+      present: false, id: null, hasAgentScript: false, signal: 'FAIL',
+      reason: items.length === 0
+        ? 'agent-templates returned an empty data[] — wrong agentType or the org is not ITSM-provisioned; hand off to the readiness check.'
+        : inNamespace.length === 0
+          ? `agent-templates returned ${items.length} entries but none under the svc_emp_intelligence__ namespace — the Employee IT Service feature toggles are not provisioned on this org; hand off to the readiness check.`
+          : `No svc_emp_intelligence__ template with masterLabel "${masterLabel}" (got: ${inNamespace.map((i) => i?.masterLabel).filter(Boolean).join(', ') || 'none'}). Hand off to the readiness check.`,
+    };
+  }
+  // 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.
+  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.` };
+}
+
+const [studioPath, templatePath, rawLabel] = process.argv.slice(2);
+if (!studioPath || !templatePath) {
+  process.stderr.write('usage: node classify-preflight.mjs <studio-access.json> <agent-templates.json> [masterLabel]\n');
+  process.exit(2);
+}
+const masterLabel = rawLabel && rawLabel.trim() ? rawLabel : 'IT Service Employee';
+
+const studio = classifyStudio(readJson(studioPath));
+const template = classifyTemplate(readJson(templatePath), masterLabel);
+
+// Verdict: the template MUST be present to create. Studio FALSE blocks (hand-off);
+// Studio ERROR (non-404 failed read, e.g. 401/403) blocks — surface it, stop.
+// Studio CANNOT-CONFIRM (confirmed 404 gate) does not block — create/publish/activate is authoritative.
+let verdict;
+if (studio.signal === 'ERROR') verdict = 'ERROR';
+else if (studio.signal === 'FAIL' || template.signal === 'FAIL') verdict = 'NOT-READY';
+else if (template.signal === 'PASS') verdict = 'READY'; // studio PASS, or unconfirmed via a documented 404 gate — template present is enough to attempt
+else verdict = 'CANNOT-CONFIRM';
+
+process.stdout.write(JSON.stringify({
+  studio: { hasAccess: studio.hasAccess, signal: studio.signal, reason: studio.reason },
+  template: {
+    present: template.present,
+    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".
+    botDefinitionId: template.botDefinitionId ?? null,
+    signal: template.signal,
+    reason: template.reason,
+  },
+  verdict,
+  reasons: [studio.reason, template.reason],
+}, null, 2) + '\n');

package/skills/service-itsm-agentic-setup-employee-agent-configure/scripts/create-scratch-dir.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Deterministic Phase-0 scratch-directory creator for the Employee-agent
+// create/activate flow.
+//
+// Phase-0 path selection + `mkdtemp` behavior are deterministic and must not
+// live in workflow prose (authoring standard A9).
+//
+// The scratch dir MUST stay OUTSIDE the harness's scored `${outputDir}` tree.
+// Several phases capture raw `sf api request rest` stdout, and that command is
+// in beta — it prints beta/update/plugin diagnostics to STDERR. If an agent
+// captures combined output (`2>&1`) instead of the documented `2>…err` split,
+// that stderr preamble is merged into the captured file; a raw capture rooted
+// under `${outputDir}` would then land in the eval's scored artifact set and
+// fail the `core:json-valid` assertion even though the response body itself is
+// well-formed JSON. So the scratch dir roots under `${TMPDIR}` (private,
+// user-scoped), then `/tmp`, and only as an ultimate fallback (both temp bases
+// unwritable) under the harness `${outputDir}`. `mkdtempSync` creates the run
+// dir mode 0700 (owner-only) with a random suffix, so the world-writable `/tmp`
+// parent is not a concern. Only the durable `${outputDir}/report.md` (written
+// directly by render-report.mjs) is ever meant to be scored.
+//
+// Usage:
+//   node create-scratch-dir.mjs [outputDir]
+//
+// Emits the absolute path of the created directory to stdout (a single line,
+// trailing newline). Exit 0 on success, 3 when no candidate base is writable.
+
+import { mkdtempSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PREFIX = 'itsm-employee-agent.';
+
+// Candidate scratch bases, in priority order. `${outputDir}` is LAST so
+// transient captures never enter the scored tree except when no temp dir works.
+const candidates = [];
+const tmp = (process.env.TMPDIR ?? '').trim();
+if (tmp) candidates.push(tmp);
+candidates.push('/tmp');
+const outputDir = (process.argv[2] ?? '').trim();
+if (outputDir) candidates.push(outputDir);
+
+let dir = null;
+let lastErr = null;
+for (const base of candidates) {
+  try {
+    dir = mkdtempSync(join(base, PREFIX));
+    break;
+  } catch (err) {
+    lastErr = err;
+  }
+}
+
+if (dir) {
+  process.stdout.write(`${dir}\n`);
+} else {
+  process.stderr.write(`error: mkdtemp failed under all of [${candidates.join(', ')}]: ${lastErr?.message ?? 'no base dir'}\n`);
+  process.exit(3);
+}

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

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+// Deterministic renderer for the Employee-agent create/activate report.
+//
+// Composing the report from phase state in model prose is unreliable
+// (authoring standard A9) — the layout, field placement, and next-step
+// wording all belong in a script that emits byte-identical output for a
+// given state input. This helper is the single source of report text for
+// both the chat-turn response and the harness's ${outputDir}/report.md
+// file, so the two never diverge.
+//
+// Usage:
+//   node render-report.mjs <state.json> [outPath]
+//
+// state.json shape (all fields optional except `verdict`):
+//   {
+//     "org":          string,
+//     "template":     { "masterLabel": string, "id": string, "kind": "broad" | "specialized" },
+//     "developerName":string,
+//     "label":        string,
+//     "preflight":    { "studioHasAccess": "true" | "false" | "cannot-confirm",
+//                       "templateAgentScriptPresent": "yes" | "no" | "pending" },
+//     "enumerate":    { "existsBeforeWrite": "yes" | "no" | "pending",
+//                       "latestVersionStatus": "Active" | "Inactive" | "n/a" | "pending" },
+//     "confirmToWrite": "true" | "false" | "pending",
+//     "createBundle": string,
+//     "publish":      string,
+//     "activate":     string,
+//     "verify":       string,
+//     "verdict":      "CREATED" | "ALREADY-CREATED" | "ACTIVATED" |
+//                     "PENDING CONFIRMATION" | "DECLINED" | "FAILED",
+//     "reason":       string
+//   }
+//
+// If `outPath` is provided, writes to that path; otherwise emits to stdout.
+// The rendered report is always ~30 lines and shape-identical run to run.
+
+import { readFileSync, writeFileSync } from 'node:fs';
+
+const [statePath, outPath] = process.argv.slice(2);
+if (!statePath) {
+  process.stderr.write('usage: node render-report.mjs <state.json> [outPath]\n');
+  process.exit(2);
+}
+
+let state;
+try {
+  state = JSON.parse(readFileSync(statePath, 'utf8'));
+} catch (err) {
+  process.stderr.write(`error: could not read/parse ${statePath}: ${err.message}\n`);
+  process.exit(3);
+}
+
+const VALID_VERDICTS = new Set([
+  'CREATED', 'ALREADY-CREATED', 'ACTIVATED',
+  'PENDING CONFIRMATION', 'DECLINED', 'FAILED',
+]);
+const verdict = String(state?.verdict ?? '').trim();
+if (!VALID_VERDICTS.has(verdict)) {
+  process.stderr.write(`error: verdict "${verdict}" is not one of: ${[...VALID_VERDICTS].join(', ')}\n`);
+  process.exit(3);
+}
+
+function field(v, fallback = 'pending') {
+  const s = v === undefined || v === null ? '' : String(v).trim();
+  return s === '' ? fallback : s;
+}
+
+const org = field(state.org, '<unspecified>');
+const tmplLabel = field(state?.template?.masterLabel, 'IT Service Employee');
+const tmplId = field(state?.template?.id, 'svc_emp_intelligence__ItEmployeeAssistance');
+const tmplKind = field(state?.template?.kind, 'broad umbrella');
+const devName = field(state.developerName, '<pending>');
+const label = field(state.label, '<pending>');
+
+const preStudio = field(state?.preflight?.studioHasAccess, 'pending');
+const preTmpl = field(state?.preflight?.templateAgentScriptPresent, 'pending');
+const enumExists = field(state?.enumerate?.existsBeforeWrite, 'pending');
+const enumVer = field(state?.enumerate?.latestVersionStatus, 'pending');
+
+function classifyPreflightVerdict() {
+  const explicit = field(state?.preflight?.verdict, '');
+  if (explicit !== 'pending' && explicit !== '') return explicit;
+  if (preStudio === 'false' || preTmpl === 'no') return 'NOT-READY';
+  const okStudio = preStudio === 'true';
+  const okTmpl = preTmpl === 'yes';
+  if (okStudio && okTmpl) return 'READY';
+  if (preStudio === 'cannot-confirm' || preTmpl === 'pending') return 'CANNOT-CONFIRM';
+  return 'pending';
+}
+function classifyEnumerate() {
+  const explicit = field(state?.enumerate?.verdict, '');
+  if (explicit !== 'pending' && explicit !== '') return explicit;
+  if (enumExists === 'yes') {
+    if (enumVer === 'Active') return 'exists:true, needsActivation:false';
+    if (enumVer === 'Inactive') return 'exists:true, needsActivation:true';
+    return 'exists:true';
+  }
+  if (enumExists === 'no') return 'exists:false';
+  return 'pending';
+}
+const preVerdict = classifyPreflightVerdict();
+const enumVerdict = classifyEnumerate();
+
+const confirm = field(state.confirmToWrite, 'pending');
+const isPending = verdict === 'PENDING CONFIRMATION';
+const isDeclined = verdict === 'DECLINED';
+const isCreated = verdict === 'CREATED';
+const isActivated = verdict === 'ACTIVATED';
+const isAlready = verdict === 'ALREADY-CREATED';
+const isFailed = verdict === 'FAILED';
+const gatedFallback = isPending
+  ? 'pending confirmation'
+  : isDeclined ? 'skipped'
+  : isAlready ? 'skipped (already exists)'
+  : isFailed ? 'skipped'
+  : 'pending';
+
+const bundleVersionId = field(state.bundleVersionId, '');
+const bundleVersionIdSuffix = bundleVersionId ? ` bundleVersionId=${bundleVersionId}` : '';
+const onBundleVersionId = bundleVersionId ? ` on bundleVersionId=${bundleVersionId}` : '';
+
+function withCreateSuffix(base) {
+  if (base === 'pending' || base.startsWith('skipped') || base === 'pending confirmation') return base;
+  return `${base}${bundleVersionIdSuffix}`;
+}
+function withPublishActivateSuffix(base) {
+  if (base === 'pending' || base.startsWith('skipped') || base === 'pending confirmation') return base;
+  return `${base}${onBundleVersionId}`;
+}
+
+const createBundle = withCreateSuffix(field(state.createBundle, gatedFallback));
+const publish = withPublishActivateSuffix(field(state.publish, gatedFallback));
+const activate = withPublishActivateSuffix(field(state.activate, gatedFallback));
+const verifyFallback = isDeclined || isPending || isFailed
+  ? 'skipped'
+  : isAlready
+    ? `exists:true; latestVersionStatus=${enumVer}`
+    : 'pending';
+let verify = field(state.verify, verifyFallback);
+if (
+  (isCreated || isActivated) &&
+  verify !== 'pending' &&
+  !verify.startsWith('skipped') &&
+  !/exists\s*[:=]/i.test(verify)
+) {
+  verify = `${verify}; exists:true; latestVersionStatus=Active`;
+}
+
+const reason = String(state.reason ?? '').trim();
+
+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.',
+  '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.',
+  '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.',
+  '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':
+    'No write occurred. This skill\'s create + publish + activate run 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. The user\'s decline (or "hold off on activation") kept the run at the gate. Re-run and confirm when ready for the full sequence.',
+  'FAILED':
+    reason
+      ? `Review the Reason above and remediate. Enablement of missing prerequisites is a Setup-UI/admin action outside this skill's scope — use \`service-itsm-agentic-setup-agentforce-studio-validate\` or \`service-itsm-agentic-setup-agentforce-studio-configure\` to check/enable readiness first. Re-run this skill once the blocker is resolved.`
+      : 'Review the observed error and remediate. Enablement of missing prerequisites is a Setup-UI/admin action outside this skill\'s scope — use `service-itsm-agentic-setup-agentforce-studio-validate` or `service-itsm-agentic-setup-agentforce-studio-configure` to check/enable readiness first. Re-run this skill once the blocker is resolved.',
+};
+
+const report = `# Employee Agent — Create & Activate
+
+IT Service Employee Agent Creation (via service-itsm-agentic-setup-employee-agent-configure)
+
+Org:      ${org} (API v67.0)
+Template: ${tmplLabel} (id=${tmplId}) — ${tmplKind}
+Source:   ${tmplId} Agent Script
+Agent:    ${devName} ("${label}") — NGA-native bundle
+
+  Preflight  ......................... Studio hasAccess=${preStudio}; template agentScript present=${preTmpl}; verdict=${preVerdict}
+  Enumerate  ......................... target agent exists before write=${enumExists}; latest version status=${enumVer}; verdict=${enumVerdict}
+  Confirm-to-write ................... user-confirmed=${confirm}${(confirm === 'true' && (devName !== '<pending>' || label !== '<pending>')) ? `; confirmed developerName=${devName}, label="${label}"` : ''}
+  Create bundle ...................... ${createBundle}
+  Publish ............................ ${publish}
+  Activate ........................... ${activate}
+  Verify ............................. ${verify}
+
+Verdict: ${verdict}
+Reason:  ${reason}
+
+Next steps:
+  - ${NEXT_STEPS[verdict]}
+`;
+
+if (outPath) {
+  writeFileSync(outPath, report, 'utf8');
+  process.stdout.write(outPath + '\n');
+} else {
+  process.stdout.write(report);
+}

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

@@ -0,0 +1,186 @@
+---
+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.3"
+  domains: ["Service", "Agentforce"]
+  minApiVersion: "67.0"
+  relatedSkills:
+    - "service-itsm-agentic-setup-agentforce-studio-configure"
+    - "service-itsm-agentic-setup-agentforce-studio-validate"
+    - "service-itsm-agentic-setup-employee-agent-configure"
+    - "service-itsm-agentic-setup-itsm-agentforce-permset-assign"
+  cliTools:
+    - tool: ["node"]
+      semver: ">=18.0.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  accessCheck:
+    - type: "license"
+      value: "Agentforce"
+allowed-tools: |
+  Bash
+  Read
+  Write
+  AskUserQuestion
+---
+
+# Create the IT Service Fulfiller Agent
+
+Create and activate the **IT Service Fulfiller Agent** as a **Next-Gen Authoring (NGA) native agent** — Agent-Script-based (`AiAuthoringBundleDefVer`/bundle), appearing natively in Agentforce Studio's Agents list with no external-link icon — entirely through the **Salesforce CLI (`sf`)**. **This skill does not call the legacy `/connect/service-itsm/createAgent`**; instead it reuses the shipped ITSM Fulfiller template's `agentScript` and feeds it into the NGA bundle pipeline:
+
+1. `POST /nextgen-authoring/bundles` (`createBundleWithVersion`) — creates the bundle + first version from the template's Agent Script.
+2. `POST /nextgen-authoring/bundle-versions/{id}/publish` — publishes the version (creates the underlying `BotDefinition`/`BotVersion`).
+3. `POST /nextgen-authoring/bundle-versions/{id}/activate` — activates it.
+
+Commands: `sf api request rest` for Connect API GET/POST; `sf data query` for the SOQL idempotency + verify reads.
+
+Helper scripts (invoked via `Bash`) hold every JSON-parsing / decision rule so the model never eyeballs a response body (A9): `classify-preflight.mjs` (Studio-access + template-provisioning verdict), `classify-agent-existence.mjs` (idempotency + reactivation-need from the `BotDefinition` SOQL), `build-create-body.mjs` (HTML-decodes and substitutes the template's `agentScript`, writes the bundle-create body to a JSON file so large content and free-text quotes never hit an inline shell string), `render-report.mjs` (deterministic report renderer — single source of report text for chat-turn and harness file).
+
+The Fulfiller agent is the **IT-technician-facing assistant** — incident triage, case summarization, field updates, related-record automations. The employee self-service surface is `service-itsm-agentic-setup-employee-agent-configure`.
+
+## Scope
+
+- **In scope**: Reading `agent-templates`; extracting the Fulfiller template's Agent Script (`svc_itsm_intelligence__ITSrvcMgmtFulfiller`); creating the Fulfiller agent as an **NGA-native agent** via `createBundleWithVersion` → `publish` → `activate`; SOQL-verifying live; idempotent skip on duplicate developer name — all via `sf`.
+- **Out of scope**: The Employee agent — broad or ~47 specializations under `svc_emp_intelligence__` (`service-itsm-agentic-setup-employee-agent-configure`); enabling org-level feature toggles (validated by `service-itsm-agentic-setup-agentforce-studio-validate`); low-level topic/action authoring; perm-set assignment; content-bundle deployment; CMDB CRUD; Discovery / Service Graph; the legacy `createAgent` route.
+
+---
+
+## Preconditions
+
+If any of these are unmet, `sf` surfaces an auth error or a `401`/`403`/`404`; **surface the raw error verbatim and stop — do not fabricate state**.
+
+1. **`sf` CLI authenticated** to the target org (`sf org display -o <alias>` shows Connected). All calls use `--target-org <alias>`; never extract the access token by hand.
+2. **API v67.0+** — pinned in the URL path; do not hand-edit below the minimum.
+3. **ITSM features + Fulfiller template provisioned** (`svc_itsm_intelligence__ITSrvcMgmtFulfiller`). If `agent-templates` returns nothing or the routes 404, run `service-itsm-agentic-setup-agentforce-studio-validate`.
+4. **`node` ≥ 18** on PATH.
+
+---
+
+## Operations at a glance
+
+| Concern | Command | Notes |
+|---------|---------|-------|
+| Studio access (precondition read) | `sf api request rest "/services/data/v67.0/agentforce-studio/access/Agents" --method GET -o <alias>` | `hasAccess=false` ⇒ prereq hand-off |
+| List agent templates + Agent Script (read) | `sf api request rest "/services/data/v67.0/connect/service-itsm/agent-templates?agentType=AgentforceEmployeeAgent" --method GET -o <alias>` | `agentType=AgentforceEmployeeAgent` required; confirms 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 |
+| **Create the NGA bundle** (write) | `sf api request rest "/services/data/v67.0/nextgen-authoring/bundles" --method POST --body @<body-file> -o <alias>` | Body built by `scripts/build-create-body.mjs`; response `id` = the bundle **version** Id |
+| **Publish the bundle version** (write) | `sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/publish" --method POST --body '{}' -o <alias>` | Returns `publishedBotId`/`publishedBotVersionId` — creates the underlying `BotDefinition`/`BotVersion` |
+| **Activate the bundle version** (write) | `sf api request rest "/services/data/v67.0/nextgen-authoring/bundle-versions/<bundleVersionId>/activate" --method POST --body '{}' -o <alias>` | Empty response on success; agent is now live and NGA-native |
+| **Activate an existing inactive version** (write) | `sf api request rest "/services/data/v67.0/connect/bot-versions/<latestVersionId>/activation" --method POST --body '{"status":"Active"}' -o <alias>` | Reactivation path only (Phase 2b) — skips create/publish |
+| Verify agent is live (read) | `sf data query -q "SELECT ... FROM BotDefinition WHERE Id='<verifyId>'" -o <alias> --json` | `<verifyId>` = create path's `publishedBotId` (Phase-5) or the Phase-2 classifier's returned live matched Id (its `botDefinitionId`/`agentId`) on ALREADY-CREATED / reactivation — not the null Phase-1 template `botDefinitionId`, never the collected developerName; confirm `BotDefinition` present + latest version Active |
+
+Full command shapes and the ITSM Connect API reference live in `references/cli-invocation.md`; the reactivation-path call + idempotency verdict table live in `references/reactivation.md`; the response-body error codes and recurring gotchas live in `references/error-taxonomy.md`.
+
+> **Never extract the access token.** Use `sf api request rest` / `sf data query` directly — they use the CLI's stored session for the target org. Do **not** pull the `accessToken` out of `sf org display` and hand-build an HTTP request with it; that bypasses the CLI session and leaks a bearer token into shell context.
+
+> **`--json` rule.** `sf data query` **takes** `--json` (results come back in a `.result.records[]` envelope — that's what the classifier expects). `sf api request rest` does **not** — omit `--json` there; its raw stdout body is already JSON.
+
+---
+
+## Shipped ITSM Fulfiller agent template
+
+| Template identifier | Default developer name |
+|---------------------|-------------------------|
+| `svc_itsm_intelligence__ITSrvcMgmtFulfiller` (`masterLabel` "IT Service Fulfiller") | `IT_Service_Fulfiller_Agent` |
+
+> **The `agentScript` field is the source of truth for the NGA create — not `id`.** `scripts/build-create-body.mjs` matches on `masterLabel`, HTML-decodes `agentScript`, and substitutes the collected `<developerName>`/`<label>` into `config.developer_name`/`config.agent_label` before it becomes the bundle's `resourceContent`. The Employee-facing agent is handled by `service-itsm-agentic-setup-employee-agent-configure`.
+
+---
+
+## Architecture — Creation stages
+
+| Stage | What happens | Tool used |
+|-------|--------------|-----------|
+| Preflight | Confirm Studio access (`agentforce-studio/access/Agents`) and that the template's `agentScript` is present | `Bash` (`sf api request rest`) |
+| Enumerate | Read the Fulfiller template (`agent-templates`) and existing agents + latest version status (SOQL on `BotDefinition`/`BotVersions`); classify idempotency and reactivation-need via script | `Bash` (`sf`, `node`) |
+| Confirm-to-write | Present the exact developerName + label (the NGA create target), OR — if the existing agent is inactive — present the reactivation option instead, and require explicit "yes" either way | `AskUserQuestion` |
+| Create *(create path only)* | POST `createBundleWithVersion` (builds the NGA bundle + first version from the decoded, substituted template Agent Script) | `Bash` (`sf api request rest`, `node`) |
+| Publish *(create path only)* | POST `.../bundle-versions/<id>/publish` (creates the underlying `BotDefinition`/`BotVersion`) | `Bash` (`sf api request rest`) |
+| 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.
+
+---
+
+## Clarifying Questions
+
+Collect from the user (ask only what is not already in conversation context):
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| Target org | The `sf` org alias to create the agent in | Default org (`sf config get target-org`) |
+| Developer name | Unique `DeveloperName` for the agent | `IT_Service_Fulfiller_Agent` |
+| 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.
+
+---
+
+## Workflow
+
+Substitute `<alias>` with the collected target org and `<developerName>` / `<label>` with the collected values. Full command shapes + per-phase verdict-branch handling live in `references/workflow-detail.md` — the phase summary below names each step and its load-bearing rule; the reference file holds the exact `sf` / `node` invocations to copy.
+
+0. **Phase 0 — Establish `${SCRATCH_DIR}`.** 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`.
+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`. Branch on `verdict`: `READY` ⇒ Phase 3; `NOT-READY` ⇒ `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"`.
+6. **Phase 4 — Create.** `scripts/build-create-body.mjs ${SCRATCH_DIR}/agent-templates.json "IT Service Fulfiller" "<developerName>" "<label>" ${SCRATCH_DIR}/create-bundle-body.json` (helper re-reads Phase-1 templates JSON, HTML-decodes the matched `agentScript`, substitutes internal `config.developer_name`/`config.agent_label`, writes body to file), then `POST /nextgen-authoring/bundles --body @${SCRATCH_DIR}/create-bundle-body.json`. **Capture response `id`** — that is the `bundleVersionId` for Phases 5–6, not `bundleId`. `403 FUNCTIONALITY_NOT_ENABLED`/`404` ⇒ trigger the Phase-1 hand-off; build-script exit 3 ⇒ surface stderr.
+7. **Phase 5 — Publish.** `POST /nextgen-authoring/bundle-versions/<bundleVersionId>/publish --body '{}'` (empty body required). Success: `{ lastPublishedOn, publishedBotId, publishedBotVersionId }` — this call creates the underlying `BotDefinition`/`BotVersion`. Any error ⇒ surface verbatim; never activate an unpublished version.
+8. **Phase 6 — Activate.** `POST /nextgen-authoring/bundle-versions/<bundleVersionId>/activate --body '{}'` captured to `${SCRATCH_DIR}/activate-response.json`, then `node "<skill_dir>/scripts/classify-activate-result.mjs" ${SCRATCH_DIR}/activate-response.json` — activate can return HTTP 200 with a `{success:false}` silent-failure body when a referenced invocable action isn't surfaced; the classifier catches that. `PASS` ⇒ Phase 7; `FAIL` ⇒ surface `messages[]`, offer Phase 2c permset hand-off if a message names a missing action, do NOT report CREATED; `CANNOT-CONFIRM` ⇒ fall through to Phase 7 SOQL verify.
+9. **Phase 7 — Verify.** SOQL `BotDefinition WHERE Id='<id>'` (+ `BotVersions` subquery) and classify — `<id>` is the create path's `publishedBotId` (captured from Phase 5) or, on the ALREADY-CREATED / reactivation path, the **live matched Id the Phase-2 classifier returned** (its `botDefinitionId`/`agentId` output — the actual `BotDefinition.Id` of the matched record), **not** the Phase-1 template `botDefinitionId` (which is always null for the Fulfiller, so on any existing-agent hit the verify would run `WHERE Id=''` and falsely report failure after a successful skip/activation). Confirm `exists:true, count:1, latestVersionStatus:"Active"`. Any discrepancy ⇒ report verbatim, do not fabricate success.
+10. **Phase 8 — Aggregate verdict.** Emit CREATED / ALREADY-CREATED / ACTIVATED / FAILED (ACTIVATED on the Phase-2b path) + `BotDefinition` Id / bundle `id` by re-invoking `render-report.mjs` — the single source of report text. If `${outputDir}` was provided, overwrite `${outputDir}/report.md`; otherwise emit stdout as the turn-side report.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| All calls go through `sf api request rest` / `sf data query`; **never extract the access token** | Leaks a bearer token into shell context; the CLI's stored session is the correct surface |
+| Idempotency read keys PRIMARILY on the template's `botDefinitionId` (Phase-1 row), falling back to the collected `<developerName>` when null; the verify read keys on the publish `publishedBotId` / `botDefinitionId`; that same `<developerName>`/`<label>` also thread through the create body (outer `apiName`/`label` AND the substituted `config.developer_name`/`config.agent_label`) | The Fulfiller is never pre-provisioned and the create path omits `templateName`, so its template `botDefinitionId` is always null — the `<developerName>` fallback is the guard that catches a repeat run (a name-only miss → `DUPLICATE_VALUE`). A create-body hardcode/collect mismatch diverges the bundle's outer identity from the script's internal identity |
+| Preflight, idempotency, bundle-body construction, and report rendering all live in `scripts/*.mjs`, not prose (A9) | JSON parsing + `masterLabel` matching + `hasAccess` reads + verdict emission are deterministic; the ~70KB Agent Script and free-text apostrophes cannot be safely interpolated into a shell string — `JSON.stringify` in the helper escapes them |
+| Three-call sequence: `createBundleWithVersion` → `publish` → `activate`, in that order, on the SAME captured `bundleVersionId` (response `id`, not `bundleId`) | Platform enforces DRAFT → published → active; response-body / empty-body / `--json` / `agentType` / HTML-decode gotchas live in `references/error-taxonomy.md` |
+| Enumerate `BotDefinition` **with the `BotVersions` subquery**; skip create when Active; offer Phase-2b reactivation when Inactive — never silent skip, never duplicate create | Subquery is what distinguishes Active/Inactive; the server rejects a duplicate `DeveloperName` at publish (unique-constraint → bundle cleanup), so this read is what turns a repeat into a graceful skip instead of that hard error |
+| **REQUIRED confirm-to-write checkpoint** before create sequence or reactivation call | Both change live org state — explicit user approval required |
+| On `hasAccess=false` / `403 FUNCTIONALITY_NOT_ENABLED`, offer the readiness hand-off — never enable features here; never call legacy `/connect/service-itsm/createAgent` | Enablement is a Setup-UI/admin action; `createAgent` produces a Setup-page bot with an external-link icon (wrong kind of agent for this skill) |
+| Report exact CLI response text on any error | Enables support to diagnose failures |
+
+---
+
+## Verification Checklist
+
+- [ ] Preflight classified by `classify-preflight.mjs` (PASS or documented CANNOT-CONFIRM); hand-off offered on FAIL; raw error surfaced on ERROR.
+- [ ] Idempotency keyed on the template's `botDefinitionId` (Phase-1 row) with the collected developerName as fallback; `BotDefinition WHERE Id='<botDefinitionId>' OR DeveloperName='<developerName>'` (the `OR` covers both a null and a dangling `botDefinitionId`) + latest `BotVersion.Status` (subquery present) read + classified before any write.
+- [ ] If `needsActivation:true`, Phase-2b reactivation offer presented — no silent skip, no duplicate create.
+- [ ] Explicit user confirmation at Phase 3 (create) or Phase 2b (reactivation) before any write.
+- [ ] Bundle body built by `build-create-body.mjs`, POSTed via `--body @<file>` with the collected `developerName`/`label`; or write correctly skipped.
+- [ ] Same `bundleVersionId` (response `id`) used for publish + activate; reactivation used `POST /connect/bot-versions/<id>/activation`; legacy `createAgent` never called.
+- [ ] Phase-7 verify confirmed `BotDefinition` present + latest version Active.
+- [ ] Access token never extracted; final verdict + `BotDefinition`/bundle Id reported.
+
+---
+
+## Output Format
+
+The report layout is generated deterministically by `scripts/render-report.mjs` — the single source of report text for both the chat turn and the harness's `${outputDir}/report.md`. Never hand-compose the layout in prose (A9); always shell out to the helper. Full rendered shape, report-state JSON schema, and checkpoint-write rules live in `references/report-format.md`.
+
+Terminal verdicts: `CREATED | ALREADY-CREATED | ACTIVATED | PENDING CONFIRMATION | DECLINED | FAILED`. When `${outputDir}` is set, write at Phase 3, Phase 6 (or Phase 2b), and Phase 8 — each write overwrites the same file. Skip these writes in interactive/chat surfaces.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|--------------|
+| `references/workflow-detail.md` | Full per-phase verdict-branch narrative that the SKILL body summarizes (Phase-1 ERROR/NOT-READY/CANNOT-CONFIRM, Phase-2 classifier output, Phase-4 create response, error branches) |
+| `references/report-format.md` | Every `render-report.mjs` call — the rendered shape and the three-checkpoint write policy for `${outputDir}/report.md` |
+| `references/cli-invocation.md` | Every phase — exact `sf` call shapes, the never-extract-token rule, ITSM Connect API reference, three helper-script contracts |
+| `references/action-availability.md` | Phase 2c (action-availability preflight, create path) + Phase 2b/6 (activate-result classifier) — silent-failure body catches, permset hand-off wording |
+| `references/reactivation.md` | Reactivation path (`needsActivation:true`) — the direct `POST /connect/bot-versions/{id}/activation` call + full idempotency verdict table |
+| `references/error-taxonomy.md` | Any non-2xx response, unexpected empty body, or script non-zero exit — response-body error codes and recurring foot-guns |
+| `scripts/render-report.mjs` | Every checkpoint that writes `${outputDir}/report.md` (Phase-3 gate, Phase-6 create-succeeded, Phase-8 final) — deterministic renderer from a phase-state JSON |