seo 0.1.0 → 0.2.0

package/PRIVACY.md

@@ -3,7 +3,7 @@
 Last updated: 10 July 2026
 
 This policy covers the official `seo` command-line tool, library, MCP server,
-and the seoskills.dev website.
+and the seoskill.dev website.
 
 The current software runs on your machine. It does not create an SEO account,
 upload reports to an SEO service, or send your Google data to the project
@@ -57,7 +57,7 @@ The CLI does not include project-controlled usage telemetry. Installing the
 package through npm or using GitHub is covered by the policies of those
 services.
 
-The seoskills.dev host and security provider may process normal web request
+The seoskill.dev host and security provider may process normal web request
 data such as an IP address, user agent, requested path, and timestamp. Website
 logs do not include the reports, tokens, or Google API responses stored by the
 local software.

package/README.md

@@ -1,23 +1,23 @@
 <p align="center">
-  <img src="apps/web/public/favicon.svg" alt="SEO Skills CLI" width="72" height="72">
+  <img src="apps/web/public/favicon.svg" alt="SEO Skill" width="72" height="72">
 </p>
 
-<h1 align="center">SEO Skills CLI</h1>
+<h1 align="center">SEO Skill</h1>
 
 <p align="center">
-  Find what is costing you traffic, which pages are closest to more clicks, and what to fix first. Local SEO tools and skills for people, AI agents, and CI.
+  The only SEO skill your agent needs. 50+ SEO audit tools through a local CLI and MCP server, using your own crawl, Search Console, and GA4 data.
 </p>
 
 <p align="center">
   <a href="#quick-start">Get started</a>
   ·
-  <a href="https://seoskills.dev/docs">Documentation</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://seoskills.dev/privacy">Privacy</a>
+  <a href="https://seoskill.dev/privacy">Privacy</a>
   ·
   <a href="SECURITY.md">Security</a>
   ·
@@ -35,19 +35,26 @@
   <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>
 
-`seo` turns a local crawl and your own search data into work you can inspect
-and ship. Find technical blockers, recover search demand, improve pages already
-close to more clicks, and catch regressions after a release.
+The `seo` command runs a full SEO audit from your terminal, turning a local
+crawl and your own search data into work you can inspect and ship. Find
+technical blockers, recover search demand, improve pages already close to more
+clicks, and catch regressions after a release.
+
+## Who this is for
+
+- People running their own sites who want a clear audit and a ranked list of
+  fixes, without learning a heavy dashboard.
+- AI agents that need real crawl, Search Console, and GA4 evidence through MCP
+  and one packaged SEO skill instead of screenshots or guesses.
+- Developers who want to embed the same report engine in a script, a CI job, or
+  a TypeScript app.
 
 ## Quick start
 
 Requires Node 22 or newer.
 
-Install the command once, then add the skills when an agent will use it:
-
 ```sh
 npm i -g seo
-npx skills add iannuttall/seo --all
 seo start
 seo report
 ```
@@ -57,13 +64,49 @@ optional GA4 property, and a local project profile. Public releases can include
 the shared Google app. If it is unavailable in your build, setup guides you
 through adding your own desktop OAuth client.
 
-That is the normal path. `seo` is then available in every terminal, script,
-CI job, and local MCP client on the machine.
+That is the normal path. The `seo` command is then available in every terminal,
+script, CI job, and local MCP client on the machine.
 
 The main report uses the evidence you have, explains what it could not check,
 and recommends a short list of follow-up commands. You can start with a local
 technical report before connecting Google.
 
+Running `seo help` shows the shape of the tool:
+
+```txt
+seo v0.2.0
+
+Human-friendly SEO reports first, power tools when you need them.
+
+Start here
+  seo start                                Connect Google and save a project profile
+  seo report                               Run the main SEO report for the default project
+  seo report --site sc-domain:example.com  Run without a profile
+  seo report --url https://example.com     Start with a local technical report
+
+Projects
+  seo projects list  List saved project profiles
+  seo projects add   Create or update a project profile
+  seo sites          List Search Console properties
+  seo doctor         Check local auth and config
+
+Act on a report
+  seo refresh-priorities  Rank the next best SEO actions
+  seo quick-wins          Find ranking 4-10 low-CTR wins
+  seo second-page         Investigate URLs averaging positions 10-20
+  seo technical-watch     Crawl and index-monitor a site
+
+Agent and power tools
+  seo report --json    Run the main report as structured JSON
+  seo export diagnose  Export report data to CSV
+  seo mcp install      Install SEO tools into MCP clients
+  seo skill list       Show the packaged SEO skill
+  seo reports list     Discover every structured report
+
+Use `seo help <command>` or `seo <command> --help` for command help.
+Use `seo help all` for the longer command list.
+```
+
 ## What you get
 
 - Find technical blockers across metadata, links, indexability, canonicals,
