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/frontend-check` is the frontend half of the gate, exposed as
  the `check-frontend` 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
  `check-backend` target is the mirror of it.
- `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.

READMEs at the root and in `backend/` document every script, and
`TODO.md` records the change.

.gitea/workflows/check.yml

@@ -6,5 +6,6 @@ jobs:
         steps:
             # actions/checkout v4.2.2, 2026-02-22
             - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-            - run: docker build .
+            # script/cibuild builds both images; it is the only build
-            - run: docker build -f Dockerfile.backend .
+            # step, so how the repo builds stays defined in script/.
+            - run: script/cibuild

Dockerfile

@@ -3,9 +3,16 @@ FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e3
 WORKDIR /app
 COPY package.json yarn.lock ./
 RUN yarn install --frozen-lockfile
-RUN apk add --no-cache git
+RUN apk add --no-cache git make
 COPY . .
-RUN yarn build
+# make check-frontend 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 check-frontend
 
 # nginx:stable-alpine as of 2026-02-22
 FROM nginx@sha256:15e96e59aa3b0aada3a121296e3bce117721f42d88f5f64217ef4b18f458c6ab

Makefile

@@ -1,21 +1,45 @@
-.PHONY: dev test lint fmt fmt-check check docker
+.PHONY: bootstrap setup dev test lint fmt fmt-check check check-frontend \
+	check-backend 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.
+check-frontend:
+	@script/frontend-check
+
+check-backend:
+	@backend/script/check
 
 docker:
-	timeout 300 docker build -t netwatch .
+	@script/docker
+
+hooks:
+	@script/install-precommit

README.md

@@ -23,6 +23,61 @@ 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 (pinned node via nvm if needed,
+  yarn via corepack, `yarn install --frozen-lockfile`)
+- `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`, used by
+  `Dockerfile`, whose build stage is a node image with no Go toolchain
+- `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

REPO_POLICIES.md

@@ -1,108 +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
+This document covers repository structure, tooling, and workflow standards. Code
-  RCE vulnerability. All docker image references must use cryptographic hashes
+style conventions are in separate documents:
-  to securely specify the exact image that is expected.
 
-- Correspondingly, `go install` commands using things like '@latest' are also
+- [Code Styleguide](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/CODE_STYLEGUIDE.md)
-  dangerous RCE. Whenever writing scripts or tools, ALWAYS specify go install
+  (general, bash, Docker)
-  targets using commit hashes which are cryptographically secure.
+- [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,
+- Cross-project documentation (such as this file) must include
-  the Dockerfile should bring up a development environment and `make check`
+  `last_modified: YYYY-MM-DD` in the YAML front matter so it can be kept in sync
-  (i.e. the docker build should fail if the branch is not green).
+  with the authoritative source as policies evolve.
 
-- Platform-specific standard formatting should be used. `black` for python,
+- **ALL external references must be pinned by cryptographic hash.** This
-  `prettier` for js/css/etc, `go fmt` for go. The only changes to default
+  includes Docker base images, Go modules, npm packages, GitHub Actions, and
-  settings should be to specify four-space indents where applicable (i.e.
+  anything else fetched from a remote source. Version tags (`@v4`, `@latest`,
-  everything except `go fmt`).
+  `: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
+- Every repo with software must have a root `Makefile` with these targets:
-  pre-commit hook. If it is not possible, `make lint && make fmt-check` should
+  `make bootstrap`, `make setup`, `make test`, `make lint`, `make fmt` (writes),
-  be a pre-commit hook.
+  `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
+- Repos follow the
-  fixing. In fact, there should be a timeout specified in the `Makefile` that
+  [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
-  fails it automatically if it takes >30s.
+  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 feature
+- Never commit secrets. `.env` files, credentials, API keys, and private keys
-  branch.
+  must be in `.gitignore`. No exceptions.
 
-- We have a standardized `.golangci.yml` which we reuse and is _NEVER_ to be
+- `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
-  modified by an agent, only manually by the user. It can be copied from
+  editor files (`.swp`, `*~`), language build artifacts, and `node_modules/`.
-  `~/dev/upaas/.golangci.yml` if it exists at that location.
+  Fetch the standard `.gitignore` from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
+  a new repo.
 
-- When specifying images or packages by hash in Dockerfiles or
+- **No build artifacts in version control.** Code-derived data (compiled
-  `docker-compose.yml`, put a comment above the line and show the version and
+  bundles, minified output, generated assets) must never be committed to the
-  date at which it was current.
+  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.
 
