docs: add menu bar tray guide and stable screenpipe path

docs.json

@@ -43,6 +43,7 @@
               "guides/github-linear",
               "guides/mcp-setup",
               "guides/dashboard",
+              "guides/menu-bar",
               "guides/querying-data"
             ]
           },

guides/dashboard.mdx

@@ -16,6 +16,10 @@ http://localhost:3000
 
 Any browser works. You can keep it open as a background tab while you work.
 
+<Tip>
+  Prefer not to keep the dashboard open? Meridian also ships a macOS [menu bar tray app](/guides/menu-bar) that shows daemon health and your top app for the day directly from the system tray.
+</Tip>
+
 ## Dashboard views
 
 The dashboard has three main views accessible from the navigation bar.

guides/menu-bar.mdx

@@ -0,0 +1,102 @@
+---
+title: "Use the Meridian Menu Bar Tray App"
+sidebarTitle: "Menu bar"
+description: "Check daemon health, see your top app for the day, and trigger a worklog draft from the macOS menu bar — without opening the dashboard."
+---
+
+Meridian ships with a lightweight macOS menu bar tray app that lives in your system tray and gives you an at-a-glance view of whether the background daemons are healthy and what you've been working on today. It's designed for the times you don't want to context-switch to the full dashboard — a quick glance at the menu bar is enough to confirm Meridian is recording and to spot when something has stopped working.
+
+<Note>
+The tray app is **macOS only**. The Linux and Windows builds of Meridian do not include it.
+</Note>
+
+## What the tray shows
+
+The tray icon reflects daemon health in real time. Open the popover to see:
+
+- **Daemon status** — whether the Rust ETL daemon is running, derived from the `daemon_running` field on `/api/health` (a launchd probe with a 3-second timeout).
+- **Accessibility helper status** — whether the a11y helper is currently trusted by macOS. An untrusted helper means window titles aren't being captured.
+- **Today's top app** — the app you've spent the most focused time in so far today, with elapsed time.
+- **Pending worklog drafts** — a count of drafts waiting on your review.
+
+From the popover you can also:
+
+- Open the full dashboard at `http://localhost:3000`.
+- Trigger a worklog draft for today without leaving the menu bar.
+- Pause or resume the daemon.
+
+The tray polls `/api/health` and the activity endpoints every 60 seconds. When the daemon goes down — or comes back online — you get a macOS notification so you don't silently lose recording time.
+
+## Installation and auto-start
+
+The tray app is installed automatically by `./install.sh` and `meridian update`. It's registered as a LaunchAgent (`com.meridiona.tray`) so it starts on login alongside the rest of the stack — there's no separate command to run.
+
+You can verify it's loaded with:
+
+```bash
+launchctl list | grep com.meridiona.tray
+```
+
+If you want to start, stop, or restart the tray independently of the other daemons:
+
+```bash
+# Stop the tray
+launchctl stop com.meridiona.tray
+
+# Start it again
+launchctl start com.meridiona.tray
+```
+
+Logs are written to `~/.meridian/logs/tray.log` and `~/.meridian/logs/tray-error.log`.
+
+## When to use it
+
+Reach for the tray when you want to:
+
+- Confirm Meridian is still recording without breaking flow to open a browser.
+- Get notified the moment the daemon stops (for example after a system update or permission revocation).
+- Kick off a worklog draft quickly at the end of the day or after a focused session.
+
+For deeper analysis — timelines, per-session detail, the apps view — open the dashboard. The tray is intentionally minimal.
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="The tray icon doesn't appear in the menu bar">
+    Check that the LaunchAgent is registered and running:
+
+    ```bash
+    launchctl list | grep com.meridiona.tray
+    ```
+
+    If it's missing, re-run the installer or reinstall just the tray daemon:
+
+    ```bash
+    bash scripts/install-tray-daemon.sh
+    ```
+
+    Then tail the log to confirm it started:
+
+    ```bash
+    tail -f ~/.meridian/logs/tray.log
+    ```
+  </Accordion>
+  <Accordion title="The popover shows 'daemon stopped' but meridian status looks fine">
+    The tray reads `daemon_running` from `/api/health`, which probes launchd for `com.meridiona.daemon`. If the UI service is down or unreachable on `http://localhost:3000`, the tray can't fetch health and falls back to a stopped state. Confirm the UI is up:
+
+    ```bash
+    meridian status
+    curl -s http://localhost:3000/api/health
+    ```
+
+    Restart the stack with `meridian restart` if the UI service isn't running.
+  </Accordion>
+  <Accordion title="Health status isn't refreshing">
+    The tray polls every 60 seconds. If the popover shows stale numbers for longer than that, check the tray log for errors and confirm the dashboard is reachable:
+
+    ```bash
+    tail -f ~/.meridian/logs/tray.log
+    curl -s http://localhost:3000/api/health | jq
+    ```
+  </Accordion>
+</AccordionGroup>

