feat: add frictionless RA-H OS setup

- Add MCP setup, doctor, init-db, config, and rules CLI commands
- Publish latest MCP package wiring and local setup helper
- Update OS install docs for MCP-only, full app, and demo-safe setup

Generated with Claude Code

docs/8_mcp.md

@@ -2,6 +2,40 @@
 
 RA-H exposes MCP tools for direct graph work against the local database or app API.
 
+## Quick Install
+
+For normal users, configure MCP through the published package:
+
+```bash
+npx -y ra-h-mcp-server@latest setup --client claude-code --yes
+```
+
+Other clients:
+
+```bash
+npx -y ra-h-mcp-server@latest setup --client cursor --yes
+npx -y ra-h-mcp-server@latest setup --client codex
+```
+
+`--yes` lets the installer write supported JSON client config automatically. Codex uses TOML config, so the installer prints the block to add.
+
+Verify the install:
+
+```bash
+npx -y ra-h-mcp-server@latest doctor
+```
+
+Manual JSON/TOML config should be treated as troubleshooting or unsupported-client fallback. Public docs should not point users at stale pinned versions; use `@latest` by default and pin exact versions only for release/debug reproducibility.
+
+For demo isolation or a separate DB:
+
+```bash
+npx -y ra-h-mcp-server@latest setup \
+  --client claude-code \
+  --yes \
+  --db "$HOME/Desktop/ra-h_os-demo-data/rah.sqlite"
+```
+
 Important runtime distinction:
 
 - the app MCP surface talks to the running app/API

docs/README.md

@@ -26,9 +26,21 @@
 ## Start Here
 
 If you just want RA-H OS working:
-1. Read [../README.md](../README.md)
-2. Follow [MCP](./8_mcp.md) if you want external-agent access
-3. Read [Full Local](./10_full-local.md) if you want a more local-first or community setup
+1. Use the MCP quick install below if you mainly want agent access.
+2. Use the local app quick start if you also want the browser UI.
+3. Read [Full Local](./10_full-local.md) if you want a more local-first or community setup.
+
+## MCP Quick Install
+
+```bash
+npx -y ra-h-mcp-server@latest setup --client claude-code --yes
+```
+
+Run `doctor` after setup or whenever MCP feels stale:
+
+```bash
+npx -y ra-h-mcp-server@latest doctor
+```
 
 ## Local App Quick Start
 
@@ -36,8 +48,7 @@ If you just want RA-H OS working:
 git clone https://github.com/bradwmorris/ra-h_os.git
 cd ra-h_os
 npm install
-npm rebuild better-sqlite3
-npm run bootstrap:local
+npm run setup:local
 npm run dev
 ```
 
@@ -45,22 +56,22 @@ Open http://localhost:3000
 
 ## MCP Integration
 
-Add to your `~/.claude.json`:
+The recommended MCP setup is the CLI command above. Manual config is only for troubleshooting or unsupported clients:
 
 ```json
 {
   "mcpServers": {
     "ra-h": {
       "command": "npx",
-      "args": ["--yes", "ra-h-mcp-server@2.1.2"]
+      "args": ["-y", "ra-h-mcp-server@latest"]
     }
   }
 }
 ```
 
-If you publish a newer MCP release and need clients to use it immediately, bump the pinned version here and restart the client. Do not assume plain `npx ra-h-mcp-server` always refreshes instantly.
+If you need a frozen version for release/debug work, pin it intentionally and restart the client.
 
-Run RA-H once first so the database exists. The standalone MCP server can write nodes without the app running, but the app owns chunking and embedding from node source: readable `chunks`, full-text indexes, `vec_nodes`, and `vec_chunks`. See [MCP docs](./8_mcp.md) for the full install, verify, memory-file, and troubleshooting path.
+The setup command creates the default database if it does not exist. The standalone MCP server can write nodes without the app running, but the app owns chunking and embedding from node source: readable `chunks`, full-text indexes, `vec_nodes`, and `vec_chunks`. See [MCP docs](./8_mcp.md) for the full install, verify, memory-file, and troubleshooting path.
 
 ## Questions?
 

docs/TROUBLESHOOTING.md

@@ -18,17 +18,17 @@ sudo apt install build-essential python3
 npm install -g windows-build-tools
 ```
 
-### `npm rebuild better-sqlite3` fails
+### `npm run setup:local` fails
 
 **Symptom:** Native module rebuild errors
 
 **Fix:**
-1. Ensure Node.js 18+ is installed
+1. Ensure Node.js 20.18.1+ is installed
 2. Delete `node_modules` and reinstall:
    ```bash
    rm -rf node_modules package-lock.json
    npm install
-   npm rebuild better-sqlite3
+   npm run setup:local
    ```
 
 ## Runtime Issues
@@ -38,7 +38,7 @@ npm install -g windows-build-tools
 **Symptom:** Error on `npm run dev`
 
 **Fixes:**
-1. Run the bootstrap script first: `scripts/dev/bootstrap-local.sh`
+1. Run local setup first: `npm run setup:local`
 2. Check `.env.local` exists (copy from `.env.example` if missing)
 3. Ensure database directory exists: `~/Library/Application Support/RA-H/db/`
 

docs/development/process.md

@@ -16,8 +16,7 @@ This repo is the open-source build of RA-H. Keep changes focused, reviewable, an
 git clone https://github.com/bradwmorris/ra-h_os.git
 cd ra-h_os
 npm install
-npm rebuild better-sqlite3
-scripts/dev/bootstrap-local.sh
+npm run setup:local
 npm run dev
 ```
 
@@ -57,4 +56,4 @@ npm run build
   - stricter node/edge validation
   - improved eval logging/UI
   - reduced 5-scenario eval suite with archived legacy scenarios
-- after pulling changes, if SQLite routes fail locally, run `npm rebuild better-sqlite3` under the same Node version used for `npm run dev`
+- after pulling changes, if SQLite routes fail locally, run `npm run setup:local` under the same Node version used for `npm run dev`

docs/os_docs/2025-12-09-open-source-porting-notes.md

@@ -206,7 +206,7 @@ This document captures every change required to bring the private RA-H repo into
 
 ## 6. Testing
 - `npm run type-check` passes.
-- Local dev requires: `npm rebuild better-sqlite3` once per machine, `scripts/dev/bootstrap-local.sh`, `npm run dev`.
+- Local dev now uses: `npm run setup:local`, then `npm run dev`.
 - Manual smoke: open Settings → API Keys, add OpenAI + Anthropic keys (Anthropic test now succeeds), refresh; nodes/ui/chat all function.
 
 ## 7. Documentation Cleanup (2025-12-15)