@ainyc/canonry 1.46.0 → 1.46.1

package/assets/agent-workspace/skills/aero/references/memory-patterns.md

@@ -0,0 +1,37 @@
+# Memory Patterns
+
+## Per-Client State Template
+
+Store in OpenClaw agent memory after each significant event:
+
+```
+Client: <business name>
+Domain: <domain>
+Project: <project slug>
+
+Baseline (set <date>):
+  Overall cited rate: <X>% (<N>/<total> keyword-provider pairs)
+  Best provider: <provider> (<X>% cited)
+  Worst provider: <provider> (<X>% cited)
+  Top keyword: "<keyword>" (cited on <N>/<total> providers)
+  Worst keyword: "<keyword>" (cited on <N>/<total>)
+
+Competitors:
+  <domain> — <trend description>
+
+Content strategy:
+  <page type> drives <X>% of citations
+
+Open items:
+  - <description>
+
+Sweep history summary:
+  <date>: <X>% (<note>)
+```
+
+## Update Cadence
+
+- **After each sweep:** Update cited rates, flag new regressions
+- **After each fix:** Record what was changed, set monitoring flag
+- **After each client interaction:** Update preferences, strategy notes
+- **Weekly:** Summarize trend direction, update competitor notes

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

@@ -0,0 +1,52 @@
+# Orchestration Workflows
+
+## Workflow 1: New Client Baseline
+
+Trigger: First sweep completes for a new project
+
+Steps:
+1. `canonry evidence <project> --format json` → get initial citation data
+2. Compute baseline: cited rate, provider breakdown, top/bottom keywords
+3. `npx @ainyc/aeo-audit "<domain>" --format json` → site readiness score
+4. Identify top 3 gaps (uncited keywords with fixable site issues)
+5. Generate onboarding report with baseline + action plan
+6. Store baseline metrics in memory
+
+## Workflow 2: Regression Response
+
+Trigger: Comparison shows decline or webhook fires regression.detected
+
+Steps:
+1. `canonry evidence <project> --format json` → current state
+2. `canonry history <project> --keyword "<keyword>"` → trend for affected keyword
+3. Check indexing: `canonry google coverage <project>` → is the page still indexed?
+4. Check competitor: did a competitor gain the citation we lost?
+5. Audit the page: `npx @ainyc/aeo-audit "<page-url>" --format json`
+6. Diagnose cause: indexing issue / content issue / competitive displacement
+7. Recommend fix with evidence
+8. If content fix: generate diff (schema, llms.txt, or content changes)
+9. Update memory with regression event + diagnosis
+
+## Workflow 3: Weekly Review
+
+Trigger: Scheduled (weekly, or on-demand)
+
+Steps:
+1. `canonry evidence <project> --format json` → current metrics
+2. Compare to baseline/prior week from memory
+3. Compute deltas: citations gained, lost, stable
+4. Flag any new regressions not yet addressed
+5. Check competitor movement
+6. Generate summary with key changes + recommended next steps
+
+## Workflow 4: Content Gap Analysis
+
+Trigger: User asks "why aren't we cited for X?" or multiple uncited keywords detected
+
+Steps:
+1. `canonry evidence <project> --keyword "<keyword>"` → confirm uncited
+2. Check if a relevant page exists on the domain
+3. If no page: recommend content creation (topic, target keywords)
+4. If page exists: `npx @ainyc/aeo-audit "<page-url>"` → diagnose why uncited
+5. Check schema completeness, llms.txt coverage, indexing status
+6. Generate prioritized fix list

package/assets/agent-workspace/skills/aero/references/regression-playbook.md

@@ -0,0 +1,34 @@
+# Regression Playbook
+
+## Detection
+
+A regression is detected when a citation is lost between consecutive completed runs for the same project. Specifically: a keyword+provider pair that was cited in run N is no longer cited in run N+1.
+
+## Triage
+
+Classify the regression by severity:
+
+| Severity | Criteria |
+|---|---|
+| **Critical** | Branded term lost on any provider |
+| **High** | Top-performing keyword lost on primary provider |
+| **Medium** | Non-branded keyword lost on one provider |
+| **Low** | Keyword lost that was only marginally cited |
+
+## Diagnosis
+
+For each regression, check causes in order:
+
+1. **Competitor displacement** — Did a competitor domain appear in the citation for this keyword+provider? Check current run snapshots.
+2. **Indexing loss** — Is the page still indexed? Check Google Search Console integration or HTTP status.
+3. **Content change** — Did the page content change significantly? Compare content hashes if available.
+4. **Provider behavior change** — Did the provider change its response pattern for this query type?
+5. **Unknown** — No clear cause identified. Flag for manual investigation.
+
+## Response
+
+1. Alert the client with specific data (keyword, provider, dates, evidence)
+2. Recommend diagnostic steps based on suspected cause
+3. If actionable: generate fix (schema update, content suggestion, indexing resubmission)
+4. Set monitoring flag to track if the regression resolves
+5. Update memory with the regression event and diagnosis

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

