Add screenshot capture tool and dev setup docs

.gitignore

@@ -0,0 +1 @@
+/screenshots/

docs/dev.md

@@ -1,5 +1,7 @@
 # Local development
 
+Toolchain prerequisites: see [setup.md](setup.md).
+
 ## Run
 
     go run .
@@ -16,3 +18,4 @@ The server reads local data from `sampledata/`, mirroring the production Sheets
 - `internal/data` — data source interface and the CSV sample-data implementation
 - `internal/directory` — directory app handlers
 - `web/directory` — directory app page templates and static assets
+- `tools/screenshot` — dev-site page capture, see [screenshots.md](screenshots.md)

docs/plan.md

@@ -19,7 +19,7 @@
 - One command starts the local server.
 - Templates, static assets, and content reload on change without restarting the server.
 - A local data mode serves generated, non-production sample data so contributors never need real community data to develop or test.
-- A documented screenshot mechanism captures pages from the local dev server, so agents (and humans) can verify visual changes. See `docs/screenshots.md` once it exists.
+- A documented screenshot mechanism captures pages from the local dev server, so agents (and humans) can verify visual changes. See `docs/screenshots.md`.
 
 ## Directory app
 

docs/screenshots.md

@@ -0,0 +1,27 @@
+# Screenshots
+
+`tools/screenshot` captures pages from the local dev server as PNGs, so humans and agents can verify visual changes. It drives a locally installed Chrome (or Chromium) headless via chromedp; no other browser tooling is required.
+
+## Usage
+
+With the server running:
+
+    go run ./tools/screenshot -url http://localhost:8080/directory/ -out screenshots/directory.png -wait header
+
+Flags:
+
+- `-url` — page to capture (default `http://localhost:8080/directory/`)
+- `-out` — output PNG path (default `screenshots/capture.png`); `screenshots/` is gitignored
+- `-wait` — CSS selector that must be visible before capture (default `body`); pass a selector the page's JavaScript renders (for example `.card`) to capture after data loads
+
+The capture is a full-page screenshot at a 1280×800 viewport.
+
+## Agent recipe
+
+One self-contained command that starts the server, captures, and shuts down:
+
+    go run . &
+    go run ./tools/screenshot -out screenshots/directory.png -wait header
+    kill $(lsof -ti :8080)
+
+Then read `screenshots/directory.png` to inspect the result.

docs/setup.md

@@ -0,0 +1,11 @@
+# Dev environment setup
+
+Development happens on macOS. Two Homebrew installs, and everything in `docs/dev.md` and `docs/screenshots.md` works:
+
+    brew install go
+    brew install --cask google-chrome
+
+- **Go** 1.26 or later — builds and runs the server and all tooling (`go run`, `go vet`).
+- **Google Chrome** — launched headless by the screenshot tool; never needs to be opened by hand. The tool finds it in its standard install location automatically.
+
+No Node, no Docker, and no cloud credentials are needed for local development.

go.mod

@@ -1,3 +1,15 @@
 module heliosian
 
 go 1.26
+
+require github.com/chromedp/chromedp v0.16.0
+
+require (
+	github.com/chromedp/cdproto v0.0.0-20260714215040-dc233986426f // indirect
+	github.com/chromedp/sysutil v1.1.0 // indirect
+	github.com/go-json-experiment/json v0.0.0-20260623181947-01eb4420fa68 // indirect
+	github.com/gobwas/httphead v0.1.0 // indirect
+	github.com/gobwas/pool v0.2.1 // indirect
+	github.com/gobwas/ws v1.4.0 // indirect
+	golang.org/x/sys v0.47.0 // indirect
+)

go.sum

