diff --git a/README.md b/README.md
index 53a778b72..07ce84032 100644
--- a/README.md
+++ b/README.md
@@ -213,6 +213,59 @@ Two shared layouts do the composing, both in `library/layouts/`:
 - **`StackLayout`** — the opposite: elements stacked top-to-bottom at natural height, so the page
   scrolls through them.
 
+### Working fast: use the dev server, not the build
+
+A full `bun run build` rebuilds every bundle and takes minutes. **You do not need it to see a
+change.** The dev server hot-reloads:
+
+```bash
+bun run dev                      # http://localhost:5173
+bun x vite --port 5299 --strictPort   # any other port, when 5173 is taken
+```
+
+★ **If more than one of you is working in this repo at once, EVERY dev server must name its own
+port, and must pass `--strictPort`.** Vite's default behaviour on a busy port is to silently move to
+the next one — 5173 becomes 5174 — and five gates (`check-facet-changes-map`,
+`plugin-gallery-smoke`, `smoke-studio`, `generate-gallery`, `check-scrim-covers-viewport`) have
+`5173` written into them. A second server without `--strictPort` therefore leaves those gates
+talking to somebody else's server, or to none, and reporting a confident wrong answer with no error.
+With `--strictPort` the duplicate exits non-zero instead of drifting — verified: port taken → exit 1.
+
+Reach for the full build only when you need the deployable tree, an SRI-consistent leaf page, or a
+manifest. To check one bundle's compiled output without touching anyone else's:
+
+```bash
+BUNDLE=<name> bun x vite build   # this bundle only; does NOT clean the tree
+```
+
+### Everything must reach Forgejo
+
+**A local commit is invisible.** The Driver runs a laptop watcher against
+`git.nuxtbase.app/doxa-life/doxa-maps` and sees changes in the browser from THAT repo — so work that
+stops at `git commit` has not been delivered, no matter how well it was verified locally.
+
+Push every increment:
+
+```bash
+TOKEN="$(pass show vivarium/forgejo-certified-sandbox | head -1)"
+git -c http.postBuffer=524288000 \
+    push "https://oauth2:${TOKEN}@git.nuxtbase.app/doxa-life/doxa-maps.git" HEAD:doxa-maps-plugin-studio \
+    2>&1 | sed "s/${TOKEN}/[REDACTED]/g"
+unset TOKEN
+```
+
+Never write the credential into `.git/config` (see the clone note above), always filter output
+through `sed`, and prefer many small pushed commits over one large local one.
+
+★ After pushing to an INLINE url, `git log @{u}..` still reports the commits as unpushed, because git
+only moves a remote-tracking ref when it pushes to a NAMED remote. Sync it so the next reader is not
+misled:
+
+```bash
+git fetch "https://oauth2:${TOKEN}@git.nuxtbase.app/doxa-life/doxa-maps.git" \
+    'refs/heads/doxa-maps-plugin-studio:refs/remotes/origin/doxa-maps-plugin-studio'
+```
+
 ### The production build
 
 The dev server is for working. When you want the deployable tree: