MiniMax H3 on RunPod: install/download scripts, ComfyUI wiring, benchmark harness, research docs

- scripts/pod: weight downloads (workspace + tmpfs overflow for volume quota),
  extra_model_paths.yaml, headless ComfyUI launcher, test image generator,
  one-shot pod installer
- scripts/local: auto-reconnecting port forward for the ComfyUI panel
- bench: API-based harness for t2v/i2v/ref2v across durations, resolutions,
  and weight families; CSV/JSONL results
- docs: WEIGHTS.md (what's downloaded where), RESEARCH.md (ComfyUI guides,
  no-Comfy options via SGLang/vLLM/diffusers, concurrency model, serverless)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

README.md

@@ -1 +1,44 @@
-cloud-worker
+# cloud-worker
+
+Tooling for running the **MiniMax H3** open-weights video model (native stereo
+audio, 24 fps, 5–15 s, ~1 MP native) on RunPod GPU machines via ComfyUI.
+
+Current test rig: 1x B200 (180 GB) pod — connection details in `pod-info.txt`.
+
+## Layout
+
+- `scripts/pod/` — runs on the pod
+  - `install-minimax-h3.sh` — one-shot setup on a fresh pod (after `install-comfy.sh`)
+  - `download-weights.sh` — all weight families → `/workspace/minimax-h3/models`
+  - `download-weights-tmpfs.sh` — overflow files → `/dev/shm` (network-volume
+    quota workaround; ephemeral, re-run after pod restart)
+  - `extra_model_paths.yaml` — installed to `/ComfyUI/extra_model_paths.yaml`
+  - `start-comfyui.sh` — headless ComfyUI in tmux on 127.0.0.1:8188
+  - `make-test-images.py` — synthetic reference/first-frame images → `/ComfyUI/input`
+- `scripts/local/port-forward.sh` — persistent tunnel `localhost:8188` → pod
+  ComfyUI panel (auto-reconnects)
+- `bench/minimax_bench.py` — API-based benchmark harness (t2v / i2v / ref2v ×
+  duration × resolution × weight family); appends to `bench/results.csv` +
+  `bench/results.jsonl`
+- `docs/WEIGHTS.md` — which weights are downloaded, where, and which family
+- `docs/RESEARCH.md` — model/ComfyUI findings, running without ComfyUI
+  (SGLang / vLLM-Omni / diffusers), concurrency model, RunPod serverless
+- `docs/BENCHMARKS.md` — measured results on the B200
+
+## Quick start
+
+```bash
+# tunnel to the ComfyUI panel (leave running)
+scripts/local/port-forward.sh &
+open http://localhost:8188
+
+# one-off generation through the API
+python3 bench/minimax_bench.py --task t2v --width 864 --height 480 --seconds 5
+
+# smoke suite / full sweep
+python3 bench/minimax_bench.py --suite quick
+python3 bench/minimax_bench.py --suite sweep --prefix prunedint8_
+```
+
+On the pod, ComfyUI runs in tmux session `comfyui`
+(`tmux attach -t comfyui`), logs at `/workspace/minimax-h3/comfyui.log`.