docs: rewrite CLAUDE.md with Spaces lessons + add SKILLS.md process guide

CLAUDE.md (heavily updated):
- Spaces deployment specifics: preload_from_hub + cache mirror, allowed_paths,
HF widget z-index coexistence, dynamic ZeroGPU duration + auto-retry,
history_result-across-subprocess gotcha, custom node pinning
- New section on Gradio scoping facts (CSS prefix, script stripping,
z-index 40 baseline)
- Per-mode behavior summary
- Common pitfalls section restructured by area (ComfyUI/models, Gradio/UI,
Spaces, authoring)

SKILLS.md (new):
- Process rules: investigate before fix, Playwright before patch, web-search
literal errors, sequential-thinking on 2nd failed fix
- Verification: local before push, smoke tests, isolated function tests
- Run/stop the local server, get LAN IP for WiFi testing
- Push lifecycle and when not to push
- Spaces deploy lifecycle
- Memory entries (cross-session preferences)
- Useful one-liners for stage/sha/registry audits

CLAUDE.md

@@ -2,6 +2,10 @@
 
 Working notes for AI assistants and subagents implementing this project.
 
+> Companion: see `SKILLS.md` for process rules — how to investigate, verify,
+> commit, and ship changes here. This file is the *what* and *why*; SKILLS.md
+> is the *how*.
+
 ---
 
 ## ⚠ Git authorship — sole author rule
@@ -10,14 +14,12 @@ Working notes for AI assistants and subagents implementing this project.
 
 When committing:
 
-- Do **NOT** append `Co-Authored-By: Claude ...` (or any other agent name) to commit messages.
-- Do **NOT** add "Generated with Claude Code", "🤖 Generated with...", or any other attribution footer.
+- Do **NOT** append `Co-Authored-By: Claude ...` (or any other agent name).
+- Do **NOT** add "Generated with Claude Code" / "🤖 Generated with..." footers.
 - Do **NOT** pass `--author=...` — let git use the user's existing config.
 - Do **NOT** include attribution in PR descriptions.
 
-If asked to amend, re-commit, or rebase, strip any prior agent attribution from the commit message.
-
-This rule overrides the default Claude Code commit-message template. Treat any tooling that suggests adding a Claude trailer as a bug to ignore.
+If asked to amend, re-commit, or rebase, strip any prior agent attribution from the commit message. Treat any tooling that suggests adding a Claude trailer as a bug to ignore.
 
 ---
 
@@ -27,19 +29,121 @@ Gradio app wrapping the existing ComfyUI LTX 2.3 All-In-One workflow into mode-s
 
 **Spec:** `docs/superpowers/specs/2026-04-30-ltx23-aio-generator-design.md`
 **Plan:** `docs/superpowers/plans/2026-04-30-ltx23-aio-generator.md`
+**Future-improvements backlog:** `docs/future_improvements.md`
 
 If you're a subagent picking up a task, the plan file is your assignment.
 
 ---
 
+## Modes (six)
+
+`t2v` text→video · `i2v` image→video · `a2v` audio→video · `lipsync` (image+audio) · `keyframe` (first+last frame→video) · `style` (preprocessor + IC-LoRA → restyle).
+
+Each is a separate API-format JSON in `workflows/`. Per-mode parameter patches live in `modes.py` `parameterize_fn`.
+
+---
+
 ## Architectural facts (locked — do not relitigate)
 
-1. **Backend is ComfyUI in library mode.** We call `comfy.execution.PromptExecutor` directly with workflow JSONs we parameterize. We do **not** call `ltx-pipelines` directly. We do **not** run ComfyUI as a subprocess.
-2. **Six mode-specific workflow JSON files** in `workflows/`, derived from the master at `~/Projects/comfyui/user/default/workflows/1. LTX 2.3 All-In-One 260406-05.json` via `tools/extract_modes.py`. Do not hand-edit them.
-3. **Models live in HF cache (local) or `/data` (Spaces).** Never in this repo. `comfyui/models/` contains symlinks (local) or downloaded files (Spaces). Never commit `*.safetensors`, `*.gguf`, `*.bin`, or `*.pt`.
+1. **Backend is ComfyUI in library mode.** We call `comfy.execution.PromptExecutor` directly with workflow JSONs we parameterize. We do NOT run ComfyUI as a subprocess.
+2. **Six mode-specific workflow JSON files** in `workflows/` are user-exported "API format" from the master workflow. Do not hand-edit. Editor-format (with `nodes` array) does NOT work — `walk_workflow_for_models` and `PromptExecutor` both expect API format.
+3. **Models live in HF cache.** Local: `~/.cache/huggingface/hub` symlinked into `comfyui/models/<comfy_type>/`. Spaces: same hub cache mirrored into `~/hf-cache-rw/` (see "Spaces deployment" below). Never commit `*.safetensors`, `*.gguf`, `*.bin`, `*.pt`. The `assets/seed_inputs/` exception in `.gitignore` covers the small placeholder files.
 4. **One backend, one process.** The `@spaces.GPU` decorator is the only divergence between local and Spaces runtimes.
 5. **VRAM is ComfyUI's job.** The only `empty_cache()` calls live in `backend.py`'s `try/finally`. Don't sprinkle them elsewhere.
