seo 0.13.3 → 0.14.0

package/dist/provider-sdk.d.ts

@@ -1,5 +1,4 @@
 
-//#region packages/core/src/provider-extensions/sdk.d.ts
 export declare const SEO_PROVIDER_API_VERSION: 1;
 export type SeoProviderApiVersion = typeof SEO_PROVIDER_API_VERSION;
 export type SeoProviderKind = 'traffic-analytics' | 'search-results' | 'keyword-data' | 'domain-data' | 'link-data' | 'local-search' | 'ai-data' | 'other';
@@ -199,5 +198,4 @@ export interface SeoProviderHost {
 export type SeoProviderActivate = (host: SeoProviderHost) => void | Promise<void>;
 export type SeoAnalyticsConnection = SeoProviderConnection;
 export type SeoAnalyticsLandingPageResult = SeoLandingPageVisitsResult;
-//#endregion
 //# sourceMappingURL=provider-sdk.d.ts.map

package/dist/provider-sdk.js

@@ -1,7 +1,6 @@
 import { createRequire as __seoCreateRequire } from 'node:module'; const require = __seoCreateRequire(import.meta.url);
-//#region packages/core/src/provider-extensions/sdk.ts
+// packages/core/src/provider-extensions/sdk.ts
 const SEO_PROVIDER_API_VERSION = 1;
-//#endregion
 export { SEO_PROVIDER_API_VERSION };
 
 //# sourceMappingURL=provider-sdk.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seo",
-  "version": "0.13.3",
+  "version": "0.14.0",
   "mcpName": "dev.seoskill/seo",
   "description": "The SEO command for AI agents: a free Google Search Console MCP server and CLI. Reads your real Search Console, Google Analytics and Bing data for traffic drops, quick wins, content decay, cannibalization and indexing, plus DataForSEO and Ahrefs keyword research.",
   "type": "module",
@@ -57,6 +57,7 @@
   "files": [
     "dist",
     "skills",
+    "site-kit",
     "evals",
     "PRIVACY.md",
     "SECURITY.md",
@@ -117,7 +118,7 @@
     "jsonc-parser": "^3.3.1",
     "libsql": "^0.5.29",
     "lighthouse": "13.5.0",
-    "linkedom": "^0.18.13",
+    "linkedom": "^0.18.14",
     "open": "^11.0.4",
     "p-queue": "^9.3.5",
     "p-retry": "^8.0.1",
@@ -134,10 +135,10 @@
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.15",
+    "@biomejs/biome": "^2.6.2",
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "tsdown": "^0.23.1",
-    "turbo": "^2.11.8",
+    "tsdown": "^0.23.2",
+    "turbo": "^2.11.10",
     "typescript": "^6.0.3"
   }
 }

package/site-kit/README.md

@@ -0,0 +1,13 @@
+# Site kit
+
+The files behind `seo site`. They ship in the npm package.
+
+- `starter/` is the Astro site on Cloudflare that `seo site new <folder>`
+  copies. `gitignore` becomes `.gitignore` in the copy, because npm drops
+  `.gitignore` files from packages.
+- `guide/` holds one Markdown file per step that `seo site guide <step>`
+  prints. The list and order of steps is `SITE_GUIDE_STEPS` in
+  `packages/cli/src/commands/site.ts`.
+
+`seo site check` lives in `packages/core/src/site-check`. Change the starter
+and the check together: the starter's own build must pass the check.

package/site-kit/guide/build.md

