docs: add overlay creation guidance

CLAUDE.md

@@ -41,3 +41,5 @@ bash tests/test-resolve-list-cleanup.sh
 - Python targets 3.12, formatted by ruff with 120 char line length (see `ruff.toml`).
 - Commit messages follow conventional commits: `fix:`, `feat:`, `ci:`, etc.
 - `.gitignore.template` defines patterns for per-worktree gitignored files; `setup-worktree` copies it as `.gitignore` into each worktree.
+- When targeting a specific dependency group, use `uv sync --group dev`, not `--dev` (legacy alias removed in uv 0.7.x+).
+- When creating a new project overlay, strip inherited packages and config for tools the target project doesn't use — don't leave dead weight from the source overlay.

projects/README.md

@@ -0,0 +1,22 @@
+# Project overlays
+
+Each subdirectory is a project-specific overlay applied on top of the base devcontainer image. See `defaults/` for the fallback overlay and file-by-file documentation.
+
+## Creating a new overlay
+
+Start from the closest existing overlay, not `defaults/`. The volume topology, toolchain pinning, and SHA256 checksums are easy to get wrong from scratch — stripping what you don't need is faster and less error-prone.
+
+### Cargo volumes
+
+Rust overlays use a three-volume split:
+
+- `cargo-registry` and `cargo-git` — shared across worktrees (`external: true`). These are content-addressed and safe to share.
+- `cargo-target` — per-worktree (no `external: true`). Concurrent writes to a shared target dir corrupt incremental build state.
+
+Shared volumes must be listed in `external-volumes.txt` so `ensure_external_volumes()` pre-creates them before compose up. Missing an entry here means the first `devcontainer up` fails with a missing-volume error.
+
+The `cargo-target` mount point must match where the crate root is. For example, `xorq-desktop` mounts it at `desktop/src-tauri/target` while `batchcorder` mounts at the repo-root `target/`. Getting this wrong means builds write to the wrong place.
+
+### Expensive build steps
+
+Gate expensive build steps (e.g., `maturin develop`) behind artifact presence checks so container recreation with persisted volumes doesn't pay for a redundant rebuild. Use file-presence tests (`compgen -G "path/*.so"`) rather than import probes, which can trigger the build tool and defeat the skip.