diff --git a/CLAUDE.md b/CLAUDE.md
index 4c818d4..a93508c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,6 +4,13 @@
 
 ## Docs site
 
+### Audience and voice
+
+- These docs are for end users of XcodeBuildMCP (developers using the CLI and MCP server in their workflow), not contributors working on XcodeBuildMCP itself.
+- Write about what the command or feature does for the user and when to use it. Skip the "how it works" details: which APIs are called, what the lookup strategy is, internal fallbacks, file layouts, timeout values, protocol specifics, parsing rules.
+- Keep callouts and notes focused on things that affect the user's decisions (when to use a flag, when something will not work for them), not on justifying the implementation.
+- If you find yourself writing a per-channel mechanics table, a "fetched from ... by ..." sentence, or a "we chose X because Y" explanation, cut it.
+
 ### Adding or editing a page
 
 Content lives at `app/docs/_content/<slug>.mdx`. To add a new page, also update:
diff --git a/app/docs/_content/cli.mdx b/app/docs/_content/cli.mdx
index da7a471..c2d7ea5 100644
--- a/app/docs/_content/cli.mdx
+++ b/app/docs/_content/cli.mdx
@@ -27,6 +27,7 @@ xcodebuildmcp simulator build --help
 | `tools` | List every tool, grouped by workflow. |
 | `setup` | Interactive wizard to create or update `.xcodebuildmcp/config.yaml`. |
 | `init` | Install the MCP or CLI agent skill (Claude Code, Cursor, Codex). |
+| `upgrade` | Self-update the CLI using the package manager it was installed with. |
 | `simulator` | Build, install, launch, test, log capture on simulators. |
 | `device` | Install, launch, test on physical Apple devices. |
 | `macos` | Build, run, test macOS targets. |
@@ -119,6 +120,20 @@ xcodebuildmcp simulator record-video \
   Every command accepts <code>--output json</code> for JSONL event streams, suitable for CI pipelines and scripting.
 </Callout>
 
+## Keeping the CLI up to date
+
+Run `xcodebuildmcp upgrade` to check for a newer version and install it in place. No need to remember whether you installed via Homebrew or npm, the command figures that out and runs the right upgrade for you.
+
+```shell
+xcodebuildmcp upgrade           # show current vs latest, release notes, and confirm
+xcodebuildmcp upgrade --check   # just tell me if there's an update, don't prompt
+xcodebuildmcp upgrade --yes     # upgrade without asking
+```
+
+If you installed via `npx`, the command will tell you how to pick up the latest version the next time you invoke it (npx installs are ephemeral, so there's nothing to upgrade in place).
+
+In CI or other non-interactive contexts, pass `--check` or `--yes`. Without either flag in a non-TTY context, the command exits non-zero instead of hanging on a prompt.
+
 ## Per-workspace daemon
 
 The CLI auto-starts a daemon only when needed. Stateless tools (`build`, `test`, `list`, discovery) run in-process. Stateful tools route through the daemon:
diff --git a/app/docs/_content/installation.mdx b/app/docs/_content/installation.mdx
index 3bd9561..74c7609 100644
--- a/app/docs/_content/installation.mdx
+++ b/app/docs/_content/installation.mdx
@@ -22,12 +22,6 @@ brew tap getsentry/xcodebuildmcp
 brew install xcodebuildmcp
 ```
 
-Upgrade later:
-
-```shell
-brew update && brew upgrade xcodebuildmcp
-```
-
 ## Option B: npm / npx
 
 For CLI use, install globally:
@@ -41,6 +35,16 @@ For MCP-server-only use, no global install needed, just reference `npx` in your
 
 Pin a specific version by replacing `@latest` with a tag, for example `@2.3.2`.
 
+## Keeping it up to date
+
+Once installed, run the built-in self-update command:
+
+```shell
+xcodebuildmcp upgrade
+```
+
+It checks for a newer version and installs it in place using whichever package manager you installed with. See [CLI → Keeping the CLI up to date](/docs/cli#keeping-the-cli-up-to-date) for available flags.
+
 ## Verify
 
 Run the doctor to check your environment: