Add local AI and Qdrant vector backends

docs/10_full-local.md

@@ -19,10 +19,18 @@ Supported core path:
 - local SQLite DB
 - standard standalone MCP server
 - documented repo install flow
-- hosted model APIs if you choose them
+- OpenAI model APIs by default, or the documented OpenAI-compatible local endpoint profile
 
 This is the path the core docs and troubleshooting are written for.
 
+Supported local model profile:
+- RA-H calls a local OpenAI-compatible HTTP endpoint
+- the local runtime can be Ollama or llama.cpp after you start it yourself
+- the initial local model pair is Qwen3 4B plus Qwen3 Embedding 0.6B
+- embedding dimensions are 1024 unless a tested runtime proves a different supported dimension is needed
+
+Start with [Local Models](../LOCAL-MODELS.md).
+
 ## 3. Where Local-First Starts Getting Experimental
 
 Local-first gets more experimental when you change:
@@ -34,12 +42,13 @@ Local-first gets more experimental when you change:
 
 That does not make those setups bad. It just changes the support boundary.
 
-## 4. Community Pattern: Local Models + RA-H MCP
+## 4. Supported Local Model Profile + RA-H MCP
 
-Reasonable community pattern:
+Supported app utility/embedding pattern:
 - keep RA-H OS local
 - keep SQLite local
-- connect a local-model-capable client to RA-H through MCP
+- run a local OpenAI-compatible model server for app utility LLM calls and embeddings
+- connect a local-model-capable external client to RA-H through MCP if you want local agent runtime too
 
 Honest caveat:
 - tool-calling quality depends heavily on the model/runtime
@@ -63,16 +72,19 @@ References:
 - https://docs.anythingllm.com/mcp-compatibility/overview
 - https://docs.anythingllm.com/agent/intelligent-tool-selection
 
-## 6. Community Pattern: Qdrant Add-On For Vector-Heavy Or `sqlite-vec`-Hostile Environments
+## 6. Qdrant Sidecar For `sqlite-vec`-Hostile Environments
 
-Qdrant is a plausible local or self-hosted vector backend when:
-- `sqlite-vec` is weak on the target platform
-- storage/runtime constraints make the default vector path awkward
-- you are intentionally running a more custom environment
+Qdrant is a supported optional vector sidecar when:
+- `sqlite-vec` is unavailable or unreliable on the target platform
+- Alpine/musl, Windows ARM64, or uncertain ARM64 environments make native extensions awkward
+- you want Qdrant's vector index while keeping SQLite as the source-of-truth database
 
 Important boundary:
-- this is not a bundled official RA-H core dependency
-- the Nathan Maine repo is a community add-on example, not the default install story
+- Qdrant is not required for local embeddings
+- Qdrant does not replace SQLite as the app database
+- the Nathan Maine repo is a community reference, not the current implementation contract
+
+Start with [Qdrant Deployment](../QDRANT-DEPLOYMENT.md).
 
 References:
 - https://qdrant.tech/documentation/quickstart/
@@ -92,11 +104,15 @@ Supported core path:
 - repo install flow
 - SQLite
 - documented standalone MCP setup
+- OpenAI default AI profile
+- documented OpenAI-compatible local endpoint profile
+- sqlite-vec default vector backend
+- Qdrant fallback backend for sqlite-vec-hostile environments
 
 Reasonable community pattern:
-- alternate local-model or alternate local chat surface that still respects the MCP contract
+- alternate local chat surface that still respects the MCP contract
 
 Experimental / user-owned:
-- custom vector backend swaps
+- arbitrary custom model/provider choices outside the tested local profile
 - unsupported runtime targets
 - heavily modified inference stacks

docs/2_schema.md

@@ -83,7 +83,7 @@ Machine-readable semantic vectors for chunks.
 
 Shape:
 - `chunk_id`
-- `embedding FLOAT[1536]`
+- `embedding FLOAT[active embedding dimensions]`
 
 `vec_chunks` is a separate sqlite-vec virtual table. It is table-like, but it is optimized for vector similarity search rather than normal text inspection.
 
@@ -100,7 +100,7 @@ Concrete live example from the April 20 audit:
 - chunk `108055`: `chunk_idx = 0`
 - chunk text starts with `[0.1s] Tell me about your levels.`
 - `vec_chunks` has a matching row where `chunk_id = 108055`
-- that row stores a 1536-number embedding for semantic comparison
+- that row stores a numeric embedding for semantic comparison. OpenAI `text-embedding-3-small` defaults to 1536 dimensions; the supported local Qwen3 embedding profile uses 1024 dimensions.
 
 ### `vec_nodes`
 
@@ -108,7 +108,7 @@ Machine-readable semantic vectors for whole nodes.
 
 Shape:
 - `node_id`
-- `embedding FLOAT[1536]`
+- `embedding FLOAT[active embedding dimensions]`
 
 The join point is:
 

docs/8_mcp.md

@@ -45,6 +45,7 @@ Important runtime distinction:
 - the standalone MCP surface talks directly to an existing SQLite DB file
 - standalone MCP can read and write nodes/edges without the app running, but it does not own chunking or embedding
 - if standalone MCP writes `nodes.source` while the app is closed, the app later processes that node through startup recovery
+- external MCP agent model choice is separate from RA-H app utility model choice; app utility LLMs and embeddings use `LLM_PROFILE` and `EMBEDDING_PROFILE`
 
 ## WAL / Multi-Surface Safety
 
@@ -124,6 +125,7 @@ MCP users should understand the same retrieval split as the app:
 - `vec_nodes` can find semantically similar whole nodes when node-level vectors exist
 - `vec_chunks` can find semantically similar passages when chunk-level vectors exist
 - standalone MCP does not generate embeddings itself
+- with the local model profile, the app later calls your configured OpenAI-compatible endpoints for descriptions, summaries, and embeddings
 
 If an external agent creates or updates a node through standalone MCP while the app is closed, the node can exist before its chunks and vectors do. The app-owned pipeline processes that later.
 

docs/README.md

@@ -21,6 +21,8 @@
 | [MCP](./8_mcp.md) | Full standalone MCP install, behavior guide, and memory-file guidance |
 | [Open Source](./9_open-source.md) | Scope, support boundary, contributor reality |
 | [Full Local](./10_full-local.md) | Supported local path vs community patterns |
+| [Local Models](../LOCAL-MODELS.md) | OpenAI-compatible local endpoint profile |
+| [Qdrant](../QDRANT-DEPLOYMENT.md) | Optional vector sidecar for sqlite-vec-hostile environments |
 | [Troubleshooting](./TROUBLESHOOTING.md) | Common issues and fixes |
 
 ## Start Here
@@ -28,7 +30,7 @@
 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.
-3. Read [Full Local](./10_full-local.md) if you want a more local-first or community setup.
+3. Read [Local Models](../LOCAL-MODELS.md) and [Full Local](./10_full-local.md) if you want a more local-first setup.
 
 ## MCP Quick Install