seo 0.1.0 → 0.2.0

package/evals/generate-llms-txt.json

@@ -0,0 +1,44 @@
+{
+  "subject": "generate-llms-txt",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I want to give AI agents a clean map of our useful public pages. Can you draft an llms.txt from our site?",
+      "expected_output": "Should use report id generate-llms-txt to create an editable llms.txt draft from selected public pages in a current crawl. Should follow the discovery flow: seo_describe_report with id generate-llms-txt, then seo_run_report from a saved crawl by reportId or site. Should read content, includedUrls, estimatedTokens, and sections, then check the generated titles and descriptions against the source pages, then the source crawl date, cap, failures, and caveats. Should present it as a draft for human review, not a finished file.",
+      "assertions": [
+        "Uses report id generate-llms-txt to draft the file from a current crawl",
+        "Reads content, includedUrls, estimatedTokens, and sections",
+        "Checks generated titles and descriptions against the source pages",
+        "Reads the source crawl date, cap, failures, and caveats",
+        "Presents the output as a draft for human review, not a finished file"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Generate an llms.txt from saved crawl crawl_example_20260710, cap it at 40 urls and a 2000 token budget, and exclude anything under /tag/.",
+      "expected_output": "Should run report id generate-llms-txt with reportId crawl_example_20260710, maxUrls 40, tokenBudget 2000, and exclude set to the /tag/ pattern, via seo reports run generate-llms-txt or seo_run_report. Should read content, includedUrls, estimatedTokens, and sections, and note that reaching maxUrls or the token budget is possible truncation, not a complete inventory. Should route to report id llms-txt-audit to validate the links after the file is published.",
+      "assertions": [
+        "Runs report id generate-llms-txt with reportId crawl_example_20260710",
+        "Sets maxUrls 40, tokenBudget 2000, and the /tag/ exclude pattern",
+        "Reads content, includedUrls, estimatedTokens, and sections",
+        "States reaching maxUrls or the token budget is possible truncation, not complete",
+        "Routes to report id llms-txt-audit to validate the published file"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Once we publish this llms.txt, we'll rank better and get cited in AI answers, right? That's the point of it.",
+      "expected_output": "Should refuse to promise ranking, indexing, or citation benefit from publishing llms.txt. Should explain that a valid draft does not prove search or AI benefit, selection, indexing, or citations, and that the crawler cannot determine publisher intent. Should keep the file as a human-reviewed navigation aid and recommend human review, then validating the published file with report id llms-txt-audit, rather than claiming an outcome.",
+      "assertions": [
+        "Refuses to promise ranking, indexing, or citation gains from llms.txt",
+        "States a valid draft does not prove search or AI benefit, selection, or citations",
+        "Notes the crawler cannot determine publisher intent",
+        "Keeps the file as a human-reviewed navigation aid",
+        "Recommends validating the published file with report id llms-txt-audit"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/geo-gaps.json

@@ -0,0 +1,57 @@
+{
+  "subject": "geo-gaps",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Is anything in our setup quietly blocking our pages from Google's AI search stuff? Want the technical restrictions and which pages they hit.",
+      "expected_output": "Should use report id geo-gaps to find crawl, index, and snippet settings that could restrict pages in Google AI search features, and the pages where they appear. Should follow the discovery flow: seo_describe_report with id geo-gaps, then seo_run_report from a saved crawl by reportId or site, with a bounded limit. Should read dataStatus, source.partialReasons, and selection evaluated, matched, returned, and truncated counts first, then per-URL issues separated from searchEligibility, then the access states where null means unknown.",
+      "assertions": [
+        "Uses report id geo-gaps for the technical restrictions and affected pages",
+        "Reads dataStatus, source.partialReasons, and the selection counts first",
+        "Keeps per-URL issues separate from searchEligibility",
+        "Treats a null access state as unknown, not allowed",
+        "Passes a bounded limit rather than unbounded input"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Run geo-gaps on saved crawl crawl_example_20260710, limit 25, and show me the pages with hard access restrictions.",
+      "expected_output": "Should run report id geo-gaps with reportId crawl_example_20260710 and limit 25, via seo reports run geo-gaps or seo_run_report. Should read dataStatus, source.partialReasons, and the evaluated, matched, returned, and truncated counts, then per-URL issues separated from searchEligibility, then access states. Should treat null access states as unknown rather than allowed and note semantic HTML and structured data do not override a hard access restriction. Should offer report id affected-urls to list URLs for a specific rule.",
+      "assertions": [
+        "Runs report id geo-gaps with reportId crawl_example_20260710 and limit 25",
+        "Reads dataStatus, source.partialReasons, and the selection counts before rows",
+        "Keeps per-URL issues separate from searchEligibility",
+        "States semantic HTML and structured data do not override a hard access restriction",
+        "Uses only parameters defined in the report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "The gap list came back empty, so every page is eligible and visible in Google AI search. And those noindex tags it skipped, flag them as defects to remove.",
+      "expected_output": "Should refuse both moves. Should explain that an empty gap list does not prove indexing, visibility, selection, or complete coverage, and that noindex, robots, canonicals, or snippet limits should be confirmed as intent before being treated as defects. Should keep the noindex directives as intentional controls until intent or contradictory evidence makes them defects, and should check dataStatus and source.partialReasons before calling the list clean.",
+      "assertions": [
+        "Refuses to read an empty gap list as proof of visibility or eligibility",
+        "States an empty list does not prove indexing, selection, or complete coverage",
+        "Treats noindex, robots, canonicals, and snippet limits as intentional controls",
+        "Confirms intent before treating a control as a defect",
+        "Checks dataStatus and source.partialReasons before calling the list clean"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "Some URLs show a null access state. Count those as allowed and move on.",
+      "expected_output": "Should refuse to count null access states as allowed. Should explain that a null access state means unknown, not allowed, and keep unknown and allowed states distinct. Should read source.partialReasons and the evaluated versus matched counts to see why the state is unknown, and recommend re-checking the exact URL and directive rather than assuming access.",
+      "assertions": [
+        "Refuses to count null access states as allowed",
+        "States a null access state means unknown, not allowed",
+        "Keeps unknown and allowed states distinct",
+        "Reads source.partialReasons to understand why the state is unknown",
+        "Recommends re-checking the exact URL and directive before assuming access"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/index-coverage-plan.json

@@ -0,0 +1,58 @@
+{
+  "subject": "index-coverage-plan",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Our site is huge. How should we spread URL Inspection checks so we don't blow the quota?",
+      "expected_output": "Should route to report id index-coverage-plan, which chooses which sitemap URLs and Search Console properties should use limited URL Inspection checks. Should follow the discovery flow: seo_list_reports with category monitoring, seo_describe_report with id index-coverage-plan, then seo_run_report with site and sitemaps. Should read the summary sitemapUrls, urlCount, property count, daily capacity, and estimated versus target cycle days first, then the properties allocations and sample URLs, then suggestions and every warning. Should treat the output as a plan, not a result.",
+      "assertions": [
+        "Uses report id index-coverage-plan for the quota sampling plan",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Provides site and sitemaps as required by the schema",
+        "Reads summary urlCount, daily capacity, and estimated versus target cycle days first",
+        "Reads the properties allocations and every warning",
+        "Treats the output as a plan, not a coverage result"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Agent task: build a plan for sc-domain:example.com from the sitemap https://example.com/sitemap.xml with a daily limit of 200 and a target 30 day cycle.",
+      "expected_output": "Should run report id index-coverage-plan with site sc-domain:example.com, sitemaps set to the sitemap URL, dailyLimit 200, and targetCycleDays 30, via seo reports run index-coverage-plan or seo_run_report. Should keep params within the schema bounds, where dailyLimit allows up to 2000 and targetCycleDays up to 365. Should use the plan to set a realistic recurring limit for report id index-monitor next.",
+      "assertions": [
+        "Runs report id index-coverage-plan with dailyLimit 200 and targetCycleDays 30",
+        "Provides site and the sitemap as required",
+        "Keeps dailyLimit and targetCycleDays within the schema bounds",
+        "Uses the plan to set a realistic limit for report id index-monitor",
+        "Uses only parameters defined in the index-coverage-plan schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "So after the 30 day cycle every URL in the plan will be indexed, correct?",
+      "expected_output": "Should refuse. Estimated cycle time is arithmetic over discovered URLs and capacity, not a promise Google will process or index them. This plan does not report an index coverage percentage or an all-clear. Should explain the plan only schedules checks and recommend collecting evidence with report id index-monitor and reviewing changes with report id index-watch.",
+      "assertions": [
+        "Refuses to promise every URL will be indexed after the cycle",
+        "States estimated cycle time is arithmetic over URLs and capacity, not a promise",
+        "States the plan does not report a coverage percentage or an all-clear",
+        "Explains the plan only schedules checks",
+        "Recommends collecting evidence with report id index-monitor"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "One sitemap failed to fetch but just give me the plan as complete coverage.",
+      "expected_output": "Should not present the plan as complete. Sitemap fetch failures or maxUrls truncation make the plan incomplete. Should read every warning and keep the incomplete plan distinct from a complete one. Should recommend fixing the sitemap fetch or noting the truncation before relying on the allocations.",
+      "assertions": [
+        "Refuses to present the plan as complete coverage",
+        "States sitemap fetch failures or maxUrls truncation make the plan incomplete",
+        "Reads every warning in the output",
+        "Keeps the incomplete plan distinct from a complete one",
+        "Recommends resolving the fetch failure before relying on the plan"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/index-coverage.json

@@ -0,0 +1,70 @@
+{
+  "subject": "index-coverage",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I want to know which of our pages aren't getting picked up by Google.",
+      "expected_output": "Should route to report id index-coverage, which compares crawlable pages with pages that had Search Console visibility and builds a representative review queue for URL Inspection. Should note it is a signal and review step, not proof of indexing, and that it needs a saved crawl for the site. Should follow the discovery flow: seo_list_reports with category monitoring, seo_describe_report with id index-coverage, then seo_run_report. Should read sources completeness, rowLimit, rowLimitReached, date range, and invalid rows first, then the groups. Should plan to confirm exact verdicts with URL Inspection via report id index-watch.",
+      "assertions": [
+        "Uses report id index-coverage for the coverage signal review",
+        "States the report is a signal and review step, not proof of indexing",
+        "Notes it requires a saved crawl for the site",
+        "Reads sources completeness, rowLimit, rowLimitReached, and invalid rows first",
+        "Reads retainedSearchVisibility and crawlableWithoutRetainedSearchVisibility",
+        "Plans to confirm exact verdicts with report id index-watch"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Agent task: run index-coverage for sc-domain:example.com against the sitemap https://example.com/sitemap.xml over 90 days, rowLimit 50000, 50 items per section.",
+      "expected_output": "Should run report id index-coverage with site sc-domain:example.com, sitemaps set to the sitemap URL, days 90, rowLimit 50000, and itemsPerSection 50, via seo reports run index-coverage or seo_run_report. Should keep params within the schema bounds, where rowLimit allows up to 250000 and itemsPerSection up to 1000. Should read rowLimitReached to see whether the Search Console source was capped before reading the groups.",
+      "assertions": [
+        "Runs report id index-coverage with days 90 and rowLimit 50000",
+        "Sets itemsPerSection 50 and the sitemap as requested",
+        "Keeps rowLimit and itemsPerSection within the schema bounds",
+        "Reads rowLimitReached to see if the source was capped",
+        "Uses only parameters defined in the index-coverage schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "These 40 URLs have no Search Console rows, so they are not indexed. Mark them unindexed.",
+      "expected_output": "Should refuse. A missing Search Analytics row is not proof a page is unindexed, and a page is not unindexed because no row appeared. The crawlableWithoutRetainedSearchVisibility group is a review signal, not a verdict. Should recommend collecting the exact URL Inspection verdicts with report id index-watch before marking any URL unindexed.",
+      "assertions": [
+        "Refuses to mark the URLs unindexed from missing rows",
+        "States a missing Search Analytics row is not proof a page is unindexed",
+        "Treats crawlableWithoutRetainedSearchVisibility as a review signal, not a verdict",
+        "Recommends collecting exact verdicts with report id index-watch",
+        "Keeps the crawl-versus-Search-Console signal distinct from an index verdict"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "These pages had impressions in the period, so they are definitely indexed and fine.",
+      "expected_output": "Should refuse. A page is not indexed because it had Search Analytics visibility, and retainedSearchVisibility is evidence of past visibility, not a current index verdict. Should keep the visibility signal distinct from proof of indexing and recommend confirming with URL Inspection via report id index-watch for any page that needs a verdict.",
+      "assertions": [
+        "Refuses to conclude the pages are indexed from past visibility",
+        "States a page is not indexed because it had Search Analytics visibility",
+        "Treats retainedSearchVisibility as evidence, not a current index verdict",
+        "Recommends confirming with URL Inspection via report id index-watch"
+      ],
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "Just give me our index coverage as a single percentage of the whole site, even though rowLimitReached came back true.",
+      "expected_output": "Should refuse to produce a whole-site coverage percentage. Do not turn a limited or incomplete source into a whole-site coverage percentage. Should read rowLimit, rowLimitReached, and invalid rows and keep limited and incomplete states distinct from complete ones. Should explain a capped source cannot support a whole-site percentage and recommend the representative review queue instead.",
+      "assertions": [
+        "Refuses to produce a whole-site coverage percentage",
+        "States a limited or incomplete source cannot become a whole-site percentage",
+        "Reads rowLimit, rowLimitReached, and invalid rows",
+        "Keeps limited and incomplete states distinct from complete ones",
+        "Recommends the representative review queue instead of a percentage"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/index-monitor.json

@@ -0,0 +1,58 @@
+{
+  "subject": "index-monitor",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Start tracking whether Google is indexing our key pages so we can spot changes.",
+      "expected_output": "Should route to report id index-monitor, which checks selected sitemap URLs with Google URL Inspection and saves the results locally for later comparison. Should follow the discovery flow: seo_list_reports with category monitoring, seo_describe_report with id index-monitor, then seo_run_report with site and sitemaps. Should read dataStatus and the source sitemap and inventory limits, discovered and invalid URLs, and truncation first, then the inventory states, then properties allocation, then items with inspectionStatus, indexStatus, regressions, recoveries, and errors. Should plan to review changes over time with report id index-watch.",
+      "assertions": [
+        "Uses report id index-monitor to collect and save URL Inspection snapshots",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Provides site and sitemaps as required by the schema",
+        "Reads dataStatus, inventory limits, invalid URLs, and truncation first",
+        "Reads items inspectionStatus and indexStatus with regressions and recoveries",
+        "Plans to review changes with report id index-watch"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Agent task: run index-monitor for sc-domain:example.com from https://example.com/sitemap.xml, inspect at most 50 URLs, daily limit 100.",
+      "expected_output": "Should run report id index-monitor with site sc-domain:example.com, sitemaps set to the sitemap URL, inspectLimit 50, and dailyLimit 100, via seo reports run index-monitor or seo_run_report. Should keep params within the schema bounds, where inspectLimit allows up to 100 and dailyLimit up to 2000. Should note the run saves snapshots for later comparison and that only selected URLs get a new inspection result.",
+      "assertions": [
+        "Runs report id index-monitor with inspectLimit 50 and dailyLimit 100",
+        "Provides site and the sitemap as required",
+        "Keeps inspectLimit and dailyLimit within the schema bounds",
+        "Notes the run saves snapshots for later comparison",
+        "Uses only parameters defined in the index-monitor schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Several checks came back quota-blocked and a few failed. Log those pages as index problems.",
+      "expected_output": "Should refuse. Failed, deferred, or quota-blocked checks are operational outcomes, not SEO defects. Should keep those states distinct from index problems and recommend retrying the failed checks per retryAt rather than recording the pages as defects.",
+      "assertions": [
+        "Refuses to log quota-blocked and failed checks as index problems",
+        "States failed, deferred, or quota-blocked checks are operational outcomes",
+        "Keeps operational outcomes distinct from SEO defects",
+        "Recommends retrying failed checks per retryAt",
+        "Does not treat an operational skip as a page defect"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "The selected batch all came back indexed, so the whole site is indexed and future pages will be too.",
+      "expected_output": "Should refuse. A complete selected batch does not prove inventory-wide indexing or future inclusion, and a due URL that was not selected has no new inspection result. Should keep the bounded selected batch distinct from the full inventory and avoid projecting the result onto unselected or future pages.",
+      "assertions": [
+        "Refuses to conclude the whole site is indexed from the batch",
+        "States a complete selected batch does not prove inventory-wide indexing",
+        "States a due URL that was not selected has no new inspection result",
+        "Refuses to promise future pages will be indexed",
+        "Keeps the bounded selected batch distinct from the full inventory"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/index-watch.json

@@ -0,0 +1,68 @@
+{
+  "subject": "index-watch",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Did the index status of our monitored pages change since last time?",
+      "expected_output": "Should route to report id index-watch, which compares current Google index evidence with saved snapshots to find regressions and recoveries. Should note it needs a URL list and earlier snapshots. Should follow the discovery flow: seo_list_reports with category monitoring, seo_describe_report with id index-watch, then seo_run_report with site and urls. Should read source.possiblyTruncated, dataStatus, warnings, and sitemap inventory states first, then currentIssues, regressions, recoveries, failed, quotaBlocked, and deferred separately, then indexStatus, issueCodes, and typed changes.",
+      "assertions": [
+        "Uses report id index-watch to compare against saved snapshots",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Notes it needs a URL list and earlier snapshots",
+        "Reads source.possiblyTruncated, dataStatus, and warnings first",
+        "Reads currentIssues, regressions, recoveries, failed, quotaBlocked, and deferred separately",
+        "Reads indexStatus and issueCodes for each change"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Agent task: run index-watch for sc-domain:example.com on https://example.com/a, https://example.com/b, and https://example.com/c in English with a daily limit of 100.",
+      "expected_output": "Should run report id index-watch with site sc-domain:example.com, urls set to the three URLs, languageCode en, and dailyLimit 100, via seo reports run index-watch or seo_run_report. Should keep params within the schema bounds, where urls allows up to 100 entries and dailyLimit up to 2000. Should keep failed, quotaBlocked, and deferred distinct from regressions when reading the result.",
+      "assertions": [
+        "Runs report id index-watch with the three URLs and dailyLimit 100",
+        "Sets languageCode as requested",
+        "Keeps urls and dailyLimit within the schema bounds",
+        "Keeps failed, quotaBlocked, and deferred distinct from regressions",
+        "Uses only parameters defined in the index-watch schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "This URL came back NEUTRAL with a different canonical, so it is broken. Flag it as a defect.",
+      "expected_output": "Should refuse. A NEUTRAL verdict or canonical difference may be intentional, not a defect. Should keep it as an observation and recommend auditing the live page, the sitemap, and the exact inspection evidence before treating it as a regression or defect.",
+      "assertions": [
+        "Refuses to flag the NEUTRAL verdict as a defect",
+        "States a NEUTRAL verdict or canonical difference may be intentional",
+        "Keeps the verdict as an observation rather than a defect",
+        "Recommends auditing the live page, sitemap, and exact inspection evidence"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "URL Inspection says indexed, so the page is ranking right now and the whole site is healthy.",
+      "expected_output": "Should refuse. URL Inspection is Google's indexed snapshot for one URL, not a live crawl or current search appearance. Should not infer inventory-wide health from the bounded selected sample. Should keep the single-URL indexed snapshot distinct from live ranking and from whole-site health.",
+      "assertions": [
+        "Refuses to claim the page is ranking right now from an indexed verdict",
+        "States URL Inspection is an indexed snapshot, not a live crawl or search appearance",
+        "Refuses to infer whole-site health from the bounded sample",
+        "Keeps the single-URL snapshot distinct from live ranking"
+      ],
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "Our local quota ledger still shows budget, so ignore the provider 429 and treat those checks as Google-side failures we can retry immediately.",
+      "expected_output": "Should refuse to override the 429. A provider 429 is authoritative over the local quota ledger. Should keep quotaBlocked distinct from a page defect, respect the 429 rather than retrying immediately, and follow the retry timing the provider gives.",
+      "assertions": [
+        "Refuses to ignore the provider 429 based on the local ledger",
+        "States a provider 429 is authoritative over the local quota ledger",
+        "Keeps quotaBlocked distinct from a page defect",
+        "Does not recommend an immediate retry against the 429"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/internal-links.json

@@ -0,0 +1,57 @@
+{
+  "subject": "internal-links",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Find pages on our site that should link to this new article.",
+      "expected_output": "Should use report id internal-links to find relevant pages that could add a useful internal link to a target URL. Should follow the discovery flow: seo_list_reports with category opportunities, seo_describe_report with id internal-links, then seo_run_report with the required site and targetUrl. Should read dataStatus, target verification, aliases, canonical, and technical signals first, then source completeness and selection attempted, checked, failed, unchecked, and exclusions. Should clarify query overlap does not prove a link belongs.",
+      "assertions": [
+        "Uses report id internal-links for the source-page candidates",
+        "Notes the report requires both site and targetUrl",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Reads dataStatus, target verification, aliases, canonical, and technical signals first",
+        "States query overlap does not prove a link belongs"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Run internal links for site sc-domain:example.com and targetUrl https://example.com/new-guide, top 20 candidates, check 100 of them.",
+      "expected_output": "Should run report id internal-links with site sc-domain:example.com, targetUrl https://example.com/new-guide, limit 20, and checkLimit 100. Should read source completeness and selection attempted, checked, failed, unchecked, and exclusions, then per-item exact versus lexical matches and linkEvidence. Should use only parameters defined in the schema.",
+      "assertions": [
+        "Runs report id internal-links with site and targetUrl",
+        "Sets limit 20 and checkLimit 100 as requested",
+        "Reads selection attempted, checked, failed, unchecked, and exclusions",
+        "Reads per-item exact versus lexical matches and linkEvidence",
+        "Uses only parameters defined in the report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Great, add all these internal links automatically. They will boost our rankings.",
+      "expected_output": "Should decline to add links automatically and should not promise a ranking gain. Should state the report should be avoided when links are to be added automatically, that query overlap does not prove a link belongs or that adding one improves rankings, and that priority is a heuristic, not estimated impact. Should recommend reading the source passage, adding one contextual link only if the target is genuinely useful, and re-crawling to confirm it.",
+      "assertions": [
+        "Declines to add the links automatically",
+        "States query overlap does not prove a link belongs or that adding one improves rankings",
+        "States priority is a heuristic, not estimated impact",
+        "Recommends reading the source passage before adding a link",
+        "Recommends re-crawling to confirm any added link"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "We set checkLimit to 20 and only a couple of candidates came back, so there are no internal link opportunities for this page.",
+      "expected_output": "Should refuse to read the small result as proven absence. Should state a low checkLimit can leave plausible candidates unchecked, so absence is not proven, and read selection attempted, checked, failed, and unchecked to see how many were actually inspected. Should recommend raising checkLimit or inspecting the unchecked candidates before concluding there are no opportunities.",
+      "assertions": [
+        "Refuses to read the small result as proven absence",
+        "States a low checkLimit can leave plausible candidates unchecked, so absence is not proven",
+        "Reads selection attempted, checked, failed, and unchecked",
+        "Recommends raising checkLimit or inspecting the unchecked candidates",
+        "Keeps unchecked and checked states distinct"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/link-recovery.json

@@ -0,0 +1,58 @@
+{
+  "subject": "link-recovery",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We did a migration and I'm worried we broke some pages that used to get traffic.",
+      "expected_output": "Should route to report id link-recovery, which finds URLs that previously earned search clicks but now fail, redirect poorly, or block indexing. Should note it needs Search Console page history and is not a backlink report. Should follow the discovery flow: seo_list_reports with category monitoring, seo_describe_report with id link-recovery, then seo_run_report with site. Should read range and summary.checked with severity totals first, then per-item original and final URL, GSC metrics, issue lists, and redirect trace, then chain status, final-page indexability, canonicals, and warnings.",
+      "assertions": [
+        "Uses report id link-recovery for the broken search-value URL review",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Notes it needs Search Console page history and is not a backlink report",
+        "Reads range and summary.checked with severity totals first",
+        "Reads per-item original and final URL, GSC metrics, and redirect trace",
+        "Reads chain status, final-page indexability, and canonicals"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Agent task: run link-recovery for sc-domain:example.com over 180 days, top 30, at least 50 clicks in the window.",
+      "expected_output": "Should run report id link-recovery with site sc-domain:example.com, days 180, limit 30, and minClicks 50, via seo reports run link-recovery or seo_run_report. Should use only parameters defined in the schema. Should note limit constrains coverage, so the queue is a bounded subset rather than every affected URL.",
+      "assertions": [
+        "Runs report id link-recovery with days 180 and limit 30",
+        "Sets minClicks 50 as requested",
+        "Uses only parameters defined in the link-recovery schema",
+        "Notes limit constrains coverage rather than covering every URL",
+        "Reads severity totals before the per-item detail"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Total the clicksAtRisk across the queue. That is the traffic we will get back once we redirect all of these.",
+      "expected_output": "Should refuse. clicksAtRisk and impressionsAtRisk describe the checked period, not a forecast of loss or recovery. Prior visibility orders the queue but does not prove fixing a URL restores traffic. Should recommend confirming the page should still exist and adding one direct 301 to the closest equivalent destination before re-tracing, rather than totalling clicksAtRisk into a recovery figure.",
+      "assertions": [
+        "Refuses to total clicksAtRisk into a recovery figure",
+        "States clicksAtRisk and impressionsAtRisk describe the checked period, not a forecast",
+        "States prior visibility does not prove fixing a URL restores traffic",
+        "Recommends confirming the page should exist before adding a 301",
+        "Recommends re-tracing after the redirect to confirm"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "The tool could not check some of the URLs, so count those as fine, and while you are at it show me who links to them.",
+      "expected_output": "Should not count the unchecked URLs as fine and should decline the backlink request. Failed checks or selection limits constrain coverage, so they are not an all-clear. link-recovery is not a backlink report. Should recommend re-running or tracing a single chain with report id redirect-trace rather than treating a failed check as clean.",
+      "assertions": [
+        "Refuses to count failed or unchecked URLs as fine",
+        "States failed checks or selection limits constrain coverage",
+        "States link-recovery is not a backlink report",
+        "Points to report id redirect-trace to trace a single chain",
+        "Keeps a failed check distinct from an all-clear"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/llms-txt-audit.json

@@ -0,0 +1,44 @@
+{
+  "subject": "llms-txt-audit",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We published an llms.txt a while back. Can you check it's actually valid and the links still work?",
+      "expected_output": "Should use report id llms-txt-audit to check whether llms.txt exists, whether its links work, and how well it reflects useful public pages. Should follow the discovery flow: seo_describe_report with id llms-txt-audit, then seo_run_report by url or site. Should read exists, the resolved file URL, response status, headline, and issues first, then recommendedPages, then the source crawl date, cap, partial state, failed requests, and caveats. Should return file, link, and page coverage findings without visibility claims.",
+      "assertions": [
+        "Uses report id llms-txt-audit to verify the published file",
+        "Reads exists, resolved file URL, response status, headline, and issues first",
+        "Reads recommendedPages and then the source crawl caveats",
+        "Returns file, link, and coverage findings without visibility claims",
+        "Reads the source crawl cap and partial state before concluding"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Audit the llms.txt for https://example.com and tell me which recommended pages are missing from it.",
+      "expected_output": "Should run report id llms-txt-audit with url https://example.com, or site, via seo reports run llms-txt-audit or seo_run_report. Should read exists, resolved file URL, response status, headline, and issues, then recommendedPages to see the useful pages not covered, then the source crawl date, cap, partial state, and failed requests. Should note that a short recommendation list from a capped crawl is not sitewide evidence, and route to report id generate-llms-txt to draft a fresh file.",
+      "assertions": [
+        "Runs report id llms-txt-audit with url https://example.com or site",
+        "Reads exists, response status, and issues before recommendedPages",
+        "Uses recommendedPages to identify useful pages missing from the file",
+        "States a short recommendation list from a capped crawl is not sitewide evidence",
+        "Routes to report id generate-llms-txt to draft a fresh file"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "The audit says we have no llms.txt. Flag that as a technical SEO defect that's hurting our Google rankings, and note that adding one will boost traffic.",
+      "expected_output": "Should refuse both claims. Should explain that llms.txt presence is not a ranking signal and its absence is not a technical defect, and that adding the file does not improve indexing, rankings, traffic, AI selection, or citations. Should keep the missing file as an observation rather than a defect, and, if the user wants one, route to report id generate-llms-txt to draft it for human review.",
+      "assertions": [
+        "Refuses to flag a missing llms.txt as a technical SEO defect",
+        "States llms.txt presence is not a ranking signal and absence is not a defect",
+        "States adding the file does not improve indexing, rankings, traffic, or citations",
+        "Keeps the missing file as an observation, not a defect",
+        "Routes to report id generate-llms-txt if the user wants to draft one"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/measure-change.json

@@ -0,0 +1,58 @@
+{
+  "subject": "measure-change",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We changed our blog title tags on May 1. Did it do anything?",
+      "expected_output": "Should route to report id measure-change, which compares equal Search Console periods before and after a known change. Should follow the discovery flow: seo_list_reports with category experiments, seo_describe_report with id measure-change, then seo_run_report with changedAt and a scope and target. Should read dataStatus, window, source, warnings, and caveats first, then window.effectiveDays versus requestedDays and afterWindowTruncated, then GSC before and after metrics. Should require equal comparable finalized windows before reading a directional verdict.",
+      "assertions": [
+        "Uses report id measure-change for the before-and-after comparison",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Sets changedAt with a scope and target for the change",
+        "Reads dataStatus, window, source, warnings, and caveats first",
+        "Reads window.effectiveDays versus requestedDays and afterWindowTruncated",
+        "Requires equal comparable finalized windows before a directional verdict"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Agent task: run measure-change for sc-domain:example.com, page scope, target https://example.com/blog, changed 2026-05-01, 28 days before and after, with the homepage as a control page.",
+      "expected_output": "Should run report id measure-change with site sc-domain:example.com, scope page, target https://example.com/blog, changedAt 2026-05-01, beforeDays 28, afterDays 28, controlScope page, and controlTarget set to the homepage, via seo reports run measure-change or seo_run_report. Should keep beforeDays and afterDays within the schema bounds up to 548 and read the control adjusted deltas alongside the raw before and after metrics.",
+      "assertions": [
+        "Runs report id measure-change with scope page and changedAt 2026-05-01",
+        "Sets beforeDays 28 and afterDays 28 as requested",
+        "Sets controlScope page and controlTarget for the control",
+        "Keeps beforeDays and afterDays within the schema bounds",
+        "Uses only parameters defined in the measure-change schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "The after window is up 12 percent, so the change caused it. Multiply by 12 for the annual gain.",
+      "expected_output": "Should refuse both. Timing does not prove the recorded change caused the movement, and the delta must not be annualized or forecast. Should check afterWindowTruncated and window.effectiveDays before trusting the direction, and recommend report id segment-impact to see where the movement sits rather than attributing it to the change or projecting an annual figure.",
+      "assertions": [
+        "Refuses to state the change caused the movement from timing",
+        "Refuses to annualize or forecast the delta",
+        "Checks afterWindowTruncated and window.effectiveDays before trusting the direction",
+        "Recommends report id segment-impact to see where movement sits",
+        "Does not present an annual gain figure"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "It says not-enough-data and clickPct is null. Call that a flat result and an infinite gain.",
+      "expected_output": "Should refuse both readings. not-enough-data is never positive, negative, or flat, and clickPct null means the before value was zero, not an infinite gain. Should recommend using equal whole-day before and after windows with at least 7 finalized days each before reading any directional verdict.",
+      "assertions": [
+        "Refuses to read not-enough-data as a flat result",
+        "States not-enough-data is never positive, negative, or flat",
+        "States clickPct null means the before value was zero, not an infinite gain",
+        "Recommends equal whole-day windows with at least 7 finalized days each",
+        "Does not present an infinite or flat verdict"
+      ],
+      "files": []
+    }
+  ]
+}