@@ -0,0 +1,70 @@
+# Step 5 of 10: build
+
+Goal: the site runs from the starter, deploys to a private preview on
+Cloudflare and passes `seo site check`.
+
+## Start the site
+
+If the project does not exist yet, create it in a new folder:
+
+```sh
+seo site new <folder> --name "<Site name>" --domain <domain>
+cd <folder>
+pnpm build
+```
+
+The starter is a static Astro site on Cloudflare Workers static assets. It
+already does the parts every page needs:
+
+- One layout (`src/layouts/Base.astro`) writes the title, description,
+  canonical, sharing tags and one JSON-LD graph per page.
+- A Markdown copy of every page, `llms.txt` and `agent-routes.json`, from
+  `agentMarkdown()`.
+- A sharing image for every page, drawn at build time from its H1.
+- A sitemap index with files of up to 5,000 URLs, listed in `robots.txt`.
+- `robots.txt` open to every crawler, with a Content-Signal line. Set
+  `aiTraining` in `site.config.json` to the person's choice.
+- `pnpm build` ends with `seo site check`, so a broken build never ships.
+
+## Use the components
+
+The starter has a clean blank theme for the person to make their own.
+`AGENTS.md` lists the components: header, footer, page header,
+breadcrumbs, section heading, cards with a destination label, fact table,
+FAQ accordion, buttons, form inputs, code block and `site-prose` text.
+Build every page from them. Make a new component only for something none
+of them shows, in the same style: token classes from
+`src/styles/globals.css`, muted panels, no borders, shadows or raw
+colours. Change the look by changing the tokens, never page by page.
+
+## Deploy a private preview
+
+1. Create a GitHub repository and push: `gh repo create --private --source
+   . --push`.
+2. In the Cloudflare dashboard, open Workers & Pages, create an
+   application, import the repository and keep the build command
+   `pnpm build`. Set the deploy command to `pnpm run deploy`.
+3. Until launch the site lives on its workers.dev address. Protect it with
+   Cloudflare Access (in the Worker's settings, under Domains & Routes,
+   turn on Cloudflare Access for workers.dev) so only the person can open
+   it. Never use noindex for this: it is too easy to forget.
+4. Send the person the preview link and a screenshot of the home page on
+   desktop and phone.
+
+## Rules
+
+- Static first. Run code on the server only for a route that needs it,
+  such as a search box over a large dataset, and keep it under `/api/*`.
+  Never set `run_worker_first` for anything else.
+- Every word of content and the H1 is in the built HTML. Most AI systems
+  do not run JavaScript.
+- One URL form everywhere: no trailing slash, and canonicals drop query
+  strings.
+- Missing pages return a real 404. Never redirect them to the home page.
+- Keep the data in committed JSON or R2. Never query a database on a page
+  request.
+
+Done when: the preview is live behind Cloudflare Access, `pnpm build`
+passes and the person has seen the screenshots.
+
+Next: `seo site guide golden-page`

package/site-kit/guide/data.md

@@ -0,0 +1,49 @@
+# Step 3 of 10: data
+
+Goal: a clean dataset that is hard to copy, with a source and a checked
+date for every fact, rebuilt from scratch by one command.
+
+The data is what makes the site worth visiting. A site built on one copied
+dataset gets no traction. Data that is combined, cleaned and worked out
+into something new does.
+
+## What the agent does
+
+1. Find sources in this order: government and open data, then public pages
+   that can be collected, then data people add themselves. Check each
+   source's licence and terms before using it.
+2. Write the import as a script that gives the same result every run, such
+   as `scripts/build-data.mjs`, from raw files in `data/raw` to JSON in
+   `src/data`. It reports any name it cannot match instead of guessing.
+3. Join and enrich the sources: clean names, units and plurals, add places
+   and work out comparisons or a score. Formatting is a quality signal, so
+   "LLC" never becomes "Llc".
+4. List every source in `src/data/sources.json` with its URL and the date
+   it was checked. `pnpm data:refresh` records each source's ETag, date and
+   hash, so a change opens a pull request.
+5. Add a rule to `scripts/validate-data.mjs` for each kind of mistake the
+   data can contain, and run `pnpm data:validate`.
+6. Replace the example parks data and the parks pages as the plan says.
+
+## What the person does
+
+- Decide how often the data is refreshed. Ask how often it changes at the
+  source before anything is built: daily for tides, yearly for statistics.
+  Set the cron in `.github/workflows/refresh-data.yml` to match.
+- Spot-check 20 rows like an expert in the subject.
+
+## Rules
+
+- Keep an unknown value unknown. Never guess opening hours, rules or
+  prices. Store facts and work totals out from them.
+- Never use a competitor as the source.
+- Money and health numbers change only through a pull request a person
+  reviews. The refresh workflow does this for you.
+- A score or index the site owns, explained on a methodology page, makes
+  pages worth linking to.
+
+Done when: the dataset builds from nothing with one command, every fact
+has a source and a checked date, `pnpm data:validate` passes and the
+refresh workflow is scheduled.
+
+Next: `seo site guide plan`

