diff --git a/CLAUDE.md b/CLAUDE.md
index f44b74ee..d87536d5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -29,15 +29,24 @@ npm run build
 
 This repo vendors [blender-mcp](https://github.com/ahujasid/blender-mcp) as a git submodule at `mcp/blender-mcp` and registers it in `.mcp.json`. **Prefer the blender-mcp tools over manual scripting** when the task involves creating or editing 3D models, materials, or scenes in Blender (e.g. ship/arena assets) — it drives a live Blender instance directly rather than hand-writing `.blend`/Python scene-manipulation code.
 
-Setup after cloning (same submodule caveat as godot-mcp above):
+Setup after cloning (same submodule caveat as godot-mcp above): `git submodule update --init --recursive`.
+
+**Preflight — run this before the first blender-mcp tool call in a session** (both commands are idempotent and quick when already current; don't repeat them for later calls in the same session):
 
 ```bash
-git submodule add https://github.com/ahujasid/blender-mcp.git mcp/blender-mcp
 cd mcp/blender-mcp
-uv sync
+uv sync                           # the submodule pointer moves often and deps drift with it
+uv run blender-mcp install-addon  # copies the bundled addon into Blender's user addons dir
 ```
 
-One-time manual step (GUI, can't be scripted): install the Blender addon — Blender → Edit → Preferences → Add-ons → Install → select `mcp/blender-mcp/addon.py` → enable "Interface: Blender MCP". Blender must be running with the addon's socket server started (default `localhost:9876`) for the MCP tools to connect; override with the `BLENDER_HOST` / `BLENDER_PORT` env vars in `.mcp.json` if needed.
+`install-addon` replaced the old manual GUI install (Preferences → Add-ons → Install → `addon.py`). It discovers Blender's addons directory itself (`uv run blender-mcp addon-paths` lists candidates; `--addons-dir` or `BLENDERMCP_ADDONS_DIR` overrides), backs up any existing copy, and is version-aware — it compares `ADDON_PROTOCOL_VERSION` in the installed file against the bundled one and rewrites only when the installed copy is missing or older, so a no-op run is cheap. The source of truth is `src/blender_mcp/bundled/addon.py`; the repo-root `addon.py` is an identical copy kept for the legacy manual path.
+
+What still cannot be scripted, and is the user's job — ask them rather than retrying a failing tool call:
+
+- Blender must be running with "Interface: Blender MCP" enabled and its socket server started (default `localhost:9876`; override via `BLENDER_HOST` / `BLENDER_PORT` in `.mcp.json`).
+- If `install-addon` rewrote the addon while Blender was open, the new code isn't loaded until Blender restarts or the addon is disabled/re-enabled. Treat "install-addon reported an update" as a signal to tell the user to restart Blender before continuing.
+
+Upstream ships telemetry with a consent prompt that arrives through the MCP client on first use. To opt out, set `DISABLE_TELEMETRY=1` (or `BLENDER_MCP_DISABLE_TELEMETRY` / `MCP_DISABLE_TELEMETRY`) in the server's `env` block in `.mcp.json`.
 
 ## Commands