@@ -0,0 +1,21 @@
+github.com/chromedp/cdproto v0.0.0-20260714215040-dc233986426f h1:0Z1zcSLEmnj2c2CmJYBqewtS6pxhB39bNWUSEUAWjgk=
+github.com/chromedp/cdproto v0.0.0-20260714215040-dc233986426f/go.mod h1:RwFsSODCtFExll+GhHM6R92SARHR3Z3oipaxLHj46C0=
+github.com/chromedp/chromedp v0.16.0 h1:rOO4deOm4CbZgBCa8mD9g2rDyIoNs0BkgvNrlbp5ouk=
+github.com/chromedp/chromedp v0.16.0/go.mod h1:rbuGKFT1vMcFcFqKfPIO1GpX/N+2s8onm2qMxZLbU5U=
+github.com/chromedp/sysutil v1.1.0 h1:PUFNv5EcprjqXZD9nJb9b/c9ibAbxiYo4exNWZyipwM=
+github.com/chromedp/sysutil v1.1.0/go.mod h1:WiThHUdltqCNKGc4gaU50XgYjwjYIhKWoHGPTUfWTJ8=
+github.com/go-json-experiment/json v0.0.0-20260623181947-01eb4420fa68 h1:KZaTBSyshWX3MP5jukJcNSuXDQTO+rNpt0J564dX/eg=
+github.com/go-json-experiment/json v0.0.0-20260623181947-01eb4420fa68/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
+github.com/gobwas/httphead v0.1.0 h1:exrUm0f4YX0L7EBwZHuCF4GDp8aJfVeBrlLQrs6NqWU=
+github.com/gobwas/httphead v0.1.0/go.mod h1:O/RXo79gxV8G+RqlR/otEwx4Q36zl9rqC5u12GKvMCM=
+github.com/gobwas/pool v0.2.1 h1:xfeeEhW7pwmX8nuLVlqbzVc7udMDrwetjEv+TZIz1og=
+github.com/gobwas/pool v0.2.1/go.mod h1:q8bcK0KcYlCgd9e7WYLm9LpyS+YeLd8JVDW6WezmKEw=
+github.com/gobwas/ws v1.4.0 h1:CTaoG1tojrh4ucGPcoJFiAQUAsEWekEWvLy7GsVNqGs=
+github.com/gobwas/ws v1.4.0/go.mod h1:G3gNqMNtPppf5XUz7O4shetPpcZ1VJ7zt18dlUeakrc=
+github.com/ledongthuc/pdf v0.0.0-20220302134840-0c2507a12d80 h1:6Yzfa6GP0rIo/kULo2bwGEkFvCePZ3qHDDTC3/J9Swo=
+github.com/ledongthuc/pdf v0.0.0-20220302134840-0c2507a12d80/go.mod h1:imJHygn/1yfhB7XSJJKlFZKl/J+dCPAknuiaGOshXAs=
+github.com/orisano/pixelmatch v0.0.0-20220722002657-fb0b55479cde h1:x0TT0RDC7UhAVbbWWBzr41ElhJx5tXPWkIHA2HWPRuw=
+github.com/orisano/pixelmatch v0.0.0-20220722002657-fb0b55479cde/go.mod h1:nZgzbfBr3hhjoZnS66nKrHmduYNpc34ny7RK4z5/HM0=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
+golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=

tools/screenshot/main.go

@@ -0,0 +1,41 @@
+// Command screenshot captures a page from the local dev server as a PNG.
+package main
+
+import (
+	"context"
+	"flag"
+	"log"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/chromedp/chromedp"
+)
+
+func main() {
+	url := flag.String("url", "http://localhost:8080/directory/", "page to capture")
+	out := flag.String("out", "screenshots/capture.png", "output png path")
+	wait := flag.String("wait", "body", "css selector that must be visible before capturing")
+	flag.Parse()
+	ctx, cancelBrowser := chromedp.NewContext(context.Background())
+	defer cancelBrowser()
+	ctx, cancelTimeout := context.WithTimeout(ctx, 30*time.Second)
+	defer cancelTimeout()
+	var png []byte
+	err := chromedp.Run(ctx,
+		chromedp.EmulateViewport(1280, 800),
+		chromedp.Navigate(*url),
+		chromedp.WaitVisible(*wait, chromedp.ByQuery),
+		chromedp.FullScreenshot(&png, 90),
+	)
+	if err != nil {
+		log.Fatalf("[ERROR] capture %s: %v", *url, err)
+	}
+	if err := os.MkdirAll(filepath.Dir(*out), 0o755); err != nil {
+		log.Fatalf("[ERROR] create output dir: %v", err)
+	}
+	if err := os.WriteFile(*out, png, 0o644); err != nil {
+		log.Fatalf("[ERROR] write %s: %v", *out, err)
+	}
+	log.Printf("captured %s to %s", *url, *out)
+}