Meridiona · mintlify · Jun 2, 2026 · Jun 4, 2026
diff --git a/concepts/categories.mdx b/concepts/categories.mdx
@@ -86,7 +86,7 @@ You can filter sessions by confidence score when querying `meridian.db` directly
 
 ## Categories in the dashboard
 
-The dashboard at **http://localhost:3000** uses categories in three places:
+The dashboard at **http://localhost:3939** uses categories in three places:
 
 - **Day timeline** — each session segment on the timeline bar is colored by its category, giving you an instant visual breakdown of how your day was split across activity types.
 - **Session badges** — every session card shows a color-coded pill badge with the category label and emoji, plus the confidence score when it's below 0.85.

diff --git a/concepts/how-it-works.mdx b/concepts/how-it-works.mdx
@@ -73,7 +73,7 @@ The MCP server provides tools for querying sessions, timelines, stats, active ta
 
 ## The local dashboard
 
-The dashboard at **http://localhost:3000** gives you a visual view of everything Meridian has recorded: a color-coded day timeline, per-category breakdowns, session cards with window titles and OCR excerpts, and an always-visible active session indicator. It runs as a local Next.js process managed by launchd — no cloud, no login.
+The dashboard at **http://localhost:3939** gives you a visual view of everything Meridian has recorded: a color-coded day timeline, per-category breakdowns, session cards with window titles and OCR excerpts, and an always-visible active session indicator. It runs as a local Next.js process managed by launchd — no cloud, no login.
 
 <CardGroup cols={2}>
   <Card title="Sessions" icon="table" href="/concepts/sessions">

diff --git a/concepts/sessions.mdx b/concepts/sessions.mdx
@@ -75,5 +75,5 @@ sqlite3 ~/.meridian/meridian.db \
 ```
 
 <Tip>
-  The Meridian dashboard at **http://localhost:3000** and the MCP server both read from this same database. Any SQL query you run against `~/.meridian/meridian.db` reflects exactly what the dashboard shows.
+  The Meridian dashboard at **http://localhost:3939** and the MCP server both read from this same database. Any SQL query you run against `~/.meridian/meridian.db` reflects exactly what the dashboard shows.
 </Tip>
diff --git a/concepts/task-classification.mdx b/concepts/task-classification.mdx
@@ -83,7 +83,7 @@ Task classification runs entirely on your machine using a persistent MLX inferen
 If you don't need ticket linking — or if you're running on a machine without Apple Silicon — you can disable classification entirely:
 
 ```bash
-# In ~/.meridian/.env
+# In ~/.meridian/app/.env
 CLASSIFICATION_ENABLED=false
 ```
 

diff --git a/configuration.mdx b/configuration.mdx
@@ -4,34 +4,30 @@ sidebarTitle: "Configuration"
 description: "Learn where Meridian's config files live, how to edit them, and what every environment variable does — from polling intervals to PM credentials."
 ---
 
-Meridian is configured entirely through environment variables. There are no config files with special formats or UI settings to hunt down — every option is a key-value pair in a `.env` file. The installer creates these files and populates them during the credential walkthrough, but you can edit them at any time.
+Meridian is configured entirely through environment variables. There are no config files with special formats or UI settings to hunt down — every option is a key-value pair in a single `.env` file. `meridian setup` creates the file and you can edit it at any time.
 
 ## Where configuration lives
 
-Meridian uses two env files, one per process boundary:
+The npm install lays out the runtime under `~/.meridian/`:
 
-| File | Used by |
+| Path | Purpose |
 |---|---|
-| `~/.meridian/.env` | The Rust daemon — core settings and PM credentials |
-| `services/.env` | The Python agents — LLM endpoint and Jira credentials |
+| `~/.meridian/app/.env` | The one backend config — read by the daemon, classifier, and worklog stage. |
+| `~/.meridian/meridian.db` | The session database. |
+| `~/.meridian/logs/` | Per-service logs (daemon, MLX server, screenpipe, UI). |
+| `~/Library/LaunchAgents/com.meridiona.*.plist` | The launchd agents registered by `meridian setup`. |
 
-A third internal env file is managed automatically by the installer and holds the `OPENROUTER_API_KEY` for cloud LLM fallback. In practice you never need to touch it directly — the installer keeps it in sync with the values you provide during setup.
+Contributors building from source share the same on-disk layout, except their config lives at the **repo-root `.env`** instead of `~/.meridian/app/.env` (the source checkout is what `meridian dev` runs against).
 
 ## Editing configuration
 
-To open the daemon config in your `$EDITOR`, run:
+To open the config in your `$EDITOR`, run:
 
 ```bash
 meridian config edit
 ```
 
-This opens `~/.meridian/.env`. To edit the Python agents config, open `services/.env` directly:
-
-```bash
-$EDITOR services/.env
-```
-
-After saving, restart the relevant daemon for the change to take effect:
+This opens `~/.meridian/app/.env` (or the repo-root `.env` for source builds). After saving, restart for the change to take effect:
 
 ```bash
 meridian restart
