feat(polish): phase 10 — search, accessibility, SEO and a real CSP

PLAN.md §13 phase 10, with four decisions of record — D47-D50, taking the count
to fifty. Three were straightforward; the CSP turned into the phase's real work,
because the thing meant to be a configuration flag was broken in a dependency and
broken silently.

D47 — search reaches the marketing pages, and the header gets a box.
Base.astro marks its <main> as a Pagefind body, so all ten join the index the
docs already query, and Search.astro opens it in a <dialog>. Nothing is fetched
until the dialog is opened (the bundle is 120 kB and these pages otherwise ship
almost no JavaScript). Pagefind titles a result from the first <h1>, and these
pages have editorial ones — "The app for a deployment you already use" — so the
index is given the page's short name instead. applyBrand.mjs now re-indexes after
a rewrite, closing a note phase 2 left for this phase.

D48 — the CSP is a real response header, sent by the container. Not a <meta>,
which ignores frame-ancestors, and not advice for someone's reverse proxy, which
puts the strictest promise in §6 outside what this repo tests. Three things
fought it, all the same shape — correct build, broken page, no error:

  * Astro does not hash <script is:inline>, and Starlight ships six per docs
    page, so the first build with CSP on had a strict header and a dead theme
    switcher. The hashes are now generated into src/config/cspHashes.mjs and
    checkCsp.mjs verifies every inline block against its own page's policy.
  * Expressive Code writes ~3,700 inline style ATTRIBUTES, which cannot be
    hashed, hence style-src-attr 'unsafe-inline' — scoped to that directive, so
    script-src is untouched.
  * @astrojs/node matched a request to a policy with pathname.includes(), a
    substring test: /modules/ was served /docs/modules/building-a-module's
    policy and rendered with its own stylesheet refused. scripts/serve.mjs keeps
    the same _headers.json and matches by equality; test/headers.test.mjs starts
    the server and reads the responses, because nothing that reads dist/ can see
    this.

D49 — robots.txt allows everything and names the sitemap (there was no way to
find it: no robots.txt, and D9 rules out a search console). D50 — Organization
and SoftwareApplication, no ratings and no docs-wide Article markup.

checkA11y.mjs is the eleventh check: seven structural rules over all fifty pages,
verified by breaking each in turn. The walk at 390/768/1280 found no overflow
anywhere, the CSP violations above, a 17x17 consent checkbox (WCAG 2.2 SC 2.5.8
wants 24), and a skip link that moved the scroll but not the focus.

npm run verify is green: fourteen steps, both test suites, all eleven checks.

Co-Authored-By: Claude <noreply@anthropic.com>

README.md

@@ -35,17 +35,24 @@ Node 22 LTS or newer.
 
 ## The checks, and why they are not optional
 
-Two of them, both from `PLAN.md` §12. Neither is a linter; each one enforces a promise the site
-makes that would otherwise decay quietly.
+Eleven of them, from `PLAN.md` §12. None is a linter; each one enforces a promise the site makes
+that would otherwise decay quietly.
 
 ```bash
+npm run check:sidebar                             # the rendered docs tree still matches the planned one
+npm run check:screens                             # every screenshot has an entry, at the size declared
 npm run check:tokens                              # no colour literal outside the token file
 npm run check:brand                               # the branding pipeline's two quiet failures
 npm run check:datasafety                          # the Play declaration still matches /privacy
 npm run check                                     # astro check
 npm test                                          # the beta signup's decision path, and the policy data
-npm run build && npm run check:links              # every internal link resolves (reads the build)
+npm run build                                     # everything below reads the build
+npm run check:links                               # every internal link resolves
 GITEA_TOKEN=<token> npm run check:facts           # every version agrees with its authority
+GITEA_TOKEN=<token> npm run check:quickstart      # the install page still matches website's own files
+GITEA_TOKEN=<token> npm run check:reference       # every name the Reference lists still exists
+npm run check:a11y                                # seven structural accessibility rules, every page
+npm run check:csp                                 # every inline script and style is hashed in its policy
 npm run verify                                    # all of the above, in that order
 ```
 
@@ -81,6 +88,22 @@ carry are assembled from data files and template literals and a source scan sees
 also refuses a commit permalink into any org repository — those stop tracking the document they name
 without ever 404ing, which is the failure a link checker would otherwise call healthy.
 