quickstart.mdx

@@ -45,9 +45,21 @@ This guide walks you through getting Meridian running on your machine for the fi
     - **Accessibility** — to read window titles and accessibility tree events
     - **Microphone** — to transcribe audio (optional but recommended for meeting context)
 
+    The screenpipe binary lives at a stable, user-visible path so the grants survive Node upgrades and the System Settings file picker can navigate to it without traversing hidden directories:
+
+    ```
+    ~/.meridian/bin/screenpipe
+    ```
+
+    `meridian permissions` prints this path for you. To grant Screen Recording or Accessibility, open the relevant System Settings pane, click **+**, press **⌘⇧G**, paste the path above, click **Open**, and toggle the entry on.
+
     <Note>
-      For Screen Recording and Accessibility, click the **+** button in the System Settings pane, navigate to the screenpipe binary, and toggle it on. The Microphone pane works differently — screenpipe will appear there automatically after it first requests mic access. If it isn't listed yet, grant Screen Recording first, then check back.
+      The Microphone pane works differently — screenpipe appears there automatically after it first requests mic access. If it isn't listed yet, grant Screen Recording first, then check back.
     </Note>
+
+    <Tip>
+      **Upgrading from an older install?** Updates preserve whatever screenpipe path your launchd plist already points at, so your existing TCC grant for Screen Recording and Accessibility stays valid. Fresh installs land at `~/.meridian/bin/screenpipe`.
+    </Tip>
   </Step>
   <Step title="Configure your credentials">
     Immediately after the build, the installer prompts you for credentials grouped by service. Press **Enter** on any prompt to skip that variable — you can always add it later.

reference/cli.mdx

@@ -173,14 +173,24 @@ EDITOR=code meridian config edit
 meridian permissions
 ```
 
-Walks you interactively through the three macOS privacy panes that screenpipe requires:
+Walks you interactively through the three macOS privacy panes that screenpipe requires. The command first prints the stable binary path you need to grant access to:
 
-1. **Screen Recording** — opens the System Settings pane; click `+`, navigate to the screenpipe binary, add it, and toggle it on.
+```
+~/.meridian/bin/screenpipe
+```
+
+Then it opens each pane in sequence:
+
+1. **Screen Recording** — opens the System Settings pane; click `+`, press `⌘⇧G`, paste the path above, click **Open**, and toggle the entry on.
 2. **Accessibility** — same steps.
 3. **Microphone** — screenpipe appears here only after it first requests mic access. Grant Screen Recording first if screenpipe is not listed yet.
 
 After each step the script waits for you to press Enter. Run `meridian restart` afterwards so screenpipe picks up the newly granted permissions.
 
+<Note>
+Updates preserve whatever screenpipe path your existing launchd plist points at so the macOS TCC grant stays valid. The `~/.meridian/bin/screenpipe` path is used for fresh installs and when no plist exists yet.
+</Note>
+
 <Warning>
 Without Screen Recording permission, screenpipe cannot capture frames and Meridian will have no data to process.
 </Warning>

reference/troubleshooting.mdx

@@ -277,7 +277,13 @@ Run the guided permissions walkthrough:
 meridian permissions
 ```
 
-The command opens the Screen Recording, Accessibility, and Microphone System Settings panes in sequence and waits for you to confirm each one. After granting access, restart the stack:
+The command prints the stable binary path you need to grant access to and opens the Screen Recording, Accessibility, and Microphone System Settings panes in sequence. Grant access to:
+
+```
+~/.meridian/bin/screenpipe
+```
+
+In each pane, click **+**, press **⌘⇧G**, paste that path, click **Open**, and toggle the entry on. After granting access, restart the stack:
 
 ```bash
 meridian restart
@@ -287,6 +293,10 @@ meridian restart
 You must restart screenpipe after granting Screen Recording permission. The permission change does not take effect for a running process.
 </Warning>
 
+<Note>
+Updates never rewrite the screenpipe path in your launchd plist — if you previously granted access against an older path (for example an `nvm`-versioned npm path), the existing TCC grant is preserved. Only fresh installs land at `~/.meridian/bin/screenpipe`.
+</Note>
+
 </Accordion>
 
 <Accordion title="No audio transcription in sessions">