build: unify the gate so root make check covers the backend (closes #16)

Root `make check` only ever ran the frontend, so the "main is always
green" policy was satisfied vacuously: the Go backend could be entirely
broken and the root gate stayed green.

- The backend moves onto scripts-to-rule-them-all. Its test, lint, fmt,
  fmt-check, build, run and clean implementations now live in
  `backend/script/`, and `backend/Makefile` is thin shims. The backend
  is its own project (own module, README, LICENSE, linter config,
  Dockerfile stage), and `Dockerfile.backend` only copies `backend/`
  into its builder, so its scripts have to live under `backend/`.
- The root `script/test`, `script/lint`, `script/fmt` and
  `script/fmt-check` now run the frontend step and then the matching
  `backend/script/*` step, so `script/check` — and therefore the
  pre-commit hook — gates both halves. The frontend-only steps moved
  into `script/frontend-*` so nothing is duplicated.
- `script/bootstrap` now provisions the backend's toolchain as well,
  because widening the gate without widening bootstrap left the
  documented fresh-clone path (`make setup`) installing a pre-commit
  hook that rejected every commit with `golangci-lint: not found`.
  golangci-lint is installed at exactly `2.7.2`, the version
  `Dockerfile.backend` pins, so local findings match CI. Go is reused
  only when the installed version falls inside a window — at least
  `backend/go.mod`'s floor, and no newer in major.minor than the Go the
  pinned linter was built with — otherwise `go1.25.7` is installed. The
  upper bound is load-bearing: golangci-lint links `go/types` from its
  own build toolchain, so the pinned `2.7.2` (built with `go1.25.4`)
  panics with "file requires newer Go version go1.26" against a host Go
  1.26, which would leave `make setup` exiting 0 and every commit
  rejected. Both tools come from a specific release archive whose sha256
  is hardcoded here and verified before anything is unpacked — never an
  install script piped to a shell — and both are symlinked onto `PATH`,
  since nvm-style activation does not reach `make` or the git hook.
- `script/bootstrap` links only into `~/.local/bin` and never into a
  system-wide prefix. `/usr/local/bin` is shared with other users and
  with a package manager — on an Intel Mac it is the Homebrew prefix —
  and pointing an entry there at one user's `$HOME` breaks it for
  everyone else. It also refuses, non-zero, to replace anything it did
  not create: only a symlink already pointing into its own toolchain
  directory is overwritten, so a pre-existing binary is reported rather
  than deleted. `corepack enable` is given `--install-directory` so its
  four shims (`yarn`, `yarnpkg`, `pnpm`, `pnpx`) land inside that same
  toolchain directory instead of beside the corepack binary, and only
  `yarn` is linked onto `PATH`.
- `script/bootstrap` exits non-zero when it cannot guarantee the pinned
  toolchain is the one the gate will run. Reporting success while
  knowing a different linter or a newer Go precedes `~/.local/bin` is
  the same defect this commit exists to remove, so the final step
  re-resolves `go`, `gofmt`, `golangci-lint`, `node` and `yarn` against
  the caller's own `PATH` and fails with what it found and how to fix
  it. The three tools that carry a version constraint are re-checked
  with the same predicates their installs use, not for bare presence:
  `gofmt` is a gate tool — `backend/script/fmt-check` runs it — and its
  output is not guaranteed identical across Go releases, so a `gofmt`
  built by a different Go than the one that compiles the code counts as
  missing. `go` and `gofmt` are relinked on every run in which the
  pinned toolchain is the one in use, rather than only on the run that
  unpacked the archive, so a deleted link is repaired instead of
  falling through to whatever `gofmt` the host happens to have. The
  failure text separates a tool that resolves to the wrong build
  (something shadows `~/.local/bin`) from one that does not resolve at
  all (nothing is shadowing it, it was never installed), and always
  names a real directory rather than interpolating an unset one.
- `script/frontend-check` is the frontend half of the gate, exposed as
  the `frontend-check` target, for the frontend Dockerfile: its build
  stage is a node image with no Go toolchain. The backend half is gated
  by `Dockerfile.backend`, and `script/cibuild` builds both images, so
  the two Dockerfiles together still gate the whole repo. The
  `backend-check` target is the mirror of it. Both targets are named
  after the script they shim, like every other target.
- `script/cibuild` builds both images through one `build_image` helper,
  and the Gitea workflow's only build step is `script/cibuild`; the raw
  `docker build -f Dockerfile.backend .` is gone from the workflow.
  `script/docker` likewise builds and tags both images.
- `backend/Makefile`'s `hooks` target is removed. It wrote the same
  `.git/hooks/pre-commit` as `script/install-precommit`, so the two
  clobbered each other and the developer silently ended up gating on
  only one half of the repo. `script/install-precommit` is now the only
  installer, and the hook it writes runs the repo-wide `script/check`.
- `backend/Makefile`'s `docker` target is removed too: the backend image
  builds from the repo root with a root-level Dockerfile, so it belongs
  to the root `script/docker` and `script/cibuild` rather than to a
  backend script that would have to reach outside `backend/`.
- `backend/script/lint` verifies that `.golangci.yml` still matches its
  pinned sha256 before running the linter. Offline hash comparison, no
  network. The pin is marked provisional in the file: it is the config
  currently on `main`, and the comment names PR #31 and the canonical
  hash that must replace it when #31 lands.
- Every script locates the repo root with the mandated
  `$(cd "$(dirname "$0")/.." && pwd -P)` idiom, `cd`s there, and calls
  siblings as `"$ROOT/script/<name>"`; the `SCRIPT_DIR` variant is gone.

READMEs at the root and in `backend/` document every script, the
backend's Getting Started separates commands run from `backend/` from
those run at the repo root, and `TODO.md` records the change.

.dockerignore

@@ -1,6 +1,5 @@
 node_modules
 dist
-.git
 .DS_Store
 *.log
 .claude

.gitea/workflows/check.yml

@@ -0,0 +1,11 @@
+name: check
+on: [push]
+jobs:
+    check:
+        runs-on: ubuntu-latest
+        steps:
+            # actions/checkout v4.2.2, 2026-02-22
+            - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+            # script/cibuild builds both images; it is the only build
+            # step, so how the repo builds stays defined in script/.
+            - run: script/cibuild

.prettierignore

@@ -1,3 +1,4 @@
+backend/
 dist/
 node_modules/
 yarn.lock

.prettierrc

@@ -1,3 +1,4 @@
 {
-    "tabWidth": 4
+    "tabWidth": 4,
+    "proseWrap": "always"
 }

Dockerfile

@@ -3,48 +3,23 @@ FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e3
 WORKDIR /app
 COPY package.json yarn.lock ./
 RUN yarn install --frozen-lockfile
+RUN apk add --no-cache git make
 COPY . .
-RUN yarn build
+# make frontend-check runs script/frontend-check (test + lint +
+# fmt-check for the frontend); its test step is the production yarn
+# build, so this both produces dist/ and gates the image on
+# lint/fmt-check/test regressions, not merely a broken build. It is the
+# frontend half of `make check` rather than all of it because this stage
+# is a node image with no Go toolchain; the backend half is gated by
+# Dockerfile.backend, and script/cibuild builds both images.
+RUN make frontend-check
 
 # nginx:stable-alpine as of 2026-02-22
 FROM nginx@sha256:15e96e59aa3b0aada3a121296e3bce117721f42d88f5f64217ef4b18f458c6ab
-# Remove default config
 RUN rm /etc/nginx/conf.d/default.conf
-# Config template — envsubst replaces $PORT at container start
-COPY <<'EOF' /etc/nginx/netwatch.conf.template
-server {
-    listen $PORT;
-    server_name _;
-
-    root /usr/share/nginx/html;
-    index index.html;
-
-    # Trust RFC1918 reverse proxies for X-Forwarded-For
-    set_real_ip_from 10.0.0.0/8;
-    set_real_ip_from 172.16.0.0/12;
-    set_real_ip_from 192.168.0.0/16;
-    real_ip_header X-Forwarded-For;
-    real_ip_recursive on;
-
-    # Access log to stdout (Docker best practice)
-    access_log /dev/stdout combined;
-    error_log  /dev/stderr warn;
-
-    location / {
-        try_files $uri $uri/ /index.html;
-    }
-
-    # Cache static assets aggressively
-    location /assets/ {
-        expires 1y;
-        add_header Cache-Control "public, immutable";
-    }
-}
-EOF
-
+COPY nginx.conf /etc/nginx/conf.d/netwatch.conf
 COPY --from=build /app/dist /usr/share/nginx/html
 
-ENV PORT=8080
 EXPOSE 8080
 
-CMD ["/bin/sh", "-c", "envsubst '$PORT' < /etc/nginx/netwatch.conf.template > /etc/nginx/conf.d/netwatch.conf && exec nginx -g 'daemon off;'"]
+CMD ["nginx", "-g", "daemon off;"]

Dockerfile.backend

@@ -0,0 +1,25 @@
+# golang:1.25-alpine (2026-02-27)
+FROM golang:1.25-alpine@sha256:f6751d823c26342f9506c03797d2527668d095b0a15f1862cddb4d927a7a4ced AS builder
+
+RUN apk add --no-cache git make gcc musl-dev
+
+# golangci-lint v2.7.2 (2026-02-27)
+RUN CGO_ENABLED=0 go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@9f61b0f53f80672872fced07b6874397c3ed197b
+
+WORKDIR /repo/backend
+COPY backend/go.mod backend/go.sum ./
+RUN go mod download
+COPY .git /repo/.git
+COPY backend/ .
+
+RUN make check
+RUN make build
+
+# alpine:3.23 (2026-02-27)
+FROM alpine:3.23@sha256:25109184c71bdad752c8312a8623239686a9a2071e8825f20acb8f2198c3f659
+
+RUN apk add --no-cache ca-certificates
+COPY --from=builder /repo/backend/netwatch-server /usr/local/bin/netwatch-server
+
+EXPOSE 8080
+ENTRYPOINT ["netwatch-server"]

Makefile

@@ -1,18 +1,46 @@
-.PHONY: test lint fmt fmt-check check docker
+.PHONY: bootstrap setup dev test lint fmt fmt-check check frontend-check \
+	backend-check docker hooks
+
+# Standard targets are thin shims; the implementations live in script/
+# per the scripts-to-rule-them-all pattern (see the Entrypoints section
+# of README.md). test, lint, fmt, fmt-check and check all cover the
+# whole repo: the frontend at the root and the Go backend in backend/.
+
+bootstrap:
+	@script/bootstrap
+
+setup:
+	@script/setup
+
+dev:
+	yarn dev
 
 test:
-	timeout 30 yarn build
+	@script/test
 
 lint:
-	yarn prettier --check .
+	@script/lint
 
 fmt:
-	yarn prettier --write .
+	@script/fmt
 
 fmt-check:
-	yarn prettier --check .
+	@script/fmt-check
 
-check: test lint fmt-check
+check:
+	@script/check
+
+# Half-repo gates. Used by the two Dockerfiles, whose build stages only
+# have the toolchain for their own half; prefer `make check` otherwise.
+# Each is named after the script it shims, like every other target here.
+frontend-check:
+	@script/frontend-check
+
+backend-check:
+	@backend/script/check
 
 docker:
-	timeout 300 docker build -t netwatch .
+	@script/docker
+
+hooks:
+	@script/install-precommit

README.md

@@ -1,4 +1,7 @@
-NetWatch is an MIT-licensed JavaScript single-page application by [@sneak](https://sneak.berlin) that provides real-time network latency monitoring to common internet hosts, displayed with color-coded figures and sparkline graphs, served from a static bucket or Docker container.
+NetWatch is an MIT-licensed JavaScript single-page application by
+[@sneak](https://sneak.berlin) that provides real-time network latency
+monitoring to common internet hosts, displayed with color-coded figures and
+sparkline graphs, served from a static bucket or Docker container.
 
 ## Getting Started
 
@@ -20,29 +23,116 @@ docker build -t netwatch .
 docker run -p 8080:8080 netwatch
 ```
 
+## Entrypoints
+
+This repository adheres to the
+[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+standard: normalized scripts in `script/` are the entrypoints for the
+development workflow, and the Makefile targets are thin shims that call them.
+
+The repo holds two projects: the frontend at the repo root and the Go backend in
+`backend/`, which has its own `script/` directory and its own shim Makefile. The
+root scripts cover both, so `make check` at the root fails if either half is
+broken. We provide:
+
+- `script/bootstrap` — install all dependencies, assuming nothing is present:
+  pinned node via nvm if needed, yarn via corepack,
+  `yarn install --frozen-lockfile`, and the backend's toolchain — Go (an
+  already-installed Go is reused only when its version falls inside the window
+  the pinned golangci-lint can analyse; a newer Go is ignored, not preferred)
+  and golangci-lint at the version `Dockerfile.backend` pins. Everything not
+  installed by the system package manager comes from a hash-verified release
+  archive and is symlinked into `~/.local/bin`, so `make check` works in a plain
+  shell afterwards
+- `script/setup` — make a fresh clone ready for development: bootstrap plus the
+  git pre-commit hook
+- `script/projectname` — print the project name (used for the Docker image tags)
+- `script/test` — run the whole repo's tests: `script/frontend-test`, then
+  `backend/script/test`
+- `script/lint` — lint the whole repo: `script/frontend-lint`, then
+  `backend/script/lint`
+- `script/fmt` — format the whole repo (writes): `script/frontend-fmt`, then
+  `backend/script/fmt`
+- `script/fmt-check` — check formatting across the whole repo (read-only)
+- `script/check` — run test, lint, and fmt-check; this is the repo-wide gate
+- `script/frontend-test` — the frontend's test: the production build (no unit
+  tests yet)
+- `script/frontend-lint` — run prettier in check mode
+- `script/frontend-fmt` — format everything prettier understands (writes)
+- `script/frontend-fmt-check` — check prettier formatting (read-only)
+- `script/frontend-check` — the frontend half of `script/check`, shimmed by
+  `make frontend-check` and used by `Dockerfile`, whose build stage is a node
+  image with no Go toolchain. Its mirror `make backend-check` shims to
+  `backend/script/check`
+- `script/docker` — build both images, tagged via `script/projectname`:
+  `netwatch` from `Dockerfile` and `netwatch-server` from `Dockerfile.backend`
+- `script/cibuild` — CI entrypoint: builds both images; the only build step in
+  the Gitea workflow
+- `script/precommit` — run by the git pre-commit hook; runs `script/check`, so a
+  commit is gated on both halves of the repo
+- `script/install-precommit` — install the git pre-commit hook; this is the
+  repo's only pre-commit hook installer
+
+The backend's scripts are shimmed by `backend/Makefile` and are also called by
+the root scripts above:
+
+- `backend/script/build` — compile `netwatch-server` with version and
+  architecture stamped in
+- `backend/script/test` — run the Go tests under a 30-second timeout
+- `backend/script/lint` — assert `.golangci.yml` still matches its pinned
+  sha256, then run golangci-lint
+- `backend/script/fmt` — format the Go sources (writes)
+- `backend/script/fmt-check` — check Go formatting (read-only)
+- `backend/script/check` — run the backend's test, lint, and fmt-check
+- `backend/script/run` — build and run the server locally
+- `backend/script/clean` — remove build artifacts
+
 ## Rationale
 
-When debugging network issues, it's useful to have a persistent at-a-glance view of latency and reachability to multiple well-known internet endpoints. NetWatch provides this as a zero-dependency SPA that can be deployed anywhere static files are served, with no backend required.
+When debugging network issues, it's useful to have a persistent at-a-glance view
+of latency and reachability to multiple well-known internet endpoints. NetWatch
+provides this as a zero-dependency SPA that can be deployed anywhere static
+files are served, with no backend required.
 
 ## Design
 
-The application is a single-page app built with Vite and Tailwind CSS v4. All code lives in `src/main.js` with a class-based architecture:
+The application is a single-page app built with Vite and Tailwind CSS v4. All
+code lives in `src/main.js` with a class-based architecture:
 
-- **`CONFIG`**: Frozen configuration object (update interval, timeouts, axis ticks, etc.)
-- **`HostState`**: Per-host state management — history buffer, latency tracking, status transitions
-- **`AppState`**: Top-level state container — WAN hosts, local hosts, pause state, aggregate stats
-- **`SparklineRenderer`**: Canvas 2D sparkline drawing with fixed axes, color-coded line segments, error regions, and DPR-aware scaling
-- **UI functions**: `buildUI()` constructs the DOM, `updateHostRow()` / `updateSummary()` / `updateHealthBox()` handle incremental updates
-- **`tick()`**: Main loop — measures all hosts in parallel via `Promise.all`, pushes samples, redraws UI. When paused, pushes blank markers (no probes, no false outage)
+- **`CONFIG`**: Frozen configuration object (update interval, timeouts, axis
+  ticks, etc.)
+- **`HostState`**: Per-host state management — history buffer, latency tracking,
+  status transitions
+- **`AppState`**: Top-level state container — WAN hosts, local hosts, pause
+  state, aggregate stats
+- **`SparklineRenderer`**: Canvas 2D sparkline drawing with fixed axes,
+  color-coded line segments, error regions, and DPR-aware scaling
+- **UI functions**: `buildUI()` constructs the DOM, `updateHostRow()` /
+  `updateSummary()` / `updateHealthBox()` handle incremental updates
+- **`tick()`**: Main loop — measures all hosts in parallel via `Promise.all`,
+  pushes samples, redraws UI. When paused, pushes blank markers (no probes, no
+  false outage)
 
 ### Monitoring targets
 
-- **9 WAN hosts**: Google Cloud Console, AWS Console, GitHub, Cloudflare, Azure, DigitalOcean, Fastly, Akamai, datavi.be
-- **1 Local host**: Local Gateway (192.168.100.1), tracked separately from WAN stats
+- **22 WAN hosts**: datavi.be, Anthropic API, OpenAI API, AWS Console, GCP
+  Console, Azure, Cloudflare, Fastly, Akamai, GitHub, B2, 7 S3 regional
+  endpoints (Cape Town, London, Bahrain, Tokyo, Sydney, Oregon, São Paulo), 4
+  GCS locational endpoints (Iowa, Belgium, Singapore, Sydney)
+- **Local CPE**: Cable modem at 192.168.100.1 (always monitored)
+- **Local Gateway**: Auto-detected on startup by probing common default gateway
+  addresses (192.168.1.1, 192.168.0.1, 192.168.8.1, 10.0.0.1); first responder
+  wins. Note: modern browsers enforce Private Network Access restrictions that
+  block public-origin pages from reaching RFC1918 addresses, so local targets
+  only work when NetWatch is served from localhost or a private address.
+
+Local hosts are tracked separately from WAN stats.
 
 ### Latency measurement
 
-HEAD requests with `mode: 'no-cors'` and `cache: 'no-store'`, timed with `performance.now()`. 1-second timeout; anything over 1000ms is clamped to unreachable. IPv4 only.
+HEAD requests with `mode: 'no-cors'` and `cache: 'no-store'`, timed with
+`performance.now()`. 1-second timeout; anything over 1000ms is clamped to
+unreachable. IPv4 only.
 
 ### Color coding
 
@@ -72,31 +162,40 @@ dist/
 - Summary stats: reachable count, min/max/avg latency across WAN hosts only
 - Fixed chart axes: Y-axis 0–1000ms, X-axis 0–300s
 - Color-coded latency figures and sparkline line segments
-- Play/pause: pause stops probes but history keeps scrolling (blank gaps, no false outage)
+- Play/pause: pause stops probes but history keeps scrolling (blank gaps, no
+  false outage)
 - Clickable service URLs
 - Canvas-based sparkline rendering with devicePixelRatio scaling
 - Zero runtime dependencies: all resources bundled into build artifacts
 
 ## Deployment
 
-After running `yarn build`, deploy the contents of the `dist/` directory to any static file host (S3, GCS, Cloudflare Pages, Vercel, Netlify, GitHub Pages) or use the Docker image behind a reverse proxy.
+After running `yarn build`, deploy the contents of the `dist/` directory to any
+static file host (S3, GCS, Cloudflare Pages, Vercel, Netlify, GitHub Pages) or
+use the Docker image behind a reverse proxy.
 
 The Docker image:
 
 - Listens on port 8080 by default (override with `PORT` env var)
-- Trusts `X-Forwarded-For` from RFC1918 reverse proxies (10/8, 172.16/12, 192.168/16)
+- Trusts `X-Forwarded-For` from RFC1918 reverse proxies (10/8, 172.16/12,
+  192.168/16)
 - Sends access logs to stdout
 - Caches static assets with immutable headers
 
 ## Browser Compatibility
 
-Requires a modern browser with ES modules, Fetch API, Canvas API, and CSS custom properties.
+Requires a modern browser with ES modules, Fetch API, Canvas API, and CSS custom
+properties.
 
 ## Limitations
 
-- **CORS**: Some hosts may block cross-origin HEAD requests. The app uses `no-cors` mode which allows the request but provides opaque responses. Latency is still measurable based on request timing.
-- **Local gateway**: The 192.168.100.1 endpoint requires the host to be accessible from your network.
-- **Network conditions**: Measurements reflect browser-to-endpoint latency, which includes your local network, ISP, and internet routing.
+- **CORS**: Some hosts may block cross-origin HEAD requests. The app uses
+  `no-cors` mode which allows the request but provides opaque responses. Latency
+  is still measurable based on request timing.
+- **Local gateway**: The 192.168.100.1 endpoint requires the host to be
+  accessible from your network.
+- **Network conditions**: Measurements reflect browser-to-endpoint latency,
+  which includes your local network, ISP, and internet routing.
 
 ## TODO
 

REPO_POLICIES.md

@@ -1,110 +1,408 @@
-# Development Policies
+---
+title: Repository Policies
+last_modified: 2026-07-06
+---
 
-- Docker image references by tag are server-mutable, therefore using them is
-  an RCE vulnerability. All docker image references must use cryptographic
-  hashes to securely specify the exact image that is expected.
+This document covers repository structure, tooling, and workflow standards. Code
+style conventions are in separate documents:
 
-- Correspondingly, `go install` commands using things like '@latest' are
-  also dangerous RCE. Whenever writing scripts or tools, ALWAYS specify go
-  install targets using commit hashes which are cryptographically secure.
+- [Code Styleguide](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE.md)
+  (general, bash, Docker)
+- [Go](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_GO.md)
+- [JavaScript](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_JS.md)
+- [Python](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE_PYTHON.md)
+- [Go HTTP Server Conventions](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/GO_HTTP_SERVER_CONVENTIONS.md)
 
-- Every repo with software in it must have a Makefile in the root. Each
-  such Makefile should support `make test` (runs the project-specific
-  tests), `make lint`, `make fmt` (writes), `make fmt-check` (readonly), and
-  `make check` (has `test`, `lint`, and `fmt-check` as prereqs), `make
-docker` (builds docker image).
+---
 
-- Every repo should have a Dockerfile. If the repo contains non-server
-  software, the Dockerfile should bring up a development environment and
-  `make check` (i.e. the docker build should fail if the branch is not
-  green).
+- Cross-project documentation (such as this file) must include
+  `last_modified: YYYY-MM-DD` in the YAML front matter so it can be kept in sync
+  with the authoritative source as policies evolve.
 
-- Platform-specific standard formatting should be used. `black` for python,
-  `prettier` for js/css/etc, `go fmt` for go. The only changes to default
-  settings should be to specify four-space indents where applicable (i.e.
-  everything except `go fmt`).
+- **ALL external references must be pinned by cryptographic hash.** This
+  includes Docker base images, Go modules, npm packages, GitHub Actions, and
+  anything else fetched from a remote source. Version tags (`@v4`, `@latest`,
+  `:3.21`, etc.) are server-mutable and therefore remote code execution
+  vulnerabilities. The ONLY acceptable way to reference an external dependency
+  is by its content hash (Docker `@sha256:...`, Go module hash in `go.sum`, npm
+  integrity hash in lockfile, GitHub Actions `@<commit-sha>`). No exceptions.
+  This also means never `curl | bash` to install tools like pyenv, nvm, rustup,
+  etc. Instead, download a specific release archive from GitHub, verify its hash
+  (hardcoded in the Dockerfile or script), and only then install. Unverified
+  install scripts are arbitrary remote code execution. This is the single most
+  important rule in this document. Double-check every external reference in
+  every file before committing. There are zero exceptions to this rule.
 
-- If local testing is possible (it is not always), `make check` should be a
-  pre-commit hook. If it is not possible, `make lint && make fmt-check`
-  should be a pre-commit hook.
+- Every repo with software must have a root `Makefile` with these targets:
+  `make bootstrap`, `make setup`, `make test`, `make lint`, `make fmt` (writes),
+  `make fmt-check` (read-only), `make check` (runs `test`, `lint`, `fmt-check`),
+  `make docker`, and `make hooks` (installs pre-commit hook). A model Makefile
+  is at `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`.
 
-- If a working `make test` takes more than 20 seconds, that's a bug that
-  needs fixing. In fact, there should be a timeout specified in the
-  `Makefile` that fails it automatically if it takes >30s.
+- Repos follow the
+  [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+  pattern: the implementation of each Makefile target lives in an executable
+  script in `script/` (`script/bootstrap`, `script/setup`, `script/test`,
+  `script/lint`, `script/fmt`, `script/fmt-check`, `script/check`,
+  `script/docker`), and the Makefile targets are thin shims that call them. The
+  scripts must be POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run in
+  minimal containers (e.g. alpine images have no bash); locate the repo root
+  with `$(cd "$(dirname "$0")/.." && pwd -P)` and `cd` there before acting. From
+  the standard's canonical set we use `bootstrap`, `setup` (make the repo ready
+  for development after a fresh clone: runs `bootstrap`, then
+  `install-precommit`, plus any repo-specific initialization), `test`, and
+  `cibuild`. `script/bootstrap` installs all dependencies idempotently and
+  assumes nothing is present: base tools come from nix, apt, brew, or apk
+  (detected in that order; apt runs noninteractive). For node it uses the
+  installed node if present; otherwise it installs a PINNED node version via
+  nvm, first installing nvm itself if missing — from a hash-verified GitHub
+  release archive (never `curl | sh`), with bash installed as an explicit
+  prerequisite since nvm requires bash. yarn is then pinned via
+  `corepack prepare yarn@<version> --activate`. Never install "latest" or "lts";
+  always exact versions. `script/cibuild` runs the CI build: it changes to the
+  repo root and runs `docker build .`; the Gitea workflow calls it. Four further
+  scripts are our own extensions to the standard: `script/check` runs
+  `script/test`, `script/lint`, and `script/fmt-check`; `script/precommit` is
+  what the git pre-commit hook runs, and it calls `script/check`;
+  `script/install-precommit` installs the git pre-commit hook (the `make hooks`
+  target shims to it); and `script/projectname` (literally that filename) simply
+  outputs the project's name. Scripts that need the name call
+  `script/projectname` — e.g. `script/docker` assembles its image tag from it —
+  so those scripts stay byte-identical across all repos. Repo-type-specific
+  pre-commit extras (e.g. `go mod tidy` verification in Go repos) belong in
+  `script/precommit`, not in the hook itself. Model scripts are at
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`. The README
+  must document the provided scripts in an **Entrypoints** section (see the
+  README requirements below).
 
-- Docker builds should time out in 5 minutes or less.
+- Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.)
+  instead of invoking the underlying tools directly. The Makefile is the single
+  source of truth for how these operations are run.
+
+- The Makefile is authoritative documentation for how the repo is used. Beyond
+  the required targets above, it should have targets for every common operation:
+  running a local development server (`make run`, `make dev`), re-initializing
+  or migrating the database (`make db-reset`, `make migrate`), building
+  artifacts (`make build`), generating code, seeding data, or anything else a
+  developer would do regularly. If someone checks out the repo and types
+  `make<tab>`, they should see every meaningful operation available. A new
+  contributor should be able to understand the entire development workflow by
+  reading the Makefile.
+
+- Every repo should have a `Dockerfile`. All Dockerfiles must run `make check`
+  as a build step so the build fails if the branch is not green. For non-server
+  repos, the Dockerfile should bring up a development environment and run
+  `make check`. For server repos, `make check` should run as an early build
+  stage before the final image is assembled. Dockerfiles install development
+  prerequisites by running `script/bootstrap` rather than duplicating installs
+  inline; COPY `script/` and the dependency manifests (`package.json` +
+  `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it so the bootstrap
+  layer stays cached until dependencies change.
+
+- **Dockerfiles must use a separate lint stage for fail-fast feedback.** Go
+  repos use a multistage build where linting runs in an independent stage based
+  on the `golangci/golangci-lint` image (pinned by hash). This stage runs
+  `make fmt-check` and `make lint` before the full build begins. The build stage
+  then declares an explicit dependency on the lint stage via
+  `COPY --from=lint /src/go.sum /dev/null`, which forces BuildKit to complete
+  linting before proceeding to compilation and tests. This ensures lint failures
+  surface in seconds rather than minutes, without blocking on dependency
+  download or compilation in the build stage.
+
+    The standard pattern for a Go repo Dockerfile is:
+
+    ```dockerfile
+    # Lint stage — fast feedback on formatting and lint issues
+    # golangci/golangci-lint:v2.x.x, YYYY-MM-DD
+    FROM golangci/golangci-lint@sha256:... AS lint
+    WORKDIR /src
+    COPY go.mod go.sum ./
+    RUN go mod download
+    COPY . .
+    RUN make fmt-check
+    RUN make lint
+
+    # Build stage
+    # golang:1.x-alpine, YYYY-MM-DD
+    FROM golang@sha256:... AS builder
+    WORKDIR /src
+
+    # Force BuildKit to run the lint stage before proceeding
+    COPY --from=lint /src/go.sum /dev/null
+
+    COPY go.mod go.sum ./
+    RUN go mod download
+    COPY . .
+    RUN make test
+
+    ARG VERSION=dev
+    RUN CGO_ENABLED=0 go build -trimpath \
+        -ldflags="-s -w -X main.Version=${VERSION}" \
+        -o /app ./cmd/app/
+
+    # Runtime stage
+    FROM alpine@sha256:...
+    COPY --from=builder /app /usr/local/bin/app
+    ENTRYPOINT ["app"]
+    ```
+
+    Key points:
+    - The lint stage uses the `golangci/golangci-lint` image directly (it
+      includes both Go and the linter), so there is no need to install the
+      linter separately.
+    - `COPY --from=lint /src/go.sum /dev/null` is a no-op file copy that creates
+      a stage dependency. BuildKit runs stages in parallel by default; without
+      this line, the build stage would not wait for lint to finish and a lint
+      failure might not fail the overall build.
+    - If the project uses `//go:embed` directives that reference build artifacts
+      (e.g. a web frontend compiled in a separate stage), the lint stage must
+      create placeholder files so the embed directives resolve. Example:
+      `RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css`.
+      The lint stage should not depend on the actual build output — it exists to
+      fail fast.
+    - If the project requires CGO or system libraries for linting (e.g.
+      `vips-dev`), install them in the lint stage with `apk add`.
+    - The build stage runs `make test` after compilation setup. Tests run in the
+      build stage, not the lint stage, because they may require compiled
+      artifacts or heavier dependencies.
+
+- Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
+  runs `script/cibuild` (which runs `docker build .`) on push. Since the
+  Dockerfile already runs `make check`, a successful build implies all checks
+  pass.
+
+- Use platform-standard formatters: `black` for Python, `prettier` for
+  JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
+  two exceptions: four-space indents (except Go), and `proseWrap: always` for
+  Markdown (hard-wrap at 80 columns). Documentation and writing repos (Markdown,
+  HTML, CSS) should also have `.prettierrc` and `.prettierignore`.
+
+- Pre-commit hook: runs `script/precommit`, which calls `script/check`. If local
+  testing is not possible in the repo, `script/precommit` may skip `script/test`
+  and run only `script/lint` and `script/fmt-check`. The hook is installed by
+  `script/install-precommit`; the Makefile must provide a `make hooks` target
+  that shims to it.
+
+- All repos with software must have tests that run via the platform-standard
+  test framework (`go test`, `pytest`, `jest`/`vitest`, etc.). If no meaningful
+  tests exist yet, add the most minimal test possible — e.g. importing the
+  module under test to verify it compiles/parses. There is no excuse for
+  `make test` to be a no-op.
+
+- `make test` must complete in under 20 seconds. Add a 30-second timeout in the
+  Makefile.
+
+- **`make test` should use the conditional verbose rerun pattern.** Run tests
+  without `-v` (verbose) first. If tests fail, automatically rerun with `-v` to
+  show full output. This keeps CI logs and `docker build` output clean on
+  success (just package/suite summaries) while providing full diagnostic detail
+  on failure (every test case, every assertion). The general shell pattern:
+
+    ```makefile
+    test:
+    	@<test-command> || \
+    		{ echo "--- Rerunning with -v for details ---"; \
+    		  <test-command-with-v>; exit 1; }
+    ```
+
+    Go example:
+
+    ```makefile
+    test:
+    	@go test -timeout 30s -race -cover ./... || \
+    		{ echo "--- Rerunning with -v for details ---"; \
+    		  go test -timeout 30s -race -v ./...; exit 1; }
+    ```
+
+    Python example:
+
+    ```makefile
+    test:
+    	@python -m pytest || \
+    		{ echo "--- Rerunning with -v for details ---"; \
+    		  python -m pytest -v; exit 1; }
+    ```
+
+    The `exit 1` ensures the target always fails after a rerun — the first run
+    already proved the tests are broken, so the build must not pass even if a
+    flaky test happens to succeed on the second attempt. The rerun exists solely
+    for diagnostic output.
+
+- Docker builds must complete in under 5 minutes.
+
+- `make check` must not modify any files in the repo. Tests may use temporary
+  directories.
 
 - `main` must always pass `make check`, no exceptions.
 
-- Do all changes on a feature branch. You can do whatever you want on a
+- Never commit secrets. `.env` files, credentials, API keys, and private keys
+  must be in `.gitignore`. No exceptions.
+
+- `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
+  editor files (`.swp`, `*~`), language build artifacts, and `node_modules/`.
+  Fetch the standard `.gitignore` from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
+  a new repo.
+
+- **No build artifacts in version control.** Code-derived data (compiled
+  bundles, minified output, generated assets) must never be committed to the
+  repository if it can be avoided. The build process (e.g. Dockerfile, Makefile)
+  should generate these at build time. Notable exception: Go protobuf generated
+  files (`.pb.go`) ARE committed because repos need to work with `go get`, which
+  downloads code but does not execute code generation.
+
+- Never use `git add -A` or `git add .`. Always stage files explicitly by name.
+
+- Never force-push to `main`.
+
+- Make all changes on a feature branch. You can do whatever you want on a
   feature branch.
 
-- We have a standardized `.golangci.yml` which we reuse and is _NEVER_ to be
-  modified by an agent, only manually by the user. It can be copied from
-  `~/dev/upaas/.golangci.yml` if it exists at that location.
+- `.golangci.yml` is standardized and must _NEVER_ be modified by an agent, only
+  manually by the user. Fetch from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`.
 
-- When specifying images or packages by hash in Dockerfiles or
-  `docker-compose.yml`, put a comment above the line and show the version
-  and date at which it was current.
+- When pinning images or packages by hash, add a comment above the reference
+  with the version and date (YYYY-MM-DD).
 
-- For javascript, always use `yarn` over `npm`.
+- Use `yarn`, not `npm`.
 
-- Whenever writing dates, ALWAYS write YYYY-MM-DD (ISO 8601).
+- Write all dates as YYYY-MM-DD (ISO 8601).
 
-- Simple projects should be configured with environment variables, as is
-  standard for Dockerized applications.
+- Simple projects should be configured with environment variables.
 
-- Dockerized web services should listen on the default HTTP port of 8080
-  unless overridden with the `PORT` environment variable.
+- Dockerized web services listen on port 8080 by default, overridable with
+  `PORT`.
 
-- The `README.md` is a project's primary documentation. It should contain
-  at a minimum the following sections:
-    - Description
-        - Include a short and complete description of the functionality and
-          purpose of the software as the first line in the readme. It must
-          include:
-            - the name
-            - the purpose
-            - the category (web server, SPA, command line tool, etc)
-            - the license
-            - the author
-            - eg: "µPaaS is an MIT-licensed Go web application by @sneak
-              that receives git-frontend webhooks and interacts with a
-              Docker server to build and deploy applications in realtime as
-              certain branches are updated."
-    - Getting Started
-        - a code block with copy-pasteable installation/use sections
-    - Rationale
-        - why does this exist?
-    - Design
-        - how is the program structured?
-    - TODO
-        - This is your TODO list for the project - update it meticulously,
-          even in between commits. Whenever planning, put your todo list in
-          the README so that a separate agent with new context can pick up
-          where you left off.
-    - License
-        - GPL or MIT or WTFPL - ask the user when beginning a new project
-          and include a LICENSE file in the root and in a section in the
-          README.
-    - Author
-        - @sneak (link `@sneak` to `https://sneak.berlin`).
+- **HTTP/web services must be hardened for production internet exposure before
+  tagging 1.0.** This means full compliance with security best practices
+  including, without limitation, all of the following:
+    - **Security headers** on every response:
+        - `Strict-Transport-Security` (HSTS) with `max-age` of at least one year
+          and `includeSubDomains`.
+        - `Content-Security-Policy` (CSP) with a restrictive default policy
+          (`default-src 'self'` as a baseline, tightened per-resource as
+          needed). Never use `unsafe-inline` or `unsafe-eval` unless
+          unavoidable, and document the reason.
+        - `X-Frame-Options: DENY` (or `SAMEORIGIN` if framing is required).
+          Prefer the `frame-ancestors` CSP directive as the primary control.
+        - `X-Content-Type-Options: nosniff`.
+        - `Referrer-Policy: strict-origin-when-cross-origin` (or stricter).
+        - `Permissions-Policy` restricting access to browser features the
+          application does not use (camera, microphone, geolocation, etc.).
+    - **Request and response limits:**
+        - Maximum request body size enforced on all endpoints (e.g. Go
+          `http.MaxBytesReader`). Choose a sane default per-route; never accept
+          unbounded input.
+        - Maximum response body size where applicable (e.g. paginated APIs).
+        - `ReadTimeout` and `ReadHeaderTimeout` on the `http.Server` to defend
+          against slowloris attacks.
+        - `WriteTimeout` on the `http.Server`.
+        - `IdleTimeout` on the `http.Server`.
+        - Per-handler execution time limits via `context.WithTimeout` or
+          chi/stdlib `middleware.Timeout`.
+    - **Authentication and session security:**
+        - Rate limiting on password-based authentication endpoints. API keys are
+          high-entropy and not susceptible to brute force, so they are exempt.
+        - CSRF tokens on all state-mutating HTML forms. API endpoints
+          authenticated via `Authorization` header (Bearer token, API key) are
+          exempt because the browser does not attach these automatically.
+        - Passwords stored using bcrypt, scrypt, or argon2 — never plain-text,
+          MD5, or SHA.
+        - Session cookies set with `HttpOnly`, `Secure`, and `SameSite=Lax` (or
+          `Strict`) attributes.
+    - **Reverse proxy awareness:**
+        - True client IP detection when behind a reverse proxy
+          (`X-Forwarded-For`, `X-Real-IP`). The application must accept
+          forwarded headers only from a configured set of trusted proxy
+          addresses — never trust `X-Forwarded-For` unconditionally.
+    - **CORS:**
+        - Authenticated endpoints must restrict `Access-Control-Allow-Origin` to
+          an explicit allowlist of known origins. Wildcard (`*`) is acceptable
+          only for public, unauthenticated read-only APIs.
+    - **Error handling:**
+        - Internal errors must never leak stack traces, SQL queries, file paths,
+          or other implementation details to the client. Return generic error
+          messages in production; detailed errors only when `DEBUG` is enabled.
+    - **TLS:**
+        - Services never terminate TLS directly. They are always deployed behind
+          a TLS-terminating reverse proxy. The service itself listens on plain
+          HTTP. However, HSTS headers and `Secure` cookie flags must still be
+          set by the application so that the browser enforces HTTPS end-to-end.
 
-- When beginning a new project, initialize a git repo and make the first
-  commit simply the first version of the README.md in the root of the repo.
+    This list is non-exhaustive. Apply defense-in-depth: if a standard security
+    hardening measure exists for HTTP services and is not listed here, it is
+    still expected. When in doubt, harden.
 
-- For Go packages, the module root is `sneak.berlin/go/...`, such
-  as `sneak.berlin/go/dnswatcher`.
+- `README.md` is the primary documentation. Required sections:
+    - **Description**: First line must include the project name, purpose,
+      category (web server, SPA, CLI tool, etc.), license, and author. Example:
+      "µPaaS is an MIT-licensed Go web application by @sneak that receives
+      git-frontend webhooks and deploys applications via Docker in realtime."
+    - **Getting Started**: Copy-pasteable install/usage code block.
+    - **Entrypoints**: Opens by stating that the repo adheres to the
+      [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+      standard (with that link), then documents each provided `script/`
+      entrypoint and its purpose.
+    - **Rationale**: Why does this exist?
+    - **Design**: How is the program structured?
+    - **TODO**: Update meticulously, even between commits. When planning, put
+      the todo list in the README so a new agent can pick up where the last one
+      left off.
+    - **License**: MIT, GPL, or WTFPL. Ask the user for new projects. Include a
+      `LICENSE` file in the repo root and a License section in the README.
+    - **Author**: [@sneak](https://sneak.berlin).
 
-- We use SemVer always.
+- First commit of a new repo should contain only `README.md`.
 
-- If no tag `1.0.0` or greater exists in the repository, modify the existing
-  migrations and assume no installed base or existing databases. If
-  `>=1.0.0`, database changes add new migration files.
+- Go module root: `sneak.berlin/go/<name>`. Always run `go mod tidy` before
+  committing.
 
-- New repos must have at a minimum the following files:
-    - `README.md`, `.git`, `.gitignore`
-    - `POLICIES.md` (copy from `~/Documents/_PROMPTS/POLICIES.md`)
+- Use SemVer.
+
+- Database migrations live in `internal/db/migrations/` and must be embedded in
+  the binary.
+    - `000_migration.sql` — contains ONLY the creation of the migrations
+      tracking table itself. Nothing else.
+    - `001_schema.sql` — the full application schema.
+    - **Pre-1.0.0:** never add additional migration files (002, 003, etc.).
+      There is no installed base to migrate. Edit `001_schema.sql` directly.
+    - **Post-1.0.0:** add new numbered migration files for each schema change.
+      Never edit existing migrations after release.
+
+- All repos should have an `.editorconfig` enforcing the project's indentation
+  settings.
+
+- Avoid putting files in the repo root unless necessary. Root should contain
+  only project-level config files (`README.md`, `Makefile`, `Dockerfile`,
+  `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and
+  language-specific config). Everything else goes in a subdirectory. Canonical
+  subdirectory names:
+    - `bin/` — executable scripts and tools
+    - `cmd/` — Go command entrypoints
+    - `configs/` — configuration templates and examples
+    - `deploy/` — deployment manifests (k8s, compose, terraform)
+    - `docs/` — documentation and markdown (README.md stays in root)
+    - `internal/` — Go internal packages
+    - `internal/db/migrations/` — database migrations
+    - `pkg/` — Go library packages
+    - `share/` — systemd units, data files
+    - `static/` — static assets (images, fonts, etc.)
+    - `web/` — web frontend source
+
+- When setting up a new repo, files from the `prompts` repo may be used as
+  templates. Fetch them from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/<path>`.
+
+- New repos must contain at minimum:
+    - `README.md`, `.git`, `.gitignore`, `.editorconfig`
+    - `LICENSE`, `REPO_POLICIES.md` (copy from the `prompts` repo)
+    - `Makefile`
+    - `script/` entrypoints (`bootstrap`, `setup`, `projectname`, `test`,
+      `lint`, `fmt`, `fmt-check`, `check`, `docker`, `cibuild`, `precommit`,
+      `install-precommit`)
     - `Dockerfile`, `.dockerignore`
-    - for go: `go.mod`, `go.sum`, `.golangci.yml`
-    - for js: `package.json`
+    - `.gitea/workflows/check.yml`
+    - Go: `go.mod`, `go.sum`, `.golangci.yml`
+    - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
+    - Python: `pyproject.toml`

TODO.md

@@ -0,0 +1,61 @@
+# Workflow
+
+- branch (from `main`)
+- do the work in Next Step
+- move Next Step to the top of Completed Steps
+- move the top item of Future Steps into Next Step
+- commit (`TODO.md` changes in the same commit as the work)
+- merge to `main` if the branch is not protected, otherwise open a PR
+- push
+
+# Status
+
+pre-1.0. No git tags. Backend work in flight on feat/reportbuf-storage (dirty:
+src/main.js). Frontend is functional; backend is new and unmerged.
+
+# Next Step
+
+Land feat/reportbuf-storage: finish the in-progress src/main.js change, get make
+check green, and merge the branch to main. The branch adds the backend (buffered
+zstd-compressed report storage), the CI workflow, and backend repo standard
+files, so merging it also closes most compliance gaps.
+
+# Completed Steps
+
+- 2026-08-09: unified the gate: the root `make check` now covers the Go backend
+  as well as the frontend, the backend moved onto scripts-to-rule-them-all
+  (`backend/script/*` with `backend/Makefile` as thin shims), the duplicate
+  pre-commit hook installer in `backend/Makefile` was removed, `script/cibuild`
+  now builds both images as the workflow's only build step, and
+  `script/bootstrap` provisions the backend toolchain (pinned, hash-verified Go
+  and golangci-lint) so a fresh clone can pass the widened gate. Bootstrap
+  matches the Go pin rather than treating it as a floor, because the pinned
+  golangci-lint cannot analyse packages built by a newer Go; it links only into
+  `~/.local/bin`, never a system-wide prefix, and refuses to replace anything it
+  did not create; and it exits non-zero rather than reporting success when the
+  tools on the caller's `PATH` are not the pinned ones — `gofmt` included, held
+  to the same version agreement as `go` and relinked on every run so a deleted
+  link cannot leave another Go's `gofmt` gating the repo
+- 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints, Makefile
+  shims, README Entrypoints section
+- 2026-02-27: backend with buffered zstd-compressed report storage; CI workflow
+  and backend repo standard files; backend Dockerfile fixed (Go 1.25,
+  golangci-lint) and moved to repo root (feat/reportbuf-storage, unmerged)
+- 2026-02-26: host row layout redesigned with CSS grid; overflow and spacing
+  fixes; nginx config extracted; port hardcoded to 8080
+- 2026-02-26: debug log panel, median stats, recovery probe, Docker build fix,
+  S3 Singapore endpoint added
+- 2026-02-23: summary box redesign, host pinning, local and UTC clocks, checks
+  counter
+- 2026-02-23: hosts sorted by latency; GET instead of HEAD for latency; timeout
+  derived from interval; Hetzner regional endpoints; 3s interval
+- 2026-01-29: initial NetWatch network latency monitor
+
+# Future Steps
+
+- Compliance top-up as one small commit: add .editorconfig and add the hooks
+  target to the Makefile
+- After merge, confirm .gitea/workflows/check.yml is on main and CI is green
+  (main always green policy)
+- Decide what to do with untracked resume.sh: commit it, gitignore it, or delete
+  it

backend/.dockerignore

@@ -0,0 +1,2 @@
+node_modules
+.DS_Store

backend/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[Makefile]
+indent_style = tab

backend/.gitignore

@@ -0,0 +1,6 @@
+/netwatch-server
+*.log
+*.out
+*.test
+.env
+data/

backend/.golangci.yml

@@ -0,0 +1,32 @@
+version: "2"
+
+run:
+  timeout: 5m
+  modules-download-mode: readonly
+
+linters:
+  default: all
+  disable:
+    # Genuinely incompatible with project patterns
+    - exhaustruct      # Requires all struct fields
+    - depguard         # Dependency allow/block lists
+    - godot            # Requires comments to end with periods
+    - wsl              # Deprecated, replaced by wsl_v5
+    - wrapcheck        # Too verbose for internal packages
+    - varnamelen       # Short names like db, id are idiomatic Go
+
+linters-settings:
+  lll:
+    line-length: 88
+  funlen:
+    lines: 80
+    statements: 50
+  cyclop:
+    max-complexity: 15
+  dupl:
+    threshold: 100
+
+issues:
+  exclude-use-default: false
+  max-issues-per-linter: 0
+  max-same-issues: 0

backend/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 @sneak (https://sneak.berlin)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

backend/Makefile

@@ -0,0 +1,38 @@
+# Standard targets are thin shims; the implementations live in
+# backend/script/ per the scripts-to-rule-them-all pattern (see the
+# Entrypoints section of README.md).
+#
+# There is no `hooks` target here: the repo has exactly one pre-commit
+# hook installer, the root `script/install-precommit`, and the hook it
+# installs gates both halves of the repo. There is no `docker` target
+# either: the backend image is built from Dockerfile.backend with the
+# repo root as its context, so it belongs to the root `make docker` and
+# `script/cibuild`.
+
+.PHONY: all build test lint fmt fmt-check check run clean
+
+all: build
+
+build:
+	@script/build
+
+test:
+	@script/test
+
+lint:
+	@script/lint
+
+fmt:
+	@script/fmt
+
+fmt-check:
+	@script/fmt-check
+
+check:
+	@script/check
+
+run:
+	@script/run
+
+clean:
+	@script/clean

backend/README.md

@@ -0,0 +1,106 @@
+netwatch-server is an MIT-licensed Go HTTP backend by
+[@sneak](https://sneak.berlin) that receives telemetry reports from the NetWatch
+SPA and persists them as zstd-compressed JSONL files on disk.
+
+## Getting Started
+
+From this directory (`backend/`):
+
+```bash
+# Build and run locally
+make run
+
+# Run the backend's tests, lint, and format check
+make check
+```
+
+From the repo root, one directory up — `Dockerfile.backend` lives there and its
+build context is the repo root, so there is no `docker` target here:
+
+```bash
+# Build both images, including netwatch-server
+make docker
+
+# Run the backend image
+docker run -p 8080:8080 netwatch-server
+```
+
+## Entrypoints
+
+This project follows the same
+[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+pattern as the repo root: the implementations live in `backend/script/` and the
+targets in `backend/Makefile` are thin shims that call them. The repo root's
+`script/test`, `script/lint`, `script/fmt` and `script/fmt-check` call these
+too, so the root `make check` covers the backend.
+
+- `script/build` — compile `netwatch-server` with the version and architecture
+  stamped in via ldflags (statically linked on Linux)
+- `script/test` — run the Go tests under a 30-second timeout
+- `script/lint` — assert `.golangci.yml` still matches its pinned sha256, then
+  run golangci-lint
+- `script/fmt` — format the Go sources (writes)
+- `script/fmt-check` — check Go formatting (read-only)
+- `script/check` — run test, lint, and fmt-check
+- `script/run` — build and run the server locally
+- `script/clean` — remove build artifacts
+
+There is deliberately no `hooks` target here: the repo has exactly one
+pre-commit hook installer, the root `script/install-precommit`, and the hook it
+installs runs the root `script/check`, which gates both halves of the repo.
+There is no `docker` target either: `Dockerfile.backend` lives at the repo root
+and builds with the repo root as its context, so the backend image is built by
+the root `make docker` and by `script/cibuild`.
+
+## Rationale
+
+The NetWatch frontend collects latency measurements from the browser but has no
+way to persist or aggregate them. This backend provides a minimal
+`POST /api/v1/reports` endpoint that buffers incoming reports in memory and
+flushes them to compressed files on disk for later analysis.
+
+## Design
+
+The server is structured as an `fx`-wired Go application under `cmd/netwatch-server/`.
+Internal packages in `internal/` follow standard Go project layout:
+
+- **`config`**: Loads configuration from environment variables and config files
+  via Viper.
+- **`handlers`**: HTTP request handlers for the API (health check, report
+  ingestion).
+- **`reportbuf`**: In-memory buffer that accumulates JSONL report lines and
+  flushes to zstd-compressed files when the buffer reaches 10 MiB or every 60
+  seconds.
+- **`server`**: Chi-based HTTP server with middleware wiring and route
+  registration.
+- **`healthcheck`**, **`middleware`**, **`logger`**, **`globals`**: Supporting
+  infrastructure.
+
+### Configuration
+
+| Variable   | Default            | Description                       |
+| ---------- | ------------------ | --------------------------------- |
+| `PORT`     | `8080`             | HTTP listen port                  |
+| `DATA_DIR` | `./data/reports`   | Directory for compressed reports  |
+| `DEBUG`    | `false`            | Enable debug logging              |
+
+### Report storage
+
+Reports are written as `reports-<timestamp>.jsonl.zst` files in `DATA_DIR`.
+Each file contains one JSON object per line, compressed with zstd. Files are
+created with `O_EXCL` to prevent overwrites.
+
+## TODO
+
+- Add integration test that POSTs a report and verifies the compressed output
+- Add report decompression/query endpoint
+- Add metrics (Prometheus) for buffer size, flush count, report count
+- Add retention policy to prune old report files
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Author
+
+[@sneak](https://sneak.berlin)

backend/cmd/netwatch-server/main.go

@@ -0,0 +1,42 @@
+// Package main is the entry point for netwatch-server.
+package main
+
+import (
+	"sneak.berlin/go/netwatch/internal/config"
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/handlers"
+	"sneak.berlin/go/netwatch/internal/healthcheck"
+	"sneak.berlin/go/netwatch/internal/logger"
+	"sneak.berlin/go/netwatch/internal/middleware"
+	"sneak.berlin/go/netwatch/internal/reportbuf"
+	"sneak.berlin/go/netwatch/internal/server"
+
+	"go.uber.org/fx"
+)
+
+//nolint:gochecknoglobals // set via ldflags at build time
+var (
+	Appname   = "netwatch-server"
+	Version   string
+	Buildarch string
+)
+
+func main() {
+	globals.Appname = Appname
+	globals.Version = Version
+	globals.Buildarch = Buildarch
+
+	fx.New(
+		fx.Provide(
+			config.New,
+			globals.New,
+			handlers.New,
+			healthcheck.New,
+			logger.New,
+			middleware.New,
+			reportbuf.New,
+			server.New,
+		),
+		fx.Invoke(func(*server.Server) {}),
+	).Run()
+}

backend/go.mod

@@ -0,0 +1,30 @@
+module sneak.berlin/go/netwatch
+
+go 1.25.5
+
+require (
+	github.com/go-chi/chi/v5 v5.2.5
+	github.com/go-chi/cors v1.2.2
+	github.com/joho/godotenv v1.5.1
+	github.com/klauspost/compress v1.18.4
+	github.com/spf13/viper v1.21.0
+	go.uber.org/fx v1.24.0
+)
+
+require (
+	github.com/fsnotify/fsnotify v1.9.0 // indirect
+	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
+	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
+	github.com/sagikazarmark/locafero v0.11.0 // indirect
+	github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 // indirect
+	github.com/spf13/afero v1.15.0 // indirect
+	github.com/spf13/cast v1.10.0 // indirect
+	github.com/spf13/pflag v1.0.10 // indirect
+	github.com/subosito/gotenv v1.6.0 // indirect
+	go.uber.org/dig v1.19.0 // indirect
+	go.uber.org/multierr v1.10.0 // indirect
+	go.uber.org/zap v1.26.0 // indirect
+	go.yaml.in/yaml/v3 v3.0.4 // indirect
+	golang.org/x/sys v0.29.0 // indirect
+	golang.org/x/text v0.28.0 // indirect
+)

backend/go.sum

@@ -0,0 +1,65 @@
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
+github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
+github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
+github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
+github.com/go-chi/chi/v5 v5.2.5 h1:Eg4myHZBjyvJmAFjFvWgrqDTXFyOzjj7YIm3L3mu6Ug=
+github.com/go-chi/chi/v5 v5.2.5/go.mod h1:X7Gx4mteadT3eDOMTsXzmI4/rwUpOwBHLpAfupzFJP0=
+github.com/go-chi/cors v1.2.2 h1:Jmey33TE+b+rB7fT8MUy1u0I4L+NARQlK6LhzKPSyQE=
+github.com/go-chi/cors v1.2.2/go.mod h1:sSbTewc+6wYHBBCW7ytsFSn836hqM7JxpglAy2Vzc58=
+github.com/go-viper/mapstructure/v2 v2.4.0 h1:EBsztssimR/CONLSZZ04E8qAkxNYq4Qp9LvH92wZUgs=
+github.com/go-viper/mapstructure/v2 v2.4.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
+github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
+github.com/klauspost/compress v1.18.4 h1:RPhnKRAQ4Fh8zU2FY/6ZFDwTVTxgJ/EMydqSTzE9a2c=
+github.com/klauspost/compress v1.18.4/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
+github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
+github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+github.com/sagikazarmark/locafero v0.11.0 h1:1iurJgmM9G3PA/I+wWYIOw/5SyBtxapeHDcg+AAIFXc=
+github.com/sagikazarmark/locafero v0.11.0/go.mod h1:nVIGvgyzw595SUSUE6tvCp3YYTeHs15MvlmU87WwIik=
+github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 h1:+jumHNA0Wrelhe64i8F6HNlS8pkoyMv5sreGx2Ry5Rw=
+github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8/go.mod h1:3n1Cwaq1E1/1lhQhtRK2ts/ZwZEhjcQeJQ1RuC6Q/8U=
+github.com/spf13/afero v1.15.0 h1:b/YBCLWAJdFWJTN9cLhiXXcD7mzKn9Dm86dNnfyQw1I=
+github.com/spf13/afero v1.15.0/go.mod h1:NC2ByUVxtQs4b3sIUphxK0NioZnmxgyCrfzeuq8lxMg=
+github.com/spf13/cast v1.10.0 h1:h2x0u2shc1QuLHfxi+cTJvs30+ZAHOGRic8uyGTDWxY=
+github.com/spf13/cast v1.10.0/go.mod h1:jNfB8QC9IA6ZuY2ZjDp0KtFO2LZZlg4S/7bzP6qqeHo=
+github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
+github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/spf13/viper v1.21.0 h1:x5S+0EU27Lbphp4UKm1C+1oQO+rKx36vfCoaVebLFSU=
+github.com/spf13/viper v1.21.0/go.mod h1:P0lhsswPGWD/1lZJ9ny3fYnVqxiegrlNrEmgLjbTCAY=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
+github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
+go.uber.org/dig v1.19.0 h1:BACLhebsYdpQ7IROQ1AGPjrXcP5dF80U3gKoFzbaq/4=
+go.uber.org/dig v1.19.0/go.mod h1:Us0rSJiThwCv2GteUN0Q7OKvU7n5J4dxZ9JKUXozFdE=
+go.uber.org/fx v1.24.0 h1:wE8mruvpg2kiiL1Vqd0CC+tr0/24XIB10Iwp2lLWzkg=
+go.uber.org/fx v1.24.0/go.mod h1:AmDeGyS+ZARGKM4tlH4FY2Jr63VjbEDJHtqXTGP5hbo=
+go.uber.org/goleak v1.2.0 h1:xqgm/S+aQvhWFTtR0XK3Jvg7z8kGV8P4X14IzwN3Eqk=
+go.uber.org/goleak v1.2.0/go.mod h1:XJYK+MuIchqpmGmUSAzotztawfKvYLUIgg7guXrwVUo=
+go.uber.org/multierr v1.10.0 h1:S0h4aNzvfcFsC3dRF1jLoaov7oRaKqRGC/pUEJ2yvPQ=
+go.uber.org/multierr v1.10.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
+go.uber.org/zap v1.26.0 h1:sI7k6L95XOKS281NhVKOFCUNIvv9e0w4BF8N3u+tCRo=
+go.uber.org/zap v1.26.0/go.mod h1:dtElttAiwGvoJ/vj4IwHBS/gXsEu/pZ50mUIRWuG0so=
+go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+golang.org/x/sys v0.29.0 h1:TPYlXGxvx1MGTn2GiZDhnjPA9wZzZeGKHHmKhHYvgaU=
+golang.org/x/sys v0.29.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/text v0.28.0 h1:rhazDwis8INMIwQ4tpjLDzUhx6RlXqZNPEM0huQojng=
+golang.org/x/text v0.28.0/go.mod h1:U8nCwOR8jO/marOQ0QbDiOngZVEBB7MAiitBuMjXiNU=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 h1:YR8cESwS4TdDjEe65xsg0ogRM/Nc3DYOhEAlW+xobZo=
+gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

backend/internal/config/config.go

@@ -0,0 +1,86 @@
+// Package config loads application configuration from
+// environment variables, .env files, and config files.
+package config
+
+import (
+	"errors"
+	"log/slog"
+
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/logger"
+
+	_ "github.com/joho/godotenv/autoload" // loads .env file
+	"github.com/spf13/viper"
+	"go.uber.org/fx"
+)
+
+// Params defines the dependencies for Config.
+type Params struct {
+	fx.In
+
+	Globals *globals.Globals
+	Logger  *logger.Logger
+}
+
+// Config holds the resolved application configuration.
+type Config struct {
+	DataDir         string
+	Debug           bool
+	MetricsPassword string
+	MetricsUsername string
+	Port            int
+	SentryDSN       string
+	log             *slog.Logger
+	params          *Params
+}
+
+// New loads configuration from env, .env files, and config
+// files, returning a fully resolved Config.
+func New(
+	_ fx.Lifecycle,
+	params Params,
+) (*Config, error) {
+	log := params.Logger.Get()
+	name := params.Globals.Appname
+
+	viper.SetConfigName(name)
+	viper.SetConfigType("yaml")
+	viper.AddConfigPath("/etc/" + name)
+	viper.AddConfigPath("$HOME/.config/" + name)
+
+	viper.AutomaticEnv()
+
+	viper.SetDefault("DATA_DIR", "./data/reports")
+	viper.SetDefault("DEBUG", "false")
+	viper.SetDefault("PORT", "8080")
+	viper.SetDefault("SENTRY_DSN", "")
+	viper.SetDefault("METRICS_USERNAME", "")
+	viper.SetDefault("METRICS_PASSWORD", "")
+
+	err := viper.ReadInConfig()
+	if err != nil {
+		var notFound viper.ConfigFileNotFoundError
+		if !errors.As(err, &notFound) {
+			log.Error("config file malformed", "error", err)
+			panic(err)
+		}
+	}
+
+	s := &Config{
+		DataDir:         viper.GetString("DATA_DIR"),
+		Debug:           viper.GetBool("DEBUG"),
+		MetricsPassword: viper.GetString("METRICS_PASSWORD"),
+		MetricsUsername: viper.GetString("METRICS_USERNAME"),
+		Port:            viper.GetInt("PORT"),
+		SentryDSN:       viper.GetString("SENTRY_DSN"),
+		log:             log,
+		params:          &params,
+	}
+
+	if s.Debug {
+		params.Logger.EnableDebugLogging()
+		s.log = params.Logger.Get()
+	}
+
+	return s, nil
+}

backend/internal/globals/globals.go

@@ -0,0 +1,31 @@
+// Package globals provides build-time variables injected via
+// ldflags and made available through dependency injection.
+package globals
+
+import "go.uber.org/fx"
+
+//nolint:gochecknoglobals // set from main before fx starts
+var (
+	// Appname is the application name.
+	Appname string
+	// Version is the git version tag.
+	Version string
+	// Buildarch is the build architecture.
+	Buildarch string
+)
+
+// Globals holds build-time metadata for the application.
+type Globals struct {
+	Appname   string
+	Version   string
+	Buildarch string
+}
+
+// New creates a Globals instance from package-level variables.
+func New(_ fx.Lifecycle) (*Globals, error) {
+	return &Globals{
+		Appname:   Appname,
+		Buildarch: Buildarch,
+		Version:   Version,
+	}, nil
+}

backend/internal/handlers/handlers.go

@@ -0,0 +1,74 @@
+// Package handlers implements HTTP request handlers for the
+// netwatch-server API.
+package handlers
+
+import (
+	"context"
+	"encoding/json"
+	"log/slog"
+	"net/http"
+
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/healthcheck"
+	"sneak.berlin/go/netwatch/internal/logger"
+	"sneak.berlin/go/netwatch/internal/reportbuf"
+
+	"go.uber.org/fx"
+)
+
+const jsonContentType = "application/json; charset=utf-8"
+
+// Params defines the dependencies for Handlers.
+type Params struct {
+	fx.In
+
+	Buffer      *reportbuf.Buffer
+	Globals     *globals.Globals
+	Healthcheck *healthcheck.Healthcheck
+	Logger      *logger.Logger
+}
+
+// Handlers provides HTTP handler factories for all endpoints.
+type Handlers struct {
+	buf    *reportbuf.Buffer
+	hc     *healthcheck.Healthcheck
+	log    *slog.Logger
+	params *Params
+}
+
+// New creates a Handlers instance.
+func New(
+	lc fx.Lifecycle,
+	params Params,
+) (*Handlers, error) {
+	s := new(Handlers)
+	s.buf = params.Buffer
+	s.params = &params
+	s.log = params.Logger.Get()
+	s.hc = params.Healthcheck
+
+	lc.Append(fx.Hook{
+		OnStart: func(_ context.Context) error {
+			return nil
+		},
+	})
+
+	return s, nil
+}
+
+func (s *Handlers) respondJSON(
+	w http.ResponseWriter,
+	_ *http.Request,
+	data any,
+	status int,
+) {
+	w.Header().Set("Content-Type", jsonContentType)
+	w.WriteHeader(status)
+
+	if data != nil {
+		err := json.NewEncoder(w).Encode(data)
+		if err != nil {
+			s.log.Error("json encode error", "error", err)
+		}
+	}
+}

backend/internal/handlers/handlers_test.go

@@ -0,0 +1,13 @@
+package handlers_test
+
+import (
+	"testing"
+
+	_ "sneak.berlin/go/netwatch/internal/handlers"
+)
+
+func TestImport(t *testing.T) {
+	t.Parallel()
+	// Compilation check — verifies the package parses
+	// and all imports resolve.
+}

backend/internal/handlers/healthcheck.go

@@ -0,0 +1,11 @@
+package handlers
+
+import "net/http"
+
+// HandleHealthCheck returns a handler for the health check
+// endpoint.
+func (s *Handlers) HandleHealthCheck() http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		s.respondJSON(w, r, s.hc.Check(), http.StatusOK)
+	}
+}

backend/internal/handlers/report.go

@@ -0,0 +1,82 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+)
+
+const maxReportBodyBytes = 1 << 20 // 1 MiB
+
+type reportSample struct {
+	T       int64   `json:"t"`
+	Latency *int    `json:"latency"`
+	Error   *string `json:"error"`
+}
+
+type reportHost struct {
+	History []reportSample `json:"history"`
+	Name    string         `json:"name"`
+	Status  string         `json:"status"`
+	URL     string         `json:"url"`
+}
+
+type report struct {
+	ClientID  string          `json:"clientId"`
+	Geo       json.RawMessage `json:"geo"`
+	Hosts     []reportHost    `json:"hosts"`
+	Timestamp string          `json:"timestamp"`
+}
+
+// HandleReport returns a handler that accepts telemetry
+// reports from NetWatch clients.
+func (s *Handlers) HandleReport() http.HandlerFunc {
+	type response struct {
+		Status string `json:"status"`
+	}
+
+	return func(w http.ResponseWriter, r *http.Request) {
+		r.Body = http.MaxBytesReader(
+			w, r.Body, maxReportBodyBytes,
+		)
+
+		var rpt report
+
+		err := json.NewDecoder(r.Body).Decode(&rpt)
+		if err != nil {
+			s.log.Error("failed to decode report",
+				"error", err,
+			)
+			s.respondJSON(w, r,
+				&response{Status: "error"},
+				http.StatusBadRequest,
+			)
+
+			return
+		}
+
+		totalSamples := 0
+		for _, h := range rpt.Hosts {
+			totalSamples += len(h.History)
+		}
+
+		s.log.Info("report received",
+			"client_id", rpt.ClientID,
+			"timestamp", rpt.Timestamp,
+			"host_count", len(rpt.Hosts),
+			"total_samples", totalSamples,
+			"geo", string(rpt.Geo),
+		)
+
+		bufErr := s.buf.Append(rpt)
+		if bufErr != nil {
+			s.log.Error("failed to buffer report",
+				"error", bufErr,
+			)
+		}
+
+		s.respondJSON(w, r,
+			&response{Status: "ok"},
+			http.StatusOK,
+		)
+	}
+}

backend/internal/healthcheck/healthcheck.go

@@ -0,0 +1,82 @@
+// Package healthcheck provides a service that reports
+// application health, uptime, and version information.
+package healthcheck
+
+import (
+	"context"
+	"log/slog"
+	"time"
+
+	"sneak.berlin/go/netwatch/internal/config"
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/logger"
+
+	"go.uber.org/fx"
+)
+
+// Params defines the dependencies for Healthcheck.
+type Params struct {
+	fx.In
+
+	Config  *config.Config
+	Globals *globals.Globals
+	Logger  *logger.Logger
+}
+
+// Healthcheck tracks startup time and builds health responses.
+type Healthcheck struct {
+	StartupTime time.Time
+	log         *slog.Logger
+	params      *Params
+}
+
+// Response is the JSON payload returned by the health check
+// endpoint.
+type Response struct {
+	Appname       string `json:"appname"`
+	Now           string `json:"now"`
+	Status        string `json:"status"`
+	UptimeHuman   string `json:"uptimeHuman"`
+	UptimeSeconds int64  `json:"uptimeSeconds"`
+	Version       string `json:"version"`
+}
+
+// New creates a Healthcheck, recording startup time via an
+// fx lifecycle hook.
+func New(
+	lc fx.Lifecycle,
+	params Params,
+) (*Healthcheck, error) {
+	s := new(Healthcheck)
+	s.params = &params
+	s.log = params.Logger.Get()
+
+	lc.Append(fx.Hook{
+		OnStart: func(_ context.Context) error {
+			s.StartupTime = time.Now().UTC()
+
+			return nil
+		},
+		OnStop: func(_ context.Context) error {
+			return nil
+		},
+	})
+
+	return s, nil
+}
+
+// Check returns the current health status of the application.
+func (s *Healthcheck) Check() *Response {
+	return &Response{
+		Appname:       s.params.Globals.Appname,
+		Now:           time.Now().UTC().Format(time.RFC3339Nano),
+		Status:        "ok",
+		UptimeHuman:   s.uptime().String(),
+		UptimeSeconds: int64(s.uptime().Seconds()),
+		Version:       s.params.Globals.Version,
+	}
+}
+
+func (s *Healthcheck) uptime() time.Duration {
+	return time.Since(s.StartupTime)
+}

backend/internal/logger/logger.go

@@ -0,0 +1,85 @@
+// Package logger provides a configured slog.Logger with TTY
+// detection for development vs production output.
+package logger
+
+import (
+	"log/slog"
+	"os"
+
+	"sneak.berlin/go/netwatch/internal/globals"
+
+	"go.uber.org/fx"
+)
+
+// Params defines the dependencies for Logger.
+type Params struct {
+	fx.In
+
+	Globals *globals.Globals
+}
+
+// Logger wraps slog.Logger with dynamic level control.
+type Logger struct {
+	log    *slog.Logger
+	level  *slog.LevelVar
+	params Params
+}
+
+// New creates a Logger with TTY-aware output formatting.
+func New(_ fx.Lifecycle, params Params) (*Logger, error) {
+	l := new(Logger)
+	l.level = new(slog.LevelVar)
+	l.level.Set(slog.LevelInfo)
+	l.params = params
+
+	tty := false
+
+	if fileInfo, _ := os.Stdout.Stat(); fileInfo != nil {
+		if (fileInfo.Mode() & os.ModeCharDevice) != 0 {
+			tty = true
+		}
+	}
+
+	var handler slog.Handler
+	if tty {
+		handler = slog.NewTextHandler(
+			os.Stdout,
+			&slog.HandlerOptions{
+				Level:     l.level,
+				AddSource: true,
+			},
+		)
+	} else {
+		handler = slog.NewJSONHandler(
+			os.Stdout,
+			&slog.HandlerOptions{
+				Level:     l.level,
+				AddSource: true,
+			},
+		)
+	}
+
+	l.log = slog.New(handler)
+
+	return l, nil
+}
+
+// EnableDebugLogging sets the log level to debug.
+func (l *Logger) EnableDebugLogging() {
+	l.level.Set(slog.LevelDebug)
+	l.log.Debug("debug logging enabled", "debug", true)
+}
+
+// Get returns the underlying slog.Logger.
+func (l *Logger) Get() *slog.Logger {
+	return l.log
+}
+
+// Identify logs the application's build-time metadata.
+func (l *Logger) Identify() {
+	l.log.Info("starting",
+		"appname", l.params.Globals.Appname,
+		"version", l.params.Globals.Version,
+		"buildarch", l.params.Globals.Buildarch,
+	)
+}

backend/internal/middleware/middleware.go

@@ -0,0 +1,129 @@
+// Package middleware provides HTTP middleware for logging,
+// CORS, and other cross-cutting concerns.
+package middleware
+
+import (
+	"log/slog"
+	"net"
+	"net/http"
+	"time"
+
+	"sneak.berlin/go/netwatch/internal/config"
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/logger"
+
+	"github.com/go-chi/chi/v5/middleware"
+	"github.com/go-chi/cors"
+	"go.uber.org/fx"
+)
+
+const corsMaxAgeSec = 300
+
+// Params defines the dependencies for Middleware.
+type Params struct {
+	fx.In
+
+	Config  *config.Config
+	Globals *globals.Globals
+	Logger  *logger.Logger
+}
+
+// Middleware holds shared state for middleware factories.
+type Middleware struct {
+	log    *slog.Logger
+	params *Params
+}
+
+// New creates a Middleware instance.
+func New(
+	_ fx.Lifecycle,
+	params Params,
+) (*Middleware, error) {
+	s := new(Middleware)
+	s.params = &params
+	s.log = params.Logger.Get()
+
+	return s, nil
+}
+
+type loggingResponseWriter struct {
+	http.ResponseWriter
+
+	statusCode int
+}
+
+func newLoggingResponseWriter(
+	w http.ResponseWriter,
+) *loggingResponseWriter {
+	return &loggingResponseWriter{w, http.StatusOK}
+}
+
+func (lrw *loggingResponseWriter) WriteHeader(code int) {
+	lrw.statusCode = code
+	lrw.ResponseWriter.WriteHeader(code)
+}
+
+func ipFromHostPort(hostPort string) string {
+	host, _, err := net.SplitHostPort(hostPort)
+	if err != nil {
+		return hostPort
+	}
+
+	return host
+}
+
+// Logging returns middleware that logs each request with
+// timing, status code, and client information.
+func (s *Middleware) Logging() func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(
+			func(w http.ResponseWriter, r *http.Request) {
+				start := time.Now().UTC()
+				lrw := newLoggingResponseWriter(w)
+				ctx := r.Context()
+
+				defer func() {
+					latency := time.Since(start)
+					s.log.InfoContext(ctx, "request",
+						"request_start", start,
+						"method", r.Method,
+						"url", r.URL.String(),
+						"useragent", r.UserAgent(),
+						"request_id",
+						ctx.Value(
+							middleware.RequestIDKey,
+						),
+						"referer", r.Referer(),
+						"proto", r.Proto,
+						"remote_ip",
+						ipFromHostPort(r.RemoteAddr),
+						"status", lrw.statusCode,
+						"latency_ms",
+						latency.Milliseconds(),
+					)
+				}()
+
+				next.ServeHTTP(lrw, r)
+			},
+		)
+	}
+}
+
+// CORS returns middleware that adds permissive CORS headers.
+func (s *Middleware) CORS() func(http.Handler) http.Handler {
+	return cors.Handler(cors.Options{
+		AllowedOrigins: []string{"*"},
+		AllowedMethods: []string{
+			"GET", "POST", "PUT", "DELETE", "OPTIONS",
+		},
+		AllowedHeaders: []string{
+			"Accept",
+			"Authorization",
+			"Content-Type",
+			"X-CSRF-Token",
+		},
+		ExposedHeaders:   []string{"Link"},
+		AllowCredentials: false,
+		MaxAge:           corsMaxAgeSec,
+	})
+}

backend/internal/reportbuf/reportbuf.go

@@ -0,0 +1,199 @@
+// Package reportbuf accumulates telemetry reports in memory
+// and periodically flushes them to zstd-compressed JSONL files.
+package reportbuf
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io/fs"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+
+	"sneak.berlin/go/netwatch/internal/config"
+	"sneak.berlin/go/netwatch/internal/logger"
+
+	"github.com/klauspost/compress/zstd"
+	"go.uber.org/fx"
+)
+
+const (
+	flushSizeThreshold             = 10 << 20 // 10 MiB
+	flushInterval                  = 1 * time.Minute
+	defaultDataDir                 = "./data/reports"
+	dirPerms           fs.FileMode = 0o750
+	filePerms          fs.FileMode = 0o640
+)
+
+// Params defines the dependencies for Buffer.
+type Params struct {
+	fx.In
+
+	Config *config.Config
+	Logger *logger.Logger
+}
+
+// Buffer accumulates JSON lines in memory and flushes them
+// to zstd-compressed files on disk.
+type Buffer struct {
+	buf     bytes.Buffer
+	dataDir string
+	done    chan struct{}
+	log     *slog.Logger
+	mu      sync.Mutex
+}
+
+// New creates a Buffer and registers lifecycle hooks to
+// manage the data directory and flush goroutine.
+func New(
+	lc fx.Lifecycle,
+	params Params,
+) (*Buffer, error) {
+	dir := params.Config.DataDir
+	if dir == "" {
+		dir = defaultDataDir
+	}
+
+	b := &Buffer{
+		dataDir: dir,
+		done:    make(chan struct{}),
+		log:     params.Logger.Get(),
+	}
+
+	lc.Append(fx.Hook{
+		OnStart: func(_ context.Context) error {
+			err := os.MkdirAll(b.dataDir, dirPerms)
+			if err != nil {
+				return fmt.Errorf("create data dir: %w", err)
+			}
+
+			go b.flushLoop()
+
+			return nil
+		},
+		OnStop: func(_ context.Context) error {
+			close(b.done)
+			b.flushLocked()
+
+			return nil
+		},
+	})
+
+	return b, nil
+}
+
+// Append marshals v as a single JSON line and appends it to
+// the buffer. If the buffer reaches the size threshold, it is
+// drained and written to disk asynchronously.
+func (b *Buffer) Append(v any) error {
+	line, err := json.Marshal(v)
+	if err != nil {
+		return fmt.Errorf("marshal report: %w", err)
+	}
+
+	b.mu.Lock()
+	b.buf.Write(line)
+	b.buf.WriteByte('\n')
+
+	if b.buf.Len() >= flushSizeThreshold {
+		data := b.drainBuf()
+		b.mu.Unlock()
+
+		go b.writeFile(data)
+
+		return nil
+	}
+
+	b.mu.Unlock()
+
+	return nil
+}
+
+// flushLoop runs a ticker that periodically flushes buffered
+// data to disk until the done channel is closed.
+func (b *Buffer) flushLoop() {
+	ticker := time.NewTicker(flushInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ticker.C:
+			b.flushLocked()
+		case <-b.done:
+			return
+		}
+	}
+}
+
+// flushLocked acquires the lock, drains the buffer, and
+// writes the data to a compressed file.
+func (b *Buffer) flushLocked() {
+	b.mu.Lock()
+
+	if b.buf.Len() == 0 {
+		b.mu.Unlock()
+
+		return
+	}
+
+	data := b.drainBuf()
+	b.mu.Unlock()
+
+	b.writeFile(data)
+}
+
+// drainBuf copies the buffer contents and resets it.
+// The caller must hold b.mu.
+func (b *Buffer) drainBuf() []byte {
+	data := make([]byte, b.buf.Len())
+	copy(data, b.buf.Bytes())
+	b.buf.Reset()
+
+	return data
+}
+
+// writeFile creates a timestamped zstd-compressed JSONL file
+// in the data directory.
+func (b *Buffer) writeFile(data []byte) {
+	ts := time.Now().UTC().Format("2006-01-02T15-04-05.000Z")
+	name := fmt.Sprintf("reports-%s.jsonl.zst", ts)
+	path := filepath.Join(b.dataDir, name)
+
+	f, err := os.OpenFile( //nolint:gosec // path built from controlled dataDir + timestamp
+		path,
+		os.O_WRONLY|os.O_CREATE|os.O_EXCL,
+		filePerms,
+	)
+	if err != nil {
+		b.log.Error("create report file", "error", err)
+
+		return
+	}
+
+	defer func() { _ = f.Close() }()
+
+	enc, err := zstd.NewWriter(f)
+	if err != nil {
+		b.log.Error("create zstd encoder", "error", err)
+
+		return
+	}
+
+	_, writeErr := enc.Write(data)
+	if writeErr != nil {
+		b.log.Error("write compressed data", "error", writeErr)
+
+		_ = enc.Close()
+
+		return
+	}
+
+	closeErr := enc.Close()
+	if closeErr != nil {
+		b.log.Error("close zstd encoder", "error", closeErr)
+	}
+}

backend/internal/reportbuf/reportbuf_test.go

@@ -0,0 +1,13 @@
+package reportbuf_test
+
+import (
+	"testing"
+
+	_ "sneak.berlin/go/netwatch/internal/reportbuf"
+)
+
+func TestImport(t *testing.T) {
+	t.Parallel()
+	// Compilation check — verifies the package parses
+	// and all imports resolve.
+}

backend/internal/server/http.go

@@ -0,0 +1,43 @@
+package server
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+	"time"
+)
+
+const (
+	readTimeout    = 10 * time.Second
+	writeTimeout   = 10 * time.Second
+	maxHeaderBytes = 1 << 20 // 1 MiB
+)
+
+func (s *Server) serveUntilShutdown() {
+	listenAddr := fmt.Sprintf(":%d", s.params.Config.Port)
+
+	s.httpServer = &http.Server{
+		Addr:           listenAddr,
+		Handler:        s,
+		MaxHeaderBytes: maxHeaderBytes,
+		ReadTimeout:    readTimeout,
+		WriteTimeout:   writeTimeout,
+	}
+
+	s.SetupRoutes()
+
+	s.log.Info("http begin listen",
+		"listenaddr", listenAddr,
+		"version", s.params.Globals.Version,
+		"buildarch", s.params.Globals.Buildarch,
+	)
+
+	err := s.httpServer.ListenAndServe()
+	if err != nil && !errors.Is(err, http.ErrServerClosed) {
+		s.log.Error("listen error", "error", err)
+
+		if s.cancelFunc != nil {
+			s.cancelFunc()
+		}
+	}
+}

backend/internal/server/routes.go

@@ -0,0 +1,31 @@
+package server
+
+import (
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/go-chi/chi/v5/middleware"
+)
+
+const requestTimeout = 60 * time.Second
+
+// SetupRoutes configures the chi router with middleware and
+// all application routes.
+func (s *Server) SetupRoutes() {
+	s.router = chi.NewRouter()
+
+	s.router.Use(middleware.Recoverer)
+	s.router.Use(middleware.RequestID)
+	s.router.Use(s.mw.Logging())
+	s.router.Use(s.mw.CORS())
+	s.router.Use(middleware.Timeout(requestTimeout))
+
+	s.router.Get(
+		"/.well-known/healthcheck",
+		s.h.HandleHealthCheck(),
+	)
+
+	s.router.Route("/api/v1", func(r chi.Router) {
+		r.Post("/reports", s.h.HandleReport())
+	})
+}

backend/internal/server/server.go

@@ -0,0 +1,147 @@
+// Package server provides the HTTP server lifecycle,
+// including startup, routing, signal handling, and graceful
+// shutdown.
+package server
+
+import (
+	"context"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"sneak.berlin/go/netwatch/internal/config"
+	"sneak.berlin/go/netwatch/internal/globals"
+	"sneak.berlin/go/netwatch/internal/handlers"
+	"sneak.berlin/go/netwatch/internal/logger"
+	"sneak.berlin/go/netwatch/internal/middleware"
+
+	"github.com/go-chi/chi/v5"
+	"go.uber.org/fx"
+)
+
+// Params defines the dependencies for Server.
+type Params struct {
+	fx.In
+
+	Config     *config.Config
+	Globals    *globals.Globals
+	Handlers   *handlers.Handlers
+	Logger     *logger.Logger
+	Middleware *middleware.Middleware
+}
+
+// Server is the top-level HTTP server orchestrator.
+type Server struct {
+	cancelFunc  context.CancelFunc
+	exitCode    int
+	h           *handlers.Handlers
+	httpServer  *http.Server
+	log         *slog.Logger
+	mw          *middleware.Middleware
+	params      Params
+	router      *chi.Mux
+	startupTime time.Time
+}
+
+// New creates a Server and registers lifecycle hooks for
+// starting and stopping it.
+func New(
+	lc fx.Lifecycle,
+	params Params,
+) (*Server, error) {
+	s := new(Server)
+	s.params = params
+	s.mw = params.Middleware
+	s.h = params.Handlers
+	s.log = params.Logger.Get()
+
+	lc.Append(fx.Hook{
+		OnStart: func(_ context.Context) error {
+			s.startupTime = time.Now().UTC()
+
+			go func() { //nolint:contextcheck // fx OnStart ctx is startup-only; run() creates its own
+				s.run()
+			}()
+
+			return nil
+		},
+		OnStop: func(_ context.Context) error {
+			if s.cancelFunc != nil {
+				s.cancelFunc()
+			}
+
+			return nil
+		},
+	})
+
+	return s, nil
+}
+
+// ServeHTTP delegates to the chi router.
+func (s *Server) ServeHTTP(
+	w http.ResponseWriter,
+	r *http.Request,
+) {
+	s.router.ServeHTTP(w, r)
+}
+
+func (s *Server) run() {
+	exitCode := s.serve()
+	os.Exit(exitCode)
+}
+
+func (s *Server) serve() int {
+	var ctx context.Context //nolint:wsl // ctx must be declared before multi-assign
+
+	ctx, s.cancelFunc = context.WithCancel(
+		context.Background(),
+	)
+
+	go func() {
+		c := make(chan os.Signal, 1)
+
+		signal.Ignore(syscall.SIGPIPE)
+		signal.Notify(c, os.Interrupt, syscall.SIGTERM)
+
+		sig := <-c
+		s.log.Info("signal received", "signal", sig)
+
+		if s.cancelFunc != nil {
+			s.cancelFunc()
+		}
+	}()
+
+	go func() {
+		s.serveUntilShutdown()
+	}()
+
+	<-ctx.Done()
+	s.cleanShutdown()
+
+	return s.exitCode
+}
+
+const shutdownTimeout = 5 * time.Second
+
+func (s *Server) cleanShutdown() {
+	s.exitCode = 0
+
+	ctxShutdown, shutdownCancel := context.WithTimeout(
+		context.Background(),
+		shutdownTimeout,
+	)
+	defer shutdownCancel()
+
+	err := s.httpServer.Shutdown(ctxShutdown)
+	if err != nil {
+		s.log.Error(
+			"server clean shutdown failed",
+			"error", err,
+		)
+	}
+
+	s.log.Info("server stopped")
+}

backend/script/build

@@ -0,0 +1,27 @@
+#!/bin/sh
+# script/build: compile the netwatch-server binary into the backend
+# project root. Version and architecture are stamped into the binary via
+# ldflags; on Linux the binary is statically linked.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+BINARY="netwatch-server"
+
+main() {
+    cd "$ROOT"
+
+    # git describe fails outside a working repo (e.g. a source tarball),
+    # which must not abort the build.
+    version="$(git describe --always --dirty 2>/dev/null || echo unknown)"
+    buildarch="$(uname -m)"
+
+    ldflags="-X main.Version=$version -X main.Buildarch=$buildarch"
+    if [ "$(uname -s)" != "Darwin" ]; then
+        ldflags="-linkmode external -extldflags -static $ldflags"
+    fi
+
+    go build -o "$BINARY" -ldflags "$ldflags" ./cmd/netwatch-server/
+}
+
+main "$@"

backend/script/check

@@ -0,0 +1,16 @@
+#!/bin/sh
+# script/check: run all backend checks (test, lint, fmt-check). Must not
+# modify any files. The root script/check calls this, so the repo-wide
+# gate covers the backend.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    "$ROOT/script/test"
+    "$ROOT/script/lint"
+    "$ROOT/script/fmt-check"
+}
+
+main "$@"

backend/script/clean

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/clean: remove build artifacts.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    rm -f netwatch-server
+}
+
+main "$@"

