seo 0.0.15 → 0.1.0

package/skills/seo-geo-readiness/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: seo-geo-readiness
+description: Audit local technical eligibility evidence and supporting website observations for AI search with seo. Use when the user asks about ChatGPT, Claude, Perplexity, Gemini, Google AI Overviews, LLM citations, llms.txt, structured data, authorship, or AI-search visibility.
+---
+
+# GEO readiness
+
+This workflow measures technical readiness and referral evidence. It does not
+prove that an AI product cites the site.
+
+## Run the readiness report
+
+Create a saved crawl, then analyze the same report:
+
+```bash
+seo crawl --project <project> --max-pages 500 --save --json
+seo ai-readiness --project <project> --json
+```
+
+Through MCP, use `seo_run_report` with report id `ai-readiness`. Use report id
+`geo-gaps` when exact affected URLs for crawl and indexability rules are
+needed. Call `seo_describe_report` before a report when its parameters are not
+already known.
+
+1. Check `dataStatus`, `summary.pageLimitReached`, warnings, and caveats.
+2. Separate failed technical checks from contextual observations.
+3. Treat local crawl indexability as local evidence. It does not prove that
+   Google indexed the URL.
+4. Use bounded URL Inspection evidence when Google's indexed snapshot changes
+   the decision. It is not a live crawl or a sitewide sample.
+
+## Explain the evidence
+
+- Blocked crawling, publisher `noindex`, snippet restrictions, and non-success
+  HTML responses can prevent or limit technical eligibility.
+- Structured data, semantic HTML, authorship, and dates are contextual
+  observations. Recommend them only for a documented user or Search feature
+  need.
+- Paragraph shape, lists, tables, and question headings do not prove quality or
+  citation likelihood.
+- Do not recommend content chunking or a minimum word count solely for AI
+  Search.
+- `/llms.txt` is optional metadata for agents that support it. The report does
+  not treat it as a Google Search ranking signal.
+
+Useful follow-up reports remain structured for agents:
+
+```bash
+seo seo-to-ai-query --project <project> --json
+seo ai-referrals --project <project> --json
+seo llms audit --project <project> --json
+```
+
+`seo-to-ai-query` creates deterministic monitoring-prompt suggestions from
+retained GSC wording. These are not observed AI queries. `ai-referrals` reports
+known GA4 referral evidence and cannot measure citations without a referral.
+
+Report `nosnippet`, `max-snippet:0`, positive `max-snippet` limits, and
+unrestricted `max-snippet:-1` exactly. No detected page-level restriction does
+not guarantee that Google will select or show the page.

package/skills/seo-geo-readiness/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SEO GEO readiness"
+  short_description: "Review local AI-search readiness evidence"
+  default_prompt: "Use $seo-geo-readiness to review this site's AI-search readiness without overstating citations or visibility."

package/skills/seo-site-audit/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: seo-site-audit
+description: Run an evidence-backed site audit with the seo main report, crawler, and focused follow-up reports. Use when the user asks to audit or diagnose a website across Search Console performance, technical SEO, indexability, metadata, schema, internal linking, security, performance, or AI-search readiness.
+---
+
+# SEO site audit
+
+Start with the main report. It joins the available first-party evidence and
+returns a small set of follow-up commands.
+
+Through MCP, call `seo_run_report` with report id
+`search-performance-overview`. Call `seo_describe_report` first when its
+parameters are not already known. Use the CLI when MCP is not available:
+
+```bash
+seo report --project <project> --json
+seo report --site sc-domain:example.com --json
+```
+
+## Read the main report
+
+1. Check `dataStatus`, source completeness, skipped sections, warnings, and
+   caveats before interpreting findings.
+2. Read the narrative and priority queue against their evidence references.
+3. Use `nextCommands` to choose a small number of follow-ups. Do not run every
+   report by default.
+4. Keep missing, unavailable, filtered, partial, capped, and complete evidence
+   separate. A partial source cannot support an all-clear.
+
+## Add technical crawl evidence
+
+Run a crawl when the user asks for technical coverage or the main report
+identifies a technical evidence gap:
+
+```bash
+seo crawl --project <project> --max-pages 500 --save --json
+seo crawl https://example.com --max-pages 500 --save --json
+```
+
+Read `summary`, `topFixes`, `warnings`, and `caveats` first. Check
+`summary.pageLimitReached` before making sitewide claims. Reuse the saved report
+for detail instead of crawling again:
+
+- Report id `top-fixes` returns a bounded queue.
+- Report id `affected-urls` returns URLs for one rule.
+- Report id `explain-crawl-issue` explains an unfamiliar rule.
+- Report id `crawl-report` returns requested report detail.
+
+Use report id `performance-audit` for a selected URL when performance evidence
+is needed. A crawl does not replace Lighthouse lab data or CrUX field data.
+
+## Present the result
+
+Give the user the top three to five evidence-backed actions, affected areas,
+and a verification command for each action. Name every material gap or cap.
+
+Never invent clicks, sessions, rankings, issue counts, indexing state, or
+sitewide health. Keep advice structural and diagnostic unless the user asks
+for copy.

