Clarify setup profiles in README

README.md

@@ -9,7 +9,7 @@
  ╚═╝  ╚═╝╚═╝  ╚═╝      ╚═╝  ╚═╝
 ```
 
-**TL;DR:** Use the MCP quick install if you want Claude Code, Cursor, Codex, or another agent to read and write your local graph. Clone this repository only if you also want the local browser UI.
+**TL;DR:** Use the MCP quick install if you want Claude Code, Cursor, Codex, or another agent to read and write your local graph. Clone this repository only if you also want the local browser UI. If you clone the repo, choose **OpenAI** or **local Qwen** before setup creates the vector tables.
 
 [![Watch the setup walkthrough](https://img.youtube.com/vi/YyUCGigZIZE/hqdefault.jpg)](https://youtu.be/YyUCGigZIZE?si=USYgvmwtdGpgGdwu)
 
@@ -25,7 +25,7 @@
 2. **Provides a UI** — Browse, search, and organize your nodes at `localhost:3000`
 3. **Exposes an MCP server** — Claude Code and other MCP clients can query and add to your knowledge base
 
-Your data stays on your machine. Nothing is sent anywhere unless you configure an API key.
+Your database stays on your machine. With the `openai` profile, model requests go to OpenAI after you add an API key. With the `qwen-local` profile, model requests go to your local Ollama/OpenAI-compatible endpoint.
 
 Current contract:
 - no runtime `dimensions`
@@ -53,7 +53,8 @@ Current contract:
 | You want... | Use this path |
 |-------------|---------------|
 | Your AI coding agent can read/write your RA-H graph | **Option A: MCP-only quick install** |
-| A browser UI at `localhost:3000` | **Option B: Full local app** |
+| A browser UI at `localhost:3000` with OpenAI models | **Option B1: Full local app with OpenAI** |
+| A browser UI at `localhost:3000` with local Qwen models | **Option B2: Full local app with local Qwen** |
 | A clean demo that does not touch your real graph | **Demo-safe isolated install** |
 
 ### Option A: MCP-only quick install
@@ -105,21 +106,41 @@ Notes:
 npx -y ra-h-mcp-server@latest setup --client claude-code --yes --pin current
 ```
 
-### Option B: Full local app
+### Option B1: Full local app with OpenAI
 
-Use this if you want the browser UI at `localhost:3000`.
+Use this if you want the browser UI at `localhost:3000` and want RA-H to use OpenAI for descriptions, embeddings, and semantic search.
 
 ```bash
 git clone https://github.com/bradwmorris/ra-h_os.git
 cd ra-h_os
 npm install
-npm run setup:local
+npm run setup:local -- --profile openai
 npm run dev
 ```
 
