@canonry/canonry 7.77.1 → 7.78.0

package/dist/{chunk-P3BWUKJL.js → chunk-JEUL5QZP.js}

@@ -1,10 +1,10 @@
 import {
   registeredProviderNames
-} from "./chunk-2WBT6TEJ.js";
+} from "./chunk-FCYGY4FT.js";
 import {
   configExists,
   loadConfigRaw
-} from "./chunk-2BRVGCVU.js";
+} from "./chunk-VLOCDWCS.js";
 
 // src/setup-state.ts
 import fs from "fs";
@@ -28,7 +28,7 @@ async function buildSetupState() {
   }
   if (dbPath && fs.existsSync(dbPath)) {
     try {
-      const { createClient, projects, queries: queriesTable } = await import("./src-SXB3MOP3.js");
+      const { createClient, projects, queries: queriesTable } = await import("./src-IBGSUYEG.js");
       const db = createClient(dbPath);
       project_count = db.select({ id: projects.id }).from(projects).all().length;
       const firstQuery = db.select({ id: queriesTable.id }).from(queriesTable).limit(1).all();
@@ -47,7 +47,7 @@ function queueServeHandoff() {
 async function runPendingServeHandoff(format) {
   if (!pendingServeHandoff) return;
   pendingServeHandoff = false;
-  const { serveCommand } = await import("./serve-UNVCQSRC.js");
+  const { serveCommand } = await import("./serve-WSOG525W.js");
   await serveCommand(format);
 }
 

package/dist/{chunk-PSNTEGNY.js → chunk-KZB6HLFT.js}

@@ -1,6 +1,6 @@
 import {
   cloudflareQueueNameSchema
-} from "./chunk-FCGYYZHL.js";
+} from "./chunk-PM2DB3HE.js";
 
 // src/cloudflare-traffic-config.ts
 function unsupportedDeliveryMode(deliveryMode) {

package/dist/{chunk-UGNNR7EO.js → chunk-L2KMR7CM.js}

@@ -1,6 +1,6 @@
 import {
   createApiClient
-} from "./chunk-X7UC755Q.js";
+} from "./chunk-C5WSQXP5.js";
 import {
   emitJsonl
 } from "./chunk-Z7IUAJOF.js";
@@ -19,7 +19,7 @@ import {
   formatMicros,
   formatRunErrorOneLine,
   resolveProviderInput
-} from "./chunk-FCGYYZHL.js";
+} from "./chunk-PM2DB3HE.js";
 
 // src/commands/run.ts
 function getClient() {

package/dist/{chunk-H4ANN32B.js → chunk-L6F2HOQH.js}

@@ -7,27 +7,27 @@ import {
   reparseStoredResult4,
   reparseStoredResult5,
   resolveStoredApiResponse
-} from "./chunk-C3UFOS7J.js";
+} from "./chunk-UH44UCRM.js";
 import {
   loadConfig
-} from "./chunk-2BRVGCVU.js";
+} from "./chunk-VLOCDWCS.js";
 import {
   isMachineFormat
 } from "./chunk-HGMYEDAQ.js";
 import {
   determineCitationState
-} from "./chunk-XYYWKCJQ.js";
+} from "./chunk-JERATA5R.js";
 import {
   backfillProjectAnswerMentions,
   competitorIdentityColumns,
   createRunCompetitorResolver,
   readMarketCompetitorNames,
   refreshSnapshotMentionIdentity
-} from "./chunk-GDKMVOZI.js";
+} from "./chunk-M3BUP6XD.js";
 import {
   classifyAiUserFetch,
   classifyCrawler
-} from "./chunk-TESDUMVK.js";
+} from "./chunk-O4WBYEGV.js";
 import {
   aiUserFetchEventsHourly,
   auditLog,
@@ -42,7 +42,7 @@ import {
   querySnapshots,
   rawEventSamples,
   runs
-} from "./chunk-D5XPB7MM.js";
+} from "./chunk-6VBLPCCX.js";
 import {
   ProviderNames,
   RetrievalContracts,
@@ -59,7 +59,7 @@ import {
   extractRecommendedCompetitors,
   normalizeUrlPath,
   openRouterRouteModel
-} from "./chunk-FCGYYZHL.js";
+} from "./chunk-PM2DB3HE.js";
 
 // src/commands/backfill.ts
 import { setImmediate as yieldToEventLoop } from "timers/promises";