package/site-kit/guide/golden-page.md

@@ -0,0 +1,50 @@
+# Step 6 of 10: golden page
+
+Goal: one page that is the best answer on the web for its search, built
+from real data before any template exists.
+
+## What the agent does
+
+1. Build the first page of the main page type with real data, in the page
+   template the plan names. The starter's park page
+   (`src/pages/parks/[slug].astro`) shows the shape.
+2. Take screenshots on desktop, at phone width and in dark mode. Review
+   them against the rules below before the person sees them.
+3. Show the person the screenshots and the preview link, then change the
+   page from their feedback until they approve it.
+
+## What the person does
+
+Judge the page as a user, not as a builder. Do I know what this is at a
+glance? Does it answer my question? Is every part there for a reason?
+Would I send it to a friend who asked?
+
+## How a good page is laid out
+
+- A clear H1 and a short answer at the top that makes sense on its own.
+  Never "see below".
+- The tool or the main data next, then a well designed table of the
+  details.
+- A fact block for each set of facts, with the source and the checked date
+  (`src/components/FactTable.astro`).
+- Questions people really ask, answered on the page. The FAQ markup
+  repeats them word for word, which `seo site check` tests.
+- Links to related pages in the body, with words that name the page they
+  lead to. One link per target per page, never in the H1.
+- Assumptions and caveats at the bottom, in plain words.
+
+Charts, maps and calculators earn their place when they help. Every chart
+also has its data in a table and a sentence that says what it shows.
+
+## Design rules
+
+Simple and quiet. The system font or Inter, plenty of space, one link
+colour. `seo site check` fails the build on uppercase or letter-spaced
+labels, gradients, shadows, coloured left borders and card grids wider
+than two columns. Also avoid stat boxes, eyebrow labels above headings and
+slogans made of three short phrases. Attention to detail is what
+separates a good page: capitals, units, plurals and empty states.
+
+Done when: the person approves the page and `pnpm build` passes.
+
+Next: `seo site guide writing`

package/site-kit/guide/grow.md

@@ -0,0 +1,58 @@
+# Step 10 of 10: grow
+
+Goal: know what is working from the site's own data, improve one thing at
+a time, and keep the data current with minutes of the person's time a
+week.
+
+## Measure every week
+
+Search Console data starts a few days after launch. Run the report each
+week and treat each section as a list to review, never a forecast:
+
+```sh
+seo report --site <domain>
+seo report --site <domain> --section quick-wins
+seo report --site <domain> --section striking-distance
+seo report --site <domain> --section ai-queries
+seo index --site <domain>
+```
+
+- Quick wins and low CTR: pages near the top with fewer clicks than their
+  position should get. Review the title and description.
+- Striking distance and second page: pages close to page one. Improve the
+  section that answers the search.
+- AI queries: long questions people ask, which may need a section or an
+  FAQ answer.
+- Content decay and traffic drop: what lost clicks, and the Google updates
+  around that date.
+- `seo index`: why Google left pages out of its index.
+
+Use `seo page --url <url>` for one page's searches and status. Your own
+Search Console data is the only data that is about your site. Keyword
+tools are estimates.
+
+## Change one thing at a time
+
+Note the date and what changed. Compare equal windows four and eight weeks
+later with `seo compare --site <domain> --date <date>`. A change in the
+same week as a Google update proves nothing on its own.
+
+## Keep the data current
+
+- The refresh workflow opens a pull request when a source changes. The
+  person checks the numbers and merges it.
+- When a refresh fails, find out why and fix the import, then let the next
+  run open the pull request.
+
+## Become known
+
+Keep the name and description the same on the site, in its JSON-LD and on
+every profile. Publish the site's own data and statistics, because those
+are what people link to and AI answers cite. Never buy links or post fake
+mentions.
+
+At six months, a steady few hundred visits a day means keep going. Much
+less means rebuild it smaller and better, or try the next idea.
+
+Done when: the weekly report runs, and each item has an action or a clear
+"no action".

package/site-kit/guide/launch.md

