seo 0.2.9 → 0.2.12

package/evals/bing-webmaster-overview.json

@@ -0,0 +1,31 @@
+{
+  "subject": "bing-webmaster-overview",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Show me how our site is doing in Bing and whether Bing is crawling it cleanly.",
+      "expected_output": "Should use report id bing-webmaster-overview for bounded Bing traffic, crawl, query, and page insights. Should follow the discovery flow with seo_list_reports, seo_describe_report, then seo_run_report using the verified Bing site URL. Should read dataStatus and provenance before findings, traffic comparisons, crawl changes, and opportunities. Should inspect query and page coverage before movements because weekly top-list entries missing from a period are unknown, not zero. Movement comparisons require the entry in every weekly top list in both periods. Should state that Bing evidence does not describe Google or the whole search market and that the inIndex statistic is not URL-level proof of indexing.",
+      "assertions": [
+        "Uses report id bing-webmaster-overview",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Passes the verified Bing site URL",
+        "Reads dataStatus and provenance before findings",
+        "Treats dimensions missing from weekly top lists as unknown rather than zero",
+        "Does not present Bing inIndex as URL-level proof of indexing"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "The Bing report is partial and capped but the returned crawl rows show no 4xx errors. Can we call the site clean?",
+      "expected_output": "Should refuse the all-clear. Should explain that partial or capped evidence only describes the retained Bing rows, that invalid or unavailable rows stay visible, and that Bing is one provider rather than a complete live crawl. Should recommend a bounded live site crawl to verify current response and page evidence.",
+      "assertions": [
+        "Refuses to call the site clean from partial capped evidence",
+        "Keeps capped invalid and unavailable rows visible",
+        "States Bing is one provider rather than a complete live crawl",
+        "Recommends a bounded live crawl for current evidence"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/link-evidence.json

@@ -0,0 +1,29 @@
+{
+  "subject": "link-evidence",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Agent task: show me who links to this site using the connected Bing project.",
+      "expected_output": "Should route to report id link-evidence and describe it before the first run. Should run seo links --project <project> --json or seo_run_report with the verified Bing site. Should read dataStatus, provenance, warnings, caveats, and selection before listing rows. Should call the result bounded Bing evidence, not a complete backlink profile, and should recommend opening selected referring URLs to confirm that the links still exist.",
+      "assertions": [
+        "Uses report id link-evidence",
+        "Reads coverage and limits before link rows",
+        "Does not claim complete backlink coverage or link quality",
+        "Recommends direct verification of selected referring URLs"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Agent task: import ./links.csv and give me every backlink plus domain authority scores.",
+      "expected_output": "Should run report id link-evidence with file ./links.csv and bounded row and output limits, or use seo links --file ./links.csv --json. Should explain that the import can normalize and deduplicate retained rows but cannot create domain authority scores or guarantee every backlink. Should read suppliedRows, validRows, invalidRows, duplicateRows, capped, selection, warnings, and caveats before summarising.",
+      "assertions": [
+        "Uses the bounded file import path",
+        "Reads import provenance and output selection",
+        "Declines to invent domain authority scores",
+        "Does not call the retained rows every backlink"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/seo.json

@@ -82,6 +82,22 @@
         "Offers a bounded live verification instead of asserting the rank"
       ],
       "files": []
+    },
+    {
+      "id": 7,
+      "prompt": "Make a polished HTML report from our latest SEO audit that I can send to a client. The normal generated template looks too generic.",
+      "expected_output": "Should use structured report evidence and create one local standalone HTML file rather than treating the built-in renderer as the required design. Should start from `seo report --project <project> --json` and request `--full` only when the intended layout needs deeper sections. The page should be responsive, accessible, print friendly, self contained, and marked noindex,nofollow. It should visibly preserve the site, reporting period, generated date, provider labels, data status, priorities, caveats, skipped or partial evidence, and verification steps. It may choose a visual style for the audience but must not invent missing values, forecasts, causation, scores, or stronger conclusions. It should keep provider evidence separate, omit secrets and unnecessary raw rows, save the file locally, and tell the user where it was written.",
+      "assertions": [
+        "Creates a local standalone HTML file from structured report evidence",
+        "Uses compact JSON first and requests full detail only when the layout needs it",
+        "Treats layout and visual style as flexible rather than copying the built-in renderer",
+        "Keeps provider labels, dates, data status, caveats, partial states, and verification steps visible",
+        "Does not invent missing values, forecasts, causation, scores, or stronger conclusions",
+        "Keeps provider evidence separate and omits secrets and unnecessary raw rows",
+        "Makes the page responsive, accessible, print friendly, self contained, and noindex",
+        "Saves the file locally and reports its path"
+      ],
+      "files": []
     }
   ]
 }

package/evals/server-log-analysis.json

@@ -0,0 +1,29 @@
+{
+  "subject": "server-log-analysis",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Agent task: analyze ./access.log and tell me which search crawlers are hitting errors.",
+      "expected_output": "Should route to report id server-log-analysis and describe it before the first run. Should run seo server-logs analyze --file ./access.log --json or the structured report with bounded row, path, and output limits. Should read dataStatus, provenance coverage, warnings, caveats, statusCodes, crawlers, and selection before listing crawler paths. Should treat user-agent classification as observed but unverified and should verify important errors against the original log and server configuration.",
+      "assertions": [
+        "Uses report id server-log-analysis",
+        "Reads file coverage and limits before crawler path rows",
+        "Does not treat a user-agent match as verified crawler identity",
+        "Recommends checking important errors against the source evidence"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Agent task: load this huge JSONL access log and keep every raw request so we can search it later.",
+      "expected_output": "Should explain that server-log-analysis is a one-shot streaming aggregate and does not retain raw requests or build a local log database. Should use explicit row, path, and output bounds, then report any capped, malformed, or untracked evidence. Should recommend a dedicated log platform if durable raw-event search is required.",
+      "assertions": [
+        "Uses streaming bounded aggregation",
+        "Does not claim raw log retention",
+        "Keeps capped and malformed evidence visible",
+        "Does not load the whole file into memory"
+      ],
+      "files": []
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seo",
-  "version": "0.2.9",
+  "version": "0.2.12",
   "description": "The only SEO skill your agent needs. 50+ SEO audit tools through a local CLI and MCP server, using your own crawl, Search Console, and Google Analytics data.",
   "type": "module",
   "license": "Apache-2.0",
@@ -74,8 +74,8 @@
     "security:check": "pnpm run security:audit && pnpm run security:secrets",
     "security:secrets": "node scripts/security-secrets.mjs",
     "skills:validate": "node scripts/validate-skills.mjs",
-    "test": "turbo run test && pnpm run build:package && node --test scripts/package.test.mjs scripts/dogfood-summary.test.mjs && node scripts/resource-harness.mjs && node scripts/provider-resource-harness.mjs && pnpm run skills:validate",
-    "test:resources": "pnpm run build:package && node scripts/resource-harness.mjs && node scripts/provider-resource-harness.mjs",
+    "test": "turbo run test && pnpm run build:package && node --test scripts/package.test.mjs scripts/dogfood-summary.test.mjs && node scripts/resource-harness.mjs && node scripts/provider-resource-harness.mjs && node scripts/indexnow-resource-harness.mjs && node scripts/bing-resource-harness.mjs && pnpm run skills:validate",
+    "test:resources": "pnpm run build:package && node scripts/resource-harness.mjs && node scripts/provider-resource-harness.mjs && node scripts/indexnow-resource-harness.mjs && node scripts/bing-resource-harness.mjs",
     "test:package-install": "pnpm run build:package && node --test scripts/installed-package.test.mjs",
     "typecheck": "turbo run typecheck"
   },

package/skills/seo/SKILL.md

@@ -5,25 +5,20 @@ description: Use and read this skill immediately if the user request is in any w
 
 # seo
 
-`seo` is a local CLI, MCP server, and report engine. It answers SEO questions
-with evidence from three sources: its own crawl of the site, Google Search
-Console, and Google Analytics. Every report returns structured JSON with the observed
-evidence, derived findings, caveats, and provenance kept separate. Nothing is
-hosted; data stays on the machine.
-
-You do not need to memorise reports. Discover them at runtime.
+`seo` is a local CLI, MCP server, and report engine using crawl, Search Console,
+Google Analytics, and optional Bing evidence. Reports keep observations,
+findings, caveats, and provenance separate. Data stays local. Discover reports
+at runtime instead of memorising them.
 
 ## Discover, describe, run
 
 With the MCP server (preferred):
 
-1. `seo_list_reports` returns every report id with a one-line purpose,
-   optionally by category.
-2. `seo_describe_report` with one id returns when to use it, when to avoid it,
-   its exact JSON Schema, the order to read its output in, what its evidence
-   cannot support, one verification step, and related report ids.
-3. `seo_run_report` with the id and a bounded `params` object. Read
-   `structuredContent`, not the display text.
+1. `seo_list_reports` returns report ids and purposes, optionally by category.
+2. `seo_describe_report` returns one report's usage, schema, reading order,
+   limits, verification, and related ids.
+3. `seo_run_report` runs bounded `params`. Read `structuredContent`, not display
+   text.
 
 The same catalog exists without MCP:
 
@@ -33,32 +28,22 @@ seo reports describe <report-id> --json
 seo reports run <report-id> --params '<json>' --json
 ```
 
-Always describe a report before its first run in a session. The describe
-response is the per-report manual: follow its `readOrder`, respect its
-`doNotClaim` limits, and use its `related` ids to decide what to run next.
-Reuse the schema for repeated runs. Do not guess parameters.
-
-When a describe response lists `fixableChecks`, the report also serves fix
-guidance per check. After a run, take each failed or warning check id from
-`topActions` and call `seo_describe_report` with `id` and `check` (CLI:
-`seo reports describe <report-id> --check <check-id>`). The result contains
-the goal, fix steps, a ready-to-use agent prompt, spec links, and a
-verification step for that one check. Fetch guidance only for checks you are
-actually going to fix.
+Describe a report before its first run. Follow `readOrder`, `doNotClaim`, and
+`related`; reuse its schema and do not guess parameters. When `fixableChecks`
+exists, fetch guidance only for failed or warning ids in `topActions` with
+`seo_describe_report` using `id` and `check` (CLI:
+`seo reports describe <report-id> --check <check-id>`).
 
 ## Setup and selection
 
-Run the `setup-check` report (or `seo doctor`) if auth state is unknown.
-Saved project profiles are selected with `--project <id>`; list them with
-`seo projects list --json`. Without a profile, pass `--site sc-domain:example.com`
-for Search Console reports or `--url https://example.com` for crawl-only
-reports. Crawl and page audits work with no Google connection at all. Always
-pass `--json`; JSON mode never prompts.
+Use `setup-check` or `seo doctor` when auth is unknown. Select profiles with
+`--project <id>` and list them with `seo projects list --json`. Without one,
+pass `--site sc-domain:example.com` or `--url https://example.com`. Crawl audits
+need no Google connection. Agent commands use `--json`, which never prompts.
 
 ## Common jobs
 
-Each job lists report ids in a sensible starting order. Run the first, read
-its evidence, then decide; do not run a whole chain blindly.
+Run the first report, read it, then decide. Do not run a whole chain blindly.
 
 | Job | Reports |
 |---|---|
@@ -70,33 +55,39 @@ its evidence, then decide; do not run a whole chain blindly.
 | AI search visibility and eligibility | `ai-readiness`, `geo-gaps`, `ai-referrals`, `seo-to-ai-query` |
 | Plan content from real demand | `query-clusters`, `page-opportunities`, `content-optimization`, `cannibalisation` |
 | Catch regressions over time | `technical-watch`, `crawl-diff`, `index-watch`, `measure-change` after a fix ships |
+| Review Bing traffic, crawl, query, and page insights | `bing-webmaster-overview`, then `site-crawl` when live page evidence is needed |
+| See who links to the site | `link-evidence`, then verify selected referring URLs directly |
+| Review real crawler requests in a server log | `server-log-analysis`, then verify important errors against the original log and server configuration |
 | Client-ready reporting | `monthly-report`, `narrative-report`, `monthly-action-plan` |
 | Turn crawl findings into tickets | `top-fixes`, `affected-urls`, `explain-crawl-issue` |
 
-A single page complaint usually needs both angles: the index evidence for that
-URL and an `audit-page` pass for content or technical problems on the page
-itself.
-
-The main human report is the `seo report` command. It is the right first move
-for a broad performance question with a known project and available search
-evidence. For a broad technical audit of a large or unfamiliar URL, run the
-sitemap health pass before any full crawl. The focused reports above are for
-specific symptoms.
-
-For a large or unfamiliar site, do not open with a full crawl. Describe and run
-`site-crawl` with `health: true` and an explicit `sitemapUrl` when known. This
-first pass checks sitemap URL responses, redirects, robots decisions, and
-access blocks without downloading, parsing, rendering, or caching page bodies.
-Read `config.strategy`, `access`, failures, limits, and sitemap completeness.
-Run the full `site-crawl` second only when the question needs page content,
-metadata, canonicals, internal links, structured data, or rendered HTML.
-
-The crawler identifies every HTTP and browser request as
-`SEO-Skill/<version> (+https://seoskill.dev)`. If `access.blockedRequests` is
-non-zero, give the user the provider evidence and exact User-Agent. A
-User-Agent is spoofable, so ask for a temporary exception scoped to the audit
-machine source IP, hostname or required paths, and only the blocking security
-rule. Never recommend a broad User-Agent-only bypass.
+Use `seo report` first for a broad performance question with a known project.
+For a large or unfamiliar URL, run sitemap health before a full crawl.
+
+## Create a client HTML report
+
+For a polished or branded report, create one standalone HTML file from
+structured data. Built-in `--format html` is a predictable fallback. Start with
+compact JSON and request `--full` only when deeper evidence is needed. Follow
+supplied brand direction and design for the findings. Use responsive,
+accessible, print-friendly HTML, embedded CSS, `noindex,nofollow`, and no remote
+scripts or assets.
+
+Show site, period, generated date, provider labels, data status, priorities,
+limitations, and verification. Preserve partial, capped, sampled, missing, and
+skipped states. Keep observations separate from interpretation and providers
+separate from each other. Never invent scores, forecasts, causes, or missing
+values. Omit secrets and unnecessary raw rows. Save locally and report the path.
+
+For a large site, run `site-crawl` with `health: true` and an explicit
+`sitemapUrl` when known. Read `config.strategy`, `access`, failures, limits, and
+sitemap completeness. Full crawl second only for page content, metadata,
+canonicals, links, structured data, or rendered HTML.
+
+Requests use `SEO-Skill/<version> (+https://seoskill.dev)`. For
+`access.blockedRequests`, show provider evidence and the identity. Ask for a
+temporary exception scoped by audit IP, host or paths, and blocking rule. Never
+recommend a User-Agent-only bypass.
 
 ## Evidence rules
 
@@ -115,13 +106,11 @@ rule. Never recommend a broad User-Agent-only bypass.
 
 ## Beyond the report catalog
 
-The CLI also has direct commands for raw provider access and administration:
-`seo gsc-query`, `seo url-inspect`, `seo analytics google properties`,
-`seo analytics google report`, `seo updates`, `seo crawl`, `seo export`, and
-`seo projects`. Use `seo help all` to list everything. Prefer a registered
-report when one covers the question, because reports carry provenance and
-caveats that raw queries do not.
+Use `seo help all` for direct provider and administration commands. Bing setup
+uses `seo providers bing`; link evidence uses `seo links --project <id> --json`
+or `seo links --file <path> --json`. IndexNow writes externally: validate with
+`seo indexnow submit --dry-run --json` and remove dry run only when authorised.
+Receipt does not prove crawling or indexing. Prefer registered reports.
 
-Full report output is cached locally. Pass `refresh: true` (or `--refresh`)
-only when the user explicitly wants a fresh fetch. The sitemap health strategy
-always bypasses page-body cache and never writes page responses to it.
+Use `refresh: true` or `--refresh` only when fresh data is requested. Sitemap
+health always bypasses page-body cache and never writes page responses.