docs: revamp README + add AGENTS.md + refresh SKILLS.md

- README.md: opensource-style intro with badges, modes table, architecture
diagram, project layout, tech stack, design, license + credits (Danielle
Falco / FutuTek for the original All-In-One ComfyUI workflow).
- AGENTS.md: new tool-agnostic agent rulebook — seven rules, project shape,
locked-architecture-decisions table, commit / verification / testing rules,
out-of-scope list.
- SKILLS.md: cross-refs AGENTS.md from intro; push section now flags the
master:main refspec (orphan-branch trap); repo-structure listing includes
AGENTS.md.

AGENTS.md

@@ -0,0 +1,136 @@
+# AGENTS.md
+
+Tool-agnostic agent guidance for the `ltx2.3-AIO-generator` repo. If you're driving Claude Code, Cursor, Aider, Codex, or anything else with file-edit + shell access, **start here**.
+
+This file is the authoritative project rulebook.
+
+- `CLAUDE.md` — Claude-specific extensions and the full gotchas catalogue (what & why).
+- `SKILLS.md` — process / how-to (debugging, deployment, when to commit, useful one-liners).
+- `README.md` — public-facing project intro (different audience).
+
+---
+
+## TL;DR — the seven rules
+
+1. **Mayank Gupta is sole author on every commit.** No agent co-author trailers. No "generated with…" footers. No `--author=` flag. Strip any tool-suggested attribution.
+2. **Backend is ComfyUI in library mode.** We call `comfy.execution.PromptExecutor` directly with our parameterized workflow JSONs. We do NOT subprocess ComfyUI and we do NOT swap to a different inference engine.
+3. **Six mode workflows live in `workflows/` as user-exported API-format JSON.** Do not hand-edit. The user re-exports from the ComfyUI editor when the master changes; `python tools/extract_modes.py --master ... --out workflows` regenerates the six mode files.
+4. **Models live in the HF cache.** Local: `~/.cache/huggingface/hub` symlinked into `comfyui/models/<comfy_type>/`. Spaces: build-time `preload_from_hub` + runtime mirror to `~/hf-cache-rw/`. Never commit `*.safetensors`, `*.gguf`, `*.bin`, `*.pt`.
+5. **Don't pin `spaces` in `requirements.txt`.** HF Spaces' ZeroGPU build injects its own version; pinning causes pip-resolve failure.
+6. **HF Space deploys from `main`. Local default branch is `master`.** Push with `git push space master:main` — bare `git push space master` creates an orphan remote branch that does NOT trigger a deploy.
+7. **VRAM is ComfyUI's job.** The only `empty_cache()` calls live in `backend.py`'s try/finally. Don't sprinkle them elsewhere.
+
+If you can't satisfy any of these without changing architectural shape, **ask the user before proceeding.**
+
+---
+
+## Project shape
+
+Single-process Gradio 5.50 app, flat top-level Python layout, ~3.5 k LOC excluding the ComfyUI submodule. ComfyUI itself is vendored as a git submodule locally and runtime-cloned into `~/comfyui` on HF Spaces.
+
+```
+app.py            Gradio Blocks entry · _bootstrap · _on_generate · header drawer
+backend.py        ComfyUILibraryBackend · @spaces.GPU · _execute_workflow · duration estimator
+modes.py          MODE_REGISTRY + per-mode parameterize_fn + node-id constants
+models.py         MODEL_REGISTRY · walk_workflow_for_models · ensure_models_for_mode
+ui.py             render_status · _render_idle · mode-form layout primitives
+workflow.py       load_template · set_input helpers
+workflows/        Six API-format mode JSONs — DO NOT hand-edit
+assets/           Seed input placeholders for cold-start staging
+tools/            extract_modes.py — regenerate workflows/ from a master export
+docs/superpowers/ Spec + plan + brainstorm artifacts (per feature)
+tests/            L1 + L2 + L3; GPU smoke gated by --gpu
+comfyui/          Submodule (local) / runtime clone target (Spaces)
+```
+
+Same code path everywhere. The only branching is in `_bootstrap()` (cache-mirror dance on Spaces; plain symlink locally) and the `@spaces.GPU` decorator (identity off Spaces).
+
+---
+
+## Locked architecture decisions
+
+These came out of 100+ commits of iteration. Do not relitigate.
+
+| Decision | Why | Code reference |
+|---|---|---|
+| ComfyUI library mode (no subprocess) | Direct executor access; shared Python process for model lifecycle and progress reporting | `backend.ComfyUILibraryBackend.__init__` |
+| Six API-format workflow JSONs | API format (`{node_id: {class_type, inputs}}`) is what `PromptExecutor` + `walk_workflow_for_models` consume. Editor format silently fails. | `workflows/*.json` |
+| Workflow parameterization via patches | The user owns workflow shape via ComfyUI editor exports; we only patch leaf inputs. Never hand-edit JSON. | `modes.parameterize_fn` |
+| Custom nodes pinned to SHAs (not branches) | Reproducible builds; `git clone --branch <SHA>` is unsupported — we use a `_git_clone()` init+fetch+checkout helper | `app.CUSTOM_NODES_PINNED`, `app._git_clone` |
+| HF cache → `comfyui/models/<type>/` symlinks | Avoids duplicate weight copies; HF cache stays the single source of truth | `models.symlink_hf_cache_to_comfy_layout` |
+| `_mirror_preload_hf_cache()` on Spaces | preload_from_hub files are owned by the build user (root-ish); the runtime user (uid 1000) can't write to them. Hardlink blobs + copy refs into a writable mirror under `~/hf-cache-rw/`. | `app._mirror_preload_hf_cache` |
+| `_comfy_dir()` per-platform | `~/comfyui` on Spaces (writable HOME); `<repo>/comfyui` locally. Both `app.py` and `backend.py` must agree. | `app._comfy_dir`, `backend._comfy_dir` |
+| `@spaces.GPU(duration=callable)` applied module-level | Runtime decoration isn't detected by ZeroGPU's startup analyzer. Static decorator + dynamic-duration callable is the supported pattern. | `backend._execute_workflow` |
+| Per-call duration estimator | A one-size-fits-all 600 s caps everything in the slow queue lane. Estimator reads frames + mode + preset + cold-cache buffer, clamps `[60, 900] s`. | `backend._duration_for` |
+| Auto-retry once at 2× on timeout | `"GPU task aborted"` is the queue-eviction signal; one retry catches transient busy queues. | `app._on_generate` |
+| `allowed_paths=[output_dir]` on launch | Gradio 5 refuses files outside cwd / temp / `allowed_paths`. ComfyUI writes to `~/comfyui/output/...` on Spaces — outside the app cwd. | `app.app.launch(...)` |
+| Header `z-index: 15` default / `60` elevated | HF injects `#huggingface-space-header` at fixed z-index 20. Default keeps our header below it (HF widget visible); drawer-open bumps above the scrim. | `_CUSTOM_CSS` `.aio-header` |
+| Click-outside dismisser in `gr.Blocks(head=…)` | Gradio strips `<script>` tags inside `gr.HTML`. Inline scripts have to live in `<head>` to actually run. | `app._HEAD_HTML` |
+| Mode tag in header via inline `onclick` | `onclick="…"` attributes on plain HTML buttons survive sanitization (unlike inline `<script>`). Lets us update the tag without a server round-trip. | mode buttons in `build_app` |
+| Topaz Cinema Slate theme | Locked from brainstorming round. Slate `#1A1F26` + amber accent `#E0A458` + IBM Plex Sans. | `app._TOPAZ_THEME`, `_CUSTOM_CSS` |
+
+---
+
+## Commit rules
+
+- **Conventional Commits:** `<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 plan task IDs when implementing a specific plan step.
+- Frequent small commits; one logical change per commit.
+- **No agent attribution** in commit message or body. See rule 1.
+- Don't `git push --force` to `master` / `main` unless the user explicitly says so.
+
+---
+
+## Verification rules
+
+- **Tests must pass before committing.** `python -m pytest tests/ -q` from the project root. Default skips GPU markers.
+- **Ruff must be clean.** `ruff check . && ruff format --check .` — both no-op.
+- **Smoke import after backend / app edits.** `python -c "import app; b = app.build_app(); print(type(b).__name__)"` should print `Blocks` without traceback. Catches most syntax / import-cycle issues without spinning up the full server.
+- **For UI changes:** start the local server (`python app.py` → http://127.0.0.1:7860), click through the affected mode, verify visually. Don't trust a green test run + clean ruff as proof the UI works — the test suite doesn't render Gradio Blocks.
+- **For deployment changes:** push to HF Space, watch the build stage transitions (`BUILDING` → `APP_STARTING` → `RUNNING`), verify the runtime stage hits `RUNNING` before claiming success.
+
+If a change requires breaking these rules, write the reason in the commit body.
+
+---
+
+## Testing conventions
+
+- **TDD per the plan.** Failing test first, then implementation.
+- **L1** — unit tests on pure Python (mode registry, parameterize_fn, walker, extractor). Runs in CI without GPU.
+- **L2** — graph validation against the bundled ComfyUI (`pytest --comfy-real`). Optional; runs locally + nightly.
+- **L3** — backend smoke tests with real workflow JSONs but stubbed HTTP / filesystem boundaries. Runs in CI without GPU.
+- **L4** — HF Space smoke. Manual click-through on the live Space after each deploy.
+- **No mocks for ComfyUI core.** Tests run against real workflow JSONs. Stub only HTTP boundaries (HF Hub) and filesystem (use `tmp_path` and the `fake_hf_cache` fixture).
+- `pyproject.toml` declares the `gpu` marker; pass `--gpu` to opt into GPU smoke.
+
+---
+
+## Out of scope (v1 — don't add without asking)
+
+The spec at `docs/superpowers/specs/2026-04-30-ltx23-aio-generator-design.md` § 11 calls these out as v1.1+. If you find yourself "while I'm here"-ing into one of them, stop.
+
+- **Lite mode** (`LTX23_AIO_LITE=1`) for the free HF Spaces tier
+- **Custom LoRA** add/remove rows (Power-Lora-Loader clone)
+- **GGUF Q4 transformer** / "Low VRAM" preset (currently always BF16-served)
+- **Auto-launch the 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 `docs/future_improvements.md` item 6)
+- **Telemetry-driven duration estimator** (requires persistent storage)
+
+If a feature you're adding requires one of these as a sub-step, **ask the user.**
+
+---
+
+## When you're not sure
+
+1. Read `docs/superpowers/specs/2026-04-30-ltx23-aio-generator-design.md` — that's the architectural source of truth.
+2. Read `docs/superpowers/plans/2026-04-30-ltx23-aio-generator.md` — task-by-task breakdown.
+3. Read `SKILLS.md` — process rules, debugging patterns, deployment workflow, useful one-liners.
+4. Read `CLAUDE.md` — gotchas catalogue and what-not-to-do.
+5. `git log --oneline` — every non-obvious decision has a fix-commit explaining the reasoning.
+6. **Ask the user.** A clarifying question costs the user ten seconds. A wrong implementation costs everyone an hour.

README.md

@@ -21,42 +21,211 @@ preload_from_hub:
   - google/gemma-3-12b-it-qat-q4_0-unquantized gemma-3-12b-it/model-00001-of-00005.safetensors,gemma-3-12b-it/model-00002-of-00005.safetensors,gemma-3-12b-it/model-00003-of-00005.safetensors,gemma-3-12b-it/model-00004-of-00005.safetensors,gemma-3-12b-it/model-00005-of-00005.safetensors,gemma-3-12b-it/model.safetensors.index.json,gemma-3-12b-it/preprocessor_config.json,gemma-3-12b-it/tokenizer.model
 ---
 
-# LTX 2.3 All-in-One Video Generator
+# LTX 2.3 Studio
 
-A Gradio app for [LTX-2.3](https://huggingface.co/Lightricks/LTX-2.3) wrapping all six modes of the official ComfyUI All-In-One workflow under a single, focused UI. Runs locally on Apple Silicon (MPS) or NVIDIA (CUDA), and deploys to Hugging Face Spaces (ZeroGPU).
+A single-process Gradio app that wraps [LTX-2.3](https://huggingface.co/Lightricks/LTX-2.3) — Lightricks' open 22B video generation model — under one focused UI. Six modes (text · image · audio · lipsync · keyframe · style) sharing the same ComfyUI All-In-One workflow. Runs locally on Apple Silicon (MPS) or NVIDIA (CUDA), deploys to Hugging Face Spaces (ZeroGPU).
 
-## Modes
+[![Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Spaces-Live-E0A458?style=flat-square)](https://huggingface.co/spaces/techfreakworm/LTX2.3-Studio)
+[![GitHub stars](https://img.shields.io/github/stars/techfreakworm/ltx2.3-AIO-generator?style=flat-square&color=E0A458)](https://github.com/techfreakworm/ltx2.3-AIO-generator/stargazers)
+[![License: MIT](https://img.shields.io/badge/License-MIT-E0A458?style=flat-square)](LICENSE)
+[![Python 3.11](https://img.shields.io/badge/Python-3.11-E0A458?style=flat-square&logo=python&logoColor=white)](pyproject.toml)
+[![Powered by ComfyUI](https://img.shields.io/badge/backend-ComfyUI-E0A458?style=flat-square)](https://github.com/comfyanonymous/ComfyUI)
+[![Built on LTX-2.3](https://img.shields.io/badge/model-LTX--2.3%2022B-E0A458?style=flat-square)](https://huggingface.co/Lightricks/LTX-2.3)
 
-1. **Text → Video** (+ optional Audio)
-2. **Audio → Video** (Text + Audio → Video + Audio)
-3. **Image → Video** (+ optional Audio)
-4. **Lipsync** (Image + Audio → Video + Audio)
-5. **First / Last Frame → Video** (keyframe interpolation)
-6. **Style Transfer** (Video → Video, motion control)
+→ **Live demo:** https://huggingface.co/spaces/techfreakworm/LTX2.3-Studio
 
-## Local quickstart
+---
+
+## What's inside
+
+Six modes wired through the same ComfyUI All-In-One workflow. Each mode exposes only the inputs it actually consumes — the form stays short and focused.
+
+| Mode | Inputs | Output | Notes |
+|---|---|---|---|
+| **Text → Video** | Prompt (+ optional audio prompt) | mp4 (+ optional wav) | The core mode. Camera-control LoRAs auto-applied by keyword. |
+| **Audio → Video** | Prompt + audio track | mp4 with the input audio preserved | Conditions motion on the audio waveform. |
+| **Image → Video** | Image + prompt | mp4 (+ optional audio) | Image-conditioned generation. |
+| **Lipsync** | Image + audio | mp4 with audio | Viseme-aligned mouth motion. |
+| **Keyframe** | First + last frames + prompt | mp4 | Latent interpolation between two anchors. |
+| **Style Transfer** | Source video + style image | mp4 | IC-LoRA restyle; motion preserved from source. |
+
+Every mode carries **Fast / Balanced / Quality** presets (steps × 1, × 1.5, × 3). A per-mode ZeroGPU duration estimator adapts the call timeout to the requested workload.
+
+---
 
-Requires Python 3.11, ~80 GB free disk for model weights, and ~24 GB+ GPU memory (CUDA) or 32 GB+ unified memory (Apple Silicon).
+## Quick start (local)
+
+Requires **Python 3.11**, ~80 GB free disk for the weight set, and ~24 GB VRAM (CUDA) or ~32 GB unified memory (Apple Silicon).
 
 ```bash
