seo 0.7.1 → 0.8.0

package/README.md

@@ -1,408 +1,174 @@
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="assets/brand/s-dark.svg">
-    <img src="assets/brand/s.svg" alt="SEO Skill" width="144">
+    <img src="assets/brand/s.svg" alt="SEO Skill" width="120">
   </picture>
 </p>
 
-<h1 align="center">SEO Skill</h1>
+# SEO For Agent-Native Teams
 
-<p align="center">
-  The SEO command for AI agents. A free Google Search Console MCP server and CLI: your agent reads your real Search Console, Google Analytics and Bing data, with Google update dates beside it, plus keyword research from your own DataForSEO or Ahrefs key.
-</p>
-
-<p align="center">
-  <a href="#install-and-run-setup">Get started</a>
-  ·
-  <a href="https://seoskill.dev/docs/mcp">Hosted MCP</a>
-  ·
-  <a href="https://seoskill.dev/docs">Documentation</a>
-  ·
-  <a href="https://www.npmjs.com/package/seo">npm</a>
-  ·
-  <a href="https://github.com/iannuttall/seo/issues">Questions</a>
-  ·
-  <a href="https://seoskill.dev/privacy">Privacy</a>
-  ·
-  <a href="SECURITY.md">Security</a>
-  ·
-  <a href="LICENSE">License</a>
-  ·
-  <a href="CHANGELOG.md">Changelog</a>
-</p>
-
-<p align="center">
-  <a href="https://github.com/iannuttall/seo/actions/workflows/ci.yml"><img alt="Checks" src="https://img.shields.io/github/actions/workflow/status/iannuttall/seo/ci.yml?branch=main&label=checks&style=flat-square"></a>
-  <a href="https://www.npmjs.com/package/seo"><img alt="npm version" src="https://img.shields.io/npm/v/seo?style=flat-square"></a>
-  <a href="https://www.npmjs.com/package/seo"><img alt="npm downloads" src="https://img.shields.io/npm/dm/seo?style=flat-square"></a>
-  <img alt="Node 22 or newer" src="https://img.shields.io/badge/Node-22%2B-339933?style=flat-square">
-  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-ready-3178c6?style=flat-square">
-  <a href="LICENSE"><img alt="Apache 2.0 license" src="https://img.shields.io/badge/license-Apache--2.0-lightgrey?style=flat-square"></a>
-</p>
-
-Ask your agent what is happening in search and get an answer built from your
-own Search Console, Bing Webmaster Tools, Google Analytics and Clicky data,
-with Google update dates laid over it. Add your own DataForSEO or Ahrefs key when you need keyword,
-SERP, competitor or backlink data.
-
-The results are facts with their dates and limits. There is no advice baked
-in. Your agent reads the facts, shows you what matters and asks before it
-changes a page.
+[![npm](https://img.shields.io/npm/v/seo?style=flat-square)](https://www.npmjs.com/package/seo)
 
-## Install and run setup
+The SEO data I give my agents every day, so they work from my real numbers
+instead of guessing.
 
-You need Node 22 or newer.
+Most AI SEO tools do one of two things. They hand your agent a checklist of
+generic advice, or they feed it estimates from a keyword tool that has never
+seen your site. Either way you end up with the same pages everyone else is
+publishing. Pages written from a keyword list aren't SEO. They're slop.
 
-```sh
-npm i -g seo
-seo start
-```
+This works the other way round. It's a Google Search Console MCP server and
+CLI, and it doesn't tell your agent what to do. It gives it the facts: your
+clicks, impressions and positions from Search Console, your visits from
+Google Analytics or Clicky, your Bing data, the dates of Google updates, and
+a crawl of your site. Your agent works out what matters, and you decide what
+changes.
 
-`seo start` signs you in with Google. Then it offers to add an MCP server to
-the agents it finds (the free hosted server is the first choice, or you can
-run one locally) and to install the skill. That is all it asks. Nothing about
-your site is saved: each command names the site it works on.
+It's free and open source. Hack around with it. Make it your own.
 
-List the properties your sign-in can read, then run the main report for one:
-
-```sh
-seo sites
-seo report --site example.com
-```
+## Installation (30-second setup)
 
-## Connect the hosted MCP server
+### 1. Connect it to your agent
 
-If you would rather not install anything, connect your agent to the free
-hosted server at `https://seoskill.dev/mcp`:
+<details>
+<summary><strong>Claude Code</strong></summary>
 
-```sh
+```bash
 claude mcp add --transport http seoskill https://seoskill.dev/mcp
-codex mcp add seoskill --url https://seoskill.dev/mcp
-```
-
-Sign in with Google when the client asks. That first Google account is your
-account, so there is no password or separate signup. The server keeps only
-your linked Google accounts and any API keys you save, encrypted. It keeps no
-report data, no Search Console or analytics rows and no request logs.
-
-Your [account page](https://seoskill.dev/account) lets you add more Google
-accounts, save DataForSEO or Ahrefs keys, or delete everything.
-Each request uses the linked Google account that can read the site. The
-[hosted MCP guide](https://seoskill.dev/docs/mcp) covers other clients, and the
-[API keys guide](https://seoskill.dev/docs/keys) shows how to add a key
-without pasting it into a chat.
-
-A crawl fetches many pages, so `seo crawl` and `seo internal-links` run only
-on your machine, through the CLI or the local MCP server. Bing data also runs
-only there for now; when you ask the hosted server for Bing, it tells your
-agent which CLI command to run.
-
-## The eight commands
-
-| Command | MCP tool | What it returns |
-| --- | --- | --- |
-| `seo report` | `seo_report` | The main report: an overview against the previous period, then every section's count and top rows |
-| `seo page --url <url>` | `seo_page` | One URL: live page facts, Google index status and its queries |
-| `seo compare --date <date>` | `seo_compare` | Equal periods before and after a date, with the Google updates in the window |
-| `seo index` | `seo_index` | Pages that lost most of their clicks, checked live and with URL Inspection |
-| `seo research <action>` | `seo_research` | Keyword metrics, ranked keywords, SERPs, competitors and backlinks from your key |
-| `seo data` | `seo_data` | Raw Search Console rows, or Bing rows in the CLI and local server; the hosted tool also reads analytics landing pages |
-| `seo crawl <url>` | `seo_crawl` | A site crawl with technical issues and the URLs they affect (local only) |
-| `seo internal-links --url <url>` | `seo_internal_links` | Pages that could link to a target page (local only) |
-
-Each command takes its target (a site, URL or property) and an optional date
-window. `--site` takes a domain, a URL or a Search Console property, and
-`seo sites` lists the ones you can read. Commands that return rows also take `--detail summary|rows|full` and
-`--offset`. Brand terms, minimum impressions and the comparison period are set
-for you and shown in the output, so there is nothing else to tune.
-
-Run `seo help` for the short list, or `seo <command> --help` for one command.
-The [command docs](https://seoskill.dev/docs) explain each one.
-
-## Start with one report
-
-Run the report without a section first:
-
-```sh
-seo report --site example.com
 ```
 
-It shows site totals against the previous period, the pages and queries that
-moved, and a short count with top rows for each section. Then ask for the one
-section that matters:
-
-```sh
-seo report --site example.com --section quick-wins
-```
+</details>
 
-The sections are `overview`, `quick-wins`, `low-ctr`, `striking-distance`,
-`second-page`, `content-decay`, `cannibalization`, `traffic-drop` and `bing`.
-Page sections check their top 20 URLs live and merge same-site redirects.
+<details>
+<summary><strong>Codex</strong></summary>
 
-Each result ends with the command to run next. A traffic drop usually leads to
-`seo compare` with the date it started, then `seo page` for the URLs that
-moved:
-
-```sh
-seo compare --site example.com --date 2026-09-15
-seo page --url https://example.com/pricing
+```bash
+codex mcp add seoskill --url https://seoskill.dev/mcp
 ```
 
-Start with the summary. Ask for `--detail rows --offset 20` for the next page
-of rows, or `--detail full` for every field, only when you need them.
+</details>
 
-## Add keyword and competitor data
+<details>
+<summary><strong>Any other agent</strong></summary>
 
-Research uses your own provider account, so each request costs your credits
-with that provider. Connect a key once:
+Add `https://seoskill.dev/mcp` as a remote MCP server. Cursor, Claude
+Desktop, VS Code and most other agents support it.
 
-```sh
-seo providers dataforseo connect
-seo providers ahrefs connect
-```
+</details>
 
-On the hosted server, save the keys on your
-[account page](https://seoskill.dev/account) or send them as headers. Then ask
-for one action:
+<details>
+<summary><strong>The CLI</strong> (for crawls and Bing, which run on your machine)</summary>
 
-```sh
-seo research keyword_metrics --keywords "invoice software,invoice template"
-seo research serp --keywords "invoice software"
-seo research ranked_keywords --target example.com
-seo research competitors --target example.com
-seo research backlinks --target example.com
+```bash
+npm i -g seo
+seo start
 ```
 
-Rows with a domain get a free Domain Rating column, credited "Domain Rating by
-Ahrefs". The hosted server adds it for everyone; the CLI adds it when you have
-saved an Ahrefs key. Provider numbers are estimates. Search Console stays the
-record of what your own site actually got.
+`seo start` signs you in, connects your agents and installs the skill.
 
-## Add Bing Webmaster Tools
+</details>
 
-Bing data is free. It works in the CLI and the local MCP server. Save a Bing
-Webmaster API key (Bing Webmaster Tools, then Settings, then API access):
+### 2. Sign in with Google
 
-```sh
-seo providers bing connect
-```
-
-Agents and CI can set `SEO_BING_API_KEY` instead. `seo providers bing status`
-shows the connection and `seo providers bing disconnect` removes it. The
-hosted server has no Bing for now. When you ask it for Bing, it tells your
-agent to run the CLI instead, the same way it does for a crawl.
-
-`seo report` then shows Google and Bing clicks and impressions for the same
-dates, and each engine's share of those clicks. The `bing` section puts Bing's
-top queries and pages beside Google's numbers for the same rows, and
-`seo data --source bing` returns the raw Bing rows. Bing and Google numbers sit
-side by side and are never added together. Bing lists only its top queries
-and pages by week, so a row missing from Bing's list is unknown, not zero.
+Your agent opens a Google sign-in. Pick the account that can see your Search
+Console. That's your account. There's no password and no signup form.
 
-## Add your analytics
+### 3. Ask it something real
 
-Google Analytics comes with your Google sign-in. List your properties, then
-pass the numeric property id to a Google Analytics command:
-
-```sh
-seo analytics google properties
-seo ai-referrals --property 123456789
+```text
+Why did clicks drop on example.com last month?
 ```
 
-For Clicky, save your Clicky account login (every site) or one site's ID and
-sitekey on your [account page](https://seoskill.dev/account#clicky). The
-hosted server and a CLI linked with `seo login` both read them:
+That's it. You're ready to go.
 
-```sh
-seo data --source clicky --site example.com
-```
+## What you can ask it
 
-A site saved on this machine only with
-`seo analytics clicky connect --site-id 12345` works too, by its site ID.
+- "Why did clicks drop last month? Was it the core update?"
+- "Which pages are close to page one, and what do they rank for?"
+- "Is this page indexed? If not, why not?"
+- "Which searches does this page show up for that it never mentions?"
+- "Can ChatGPT, Claude and Perplexity read my site?"
+- "Who am I up against in search, and is there demand for a 'vs' or alternatives page?"
 
-There will be no more built-in sources. For any other analytics or research
-tool, build your own provider package from the
-[provider template](https://github.com/iannuttall/seo-provider-template). Each source keeps its own metric names, so a
-Clicky visit is never relabelled as a Google Analytics user.
+Your agent picks the commands, reads the results and shows you what it found.
 
-## Use it with agents
+## Why it exists
 
-The skill teaches your agent the eight commands, the one-report flow and the
-evidence rules. If you skipped it during `seo start`, add it now:
+I built this because agents kept failing at SEO in the same few ways.
 
-```sh
-seo skill install
-```
+### #1: The agent makes things up
 
-`seo start` can add the hosted or the local MCP server for you. To add the
-local MCP server later, to Codex, Claude Code, Claude Desktop or Cursor:
+**The problem.** Ask an agent why your traffic dropped and you get a tidy
+list of possible causes. Algorithm update, technical issues, content
+quality. None of it comes from your site, so none of it helps.
 
-```sh
-seo mcp install
-```
+**The fix** is to give it your numbers:
 
-Scripts can pick clients with `--codex`, `--claude-code`, `--cursor` or
-`--claude-desktop`. Other clients can start `seo mcp serve` as a local stdio
-server.
-
-The local server and the hosted server serve the same tools: `seo_sites`,
-`seo_report`, `seo_page`, `seo_compare`, `seo_index`, `seo_research` and
-`seo_data`. The local server adds `seo_crawl` and `seo_internal_links`, plus
-`seo_list_providers`, `seo_describe_provider` and `seo_run_provider` for
-installed provider packages.
-
-## What the results can show
-
-- Missing, partial, capped and filtered data is named. It never becomes a zero
-  or an all-clear.
-- Search Console, Bing, analytics, live page checks and provider estimates stay
-  apart. Query rows do not add up to site totals.
-- Flags such as likely automated queries and CTR gaps against the site's own
-  curve are heuristics. They point at rows worth a look.
-- A Google update in the same window is timing, not cause.
-- An intentional `noindex`, canonical or redirect is an observation until you
-  say it is wrong.
-
-Nothing here promises clicks, rankings or indexing. Check a change by running
-the same command again over a later, complete window.
-
-## Upgrading from 0.3
-
-Saved project profiles are gone. Every command takes `--site` (or `--url`), and
-`--project` or `--client` now stops with a note that says so. `seo projects`,
-`seo client` and the commands that saved history between runs (`change-log`,
-`tests`, `content-groups`, `monitoring`, `schedule`, `index-watch`,
-`technical-watch`, `crawl-reports`, `crawl-diff` and `diagnose`) were removed.
-Your agent keeps its own notes now. Each removed command names what to use
-instead. To stay on the old version, run `npm i -g seo@0.2.41`.
-
-## Upgrading from 0.2
-
-Version 0.3.0 moved most reports into the eight commands. Old names such as
-`seo quick-wins` still run in 0.3 and print the new command to use. They stop
-working in 0.4.0. Some reports and commands were removed, including rank
-tracking, programmatic SEO, AI search readiness, llms.txt, Bing links,
-IndexNow, Semrush, local search, server logs and the monthly and narrative
-reports. Bing Webmaster search data came back in 0.3.0-beta.3. The old
-research reports became `seo research`. The [changelog](CHANGELOG.md) lists
-every old name and where it went.
-
-## Use it in CI and scripts
-
-Add `--json` to any command. JSON mode never prompts. Pass `--site` every
-time.
-
-```sh
-seo report --site sc-domain:example.com --json
-seo report --site sc-domain:example.com --section content-decay --json
-```
+- [`seo report`](https://seoskill.dev/docs/report) shows your totals against the last period, the pages and queries that moved, and the places worth a look: quick wins, low click-through rates, pages stuck on page two, decay and cannibalization.
+- [`seo compare`](https://seoskill.dev/docs/compare) lines up the weeks before and after a date, with the Google updates in between.
 
-A CI job can read Search Console with a Google service account. Give it the
-JSON key through your secret store and grant it access to the exact
-properties:
-
-```yaml
-- name: Run the SEO report
-  run: |
-    npm i -g seo
-    seo report --site sc-domain:example.com --json > seo-report.json
-  env:
-    SEO_GOOGLE_SERVICE_ACCOUNT_JSON: ${{ secrets.SEO_GOOGLE_SERVICE_ACCOUNT_JSON }}
-```
+### #2: Keyword tools are guessing too
 
-## Use it as a library
+**The problem.** Ahrefs and Semrush estimate your traffic from a sample.
+They miss most of the long tail, and they rarely agree with each other.
 
-Install the same package in any Node 22 or newer project:
+**The fix** is to start from your own data. Search Console is the source of
+truth for Google. When you do need keyword volumes or competitor data,
+[`seo research`](https://seoskill.dev/docs/research) uses your own
+DataForSEO or Ahrefs key, and it keeps those estimates apart from your real
+numbers.
 
-```sh
-npm install seo
-```
+### #3: The agent says it's fixed when it isn't
 
-```ts
-import { executeReport } from 'seo/mcp'
-import { crawlSite } from 'seo'
+**The problem.** Agents trust their own edits. Then you find the page is
+still noindexed, still redirecting, or still not in Google.
 
-const wins = await executeReport('quick-wins', {
-  site: 'sc-domain:example.com',
-})
+**The fix** is to check the live site:
 
-const crawl = await crawlSite({
-  url: 'https://example.com',
-  maxPages: 100,
-})
+- [`seo page`](https://seoskill.dev/docs/page) loads one URL and asks Google whether it's indexed.
+- [`seo index`](https://seoskill.dev/docs/indexing) checks every page that lost its clicks.
+- [`seo crawl`](https://seoskill.dev/docs/crawl) checks the whole site, including what AI agents can read.
 
-console.log(wins)
-console.log(crawl.summary, crawl.issueGroups)
-```
+### #4: Too many reports
 
-`seo/provider-sdk` is the public contract for provider packages. Start from
-the [provider template](https://github.com/iannuttall/seo-provider-template).
+**The problem.** SEO tools love reports. The first version of this had about
+70 of them, and almost nobody used most of them.
 
-## Local data and Google access
+**The fix** was to cut it down to a handful of commands. Each one takes a
+site or a URL, and dates if you want them. There are no settings to tune. Every result
+ends with the command to run next, so your agent always knows where to go.
 
-Google tokens use your system keychain, with a private `0600` file fallback on
-headless machines. Settings, provider keys and a short cache of Google
-responses stay in your local config directory. Reports and crawls are not
-saved: each run returns its results and your agent decides what to keep. A command still reaches the network when it needs Google,
-your site or a provider you connected.
+## Reference
 
-```sh
-seo privacy
-seo doctor
-seo auth logout --all
-seo reset
-```
+| Command | What it returns |
+| --- | --- |
+| [`seo report`](https://seoskill.dev/docs/report) | Your Search Console overview, then the top rows of each section |
+| [`seo page`](https://seoskill.dev/docs/page) | One URL: the live page, its Google index status and its queries |
+| [`seo compare`](https://seoskill.dev/docs/compare) | Before and after a date, with Google updates |
+| [`seo index`](https://seoskill.dev/docs/indexing) | Pages that lost their clicks, checked live and with Google |
+| [`seo research`](https://seoskill.dev/docs/research) | Keywords, search results, competitors and backlinks from your own key |
+| [`seo data`](https://seoskill.dev/docs/data) | Raw Search Console or Bing rows |
+| [`seo analytics`](https://seoskill.dev/docs/analytics) | Landing pages from Google Analytics or Clicky |
+| [`seo crawl`](https://seoskill.dev/docs/crawl) | Technical issues and AI agent access across a site (CLI only) |
+| [`seo internal-links`](https://seoskill.dev/docs/internal-links) | Pages that could link to a page (CLI only) |
 
-The hosted server keeps only your linked sign-ins and saved keys, encrypted,
-and no report data or logs. Read the
-[privacy policy](https://seoskill.dev/privacy) for every network boundary and
-the [telemetry page](https://seoskill.dev/telemetry) for the anonymous usage
-counts and how to turn them off.
-
-## Documentation
-
-Questions, bug reports and feature requests go through
-[GitHub Issues](https://github.com/iannuttall/seo/issues). Report suspected
-vulnerabilities privately through the process in [SECURITY.md](SECURITY.md).
-
-- [Getting started](https://seoskill.dev/docs/getting-started)
-- [Hosted MCP](https://seoskill.dev/docs/mcp)
-- [API keys](https://seoskill.dev/docs/keys)
-- [Your hosted account](https://seoskill.dev/account)
-- [CLI](https://seoskill.dev/docs/cli)
-- [Commands](https://seoskill.dev/docs)
-- [What is stored](https://seoskill.dev/docs/privacy)
-- [Privacy policy](https://seoskill.dev/privacy)
-- [Public usage stats](https://seoskill.dev/stats)
-- [Terms of use](https://seoskill.dev/terms)
-- [Contributing](CONTRIBUTING.md)
-- [Trademark and brand policy](TRADEMARKS.md)
-
-## Develop locally
-
-Most users do not need the source checkout. If you want to contribute:
-
-```sh
-git clone https://github.com/iannuttall/seo.git
-cd seo
-pnpm install
-pnpm build
-node dist/cli.js start --dry-run
-```
+Every command is also an MCP tool, such as `seo_report`. Add `--json` to any
+command when you're scripting it.
 
-Run the full quality gate before opening a pull request:
+## What it keeps
 
-```sh
-pnpm build
-pnpm typecheck
-pnpm test
-pnpm lint
-pnpm pack --dry-run
-```
+As little as possible. The hosted server keeps your linked Google accounts
+and any keys you save, encrypted. It doesn't keep your Search Console data,
+your reports or request logs. The CLI keeps your sign-in in your system
+keychain. The [privacy policy](https://seoskill.dev/privacy) has the details.
 
-Contributor architecture and report rules live in [AGENTS.md](AGENTS.md).
+## Links
 
-## License
+- [Documentation](https://seoskill.dev/docs)
+- [Cloud agents and CI](https://seoskill.dev/docs/cloud-agents)
+- [Add your own analytics source](https://github.com/iannuttall/seo-provider-template)
+- [Changelog](CHANGELOG.md) and [contributing](CONTRIBUTING.md)
+- [Questions and bugs](https://github.com/iannuttall/seo/issues)
 
-The code is available under [Apache-2.0](LICENSE). Project names and artwork are
-covered separately by the [trademark and brand policy](TRADEMARKS.md).
+Apache-2.0. The name and artwork are covered by the
+[brand policy](TRADEMARKS.md).