diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..ad3c0fc
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,33 @@
+# CLAUDE.md
+
+Dotfiles & workstation automation for Linux, macOS, WSL. `bashrc` loads `rc/*.sh` (ordered by prefix) and adds `bin/` to PATH. `$LWS` points to repo root.
+
+## Directory Layout
+
+- `rc/` — Shell init files, loaded in `0X-name.sh` order. Per-tool env setup goes here.
+- `install/` — Idempotent one-off installer scripts (run manually).
+- `bin/` — Scripts auto-added to PATH. New CLI tools go here.
+- `scripts/` — Setup scripts NOT on PATH (git-config, docker fixes, gnome config).
+- `conf/` — Tool configs (vim, WireGuard, WSL).
+- `functions.sh` — Core lib: `append_path`, `prepend_path`, `set_uniq_path`, `source_directory_sh`, `is_fast_init`/`is_slow_init`, WSL detection, debug logging.
+
+## Conventions
+
+All new bash scripts MUST use:
+```bash
+#!/usr/bin/env bash
+set -E -o errexit -o nounset -o pipefail
+```
+
+Before writing shell code, check `functions.sh` for existing helper functions (e.g. `can_run`, `append_path_try`, `source_try`) and prefer them over raw commands.
+
+RC files MUST guard slow tools and check availability:
+```bash
+if is_slow_init && can_run pyenv; then
+    # initialize pyenv
+fi
+```
+
+Installers (`install/*.sh`) MUST be idempotent — check before installing.
+
+Env vars: `LWS_FAST=1` skips slow tools, `LWS_DEBUG=1` enables debug logging.