-- For javascript, always use `yarn` over `npm`.
+- Never use `git add -A` or `git add .`. Always stage files explicitly by name.
 
-- Whenever writing dates, ALWAYS write YYYY-MM-DD (ISO 8601).
+- Never force-push to `main`.
 
-- Simple projects should be configured with environment variables, as is
+- Make all changes on a feature branch. You can do whatever you want on a
-  standard for Dockerized applications.
+  feature branch.
 
-- Dockerized web services should listen on the default HTTP port of 8080 unless
+- `.golangci.yml` is standardized and must _NEVER_ be modified by an agent, only
-  overridden with the `PORT` environment variable.
+  manually by the user. Fetch from
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`.
 
-- The `README.md` is a project's primary documentation. It should contain at a
+- When pinning images or packages by hash, add a comment above the reference
-  minimum the following sections:
+  with the version and date (YYYY-MM-DD).
-    - 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`).
 
-- When beginning a new project, initialize a git repo and make the first commit
+- Use `yarn`, not `npm`.
-  simply the first version of the README.md in the root of the repo.
 
-- For Go packages, the module root is `sneak.berlin/go/...`, such as
+- Write all dates as YYYY-MM-DD (ISO 8601).
-  `sneak.berlin/go/dnswatcher`.
 
-- We use SemVer always.
+- Simple projects should be configured with environment variables.
 
-- If no tag `1.0.0` or greater exists in the repository, modify the existing
+- Dockerized web services listen on port 8080 by default, overridable with
-  migrations and assume no installed base or existing databases. If `>=1.0.0`,
+  `PORT`.
-  database changes add new migration files.
 
-- New repos must have at a minimum the following files:
+- **HTTP/web services must be hardened for production internet exposure before
-    - `README.md`, `.git`, `.gitignore`
+  tagging 1.0.** This means full compliance with security best practices
-    - `POLICIES.md` (copy from `~/Documents/_PROMPTS/POLICIES.md`)
+  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.
+
+    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.
+
+- `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).
+
+- First commit of a new repo should contain only `README.md`.
+
+- Go module root: `sneak.berlin/go/<name>`. Always run `go mod tidy` before
+  committing.
+
+- 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`
+    - `.gitea/workflows/check.yml`
-    - for js: `package.json`
+    - Go: `go.mod`, `go.sum`, `.golangci.yml`
+    - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
+    - Python: `pyproject.toml`

TODO.md

@@ -0,0 +1,52 @@
+# 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, and
+  `script/cibuild` now builds both images as the workflow's only build step
+- 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/Makefile

@@ -1,53 +1,38 @@
-UNAME_S := $(shell uname -s)
+# Standard targets are thin shims; the implementations live in
-VERSION := $(shell git describe --always --dirty)
+# backend/script/ per the scripts-to-rule-them-all pattern (see the
-BUILDARCH := $(shell uname -m)
+# Entrypoints section of README.md).
-BINARY := netwatch-server
+#
+# 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`.
 
-GOLDFLAGS += -X main.Version=$(VERSION)
+.PHONY: all build test lint fmt fmt-check check run clean
-GOLDFLAGS += -X main.Buildarch=$(BUILDARCH)
-
-ifeq ($(UNAME_S),Darwin)
-	GOFLAGS := -ldflags "$(GOLDFLAGS)"
-else
-	GOFLAGS = -ldflags "-linkmode external -extldflags -static $(GOLDFLAGS)"
-endif
-
-.PHONY: all build test lint fmt fmt-check check docker hooks run clean
 
 all: build
 
-build: ./$(BINARY)
+build:
-
+	@script/build
-./$(BINARY): $(shell find . -name '*.go' -type f) go.mod go.sum
-	go build -o $@ $(GOFLAGS) ./cmd/netwatch-server/
 
 test:
-	timeout 30 go test ./...
+	@script/test
 
 lint:
-	golangci-lint run ./...
+	@script/lint
 
 fmt:
-	go fmt ./...
+	@script/fmt
 
 fmt-check:
-	@test -z "$$(gofmt -l .)" || \
+	@script/fmt-check
-		(echo "Files not formatted:"; gofmt -l .; exit 1)
 
-check: test lint fmt-check
+check:
+	@script/check
 
