seo 0.3.0-beta.2 → 0.4.0

package/PRIVACY.md

@@ -3,11 +3,14 @@
 Last updated: 15 October 2026
 
 This policy covers the official `seo` command-line tool, library, MCP server,
-the hosted MCP server at seoskill.dev/mcp, and the seoskill.dev website.
+the hosted MCP server at seoskill.dev/mcp with its account page, and the
+seoskill.dev website.
 
-In short: the hosted MCP never stores your data, API keys are never stored,
-and the only thing kept about your use is an anonymous usage count (the event,
-report, agent, version and week).
+In short: the hosted MCP keeps only your linked Google accounts and any API
+keys you save, encrypted, so it can fetch your own data when you ask. It never
+keeps your Search Console or analytics data, your reports or a log of your
+requests. The only thing kept about your use is an anonymous usage
+count (the event, report, agent, version and week).
 
 The command-line tool runs on your machine. It does not create an SEO
 account, upload reports to a hosted SEO service, or send reports or connected
@@ -21,30 +24,52 @@ the work you requested. The sections below explain what each request can send.
 ## The hosted MCP server
 
 The hosted MCP server at `https://seoskill.dev/mcp` runs the same reports
-for an MCP client you connect to it. It never stores your data or your keys.
-There is no database, account or log of your data. The only thing it keeps is
-the anonymous usage count described below.
-
-- **Google sign-in.** You sign in with Google and grant read-only access to
-  Search Console and Google Analytics. The resulting Google tokens are sealed
-  (encrypted) into the tokens your MCP client keeps. The server keeps no
-  copy. Revoking the app in your
-  [Google Account connections](https://myaccount.google.com/connections)
-  stops them working.
-- **API keys.** Keys for DataForSEO and Ahrefs are optional. You can enter
-  them on the sign-in page, where they are sealed into the same tokens, or
-  send them as request headers. A key is used for the request it arrives with and is never stored.
+for an MCP client you connect to it. To do that it keeps a small store in
+Cloudflare D1 with only these things:
+
+- **A person id.** A random id created the first time you sign in with
+  Google. That first Google account is your account. There is no password.
+- **Your linked Google accounts.** The email address of each Google account
+  you link, and its refresh and access tokens. You grant read-only access to
+  Search Console and Google Analytics.
+- **Your API keys, if you save them.** A DataForSEO login and password and an
+  Ahrefs key.
+
+Every token and key is encrypted with a server key before it is written. The
+tokens are used only to fetch your own data when you or your agent ask for
+it. The token your MCP client keeps carries only your person id.
+
+The server keeps nothing else. It does not keep reports, Search Console
+or Google Analytics rows, lists of your sites, or the pages it checked.
+Request logs are turned off.
+
 - **Your data.** Search Console, Google Analytics and provider responses are
-  fetched for each request, returned to your MCP client and not kept. Pages
-  checked live are fetched for the request and not kept.
-- **Outside services.** Google answers the Google requests. The provider you
-  choose receives your research request under its own policy. Ahrefs
-  receives the domains in research rows for the free Domain Rating column.
-  Cloudflare runs the server and handles the network requests.
+  fetched for each request, returned to your MCP client and not kept. Pages checked live are fetched for the request and not kept.
+- **API key headers.** You can send `X-DataForSEO-Login`,
+  `X-DataForSEO-Password` and `X-Ahrefs-Key` headers instead of saving keys.
+  A header wins over a saved key and is used for that request only.
+- **The account page.** At [seoskill.dev/account](https://seoskill.dev/account)
+  you sign in with Google to see your linked accounts, add or remove them,
+  and save or remove keys. It sets one essential cookie that holds your
+  encrypted person id for up to 30 days.
+- **Outside services.** Google answers its own requests. The provider you
+  choose receives your research request under its own policy.
+  Ahrefs receives the domains in research rows for the free Domain Rating
+  column. Cloudflare runs the server, stores the encrypted data and handles
+  the network requests.
 - **Usage counts.** Each run sends one anonymous event to the same telemetry
   endpoint the CLI uses, with the event, report, agent, version and week. It
   never contains a site, URL, query, key, account or report data.
 
+### Delete your hosted data
+
+Sign in at [seoskill.dev/account](https://seoskill.dev/account) and choose
+**Delete everything**. It deletes your person id, linked accounts and keys,
+and revokes the Google sign-ins. Your agents will ask you to sign in again if
+you use the hosted server later. You can also revoke SEO Skill in your
+[Google Account connections](https://myaccount.google.com/connections), which
+stops the stored Google tokens working.
+
 Your MCP client and its model provider receive the results under their own
 terms.
 
@@ -61,9 +86,9 @@ read-only access to:
   access.
 
 The software uses this data to list properties, run the report you requested,
-join search or analytics evidence to crawl findings, and save local report
-history when a command supports it. It does not use Google data for advertising
-or to train general-purpose AI models.
+and join search or analytics evidence to crawl findings. It does not save
+report history. It does not use Google data for advertising or to train
+general-purpose AI models.
 
 The shared desktop OAuth client identifies the `seo` app to Google. OAuth
 tokens and API responses are returned to your machine, not to the project
@@ -80,16 +105,26 @@ site ID, sitekey, requested report type, date range, and row limit directly to
 Clicky over HTTPS. It can read the traffic data that sitekey permits. The
 project maintainer does not receive the request or response.
 
-The site ID is saved in the project profile. The sitekey uses the operating
+The site ID is saved in the local configuration. The sitekey uses the operating
 system keychain when available, with a private local file fallback. Agents and
 CI can use `SEO_CLICKY_SITEKEY` without saving it. Clicky responses are cached
 locally for up to 24 hours, and cache keys and cached responses do not contain
 the sitekey.
 
+## Bing data the software can access
+
+Bing access is optional. In the command-line tool and local MCP server, you
+save a Bing Webmaster API key with `seo providers bing connect`, or set
+`SEO_BING_API_KEY`. The key is saved in the system keychain when available,
+with a private local file fallback. Requests go directly from your machine to
+Bing over HTTPS and can read the sites that key can read. Run
+`seo providers bing disconnect` to remove the saved key. The hosted MCP
+server does not read Bing data.
+
 ## How Google data is protected
 
-The software stores project profiles, settings, OAuth tokens, cached API
-responses, logs, and saved reports in local user directories. It does not
+The software stores settings, OAuth tokens, cached API responses, and logs in
+local user directories. It does not save reports or crawls. It does not
 upload Google API responses to a hosted SEO account or project database.
 Google API requests go directly from your machine to Google over HTTPS. The
 software does not send Search Console data to a research provider. `seo
@@ -124,10 +159,10 @@ run, expired rows may remain in the local cache file until you delete them.
 Run `seo cache clear --provider google-analytics` to remove cached Google
 Analytics responses immediately. Run `seo cache clear --provider gsc` to do
 the same for Search Console. Run `seo cache clear --provider clicky` to remove
-cached Clicky responses. Project profiles and reports that you deliberately
-save remain until you delete them with the relevant command or run
-`seo reset --yes`. The reset command removes Google tokens, local
-configuration, caches, logs, histories, saved reports, and saved provider
+cached Clicky responses. Settings and saved provider credentials remain until
+you delete them with the relevant command or run `seo reset --yes`. The reset
+command removes Google tokens, local configuration, caches, logs, any
+histories or reports saved by earlier versions, and saved provider
 credentials. It removes active keychain credentials before deleting local
 files. If the keychain refuses a deletion, reset stops and tells you to unlock
 it before trying again.
@@ -300,8 +335,10 @@ copy, publish, transmit, or pass it to an agent or application yourself.
 ## Removing access and local data
 
 Use `seo auth logout` to remove local Google tokens. Use
-`seo providers dataforseo disconnect` or `seo providers ahrefs disconnect` to
-remove the corresponding saved provider credential. Environment variables are
+`seo providers dataforseo disconnect`, `seo providers ahrefs disconnect` or
+`seo providers bing disconnect` to remove the corresponding saved credential.
+To remove what the hosted MCP keeps, use **Delete everything** on the
+[account page](https://seoskill.dev/account). Environment variables are
 controlled by your shell or runtime and are not changed by these commands. Use `seo privacy` to
 inspect local paths and `seo reset --yes` to remove every saved credential and
 local file managed by the software.

package/README.md

@@ -8,7 +8,7 @@
 <h1 align="center">SEO Skill</h1>
 
 <p align="center">
-  The SEO command for AI agents. Give your agent your own Search Console and analytics data, with Google update dates beside it, and keyword data from your own provider key.
+  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">
@@ -18,8 +18,6 @@
   ·
   <a href="https://seoskill.dev/docs">Documentation</a>
   ·
-  <a href="https://seoskill.dev/docs/mcp">Hosted MCP</a>
-  ·
   <a href="https://www.npmjs.com/package/seo">npm</a>
   ·
   <a href="https://github.com/iannuttall/seo/issues">Questions</a>
@@ -43,8 +41,8 @@
 </p>
 
 Ask your agent what is happening in search and get an answer built from your
-own Search Console, Google Analytics and Clicky data, with Google update dates
-laid over it. Add your own DataForSEO or Ahrefs key when you need keyword,
+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
@@ -60,15 +58,16 @@ npm i -g seo
 seo start
 ```
 
-`seo start` signs you in with Google, lists the Search Console properties you
-can read, lets you pick a Google Analytics property, and saves a project
-profile (a local shortcut for the site and its data sources). It can also add
-the skill and the local MCP server to your agents.
+`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.
 
-Then run the main report:
+List the properties your sign-in can read, then run the main report for one:
 
 ```sh
-seo report
+seo sites
+seo report --site example.com
 ```
 
 ## Connect the hosted MCP server
@@ -81,15 +80,22 @@ 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. The server stores nothing. Your
-sign-in and any provider keys are sealed into the token your MCP client
-keeps, or sent as headers on each request. The
+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.
+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
 
@@ -100,12 +106,13 @@ on your machine, through the CLI or the local MCP server.
 | `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; the hosted tool also reads analytics landing pages |
+| `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. Commands that return rows also take `--detail summary|rows|full` and
+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.
 
@@ -117,7 +124,7 @@ The [command docs](https://seoskill.dev/docs) explain each one.
 Run the report without a section first:
 
 ```sh
-seo report
+seo report --site example.com
 ```
 
 It shows site totals against the previous period, the pages and queries that
@@ -125,33 +132,25 @@ moved, and a short count with top rows for each section. Then ask for the one
 section that matters:
 
 ```sh
-seo report --section quick-wins
+seo report --site example.com --section quick-wins
 ```
 
 The sections are `overview`, `quick-wins`, `low-ctr`, `striking-distance`,
-`second-page`, `content-decay`, `cannibalization` and `traffic-drop`. Page
-sections check their top 20 URLs live and merge same-site redirects.
+`second-page`, `content-decay`, `cannibalization`, `traffic-drop` and `bing`.
+Page sections check their top 20 URLs live and merge same-site redirects.
 
 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 --date 2026-09-15
+seo compare --site example.com --date 2026-09-15
 seo page --url https://example.com/pricing
 ```
 
 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.
 
-Use `--project` when you have more than one saved project, or `--site` to work
-without one:
-
-```sh
-seo report --project example
-seo report --site sc-domain:example.com
-```
-
 ## Add keyword and competitor data
 
 Research uses your own provider account, so each request costs your credits
@@ -162,7 +161,9 @@ seo providers dataforseo connect
 seo providers ahrefs connect
 ```
 
-Then ask for one action:
+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:
 
 ```sh
 seo research keyword_metrics --keywords "invoice software,invoice template"
@@ -177,18 +178,44 @@ 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.
 
+## Add Bing Webmaster Tools
+
+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):
+
+```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.
+
 ## Add your analytics
 
-Google Analytics comes with your Google sign-in. Pick the property during
-`seo start`.
+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
+```
 
 Clicky is available through the
 [Clicky provider package](https://github.com/iannuttall/seoskill-clicky-provider).
-Install it, then attach its site ID to a project with `seo start`:
+Install it, then connect a site with its Clicky site ID:
 
 ```sh
 seo providers install @seoskill/clicky-provider
-seo start
+seo analytics clicky connect --site-id 12345
 ```
 
 The hosted server reads Google Analytics only. Clicky runs on your machine,
@@ -207,7 +234,8 @@ evidence rules. If you skipped it during `seo start`, add it now:
 seo skill install
 ```
 
-To add the local MCP server to Codex, Claude Code, Claude Desktop or Cursor:
+`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:
 
 ```sh
 seo mcp install
@@ -227,7 +255,7 @@ installed provider packages.
 
 - Missing, partial, capped and filtered data is named. It never becomes a zero
   or an all-clear.
-- Search Console, analytics, live page checks and provider estimates stay
+- 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.
@@ -238,20 +266,31 @@ installed provider packages.
 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 Webmaster,
+tracking, programmatic SEO, AI search readiness, llms.txt, Bing links,
 IndexNow, Semrush, local search, server logs and the monthly and narrative
-reports. The old research reports became `seo research`. The
-[changelog](CHANGELOG.md) lists every old name and where it went.
+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, so pass `--project` or
-`--site` in unattended runs.
+Add `--json` to any command. JSON mode never prompts. Pass `--site` every
+time.
 
 ```sh
 seo report --site sc-domain:example.com --json
@@ -303,8 +342,9 @@ working example.
 ## Local data and Google access
 
 Google tokens use your system keychain, with a private `0600` file fallback on
-headless machines. Project profiles, crawls and caches stay in your local
-config directory. A command still reaches the network when it needs Google,
+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.
 
 ```sh
@@ -314,7 +354,8 @@ seo auth logout --all
 seo reset
 ```
 
-The hosted server keeps no data at all. Read the
+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.
@@ -328,6 +369,7 @@ 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)

package/SECURITY.md

@@ -19,8 +19,8 @@ questions and non-sensitive bugs.
 
 ## Local data and credentials
 
-`seo` is local-first. Project profiles, Google OAuth metadata, crawl reports,
-and caches stay on the machine running the command. Access and refresh tokens
+`seo` is local-first. Settings, Google OAuth metadata, provider keys and
+caches stay on the machine running the command. Access and refresh tokens
 use the operating-system keychain when enabled; fallback token files and local
 credential files use private file permissions.