@ainyc/canonry 4.72.2 → 4.72.4

package/assets/agent-workspace/skills/canonry/references/aeo-analysis.md

@@ -53,7 +53,7 @@ Shows which source categories AI models cite for your queries. Helps identify:
 - Content format opportunities (FAQ, how-to, comparison pages)
 
 ### Winnability gate + briefs (`canonry content targets|map|brief`)
-Every content target carries a deterministic `winnabilityClass`: **ownable** (worth writing for) or **ceded** (the cited surface is dominated by aggregators/OTAs or editorial media — a head term first-party content cannot realistically win). It is derived (no LLM) from the discovery domain classifier, so **run `canonry discover run` first** to populate it; with no classifications every target fails open to `ownable`. `canonry doctor --project <project> --check content.winnability.coverage` reports whether the cited-surface domains behind the gate have enough discovery coverage.
+Every content target carries a deterministic `winnabilityClass`: **ownable** (worth writing for) or **ceded** (the cited surface is dominated by aggregators/OTAs or editorial media, a head term first-party content cannot realistically win). It is derived (no LLM) by classifying each cited domain through the shared surface classifier (own > tracked competitor > stored discovery class > static allow-list), so well-known aggregators/editorial cede immediately, no discovery run required. **`canonry discover run`** improves recall for niche domains the allow-list misses; a target only fails open to `ownable` when none of its cited surface is recognized. `canonry doctor --project <project> --check content.winnability.coverage` reports recognized-coverage of the cited surface and, when the project has no ICP, nudges you to set one (discovery needs it).
 - `canonry content targets <project> --ownable` — the winnable shortlist (ownable rows sort first by default).
 - `canonry content map <project>` — the winnability map: which cited surfaces are ceded vs the ranked ownable targets.
 - `canonry content brief <project> <targetRef>` — synthesize a structured brief (angle, why-winnable, schema hookup) for an **ownable** target. Ceded targets are rejected — don't chase them.

package/assets/agent-workspace/skills/canonry/references/server-side-traffic.md

@@ -66,8 +66,45 @@ sync flow does NOT echo the private key back in any response.
 ## Connecting a WordPress source
 
 The WordPress adapter pulls events from the **Canonry Traffic Logger**
