diff --git a/CLAUDE.md b/CLAUDE.md
index a0f9960..0afc94d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,23 +1,29 @@
 # Claude Instructions for WLED Screen Controller
 
-## CRITICAL: Use ast-index for Code Search
+## Code Search
 
-**Always use `ast-index` as the PRIMARY code search tool.** It is 17-69x faster than grep and returns structured, accurate results.
+**If `ast-index` is available, use it as the PRIMARY code search tool.** It is significantly faster than grep and returns structured, accurate results. Fall back to grep/Glob only when ast-index is not installed, returns empty results, or when searching regex patterns/string literals/comments.
 
-- **Use ast-index first** for: finding classes, symbols, usages, implementations, files, callers, hierarchy
-- **Fall back to Grep only** for: regex patterns, string literals inside code, comment content, or when ast-index returns empty results
-- Run `ast-index update` if the index feels stale after many file changes
-- Run `ast-index rebuild` if the index is missing or corrupted
+**IMPORTANT for subagents:** When spawning Agent subagents (Plan, Explore, general-purpose, etc.), always instruct them to use `ast-index` via Bash for code search instead of grep/Glob. Example: include "Use `ast-index search`, `ast-index class`, `ast-index usages` etc. via Bash for code search" in the agent prompt.
 
-Common commands:
 ```bash
-ast-index search "Query"              # Universal search
-ast-index symbol "Name"               # Find symbol definitions
-ast-index usages "Symbol"             # Find all usages
-ast-index class "Name"                # Find class/interface
-ast-index implementations "Parent"    # Find implementations
-ast-index outline "path/to/file"      # Show file structure
-ast-index callers "funcName"          # Find call sites
+# Check if available:
+ast-index version
+
+# Rebuild index (first time or after major changes):
+ast-index rebuild
+
+# Common commands:
+ast-index search "Query"                  # Universal search across files, symbols, modules
+ast-index class "ClassName"               # Find class/struct/interface definitions
+ast-index usages "SymbolName"             # Find all places a symbol is used
+ast-index implementations "BaseClass"     # Find all subclasses/implementations
+ast-index symbol "FunctionName"           # Find any symbol (class, function, property)
+ast-index outline "path/to/File.cpp"      # Show all symbols in a file
+ast-index hierarchy "ClassName"           # Show inheritance tree
+ast-index callers "FunctionName"          # Find all call sites
+ast-index changed --base master           # Show symbols changed in current branch
+ast-index update                          # Incremental update after file changes
 ```
 
 ## CRITICAL: Git Commit and Push Policy