@canonry/canonry 7.25.0 → 7.43.2

package/dist/{chunk-6AOIFHC6.js → chunk-LYKDNJXR.js}

@@ -1,3 +1,7 @@
+import {
+  CliError,
+  EXIT_SYSTEM_ERROR
+} from "./chunk-HGMYEDAQ.js";
 import {
   AGENT_MEMORY_KEY_MAX_LENGTH,
   AGENT_MEMORY_VALUE_MAX_BYTES,
@@ -7,6 +11,7 @@ import {
   GOOGLE_MARKETING_STORED_SNAPSHOT_PAGE_MAX,
   LATEST_RUN_ID,
   MEASUREMENT_DEFAULT_QUERY_CLASS,
+  OperationAccesses,
   PROVIDER_ACCOUNT_FAILURE_STREAK,
   PROVIDER_ACCOUNT_RETRY_HOURS,
   RESEARCH_RUN_SCOPE,
@@ -27,6 +32,7 @@ import {
   adsUnresolvedOperationListQuerySchema,
   agentConversationCreateSchema,
   apiKeyDtoSchema,
+  auditHistoryQuerySchema,
   backlinkSourceSchema,
   calendarDateSchema,
   canonicalizeGtmAccountId,
@@ -35,7 +41,9 @@ import {
   competitorAliasesRequestSchema,
   competitorAppendRequestSchema,
   competitorBatchRequestSchema,
+  competitorChangePreviewRequestSchema,
   competitorLandscapeQuerySchema,
+  competitorSuggestionsQuerySchema,
   contentTargetDismissRequestSchema,
   describeError,
   discoveryBucketSchema,
@@ -44,14 +52,17 @@ import {
   discoveryRunRequestSchema,
   feedbackAcceptedDtoSchema,
   feedbackSubmissionSchema,
+  gaAcquisitionQuerySchema,
   gaMeasurementAnalysisWindowSchema,
   gaMeasurementHostScopeSchema,
   gaSearchLandingWindowSchema,
   googleAdsMetricsWindowSchema,
   gscPerformanceOrderBySchema,
+  instanceStatusDtoSchema,
   keywordBatchRequestSchema,
   keywordGenerateRequestSchema,
   logQuerySchema,
+  maxOperationAccess,
   measurementChangesQuerySchema,
   measurementDataQualityQuerySchema,
   measurementDiscoveryRequestSchema,
@@ -94,9 +105,11 @@ import {
   measurementQuestionResultQuerySchema,
   notificationCreateRequestSchema,
   notificationEventSchema,
+  operationAccess,
   operationalLogListReadSchema,
   organicEvidencePeriodSchema,
   projectConfigSchema,
+  projectPatchRequestSchema,
   projectUpsertRequestSchema,
   providerQuotaPolicySchema,
   providerReloadRequestSchema,
@@ -109,6 +122,7 @@ import {
   queryTrackingPreviewRequestSchema,
   referralAssessmentQuerySchema,
   reportMonthSchema,
+  reportedQueryClasses,
   researchBatchCreateSchema,
   researchRunCreateSchema,
   resultsClearRequestSchema,
@@ -141,77 +155,11 @@ import {
   trafficConnectVercelRequestSchema,
   trafficConnectWordpressRequestSchema,
   trafficEventKindSchema,
+  trafficSamplesQuerySchema,
   trafficSeriesGranularitySchema,
   visibilityCompareSelectionSchema,
   visibilityReportRequestSchema
-} from "./chunk-PFEQWGJN.js";
-
-// src/support-links.ts
-var CANONRY_DISCORD_URL = "https://discord.gg/jnJ2H2z5Xh";
-var CANONRY_ISSUES_URL = "https://github.com/Canonry/canonry/issues";
-
-// src/cli-error.ts
-function isMachineFormat(format) {
-  return format === "json" || format === "jsonl";
-}
-var EXIT_USER_ERROR = 1;
-var EXIT_SYSTEM_ERROR = 2;
-var CliError = class extends Error {
-  code;
-  displayMessage;
-  details;
-  exitCode;
-  constructor(options) {
-    super(options.message);
-    this.name = "CliError";
-    this.code = options.code;
-    this.displayMessage = options.displayMessage;
-    this.details = options.details;
-    this.exitCode = options.exitCode ?? EXIT_USER_ERROR;
-  }
-};
-function usageError(displayMessage, options) {
-  const firstLine = displayMessage.split("\n", 1)[0] ?? "Error: invalid command usage";
-  return new CliError({
-    code: "CLI_USAGE_ERROR",
-    message: options?.message ?? firstLine.replace(/^Error:\s*/, ""),
-    displayMessage,
-    details: options?.details
-  });
-}
-function isEndpointMissing(err) {
-  if (!(err instanceof CliError)) return false;
-  const status = err.details?.httpStatus;
-  return status === 404 || status === 405;
-}
-function systemError(message, options) {
-  return new CliError({
-    code: "CLI_SYSTEM_ERROR",
-    message,
-    displayMessage: options?.displayMessage,
-    details: options?.details,
-    exitCode: EXIT_SYSTEM_ERROR
-  });
-}
-function printCliError(err, format) {
-  if (isMachineFormat(format)) {
-    const envelope = err instanceof CliError ? { error: { code: err.code, message: err.message, ...err.details ? { details: err.details } : {} } } : { error: { code: "CLI_ERROR", message: err instanceof Error ? err.message : "An unexpected error occurred" } };
-    console.error(JSON.stringify(envelope, null, format === "jsonl" ? 0 : 2));
-    return;
-  }
-  if (err instanceof CliError && err.displayMessage) {
-    console.error(err.displayMessage);
-  } else if (err instanceof Error) {
-    console.error(`Error: ${err.message}`);
-  } else {
-    console.error("An unexpected error occurred");
-  }
-  const unexpected = !(err instanceof CliError) || err.exitCode === EXIT_SYSTEM_ERROR;
-  if (unexpected && process.stderr.isTTY) {
-    console.error(`
-Need help? Run 'canonry support' or ask in the Canonry Discord: ${CANONRY_DISCORD_URL}`);
-  }
-}
+} from "./chunk-E43JM3QV.js";
 
 // src/package-version.ts
 import { createRequire } from "module";
@@ -388,6 +336,13 @@ var writeAnnotations = (opts) => ({
   destructiveHint: Boolean(opts.destructiveHint),
   ...opts.openWorldHint ? { openWorldHint: opts.openWorldHint } : {}
 });
+function toolOperationAccess(tool) {
+  const derived = maxOperationAccess(tool.openApiOperations.map((operation) => {
+    const separator = operation.indexOf(" ");
+    return separator < 0 ? OperationAccesses.stored : operationAccess(operation.slice(0, separator), operation.slice(separator + 1));
+  }));
+  return tool.access === "write" ? OperationAccesses.write : derived;
+}
 function defineTool(tool) {
   return {
     ...tool,
@@ -541,6 +496,7 @@ var measurementDraftActionOpenApiOperations = [
   "POST /api/v1/projects/{name}/measurement-plan/draft/actions/discard"
 ];
 var runsListInputSchema = z3.object({
+  since: z3.string().optional().describe("Inclusive ISO 8601 lower bound on creation time. Omit to read all dates."),
   project: projectNameSchema,
   limit: z3.number().int().positive().max(500).optional(),
   kind: runListFilterQuerySchema.shape.kind.describe('Restrict to a single run kind (e.g. "answer-visibility"). Unknown values are rejected.'),
@@ -562,12 +518,9 @@ var timelineInputSchema = z3.object({
   limit: z3.number().int().positive().max(100).optional().describe("Restrict history to the most recent N project runs.")
 });
 var historyFilterShape = {
+  ...auditHistoryQuerySchema.shape,
   limit: z3.number().int().positive().max(500).optional(),
-  offset: z3.number().int().nonnegative().optional(),
-  since: z3.string().optional().describe("ISO 8601 lower bound."),
-  action: z3.string().optional().describe("Exact audit action filter."),
-  actor: z3.string().optional().describe("Exact actor filter."),
-  entityType: z3.string().optional().describe("Exact entity type filter.")
+  offset: z3.number().int().nonnegative().optional()
 };
 var projectHistoryInputSchema = z3.object({ project: projectNameSchema, ...historyFilterShape });
 var globalHistoryInputSchema = z3.object(historyFilterShape);
@@ -938,6 +891,12 @@ var competitorsAddInputSchema = z3.object({
   project: projectNameSchema,
   request: competitorAppendRequestSchema
 });
+var competitorChangePreviewInputSchema = z3.discriminatedUnion("change", [
+  competitorChangePreviewRequestSchema.options[0].extend({ project: projectNameSchema }),
+  competitorChangePreviewRequestSchema.options[1].extend({ project: projectNameSchema }),
+  competitorChangePreviewRequestSchema.options[2].extend({ project: projectNameSchema }),
+  competitorChangePreviewRequestSchema.options[3].extend({ project: projectNameSchema })
+]);
 var competitorDomainInputSchema = z3.string().trim().min(1).describe("Tracked competitor domain (any spelling; it resolves to the stored registrable domain).");
 var competitorAliasesInputSchema = competitorAliasesRequestSchema.safeExtend({
   project: projectNameSchema,
@@ -952,6 +911,9 @@ var competitorLandscapeInputSchema = competitorLandscapeQuerySchema.safeExtend({
   project: projectNameSchema,
   runId: z3.string().trim().min(1).optional().describe(latestSweepRunIdDescription)
 }).strict();
+var competitorSuggestionsInputSchema = competitorSuggestionsQuerySchema.safeExtend({
+  project: projectNameSchema
+}).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;
@@ -961,6 +923,10 @@ var projectUpsertInputSchema = z3.object({
   project: projectNameSchema,
   request: projectUpsertRequestSchema
 });
+var projectPatchInputSchema = z3.object({
+  project: projectNameSchema,
+  request: projectPatchRequestSchema
+});
 var applyConfigInputSchema = z3.object({
   config: projectConfigSchema
 });
@@ -983,6 +949,10 @@ var doctorInputSchema = z3.object({
   project: projectNameSchema.optional().describe("Project name to scope project-level checks. Omit to run global checks (provider keys, config, etc.)."),
   checks: z3.array(z3.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 statusInputSchema = z3.object({
+  project: projectNameSchema.optional().describe("Optional project name. Omit to read every visible project."),
+  problems: z3.boolean().optional().describe("Return only failing, stale, or never-synced projects and integrations.")
+});
 var contentTargetsInputSchema = z3.object({
   project: projectNameSchema,
   limit: z3.number().int().positive().max(500).optional().describe("Max rows. Defaults to all. Use a small number (3-10) when summarizing for the user."),
@@ -1285,7 +1255,7 @@ var sentimentPreviewInputSchema = sentimentBackfillSelectionSchema.safeExtend({
   if (input.from && input.to && Date.parse(input.from) > Date.parse(input.to)) ctx.addIssue({ code: "custom", message: "from must be at or before to" });
 });
 var sentimentBackfillInputSchema = sentimentBackfillRequestSchema.extend({ project: projectNameSchema });
-var canonryMcpTools = [
+var rawCanonryMcpTools = [
   defineTool({
     name: "canonry_sentiment_settings",
     title: "Read sentiment readiness and settings",
@@ -1591,6 +1561,34 @@ var canonryMcpTools = [
       return client.getCompetitorLandscape(project, latestSweepUnlessPooled(query));
     }
   }),
+  defineTool({
+    name: "canonry_competitors_suggest",
+    title: "Suggest competitors from stored evidence",
+    description: "Read stored completed and partial answer evidence and rank possible direct competitors. Candidate naming and citation counts are separate, cited-only domains are excluded, listing and marketplace surfaces are excluded, and the response discloses the answer and sweep denominator. No provider, discovery, classifier, or write operation runs. A Simple project without a usable brand alias pools all query classes and echoes queryClass=all. Use the returned evidence and sample URLs to review a candidate before tracking it.",
+    access: "read",
+    tier: "setup",
+    inputSchema: competitorSuggestionsInputSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/projects/{name}/competitor-suggestions"],
+    handler: (client, input) => {
+      const { project, ...query } = input;
+      return client.suggestCompetitors(project, query);
+    }
+  }),
+  defineTool({
+    name: "canonry_competitors_change_preview",
+    title: "Preview competitor change impact",
+    description: "Preview the stored-evidence share impact of one explicit competitor add, remove, replace, or curated alias change. It reads the latest completed or partial sweep and never writes competitors, aliases, history, or provider state. Use this before a separate write when an operator wants the before and after denominator and percentage-point delta. Ordinary competitor writes do not call this implicitly.",
+    access: "read",
+    tier: "setup",
+    inputSchema: competitorChangePreviewInputSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["POST /api/v1/projects/{name}/competitor-changes/preview"],
+    handler: (client, input) => {
+      const { project, ...request } = input;
+      return client.previewCompetitorChange(project, request);
+    }
+  }),
   defineTool({
     name: "canonry_search",
     title: "Search project (composite)",
@@ -1617,10 +1615,22 @@ var canonryMcpTools = [
     openApiOperations: ["GET /api/v1/doctor", "GET /api/v1/projects/{name}/doctor"],
     handler: (client, input) => client.runDoctor({ project: input.project, checkIds: input.checks, ...input.reportMonth ? { reportMonth: input.reportMonth } : {} })
   }),
+  defineTool({
+    name: "canonry_status",
+    title: "Read integration status",
+    description: "Read stored synchronization status for one project or the instance. This is a read-only local database read and never calls providers or runs doctor checks.",
+    access: "read",
+    tier: "core",
+    inputSchema: statusInputSchema,
+    outputSchema: instanceStatusDtoSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/status"],
+    handler: (client, input) => client.getStatus({ project: input.project, problems: input.problems })
+  }),
   defineTool({
     name: "canonry_project_export",
     title: "Export project config",
-    description: "Export a Canonry project in config-as-code format.",
+    description: "Export a Canonry project in config-as-code format. Notification webhook URLs are always redacted for MCP.",
     access: "read",
     tier: "setup",
     inputSchema: projectInputSchema,
@@ -1652,6 +1662,10 @@ var canonryMcpTools = [
       limit: input.limit,
       offset: input.offset,
       since: input.since,
+      until: input.until,
+      actionPrefix: input.actionPrefix,
+      excludeEntityTypes: input.excludeEntityTypes,
+      entityId: input.entityId,
       action: input.action,
       actor: input.actor,
       entityType: input.entityType
@@ -1671,13 +1685,13 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_runs_list",
     title: "List project runs",
-    description: "List runs for a Canonry project. Includes both real runs (trigger='manual'/'scheduled'/'config-apply'/'backfill') AND probe runs (trigger='probe'). Probe runs are operator/agent test runs that don't influence dashboard, analytics, intelligence, or notifications \u2014 filter by `trigger !== 'probe'` if you only want runs that feed project metrics. Narrow with `kind` and/or `status` (e.g. status='running' lists only in-flight work). Use `excludeKind` or `excludeKinds` to remove kinds before applying the limit.",
+    description: "List runs for a Canonry project. Includes both real runs (trigger='manual'/'scheduled'/'config-apply'/'backfill') AND probe runs (trigger='probe'). Probe runs are operator/agent test runs that don't influence dashboard, analytics, intelligence, or notifications; filter by `trigger !== 'probe'` if you only want runs that feed project metrics. Narrow with `kind` and/or `status` (e.g. status='running' lists only in-flight work). Use `excludeKind` or `excludeKinds` to remove kinds before applying the limit. `since` bounds creation time; omitting limit returns every matching run.",
     access: "read",
     tier: "monitoring",
     inputSchema: runsListInputSchema,
     annotations: readAnnotations(),
     openApiOperations: ["GET /api/v1/projects/{name}/runs"],
-    handler: (client, input) => client.listRuns(input.project, input.limit, input.kind, input.status, input.excludeKind, input.excludeKinds)
+    handler: (client, input) => client.listRuns(input.project, input.limit, input.kind, input.status, input.excludeKind, input.excludeKinds, input.since)
   }),
   defineTool({
     name: "canonry_runs_latest",
@@ -1969,7 +1983,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_queries_list",
     title: "List queries",
-    description: "List tracked queries for a Canonry project.",
+    description: "List tracked queries for a Canonry project. Each row carries queryClass as the server classes it: branded, non-brand, or null when no single class exists (no usable brand name, or the active measurement plan holds no single class for the query). A row with no queryClass comes from a server older than the field: the class is unknown, not null. Never infer a class from the query text.",
     access: "read",
     tier: "setup",
     inputSchema: projectInputSchema,
@@ -2264,11 +2278,11 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_bing_coverage",
     title: "Get Bing coverage",
-    description: "Read stored Bing index coverage counts and URL inspections for a Canonry project. Preserves indexed, not indexed and unknown evidence, the server percentage and last inspection time. Project-wide for Simple and Advanced portfolios; Property, Target and market attribution are unavailable. Requires the existing Bing connection. Never calls Bing or starts a sync.",
-    access: "read",
+    description: "Read Bing index coverage counts and URL inspections for a Canonry project. The route records an idempotent daily coverage snapshot while returning the result, but does not call Bing or start a sync. Preserves indexed, not indexed and unknown evidence, the server percentage and last inspection time. Project-wide for Simple and Advanced portfolios; Property, Target and market attribution are unavailable. Requires the existing Bing connection.",
+    access: "write",
     tier: "bing",
     inputSchema: projectInputSchema,
-    annotations: readAnnotations(),
+    annotations: writeAnnotations({ idempotentHint: true }),
     openApiOperations: ["GET /api/v1/projects/{name}/bing/coverage"],
     handler: (client, input) => client.bingCoverage(input.project)
   }),
@@ -2316,6 +2330,20 @@ var canonryMcpTools = [
     openApiOperations: ["GET /api/v1/projects/{name}/ga/properties"],
     handler: (client, input) => client.gaProperties(input.project)
   }),
+  defineTool({
+    name: "canonry_ga_acquisition",
+    title: "Read stored GA4 acquisition",
+    description: "Read stored GA4 sessions by day, channel, source/medium, host and normalized landing page. Sessions only; totalSessions is the full filtered total, independent of grouping and pagination. No Google calls. Project-only attribution; stored rows cannot distinguish an older connected GA4 property. Meaningful page query parameters remain distinct.",
+    access: "read",
+    tier: "ga",
+    inputSchema: gaAcquisitionQuerySchema.extend({ project: projectNameSchema, limit: z3.number().int().min(1).max(500).optional() }),
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/projects/{name}/ga/acquisition"],
+    handler: (client, input) => {
+      const { project, ...query } = input;
+      return client.gaAcquisition(project, query);
+    }
+  }),
   defineTool({
     name: "canonry_ga_measurement_analysis",
     title: "Analyze GA acquisition and search demand",
@@ -2462,7 +2490,7 @@ var canonryMcpTools = [
     access: "write",
     tier: "gbp",
     inputSchema: gbpDiscoverInputSchema,
-    annotations: writeAnnotations({ idempotentHint: true }),
+    annotations: writeAnnotations({ idempotentHint: true, openWorldHint: true }),
     openApiOperations: ["POST /api/v1/projects/{name}/gbp/locations/discover"],
     handler: (client, input) => client.discoverGbpLocations(input.project, {
       selectAllNew: input.selectAllNew,
@@ -2500,7 +2528,7 @@ var canonryMcpTools = [
     access: "write",
     tier: "gbp",
     inputSchema: gbpSyncInputSchema,
-    annotations: writeAnnotations({ idempotentHint: true }),
+    annotations: writeAnnotations({ idempotentHint: true, openWorldHint: true }),
     openApiOperations: ["POST /api/v1/projects/{name}/gbp/sync"],
     handler: (client, input) => client.triggerGbpSync(input.project, {
       locationNames: input.locationNames,
@@ -2654,6 +2682,20 @@ var canonryMcpTools = [
       return client.trafficReferralAssessment(project, query);
     }
   }),
+  defineTool({
+    name: "canonry_traffic_samples",
+    title: "Read stored traffic samples",
+    description: "Read the stored sampled tail of server-side traffic with 30-day retention. Sample rows are not a count of visits. Default kind excludes unknown requests. Project/source only; Property, Target and market dimensions are unavailable. No provider call or write.",
+    access: "read",
+    tier: "traffic",
+    inputSchema: trafficSamplesQuerySchema.extend({ project: projectNameSchema }),
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/projects/{name}/traffic/samples"],
+    handler: (client, input) => {
+      const { project, ...query } = input;
+      return client.trafficListSamples(project, query);
+    }
+  }),
   defineTool({
     name: "canonry_traffic_events",
     title: "List traffic events",
@@ -2762,10 +2804,21 @@ var canonryMcpTools = [
     openApiOperations: ["PUT /api/v1/projects/{name}"],
     handler: (client, input) => client.putProject(input.project, input.request)
   }),
+  defineTool({
+    name: "canonry_project_update",
+    title: "Update project fields",
+    description: "Update named fields on an existing Canonry project with PATCH semantics. Omitted fields keep their stored values, measurement merges one level, and expectedConfigRevision prevents overwriting a newer edit. Prefer this for targeted changes over canonry_project_upsert.",
+    access: "write",
+    tier: "setup",
+    inputSchema: projectPatchInputSchema,
+    annotations: writeAnnotations({ idempotentHint: true }),
+    openApiOperations: ["PATCH /api/v1/projects/{name}"],
+    handler: (client, input) => client.patchProject(input.project, input.request)
+  }),
   defineTool({
     name: "canonry_apply_config",
     title: "Apply project config",
-    description: "Apply one Canonry config-as-code project document. Replaces the project to match the config; fields omitted from the spec are reset to defaults, with these exceptions: a spec with neither queries nor keywords leaves the tracked-query basket unchanged (to clear the basket, pass an explicit empty queries list); an omitted providerDispatchModes keeps the stored preference; an omitted qualifiedAliases keeps the stored list, minus names that no longer qualify (a removed alias, a spelling of the display name, or a competitor's name); send [] to clear it; and a competitor given as a plain domain keeps its stored curated aliases, while `{ domain, aliases }` sets them exactly (`[]` clears). A spec identity that claims a competitor's alias drops that alias (audited); a new competitor whose name overlaps another competitor's alias (one brand key contains the other) or that is the project's own site fails the apply. An omitted siteAuditMaxPages keeps the stored Site Health page budget (null means the full site). An omitted competitorAutoAliases keeps the stored answer-derived competitor alias mode (off, preview or apply). For multi-document YAML, call this tool once per project document.",
+    description: "Apply one Canonry config-as-code project document. Replaces the project to match the config; fields omitted from the spec are reset to defaults, with these exceptions: a spec with neither queries nor keywords leaves the tracked-query basket unchanged (to clear the basket, pass an explicit empty queries list); an omitted providerDispatchModes keeps the stored preference; an omitted qualifiedAliases keeps the stored list, minus names that no longer qualify (a removed alias, a spelling of the display name, or a competitor's name); send [] to clear it; and a competitor given as a plain domain keeps its stored curated aliases, while `{ domain, aliases }` sets them exactly (`[]` clears). A spec identity that claims a competitor's alias drops that alias (audited); a new competitor whose name overlaps another competitor's alias (one brand key contains the other) or that is the project's own site fails the apply. An omitted siteAuditMaxPages keeps the stored Site Health page budget (null means the full site). An omitted competitorAutoAliases keeps the stored answer-derived competitor alias mode (off, preview or apply). For multi-document YAML, call this tool once per project document. Call canonry_apply_config_preview first.",
     access: "write",
     tier: "core",
     inputSchema: applyConfigInputSchema,
@@ -2774,6 +2827,17 @@ var canonryMcpTools = [
     openApiOperations: ["POST /api/v1/apply"],
     handler: (client, input) => client.apply(input.config)
   }),
+  defineTool({
+    name: "canonry_apply_config_preview",
+    title: "Preview project config apply",
+    description: "Preview one Canonry config-as-code project document. Returns per-field and child-resource changes with notification hosts only; the server resolves notification DNS to preserve the real apply verdict, then rolls back the transaction before responding, so no database writes, audit rows, or callbacks persist.",
+    access: "read",
+    tier: "core",
+    inputSchema: applyConfigInputSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["POST /api/v1/apply/preview"],
+    handler: (client, input) => client.previewApply(input.config)
+  }),
   defineTool({
     name: "canonry_queries_generate",
     title: "Generate query suggestions",
@@ -3275,14 +3339,15 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_queries_add",
     title: "Add queries",
-    description: "Append tracked queries to a Canonry project; existing queries are skipped by the API.",
+    description: "Append tracked queries to a Canonry project; existing queries are skipped by the API. Returns queryClasses: each requested query with the class the server gave it (branded, non-brand, or null when no single class exists). An entry with no queryClass means the server did not report one.",
     access: "write",
     tier: "setup",
     inputSchema: queriesInputSchema,
     annotations: writeAnnotations({ idempotentHint: true }),
     openApiOperations: ["POST /api/v1/projects/{name}/queries"],
     handler: async (client, input) => {
-      await client.appendQueries(input.project, uniqueStrings(input.request.queries));
+      const queries = uniqueStrings(input.request.queries);
+      return { ok: true, queryClasses: reportedQueryClasses(queries, await client.appendQueries(input.project, queries)) };
     }
   }),
   defineTool({
@@ -3327,20 +3392,18 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_competitors_add",
     title: "Add competitors",
-    description: "Add tracked competitor domains to a Canonry project. Each entry is a domain, or `{ domain, aliases }` to also add curated answer-text names to that competitor (tracked already or not; existing aliases are kept, the same rules as canonry_competitors_aliases_set apply). A new domain whose name overlaps another competitor's curated alias, or the label or a curated alias of a competitor an Advanced market pins (one brand key contains the other, so the alias \"Tune\" claims tunespoke.example), is rejected until that name is removed, and so is the project's own site. Already tracked domains (any spelling) are skipped.",
+    description: "Use canonry_competitors_change_preview to inspect the stored share impact before this separate write. Measured projects require `acknowledgeBulkAdd: true` when new domains plus recent additions exceed the shared five-domain, 24-hour guard. Review with canonry_competitors_suggest or canonry_competitors_change_preview first; the built-in agent cannot acknowledge bulk growth. Add tracked competitor domains to a Canonry project. Each entry is a domain, or `{ domain, aliases }` to also add curated answer-text names to that competitor (tracked already or not; existing aliases are kept, the same rules as canonry_competitors_aliases_set apply). A new domain whose name overlaps another competitor's curated alias, or the label or a curated alias of a competitor an Advanced market pins (one brand key contains the other, so the alias \"Tune\" claims tunespoke.example), is rejected until that name is removed, and so is the project's own site. Already tracked domains (any spelling) are skipped.",
     access: "write",
     tier: "setup",
     inputSchema: competitorsAddInputSchema,
     annotations: writeAnnotations({ idempotentHint: true }),
     openApiOperations: ["POST /api/v1/projects/{name}/competitors"],
-    handler: async (client, input) => {
-      await client.appendCompetitors(input.project, input.request.competitors);
-    }
+    handler: (client, input) => client.appendCompetitors(input.project, input.request.competitors, { acknowledgeBulkAdd: input.request.acknowledgeBulkAdd })
   }),
   defineTool({
     name: "canonry_competitors_aliases_set",
     title: "Set competitor aliases",
-    description: 'Set one tracked competitor\'s operator-curated aliases exactly (`[]` clears): the brand names it goes by in answer text when they differ from its domain, e.g. "TuneSpoke" for spoketuneworks.example or a 3-letter brand the domain label floor drops. Every competitor mention matcher (mention share, competitor landscape, mention gaps, run and history signals) uses them on stored answers at read time. Rejected: aliases under 3 letters or digits, over 80 characters, more than 10, or whose brand key contains, or sits inside, one of the project\'s own names or hosts or a name another tracked competitor answers to (its aliases, domain label or written host), because answers may split or join the words: "Tune" cannot belong to one competitor while another answers to "Tune Spoke", "TuneSpoke" or tunespoke.example, and joined-word lookalikes ("Tune" and "Tuner") are refused too. A competitor an Advanced market pins (active revision, pending draft, or a superseded revision the project\'s runs were measured under) counts as another competitor. Names detected automatically from stored answers (`autoAliases`) are matched the same way; a curated alias always wins, so an auto name the new list overlaps is dropped. Idempotent; returns the competitor.',
+    description: 'Use canonry_competitors_change_preview to inspect the stored share impact before this separate write. Set one tracked competitor\'s operator-curated aliases exactly (`[]` clears): the brand names it goes by in answer text when they differ from its domain, e.g. "TuneSpoke" for spoketuneworks.example or a 3-letter brand the domain label floor drops. Every competitor mention matcher (mention share, competitor landscape, mention gaps, run and history signals) uses them on stored answers at read time. Rejected: aliases under 3 letters or digits, over 80 characters, more than 10, or whose brand key contains, or sits inside, one of the project\'s own names or hosts or a name another tracked competitor answers to (its aliases, domain label or written host), because answers may split or join the words: "Tune" cannot belong to one competitor while another answers to "Tune Spoke", "TuneSpoke" or tunespoke.example, and joined-word lookalikes ("Tune" and "Tuner") are refused too. A competitor an Advanced market pins (active revision, pending draft, or a superseded revision the project\'s runs were measured under) counts as another competitor. Names detected automatically from stored answers (`autoAliases`) are matched the same way; a curated alias always wins, so an auto name the new list overlaps is dropped. Idempotent; returns the competitor.',
     access: "write",
     tier: "setup",
     inputSchema: competitorAliasesInputSchema,
@@ -3362,7 +3425,7 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_competitors_auto_aliases_apply",
     title: "Apply competitor auto-aliases",
-    description: "Run automatic competitor alias detection now from the project's stored answers and store the result, whatever the project's competitorAutoAliases mode (a one-off apply; a project in `apply` mode also gets this pass after every completed or partial sweep, a competitor add, an unblock and a market pin write that changes the pins). Stored names restate history at read time: every period's competitor counts change, and so does share of voice for a tracked competitor; competitorIdentityChangedAt on the landscape, project-frame visibility-compare and analytics metrics marks when. Idempotent: unchanged answers write nothing. Curated aliases and blocked names always win. A change is audited as the system pass plus competitors.auto-aliases-apply-requested naming who asked. Not available to the built-in Aero agent. Returns what was stored, per competitor, with evidence.",
+    description: "Use canonry_competitors_auto_aliases_detect first to preview names and their stored share impact. Run automatic competitor alias detection now from the project's stored answers and store the result, whatever the project's competitorAutoAliases mode (a one-off apply; a project in `apply` mode also gets this pass after every completed or partial sweep, a competitor add, an unblock and a market pin write that changes the pins). Stored names restate history at read time: every period's competitor counts change, and so does share of voice for a tracked competitor; competitorIdentityChangedAt on the landscape, project-frame visibility-compare and analytics metrics marks when. Idempotent: unchanged answers write nothing. Curated aliases and blocked names always win. A change is audited as the system pass plus competitors.auto-aliases-apply-requested naming who asked. Not available to the built-in Aero agent. Returns what was stored, per competitor, with evidence.",
     access: "write",
     tier: "setup",
     inputSchema: projectInputSchema,
@@ -3395,15 +3458,13 @@ var canonryMcpTools = [
   defineTool({
     name: "canonry_competitors_remove",
     title: "Remove competitors",
-    description: "Remove tracked competitor domains from a Canonry project.",
+    description: "Use canonry_competitors_change_preview to inspect the stored share impact before this separate write. Remove tracked competitor domains from a Canonry project.",
     access: "write",
     tier: "setup",
     inputSchema: competitorsInputSchema,
     annotations: writeAnnotations({ idempotentHint: true, destructiveHint: true }),
     openApiOperations: ["DELETE /api/v1/projects/{name}/competitors"],
-    handler: async (client, input) => {
-      await client.deleteCompetitors(input.project, uniqueStrings(input.request.competitors));
-    }
+    handler: (client, input) => client.deleteCompetitors(input.project, uniqueStrings(input.request.competitors))
   }),
   defineTool({
     name: "canonry_schedule_set",
@@ -4433,29 +4494,24 @@ var canonryMcpTools = [
     access: "write",
     tier: "ads",
     inputSchema: projectInputSchema,
-    annotations: writeAnnotations({ idempotentHint: true }),
+    annotations: writeAnnotations({ idempotentHint: true, openWorldHint: true }),
     openApiOperations: ["POST /api/v1/projects/{name}/ads/sync"],
     handler: (client, input) => client.triggerAdsSync(input.project)
   })
 ];
+var canonryMcpTools = rawCanonryMcpTools.map((tool) => {
+  if (tool.access !== "read" || toolOperationAccess(tool) !== OperationAccesses.live) return tool;
+  return { ...tool, annotations: { ...tool.annotations, openWorldHint: true } };
+});
 var CanonryMcpToolNames = Object.freeze(
   Object.fromEntries(canonryMcpTools.map((tool) => [tool.name, tool.name]))
 );
 
 export {
-  CANONRY_DISCORD_URL,
-  CANONRY_ISSUES_URL,
-  isMachineFormat,
-  EXIT_USER_ERROR,
-  EXIT_SYSTEM_ERROR,
-  CliError,
-  usageError,
-  isEndpointMissing,
-  systemError,
-  printCliError,
   PACKAGE_VERSION,
   measurementDraftOperationSchema,
   runMeasurementDraftAction,
+  toolOperationAccess,
   canonryMcpTools,
   CanonryMcpToolNames
 };