@@ -0,0 +1,55 @@
+# Step 9 of 10: launch
+
+Goal: the site is live on its domain, Google and Bing know about it, and
+the most important pages are found quickly.
+
+## What the agent does
+
+1. Add the domain to `wrangler.jsonc` and push:
+
+   ```jsonc
+   "routes": [{ "pattern": "<domain>", "custom_domain": true }]
+   ```
+
+   Redirect `www` to the bare domain with a Cloudflare redirect rule.
+   Take Cloudflare Access off the live domain.
+2. Add the two Markdown rewrite rules, so an agent that asks for
+   `Accept: text/markdown` at a normal URL gets the Markdown copy. Print
+   them with `pnpm rewrites` and add them in the Cloudflare dashboard under
+   Rules, URL rewrite. They run before the site, so no code runs per
+   request.
+3. Check production: the home page, a page of each type, `robots.txt`,
+   `sitemap.xml`, `llms.txt`, a sharing image, a 404 and a Markdown
+   request:
+
+   ```sh
+   seo crawl --url https://<domain>
+   curl -sI -H "Accept: text/markdown" https://<domain>/
+   ```
+
+4. From now on `pnpm run deploy` (the Cloudflare deploy command) sends the
+   pages that changed to IndexNow after each deploy.
+5. Pick the 100 most important URLs: hubs, the pages with the most data
+   and the pages that link to everything else. Check each one is built,
+   canonical and in a sitemap.
+
+## What the person does
+
+1. Add the domain to Google Search Console as a Domain property and
+   verify it through Cloudflare. Submit `https://<domain>/sitemap.xml`.
+2. Import the site into Bing Webmaster Tools from Search Console.
+3. Add Clicky, on the production domain only.
+4. Run `seo start` again if the new property should show up in SEO Skill.
+
+## Rules
+
+- Publish every page at once. A site built for people does not drip feed
+  pages.
+- Found is not indexed. Expect impressions within days if the site is
+  good, and judge it at six months.
+- Never change a live URL without a 301 to the closest page.
+
+Done when: the domain serves the site, Search Console and Bing have the
+sitemap, and `seo crawl` reports no errors.
+
+Next: `seo site guide grow`

package/site-kit/guide/market.md

@@ -0,0 +1,57 @@
+# Step 2 of 10: market
+
+Goal: a niche with real search demand and data the site can own, where the
+pages that rank today are weak. The step ends with a plan file and a go or
+no-go from the person.
+
+## What the agent does
+
+1. Ask the person for the idea, in their words. Good ideas come from their
+   own life and hobbies, open data, forums, and sites that look weak.
+2. Find the head term and its modifiers. Searches usually take the shape
+   head term plus modifier, such as "{club} {season} home shirt".
+3. Read the live search results for each pattern: who ranks, what kind of
+   page wins (tool, list, directory item, guide) and how strong those sites
+   look.
+4. With a keyword data key, get the numbers:
+
+   ```sh
+   seo research keyword_metrics --keywords "<term>,<term>"
+   seo research serp --keywords "<head term>"
+   seo research competitors --target <a competitor domain>
+   seo research ranked_keywords --target <a competitor domain>
+   ```
+
+   Then look at the competitors of those competitors for pockets of
+   demand. Without a key, use the search results, autocomplete and "people
+   also ask", and say that the volumes are unknown.
+5. Write `plan.md` in the project with the head terms, the modifiers, who
+   ranks, the data sources, how often the data changes, the page types and
+   a page count estimate.
+
+## What the person does
+
+Read `plan.md` and say go or no-go. Their judgement of the market matters
+more than any number.
+
+## Signs a market is winnable
+
+- Forum threads, thin directories or old pages in the top results.
+- Sites with few links and low authority ranking on page one.
+- Searches with buyers behind them. 100 searches from people about to buy
+  beat 4,400 from people who want something free. A real cost per click
+  shows the market pays.
+
+## Walk away when
+
+- The data is too hard to get, too hard to keep current or too costly to
+  host.
+- Every result is a household brand with years of links.
+- The only pages you could make are thin rewrites of one source.
+
+Build five ideas to find one that works. A quiet, boring market is fine.
+
+Done when: `plan.md` names the head terms, the page types, the data
+sources and a page count, and the person said go.
+
+Next: `seo site guide data`