-WordPress plugin, which captures every non-admin GET page-load and
-exposes a paginated REST endpoint protected by an Application Password.
+WordPress plugin, which captures every non-admin GET page-load **that
+reaches PHP** and exposes a paginated REST endpoint protected by an
+Application Password.
+
+> **Cache blind spot.** The plugin is a PHP hook, so it only sees
+> requests that execute WordPress. A full-page cache (LiteSpeed, WP
+> Rocket, W3 Total Cache, WP Super Cache) or CDN serves cached pages
+> before PHP runs, so cache-served page views, including live AI
+> user-fetches (Claude-User, ChatGPT-User), are NOT logged. Bot crawls
+> of uncached endpoints (sitemap, feeds, assets, cache misses) still
+> come through, which can make capture look healthy while real page
+> views go uncounted. Exclude AI user-agents from the cache (and any
+> CDN), or capture from access/edge logs instead. The
+> `traffic.source.cache-blindspot` doctor check warns whenever a
+> WordPress source is connected.
+
+**Which user-agents to exclude from the cache** (one per line in
+LiteSpeed's "Do Not Cache User Agents", WP Rocket's
+`rocket_cache_reject_ua`, or W3TC / WP Super Cache "Rejected User
+Agents"):
+
+```
+Claude-User
+ClaudeBot
+ChatGPT-User
+OAI-SearchBot
+GPTBot
+PerplexityBot
+Perplexity-User
+```
+
+These are the answer-engine fetchers in both live-user-fetch (`*-User`)
+and crawler forms. Do NOT add `Googlebot` or `Bingbot`: caching helps
+search crawlers (page speed is a ranking signal, and cached pages let
+them crawl more per visit, which matters most on crawl-budget-starved
+sites), and their crawl stats are already authoritative in GSC and Bing
+Webmaster Tools. Rule of thumb: bypass cache only for agents you cannot
+measure elsewhere and that gain nothing from being cached. Answer-engine
+fetchers fit both; search crawlers fit neither.
 
 ```bash
 # 1. Install the plugin. Download the latest release zip from the
@@ -223,7 +260,7 @@ MCP `canonry_traffic_status` tool.
 | Project dashboard `/projects/:name/activity` | Live source table + 24h totals + GA4 referrals (combined view) |
 | Top-level `/traffic` route | Cross-project source admin (connect, sync, archive) |
 | `cnry report <project>` (HTML + SPA) | "AI Visibility — Server-Side" section, ranked above Indexing Health |
-| `cnry doctor --project <name>` | `traffic.source.connected`, `recent-data`, `credentials`, `scopes` checks |
+| `cnry doctor --project <name>` | `traffic.source.connected`, `recent-data`, `credentials`, `scopes`, `cache-blindspot` checks |
 | MCP toolkit `traffic` | Tools: `canonry_traffic_status`, `_sources_list`, `_source_get`, `_events`, `_connect_cloud_run`, `_sync` |
 
 ## Doctor signals
@@ -237,6 +274,7 @@ The doctor checks are adapter-agnostic. When they fail or warn:
 | `traffic.source.recent-data` | `traffic.recent-data.stale` | Last sync was >7d ago. Run `cnry traffic sync …` or schedule a recurring sync. |
 | `traffic.source.recent-data` | `traffic.recent-data.empty` | Source connected but no data in 30d. Verify config and credentials with `cnry traffic sources <project>`. |
 | `traffic.source.credentials` | `traffic.credentials.resolve-failed` | Service-account key in `~/.canonry/config.yaml` is invalid or expired. Re-connect. |
+| `traffic.source.cache-blindspot` | `traffic.cache-blindspot.wordpress-plugin` | A WordPress source is connected, so the plugin cannot see cache-served page views. Exclude AI user-agents from the page cache and any CDN, or switch to a log/edge source. Warns only, not a failure. |
 
 ## Scheduling
 
@@ -276,6 +314,21 @@ domains, or PII are surfaced.
 
 ## Limits & caveats
 
+- **The WordPress plugin is blind to cache-served traffic.** The
+  `wordpress` adapter logs only requests that reach PHP. A full-page
+  cache or CDN serves cached pages from the edge, so cache-served page
+  views, including live AI user-fetches (Claude-User, ChatGPT-User),
+  never reach the plugin and go uncounted, even though bot crawls of
+  uncached endpoints (sitemap, assets) still appear. On a cached
+  WordPress site, treat the plugin's page-view counts as a floor, not a
+  total. Either exclude AI user-agents from the cache + CDN, or capture
+  cache-independent via a `cloud-run` / `vercel` / edge-log source. The
+  `traffic.source.cache-blindspot` doctor check surfaces this. Adapter
+  coverage differs: `vercel` ingests edge request-logs so cache hits are
+  captured (it records the `cache` HIT/MISS label), and `cloud-run` logs
+  every request that reaches the service, missing only what a CDN placed
+  in front of Cloud Run serves from its own edge cache. Only the
+  hook-based `wordpress` adapter has the always-present blind spot.
 - **Path-level citation cross-reference is not implemented yet.** The
   citation store is domain-grain (`query_snapshots.cited_domains`). A
   future iteration that lands URL-grain citation evidence will extend

package/dist/{chunk-J7SDOU2J.js → chunk-HOKVBMOD.js}

@@ -65,6 +65,7 @@ import {
   citationStateSchema,
   citationStateToCited,
   citationVisibilityResponseSchema,
+  classifyCitedSurface,
   classifySkillFile,
   classifySurfaceFromCategory,
   clusterByCosine,
@@ -222,7 +223,7 @@ import {
   wordpressSchemaDeployResultDtoSchema,
   wordpressSchemaStatusResultDtoSchema,
   wordpressStatusDtoSchema
-} from "./chunk-SJI6JGPN.js";
+} from "./chunk-JXFNERK4.js";
 
 // src/intelligence-service.ts
 import { eq as eq32, desc as desc16, asc as asc3, and as and23, ne as ne5, or as or5, inArray as inArray11, gte as gte6, lte as lte3 } from "drizzle-orm";
@@ -3636,7 +3637,12 @@ function buildContentTargetRows(input) {
       gscAvgPosition: cq.gscPosition,
       organicSessions: input.gaTrafficByPage.get(ourPage.url) ?? 0
     } : null;
-    const { winnabilityClass, winnability } = deriveWinnabilityClass(cq.citedSurfaceDomains, input.domainClasses);
+    const surfaceClasses = classifyCitedSurface(
+      cq.citedSurfaceDomains,
+      { projectDomains: [input.ownDomain], competitorDomains: input.competitors },
+      input.domainClasses
+    );
+    const { winnabilityClass, winnability } = deriveWinnabilityClass(cq.citedSurfaceDomains, surfaceClasses);
     rows.push({
       targetRef,
       query: cq.query,
@@ -29667,23 +29673,30 @@ var winnabilityCoverageCheck = {
         }
       };
     }
-    const coveredDomains = citedDomains.filter((domain) => input.domainClasses.has(domain));
-    const unclassifiedDomains = citedDomains.filter((domain) => !input.domainClasses.has(domain));
+    const surfaceClasses = classifyCitedSurface(
+      citedDomains.map((domain) => ({ domain })),
+      { projectDomains: [input.ownDomain], competitorDomains: input.competitors },
+      input.domainClasses
+    );
+    const coveredDomains = citedDomains.filter((domain) => surfaceClasses.has(domain));
+    const unclassifiedDomains = citedDomains.filter((domain) => !surfaceClasses.has(domain));
     const coverage = coveredDomains.length / citedDomains.length;
     const details = {
       citedSurfaceDomainCount: citedDomains.length,
-      classifiedDomainCount: input.domainClasses.size,
       coveredDomainCount: coveredDomains.length,
+      classifiedDomainCount: input.domainClasses.size,
       coverage,
       threshold: WINNABILITY_COVERAGE_WARN_THRESHOLD,
       unclassifiedDomains: unclassifiedDomains.slice(0, UNCLASSIFIED_DOMAIN_SAMPLE_LIMIT)
     };
+    const hasIcp = Boolean(project.icpDescription && project.icpDescription.trim().length > 0);
+    const discoverRemediation = hasIcp ? `Run \`canonry discover run ${ctx.project.name} --wait\` to classify the unrecognized domains before relying on ownable/ceded content targets.` : `This project has no ICP, which discovery requires. Run \`canonry discover run ${ctx.project.name} --icp "<who the project sells to>" --wait\` (or set \`spec.icpDescription\`) to classify the unrecognized domains.`;
     if (coveredDomains.length === 0) {
       return {
         status: CheckStatuses.warn,
         code: "content.winnability.no-classifications",
-        summary: `0 of ${citedDomains.length} cited-surface domain(s) have discovery classifications; the winnability gate is failing open.`,
-        remediation: `Run \`canonry discover run ${ctx.project.name} --wait\` to classify cited domains before trusting ownable/ceded content targets.`,
+        summary: `0 of ${citedDomains.length} cited-surface domain(s) are recognized (own/competitor/aggregator/editorial); the winnability gate is failing open.`,
+        remediation: discoverRemediation,
         details
       };
     }
@@ -29691,15 +29704,15 @@ var winnabilityCoverageCheck = {
       return {
         status: CheckStatuses.warn,
         code: "content.winnability.low-coverage",
-        summary: `${coveredDomains.length} of ${citedDomains.length} cited-surface domain(s) classified (${percent(coverage)}%); the winnability gate may miss ceded surfaces.`,
-        remediation: `Run \`canonry discover run ${ctx.project.name} --wait\` to raise classification coverage before relying on ownable/ceded content targets.`,
+        summary: `${coveredDomains.length} of ${citedDomains.length} cited-surface domain(s) recognized (${percent(coverage)}%); the winnability gate may miss ceded surfaces in the unrecognized tail.`,
+        remediation: discoverRemediation,
         details
       };
     }
     return {
       status: CheckStatuses.ok,
       code: "content.winnability.covered",
-      summary: `${coveredDomains.length} of ${citedDomains.length} cited-surface domain(s) classified (${percent(coverage)}%); the winnability gate is active.`,
+      summary: `${coveredDomains.length} of ${citedDomains.length} cited-surface domain(s) recognized (${percent(coverage)}%); the winnability gate is active.`,
       remediation: null,
       details
     };
@@ -30936,11 +30949,41 @@ var scopesCheck3 = {
     return summarizePerSourceResults("scopes", "scopes", results);
   }
 };