+**`checkA11y.mjs`** applies seven structural rules to every built page — one `<h1>` and no skipped
+heading level, an `alt` on every image, a label on every form control, an accessible name on every
+link and button, `<html lang>`, one `<main>` with a skip link that reaches it, and no positive
+`tabindex`. Structural on purpose: a static check cannot measure contrast on a rendered page or find
+a focus trap, and one that pretended to would be trusted for things it cannot see. It covers
+Starlight's forty pages as well as our ten, so a dependency upgrade that loses a label turns the
+build red rather than becoming a discovery.
+
+**`checkCsp.mjs`** verifies that every route has a policy and that **every inline script and style is
+covered by a hash in its own page's policy**. That second rule is the one that earns its keep: Astro
+does not hash `<script is:inline>`, and Starlight ships six of them per documentation page, so the
+first build with CSP enabled had a strict, correct header and a dead theme switcher — a failure whose
+only symptom is a console message. When Starlight is upgraded and a hash stops matching,
+`npm run csp:hashes` rebuilds, re-harvests `src/config/cspHashes.mjs` and rebuilds again; read the
+diff before committing it, because that file is a list of scripts allowed to run.
+
 **`npm test`** is the one check that reads none of the above. Everything else inspects built output,
 and the beta signup's logic does not appear there: a honeypot can stop working entirely and produce
 a build identical to one where it works. It covers the honeypot, the signed form token, the timing
@@ -147,6 +170,40 @@ Regenerating the stock assets is a separate, manual step — `npm run brand:asse
 the emblem and the Cinzel outlines from the sibling checkouts in the workspace. Its output is
 committed so that CI never needs either.
 
+## Security headers, and the one workaround in the server
+
+`npm start` runs `scripts/applyBrand.mjs` and then `scripts/serve.mjs` — not
+`dist/server/entry.mjs` directly. `serve.mjs` is a thin wrapper around the adapter's own handler,
+and it exists for two reasons.
+
+The first is a bug in `@astrojs/node`. Its `staticHeaders` option writes one Content-Security-Policy
+per prerendered route into `dist/_headers.json`, then looks the right one up per request with
+`headersMap.find((h) => h.pathname.includes(baselessPathname))` — a **substring** test taking the
+first match. So `/modules/` was served the policy built for `/docs/modules/building-a-module`,
+`/architecture/` got a docs page's, and `/`, being a substring of every path in the file, got
+whichever record came first. Because each policy is a list of per-page hashes, that is not a
+cosmetic mismatch: the browser refused the page's own stylesheet, and `/modules/` and
+`/architecture/` rendered unstyled with `Refused to apply inline style` in a console. The wrapper
+keeps the same `_headers.json` and matches by **equality**. It is deliberately small so it can be
+deleted whole once the upstream `find` is fixed; the test for that is whether `/modules/` and
+`/docs/modules/building-a-module` are served different policies.
+
+The second is the handful of headers that have nothing to do with Astro: `X-Content-Type-Options`,
+`Referrer-Policy`, `X-Frame-Options` and a `Permissions-Policy` that turns off hardware this site has
+no reason to ask for. They are set in the container rather than written into an operator's
+reverse-proxy configuration, because the image should be correct on its own and a proxy somebody
+else configures is a promise this repository cannot check. The two routes that render per request —
+`/beta` and `/brand/*` — have no prerendered policy, so they get `frame-ancestors 'none'` on its own:
+the one directive a `<meta>` CSP cannot express, and therefore the one thing Astro's per-page meta
+tag leaves them missing.
+
+`style-src-attr 'unsafe-inline'` is the single relaxation in the policy, and it is scoped to that
+directive. Starlight and Expressive Code write around 3,700 inline `style` attributes into the
+documentation — icon sizes, the theme select's width, and every syntax colour — which cannot be
+hashed, because CSP hashes cover `<style>` elements and never attributes. A style attribute cannot
+execute script, so this leaves `script-src`, the directive CSP exists for, untouched. The marketing
+pages emit no inline style attributes at all.
+
 ## Layout
 
 ```
@@ -170,9 +227,10 @@ src/
   lib/betaSignup.mjs     Everything between a POST body and a row. Never throws.
   lib/tokens.mjs         Reads tokens.css at build time, for the few values that leave CSS.
   config/sidebar.mjs     The documentation journey, and the planned tree behind it.
+  config/cspHashes.mjs   GENERATED. Starlight's inline scripts, which Astro does not hash.
 brand-default/           The stock brand, baked into the image and always complete.
-scripts/                 The build-time checks, plus applyBrand (boot), brand:assets (manual)
-                         and beta.mjs (the tester-list CLI).
+scripts/                 The build-time checks, plus applyBrand and serve (boot),
+                         brand:assets (manual) and beta.mjs (the tester-list CLI).
 test/                    node --test. The logic the other checks cannot see.
 PLAY_DATA_SAFETY.md      GENERATED. The answers to Google Play's Data Safety form, from
                          src/data/collection.mjs. Edit the data, run npm run play:datasafety.