-6. **Bundled ComfyUI, never user's existing.** Local: git submodule. Spaces: runtime clone to `/data/comfyui`.
+6. **Bundled ComfyUI, never user's existing.** Local: git submodule. Spaces: runtime clone via `_git_clone()` in `app.py:_bootstrap()`.
+7. **comfy_dir resolves per-platform.** `~/comfyui` on Spaces (writable HOME), `<repo>/comfyui` locally. Both `app.py` and `backend.py` have `_comfy_dir()`-style helpers that MUST stay in sync.
+8. **Custom nodes are pinned to SHAs**, not branches. See `CUSTOM_NODES_PINNED` in `app.py`. `--branch <SHA>` doesn't work in `git clone`; we use init+fetch+checkout via `_git_clone()`.
+
+---
+
+## Spaces deployment specifics (where the gotchas live)
+
+### Model loading: `preload_from_hub` + runtime cache mirror
+
+HF Spaces' `preload_from_hub` directive in README YAML downloads listed files at build time into `~/.cache/huggingface/hub`. **Limitation: those files are owned by the build user** (root-ish). At runtime we run as uid 1000 and can't write there — any `hf_hub_download` for a non-preloaded file fails with `Permission denied (os error 13)`.
+
+**Fix:** `_mirror_preload_hf_cache()` in `app.py` walks the read-only preload tree once at bootstrap and builds a parallel writable tree at `~/hf-cache-rw/`:
+- `blobs/<sha>` files → **hardlinked** (zero-copy, shared inode, instant reads)
+- `snapshots/<commit>/...` symlinks → **preserved** (relative paths resolve within the mirror)
+- `refs/<branch>` → **byte-copied** (HF lib overwrites these on etag check; hardlinks would fail)
+- All dirs → mkdir (we own them)
+- Falls back to symlink if `os.link()` returns EXDEV (cross-device)
+
+Then sets `HF_HOME=~/hf-cache-rw` and `HF_HUB_CACHE=~/hf-cache-rw/hub`. After this, preloaded reads are instant cache hits AND lazy downloads write to dirs we own.
+
+The 10-entry cap on `preload_from_hub` is a hard HF limit. Total preload size cap is 150 GB (Spaces ephemeral storage). Current list is ~111 GB; see `docs/future_improvements.md` for what got dropped (84 GB of unused Lightricks transformers, 39 GB GGUF — both lazy-load when actually referenced).
+
+### Per-call ZeroGPU duration: dynamic estimator + auto-retry
+
+`@spaces.GPU(duration=N)` is a per-call timeout, not a billing cap. Shorter declared duration = faster queue priority on the shared pool. Setting a one-size-fits-all 600s caps everything in the slow lane.
+
+**`_duration_for(executor, workflow, output_ids, mode, preset, multiplier=1.0)`** in `backend.py` estimates from:
+- `_BASE_DURATION_S[mode]` — t2v 90s, lipsync 240s, style 360s, etc.
+- `_PRESET_MULT[preset]` — fast 1×, balanced 1.5×, quality 3×
+- `_frames_from_workflow(workflow)` — read from `EmptyLTXVLatentVideo` `length`
+- +60s cold-cache buffer, +0.3s/frame VAE decode
+- Clamped to `[60s, 900s]`
+
+`@spaces.GPU(duration=_duration_for)` decorates `_execute_workflow` — ZeroGPU calls the estimator with the same args.
+
+**Auto-retry on timeout** in `_on_generate` (app.py): if first attempt raises `gradio.exceptions.Error('GPU task aborted')`, classified as `category='gpu_timeout'`, the handler shows a "Retrying with extended GPU budget" banner and re-submits with `duration_multiplier=2.0`. The estimator clamps the retry at 900s anyway. One retry only.
+
+### Returning the video path through ZeroGPU's subprocess boundary
+
+`executor.history_result` was unreliable across the `@spaces.GPU` boundary — sometimes the parent process saw an empty dict even when the file was on disk. Fix: `_execute_workflow` reads `history_result["outputs"]` INSIDE the GPU context and returns the path string directly (picklable). Plus a filesystem fallback `_newest_recent_video()` that scans `comfyui/output/` for the newest mp4 modified in the last 60s.
+
+### `allowed_paths` for video output
+
+Gradio 5 refuses to expose files outside cwd / temp / `allowed_paths`. ComfyUI writes to `~/comfyui/output/...` which is outside our app's cwd `/home/user/app` on Spaces. `app.launch(..., allowed_paths=[str(_output_dir)])` whitelists the entire ComfyUI output tree. Without this, video generates fine but `gr.Video` shows blank.
+
+### HF Spaces' header widget z-index (DOM-injected)
+
+When a Space is loaded via the bare embed URL (`https://*.hf.space`), HF injects `#huggingface-space-header` at fixed `z-index: 20` in the top-right (the heart/share widget). Our header z-index has to coexist:
+- Default: header `z-index: 15` (below HF widget — visible)
+- Drawer open: `.drawer-elevated` class bumps to `z-index: 60` (above scrim 45 / drawer 50, hamburger × clickable as close)
+
+JS toggles `.drawer-elevated` on `.aio-header` in lockstep with `.drawer-open` on `.aio-shell`. Three call sites: hamburger onclick, click-outside dismisser (in `gr.Blocks(head=...)` because `<script>` in `gr.HTML` gets stripped), mode-button auto-close.
+
+### Custom nodes the workflow needs
+
+Pinned in `CUSTOM_NODES_PINNED` (`app.py`):
+
+```
+Lightricks/ComfyUI-LTXVideo
+kijai/ComfyUI-KJNodes
+rgthree/rgthree-comfy
+Kosinkadink/ComfyUI-VideoHelperSuite
+pythongosssss/ComfyUI-Custom-Scripts
+city96/ComfyUI-GGUF
+Fannovel16/comfyui_controlnet_aux
+evanspearman/ComfyMath
+Smirnov75/ComfyUI-mxToolkit
+DoctorDiffusion/ComfyUI-MediaMixer  (provides FinalFrameSelector)
+```
+
+Also `requirements.txt` includes deps the custom nodes need but their own `requirements.txt` files don't list (gguf, imageio_ffmpeg, opencv-python, matplotlib, diffusers, yt-dlp, psutil).
+
+---
+
+## UI design system: Topaz Cinema Slate
+
+Dark slate background + amber accent, IBM Plex typography. Defined as `_TOPAZ_THEME = gr.themes.Base(...).set(...)` in `app.py`. Custom CSS in `_CUSTOM_CSS` for everything Gradio's theme machinery doesn't cover (drawer, header, mode buttons, status banner).
+
+Layout: hamburger drawer. Pinned 220 px sidebar at ≥1024 px; below that, `position: fixed` overlay sliding from `left: -100%` to `left: 0` via `.aio-shell.drawer-open`.
+
+Mode-tag in header (`#aio-mode-tag`) shows current mode (T2V/A2V/I2V/LIPSYNC/KEY/STYLE), updated by JS in mode-button click handlers.
+
+Spec: `docs/superpowers/specs/2026-05-01-topaz-drawer-redesign-design.md`
+Plan: `docs/superpowers/plans/2026-05-01-topaz-drawer-redesign.md`
+
+---
+
+## Critical Gradio scoping facts
+
+- **Gradio prefixes user CSS** with `.gradio-container.gradio-container-<version> .contain ` — selectors that need to escape upward (`body:has(...)`, `html.foo .bar`) are rewritten to nonsense and silently break. Toggle classes via JS on elements INSIDE `.contain` (we use `.aio-shell` and `.aio-header`).
+- **Gradio strips `<script>` tags inside `gr.HTML`** at sanitization. Inline scripts MUST go in `gr.Blocks(head=...)` to actually run. The `_HEAD_HTML` string in `app.py` is where the global click-outside dismisser lives.
+- **Gradio's form labels have `z-index: 40`** built in. Anything we want above them (drawer, scrim) needs `z-index >= 41`. Our hierarchy: header (15 default → 60 elevated) > drawer (50) > scrim (45) > Gradio labels (40) > body.
+- **`onclick="..."` attributes on plain HTML buttons DO survive** sanitization. Use them for tiny per-element interactions (hamburger toggle).
 
 ---
 
