@canonry/canonry 4.118.0 → 4.124.0

package/dist/cli.js

@@ -29,7 +29,7 @@ import {
   setTelemetrySource,
   showFirstRunNotice,
   trackEvent
-} from "./chunk-HGNY5GL4.js";
+} from "./chunk-4D2XUMMV.js";
 import {
   CliError,
   EXIT_SYSTEM_ERROR,
@@ -46,7 +46,7 @@ import {
   saveConfig,
   saveConfigPatch,
   usageError
-} from "./chunk-75UBTCKS.js";
+} from "./chunk-WGGB7QBD.js";
 import {
   apiKeys,
   createClient,
@@ -54,8 +54,11 @@ import {
   projects,
   queries,
   renderReportHtml
-} from "./chunk-CMZIPFNQ.js";
+} from "./chunk-BGLBWFMV.js";
 import {
+  AdsOperationKinds,
+  AdsOperationStates,
+  AdsOperationStepStates,
   BacklinkSources,
   CcReleaseSyncStatuses,
   CheckScopes,
@@ -65,15 +68,19 @@ import {
   REPORT_PERIOD_OPTIONS,
   RunStatuses,
   TrafficEventKinds,
+  adsActivateTreeRequestSchema,
+  adsActivationGrantCreateRequestSchema,
   adsAdCreateRequestSchema,
   adsAdGroupCreateRequestSchema,
   adsAdGroupUpdateRequestSchema,
   adsAdUpdateRequestSchema,
   adsCampaignCreateRequestSchema,
   adsCampaignUpdateRequestSchema,
+  adsGeoSearchQuerySchema,
   adsImageUploadRequestSchema,
   adsPauseRequestSchema,
   backlinkSourceSchema,
+  buildModelChangeNotice,
   discoveryBucketSchema,
   discoveryCompetitorTypeSchema,
   effectiveDomains,
@@ -88,7 +95,7 @@ import {
   providerQuotaPolicySchema,
   resolveProviderInput,
   winnabilityClassSchema
-} from "./chunk-KEZWLP4O.js";
+} from "./chunk-SLCGTOKT.js";
 
 // src/cli.ts
 import { pathToFileURL } from "url";
@@ -2746,20 +2753,54 @@ function readRequest(inputPath, schema) {
     });
   }
 }
+function printOperationDetails(operation) {
+  console.log(`Operation: ${operation.operationKey}`);
+  if (operation.entityId) console.log(`Entity:    ${operation.entityType ?? "unknown"} ${operation.entityId}`);
+  if (operation.upstreamUpdatedAt != null) console.log(`Updated:   ${operation.upstreamUpdatedAt}`);
+  if (operation.errorCode) console.log(`Error:     ${operation.errorCode}: ${operation.errorMessage ?? ""}`);
+  if (operation.state === AdsOperationStates.pending || operation.state === AdsOperationStates.unknown || operation.state === AdsOperationStates.reconciling) {
+    if (operation.kind === AdsOperationKinds.campaign_tree_activate) {
+      console.log("Do not retry with a new operation key. Resume activation recovery for the original receipt instead.");
+    } else {
+      console.log("Do not retry with a new operation key. Reconcile the original receipt instead.");
+    }
+  }
+}
 function printOperation(result, format) {
   if (isMachineFormat(format)) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
-  const operation = result.operation;
-  console.log(`${result.replayed ? "Replayed" : "Recorded"} ${operation.kind}: ${operation.state}`);
-  console.log(`Operation: ${operation.operationKey}`);
-  if (operation.entityId) console.log(`Entity:    ${operation.entityType ?? "unknown"} ${operation.entityId}`);
-  if (operation.upstreamUpdatedAt != null) console.log(`Updated:   ${operation.upstreamUpdatedAt}`);
-  if (operation.errorCode) console.log(`Error:     ${operation.errorCode}: ${operation.errorMessage ?? ""}`);
-  if (operation.state === "unknown") {
-    console.log("Do not retry with a new operation key. Reconcile this outcome with a human first.");
+  console.log(`${result.replayed ? "Replayed" : "Recorded"} ${result.operation.kind}: ${result.operation.state}`);
+  printOperationDetails(result.operation);
+}
+function printReconciliation(result, format) {
+  if (isMachineFormat(format)) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`${result.resolved ? "Resolved" : "Still unresolved"} ${result.operation.kind}: ${result.operation.state}`);
+  printOperationDetails(result.operation);
+}
+function printActivationGrant(result, verb, format) {
+  if (isMachineFormat(format)) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
   }
