diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..e7295db
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,121 @@
+# Claude notes — instamesh-docker
+
+Agent context for this repo. Read before non-trivial changes.
+
+## What this is
+
+Docker wrapper around upstream [TencentARC/InstantMesh](https://github.com/TencentARC/InstantMesh)
+for single-image → 3D mesh generation. **Not** a fork of InstantMesh
+itself — this repo owns the docker build + compose plus a small set of
+patches that fix known upstream build breakage.
+
+## Repo shape
+
+```
+instamesh-docker/
+  InstantMesh/          # UNTRACKED — upstream clone. Operators run
+                        # `git clone https://github.com/TencentARC/InstantMesh.git`
+                        # once before `docker compose build`. Not a submodule.
+  docker/
+    Dockerfile          # patched (see "Patches applied" below)
+    compose.yml         # GPU compose, named volume for model cache, port 43839
+    requirements.txt    # InstantMesh's pip deps, kept here so the Dockerfile
+                        # can ADD them without changing the upstream tree
+  main.py, pyproject.toml, uv.lock, .python-version
+                        # leftover uv scaffolding from initial repo init;
+                        # NOT part of the build path. Don't extend these.
+  README.md
+  CLAUDE.md
+```
+
+`InstantMesh/` is intentionally untracked. Don't add it as a submodule
+or vendor it into source control — keep the upstream boundary clean.
+
+## Patches applied (vs. upstream)
+
+The Dockerfile is forked from InstantMesh's docker config with three
+deliberate changes — call out any churn around these:
+
+1. **CUDA aligned to 12.1.** Base image is
+   `nvidia/cuda:12.1.0-runtime-ubuntu22.04`; conda installs `cuda` from
+   `nvidia/label/cuda-12.1.0`; pip installs `torch==2.1.0 + cu121` and
+   `xformers==0.0.22.post7`. All four must stay in sync. Don't bump CUDA
+   without re-pinning all of them.
+2. **Duplicate `conda create` removed.** Upstream's Dockerfile created
+   the conda env twice; the second one nuked the first's pinned
+   packages. Don't reintroduce.
+3. **`onnxruntime` added.** Missing from upstream's `requirements.txt`
+   (InstantMesh issue #175). Installed as a separate `pip install` step
+   after the bulk requirements install so it's not silently dropped by
+   the `|| true` below.
+
+## Intentional `|| true` on the bulk pip install
+
+```dockerfile
+RUN pip install --no-cache-dir -r requirements.txt || true
+```
+
+This is **on purpose**. The requirements include `nvdiffrast` via a git
+URL that needs `--no-build-isolation`, which pip's bulk install won't
+do. We let that line fail, then install `nvdiffrast` correctly:
+
+```dockerfile
+RUN pip install git+https://github.com/NVlabs/nvdiffrast.git --no-build-isolation
+```
+
+Don't "fix" the bulk install by removing `|| true` — the build will
+hard-fail on nvdiffrast.
+
+## Hardware contract
+
+- **NVIDIA GPU required**, exposed through Docker via the nvidia
+  runtime. InstantMesh wants **≥ 12 GB VRAM** comfortably; smaller cards
+  may OOM during inference.
+- **CUDA 12.1** — see patch #1 above.
+
+## Build is slow + brittle
+
+Expect a 15+ minute first build. Conda + nvdiffrast compilation +
+PyTorch wheels add up. Triggers that re-run the slow layers:
+- Editing `docker/requirements.txt` invalidates the conda install layer.
+- Editing the Dockerfile's `apt-get install` line redoes the whole
+  thing from a fresh base image.
+
+Lean on Docker's layer cache; don't restructure for "cleanliness"
+without measuring the rebuild cost.
+
+## Compose
+
+```yaml
+ports:
+  - "43839:43839"      # Gradio app, host-published
+volumes:
+  - instantmesh-models:/workspace/models   # weights cache (named volume)
+```
+
+No host-network mode, no bind mounts for code (the upstream tree is
+COPYed at build time). If you need to iterate on InstantMesh source,
+edit `InstantMesh/` locally and rebuild — there's no dev-mode wiring.
+
+## Where outputs go
+
+InstantMesh's Gradio app writes generated meshes inside the container
+(under `/workspace/instantmesh/`). There's **no bind mount** for
+outputs in `compose.yml` — operator downloads results from the Gradio
+UI. If you find yourself wanting to bind-mount an outputs dir, mirror
+`hunyuan3d-sunnie/docker/outputs/`.
+
+## Don't-touch zones
+
+- The CUDA 12.1 pins (base image / conda label / PyTorch wheel index /
+  xformers wheel) — load-bearing as a set.
+- The `|| true` on bulk requirements install — required for nvdiffrast.
+- The `onnxruntime` separate install line — load-bearing per upstream #175.
+- The untracked `InstantMesh/` directory — let operators reclone.
+
+## Bigger picture
+
+Personal/one-off project, GPU-only. Runs on the dev tower; not part of
+the homelab production stack. Sibling project `hunyuan3d-sunnie/` uses
+a different model (Hunyuan3D-2) for the same general shape of problem
+on a 10 GB card — pick that one if VRAM is tight.
diff --git a/README.md b/README.md
index e69de29..44df037 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,59 @@
+# instamesh-docker
+
+Docker wrapper around [TencentARC/InstantMesh](https://github.com/TencentARC/InstantMesh)
+for single-image → 3D mesh generation. Patches upstream's docker setup to
+fix a couple of known build issues (missing `onnxruntime`, duplicate
+conda env create) and pins CUDA to 12.1 to match the InstantMesh
+PyTorch / xformers wheels.
+
+## Requirements
+
+- NVIDIA GPU with CUDA 12.1 support and ≥ 12 GB VRAM (InstantMesh is
+  not VRAM-friendly).
+- Docker + the NVIDIA Container Toolkit (`nvidia` runtime exposed to
+  compose).
+- Disk: several GB for the conda env + model weights.
+- Network egress on first build to pull miniconda, PyTorch wheels, and
+  the nvdiffrast / InstantMesh dependencies (long build — 15+ minutes
+  is normal).
+
+## Quick start
+
+```bash
+# Clone the upstream model repo into this directory (the Dockerfile
+# COPYs it via the build context; not a git submodule). Operator-managed;
+# not committed.
+git clone https://github.com/TencentARC/InstantMesh.git
+
+# Build and run
+cd docker
+docker compose build
+docker compose up
+
+# Gradio UI at http://localhost:43839
+```
+
+## Project structure
+
+```
+instamesh-docker/
+  InstantMesh/         # cloned upstream — operator-managed, not committed
+  docker/
+    Dockerfile         # patched build (CUDA 12.1, onnxruntime fix)
+    compose.yml        # GPU compose, named volume for model cache
+    requirements.txt   # Python deps installed inside the conda env
+  README.md
+  CLAUDE.md
+```
+
+## Notes
+
+- First run downloads model weights into the `instantmesh-models`
+  named volume (mounted at `/workspace/models`). Several GB.
+- The build uses miniconda inside the container with a `python=3.10`
+  env named `instantmesh` — not the host's Python. The repo-root
+  `pyproject.toml` / `uv.lock` / `.python-version` are leftover uv
+  scaffolding and are not part of the build path.
+- See `CLAUDE.md` for the agent-facing gotchas: the patched bits, the
+  intentional `|| true` on the bulk requirements install, and the CUDA
+  pin reasoning.