diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 057ed302..1b54b7e4 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -64,3 +64,13 @@ jobs:
 
       - name: Validate generated feeds
         run: pnpm run validate-feeds
+
+      - name: Validate generated content contracts
+        run: pnpm run validate-generated-content
+
+      # After the build: these journeys drive the real dist/client output.
+      - name: Install Chromium for browser journeys
+        run: pnpm exec playwright install --with-deps chromium
+
+      - name: Run browser regression journeys
+        run: pnpm run test:browser
diff --git a/README.md b/README.md
index f393192e..86a2b617 100644
--- a/README.md
+++ b/README.md
@@ -47,15 +47,25 @@ English is the listing language. Spanish is a twin: language toggle, title searc
 
 ## Toolchain
 
-| Tool    | Version               | Source of truth                            |
-| ------- | --------------------- | ------------------------------------------ |
-| Node.js | 22.12.0 (`>=22.12.0`) | `.nvmrc`, `engines.node` in `package.json` |
-| pnpm    | 12.3.4                | `packageManager` in `package.json`         |
+| Tool    | Version          | Source of truth                            |
+| ------- | ---------------- | ------------------------------------------ |
+| Node.js | 22.12.0 (`22.x`) | `.nvmrc`, `engines.node` in `package.json` |
+| pnpm    | 12.3.4           | `packageManager` in `package.json`         |
 
 CI reads both from those files — `actions/setup-node` uses `node-version-file: .nvmrc`
 and `pnpm/action-setup` uses the `packageManager` field — so there is no separate
 version to keep in sync in `.github/workflows/ci.yml`.
 
+`engines.node` is capped to a single major on purpose. **Vercel reads
+`engines.node` and it overrides the Node version in Project Settings**, so an
+open range such as `>=22.12.0` silently promotes production to the newest major
+Node — and keeps doing so as new ones ship. `22.x` keeps production, CI, and
+`.nvmrc` on the same major.
+
+pnpm does not enforce `engines` unless `engine-strict` is set, so a newer local
+Node still installs and runs. It is not the tested target, though: run `nvm use`
+in this directory to pick up `.nvmrc` before trusting a local result.
+
 Locally, `corepack enable` makes `pnpm` in this directory resolve to the pinned
 version. Without corepack, install pnpm 12 yourself; older majors may not
 understand every key in `pnpm-workspace.yaml`.
@@ -93,32 +103,101 @@ Remark42 uses `PUBLIC_REMARK42_HOST` and `PUBLIC_REMARK42_SITE_ID` when you turn
 
 ## Scripts
 
-| Command                             | What it does                                                                                  |
-| ----------------------------------- | --------------------------------------------------------------------------------------------- |
-| `pnpm run dev`                      | Dev server                                                                                    |
-| `pnpm run build`                    | Builds social JPG/PNG from AVIF (skipped when fingerprints + files match), then `astro build` |
-| `pnpm run preview`                  | Serves prerendered `dist/client` on :4321 (no Vercel CLI needed; see caveat below)            |
-| `pnpm run preview:vercel`           | `astro preview` — needs the Vercel CLI installed                                              |
-| `pnpm test`                         | Vitest unit tests (publish filters, SEO routing, feed HTML, quotes helpers)                   |
-| `pnpm run test:watch`               | Vitest in watch mode                                                                          |
-| `pnpm changelog:since`              | Commits + file groups since the previous version (for CHANGELOG drafts)                       |
-| `pnpm run check`                    | `astro check` (TypeScript / Astro diagnostics)                                                |
-| `pnpm run lint`                     | ESLint                                                                                        |
-| `pnpm run lint:fix`                 | ESLint with `--fix`                                                                           |
-| `pnpm run format`                   | Prettier write                                                                                |
-| `pnpm run format:check`             | Prettier check (CI verifier; does not rewrite files)                                          |
-| `pnpm run audit-frontmatter`        | Required-field / language sanity check on `src/content/p`                                     |
-| `pnpm run validate-feeds`           | Validates `dist/rss.xml` + `dist/feed.json` (run after build)                                 |
-| `pnpm run validate-structured-data` | Smoke-checks structured-data module exports                                                   |
-| `pnpm run generate-social-images`   | AVIF → JPEG/PNG under `public/social/` only (same logic as the start of `pnpm run build`)     |
-| `pnpm run generate-favicons`        | Favicon assets                                                                                |
-| `pnpm run sync-remark42-rewrite`    | Regenerates the Remark42 rewrite in `vercel.json` from `REMARK42_UPSTREAM_ORIGIN`             |
-| `pnpm run check-remark42-rewrite`   | CI check that `vercel.json`'s Remark42 rewrite matches `REMARK42_UPSTREAM_ORIGIN`             |
-| `pnpm run lighthouse`               | Lighthouse HTML report against `dist/`; starts and stops its own preview server               |
-| `pnpm run audit-performance`        | Same, performance category only, JSON output                                                  |
+| Command                               | What it does                                                                                  |
+| ------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `pnpm run dev`                        | Dev server                                                                                    |
+| `pnpm run build`                      | Builds social JPG/PNG from AVIF (skipped when fingerprints + files match), then `astro build` |
+| `pnpm run preview`                    | Serves prerendered `dist/client` on :4321 (no Vercel CLI needed; see caveat below)            |
+| `pnpm run preview:vercel`             | `astro preview` — needs the Vercel CLI installed                                              |
+| `pnpm test`                           | Vitest unit tests (publish filters, SEO routing, feed HTML, quotes helpers)                   |
+| `pnpm run test:watch`                 | Vitest in watch mode                                                                          |
+| `pnpm run test:browser`               | Browser regression journeys against `dist/client` (build first; see below)                    |
+| `pnpm changelog:since`                | Commits + file groups since the previous version (for CHANGELOG drafts)                       |
+| `pnpm run check`                      | `astro check` (TypeScript / Astro diagnostics)                                                |
+| `pnpm run lint`                       | ESLint                                                                                        |
+| `pnpm run lint:fix`                   | ESLint with `--fix`                                                                           |
+| `pnpm run format`                     | Prettier write                                                                                |
+| `pnpm run format:check`               | Prettier check (CI verifier; does not rewrite files)                                          |
+| `pnpm run audit-frontmatter`          | Required-field / language sanity check on `src/content/p`                                     |
+| `pnpm run validate-feeds`             | Validates `dist/rss.xml` + `dist/feed.json` (run after build)                                 |
+| `pnpm run validate-structured-data`   | Smoke-checks structured-data module exports (source only)                                     |
+| `pnpm run validate-generated-content` | Parses the built site: JSON-LD, RSS XML, feed ids, canonicals, local assets, drafts           |
+| `pnpm run generate-social-images`     | AVIF → JPEG/PNG under `public/social/` only (same logic as the start of `pnpm run build`)     |
+| `pnpm run generate-favicons`          | Favicon assets                                                                                |
+| `pnpm run sync-remark42-rewrite`      | Regenerates the Remark42 rewrite in `vercel.json` from `REMARK42_UPSTREAM_ORIGIN`             |
+| `pnpm run check-remark42-rewrite`     | CI check that `vercel.json`'s Remark42 rewrite matches `REMARK42_UPSTREAM_ORIGIN`             |
+| `pnpm run lighthouse`                 | Lighthouse HTML report against `dist/`; starts and stops its own preview server               |
+| `pnpm run audit-performance`          | Same, performance category only, JSON output                                                  |
 
 CI’s format step **checks**; it does not rewrite or open a follow-up commit. After `pnpm install`, a pre-commit hook runs Prettier on staged files so commits already match that check.
 
+### Generated content contracts
+
+`pnpm run validate-generated-content` runs after a build and parses the emitted
+bytes rather than the source:
+
+- every representative surface's JSON-LD parses and carries `@context` / `@type`
+- `rss.xml` is well-formed XML by a real parser — a substring check passes on an
+  unescaped `&` or an unbalanced tag, which are the faults that break readers
+- feed ids are unique, and RSS and JSON Feed carry the same posts
+- canonical URL, feed entry URL, and JSON-LD identity agree
+- site-local `og:image` targets and internal links resolve to real files
+- drafts, `published: false`, and future-dated posts appear nowhere; public
+  English posts appear everywhere they should; Spanish twins stay out of feeds
+
+Surfaces covered: homepage, `/everything`, `/writing-insights`, an English essay,
+a Spanish twin, and a recipe. External URLs are never fetched — a release must
+not fail because someone else's site is down. Remote link health, if wanted, is a
+separate optional report.
+
+The rules live in `scripts/lib/generated-content-checks.mjs` as pure functions
+with unit tests in `pnpm test`, because the repo has no draft or future-dated
+post to exercise them against.
+
+### Offline behaviour
+
+`public/sw.js` makes one promise: **everything you have already opened stays
+readable offline** — article pages, their images, the browse pages you navigated
+through, and the site's CSS, JS, and fonts. Anything never opened is not
+available offline, and `/offline.html` says so.
+
+It does not pre-download the site. Measured on this build, reader-facing output
+is about 118 MB: 25.9 MB of article HTML across 129 posts (~205 KB per page),
+67.3 MB of images, and ~24 MB of listing pages. Precaching that on a first visit
+would cost more data than most phone plans enjoy and be re-fetched on every
+deploy. Caching as you read reaches the same practical result for a few hundred
+KB per article.
+
+Never cached: `/api/*` (quotes, the Remark42 proxy) is network-only, `/social/*`
+(30.3 MB of Open Graph cards a reader never displays) is skipped entirely, and
+cross-origin requests are left alone.
+
+Caches are named `notes-<kind>-v<version>`, and an upgrade deletes only caches
+carrying that prefix, so a cache belonging to anything else on the origin
+survives. Page, asset, and image caches have entry ceilings (120/120/250),
+trimmed FIFO. `pnpm run test:browser` covers activation, upgrade, the offline
+journeys, and what must never be stored.
+
+### Browser regression journeys
+
+`pnpm run test:browser` drives headless Chromium over the real build output —
+lightbox keyboard journey, search announcements and rapid clear, carousel pause
+including reduced motion, mobile navigation focus return, theme persistence, and
+EN/ES routing — at 390, 768, and 1440 pixels.
+
+It needs a completed `pnpm run build` and does not build for you: building inside
+the test run would make a failure ambiguous between the build and the behavior.
+First run also needs the browser binary:
+
+```bash
+pnpm exec playwright install chromium
+```
+
+These use the `playwright` library through Vitest rather than `@playwright/test`,
+so the repo keeps one test runner. They are a separate command from `pnpm test`
+so the unit suite stays fast. Service workers are blocked in the test context —
+offline behavior needs its own suite with explicit lifecycle steps.
+
 ### Previewing and measuring a build locally
 
 `pnpm run preview` serves `dist/client` from `scripts/serve-dist.mjs`. It shows the
diff --git a/docs/TECHNICAL-AUDIT.md b/docs/TECHNICAL-AUDIT.md
index 90ee3501..de6da18e 100644
--- a/docs/TECHNICAL-AUDIT.md
+++ b/docs/TECHNICAL-AUDIT.md
@@ -119,18 +119,40 @@ No accounts. No server-side reading progress. Constitution principle IV applies.
 
 ## 7. Quality gates (actual vs claimed)
 
-| Gate                                | Status                                                   |
-| ----------------------------------- | -------------------------------------------------------- |
-| `pnpm run format:check`             | CI                                                       |
-| `pnpm run check`                    | CI                                                       |
-| `pnpm run lint`                     | CI                                                       |
-| `pnpm run build`                    | CI (+ social image step)                                 |
-| `pnpm run validate-feeds`           | CI, after the build (needs `dist/`)                      |
-| `pnpm run audit-frontmatter`        | CI, before the build — walks `src/content/p`             |
-| `pnpm run validate-structured-data` | CI — smoke-checks structured-data module surface only    |
-| `pnpm run check-remark42-rewrite`   | CI — `vercel.json` rewrite vs `REMARK42_UPSTREAM_ORIGIN` |
-| Unit tests (`pnpm test`)            | CI — see §9 for coverage                                 |
-| Browser / e2e tests                 | **None** — Playwright is installed but unconfigured      |
+| Gate                                | Status                                                        |
+| ----------------------------------- | ------------------------------------------------------------- |
+| `pnpm run format:check`             | CI                                                            |
+| `pnpm run check`                    | CI — also owns unused locals/params (see below)               |
+| `pnpm run lint`                     | CI — coverage detailed below                                  |
+| `pnpm run build`                    | CI (+ social image step)                                      |
+| `pnpm run validate-feeds`           | CI, after the build (needs `dist/`)                           |
+| `pnpm run audit-frontmatter`        | CI, before the build — walks `src/content/p`                  |
+| `pnpm run validate-structured-data` | CI — smoke-checks structured-data module surface only         |
+| `pnpm run check-remark42-rewrite`   | CI — `vercel.json` rewrite vs `REMARK42_UPSTREAM_ORIGIN`      |
+| Unit tests (`pnpm test`)            | CI — see §9 for coverage                                      |
+| Browser / e2e tests                 | CI — 22 journeys over `dist/client` (`pnpm run test:browser`) |
+
+**Lint coverage (corrected 2026-09-10).** Before this pass `eslint .` reached 131
+files and applied exactly 8 rules to each — all `eslint-plugin-astro` deprecated-API
+checks. `.ts` files matched no config block at all and were skipped silently, plain
+`.js`/`.mjs` got the Astro rules and no JavaScript rules, and
+`src/pages/writing-insights/**` was excluded outright. A green `pnpm run lint`
+therefore established very little.
+
+It now reaches 214 files with a correctness rule set applied to `.js`, `.mjs`,
+`.cjs`, `.ts`, and `.astro`, and no source directory is excluded. Removing the
+Writing Insights exclusion surfaced one real defect: an unescaped `>` in
+`insights.astro` that the Astro compiler tolerates but `astro-eslint-parser`
+cannot parse.
+
+Unused symbols are split by language on purpose. Core `no-unused-vars` cannot read
+TypeScript type positions — it reports every parameter name in a function type as
+an unused argument — so it runs on plain JavaScript only, and `noUnusedLocals` /
+`noUnusedParameters` in `tsconfig.json` cover TypeScript through `astro check`.
+Both halves were confirmed by planting a deliberate violation in each file class.
+
+Still uncovered: type-aware lint rules. Adding `typescript-eslint` would bring
+them, at the cost of a new devDependency.
 
 ---
 
diff --git a/eslint.config.mjs b/eslint.config.mjs
index e84bd586..800dd604 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -1,17 +1,103 @@
 import eslintPluginAstro from 'eslint-plugin-astro';