package/skills/seo-site-audit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SEO site audit"
+  short_description: "Audit a site with report and crawl evidence"
+  default_prompt: "Use $seo-site-audit to audit this site and return a bounded evidence-backed action plan."

package/skills/seo-to-ai-query/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: seo-to-ai-query
+description: Convert retained GSC query wording into deterministic AI monitoring prompts; use when an agent needs a reproducible prompt seed set without claiming observed AI demand or visibility.
+---
+
+# Queries to AI prompts
+
+Use this report to turn first-party GSC query wording into a bounded set of prompts for later manual or automated monitoring. Each source query keeps its clicks, impressions, CTR, and average position, while deterministic templates produce stable prompt suggestions. The output is useful for designing a monitoring corpus. It is not evidence that anyone entered those prompts into an AI product, that an answer mentioned the site, or that the source query has equivalent AI demand.
+
+## Run the report
+
+Use the compact MCP flow:
+
+1. Call `seo_list_reports` with `{"category":"ai-search"}`.
+2. Call `seo_describe_report` with `{"id":"seo-to-ai-query"}`.
+3. Call `seo_run_report` with `{"id":"seo-to-ai-query","params":{"site":"sc-domain:example.com","days":90,"limit":20,"minImpressions":100,"maxRows":10000}}`.
+
+The CLI uses the same registry entry:
+
+```sh
+seo reports describe seo-to-ai-query --json
+seo reports run seo-to-ai-query --params '{"site":"sc-domain:example.com","days":90,"limit":20,"minImpressions":100,"maxRows":10000}' --json
+```
+
+`site` is required. Use either `days` or an explicit `startDate` and `endDate` pair. `maxRows` bounds source retrieval and `limit` bounds returned queries. Supply `brandTerms` or `includeBrand:true` only when brand handling is intentional.
+
+## Interpret and act
+
+Check `dataStatus` before reading `items`: `empty`, `filtered`, `partial`, and `available` mean different things. Preserve `dateRange`, `source.possiblyTruncated`, filters, `selection.invalidRows`, `selection.conflictingRows`, limited rows, warnings, and caveats. `methodology.observedAiPromptData` and `estimatedTrafficLift` are explicitly false. Each item has `evidenceScope: retained-gsc-query`; its prompts inherit that narrow scope.
+
+Safe actions are to select representative prompt variants, store the source query and date range beside later observations, and refresh the corpus on a controlled schedule. Do not report generated prompt count as AI demand, fill missing prompts with guessed traffic, or interpret no returned rows as an all-clear when the source is partial or filtering removed candidates.

package/skills/seo-to-ai-query/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Queries to AI prompts"
+  short_description: "Convert retained GSC wording into deterministic monitoring prompts"
+  default_prompt: "Use $seo-to-ai-query to run the seo-to-ai-query report and explain its evidence and limits."