@@ -0,0 +1,67 @@
+# Reporting Templates
+
+## Weekly Report
+
+```
+# Weekly AEO Report: <project> (<date range>)
+
+## Summary
+- Cited rate: <X>% (Δ<+/-Y>% from last week)
+- Regressions: <N> new, <N> resolved
+- Gains: <N> new citations
+- Providers monitored: <N>
+
+## Key Changes
+- <most important change with data>
+- <second most important>
+- <third>
+
+## Regressions
+| Keyword | Provider | Status | Suspected Cause |
+|---------|----------|--------|-----------------|
+| <keyword> | <provider> | New/Investigating/Resolved | <cause> |
+
+## Gains
+| Keyword | Provider | Position | Page |
+|---------|----------|----------|------|
+| <keyword> | <provider> | <N> | <url> |
+
+## Competitor Watch
+- <competitor>: <trend>
+
+## Recommended Actions
+1. <action with rationale>
+2. <action>
+3. <action>
+```
+
+## Monthly Report
+
+```
+# Monthly AEO Report: <project> (<month year>)
+
+## Executive Summary
+<2-3 sentence overview of the month>
+
+## Metrics
+| Metric | Start of Month | End of Month | Change |
+|--------|---------------|--------------|--------|
+| Overall cited rate | <X>% | <Y>% | <Δ>% |
+| Keywords monitored | <N> | <N> | <Δ> |
+| Active regressions | <N> | <N> | <Δ> |
+
+## Provider Breakdown
+| Provider | Cited Rate | Trend |
+|----------|-----------|-------|
+| <provider> | <X>% | ↑/↓/→ |
+
+## Fixes Deployed
+| Date | Fix | Status | Impact |
+|------|-----|--------|--------|
+| <date> | <description> | Monitoring/Confirmed | <result> |
+
+## Next Month Priorities
+1. <priority>
+2. <priority>
+3. <priority>
+```

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

