docs: architecture map (initial 5-slice generation, 105 pages)

Five-slice navigable map of the entire codebase under
docs/architecture-map/. Each slice is a self-contained
breadcrumbed sub-tree:

  01-frontend (16)              Svelte/SvelteKit UI
  02-tauri-runtime (26)         src-tauri commands + lifecycle
  03-audio-transcription (16)   audio + transcription crates
  04-llm-formatting-mcp (19)    llm, ai-formatting, mcp, cloud
  05-core-storage-hotkey-build  core, storage, hotkey, workspace,
                          (26) CI, dev glue

Plus master README.md and data-flow-end-to-end.md tracing
audio bytes from microphone to FTS5 search to MCP read.

Generated by 5 parallel subagents on 2026/05/09 against
HEAD 3c47000. Each page has YAML frontmatter, file:line code
refs, sibling cross-links, plain-English summaries.

Aggregated debt surfaced (full lists in master README):
RB-08 macOS power assertion, schema head drift v14 vs v15,
VAD blocked on ort version conflict, streaming primitives
not wired into live.rs, no prompt versioning, MCP has no
auth, cloud-providers in-memory keystore, SettingsPage
2 484 LOC, commands/live.rs 1 737 LOC, dual theme system,
brand rename to Lumenote pending across the codebase.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/architecture-map/05-core-storage-hotkey-build/core-paths.md

@@ -0,0 +1,86 @@
+---
+name: Core app paths
+type: architecture-map-page
+slice: 05-core-storage-hotkey-build
+last_verified: 2026/05/09
+---
+
+# Core app paths
+
+> **Where you are:** [Architecture map](../README.md) → [Core, Storage, Hotkey, Build](README.md) → Core app paths
+
+**Plain English summary.** Where Magnotia stores its files on disk. One root, derived from the OS conventions (LOCALAPPDATA on Windows, `~/Library/Application Support/Magnotia` on macOS, `$XDG_DATA_HOME/magnotia` on Linux), and named accessor methods for each subdirectory. Every other crate that needs to know "where does the database live?" reaches for `magnotia_core::paths::AppPaths::current()`.
+
+## At a glance
+
+- File: `crates/core/src/paths.rs` (125 LOC).
+- External deps: standard library only.
+- Public surface: `AppPaths` (struct), `app_paths`, `app_data_dir`.
+- Consumers: `magnotia-storage::file_storage` (re-exports the path helpers), the Tauri startup code (slice 2), the model manager (slices 3 + 4), the diagnostic-report bundler (slice 2).
+
+## What's in here
+
+### `AppPaths` — `crates/core/src/paths.rs:6`
+
+```rust
+pub struct AppPaths { app_data_dir: PathBuf }
+
+impl AppPaths {
+    pub fn current() -> Self;                         // resolves at construction
+    pub fn app_data_dir(&self) -> PathBuf;
+    pub fn database_path(&self) -> PathBuf;           // <root>/magnotia.db
+    pub fn recordings_dir(&self) -> PathBuf;          // <root>/recordings
+    pub fn crashes_dir(&self) -> PathBuf;             // <root>/crashes
+    pub fn logs_dir(&self) -> PathBuf;                // <root>/logs
+    pub fn diagnostic_reports_dir(&self) -> PathBuf;  // <root>/diagnostic-reports
+    pub fn models_dir(&self) -> PathBuf;              // <root>/models
+    pub fn speech_model_dir(&self, id: &ModelId) -> PathBuf;  // <root>/models/<id>
+    pub fn llm_models_dir(&self) -> PathBuf;          // <root>/models/llm
+    pub fn migration_sentinel(&self, name: &str) -> PathBuf;  // <root>/.<name>.sentinel
+}
+
+pub fn app_paths() -> AppPaths;
+pub fn app_data_dir() -> PathBuf;
+```
+
+### Root resolution — `crates/core/src/paths.rs:66`
+
+The `resolve_app_data_dir` function picks the root by `cfg(target_os = ...)`:
+
+| OS | Root |
+|---|---|
+| Windows | `%LOCALAPPDATA%/magnotia` |
+| macOS | `$HOME/Library/Application Support/Magnotia` |
+| Linux | `$HOME/.magnotia` if it already exists (legacy), else `$XDG_DATA_HOME/magnotia` if set, else `$HOME/.local/share/magnotia` |
+| other | `$HOME/.magnotia` |
+
+The Linux legacy-path branch keeps existing users on `~/.magnotia` (early dogfooding default) without forcing a migration when the canonical XDG location is preferred.
+
+### Sentinel files — `crates/core/src/paths.rs:53`
+
+`migration_sentinel(name) -> <root>/.<name>.sentinel`. Used for one-shot data migrations outside the SQLite schema (for example, a one-off file-system reorganisation). The pattern is: write the sentinel after the migration runs successfully; check for the sentinel on next startup; skip the migration if the sentinel exists.
+
+## Data flow / contract
+
+- All paths are derived from a single root. Changing `resolve_app_data_dir` once moves every downstream file. Tested at `paths.rs:111`.
+- Path resolution is pure: only reads env vars (`HOME`, `LOCALAPPDATA`, `XDG_DATA_HOME`) plus `Path::exists` for the Linux legacy probe.
+- `AppPaths::current()` does not create directories. Callers that need a directory to exist call `std::fs::create_dir_all` at write time. The storage `init` function does this for the database parent (`crates/storage/src/database.rs:10`).
+
+## Tests
+
+`crates/core/src/paths.rs:104-125`:
+
+- `derives_all_paths_from_one_base` — verifies that `database_path`, `speech_model_dir(<id>)`, and `llm_models_dir` are all rooted at the same `app_data_dir`.
+
+## Watch-outs
+
+- **`std::env::var(...).unwrap_or_else(|_| "/tmp".to_string())` is the fallback for missing `HOME`.** Should never trigger in practice; defensive.
+- **`AppPaths::current()` reads env vars at every call.** Cheap, but repeated calls are wasteful. Slice 2 caches a `OnceLock<AppPaths>` so the value is resolved once at startup.
+- **No Windows fallback for missing `LOCALAPPDATA`.** Falls through to `.` (current working directory). On a misconfigured Windows host this could write the database next to the binary. Not great; the impact is limited to first-run scenarios where the env is broken.
+- **Sentinel files are hidden on Unix (`.<name>.sentinel`) but visible on Windows.** Acceptable; sentinels live alongside `magnotia.db` so the user sees both.
+
+## See also
+
+- [Storage file paths](storage-file-paths.md) — re-exports.
+- [Model registry](core-model-registry.md) — model IDs feed into `speech_model_dir`.
+- [Slice 2 Tauri startup](../02-tauri-runtime/README.md) — caller of `AppPaths::current()` at boot.