+var cacheBlindSpotCheck = {
+  id: "traffic.source.cache-blindspot",
+  category: CheckCategories.integrations,
+  scope: CheckScopes.project,
+  title: "WordPress traffic cache blind spot",
+  run: (ctx) => {
+    if (!ctx.project) return skippedNoProject4();
+    const wpSources = loadProbes(ctx).filter(
+      (s) => s.sourceType === TrafficSourceTypes.wordpress
+    );
+    if (wpSources.length === 0) {
+      return {
+        status: CheckStatuses.skipped,
+        code: "traffic.cache-blindspot.no-wordpress-source",
+        summary: "No WordPress traffic source connected, so the plugin cache blind spot does not apply (log and edge adapters see cache-served requests)."
+      };
+    }
+    return {
+      status: CheckStatuses.warn,
+      code: "traffic.cache-blindspot.wordpress-plugin",
+      summary: `${wpSources.length} WordPress traffic source(s) capture via the Canonry Traffic Logger plugin, which only logs requests that execute PHP. A full-page cache (LiteSpeed, WP Rocket, W3 Total Cache, WP Super Cache) or CDN serves cached pages before PHP runs, so cache-served page views, including live AI user-fetches such as Claude-User and ChatGPT-User, are not captured. Bot crawls of uncached endpoints (sitemap, feeds, assets, cache misses) still appear, which can make capture look healthy while real page views go uncounted.`,
+      remediation: 'Exclude AI user-agents from the page cache so their requests reach PHP: LiteSpeed Cache has "Do Not Cache User Agents" under Cache > Excludes; WP Rocket uses the `rocket_cache_reject_ua` filter; W3 Total Cache and WP Super Cache have a "Rejected User Agents" box. Mirror the rule at any CDN in front. For cache-independent capture, ingest from server or edge access logs (a `cloud-run` or `vercel` source, or an edge worker) instead of the WordPress plugin.',
+      details: {
+        wordpressSourceCount: wpSources.length,
+        wordpressSourceIds: wpSources.map((s) => s.id)
+      }
+    };
+  }
+};
 var TRAFFIC_SOURCE_CHECKS = [
   sourceConnectedCheck,
   recentDataCheck,
   credentialsCheck,
-  scopesCheck3
+  scopesCheck3,
+  cacheBlindSpotCheck
 ];
 
 // ../api-routes/src/doctor/checks/wordpress-publish.ts