package/skills/setup-check/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: setup-check
+description: Check whether local SEO Skills CLI authentication and defaults are usable; use it before reports when login, scopes, or saved configuration may be incomplete.
+---
+
+# Check local setup
+
+Run `setup-check` before blaming a report for an authentication or configuration
+failure. It reads local setup state and separates missing credentials, missing
+Google scopes, and absent defaults from actual SEO evidence. A passing result
+means the local prerequisites look present. It does not prove that a token is
+still accepted by Google or that the account can access a particular property.
+
+## Run the report
+
+With MCP, call `seo_list_reports` with `{"category":"setup"}`. Then call
+`seo_describe_report` with `{"id":"setup-check"}` and use the returned schema.
+Finally call `seo_run_report` with `{"id":"setup-check","params":{}}`. The report
+accepts no parameters, so do not invent a site, project, or refresh field.
+
+The CLI exposes the same registry and schema:
+
+```sh
+seo reports describe setup-check --json
+seo reports run setup-check --params '{}' --json
+```
+
+Read MCP `structuredContent` or the CLI JSON as the machine contract. Use the
+text response only as a short presentation layer.
+
+## Interpret the checks
+
+Start with `ok`, then inspect every entry in `checks`. `status` distinguishes a
+blocking `fail` from a non-blocking `warn`; `detail` records what was observed;
+`fix` gives the matching local remedy when one exists. `generatedAt` tells you
+when the filesystem and token metadata were checked. Missing saved GSC or GA4
+defaults are normally warnings because explicit report parameters can replace
+them.
+
+Never copy account emails, token contents, OAuth client values, private keys,
+or local credential files into an answer. Summarise the check id, status, and a
+safe fix instead.
+
+## Act safely
+
+Apply the narrow fix attached to a failed check, such as logging in again or
+restoring the same OAuth client used by stored tokens. Re-run `setup-check`, then run
+a small read-only report for the intended property. Do not treat a setup pass
+as evidence about rankings, indexing, analytics accuracy, or site health.

package/skills/setup-check/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Doctor"
+  short_description: "Check local seo auth and configuration"
+  default_prompt: "Use $setup-check to run the setup-check report and explain its evidence and limits."

package/skills/site-crawl/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: site-crawl
+description: Build a bounded technical SEO inventory with explicit request, page, issue, and completeness evidence. Use for a site baseline or to save a stable crawl for focused follow-up reports.
+---
+
+# Crawl a site
+
+A crawl observes what the configured fetcher could discover and retrieve during one run. It is the foundation for most technical reports, but it is not an index, traffic source, or guarantee of complete site coverage. Set a deliberate page and depth budget, then save the snapshot when later analysis must share the same evidence.
+
+## Run it
+
+For MCP, call `seo_list_reports` with category `crawl` when discovery is needed. Call `seo_describe_report` with `{ "id": "site-crawl" }`, then `seo_run_report` with:
+
+```json
+{
+  "id": "site-crawl",
+  "params": {
+    "url": "https://example.com/",
+    "maxPages": 100,
+    "maxDepth": 3,
+    "saveReport": true
+  }
+}
+```
+
+Check `isError` and consume MCP `structuredContent`. The same run is available from the CLI:
+
+```sh
+seo reports describe site-crawl --json
+seo reports run site-crawl --params '{"url":"https://example.com/","maxPages":100,"maxDepth":3,"saveReport":true}' --json
+```
+
+Describe the schema before adding `include`, `exclude`, sitemap, robots, JavaScript, or fetch-rate controls; their interaction changes the evidence collected.
+
+## Judge the crawl before the site
+
+Start with status, `requestEvidenceStatus`, attempted and fetched counts, failures, retained pages, `pageLimitReached`, data-source states, warnings, and caveats. A partial or capped crawl cannot support an all-clear or a definitive zero. Raw `pages`, `requests`, and full `issues` are opt-in because they can be large; request only what the next decision needs.
+
+Separate observations from defects. Response failures and contradictory indexability signals deserve investigation, while canonicals, robots rules, `noindex`, and snippet limits may be intentional. Use the compact top fixes for triage, then run `affected-urls` and `explain-crawl-issue` before creating work. Preserve the report id and crawl settings for verification. If JavaScript rendering was disabled or discovery depended on the sitemap or internal links, state that boundary when summarizing results.

