Add docs-live Makefile target and use make in docs

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: gilesknap

Makefile

@@ -8,7 +8,7 @@ agent-%: clean-agent
 clean-agent:
 	rm -f agent
 
-.PHONY: lint test docs ci
+.PHONY: lint test docs docs-live ci
 
 lint:
 	golangci-lint run
@@ -19,6 +19,9 @@ test:
 docs:
 	uv run sphinx-build -W --keep-going docs docs/_build/html
 
+docs-live:
+	uv run sphinx-autobuild docs docs/_build/html
+
 ci:
 	$(MAKE) -j lint test docs
 

docs/how-to/run-sphinx.md

@@ -1,6 +1,8 @@
 # Run Sphinx
 
-This guide explains how to build and preview the project documentation locally using Sphinx.
+This guide explains how to build and preview the project documentation locally
+using Sphinx. Makefile targets are provided so you don't need to remember the
+full commands.
 
 ## Prerequisites
 
@@ -17,24 +19,20 @@ $ uv sync --group docs
 
 ## Build the documentation
 
-Run a one-off build into `docs/_build/html`:
+Run a one-off build (warnings are treated as errors, matching CI):
 
 ```bash
-$ uv run sphinx-build docs docs/_build/html
+$ make docs
 ```
 
-To treat warnings as errors (as CI does):
-
-```bash
-$ uv run sphinx-build -W --keep-going docs docs/_build/html
-```
+The output is written to `docs/_build/html`.
 
 ## Live preview
 
 For a live-reloading server that rebuilds on changes:
 
 ```bash
-$ uv run sphinx-autobuild docs docs/_build/html
+$ make docs-live
 ```
 
 Then open the URL shown in the terminal (typically `http://127.0.0.1:8000`).