-git clone --recurse-submodules https://github.com/<your-handle>/ltx2.3-AIO-generator
+git clone --recurse-submodules https://github.com/techfreakworm/ltx2.3-AIO-generator
 cd ltx2.3-AIO-generator
-bash setup.sh
+bash setup.sh           # creates .venv, installs ComfyUI + pinned custom nodes + app deps
 source .venv/bin/activate
-python app.py
+python app.py           # http://127.0.0.1:7860
 ```
 
-The first run downloads ~70 GB of models into your existing `~/.cache/huggingface/hub` (no duplicate copies in this repo) and symlinks them into `comfyui/models/`.
+The first run resolves model weights into your HF cache (`~/.cache/huggingface/hub/`) and symlinks them into `comfyui/models/<comfy_type>/`. Subsequent starts skip the download. Expect ~70 GB of weights pulled on a cold first run.
+
+**Apple Silicon notes.** `PYTORCH_ENABLE_MPS_FALLBACK=1` is set automatically so the few MPS-unsupported ops fall back to CPU. ComfyUI's VRAM autodetect picks the right tier; override with `LTX23_AIO_VRAM=lowvram|normalvram|highvram` if you need to force one.
+
+**LAN access** (phone / tablet on the same WiFi): `python app.py` binds `0.0.0.0:7860`. Visit `http://<your-LAN-IP>:7860` from another device. On macOS, allow inbound for `python` in System Settings → Network → Firewall if the connection refuses.
 
