diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000000..0ed8b7fd6d
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,73 @@
+# Copilot instructions for ReSpec
+
+ReSpec is a browser-based tool that generates W3C specifications. Authors write HTML plus a `<script>` tag, and ReSpec fills in boilerplate, cross-references, bibliography, and validation. Roughly half of W3C standards are produced with it, so a regression here reaches a lot of documents.
+
+Contributions written with AI are welcome and have a policy: see [AI_POLICY.md](../AI_POLICY.md). Read it before opening a pull request.
+
+## Build and test
+
+This is the whole sequence. The build is part of it, and so are `BROWSERS` and `PUPPETEER_CACHE_DIR`:
+
+```bash
+export PUPPETEER_CACHE_DIR="$PWD/.cache/puppeteer"
+pnpm i --frozen-lockfile
+pnpm lint                 # tsc -p src/jsconfig.json && eslint .
+pnpm build:w3c && pnpm build:geonovum && pnpm build:aom && pnpm build:dini
+BROWSERS=ChromeHeadless pnpm test        # unit then integration, via karma
+pnpm test:build                          # the builder tool
+pnpm test:headless                       # renders examples through puppeteer
+```
+
+**Always set `BROWSERS`, or pass `--browsers`.** No karma config sets a default, so `pnpm test` on its own launches nothing, waits for a browser to connect by hand, and hangs until something kills it. Nothing in the output says so; it simply stops after printing `START:`.
+
+**Set `PUPPETEER_CACHE_DIR` to `$PWD/.cache/puppeteer` for anything that launches a browser**, which includes `pnpm test:headless` via `tools/respecDocWriter.js`. The agent environment provisions the browser there rather than in the default home cache, so puppeteer will not find it unless pointed at the same place.
+
+If you are a human with a browser already in puppeteer's default cache, you do not need that line, and you should skip it: the workspace copy is around 340 MB and does not get shared between checkouts.
+
+The integration suite (`tests/spec/`) reads the bundles in `builds/`, not `src/`, so a source change has no effect on it until the bundle is rebuilt. That is why the build sits above the test line rather than being mentioned afterwards. The unit suite (`tests/unit/`) loads `src/` directly, so it needs no rebuild and is the faster loop while iterating.
+
+There is one bundle per profile. Building only `w3c` leaves the Geonovum, DiNI and AOM suites testing the previous code, which looks like a passing or failing test that has nothing to do with the change. If a change that provably does nothing alters a test result, suspect a stale bundle before suspecting the test.
+
+Never commit anything under `builds/`. CI rebuilds it, and a PR touching it fails a dedicated check.
+
+To run a single integration suite, rebuild first, then pass the describe block. The unit config needs no rebuild:
+
+```bash
+pnpm build:w3c
+npx karma start tests/spec/karma.conf.cjs --single-run --browsers ChromeHeadless --grep="Core - Inlines"
+npx karma start tests/unit/karma.conf.cjs --single-run --browsers ChromeHeadless
+```
+
+`--grep` is a literal string match. Alternation does not work, and only the last `--grep` counts, so run separate invocations instead.
+
+## Code style
+
+Prefer functional style over imperative loops: `forEach`, `map`, `filter`, `find`, `reduce`, `some`, `every`. Use an early `return` inside `forEach` rather than `continue`. `NodeList`, `Map` and `Set` have `forEach` natively, so prefer `nodeList.forEach()` over `[...nodeList].forEach()` and avoid the extra array.
+
+Every `querySelector`, `closest`, `getElementById` and `getAttribute` result is possibly null; check before use. Do not paper over it with `?? ""`, because the empty string then flows on into an `html` template and renders as an empty text node, so the bug shows up later as missing output rather than as a null failing where it happened.
+
+Write en-US English everywhere, including comments and identifiers: behavior, color, license, center, analyze, initialize, serialize. Leave existing en-GB spelling alone when it is load-bearing, such as an established identifier or a verbatim quotation.
+
+Run `pnpm format --write` on changed files. CI fails on unformatted code.
+
+## Pull requests, commits, and comments
+
+The house style is in [AI_POLICY.md](../AI_POLICY.md) under "Write it the way the project writes it". In short:
+
+- Pull request titles follow conventional commits, `type(scope): summary`, enforced by the Check PR Title workflow.
+- Pull request descriptions are plain prose. No `## Summary`, no `## Changes`, no `## Test plan`, no emoji, no bold section labels. A closing reference goes on the first line.
+- `Closes #N` only when every ask in the issue is delivered, otherwise `Refs #N`. Confirm the number is an issue and not a pull request before citing it.
+- Commit messages are one imperative subject line, lowercase after any prefix, no trailing period, and no body unless the diff cannot be understood without one. A `Co-Authored-By` trailer naming the model that wrote it is welcome.
+- Comments say why, not what. Delete a comment that restates the line below it. No bare `fixes #1234` in source.
+
+## Tests
+
+A test that cannot fail is worse than no test, because it costs review time and implies coverage that does not exist. A regression test must fail on `main` for the reason the issue describes, and pass with the fix. Do not assert a literal the implementation just set, and do not exercise a path the issue never mentioned while the reported path stays uncovered.
+
+Do not claim a bug is fixed without showing it broken first. Run the same repro against the pre-fix state and against your fix, and put that in the PR description. Prefer running it on the base commit; when the base will not build with your new test, revert only the fix and say so. The exact format the check validates is in [ai-pr-proof-requirement.md](../ai-pr-proof-requirement.md).
+
+One concern per pull request. A locale addition or a drive-by refactor belongs in its own PR even when it is one line and obviously correct.
+
+## Adding a module
+
+A module goes in `src/core/` only if every profile wants it. If it is specific to one, put it in that profile's folder instead, as `src/w3c/` already does for eight modules. Either way it exports `name` and a `run(conf)`. `run` may be synchronous or async, whichever the work needs: most core modules are synchronous, and only the ones that fetch or await something are not. The module must be registered in every profile that needs it: `profiles/w3c.js`, `profiles/geonovum.js`, `profiles/aom.js`, `profiles/dini.js`. Tests go in `tests/spec/core/`. If the module uses `getIntlData`, add a Czech (`cs`) entry.
diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml
new file mode 100644
index 0000000000..f9f3f5cf2d
--- /dev/null
+++ b/.github/workflows/copilot-setup-steps.yml
@@ -0,0 +1,70 @@
+name: "Copilot Setup Steps"
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v5
+      - uses: actions/setup-node@v6
+        with: { node-version-file: ".nvmrc", cache: pnpm }
+
+      # Deliberately NOT setting PUPPETEER_SKIP_DOWNLOAD, though the CI workflows
+      # do. CI can skip the download because it points PUPPETEER_EXECUTABLE_PATH at
+      # the runner's Chrome for the same job. Variables set here do not reach the
+      # agent's later commands, so skipping would leave it with neither a bundled
+      # browser nor a path to one.
+      #
+      # PUPPETEER_CACHE_DIR is set per step, not on the job. Copilot honors only
+      # steps, permissions, runs-on, services, snapshot and timeout-minutes, so a
+      # job-level env block is dropped when it runs these as setup steps, even
+      # though a normal Actions run would apply it. The workspace location is
+      # deliberate: puppeteer defaults to ~/.cache/puppeteer, and the home
+      # directory is not guaranteed to survive into the agent's own session.
+      - run: pnpm i --frozen-lockfile
+        env:
+          PUPPETEER_CACHE_DIR: ${{ github.workspace }}/.cache/puppeteer
+
+      # Explicitly, rather than relying on puppeteer's postinstall. pnpm caches the
+      # fact that a build script ran, but the browser that script downloads lands
+      # outside node_modules, so on a warm store the install completes in seconds
+      # and no browser appears. This command is idempotent.
+      - run: npx puppeteer browsers install chrome
+        env:
+          PUPPETEER_CACHE_DIR: ${{ github.workspace }}/.cache/puppeteer
+
+      # karma loads the bundles from builds/, not src/, and there is one per
+      # profile. Building all four means the agent can run any suite without first
+      # working out why a src/ change had no effect on the tests.
+      - run: pnpm build:w3c
+      - run: pnpm build:geonovum
+      - run: pnpm build:aom
+      - run: pnpm build:dini
+
+      # Fails the setup loudly if puppeteer has no usable browser, rather than
+      # leaving the agent to discover it mid-task. Same cache dir as the install,
+      # or this would check a location nothing populated. Dynamic import rather
+      # than require, so it does not depend on require(esm) support if the pinned
+      # Node version ever moves.
+      - name: Check puppeteer has a browser
+        env:
+          PUPPETEER_CACHE_DIR: ${{ github.workspace }}/.cache/puppeteer
+        run: |
+          node -e "
+          const fs = require('fs');
+          import('puppeteer')
+            .then(p => p.default.executablePath())
+            .then(p => { fs.accessSync(p); console.log('browser ok:', p); })
+            .catch(e => { console.error('no usable browser:', e.message); process.exit(1); })
+          "
diff --git a/.gitignore b/.gitignore
index c43f37bd81..b5cf7c7522 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,4 +16,8 @@ package-lock.json
 yarn.lock
 *.log
 .worktrees/
