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/Makefile

@@ -0,0 +1,59 @@
+# cuckoo-escapement docs — make targets follow the warehacking cookie-cutter.
+#
+# `make prod` builds the static site + brings up Caddy serving it.
+# `make dev`  starts the Astro dev server with HMR behind Caddy.
+# `make down` stops both.
+
+SHELL := /usr/bin/env bash
+.SHELLFLAGS := -eu -o pipefail -c
+.DEFAULT_GOAL := help
+
+.PHONY: help
+help: ## Show this help
+	@awk 'BEGIN {FS = ":.*##"} /^[a-zA-Z0-9_-]+:.*##/ {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+.PHONY: prod
+prod: ## Build + run the production docs container (Caddy serves dist/)
+	docker compose up -d --build docs
+
+.PHONY: dev
+dev: ## Run the Astro dev server with HMR (--profile dev)
+	docker compose --profile dev up --build docs-dev
+
+.PHONY: down
+down: ## Stop and remove the docs containers
+	docker compose --profile dev down
+	docker compose down
+
+.PHONY: logs
+logs: ## Tail logs (works for whichever profile is up)
+	docker compose logs -f --tail=100
+
+.PHONY: build
+build: ## Build the static site WITHOUT bringing up Caddy (CI gate)
+	docker compose build docs
+
+.PHONY: shell
+shell: ## Open a shell in the running dev container (debugging)
+	docker compose exec docs-dev sh
+
+# ---- Production deploy --------------------------------------------------
+#
+# `make deploy` pulls origin/main on the warehack.ing prod host and rebuilds
+# the docs container. Agent-forwarding (`-A`) lets the remote `git pull` use
+# the operator's local SSH key for Gitea — nothing persistent is provisioned
+# on the deploy host.
+#
+# Override DEPLOY_HOST / DEPLOY_PATH for a different deployment without
+# editing this file. The defaults are the warehack.ing cookie-cutter shape
+# (see ~/.claude/references/warehacking.md).
+
+DEPLOY_HOST ?= warehack-ing@warehack.ing
+DEPLOY_PATH ?= ~/cuckoo-escapement
+
+.PHONY: deploy
+deploy: ## Pull main + rebuild the docs container on the prod host
+	@echo "==> deploying $(DEPLOY_HOST):$(DEPLOY_PATH)"
+	ssh -A $(DEPLOY_HOST) "cd $(DEPLOY_PATH) && git fetch origin main && git reset --hard origin/main && cd docs-site && make prod"
+	@echo "==> sanity check"
+	@curl -s -o /dev/null -w "    HTTP %{http_code}  %{url_effective}\n" "https://cuckoo.warehack.ing/explanation/bug-detection/"