seo 0.1.0 → 0.2.1

package/evals/community-intent.json

@@ -0,0 +1,57 @@
+{
+  "subject": "community-intent",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "What are people searching that shows they want reviews, comparisons, or real experiences?",
+      "expected_output": "Should use report id community-intent to find Search Console queries that explicitly ask for reviews, comparisons, recommendations, or real experience. Should follow the discovery flow: seo_list_reports with category ai-search, seo_describe_report with id community-intent, then seo_run_report with the required site. Should read dataStatus, source.completeness, warnings, and caveats first. Should clarify the intent labels are low-confidence English language heuristics based on explicit query wording, not verified intent.",
+      "assertions": [
+        "Uses report id community-intent for review and comparison query wording",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Reads dataStatus, source.completeness, warnings, and caveats first",
+        "States intent labels are low-confidence English language heuristics, not verified intent",
+        "Grounds the labels in explicit query wording rather than guessed intent"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Run community intent for sc-domain:example.com over 180 days, top 50 queries, at least 50 impressions, and exclude brand terms.",
+      "expected_output": "Should run report id community-intent with site sc-domain:example.com, days 180, limit 50, minImpressions 50, and includeBrand false. Should read selection.classifiedRows for every match and selection.returnedRows for the limited set, then per-item intent, signals, and matchedTerms. Should note limit bounds the returned set while classifiedRows shows all matches, and use only parameters defined in the schema.",
+      "assertions": [
+        "Runs report id community-intent with days 180, limit 50, and minImpressions 50",
+        "Sets includeBrand false to exclude brand terms",
+        "Reads selection.classifiedRows for all matches and selection.returnedRows for the limited set",
+        "Reads per-item intent, signals, and matchedTerms",
+        "Uses only parameters defined in the report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "For each of these community queries, tell me which page ranks and confirm the searcher's real intent.",
+      "expected_output": "Should decline to name the ranking URL or confirm verified intent from this report. Should state the classifier does not inspect the live SERP or identify the ranking URL, and that intent labels are low-confidence English language heuristics, not verified intent. Should recommend retrieving GSC query and page rows to find the ranking URL and check its content against the observed query language. Should route to page-opportunities to review one ranking URL and content-optimization to turn intent into a brief.",
+      "assertions": [
+        "Declines to name the ranking URL from this report",
+        "States the classifier does not inspect the live SERP or identify the ranking URL",
+        "States intent labels are low-confidence heuristics, not verified intent",
+        "Recommends retrieving GSC query and page rows to find the ranking URL",
+        "Routes to report id page-opportunities or report id content-optimization"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "No community-intent rows came back for our product category, so there is no review demand there.",
+      "expected_output": "Should refuse to read the empty result as absence of demand. Should state a capped or partial zero is inconclusive, not absence of demand, and check dataStatus, source.completeness, warnings, and caveats. Should keep filtered, capped, partial, and complete states distinct and recommend widening the window with days, lowering minImpressions, or raising maxRows before concluding there is no review demand.",
+      "assertions": [
+        "Refuses to treat the empty result as absence of demand",
+        "States a capped or partial zero is inconclusive, not absence of demand",
+        "Checks dataStatus, source.completeness, warnings, and caveats",
+        "Keeps filtered, capped, partial, and complete states distinct",
+        "Recommends widening the window or lowering minImpressions before concluding"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/compare-crawls.json

@@ -0,0 +1,56 @@
+{
+  "subject": "compare-crawls",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We pushed a big migration last week. Can you tell me what actually changed on the site technically since before it went out?",
+      "expected_output": "Should use report id compare-crawls to produce a before-and-after view of added, removed, fixed, and new findings from two saved crawl snapshots. Should follow the discovery flow: seo_describe_report with id compare-crawls, then seo_run_report with the before and after snapshot ids. Should read comparability.status and its matching flags first, then the preserved config, requestScope, and caps for each side, then top-level completeness and truncated reason codes, then summary, pageChanges, and issueChanges. Should offer report id crawl-history to find the snapshot ids.",
+      "assertions": [
+        "Uses report id compare-crawls for the before-and-after view",
+        "Reads comparability.status and its matching flags before any delta",
+        "Reads preserved config, requestScope, and caps for both snapshots",
+        "Reads summary, pageChanges, and issueChanges after the completeness checks",
+        "Offers report id crawl-history to locate the two snapshot ids"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Compare saved crawls with before crawl_example_20260601 and after crawl_example_20260710 and confirm the canonical fix landed.",
+      "expected_output": "Should run report id compare-crawls with before crawl_example_20260601 and after crawl_example_20260710, via seo reports run compare-crawls or seo_run_report. Should check comparability.status and matching flags before reading any change, then issueChanges for the canonical rule. Should note source row caps limit joined GSC or GA4 evidence even when the document crawl completed, and that verification is re-running the same definition and request scope after deployment.",
+      "assertions": [
+        "Runs report id compare-crawls with the before and after snapshot ids as given",
+        "Checks comparability.status and matching flags before reading any change",
+        "Reads issueChanges to confirm the canonical rule delta",
+        "Notes source row caps limit joined GSC or GA4 evidence even when the crawl completed",
+        "Uses only parameters defined in the report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "A page shows up in the before crawl but not the after crawl, and issues dropped after the release. So the release removed the page and fixed those issues, correct?",
+      "expected_output": "Should refuse both causal conclusions. Should explain that an absent page from a capped, skipped, failed, or differently scoped crawl is not proven removed, and that a change between snapshots is not proof the release caused it. Should check comparability.status, the caps, and the scope on both sides before drawing any conclusion, and should recommend re-running the same definition and request scope to confirm the delta rather than asserting cause.",
+      "assertions": [
+        "Refuses to treat an absent page as proven removed",
+        "States absence can come from a capped, skipped, failed, or differently scoped crawl",
+        "Refuses to treat the change as proof the release caused it",
+        "Checks comparability.status, caps, and scope on both sides first",
+        "Recommends re-running the same definition and scope to confirm the delta"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "The two crawls I picked used different page limits and start URLs, but just diff them and give me the numbers anyway.",
+      "expected_output": "Should warn that materially different scope or settings make the comparison unreliable and that report id compare-crawls should be avoided when the two crawls used different scope. Should read comparability.status and its matching flags and surface that the snapshots are not comparable rather than presenting the raw delta as a real change. Should recommend re-running both sides with the same definition and request scope before comparing.",
+      "assertions": [
+        "Warns that different scope or settings make the diff unreliable",
+        "Reads comparability.status and its matching flags to show the crawls are not comparable",
+        "Does not present the raw delta as a confirmed change",
+        "Recommends re-running both sides with the same definition and request scope"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/content-optimization.json

@@ -0,0 +1,57 @@
+{
+  "subject": "content-optimization",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Help me improve this blog post using what people actually search for.",
+      "expected_output": "Should use report id content-optimization to turn a page and its Search Console queries into a practical brief for improving relevance and coverage. Should follow the discovery flow: seo_list_reports with category ai-search, seo_describe_report with id content-optimization, then seo_run_report with the required site and url. Should read sourceReport dataStatus, selection, benchmark.possiblyTruncated, and verification.status first, then treat summary.score and primaryIntent as heuristics.",
+      "assertions": [
+        "Uses report id content-optimization for the page brief",
+        "Notes the report requires both site and url",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Reads sourceReport dataStatus, selection, benchmark.possiblyTruncated, and verification.status first",
+        "Treats summary.score and primaryIntent as heuristics"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Run the content brief for site sc-domain:example.com and url https://example.com/guide over 90 days, verify the live content, top 25 queries.",
+      "expected_output": "Should run report id content-optimization with site sc-domain:example.com, url https://example.com/guide, days 90, verifyContent true, and limit 25. Should read verification.status before treating any live-content observation as verified, and read topActions separating technical-check and unverified items from verified observations. Should then read intentMix and the source query metrics, and use only parameters defined in the schema.",
+      "assertions": [
+        "Runs report id content-optimization with site and url and days 90",
+        "Sets verifyContent true and limit 25 as requested",
+        "Reads verification.status before treating live-content observations as verified",
+        "Separates technical-check and unverified topActions from verified observations",
+        "Uses only parameters defined in the report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Give me the estimated click lift from this brief and just drop every suggested query phrase into the copy to lock it in.",
+      "expected_output": "Should refuse to present estimatedClickLift as a forecast and should decline to force the query wording into the copy. Should state estimatedClickLift and score are prioritisation heuristics, not forecasts or quality grades, that query wording is not a content mandate, and that adding suggested wording is not guaranteed traffic. Should recommend fetching the page after the edit and confirming the missing answer block or clearer framing is present.",
+      "assertions": [
+        "Refuses to present estimatedClickLift as a forecast",
+        "States estimatedClickLift and score are prioritisation heuristics, not forecasts or quality grades",
+        "States query wording is not a content mandate",
+        "States adding suggested wording is not guaranteed traffic",
+        "Recommends fetching the page after the edit to confirm the change"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "I ran it without content verification, but topActions says add a comparison section, so the page is definitely missing one.",
+      "expected_output": "Should not treat an unverified topAction as a confirmed live-page gap. Should read verification.status and note that without verifyContent the brief has query evidence but no verified content observation, so unverified and technical-check actions are not confirmed against the live page. Should keep verified and unverified states distinct and recommend running with verifyContent true or fetching the page before concluding the section is missing.",
+      "assertions": [
+        "Refuses to treat the unverified topAction as a confirmed live-page gap",
+        "Reads verification.status to classify the action",
+        "States unverified and technical-check actions are not confirmed against the live page",
+        "Keeps verified and unverified states distinct",
+        "Recommends setting verifyContent true or fetching the page before concluding"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/crawl-diff.json

@@ -0,0 +1,58 @@
+{
+  "subject": "crawl-diff",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We just shipped a big deploy. Did anything technical break on the site?",
+      "expected_output": "Should route to report id crawl-diff, which crawls the site and compares it with the previous matching run. Should follow the discovery flow: seo_list_reports with category monitoring, seo_describe_report with id crawl-diff, then seo_run_report with a startUrl. Should read run versus previousRun first, treating a missing previous run as a baseline, then the start URL, limit, counts, timestamps, rendering, and warnings for both runs, then the summary counts traced into items before, after, and changes. Should treat recommendations as review actions.",
+      "assertions": [
+        "Uses report id crawl-diff for the post-deploy technical check",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Reads run versus previousRun and treats a missing previous run as a baseline",
+        "Reads counts, rendering, and warnings for both runs",
+        "Reads the summary counts traced into before, after, and changes",
+        "Treats recommendations as review actions rather than confirmed defects"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Agent task: run crawl-diff starting at https://example.com with a 500 page limit and JavaScript rendering.",
+      "expected_output": "Should run report id crawl-diff with startUrl https://example.com, limit 500, and js true, via seo reports run crawl-diff or seo_run_report. Should use only startUrl, site, limit, refresh, and js from the schema. Should note that a first run with no previousRun is a baseline, not a change set, and that comparability depends on running with a comparable scope next time.",
+      "assertions": [
+        "Runs report id crawl-diff with startUrl, limit 500, and js true",
+        "Uses only parameters defined in the crawl-diff schema",
+        "States a first run with no previousRun is a baseline, not a change set",
+        "Notes comparability depends on a comparable scope on the next run",
+        "Reads the fresh run and previousRun before the changes"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Twelve URLs are gone from the diff, so we deleted 12 pages, and the crawl is clean now so our rankings are safe.",
+      "expected_output": "Should refuse both claims. A removed URL may be outside the current discovered set or limit rather than deleted. A bounded diff is not an inventory-wide audit and does not show ranking impact. Should recommend repeating the crawl with comparable scope and confirming the changed items before concluding pages were deleted or that rankings are unaffected.",
+      "assertions": [
+        "Refuses to treat a removed URL as a deleted page",
+        "States a removed URL may be outside the current discovered set or limit",
+        "States a bounded diff is not an inventory-wide audit",
+        "Refuses to claim the diff shows ranking impact",
+        "Recommends repeating the crawl with comparable scope to confirm"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "Those issues do not appear in this run, so they are fixed, even though the log shows some fetches failed.",
+      "expected_output": "Should not treat the absence as resolved when fetches failed. A fetch or extraction failure cannot support a resolved issue. Should read the warnings and rendering for both runs and keep a failed fetch distinct from a resolved finding. Should recommend re-running with comparable scope and confirming the changed item before calling the issues fixed.",
+      "assertions": [
+        "Refuses to call the issues fixed when fetches failed",
+        "States a fetch or extraction failure cannot support a resolved issue",
+        "Reads the warnings and rendering for both runs",
+        "Keeps a failed fetch distinct from a resolved finding",
+        "Recommends re-running with comparable scope to confirm the fix"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/crawl-history.json

@@ -0,0 +1,44 @@
+{
+  "subject": "crawl-history",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I ran a few crawls of our site over the last month and lost track of them. Which ones do I have saved?",
+      "expected_output": "Should use report id crawl-history to list the local crawl snapshots so the user can choose one by site and date. Should follow the discovery flow: seo_describe_report with id crawl-history, then seo_run_report, optionally scoped by site and a bounded limit. Should read each snapshot id, site, start URL, creation time, and status, then total pages and issue count, then the configuration hash and storage version. Should present the list as orientation metadata for choosing a snapshot, not as findings.",
+      "assertions": [
+        "Uses report id crawl-history to list saved crawl snapshots",
+        "Optionally scopes by site and passes a bounded limit",
+        "Reads each snapshot id, site, start URL, creation time, and status",
+        "Reads total pages and issue count as orientation, not findings",
+        "Presents the list for choosing a snapshot rather than analysing it"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "List the last 5 saved crawls for sc-domain:example.com so I can grab the newest snapshot id.",
+      "expected_output": "Should run report id crawl-history with site sc-domain:example.com and limit 5, via seo reports run crawl-history or seo_run_report. Should read each snapshot id, site, start URL, creation time, and status to identify the newest one, then hand the chosen id to report id crawl-report for inspection. Should note that a saved list can expose stale data, so the loaded snapshot's caveats still need checking before analysis.",
+      "assertions": [
+        "Runs report id crawl-history with site sc-domain:example.com and limit 5",
+        "Reads snapshot id, site, start URL, creation time, and status to pick the newest",
+        "Hands the chosen id to report id crawl-report for inspection",
+        "Notes a saved list can expose stale data",
+        "Uses only parameters defined in the report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "The newest crawl has way fewer pages than the one before it. That means our site shrank, right? And the higher issue count means it's in worse shape.",
+      "expected_output": "Should refuse both readings. Should explain that a smaller page count could reflect a scope change, cap, or failure rather than a real site change, and that the counts are orientation metadata, not severity or completeness. Should recommend loading each snapshot with report id crawl-report and comparing scope and caveats, or using report id compare-crawls with matched scope, before concluding anything about site size or health.",
+      "assertions": [
+        "Refuses to read a smaller page count as the site shrinking",
+        "States a smaller count can reflect a scope change, cap, or failure",
+        "States the counts are orientation metadata, not severity or completeness",
+        "Recommends loading snapshots with report id crawl-report to compare scope and caveats",
+        "Suggests report id compare-crawls with matched scope for a real before-and-after"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/crawl-report.json

@@ -0,0 +1,44 @@
+{
+  "subject": "crawl-report",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Open the crawl I saved earlier and show me the summary before I dig into anything.",
+      "expected_output": "Should use report id crawl-report to load a saved crawl by id, or the latest local crawl for a site, and return its summary. Should follow the discovery flow: seo_describe_report with id crawl-report, then seo_run_report with the id or site. Should read id, source URL and site, generatedAt, definition id, config hash, status, and requestEvidenceStatus first, then summary counts and pageLimitReached, then data sources, warnings, and caveats. Should keep page and issue detail opt-in through includePages and includeIssues.",
+      "assertions": [
+        "Uses report id crawl-report to load the saved crawl",
+        "Reads generatedAt, status, and requestEvidenceStatus before the summary",
+        "Reads summary counts and pageLimitReached next",
+        "Keeps page and issue detail opt-in via includePages and includeIssues",
+        "Reads data sources, warnings, and caveats before analysis"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Load crawl_example_20260710 with includeIssues true so I can see the technical findings.",
+      "expected_output": "Should run report id crawl-report with id crawl_example_20260710 and includeIssues true, via seo reports run crawl-report or seo_run_report. Should confirm status and requestEvidenceStatus, then read summary counts and pageLimitReached, then the issues once includeIssues is set. Should note that loading a report is a local storage read, not a fresh check, and that pageLimitReached true means the crawl was capped.",
+      "assertions": [
+        "Runs report id crawl-report with id crawl_example_20260710 and includeIssues true",
+        "Confirms status and requestEvidenceStatus before reading detail",
+        "Reads summary counts and pageLimitReached before the issues",
+        "States loading a report is a local storage read, not a fresh check",
+        "Uses only parameters defined in the report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "This saved crawl passed with no critical issues, so that's the current state of the live site. We're good, right?",
+      "expected_output": "Should refuse to treat a saved crawl as the current live state. Should explain that a report can be internally valid yet stale, capped, or partial and cannot prove the current live state, and that loading it is a local storage read rather than a fresh check. Should check generatedAt, pageLimitReached, and caveats, and recommend running a new crawl with the same configuration and keeping both ids to confirm the current state.",
+      "assertions": [
+        "Refuses to treat the saved crawl as the current live state",
+        "States a valid report can still be stale, capped, or partial",
+        "States loading a report is a local storage read, not a fresh check",
+        "Checks generatedAt, pageLimitReached, and caveats",
+        "Recommends a new crawl with the same configuration to confirm current state"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/crawler-rules.json

@@ -0,0 +1,44 @@
+{
+  "subject": "crawler-rules",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "What technical checks can this tool actually run on a crawl? I want to see what's available before I ask for anything specific.",
+      "expected_output": "Should use report id crawler-rules to return the catalog of available technical check IDs and the evidence each rule looks for. Should follow the discovery flow: seo_describe_report with id crawler-rules, then seo_run_report, optionally scoped by category. Should read each rule id, title, and category, then default severity as triage metadata, then guidance metadata. Should present the list as a catalog of available checks, not as findings on any specific site.",
+      "assertions": [
+        "Uses report id crawler-rules to list the available checks",
+        "Reads each rule id, title, and category",
+        "Treats default severity as generic triage metadata, not actual priority",
+        "Presents the catalog as available checks, not findings on a site",
+        "Does not imply any listed rule was triggered by a crawl"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Show me only the indexability rules so I can pick the right rule id for an affected-urls run.",
+      "expected_output": "Should run report id crawler-rules with category indexability, one of the allowed enum values, via seo reports run crawler-rules or seo_run_report. Should read each rule id, title, and category, then read the guidance metadata to choose the correct id, then pass that exact id to report id affected-urls or report id explain-crawl-issue against a real crawl. Should note that listing a rule does not mean any page triggered it.",
+      "assertions": [
+        "Runs report id crawler-rules with category indexability from the allowed enum",
+        "Reads each rule id, title, and category to pick the right one",
+        "Passes the chosen id to report id affected-urls or report id explain-crawl-issue",
+        "States listing a rule does not mean any page triggered it",
+        "Uses only the category enum values defined in the report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "This rule is marked high severity in the catalog, so it must be the most urgent thing on our site and a Google requirement. Add it to the top of the list.",
+      "expected_output": "Should refuse both claims. Should explain that default severity is generic triage metadata, not actual priority for this site, and that listing a rule does not make the convention a search-engine requirement. Should note that similarly named rules may not share source semantics. Should recommend confirming the rule against real evidence with report id affected-urls and ranking real findings with report id top-fixes before deciding urgency.",
+      "assertions": [
+        "Refuses to treat default severity as this site's actual priority",
+        "States listing a rule does not make the convention a search-engine requirement",
+        "Notes similarly named rules may not share source semantics",
+        "Recommends confirming the rule with report id affected-urls against real evidence",
+        "Recommends report id top-fixes to rank real findings before deciding urgency"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/ctr-underperformers.json

@@ -0,0 +1,57 @@
+{
+  "subject": "ctr-underperformers",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Which queries get lots of impressions but hardly any clicks?",
+      "expected_output": "Should use report id ctr-underperformers to find high-impression queries whose click-through rate trails comparable queries at similar positions. Should follow the discovery flow: seo_list_reports with category opportunities, seo_describe_report with id ctr-underperformers, then seo_run_report with the required site. Should read dataStatus, range, source.completeness, possiblyTruncated, and validation counts first. Should clarify these are title or snippet review candidates, not a promised click uplift.",
+      "assertions": [
+        "Uses report id ctr-underperformers for the CTR comparison queue",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Reads dataStatus, range, source.completeness, possiblyTruncated, and validation counts first",
+        "Frames the rows as title or snippet review candidates",
+        "States the report does not promise a click uplift"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Run CTR underperformers for sc-domain:example.com, at least 500 impressions, top 30, exclude brand.",
+      "expected_output": "Should run report id ctr-underperformers with site sc-domain:example.com, minImpressions 500, limit 30, and includeBrand false. Should read selection before the queue, then per-item query, URL, impressions, position, observed CTR, target CTR, and benchmark source, then the estimated shortfall. Should use only parameters defined in the schema and not invent a days parameter, since the report does not accept one.",
+      "assertions": [
+        "Runs report id ctr-underperformers with minImpressions 500 and limit 30",
+        "Sets includeBrand false to exclude brand terms",
+        "Reads per-item observed CTR, target CTR, and benchmark source",
+        "Reads selection before the queue and the estimated shortfall",
+        "Uses only parameters defined in the schema and does not invent a days parameter"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Add up the estimated shortfall across these rows to get the clicks we will gain once we rewrite the titles.",
+      "expected_output": "Should refuse to total the shortfall as promised clicks. Should state the shortfall is directional prioritisation math, not a traffic forecast, and that page-one average position hides day, device, geography, and result-feature variation, so a title change does not promise clicks. Should recommend inspecting the current SERP and displayed title link, then comparing a complete later period after testing framing.",
+      "assertions": [
+        "Refuses to total the shortfall into promised clicks",
+        "States the shortfall is directional prioritisation math, not a traffic forecast",
+        "Notes page-one average position hides day, device, geography, and result-feature variation",
+        "Recommends inspecting the current SERP and displayed title link",
+        "Recommends comparing a complete later period after testing framing"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "No underperformers came back, so all our titles are already optimal.",
+      "expected_output": "Should refuse to read the empty result as an all-clear. Should state a partial empty result is not an all-clear and check source.completeness, possiblyTruncated, and the validation counts. Should note the comparison groups may have too little data to benchmark, and recommend lowering minImpressions or widening the input before concluding the titles are optimal.",
+      "assertions": [
+        "Refuses to read the empty result as an all-clear",
+        "States a partial empty result is not an all-clear",
+        "Checks source.completeness, possiblyTruncated, and validation counts",
+        "Notes the comparison groups may have too little data to benchmark",
+        "Recommends lowering minImpressions or widening the input before concluding"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/decaying-pages.json

@@ -0,0 +1,57 @@
+{
+  "subject": "decaying-pages",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Which of our pages are losing search traffic?",
+      "expected_output": "Should use report id decaying-pages to find pages and queries with meaningful click declines across comparable Search Console periods. Should follow the discovery flow: seo_list_reports with category opportunities, seo_describe_report with id decaying-pages, then seo_run_report with the required site. Should read dataStatus, ranges, and source.completeness first, then the current and previous fetched rows, caps, truncation, and invalid rows in selection. Should clarify a diagnosis such as lost_position or lost_ctr labels correlated movement, not a cause.",
+      "assertions": [
+        "Uses report id decaying-pages for the click-decline investigation list",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Reads dataStatus, ranges, and source.completeness first",
+        "Reads current and previous fetched rows, caps, truncation, and invalid rows in selection",
+        "States lost_position or lost_ctr labels correlated movement, not a cause"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Run the decay report for sc-domain:example.com year over year, at least a 30 percent drop, at least 100 previous clicks, top 25 pages.",
+      "expected_output": "Should run report id decaying-pages with site sc-domain:example.com, comparison year-over-year, minDropPct 30, minPreviousClicks 100, and limit 25. Should read summary.observedRetainedQueryClickLoss versus the returned subset, then per-item clicks, impressions, CTR, position, and signals. Should use only parameters defined in the schema.",
+      "assertions": [
+        "Runs report id decaying-pages with comparison year-over-year",
+        "Sets minDropPct 30, minPreviousClicks 100, and limit 25 as requested",
+        "Reads summary.observedRetainedQueryClickLoss versus the returned subset",
+        "Reads per-item clicks, impressions, CTR, position, and signals",
+        "Uses only parameters defined in the report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "The lost_ctr label means the old content caused the decline, so add up all the drops for our total lost traffic.",
+      "expected_output": "Should refuse both moves. Should state a diagnosis such as lost_ctr or lost_position labels correlated movement, not a cause, and that capped rows must not be summed into a property-wide loss. Should note missing retained rows are not zero traffic. Should recommend checking deployments, live indexability, and SERP composition for the affected URLs before editing.",
+      "assertions": [
+        "Refuses to read lost_ctr as an established cause",
+        "States the diagnosis labels correlated movement, not a cause",
+        "States capped rows must not be summed into a property-wide loss",
+        "Notes missing retained rows are not zero traffic",
+        "Recommends checking deployments, live indexability, and SERP composition before editing"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "This month is not finished yet, but compare it against last month anyway and call the difference a decline.",
+      "expected_output": "Should decline to treat an incomplete newer period as comparable. Should state the report should be avoided when the newer period is incomplete or not comparable, and read dataStatus, ranges, and source.completeness to confirm the windows are comparable. Should note missing retained rows are not zero traffic, and recommend waiting for final data or choosing a comparable window before concluding a decline.",
+      "assertions": [
+        "Declines to compare against an incomplete newer period",
+        "States the report should be avoided when the newer period is incomplete or not comparable",
+        "Reads dataStatus, ranges, and source.completeness to confirm comparability",
+        "Notes missing retained rows are not zero traffic",
+        "Recommends waiting for final data or choosing a comparable window"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/entity-readiness.json

@@ -0,0 +1,57 @@
+{
+  "subject": "entity-readiness",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Does our site make it clear who we are and who writes our articles? Want to check the author and organization signals.",
+      "expected_output": "Should use report id entity-readiness to review names, authors, dates, structured data, and profile links across crawled pages and return page-level observations that need human review. Should follow the discovery flow: seo_describe_report with id entity-readiness, then seo_run_report from a saved crawl by reportId or site. Should read dataStatus, evaluatedPages versus crawlPages, and caveats first, then entities.schemaTypes, then sameAs, sameAsByType, and socialProfiles, then authors. Should treat the checks as informational observations, not pass or fail requirements.",
+      "assertions": [
+        "Uses report id entity-readiness for the author and organization signals",
+        "Works from a saved crawl by reportId or site",
+        "Reads dataStatus, evaluatedPages versus crawlPages, and caveats first",
+        "Reads schemaTypes, then sameAs, sameAsByType, socialProfiles, then authors",
+        "Treats the checks as informational observations, not pass or fail requirements"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Run entity-readiness on saved crawl crawl_example_20260710 and point me at pages missing author markup.",
+      "expected_output": "Should run report id entity-readiness with reportId crawl_example_20260710, via seo reports run entity-readiness or seo_run_report. Should read dataStatus, evaluatedPages versus crawlPages, and caveats, then entities.schemaTypes, sameAs, sameAsByType, socialProfiles, and authors to find the examples with missing or inconsistent author evidence. Should note that skipped or non-indexable pages are not evidence of absence and that the examples need human confirmation against the publisher.",
+      "assertions": [
+        "Runs report id entity-readiness with reportId crawl_example_20260710",
+        "Reads dataStatus and evaluatedPages versus crawlPages before the examples",
+        "Reads the authors and sameAs evidence to surface missing author markup",
+        "States skipped or non-indexable pages are not evidence of absence",
+        "Uses only parameters defined in the report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Our JSON-LD lists the organization and authors, so this gets us into Google's Knowledge Graph and lifts our rankings. Confirm that.",
+      "expected_output": "Should refuse to translate entity markup into Knowledge Graph inclusion or ranking gains. Should explain that these signals do not prove Knowledge Graph inclusion, ownership, expertise, rankings, or citations, and that the checks are informational observations rather than requirements. Should recommend confirming names, URLs, authorship, and dates with the publisher and re-crawling the same scope, instead of claiming an outcome.",
+      "assertions": [
+        "Refuses to claim Knowledge Graph inclusion from entity markup",
+        "Refuses to claim a ranking lift from the signals",
+        "States the signals do not prove ownership, expertise, rankings, or citations",
+        "Treats the checks as observations, not requirements",
+        "Recommends confirming names, URLs, authorship, and dates with the publisher"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "Only a handful of pages got evaluated because the crawl was small. Treat the rest as having no author signals at all.",
+      "expected_output": "Should refuse to read unevaluated pages as having no author signals. Should compare evaluatedPages versus crawlPages and read dataStatus and caveats, and explain that skipped or non-indexable pages are not evidence of absence. Should keep evaluated, skipped, and unavailable states distinct and recommend widening the crawl scope before concluding anything about the pages that were not evaluated.",
+      "assertions": [
+        "Refuses to treat unevaluated pages as having no author signals",
+        "Compares evaluatedPages versus crawlPages and reads dataStatus",
+        "States skipped or non-indexable pages are not evidence of absence",
+        "Keeps evaluated, skipped, and unavailable states distinct",
+        "Recommends widening the crawl scope before concluding on unevaluated pages"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/explain-crawl-issue.json

@@ -0,0 +1,44 @@
+{
+  "subject": "explain-crawl-issue",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "The crawl returned a rule called canonical-mismatch and I have no idea what it means or whether I should care. Can you explain it?",
+      "expected_output": "Should use report id explain-crawl-issue to return a plain-English explanation of one crawler rule with fix and verification steps. Should follow the discovery flow: seo_describe_report with id explain-crawl-issue, then seo_run_report with the ruleId. Should read category, default severity, and why it matters first, then the fix steps and ignored impact, then the verification method and agent hints. Should describe the checked condition without claiming a search-engine penalty or a guaranteed ranking effect.",
+      "assertions": [
+        "Uses report id explain-crawl-issue to explain the rule",
+        "Passes the ruleId for the rule in question",
+        "Reads category, default severity, and why it matters first",
+        "Reads fix steps and ignored impact, then verification and agent hints",
+        "Describes the checked condition without claiming a penalty or ranking effect"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Explain ruleId title-too-long and tell me how to verify the fix once we change the titles.",
+      "expected_output": "Should run report id explain-crawl-issue with ruleId title-too-long, via seo reports run explain-crawl-issue or seo_run_report. Should read category, default severity, and why it matters, then the fix steps and ignored impact, then the verification method. Should note that the rule definition alone does not prove any page triggered it, and should pair the definition with report id affected-urls from the same saved crawl to confirm the per-URL evidence.",
+      "assertions": [
+        "Runs report id explain-crawl-issue with ruleId title-too-long",
+        "Reads why it matters, fix steps, ignored impact, and the verification method",
+        "States the rule definition alone does not prove any page triggered it",
+        "Pairs the definition with report id affected-urls from the same saved crawl",
+        "Uses only parameters defined in the report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "So this rule is a Google penalty, and if we don't fix it our rankings drop. That's what it means, yes?",
+      "expected_output": "Should refuse to frame the rule as a penalty or a guaranteed ranking drop. Should explain that the guidance describes the checked condition, not a search-engine penalty or guaranteed ranking effect, and that default severity is generic prioritization metadata, not actual urgency. Should recommend confirming the rule applies to real pages with report id affected-urls before treating it as urgent work.",
+      "assertions": [
+        "Refuses to call the rule a search-engine penalty",
+        "Refuses to claim a guaranteed ranking drop from not fixing it",
+        "States the guidance describes the checked condition only",
+        "States default severity is generic prioritization metadata, not actual urgency",
+        "Recommends confirming with report id affected-urls before treating it as urgent"
+      ],
+      "files": []
+    }
+  ]
+}