docs: add INSTALL.md with IDE-specific install flows

INSTALL.md

@@ -0,0 +1,217 @@
+# Install Gradata Plugin
+
+Gradata captures corrections you make to AI coding agent output and graduates
+them into durable rules. Over time the agent converges on *your* judgment.
+
+## Quick install (all platforms)
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/Gradata/gradata-plugin/main/install.sh | sh
+```
+
+This clones the plugin to `~/.gradata/plugin/`, patches `AGENTS.md`, and
+detects which agent CLI(s) you have installed so hooks are wired.
+
+## Requirements
+
+- **Python 3.10+** — SDK host (daemon + graduation logic)
+- **Node.js 18+** — plugin hooks
+- One or more AGENTS.md-aware agent CLIs (see below)
+- `pip install git+https://github.com/Gradata/gradata.git#subdirectory=Gradata` (PyPI publish coming soon)
+
+---
+
+## Per-IDE install flows
+
+### Claude Code
+
+Claude Code loads Gradata as a plugin via `~/.claude/plugins/gradata`.
+The quick install sets this up automatically. Manual setup:
+
+```sh
+git clone --depth 1 https://github.com/Gradata/gradata-plugin "$HOME/.gradata/plugin"
+node "$HOME/.gradata/plugin/setup/install.js" --auto
+# or install Claude-specific:
+node "$HOME/.gradata/plugin/setup/install.js" --agent claude
+```
+
+**What gets installed:**
+- `~/.claude/plugins/gradata` → symlink to `~/.gradata/plugin`
+- AGENTS.md Gradata block between `<!-- BEGIN GRADATA -->` / `<!-- END GRADATA -->`
+- `/gradata status`, `/gradata review`, etc. slash commands
+
+**Post-install checklist:**
+- [ ] `node ~/.gradata/plugin/setup/doctor.js` reports all green
+- [ ] In Claude Code: `/gradata doctor` works
+- [ ] Start a session, make a correction, end session, wait 24h, check `AGENTS.md`
+
+---
+
+### Codex (OpenAI)
+
+Codex uses a hook block in `~/.codex/config.toml`. The quick install adds it
+automatically. Manual:
+
+```sh
+git clone --depth 1 https://github.com/Gradata/gradata-plugin "$HOME/.gradata/plugin"
+node "$HOME/.gradata/plugin/setup/install.js" --auto
+# or install Codex-specific:
+node "$HOME/.gradata/plugin/setup/install.js" --agent codex
+```
+
+**What gets installed:**
+- `~/.codex/config.toml` — managed hook block between `# BEGIN GRADATA CODEX HOOKS` / `# END GRADATA CODEX HOOKS`
+- AGENTS.md Gradata block
+- Session lifecycle hooks: start, prompt, edit, stop
+
+**Post-install checklist:**
+- [ ] `node ~/.gradata/plugin/setup/doctor.js` reports all green
+- [ ] `cat ~/.codex/config.toml` shows Gradata hook block
+- [ ] Start a Codex session — on exit, confirm no error in Gradata daemon logs
+- [ ] After ~1h of work, check `~/.gradata/projects/` for lesson files
+
+---
+
+### Cursor
+
+Cursor uses hooks in `~/.cursor/hooks.json`.
+
+```sh
+git clone --depth 1 https://github.com/Gradata/gradata-plugin "$HOME/.gradata/plugin"
+node "$HOME/.gradata/plugin/setup/install.js" --auto
+# or install Cursor-specific:
+node "$HOME/.gradata/plugin/setup/install.js" --agent cursor
+```
+
+**What gets installed:**
+- `~/.cursor/hooks.json` — managed hook entries
+- AGENTS.md Gradata block
+
+**Post-install checklist:**
+- [ ] `node ~/.gradata/plugin/setup/doctor.js` reports all green
+- [ ] `cat ~/.cursor/hooks.json` shows Gradata hook entries
+- [ ] In Cursor: start session, make a code edit, end session — verify hooks fired
+
+---
+
+### VSCode (via Cline or Continue.dev)
+
+VSCode does not have a built-in AGENTS.md reader. Use Cline or Continue.dev
+(both AGENTS.md-aware extensions) with the Gradata plugin.
+
+```sh
+git clone --depth 1 https://github.com/Gradata/gradata-plugin "$HOME/.gradata/plugin"
+node "$HOME/.gradata/plugin/setup/install.js" --auto --patch-agents-md "$PWD/AGENTS.md"
+```
+
+The `--patch-agents-md` flag targets your project's AGENTS.md (omit for
+`~/AGENTS.md`). Cline reads AGENTS.md from the project root automatically.
+
+**Post-install checklist:**
+- [ ] `node ~/.gradata/plugin/setup/doctor.js` reports all green
+- [ ] Project AGENTS.md contains a Gradata block
+- [ ] In VSCode with Cline: `/gradata-quickstart` loads the Gradata skill
+- [ ] Direct hooks (SessionStart, UserPromptSubmit, Stop) are NOT wired —
+  Cline does not expose lifecycle hooks. Rules inject via AGENTS.md block only.
+  Graduation sweeps require you to run `node ~/.gradata/plugin/setup/doctor.js`
+  periodically to trigger the sweep manually.
+
+---
+
+### JetBrains (via Continue.dev)
+
+JetBrains does not have a built-in AGENTS.md reader. Use Continue.dev
+(an AGENTS.md-aware extension) with the Gradata plugin.
+
+```sh
+git clone --depth 1 https://github.com/Gradata/gradata-plugin "$HOME/.gradata/plugin"
+node "$HOME/.gradata/plugin/setup/install.js" --auto --patch-agents-md "$PWD/AGENTS.md"
+```
+
+Same caveats as VSCode: no lifecycle hooks, rules inject via AGENTS.md block
+only, graduation sweeps are manual via the doctor command.
+
+**Post-install checklist:**
+- [ ] `node ~/.gradata/plugin/setup/doctor.js` reports all green
+- [ ] Project AGENTS.md contains a Gradata block
+- [ ] In JetBrains with Continue.dev: Gradata section visible in AGENTS.md context
+
+---
+
+### Hermes / OpenCode / any AGENTS.md-aware CLI
+
+These runtimes read AGENTS.md automatically — no additional hook wiring needed.
+
+```sh
+git clone --depth 1 https://github.com/Gradata/gradata-plugin "$HOME/.gradata/plugin"
+node "$HOME/.gradata/plugin/setup/install.js" --auto
+```
+
+The `gradata-quickstart` skill provides the full command reference. Run the
+doctor for diagnostics at any time.
+
+**Post-install checklist:**
+- [ ] `node ~/.gradata/plugin/setup/doctor.js` reports all green
+
+---
+
+## Verify install
+
+The universal health check works across all IDEs and agent CLIs:
+
+```sh
+node ~/.gradata/plugin/setup/doctor.js
+```
+
+**Expected output on success:**
+
+```
+Gradata Doctor
+==============
+✓ Plugin checkout: ~/.gradata/plugin/ (v0.1.0)
+✓ Hooks: 7 hooks present, all parse clean
+✓ Node.js: v18+ detected
+✓ Python: 3.10+ detected at /usr/bin/python3
+✓ Daemon: reachable on 127.0.0.1:19519 (pid 12345)
+✓ AGENTS.md: Gradata block present, markers balanced (1/1)
+✓ Config: ~/.gradata/config.toml (python_path set)
+
+All checks passed. Plugin is healthy.
+```
+
+If any check fails, the doctor prints specific remediation steps.
+
+## Troubleshooting
+
+**"Daemon not available"**
+The Python daemon is not running. It auto-starts on session begin. If manually
+starting: `gradata daemon start` (or the path in `~/.gradata/config.toml`).
+
+**"No rules injecting"**
+Rules require graduation. A correction must repeat across sessions to reach
+PATTERN or RULE tier. New corrections start at INSTINCT and don't inject.
+
+**"Wrong Python"**
+Edit `~/.gradata/config.toml` and update `python_path` to the Python where
+the `gradata` package is installed (`which python3`).
+
+**"Marker corruption in AGENTS.md"**
+The installer detected unbalanced `<!-- BEGIN GRADATA -->` / `<!-- END GRADATA -->`
+markers. Remove both blocks manually and re-run the installer.
+
+## Uninstall
+
+```sh
+# Remove plugin checkout
+rm -rf ~/.gradata/plugin
+
+# Remove Gradata block from AGENTS.md (between markers)
+# Remove Claude Code plugin symlink
+rm -f ~/.claude/plugins/gradata
+
+# Remove Codex hooks (between # BEGIN GRADATA and # END GRADATA in config.toml)
+# Remove Cursor hooks (gradata entries in hooks.json)
+
+# Remove config and data (optional — destroys all lessons)
+rm -rf ~/.gradata
+```