@@ -78,6 +121,19 @@ technical report before connecting Google.
 - Give scripts and agents deterministic JSON, Markdown, stable rule IDs, and a
   compact local MCP surface.
 
+## How the reports stay honest
+
+The point of a report is to be defensible, so the design keeps a few rules:
+
+- Observed evidence stays separate from derived findings and recommended
+  actions. You can always see the crawl row or provider row behind a claim.
+- Partial data is never reported as a zero. A capped, filtered, or sampled
+  source says so, and it cannot support a definitive all-clear.
+- Heuristics are labeled as heuristics. A convention or threshold is not
+  presented as a search-engine rule.
+- Each recommendation comes with a way to check that the fix worked, rather than
+  a promise about rankings or traffic.
+
 ## Everyday use
 
 `seo start` can save a project profile, which is a local shortcut for a site,
@@ -116,7 +172,7 @@ Run `seo help` for the short path or `seo help all` for the full command list.
 
 ## Crawl a site
 
-Run a readable technical crawl:
+Run a readable technical crawl, the base of any technical SEO audit:
 
 ```sh
 seo crawl https://example.com --format pretty
@@ -167,7 +223,7 @@ browser or a copied local token:
     SEO_GOOGLE_SERVICE_ACCOUNT_JSON: ${{ secrets.SEO_GOOGLE_SERVICE_ACCOUNT_JSON }}
 ```
 