-## HF Spaces deployment
+## Quick start (HF Spaces)
 
-This repo is a Gradio Space. The required Pro tier provides ~50 GB persistent `/data` storage and longer per-call ZeroGPU budgets needed for Balanced and Quality presets.
+This repo is a Gradio Space. The Pro tier provides ZeroGPU (A10G) access and the per-call duration budget needed for the Balanced and Quality presets.
 
 ```bash
-git remote add space https://huggingface.co/spaces/<your-handle>/ltx2.3-aio
-git push space main
+git remote add space https://huggingface.co/spaces/<your-handle>/LTX2.3-Studio
+git push space master:main       # local branch is master; HF Space deploys from main
 ```
 
+> ⚠ The refspec `master:main` matters. The local default branch is `master` (GitHub convention); the HF Space deploys from `main`. A bare `git push space master` creates an orphan remote branch that does NOT trigger a deploy.
+
+The Space's `preload_from_hub` directive (see the YAML at the top of this file) bakes ~111 GB of weights into the build image. `app.py:_bootstrap()` then:
+
+1. Clones ComfyUI + pinned custom nodes into `~/comfyui` on cold start (ZeroGPU container freezes preserve them across calls)
+2. Mirrors the read-only preload cache into `~/hf-cache-rw/` — works around the build-user-vs-runtime-user permissions trap (preloaded files are root-owned; we run as uid 1000 and can't write to them, so any lazy download to the cache would fail with `Permission denied`)
+3. Stages seed input files into `comfyui/input/` so workflow loaders don't error before any user upload arrives
+
+Subsequent requests hit warm cache — no network traffic on inference 2+.
+
+**ZeroGPU duration estimator.** Each generate call carries a dynamic `@spaces.GPU(duration=N)` calculated from mode, preset, and frame count. Clamped at `[60, 900] s`. On timeout (`"GPU task aborted"`), the handler auto-retries once at 2× duration.
+
+---
+
+## Architecture
+
+```
+                                     ┌──────────────────────────────────┐
+                          browser ──▶│   app.py — Gradio Blocks         │
+                                     │   header · drawer · 6 mode tabs  │
+                                     └──────────────────┬───────────────┘
+                                                        │
+                                                        ▼
+                                     ┌──────────────────────────────────┐
+                                     │   backend.py                     │
+                                     │   ComfyUILibraryBackend          │
+                                     │   @spaces.GPU(duration=callable) │
+                                     │   calls PromptExecutor directly  │
+                                     └──────────────────┬───────────────┘
+                                                        │
+       ┌──────────────┬──────────────┬──────────────────┴──────┬──────────────────┐
+       ▼              ▼              ▼                         ▼                  ▼
+   modes.py       models.py      workflow.py                ui.py              tools/
+   per-mode       walk + ensure  load + patch               per-mode form      extract_modes.py
+   parameterize   from HF cache  API-format JSON            builders           (regen workflows/)
+                                                        │
+                                                        ▼
+                                     ┌──────────────────────────────────┐
+                                     │   comfyui/                       │
+                                     │   submodule (local)              │
+                                     │   runtime clone at ~/comfyui     │
+                                     │   on HF Spaces                   │
+                                     │                                  │
+                                     │   ├── custom_nodes/ (pinned SHAs)│
+                                     │   └── models/ → HF cache symlinks│
+                                     └──────────────────────────────────┘
+```
+
+**One backend, one process.** The `@spaces.GPU` decorator is the only divergence between local and Spaces runtime. ComfyUI manages VRAM via its tiered presets — no `empty_cache()` sprinkling needed elsewhere.
+
+**Workflow as data.** Each of the six modes is a user-exported API-format JSON in `workflows/`. The mode handler patches a deep-copied template (`modes.parameterize_fn`) and hands it to ComfyUI's `PromptExecutor`. Updating the master workflow is a three-step ritual: edit in the ComfyUI editor → export → `python tools/extract_modes.py --master ... --out workflows`.
+
+---
+
+## Project layout
+
+```
+.
+├── app.py              # Gradio Blocks entry, _bootstrap, _on_generate, mode tabs
+├── backend.py          # ComfyUILibraryBackend, @spaces.GPU, duration estimator
+├── 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 helpers
+├── 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 staging
+├── tools/
+│   └── extract_modes.py  # regenerate workflows/ from a master ComfyUI export
+├── docs/
+│   ├── future_improvements.md
+│   └── superpowers/{specs,plans}/  # spec + implementation plans per feature
+├── tests/              # L1 + L3 in CI; L2 with --comfy-real; L4 GPU smoke
+├── README.md           # this file (HF Space YAML + project intro)
+├── CLAUDE.md           # project facts + gotchas (what & why)
+├── AGENTS.md           # tool-agnostic agent rulebook
+├── SKILLS.md           # process / debugging / deployment (how)
+├── requirements.txt    # pinned deps
+├── pyproject.toml      # ruff + pytest config (py311)
+├── setup.sh            # venv + ComfyUI + custom nodes bootstrap
+└── comfyui/            # git submodule (local) / runtime clone target (Spaces)
+```
+
+---
+
+## Tech stack
+
+- **[Gradio 5.50](https://gradio.app/)** — UI shell, native components, `gr.Progress(track_tqdm=True)`
+- **[ComfyUI](https://github.com/comfyanonymous/ComfyUI)** — library-mode `PromptExecutor` (pinned commit; submodule locally, runtime-cloned on Spaces)
+- **[LTX-2.3 22B](https://huggingface.co/Lightricks/LTX-2.3)** by Lightricks — primary diffusion transformer (BF16 weights via [Kijai/LTX2.3_comfy](https://huggingface.co/Kijai/LTX2.3_comfy))
+- **[Gemma 3 12B](https://huggingface.co/google/gemma-3-12b-it)** by Google — multimodal text encoder (requires the full 5-shard model — text-only checkpoints crash on meta-tensor allocation in SDPA)
+- **Custom nodes** (pinned SHAs in `app.CUSTOM_NODES_PINNED`):
+  - [Lightricks/ComfyUI-LTXVideo](https://github.com/Lightricks/ComfyUI-LTXVideo) — LTX sampler / decoder nodes
+  - [kijai/ComfyUI-KJNodes](https://github.com/kijai/ComfyUI-KJNodes) — utility nodes
+  - [rgthree/rgthree-comfy](https://github.com/rgthree/rgthree-comfy) — Power-Lora-Loader
+  - [Kosinkadink/ComfyUI-VideoHelperSuite](https://github.com/Kosinkadink/ComfyUI-VideoHelperSuite) — video I/O
+  - [pythongosssss/ComfyUI-Custom-Scripts](https://github.com/pythongosssss/ComfyUI-Custom-Scripts) — string / dict helpers
+  - [city96/ComfyUI-GGUF](https://github.com/city96/ComfyUI-GGUF) — GGUF transformer loader
+  - [Fannovel16/comfyui_controlnet_aux](https://github.com/Fannovel16/comfyui_controlnet_aux) — DWPose for Lipsync/Style preprocessors
+  - [evanspearman/ComfyMath](https://github.com/evanspearman/ComfyMath) — math nodes for the workflow's keyframe path
+  - [Smirnov75/ComfyUI-mxToolkit](https://github.com/Smirnov75/ComfyUI-mxToolkit) — utility nodes
+  - [DoctorDiffusion/ComfyUI-MediaMixer](https://github.com/DoctorDiffusion/ComfyUI-MediaMixer) — `FinalFrameSelector`
+- **[HF Spaces ZeroGPU](https://huggingface.co/zero-gpu)** (A10G) — `@spaces.GPU(duration=…)` for queue-priority signalling and per-call timeout
+
+---
+
+## Design
+
+Theme: **Topaz Cinema Slate** — slate substrate `#1A1F26`, warm amber accent `#E0A458` used sparingly, IBM Plex Sans throughout. Defined as `_TOPAZ_THEME` + `_CUSTOM_CSS` in `app.py`.
+
+Layout: hamburger drawer. Pinned 220 px sidebar at ≥1024 px (mode buttons + model status + settings); below 1024 px it slides in as a fixed overlay via the `.aio-shell.drawer-open` class. The header carries a live mode tag (T2V/A2V/I2V/LIPSYNC/KEY/STYLE) updated by JS without a server round-trip.
+
+Spec, plan, and design rationale live under `docs/superpowers/specs/` and `docs/superpowers/plans/`.
+
+---
+
+## Notes on running
+
+- **First inference is slow.** Cold-start workflow validation + model load on the active node graph takes ~30 – 90 s. Subsequent calls within the same session reuse loaded models.
+- **VRAM tier** is auto-detected; override with `LTX23_AIO_VRAM=lowvram|normalvram|highvram`.
+- **ZeroGPU duration cap.** The per-call estimator clamps to `[60, 900] s`. If a generation aborts with `"GPU task aborted"`, the handler retries once at 2× duration. The duration field is the queue-priority signal, not a billing cap.
+- **Output directory.** Local: `comfyui/output/LTX2.3/`. Spaces: `~/comfyui/output/LTX2.3/`. Both are whitelisted via `allowed_paths=` on launch (Gradio 5 file-access policy).
+- **Local LAN testing.** Bound to `0.0.0.0:7860`. macOS firewall: allow inbound for `python` if a connection from your phone refuses.
+
+---
+
 ## License
 
-MIT for the AIO app code. ComfyUI and LTX-2.3 retain their respective licenses.
+MIT for the AIO app code (see `LICENSE`).
+
+- [ComfyUI](https://github.com/comfyanonymous/ComfyUI) is GPL-3.0.
+- LTX-2.3 and Lightricks-published LoRAs / auxiliaries retain Lightricks' open-source licensing — see the individual model cards on Hugging Face.
+- Gemma 3 weights are subject to Google's [Gemma Terms of Use](https://ai.google.dev/gemma/terms).
+- Each pinned custom node retains its own license; see the linked repositories.
+
+## Credits
+
+- **LTX-2.3** by [Lightricks](https://github.com/Lightricks)
+- **ComfyUI** by [comfyanonymous](https://github.com/comfyanonymous)
+- **Gemma 3** by [Google DeepMind](https://github.com/google-deepmind)
+- **All-In-One ComfyUI workflow** that this app wraps — by [Danielle Falco](https://www.youtube.com/@FutuTek) (FutuTek)
+- **Workflow nodes** by Lightricks, [kijai](https://github.com/kijai), [rgthree](https://github.com/rgthree), [Kosinkadink](https://github.com/Kosinkadink), [pythongosssss](https://github.com/pythongosssss), [city96](https://github.com/city96), [Fannovel16](https://github.com/Fannovel16), [evanspearman](https://github.com/evanspearman), [Smirnov75](https://github.com/Smirnov75), [DoctorDiffusion](https://github.com/DoctorDiffusion)
+
+Built by [@techfreakworm](https://huggingface.co/techfreakworm) — drop a ♥ on the [Space](https://huggingface.co/spaces/techfreakworm/LTX2.3-Studio) if it's useful, and follow there for what's next.

SKILLS.md

@@ -1,8 +1,14 @@
-# Skills — how to make changes in this project
+# SKILLS.md — 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*.
+Process rules and habits for agents working on this repo. Sits alongside:
 
-> Default rule when in doubt: **stop and ask the user**. The user prefers a question over wrong work.
+- `AGENTS.md` — the tool-agnostic rulebook (locked decisions, out-of-scope list, commit + verification rules).
+- `CLAUDE.md` — Claude-specific extensions + full gotchas catalogue (*what & why*).
+- `README.md` — public-facing intro (different audience).
+
+This file is the *how* — debugging patterns, verification habits, deployment workflow, useful one-liners.
+
+> **Default rule when in doubt:** stop and ask the user. The user prefers a question over wrong work.
 
 ---
 
@@ -152,12 +158,15 @@ lsof -nP -iTCP:7860 -sTCP:LISTEN | awk 'NR>1 {print $2}' | xargs -r kill -9
 ### Two remotes
 
 ```bash
-git push origin master                                                 # GitHub
-HF_TOKEN=$(cat ~/.cache/huggingface/token)                             # HF auth (cli removed `hf auth token`)
-git push "https://techfreakworm:${HF_TOKEN}@huggingface.co/spaces/techfreakworm/LTX2.3-Studio" master:main
+git push origin master           # GitHub:  techfreakworm/ltx2.3-AIO-generator
+git push space  master:main      # HF Space: techfreakworm/LTX2.3-Studio (deploys from main)
 ```
 
-GitHub: `master`. HF Space: `main`. The Space accepts force-push only with explicit user consent.
+The repo has both remotes pre-configured (`origin` + `space`). HF credentials live in `~/.cache/huggingface/token`; git's credential helper picks them up automatically — no need to embed the token in the URL.
+
+> ⚠ **Refspec matters for the Space push.** Local default branch is `master`; the HF Space deploys from `main`. A bare `git push space master` succeeds but creates an orphan `refs/heads/master` on the remote that does NOT trigger a deploy — the Space silently stays on the old build. Always push with the `master:main` refspec form.
+
+If unsure, verify with `git ls-remote space` — `HEAD` should point at `refs/heads/main`.
 
 ### When to push
 
@@ -261,9 +270,10 @@ Do not loop on patches when you've patched twice and it's still broken.
 │   └── 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)
+├── README.md            # HF Space YAML + project intro (public-facing)
+├── AGENTS.md            # tool-agnostic agent rulebook (locked decisions, OoS)
+├── CLAUDE.md            # what & why — full gotchas catalogue
+├── SKILLS.md            # how — process, debugging, deployment (this file)
 ├── requirements.txt
 └── comfyui/             # git submodule (local) / runtime clone target (Spaces)
 ```