@@ -437,7 +437,7 @@ No DB writes performed. Re-run without --dry-run to apply.`);
   }
 }
 async function backfillInsightsCommand(project, opts) {
-  const { IntelligenceService } = await import("./intelligence-service-NXZYQJBH.js");
+  const { IntelligenceService } = await import("./intelligence-service-D7DS4UKT.js");
   const config = loadConfig();
   const db = createClient(config.database);
   migrate(db);

package/dist/{chunk-GDKMVOZI.js → chunk-M3BUP6XD.js}

@@ -9,14 +9,14 @@ import {
   normalizeCloudflareWorkerEvent,
   sessionizeJourneyRequests,
   verifyRequestSignature
-} from "./chunk-TESDUMVK.js";
+} from "./chunk-O4WBYEGV.js";
 import {
   currentOutcomeAttribution,
   getRequestContext,
   registerRequestContext,
   requestAuditIdentity,
   sanitizeRequestContext
-} from "./chunk-JPOIDGGF.js";
+} from "./chunk-3MGM3U6V.js";
 import {
   SentimentIdempotencyConflict,
   SentimentRepository,
@@ -157,7 +157,7 @@ import {
   userSessions,
   users,
   writeNegativeReviewMaxStars
-} from "./chunk-D5XPB7MM.js";
+} from "./chunk-6VBLPCCX.js";
 import {
   ADS_ACTIVATE_SCOPE,
   ADS_ACTIVATION_ABSOLUTE_MAX_ENTITIES,
@@ -371,6 +371,8 @@ import {
   SeoAdapterOutcomes,
   SeoAvailability,
   SeoCapabilities,
+  SeoKeywordGapKinds,
+  SeoKeywordGapModes,
   SeoMarketRankingSearchStatuses,
   SeoMarketRankingSorts,
   SeoRunStatuses,
@@ -534,6 +536,8 @@ import {
   compactDateToIso,
   compareMarketRankingsBy,
   compareSemver,
+  compareSeoCompetitorsBy,
+  compareSeoKeywordGapsBy,
   compareText,
   competitorAliasBlockRequestSchema,
   competitorAliasProjectIdentity,
@@ -1058,9 +1062,16 @@ import {
   sentimentSettingsUpdateSchema,
   sentimentSummaryRequestSchema,
   sentimentSummarySchema,
+  seoCompetitorListSchema,
+  seoCompetitorQuerySchema,
+  seoCompetitorSortSchema,
   seoContextSchema,
   seoDomainIntelligenceListSchema,
   seoEvidenceQuerySchema,
+  seoKeywordGapKindSchema,
+  seoKeywordGapListSchema,
+  seoKeywordGapQuerySchema,
+  seoKeywordGapSortSchema,
   seoKeywordMetricsListSchema,
   seoMarketRankingFilterSchema,
   seoMarketRankingListSchema,
@@ -1196,7 +1207,7 @@ import {
   wordpressSchemaDeployResultDtoSchema,
   wordpressSchemaStatusResultDtoSchema,
   wordpressStatusDtoSchema
-} from "./chunk-FCGYYZHL.js";
+} from "./chunk-PM2DB3HE.js";
 
 // ../api-routes/src/user-session.ts
 import crypto2 from "crypto";
@@ -15435,7 +15446,9 @@ function resultRows(tasks) {
     keywordMetrics: kept.flatMap((task) => task.results.keywordMetrics),
     domainIntelligence: kept.flatMap((task) => task.results.domainIntelligence),
     rankedKeywords: kept.flatMap((task) => task.results.rankedKeywords),
-    marketRankings: tasks.flatMap(marketRankingRows)
+    marketRankings: tasks.flatMap(marketRankingRows),
+    competitors: kept.flatMap((task) => task.results.competitors ?? []),
+    keywordGaps: kept.flatMap((task) => task.results.keywordGaps ?? [])
   };
 }
 function marketRankingRows(task) {
@@ -15471,14 +15484,14 @@ function scopedPlanTargets(plan, scope) {
   return { targets: plan.targets.filter((target) => targetKeys.includes(target.stableKey)), market, targetKeys };
 }
 function scopeCapabilities(kind, targets) {
-  if (kind === SeoScopeKinds.project) return [SeoCapabilities["keyword-metrics"], SeoCapabilities["domain-intelligence"], SeoCapabilities["ranked-keywords"], SeoCapabilities["market-rankings"]];
+  if (kind === SeoScopeKinds.project) return Object.values(SeoCapabilities);
   const exactHosts = targets.length > 0 && targets.every((target) => target.urlMatchers.length > 0 && target.urlMatchers.every((matcher) => matcher.kind === "host"));
   const markets = kind === SeoScopeKinds.group || kind === SeoScopeKinds.market ? [SeoCapabilities["market-rankings"]] : [];
   return exactHosts ? [SeoCapabilities["keyword-metrics"], SeoCapabilities["ranked-keywords"], ...markets] : [SeoCapabilities["keyword-metrics"], ...markets];
 }
 function scopeReason(capabilities) {
   const markets = capabilities.includes(SeoCapabilities["market-rankings"]);
-  return capabilities.includes(SeoCapabilities["ranked-keywords"]) ? `Supports explicit keyword metrics${markets ? ", market rankings" : ""} and exact-host ranked keywords. Whole-domain intelligence requires project scope.` : `Supports explicit keyword metrics${markets ? " and market rankings" : " only"}. Path and entity Properties cannot be replaced by whole-domain data.`;
+  return capabilities.includes(SeoCapabilities["ranked-keywords"]) ? `Supports explicit keyword metrics${markets ? ", market rankings" : ""} and exact-host ranked keywords. Use project scope for domain intelligence, competitor discovery and keyword gaps.` : `Supports explicit keyword metrics${markets ? " and market rankings" : " only"}. Use project scope for domain research; path and entity Properties cannot be replaced by whole-domain data.`;
 }
 function cancelSeoRefresh(db, projectId, id) {
   db.transaction((tx) => {
@@ -15503,6 +15516,7 @@ function resolveScope2(db, projectId, input) {
   const { market, targetKeys, targets } = scopedPlanTargets(plan, input.scope);
   const supported = scopeCapabilities(input.scope.kind, targets);
   if (input.capabilities.some((capability) => !supported.includes(capability))) {
+    if (input.capabilities.includes(SeoCapabilities["competitor-discovery"]) || input.capabilities.includes(SeoCapabilities["keyword-gaps"])) throw validationError("Competitor discovery and keyword gaps compare whole domains. Select project scope with an explicit domain Target; Property, group and market scope cannot be broadened automatically.");
     if (supported.includes(SeoCapabilities["ranked-keywords"])) throw validationError("Domain intelligence requires project scope with a whole-domain Target. This Advanced scope supports exact-host ranked keywords and explicit keyword metrics.");
     throw validationError("This Advanced scope contains path or entity Properties and supports explicit keyword metrics only. Select a host-only scope for ranked keywords, or project scope for whole-domain intelligence.");
   }
@@ -15515,13 +15529,24 @@ function resolveScope2(db, projectId, input) {
 }
 function normalizeProfile(input) {
   if (new Set(input.capabilities).size !== input.capabilities.length) throw validationError("Select each SEO capability once.");
-  const targets = input.targets.map((target) => {
+  const normalized = [...input.targets, ...input.competitors ?? []].map((target) => {
     const host = normalizeHostname(target.value);
     if (!host) throw validationError("SEO Targets must be plain hostnames without paths or ports.");
     if (target.kind === SeoTargetKinds.host && target.includeSubdomains) throw validationError("Exact host Targets cannot include subdomains.");
     return { ...target, value: host };
   });
+  const targets = normalized.slice(0, input.targets.length);
+  const comparisonTargets = normalized.slice(input.targets.length);
   if (new Set(targets.map((target) => `${target.kind}:${target.value}:${target.includeSubdomains}`)).size !== targets.length) throw validationError("SEO Targets must be distinct.");
+  const competitive = input.capabilities.includes(SeoCapabilities["competitor-discovery"]) || input.capabilities.includes(SeoCapabilities["keyword-gaps"]);
+  if (competitive && [...targets, ...comparisonTargets].some((target) => target.kind !== SeoTargetKinds.domain || !target.includeSubdomains || registrableDomain(target.value) !== target.value)) throw validationError("Competitor discovery and keyword gaps require root domain Targets with subdomains included. Exact host comparisons are not supported by this source.");
+  if (input.capabilities.includes(SeoCapabilities["keyword-gaps"])) {
+    if (!comparisonTargets.length) throw validationError("Keyword gaps requires at least one explicit competitor domain.");
+    if (new Set(comparisonTargets.map((target) => target.value)).size !== comparisonTargets.length) throw validationError("Competitor domains must be distinct.");
+    if (comparisonTargets.some((competitor) => targets.some((target) => target.value === competitor.value))) throw validationError("A keyword-gap competitor must differ from every Target domain.");
+  } else if (input.competitors !== void 0) {
+    throw validationError("Comparison competitors apply only to keyword gaps.");
+  }
   const keywords = [...new Set(input.keywords)];
   if (input.capabilities.includes(SeoCapabilities["keyword-metrics"]) && !keywords.length) throw validationError("Keyword metrics requires at least one explicit keyword.");
   if (input.capabilities.some((capability) => capability !== SeoCapabilities["keyword-metrics"]) && !targets.length) throw validationError("Domain capabilities require at least one explicit Target.");
@@ -15535,7 +15560,7 @@ function normalizeProfile(input) {
   } else if (input.rankings) {
     throw validationError("Search settings apply only to market rankings.");
   }
-  return { ...input, targets, keywords };
+  return { ...input, targets, keywords, ...input.competitors === void 0 ? {} : { competitors: comparisonTargets } };
 }
 var NO_MARKET_RANKINGS = { searches: [] };
 function advancedMarketQueries(plan, scope) {
@@ -15630,6 +15655,18 @@ function marketRankingPlan(db, projectId, input) {
 }
 function taskRequests(profile, rankings) {
   return profile.capabilities.flatMap((capability) => {
+    if (capability === SeoCapabilities["keyword-gaps"]) {
+      return profile.targets.flatMap((target) => (profile.competitors ?? []).flatMap((competitor) => Object.values(SeoKeywordGapModes).map((mode) => ({
+        capability,
+        target,
+        keywords: [],
+        locationCode: profile.locationCode,
+        languageCode: profile.languageCode,
+        limit: profile.limit,
+        tag: "",
+        comparison: { competitor, mode }
+      }))));
+    }
     if (capability === SeoCapabilities["market-rankings"]) {
       const settings = profile.rankings;
       return rankings.searches.map((search) => ({
@@ -15891,7 +15928,7 @@ async function seoRoutes(app, opts) {
     const row = job(resolveProject(app.db, request.params.name).id, request.params.id);
     const rows = tasks(row.id);
     const results = resultRows(rows);
-    return { ...runDto(row, rows.map((task) => ({ status: task.status, count: 1 }))), tasks: rows.map((task) => ({ id: task.id, capability: task.request.capability, target: task.request.target, status: task.status, error: task.error, remoteTaskId: task.receipts[0]?.remoteTaskId ?? null, ...taskSearch(task), retried: task.retryOf !== null })), results: { keywordMetrics: results.keywordMetrics.slice(0, 20), domainIntelligence: results.domainIntelligence.slice(0, 20), rankedKeywords: results.rankedKeywords.slice(0, 20), marketRankings: [...results.marketRankings].sort(compareMarketRankings).slice(0, 20) }, resultCounts: { keywordMetrics: results.keywordMetrics.length, domainIntelligence: results.domainIntelligence.length, rankedKeywords: results.rankedKeywords.length, marketRankings: results.marketRankings.length }, resultsTruncated: Object.values(results).some((items) => items.length > 20) };
+    return { ...runDto(row, rows.map((task) => ({ status: task.status, count: 1 }))), tasks: rows.map((task) => ({ id: task.id, capability: task.request.capability, target: task.request.target, comparison: task.request.comparison ?? null, status: task.status, error: task.error, remoteTaskId: task.receipts[0]?.remoteTaskId ?? null, ...taskSearch(task), retried: task.retryOf !== null })), results: { keywordMetrics: results.keywordMetrics.slice(0, 20), domainIntelligence: results.domainIntelligence.slice(0, 20), rankedKeywords: results.rankedKeywords.slice(0, 20), marketRankings: [...results.marketRankings].sort(compareMarketRankings).slice(0, 20), competitors: results.competitors.slice(0, 20), keywordGaps: results.keywordGaps.slice(0, 20) }, resultCounts: { keywordMetrics: results.keywordMetrics.length, domainIntelligence: results.domainIntelligence.length, rankedKeywords: results.rankedKeywords.length, marketRankings: results.marketRankings.length, competitors: results.competitors.length, keywordGaps: results.keywordGaps.length }, resultsTruncated: Object.values(results).some((items) => items.length > 20) };
   });
   app.post("/projects/:name/seo/runs/:id/cancel", { config: { paidRead: true, writeScope: SEO_RUN_SCOPE } }, async (request) => {
     requireScope(request, SEO_RUN_SCOPE);
@@ -15910,7 +15947,7 @@ async function seoRoutes(app, opts) {
     const results = resultRows(rows);
     const primary = row?.profile.targets[0];
     const domain = primary ? results.domainIntelligence.find((result) => result.target.kind === primary.kind && result.target.value === primary.value && result.target.includeSubdomains === primary.includeSubdomains) : null;
-    return { status: status(project.id), profiles: profiles(project.id), latestRun: latest ? runSummary(latest) : null, evidenceRunId: row?.id ?? null, evidenceRun: row ? runDto(row, rows.map((task) => ({ status: task.status, count: 1 }))) : null, keywordMetricsCount: results.keywordMetrics.length, domainIntelligenceCount: results.domainIntelligence.length, rankedKeywordCount: results.rankedKeywords.length, marketRankingCount: results.marketRankings.length, summary: domain ? { target: domain.target, organicKeywords: domain.organicKeywords, inTop10: domain.top1 !== null && domain.top2To3 !== null && domain.top4To10 !== null ? domain.top1 + domain.top2To3 + domain.top4To10 : null, estimatedOrganicTraffic: domain.estimatedOrganicTraffic, provenance: domain.provenance } : null };
+    return { status: status(project.id), profiles: profiles(project.id), latestRun: latest ? runSummary(latest) : null, evidenceRunId: row?.id ?? null, evidenceRun: row ? runDto(row, rows.map((task) => ({ status: task.status, count: 1 }))) : null, keywordMetricsCount: results.keywordMetrics.length, domainIntelligenceCount: results.domainIntelligence.length, rankedKeywordCount: results.rankedKeywords.length, marketRankingCount: results.marketRankings.length, competitorCount: results.competitors.length, keywordGapCount: results.keywordGaps.length, summary: domain ? { target: domain.target, organicKeywords: domain.organicKeywords, inTop10: domain.top1 !== null && domain.top2To3 !== null && domain.top4To10 !== null ? domain.top1 + domain.top2To3 + domain.top4To10 : null, estimatedOrganicTraffic: domain.estimatedOrganicTraffic, provenance: domain.provenance } : null };
   });
   for (const [path8, key] of [["keyword-metrics", "keywordMetrics"], ["domain-intelligence", "domainIntelligence"], ["ranked-keywords", "rankedKeywords"]]) app.get(`/projects/:name/seo/${path8}`, async (request) => {
     const query = queryInput(request.query);
@@ -15920,6 +15957,30 @@ async function seoRoutes(app, opts) {
     const offset = query.offset ?? 0;
     return { runId: row?.id ?? null, items: items.slice(offset, offset + limit), total: items.length, limit, offset };
   });
+  app.get("/projects/:name/seo/competitors", async (request) => {
+    const raw = request.query;
+    const parsed = seoCompetitorQuerySchema.safeParse({ ...raw, ...raw.limit === void 0 ? {} : { limit: Number(raw.limit) }, ...raw.offset === void 0 ? {} : { offset: Number(raw.offset) } });
+    if (!parsed.success) throw validationError("Invalid SEO competitor selection.");
+    const query = parsed.data;
+    const row = selected(resolveProject(app.db, request.params.name).id, query, true);
+    const items = row ? resultRows(tasks(row.id)).competitors : [];
+    if (query.sort) items.sort(compareSeoCompetitorsBy(query.sort));
+    const limit = query.limit ?? 50;
+    const offset = query.offset ?? 0;
+    return { runId: row?.id ?? null, items: items.slice(offset, offset + limit), total: items.length, limit, offset };
+  });
+  app.get("/projects/:name/seo/keyword-gaps", async (request) => {
+    const raw = request.query;
+    const parsed = seoKeywordGapQuerySchema.safeParse({ ...raw, ...raw.limit === void 0 ? {} : { limit: Number(raw.limit) }, ...raw.offset === void 0 ? {} : { offset: Number(raw.offset) } });
+    if (!parsed.success) throw validationError("Invalid SEO keyword-gap selection.");
+    const query = parsed.data;
+    const row = selected(resolveProject(app.db, request.params.name).id, query, true);
+    const items = (row ? resultRows(tasks(row.id)).keywordGaps : []).filter((item2) => !query.kind || (query.kind === SeoKeywordGapKinds.shared ? item2.kind !== SeoKeywordGapKinds.missing : item2.kind === query.kind));
+    if (query.sort) items.sort(compareSeoKeywordGapsBy(query.sort));
+    const limit = query.limit ?? 50;
+    const offset = query.offset ?? 0;
+    return { runId: row?.id ?? null, items: items.slice(offset, offset + limit), total: items.length, limit, offset };
+  });
   app.get("/projects/:name/seo/market-rankings", async (request) => {
     const raw = request.query ?? {};
     const parsed = seoMarketRankingQuerySchema.safeParse({ ...raw, ...raw.limit === void 0 ? {} : { limit: Number(raw.limit) }, ...raw.offset === void 0 ? {} : { offset: Number(raw.offset) } });
@@ -34192,6 +34253,8 @@ var SCHEMA_TABLE = {
   SeoRunList: seoRunListSchema,
   SeoOverview: seoOverviewSchema,
   SeoKeywordMetricsList: seoKeywordMetricsListSchema,
+  SeoCompetitorList: seoCompetitorListSchema,
+  SeoKeywordGapList: seoKeywordGapListSchema,
   SeoDomainIntelligenceList: seoDomainIntelligenceListSchema,
   SeoRankedKeywordList: seoRankedKeywordListSchema,
   SeoMarketRankingList: seoMarketRankingListSchema,
@@ -35425,12 +35488,40 @@ var routeCatalog = [
       409: errorResponse("Selection, intent or execution identity changed.")
     }
   },
+  {
+    method: "get",
+    path: "/api/v1/projects/{name}/seo/competitors",
+    summary: "Read stored organic search competitors",
+    tags: ["seo"],
+    description: "Stored whole-domain organic competitor discovery only; never calls a provider. Available for Simple and Advanced project profiles. Each row names its target and source locale. Results are bounded provider database observations, not an exhaustive competitor inventory or a market/Property measurement.",
+    parameters: [nameParameter, ...seoEvidenceParameters, { name: "sort", in: "query", description: "Sort the complete saved result before pagination: domain, shared searches, average position or estimated traffic. Prefix with - for descending. Missing values stay last in both directions. Omitted preserves stored order.", schema: { type: "string", enum: [...seoCompetitorSortSchema.options] } }],
+    responses: {
+      200: jsonResponse("Saved organic competitor evidence.", "SeoCompetitorList"),
+      400: errorResponse("Invalid scope or input."),
+      403: errorResponse("Insufficient authority."),
+      404: errorResponse("Project or selected evidence not found.")
+    }
+  },
+  {
+    method: "get",
+    path: "/api/v1/projects/{name}/seo/keyword-gaps",
+    summary: "Read stored organic keyword comparisons",
+    tags: ["seo"],
+    description: "Stored whole-domain comparisons only; never calls a provider. Missing means the source database has a competitor ranking and no target ranking, not absence from Google. Shared includes outranked searches where both domains rank; outranked selects only those with the competitor ahead. Filters apply before pagination; total counts saved rows, not the full provider keyword universe. A signed rankGap is target position minus competitor position and is null when the target is missing.",
+    parameters: [nameParameter, ...seoEvidenceParameters, { name: "kind", in: "query", description: "shared includes outranked; missing and outranked select that exact kind. Omitted returns all saved comparisons.", schema: { type: "string", enum: [...seoKeywordGapKindSchema.options] } }, { name: "sort", in: "query", description: "Sort after filtering and before pagination: keyword, kind, target rank, competitor rank, rank gap or monthly search volume. Prefix with - for descending. Missing values stay last in both directions. Omitted preserves stored order.", schema: { type: "string", enum: [...seoKeywordGapSortSchema.options] } }],
+    responses: {
+      200: jsonResponse("Saved keyword comparison evidence.", "SeoKeywordGapList"),
+      400: errorResponse("Invalid scope or input."),
+      403: errorResponse("Insufficient authority."),
+      404: errorResponse("Project or selected evidence not found.")
+    }
+  },
   {
     method: "get",
     path: "/api/v1/projects/{name}/seo/market-rankings",
     summary: "Read stored market rankings",
     tags: ["seo"],
-    description: "Stored evidence only; never calls a provider. The project's position for each tracked non-brand query, searched on Google from its market's location. searchStatus says how each search ended: in a completed or partial row a null rank means the site was not in the checked results (depth, which is lower when only part of the results came back); a failed or cancelled search keeps its rows with no rank. outcome says where each row landed (a partial search without the site is partly-checked, never not-ranked) and rivalAhead whether a tracked competitor ranks above the site.",
+    description: "Stored evidence only; never calls a provider. The project's position for each tracked non-brand query, searched on Google from its market's location. searchStatus says how each search ended: in a completed or partial row a null rank means the site was not in the checked results (depth, which is lower when only part of the results came back); a failed or cancelled search keeps its rows with no rank. outcome says where each row landed (a partial search without the site is partly-checked, never not-ranked) and rivalAhead whether a tracked competitor ranks above the site. topCompetitor is the best tracked rival, and rankGap is the target position minus that rival position, null when either rank is unavailable.",
     parameters: [
       nameParameter,
       ...seoEvidenceParameters,
@@ -35474,7 +35565,7 @@ var routeCatalog = [
     path: "/api/v1/projects/{name}/seo/profiles/{id}",
     summary: "Save an SEO profile",
     tags: ["seo"],
-    description: "Requires seo.write and an administrator session. Saving never starts provider work. Scope, locale, targets, capabilities, keywords and row limit are identity parameters.",
+    description: "Requires seo.write and an administrator session. Saving never starts provider work. Scope, locale, targets, comparison competitors, capabilities, keywords and row limit are identity parameters. Keyword gaps requires one to five explicit competitor root domains; shared and missing datasets are reserved separately for each target/competitor pair. Competitor discovery and keyword gaps support project scope with whole-domain targets only, including Advanced projects.",
     parameters: [nameParameter, { name: "id", in: "path", required: true, description: "Exact project-scoped identifier.", schema: stringSchema }],
     requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/SeoProfileInput" } } } },
     responses: {

package/dist/{chunk-4QHTXT4A.js → chunk-MUYTDD35.js}

@@ -2,11 +2,11 @@ import {
   dedupeGscSitemapUrls,
   resolveDiscoveredGscSitemapUrls,
   submitGscSitemapBatches
-} from "./chunk-JSCO223C.js";
+} from "./chunk-ZHFE6J3A.js";
 import {
   measurementDraftOperationSchema,
   runMeasurementDraftAction
-} from "./chunk-5QR7D4RQ.js";
+} from "./chunk-7HB6QLX4.js";
 import {
   CliError
 } from "./chunk-HGMYEDAQ.js";
@@ -138,9 +138,13 @@ import {
   sentimentSettingsUpdateSchema,
   sentimentSummaryIncludeSchema,
   sentimentSummaryReadSchema,
+  seoCompetitorListSchema,
+  seoCompetitorQuerySchema,
   seoContextSchema,
   seoDomainIntelligenceListSchema,
   seoEvidenceQuerySchema,
+  seoKeywordGapListSchema,
+  seoKeywordGapQuerySchema,
   seoKeywordMetricsListSchema,
   seoMarketRankingListSchema,
   seoMarketRankingQuerySchema,
@@ -178,7 +182,7 @@ import {
   trafficSeriesGranularitySchema,
   visibilityCompareSelectionSchema,
   visibilityReportRequestSchema
-} from "./chunk-FCGYYZHL.js";
+} from "./chunk-PM2DB3HE.js";
 
 // src/mcp/tool-registry.ts
 import { z as z2 } from "zod";
@@ -1131,6 +1135,8 @@ var sentimentPreviewInputSchema = sentimentBackfillSelectionSchema.safeExtend({
 var sentimentBackfillInputSchema = sentimentBackfillRequestSchema.extend({ project: projectNameSchema });
 var seoIdInputSchema = projectInputSchema.extend({ id: z2.string().min(1) });
 var seoEvidenceInputSchema = seoEvidenceQuerySchema.extend({ project: projectNameSchema });
+var seoCompetitorInputSchema = seoCompetitorQuerySchema.extend({ project: projectNameSchema });
+var seoKeywordGapInputSchema = seoKeywordGapQuerySchema.extend({ project: projectNameSchema });
 var seoMarketRankingInputSchema = seoMarketRankingQuerySchema.extend({ project: projectNameSchema });
 var seoMarketRankingSummaryInputSchema = seoMarketRankingSummaryQuerySchema.extend({ project: projectNameSchema });
 var rawCanonryMcpTools = [
@@ -1344,10 +1350,40 @@ var rawCanonryMcpTools = [
       return client.getSeoRankedKeywords(project, query);
     }
   }),
+  defineTool({
+    name: "canonry_seo_competitors",
+    title: "SEO organic competitors",
+    description: "Read saved whole-domain organic competitor discovery only. No provider calls or automatic competitor pins. Preserve target, location, language, source date and runId while paging. Shared-search counts and traffic are provider database estimates; saved rows are bounded by the profile limit. Optional sort orders all saved rows before paging; a leading minus descends, missing values stay last, and omission preserves source order. Preserve sort while paging.",
+    access: "read",
+    tier: "seo",
+    inputSchema: seoCompetitorInputSchema,
+    outputSchema: seoCompetitorListSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/projects/{name}/seo/competitors"],
+    handler: (client, input) => {
+      const { project, ...query } = input;
+      return client.getSeoCompetitors(project, query);
+    }
+  }),
+  defineTool({
+    name: "canonry_seo_keyword_gaps",
+    title: "SEO keyword gaps",
+    description: "Read saved whole-domain organic search comparisons only. No provider calls. kind=shared includes all searches where both domains rank, including outranked; missing means the source database has a rival rank and no target rank; outranked means the rival ranks higher. rankGap is target rank minus rival rank and null without both. Preserve exact targets, locale, source date and runId while paging. Results are a bounded source sample, not all possible opportunities. Optional sort orders all filtered rows before paging; a leading minus descends, missing values stay last, and omission preserves source order. Preserve sort while paging.",
+    access: "read",
+    tier: "seo",
+    inputSchema: seoKeywordGapInputSchema,
+    outputSchema: seoKeywordGapListSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/projects/{name}/seo/keyword-gaps"],
+    handler: (client, input) => {
+      const { project, ...query } = input;
+      return client.getSeoKeywordGaps(project, query);
+    }
+  }),
   defineTool({
     name: "canonry_seo_market_rankings",
     title: "SEO market rankings",
-    description: "Read stored SEO data only. No provider calls. The site's Google position for each tracked non-brand query in each market, searched from that market's location; these are the same tracked queries AI visibility measures, and searchText is the exact text searched. searchStatus says how each search ended: a null rank in a completed or partial row means not in the checked results (depth, lower when only part of the results came back); a failed or cancelled row has no rank because the search returned nothing. outcome says where each row landed (page-1, ranks-11-20, ranks-21-plus, not-ranked, partly-checked for a partial search without the site, failed, cancelled) and rivalAhead whether a tracked competitor ranks above the site. Filter with marketKey, regionKey, outcome (needs-work = off page 1 with a result) and q; sort=rank puts the closest to page 1 first. Keep runId fixed while paging.",
+    description: "Read stored SEO data only. No provider calls. The site's Google position for each tracked non-brand query in each market, searched from that market's location; these are the same tracked queries AI visibility measures, and searchText is the exact text searched. searchStatus says how each search ended: a null rank in a completed or partial row means not in the checked results (depth, lower when only part of the results came back); a failed or cancelled row has no rank because the search returned nothing. outcome says where each row landed (page-1, ranks-11-20, ranks-21-plus, not-ranked, partly-checked for a partial search without the site, failed, cancelled) and rivalAhead whether a tracked competitor ranks above the site. topCompetitor is the best tracked rival; rankGap is target rank minus rival rank and null without both. Filter with marketKey, regionKey, outcome (needs-work = off page 1 with a result) and q; sort=rank puts the closest to page 1 first. Keep runId fixed while paging.",
     access: "read",
     tier: "seo",
     inputSchema: seoMarketRankingInputSchema,

package/dist/{chunk-TESDUMVK.js → chunk-O4WBYEGV.js}

@@ -8,7 +8,7 @@ import {
   classifyJourneyEntry,
   hostMatchesDomain,
   hostOf
-} from "./chunk-FCGYYZHL.js";
+} from "./chunk-PM2DB3HE.js";
 
 // ../integration-traffic/src/ip-ranges/amazonbot.json
 var amazonbot_default = {