@canonry/canonry 4.104.0

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

@@ -0,0 +1,67 @@
+---
+name: orchestration
+description: Workflow recipes — baseline, regression response, weekly review, content gap analysis. Read when planning a multi-step task or recurring review.
+---
+
+# Orchestration Workflows
+
+**Read the mention signal first in every workflow.** Compute and compare **mention rate + mention share** before cited rate. The fast mention read is `cnry overview <project> --format json` (returns `queryCounts.mentionRate`, `scores.mention`, `scores.mentionShare`) plus `cnry analytics <project> --feature gaps --format json` (returns `mentionedQueries[]`, `mentionGap[]`, `notMentioned[]` alongside the cited buckets). Use `cnry evidence <project>` for the per-query drilldown — it prints the two-glyph `[C/c][M/m]` cell per (query × provider) and a `Mentioned: X / Y` line next to `Cited: X / Y`. Mention and citation are independent — never derive one from the other. Treat `answerMentioned = null` as "not checked," never as not-mentioned.
+
+## Workflow 1: New Client Baseline
+
+Trigger: First sweep completes for a new project
+
+Steps:
+1. `cnry overview <project> --format json` → mention read first: `queryCounts.mentionRate`, `scores.mention`, `scores.mentionShare`. Then `cnry analytics <project> --feature gaps --format json` for `mentionedQueries[]` / `mentionGap[]` / `notMentioned[]`, and `cnry evidence <project> --format json` for the per-query `[C/c][M/m]` drilldown and the secondary cited data.
+2. Compute baseline in this order: **mention rate, mention share**, then cited rate; provider breakdown; top/bottom queries by mention.
+3. `cnry technical-aeo run <project> --wait`, then `cnry technical-aeo score <project> --format json` → site readiness score across every page in the sitemap (auto-discovered; add `--limit <n>` to `run` to cap, default 500). Persists to the dashboard and is trendable via `cnry technical-aeo trend <project>`.
+4. Identify top 3 gaps — lead with `mentionGap[]` / `notMentioned[]` (where competitors are named and you aren't), then the cited gaps with fixable site issues.
+5. Generate onboarding report with baseline + action plan
+6. Store baseline metrics in memory (include mention rate + mention share, not just cited rate)
+
+## Workflow 2: Regression Response
+
+Trigger: Comparison shows decline or webhook fires regression.detected
+
+Steps:
+1. `cnry overview <project> --format json` → current state, mention first: did `scores.mention` / `scores.mentionShare` move? Then `cnry analytics <project> --feature gaps --format json` (`mentionGap[]` / `notMentioned[]`) and `cnry evidence <project> --format json` for the per-query `[C/c][M/m]` drilldown (which signal actually dropped on which provider).
+2. `cnry history <project>` → trend for affected query
+3. Check competitor mention share BEFORE cited displacement: did a competitor take the **mention** share you lost (`mentionGap[]`)? Only then ask whether a competitor gained the **citation** you lost.
+4. Check indexing: `cnry google coverage <project>` → is the page still indexed? (a deindexed/thin page starves both signals)
+5. Audit the page: `npx @ainyc/aeo-audit "<page-url>" --format json`
+6. Diagnose cause: indexing issue / content issue / competitive displacement (mention-share loss first, citation loss second)
+7. Recommend fix with evidence — lead with what restores the mention
+8. If content fix: generate diff (schema, llms.txt, or content changes)
+9. Update memory with regression event + diagnosis (record which signal regressed: mention, citation, or both)
+
+**Want to verify the regression is real / reproducible before reporting?** Use a probe run instead of a real sweep:
+
+```
+cnry run <project> --probe --provider <p> --query "<regressed-query>"
+```
+
+Then `cnry runs get <id>` to inspect the snapshot. The probe's snapshot won't displace the latest scheduled sweep on the dashboard, won't generate insights, and won't fire notifications — so you can re-test as many times as needed without polluting metrics. Promote to a real sweep (drop `--probe`) only if the operator explicitly wants the data to feed the dashboard.
+
+## Workflow 3: Weekly Review
+
+Trigger: Scheduled (weekly, or on-demand)
+
+Steps:
+1. `cnry overview <project> --format json` → current metrics, mention first (`queryCounts.mentionRate`, `scores.mention`, `scores.mentionShare`); `cnry analytics <project> --feature gaps --format json` for the mention gaps; `cnry evidence <project> --format json` for the per-query `[C/c][M/m]` drilldown
+2. Compare to baseline/prior week from memory — mention rate + mention share first, cited rate second
+3. Compute deltas: mentions gained/lost/stable (primary), then citations gained/lost/stable (secondary)
+4. Flag any new regressions not yet addressed (lead with lost mentions)
+5. Check competitor movement — mention share swing first, then cited-domain displacement
+6. Generate summary with key changes + recommended next steps
+
+## Workflow 4: Content Gap Analysis
+
+Trigger: User asks "why aren't we mentioned/cited for X?" or multiple not-mentioned / uncited queries detected
+
+Steps:
+1. `cnry overview <project> --format json` + `cnry analytics <project> --feature gaps --format json` → confirm the gap, mention first: is the query in `notMentioned[]` (not named at all) or `mentionGap[]` (a competitor is named, you aren't)? Then `cnry evidence <project>` for the per-query `[C/c][M/m]` cell to see whether you also lack the citation. Mention gap leads the diagnosis; the missing citation is the secondary lens.
+2. Check if a relevant page exists on the domain
+3. If no page: recommend content creation (topic, target queries) — give the engine a reason to name you
+4. If page exists: `npx @ainyc/aeo-audit "<page-url>"` → diagnose why neither mentioned nor cited
+5. Check schema completeness, llms.txt coverage, indexing status
+6. Generate prioritized fix list — fixes that earn the mention first, then the citation

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

@@ -0,0 +1,58 @@
+---
+name: regression-playbook
+description: Detection → triage → diagnosis → response for lost mentions (primary) and lost citations (secondary). Read when investigating why a query lost a mention or a citation.
+---
+
+# Regression Playbook
+
+## Detection
+
+A regression is, primarily, a **lost mention**: a query+provider pair whose answer text named the brand (`answerMentioned = true`) in run N no longer does in run N+1. A **lost citation** (the domain dropped from the grounding sources between the same two runs) is the secondary regression on the same query. The two signals are independent — a query can lose its mention while keeping its citation, or vice versa — so detect and report them separately; never infer one from the other. Treat `answerMentioned = null` as "not checked," not as a lost mention.
+
+**Confirm the drop is real, not sampling noise.** A single run is n=1 per provider — far too small to call a regression. Before escalating, pull `cnry visibility-stats <project> --by-provider` (MCP: `canonry_visibility_stats`) for the affected query: it returns the per-query mention/citation **rate with its sample size** (`checked` = the n for mention, `total` for citation) pooled across recent runs, so you can tell a genuine rate decline from one flaky probe. Use `--last-runs N` to bound the window to the runs around the suspected change. `null` ("not checked") is excluded from `checked` — never counted as not-mentioned.
+
+## Triage
+
+Classify the regression by severity. Mention loss leads; mention-share loss to a competitor is next; a citation loss is a lower, secondary tier on the same query.
+
+| Severity | Criteria |
+|---|---|
+| **Critical** | Lost a branded-term MENTION on any provider (the engine stopped naming you for your own brand) |
+| **High** | Mention-share loss — a competitor took mention share on a top query where yours fell; or a top-performing query lost its mention on the primary provider |
+| **Medium** | Non-branded query lost its mention on one provider; or a top query lost its CITATION (secondary signal) while the mention held |
+| **Low** | Query lost a mention or citation it only held marginally |
+
+## Diagnosis
+
+For each regression, check causes in order:
+
+1. **Competitor displacement** — Check mention share BEFORE cited-domain displacement. First: did a competitor brand take the mention share you lost? Compare `scores.mentionShare` (`cnry overview`) run-over-run and read `cnry analytics <project> --feature gaps` (`mentionGap[]` = competitor mentioned where you're not) to see who is being named instead of you. Only then check the citation side: did a competitor domain appear in the grounding sources for this query+provider? Check current run snapshots. For the whole cited picture, `cnry sources <project> --rank` (MCP: `canonry_analytics_sources`) ranks every cited domain and tags each with a surface class (own / direct-competitor / ota-aggregator / editorial-media / other), and `--by-provider` shows which engine grounds on whom — so you can tell a rival you must out-rank from an aggregator/editorial surface you should pitch for placement.
+2. **Indexing loss** — Is the page still indexed? Check Google Search Console integration or HTTP status. An unindexed or thin page starves the engine of reasons to mention you as well as to cite you.
+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 (query, 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
+
+## Local (Google Business Profile) insights
+
+A `gbp-sync` run produces a separate family of **location-scoped** insights (`provider = 'gbp'`, the location's display name in `query`). They're point-in-time, not run-to-run citation transitions, so triage them on their own terms:
+
+| Type | Meaning | Response |
+|---|---|---|
+| `gbp-lodging-gap` (low) | Lodging-capable location whose structured Lodging attributes canonry can't read via the GBP API, no Places evidence available | A **verify-nudge, not a confirmed gap**. The GBP Lodging API returns empty even for complete hotels, because the owner-set "Hotel details" amenity panel writes to a separate surface the API doesn't expose. Recommend the operator verify amenities in the GBP "Hotel details" panel; only treat as a real gap if they are genuinely unset there. Do not tell them they "have no amenities". |
+| `gbp-listing-discrepancy` (medium) | canonry can't read the Lodging attributes **plus** a Places snapshot showing the public listing advertises specific amenities (#648) | Worth a look but still a **verify**: Places can read amenities the Lodging API can't, so they are likely already set in "Hotel details" and just not API-readable. Name the exact amenities (breakfast, parking, pet-friendly, …) and ask the operator to confirm them in "Hotel details". Supersedes `gbp-lodging-gap`. Requires a Places API key (`gbp.places.api-key` doctor check). |
+| `gbp-cta-gap` (medium) | Place actions present but only aggregator/OTA booking links | Recommend adding a direct (merchant-owned) booking/reservation link as the preferred place action so AI surfaces the property's own site, not an OTA. |
+| `gbp-description-missing` (low) | A selected location with no owner business description (`profile.description`) set | A **reliable, confirmable gap**, not a verify-nudge: the description reads straight from the Business Information API, so an empty one is a real completeness miss. Recommend adding a business description (up to 750 chars). It is the cheapest owner-controlled prose AI answer engines lift to describe the business and it seeds the entity attributes (specialties, service area, differentiators) models draw on. Low severity: a quick owner-controlled improvement, not a regression. |
+| `gbp-metric-drop` (high/medium) | A headline conversion metric (direction requests, website clicks, call clicks) fell sharply week-over-week | **First rule out the ~2 to 3 day reporting lag** before treating the drop as real: confirm the window is anchored to `freshness.dataThroughDate` (the last complete day, not wall-clock), pull the daily series with `cnry gbp metrics` and discount the most recent ~3 days, and cross-check GSC daily. The lag reads falsely negative right after US holidays. Only once the drop survives the honest window: investigate profile/category edits, suspensions, or new local competition, and correlate with recent profile changes. |
+| `gbp-keyword-drop` (high/medium) | A head local search term's impressions fell month-over-month | Check whether the property still ranks for the term; refresh the profile / categories. Needs ≥2 accumulated months of `gbp_keyword_monthly` history. |
+
+These flow through the same notification + proactive wake-up path as visibility insights, so you'll see them in the post-`gbp-sync` follow-up. Dismissals are location-scoped (one location's gap can be dismissed without silencing the same gap at a sibling location).
+
+**Calibrating `gbp-listing-discrepancy` (don't over-claim).** The Places cross-reference only sees a narrow, schema-bound amenity subset; the broader rendered hotel module (wifi, pool, room service, room rates) lives in Google Hotel Center, which the Places API can't read. Run live against a real hotel, it surfaced exactly **one** amenity (`wheelchair accessibility`). So quote the named amenities as concrete proof, but frame the discrepancy as a **floor** ("the public listing advertises at least X that your profile doesn't"), not a full inventory. The converse also holds: a thin or empty `gbp places` result is NOT evidence the public listing is bare; it means Places carries little structured data for that place. Either way the recommendation is the same and unchanged by the count: the owner controls the structured GBP attributes AI engines cite, so any amenity the profile fails to assert is a gap worth closing.

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

@@ -0,0 +1,98 @@
+---
+name: reporting
+description: Weekly and monthly report templates with metric tables, regression/gain sections, and recommended-actions structure. Read when asked to produce a client-facing summary.
+---
+
+# 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
+cnry report <project>                          # writes canonry-report-<project>-YYYY-MM-DD.html in cwd
+cnry report <project> --output dist/aeo.html   # custom path
+cnry report <project> --format json            # raw payload, useful for narrating in chat
+```
+
+The HTML is self-contained (inline CSS + SVG charts, no network dependencies) and leads visually with mention coverage (the primary gauge), then covers: executive summary, per-query × per-provider matrix (mention + citation), competitor landscape, AI citation sources, GSC + GA4 performance, social and AI referrals, indexing health, 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:
+- **Mention is the primary metric; citation is secondary.** Narrate the mention figures first. `executiveSummary.mentionRate` is **per-query** — `mentionedQueryCount / totalQueryCount`, where a query counts as mentioned if any provider's answer text named the brand in the run. The report leads visually with mention coverage, but the machine field backing that headline is not confirmed in the CLI docs — [confirm field name against `cnry report --format json` / `ProjectReportDto`] before quoting it as the headline; `executiveSummary.mentionRate` / `mentionedQueryCount` are the confirmed per-query mention fields.
+- `executiveSummary.citationRate` is the **secondary**, per-query citation signal — `citedQueryCount / totalQueryCount`, where a query counts as cited if any provider in the run cited it. The denominator is total tracked queries (not (query × provider) pairs), so the rate stays comparable when provider count varies between runs. Use `citedQueryCount` / `totalQueryCount` directly when narrating ratios. Mention and citation are independent — never compute one from the other.
+- The same per-query definition powers every `citationsTrend[].citationRate` so trend deltas reflect real movement, not provider-mix variance.
+- `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
+
+```
+# Weekly AEO Report: <project> (<date range>)
+
+## Summary
+- Mention rate: <X>% (Δ<+/-Y>% from last week)        ← primary KPI
+- Mention share: <X>% (Δ<+/-Y>% from last week)       ← AI share-of-voice vs competitors
+- Cited rate: <X>% (Δ<+/-Y>% from last week)          ← secondary signal
+- Regressions: <N> new, <N> resolved (lead with lost mentions; note lost citations second)
+- Gains: <N> new mentions / <N> new citations
+- Providers monitored: <N>
+
+## Key Changes
+- <most important change with data>
+- <second most important>
+- <third>
+
+## Regressions
+| Query | Provider | Status | Suspected Cause |
+|-------|----------|--------|-----------------|
+| <query> | <provider> | New/Investigating/Resolved | <cause> |
+
+## Gains
+| Query | Provider | Position | Page |
+|-------|----------|----------|------|
+| <query> | <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 |
+|--------|---------------|--------------|--------|
+| Mention rate (primary) | <X>% | <Y>% | <Δ>% |
+| Mention share (primary) | <X>% | <Y>% | <Δ>% |
+| Cited rate (secondary) | <X>% | <Y>% | <Δ>% |
+| Queries monitored | <N> | <N> | <Δ> |
+| Active regressions | <N> | <N> | <Δ> |
+
+## Provider Breakdown
+| Provider | Mention Rate | Mention Trend | Cited Rate | Cited Trend |
+|----------|--------------|---------------|-----------|-------------|
+| <provider> | <X>% | ↑/↓/→ | <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/aero/references/wordpress-elementor-mcp.md

@@ -0,0 +1,223 @@
+---
+name: wordpress-elementor-mcp
+description: WordPress + Elementor MCP integration guide — prerequisites, auth, widget manipulation. Read only when the task involves editing WordPress/Elementor pages.
+---
+
+# Elementor + WordPress MCP Development Guide
+
+## Overview
+
+This guide covers programmatic management of WordPress + Elementor sites using the Elementor MCP plugin. It enables AI agents to read, create, and modify Elementor page layouts, widgets, and settings via the Model Context Protocol.
+
+## Prerequisites
+
+### WordPress Side
+- WordPress >= 6.8
+- Elementor >= 3.20 (container-based layouts)
+- Elementor Pro (for custom CSS, forms, nav menus, etc.)
+- **WordPress MCP Adapter** plugin ([GitHub](https://github.com/WordPress/mcp-adapter))
+- **Elementor MCP** plugin ([GitHub](https://github.com/msrbuilds/elementor-mcp))
+- Application Password created for API auth (Users > Profile > Application Passwords)
+- Permalinks set to "Post name" (required for `/wp-json/` REST API routing)
+
+### Client Side
+- `.mcp.json` in project root with HTTP MCP server config
+- Base64-encoded credentials: `echo -n "username:app-password" | base64`
+
+## MCP Configuration
+
+```json
+{
+  "mcpServers": {
+    "elementor-staging": {
+      "type": "http",
+      "url": "https://your-staging-site.com/wp-json/mcp/elementor-mcp-server",
+      "headers": {
+        "Authorization": "Basic BASE64_CREDENTIALS"
+      }
+    },
+    "elementor-production": {
+      "type": "http",
+      "url": "https://your-production-site.com/wp-json/mcp/elementor-mcp-server",
+      "headers": {
+        "Authorization": "Basic BASE64_CREDENTIALS"
+      }
+    }
+  }
+}
+```
+
+### Troubleshooting Connection Issues
+- If `/wp-json/` returns 404: go to Settings > Permalinks, set to "Post name", click Save
+- If auth fails (401): verify application password is correct and user has admin role
+- If MCP endpoint 404 but `/wp-json/` works: re-activate both MCP plugins
+- After staging re-clone: re-install plugins, re-create app password, re-save permalinks
+
+## Elementor Architecture
+
+### Element Hierarchy
+```
+Page
+ └── Container (root section)
+      └── Container (hero/section)
+           └── Container (row/column)
+                └── Widget (heading, text-editor, button, etc.)
+```
+
+### Key Concepts
+- **Containers** are flex/grid layouts that hold other containers or widgets
+- **Widgets** are the actual content elements (headings, text, images, buttons, forms)
+- **Element IDs** are 7-char hex strings, unique within a page
+- **Settings** control all visual properties (typography, colors, spacing, responsive)
+- **Responsive suffixes**: `_tablet` and `_mobile` variants (e.g., `typography_font_size_tablet`)
+
+### Common Widget Types
+- `heading` — H1-H6 titles
+- `text-editor` — Rich text content
+- `button` — CTA buttons with links
+- `image` / `image-box` — Images with optional text
+- `form` — Contact/lead forms (Pro)
+- `google_maps` — Embedded maps
+- `html` — Custom HTML (used for JSON-LD schema injection)
+- `reviews` — Testimonials
+- `nested-tabs` / `nested-accordion` — Tabbed/accordion content
+
+## Core MCP Workflow
+
+### 1. Discovery
+
+```
+list-pages              → Get all Elementor pages with IDs
+get-page-structure      → See element tree (containers + widgets)
+get-element-settings    → Inspect any element's full settings
+find-element            → Search by text content, widget type, or setting
+list-widgets            → See all available widget types
+get-widget-schema       → Get available settings for a widget type
+```
+
+### 2. Content Updates
+
+```
+update-widget           → Change text, links, colors, typography (partial merge)
+update-container        → Change layout, spacing, alignment, background
+add-heading             → Add a heading widget
+add-text-editor         → Add a text block
+add-button              → Add a CTA button
+add-html                → Add custom HTML (JSON-LD schema, tracking scripts)
+add-container           → Add a layout container
+```
+
+### 3. Structure Changes
+
+```
+move-element            → Reorder or re-parent elements
+remove-element          → Delete an element
+duplicate-element       → Clone an element
+reorder-elements        → Change sibling order
+```
+
+### 4. Styling
+
+```
+add-custom-css          → Page-level or element-level CSS (use media queries for responsive)
+update-global-colors    → Site-wide color palette
+update-global-typography → Site-wide font presets
+```
+
+### 5. Page Management
+
+```
+create-page             → New WordPress page with Elementor
+build-page              → Create complete page from declarative JSON
+export-page             → Get full page data
+delete-page-content     → Clear page content
+```
+
+## Best Practices
+
+### Staging-First Workflow
+1. Make all changes on staging via MCP
+2. Verify visually across viewports (use Chrome browser tools)
+3. Get human approval
+4. Replay changes on production via MCP
+5. Re-clone staging from production for next iteration
+
+### Responsive Design
+- Always check 3 breakpoints: desktop (1440+), tablet (768-1024), mobile (375-390)
+- Use `_tablet` and `_mobile` setting suffixes for responsive overrides
+- For large desktop fixes (1800px+), use `add-custom-css` with media queries
+- Elementor's breakpoints: desktop (default), tablet (1024px), mobile (767px)
+
+### Settings Merge Behavior
+- `update-widget` and `update-container` do **partial merges** — only specified settings change
+- Nested objects (like `margin`, `padding`, `typography_font_size`) must include all subkeys
+- Example margin: `{"unit": "px", "top": "0", "right": "0", "bottom": "0", "left": "20", "isLinked": false}`
+
+### CSS Custom Overrides
+- Use `add-custom-css` with `replace: true` to avoid CSS accumulation
+- Use `selector` keyword for element-level CSS: `selector .heading { color: red; }`
+- Wrap responsive fixes in `@media` queries to avoid affecting other breakpoints
+- Always verify CSS doesn't break other viewports after applying
+
+### JSON-LD Schema Injection
+- Use `add-html` widget with `<script type="application/ld+json">` content
+- Place in root container (append position -1) — script tags produce no visible output
+- Use distinct `@id` values that don't conflict with Yoast's auto-generated schema
+- Yoast generates: WebPage, BreadcrumbList, WebSite, Organization
+- Custom schema should use: Service, RoofingContractor, DefinedTerm, LocalBusiness, etc.
+
+### Common Gotchas
+- **Elementor CSS cache**: changes may not appear until CSS is regenerated. Use Elementor > Tools > Regenerate Files & Data, or the cache flush endpoint
+- **Shared templates**: headers/footers are Elementor Library templates (different post type). Find their post ID via browser inspection (`data-elementor-id` attribute)
+- **Widget IDs shared across pages**: pages cloned from templates share element IDs. Changes to one page don't affect others
+- **Yoast SEO meta**: not writable via REST API. Must be set manually in wp-admin
+- **WP Staging re-clone**: wipes plugins, app passwords, and permalink settings. Must reconfigure after each clone
+- **Background images**: `background-position` and `background-size: cover` interact differently across viewport sizes. Use browser tools to measure actual rendered positions
+
+## Quick Reference: Common Operations
+
+### Change heading text
+```
+update-widget(post_id, element_id, {"title": "New Heading"})
+```
+
+### Change text block content
+```
+update-widget(post_id, element_id, {"editor": "<p>New content</p>"})
+```
+
+### Change font size (responsive)
+```
+update-widget(post_id, element_id, {
+  "typography_font_size": {"unit": "px", "size": 80, "sizes": []},
+  "typography_font_size_tablet": {"unit": "px", "size": 65, "sizes": []},
+  "typography_font_size_mobile": {"unit": "px", "size": 40, "sizes": []}
+})
+```
+
+### Change container margin
+```
+update-container(post_id, element_id, {
+  "margin": {"unit": "px", "top": "0", "right": "0", "bottom": "0", "left": "250", "isLinked": false}
+})
+```
+
+### Add JSON-LD schema to a page
+```
+add-html(post_id, parent_id, '<script type="application/ld+json">{"@context":"https://schema.org",...}</script>')
+```
+
+### Add responsive CSS fix
+```
+add-custom-css(post_id, '@media (min-width: 1800px) { .elementor-element-XXXXX { margin-top: -200px !important; } }', replace=true)
+```
+
+### Find text on a page
+```
+find-element(post_id, search_text="lorem ipsum")
+```
+
+### Update Google Maps widget
+```
+update-widget(post_id, element_id, {"address": "Southeast Michigan, USA", "zoom": {"unit": "px", "size": 8, "sizes": []}})
+```

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

@@ -0,0 +1,30 @@
+---
+name: aero-soul
+description: Aero's persona, values, and voice — context-agnostic identity that applies whether Aero runs as the built-in agent or wraps around an external agent shell.
+---
+
+# Who You Are
+
+You are **Aero** — an AEO analyst. You help operators understand whether AI answer engines NAME their brand (mention) and, secondarily, whether they CITE their domain, and you act decisively on what the data shows. Mention is the primary gauge; citation is the secondary signal. The two are independent — never compute one from the other.
+
+## Values
+
+- **Evidence over opinion.** Numbers before interpretation. "ChatGPT stopped mentioning you for 'roof repair phoenix' between March 28 and April 2, and your mention share fell from 50% to 0%" beats "your visibility decreased" — then note the lost citation second.
+- **Proactive, not passive.** Regressions don't wait to be asked about. Surface them when you spot them. Flag competitors the moment they take mention share in answers you used to own, and when they appear in citations you own.
+- **Honest about uncertainty.** When the data is ambiguous, say so. Don't manufacture confidence. Don't promise fixes will appear in the next sweep — AEO changes take weeks.
+- **Cautious with writes.** Sweeps cost quota. Schedules shape downstream notifications. Queries define what gets tracked. Confirm intent before mutating state the operator will notice. When *you* need to test something (verify a fix, reproduce a regression), use `cnry run --probe` — same wire call, no dashboard/analytics/notification pollution.
+- **Canonry is the source of truth.** Read state back; never maintain a parallel copy in your head. Conclusions age, the data doesn't.
+
+## Voice
+
+Concise, peer-to-peer, action-oriented. The operator is a practitioner — skip the disclaimers and the 101 explanations. Every observation ends with a next step.
+
+Analyst energy: sharp, confident, direct. You don't sugarcoat bad news, but you lead with what to do about it. No hedging filler, no emoji, no corporate warmth. Just signal.
+
+You have opinions. If a client's setup is actively hurting them, say so plainly.
+
+## Boundaries
+
+- Never fabricate mention or citation data. If you haven't run a sweep, say so. Never coerce `answerMentioned` null → false — null means "not checked," not "not mentioned."
+- Never speculate why an AI mentioned or cited a competitor without evidence — stick to what canonry observed.
+- Private client data stays private.

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

@@ -0,0 +1,152 @@
+---
+name: canonry
+description: "Agent-first AEO operating platform."
+metadata:
+  {
+    "agent":
+      {
+        "emoji": "📡",
+        "requires": { "bins": ["canonry"] },
+        "install":
+          [
+            {
+              "id": "npm",
+              "kind": "npm",
+              "package": "@canonry/canonry",
+              "bins": ["canonry"],
+              "label": "Install canonry globally",
+              "command": "npm install -g @canonry/canonry"
+            },
+            {
+              "id": "npx",
+              "kind": "npx",
+              "package": "@canonry/canonry",
+              "bins": ["canonry"],
+              "label": "Run canonry via npx",
+              "command": "npx @canonry/canonry@latest init"
+            }
+          ],
+      },
+  }
+---
+
+# Canonry
+
+Agent-first open-source AEO (Answer Engine Optimization) operating platform. Track how AI answer engines **mention** your brand in answers and **cite** your domain in sources across Gemini, ChatGPT, Claude, and Perplexity, then act on the signal through the content engine and integrations.
+
+**Website:** [canonry.ai](https://canonry.ai) | **Docs:** [github.com/Canonry/canonry](https://github.com/Canonry/canonry)
+
+**CLI:** invoke as `cnry` (short form) or `canonry` — both ship with the npm package and are interchangeable. Examples in this skill use `cnry`.
+
+## When to Use
+
+- Tracking brand **mentions** in AI answer text and **citations** in source links across providers
+- Expanding the tracked-query basket from an ICP description (`cnry discover run`)
+- Running technical SEO audits (14‑factor scoring)
+- Implementing structured data (JSON‑LD)
+- Diagnosing indexing gaps via Google Search Console / Bing Webmaster Tools
+- Wiring server-side traffic (Cloud Run, WordPress, Vercel) and GA4 referrals into a single AEO signal
+- Optimizing `llms.txt`, sitemaps, robots.txt for AI crawlers
+- Submitting URLs to Google Indexing API and Bing IndexNow
+- Analyzing competitor citation patterns
+
+## Core Philosophy
+
+- **Measure outcomes** — AI models are black boxes; track mentions + citations, don't assume causality
+- **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
+
+## What Canonry Measures (Vocabulary)
+
+Two parallel signals are tracked per (query × provider) snapshot. They are independent — a model can do either, both, or neither — never conflate them.
+
+| Term | Means | Headline metric |
+|---|---|---|
+| **mentioned** | The project's brand or domain appears in the LLM's **answer text** (the prose the model returns). | **Mention Coverage** — share of (query × provider) snapshots where the brand was mentioned. **Mention Share** is the project's share among the cited+mentioned set vs competitors. |
+| **cited** | The project's domain appears in the LLM's **source links** (the grounding citations returned alongside the answer). | **Citation Coverage** — share of snapshots where the domain was in the source list. |
+
+Configure `spec.brandAliases` on the project (or pass via `cnry apply`) so the mention detector catches "Meta" alongside "Facebook", etc. The downloadable report (`cnry report`) and the dashboard both lead with Mention Coverage; Citation Coverage rides as the secondary gauge.
+
+## How to Operate
+
+A canonry engagement follows the same loop regardless of project size:
+
+1. **Diagnose** — Run a baseline sweep (`cnry run <project> --wait`) and a technical audit (`cnry technical-aeo run <project> --wait`, then `cnry technical-aeo score <project> --format json`). The audit crawls every page in the project's sitemap (auto-discovered from `/sitemap.xml`, the sitemap index, or `robots.txt`) so readiness reflects the whole site, not just one page, and persists the score to the dashboard. Read Mention Coverage first, Citation Coverage second. See `references/aeo-analysis.md`.
+2. **Prioritize** — Triage by impact: indexing gaps → schema gaps → content gaps → query strategy. Branded-term losses are urgent.
+3. **Execute** — Apply fixes via the canonry CLI or platform integrations. Use `--dry-run` on supported mutations (`cnry project delete`, `cnry query replace`, `cnry backfill ...`) to preview before committing. 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 (`cnry run --all --wait` fans out across every project). Correlate visibility shifts with deployments and competitor moves.
+5. **Report** — Lead with data, not interpretation: "Lost the mention for `<query>` on Gemini between <date> and <date> — two competitors moved in. Here's what to fix." For a one-command client-facing summary, run `cnry report <project>` to generate a self-contained HTML bundle (mention + citation hero, competitor landscape, GSC + GA4 performance, insights, suggested next queries). Same payload is available via `--format json` and the `canonry_report` MCP tool.
+
+**Verifying without polluting metrics**: when you need to test something on your own initiative — "did the latest provider deploy work?", "is this regression reproducible?", "would this query actually surface us?" — use `cnry run <project> --probe --provider <p> --query "..."`. Probe runs write a snapshot you can inspect via `cnry runs get <id>` but are excluded from the dashboard, analytics, intelligence, report, and notifications. Use probes for *your* investigation; use real sweeps when the operator wants the data to feed metrics.
+
+## Surgical Reads
+
+When you need a specific value rather than a full payload, use the dot-path getter:
+
+```bash
+cnry get <project> scores.mentionShare.value
+cnry get <project> scores.mentionCoverage.value
+cnry get <project> insights[0].severity
+cnry get <project> --from report scores.citationCoverage.value
+```
+
+`cnry get` resolves a path into the project's overview (default) or any registered source (`report`, `traffic`, `discovery`, etc.). Returns scalar values without forcing the agent to grep through a 30 KB JSON dump.
+
+## Common Starting Points
+
+- **New site, 0 citations** → submit to GSC/Bing first; basic LocalBusiness/Service schema; `llms.txt`; trim to 8–12 high-intent queries. 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`.
+- **Empty / generic query basket** → describe the ICP and let discovery expand: `cnry discover run <project> --icp "..." --wait`, then `cnry discover promote <session-id>` to adopt the cited + aspirational queries. Multi-location projects can geo-constrain with `--locations <label,...>`.
+- **Multi-county targeting** → reference counties in `areaServed` schema and `llms.txt`; do not split into per-county queries until base visibility exists.
+
+## Google Analytics 4
+
+GA4 is a first-class signal alongside citation tracking. Connect once with `cnry ga connect <project> --property-id <id> --key-file <path>`; `cnry 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 `cnry ga traffic` for the current snapshot, `cnry ga attribution --trend` for a unified channel-share overview with biggest-mover deltas, and `cnry ga ai-referral-history` / `cnry ga social-referral-history` for daily series. See `references/canonry-cli.md` for the full command catalog and return-shape details.
+
+## Server-Side Traffic
+
+When the project ships behind a server you control, wire crawler + AI-referral evidence directly from the edge: `cnry traffic connect cloud-run | wordpress | vercel <project> ...` writes credentials to `~/.canonry/config.yaml`, `cnry traffic sync` pulls and classifies logs into hourly buckets, and `cnry traffic events / sources / status` expose the rollups. See `references/server-side-traffic.md` for adapter-specific setup.
+
+**Vercel gotcha:** a freshly connected Vercel source captures only going-forward traffic — `lastSyncedAt` is seeded to NOW to avoid the 30-day default window exceeding Vercel's ~14-day request-logs retention (which would otherwise throw on every first sync). Use `cnry traffic backfill <project> --source <id> --days N` for historical recovery. If an idle Vercel/Cloud Run source has been failing long enough that `lastSyncedAt` aged past retention, unstick it with `cnry traffic reset <project> --source <id> --advance-to-now`.
+
+## Local AEO (Google Business Profile)
+
+For businesses with a physical location or service area, Google Business Profile is the local-AEO signal source — reviews, search-keyword impressions, daily performance metrics, and (for hotels) structured amenities + booking CTAs all feed how AI engines answer local-intent queries. Connect with `cnry gbp connect <project>`, discover locations with `cnry gbp locations discover <project>`, and pick which sync with `cnry gbp locations select/deselect`.
+
+**Hard prerequisites and gotchas — read `references/google-business-profile.md` before attempting setup:** GBP requires a Google access-form approval (0 QPM until granted), the only OAuth scope is the write-capable `business.manage`, **reviews live on a separately-gated legacy v4 API that the Basic approval does NOT grant** (and can't be self-enabled), and the **Q&A API was retired (2025-11-03)**. Keyword data is heavily privacy-redacted (often 100% for small businesses); an empty place-action profile is a real AEO finding to surface, but an empty lodging result is a verify-not-a-gap (the Lodging API can return 0 readable groups even when the owner-facing "Hotel details" panel has amenities set). The reference doc has the full setup walkthrough, the real-world data shapes, and the troubleshooting matrix.
+
+## Built-in Analyst (Aero)
+
+Canonry ships a built-in agent — Aero — for users who don't already have one. Drive it from the CLI:
+
+```bash
+cnry agent ask <project> "what changed since the last sweep?"
+cnry agent ask <project> "..." --provider claude --scope read-only
+cnry agent memory list <project>          # durable project notes
+```
+
+Aero also wakes unprompted after every `run.completed` so insights and regressions get analyzed without a user click. Users who already run their own agent (Claude Code, Codex, custom) wire webhooks instead: `cnry agent attach <project> --url <webhook-url>` subscribes to `run.completed`, `insight.critical`, `insight.high`, `citation.gained`.
+
+## Boundaries & Safety
+
+- **Never touch live WordPress without explicit approval**
+- **Back up `~/.canonry/config.yaml` before any config edit**
+- **Never fabricate mention or citation data** — if a sweep hasn't run, say so; never coerce `answerMentioned` null → false (null = "not checked")
+- **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, flags, or JSON return shapes |
+| `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 |
+| `references/server-side-traffic.md` | Wiring server-log evidence (Cloud Run, WordPress, Vercel adapters) for AI Visibility — Server-Side. Connect, sync, manage sources, troubleshoot. |
+| `references/google-business-profile.md` | Connecting Google Business Profile for local AEO: access-form approval, GCP API enablement, the v4-reviews access gate, hotel lodging/place-action signals, data shapes, troubleshooting. |
+
+---
+
+**Tools:** canonry v4+, @ainyc/aeo-audit v1.3+  
+**Website:** [canonry.ai](https://canonry.ai) | **Org:** [ainyc.ai](https://ainyc.ai) | **Reference:** [AINYC AEO Methodology](https://ainyc.ai/aeo-methodology)