{"id":"8e5857b8-c501-4d50-88ac-3ddb6b2cb766","entityType":"agent","slug":"clawhub-arberx-aeo","name":"aeo","canonicalUrl":"https://www.xpersona.co/agent/clawhub-arberx-aeo","canonicalPath":"/agent/clawhub-arberx-aeo","generatedAt":"2026-10-09T13:01:01.707Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T06:25:34.209Z","emptyReason":null},"description":"Run AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation. Skill: aeo Owner: arberx Summary: Run AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation. Tags: latest:7.2.0 Version history: v7.2.0 | 2026-09-07T23:51:08.552Z | user Give the derived duration budget room to be a ceiling (#76) v7","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 3.9K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17327ksxg2btxvszh6e1p12fx83k99a:aeo","sourceUrl":"https://clawhub.ai/arberx/aeo","homepage":"https://clawhub.ai/arberx/skills/aeo","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/arberx/aeo","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/arberx/skills/aeo","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":55,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Run AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output a"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T06:25:34.209Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T06:25:34.209Z","emptyReason":null},"stars":null,"forks":null,"downloads":3917,"packageName":null,"latestVersion":"7.2.0","tractionLabel":"3.9K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T06:25:34.209Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T06:25:34.209Z","lastCrawledAt":"2026-10-09T06:25:34.209Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T06:25:34.209Z","lastVerifiedAt":null,"highlights":[{"version":"7.2.0","createdAt":"2026-09-07T23:51:08.552Z","changelog":"Give the derived duration budget room to be a ceiling (#76)","fileCount":3,"zipByteSize":10694},{"version":"7.1.0","createdAt":"2026-08-28T18:22:49.284Z","changelog":"Scale the edge budget with the page count (#75)","fileCount":3,"zipByteSize":10498},{"version":"7.0.0","createdAt":"2026-08-26T15:29:33.032Z","changelog":"Make a page budget mean a page budget (#74)","fileCount":3,"zipByteSize":10507},{"version":"6.0.0","createdAt":"2026-08-16T20:36:40.332Z","changelog":"A link we could not fetch is not a broken link (#73)","fileCount":3,"zipByteSize":10653},{"version":"5.0.0","createdAt":"2026-08-14T01:22:06.203Z","changelog":"Fix a quadratic sitemap sampler that blocks the event loop, and stop reporting weight as a percentage (#72)","fileCount":3,"zipByteSize":10572},{"version":"4.7.0","createdAt":"2026-08-13T01:23:51.973Z","changelog":"feat: record where each link sits in the page (#71)","fileCount":3,"zipByteSize":10539},{"version":"4.6.2","createdAt":"2026-08-09T16:38:23.641Z","changelog":"release: dual-publish AEO audit 4.6.2 (#70)","fileCount":3,"zipByteSize":10535},{"version":"4.6.1","createdAt":"2026-08-09T15:58:34.860Z","changelog":"fix: recover failed public releases (#69)","fileCount":3,"zipByteSize":10655}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17327ksxg2btxvszh6e1p12fx83k99a:aeo","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-arberx-aeo/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-arberx-aeo/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-arberx-aeo/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-arberx-aeo/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-arberx-aeo/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-arberx-aeo/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T13:01:01.704Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-arberx-aeo/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-arberx-aeo/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-arberx-aeo/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-arberx-aeo/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T06:25:34.209Z","emptyReason":null},"readme":"Skill: aeo\n\nOwner: arberx\n\nSummary: Run AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation.\n\nTags: latest:7.2.0\n\nVersion history:\n\nv7.2.0 | 2026-09-07T23:51:08.552Z | user\n\nGive the derived duration budget room to be a ceiling (#76)\n\nv7.1.0 | 2026-08-28T18:22:49.284Z | user\n\nScale the edge budget with the page count (#75)\n\nv7.0.0 | 2026-08-26T15:29:33.032Z | user\n\nMake a page budget mean a page budget (#74)\n\nv6.0.0 | 2026-08-16T20:36:40.332Z | user\n\nA link we could not fetch is not a broken link (#73)\n\nv5.0.0 | 2026-08-14T01:22:06.203Z | user\n\nFix a quadratic sitemap sampler that blocks the event loop, and stop reporting weight as a percentage (#72)\n\nv4.7.0 | 2026-08-13T01:23:51.973Z | user\n\nfeat: record where each link sits in the page (#71)\n\nv4.6.2 | 2026-08-09T16:38:23.641Z | user\n\nrelease: dual-publish AEO audit 4.6.2 (#70)\n\nv4.6.1 | 2026-08-09T15:58:34.860Z | user\n\nfix: recover failed public releases (#69)\n\nv4.6.0 | 2026-08-09T02:19:02.492Z | user\n\nfeat: add bounded full-site crawl graph (#65)\n\nv4.5.0 | 2026-08-05T15:14:57.763Z | user\n\nCoverage, template grouping, and applicable-scoped rollups (4.5.0) (#64)\n\nv4.4.0 | 2026-07-26T22:55:13.638Z | user\n\nfeat: report faults that only exist between pages (#63)\n\nv4.3.0 | 2026-07-16T02:27:20.433Z | user\n\nfeat: publish private hosted audit engine (#61)\n\nv4.2.0 | 2026-06-27T17:09:26.896Z | user\n\nfeat: value-aware Content Signals Policy evaluation (4.2.0) (#57)\n\nv4.1.3 | 2026-06-25T01:29:29.692Z | user\n\nfix(security): route sitemap-mode fetches through SSRF guard (#55)\n\nv4.1.1 | 2026-06-20T03:17:06.683Z | user\n\nfix: robust engine-version resolution in AEO Audit Guard action (4.1.1) (#53)\n\nv4.1.0 | 2026-06-20T02:50:09.223Z | user\n\nfeat: AEO regression gate — compare subcommand + GitHub Action (4.1.0) (#52)\n\nv4.0.1 | 2026-06-17T14:23:06.106Z | user\n\nfix: XML-entity-decode sitemap <loc> URLs (#50) (#51)\n\nv4.0.0 | 2026-06-10T04:10:25.444Z | user\n\nfeat!: rename ai-readable-content factor to ai-access-files (#49)\n\nv3.1.0 | 2026-06-10T01:39:35.864Z | user\n\nfeat: page-specific factor classification + best-page context (3.1.0) (#48)\n\nv3.0.0 | 2026-06-08T23:51:26.786Z | user\n\nfeat!: remove letter grades and factor status, pure 0–100 score (3.0.0) (#47)\n\nv2.1.0 | 2026-06-04T00:08:09.579Z | user\n\nfeat: critical per-page defects, agent-native audit output (2.0.0) (#44)\n\nv1.13.0 | 2026-05-31T22:44:51.640Z | user\n\nfeat: dev-server + static-output auditing & spec.website alignment (1.13.0) (#40)\n\nv1.11.0 | 2026-05-29T20:58:41.602Z | user\n\nfeat(cli): add --require-meta flag to hard-fail on missing meta description (1.11.0) (#37) (#38)\n\nv1.10.0 | 2026-05-23T15:50:29.398Z | user\n\nfeat: sitemap fallback, content-negotiation diagnostic, domain-aware schema recs (1.10.0) (#36)\n\nv1.9.0 | 2026-05-22T14:38:22.227Z | user\n\nfeat(lighthouse): add optional Lighthouse factor via PageSpeed Insights (1.9.0) (#31)\n\nv1.8.1 | 2026-05-16T22:28:34.390Z | user\n\nReduce AI-Readable Content factor weight from 10% to 5%\n\nv1.8.0 | 2026-05-15T18:14:05.962Z | user\n\nfeat(snippet-eligibility): add indexing-directive analyzer per Google AEO guide (1.8.0) (#28)\n\nv1.7.1 | 2026-05-06T13:04:01.831Z | user\n\ndocs: surface runSitemapAudit for library users and default Schema skill mode to sitemap (1.7.1) (#27)\n\nv1.7.0 | 2026-04-30T17:19:39.583Z | user\n\nfeat(schema-validity): add page-level JSON-LD validity analyzer (1.7.0) (#26)\n\nv1.6.0 | 2026-04-28T19:06:34.333Z | user\n\nfeat(detect-platform): add platform/CMS/framework fingerprinting CLI mode (#25)\n\nv1.5.0 | 2026-04-26T13:44:54.883Z | user\n\nfeat(sitemap): bounded concurrency, default --limit 200, surface truncation (#23)\n\nv1.4.0 | 2026-04-18T17:20:44.633Z | user\n\nAdd agent-skill-exposure analyzer; surface per-issue affected URLs and flag short meta descriptions in sitemap audit\n\nv1.3.4 | 2026-04-15T16:58:51.469Z | user\n\nAdd technical-seo factor (H1, image alt, meta desc, canonical)\n\nv1.3.3 | 2026-03-25T12:25:59.178Z | user\n\nFix nested schema detection: extractSchemaTypes and findSchemaByType now recurse into nested JSON-LD objects (e.g. HowTo inside ProfessionalService). Fix E-E-A-T signal scoping: Person and Organization lookups now use authoritative scope only (top-level declarations + Article.author patterns), preventing score inflation from incidental nested references like Review.author.\n\nv1.3.2 | 2026-03-14T18:18:47.528Z | user\n\nAdd provenance metadata (homepage, repository) and drop broad Edit permissions to reduce OpenClaw security flags\n\nv1.3.1 | 2026-03-14T18:05:28.785Z | user\n\nReduce security flags: pin npx to @1, remove redundant Bash patterns, narrow file permissions\n\nv1.3.0 | 2026-03-14T00:22:25.874Z | user\n\nAdd sitemap audit mode: --sitemap for site-wide audits with cross-cutting issue detection, --limit to cap pages, --top-issues for aggregate patterns only\n\nv1.2.2 | 2026-03-09T20:23:12.722Z | user\n\nFix shell injection: replace $ARGUMENTS with safe quoted placeholders, scope Edit/Write permissions to specific file types\n\nv1.2.1 | 2026-03-09T19:10:17.053Z | user\n\nTighten skill permissions: scope npx to @ainyc/aeo-audit only, remove unused curl wildcard\n\nv1.2.0 | 2026-03-08T21:35:30.689Z | auto\n\n- Added support for running audits using the local repository build by allowing `pnpm run build` and `node bin/aeo-audit.js ...` commands.\n- Updated examples and workflow steps to clarify when to use the published package (`npx`) versus the local build (`node bin/aeo-audit.js`), depending on context.\n- Expanded the tool whitelist to include local build and execution commands.\n- Simplified and clarified instructions for auditing, fixing, schema validation, and llms.txt generation to support both published and local repo modes.\n\nv1.1.1 | 2026-03-06T02:33:59.072Z | user\n\nMake skills/aeo the single source of truth for npm and ClawHub\n\nv1.1.0 | 2026-03-06T02:23:37.460Z | user\n\nMake aeo the canonical umbrella skill and retire the aeo-audit slug\n\nv1.0.1 | 2026-03-05T16:53:26.104Z | auto\n\nAEO Skill v1.0.1 Changelog\n\n- Initial public release of the AEO (Answer Engine Optimization) toolkit.\n- Supports website audits across 13 AI citation factors with structured reports and grading.\n- Provides automated fixing for common AEO issues directly in the codebase following audit results.\n- Adds generation of llms.txt and llms-full.txt files based on site or project content.\n- Enables monitoring of AEO score changes over time or comparison with competitors.\n- Includes detailed validation and enhancement of structured data (JSON-LD/schema).\n- Robust error handling for audit failures, unreachable URLs, and non-HTML responses.\n\nArchive index:\n\nArchive v7.2.0: 3 files, 10694 bytes\n\nFiles: skill-card.md (2604b), SKILL.md (23683b), _meta.json (122b)\n\nFile v7.2.0:SKILL.md\n\n---\nname: aeo\ndescription: Run AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation.\nhomepage: https://canonry.ai\nrepository: https://github.com/Canonry/aeo-audit\nallowed-tools:\n  - Bash(npx @canonry/aeo-audit@4 *)\n  - Read\n  - Glob\n  - Grep\n  - Write(llms.txt)\n  - Write(llms-full.txt)\n  - Write(robots.txt)\n---\n\n# AEO\n\nWebsite: [canonry.ai](https://canonry.ai)\n\nOne skill for audit, preview-branch review, fixes, schema, llms.txt, and monitoring workflows.\n\n## Command\n\nAlways use the published package:\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" [flags] --format json\n```\n\n## Argument Safety\n\n**Never interpolate user input directly into shell commands.** Always:\n1. Validate that the target is either a URL matching `https://` / `http://` or a local filesystem path (static-output mode), and that it contains no shell metacharacters.\n2. Quote every argument individually (e.g., `npx @canonry/aeo-audit@4 \"https://example.com\" --format json`).\n3. Pass flags as separate, literal tokens — never construct command strings from raw user text.\n4. Reject arguments containing characters like `;`, `|`, `&`, `$`, `` ` ``, `(`, `)`, `{`, `}`, `<`, `>`, or newlines.\n\n## Modes\n\n- `audit`: score and diagnose a site\n- `fix`: apply code changes after an audit\n- `schema`: validate JSON-LD and entity consistency\n- `llms`: create or improve `llms.txt` and `llms-full.txt`\n- `monitor`: compare changes over time, compare a branch preview against production, or benchmark competitors\n- `detect-platform`: identify the CMS, site builder, framework, or hosting stack a site uses\n- `compare`: diff two saved `--format json` reports into a regression verdict + exit code (CI gate)\n\nIf no mode is provided, default to `audit`.\n\n## Examples\n\n- `audit https://example.com`\n- `audit https://example.com --sitemap`\n- `audit https://example.com --sitemap --limit 10`\n- `audit https://example.com --sitemap --top-issues`\n- `audit https://example.com --sitemap --format agent` (slim decision for agents)\n- `audit https://example.com --lighthouse`\n- `audit https://example.com --require-meta`\n- `audit https://example.com --sitemap --require-meta`\n- `audit http://localhost:3000 --allow-local`\n- `audit http://localhost:3000 --sitemap --rewrite-sitemap-origin --allow-local`\n- `audit http://localhost:3000 --sitemap --rewrite-sitemap-origin --allow-local --changed --base main --include-critical`\n- `audit https://staging.example.com --sitemap --rewrite-sitemap-origin`\n- `audit ./out` (static-output mode: audit built HTML offline)\n- `audit ./out --base-url https://example.com --require-meta`\n- `fix https://example.com`\n- `schema https://example.com`\n- `llms https://example.com`\n- `monitor https://site-a.com --compare https://site-b.com`\n- `detect-platform https://example.com`\n- `detect-platform https://example.com --min-confidence high`\n- `detect-platform --urls competitors.txt`\n- `detect-platform --urls https://a.com,https://b.com`\n- `compare --baseline baseline.json --current current.json` (fail CI on AEO regression)\n\n## Mode Selection\n\n- If the first argument is one of `audit`, `fix`, `schema`, `llms`, `monitor`, or `detect-platform`, use that mode.\n- If no explicit mode is given, infer the intent from the request and default to `audit`.\n\n## Audit\n\nUse for broad requests such as \"audit this site\" or \"why am I not being cited?\"\n\n1. Run:\n   ```bash\n   npx @canonry/aeo-audit@4 \"<url>\" [flags] --format json\n   ```\n2. Return:\n   - Overall score\n   - Short summary\n   - Factor breakdown\n   - Top strengths\n   - Top fixes\n   - Metadata such as fetch time and auxiliary file availability\n\n#### `--require-meta` (CI gate)\n\nPass `--require-meta` (single or sitemap mode) to force exit `1` whenever any audited page is missing `<meta name=\"description\">`, regardless of the otherwise score-based exit rule. Useful in CI pipelines that need to block deploys on a missing meta description even on otherwise-healthy sites.\n\n### Sitemap Mode\n\nUse `--sitemap` to audit all pages discovered from the site's sitemap:\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap https://example.com/sitemap.xml --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --limit 10 --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --top-issues --format json\n```\n\nFlags:\n- `--sitemap [url]` — auto-discover the sitemap (tries `/sitemap.xml`, then `/sitemap-index.xml`, then `Sitemap:` directives in `/robots.txt`) or provide an explicit URL\n- `--limit <n>` — cap pages audited (default 200, sampled across the site's URL templates rather than taken in sitemap order; `<priority>` orders instances within a template)\n- `--top-issues` — skip per-page output, show only cross-cutting patterns and critical defects\n- `--rewrite-sitemap-origin` — rewrite every `<loc>`'s origin to the target URL's origin (preserving path/query) before crawling. Use when the sitemap hardcodes the prod/canonical domain but you want to audit a staging host or local dev server.\n- `--changed` — filter sitemap URLs to static routes changed since `--base`; use for PR work\n- `--base <ref>` — git base for `--changed` (default `main`)\n- `--include-critical` — add critical paths to the changed-page set\n- `--critical-paths <list>` — comma-separated critical paths for `--include-critical`; defaults to `/`\n- `--require-meta` — force exit `1` if any audited page is missing `<meta name=\"description\">`, regardless of overall score (useful as a CI gate)\n- `--include-geo` / `--include-agent-skills` — honored per page in sitemap mode (adds the optional geographic-signals / agent-skill-exposure factors). `--lighthouse` is not available with `--sitemap`.\n\nPages are audited with bounded concurrency (5 in flight) to avoid hammering the target origin.\n\nReturns:\n- Per-page scores\n- **Critical defects** — binary, one-line-fix structural defects (an `<h1>` count other than one, a missing `<title>`, a missing meta description) surfaced **regardless of how few pages they affect**, with the offending pages named (homepage and high sitemap-`priority` pages first). These would otherwise be averaged into a passing factor score; the JSON field is `criticalDefects` and critical-severity ones are also promoted to the top of `prioritizedFixes`. Shown even with `--top-issues`.\n- Cross-cutting issues (factors failing across multiple pages), each with the best-scoring page (`bestScore`/`bestPageUrl`) and a `status`: `sitewide` (a real coverage gap) vs. `limited`/`opportunity` for page-specific factors (FAQ, definitions) that legitimately apply to only some page types\n- Aggregate score\n- Prioritized fixes (critical defects first, then site-wide gaps; page-specific `limited`/`opportunity` factors demoted below them, scoped to the page(s) that carry them), each costed as `templateCount` templates over `instanceCount` pages\n- **Templates** — pages that share a URL shape *and* score alike, collapsed into the template that produced them, with the page to fix on. \"194 property pages missing schema\" is one template edit, not 194\n- **Coverage** — what the aggregate score was taken over: pages audited/discovered and how many URL templates the sample reached, with a `confidence` of `full` / `representative` / `indicative`. A sample that missed whole templates is labelled `indicative` and does not speak for the sections it never saw\n\n### Preview / PR Audit Workflow\n\nUse this path for PR review, local production builds, preview deployments, and branch-vs-main questions. Prefer built-in flags over manual sitemap downloads, localtunnel glue, or ad hoc URL scripts.\n\nFor a local preview server whose sitemap emits production canonicals:\n\n```bash\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" \\\n  --sitemap \\\n  --rewrite-sitemap-origin \\\n  --allow-local \\\n  --changed \\\n  --base main \\\n  --include-critical \\\n  --format agent\n```\n\nGuidance:\n- Use `--allow-local` only when the user explicitly wants to audit localhost/private IPs.\n- Use `--rewrite-sitemap-origin` when a local or staging sitemap emits production canonicals.\n- Use `--changed --base <ref>` for PR work so unrelated site sections do not dominate the result.\n- Use `--include-critical --critical-paths /,/pricing,/contact` when important pages should always be checked.\n- If `--changed` finds no static routes, inspect the diff manually. Dynamic route templates cannot be safely converted to concrete URLs without route params; include known concrete paths with `--critical-paths` or audit explicit URLs separately.\n- Prefer `--format agent` for agent action, `--format json` for saved compare baselines, and `--format markdown` for human summaries.\n\nFor branch-vs-production regression review, produce comparable reports first, then run `compare`:\n\n```bash\nnpx @canonry/aeo-audit@4 \"https://production.example\" --sitemap --format json > baseline.json\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" --sitemap --rewrite-sitemap-origin --allow-local --format json > current.json\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json --format markdown\n```\n\nReport:\n- URLs audited or changed paths selected\n- Score/regression verdict from `compare`\n- Critical defects and prioritized fixes\n- Caveats such as local/private opt-in, sitemap origin rewriting, dynamic route templates skipped, or sitemap pages filtered out\n\n#### Machine-readable output (for agents)\n\nUse `--format json` for the full report, or **`--format agent`** for just the decision: `{ schemaVersion, tool, mode, url, score, pass, criticalDefectCount, issues }`, where `issues` is the ranked `prioritizedFixes` and the per-factor/per-page detail is omitted. Prefer `--format agent` when you only need to decide and act. Key fields for acting on the result without parsing prose:\n- `schemaVersion` (on every audit report) versions the JSON shape independently of the package version — pin to it and treat a major bump as breaking; absence means a pre-2.0 report.\n- `prioritizedFixes` is a ranked array of objects, each with a stable `id`, `kind`, optional `severity`, the complete `affectedPages` list (never truncated), `affectsHomepage`, `prevalencePct`, and a human `summary`. Cross-cutting fixes also carry `avgScore`, `bestScore`/`bestPageUrl`, and a `status` (`sitewide` | `limited` | `opportunity`) — treat `limited`/`opportunity` as page-specific tune-ups, not site-wide failures. It's the pre-computed to-do list — no need to re-rank factor scores yourself.\n- Stable identifiers everywhere — `criticalDefects[].id`, `prioritizedFixes[].id`, and every factor finding's `code` (e.g. `technical-seo.h1.multiple`) — let integrations key on codes rather than message strings.\n\n#### Auxiliary File Diagnostics\n\nWhen the audit fetches `/llms.txt`, `/llms-full.txt`, `/robots.txt`, and `/sitemap.xml`, it probes once with `Accept: text/markdown` to detect a **content-negotiation** trap: file responds OK to a bare request but returns a non-2xx response when the client prefers markdown. This catches Astro / Vercel / Starlight setups that 307-redirect `.txt` → non-existent `.md` for markdown-accepting clients, making the file invisible to AI content-extraction tools even though the file exists. The diagnostic surfaces as a finding on the **AI Access Files (llms.txt, sitemap)** factor.\n\n### Local Dev / Staging Targets\n\nBy default the audit blocks any URL that resolves to a private, loopback, or link-local address (SSRF protection). When the user wants to audit **their own** dev or staging server, pass `--allow-local` (alias `--allow-private`):\n\n```bash\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" --allow-local --format json\nnpx @canonry/aeo-audit@4 \"http://10.0.5.20\" --allow-private --format json\n```\n\n- Pass the explicit `http://` scheme for local dev servers — a bare host defaults to `https://`.\n- The relaxation is scoped to the **single host named on the CLI**, evaluated per hop. A redirect or sitemap `<loc>` pointing at any other private host (e.g. `169.254.169.254`) stays blocked.\n- To audit a whole local site whose sitemap hardcodes the prod domain, combine with sitemap origin rewriting:\n\n```bash\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" --sitemap --rewrite-sitemap-origin --allow-local --format json\n```\n\n### Static-Output Mode\n\nWhen the user wants to audit **built HTML offline** (CI on a `next export` / `dist` / `out` directory, or before deploying), pass a filesystem path instead of a URL:\n\n```bash\n# A directory of built HTML (aggregated like sitemap mode)\nnpx @canonry/aeo-audit@4 \"./out\" --base-url https://example.com --format json\n# A single built file\nnpx @canonry/aeo-audit@4 \"./dist/index.html\" --format json\n# Gate CI on missing meta descriptions across the build\nnpx @canonry/aeo-audit@4 \"./out\" --require-meta --format json\n```\n\n- A `.html`/`.htm` file → single-page report; a directory → aggregated report (`--limit`, `--top-issues`, `--factors`, `--include-geo`, `--include-agent-skills`, `--require-meta` apply).\n- `--base-url <url>` maps files to page URLs (`out/about/index.html` → `<base>/about/`; default `https://localhost`). `index.html` collapses to its directory URL; other files drop the `.html` extension.\n- `llms.txt`, `llms-full.txt`, `robots.txt`, and `sitemap.xml` are read from the directory root when present.\n- **Partial coverage:** server-only signals (redirects, `X-Robots-Tag`, `Last-Modified`, `Link` headers) aren't visible from static files. Recommend auditing the deployed URL for full coverage.\n\n### Compare / Regression Mode\n\nWhen the user wants to **fail CI on an AEO regression** (a PR dropped the score, broke a page, or introduced a structural defect), use the `compare` subcommand. It diffs two saved `--format json` reports — a baseline and the current run — and exits non-zero on a regression. It runs no audit and no network; it only reads reports.\n\n```bash\n# 1. Produce the current report (any mode's --format json output works)\nnpx @canonry/aeo-audit@4 \"./out\" --base-url https://example.com --format json > current.json\n# 2. Diff against a stored baseline — exit 1 if it regressed\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json\n# Write a Markdown summary (for a PR comment) and tighten the overall gate\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json --overall-tolerance 0 --md-out diff.md\n# Committed/artifact baselines: hard-fail (exit 2) if factor set / engine major differ\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json --strict-comparability\n```\n\n- **A regression is any of:** overall/aggregate drop > `--overall-tolerance` (default 2); a single page drop > `--page-tolerance` (default 5); a single factor drop > `--factor-tolerance` (default 8); a page that was auditing successfully now erroring; a new `severity:critical` defect (`--fail-on-new-critical`, default on); or a major report-schema change. Score/page/factor deltas only gate when the two runs are **comparable** (same factor set, no major engine change) — otherwise they're warnings, not failures.\n- `missing-meta-description` is `severity:warning`, so it does **not** trip `--fail-on-new-critical`; use `--require-meta` on the audit or `--fail-on warnings` here. Removed pages and new warnings are report-only unless promoted with `--fail-on removed-pages,warnings`.\n- **Exit codes:** `0` = no regression / improvement / first run (no baseline); `1` = regression; `2` = misconfiguration (mode mismatch, unreadable report, missing `--current`, or incomparable factor-set/engine under `--strict-comparability`). `--report-only` always exits `0` (soak mode).\n- Both reports must be the same mode (two single, or two multi-page). stdout carries only the `CompareReport` JSON (or Markdown with `--format markdown`); diagnostics go to stderr.\n\n### Lighthouse Mode\n\nUse `--lighthouse` when the user wants page speed, accessibility, or best-practices scoring alongside the AEO factors. It calls Google PageSpeed Insights (mobile strategy) and aggregates Performance + Accessibility + Best Practices into a single optional factor (weight 8).\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --lighthouse --format json\nPAGESPEED_API_KEY=xxx npx @canonry/aeo-audit@4 \"<url>\" --lighthouse --format json\n```\n\nConstraints:\n- Single-URL only — cannot combine with `--sitemap` or `--detect-platform`. Each Lighthouse audit takes 15-30s, which would blow up sitemap runtime.\n- Optional `PAGESPEED_API_KEY` env var lifts anonymous PSI rate limits (25k/day unauthenticated).\n- On PSI failure (unreachable target, timeout, HTTP error) the factor scores 0 and surfaces a `timeout` or `unreachable` finding rather than throwing — the rest of the audit still runs.\n\n### Detect Platform Mode\n\nUse `--detect-platform` when the user wants to know what stack a site is built on (e.g., \"is this WordPress?\", \"what framework does competitor X use?\", \"is this site custom-built?\"). This is much faster than a full audit because it skips analyzer scoring.\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --detect-platform --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --detect-platform --min-confidence high --format json\n```\n\nFlags:\n- `--detect-platform` — switch to detection mode instead of auditing\n- `--min-confidence <lvl>` — filter to `low` (default), `medium`, or `high` confidence\n- `--urls <src>` — run on multiple URLs at once (file path, comma-separated list, or `-` for stdin)\n- `--concurrency <n>` — max in-flight fetches in batch mode (default 5)\n\nThe report groups detections by category (CMS, site builder, e-commerce, framework, SSG, hosting), each with a confidence bucket, a 0–100 score, an optional version, and the signals that matched. When the report's `isCustom` flag is true, no CMS/site-builder/e-commerce platform was identified — the site is likely custom-built. Exit code is `0` when at least one platform is detected, `1` otherwise.\n\n#### Batch detection\n\nWhen the user wants to fingerprint many sites at once (competitor lists, customer cohorts), pass `--urls`:\n\n```bash\nnpx @canonry/aeo-audit@4 --detect-platform --urls urls.txt --format json\nnpx @canonry/aeo-audit@4 --detect-platform --urls https://a.com,https://b.com --format json\ncat urls.txt | npx @canonry/aeo-audit@4 --detect-platform --urls - --format json\n```\n\nThe batch report contains a `results` array; each entry has `status: 'success'` or `'error'`, plus the same shape as a single-URL report on success. Per-URL fetch errors do not abort the run. Exit code is `0` when at least one URL succeeded, `1` otherwise.\n\n## Fix\n\nUse when the user wants code changes applied after the audit.\n\n1. Run:\n   ```bash\n   npx @canonry/aeo-audit@4 \"<url>\" [flags] --format json\n   ```\n2. Find factors scoring below 70 (lowest first).\n3. Apply targeted fixes in the current codebase.\n4. Prioritize:\n   - Structured data and schema completeness\n   - `llms.txt` and `llms-full.txt`\n   - `robots.txt` crawler access\n   - E-E-A-T signals\n   - FAQ markup\n   - freshness metadata\n   - agent-readiness signals: per-page Markdown source endpoints, `robots.txt` `Content-Signal` directives (the audit scores the values — set `ai-input=yes`/`search=yes` to permit AI answers and search indexing; `ai-input=no` opts out of the real-time AI use AEO depends on), and A2A agent cards (aligned with specification.website)\n5. Re-run the audit and report the score delta.\n\nRules:\n- Always explain proposed changes and get user confirmation before editing files.\n- Do not remove existing schema or content unless the user asks.\n- Preserve existing code style and patterns.\n- If a fix is ambiguous or high-risk, explain the tradeoff before editing.\n\n## Schema\n\nUse when the request is specifically about JSON-LD or schema quality.\n\nValidity issues like duplicate singleton `@type`s and JSON parse errors are **per page**, so a homepage-only audit misses every subpage. Default to sitemap mode for site-wide schema requests (\"audit my schema\", \"are my FAQ blocks valid?\"); use single-URL mode only when the user names one specific page.\n\nSite-wide (default):\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --top-issues --format json --factors structured-data,schema-completeness,schema-validity,entity-consistency\n```\n\nSingle page:\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --format json --factors structured-data,schema-completeness,schema-validity,entity-consistency\n```\n\nReport:\n- Schema types found\n- Property completeness by type\n- Missing recommended properties\n- **Validity errors** (duplicate singleton `@type`s, JSON parse errors, empty `<script>` blocks) — surface these prominently regardless of overall score; Google drops invalid blocks silently from rich results\n- Entity consistency issues\n- In sitemap mode: list every affected URL for each validity error so the user can locate per-page duplicates\n\nProvide corrected JSON-LD examples when useful.\n\nChecklist:\n- `LocalBusiness`: name, address, telephone, openingHours, priceRange, image, url, geo, areaServed, sameAs\n- `FAQPage`: mainEntity with at least 3 Q&A pairs (and only **one** `FAQPage` block per page — duplicates invalidate rich results)\n- `HowTo`: name and at least 3 steps (singleton — only one per page)\n- `Organization`: name, logo, contactPoint, sameAs, foundingDate, url, description\n- Singletons that must not repeat per page: `FAQPage`, `HowTo`, `Article`, `BlogPosting`, `NewsArticle`, `BreadcrumbList`, `Product`, `Recipe`\n\n## llms.txt\n\nUse when the user wants `llms.txt` or `llms-full.txt` created or improved.\n\nIf a URL is provided:\n1. Run:\n   ```bash\n   npx @canonry/aeo-audit@4 \"<url>\" [flags] --format json --factors ai-access-files\n   ```\n2. Inspect existing AI-readable files if present.\n3. Extract key content from the site.\n4. Generate improved `llms.txt` and `llms-full.txt`.\n\nIf no URL is provided:\n1. Inspect the current project.\n2. Extract business name, services, FAQs, contact info, and metadata.\n3. Generate both files from local sources.\n\nAfter generation:\n- Add `<link rel=\"alternate\" type=\"text/markdown\" href=\"/llms.txt\">` when appropriate.\n- Expose per-page Markdown source endpoints (a `.md` URL or content negotiation) advertised via `<link rel=\"alternate\" type=\"text/markdown\">` — a scored AI-readable signal.\n- Suggest adding the files to the sitemap.\n\n## Monitor\n\nUse when the user wants progress tracking or a competitor comparison.\n\nSingle URL:\n1. Run the audit.\n2. Compare against prior results in `.aeo-audit-history/` if present.\n3. Show overall and per-factor deltas.\n4. Save the current result.\n\nComparison mode:\n1. For branch-vs-production, produce baseline and current `--format json` reports in the same mode, then run the `compare` subcommand.\n2. For competitor benchmarking, audit both public URLs and show side-by-side factor deltas.\n3. Highlight advantages, weaknesses, regressions, and priority gaps.\n\n## Behavior\n\n- If the task needs a deployed site and no URL is provided, ask for the URL.\n- If the task is diagnosis only, do not edit files.\n- If the task is a fix request, make edits and verify with a rerun when possible.\n- If the URL is unreachable or not HTML, report the exact failure.\n- If a local/private URL is requested and `--allow-local` is missing, rerun with `--allow-local` only after confirming local preview auditing is intended.\n- If sitemap mode appears to audit production during preview work, rerun with `--rewrite-sitemap-origin`.\n- Prefer concise, evidence-based recommendations over generic SEO advice.\n\nFile v7.2.0:_meta.json\n\n{\n  \"ownerId\": \"kn7frv4wj3y54yjs1331dcchvh81414c\",\n  \"slug\": \"aeo\",\n  \"version\": \"7.2.0\",\n  \"publishedAt\": 1788825068552\n}\n\nFile v7.2.0:skill-card.md\n\n## Description:\n\nRun AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[arberx](https://clawhub.ai/user/arberx)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, site owners, and marketing engineers use this skill to audit and improve how websites expose content to answer engines, crawlers, schema validators, and AI-readable files. It supports deployed sites, preview branches, local builds with explicit private-target opt-in, static HTML output, regression checks, and guided fixes.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill runs a dynamically resolved npm CLI with the agent's normal file, environment, and network permissions.\n\nMitigation: Run it in a sandbox with minimal environment variables, and pin or preinstall a reviewed exact package version before use in sensitive repositories or CI.\n\nRisk: Local or private preview audits can reach internal targets when the user explicitly opts in.\n\nMitigation: Use local/private audit flags only for targets the user controls, keep the scope to the named host, and review any sitemap origin rewriting before crawling.\n\nRisk: Fix and llms.txt workflows may modify site files or AI-readable public metadata.\n\nMitigation: Require user confirmation before edits, review generated diffs, and rerun the relevant audit or validation mode after changes.\n\n## Reference(s):\n\n- [Canonry AEO Homepage](https://canonry.ai)\n- [ClawHub Skill Page](https://clawhub.ai/arberx/skills/aeo)\n- [Publisher Profile](https://clawhub.ai/user/arberx)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands, JSON or agent-format audit reports, and file edits for approved fixes.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May generate or update llms.txt, llms-full.txt, robots.txt, structured data, and comparison summaries when the selected workflow calls for those outputs.]\n\n## Skill Version(s):\n\n7.2.0 (source: ClawHub release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v7.1.0: 3 files, 10498 bytes\n\nFiles: skill-card.md (2136b), SKILL.md (23683b), _meta.json (122b)\n\nFile v7.1.0:SKILL.md\n\n---\nname: aeo\ndescription: Run AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation.\nhomepage: https://canonry.ai\nrepository: https://github.com/Canonry/aeo-audit\nallowed-tools:\n  - Bash(npx @canonry/aeo-audit@4 *)\n  - Read\n  - Glob\n  - Grep\n  - Write(llms.txt)\n  - Write(llms-full.txt)\n  - Write(robots.txt)\n---\n\n# AEO\n\nWebsite: [canonry.ai](https://canonry.ai)\n\nOne skill for audit, preview-branch review, fixes, schema, llms.txt, and monitoring workflows.\n\n## Command\n\nAlways use the published package:\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" [flags] --format json\n```\n\n## Argument Safety\n\n**Never interpolate user input directly into shell commands.** Always:\n1. Validate that the target is either a URL matching `https://` / `http://` or a local filesystem path (static-output mode), and that it contains no shell metacharacters.\n2. Quote every argument individually (e.g., `npx @canonry/aeo-audit@4 \"https://example.com\" --format json`).\n3. Pass flags as separate, literal tokens — never construct command strings from raw user text.\n4. Reject arguments containing characters like `;`, `|`, `&`, `$`, `` ` ``, `(`, `)`, `{`, `}`, `<`, `>`, or newlines.\n\n## Modes\n\n- `audit`: score and diagnose a site\n- `fix`: apply code changes after an audit\n- `schema`: validate JSON-LD and entity consistency\n- `llms`: create or improve `llms.txt` and `llms-full.txt`\n- `monitor`: compare changes over time, compare a branch preview against production, or benchmark competitors\n- `detect-platform`: identify the CMS, site builder, framework, or hosting stack a site uses\n- `compare`: diff two saved `--format json` reports into a regression verdict + exit code (CI gate)\n\nIf no mode is provided, default to `audit`.\n\n## Examples\n\n- `audit https://example.com`\n- `audit https://example.com --sitemap`\n- `audit https://example.com --sitemap --limit 10`\n- `audit https://example.com --sitemap --top-issues`\n- `audit https://example.com --sitemap --format agent` (slim decision for agents)\n- `audit https://example.com --lighthouse`\n- `audit https://example.com --require-meta`\n- `audit https://example.com --sitemap --require-meta`\n- `audit http://localhost:3000 --allow-local`\n- `audit http://localhost:3000 --sitemap --rewrite-sitemap-origin --allow-local`\n- `audit http://localhost:3000 --sitemap --rewrite-sitemap-origin --allow-local --changed --base main --include-critical`\n- `audit https://staging.example.com --sitemap --rewrite-sitemap-origin`\n- `audit ./out` (static-output mode: audit built HTML offline)\n- `audit ./out --base-url https://example.com --require-meta`\n- `fix https://example.com`\n- `schema https://example.com`\n- `llms https://example.com`\n- `monitor https://site-a.com --compare https://site-b.com`\n- `detect-platform https://example.com`\n- `detect-platform https://example.com --min-confidence high`\n- `detect-platform --urls competitors.txt`\n- `detect-platform --urls https://a.com,https://b.com`\n- `compare --baseline baseline.json --current current.json` (fail CI on AEO regression)\n\n## Mode Selection\n\n- If the first argument is one of `audit`, `fix`, `schema`, `llms`, `monitor`, or `detect-platform`, use that mode.\n- If no explicit mode is given, infer the intent from the request and default to `audit`.\n\n## Audit\n\nUse for broad requests such as \"audit this site\" or \"why am I not being cited?\"\n\n1. Run:\n   ```bash\n   npx @canonry/aeo-audit@4 \"<url>\" [flags] --format json\n   ```\n2. Return:\n   - Overall score\n   - Short summary\n   - Factor breakdown\n   - Top strengths\n   - Top fixes\n   - Metadata such as fetch time and auxiliary file availability\n\n#### `--require-meta` (CI gate)\n\nPass `--require-meta` (single or sitemap mode) to force exit `1` whenever any audited page is missing `<meta name=\"description\">`, regardless of the otherwise score-based exit rule. Useful in CI pipelines that need to block deploys on a missing meta description even on otherwise-healthy sites.\n\n### Sitemap Mode\n\nUse `--sitemap` to audit all pages discovered from the site's sitemap:\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap https://example.com/sitemap.xml --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --limit 10 --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --top-issues --format json\n```\n\nFlags:\n- `--sitemap [url]` — auto-discover the sitemap (tries `/sitemap.xml`, then `/sitemap-index.xml`, then `Sitemap:` directives in `/robots.txt`) or provide an explicit URL\n- `--limit <n>` — cap pages audited (default 200, sampled across the site's URL templates rather than taken in sitemap order; `<priority>` orders instances within a template)\n- `--top-issues` — skip per-page output, show only cross-cutting patterns and critical defects\n- `--rewrite-sitemap-origin` — rewrite every `<loc>`'s origin to the target URL's origin (preserving path/query) before crawling. Use when the sitemap hardcodes the prod/canonical domain but you want to audit a staging host or local dev server.\n- `--changed` — filter sitemap URLs to static routes changed since `--base`; use for PR work\n- `--base <ref>` — git base for `--changed` (default `main`)\n- `--include-critical` — add critical paths to the changed-page set\n- `--critical-paths <list>` — comma-separated critical paths for `--include-critical`; defaults to `/`\n- `--require-meta` — force exit `1` if any audited page is missing `<meta name=\"description\">`, regardless of overall score (useful as a CI gate)\n- `--include-geo` / `--include-agent-skills` — honored per page in sitemap mode (adds the optional geographic-signals / agent-skill-exposure factors). `--lighthouse` is not available with `--sitemap`.\n\nPages are audited with bounded concurrency (5 in flight) to avoid hammering the target origin.\n\nReturns:\n- Per-page scores\n- **Critical defects** — binary, one-line-fix structural defects (an `<h1>` count other than one, a missing `<title>`, a missing meta description) surfaced **regardless of how few pages they affect**, with the offending pages named (homepage and high sitemap-`priority` pages first). These would otherwise be averaged into a passing factor score; the JSON field is `criticalDefects` and critical-severity ones are also promoted to the top of `prioritizedFixes`. Shown even with `--top-issues`.\n- Cross-cutting issues (factors failing across multiple pages), each with the best-scoring page (`bestScore`/`bestPageUrl`) and a `status`: `sitewide` (a real coverage gap) vs. `limited`/`opportunity` for page-specific factors (FAQ, definitions) that legitimately apply to only some page types\n- Aggregate score\n- Prioritized fixes (critical defects first, then site-wide gaps; page-specific `limited`/`opportunity` factors demoted below them, scoped to the page(s) that carry them), each costed as `templateCount` templates over `instanceCount` pages\n- **Templates** — pages that share a URL shape *and* score alike, collapsed into the template that produced them, with the page to fix on. \"194 property pages missing schema\" is one template edit, not 194\n- **Coverage** — what the aggregate score was taken over: pages audited/discovered and how many URL templates the sample reached, with a `confidence` of `full` / `representative` / `indicative`. A sample that missed whole templates is labelled `indicative` and does not speak for the sections it never saw\n\n### Preview / PR Audit Workflow\n\nUse this path for PR review, local production builds, preview deployments, and branch-vs-main questions. Prefer built-in flags over manual sitemap downloads, localtunnel glue, or ad hoc URL scripts.\n\nFor a local preview server whose sitemap emits production canonicals:\n\n```bash\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" \\\n  --sitemap \\\n  --rewrite-sitemap-origin \\\n  --allow-local \\\n  --changed \\\n  --base main \\\n  --include-critical \\\n  --format agent\n```\n\nGuidance:\n- Use `--allow-local` only when the user explicitly wants to audit localhost/private IPs.\n- Use `--rewrite-sitemap-origin` when a local or staging sitemap emits production canonicals.\n- Use `--changed --base <ref>` for PR work so unrelated site sections do not dominate the result.\n- Use `--include-critical --critical-paths /,/pricing,/contact` when important pages should always be checked.\n- If `--changed` finds no static routes, inspect the diff manually. Dynamic route templates cannot be safely converted to concrete URLs without route params; include known concrete paths with `--critical-paths` or audit explicit URLs separately.\n- Prefer `--format agent` for agent action, `--format json` for saved compare baselines, and `--format markdown` for human summaries.\n\nFor branch-vs-production regression review, produce comparable reports first, then run `compare`:\n\n```bash\nnpx @canonry/aeo-audit@4 \"https://production.example\" --sitemap --format json > baseline.json\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" --sitemap --rewrite-sitemap-origin --allow-local --format json > current.json\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json --format markdown\n```\n\nReport:\n- URLs audited or changed paths selected\n- Score/regression verdict from `compare`\n- Critical defects and prioritized fixes\n- Caveats such as local/private opt-in, sitemap origin rewriting, dynamic route templates skipped, or sitemap pages filtered out\n\n#### Machine-readable output (for agents)\n\nUse `--format json` for the full report, or **`--format agent`** for just the decision: `{ schemaVersion, tool, mode, url, score, pass, criticalDefectCount, issues }`, where `issues` is the ranked `prioritizedFixes` and the per-factor/per-page detail is omitted. Prefer `--format agent` when you only need to decide and act. Key fields for acting on the result without parsing prose:\n- `schemaVersion` (on every audit report) versions the JSON shape independently of the package version — pin to it and treat a major bump as breaking; absence means a pre-2.0 report.\n- `prioritizedFixes` is a ranked array of objects, each with a stable `id`, `kind`, optional `severity`, the complete `affectedPages` list (never truncated), `affectsHomepage`, `prevalencePct`, and a human `summary`. Cross-cutting fixes also carry `avgScore`, `bestScore`/`bestPageUrl`, and a `status` (`sitewide` | `limited` | `opportunity`) — treat `limited`/`opportunity` as page-specific tune-ups, not site-wide failures. It's the pre-computed to-do list — no need to re-rank factor scores yourself.\n- Stable identifiers everywhere — `criticalDefects[].id`, `prioritizedFixes[].id`, and every factor finding's `code` (e.g. `technical-seo.h1.multiple`) — let integrations key on codes rather than message strings.\n\n#### Auxiliary File Diagnostics\n\nWhen the audit fetches `/llms.txt`, `/llms-full.txt`, `/robots.txt`, and `/sitemap.xml`, it probes once with `Accept: text/markdown` to detect a **content-negotiation** trap: file responds OK to a bare request but returns a non-2xx response when the client prefers markdown. This catches Astro / Vercel / Starlight setups that 307-redirect `.txt` → non-existent `.md` for markdown-accepting clients, making the file invisible to AI content-extraction tools even though the file exists. The diagnostic surfaces as a finding on the **AI Access Files (llms.txt, sitemap)** factor.\n\n### Local Dev / Staging Targets\n\nBy default the audit blocks any URL that resolves to a private, loopback, or link-local address (SSRF protection). When the user wants to audit **their own** dev or staging server, pass `--allow-local` (alias `--allow-private`):\n\n```bash\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" --allow-local --format json\nnpx @canonry/aeo-audit@4 \"http://10.0.5.20\" --allow-private --format json\n```\n\n- Pass the explicit `http://` scheme for local dev servers — a bare host defaults to `https://`.\n- The relaxation is scoped to the **single host named on the CLI**, evaluated per hop. A redirect or sitemap `<loc>` pointing at any other private host (e.g. `169.254.169.254`) stays blocked.\n- To audit a whole local site whose sitemap hardcodes the prod domain, combine with sitemap origin rewriting:\n\n```bash\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" --sitemap --rewrite-sitemap-origin --allow-local --format json\n```\n\n### Static-Output Mode\n\nWhen the user wants to audit **built HTML offline** (CI on a `next export` / `dist` / `out` directory, or before deploying), pass a filesystem path instead of a URL:\n\n```bash\n# A directory of built HTML (aggregated like sitemap mode)\nnpx @canonry/aeo-audit@4 \"./out\" --base-url https://example.com --format json\n# A single built file\nnpx @canonry/aeo-audit@4 \"./dist/index.html\" --format json\n# Gate CI on missing meta descriptions across the build\nnpx @canonry/aeo-audit@4 \"./out\" --require-meta --format json\n```\n\n- A `.html`/`.htm` file → single-page report; a directory → aggregated report (`--limit`, `--top-issues`, `--factors`, `--include-geo`, `--include-agent-skills`, `--require-meta` apply).\n- `--base-url <url>` maps files to page URLs (`out/about/index.html` → `<base>/about/`; default `https://localhost`). `index.html` collapses to its directory URL; other files drop the `.html` extension.\n- `llms.txt`, `llms-full.txt`, `robots.txt`, and `sitemap.xml` are read from the directory root when present.\n- **Partial coverage:** server-only signals (redirects, `X-Robots-Tag`, `Last-Modified`, `Link` headers) aren't visible from static files. Recommend auditing the deployed URL for full coverage.\n\n### Compare / Regression Mode\n\nWhen the user wants to **fail CI on an AEO regression** (a PR dropped the score, broke a page, or introduced a structural defect), use the `compare` subcommand. It diffs two saved `--format json` reports — a baseline and the current run — and exits non-zero on a regression. It runs no audit and no network; it only reads reports.\n\n```bash\n# 1. Produce the current report (any mode's --format json output works)\nnpx @canonry/aeo-audit@4 \"./out\" --base-url https://example.com --format json > current.json\n# 2. Diff against a stored baseline — exit 1 if it regressed\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json\n# Write a Markdown summary (for a PR comment) and tighten the overall gate\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json --overall-tolerance 0 --md-out diff.md\n# Committed/artifact baselines: hard-fail (exit 2) if factor set / engine major differ\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json --strict-comparability\n```\n\n- **A regression is any of:** overall/aggregate drop > `--overall-tolerance` (default 2); a single page drop > `--page-tolerance` (default 5); a single factor drop > `--factor-tolerance` (default 8); a page that was auditing successfully now erroring; a new `severity:critical` defect (`--fail-on-new-critical`, default on); or a major report-schema change. Score/page/factor deltas only gate when the two runs are **comparable** (same factor set, no major engine change) — otherwise they're warnings, not failures.\n- `missing-meta-description` is `severity:warning`, so it does **not** trip `--fail-on-new-critical`; use `--require-meta` on the audit or `--fail-on warnings` here. Removed pages and new warnings are report-only unless promoted with `--fail-on removed-pages,warnings`.\n- **Exit codes:** `0` = no regression / improvement / first run (no baseline); `1` = regression; `2` = misconfiguration (mode mismatch, unreadable report, missing `--current`, or incomparable factor-set/engine under `--strict-comparability`). `--report-only` always exits `0` (soak mode).\n- Both reports must be the same mode (two single, or two multi-page). stdout carries only the `CompareReport` JSON (or Markdown with `--format markdown`); diagnostics go to stderr.\n\n### Lighthouse Mode\n\nUse `--lighthouse` when the user wants page speed, accessibility, or best-practices scoring alongside the AEO factors. It calls Google PageSpeed Insights (mobile strategy) and aggregates Performance + Accessibility + Best Practices into a single optional factor (weight 8).\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --lighthouse --format json\nPAGESPEED_API_KEY=xxx npx @canonry/aeo-audit@4 \"<url>\" --lighthouse --format json\n```\n\nConstraints:\n- Single-URL only — cannot combine with `--sitemap` or `--detect-platform`. Each Lighthouse audit takes 15-30s, which would blow up sitemap runtime.\n- Optional `PAGESPEED_API_KEY` env var lifts anonymous PSI rate limits (25k/day unauthenticated).\n- On PSI failure (unreachable target, timeout, HTTP error) the factor scores 0 and surfaces a `timeout` or `unreachable` finding rather than throwing — the rest of the audit still runs.\n\n### Detect Platform Mode\n\nUse `--detect-platform` when the user wants to know what stack a site is built on (e.g., \"is this WordPress?\", \"what framework does competitor X use?\", \"is this site custom-built?\"). This is much faster than a full audit because it skips analyzer scoring.\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --detect-platform --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --detect-platform --min-confidence high --format json\n```\n\nFlags:\n- `--detect-platform` — switch to detection mode instead of auditing\n- `--min-confidence <lvl>` — filter to `low` (default), `medium`, or `high` confidence\n- `--urls <src>` — run on multiple URLs at once (file path, comma-separated list, or `-` for stdin)\n- `--concurrency <n>` — max in-flight fetches in batch mode (default 5)\n\nThe report groups detections by category (CMS, site builder, e-commerce, framework, SSG, hosting), each with a confidence bucket, a 0–100 score, an optional version, and the signals that matched. When the report's `isCustom` flag is true, no CMS/site-builder/e-commerce platform was identified — the site is likely custom-built. Exit code is `0` when at least one platform is detected, `1` otherwise.\n\n#### Batch detection\n\nWhen the user wants to fingerprint many sites at once (competitor lists, customer cohorts), pass `--urls`:\n\n```bash\nnpx @canonry/aeo-audit@4 --detect-platform --urls urls.txt --format json\nnpx @canonry/aeo-audit@4 --detect-platform --urls https://a.com,https://b.com --format json\ncat urls.txt | npx @canonry/aeo-audit@4 --detect-platform --urls - --format json\n```\n\nThe batch report contains a `results` array; each entry has `status: 'success'` or `'error'`, plus the same shape as a single-URL report on success. Per-URL fetch errors do not abort the run. Exit code is `0` when at least one URL succeeded, `1` otherwise.\n\n## Fix\n\nUse when the user wants code changes applied after the audit.\n\n1. Run:\n   ```bash\n   npx @canonry/aeo-audit@4 \"<url>\" [flags] --format json\n   ```\n2. Find factors scoring below 70 (lowest first).\n3. Apply targeted fixes in the current codebase.\n4. Prioritize:\n   - Structured data and schema completeness\n   - `llms.txt` and `llms-full.txt`\n   - `robots.txt` crawler access\n   - E-E-A-T signals\n   - FAQ markup\n   - freshness metadata\n   - agent-readiness signals: per-page Markdown source endpoints, `robots.txt` `Content-Signal` directives (the audit scores the values — set `ai-input=yes`/`search=yes` to permit AI answers and search indexing; `ai-input=no` opts out of the real-time AI use AEO depends on), and A2A agent cards (aligned with specification.website)\n5. Re-run the audit and report the score delta.\n\nRules:\n- Always explain proposed changes and get user confirmation before editing files.\n- Do not remove existing schema or content unless the user asks.\n- Preserve existing code style and patterns.\n- If a fix is ambiguous or high-risk, explain the tradeoff before editing.\n\n## Schema\n\nUse when the request is specifically about JSON-LD or schema quality.\n\nValidity issues like duplicate singleton `@type`s and JSON parse errors are **per page**, so a homepage-only audit misses every subpage. Default to sitemap mode for site-wide schema requests (\"audit my schema\", \"are my FAQ blocks valid?\"); use single-URL mode only when the user names one specific page.\n\nSite-wide (default):\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --top-issues --format json --factors structured-data,schema-completeness,schema-validity,entity-consistency\n```\n\nSingle page:\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --format json --factors structured-data,schema-completeness,schema-validity,entity-consistency\n```\n\nReport:\n- Schema types found\n- Property completeness by type\n- Missing recommended properties\n- **Validity errors** (duplicate singleton `@type`s, JSON parse errors, empty `<script>` blocks) — surface these prominently regardless of overall score; Google drops invalid blocks silently from rich results\n- Entity consistency issues\n- In sitemap mode: list every affected URL for each validity error so the user can locate per-page duplicates\n\nProvide corrected JSON-LD examples when useful.\n\nChecklist:\n- `LocalBusiness`: name, address, telephone, openingHours, priceRange, image, url, geo, areaServed, sameAs\n- `FAQPage`: mainEntity with at least 3 Q&A pairs (and only **one** `FAQPage` block per page — duplicates invalidate rich results)\n- `HowTo`: name and at least 3 steps (singleton — only one per page)\n- `Organization`: name, logo, contactPoint, sameAs, foundingDate, url, description\n- Singletons that must not repeat per page: `FAQPage`, `HowTo`, `Article`, `BlogPosting`, `NewsArticle`, `BreadcrumbList`, `Product`, `Recipe`\n\n## llms.txt\n\nUse when the user wants `llms.txt` or `llms-full.txt` created or improved.\n\nIf a URL is provided:\n1. Run:\n   ```bash\n   npx @canonry/aeo-audit@4 \"<url>\" [flags] --format json --factors ai-access-files\n   ```\n2. Inspect existing AI-readable files if present.\n3. Extract key content from the site.\n4. Generate improved `llms.txt` and `llms-full.txt`.\n\nIf no URL is provided:\n1. Inspect the current project.\n2. Extract business name, services, FAQs, contact info, and metadata.\n3. Generate both files from local sources.\n\nAfter generation:\n- Add `<link rel=\"alternate\" type=\"text/markdown\" href=\"/llms.txt\">` when appropriate.\n- Expose per-page Markdown source endpoints (a `.md` URL or content negotiation) advertised via `<link rel=\"alternate\" type=\"text/markdown\">` — a scored AI-readable signal.\n- Suggest adding the files to the sitemap.\n\n## Monitor\n\nUse when the user wants progress tracking or a competitor comparison.\n\nSingle URL:\n1. Run the audit.\n2. Compare against prior results in `.aeo-audit-history/` if present.\n3. Show overall and per-factor deltas.\n4. Save the current result.\n\nComparison mode:\n1. For branch-vs-production, produce baseline and current `--format json` reports in the same mode, then run the `compare` subcommand.\n2. For competitor benchmarking, audit both public URLs and show side-by-side factor deltas.\n3. Highlight advantages, weaknesses, regressions, and priority gaps.\n\n## Behavior\n\n- If the task needs a deployed site and no URL is provided, ask for the URL.\n- If the task is diagnosis only, do not edit files.\n- If the task is a fix request, make edits and verify with a rerun when possible.\n- If the URL is unreachable or not HTML, report the exact failure.\n- If a local/private URL is requested and `--allow-local` is missing, rerun with `--allow-local` only after confirming local preview auditing is intended.\n- If sitemap mode appears to audit production during preview work, rerun with `--rewrite-sitemap-origin`.\n- Prefer concise, evidence-based recommendations over generic SEO advice.\n\nFile v7.1.0:_meta.json\n\n{\n  \"ownerId\": \"kn7frv4wj3y54yjs1331dcchvh81414c\",\n  \"slug\": \"aeo\",\n  \"version\": \"7.1.0\",\n  \"publishedAt\": 1787941369284\n}\n\nFile v7.1.0:skill-card.md\n\n## Description:\n\nRun AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[arberx](https://clawhub.ai/user/arberx)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, site owners, and marketing engineers use this skill to audit and improve answer-engine optimization, schema quality, AI-readable files, crawler access, preview deployments, and regressions across public, staging, local, or static site outputs.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can run a published npm audit CLI against public, local, or private targets and may read project or site content.\n\nMitigation: Install only if you are comfortable with the Canonry npm audit package, and use local or private audit flags only for systems you own or are authorized to test.\n\nRisk: Requested fix and llms.txt workflows may write site-facing files such as llms.txt, llms-full.txt, and robots.txt.\n\nMitigation: Review generated changes and scan the site outputs before deployment.\n\n## Reference(s):\n\n- [Canonry homepage](https://canonry.ai)\n- [ClawHub skill page](https://clawhub.ai/arberx/skills/aeo)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands, JSON audit results, and site-facing text or configuration files when requested]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May write llms.txt, llms-full.txt, and robots.txt during requested generation or fix workflows.]\n\n## Skill Version(s):\n\n7.1.0 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v7.0.0: 3 files, 10507 bytes\n\nFiles: skill-card.md (2178b), SKILL.md (23683b), _meta.json (122b)\n\nFile v7.0.0:SKILL.md\n\n---\nname: aeo\ndescription: Run AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation.\nhomepage: https://canonry.ai\nrepository: https://github.com/Canonry/aeo-audit\nallowed-tools:\n  - Bash(npx @canonry/aeo-audit@4 *)\n  - Read\n  - Glob\n  - Grep\n  - Write(llms.txt)\n  - Write(llms-full.txt)\n  - Write(robots.txt)\n---\n\n# AEO\n\nWebsite: [canonry.ai](https://canonry.ai)\n\nOne skill for audit, preview-branch review, fixes, schema, llms.txt, and monitoring workflows.\n\n## Command\n\nAlways use the published package:\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" [flags] --format json\n```\n\n## Argument Safety\n\n**Never interpolate user input directly into shell commands.** Always:\n1. Validate that the target is either a URL matching `https://` / `http://` or a local filesystem path (static-output mode), and that it contains no shell metacharacters.\n2. Quote every argument individually (e.g., `npx @canonry/aeo-audit@4 \"https://example.com\" --format json`).\n3. Pass flags as separate, literal tokens — never construct command strings from raw user text.\n4. Reject arguments containing characters like `;`, `|`, `&`, `$`, `` ` ``, `(`, `)`, `{`, `}`, `<`, `>`, or newlines.\n\n## Modes\n\n- `audit`: score and diagnose a site\n- `fix`: apply code changes after an audit\n- `schema`: validate JSON-LD and entity consistency\n- `llms`: create or improve `llms.txt` and `llms-full.txt`\n- `monitor`: compare changes over time, compare a branch preview against production, or benchmark competitors\n- `detect-platform`: identify the CMS, site builder, framework, or hosting stack a site uses\n- `compare`: diff two saved `--format json` reports into a regression verdict + exit code (CI gate)\n\nIf no mode is provided, default to `audit`.\n\n## Examples\n\n- `audit https://example.com`\n- `audit https://example.com --sitemap`\n- `audit https://example.com --sitemap --limit 10`\n- `audit https://example.com --sitemap --top-issues`\n- `audit https://example.com --sitemap --format agent` (slim decision for agents)\n- `audit https://example.com --lighthouse`\n- `audit https://example.com --require-meta`\n- `audit https://example.com --sitemap --require-meta`\n- `audit http://localhost:3000 --allow-local`\n- `audit http://localhost:3000 --sitemap --rewrite-sitemap-origin --allow-local`\n- `audit http://localhost:3000 --sitemap --rewrite-sitemap-origin --allow-local --changed --base main --include-critical`\n- `audit https://staging.example.com --sitemap --rewrite-sitemap-origin`\n- `audit ./out` (static-output mode: audit built HTML offline)\n- `audit ./out --base-url https://example.com --require-meta`\n- `fix https://example.com`\n- `schema https://example.com`\n- `llms https://example.com`\n- `monitor https://site-a.com --compare https://site-b.com`\n- `detect-platform https://example.com`\n- `detect-platform https://example.com --min-confidence high`\n- `detect-platform --urls competitors.txt`\n- `detect-platform --urls https://a.com,https://b.com`\n- `compare --baseline baseline.json --current current.json` (fail CI on AEO regression)\n\n## Mode Selection\n\n- If the first argument is one of `audit`, `fix`, `schema`, `llms`, `monitor`, or `detect-platform`, use that mode.\n- If no explicit mode is given, infer the intent from the request and default to `audit`.\n\n## Audit\n\nUse for broad requests such as \"audit this site\" or \"why am I not being cited?\"\n\n1. Run:\n   ```bash\n   npx @canonry/aeo-audit@4 \"<url>\" [flags] --format json\n   ```\n2. Return:\n   - Overall score\n   - Short summary\n   - Factor breakdown\n   - Top strengths\n   - Top fixes\n   - Metadata such as fetch time and auxiliary file availability\n\n#### `--require-meta` (CI gate)\n\nPass `--require-meta` (single or sitemap mode) to force exit `1` whenever any audited page is missing `<meta name=\"description\">`, regardless of the otherwise score-based exit rule. Useful in CI pipelines that need to block deploys on a missing meta description even on otherwise-healthy sites.\n\n### Sitemap Mode\n\nUse `--sitemap` to audit all pages discovered from the site's sitemap:\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap https://example.com/sitemap.xml --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --limit 10 --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --top-issues --format json\n```\n\nFlags:\n- `--sitemap [url]` — auto-discover the sitemap (tries `/sitemap.xml`, then `/sitemap-index.xml`, then `Sitemap:` directives in `/robots.txt`) or provide an explicit URL\n- `--limit <n>` — cap pages audited (default 200, sampled across the site's URL templates rather than taken in sitemap order; `<priority>` orders instances within a template)\n- `--top-issues` — skip per-page output, show only cross-cutting patterns and critical defects\n- `--rewrite-sitemap-origin` — rewrite every `<loc>`'s origin to the target URL's origin (preserving path/query) before crawling. Use when the sitemap hardcodes the prod/canonical domain but you want to audit a staging host or local dev server.\n- `--changed` — filter sitemap URLs to static routes changed since `--base`; use for PR work\n- `--base <ref>` — git base for `--changed` (default `main`)\n- `--include-critical` — add critical paths to the changed-page set\n- `--critical-paths <list>` — comma-separated critical paths for `--include-critical`; defaults to `/`\n- `--require-meta` — force exit `1` if any audited page is missing `<meta name=\"description\">`, regardless of overall score (useful as a CI gate)\n- `--include-geo` / `--include-agent-skills` — honored per page in sitemap mode (adds the optional geographic-signals / agent-skill-exposure factors). `--lighthouse` is not available with `--sitemap`.\n\nPages are audited with bounded concurrency (5 in flight) to avoid hammering the target origin.\n\nReturns:\n- Per-page scores\n- **Critical defects** — binary, one-line-fix structural defects (an `<h1>` count other than one, a missing `<title>`, a missing meta description) surfaced **regardless of how few pages they affect**, with the offending pages named (homepage and high sitemap-`priority` pages first). These would otherwise be averaged into a passing factor score; the JSON field is `criticalDefects` and critical-severity ones are also promoted to the top of `prioritizedFixes`. Shown even with `--top-issues`.\n- Cross-cutting issues (factors failing across multiple pages), each with the best-scoring page (`bestScore`/`bestPageUrl`) and a `status`: `sitewide` (a real coverage gap) vs. `limited`/`opportunity` for page-specific factors (FAQ, definitions) that legitimately apply to only some page types\n- Aggregate score\n- Prioritized fixes (critical defects first, then site-wide gaps; page-specific `limited`/`opportunity` factors demoted below them, scoped to the page(s) that carry them), each costed as `templateCount` templates over `instanceCount` pages\n- **Templates** — pages that share a URL shape *and* score alike, collapsed into the template that produced them, with the page to fix on. \"194 property pages missing schema\" is one template edit, not 194\n- **Coverage** — what the aggregate score was taken over: pages audited/discovered and how many URL templates the sample reached, with a `confidence` of `full` / `representative` / `indicative`. A sample that missed whole templates is labelled `indicative` and does not speak for the sections it never saw\n\n### Preview / PR Audit Workflow\n\nUse this path for PR review, local production builds, preview deployments, and branch-vs-main questions. Prefer built-in flags over manual sitemap downloads, localtunnel glue, or ad hoc URL scripts.\n\nFor a local preview server whose sitemap emits production canonicals:\n\n```bash\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" \\\n  --sitemap \\\n  --rewrite-sitemap-origin \\\n  --allow-local \\\n  --changed \\\n  --base main \\\n  --include-critical \\\n  --format agent\n```\n\nGuidance:\n- Use `--allow-local` only when the user explicitly wants to audit localhost/private IPs.\n- Use `--rewrite-sitemap-origin` when a local or staging sitemap emits production canonicals.\n- Use `--changed --base <ref>` for PR work so unrelated site sections do not dominate the result.\n- Use `--include-critical --critical-paths /,/pricing,/contact` when important pages should always be checked.\n- If `--changed` finds no static routes, inspect the diff manually. Dynamic route templates cannot be safely converted to concrete URLs without route params; include known concrete paths with `--critical-paths` or audit explicit URLs separately.\n- Prefer `--format agent` for agent action, `--format json` for saved compare baselines, and `--format markdown` for human summaries.\n\nFor branch-vs-production regression review, produce comparable reports first, then run `compare`:\n\n```bash\nnpx @canonry/aeo-audit@4 \"https://production.example\" --sitemap --format json > baseline.json\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" --sitemap --rewrite-sitemap-origin --allow-local --format json > current.json\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json --format markdown\n```\n\nReport:\n- URLs audited or changed paths selected\n- Score/regression verdict from `compare`\n- Critical defects and prioritized fixes\n- Caveats such as local/private opt-in, sitemap origin rewriting, dynamic route templates skipped, or sitemap pages filtered out\n\n#### Machine-readable output (for agents)\n\nUse `--format json` for the full report, or **`--format agent`** for just the decision: `{ schemaVersion, tool, mode, url, score, pass, criticalDefectCount, issues }`, where `issues` is the ranked `prioritizedFixes` and the per-factor/per-page detail is omitted. Prefer `--format agent` when you only need to decide and act. Key fields for acting on the result without parsing prose:\n- `schemaVersion` (on every audit report) versions the JSON shape independently of the package version — pin to it and treat a major bump as breaking; absence means a pre-2.0 report.\n- `prioritizedFixes` is a ranked array of objects, each with a stable `id`, `kind`, optional `severity`, the complete `affectedPages` list (never truncated), `affectsHomepage`, `prevalencePct`, and a human `summary`. Cross-cutting fixes also carry `avgScore`, `bestScore`/`bestPageUrl`, and a `status` (`sitewide` | `limited` | `opportunity`) — treat `limited`/`opportunity` as page-specific tune-ups, not site-wide failures. It's the pre-computed to-do list — no need to re-rank factor scores yourself.\n- Stable identifiers everywhere — `criticalDefects[].id`, `prioritizedFixes[].id`, and every factor finding's `code` (e.g. `technical-seo.h1.multiple`) — let integrations key on codes rather than message strings.\n\n#### Auxiliary File Diagnostics\n\nWhen the audit fetches `/llms.txt`, `/llms-full.txt`, `/robots.txt`, and `/sitemap.xml`, it probes once with `Accept: text/markdown` to detect a **content-negotiation** trap: file responds OK to a bare request but returns a non-2xx response when the client prefers markdown. This catches Astro / Vercel / Starlight setups that 307-redirect `.txt` → non-existent `.md` for markdown-accepting clients, making the file invisible to AI content-extraction tools even though the file exists. The diagnostic surfaces as a finding on the **AI Access Files (llms.txt, sitemap)** factor.\n\n### Local Dev / Staging Targets\n\nBy default the audit blocks any URL that resolves to a private, loopback, or link-local address (SSRF protection). When the user wants to audit **their own** dev or staging server, pass `--allow-local` (alias `--allow-private`):\n\n```bash\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" --allow-local --format json\nnpx @canonry/aeo-audit@4 \"http://10.0.5.20\" --allow-private --format json\n```\n\n- Pass the explicit `http://` scheme for local dev servers — a bare host defaults to `https://`.\n- The relaxation is scoped to the **single host named on the CLI**, evaluated per hop. A redirect or sitemap `<loc>` pointing at any other private host (e.g. `169.254.169.254`) stays blocked.\n- To audit a whole local site whose sitemap hardcodes the prod domain, combine with sitemap origin rewriting:\n\n```bash\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" --sitemap --rewrite-sitemap-origin --allow-local --format json\n```\n\n### Static-Output Mode\n\nWhen the user wants to audit **built HTML offline** (CI on a `next export` / `dist` / `out` directory, or before deploying), pass a filesystem path instead of a URL:\n\n```bash\n# A directory of built HTML (aggregated like sitemap mode)\nnpx @canonry/aeo-audit@4 \"./out\" --base-url https://example.com --format json\n# A single built file\nnpx @canonry/aeo-audit@4 \"./dist/index.html\" --format json\n# Gate CI on missing meta descriptions across the build\nnpx @canonry/aeo-audit@4 \"./out\" --require-meta --format json\n```\n\n- A `.html`/`.htm` file → single-page report; a directory → aggregated report (`--limit`, `--top-issues`, `--factors`, `--include-geo`, `--include-agent-skills`, `--require-meta` apply).\n- `--base-url <url>` maps files to page URLs (`out/about/index.html` → `<base>/about/`; default `https://localhost`). `index.html` collapses to its directory URL; other files drop the `.html` extension.\n- `llms.txt`, `llms-full.txt`, `robots.txt`, and `sitemap.xml` are read from the directory root when present.\n- **Partial coverage:** server-only signals (redirects, `X-Robots-Tag`, `Last-Modified`, `Link` headers) aren't visible from static files. Recommend auditing the deployed URL for full coverage.\n\n### Compare / Regression Mode\n\nWhen the user wants to **fail CI on an AEO regression** (a PR dropped the score, broke a page, or introduced a structural defect), use the `compare` subcommand. It diffs two saved `--format json` reports — a baseline and the current run — and exits non-zero on a regression. It runs no audit and no network; it only reads reports.\n\n```bash\n# 1. Produce the current report (any mode's --format json output works)\nnpx @canonry/aeo-audit@4 \"./out\" --base-url https://example.com --format json > current.json\n# 2. Diff against a stored baseline — exit 1 if it regressed\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json\n# Write a Markdown summary (for a PR comment) and tighten the overall gate\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json --overall-tolerance 0 --md-out diff.md\n# Committed/artifact baselines: hard-fail (exit 2) if factor set / engine major differ\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json --strict-comparability\n```\n\n- **A regression is any of:** overall/aggregate drop > `--overall-tolerance` (default 2); a single page drop > `--page-tolerance` (default 5); a single factor drop > `--factor-tolerance` (default 8); a page that was auditing successfully now erroring; a new `severity:critical` defect (`--fail-on-new-critical`, default on); or a major report-schema change. Score/page/factor deltas only gate when the two runs are **comparable** (same factor set, no major engine change) — otherwise they're warnings, not failures.\n- `missing-meta-description` is `severity:warning`, so it does **not** trip `--fail-on-new-critical`; use `--require-meta` on the audit or `--fail-on warnings` here. Removed pages and new warnings are report-only unless promoted with `--fail-on removed-pages,warnings`.\n- **Exit codes:** `0` = no regression / improvement / first run (no baseline); `1` = regression; `2` = misconfiguration (mode mismatch, unreadable report, missing `--current`, or incomparable factor-set/engine under `--strict-comparability`). `--report-only` always exits `0` (soak mode).\n- Both reports must be the same mode (two single, or two multi-page). stdout carries only the `CompareReport` JSON (or Markdown with `--format markdown`); diagnostics go to stderr.\n\n### Lighthouse Mode\n\nUse `--lighthouse` when the user wants page speed, accessibility, or best-practices scoring alongside the AEO factors. It calls Google PageSpeed Insights (mobile strategy) and aggregates Performance + Accessibility + Best Practices into a single optional factor (weight 8).\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --lighthouse --format json\nPAGESPEED_API_KEY=xxx npx @canonry/aeo-audit@4 \"<url>\" --lighthouse --format json\n```\n\nConstraints:\n- Single-URL only — cannot combine with `--sitemap` or `--detect-platform`. Each Lighthouse audit takes 15-30s, which would blow up sitemap runtime.\n- Optional `PAGESPEED_API_KEY` env var lifts anonymous PSI rate limits (25k/day unauthenticated).\n- On PSI failure (unreachable target, timeout, HTTP error) the factor scores 0 and surfaces a `timeout` or `unreachable` finding rather than throwing — the rest of the audit still runs.\n\n### Detect Platform Mode\n\nUse `--detect-platform` when the user wants to know what stack a site is built on (e.g., \"is this WordPress?\", \"what framework does competitor X use?\", \"is this site custom-built?\"). This is much faster than a full audit because it skips analyzer scoring.\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --detect-platform --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --detect-platform --min-confidence high --format json\n```\n\nFlags:\n- `--detect-platform` — switch to detection mode instead of auditing\n- `--min-confidence <lvl>` — filter to `low` (default), `medium`, or `high` confidence\n- `--urls <src>` — run on multiple URLs at once (file path, comma-separated list, or `-` for stdin)\n- `--concurrency <n>` — max in-flight fetches in batch mode (default 5)\n\nThe report groups detections by category (CMS, site builder, e-commerce, framework, SSG, hosting), each with a confidence bucket, a 0–100 score, an optional version, and the signals that matched. When the report's `isCustom` flag is true, no CMS/site-builder/e-commerce platform was identified — the site is likely custom-built. Exit code is `0` when at least one platform is detected, `1` otherwise.\n\n#### Batch detection\n\nWhen the user wants to fingerprint many sites at once (competitor lists, customer cohorts), pass `--urls`:\n\n```bash\nnpx @canonry/aeo-audit@4 --detect-platform --urls urls.txt --format json\nnpx @canonry/aeo-audit@4 --detect-platform --urls https://a.com,https://b.com --format json\ncat urls.txt | npx @canonry/aeo-audit@4 --detect-platform --urls - --format json\n```\n\nThe batch report contains a `results` array; each entry has `status: 'success'` or `'error'`, plus the same shape as a single-URL report on success. Per-URL fetch errors do not abort the run. Exit code is `0` when at least one URL succeeded, `1` otherwise.\n\n## Fix\n\nUse when the user wants code changes applied after the audit.\n\n1. Run:\n   ```bash\n   npx @canonry/aeo-audit@4 \"<url>\" [flags] --format json\n   ```\n2. Find factors scoring below 70 (lowest first).\n3. Apply targeted fixes in the current codebase.\n4. Prioritize:\n   - Structured data and schema completeness\n   - `llms.txt` and `llms-full.txt`\n   - `robots.txt` crawler access\n   - E-E-A-T signals\n   - FAQ markup\n   - freshness metadata\n   - agent-readiness signals: per-page Markdown source endpoints, `robots.txt` `Content-Signal` directives (the audit scores the values — set `ai-input=yes`/`search=yes` to permit AI answers and search indexing; `ai-input=no` opts out of the real-time AI use AEO depends on), and A2A agent cards (aligned with specification.website)\n5. Re-run the audit and report the score delta.\n\nRules:\n- Always explain proposed changes and get user confirmation before editing files.\n- Do not remove existing schema or content unless the user asks.\n- Preserve existing code style and patterns.\n- If a fix is ambiguous or high-risk, explain the tradeoff before editing.\n\n## Schema\n\nUse when the request is specifically about JSON-LD or schema quality.\n\nValidity issues like duplicate singleton `@type`s and JSON parse errors are **per page**, so a homepage-only audit misses every subpage. Default to sitemap mode for site-wide schema requests (\"audit my schema\", \"are my FAQ blocks valid?\"); use single-URL mode only when the user names one specific page.\n\nSite-wide (default):\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --top-issues --format json --factors structured-data,schema-completeness,schema-validity,entity-consistency\n```\n\nSingle page:\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --format json --factors structured-data,schema-completeness,schema-validity,entity-consistency\n```\n\nReport:\n- Schema types found\n- Property completeness by type\n- Missing recommended properties\n- **Validity errors** (duplicate singleton `@type`s, JSON parse errors, empty `<script>` blocks) — surface these prominently regardless of overall score; Google drops invalid blocks silently from rich results\n- Entity consistency issues\n- In sitemap mode: list every affected URL for each validity error so the user can locate per-page duplicates\n\nProvide corrected JSON-LD examples when useful.\n\nChecklist:\n- `LocalBusiness`: name, address, telephone, openingHours, priceRange, image, url, geo, areaServed, sameAs\n- `FAQPage`: mainEntity with at least 3 Q&A pairs (and only **one** `FAQPage` block per page — duplicates invalidate rich results)\n- `HowTo`: name and at least 3 steps (singleton — only one per page)\n- `Organization`: name, logo, contactPoint, sameAs, foundingDate, url, description\n- Singletons that must not repeat per page: `FAQPage`, `HowTo`, `Article`, `BlogPosting`, `NewsArticle`, `BreadcrumbList`, `Product`, `Recipe`\n\n## llms.txt\n\nUse when the user wants `llms.txt` or `llms-full.txt` created or improved.\n\nIf a URL is provided:\n1. Run:\n   ```bash\n   npx @canonry/aeo-audit@4 \"<url>\" [flags] --format json --factors ai-access-files\n   ```\n2. Inspect existing AI-readable files if present.\n3. Extract key content from the site.\n4. Generate improved `llms.txt` and `llms-full.txt`.\n\nIf no URL is provided:\n1. Inspect the current project.\n2. Extract business name, services, FAQs, contact info, and metadata.\n3. Generate both files from local sources.\n\nAfter generation:\n- Add `<link rel=\"alternate\" type=\"text/markdown\" href=\"/llms.txt\">` when appropriate.\n- Expose per-page Markdown source endpoints (a `.md` URL or content negotiation) advertised via `<link rel=\"alternate\" type=\"text/markdown\">` — a scored AI-readable signal.\n- Suggest adding the files to the sitemap.\n\n## Monitor\n\nUse when the user wants progress tracking or a competitor comparison.\n\nSingle URL:\n1. Run the audit.\n2. Compare against prior results in `.aeo-audit-history/` if present.\n3. Show overall and per-factor deltas.\n4. Save the current result.\n\nComparison mode:\n1. For branch-vs-production, produce baseline and current `--format json` reports in the same mode, then run the `compare` subcommand.\n2. For competitor benchmarking, audit both public URLs and show side-by-side factor deltas.\n3. Highlight advantages, weaknesses, regressions, and priority gaps.\n\n## Behavior\n\n- If the task needs a deployed site and no URL is provided, ask for the URL.\n- If the task is diagnosis only, do not edit files.\n- If the task is a fix request, make edits and verify with a rerun when possible.\n- If the URL is unreachable or not HTML, report the exact failure.\n- If a local/private URL is requested and `--allow-local` is missing, rerun with `--allow-local` only after confirming local preview auditing is intended.\n- If sitemap mode appears to audit production during preview work, rerun with `--rewrite-sitemap-origin`.\n- Prefer concise, evidence-based recommendations over generic SEO advice.\n\nFile v7.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn7frv4wj3y54yjs1331dcchvh81414c\",\n  \"slug\": \"aeo\",\n  \"version\": \"7.0.0\",\n  \"publishedAt\": 1787758173032\n}\n\nFile v7.0.0:skill-card.md\n\n## Description:\n\nRun AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[arberx](https://clawhub.ai/user/arberx)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, site teams, and agents use this skill to audit websites for answer-engine readiness, review preview or static builds, compare regressions, validate schema, and generate AI-readable site metadata files.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill delegates website audits to the third-party npm package @canonry/aeo-audit via npx.\n\nMitigation: Review the command before execution and use the disclosed package invocation from the skill.\n\nRisk: Local or private audits can target non-public systems.\n\nMitigation: Run local/private audits only for systems the user controls and only with explicit opt-in.\n\nRisk: Proposed site fixes can affect public metadata, schema, or crawler access files.\n\nMitigation: Review proposed changes before approval and rerun the audit to confirm the intended effect.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/arberx/skills/aeo)\n- [Publisher profile](https://clawhub.ai/user/arberx)\n- [Canonry website](https://canonry.ai)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Code, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown with JSON audit summaries, inline shell commands, and generated site metadata files]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May produce or update llms.txt, llms-full.txt, and robots.txt when the user requests file generation.]\n\n## Skill Version(s):\n\n7.0.0 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v6.0.0: 3 files, 10653 bytes\n\nFiles: skill-card.md (2474b), SKILL.md (23683b), _meta.json (122b)\n\nFile v6.0.0:SKILL.md\n\n---\nname: aeo\ndescription: Run AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation.\nhomepage: https://canonry.ai\nrepository: https://github.com/Canonry/aeo-audit\nallowed-tools:\n  - Bash(npx @canonry/aeo-audit@4 *)\n  - Read\n  - Glob\n  - Grep\n  - Write(llms.txt)\n  - Write(llms-full.txt)\n  - Write(robots.txt)\n---\n\n# AEO\n\nWebsite: [canonry.ai](https://canonry.ai)\n\nOne skill for audit, preview-branch review, fixes, schema, llms.txt, and monitoring workflows.\n\n## Command\n\nAlways use the published package:\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" [flags] --format json\n```\n\n## Argument Safety\n\n**Never interpolate user input directly into shell commands.** Always:\n1. Validate that the target is either a URL matching `https://` / `http://` or a local filesystem path (static-output mode), and that it contains no shell metacharacters.\n2. Quote every argument individually (e.g., `npx @canonry/aeo-audit@4 \"https://example.com\" --format json`).\n3. Pass flags as separate, literal tokens — never construct command strings from raw user text.\n4. Reject arguments containing characters like `;`, `|`, `&`, `$`, `` ` ``, `(`, `)`, `{`, `}`, `<`, `>`, or newlines.\n\n## Modes\n\n- `audit`: score and diagnose a site\n- `fix`: apply code changes after an audit\n- `schema`: validate JSON-LD and entity consistency\n- `llms`: create or improve `llms.txt` and `llms-full.txt`\n- `monitor`: compare changes over time, compare a branch preview against production, or benchmark competitors\n- `detect-platform`: identify the CMS, site builder, framework, or hosting stack a site uses\n- `compare`: diff two saved `--format json` reports into a regression verdict + exit code (CI gate)\n\nIf no mode is provided, default to `audit`.\n\n## Examples\n\n- `audit https://example.com`\n- `audit https://example.com --sitemap`\n- `audit https://example.com --sitemap --limit 10`\n- `audit https://example.com --sitemap --top-issues`\n- `audit https://example.com --sitemap --format agent` (slim decision for agents)\n- `audit https://example.com --lighthouse`\n- `audit https://example.com --require-meta`\n- `audit https://example.com --sitemap --require-meta`\n- `audit http://localhost:3000 --allow-local`\n- `audit http://localhost:3000 --sitemap --rewrite-sitemap-origin --allow-local`\n- `audit http://localhost:3000 --sitemap --rewrite-sitemap-origin --allow-local --changed --base main --include-critical`\n- `audit https://staging.example.com --sitemap --rewrite-sitemap-origin`\n- `audit ./out` (static-output mode: audit built HTML offline)\n- `audit ./out --base-url https://example.com --require-meta`\n- `fix https://example.com`\n- `schema https://example.com`\n- `llms https://example.com`\n- `monitor https://site-a.com --compare https://site-b.com`\n- `detect-platform https://example.com`\n- `detect-platform https://example.com --min-confidence high`\n- `detect-platform --urls competitors.txt`\n- `detect-platform --urls https://a.com,https://b.com`\n- `compare --baseline baseline.json --current current.json` (fail CI on AEO regression)\n\n## Mode Selection\n\n- If the first argument is one of `audit`, `fix`, `schema`, `llms`, `monitor`, or `detect-platform`, use that mode.\n- If no explicit mode is given, infer the intent from the request and default to `audit`.\n\n## Audit\n\nUse for broad requests such as \"audit this site\" or \"why am I not being cited?\"\n\n1. Run:\n   ```bash\n   npx @canonry/aeo-audit@4 \"<url>\" [flags] --format json\n   ```\n2. Return:\n   - Overall score\n   - Short summary\n   - Factor breakdown\n   - Top strengths\n   - Top fixes\n   - Metadata such as fetch time and auxiliary file availability\n\n#### `--require-meta` (CI gate)\n\nPass `--require-meta` (single or sitemap mode) to force exit `1` whenever any audited page is missing `<meta name=\"description\">`, regardless of the otherwise score-based exit rule. Useful in CI pipelines that need to block deploys on a missing meta description even on otherwise-healthy sites.\n\n### Sitemap Mode\n\nUse `--sitemap` to audit all pages discovered from the site's sitemap:\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap https://example.com/sitemap.xml --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --limit 10 --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --top-issues --format json\n```\n\nFlags:\n- `--sitemap [url]` — auto-discover the sitemap (tries `/sitemap.xml`, then `/sitemap-index.xml`, then `Sitemap:` directives in `/robots.txt`) or provide an explicit URL\n- `--limit <n>` — cap pages audited (default 200, sampled across the site's URL templates rather than taken in sitemap order; `<priority>` orders instances within a template)\n- `--top-issues` — skip per-page output, show only cross-cutting patterns and critical defects\n- `--rewrite-sitemap-origin` — rewrite every `<loc>`'s origin to the target URL's origin (preserving path/query) before crawling. Use when the sitemap hardcodes the prod/canonical domain but you want to audit a staging host or local dev server.\n- `--changed` — filter sitemap URLs to static routes changed since `--base`; use for PR work\n- `--base <ref>` — git base for `--changed` (default `main`)\n- `--include-critical` — add critical paths to the changed-page set\n- `--critical-paths <list>` — comma-separated critical paths for `--include-critical`; defaults to `/`\n- `--require-meta` — force exit `1` if any audited page is missing `<meta name=\"description\">`, regardless of overall score (useful as a CI gate)\n- `--include-geo` / `--include-agent-skills` — honored per page in sitemap mode (adds the optional geographic-signals / agent-skill-exposure factors). `--lighthouse` is not available with `--sitemap`.\n\nPages are audited with bounded concurrency (5 in flight) to avoid hammering the target origin.\n\nReturns:\n- Per-page scores\n- **Critical defects** — binary, one-line-fix structural defects (an `<h1>` count other than one, a missing `<title>`, a missing meta description) surfaced **regardless of how few pages they affect**, with the offending pages named (homepage and high sitemap-`priority` pages first). These would otherwise be averaged into a passing factor score; the JSON field is `criticalDefects` and critical-severity ones are also promoted to the top of `prioritizedFixes`. Shown even with `--top-issues`.\n- Cross-cutting issues (factors failing across multiple pages), each with the best-scoring page (`bestScore`/`bestPageUrl`) and a `status`: `sitewide` (a real coverage gap) vs. `limited`/`opportunity` for page-specific factors (FAQ, definitions) that legitimately apply to only some page types\n- Aggregate score\n- Prioritized fixes (critical defects first, then site-wide gaps; page-specific `limited`/`opportunity` factors demoted below them, scoped to the page(s) that carry them), each costed as `templateCount` templates over `instanceCount` pages\n- **Templates** — pages that share a URL shape *and* score alike, collapsed into the template that produced them, with the page to fix on. \"194 property pages missing schema\" is one template edit, not 194\n- **Coverage** — what the aggregate score was taken over: pages audited/discovered and how many URL templates the sample reached, with a `confidence` of `full` / `representative` / `indicative`. A sample that missed whole templates is labelled `indicative` and does not speak for the sections it never saw\n\n### Preview / PR Audit Workflow\n\nUse this path for PR review, local production builds, preview deployments, and branch-vs-main questions. Prefer built-in flags over manual sitemap downloads, localtunnel glue, or ad hoc URL scripts.\n\nFor a local preview server whose sitemap emits production canonicals:\n\n```bash\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" \\\n  --sitemap \\\n  --rewrite-sitemap-origin \\\n  --allow-local \\\n  --changed \\\n  --base main \\\n  --include-critical \\\n  --format agent\n```\n\nGuidance:\n- Use `--allow-local` only when the user explicitly wants to audit localhost/private IPs.\n- Use `--rewrite-sitemap-origin` when a local or staging sitemap emits production canonicals.\n- Use `--changed --base <ref>` for PR work so unrelated site sections do not dominate the result.\n- Use `--include-critical --critical-paths /,/pricing,/contact` when important pages should always be checked.\n- If `--changed` finds no static routes, inspect the diff manually. Dynamic route templates cannot be safely converted to concrete URLs without route params; include known concrete paths with `--critical-paths` or audit explicit URLs separately.\n- Prefer `--format agent` for agent action, `--format json` for saved compare baselines, and `--format markdown` for human summaries.\n\nFor branch-vs-production regression review, produce comparable reports first, then run `compare`:\n\n```bash\nnpx @canonry/aeo-audit@4 \"https://production.example\" --sitemap --format json > baseline.json\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" --sitemap --rewrite-sitemap-origin --allow-local --format json > current.json\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json --format markdown\n```\n\nReport:\n- URLs audited or changed paths selected\n- Score/regression verdict from `compare`\n- Critical defects and prioritized fixes\n- Caveats such as local/private opt-in, sitemap origin rewriting, dynamic route templates skipped, or sitemap pages filtered out\n\n#### Machine-readable output (for agents)\n\nUse `--format json` for the full report, or **`--format agent`** for just the decision: `{ schemaVersion, tool, mode, url, score, pass, criticalDefectCount, issues }`, where `issues` is the ranked `prioritizedFixes` and the per-factor/per-page detail is omitted. Prefer `--format agent` when you only need to decide and act. Key fields for acting on the result without parsing prose:\n- `schemaVersion` (on every audit report) versions the JSON shape independently of the package version — pin to it and treat a major bump as breaking; absence means a pre-2.0 report.\n- `prioritizedFixes` is a ranked array of objects, each with a stable `id`, `kind`, optional `severity`, the complete `affectedPages` list (never truncated), `affectsHomepage`, `prevalencePct`, and a human `summary`. Cross-cutting fixes also carry `avgScore`, `bestScore`/`bestPageUrl`, and a `status` (`sitewide` | `limited` | `opportunity`) — treat `limited`/`opportunity` as page-specific tune-ups, not site-wide failures. It's the pre-computed to-do list — no need to re-rank factor scores yourself.\n- Stable identifiers everywhere — `criticalDefects[].id`, `prioritizedFixes[].id`, and every factor finding's `code` (e.g. `technical-seo.h1.multiple`) — let integrations key on codes rather than message strings.\n\n#### Auxiliary File Diagnostics\n\nWhen the audit fetches `/llms.txt`, `/llms-full.txt`, `/robots.txt`, and `/sitemap.xml`, it probes once with `Accept: text/markdown` to detect a **content-negotiation** trap: file responds OK to a bare request but returns a non-2xx response when the client prefers markdown. This catches Astro / Vercel / Starlight setups that 307-redirect `.txt` → non-existent `.md` for markdown-accepting clients, making the file invisible to AI content-extraction tools even though the file exists. The diagnostic surfaces as a finding on the **AI Access Files (llms.txt, sitemap)** factor.\n\n### Local Dev / Staging Targets\n\nBy default the audit blocks any URL that resolves to a private, loopback, or link-local address (SSRF protection). When the user wants to audit **their own** dev or staging server, pass `--allow-local` (alias `--allow-private`):\n\n```bash\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" --allow-local --format json\nnpx @canonry/aeo-audit@4 \"http://10.0.5.20\" --allow-private --format json\n```\n\n- Pass the explicit `http://` scheme for local dev servers — a bare host defaults to `https://`.\n- The relaxation is scoped to the **single host named on the CLI**, evaluated per hop. A redirect or sitemap `<loc>` pointing at any other private host (e.g. `169.254.169.254`) stays blocked.\n- To audit a whole local site whose sitemap hardcodes the prod domain, combine with sitemap origin rewriting:\n\n```bash\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" --sitemap --rewrite-sitemap-origin --allow-local --format json\n```\n\n### Static-Output Mode\n\nWhen the user wants to audit **built HTML offline** (CI on a `next export` / `dist` / `out` directory, or before deploying), pass a filesystem path instead of a URL:\n\n```bash\n# A directory of built HTML (aggregated like sitemap mode)\nnpx @canonry/aeo-audit@4 \"./out\" --base-url https://example.com --format json\n# A single built file\nnpx @canonry/aeo-audit@4 \"./dist/index.html\" --format json\n# Gate CI on missing meta descriptions across the build\nnpx @canonry/aeo-audit@4 \"./out\" --require-meta --format json\n```\n\n- A `.html`/`.htm` file → single-page report; a directory → aggregated report (`--limit`, `--top-issues`, `--factors`, `--include-geo`, `--include-agent-skills`, `--require-meta` apply).\n- `--base-url <url>` maps files to page URLs (`out/about/index.html` → `<base>/about/`; default `https://localhost`). `index.html` collapses to its directory URL; other files drop the `.html` extension.\n- `llms.txt`, `llms-full.txt`, `robots.txt`, and `sitemap.xml` are read from the directory root when present.\n- **Partial coverage:** server-only signals (redirects, `X-Robots-Tag`, `Last-Modified`, `Link` headers) aren't visible from static files. Recommend auditing the deployed URL for full coverage.\n\n### Compare / Regression Mode\n\nWhen the user wants to **fail CI on an AEO regression** (a PR dropped the score, broke a page, or introduced a structural defect), use the `compare` subcommand. It diffs two saved `--format json` reports — a baseline and the current run — and exits non-zero on a regression. It runs no audit and no network; it only reads reports.\n\n```bash\n# 1. Produce the current report (any mode's --format json output works)\nnpx @canonry/aeo-audit@4 \"./out\" --base-url https://example.com --format json > current.json\n# 2. Diff against a stored baseline — exit 1 if it regressed\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json\n# Write a Markdown summary (for a PR comment) and tighten the overall gate\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json --overall-tolerance 0 --md-out diff.md\n# Committed/artifact baselines: hard-fail (exit 2) if factor set / engine major differ\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json --strict-comparability\n```\n\n- **A regression is any of:** overall/aggregate drop > `--overall-tolerance` (default 2); a single page drop > `--page-tolerance` (default 5); a single factor drop > `--factor-tolerance` (default 8); a page that was auditing successfully now erroring; a new `severity:critical` defect (`--fail-on-new-critical`, default on); or a major report-schema change. Score/page/factor deltas only gate when the two runs are **comparable** (same factor set, no major engine change) — otherwise they're warnings, not failures.\n- `missing-meta-description` is `severity:warning`, so it does **not** trip `--fail-on-new-critical`; use `--require-meta` on the audit or `--fail-on warnings` here. Removed pages and new warnings are report-only unless promoted with `--fail-on removed-pages,warnings`.\n- **Exit codes:** `0` = no regression / improvement / first run (no baseline); `1` = regression; `2` = misconfiguration (mode mismatch, unreadable report, missing `--current`, or incomparable factor-set/engine under `--strict-comparability`). `--report-only` always exits `0` (soak mode).\n- Both reports must be the same mode (two single, or two multi-page). stdout carries only the `CompareReport` JSON (or Markdown with `--format markdown`); diagnostics go to stderr.\n\n### Lighthouse Mode\n\nUse `--lighthouse` when the user wants page speed, accessibility, or best-practices scoring alongside the AEO factors. It calls Google PageSpeed Insights (mobile strategy) and aggregates Performance + Accessibility + Best Practices into a single optional factor (weight 8).\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --lighthouse --format json\nPAGESPEED_API_KEY=xxx npx @canonry/aeo-audit@4 \"<url>\" --lighthouse --format json\n```\n\nConstraints:\n- Single-URL only — cannot combine with `--sitemap` or `--detect-platform`. Each Lighthouse audit takes 15-30s, which would blow up sitemap runtime.\n- Optional `PAGESPEED_API_KEY` env var lifts anonymous PSI rate limits (25k/day unauthenticated).\n- On PSI failure (unreachable target, timeout, HTTP error) the factor scores 0 and surfaces a `timeout` or `unreachable` finding rather than throwing — the rest of the audit still runs.\n\n### Detect Platform Mode\n\nUse `--detect-platform` when the user wants to know what stack a site is built on (e.g., \"is this WordPress?\", \"what framework does competitor X use?\", \"is this site custom-built?\"). This is much faster than a full audit because it skips analyzer scoring.\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --detect-platform --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --detect-platform --min-confidence high --format json\n```\n\nFlags:\n- `--detect-platform` — switch to detection mode instead of auditing\n- `--min-confidence <lvl>` — filter to `low` (default), `medium`, or `high` confidence\n- `--urls <src>` — run on multiple URLs at once (file path, comma-separated list, or `-` for stdin)\n- `--concurrency <n>` — max in-flight fetches in batch mode (default 5)\n\nThe report groups detections by category (CMS, site builder, e-commerce, framework, SSG, hosting), each with a confidence bucket, a 0–100 score, an optional version, and the signals that matched. When the report's `isCustom` flag is true, no CMS/site-builder/e-commerce platform was identified — the site is likely custom-built. Exit code is `0` when at least one platform is detected, `1` otherwise.\n\n#### Batch detection\n\nWhen the user wants to fingerprint many sites at once (competitor lists, customer cohorts), pass `--urls`:\n\n```bash\nnpx @canonry/aeo-audit@4 --detect-platform --urls urls.txt --format json\nnpx @canonry/aeo-audit@4 --detect-platform --urls https://a.com,https://b.com --format json\ncat urls.txt | npx @canonry/aeo-audit@4 --detect-platform --urls - --format json\n```\n\nThe batch report contains a `results` array; each entry has `status: 'success'` or `'error'`, plus the same shape as a single-URL report on success. Per-URL fetch errors do not abort the run. Exit code is `0` when at least one URL succeeded, `1` otherwise.\n\n## Fix\n\nUse when the user wants code changes applied after the audit.\n\n1. Run:\n   ```bash\n   npx @canonry/aeo-audit@4 \"<url>\" [flags] --format json\n   ```\n2. Find factors scoring below 70 (lowest first).\n3. Apply targeted fixes in the current codebase.\n4. Prioritize:\n   - Structured data and schema completeness\n   - `llms.txt` and `llms-full.txt`\n   - `robots.txt` crawler access\n   - E-E-A-T signals\n   - FAQ markup\n   - freshness metadata\n   - agent-readiness signals: per-page Markdown source endpoints, `robots.txt` `Content-Signal` directives (the audit scores the values — set `ai-input=yes`/`search=yes` to permit AI answers and search indexing; `ai-input=no` opts out of the real-time AI use AEO depends on), and A2A agent cards (aligned with specification.website)\n5. Re-run the audit and report the score delta.\n\nRules:\n- Always explain proposed changes and get user confirmation before editing files.\n- Do not remove existing schema or content unless the user asks.\n- Preserve existing code style and patterns.\n- If a fix is ambiguous or high-risk, explain the tradeoff before editing.\n\n## Schema\n\nUse when the request is specifically about JSON-LD or schema quality.\n\nValidity issues like duplicate singleton `@type`s and JSON parse errors are **per page**, so a homepage-only audit misses every subpage. Default to sitemap mode for site-wide schema requests (\"audit my schema\", \"are my FAQ blocks valid?\"); use single-URL mode only when the user names one specific page.\n\nSite-wide (default):\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --top-issues --format json --factors structured-data,schema-completeness,schema-validity,entity-consistency\n```\n\nSingle page:\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --format json --factors structured-data,schema-completeness,schema-validity,entity-consistency\n```\n\nReport:\n- Schema types found\n- Property completeness by type\n- Missing recommended properties\n- **Validity errors** (duplicate singleton `@type`s, JSON parse errors, empty `<script>` blocks) — surface these prominently regardless of overall score; Google drops invalid blocks silently from rich results\n- Entity consistency issues\n- In sitemap mode: list every affected URL for each validity error so the user can locate per-page duplicates\n\nProvide corrected JSON-LD examples when useful.\n\nChecklist:\n- `LocalBusiness`: name, address, telephone, openingHours, priceRange, image, url, geo, areaServed, sameAs\n- `FAQPage`: mainEntity with at least 3 Q&A pairs (and only **one** `FAQPage` block per page — duplicates invalidate rich results)\n- `HowTo`: name and at least 3 steps (singleton — only one per page)\n- `Organization`: name, logo, contactPoint, sameAs, foundingDate, url, description\n- Singletons that must not repeat per page: `FAQPage`, `HowTo`, `Article`, `BlogPosting`, `NewsArticle`, `BreadcrumbList`, `Product`, `Recipe`\n\n## llms.txt\n\nUse when the user wants `llms.txt` or `llms-full.txt` created or improved.\n\nIf a URL is provided:\n1. Run:\n   ```bash\n   npx @canonry/aeo-audit@4 \"<url>\" [flags] --format json --factors ai-access-files\n   ```\n2. Inspect existing AI-readable files if present.\n3. Extract key content from the site.\n4. Generate improved `llms.txt` and `llms-full.txt`.\n\nIf no URL is provided:\n1. Inspect the current project.\n2. Extract business name, services, FAQs, contact info, and metadata.\n3. Generate both files from local sources.\n\nAfter generation:\n- Add `<link rel=\"alternate\" type=\"text/markdown\" href=\"/llms.txt\">` when appropriate.\n- Expose per-page Markdown source endpoints (a `.md` URL or content negotiation) advertised via `<link rel=\"alternate\" type=\"text/markdown\">` — a scored AI-readable signal.\n- Suggest adding the files to the sitemap.\n\n## Monitor\n\nUse when the user wants progress tracking or a competitor comparison.\n\nSingle URL:\n1. Run the audit.\n2. Compare against prior results in `.aeo-audit-history/` if present.\n3. Show overall and per-factor deltas.\n4. Save the current result.\n\nComparison mode:\n1. For branch-vs-production, produce baseline and current `--format json` reports in the same mode, then run the `compare` subcommand.\n2. For competitor benchmarking, audit both public URLs and show side-by-side factor deltas.\n3. Highlight advantages, weaknesses, regressions, and priority gaps.\n\n## Behavior\n\n- If the task needs a deployed site and no URL is provided, ask for the URL.\n- If the task is diagnosis only, do not edit files.\n- If the task is a fix request, make edits and verify with a rerun when possible.\n- If the URL is unreachable or not HTML, report the exact failure.\n- If a local/private URL is requested and `--allow-local` is missing, rerun with `--allow-local` only after confirming local preview auditing is intended.\n- If sitemap mode appears to audit production during preview work, rerun with `--rewrite-sitemap-origin`.\n- Prefer concise, evidence-based recommendations over generic SEO advice.\n\nFile v6.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn7frv4wj3y54yjs1331dcchvh81414c\",\n  \"slug\": \"aeo\",\n  \"version\": \"6.0.0\",\n  \"publishedAt\": 1786912600332\n}\n\nFile v6.0.0:skill-card.md\n\n## Description:\n\nRun AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[arberx](https://clawhub.ai/user/arberx)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, site owners, and marketing engineers use this skill to audit answer-engine optimization signals, compare preview or branch changes against production, validate schema, generate AI-readable site files, and apply site fixes after review.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill executes an npm CLI that fetches and analyzes websites.\n\nMitigation: Run audits only against intended targets, quote validated arguments, and review generated commands before execution.\n\nRisk: Local or private audit flags can access localhost, private IPs, or staging systems.\n\nMitigation: Use local/private flags only for systems the user controls and only after explicit opt-in.\n\nRisk: Fix and llms.txt workflows may generate or change site files.\n\nMitigation: Review proposed edits before applying them and verify changes with a follow-up audit when practical.\n\nRisk: Optional Lighthouse/PageSpeed checks can use a PageSpeed API key.\n\nMitigation: Provide API keys only when intentionally enabling those checks and avoid exposing secrets in shared logs or prompts.\n\n## Reference(s):\n\n- [AEO ClawHub skill page](https://clawhub.ai/arberx/skills/aeo)\n- [Canonry homepage](https://canonry.ai)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands, JSON audit reports, and optional generated or modified site files]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May produce audit scores, prioritized fixes, regression verdicts, schema guidance, llms.txt content, robots.txt updates, and code or configuration edits when the user asks for fixes.]\n\n## Skill Version(s):\n\n6.0.0 (source: release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v5.0.0: 3 files, 10572 bytes\n\nFiles: skill-card.md (2332b), SKILL.md (23683b), _meta.json (122b)\n\nFile v5.0.0:SKILL.md\n\n---\nname: aeo\ndescription: Run AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation.\nhomepage: https://canonry.ai\nrepository: https://github.com/Canonry/aeo-audit\nallowed-tools:\n  - Bash(npx @canonry/aeo-audit@4 *)\n  - Read\n  - Glob\n  - Grep\n  - Write(llms.txt)\n  - Write(llms-full.txt)\n  - Write(robots.txt)\n---\n\n# AEO\n\nWebsite: [canonry.ai](https://canonry.ai)\n\nOne skill for audit, preview-branch review, fixes, schema, llms.txt, and monitoring workflows.\n\n## Command\n\nAlways use the published package:\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" [flags] --format json\n```\n\n## Argument Safety\n\n**Never interpolate user input directly into shell commands.** Always:\n1. Validate that the target is either a URL matching `https://` / `http://` or a local filesystem path (static-output mode), and that it contains no shell metacharacters.\n2. Quote every argument individually (e.g., `npx @canonry/aeo-audit@4 \"https://example.com\" --format json`).\n3. Pass flags as separate, literal tokens — never construct command strings from raw user text.\n4. Reject arguments containing characters like `;`, `|`, `&`, `$`, `` ` ``, `(`, `)`, `{`, `}`, `<`, `>`, or newlines.\n\n## Modes\n\n- `audit`: score and diagnose a site\n- `fix`: apply code changes after an audit\n- `schema`: validate JSON-LD and entity consistency\n- `llms`: create or improve `llms.txt` and `llms-full.txt`\n- `monitor`: compare changes over time, compare a branch preview against production, or benchmark competitors\n- `detect-platform`: identify the CMS, site builder, framework, or hosting stack a site uses\n- `compare`: diff two saved `--format json` reports into a regression verdict + exit code (CI gate)\n\nIf no mode is provided, default to `audit`.\n\n## Examples\n\n- `audit https://example.com`\n- `audit https://example.com --sitemap`\n- `audit https://example.com --sitemap --limit 10`\n- `audit https://example.com --sitemap --top-issues`\n- `audit https://example.com --sitemap --format agent` (slim decision for agents)\n- `audit https://example.com --lighthouse`\n- `audit https://example.com --require-meta`\n- `audit https://example.com --sitemap --require-meta`\n- `audit http://localhost:3000 --allow-local`\n- `audit http://localhost:3000 --sitemap --rewrite-sitemap-origin --allow-local`\n- `audit http://localhost:3000 --sitemap --rewrite-sitemap-origin --allow-local --changed --base main --include-critical`\n- `audit https://staging.example.com --sitemap --rewrite-sitemap-origin`\n- `audit ./out` (static-output mode: audit built HTML offline)\n- `audit ./out --base-url https://example.com --require-meta`\n- `fix https://example.com`\n- `schema https://example.com`\n- `llms https://example.com`\n- `monitor https://site-a.com --compare https://site-b.com`\n- `detect-platform https://example.com`\n- `detect-platform https://example.com --min-confidence high`\n- `detect-platform --urls competitors.txt`\n- `detect-platform --urls https://a.com,https://b.com`\n- `compare --baseline baseline.json --current current.json` (fail CI on AEO regression)\n\n## Mode Selection\n\n- If the first argument is one of `audit`, `fix`, `schema`, `llms`, `monitor`, or `detect-platform`, use that mode.\n- If no explicit mode is given, infer the intent from the request and default to `audit`.\n\n## Audit\n\nUse for broad requests such as \"audit this site\" or \"why am I not being cited?\"\n\n1. Run:\n   ```bash\n   npx @canonry/aeo-audit@4 \"<url>\" [flags] --format json\n   ```\n2. Return:\n   - Overall score\n   - Short summary\n   - Factor breakdown\n   - Top strengths\n   - Top fixes\n   - Metadata such as fetch time and auxiliary file availability\n\n#### `--require-meta` (CI gate)\n\nPass `--require-meta` (single or sitemap mode) to force exit `1` whenever any audited page is missing `<meta name=\"description\">`, regardless of the otherwise score-based exit rule. Useful in CI pipelines that need to block deploys on a missing meta description even on otherwise-healthy sites.\n\n### Sitemap Mode\n\nUse `--sitemap` to audit all pages discovered from the site's sitemap:\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap https://example.com/sitemap.xml --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --limit 10 --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --top-issues --format json\n```\n\nFlags:\n- `--sitemap [url]` — auto-discover the sitemap (tries `/sitemap.xml`, then `/sitemap-index.xml`, then `Sitemap:` directives in `/robots.txt`) or provide an explicit URL\n- `--limit <n>` — cap pages audited (default 200, sampled across the site's URL templates rather than taken in sitemap order; `<priority>` orders instances within a template)\n- `--top-issues` — skip per-page output, show only cross-cutting patterns and critical defects\n- `--rewrite-sitemap-origin` — rewrite every `<loc>`'s origin to the target URL's origin (preserving path/query) before crawling. Use when the sitemap hardcodes the prod/canonical domain but you want to audit a staging host or local dev server.\n- `--changed` — filter sitemap URLs to static routes changed since `--base`; use for PR work\n- `--base <ref>` — git base for `--changed` (default `main`)\n- `--include-critical` — add critical paths to the changed-page set\n- `--critical-paths <list>` — comma-separated critical paths for `--include-critical`; defaults to `/`\n- `--require-meta` — force exit `1` if any audited page is missing `<meta name=\"description\">`, regardless of overall score (useful as a CI gate)\n- `--include-geo` / `--include-agent-skills` — honored per page in sitemap mode (adds the optional geographic-signals / agent-skill-exposure factors). `--lighthouse` is not available with `--sitemap`.\n\nPages are audited with bounded concurrency (5 in flight) to avoid hammering the target origin.\n\nReturns:\n- Per-page scores\n- **Critical defects** — binary, one-line-fix structural defects (an `<h1>` count other than one, a missing `<title>`, a missing meta description) surfaced **regardless of how few pages they affect**, with the offending pages named (homepage and high sitemap-`priority` pages first). These would otherwise be averaged into a passing factor score; the JSON field is `criticalDefects` and critical-severity ones are also promoted to the top of `prioritizedFixes`. Shown even with `--top-issues`.\n- Cross-cutting issues (factors failing across multiple pages), each with the best-scoring page (`bestScore`/`bestPageUrl`) and a `status`: `sitewide` (a real coverage gap) vs. `limited`/`opportunity` for page-specific factors (FAQ, definitions) that legitimately apply to only some page types\n- Aggregate score\n- Prioritized fixes (critical defects first, then site-wide gaps; page-specific `limited`/`opportunity` factors demoted below them, scoped to the page(s) that carry them), each costed as `templateCount` templates over `instanceCount` pages\n- **Templates** — pages that share a URL shape *and* score alike, collapsed into the template that produced them, with the page to fix on. \"194 property pages missing schema\" is one template edit, not 194\n- **Coverage** — what the aggregate score was taken over: pages audited/discovered and how many URL templates the sample reached, with a `confidence` of `full` / `representative` / `indicative`. A sample that missed whole templates is labelled `indicative` and does not speak for the sections it never saw\n\n### Preview / PR Audit Workflow\n\nUse this path for PR review, local production builds, preview deployments, and branch-vs-main questions. Prefer built-in flags over manual sitemap downloads, localtunnel glue, or ad hoc URL scripts.\n\nFor a local preview server whose sitemap emits production canonicals:\n\n```bash\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" \\\n  --sitemap \\\n  --rewrite-sitemap-origin \\\n  --allow-local \\\n  --changed \\\n  --base main \\\n  --include-critical \\\n  --format agent\n```\n\nGuidance:\n- Use `--allow-local` only when the user explicitly wants to audit localhost/private IPs.\n- Use `--rewrite-sitemap-origin` when a local or staging sitemap emits production canonicals.\n- Use `--changed --base <ref>` for PR work so unrelated site sections do not dominate the result.\n- Use `--include-critical --critical-paths /,/pricing,/contact` when important pages should always be checked.\n- If `--changed` finds no static routes, inspect the diff manually. Dynamic route templates cannot be safely converted to concrete URLs without route params; include known concrete paths with `--critical-paths` or audit explicit URLs separately.\n- Prefer `--format agent` for agent action, `--format json` for saved compare baselines, and `--format markdown` for human summaries.\n\nFor branch-vs-production regression review, produce comparable reports first, then run `compare`:\n\n```bash\nnpx @canonry/aeo-audit@4 \"https://production.example\" --sitemap --format json > baseline.json\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" --sitemap --rewrite-sitemap-origin --allow-local --format json > current.json\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json --format markdown\n```\n\nReport:\n- URLs audited or changed paths selected\n- Score/regression verdict from `compare`\n- Critical defects and prioritized fixes\n- Caveats such as local/private opt-in, sitemap origin rewriting, dynamic route templates skipped, or sitemap pages filtered out\n\n#### Machine-readable output (for agents)\n\nUse `--format json` for the full report, or **`--format agent`** for just the decision: `{ schemaVersion, tool, mode, url, score, pass, criticalDefectCount, issues }`, where `issues` is the ranked `prioritizedFixes` and the per-factor/per-page detail is omitted. Prefer `--format agent` when you only need to decide and act. Key fields for acting on the result without parsing prose:\n- `schemaVersion` (on every audit report) versions the JSON shape independently of the package version — pin to it and treat a major bump as breaking; absence means a pre-2.0 report.\n- `prioritizedFixes` is a ranked array of objects, each with a stable `id`, `kind`, optional `severity`, the complete `affectedPages` list (never truncated), `affectsHomepage`, `prevalencePct`, and a human `summary`. Cross-cutting fixes also carry `avgScore`, `bestScore`/`bestPageUrl`, and a `status` (`sitewide` | `limited` | `opportunity`) — treat `limited`/`opportunity` as page-specific tune-ups, not site-wide failures. It's the pre-computed to-do list — no need to re-rank factor scores yourself.\n- Stable identifiers everywhere — `criticalDefects[].id`, `prioritizedFixes[].id`, and every factor finding's `code` (e.g. `technical-seo.h1.multiple`) — let integrations key on codes rather than message strings.\n\n#### Auxiliary File Diagnostics\n\nWhen the audit fetches `/llms.txt`, `/llms-full.txt`, `/robots.txt`, and `/sitemap.xml`, it probes once with `Accept: text/markdown` to detect a **content-negotiation** trap: file responds OK to a bare request but returns a non-2xx response when the client prefers markdown. This catches Astro / Vercel / Starlight setups that 307-redirect `.txt` → non-existent `.md` for markdown-accepting clients, making the file invisible to AI content-extraction tools even though the file exists. The diagnostic surfaces as a finding on the **AI Access Files (llms.txt, sitemap)** factor.\n\n### Local Dev / Staging Targets\n\nBy default the audit blocks any URL that resolves to a private, loopback, or link-local address (SSRF protection). When the user wants to audit **their own** dev or staging server, pass `--allow-local` (alias `--allow-private`):\n\n```bash\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" --allow-local --format json\nnpx @canonry/aeo-audit@4 \"http://10.0.5.20\" --allow-private --format json\n```\n\n- Pass the explicit `http://` scheme for local dev servers — a bare host defaults to `https://`.\n- The relaxation is scoped to the **single host named on the CLI**, evaluated per hop. A redirect or sitemap `<loc>` pointing at any other private host (e.g. `169.254.169.254`) stays blocked.\n- To audit a whole local site whose sitemap hardcodes the prod domain, combine with sitemap origin rewriting:\n\n```bash\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" --sitemap --rewrite-sitemap-origin --allow-local --format json\n```\n\n### Static-Output Mode\n\nWhen the user wants to audit **built HTML offline** (CI on a `next export` / `dist` / `out` directory, or before deploying), pass a filesystem path instead of a URL:\n\n```bash\n# A directory of built HTML (aggregated like sitemap mode)\nnpx @canonry/aeo-audit@4 \"./out\" --base-url https://example.com --format json\n# A single built file\nnpx @canonry/aeo-audit@4 \"./dist/index.html\" --format json\n# Gate CI on missing meta descriptions across the build\nnpx @canonry/aeo-audit@4 \"./out\" --require-meta --format json\n```\n\n- A `.html`/`.htm` file → single-page report; a directory → aggregated report (`--limit`, `--top-issues`, `--factors`, `--include-geo`, `--include-agent-skills`, `--require-meta` apply).\n- `--base-url <url>` maps files to page URLs (`out/about/index.html` → `<base>/about/`; default `https://localhost`). `index.html` collapses to its directory URL; other files drop the `.html` extension.\n- `llms.txt`, `llms-full.txt`, `robots.txt`, and `sitemap.xml` are read from the directory root when present.\n- **Partial coverage:** server-only signals (redirects, `X-Robots-Tag`, `Last-Modified`, `Link` headers) aren't visible from static files. Recommend auditing the deployed URL for full coverage.\n\n### Compare / Regression Mode\n\nWhen the user wants to **fail CI on an AEO regression** (a PR dropped the score, broke a page, or introduced a structural defect), use the `compare` subcommand. It diffs two saved `--format json` reports — a baseline and the current run — and exits non-zero on a regression. It runs no audit and no network; it only reads reports.\n\n```bash\n# 1. Produce the current report (any mode's --format json output works)\nnpx @canonry/aeo-audit@4 \"./out\" --base-url https://example.com --format json > current.json\n# 2. Diff against a stored baseline — exit 1 if it regressed\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json\n# Write a Markdown summary (for a PR comment) and tighten the overall gate\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json --overall-tolerance 0 --md-out diff.md\n# Committed/artifact baselines: hard-fail (exit 2) if factor set / engine major differ\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json --strict-comparability\n```\n\n- **A regression is any of:** overall/aggregate drop > `--overall-tolerance` (default 2); a single page drop > `--page-tolerance` (default 5); a single factor drop > `--factor-tolerance` (default 8); a page that was auditing successfully now erroring; a new `severity:critical` defect (`--fail-on-new-critical`, default on); or a major report-schema change. Score/page/factor deltas only gate when the two runs are **comparable** (same factor set, no major engine change) — otherwise they're warnings, not failures.\n- `missing-meta-description` is `severity:warning`, so it does **not** trip `--fail-on-new-critical`; use `--require-meta` on the audit or `--fail-on warnings` here. Removed pages and new warnings are report-only unless promoted with `--fail-on removed-pages,warnings`.\n- **Exit codes:** `0` = no regression / improvement / first run (no baseline); `1` = regression; `2` = misconfiguration (mode mismatch, unreadable report, missing `--current`, or incomparable factor-set/engine under `--strict-comparability`). `--report-only` always exits `0` (soak mode).\n- Both reports must be the same mode (two single, or two multi-page). stdout carries only the `CompareReport` JSON (or Markdown with `--format markdown`); diagnostics go to stderr.\n\n### Lighthouse Mode\n\nUse `--lighthouse` when the user wants page speed, accessibility, or best-practices scoring alongside the AEO factors. It calls Google PageSpeed Insights (mobile strategy) and aggregates Performance + Accessibility + Best Practices into a single optional factor (weight 8).\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --lighthouse --format json\nPAGESPEED_API_KEY=xxx npx @canonry/aeo-audit@4 \"<url>\" --lighthouse --format json\n```\n\nConstraints:\n- Single-URL only — cannot combine with `--sitemap` or `--detect-platform`. Each Lighthouse audit takes 15-30s, which would blow up sitemap runtime.\n- Optional `PAGESPEED_API_KEY` env var lifts anonymous PSI rate limits (25k/day unauthenticated).\n- On PSI failure (unreachable target, timeout, HTTP error) the factor scores 0 and surfaces a `timeout` or `unreachable` finding rather than throwing — the rest of the audit still runs.\n\n### Detect Platform Mode\n\nUse `--detect-platform` when the user wants to know what stack a site is built on (e.g., \"is this WordPress?\", \"what framework does competitor X use?\", \"is this site custom-built?\"). This is much faster than a full audit because it skips analyzer scoring.\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --detect-platform --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --detect-platform --min-confidence high --format json\n```\n\nFlags:\n- `--detect-platform` — switch to detection mode instead of auditing\n- `--min-confidence <lvl>` — filter to `low` (default), `medium`, or `high` confidence\n- `--urls <src>` — run on multiple URLs at once (file path, comma-separated list, or `-` for stdin)\n- `--concurrency <n>` — max in-flight fetches in batch mode (default 5)\n\nThe report groups detections by category (CMS, site builder, e-commerce, framework, SSG, hosting), each with a confidence bucket, a 0–100 score, an optional version, and the signals that matched. When the report's `isCustom` flag is true, no CMS/site-builder/e-commerce platform was identified — the site is likely custom-built. Exit code is `0` when at least one platform is detected, `1` otherwise.\n\n#### Batch detection\n\nWhen the user wants to fingerprint many sites at once (competitor lists, customer cohorts), pass `--urls`:\n\n```bash\nnpx @canonry/aeo-audit@4 --detect-platform --urls urls.txt --format json\nnpx @canonry/aeo-audit@4 --detect-platform --urls https://a.com,https://b.com --format json\ncat urls.txt | npx @canonry/aeo-audit@4 --detect-platform --urls - --format json\n```\n\nThe batch report contains a `results` array; each entry has `status: 'success'` or `'error'`, plus the same shape as a single-URL report on success. Per-URL fetch errors do not abort the run. Exit code is `0` when at least one URL succeeded, `1` otherwise.\n\n## Fix\n\nUse when the user wants code changes applied after the audit.\n\n1. Run:\n   ```bash\n   npx @canonry/aeo-audit@4 \"<url>\" [flags] --format json\n   ```\n2. Find factors scoring below 70 (lowest first).\n3. Apply targeted fixes in the current codebase.\n4. Prioritize:\n   - Structured data and schema completeness\n   - `llms.txt` and `llms-full.txt`\n   - `robots.txt` crawler access\n   - E-E-A-T signals\n   - FAQ markup\n   - freshness metadata\n   - agent-readiness signals: per-page Markdown source endpoints, `robots.txt` `Content-Signal` directives (the audit scores the values — set `ai-input=yes`/`search=yes` to permit AI answers and search indexing; `ai-input=no` opts out of the real-time AI use AEO depends on), and A2A agent cards (aligned with specification.website)\n5. Re-run the audit and report the score delta.\n\nRules:\n- Always explain proposed changes and get user confirmation before editing files.\n- Do not remove existing schema or content unless the user asks.\n- Preserve existing code style and patterns.\n- If a fix is ambiguous or high-risk, explain the tradeoff before editing.\n\n## Schema\n\nUse when the request is specifically about JSON-LD or schema quality.\n\nValidity issues like duplicate singleton `@type`s and JSON parse errors are **per page**, so a homepage-only audit misses every subpage. Default to sitemap mode for site-wide schema requests (\"audit my schema\", \"are my FAQ blocks valid?\"); use single-URL mode only when the user names one specific page.\n\nSite-wide (default):\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --top-issues --format json --factors structured-data,schema-completeness,schema-validity,entity-consistency\n```\n\nSingle page:\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --format json --factors structured-data,schema-completeness,schema-validity,entity-consistency\n```\n\nReport:\n- Schema types found\n- Property completeness by type\n- Missing recommended properties\n- **Validity errors** (duplicate singleton `@type`s, JSON parse errors, empty `<script>` blocks) — surface these prominently regardless of overall score; Google drops invalid blocks silently from rich results\n- Entity consistency issues\n- In sitemap mode: list every affected URL for each validity error so the user can locate per-page duplicates\n\nProvide corrected JSON-LD examples when useful.\n\nChecklist:\n- `LocalBusiness`: name, address, telephone, openingHours, priceRange, image, url, geo, areaServed, sameAs\n- `FAQPage`: mainEntity with at least 3 Q&A pairs (and only **one** `FAQPage` block per page — duplicates invalidate rich results)\n- `HowTo`: name and at least 3 steps (singleton — only one per page)\n- `Organization`: name, logo, contactPoint, sameAs, foundingDate, url, description\n- Singletons that must not repeat per page: `FAQPage`, `HowTo`, `Article`, `BlogPosting`, `NewsArticle`, `BreadcrumbList`, `Product`, `Recipe`\n\n## llms.txt\n\nUse when the user wants `llms.txt` or `llms-full.txt` created or improved.\n\nIf a URL is provided:\n1. Run:\n   ```bash\n   npx @canonry/aeo-audit@4 \"<url>\" [flags] --format json --factors ai-access-files\n   ```\n2. Inspect existing AI-readable files if present.\n3. Extract key content from the site.\n4. Generate improved `llms.txt` and `llms-full.txt`.\n\nIf no URL is provided:\n1. Inspect the current project.\n2. Extract business name, services, FAQs, contact info, and metadata.\n3. Generate both files from local sources.\n\nAfter generation:\n- Add `<link rel=\"alternate\" type=\"text/markdown\" href=\"/llms.txt\">` when appropriate.\n- Expose per-page Markdown source endpoints (a `.md` URL or content negotiation) advertised via `<link rel=\"alternate\" type=\"text/markdown\">` — a scored AI-readable signal.\n- Suggest adding the files to the sitemap.\n\n## Monitor\n\nUse when the user wants progress tracking or a competitor comparison.\n\nSingle URL:\n1. Run the audit.\n2. Compare against prior results in `.aeo-audit-history/` if present.\n3. Show overall and per-factor deltas.\n4. Save the current result.\n\nComparison mode:\n1. For branch-vs-production, produce baseline and current `--format json` reports in the same mode, then run the `compare` subcommand.\n2. For competitor benchmarking, audit both public URLs and show side-by-side factor deltas.\n3. Highlight advantages, weaknesses, regressions, and priority gaps.\n\n## Behavior\n\n- If the task needs a deployed site and no URL is provided, ask for the URL.\n- If the task is diagnosis only, do not edit files.\n- If the task is a fix request, make edits and verify with a rerun when possible.\n- If the URL is unreachable or not HTML, report the exact failure.\n- If a local/private URL is requested and `--allow-local` is missing, rerun with `--allow-local` only after confirming local preview auditing is intended.\n- If sitemap mode appears to audit production during preview work, rerun with `--rewrite-sitemap-origin`.\n- Prefer concise, evidence-based recommendations over generic SEO advice.\n\nFile v5.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn7frv4wj3y54yjs1331dcchvh81414c\",\n  \"slug\": \"aeo\",\n  \"version\": \"5.0.0\",\n  \"publishedAt\": 1786670526203\n}\n\nFile v5.0.0:skill-card.md\n\n## Description:\n\nRun AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[arberx](https://clawhub.ai/user/arberx)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, site maintainers, and marketing engineering teams use this skill to audit websites or built site output for AI answer readiness, schema quality, auxiliary AI access files, and release regressions. It can guide command execution, summarize audit findings, compare reports, and propose or write targeted site files when requested.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Commands for fix, llms, monitor, local/private targets, and output-file flags can read project content, write public-facing files, or save comparison results.\n\nMitigation: Review proposed commands before execution, require explicit opt-in for local/private targets, and confirm file writes or output paths before running those modes.\n\nRisk: Generated llms.txt, llms-full.txt, robots.txt, schema, or site fixes may affect public crawler and AI access behavior.\n\nMitigation: Inspect generated files and proposed site changes before publishing or deploying them.\n\n## Reference(s):\n\n- [Canonry](https://canonry.ai)\n- [AEO audit repository](https://github.com/Canonry/aeo-audit)\n- [ClawHub skill page](https://clawhub.ai/arberx/skills/aeo)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Code, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown guidance with command snippets, JSON audit summaries, and generated text or configuration files.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May write llms.txt, llms-full.txt, robots.txt, and comparison or report files when the user requests those modes.]\n\n## Skill Version(s):\n\n5.0.0 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v4.7.0: 3 files, 10539 bytes\n\nFiles: skill-card.md (2183b), SKILL.md (23683b), _meta.json (122b)\n\nFile v4.7.0:SKILL.md\n\n---\nname: aeo\ndescription: Run AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation.\nhomepage: https://canonry.ai\nrepository: https://github.com/Canonry/aeo-audit\nallowed-tools:\n  - Bash(npx @canonry/aeo-audit@4 *)\n  - Read\n  - Glob\n  - Grep\n  - Write(llms.txt)\n  - Write(llms-full.txt)\n  - Write(robots.txt)\n---\n\n# AEO\n\nWebsite: [canonry.ai](https://canonry.ai)\n\nOne skill for audit, preview-branch review, fixes, schema, llms.txt, and monitoring workflows.\n\n## Command\n\nAlways use the published package:\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" [flags] --format json\n```\n\n## Argument Safety\n\n**Never interpolate user input directly into shell commands.** Always:\n1. Validate that the target is either a URL matching `https://` / `http://` or a local filesystem path (static-output mode), and that it contains no shell metacharacters.\n2. Quote every argument individually (e.g., `npx @canonry/aeo-audit@4 \"https://example.com\" --format json`).\n3. Pass flags as separate, literal tokens — never construct command strings from raw user text.\n4. Reject arguments containing characters like `;`, `|`, `&`, `$`, `` ` ``, `(`, `)`, `{`, `}`, `<`, `>`, or newlines.\n\n## Modes\n\n- `audit`: score and diagnose a site\n- `fix`: apply code changes after an audit\n- `schema`: validate JSON-LD and entity consistency\n- `llms`: create or improve `llms.txt` and `llms-full.txt`\n- `monitor`: compare changes over time, compare a branch preview against production, or benchmark competitors\n- `detect-platform`: identify the CMS, site builder, framework, or hosting stack a site uses\n- `compare`: diff two saved `--format json` reports into a regression verdict + exit code (CI gate)\n\nIf no mode is provided, default to `audit`.\n\n## Examples\n\n- `audit https://example.com`\n- `audit https://example.com --sitemap`\n- `audit https://example.com --sitemap --limit 10`\n- `audit https://example.com --sitemap --top-issues`\n- `audit https://example.com --sitemap --format agent` (slim decision for agents)\n- `audit https://example.com --lighthouse`\n- `audit https://example.com --require-meta`\n- `audit https://example.com --sitemap --require-meta`\n- `audit http://localhost:3000 --allow-local`\n- `audit http://localhost:3000 --sitemap --rewrite-sitemap-origin --allow-local`\n- `audit http://localhost:3000 --sitemap --rewrite-sitemap-origin --allow-local --changed --base main --include-critical`\n- `audit https://staging.example.com --sitemap --rewrite-sitemap-origin`\n- `audit ./out` (static-output mode: audit built HTML offline)\n- `audit ./out --base-url https://example.com --require-meta`\n- `fix https://example.com`\n- `schema https://example.com`\n- `llms https://example.com`\n- `monitor https://site-a.com --compare https://site-b.com`\n- `detect-platform https://example.com`\n- `detect-platform https://example.com --min-confidence high`\n- `detect-platform --urls competitors.txt`\n- `detect-platform --urls https://a.com,https://b.com`\n- `compare --baseline baseline.json --current current.json` (fail CI on AEO regression)\n\n## Mode Selection\n\n- If the first argument is one of `audit`, `fix`, `schema`, `llms`, `monitor`, or `detect-platform`, use that mode.\n- If no explicit mode is given, infer the intent from the request and default to `audit`.\n\n## Audit\n\nUse for broad requests such as \"audit this site\" or \"why am I not being cited?\"\n\n1. Run:\n   ```bash\n   npx @canonry/aeo-audit@4 \"<url>\" [flags] --format json\n   ```\n2. Return:\n   - Overall score\n   - Short summary\n   - Factor breakdown\n   - Top strengths\n   - Top fixes\n   - Metadata such as fetch time and auxiliary file availability\n\n#### `--require-meta` (CI gate)\n\nPass `--require-meta` (single or sitemap mode) to force exit `1` whenever any audited page is missing `<meta name=\"description\">`, regardless of the otherwise score-based exit rule. Useful in CI pipelines that need to block deploys on a missing meta description even on otherwise-healthy sites.\n\n### Sitemap Mode\n\nUse `--sitemap` to audit all pages discovered from the site's sitemap:\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap https://example.com/sitemap.xml --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --limit 10 --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --top-issues --format json\n```\n\nFlags:\n- `--sitemap [url]` — auto-discover the sitemap (tries `/sitemap.xml`, then `/sitemap-index.xml`, then `Sitemap:` directives in `/robots.txt`) or provide an explicit URL\n- `--limit <n>` — cap pages audited (default 200, sampled across the site's URL templates rather than taken in sitemap order; `<priority>` orders instances within a template)\n- `--top-issues` — skip per-page output, show only cross-cutting patterns and critical defects\n- `--rewrite-sitemap-origin` — rewrite every `<loc>`'s origin to the target URL's origin (preserving path/query) before crawling. Use when the sitemap hardcodes the prod/canonical domain but you want to audit a staging host or local dev server.\n- `--changed` — filter sitemap URLs to static routes changed since `--base`; use for PR work\n- `--base <ref>` — git base for `--changed` (default `main`)\n- `--include-critical` — add critical paths to the changed-page set\n- `--critical-paths <list>` — comma-separated critical paths for `--include-critical`; defaults to `/`\n- `--require-meta` — force exit `1` if any audited page is missing `<meta name=\"description\">`, regardless of overall score (useful as a CI gate)\n- `--include-geo` / `--include-agent-skills` — honored per page in sitemap mode (adds the optional geographic-signals / agent-skill-exposure factors). `--lighthouse` is not available with `--sitemap`.\n\nPages are audited with bounded concurrency (5 in flight) to avoid hammering the target origin.\n\nReturns:\n- Per-page scores\n- **Critical defects** — binary, one-line-fix structural defects (an `<h1>` count other than one, a missing `<title>`, a missing meta description) surfaced **regardless of how few pages they affect**, with the offending pages named (homepage and high sitemap-`priority` pages first). These would otherwise be averaged into a passing factor score; the JSON field is `criticalDefects` and critical-severity ones are also promoted to the top of `prioritizedFixes`. Shown even with `--top-issues`.\n- Cross-cutting issues (factors failing across multiple pages), each with the best-scoring page (`bestScore`/`bestPageUrl`) and a `status`: `sitewide` (a real coverage gap) vs. `limited`/`opportunity` for page-specific factors (FAQ, definitions) that legitimately apply to only some page types\n- Aggregate score\n- Prioritized fixes (critical defects first, then site-wide gaps; page-specific `limited`/`opportunity` factors demoted below them, scoped to the page(s) that carry them), each costed as `templateCount` templates over `instanceCount` pages\n- **Templates** — pages that share a URL shape *and* score alike, collapsed into the template that produced them, with the page to fix on. \"194 property pages missing schema\" is one template edit, not 194\n- **Coverage** — what the aggregate score was taken over: pages audited/discovered and how many URL templates the sample reached, with a `confidence` of `full` / `representative` / `indicative`. A sample that missed whole templates is labelled `indicative` and does not speak for the sections it never saw\n\n### Preview / PR Audit Workflow\n\nUse this path for PR review, local production builds, preview deployments, and branch-vs-main questions. Prefer built-in flags over manual sitemap downloads, localtunnel glue, or ad hoc URL scripts.\n\nFor a local preview server whose sitemap emits production canonicals:\n\n```bash\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" \\\n  --sitemap \\\n  --rewrite-sitemap-origin \\\n  --allow-local \\\n  --changed \\\n  --base main \\\n  --include-critical \\\n  --format agent\n```\n\nGuidance:\n- Use `--allow-local` only when the user explicitly wants to audit localhost/private IPs.\n- Use `--rewrite-sitemap-origin` when a local or staging sitemap emits production canonicals.\n- Use `--changed --base <ref>` for PR work so unrelated site sections do not dominate the result.\n- Use `--include-critical --critical-paths /,/pricing,/contact` when important pages should always be checked.\n- If `--changed` finds no static routes, inspect the diff manually. Dynamic route templates cannot be safely converted to concrete URLs without route params; include known concrete paths with `--critical-paths` or audit explicit URLs separately.\n- Prefer `--format agent` for agent action, `--format json` for saved compare baselines, and `--format markdown` for human summaries.\n\nFor branch-vs-production regression review, produce comparable reports first, then run `compare`:\n\n```bash\nnpx @canonry/aeo-audit@4 \"https://production.example\" --sitemap --format json > baseline.json\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" --sitemap --rewrite-sitemap-origin --allow-local --format json > current.json\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json --format markdown\n```\n\nReport:\n- URLs audited or changed paths selected\n- Score/regression verdict from `compare`\n- Critical defects and prioritized fixes\n- Caveats such as local/private opt-in, sitemap origin rewriting, dynamic route templates skipped, or sitemap pages filtered out\n\n#### Machine-readable output (for agents)\n\nUse `--format json` for the full report, or **`--format agent`** for just the decision: `{ schemaVersion, tool, mode, ur\n\nArchive v4.6.2: 3 files, 10535 bytes\n\nFiles: skill-card.md (2182b), SKILL.md (23683b), _meta.json (122b)\n\nArchive v4.6.1: 3 files, 10655 bytes\n\nFiles: skill-card.md (2405b), SKILL.md (23611b), _meta.json (122b)\n\nArchive v4.6.0: 3 files, 10597 bytes\n\nFiles: skill-card.md (2315b), SKILL.md (23611b), _meta.json (122b)\n\nArchive v4.5.0: 3 files, 10578 bytes\n\nFiles: skill-card.md (2345b), SKILL.md (23611b), _meta.json (122b)","readmeExcerpt":"Skill: aeo Owner: arberx Summary: Run AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation. Tags: latest:7.2.0 Version history: v7.2.0 | 2026-09-07T23:51:08.552Z | user Give the derived duration budget room to be a ceiling (#76) v7","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"npx @canonry/aeo-audit@4 \"<url>\" [flags] --format json"},{"language":"bash","snippet":"npx @canonry/aeo-audit@4 \"<url>\" [flags] --format json"},{"language":"bash","snippet":"npx @canonry/aeo-audit@4 \"<url>\" --sitemap --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap https://example.com/sitemap.xml --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --limit 10 --format json\nnpx @canonry/aeo-audit@4 \"<url>\" --sitemap --top-issues --format json"},{"language":"bash","snippet":"npx @canonry/aeo-audit@4 \"http://localhost:3000\" \\\n  --sitemap \\\n  --rewrite-sitemap-origin \\\n  --allow-local \\\n  --changed \\\n  --base main \\\n  --include-critical \\\n  --format agent"},{"language":"bash","snippet":"npx @canonry/aeo-audit@4 \"https://production.example\" --sitemap --format json > baseline.json\nnpx @canonry/aeo-audit@4 \"http://localhost:3000\" --sitemap --rewrite-sitemap-origin --allow-local --format json > current.json\nnpx @canonry/aeo-audit@4 compare --baseline baseline.json --current current.json --format markdown"},{"language":"bash","snippet":"npx @canonry/aeo-audit@4 \"http://localhost:3000\" --allow-local --format json\nnpx @canonry/aeo-audit@4 \"http://10.0.5.20\" --allow-private --format json"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: aeo\ndescription: Run AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation.\nhomepage: https://canonry.ai\nrepository: https://github.com/Canonry/aeo-audit\nallowed-tools:\n  - Bash(npx @canonry/aeo-audit@4 *)\n  - Read\n  - Glob\n  - Grep\n  - Write(llms.txt)\n  - Write(llms-full.txt)\n  - Write(robots.txt)\n---\n\n# AEO\n\nWebsite: [canonry.ai](https://canonry.ai)\n\nOne skill for audit, preview-branch review, fixes, schema, llms.txt, and monitoring workflows.\n\n## Command\n\nAlways use the published package:\n\n```bash\nnpx @canonry/aeo-audit@4 \"<url>\" [flags] --format json\n```\n\n## Argument Safety\n\n**Never interpolate user input directly into shell commands.** Always:\n1. Validate that the target is either a URL matching `https://` / `http://` or a local filesystem path (static-output mode), and that it contains no shell metacharacters.\n2. Quote every argument individually (e.g., `npx @canonry/aeo-audit@4 \"https://example.com\" --format json`).\n3. Pass flags as separate, literal tokens — never construct command strings from raw user text.\n4. Reject arguments containing characters like `;`, `|`, `&`, `$`, `` ` ``, `(`, `)`, `{`, `}`, `<`, `>`, or newlines.\n\n## Modes\n\n- `audit`: score and diagnose a site\n- `fix`: apply code changes after an audit\n- `schema`: validate JSON-LD and entity consistency\n- `llms`: create or improve `llms.txt` and `llms-full.txt`\n- `monitor`: compare changes over time, compare a branch preview against production, or benchmark competitors\n- `detect-platform`: identify the CMS, site builder, framework, or hosting stack a site uses\n- `compare`: diff two saved `--format json` reports into a regression verdict + exit code (CI gate)\n\nIf no mode is provided, default to `audit`.\n\n## Examples\n\n- `audit https://example.com`\n- `audit https://example.com --sitemap`\n- `audit https://example.com --sitemap --limit 10`\n- `audit https://example.com --sitemap --top-issues`\n- `audit https://example.com --sitemap --format agent` (slim decision for agents)\n- `audit https://example.com --lighthouse`\n- `audit https://example.com --require-meta`\n- `audit https://example.com --sitemap --require-meta`\n- `audit http://localhost:3000 --allow-local`\n- `audit http://localhost:3000 --sitemap --rewrite-sitemap-origin --allow-local`\n- `audit http://localhost:3000 --sitemap --rewrite-sitemap-origin --allow-local --changed --base main --include-critical`\n- `audit https://staging.example.com --sitemap --rewrite-sitemap-origin`\n- `audit ./out` (static-output mode: audit built HTML offline)\n- `audit ./out --base-url https://example.com --require-meta`\n- `fix https://example.com`\n- `schema https://example.com`\n- `llms https://example.com`\n- `monitor https://site-a.com --compare https://site-b.com`\n- `detect-platform https://example.com`\n- `detect-platform https://example.com --min-confide"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7frv4wj3y54yjs1331dcchvh81414c\",\n  \"slug\": \"aeo\",\n  \"version\": \"7.2.0\",\n  \"publishedAt\": 1788825068552\n}"},{"path":"skill-card.md","content":"## Description:\n\nRun AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[arberx](https://clawhub.ai/user/arberx)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, site owners, and marketing engineers use this skill to audit and improve how websites expose content to answer engines, crawlers, schema validators, and AI-readable files. It supports deployed sites, preview branches, local builds with explicit private-target opt-in, static HTML output, regression checks, and guided fixes.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill runs a dynamically resolved npm CLI with the agent's normal file, environment, and network permissions.\n\nMitigation: Run it in a sandbox with minimal environment variables, and pin or preinstall a reviewed exact package version before use in sensitive repositories or CI.\n\nRisk: Local or private preview audits can reach internal targets when the user explicitly opts in.\n\nMitigation: Use local/private audit flags only for targets the user controls, keep the scope to the named host, and review any sitemap origin rewriting before crawling.\n\nRisk: Fix and llms.txt workflows may modify site files or AI-readable public metadata.\n\nMitigation: Require user confirmation before edits, review generated diffs, and rerun the relevant audit or validation mode after changes.\n\n## Reference(s):\n\n- [Canonry AEO Homepage](https://canonry.ai)\n- [ClawHub Skill Page](https://clawhub.ai/arberx/skills/aeo)\n- [Publisher Profile](https://clawhub.ai/user/arberx)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands, JSON or agent-format audit reports, and file edits for approved fixes.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May generate or update llms.txt, llms-full.txt, robots.txt, structured data, and comparison summaries when the selected workflow calls for those outputs.]\n\n## Skill Version(s):\n\n7.2.0 (source: ClawHub release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Run AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation. Skill: aeo Owner: arberx Summary: Run AEO audits, preview branch audits, changed-page sitemap audits, local/private preview audits with explicit opt-in, sitemap origin rewriting, static-output audits, regression comparisons, site fixes, schema validation, and llms.txt generation. Tags: latest:7.2.0 Version history: v7.2.0 | 2026-09-07T23:51:08.552Z | user Give the derived duration budget room to be a ceiling (#76) v7","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1201,"uniquenessScore":50,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T06:25:34.209Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T06:25:34.209Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:01:01.707Z","emptyReason":null},"items":[{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-10T18:48:31.762Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}