From f4fb97e7cd683389bee459789696e79630285adc Mon Sep 17 00:00:00 2001
From: Oto Macenauer <oto.macenauer@absa.africa>
Date: Wed, 23 Sep 2026 10:58:09 +0200
Subject: [PATCH 1/3] fix: absolute CSS URLs and no stale portal copies in a
 pierced fragment

Embedded with server-side piercing, reframed copies every linked sub-app
stylesheet into an adopted constructed stylesheet when it portals the
fragment, and only drops the copy once the sheet is fetched again. On the
moveBefore() path it never is, so the first app's CSS stayed applied to
the catalog and to every other app for the life of the fragment. The copy
also resolves url() against the host document, whose router strips the
trailing slash, so a relative url() in a sub-app stylesheet 404'd
(/knowledge-base/docs/... instead of /knowledge-base/user-guide/docs/...).

- copyAssets() now makes every url() and @import in copied sub-app CSS
  absolute, resolving relative ones against the stylesheet's own URL
  (rewriteCssUrls(), shared with the inline-style rewrite).
- embedded-transitions.js drops the knowledge base's own adopted copies
  before the first swap, identified by the layer-order statement every
  built sub-app stylesheet opens with.

Serving scripts and styles from a separate path prefix was evaluated and
rejected: the gateway dispatches on sec-fetch-dest, not on the path, and a
retargeted build reproduced both failures unchanged.

Tests: relative url() rewrite (unit + dist scan), and an embedded test
that starts on an app page, crosses to another app, and asserts no copy
remains, styles match a hard load and no request fails. Both fail without
the fix.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                           |  2 +-
 scripts/build-vite.js               | 24 +++++++------
 src/scripts/embedded-transitions.js | 37 ++++++++++++++++++-
 src/utils/transform.js              | 29 +++++++++++----
 tests/build-integrity.spec.js       | 23 ++++++++++++
 tests/css-isolation.spec.js         | 56 +++++++++++++++++++++++++++++
 tests/transform.spec.js             | 20 ++++++++++-
 7 files changed, 170 insertions(+), 21 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 1432605..00bc457 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -126,7 +126,7 @@ Known gap: inline `on*` handlers in sub-app HTML are not stripped (#67). They ar
 
 `transform.js` parses the document with **parse5** and rewrites every URL-bearing attribute to an absolute `/{prefix}/{slug}/…` path: `href`/`src`/`action`/`formaction`/`poster`, `object[data]`, `srcset`/`imagesrcset`, `url()` in inline `style=` and `<style>` blocks, and URL-bearing `<meta>` content. `<base>` tags are removed. Because it walks a parsed tree, markup quoted inside prose or comments is left alone.
 
-Root-relative `url()` inside a sub-app's **copied CSS files** is a separate rewrite, in `copyAssets()` (`scripts/build-vite.js`), targeting the same absolute path.
+`url()` and `@import` inside a sub-app's **copied CSS files** are a separate rewrite, in `copyAssets()` (`scripts/build-vite.js`, via `rewriteCssUrls()`): root-relative ones target the same absolute path, relative ones are resolved against the stylesheet's own URL and made absolute too. That is not cosmetic — a pierced fragment's linked sheets are copied by reframed into constructed stylesheets, which resolve URLs against the host document, so a relative `url()` 404s there. `embedded-transitions.js` drops those copies at the first swap (reframed never does on the `moveBefore()` path, so the first app's CSS would otherwise follow the visitor everywhere).
 
 ## Contract for Doc Apps
 
diff --git a/scripts/build-vite.js b/scripts/build-vite.js
index 97821e7..cf29d33 100644
--- a/scripts/build-vite.js
+++ b/scripts/build-vite.js
@@ -27,6 +27,7 @@ import { HOIST_DIR, hoistAppInlineScripts } from './hoist-inline-scripts.js';
 import { collectHtmlFiles } from '../src/utils/apps.js';
 import { PATH_PREFIX, REGISTRY_FILE } from '../src/utils/config.js';
 import { layerSubAppCss } from '../src/utils/css-layers.js';