package/site-kit/guide/plan.md

@@ -0,0 +1,49 @@
+# Step 4 of 10: plan
+
+Goal: a page list where every page has real demand and one clear job, and
+the domain to put it on.
+
+## What the agent does
+
+1. Map each search pattern to a page type and a URL pattern.
+2. Check the demand for each page type before building it. With a keyword
+   data key, run `seo research keyword_metrics` on a sample of each
+   pattern. Without one, check that the search results show pages of that
+   type.
+3. Group searches that share the same top results into one page, so pages
+   never compete with each other.
+4. When the data allows two sizes, propose both (for example about 700
+   pages or about 9,000) and let the person choose by risk.
+5. Add a route list to `plan.md`: page type, URL pattern, target search
+   pattern and expected count.
+6. Suggest three domains: two words, no hyphens, about the subject. Check
+   they are free on Cloudflare Registrar.
+
+## What the person does
+
+Approve the page list and the URL pattern, then buy the domain on
+Cloudflare Registrar. Then put the domain in `site.config.json`.
+
+## Rules
+
+- Use the smallest page type that fully answers the search: a tool, a
+  landing page, then a guide.
+- Every search intent gets one URL. Never make a second page for the same
+  job.
+- Small and focused wins: hundreds of rich pages, never tens of thousands
+  of thin ones. Directories are the exception, because people search for
+  each item by name.
+- Long variants of a search become sections on one strong page. They do
+  not get thin pages of their own.
+- Never make one page per question or per wording of a search. Google
+  treats that as scaled content abuse.
+- Build a page only when the data has enough to make it useful. A URL that
+  does not qualify is never built.
+- URLs are lowercase and lead with the subject, one or two folders deep,
+  with no IDs, no source names and no trailing slash.
+- Hub pages are real pages with their own data, not lists of 500 links.
+
+Done when: `plan.md` has the route list, the person approved it, and the
+domain is bought and set in `site.config.json`.
+
+Next: `seo site guide build`

package/site-kit/guide/scale.md

@@ -0,0 +1,41 @@
+# Step 8 of 10: scale
+
+Goal: every page as good as the golden page.
+
+## What the agent does
+
+1. Turn the golden page into the template for its page type. Each block
+   shows only when the data has enough for it.
+2. Build every page, then screenshot a sample of each page type: the
+   pages with the most data, the least data and the strangest data.
+3. Review the sample with a second agent that did not build it.
+4. Link the pages in the build: hubs to their pages, pages to their
+   siblings, and every page within three clicks of the home page.
+   `seo site check` fails on pages nothing links to.
+5. Update `llms.config.mjs` so `llms.txt` lists the hubs and page types.
+
+## What the person does
+
+Review the sample from every page type, most of all the pages with the
+least data. A thin page gets better data, gets merged into a stronger page
+or is not built.
+
+## Rules
+
+- Fix a problem in the template or the data, never page by page. Fixing
+  pages one at a time hides the real fault.
+- Reuse the starter's components. Do not invent a new one for each page
+  type.
+- Rigid templates with thin data make bad pages. Leave a block out rather
+  than fill it with filler.
+- `seo site check` checks every page before deploy: titles and
+  descriptions present, unique and the right length, one H1, canonicals,
+  JSON-LD, FAQ markup that matches the page, links that work, every page in
+  a sitemap, no noindex, a sharing image and a Markdown copy for each page,
+  the copy and design rules, and a source and date on every fact block.
+  It stops at 10,000 pages.
+
+Done when: a random sample of pages passes the person's review and
+`pnpm build` passes.
+
+Next: `seo site guide launch`

package/site-kit/guide/setup.md