-docker:
+run:
-	timeout 300 docker build -t netwatch-server -f ../Dockerfile.backend ..
+	@script/run
-
-hooks:
-	@printf '#!/bin/sh\ncd backend && make check\n' > \
-		$$(git rev-parse --show-toplevel)/.git/hooks/pre-commit
-	@chmod +x \
-		$$(git rev-parse --show-toplevel)/.git/hooks/pre-commit
-	@echo "Pre-commit hook installed"
-
-run: build
-	./$(BINARY)
 
 clean:
-	rm -f ./$(BINARY)
+	@script/clean

backend/README.md

@@ -11,11 +11,38 @@ make run
 # Run tests, lint, and format check
 make check
 
-# Docker
+# Docker (from the repo root; the image's build context is the repo root)
-docker build -t netwatch-server .
+make docker
 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

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,15 @@
+#!/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
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/test"
+    "$SCRIPT_DIR/lint"
+    "$SCRIPT_DIR/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,46 @@
+#!/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.
+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,14 @@
+#!/bin/sh
+# script/run: build and run netwatch-server locally.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/build"
+    cd "$ROOT"
+    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 "$@"

script/bootstrap

@@ -0,0 +1,143 @@
+#!/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).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+# 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"
+
+PKGMGR=""
+SUDO=""
+APT_UPDATED=""
+
+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
+}
+
+# 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)"
+    curl -fsSL -o "$tmp/nvm.tar.gz" \
+        "https://github.com/nvm-sh/nvm/archive/refs/tags/v${NVM_VERSION}.tar.gz"
+    verify_sha256 "$tmp/nvm.tar.gz" "$NVM_SHA256"
+    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"
+}
+
+ensure_yarn() {
+    if ! missing yarn; then return 0; fi
+    if ! missing corepack; then
+        corepack enable
+        corepack prepare "yarn@$YARN_VERSION" --activate
+    elif [ -s "$HOME/.nvm/nvm.sh" ]; then
+        nvm_sh "nvm use $NODE_VERSION >/dev/null && corepack enable && \
+            corepack prepare yarn@$YARN_VERSION --activate"
+    else
+        npm install -g "yarn@$YARN_VERSION"
+    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
+}
+
+main() {
+    cd "$ROOT"
+
+    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
+
+    echo "bootstrap complete"
+}
+
+main "$@"

script/check

@@ -0,0 +1,15 @@
+#!/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
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/test"
+    "$SCRIPT_DIR/lint"
+    "$SCRIPT_DIR/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,17 @@
+#!/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
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    name="$("$SCRIPT_DIR/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,17 @@
+#!/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
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/frontend-test"
+    "$SCRIPT_DIR/frontend-lint"
+    "$SCRIPT_DIR/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,12 @@
+#!/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
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/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,13 @@
+#!/bin/sh
+# script/setup: set up the repo for development after a fresh clone:
+# installs dependencies and the git pre-commit hook.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/bootstrap"
+    "$SCRIPT_DIR/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/main.js

@@ -1131,25 +1131,6 @@ function handleResize(state) {
 async function init() {
     log.info("NetWatch starting");
 
-    // Mobile detection — show a friendly message and bail out early
-    if (window.innerWidth < 768) {
-        const app = document.getElementById("app");
-        app.innerHTML = `
-        <div class="mx-auto px-[5%] py-8">
-          <header class="mb-8">
-            <h1 class="text-3xl font-bold text-white"><a href="https://git.eeqj.de/sneak/netwatch" target="_blank" rel="noopener" class="underline decoration-dashed decoration-gray-500 underline-offset-4">NetWatch</a> by <a href="https://sneak.berlin" target="_blank" rel="noopener" class="text-blue-400 underline hover:text-blue-300">@sneak</a></h1>
-            <p class="text-gray-400 mt-2">Real-time network connectivity monitor</p>
-          </header>
-          <div style="display:flex;align-items:center;justify-content:center;min-height:50vh;">
-            <div style="background:#1f2937;border:1px solid #374151;border-radius:12px;padding:2rem 1.5rem;text-align:center;max-width:90vw;">
-              <p style="font-size:1.25rem;color:#e5e7eb;margin:0;">Not yet available on mobile.</p>
-            </div>
-          </div>
-        </div>`;
-        log.info("Mobile viewport detected — skipping monitor startup");
-        return;
-    }
-
     // Probe common gateway IPs to find the local router
     const gateway = await detectGateway();
     const localHosts = [LOCAL_CPE];

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;
+    }
+}