Clarify default database location

.env.example

@@ -34,9 +34,17 @@ OPENAI_API_KEY=
 # VECTOR_BACKEND=qdrant
 # QDRANT_URL=http://localhost:6333
 
-# Database/vector paths are auto-detected for macOS, Windows, and Linux.
-# Override only if you intentionally want a custom location.
+# Database path defaults to the operating system app-data folder:
+#   macOS:   ~/Library/Application Support/RA-H/db/rah.sqlite
+#   Linux:   ~/.local/share/RA-H/db/rah.sqlite
+#   Windows: %APPDATA%/RA-H/db/rah.sqlite
+#
+# Set SQLITE_DB_PATH before setup if you intentionally want a repo-local DB,
+# demo DB, or any other separate location.
 # SQLITE_DB_PATH=/absolute/path/to/rah.sqlite
+
+# sqlite-vec extension path is auto-detected for macOS, Windows, and Linux.
+# Override only if you intentionally want a custom extension location.
 # SQLITE_VEC_EXTENSION_PATH=/absolute/path/to/vec0.<dylib|dll|so>
 
 # App config (no changes needed)

.gitignore

@@ -38,6 +38,7 @@ yarn-error.log*
 next-env.d.ts
 
 # Database
+.ra-h/
 *.db
 *.sqlite
 *.sqlite3

README.md

@@ -277,23 +277,35 @@ Qdrant does not change your model choice. OpenAI vs local Qwen is controlled by
 
 ## Where Your Data Lives
 
+By default, setup creates and seeds the SQLite database in your operating system's app-data folder, not inside the cloned repo:
+
 ```
 ~/Library/Application Support/RA-H/db/rah.sqlite   # macOS
 ~/.local/share/RA-H/db/rah.sqlite                  # Linux
 %APPDATA%/RA-H/db/rah.sqlite                       # Windows
 ```
 
+This default applies to both app profiles:
+- `npm run setup:local -- --profile openai`
+- `npm run setup:local -- --profile qwen-local`
+
 This is a standard SQLite file. You can:
 - Back it up by copying the file
 - Query it directly with `sqlite3` or any SQLite tool
 - Move it between machines
 
-Override the location only when you intentionally want a separate database:
+You can put the database somewhere else by setting `SQLITE_DB_PATH` before setup. Use this when you want a repo-local DB, a demo DB, or any other separate database:
 
 ```bash
 SQLITE_DB_PATH="$HOME/Desktop/ra-h_os-demo-data/rah.sqlite" npm run setup:local -- --profile qwen-local
 ```
 
+To put it directly inside your cloned repo, use a gitignored local folder:
+
+```bash
+SQLITE_DB_PATH="$PWD/.ra-h/db/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

docs/README.md

@@ -91,7 +91,17 @@ 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 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.
+The selected setup profile creates the default database if it does not exist. By default, that database is in the operating system's app-data folder, not inside the cloned repo:
+
+```text
+~/Library/Application Support/RA-H/db/rah.sqlite   # macOS
+~/.local/share/RA-H/db/rah.sqlite                  # Linux
+%APPDATA%/RA-H/db/rah.sqlite                       # Windows
+```
+
+Set `SQLITE_DB_PATH` before setup if you want a repo-local DB, demo DB, or any other separate location. If MCP should use that same non-default database, pass the same path to the MCP installer with `--db`.
+
+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?