+  const cancellationRequested = verb === "Revoked" && result.grant.revocationRequestedAt !== null;
+  console.log(cancellationRequested ? `Cancellation requested for activation grant ${result.grant.id}: ${result.grant.state}` : `${verb} activation grant ${result.grant.id}: ${result.grant.state}`);
+  if (cancellationRequested) console.log(`Requested: ${result.grant.revocationRequestedAt}`);
+  console.log(`Manifest: ${result.grant.manifestHash}`);
+  console.log(`Expires:  ${result.grant.expiresAt}`);
+}
+function printActivation(result, format) {
+  if (isMachineFormat(format)) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  const activeSteps = result.steps.filter((step) => step.state === AdsOperationStepStates.active).length;
+  console.log(`Activation ${result.operation.operationKey}: ${result.operation.state}`);
+  console.log(`Steps:      ${activeSteps}/${result.steps.length} active`);
 }
 function describeConnection(status) {
   const lines = [];
@@ -2813,9 +2854,155 @@ async function adsStatus(project, opts) {
     console.log("Connect with: canonry ads connect " + project + " --api-key <sdk-key>");
   }
 }
+async function adsAccount(project, opts) {
+  const result = await getClient5().getAdsAccount(project);
+  if (isMachineFormat(opts?.format)) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`Account:    ${result.name}`);
+  console.log(`ID:         ${result.id}`);
+  console.log(`Status:     ${result.status}`);
+  console.log(`Currency:   ${result.currencyCode ?? "unknown"}`);
+  console.log(`Timezone:   ${result.timezone ?? "unknown"}`);
+  console.log(`Review:     ${result.reviewStatus ?? "unknown"}`);
+  console.log(`Integrity:  ${result.integrityReviewStatus ?? "unknown"}`);
+  if (result.integrityDecision) console.log(`Decision:   ${result.integrityDecision}`);
+  if (result.url) console.log(`Ads Manager: ${result.url}`);
+}
+async function adsGeoSearch(project, opts) {
+  const parsed = adsGeoSearchQuerySchema.safeParse({ q: opts.q, limit: opts.limit });
+  if (!parsed.success) {
+    throw new CliError({
+      code: "ADS_GEO_QUERY_INVALID",
+      message: "A valid geo search query is required",
+      displayMessage: "Error: --query is required and --limit must be an integer from 1 to 100",
+      details: {
+        project,
+        issues: parsed.error.issues.map((issue) => ({ path: issue.path.join("."), message: issue.message }))
+      }
+    });
+  }
+  const query = parsed.data;
+  const result = await getClient5().searchAdsGeo(project, query);
+  if (opts.format === "jsonl") {
+    emitJsonl(result.results.map((location) => ({ project, query: result.query, ...location })));
+    return;
+  }
+  if (isMachineFormat(opts.format)) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (result.results.length === 0) {
+    console.log(`No OpenAI Ads locations matched "${result.query}".`);
+    return;
+  }
+  for (const location of result.results) {
+    const region = location.regionCode ? `, ${location.regionCode}` : "";
+    console.log(`${location.canonicalName} (${location.type}, ${location.countryCode}${region}) [${location.id}]`);
+  }
+}
+async function adsConversionPixels(project, opts) {
+  const result = await getClient5().getAdsConversionPixels(project);
+  if (opts?.format === "jsonl") {
+    emitJsonl(result.pixels.map((pixel) => ({ project, ...pixel })));
+    return;
+  }
+  if (isMachineFormat(opts?.format)) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (result.pixels.length === 0) {
+    console.log("No OpenAI Ads conversion pixels are configured.");
+    return;
+  }
+  for (const pixel of result.pixels) {
+    const name = pixel.name ?? "Unnamed conversion pixel";
+    const clientType = pixel.clientType ?? "unknown client";
+    const pixelId = pixel.pixelId ? ` pixel ${pixel.pixelId}` : "";
+    console.log(`${name} (${clientType}) [${pixel.id}]${pixelId}`);
+  }
+}
+async function adsConversionEventSettings(project, opts) {
+  const result = await getClient5().getAdsConversionEventSettings(project);
+  if (opts?.format === "jsonl") {
+    emitJsonl(result.eventSettings.map((eventSetting) => ({ project, ...eventSetting })));
+    return;
+  }
+  if (isMachineFormat(opts?.format)) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (result.eventSettings.length === 0) {
+    console.log("No OpenAI Ads conversion event settings are configured.");
+    return;
+  }
+  for (const eventSetting of result.eventSettings) {
+    const name = eventSetting.name ?? "Unnamed conversion event";
+    const eventType = eventSetting.eventType ?? "unknown event";
+    const attribution = eventSetting.attributionWindowDays === void 0 ? "unknown attribution window" : `${eventSetting.attributionWindowDays}d attribution`;
+    const sources = eventSetting.sources?.map((source) => source.name ?? source.id).join(", ") || "no source details";
+    const archived = eventSetting.archived === true ? " [archived]" : "";
+    console.log(
+      `${name}${archived}: ${eventType}, ${attribution}, ${sources} [${eventSetting.id}]`
+    );
+  }
+}
 async function adsOperationGet(project, opts) {
   printOperation(await getClient5().getAdsOperation(project, opts.operationKey), opts.format);
 }