package/dist/{chunk-SJI6JGPN.js → chunk-JXFNERK4.js}

@@ -1898,6 +1898,18 @@ function classifySurfaceFromCategory(domain, category, context, storedClass) {
       return SurfaceClasses.other;
   }
 }
+function classifyCitedSurface(domains, context, storedClasses) {
+  const out = /* @__PURE__ */ new Map();
+  for (const { domain } of domains) {
+    if (out.has(domain)) continue;
+    const stored = storedClasses?.get(domain);
+    const storedClass = stored ? surfaceClassFromCompetitorType(stored) : void 0;
+    const { category } = categorizeSource(domain);
+    const cls = classifySurfaceFromCategory(domain, category, context, storedClass);
+    if (cls !== SurfaceClasses.other) out.set(domain, cls);
+  }
+  return out;
+}
 
 // ../contracts/src/analytics.ts
 var metricsWindowSchema = z18.enum(["7d", "30d", "90d", "all"]);
@@ -2575,17 +2587,17 @@ function winnabilityClassLabel(winnabilityClass) {
   }
 }
 var CEDED_SURFACE_THRESHOLD = 0.6;
-function deriveWinnabilityClass(citedSurfaceDomains, domainClasses, threshold = CEDED_SURFACE_THRESHOLD) {
-  const hasCoverage = citedSurfaceDomains.some((d) => domainClasses.has(d.domain));
-  if (citedSurfaceDomains.length === 0 || domainClasses.size === 0 || !hasCoverage) {
+function deriveWinnabilityClass(citedSurfaceDomains, surfaceClasses, threshold = CEDED_SURFACE_THRESHOLD) {
+  const hasCoverage = citedSurfaceDomains.some((d) => surfaceClasses.has(d.domain));
+  if (citedSurfaceDomains.length === 0 || surfaceClasses.size === 0 || !hasCoverage) {
     return { winnabilityClass: WinnabilityClasses.ownable, winnability: null };
   }
   let total = 0;
   let ceded = 0;
   for (const { domain, citationCount } of citedSurfaceDomains) {
     total += citationCount;
-    const cls = domainClasses.get(domain);
-    if (cls === DiscoveryCompetitorTypes["ota-aggregator"] || cls === DiscoveryCompetitorTypes["editorial-media"]) {
+    const cls = surfaceClasses.get(domain);
+    if (cls === SurfaceClasses["ota-aggregator"] || cls === SurfaceClasses["editorial-media"]) {
       ceded += citationCount;
     }
   }
@@ -4331,6 +4343,7 @@ export {
   surfaceClassLabel,
   surfaceClassFromCompetitorType,
   classifySurfaceFromCategory,
+  classifyCitedSurface,
   brandMetricsDtoSchema,
   sourceBreakdownDtoSchema,
   parseWindow,

package/dist/{chunk-BRXQKUGY.js → chunk-SRBO33HB.js}

@@ -9,7 +9,7 @@ import {
   loadConfig,
   loadConfigRaw,
   saveConfigPatch
-} from "./chunk-NYZSY5QJ.js";
+} from "./chunk-ZUBBADMR.js";
 import {
   CC_CACHE_DIR,
   DUCKDB_SPEC,
@@ -95,7 +95,7 @@ import {
   runs,
   schedules,
   usageCounters
-} from "./chunk-J7SDOU2J.js";
+} from "./chunk-HOKVBMOD.js";
 import {
   AGENT_MEMORY_VALUE_MAX_BYTES,
   AGENT_PROVIDER_IDS,
@@ -145,7 +145,7 @@ import {
   validationError,
   winnabilityClassLabel,
   withRetry
-} from "./chunk-SJI6JGPN.js";
+} from "./chunk-JXFNERK4.js";
 
 // src/telemetry.ts
 import crypto from "crypto";
@@ -5620,7 +5620,7 @@ function readStoredGroundingSources(rawResponse) {
   return result;
 }
 async function backfillInsightsCommand(project, opts) {
-  const { IntelligenceService: IntelligenceService2 } = await import("./intelligence-service-JNF3JRFR.js");
+  const { IntelligenceService: IntelligenceService2 } = await import("./intelligence-service-CSW4R4I7.js");
   const config = loadConfig();
   const db = createClient(config.database);
   migrate(db);

package/dist/{chunk-NYZSY5QJ.js → chunk-ZUBBADMR.js}

@@ -22,7 +22,7 @@ import {
   trafficConnectVercelRequestSchema,
   trafficConnectWordpressRequestSchema,
   trafficEventKindSchema
-} from "./chunk-SJI6JGPN.js";
+} from "./chunk-JXFNERK4.js";
 
 // src/config.ts
 import fs from "fs";

package/dist/cli.js

@@ -27,7 +27,7 @@ import {
   setTelemetrySource,
   showFirstRunNotice,
   trackEvent
-} from "./chunk-BRXQKUGY.js";
+} from "./chunk-SRBO33HB.js";
 import {
   CliError,
   EXIT_SYSTEM_ERROR,
@@ -44,7 +44,7 @@ import {
   saveConfig,
   saveConfigPatch,
   usageError
-} from "./chunk-NYZSY5QJ.js";
+} from "./chunk-ZUBBADMR.js";
 import {
   apiKeys,
   createClient,
@@ -52,7 +52,7 @@ import {
   projects,
   queries,
   renderReportHtml
-} from "./chunk-J7SDOU2J.js";
+} from "./chunk-HOKVBMOD.js";
 import {
   CcReleaseSyncStatuses,
   CheckScopes,
@@ -71,7 +71,7 @@ import {
   providerQuotaPolicySchema,
   resolveProviderInput,
   winnabilityClassSchema
-} from "./chunk-SJI6JGPN.js";
+} from "./chunk-JXFNERK4.js";
 
 // src/cli.ts
 import { pathToFileURL } from "url";

package/dist/index.js

@@ -1,11 +1,11 @@
 import {
   createServer
-} from "./chunk-BRXQKUGY.js";
+} from "./chunk-SRBO33HB.js";
 import {
   loadConfig
-} from "./chunk-NYZSY5QJ.js";
-import "./chunk-J7SDOU2J.js";
-import "./chunk-SJI6JGPN.js";
+} from "./chunk-ZUBBADMR.js";
+import "./chunk-HOKVBMOD.js";
+import "./chunk-JXFNERK4.js";
 export {
   createServer,
   loadConfig

package/dist/{intelligence-service-JNF3JRFR.js → intelligence-service-CSW4R4I7.js}

@@ -1,7 +1,7 @@
 import {
   IntelligenceService
-} from "./chunk-J7SDOU2J.js";
-import "./chunk-SJI6JGPN.js";
+} from "./chunk-HOKVBMOD.js";
+import "./chunk-JXFNERK4.js";
 export {
   IntelligenceService
 };

package/dist/mcp.js

@@ -3,8 +3,8 @@ import {
   PACKAGE_VERSION,
   canonryMcpTools,
   createApiClient
-} from "./chunk-NYZSY5QJ.js";
-import "./chunk-SJI6JGPN.js";
+} from "./chunk-ZUBBADMR.js";
+import "./chunk-JXFNERK4.js";
 
 // src/mcp/cli.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainyc/canonry",
