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.

Makefile

@@ -0,0 +1,65 @@
+# Task runner for the repo. Run `make` on its own to list the targets.
+#
+# These are thin wrappers over the Go tool — `make build` is exactly
+# `go run . -build`. The wrapping earns its keep for the targets Go alone
+# cannot express (serve, test, clean) and for not having to remember which
+# steps need a GITHUB_TOKEN and which do not.
+
+DIST ?= dist
+PORT ?= 8080
+
+# Print the help text when make is run with no target.
+.DEFAULT_GOAL := help
+
+.PHONY: help update build check serve test fmt lint clean
+
+help: ## Show this help
+	@echo "Usage: make <target>"
+	@echo
+	@grep -hE '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-8s\033[0m %s\n", $$1, $$2}'
+	@echo
+	@echo "Only 'update' needs network access and a GITHUB_TOKEN."
+
+update: ## Fetch GitHub and refresh README, history and metadata (needs GITHUB_TOKEN)
+	@[ -n "$$GITHUB_TOKEN" ] || { \
+		echo "GITHUB_TOKEN is not set — see docs/LOCAL_DEV.md for how to get one."; \
+		echo "If you only changed tags, notes or the dashboard, use 'make build' instead."; \
+		exit 1; \
+	}
+	go run .
+
+build: ## Render the site into dist/ from committed data (offline)
+	go run . -build
+
+check: ## Validate data/agents.yml (offline)
+	go run . -check
+
+serve: build ## Build, then preview the dashboard locally (override with PORT=)
+	@command -v python3 >/dev/null || { \
+		echo "python3 not found — serve $(DIST)/ with any static file server instead."; \
+		exit 1; \
+	}
+	@echo "Serving $(DIST)/ at http://localhost:$(PORT) — Ctrl-C to stop"
+	@python3 -m http.server $(PORT) -d $(DIST)
+
+test: ## Run everything CI runs (vet, tests, check, build)
+	go vet ./...
+	go test ./...
+	go run . -check
+	go run . -build
+
+fmt: ## Format the Go sources
+	gofmt -w .
+
+lint: ## Run golangci-lint if it is installed
+	@command -v golangci-lint >/dev/null || { \
+		echo "golangci-lint not installed — CI runs it regardless."; \
+		echo "Install: https://golangci-lint.run/welcome/install/"; \
+		exit 1; \
+	}
+	golangci-lint run
+
+clean: ## Remove build output
+	rm -rf $(DIST)
+	rm -f awesome-ai-dev-tools

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