From d0197a41ed7f7b717ddb9d50ba754edc478ab0e4 Mon Sep 17 00:00:00 2001
From: Claude Opus 5 <noreply@anthropic.com>
Date: Thu, 30 Jul 2026 01:38:17 +0600
Subject: [PATCH] add a Makefile and build instructions

So the thing can be built and run without reading the harness. Eight targets,
each one go command or verify.sh; make help lists them. README gains the four
lines someone actually needs, and says a site root is a directory the binary is
pointed at rather than something in this repo.

make is recorded in toolchain.md as a convenience: the gate never invokes it, so
a machine without make loses nothing but typing.
---
 Makefile          | 33 +++++++++++++++++++++++++++++++++
 README.md         | 17 +++++++++++++++++
 docs/toolchain.md |  7 +++++--
 3 files changed, 55 insertions(+), 2 deletions(-)
 create mode 100644 Makefile

diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..0b42a27
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,33 @@
+# Convenience only. `go build`, `go test` and ./scripts/verify.sh are the ground truth — nothing here
+# is required to work on khosra, and the gate never invokes make.
+
+SITE ?= $(KHOSRA_SITE)
+ADDR ?= localhost:8080
+BIN  := ./khosra
+
+.PHONY: help build run test verify fmt tidy clean
+
+help: ## list targets
+	@grep -hE '^[a-z]+:.*##' $(MAKEFILE_LIST) | sed 's/:[^#]*## /|/' | column -t -s '|'
+
+build: ## compile the binary
+	go build -o $(BIN) ./cmd/khosra
+
+run: build ## serve a site root: make run SITE=/path/to/site
+	@test -n "$(SITE)" || { echo "set SITE=/path/to/site, or export KHOSRA_SITE"; exit 1; }
+	$(BIN) -site "$(SITE)" -addr "$(ADDR)"
+
+test: ## run tests with the race detector
+	go test -race ./...
+
+verify: ## everything the harness enforces; must be green before a commit
+	./scripts/verify.sh
+
+fmt: ## format all Go source
+	gofmt -w .
+
+tidy: ## tidy go.mod
+	go mod tidy
+
+clean: ## remove build output
+	rm -f $(BIN)
diff --git a/README.md b/README.md
index 3533a15..b472e04 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,23 @@ A flat-file personal publishing engine in Go. Point the binary at a directory of
 becomes an owned, networked home for fiction, webcomics, art, and essays, in English and Bengali.
 The site's content lives in its own repository, not this one (ADR-0011).
 
+## Build and run
+
+Needs Go 1.26+ and git; nothing else.
+
+```
+make build                      # or: go build -o khosra ./cmd/khosra
+make run SITE=/path/to/site     # or: ./khosra -site /path/to/site
+make test
+make verify                     # everything the project enforces — green before every commit
+```
+
+`make help` lists targets. `make` is a convenience wrapper; `go build`, `go test` and
+`./scripts/verify.sh` work on their own and are what the gate uses.
+
+A site root is a directory holding `content/`, and optionally `static/` and `templates/`. It lives in its
+own repository, not this one — the binary is pointed at it.
+
 **If you are a human:** start at [HARNESS.md](HARNESS.md) — what the scaffolding is, how to use it,
 and what to decide.
 
diff --git a/docs/toolchain.md b/docs/toolchain.md
index 5ca9694..1a21b13 100644
--- a/docs/toolchain.md
+++ b/docs/toolchain.md
@@ -32,8 +32,11 @@ These are the ones most likely to move, and the ones whose breakage looks like a
 ## Not depended on
 
 No CI service, no container registry, no language server, no linter binary, no package manager beyond
-`go mod`. `verify.sh` runs offline with nothing but Go and git on `PATH`, which is deliberate — the gate
-must work on a machine you have not configured for two years.
+`go mod`. The `Makefile` is a convenience wrapper only: every target is one `go` or `verify.sh` command,
+and the gate never invokes `make`, so a machine without it loses nothing but typing.
+
+`verify.sh` runs offline with nothing but Go and git on `PATH`, which is deliberate — the gate must work
+on a machine you have not configured for two years.
 
 `VERIFY_DOCKER=1` adds a container build step and needs `docker`; it is opt-in and off by default.