@@ -0,0 +1,59 @@
+# Step 1 of 10: setup
+
+Goal: the person has every account the site needs, signed in on this
+machine, and knows what each one costs.
+
+Work through this with the person one account at a time. For each one, say
+where to click, what it costs and what to paste back. Logins that open a
+browser come before API keys. Never ask for a password, and never ask the
+person to paste a key into the chat. Keys go into the tool that uses them.
+
+## Check the machine
+
+Check for Node.js 22.12 or newer, pnpm and git, and install what is
+missing. Then install `seo`:
+
+```sh
+node --version
+pnpm --version || npm i -g pnpm
+git --version
+npm i -g seo
+```
+
+## Sign in to each account, in this order
+
+| Order | Account | How | Cost |
+| --- | --- | --- | --- |
+| 1 | GitHub | `gh auth login`, then choose the browser login | Free |
+| 2 | Cloudflare | `npx wrangler login` | The free plan is enough |
+| 3 | Domain | Buy it later, in the plan step, on Cloudflare Registrar | About $10 a year |
+| 4 | Google Search Console | After the domain exists, add a Domain property and verify it through Cloudflare | Free |
+| 5 | Bing Webmaster Tools | Import the site from Search Console | Free |
+| 6 | SEO Skill | `seo start` signs in with Google and adds the MCP server and skill | Free |
+| 7 | Keyword data (optional) | A DataForSEO or Ahrefs key, saved on the account page at https://seoskill.dev/account, then `seo login` | Free without a key, the provider bills you with one |
+| 8 | Analytics | Clicky, on the production site only | Free tier |
+
+Accounts 3 to 5 need the domain, so they wait until the plan is approved.
+Note each one as a to-do for the launch step.
+
+## Keyword data is the person's choice
+
+Without a key, the market and plan steps use free sources: the live search
+results, autocomplete, forums and, once the site is live, its own Search
+Console data. With a DataForSEO or Ahrefs key, `seo research` adds search
+volumes, difficulty, the pages that rank and competitor keywords. Explain
+both, give the price page of each provider, and let the person choose.
+DataForSEO bills per request. Ahrefs needs a plan that includes API units.
+
+## Rules
+
+- One account at a time. Wait for the person to finish before the next.
+- If a login fails, read the error to them in plain words and try once more
+  before moving on.
+- Write what was set up in the project notes, never the keys themselves.
+
+Done when: `gh auth status`, `npx wrangler whoami` and `seo doctor` all
+show a signed-in account, and the person has chosen free or paid keyword
+data.
+
+Next: `seo site guide market`

package/site-kit/guide/writing.md

@@ -0,0 +1,55 @@
+# Step 7 of 10: writing
+
+Goal: copy a person enjoys reading and an AI answer can lift out and quote
+correctly.
+
+## What the agent does
+
+1. Write in two passes. First collect the facts for a page from the data
+   and its sources. Then write only from those facts.
+2. Put sentences that depend on the data in `src/lib/narrative.ts`. Each
+   sentence is shown only when its fact exists, and the wording changes
+   with the numbers, so pages read differently.
+3. Check every claim against its source before it ships.
+4. Run `pnpm build`. `seo site check` fails on the copy rules below.
+
+## What the person does
+
+Plan the sections of the main page type, because sections an AI plans come
+out generic. Read a few pages like a visitor, and turn every pattern they
+dislike into a rule.
+
+## Rules for people
+
+- Clear, direct, full sentences. Say what the reader gets.
+- The length is whatever answers the question. No word count targets, and
+  no "what is X" opening when the reader already knows.
+- The title tag is for the search result: the words people search for
+  first, short enough not to be cut off. The H1 says the same thing in
+  plainer words.
+- Questions in an FAQ come from real searches or common sense.
+- Never write about the build, the tools, collecting data, search terms or
+  "coming soon".
+
+`seo site check` fails on: dashes used as punctuation, semicolons, "it's
+not X, it's Y" lines, hype words such as seamless, robust and unlock,
+openings such as "in this guide" and "did you know", tool and process
+words, and "coming soon". When a banned word is part of the subject (a
+site about Cloudflare, say), add it to `allowWords` in `site.config.json`.
+
+## Rules for being quoted
+
+- Every section answers on its own. Name the subject, give the answer in
+  the first sentence or two, then the conditions. Test it by reading the
+  section alone.
+- Write H2s the way people ask.
+- Keep each number next to its source and date, in visible text.
+- Credit the site's own figures by name: "{Site}'s data shows", never "our
+  data".
+- One strong page per claim. Keep price and other fast moving pages fresh,
+  with a visible date.
+
+Done when: every section passes the read-it-alone test, the facts match the
+sources and `pnpm build` passes.
+
+Next: `seo site guide scale`