diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..b1fcf0d
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,186 @@
+# Install Gradata Plugin
+
+Pick your IDE below. Each section is self-contained — follow ONE path.
+
+**Prerequisites (all IDEs):** Git, Node.js 18+, Python 3.10+.
+
+---
+
+## 1. VSCode
+
+The Gradata plugin runs inside Claude Code's extension for VSCode.
+
+### Install
+
+1. Install the [Claude Code extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) from the VSCode marketplace.
+2. Clone the Gradata plugin into Claude Code's plugins directory:
+
+   ```sh
+   git clone https://github.com/Gradata/gradata-plugin ~/.claude/plugins/gradata
+   ```
+
+3. Run the one-time setup script (auto-detects Python, installs `gradata` SDK if needed):
+
+   ```sh
+   node ~/.claude/plugins/gradata/setup/install.js
+   ```
+
+### Verify
+
+Open the Claude Code panel in VSCode (`Cmd+Shift+P` → "Claude Code: Open") and run:
+
+```
+/gradata doctor
+```
+
+Expected output:
+
+```
+Gradata Doctor
+  [+] Daemon running (PID: ...)
+  [+] Brain connected
+  [+] 7 hooks loaded
+  [+] 7 skills registered
+```
+
+If the daemon isn't running, `/gradata doctor` will start it automatically.
+
+### Post-install checklist
+
+- [ ] `~/.claude/plugins/gradata/.claude-plugin/plugin.json` exists
+- [ ] `~/.gradata/config.toml` has a valid `python_path`
+- [ ] `gradata` Python package is installed (`pip list | grep gradata`)
+
+---
+
+## 2. Cursor
+
+Cursor ships Claude Code integration. The plugin install is identical to VSCode.
+
+### Install
+
+1. Install Claude Code in Cursor: open the Cursor command palette (`Cmd+Shift+P` / `Ctrl+Shift+P`), search "Claude Code", and enable it. (Cursor bundles Claude Code — no marketplace install needed on recent builds.)
+2. Clone the plugin:
+
+   ```sh
+   git clone https://github.com/Gradata/gradata-plugin ~/.claude/plugins/gradata
+   ```
+
+3. Run setup:
+
+   ```sh
+   node ~/.claude/plugins/gradata/setup/install.js
+   ```
+
+### Verify
+
+In the Claude Code chat panel inside Cursor, run:
+
+```
+/gradata doctor
+```
+
+Expected output matches VSCode: green checkmarks on daemon, brain, hooks, and skills.
+
+### Note: activation events
+
+Cursor's Claude Code integration fires the same lifecycle hooks as VSCode — `session-start`, `user-prompt`, `post-edit`, `session-stop`. If `/gradata doctor` shows hooks loaded but you don't see rules injecting after corrections, confirm Cursor is running Claude Code ≥ 1.0.37 (check `Cmd+Shift+P` → "Claude Code: About").
+
+### Post-install checklist
+
+- [ ] Same three checks as VSCode section above
+- [ ] Run a correction in Cursor (edit AI output), then `/gradata status` — lesson count should be ≥ 1
+
+---
+
+## 3. JetBrains (IntelliJ / PyCharm / WebStorm / GoLand)
+
+Gradata does not yet ship a JetBrains plugin with hook wiring. The Gradata SDK works standalone for manual capture and rule management.
+
+### Install
+
+1. Install the Gradata Python SDK:
+
+   ```sh
+   pip install gradata
+   ```
+
+2. (Optional) Set a brain directory if you want project-local storage instead of the default `~/.gradata/`:
+
+   ```sh
+   export BRAIN_DIR="$HOME/.gradata/brain"
+   ```
+
+### Usage (manual mode)
+
+Without hook wiring, you work with the `gradata` CLI directly:
+
+```sh
+# Start the daemon in a terminal tab
+gradata daemon --port 7342
+
+# In another tab, capture a correction manually
+gradata capture \
+  --tool Edit \
+  --old 'console.log("x")' \
+  --new 'logger.info("x")' \
+  --file src/app.ts
+
+# Review lessons and promote
+gradata review
+gradata promote --id <lesson-id>
+
+# Export rules as markdown for use in JetBrains AI chat / project context
+gradata rules --format markdown > .gradata-rules.md
+```
+
+### Verify
+
+```sh
+gradata doctor
+```
+
+Expected output:
+
+```
+Brain Dir     [+]  /home/user/.gradata/brain
+Python        [+]  3.12.x
+gradata SDK   [+]  1.x.x
+```
+
+### Post-install checklist
+
+- [ ] `gradata --version` prints a version
+- [ ] `gradata doctor` shows all green checkmarks
+- [ ] `gradata daemon` starts without errors (stop with Ctrl+C)
+
+---
+
+## Troubleshooting (all IDEs)
+
+**"Daemon not available"**
+The Python daemon isn't running or isn't reachable on `127.0.0.1:7342`. Run `/gradata doctor` — it auto-starts the daemon if it's down.
+
+**"No rules injecting"**
+Rules require graduation. A correction must repeat across 3+ sessions to reach PATTERN, further to reach RULE. Run `/gradata status` to check lesson count and tiers.
+
+**"Wrong Python"**
+The daemon uses the Python interpreter from `~/.gradata/config.toml`. If you installed `gradata` into a venv, update `python_path` in that file to point at the venv's interpreter.
+
+**"Plugin not loading" (VSCode / Cursor)**
+Check that the plugin directory is correct:
+
+```sh
+ls ~/.claude/plugins/gradata/.claude-plugin/plugin.json
+```
+
+If missing, the clone didn't land properly. Re-run step 2 of the VSCode/Cursor install.
+
+**"node: command not found"**
+Node.js is a prerequisite for the plugin installer and hooks. Install via [nvm](https://github.com/nvm-sh/nvm), [fnm](https://github.com/Schniz/fnm), or your system package manager.
+
+---
+
+## Next steps
+
+After install, read the [README](README.md) for architecture, commands, and how corrections graduate into rules.