-CLAUDE.md
+CLAUDE.local.md
+
+# Browser downloaded by puppeteer when PUPPETEER_CACHE_DIR points into the repo
+# (see .github/workflows/copilot-setup-steps.yml)
+.cache/
diff --git a/AI_POLICY.md b/AI_POLICY.md
new file mode 100644
index 0000000000..3c9d749824
--- /dev/null
+++ b/AI_POLICY.md
@@ -0,0 +1,92 @@
+# AI policy
+
+ReSpec accepts contributions written with AI. This document says what we ask for in return.
+
+<img src="assets/ai-is-welcome-here.png" alt="Pixel-art robot grinning in front of a burning forest, captioned &quot;AI is welcome here.&quot;" width="320">
+
+Everything under "Everyone" applies to any contributor, maintainers included, and it is short. The section after it describes the stricter process we run on our own AI generated work, and asks nothing of you.
+
+## Everyone
+
+### You are responsible for what you submit
+
+By opening a pull request you are stating that you understand every line of it, that you have run it, and that you have the right to contribute it under the project's license. Responsibility for correctness, security, and copyright sits with you, not with the tool you used. We will not accept "the AI wrote it" as an account of a defect.
+
+Two specific things to check before submitting, because generated code gets them wrong in ways that read as plausible: that every package you import actually exists and is one we already depend on or that you are deliberately adding, and that every DOM or platform API you call is real. Invented dependencies and invented APIs are the two failure modes we see most.
+
+### Disclose it
+
+If AI generated any of the logic in your contribution, say so in the pull request description. Generated logic means an agent, a function, an algorithm, a test, a feature: something you would otherwise have had to work out.
+
+You do not need to apply a label. Labeling requires triage access on this repository, which most contributors do not have, so a maintainer adds the `AI` label based on what your description says. One line is enough.
+
+Editor autocomplete, a rename refactor, or a model helping you word a comment do not need disclosing. The point is to tell a reviewer where to spend attention, not to tally tool use, and a disclosure on everything tells them nothing.
+
+### Do not paste private material into a model
+
+Whatever you send to a hosted model leaves this project, and may be retained or used for training. Do not paste into one: credentials or tokens, an embargoed or unpublished security report, a member-confidential or otherwise private W3C document, or third-party code or text you do not have the right to redistribute.
+
+This matters more here than in most projects, because the people writing specs with ReSpec routinely handle material that is under embargo or restricted to group members. If a bug can only be explained with such material, describe the shape of the problem instead, or ask a maintainer to reproduce it.
+
+### One concern per pull request
+
+A PR fixes one thing. A locale addition, a drive-by refactor, or a second bug fix belongs in its own PR, even when it is a one line change and even when it is obviously correct. Bundling is the most common reason an AI PR takes three review rounds instead of one.
+
+### Write it the way the project writes it
+
+Generated prose has a house style of its own, and it is not ours. Three places it shows up:
+
+**The pull request description** is plain prose. No `## Summary`, no `## Changes`, no `## Test plan`, no emoji, no bold section labels. If it closes an issue, that line goes first. Then say how the bug was fixed, then anything else a reviewer needs. Two or three sentences is usually enough for that part. A sentence saying what you ran locally is welcome; a formal test-plan section is not, since CI runs the tests and the reviewer can read them.
+
+**The commit message** is one imperative subject line, lowercase after any prefix, no trailing period. A body only when the diff genuinely cannot be understood without one, and then a sentence or two. No bullet lists, no "Summary", no recap of what the diff already shows. A `Co-Authored-By` trailer naming the model that wrote it is welcome, and consistent with what already appears in this project's history.
+
+**Code comments** say why, not what. A comment restating the line below it is noise a reader has to skim past, and generated code produces a lot of it. The test is not whether a comment is obvious to us, which you have no way to judge: it is whether the comment would still be needed if the reader could see the code, and they can. What earns a comment is a reason that is not visible: a workaround for a browser bug, an ordering constraint, why the obvious approach fails. The same test applies to an issue link: keep it when the issue records that reason, drop it when it does not. A bare `fixes #1234` in the source is the common failing case, since it tells a future reader nothing the history does not already hold.
+
+### Say exactly what the issue asked for
+
+Say which of the issue's asks you addressed and which you did not. A short list is fine and does not count against keeping the prose brief; the point is that a reviewer can tell at a glance whether the issue is finished, not that you produce a formal document.
+
+Only write `Closes #N` when every ask is delivered. Otherwise write `Refs #N` and say what is left. Before citing a number, confirm it is an issue rather than a pull request, and that it is open.
+
+### What does not count as a test
+
+This applies to every contribution, from anyone, wherever a test is offered as evidence that a fix works. Not every change needs a regression test: a refactor, a docs change, or a dependency bump may need none. But a test that claims to pin a bug and cannot fail proves nothing and costs review time. We reject:
+
+- a test that passes on `main` without the fix, when it is offered as proof of one
+- a test asserting a literal the implementation just set, or restating the implementation's own shape
+- a test exercising a path the issue never mentioned, while the reported path stays uncovered
+- a test whose name claims more than its body checks
+
+### Screenshots when the change is visual
+
+If the change alters rendered output, include before and after screenshots. If it does not, skip them. Most AI PRs here are not visual and screenshots would prove nothing about them.
+
+### Prove the bug is fixed
+
+A bug-fix PR has to show the bug happening before the change and not happening after it, using the same repro both times. A green test proves nothing on its own if nobody saw it fail first. For a rendering bug, add before and after images; for everything else the repro output is the proof, and images are optional. The machine-readable form the automated check looks for is specified in [ai-pr-proof-requirement.md](ai-pr-proof-requirement.md); keep the description itself plain prose.
+
+### Say what you did not fix
+
+List every review finding you chose not to act on, with your reason, in the PR before asking for another round. A finding you drop silently is a decision you made on the reviewer's behalf.
+
+## What the maintainers hold themselves to
+
+Nothing in this section is asked of you. It describes how we run our own AI generated work, and it is here so you can see the standard we are applying to ourselves rather than only to contributions.
+
+If you are contributing, you need one model and your own judgment. You are never expected to own a second AI subscription, or to orchestrate models against each other, to send us a patch.
+
+### The test is written by a different model than the fix
+
+A model that writes a fix cannot be trusted to write the test for it, because a test authored alongside an implementation tends to assert what the code happens to do rather than what the report said was broken. So, in our own pipeline:
+
+1. The test is written by a **different** model from the one writing the fix, and is written **from the issue alone, before the fix exists**. It has to fail on `main` for the reason the issue describes. Starting red is what makes passing later mean something.
+2. The fix is then written to make that test pass.
+3. A third model audits both, judging whether the test pins the reported behavior or something incidental. Every finding gets answered: fixed, or a reason why it is wrong. No thread is resolved silently.
+
+In practice that means one of Claude or Gemini writes the test and the other writes the fix, and Copilot audits both. This is enforceable for us only because we control the whole pipeline. From outside a pull request, nobody could check that the ordering happened, which is exactly why we do not ask it of anyone else.
+
+### Higher scrutiny, on purpose
+
+We hold this work to a stricter standard than a human's. A model can produce a confident, fluent, well formatted pull request that is wrong, and can do it faster than anyone can read it. That asymmetry is the reason for the extra steps.
+
+We would rather a model attempt a real fix under these checks than a timid one, so most of the hard bugs are fair game. Some are not, and this matches GitHub's own guidance on what to keep away from a coding agent: security, authentication and anything touching personal data, a production-critical breakage, and changes resting on substantial business logic or on design consistency across the codebase. Those we do ourselves.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000000..16096daa92
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,124 @@
+# ReSpec
+
+Browser-based tool that generates W3C specifications. Authors write HTML plus a `<script>` tag; ReSpec handles boilerplate, cross-references, bibliography, and validation. Around half of W3C standards are produced with it, so a regression here reaches a lot of documents.
+
+Build, test, code style, and the house style for pull requests, commits and comments live in the file below, shared with other agents rather than duplicated:
+
+@.github/copilot-instructions.md
+
+Contributions written with AI are welcome and have a policy: @AI_POLICY.md
+
+## Architecture
+
+- **`src/core/`** — profile-agnostic modules (markdown, xref, dfn, biblio, etc.)
+- **`src/w3c/`** — W3C-specific modules (headers, SoTD, conformance, SEO)
+- **`profiles/w3c.js`** — entry point that wires modules together
+- **`worker/respec-worker.js`** — Web Worker for syntax highlighting (built to `builds/`); inlined as a string in the bundle via Rollup's `text!` plugin — not loaded as a separate module at runtime
+- **`src/core/base-runner.js`** — sequential module pipeline (`run()` called on each module)
+
+The build output is an IIFE (`builds/respec-w3c.js`). Rollup captures `document.currentScript` at bundle time for `import.meta.url` resolution.
+
+## Key modules
+
+| Module                              | What it does                                                                      |
+| ----------------------------------- | --------------------------------------------------------------------------------- |
+| `src/core/dfn.js` + `dfn-map.js`    | Definition registration and export                                                |
+| `src/core/link-to-dfn.js`           | Resolves `<a>` tags to local `<dfn>` elements                                     |
+| `src/core/xref.js` + `xref-db.js`   | External term resolution via respec.org/xref API + IndexedDB cache                |
+| `src/core/biblio.js`                | Bibliography from api.specref.org + IndexedDB cache                               |
+| `src/core/inlines.js`               | All inline shorthand syntax: `[= =]`, `{{ }}`, `[[SPEC]]`, `[[[...]]]`, variables |
+| `src/core/webidl.js`                | WebIDL parsing (via webidl2 npm), semantic markup, auto-dfn                       |
+| `src/core/issues-notes.js`          | GitHub issue integration, issue/note/warning blocks                               |
+| `src/core/markdown.js`              | Optional markdown processing via `marked`                                         |
+| `src/core/dfn-panel.js`             | Interactive definition panels (hover/click)                                       |
+| `src/core/highlight.js` + `worker/` | Syntax highlighting via highlight.js in a Web Worker                              |
+| `src/w3c/headers.js`                | Full W3C header/SoTD generation                                                   |
+| `src/w3c/seo.js`                    | Schema.org JSON-LD, canonical link (`doJsonLd: true` to enable)                   |
+
+## Inline shorthand syntax reference
+
+```
+[= term =]              → link to a local/external definition
+[= For/term =]          → scoped definition link
+{{ IDLInterface }}      → WebIDL type reference
+{{ IDLInterface/member() }} → WebIDL member reference
+[[SPEC]]                → normative reference
+?[[SPEC]]               → informative reference
+[[[expand]]]            → expand section title at that ID
+[[[SPEC#id]]]           → cross-spec section link
+[[[#id]]]               → in-document section expander
+|varName|               → variable (for algorithms)
+|varName: Type|         → typed variable
+```
+
+## Testing patterns
+
+```js
+// Standard test setup
+import {
+  makeRSDoc,
+  makeStandardOps,
+  errorFilters,
+  warningFilters,
+} from "../SpecHelper.js";
+const errors = errorFilters.filter("module/name");
+const warnings = warningFilters.filter("module/name");
+
+const doc = await makeRSDoc(
+  makeStandardOps({ specStatus: "WD", group: "webapps" }, body)
+);
+```
+
+### Common Copilot findings (from respec-web-services experience)
+
+These patterns apply equally to ReSpec code:
+
+- `catch (error)` must narrow `unknown` with `instanceof Error` before accessing `.message`
+- `toThrow()` can't match messages on raw string throws — use try/catch
+- Env var save/restore in tests: reset per-test in `beforeEach`, not shared across specs
+- `setInterval` for async work risks overlap — use self-scheduling `setTimeout` with in-flight guard
+- Mock objects must match the real interface — positional args vs options object
+
+## Post-rebase verification (MANDATORY)
+
+After any rebase with conflicts, verify the working tree matches expectations:
+
+- `ls` new files to confirm they exist (rebase can silently drop additions)
+- `grep` for key additions (imports, function calls) in conflict-resolved files
+- Run `pnpm lint` before pushing — never assume the rebase was clean
+
+### CI lint failures on PRs
+
+Almost always caused by the branch being behind main. Fix:
+
+1. `git rebase main` (resolve conflicts — for `builds/` files, always take `--ours`)
+2. `git diff main --name-only | xargs npx prettier --write`
+3. `git push --force-with-lease`
+
+Do NOT commit `builds/` files — CI rebuilds them. On rebase conflicts in build artifacts, take main's version.
+
+## Pre-PR checklist (learned from Copilot reviews)
+
+Before pushing any PR, check for these patterns that Copilot consistently flags:
+
+**Null safety:** Every `querySelector()`, `closest()`, `getElementById()`, `getAttribute()` result must be checked before use. Never use `?? ""` on DOM queries (creates empty text nodes). Guard `append()` calls against null.
+
+**Template literals:** No JSDoc inside `html` template literals. Wrap `<tag>` references in backticks in error messages so they display as code, not HTML.
+
+**JSDoc:** `@param` before `@returns`, parameter order matches signature.
+
+**URLs:** Use `encodeURIComponent()` for user values in URLs. Pin CDN versions (exception: `web-features/data.json` is intentionally unversioned to reflect current browser support).
+
+**Accessibility:** Visual indicators need `aria-label` or equivalent. Don't rely on `title` alone.
+
+**Tests:** Use local fixtures, never remote endpoints. Export behaviors need `getExportedDoc()` tests. Test names must match what the test body actually exercises.
+
+**DOM node reuse:** `html` tagged template literals create DOM nodes. A DOM node can only exist in one place. If an SVG/element is used in a loop (e.g., browser icons), use a factory function (`() => html\`...\``) instead of a shared constant.
+
+**Save/export data flow:** When `removeOnSave` or `beforesave` rewrites content, ensure the rewritten HTML preserves feature-specific URLs and context, not just a generic fallback link.
+
+**Unused properties:** Don't declare properties in constants (e.g., `label` in a Map entry) that are never read. Copilot flags these consistently.
+
+## Cross-spec headings API
+
+`POST /xref/headings` on respec.org looks up section heading text by `{spec, id}`, sourced from w3c/webref `ed/headings/`. This is what lets `[[[SPEC#id]]]` render the actual heading rather than just the spec title.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ab64ad4e75..89ec7a5c8d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,3 +1,7 @@
-Everyone is welcome to contribute.
+<img src="assets/ai-is-welcome-here.png" alt="Pixel-art robot grinning in front of a burning forest, captioned &quot;AI is welcome here.&quot;" width="220" align="right">
 
