diff --git a/concepts/task-classification.mdx b/concepts/task-classification.mdx index b60c830..6672647 100644 --- 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 /.env CLASSIFICATION_ENABLED=false ``` diff --git a/configuration.mdx b/configuration.mdx index 9a81ab1..575775e 100644 --- a/configuration.mdx +++ b/configuration.mdx @@ -8,30 +8,23 @@ Meridian is configured entirely through environment variables. There are no conf ## Where configuration lives -Meridian uses two env files, one per process boundary: +Meridian uses a single env file at the repository root, shared by the Rust daemon and the Python agents: | File | Used by | |---|---| -| `~/.meridian/.env` | The Rust daemon — core settings and PM credentials | -| `services/.env` | The Python agents — LLM endpoint and Jira credentials | +| `/.env` | The Rust daemon **and** the Python agents — every variable below | -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. +`install.sh` creates this file from `.env.example` on first run and writes any values you supply during the credential walkthrough back to the same file. Nothing is read from outside the repository. ## 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 the repo-root `.env`. After saving, restart Meridian for the change to take effect: ```bash meridian restart @@ -91,7 +84,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="/.env" # Required for task classification and Jira sync JIRA_BASE_URL=https://your-org.atlassian.net JIRA_EMAIL=you@your-org.com @@ -105,7 +98,7 @@ Everything else defaults to safe values and can be added incrementally. ## Re-running credential prompts -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 installer skips any variable that already has a value in the repo-root `.env`. To re-prompt for a specific credential, delete that line from the file and re-run the installer: ```bash # 1. Remove the line you want to re-set (e.g. JIRA_API_TOKEN) @@ -122,5 +115,5 @@ If you want to bypass the credential prompts entirely and manage the files yours ``` - 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 also edit the repo-root `.env` directly with any text editor and then run `meridian restart`. The installer's prompt flow is a convenience, not a requirement. diff --git a/guides/github-linear.mdx b/guides/github-linear.mdx index f93d1c6..cb4f104 100644 --- 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 the repo-root `.env`: ```bash - # ~/.meridian/.env + # /.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 the repo-root `.env`: ```bash - # ~/.meridian/.env + # /.env LINEAR_API_KEY=lin_api_your_key_here diff --git a/guides/jira.mdx b/guides/jira.mdx index 8b82fb1..ff15d24 100644 --- 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 the repo-root `.env` in your `$EDITOR`. Add or update the Jira block: ```bash -# ~/.meridian/.env +# /.env JIRA_BASE_URL=https://your-org.atlassian.net JIRA_EMAIL=you@your-org.com @@ -67,7 +67,7 @@ Alternatively, re-run the installer's credential walkthrough to be prompted inte ```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 the repo-root `.env` on startup and refreshes the `pm_tasks` cache from Jira within the first poll cycle. ```bash @@ -117,7 +117,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 the repo-root `.env` automatically — no extra configuration needed. ## Troubleshooting diff --git a/guides/mcp-setup.mdx b/guides/mcp-setup.mdx index 1dd5b13..bdf01e5 100644 --- a/guides/mcp-setup.mdx +++ b/guides/mcp-setup.mdx @@ -180,6 +180,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. - 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 the repo-root `.env` and that at least one Jira, GitHub, or Linear integration is configured. Check `meridian doctor` for the classifier status. diff --git a/quickstart.mdx b/quickstart.mdx index 01272c7..ff86d55 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -65,7 +65,7 @@ This guide walks you through getting Meridian running on your machine for the fi meridian config edit ``` - This opens `~/.meridian/.env` in your `$EDITOR`. See the [Configuration](/configuration) page for the full variable reference. + This opens the repo-root `.env` in your `$EDITOR`. See the [Configuration](/configuration) page for the full variable reference. Bring all daemons up with a single command: @@ -83,7 +83,7 @@ This guide walks you through getting Meridian running on your machine for the fi You should see all services — `com.meridiona.screenpipe`, `com.meridiona.daemon`, `com.meridiona.jira-updater`, `com.meridiona.ui`, `com.meridiona.mlx-server`, and `com.meridiona.coding-agent-indexer` — reported as running with their process IDs. - **MLX inference server for task classification.** If you installed with `--mlx`, Meridian uses a persistent MLX inference server (Qwen3.5-9B, running on-device via Metal) for session-to-ticket classification. On first start, the model downloads to your local cache (~6.6 GB) — this can take a few minutes depending on your connection speed. Subsequent starts load from cache in around 5 seconds. Watch the server come up with `meridian logs mlx-server`. If you haven't set up the MLX server, set `CLASSIFICATION_ENABLED=false` in `~/.meridian/.env` to run in activity-tracking mode without ticket classification. + **MLX inference server for task classification.** If you installed with `--mlx`, Meridian uses a persistent MLX inference server (Qwen3.5-9B, running on-device via Metal) for session-to-ticket classification. On first start, the model downloads to your local cache (~6.6 GB) — this can take a few minutes depending on your connection speed. Subsequent starts load from cache in around 5 seconds. Watch the server come up with `meridian logs mlx-server`. If you haven't set up the MLX server, set `CLASSIFICATION_ENABLED=false` in the repo-root `.env` to run in activity-tracking mode without ticket classification. @@ -133,7 +133,7 @@ meridian restart ## Troubleshooting - Run `meridian doctor` to identify the specific failure. Common causes are a missing `~/.meridian/.env` file (run `./install.sh` to create it), or a missing screenpipe database (start screenpipe first, then run `meridian start`). + Run `meridian doctor` to identify the specific failure. Common causes are a missing repo-root `.env` file (run `./install.sh` to create it from `.env.example`), or a missing screenpipe database (start screenpipe first, then run `meridian start`). diff --git a/reference/cli.mdx b/reference/cli.mdx index db9553e..141e280 100644 --- a/reference/cli.mdx +++ b/reference/cli.mdx @@ -43,7 +43,7 @@ meridian stop Disables and boots out every LaunchAgent, then kills any orphaned `mlx_lm.server` processes that launchd does not track. The `.plist` files in `~/Library/LaunchAgents/` are left in place so `meridian start` can bring everything back up. -Use this command before editing `~/.meridian/.env` so the daemon picks up the new values on the next `meridian start`. +Use this command before editing the repo-root `.env` so the daemon picks up the new values on the next `meridian start`. @@ -129,7 +129,7 @@ Runs a full suite of environment health checks and prints a pass/fail result for - `meridian-daemon` binary exists and is executable - Service `.plist` files are installed and pass `plutil -lint` (daemon, jira-updater, screenpipe, UI) - Daemon process is running -- `~/.meridian/.env` configuration file exists +- Repo-root `.env` configuration file exists - screenpipe binary is in `$PATH` - screenpipe database exists at `~/.screenpipe/db.sqlite` - screenpipe process is running @@ -153,7 +153,7 @@ Run `meridian doctor` as the first diagnostic step whenever something seems wron meridian config edit ``` -Opens `~/.meridian/.env` in your `$EDITOR` (falls back to `nano` if `$EDITOR` is not set). This is the canonical way to update API keys, change the poll interval, or toggle classification without hunting for the file path. +Opens the repo-root `.env` in your `$EDITOR` (falls back to `nano` if `$EDITOR` is not set). This is the canonical way to update API keys, change the poll interval, or toggle classification without hunting for the file path. After saving, run `meridian restart` so the daemon picks up the new values. diff --git a/reference/environment-variables.mdx b/reference/environment-variables.mdx index 2f9f4b9..6724f3e 100644 --- a/reference/environment-variables.mdx +++ b/reference/environment-variables.mdx @@ -1,10 +1,10 @@ --- title: "Meridian Environment Variables and Configuration Reference" sidebarTitle: "Environment Variables" -description: "All environment variables Meridian reads from ~/.meridian/.env — core daemon, classification, Jira, GitHub, Linear, and MCP server settings." +description: "All environment variables Meridian reads from the repo-root .env — core daemon, classification, Jira, GitHub, Linear, and MCP server settings." --- -Meridian reads its configuration from `~/.meridian/.env`, which the installer creates and populates during `./install.sh`. You can edit it at any time with `meridian config edit`. Changes take effect after a `meridian restart`. +Meridian reads its configuration from a single `.env` file at the repository root, shared by the Rust daemon and the Python agents. `./install.sh` creates and populates this file from `.env.example` on first run. You can edit it at any time with `meridian config edit`. Changes take effect after a `meridian restart`. Every variable has a safe default; you only need to set the ones relevant to your workflow. The sections below list every supported variable grouped by the part of Meridian that reads it. @@ -79,10 +79,10 @@ The MCP server reads one variable at startup to locate the database. ## Minimal Example Configuration -The block below shows the minimum set of variables needed to run the full Meridian stack with Jira classification enabled. Copy it to `~/.meridian/.env` and fill in your values, or use `meridian config edit` to open the file directly. +The block below shows the minimum set of variables needed to run the full Meridian stack with Jira classification enabled. Copy it to the repo-root `.env` and fill in your values, or use `meridian config edit` to open the file directly. ```bash -# ~/.meridian/.env +# /.env # ── Core ────────────────────────────────────────────────────────────────────── POLL_INTERVAL_SECS=60 @@ -105,5 +105,5 @@ LINEAR_API_KEY=lin_api_your_key_here ``` -After editing `~/.meridian/.env`, run `meridian restart` to apply the new values. The daemon reads the file once at startup and does not hot-reload changes. +After editing the repo-root `.env`, run `meridian restart` to apply the new values. The daemon reads the file once at startup and does not hot-reload changes. diff --git a/reference/troubleshooting.mdx b/reference/troubleshooting.mdx index e7a0a64..d421bc7 100644 --- a/reference/troubleshooting.mdx +++ b/reference/troubleshooting.mdx @@ -98,7 +98,7 @@ meridian logs mlx-server -f Wait until you see `server: MLX model ready` (this can take up to 30 seconds on first run while the model downloads). -Alternatively, if you do not need session classification, set `CLASSIFICATION_ENABLED=false` in `~/.meridian/.env` and restart: +Alternatively, if you do not need session classification, set `CLASSIFICATION_ENABLED=false` in the repo-root `.env` and restart: ```bash meridian config edit # set CLASSIFICATION_ENABLED=false @@ -161,7 +161,7 @@ meridian config edit # verify SCREENPIPE_DB if you customised it A 401 from the Jira API means either `JIRA_EMAIL` or `JIRA_API_TOKEN` is wrong, or the token has been revoked. -1. Open `~/.meridian/.env` with `meridian config edit`. +1. Open the repo-root `.env` with `meridian config edit`. 2. Verify that `JIRA_EMAIL` matches the email address of the Atlassian account that owns the token. 3. Regenerate the token at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) and paste the new value into `JIRA_API_TOKEN`. 4. Restart: `meridian restart`. @@ -193,14 +193,14 @@ python3 scripts/refresh_pm_tasks.py --jql "project=KAN ORDER BY updated DESC" A GitHub 401 means the personal access token is expired, revoked, or was created without the `repo` scope. 1. Go to [github.com/settings/tokens](https://github.com/settings/tokens) and create a new classic PAT with at minimum the `repo` scope. -2. Update `GITHUB_TOKEN` in `~/.meridian/.env` via `meridian config edit`. +2. Update `GITHUB_TOKEN` in the repo-root `.env` via `meridian config edit`. 3. Restart: `meridian restart`. -1. Verify `LINEAR_API_KEY` is set correctly in `~/.meridian/.env`. +1. Verify `LINEAR_API_KEY` is set correctly in the repo-root `.env`. 2. Check `LINEAR_TEAM_IDS` — if set, confirm the team IDs are correct (visible in Linear's workspace settings URL). 3. Ensure the teams have open issues in a status that the connector picks up. 4. Check the jira-updater log (which also handles Linear sync) for error messages: