@canonry/canonry 5.22.0 → 5.28.1

package/dist/{chunk-DDL2XSNM.js → chunk-MPICT6V7.js}

@@ -4,6 +4,7 @@ import {
   DISCOVERY_MAX_PROBES_CAP,
   DISCOVERY_PROBE_CONCURRENCY_CAP,
   GOOGLE_MARKETING_STORED_SNAPSHOT_PAGE_MAX,
+  LATEST_RUN_ID,
   RESEARCH_RUN_SCOPE,
   adsActivateTreeRequestSchema,
   adsAdCreateRequestSchema,
@@ -71,13 +72,14 @@ import {
   measurementPropertyCompetitorsQuerySchema,
   measurementPropertyEvidenceQuerySchema,
   measurementPropertyQuestionsQuerySchema,
+  measurementQueryClassFilterSchema,
   measurementQuerySetUpsertRequestSchema,
   measurementQueryTemplateApplyRequestSchema,
   measurementQueryTemplateUpsertRequestSchema,
   measurementQuestionResultQuerySchema,
   notificationCreateRequestSchema,
   notificationEventSchema,
-  operationalLogListDtoSchema,
+  operationalLogListReadSchema,
   organicEvidencePeriodSchema,
   projectConfigSchema,
   projectUpsertRequestSchema,
@@ -87,6 +89,7 @@ import {
   queryGenerateRequestSchema,
   queryTrackingCommitRequestSchema,
   queryTrackingPreviewRequestSchema,
+  referralAssessmentQuerySchema,
   reportMonthSchema,
   reportPeriodSchema,
   researchBatchCreateSchema,
@@ -107,7 +110,7 @@ import {
   trafficSeriesGranularitySchema,
   visibilityCompareSelectionSchema,
   visibilityReportRequestSchema
-} from "./chunk-S5OSY3PI.js";
+} from "./chunk-KVQHG3WB.js";
 
 // src/cli-error.ts
 function isMachineFormat(format) {
@@ -392,20 +395,34 @@ var measurementOverviewInputSchema = z3.object({
     context.addIssue({ code: "custom", path: ["targetKey"], message: `${input.scope} scope does not accept targetKey.` });
   }
 });
+var AGENT_DEFAULT_QUERY_CLASS = "non-brand";
+var propertyQueryClassInputSchema = measurementQueryClassFilterSchema.optional().describe("Omit for non-brand. branded reads brand recall; all pools both classes, so name the class you report.");
+function agentQueryClass(queryClass) {
+  return queryClass ?? AGENT_DEFAULT_QUERY_CLASS;
+}
 var measurementPropertyEvidenceInputSchema = measurementPropertyEvidenceQuerySchema.extend({
   project: projectNameSchema,
   targetKey: measurementPropertyEvidenceQuerySchema.shape.targetKey.describe("Property stable key. Required \u2014 this read is scoped to exactly one Property."),
+  queryClass: propertyQueryClassInputSchema,
   shape: measurementPropertyEvidenceQuerySchema.shape.shape.describe(
     "What one row is. Omit for sources (one row per cited URL). answers gives one row per measured answer with its cited URLs nested, including the answers that cited nothing."
   )
 }).strict();
+var PORTFOLIO_SUMMARY_AGENT_ROWS = 4;
+var PORTFOLIO_SUMMARY_AGENT_LIMIT_MAX = 10;
+function portfolioSummaryForAgents(summary, limitNote) {
+  const rows = summary.weakestProperties;
+  return {
+    ...limitNote === void 0 ? {} : { limitNote },
+    ...summary,
+    ...Array.isArray(rows) ? { weakestProperties: summary.weakestProperties.map(({ recommendedInstead: _names, recommendedInsteadTotal: _total, recommendedInsteadTruncated: _cut, ...row }) => row) } : {}
+  };
+}
 var measurementPortfolioSummaryInputSchema = measurementPortfolioSummaryQuerySchema.extend({
   project: projectNameSchema,
-  groupKey: measurementPortfolioSummaryQuerySchema.shape.groupKey.describe("A market stable key (a row's metro.groupKey). Scopes rows to that market and lists its direct submarkets."),
-  // Capped below the route's 50: past about 10 rows the per-row evidence
-  // (names given instead, cited domains) no longer fits the tool-result cap.
-  limit: z3.number().int().positive().max(10).optional().describe("Rows per list, at most 10. Default 4 keeps the whole result under the tool-result cap; prefer groupKey over a larger limit."),
-  includeNestedMarkets: measurementPortfolioSummaryQuerySchema.shape.includeNestedMarkets.describe("Every market at every level, uncapped. Off by default; large portfolios exceed the cap with it on.")
+  groupKey: measurementPortfolioSummaryQuerySchema.shape.groupKey.describe("A market stable key (a row's metro.groupKey or a markets row's groupKey). Scopes rows to that market and lists its direct submarkets."),
+  limit: z3.number().int().positive().max(PORTFOLIO_SUMMARY_AGENT_LIMIT_MAX).optional().describe(`Rows per Property list. Default ${PORTFOLIO_SUMMARY_AGENT_ROWS}, which is also the most returned (a larger value is lowered and limitNote says so). For other rows pass groupKey (one metro's weakest), or page canonry_measurement_overview.`),
+  includeNestedMarkets: measurementPortfolioSummaryQuerySchema.shape.includeNestedMarkets.describe("Every market at every level, uncapped. Off by default and rarely needed: markets already lists every metro, and groupKey lists one metro's submarkets. Large portfolios exceed the tool-result cap with it on.")
 }).strict();
 var measurementPropertyQuestionsInputSchema = measurementPropertyQuestionsQuerySchema.extend({
   project: projectNameSchema
@@ -414,10 +431,14 @@ var measurementQuestionResultInputSchema = measurementQuestionResultQuerySchema.
   project: projectNameSchema
 }).strict();
 var measurementPropertyCompetitorsInputSchema = measurementPropertyCompetitorsQuerySchema.extend({
-  project: projectNameSchema
+  project: projectNameSchema,
+  queryClass: propertyQueryClassInputSchema
 }).strict();
-var measurementChangesInputSchema = measurementChangesQuerySchema.extend({
-  project: projectNameSchema
+var MEASUREMENT_CHANGES_AGENT_ROWS = 20;
+var measurementChangesInputSchema = measurementChangesQuerySchema.safeExtend({
+  project: projectNameSchema,
+  queryClass: measurementQueryClassFilterSchema.default(AGENT_DEFAULT_QUERY_CLASS).describe("Defaults to non-brand. Call once per class; all pools both classes in rows and distribution."),
+  limit: z3.number().int().positive().max(MEASUREMENT_CHANGES_AGENT_ROWS).optional().describe(`Changed rows, largest move first. Default 10, at most ${MEASUREMENT_CHANGES_AGENT_ROWS}; distribution counts every Property whatever the limit.`)
 }).strict();
 var measurementDataQualityInputSchema = measurementDataQualityQuerySchema.extend({
   project: projectNameSchema
@@ -554,6 +575,14 @@ var gscTopPagesInputSchema = z3.object({
   limit: z3.number().int().positive().max(500).optional(),
   window: analyticsWindowSchema.optional()
 });
+var gscQueryTotalsInputSchema = z3.object({
+  project: projectNameSchema,
+  startDate: z3.string().optional(),
+  endDate: z3.string().optional(),
+  limit: z3.number().int().positive().max(5e3).optional(),
+  offset: z3.number().int().nonnegative().optional(),
+  window: analyticsWindowSchema.optional()
+});
 var gscInspectionsInputSchema = z3.object({
   project: projectNameSchema,
   url: z3.string().optional(),
@@ -704,6 +733,12 @@ var gbpLocationScopedInputSchema = z3.object({
   project: projectNameSchema,
   locationName: z3.string().optional()
 });
+var gbpReviewsInputSchema = z3.object({
+  project: projectNameSchema,
+  locationName: z3.string().optional(),
+  negative: z3.boolean().optional().describe("Only reviews at or below the project's negative-review threshold (negativeReviewMaxStars, 3 stars by default), the one the review.negative webhook uses."),
+  limit: z3.number().int().positive().max(500).optional().describe("Max reviews, newest first. Default 50.")
+});
 var gbpAccountsInputSchema = z3.object({
   project: projectNameSchema
 });
@@ -849,9 +884,16 @@ var competitorsInputSchema = z3.object({
   project: projectNameSchema,
   request: competitorBatchRequestSchema
 });
+var latestSweepRunIdDescription = "A run id, or latest for the latest sweep (the run the measurement reads display). With queryClass branded or non-brand and neither runId nor window, this tool reads latest; pass window to pool every sweep in it.";
 var competitorLandscapeInputSchema = competitorLandscapeQuerySchema.safeExtend({
-  project: projectNameSchema
+  project: projectNameSchema,
+  runId: z3.string().trim().min(1).optional().describe(latestSweepRunIdDescription)
 }).strict();
+function latestSweepUnlessPooled(query) {
+  if (query.runId !== void 0 || query.window !== void 0) return query;
+  if (query.queryClass !== "branded" && query.queryClass !== "non-brand") return query;
+  return { ...query, runId: LATEST_RUN_ID };
+}
 var projectUpsertInputSchema = z3.object({
   project: projectNameSchema,
   request: projectUpsertRequestSchema
@@ -1147,14 +1189,24 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_visibility_report",
     title: "Read scoped AI visibility",
-    description: "Read stored visibility for a site, group, market or property. Branded, non-brand and unclassified answers remain separate populations. The response owns rates, trends, query performance, answers and competitors under one frozen measured definition. Each population carries `comparison`, the change versus the previous eligible whole-project sweep when both are complete and comparable; it is absent when that sweep cannot be read. Material plan changes retain the prior measured revision; pending assignments are explicit. Search filters the query list only. Reuse cursors with identical selection. Never starts a sweep.",
+    description: "Read stored visibility for a site, group, market or property. Branded, non-brand and unclassified answers remain separate populations. The response owns rates, trends, query performance, answers and competitors under one frozen measured definition. Each population carries `comparison`, the change versus the previous eligible whole-project sweep when both are complete and comparable; it is absent when that sweep cannot be read. Material plan changes retain the prior measured revision; pending assignments are explicit. Search filters the query list only. Reuse cursors with identical selection. On an Advanced project use mode advanced, or omit mode: mode simple reads only pre-plan sweeps, so it is refused there unless runId names one. Never starts a sweep.",
     access: "read",
     tier: "monitoring",
     inputSchema: visibilityReportRequestSchema.safeExtend({ project: projectNameSchema }),
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/visibility-report"],
-    handler: (client, input) => {
+    handler: async (client, input) => {
       const { project, ...selection } = input;
+      if (selection.mode === "simple" && selection.runId === void 0) {
+        const { versions } = await client.listMeasurementPlanVersions(project);
+        if (versions.some((version) => version.active)) {
+          throw new CliError({
+            code: "VALIDATION_ERROR",
+            message: 'This project measures through an Advanced Measurement plan, so mode "simple" reads only pre-plan sweeps. Use mode "advanced", or omit mode. To inspect one pre-plan sweep, pass its runId.',
+            details: { project, mode: "simple" }
+          });
+        }
+      }
       return client.getVisibilityReport(project, selection);
     }
   }),
@@ -1227,7 +1279,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_project_overview",
     title: "Get project overview (composite)",
-    description: 'One-call summary for "how is project X doing?". Returns independent mention and citation coverage, separate query-level movement for each signal, query-basket comparability with added/removed counts, latest run and health, insights, provider/model breakdowns, competitors, attention items, and recent history. Movement excludes queries not shared by both sweeps. Filterable by location and time window. Prefer this over fanning out to separate read tools for the same question. SCOPE LIMIT: this returns nothing about Advanced Measurement: no plan, Targets, Properties, groups, or segments. Its silence is not evidence that a project lacks them. Before stating that a project has no Properties, no Advanced plan, or cannot break out per-Property performance, call canonry_measurement_plan_get to establish the portfolio type, and canonry_measurement_portfolio_summary to rank Properties.',
+    description: `One-call summary for "how is project X doing?". Returns independent mention and citation coverage, separate query-level movement for each signal, query-basket comparability with added/removed counts, latest run and health, insights, provider/model breakdowns, competitors, attention items, and recent history. Movement excludes queries not shared by both sweeps. Filterable by location and time window. Prefer this over fanning out to separate read tools for the same question. queryClassScope says which figures pool branded and non-brand: the coverage, scores (except scores.mentionShare) and movement count queries across both classes, so never report them as one class or as answers. The latest run's status and health are not a completeness check: for expected, executed and missing answers read canonry_measurement_data_quality or, for a plan run, canonry_run_completeness. canonry_doctor checks configuration and integrations, not sweeps. SCOPE LIMIT: this returns nothing about Advanced Measurement: no plan, Targets, Properties, groups, or segments. Its silence is not evidence that a project lacks them. When the system prompt has no Project shape line, call canonry_measurement_plan_get before stating that a project has no Properties, no Advanced plan, or cannot break out per-Property performance; use canonry_measurement_portfolio_summary to rank Properties.`,
     access: "read",
     tier: "core",
     inputSchema: z3.object({
@@ -1287,14 +1339,14 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_analytics_sources",
     title: "Get cited-source rankings",
-    description: "Where AI engines cite from for a project: cited domains ranked by how many answers cite them, each tagged with a category and a surface class (own / direct-competitor / ota-aggregator / editorial-media / other), plus a surface-class roll-up and a per-provider breakdown. Project-wide: without `runId` it pools every sweep in the window (`runCount` says how many); without `queryClass` it pools branded and non-brand answers, where branded queries inflate your own domain. For the sources behind non-brand answers, set `queryClass=non-brand` and the latest `runId`; on a v2 measurement plan the class comes from the plan, the same answers as canonry_competitor_landscape with scope=all-markets. Counts come from each answer's stored source list, so every engine is included, Gemini too. A domain counts at most once per answer; `answerShare` is the share of all answers in scope that cite it. `providersWithoutSources` names engines that answered but cited nothing. `limit` caps each ranked list (default 10 for this tool, which keeps each engine list whole); a long-tail rollup keeps the totals. The per-query breakdown is omitted unless `includeByQuery` is true. No LLM calls; probe runs excluded.",
+    description: "Where AI engines cite from for a project: cited domains ranked by how many answers cite them, each tagged with a category and a surface class (own / direct-competitor / ota-aggregator / editorial-media / other), plus a surface-class roll-up and a per-provider breakdown. Project-wide: without `queryClass` it pools branded and non-brand answers, where branded queries inflate your own domain. With `queryClass` set and neither `runId` nor `window`, this tool reads the latest sweep (`runId` latest); pass `window` to pool every sweep in it. `pooledAcrossRuns` true (`runCount` above 1) means the counts sum several runs and `runIds` is their scope; the legacy `runId` field is then only the newest run in the window. On a v2 measurement plan the class comes from the plan, the same answers as canonry_competitor_landscape with scope=all-markets. `countUnits` says what each count counts: `domainTotal` is distinct domains, never answers or citations. Compare engines by answer count or `answerShare`, never by rank position. Counts come from each answer's stored source list, so every engine is included, Gemini too. A domain counts at most once per answer; `answerShare` is the share of all answers in scope that cite it. `providersWithoutSources` names engines that answered but cited nothing. `limit` caps each ranked list (default 10 for this tool, which keeps each engine list whole); a long-tail rollup keeps the totals. The per-query breakdown is omitted unless `includeByQuery` is true. No LLM calls; probe runs excluded.",
     access: "read",
     tier: "monitoring",
     inputSchema: z3.object({
       project: projectNameSchema,
       window: analyticsWindowSchema.optional().describe("Time range: 7d, 30d, 90d, or all (default all)."),
       limit: z3.number().int().positive().max(50).optional().describe("Cap each ranked list to the top N domains. Default 10; larger lists can exceed the tool-result cap."),
-      runId: z3.string().trim().min(1).optional().describe("Read one answer-visibility run (for example the latest sweep) instead of pooling every run in the window."),
+      runId: z3.string().trim().min(1).optional().describe(latestSweepRunIdDescription),
       queryClass: z3.enum(["all", "branded", "non-brand"]).optional().describe("Branded or non-brand answers only. With an active v2 measurement plan the class comes from the plan assignments. Default all pools both classes."),
       includeByQuery: z3.boolean().optional().describe("Include the per-query breakdown. It is large; default false for this tool.")
     }),
@@ -1305,7 +1357,7 @@ var canonryMcpTools = [
       // The full ranked lists run past the agent's tool-result cap on a large
       // project, and the per-engine lists are the first thing lost.
       limit: input.limit ?? 10,
-      runId: input.runId,
+      runId: latestSweepUnlessPooled(input).runId,
       queryClass: input.queryClass,
       includeByQuery: input.includeByQuery ?? false
     })
@@ -1313,7 +1365,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_competitor_landscape",
     title: "Get historical competitor landscape",
-    description: "Returns pinned competitors first, then observed direct competitors and other cited sources from stored answer/source evidence only. Mention share is percentage points (0..100) from answer text; citations are independent. The response carries basis (tracked or observed), availability, and reason. Pins exclusively define the comparison set when present. Otherwise at least 3 stored direct competitors must each be mentioned in 3 answers in the selected scope; raw names and platforms never enter that denominator. Without a comparison set the ratio is null, never 100%. The full comparison array is uncapped. Share of voice needs ONE query class: `queryClass=all`, and omitting it, pool branded and non-brand, so every `shareOfVoice` comes back null and only the counts are published. Pass `queryClass=non-brand` (or `branded`) for a ratio, exactly as visibility-stats does. A project with no brand name or alias cannot be split by class, so a class-scoped read on one is refused rather than answered empty. Optional groupBy: model adds provider/requested-model groups with separate served-model evidence and sample counts. Optional model filters one exact requested model ID and requires provider. Unknown historical models remain explicit. Groups are not a matched-query or equal-weight comparison. Advanced reads support one market group or explicit scope: all-markets. On a project with an active v2 measurement plan, queryClass=branded or non-brand with no scope or groupKey defaults to scope=all-markets, so classes come from the plan; pass scope=project to force the text classifier. No provider, discovery, or classifier work runs. Ranked lists are capped at 100 observed/other-source rows per group; pins remain complete. `observedNames` are names written in answer text, not cited sources, capped at the top 50 by answer count; `observedNamesTotal` is the full count. Model groups are capped at 50 and disclose truncation.",
+    description: "Returns pinned competitors first, then observed direct competitors and other cited sources from stored answer/source evidence only. Mention share is percentage points (0..100) from answer text; citations are independent. The response carries basis (tracked or observed), availability, and reason. Pins exclusively define the comparison set when present. Otherwise at least 3 stored direct competitors must each be mentioned in 3 answers in the selected scope; raw names and platforms never enter that denominator. Without a comparison set the ratio is null, never 100%. The full comparison array is uncapped. Share of voice needs ONE query class: `queryClass=all`, and omitting it, pool branded and non-brand, so every `shareOfVoice` comes back null and only the counts are published. Pass `queryClass=non-brand` (or `branded`) for a ratio, exactly as visibility-stats does. A project with no brand name or alias cannot be split by class, so a class-scoped read on one is refused rather than answered empty. Optional groupBy: model adds provider/requested-model groups with separate served-model evidence and sample counts. Optional model filters one exact requested model ID and requires provider. Unknown historical models remain explicit. Groups are not a matched-query or equal-weight comparison. Advanced reads support one market group or explicit scope: all-markets. On a project with an active v2 measurement plan, queryClass=branded or non-brand with no scope or groupKey defaults to scope=all-markets, so classes come from the plan; pass scope=project to force the text classifier. No provider, discovery, or classifier work runs. Ranked lists are capped at 100 observed/other-source rows per group; pins remain complete. `observedNames` are names written in answer text, not cited sources, capped at the top 50 by answer count; `observedNamesTotal` counts distinct names, never answers (`countUnits` says what each count counts). Model groups are capped at 50 and disclose truncation. For which names answers give instead across a portfolio, read this with queryClass and runId latest: per-Property named-instead lists are samples of weak Properties. With queryClass branded or non-brand and neither runId nor window, this tool reads the latest sweep; pass window to pool sweeps. `runCount` and `runIds` name the runs counted; above 1 the counts pool several runs.",
     access: "read",
     tier: "monitoring",
     inputSchema: competitorLandscapeInputSchema,
@@ -1321,7 +1373,7 @@ var canonryMcpTools = [
     openApiOperations: ["GET /api/v1/projects/{name}/analytics/competitors"],
     handler: (client, input) => {
       const { project, ...query } = input;
-      return client.getCompetitorLandscape(project, query);
+      return client.getCompetitorLandscape(project, latestSweepUnlessPooled(query));
     }
   }),
   defineTool({
@@ -1342,7 +1394,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_doctor",
     title: "Run health checks",
-    description: 'Run canonry health checks. With `project`, runs project-scoped checks (Google/GA auth, redirect URI, scopes, property access). Without `project`, runs global checks (provider keys, etc.). Use `checks` to filter by exact ID or wildcard prefix (e.g. ["google.auth.*"]). Returns a structured DoctorReport with per-check status, code, summary, remediation, and details \u2014 use this to diagnose Google auth failures (401/403/redirect-mismatch/principal-mismatch) without parsing logs.',
+    description: 'Run canonry health checks. With `project`, runs project-scoped checks (Google/GA auth, redirect URI, scopes, property access). Without `project`, runs global checks (provider keys, etc.). Use `checks` to filter by exact ID or wildcard prefix (e.g. ["google.auth.*"]). Returns a structured DoctorReport with per-check status, code, summary, remediation, and details. Use it to diagnose Google auth failures (401/403/redirect-mismatch/principal-mismatch) without parsing logs. It checks configuration and integrations, not whether a sweep completed or its answers are reliable: for that read canonry_measurement_data_quality or canonry_run_completeness.',
     access: "read",
     tier: "core",
     inputSchema: doctorInputSchema,
@@ -1437,7 +1489,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_run_completeness",
     title: "Get run completeness",
-    description: "Expected, answered and missing measurement slots per provider for a plan run, whether canonry_run_fill would be admitted now and why not, and the latest fill.",
+    description: "Is a plan run complete? Expected, executed and missing answers (measurement slots, one per query per engine) for the run, missing answers per engine (missingByProvider), whether canonry_run_fill would be admitted now and why not, and the latest fill. Pass run.displayedRunId from canonry_measurement_data_quality, or measurement.displayedRunId from canonry_measurement_overview. Quote expected, executed and missing. A planless run (planned false) has no expected answers, so its zero counts are not a completeness check; readable false means the counts are unknown, not zero.",
     access: "read",
     tier: "monitoring",
     inputSchema: runGetInputSchema,
@@ -1796,7 +1848,8 @@ var canonryMcpTools = [
     access: "read",
     tier: "setup",
     inputSchema: logQuerySchema,
-    outputSchema: operationalLogListDtoSchema,
+    // Tolerant on purpose: a field a newer server adds is dropped, not a rejected page.
+    outputSchema: operationalLogListReadSchema,
     annotations: readAnnotations(false),
     openApiOperations: ["GET /api/v1/operations/logs"],
     handler: async (client, input) => client.listOperationalLogs(input)
@@ -1885,6 +1938,17 @@ var canonryMcpTools = [
     openApiOperations: ["GET /api/v1/projects/{name}/google/gsc/top-pages"],
     handler: (client, input) => client.gscTopPages(input.project, compactStringParams(input, ["startDate", "endDate", "limit", "window"]))
   }),
+  defineTool({
+    name: "canonry_gsc_query_totals",
+    title: "Get GSC query totals",
+    description: "Get stored Google Search Console totals per search query for a date window (no call to Google): clicks, impressions, CTR, impression-weighted average position and the number of days the query appeared. Rows are ordered clicks desc, impressions desc, query asc; page with limit/offset until truncated is false. The rows are the queries Google names: Google leaves rare queries out, so never sum them for a property total, use canonry_gsc_performance_daily. Each row has `source`: google (Google's per-query figures), page-summed (legacy page table, impressions over-count) or mixed (both across the window).",
+    access: "read",
+    tier: "gsc",
+    inputSchema: gscQueryTotalsInputSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/projects/{name}/google/gsc/query-totals"],
+    handler: (client, input) => client.gscQueryTotals(input.project, compactStringParams(input, ["startDate", "endDate", "limit", "offset", "window"]))
+  }),
   defineTool({
     name: "canonry_gsc_inspections",
     title: "List GSC inspections",
@@ -2217,6 +2281,17 @@ var canonryMcpTools = [
     openApiOperations: ["GET /api/v1/projects/{name}/gbp/places"],
     handler: (client, input) => client.listGbpPlaces(input.project, compactStringParams(input, ["locationName"]))
   }),
+  defineTool({
+    name: "canonry_gbp_reviews",
+    title: "Get GBP reviews",
+    description: "List stored Google Business Profile reviews newest first, with each location's review access and latest rating. Reviews come from the Business Profile v4 API when Google has enabled it for the Cloud project (every review), otherwise from the public Places listing (at most five, chosen by relevance). `negative` marks reviews at or below the project's threshold (`negativeMaxStars` in the response; set per project with `negativeReviewMaxStars`, 3 stars by default), the one the `review.negative` webhook uses; `alertState` says whether each one alerted. Empty until a gbp sync runs.",
+    access: "read",
+    tier: "gbp",
+    inputSchema: gbpReviewsInputSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/projects/{name}/gbp/reviews"],
+    handler: (client, input) => client.listGbpReviews(input.project, compactStringParams(input, ["locationName", "negative", "limit"]))
+  }),
   defineTool({
     name: "canonry_gbp_summary",
     title: "Get GBP local-AEO summary",
@@ -2261,6 +2336,20 @@ var canonryMcpTools = [
     openApiOperations: ["GET /api/v1/projects/{name}/traffic/status"],
     handler: (client, input) => client.trafficStatus(input.project)
   }),
+  defineTool({
+    name: "canonry_traffic_referral_assessment",
+    title: "Assess AI referral bursts",
+    description: "Read stored AI-referral burst evidence and a separate adjusted estimate without changing raw totals or report headlines. Candidate bursts are not confirmed automation. Project/source scope only, for Simple or Advanced portfolios; Property, Target and market attribution are unavailable. GA quotient is descriptive with unknown matching coverage. No provider calls.",
+    access: "read",
+    tier: "traffic",
+    inputSchema: referralAssessmentQuerySchema.extend({ project: projectNameSchema }),
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/projects/{name}/traffic/referral-assessment"],
+    handler: (client, input) => {
+      const { project, ...query } = input;
+      return client.trafficReferralAssessment(project, query);
+    }
+  }),
   defineTool({
     name: "canonry_traffic_events",
     title: "List traffic events",
@@ -2361,7 +2450,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_project_upsert",
     title: "Create or replace project",
-    description: "Create or replace a Canonry project. PUT semantics \u2014 fields not in the request are reset to their defaults. Provide the full intended project shape.",
+    description: "Create or replace a Canonry project. PUT semantics \u2014 fields not in the request are reset to their defaults. Provide the full intended project shape. Exception: an omitted providerDispatchModes (provider \u2192 sync|batch for scheduled sweeps) keeps the stored preference; send {} to clear it.",
     access: "write",
     tier: "setup",
     inputSchema: projectUpsertInputSchema,
@@ -2549,7 +2638,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_measurement_overview",
     title: "Get Advanced Measurement overview",
-    description: "For best/worst Property mention rankings, prefer canonry_measurement_portfolio_summary and its mentionRanking. An unavailable aggregate does not invalidate available Property metrics. Return stored, revision-pinned Advanced Measurement metrics and a bounded page of Property rows for all Properties, one reporting group, or one Property. Filter by query class, provider, location, date window, run, or Property search; search filters rows without changing metric denominators. It ranks one run snapshot only and never infers a trend or compares across revisions. Choose label-asc (default), label-desc, citationCoverage-asc/desc, or mentionCoverage-asc/desc. For a coverage sort, unavailable rows form the first bucket in either direction; available rows then follow the requested numeric direction. The cursor is sort-aware, pins pagination to the active revision, displayed run, evidence snapshot, and filters even if a newer run completes, and must be reused unchanged with the same sort and filters. Legacy label cursors work only when sort is omitted, while any explicit sort needs a new sort-bound cursor. It never starts provider work or incurs provider cost; page size is at most 100, and it refuses invalid scope keys, cursor combinations, appended evidence, or a run pinned to another revision.",
+    description: "For best/worst Property mention rankings, prefer canonry_measurement_portfolio_summary and its mentionRanking. An unavailable aggregate does not invalidate available Property metrics. Return stored, revision-pinned Advanced Measurement metrics and a bounded page of Property rows for all Properties, one reporting group, or one Property. Filter by query class, provider, location, date window, run, or Property search; search filters rows without changing metric denominators. On a schema-v2 plan each Property row carries its metro (and otherMetros when it is in several). It ranks one run snapshot only and never infers a trend or compares across revisions. Choose label-asc (default), label-desc, citationCoverage-asc/desc, or mentionCoverage-asc/desc. For a coverage sort, unavailable rows form the first bucket in either direction; available rows then follow the requested numeric direction. The cursor is sort-aware, pins pagination to the active revision, displayed run, evidence snapshot, and filters even if a newer run completes, and must be reused unchanged with the same sort and filters. Legacy label cursors work only when sort is omitted, while any explicit sort needs a new sort-bound cursor. It never starts provider work or incurs provider cost; page size is at most 100, and it refuses invalid scope keys, cursor combinations, appended evidence, or a run pinned to another revision.",
     access: "read",
     tier: "setup",
     inputSchema: measurementOverviewInputSchema,
@@ -2563,7 +2652,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_measurement_property_evidence",
     title: "Page one Property's measurement evidence",
-    description: "Return the stored evidence rows for exactly one Property out of one revision-pinned run, optionally narrowed to a question class, provider, or location. shape chooses what a row is: sources (the default) returns one row per cited URL under evidence; answers returns one row per measured answer under answers, with the cited URLs nested inside and both signals on the row (mentioned, cited). Use shape=answers to explain a GAP \u2014 an answer that mentioned the Property without linking it, or that named nobody at all, has no URL to hang a source row on and does not appear in the default shape, so counting source rows understates what was measured. mentioned is null, never false, when the answer text was never captured: that is a missing signal, not a measured no. Exactly one of evidence or answers is returned and the other is absent rather than empty. A cursor is bound to the shape that issued it and is refused on the other. Prefer this over canonry_measurement_report when you want one Property: the report reconstructs every group and every Target for a revision and does not paginate. Run selection matches canonry_measurement_overview \u2014 the most recent completed run pinned to the active revision unless runId names another, and a run pinned to a different revision is refused rather than joined. The cursor also pins the active revision, displayed run, evidence snapshot, and filters; reuse it unchanged. Not available for a schema v1 revision, which records no question class to scope by. It never starts provider work; page size is at most 100. An empty page under measurement.state = not_measured means the Property has not been measured at all, which is NOT a measured result of zero.",
+    description: "Return the stored evidence rows for exactly one Property out of one revision-pinned run, optionally narrowed to a provider or location. Defaults to non-brand queries; pass queryClass branded or all to change it, and state the returned class. shape chooses what a row is: sources (the default) returns one row per cited URL under evidence; answers returns one row per measured answer under answers, with the cited URLs nested inside and both signals on the row (mentioned, cited). Use shape=answers to explain a GAP: an answer that mentioned the Property without linking it, or that named nobody at all, has no URL to hang a source row on and does not appear in the default shape, so counting source rows understates what was measured. mentioned is null, never false, when the answer text was never captured: that is a missing signal, not a measured no. Exactly one of evidence or answers is returned and the other is absent rather than empty. A cursor is bound to the shape that issued it and is refused on the other. Prefer this over canonry_measurement_report when you want one Property: the report reconstructs every group and every Target for a revision and does not paginate. Run selection matches canonry_measurement_overview: the most recent completed run pinned to the active revision unless runId names another, and a run pinned to a different revision is refused rather than joined. The cursor also pins the active revision, displayed run, evidence snapshot, and filters; reuse it unchanged. Not available for a schema v1 revision, which records no question class to scope by. It never starts provider work; page size is at most 100. An empty page under measurement.state = not_measured means the Property has not been measured at all, which is NOT a measured result of zero.",
     access: "read",
     tier: "setup",
     inputSchema: measurementPropertyEvidenceInputSchema,
@@ -2571,21 +2660,25 @@ var canonryMcpTools = [
     openApiOperations: ["GET /api/v1/projects/{name}/measurement-property-evidence"],
     handler: (client, input) => {
       const { project, ...query } = input;
-      return client.getMeasurementPropertyEvidence(project, query);
+      return client.getMeasurementPropertyEvidence(project, { ...query, queryClass: agentQueryClass(query.queryClass) });
     }
   }),
   defineTool({
     name: "canonry_measurement_portfolio_summary",
     title: "Summarize measured Properties",
-    description: "Start here for best and worst Properties. One call returns the weakest Properties, the names answers wrote instead of them, and the domains engines cited for them. Defaults to non-brand queries; state the returned queryClass and never pool branded with non-brand. Keep the default limit; for more rows narrow with groupKey (a metro) rather than raising limit, which can overflow the tool-result cap. Mention (answer text names the Property) and citation (a source URL on its page) are separate: report each as numerator/denominator, with any unattributed count beside mention. Denominators count answers, one per query per engine (queries x engines = answers). Group Properties only by each row's metro and submarkets, never by label. namedInsteadInAnswerText lists names written in the answer text of answers that neither named nor cited the Property, counted by answer: they are not citations. citedDomains and weakestAnswerSources count answers citing each domain, every engine included; weakestAnswerSources covers the weakest rows plus every tied Property, each answer once. When tiedAtWeakest is set, that many Properties share the weakest rates and are ordered by name, not ranked. mentionRanking.strongest/.weakest rank every Property with an available mention rate; .excluded lists the rest with reasons. markets lists one level worst-first (metros, or a groupKey's submarkets), capped at limit, with totalMarkets; includeNestedMarkets returns every level. Markets may share Properties and never sum to portfolio totals. Reads stored data only; never starts provider work.",
+    description: "Start here for best and worst Properties. One call returns the weakest Properties, the names answers wrote instead of them, and the domains engines cited for them. Defaults to non-brand queries; state the returned queryClass and never pool branded with non-brand. Returns at most 4 Property rows per list, the most that fit one result; a larger limit is lowered and limitNote says so. For other rows pass groupKey (one metro's weakest), or page canonry_measurement_overview. Mention (answer text names the Property) and citation (a source URL on its page) are separate: report each as numerator/denominator, with any unattributed count beside mention. Denominators count answers, one per query per engine (queries x engines = answers). Group Properties only by each row's metro and submarkets, never by label. namedInsteadInAnswerText lists names written in the answer text of answers that neither named nor cited the Property, counted by answer: they are not citations, and namedInsteadInAnswerTextTotal counts distinct names, not answers. citedDomains and weakestAnswerSources count answers citing each domain, every engine included; weakestAnswerSources pools the weakest rows plus every tied Property, each answer once, and its domainTotal counts distinct domains, not citations. When tiedAtWeakest is set, tiedAtWeakest.count Properties share the weakest rates and the rows are the first of them by name, not a rank: report the count, tiedAtWeakest.byMetro (tied Properties per metro over the whole tie; a Property in two metros counts in both) and tiedAtWeakest.namedInstead (names written instead across the whole tie, counted by distinct answer; namedInsteadTotal is distinct names), and call the rows examples. mentionRanking.strongest/.weakest rank every Property with an available mention rate; .excluded lists the rest with reasons. markets lists every market at one level, worst-first (every metro, or a groupKey's submarkets), whatever the limit. Markets may share Properties and never sum to portfolio totals. Reads stored data only; never starts provider work.",
     access: "read",
     tier: "monitoring",
     inputSchema: measurementPortfolioSummaryInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/measurement-portfolio-summary"],
-    handler: (client, input) => {
+    handler: async (client, input) => {
       const { project, ...query } = input;
-      return client.getMeasurementPortfolioSummary(project, query);
+      const most = PORTFOLIO_SUMMARY_AGENT_ROWS;
+      const lowered = query.limit !== void 0 && query.limit > most;
+      const summary = await client.getMeasurementPortfolioSummary(project, lowered ? { ...query, limit: most } : query);
+      const more = query.groupKey === void 0 ? "For other rows pass groupKey (one metro's weakest), or page canonry_measurement_overview." : "For more rows page canonry_measurement_overview with scope group.";
+      return portfolioSummaryForAgents(summary, lowered ? `limit ${query.limit} was lowered to ${most}, the most rows that fit one result. ${more}` : void 0);
     }
   }),
   defineTool({
@@ -2619,7 +2712,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_measurement_property_competitors",
     title: "List a Property\u2019s stored replacements",
-    description: "After reviewing a Property\u2019s question outcomes, find repeated stored replacement names for its misses. Reads stored data only; it never starts provider work.",
+    description: "For one Property: the names answers wrote in their text instead of it, and the domains its own answers cited. Defaults to non-brand queries; pass queryClass branded or all to change it, and state the returned queryClass. competitors[] are names written in the answer text of this Property's answers that did not name it, never citations: occurrences counts answers, and questions lists at most 5 of questionTotal, so never read those 5 as all. citedDomains (top 10), citedDomainsTotal (distinct domains) and citedDomainsAnswers (the answers counted) are the domains cited in this Property's own answers, counted by answer: sources, never names written instead. Use them, not the portfolio-wide weakestAnswerSources, for one Property's sources. Reads stored data only; it never starts provider work.",
     access: "read",
     tier: "monitoring",
     inputSchema: measurementPropertyCompetitorsInputSchema,
@@ -2627,13 +2720,13 @@ var canonryMcpTools = [
     openApiOperations: ["GET /api/v1/projects/{name}/measurement-property-competitors"],
     handler: (client, input) => {
       const { project, ...query } = input;
-      return client.getMeasurementPropertyCompetitors(project, query);
+      return client.getMeasurementPropertyCompetitors(project, { ...query, queryClass: agentQueryClass(query.queryClass) });
     }
   }),
   defineTool({
     name: "canonry_measurement_changes",
     title: "Compare stored measurement changes",
-    description: "After reviewing the current summary, compare stored runs only when their execution identity is compatible. Reads stored data only; it never starts provider work.",
+    description: "What changed since the previous sweep: compares the displayed run with the previous run of the same plan revision and execution identity; an incompatible pair returns unavailable with a reason, never a trend. Defaults to non-brand queries: call once per class (queryClass branded for the branded move) and never report one class as the whole. queryClass all pools both classes in rows and distribution and adds metricsByClass, the headline metrics per class; report those per class, never the pooled metrics alone. changedProperties come largest move first (answers that named the Property, then answers that cited it; sort label for alphabetical), default 10 and at most 20 rows; totalProperties above the rows returned means rows you did not see. distribution counts every Property in scope: improved, declined, mixed, withinNoise, unchanged, notComparable. mentionAnswersDelta and citationAnswersDelta are signed answer counts; denominatorChanged true means a rate was taken over a different number of answers, so those counts are not like for like and the coverage rates give the direction. A move is the rate change times the larger answer count (the count change when the denominator held). withinNoise true means every move was 2 answers or fewer: within noise, never a gain, loss, trend or regression. Reads stored data only; it never starts provider work.",
     access: "read",
     tier: "monitoring",
     inputSchema: measurementChangesInputSchema,
@@ -2641,13 +2734,13 @@ var canonryMcpTools = [
     openApiOperations: ["GET /api/v1/projects/{name}/measurement-changes"],
     handler: (client, input) => {
       const { project, ...query } = input;
-      return client.getMeasurementChanges(project, query);
+      return client.getMeasurementChanges(project, { ...query, queryClass: agentQueryClass(query.queryClass) });
     }
   }),
   defineTool({
     name: "canonry_measurement_data_quality",
     title: "Inspect stored measurement data quality",
-    description: "Before acting on a measurement, inspect its stored completeness, capture, retrieval, and comparability context. Reads stored data only; it never starts provider work.",
+    description: "Is the sweep complete, and is anything unreliable? For the displayed run (run.displayedRunId, or runId): completeness (expected, executed, answered and missing answers), capture, retrieval, population (expected, answered and missing questions), comparison (comparability with the previous run), unattributedByClass (per class, the answers every mention rate leaves out because they name the Property ambiguously; report per class, never pooled) and latestFill (the newest in-place fill: status, expected, filled; its answers already count in completeness). Quote expected, executed and missing. A Healthy run status is not a completeness check. For missing answers per engine and whether a fill would be admitted, pass run.displayedRunId to canonry_run_completeness. Reads stored data only; it never starts provider work.",
     access: "read",
     tier: "monitoring",
     inputSchema: measurementDataQualityInputSchema,
@@ -2842,7 +2935,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_run_trigger",
     title: "Trigger run",
-    description: "Trigger an answer-visibility run for a Canonry project. Omit both scoping fields for a full sweep. Pass request.queries[] to measure only some of the project's tracked questions. On a project with a published measurement plan, pass request.measurementScope with at least one group or target to measure one slice of that plan \u2014 a group stands for its member Targets, and only the questions those Targets selected are measured. A scope naming nothing is rejected rather than treated as a full sweep, so omit the field entirely when you want everything. Either kind of slice is recorded as a spot check: it never replaces a full sweep in the dashboard, analytics or report. For verification scenarios (testing whether a provider migration worked, reproducing a regression, sanity-checking after a code change), set request.trigger='probe' \u2014 probe runs write a snapshot you can inspect via canonry_runs_get but are EXCLUDED from dashboard, analytics, intelligence, report, and notifications. Use 'probe' whenever you are testing on your own initiative rather than producing data the user/dashboard will consume.",
+    description: "Trigger an answer-visibility run for a Canonry project. Omit both scoping fields for a full sweep. Pass request.queries[] to measure only some of the project's tracked questions. On a project with a published measurement plan, pass request.measurementScope with at least one group or target to measure one slice of that plan \u2014 a group stands for its member Targets, and only the questions those Targets selected are measured. A scope naming nothing is rejected rather than treated as a full sweep, so omit the field entirely when you want everything. Either kind of slice is recorded as a spot check: it never replaces a full sweep in the dashboard, analytics or report. For verification scenarios (testing whether a provider migration worked, reproducing a regression, sanity-checking after a code change), set request.trigger='probe' \u2014 probe runs write a snapshot you can inspect via canonry_runs_get but are EXCLUDED from dashboard, analytics, intelligence, report, and notifications. Use 'probe' whenever you are testing on your own initiative rather than producing data the user/dashboard will consume. request.dispatchMode='batch' sends every provider that can (a full sweep of a published plan, a batch-capable provider enabled in config.yaml, every answer's model frozen) to its asynchronous batch API at the batch price; the rest run sync and the run stays running until the batch ends (up to its deadline, 24h by default). A batch request no provider can honour is refused with each provider's reason. Omit it for the ordinary sync sweep.",
     access: "write",
     tier: "core",
     inputSchema: runTriggerInputSchema,

package/dist/{chunk-3LCR6WU6.js → chunk-ONTEFAA7.js}

@@ -5,12 +5,12 @@ import {
   siteCrawlGraphNodes,
   siteCrawlPages,
   siteCrawlSnapshots
-} from "./chunk-P5VXVFQW.js";
+} from "./chunk-7RKCDOWO.js";
 import {
   SITE_CRAWL_GRAPH_MAX_EDGES,
   SITE_CRAWL_GRAPH_MAX_NODES,
   TEMPLATE_LINK_RATIO_THRESHOLD
-} from "./chunk-S5OSY3PI.js";
+} from "./chunk-KVQHG3WB.js";
 
 // src/site-crawl-graph-layout.ts
 import crypto from "crypto";