package/skills/site-crawl/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Crawl site"
+  short_description: "Crawl a site for technical SEO evidence"
+  default_prompt: "Use $site-crawl to run the site-crawl report and explain its evidence and limits."

package/skills/striking-distance/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: striking-distance
+description: Find retained GSC query-page rows with average positions from 11 through 20; use it to build a bounded review queue near page-one visibility.
+---
+
+# Review striking-distance rows
+
+Use `striking-distance` to find query-page combinations whose retained GSC
+average position falls from 11 through 20. This range can surface useful review
+candidates, but it is a heuristic boundary. Average position varies by search,
+device, country, and day, so the report does not prove that a URL consistently
+ranks on a literal second results page or predict how many clicks a change will
+produce.
+
+## Run the report
+
+With MCP, call `seo_list_reports` with `{"category":"diagnosis"}`, call
+`seo_describe_report` with `{"id":"striking-distance"}`, then call
+`seo_run_report` with only described parameters. Example:
+`{"id":"striking-distance","params":{"site":"sc-domain:example.com","days":28,"minImpressions":50,"limit":10,"includeBrand":false,"verifyContent":true,"verifyLimit":5}}`.
+
+The CLI has exact registry parity:
+
+```sh
+seo reports describe striking-distance --json
+seo reports run striking-distance --params '{"site":"sc-domain:example.com","days":28,"minImpressions":50,"limit":10,"includeBrand":false,"verifyContent":true,"verifyLimit":5}' --json
+```
+
+Add `brandTerms`, JavaScript rendering, or bounded fetch-rate controls only
+after inspecting the schema and when the investigation needs them.
+
+## Interpret the output
+
+Check `range`, `rangeDays`, `dataStatus`, and `source` before the item list.
+`source.possiblyTruncated` and retained-row completeness limit any all-clear.
+Use `selection` to see what was invalid, outside the position range, branded,
+below thresholds, eligible, returned, or limited. `methodology` explains the
+priority heuristic.
+
+For each item, read the observed query, URL, clicks, impressions, CTR, average
+position, recommendation evidence, and optional `contentVerification`.
+`verification` reports requested, attempted, verified, technical, and failed
+counts; unverified or failed pages must keep lower confidence. Groups and
+templates show repeated patterns only within retained candidates.
+
+## Act safely
+
+Audit a small number of high-impression candidates. Fix verified technical
+problems first; otherwise compare intent, title framing, page coverage, and
+internal links against observed query evidence. Do not rewrite a page solely
+because it sits inside the position band, and do not present the priority score
+as expected traffic or ranking lift.

package/skills/striking-distance/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Striking distance"
+  short_description: "Find retained GSC query and page rows averaging positions 11 through 20"
+  default_prompt: "Use $striking-distance to run the striking-distance report and explain its evidence and limits."

