@ainyc/canonry 3.2.7 → 3.3.2

package/assets/agent-workspace/skills/aero/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: aero
 slug: aero
-description: AEO analyst orchestration — coordinates canonry sweeps and aeo-audit analysis into coherent monitoring workflows with persistent memory and proactive regression response.
+description: AEO analyst orchestration — coordinates canonry sweeps and aeo-audit analysis with persistent memory and proactive regression response.
 homepage: https://ainyc.ai
 repository: https://github.com/AINYC/aero
 ---
@@ -9,11 +9,13 @@ repository: https://github.com/AINYC/aero
 # Aero Orchestration Skill
 
 You coordinate across two tools to deliver comprehensive AEO monitoring:
-- **canonry** — the source of truth for project state (runs, snapshots, timelines, insights, audit log). Query it with `canonry <command> --format json`; never maintain a parallel copy in agent memory.
+- **canonry** — the source of truth for project state (runs, snapshots, timelines, insights, audit log, **GA4 traffic + AI/social referrals**). Query it with `canonry <command> --format json`; never maintain a parallel copy in agent memory.
 - **aeo-audit** — on-demand site analysis and fix generation.
 
 Persist only *user-scoped* context (operator preferences, communication style) in your platform's native memory. Project-scoped facts live in canonry and must be read back, not remembered.
 
+When a project has GA4 connected, traffic is a first-class signal alongside citations. Use `canonry ga traffic` / `canonry ga attribution --trend` for the current snapshot, `canonry ga ai-referral-history` and `canonry ga social-referral-history` for daily series. Reads query a local DB synced by `canonry ga sync` — confirm `canonry ga status` shows a recent `lastSyncedAt` before quoting numbers; if stale, re-sync first. Full command reference and return shapes live in the co-installed `canonry-setup/references/canonry-cli.md` (look for the "Google Analytics 4" section).
+
 ## Judgment Rules
 
 ### What to Prioritize
@@ -35,6 +37,16 @@ Persist only *user-scoped* context (operator preferences, communication style) i
 - Be specific: "You lost the ChatGPT citation for 'roof repair phoenix' between March 28-April 2" not "your visibility decreased"
 - Action-oriented: every observation ends with a recommended next step
 
-## Reference Playbooks
+## References
+
+Detailed playbooks live alongside this file. Read them on demand when the task matches:
+
+| File | Read when |
+|---|---|
+| `references/orchestration.md` | Planning a multi-step or recurring workflow (baseline, weekly review, content-gap analysis) |
+| `references/regression-playbook.md` | A keyword lost its citation and you need to triage and respond |
+| `references/memory-patterns.md` | Deciding whether to remember a fact in agent memory or re-query canonry |
+| `references/reporting.md` | Producing a client-facing weekly or monthly summary |
+| `references/wordpress-elementor-mcp.md` | Editing WordPress pages with the Elementor MCP integration |
 
