diff --git a/CLAUDE.md b/CLAUDE.md
index b93f543..b30277f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,11 +1,14 @@
 # Linux Workspace
 
-Dotfiles & workstation automation for Linux, macOS, WSL. `bashrc` loads `rc/*.sh` (ordered by prefix)
+Dotfiles & workstation automation for Linux, macOS, WSL. `bashrc` sources `rc/*.sh` alphabetically
 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.
+- `rc/` — Shell init files, sourced alphabetically. Use a `0X-` prefix only when a file must load
+  before others. Per-tool env setup goes here.
+- `rc.available/` — Archived rc files, not loaded. Do not edit or reference.
+- `rc.fish/` — Fish init (loaded by `fishrc`). Bash changes are not mirrored there automatically.
 - `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).
@@ -47,12 +50,25 @@ RC files MUST guard slow tools and check availability:
 
 ```bash
 if is_slow_init && can_run pyenv; then
-    # initialize pyenv
+  # initialize pyenv
 fi
 ```
 
 Installers (`install/*.sh`) MUST be idempotent — check before installing.
 
+## Verification
+
+After editing shell code, run:
+
+- `shellcheck <file>` — fix new warnings in code you touched
+- `bash -n <file>` — syntax check
+- `LWS_DEBUG=1 bash -i -c exit` — after `rc/` or `functions.sh` changes; shell must start without errors
+
+## macOS Compatibility
+
+Code must also run on macOS with BSD userland. Avoid GNU-only flags (`sed -i` without a suffix
+argument, `date -d`, `readlink -f`, `grep -P`), or branch on `uname`.
+
 ## Environment Variables
 
 - `LWS_FAST=1` — skips slow tools during shell init