diff --git a/CLAUDE.md b/CLAUDE.md
index cc0b1f2..4211517 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -15,7 +15,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 | 5 | `bggpipe upload` | add games via a logged-in Playwright session | working — all browser flows verified live 2026-08-06 (62 adds + 36 version updates landed) |
 | 6 | `bggpipe enrich` | fetch full game/version metadata into `games.json` | working |
 
-Full design lives in `bgg-shelf-pipeline-spec.md` (read it before changing pipeline semantics); the upload-stage walkthrough is in `docs/bgg-upload-flow.md`.
+Full design lives in `docs/spec.md` (read it before changing pipeline semantics); the upload-stage walkthrough is in `docs/bgg-upload-flow.md`.
 
 ## Commands
 
diff --git a/README.md b/README.md
index 1d5620b..d78f1f8 100644
--- a/README.md
+++ b/README.md
@@ -69,7 +69,7 @@ uv run ruff check src tests   # lint
 uv run bggpipe web --dev      # the app with code hot-reload
 ```
 
-Run your own *pipeline* from a different directory — the clone's `data/` is the author's live data. Architecture and contributor guidance: [CLAUDE.md](CLAUDE.md) and the [full spec](bgg-shelf-pipeline-spec.md); BGG automation notes: [docs/bgg-upload-flow.md](docs/bgg-upload-flow.md).
+Run your own *pipeline* from a different directory — the clone's `data/` is the author's live data. Architecture and contributor guidance: [CLAUDE.md](CLAUDE.md) and the [design contract](docs/spec.md); BGG automation notes: [docs/bgg-upload-flow.md](docs/bgg-upload-flow.md).
 
 ## A note on being a good BGG citizen
 
diff --git a/bgg-shelf-pipeline-spec.md b/docs/spec.md
similarity index 98%
rename from bgg-shelf-pipeline-spec.md
rename to docs/spec.md
index 908ac4f..ead98d4 100644
--- a/bgg-shelf-pipeline-spec.md
+++ b/docs/spec.md
@@ -1,4 +1,8 @@
-# Shelf-to-BGG Collection Pipeline — Build Spec
+# Shelf-to-BGG Collection Pipeline — Design Contract
+
+> This is the pipeline's contract — what must stay true, and why — kept
+> current as the design evolves. Read it before changing pipeline
+> semantics. How to *use* the pipeline is the [user's guide](guide.md).
 
 ## Goal