seo-doctor

A conformance instrument that measures a built website-factory site against the pinned SEO standard. It builds/serves the site locally, crawls it, reads its source tree, and judges every rule of the standard as present (pass), non-conforming (fail) or could-not-judge (abstention).

Built ON the @vantageos/mcp-doctor engine — never a new engine. seo-doctor adds only the site-snapshot loader (live crawler + local server lifecycle), the source-tree walker, and the 33 SEO detectors; the engine's runDoctor / renderTable / computeExitCode are consumed, not reimplemented.

No client name, domain or business value lives in this repository. The client is a configuration parameter — see docs/configuration.md.

What it checks

The standard it measures is vendored and pinned — see docs/pins.md for the exact commit and how the pin is verified. Coverage of the standard's 33 rules is generated, never hand-typed — see docs/coverage.md.

Install

npm install --global @vantageos/seo-doctor@alpha

0.1.0-alpha.4 publishes under the alpha tag (publishConfig.tag) — and latest moves to that SAME version on every alpha publish (npm sets latest on a package's first publish regardless of tag, and Pi's ruling keeps it moving with each alpha: leaving latest pinned to a superseded alpha would serve a gate measuring an old, superseded standard). A plain npm i @vantageos/seo-doctor and the explicit @alpha form therefore install the SAME thing today. There is no stable release yet — when one exists, latest moves to it, and @alpha stops being the same as a plain install. Use the explicit tag anyway; it is the documented form and stays correct across that day. To work on this repository instead, build from source:

npm ci
npm run build

Quick start

Installed:

npx seo-doctor <site-dir>

From source:

npx tsx src/cli.ts <site-dir>

<site-dir> must be a real directory that has its own package.json and a start script that respects the PORT environment variable (the same contract next start satisfies with no -p flag). seo-doctor spawns that command, crawls the site it serves, judges every rule, and prints a report.

Every flag the CLI accepts, what --snapshot-json is for, and what is NOT built yet (S-21's --compare second-build input) are documented in docs/usage.md.

Exit codes

| Exit | Meaning | |---|---| | 0 | No non-conforming rule and no could-not-judge rule was reached. Not "the site conforms" — see the caveat in docs/exit-codes.md. | | 1 | At least one rule is non-conforming. | | 2 | At least one rule is could-not-judge, OR the target could not be read/built/served at all (a missing directory, a directory with no package.json, a crawl failure). |

Full detail, including the engine's own exit-code caveat from PINS.txt: docs/exit-codes.md.

Documentation

• docs/usage.md — the CLI, every flag, the config file.
• docs/exit-codes.md — 0 / 1 / 2, with the engine's caveat.
• docs/coverage.md — all 33 rules, generated.
• docs/pins.md — the standard + engine pins, and the re-pin procedure.
• docs/configuration.md — every seo-doctor.config.json key, mapped to the standard's §4 table.
• docs/ci-integration.md — the CI job a website-factory site adds.
• docs/tdd-log.md — the build log: RED/GREEN runs, mutation-testing proof against a real template, known gaps.
• docs/proof.md — every command this documentation set claims, executed for real, output and exit code cited.
• CHANGELOG.md

License

FSL-1.1-Apache-2.0 — free for production use; the source becomes Apache-2.0 on the Change Date in the LICENSE file. Same license as every other @vantageos/* package.

Status

0.1.0-alpha.4 — clause-level coverage (npm run coverage): 27 CHECKED + 5 PARTIAL + 1 NOT_MECHANICALLY_CHECKABLE = 33 of 33 derived rules, all accounted for. PARTIAL (S-6, S-12, S-14, S-25, S-30) means the rule IS built and judged, but at least one of its Refuses: clauses is a named, written abstention rather than a fabricated pass — see docs/coverage.md for exactly which clause and why. S-21 (needs a second build) is the one remaining rule-level NOT_MECHANICALLY_CHECKABLE exception — see docs/pins.md. Full honest state, including known gaps, in docs/tdd-log.md.