diff --git a/CLAUDE.md b/CLAUDE.md
index 5ce3f4e1..47133edb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -36,6 +36,7 @@ should be typed here again.
 | what the collector sends | `docs/COLLECTOR-INTEGRATION.md`, ADR-006 |
 | how a site is deployed | `docs/INSTALL-WINDOWS.md`, `docs/OPERATE-WINDOWS.md` |
 | how code reaches GitHub | `tools/export-github.sh` |
+| which branch reaches which server | `devnotes/deploy-and-branch-model.html` |
 
 ## Standards are gates, not prose
 
@@ -102,7 +103,9 @@ surface and always ships.
 - `shopdb/plugins/loader.py` - discovery and dependency-aware loading
 - `shopdb/plugins/alembic_template.py` - the env every plugin chain runs through
 - `frontend/src/router/index.js`, `frontend/src/components/AppSidebar.vue`
-- `tools/export-github.sh` - scrub and publication gate
+- `tools/export-github.sh` - scrub and publication gate; builds the dist for
+  the branch it is on (`wj` -> /shopdb, `dev` -> /ops) and refuses on any other
+- `tools/mirror-wilm.sh` - push a carried wilm bundle to gitea
 
 ## State
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5fddca00..83a739fe 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -171,15 +171,32 @@ Tests are required for:
 
 ## Branches: what belongs on main, and what does not
 
-`main` is the product every site runs and the publication mirror exports.
-`<site>` branches hold work that is not ready for other sites to see. There are
-two: `wj` here, and `wilm` on the corporate GitHub, where the other site
-develops the .NET endpoint agent.
+`main` is the curated product other sites adopt, and what the publication
+mirror exports. It is a release decision: something reaching `main` says other
+sites should take it. **`main` is not what this site runs.**
+
+Each branch answers to one instance:
+
+| branch | runs on | contains |
+|---|---|---|
+| `dev` | the dev instance | work being validated |
+| `wj` | this site's PRODUCTION | everything this site runs |
+| `main` | nothing directly | the curated release for other sites |
+| `wilm` | the other site | their work, on the corporate GitHub |
+
+So work flows `dev` -> `wj` -> `main`: land it on `dev`, validate it on the dev
+instance, take it to `wj` for production, and promote to `main` what you are
+happy for another site to run. Promoting first and back-filling the site branch
+is the wrong way round - it puts unvalidated work in front of other sites and
+leaves production behind.
+
+`wilm` is not visible from the dev box because that machine has no account on
+the corporate GitHub, which is why `fetch-wilm-branch.cmd` exists to bring it
+back for review. It sits on the publication lineage, so it shares no ancestor
+with `main`/`wj`/`dev` and cannot be merged locally.
 
 A site branch is not a fork. Both feed `main`, and the sooner they do it the
-cheaper it is. A branch the dev box cannot see is still a branch: `wilm` is not
-visible from here because this machine has no GitHub account, which is why
-`fetch-wilm-branch.cmd` on the share exists to bring it back for review.
+cheaper it is.
 
 **Most work is product.** ADR-015 gives site differences three homes on `main`:
 a setting with a neutral default, seed data, or a site-namespaced directory