build: add a Makefile task runner

`go run build` cannot work — Go resolves a bare argument as an import
path, so it looks for a package named "build" in std. Wrap the existing
commands in make targets instead, which gives the `make build` /
`make check` ergonomics without changing the Go interface underneath.

The wrapper earns its keep beyond the aliasing: `make serve` builds and
previews dist/ in one step, `make test` runs exactly what CI runs, and
`make update` fails with a pointer to LOCAL_DEV.md when GITHUB_TOKEN is
unset rather than erroring out mid-run.

Cloudflare keeps calling `go run . -build` directly. Locally make is
convenience; in the build image it would be a dependency relied on for
no benefit.

docs/CONTRIBUTING.md

@@ -135,4 +135,5 @@ historical-significance exception.
 - No manual review required; the updater regenerates the README after your PR merges
 
 For local testing before opening a PR, see [LOCAL_DEV.md](./LOCAL_DEV.md). A tag
-or note change needs only `go run . -build` — no GitHub token.
+or note change needs only `make build` — no GitHub token. `make test` runs
+everything CI will.

docs/DEPLOY.md

@@ -36,7 +36,7 @@ by the nightly **Update rankings** workflow — so this is normally just a
 sanity check:
 
 ```bash
-go run . -build   # should print "built dist: N entries, data fetched ..."
+make build   # should print "built dist: N entries, data fetched ..."
 ```
 
 If it is ever missing (a fresh fork, say), regenerate it by triggering
@@ -79,6 +79,10 @@ Cloudflare's build image ships Go and honours `GO_VERSION`. Even on an older
 image, Go's toolchain directive in `go.mod` downloads the matching toolchain
 automatically.
 
+The build command is the raw `go run . -build` rather than `make build`, which
+is the same thing locally. Locally `make` is convenience; in the build image it
+would be one more dependency to rely on for no benefit.
+
 ### 4. Deploy
 
 Save and deploy. Subsequent pushes to `main` — yours and the nightly bot's —

docs/LOCAL_DEV.md

@@ -3,7 +3,10 @@
 ## Prerequisites
 
 - Go 1.23 or later
-- A GitHub personal access token (PAT)
+- `make` (optional — every target is a one-line wrapper you can run by hand)
+- A GitHub personal access token (PAT), for the update step only
+
+Run `make` with no arguments to list the available targets.
 
 ## Getting a GitHub Token
 
@@ -24,7 +27,7 @@ needs a token. See [DEPLOY.md](./DEPLOY.md) for why.
 
 ```bash
 export GITHUB_TOKEN=ghp_your_token_here
-go run .
+make update          # or: go run .
 ```
 
 This will:
@@ -37,17 +40,17 @@ This will:
 ### Build (offline, no token)
 
 ```bash
-go run . -build
+make build           # or: go run . -build
 ```
 
 This joins `data/agents.yml` (tags and notes) with `data/metadata.json` (stars
 and repo metadata) and renders `dist/` — a copy of `site/` plus the generated
 `dist/data.json`. This is exactly what Cloudflare Pages runs.
 
-Preview it with any static server:
+Preview it at <http://localhost:8080>:
 
 ```bash
-go run . -build && python3 -m http.server -d dist 8080
+make serve           # builds first; override the port with PORT=3000
 ```
 
 If you only touched `site/index.html` or the tags in `data/agents.yml`, the
@@ -56,7 +59,15 @@ build step alone is enough — no token required.
 ### Validate (offline, no token)
 
 ```bash
-go run . -check
+make check           # or: go run . -check
+```
+
+### Before pushing
+
+`make test` runs what CI runs — vet, tests, `-check` and `-build`:
+
+```bash
+make test
 ```
 
 ## Reverting Local Changes