From b38311021c3e134261a178acb41be760ee6dfd04 Mon Sep 17 00:00:00 2001
From: m3ultra <m3ultra@m3ultra.local>
Date: Fri, 17 Jul 2026 16:49:16 +1000
Subject: [PATCH] Add README: run, read order, lane model, new-machine setup

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 README.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c2f41bb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,82 @@
+# SHADES — rig it, then survive the night
+
+Geometry/tower-defense: you're a small person rigging shade sails against
+Australian storms. three.js r175 (vendored, no build step) + a zero-dep
+Python server. Everything the repo needs is in the repo.
+
+## Run it
+
+```
+python3 server.py --port 8801     # any free port
+# game:     http://localhost:8801/web/world/index.html
+# selftest: http://localhost:8801/web/world/selftest.html   (must be all green)
+# 2D proto: http://localhost:8801/prototype/index.html      (the original thesis)
+```
+
+No pip, no npm, no build. Python 3.8+ and a browser.
+
+## Read in this order
+
+1. `DESIGN.md` — the design canon (what the game is)
+2. `PLAN3D.md` — the build canon (stack, contracts, lane model)
+3. `THREADS.md` — the append-only lane log. **The project's memory.** Read the
+   last few `[I]` integrator entries to know the current state.
+4. `SPRINT11.md` — the current sprint (highest-numbered SPRINTn.md wins)
+5. `LANE_PROMPTS.md` — copy-paste prompts per lane, per sprint (bottom = newest)
+
+## The lane model (how this repo is built)
+
+Five parallel Opus agents ("lanes"), each in its OWN clone, on its own branch:
+
+| lane | owns |
+|---|---|
+| A | main.js, world.js, camera, hud, week, sites, server — shell & integration, merge shepherd |
+| B | sail.js, rigging — cloth sim, economy, balance.test pen |
+| C | weather, skyfx, debris, storm/site wind data |
+| D | player, interact, ladder, broom — and the designated playtester |
+| E | Blender asset factory (tools/blender), models/, textures |
+
+Hard rules (they exist because each was earned — see THREADS):
+- **One clone per lane.** Never two agents in one working tree.
+- Rebase onto latest `main` before starting; small commits; push your branch.
+- File ownership is the merge strategy; cross-lane needs go in THREADS.md.
+- Selftest green after every landing. Skips must be real. An assert that
+  cannot fail is decoration.
+- All sim code is deterministic `(dt, t)` — no Date.now, no rAF.
+- Measure, don't reason: the repo's biggest bugs were all "a number gathered
+  from the wrong harness". When two harnesses disagree, find the variable.
+
+## Setup on a new machine
+
+Gitea's SSH runs over tailscale (the public host is Cloudflare-proxied, no
+direct SSH). Add to `~/.ssh/config`:
+
+```
+Host gitea.partly.party
+    HostName 100.71.119.27
+    Port 222
+    User git
+```
+
+Then:
+
+```
+git clone git@gitea.partly.party:monster/shades.git ~/Documents/shades
+for L in A B C D E; do
+  git clone git@gitea.partly.party:monster/shades.git ~/Documents/shades-lane$L
+  git -C ~/Documents/shades-lane$L checkout -B lane/$(echo $L | tr 'A-Z' 'a-z') origin/lane/$(echo $L | tr 'A-Z' 'a-z')
+done
+```
+
+`~/Documents/shades` is the integration checkout (main; where merges and
+sprint docs happen). The five `shades-lane*` clones are where lane agents run.
+
+## Sprint cycle
+
+1. Fire lanes with the newest prompts at the bottom of `LANE_PROMPTS.md`
+   (Lane A usually first if the sprint gives it rulings/blocking items).
+2. Lanes work, push their branches, log in THREADS.md.
+3. Integrate in the main checkout: merge `origin/lane/{e,c,b,d}` (THREADS.md
+   conflicts resolve keep-both-chronological; real code conflicts get read),
+   run selftest, play the result, write `SPRINT(n+1).md` + prompts, push main
+   AND fast-forward all five `lane/*` branches to main.