@canonry/canonry 7.1.1 → 7.3.0

package/dist/cli.js

@@ -1,15 +1,7 @@
 #!/usr/bin/env node --import tsx
 import {
   AERO_TOOL_PROFILES,
-  backfillAiReferralPaths,
-  backfillAiReferralPathsCommand,
-  backfillAnswerMentionsCommand,
-  backfillAnswerVisibilityCommand,
-  backfillInsightsCommand,
-  backfillNormalizedPaths,
-  backfillNormalizedPathsCommand,
-  backfillSnapshotAttributionCommand,
-  backfillTrafficClassificationCommand,
+  OPENAI_RETRIEVAL_CONTRACT,
   checkLatestVersionForCli,
   cliRuntimeContext,
   coerceAgentProvider,
@@ -28,6 +20,11 @@ import {
   listAgentProviders,
   notePrintedUpdateAvailable,
   readCachedUpdateAvailable,
+  reparseStoredResult,
+  reparseStoredResult2,
+  reparseStoredResult3,
+  reparseStoredResult4,
+  reparseStoredResult5,
   setGoogleAuthConfig,
   setTelemetryPreference,
   setTelemetrySource,
@@ -35,11 +32,11 @@ import {
   trackCliCommandFinished,
   trackEvent,
   waitForServerRuntimeStartup
-} from "./chunk-22R5E5CY.js";
+} from "./chunk-MQPBOQUH.js";
 import {
   autoSyncSkills,
   formatAutoSyncNotice
-} from "./chunk-IAMECH2N.js";
+} from "./chunk-3JEUZ2K5.js";
 import {
   configExists,
   createApiClient,
@@ -56,13 +53,13 @@ import {
   saveConfig,
   saveConfigPatch,
   shouldPrintServeSkillsNudge
-} from "./chunk-MTSFSXCG.js";
+} from "./chunk-RVELNJAW.js";
 import {
   DEFAULT_DEMO_TRUSTED_PROXIES,
   trustedProxiesProblem,
   trustedProxyProblem
 } from "./chunk-RB2F4D3Z.js";
