@ainyc/canonry 2.16.0 → 2.16.3

package/dist/{chunk-HNVRN5QL.js → chunk-7DVIJC6L.js}

@@ -1913,6 +1913,69 @@ function normalizeUrlPath(input) {
   return `${pathPart}?${encodeQuery(pairs)}`;
 }
 
+// ../contracts/src/citations.ts
+import { z as z18 } from "zod";
+var citationCoverageProviderSchema = z18.object({
+  provider: z18.string(),
+  citationState: citationStateSchema,
+  cited: z18.boolean(),
+  runId: z18.string(),
+  runCreatedAt: z18.string()
+});
+var citationCoverageRowSchema = z18.object({
+  keywordId: z18.string(),
+  keyword: z18.string(),
+  providers: z18.array(citationCoverageProviderSchema),
+  citedCount: z18.number().int().nonnegative(),
+  totalProviders: z18.number().int().nonnegative()
+});
+var competitorGapRowSchema = z18.object({
+  keywordId: z18.string(),
+  keyword: z18.string(),
+  provider: z18.string(),
+  citingCompetitors: z18.array(z18.string()),
+  runId: z18.string(),
+  runCreatedAt: z18.string()
+});
+var citationVisibilitySummarySchema = z18.object({
+  providersConfigured: z18.number().int().nonnegative(),
+  providersCiting: z18.number().int().nonnegative(),
+  totalKeywords: z18.number().int().nonnegative(),
+  keywordsCited: z18.number().int().nonnegative(),
+  keywordsFullyCovered: z18.number().int().nonnegative(),
+  keywordsUncovered: z18.number().int().nonnegative(),
+  latestRunId: z18.string().nullable(),
+  latestRunAt: z18.string().nullable()
+});
+var citationVisibilityResponseSchema = z18.object({
+  summary: citationVisibilitySummarySchema,
+  byKeyword: z18.array(citationCoverageRowSchema),
+  competitorGaps: z18.array(competitorGapRowSchema),
+  status: z18.enum(["ready", "no-data"]),
+  reason: z18.enum(["no-runs-yet", "no-keywords"]).optional()
+});
+function emptyCitationVisibility(reason) {
+  return {
+    summary: {
+      providersConfigured: 0,
+      providersCiting: 0,
+      totalKeywords: 0,
+      keywordsCited: 0,
+      keywordsFullyCovered: 0,
+      keywordsUncovered: 0,
+      latestRunId: null,
+      latestRunAt: null
+    },
+    byKeyword: [],
+    competitorGaps: [],
+    status: "no-data",
+    reason
+  };
+}
+function citationStateToCited(state) {
+  return state === "cited";
+}
+
 // src/client.ts
 function createApiClient() {
   const config = loadConfig();
@@ -2524,6 +2587,12 @@ var ApiClient = class {
     const qs = limit ? `?limit=${limit}` : "";
     return this.request("GET", `/projects/${encodeURIComponent(project)}/health/history${qs}`);
   }
+  async getCitationVisibility(project) {
+    return this.request(
+      "GET",
+      `/projects/${encodeURIComponent(project)}/citations/visibility`
+    );
+  }
   // --- Backlinks ---------------------------------------------------------
   async backlinksStatus() {
     return this.request("GET", "/backlinks/status");
@@ -2570,21 +2639,21 @@ var ApiClient = class {
 };
 
 // src/mcp/tool-registry.ts
-import { z as z19 } from "zod";
+import { z as z20 } from "zod";
 
 // src/mcp/schema.ts
-import { z as z18 } from "zod";
-var projectNameSchema = z18.string().min(1).describe("Canonry project name.");
-var runIdSchema = z18.string().min(1).describe("Canonry run ID.");
-var insightIdSchema = z18.string().min(1).describe("Canonry insight ID.");
-var analyticsWindowSchema = z18.enum(["7d", "30d", "90d", "all"]).describe("Analytics time window.");
-var emptyInputSchema = z18.object({});
-var projectInputSchema = z18.object({
+import { z as z19 } from "zod";
+var projectNameSchema = z19.string().min(1).describe("Canonry project name.");
+var runIdSchema = z19.string().min(1).describe("Canonry run ID.");
+var insightIdSchema = z19.string().min(1).describe("Canonry insight ID.");
+var analyticsWindowSchema = z19.enum(["7d", "30d", "90d", "all"]).describe("Analytics time window.");
+var emptyInputSchema = z19.object({});
+var projectInputSchema = z19.object({
   project: projectNameSchema
 });
 function toJsonSchema(schema, name) {
   return {
-    ...z18.toJSONSchema(schema, { target: "draft-7" }),
+    ...z19.toJSONSchema(schema, { target: "draft-7" }),
     title: name
   };
 }
@@ -2626,119 +2695,119 @@ function defineTool(tool) {
     inputJsonSchema: toJsonSchema(tool.inputSchema, tool.name)
   };
 }
-var runTriggerInputSchema = z19.object({
+var runTriggerInputSchema = z20.object({
   project: projectNameSchema,
   request: runTriggerRequestSchema.optional()
 });
-var runsListInputSchema = z19.object({
+var runsListInputSchema = z20.object({
   project: projectNameSchema,
-  limit: z19.number().int().positive().max(500).optional()
+  limit: z20.number().int().positive().max(500).optional()
 });
-var runGetInputSchema = z19.object({
+var runGetInputSchema = z20.object({
   runId: runIdSchema
 });
-var timelineInputSchema = z19.object({
+var timelineInputSchema = z20.object({
   project: projectNameSchema,
-  location: z19.string().optional().describe("Location label. Use an empty string for locationless results.")
+  location: z20.string().optional().describe("Location label. Use an empty string for locationless results.")
 });
-var snapshotsListInputSchema = z19.object({
+var snapshotsListInputSchema = z20.object({
   project: projectNameSchema,
-  limit: z19.number().int().positive().max(500).optional(),
-  offset: z19.number().int().nonnegative().optional(),
-  location: z19.string().optional().describe("Location label. Use an empty string for locationless results.")
+  limit: z20.number().int().positive().max(500).optional(),
+  offset: z20.number().int().nonnegative().optional(),
+  location: z20.string().optional().describe("Location label. Use an empty string for locationless results.")
 });
-var snapshotsDiffInputSchema = z19.object({
+var snapshotsDiffInputSchema = z20.object({
   project: projectNameSchema,
   run1: runIdSchema,
   run2: runIdSchema
 });
-var insightsListInputSchema = z19.object({
+var insightsListInputSchema = z20.object({
   project: projectNameSchema,
-  dismissed: z19.boolean().optional(),
+  dismissed: z20.boolean().optional(),
   runId: runIdSchema.optional()
 });
-var insightInputSchema = z19.object({
+var insightInputSchema = z20.object({
   project: projectNameSchema,
   insightId: insightIdSchema
 });
-var healthHistoryInputSchema = z19.object({
+var healthHistoryInputSchema = z20.object({
   project: projectNameSchema,
-  limit: z19.number().int().positive().max(100).optional()
+  limit: z20.number().int().positive().max(100).optional()
 });
-var gscPerformanceInputSchema = z19.object({
+var gscPerformanceInputSchema = z20.object({
   project: projectNameSchema,
-  startDate: z19.string().optional(),
-  endDate: z19.string().optional(),
-  query: z19.string().optional(),
-  page: z19.string().optional(),
-  limit: z19.number().int().positive().max(500).optional(),
+  startDate: z20.string().optional(),
+  endDate: z20.string().optional(),
+  query: z20.string().optional(),
+  page: z20.string().optional(),
+  limit: z20.number().int().positive().max(500).optional(),
   window: analyticsWindowSchema.optional()
 });
-var gscInspectionsInputSchema = z19.object({
+var gscInspectionsInputSchema = z20.object({
   project: projectNameSchema,
-  url: z19.string().optional(),
-  limit: z19.number().int().positive().max(500).optional()
+  url: z20.string().optional(),
+  limit: z20.number().int().positive().max(500).optional()
 });
-var gscCoverageHistoryInputSchema = z19.object({
+var gscCoverageHistoryInputSchema = z20.object({
   project: projectNameSchema,
-  limit: z19.number().int().positive().max(500).optional()
+  limit: z20.number().int().positive().max(500).optional()
 });
-var gaWindowInputSchema = z19.object({
+var gaWindowInputSchema = z20.object({
   project: projectNameSchema,
   window: analyticsWindowSchema.optional()
 });
 var gaTrafficInputSchema = gaWindowInputSchema.extend({
-  limit: z19.number().int().positive().max(500).optional()
+  limit: z20.number().int().positive().max(500).optional()
 });
-var keywordsInputSchema = z19.object({
+var keywordsInputSchema = z20.object({
   project: projectNameSchema,
   request: keywordBatchRequestSchema
 });
-var keywordGenerateInputSchema = z19.object({
+var keywordGenerateInputSchema = z20.object({
   project: projectNameSchema,
   request: keywordGenerateRequestSchema
 });
-var competitorsInputSchema = z19.object({
+var competitorsInputSchema = z20.object({
   project: projectNameSchema,
   request: competitorBatchRequestSchema
 });
-var projectUpsertInputSchema = z19.object({
+var projectUpsertInputSchema = z20.object({
   project: projectNameSchema,
   request: projectUpsertRequestSchema
 });
-var applyConfigInputSchema = z19.object({
+var applyConfigInputSchema = z20.object({
   config: projectConfigSchema
 });
-var scheduleSetInputSchema = z19.object({
+var scheduleSetInputSchema = z20.object({
   project: projectNameSchema,
   schedule: scheduleUpsertRequestSchema
 });
-var agentWebhookAttachInputSchema = z19.object({
+var agentWebhookAttachInputSchema = z20.object({
   project: projectNameSchema,
-  url: z19.string().url()
+  url: z20.string().url()
 });
-var doctorInputSchema = z19.object({
+var doctorInputSchema = z20.object({
   project: projectNameSchema.optional().describe("Project name to scope project-level checks. Omit to run global checks (provider keys, config, etc.)."),
-  checks: z19.array(z19.string().min(1)).optional().describe('Optional check IDs or wildcard prefixes (e.g. "google.auth.*", "config.providers"). Empty/omitted runs all matching checks for the chosen scope.')
+  checks: z20.array(z20.string().min(1)).optional().describe('Optional check IDs or wildcard prefixes (e.g. "google.auth.*", "config.providers"). Empty/omitted runs all matching checks for the chosen scope.')
 });
-var contentTargetsInputSchema = z19.object({
+var contentTargetsInputSchema = z20.object({
   project: projectNameSchema,
-  limit: z19.number().int().positive().max(500).optional().describe("Max rows. Defaults to all. Use a small number (3-10) when summarizing for the user."),
-  includeInProgress: z19.boolean().optional().describe("Include rows that already have an in-flight tracked action. Default false.")
+  limit: z20.number().int().positive().max(500).optional().describe("Max rows. Defaults to all. Use a small number (3-10) when summarizing for the user."),
+  includeInProgress: z20.boolean().optional().describe("Include rows that already have an in-flight tracked action. Default false.")
 });
-var backlinksDomainsInputSchema = z19.object({
+var backlinksDomainsInputSchema = z20.object({
   project: projectNameSchema,
-  limit: z19.number().int().positive().max(200).optional().describe("Max linking-domain rows. Default 50, max 200."),
-  release: z19.string().optional().describe("Common Crawl release id (e.g., cc-main-2026-jan-feb-mar). Omit for the most recent release with data.")
+  limit: z20.number().int().positive().max(200).optional().describe("Max linking-domain rows. Default 50, max 200."),
+  release: z20.string().optional().describe("Common Crawl release id (e.g., cc-main-2026-jan-feb-mar). Omit for the most recent release with data.")
 });
-var memoryUpsertInputSchema = z19.object({
+var memoryUpsertInputSchema = z20.object({
   project: projectNameSchema,
-  key: z19.string().min(1).max(AGENT_MEMORY_KEY_MAX_LENGTH).describe(`Stable identifier for the note (max ${AGENT_MEMORY_KEY_MAX_LENGTH} chars). Writing the same key overwrites the prior value.`),
-  value: z19.string().min(1).describe(`Plain-text note body (max ${AGENT_MEMORY_VALUE_MAX_BYTES} bytes). Use for durable operator preferences, migration context, or non-obvious reasoning that should survive future sessions.`)
+  key: z20.string().min(1).max(AGENT_MEMORY_KEY_MAX_LENGTH).describe(`Stable identifier for the note (max ${AGENT_MEMORY_KEY_MAX_LENGTH} chars). Writing the same key overwrites the prior value.`),
+  value: z20.string().min(1).describe(`Plain-text note body (max ${AGENT_MEMORY_VALUE_MAX_BYTES} bytes). Use for durable operator preferences, migration context, or non-obvious reasoning that should survive future sessions.`)
 });
-var memoryForgetInputSchema = z19.object({
+var memoryForgetInputSchema = z20.object({
   project: projectNameSchema,
-  key: z19.string().min(1).max(AGENT_MEMORY_KEY_MAX_LENGTH).describe("Exact key of the note to remove. No-op (status=missing) when no note exists for that key.")
+  key: z20.string().min(1).max(AGENT_MEMORY_KEY_MAX_LENGTH).describe("Exact key of the note to remove. No-op (status=missing) when no note exists for that key.")
 });
 var AGENT_WEBHOOK_EVENTS = [
   notificationEventSchema.enum["run.completed"],
@@ -2786,10 +2855,10 @@ var canonryMcpTools = [
     description: "Search query snapshots and intelligence insights for the given text. Looks at snapshot answer text, cited domains, raw provider responses, and insight title/keyword/recommendation/cause. Returns ranked hits with snippets \u2014 use it instead of paginating snapshots when you need to find a competitor mention or term.",
     access: "read",
     tier: "core",
-    inputSchema: z19.object({
+    inputSchema: z20.object({
       project: projectNameSchema,
-      q: z19.string().min(2).describe("Search term, at least 2 characters."),
-      limit: z19.number().int().positive().max(50).optional().describe("Max combined hits (1-50, default 25).")
+      q: z20.string().min(2).describe("Search term, at least 2 characters."),
+      limit: z20.number().int().positive().max(50).optional().describe("Max combined hits (1-50, default 25).")
     }),
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/search"],
@@ -2942,6 +3011,17 @@ var canonryMcpTools = [
     openApiOperations: ["GET /api/v1/projects/{name}/health/history"],
     handler: (client, input) => client.getHealthHistory(input.project, input.limit)
   }),
+  defineTool({
+    name: "canonry_citations_visibility",
+    title: "Get citation visibility",
+    description: 'Single-call AI citation surface for a Canonry project. Returns the project headline (cited by N of M engines), per-keyword engine coverage rows from the latest snapshot per (keyword \xD7 provider), and a competitor-gap list (keywords where a configured competitor is cited but the project is not). Carries `status: "no-data"` with `reason: "no-keywords"` or `"no-runs-yet"` when inputs are missing.',
+    access: "read",
+    tier: "monitoring",
+    inputSchema: projectInputSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/projects/{name}/citations/visibility"],
+    handler: (client, input) => client.getCitationVisibility(input.project)
+  }),
   defineTool({
     name: "canonry_content_targets",
     title: "Get content targets",
@@ -3538,6 +3618,8 @@ export {
   CheckCategories,
   summarizeCheckResults,
   normalizeUrlPath,
+  emptyCitationVisibility,
+  citationStateToCited,
   createApiClient,
   ApiClient,
   canonryMcpTools

package/dist/cli.js

@@ -17,7 +17,7 @@ import {
   setGoogleAuthConfig,
   showFirstRunNotice,
   trackEvent
-} from "./chunk-CKABU6PE.js";
+} from "./chunk-75EV36V6.js";
 import {
   CcReleaseSyncStatuses,
   CheckScopes,
@@ -45,7 +45,7 @@ import {
   saveConfig,
   saveConfigPatch,
   usageError
-} from "./chunk-HNVRN5QL.js";
+} from "./chunk-7DVIJC6L.js";
 import {
   apiKeys,
   competitors,
@@ -6326,6 +6326,84 @@ async function searchProject(project, opts) {
   }
 }
 
+// src/commands/citations.ts
+async function showCitationVisibility(project, opts) {
+  const client = createApiClient();
+  const data = await client.getCitationVisibility(project);
+  if (opts.format === "json") {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  if (data.status === "no-data") {
+    if (data.reason === "no-keywords") {
+      console.log("No keywords configured. Add some with `canonry keyword add`.");
+    } else {
+      console.log("No citation data yet \u2014 run a sweep first (canonry run <project>).");
+    }
+    return;
+  }
+  printSummary(data);
+  console.log("");
+  printCoverage(data);
+  if (data.competitorGaps.length > 0) {
+    console.log("");
+    printGaps2(data);
+  }
+}
+function printSummary(data) {
+  const { providersCiting, providersConfigured, totalKeywords, keywordsCited, keywordsFullyCovered, keywordsUncovered } = data.summary;
+  console.log(`Citation visibility \u2014 cited by ${providersCiting}/${providersConfigured} engines`);
+  if (data.summary.latestRunAt) {
+    console.log(`Latest run:        ${data.summary.latestRunAt}`);
+  }
+  console.log(`Keywords:          ${totalKeywords}`);
+  console.log(`  cited (any):     ${keywordsCited}`);
+  console.log(`  fully covered:   ${keywordsFullyCovered}`);
+  console.log(`  uncovered:       ${keywordsUncovered}`);
+}
+function printCoverage(data) {
+  if (data.byKeyword.length === 0) {
+    console.log("No keyword coverage rows.");
+    return;
+  }
+  const providerSet = /* @__PURE__ */ new Set();
+  for (const row of data.byKeyword) {
+    for (const p of row.providers) providerSet.add(p.provider);
+  }
+  const providerColumns = Array.from(providerSet).sort();
+  if (providerColumns.length === 0) {
+    console.log("Per-keyword coverage:");
+    for (const row of data.byKeyword) {
+      console.log(`  ${row.keyword.padEnd(35)} no snapshots`);
+    }
+    return;
+  }
+  const keywordWidth = Math.max(7, ...data.byKeyword.map((r) => r.keyword.length));
+  const header = ["Keyword".padEnd(keywordWidth), ...providerColumns.map((p) => p.padEnd(10)), "Coverage"].join("  ");
+  console.log("Per-keyword coverage:");
+  console.log(header);
+  console.log("\u2500".repeat(header.length));
+  for (const row of data.byKeyword) {
+    const cells = providerColumns.map((p) => {
+      const provider = row.providers.find((x) => x.provider === p);
+      if (!provider) return "\u2013".padEnd(10);
+      return (provider.cited ? "\u2713" : "\u2717").padEnd(10);
+    });
+    const coverage = `${row.citedCount}/${row.totalProviders}`;
+    console.log([row.keyword.padEnd(keywordWidth), ...cells, coverage].join("  "));
+  }
+}
+function printGaps2(data) {
+  console.log("Competitor gaps (not cited but a competitor is):");
+  const keywordWidth = Math.max(7, ...data.competitorGaps.map((g) => g.keyword.length));
+  const providerWidth = Math.max(8, ...data.competitorGaps.map((g) => g.provider.length));
+  for (const gap of data.competitorGaps) {
+    console.log(
+      `  ${gap.keyword.padEnd(keywordWidth)}  ${gap.provider.padEnd(providerWidth)}  ${gap.citingCompetitors.join(", ")}`
+    );
+  }
+}
+
 // src/cli-commands/intelligence.ts
 var INTELLIGENCE_CLI_COMMANDS = [
   {
@@ -6400,6 +6478,16 @@ var INTELLIGENCE_CLI_COMMANDS = [
       });
       await searchProject(project, { query, limit, format: input.format });
     }
+  },
+  {
+    path: ["citations", "visibility"],
+    usage: "canonry citations visibility <project> [--format json]",
+    options: {},
+    run: async (input) => {
+      const usage = "canonry citations visibility <project> [--format json]";
+      const project = requireProject(input, "citations visibility", usage);
+      await showCitationVisibility(project, { format: input.format });
+    }
   }
 ];
 

package/dist/index.js

@@ -1,9 +1,9 @@
 import {
   createServer
-} from "./chunk-CKABU6PE.js";
+} from "./chunk-75EV36V6.js";
 import {
   loadConfig
-} from "./chunk-HNVRN5QL.js";
+} from "./chunk-7DVIJC6L.js";
 import "./chunk-NEDRCOOL.js";
 import "./chunk-MLKGABMK.js";
 export {

package/dist/mcp.js

@@ -2,7 +2,7 @@ import {
   CliError,
   canonryMcpTools,
   createApiClient
-} from "./chunk-HNVRN5QL.js";
+} from "./chunk-7DVIJC6L.js";
 import "./chunk-MLKGABMK.js";
 
 // src/mcp/cli.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainyc/canonry",
-  "version": "2.16.0",
+  "version": "2.16.3",
   "type": "module",
   "description": "Agent-first open-source AEO operating platform - track how answer engines cite your domain",
   "license": "FSL-1.1-ALv2",
@@ -60,20 +60,20 @@
     "tsup": "^8.5.1",
     "tsx": "^4.19.0",
     "@ainyc/canonry-api-routes": "0.0.0",
-    "@ainyc/canonry-config": "0.0.0",
-    "@ainyc/canonry-intelligence": "0.0.0",
     "@ainyc/canonry-db": "0.0.0",
-    "@ainyc/canonry-integration-commoncrawl": "0.0.0",
     "@ainyc/canonry-contracts": "0.0.0",
+    "@ainyc/canonry-config": "0.0.0",
+    "@ainyc/canonry-integration-bing": "0.0.0",
+    "@ainyc/canonry-integration-commoncrawl": "0.0.0",
+    "@ainyc/canonry-intelligence": "0.0.0",
     "@ainyc/canonry-integration-google": "0.0.0",
-    "@ainyc/canonry-integration-wordpress": "0.0.0",
     "@ainyc/canonry-provider-cdp": "0.0.0",
     "@ainyc/canonry-provider-claude": "0.0.0",
+    "@ainyc/canonry-provider-gemini": "0.0.0",
     "@ainyc/canonry-provider-local": "0.0.0",
+    "@ainyc/canonry-integration-wordpress": "0.0.0",
     "@ainyc/canonry-provider-openai": "0.0.0",
-    "@ainyc/canonry-provider-perplexity": "0.0.0",
-    "@ainyc/canonry-integration-bing": "0.0.0",
-    "@ainyc/canonry-provider-gemini": "0.0.0"
+    "@ainyc/canonry-provider-perplexity": "0.0.0"
   },
   "scripts": {
     "build": "tsx scripts/copy-agent-assets.ts && tsup && tsx build-web.ts",