package/skills/technical-watch/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: technical-watch
+description: Coordinate crawl comparison, URL Inspection monitoring, and optional link recovery. Use it for a bounded recurring watch without claiming inventory-wide coverage.
+---
+
+# Technical watch workflow
+
+This workflow watches several technical surfaces together: crawl change,
+sitemap-derived URL inspection, and optional recovery of historically valuable
+links. It is useful after releases and on a schedule. Its components have
+different coverage and freshness, so a successful run does not prove every URL
+is crawlable, indexed, unchanged, or free of issues.
+
+## Run it
+
+Use the exact MCP discovery flow:
+
+1. Call `seo_list_reports` with `category: "workflows"` and select `technical-watch`.
+2. Call `seo_describe_report` with `id: "technical-watch"`; choose the components required.
+3. Call `seo_run_report` with that id and only schema-valid parameters.
+
+CLI parity:
+
+```sh
+seo reports describe technical-watch --json
+seo reports run technical-watch --params '{"site":"sc-domain:example.com","startUrl":"https://example.com/","sitemaps":["https://example.com/sitemap.xml"],"limit":250,"dailyLimit":200,"inspectLimit":25,"recoverLinks":true}' --json
+```
+
+Provide `startUrl` for crawl comparison and `sitemaps` for index monitoring.
+`dailyLimit`, `inspectLimit`, `maxUrls`, and crawl `limit` are real coverage
+bounds. Enable `js` only when rendering is required.
+
+## Interpret and act
+
+Inspect every workflow step and nested `crawl`, `index`, and `recovery` output
+independently. For crawls, compare run ids, limits, failures, warnings, and
+changed items. For inspection, distinguish selected, unselected-due, attempted,
+failed, quota-blocked, deferred, current issue, and regression states. URL
+Inspection is a provider snapshot; sitemap discovery is not proof of indexing.
+For recovery, historical clicks-at-risk are observed history, not forecast loss.
+
+Reproduce new failures, verify redirect chains and intentional controls, then
+fix confirmed regressions with a rollback path. Schedule another bounded run to
+confirm recovery. Never remove `noindex`, canonicals, robots rules, or redirects
+without checking intent. Partial crawls, capped sitemap inventories, quotas,
+and failed subqueries must stay visible in any all-clear statement.
+
+Use MCP `structuredContent` for automation and Markdown only for the human watch
+summary.

package/skills/technical-watch/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Technical watch workflow"
+  short_description: "Run crawl-diff and URL Inspection monitoring together"
+  default_prompt: "Use $technical-watch to run the technical-watch report and explain its evidence and limits."

package/skills/top-fixes/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: top-fixes
+description: Rank recurring technical crawl findings into a bounded implementation queue with visible scoring factors. Use for triage before inspecting affected URLs and rule-level evidence.
+---
+
+# Prioritize technical fixes
+
+Large crawls need triage, but priority must remain explainable. This report groups issues by rule and ranks them using severity, affected-page count, estimated effort, and any available Search Console or analytics evidence. It is a deterministic queue from retained evidence, not a forecast of rankings, traffic, conversions, or revenue.
+
+## Run it
+
+For MCP, call `seo_list_reports` with category `crawl` only when discovery is needed. Call `seo_describe_report` with `{ "id": "top-fixes" }`, then call `seo_run_report` with:
+
+```json
+{
+  "id": "top-fixes",
+  "params": {
+    "reportId": "crawl_example_20260710",
+    "category": "metadata",
+    "limit": 5
+  }
+}
+```
+
+Confirm `isError` is false and read `structuredContent`. CLI parity is:
+
+```sh
+seo reports describe top-fixes --json
+seo reports run top-fixes --params '{"reportId":"crawl_example_20260710","category":"metadata","limit":5}' --json
+```
+
+Use `url` only for an intentional fresh crawl. Reusing a saved report keeps the queue tied to the same issue inventory.
+
+## Turn priority into work
+
+Read `dataSources`, summary, warnings, and caveats before the ranked fixes. For each item inspect the rule id, affected count, sample URLs, `scoreFactors`, `whyThisRanks`, effort, fix guidance, and verification steps. Missing provider joins must stay unavailable; numeric zeros are meaningful only when the corresponding source is complete and valid.
+
+The category and result limits narrow the queue, while the original crawl may also be capped or partial. Therefore rank means "highest among retained eligible findings," not globally highest. Run `affected-urls` for the same rule and report id, inspect representative templates, and use `explain-crawl-issue` before assigning work. Confirm intentional indexability and canonical controls with the publisher. After implementation, repeat the same crawl configuration and verify the observed rule evidence rather than relying on a score change alone.

package/skills/top-fixes/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Top fixes"
+  short_description: "Return a bounded technical fix queue from crawl evidence"
+  default_prompt: "Use $top-fixes to run the top-fixes report and explain its evidence and limits."

