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/docker-compose.yml

@@ -0,0 +1,73 @@
+# cuckoo-escapement docs site — two profiles.
+#
+# Default (no --profile flag):
+#   prod-style — Caddy serves the built dist/. Use for production-like
+#   deploys (the public site at cuckoo.warehack.ing runs this).
+#
+# --profile dev:
+#   Astro dev server with HMR. Volume mounts on src/ so edits hot-reload.
+#   The Vite HMR WebSocket is configured in astro.config.mjs to work
+#   behind the caddy-docker-proxy TLS-terminating front-end — see the
+#   `caddy.reverse_proxy.*` labels below for the WebSocket-friendly
+#   timeout configuration.
+#
+# Both services attach to the external `caddy` network and expose
+# themselves to caddy-docker-proxy via labels. Edit DOMAIN in .env to
+# switch between cuckoo.warehack.ing (prod) and cuckoo.l.warehack.ing
+# (local-dev tier).
+
+services:
+  docs:
+    profiles: ["prod", ""]
+    build:
+      context: .
+      target: prod
+    image: cuckoo-escapement-docs:prod
+    container_name: cuckoo-escapement-docs
+    restart: unless-stopped
+    networks:
+      - caddy
+    labels:
+      caddy: ${DOMAIN:-cuckoo.warehack.ing}
+      caddy.reverse_proxy: "{{upstreams 80}}"
+      # encode + gzip already in the container; let caddy pass through.
+
+  docs-dev:
+    profiles: ["dev"]
+    build:
+      context: .
+      target: dev
+    image: cuckoo-escapement-docs:dev
+    container_name: cuckoo-escapement-docs-dev
+    restart: unless-stopped
+    environment:
+      - DOMAIN=${DOMAIN:-cuckoo.l.warehack.ing}
+      - ASTRO_TELEMETRY_DISABLED=1
+    volumes:
+      # Hot-reload bind mounts. node_modules stays inside the container
+      # so host platform mismatches don't break native deps.
+      - ./astro.config.mjs:/app/astro.config.mjs:ro
+      - ./tsconfig.json:/app/tsconfig.json:ro
+      - ./src:/app/src
+      - ./public:/app/public
+    networks:
+      - caddy
+    labels:
+      caddy: ${DOMAIN:-cuckoo.l.warehack.ing}
+      caddy.reverse_proxy: "{{upstreams 4321}}"
+      # Vite HMR over WebSocket. Caddy's defaults close "idle" WS
+      # connections after ~10-15s; HMR doesn't send app-level pings, so
+      # we need explicit long-lived timeouts. Required for Caddy 2.10+
+      # (HTTP/2 WS fix). See ~/.claude/references/web-frontend.md.
+      caddy.reverse_proxy.flush_interval: "-1"
+      caddy.reverse_proxy.transport: "http"
+      caddy.reverse_proxy.transport.read_timeout: "0"
+      caddy.reverse_proxy.transport.write_timeout: "0"
+      caddy.reverse_proxy.transport.keepalive: "5m"
+      caddy.reverse_proxy.transport.keepalive_idle_conns: "10"
+      caddy.reverse_proxy.stream_timeout: "24h"
+      caddy.reverse_proxy.stream_close_delay: "5s"
+
+networks:
+  caddy:
+    external: true