diff --git a/genie/installation.mdx b/genie/installation.mdx
index c130a03..0ab4fd4 100644
--- a/genie/installation.mdx
+++ b/genie/installation.mdx
@@ -47,8 +47,8 @@ curl -fsSL https://raw.githubusercontent.com/automagik-dev/genie/main/install.sh
   <Step title="Install the package">
     Downloads and installs `@automagik/genie` globally using your system's package manager.
   </Step>
-  <Step title="Link the Claude Code plugin">
-    Symlinks the plugin to `~/.claude/plugins/genie` so Claude Code can discover every slash command.
+  <Step title="Register the Claude Code plugin">
+    Runs `claude plugin marketplace add automagik-dev/genie` and `claude plugin install genie@automagik`, which registers Genie in Claude Code's plugin marketplace system (`~/.claude/plugins/installed_plugins.json`) so its skills — `/wish`, `/work`, `/review`, `/brainstorm`, and friends — are discoverable.
   </Step>
   <Step title="Configure git hooks">
     Wires up hooks for agent identity injection and event capture.
@@ -105,27 +105,67 @@ genie setup
 
 ## Verify your install
 
-Run the diagnostic tool to confirm every component is wired up:
+Run the diagnostic tool to confirm the CLI, prerequisites, and local config are wired up:
 
 ```bash
 genie doctor
 ```
 
 ```text
-Genie Doctor — Checking your setup...
-
-✓ genie CLI found (v4.260324.8)
-✓ Claude Code installed
-✓ tmux available (3.4)
-✓ Git configured
-✓ GitHub CLI authenticated
-✓ Plugin symlink active (~/.claude/plugins/genie → ...)
-✓ Git hooks configured
-✓ Config file exists (~/.genie/config.json)
-
-All checks passed.
+Genie Doctor
+────────────────────────────────────────
+
+Prerequisites:
+  ✓ tmux
+  ✓ jq
+  ✓ bun / node
+  ✓ Claude Code
+
+Installer Resolution:
+  ✓ Resolved binary ...
+
+Configuration:
+  ✓ Genie config exists ~/.genie/config.json
+  ✓ Setup complete
+  ✓ Claude settings exists ~/.claude/settings.json
+
+────────────────────────────────────────
 ```
 
+<Warning>
+  `genie doctor` checks the CLI and local config — it does **not** currently verify that the Claude Code plugin is registered. Use the plugin check below as well; a green `genie doctor` does not by itself mean your slash commands will work.
+</Warning>
+
+### Verify the plugin is registered
+
+`genie doctor` doesn't check plugin registration, so confirm it separately with Claude Code's own CLI:
+
+```bash
+claude plugin list
+```
+
+You should see:
+
+```text
+Installed plugins:
+
+  ❯ genie@automagik
+    Version: 5.x.x
+    Scope: user
+    Status: ✔ enabled
+```
+
+If it's missing, register it manually:
+
+```bash
+claude plugin marketplace add automagik-dev/genie
+claude plugin install genie@automagik
+```
+
+<Note>
+  **Restart required.** After any install or update, Claude Code only picks up plugin changes ("skills"/slash commands like `/wish`, `/work`, `/review`) on the *next* session start. If a slash command doesn't autocomplete, restart your `claude` session before assuming the install failed.
+</Note>
+
 ## Environment variables
 
 | Variable | Default | Description |
@@ -142,13 +182,24 @@ genie update          # Stable channel
 genie update --next   # Development builds
 ```
 
+<Warning>
+  `genie update` pulls the CLI from npm/Bun's dist-tag, which can lag behind the plugin marketplace source on GitHub. If `genie update` reports an older version than what `claude plugin list` shows, it can overwrite the plugin's marketplace metadata down to the older version as a side effect. Recover with:
+
+  ```bash
+  claude plugin marketplace update automagik
+  claude plugin update genie@automagik
+  ```
+
+  Then restart your Claude Code session.
+</Warning>
+
 ## Uninstalling
 
 ```bash
 genie uninstall
 ```
 
-This removes the CLI, plugin symlink, and git hooks. Your project's `.genie/` state directory is preserved.
+This removes the hook script, orchestration rules, `~/.local/bin` CLI symlinks, and the global `~/.genie` directory. It does **not** remove the npm/Bun package itself — the command will remind you to also run `bun remove -g @automagik/genie` or `npm uninstall -g @automagik/genie`. It also does **not** unregister the Claude Code plugin; run `claude plugin uninstall genie@automagik` separately if you want that removed too. Your project's local `.genie/` state directory is preserved.
 
 ## What's next