package/skills/traffic-anomaly/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: traffic-anomaly
+description: Test whether recent finalized GSC clicks or impressions differ unusually from an observed baseline; use it to confirm movement before investigating possible causes.
+---
+
+# Detect unusual traffic movement
+
+Use `traffic-anomaly` when a dashboard looks different and you need a
+repeatable check against recent history. It compares a recent finalized GSC
+window with an observed baseline for clicks and impressions. Statistical
+unusualness helps decide whether deeper investigation is warranted. It does not
+identify a cause, diagnose a site defect, or prove that an external event
+affected the property.
+
+## Run the report
+
+With MCP, call `seo_list_reports` with `{"category":"diagnosis"}`. Call
+`seo_describe_report` with `{"id":"traffic-anomaly"}` before choosing windows.
+Then call `seo_run_report`, for example
+`{"id":"traffic-anomaly","params":{"site":"sc-domain:example.com","days":90,"recentDays":7,"refresh":false}}`.
+
+CLI parity uses the same report definition:
+
+```sh
+seo reports describe traffic-anomaly --json
+seo reports run traffic-anomaly --params '{"site":"sc-domain:example.com","days":90,"recentDays":7,"refresh":false}' --json
+```
+
+The discovery schema currently exposes broad numeric types for these window
+fields. Use sensible positive whole-day values even though all bounds are not
+expressed in JSON Schema.
+
+## Interpret the output
+
+Read `coverage` first. Confirm the requested dates, expected and observed days,
+missing days, invalid rows, duplicate rows, and `status`. Partial coverage can
+change the baseline and must stay in the conclusion. `rows` is not a quality
+verdict.
+
+Each entry in `anomalies` names the metric, baseline and comparison dates,
+means and totals, `percentChange`, `zScore`, `significanceMethod`, `direction`,
+and `significant`. A null percentage from a zero baseline is different from
+zero change. `outside-flat-baseline` handles movement where an observed
+baseline has no variance; it still describes only the supplied data.
+
+## Act safely
+
+If movement is significant and coverage is adequate, run `segment-impact` for
+pages and queries, then check site changes, seasonality, indexing, and tracking.
+If it is normal, keep monitoring rather than forcing a story. Never label the
+result a penalty, algorithm update, recovery, or causal diagnosis without
+independent evidence.

package/skills/traffic-anomaly/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Traffic anomaly"
+  short_description: "Detect statistically unusual recent GSC movement"
+  default_prompt: "Use $traffic-anomaly to run the traffic-anomaly report and explain its evidence and limits."

package/skills/update-correlation/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: update-correlation
+description: Overlay finalized GSC anomaly windows with official Google ranking-update dates; use it for timing context while keeping attribution explicitly unestablished.
+---
+
+# Add update timing context
+
+Use `update-correlation` only after defining the traffic window you want to
+examine. It combines the anomaly analysis with official ranking incident dates
+and known local changes. Overlap can make an update a reasonable investigation
+context. It cannot show that the update caused a gain or loss, even when the
+movement is large and no other change has been recorded.
+
+## Run the report
+
+With MCP, call `seo_list_reports` with `{"category":"diagnosis"}`. Call
+`seo_describe_report` with `{"id":"update-correlation"}`, then use
+`seo_run_report`, for example
+`{"id":"update-correlation","params":{"site":"sc-domain:example.com","days":90,"recentDays":7,"paddingDays":2,"refresh":false}}`.
+
+The same definition is available through the CLI:
+
+```sh
+seo reports describe update-correlation --json
+seo reports run update-correlation --params '{"site":"sc-domain:example.com","days":90,"recentDays":7,"paddingDays":2,"refresh":false}' --json
+```
+
+The schema currently types window and padding values as general numbers. Pass
+positive whole-day values and avoid excessive padding that makes overlap almost
+inevitable.
+
+## Interpret the output
+
+Start with `classification`, but always keep `attribution` and `confidence` in
+view. The report intentionally returns attribution as `not-established` and
+confidence as `none`. Inspect the underlying `anomalies`, exact
+`overlappingUpdates`, and `confounders` before repeating the summary.
+
+Use `evidence` for observed movement and date overlap, `caveats` for window,
+padding, freshness, and source limits, and `source` to identify the official
+feed. `significant-movement-with-update-overlap` means both facts occurred in
+the configured window. `update-overlap-without-significant-movement` is not an
+impact result. `no-update-overlap` does not explain any movement that remains.
+
+## Act safely
+
+Test saved deploys, redirects, pruning, blocking, tracking, and content changes
+first when they overlap. Use `segment-impact` or the postmortem workflow to map
+affected templates and queries. Preserve winning patterns and investigate
+losers with page-level evidence. Never describe temporal overlap as a penalty,
+reward, recovery, or confirmed algorithm effect.

