diff --git a/CLAUDE.md b/CLAUDE.md
index 217210d..338230b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10,6 +10,7 @@ and adds `bin/` to PATH. `$LWS` points to repo root.
 - `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).
+- `doc/` — Reference docs, cheatsheets, bookmarks.
 - `functions.sh` — Core lib (see below).
 
 ## Key Helpers (`functions.sh`)
@@ -26,7 +27,7 @@ and adds `bin/` to PATH. `$LWS` points to repo root.
 
 ## Conventions
 
-All new bash scripts should use:
+All new **executable** bash scripts should use:
 
 ```bash
 #!/usr/bin/env bash
@@ -34,8 +35,13 @@ All new bash scripts should use:
 set -E -o errexit -o nounset -o pipefail
 ```
 
+**Sourced files** (rc files, `functions.sh`) must NOT use `set -o errexit` — they run inside
+the user's shell. Add `# shellcheck shell=bash` at the top instead of a shebang.
+
 Before writing shell code, check `functions.sh` for existing helper functions and prefer them over raw commands.
 
+Detailed formatting, naming, and syntax rules are in `.claude/rules/bash-style.md`.
+
 RC files MUST guard slow tools and check availability:
 
 ```bash
diff --git a/README.md b/README.md
index 20f26a8..134a735 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,10 @@ For faster load can be set
 For debug log enabled
 `LWS_DEBUG=1`
 
+## Directory notes
+
+`opt/` (git-ignored) is used for locally installed tools (e.g. bash-git-prompt, enhancd).
+
 ## Quick commands
 
 ```bash