Docs: Centralize and document data path management for packaged builds

AGENTS.md

@@ -19,6 +19,7 @@ Heimgeist is a local desktop chat app for Ollama. It uses a React/Vite renderer,
 - `backend/` - FastAPI backend and local processing.
   - `backend/main.py` defines chat, session, model, audio, Ollama, and web search routes.
   - `backend/local_rag.py` defines library, file registration, job, and local context routes.
+  - `backend/paths.py` centralizes backend runtime data paths for SQLite and local RAG libraries.
   - `backend/schemas.py` and `backend/models.py` define API and database data shapes.
   - `backend/rag/` contains corpus, enrichment, embedding, indexing, and retrieval helpers.
   - `backend/database.py` points SQLite at `backend/app.db`.
@@ -46,6 +47,7 @@ There are currently no npm `test` or `lint` scripts in `package.json`.
 - Renderer code should remain platform-neutral where practical. It may call backend HTTP APIs and may call `desktopApi`, but it should not import or call Tauri APIs directly.
 - `src/desktop/desktopApi.js` is the renderer's platform abstraction. Add desktop capabilities there first, then back them with Tauri commands/events.
 - `src-tauri/src/main.rs` owns desktop concerns: windows, menus, dialogs, shell opening, settings persistence, update placeholders, focus events, and Tauri command implementations.
+- `backend/paths.py` owns backend runtime path resolution. Default development paths must remain `backend/app.db` and `backend/libraries`; packaged launchers may pass app-managed paths through internal environment hooks.
 - Backend code owns chat/session persistence, Ollama integration, Whisper transcription, web search enrichment, and RAG library processing.
 - Backend API contracts should stay stable unless intentionally coordinated with renderer changes. If a response/request shape changes in `backend/schemas.py` or route handlers, update the renderer callers in the same change.
 - Keep local RAG job orchestration and generated library state in the backend. Renderer code should use backend endpoints rather than reading library files directly.
@@ -61,6 +63,7 @@ Do not edit or commit generated/runtime data unless the task explicitly requires
 - `dist/` - Vite build output.
 - `__pycache__/`, `*.pyc`, `.DS_Store`, and similar machine-generated files.
 - Local app settings files under the Tauri app config directory or `HEIMGEIST_SETTINGS_FILE`.
+- Packaged-build backend data directories supplied through internal deployment hooks such as `HEIMGEIST_DATA_DIR`, `HEIMGEIST_DB_PATH`, or `HEIMGEIST_LIB_ROOT`.
 - Tauri-generated `src-tauri/target/`, `src-tauri/gen/`, and local `src-tauri/Cargo.lock` if generated by local verification.
 
 Avoid broad file operations that traverse these directories. Use ignore patterns with search tools when inspecting the repo.
@@ -80,6 +83,7 @@ Avoid broad file operations that traverse these directories. Use ignore patterns
 - Preserve `HEIMGEIST_SETTINGS_FILE` as an explicit shared settings override.
 - Keep first-run legacy settings import available when Tauri settings do not already exist.
 - Do not move or rewrite `backend/app.db` or `backend/libraries`; the development backend must keep using the existing backend working directory.
+- Treat `HEIMGEIST_DATA_DIR`, `HEIMGEIST_DB_PATH`, and `HEIMGEIST_LIB_ROOT` as internal app/sidecar deployment hooks only. Do not expose them in the UI or document them as normal user configuration.
 - Production-release work still needs backend sidecar packaging, signed updater/changelog parity, bundle metadata, signing/notarization, and installer behavior.
 - Avoid refactors that mix migration prep with unrelated feature work. Migration work should be explicit and reviewable.
 
@@ -99,6 +103,7 @@ Avoid broad file operations that traverse these directories. Use ignore patterns
 - The Tauri bridge is intentionally narrow. Direct `window.__TAURI__` use outside `src/desktop/desktopApi.js` makes desktop behavior harder to reason about.
 - `src/App.jsx`, `src/chatGeneration.js`, and backend chat routes share assumptions about streaming, regeneration, attachments, source metadata, and session state.
 - `backend/main.py` creates/migrates SQLite tables at import/startup. Schema changes need care because they run against local user data.