package/skills/update-correlation/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Update correlation"
+  short_description: "Compare recent GSC movement with official Google ranking update windows"
+  default_prompt: "Use $update-correlation to run the update-correlation report and explain its evidence and limits."

package/skills/update-postmortem/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: update-postmortem
+description: Compare retained winners and losers around a Google ranking update window. Use it to structure a postmortem while explicitly keeping causation unestablished.
+---
+
+# Update postmortem workflow
+
+This workflow organizes performance movement around a known Google update,
+including template and segment evidence plus optional local change-log context.
+It helps identify where to investigate. Temporal overlap and exposure do not
+prove that the update caused any change, and retained winners and losers are not
+a complete property inventory when sources are capped or filtered.
+
+## Run it
+
+Use the exact MCP discovery flow:
+
+1. Call `seo_list_reports` with `category: "workflows"` and select `update-postmortem`.
+2. Call `seo_describe_report` with `id: "update-postmortem"`; inspect the current schema.
+3. Call `seo_run_report` with that id and only described parameters.
+
+CLI parity:
+
+```sh
+seo reports describe update-postmortem --json
+seo reports run update-postmortem --params '{"site":"sc-domain:example.com","days":90,"recentDays":7,"limit":10,"includeBrand":false,"knownConfounders":["Site migration on 2026-05-12"],"includeChangeLog":true}' --json
+```
+
+Record specific known confounders rather than vague suspicions. The change log
+is supporting context, not automatic attribution.
+
+## Interpret and act
+
+Start with workflow step statuses, finalized date windows, source completeness,
+failed measurements, retained limits, and caveats. Then inspect `update`,
+`insights`, `templateMovement`, and `segments`. Keep positive and negative
+movement visible. The report's cause remains not established even when dates
+overlap. Compare like-for-like metrics and note brand filtering, invalid rows,
+duplicate aggregation, and partial provider results.
+
+Safe next steps are falsifiable: inspect representative URLs from affected
+segments, reproduce technical changes, compare deployed templates, validate the
+local change log, and measure a bounded intervention. Preserve known
+confounders in the handoff. Do not roll back, rewrite, merge, or delete content
+solely because it appears among losers. Never claim update causation, recovery
+probability, future traffic, or ranking impact from this workflow.
+
+Use MCP `structuredContent` as the machine contract and Markdown only for the
+human-readable postmortem.

package/skills/update-postmortem/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Update postmortem workflow"
+  short_description: "Analyze winners and losers around a Google ranking update window"
+  default_prompt: "Use $update-postmortem to run the update-postmortem report and explain its evidence and limits."

package/.jshintrc

@@ -1,18 +0,0 @@
-{
-  "globals"   : {
-    /* MOCHA */
-    "describe"   : false,
-    "it"         : false,
-    "before"     : false,
-    "beforeEach" : false,
-    "after"      : false,
-    "afterEach"  : false,
-
-    /* COMMONJS / NODE */
-    "module"     : false,
-    "require"    : false,
-    "console"    : false,
-    "process"    : false,
-    "global"     : false
-  }
-}

package/.npmignore

@@ -1,3 +0,0 @@
-.DS_Store
-node_modules
-.seo-cache

package/.travis.yml

@@ -1,3 +0,0 @@
-language: node_js
-node_js:
-  - "0.10"

package/Makefile

@@ -1,10 +0,0 @@
-REPORTER = spec
-
-test:
-	@./node_modules/.bin/mocha \
-		--require ./test/init.js \
-		--require should \
-		--reporter $(REPORTER) \
-		test/*.test.js
-
-.PHONY: all test

package/index.js

@@ -1,2 +0,0 @@
-'use strict';
-module.exports = require('./lib/seo');