@@ -91,7 +87,7 @@ The API key is required to enable the Linear connector. `LINEAR_TEAM_IDS` is opt
 
 The smallest configuration that enables activity tracking, session categorisation, and Jira ticket sync is:
 
-```bash title="~/.meridian/.env"
+```bash title="~/.meridian/app/.env"
 # Required for task classification and Jira sync
 JIRA_BASE_URL=https://your-org.atlassian.net
 JIRA_EMAIL=you@your-org.com
@@ -103,24 +99,17 @@ CLASSIFICATION_ENABLED=true
 
 Everything else defaults to safe values and can be added incrementally.
 
-## Re-running credential prompts
+## Editing credentials later
 
-The installer skips any variable that already has a value in the relevant `.env` file. To re-prompt for a specific credential, delete that line from the file and re-run the installer:
+The npm install does not include an interactive credential prompt — edit the file directly:
 
 ```bash
-# 1. Remove the line you want to re-set (e.g. JIRA_API_TOKEN)
 meridian config edit
-
-# 2. Re-run the installer — it will prompt only for missing values
-./install.sh --skip-permissions
+meridian restart
 ```
 
-If you want to bypass the credential prompts entirely and manage the files yourself, pass `--skip-env`:
-
-```bash
-./install.sh --skip-env
-```
+Contributors who built from source can re-run `./install.sh --skip-permissions` to be re-prompted for any variable that isn't already set; `./install.sh --skip-env` bypasses the prompt flow entirely.
 
 <Tip>
-  You can also edit `~/.meridian/.env` directly with any text editor and then run `meridian restart`. The installer's prompt flow is a convenience, not a requirement.
+  You can edit the `.env` with any text editor and then run `meridian restart`. The daemon reads the file once at startup and does not hot-reload changes.
 </Tip>
diff --git a/guides/dashboard.mdx b/guides/dashboard.mdx
@@ -8,12 +8,14 @@ Meridian includes a Next.js dashboard that gives you a live, browser-based view
 
 ## Opening the dashboard
 
-The dashboard starts automatically when you run `meridian start` and listens on port 3000. To open it, navigate to:
+The dashboard starts automatically when you run `meridian start` and listens on port 3939. To open it, navigate to:
 
 ```
-http://localhost:3000
+http://localhost:3939
 ```
 
+Override the port by setting `MERIDIAN_UI_PORT` in `~/.meridian/app/.env`, then `meridian restart`.
+
 Any browser works. You can keep it open as a background tab while you work.
 
 ## Dashboard views
@@ -72,17 +74,13 @@ To tail the dashboard's log output:
 meridian logs ui
 ```
 
-If you've pulled an update to the repository and want to rebuild the dashboard with the latest changes:
+To pull a newer release of the dashboard along with the rest of Meridian:
 
 ```bash