-Open [localhost:3000](http://localhost:3000). Done.
+Open [localhost:3000](http://localhost:3000). Add your OpenAI API key when the app prompts you, or later in Settings -> API Keys.
 
-If you also want your coding agent connected to the same database, run Option A after the app setup.
+### Option B2: Full local app with local Qwen
+
+Use this if you want the browser UI at `localhost:3000` and want RA-H to call local OpenAI-compatible Ollama endpoints instead of OpenAI.
+
+Prerequisites:
+- Ollama is installed and running.
+- These models are pulled before setup.
+
+```bash
+git clone https://github.com/bradwmorris/ra-h_os.git
+cd ra-h_os
+npm install
+ollama pull qwen3:4b
+ollama pull qwen3-embedding:0.6b
+npm run setup:local -- --profile qwen-local
+npm run dev
+```
+
+Open [localhost:3000](http://localhost:3000). Settings -> API Keys will show the active local model profile and disable OpenAI key entry.
+
+If you also want your coding agent connected to the same default database, run Option A after the app setup. If you override `SQLITE_DB_PATH`, pass the same path to the MCP installer with `--db`.
 
 Full install details:
 - [docs/README.md](./docs/README.md)
@@ -130,11 +151,18 @@ Full install details:
 
 ---
 
-## First-Time Setup
+## First-Time Setup Rules
 
-Pick the embedding profile before the database is created. This matters because
+Pick the embedding profile before the database is created.
-the readable `nodes` and `chunks` tables are normal SQLite tables, but the
+
-derived sqlite-vec vector tables are created with a fixed embedding width.
+This is not cosmetic. The readable `nodes` and `chunks` tables are normal SQLite tables, but the derived vector tables are created with a fixed embedding width:
+
+| Setup profile | Utility model | Embedding model | Vector width |
+|---------------|---------------|-----------------|--------------|
+| `openai` | `gpt-4o-mini` | `text-embedding-3-small` | `1536` |
+| `qwen-local` | `qwen3:4b` through Ollama | `qwen3-embedding:0.6b` through Ollama | `1024` |
+
+Setup requires one of these commands on a fresh install.
 
 OpenAI:
 
@@ -154,12 +182,9 @@ npm run setup:local -- --profile qwen-local
 npm run dev
 ```
 
-If you run setup without a profile and `.env.local` does not already select one,
+If you run setup without a profile and `.env.local` does not already select one, setup stops before creating vector tables and prints the two supported commands.
-setup stops before creating vector tables and prints the two supported commands.
 
-If you change embedding provider, model, dimensions, or vector backend after
+If you change embedding provider, model, dimensions, or vector backend after data exists, your source data stays intact but derived embeddings must be rebuilt:
-data exists, your source data stays intact but derived embeddings must be
-rebuilt:
 
 ```bash
 npm run rebuild:embeddings
@@ -169,7 +194,9 @@ npm run rebuild:embeddings
 
 ## OpenAI API Key
 
-**Optional but recommended.** Without a key, you can still create and organize nodes manually.
+Only applies to the `openai` setup profile.
+
+Without a key, you can still create and organize nodes manually.
 
 With a key, you get:
 - Auto-generated descriptions when you add nodes
@@ -178,15 +205,19 @@ With a key, you get:
 
 **Cost:** Less than $0.10/day for heavy use. Most users spend $1-2/month.
 
-**Setup:** The app will prompt you on first launch, or go to Settings → API Keys.
+**Setup:** The app will prompt you on first launch, or go to Settings -> API Keys.
 
 Get a key at [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
 
+If you selected `qwen-local`, do not add an OpenAI key in the UI. Settings -> API Keys shows the active local model profile and disables OpenAI key entry so the install stays aligned with the setup profile.
+
 ---
 
 ## Local Model Profile
 
-OpenAI remains the default supported cloud path. If you want local utility LLM calls and local embeddings, run a local OpenAI-compatible model server and point RA-H at it.
+Use the `qwen-local` setup profile if you want local utility LLM calls and local embeddings.
+
+RA-H does not bundle model weights. It calls a local OpenAI-compatible HTTP endpoint. The tested local path is Ollama with Qwen.
 
 Supported local contract:
 
@@ -240,6 +271,8 @@ QDRANT_URL=http://localhost:6333
 
 SQLite remains the source-of-truth database. Qdrant stores only derived vector indexes.
 
+Qdrant does not change your model choice. OpenAI vs local Qwen is controlled by `LLM_PROFILE` and `EMBEDDING_PROFILE`. sqlite-vec vs Qdrant is controlled by `VECTOR_BACKEND`.
+
 ---
 
 ## Where Your Data Lives
@@ -255,6 +288,18 @@ This is a standard SQLite file. You can:
 - Query it directly with `sqlite3` or any SQLite tool
 - Move it between machines
 
+Override the location only when you intentionally want a separate database:
+
+```bash
+SQLITE_DB_PATH="$HOME/Desktop/ra-h_os-demo-data/rah.sqlite" npm run setup:local -- --profile qwen-local
+```
+
+If MCP should use that same non-default database, pass the same path to the MCP installer:
+
+```bash
+npx -y ra-h-mcp-server@latest setup --client claude-code,codex --yes --db "$HOME/Desktop/ra-h_os-demo-data/rah.sqlite"
+```
+
 ---
 
 ## Demo-safe isolated install
@@ -398,8 +443,11 @@ See [docs/2_schema.md](./docs/2_schema.md) and [docs/8_mcp.md](./docs/8_mcp.md)
 
 | Command | What it does |
 |---------|--------------|
-| `npm run setup:local` | Rebuild native modules, create `.env.local`, create the SQLite DB, and seed the base schema |
+| `npm run setup:local -- --profile openai` | Rebuild native modules, create `.env.local`, create the SQLite DB, and seed OpenAI-width vector tables |
+| `npm run setup:local -- --profile qwen-local` | Rebuild native modules, create `.env.local`, create the SQLite DB, and seed Qwen-width vector tables |
+| `npm run setup:local` | Only valid if `.env.local` already selects an embedding profile; otherwise it stops before DB/vector setup |
 | `npm run bootstrap:local` | Lower-level helper used by `setup:local`; most users should not run this directly |
+| `npm run rebuild:embeddings` | Recreate derived embeddings after changing embedding provider, model, dimensions, or vector backend |
 | `npm run dev` | Start the app at localhost:3000 |
 | `npm run dev:local` | Alias for `npm run dev` |
 | `npm run build` | Production build |

docs/README.md

@@ -29,8 +29,8 @@
 
 If you just want RA-H OS working:
 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.
+2. Use the OpenAI local app quick start if you want the browser UI with OpenAI models.
-3. Read [Local Models](../LOCAL-MODELS.md) and [Full Local](./10_full-local.md) if you want a more local-first setup.
+3. Use the local Qwen quick start if you want the browser UI with local Ollama models.
 
 ## MCP Quick Install
 
@@ -44,17 +44,35 @@ Run `doctor` after setup or whenever MCP feels stale:
 npx -y ra-h-mcp-server@latest doctor
 ```
 
-## Local App Quick Start
+## Local App Quick Start: OpenAI
 
 ```bash
 git clone https://github.com/bradwmorris/ra-h_os.git
 cd ra-h_os
 npm install
-npm run setup:local
+npm run setup:local -- --profile openai
 npm run dev
 ```
 
-Open http://localhost:3000
+Open http://localhost:3000 and add your OpenAI API key when prompted, or later in Settings -> API Keys.
+
+## Local App Quick Start: Local Qwen
+
+Requires Ollama to be installed and running.
+
+```bash
+git clone https://github.com/bradwmorris/ra-h_os.git
+cd ra-h_os
+npm install
+ollama pull qwen3:4b
+ollama pull qwen3-embedding:0.6b
+npm run setup:local -- --profile qwen-local
+npm run dev
+```
+
+Open http://localhost:3000. Settings -> API Keys shows the active local model profile and disables OpenAI key entry.
+
+Fresh app setup must choose `--profile openai` or `--profile qwen-local` before vector tables are created. OpenAI embeddings use width `1536`; the supported Qwen embedding profile uses width `1024`.
 
 ## MCP Integration
 
@@ -73,7 +91,7 @@ The recommended MCP setup is the CLI command above. Manual config is only for tr
 
 If you need a frozen version for release/debug work, pin it intentionally and restart the client.
 
-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.
+The selected setup profile 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?