Queue executable speed and peer-to-peer sharing plans with tested patches and harnesses

plans/README.md

@@ -0,0 +1,22 @@
+# plans/
+
+Executable plan queue (skills `plan-queue` / `run-queue`). Each file in `queue/` is
+self-contained: exact files, anchors, code and copy-paste verification.
+
+- `INDEX.md` — the order and status of every plan.
+- `queue/ active/ done/ failed/` — plan lifecycle.
+- `patches/` — unified diffs referenced by plans (`git apply plans/patches/<name>.diff`).
+  They were produced from code that passed its tests, and are meant to be applied in plan
+  order (e.g. `016-media-cache-adopt.diff` expects `009` and `010` applied). If a patch
+  does not apply, stop and report — never hand-edit around it.
+- `harness/` — small throwaway servers + Playwright checks that exercise the browser
+  side of the P2P plans for real (OPFS, IndexedDB, WebSocket, WebRTC). Run the server
+  from `server/` (`bun ../plans/harness/<x>-server.js`), then `node <x>-check.mjs` from
+  `plans/harness/` (needs `npm i --no-save playwright` and a Chromium; the cloud image has
+  one at `/opt/pw-browsers/chromium-1194/chrome-linux/chrome`, override with `CHROMIUM=`).
+
+Environment notes: server tests need `cd server && bun install`; media / intake tests need
+`ffmpeg` + `ffprobe`; plan 003 needs network access to Google Fonts once; plan 007's
+pool test needs `bin/yt-dlp` (`npm run setup`) or skips.
+Stop a background server by PID (`… & SRV=$!` … `kill $SRV`) — `pkill -f <name>` also
+matches the shell running the command and kills it.