+async function adsOperationsUnresolved(project, opts) {
+  const query = {
+    state: opts?.state,
+    limit: opts?.limit,
+    cursor: opts?.cursor
+  };
+  const client = getClient5();
+  const result = Object.values(query).some((value) => value !== void 0) ? await client.getUnresolvedAdsOperations(project, query) : await client.getUnresolvedAdsOperations(project);
+  if (opts?.format === "jsonl") {
+    emitJsonl(result.operations.map((operation) => ({ project, ...operation })));
+    return;
+  }
+  if (isMachineFormat(opts?.format)) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  if (result.operations.length === 0) {
+    console.log("No unresolved OpenAI Ads mutation receipts.");
+    return;
+  }
+  console.log("STATE         KIND                  OPERATION KEY");
+  for (const operation of result.operations) {
+    console.log(`${operation.state.padEnd(13)} ${operation.kind.padEnd(21)} ${operation.operationKey}`);
+  }
+  if (result.nextCursor) console.log(`Next cursor: ${result.nextCursor}`);
+}
+async function adsOperationReconcile(project, opts) {
+  printReconciliation(
+    await getClient5().reconcileAdsOperation(project, opts.operationKey),
+    opts.format
+  );
+}
+async function adsOperationResumeActivation(project, opts) {
+  printActivation(
+    await getClient5().resumeAdsActivation(project, opts.operationKey),
+    opts.format
+  );
+}
+async function adsActivationGrantCreate(project, opts) {
+  const request = readRequest(
+    opts.input,
+    adsActivationGrantCreateRequestSchema
+  );
+  printActivationGrant(await getClient5().createAdsActivationGrant(project, request), "Approved", opts.format);
+}
+async function adsActivationGrantRevoke(project, grantId, opts) {
+  printActivationGrant(
+    await getClient5().revokeAdsActivationGrant(project, grantId),
+    "Revoked",
+    opts?.format
+  );
+}
 async function adsImageUpload(project, opts) {
   const request = readRequest(opts.input, adsImageUploadRequestSchema);
   printOperation(await getClient5().uploadAdsImage(project, request), opts.format);
@@ -2832,6 +3019,10 @@ async function adsCampaignPause(project, campaignId, opts) {
   const request = readRequest(opts.input, adsPauseRequestSchema);
   printOperation(await getClient5().pauseAdsCampaign(project, campaignId, request), opts.format);
 }
+async function adsCampaignActivateTree(project, campaignId, opts) {
+  const request = readRequest(opts.input, adsActivateTreeRequestSchema);
+  printActivation(await getClient5().activateAdsCampaignTree(project, campaignId, request), opts.format);
+}
 async function adsAdGroupCreate(project, opts) {
   const request = readRequest(opts.input, adsAdGroupCreateRequestSchema);
   printOperation(await getClient5().createAdsAdGroup(project, request), opts.format);
@@ -2973,6 +3164,87 @@ var ADS_CLI_COMMANDS = [
       await adsStatus(project, { format: input.format });
     }
   },
+  {
+    path: ["ads", "account"],
+    usage: "canonry ads account <project> [--format json]",
+    run: async (input) => {
+      const project = requireProject(input, "ads.account", "canonry ads account <project> [--format json]");
+      await adsAccount(project, { format: input.format });
+    }
+  },
+  {
+    path: ["ads", "geo", "search"],
+    usage: "canonry ads geo search <project> --query <text> [--limit <n>] [--format json|jsonl]",
+    options: {
+      query: stringOption(),
+      limit: stringOption()
+    },
+    run: async (input) => {
+      const usage = "canonry ads geo search <project> --query <text> [--limit <n>] [--format json|jsonl]";
+      const project = requireProject(input, "ads.geo.search", usage);
+      await adsGeoSearch(project, {
+        q: getString(input.values, "query"),
+        limit: parseIntegerOption(input, "limit", {
+          command: "ads.geo.search",
+          message: "--limit must be an integer from 1 to 100",
+          usage
+        }),
+        format: input.format
+      });
+    }
+  },
+  {
+    path: ["ads", "conversions", "pixels"],
+    usage: "canonry ads conversions pixels <project> [--format json|jsonl]",
+    run: async (input) => {
+      const project = requireProject(input, "ads.conversions.pixels", "canonry ads conversions pixels <project> [--format json|jsonl]");
+      await adsConversionPixels(project, { format: input.format });
+    }
+  },
+  {
+    path: ["ads", "conversions", "event-settings"],
+    usage: "canonry ads conversions event-settings <project> [--format json|jsonl]",
+    run: async (input) => {
+      const project = requireProject(input, "ads.conversions.event-settings", "canonry ads conversions event-settings <project> [--format json|jsonl]");
+      await adsConversionEventSettings(project, { format: input.format });
+    }
+  },
+  {
+    path: ["ads", "operations", "unresolved"],
+    usage: "canonry ads operations unresolved <project> [--state <csv>] [--limit <n>] [--cursor <opaque>] [--format json|jsonl]",
+    options: {
+      state: stringOption(),
+      limit: stringOption(),
+      cursor: stringOption()
+    },
+    run: async (input) => {
+      const usage = "canonry ads operations unresolved <project> [--state <csv>] [--limit <n>] [--cursor <opaque>] [--format json|jsonl]";
+      const project = requireProject(
+        input,
+        "ads.operations.unresolved",
+        usage
+      );
+      const rawState = getString(input.values, "state");
+      const state = rawState === void 0 ? void 0 : rawState.split(",").filter((value) => value === "pending" || value === "unknown" || value === "reconciling");
+      if (rawState !== void 0 && state?.length !== rawState.split(",").length) {
+        throw usageError(`Error: --state must contain only pending, unknown, or reconciling
+Usage: ${usage}`, {
+          message: "--state must contain only pending, unknown, or reconciling",
+          details: { command: "ads.operations.unresolved", usage }
+        });
+      }
+      await adsOperationsUnresolved(project, {
+        state,
+        limit: parseIntegerOption(input, "limit", {
+          command: "ads.operations.unresolved",
+          message: "--limit must be an integer from 1 to 200",
+          usage
+        }),
+        cursor: getString(input.values, "cursor"),
+        format: input.format
+      });
+    }
+  },
   {
     path: ["ads", "operation"],
     usage: "canonry ads operation <project> <operation-key> [--format json]",
@@ -2987,6 +3259,70 @@ var ADS_CLI_COMMANDS = [
       await adsOperationGet(project, { operationKey, format: input.format });
     }
   },
+  {
+    path: ["ads", "operation", "reconcile"],
+    usage: "canonry ads operation reconcile <project> --operation-key <key> [--format json]",
+    options: {
+      "operation-key": stringOption()
+    },
+    run: async (input) => {
+      const usage = "canonry ads operation reconcile <project> --operation-key <key> [--format json]";
+      const project = requireProject(input, "ads.operation.reconcile", usage);
+      const operationKey = requireStringOption(input, "operation-key", {
+        command: "ads.operation.reconcile",
+        usage,
+        message: "--operation-key is required"
+      });
+      await adsOperationReconcile(project, {
+        operationKey,
+        format: input.format
+      });
+    }
+  },
+  {
+    path: ["ads", "operation", "resume-activation"],
+    usage: "canonry ads operation resume-activation <project> --operation-key <key> [--format json]",
+    options: { "operation-key": stringOption() },
+    run: async (input) => {
+      const usage = "canonry ads operation resume-activation <project> --operation-key <key> [--format json]";
+      const project = requireProject(input, "ads.operation.resume-activation", usage);
+      await adsOperationResumeActivation(project, {
+        operationKey: requireStringOption(input, "operation-key", {
+          command: "ads.operation.resume-activation",
+          message: "--operation-key is required",
+          usage
+        }),
+        format: input.format
+      });
+    }
+  },
+  {
+    path: ["ads", "activation-grant", "create"],
+    usage: "canonry ads activation-grant create <project> --input <json-file|-> [--format json]",
+    options: { input: stringOption() },
+    run: async (input) => {
+      const usage = "canonry ads activation-grant create <project> --input <json-file|-> [--format json]";
+      const project = requireProject(input, "ads.activation-grant.create", usage);
+      await adsActivationGrantCreate(project, {
+        input: getString(input.values, "input"),
+        format: input.format
+      });
+    }
+  },
+  {
+    path: ["ads", "activation-grant", "revoke"],
+    usage: "canonry ads activation-grant revoke <project> <grant-id> [--format json]",
+    run: async (input) => {
+      const usage = "canonry ads activation-grant revoke <project> <grant-id> [--format json]";
+      const project = requireProject(input, "ads.activation-grant.revoke", usage);
+      const grantId = requirePositional(input, 1, {
+        command: "ads.activation-grant.revoke",
+        usage,
+        message: "activation grant id is required"
+      });
+      await adsActivationGrantRevoke(project, grantId, { format: input.format });
+    }
+  },
   {
     path: ["ads", "image", "upload"],
     usage: "canonry ads image upload <project> --input <json-file|-> [--format json]",
@@ -3016,6 +3352,24 @@ var ADS_CLI_COMMANDS = [
       await adsCampaignUpdate(project, id, { input: getString(input.values, "input"), format: input.format });
     }
   },
+  {
+    path: ["ads", "campaign", "activate-tree"],
+    usage: "canonry ads campaign activate-tree <project> <campaign-id> --input <json-file|-> [--format json]",
+    options: { input: stringOption() },
+    run: async (input) => {
+      const usage = "canonry ads campaign activate-tree <project> <campaign-id> --input <json-file|-> [--format json]";
+      const project = requireProject(input, "ads.campaign.activate-tree", usage);
+      const id = requirePositional(input, 1, {
+        command: "ads.campaign.activate-tree",
+        usage,
+        message: "campaign id is required"
+      });
+      await adsCampaignActivateTree(project, id, {
+        input: getString(input.values, "input"),
+        format: input.format
+      });
+    }
+  },
   {
     path: ["ads", "campaign", "pause"],
     usage: "canonry ads campaign pause <project> <campaign-id> --input <json-file|-> [--format json]",
@@ -3409,10 +3763,16 @@ async function gaSessionHistory(project, opts) {
   console.log(`  ${"DATE".padEnd(dateWidth)}  ${"SESSIONS".padEnd(10)}${"ORGANIC".padEnd(10)}${"USERS".padEnd(8)}`);
   console.log(`  ${"\u2500".repeat(dateWidth)}  ${"\u2500".repeat(10)}${"\u2500".repeat(10)}${"\u2500".repeat(8)}`);
   for (const row of result) {
+    const users = row.usersSource === "deduplicated" ? String(row.users) : `${row.users}*`;
     console.log(
-      `  ${row.date.padEnd(dateWidth)}  ${String(row.sessions).padEnd(10)}${String(row.organicSessions).padEnd(10)}${String(row.users).padEnd(8)}`
+      `  ${row.date.padEnd(dateWidth)}  ${String(row.sessions).padEnd(10)}${String(row.organicSessions).padEnd(10)}${users.padEnd(8)}`
     );
   }
+  if (result.some((row) => row.usersSource !== "deduplicated")) {
+    console.log("\n  * Visitor count is approximate \u2014 it adds up each page a visitor landed on,");
+    console.log("    so someone who read several pages is counted more than once. Run");
+    console.log(`    "canonry ga sync ${project}" to replace these with exact counts.`);
+  }
 }
 async function gaCoverage(project, format) {
   const client = getClient6();
@@ -7634,11 +7994,29 @@ async function showAnalytics(project, options) {
     console.log(JSON.stringify(results, null, 2));
   }
 }
+var BUCKET_DATE_WIDTH = 35;
+function bucketDates(bucket) {
+  const legacyCompatible = bucket;
+  const start = legacyCompatible.dataStartDate?.slice(0, 10);
+  const end = legacyCompatible.dataEndDate?.slice(0, 10);
+  if (!start || !end) return "date unavailable";
+  const sweeps = legacyCompatible.sweepCount ?? 1;
+  const pooled = sweeps > 1 ? ` (${sweeps} sweeps)` : "";
+  if (start === end) return `${start}${pooled}`;
+  return `${start} \u2192 ${end}${pooled}`;
+}
 function printMetrics(data) {
   console.log(`
 Citation Rate Trends (${data.window})`);
   console.log("\u2500".repeat(50));
   const pct4 = (n) => `${(n * 100).toFixed(1)}%`;
+  const modelChangeNotice = buildModelChangeNotice(readModelPointerChanges(data));
+  if (modelChangeNotice?.kind === "change") {
+    console.log(`
+  Model Updates Behind These Numbers:`);
+    console.log(`    ${modelChangeNotice.text}`);
+    console.log("");
+  }
   console.log(`  Overall: ${pct4(data.overall.citationRate)} (${data.overall.cited}/${data.overall.total})`);
   console.log(`  Trend:   ${data.trend}`);
   if (Object.keys(data.byProvider).length > 0) {
@@ -7650,28 +8028,95 @@ Citation Rate Trends (${data.window})`);
   }
   if (data.buckets.length > 0) {
     console.log(`
-  Timeline:`);
+  Timeline (dates in UTC):`);
     for (const bucket of data.buckets) {
-      const start = bucket.startDate.slice(0, 10);
       const bar = bucket.total > 0 ? "\u2588".repeat(Math.round(bucket.citationRate * 20)) : "";
-      console.log(`    ${start}  ${pct4(bucket.citationRate).padStart(6)}  ${bar}`);
+      console.log(`    ${bucketDates(bucket).padEnd(BUCKET_DATE_WIDTH)}  ${pct4(bucket.citationRate).padStart(6)}  ${bar}`);
     }
   }
   const providersInBuckets = [...new Set(data.buckets.flatMap((b) => Object.keys(b.byProvider ?? {})))].sort();
   if (data.buckets.length > 0 && providersInBuckets.length > 0) {
     console.log(`
-  By Provider Timeline:`);
+  By Provider Timeline (dates in UTC):`);
     for (const provider of providersInBuckets) {
       console.log(`    ${provider}:`);
       for (const bucket of data.buckets) {
         const metric = bucket.byProvider?.[provider];
         if (!metric) continue;
-        const start = bucket.startDate.slice(0, 10);
         const bar = metric.total > 0 ? "\u2588".repeat(Math.round(metric.citationRate * 20)) : "";
-        console.log(`      ${start}  ${pct4(metric.citationRate).padStart(6)}  ${bar}`);
+        console.log(`      ${bucketDates(bucket).padEnd(BUCKET_DATE_WIDTH)}  ${pct4(metric.citationRate).padStart(6)}  ${bar}`);
+      }
+    }
+  }
+  if (modelChangeNotice?.kind === "no-known-change") {
+    console.log(`
+  Model Updates Behind These Numbers:`);
+    console.log(`    ${modelChangeNotice.text}`);
+    console.log(`    ${modelChangeNotice.detail}`);
+  }
+  const attributionEntries = Object.entries(readModelAttribution(data)).sort(([a], [b]) => a.localeCompare(b));
+  if (attributionEntries.length > 0) {
+    console.log(`
+  Model Evidence:`);
+    for (const [provider, attribution] of attributionEntries) {
+      const latest = attribution.latestObservation;
+      console.log(`    ${provider}: latest ${formatModelEvidence(latest.state)} at ${latest.observedAt}`);
+      for (const event of attribution.events) {
+        const dating = event.fromPreWindowAnchor ? " (on or before)" : "";
+        const priorSweep = event.fromPreWindowAnchor && event.anchorObservedAt ? `  [last seen ${formatModelEvidence(event.from)} on ${event.anchorObservedAt}]` : "";
+        console.log(`      ${event.observedAt}${dating}  ${formatModelEvidence(event.from)} \u2192 ${formatModelEvidence(event.to)}${priorSweep}`);
+      }
+      const eventTotal = attribution.eventTotal ?? attribution.events.length;
+      if (eventTotal > attribution.events.length) {
+        console.log(`      Showing the latest ${attribution.events.length} of ${eventTotal} model changes.`);
+      }
+      if (attribution.anchorUnavailable) {
+        console.log(`      We did not look far enough back to be sure this is every change.`);
       }
     }
   }
+  const servedEntries = Object.entries(readServedModelAttribution(data)).sort(([a], [b]) => a.localeCompare(b));
+  if (servedEntries.length > 0) {
+    const mismatch = readModelServiceMismatch(data);
+    console.log(`
+  What the Engines Answered With:`);
+    for (const [provider, served] of servedEntries) {
+      const rawIds = served.latestServedModelIds.length > 0 ? served.latestServedModelIds.join(", ") : formatModelEvidence(served.latestObservation.state);
+      const substituted = mismatch[provider];
+      const note = substituted ? ` \u2014 not the ${formatModelEvidence(substituted.configured)} you selected` : "";
+      console.log(`    ${provider}: ${rawIds} at ${served.latestObservation.observedAt}${note}`);
+      for (const event of served.events) {
+        const dating = event.fromPreWindowAnchor ? " (on or before)" : "";
+        console.log(`      ${event.observedAt}${dating}  ${formatModelEvidence(event.from)} \u2192 ${formatModelEvidence(event.to)}`);
+      }
+    }
+  }
+}
+function readServedModelAttribution(data) {
+  const legacyCompatible = data;
+  return legacyCompatible.servedModelAttribution ?? {};
+}
+function readModelServiceMismatch(data) {
+  const legacyCompatible = data;
+  return legacyCompatible.modelServiceMismatch ?? {};
+}
+function readModelPointerChanges(data) {
+  const legacyCompatible = data;
+  return legacyCompatible.modelPointerChanges ?? {};
+}
+function readModelAttribution(data) {
+  const legacyCompatible = data;
+  return legacyCompatible.modelAttribution ?? {};
+}
+function formatModelEvidence(state) {
+  switch (state.status) {
+    case "known":
+      return `known ${state.model}`;
+    case "unknown":
+      return "unknown";
+    case "mixed":
+      return `mixed ${state.models.join(", ")}${state.includesUnknown ? " + unknown" : ""}`;
+  }
 }
 function printGaps(data) {
   console.log(`
@@ -8128,7 +8573,9 @@ async function createProject(name, opts) {
     ownedDomains: opts.ownedDomains ?? [],
     aliases: normalizeProjectAliases(opts.displayName, opts.aliases ?? []),
     country: opts.country,
-    language: opts.language
+    language: opts.language,
+    providers: opts.providers ?? [],
+    providerModels: opts.providerModels ?? {}
   });
   if (isMachineFormat(opts.format)) {
     console.log(JSON.stringify(result, null, 2));
@@ -8191,6 +8638,9 @@ async function showProject(name, format) {
   console.log(`  Language:         ${project.language}`);
   console.log(`  Config source:    ${project.configSource}`);
   console.log(`  Config revision:  ${project.configRevision}`);
+  console.log(`  Providers:        ${(project.providers ?? []).length > 0 ? project.providers.join(", ") : "all configured"}`);
+  const providerModels = Object.entries(project.providerModels ?? {});
+  console.log(`  Model overrides:  ${providerModels.length > 0 ? providerModels.map(([provider, model]) => `${provider}=${model}`).join(", ") : "(none; instance settings inherited)"}`);
   console.log(`  Tags:             ${project.tags.length > 0 ? project.tags.join(", ") : "(none)"}`);
   const labelEntries = Object.entries(project.labels);
   console.log(`  Labels:           ${labelEntries.length > 0 ? labelEntries.map(([k, v]) => `${k}=${v}`).join(", ") : "(none)"}`);
@@ -8220,19 +8670,45 @@ async function updateProjectSettings(name, opts) {
     const toRemove = new Set(opts.removeAlias.map((a) => a.toLowerCase()));
     aliases = aliases.filter((a) => !toRemove.has(a.toLowerCase()));
   }
+  const providerModels = { ...project.providerModels ?? {}, ...opts.providerModels ?? {} };
+  for (const provider of opts.clearProviderModels ?? []) delete providerModels[provider];
+  const nextProviders = opts.providers ?? project.providers ?? [];
+  if (nextProviders.length > 0) {
+    const requested = Object.keys(opts.providerModels ?? {}).filter((p) => !nextProviders.includes(p));
+    if (requested.length > 0) {
+      throw usageError(
+        `Error: --provider-model set for ${requested.join(", ")}, which ${requested.length > 1 ? "are" : "is"} not a selected engine for "${name}"`,
+        {
+          message: "provider-model set for a provider the project does not run",
+          details: { command: "project.update", project: name, providers: nextProviders, unselected: requested }
+        }
+      );
+    }
+  }
   const result = await client.putProject(name, {
     displayName: nextDisplayName,
     canonicalDomain: opts.domain ?? project.canonicalDomain,
     ownedDomains,
     aliases: normalizeProjectAliases(nextDisplayName, aliases),
     country: opts.country ?? project.country,
-    language: opts.language ?? project.language
+    language: opts.language ?? project.language,
+    tags: project.tags,
+    labels: project.labels,
+    providers: opts.providers ?? project.providers,
+    providerModels,
+    locations: project.locations,
+    defaultLocation: project.defaultLocation,
+    autoExtractBacklinks: project.autoExtractBacklinks
   });
   if (isMachineFormat(opts.format)) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
   console.log(`Project updated: ${result.name}`);
+  const dropped = Object.keys(providerModels).filter((provider) => !(provider in result.providerModels));
+  if (dropped.length > 0) {
+    console.log(`  Dropped model override for deselected engine(s): ${dropped.join(", ")}`);
+  }
 }
 async function deleteProject(name, opts) {
   const client = getClient20();
@@ -8336,20 +8812,22 @@ async function setDefaultLocation(project, label, format) {
 var PROJECT_CLI_COMMANDS = [
   {
     path: ["project", "create"],
-    usage: "canonry project create <name> [--domain <domain>] [--owned-domain <domain>...] [--alias <name>...] [--country <code>] [--language <lang>] [--display-name <name>] [--format json]",
+    usage: "canonry project create <name> [--domain <domain>] [--owned-domain <domain>...] [--alias <name>...] [--country <code>] [--language <lang>] [--display-name <name>] [--provider <name>...] [--provider-model provider=model...] [--format json]",
     options: {
       domain: { type: "string", short: "d" },
       "owned-domain": multiStringOption(),
       alias: multiStringOption(),
       country: stringOption(),
       language: stringOption(),
-      "display-name": stringOption()
+      "display-name": stringOption(),
+      provider: multiStringOption(),
+      "provider-model": multiStringOption()
     },
     run: async (input) => {
       const name = requireProject(
         input,
         "project.create",
-        "canonry project create <name> [--domain <domain>] [--owned-domain <domain>...] [--alias <name>...] [--country <code>] [--language <lang>] [--display-name <name>] [--format json]"
+        "canonry project create <name> [--domain <domain>] [--owned-domain <domain>...] [--alias <name>...] [--country <code>] [--language <lang>] [--display-name <name>] [--provider <name>...] [--provider-model provider=model...] [--format json]"
       );
       await createProject(name, {
         domain: getString(input.values, "domain") ?? name,
@@ -8358,13 +8836,15 @@ var PROJECT_CLI_COMMANDS = [
         country: getString(input.values, "country") ?? "US",
         language: getString(input.values, "language") ?? "en",
         displayName: getString(input.values, "display-name") ?? name,
+        providers: getStringArray(input.values, "provider") ?? [],
+        providerModels: parseProviderModelAssignments(getStringArray(input.values, "provider-model")),
         format: input.format
       });
     }
   },
   {
     path: ["project", "update"],
-    usage: "canonry project update <name> [--domain <domain>] [--owned-domain <domain>...] [--add-domain <domain>...] [--remove-domain <domain>...] [--alias <name>...] [--add-alias <name>...] [--remove-alias <name>...] [--country <code>] [--language <lang>] [--display-name <name>] [--format json]",
+    usage: "canonry project update <name> [--domain <domain>] [--owned-domain <domain>...] [--add-domain <domain>...] [--remove-domain <domain>...] [--alias <name>...] [--add-alias <name>...] [--remove-alias <name>...] [--country <code>] [--language <lang>] [--display-name <name>] [--provider <name>...] [--all-providers] [--provider-model provider=model...] [--clear-provider-model <provider>...] [--format json]",
     options: {
       domain: { type: "string", short: "d" },
       "owned-domain": multiStringOption(),
@@ -8375,14 +8855,26 @@ var PROJECT_CLI_COMMANDS = [
       "remove-alias": multiStringOption(),
       country: stringOption(),
       language: stringOption(),
-      "display-name": stringOption()
+      "display-name": stringOption(),
+      provider: multiStringOption(),
+      "all-providers": { type: "boolean" },
+      "provider-model": multiStringOption(),
+      "clear-provider-model": multiStringOption()
     },
     run: async (input) => {
       const name = requireProject(
         input,
         "project.update",
-        "canonry project update <name> [--domain <domain>] [--owned-domain <domain>...] [--add-domain <domain>...] [--remove-domain <domain>...] [--alias <name>...] [--add-alias <name>...] [--remove-alias <name>...] [--country <code>] [--language <lang>] [--display-name <name>] [--format json]"
+        "canonry project update <name> [--domain <domain>] [--owned-domain <domain>...] [--add-domain <domain>...] [--remove-domain <domain>...] [--alias <name>...] [--add-alias <name>...] [--remove-alias <name>...] [--country <code>] [--language <lang>] [--display-name <name>] [--provider <name>...] [--all-providers] [--provider-model provider=model...] [--clear-provider-model <provider>...] [--format json]"
       );
+      const providers = getStringArray(input.values, "provider");
+      const allProviders = getBoolean(input.values, "all-providers");
+      if (allProviders && providers?.length) throw usageError("Error: --all-providers conflicts with --provider");
+      const providerModels = parseProviderModelAssignments(getStringArray(input.values, "provider-model"));
+      const clearProviderModels = getStringArray(input.values, "clear-provider-model") ?? [];
+      for (const provider of clearProviderModels) {
+        if (provider in providerModels) throw usageError(`Error: --provider-model and --clear-provider-model conflict for ${provider}`);
+      }
       await updateProjectSettings(name, {
         displayName: getString(input.values, "display-name"),
         domain: getString(input.values, "domain"),
@@ -8394,6 +8886,9 @@ var PROJECT_CLI_COMMANDS = [
         removeAlias: getStringArray(input.values, "remove-alias"),
         country: getString(input.values, "country"),
         language: getString(input.values, "language"),
+        providers: allProviders ? [] : providers,
+        providerModels,
+        clearProviderModels,
         format: input.format
       });
     }
@@ -8509,6 +9004,18 @@ var PROJECT_CLI_COMMANDS = [
     }
   }
 ];
+function parseProviderModelAssignments(assignments) {
+  const result = {};
+  for (const assignment of assignments ?? []) {
+    const separator = assignment.indexOf("=");
+    const provider = separator === -1 ? "" : assignment.slice(0, separator).trim();
+    const model = separator === -1 ? "" : assignment.slice(separator + 1).trim();
+    if (!provider || !model) throw usageError(`Error: --provider-model must use provider=model (received ${assignment})`);
+    if (provider in result) throw usageError(`Error: duplicate --provider-model assignment for ${provider}`);
+    result[provider] = model;
+  }
+  return result;
+}
 
 // src/commands/report.ts
 import fs9 from "fs";
@@ -10944,18 +11451,36 @@ async function bootstrapCommand(_opts) {
   } : existingConfig?.google;
   const keyHash = crypto.createHash("sha256").update(rawApiKey).digest("hex");
   const keyPrefix = rawApiKey.slice(0, 9);
+  const existingConfigKeyHash = existingConfig ? crypto.createHash("sha256").update(existingConfig.apiKey).digest("hex") : void 0;
   const db = createClient(databasePath);
   migrate(db);
   db.transaction((tx) => {
-    tx.delete(apiKeys).where(eq(apiKeys.name, "default")).run();
-    tx.insert(apiKeys).values({
-      id: crypto.randomUUID(),
-      name: "default",
-      keyHash,
-      keyPrefix,
-      scopes: ["*"],
-      createdAt: (/* @__PURE__ */ new Date()).toISOString()
-    }).run();
+    const rotatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const existingDefaults = tx.select({ id: apiKeys.id, keyHash: apiKeys.keyHash }).from(apiKeys).where(eq(apiKeys.name, "default")).all();
+    const existingDefault = existingDefaults.find((key) => key.keyHash === existingConfigKeyHash) ?? existingDefaults.at(0);
+    if (existingDefault) {
+      tx.update(apiKeys).set({
+        keyHash,
+        keyPrefix,
+        scopes: ["*"],
+        projectId: null,
+        lastUsedAt: null,
+        revokedAt: null
+      }).where(eq(apiKeys.id, existingDefault.id)).run();
+      for (const duplicate of existingDefaults) {
+        if (duplicate.id === existingDefault.id) continue;
+        tx.update(apiKeys).set({ revokedAt: rotatedAt }).where(eq(apiKeys.id, duplicate.id)).run();
+      }
+    } else {
+      tx.insert(apiKeys).values({
+        id: crypto.randomUUID(),
+        name: "default",
+        keyHash,
+        keyPrefix,
+        scopes: ["*"],
+        createdAt: rotatedAt
+      }).run();
+    }
   });
   saveConfig({
     apiUrl: env.apiUrl || existingConfig?.apiUrl || `http://localhost:${process.env.CANONRY_PORT || "4100"}`,