+import tsParser from '@typescript-eslint/parser';
+
+/**
+ * Correctness-focused core rules. These are ESLint built-ins, so they need no
+ * extra plugin package.
+ *
+ * Two rules are deliberately absent from this shared set:
+ *
+ * - `no-undef` needs a per-environment globals list to be accurate, and the
+ *   `globals` package is not a direct dependency here. TypeScript already
+ *   reports undefined identifiers across `.ts` and `.astro` via `astro check`.
+ * - `no-unused-vars` is applied to plain JavaScript only, further down. The core
+ *   rule cannot read TypeScript type positions, so it reports every parameter
+ *   name in a function *type* — `warn: (message: string) => void` — as an unused
+ *   argument: 45 false positives and no true ones in this repo. `noUnusedLocals`
+ *   and `noUnusedParameters` in `tsconfig.json` cover TypeScript correctly and
+ *   run in CI through `astro check`.
+ */
+const correctnessRules = {
+  // Default 'except-parens' on purpose: it still catches an accidental
+  // `if (a = b)` while permitting the parenthesized `while ((m = re.exec(s)))`
+  // iteration idiom the social-image script uses.
+  'no-cond-assign': 'error',
+  'no-constant-binary-expression': 'error',
+  'no-constant-condition': ['error', { checkLoops: false }],
+  'no-dupe-args': 'error',
+  'no-dupe-else-if': 'error',
+  'no-dupe-keys': 'error',
+  'no-duplicate-case': 'error',
+  'no-empty': ['error', { allowEmptyCatch: true }],
+  'no-fallthrough': 'error',
+  'no-func-assign': 'error',
+  'no-irregular-whitespace': 'error',
+  'no-self-assign': 'error',
+  'no-self-compare': 'error',
+  'no-sparse-arrays': 'error',
+  'no-template-curly-in-string': 'error',
+  // 'no-unmodified-loop-condition' is left off: it cannot see a binding mutated
+  // through a method, so `while (d <= end) { d.setMonth(...) }` in
+  // brainScience/data.ts reads as an infinite loop to it. Not in ESLint's
+  // recommended set for the same reason.
+  'no-unreachable': 'error',
+  'no-unsafe-finally': 'error',
+  'no-unsafe-negation': 'error',
+  'no-unsafe-optional-chaining': 'error',
+  'no-async-promise-executor': 'error',
+  'no-compare-neg-zero': 'error',
+  'use-isnan': 'error',
+  'valid-typeof': 'error',
+};
 
 export default [
   {
-    // Ignore build output, dependencies, and complex Writing Insights dashboards
-    ignores: [
-      'dist/**',
-      'build/**',
-      'coverage/**',
-      '**/*.min.js',
-      'node_modules/**',
-      'src/pages/writing-insights/**',
-    ],
+    // Build output and dependencies only. Source directories are not excluded:
+    // an ignored directory makes a green lint run mean less than it appears to.
+    ignores: ['dist/**', 'build/**', 'coverage/**', '.vercel/**', '**/*.min.js', 'node_modules/**'],
   },
-  // Astro + JavaScript/TypeScript recommended rules for .astro files and scripts
+
+  // Astro's own rules for .astro files.
   ...eslintPluginAstro.configs.recommended,
+
+  // Plain JavaScript: scripts/, public/, and config files. TypeScript does not
+  // check these (`checkJs` is off), so ESLint owns unused symbols here.
+  {
+    files: ['**/*.js', '**/*.mjs', '**/*.cjs'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+    },
+    rules: {
+      ...correctnessRules,
+      'no-unused-vars': [
+        'error',
+        {
+          args: 'after-used',
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          caughtErrors: 'none',
+          ignoreRestSiblings: true,
+        },
+      ],
+    },
+  },
+
+  // TypeScript. Flat config lints no .ts file unless a config block claims it,
+  // so without this entry every .ts file in src/ was silently skipped.
+  {
+    files: ['**/*.ts', '**/*.mts', '**/*.cts'],
+    languageOptions: {
+      parser: tsParser,
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+    },
+    rules: correctnessRules,
+  },
+
+  // The same rules inside .astro frontmatter and <script> blocks.
+  {
+    files: ['**/*.astro'],
+    rules: correctnessRules,
+  },
 ];
