> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stage.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# Site health check

> One pass that scores a site on Stage version, SEO, editability, performance and GPU, accessibility, and platform adoption — with a ranked fix list.

Every client repo ships the `stage-health-check` skill in `.claude/skills/`. It runs a
deterministic audit and writes a report; an agent (or you) reads the report, checks the
judgement calls against the code, and ranks the fixes.

## Run it

```bash theme={null}
node .claude/skills/stage-health-check/health-check.mjs \
  --repo . --url https://<site> --routes /,/about,/news/<slug> --name "<Client>"
# → .context/health/<date>/report.md
```

* `--skip lighthouse` for a fast loop; `--skip runtime,lighthouse` for a static-only pass with no URL.
* `--presets mobile` halves the Lighthouse time.
* Playwright and Lighthouse install on first run into a temp tools directory, never into the site's `package.json`. It drives the system Google Chrome.
* Use the **live** URL. Local runs prove wiring, not performance: ISR has no local preview, and TTFB and Lighthouse numbers only mean something on the served host.

## What it scores

| Dimension | Looks at |
| - | - |
| Stage version | Exact, matching pins for `@sp-stage/sdk` + `@sp-stage/admin`; distance from latest; the breaking releases in between and their migration notes; no committed `.env` |
| SEO | Head tags the layout can emit; title, description, canonical, OG image, `lang`, one `h1`, JSON-LD on the served pages; `robots.txt`, sitemap (no A/B variants), `llms.txt`, a real 404; Lighthouse SEO |
| Editability | Every registered component has an anchored wrapper; admin-owned text has a `stagePath`; lists rendered item-by-item have a schema array (or a recorded exception); schema arrays are actually rendered; settings cogs expose only anchorless props; notch entries resolve; no legacy anchors or in-flow edit chrome; `<main>` carries the sections root |
| Performance & GPU | Lighthouse mobile + desktop with LCP / CLS / TBT; scroll-sweep frame rate and layout counts; large `backdrop-filter` regions; always-running animations; layout-property animation; autoplay video and WebGL; oversized or lazy-above-fold images; JS and image weight; fonts |
| Accessibility | Lighthouse A11y; `lang`, `alt`, link names, heading order; reduced-motion gating on JS animation; the design-engineering baseline |
| Platform adoption | On-demand ISR wired correctly (no timed expiration, no production read cache, no `getStaticPaths`, revalidate route); middleware; the platform routes; the `/admin` mount; house conventions |

Levels: 🔴 broken or leaking, 🟠 below the bar, 🔵 review. A dimension fails on any 🔴.

## The standard lives in `checks.md`

The skill's `checks.md` is the canonical list: every check with its *why*, its *fix*, and
the Stage version that introduced the practice. A site pinned below that version is told
to bump first, not that it's broken. The file is updated whenever the platform moves — a
new practice lands there in the same PR as the feature, and a fix applied on a second
site becomes a check for the third.

The fleet-wide view (which sites are behind, which don't answer) is the Fleet tool; this
is the per-site deep pass.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.