@nextcommerce/campaigns-os 1.54.0 → 1.55.0

package/skills.json

@@ -1,7 +1,7 @@
 {
   "name": "campaigns-os-skills",
   "description": "Skills bundled with Campaigns OS. `skills.sh` installs these into the shared agent skill directories (~/.claude/skills, ~/.codex/skills), so each one is a versioned package: bump the version whenever a package changes. `bundle_revision` identifies the bundle as a whole — `<package version>+skills.<n>`, where the prefix is this package's version and `<n>` counts the skill-text revisions published against it. It advances whenever ANY bundled skill changes, every SKILL.md states it on its first body line, and `campaigns-os tooling status --skills-revision <value>` compares the value an agent read from a skill against the bundle on disk. See docs/skills-revision.md.",
-  "bundle_revision": "1.54.0+skills.1",
+  "bundle_revision": "1.55.0+skills.1",
   "homepage": "https://github.com/NextCommerceCo/campaigns-os",
   "retired_skills": [
     {
@@ -16,7 +16,7 @@
     {
       "id": "next-campaigns-os",
       "name": "Campaigns OS Lifecycle",
-      "version": "1.0.50",
+      "version": "1.0.52",
       "path": "skills/next-campaigns-os/SKILL.md",
       "domain": "campaigns",
       "description": "Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth."
@@ -24,7 +24,7 @@
     {
       "id": "next-campaigns-os-setup",
       "name": "Campaigns OS Setup",
-      "version": "2.0.33",
+      "version": "2.0.35",
       "path": "skills/next-campaigns-os-setup/SKILL.md",
       "domain": "campaigns",
       "description": "Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet before full build wiring. Formerly next-campaigns-setup; renamed to release that name to the published NextCommerceCo/skills scaffolder."
@@ -32,7 +32,7 @@
     {
       "id": "next-campaigns-build",
       "name": "Campaign Build",
-      "version": "1.0.35",
+      "version": "1.0.37",
       "path": "skills/next-campaigns-build/SKILL.md",
       "domain": "campaigns",
       "description": "Assemble a NEXT campaign from a doctor-cleared Build Packet, CampaignSpec/API values, prepared HTML/assets, page-kit, and starter-template contracts."
@@ -40,7 +40,7 @@
     {
       "id": "next-campaigns-polish",
       "name": "Campaign Polish",
-      "version": "1.1.34",
+      "version": "1.1.36",
       "path": "skills/next-campaigns-polish/SKILL.md",
       "domain": "campaigns",
       "description": "Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign."
@@ -48,7 +48,7 @@
     {
       "id": "next-campaigns-qa",
       "name": "Campaign QA",
-      "version": "1.3.34",
+      "version": "1.3.36",
       "path": "skills/next-campaigns-qa/SKILL.md",
       "domain": "campaigns",
       "description": "Run spec-aware QA from a saved Map or local-spec Build Packet and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof."
@@ -56,7 +56,7 @@
     {
       "id": "campaign-lifecycle-orientation",
       "name": "Campaign Lifecycle Orientation",
-      "version": "1.0.30",
+      "version": "1.0.32",
       "path": "skills/campaign-lifecycle-orientation/SKILL.md",
       "domain": "campaigns",
       "description": "Orient a reader to the Campaigns OS lifecycle artifacts a run has already emitted, without advancing their state: the shared vocabulary, doctor as a gate, the stage record, and the store-theme/Page Kit two-worlds trap."
@@ -64,7 +64,7 @@
     {
       "id": "campaign-run-evidence",
       "name": "Campaign Run Evidence",
-      "version": "1.0.30",
+      "version": "1.0.32",
       "path": "skills/campaign-run-evidence/SKILL.md",
       "domain": "campaigns",
       "description": "Interpret existing doctor, QA verdict and proof-depth evidence without claiming more proof than the artifacts contain, and keep funnel proof apart from merchant launch readiness."
@@ -72,7 +72,7 @@
     {
       "id": "campaign-readback-classification",
       "name": "Campaign Readback Classification",
-      "version": "1.0.30",
+      "version": "1.0.32",
       "path": "skills/campaign-readback-classification/SKILL.md",
       "domain": "campaigns",
       "description": "Classify a selected campaign from the campaigns-os-readback/v2 fields (artifacts, staleness.stale_keys, clean, doctor, divergences, skip_cascades) and write a read-only handoff without turning diagnosis into permission."
@@ -80,7 +80,7 @@
     {
       "id": "contribution-intake",
       "name": "Contribution Intake",
-      "version": "1.0.30",
+      "version": "1.0.32",
       "path": "skills/contribution-intake/SKILL.md",
       "domain": "campaigns",
       "description": "Turn a suggestion about the agent surface into a classified, evidence-checked and redacted proposal, filed on this repository tracker only with attended approval."

package/src/adapter-decision-contract.mjs

@@ -66,6 +66,20 @@ const SCRIPT_STYLE_REFERENCE_POLICIES = new Set(["frontmatter_or_campaign_asset"
 const CTA_REWRITE_POLICIES = ROUTE_REWRITE_POLICIES;
 const LAYOUT_CHOICES = new Set(["campaign_layout", "page_layout", "raw_passthrough", "not_applicable", "unknown"]);
 
+// The scalar choices record build can set; the object-valued template slice
+// stays with its existing proof fields and doctor checks.
+export const ADAPTER_DECISION_SCALAR_VALUES = Object.freeze(Object.assign(Object.create(null), {
+  raw_html_conversion_status: [...RAW_HTML_CONVERSION_STATUSES],
+  source_asset_strategy: [...SOURCE_ASSET_STRATEGIES],
+  commerce_shell_adoption: [...COMMERCE_SHELL_ADOPTIONS],
+  route_rewrite_policy: [...ROUTE_REWRITE_POLICIES],
+  config_script_strategy: [...CONFIG_SCRIPT_STRATEGIES],
+  frontmatter_policy: [...FRONTMATTER_POLICIES],
+  script_style_reference_policy: [...SCRIPT_STYLE_REFERENCE_POLICIES],
+  cta_rewrite_policy: [...CTA_REWRITE_POLICIES],
+  layout_choice: [...LAYOUT_CHOICES],
+}));
+
 /**
  * Seeds the adapter decision record written onto a new Build Packet.
  *
@@ -170,7 +184,7 @@ export function validateAdapterSourceFiles({ decisions, sourceRoot, pages = [],
   addIssue(
     warnings,
     "source_html.raw_html_wrappers",
-    `source_html.adapter_contract.raw_html_conversion_status is "${status}", but mapped source HTML still contains document wrapper tags: ${sample}${more}. Strip <!doctype>, <html>, <head>, and <body> before treating the page as page-kit-ready source.`
+    `Effective raw_html_conversion_status is "${status}", but mapped source HTML still contains document wrapper tags: ${sample}${more}. Strip <!doctype>, <html>, <head>, and <body> before treating the page as page-kit-ready source.`
   );
 }
 
@@ -184,32 +198,32 @@ export function validateAdapterDecisionGates({ decisions, location, specPages =
       addIssue(
         warnings,
         "adapter.raw_html_conversion_status",
-        `Assembly is recorded complete, but ${location}.raw_html_conversion_status is "${decisions.raw_html_conversion_status}". Record completed/not_required after wrapper stripping, frontmatter, asset moves, script/style refs, CTA rewrites, route policy, and layout choice are settled.`
+        `Assembly is recorded complete, but ${location}.raw_html_conversion_status is "${decisions.raw_html_conversion_status}". Use record build --adapter-decision raw_html_conversion_status=<value> to record completed/not_required after wrapper stripping, frontmatter, asset moves, script/style refs, CTA rewrites, route policy, and layout choice are settled.`
       );
     }
     if (["raw_passthrough", "unknown"].includes(decisions.source_asset_strategy)) {
-      addIssue(warnings, "adapter.source_asset_strategy", `Assembly is recorded complete with ${location}.source_asset_strategy="${decisions.source_asset_strategy}". Page-kit builds should normally use pagekit_campaign_asset_root so src/<slug>/assets/* publishes at /<slug>/*.`);
+      addIssue(warnings, "adapter.source_asset_strategy", `Assembly is recorded complete with ${location}.source_asset_strategy="${decisions.source_asset_strategy}". Use record build --adapter-decision source_asset_strategy=<value> to record pagekit_campaign_asset_root when src/<slug>/assets/* publishes at /<slug>/*.`);
     }
     if (["raw_passthrough", "unknown"].includes(decisions.route_rewrite_policy)) {
-      addIssue(warnings, "adapter.route_rewrite_policy", `Assembly is recorded complete with ${location}.route_rewrite_policy="${decisions.route_rewrite_policy}". Record how CampaignSpec routes and CTA destinations were rewritten before QA.`);
+      addIssue(warnings, "adapter.route_rewrite_policy", `Assembly is recorded complete with ${location}.route_rewrite_policy="${decisions.route_rewrite_policy}". Use record build --adapter-decision route_rewrite_policy=<value> to record how CampaignSpec routes and CTA destinations were rewritten before QA.`);
     }
     if (decisions.config_script_strategy === "unknown") {
-      addIssue(warnings, "adapter.config_script_strategy", `Assembly is recorded complete but ${location}.config_script_strategy is unknown. Record whether config scripts load via campaign assets, frontmatter scripts, inline config, or not_required.`);
+      addIssue(warnings, "adapter.config_script_strategy", `Assembly is recorded complete but ${location}.config_script_strategy is unknown. Use record build --adapter-decision config_script_strategy=<value> to record whether config scripts load via campaign assets, frontmatter scripts, inline config, or not_required.`);
     }
     if (["preserve_document_wrappers", "unknown"].includes(decisions.wrapper_policy)) {
-      addIssue(warnings, "adapter.wrapper_policy", `Assembly is recorded complete with ${location}.wrapper_policy="${decisions.wrapper_policy}". Page-kit source should normally strip document wrappers unless preserving them is explicitly not_required.`);
+      addIssue(warnings, "adapter.wrapper_policy", `Assembly is recorded complete with ${location}.wrapper_policy="${decisions.wrapper_policy}". Select wrapper_policy at intake with prepare-build --wrapper-policy or the source-html manifest's wrapper_policy option; page-kit source should normally strip document wrappers unless preserving them is explicitly not_required.`);
     }
     if (["raw_passthrough", "unknown"].includes(decisions.frontmatter_policy)) {
-      addIssue(warnings, "adapter.frontmatter_policy", `Assembly is recorded complete with ${location}.frontmatter_policy="${decisions.frontmatter_policy}". Record how Page Kit YAML frontmatter was created or why it is not_required.`);
+      addIssue(warnings, "adapter.frontmatter_policy", `Assembly is recorded complete with ${location}.frontmatter_policy="${decisions.frontmatter_policy}". Use record build --adapter-decision frontmatter_policy=<value> to record how Page Kit YAML frontmatter was created or why it is not_required.`);
     }
     if (["raw_passthrough", "unknown"].includes(decisions.script_style_reference_policy)) {
-      addIssue(warnings, "adapter.script_style_reference_policy", `Assembly is recorded complete with ${location}.script_style_reference_policy="${decisions.script_style_reference_policy}". Record how scripts/styles load via frontmatter, campaign assets, inline blocks, or not_required.`);
+      addIssue(warnings, "adapter.script_style_reference_policy", `Assembly is recorded complete with ${location}.script_style_reference_policy="${decisions.script_style_reference_policy}". Use record build --adapter-decision script_style_reference_policy=<value> to record how scripts/styles load via frontmatter, campaign assets, inline blocks, or not_required.`);
     }
     if (["raw_passthrough", "unknown"].includes(decisions.cta_rewrite_policy)) {
-      addIssue(warnings, "adapter.cta_rewrite_policy", `Assembly is recorded complete with ${location}.cta_rewrite_policy="${decisions.cta_rewrite_policy}". Record how CTA destinations were rewritten from CampaignSpec routes before QA.`);
+      addIssue(warnings, "adapter.cta_rewrite_policy", `Assembly is recorded complete with ${location}.cta_rewrite_policy="${decisions.cta_rewrite_policy}". Use record build --adapter-decision cta_rewrite_policy=<value> to record how CTA destinations were rewritten from CampaignSpec routes before QA.`);
     }
     if (["raw_passthrough", "unknown"].includes(decisions.layout_choice)) {
-      addIssue(warnings, "adapter.layout_choice", `Assembly is recorded complete with ${location}.layout_choice="${decisions.layout_choice}". Record the Page Kit layout strategy before handoff.`);
+      addIssue(warnings, "adapter.layout_choice", `Assembly is recorded complete with ${location}.layout_choice="${decisions.layout_choice}". Use record build --adapter-decision layout_choice=<value> to record the Page Kit layout strategy before handoff.`);
     }
   }
 
@@ -219,13 +233,13 @@ export function validateAdapterDecisionGates({ decisions, location, specPages =
       addIssue(
         errors,
         "adapter.commerce_shell_adoption",
-        `Runtime commerce pages (${runtimePages.map((page) => page.id).join(", ")}) are marked custom_html_experimental for template family "${family}". Use template_clone_first_verified or sdk_surfaces_preserved before treating checkout/upsell/downsell/receipt as build-ready.`
+        `Runtime commerce pages (${runtimePages.map((page) => page.id).join(", ")}) are marked custom_html_experimental for template family "${family}". Use record build --adapter-decision commerce_shell_adoption=<value> to record template_clone_first_verified or sdk_surfaces_preserved before treating checkout/upsell/downsell/receipt as build-ready.`
       );
     } else if (assemblyComplete && !["template_clone_first_verified", "sdk_surfaces_preserved"].includes(adoption)) {
       addIssue(
         warnings,
         "adapter.commerce_shell_adoption",
-        `Assembly is recorded complete, but ${location}.commerce_shell_adoption is "${adoption || "missing"}" for runtime commerce pages (${runtimePages.map((page) => page.id).join(", ")}). Commerce pages should be template-clone-first, then styled, with SDK-owned surfaces preserved.`
+        `Assembly is recorded complete, but ${location}.commerce_shell_adoption is "${adoption || "missing"}" for runtime commerce pages (${runtimePages.map((page) => page.id).join(", ")}). Use record build --adapter-decision commerce_shell_adoption=<value> after commerce pages are template-clone-first, then styled, with SDK-owned surfaces preserved.`
       );
     }
   }

package/src/brand-theme.mjs

@@ -256,8 +256,11 @@ function inferDesignIntentTokens(content, rootTokens = {}) {
     const lower = name.toLowerCase();
     if (isTargetContractToken(lower)) continue;
     const parts = tokenNameParts(lower);
+    const decorativeName = hasTokenPart(parts, DECORATIVE_NAME_PARTS);
+    const namedRole = hasTokenPart(parts, EXPLICIT_BRAND_PARTS);
     const ctaName = hasTokenPart(parts, ["cta", "button", "btn"]);
-    if (!ctaName && (hasTokenSequence(parts, ["brand"], ["primary", "main"]) || (hasTokenPart(parts, ["primary"]) && !hasTokenPart(parts, ["text", "foreground", "surface", "background", "bg", "border", "outline"])))) {
+    if (!ctaName && (!decorativeName || namedRole)
+      && (hasTokenSequence(parts, ["brand"], ["primary", "main"]) || (hasTokenPart(parts, ["primary"]) && !hasTokenPart(parts, ["text", "foreground", "surface", "background", "bg", "border", "outline"])))) {
       addToken("--brand-primary", color);
     }
     if (ctaName) {
@@ -281,7 +284,7 @@ function inferDesignIntentTokens(content, rootTokens = {}) {
     if (hasTokenPart(parts, ["rating", "star", "review"])) addToken("--rating-star", color);
   }
 
-  const rulePattern = /([^{}]+)\{([^{}]+)\}/g;
+  const rulePattern = /([^{};]+)\{([^{}]+)\}/g;
   for (const match of stripCssComments(content).matchAll(rulePattern)) {
     const selector = match[1] || "";
     for (const declaration of match[2].split(";")) {
@@ -291,9 +294,11 @@ function inferDesignIntentTokens(content, rootTokens = {}) {
       const color = resolveDeclarationColor(rawValue, rootTokens);
       if (!color) continue;
       if (["background", "background-color"].includes(name)) {
-        if (/(header|nav|announcement|brand|hero)/i.test(selector) && isStrongBrandColor(color)) {
+        if (hasPrimarySelectorRole(selector)
+          && isStrongBrandColor(color)) {
           addToken("--brand-primary", color);
-        } else if (isCtaLikeSelector(selector) && isStrongBrandColor(color)) {
+        }
+        if (isCtaLikeSelector(eligibleSelectorText(selector)) && isStrongBrandColor(color)) {
           addToken("--button-primary-bg", color);
           addToken("--brand-cta", color);
           addToken("--brand-accent", color);
@@ -319,6 +324,32 @@ function inferDesignIntentTokens(content, rootTokens = {}) {
   return tokens;
 }
 
+const DECORATIVE_NAME_PARTS = ["sale", "discount", "badge", "rating", "star", "strike", "border", "announcement"];
+const EXPLICIT_BRAND_PARTS = ["brand", "primary", "cta", "button", "btn"];
+
+function selectorSubjectParts(compound) {
+  return [...compound.classes, ...compound.ids].flatMap(tokenNameParts);
+}
+
+function subjectHasDecorativeRole(compound) {
+  // A button or submit input is a control whatever its classes say.
+  if (compound.type === "button") return false;
+  if (compound.type === "input" && compound.attributes.some((attribute) => /^\s*type\s*=\s*(["']?)submit\1\s*(?:i\s*)?$/i.test(attribute))) return false;
+  const parts = selectorSubjectParts(compound);
+  return hasTokenPart(parts, DECORATIVE_NAME_PARTS) && !hasTokenPart(parts, EXPLICIT_BRAND_PARTS);
+}
+
+function eligibleSelectorText(selector) {
+  const compounds = rightmostCompounds(selector);
+  if (!compounds) return selector;
+  return compounds.filter((compound) => !subjectHasDecorativeRole(compound))
+    .map((compound) => compound.selectorText).join(", ");
+}
+
+function hasPrimarySelectorRole(selector) {
+  return /(header|nav|announcement|brand|hero)/i.test(eligibleSelectorText(selector));
+}
+
 function isCtaLikeSelector(selector) {
   return /(?:^|[.#\s:_-])(?:cta|button|btn|submit|cart|buy|order)(?:$|[.#\s:_-])/i.test(String(selector || ""));
 }
@@ -337,11 +368,12 @@ const SELECTOR_ARGUMENT_PSEUDOS = new Set(["not", "is", "where", "has"]);
 function rightmostCompounds(selectorList) {
   const text = String(selectorList || "");
   const compounds = [];
-  const fresh = () => ({ type: null, classes: [], attributes: [], pseudos: [] });
-  const isEmpty = (compound) => !compound.type && !compound.classes.length && !compound.attributes.length && !compound.pseudos.length;
+  const fresh = () => ({ type: null, classes: [], ids: [], attributes: [], pseudos: [] });
+  const isEmpty = (compound) => !compound.type && !compound.classes.length && !compound.ids.length && !compound.attributes.length && !compound.pseudos.length;
   let current = fresh();
   let afterCombinator = false;
   let i = 0;
+  let selectorStart = 0;
   const readName = () => {
     const start = i;
     while (i < text.length && (/[A-Za-z0-9_\- -￿]/.test(text[i]) || text[i] === "\\")) i += text[i] === "\\" ? 2 : 1;
@@ -371,10 +403,12 @@ function rightmostCompounds(selectorList) {
     if (/[\s>+~]/.test(ch)) { afterCombinator = true; i += 1; continue; }
     if (ch === ",") {
       if (isEmpty(current)) return null;
+      current.selectorText = text.slice(selectorStart, i);
       compounds.push(current);
       current = fresh();
       afterCombinator = false;
       i += 1;
+      selectorStart = i;
       continue;
     }
     if (afterCombinator) { current = fresh(); afterCombinator = false; }
@@ -383,6 +417,7 @@ function rightmostCompounds(selectorList) {
       const name = readName();
       if (!name) return null;
       if (ch === ".") current.classes.push(name);
+      else current.ids.push(name);
     } else if (ch === "[") {
       const attribute = readGroup("[", "]");
       if (attribute === null) return null;
@@ -404,6 +439,7 @@ function rightmostCompounds(selectorList) {
     }
   }
   if (isEmpty(current)) return null;
+  current.selectorText = text.slice(selectorStart);
   compounds.push(current);
   return compounds;
 }
@@ -469,7 +505,7 @@ function splitDeclarations(body) {
 // declaredCtaForegroundValue.
 function collectCtaLabelRules(content, rootTokens = {}) {
   const rules = [];
-  for (const match of stripCssComments(content).matchAll(/([^{}]+)\{([^{}]+)\}/g)) {
+  for (const match of stripCssComments(content).matchAll(/([^{};]+)\{([^{}]+)\}/g)) {
     if (!isButtonSelector(match[1])) continue;
     let color = null;
     let background = null;
@@ -975,7 +1011,7 @@ function mapTokens(tokens, targetTokens, { rootTokens = {}, ctaLabelRules = [] }
   const hasCta = mappings.some((mapping) => mapping.target === "--brand--color--cta-primary");
   if (!hasCta && isNonEmptyString(tokens["--brand-accent"])) {
     addMapping("--brand-accent", "--brand--color--cta-primary", tokens["--brand-accent"].trim(), "medium", { method: "cta-fallback-from-brand-accent" });
-    warnings.push(issue("theme.cta.fallback", "No explicit CTA token was found; using --brand-accent as --brand--color--cta-primary."));
+    warnings.push(issue("theme.cta.fallback", "No explicit CTA token or button background was found; using --brand-accent as --brand--color--cta-primary. This may be a rating or decorative accent; confirm the CTA colour against the design."));
   } else if (!hasCta && isNonEmptyString(tokens["--brand-primary"])) {
     addMapping("--brand-primary", "--brand--color--cta-primary", tokens["--brand-primary"].trim(), "medium", { method: "cta-fallback-from-brand-primary" });
     warnings.push(issue("theme.cta.fallback", "No explicit CTA token was found; using --brand-primary as --brand--color--cta-primary."));

package/src/campaign-identity.mjs

@@ -45,6 +45,7 @@ export const CAMPAIGN_IDENTITY = "built_output.campaign_identity";
 // Finding kinds, each with its own issue code under the gate id.
 export const CAMPAIGN_IDENTITY_KINDS = Object.freeze({
   api_key_drift: `${CAMPAIGN_IDENTITY}.api_key_drift`,
+  api_key_mismatch: `${CAMPAIGN_IDENTITY}.api_key_mismatch`,
   funnel_drift: `${CAMPAIGN_IDENTITY}.funnel_drift`,
   funnel_missing: `${CAMPAIGN_IDENTITY}.funnel_missing`,
   attribution_drift: `${CAMPAIGN_IDENTITY}.attribution_drift`,
@@ -270,7 +271,7 @@ function gateBase(subject) {
  *   file?: string|null, content: string, spec_page?: boolean,
  *   scripts?: Array<{ src: string, file?: string|null, content: string }> }> }} input
  */
-export function evaluateCampaignIdentity({ subject, pages = [] } = {}) {
+export function evaluateCampaignIdentity({ subject, pages = [], expectedApiKey = null } = {}) {
   const all = Array.isArray(pages) ? pages : [];
   const skipped = all
     .filter((page) => isParkedPage(page.route ?? page.file ?? page.page_id))
@@ -298,7 +299,7 @@ export function evaluateCampaignIdentity({ subject, pages = [] } = {}) {
   //    value. Meta and config are compared together on purpose: a page whose
   //    meta names one campaign while its config.js names another is drift
   //    inside a single page, and the SDK's precedence rule only hides it.
-  const keyObservations = identities.flatMap((identity) => identity.api_keys.map((key) => ({ page_id: identity.page_id, ...key })));
+  const keyObservations = identities.flatMap((identity) => identity.api_keys.map((key) => ({ page_id: identity.page_id, page_file: identity.file || identity.page_id, ...key })));
   const firstKey = keyObservations[0] || null;
   for (const observation of keyObservations.slice(1)) {
     if (observation.value === firstKey.value) continue;
@@ -312,6 +313,32 @@ export function evaluateCampaignIdentity({ subject, pages = [] } = {}) {
     });
     break; // one finding per kind names the first pair; the rest follow from the same edit
   }
+  const wrongKeys = new Map();
+  if (expectedApiKey?.key) {
+    for (const observation of keyObservations) {
+      if (observation.value === expectedApiKey.key) continue;
+      if (!wrongKeys.has(observation.value)) wrongKeys.set(observation.value, new Map());
+      const sources = wrongKeys.get(observation.value);
+      const sourceId = `${observation.where}\u0000${observation.source}`;
+      if (!sources.has(sourceId)) sources.set(sourceId, { file: observation.where, source: observation.source, pages: new Set() });
+      sources.get(sourceId).pages.add(observation.page_file);
+    }
+  }
+  const wrongSourceFiles = [...new Set([...wrongKeys.values()].flatMap((sources) => [...sources.values()].map((source) => source.file)))];
+  if (wrongKeys.size) {
+    const firstWrong = keyObservations.find((observation) => observation.value !== expectedApiKey.key);
+    const wrongDetails = [...wrongKeys].map(([value, sources]) =>
+      `${[...sources.values()].map(({ file, source, pages }) => `${file} (${source}; used by ${[...pages].join(", ")})`).join(" and ")} has ${quote(value)}`,
+    ).join("; ");
+    findings.push({
+      kind: "api_key_mismatch",
+      code: CAMPAIGN_IDENTITY_KINDS.api_key_mismatch,
+      a: { page_id: null, file: expectedApiKey.source, value: expectedApiKey.key },
+      b: { page_id: firstWrong.page_id, file: firstWrong.where, source: firstWrong.source, value: firstWrong.value },
+      evidence: `Built API key in ${wrongDetails} differs from the Campaigns API key in ${expectedApiKey.source}.`,
+      message: `Built API key in ${wrongDetails} differs from the Campaigns API key ${quote(expectedApiKey.key)} in ${expectedApiKey.source}. Replace the built key in the named source with the campaign's own key, then rebuild.`,
+    });
+  }
 
   // 2. next-funnel: one value across pages, and present wherever the SDK is
   //    bootstrapped (a page that declares next-page-type is SDK-bound).
@@ -422,7 +449,7 @@ export function evaluateCampaignIdentity({ subject, pages = [] } = {}) {
     // Short on purpose; the per-edit prose is findings[].message, which is
     // what each doctor error carries. A reason that concatenates them is
     // truncated by every single-line renderer.
-    reason: `${findings.length} campaign identity drift finding(s) across ${scanned.length} built page(s) (${[...new Set(findings.map((finding) => finding.kind))].join(", ")}); see findings[] for the two files and two values of each.`,
+    reason: `${findings.length} campaign identity ${findings.every((finding) => finding.kind === "api_key_mismatch") ? "API key mismatch" : "drift"} finding(s) across ${scanned.length} built page(s) (${[...new Set(findings.map((finding) => finding.kind))].join(", ")}); see findings[] for the sources and values to repair.`,
     findings,
     pages_scanned: scanned.length,
     pages_skipped: skipped,
@@ -432,7 +459,9 @@ export function evaluateCampaignIdentity({ subject, pages = [] } = {}) {
         id: "repair_identity",
         kind: "edit",
         command: null,
-        description: `Make every page name the same campaign: ${findings.map((finding) => `${finding.b?.file || finding.a.file} (${finding.kind.replace(/_/g, " ")})`).join("; ")}. Not waivable: two campaign identities on one funnel cannot both be intended.`,
+        description: findings.map((finding) => finding.kind === "api_key_mismatch"
+          ? `Replace the built key in ${wrongSourceFiles.join(", ")} with the campaign's key, then rebuild.`
+          : `Make every page name the same campaign: ${finding.b?.file || finding.a.file} (${finding.kind.replace(/_/g, " ")}).`).join(" "),
       },
     ],
   };