diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..9f785da
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,97 @@
+# Claude notes — hunyuan3d-sunnie
+
+Agent context for this repo. Read before non-trivial changes.
+
+## What this is
+
+One-off pipeline to generate a 3D mesh of *Sunnie* from a reference
+image using Tencent's [Hunyuan3D-2](https://github.com/Tencent-Hunyuan/Hunyuan3D-2)
+(`mini-turbo` variant), then rig + animate in Blender via Mixamo. This
+repo owns the **docker wrapper** around upstream Hunyuan3D-2 — it is
+**not** a fork of the model code itself.
+
+## Repo shape
+
+```
+hunyuan3d-sunnie/
+  Hunyuan3D-2/        # UNTRACKED — upstream clone. Cloned by the operator
+                      # before `docker compose build`. Not a git submodule.
+  docker/
+    Dockerfile        # community-derived (per repo issues #125, #122)
+    compose.yml       # GPU compose; pins the mini-turbo model + flashvdm
+    outputs/          # generated .glb meshes land here (gitignored)
+  README.md
+  CLAUDE.md
+```
+
+`Hunyuan3D-2/` is intentionally untracked. Operators run
+`git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.git` once;
+the Dockerfile then COPYs it in via the build context. Don't add it
+as a submodule or vendor it into source control — keep the upstream
+boundary clean.
+
+## Hardware contract
+
+- **NVIDIA GPU required**, exposed through Docker via the nvidia
+  runtime (`deploy.resources.reservations.devices` with the `nvidia`
+  driver). The compose `command` is tuned for **RTX 3080 / 10 GB
+  VRAM** with `--low_vram_mode` + `--enable_flashvdm`. Move to a
+  bigger card → drop `--low_vram_mode`. Smaller card → expect OOMs.
+- **CUDA 12.4**. The Dockerfile pulls `nvidia/cuda:12.4.0-devel-ubuntu22.04`
+  and installs PyTorch from the cu124 wheels index. Don't switch CUDA
+  versions without re-aligning the PyTorch index URL.
+
+## Compose command — don't casually edit
+
+```yaml
+command: >
+  python3 gradio_app.py
+  --model_path tencent/Hunyuan3D-2mini
+  --subfolder hunyuan3d-dit-v2-mini-turbo
+  --texgen_model_path tencent/Hunyuan3D-2
+  --low_vram_mode
+  --enable_flashvdm
+  --host 0.0.0.0
+  --port 8080
+```
+
+- `--model_path` + `--subfolder` together select the **mini-turbo**
+  variant. The full Hunyuan3D-2 model won't fit in 10 GB.
+- `--texgen_model_path` uses the full Hunyuan3D-2 model **for PBR
+  texture generation only** (texture-gen has a lower VRAM ceiling
+  than mesh-gen).
+- Removing `--low_vram_mode` or `--enable_flashvdm` will likely
+  produce OOM on a 3080.
+
+## Model weights
+
+First run downloads weights to the `hunyuan3d-models` named volume
+(mounted at `/root/.cache/hy3dgen`). Both the mini-turbo mesh model
+and the full texgen model need to come down — several GB total. Don't
+prune that volume between sessions unless you're ready to wait through
+the re-download.
+
+## Where outputs land
+
+`./docker/outputs/` is bind-mounted into the container at
+`/workspace/outputs/`. The Gradio app drops `.glb` files there with
+PBR textures embedded — ready for Blender import → Mixamo rigging.
+The dir is gitignored; nothing in it is meant to be committed.
+
+## Don't-touch zones
+
+- The untracked `Hunyuan3D-2/` directory — let operators reclone if
+  they need to update.
+- The `--low_vram_mode` + `--enable_flashvdm` flags — load-bearing for
+  the 3080.
+- The Dockerfile's PyTorch index URL — pinned to cu124 to match the
+  base image.
+- `pip install -e .` and `flash-attn` are wrapped in `|| true` because
+  they're known-flaky on this base image; that's intentional. Don't
+  "fix" by making them required.
+
+## Bigger picture
+
+This is a personal/one-off project, not part of the homelab production
+stack. It only runs on the dev tower (which has the GPU) — never on
+the herbydev Proxmox host or the NAS.
diff --git a/README.md b/README.md
index dd280c5..7c96964 100644
--- a/README.md
+++ b/README.md
@@ -4,10 +4,18 @@ Self-hosted Hunyuan3D-2 (mini-turbo variant) for generating a 3D Sunnie
 mesh from a reference image, then rigging and animating in Blender via
 Mixamo.
 
+## Requirements
+
+- NVIDIA GPU with CUDA 12.4 support and ≥ 10 GB VRAM (tuned for RTX 3080).
+- Docker + the NVIDIA Container Toolkit (`nvidia` runtime exposed to compose).
+- Network egress to pull PyTorch wheels + Hugging Face model weights on
+  first build / first run.
+
 ## Quick Start
 
 ```bash
-# Clone the model repo
+# Clone the upstream model repo into this directory (not a submodule —
+# the Dockerfile COPYs it via the build context). This dir is gitignored.
 git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.git
 
 # Build and run
@@ -22,15 +30,22 @@ docker compose up
 
 ```
 hunyuan3d-sunnie/
-  Hunyuan3D-2/          # cloned repo (git submodule or manual clone)
+  Hunyuan3D-2/          # cloned upstream — gitignored, operator-managed
   docker/
-    Dockerfile           # custom build with CUDA 12.4
-    compose.yml          # GPU-enabled compose with model volume
-    outputs/             # generated meshes land here
+    Dockerfile          # custom build, CUDA 12.4, community-derived
+    compose.yml         # GPU compose; pins mini-turbo + flashvdm + low_vram
+    outputs/            # generated .glb meshes land here (gitignored)
 ```
 
 ## Notes
 
-- First run downloads model weights (~several GB) to the named volume
-- Uses mini-turbo variant with --low_vram_mode for RTX 3080 (10GB VRAM)
-- Outputs .glb with PBR textures for Blender import
+- First run downloads model weights (~several GB) to the
+  `hunyuan3d-models` named volume — both the mini-turbo mesh model and
+  the full Hunyuan3D-2 model for PBR texture generation.
+- Uses the `mini-turbo` variant with `--low_vram_mode` and
+  `--enable_flashvdm` for the 10 GB VRAM ceiling on a 3080. Bigger card?
+  Drop `--low_vram_mode`. Smaller card? Expect OOMs.
+- Outputs `.glb` with PBR textures, ready for Blender import → Mixamo
+  rigging.
+- See `CLAUDE.md` for the agent-facing gotchas (don't-touch flags,
+  CUDA pin rationale, etc.).