backend/script/fmt

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/fmt: format all Go sources in the backend (writes).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    go fmt ./...
+}
+
+main "$@"

backend/script/fmt-check

@@ -0,0 +1,18 @@
+#!/bin/sh
+# script/fmt-check: check Go formatting (read-only). Same scope as
+# script/fmt, but fails instead of writing.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    unformatted="$(gofmt -l .)"
+    if [ -n "$unformatted" ]; then
+        echo "Files not formatted:"
+        echo "$unformatted"
+        exit 1
+    fi
+}
+
+main "$@"

backend/script/lint

@@ -0,0 +1,56 @@
+#!/bin/sh
+# script/lint: run the Go linter over the backend.
+#
+# .golangci.yml is standardized org-wide and must never be edited here
+# (REPO_POLICIES.md). Its last silent drift replaced the v2 schema with
+# v1 keys, which left every threshold in the file inert while the build
+# stayed green. This script therefore asserts the file still matches the
+# pinned copy byte for byte before the linter runs. The check is a local
+# hash comparison: no network, no remote schema, nothing unpinned in the
+# build path.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+# sha256 of the pinned backend/.golangci.yml.
+#
+# PROVISIONAL. The hash below is the file currently on main, which is
+# the schema-invalid v1-keyed config described above: it is pinned only
+# so this branch and main stay green, NOT because it is canonical.
+#
+# The canonical org-wide .golangci.yml is
+# 021cc83f4e6fc7c31b95b34b846723dfcf20b66b7baeea1dc40406e643346bcb,
+# and PR #31 replaces backend/.golangci.yml with it. When #31 lands,
+# GOLANGCI_CONFIG_SHA256 must be updated to that hash in the same
+# commit. Until then, do not treat the pinned file as the standard.
+GOLANGCI_CONFIG_SHA256="33ba2bf7fe4a44779d09b0fb31d6daf03685f8dc9d2bc417f963d7aabb0d17dc"
+
+# sha256 <file>: print the file's sha256, coreutils or Darwin/busybox.
+sha256() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        sha256sum "$1" | cut -d' ' -f1
+    else
+        shasum -a 256 "$1" | cut -d' ' -f1
+    fi
+}
+
+check_config_hash() {
+    actual="$(sha256 .golangci.yml)"
+    if [ "$actual" != "$GOLANGCI_CONFIG_SHA256" ]; then
+        echo ".golangci.yml has drifted from the pinned config."
+        echo "  expected $GOLANGCI_CONFIG_SHA256"
+        echo "  actual   $actual"
+        echo "Restore it verbatim from sneak/prompts; do not edit it."
+        echo "Only update GOLANGCI_CONFIG_SHA256 in this script when the"
+        echo "pinned config is deliberately replaced with a new standard."
+        exit 1
+    fi
+}
+
+main() {
+    cd "$ROOT"
+    check_config_hash
+    golangci-lint run ./...
+}
+
+main "$@"

