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>

scripts/applyBrand.mjs

@@ -229,10 +229,71 @@ const counts = new Map(replacements.map((r) => [r.field, 0]));
 counts.set('demoDeep', 0);
 let filesTouched = 0;
 
+/**
+ * The CSP (§6, D48) hashes every inline `<script>` and `<style>` in the build. This script
+ * runs after that hashing and rewrites the same files, so a brand value that happened to
+ * sit inside an inline block would change its bytes, invalidate its hash and get the block
+ * refused by the browser — with no error anywhere except a console nobody has open. The
+ * page would render perfectly and the script simply would not run.
+ *
+ * Nothing puts brand text in an inline script today, and the replacements are guarded by
+ * MIN_REWRITABLE_LENGTH so they are unlikely to collide by accident. "Unlikely" is not the
+ * standard for a failure this quiet, so the collision is checked rather than reasoned
+ * about: if a rewrite ever lands inside an inline block, this refuses to write that file
+ * and says so, and the page keeps its stock text instead of losing its behaviour.
+ */
+const INLINE_BLOCK = /<(script|style)(?![^>]*\bsrc\s*=)([^>]*)>([\s\S]*?)<\/\1>/g;
+
+/**
+ * The structured-data block (D50) is a `<script>` that no browser executes and no CSP hash
+ * covers, so it is not one of the blocks this guard protects — and it MUST NOT be, because
+ * it contains the site's name. Treating it as a script would make the guard refuse to
+ * rewrite the homepage, which is §7 failing on the one page that matters most.
+ */
+const DATA_BLOCK = /type\s*=\s*["']application\/(ld\+json|json)["']/i;
+
+const inlineRanges = (html) => {
+  const ranges = [];
+  INLINE_BLOCK.lastIndex = 0;
+  let match;
+  while ((match = INLINE_BLOCK.exec(html))) {
+    if (match[1] === 'script' && DATA_BLOCK.test(match[2])) continue;
+    // Where the block's CONTENT starts — measured back from the end of the whole match, so
+    // the opening tag's attributes cannot throw the offset off: `</script>` is the tag name
+    // plus three characters.
+    const closing = match[1].length + 3;
+    const start = match.index + match[0].length - closing - match[3].length;
+    ranges.push([start, start + match[3].length]);
+  }
+  return ranges;
+};
+const hitsInlineBlock = (html, needle) => {
+  if (!needle || !html.includes(needle)) return false;
+  const ranges = inlineRanges(html);
+  if (ranges.length === 0) return false;
+  for (let at = html.indexOf(needle); at !== -1; at = html.indexOf(needle, at + 1)) {
+    const end = at + needle.length;
+    if (ranges.some(([from, to]) => at < to && end > from)) return true;
+  }
+  return false;
+};
+const inlineCollisions = [];
+
 for (const file of walk(CLIENT)) {
   const before = readFileSync(file, 'utf8');
   let after = before;
 
+  if (path.extname(file) === '.html') {
+    const colliding = replacements.filter(({ from }) => hitsInlineBlock(before, from));
+    if (colliding.length) {
+      inlineCollisions.push({
+        file: path.relative(CLIENT, file),
+        fields: [...new Set(colliding.map((c) => c.field))],
+      });
+      continue;
+    }
+  }
+
   for (const { field, from, to } of replacements) {
     if (!after.includes(from)) continue;
     counts.set(field, counts.get(field) + after.split(from).length - 1);
@@ -270,6 +331,47 @@ if (counts.get('demoDeep')) {
   );
 }
 
-// Pagefind builds its search index from the HTML at BUILD time (phase 10), so a rename
-// applied here reaches the pages but not the search results. Worth fixing when search
-// lands; recorded here rather than in a plan section nobody will re-read.
+if (inlineCollisions.length) {
+  console.error(
+    `\n[brand] ${inlineCollisions.length} file(s) were LEFT UNCHANGED: a brand value occurs ` +
+      `inside an inline <script> or <style>, and rewriting it would break that block's CSP ` +
+      `hash (§6, D48) — the page would render and the script would silently not run.\n`
+  );
+  for (const { file, fields } of inlineCollisions) {
+    console.error(`  ! ${file}  (${fields.join(', ')})`);
+  }
+  console.error(
+    `\n  Those pages keep the stock text. Fix it by taking the brand value out of the inline\n` +
+      `  block — move it into markup the CSP does not hash, or into /brand/theme.css.\n`
+  );
+}
+
+/* ---------------------------------------------------------------------------------------
+   Search
+   --------------------------------------------------------------------------------------- */
+
+/**
+ * Pagefind builds its index from the built HTML at BUILD time, so everything above reaches
+ * the pages and none of it reaches the search results: a site renamed through the mount
+ * would answer a search for its own name with the stock one, and every result title would
+ * still carry the old suffix. Phase 2 recorded that and left it for this phase, when
+ * search became site-wide (D47).
+ *
+ * The fix is to re-index, which is cheap and needs nothing the container does not already
+ * have — Pagefind is what Starlight ran at build. It only runs when a rewrite actually
+ * happened, so the stock deployment, which is the common case, still pays nothing.
+ */
+if (filesTouched > 0) {
+  const pagefind = await import('pagefind');
+  try {
+    const { index } = await pagefind.createIndex();
+    const { page_count } = await index.addDirectory({ path: CLIENT });
+    await index.writeFiles({ outputPath: path.join(CLIENT, 'pagefind') });
+    console.log(`[brand] re-indexed ${page_count} page(s) for search so results agree with it.`);
+  } catch (error) {
+    // Search degrading to stale titles is not a reason to refuse to serve the site.
+    console.error(`[brand] could not rebuild the search index; it keeps the built one: ${error.message}`);
+  } finally {
+    await pagefind.close();
+  }
+}

scripts/checkA11y.mjs

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+/**
+ * checkA11y.mjs — PLAN.md §13 phase 10.
+ *
+ * Every other rule this repository cares about is enforced by a script — the facts, the
+ * links, the tokens, the sidebar, the screenshots, the CSP. Accessibility was the exception:
+ * it was a thing someone checked once, by hand, on the pages they happened to open. This
+ * makes it the eleventh check so a regression fails a build instead of waiting for a reader
+ * who cannot use the page and will not file an issue.
+ *
+ *   node scripts/checkA11y.mjs
+ *
+ * ── What it checks, and why each one ────────────────────────────────────────
+ * A static check cannot measure contrast against a rendered page or find a focus trap, and
+ * pretending otherwise would be worse than not checking. What it CAN do is catch the class
+ * of defect that is invisible to a sighted author and permanent once shipped:
+ *
+ *   1. **One `<h1>` per page, and no skipped heading level.** The heading tree is the
+ *      document outline a screen-reader user navigates by. Two `<h1>`s or an `<h2>` under
+ *      nothing reads as a page with no structure at all.
+ *   2. **Every `<img>` has an `alt`.** Not "a non-empty alt": `alt=""` is correct and
+ *      deliberate for the header mark, which sits inside a link that already says the
+ *      product's name. A MISSING attribute is what makes a screen reader read the filename.
+ *   3. **Every form control has a label.** `<label for>`, a wrapping `<label>`,
+ *      `aria-label` or `aria-labelledby`. The signup form is the only place on this site
+ *      where a person is asked to type something, so it is the one place this must hold.
+ *   4. **Every link and button has an accessible name.** An icon-only control with no text
+ *      and no `aria-label` is announced as "link", which is no name at all. The search
+ *      button is icon-only under 46rem, which is exactly this hazard.
+ *   5. **`<html lang>` is set**, or a screen reader reads English prose with whatever voice
+ *      the reader last used.
+ *   6. **One `<main>` per page and a skip link that points at it.** The site's header is a
+ *      lockup, four links and a search box in front of every page; without a working skip
+ *      link a keyboard user walks all six on every navigation.
+ *   7. **No positive `tabindex`.** It reorders the tab sequence away from the visual one
+ *      and is almost never what the author meant.
+ *
+ * Both chromes are checked — the marketing pages and Starlight's forty. Starlight is
+ * generally careful, so the docs half is a regression alarm on a dependency rather than a
+ * review of our own markup, and it has already earned its place once: it is what would have
+ * caught the `<h2>`-without-`<h1>` shape if a docs page had ever lost its title.
+ *
+ * No token and no network: everything read here is in `dist/`.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const clientDir = path.join(root, 'dist', 'client');
+
+if (!fs.existsSync(clientDir)) {
+  console.error('\ncheckA11y: dist/client does not exist. Run `npm run build` first.\n');
+  process.exit(1);
+}
+
+const failures = [];
+const fail = (page, what, detail) => failures.push({ page, what, detail });
+
+const pages = [];
+const walk = (dir) => {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full);
+    else if (entry.name.endsWith('.html')) pages.push(full);
+  }
+};
+walk(clientDir);
+
+/* ---------------------------------------------------------------------------------------
+   A very small amount of HTML reading
+
+   Not a parser. Everything below is a tag-level question — does this element carry this
+   attribute, what text sits between these two tags — and a regex answers those on
+   generated, well-formed output. A DOM parser would be a dependency, and this repository's
+   checks are dependency-free on purpose (§12): the reader runs them the same way CI does.
+   --------------------------------------------------------------------------------------- */
+
+/** Takes the ATTRIBUTE STRING — what is between the tag name and the `>` — not the tag. */
+const attrs = (attrString) => {
+  const found = new Map();
+  const re = /([a-zA-Z_:][-a-zA-Z0-9_:.]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
+  let m;
+  while ((m = re.exec(attrString))) {
+    found.set(m[1].toLowerCase(), m[2] ?? m[3] ?? m[4] ?? '');
+  }
+  return found;
+};
+
+/** Text a screen reader would announce: markup and comments stripped, entities loosened. */
+const textOf = (html) =>
+  html
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/&[a-zA-Z#0-9]+;/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+/** An element's own accessible name, near enough for "is there one at all". */
+const named = (tag, inner) => {
+  const a = attrs(tag);
+  if (a.get('aria-label')?.trim()) return true;
+  if (a.get('aria-labelledby')?.trim()) return true;
+  if (a.get('title')?.trim()) return true;
+  if (textOf(inner)) return true;
+  // An image child with alt text names the control.
+  for (const img of inner.matchAll(/<img\b([^>]*)>/gi)) {
+    if (attrs(img[1]).get('alt')?.trim()) return true;
+  }
+  // An SVG with a title element does too.
+  if (/<svg\b[^>]*>[\s\S]*?<title\b[^>]*>[^<]+<\/title>/i.test(inner)) return true;
+  return false;
+};
+
+for (const file of pages) {
+  const page = '/' + path.relative(clientDir, file).replace(/\\/g, '/');
+
+  /**
+   * Comments are stripped before anything is counted, and that is not a nicety: this
+   * repository comments its markup heavily, and several of those comments quote the tags
+   * they are explaining. `Base.astro`'s note about `data-pagefind-body` contains the text
+   * "<main>", and the first run of this check reported every marketing page as having two
+   * `<main>` landmarks because of it. Stripping once, up front, also keeps every offset
+   * below measured against the same string.
+   */
+  const html = fs.readFileSync(file, 'utf8').replace(/<!--[\s\S]*?-->/g, '');
+
+  // ── 5. lang ───────────────────────────────────────────────────────────────
+  const htmlTag = /<html\b([^>]*)>/i.exec(html);
+  if (!htmlTag) fail(page, '<html>', 'has no <html> element');
+  else if (!attrs(htmlTag[1]).get('lang')?.trim()) fail(page, '<html>', 'has no lang attribute');
+
+  // ── 1. headings ───────────────────────────────────────────────────────────
+  const headings = [...html.matchAll(/<h([1-6])\b([^>]*)>([\s\S]*?)<\/h\1>/gi)]
+    // `aria-hidden` headings are decorative and out of the outline by definition.
+    .filter((m) => attrs(m[2]).get('aria-hidden') !== 'true')
+    .map((m) => ({ level: Number(m[1]), text: textOf(m[3]) }));
+
+  const h1s = headings.filter((h) => h.level === 1);
+  if (h1s.length === 0) fail(page, 'headings', 'has no <h1>');
+  if (h1s.length > 1) {
+    fail(page, 'headings', `has ${h1s.length} <h1>s: ${h1s.map((h) => JSON.stringify(h.text)).join(', ')}`);
+  }
+
+  let previous = 0;
+  for (const heading of headings) {
+    if (previous && heading.level > previous + 1) {
+      fail(
+        page,
+        'headings',
+        `jumps from h${previous} to h${heading.level} at ${JSON.stringify(heading.text.slice(0, 50))}`,
+      );
+    }
+    previous = heading.level;
+  }
+
+  // ── 2. images ─────────────────────────────────────────────────────────────
+  for (const img of html.matchAll(/<img\b([^>]*)>/gi)) {
+    const a = attrs(img[1]);
+    if (!a.has('alt')) {
+      fail(page, '<img>', `has no alt attribute: src=${a.get('src') ?? '(none)'}`);
+    }
+  }
+
+  // ── 3. form controls ──────────────────────────────────────────────────────
+  const labelledIds = new Set(
+    [...html.matchAll(/<label\b([^>]*)>/gi)]
+      .map((m) => attrs(m[1]).get('for'))
+      .filter(Boolean),
+  );
+  /**
+   * A control wrapped in its own `<label>` needs no `for` and — this is the part that took
+   * a wrong answer to find — needs no `id` either, so it cannot be recorded by id. Starlight
+   * labels its theme and language selects exactly this way. What is recorded instead is the
+   * character offset of each wrapped control, which identifies it uniquely without
+   * requiring it to have any attributes at all.
+   */
+  const wrappedAt = new Set();
+  for (const label of html.matchAll(/<label\b[^>]*>([\s\S]*?)<\/label>/gi)) {
+    const base = label.index + label[0].indexOf(label[1]);
+    for (const control of label[1].matchAll(/<(input|select|textarea)\b[^>]*>/gi)) {
+      wrappedAt.add(base + control.index);
+    }
+  }
+
+  for (const control of html.matchAll(/<(input|select|textarea)\b([^>]*)>/gi)) {
+    const a = attrs(control[2]);
+    const type = (a.get('type') ?? 'text').toLowerCase();
+    // These are not things a person types into and are named by other means.
+    if (['hidden', 'submit', 'button', 'reset', 'image'].includes(type)) continue;
+
+    const id = a.get('id');
+    const hasLabel =
+      wrappedAt.has(control.index) ||
+      (id && labelledIds.has(id)) ||
+      a.get('aria-label')?.trim() ||
+      a.get('aria-labelledby')?.trim() ||
+      a.get('title')?.trim();
+
+    if (!hasLabel) {
+      fail(
+        page,
+        `<${control[1]}>`,
+        `has no label: ${id ? `id="${id}"` : `name="${a.get('name') ?? '(none)'}"`} — ` +
+          'a placeholder is not a label',
+      );
+    }
+  }
+
+  // ── 4. link and button names ──────────────────────────────────────────────
+  for (const [, tag, attrString, inner] of html.matchAll(/<(a|button)\b([^>]*)>([\s\S]*?)<\/\1>/gi)) {
+    const a = attrs(attrString);
+    if (a.get('aria-hidden') === 'true') continue;
+    // An <a> with no href is not a link; it is a target for one.
+    if (tag.toLowerCase() === 'a' && !a.has('href')) continue;
+    if (named(attrString, inner)) continue;
+
+    fail(
+      page,
+      `<${tag}>`,
+      `has no accessible name: ${a.get('href') ? `href="${a.get('href')}"` : `class="${a.get('class') ?? ''}"`}`,
+    );
+  }
+
+  // ── 6. main and the skip link ─────────────────────────────────────────────
+  const mains = [...html.matchAll(/<main\b([^>]*)>/gi)];
+  if (mains.length === 0) fail(page, '<main>', 'has no <main> landmark');
+  if (mains.length > 1) fail(page, '<main>', `has ${mains.length} <main> elements`);
+
+  const skip = /<a\b([^>]*class="[^"]*skip-link[^"]*"[^>]*)>/i.exec(html);
+  if (skip) {
+    const target = attrs(skip[1]).get('href') ?? '';
+    if (!target.startsWith('#')) {
+      fail(page, 'skip link', `points at ${JSON.stringify(target)}, which is not an in-page anchor`);
+    } else {
+      const id = target.slice(1);
+      if (!new RegExp(`\\bid=["']${id}["']`).test(html)) {
+        fail(page, 'skip link', `points at #${id}, and nothing on the page has that id`);
+      }
+    }
+  }
+
+  // ── 7. positive tabindex ──────────────────────────────────────────────────
+  for (const m of html.matchAll(/\btabindex\s*=\s*["']?(-?\d+)/gi)) {
+    if (Number(m[1]) > 0) {
+      fail(page, 'tabindex', `is ${m[1]} — a positive tabindex reorders the tab sequence`);
+    }
+  }
+}
+
+/* ---------------------------------------------------------------------------------------
+   Report
+   --------------------------------------------------------------------------------------- */
+
+if (failures.length === 0) {
+  console.log(`checkA11y: ${pages.length} built pages pass all seven structural checks.`);
+} else {
+  // Grouped by page: a shared component's defect otherwise prints fifty times and buries
+  // the one page that has a real problem of its own.
+  const byPage = new Map();
+  for (const f of failures) {
+    if (!byPage.has(f.page)) byPage.set(f.page, []);
+    byPage.get(f.page).push(f);
+  }
+
+  console.error(`\ncheckA11y: ${failures.length} problem(s) across ${byPage.size} page(s):\n`);
+  for (const [page, items] of byPage) {
+    console.error(`  ${page}`);
+    for (const item of items) console.error(`    ✗ ${item.what}: ${item.detail}`);
+  }
+  console.error(`
+These are structural, so they are the same in every browser and for every reader. A defect
+repeated across many pages is usually one shared component — fix it there rather than on
+each page.
+`);
+  process.exit(1);
+}

scripts/checkCsp.mjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+/**
+ * checkCsp.mjs — PLAN.md §6 and D48, added in phase 10.
+ *
+ * §6 promises "a strict CSP with no external origins". D48 decided that promise should be
+ * a real response header sent by the container itself, not a `<meta>` (which ignores
+ * `frame-ancestors`) and not advice in an operator's proxy config (which lives outside the
+ * artifact we ship and test). `astro.config.mjs` sets it up; this checks it arrived.
+ *
+ *   node scripts/checkCsp.mjs            # verify the built output
+ *   node scripts/checkCsp.mjs --write    # rewrite src/config/cspHashes.mjs from the build
+ *   node scripts/checkCsp.mjs --reset    # empty it, so the next harvest starts from nothing
+ *
+ * Three things are checked, and each one has already been wrong once:
+ *
+ *  1. **Every built route has a policy.** `staticHeaders` writes `dist/_headers.json`; a
+ *     route missing from it is a page served with no CSP at all, which is the failure mode
+ *     nobody notices because the page looks perfect.
+ *
+ *  2. **Every inline script and style is covered by its page's own policy.** This is the
+ *     real check. Astro does not hash `<script is:inline>`, and Starlight ships six of
+ *     them per documentation page — so the first build with CSP on had a strict, correct
+ *     header and a dead theme switcher. Hashing is verified per page against that page's
+ *     header, not against a global list, because that is what the browser does.
+ *
+ *  3. **The directives §6 actually promised are present.** A policy that lost
+ *     `frame-ancestors` in a refactor still passes checks 1 and 2 while no longer stopping
+ *     anything.
+ *
+ * `--write` harvests the hashes from check 2 into `src/config/cspHashes.mjs`, which
+ * `astro.config.mjs` feeds back into the next build. So the sequence is reset → build →
+ * write → build → verify, which is what `npm run csp:hashes` runs. It resets first because
+ * harvesting only ever collects what the build did NOT cover — see `--reset` below.
+ *
+ * No token and no network: everything read here is in `dist/`.
+ */
+
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const headersFile = path.join(root, 'dist', '_headers.json');
+const clientDir = path.join(root, 'dist', 'client');
+const hashesFile = path.join(root, 'src', 'config', 'cspHashes.mjs');
+
+const write = process.argv.includes('--write');
+const reset = process.argv.includes('--reset');
+
+const failures = [];
+const fail = (what, detail) => failures.push({ what, detail });
+
+/**
+ * Rewrites the two exported arrays in `src/config/cspHashes.mjs`, leaving every comment and
+ * the JSDoc types above them untouched.
+ */
+const writeHashes = (script, style) => {
+  const source = fs.readFileSync(hashesFile, 'utf8');
+  const list = (hashes) =>
+    hashes.size === 0 ? '[]' : `[\n${[...hashes].sort().map((h) => `  '${h}',`).join('\n')}\n]`;
+
+  fs.writeFileSync(
+    hashesFile,
+    source
+      .replace(
+        /export const inlineScriptHashes = [\s\S]*?;\n/,
+        `export const inlineScriptHashes = ${list(script)};\n`,
+      )
+      .replace(
+        /export const inlineStyleHashes = [\s\S]*?;\n/,
+        `export const inlineStyleHashes = ${list(style)};\n`,
+      ),
+  );
+};
+
+/**
+ * `--reset` empties the generated file, and `npm run csp:hashes` runs it FIRST.
+ *
+ * Without it the regeneration is not idempotent, and its failure mode is the worst
+ * available: harvesting collects the blocks the build did not cover, so running it against
+ * a build that is already correct finds nothing, writes two empty arrays and produces a
+ * build with no hashes at all. Emptying first means the harvest always sees the same thing
+ * — every inline block Astro does not hash on its own — whatever state the file was in.
+ */
+if (reset) {
+  writeHashes(new Set(), new Set());
+  console.log('checkCsp --reset: src/config/cspHashes.mjs emptied, ready to re-harvest.');
+  process.exit(0);
+}
+
+// ── The build has to be there ───────────────────────────────────────────────
+if (!fs.existsSync(headersFile)) {
+  console.error(`
+checkCsp: dist/_headers.json does not exist.
+
+That file is written by the Node adapter's \`staticHeaders\` option, so either the build
+has not run (\`npm run build\`) or \`staticHeaders\` was turned off in astro.config.mjs —
+in which case the CSP is a <meta> tag and \`frame-ancestors\` is being ignored (D48).
+`);
+  process.exit(1);
+}
+
+/**
+ * `_headers.json` is keyed by an internal route id, so the pathname lives in the record.
+ * Normalised without a trailing slash: the file says `/docs/first-run`, the built page is
+ * at `docs/first-run/index.html`, and `build.format: 'directory'` serves it at
+ * `/docs/first-run/`.
+ */
+const byPath = new Map();
+for (const record of Object.values(JSON.parse(fs.readFileSync(headersFile, 'utf8')))) {
+  const csp = record.headers?.find((h) => h.key.toLowerCase() === 'content-security-policy');
+  byPath.set(record.pathname.replace(/\/$/, '') || '/', csp?.value ?? null);
+}
+
+// ── Walk the built HTML ─────────────────────────────────────────────────────
+const pages = [];
+const walk = (dir) => {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full);
+    else if (entry.name === 'index.html' || entry.name.endsWith('.html')) pages.push(full);
+  }
+};
+walk(clientDir);
+
+/**
+ * Inline only: anything with a `src` is a fetched file and is covered by `'self'`.
+ * The body is hashed exactly as written, because that is what the browser hashes — one
+ * byte of whitespace either side changes the digest.
+ */
+const INLINE_SCRIPT = /<script(?![^>]*\bsrc\s*=)([^>]*)>([\s\S]*?)<\/script>/g;
+const INLINE_STYLE = /<style([^>]*)>([\s\S]*?)<\/style>/g;
+
+/**
+ * `<script type="application/ld+json">` (D50) is a data block, not code: the browser never
+ * executes it, and CSP's script-src is not enforced against it. Demanding a hash for one
+ * would be wrong twice over — it would add the structured data's own text to the list of
+ * scripts allowed to run, and that text changes whenever a fact or the brand name does, so
+ * the generated hash file would churn on edits that cannot affect security.
+ */
+const DATA_BLOCK = /type\s*=\s*["']application\/(ld\+json|json)["']/i;
+
+const sha256 = (body) => `sha256-${createHash('sha256').update(body, 'utf8').digest('base64')}`;
+
+const harvested = { script: new Set(), style: new Set() };
+let inlineScripts = 0;
+let inlineStyles = 0;
+let uncovered = 0;
+
+for (const file of pages) {
+  const rel = path.relative(clientDir, file).replace(/\\/g, '/');
+  const pathname = '/' + rel.replace(/index\.html$/, '').replace(/\.html$/, '').replace(/\/$/, '');
+  const csp = byPath.get(pathname === '/' ? '/' : pathname.replace(/\/$/, ''));
+
+  if (csp === undefined) {
+    fail(pathname, 'is a built page with no entry in dist/_headers.json — it ships with no CSP');
+    continue;
+  }
+  if (csp === null) {
+    fail(pathname, 'has an entry in dist/_headers.json but no Content-Security-Policy header');
+    continue;
+  }
+
+  const html = fs.readFileSync(file, 'utf8');
+
+  for (const [kind, re, counter] of [
+    ['script', INLINE_SCRIPT, 'inlineScripts'],
+    ['style', INLINE_STYLE, 'inlineStyles'],
+  ]) {
+    re.lastIndex = 0;
+    let match;
+    while ((match = re.exec(html))) {
+      const [, attrs, body] = match;
+      if (kind === 'script' && DATA_BLOCK.test(attrs)) continue;
+      // An empty inline block needs no hash; browsers do not enforce one.
+      if (body.trim() === '') continue;
+      if (counter === 'inlineScripts') inlineScripts++;
+      else inlineStyles++;
+
+      const hash = sha256(body);
+      if (csp.includes(hash)) continue;
+
+      uncovered++;
+      harvested[kind].add(hash);
+      if (!write) {
+        fail(
+          `${pathname} (inline <${kind}>)`,
+          `${hash} is not in that page's policy — ${JSON.stringify(body.trim().slice(0, 60))}…`,
+        );
+      }
+    }
+  }
+}
+
+// ── The directives §6 promised, on a page that has to have them ─────────────
+const REQUIRED = [
+  "default-src 'self'",
+  "base-uri 'self'",
+  "form-action 'self'",
+  "object-src 'none'",
+  "frame-ancestors 'none'",
+];
+const home = byPath.get('/');
+if (!home) {
+  fail('/', 'the homepage has no CSP header at all');
+} else {
+  for (const directive of REQUIRED) {
+    if (!home.includes(directive)) fail('/ policy', `is missing "${directive}" (PLAN.md §6)`);
+  }
+  // The point of the whole exercise: a hash and 'unsafe-inline' in the same script
+  // directive means browsers ignore 'unsafe-inline' — but if the hashes ever went away it
+  // would quietly start applying.
+  const scriptSrc = /script-src ([^;]*)/.exec(home)?.[1] ?? '';
+  if (scriptSrc.includes("'unsafe-inline'")) {
+    fail('/ policy', "script-src contains 'unsafe-inline' — D48 says the hashes carry this");
+  }
+  if (scriptSrc.includes("'unsafe-eval'")) {
+    fail('/ policy', "script-src contains 'unsafe-eval' ('wasm-unsafe-eval' is the intended one)");
+  }
+}
+
+// ── --write: regenerate the hash file ───────────────────────────────────────
+if (write) {
+  writeHashes(harvested.script, harvested.style);
+  console.log(
+    `checkCsp --write: harvested ${harvested.script.size} script and ${harvested.style.size} ` +
+      `style hash(es) from ${pages.length} pages into src/config/cspHashes.mjs.`,
+  );
+  if (failures.length) {
+    console.error('\ncheckCsp --write: the build is still wrong in ways hashes cannot fix:\n');
+    for (const f of failures) console.error(`  ✗ ${f.what}\n      ${f.detail}`);
+    process.exit(1);
+  }
+  console.log('Now rebuild so the next build embeds them (npm run csp:hashes does both).');
+  process.exit(0);
+}
+
+// ── Report ──────────────────────────────────────────────────────────────────
+if (failures.length === 0) {
+  console.log(
+    `checkCsp: ${pages.length} pages carry a policy; ` +
+      `${inlineScripts} inline script(s) and ${inlineStyles} inline style(s) are all hashed.`,
+  );
+} else {
+  console.error(`\ncheckCsp: ${failures.length} problem(s) with the Content-Security-Policy:\n`);
+  for (const f of failures) console.error(`  ✗ ${f.what}\n      ${f.detail}`);
+  if (uncovered) {
+    console.error(`
+${uncovered} inline block(s) are not covered by a hash. In a browser this is silent: the
+page renders and the script simply never runs — Starlight's theme switch and mobile
+sidebar are inline scripts, so this is how the documentation loses them.
+
+If the inline block is legitimate (usually: Starlight was upgraded), run
+
+  npm run csp:hashes
+
+which rebuilds, harvests the hashes into src/config/cspHashes.mjs and rebuilds again.
+Read what changed before committing it — that file is a list of scripts allowed to run.
+`);
+  }
+  process.exit(1);
+}

scripts/serve.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * serve.mjs — the production entry point (PLAN.md §6, D48).
+ *
+ * `npm start` runs `applyBrand.mjs` and then this, instead of `dist/server/entry.mjs`
+ * directly. It is a thin wrapper around the adapter's own handler and exists for two
+ * reasons, one of them a bug in a dependency.
+ *
+ * ---------------------------------------------------------------------------------------
+ * 1. THE ADAPTER SERVES THE WRONG PAGE'S CONTENT-SECURITY-POLICY
+ * ---------------------------------------------------------------------------------------
+ * `@astrojs/node`'s `staticHeaders` writes one policy per prerendered route into
+ * `dist/_headers.json` and looks the right one up per request. The lookup, in
+ * `dist/serve-static.js`, is:
+ *
+ *     headersMap.find((header) => header.pathname.includes(baselessPathname))
+ *
+ * `String.includes` — a SUBSTRING test, not equality, taking the first match. So:
+ *
+ *   - `/modules/` matches the record for `/docs/modules/building-a-module`,
+ *   - `/architecture/` matches `/docs/architecture/...`,
+ *   - and `/`, which is a substring of every path in the file, matches whichever record
+ *     happens to be first — here `/404`.
+ *
+ * Every prerendered page was therefore served some other page's policy. Because the
+ * policies are per-page hash lists, that is not a cosmetic mismatch: the browser refused
+ * the page's own stylesheet. `/modules/` and `/architecture/` rendered unstyled sections
+ * with `Refused to apply inline style` in a console, and the homepage only looked fine
+ * because it happens to share a hash with the 404 page.
+ *
+ * Astro's static-header machinery is otherwise exactly what §6 wants, so this replaces the
+ * lookup rather than the mechanism: the same `_headers.json`, matched by pathname
+ * EQUALITY. The workaround is deliberately small and obvious so it can be deleted whole
+ * when the upstream `find` is fixed — the check for that is whether `/modules/` and
+ * `/docs/modules/building-a-module` are served different policies.
+ *
+ * ---------------------------------------------------------------------------------------
+ * 2. THE HEADERS THAT ARE NOT CSP
+ * ---------------------------------------------------------------------------------------
+ * A few security headers have nothing to do with Astro and no other place to live. They
+ * are set here rather than written into an operator's reverse-proxy configuration (D48,
+ * again): the container should be correct on its own, and a proxy someone else configures
+ * is a promise this repository cannot check.
+ *
+ * The two routes that render per request — `/beta` and `/brand/*` — have no entry in
+ * `_headers.json`, because nothing prerendered them. They get `frame-ancestors 'none'` on
+ * its own, which is the one directive a `<meta>` CSP cannot express and therefore the one
+ * thing Astro's per-page meta tag leaves them missing.
+ */
+
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.join(here, '..');
+
+const port = Number(process.env.PORT ?? 4321);
+const host = process.env.HOST ?? '0.0.0.0';
+
+/* ---------------------------------------------------------------------------------------
+   The policies, matched exactly
+   --------------------------------------------------------------------------------------- */
+
+const normalise = (pathname) => {
+  const clean = pathname.split('?')[0].split('#')[0];
+  const trimmed = clean.replace(/\/+$/, '');
+  return trimmed === '' ? '/' : trimmed;
+};
+
+const policies = new Map();
+const headersFile = path.join(root, 'dist', '_headers.json');
+
+if (fs.existsSync(headersFile)) {
+  for (const record of Object.values(JSON.parse(fs.readFileSync(headersFile, 'utf8')))) {
+    const csp = record.headers?.find((h) => h.key.toLowerCase() === 'content-security-policy');
+    if (csp) policies.set(normalise(record.pathname), csp.value);
+  }
+} else {
+  // Not fatal: the site still serves, with the per-page <meta> policy Astro also emits.
+  // Loud, because a deployment silently losing its response-header CSP is exactly what §6
+  // is trying to prevent.
+  console.error(
+    '[serve] dist/_headers.json is missing — pages will be served without a CSP response\n' +
+      '        header. Check that astro.config.mjs still sets `staticHeaders: true`.'
+  );
+}
+
+const FRAME_ONLY = "frame-ancestors 'none'";
+
+/**
+ * Headers with no page-by-page component. Each is the browser default made explicit, and
+ * each closes something the CSP does not:
+ *
+ *   - `X-Content-Type-Options` stops a browser guessing that a .txt is HTML.
+ *   - `Referrer-Policy` keeps the path of the page a reader came from out of requests to
+ *     other origins — there are none today (D9), and this is what keeps that true if a
+ *     link is ever followed off-site.
+ *   - `X-Frame-Options` says again, for anything too old to honour `frame-ancestors`.
+ *   - `Permissions-Policy` turns off hardware this site has no reason to ask for. A
+ *     marketing page requesting a camera should be impossible, not merely unlikely.
+ */
+const STATIC_HEADERS = {
+  'X-Content-Type-Options': 'nosniff',
+  'Referrer-Policy': 'strict-origin-when-cross-origin',
+  'X-Frame-Options': 'DENY',
+  'Permissions-Policy': 'camera=(), microphone=(), geolocation=(), payment=(), usb=()',
+};
+
+/* ---------------------------------------------------------------------------------------
+   The server
+   --------------------------------------------------------------------------------------- */
+
+// The adapter's entry starts its own listener on import unless this is set.
+process.env.ASTRO_NODE_AUTOSTART = 'disabled';
+
+// `pathToFileURL`, not the bare path: on Windows an absolute path starts with a drive
+// letter, and Node's ESM loader reads `c:` as an unsupported URL scheme.
+const { handler } = await import(pathToFileURL(path.join(root, 'dist', 'server', 'entry.mjs')).href);
+
+const server = http.createServer((req, res) => {
+  const policy = policies.get(normalise(req.url ?? '/'));
+
+  for (const [key, value] of Object.entries(STATIC_HEADERS)) res.setHeader(key, value);
+  res.setHeader('Content-Security-Policy', policy ?? FRAME_ONLY);
+
+  /**
+   * The adapter will set its own (wrong) `Content-Security-Policy` from inside the static
+   * handler, overwriting what was just set. Rather than race it, every later attempt to
+   * set that one header is ignored — the correct value is already on the response, and
+   * this request's policy cannot change halfway through serving it.
+   */
+  const setHeader = res.setHeader.bind(res);
+  res.setHeader = (name, value) => {
+    if (String(name).toLowerCase() === 'content-security-policy') return res;
+    return setHeader(name, value);
+  };
+
+  handler(req, res);
+});
+
+server.listen(port, host, () => {
+  console.log(`[serve] listening on http://${host}:${port} — ${policies.size} prerendered policies`);
+});