-  "version": "4.72.2",
+  "version": "4.72.4",
   "type": "module",
   "description": "Agent-first open-source AEO operating platform - track how answer engines cite your domain",
   "license": "FSL-1.1-ALv2",
@@ -62,24 +62,24 @@
     "@types/node-cron": "^3.0.11",
     "tsup": "^8.5.1",
     "tsx": "^4.19.0",
-    "@ainyc/canonry-api-routes": "0.0.0",
     "@ainyc/canonry-api-client": "0.0.0",
+    "@ainyc/canonry-api-routes": "0.0.0",
     "@ainyc/canonry-config": "0.0.0",
     "@ainyc/canonry-contracts": "0.0.0",
-    "@ainyc/canonry-db": "0.0.0",
     "@ainyc/canonry-integration-bing": "0.0.0",
-    "@ainyc/canonry-integration-commoncrawl": "0.0.0",
     "@ainyc/canonry-integration-cloud-run": "0.0.0",
+    "@ainyc/canonry-integration-commoncrawl": "0.0.0",
+    "@ainyc/canonry-db": "0.0.0",
     "@ainyc/canonry-integration-google": "0.0.0",
-    "@ainyc/canonry-integration-google-places": "0.0.0",
     "@ainyc/canonry-integration-google-business-profile": "0.0.0",
+    "@ainyc/canonry-integration-google-places": "0.0.0",
     "@ainyc/canonry-integration-wordpress": "0.0.0",
     "@ainyc/canonry-integration-traffic": "0.0.0",
     "@ainyc/canonry-intelligence": "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-provider-cdp": "0.0.0",
     "@ainyc/canonry-provider-openai": "0.0.0",
     "@ainyc/canonry-provider-perplexity": "0.0.0"
   },