The Cuckoo Escapement: field report, kernel patch, dashboard

What the Raspberry Pi time-server guides get wrong on a Pi 4, with the
measurements. The headline artifact is a four-line pps-gpio patch: PREEMPT_RT
force-threads IRQ handlers, and pps-gpio takes its timestamp inside its handler,
so the realtime kernel puts a scheduler between the electrical edge and the
clock. IRQF_NO_THREAD takes RMS offset from 2468 ns to 199 ns.

- kernel/     the patch
- dashboard/  live status page (position hidden by default)
- docs-site/  the write-up (Astro/Starlight, brass, no tutorial section)

docs-site/astro.config.mjs

@@ -0,0 +1,105 @@
+// The Cuckoo Escapement — Starlight, diátaxis-shaped.
+//
+// This site is a FIELD REPORT, not a tutorial. The build guides already exist
+// (geerlingguy/time-pi, josh-blake/pixie) and they're good. What doesn't exist
+// is a record of everything they get wrong on a Pi 4, with numbers. So the IA is
+// deliberately inverted from the usual docs site: heavy on Explanation and
+// Reference, and there is no Tutorial section at all.
+//
+// Telemetry + devToolbar off per project convention. The HMR block is required
+// when the dev server runs behind Caddy (TLS-terminating proxy) — without an
+// explicit host/protocol/clientPort, Vite's WebSocket drops every ~10s.
+//
+// Site URL comes from DOMAIN so one image serves both cuckoo.warehack.ing (prod)
+// and cuckoo.l.warehack.ing (local dev).
+
+import mdx from "@astrojs/mdx";
+import sitemap from "@astrojs/sitemap";
+import starlight from "@astrojs/starlight";
+import { defineConfig } from "astro/config";
+import starlightLinksValidator from "starlight-links-validator";
+
+const domain = process.env.DOMAIN ?? "cuckoo.warehack.ing";
+
+export default defineConfig({
+  site: `https://${domain}`,
+  telemetry: false,
+  devToolbar: { enabled: false },
+
+  vite: {
+    server: {
+      host: "0.0.0.0",
+      hmr: { host: domain, protocol: "wss", clientPort: 443 },
+    },
+  },
+
+  integrations: [
+    starlight({
+      title: "The Cuckoo Escapement",
+      description:
+        "What the Raspberry Pi time-server guides get wrong, and the numbers to prove it. " +
+        "GPS Stratum 1 on a Pi 4: PREEMPT_RT makes PPS jitter worse, the PPS interrupt " +
+        "cannot be pinned, PTP is impossible, and your dashboard is taxing your clock.",
+
+      // The mark IS the word "cuckoo" — a rebus. replacesTitle stops Starlight
+      // rendering the title text beside it (which would read "…escapement The
+      // Cuckoo Escapement"). The SVG's aria-label carries the full name.
+      logo: { src: "./src/assets/logo.svg", replacesTitle: true },
+      favicon: "/favicon.svg",
+      customCss: ["./src/styles/brass.css"],
+
+      social: [
+        {
+          icon: "seti:git",
+          label: "Source",
+          href: "https://git.supported.systems/warehack.ing/cuckoo-escapement",
+        },
+      ],
+
+      // Diátaxis, but weighted for a field report. Explanation leads, because the
+      // whole point is WHY the received wisdom is wrong. There is no Tutorial —
+      // that would be the one thing the world does not need another of.
+      // NB: Starlight >=0.39 removed the inline {label, autogenerate} shorthand;
+      // it must be nested as {label, items: [{autogenerate}]}.
+      sidebar: [
+        {
+          label: "Start here",
+          items: [
+            { label: "What this is (and isn't)", slug: "index" },
+            { label: "The findings, in brief", slug: "findings" },
+          ],
+        },
+        {
+          label: "Explanation",
+          items: [{ autogenerate: { directory: "explanation" } }],
+        },
+        {
+          label: "Reference",
+          items: [{ autogenerate: { directory: "reference" } }],
+        },
+        {
+          label: "How-to",
+          items: [{ autogenerate: { directory: "how-to" } }],
+        },
+      ],
+
+      components: {
+        // Appends the "A Supported Systems Joint" badge under Starlight's default
+        // footer, without rewriting the component.
+        Footer: "./src/components/Footer.astro",
+      },
+
+      plugins: [
+        starlightLinksValidator({
+          // Broken internal links fail the build rather than shipping silently.
+          errorOnRelativeLinks: false,
+        }),
+      ],
+
+      pagination: true,
+      lastUpdated: true,
+    }),
+    mdx(),
+    sitemap(),
+  ],
+});