docs: clarify runtime diagnostics and logs

Author: Saga4

apps/desktop/src/App.tsx

@@ -5895,9 +5895,11 @@ function SettingsView({
 
   function copyDiagnostics() {
     const summary = [
+      `Health: ${healthLabel(snapshot.health.state)}`,
       `Locality process: ${daemonStopped ? "Stopped" : "Running"}`,
       snapshot.mount.provider ? `Provider: ${providerStatusLabel(snapshot.mount.provider)}` : null,
       "State folder: ~/.loc",
+      "Logs folder: ~/.loc/logs",
       `Projection: ${snapshot.mount.projection}`,
       `Connection: ${snapshot.connection.status}`,
       `Mount: ${snapshot.mount.status}`,
@@ -6198,6 +6200,7 @@ function SettingsView({
                   <SettingRow title="Provider" value={providerStatusLabel(snapshot.mount.provider)} />
                 )}
                 <SettingRow title="State folder" value="~/.loc" />
+                <SettingRow title="Logs folder" value="~/.loc/logs" />
                 <SettingRow title="Projection" value={snapshot.mount.projection} />
                 <div className="button-row">
                   <SecondaryButton compact onClick={copyDiagnostics}>

docs/daemon.md

@@ -196,6 +196,36 @@ Timed-out `push` requests do not fall back because the daemon may already own an
 in-flight remote mutation. Stop or recover the daemon before retrying the push.
 Set `LOCALITY_DAEMON_DISABLE=1` to force direct execution without the fallback warning.
 
+### Development Schema Skew
+
+The SQLite state under `~/.loc` is durable user state. Do not delete it as the
+first response to a daemon startup failure. In development, a common failure is
+version skew between a freshly rebuilt desktop app and stale debug sidecars under
+`target/debug/`. A newer desktop can migrate `~/.loc/state.sqlite3`; an older
+`target/debug/localityd` can then fail with an unsupported schema or component
+version.
+
+The dev sidecar prep path builds fresh `loc` and `localityd` binaries before it
+uses `loc daemon stop`, then terminates any remaining `localityd` process. This
+keeps the stop/restart path from relying on an old CLI that may no longer be able
+to open the upgraded state database.
+
+Use these checks before assuming state corruption:
+
+```bash
+./target/debug/localityd --build-info
+./target/debug/loc daemon status
+tail -50 ~/.loc/logs/localityd.err.log
+tail -50 ~/.loc/logs/desktop.log
+```
+
+Recovery should rebuild the debug sidecars and relaunch the desktop app:
+
+```bash
+make prepare-desktop-dev-sidecars
+make dev-tauri
+```
+
 ## Runtime Loop
 
 `DaemonRuntime` is the foreground daemon's control plane. It owns the scheduler

docs/desktop-app.md

@@ -142,6 +142,35 @@ write localityd logs in the same folder. The UI should point support and power u
 to that one directory instead of asking them to inspect terminal output,
 launchd, and helper logs separately.
 
+Desktop health labels map to separate runtime layers:
+
+- `Stopped` means the `localityd` daemon is not ready. Background sync, hydration,
+  and Live Mode are paused until the daemon starts again.
+- `Runtime Needs Repair` means the platform projection is stopped, unregistered,
+  or otherwise unavailable. On macOS this is usually File Provider; on Windows it
+  is Cloud Files; on Linux it is the FUSE projection.
+- `Reconnect Needed` means a connector credential or workspace connection needs
+  repair before sync can continue.
+- `Needs Review` means Locality is running, but one or more files require human
+  review before push or automatic sync.
+
+The Settings diagnostics surface should include both `~/.loc` and
+`~/.loc/logs`. `desktop.log`, `localityd.log`, `localityd.err.log`, and projection
+helper logs belong in that one logs directory so support does not have to collect
+terminal output, LaunchAgent output, and helper output separately.
+
+In development, schema skew usually means the desktop process and the
+`localityd` sidecar were built at different times. `make dev-tauri` runs
+`prepare-dev-sidecars`, which must build fresh `loc` and `localityd` binaries
+before restarting the daemon. Direct background launches, LaunchAgent starts, and
+`LOCALITY_DESKTOP_SKIP_DEV_SIDECARS=1` bypass that protection, so recovery should
+be a sidecar rebuild, not deletion of `~/.loc/state.sqlite3`:
+
+```bash
+make prepare-desktop-dev-sidecars
+make dev-tauri
+```
+
 ### 4. Create Workspace Mount
 
 The desktop product target is a workspace-level Notion mount using the access

docs/desktop-ui-screens.md

@@ -837,6 +837,7 @@ Diagnostics
 
 Locality process        Running
 State folder       ~/.loc
+Logs folder        ~/.loc/logs
 Mounts watched     1
 Projection         macOS File Provider
 
@@ -890,7 +891,7 @@ The UI needs desktop-facing data shaped around product concepts:
 
 ```text
 app_health
-  state: ready | preparing | needs_review | reconnect_needed | stopped
+  state: ready | preparing | needs_review | reconnect_needed | stopped | runtime_stopped
   attention_count
 
 connection