leadbay
diff --git a/‎CHANGELOG.md‎
Lines changed: 4 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎packages/dxt/manifest.template.json‎
Lines changed: 3 additions & 3 deletions b/‎packages/dxt/manifest.template.json‎
Lines changed: 3 additions & 3 deletions
diff --git a/‎packages/leadclaw/src/index.ts‎
Lines changed: 6 additions & 3 deletions b/‎packages/leadclaw/src/index.ts‎
Lines changed: 6 additions & 3 deletions
diff --git a/‎packages/mcp/CHANGELOG.md‎
Lines changed: 32 additions & 0 deletions b/‎packages/mcp/CHANGELOG.md‎
Lines changed: 32 additions & 0 deletions
diff --git a/‎packages/mcp/MIGRATION.md‎
Lines changed: 72 additions & 0 deletions b/‎packages/mcp/MIGRATION.md‎
Lines changed: 72 additions & 0 deletions
@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.3.0 — 2026-04-29
+
+- **`@leadbay/mcp` 0.3.0**: closes [product#3504](https://github.com/leadbay/product/issues/3504) end-to-end. Composite write tools (`refine_prompt`, `report_outreach`, `adjust_audience`, `bulk_qualify_leads`, `enrich_titles`, `answer_clarification`, `import_leads`) are now ON by default — `LEADBAY_MCP_WRITE` defaults to `"1"`. The `SERVER_INSTRUCTIONS` is now built dynamically from the actual exposed tool set, so the system prompt no longer references tools the server doesn't register. `leadbay-mcp login` defaults to writing a 0600-mode credentials file at the platform-correct path (`$XDG_CONFIG_HOME/leadbay/credentials.json`, `~/Library/Application Support/leadbay/credentials.json`, or `%APPDATA%\leadbay\credentials.json`); pass `--unsafe-print-token` for legacy CI flows. `leadbay-mcp install` now registers Claude Code at `--scope user` so the MCP server is visible from any project. **Behavior callout**: in 0.2.x the parser only recognized `LEADBAY_MCP_WRITE === "1"` as ON; 0.3.0 also accepts `true|yes|on` as ON. See `packages/mcp/MIGRATION.md`.
+
 ## 0.2.5 — 2026-04-28
 
 - **`@leadbay/mcp` 0.2.5** + **`@leadbay/leadclaw` 0.2.5**: new `leadbay_import_leads` composite write tool ([product#3537](https://github.com/leadbay/product/issues/3537)). Imports a list of company domains and returns Leadbay leadIds for the ones the crawler already knows, chainable into `leadbay_bulk_qualify_leads` and `leadbay_research_lead`. Writes user state (creates a CRM-imports row visible in the web UI). Gated behind `LEADBAY_MCP_WRITE=1` (MCP) and `exposeWrite: true` (OpenClaw). See package CHANGELOGs for full surface, error codes, and limitations.
 
@@ -43,7 +43,7 @@
     "leadbay_token": {
       "type": "string",
       "title": "Leadbay bearer token",
-      "description": "Mint one with: npx -y @leadbay/mcp login --email <you> --region <us|fr> --write-config ~/leadbay.json (then copy the token from that file)",
+      "description": "Mint one with: npx -y @leadbay/mcp@0.3 login --email <you> --region <us|fr> (then copy LEADBAY_TOKEN from the credentials file the command writes — path is shown on stderr)",
       "sensitive": true,
       "required": true
     },
@@ -58,8 +58,8 @@
     "leadbay_mcp_write": {
       "type": "boolean",
       "title": "Enable write tools",
-      "description": "Let Claude mutate your Leadbay account (refine_prompt, adjust_audience, report_outreach). Off by default — enable only when you want the agent to modify state.",
-      "default": false,
+      "description": "Allow Claude to call composite write tools (refine_prompt, adjust_audience, report_outreach, bulk_qualify_leads, enrich_titles, answer_clarification, import_leads). ON by default since 0.3.0 — turn this off only if you want a strictly read-only agent.",
+      "default": true,
       "required": false
     }
   },
 
@@ -13,9 +13,12 @@ import type { Tool } from "@leadbay/core";
 //
 // Tool exposure is gated by plugin config:
 //   - composite read tools: ALWAYS exposed (the agent's default surface)
-//   - composite write tools: ALWAYS exposed (OpenClaw runs in user context;
-//     the agent has explicit consent. Write composites enforce their own
-//     verification — e.g. report_outreach requires verification={source, ref}.)
+//   - composite write tools: exposed only when exposeWrite=true
+//     (independent of the @leadbay/mcp default — OpenClaw plugins go through
+//     a separate consent surface. The MCP server flipped this to default-on
+//     in 0.3.0 so its own SERVER_INSTRUCTIONS would stop referencing
+//     unregistered tools; OpenClaw doesn't ship those instructions, so the
+//     gate stays explicit here.)
 //   - granular read tools: exposed only when exposeGranular=true
 //   - granular write tools: exposed only when both exposeGranular=true
 //     AND exposeWrite=true
 
@@ -1,5 +1,37 @@
 # Changelog — @leadbay/mcp
 
+## 0.3.0 — 2026-04-29
+
+Behavior-changing release: closes [product#3504](https://github.com/leadbay/product/issues/3504) end-to-end. Default-installed MCP server now matches its own system prompt out of the box, the `login` command never lands a bearer token in scrollback by default, and `claude mcp add` registers Leadbay at user scope so it's visible from any project.
+
+### Coverage — composite write tools default ON
+
+- **`LEADBAY_MCP_WRITE` default is now `"1"` (ON).** The composite write tools (`leadbay_bulk_qualify_leads`, `leadbay_enrich_titles`, `leadbay_refine_prompt`, `leadbay_report_outreach`, `leadbay_adjust_audience`, `leadbay_answer_clarification`, `leadbay_import_leads`) are exposed by default. Set `LEADBAY_MCP_WRITE=0` (or `--no-write` on `install`) to disable them.
+- **`SERVER_INSTRUCTIONS` is now dynamic.** The system prompt sent to MCP clients references only the tools actually registered on this instance. Read-only-mode agents receive a different prompt that omits the verification mandate and tells the agent to ask the user to enable writes if they request a config-mutating action.
+- **`leadbay-mcp install --include-write` is a no-op (deprecated).** Writes are on by default. Pass `--no-write` for the inverse. The deprecation warning prints **before** the password prompt so it's not buried.
+- **`LEADBAY_MCP_WRITE` value-vocabulary expanded.** In 0.2.x only `"1"` was ON; `"true"` / `"yes"` / `"on"` were treated as OFF. In 0.3.0 the parser accepts all of those as ON, and `"0"` / `"false"` / `"no"` / `"off"` as OFF. Unrecognized values default to ON with a one-shot stderr warning. **Existing operators using `=true` / `=yes` / `=on` will see writes flip ON.** See [MIGRATION.md](./MIGRATION.md).
+
+### Login — no token in stdout
+
+- **`leadbay-mcp login` default writes a 0600-mode credentials file.** The path resolves to `$XDG_CONFIG_HOME/leadbay/credentials.json` if set, else `~/Library/Application Support/leadbay/credentials.json` on macOS, `%APPDATA%\leadbay\credentials.json` on Windows, else `~/.config/leadbay/credentials.json`. Existing `~/.leadbay-mcp.json` files (0.2.x) are still honored on this run with a deprecation note pointing at the new path (no automatic file move).
+- **`--unsafe-print-token`** restores the previous "print JSON config to stdout" behavior. The deprecated `--print-token` alias still works for one release with a deprecation warning.
+- **Collision detection** — if the target credentials file already exists with a different `LEADBAY_TOKEN` or `LEADBAY_REGION`, `login` refuses without `--force` and tells the operator how to keep both files.
+- **EACCES / EROFS / ENOENT** errors on the file write print actionable remediation pointing at `--write-config /tmp/...` or `--unsafe-print-token`.
+
+### Scope — visible from any project
+
+- **`leadbay-mcp install` now passes `--scope user` to `claude mcp add`.** This was Ludo's third complaint in #3504: the default `claude mcp add` is project-local, so a freshly-opened conversation from a different directory can't see the server. README §2 (Claude Code), §1 (install), and §4 (troubleshooting table) all reflect the user-scope recommendation.
+
+### Migration
+
+- Read [MIGRATION.md](./MIGRATION.md) for the value-vocabulary flip, the login default, and the install scope change.
+- The legacy DXT manifest key (`leadbay_mcp_write`) is unchanged in shape — it now defaults `true` (ON) and feeds the same `LEADBAY_MCP_WRITE` env var. Users who explicitly set the toggle to `false` keep their read-only behavior; users who never touched it (the bug case Ludo hit) now get the new default ON.
+- Tests: dropped the `SERVER_INSTRUCTIONS` const re-export. Tests now exercise `buildServerInstructions(exposedSet)` directly across the default/read-only/advanced matrices. New unit suites: `parse-write-env.test.ts`, `login-default.test.ts`, `install-flags.test.ts`.
+
+### Known follow-up (0.4.0)
+
+- `compositeWriteTools` will split into safer-tier (credit-spending: bulk_qualify_leads, enrich_titles, report_outreach, answer_clarification) and config-mutating-tier (refine_prompt, adjust_audience, import_leads), with audit-log + one-click undo on the config-mutating side. Tracked separately.
+
 ## 0.2.5 — 2026-04-28
 
 New `leadbay_import_leads` composite write tool.
 
@@ -1,3 +1,75 @@
+# Migration: leadbay-mcp 0.2.x → 0.3.0
+
+This release fixes [product#3504](https://github.com/leadbay/product/issues/3504): the default-installed MCP server's system prompt told the agent to call tools that the server didn't actually expose. Three behavior changes you need to know about.
+
+## 1. `LEADBAY_MCP_WRITE` defaults to ON
+
+In 0.2.x the composite write tools (`leadbay_bulk_qualify_leads`, `leadbay_enrich_titles`, `leadbay_refine_prompt`, `leadbay_report_outreach`, `leadbay_adjust_audience`, `leadbay_answer_clarification`, `leadbay_import_leads`) were gated behind `LEADBAY_MCP_WRITE=1`. The `SERVER_INSTRUCTIONS` referenced them anyway → users got an agent system prompt that lied about what was available.
+
+**0.3.0**: `LEADBAY_MCP_WRITE` defaults to `"1"` (ON). The system prompt is built from the actual exposed tool set, so it stops lying. To restore the previous read-only behavior, set `LEADBAY_MCP_WRITE=0` (or `--no-write` on `leadbay-mcp install`).
+
+### Value-vocabulary flip
+
+In 0.2.x the parser was strict: only `LEADBAY_MCP_WRITE === "1"` turned writes on. So `=true`, `=yes`, `=on` were treated as OFF (probably accidentally — the user clearly meant "on"). The 0.3.0 parser accepts all of these as ON:
+
+| Value | 0.2.x meaning | 0.3.0 meaning |
+|---|---|---|
+| unset | OFF | **ON** |
+| `""` | OFF | **ON** |
+| `"1"` / `"true"` / `"yes"` / `"on"` | OFF (only `"1"`) / OFF (the rest) | **ON** |
+| `"0"` / `"false"` / `"no"` / `"off"` | OFF | OFF |
+| anything else | OFF | ON + stderr warning |
+
+If you were relying on `LEADBAY_MCP_WRITE=true` to mean OFF (unlikely but possible), switch to `LEADBAY_MCP_WRITE=0`.
+
+## 2. `leadbay-mcp login` no longer prints the token to stdout
+
+In 0.2.x `login` printed the bearer token (inside an MCP-config JSON blob) to stdout by default, with a stderr warning. Real users (Ludo's incident) had tokens leak into terminal scrollback / agent chat / CI logs.
+
+**0.3.0**: `login` writes a `0600`-mode credentials file by default. The path resolves per-platform:
+
+| Platform | Default path |
+|---|---|
+| Linux (or anywhere `XDG_CONFIG_HOME` is set) | `$XDG_CONFIG_HOME/leadbay/credentials.json` (or `~/.config/leadbay/credentials.json`) |
+| macOS | `~/Library/Application Support/leadbay/credentials.json` |
+| Windows | `%APPDATA%\leadbay\credentials.json` |
+
+If `~/.leadbay-mcp.json` (the 0.2.x default) already exists, `login` writes to that path with a one-shot deprecation note pointing at the new location.
+
+### `--unsafe-print-token` (legacy CI use)
+
+Pass `--unsafe-print-token` to restore the old "print to stdout" behavior. The deprecated `--print-token` alias still works for one release with a warning. Use only if you have to — the token will end up in scrollback / logs.
+
+### Collision detection
+
+If the target file already exists with a different `LEADBAY_TOKEN` or `LEADBAY_REGION`, `login` refuses without `--force` and tells you how to keep both files. Toggling between accounts no longer silently overwrites the prior token.
+
+### File-write errors
+
+`EACCES` / `EROFS` / `ENOENT` print actionable remediation pointing at `--write-config /tmp/...` or `--unsafe-print-token`.
+
+## 3. `leadbay-mcp install` registers Claude Code at `--scope user`
+
+Previously `claude mcp add leadbay …` defaulted to project-local scope, so opening Claude Code from a different directory made Leadbay invisible. Ludo's #3504 third complaint.
+
+**0.3.0**: `install` injects `--scope user` into the `claude mcp add` argv. New installs are visible from any project.
+
+If you have a 0.2.x project-scope install and want to upgrade to user scope, run:
+```bash
+claude mcp remove leadbay
+npx -y @leadbay/mcp@0.3 install --email you@yourcompany.com --region us
+```
+Or do it manually:
+```bash
+claude mcp add leadbay --scope user --env LEADBAY_TOKEN=<token> --env LEADBAY_REGION=us -- npx -y @leadbay/mcp@0.3
+```
+
+## 4. `--include-write` is a no-op
+
+The legacy `leadbay-mcp install --include-write` flag is accepted but a no-op — writes are on by default in 0.3.0. The deprecation warning prints **before** the password prompt so users see it.
+
+---
+
 # Migration: leadclaw / leadbay-mcp 0.1.x → 0.2.0
 
 This release is the autoplan-reviewed agent-experience overhaul. The OpenClaw