+import { rewriteCssUrls } from '../src/utils/transform.js';
 import {
   ARTIFACT_NAME, MANIFEST, expandManifest, findManifestRoot, isIframe,
   readManifest, resolveRegistry, sourceKey, stagingName, toRegistryEntry,
@@ -383,8 +384,8 @@ async function build() {
   }
 
   /**
-   * Copies a sub-app's non-HTML assets, rewriting root-relative CSS url()
-   * references on the way through.
+   * Copies a sub-app's non-HTML assets, rewriting every CSS url() and
+   * `@import` to an absolute path on the way through.
    *
    * A sub-app's CSS is authored for the root of its own site, so `url(/fonts/x)`
    * means "this app's /fonts/x" — but the app is served from
@@ -394,8 +395,12 @@ async function build() {
    * `{slug}/style.css` used to climb out of the app entirely and
    * `{slug}/assets/css/a.css` landed one level short (#49). An absolute target
    * needs no depth arithmetic and matches what transform.js does for HTML.
+   *
+   * Relative references are made absolute too, resolved against the file's own
+   * URL: inside a web fragment a sheet's rules can end up resolved against the
+   * host document instead of the file (see rewriteCssUrls).
    */
-  function copyAssets(src, dest, slug) {
+  function copyAssets(src, dest, slug, rel = '') {
     mkdirSync(dest, { recursive: true });
     // withFileTypes: the entry type comes out of the directory read that already
     // happened, instead of a statSync syscall per file — and a symlink reports as
@@ -407,7 +412,7 @@ async function build() {
       const s = join(src, entry.name);
       const d = join(dest, entry.name);
 
-      if (entry.isDirectory()) { copyAssets(s, d, slug); continue; }
+      if (entry.isDirectory()) { copyAssets(s, d, slug, rel + entry.name + '/'); continue; }
       if (!entry.isFile() || entry.name.endsWith('.html')) continue;
 
       if (entry.name.endsWith('.css')) {
@@ -415,13 +420,10 @@ async function build() {
         // place, and a hardlink would write that edit back into apps/{slug}/.
         copyFileSync(s, d);
         const css = readFileSync(d, 'utf8');
-        // url(/path) | url('/path') | url("/path") → url(/{prefix}/{slug}/path).
-        // The (?!\/) guard skips protocol-relative //host/…; data: and #ref
-        // never match, since neither starts with a slash.
-        const rewritten = css.replace(
-          /url\(\s*(['"]?)\/(?!\/)/g,
-          'url($1/' + PATH_PREFIX + '/' + slug + '/',
-        );
+        // url(/path) → url(/{prefix}/{slug}/path); url(path) → resolved against
+        // this file's URL. External, protocol-relative, data: and #ref are kept.
+        const fileUrl = '/' + PATH_PREFIX + '/' + slug + '/' + rel + entry.name;
+        const rewritten = rewriteCssUrls(css, fileUrl, PATH_PREFIX, slug);
         // Then wrap the whole sheet in the sub-app cascade layer, so that a
         // sheet which outlives its page inside a web fragment cannot restyle
         // the knowledge base's own markup — see src/utils/css-layers.js.
diff --git a/src/scripts/embedded-transitions.js b/src/scripts/embedded-transitions.js
index 7871625..d1ccf9e 100644
--- a/src/scripts/embedded-transitions.js
+++ b/src/scripts/embedded-transitions.js
@@ -7,7 +7,8 @@
  * Embedded, the knowledge base's scripts run in reframed's hidden iframe, whose
  * `document` is patched so that documentElement/head/body resolve to the
  * wf-html/wf-head/wf-body elements living in the host document's shadow tree.
- * Two things go wrong for the ClientRouter there:
+ * Two things go wrong for the ClientRouter there (and a third, for a pierced
+ * first page, is dropPortalSnapshots() below):
  *
  *  1. document.startViewTransition() animates the hidden iframe, which is never
  *     painted, so a navigation swaps with no crossfade. The gateway keeps the
@@ -25,6 +26,7 @@
  *     head is diffed in place.
  */
 import { swapFunctions } from 'astro:transitions/client';
+import { LAYER_ORDER } from '../utils/css-layers.js';
 
 const PERSIST = 'data-astro-transition-persist';
 
@@ -110,7 +112,40 @@ function swapHead(head, newHead) {
   }
 }
 
+/**
+ * Removes the copies of the sub-app stylesheets that reframed left adopted on
+ * the fragment's shadow root.
+ *
+ * When reframed portals a server-rendered (pierced) fragment it copies every
+ * linked sheet's rules into a constructed stylesheet and adopts it, to cover
+ * the moment the <link> is re-inserted. It deletes those copies once it sees
+ * the stylesheet fetched again — but on the moveBefore() path the <link> is
+ * moved atomically and never re-fetched, so the copies stay adopted for the
+ * life of the fragment: the first app's CSS then applies to every page the
+ * visitor navigates to, the catalog and other apps included. Before the first
+ * swap the <link> each copy stands in for is still applied, so dropping the
+ * copies there changes nothing on the current page.
+ *
+ * Only the knowledge base's own copies are dropped: every sub-app stylesheet
+ * the build writes opens with the cascade-layer order statement (see
+ * src/utils/css-layers.js), and a copy keeps that first rule. document here is
+ * reframed's, whose adoptedStyleSheets is the fragment shadow root's.
+ */
+function dropPortalSnapshots() {
+  const adopted = document.adoptedStyleSheets;
+  if (!adopted || adopted.length === 0) return;
+  const isSnapshot = (sheet) => {
+    try {
+      return !sheet.href && sheet.cssRules[0]?.cssText === LAYER_ORDER;
+    } catch {
+      return false;
+    }
+  };
+  if (adopted.some(isSnapshot)) document.adoptedStyleSheets = adopted.filter((s) => !isSnapshot(s));
+}
+
 document.addEventListener('astro:before-swap', (event) => {
+  dropPortalSnapshots();
   const newDoc = event.newDocument;
   const current = {
     root: document.querySelector('wf-html'),
diff --git a/src/utils/transform.js b/src/utils/transform.js
index 0666c8f..6062987 100644
--- a/src/utils/transform.js
+++ b/src/utils/transform.js
@@ -60,15 +60,30 @@ const URL_META = new Set([
   'twitter:image', 'twitter:image:src',
 ]);
 
-/** Rewrites every `url(...)` reference in a CSS string (inline `style=` or a <style> block). */
-function rewriteCssUrls(css, base, prefix, slug) {
-  return css.replace(
-    /url\(\s*(['"]?)([^'")]*)\1\s*\)/gi,
-    (match, quote, url) => {
+/**
+ * Rewrites every `url(...)` reference, and every `@import "…"` string, in a CSS
+ * string — an inline `style=`, a <style> block or a copied stylesheet file —
+ * to an absolute path. `base` is the path the CSS is resolved against: the
+ * page for inline CSS, the stylesheet's own URL for a file.
+ *
+ * Absolute even where a relative URL would resolve correctly from the file,
+ * because inside a web fragment the rules do not always stay in the file.
+ * When reframed portals a server-rendered fragment it copies each linked
+ * sheet's rules into a constructed stylesheet, and a constructed sheet
+ * resolves its URLs against the HOST document — `/knowledge-base/app`, with
+ * the host router's trailing slash stripped — so `url('img/x.png')` in
+ * `/knowledge-base/app/site.css` becomes a request for `/knowledge-base/img/x.png`.
+ */
+export function rewriteCssUrls(css, base, prefix, slug) {
+  return css
+    .replace(/url\(\s*(['"]?)([^'")]*)\1\s*\)/gi, (match, quote, url) => {
       const abs = resolveUrl(url.trim(), base, prefix, slug);
       return abs === null ? match : `url(${quote}${abs}${quote})`;
-    },
-  );
+    })
+    .replace(/@import\s+(['"])([^'"]*)\1/gi, (match, quote, url) => {
+      const abs = resolveUrl(url.trim(), base, prefix, slug);
+      return abs === null ? match : `@import ${quote}${abs}${quote}`;
+    });
 }
 
 /**
diff --git a/tests/build-integrity.spec.js b/tests/build-integrity.spec.js
index bff0176..aa7de95 100644
--- a/tests/build-integrity.spec.js
+++ b/tests/build-integrity.spec.js
@@ -537,4 +537,27 @@ test.describe('stylesheet emission', () => {
     expect(css).toContain('url(#clip)');
     expect(css).toContain('url(//cdn.example.com/x.png)');
   });
+
+  test('relative url() in sub-app CSS is resolved against the stylesheet, not left relative', () => {
+    // Embedded with piercing, reframed copies a linked sheet's rules into a
+    // constructed stylesheet, which resolves URLs against the HOST document —
+    // so a relative url() fetched /knowledge-base/docs/… instead of
+    // /knowledge-base/user-guide/docs/…. Only an absolute URL survives that.
+    expect(read('user-guide/showcase.css'))
+      .toContain("url('/knowledge-base/user-guide/docs/assets/images/hero.png')");
+
+    const subAppCss = filesWithExt(DIST, '.css')
+      .map((f) => relative(DIST, f).split('\\').join('/'))
+      .filter((f) => f.includes('/') && !f.startsWith('_astro/'));
+    expect(subAppCss.length, 'no sub-app stylesheet found in dist/').toBeGreaterThan(0);
+    for (const file of subAppCss) {
+      const css = read(file);
+      const urls = [...css.matchAll(/url\(\s*['"]?([^'")]*)/gi), ...css.matchAll(/@import\s+['"]([^'"]*)/gi)]
+        .map((m) => m[1].trim())
+        .filter((u) => u && !/^([a-z][a-z0-9+.-]*:|\/\/|#)/i.test(u));
+      for (const u of urls) {
+        expect(u, `${file}: relative URL left in a sub-app stylesheet`).toMatch(/^\/knowledge-base\//);
+      }
+    }
+  });
 });
diff --git a/tests/css-isolation.spec.js b/tests/css-isolation.spec.js
index 611d691..5c17c14 100644
--- a/tests/css-isolation.spec.js
+++ b/tests/css-isolation.spec.js
@@ -302,6 +302,62 @@ for (const [mode, open] of [['bound', gotoBoundFragment], ['unbound', gotoFragme
   });
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// A first page that is an app page. Pierced, reframed portals the server-rendered
+// fragment and copies each linked sub-app sheet into an adopted constructed
+// stylesheet; it only drops the copy once the sheet is fetched again, which the
+// moveBefore() path never does. The copy then styled every later page, and
+// resolved the sheet's relative url()s against the host document (404s).
+
+/** Adopted sheets on the fragment's shadow root that are copies of a sub-app stylesheet. */
+async function adoptedSubAppCopies(page) {
+  return page.evaluate((order) => {
+    function fragmentRoot(root) {
+      if (root.querySelector('wf-document')) return root;
+      for (const el of root.querySelectorAll('*')) {
+        if (el.shadowRoot) { const f = fragmentRoot(el.shadowRoot); if (f) return f; }
+      }
+      return null;
+    }
+    const root = fragmentRoot(document);
+    return root ? root.adoptedStyleSheets.filter((s) => s.cssRules[0]?.cssText === order).length : null;
+  }, '@layer theme, base, kb-app, kb-reset, components, utilities;');
+}
+
+const PLATFORM = { path: '/knowledge-base/platform-overview/', card: '.kb-card[href="/knowledge-base/platform-overview/"]' };
+const waitForPlatform = (page) => expect.poll(async () => (await appSnapshot(page))?.h1 ?? '', { timeout: 15_000 }).toMatch(/^Platform Overview/);
+
+for (const [mode, open] of [['bound', gotoBoundFragment], ['unbound', gotoFragment]]) {
+  test.describe(`starting on an app page, ${mode} embedding`, () => {
+    test("the first app's CSS does not follow the visitor to another app, and every URL it names loads", async ({ page }) => {
+      const failed = [];
+      page.on('response', (r) => { if (r.status() >= 400) failed.push(`${r.status()} ${new URL(r.url()).pathname}`); });
+
+      await open(page, '/knowledge-base/user-guide/');
+      await waitForApp(page);
+      await page.waitForTimeout(500);
+
+      await clickInFragment(page, LIBRARY);
+      await waitForCatalog(page);
+      expect(await adoptedSubAppCopies(page), 'a copy of the first app\'s CSS is still adopted on the catalog').toBe(0);
+
+      await clickInFragment(page, PLATFORM.card);
+      await waitForPlatform(page);
+      await page.waitForTimeout(500);
+      expect(await adoptedSubAppCopies(page), 'a copy of the first app\'s CSS is still adopted on another app').toBe(0);
+      const navigated = await appSnapshot(page);
+
+      await open(page, PLATFORM.path);
+      await waitForPlatform(page);
+      await page.waitForTimeout(500);
+      const hard = await appSnapshot(page);
+      expect(navigated.styles, 'another app reached from the first is styled differently from a hard load').toEqual(hard.styles);
+
+      expect(failed, 'asset requests that failed while embedded').toEqual([]);
+    });
+  });
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 test.describe('a sub-app stylesheet that outlives its page', () => {
   /**
diff --git a/tests/transform.spec.js b/tests/transform.spec.js
index fac5e81..eb266ba 100644
--- a/tests/transform.spec.js
+++ b/tests/transform.spec.js
@@ -12,7 +12,7 @@
  */
 
 import { test, expect } from '@playwright/test';
-import { transformSubAppHtml, isThemeBootstrap } from '../src/utils/transform.js';
+import { transformSubAppHtml, isThemeBootstrap, rewriteCssUrls } from '../src/utils/transform.js';
 import { layerSubAppCss, LAYER_ORDER, SUB_APP_LAYER } from '../src/utils/css-layers.js';
 
 const PREFIX = 'knowledge-base';
@@ -116,6 +116,24 @@ test.describe('URL rewriting', () => {
     expect(bodyHtml).toContain('url(/knowledge-base/demo/bg.png)');
     expect(headHtml).toContain("url('/knowledge-base/demo/docs/img/hero.png')");
   });
+
+  test('a stylesheet file resolves its URLs against its own path, never the page', () => {
+    const css = rewriteCssUrls(
+      '@import "base.css";\n@import url(../theme/t.css) screen;\n' +
+      ".a{background:url('img/x.png')}\n.b{background:url(/root.png)}\n" +
+      '.c{background:url(data:image/gif;base64,R0)}\n.d{mask:url(#m)}\n' +
+      '.e{background:url(https://cdn.example.com/y.png)}\n.f{background:url(//cdn.example.com/z.png)}',
+      '/knowledge-base/demo/assets/css/site.css', PREFIX, SLUG,
+    );
+    expect(css).toContain('@import "/knowledge-base/demo/assets/css/base.css";');
+    expect(css).toContain('@import url(/knowledge-base/demo/assets/theme/t.css) screen;');
+    expect(css).toContain("url('/knowledge-base/demo/assets/css/img/x.png')");
+    expect(css).toContain('url(/knowledge-base/demo/root.png)');
+    expect(css).toContain('url(data:image/gif;base64,R0)');
+    expect(css).toContain('url(#m)');
+    expect(css).toContain('url(https://cdn.example.com/y.png)');
+    expect(css).toContain('url(//cdn.example.com/z.png)');
+  });
 });
 
 // Inside a web fragment a sub-app stylesheet can outlive its page (reframed

From 1d48c55d676eac869f9d874f6d8ceda45385fdda Mon Sep 17 00:00:00 2001
From: Oto Macenauer <oto.macenauer@absa.africa>
Date: Wed, 23 Sep 2026 10:58:35 +0200
Subject: [PATCH 2/3] feat(contract): rule IDs and a checker for published docs

contract/RULES.md is the catalogue: every rule a published docs site is
checked against, by ID (KB-<area>-<nnn>), with its severity, the reason
and the fix. actions/lib/rules.js is the machine side, and the self-test
fails if the two disagree on IDs, titles or severities.

actions/lib/check.js replaces verify-html.js. It parses HTML (htmlparser2)
and CSS (postcss) instead of pattern matching, so markup quoted in prose,
data blocks and article headers are not reported. Every finding names its
rule; errors stop the publish, warnings are annotated with the rule as the
title. The existing checks keep their severity and wording, now prefixed
with the ID; manifest and size failures carry KB-MAN-001 / KB-ART-00x.

New rules, all warnings so no repo pinned to @v1 starts failing: inline
event handlers and javascript: URLs (dead under script-src 'self'), a
site-level <header>, links to non-HTML files (a document request for one
is answered by the host application), !important (beats the kb-app layer
fence), dark mode, scripts/styles/fonts from another origin (CSP), and
fetches of page-relative URLs (resolved against the host page once
embedded).

actions/lib/check-cli.js runs the same checks without publishing, for a
docs repo's PR CI or an agent fixing a repo (--json, --strict).
isThemeBootstrap() moves to the dependency-free src/utils/theme.js so the
build and the checker share one definition.

htmlparser2 and postcss become direct dependencies of actions/ at the
versions its lockfile already carried.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                                     |   1 +
 README.md                                     |   1 +
 actions/lib/check-cli.js                      |  79 ++++
 actions/lib/check.js                          | 337 ++++++++++++++++++
 actions/lib/check.selftest.js                 | 256 +++++++++++++
 actions/lib/manifest.js                       |   6 +-
 actions/lib/pack.js                           |   4 +-
 actions/lib/rules.js                          |  54 +++
 actions/lib/verify-html.js                    | 135 -------
 actions/package-lock.json                     |   2 +
 actions/package.json                          |   6 +-
 actions/publish-docs/README.md                |   7 +-
 actions/publish-docs/src/index.js             |  14 +-
 actions/publish-docs/src/selftest.js          |   8 +-
 contract/HEADLESS_RULES.md                    |   4 +
 contract/RULES.md                             | 221 ++++++++++++
 .../kb-docs-add/references/troubleshooting.md |  26 +-
 src/utils/theme.js                            |  22 ++
 src/utils/transform.js                        |  18 +-
 19 files changed, 1016 insertions(+), 185 deletions(-)
 create mode 100644 actions/lib/check-cli.js
 create mode 100644 actions/lib/check.js
 create mode 100644 actions/lib/check.selftest.js
 create mode 100644 actions/lib/rules.js
 delete mode 100644 actions/lib/verify-html.js
 create mode 100644 contract/RULES.md
 create mode 100644 src/utils/theme.js

diff --git a/CLAUDE.md b/CLAUDE.md
index 00bc457..fc1bc3f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -135,6 +135,7 @@ Apps registered in `apps.json` must comply with:
 - `contract/kb-docs.schema.json` — JSON Schema for `kb-docs.json`
 - `contract/DEPLOYMENT.md` — What a private deployment repo owns, and the reusable workflow it calls
 - `contract/HEADLESS_RULES.md` — Structural requirements (headless HTML, relative paths, `data-kb-headless` attribute)
+- `contract/RULES.md` — Every checked rule by ID (`KB-<area>-<nnn>`), severity and fix. `actions/lib/rules.js` is the machine side; `actions/lib/check.selftest.js` fails if the two differ. The checker is `actions/lib/check.js` (run by `publish-docs`, or standalone via `actions/lib/check-cli.js`). New rules start as `warning`; promoting one to `error` is a major-version change of the actions
 - `contract/STYLE_GUIDE.md` — Design tokens and typography (light only — the knowledge base has no dark mode)
 - `contract/SINGLE_PAGE.md` — The copy-paste onboarding workflow for single-page docs
 
diff --git a/README.md b/README.md
index 2d43d5f..7555cdd 100644
--- a/README.md
+++ b/README.md
@@ -359,6 +359,7 @@ Apps must comply with the knowledge base contract before they can be registered:
 | [`contract/kb-docs.schema.json`](contract/kb-docs.schema.json) | JSON Schema for `kb-docs.json` |
 | [`contract/DEPLOYMENT.md`](contract/DEPLOYMENT.md) | Deployment repo layout, credentials, triggers, rollback |
 | [`contract/HEADLESS_RULES.md`](contract/HEADLESS_RULES.md) | Headless HTML, relative paths, `data-kb-headless` |
+| [`contract/RULES.md`](contract/RULES.md) | Every checked rule by ID (`KB-HTML-003` …), its severity and fix; how to run the checker |
 | [`contract/STYLE_GUIDE.md`](contract/STYLE_GUIDE.md) | Design tokens (`--color-kb-*`) and typography — light only; the knowledge base has no dark mode |
 | [`contract/SINGLE_PAGE.md`](contract/SINGLE_PAGE.md) | Zero-config markdown onboarding |
 
diff --git a/actions/lib/check-cli.js b/actions/lib/check-cli.js
new file mode 100644
index 0000000..080bcf2
--- /dev/null
+++ b/actions/lib/check-cli.js
@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * check-cli.js — runs the contract checks outside a release.
+ *
+ * The publish-docs action runs the same checks at release time; this is for
+ * everywhere else: a docs repo's pull-request CI, a local build, an agent
+ * fixing a repo. It reads nothing but the manifest and the built output, and
+ * never packs or uploads.
+ *
+ *   node actions/lib/check-cli.js [--manifest kb-docs.json] [--dist dist] [--json] [--strict]
+ *
+ * Exit status: 1 when there is an error finding (or any finding under
+ * --strict), 0 otherwise. --json prints the findings as a JSON array, for a
+ * caller that wants to act on rule IDs rather than read prose.
+ */
+
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { appDirResolver, checkApps } from './check.js';
+import { PublishError, readManifestFile } from './manifest.js';
+import { RULES_DOC, finding, formatFinding } from './rules.js';
+
+function parseArgs(argv) {
+  const args = { manifest: 'kb-docs.json', dist: 'dist', json: false, strict: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--json') args.json = true;
+    else if (arg === '--strict') args.strict = true;
+    else if (arg === '--manifest' || arg === '--dist') args[arg.slice(2)] = argv[++i];
+    else if (arg === '--help' || arg === '-h') args.help = true;
+    else throw new Error(`Unknown argument "${arg}". Try --help.`);
+  }
+  return args;
+}
+
+function collect({ manifest: manifestPath, dist }) {
+  let manifest;
+  try {
+    manifest = readManifestFile(resolve(manifestPath));
+  } catch (err) {
+    if (!(err instanceof PublishError)) throw err;
+    return [finding('KB-MAN-001', manifestPath, err.message.replace(/^KB-MAN-001 /, ''))];
+  }
+  const distDir = resolve(dist);
+  if (!existsSync(distDir)) {
+    return [finding('KB-ART-001', dist, `the built output directory does not exist. Build the site first, or pass --dist.`)];
+  }
+  const appDirFor = appDirResolver(manifest, distDir);
+  const missing = manifest.apps.filter((app) => !existsSync(appDirFor(app.slug)));
+  if (missing.length > 0) {
+    return missing.map((app) => finding('KB-ART-001', app.slug,
+      `no built output at ${appDirFor(app.slug)} — with several apps, --dist holds one subdirectory per slug.`));
+  }
+  return checkApps(manifest, appDirFor);
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log('Usage: check-cli.js [--manifest kb-docs.json] [--dist dist] [--json] [--strict]');
+    return 0;
+  }
+
+  const findings = collect(args);
+  const errors = findings.filter((f) => f.severity === 'error').length;
+
+  if (args.json) {
+    console.log(JSON.stringify(findings, null, 2));
+  } else if (findings.length === 0) {
+    console.log('No findings — the built output satisfies the knowledge base contract.');
+  } else {
+    for (const f of findings) console.log(`${f.severity.padEnd(7)} ${formatFinding(f)}`);
+    console.log(`\n${errors} error(s), ${findings.length - errors} warning(s). Each rule is explained in ${RULES_DOC}.`);
+  }
+  return errors > 0 || (args.strict && findings.length > 0) ? 1 : 0;
+}
+
+process.exitCode = main();
diff --git a/actions/lib/check.js b/actions/lib/check.js
new file mode 100644
index 0000000..b65dc1d
--- /dev/null
+++ b/actions/lib/check.js
@@ -0,0 +1,337 @@
+/**
+ * check.js — checks a built docs site against the contract, rule by rule.
+ *
+ * Runs in the publishing repo: at publish time inside the publish-docs action,
+ * and on demand through check-cli.js (a repo's own CI, or an agent fixing the
+ * repo). That is the only place anyone can act on a finding. The knowledge base
+ * build repairs some of the same things when it re-hosts a page — it hoists
+ * inline scripts, strips a theme bootstrap, absolutises CSS URLs — but by then
+ * the artifact is released and the person who can fix it has moved on.
+ *
+ * Each rule is defined in rules.js and explained in contract/RULES.md. Every
+ * finding is collected and reported together, each naming its rule and file.
+ *
+ * HTML is parsed (htmlparser2) and CSS is parsed (postcss) rather than pattern
+ * matched, so markup quoted in prose or inside a script is never mistaken for
+ * the real thing. JavaScript is not parsed: KB-JS-001 is a textual heuristic,
+ * which is why it is a warning.
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import { parseDocument } from 'htmlparser2';
+import postcss from 'postcss';
+
+import { isThemeBootstrap } from '../../src/utils/theme.js';
+import { PublishError } from './manifest.js';
+import { RULES_DOC, finding, formatFinding } from './rules.js';
+
+/** The marker the knowledge base looks for on `<html>`. */
+export const HEADLESS_MARKER = 'data-kb-headless="true"';
+/** Its pre-v1 spelling, worth naming explicitly when we see it. */
+const LEGACY_MARKER = 'data-mp-headless';
+
+/** Attributes holding one URL — the set the knowledge base rewrites. */
+const URL_ATTRS = ['href', 'src', 'action', 'formaction', 'poster'];
+
+/** Script types a browser executes. Anything else (JSON, templates) is data. */
+const EXECUTABLE_TYPES = new Set(['', 'module', 'text/javascript', 'application/javascript']);
+
+/** Pages a link may point at without leaving the fragment's document routing. */
+const PAGE_EXTENSIONS = new Set(['html', 'htm']);
+
+/** `https://…`, `http://…` or `//…` — another origin as far as the CSP is concerned. */
+const isCrossOrigin = (url) => /^(?:https?:)?\/\//i.test(url.trim());
+/** Has a scheme (`mailto:`, `data:`, `https:` …). */
+const hasScheme = (url) => /^[a-z][a-z0-9+.-]*:/i.test(url.trim());
+
+/** Every file with one of the extensions under a directory. Symlinks are skipped. */
+function filesWithExt(dir, exts, acc = []) {
+  if (!existsSync(dir)) return acc;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isSymbolicLink()) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) filesWithExt(full, exts, acc);
+    else if (exts.some((ext) => entry.name.endsWith(ext))) acc.push(full);
+  }
+  return acc;
+}
+
+/** Every .html file under a directory. Symlinks are skipped. */
+export const htmlFiles = (dir) => filesWithExt(dir, ['.html']);
+
+/** Depth-first walk over every element. */
+function* elements(node) {
+  for (const child of node.children ?? []) {
+    if (child.type === 'tag' || child.type === 'script' || child.type === 'style') {
+      yield child;
+      yield* elements(child);
+    }
+  }
+}
+
+const textOf = (el) => (el.children ?? []).map((c) => c.data ?? '').join('');
+const classes = (el) => (el?.attribs?.class ?? '').split(/\s+/).filter(Boolean);
+const quoteFirst = (list) => `"${list[0]}"`;
+
+/**
+ * Findings for one stylesheet — a file or an inline <style> block.
+ * Unparseable CSS is left to the browser: it is not a contract matter.
+ */
+function checkCss(css, where) {
+  let root;
+  try {
+    root = postcss.parse(css);
+  } catch {
+    return [];
+  }
+  const out = [];
+
+  let important = 0;
+  root.walkDecls((decl) => { if (decl.important) important++; });
+  if (important > 0) {
+    out.push(finding('KB-CSS-001', where,
+      `${important} !important declaration(s). They outrank the knowledge base's own rules, so a ` +
+      `leaked one can restyle the masthead or the catalog. Raise specificity instead.`));
+  }
+
+  const external = [];
+  root.walkAtRules('import', (rule) => {
+    const url = rule.params.match(/^(?:url\(\s*)?['"]?([^'")\s]+)/i)?.[1] ?? '';
+    if (isCrossOrigin(url)) external.push(url);
+  });
+  root.walkAtRules('font-face', (rule) => {
+    rule.walkDecls('src', (decl) => {
+      for (const m of decl.value.matchAll(/url\(\s*['"]?([^'")]+)/gi)) {
+        if (isCrossOrigin(m[1])) external.push(m[1]);
+      }
+    });
+  });
+  if (external.length > 0) {
+    out.push(finding('KB-CSP-001', where,
+      `${external.length} stylesheet or font URL(s) on another origin, e.g. ${quoteFirst(external)}. ` +
+      `The knowledge base only loads styles and fonts from itself; ship them with the site.`));
+  }
+  return out;
+}
+
+/**
+ * Findings for one script — a file or an inline block. A literal page-relative
+ * URL handed to fetch() or XMLHttpRequest resolves against the host page once
+ * embedded, not against this app.
+ */
+function checkJs(js, where) {
+  const relativeUrls = [
+    // The literal must be the whole argument: `"function"==typeof e ? … : e`
+    // in a minified bundle starts with a string too.
+    ...js.matchAll(/\bfetch\s*\(\s*(['"`])([^'"`\s]+)\1\s*[,)]/g),
+    ...js.matchAll(/\.open\s*\(\s*['"][A-Za-z]+['"]\s*,\s*(['"`])([^'"`\s]+)\1\s*[,)]/g),
+  ]
+    .map((m) => m[2])
+    .filter((url) => !hasScheme(url) && !url.startsWith('/') && !url.startsWith('#') && !url.includes('${'));
+  if (relativeUrls.length === 0) return [];
+  return [finding('KB-JS-001', where,
+    `${relativeUrls.length} fetch of a page-relative URL, e.g. ${quoteFirst(relativeUrls)}. Embedded, it ` +
+    `resolves against the host page's URL. Resolve it against the script instead: ` +
+    `new URL(url, import.meta.url) or document.currentScript.src.`)];
+}
+
+/** Findings for one HTML page. */
+function checkHtml(html, where) {
+  const out = [];
+  const doc = parseDocument(html);
+  const all = [...elements(doc)];
+  const root = all.find((el) => el.name === 'html');
+  const body = all.find((el) => el.name === 'body');
+
+  if (root?.attribs?.['data-kb-headless'] !== 'true') {
+    out.push(finding('KB-HTML-001', where, root && LEGACY_MARKER in root.attribs
+      ? `carries ${LEGACY_MARKER}, the pre-v1 marker. Emit ${HEADLESS_MARKER} instead.`
+      : `missing ${HEADLESS_MARKER} on <html>. Build with your headless flag.`));
+  }
+
+  if (all.some((el) => el.name === 'base')) {
+    out.push(finding('KB-HTML-002', where,
+      'contains a <base> element, which re-resolves every URL once the page is re-hosted.'));
+  }
+
+  const rootRelative = [];
+  const scriptUrls = [];
+  const handlers = [];
+  const nonPageLinks = [];
+  const external = [];
+  let inline = 0;
+  let themeScript = false;
+
+  for (const el of all) {
+    const attrs = el.attribs ?? {};
+
+    // Root-relative URLs are authored for the app's own site root, but the app
+    // is served from /knowledge-base/{slug}/. //host and /favicon are left
+    // alone, matching the knowledge base's own rewrite.
+    for (const name of URL_ATTRS) {
+      const value = attrs[name]?.trim();
+      if (value === undefined || el.name === 'base') continue;
+      if (value.startsWith('/') && !value.startsWith('//') && !value.startsWith('/favicon')) rootRelative.push(value);
+      if (/^javascript:/i.test(value)) scriptUrls.push(`<${el.name} ${name}>`);
+    }
+
+    for (const name of Object.keys(attrs)) {
+      if (/^on[a-z]+$/i.test(name)) handlers.push(`<${el.name} ${name}>`);
+    }
+
+    if (el.name === 'a' && attrs.href !== undefined) {
+      const href = attrs.href.trim();
+      if (href && !href.startsWith('#') && !href.startsWith('/') && !hasScheme(href)) {
+        const path = href.split(/[?#]/)[0];
+        const last = path.split('/').pop();
+        const ext = last.includes('.') ? last.split('.').pop().toLowerCase() : '';
+        if (ext && !PAGE_EXTENSIONS.has(ext)) nonPageLinks.push(href);
+      }
+    }
+
+    if (el.name === 'script') {
+      if (attrs.src !== undefined) {
+        if (isCrossOrigin(attrs.src)) external.push(attrs.src);
+      } else if (EXECUTABLE_TYPES.has((attrs.type ?? '').trim().toLowerCase())) {
+        const code = textOf(el);
+        if (code.trim() !== '') {
+          inline++;
+          if (isThemeBootstrap(code)) themeScript = true;
+          out.push(...checkJs(code, `${where} (inline script)`));
+        }
+      }
+    }
+
+    if (el.name === 'link' && attrs.href !== undefined && isCrossOrigin(attrs.href)) {
+      const rel = (attrs.rel ?? '').toLowerCase().split(/\s+/);
+      const as = (attrs.as ?? '').toLowerCase();
+      if (rel.includes('stylesheet') || (rel.some((r) => r === 'preload' || r === 'modulepreload') && ['script', 'style', 'font', ''].includes(as))) {
+        external.push(attrs.href);
+      }
+    }
+
+    if (el.name === 'style') out.push(...checkCss(textOf(el), `${where} (inline style)`));
+  }
+
+  if (rootRelative.length > 0) {
+    out.push(finding('KB-HTML-003', where,
+      `${rootRelative.length} root-relative URL(s), e.g. ${quoteFirst(rootRelative)}. ` +
+      `Paths must be relative — the app is mounted under /knowledge-base/{slug}/.`));
+  }
+  if (inline > 0) {
+    out.push(finding('KB-HTML-004', where,
+      `${inline} inline <script> block(s). The knowledge base will hoist them into files so it can ` +
+      `serve script-src 'self'; ship them as files to keep control of that.`));
+  }
+  if (handlers.length > 0) {
+    out.push(finding('KB-HTML-005', where,
+      `${handlers.length} inline event handler(s), e.g. ${handlers[0]}. The knowledge base serves ` +
+      `script-src 'self', so they never run. Attach listeners from a script file.`));
+  }
+  if (scriptUrls.length > 0) {
+    out.push(finding('KB-HTML-006', where,
+      `${scriptUrls.length} javascript: URL(s), e.g. ${scriptUrls[0]}. Blocked by the knowledge base's ` +
+      `script-src 'self'. Use a button and a listener from a script file.`));
+  }
+  const header = all.find((el) => el.name === 'header' && el.parent === body);
+  if (body && header) {
+    out.push(finding('KB-HTML-007', where,
+      'has a <header> directly inside <body>. The knowledge base masthead is the only site-level ' +
+      'header; leave yours out of the headless build.'));
+  }
+  if (nonPageLinks.length > 0) {
+    out.push(finding('KB-HTML-008', where,
+      `${nonPageLinks.length} link(s) to a non-HTML file, e.g. ${quoteFirst(nonPageLinks)}. Embedded, ` +
+      `following one loads the host application instead of the file. Link to a page that embeds it, ` +
+      `or host the file outside the docs.`));
+  }
+  if (themeScript || classes(root).includes('dark') || classes(body).includes('dark')) {
+    out.push(finding('KB-THEME-001', where,
+      'ships dark mode (a theme bootstrap script or a "dark" class). The knowledge base is light only ' +
+      'and strips both; leave them out of the headless build.'));
+  }
+  if (external.length > 0) {
+    out.push(finding('KB-CSP-001', where,
+      `${external.length} script or stylesheet URL(s) on another origin, e.g. ${quoteFirst(external)}. ` +
+      `The knowledge base only loads scripts and styles from itself; ship them with the site.`));
+  }
+  return out;
+}
+
+/**
+ * Checks one app's built output.
+ *
+ * @param {string} appDir - directory that becomes `<slug>/` in the artifact
+ * @param {object} app    - the app's manifest entry
+ * @returns {Array<{id: string, severity: string, where: string, message: string}>}
+ */
+export function checkApp(appDir, app) {
+  const out = [];
+  const rel = (file) => `${app.slug}/${relative(appDir, file).replace(/\\/g, '/')}`;
+
+  const entryPoint = app.entryPoint ?? 'index.html';
+  if (!existsSync(join(appDir, entryPoint))) {
+    out.push(finding('KB-ART-001', app.slug,
+      `entryPoint "${entryPoint}" does not exist in the built output. ` +
+      `Check the action's "dist" input points at your build directory.`));
+  }
+
+  for (const page of app.pages ?? []) {
+    if (!existsSync(join(appDir, page.path))) {
+      out.push(finding('KB-ART-002', app.slug,
+        `pages entry "${page.title}" points at "${page.path}", which is not in the built output.`));
+    }
+  }
+
+  const pages = htmlFiles(appDir);
+  if (pages.length === 0) {
+    out.push(finding('KB-ART-003', app.slug, 'the built output contains no HTML at all.'));
+    return out;
+  }
+
+  for (const file of pages) out.push(...checkHtml(readFileSync(file, 'utf8'), rel(file)));
+  for (const file of filesWithExt(appDir, ['.css'])) out.push(...checkCss(readFileSync(file, 'utf8'), rel(file)));
+  for (const file of filesWithExt(appDir, ['.js', '.mjs'])) out.push(...checkJs(readFileSync(file, 'utf8'), rel(file)));
+  return out;
+}
+
+/**
+ * Resolves an app's built output inside the `dist` input.
+ *
+ * One app is the common case, and then `dist` *is* that app's directory — a repo
+ * publishing a single site should not have to invent a subdirectory named after
+ * its own slug. With several apps, `dist` holds one subdirectory per slug.
+ */
+export function appDirResolver(manifest, distDir) {
+  if (manifest.apps.length === 1) return () => distDir;
+  return (slug) => join(distDir, slug);
+}
+
+/** Findings for every app in a manifest. */
+export function checkApps(manifest, appDirFor) {
+  return manifest.apps.flatMap((app) => checkApp(appDirFor(app.slug), app));
+}
+
+/**
+ * Checks every app in a manifest for the publish step: warnings are annotated,
+ * and any error stops the publish with every error listed at once.
+ *
+ * @param {(slug: string) => string} appDirFor - resolves an app's built output
+ */
+export function verifyApps(manifest, appDirFor) {
+  const findings = checkApps(manifest, appDirFor);
+  const warnings = findings.filter((f) => f.severity === 'warning');
+  const errors = findings.filter((f) => f.severity === 'error');
+
+  for (const w of warnings) process.stdout.write(`::warning title=${w.id}::${formatFinding(w)}\n`);
+
+  if (errors.length > 0) {
+    throw new PublishError(
+      `The built output does not satisfy the knowledge base contract (see ${RULES_DOC}):\n` +
+      errors.map((e) => `  • ${formatFinding(e)}`).join('\n'),
+    );
+  }
+  return { warnings };
+}
diff --git a/actions/lib/check.selftest.js b/actions/lib/check.selftest.js
new file mode 100644
index 0000000..675e9a0
--- /dev/null
+++ b/actions/lib/check.selftest.js
@@ -0,0 +1,256 @@
+/**
+ * check.selftest.js — `npm run selftest:check` inside actions/.
+ *
+ * Pins every rule the checker reports: a clean site produces no finding at all,
+ * each violation produces exactly the rule it breaks, and look-alikes that are
+ * not violations (markup quoted in prose, a data block, an article header, an
+ * image on a CDN) produce nothing. Then the CLI, and last the catalogue itself:
+ * contract/RULES.md and rules.js must list the same IDs, titles and severities,
+ * because the IDs are what a repo author searches for.
+ */
+
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { checkApp } from './check.js';
+import { RULES } from './rules.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLI = join(__dirname, 'check-cli.js');
+const RULES_MD = join(__dirname, '..', '..', 'contract', 'RULES.md');
+
+const root = mkdtempSync(join(tmpdir(), 'kb-check-'));
+let failures = 0;
+
+function check(name, fn) {
+  try {
+    fn();
+    console.log(`  \x1b[32m✓\x1b[0m ${name}`);
+  } catch (err) {
+    failures++;
+    console.log(`  \x1b[31m✗\x1b[0m ${name}\n    ${err.message}`);
+  }
+}
+
+const APP = { slug: 'demo', name: 'Demo', description: 'Demo docs.' };
+
+/** A compliant page; `head` and `body` are spliced in. */
+function page({ head = '', body = '', html = 'lang="en" data-kb-headless="true"', bodyAttrs = '' } = {}) {
+  return `<!doctype html>
+<html ${html}>
+<head><meta charset="utf-8"><title>T</title><link rel="stylesheet" href="assets/site.css">${head}</head>
+<body${bodyAttrs}><main id="content"><h1>T</h1>${body}</main></body>
+</html>
+`;
+}
+
+/** Writes a site into a fresh directory and returns its findings. */
+function site(name, files, app = APP) {
+  const dir = join(root, name);
+  rmSync(dir, { recursive: true, force: true });
+  for (const [rel, content] of Object.entries({ 'assets/site.css': '.doc { color: #333 }', ...files })) {
+    mkdirSync(join(dir, dirname(rel)), { recursive: true });
+    writeFileSync(join(dir, rel), content);
+  }
+  return checkApp(dir, app);
+}
+
+const ids = (findings) => findings.map((f) => f.id).sort();
+
+/** Asserts a site produces exactly these rule IDs. */
+function expectIds(findings, expected) {
+  assert.deepEqual(ids(findings), [...expected].sort(), JSON.stringify(findings, null, 2));
+}
+
+console.log('Clean output');
+
+check('a compliant site produces no finding at all', () => {
+  expectIds(site('clean', {
+    'index.html': page({
+      head: '<script src="assets/app.js" defer></script><script type="application/ld+json">{"a":1}</script>',
+      body:
+        '<article><header><h2>Section</h2></header></article>' +
+        '<p>Write <code>&lt;base href="/"&gt;</code> or <code>onclick="x()"</code> in prose freely.</p>' +
+        '<a href="guide/">Guide</a> <a href="guide/index.html#top">Top</a> <a href="#intro">Intro</a>' +
+        '<a href="https://example.com/report.pdf">External PDF</a> <a href="mailto:a@b.c">Mail</a>' +
+        '<img src="https://cdn.example.com/logo.png"> <link rel="icon" href="/favicon.ico">',
+    }),
+    'guide/index.html': page(),
+    'assets/app.js': 'fetch(new URL("data.json", import.meta.url)); fetch("/api/x"); fetch(`${base}/y`);' +
+      's.open("GET","function"==typeof e?e(n):e,!0);',
+  }), []);
+});
+
+console.log('\nManifest and artifact');
+
+check('KB-ART-001: a missing entry point', () => {
+  expectIds(site('no-entry', { 'other.html': page() }), ['KB-ART-001']);
+});
+
+check('KB-ART-002: a pages entry that is not in the output', () => {
+  const app = { ...APP, pages: [{ title: 'Gone', path: 'gone/index.html', order: 1 }] };
+  expectIds(site('gone-page', { 'index.html': page() }, app), ['KB-ART-002']);
+});
+
+check('KB-ART-003: no HTML at all', () => {
+  expectIds(site('no-html', { 'readme.txt': 'x' }, { ...APP, entryPoint: 'readme.txt' }), ['KB-ART-003']);
+});
+
+console.log('\nHTML');
+
+check('KB-HTML-001: a page without the headless marker, and the legacy marker by name', () => {
+  const missing = site('no-marker', { 'index.html': page({ html: 'lang="en"' }) });
+  expectIds(missing, ['KB-HTML-001']);
+  assert.match(missing[0].message, /missing data-kb-headless/);
+  const legacy = site('legacy-marker', { 'index.html': page({ html: 'data-mp-headless="true"' }) });
+  assert.match(legacy[0].message, /data-mp-headless.*pre-v1/);
+});
+
+check('KB-HTML-002: a <base> element', () => {
+  expectIds(site('base', { 'index.html': page({ head: '<base href="/docs/">' }) }), ['KB-HTML-002']);
+});
+
+check('KB-HTML-003: root-relative URLs, named with an example', () => {
+  const f = site('root-relative', { 'index.html': page({ body: '<img src="/images/logo.png"><a href="/guide/">G</a>' }) });
+  expectIds(f, ['KB-HTML-003']);
+  assert.match(f[0].message, /2 root-relative URL\(s\), e\.g\. "\/images\/logo\.png"/);
+});
+
+check('KB-HTML-004: an executable inline script, not a data block', () => {
+  expectIds(site('inline', { 'index.html': page({ body: '<script>console.log(1)</script><script type="importmap">{}</script>' }) }), ['KB-HTML-004']);
+});
+
+check('KB-HTML-005: an inline event handler', () => {
+  const f = site('handler', { 'index.html': page({ body: '<button onclick="go()">Go</button>' }) });
+  expectIds(f, ['KB-HTML-005']);
+  assert.match(f[0].message, /<button onclick>/);
+});
+
+check('KB-HTML-006: a javascript: URL', () => {
+  expectIds(site('js-url', { 'index.html': page({ body: '<a href="javascript:void(0)">x</a>' }) }), ['KB-HTML-006']);
+});
+
+check('KB-HTML-007: a <header> directly inside <body>, not one inside the content', () => {
+  const html = page().replace('<body>', '<body><header class="fixed top-0"><a href="./">Logo</a></header>');
+  expectIds(site('site-header', { 'index.html': html }), ['KB-HTML-007']);
+});
+
+check('KB-HTML-008: a link to a non-HTML file in the app', () => {
+  const f = site('download', { 'index.html': page({ body: '<a href="files/spec.pdf">Spec</a><a href="img/big.png?v=2">Big</a>' }) });
+  expectIds(f, ['KB-HTML-008']);
+  assert.match(f[0].message, /2 link\(s\).*"files\/spec\.pdf"/);
+});
+
+console.log('\nCSS, theme, CSP, JavaScript');
+
+check('KB-CSS-001: !important in a stylesheet file and in an inline <style>', () => {
+  const f = site('important', {
+    'index.html': page({ head: '<style>h1 { color: red !important }</style>' }),
+    'assets/site.css': 'a { color: blue !important; } p { margin: 0 !important }',
+  });
+  expectIds(f, ['KB-CSS-001', 'KB-CSS-001']);
+  assert.ok(f.some((x) => x.where === 'demo/assets/site.css' && /^2 !important/.test(x.message)), JSON.stringify(f));
+});
+
+check('KB-THEME-001: a theme bootstrap script, and a dark class', () => {
+  const bootstrap = "if (localStorage.getItem('theme') === 'dark') document.documentElement.classList.add('dark');";
+  expectIds(site('theme-script', { 'index.html': page({ head: `<script>${bootstrap}</script>` }) }), ['KB-HTML-004', 'KB-THEME-001']);
+  expectIds(site('theme-class', { 'index.html': page({ bodyAttrs: ' class="docs dark"' }) }), ['KB-THEME-001']);
+});
+
+check('KB-CSP-001: scripts, stylesheets and fonts from another origin', () => {
+  const f = site('csp', {
+    'index.html': page({ head: '<script src="https://cdn.example.com/x.js"></script><link rel="stylesheet" href="//cdn.example.com/x.css">' }),
+    'assets/site.css': "@import url('https://fonts.googleapis.com/css2?family=Inter');\n" +
+      "@font-face { font-family: X; src: url(https://cdn.example.com/x.woff2) format('woff2'); }",
+  });
+  expectIds(f, ['KB-CSP-001', 'KB-CSP-001']);
+});
+
+check('KB-JS-001: a page-relative fetch in a file and in an inline script', () => {
+  const f = site('fetch', {
+    'index.html': page({ body: "<script>fetch('search.json')</script>" }),
+    'assets/app.js': "const x = new XMLHttpRequest(); x.open('GET', 'data/index.json');",
+  });
+  expectIds(f, ['KB-HTML-004', 'KB-JS-001', 'KB-JS-001']);
+});
+
+console.log('\nCLI');
+
+function cli(dir, ...args) {
+  try {
+    return { code: 0, out: execFileSync(process.execPath, [CLI, ...args], { cwd: dir, encoding: 'utf8' }) };
+  } catch (err) {
+    return { code: err.status, out: `${err.stdout}${err.stderr}` };
+  }
+}
+
+function workspace(name, files) {
+  const dir = join(root, name);
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(join(dir, 'dist'), { recursive: true });
+  writeFileSync(join(dir, 'kb-docs.json'), JSON.stringify({ kbVersion: '1', apps: [APP] }));
+  for (const [rel, content] of Object.entries(files)) {
+    mkdirSync(join(dir, 'dist', dirname(rel)), { recursive: true });
+    writeFileSync(join(dir, 'dist', rel), content);
+  }
+  return dir;
+}
+
+check('exits 0 on warnings only, 1 under --strict, and prints rule IDs', () => {
+  const dir = workspace('cli-warn', { 'index.html': page({ body: '<script>1</script>' }) });
+  const plain = cli(dir);
+  assert.equal(plain.code, 0, plain.out);
+  assert.match(plain.out, /warning KB-HTML-004 demo\/index\.html:/);
+  assert.match(plain.out, /contract\/RULES\.md/);
+  assert.equal(cli(dir, '--strict').code, 1);
+});
+
+check('exits 1 on an error, and --json is machine-readable', () => {
+  const dir = workspace('cli-error', { 'index.html': page({ html: 'lang="en"' }) });
+  const { code, out } = cli(dir, '--json');
+  assert.equal(code, 1);
+  const findings = JSON.parse(out);
+  assert.deepEqual(findings.map((f) => [f.id, f.severity, f.where]), [['KB-HTML-001', 'error', 'demo/index.html']]);
+});
+
+check('reports a broken manifest as KB-MAN-001 instead of crashing', () => {
+  const dir = workspace('cli-manifest', { 'index.html': page() });
+  writeFileSync(join(dir, 'kb-docs.json'), '{ not json');
+  const { code, out } = cli(dir);
+  assert.equal(code, 1);
+  assert.match(out, /error {3}KB-MAN-001 kb-docs\.json: .*not valid JSON/);
+});
+
+console.log('\nCatalogue');
+
+check('contract/RULES.md and rules.js list the same rules, titles and severities', () => {
+  const md = readFileSync(RULES_MD, 'utf8');
+  const documented = {};
+  for (const m of md.matchAll(/^### (KB-[A-Z]+-\d{3}) — (.+)\n\n\*\*Severity:\*\* (error|warning)$/gm)) {
+    documented[m[1]] = { severity: m[3], title: m[2].replace(/`/g, '') };
+  }
+  const coded = Object.fromEntries(Object.entries(RULES).map(([id, r]) => [id, { severity: r.severity, title: r.title }]));
+  assert.deepEqual(documented, coded);
+
+  const indexed = [...md.matchAll(/^\| \[(KB-[A-Z]+-\d{3})\]\(#[^)]+\) \| (error|warning) \|/gm)].map((m) => [m[1], m[2]]);
+  assert.deepEqual(indexed, Object.entries(RULES).map(([id, r]) => [id, r.severity]), 'the index table is out of step');
+});
+
+check('every rule the checker can report is in the catalogue', () => {
+  const sources = ['check.js', 'check-cli.js', 'manifest.js', 'pack.js'].map((f) => readFileSync(join(__dirname, f), 'utf8')).join('\n');
+  const used = new Set(sources.match(/KB-[A-Z]+-\d{3}/g));
+  for (const id of used) assert.ok(RULES[id], `${id} is reported but not in rules.js`);
+  for (const id of Object.keys(RULES)) assert.ok(used.has(id), `${id} is in rules.js but nothing reports it`);
+});
+
+rmSync(root, { recursive: true, force: true });
+if (failures > 0) {
+  console.log(`\n\x1b[31m${failures} check(s) failed\x1b[0m`);
+  process.exit(1);
+}
+console.log('\nAll checks passed');
diff --git a/actions/lib/manifest.js b/actions/lib/manifest.js
index 56aa48e..2f52248 100644
--- a/actions/lib/manifest.js
+++ b/actions/lib/manifest.js
@@ -70,7 +70,7 @@ export function validateManifest(manifest, source) {
   });
 
   throw new PublishError(
-    `${source} does not satisfy the knowledge base contract:\n${[...new Set(lines)].join('\n')}\n\n` +
+    `KB-MAN-001 ${source} does not satisfy the knowledge base contract:\n${[...new Set(lines)].join('\n')}\n\n` +
     `See contract/ARTIFACT.md for what each field means.`,
   );
 }
@@ -83,7 +83,7 @@ export function validateManifest(manifest, source) {
 export function readManifestFile(file) {
   if (!existsSync(file)) {
     throw new PublishError(
-      `No manifest at ${file}.\n` +
+      `KB-MAN-001 No manifest at ${file}.\n` +
       `Create a ${MANIFEST} in your repository root describing the app(s) this release publishes — ` +
       `see contract/ARTIFACT.md for the shape, or set the action's "manifest" input if it lives elsewhere.`,
     );
@@ -92,7 +92,7 @@ export function readManifestFile(file) {
   try {
     manifest = JSON.parse(readFileSync(file, 'utf8'));
   } catch (err) {
-    throw new PublishError(`${file} is not valid JSON — ${err.message}`);
+    throw new PublishError(`KB-MAN-001 ${file} is not valid JSON — ${err.message}`);
   }
   return validateManifest(manifest, file);
 }
diff --git a/actions/lib/pack.js b/actions/lib/pack.js
index a9bca2c..d30637b 100644
--- a/actions/lib/pack.js
+++ b/actions/lib/pack.js
@@ -69,7 +69,7 @@ function checkSize(outPath) {
 
   if (bytes > SIZE_LIMIT) {
     throw new PublishError(
-      `The packed artifact is ${mb(bytes)} MB, over the ${mb(SIZE_LIMIT)} MB limit ` +
+      `KB-ART-005 The packed artifact is ${mb(bytes)} MB, over the ${mb(SIZE_LIMIT)} MB limit ` +
       `(which is also GitHub's per-asset release limit).\n` +
       `The usual cause is uncompressed images or a vendored toolchain the built site does not ` +
       `need at runtime. See contract/ARTIFACT.md.`,
@@ -77,7 +77,7 @@ function checkSize(outPath) {
   }
   if (bytes > SIZE_WARN) {
     process.stdout.write(
-      `::warning::The packed artifact is ${mb(bytes)} MB, over the ${mb(SIZE_WARN)} MB target. ` +
+      `::warning title=KB-ART-004::KB-ART-004 The packed artifact is ${mb(bytes)} MB, over the ${mb(SIZE_WARN)} MB target. ` +
       `Every knowledge base build downloads it — see contract/ARTIFACT.md.\n`,
     );
   }
diff --git a/actions/lib/rules.js b/actions/lib/rules.js
new file mode 100644
index 0000000..54458a9
--- /dev/null
+++ b/actions/lib/rules.js
@@ -0,0 +1,54 @@
+/**
+ * rules.js — the contract's rules, by ID.
+ *
+ * contract/RULES.md is the normative text: what each rule requires, why, and
+ * how to fix a violation. This is the machine side of the same catalogue, and
+ * the self-test fails if the two list different IDs or severities.
+ *
+ * Severity is what the publishing action does with a finding: an `error` stops
+ * the publish, a `warning` is annotated on the run and the publish goes ahead.
+ * New rules start as warnings; turning one into an error breaks repos that
+ * published fine yesterday, so that only happens with a major version.
+ */
+
+export const RULES = Object.freeze({
+  'KB-MAN-001': { severity: 'error',   title: 'kb-docs.json exists and satisfies the schema' },
+  'KB-ART-001': { severity: 'error',   title: 'The entry point exists in the built output' },
+  'KB-ART-002': { severity: 'error',   title: 'Every pages entry exists in the built output' },
+  'KB-ART-003': { severity: 'error',   title: 'Each app contains HTML' },
+  'KB-ART-004': { severity: 'warning', title: 'The artifact is at most 20 MB' },
+  'KB-ART-005': { severity: 'error',   title: 'The artifact is at most 100 MB' },
+  'KB-HTML-001': { severity: 'error',   title: 'Every page is marked headless' },
+  'KB-HTML-002': { severity: 'error',   title: 'No <base> element' },
+  'KB-HTML-003': { severity: 'error',   title: 'No root-relative URLs' },
+  'KB-HTML-004': { severity: 'warning', title: 'No inline <script> blocks' },
+  'KB-HTML-005': { severity: 'warning', title: 'No inline event handler attributes' },
+  'KB-HTML-006': { severity: 'warning', title: 'No javascript: URLs' },
+  'KB-HTML-007': { severity: 'warning', title: 'No site-level <header>' },
+  'KB-HTML-008': { severity: 'warning', title: 'No links to non-HTML files in the app' },
+  'KB-CSS-001':  { severity: 'warning', title: 'No !important declarations' },
+  'KB-THEME-001': { severity: 'warning', title: 'No dark mode' },
+  'KB-CSP-001':  { severity: 'warning', title: 'No scripts, stylesheets or fonts from another origin' },
+  'KB-JS-001':   { severity: 'warning', title: 'No fetches of page-relative URLs' },
+});
+
+/** Where a finding's rule is explained. */
+export const RULES_DOC = 'contract/RULES.md';
+
+/**
+ * A finding: one rule, one place, one message.
+ *
+ * @param {string} id      - a key of RULES
+ * @param {string} where   - `<slug>/<file>`, or whatever names the place
+ * @param {string} message - what is wrong and what to do, for the repo author
+ */
+export function finding(id, where, message) {
+  const rule = RULES[id];
+  if (!rule) throw new Error(`Unknown rule ${id} — add it to actions/lib/rules.js and ${RULES_DOC}.`);
+  return { id, severity: rule.severity, where, message };
+}
+
+/** One line per finding, as the action and the CLI print it. */
+export function formatFinding(f) {
+  return `${f.id} ${f.where}: ${f.message}`;
+}
diff --git a/actions/lib/verify-html.js b/actions/lib/verify-html.js
deleted file mode 100644
index db8ed06..0000000
--- a/actions/lib/verify-html.js
+++ /dev/null
@@ -1,135 +0,0 @@
-/**
- * verify-html.js — checks built HTML against contract/HEADLESS_RULES.md.
- *
- * This runs in the publishing repo, at publish time, which is the only moment
- * anyone can act on it. The knowledge base build warns about the same things,
- * but by then the artifact is already released and the person who can fix it has
- * moved on.
- *
- * Every problem is collected and reported together, each naming the file.
- */
-
-import { readdirSync, readFileSync, existsSync } from 'node:fs';
-import { join, relative } from 'node:path';
-
-import { PublishError } from './manifest.js';
-
-/** The marker the knowledge base looks for on `<html>`. */
-export const HEADLESS_MARKER = 'data-kb-headless="true"';
-/** Its pre-v1 spelling, worth naming explicitly when we see it. */
-const LEGACY_MARKER = 'data-mp-headless';
-
-/** Every .html file under a directory. Symlinks are skipped. */
-export function htmlFiles(dir, acc = []) {
-  if (!existsSync(dir)) return acc;
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    if (entry.isSymbolicLink()) continue;
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) htmlFiles(full, acc);
-    else if (entry.name.endsWith('.html')) acc.push(full);
-  }
-  return acc;
-}
-
-/**
- * Verifies one app's built output.
- *
- * @param {string} appDir - directory that becomes `<slug>/` in the artifact
- * @param {object} app    - the app's manifest entry
- * @returns {{errors: string[], warnings: string[]}}
- */
-export function verifyApp(appDir, app) {
-  const errors = [];
-  const warnings = [];
-  const rel = (file) => relative(appDir, file).replace(/\\/g, '/');
-
-  const entryPoint = app.entryPoint ?? 'index.html';
-  if (!existsSync(join(appDir, entryPoint))) {
-    errors.push(
-      `${app.slug}: entryPoint "${entryPoint}" does not exist in the built output. ` +
-      `Check the action's "dist" input points at your build directory.`,
-    );
-  }
-
-  for (const page of app.pages ?? []) {
-    if (!existsSync(join(appDir, page.path))) {
-      errors.push(
-        `${app.slug}: pages entry "${page.title}" points at "${page.path}", which is not in the built output.`,
-      );
-    }
-  }
-
-  const files = htmlFiles(appDir);
-  if (files.length === 0) {
-    errors.push(`${app.slug}: the built output contains no HTML at all.`);
-    return { errors, warnings };
-  }
-
-  for (const file of files) {
-    const html = readFileSync(file, 'utf8');
-    const where = `${app.slug}/${rel(file)}`;
-
-    if (!html.includes(HEADLESS_MARKER)) {
-      errors.push(
-        html.includes(LEGACY_MARKER)
-          ? `${where}: carries ${LEGACY_MARKER}, the pre-v1 marker. Emit ${HEADLESS_MARKER} instead.`
-          : `${where}: missing ${HEADLESS_MARKER} on <html>. Build with your headless flag.`,
-      );
-    }
-
-    if (/<base\b/i.test(html)) {
-      errors.push(`${where}: contains a <base> element, which re-resolves every URL once the page is re-hosted.`);
-    }
-
-    // Root-relative URLs are authored for the app's own site root, but the app
-    // is served from /knowledge-base/{slug}/, so they 404 there. //host and
-    // /favicon are left alone, matching the knowledge base's own rewrite.
-    const absolute = [...html.matchAll(/\b(?:href|src|action|poster)="(\/[^/"][^"]*)"/g)]
-      .map((m) => m[1])
-      .filter((url) => !url.startsWith('/favicon'));
-    if (absolute.length > 0) {
-      errors.push(
-        `${where}: ${absolute.length} root-relative URL(s), e.g. "${absolute[0]}". ` +
-        `Paths must be relative — the app is mounted under /knowledge-base/{slug}/.`,
-      );
-    }
-
-    // Not fatal: the knowledge base hoists inline scripts so it can serve
-    // script-src 'self'. The repo should still know they are there.
-    const inline = [...html.matchAll(/<script\b(?![^>]*\bsrc=)[^>]*>([\s\S]*?)<\/script>/gi)]
-      .filter((m) => m[1].trim() !== '');
-    if (inline.length > 0) {
-      warnings.push(
-        `${where}: ${inline.length} inline <script> block(s). The knowledge base will hoist them into ` +
-        `files so it can serve script-src 'self'; ship them as files to keep control of that.`,
-      );
-    }
-  }
-
-  return { errors, warnings };
-}
-
-/**
- * Verifies every app in a manifest and throws once if any failed.
- *
- * @param {(slug: string) => string} appDirFor - resolves an app's built output
- */
-export function verifyApps(manifest, appDirFor) {
-  const errors = [];
-  const warnings = [];
-  for (const app of manifest.apps) {
-    const result = verifyApp(appDirFor(app.slug), app);
-    errors.push(...result.errors);
-    warnings.push(...result.warnings);
-  }
-
-  for (const warning of warnings) process.stdout.write(`::warning::${warning}\n`);
-
-  if (errors.length > 0) {
-    throw new PublishError(
-      `The built output does not satisfy contract/HEADLESS_RULES.md:\n` +
-      errors.map((e) => `  • ${e}`).join('\n'),
-    );
-  }
-  return { warnings };
-}
diff --git a/actions/package-lock.json b/actions/package-lock.json
index 25f1e7c..a49c468 100644
--- a/actions/package-lock.json
+++ b/actions/package-lock.json
@@ -11,11 +11,13 @@
       "dependencies": {
         "ajv": "8.17.1",
         "highlight.js": "11.11.1",
+        "htmlparser2": "8.0.2",
         "markdown-it": "14.1.0",
         "markdown-it-anchor": "9.2.0",
         "markdown-it-footnote": "4.0.0",
         "markdown-it-task-lists": "2.1.1",
         "mermaid": "11.4.1",
+        "postcss": "8.5.28",
         "sanitize-html": "2.17.0",
         "yaml": "2.7.1"
       }
diff --git a/actions/package.json b/actions/package.json
index e935d12..c6a50e2 100644
--- a/actions/package.json
+++ b/actions/package.json
@@ -6,7 +6,9 @@
   "type": "module",
   "license": "Apache-2.0",
   "scripts": {
-    "selftest": "node publish-single-page-docs/src/selftest.js && node publish-docs/src/selftest.js && node lib/release.selftest.js",
+    "selftest": "node publish-single-page-docs/src/selftest.js && node publish-docs/src/selftest.js && node lib/release.selftest.js && node lib/check.selftest.js",
+    "selftest:check": "node lib/check.selftest.js",
+    "check": "node lib/check-cli.js",
     "selftest:single-page": "node publish-single-page-docs/src/selftest.js",
     "selftest:docs": "node publish-docs/src/selftest.js",
     "selftest:release": "node lib/release.selftest.js"
@@ -14,11 +16,13 @@
   "dependencies": {
     "ajv": "8.17.1",
     "highlight.js": "11.11.1",
+    "htmlparser2": "8.0.2",
     "markdown-it": "14.1.0",
     "markdown-it-anchor": "9.2.0",
     "markdown-it-footnote": "4.0.0",
     "markdown-it-task-lists": "2.1.1",
     "mermaid": "11.4.1",
+    "postcss": "8.5.28",
     "sanitize-html": "2.17.0",
     "yaml": "2.7.1"
   }
diff --git a/actions/publish-docs/README.md b/actions/publish-docs/README.md
index 7d33cfc..204c578 100644
--- a/actions/publish-docs/README.md
+++ b/actions/publish-docs/README.md
@@ -17,8 +17,11 @@ The action never builds your site. Doc repos use mkdocs, Starlight, Jekyll and
 hand-rolled scripts; the contract is about the output, not the toolchain.
 
 **Full documentation — the artifact layout, the manifest and its schema —
-lives in [`contract/ARTIFACT.md`](../../contract/ARTIFACT.md).** The HTML rules
-it checks are [`contract/HEADLESS_RULES.md`](../../contract/HEADLESS_RULES.md).
+lives in [`contract/ARTIFACT.md`](../../contract/ARTIFACT.md).** Every check it
+runs is a rule in [`contract/RULES.md`](../../contract/RULES.md), and every finding
+names its rule ID: errors stop the publish, warnings are annotated on the run. The
+same checks run without publishing through `actions/lib/check-cli.js` — see
+`contract/RULES.md` → "Running the checks".
 
 If your docs are a markdown file or two rather than a site, you want
 [`publish-single-page-docs`](../publish-single-page-docs) instead: it renders the
diff --git a/actions/publish-docs/src/index.js b/actions/publish-docs/src/index.js
index 0763fd5..f8a94f5 100644
--- a/actions/publish-docs/src/index.js
+++ b/actions/publish-docs/src/index.js
@@ -23,19 +23,7 @@ import { join, resolve } from 'node:path';
 import { ASSET_NAME, PublishError, readManifestFile, writeManifest } from '../../lib/manifest.js';
 import { packArtifact } from '../../lib/pack.js';
 import { run, setOutput, summary } from '../../lib/runner.js';
-import { verifyApps } from '../../lib/verify-html.js';
-
-/**
- * Resolves an app's built output inside the `dist` input.
- *
- * One app is the common case, and then `dist` *is* that app's directory — a repo
- * publishing a single site should not have to invent a subdirectory named after
- * its own slug. With several apps, `dist` holds one subdirectory per slug.
- */
-function appDirResolver(manifest, distDir) {
-  if (manifest.apps.length === 1) return () => distDir;
-  return (slug) => join(distDir, slug);
-}
+import { appDirResolver, verifyApps } from '../../lib/check.js';
 
 function main() {
   const workspace = resolve(process.env.KB_WORKSPACE || process.cwd());
diff --git a/actions/publish-docs/src/selftest.js b/actions/publish-docs/src/selftest.js
index 7a42554..b63e291 100644
--- a/actions/publish-docs/src/selftest.js
+++ b/actions/publish-docs/src/selftest.js
@@ -17,7 +17,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { ASSET_NAME, MANIFEST, PublishError, buildManifest, readManifestFile } from '../../lib/manifest.js';
-import { verifyApp } from '../../lib/verify-html.js';
+import { checkApp } from '../../lib/check.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ENTRY = join(__dirname, 'index.js');
@@ -213,19 +213,19 @@ try {
       files: { 'index.html': page('X', '<script>console.log(1)</script>') },
     });
     const { stdout, artifact } = publish(ws);
-    assert.match(stdout, /::warning::.*inline <script>/);
+    assert.match(stdout, /::warning title=KB-HTML-004::.*inline <script>/);
     assert.ok(existsSync(artifact), 'a warning must not block the publish');
   });
 
   check('accepts a page whose only absolute URL is a favicon', () => {
-    const { errors } = verifyApp(
+    const findings = checkApp(
       workspace('favicon', {
         manifest: ONE_APP,
         files: { 'index.html': page('X', '<link rel="icon" href="/favicon.ico">') },
       }) + '/dist',
       ONE_APP.apps[0],
     );
-    assert.deepEqual(errors, []);
+    assert.deepEqual(findings.filter((f) => f.severity === 'error'), []);
   });
 
   // ── Packing ────────────────────────────────────────────────────────────────
diff --git a/contract/HEADLESS_RULES.md b/contract/HEADLESS_RULES.md
index 1d05cb9..d46fe7f 100644
--- a/contract/HEADLESS_RULES.md
+++ b/contract/HEADLESS_RULES.md
@@ -194,6 +194,10 @@ move.
 
 ## Checklist
 
+Each item below is checked by the `publish-docs` action; [`RULES.md`](./RULES.md) lists
+every rule it checks by ID — these and the warnings beyond them — and shows how to run
+the same checks before you release.
+
 Before opening a PR to add your app to `apps.json`:
 
 - [ ] `kb-docs.json` is in the repo root and validates against [`contract/kb-docs.schema.json`](./kb-docs.schema.json)
diff --git a/contract/RULES.md b/contract/RULES.md
new file mode 100644
index 0000000..7c57387
--- /dev/null
+++ b/contract/RULES.md
@@ -0,0 +1,221 @@
+# Contract rules
+
+Every requirement a published docs site is checked against, by ID. The other contract
+pages explain the model — [`ARTIFACT.md`](./ARTIFACT.md) the archive and manifest,
+[`HEADLESS_RULES.md`](./HEADLESS_RULES.md) the headless build — and this page is the
+list a check reports against: each finding names one of these IDs.
+
+**Severity** is what the `publish-docs` action does with a finding:
+
+- **error** — the publish stops, with every error listed at once.
+- **warning** — the finding is annotated on the workflow run, and the publish goes ahead.
+  The knowledge base either repairs it when it re-hosts the page, or it only hurts the
+  page that carries it. Fix it anyway: a repaired page is not the page you wrote.
+
+New rules are introduced as warnings. A warning only becomes an error in a new major
+version of the actions (`@v2`), so a repo pinned to `@v1` never starts failing on a rule
+it has not seen before.
+
+## Running the checks
+
+The `publish-docs` action runs them before it packs anything. To run them earlier — on
+a pull request, or while fixing a repo — use the same code from a checkout of this
+repository:
+
+```bash
+git clone --depth 1 https://github.com/AbsaOSS/knowledge-base.git /tmp/knowledge-base
+npm ci --omit=dev --prefix /tmp/knowledge-base/actions
+node /tmp/knowledge-base/actions/lib/check-cli.js --manifest kb-docs.json --dist dist
+```
+
+`--json` prints the findings as a JSON array (`id`, `severity`, `where`, `message`);
+`--strict` exits non-zero on warnings as well as errors.
+
+## Index
+
+| ID | Severity | Rule |
+|---|---|---|
+| [KB-MAN-001](#kb-man-001--kb-docsjson-exists-and-satisfies-the-schema) | error | kb-docs.json exists and satisfies the schema |
+| [KB-ART-001](#kb-art-001--the-entry-point-exists-in-the-built-output) | error | The entry point exists in the built output |
+| [KB-ART-002](#kb-art-002--every-pages-entry-exists-in-the-built-output) | error | Every pages entry exists in the built output |
+| [KB-ART-003](#kb-art-003--each-app-contains-html) | error | Each app contains HTML |
+| [KB-ART-004](#kb-art-004--the-artifact-is-at-most-20-mb) | warning | The artifact is at most 20 MB |
+| [KB-ART-005](#kb-art-005--the-artifact-is-at-most-100-mb) | error | The artifact is at most 100 MB |
+| [KB-HTML-001](#kb-html-001--every-page-is-marked-headless) | error | Every page is marked headless |
+| [KB-HTML-002](#kb-html-002--no-base-element) | error | No `<base>` element |
+| [KB-HTML-003](#kb-html-003--no-root-relative-urls) | error | No root-relative URLs |
+| [KB-HTML-004](#kb-html-004--no-inline-script-blocks) | warning | No inline `<script>` blocks |
+| [KB-HTML-005](#kb-html-005--no-inline-event-handler-attributes) | warning | No inline event handler attributes |
+| [KB-HTML-006](#kb-html-006--no-javascript-urls) | warning | No `javascript:` URLs |
+| [KB-HTML-007](#kb-html-007--no-site-level-header) | warning | No site-level `<header>` |
+| [KB-HTML-008](#kb-html-008--no-links-to-non-html-files-in-the-app) | warning | No links to non-HTML files in the app |
+| [KB-CSS-001](#kb-css-001--no-important-declarations) | warning | No `!important` declarations |
+| [KB-THEME-001](#kb-theme-001--no-dark-mode) | warning | No dark mode |
+| [KB-CSP-001](#kb-csp-001--no-scripts-stylesheets-or-fonts-from-another-origin) | warning | No scripts, stylesheets or fonts from another origin |
+| [KB-JS-001](#kb-js-001--no-fetches-of-page-relative-urls) | warning | No fetches of page-relative URLs |
+
+---
+
+## Manifest and artifact
+
+### KB-MAN-001 — kb-docs.json exists and satisfies the schema
+
+**Severity:** error
+
+The manifest must exist where the action's `manifest` input points, parse as JSON and
+validate against [`kb-docs.schema.json`](./kb-docs.schema.json). Every schema violation
+is reported at once, each naming the field. Fields are specified in
+[`ARTIFACT.md`](./ARTIFACT.md).
+
+### KB-ART-001 — The entry point exists in the built output
+
+**Severity:** error
+
+Each app's `entryPoint` (default `index.html`) must exist in that app's built directory.
+Usually the action's `dist` input points at the wrong directory, or — with several apps —
+`dist` does not hold one subdirectory per slug.
+
+### KB-ART-002 — Every pages entry exists in the built output
+
+**Severity:** error
+
+When an app lists `pages`, every `path` must exist. The list is the authoritative route
+table; a missing page is a broken navigation entry.
+
+### KB-ART-003 — Each app contains HTML
+
+**Severity:** error
+
+An app directory with no `.html` file at all has nothing to serve.
+
+### KB-ART-004 — The artifact is at most 20 MB
+
+**Severity:** warning
+
+Every registered artifact is downloaded on every knowledge base build. Over 20 MB the
+action warns; see the size table in [`ARTIFACT.md`](./ARTIFACT.md). Uncompressed images
+and vendored toolchains are the usual cause.
+
+### KB-ART-005 — The artifact is at most 100 MB
+
+**Severity:** error
+
+Over 100 MB the action refuses to publish. It is also GitHub's per-asset release limit.
+
+## HTML
+
+### KB-HTML-001 — Every page is marked headless
+
+**Severity:** error
+
+`<html>` must carry `data-kb-headless="true"`, which is what a headless build emits (see
+[`HEADLESS_RULES.md`](./HEADLESS_RULES.md)). The pre-v1 spelling `data-mp-headless` is
+reported by name: republish with a current action.
+
+### KB-HTML-002 — No `<base>` element
+
+**Severity:** error
+
+A `<base>` re-resolves every relative URL on the page against a location of its own,
+which stops being right the moment the page is re-hosted under `/knowledge-base/{slug}/`.
+
+### KB-HTML-003 — No root-relative URLs
+
+**Severity:** error
+
+`href`, `src`, `action`, `formaction` and `poster` values must be relative (`guide/`,
+`../img/x.png`), not root-relative (`/guide/`). The app is served from
+`/knowledge-base/{slug}/`; the knowledge base rebases a root-relative URL onto that app
+root, which is only what you meant if your site was built for the root of a domain.
+Relative paths mean the same thing everywhere. `/favicon…` and protocol-relative
+`//host/…` URLs are not checked.
+
+### KB-HTML-004 — No inline `<script>` blocks
+
+**Severity:** warning
+
+The knowledge base serves `script-src 'self'`, so it moves every executable inline script
+into a file of its own when it re-hosts the page. Ship scripts as files to keep control
+of what runs. JSON and other data blocks (`type="application/ld+json"` and the like) are
+not scripts and are not reported.
+
+### KB-HTML-005 — No inline event handler attributes
+
+**Severity:** warning
+
+`onclick="…"` and every other `on*` attribute is blocked by `script-src 'self'`: the
+handler never runs. Attach listeners from a script file.
+
+### KB-HTML-006 — No `javascript:` URLs
+
+**Severity:** warning
+
+Blocked by `script-src 'self'` for the same reason as KB-HTML-005. Use a `<button>` with
+a listener from a script file.
+
+### KB-HTML-007 — No site-level `<header>`
+
+**Severity:** warning
+
+The knowledge base masthead is the only site-level header. A `<header>` directly inside
+`<body>` is the site bar a headless build must leave out (see
+[`HEADLESS_RULES.md`](./HEADLESS_RULES.md)). A `<header>` inside your content — an
+article or section header — is fine and is not reported.
+
+### KB-HTML-008 — No links to non-HTML files in the app
+
+**Severity:** warning
+
+Embedded in a host application, the knowledge base's URLs are routed through the host.
+A request for a page loads the page; a request the browser makes *as a document* for
+anything else — a PDF, a ZIP, an image opened from a link — reaches the host
+application, which answers with its own page instead of the file. Link to an HTML page
+that embeds or describes the file, or host downloads outside the docs. Links to other
+origins are not reported.
+
+## CSS
+
+### KB-CSS-001 — No `!important` declarations
+
+**Severity:** warning
+
+Every sub-app stylesheet is wrapped in the `kb-app` cascade layer, below the knowledge
+base's own rules, so a stylesheet that outlives its page cannot restyle the masthead or
+the catalog. `!important` inverts layer order: an important declaration in a lower layer
+beats a normal one in a higher layer. Raise specificity instead.
+
+## Theme
+
+### KB-THEME-001 — No dark mode
+
+**Severity:** warning
+
+The knowledge base is light only (see [`STYLE_GUIDE.md`](./STYLE_GUIDE.md)). It deletes
+a theme bootstrap script and a `dark` class on `<html>` or `<body>` when it re-hosts the
+page, so a headless build should not ship them.
+
+## Content Security Policy
+
+### KB-CSP-001 — No scripts, stylesheets or fonts from another origin
+
+**Severity:** warning
+
+The knowledge base serves `script-src 'self'`, `style-src 'self' 'unsafe-inline'` and
+`font-src 'self' data:`. A `<script src>`, a stylesheet `<link>`, a preload of a script,
+style or font, a CSS `@import` or an `@font-face` source on another origin is blocked.
+Ship them with the site. Images from `https:` origins are allowed.
+
+## JavaScript
+
+### KB-JS-001 — No fetches of page-relative URLs
+
+**Severity:** warning
+
+Embedded, a page-relative URL is resolved against the **host** page, not against your
+app: elements a script creates belong to the host document, and a host router may
+strip the trailing slash from `/knowledge-base/{slug}/page/`, which moves every relative
+URL one directory up. A literal relative URL passed to `fetch()` or
+`XMLHttpRequest.open()` is reported. Resolve it against the script instead —
+`new URL('data.json', import.meta.url)` in a module, or `document.currentScript.src` in
+a classic script. This is a textual check: URLs assembled at runtime are not seen, and a
+match inside a string or comment is reported anyway.
diff --git a/skills/kb-docs-add/references/troubleshooting.md b/skills/kb-docs-add/references/troubleshooting.md
index 4ebe226..69a8c71 100644
--- a/skills/kb-docs-add/references/troubleshooting.md
+++ b/skills/kb-docs-add/references/troubleshooting.md
@@ -35,19 +35,23 @@ All reported at once, each naming `docs[i]` and the fix.
 
 ## `publish-docs` manifest and HTML errors
 
+Every finding starts with a rule ID; `contract/RULES.md` explains each one, including
+the warnings not listed here. The same checks run before a release with
+`node <knowledge-base>/actions/lib/check-cli.js --manifest kb-docs.json --dist <dir>`.
+
 | Message | Fix |
 |---|---|
-| `No manifest at kb-docs.json` | Put `kb-docs.json` at the repo root, or set the `manifest` input to where it is. |
-| `kb-docs.json is not valid JSON` | Trailing comma or comment. JSON, not JSONC. |
-| `kb-docs.json does not satisfy the knowledge base contract:` … | Each bullet names the field. Common: `kbVersion` as a number (must be the string `"1"`), `description` too short, `slug` with a capital, an unknown key in `pages[]`. |
-| `<slug>: entryPoint "index.html" does not exist in the built output` | The `dist` input points at the wrong directory, or the build writes somewhere else (mkdocs `site_dir`, Astro `outDir`). For a one-app manifest `dist` is the app directory itself, not its parent. |
-| `<slug>: pages entry "…" points at "…", which is not in the built output` | Path in `pages[]` does not match the generator's output layout (`foo.html` vs `foo/index.html`). Fix the path or drop `pages`. |
-| `<slug>: the built output contains no HTML at all` | Wrong `dist`, or the build failed silently. |
-| `<slug>/…: missing data-kb-headless="true" on <html>` | The headless variant was not the one built, or the template does not emit the attribute. See `packaged.md` §A. |
-| `<slug>/…: carries data-mp-headless, the pre-v1 marker` | Rename the attribute to `data-kb-headless`. |
-| `<slug>/…: contains a <base> element` | Remove it. Relative paths make it unnecessary. |
-| `<slug>/…: N root-relative URL(s), e.g. "/assets/…"` | The generator emits absolute paths: unset `site_url`/`base`/`baseurl`, or configure relative URLs (`use_directory_urls`, `trailingSlash`, `relativeurls`). |
-| `::warning:: … inline <script> block(s)` | Not a failure. Ship scripts as files if you want control over what runs. |
+| `KB-MAN-001 No manifest at kb-docs.json` | Put `kb-docs.json` at the repo root, or set the `manifest` input to where it is. |
+| `KB-MAN-001 kb-docs.json is not valid JSON` | Trailing comma or comment. JSON, not JSONC. |
+| `KB-MAN-001 kb-docs.json does not satisfy the knowledge base contract:` … | Each bullet names the field. Common: `kbVersion` as a number (must be the string `"1"`), `description` too short, `slug` with a capital, an unknown key in `pages[]`. |
+| `KB-ART-001 <slug>: entryPoint "index.html" does not exist in the built output` | The `dist` input points at the wrong directory, or the build writes somewhere else (mkdocs `site_dir`, Astro `outDir`). For a one-app manifest `dist` is the app directory itself, not its parent. |
+| `KB-ART-002 <slug>: pages entry "…" points at "…", which is not in the built output` | Path in `pages[]` does not match the generator's output layout (`foo.html` vs `foo/index.html`). Fix the path or drop `pages`. |
+| `KB-ART-003 <slug>: the built output contains no HTML at all` | Wrong `dist`, or the build failed silently. |
+| `KB-HTML-001 <slug>/…: missing data-kb-headless="true" on <html>` | The headless variant was not the one built, or the template does not emit the attribute. See `packaged.md` §A. |
+| `KB-HTML-001 <slug>/…: carries data-mp-headless, the pre-v1 marker` | Rename the attribute to `data-kb-headless`. |
+| `KB-HTML-002 <slug>/…: contains a <base> element` | Remove it. Relative paths make it unnecessary. |
+| `KB-HTML-003 <slug>/…: N root-relative URL(s), e.g. "/assets/…"` | The generator emits absolute paths: unset `site_url`/`base`/`baseurl`, or configure relative URLs (`use_directory_urls`, `trailingSlash`, `relativeurls`). |
+| `::warning title=KB-…::` | Not a failure; the publish goes ahead. Each warning's rule in `contract/RULES.md` says what breaks and how to fix it. |
 
 ## Release and upload
 
diff --git a/src/utils/theme.js b/src/utils/theme.js
new file mode 100644
index 0000000..e56bc2c
--- /dev/null
+++ b/src/utils/theme.js
@@ -0,0 +1,22 @@
+// src/utils/theme.js
+//
+// Recognises a sub-app's own dark-mode bootstrap. Dependency-free on purpose:
+// the build strips what this matches (transform.js, hoist-inline-scripts.js),
+// and the publishing actions' checker (actions/lib/check.js) reports it to the
+// repo that ships it — one definition for both, so they cannot disagree about
+// what counts as a theme bootstrap.
+
+/**
+ * True when a script body is a sub-app's own dark-mode bootstrap.
+ *
+ * The strip has to happen in two places: in transform.js for the `astro dev`
+ * path, and in scripts/hoist-inline-scripts.js for the build, which turns
+ * inline scripts into files before transform.js ever sees the document — a
+ * hoisted bootstrap would otherwise sail past the strip and re-add `dark` at
+ * runtime, which is exactly the leak the light-only rule exists to prevent.
+ */
+export function isThemeBootstrap(code) {
+  return /\blocalStorage\b/.test(code) &&
+         /\bclassList\b/.test(code) &&
+         /\bdark\b|\btheme\b/i.test(code);
+}
diff --git a/src/utils/transform.js b/src/utils/transform.js
index 6062987..d630f98 100644
--- a/src/utils/transform.js
+++ b/src/utils/transform.js
@@ -23,6 +23,7 @@
 
 import { parse, serialize } from 'parse5';
 import { layerSubAppCss } from './css-layers.js';
+import { isThemeBootstrap } from './theme.js';
 
 // ── URL rewriting ─────────────────────────────────────────────────────────────
 
@@ -140,20 +141,9 @@ const childElement = (node, tagName) =>
 
 // ── Light-only enforcement ────────────────────────────────────────────────────
 
-/**
- * True when a script body is a sub-app's own dark-mode bootstrap.
- *
- * Exported because the strip has to happen in two places: here for the `astro
- * dev` path, and in scripts/hoist-inline-scripts.js for the build, which turns
- * inline scripts into files before this module ever sees the document — a
- * hoisted bootstrap would otherwise sail past the strip and re-add `dark` at
- * runtime, which is exactly the leak the light-only rule exists to prevent.
- */
-export function isThemeBootstrap(code) {
-  return /\blocalStorage\b/.test(code) &&
-         /\bclassList\b/.test(code) &&
-         /\bdark\b|\btheme\b/i.test(code);
-}
+// isThemeBootstrap() lives in theme.js, dependency-free, so the publishing
+// actions' checker can share it. Re-exported for the build's existing imports.
+export { isThemeBootstrap };
 
 // ── Sub-app HTML transformation ───────────────────────────────────────────────
 

From 55e69dc591301af46b6a147364207e92b5cb9179 Mon Sep 17 00:00:00 2001
From: Oto Macenauer <oto.macenauer@absa.africa>
Date: Wed, 23 Sep 2026 11:12:12 +0200
Subject: [PATCH 3/3] feat(skills): audit mode for kb-docs-add

An already-onboarded repo (it has kb-docs.json, or a workflow calling
publish-docs / publish-single-page-docs) now goes down an audit path
instead of onboarding. references/audit.md:

1. check the workflow wiring the checker cannot see (pinned @v1,
   contents: write, the headless variant is what gets built, dist);
2. build what the workflow builds, or download the last release;
3. run actions/lib/check-cli.js from a scratch clone at the pinned
   major, never copied into the repo;
4. fix each finding at its source, errors first, from a table mapping
   every rule ID to its usual fix; never edit built output or patch a
   theme the team does not own;
5. read the site's own scripts for what the checker cannot see (URLs
   built from location, client-side routing) and report those;
6. re-check and report every finding with a status.

Onboarding's Verify step and packaged.md now run the checker instead of
three greps.

Eval 4 (onboarded-mkdocs) is a real mkdocs repo with planted violations:
a workflow that builds the standalone site, an inline dark-mode
bootstrap, an onclick handler, Google Fonts, !important, a page-relative
fetch, a PDF link and a location.pathname-derived base. Built with mkdocs
1.6.1 the checker reports 3 errors and 18 warnings; the fixes audit.md
prescribes bring it to no findings. Two agent runs following only the
skill: the first met 12 of 13 assertions (the miss was an over-strict
assertion, now relaxed) and its feedback shaped audit.md; the second met
all 14.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                                     |   2 +-
 skills/kb-docs-add/SKILL.md                   |  29 +++-
 skills/kb-docs-add/references/audit.md        | 132 ++++++++++++++++++
 skills/kb-docs-add/references/packaged.md     |  17 +--
 .../kb-docs-add/references/troubleshooting.md |   3 +-
 tests/fixtures/kb-docs-add/evals.json         |  25 ++++
 .../.github/workflows/publish-docs.yml        |  26 ++++
 .../kb-docs-add/onboarded-mkdocs/.gitignore   |   2 +
 .../onboarded-mkdocs/docs/files/limits.pdf    | Bin 0 -> 23 bytes
 .../onboarded-mkdocs/docs/getting-started.md  |   3 +
 .../onboarded-mkdocs/docs/index.md            |   4 +
 .../onboarded-mkdocs/docs/reference/config.md |   7 +
 .../kb-docs-add/onboarded-mkdocs/kb-docs.json |  12 ++
 .../onboarded-mkdocs/mkdocs-headless.yml      |   3 +
 .../kb-docs-add/onboarded-mkdocs/mkdocs.yml   |  17 +++
 .../onboarded-mkdocs/requirements.txt         |   1 +
 .../onboarded-mkdocs/theme/js/theme.js        |   5 +
 .../onboarded-mkdocs/theme/js/versions.js     |  22 +++
 .../onboarded-mkdocs/theme/main.html          |  37 +++++
 .../onboarded-mkdocs/theme/style.css          |   7 +
 .../onboarded-mkdocs/theme/versions.json      |   4 +
 21 files changed, 340 insertions(+), 18 deletions(-)
 create mode 100644 skills/kb-docs-add/references/audit.md
 create mode 100644 tests/fixtures/kb-docs-add/onboarded-mkdocs/.github/workflows/publish-docs.yml
 create mode 100644 tests/fixtures/kb-docs-add/onboarded-mkdocs/.gitignore
 create mode 100644 tests/fixtures/kb-docs-add/onboarded-mkdocs/docs/files/limits.pdf
 create mode 100644 tests/fixtures/kb-docs-add/onboarded-mkdocs/docs/getting-started.md
 create mode 100644 tests/fixtures/kb-docs-add/onboarded-mkdocs/docs/index.md
 create mode 100644 tests/fixtures/kb-docs-add/onboarded-mkdocs/docs/reference/config.md
 create mode 100644 tests/fixtures/kb-docs-add/onboarded-mkdocs/kb-docs.json
 create mode 100644 tests/fixtures/kb-docs-add/onboarded-mkdocs/mkdocs-headless.yml
 create mode 100644 tests/fixtures/kb-docs-add/onboarded-mkdocs/mkdocs.yml
 create mode 100644 tests/fixtures/kb-docs-add/onboarded-mkdocs/requirements.txt
 create mode 100644 tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/js/theme.js
 create mode 100644 tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/js/versions.js
 create mode 100644 tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/main.html
 create mode 100644 tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/style.css
 create mode 100644 tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/versions.json

diff --git a/CLAUDE.md b/CLAUDE.md
index fc1bc3f..e408596 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -85,7 +85,7 @@ Orchestrator: `scripts/build-vite.js`. Flags: `--local`, `--headless`.
 - `scripts/artifacts.js` — Safe tarball extraction + tree copy, shared by both fetch paths. Validates archive members (no traversal, no absolute paths, no symlinks) before anything is written, and replaces the old `cp -r`/`tar` shell-outs so the build runs on Windows
 - `scripts/hoist-inline-scripts.js` — Moves inline `<script>` bodies in sub-app HTML into files before the Astro build, so the deployment can serve `script-src 'self'`. Needed because bundles published before the action stopped emitting an inline mermaid bootstrap still contain one. A sub-app's dark-mode bootstrap is deleted here rather than hoisted — light only, and hoisting would put it beyond the reach of `transform.js`
 - `actions/publish-single-page-docs/` — Reusable GitHub Action that turns a repo's markdown into a single-page bundle
-- `skills/kb-docs-add/` — Agent skill (Claude Code, GitHub Copilot, `npx skills add`) that walks an agent through onboarding a docs repo: classify, write only the contract-required files, verify, troubleshoot. Guidance only — no scripts; `examples/` are the contract's own code blocks and `tests/skill.spec.js` fails if they drift. Eval fixtures live in `tests/fixtures/kb-docs-add/`
+- `skills/kb-docs-add/` — Agent skill (Claude Code, GitHub Copilot, `npx skills add`) that walks an agent through onboarding a docs repo (classify, write only the contract-required files, verify, troubleshoot) and through auditing one already onboarded (`references/audit.md`: run `actions/lib/check-cli.js` from a scratch clone, fix findings by rule ID at the source, report what the checker cannot see). Guidance only — no scripts; `examples/` are the contract's own code blocks and `tests/skill.spec.js` fails if they drift. Eval fixtures live in `tests/fixtures/kb-docs-add/`
 
 ### Onboarding Types
 
diff --git a/skills/kb-docs-add/SKILL.md b/skills/kb-docs-add/SKILL.md
index 1d2476e..5a0594b 100644
--- a/skills/kb-docs-add/SKILL.md
+++ b/skills/kb-docs-add/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: kb-docs-add
-description: Onboard a repository's documentation into the AbsaOSS knowledge base. Classifies the repo (markdown files → single-page, a static docs site → packaged, hosted elsewhere → iframe stopgap), writes only the files the contract requires (one workflow calling publish-single-page-docs, or kb-docs.json + a headless build flag + a publish-docs workflow), and explains how to verify the release carries kb-docs.tar.gz. Use whenever someone wants to publish docs to the knowledge base, add a repo or service to the knowledge base, write kb-docs.json, produce kb-docs.tar.gz, make a docs site headless for the knowledge base, or fix a failing publish-docs / publish-single-page-docs workflow — even when they only say "get our docs into the KB" or "our docs don't show up in the knowledge base".
+description: Onboard a repository's documentation into the AbsaOSS knowledge base. Classifies the repo (markdown files → single-page, a static docs site → packaged, hosted elsewhere → iframe stopgap), writes only the files the contract requires (one workflow calling publish-single-page-docs, or kb-docs.json + a headless build flag + a publish-docs workflow), and explains how to verify the release carries kb-docs.tar.gz. Use whenever someone wants to publish docs to the knowledge base, add a repo or service to the knowledge base, write kb-docs.json, produce kb-docs.tar.gz, make a docs site headless for the knowledge base, or fix a failing publish-docs / publish-single-page-docs workflow — even when they only say "get our docs into the KB" or "our docs don't show up in the knowledge base". Also audits an onboarded repo: runs the contract checker, fixes findings by rule ID (KB-HTML-003…) at the source — for publish warnings or docs that break once embedded.
 license: Apache-2.0
 metadata:
   author: AbsaOSS
@@ -23,6 +23,10 @@ a guided path through it, not a replacement.
 
 Look at what the repo actually contains before writing anything.
 
+**Already onboarded?** A `kb-docs.json`, or a workflow calling `publish-docs` /
+`publish-single-page-docs`, means the job is an audit, not an onboarding: go to §6,
+unless the user asks to publish something new from the repo.
+
 | You find | Type | What you will write |
 |---|---|---|
 | Markdown files (README, `docs/*.md`, runbooks) and **no** docs-site generator | **single-page** | one workflow file |
@@ -83,9 +87,9 @@ its first run boring:
 1. Every `md:` path (single-page) or `pages[].path` (packaged) exists in the checkout.
 2. Every `slug` matches `^[a-z0-9]+(-[a-z0-9]+)*$`, 2–32 characters, and is
    service-prefixed. Every `description` is 10–280 characters.
-3. Packaged only: run the headless build and confirm, on the output,
-   `data-kb-headless="true"` on `<html>`, no `<base>`, no `href="/`/`src="/`. These are
-   the checks the action fails on; the same grep now saves a CI round trip.
+3. Packaged only: run the headless build, then the action's own checker on the output
+   (`references/audit.md` §3 has the three commands). No errors means the publish will
+   not fail on the HTML. Fix warnings the same way (§4 there), or name them in the report.
 4. The workflow has `permissions: contents: write` — the upload needs it and the error
    without it (`Resource not accessible by integration`) does not say so.
 
@@ -102,9 +106,22 @@ Then tell the user the two things only they can do:
 
 Read `references/troubleshooting.md`: it maps every message the actions and the knowledge
 base build emit to its cause and fix. Do not guess from the symptom — the messages are
-specific on purpose.
+specific on purpose. A message that starts with a rule ID (`KB-…`) is a checker finding:
+`references/audit.md` §4 maps each ID to its fix.
+
+## 6. Audit an onboarded repo
+
+Read `references/audit.md`. In short: check the workflow wiring, build the headless output
+(or download the last release's `kb-docs.tar.gz`), run the checker from a scratch
+clone of the knowledge base, then fix each finding **at its source**, errors first:
+config, the team's own templates, CSS, scripts or markdown. Never fix the built output,
+and never patch a theme the team does not own. Also read the site's own scripts for
+what the checker cannot see (URLs built from `location`, client-side routing), and report
+those. Re-run until no errors remain.
 
 ## Report back
 
 End with: the files written (full paths), the type you chose and why, the manual steps
-above, and any contract requirement you could not satisfy from inside this repo.
+above, and any contract requirement you could not satisfy from inside this repo. After an
+audit, report instead in the shape `references/audit.md` §6 gives: every finding with its
+status.
diff --git a/skills/kb-docs-add/references/audit.md b/skills/kb-docs-add/references/audit.md
new file mode 100644
index 0000000..d948c87
--- /dev/null
+++ b/skills/kb-docs-add/references/audit.md
@@ -0,0 +1,132 @@
+# Audit path
+
+The repo is already onboarded: it has a `kb-docs.json` or a workflow calling
+`publish-docs` / `publish-single-page-docs`. The user wants it checked against the
+contract, wants publish warnings gone, or reports docs that look or behave wrong inside
+the knowledge base. Normative text: `contract/RULES.md` in `AbsaOSS/knowledge-base`. It
+lists every rule by ID (`KB-HTML-003` …) with its reason and fix.
+
+You do not judge compliance yourself. The checker does that, and you fix what it reports.
+Every finding carries a rule ID, and the table below maps each ID to a change.
+
+## 1. Check the wiring first
+
+These are cheap and the checker cannot see them:
+
+- The workflow pins `AbsaOSS/knowledge-base/actions/<action>@v1` (a major tag, never
+  `@master` or a SHA nobody will bump), triggers on `release: published`, and has
+  `permissions: contents: write`.
+- `publish-docs`: the build step runs the **headless** variant, and `dist` is the directory
+  that variant writes (mkdocs `site_dir`, Astro `outDir` …).
+- `publish-single-page-docs`: every `md:` path exists, and the slugs are service-prefixed.
+  The action renders the HTML itself, so there is no built output of yours to check.
+  Stop after this step for a single-page repo.
+- No pre-v1 names anywhere: `dist.tar.gz`, `marketplace.json`, `bundle.json`,
+  `data-mp-headless`.
+
+## 2. Get the built output
+
+Check what the knowledge base will actually receive. In order of preference:
+
+1. **Run the build step the workflow runs**, and check its output directory.
+2. **Download the published artifact** when the build cannot run here (missing toolchain,
+   private dependencies): `gh release download --pattern kb-docs.tar.gz`, then extract it.
+   This audits the last release, not the working tree, so say so in the report.
+
+If the workflow does not build the headless variant (step 1 found that), check its output
+anyway: that is what gets published, and the findings, usually `KB-HTML-001` on every
+page, show the user the cost. Then fix the workflow and audit the headless build. The
+wiring fix is the top finding in the report.
+
+An `error` finding fails the publish, and a `warning` does not. Trust the checker over the
+user's description of the symptom. If the user says "warnings"
+and the checker reports errors, say so. Their memory, or the last run they looked at, may
+be out of date.
+
+## 3. Run the checker
+
+Use the knowledge base at the major version the workflow pins, so the rules match what
+the publish runs:
+
+```bash
+git clone --depth 1 --branch v1 https://github.com/AbsaOSS/knowledge-base.git "$TMP/kb"
+npm ci --omit=dev --prefix "$TMP/kb/actions"
+node "$TMP/kb/actions/lib/check-cli.js" --manifest kb-docs.json --dist <output-dir> --json
+```
+
+`$TMP` is any scratch directory outside the repo. Never copy the checker into the repo.
+If that tag has no `actions/lib/check-cli.js`, it predates the checker: clone without
+`--branch` and tell the user that some rules are newer than their pinned action.
+`--dist` is the build's output directory, the same value as the workflow's `dist` input.
+For an extracted artifact it is the extraction root when the manifest lists several apps,
+and the one app directory when it lists one.
+
+Each finding is `{ id, severity, where, message }`. `where` is `<slug>/<file>`, relative
+to the app's output directory.
+
+## 4. Fix at the source, errors first
+
+A finding names a file in the **output**. The fix goes in whatever produced it: the
+generator config, the theme templates the team owns, their stylesheet or script, or
+the markdown. Never edit built output: the next build undoes it.
+
+| Rule | Usual cause → fix |
+|---|---|
+| `KB-MAN-001` | Schema problem. Each bullet names the field; see `troubleshooting.md`. |
+| `KB-ART-001…003` | `dist` points at the wrong directory, or a `pages[].path` does not match the output layout (`foo.html` vs `foo/index.html`). |
+| `KB-ART-004/005` | Uncompressed images, source maps, a vendored toolchain in the output. Exclude them from the build. |
+| `KB-HTML-001` | The headless variant is not the one built, or the template misses the attribute (`packaged.md` §A). |
+| `KB-HTML-002` | A template emits `<base>`. Remove it. |
+| `KB-HTML-003` | Generator emits absolute paths: unset `site_url`/`base`/`baseurl`, enable relative URLs (see `troubleshooting.md`). |
+| `KB-HTML-004` | Move the script body into a file under the site's assets and reference it with `<script src>`. If the inline script is the dark-mode bootstrap, the `KB-THEME-001` fix applies instead: leave it out of the headless build. |
+| `KB-HTML-005/006` | `onclick=` / `href="javascript:…"`, often a menu or copy button. Give the element an id or class, and attach the listener from a script file. |
+| `KB-HTML-007` | The site header survives in the headless variant. Hide it under the headless condition (`packaged.md` §A). |
+| `KB-HTML-008` | A link to a PDF, ZIP, image … inside the app. Link to a page that embeds or describes it, or to the file on another origin (a release asset, a storage URL). You rarely know that URL: ask, or leave the finding with a note saying what the team must choose. |
+| `KB-CSS-001` | `!important` in the team's own CSS: drop it and raise specificity. In a third-party theme's CSS: report it, do not patch. |
+| `KB-THEME-001` | Dark-mode toggle or bootstrap still in the headless variant. Remove it under the headless condition. |
+| `KB-CSP-001` | Web fonts or scripts from a CDN. Vendor the files into the site's assets and reference them relatively. Themes often have a switch for this (mkdocs-material: `theme.font: false`). A web font may also simply be left out of the headless build, so the page falls back to the rest of its `font-family` stack. Vendor it when the font matters to how the docs read and you can fetch it; otherwise leave it out. Say which you chose. A script cannot be left out if the page needs it: vendor it. |
+| `KB-JS-001` | `fetch('data.json')` resolves against the host page. Use `new URL('data.json', import.meta.url)` in a module. In a classic script, read `document.currentScript.src` at top level: it is `null` inside callbacks. |
+
+When a fix would mean re-implementing or forking a theme the team does not own, do not
+make it. Record the rule, the file and why it stays. The same boundary as onboarding
+applies: no new generator, no helper scripts, no wrapper actions, no `Makefile` targets.
+New files that are part of the site are fine: the script a listener moves into, or a
+vendored font. The ban is on tooling around the build, not on the site's own assets.
+
+## 5. What the checker cannot see
+
+Read the site's own scripts (not vendored libraries) for these. They are judgment calls,
+so **report them; change them only when the fix is obvious and local**. Obvious and local
+means one file, the same technique as a row above, and no change in what the page does.
+One example: a base path computed from `location.pathname` becomes one resolved from the
+script's URL. Anything that changes behaviour is the team's decision, so report it. Examples:
+hiding a feature in the headless build, dropping a navigation, or links to content the
+artifact does not contain (older doc versions, other sites).
+
+- URLs assembled at runtime from `location.pathname`, `location.href`, `document.baseURI`
+  or string concatenation. Embedded, the page URL is the **host's**, and a host router
+  may strip the trailing slash. Resolving against the script's own URL is the fix
+  (row `KB-JS-001` above).
+- The site's own client-side routing: `history.pushState`, a SPA router, intercepted link
+  clicks. The knowledge base does its own navigation between pages.
+- `navigator.serviceWorker.register`, and anything reading or writing `localStorage`
+  beyond UI state.
+
+## 6. Re-check, then report
+
+Rebuild and re-run the checker until it reports no errors. Warnings you left must each
+have a reason in the report. If step 2 used the downloaded artifact, you cannot re-check.
+Say that the next release's publish run is the verification.
+
+Report:
+
+- The checker's counts before and after (`N error(s), M warning(s)`). The before counts
+  usually explain the user's symptom.
+- A table of findings: rule, file, status (**fixed** with the change / **left** with the
+  reason / **reported** for step 5 items). One row per rule and cause, with a count
+  (`KB-HTML-005 ×3, every page`), not one row per page.
+- The files changed, with full paths.
+- The checker's final summary line, and whether it ran on a fresh build or the last
+  release.
+- The one manual step: publish a release so the fixed output reaches the knowledge base.
+  The registry entry does not change.
diff --git a/skills/kb-docs-add/references/packaged.md b/skills/kb-docs-add/references/packaged.md
index 8369e3d..44d7294 100644
--- a/skills/kb-docs-add/references/packaged.md
+++ b/skills/kb-docs-add/references/packaged.md
@@ -79,14 +79,8 @@ variant.
   from the table above, and offer the single-page path for the markdown sources instead.
   A half-headless site in the knowledge base is worse than markdown that renders cleanly.
 
-After the change, build the variant and check the output yourself — the same greps the
-action runs:
-
-```bash
-grep -L 'data-kb-headless="true"' $(find dist -name '*.html')   # must print nothing
-grep -rlE '(href|src|action|poster)="/' dist                     # must print nothing
-grep -rl '<base' dist                                            # must print nothing
-```
+After the change, build the variant and run the action's own checker on the output
+(`audit.md` §3). No errors means the publish will not fail on the HTML.
 
 ## B. `kb-docs.json` in the repo root
 
@@ -182,10 +176,13 @@ the user's situation calls for it; see `contract/DEPLOYMENT.md`.
 
 1. `kb-docs.json` exists, is valid JSON, satisfies `contract/kb-docs.schema.json`.
 2. For every app: `dist/<entryPoint>` exists; every `pages[].path` exists; the output has HTML.
-3. Every HTML file: `data-kb-headless="true"`, no `<base>`, no root-relative URLs.
+3. Every HTML file: `data-kb-headless="true"`, no `<base>`, no root-relative URLs. These
+   fail the publish. The HTML, CSS and scripts are also checked for rules that only warn
+   (inline scripts and handlers, `!important`, dark mode, CDN assets …).
 4. Pack, upload to the release (replacing an existing `kb-docs.tar.gz`), optional notify.
 
-All problems in a step are reported together, naming the file and the fix. If the first
+Every finding starts with its rule ID from `contract/RULES.md`, and all of them are
+reported together. The same checker runs before a release (`audit.md` §3). If the first
 run fails, the message is in `troubleshooting.md`.
 
 ## Then
diff --git a/skills/kb-docs-add/references/troubleshooting.md b/skills/kb-docs-add/references/troubleshooting.md
index 69a8c71..9120e13 100644
--- a/skills/kb-docs-add/references/troubleshooting.md
+++ b/skills/kb-docs-add/references/troubleshooting.md
@@ -36,7 +36,8 @@ All reported at once, each naming `docs[i]` and the fix.
 ## `publish-docs` manifest and HTML errors
 
 Every finding starts with a rule ID; `contract/RULES.md` explains each one, including
-the warnings not listed here. The same checks run before a release with
+the warnings not listed here, and `audit.md` §4 maps each ID to its usual fix. The same
+checks run before a release with
 `node <knowledge-base>/actions/lib/check-cli.js --manifest kb-docs.json --dist <dir>`.
 
 | Message | Fix |
diff --git a/tests/fixtures/kb-docs-add/evals.json b/tests/fixtures/kb-docs-add/evals.json
index e38a6d3..bbc2464 100644
--- a/tests/fixtures/kb-docs-add/evals.json
+++ b/tests/fixtures/kb-docs-add/evals.json
@@ -54,6 +54,31 @@
         "The reply says the external site must allow embedding (frame-ancestors / X-Frame-Options)",
         "The reply does not invent a kb-docs.json or a workflow for this repo"
       ]
+    },
+    {
+      "id": 4,
+      "name": "onboarded-mkdocs-audit",
+      "prompt": "card-vault already publishes to the knowledge base, but the publish run is full of warnings and the version picker is broken when the docs are embedded. Can you check it against the knowledge base rules and fix what you can?",
+      "files": [
+        "onboarded-mkdocs"
+      ],
+      "expected_output": "An audit, not an onboarding. The agent notices the workflow builds the standalone config (mkdocs build) instead of the headless variant, and switches it to mkdocs build -f mkdocs-headless.yml. It runs the knowledge base checker from a scratch clone against the headless output. It fixes each finding in the team's theme and docs: the inline dark-mode bootstrap and the toggle go under the headless condition (or move to a file), the onclick copy button gets a listener in a script file, the Google Fonts link is removed or vendored, !important goes from theme/style.css, versions.js resolves versions.json against its own script URL, and the PDF link no longer points into the app. It re-runs the checker to no findings. It reports the root computed from location.pathname in versions.js as a judgment item. The final report is a table of findings with a status each, and says a new release is the only manual step.",
+      "assertions": [
+        "kb-docs.json is unchanged and no new kb-docs.json, manifest or registry entry was written",
+        ".github/workflows/publish-docs.yml still uses AbsaOSS/knowledge-base/actions/publish-docs@v1 with contents: write, and its build step now builds mkdocs-headless.yml",
+        "The agent ran actions/lib/check-cli.js from a knowledge base checkout outside the fixture; no copy of the checker, no scripts/ directory and no Makefile exist in the fixture",
+        "No built output (dist/, site/) was added to the fixture, and no generated HTML was edited",
+        "theme/main.html no longer emits an inline <script> or the theme toggle when config.extra.headless is set, and still does when it is not",
+        "The copy button has no onclick attribute; its listener lives in a .js file under theme/",
+        "The fonts.googleapis.com stylesheet link is gone from the headless output (removed or the font vendored under theme/)",
+        "theme/style.css contains no !important",
+        "theme/js/versions.js no longer calls fetch('versions.json') with a page-relative URL; it resolves against document.currentScript.src or import.meta.url captured at top level",
+        "The KB-HTML-008 link to docs/files/limits.pdf is either replaced (a page or an off-app URL) or explicitly left in the report with what the team must decide; it is not silently ignored",
+        "The report names the location.pathname-based root in versions.js as something the checker cannot see",
+        "The report lists findings with rule IDs (KB-HTML-001, KB-HTML-004, KB-HTML-005, KB-THEME-001, KB-CSP-001, KB-CSS-001, KB-JS-001, KB-HTML-008) and a status each, and a final checker run with no errors",
+        "The report leads with the wiring finding: the workflow built the standalone site, and the checker reports errors on that output (so the publish would fail), not merely warnings",
+        "The report says a new GitHub Release is needed and that the apps.json registry entry does not change"
+      ]
     }
   ]
 }
diff --git a/tests/fixtures/kb-docs-add/onboarded-mkdocs/.github/workflows/publish-docs.yml b/tests/fixtures/kb-docs-add/onboarded-mkdocs/.github/workflows/publish-docs.yml
new file mode 100644
index 0000000..521c801
--- /dev/null
+++ b/tests/fixtures/kb-docs-add/onboarded-mkdocs/.github/workflows/publish-docs.yml
@@ -0,0 +1,26 @@
+name: Publish docs
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - run: pip install -r requirements.txt && mkdocs build
+
+      - uses: AbsaOSS/knowledge-base/actions/publish-docs@v1
+        with:
+          manifest: kb-docs.json
+          dist: dist
diff --git a/tests/fixtures/kb-docs-add/onboarded-mkdocs/.gitignore b/tests/fixtures/kb-docs-add/onboarded-mkdocs/.gitignore
new file mode 100644
index 0000000..c560d76
--- /dev/null
+++ b/tests/fixtures/kb-docs-add/onboarded-mkdocs/.gitignore
@@ -0,0 +1,2 @@
+dist/
+site/
diff --git a/tests/fixtures/kb-docs-add/onboarded-mkdocs/docs/files/limits.pdf b/tests/fixtures/kb-docs-add/onboarded-mkdocs/docs/files/limits.pdf
new file mode 100644
index 0000000000000000000000000000000000000000..8c4a833175f22d04ee01c8ece9e0664939fa0e78
GIT binary patch
literal 23
ecmY!laB<T$)HC5yRVc_wOis<n&q+xw;sO9hH3pmj

literal 0
HcmV?d00001

diff --git a/tests/fixtures/kb-docs-add/onboarded-mkdocs/docs/getting-started.md b/tests/fixtures/kb-docs-add/onboarded-mkdocs/docs/getting-started.md
new file mode 100644
index 0000000..cb3653d
--- /dev/null
+++ b/tests/fixtures/kb-docs-add/onboarded-mkdocs/docs/getting-started.md
@@ -0,0 +1,3 @@
+# Getting started
+
+Request a client certificate, then call `POST /tokens` with the card number.
diff --git a/tests/fixtures/kb-docs-add/onboarded-mkdocs/docs/index.md b/tests/fixtures/kb-docs-add/onboarded-mkdocs/docs/index.md
new file mode 100644
index 0000000..6502273
--- /dev/null
+++ b/tests/fixtures/kb-docs-add/onboarded-mkdocs/docs/index.md
@@ -0,0 +1,4 @@
+# Card Vault
+
+Card Vault swaps card numbers for tokens so that no other service stores a PAN.
+This guide covers integrating a new caller.
diff --git a/tests/fixtures/kb-docs-add/onboarded-mkdocs/docs/reference/config.md b/tests/fixtures/kb-docs-add/onboarded-mkdocs/docs/reference/config.md
new file mode 100644
index 0000000..ec2d315
--- /dev/null
+++ b/tests/fixtures/kb-docs-add/onboarded-mkdocs/docs/reference/config.md
@@ -0,0 +1,7 @@
+# Configuration
+
+| Key | Default | Meaning |
+|---|---|---|
+| `timeout_ms` | 3000 | upstream timeout |
+
+Rate limits per caller are listed in the [limits sheet](../files/limits.pdf).
diff --git a/tests/fixtures/kb-docs-add/onboarded-mkdocs/kb-docs.json b/tests/fixtures/kb-docs-add/onboarded-mkdocs/kb-docs.json
new file mode 100644
index 0000000..00c75cb
--- /dev/null
+++ b/tests/fixtures/kb-docs-add/onboarded-mkdocs/kb-docs.json
@@ -0,0 +1,12 @@
+{
+  "kbVersion": "1",
+  "apps": [
+    {
+      "slug": "card-vault",
+      "name": "Card Vault",
+      "description": "Tokenisation service for card numbers: integration guide and configuration reference.",
+      "icon": "book-open",
+      "tags": ["payments", "security"]
+    }
+  ]
+}
diff --git a/tests/fixtures/kb-docs-add/onboarded-mkdocs/mkdocs-headless.yml b/tests/fixtures/kb-docs-add/onboarded-mkdocs/mkdocs-headless.yml
new file mode 100644
index 0000000..8c11e8b
--- /dev/null
+++ b/tests/fixtures/kb-docs-add/onboarded-mkdocs/mkdocs-headless.yml
@@ -0,0 +1,3 @@
+INHERIT: mkdocs.yml
+extra:
+  headless: true
diff --git a/tests/fixtures/kb-docs-add/onboarded-mkdocs/mkdocs.yml b/tests/fixtures/kb-docs-add/onboarded-mkdocs/mkdocs.yml
new file mode 100644
index 0000000..1b01f95
--- /dev/null
+++ b/tests/fixtures/kb-docs-add/onboarded-mkdocs/mkdocs.yml
@@ -0,0 +1,17 @@
+site_name: Card Vault
+site_description: Tokenisation service for card numbers.
+docs_dir: docs
+site_dir: dist
+
+theme:
+  name: null
+  custom_dir: theme
+
+nav:
+  - Overview: index.md
+  - Getting started: getting-started.md
+  - Reference:
+      - Configuration: reference/config.md
+
+plugins:
+  - search
diff --git a/tests/fixtures/kb-docs-add/onboarded-mkdocs/requirements.txt b/tests/fixtures/kb-docs-add/onboarded-mkdocs/requirements.txt
new file mode 100644
index 0000000..f2caded
--- /dev/null
+++ b/tests/fixtures/kb-docs-add/onboarded-mkdocs/requirements.txt
@@ -0,0 +1 @@
+mkdocs==1.6.1
diff --git a/tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/js/theme.js b/tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/js/theme.js
new file mode 100644
index 0000000..82c009f
--- /dev/null
+++ b/tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/js/theme.js
@@ -0,0 +1,5 @@
+// Dark-mode toggle for the standalone site.
+document.getElementById('theme-toggle').addEventListener('click', function () {
+  var dark = document.documentElement.classList.toggle('dark');
+  localStorage.setItem('theme', dark ? 'dark' : 'light');
+});
diff --git a/tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/js/versions.js b/tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/js/versions.js
new file mode 100644
index 0000000..d1f00c6
--- /dev/null
+++ b/tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/js/versions.js
@@ -0,0 +1,22 @@
+// Fills the version picker from versions.json, published next to the docs.
+(function () {
+  var picker = document.getElementById('version-picker');
+  if (!picker) return;
+
+  fetch('versions.json')
+    .then(function (r) { return r.json(); })
+    .then(function (versions) {
+      // The docs root is the first path segment of the current page.
+      var root = '/' + location.pathname.split('/')[1] + '/';
+      versions.forEach(function (v) {
+        var option = document.createElement('option');
+        option.value = root + v.path;
+        option.textContent = v.title;
+        picker.appendChild(option);
+      });
+    });
+
+  picker.addEventListener('change', function () {
+    location.href = picker.value;
+  });
+})();
diff --git a/tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/main.html b/tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/main.html
new file mode 100644
index 0000000..8d90607
--- /dev/null
+++ b/tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/main.html
@@ -0,0 +1,37 @@
+<!DOCTYPE html>
+<html lang="en"{% if config.extra.headless %} data-kb-headless="true"{% endif %}>
+<head>
+  <meta charset="utf-8">
+  <title>{{ page.title }} - {{ config.site_name }}</title>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Source+Sans+3:wght@400;600&display=swap">
+  <link rel="stylesheet" href="{{ 'style.css' | url }}">
+  <script>
+    if (localStorage.getItem('theme') === 'dark') document.documentElement.classList.add('dark');
+  </script>
+</head>
+<body>
+  {% if not config.extra.headless %}
+  <header class="topnav fixed top-0 inset-x-0">
+    <a class="brand" href="{{ nav.homepage.url | url }}">{{ config.site_name }}</a>
+    <nav>
+      <a href="https://developer.example.com">Developer portal</a>
+    </nav>
+  </header>
+  {% endif %}
+  <nav id="sidebar">
+    <ul>
+    {% for nav_item in nav %}
+      <li><a href="{{ nav_item.url | url }}">{{ nav_item.title }}</a></li>
+    {% endfor %}
+    </ul>
+    <select id="version-picker" aria-label="Version"></select>
+  </nav>
+  <main id="content">
+    <button class="copy-page" onclick="navigator.clipboard.writeText(document.getElementById('content').innerText)">Copy page</button>
+    <button id="theme-toggle" aria-label="Toggle theme">◐</button>
+    {{ page.content }}
+  </main>
+  <script src="{{ 'js/versions.js' | url }}"></script>
+  <script src="{{ 'js/theme.js' | url }}"></script>
+</body>
+</html>
diff --git a/tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/style.css b/tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/style.css
new file mode 100644
index 0000000..83785b8
--- /dev/null
+++ b/tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/style.css
@@ -0,0 +1,7 @@
+:root { --bg-page: #f8f9fb; --text-body: #374151; }
+body { font-family: 'Source Sans 3', sans-serif; }
+.topnav { position: fixed; top: 0; height: 56px; }
+#sidebar { position: sticky; top: 0; }
+#content h1 { color: #1b0e12 !important; }
+#content a { text-decoration: underline !important; }
+.dark body { background: #111827; color: #e5e7eb; }
diff --git a/tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/versions.json b/tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/versions.json
new file mode 100644
index 0000000..28054e7
--- /dev/null
+++ b/tests/fixtures/kb-docs-add/onboarded-mkdocs/theme/versions.json
@@ -0,0 +1,4 @@
+[
+  { "title": "latest", "path": "" },
+  { "title": "2.x", "path": "2.x/" }
+]