seo 0.1.0 → 0.2.1

package/evals/monthly-action-plan.json

@@ -0,0 +1,56 @@
+{
+  "subject": "monthly-action-plan",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Give me this month's SEO action plan.",
+      "expected_output": "Should use report id monthly-action-plan to review a calendar month of search performance and turn the evidence into next actions. Should follow the discovery flow: seo_list_reports with category workflows, seo_describe_report with id monthly-action-plan, then seo_run_report with the required site. Should read the workflow summary, steps, actions, and nested output, then the requested month and final-data window, then provider status and skipped sections. Should clarify actions are a review queue, not automatic edit instructions.",
+      "assertions": [
+        "Uses report id monthly-action-plan for the monthly review and action queue",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Reads the workflow summary, steps, actions, and nested output first",
+        "Reads the requested month, final-data window, provider status, and skipped sections",
+        "States actions are a review queue, not automatic edit instructions"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Run the monthly action plan for sc-domain:example.com for 2026-06, top 20 items.",
+      "expected_output": "Should run report id monthly-action-plan with site sc-domain:example.com, month 2026-06, and limit 20. Should read the requested month and final-data window and confirm the month has final Search Console data, then provider status and skipped sections before conclusions, then warnings, caveats, and retained caps. Should treat a skipped section as not a zero, and use only parameters defined in the schema.",
+      "assertions": [
+        "Runs report id monthly-action-plan with month 2026-06 and limit 20",
+        "Reads the requested month and final-data window",
+        "Reads provider status and skipped sections before conclusions",
+        "Treats a skipped section as not a zero",
+        "Uses only parameters defined in the report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Have the plan forecast next month's traffic, blame the June core update for the drop, and treat the skipped GA4 section as zero AI traffic.",
+      "expected_output": "Should refuse every move. Should state the report should not invent click, traffic, ranking, or revenue forecasts, or attribute movement to an update from timing alone. Should state a skipped section is not a zero and a successful workflow does not make every nested source complete. Should recommend tracing each narrative claim back to its structured diagnosis or measurement and confirming affected URLs.",
+      "assertions": [
+        "Refuses to forecast next month's traffic",
+        "Refuses to attribute the drop to the update from timing alone",
+        "States a skipped section is not a zero",
+        "States a successful workflow does not make every nested source complete",
+        "Recommends tracing each narrative claim back to its structured diagnosis or measurement"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "Actually I just want a clean client summary, not an action queue.",
+      "expected_output": "Should note that monthly-action-plan should be avoided when you only need a client-ready summary without an action queue, and route to report id monthly-report to produce the human brief. Should keep the recommendation grounded in the report's stated avoidWhen and related reports rather than forcing the action plan.",
+      "assertions": [
+        "Notes monthly-action-plan is for a review with an action queue",
+        "States it should be avoided when only a client-ready summary is needed",
+        "Routes to report id monthly-report for the human brief",
+        "Grounds the routing in the report's avoidWhen and related reports"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/monthly-report.json

@@ -0,0 +1,58 @@
+{
+  "subject": "monthly-report",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Can you put together last month's SEO summary for the client?",
+      "expected_output": "Should route to report id monthly-report as a readable calendar-month summary. Should follow the discovery flow: seo_list_reports with category reporting, seo_describe_report with id monthly-report, then seo_run_report with a month that has final Search Console data. Should note the report covers a calendar month, not a rolling window. Should read the month and its underlying date windows first, then dataStatus and source completeness, then skipped sections, warnings, and caveats, before the narrative and its referenced diagnosis, changes, and priorities.",
+      "assertions": [
+        "Uses report id monthly-report for the calendar-month summary",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Notes the report is a calendar month, not a rolling window",
+        "Reads the month and its date windows before the narrative",
+        "Checks dataStatus, source completeness, and skipped sections first",
+        "Confirms the month has final Search Console data before presenting it"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Agent task: run the monthly report for sc-domain:example.com for 2026-05, top 15 items, brand excluded, and verify the top 5 pages against their live content.",
+      "expected_output": "Should run report id monthly-report with site sc-domain:example.com, month 2026-05, limit 15, includeBrand false, verifyContent true, and verifyLimit 5, via seo reports run monthly-report or seo_run_report. Should use only parameters defined in the schema and keep month in the YYYY-MM form. Should note verifyLimit is a bounded subset, not full-site validation, and read dataStatus and skipped sections before the narrative.",
+      "assertions": [
+        "Runs report id monthly-report with month 2026-05 and limit 15",
+        "Sets includeBrand false, verifyContent true, and verifyLimit 5 as requested",
+        "Uses only parameters defined in the monthly-report schema",
+        "States verifyLimit is a bounded subset, not full-site validation",
+        "Reads dataStatus and skipped sections before the narrative"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Traffic dropped last month. Tell the client exactly why it happened and forecast next month's clicks.",
+      "expected_output": "Should refuse both requests. The report cannot establish why traffic changed and cannot forecast clicks, rankings, or revenue. Should follow a narrative reference into the structured evidence and validate the affected URLs before drawing any conclusion. Should point to a focused diagnosis such as report id segment-impact or report id update-correlation to investigate the movement rather than asserting a cause or inventing a forecast.",
+      "assertions": [
+        "Refuses to state why traffic changed from this report alone",
+        "Refuses to forecast next month's clicks, rankings, or revenue",
+        "Follows a narrative reference into the structured evidence to check it",
+        "Points to a focused diagnosis such as report id segment-impact",
+        "Does not invent a forecast figure"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "One section shows zero, so we had nothing there last month. Put that in the report as a clean zero.",
+      "expected_output": "Should not record the section as a clean zero without checking its state. A zero from a complete source differs from an unavailable, partial, filtered, or capped section. Should read dataStatus, source completeness, and skipped sections and keep these states distinct. Should only report a true zero when the source for that section is complete, and otherwise name the section as unavailable, partial, or capped.",
+      "assertions": [
+        "Refuses to record the section as a clean zero without checking its state",
+        "Distinguishes a zero from a complete source from an unavailable or partial section",
+        "Reads dataStatus, source completeness, and skipped sections",
+        "Keeps unavailable, partial, filtered, and capped states distinct",
+        "Only reports a true zero when that section's source is complete"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/narrative-report.json

@@ -0,0 +1,58 @@
+{
+  "subject": "narrative-report",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Write up where our SEO stands right now for a stakeholder update.",
+      "expected_output": "Should route to report id narrative-report to assemble one evidence-linked briefing. Should follow the discovery flow: seo_list_reports with category reporting, seo_describe_report with id narrative-report, then seo_run_report with only schema-valid params. Should read the top-level caveats and headline first, then sections and priorities, then diagnosis, changeMeasurements, and changeMeasurementAttempts, then monitoring. Should keep the caveats visible rather than smoothing them out.",
+      "assertions": [
+        "Uses report id narrative-report for the stakeholder briefing",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Reads top-level caveats and headline before the sections",
+        "Reads diagnosis, changeMeasurements, and changeMeasurementAttempts",
+        "Keeps caveats visible rather than hiding them",
+        "Passes only parameters defined in the narrative-report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Agent task: run the narrative report for sc-domain:example.com over 90 days with a 28 day recent window, cap changes at 10, verify 5 pages, and return the structured evidence.",
+      "expected_output": "Should run report id narrative-report with site sc-domain:example.com, days 90, recentDays 28, changeLimit 10, verifyContent true, and verifyLimit 5, via seo reports run narrative-report or seo_run_report. Should use only parameters defined in the schema. Should preserve the caveats, the diagnosis, and the changeMeasurementAttempts in the structured output rather than dropping failed measurements.",
+      "assertions": [
+        "Runs report id narrative-report with days 90 and recentDays 28",
+        "Sets changeLimit 10, verifyContent true, and verifyLimit 5 as requested",
+        "Uses only parameters defined in the narrative-report schema",
+        "Preserves caveats and changeMeasurementAttempts in the output",
+        "Reads diagnosis and monitoring as part of the evidence"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Summarize this so it says the March update caused our gains. Make it persuasive for the client.",
+      "expected_output": "Should refuse the causal framing. Update timing, template groupings, and opportunity scores are investigation context, not ranking causes, and the narrative summarizes evidence and does not strengthen it or prove causation. Should keep the caveats intact and describe the update overlap as context to investigate rather than a confirmed cause of the gains.",
+      "assertions": [
+        "Refuses to state the March update caused the gains",
+        "Labels update timing and template groupings as investigation context, not causes",
+        "States the narrative summarizes evidence and does not prove causation",
+        "Keeps the caveats intact rather than removing them for persuasion",
+        "Frames the update overlap as context to investigate"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "One of the change measurements failed to run, so just leave it out and mark that change as no impact.",
+      "expected_output": "Should not drop the failed measurement or call it no impact. A failed or skipped measurement stays visible and is not a zero. Should keep it in changeMeasurementAttempts and recommend reproducing the technical failure or inspecting the affected URLs before treating it as a defect or a no-impact result.",
+      "assertions": [
+        "Refuses to drop the failed measurement from the report",
+        "States a failed or skipped measurement stays visible and is not a zero",
+        "Keeps the failure in changeMeasurementAttempts",
+        "Refuses to record the change as no impact",
+        "Recommends reproducing the failure or inspecting the URLs first"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/okf-build.json

@@ -0,0 +1,44 @@
+{
+  "subject": "okf-build",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I want a compact, cited knowledge pack about our site that an agent can load and trust. Can you build one from our pages?",
+      "expected_output": "Should use report id okf-build to create an OKF manifest and optional markdown files with source links from public pages in a crawl. Should follow the discovery flow: seo_describe_report with id okf-build, then seo_run_report from a saved crawl by reportId or site. Should read the manifest schema version, report id, source URL, generation time, crawl status, title, concept count, and caveats first, then selection page counts and deterministic ordering, then the returned validation before using files. Should treat the pack as bounded, cited evidence, not invented facts.",
+      "assertions": [
+        "Uses report id okf-build to create the cited knowledge pack",
+        "Works from a saved crawl by reportId or site",
+        "Reads manifest schema version, crawl status, concept count, and caveats first",
+        "Reads selection page counts and deterministic ordering, then the validation",
+        "Treats the pack as bounded, cited evidence rather than invented facts"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Build an OKF pack from saved crawl crawl_example_20260710 with maxConcepts 30 and includeFiles true, then check it validates.",
+      "expected_output": "Should run report id okf-build with reportId crawl_example_20260710, maxConcepts 30, and includeFiles true, via seo reports run okf-build or seo_run_report. Should read the manifest schema version, crawl status, title, concept count, and caveats, then selection page counts and deterministic ordering, then the returned validation before using the files. Should note that if selected pages equal the limit the bundle is bounded, not exhaustive, and route to report id okf-validate to check the files separately.",
+      "assertions": [
+        "Runs report id okf-build with reportId crawl_example_20260710",
+        "Sets maxConcepts 30 and includeFiles true as requested",
+        "Reads manifest, selection page counts, and the returned validation in order",
+        "States a bundle at the page limit is bounded, not exhaustive",
+        "Routes to report id okf-validate to check the files separately"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "The pack built and validated fine, so everything in it is accurate, current, and confirms we own these pages. Ship it to the agents.",
+      "expected_output": "Should refuse to read structural success as fact. Should explain that a successful structural validation does not establish ownership, freshness, factual accuracy, or completeness, and that the builder does not make extracted claims true or current. Should recommend inspecting citations, canonical URLs, and summaries against the source pages, especially for time-dependent claims, before distributing the pack.",
+      "assertions": [
+        "Refuses to treat structural validation as proof the content is accurate",
+        "States validation does not establish ownership, freshness, accuracy, or completeness",
+        "States the builder does not make extracted claims true or current",
+        "Recommends inspecting citations and canonical URLs against source pages",
+        "Flags time-dependent claims for extra verification before distribution"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/okf-validate.json

@@ -0,0 +1,44 @@
+{
+  "subject": "okf-validate",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I edited our knowledge pack markdown by hand. Can you check I didn't break the structure or any references before we use it?",
+      "expected_output": "Should use report id okf-validate to check supplied OKF markdown files for structure, references, and broken links before use. Should follow the discovery flow: seo_describe_report with id okf-validate, then seo_run_report with the required files array of path and content objects. Should read validation.valid and the file and concept counts first, then each issue level, path, and message, then explanation.nextActions as ordering guidance. Should present it as a file-contract check, not a fact check.",
+      "assertions": [
+        "Uses report id okf-validate to check the edited files",
+        "Passes the required files array of path and content objects",
+        "Reads validation.valid and the file and concept counts first",
+        "Reads each issue level, path, and message, then explanation.nextActions",
+        "Presents the result as a file-contract check, not a fact check"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Validate these two OKF files and tell me what to fix first if anything is wrong.",
+      "expected_output": "Should run report id okf-validate with the files array containing both path and content entries, via seo reports run okf-validate or seo_run_report. Should read validation.valid and the counts, then each issue level, path, and message, then use explanation.nextActions as the ordering guidance for what to fix first. Should note that warnings still require review even when validation.valid is true, and that a valid result must not be reported as fact checked.",
+      "assertions": [
+        "Runs report id okf-validate with both files in the files array",
+        "Reads validation.valid, then each issue level, path, and message",
+        "Uses explanation.nextActions to order the fixes",
+        "States warnings still require review even when validation.valid is true",
+        "Uses only parameters defined in the report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "It came back valid true, so the pack is fact checked and the cited sources are all confirmed. We can trust it as-is.",
+      "expected_output": "Should refuse to equate valid true with fact checked. Should explain that validation checks the file contract only and does not browse cited sources or determine whether the knowledge is true, current, owned, or complete, and that valid true must never be reported as fact checked. Should recommend separately verifying the cited URLs, claims, dates, and the recorded crawl snapshot after the structural check passes.",
+      "assertions": [
+        "Refuses to report valid true as fact checked",
+        "States validation checks the file contract only",
+        "States it does not confirm the knowledge is true, current, owned, or complete",
+        "Notes the validator does not browse the cited sources",
+        "Recommends separately verifying cited URLs, claims, dates, and the crawl snapshot"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/page-opportunities.json

@@ -0,0 +1,57 @@
+{
+  "subject": "page-opportunities",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "What should I fix on this one page to get more search traffic?",
+      "expected_output": "Should use report id page-opportunities to find Search Console queries and page evidence pointing to useful improvements for one URL. Should follow the discovery flow: seo_list_reports with category ai-search, seo_describe_report with id page-opportunities, then seo_run_report with the required site and url. Should read dataStatus, range, source.targetRowsFetched, selection, and benchmark first, then benchmark.possiblyTruncated and verification.status and reason. Should clarify summary.opportunities is a review queue, not a defect count.",
+      "assertions": [
+        "Uses report id page-opportunities for the single-URL improvement list",
+        "Notes the report requires both site and url",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Reads dataStatus, range, source.targetRowsFetched, selection, and benchmark first",
+        "States summary.opportunities is a review queue, not a defect count"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Run page opportunities for site sc-domain:example.com and url https://example.com/pricing over 120 days, verify content, top 20.",
+      "expected_output": "Should run report id page-opportunities with site sc-domain:example.com, url https://example.com/pricing, days 120, verifyContent true, and limit 20. Should read benchmark.possiblyTruncated and verification.status and reason before treating results as complete or verified, then per-item query metrics, opportunity type, and benchmark and verification evidence. Should use only parameters defined in the schema.",
+      "assertions": [
+        "Runs report id page-opportunities with site and url and days 120",
+        "Sets verifyContent true and limit 20 as requested",
+        "Reads benchmark.possiblyTruncated and verification.status and reason",
+        "Reads per-item query metrics, opportunity type, and benchmark and verification evidence",
+        "Uses only parameters defined in the report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Total the estimatedCtrClickShortfall for these opportunities as the extra clicks we will get, and if there are only a few rows the page is basically fine.",
+      "expected_output": "Should refuse to total the shortfall as promised clicks and should not read a short queue as an all-clear. Should state estimatedCtrClickShortfall is a directional calculation, not a click forecast, and that summary.opportunities is a review queue, not a defect count, so partial data is not an all-clear. Should check benchmark.possiblyTruncated and selection before concluding, and recommend inspecting the live SERP before editing.",
+      "assertions": [
+        "Refuses to total estimatedCtrClickShortfall into promised clicks",
+        "States estimatedCtrClickShortfall is a directional calculation, not a click forecast",
+        "States summary.opportunities is a review queue and partial data is not an all-clear",
+        "Checks benchmark.possiblyTruncated and selection before concluding",
+        "Recommends inspecting the live SERP before editing"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "Content verification failed on this URL, but it lists a missing-topic opportunity, so the page clearly does not cover that topic.",
+      "expected_output": "Should not turn a failed verification into a live-page coverage conclusion. Should read verification.status and reason and state that only verified results support live-page coverage observations, so a failed or unverified item still has query evidence but no confirmed coverage gap. Should keep verified and unverified states distinct and recommend inspecting the live SERP and resolving any status or indexability contradiction before editing.",
+      "assertions": [
+        "Refuses to read the failed verification as a confirmed coverage gap",
+        "Reads verification.status and reason",
+        "States only verified results support live-page coverage observations",
+        "Keeps verified and unverified states distinct",
+        "Recommends inspecting the live SERP and resolving contradictions before editing"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/performance-audit.json

@@ -0,0 +1,57 @@
+{
+  "subject": "performance-audit",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Is this page fast enough? Run a performance check on it.",
+      "expected_output": "Should use report id performance-audit to run Lighthouse lab checks and add CrUX field Core Web Vitals when that data is available. Should follow the discovery flow: seo_list_reports with category ai-search, seo_describe_report with id performance-audit, then seo_run_report with the required url. Should read dataStatus, source, labDataStatus, and fieldDataStatus first, then keep lab findings separate from real-user field data.",
+      "assertions": [
+        "Uses report id performance-audit for the page performance check",
+        "Notes it runs Lighthouse lab checks and adds CrUX field data when available",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Reads dataStatus, source, labDataStatus, and fieldDataStatus first",
+        "Keeps lab findings separate from real-user field data"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Run the performance audit for https://example.com/product on mobile.",
+      "expected_output": "Should run report id performance-audit with url https://example.com/product and strategy mobile. Should read the Lighthouse score, lab metrics, and labInsights, then CrUX fieldData.metrics with scope, formFactor, and collectionPeriod, keeping the lab and field values clearly labelled and separate. Should use only parameters defined in the schema.",
+      "assertions": [
+        "Runs report id performance-audit with url and strategy mobile",
+        "Reads the Lighthouse score, lab metrics, and labInsights",
+        "Reads CrUX fieldData.metrics with scope, formFactor, and collectionPeriod",
+        "Keeps lab and field values clearly labelled and separate",
+        "Uses only parameters defined in the report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Average the Lighthouse score and the CrUX field numbers into one score, and tell me this mobile result beats our desktop page and will rank us higher.",
+      "expected_output": "Should refuse every move. Should state lab and field values must not be combined into a new score, that origin-level CrUX data is not page-level evidence, that mobile and desktop must not be compared as equal populations, and that no ranking outcome can be claimed. Should keep the Lighthouse lab score and CrUX field metrics distinct with their scope and formFactor, and recommend reproducing the relevant lab issue and re-running the audit after the change.",
+      "assertions": [
+        "Refuses to combine lab and field values into a new score",
+        "States origin-level CrUX data is not page-level evidence",
+        "Refuses to compare mobile and desktop as equal populations",
+        "Refuses to claim a ranking outcome",
+        "Recommends reproducing the lab issue and re-running the audit"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "The source came back as fetch-fallback. Use that duration as our LCP and TTFB and give it a performance score.",
+      "expected_output": "Should refuse to treat the fetch-fallback duration as a Core Web Vital or score it. Should state a fetch-fallback duration is the local fetch workflow, not TTFB, LCP, CLS, TBT, or INP, and never earns a score. Should read the fetch-fallback fields as such when source is fetch-fallback, keep them distinct from lab and field metrics, and recommend re-running once the page can be measured properly.",
+      "assertions": [
+        "Refuses to treat the fetch-fallback duration as a Core Web Vital",
+        "States a fetch-fallback duration is the local fetch workflow, not TTFB, LCP, CLS, TBT, or INP",
+        "States a fetch-fallback duration never earns a score",
+        "Reads the fetch-fallback fields as such when source is fetch-fallback",
+        "Keeps fetch-fallback values distinct from lab and field metrics"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/pseo-audit.json

@@ -0,0 +1,84 @@
+{
+  "subject": "pseo-audit",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We generate thousands of pages from templates, like one per city and one per integration. Can you audit whether they're working?",
+      "expected_output": "Should use report id pseo-audit to group repeated URL templates and compare their retained Search Console visibility. Should start compact with a summary pass, describing the schema first when parameters are unknown, for example seo reports run pseo-audit --params with detail summary. Should read dataStatus, source, selection, warnings, and caveats, then use population to separate discovered, GSC-visible, sampled, and untested URLs. Should not label repeated paths as spam or thin by default.",
+      "assertions": [
+        "Uses report id pseo-audit to compare template families",
+        "Starts with a compact summary pass before deep sampling",
+        "Describes the schema before running when parameters are unknown",
+        "Reads dataStatus, source, selection, warnings, and caveats first",
+        "Uses population to separate discovered, GSC-visible, sampled, and untested URLs",
+        "Does not label repeated templates as spam or thin by default"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Run the pSEO audit for sc-domain:example.com. Start summary-only, then rerun the important templates with 3 crawl and 3 index samples each.",
+      "expected_output": "Should run report id pseo-audit first with detail summary, then rerun with crawlSamples 3, inspectSamples 3, and detail full for the important templates, via seo reports run pseo-audit --params. Should note URL Inspection uses property quota and should only be requested when index evidence changes the decision, with 3 samples a sensible start and 10 per template the maximum. Should read the template verdict, then confirm it against crawl, inspection, and evidence.",
+      "assertions": [
+        "Runs report id pseo-audit with detail summary first",
+        "Reruns important templates with crawlSamples 3 and inspectSamples 3 and detail full",
+        "Notes URL Inspection uses property quota and is requested only when it changes the decision",
+        "Confirms the template verdict against crawl, inspection, and evidence",
+        "Uses only parameters defined in the report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "The URL Inspection coverageState for a sample says 'Crawled - currently not indexed'. That still counts as indexed for our template health, right?",
+      "expected_output": "Should refuse to read coverageState as an indexed signal. Should explain that coverageState is diagnostic text and must never be parsed to decide whether a URL is indexed, and that PASS is the only indexed URL Inspection verdict, with NEUTRAL meaning excluded, FAIL meaning invalid, and every other value unknown. Should note URL Inspection describes Google's indexed snapshot for one URL and does not prove every URL in the template is healthy. Should mark the template as index-risk if sampled URLs returned excluded or invalid verdicts, stating the sample count.",
+      "assertions": [
+        "Refuses to treat coverageState text as an indexed signal",
+        "States coverageState must never be parsed to decide indexing",
+        "States PASS is the only indexed verdict and NEUTRAL and FAIL mean excluded and invalid",
+        "Notes URL Inspection covers one URL and does not prove template-wide health",
+        "Flags index-risk with the sample count when samples are excluded or invalid"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "Some template URLs from our sitemap have zero rows in the report. That proves nobody searches for those pages, so let's delete them. Also mark the short ones as thin.",
+      "expected_output": "Should reject both conclusions. Should explain a sitemap URL with no GSC row does not prove zero demand, since performance may be omitted or credited to a canonical URL, so a missing row is not a definitive zero. Should explain word count is descriptive and a page should not be called thin because it is short, and literal query-term coverage and path entity fit are review heuristics, not ranking factors or spam verdicts. Should recommend human review before deletion.",
+      "assertions": [
+        "Refuses to treat a sitemap URL with no GSC row as proven zero demand",
+        "Notes performance may be omitted or credited to a canonical URL",
+        "Refuses to call short pages thin from word count alone",
+        "States literal term coverage and path entity fit are review heuristics, not ranking factors",
+        "Recommends human review before deleting the pages"
+      ],
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "One of our template groups only has two matching URLs. Just give me the same healthy-or-not verdict for it.",
+      "expected_output": "Should note the minimumTemplateUrls default is 3, so two URLs may not form a comparable template group, and should explain that too few pages cannot be compared as a template. Should explain that a healthy verdict requires at least two conclusive indexed samples and two usable crawl samples and remains a sample finding, while inconclusive means search evidence exists but technical sampling is too weak. Should not force a health verdict on a group that lacks the evidence.",
+      "assertions": [
+        "Notes minimumTemplateUrls default is 3 and two URLs may not form a group",
+        "Explains too few pages cannot be compared as a template",
+        "States healthy requires at least two indexed and two usable crawl samples and stays a sample finding",
+        "Explains inconclusive when technical sampling is too weak",
+        "Does not force a health verdict without sufficient evidence"
+      ],
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "The clicks and impressions in the report are our official template totals for the board deck, correct?",
+      "expected_output": "Should clarify that clicks, impressions, CTR, and position come from retained page-dimension Search Analytics rows and are not guaranteed property totals. Should note query patterns and examples come from retained query and page rows, so anonymized and lower-ranked rows may be absent. Should keep retained subsets distinct from complete totals and recommend labeling the figures as a retained subset rather than official totals.",
+      "assertions": [
+        "States the metrics come from retained page-dimension rows, not guaranteed totals",
+        "Notes query patterns come from retained rows and may omit anonymized rows",
+        "Keeps retained subsets distinct from complete property totals",
+        "Refuses to present the figures as official template totals",
+        "Recommends labeling the numbers as a retained subset"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/query-clusters.json

@@ -0,0 +1,57 @@
+{
+  "subject": "query-clusters",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Group our search queries into topics so I can see the themes.",
+      "expected_output": "Should use report id query-clusters to group related Search Console queries so repeated demand themes are easier to review. Should follow the discovery flow: seo_list_reports with category opportunities, seo_describe_report with id query-clusters, then seo_run_report with the required site. Should read the summary cluster and query counts, clicks, impressions, threshold, limit, and brand filtering first, then per-cluster member queries, pages, demand, and performance. Should clarify token overlap does not prove shared intent.",
+      "assertions": [
+        "Uses report id query-clusters for the query grouping",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Reads the summary counts, threshold, limit, and brand filtering first",
+        "Reads per-cluster member queries, pages, demand, and performance",
+        "States token overlap does not prove shared intent"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Run query clusters for sc-domain:example.com, at least 100 impressions, top 40 clusters, scope /blog/.",
+      "expected_output": "Should run report id query-clusters with site sc-domain:example.com, minImpressions 100, limit 40, and scope /blog/. Should read per-cluster member queries, pages, and demand, then each cluster recommendation. Should note the threshold and cap in the summary bound the conclusion, and use only parameters defined in the schema.",
+      "assertions": [
+        "Runs report id query-clusters with minImpressions 100 and limit 40",
+        "Sets scope to /blog/ as requested",
+        "Reads per-cluster member queries, pages, and demand",
+        "Reads each cluster recommendation",
+        "Uses only parameters defined in the report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Each cluster should become a new page, and this proves those existing URLs are competing for the same thing.",
+      "expected_output": "Should decline both conclusions. Should state token overlap does not prove shared intent, justify a new page, or establish that current URLs compete. Should recommend checking whether a cluster maps to one intent before changing section structure or navigation, and route to cannibalisation to check URL overlap when competition is the real question.",
+      "assertions": [
+        "Declines to turn each cluster into a new page",
+        "States token overlap does not prove shared intent or justify a new page",
+        "States token overlap does not establish that current URLs compete",
+        "Recommends checking whether a cluster maps to one intent before restructuring",
+        "Routes to report id cannibalisation to check URL overlap"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "Queries under the threshold basically do not exist, and these page-two clusters will just pick up clicks from better CTR.",
+      "expected_output": "Should refuse both readings. Should state queries below the threshold or outside the cap are outside the conclusion, not absent demand, and that page-two clusters do not claim a CTR-only click lift. Should read the summary threshold, limit, and brand filtering to see what was excluded, and keep excluded and observed states distinct.",
+      "assertions": [
+        "Refuses to treat below-threshold queries as absent demand",
+        "States queries below the threshold or outside the cap are outside the conclusion, not absent demand",
+        "States page-two clusters do not claim a CTR-only click lift",
+        "Reads the summary threshold, limit, and brand filtering to see what was excluded",
+        "Keeps excluded and observed states distinct"
+      ],
+      "files": []
+    }
+  ]
+}

package/evals/quick-wins.json

@@ -0,0 +1,86 @@
+{
+  "subject": "quick-wins",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Where can we get some easy SEO wins without creating new content?",
+      "expected_output": "Should use report id quick-wins to build a bounded queue of retained position 4 through 10 query and page rows with CTR below a site-aware benchmark. Should follow the discovery flow: seo_list_reports with category opportunities, seo_describe_report with id quick-wins, then seo_run_report with bounded params. Should clarify that quick win names the review queue, not effort, certainty, or expected traffic. Should check dataStatus, date range, and the source row cap before presenting rows.",
+      "assertions": [
+        "Uses report id quick-wins for the opportunity queue",
+        "Follows seo_list_reports, seo_describe_report, seo_run_report in order",
+        "Clarifies quick win describes the review queue, not effort or expected traffic",
+        "Targets retained position 4 to 10 rows below the CTR benchmark",
+        "Checks dataStatus, date range, and source row cap before presenting rows",
+        "Passes bounded parameters rather than unbounded ones"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Run quick-wins for sc-domain:example.com over 90 days, top 20 rows, at least 100 impressions, and verify the top 5 pages against their live content.",
+      "expected_output": "Should run report id quick-wins with params site sc-domain:example.com, days 90, limit 20, minImpressions 100, verifyContent true, verifyLimit 5, via seo reports run quick-wins --params or seo_run_report. Should note limit bounds returned rows and verifyLimit bounds live page checks. Should inspect verification.requested, attempted, verified, failed, and technical counts and treat an unverified item as still having GSC evidence but not a content-coverage conclusion.",
+      "assertions": [
+        "Runs report id quick-wins with days 90, limit 20, and minImpressions 100",
+        "Sets verifyContent true and verifyLimit 5 as requested",
+        "Notes limit bounds returned rows and verifyLimit bounds live checks",
+        "Inspects verification requested, attempted, verified, failed, and technical counts",
+        "Treats an unverified item as having GSC evidence but no content-coverage conclusion",
+        "Uses only parameters defined in the report schema"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "So if we rewrite the titles for the top quick-wins rows, this guarantees more clicks, right? Give me the total extra clicks.",
+      "expected_output": "Should refuse to guarantee clicks or total the shortfall as lift. Should explain that estimatedCtrClickShortfall and the priority score are heuristics and explicitly not estimated lift. Should note average position is not a stable rank and that CTR is influenced by intent and SERP features, so a title change does not promise clicks. Should recommend recording the change and comparing a later complete window instead of forcing query wording into copy.",
+      "assertions": [
+        "Refuses to guarantee more clicks from title rewrites",
+        "States estimatedCtrClickShortfall and priority score are heuristics, not lift",
+        "Does not total the shortfall into a promised click gain",
+        "Notes average position is not a stable rank",
+        "Recommends comparing a later complete window to measure the effect",
+        "Warns against forcing query wording into copy"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "The run shows possiblyTruncated true and some invalidRows. There are no rows for our pricing section, so pricing has no opportunities. Agreed?",
+      "expected_output": "Should not read the empty pricing result as a definitive zero. Should explain that source.possiblyTruncated and selection.invalidRows mean the evidence is capped or partial, so filtered or capped evidence cannot be called an all-clear or a true zero. Should keep filtered, invalid, capped, and complete states distinct. Should recommend widening the window or thresholds, or checking the source cap, before concluding pricing has no opportunities.",
+      "assertions": [
+        "Refuses to treat the empty pricing result as a definitive zero",
+        "Cites possiblyTruncated and invalidRows as capped or partial evidence",
+        "States filtered or capped evidence cannot be an all-clear",
+        "Keeps filtered, invalid, capped, and complete states distinct",
+        "Recommends widening the window or checking the cap before concluding"
+      ],
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "A row sits at average position 6 for a query that isn't in the page copy. Just drop the exact query phrase into the title and H1 to lock in position 6.",
+      "expected_output": "Should decline to force the exact query wording into the copy and should not treat average position 6 as a locked rank. Should explain average position is averaged and varies by search, device, country, and day. Should recommend inspecting the live SERP and testing clearer snippet framing, and only improving coverage if the page genuinely misses the answer, rather than keyword-stuffing the title and H1. Should keep the action structural.",
+      "assertions": [
+        "Declines to force the exact query phrase into the title and H1",
+        "States average position 6 is not a locked or stable rank",
+        "Notes average position varies by search, device, country, and day",
+        "Recommends inspecting the live SERP and testing snippet framing",
+        "Only suggests coverage changes if the answer is genuinely missing"
+      ],
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Content verification failed to fetch several of the pages. Treat those as thin pages that need a rewrite.",
+      "expected_output": "Should not turn a failed fetch into a thin-content verdict. Should read verification.failed and technical counts and keep a failed or unverified page at lower confidence, noting it still has GSC evidence but cannot support a content-coverage conclusion. Should recommend retrying the fetch or inspecting the page directly before recommending a rewrite. Should keep failed and verified states distinct.",
+      "assertions": [
+        "Refuses to label failed-fetch pages as thin content",
+        "Reads verification.failed and technical counts",
+        "Keeps failed or unverified pages at lower confidence",
+        "States the page still has GSC evidence but no content-coverage conclusion",
+        "Recommends retrying the fetch or inspecting the page before a rewrite"
+      ],
+      "files": []
+    }
+  ]
+}