@@ -0,0 +1,274 @@
+---
+name: canonry
+description: "AEO (Answer Engine Optimization) monitoring and analysis using canonry CLI and aeo-audit tool. Use when: (1) running citation sweeps across AI providers (Gemini, ChatGPT, Claude, Perplexity); (2) auditing technical SEO with structured data validation; (3) implementing schema markup, sitemaps, llms.txt; (4) diagnosing indexing issues via Google Search Console and Bing Webmaster Tools; (5) optimizing content for AI readability and entity consistency. NOT for: general web development, content writing, PPC campaigns, or social media management."
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "📡",
+        "requires": { "bins": ["canonry"] },
+        "install":
+          [
+            {
+              "id": "npm",
+              "kind": "npm",
+              "package": "canonry",
+              "bins": ["canonry"],
+              "label": "Install canonry globally",
+              "command": "npm install -g canonry"
+            },
+            {
+              "id": "npx",
+              "kind": "npx",
+              "package": "@ainyc/aeo-audit",
+              "bins": ["aeo-audit"],
+              "label": "Use aeo-audit via npx",
+              "command": "npx @ainyc/aeo-audit@latest"
+            }
+          ],
+      },
+  }
+---
+
+# Canonry
+
+Monitor and optimize site visibility across AI answer engines (Gemini, ChatGPT, Claude, Perplexity) and traditional search engines using the `canonry` CLI for AEO monitoring and `aeo-audit` for technical SEO analysis.
+
+## When to Use
+
+✅ **USE this skill when:**
+
+- Tracking which keyphrases earn citations (or lose them) across AI providers
+- Running technical SEO audits with 14‑factor scoring
+- Implementing structured data (JSON‑LD: LocalBusiness, FAQPage, Service)
+- Diagnosing indexing gaps in Google Search Console / Bing Webmaster Tools
+- Optimizing `llms.txt`, `llms‑full.txt`, sitemaps, robots.txt for AI crawlers
+- Patching missing H1 tags, meta descriptions, image alt text
+- Submitting URLs to Google Indexing API and Bing IndexNow
+- Analyzing competitor citation patterns in AI answers
+
+## When NOT to Use
+
+❌ **DON'T use this skill when:**
+
+- General WordPress development (use `wordpress` skill if available)
+- Content writing or copy creation (human‑led task)
+- Paid search/SEM campaigns (different specialty)
+- Social media management or outreach
+- Local business listing management (e.g., GBP, Yelp)
+- Backlink building or outreach campaigns
+
+## Core Philosophy
+
+- **AI models are black boxes** — Measure citation outcomes, not assume causality
+- **Position, then wait** — Site changes take weeks/months to reflect in AI indexes; canonry tells us *when* it happens, not *if*
+- **Signal‑over‑noise** — Trim keyphrase lists to high‑intent queries; avoid granular targeting until base visibility exists
+- **CLI‑native, UI‑optional** — Prefer API‑driven changes over manual CMS clicks; faster, repeatable, auditable
+
+## Toolchain
+
+### canonry (AEO Monitoring)
+```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])"'
+```
+
+## 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
+- **Client data stays private** — canonry repo is public; no real domains in issues
+- **Respect API rate limits** — batch operations, avoid tight loops
+
+## Output Templates
+
+### Audit Summary
+```
+## AEO/SEO Audit — https://client.com
+
+**Overall:** 66/100 (D)
+
+**Top strengths (A/A+):**
+- AI‑Readable Content (100) — llms.txt, llms‑full.txt present
+- FAQ Content (100) — FAQPage schema detected
+- AI Crawler Access (100) — robots.txt allows all bots
+
+**Critical gaps (F):**
+- Definition Blocks (0) — no "What is…" sections
+- E‑E‑A‑T Signals (45) — missing Person schema, author tags
+- Citations & Authority (44) — no external references to industry sources
+
+**Immediate actions:**
+1. Add H1 tag to homepage (Technical SEO: 60/100)
+2. Create "What is polyurea?" section on /services/ (Definition Blocks: 0/100)
+3. Submit all 5 URLs to Bing IndexNow (indexing: 2/5)
+```
+
+### Citation Report
+```
+## canonry sweep — client-project
+
+**Run:** 2026‑04‑03T13:44Z (ID: 4a45ebfc...)
+
+**Keyphrase visibility (12 tracked):**
+✅ polyurea roof coating — 3/3 providers
+✅ commercial roof coating — 2/3 providers  
+❌ polyurea roof coating Michigan — 0/3 (geo gap)
+❌ commercial roofing contractor Michigan — 0/3 (geo gap)
+
+**Changes since last sweep (2026‑03‑27):**
+- Lost `flat roof coating Michigan` on Gemini (−1)
+- Gained `industrial roof coating` on Claude (+1)
+- No change on ChatGPT (stable)
+
+**Next steps:**
+- Build Michigan location page (/michigan/)
+- Add county‑level references to llms.txt
+- Re‑sweep in 7 days
+```
+
+---
+
+**Tools:** canonry v1.37+, @ainyc/aeo‑audit v1.3+  
+**Reference:** [AINYC AEO Methodology](https://ainyc.ai/aeo-methodology)

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

@@ -0,0 +1,130 @@
+# AEO Analysis: Interpreting Canonry Results
+
+## What Citation Means
+
+A "cited" keyword means the client's domain appeared in an AI provider's response when that query was asked. It does NOT mean:
+- The AI recommended them positively
+- The citation is prominent
+- It will persist on the next sweep
+
+A "not-cited" keyword means the AI answered without mentioning the client at all.
+
+## Reading Evidence Output
+
+```
+✓ cited  AEO Agency NYC             ← branded/direct match
+✓ cited  best plumber brooklyn
+✗ not-cited  how to fix a leaky faucet  ← informational gap: no page for this topic
+✗ not-cited  emergency plumber near me  ← competitive gap: others cited instead
+```
+
+### Keyword Categories
+
+**Branded/direct keywords** (e.g., "[business name] [city]"):
+- If cited: good — entity is established for core queries
+- If not cited: urgent — something broken at a fundamental level (indexing, schema, llms.txt)
+
+**Competitive keywords** (e.g., "best [service] [city]"):
+- If not cited: check who IS cited — competitor analysis needed
+- Harder wins; require established authority and trust signals
+
+**Informational/how-to keywords** (e.g., "how to [do X]"):
+- If not cited: almost always a content gap — no page targeting this topic, or it's not indexed
+- High-leverage — informational content positions a site as authoritative to AI models
+
+## Using Analytics
+
+### Citation Rate Trends (`--feature metrics`)
+Shows citation rate over time across providers. Use to identify:
+- Improving or declining visibility trends
+- Provider-specific performance differences
+- Impact of content/indexing changes over time
+
+**Key phrase normalization:** When new key phrases are added to a project mid-history, canonry automatically normalizes each time bucket to only include key phrases that existed before that bucket started. This prevents newly-added (typically uncited) key phrases from creating a false drop in the citation rate trend. The chart displays dashed vertical annotation lines at points where key phrases were added (e.g. "+3 kp"), and each bucket's tooltip shows the key phrase count ("kp") used for that bucket's calculation.
+
+### Gap Analysis (`--feature gaps`)
+Categorizes keywords as cited, gap (competitor cited but you're not), or uncited (nobody cited). Priorities:
+- **Gap keywords** are highest priority — competitors are winning these
+- **Uncited keywords** may need content or may be too broad
+
+### Source Breakdown (`--feature sources`)
+Shows which source categories AI models cite for your keywords. Helps identify:
+- Whether competitors dominate specific categories
+- Content format opportunities (FAQ, how-to, comparison pages)
+
+## Diagnosing Citation Gaps
+
+### Step 1: Check indexing first
+Not cited ≠ bad content. Often the page isn't indexed yet.
+```bash
+canonry google coverage <project>
+```
+If key pages are "unknown to Google," submit them before drawing conclusions.
+
+### Step 2: Check if content exists
+Is there a page on the site targeting that keyword? If not, that's the gap — not a canonry or provider issue.
+
+### Step 3: Check competitors
+For competitive keywords, if others are cited and the client isn't:
+- Do competitors have more specific, dedicated pages?
+- Do they have stronger schema/structured data?
+- Are they more established in the index?
+
+Run `canonry evidence <project> --format json` and check `competitorOverlap` in snapshots.
+
+### Step 4: Check across providers
+Gemini, OpenAI, Claude, and Perplexity may behave differently. One citing a domain while another doesn't is normal — each has its own knowledge base and update schedule.
+
+### Step 5: Check analytics trends
+```bash
+canonry analytics <project> --feature gaps --window 30d
+```
+Look for patterns: are gaps growing or shrinking? Are new competitors appearing?
+
+## Trend Interpretation
+
+**Stable cited** — monitor for regressions, no action needed.
+
+**New citation** (was not-cited, now cited) — win. Correlate with what changed: new content, indexing, schema update.
+
+**Regression** (was cited, now not-cited) — investigate immediately:
+- Did a competitor page launch?
+- Did the page get deindexed or go down?
+- Did the model update?
+- Check `canonry google deindexed <project>` for index losses
+
+**Fluctuation** (cited in some runs, not others) — normal for competitive keywords. Track trend over 5+ runs before drawing conclusions. AI answers are non-deterministic.
+
+## What to Recommend
+
+### Low overall citation (< 50%)
+1. Audit indexing — `canonry google coverage <project>`
+2. Submit unindexed pages to Google Indexing API
+3. Submit sitemap to Bing WMT + send IndexNow batch
+4. Check core pages for schema (LocalBusiness / Organization / FAQPage)
+5. Map uncited keywords to pages — which have no corresponding page?
+
+### Branded terms not cited
+Red flag. Check:
+- Is the homepage indexed?
+- Does `llms.txt` exist and list the business clearly?
+- Does schema include the exact brand name in `name` field?
+
+### Informational terms not cited
+Content strategy play:
+- Does a page targeting this topic exist? If not, create it.
+- Is it indexed? If not, submit it.
+- Is it structured for AI extraction? (FAQ schema, clear H2s, definition-style answers)
+
+### Provider variance (cited on one, not others)
+Expected — each provider has independent knowledge. Focus on the ones that matter most for the client's audience. Don't over-optimize for one provider at the expense of others.
+
+## The AEO Timeline Reality
+
+- Site changes → weeks/months to appear in sweeps (or never)
+- Google indexing → 24–72h with Indexing API, longer organic
+- Bing indexing → hours with IndexNow, days without
+- Model training updates → unknown schedule, outside our control
+
+**Never say:** "Deploy this and re-run canonry to see if it worked."
+**Always say:** "This positions the site correctly. Canonry will tell us if/when that pays off."