diff --git a/package.json b/package.json
index e00f28df..a8c22f65 100644
--- a/package.json
+++ b/package.json
@@ -9,7 +9,7 @@
   "homepage": "https://notes.antoniwan.online",
   "packageManager": "pnpm@12.3.4",
   "engines": {
-    "node": ">=22.12.0",
+    "node": "22.x",
     "pnpm": ">=12"
   },
   "scripts": {
@@ -31,9 +31,11 @@
     "check": "astro check",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:browser": "vitest run --config vitest.browser.config.ts",
     "validate-feeds": "node scripts/validate-feeds.mjs",
     "audit-frontmatter": "node scripts/audit-frontmatter.mjs",
     "validate-structured-data": "node scripts/validate-structured-data.mjs",
+    "validate-generated-content": "node scripts/validate-generated-content.mjs",
     "changelog:since": "node scripts/changelog-since.mjs",
     "sync-remark42-rewrite": "node scripts/sync-remark42-rewrite.mjs",
     "check-remark42-rewrite": "node scripts/sync-remark42-rewrite.mjs --check"
@@ -64,6 +66,7 @@
     "@typescript-eslint/parser": "^8.59.2",
     "eslint": "^10.3.0",
     "eslint-plugin-astro": "^1.7.0",
+    "fast-xml-parser": "5.3.8",
     "lint-staged": "^17.3.0",
     "playwright": "1.55.0",
     "prettier": "^3.8.3",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 9cba005d..4aaa3d41 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -187,6 +187,9 @@ importers:
       eslint-plugin-astro:
         specifier: ^1.7.0
         version: 1.7.0(eslint@10.8.0(jiti@2.7.0)(supports-color@7.2.0))(supports-color@7.2.0)
+      fast-xml-parser:
+        specifier: 5.3.8
+        version: 5.3.8
       lint-staged:
         specifier: ^17.3.0
         version: 17.3.0
diff --git a/public/sw.js b/public/sw.js
index e191e9bb..2cacd7d6 100644
--- a/public/sw.js
+++ b/public/sw.js
@@ -1,98 +1,185 @@
-// Service Worker for Blog
-// Implements advanced caching strategies for better performance
+/**
+ * Service worker for Notes.
+ *
+ * ## The offline promise
+ *
+ * Everything you have already looked at stays readable offline: the article
+ * pages you opened, the images in them, the browse pages you navigated through,
+ * and the site's CSS, JS, and fonts. Anything you have never opened is not
+ * available offline, and the offline page says so.
+ *
+ * It deliberately does NOT pre-download the whole site. Measured against this
+ * build, reader-facing output is roughly 118 MB — 25.9 MB of article HTML across
+ * 129 posts (about 205 KB per page), 67.3 MB of images, and about 24 MB of
+ * listing pages. Precaching that on a first visit would cost a reader more data
+ * than most phone plans enjoy, take minutes, and be re-fetched on every deploy.
+ * Caching as you read gets the same practical result — your reading is available
+ * offline — for a few hundred KB per article.
+ *
+ * `/social/` (30.3 MB of Open Graph cards) is never cached: those exist for
+ * crawlers and link previews, and a reader never displays one.
+ *
+ * ## Cache layout
+ *
+ * Every cache name begins with CACHE_PREFIX. Activation deletes only caches
+ * carrying that prefix from an older version, so a cache belonging to anything
+ * else on this origin survives an upgrade.
+ */
 
 const DEBUG = self.location.hostname === 'localhost' || self.location.hostname === '127.0.0.1';
 
 const SW_VERSION = new URL(self.location.href).searchParams.get('v') || 'dev';
-const CACHE_NAME = `blog-v${SW_VERSION}`;
-const STATIC_CACHE = `static-v${SW_VERSION}`;
-const DYNAMIC_CACHE = `dynamic-v${SW_VERSION}`;
-
-// Files to cache immediately
-const STATIC_FILES = [
+const CACHE_PREFIX = 'notes-';
+const SHELL_CACHE = `${CACHE_PREFIX}shell-v${SW_VERSION}`;
+const ASSET_CACHE = `${CACHE_PREFIX}assets-v${SW_VERSION}`;
+const PAGE_CACHE = `${CACHE_PREFIX}pages-v${SW_VERSION}`;
+const IMAGE_CACHE = `${CACHE_PREFIX}images-v${SW_VERSION}`;
+
+const OWNED_CACHES = new Set([SHELL_CACHE, ASSET_CACHE, PAGE_CACHE, IMAGE_CACHE]);
+
+/**
+ * Entry ceilings. The Cache API returns keys in insertion order, so trimming
+ * from the front is FIFO, not true LRU — a page you reread often can still be
+ * evicted. That is an accepted trade for not tracking access times.
+ */
+const CACHE_LIMITS = {
+  [ASSET_CACHE]: 120,
+  [PAGE_CACHE]: 120,
+  [IMAGE_CACHE]: 250,
+};
+
+/** Small enough to fetch on install without making the first visit feel slow. */
+const SHELL_FILES = [
   '/',
   '/offline.html',
   '/images/default.avif',
   '/favicon.ico',
   '/favicon.svg',
   '/apple-touch-icon.png',
-  // Note: CSS files are dynamically generated by Astro, so we cache them
-  // via the handleStaticAsset function rather than pre-caching here
 ];
 
-// Install event - cache static files
+const ASSET_EXTENSIONS = /\.(css|js|mjs|woff2?|ttf|otf|eot)$/i;
+// AVIF is this site's primary image format. Its absence from the old matcher
+// meant no article image was ever cached.
+const IMAGE_EXTENSIONS = /\.(avif|webp|png|jpe?g|gif|svg|ico)$/i;
+
+function log(...args) {
+  if (DEBUG) console.log('[sw]', ...args);
+}
+
 self.addEventListener('install', (event) => {
   event.waitUntil(
-    caches
-      .open(STATIC_CACHE)
-      .then((cache) => {
-        if (DEBUG) console.log('Caching static files');
-        return cache.addAll(STATIC_FILES);
-      })
-      .then(() => {
-        if (DEBUG) console.log('Static files cached successfully');
-        return self.skipWaiting();
-      })
-      .catch((error) => {
-        if (DEBUG) console.error('Failed to cache static files:', error);
-      }),
+    (async () => {
+      const cache = await caches.open(SHELL_CACHE);
+      // Individually, so one missing file cannot fail the whole install the way
+      // cache.addAll() would.
+      await Promise.all(
+        SHELL_FILES.map(async (file) => {
+          try {
+            const response = await fetch(file, { cache: 'reload' });
+            if (response.ok) await cache.put(file, response);
+          } catch (error) {
+            log('shell fetch failed', file, error);
+          }
+        }),
+      );
+      await self.skipWaiting();
+    })(),
   );
 });
 
-// Activate event - clean up old caches
 self.addEventListener('activate', (event) => {
   event.waitUntil(
-    caches
-      .keys()
-      .then((cacheNames) => {
-        return Promise.all(
-          cacheNames.map((cacheName) => {
-            if (cacheName !== STATIC_CACHE && cacheName !== DYNAMIC_CACHE) {
-              if (DEBUG) console.log('Deleting old cache:', cacheName);
-              return caches.delete(cacheName);
-            }
-          }),
-        );
-      })
-      .then(() => {
-        if (DEBUG) console.log('Service Worker activated');
-        return self.clients.claim();
-      }),
+    (async () => {
+      const names = await caches.keys();
+      await Promise.all(
+        names.map((name) => {
+          // Only this worker's own caches are eligible for deletion. The old
+          // code deleted every cache on the origin except its current two.
+          if (!name.startsWith(CACHE_PREFIX)) return undefined;
+          if (OWNED_CACHES.has(name)) return undefined;
+          log('deleting stale cache', name);
+          return caches.delete(name);
+        }),
+      );
+      await self.clients.claim();
+    })(),
   );
 });
 
-// Fetch event - implement caching strategies
+/** Drops the oldest entries once a cache passes its ceiling. */
+async function trimCache(cacheName) {
+  const limit = CACHE_LIMITS[cacheName];
+  if (!limit) return;
+  const cache = await caches.open(cacheName);
+  const keys = await cache.keys();
+  if (keys.length <= limit) return;
+  const excess = keys.slice(0, keys.length - limit);
+  await Promise.all(excess.map((key) => cache.delete(key)));
+  log('trimmed', cacheName, 'by', excess.length);
+}
+
+/** Stores a response and enforces the ceiling. Awaited by every caller. */
+async function putAndTrim(cacheName, request, response) {
+  const cache = await caches.open(cacheName);
+  await cache.put(request, response);
+  await trimCache(cacheName);
+}
+
+function isSameOrigin(url) {
+  return url.origin === self.location.origin;
+}
+
+/** Open Graph artwork: crawler-facing, never displayed to a reader. */
+function isSocialCard(url) {
+  return url.pathname.startsWith('/social/');
+}
+
+function isDocumentRequest(request) {
+  return request.mode === 'navigate' || (request.headers.get('accept') || '').includes('text/html');
+}
+
 self.addEventListener('fetch', (event) => {
   const { request } = event;
+  if (request.method !== 'GET') return;
+
   const url = new URL(request.url);
+  if (!url.protocol.startsWith('http')) return;
+
+  // Cross-origin traffic — comment avatars, embeds — is left entirely alone.
+  // The old asset matcher keyed off the file extension and would happily store
+  // another origin's files in this site's cache.
+  if (!isSameOrigin(url)) return;
 
-  // Skip non-GET requests
-  if (request.method !== 'GET') {
+  if (url.pathname.startsWith('/api/')) {
+    event.respondWith(handleApiRequest(request));
     return;
   }
 
-  // Skip chrome-extension and other non-http requests
-  if (!url.protocol.startsWith('http')) {
+  if (isSocialCard(url)) return;
+
+  if (IMAGE_EXTENSIONS.test(url.pathname)) {
+    event.respondWith(cacheFirst(event, IMAGE_CACHE));
     return;
   }
 
-  // Handle different types of requests
-  if (url.pathname.startsWith('/api/')) {
-    // Never cache API traffic (random quotes, Remark42 proxy). Network-only.
-    event.respondWith(handleApiRequest(request));
-  } else if (url.pathname.match(/\.(css|js|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot)$/)) {
-    // Static assets - cache first, fallback to network
-    event.respondWith(handleStaticAsset(request));
-  } else if (url.pathname.startsWith('/p/') || url.pathname === '/') {
-    // Blog posts and pages - network first, fallback to cache
-    event.respondWith(handlePageRequest(request));
-  } else {
-    // Other requests - network first
-    event.respondWith(fetch(request));
+  if (ASSET_EXTENSIONS.test(url.pathname)) {
+    event.respondWith(cacheFirst(event, ASSET_CACHE));
+    return;
+  }
+
+  if (isDocumentRequest(request)) {
+    // Every browse page, not just '/' and '/p/'. Category, tag, Cookbook,
+    // Everything, and the static pages were previously passed straight to the
+    // network with no offline behavior at all.
+    event.respondWith(handlePageRequest(event));
+    return;
   }
+
+  // Anything else (feeds, sitemap, manifest) goes to the network untouched.
 });
 
-// Handle API requests — network only (do not put responses in Cache Storage)
+/** Quotes and the Remark42 proxy are network-only; nothing is ever stored. */
 async function handleApiRequest(request) {
   try {
     return await fetch(request);
@@ -108,195 +195,89 @@ async function handleApiRequest(request) {
   }
 }
 
-// Handle static assets — stale-while-revalidate: serve from cache instantly,
-// but always fetch a fresh copy in the background to keep the cache current.
-async function handleStaticAsset(request) {
-  const cache = await caches.open(STATIC_CACHE);
-  const cachedResponse = await cache.match(request);
-
-  const networkFetch = fetch(request)
-    .then((response) => {
-      if (response.ok) {
-        cache.put(request, response.clone());
-      }
+/**
+ * Serve from cache, then refresh in the background.
+ *
+ * The revalidation is attached to the event, so the browser keeps the worker
+ * alive until the write finishes. Previously it was a floating promise whose
+ * cache.put was never awaited, so a worker that shut down after responding could
+ * lose the update.
+ */
+async function cacheFirst(event, cacheName) {
+  const { request } = event;
+  const cache = await caches.open(cacheName);
+  const cached = await cache.match(request);
+
+  const revalidate = (async () => {
+    try {
+      const response = await fetch(request);
+      if (response.ok) await putAndTrim(cacheName, request, response.clone());
       return response;
-    })
-    .catch((error) => {
-      if (DEBUG) console.log('Background revalidation failed:', request.url, error);
+    } catch (error) {
+      log('revalidate failed', request.url, error);
       return null;
-    });
+    }
+  })();
 
-  if (cachedResponse) {
-    // Serve cached version immediately; network fetch updates cache in background
-    return cachedResponse;
+  if (cached) {
+    event.waitUntil(revalidate);
+    return cached;
   }
 
-  // Nothing in cache — wait for the network
-  const networkResponse = await networkFetch;
-  if (networkResponse) {
-    return networkResponse;
-  }
+  const network = await revalidate;
+  if (network) return network;
 
-  // Offline fallback for styles/fonts
-  if (request.url.includes('/styles/') || request.url.includes('/fonts/')) {
-    return new Response('/* Offline - styles not available */', {
-      status: 200,
-      statusText: 'OK',
-      headers: { 'Content-Type': 'text/css' },
-    });
+  // Offline with nothing stored. A placeholder is better than a broken image
+  // for article artwork; everything else gets an honest error.
+  if (IMAGE_EXTENSIONS.test(new URL(request.url).pathname)) {
+    const fallback = await caches.match('/images/default.avif');
+    if (fallback) return fallback;
   }
-
-  throw new Error('Network unavailable and no cache for: ' + request.url);
+  return Response.error();
 }
 
-// Handle page requests
-async function handlePageRequest(request) {
+/**
+ * Pages are network-first so a reader online always sees current content, with
+ * the cached copy as the offline fallback.
+ */
+async function handlePageRequest(event) {
+  const { request } = event;
+
   try {
     const response = await fetch(request);
-
-    // Cache successful page responses
     if (response.ok) {
-      const cache = await caches.open(DYNAMIC_CACHE);
-      cache.put(request, response.clone());
+      event.waitUntil(putAndTrim(PAGE_CACHE, request, response.clone()));
     }
-
     return response;
-  } catch (error) {
-    // Fallback to cache
-    const cachedResponse = await caches.match(request);
-    if (cachedResponse) {
-      return cachedResponse;
-    }
+  } catch {
+    const cached = await caches.match(request, { ignoreSearch: true });
+    if (cached) return cached;
 
-    // Return offline page
-    const offlineResponse = await caches.match('/offline.html');
-    if (offlineResponse) {
-      return offlineResponse;
-    }
+    const offline = await caches.match('/offline.html');
+    if (offline) return offline;
 
-    // Fallback offline content
     return new Response(
-      `
-      <!DOCTYPE html>
-      <html lang="en">
-        <head>
-          <meta charset="utf-8">
-          <meta name="viewport" content="width=device-width, initial-scale=1.0">
-          <title>Offline - Notes</title>
-          <style>
-            body { 
-              font-family: system-ui, sans-serif; 
-              text-align: center; 
-              padding: 2rem; 
-              background: #f3f4f6; 
-              color: #1f2937;
-            }
-            .container { max-width: 600px; margin: 0 auto; }
-            h1 { color: #dc2626; }
-            .btn { 
-              display: inline-block; 
-              padding: 0.75rem 1.5rem; 
-              background: #3b82f6; 
-              color: white; 
-              text-decoration: none; 
-              border-radius: 0.5rem; 
-              margin-top: 1rem;
-            }
-          </style>
-        </head>
-        <body>
-          <div class="container">
-            <h1>You're Offline</h1>
-            <p>The page you're looking for isn't available offline. Please check your connection and try again.</p>
-            <a href="/" class="btn">Go Home</a>
-          </div>
-        </body>
-      </html>
-      `,
-      {
-        status: 200,
-        statusText: 'OK',
-        headers: { 'Content-Type': 'text/html' },
-      },
+      '<!doctype html><meta charset="utf-8">' +
+        '<title>Offline</title>' +
+        '<p>This page is not available offline. Pages you have already opened are.</p>',
+      { status: 503, headers: { 'Content-Type': 'text/html; charset=utf-8' } },
     );
   }
 }
 
-// Background sync for offline actions
-self.addEventListener('sync', (event) => {
-  if (event.tag === 'background-sync') {
-    event.waitUntil(doBackgroundSync());
-  }
-});
-
-// Handle background sync
-async function doBackgroundSync() {
-  try {
-    // Perform any background tasks
-    if (DEBUG) console.log('Performing background sync');
-
-    // Example: sync offline data
-    const cache = await caches.open(DYNAMIC_CACHE);
-    const requests = await cache.keys();
-
-    for (const request of requests) {
-      if (request.url.includes('/api/')) {
-        try {
-          await fetch(request);
-          await cache.delete(request);
-        } catch (error) {
-          if (DEBUG) console.log('Failed to sync request:', request.url);
-        }
-      }
-    }
-  } catch (error) {
-    if (DEBUG) console.error('Background sync failed:', error);
-  }
-}
-
-// Handle push notifications
-self.addEventListener('push', (event) => {
-  if (event.data) {
-    const data = event.data.json();
-
-    const options = {
-      body: data.body || 'New content available on Blog',
-      icon: '/favicon-192x192.png',
-      badge: '/favicon-192x192.png',
-      data: data.url || '/',
-      actions: [
-        {
-          action: 'view',
-          title: 'View',
-          icon: '/favicon-192x192.png',
-        },
-        {
-          action: 'dismiss',
-          title: 'Dismiss',
-        },
-      ],
-    };
-
-    event.waitUntil(self.registration.showNotification('Blog', options));
-  }
-});
+// No push, notification, or background-sync handlers: nothing in the site uses
+// them. The previous background-sync handler walked the page cache deleting
+// '/api/' entries, which cannot exist because API traffic is never stored.
 
-// Handle notification clicks
-self.addEventListener('notificationclick', (event) => {
-  event.notification.close();
-
-  if (event.action === 'view') {
-    event.waitUntil(clients.openWindow(event.notification.data));
-  }
-});
-
-// Message handling for communication with main thread
 self.addEventListener('message', (event) => {
-  if (event.data && event.data.type === 'SKIP_WAITING') {
+  const data = event.data;
+  if (!data) return;
+
+  if (data.type === 'SKIP_WAITING') {
     self.skipWaiting();
   }
 
-  if (event.data && event.data.type === 'GET_VERSION') {
-    event.ports[0].postMessage({ version: CACHE_NAME });
+  if (data.type === 'GET_VERSION' && event.ports && event.ports[0]) {
+    event.ports[0].postMessage({ version: SW_VERSION, caches: [...OWNED_CACHES] });
   }
 });
diff --git a/scripts/lib/generated-content-checks.mjs b/scripts/lib/generated-content-checks.mjs
new file mode 100644
index 00000000..affe162d
--- /dev/null
+++ b/scripts/lib/generated-content-checks.mjs
@@ -0,0 +1,235 @@
+import {
+  isPublicMeta,
+  isSpanishPrimaryMeta,
+  normalizePostMeta,
+} from '../../src/utils/publishEligibility.mjs';
+
+/**
+ * Contract checks for the generated site.
+ *
+ * These are pure functions over already-extracted data so they can be unit
+ * tested against synthetic bad input. The repo has no draft, unpublished, or
+ * future-dated post today, so a real artifact run cannot demonstrate that the
+ * draft rule bites — the unit tests are what establish that, and
+ * `validate-generated-content.mjs` applies the same functions to the real build.
+ *
+ * Every function returns an array of human-readable problem strings. Empty means
+ * the contract holds.
+ */
+
+/** JSON-LD every page is expected to carry. */
+export const REQUIRED_SITE_SCHEMA_TYPES = ['WebSite', 'Organization'];
+
+/**
+ * Parses and shallow-validates JSON-LD blocks lifted from one page.
+ *
+ * @param {string[]} blocks raw text of each ld+json script
+ * @param {{ label: string, requiredTypes?: string[] }} context
+ */
+export function checkJsonLd(blocks, { label, requiredTypes = [] }) {
+  const problems = [];
+
+  if (blocks.length === 0) {
+    problems.push(`${label}: no application/ld+json blocks emitted`);
+    return problems;
+  }
+
+  const seenTypes = new Set();
+
+  blocks.forEach((raw, index) => {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (error) {
+      problems.push(`${label}: ld+json block ${index + 1} is not valid JSON (${error.message})`);
+      return;
+    }
+
+    // A block may be a graph or a single node; normalize before inspecting.
+    const nodes = Array.isArray(parsed) ? parsed : [parsed];
+    for (const node of nodes) {
+      if (!node || typeof node !== 'object') {
+        problems.push(`${label}: ld+json block ${index + 1} is not an object`);
+        continue;
+      }
+      if (!node['@context']) {
+        problems.push(`${label}: ld+json block ${index + 1} is missing @context`);
+      }
+      if (!node['@type']) {
+        problems.push(`${label}: ld+json block ${index + 1} is missing @type`);
+        continue;
+      }
+      for (const type of Array.isArray(node['@type']) ? node['@type'] : [node['@type']]) {
+        seenTypes.add(type);
+      }
+    }
+  });
+
+  for (const type of requiredTypes) {
+    if (!seenTypes.has(type)) {
+      problems.push(`${label}: expected ld+json @type ${type}, found ${[...seenTypes].join(', ')}`);
+    }
+  }
+
+  return problems;
+}
+
+/**
+ * Feed entries must be uniquely identified. A duplicate id makes readers merge
+ * or drop posts, and it is invisible in a byte-count check.
+ *
+ * @param {{ id?: string, url?: string, title?: string }[]} items
+ */
+export function checkFeedIdsUnique(items, label) {
+  const problems = [];
+  const seen = new Map();
+
+  items.forEach((item, index) => {
+    const id = item.id ?? item.url;
+    if (!id) {
+      problems.push(`${label}: item ${index + 1} has neither id nor url`);
+      return;
+    }
+    if (seen.has(id)) {
+      problems.push(
+        `${label}: duplicate id ${id} (items ${seen.get(id) + 1} and ${index + 1}: ` +
+          `${item.title ?? 'untitled'})`,
+      );
+      return;
+    }
+    seen.set(id, index);
+  });
+
+  return problems;
+}
+
+/**
+ * Publication rules come from the shared module rather than a copy. These two
+ * wrappers keep this file's frontmatter-shaped call sites readable.
+ */
+export function isPublicFrontmatter(data, now = new Date()) {
+  return isPublicMeta(normalizePostMeta(data), { now });
+}
+
+/** Feeds and listings carry English posts only; Spanish stays reachable by URL. */
+export function isSpanishPrimaryFrontmatter(data) {
+  return isSpanishPrimaryMeta(normalizePostMeta(data));
+}
+
+/**
+ * Nothing withheld may be published, and nothing public may go missing.
+ *
+ * @param {{ slug: string, data: object }[]} posts source frontmatter
+ * @param {Set<string>} emittedSlugs slugs with an emitted page in dist
+ * @param {Set<string>} feedSlugs slugs present in the feeds
+ */
+export function checkPublishEligibility(posts, emittedSlugs, feedSlugs, now = new Date()) {
+  const problems = [];
+
+  for (const { slug, data } of posts) {
+    const isPublic = isPublicFrontmatter(data, now);
+    const emitted = emittedSlugs.has(slug);
+    const inFeed = feedSlugs.has(slug);
+
+    if (!isPublic) {
+      const reason = data.draft
+        ? 'draft'
+        : data.published === false
+          ? 'published: false'
+          : 'future pubDate';
+      if (emitted) problems.push(`${slug}: withheld (${reason}) but a page was emitted`);
+      if (inFeed) problems.push(`${slug}: withheld (${reason}) but it appears in a feed`);
+      continue;
+    }
+
+    if (!emitted) problems.push(`${slug}: public but no page was emitted`);
+
+    if (isSpanishPrimaryFrontmatter(data)) {
+      if (inFeed) problems.push(`${slug}: Spanish-primary post must not appear in the feeds`);
+    } else if (!inFeed) {
+      problems.push(`${slug}: public English post is missing from the feeds`);
+    }
+  }
+
+  return problems;
+}
+
+/**
+ * Site-local asset references must resolve to a file in the output. External
+ * URLs are ignored on purpose: the audit asked that this gate never depend on
+ * other websites being reachable.
+ *
+ * @param {{ label: string, url: string }[]} references
+ * @param {(sitePath: string) => boolean} exists
+ * @param {string} siteOrigin
+ */
+export function checkLocalAssets(references, exists, siteOrigin) {
+  const problems = [];
+
+  for (const { label, url } of references) {
+    if (!url) continue;
+
+    let sitePath = null;
+    if (url.startsWith('/')) sitePath = url;
+    else if (siteOrigin && url.startsWith(siteOrigin)) sitePath = url.slice(siteOrigin.length);
+    // Anything else is off-site and deliberately not our problem here.
+    if (!sitePath) continue;
+
+    const clean = sitePath.split('?')[0].split('#')[0];
+    if (!exists(clean)) problems.push(`${label}: local asset ${clean} has no file in the output`);
+  }
+
+  return problems;
+}
+
+/**
+ * The canonical URL, the feed entry URL, and the JSON-LD identity have to agree,
+ * or the same post is three different documents to a crawler.
+ */
+export function checkCanonicalConsistency({ label, canonical, feedUrl, jsonLdUrl }) {
+  const problems = [];
+
+  if (!canonical) {
+    problems.push(`${label}: no canonical link emitted`);
+    return problems;
+  }
+
+  const normalize = (url) => (url ? url.replace(/\/+$/, '') : url);
+  const base = normalize(canonical);
+
+  if (feedUrl && normalize(feedUrl) !== base) {
+    problems.push(`${label}: feed url ${feedUrl} disagrees with canonical ${canonical}`);
+  }
+  if (jsonLdUrl && normalize(jsonLdUrl) !== base) {
+    problems.push(`${label}: ld+json url ${jsonLdUrl} disagrees with canonical ${canonical}`);
+  }
+
+  return problems;
+}
+
+/**
+ * Site-internal links in a page must resolve, except paths the host redirects.
+ *
+ * @param {string[]} hrefs
+ * @param {(sitePath: string) => boolean} exists
+ * @param {string[]} redirectPrefixes paths owned by vercel.json / seoRouting
+ */
+export function checkLocalLinks(hrefs, exists, redirectPrefixes = [], label = 'page') {
+  const problems = [];
+  const seen = new Set();
+
+  for (const href of hrefs) {
+    if (!href || !href.startsWith('/') || href.startsWith('//')) continue;
+
+    const clean = href.split('?')[0].split('#')[0];
+    if (!clean || clean === '/' || seen.has(clean)) continue;
+    seen.add(clean);
+
+    // Host-level redirects have no file in the output by design.
+    if (redirectPrefixes.some((prefix) => clean === prefix || clean.startsWith(prefix))) continue;
+
+    if (!exists(clean)) problems.push(`${label}: internal link ${clean} resolves to nothing`);
+  }
+
+  return problems;
+}
diff --git a/scripts/lib/generated-content-checks.test.mjs b/scripts/lib/generated-content-checks.test.mjs
new file mode 100644
index 00000000..e16ebd8c
--- /dev/null
+++ b/scripts/lib/generated-content-checks.test.mjs
@@ -0,0 +1,225 @@
+import { describe, expect, test } from 'vitest';
+
+import {
+  checkCanonicalConsistency,
+  checkFeedIdsUnique,
+  checkJsonLd,
+  checkLocalAssets,
+  checkLocalLinks,
+  checkPublishEligibility,
+  isPublicFrontmatter,
+  isSpanishPrimaryFrontmatter,
+} from './generated-content-checks.mjs';
+
+const ORIGIN = 'https://notes.antoniwan.online';
+
+describe('checkJsonLd', () => {
+  test('accepts well-formed blocks that carry the required types', () => {
+    const blocks = [
+      JSON.stringify({ '@context': 'https://schema.org', '@type': 'WebSite', name: 'Notes' }),
+      JSON.stringify({ '@context': 'https://schema.org', '@type': 'Organization', name: 'Notes' }),
+    ];
+    expect(
+      checkJsonLd(blocks, { label: 'page', requiredTypes: ['WebSite', 'Organization'] }),
+    ).toEqual([]);
+  });
+
+  test('rejects malformed JSON', () => {
+    const problems = checkJsonLd(['{ "@type": "WebSite", }'], { label: 'page' });
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toMatch(/not valid JSON/);
+  });
+
+  test('rejects a block missing @context or @type', () => {
+    expect(checkJsonLd([JSON.stringify({ '@type': 'WebSite' })], { label: 'page' })[0]).toMatch(
+      /missing @context/,
+    );
+    expect(
+      checkJsonLd([JSON.stringify({ '@context': 'https://schema.org' })], { label: 'page' })[0],
+    ).toMatch(/missing @type/);
+  });
+
+  test('rejects a page with no JSON-LD at all', () => {
+    expect(checkJsonLd([], { label: 'page' })[0]).toMatch(/no application\/ld\+json/);
+  });
+
+  test('reads a @graph-style array and a required type it does not contain', () => {
+    const blocks = [
+      JSON.stringify([
+        { '@context': 'https://schema.org', '@type': 'WebSite' },
+        { '@context': 'https://schema.org', '@type': 'Person' },
+      ]),
+    ];
+    expect(checkJsonLd(blocks, { label: 'page', requiredTypes: ['WebSite'] })).toEqual([]);
+    expect(checkJsonLd(blocks, { label: 'page', requiredTypes: ['Organization'] })[0]).toMatch(
+      /expected ld\+json @type Organization/,
+    );
+  });
+});
+
+describe('checkFeedIdsUnique', () => {
+  test('accepts distinct ids', () => {
+    const items = [
+      { id: 'a', url: '/p/a' },
+      { id: 'b', url: '/p/b' },
+    ];
+    expect(checkFeedIdsUnique(items, 'feed')).toEqual([]);
+  });
+
+  test('rejects a duplicate id', () => {
+    const items = [
+      { id: 'a', url: '/p/a', title: 'First' },
+      { id: 'a', url: '/p/a-again', title: 'Second' },
+    ];
+    const problems = checkFeedIdsUnique(items, 'feed');
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toMatch(/duplicate id a/);
+  });
+
+  test('rejects an item with no identity at all', () => {
+    expect(checkFeedIdsUnique([{ title: 'orphan' }], 'feed')[0]).toMatch(/neither id nor url/);
+  });
+});
+
+describe('publication eligibility', () => {
+  const now = new Date('2026-09-10T00:00:00Z');
+  const live = { pubDate: '2026-01-01' };
+
+  test('classifies frontmatter the way publishFilters does', () => {
+    expect(isPublicFrontmatter(live, now)).toBe(true);
+    expect(isPublicFrontmatter({ ...live, draft: true }, now)).toBe(false);
+    expect(isPublicFrontmatter({ ...live, published: false }, now)).toBe(false);
+    expect(isPublicFrontmatter({ pubDate: '2027-01-01' }, now)).toBe(false);
+    expect(isSpanishPrimaryFrontmatter({ language: ['es'] })).toBe(true);
+    expect(isSpanishPrimaryFrontmatter({ language: ['en', 'es'] })).toBe(false);
+    expect(isSpanishPrimaryFrontmatter({})).toBe(false);
+  });
+
+  test('accepts a build where every post is where it belongs', () => {
+    const posts = [
+      { slug: 'essay', data: live },
+      { slug: 'ensayo', data: { ...live, language: ['es'] } },
+      { slug: 'wip', data: { ...live, draft: true } },
+    ];
+    // The Spanish twin gets a page but no feed entry; the draft gets neither.
+    const problems = checkPublishEligibility(
+      posts,
+      new Set(['essay', 'ensayo']),
+      new Set(['essay']),
+      now,
+    );
+    expect(problems).toEqual([]);
+  });
+
+  test('fails when a draft is published — the fixture the audit asked for', () => {
+    const posts = [{ slug: 'wip', data: { ...live, draft: true } }];
+    const problems = checkPublishEligibility(posts, new Set(['wip']), new Set(['wip']), now);
+    expect(problems).toHaveLength(2);
+    expect(problems[0]).toMatch(/withheld \(draft\) but a page was emitted/);
+    expect(problems[1]).toMatch(/withheld \(draft\) but it appears in a feed/);
+  });
+
+  test('fails when a future-dated post leaks out', () => {
+    const posts = [{ slug: 'embargoed', data: { pubDate: '2027-06-01' } }];
+    const problems = checkPublishEligibility(posts, new Set(['embargoed']), new Set(), now);
+    expect(problems[0]).toMatch(/withheld \(future pubDate\) but a page was emitted/);
+  });
+
+  test('fails when published: false leaks out', () => {
+    const posts = [{ slug: 'pulled', data: { ...live, published: false } }];
+    const problems = checkPublishEligibility(posts, new Set(['pulled']), new Set(), now);
+    expect(problems[0]).toMatch(/withheld \(published: false\) but a page was emitted/);
+  });
+
+  test('fails when a Spanish-primary post reaches the English feeds', () => {
+    const posts = [{ slug: 'ensayo', data: { ...live, language: ['es'] } }];
+    const problems = checkPublishEligibility(posts, new Set(['ensayo']), new Set(['ensayo']), now);
+    expect(problems[0]).toMatch(/Spanish-primary post must not appear in the feeds/);
+  });
+
+  test('fails when a public English post goes missing', () => {
+    const posts = [{ slug: 'essay', data: live }];
+    expect(checkPublishEligibility(posts, new Set(), new Set(), now)).toEqual([
+      'essay: public but no page was emitted',
+      'essay: public English post is missing from the feeds',
+    ]);
+  });
+});
+
+describe('checkLocalAssets', () => {
+  const exists = (sitePath) => sitePath === '/images/real.avif';
+
+  test('accepts a local asset that exists, by path or by absolute URL', () => {
+    expect(
+      checkLocalAssets(
+        [
+          { label: 'a', url: '/images/real.avif' },
+          { label: 'b', url: `${ORIGIN}/images/real.avif` },
+        ],
+        exists,
+        ORIGIN,
+      ),
+    ).toEqual([]);
+  });
+
+  test('rejects a local asset with no file behind it', () => {
+    const problems = checkLocalAssets([{ label: 'og', url: '/images/gone.avif' }], exists, ORIGIN);
+    expect(problems[0]).toMatch(/local asset \/images\/gone\.avif has no file/);
+  });
+
+  test('ignores off-site URLs so the gate never depends on another website', () => {
+    expect(
+      checkLocalAssets([{ label: 'x', url: 'https://example.com/a.png' }], exists, ORIGIN),
+    ).toEqual([]);
+  });
+});
+
+describe('checkCanonicalConsistency', () => {
+  const canonical = `${ORIGIN}/p/essay`;
+
+  test('accepts agreement, ignoring a trailing slash', () => {
+    expect(
+      checkCanonicalConsistency({
+        label: 'p',
+        canonical,
+        feedUrl: `${ORIGIN}/p/essay/`,
+        jsonLdUrl: canonical,
+      }),
+    ).toEqual([]);
+  });
+
+  test('rejects a feed URL that points somewhere else', () => {
+    const problems = checkCanonicalConsistency({
+      label: 'p',
+      canonical,
+      feedUrl: `${ORIGIN}/posts/essay`,
+    });
+    expect(problems[0]).toMatch(/disagrees with canonical/);
+  });
+
+  test('rejects a page with no canonical link', () => {
+    expect(checkCanonicalConsistency({ label: 'p', canonical: null })[0]).toMatch(/no canonical/);
+  });
+});
+
+describe('checkLocalLinks', () => {
+  const exists = (sitePath) => sitePath === '/about';
+
+  test('rejects an internal link that resolves to nothing', () => {
+    const problems = checkLocalLinks(['/about', '/ghost'], exists, [], 'page');
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toMatch(/\/ghost resolves to nothing/);
+  });
+
+  test('skips host-level redirects, which have no file by design', () => {
+    expect(checkLocalLinks(['/api/quotes', '/rss.xml'], exists, ['/api/', '/rss.xml'])).toEqual([]);
+  });
+
+  test('ignores external and protocol-relative links', () => {
+    expect(checkLocalLinks(['https://example.com', '//cdn.example.com/x'], exists)).toEqual([]);
+  });
+
+  test('reports a broken link once even when it appears repeatedly', () => {
+    expect(checkLocalLinks(['/ghost', '/ghost#a', '/ghost?b=1'], exists)).toHaveLength(1);
+  });
+});
diff --git a/scripts/serve-dist.mjs b/scripts/serve-dist.mjs
index c4bc1bb3..04e433e2 100644
--- a/scripts/serve-dist.mjs
+++ b/scripts/serve-dist.mjs
@@ -88,7 +88,12 @@ export function createDistServer() {
   });
 }
 
-/** Starts the server, rejecting with a readable message on a busy port. */
+/**
+ * Starts the server and resolves with its origin.
+ *
+ * Port 0 asks the OS for a free port, so the origin is read back from the bound
+ * address rather than from the requested port.
+ */
 export function listen(server, { host, port }) {
   return new Promise((ready, reject) => {
     server.once('error', (error) => {
@@ -98,7 +103,11 @@ export function listen(server, { host, port }) {
       }
       reject(error);
     });
-    server.listen(port, host, () => ready(`http://${host}:${port}`));
+    server.listen(port, host, () => {
+      const address = server.address();
+      const boundPort = typeof address === 'object' && address ? address.port : port;
+      ready(`http://${host}:${boundPort}`);
+    });
   });
 }
 
diff --git a/scripts/validate-generated-content.mjs b/scripts/validate-generated-content.mjs
new file mode 100644
index 00000000..d578de7b
--- /dev/null
+++ b/scripts/validate-generated-content.mjs
@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+/**
+ * Validates the generated site against its content contracts. Run after
+ * `pnpm run build`.
+ *
+ * This is the artifact-level counterpart to `validate-structured-data.mjs`,
+ * which only greps the source module for export names and therefore cannot say
+ * whether a layout wired those utilities correctly. Here the emitted bytes are
+ * parsed:
+ *
+ * - every representative page's JSON-LD parses and carries @context / @type
+ * - RSS is well-formed XML, by a real parser, not a substring search
+ * - feed ids are unique across RSS and JSON Feed
+ * - canonical URL, feed entry URL, and JSON-LD identity agree
+ * - site-local images and internal links resolve to real files
+ * - drafts, unpublished, and future-dated posts are absent from pages and feeds,
+ *   and public English posts are present
+ *
+ * External URLs are never fetched. A release must not fail because someone
+ * else's website is down.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import yaml from 'js-yaml';
+import { XMLParser, XMLValidator } from 'fast-xml-parser';
+
+import {
+  checkCanonicalConsistency,
+  checkFeedIdsUnique,
+  checkJsonLd,
+  checkLocalAssets,
+  checkLocalLinks,
+  checkPublishEligibility,
+  REQUIRED_SITE_SCHEMA_TYPES,
+} from './lib/generated-content-checks.mjs';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SITE_ORIGIN = 'https://notes.antoniwan.online';
+
+/**
+ * Paths served by host-level redirects or the on-demand route, so they have no
+ * file in the static output and must not be reported as broken links.
+ */
+const REDIRECT_PREFIXES = ['/api/', '/rss.xml', '/sitemap.xml', '/sitemap-index.xml'];
+
+const problems = [];
+const notes = [];
+
+function findDistRoot() {
+  for (const dir of [path.join(root, 'dist', 'client'), path.join(root, 'dist')]) {
+    if (fs.existsSync(path.join(dir, 'index.html'))) return dir;
+  }
+  return null;
+}
+
+const dist = findDistRoot();
+if (!dist) {
+  console.error('validate-generated-content: no built output — run `pnpm run build` first');
+  process.exit(1);
+}
+
+/** True when a site path corresponds to a file in the output. */
+function outputHas(sitePath) {
+  const clean = decodeURIComponent(sitePath).replace(/^\/+/, '');
+  const direct = path.join(dist, clean);
+  if (fs.existsSync(direct) && fs.statSync(direct).isFile()) return true;
+  const asDirectory = path.join(dist, clean, 'index.html');
+  return fs.existsSync(asDirectory) && fs.statSync(asDirectory).isFile();
+}
+
+// --- Page-level extraction ---------------------------------------------------
+
+function readPage(sitePath) {
+  const file = path.join(dist, sitePath.replace(/^\/+/, ''), 'index.html');
+  const indexFile = sitePath === '/' ? path.join(dist, 'index.html') : file;
+  if (!fs.existsSync(indexFile)) return null;
+  return fs.readFileSync(indexFile, 'utf8');
+}
+
+function extractJsonLdBlocks(html) {
+  return [
+    ...html.matchAll(/<script[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi),
+  ].map((match) => match[1]);
+}
+
+function extractAttribute(html, pattern) {
+  const match = html.match(pattern);
+  return match ? match[1] : null;
+}
+
+function extractCanonical(html) {
+  return extractAttribute(html, /<link[^>]*rel=["']canonical["'][^>]*href=["']([^"']+)["']/i);
+}
+
+function extractOgImage(html) {
+  return extractAttribute(
+    html,
+    /<meta[^>]*property=["']og:image["'][^>]*content=["']([^"']+)["']/i,
+  );
+}
+
+function extractHrefs(html) {
+  return [...html.matchAll(/<a[^>]*href=["']([^"']+)["']/gi)].map((match) => match[1]);
+}
+
+/** The JSON-LD node that claims to be this page, if any. */
+function articleUrlFromJsonLd(blocks) {
+  for (const raw of blocks) {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    for (const node of Array.isArray(parsed) ? parsed : [parsed]) {
+      const types = Array.isArray(node?.['@type']) ? node['@type'] : [node?.['@type']];
+      if (!types.includes('BlogPosting') && !types.includes('Article')) continue;
+      const target = node.mainEntityOfPage;
+      const fromMain = typeof target === 'string' ? target : target?.['@id'];
+      return node.url ?? fromMain ?? node['@id'] ?? null;
+    }
+  }
+  return null;
+}
+
+// --- Source frontmatter ------------------------------------------------------
+
+const contentDir = path.join(root, 'src', 'content', 'p');
+
+function walkContent(dir) {
+  const found = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) found.push(...walkContent(full));
+    else if (/\.mdx?$/i.test(entry.name)) found.push(full);
+  }
+  return found;
+}
+
+function readFrontmatter(file) {
+  const raw = fs.readFileSync(file, 'utf8');
+  if (!raw.startsWith('---')) return null;
+  const end = raw.indexOf('\n---', 3);
+  if (end === -1) return null;
+  try {
+    return yaml.load(raw.slice(3, end).replace(/^\r?\n/, '')) ?? {};
+  } catch (error) {
+    problems.push(`${path.relative(root, file)}: unreadable frontmatter (${error.message})`);
+    return null;
+  }
+}
+
+const posts = [];
+for (const file of walkContent(contentDir)) {
+  const data = readFrontmatter(file);
+  if (!data) continue;
+  // The collection id — and therefore the route — keeps the subdirectory, so
+  // recipes live at /p/recipes/<name>, not /p/<name>.
+  const slug = path
+    .relative(contentDir, file)
+    .replace(/\.mdx?$/i, '')
+    .split(path.sep)
+    .join('/');
+  posts.push({ slug, data });
+}
+notes.push(`${posts.length} source posts`);
+
+// --- Feeds -------------------------------------------------------------------
+
+const jsonFeedPath = path.join(dist, 'feed.json');
+const rssPath = path.join(dist, 'rss.xml');
+
+if (!fs.existsSync(jsonFeedPath)) problems.push('feed.json is missing from the output');
+if (!fs.existsSync(rssPath)) problems.push('rss.xml is missing from the output');
+
+let jsonFeed = null;
+if (fs.existsSync(jsonFeedPath)) {
+  try {
+    jsonFeed = JSON.parse(fs.readFileSync(jsonFeedPath, 'utf8'));
+  } catch (error) {
+    problems.push(`feed.json is not valid JSON: ${error.message}`);
+  }
+}
+
+let rssItems = [];
+if (fs.existsSync(rssPath)) {
+  const rssRaw = fs.readFileSync(rssPath, 'utf8');
+
+  // A real XML parse. The previous check looked for substrings, which passes on
+  // an unescaped ampersand or an unbalanced tag — the two faults that actually
+  // break feed readers.
+  const validity = XMLValidator.validate(rssRaw);
+  if (validity !== true) {
+    const { code, msg, line, col } = validity.err ?? {};
+    problems.push(`rss.xml is not well-formed XML: ${code} ${msg} (line ${line}, col ${col})`);
+  } else {
+    const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: '@' });
+    const parsed = parser.parse(rssRaw);
+    const channelItems = parsed?.rss?.channel?.item ?? [];
+    rssItems = (Array.isArray(channelItems) ? channelItems : [channelItems]).map((item) => ({
+      id: typeof item.guid === 'object' ? item.guid['#text'] : item.guid,
+      url: item.link,
+      title: item.title,
+    }));
+    notes.push(`RSS ${rssItems.length} items`);
+  }
+}
+
+const jsonItems = Array.isArray(jsonFeed?.items) ? jsonFeed.items : [];
+if (jsonFeed) notes.push(`JSON Feed ${jsonItems.length} items`);
+
+problems.push(...checkFeedIdsUnique(jsonItems, 'feed.json'));
+problems.push(...checkFeedIdsUnique(rssItems, 'rss.xml'));
+
+/** Maps a feed entry URL back to a post slug, subdirectory included. */
+function slugFromUrl(url) {
+  if (typeof url !== 'string') return null;
+  const match = url.replace(/\/+$/, '').match(/\/p\/(.+)$/);
+  return match ? match[1] : null;
+}
+
+const feedSlugs = new Set(
+  [...jsonItems, ...rssItems].map((item) => slugFromUrl(item.url)).filter(Boolean),
+);
+
+// Both feeds should carry the same set of posts.
+const jsonSlugs = new Set(jsonItems.map((item) => slugFromUrl(item.url)).filter(Boolean));
+const rssSlugs = new Set(rssItems.map((item) => slugFromUrl(item.url)).filter(Boolean));
+for (const slug of jsonSlugs) {
+  if (rssSlugs.size && !rssSlugs.has(slug)) problems.push(`${slug}: in feed.json but not rss.xml`);
+}
+for (const slug of rssSlugs) {
+  if (jsonSlugs.size && !jsonSlugs.has(slug))
+    problems.push(`${slug}: in rss.xml but not feed.json`);
+}
+
+// --- Publication eligibility -------------------------------------------------
+
+const emittedSlugs = new Set(
+  posts.map((post) => post.slug).filter((slug) => outputHas(`/p/${slug}`)),
+);
+problems.push(...checkPublishEligibility(posts, emittedSlugs, feedSlugs));
+
+// --- Representative pages ----------------------------------------------------
+
+/**
+ * One of each surface the audit asked to cover. Slugs are resolved from source
+ * rather than hardcoded, so renaming a post does not silently drop coverage.
+ */
+function pickSlug(predicate) {
+  const found = posts.find(({ data }) => predicate(data));
+  return found ? found.slug : null;
+}
+
+const englishEssay = posts.find(
+  ({ slug, data }) => !slug.includes('/') && (data.language?.[0] ?? 'en') === 'en',
+)?.slug;
+const spanishTwin = pickSlug((data) => (data.language?.[0] ?? 'en') === 'es');
+// Recipes are identified by their location in the collection, which is what
+// determines their route, rather than by a tag that may or may not be set.
+const recipe = posts.find(({ slug }) => slug.startsWith('recipes/'))?.slug ?? null;
+
+const surfaces = [
+  { label: 'homepage', sitePath: '/' },
+  { label: 'index (everything)', sitePath: '/everything' },
+  { label: 'writing insights', sitePath: '/writing-insights' },
+  englishEssay && { label: `english essay (${englishEssay})`, sitePath: `/p/${englishEssay}` },
+  spanishTwin && { label: `spanish twin (${spanishTwin})`, sitePath: `/p/${spanishTwin}` },
+  recipe && { label: `recipe (${recipe})`, sitePath: `/p/${recipe}` },
+].filter(Boolean);
+
+if (!spanishTwin) problems.push('no Spanish-primary post found in source — coverage gap');
+if (!recipe) notes.push('no recipe post in source; that surface was not exercised');
+
+const feedUrlBySlug = new Map(
+  [...jsonItems, ...rssItems]
+    .map((item) => [slugFromUrl(item.url), item.url])
+    .filter(([slug]) => slug),
+);
+
+// A check that inspects nothing passes exactly like a check that inspects
+// everything. These counters make that difference visible in the output.
+let jsonLdBlocksSeen = 0;
+let linksSeen = 0;
+let assetsSeen = 0;
+
+for (const { label, sitePath } of surfaces) {
+  const html = readPage(sitePath);
+  if (!html) {
+    problems.push(`${label}: ${sitePath} was not emitted`);
+    continue;
+  }
+
+  const blocks = extractJsonLdBlocks(html);
+  jsonLdBlocksSeen += blocks.length;
+  problems.push(...checkJsonLd(blocks, { label, requiredTypes: REQUIRED_SITE_SCHEMA_TYPES }));
+
+  const canonical = extractCanonical(html);
+  const slug = sitePath.startsWith('/p/') ? sitePath.slice(3) : null;
+  problems.push(
+    ...checkCanonicalConsistency({
+      label,
+      canonical,
+      feedUrl: slug ? feedUrlBySlug.get(slug) : null,
+      jsonLdUrl: articleUrlFromJsonLd(blocks),
+    }),
+  );
+
+  const ogImage = extractOgImage(html);
+  if (ogImage) assetsSeen += 1;
+  problems.push(
+    ...checkLocalAssets([{ label: `${label} og:image`, url: ogImage }], outputHas, SITE_ORIGIN),
+  );
+
+  const hrefs = extractHrefs(html);
+  linksSeen += hrefs.filter((href) => href.startsWith('/') && !href.startsWith('//')).length;
+  problems.push(...checkLocalLinks(hrefs, outputHas, REDIRECT_PREFIXES, label));
+}
+
+if (jsonLdBlocksSeen === 0) problems.push('no JSON-LD was inspected — the extractor found nothing');
+if (linksSeen === 0)
+  problems.push('no internal links were inspected — the extractor found nothing');
+if (assetsSeen === 0) problems.push('no og:image was inspected — the extractor found nothing');
+
+notes.push(
+  `${surfaces.length} surfaces · ${jsonLdBlocksSeen} ld+json blocks · ` +
+    `${linksSeen} internal links · ${assetsSeen} og:images`,
+);
+
+// --- Report ------------------------------------------------------------------
+
+if (problems.length) {
+  console.error(`validate-generated-content: ${problems.length} problem(s)`);
+  for (const problem of problems) console.error(`  - ${problem}`);
+  process.exit(1);
+}
+
+console.log(`validate-generated-content: OK (${notes.join(' · ')})`);
diff --git a/src/pages/writing-insights/insights.astro b/src/pages/writing-insights/insights.astro
index c1bbb66e..ad420b20 100644
--- a/src/pages/writing-insights/insights.astro
+++ b/src/pages/writing-insights/insights.astro
@@ -618,8 +618,8 @@ const pageInfo = BRAIN_SCIENCE_PAGES.find((p) => p.id === 'insights');
                 >
               </p>
               <p>
-                <strong class="text-[rgb(var(--color-text))]">Threshold:</strong> >5 = emotionally intense
-                post
+                <strong class="text-[rgb(var(--color-text))]">Threshold:</strong> &gt;5 = emotionally
+                intense post
               </p>
               <p>
                 <strong class="text-[rgb(var(--color-text))]">Keywords:</strong> love, hate, fear, joy,
diff --git a/src/utils/publicationAgreement.test.ts b/src/utils/publicationAgreement.test.ts
new file mode 100644
index 00000000..331dffcd
--- /dev/null
+++ b/src/utils/publicationAgreement.test.ts
@@ -0,0 +1,191 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  isFeedEligiblePost,
+  isListingEligiblePost,
+  isPublicPost,
+  isSearchEligiblePost,
+  isSpanishPrimary,
+} from './publishFilters';
+import {
+  isFeedEligibleMeta,
+  isListingEligibleMeta,
+  isPublicMeta,
+  isSpanishPrimaryMeta,
+  normalizePostMeta,
+} from './publishEligibility.mjs';
+import {
+  isPublicFrontmatter,
+  isSpanishPrimaryFrontmatter,
+} from '../../scripts/lib/generated-content-checks.mjs';
+import { buildSitemapIndex, sitemapPageUrl } from './sitemapTranslations';
+
+/**
+ * R21: the collection surface, the sitemap surface, and the post-build
+ * validator each used to carry their own copy of these rules. This file is the
+ * cross-surface fixture check the audit asked for — every surface must reach the
+ * same verdict about drafts, scheduling, dates, and language.
+ */
+
+const NOW = new Date('2026-09-10T00:00:00Z');
+
+type Fixture = { name: string; data: Record<string, unknown> };
+
+const FIXTURES: Fixture[] = [
+  { name: 'plain English essay', data: { pubDate: '2026-01-01', language: ['en'] } },
+  { name: 'English essay with no language field', data: { pubDate: '2026-01-01' } },
+  { name: 'Spanish twin', data: { pubDate: '2026-01-01', language: ['es'] } },
+  {
+    name: 'English essay that also lists Spanish',
+    data: { pubDate: '2026-01-01', language: ['en', 'es'] },
+  },
+  { name: 'draft', data: { pubDate: '2026-01-01', draft: true } },
+  { name: 'Spanish draft', data: { pubDate: '2026-01-01', draft: true, language: ['es'] } },
+  { name: 'unpublished', data: { pubDate: '2026-01-01', published: false } },
+  { name: 'future-dated', data: { pubDate: '2027-06-01' } },
+  { name: 'future-dated Spanish', data: { pubDate: '2027-06-01', language: ['es'] } },
+  { name: 'dated exactly now', data: { pubDate: NOW.toISOString() } },
+  { name: 'date given as a YAML Date', data: { pubDate: new Date('2026-01-01T00:00:00Z') } },
+];
+
+describe('publication rules agree across every surface', () => {
+  for (const { name, data } of FIXTURES) {
+    it(name, () => {
+      const meta = normalizePostMeta(data);
+      // `publishFilters` takes collection data; the shape is structurally the
+      // same, so the cast is the adapter boundary, not a behavior change.
+      const asPostData = data as never;
+
+      expect(isPublicPost(asPostData, { now: NOW })).toBe(isPublicMeta(meta, { now: NOW }));
+      expect(isSpanishPrimary(asPostData)).toBe(isSpanishPrimaryMeta(meta));
+      expect(isFeedEligiblePost(asPostData, { now: NOW })).toBe(
+        isFeedEligibleMeta(meta, { now: NOW }),
+      );
+      expect(isListingEligiblePost(asPostData, { now: NOW })).toBe(
+        isListingEligibleMeta(meta, { now: NOW }),
+      );
+
+      // The post-build validator reaches the same verdict from raw frontmatter.
+      expect(isPublicFrontmatter(data, NOW)).toBe(isPublicMeta(meta, { now: NOW }));
+      expect(isSpanishPrimaryFrontmatter(data)).toBe(isSpanishPrimaryMeta(meta));
+
+      // Search is the documented exception: public in any language.
+      expect(isSearchEligiblePost(asPostData, { now: NOW })).toBe(isPublicMeta(meta, { now: NOW }));
+    });
+  }
+});
+
+describe('sitemap lastmod attribution', () => {
+  const entry = (postId: string, data: Record<string, unknown>) => ({
+    postId,
+    meta: normalizePostMeta(data),
+  });
+
+  it('does not bump English-only listings for a Spanish-only edit', () => {
+    const index = buildSitemapIndex(
+      [
+        entry('english-essay', {
+          pubDate: '2026-01-01',
+          updatedDate: '2026-03-01',
+          language: ['en'],
+          category: ['psychology'],
+        }),
+        // Edited much later, and it is the newest post in the set.
+        entry('ensayo-espanol', {
+          pubDate: '2026-01-01',
+          updatedDate: '2026-08-01',
+          language: ['es'],
+          category: ['psychology'],
+        }),
+      ],
+      { now: NOW },
+    );
+
+    const spanishEdit = '2026-08-01T00:00:00.000Z';
+    const englishEdit = '2026-03-01T00:00:00.000Z';
+
+    // The Spanish post's own page reflects its edit.
+    expect(index.lastmodByUrl.get(sitemapPageUrl('/p/ensayo-espanol'))?.toISOString()).toBe(
+      spanishEdit,
+    );
+
+    // English-only surfaces must not claim to have changed on that date.
+    for (const listing of ['/', '/everything', '/guided-path', '/rss.xml', '/feed.json']) {
+      expect(index.lastmodByUrl.get(sitemapPageUrl(listing))?.toISOString()).toBe(englishEdit);
+    }
+    expect(index.lastmodByUrl.get(sitemapPageUrl('/category/psychology'))?.toISOString()).toBe(
+      englishEdit,
+    );
+  });
+
+  it('never lists a withheld post at all', () => {
+    const index = buildSitemapIndex(
+      [
+        entry('live', { pubDate: '2026-01-01', language: ['en'] }),
+        entry('wip', { pubDate: '2026-08-01', draft: true }),
+        entry('pulled', { pubDate: '2026-08-02', published: false }),
+        entry('embargoed', { pubDate: '2027-01-01' }),
+      ],
+      { now: NOW },
+    );
+
+    expect(index.lastmodByUrl.has(sitemapPageUrl('/p/live'))).toBe(true);
+    for (const withheld of ['wip', 'pulled', 'embargoed']) {
+      expect(index.lastmodByUrl.has(sitemapPageUrl(`/p/${withheld}`))).toBe(false);
+    }
+    // None of them may have moved the homepage either.
+    expect(index.lastmodByUrl.get(sitemapPageUrl('/'))?.toISOString()).toBe(
+      '2026-01-01T00:00:00.000Z',
+    );
+  });
+
+  it('keeps recipes off category and tag pages, matching isCategoryListedPost', () => {
+    const index = buildSitemapIndex(
+      [
+        entry('essay', {
+          pubDate: '2026-01-01',
+          category: ['parenting'],
+          tags: ['parenting'],
+        }),
+        entry('recipes/sofrito', {
+          pubDate: '2026-08-01',
+          category: ['parenting'],
+          tags: ['parenting'],
+        }),
+      ],
+      { now: NOW },
+    );
+
+    const essayDate = '2026-01-01T00:00:00.000Z';
+    const recipeDate = '2026-08-01T00:00:00.000Z';
+
+    // The Cookbook and Everything both list recipes, so they move.
+    expect(index.lastmodByUrl.get(sitemapPageUrl('/recipes'))?.toISOString()).toBe(recipeDate);
+    expect(index.lastmodByUrl.get(sitemapPageUrl('/everything'))?.toISOString()).toBe(recipeDate);
+
+    // Category and tag pages list essays only, so they must not.
+    expect(index.lastmodByUrl.get(sitemapPageUrl('/category/parenting'))?.toISOString()).toBe(
+      essayDate,
+    );
+    expect(index.lastmodByUrl.get(sitemapPageUrl('/tag/parenting'))?.toISOString()).toBe(essayDate);
+  });
+
+  it('still clusters EN/ES translation pairs', () => {
+    const index = buildSitemapIndex(
+      [
+        entry('essay', { pubDate: '2026-01-01', language: ['en'], translationGroup: 'pair' }),
+        entry('ensayo', { pubDate: '2026-01-01', language: ['es'], translationGroup: 'pair' }),
+        entry('lonely', { pubDate: '2026-01-01', translationGroup: 'solo' }),
+      ],
+      { now: NOW },
+    );
+
+    const links = index.linksByCanonicalUrl.get(sitemapPageUrl('/p/essay'));
+    expect(links).toBeTruthy();
+    expect(links!.map((link) => link.lang).sort()).toEqual(['en-US', 'es-ES']);
+    expect(index.linksByCanonicalUrl.get(sitemapPageUrl('/p/ensayo'))).toEqual(links);
+
+    // A group of one is not a pair.
+    expect(index.linksByCanonicalUrl.has(sitemapPageUrl('/p/lonely'))).toBe(false);
+  });
+});
diff --git a/src/utils/publishEligibility.mjs b/src/utils/publishEligibility.mjs
new file mode 100644
index 00000000..464ac09a
--- /dev/null
+++ b/src/utils/publishEligibility.mjs
@@ -0,0 +1,133 @@
+/**
+ * Framework-independent publication rules.
+ *
+ * This is the single definition of "is this post public", "is it Spanish", and
+ * "does it belong in English listings and feeds". It is plain JavaScript with
+ * JSDoc types on purpose, so that all four consumers can share one
+ * implementation:
+ *
+ * - `src/utils/publishFilters.ts`, over `astro:content` collection entries
+ * - `src/utils/sitemapTranslations.ts`, over raw frontmatter at config-load time
+ *   when `astro:content` is not available
+ * - `scripts/lib/generated-content-checks.mjs`, run by plain Node after a build
+ * - anything else that needs the rules without an Astro runtime
+ *
+ * Before this module those were three separate implementations that had already
+ * drifted. Nothing here may import `astro:content`, Vite's `import.meta.env`, or
+ * anything else that would break `astro.config.mjs` at load time. Rules that
+ * genuinely depend on the environment — the dev-mode draft preview in
+ * `isCollectionListed` — stay in `publishFilters.ts`.
+ *
+ * @typedef {object} PostMeta
+ * @property {boolean} draft
+ * @property {boolean} published
+ * @property {Date | null} pubDate
+ * @property {Date | null} updatedDate
+ * @property {string[]} language
+ * @property {string[]} category
+ * @property {string[]} tags
+ * @property {string | null} translationGroup
+ *
+ * @typedef {object} EligibilityOptions
+ * @property {Date} [now] Override "now" for tests and deterministic builds.
+ * @property {boolean} [includeFuture] Include posts embargoed by a future pubDate.
+ */
+
+/** @param {unknown} value @returns {Date | null} */
+export function toDate(value) {
+  if (value instanceof Date) return Number.isNaN(value.valueOf()) ? null : value;
+  if (typeof value === 'string' || typeof value === 'number') {
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.valueOf()) ? null : parsed;
+  }
+  return null;
+}
+
+/** @param {unknown} value @returns {string[]} */
+export function toStringArray(value) {
+  if (typeof value === 'string') return value ? [value] : [];
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry) => typeof entry === 'string' && entry.length > 0);
+}
+
+/**
+ * Normalizes either a collection entry's `data` or raw YAML frontmatter into one
+ * shape. Collection entries arrive with real `Date` objects; frontmatter read
+ * from disk arrives as strings or as js-yaml `Date`s.
+ *
+ * @param {Record<string, unknown>} raw
+ * @returns {PostMeta}
+ */
+export function normalizePostMeta(raw) {
+  const source = raw ?? {};
+  return {
+    draft: source.draft === true,
+    published: source.published !== false,
+    pubDate: toDate(source.pubDate),
+    updatedDate: toDate(source.updatedDate),
+    language: toStringArray(source.language),
+    category: toStringArray(source.category),
+    tags: toStringArray(source.tags),
+    translationGroup:
+      typeof source.translationGroup === 'string' && source.translationGroup
+        ? source.translationGroup
+        : null,
+  };
+}
+
+/**
+ * Publicly live: not a draft, not unpublished, not embargoed by a future date.
+ *
+ * @param {PostMeta} meta
+ * @param {EligibilityOptions} [options]
+ */
+export function isPublicMeta(meta, options = {}) {
+  if (meta.draft) return false;
+  if (!meta.published) return false;
+  if (options.includeFuture) return true;
+  if (meta.pubDate && meta.pubDate > (options.now ?? new Date())) return false;
+  return true;
+}
+
+/**
+ * True when the post's primary language is Spanish. Only the first entry
+ * counts: `['en', 'es']` is an English post that mentions Spanish.
+ *
+ * @param {PostMeta} meta
+ */
+export function isSpanishPrimaryMeta(meta) {
+  return (meta.language[0] ?? 'en') === 'es';
+}
+
+/**
+ * Feeds carry public English posts only. Spanish stays reachable through the
+ * language toggle, search, SEO, and its direct URL.
+ *
+ * @param {PostMeta} meta
+ * @param {EligibilityOptions} [options]
+ */
+export function isFeedEligibleMeta(meta, options = {}) {
+  return isPublicMeta(meta, options) && !isSpanishPrimaryMeta(meta);
+}
+
+/**
+ * English listing surfaces: Everything, category, tag, Cookbook, Guided Path,
+ * the homepage, and 404. Same rule as feeds, named separately because the two
+ * policies are allowed to diverge later.
+ *
+ * @param {PostMeta} meta
+ * @param {EligibilityOptions} [options]
+ */
+export function isListingEligibleMeta(meta, options = {}) {
+  return isPublicMeta(meta, options) && !isSpanishPrimaryMeta(meta);
+}
+
+/**
+ * The date a crawler should treat as this post's last modification.
+ *
+ * @param {PostMeta} meta
+ * @returns {Date | null}
+ */
+export function lastmodForMeta(meta) {
+  return meta.updatedDate ?? meta.pubDate;
+}
diff --git a/src/utils/publishEligibility.test.ts b/src/utils/publishEligibility.test.ts
new file mode 100644
index 00000000..209ec380
--- /dev/null
+++ b/src/utils/publishEligibility.test.ts
@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  isFeedEligibleMeta,
+  isListingEligibleMeta,
+  isPublicMeta,
+  isSpanishPrimaryMeta,
+  lastmodForMeta,
+  normalizePostMeta,
+  toDate,
+  toStringArray,
+} from './publishEligibility.mjs';
+
+const NOW = new Date('2026-09-10T00:00:00Z');
+
+describe('normalizePostMeta', () => {
+  it('accepts both a collection entry and raw YAML frontmatter', () => {
+    // Collection entries arrive with real Dates; frontmatter read from disk
+    // arrives as strings. Both had their own parsing before this module.
+    const fromCollection = normalizePostMeta({
+      title: 'x',
+      pubDate: new Date('2026-01-01T00:00:00Z'),
+      language: ['es'],
+    });
+    const fromYaml = normalizePostMeta({
+      title: 'x',
+      pubDate: '2026-01-01T00:00:00Z',
+      language: ['es'],
+    });
+    expect(fromCollection.pubDate?.toISOString()).toBe(fromYaml.pubDate?.toISOString());
+    expect(fromCollection.language).toEqual(fromYaml.language);
+  });
+
+  it('fills in defaults for absent fields', () => {
+    const meta = normalizePostMeta({});
+    expect(meta).toEqual({
+      draft: false,
+      published: true,
+      pubDate: null,
+      updatedDate: null,
+      language: [],
+      category: [],
+      tags: [],
+      translationGroup: null,
+    });
+  });
+
+  it('treats only an explicit true/false as draft/unpublished', () => {
+    expect(normalizePostMeta({ draft: 'yes' }).draft).toBe(false);
+    expect(normalizePostMeta({ draft: true }).draft).toBe(true);
+    expect(normalizePostMeta({ published: false }).published).toBe(false);
+    expect(normalizePostMeta({ published: undefined }).published).toBe(true);
+  });
+
+  it('drops an unparseable date rather than producing Invalid Date', () => {
+    expect(normalizePostMeta({ pubDate: 'not a date' }).pubDate).toBeNull();
+    expect(toDate(new Date('nonsense'))).toBeNull();
+    expect(toDate(null)).toBeNull();
+  });
+
+  it('accepts a bare string where an array is expected', () => {
+    expect(toStringArray('parenting')).toEqual(['parenting']);
+    expect(toStringArray(['a', '', 3, 'b'])).toEqual(['a', 'b']);
+    expect(toStringArray(undefined)).toEqual([]);
+  });
+
+  it('ignores an empty translationGroup', () => {
+    expect(normalizePostMeta({ translationGroup: '' }).translationGroup).toBeNull();
+    expect(normalizePostMeta({ translationGroup: 'pair' }).translationGroup).toBe('pair');
+  });
+});
+
+describe('eligibility rules', () => {
+  const live = normalizePostMeta({ pubDate: '2026-01-01' });
+
+  it('withholds drafts, unpublished posts, and future dates', () => {
+    expect(isPublicMeta(live, { now: NOW })).toBe(true);
+    expect(
+      isPublicMeta(normalizePostMeta({ pubDate: '2026-01-01', draft: true }), { now: NOW }),
+    ).toBe(false);
+    expect(
+      isPublicMeta(normalizePostMeta({ pubDate: '2026-01-01', published: false }), { now: NOW }),
+    ).toBe(false);
+    expect(isPublicMeta(normalizePostMeta({ pubDate: '2027-01-01' }), { now: NOW })).toBe(false);
+  });
+
+  it('honours includeFuture for dev preview', () => {
+    const scheduled = normalizePostMeta({ pubDate: '2027-01-01' });
+    expect(isPublicMeta(scheduled, { now: NOW, includeFuture: true })).toBe(true);
+    // includeFuture lifts the embargo only; a draft is still a draft.
+    const scheduledDraft = normalizePostMeta({ pubDate: '2027-01-01', draft: true });
+    expect(isPublicMeta(scheduledDraft, { now: NOW, includeFuture: true })).toBe(false);
+  });
+
+  it('treats only the first language entry as primary', () => {
+    expect(isSpanishPrimaryMeta(normalizePostMeta({ language: ['es'] }))).toBe(true);
+    expect(isSpanishPrimaryMeta(normalizePostMeta({ language: ['es', 'en'] }))).toBe(true);
+    expect(isSpanishPrimaryMeta(normalizePostMeta({ language: ['en', 'es'] }))).toBe(false);
+    expect(isSpanishPrimaryMeta(normalizePostMeta({}))).toBe(false);
+  });
+
+  it('keeps Spanish out of feeds and listings but not out of the site', () => {
+    const spanish = normalizePostMeta({ pubDate: '2026-01-01', language: ['es'] });
+    expect(isPublicMeta(spanish, { now: NOW })).toBe(true);
+    expect(isFeedEligibleMeta(spanish, { now: NOW })).toBe(false);
+    expect(isListingEligibleMeta(spanish, { now: NOW })).toBe(false);
+  });
+
+  it('prefers updatedDate for lastmod, falling back to pubDate', () => {
+    expect(lastmodForMeta(live)?.toISOString()).toBe('2026-01-01T00:00:00.000Z');
+    const updated = normalizePostMeta({ pubDate: '2026-01-01', updatedDate: '2026-05-05' });
+    expect(lastmodForMeta(updated)?.toISOString()).toBe('2026-05-05T00:00:00.000Z');
+    expect(lastmodForMeta(normalizePostMeta({}))).toBeNull();
+  });
+});
diff --git a/src/utils/publishFilters.ts b/src/utils/publishFilters.ts
index ac90d14a..755004bd 100644
--- a/src/utils/publishFilters.ts
+++ b/src/utils/publishFilters.ts
@@ -1,7 +1,24 @@
 import type { CollectionEntry } from 'astro:content';
+import {
+  isFeedEligibleMeta,
+  isListingEligibleMeta,
+  isPublicMeta,
+  isSpanishPrimaryMeta,
+  normalizePostMeta,
+} from './publishEligibility.mjs';
 
 type PostData = CollectionEntry<'blog'>['data'];
 
+/**
+ * The rules themselves live in `publishEligibility.mjs`, which has no Astro or
+ * Vite dependency, so `astro.config.mjs` and plain Node build scripts can apply
+ * exactly the same logic. This file is the `astro:content` adapter over it, plus
+ * the one rule that genuinely depends on the environment (`isCollectionListed`).
+ */
+function meta(data: PostData) {
+  return normalizePostMeta(data as unknown as Record<string, unknown>);
+}
+
 export interface PublishFilterOptions {
   /** Override "now" for tests / deterministic builds. */
   now?: Date;
@@ -14,13 +31,7 @@ export interface PublishFilterOptions {
 
 /** Post is publicly live: not draft, not unpublished, and not embargoed by pubDate. */
 export function isPublicPost(data: PostData, options: PublishFilterOptions = {}): boolean {
-  if (data.draft) return false;
-  if (data.published === false) return false;
-
-  const includeFuture = options.includeFuture ?? false;
-  if (!includeFuture && data.pubDate > (options.now ?? new Date())) return false;
-
-  return true;
+  return isPublicMeta(meta(data), options);
 }
 
 /**
@@ -35,7 +46,7 @@ export function isCollectionPublic(data: PostData, options: PublishFilterOptions
 
 /** True when the post's primary language is Spanish. */
 export function isSpanishPrimary(data: PostData): boolean {
-  return (data.language?.[0] ?? 'en') === 'es';
+  return isSpanishPrimaryMeta(meta(data));
 }
 
 /**
@@ -64,8 +75,7 @@ export function isHomepageHighlight(data: PostData, options: PublishFilterOption
  * Spanish stays reachable via language toggle, title search, SEO, and direct URL.
  */
 export function isFeedEligiblePost(data: PostData, options: PublishFilterOptions = {}): boolean {
-  if (!isPublicPost(data, options)) return false;
-  return !isSpanishPrimary(data);
+  return isFeedEligibleMeta(meta(data), options);
 }
 
 /**
@@ -73,8 +83,7 @@ export function isFeedEligiblePost(data: PostData, options: PublishFilterOptions
  * Spanish does not appear on Everything, category, tag, 404, or Guided Path.
  */
 export function isListingEligiblePost(data: PostData, options: PublishFilterOptions = {}): boolean {
-  if (!isPublicPost(data, options)) return false;
-  return !isSpanishPrimary(data);
+  return isListingEligibleMeta(meta(data), options);
 }
 
 /**
diff --git a/src/utils/sitemapTranslations.ts b/src/utils/sitemapTranslations.ts
index f1191521..4e7a0e02 100644
--- a/src/utils/sitemapTranslations.ts
+++ b/src/utils/sitemapTranslations.ts
@@ -15,6 +15,14 @@ import yaml from 'js-yaml';
 import { SITE_URL } from '../consts';
 import { canonicalizeTags } from './tagVocabulary';
 import { isRecipeId } from './recipes';
+import {
+  isListingEligibleMeta,
+  isPublicMeta,
+  isSpanishPrimaryMeta,
+  lastmodForMeta,
+  normalizePostMeta,
+} from './publishEligibility.mjs';
+import type { PostMeta } from './publishEligibility.mjs';
 
 export type SitemapLangLink = { url: string; lang: string };
 
@@ -66,25 +74,6 @@ function parseFrontmatter(raw: string): Record<string, unknown> | null {
   }
 }
 
-function parseDate(value: unknown): Date | null {
-  if (value instanceof Date) {
-    return Number.isNaN(value.valueOf()) ? null : value;
-  }
-  if (typeof value === 'string' || typeof value === 'number') {
-    const d = new Date(value);
-    return Number.isNaN(d.valueOf()) ? null : d;
-  }
-  return null;
-}
-
-function isPublicFrontmatter(data: Record<string, unknown>, now = new Date()): boolean {
-  if (data.draft === true) return false;
-  if (data.published === false) return false;
-  const pub = parseDate(data.pubDate);
-  if (pub && pub > now) return false;
-  return true;
-}
-
 function postIdFromFile(file: string): string {
   const rel = path.relative(CONTENT_DIR, file).replace(/\\/g, '/');
   return rel.replace(/\.(md|mdx)$/i, '');
@@ -101,67 +90,68 @@ export function sitemapPageUrl(pathname: string): string {
   return href.replace(/\/$/, '');
 }
 
-function asStringArray(value: unknown): string[] {
-  if (typeof value === 'string' && value) return [value];
-  if (!Array.isArray(value)) return [];
-  return value.filter((v): v is string => typeof v === 'string' && v.length > 0);
-}
-
-function postLang(data: Record<string, unknown>): string {
-  const language = data.language;
-  if (Array.isArray(language) && language[0] === 'es') return 'es';
-  if (typeof language === 'string' && language === 'es') return 'es';
-  return 'en';
-}
-
 function bumpLastmod(map: Map<string, Date>, url: string, date: Date) {
   const prev = map.get(url);
   if (!prev || date > prev) map.set(url, date);
 }
 
-function loadSitemapMeta(): SitemapMeta {
-  if (sitemapMeta) return sitemapMeta;
+/** One post as the sitemap index needs it: its route id and normalized metadata. */
+export type SitemapPostEntry = { postId: string; meta: PostMeta };
 
+/**
+ * Builds the sitemap index from already-normalized posts.
+ *
+ * Exported separately from the filesystem walk so the attribution rules can be
+ * tested against fixtures. The real content set cannot demonstrate the
+ * language-policy fix on its own: it only bites when the newest post is
+ * Spanish, which is not true today.
+ */
+export function buildSitemapIndex(
+  entries: SitemapPostEntry[],
+  options: { now?: Date } = {},
+): SitemapMeta {
+  const now = options.now ?? new Date();
   const byGroup = new Map<string, Array<{ lang: string; url: string }>>();
   const lastmodByUrl = new Map<string, Date>();
-  const now = new Date();
 
-  for (const file of walkMarkdownFiles(CONTENT_DIR)) {
-    const raw = fs.readFileSync(file, 'utf8');
-    const data = parseFrontmatter(raw);
-    if (!data || !isPublicFrontmatter(data, now)) continue;
+  for (const { postId, meta } of entries) {
+    if (!isPublicMeta(meta, { now })) continue;
 
-    const lastmod = parseDate(data.updatedDate) ?? parseDate(data.pubDate);
+    const lastmod = lastmodForMeta(meta);
     if (!lastmod) continue;
 
-    const postId = postIdFromFile(file);
     const url = canonicalPostUrl(postId);
-    lastmodByUrl.set(url, lastmod);
-
-    for (const listingPath of LISTING_PATHS) {
-      bumpLastmod(lastmodByUrl, sitemapPageUrl(listingPath), lastmod);
-    }
 
-    if (isRecipeId(postId)) {
-      bumpLastmod(lastmodByUrl, sitemapPageUrl('/recipes'), lastmod);
-    }
+    // Every public post has its own page, in either language.
+    lastmodByUrl.set(url, lastmod);
 
-    for (const category of asStringArray(data.category)) {
-      bumpLastmod(lastmodByUrl, sitemapPageUrl(`/category/${category}`), lastmod);
-    }
+    // Listing pages and feeds are English-only. Bumping them for a Spanish post
+    // told crawlers an English-only listing had changed when it had not.
+    if (isListingEligibleMeta(meta, { now })) {
+      for (const listingPath of LISTING_PATHS) {
+        bumpLastmod(lastmodByUrl, sitemapPageUrl(listingPath), lastmod);
+      }
 
-    if (!isRecipeId(postId)) {
-      for (const tag of canonicalizeTags(asStringArray(data.tags))) {
-        bumpLastmod(lastmodByUrl, sitemapPageUrl(`/tag/${tag}`), lastmod);
+      if (isRecipeId(postId)) {
+        bumpLastmod(lastmodByUrl, sitemapPageUrl('/recipes'), lastmod);
+      } else {
+        // Category and tag pages list essays, not recipes — see
+        // `isCategoryListedPost` / `isTagListedPost` in utils/recipes.ts. The
+        // tag side already had this guard; the category side did not.
+        for (const category of meta.category) {
+          bumpLastmod(lastmodByUrl, sitemapPageUrl(`/category/${category}`), lastmod);
+        }
+        for (const tag of canonicalizeTags(meta.tags)) {
+          bumpLastmod(lastmodByUrl, sitemapPageUrl(`/tag/${tag}`), lastmod);
+        }
       }
     }
 
-    const group = data.translationGroup;
-    if (typeof group !== 'string' || !group) continue;
+    if (!meta.translationGroup) continue;
 
-    const list = byGroup.get(group) ?? [];
-    list.push({ lang: postLang(data), url });
-    byGroup.set(group, list);
+    const list = byGroup.get(meta.translationGroup) ?? [];
+    list.push({ lang: isSpanishPrimaryMeta(meta) ? 'es' : 'en', url });
+    byGroup.set(meta.translationGroup, list);
   }
 
   const linksByCanonicalUrl = new Map<string, SitemapLangLink[]>();
@@ -176,6 +166,21 @@ function loadSitemapMeta(): SitemapMeta {
     }
   }
 
+  return { linksByCanonicalUrl, lastmodByUrl };
+}
+
+/** Reads the content directory and builds the index from it, once. */
+function loadSitemapMeta(): SitemapMeta {
+  if (sitemapMeta) return sitemapMeta;
+
+  const entries: SitemapPostEntry[] = [];
+  for (const file of walkMarkdownFiles(CONTENT_DIR)) {
+    const data = parseFrontmatter(fs.readFileSync(file, 'utf8'));
+    if (!data) continue;
+    entries.push({ postId: postIdFromFile(file), meta: normalizePostMeta(data) });
+  }
+
+  const { linksByCanonicalUrl, lastmodByUrl } = buildSitemapIndex(entries);
   sitemapMeta = { linksByCanonicalUrl, lastmodByUrl };
   return sitemapMeta;
 }
diff --git a/tests/browser/harness.ts b/tests/browser/harness.ts
new file mode 100644
index 00000000..6bfe90b0
--- /dev/null
+++ b/tests/browser/harness.ts
@@ -0,0 +1,125 @@
+/**
+ * Shared harness for the browser regression journeys.
+ *
+ * These tests run against the real build output in `dist/client`, served by
+ * `scripts/serve-dist.mjs`, in headless Chromium driven by the `playwright`
+ * library. The library is already a devDependency; the `@playwright/test`
+ * runner is not, so Vitest stays the only test runner in this repo.
+ *
+ * They need `pnpm run build` to have run first. `pnpm run test:browser` does not
+ * build for you — building inside a test run makes a failure ambiguous between
+ * the build and the behavior.
+ */
+
+import type { Browser, BrowserContext, Page } from 'playwright';
+import { chromium } from 'playwright';
+import type { Server } from 'node:http';
+
+import { createDistServer, listen } from '../../scripts/serve-dist.mjs';
+
+/** Widths the audit asked these journeys to cover. */
+export const VIEWPORTS = {
+  mobile: { width: 390, height: 844 },
+  tablet: { width: 768, height: 1024 },
+  desktop: { width: 1440, height: 900 },
+} as const;
+
+let server: Server | null = null;
+let browser: Browser | null = null;
+let baseUrl = '';
+let boundPort = 0;
+
+/** Starts one server and one browser for the whole file. */
+export async function startHarness(): Promise<string> {
+  server = createDistServer();
+  // Port 0 lets the OS pick a free one, so a stray dev server never collides
+  // and two test files can never fight over a fixed port.
+  baseUrl = await listen(server, { host: '127.0.0.1', port: 0 });
+  boundPort = Number(new URL(baseUrl).port);
+  browser = await chromium.launch();
+  return baseUrl;
+}
+
+export async function stopHarness(): Promise<void> {
+  await browser?.close();
+  browser = null;
+  await new Promise<void>((done) => {
+    if (!server) return done();
+    server.close(() => done());
+  });
+  server = null;
+}
+
+export interface PageOptions {
+  viewport?: { width: number; height: number };
+  reducedMotion?: 'reduce' | 'no-preference';
+  colorScheme?: 'light' | 'dark';
+  /**
+   * Interaction journeys block service workers so a cached response from an
+   * earlier run can never stand in for the build under test. The service-worker
+   * suite is the one place that needs them allowed.
+   */
+  serviceWorkers?: 'allow' | 'block';
+}
+
+/** Opens an isolated context so storage never leaks between journeys. */
+export async function openPage(options: PageOptions = {}): Promise<{
+  page: Page;
+  context: BrowserContext;
+  goto: (path: string) => Promise<void>;
+  origin: string;
+}> {
+  if (!browser) throw new Error('startHarness() must run before openPage()');
+
+  const context = await browser.newContext({
+    viewport: options.viewport ?? VIEWPORTS.desktop,
+    reducedMotion: options.reducedMotion ?? 'no-preference',
+    colorScheme: options.colorScheme ?? 'light',
+    // Blocked by default: a cached response from an earlier run must never
+    // stand in for the build under test. tests/browser/service-worker.test.ts
+    // opts back in.
+    serviceWorkers: options.serviceWorkers ?? 'block',
+  });
+  const page = await context.newPage();
+
+  return {
+    page,
+    context,
+    origin: baseUrl,
+    goto: async (path: string) => {
+      // 'load', not 'domcontentloaded': evaluating against a document that is
+      // still committing produced "Execution context was destroyed" flakes.
+      await page.goto(`${baseUrl}${path}`, { waitUntil: 'load' });
+    },
+  };
+}
+
+/**
+ * Stops the server so nothing on the origin can be reached.
+ *
+ * `context.setOffline(true)` is not enough for service-worker tests: it emulates
+ * the *page's* network, while the worker's own `fetch()` still reaches the
+ * server. An offline assertion written against it passes whether or not the
+ * cache is doing anything. Taking the server down is the only way to know.
+ */
+export async function stopServing(): Promise<void> {
+  if (!server) return;
+  const closing = new Promise<void>((done) => server!.close(() => done()));
+  // close() only stops new connections; keep-alive sockets would survive it.
+  server.closeAllConnections();
+  await closing;
+  server = null;
+}
+
+/** Brings the origin back up on the same port. */
+export async function resumeServing(): Promise<void> {
+  if (server) return;
+  server = createDistServer();
+  await listen(server, { host: '127.0.0.1', port: boundPort });
+}
+
+/** A post that renders an ImageRotator with autoplay, for the carousel journey. */
+export const ROTATOR_POST = '/p/why-electric-cars-cant-look-like-electric-cars/';
+
+/** A post with prose images, for the lightbox journey. */
+export const LIGHTBOX_POST = '/p/my-crimson-desert-review-after-200-hours/';
diff --git a/tests/browser/interaction.test.ts b/tests/browser/interaction.test.ts
new file mode 100644
index 00000000..b9ba1407
--- /dev/null
+++ b/tests/browser/interaction.test.ts
@@ -0,0 +1,387 @@
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+
+import { openPage, startHarness, stopHarness, VIEWPORTS } from './harness';
+
+const ROTATOR_POST = '/p/why-electric-cars-cant-look-like-electric-cars/';
+const LIGHTBOX_POST = '/p/bend-dont-break-learning-to-flow-again/';
+/** ImageRotator autoplay interval in the published MDX, plus slack. */
+const ROTATION_PERIOD_MS = 4500;
+
+beforeAll(startHarness);
+afterAll(stopHarness);
+
+describe('article image lightbox (R08)', () => {
+  test('opens from the keyboard, traps focus, and restores it on Escape', async () => {
+    const { page, context, goto } = await openPage({ viewport: VIEWPORTS.desktop });
+    try {
+      await goto(LIGHTBOX_POST);
+
+      const image = page.locator('.prose img[role="button"]').first();
+      await expect.poll(() => image.count()).toBe(1);
+
+      // The trigger has to be reachable and named before it is any use.
+      expect(await image.getAttribute('tabindex')).toBe('0');
+      expect(await image.getAttribute('aria-label')).toBeTruthy();
+
+      const bodyOverflowBefore = await page.evaluate(() => document.body.style.overflow);
+
+      await image.focus();
+      await page.keyboard.press('Enter');
+
+      const dialog = page.locator('dialog#imageModal');
+      await expect.poll(() => dialog.evaluate((d: HTMLDialogElement) => d.open)).toBe(true);
+
+      // showModal() is what makes the background inert; a plain show() would not.
+      expect(await dialog.evaluate((d: HTMLDialogElement) => d.matches(':modal'))).toBe(true);
+      expect(await page.evaluate(() => document.activeElement?.className)).toContain('close-btn');
+      expect(await page.evaluate(() => document.body.style.overflow)).toBe('hidden');
+
+      const modalImage = page.locator('#modalImage');
+      expect(await modalImage.getAttribute('src')).toBeTruthy();
+
+      await page.keyboard.press('Escape');
+      await expect.poll(() => dialog.evaluate((d: HTMLDialogElement) => d.open)).toBe(false);
+
+      // Focus must come back to the image the reader opened, not the page top.
+      expect(await page.evaluate(() => document.activeElement?.getAttribute('role'))).toBe(
+        'button',
+      );
+      expect(await page.evaluate(() => document.body.style.overflow)).toBe(bodyOverflowBefore);
+    } finally {
+      await context.close();
+    }
+  });
+
+  test('restores focus to the image even when focus was elsewhere on open', async () => {
+    const { page, context, goto } = await openPage({ viewport: VIEWPORTS.desktop });
+    try {
+      await goto(LIGHTBOX_POST);
+
+      // <dialog> natively returns focus to whatever was focused before
+      // showModal(). Opening from an element that is NOT the image is the only
+      // way to tell the layout's own `activeImage.focus()` apart from that
+      // built-in behavior — without this, the assertion passes either way.
+      await page.evaluate(() => {
+        const elsewhere = document.querySelector<HTMLElement>('#theme-toggle');
+        elsewhere?.focus();
+        const image = [...document.querySelectorAll<HTMLImageElement>('.prose img[role="button"]')];
+        image[0]?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+      });
+
+      const dialog = page.locator('dialog#imageModal');
+      await expect.poll(() => dialog.evaluate((d: HTMLDialogElement) => d.open)).toBe(true);
+
+      await page.keyboard.press('Escape');
+      await expect.poll(() => dialog.evaluate((d: HTMLDialogElement) => d.open)).toBe(false);
+
+      const landedOn = await page.evaluate(() => ({
+        tag: document.activeElement?.tagName,
+        role: document.activeElement?.getAttribute('role'),
+        id: document.activeElement?.id,
+      }));
+      expect(landedOn.tag).toBe('IMG');
+      expect(landedOn.role).toBe('button');
+    } finally {
+      await context.close();
+    }
+  });
+
+  test('closes from the close button too', async () => {
+    const { page, context, goto } = await openPage({ viewport: VIEWPORTS.desktop });
+    try {
+      await goto(LIGHTBOX_POST);
+      const image = page.locator('.prose img[role="button"]').first();
+      await image.click();
+
+      const dialog = page.locator('dialog#imageModal');
+      await expect.poll(() => dialog.evaluate((d: HTMLDialogElement) => d.open)).toBe(true);
+
+      await page.locator('dialog#imageModal .close-btn').click();
+      await expect.poll(() => dialog.evaluate((d: HTMLDialogElement) => d.open)).toBe(false);
+    } finally {
+      await context.close();
+    }
+  });
+});
+
+describe('search (R01, R10)', () => {
+  /** Returns the id of the search bar that is actually visible at this width. */
+  async function visibleSearch(page: import('playwright').Page) {
+    await page.locator('input[id^="search-"]').first().waitFor({ state: 'attached' });
+    return page.evaluate(() => {
+      const inputs = [...document.querySelectorAll<HTMLInputElement>('input[id^="search-"]')];
+      const input = inputs.find((i) => i.offsetParent !== null) ?? inputs[0];
+      return input?.id ?? null;
+    });
+  }
+
+  test('announces the result count, and clearing leaves nothing stale', async () => {
+    const { page, context, goto } = await openPage({ viewport: VIEWPORTS.desktop });
+    try {
+      await goto('/');
+      const id = await visibleSearch(page);
+      expect(id).toBeTruthy();
+
+      const input = page.locator(`#${id}`);
+      const status = page.locator(`#${id}-status`);
+      const results = page.locator(`#${id}-results`);
+
+      expect(await status.textContent()).toBe('');
+
+      await input.fill('electric');
+      await expect.poll(() => status.textContent(), { timeout: 5_000 }).toMatch(/\d+ results? for/);
+      expect(await results.isVisible()).toBe(true);
+      expect(await results.getAttribute('aria-busy')).toBe('false');
+
+      // Clearing must empty the live region, or a screen reader re-reads a count
+      // for a search that no longer exists.
+      await page.locator(`#${id}-clear`).click();
+      await expect.poll(() => status.textContent()).toBe('');
+      await expect.poll(() => results.isVisible()).toBe(false);
+    } finally {
+      await context.close();
+    }
+  });
+
+  test('announces an empty result set', async () => {
+    const { page, context, goto } = await openPage({ viewport: VIEWPORTS.desktop });
+    try {
+      await goto('/');
+      const id = await visibleSearch(page);
+      const status = page.locator(`#${id}-status`);
+
+      await page.locator(`#${id}`).fill('zzzqqqxyzzy');
+      await expect.poll(() => status.textContent(), { timeout: 5_000 }).toMatch(/No results found/);
+    } finally {
+      await context.close();
+    }
+  });
+
+  test('clearing inside the debounce window does not reopen results', async () => {
+    const { page, context, goto } = await openPage({ viewport: VIEWPORTS.desktop });
+    try {
+      await goto('/');
+      const id = await visibleSearch(page);
+      const input = page.locator(`#${id}`);
+      const results = page.locator(`#${id}-results`);
+      const status = page.locator(`#${id}-status`);
+
+      // Type and clear well inside the 300ms debounce, then let it elapse.
+      await input.fill('el');
+      await page.waitForTimeout(120);
+      await page.locator(`#${id}-clear`).click();
+      await page.waitForTimeout(700);
+
+      expect(await input.inputValue()).toBe('');
+      expect(await results.isVisible()).toBe(false);
+      expect(await status.textContent()).toBe('');
+
+      // A real query afterwards still works.
+      await input.fill('electric');
+      await expect.poll(() => results.isVisible(), { timeout: 5_000 }).toBe(true);
+    } finally {
+      await context.close();
+    }
+  });
+
+  test('works from the mobile search panel too', async () => {
+    const { page, context, goto } = await openPage({ viewport: VIEWPORTS.mobile });
+    try {
+      await goto('/');
+      await page.locator('#mobile-search-toggle').click();
+      await expect
+        .poll(() => page.locator('#mobile-search-toggle').getAttribute('aria-expanded'))
+        .toBe('true');
+
+      const id = await visibleSearch(page);
+      expect(id).toBeTruthy();
+
+      await page.locator(`#${id}`).fill('electric');
+      await expect
+        .poll(() => page.locator(`#${id}-status`).textContent(), { timeout: 5_000 })
+        .toMatch(/\d+ results? for/);
+    } finally {
+      await context.close();
+    }
+  });
+});
+
+describe('image rotator autoplay (R11)', () => {
+  test('a reader pause survives the pointer leaving', async () => {
+    const { page, context, goto } = await openPage({ viewport: VIEWPORTS.desktop });
+    try {
+      await goto(ROTATOR_POST);
+
+      const rotator = page.locator('.image-rotator').first();
+      const button = rotator.locator('.rotator-playback');
+      const counter = rotator.locator('.current-index');
+
+      await expect.poll(() => button.isVisible()).toBe(true);
+      expect((await button.textContent())?.trim()).toBe('Pause slideshow');
+
+      // It advances on its own to begin with.
+      const start = await counter.textContent();
+      await expect
+        .poll(() => counter.textContent(), { timeout: ROTATION_PERIOD_MS + 2_000 })
+        .not.toBe(start);
+
+      await button.click();
+      expect((await button.textContent())?.trim()).toBe('Play slideshow');
+
+      const paused = await counter.textContent();
+      await page.waitForTimeout(ROTATION_PERIOD_MS);
+      expect(await counter.textContent()).toBe(paused);
+
+      // Pointer in and back out again must not undo the reader's choice.
+      await rotator.hover();
+      await page.mouse.move(0, 0);
+      await page.waitForTimeout(ROTATION_PERIOD_MS);
+      expect(await counter.textContent()).toBe(paused);
+      expect((await button.textContent())?.trim()).toBe('Play slideshow');
+    } finally {
+      await context.close();
+    }
+  });
+
+  test('reduced motion never auto-advances, but still offers the control', async () => {
+    const { page, context, goto } = await openPage({
+      viewport: VIEWPORTS.desktop,
+      reducedMotion: 'reduce',
+    });
+    try {
+      await goto(ROTATOR_POST);
+
+      const rotator = page.locator('.image-rotator').first();
+      const button = rotator.locator('.rotator-playback');
+      const counter = rotator.locator('.current-index');
+
+      await expect.poll(() => button.isVisible()).toBe(true);
+      // Starts paused, and says so, rather than hiding the control.
+      expect((await button.textContent())?.trim()).toBe('Play slideshow');
+
+      const start = await counter.textContent();
+      await page.waitForTimeout(ROTATION_PERIOD_MS);
+      expect(await counter.textContent()).toBe(start);
+
+      // A reader who wants motion can still opt in.
+      await button.click();
+      expect((await button.textContent())?.trim()).toBe('Pause slideshow');
+
+      // Clicking leaves the pointer resting on the rotator, and hover holds
+      // rotation by design — so nothing moves until the pointer leaves.
+      await page.waitForTimeout(ROTATION_PERIOD_MS);
+      expect(await counter.textContent()).toBe(start);
+
+      await page.mouse.move(0, 0);
+      await expect
+        .poll(() => counter.textContent(), { timeout: ROTATION_PERIOD_MS + 2_000 })
+        .not.toBe(start);
+    } finally {
+      await context.close();
+    }
+  });
+
+  test('manual navigation still works while paused', async () => {
+    const { page, context, goto } = await openPage({ viewport: VIEWPORTS.desktop });
+    try {
+      await goto(ROTATOR_POST);
+      const rotator = page.locator('.image-rotator').first();
+      await rotator.locator('.rotator-playback').click();
+
+      const counter = rotator.locator('.current-index');
+      const before = await counter.textContent();
+      await rotator.locator('.nav-next').click();
+      expect(await counter.textContent()).not.toBe(before);
+    } finally {
+      await context.close();
+    }
+  });
+});
+
+describe('mobile navigation', () => {
+  test('opens as a modal dialog and returns focus to the trigger', async () => {
+    const { page, context, goto } = await openPage({ viewport: VIEWPORTS.mobile });
+    try {
+      await goto('/');
+
+      const trigger = page.locator('#mobile-menu-button');
+      const menu = page.locator('dialog#mobile-menu');
+
+      expect(await trigger.getAttribute('aria-expanded')).toBe('false');
+      await trigger.click();
+
+      await expect.poll(() => menu.evaluate((d: HTMLDialogElement) => d.open)).toBe(true);
+      expect(await menu.evaluate((d: HTMLDialogElement) => d.matches(':modal'))).toBe(true);
+      await expect.poll(() => trigger.getAttribute('aria-expanded')).toBe('true');
+
+      await page.keyboard.press('Escape');
+      await expect.poll(() => menu.evaluate((d: HTMLDialogElement) => d.open)).toBe(false);
+      await expect.poll(() => trigger.getAttribute('aria-expanded')).toBe('false');
+      expect(await page.evaluate(() => document.activeElement?.id)).toBe('mobile-menu-button');
+    } finally {
+      await context.close();
+    }
+  });
+
+  test('closes from its close button', async () => {
+    const { page, context, goto } = await openPage({ viewport: VIEWPORTS.mobile });
+    try {
+      await goto('/');
+      await page.locator('#mobile-menu-button').click();
+
+      const menu = page.locator('dialog#mobile-menu');
+      await expect.poll(() => menu.evaluate((d: HTMLDialogElement) => d.open)).toBe(true);
+
+      await page.locator('#close-mobile-menu').click();
+      await expect.poll(() => menu.evaluate((d: HTMLDialogElement) => d.open)).toBe(false);
+    } finally {
+      await context.close();
+    }
+  });
+});
+
+describe('theme', () => {
+  test('a chosen theme survives a reload', async () => {
+    const { page, context, goto } = await openPage({ viewport: VIEWPORTS.desktop });
+    try {
+      await goto('/');
+
+      const toggle = page.locator('#theme-toggle');
+      await expect.poll(() => toggle.count()).toBe(1);
+
+      const before = await page.evaluate(() =>
+        document.documentElement.classList.contains('dark') ? 'dark' : 'light',
+      );
+
+      await toggle.click();
+      const after = await page.evaluate(() =>
+        document.documentElement.classList.contains('dark') ? 'dark' : 'light',
+      );
+      expect(after).not.toBe(before);
+      expect(await page.evaluate(() => localStorage.getItem('theme'))).toBe(after);
+
+      await page.reload({ waitUntil: 'domcontentloaded' });
+      const afterReload = await page.evaluate(() =>
+        document.documentElement.classList.contains('dark') ? 'dark' : 'light',
+      );
+      expect(afterReload).toBe(after);
+    } finally {
+      await context.close();
+    }
+  });
+});
+
+describe('bilingual routing', () => {
+  test('a Spanish twin is reachable and declares its language', async () => {
+    const { page, context, goto } = await openPage({ viewport: VIEWPORTS.desktop });
+    try {
+      await goto('/p/boundaries-miscalibration-unconditional-love-es/');
+      expect(await page.evaluate(() => document.documentElement.lang)).toBe('es');
+
+      await goto('/p/boundaries-miscalibration-unconditional-love/');
+      expect(await page.evaluate(() => document.documentElement.lang)).toBe('en');
+    } finally {
+      await context.close();
+    }
+  });
+});
diff --git a/tests/browser/service-worker.test.ts b/tests/browser/service-worker.test.ts
new file mode 100644
index 00000000..85d27130
--- /dev/null
+++ b/tests/browser/service-worker.test.ts
@@ -0,0 +1,253 @@
+import type { Page } from 'playwright';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+
+import {
+  openPage,
+  resumeServing,
+  startHarness,
+  stopHarness,
+  stopServing,
+  VIEWPORTS,
+} from './harness';
+
+/**
+ * R18. These exercise the real worker in a real browser: activation and
+ * upgrade, what survives a version bump, and whether the offline promise in
+ * public/sw.js holds.
+ *
+ * The promise under test: pages and images you have already opened stay
+ * readable offline; pages you never opened do not; API traffic is never stored.
+ */
+
+const ARTICLE = '/p/bend-dont-break-learning-to-flow-again/';
+const NEVER_VISITED = '/p/captured-not-pathetic/';
+
+beforeAll(startHarness);
+afterAll(stopHarness);
+
+async function openWithServiceWorker() {
+  return openPage({ viewport: VIEWPORTS.desktop, serviceWorkers: 'allow' });
+}
+
+/** Resolves once a worker controls the page. */
+async function waitForController(page: Page) {
+  await page.waitForFunction(() => navigator.serviceWorker.controller !== null, null, {
+    timeout: 20_000,
+  });
+}
+
+const cacheNames = (page: Page) => page.evaluate(() => caches.keys());
+
+const cachedUrls = (page: Page, cacheName: string) =>
+  page.evaluate(async (name) => {
+    const cache = await caches.open(name);
+    return (await cache.keys()).map((request) => new URL(request.url).pathname);
+  }, cacheName);
+
+/** Every path stored across every cache on the origin. */
+const allCachedPaths = (page: Page) =>
+  page.evaluate(async () => {
+    const names = await caches.keys();
+    const paths: string[] = [];
+    for (const name of names) {
+      const cache = await caches.open(name);
+      for (const request of await cache.keys()) paths.push(new URL(request.url).pathname);
+    }
+    return paths;
+  });
+
+describe('activation', () => {
+  test('registers, activates, and names every cache with the owned prefix', async () => {
+    const { page, context, goto } = await openWithServiceWorker();
+    try {
+      await goto('/');
+      await waitForController(page);
+
+      const names = await cacheNames(page);
+      expect(names.length).toBeGreaterThan(0);
+      expect(names.every((name) => name.startsWith('notes-'))).toBe(true);
+      // The shell is precached on install, so the offline page is available
+      // before the reader has visited anything.
+      expect(
+        await cachedUrls(
+          page,
+          names.find((n) => n.includes('shell'))!,
+        ),
+      ).toContain('/offline.html');
+    } finally {
+      await context.close();
+    }
+  });
+
+  test('an upgrade deletes its own stale caches but leaves other caches alone', async () => {
+    const { page, context, goto } = await openWithServiceWorker();
+    try {
+      await goto('/');
+      await waitForController(page);
+
+      // One cache belonging to something else on this origin, and one that
+      // looks like an older version of ours.
+      await page.evaluate(async () => {
+        await caches.open('some-other-tool-cache');
+        await caches.open('notes-pages-v0.0.1-old');
+      });
+
+      // Force the activate handler to run again by re-registering. Unregistering
+      // first guarantees a fresh install/activate cycle rather than a no-op.
+      await page.evaluate(async () => {
+        const registration = await navigator.serviceWorker.getRegistration();
+        await registration?.unregister();
+      });
+      await page.reload({ waitUntil: 'load' });
+      await waitForController(page);
+
+      const names = await cacheNames(page);
+      // The unrelated cache is untouched. The previous worker deleted every
+      // cache on the origin except its own current two.
+      expect(names).toContain('some-other-tool-cache');
+      // Our own stale version is gone.
+      expect(names).not.toContain('notes-pages-v0.0.1-old');
+    } finally {
+      await context.close();
+    }
+  });
+});
+
+describe('the offline promise', () => {
+  test('an article you opened stays readable offline', async () => {
+    const { page, context, goto } = await openWithServiceWorker();
+    try {
+      await goto('/');
+      await waitForController(page);
+
+      await goto(ARTICLE);
+      const onlineTitle = await page.title();
+      // Give the page and image writes attached to the fetch event time to land.
+      await page.waitForTimeout(1_000);
+
+      await stopServing();
+      await page.reload({ waitUntil: 'load' });
+
+      expect(await page.title()).toBe(onlineTitle);
+      expect(await page.locator('article, main').first().isVisible()).toBe(true);
+    } finally {
+      await resumeServing();
+      await context.close();
+    }
+  });
+
+  test('an article you never opened falls back to the offline page', async () => {
+    const { page, context, goto } = await openWithServiceWorker();
+    try {
+      await goto('/');
+      await waitForController(page);
+      await page.waitForTimeout(500);
+
+      const origin = await openPageOrigin(page);
+      await stopServing();
+      await page.goto(`${origin}${NEVER_VISITED}`, { waitUntil: 'load' });
+
+      const body = (await page.locator('body').innerText()).toLowerCase();
+      expect(body).toMatch(/you're offline|not available offline/);
+      // It must be the offline page, not a stale copy of some other article.
+      expect(await page.title()).toMatch(/offline/i);
+    } finally {
+      await resumeServing();
+      await context.close();
+    }
+  });
+
+  test('browse pages work offline too, not just articles', async () => {
+    const { page, context, goto } = await openWithServiceWorker();
+    try {
+      await goto('/');
+      await waitForController(page);
+
+      // '/everything' previously fell through to a plain fetch with no offline
+      // handling at all — only '/' and '/p/' were treated as pages.
+      await goto('/everything');
+      const onlineTitle = await page.title();
+      await page.waitForTimeout(1_000);
+
+      await stopServing();
+      await page.reload({ waitUntil: 'load' });
+      expect(await page.title()).toBe(onlineTitle);
+    } finally {
+      await resumeServing();
+      await context.close();
+    }
+  });
+
+  test('article images are cached, which AVIF never was before', async () => {
+    const { page, context, goto } = await openWithServiceWorker();
+    try {
+      await goto('/');
+      await waitForController(page);
+      await goto(ARTICLE);
+      await page.waitForTimeout(1_500);
+
+      const names = await cacheNames(page);
+      const imageCache = names.find((name) => name.includes('images'));
+      expect(imageCache).toBeTruthy();
+
+      const stored = await cachedUrls(page, imageCache!);
+      // Asserting the cache is merely non-empty is not enough: favicons and
+      // apple-touch-icon are .ico/.png and would satisfy it even with AVIF
+      // missing from the matcher, which is exactly the bug being guarded.
+      expect(stored.some((path) => /\.(avif|webp)$/i.test(path))).toBe(true);
+    } finally {
+      await context.close();
+    }
+  });
+});
+
+describe('what must never be stored', () => {
+  test('API traffic stays network-only', async () => {
+    const { page, context, goto, origin } = await openWithServiceWorker();
+    try {
+      await goto('/');
+      await waitForController(page);
+
+      await page.evaluate(async (base) => {
+        try {
+          await fetch(`${base}/api/quotes`);
+        } catch {
+          // The static server does not serve this route; the point is only that
+          // the worker must not store whatever came back.
+        }
+      }, origin);
+      await page.waitForTimeout(500);
+
+      expect((await allCachedPaths(page)).some((path) => path.startsWith('/api/'))).toBe(false);
+    } finally {
+      await context.close();
+    }
+  });
+
+  test('Open Graph cards are never cached for readers', async () => {
+    const { page, context, goto, origin } = await openWithServiceWorker();
+    try {
+      await goto('/');
+      await waitForController(page);
+
+      await page.evaluate(async (base) => {
+        try {
+          await fetch(`${base}/social/images/notes-og-abstract-social.jpg`);
+        } catch {
+          /* ignore */
+        }
+      }, origin);
+      await page.waitForTimeout(500);
+
+      // 30 MB of crawler-facing artwork a reader never displays.
+      expect((await allCachedPaths(page)).some((path) => path.startsWith('/social/'))).toBe(false);
+    } finally {
+      await context.close();
+    }
+  });
+});
+
+/** The page's own origin, for navigations that bypass the harness helper. */
+async function openPageOrigin(page: Page): Promise<string | null> {
+  return page.evaluate(() => window.location.origin);
+}
diff --git a/tsconfig.json b/tsconfig.json
index b89ffd8e..0a4766d1 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -5,6 +5,8 @@
   "compilerOptions": {
     "strict": true,
     "strictNullChecks": true,
-    "types": ["astro/client"]
+    "types": ["astro/client"],
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
   }
 }
diff --git a/vitest.browser.config.ts b/vitest.browser.config.ts
new file mode 100644
index 00000000..e1054b89
--- /dev/null
+++ b/vitest.browser.config.ts
@@ -0,0 +1,20 @@
+import { defineConfig } from 'vitest/config';
+
+/**
+ * Browser regression journeys, kept out of `pnpm test` on purpose.
+ *
+ * They need `dist/client` from a completed build and a Chromium binary, so they
+ * are a separate command (`pnpm run test:browser`) and a separate CI step after
+ * the build. The unit suite stays fast and dependency-free.
+ */
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/browser/**/*.test.ts'],
+    // One browser and one server per file; parallel files would multiply both.
+    fileParallelism: false,
+    // Journeys wait on real debounce and carousel intervals.
+    testTimeout: 60_000,
+    hookTimeout: 60_000,
+  },
+});
diff --git a/vitest.config.ts b/vitest.config.ts
index 5640153b..8b7b43e8 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -3,7 +3,8 @@ import { defineConfig } from 'vitest/config';
 export default defineConfig({
   test: {
     environment: 'node',
-    include: ['src/**/*.test.ts'],
-    // Pure utils only — no Astro SSR harness in this suite.
+    include: ['src/**/*.test.ts', 'scripts/**/*.test.mjs'],
+    // Pure utils and build-script helpers — no Astro SSR harness in this suite.
+    // Browser journeys live in vitest.browser.config.ts.
   },
 });