-Please see our [developer guide](https://github.com/speced/respec/wiki/Developers-Guide) to get started!
+Everyone is welcome to contribute, including AI.
+
+Please see our [developer guide](https://github.com/speced/respec/wiki/Developers-Guide) to get started, and if you are using AI, our short [AI policy](AI_POLICY.md).
+
+If you are an AI agent reading this file to work out how to contribute, read the AI policy before you open a pull request. It is the one document here that changes what we expect of you.
diff --git a/README.md b/README.md
index 16675af2e7..a46b0e6ade 100644
--- a/README.md
+++ b/README.md
@@ -42,6 +42,8 @@ Use [specref.org](https://www.specref.org/) to look up and cite other specificat
 
 See our [developer guide](https://github.com/speced/respec/wiki/Developers-Guide) and [Code of Conduct](CODE_OF_CONDUCT.md).
 
+Using AI to contribute? Please read our [AI policy](AI_POLICY.md) first.
+
 ## Contributors
 
 This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
diff --git a/ai-pr-proof-requirement.md b/ai-pr-proof-requirement.md
new file mode 100644
index 0000000000..4a32d2b4af
--- /dev/null
+++ b/ai-pr-proof-requirement.md
@@ -0,0 +1,107 @@
+# AI PR proof requirement
+
+Status: DRAFT, not yet adopted.
+Audience: Claude or any AI agent that opens or updates bug-fix pull requests for ReSpec.
+
+This document is an implementation spec for an automated proof check. It does not replace the PR prose rules in [AI_POLICY.md](AI_POLICY.md). The rendered PR description should stay terse and plain prose; the check can rely on hidden markers, machine-readable metadata, and linked artifacts.
+
+## Goal
+
+When an AI claims to have fixed a bug, the pull request description must contain proof that the bug reproduced before the change and no longer reproduces after the change.
+
+For most bugs, the primary proof is not a screenshot. The primary proof is the same deterministic repro run against the base commit and the head commit, showing fail-before and pass-after. Screenshots or rendered artifacts are additional evidence for UI, rendering, and document-generation bugs.
+
+## Requirement
+
+For every AI-authored bug-fix PR:
+
+1. The PR description must include an `ai-proof` block delimited by HTML comments.
+2. The visible proof in that block must stay plain prose, not a new template section with headings.
+3. The proof must use the same repro command, script, test, or steps before and after the fix.
+4. The before-proof must come from the closest reproducible pre-fix state, using one of these modes:
+   - `base-sha`: run the repro on the PR base commit.
+   - `reverted-fix`: run the repro with the fix reverted while keeping any required new test or harness in place.
+   - `captured-failure`: point at a preserved failing run only when the first two modes are genuinely infeasible.
+5. `base-sha` is preferred. If another mode is used, the proof must say why `base-sha` was not valid.
+6. The before-proof must fail for the reason the bug describes.
+7. The after-proof must pass, or otherwise show that the incorrect behavior is gone.
+8. If no deterministic repro can be produced in any mode, the PR must be labeled speculative and the PR description must say exactly what blocked proof generation.
+9. If the bug is visual, UI-based, rendering-based, or output-based, a human MUST include a before and after screenshots or equivalent rendered artifacts.
+
+## Required proof block
+
+Every bug-fix PR description should contain a block like this:
+
+```md
+<!-- ai-proof:start -->
+
+Proof: `BROWSERS=ChromeHeadless pnpm test --grep "Core - Inlines"` fails in `reverted-fix` mode with `AssertionError: expected "foo" to equal "bar"` and passes on `def5678`. [before log](../blob/pr-assets/pr-123/before.txt?raw=1) [after log](../blob/pr-assets/pr-123/after.txt?raw=1) [before artifact](../blob/pr-assets/pr-123/before.png?raw=1) [after artifact](../blob/pr-assets/pr-123/after.png?raw=1)
+<!-- ai-proof:
+{
+   "mode": "reverted-fix",
+   "base": "abc1234",
+   "head": "def5678",
+   "repro": "BROWSERS=ChromeHeadless pnpm test --grep \"Core - Inlines\"",
+   "before": "failed",
+   "after": "passed",
+   "blocker": "base commit does not build with the new test harness"
+}
+-->
+<!-- ai-proof:end -->
+```
+
+## Rules for good proof
+
+- The repro must match the reported bug, not a nearby behavior.
+- The command or steps must be identical before and after, except for the declared proof mode.
+- The proof must include the actual base SHA and head SHA used for the runs.
+- Non-base modes must identify what was reverted or which preserved failing run is being used.
+- The proof must be regenerated after new commits are pushed to the PR.
+- A screenshot without a before-state and without matching repro evidence does not count as proof.
+- A passing test alone does not count if it was never shown failing against the declared pre-fix state.
+- The prose may summarize, but it must link the concrete output. A claim with no linked log or artifact is not proof.
+
+## Enforcement model
+
+This should be enforced mechanically, not left as a convention.
+
+Suggested policy:
+
+1. A required check validates that the PR description contains the `ai-proof` block.
+2. The validator checks that the block names the current head SHA and declares a proof mode.
+3. If the mode is `base-sha`, the validator checks that the block also names the current base SHA.
+4. If the mode is not `base-sha`, the validator checks that the block includes a blocker explaining why `base-sha` was not valid.
+5. The validator checks that the repro command is present and that the before-proof failed and the after-proof passed.
+6. For UI, rendering, and output bugs, the validator checks that the before and after artifacts are present.
+7. If the proof block is missing, stale, or incomplete, the PR fails validation.
+
+## Implementation sketch
+
+The automation can be simple:
+
+1. Determine the PR number, base SHA, and head SHA.
+2. Choose the proof mode: `base-sha` if possible, otherwise `reverted-fix`, otherwise `captured-failure`.
+3. Generate the before-proof in the chosen mode.
+4. Run the same repro on the head SHA.
+5. Save the exit codes, logs, and optional screenshots or rendered artifacts.
+6. Upload any artifacts to a stable location for the life of the PR.
+7. Rewrite only the `ai-proof` block in the PR description.
+8. Re-run the validator on every push.
+
+## Artifact backend and retention
+
+- Logs and screenshots do not need to live forever in project history.
+- The backend only needs to keep evidence available while the PR is under review.
+- One workable implementation is workflow artifacts for logs and a rewriteable `pr-assets` branch, or equivalent short-lived store, for images that must render inline in the PR description.
+- If a branch is used, it should be treated as generated proof storage and pruned after PR close or merge.
+
+## Non-goals
+
+- This is not asking the AI to write a persuasive story in the PR description.
+- This is not satisfied by saying "fixed" or "verified" with no evidence.
+- This is not satisfied by a single after screenshot.
+- This is not satisfied by a green test that was never shown failing before the patch.
+
+## Short instruction to Claude
+
+When you fix a bug, do not claim success without proof. Update the PR description with a plain-prose `ai-proof` block that shows the same repro against the closest reproducible pre-fix state and the head commit, with fail-before and pass-after. Prefer `base-sha`, but if that is not valid, declare the proof mode and blocker explicitly. If the bug is visual, rendering-related, or changes generated output, include before and after artifacts as well. If you cannot produce deterministic proof in any mode, mark the PR as speculative and state the blocker explicitly.
diff --git a/assets/ai-is-welcome-here.png b/assets/ai-is-welcome-here.png
new file mode 100644
index 0000000000..7048ead916
Binary files /dev/null and b/assets/ai-is-welcome-here.png differ
diff --git a/eslint.config.js b/eslint.config.js
index ff263f0abf..c3f37dd79d 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -7,7 +7,7 @@ import prettierRecommended from "eslint-plugin-prettier/recommended";
 
 export default [
   {
-    ignores: ["builds/**", "js/**"],
+    ignores: [".cache/**", "builds/**", "js/**"],
   },
   js.configs.recommended,
   prettierRecommended,