-The [Google data guide](https://seoskills.dev/docs/google) covers Search
+The [Google data guide](https://seoskill.dev/docs/google) covers Search
 Console and GA4 permissions, mounted secret files, and how to check the active
 identity safely.
 
@@ -186,13 +242,18 @@ drift.
 
 ## Use it with AI agents
 
-Agents work best with both parts of the project. The `seo` package runs the
-reports. The skills teach an agent which report to choose, how to read it, and
-what to verify before changing a site.
+Your agent carries one short SEO skill, and the CLI and MCP server do the
+heavy lifting. The skill teaches an agent how to discover the 50+ audit and
+report tools at runtime, and the agent asks the CLI for the detail on each
+tool only when it is about to run it. You get the whole toolkit without fifty
+skill files sitting in the context window on every session.
+
+`seo start` offers to install the SEO skill during setup. In an agent-managed
+environment, add it yourself with the standard installer:
 
 ```sh
 npm i -g seo
-npx skills add iannuttall/seo --all
+npx skills add iannuttall/seo
 ```
 
 Then install the local stdio MCP server into a supported client:
@@ -217,22 +278,24 @@ configuration or testing:
 seo mcp serve
 ```
 
-The repository ships the focused instructions under `skills/`. They teach
-agents when to discover reports, inspect evidence, and request a smaller
-follow-up instead of loading a giant result into context.
+The repository ships one skill under `skills/seo`. It is a router: it teaches an
+agent to discover reports, describe one to load its depth at runtime, inspect
+the evidence, and request a smaller follow-up instead of loading a giant result
+into context. Per-report guidance lives in the registry and is fetched with
+`seo reports describe <id> --json`, so it never drifts from the skill.
 
-The npm package includes the same files for local inspection:
+The npm package includes the same file for local inspection:
 
 ```sh
-seo skills list
-seo skills path quick-wins
+seo skill list
+seo skill path seo
 ```
 
-Agents can also discover the complete skill catalog from
-`https://seoskills.dev/.well-known/agent-skills/index.json`. Each entry links to
+Agents can also discover the canonical skill from
+`https://seoskill.dev/.well-known/agent-skills/index.json`. The entry links to
 the canonical skill instructions and includes a content digest for verification.
 
-See [MCP and agents](https://seoskills.dev/docs/agents) for setup and tool
+See [MCP and agents](https://seoskill.dev/docs/agents) for setup and tool
 details.
 
 ## Use it as a library
@@ -282,13 +345,13 @@ console.log(crawl.summary, crawl.issueGroups)
 The main `seo` export contains the report, provider, crawler, storage, and
 rendering APIs. `seo/mcp` exposes report discovery, report execution, and the
 embeddable MCP server. See the [TypeScript library
-guide](https://seoskills.dev/docs/library) for structured error handling,
+guide](https://seoskill.dev/docs/library) for structured error handling,
 local Google access, and more examples.
 
 ## Local data and Google access
 
 Google OAuth tokens use your system keychain when it is available. On a
-headless machine or a locked keychain, SEO Skills CLI falls back to a private
+headless machine or a locked keychain, the CLI falls back to a private
 `0600` file in your user config directory. Project profiles, crawl reports, and
 provider caches are also local. Use these commands to inspect or remove them:
 
@@ -303,24 +366,54 @@ seo reset
 `seo auth storage --keychain` or `seo auth storage --file`.
 
 Power users can bring their own Google OAuth client. See
-[getting started](https://seoskills.dev/docs/getting-started) for the available
+[getting started](https://seoskill.dev/docs/getting-started) for the available
 auth paths.
 
+## Common questions
+
+### Does my site data stay on my machine?
+
+Yes. Reports, project profiles, Google tokens, crawls, and caches stay in your
+local config directory. The CLI only makes the network requests needed to fetch
+your site and call the Google APIs you connect. There is no hosted backend,
+account, or telemetry service.
+
+### Do I need a Google API key?
+
+No. `seo start` uses a normal Google sign-in for read-only Search Console and
+GA4 access. Public releases can include a shared desktop OAuth client, and if
+your build does not have one, setup helps you add your own. You can also run a
+local technical crawl with no Google connection at all.
+
+### What does it cost?
+
+The `seo` package is free and open source under Apache-2.0. It calls Google APIs
+you already have access to, so there is no separate subscription. Your own API
+quotas still apply.
+
+### How is this different from a paid SEO tool?
+
+A hosted SEO tool keeps your data on its servers and shows you a dashboard. This
+runs on your machine, works from your own crawl and Google data, and returns
+structured evidence your agent can read and act on. Every finding shows the
+evidence behind it and a way to verify a fix, so you are not trusting a score
+you cannot inspect.
+
 ## 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://seoskills.dev/docs/getting-started)
-- [CLI commands](https://seoskills.dev/docs/cli)
-- [Crawler](https://seoskills.dev/docs/crawler)
-- [Reports and data](https://seoskills.dev/docs/reports)
-- [MCP and agents](https://seoskills.dev/docs/agents)
-- [AI-search evidence](https://seoskills.dev/docs/ai-search)
-- [Privacy policy](https://seoskills.dev/privacy)
-- [Terms of use](https://seoskills.dev/terms)
-- [Security policy](https://seoskills.dev/security)
+- [Getting started](https://seoskill.dev/docs/getting-started)
+- [CLI commands](https://seoskill.dev/docs/cli)
+- [Crawler](https://seoskill.dev/docs/crawler)
+- [Reports and data](https://seoskill.dev/docs/reports)
+- [MCP and agents](https://seoskill.dev/docs/agents)
+- [AI-search evidence](https://seoskill.dev/docs/ai-search)
+- [Privacy policy](https://seoskill.dev/privacy)
+- [Terms of use](https://seoskill.dev/terms)
+- [Security policy](https://seoskill.dev/security)
 - [Contributing](CONTRIBUTING.md)
 - [Trademark and brand policy](TRADEMARKS.md)
 

package/TERMS.md

@@ -3,7 +3,7 @@
 Last updated: 10 July 2026
 
 These terms cover the official `seo` command-line tool, library, MCP server,
-documentation, and seoskills.dev website.
+documentation, and seoskill.dev website.
 
 ## Open source licence
 
@@ -58,7 +58,7 @@ You are responsible for protecting local tokens, configuration, caches,
 reports, exports, backups, and environment variables. Keep secrets out of
 public issues, logs, screenshots, repositories, and shared report files.
 
-The [privacy policy](https://seoskills.dev/privacy) explains what the software
+The [privacy policy](https://seoskill.dev/privacy) explains what the software
 stores and how to remove it.
 
 ## Availability and changes

package/TRADEMARKS.md

@@ -3,14 +3,18 @@
 The source code is available under Apache-2.0. That license does not grant a
 right to present another product or service as the official `seo` project.
 
-This policy covers the SEO Skills name, seoskills.dev, project artwork, and the
-`seo` name when it refers specifically to this package and project. It does not
-claim ownership of the generic term "SEO."
+This policy covers this project's identity: the name `seo` when it refers to
+this specific package and project, the tagline "The SEO command for AI agents",
+the logo and project artwork, and seoskill.dev.
+
+"seo" is a generic term for search engine optimization. This policy claims no
+rights over that generic use. It covers only the project's name in context, its
+logo, its branding, and its tagline.
 
 ## Uses that are fine
 
 - Truthfully saying that software uses, supports, or is based on `seo`.
-- Linking to the official repository or seoskills.dev.
+- Linking to the official repository or seoskill.dev.
 - Keeping required attribution and notices in copies or forks.
 - Describing a fork as an unofficial fork, provided the distinction is clear.
 
@@ -22,6 +26,6 @@ service, domain, package, event, or merchandise.
 
 Do not imply endorsement, partnership, or official status. Forks and hosted
 versions must use a distinct name and visual identity, and must not create
-confusion with the npm package, repository, or seoskills.dev.
+confusion with the npm package, repository, or seoskill.dev.
 
 Nominative and other uses allowed by applicable law remain allowed.