+- `backend/paths.py` controls where chat and local RAG data are stored. Preserve development defaults unless the task explicitly concerns packaged app data paths.
 - `backend/local_rag.py` coordinates asynchronous jobs, file registration, generated artifacts, and per-library locks. Avoid changes that can start duplicate jobs or corrupt `backend/libraries/`.
 - RAG builders under `backend/rag/` run heavier file processing and subprocess/threaded work. Test with small inputs before broader runs.
 - Whisper depends on ffmpeg/ffprobe paths supplied by the Node backend runner when available.

README.md

@@ -23,6 +23,12 @@ The `DBs` tab is no longer a placeholder. You can:
 
 When files are added or removed, Heimgeist automatically rebuilds the local RAG pipeline for that database: corpus, enrichment, embeddings, and indexes. In the chat composer, you can select which database the current chat should use. For each chat turn, Heimgeist queries the selected database, turns the top results into a local context block, appends that block to the user prompt, and sends the enriched prompt to Ollama.
 
+## Local Data
+
+Heimgeist stores chat history and local library indexes on the local machine. During development, the backend keeps using `backend/app.db` and `backend/libraries` so existing local data remains available.
+
+Packaged Tauri builds should launch the backend with app-managed data paths so chats and local libraries live under the operating system's normal application data location, such as Application Support on macOS, LocalAppData on Windows, or the XDG data directory on Linux. These paths are managed by the app and are not exposed as normal user settings.
+
 ## Stack
 
 - Frontend: Tauri, React, Vite
@@ -78,6 +84,7 @@ npm run dev
 │   ├── ollama_client.py
 │   ├── models.py
 │   ├── database.py
+│   ├── paths.py
 │   ├── schemas.py
 │   └── requirements.txt
 ├── src-tauri/

docs/tauri-migration.md

@@ -23,6 +23,16 @@ The development backend is still the normal FastAPI backend started from the rep
 - On first Tauri run only, when the Tauri settings file does not exist, Tauri attempts to import the historical Electron settings file from the platform config directory, including `Heimgeist/settings.json`.
 - Existing Tauri settings are never overwritten by imported settings.
 
+## Packaged Backend Data Paths
+
+The backend now centralizes runtime data paths in `backend/paths.py`.
+
+- Development remains unchanged when no internal deployment hooks are set: chat data uses `backend/app.db` and local RAG data uses `backend/libraries`.
+- Packaged Tauri builds should launch the backend with an app-managed data root so the backend stores data under the OS-appropriate app data directory.
+- The intended packaged locations are Application Support on macOS, LocalAppData on Windows, and the XDG data directory or `~/.local/share` equivalent on Linux.
+- `HEIMGEIST_DATA_DIR`, `HEIMGEIST_DB_PATH`, and `HEIMGEIST_LIB_ROOT` are internal app/sidecar plumbing hooks for packaged launchers and developer verification. They are not user-facing settings.
+- This step does not move or migrate existing development data.
+
 ## Desktop Bridge Surface
 
 Renderer code should continue to call only `src/desktop/desktopApi.js` for desktop functions. That bridge owns direct access to the Tauri global and maps the renderer API to Tauri commands/events.
@@ -56,6 +66,7 @@ The only remaining Electron references should be historical migration documentat
 
 - Replace update/changelog placeholders with a signed Tauri update flow or another release strategy.
 - Package the FastAPI backend as a sidecar or equivalent production process.
+- Launch the packaged backend with app-managed data paths from the Tauri shell.
 - Preserve ffmpeg/ffprobe environment handling for packaged audio transcription.
 - Add production backend startup health gating and shutdown behavior.
 - Finalize bundle metadata, icons, signing, notarization, and installer behavior.