backend/script/run

@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/run: build and run netwatch-server locally.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    "$ROOT/script/build"
+    exec ./netwatch-server "$@"
+}
+
+main "$@"

backend/script/test

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/test: run the backend test suite.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    timeout 30 go test ./...
+}
+
+main "$@"

nginx.conf

@@ -0,0 +1,28 @@
+server {
+    listen 8080;
+    server_name _;
+
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # Trust RFC1918 reverse proxies for X-Forwarded-For
+    set_real_ip_from 10.0.0.0/8;
+    set_real_ip_from 172.16.0.0/12;
+    set_real_ip_from 192.168.0.0/16;
+    real_ip_header X-Forwarded-For;
+    real_ip_recursive on;
+
+    # Access log to stdout (Docker best practice)
+    access_log /dev/stdout combined;
+    error_log  /dev/stderr warn;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # Cache static assets aggressively
+    location /assets/ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+}

script/bootstrap

@@ -0,0 +1,606 @@
+#!/bin/sh
+# script/bootstrap: install all dependencies needed to build and develop
+# this repo. Idempotent: every install is guarded by a check so already
+# installed tools are skipped. Base tooling comes from nix, apt, brew,
+# or apk (detected in that order); assumes nothing is present. Node is
+# used directly if installed; otherwise it is installed at a pinned
+# version via nvm (installing nvm itself first, from a hash-verified
+# release archive, never curl | sh). Go is used directly only if its
+# version falls inside the pinned window described at GO_MAX_MINOR below
+# -- a newer Go is ignored, not preferred -- and golangci-lint is
+# installed at the exact pinned version; both come from hash-verified
+# official release archives, never an install script.
+#
+# The backend's toolchain is bootstrapped here because script/check runs
+# backend/script/test and backend/script/lint, so a machine that cannot
+# run go and golangci-lint cannot pass the repo-wide gate or the
+# pre-commit hook that script/setup installs.
+#
+# Anything installed outside the system package manager is symlinked
+# into ~/.local/bin, so a later `make check` in a plain shell finds it.
+# nvm only puts node on PATH for shells that source nvm.sh, which
+# neither make nor the git hook does.
+#
+# Three rules govern what this script is allowed to touch:
+#
+#   1. Everything it installs itself lands under $HOME, using $TMPDIR
+#      only for scratch downloads it then deletes. The one exception is
+#      the system package manager, which it shells out to for base
+#      tooling (see pkg_install) and which owns those paths already. A
+#      per-repo bootstrap has no business writing to /usr/local/bin, a
+#      Homebrew prefix, or any other system-wide location behind that
+#      package manager's back.
+#   2. It never replaces something it did not create. Only a symlink
+#      that already points into one of its own managed directories is
+#      overwritten; anything else is left alone and bootstrap exits
+#      non-zero telling you what to remove.
+#   3. It never reports success while the tools a later `make check`
+#      would pick up are not the ones it provisioned. If it cannot
+#      guarantee the pinned toolchain wins on your PATH, it exits
+#      non-zero rather than leaving you a green bootstrap and a broken
+#      gate.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+# The PATH as the caller had it, captured before ensure_bin_dir amends
+# it. verify_toolchain checks against this rather than against the PATH
+# this script builds for itself, so what it reports is what a later
+# `make check` in the user's own shell will actually resolve.
+ORIG_PATH="$PATH"
+
+# Pinned versions, 2026-07-07
+NODE_VERSION="22.17.0"
+NVM_VERSION="0.40.3"
+# sha256 of https://github.com/nvm-sh/nvm/archive/refs/tags/v0.40.3.tar.gz
+NVM_SHA256="5f4d6aaa04a177dc93c985e31dbc411ab6b8c6e1e21d8015dbc1372625fcd1d0"
+YARN_VERSION="1.22.22"
+
+# Go 1.25.7 (2026-08-09). This is the toolchain inside the pinned
+# golang:1.25-alpine builder of Dockerfile.backend, so a local build
+# uses the same compiler CI does.
+#
+# The Go pin is a compatibility constraint to match, not a floor to
+# clear. golangci-lint links go/types from the Go release it was built
+# with, and go/types refuses to load packages compiled by a newer Go:
+# with the pinned linter (built with go1.25.4) and a host Go 1.26,
+# `make check` dies with
+#
+#     panic: file requires newer Go version go1.26
+#            (application built with go1.25)
+#
+# So an already-installed go is reused only inside a window:
+# GO_MIN_VERSION is the floor from backend/go.mod, and GO_MAX_MINOR is
+# the major.minor of the Go the pinned golangci-lint was built with.
+# Anything outside that window is ignored and GO_VERSION is installed
+# instead. GO_MAX_MINOR is therefore coupled to GOLANGCI_LINT_VERSION
+# below and must be revisited whenever that pin moves; `golangci-lint
+# version` prints the "built with goX.Y.Z" it needs.
+GO_VERSION="1.25.7"
+GO_MIN_VERSION="1.25.5"
+GO_MAX_MINOR="1.25"
+
+# golangci-lint 2.7.2 (2026-08-09). MUST stay equal to the golangci-lint
+# pinned in Dockerfile.backend (currently commit
+# 9f61b0f53f80672872fced07b6874397c3ed197b, which is tag v2.7.2), so a
+# local `make lint` and CI's in-image `make check` report the same
+# findings.
+#
+# Reconciliation note: PR #31 moves Dockerfile.backend to golangci-lint
+# v2.12.2, commit c0d3ddc9cf3faa61a4e378e879ece580256d76e5. When that
+# lands, GOLANGCI_LINT_VERSION and every hash in golangci_lint_sha256()
+# below must be updated to the v2.12.2 release archives in the same
+# commit, or local and CI will disagree. GO_MAX_MINOR must move with
+# it, to the major.minor that release reports as "built with".
+GOLANGCI_LINT_VERSION="2.7.2"
+
+# Where hash-verified archives are unpacked. Version-scoped, so bumping
+# a pin installs alongside the old copy instead of half-overwriting it.
+# Filled in by main() from script/projectname. TOOLCHAIN is also the
+# ownership boundary used by link_bin: a symlink pointing inside it is
+# one this script created and may replace.
+TOOLCHAIN=""
+GO_DIR=""
+GOLANGCI_LINT_DIR=""
+
+PKGMGR=""
+SUDO=""
+APT_UPDATED=""
+BIN_DIR=""
+NODE_BIN=""
+
+detect_pkgmgr() {
+    [ -n "$PKGMGR" ] && return 0
+    if command -v nix-env >/dev/null 2>&1; then
+        PKGMGR="nix"
+    elif command -v apt-get >/dev/null 2>&1; then
+        PKGMGR="apt"
+    elif command -v brew >/dev/null 2>&1; then
+        PKGMGR="brew"
+    elif command -v apk >/dev/null 2>&1; then
+        PKGMGR="apk"
+    else
+        echo "bootstrap: no supported package manager (nix, apt, brew, apk)" >&2
+        exit 1
+    fi
+    if [ "$PKGMGR" = "apt" ]; then
+        export DEBIAN_FRONTEND=noninteractive
+        if [ "$(id -u)" != "0" ]; then
+            SUDO="sudo"
+        fi
+    fi
+}
+
+# pkg_install <nix-attr> <apt-pkg> <brew-formula> <apk-pkg>
+pkg_install() {
+    detect_pkgmgr
+    case "$PKGMGR" in
+        nix) nix-env -iA "nixpkgs.$1" ;;
+        apt)
+            if [ -z "$APT_UPDATED" ]; then
+                $SUDO env DEBIAN_FRONTEND=noninteractive apt-get update
+                APT_UPDATED=1
+            fi
+            $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y "$2"
+            ;;
+        brew) brew install "$3" ;;
+        apk) apk add --no-cache "$4" ;;
+    esac
+}
+
+missing() {
+    ! command -v "$1" >/dev/null 2>&1
+}
+
+# verify_sha256 <file> <expected-hash>
+verify_sha256() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        actual="$(sha256sum "$1" | cut -d' ' -f1)"
+    else
+        actual="$(shasum -a 256 "$1" | cut -d' ' -f1)"
+    fi
+    if [ "$actual" != "$2" ]; then
+        echo "bootstrap: sha256 mismatch for $1" >&2
+        echo "  expected: $2" >&2
+        echo "  actual:   $actual" >&2
+        exit 1
+    fi
+}
+
+# fetch_verified <url> <expected-hash> <dest>: download a release
+# archive and check it against a hash hardcoded in this script before
+# anything is unpacked or run. Never pipe a remote script to a shell.
+fetch_verified() {
+    if missing curl; then pkg_install curl curl curl curl; fi
+    curl -fsSL -o "$3" "$1"
+    verify_sha256 "$3" "$2"
+}
+
+# platform: <os>-<arch> as used in the Go and golangci-lint release
+# archive filenames.
+platform() {
+    plat_os="$(uname -s)"
+    plat_arch="$(uname -m)"
+    case "$plat_os" in
+        Linux) plat_os="linux" ;;
+        Darwin) plat_os="darwin" ;;
+        *)
+            echo "bootstrap: unsupported OS $plat_os" >&2
+            exit 1
+            ;;
+    esac
+    case "$plat_arch" in
+        x86_64 | amd64) plat_arch="amd64" ;;
+        aarch64 | arm64) plat_arch="arm64" ;;
+        *)
+            echo "bootstrap: unsupported architecture $plat_arch" >&2
+            exit 1
+            ;;
+    esac
+    echo "$plat_os-$plat_arch"
+}
+
+# ver_ge <have> <want>: succeed if dotted version <have> is at least
+# <want>, comparing up to three numeric components.
+ver_ge() {
+    awk -v have="$1" -v want="$2" '
+        BEGIN {
+            n = split(have, h, ".")
+            m = split(want, w, ".")
+            for (i = 1; i <= 3; i++) {
+                hv = (i <= n) ? h[i] + 0 : 0
+                wv = (i <= m) ? w[i] + 0 : 0
+                if (hv > wv) exit 0
+                if (hv < wv) exit 1
+            }
+            exit 0
+        }'
+}
+
+# ensure_bin_dir: the directory provisioned tools are linked into. It is
+# always ~/.local/bin: per-user, never a system-wide or package-manager
+# prefix. It is put at the front of PATH for the rest of this run, and
+# reported if the caller's own PATH did not already contain it.
+ensure_bin_dir() {
+    [ -n "$BIN_DIR" ] && return 0
+    BIN_DIR="$HOME/.local/bin"
+    mkdir -p "$BIN_DIR"
+    case "$PATH" in
+        "$BIN_DIR":*) ;;
+        *)
+            PATH="$BIN_DIR:$PATH"
+            export PATH
+            ;;
+    esac
+    case ":$ORIG_PATH:" in
+        *":$BIN_DIR:"*) ;;
+        *)
+            echo "bootstrap: add $BIN_DIR to the front of your PATH, e.g." >&2
+            echo "  export PATH=\"\$HOME/.local/bin:\$PATH\"" >&2
+            ;;
+    esac
+}
+
+# owned_path <path>: true when <path> lies inside a directory this
+# script provisions, i.e. a link to it is one this script created and
+# may replace. Everything else belongs to the user or to a package
+# manager and is never touched.
+owned_path() {
+    case "$1" in
+        "$TOOLCHAIN"/*) return 0 ;;
+        "$HOME"/.nvm/*) return 0 ;;
+        *) return 1 ;;
+    esac
+}
+
+# refuse_clobber <path> <what>: report that <path> is not ours and stop.
+refuse_clobber() {
+    echo "bootstrap: $1 already exists and $2." >&2
+    echo "  Refusing to replace something this script did not create." >&2
+    echo "  Remove or rename it and re-run bootstrap." >&2
+    exit 1
+}
+
+# link_bin <target> <name>: idempotently expose one provisioned binary
+# on PATH. Only an existing symlink into one of our own directories is
+# replaced; a regular file, a directory, or a symlink pointing anywhere
+# else is left intact and bootstrap fails.
+link_bin() {
+    ensure_bin_dir
+    link="$BIN_DIR/$2"
+    if [ -L "$link" ]; then
+        existing="$(readlink "$link")"
+        if ! owned_path "$existing"; then
+            refuse_clobber "$link" \
+                "is a symlink to $existing, outside this repo's toolchain"
+        fi
+    elif [ -e "$link" ]; then
+        refuse_clobber "$link" "is not a symlink"
+    fi
+    ln -sfn "$1" "$link"
+}
+
+# nvm is a bash script; run a command in a bash with nvm loaded
+nvm_sh() {
+    bash -c ". \"\$HOME/.nvm/nvm.sh\" && $*"
+}
+
+ensure_nvm() {
+    [ -s "$HOME/.nvm/nvm.sh" ] && return 0
+    # nvm prerequisites; nvm itself requires bash
+    if missing bash; then pkg_install bash bash bash bash; fi
+    if missing curl; then pkg_install curl curl curl curl; fi
+    if missing git; then pkg_install git git git git; fi
+    tmp="$(mktemp -d)"
+    fetch_verified \
+        "https://github.com/nvm-sh/nvm/archive/refs/tags/v${NVM_VERSION}.tar.gz" \
+        "$NVM_SHA256" "$tmp/nvm.tar.gz"
+    mkdir -p "$HOME/.nvm"
+    tar -xzf "$tmp/nvm.tar.gz" -C "$HOME/.nvm" --strip-components=1
+    rm -rf "$tmp"
+}
+
+ensure_node() {
+    if ! missing node; then return 0; fi
+    ensure_nvm
+    nvm_sh "nvm install $NODE_VERSION"
+    NODE_BIN="$HOME/.nvm/versions/node/v$NODE_VERSION/bin"
+    for nb in node npm npx corepack; do
+        if [ -e "$NODE_BIN/$nb" ]; then link_bin "$NODE_BIN/$nb" "$nb"; fi
+    done
+}
+
+# ensure_yarn: yarn comes from corepack. Left to itself, `corepack
+# enable` writes its shims next to the corepack binary it resolved, and
+# it writes four of them (yarn, yarnpkg, pnpm, pnpx), not the one asked
+# for. --install-directory keeps all four inside this repo's own
+# toolchain directory, and only yarn is then linked onto PATH. The
+# no-corepack fallback likewise installs into a per-user npm prefix
+# under the toolchain directory instead of npm's global one. Nothing
+# here writes outside $HOME.
+ensure_yarn() {
+    if ! missing yarn; then return 0; fi
+    yarn_bin="$TOOLCHAIN/corepack-shims"
+    mkdir -p "$yarn_bin"
+    if ! missing corepack; then
+        corepack enable --install-directory "$yarn_bin"
+        corepack prepare "yarn@$YARN_VERSION" --activate
+    elif [ -s "$HOME/.nvm/nvm.sh" ]; then
+        nvm_sh "nvm use $NODE_VERSION >/dev/null && \
+            corepack enable --install-directory \"$yarn_bin\" && \
+            corepack prepare yarn@$YARN_VERSION --activate"
+    else
+        yarn_bin="$TOOLCHAIN/npm-global/bin"
+        npm install -g --prefix "$TOOLCHAIN/npm-global" "yarn@$YARN_VERSION"
+    fi
+    if [ -e "$yarn_bin/yarn" ]; then
+        link_bin "$yarn_bin/yarn" yarn
+    fi
+}
+
+install_js_deps() {
+    if missing yarn && [ -s "$HOME/.nvm/nvm.sh" ]; then
+        nvm_sh "nvm use $NODE_VERSION >/dev/null && cd \"$ROOT\" && \
+            yarn install --frozen-lockfile"
+    else
+        yarn install --frozen-lockfile
+    fi
+}
+
+# go_sha256 <platform>: sha256 of
+# https://go.dev/dl/go1.25.7.<platform>.tar.gz, from the signed release
+# index at https://go.dev/dl/?mode=json (2026-08-09).
+go_sha256() {
+    case "$1" in
+        linux-amd64)
+            echo "12e6d6a191091ae27dc31f6efc630e3a3b8ba409baf3573d955b196fdf086005"
+            ;;
+        linux-arm64)
+            echo "ba611a53534135a81067240eff9508cd7e256c560edd5d8c2fef54f083c07129"
+            ;;
+        darwin-amd64)
+            echo "bf5050a2152f4053837b886e8d9640c829dbacbc3370f913351eb0904cb706f5"
+            ;;
+        darwin-arm64)
+            echo "ff18369ffad05c57d5bed888b660b31385f3c913670a83ef557cdfd98ea9ae1b"
+            ;;
+        *)
+            echo "bootstrap: no pinned Go archive hash for $1" >&2
+            exit 1
+            ;;
+    esac
+}
+
+# go_ok: an already-installed go is acceptable only inside the window
+# described at GO_MAX_MINOR: at least GO_MIN_VERSION, and no newer in
+# major.minor than the Go the pinned golangci-lint was built with. A
+# newer host Go is not "good enough", it makes `make check` panic, so it
+# is treated exactly like a missing one.
+go_ok() {
+    if missing go; then return 1; fi
+    have="$(go version 2>/dev/null | awk '{print $3}')"
+    have="${have#go}"
+    [ -n "$have" ] || return 1
+    ver_ge "$have" "$GO_MIN_VERSION" || return 1
+    ver_ge "$GO_MAX_MINOR" "$(echo "$have" | cut -d. -f1,2)"
+}
+
+# gofmt_ok: gofmt is a gate tool -- backend/script/fmt-check runs it --
+# and its output is not guaranteed byte-identical across Go releases, so
+# a gofmt from a different release than the go that compiles the code is
+# treated exactly like a missing one, the same way a mismatched
+# golangci-lint is. `go version <file>` prints the toolchain a Go binary
+# was built with, so this compares the gofmt that resolves on PATH
+# against the go that resolves on PATH, without depending on where
+# either one lives. Anything it cannot read -- no go to ask, gofmt
+# absent, not a Go binary -- fails closed.
+gofmt_ok() {
+    if missing go; then return 1; fi
+    if missing gofmt; then return 1; fi
+    go_have="$(go version 2>/dev/null | awk '{print $3}')"
+    [ -n "$go_have" ] || return 1
+    fmt_have="$(go version "$(command -v gofmt)" 2>/dev/null | awk '{print $NF}')"
+    [ "$fmt_have" = "$go_have" ]
+}
+
+# ensure_go: reuse the host toolchain only when the go on PATH is inside
+# the window AND a gofmt from that same release is on PATH with it. Both
+# link_bin calls sit outside that early return, so whenever the pinned
+# toolchain is the one in use they run on every bootstrap, not only on
+# the run that unpacked the archive: a deleted or never-created gofmt
+# link is restored rather than silently left to some other Go's gofmt.
+ensure_go() {
+    if go_ok && gofmt_ok; then return 0; fi
+    if [ ! -x "$GO_DIR/bin/go" ]; then
+        plat="$(platform)"
+        tmp="$(mktemp -d)"
+        fetch_verified \
+            "https://go.dev/dl/go${GO_VERSION}.${plat}.tar.gz" \
+            "$(go_sha256 "$plat")" "$tmp/go.tar.gz"
+        rm -rf "$GO_DIR.partial"
+        mkdir -p "$GO_DIR.partial"
+        tar -xzf "$tmp/go.tar.gz" -C "$GO_DIR.partial" --strip-components=1
+        rm -rf "$GO_DIR"
+        mv "$GO_DIR.partial" "$GO_DIR"
+        rm -rf "$tmp"
+    fi
+    link_bin "$GO_DIR/bin/go" go
+    link_bin "$GO_DIR/bin/gofmt" gofmt
+}
+
+# golangci_lint_sha256 <platform>: sha256 of the golangci-lint 2.7.2
+# release archive for that platform, from
+# https://github.com/golangci/golangci-lint/releases/download/v2.7.2/golangci-lint-2.7.2-checksums.txt
+# (2026-08-09).
+golangci_lint_sha256() {
+    case "$1" in
+        linux-amd64)
+            echo "ce46a1f1d890e7b667259f70bb236297f5cf8791a9b6b98b41b283d93b5b6e88"
+            ;;
+        linux-arm64)
+            echo "7028e810837722683dab679fb121336cfa303fecff39dfe248e3e36bc18d941b"
+            ;;
+        darwin-amd64)
+            echo "6966554840a02229a14c52641bc38c2c7a14d396f4c59ba0c7c8bb0675ca25c9"
+            ;;
+        darwin-arm64)
+            echo "6ce86a00e22b3709f7b994838659c322fdc9eae09e263db50439ad4f6ec5785c"
+            ;;
+        *)
+            echo "bootstrap: no pinned golangci-lint archive hash for $1" >&2
+            exit 1
+            ;;
+    esac
+}
+
+# golangci_lint_ok: unlike go, this must be the exact pinned version.
+# A different version reports a different set of findings, so local
+# results would stop matching what Dockerfile.backend gates on.
+golangci_lint_ok() {
+    if missing golangci-lint; then return 1; fi
+    have="$(golangci-lint version 2>&1 | awk '
+        {
+            for (i = 1; i < NF; i++) {
+                if ($i == "version") {
+                    v = $(i + 1)
+                    sub(/^v/, "", v)
+                    print v
+                    exit
+                }
+            }
+        }')"
+    [ "$have" = "$GOLANGCI_LINT_VERSION" ]
+}
+
+ensure_golangci_lint() {
+    if golangci_lint_ok; then return 0; fi
+    if [ ! -x "$GOLANGCI_LINT_DIR/golangci-lint" ]; then
+        plat="$(platform)"
+        base="golangci-lint-${GOLANGCI_LINT_VERSION}-${plat}"
+        tmp="$(mktemp -d)"
+        fetch_verified \
+            "https://github.com/golangci/golangci-lint/releases/download/v${GOLANGCI_LINT_VERSION}/${base}.tar.gz" \
+            "$(golangci_lint_sha256 "$plat")" "$tmp/golangci-lint.tar.gz"
+        mkdir -p "$tmp/x"
+        tar -xzf "$tmp/golangci-lint.tar.gz" -C "$tmp/x" --strip-components=1
+        rm -rf "$GOLANGCI_LINT_DIR.partial"
+        mkdir -p "$GOLANGCI_LINT_DIR.partial"
+        cp "$tmp/x/golangci-lint" "$GOLANGCI_LINT_DIR.partial/golangci-lint"
+        chmod +x "$GOLANGCI_LINT_DIR.partial/golangci-lint"
+        rm -rf "$GOLANGCI_LINT_DIR"
+        mv "$GOLANGCI_LINT_DIR.partial" "$GOLANGCI_LINT_DIR"
+        rm -rf "$tmp"
+    fi
+    link_bin "$GOLANGCI_LINT_DIR/golangci-lint" golangci-lint
+}
+
+# verify_toolchain: bootstrap must not exit 0 while the tools the gate
+# will actually run are not the provisioned ones. Everything above only
+# guarantees the right tools exist and are linked into $BIN_DIR; if
+# something earlier on the caller's PATH shadows them, `make check` --
+# and the pre-commit hook script/setup installs -- still break, and a
+# warning buried in a long bootstrap log is not enough. So the checks
+# re-run against the PATH the caller will have (theirs, plus $BIN_DIR at
+# the front if bootstrap had to ask for it), and a failure is fatal.
+#
+# Every gate tool that has a version constraint is checked with the same
+# predicate its install used -- go_ok, gofmt_ok, golangci_lint_ok -- not
+# with a bare presence test, because a wrong-version gate tool produces
+# different results from the one CI runs, which is the failure this
+# function exists to prevent. node and yarn have no pinned version to
+# disagree about, so presence is the whole constraint for them.
+verify_toolchain() {
+    # BIN_DIR is only set once something needed linking, but the remedy
+    # text must name a real directory in every reachable state, so fall
+    # back to the one ensure_bin_dir would have chosen.
+    bin_dir="${BIN_DIR:-$HOME/.local/bin}"
+
+    # Model the PATH the caller will actually have: their own, plus
+    # $BIN_DIR at the front only if bootstrap linked something there and
+    # therefore told them to add it.
+    verify_path="$ORIG_PATH"
+    if [ -n "$BIN_DIR" ]; then
+        case ":$ORIG_PATH:" in
+            *":$BIN_DIR:"*) ;;
+            *) verify_path="$BIN_DIR:$ORIG_PATH" ;;
+        esac
+    fi
+
+    saved_path="$PATH"
+    PATH="$verify_path"
+    export PATH
+    bad=""
+    go_ok || bad="$bad go"
+    gofmt_ok || bad="$bad gofmt"
+    golangci_lint_ok || bad="$bad golangci-lint"
+    for t in node yarn; do
+        if missing "$t"; then bad="$bad $t"; fi
+    done
+    PATH="$saved_path"
+    export PATH
+
+    [ -z "$bad" ] && return 0
+
+    # Two different faults land here and they need different remedies: a
+    # tool that resolves but is the wrong build is being shadowed, and
+    # telling the user to fix PATH is right; a tool that does not resolve
+    # at all is not being shadowed by anything, and saying so would send
+    # them hunting for a conflict that does not exist.
+    echo "bootstrap: the toolchain on your PATH cannot run the gate." >&2
+    wrong=""
+    absent=""
+    for t in $bad; do
+        where="$(
+            export PATH="$verify_path"
+            command -v "$t" 2>/dev/null || true
+        )"
+        if [ -n "$where" ]; then
+            echo "  $t: $where (wrong version)" >&2
+            wrong="$wrong $t"
+        else
+            echo "  $t: not found" >&2
+            absent="$absent $t"
+        fi
+    done
+    echo "  The pinned toolchain is linked into $bin_dir." >&2
+    if [ -n "$wrong" ]; then
+        echo "  The tools shown with a path resolve to a build this" >&2
+        echo "  script did not provision: something earlier on your PATH" >&2
+        echo "  shadows $bin_dir. Put $bin_dir first in" >&2
+        echo "  PATH, or remove the conflicting tool, then re-run." >&2
+    fi
+    if [ -n "$absent" ]; then
+        echo "  The tools shown as not found are on no directory of your" >&2
+        echo "  PATH at all, so nothing is shadowing them. Add $bin_dir" >&2
+        echo "  to PATH and re-run; if they are still not found after" >&2
+        echo "  that, bootstrap failed to install them and that is a bug" >&2
+        echo "  in this script, not in your environment." >&2
+    fi
+    echo "  Failing rather than leaving you a bootstrap that reports" >&2
+    echo "  success and a \`make check\` that does not run." >&2
+    exit 1
+}
+
+main() {
+    cd "$ROOT"
+
+    TOOLCHAIN="$HOME/.local/share/$("$ROOT/script/projectname")/toolchain"
+    GO_DIR="$TOOLCHAIN/go-$GO_VERSION"
+    GOLANGCI_LINT_DIR="$TOOLCHAIN/golangci-lint-$GOLANGCI_LINT_VERSION"
+
+    if missing make; then pkg_install gnumake make make make; fi
+    if missing git; then pkg_install git git git git; fi
+
+    ensure_node
+    ensure_yarn
+    install_js_deps
+
+    ensure_go
+    ensure_golangci_lint
+
+    verify_toolchain
+
+    echo "bootstrap complete"
+}
+
+main "$@"

script/check

@@ -0,0 +1,16 @@
+#!/bin/sh
+# script/check: run all checks (test, lint, fmt-check) across the whole
+# repo, frontend and backend. Our own extension to
+# scripts-to-rule-them-all. Must not modify any files.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    "$ROOT/script/test"
+    "$ROOT/script/lint"
+    "$ROOT/script/fmt-check"
+}
+
+main "$@"

script/cibuild

@@ -0,0 +1,24 @@
+#!/bin/sh
+# script/cibuild: run the CI build. It builds every image in the repo:
+# the frontend image from Dockerfile and the backend image from
+# Dockerfile.backend. Each Dockerfile runs its half of make check as a
+# build step, so a successful cibuild implies the whole repo is green.
+# This is the only build step the Gitea workflow runs.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+# build_image <dockerfile>: build one image from the repo root context.
+# Every docker build CI performs goes through here, so build-wide flags
+# only ever have to be added in one place.
+build_image() {
+    timeout 300 docker build -f "$1" .
+}
+
+main() {
+    cd "$ROOT"
+    build_image Dockerfile
+    build_image Dockerfile.backend
+}
+
+main "$@"

script/docker

@@ -0,0 +1,16 @@
+#!/bin/sh
+# script/docker: build the repo's Docker images, tagged from
+# script/projectname: the frontend image as <name> and the backend image
+# as <name>-server. Both build from the repo root as their context.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    name="$("$ROOT/script/projectname")"
+    timeout 300 docker build -t "$name" -f Dockerfile .
+    timeout 300 docker build -t "$name-server" -f Dockerfile.backend .
+}
+
+main "$@"

script/fmt

@@ -0,0 +1,14 @@
+#!/bin/sh
+# script/fmt: format the whole repo (writes): prettier over everything
+# it understands, then gofmt over the Go backend.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    "$ROOT/script/frontend-fmt"
+    "$ROOT/backend/script/fmt"
+}
+
+main "$@"

script/fmt-check

@@ -0,0 +1,14 @@
+#!/bin/sh
+# script/fmt-check: check formatting across the whole repo (read-only).
+# Same scope as script/fmt, but fails instead of writing.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    "$ROOT/script/frontend-fmt-check"
+    "$ROOT/backend/script/fmt-check"
+}
+
+main "$@"

script/frontend-check

@@ -0,0 +1,18 @@
+#!/bin/sh
+# script/frontend-check: run the frontend half of the checks only (test,
+# lint, fmt-check). This exists for the frontend Dockerfile, whose build
+# stage is a node image with no Go toolchain; the backend half is gated
+# by Dockerfile.backend. Everywhere else, use script/check, which covers
+# the whole repo. Must not modify any files.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    "$ROOT/script/frontend-test"
+    "$ROOT/script/frontend-lint"
+    "$ROOT/script/frontend-fmt-check"
+}
+
+main "$@"

script/frontend-fmt

@@ -0,0 +1,14 @@
+#!/bin/sh
+# script/frontend-fmt: format the frontend and every other file prettier
+# understands, repo-wide (writes). backend/ is in .prettierignore; Go
+# sources are formatted by backend/script/fmt.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    yarn prettier --write .
+}
+
+main "$@"

script/frontend-fmt-check

@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/frontend-fmt-check: check prettier formatting (read-only). Same
+# scope as script/frontend-fmt, but fails instead of writing.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    yarn prettier --check .
+}
+
+main "$@"

script/frontend-lint

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/frontend-lint: run the frontend linter (prettier in check mode).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    yarn prettier --check .
+}
+
+main "$@"

script/frontend-test

@@ -0,0 +1,14 @@
+#!/bin/sh
+# script/frontend-test: run the frontend test suite. The frontend has no
+# unit tests; the production build serves as the test (fails on broken
+# code).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    timeout 30 yarn build
+}
+
+main "$@"

script/install-precommit

@@ -0,0 +1,16 @@
+#!/bin/sh
+# script/install-precommit: install the git pre-commit hook that runs
+# script/precommit. Our own extension to scripts-to-rule-them-all.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    hook=".git/hooks/pre-commit"
+    printf '#!/bin/sh\nset -e\nscript/precommit\n' > "$hook"
+    chmod +x "$hook"
+    echo "pre-commit hook installed: runs script/precommit"
+}
+
+main "$@"

script/lint

@@ -0,0 +1,14 @@
+#!/bin/sh
+# script/lint: lint the whole repo: prettier over everything it
+# understands, then golangci-lint over the Go backend.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    "$ROOT/script/frontend-lint"
+    "$ROOT/backend/script/lint"
+}
+
+main "$@"

script/precommit

@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/precommit: run by the git pre-commit hook; fails the commit if
+# checks fail. Our own extension to scripts-to-rule-them-all.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    "$ROOT/script/check"
+}
+
+main "$@"

script/projectname

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/projectname: output the name of this project. Our own
+# extension to scripts-to-rule-them-all. Other scripts that need the
+# name (e.g. script/docker) call this, so they can stay identical
+# across all repos.
+set -eu
+
+main() {
+    echo "netwatch"
+}
+
+main "$@"

script/setup

@@ -0,0 +1,14 @@
+#!/bin/sh
+# script/setup: set up the repo for development after a fresh clone:
+# installs dependencies and the git pre-commit hook.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    "$ROOT/script/bootstrap"
+    "$ROOT/script/install-precommit"
+}
+
+main "$@"

script/test

@@ -0,0 +1,14 @@
+#!/bin/sh
+# script/test: run the test suite for the whole repo: the frontend at
+# the repo root, then the Go backend in backend/.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    "$ROOT/script/frontend-test"
+    "$ROOT/backend/script/test"
+}
+
+main "$@"

src/styles.css

@@ -21,3 +21,96 @@ body {
         rgba(255, 255, 255, 0) 100%
     );
 }
+
+/* ---- Mobile responsive layout (portrait / narrow viewports) ---- */
+@media (max-width: 768px) {
+    /* Header: stack title and controls vertically */
+    header .flex.items-center.justify-between {
+        flex-direction: column;
+        align-items: flex-start !important;
+        gap: 1rem;
+    }
+
+    header .flex.flex-col.items-end {
+        align-items: flex-start !important;
+        flex-direction: row;
+        flex-wrap: wrap;
+        gap: 0.75rem;
+    }
+
+    /* Pause button: smaller on mobile */
+    #pause-btn {
+        padding: 0.5rem 1rem;
+    }
+
+    #pause-btn svg {
+        width: 1.25rem;
+        height: 1.25rem;
+    }
+
+    #pause-text {
+        font-size: 0.875rem;
+    }
+
+    /* Summary box: wrap into a grid for readability */
+    #summary {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 0.25rem 0.5rem;
+        justify-content: center;
+        line-height: 1.6;
+    }
+
+    /* Hide the pipe separators on mobile */
+    #summary .text-gray-600.mx-3 {
+        display: none;
+    }
+
+    /* Host row: stack vertically */
+    .host-row .flex.items-center.gap-4 {
+        flex-direction: column;
+        align-items: stretch !important;
+        gap: 0.5rem;
+    }
+
+    /* Info section: full width, remove fixed width */
+    .host-row .w-\[420px\] {
+        width: 100% !important;
+        display: grid;
+        grid-template-columns: 1fr auto;
+        align-items: center;
+    }
+
+    /* Host name row with dot */
+    .host-row .flex.items-center.gap-2.min-w-\[200px\] {
+        min-width: 0;
+    }
+
+    /* Latency value: slightly smaller on mobile */
+    .host-row .latency-value {
+        font-size: 1.875rem;
+        line-height: 2.25rem;
+    }
+
+    /* Sparkline: full width below the info */
+    .host-row .sparkline-container {
+        width: 100%;
+        flex-shrink: 0;
+    }
+
+    /* Pin button: inline with the host info */
+    .host-row .pin-btn {
+        position: absolute;
+        right: 0.5rem;
+        top: 0.5rem;
+    }
+
+    .host-row {
+        position: relative;
+    }
+
+    /* Footer legend: wrap nicely */
+    footer p {
+        line-height: 1.8;
+    }
+}

vite.config.js

@@ -1,8 +1,16 @@
 import { defineConfig } from "vite";
 import tailwindcss from "@tailwindcss/vite";
+import { execSync } from "child_process";
+
+const commitHash = execSync("git rev-parse --short HEAD").toString().trim();
+const commitFull = execSync("git rev-parse HEAD").toString().trim();
 
 export default defineConfig({
     plugins: [tailwindcss()],
+    define: {
+        __COMMIT_HASH__: JSON.stringify(commitHash),
+        __COMMIT_FULL__: JSON.stringify(commitFull),
+    },
     build: {
         target: "esnext",
         minify: "esbuild",