diff --git a/claude-code-tools.md b/claude-code-tools.md
index 16e85bf..09639e3 100644
--- a/claude-code-tools.md
+++ b/claude-code-tools.md
@@ -127,6 +127,39 @@ Fast hybrid code search — combines tree-sitter AST parsing, FST symbol lookup,
 
 - **Key commands / MCP tools:** `search` (symbol + semantic), `show` (full body), `usages`, `callers`, `callees`, `implementations`, `outline`, `pattern` (ast-grep–style structural match), `similar` (semantic, requires `--semantic` index), `duplicates`, `status`, `grep` (regex fallback, no index needed), `update` (incremental reindex).
 
+- **Wire it into `CLAUDE.md` (recommended):**
+
+  Installing the binaries and building an index isn't enough — Claude won't reliably prefer `vex` over `Grep`/`Read` unless a `CLAUDE.md` tells it to.
+
+  **Start from upstream**, don't duplicate. The vex README maintains a canonical `CLAUDE.md` snippet — see [`README.md` → "CLAUDE.md Integration"](https://github.com/tenatarika/vex#claudemd-integration). Paste it into your **global** `~/.claude/CLAUDE.md` (applies to every project) or a **project-local** `./CLAUDE.md` (overrides global per repo).
+
+  **Then graft on these local additions** — they go beyond what upstream covers and are worth keeping wherever you install vex:
+
+  1. **MCP server line** — add this near the top of the snippet so Claude knows the MCP route exists:
+
+     > Equivalent **MCP tools** are also available via the `vex` MCP server when registered (`claude mcp add vex -s user`) — prefer them inside a Claude Code session for cheaper token output; use the Bash CLI from subagents, hooks, and scripts.
+
+  2. **Skip-vex rule** — add to the Rules block:
+
+     > **Skip vex** for non-code text — config files (YAML/JSON/TOML), docs, log strings, free-form prose — and for files in languages vex doesn't parse. Fall back to the next tool in the priority chain that's actually capable for the case (typically Grep/Glob for free-form text).
+
+  3. **Subagent reminder** — add to the Rules block:
+
+     > **Subagents** (Plan/Explore/general-purpose) don't inherit project CLAUDE.md or the parent's MCP toolset — explicitly tell them in the prompt to use `vex` via Bash for code search.
+
+  4. **`auto_update` accuracy fix** — upstream says "Run `vex update` after modifying source files if `auto_update` is not enabled." With `auto_update = true` it runs before *each search*, so during a Claude session the manual update is rarely needed. Reword as:
+
+     > **Run `vex update` manually after editing** only if `auto_update = false`; with `auto_update = true`, vex auto-refreshes before each search.
+
+  5. **`--semantic` cost note** — append to the `vex index --semantic` line in the Indexing block:
+
+     > downloads ~86 MB ONNX model on first run, enables `vex search --semantic`, `vex similar`, `vex duplicates`.
+
+  **When to put it in global vs project CLAUDE.md:**
+
+  - **Global (`~/.claude/CLAUDE.md`)** — preferred default once `vex-mcp` is registered at user scope. Vex becomes the recommendation for every project as soon as the index is built.
+  - **Project-local (`./CLAUDE.md`)** — for overrides (different fallback chain, monorepo-specific `--filter` paths, language-specific `--kind` defaults, or excluding vex on repos where it isn't set up).
+
 ### Packaged Skills
 
 Packaged `.skill` files available in the [skills/](skills/) directory: