docs: add spike quick start README

SPIKE-README.md

@@ -0,0 +1,106 @@
+# Phase 0 Spike — Quick Start
+
+This branch contains the Phase 0 Proof of Concept for streaming tmux output via WebSocket.
+
+## What This Does
+
+- Spawns a tmux session running `pi`
+- Streams the terminal output via `pipe-pane` to a FIFO
+- Broadcasts the stream over WebSocket to multiple clients
+- Demonstrates that pi runs cleanly in tmux and streaming is viable
+
+## How to Run
+
+### 1. Start the Spike Server
+
+```bash
+npm run spike
+```
+
+Output:
+```
+=== Phase 0 Spike: tmux Stream PoC ===
+
+[spike] Creating tmux session: pi-spike
+[spike] Created FIFO: /tmp/pi-spike.fifo
+[spike] Attached pipe-pane to session pi-spike
+[spike] WebSocket server listening on ws://127.0.0.1:7799/spike
+
+=== Spike Server Running ===
+
+To attach to the tmux session (in another terminal):
+  tmux attach -t pi-spike
+
+WebSocket endpoint:
+  ws://127.0.0.1:7799/spike
+
+To test with the HTML client:
+  open /path/to/spike-client.html
+
+To stop: Ctrl+C in this terminal
+```
+
+### 2. Attach to the tmux Session
+
+In a separate terminal:
+
+```bash
+tmux attach -t pi-spike
+```
+
+Now you can interact with pi normally. Any output will be streamed to connected WebSocket clients.
+
+To detach: `Ctrl+B`, then `D`
+
+### 3. Connect a Client
+
+#### Option A: HTML Client (recommended)
+
+```bash
+open extensions/remote-control/spike-client.html
+```
+
+This opens a browser with xterm.js that renders the stream in real-time.
+
+#### Option B: Raw WebSocket (for testing)
+
+```bash
+node -e "
+const WebSocket = require('ws');
+const ws = new WebSocket('ws://127.0.0.1:7799/spike');
+ws.on('message', (data) => process.stdout.write(data));
+"
+```
+
+### 4. Stop
+
+- Press `Ctrl+C` in the terminal running the spike server
+- Or: `pkill -f "tsx.*spike.ts"`
+- Cleanup: `tmux kill-session -t pi-spike`
+
+## Files
+
+- `extensions/remote-control/spike.ts` — Main spike implementation
+- `extensions/remote-control/spike-client.html` — Test client with xterm.js
+- `run-spike.sh` — Wrapper script
+- `docs/reference/PHASE-0-report.md` — Full report with findings
+
+## Key Findings
+
+✅ **Works:** Pi runs cleanly in tmux, ANSI streaming works, latency is excellent (< 50ms localhost)
+
+⚠️ **Issue:** tmux's `pipe-pane` can disconnect after certain operations (e.g., alternate screen buffer usage). Not a blocker for PoC, but Phase 1 should use `node-pty` instead.
+
+See the full report: `docs/reference/PHASE-0-report.md`
+
+## Next Steps
+
+This branch is kept for reference. The PoC validated the approach.
+
+**Phase 1** will rebuild from scratch with:
+- `node-pty` instead of `pipe-pane`
+- Ringbuffer for replay/snapshot
+- WebSocket compression (`permessage-deflate`)
+- Proper error handling and reconnection
+
+See `docs/SYNC.md` for current status.