Document deploy and log-observation workflow

Captures the hf-upload / git-push publish paths, the
HfApi.request_space_hardware call for switching flavors (frontmatter is
not a valid path), and the SSE build/run log endpoints with the
~/.cache/huggingface/token auth pattern.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -107,6 +107,78 @@ or needs unit tests without Gradio. Not needed today.
 - **Verdict styling uses emoji prefix, not inline HTML `<span>`.** `gr.Markdown`'s HTML handling
   varies across Gradio versions; emoji is reliably rendered.
 
+## Deploying and observing the Space
+
+The live Space is at **`olfronar/megastyle-comparison`**
+(https://huggingface.co/spaces/olfronar/megastyle-comparison). Local working copy is git-backed
+with `origin` pointing at the Space's git URL — normal `git push origin main` triggers a rebuild.
+
+### Publish a change
+
+```bash
+git add <files> && git commit -m "..." && git push origin main
+```
+
+For one-off blob pushes without a git clone:
+
+```bash
+hf upload olfronar/megastyle-comparison . --repo-type space --commit-message "..."
+```
+
+### Set hardware (ZeroGPU, etc.)
+
+Hardware is *not* set via README frontmatter. Use `HfApi.request_space_hardware`:
+
+```python
+from huggingface_hub import HfApi
+HfApi().request_space_hardware("olfronar/megastyle-comparison", hardware="zero-a10g")
+```
+
+Valid flavors include `cpu-basic`, `cpu-upgrade`, `t4-small`, `a10g-small`, `a10g-large`,
+`a100-large`, and `zero-a10g` (the legacy name still used for the ZeroGPU pool, which is
+currently backed by H200 hardware). You can also toggle via the Space's *Settings → Hardware*
+page; both paths write to the same field.
+
+### Observe build and run logs
+
+HF exposes Server-Sent-Events streams for both phases. They require the user's HF token (read
+it from `~/.cache/huggingface/token` after `hf auth login`). Capped-timeout curl works for
+point-in-time snapshots:
+
+```bash
+# Build phase (docker layers, pip install)
+curl -s --max-time 20 \
+  -H "Authorization: Bearer $(cat ~/.cache/huggingface/token)" \
+  "https://huggingface.co/api/spaces/olfronar/megastyle-comparison/logs/build" | tail -80
+
+# Run phase (Python stdout/stderr, Gradio startup)
+curl -s --max-time 20 \
+  -H "Authorization: Bearer $(cat ~/.cache/huggingface/token)" \
+  "https://huggingface.co/api/spaces/olfronar/megastyle-comparison/logs/run" | tail -80
+```
+
+Each event line is JSON with `data` and `timestamp` fields. Because it's SSE, the stream is
+long-lived — always use `--max-time` to bound it.
+
+### Check high-level state
+
+```bash
+curl -s "https://huggingface.co/api/spaces/olfronar/megastyle-comparison" | \
+  python3 -c "import sys, json; d=json.load(sys.stdin); r=d.get('runtime',{}); \
+  print('stage:', r.get('stage'), 'hardware:', r.get('hardware'), 'sha:', d.get('sha','?')[:7])"
+```
+
+`stage` values: `BUILDING` → `RUNNING` (healthy) or `RUNTIME_ERROR` / `BUILD_FAILED` (check logs).
+
+### Common fix cycles
+
+- **Runtime import / missing dep**: edit `requirements.txt` or the affected import, commit, push,
+  stream the run logs until `RUNNING`. Most fixes don't need a full rebuild — layer caching makes
+  re-pushes with unchanged deps very fast.
+- **Hardware change**: one `HfApi().request_space_hardware(...)` call — no push, no rebuild.
+- **Stuck build**: use the *Settings → Factory Reboot* UI as a last resort; our Dockerfile is the
+  HF default so factory-reboot is safe.
+
 ## Working with the Hugging Face Hub
 
 - Model weights (`megastyle_encoder.pth`) should be pulled at runtime via `huggingface_hub.hf_hub_download`,