-import "./chunk-U2S5ABOR.js";
+import "./chunk-QND5LEAC.js";
 import {
   CliError,
   EXIT_SYSTEM_ERROR,
@@ -74,22 +71,36 @@ import {
   runMeasurementDraftAction,
   systemError,
   usageError
-} from "./chunk-2OQ6D26U.js";
+} from "./chunk-FWV6IIYY.js";
 import {
   CLOUDFLARE_WORKER_BINDINGS,
   CLOUDFLARE_WORKER_GENERATED_MARKER,
   CLOUDFLARE_WRANGLER_GENERATED_MARKER,
   DEFAULT_BOT_LIST,
+  aiUserFetchEventsHourly,
   apiKeys,
+  auditLog,
+  backfillProjectAnswerMentions,
+  classifyAiUserFetch,
+  classifyCrawler,
+  competitors,
+  crawlerEventsHourly,
   createClient,
+  createRunCompetitorResolver,
   dataRepairCompletions,
+  determineCitationState,
+  gaAiReferrals,
+  gaTrafficSnapshots,
   generateWorkerScript,
   generateWranglerToml,
   migrate,
+  parseJsonColumn,
   projects,
   queries,
+  querySnapshots,
+  rawEventSamples,
   runs
-} from "./chunk-VDX3LYKL.js";
+} from "./chunk-XODXE6PT.js";
 import {
   AdsDeliverySnapshotStatuses,
   AdsHistoricalCampaignRollupStatuses,
@@ -102,19 +113,25 @@ import {
   CheckScopes,
   CheckStatuses,
   CitationStates,
+  DiscoveryPromoteCompetitorSkipReasons,
   FEEDBACK_KINDS,
   GaMoverChangeBases,
   MeasurementEvidenceShapes,
   OUTSTANDING_PROVIDER_BATCH_STATUSES,
   ProviderBatchStatuses,
+  ProviderNames,
   READ_ONLY_SCOPE,
   RatioUnits,
   ResearchRunStatuses,
+  RetrievalContracts,
   RunKinds,
   RunStatuses,
   RunTriggers,
+  TrafficEventConfidences,
   TrafficEventKinds,
+  TrafficEvidenceKinds,
   TrafficSeriesGranularities,
+  TrafficSourceTypes,
   UNATTRIBUTED_MENTION_REASON,
   URL_PATH_NORMALIZATION_VERSION,
   USER_PASSWORD_MIN_LENGTH,
@@ -137,13 +154,17 @@ import {
   buildModelChangeNotice,
   canonicalizeGtmAccountId,
   canonicalizeGtmResourceSelection,
+  computeCompetitorOverlap,
   contentTargetDismissRequestSchema,
   conversionTrackingContractWriteRequestSchema,
   deduplicateResearchQueries,
   describeError,
+  determineAnswerMentioned,
   discoveryBucketSchema,
   discoveryCompetitorTypeSchema,
+  effectiveBrandNames,
   effectiveDomains,
+  extractRecommendedCompetitors,
   factorStatusFromScore,
   feedbackSubmissionSchema,
   formatGbpMetricLabel,
@@ -172,8 +193,11 @@ import {
   measurementQueryTemplateApplyRequestSchema,
   measurementQueryTemplateUpsertRequestSchema,
   measurementQuestionResultQuerySchema,
+  normalizeCompetitorAliases,
+  normalizeCompetitorDomain,
   normalizeProjectAliases,
   normalizeTelemetryStatus,
+  normalizeUrlPath,
   notificationEventSchema,
   parseTrafficAnalyticsPeriod,
   providerDispatchModeSchema,
@@ -200,7 +224,7 @@ import {
   visibilityCompareSelectionSchema,
   visibilityReportRequestSchema,
   winnabilityClassSchema
-} from "./chunk-YGHPT5B2.js";
+} from "./chunk-YQXQBFHT.js";
 
 // src/cli.ts
 import { pathToFileURL } from "url";
@@ -471,6 +495,19 @@ function ratedAnswersLine({ ratedAnswers, eligibleAnswers, ratedAnswerRate }) {
   if (ratedAnswerRate === null || ratedAnswerRate === void 0) return `Rated: Unavailable \xB7 ${eligibleAnswers} eligible ${eligibleAnswers === 1 ? "answer" : "answers"}`;
   return `Rated: ${formatPercent(ratedAnswerRate, RatioUnits.fraction)} \xB7 ${ratedAnswers} of ${eligibleAnswers} ${eligibleAnswers === 1 ? "answer" : "answers"} rated`;
 }
+var CRITICIZED_PROPERTIES_TITLE = "Most criticized properties";
+function printCriticizedProperties(value) {
+  const ranked = value.criticizedProperties;
+  if (!ranked?.keys.length) return;
+  const rows = new Map(value.breakdowns.filter((row) => row.dimension === "property").map((row) => [row.key, row]));
+  const listed = ranked.keys.flatMap((key) => rows.get(key) ?? []);
+  if (listed.length === 0) return;
+  console.log(`${CRITICIZED_PROPERTIES_TITLE}: ${listed.length} of ${ranked.total}`);
+  for (const row of listed) {
+    const { favorable, mixed, unfavorable } = row.coverage.counts;
+    console.log(`  ${row.label} (${row.key}): ${favorable} favorable \xB7 ${mixed} mixed \xB7 ${unfavorable} unfavorable \xB7 ${row.coverage.judged} judged`);
+  }
+}
 function printSummary(value) {
   const label = value.selection.queryClass === "branded" ? "Branded" : "Non-brand";
   console.log(`${label} sentiment: ${value.state}${value.provisional ? " \xB7 provisional" : ""}`);
@@ -497,6 +534,7 @@ function printSummary(value) {
     }
   }
   for (const row of value.breakdowns) if (row.dimension !== "query") console.log(`${row.dimension} ${row.label} \xB7 ${row.queryClass}: ${row.score.favorableDisplay} favorable \xB7 ${row.coverage.judged} of ${row.coverage.selected} judged`);
+  printCriticizedProperties(value);
   if (value.queryPage) console.log(`Query rows: ${value.queries.length} of ${value.queryPage.total}`);
   if (value.queryPage?.nextCursor) console.log(`Next query cursor: ${value.queryPage.nextCursor}`);
 }
@@ -511,7 +549,8 @@ async function configureSentiment(project2, request, format) {
 async function showSentimentEvidence(project2, query, format) {
   const value = await createApiClient().getSentimentEvidence(project2, query);
   if (machine(value, format)) return;
-  console.log(`${value.selection.queryClass} sentiment evidence: ${value.state} \xB7 definition ${value.selection.evaluationDefinitionId ?? "not measured"}`);
+  const outcomes = value.selection.outcome?.length ? ` \xB7 outcomes ${value.selection.outcome.join(", ")}` : "";
+  console.log(`${value.selection.queryClass} sentiment evidence: ${value.state} \xB7 definition ${value.selection.evaluationDefinitionId ?? "not measured"}${outcomes}`);
   for (const item of value.items) {
     console.log(`
 ${item.subject.displayName} \xB7 ${item.outcome} \xB7 ${item.context.provider} \xB7 run ${item.runId}`);
@@ -629,12 +668,13 @@ var SENTIMENT_CLI_COMMANDS = [
   },
   {
     path: ["sentiment", "evidence"],
-    usage: "canonry sentiment evidence <project> [selection options] [--assessment-id <id>] [--cursor <cursor>] [--limit 1..100] [--format json]",
-    help: `${readSelectionHelp} Use --assessment-id from a query assessment to read that exact stored verdict; existing scope filters still apply. Keep all selection fields, including assessmentId and the returned evaluationDefinitionId, when following a cursor. JSONL preserves the entire page envelope, including empty state and next cursor.`,
-    options: { ...readSelectionOptions, "assessment-id": stringOption(), cursor: stringOption(), limit: stringOption() },
+    usage: "canonry sentiment evidence <project> [selection options] [--assessment-id <id>] [--outcome mixed,unfavorable] [--cursor <cursor>] [--limit 1..100] [--format json]",
+    help: `${readSelectionHelp} Use --assessment-id from a query assessment to read that exact stored verdict; existing scope filters still apply. --outcome keeps only assessments with those outcomes (comma-separated or repeated, for example --outcome mixed,unfavorable for the criticism behind a branded score or the non-brand exceptions); it never changes how they were scored. Keep all selection fields, including assessmentId, outcome and the returned evaluationDefinitionId, when following a cursor. JSONL preserves the entire page envelope, including empty state and next cursor.`,
+    options: { ...readSelectionOptions, "assessment-id": stringOption(), outcome: multiStringOption(), cursor: stringOption(), limit: stringOption() },
     run: (input) => showSentimentEvidence(project(input, "evidence"), parse(sentimentEvidenceRequestSchema, {
       ...readSelection(input),
       assessmentId: getString(input.values, "assessment-id"),
+      outcome: getStringArray(input.values, "outcome")?.join(","),
       cursor: getString(input.values, "cursor"),
       limit: getString(input.values, "limit")
     }), input.format)
@@ -734,7 +774,7 @@ function parseDemoTrustedProxies(values) {
 async function demoCommand(options) {
   const { host, port } = parseDemoListenOptions(options);
   const trustProxy = parseDemoTrustedProxies(options.trustProxy);
-  const { createDemoServer } = await import("./demo-server-TIMYQLXS.js");
+  const { createDemoServer } = await import("./demo-server-BXABH765.js");
   const app = await createDemoServer({ trustProxy });
   let stopping = false;
   const stop = () => {
@@ -780,6 +820,908 @@ var DEMO_CLI_COMMANDS = [{
   }
 }];
 
+// src/commands/backfill.ts
+import { setImmediate as yieldToEventLoop } from "timers/promises";
+import { and, asc, desc, eq, gt, inArray, isNull, lte, sql } from "drizzle-orm";
+var SNAPSHOT_BATCH_SIZE = 500;
+var PATH_REPAIR_PAGE_SIZE = 128;
+async function backfillAnswerVisibilityCommand(opts) {
+  const config = loadConfig();
+  const db = createClient(config.database);
+  migrate(db);
+  const projectFilter = opts?.project?.trim();
+  const isDryRun = opts?.dryRun === true;
+  const scopedProjects = projectFilter ? db.select().from(projects).where(eq(projects.name, projectFilter)).all() : db.select().from(projects).all();
+  let examined = 0;
+  let updated = 0;
+  let wouldUpdate = 0;
+  let mentioned = 0;
+  let reparsed = 0;
+  let providerErrors = 0;
+  let retrievalRelabeled = 0;
+  if (scopedProjects.length > 0) {
+    const runRows = projectFilter ? db.select({ id: runs.id, projectId: runs.projectId, planVersionId: runs.measurementPlanVersionId }).from(runs).where(and(
+      eq(runs.kind, RunKinds["answer-visibility"]),
+      inArray(runs.projectId, scopedProjects.map((project2) => project2.id))
+    )).all() : db.select({ id: runs.id, projectId: runs.projectId, planVersionId: runs.measurementPlanVersionId }).from(runs).where(eq(runs.kind, RunKinds["answer-visibility"])).all();
+    const planVersionByRun = new Map(runRows.map((run) => [run.id, run.planVersionId]));
+    const runIdsByProject = /* @__PURE__ */ new Map();
+    for (const run of runRows) {
+      const existing = runIdsByProject.get(run.projectId);
+      if (existing) existing.push(run.id);
+      else runIdsByProject.set(run.projectId, [run.id]);
+    }
+    for (const project2 of scopedProjects) {
+      const competitorsForRun = createRunCompetitorResolver(db, db.select({ domain: competitors.domain, aliases: competitors.aliases }).from(competitors).where(eq(competitors.projectId, project2.id)).all());
+      const runIds = runIdsByProject.get(project2.id) ?? [];
+      if (runIds.length === 0) continue;
+      const projectDomains = effectiveDomains({
+        canonicalDomain: project2.canonicalDomain,
+        ownedDomains: project2.ownedDomains
+      });
+      const projectBrandNames = effectiveBrandNames({
+        displayName: project2.displayName,
+        aliases: project2.aliases
+      });
+      for (let offset = 0; offset < runIds.length; offset += SNAPSHOT_BATCH_SIZE) {
+        const batchRunIds = runIds.slice(offset, offset + SNAPSHOT_BATCH_SIZE);
+        const snapshotRows = db.select({
+          id: querySnapshots.id,
+          runId: querySnapshots.runId,
+          executionId: querySnapshots.measurementExecutionId,
+          provider: querySnapshots.provider,
+          citationState: querySnapshots.citationState,
+          answerMentioned: querySnapshots.answerMentioned,
+          answerText: querySnapshots.answerText,
+          citedDomains: querySnapshots.citedDomains,
+          competitorOverlap: querySnapshots.competitorOverlap,
+          recommendedCompetitors: querySnapshots.recommendedCompetitors,
+          rawResponse: querySnapshots.rawResponse,
+          retrievalStatus: querySnapshots.retrievalStatus,
+          retrievalContract: querySnapshots.retrievalContract
+        }).from(querySnapshots).where(inArray(querySnapshots.runId, batchRunIds)).all();
+        const pendingUpdates = [];
+        for (const snapshot of snapshotRows) {
+          examined++;
+          const reparsedResult = reparseProviderSnapshot(snapshot.provider, snapshot.rawResponse);
+          if (reparsedResult) reparsed++;
+          if (reparsedResult?.providerError) providerErrors++;
+          const answerText = reparsedResult?.answerText ?? snapshot.answerText ?? "";
+          const nextValue = determineAnswerMentioned(answerText, projectBrandNames, projectDomains);
+          if (nextValue) mentioned++;
+          const nextPatch = {};
+          if (snapshot.answerMentioned !== nextValue) {
+            nextPatch.answerMentioned = nextValue;
+          }
+          if ((snapshot.answerText ?? "") !== answerText) {
+            nextPatch.answerText = answerText;
+          }
+          if (reparsedResult) {
+            const normalized = {
+              provider: snapshot.provider,
+              answerText,
+              citedDomains: reparsedResult.citedDomains,
+              groundingSources: reparsedResult.groundingSources,
+              searchQueries: reparsedResult.searchQueries,
+              // Only feeds the citation/mention helpers below, which ignore
+              // it. Retrieval is written back solely by the narrow OpenAI
+              // contract correction after this block.
+              retrievalStatus: "unknown"
+            };
+            const nextCitationState = determineCitationState(normalized, projectDomains);
+            const nextCitedDomains = reparsedResult.citedDomains;
+            const runCompetitors = competitorsForRun(planVersionByRun.get(snapshot.runId), snapshot.executionId);
+            const nextCompetitorOverlap = computeCompetitorOverlap(normalized, runCompetitors.domains, runCompetitors.aliases);
+            const nextRecommendedCompetitors = extractRecommendedCompetitors(
+              normalized.answerText,
+              projectDomains,
+              normalized.citedDomains,
+              runCompetitors.domains,
+              projectBrandNames,
+              runCompetitors.aliases
+            );
+            const nextRawResponse = stringifyStoredSnapshotEnvelope(
+              snapshot.rawResponse,
+              reparsedResult
+            );
+            if (snapshot.citationState !== nextCitationState) {
+              nextPatch.citationState = nextCitationState;
+            }
+            if (JSON.stringify(snapshot.citedDomains) !== JSON.stringify(nextCitedDomains)) {
+              nextPatch.citedDomains = nextCitedDomains;
+            }
+            if (JSON.stringify(snapshot.competitorOverlap) !== JSON.stringify(nextCompetitorOverlap)) {
+              nextPatch.competitorOverlap = nextCompetitorOverlap;
+            }
+            if (JSON.stringify(snapshot.recommendedCompetitors) !== JSON.stringify(nextRecommendedCompetitors)) {
+              nextPatch.recommendedCompetitors = nextRecommendedCompetitors;
+            }
+            if (snapshot.rawResponse !== nextRawResponse) {
+              nextPatch.rawResponse = nextRawResponse;
+            }
+          }
+          const retrievalCorrection = correctStoredOpenAIRetrieval(snapshot, reparsedResult);
+          if (retrievalCorrection) {
+            retrievalRelabeled++;
+            Object.assign(nextPatch, retrievalCorrection);
+          }
+          if (Object.keys(nextPatch).length > 0) {
+            pendingUpdates.push({ id: snapshot.id, patch: nextPatch });
+          }
+        }
+        if (pendingUpdates.length > 0) {
+          if (isDryRun) {
+            wouldUpdate += pendingUpdates.length;
+          } else {
+            db.transaction((tx) => {
+              for (const update of pendingUpdates) {
+                tx.update(querySnapshots).set(update.patch).where(eq(querySnapshots.id, update.id)).run();
+              }
+            });
+            updated += pendingUpdates.length;
+          }
+        }
+      }
+    }
+  }
+  const result = {
+    project: projectFilter ?? null,
+    projects: scopedProjects.length,
+    examined,
+    updated,
+    mentioned,
+    reparsed,
+    providerErrors,
+    retrievalRelabeled
+  };
+  if (isDryRun) {
+    result.dryRun = true;
+    result.wouldUpdate = wouldUpdate;
+  }
+  if (isMachineFormat(opts?.format)) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`Answer visibility backfill ${isDryRun ? "preview" : "complete"}.
+`);
+  if (projectFilter) {
+    console.log(`  Project:  ${projectFilter}`);
+  }
+  console.log(`  Projects: ${scopedProjects.length}`);
+  console.log(`  Examined:     ${examined}`);
+  if (isDryRun) {
+    console.log(`  Would update: ${wouldUpdate}`);
+  } else {
+    console.log(`  Updated:      ${updated}`);
+  }
+  console.log(`  Mentioned:    ${mentioned}`);
+  console.log(`  Reparsed:     ${reparsed}`);
+  console.log(`  Errors:       ${providerErrors}`);
+  console.log(`  Relabeled:    ${retrievalRelabeled} (OpenAI retrieval contract)`);
+  if (isDryRun) {
+    console.log(`
+No DB writes performed. Re-run without --dry-run to apply.`);
+  }
+}
+function backfillNormalizedPaths(db, opts) {
+  return repairStoredPaths(db, gaTrafficSnapshots, opts);
+}
+async function repairStoredPaths(db, table, opts) {
+  const pageSize = opts?.pageSize ?? PATH_REPAIR_PAGE_SIZE;
+  const projectScope = opts?.projectId ? sql`+${table.projectId} = ${opts.projectId}` : void 0;
+  const lastId = db.select({ id: table.id }).from(table).where(projectScope).orderBy(desc(table.id)).limit(1).get()?.id;
+  if (lastId === void 0) return { examined: 0, updated: 0, unchanged: 0 };
+  let cursor;
+  let examined = 0;
+  let updated = 0;
+  for (; ; ) {
+    const rows = db.select({
+      id: table.id,
+      projectId: table.projectId,
+      landingPage: table.landingPage,
+      landingPageNormalized: table.landingPageNormalized
+    }).from(table).where(and(
+      projectScope,
+      lte(table.id, lastId),
+      cursor === void 0 ? void 0 : gt(table.id, cursor)
+    )).orderBy(asc(table.id)).limit(pageSize).all();
+    examined += rows.length;
+    const changes = rows.flatMap((row) => {
+      const next = normalizeUrlPath(row.landingPage);
+      return next === null || row.landingPageNormalized === next ? [] : [{ row, next }];
+    });
+    if (changes.length > 0) {
+      const written = db.transaction((tx) => {
+        let written2 = 0;
+        for (const { row, next } of changes) {
+          written2 += tx.update(table).set({ landingPageNormalized: next }).where(and(
+            eq(table.id, row.id),
+            eq(table.projectId, row.projectId),
+            eq(table.landingPage, row.landingPage),
+            row.landingPageNormalized === null ? isNull(table.landingPageNormalized) : eq(table.landingPageNormalized, row.landingPageNormalized)
+          )).run().changes;
+        }
+        return written2;
+      });
+      updated += written;
+      if (written < changes.length) opts?.onConflict?.();
+    }
+    if (rows.length < pageSize) break;
+    cursor = rows.at(-1).id;
+    if (cursor === lastId) break;
+    await yieldToEventLoop();
+  }
+  return { examined, updated, unchanged: examined - updated };
+}
+async function backfillNormalizedPathsCommand(opts) {
+  const config = loadConfig();
+  const db = createClient(config.database);
+  migrate(db);
+  const projectFilter = opts?.project?.trim();
+  let projectId;
+  if (projectFilter) {
+    const project2 = db.select({ id: projects.id }).from(projects).where(eq(projects.name, projectFilter)).get();
+    if (!project2) {
+      const result2 = {
+        project: projectFilter,
+        examined: 0,
+        updated: 0,
+        unchanged: 0
+      };
+      if (isMachineFormat(opts?.format)) {
+        console.log(JSON.stringify(result2, null, 2));
+        return;
+      }
+      console.log(`Backfill normalized-paths: project "${projectFilter}" not found.`);
+      return;
+    }
+    projectId = project2.id;
+  }
+  const { examined, updated, unchanged } = await backfillNormalizedPaths(db, { projectId });
+  const result = {
+    project: projectFilter ?? null,
+    examined,
+    updated,
+    unchanged
+  };
+  if (isMachineFormat(opts?.format)) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log("Normalized-path backfill complete.\n");
+  if (projectFilter) console.log(`  Project:   ${projectFilter}`);
+  console.log(`  Examined:  ${examined}`);
+  console.log(`  Updated:   ${updated}`);
+  console.log(`  Unchanged: ${unchanged}`);
+}
+function backfillAiReferralPaths(db, opts) {
+  return repairStoredPaths(db, gaAiReferrals, opts);
+}
+async function backfillAiReferralPathsCommand(opts) {
+  const config = loadConfig();
+  const db = createClient(config.database);
+  migrate(db);
+  const projectFilter = opts?.project?.trim();
+  let projectId;
+  if (projectFilter) {
+    const project2 = db.select({ id: projects.id }).from(projects).where(eq(projects.name, projectFilter)).get();
+    if (!project2) {
+      const result2 = {
+        project: projectFilter,
+        examined: 0,
+        updated: 0,
+        unchanged: 0
+      };
+      if (isMachineFormat(opts?.format)) {
+        console.log(JSON.stringify(result2, null, 2));
+        return;
+      }
+      console.log(`Backfill ai-referral-paths: project "${projectFilter}" not found.`);
+      return;
+    }
+    projectId = project2.id;
+  }
+  const { examined, updated, unchanged } = await backfillAiReferralPaths(db, { projectId });
+  const result = {
+    project: projectFilter ?? null,
+    examined,
+    updated,
+    unchanged
+  };
+  if (isMachineFormat(opts?.format)) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log("AI referral landing-page backfill complete.\n");
+  if (projectFilter) console.log(`  Project:   ${projectFilter}`);
+  console.log(`  Examined:  ${examined}`);
+  console.log(`  Updated:   ${updated}`);
+  console.log(`  Unchanged: ${unchanged}`);
+}
+async function backfillAnswerMentionsCommand(opts) {
+  const config = loadConfig();
+  const db = createClient(config.database);
+  migrate(db);
+  const projectFilter = opts?.project?.trim();
+  const isDryRun = opts?.dryRun === true;
+  const scopedProjects = projectFilter ? db.select().from(projects).where(eq(projects.name, projectFilter)).all() : db.select().from(projects).all();
+  let examined = 0;
+  let updated = 0;
+  let wouldUpdate = 0;
+  let mentioned = 0;
+  for (const project2 of scopedProjects) {
+    const result2 = backfillProjectAnswerMentions(db, project2.id, { dryRun: isDryRun });
+    examined += result2.examined;
+    updated += result2.updated;
+    wouldUpdate += result2.wouldUpdate ?? 0;
+    mentioned += result2.mentioned;
+  }
+  const result = {
+    project: projectFilter ?? null,
+    projects: scopedProjects.length,
+    examined,
+    updated,
+    mentioned
+  };
+  if (isDryRun) {
+    result.dryRun = true;
+    result.wouldUpdate = wouldUpdate;
+  }
+  if (isMachineFormat(opts?.format)) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`Answer mentions backfill ${isDryRun ? "preview" : "complete"}.
+`);
+  if (projectFilter) console.log(`  Project:      ${projectFilter}`);
+  console.log(`  Projects:     ${scopedProjects.length}`);
+  console.log(`  Examined:     ${examined}`);
+  if (isDryRun) {
+    console.log(`  Would update: ${wouldUpdate}`);
+  } else {
+    console.log(`  Updated:      ${updated}`);
+  }
+  console.log(`  Mentioned:    ${mentioned}`);
+  if (isDryRun) {
+    console.log(`
+No DB writes performed. Re-run without --dry-run to apply.`);
+  }
+}
+async function backfillInsightsCommand(project2, opts) {
+  const { IntelligenceService } = await import("./intelligence-service-EIWYQYVG.js");
+  const config = loadConfig();
+  const db = createClient(config.database);
+  migrate(db);
+  const service = new IntelligenceService(db);
+  const isJson = isMachineFormat(opts?.format);
+  const isDryRun = opts?.dryRun === true;
+  if (!isJson) {
+    const scope = opts?.since ? ` (since ${opts.since})` : "";
+    const mode = isDryRun ? " [DRY RUN \u2014 no writes]" : "";
+    process.stderr.write(`Backfilling insights for "${project2}"${scope}${mode}...
+`);
+  }
+  const result = service.backfill(project2, {
+    fromRunId: opts?.fromRun,
+    toRunId: opts?.toRun,
+    since: opts?.since,
+    dryRun: isDryRun
+  }, (info) => {
+    if (!isJson) {
+      process.stderr.write(`  [${info.index}/${info.total}] ${info.runId} \u2014 ${info.insights} insights
+`);
+    }
+  });
+  const output = {
+    project: project2,
+    processed: result.processed,
+    skipped: result.skipped,
+    totalInsights: result.totalInsights
+  };
+  if (result.dryRun) {
+    output.dryRun = true;
+    output.delta = result.delta;
+  }
+  if (isJson) {
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+  console.log(`
+Backfill ${isDryRun ? "preview" : "complete"}.`);
+  console.log(`  Processed: ${result.processed}`);
+  console.log(`  Skipped:   ${result.skipped}`);
+  console.log(`  Insights:  ${result.totalInsights}`);
+  if (result.delta) {
+    console.log(`  Delta:     -${result.delta.wouldDelete} existing  +${result.delta.wouldCreate} new  (net ${result.delta.netChange >= 0 ? "+" : ""}${result.delta.netChange})`);
+    console.log(`             No DB writes performed. Re-run without --dry-run to apply.`);
+  }
+}
+function replayQueryAuditLog(events) {
+  const active = [];
+  for (const ev of events) {
+    let diff;
+    try {
+      diff = ev.diff ? JSON.parse(ev.diff) : {};
+    } catch {
+      continue;
+    }
+    if (ev.action === "keywords.appended" || ev.action === "queries.appended") {
+      const added = Array.isArray(diff.added) ? diff.added : [];
+      for (const q of added) {
+        active.push({ text: q, addedAt: ev.createdAt, deletedAt: null });
+      }
+    } else if (ev.action === "keywords.deleted" || ev.action === "queries.deleted") {
+      const deleted = Array.isArray(diff.deleted) ? diff.deleted : [];
+      for (const q of deleted) {
+        for (let i = active.length - 1; i >= 0; i--) {
+          if (active[i].text === q && active[i].deletedAt === null) {
+            active[i].deletedAt = ev.createdAt;
+            break;
+          }
+        }
+      }
+    } else if (ev.action === "queries.replaced") {
+      const newSet = Array.isArray(diff.queries) ? diff.queries : [];
+      for (const e of active) {
+        if (e.deletedAt === null) e.deletedAt = ev.createdAt;
+      }
+      for (const q of newSet) {
+        active.push({ text: q, addedAt: ev.createdAt, deletedAt: null });
+      }
+    }
+  }
+  return active;
+}
+function activeQueriesAt(history, t) {
+  return history.filter((e) => e.addedAt <= t && (e.deletedAt === null || e.deletedAt > t)).map((e) => e.text);
+}
+var CONTENT_MATCH_STOPWORDS = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "and",
+  "or",
+  "but",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "have",
+  "has",
+  "had",
+  "do",
+  "does",
+  "did",
+  "will",
+  "would",
+  "could",
+  "should",
+  "may",
+  "might",
+  "can",
+  "this",
+  "that",
+  "these",
+  "those",
+  "i",
+  "you",
+  "he",
+  "she",
+  "it",
+  "we",
+  "they",
+  "what",
+  "which",
+  "who",
+  "how",
+  "why",
+  "when",
+  "where",
+  "with",
+  "for",
+  "from",
+  "of",
+  "in",
+  "on",
+  "at",
+  "to",
+  "by",
+  "as",
+  "best",
+  "most"
+]);
+function tokenizeForMatch(s) {
+  return s.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter((t) => t.length >= 3 && !CONTENT_MATCH_STOPWORDS.has(t));
+}
+function contentMatchScore(queryText, answerText) {
+  const queryTokens = [...new Set(tokenizeForMatch(queryText))];
+  if (queryTokens.length === 0) return 0;
+  const answerHead = answerText.slice(0, 300).toLowerCase();
+  const hit = queryTokens.filter((t) => answerHead.includes(t)).length;
+  return hit / queryTokens.length;
+}
+async function backfillSnapshotAttributionCommand(opts) {
+  const config = loadConfig();
+  const db = createClient(config.database);
+  migrate(db);
+  const project2 = db.select().from(projects).where(eq(projects.name, opts.project)).get();
+  if (!project2) {
+    throw new Error(`Project "${opts.project}" not found`);
+  }
+  const isJson = isMachineFormat(opts.format);
+  const isDryRun = opts.dryRun === true;
+  if (!isJson) {
+    const mode = isDryRun ? " [DRY RUN \u2014 no writes]" : "";
+    process.stderr.write(`Recovering orphan snapshot attribution for "${project2.name}"${mode}...
+`);
+  }
+  const events = db.select({ createdAt: auditLog.createdAt, action: auditLog.action, diff: auditLog.diff }).from(auditLog).where(and(
+    eq(auditLog.projectId, project2.id),
+    inArray(auditLog.action, ["keywords.appended", "keywords.deleted", "queries.appended", "queries.deleted", "queries.replaced"])
+  )).orderBy(auditLog.createdAt).all();
+  const history = replayQueryAuditLog(events);
+  const orphanRuns = db.select({
+    runId: runs.id,
+    createdAt: runs.createdAt,
+    location: runs.location
+  }).from(runs).innerJoin(querySnapshots, eq(querySnapshots.runId, runs.id)).where(and(
+    eq(runs.projectId, project2.id),
+    isNull(querySnapshots.queryId),
+    isNull(querySnapshots.queryText)
+  )).groupBy(runs.id).orderBy(runs.createdAt).all();
+  const result = {
+    project: project2.name,
+    examinedRuns: orphanRuns.length,
+    orphanSnapshots: 0,
+    recoveredByPosition: 0,
+    recoveredByContent: 0,
+    unrecovered: 0,
+    dryRun: isDryRun,
+    perRun: []
+  };
+  const updates = [];
+  for (const run of orphanRuns) {
+    const activeAt = activeQueriesAt(history, run.createdAt);
+    const orphanSnaps = db.select({
+      id: querySnapshots.id,
+      provider: querySnapshots.provider,
+      createdAt: querySnapshots.createdAt,
+      answerText: querySnapshots.answerText
+    }).from(querySnapshots).where(and(
+      eq(querySnapshots.runId, run.runId),
+      isNull(querySnapshots.queryId),
+      isNull(querySnapshots.queryText)
+    )).orderBy(querySnapshots.provider, querySnapshots.createdAt).all();
+    const byProvider = /* @__PURE__ */ new Map();
+    for (const s of orphanSnaps) {
+      const arr = byProvider.get(s.provider);
+      if (arr) arr.push(s);
+      else byProvider.set(s.provider, [s]);
+    }
+    let runPosition = 0;
+    let runContent = 0;
+    let runUnrecovered = 0;
+    for (const [, snaps] of byProvider) {
+      if (snaps.length === activeAt.length) {
+        for (let i = 0; i < snaps.length; i++) {
+          updates.push({ id: snaps[i].id, queryText: activeAt[i] });
+          runPosition++;
+        }
+      } else if (snaps.length < activeAt.length) {
+        const LOOKAHEAD_LIMIT = 5;
+        let cidx = 0;
+        for (const snap of snaps) {
+          const answerText = snap.answerText ?? "";
+          let matchedIdx = -1;
+          for (let i = cidx; i < Math.min(activeAt.length, cidx + LOOKAHEAD_LIMIT); i++) {
+            if (contentMatchScore(activeAt[i], answerText) >= 1) {
+              matchedIdx = i;
+              break;
+            }
+          }
+          if (matchedIdx >= 0) {
+            updates.push({ id: snap.id, queryText: activeAt[matchedIdx] });
+            runContent++;
+            cidx = matchedIdx + 1;
+          } else {
+            runUnrecovered++;
+          }
+        }
+      } else {
+        runUnrecovered += snaps.length;
+      }
+    }
+    result.orphanSnapshots += orphanSnaps.length;
+    result.recoveredByPosition += runPosition;
+    result.recoveredByContent += runContent;
+    result.unrecovered += runUnrecovered;
+    result.perRun.push({
+      runId: run.runId,
+      runCreatedAt: run.createdAt,
+      activeQueryCount: activeAt.length,
+      orphanSnaps: orphanSnaps.length,
+      recoveredPosition: runPosition,
+      recoveredContent: runContent,
+      unrecovered: runUnrecovered
+    });
+    if (!isJson) {
+      process.stderr.write(
+        `  ${run.createdAt} loc=${run.location ?? "-"} \u2192 ${orphanSnaps.length} orphan; ${runPosition} position-matched, ${runContent} content-matched, ${runUnrecovered} unrecovered
+`
+      );
+    }
+  }
+  if (!isDryRun && updates.length > 0) {
+    db.transaction((tx) => {
+      for (const u of updates) {
+        tx.update(querySnapshots).set({ queryText: u.queryText }).where(eq(querySnapshots.id, u.id)).run();
+      }
+    });
+  }
+  if (isJson) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`
+Snapshot attribution ${isDryRun ? "preview" : "recovery"} complete.`);
+  console.log(`  Examined runs:        ${result.examinedRuns}`);
+  console.log(`  Orphan snapshots:     ${result.orphanSnapshots}`);
+  console.log(`  Position-matched:     ${result.recoveredByPosition}`);
+  console.log(`  Content-matched:      ${result.recoveredByContent}`);
+  console.log(`  Unrecovered:          ${result.unrecovered}`);
+  if (isDryRun) {
+    console.log(`
+No DB writes performed. Re-run without --dry-run to apply.`);
+  }
+}
+function correctStoredOpenAIRetrieval(snapshot, reparsed) {
+  if (snapshot.provider !== ProviderNames.openai) return null;
+  if (snapshot.retrievalContract !== RetrievalContracts["native-auto-v1"]) return null;
+  return {
+    retrievalContract: OPENAI_RETRIEVAL_CONTRACT,
+    ...reparsed?.retrievalStatus === void 0 ? {} : { retrievalStatus: reparsed.retrievalStatus }
+  };
+}
+function reparseProviderSnapshot(provider, rawResponse) {
+  const envelope = parseJsonColumn(rawResponse, {});
+  const apiResponse = resolveStoredApiResponse(envelope);
+  if (!apiResponse) return null;
+  switch (provider) {
+    case ProviderNames.openai:
+      return reparseStoredResult(apiResponse);
+    case ProviderNames.claude:
+      return reparseStoredResult2(apiResponse);
+    case ProviderNames.gemini:
+      return reparseStoredResult3(apiResponse);
+    case ProviderNames.perplexity:
+      return reparseStoredResult4(apiResponse);
+    case ProviderNames.muse:
+      return reparseStoredResult5(apiResponse);
+    default:
+      return null;
+  }
+}
+function resolveStoredApiResponse(parsed) {
+  const nested = parsed.apiResponse;
+  if (nested !== null && typeof nested === "object" && !Array.isArray(nested)) {
+    return nested;
+  }
+  if (looksLikeProviderApiResponse(parsed)) {
+    return parsed;
+  }
+  return null;
+}
+function looksLikeProviderApiResponse(value) {
+  return Array.isArray(value.output) || Array.isArray(value.content) || Array.isArray(value.candidates) || Array.isArray(value.choices);
+}
+function stringifyStoredSnapshotEnvelope(rawResponse, reparsed) {
+  const parsed = parseJsonColumn(rawResponse, {});
+  const apiResponse = resolveStoredApiResponse(parsed);
+  const envelope = apiResponse === parsed ? {} : { ...parsed };
+  delete envelope.answerText;
+  delete envelope.citedDomains;
+  delete envelope.competitorOverlap;
+  delete envelope.recommendedCompetitors;
+  delete envelope.providerError;
+  return JSON.stringify({
+    ...envelope,
+    groundingSources: reparsed.groundingSources,
+    searchQueries: reparsed.searchQueries,
+    ...reparsed.providerError ? { providerError: reparsed.providerError } : {},
+    ...apiResponse ? { apiResponse } : {}
+  });
+}
+async function backfillTrafficClassificationCommand(opts) {
+  const config = loadConfig();
+  const db = createClient(config.database);
+  migrate(db);
+  const projectFilter = opts?.project?.trim();
+  const isDryRun = opts?.dryRun === true;
+  const isJson = isMachineFormat(opts?.format);
+  const scopedProjects = projectFilter ? db.select().from(projects).where(eq(projects.name, projectFilter)).all() : db.select().from(projects).all();
+  if (scopedProjects.length === 0) {
+    if (projectFilter && !isJson) {
+      process.stderr.write(`No project named "${projectFilter}".
+`);
+    }
+    if (isJson) console.log(JSON.stringify({ project: projectFilter ?? null, examined: 0, reclassified: 0 }));
+    return;
+  }
+  if (!isJson) {
+    const mode = isDryRun ? " [DRY RUN \u2014 no writes]" : "";
+    const scope = projectFilter ? `"${projectFilter}"` : "all projects";
+    process.stderr.write(`Re-classifying unknown traffic samples for ${scope}${mode}...
+`);
+  }
+  const projectIds = scopedProjects.map((p) => p.id);
+  const result = {
+    project: projectFilter ?? null,
+    examined: 0,
+    reclassified: 0,
+    unknownBefore: 0,
+    unknownAfter: 0,
+    dryRun: isDryRun,
+    byBot: {}
+  };
+  const unknownCountRow = db.select({ n: sql`count(*)` }).from(rawEventSamples).where(and(
+    eq(rawEventSamples.eventType, "unknown"),
+    inArray(rawEventSamples.projectId, projectIds)
+  )).get();
+  result.unknownBefore = Number(unknownCountRow?.n ?? 0);
+  const unknownSamples = db.select({
+    id: rawEventSamples.id,
+    projectId: rawEventSamples.projectId,
+    sourceId: rawEventSamples.sourceId,
+    ts: rawEventSamples.ts,
+    userAgent: rawEventSamples.userAgent,
+    pathNormalized: rawEventSamples.pathNormalized,
+    status: rawEventSamples.status
+  }).from(rawEventSamples).where(and(
+    eq(rawEventSamples.eventType, "unknown"),
+    inArray(rawEventSamples.projectId, projectIds)
+  )).all();
+  result.examined = unknownSamples.length;
+  if (unknownSamples.length === 0) {
+    result.unknownAfter = result.unknownBefore;
+    emitTrafficClassificationReport(result, isJson);
+    return;
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  for (const snap of unknownSamples) {
+    if (!snap.userAgent) continue;
+    const probe = {
+      sourceType: TrafficSourceTypes["cloud-run"],
+      evidenceKind: TrafficEvidenceKinds["raw-request"],
+      confidence: TrafficEventConfidences.observed,
+      eventId: snap.id,
+      observedAt: snap.ts,
+      method: "GET",
+      requestUrl: `https://placeholder${snap.pathNormalized}`,
+      host: "placeholder",
+      path: snap.pathNormalized,
+      queryString: null,
+      status: snap.status ?? 200,
+      userAgent: snap.userAgent,
+      remoteIp: null,
+      referer: null,
+      latencyMs: null,
+      requestSizeBytes: null,
+      responseSizeBytes: null,
+      providerResource: { type: "cloud_run_revision", labels: {} },
+      providerLabels: {}
+    };
+    const userFetch = classifyAiUserFetch(probe);
+    const classified = userFetch ?? classifyCrawler(probe);
+    if (!classified) continue;
+    result.reclassified++;
+    result.byBot[classified.botId] = (result.byBot[classified.botId] ?? 0) + 1;
+    if (isDryRun) continue;
+    const tsHour = new Date(snap.ts);
+    tsHour.setUTCMinutes(0, 0, 0);
+    const tsHourIso = tsHour.toISOString();
+    const status = snap.status ?? 200;
+    db.transaction((tx) => {
+      tx.update(rawEventSamples).set({ eventType: userFetch ? TrafficEventKinds["ai-user-fetch"] : TrafficEventKinds.crawler }).where(eq(rawEventSamples.id, snap.id)).run();
+      if (userFetch) {
+        tx.insert(aiUserFetchEventsHourly).values({
+          projectId: snap.projectId,
+          sourceId: snap.sourceId,
+          tsHour: tsHourIso,
+          botId: userFetch.botId,
+          operator: userFetch.operator,
+          verificationStatus: userFetch.verificationStatus,
+          pathNormalized: snap.pathNormalized,
+          status,
+          hits: 1,
+          sampledUserAgent: snap.userAgent,
+          createdAt: now,
+          updatedAt: now
+        }).onConflictDoUpdate({
+          target: [
+            aiUserFetchEventsHourly.projectId,
+            aiUserFetchEventsHourly.sourceId,
+            aiUserFetchEventsHourly.tsHour,
+            aiUserFetchEventsHourly.botId,
+            aiUserFetchEventsHourly.verificationStatus,
+            aiUserFetchEventsHourly.pathNormalized,
+            aiUserFetchEventsHourly.status
+          ],
+          set: {
+            hits: sql`${aiUserFetchEventsHourly.hits} + 1`,
+            updatedAt: now
+          }
+        }).run();
+      } else {
+        tx.insert(crawlerEventsHourly).values({
+          projectId: snap.projectId,
+          sourceId: snap.sourceId,
+          tsHour: tsHourIso,
+          botId: classified.botId,
+          operator: classified.operator,
+          verificationStatus: classified.verificationStatus,
+          pathNormalized: snap.pathNormalized,
+          status,
+          hits: 1,
+          sampledUserAgent: snap.userAgent,
+          createdAt: now,
+          updatedAt: now
+        }).onConflictDoUpdate({
+          target: [
+            crawlerEventsHourly.projectId,
+            crawlerEventsHourly.sourceId,
+            crawlerEventsHourly.tsHour,
+            crawlerEventsHourly.botId,
+            crawlerEventsHourly.verificationStatus,
+            crawlerEventsHourly.pathNormalized,
+            crawlerEventsHourly.status
+          ],
+          set: {
+            hits: sql`${crawlerEventsHourly.hits} + 1`,
+            updatedAt: now
+          }
+        }).run();
+      }
+    });
+  }
+  if (!isDryRun) {
+    const afterRow = db.select({ n: sql`count(*)` }).from(rawEventSamples).where(and(
+      eq(rawEventSamples.eventType, "unknown"),
+      inArray(rawEventSamples.projectId, projectIds)
+    )).get();
+    result.unknownAfter = Number(afterRow?.n ?? 0);
+  } else {
+    result.unknownAfter = result.unknownBefore - result.reclassified;
+  }
+  emitTrafficClassificationReport(result, isJson);
+}
+function emitTrafficClassificationReport(result, isJson) {
+  if (isJson) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  const verb = result.dryRun ? "Would re-classify" : "Re-classified";
+  console.log(`
+Traffic classification ${result.dryRun ? "preview" : "recovery"} complete.`);
+  console.log(`  Examined unknowns:   ${result.examined}`);
+  console.log(`  ${verb}:        ${result.reclassified}`);
+  console.log(`  Unknown before:      ${result.unknownBefore}`);
+  console.log(`  Unknown after:       ${result.unknownAfter}`);
+  if (result.reclassified > 0) {
+    console.log(`  By bot:`);
+    const sorted = Object.entries(result.byBot).sort(([, a], [, b]) => b - a);
+    for (const [bot, count] of sorted) {
+      console.log(`    ${count.toString().padStart(5)}  ${bot}`);
+    }
+  }
+  if (result.dryRun) {
+    console.log(`
+No DB writes performed. Re-run without --dry-run to apply.`);
+  }
+}
+
 // src/cli-commands/backfill.ts
 var BACKFILL_CLI_COMMANDS = [
   {
@@ -2317,10 +3259,16 @@ async function discoverPromotePreview(project2, sessionId, opts) {
   if (preview.suggestedCompetitors.length > 0) {
     console.log(`  Suggested new competitors:`);
     for (const c of preview.suggestedCompetitors) {
-      console.log(`    - ${c.domain} (${c.hits} hits, ${c.competitorType})`);
+      console.log(`    - ${c.domain} (${c.hits} hits, ${c.competitorType})${mergedHostsNote(c)}`);
     }
     console.log("    Only direct-competitor is promoted by default \u2014 pass --competitor-types to include other types.");
   }
+  const skippedCompetitors = preview.skippedCompetitors ?? [];
+  const held = skippedCompetitors.filter((c) => c.reason !== DiscoveryPromoteCompetitorSkipReasons["already-tracked"]);
+  if (held.length > 0) {
+    console.log(`  Competitors a promote leaves out:`);
+    for (const c of held) console.log(`    ! ${c.domain} (${c.reason}): ${c.message}`);
+  }
   console.log(`
   Run \`canonry discover promote ${project2} ${sessionId}\` to merge cited + aspirational queries.`);
   console.log("  Add `--bucket wasted-surface` only when off-ICP competitor gaps should be tracked.");
@@ -2337,15 +3285,24 @@ async function discoverPromote(project2, sessionId, opts) {
     return;
   }
   const { promoted, skipped } = result;
+  const competitorDetails = result.competitorDetails;
+  const promotedCompetitors = competitorDetails?.promoted ?? promoted.competitors.map((domain) => ({ domain }));
+  const held = (competitorDetails?.skipped ?? []).filter((c) => c.reason !== DiscoveryPromoteCompetitorSkipReasons["already-tracked"]);
   console.log(`Promoted discovery session ${sessionId} into "${project2}":`);
   console.log(`  Queries:     ${promoted.queries.length} added, ${skipped.queries.length} already tracked`);
   for (const q of promoted.queries) console.log(`    + ${q}`);
-  console.log(`  Competitors: ${promoted.competitors.length} added, ${skipped.competitors.length} already tracked`);
-  for (const c of promoted.competitors) console.log(`    + ${c}`);
+  console.log(`  Competitors: ${promoted.competitors.length} added, ${skipped.competitors.length - held.length} already tracked, ${held.length} left out`);
+  for (const c of promotedCompetitors) console.log(`    + ${c.domain}${mergedHostsNote(c)}`);
+  for (const c of held) console.log(`    ! ${c.domain} (${c.reason}): ${c.message}`);
   if (promoted.queries.length === 0 && promoted.competitors.length === 0) {
     console.log(`  Nothing new \u2014 the project's basket already covers this session.`);
   }
 }
+function mergedHostsNote(competitor) {
+  const sources = competitor.sources ?? [];
+  const hosts = sources.map((source) => source.domain).filter((host) => host !== competitor.domain);
+  return hosts.length > 0 ? ` (from ${sources.map((source) => source.domain).join(", ")})` : "";
+}
 function printSessionDetail(session) {
   console.log(`Discovery session: ${session.id}`);
   console.log(`  Status:        ${session.status}`);
@@ -8133,21 +9090,28 @@ var TRAFFIC_CLI_COMMANDS = [
 function getClient10() {
   return createApiClient();
 }
-async function addCompetitors(project2, domains, format) {
+async function addCompetitors(project2, domains, format, aliases = []) {
   const client = getClient10();
   const existing = await client.listCompetitors(project2);
   const existingDomains = existing.map((c) => c.domain);
   const existingSet = new Set(existingDomains);
-  const requested = new Set(uniqueStrings(domains));
-  const current = await client.appendCompetitors(project2, domains);
+  const requested = new Set(uniqueStrings(domains).map((domain) => normalizeCompetitorDomain(domain.trim())));
+  const current = await client.appendCompetitors(
+    project2,
+    aliases.length > 0 ? domains.map((domain) => ({ domain, aliases })) : domains
+  );
   const currentDomains = current.map((c) => c.domain);
   const addedDomains = currentDomains.filter((domain) => requested.has(domain) && !existingSet.has(domain));
+  const aliasTarget = aliases.length > 0 ? normalizeCompetitorDomain(domains[0].trim()) : null;
+  const aliasRow = aliasTarget ? current.find((c) => normalizeCompetitorDomain(c.domain) === aliasTarget) : void 0;
   if (isMachineFormat(format)) {
     console.log(JSON.stringify({
       project: project2,
       domains: currentDomains,
       addedDomains,
-      addedCount: addedDomains.length
+      addedCount: addedDomains.length,
+      // The aliased competitor as the API returns it (`CompetitorDto`).
+      ...aliasRow ? { competitor: aliasRow } : {}
     }, null, 2));
     return;
   }
@@ -8156,15 +9120,75 @@ async function addCompetitors(project2, domains, format) {
   } else {
     console.log(`Added ${addedDomains.length} competitor(s) to "${project2}".`);
   }
+  if (aliasRow) console.log(`Aliases for ${aliasRow.domain}: ${formatAliases(storedAliases(aliasRow))}`);
+}
+function storedAliases(competitor) {
+  return competitor.aliases ?? [];
+}
+function formatAliases(aliases) {
+  return aliases.length > 0 ? aliases.join(", ") : "(none)";
+}
+function sameAliasName(a, b) {
+  return a.trim().toLowerCase() === b.trim().toLowerCase();
+}
+async function competitorAliases(project2, domain, options) {
+  const client = getClient10();
+  let result;
+  if (options.set !== void 0 || options.clear === true) {
+    result = await client.setCompetitorAliases(project2, domain, options.clear ? [] : options.set ?? []);
+  } else {
+    const target = normalizeCompetitorDomain(domain.trim());
+    const matches = (await client.listCompetitors(project2)).filter((c) => normalizeCompetitorDomain(c.domain) === target);
+    if (matches.length > 1) {
+      const rows = [...matches].sort((a, b) => a.domain.localeCompare(b.domain));
+      const aliases = normalizeCompetitorAliases(rows.flatMap(storedAliases));
+      const addAgain = `canonry competitor add ${project2} ${target}${aliases.map((alias) => ` --alias ${JSON.stringify(alias)}`).join("")}`;
+      const stored = `${matches.length} rows (${rows.map((c) => c.domain).join(", ")})`;
+      throw new CliError({
+        code: "VALIDATION_ERROR",
+        message: `Competitor ${target} is stored as ${stored}; remove the competitor (every row goes) and add it again: ${addAgain}`,
+        displayMessage: `Error: competitor ${target} is stored as ${stored}. Remove it with: canonry competitor remove ${project2} ${target}, then add it again with: ${addAgain}`,
+        details: { project: project2, domain: target, matches: rows.map((c) => ({ id: c.id, domain: c.domain })), aliases }
+      });
+    }
+    const current = matches.at(0);
+    if (!current) {
+      throw new CliError({
+        code: "NOT_FOUND",
+        message: `Competitor "${target}" is not tracked by project "${project2}"`,
+        displayMessage: `Error: competitor "${target}" is not tracked by "${project2}". Add it with: canonry competitor add ${project2} ${target}`,
+        details: { project: project2, domain: target }
+      });
+    }
+    const removed = options.remove ?? [];
+    const added = options.add ?? [];
+    if (added.length === 0 && removed.length === 0) {
+      result = current;
+    } else if (removed.length === 0) {
+      const listed = await client.appendCompetitors(project2, [{ domain: current.domain, aliases: added }]);
+      result = listed.find((c) => c.domain === current.domain) ?? current;
+    } else {
+      const next = [
+        ...storedAliases(current).filter((alias) => !removed.some((name) => sameAliasName(name, alias))),
+        ...added
+      ];
+      result = await client.setCompetitorAliases(project2, current.domain, next);
+    }
+  }
+  if (isMachineFormat(options.format)) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`Aliases for ${result.domain}: ${formatAliases(storedAliases(result))}`);
 }
 async function removeCompetitors(project2, domains, format) {
   const client = getClient10();
   const existing = await client.listCompetitors(project2);
   const existingDomains = existing.map((c) => c.domain);
-  const requested = new Set(uniqueStrings(domains));
+  const requested = new Set(uniqueStrings(domains).map((domain) => normalizeCompetitorDomain(domain.trim())));
   const current = await client.deleteCompetitors(project2, domains);
   const currentSet = new Set(current.map((c) => c.domain));
-  const removedDomains = existingDomains.filter((domain) => requested.has(domain) && !currentSet.has(domain));
+  const removedDomains = existingDomains.filter((domain) => requested.has(normalizeCompetitorDomain(domain)) && !currentSet.has(domain));
   if (isMachineFormat(format)) {
     console.log(JSON.stringify({
       project: project2,
@@ -8203,7 +9227,8 @@ async function listCompetitors(project2, format) {
   console.log(`Competitors for "${project2}" (${comps.length}):
 `);
   for (const c of comps) {
-    console.log(`  ${c.domain}`);
+    const aliases = storedAliases(c);
+    console.log(aliases.length > 0 ? `  ${c.domain}  (aliases: ${aliases.join(", ")})` : `  ${c.domain}`);
   }
 }
 async function showCompetitorLandscape(project2, options) {
@@ -8293,6 +9318,8 @@ function printLandscapeRows(heading, rows, showSampleCount = false, context, que
 }
 
 // src/cli-commands/competitor.ts
+var ADD_USAGE = "canonry competitor add <project> <domain...> [--alias <name>]... [--format json]";
+var ALIASES_USAGE = "canonry competitor aliases <project> <domain> [--set <name>]... [--add <name>]... [--remove <name>]... [--clear] [--format json]";
 var LANDSCAPE_USAGE = "canonry competitor landscape <project> [--window 7d|30d|90d|all] [--group-key <key>|--scope all-markets] [--by-model] [--provider <provider> [--model <id>]] [--query-class all|branded|non-brand] [--location <label>] [--run-id <id>] [--format json|jsonl]";
 function parseLandscapeScope(value) {
   if (value === void 0 || value === "") return void 0;
@@ -8305,20 +9332,63 @@ function parseLandscapeScope(value) {
 var COMPETITOR_CLI_COMMANDS = [
   {
     path: ["competitor", "add"],
-    usage: "canonry competitor add <project> <domain...> [--format json]",
+    usage: ADD_USAGE,
+    options: {
+      alias: multiStringOption()
+    },
     run: async (input) => {
-      const project2 = requireProject(input, "competitor.add", "canonry competitor add <project> <domain...> [--format json]");
+      const project2 = requireProject(input, "competitor.add", ADD_USAGE);
       const domains = input.positionals.slice(1);
       if (domains.length === 0) {
-        throw usageError("Error: project name and at least one domain required\nUsage: canonry competitor add <project> <domain...> [--format json]", {
+        throw usageError(`Error: project name and at least one domain required
+Usage: ${ADD_USAGE}`, {
           message: "project name and at least one domain required",
           details: {
             command: "competitor.add",
-            usage: "canonry competitor add <project> <domain...> [--format json]"
+            usage: ADD_USAGE
           }
         });
       }
-      await addCompetitors(project2, domains, input.format);
+      const aliases = getStringArray(input.values, "alias") ?? [];
+      if (aliases.length > 0 && domains.length !== 1) {
+        throw usageError(`Error: --alias names one competitor, so pass exactly one domain
+Usage: ${ADD_USAGE}`, {
+          message: "--alias names one competitor, so pass exactly one domain",
+          details: { command: "competitor.add", usage: ADD_USAGE }
+        });
+      }
+      await addCompetitors(project2, domains, input.format, aliases);
+    }
+  },
+  {
+    path: ["competitor", "aliases"],
+    usage: ALIASES_USAGE,
+    options: {
+      set: multiStringOption(),
+      add: multiStringOption(),
+      remove: multiStringOption(),
+      clear: { type: "boolean" }
+    },
+    run: async (input) => {
+      const project2 = requireProject(input, "competitor.aliases", ALIASES_USAGE);
+      const domain = requirePositional(input, 1, {
+        command: "competitor.aliases",
+        usage: ALIASES_USAGE,
+        message: "competitor domain is required"
+      });
+      const set = getStringArray(input.values, "set");
+      const add = getStringArray(input.values, "add");
+      const remove = getStringArray(input.values, "remove");
+      const clear = getBoolean(input.values, "clear");
+      const exclusive = [set !== void 0, clear].filter(Boolean).length;
+      if (exclusive > 1 || exclusive === 1 && (add !== void 0 || remove !== void 0)) {
+        throw usageError(`Error: --set and --clear replace the whole list, so they cannot be combined with each other or with --add/--remove
+Usage: ${ALIASES_USAGE}`, {
+          message: "--set and --clear cannot be combined with each other or with --add/--remove",
+          details: { command: "competitor.aliases", usage: ALIASES_USAGE }
+        });
+      }
+      await competitorAliases(project2, domain, { set, add, remove, clear, format: input.format });
     }
   },
   {
@@ -8413,12 +9483,12 @@ var COMPETITOR_CLI_COMMANDS = [
   },
   {
     path: ["competitor"],
-    usage: "canonry competitor <add|remove|delete|list|landscape> <project> [args]",
+    usage: "canonry competitor <add|aliases|remove|delete|list|landscape> <project> [args]",
     run: async (input) => {
       unknownSubcommand(input.positionals[0], {
         command: "competitor",
-        usage: "canonry competitor <add|remove|delete|list|landscape> <project> [args]",
-        available: ["add", "remove", "delete", "list", "landscape"]
+        usage: "canonry competitor <add|aliases|remove|delete|list|landscape> <project> [args]",
+        available: ["add", "aliases", "remove", "delete", "list", "landscape"]
       });
     }
   }
@@ -11953,10 +13023,10 @@ Brand Gap Analysis`);
     console.log(`
   Opportunity Gaps (competitors cited, you're not):`);
     for (const q of data.gap) {
-      const competitors = q.competitorsCiting.join(", ");
+      const competitors2 = q.competitorsCiting.join(", ");
       const cons = q.consistency.totalRuns > 0 ? ` [cited ${q.consistency.citedRuns}/${q.consistency.totalRuns} runs]` : "";
       console.log(`    \u2022 ${q.query}${cons}`);
-      console.log(`      Competitors: ${competitors}`);
+      console.log(`      Competitors: ${competitors2}`);
     }
   }
   if (data.cited.length > 0) {
@@ -14631,8 +15701,8 @@ function renderQueries(pdf, report) {
     for (const result of queryResult.providerResults) {
       const status = result.error ? "error" : result.mentioned ? result.cited ? "mentioned and cited" : "mentioned" : "not mentioned";
       const accuracy = result.describedAccurately === "not-mentioned" ? "" : `; accuracy: ${result.describedAccurately}`;
-      const competitors = result.recommendedCompetitors.length > 0 ? `; recommended instead: ${result.recommendedCompetitors.join(", ")}` : "";
-      const line = `${result.displayName}: ${status}${accuracy}${competitors}`;
+      const competitors2 = result.recommendedCompetitors.length > 0 ? `; recommended instead: ${result.recommendedCompetitors.join(", ")}` : "";
+      const line = `${result.displayName}: ${status}${accuracy}${competitors2}`;
       pdf.bullet(line);
       if (result.error) {
         pdf.paragraph(`Error: ${result.error}`, { size: 9, color: FAIL, lineHeight: 12 });
@@ -14781,8 +15851,8 @@ function formatSnapshotMarkdown(report) {
       const mentioned = result.mentioned ? "Yes" : "No";
       const cited = result.cited ? "Yes" : "No";
       const accuracy = result.describedAccurately === "not-mentioned" ? "-" : result.describedAccurately;
-      const competitors = result.recommendedCompetitors.length > 0 ? result.recommendedCompetitors.join(", ") : "-";
-      lines.push(`| ${result.displayName} | ${mentioned} | ${cited} | ${accuracy} | ${competitors} |`);
+      const competitors2 = result.recommendedCompetitors.length > 0 ? result.recommendedCompetitors.join(", ") : "-";
+      lines.push(`| ${result.displayName} | ${mentioned} | ${cited} | ${accuracy} | ${competitors2} |`);
     }
     lines.push("");
   }
@@ -15081,7 +16151,7 @@ function renderHuman2(overview) {
     citationMovement,
     mentionMovement,
     movementComparison,
-    competitors,
+    competitors: competitors2,
     providerScores,
     attentionItems,
     runHistory,
@@ -15110,11 +16180,11 @@ function renderHuman2(overview) {
   printScore("Index coverage   ", scores.indexCoverage);
   printScore("Competitor press.", scores.competitorPressure);
   printScore("Run status       ", scores.runStatus);
-  const overallSentiment = overview.sentiment?.overall;
-  if (overview.sentiment?.configured && overallSentiment && overallSentiment.coverage.judged > 0 && overallSentiment.score.favorableRate !== null) {
+  const brandedSentiment = overview.sentiment?.branded;
+  if (overview.sentiment?.configured && brandedSentiment && brandedSentiment.coverage.judged > 0 && brandedSentiment.score.favorableRate !== null) {
     console.log(`
-  Overall sentiment: ${overallSentiment.score.favorableDisplay} favorable \xB7 all query classes`);
-    console.log(`    ${overallSentiment.coverage.counts.favorable} favorable / ${overallSentiment.coverage.judged} judged${overallSentiment.provisional ? " \xB7 provisional" : ""}`);
+  Sentiment: ${brandedSentiment.score.favorableDisplay} favorable \xB7 branded queries`);
+    console.log(`    ${brandedSentiment.coverage.counts.favorable} favorable / ${brandedSentiment.coverage.judged} judged${brandedSentiment.provisional ? " \xB7 provisional" : ""}`);
   }
   console.log(`
   Queries cited:     ${queryCounts.citedQueries}/${queryCounts.totalQueries} (${formatPercent(queryCounts.citedRate)})`);
@@ -15144,9 +16214,9 @@ function renderHuman2(overview) {
     console.log(`
   Transitions since ${transitions.since}: +${transitions.gained} gained, -${transitions.lost} lost, ${transitions.emerging} emerging`);
   }
-  if (competitors.length > 0) {
+  if (competitors2.length > 0) {
     console.log("\n  Competitors:");
-    for (const c of competitors) {
+    for (const c of competitors2) {
       console.log(`    ${c.domain.padEnd(28)} ${c.citationCount}/${c.totalQueries} ${c.pressureLabel}`);
     }
   }
@@ -15196,13 +16266,13 @@ function printMentionShareBreakdown(mentionShare) {
   const ranking = legacyCompatible.ranking ?? [];
   const project2 = ranking.find((row) => row.kind === "project");
   if (!project2) return;
-  const competitors = ranking.filter((row) => row.kind === "competitor");
+  const competitors2 = ranking.filter((row) => row.kind === "competitor");
   console.log(`      you${" ".repeat(28)} ${project2.mentionSnapshots} mentions (${formatPercent(project2.share)} of combined)`);
-  for (const row of competitors.slice(0, 3)) {
+  for (const row of competitors2.slice(0, 3)) {
     console.log(`      ${(row.domain ?? "").padEnd(30)} ${row.mentionSnapshots} mentions (${formatPercent(row.share)} of combined)`);
   }
-  if (competitors.length > 3) {
-    console.log(`      + ${competitors.length - 3} more competitor${competitors.length - 3 === 1 ? "" : "s"} (--format json for full breakdown)`);
+  if (competitors2.length > 3) {
+    console.log(`      + ${competitors2.length - 3} more competitor${competitors2.length - 3 === 1 ? "" : "s"} (--format json for full breakdown)`);
   }
 }
 
@@ -15795,7 +16865,7 @@ var CONTENT_CLI_COMMANDS = [
 import crypto2 from "crypto";
 import path8 from "path";
 import { isDeepStrictEqual } from "util";
-import { eq } from "drizzle-orm";
+import { eq as eq2 } from "drizzle-orm";
 function persistedValue(value) {
   if (Array.isArray(value)) return value.map(persistedValue);
   if (value && typeof value === "object") {
@@ -15855,7 +16925,7 @@ async function bootstrapCommand(opts) {
       projectId: apiKeys.projectId,
       lastUsedAt: apiKeys.lastUsedAt,
       revokedAt: apiKeys.revokedAt
-    }).from(apiKeys).where(eq(apiKeys.name, "default")).all();
+    }).from(apiKeys).where(eq2(apiKeys.name, "default")).all();
     const existingDefault = existingDefaults.find((key) => key.keyHash === existingConfigKeyHash) ?? existingDefaults.at(0);
     if (existingDefault) {
       const rotating = existingDefault.keyHash !== keyHash;
@@ -15868,13 +16938,13 @@ async function bootstrapCommand(opts) {
           projectId: null,
           ...rotating ? { lastUsedAt: null } : {},
           revokedAt: null
-        }).where(eq(apiKeys.id, existingDefault.id)).run();
+        }).where(eq2(apiKeys.id, existingDefault.id)).run();
         changed = true;
       }
       for (const duplicate of existingDefaults) {
         if (duplicate.id === existingDefault.id) continue;
         if (duplicate.revokedAt === null) {
-          tx.update(apiKeys).set({ revokedAt: rotatedAt }).where(eq(apiKeys.id, duplicate.id)).run();
+          tx.update(apiKeys).set({ revokedAt: rotatedAt }).where(eq2(apiKeys.id, duplicate.id)).run();
           changed = true;
         }
       }
@@ -16525,7 +17595,7 @@ function encodeLegacySetupState(state) {
 }
 
 // src/commands/serve.ts
-import { and, asc, eq as eq3, ne } from "drizzle-orm";
+import { and as and2, asc as asc2, eq as eq4, ne } from "drizzle-orm";
 
 // src/server-shutdown.ts
 async function closeWithIdleSweep(app, intervalMs = 250) {
@@ -16539,7 +17609,7 @@ async function closeWithIdleSweep(app, intervalMs = 250) {
 }
 
 // src/startup-path-repairs.ts
-import { eq as eq2, lt } from "drizzle-orm";
+import { eq as eq3, lt } from "drizzle-orm";
 var STARTUP_REPAIR_PAGE_SIZE = 4096;
 function repairNormalizedPathsOnStartup(db) {
   return repairPathsOnce(db, "ga-traffic-paths", backfillNormalizedPaths);
@@ -16548,7 +17618,7 @@ function repairAiReferralPathsOnStartup(db) {
   return repairPathsOnce(db, "ga-ai-referral-paths", backfillAiReferralPaths);
 }
 async function repairPathsOnce(db, name, repair) {
-  const completed = db.select({ version: dataRepairCompletions.version }).from(dataRepairCompletions).where(eq2(dataRepairCompletions.name, name)).get();
+  const completed = db.select({ version: dataRepairCompletions.version }).from(dataRepairCompletions).where(eq3(dataRepairCompletions.name, name)).get();
   if (completed && completed.version >= URL_PATH_NORMALIZATION_VERSION) return null;
   let conflicted = false;
   const result = await repair(db, { pageSize: STARTUP_REPAIR_PAGE_SIZE, onConflict: () => {
@@ -16769,15 +17839,15 @@ function readServeOpenState(db) {
       id: projects.id,
       name: projects.name,
       createdAt: projects.createdAt
-    }).from(projects).orderBy(asc(projects.createdAt), asc(projects.name)).all();
+    }).from(projects).orderBy(asc2(projects.createdAt), asc2(projects.name)).all();
     if (rows.length === 0) return { projectCount: 0, hasSiteAudit: false };
     let scanned;
     try {
       const audits = db.select({
         projectId: runs.projectId,
         status: runs.status
-      }).from(runs).where(and(
-        eq3(runs.kind, RunKinds["site-audit"]),
+      }).from(runs).where(and2(
+        eq4(runs.kind, RunKinds["site-audit"]),
         ne(runs.trigger, RunTriggers.probe)
       )).all();
       scanned = new Set(
@@ -20576,7 +21646,7 @@ Page Health:
 Projects:
   project               Create, update, list, show, delete projects
   query                 Add, replace, remove, list, import, generate queries
-  competitor            Add, remove, list competitors
+  competitor            Add, remove, list competitors and their aliases
 
 Monitoring:
   run                   Trigger visibility sweeps