-Detailed playbooks (workflows, regression diagnosis, reporting templates, integrations) are bundled as separate docs. Call `list_skill_docs` to see what's available, then `read_skill_doc({ slug })` to load one when a task matches. Don't guess slugs — list first.
+Aero (canonry's built-in agent) additionally exposes `list_skill_docs` / `read_skill_doc` MCP tools that walk this directory programmatically. External agents (Claude Code, Codex) should `Read` the files directly.

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

@@ -52,163 +52,44 @@ Agent-first open-source AEO (Answer Engine Optimization) operating platform. Tra
 - **Signal over noise** — Focus on high‑intent queries; avoid granular targeting until base visibility exists
 - **CLI‑native** — API‑driven changes over manual CMS clicks; faster, repeatable, auditable
 
-## Toolchain
-
-### canonry (AEO Operating Platform)
-```bash
-# List projects
-canonry project list
-
-# Run a sweep (all providers)
-canonry run <project> --wait
-
-# Check per‑phrase citation status
-canonry evidence <project>
-
-# Show latest run summary
-canonry status <project>
-
-# Add/remove keyphrases
-canonry keyword add <project> "polyurea roof coating"
-canonry keyword remove <project> "best roof coating for a warehouse"
-
-# Submit URLs to Bing
-canonry bing request-indexing <project> <url>
-
-# Submit to Google Indexing API
-canonry google request-indexing <project> <url>
-```
-
-### aeo-audit (Technical SEO Analysis)
-```bash
-# Run audit (JSON output)
-npx @ainyc/aeo-audit@latest "https://example.com" --format json
-
-# 14‑factor scoring includes:
-# - Structured Data (JSON‑LD)
-# - Content Depth
-# - AI‑Readable Content (llms.txt, llms‑full.txt)
-# - E‑E‑A‑T Signals
-# - FAQ Content
-# - Citations & Authority Signals
-# - Definition Blocks
-# - Technical SEO (H1, alt text, meta)
-```
-
-### Google Search Console / Bing WMT
-```bash
-# GSC coverage summary
-canonry google coverage <project>
-
-# Bing coverage summary  
-canonry bing coverage <project>
-
-# Force refresh cached data
-canonry google refresh <project>
-canonry bing refresh <project>
-```
-
-## Workflow
-
-### 1. Diagnose
-```bash
-# Baseline AEO visibility
-canonry run <project> --wait
-canonry evidence <project>
-
-# Technical SEO audit
-npx @ainyc/aeo-audit@latest "https://client.com" --format json > audit.json
-```
-
-### 2. Prioritize
-Gaps sorted by impact:
-1. **Missing H1** → immediate content patch
-2. **No structured data** → JSON‑LD injection
-3. **Thin content** → definition blocks ("What is…")
-4. **County‑level targeting** → refine after base visibility
-5. **E‑E‑A‑T signals** → Person schema, author tags (needs client input)
-
-### 3. Execute
-- **Schema injection**: LocalBusiness + FAQPage JSON‑LD via site‑appropriate method (Elementor Custom Code, theme hooks, etc.)
-- **Content patches**: H1, meta title/description, image alt text via REST API or CMS
-- **AI‑readable files**: Upload `llms.txt`, `llms‑full.txt` to site root
-- **Indexing requests**: Submit all URLs to Google Indexing API + Bing IndexNow
-- **Keyphrase strategy**: Trim to 8‑12 high‑intent queries; remove noise
-
-### 4. Monitor
-- Weekly canonry sweeps to track citation changes
-- Correlate visibility shifts with deployment dates
-- Watch for competitor displacement in keyphrases
-
-### 5. Report
-Clear, data‑first summaries:
-> “Lost `emergency dentist brooklyn` on Gemini — two competitors moved in. Here’s what to fix.”
-
-## Common Patterns
-
-### New Site (0 citations)
-- Focus on indexing first: submit sitemap to GSC/Bing, request indexing
-- Implement base schema (LocalBusiness, Service)
-- Create `llms.txt` with service‑area details
-- Trim keyphrases to 8‑12 core queries
-- Expect 4‑8 weeks for first citations
-
-### Established Site (regression)
-- Compare canonry runs to identify when loss occurred
-- Check for recent competitor content or site changes
-- Validate schema is still present and error‑free
-- Re‑submit affected URLs to indexing APIs
-
-### County‑Level Targeting
-```yaml
-# Service areas in llms.txt / schema
-Michigan:
-  - Oakland County (Troy, Auburn Hills, Pontiac)
-  - Macomb County (Sterling Heights, Shelby Township)
-  - Wayne County (Detroit, Dearborn)
-  - Lapeer County (HQ: Almont)
-
-Florida:
-  - Miami‑Dade County (Miami, Coral Gables)
-  - Broward County (Fort Lauderdale, Hollywood)
-  - Palm Beach County (West Palm Beach, Boca Raton)
-```
-- Reference counties in schema `areaServed` and `llms.txt`
-- **Do not** create separate keyphrases per county until base visibility exists
-
-### WordPress/Elementor Specifics
-- REST API user with Application Passwords (`/wp‑json/wp/v2/`)
-- Elementor data patched via `_elementor_data` meta field
-- Schema injection via Elementor Pro Custom Code (`elementor_snippet` CPT)
-- Yoast SEO title/description fields often NOT REST‑writable → manual WP Admin edit
-- `wp‑login.php` may be hidden (security plugin) → file uploads require manual WP File Manager
-
-## Example: Full AEO Audit + Action Plan
-
-```bash
-# 1. Audit
-npx @ainyc/aeo-audit@latest "https://client.com" --format json > audit.json
-
-# 2. Parse score
-cat audit.json | jq '.overallScore, .overallGrade'
-
-# 3. Check AEO baseline
-canonry status client-project
-canonry evidence client-project
-
-# 4. Generate action list
-cat audit.json | jq -r '.factors[] | select(.score < 70) | "- \(.name): \(.score)/100 (\(.grade)) - \(.recommendations[0])"'
-```
+## How to Operate
+
+A canonry engagement follows the same loop regardless of project size:
+
+1. **Diagnose** — Run a baseline sweep (`canonry run <project> --wait`) and a technical audit (`npx @ainyc/aeo-audit@latest <url> --format json`). See `references/aeo-analysis.md` for interpretation.
+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."
+
+## Common Starting Points
+
+- **New site, 0 citations** → submit to GSC/Bing first; basic LocalBusiness/Service schema; `llms.txt`; trim to 8–12 high-intent keyphrases. See `references/indexing.md`.
+- **Established site, regression** → diff canonry runs to find the loss window; verify schema is intact; resubmit affected URLs. See `references/aeo-analysis.md`.
+- **Multi-county targeting** → reference counties in `areaServed` schema and `llms.txt`; do not split into per-county keyphrases until base visibility exists.
+
+## Google Analytics 4
+
+GA4 is a first-class signal alongside citation tracking. Connect once with `canonry ga connect <project> --property-id <id> --key-file <path>`; `canonry ga sync` then pulls daily landing-page traffic, AI-referral sessions across 10 known providers (chatgpt, perplexity, claude, gemini, openai, anthropic, copilot, phind, you.com, meta.ai), and social referrals split into Organic vs Paid via GA4's `channelGroup` — and persists everything into four DB tables (`gaTrafficSnapshots`, `gaAiReferrals`, `gaSocialReferrals`, `gaTrafficSummaries`). All read commands query that local store, so they are fast and quotaless once a sync has run. AI referrals are tracked across three GA4 attribution dimensions (session source / first-user source / manual UTM) and joined to landing pages, so you can see which page each AI provider sent traffic to. Use `canonry ga traffic` for the current snapshot, `canonry ga attribution --trend` for a unified channel-share overview with biggest-mover deltas, and `canonry ga ai-referral-history` / `canonry ga social-referral-history` for daily series. See `references/canonry-cli.md` for the full command catalog and return-shape details.
 
 ## Boundaries & Safety
 
 - **Never touch live WordPress without explicit approval**
 - **Back up `~/.canonry/config.yaml` before any config edit**
-- **Never fabricate citation data** — if a sweep hasn’t run, say so
+- **Never fabricate citation data** — if a sweep hasn't run, say so
 - **Client data stays private** — canonry repo is public; no real domains in issues
 - **Respect API rate limits** — batch operations, avoid tight loops
 
+## References
+
+| File | Read when |
+|---|---|
+| `references/canonry-cli.md` | Looking up specific canonry commands or flags |
+| `references/aeo-analysis.md` | Interpreting sweep output, diagnosing regressions, planning content fixes |
+| `references/indexing.md` | Submitting URLs, checking GSC/Bing coverage, fixing indexing gaps |
+| `references/wordpress-integration.md` | Connecting to WordPress, editing pages, pushing staging → live |
+
 ---
 
-**Tools:** canonry v1.37+, @ainyc/aeo‑audit v1.3+  
+**Tools:** canonry v3+, @ainyc/aeo-audit v1.3+  
 **Website:** [ainyc.ai](https://ainyc.ai) | **Reference:** [AINYC AEO Methodology](https://ainyc.ai/aeo-methodology)

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

@@ -81,6 +81,21 @@ canonry analytics <project> --feature gaps --window 30d
 ```
 Look for patterns: are gaps growing or shrinking? Are new competitors appearing?
 
+### Step 6: Check GA4 traffic for impact
+A lost citation isn't always a lost user. Before declaring a regression real, confirm whether AI-referral traffic actually fell on the same window:
+```bash
+canonry ga status <project>                          # confirm lastSyncedAt is recent; re-sync if stale
+canonry ga ai-referral-history <project> --format json
+                                                      # daily {date, source, medium, attribution, sessions, users}
+canonry ga attribution <project> --trend             # 7d/30d direction per channel + biggest mover
+```
+Read the result against the citation loss window:
+- **AI sessions flat or up** → the citation loss may be sweep-side noise (provider variance, query refresh). Track for one more cycle before alarming the client.
+- **AI sessions dropped on the same date** → real outage; escalate. Cross-reference `aiReferrals[]` from `canonry ga traffic` to identify which provider lost traffic.
+- **Organic dropped but AI held** → the citation loss is masking a separate indexing issue. Re-run Step 1.
+
+GA4 also covers the inverse case: a *gain* on `attribution --trend` for the AI channel that isn't reflected in citation count usually means a provider expanded an existing citation's exposure (more queries triggering it) — a quiet win worth flagging in the next report.
+
 ## Trend Interpretation
 
 **Stable cited** — monitor for regressions, no action needed.

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

@@ -253,21 +253,39 @@ canonry wordpress onboard <project> --url <url> --user <user>  # full onboarding
 
 ## Google Analytics 4
 
-GA4 integration uses service account authentication (no OAuth). The service account must have Viewer access on the GA4 property.
+GA4 integration uses service account authentication (no OAuth). The service account must have Viewer access on the GA4 property. `ga sync` writes to four DB tables (`gaTrafficSnapshots`, `gaAiReferrals`, `gaSocialReferrals`, `gaTrafficSummaries`); every subsequent read command queries the local store rather than re-fetching from GA4, so reads are fast and quotaless. AI-referral rows are tracked across 10 known providers (chatgpt, perplexity, claude, gemini, openai, anthropic, copilot, phind, you.com, meta.ai), three GA4 attribution dimensions (`session` / `first_user` / `manual_utm`), and joined to landing pages. Social referrals are split Organic vs Paid via GA4's `sessionDefaultChannelGroup`. All commands support `--format json`.
 
 ```bash
-canonry ga connect <project> --property-id <id> --key-file ./sa-key.json  # connect GA4
-canonry ga disconnect <project>                  # disconnect
-canonry ga status <project>                      # connection status
-canonry ga sync <project> [--days 30] [--only traffic|ai|social]  # pull GA4 data (selective or full)
-canonry ga traffic <project>                     # landing pages + AI/social referral sources
-canonry ga coverage <project>                    # indexed pages with traffic overlay
-canonry ga ai-referral-history <project>         # daily AI referral history by source
-canonry ga social-referral-history <project>     # daily social referral history by source
-canonry ga social-referral-summary <project> [--trend]  # one-line social summary + optional trend
-canonry ga attribution <project> [--trend]        # unified channel attribution overview + optional trends
+canonry ga connect <project> --property-id <id> --key-file ./sa-key.json
+                                                  # connect via service account (auth method = service_account)
+canonry ga disconnect <project>                  # disconnect; deletes all synced rows for the project
+canonry ga status <project>                      # connected, propertyId, authMethod, lastSyncedAt
+canonry ga sync <project> [--days 30] [--only traffic|ai|social]
+                                                  # refresh from GA4 → DB; --only restricts which slice is replaced
+                                                  # returns: synced, rowCount, aiReferralCount, socialReferralCount,
+                                                  #          syncedComponents, syncedAt
+canonry ga traffic <project>                     # current-period rollup; returns: totalSessions,
+                                                  # totalOrganicSessions/totalDirectSessions/totalUsers,
+                                                  # organicSharePct/aiSharePct/socialSharePct/directSharePct,
+                                                  # topPages[], aiReferrals[], aiReferralLandingPages[],
+                                                  # aiSessionsDeduped, aiUsersBySession, socialReferrals[]
+canonry ga attribution <project> [--trend]       # unified channel breakdown (organic / ai / social / direct
+                                                  # sessions + raw and display share %s); --trend adds 7d/30d
+                                                  # direction per channel + biggest mover
+canonry ga ai-referral-history <project>         # daily array of {date, source, medium, attribution,
+                                                  # sessions, users}; one row per (day × source × dimension)
+canonry ga social-referral-history <project>     # daily array of {date, source, medium, channel,
+                                                  # sessions, users}; channel ∈ {Organic Social, Paid Social}
+canonry ga social-referral-summary <project> [--trend]
+                                                  # one-line social rollup: socialSessions, socialUsers,
+                                                  # socialSharePct, topSources[]; --trend adds 7d/30d direction
+canonry ga session-history <project>             # daily totals: {date, sessions, organicSessions, users}
+canonry ga coverage <project>                    # per-page overlay: {landingPage, sessions,
+                                                  # organicSessions, users}
 ```
 
+Every read command queries persisted DB rows, so a stale `lastSyncedAt` means the response is stale — always check `ga status` before drawing conclusions, and re-`ga sync` if the data is older than the analysis window. Use `--only ai` or `--only social` to refresh just one slice when iterating.
+
 ## Backlinks (Common Crawl)
 
 Workspace-level Common Crawl release sync + per-project backlink extraction. Requires DuckDB; install once with `canonry backlinks install`. Releases are downloaded once per workspace and reused across all projects.