@@ -47,40 +151,41 @@ If you're a subagent picking up a task, the plan file is your assignment.
 
 ### Language and structure
 
-- **Python 3.11.** No `match` statements (Spaces Python pin compatibility).
+- **Python 3.11.** No `match` statements (Spaces Python pin compatibility — Spaces base image is 3.10).
 - **Flat layout.** No `src/`, no nested packages. Top-level `.py` files only, each with one clear responsibility.
 - **No conda.** Always `python3.11 -m venv .venv`. System binaries via `brew`.
 
 ### Style
 
-- **No emojis** in code or commit messages unless the user explicitly asks. (UI text and stage labels in `modes.py`/`ui.py` are OK because they are user-facing — not code.)
+- **No emojis** in code or commit messages unless the user explicitly asks. UI text and stage labels in `modes.py` / `ui.py` are OK because they are user-facing — not code.
 - **Comments only for non-obvious WHY.** Never narrate WHAT. Code with a good name doesn't need a comment.
 - **Type hints on public functions.** Internal helpers can skip them if obvious.
-- **Imports at top of file.** No inline imports except where needed to break circular dependencies (e.g., `models.ensure_models_for_mode` imports `workflow` lazily — keep this, it's load-bearing).
+- **Imports at top of file.** Inline imports only to break circular deps (e.g., `models.ensure_models_for_mode` imports `workflow` lazily — keep this, it's load-bearing).
 - **Format with `ruff format`.** Lint with `ruff check`. Both must pass in CI.
 
+### Commits
+
+- **Conventional Commits style:** `<type>(<scope>): <subject>` — types: `feat`, `fix`, `chore`, `docs`, `test`, `refactor`, `ci`, `perf`.
+- **Subject is imperative, lowercase, no trailing period.**
+- **Body explains WHY when not obvious.** Reference spec/plan section if relevant.
+- **Frequent small commits.** One logical change per commit.
+- **No agent attribution** (see top of file).
+- See `SKILLS.md` for the full process around when to commit vs hold.
+
 ### Testing
 
-- **TDD per the plan.** Each implementation task has the failing test first. Don't skip the "run test, verify it fails" step — it catches whole classes of "test never actually exercised the code" bugs.
+- **TDD per the plan.** Each implementation task has the failing test first.
 - **No mocks for ComfyUI.** Tests run against real workflow JSONs. Stubs only for HTTP boundaries (HF Hub) and filesystem (use `tmp_path` and the `fake_hf_cache` fixture).
 - **L1 + L3 in CI** (no GPU). L2 + L4 are local-developer-only.
-- **Test naming:** `test_<unit>_<behavior_under_test>` — e.g., `test_load_template_returns_independent_copy`.
+- **Test naming:** `test_<unit>_<behavior_under_test>`.
 - **`pytest --gpu`** enables L4 smoke tests. Default skips them.
 - **`pytest --comfy-real`** uses bundled ComfyUI for L2 instead of the static stub validator.
 
-### Commits
-
-- **Conventional Commits style:** `<type>(<scope>): <subject>` — types: `feat`, `fix`, `chore`, `docs`, `test`, `refactor`, `ci`, `perf`.
-- **Subject is imperative, lowercase, no trailing period.** Example: `feat(workflow): set_input + validate over node graph`.
-- **Body explains WHY when not obvious.** Reference spec section if relevant.
-- **Frequent small commits.** One logical change per commit. The plan's task structure already reflects this.
-- **No agent attribution** (see top of file).
-
 ---
 
 ## Editing the master workflow
 
-When the user updates `~/Projects/comfyui/user/default/workflows/1. LTX 2.3 All-In-One 260406-05.json` (e.g., adds a LoRA, tweaks a sampler), regenerate the mode templates:
+When the user updates `~/Projects/comfyui/user/default/workflows/1. LTX 2.3 All-In-One 260406-05.json`:
 
 ```bash
 python3.11 tools/extract_modes.py \
@@ -90,20 +195,44 @@ python3.11 tools/extract_modes.py \
 
 Then run the test suite — L2 graph-validation catches any node that became invalid in any mode.
 
-After the templates regenerate, the node-id constants in `modes.py` (e.g., `T2V_NODE_PROMPT = 240`) may need updating if ComfyUI re-numbered nodes during the master's re-export. The procedure is in the plan's Task 11 Step 4.
+After templates regenerate, the node-id constants in `modes.py` (e.g., `T2V_NODE_PROMPT = 240`) may need updating if ComfyUI re-numbered nodes. Procedure in plan Task 11 Step 4.
+
+The user has explicitly said **don't change JSON** — when adding capabilities, prefer parameterize_fn patches over hand-edits. The user re-exports from ComfyUI editor when the workflow changes.
 
 ---
 
 ## Common pitfalls (read before opening a PR)
 
-- **Loading models eagerly at import time.** Don't. `backend.py` constructs `PromptExecutor` once at instantiation; models load only when nodes execute. Calling `comfy.sd.load_checkpoint(...)` at module top-level will OOM the test runner.
+### ComfyUI / models
+
+- **Loading models eagerly at import time.** Don't. `backend.py` constructs `PromptExecutor` once at instantiation; models load only when nodes execute.
 - **Hard-coded `torch.cuda` calls.** Use `comfy.model_management.get_torch_device()` or guard with `if torch.cuda.is_available()`. Never assume CUDA.
-- **Forgetting `.deepcopy` on workflow templates.** `workflow.load_template` already does this; if you bypass it for performance, you'll mutate the cached template and the second `Generate` click breaks.
-- **Hand-editing `workflows/<mode>.json`.** They're generated. If you need a new field, add it to `tools/extract_modes.py` (or to `modes.py`'s `parameterize_fn`).
-- **Symlinks pointing into `pip cache`.** Resolve to HF Hub's cache snapshot path (the one `hf_hub_download` returns), not pip's wheel cache.
-- **Adding `Co-Authored-By` because tooling suggests it.** See top of file. Strip it.
-- **Breaking the async generator pattern in `backend.submit`.** Each yield is a frame Gradio renders. Don't accumulate events into a list and yield once at the end — progress will appear stuck.
+- **Forgetting `.deepcopy` on workflow templates.** `workflow.load_template` already does this; if you bypass it for performance, you'll mutate the cached template.
 - **Importing `comfy.*` before `sys.path.insert(0, comfy_dir)`.** Will `ModuleNotFoundError`. The order in `backend.py:__init__` is intentional.
+- **`walk_workflow_for_models` returning empty.** Check that the workflow is API format (`{node_id: {class_type, inputs}}`), not editor format (`{nodes: [...]}`). The walker recurses into `Power Lora Loader` rows and skips ones with `on: false`.
+- **Hardcoded paths in seed inputs.** The workflow's `LoadImage` / `VHS_LoadVideo` nodes have baked-in default filenames (`Screenshot 2026-04-23 023318.jpeg`, `4. Lipsync Music.mp3`, etc.). Our `assets/seed_inputs/` covers the ones that ship with the master, plus `_stage_to_comfy_input` copies user uploads into `comfyui/input/`. If a workflow update adds a new default filename, add a placeholder file.
+- **`_COMFY_INPUT_DIR` and `_comfy_dir()` must agree.** Bug we hit: `app.py` had it hardcoded to `<repo>/comfyui/input` but on Spaces ComfyUI runs at `~/comfyui`. User uploads went to a directory ComfyUI never read. Both have to use the same on-Spaces vs local logic.
+
+### Gradio / UI
+
+- **Adding `<script>` to `gr.HTML`.** Gets stripped. Use `gr.Blocks(head=...)`.
+- **Selectors that escape `.contain`.** Gradio rewrites them. Use a class on `.aio-shell` or `.aio-header` instead.
+- **`gr.Video` paths outside cwd.** Need `allowed_paths=` on launch.
+- **Z-index above HF's injected widget.** Header default z-index must be < 20 to not cover the heart/share widget. We use 15, bump to 60 only when drawer is open.
+
+### Spaces
+
+- **`/data` requires the persistent-storage add-on** (separate paid feature, not included in Pro). We use `~/comfyui` and `~/hf-cache-rw` instead.
+- **Build user vs runtime user permissions.** preload_from_hub files are read-only for us. Mirror them — see "Spaces deployment specifics" above.
+- **`@spaces.GPU` requires module-level decoration.** Runtime-applied decoration isn't detected by ZeroGPU's startup analyzer. Module-level static decorator + dynamic-duration callable is the supported pattern.
+- **`history_result` may not survive ZeroGPU's subprocess boundary.** Compute outputs INSIDE the decorated function and return primitive types (str, int, dict of strs).
+- **`allowed_paths` on `app.launch()`** must include the ComfyUI output dir or videos won't display.
+- **Custom Dockerfile breaks ZeroGPU.** ZeroGPU is exclusively compatible with `sdk: gradio`. Switching to `sdk: docker` loses GPU access.
+
+### Authoring
+
+- **Adding `Co-Authored-By` because tooling suggests it.** See top of file. Strip it.
+- **Don't push during HF testing.** When the user is running tests on the live Space, hold local commits until they say push. They'll explicitly tell you when to push.
 
 ---
 
@@ -113,19 +242,22 @@ These are documented as v1.1+ in spec § 11. Don't pre-build them just because t
 
 - **Lite mode** (`LTX23_AIO_LITE=1`) for free HF Spaces tier
 - **Custom LoRA** add/remove rows (Power-Lora-Loader clone)
-- **GGUF Q4 transformer** / "Low VRAM" preset
+- **GGUF Q4 transformer** / "Low VRAM" preset (the GGUF is loaded but always BF16-served at the moment)
 - **Auto-launch of user's external ComfyUI** (`LTX23_AIO_COMFYUI_URL`)
 - **Multi-prompt queueing**
 - **Output history persistence** across sessions
 - **Visual regression tests** for the Gradio UI
 - **Property-based / fuzz testing** of workflow parameters
+- **Persistent Storage add-on integration** (see future_improvements.md item 6)
+- **Telemetry-driven duration estimator** (see future_improvements.md item, requires persistent storage)
 
-If a task feels like it needs one of these, stop and ask the user. Don't sneak it in.
+If a task feels like it needs one of these, stop and ask the user.
 
 ---
 
 ## When in doubt
 
-Read the spec (`docs/superpowers/specs/2026-04-30-ltx23-aio-generator-design.md`) and the plan (`docs/superpowers/plans/2026-04-30-ltx23-aio-generator.md`). If still unclear after reading both — ask the user before changing architectural shape.
-
-Reading both takes 15 minutes. Implementing the wrong thing takes a day.
+1. Read the spec and plan. 15 min of reading vs a day of wrong implementation.
+2. Read `docs/future_improvements.md` to see if the change you're considering is already on a known list.
+3. Check `git log --oneline` for similar changes — most non-obvious decisions have a fix-commit explaining the reasoning.
+4. Ask the user before changing architectural shape.

SKILLS.md

@@ -0,0 +1,298 @@
+# Skills — how to make changes in this project
+
+Process rules and habits for AI assistants working on this repo. Companion to `CLAUDE.md` (which is *what & why*); this file is *how*.
+
+> Default rule when in doubt: **stop and ask the user**. The user prefers a question over wrong work.
+
+---
+
+## Investigation before fix
+
+### Reproduce the bug visually before patching CSS / UI
+
+When the user reports a layout, color, click, or visibility issue, **the first action is Playwright + screenshot, not code**. The user has called this out explicitly:
+
+> "Make sure to check playwright with screenshot to verify issues before making fix."
+
+Skipping the visual repro twice in a row produced patches that addressed a different symptom than what the user was seeing. Reproduce, then fix, then re-screenshot to verify the fix.
+
+**Tools:** local dev server (port 7860, see "Running locally" below) + `mcp__playwright__browser_*` tools. Resize to the affected viewport (typically 380 px / 900 px / 1280 px). `browser_evaluate` is the most reliable way to inspect DOM state — getBoundingClientRect, getComputedStyle, elementFromPoint.
+
+### Pull HF Space logs first when something runs there
+
+For Spaces failures, the run logs are the source of truth. Pull and search:
+
+```bash
+HF_TOKEN=$(hf auth token)
+curl -s -H "Authorization: Bearer ${HF_TOKEN}" \
+  "https://huggingface.co/api/spaces/techfreakworm/LTX2.3-Studio/logs/run" \
+  -o /tmp/hf_run.log
+
+# Find last submit and tail from there
+python3 << 'PY'
+import json
+events = []
+for line in open('/tmp/hf_run.log'):
+    line = line.strip()
+    if line.startswith('data: '):
+        try: events.append(json.loads(line[6:]))
+        except Exception: pass
+last = max(i for i, e in enumerate(events) if 'submitting workflow' in e.get('data', ''))
+for ev in events[last:]:
+    print(ev.get('timestamp', '')[:19], ev.get('data', '').rstrip()[:240])
+PY
+```
+
+`/logs/build` is the other endpoint. Build logs show preload, image-build, pip; run logs show container output.
+
+### Stage check before action
+
+```bash
+curl -s -H "Authorization: Bearer ${HF_TOKEN}" \
+  "https://huggingface.co/api/spaces/techfreakworm/LTX2.3-Studio" | jq -r '.runtime'
+```
+
+Stages: `BUILDING` (image), `APP_STARTING` (boot), `RUNNING`, `RUNTIME_ERROR`, `RUNNING_BUILDING` (live serving + new build queued). If `RUNTIME_ERROR` is non-null, that's your headline.
+
+### Sequential thinking for repeated failures
+
+The user has called this out:
+
+> "On 2nd failed fix, stop patching; use sequential-thinking MCP + brainstorming skill"
+
+If your first fix didn't land, **stop patching**. Use `mcp__sequential-thinking__sequentialthinking` to think through the failure mode end-to-end, plus web search for canonical solutions. Do not loop on speculative one-line patches.
+
+### Web-search for HF / Gradio errors with the literal message
+
+HF docs change. The `Spaces Configuration Reference` and `Spaces ZeroGPU` pages often have undocumented behavior captured in forum threads. When you hit a Gradio/Spaces error, web-search the literal exception message. Examples that paid off:
+
+- `gradio.exceptions.InvalidPathError` → fix was `allowed_paths=` (Gradio 5 file-access policy)
+- `'Workload evicted, storage limit exceeded (150G)'` → 150 GB ephemeral cap
+- `'No @spaces.GPU function detected during startup'` → must be module-level decorator
+- `'GPU task aborted'` → `@spaces.GPU(duration=...)` cap
+
+---
+
+## Verification
+
+### Run the full repro in Playwright before declaring done
+
+After a UI fix, re-run the same Playwright sequence that exposed the bug. Take a screenshot. Read the DOM state. Don't trust "it should work now" — show that it does.
+
+### Local before push
+
+When iterating on app behavior, the local dev server gives instant feedback. The user explicitly asks for this — they do most testing on the WiFi-accessible local URL. **Never push during HF testing windows.** When the user is testing on the live Space, hold local commits until they say push.
+
+```bash
+# In repo root
+source .venv/bin/activate
+python app.py  # or background it; see "Running locally"
+```
+
+The user has stated:
+
+> "DO NOT PUSH since testing is happening on HF"
+
+When in doubt, hold and ask.
+
+### Smoke import + build_app after backend/app changes
+
+```bash
+python -c "import app; b = app.build_app(); print(type(b).__name__)"
+```
+
+Should print `Blocks`. Catches most syntax / import-cycle issues without spinning up the full server.
+
+### Sanity-test isolated functions when changing logic
+
+For workflow walkers, model registry, duration estimators — write a tiny `python3 -c '...'` or HEREDOC to feed synthetic inputs and verify outputs. Faster than running the full app, catches regressions that the full app would mask.
+
+---
+
+## Running locally
+
+### Standard launch (port 7860)
+
+```bash
+cd /Users/techfreakworm/Projects/llm/ltx2.3-AIO-generator
+source .venv/bin/activate
+nohup python app.py > /tmp/ltx_studio_run.log 2>&1 &
+echo $! > /tmp/ltx_studio.pid
+```
+
+Wait ~18 seconds for ComfyUI to import + Gradio to bind, then check:
+
+```bash
+lsof -nP -iTCP:7860 -sTCP:LISTEN
+```
+
+### LAN-accessible URL
+
+Bound to `0.0.0.0:7860` by default. Get the LAN IP:
+
+```bash
+ipconfig getifaddr en0 || ipconfig getifaddr en1
+```
+
+Open `http://<LAN_IP>:7860` on phone/tablet on the same WiFi. macOS firewall: allow inbound for `python` if connection refused.
+
+### Stop
+
+```bash
+PID=$(cat /tmp/ltx_studio.pid)
+kill -9 $PID
+lsof -nP -iTCP:7860 -sTCP:LISTEN | awk 'NR>1 {print $2}' | xargs -r kill -9
+```
+
+---
+
+## Pushing changes
+
+### Two remotes
+
+```bash
+git push origin master                                                 # GitHub
+HF_TOKEN=$(hf auth token)                                              # HF auth
+git push "https://techfreakworm:${HF_TOKEN}@huggingface.co/spaces/techfreakworm/LTX2.3-Studio" master:main
+```
+
+GitHub: `master`. HF Space: `main`. The Space accepts force-push only with explicit user consent.
+
+### When to push
+
+- Default: hold all commits locally, ask the user before pushing.
+- The user usually says "push" or "push them" when ready.
+- During the user's HF testing windows, NEVER push.
+- After a successful local Playwright verification of a fix, summarize the queued commits and ask.
+
+---
+
+## Spaces deploy lifecycle
+
+Each push triggers a Docker image rebuild. Most layers are cached unless requirements.txt or README YAML changes. The first push that adds/changes `preload_from_hub:` triggers a long preload step (download all listed files into `~/.cache/huggingface/hub`).
+
+Container start sequence (after image push):
+1. HF brings up the container as user 1000
+2. Our `_bootstrap()` runs:
+   - clones ComfyUI + custom nodes (cold-start only — frozen ZeroGPU containers retain them)
+   - pip installs each custom node's requirements
+   - `_mirror_preload_hf_cache()` builds writable cache mirror
+   - copies seed inputs
+   - sets HF_HOME / HF_HUB_CACHE env vars
+3. `gr.Blocks(...).launch()` binds 7860
+4. Stage transitions to `RUNNING`
+
+ZeroGPU container freeze on idle: keeps `~/comfyui`, `~/hf-cache-rw`, etc. Wake on next request restores in seconds. Push or rebuild loses everything.
+
+---
+
+## When the user says "deep think"
+
+The user explicitly invokes deeper investigation when stuck:
+
+> "Use deep thinking using sequential thinking and web search and code exploration."
+
+Use `mcp__sequential-thinking__sequentialthinking` to lay out the problem end-to-end. Web-search literal error messages. Read code beyond the immediate failure site. Avoid speculative one-line patches when in this mode.
+
+---
+
+## What never to do
+
+- **Push without explicit permission** during HF test windows.
+- **Add Co-Authored-By** or any agent attribution to commit messages.
+- **Hand-edit `workflows/*.json`** — the user re-exports from ComfyUI editor.
+- **`chmod` the HF preload cache** — we don't own it. See cache-mirror approach in CLAUDE.md.
+- **Switch `sdk: gradio` → `sdk: docker`** in README. Loses ZeroGPU.
+- **Move models into the repo via git LFS without asking.** Pro has 1 TB LFS but bandwidth is finite.
+- **Implement out-of-scope v1.1+ features** without asking. See "Out of scope" in CLAUDE.md.
+- **Eagerly load models at module import.** `_bootstrap()` only ensures clones + cache mirroring. Model load happens when ComfyUI's executor evaluates a node.
+
+---
+
+## Memory (cross-session)
+
+The user's preferences live at `~/.claude/projects/-Users-techfreakworm-Projects/memory/`. Key entries:
+
+- **Git authorship:** sole author, no co-author footers
+- **Verify before fix:** Playwright + screenshot first
+- **Don't push during HF testing:** hold local commits
+- **Autonomous execution:** prefer scripts over notebooks, report results
+- **No conda:** `python3.11 -m venv`, brew for system bins
+- **Tests folder:** keep `~/Projects/tests/` separate from `~/Projects/`
+
+When the user asks to remember something new, save it as a memory file and update `MEMORY.md` index.
+
+---
+
+## When stuck for too long
+
+Three escalation steps:
+
+1. **`mcp__sequential-thinking__sequentialthinking`** — think the whole flow through, identify the unknown.
+2. **WebSearch + WebFetch** — find canonical fix or known issue.
+3. **Ask the user** — describe what's been tried, what's still unknown, propose options.
+
+Do not loop on patches when you've patched twice and it's still broken.
+
+---
+
+## Repo structure (high level)
+
+```
+.
+├── app.py               # Gradio entry, _bootstrap, _on_generate, build_app
+├── backend.py           # ComfyUILibraryBackend, _execute_workflow, _GPU
+├── modes.py             # MODE_REGISTRY + per-mode parameterize_fn + node-id constants
+├── models.py            # MODEL_REGISTRY, walk_workflow_for_models, ensure_models
+├── ui.py                # render_status, _render_idle, mode-form layout primitives
+├── workflow.py          # load_template, set_input
+├── workflows/           # API-format mode JSONs (do not hand-edit)
+│   ├── t2v.json
+│   ├── i2v.json
+│   ├─�� a2v.json
+│   ├── lipsync.json
+│   ├── keyframe.json
+│   └── style.json
+├── assets/seed_inputs/  # placeholder image/audio/video for cold-start (gitignored except this dir)
+├── docs/
+│   ├── superpowers/specs/    # design specs (per-feature)
+│   ├── superpowers/plans/    # implementation plans (per-feature)
+│   └── future_improvements.md
+├── tools/extract_modes.py    # regenerate workflows/ from master
+├── tests/
+├── README.md            # HF Space YAML + project description
+├── CLAUDE.md            # what & why (this project's facts)
+├── SKILLS.md            # how (this file)
+├── requirements.txt
+└── comfyui/             # git submodule (local) / runtime clone target (Spaces)
+```
+
+---
+
+## Useful one-liners
+
+```bash
+# What's the Space's current SHA vs local HEAD
+hf_sha=$(curl -s -H "Authorization: Bearer $(hf auth token)" \
+  "https://huggingface.co/api/spaces/techfreakworm/LTX2.3-Studio" \
+  | jq -r '.sha')
+echo "HF: ${hf_sha:0:8}  local: $(git rev-parse HEAD | cut -c1-8)"
+
+# Local commits ahead of origin
+git log origin/master..HEAD --oneline
+
+# All class_types referenced by workflows (cross-check against custom_nodes)
+python3 -c "import json, glob, sys
+seen = set()
+for p in glob.glob('workflows/*.json'):
+    seen |= {n.get('class_type','') for n in json.load(open(p)).values()}
+for c in sorted(seen): print(c)"
+
+# Models referenced by workflows but not in registry
+python3 -c "import json, glob, models
+needed = set()
+for p in glob.glob('workflows/*.json'):
+    needed |= models.walk_workflow_for_models(json.load(open(p)))
+unmapped = needed - set(models.MODEL_REGISTRY)
+print('unmapped:', sorted(unmapped) or 'none')"
+```