@ainyc/canonry 3.3.3 → 3.3.9

package/assets/agent-workspace/skills/aero/references/reporting.md

@@ -5,6 +5,26 @@ description: Weekly and monthly report templates with metric tables, regression/
 
 # Reporting Templates
 
+## One-Command HTML Report
+
+When a client asks for a "current state" or "AEO report" without a specific custom narrative, prefer the bundled report instead of hand-rolling sections:
+
+```bash
+canonry report <project>                          # writes canonry-report-<project>-YYYY-MM-DD.html in cwd
+canonry report <project> --output dist/aeo.html   # custom path
+canonry report <project> --format json            # raw payload, useful for narrating in chat
+```
+
+The HTML is self-contained (inline CSS + SVG charts, no network dependencies) and covers: executive summary, per-keyword × per-provider citation matrix, competitor landscape, AI source origin, GSC + GA4 performance, social and AI referrals, indexing health, citations trend, prioritized insights, and recommended next steps. Same payload is available via `GET /api/v1/projects/<name>/report` and the `canonry_report` MCP tool — use `--format json` when you want to summarize specific numbers in a thread instead of attaching the file.
+
+Behaviors worth knowing before narrating numbers from the report:
+- `executiveSummary.citationRate` is always sourced from the latest visibility run (completed **or** partial), so it tracks the scorecard table even when the latest sweep had a flaky provider.
+- `citationsTrend` excludes partial runs. A project with only one completed run shows `trend: "unknown"` — never claim a comparison that isn't there.
+- Project ownership and competitor tagging use subdomain-aware matching: `blog.example.com` counts as the project when `example.com` is the canonical domain or in `ownedDomains`; `blog.rival.com` is tagged `isCompetitor: true` when `rival.com` is tracked.
+- AI referral totals dedupe overlapping GA4 attribution dimensions (`session` / `first_user` / `manual_utm`).
+
+The hand-rolled templates below are still the right call when the user wants a focused weekly/monthly digest with custom regression and gain narratives that the bundled report doesn't surface.
+
 ## Weekly Report
 
 ```

package/assets/agent-workspace/skills/canonry-setup/SKILL.md

@@ -60,7 +60,7 @@ A canonry engagement follows the same loop regardless of project size:
 2. **Prioritize** — Triage by impact: indexing gaps → schema gaps → content gaps → keyphrase strategy. Branded-term losses are urgent.
 3. **Execute** — Apply fixes via the canonry CLI or platform integrations. See `references/canonry-cli.md` for the full command catalog and `references/wordpress-integration.md` for the WordPress workflow.
 4. **Monitor** — Re-run sweeps weekly. Correlate visibility shifts with deployments and competitor moves.
-5. **Report** — Lead with data, not interpretation: "Lost `<keyword>` on Gemini between <date> and <date> — two competitors moved in. Here's what to fix."
+5. **Report** — Lead with data, not interpretation: "Lost `<keyword>` on Gemini between <date> and <date> — two competitors moved in. Here's what to fix." For a one-command client-facing summary, run `canonry report <project>` to generate a self-contained HTML bundle (executive summary, citation scorecard, competitor landscape, GSC + GA4 performance, insights). Same payload is available via `--format json` and the `canonry_report` MCP tool.
 
 ## Common Starting Points
 

package/assets/agent-workspace/skills/canonry-setup/references/canonry-cli.md

@@ -84,6 +84,24 @@ Output shows:
 - `✗ not-cited` — domain did not appear
 - Summary: `Cited: X / Y`
 
+## Reports
+
+```bash
+canonry report <project>                          # write canonry-report-<project>-YYYY-MM-DD.html
+canonry report <project> --output dist/aeo.html   # custom path
+canonry report <project> --format json            # raw report payload to stdout
+```
+
+One-command client-facing AEO report. Bundles the latest visibility sweep, competitor landscape, AI source origin, GSC + GA4 performance, social and AI referrals, indexing health, citations trend, prioritized insights, and recommended next steps into a self-contained HTML file (inline CSS + SVG charts, no network dependencies). Backed by `GET /api/v1/projects/<name>/report` and the `canonry_report` MCP tool.
+
+Behavior to know when narrating numbers from the report:
+- `executiveSummary.citationRate` is sourced from the latest visibility run (completed **or** partial), so it always matches the scorecard table.
+- `citationsTrend` excludes partial runs to avoid skew. A project with only one completed run gets `trend: "unknown"` and the finding "No prior run to compare against." — not "Flat compared to the previous run."
+- Project ownership uses subdomain-aware matching against `project.canonicalDomain` plus any configured `ownedDomains`. `blog.example.com` and `brand.io` count as the project, not as external sources, when those rules apply.
+- Competitor tagging in `aiSourceOrigin.topDomains` uses the same subdomain-aware match — `blog.rival.com` is `isCompetitor: true` when `rival.com` is tracked.
+- AI referral totals dedupe overlapping GA4 attribution dimensions (`session` / `first_user` / `manual_utm`) by picking the largest dimension per `(date, source, medium)`. Two 10-session rows for the same tuple report 10 sessions, not 20.
+- GSC top-query CTR and avgPosition are impression-weighted, matching GSC's own metric semantics across multi-row queries.
+
 ## Analytics
 
 ```bash

package/dist/{chunk-NCGX6UI4.js → chunk-24C7RMIS.js}

@@ -2677,6 +2677,9 @@ var ApiClient = class {
       `/projects/${encodeURIComponent(project)}/search?${params.toString()}`
     );
   }
+  async getReport(project) {
+    return this.request("GET", `/projects/${encodeURIComponent(project)}/report`);
+  }
   async runDoctor(opts = {}) {
     const qs = opts.checkIds && opts.checkIds.length > 0 ? `?check=${encodeURIComponent(opts.checkIds.join(","))}` : "";
     const path2 = opts.project ? `/projects/${encodeURIComponent(opts.project)}/doctor${qs}` : `/doctor${qs}`;
@@ -2952,6 +2955,17 @@ var canonryMcpTools = [
     openApiOperations: ["GET /api/v1/projects/{name}/overview"],
     handler: (client, input) => client.getProjectOverview(input.project)
   }),
+  defineTool({
+    name: "canonry_report",
+    title: "Get aggregated AEO report",
+    description: "Returns the full client-facing AEO report bundle for a project \u2014 executive summary, per-keyword \xD7 per-provider citation matrix, competitor landscape, AI source origin, GSC/GA4 performance, social and AI referrals, indexing health, citations trend, prioritized insights, and recommended next steps. Same payload `canonry report <project>` consumes to render the self-contained HTML.",
+    access: "read",
+    tier: "monitoring",
+    inputSchema: projectInputSchema,
+    annotations: readAnnotations(),
+    openApiOperations: ["GET /api/v1/projects/{name}/report"],
+    handler: (client, input) => client.getReport(input.project)
+  }),
   defineTool({
     name: "canonry_search",
     title: "Search project (composite)",