-cd ui && npm run build
+meridian update
 ```
 
-Then restart Meridian to pick up the new build:
-
-```bash
-meridian restart
-```
+`meridian update` runs `npm install -g @meridiona/meridian@latest` under the hood and re-runs `meridian setup`. Source-built contributors rebuild manually with `cd ui && npm run build && meridian restart`.
 
 <Note>
   The dashboard reads directly from `~/.meridian/meridian.db`. It does not make any network requests and does not send your activity data anywhere. All rendering happens locally in your browser.
@@ -91,7 +89,7 @@ meridian restart
 ## Troubleshooting
 
 <AccordionGroup>
-  <Accordion title="http://localhost:3000 returns an error or doesn't load">
+  <Accordion title="http://localhost:3939 returns an error or doesn't load">
     Check that the UI service is running:
 
     ```bash
@@ -113,12 +111,14 @@ meridian restart
   <Accordion title="The active session card shows stale data">
     The daemon writes new data every 60 seconds (configurable via `POLL_INTERVAL_SECS`). If the card hasn't updated in longer than a minute or two, check that the daemon is running with `meridian status` and review the daemon log with `meridian logs`.
   </Accordion>
-  <Accordion title="The dashboard was installed without the UI (--no-ui flag)">
-    If you ran `./install.sh --no-ui`, the dashboard was not built. Build and register it now:
+  <Accordion title="The dashboard was installed without the UI (source builds with --no-ui)">
+    If you built from source with `./install.sh --no-ui`, the dashboard was skipped. Build and register it now:
 
     ```bash
     cd ui && npm run build
     meridian restart
     ```
+
+    The npm distribution always includes a prebuilt dashboard, so this only applies to source-built contributors.
   </Accordion>
 </AccordionGroup>
diff --git a/guides/github-linear.mdx b/guides/github-linear.mdx
@@ -44,10 +44,10 @@ Meridian supports two additional issue trackers alongside Jira: GitHub Issues an
     meridian config edit
     ```
 
-    Add the GitHub block to `~/.meridian/.env`:
+    Add the GitHub block to `~/.meridian/app/.env`:
 
     ```bash
-    # ~/.meridian/.env
+    # ~/.meridian/app/.env
 
     GITHUB_TOKEN=ghp_your_personal_access_token
     GITHUB_ORG=your-org-name
@@ -140,10 +140,10 @@ Meridian supports two additional issue trackers alongside Jira: GitHub Issues an
     meridian config edit
     ```
 
-    Add the Linear block to `~/.meridian/.env`:
+    Add the Linear block to `~/.meridian/app/.env`:
 
     ```bash
-    # ~/.meridian/.env
+    # ~/.meridian/app/.env
 
     LINEAR_API_KEY=lin_api_your_key_here
 

diff --git a/guides/jira.mdx b/guides/jira.mdx
@@ -37,10 +37,10 @@ Set the following environment variables. The cleanest way is to open the Meridia
 meridian config edit
 ```
 
-This opens `~/.meridian/.env` in your `$EDITOR`. Add or update the Jira block:
+This opens `~/.meridian/app/.env` in your `$EDITOR`. Add or update the Jira block:
 
 ```bash
-# ~/.meridian/.env
+# ~/.meridian/app/.env
 
 JIRA_BASE_URL=https://your-org.atlassian.net
 JIRA_EMAIL=you@your-org.com
@@ -54,20 +54,14 @@ JIRA_API_TOKEN=your-api-token-here
   Meridian only reads your Jira tickets for classification. It never creates, modifies, closes, or deletes tickets on your behalf.
 </Note>
 
-Alternatively, re-run the installer's credential walkthrough to be prompted interactively:
-
-```bash
-./install.sh --skip-permissions
-```
-
 ## Apply and verify
 
 <Steps>
   <Step title="Restart the daemon">
     ```bash
     meridian restart
     ```
-    The daemon re-reads `~/.meridian/.env` on startup and refreshes the `pm_tasks` cache from Jira within the first poll cycle.
+    The daemon re-reads `~/.meridian/app/.env` on startup and refreshes the `pm_tasks` cache from Jira within the first poll cycle.
   </Step>
   <Step title="Run a health check">
     ```bash
@@ -117,7 +111,7 @@ python3 scripts/refresh_pm_tasks.py \
   --db ~/.meridian/meridian.db
 ```
 
-The script reads your credentials from `~/.meridian/.env` automatically — no extra configuration needed.
+The script reads your credentials from `~/.meridian/app/.env` automatically — no extra configuration needed. (The script ships in the source repo; it's a contributor utility, not part of the npm distribution.)
 
 ## Troubleshooting
 

diff --git a/guides/mcp-setup.mdx b/guides/mcp-setup.mdx
@@ -8,15 +8,17 @@ Meridian ships a TypeScript MCP (Model Context Protocol) server that gives any c
 
 The MCP server opens `~/.meridian/meridian.db` in read-only mode on each tool call, so the AI always sees up-to-date session data without any manual syncing.
 
-## How the MCP server is built
+## Where the MCP server lives
 
-`./install.sh` builds the MCP server automatically into `packages/meridian-mcp/dist/index.js`. If you need to rebuild it manually — for example after updating the repository — run:
+The npm install (`npm install -g @meridiona/meridian` + `meridian setup`) places the prebuilt MCP server inside the app bundle at `~/.meridian/app/packages/meridian-mcp/dist/index.js` — point your MCP client at that path.
+
+Source-built contributors run `./install.sh`, which builds the MCP server into `packages/meridian-mcp/dist/index.js` in the checkout. To rebuild manually after editing the source:
 
 ```bash
 cd packages/meridian-mcp && npm run build
 ```
 
-The server uses [sql.js](https://github.com/sql-js/sql.js) (pure WebAssembly SQLite) so it works with any Node.js version without native module compilation.
+The server uses [sql.js](https://github.com/sql-js/sql.js) (pure WebAssembly SQLite) so it works with any modern Node.js version without native module compilation.
 
 ## Add Meridian to your AI tool
 
@@ -28,14 +30,14 @@ The server uses [sql.js](https://github.com/sql-js/sql.js) (pure WebAssembly SQL
     ~/Library/Application Support/Claude/claude_desktop_config.json
     ```
 
-    Add the `meridian` entry inside `mcpServers`. Replace `/path/to/meridian` with the absolute path to your cloned repository:
+    Add the `meridian` entry inside `mcpServers`. If you installed via npm, point at the bundle inside `~/.meridian/app`; if you built from source, use the path to your repo checkout instead.
 
     ```json
     {
       "mcpServers": {
         "meridian": {
           "command": "node",
-          "args": ["/path/to/meridian/packages/meridian-mcp/dist/index.js"]
+          "args": ["/Users/you/.meridian/app/packages/meridian-mcp/dist/index.js"]
         }
       }
     }
@@ -44,7 +46,7 @@ The server uses [sql.js](https://github.com/sql-js/sql.js) (pure WebAssembly SQL
     Save the file, then quit and relaunch Claude Desktop. The Meridian tools will appear automatically in the tool picker.
 
     <Tip>
-      You can find your repo path by running `pwd` inside the `meridian` directory.
+      Use an absolute path — `~` is not expanded by all MCP hosts. Replace `/Users/you` with your real home directory (`echo $HOME`).
     </Tip>
   </Tab>
 
@@ -60,7 +62,7 @@ The server uses [sql.js](https://github.com/sql-js/sql.js) (pure WebAssembly SQL
       "mcpServers": {
         "meridian": {
           "command": "node",
-          "args": ["/path/to/meridian/packages/meridian-mcp/dist/index.js"]
+          "args": ["/Users/you/.meridian/app/packages/meridian-mcp/dist/index.js"]
         }
       }
     }
@@ -69,18 +71,18 @@ The server uses [sql.js](https://github.com/sql-js/sql.js) (pure WebAssembly SQL
     **Option B — Claude Code CLI (global):**
 
     ```bash
-    claude mcp add meridian node /path/to/meridian/packages/meridian-mcp/dist/index.js
+    claude mcp add meridian node ~/.meridian/app/packages/meridian-mcp/dist/index.js
     ```
 
-    Replace `/path/to/meridian` with the absolute path to your cloned repository. Run `claude mcp list` to confirm Meridian appears in the registered servers.
+    Use an absolute path with your real home directory. Run `claude mcp list` to confirm Meridian appears in the registered servers.
   </Tab>
 
   <Tab title="Cursor">
     Open Cursor's settings and navigate to **Features → MCP Servers**. Click **Add new MCP server** and fill in:
 
     - **Name:** `meridian`
     - **Command:** `node`
-    - **Args:** `/path/to/meridian/packages/meridian-mcp/dist/index.js`
+    - **Args:** `/Users/you/.meridian/app/packages/meridian-mcp/dist/index.js`
 
     Alternatively, edit your Cursor MCP config file directly (usually `~/.cursor/mcp.json`):
 
@@ -89,7 +91,7 @@ The server uses [sql.js](https://github.com/sql-js/sql.js) (pure WebAssembly SQL
       "mcpServers": {
         "meridian": {
           "command": "node",
-          "args": ["/path/to/meridian/packages/meridian-mcp/dist/index.js"]
+          "args": ["/Users/you/.meridian/app/packages/meridian-mcp/dist/index.js"]
         }
       }
     }
@@ -108,7 +110,7 @@ By default the MCP server reads `~/.meridian/meridian.db`. To point it at a diff
   "mcpServers": {
     "meridian": {
       "command": "node",
-      "args": ["/path/to/meridian/packages/meridian-mcp/dist/index.js"],
+      "args": ["/Users/you/.meridian/app/packages/meridian-mcp/dist/index.js"],
       "env": {
         "MERIDIAN_DB": "/custom/path/to/meridian.db"
       }
@@ -168,7 +170,7 @@ For the complete input schema and parameter reference for each tool, see [MCP To
   <Accordion title="The AI says it can't find Meridian or the database">
     Check two things:
 
-    1. **The daemon is running.** Run `meridian status` — all four services (screenpipe, daemon, jira-updater, ui) should show as running.
+    1. **The daemon is running.** Run `meridian status` — all four services (screenpipe, daemon, mlx-server, ui) should show as running.
     2. **The database exists.** Run `ls -lh ~/.meridian/meridian.db`. If the file is missing, the daemon hasn't written any sessions yet. Wait for the first 60-second poll cycle to complete.
 
     If the path is correct and the daemon is running, confirm the `args` path in your MCP config points to the actual `dist/index.js` file with no typos.
@@ -180,6 +182,6 @@ For the complete input schema and parameter reference for each tool, see [MCP To
     The MCP server uses sql.js (pure WebAssembly) instead of native SQLite bindings, so it is compatible with any modern Node.js version. If you see unexpected errors, rebuild the server with `cd packages/meridian-mcp && npm run build` and ensure you're on Node 18 or later.
   </Accordion>
   <Accordion title="Task-linked tools return no results">
-    Tools like `get-task-sessions`, `get-task-breakdown`, and `get-active-task` require the AI classifier to have linked sessions to tickets. Confirm that `CLASSIFICATION_ENABLED=true` in `~/.meridian/.env` and that at least one Jira, GitHub, or Linear integration is configured. Check `meridian doctor` for the classifier status.
+    Tools like `get-task-sessions`, `get-task-breakdown`, and `get-active-task` require the AI classifier to have linked sessions to tickets. Confirm that `CLASSIFICATION_ENABLED=true` in `~/.meridian/app/.env` and that at least one Jira, GitHub, or Linear integration is configured. Check `meridian doctor` for the classifier status.
   </Accordion>
 </AccordionGroup>
-Original file line number
+Diff line change
@@ Expand Up / @@ -75,5 +75,5 @@ sqlite3 ~/.meridian/meridian.db \ @@
     ```
     <Tip>
-      The Meridian dashboard at **http://localhost:3000** and the MCP server both read from this same database. Any SQL query you run against `~/.meridian/meridian.db` reflects exactly what the dashboard shows.
+      The Meridian dashboard at **http://localhost:3939** and the MCP server both read from this same database. Any SQL query you run against `~/.meridian/meridian.db` reflects exactly what the dashboard shows.
     </Tip>