@yugabytedb/meko-mcp 2.3.0 → 2.5.0

package/README.md

@@ -6,19 +6,38 @@ Reduces manual setup to a single command.
 
 ## What this installer authenticates with
 
-The installer configures **API-key authentication only**. Every supported
-client sends `Authorization: Bearer <your-api-key>` on the wire, plus the
+Every client the installer configures authenticates with a Meko API key. Each
+one sends `Authorization: Bearer <your-api-key>` on the wire, plus the
 `User-Agent` the Cloud WAF requires. Most adapters store the header value in
 client config. Codex stores `bearer_token_env_var = "MEKO_API_KEY"` and resolves
 the key from its runtime environment; Claude Desktop passes the same variable
-through `mcp-remote` header interpolation.
-
-Cloud Meko also accepts a browser **OAuth** flow, but that path is out of scope
-here: you turn it on inside a client's own UI, and it uses no API key. Don't
-configure both against the same client — see [Two authentication
-modes](../README.md#two-authentication-modes--pick-one-dont-mix-them) for the
-comparison and the failure modes, including why OAuth with a loopback callback
-still fails against the DEV environment.
+through `mcp-remote` header interpolation. Capture hooks use the same key.
+
+You don't need to have a key already. The installer gets one in this order:
+
+1. `--api-key <key>`.
+2. The `MEKO_API_KEY` environment variable.
+3. **Browser sign-in (the default).** The installer opens the Meko sign-in page,
+   and after you sign in it creates a key named `Meko installer (<host>)
+   <timestamp>`. It uses the MCP server's OAuth flow with a `localhost`
+   callback, then calls the server's `POST /api-keys`. The OAuth session is
+   discarded; only the key is kept.
+
+Sign in with the same method you use for the Meko console. If the browser
+signs in as a user with no Meko account (for example Google here, email and
+password in the console), the server refuses to create a key, and the
+installer tells you how to retry or fall back to `--api-key`.
+
+The new key counts toward your 10 active keys and expires after 365 days. You
+can revoke it at cloud.mekodata.ai > **Settings > API Keys**. Use `--no-browser`
+to print the sign-in URL instead of opening a browser, for example over SSH.
+Runs with no terminal attached (CI, scripts, redirected stdin) skip sign-in and
+require a key, with or without `--yes`.
+
+Separately, some clients can run their own browser **OAuth** flow against Cloud
+Meko, configured in the client's own UI with no API key. The installer doesn't
+set that up. Don't configure both against the same client; see [Two
+authentication modes](../README.md#two-authentication-modes--pick-one-dont-mix-them).
 
 **Note:** The server accepts the key only as `Authorization: Bearer …` on the
 wire. An `API_KEY` or `MEKO_API_KEY` environment variable does nothing unless
@@ -48,7 +67,7 @@ Claude Desktop has two install paths: a one-click `.mcpb` Desktop Extension down
 npx @yugabytedb/meko-mcp
 ```
 
-The installer walks you through connection type, URL, API key, and skills installation with guided prompts.
+The installer walks you through connection type and URL, signs you in through your browser to create an API key (unless you pass `--api-key` or set `$MEKO_API_KEY`), then asks about skills.
 
 **Local one-liner (docker-compose stack already running):**
 
@@ -88,7 +107,7 @@ You can also combine both: install via `.mcpb` for the MCP wiring, then run Opti
 
 **Option A — Desktop Extension (`.mcpb`), one-click:**
 
-1. Download `meko-<version>.mcpb` from the [GitHub Releases page](https://github.com/yugabyte/meko-mcp-server/releases) (e.g. `meko-1.1.0.mcpb`).
+1. Download `meko-<version>.mcpb` from the [GitHub Releases page](https://github.com/yugabyte/meko-mcp-server/releases) (e.g. `meko-2.5.0.mcpb`). From 2.5.0, the `.mcpb`, the npm installer, and the public plugin share one version number.
 2. Open **Claude Desktop > Settings > Extensions > Install from file** and select the file (or drag the file onto that pane).
 3. When prompted, paste your Meko MCP URL and API key.
 4. Quit and relaunch Claude Desktop.
@@ -136,7 +155,13 @@ npx @yugabytedb/meko-mcp --client all --local --yes
 
 Each client is installed sequentially. A failure on one does not abort the others — the command exits with status 2 on partial success, 1 on total failure.
 
-**CI / non-interactive (Cloud Meko):**
+**Cloud Meko (signs in through your browser):**
+
+```bash
+npx @yugabytedb/meko-mcp --url https://mcp.mekodata.ai/mcp --client claude-code
+```
+
+**CI / non-interactive (Cloud Meko, existing API key):**
 
 ```bash
 npx @yugabytedb/meko-mcp \
@@ -155,13 +180,13 @@ The installer performs up to 5 steps (some are skippable via flags):
 | 2 | Set hook environment vars | Writes `MEKO_MCP_URL` and `MEKO_API_KEY` into `~/.claude/settings.json` under the `env` key. Also prunes any stale Meko hook entries in `settings.json.hooks` that point at a prior install path (e.g. a previous `npx` cache or homebrew-global copy) so only the current install's hooks fire. |
 | 3 | Register public plugin marketplace | `claude plugin marketplace add https://github.com/yugabyte/meko-skills.git --scope user` |
 | 4 | Install skills plugin | `claude plugin install meko-agent-skills --scope user` |
-| 5 | Validate setup | Config check via `claude mcp list`, MCP `initialize` handshake, `tools/list` verification, and a canary `datapack_list` call |
+| 5 | Validate setup | Config check via `claude mcp list`, MCP `initialize` handshake, `tools/list` verification, and a canary `datapack_search` call (`datapack_list` on older servers) |
 
 ### Post-install validation (canary)
 
-Step 5 includes a **canary call** that invokes the read-only `datapack_list` tool and asserts the response is a non-empty JSON array of datapack records. This proves the part of the stack that connectivity + `tools/list` don't cover: the API token authenticated as a real Meko identity, the tenant resolver found an account for it, and datapack routing wired up the user's actual workspace. A successful `tools/list` only proves the server speaks MCP — it says nothing about whether a Meko tool call would actually find the user's data.
+Step 5 includes a **canary call** that invokes the read-only `datapack_search(limit=1)` tool and asserts it returns at least one datapack. On a server whose `tools/list` has no `datapack_search`, it calls `datapack_list` instead and asserts a non-empty JSON array; `datapack_search` reads one page whatever the account size, where `datapack_list` reads the whole account. This proves the part of the stack that connectivity + `tools/list` don't cover: the API token authenticated as a real Meko identity, the tenant resolver found an account for it, and datapack routing wired up the user's actual workspace. A successful `tools/list` only proves the server speaks MCP — it says nothing about whether a Meko tool call would actually find the user's data.
 
-The canary used to do a `memory_add` → `memory_get_by_id` → `memory_delete_by_id` round-trip, but mem0's LLM fact-extractor is non-deterministic for synthetic test text — for the same input it sometimes returned `results: []` (no facts extracted) while still adding graph relations, which the installer reported as "no memory id" and surfaced as a validation failure even when the server was healthy. `datapack_list` is a single SQL read with no LLM in the path and returns deterministically.
+The canary used to do a `memory_add` → `memory_get_by_id` → `memory_delete_by_id` round-trip, but mem0's LLM fact-extractor is non-deterministic for synthetic test text — for the same input it sometimes returned `results: []` (no facts extracted) while still adding graph relations, which the installer reported as "no memory id" and surfaced as a validation failure even when the server was healthy. Both datapack tools are a single SQL read with no LLM in the path and return deterministically.
 
 `--no-canary` skips the canary entirely. The `initialize` and `tools/list` checks still run. Use this when you've already proved the round-trip in a prior step (CI, pre-flight smoke).
 
@@ -203,7 +228,7 @@ The canary used to do a `memory_add` → `memory_get_by_id` → `memory_delete_b
   - Steering file: `~/.kiro/steering/meko.md` or `.kiro/steering/meko.md`. It follows hook capture when the session-start marker is present and falls back to agent-driven persistence only when hooks are disabled, untrusted, or a different CLI 2.x agent is selected. See [Kiro notes](#kiro-notes).
 - **OpenCode CLI/TUI 1.18.x**
   - User plugin: `$OPENCODE_CONFIG_DIR/plugins/meko.js` when set, otherwise `~/.config/opencode/plugins/meko.js`; project plugin: `<project>/.opencode/plugins/meko.js`.
-  - Stable runtime and private environment: `$OPENCODE_CONFIG_DIR/meko/` when set, otherwise `~/.config/opencode/meko/`, or `<project>/.opencode/meko/`. `opencode-hook-env.json` is mode 0600 and contains the MCP URL, API key, server name, User-Agent, hook client, stable Node executable, and watermark dir. Automatic capture uses the server-default datapack in this release. `--datapack` applies only to `--migrate`. OpenCode does not read `pin-<slug>.json` (no SessionStart, and `meko-select-datapack` is not installed).
+  - Stable runtime and private environment: `$OPENCODE_CONFIG_DIR/meko/` when set, otherwise `~/.config/opencode/meko/`, or `<project>/.opencode/meko/`. `opencode-hook-env.json` is mode 0600 and contains the MCP URL, API key, server name, User-Agent, hook client, stable Node executable, and watermark dir. Edits to this file reach the next capture attempt, including the retries of a running capture timer. Removing `MEKO_MCP_URL` or `MEKO_API_KEY` from the file, as `--uninstall` does, also removes it from a running timer's next attempt. Automatic capture uses the server-default datapack in this release. `--datapack` applies only to `--migrate`. OpenCode does not read `pin-<slug>.json` (no SessionStart, and `meko-select-datapack` is not installed).
   - Skill: `$OPENCODE_CONFIG_DIR/skills/meko-mcp-tools/` when set, otherwise `~/.config/opencode/skills/meko-mcp-tools/`, or `<project>/.opencode/skills/meko-mcp-tools/`.
   - The plugin mutates OpenCode's resolved configuration at runtime with a native remote MCP entry (`type: remote`, `enabled: true`, `oauth: false`). It does **not** edit `opencode.json` or `opencode.jsonc`; validation runs `opencode debug config` and verifies the resolved entry.
   - Restart OpenCode after install. Reinstall upgrades installer-owned assets while preserving durable capture state and user-owned collisions.
@@ -231,14 +256,15 @@ Usage:
 |------|-------------|---------|
 | `--client <list>` | Target client(s): one or more of `claude-code`, `claude-desktop`, `cursor`, `codex`, `kiro`, `opencode`. Comma-separated, or `all`. `codex` covers both the OpenAI Codex CLI and the Codex Desktop App (they share `~/.codex/config.toml`); `kiro` covers both the Kiro IDE and `kiro-cli` (they share `~/.kiro/settings/mcp.json`). OpenCode is version-gated to CLI/TUI 1.18.x. Aliases: `claude` → `claude-code`, `kiro-cli` / `kiro-ide` → `kiro`. | `claude-code` |
 | `--url <url>` | MCP server URL (from cloud.mekodata.ai > Datapacks > Connect) | Shared existing endpoint, otherwise production; conflicts prompt or require `--url` under `--yes` |
-| `--api-key <key>` | API key for Cloud Meko authentication. If a Cloud `--url` is supplied without this flag, the installer falls back to `$MEKO_API_KEY`, then to an interactive prompt on a TTY. Only fails hard when running under `--yes` or with no TTY attached. | _(interactive prompt or `$MEKO_API_KEY` env)_ |
+| `--api-key <key>` | Use an existing Cloud Meko API key instead of signing in. Without this flag, the installer falls back to `$MEKO_API_KEY`, then to browser sign-in, which creates a key. Fails hard when no TTY is attached, with or without `--yes`. | _(`$MEKO_API_KEY`, else browser sign-in)_ |
+| `--no-browser` | Print the sign-in URL instead of opening a browser. | `false` |
 | `--local` | Use local Meko at `http://localhost:8000/mcp` (no API key needed) | `false` |
 | `--scope <scope>` | Config scope: `user` or `project` (`claude-desktop` uses user scope config) | `user` |
 | `--name <name>` | MCP server name in config | `meko` |
 | `--cursor-hook-mode <mode>` | Cursor hook strategy: `native` or `claude-compat` | `native` |
 | `--skip-skills` | Skip plugin marketplace and skills installation (steps 3-4) | `false` |
 | `--skip-validation` | Skip post-install validation (step 5) | `false` |
-| `--no-canary` | Skip the canary `datapack_list` call. Basic connectivity + tools/list still run. | `false` |
+| `--no-canary` | Skip the canary `datapack_search` / `datapack_list` call. Basic connectivity + tools/list still run. | `false` |
 | `--dry-run` | Show what would be done without making changes | `false` |
 | `--uninstall` | Remove Meko MCP server, skills, env vars, and marketplace entry | `false` |
 | `--verbose` | Show detailed output (API keys are always redacted) | `false` |
@@ -252,7 +278,9 @@ Capture health flags (durable outbox / recovery — Capture V2):
 |------|-------------|---------|
 | `--capture-status` | Report aggregate conversation-capture health from `~/.claude/meko-capture` (or `MEKO_WATERMARK_DIR`). Exit `0` = healthy\|catching_up, `2` = degraded_retrying, `3` = blocked_action_required. | `false` |
 | `--json` | With `--capture-status`, print machine-readable JSON matching the capture-health cache shape. Also accepted by `--capture-cleanup`. | `false` |
-| `--capture-cleanup <action>` | Inspect and clean up stuck capture on this machine. Actions: `status`, `stop`, `resume`, `drain`, `discard`, `repair`. See [Clean up stuck capture](../OPERATIONS.md#clean-up-stuck-capture). Exit `0` = done, `1` = error, `2` = partly done. | |
+| `--no-autofix` | Turn off automatic capture repair. The capture timer otherwise runs `--capture-cleanup fix` every 30 minutes (`MEKO_AUTOFIX_INTERVAL`) when a session is stuck. Saved for every client; a reinstall keeps it. | `false` |
+| `--autofix` | Turn automatic capture repair back on. | `false` |
+| `--capture-cleanup <action>` | Inspect and clean up stuck capture on this machine. Actions: `status`, `fix`, `stop`, `resume`, `drain`, `discard`, `repair`. Start with `fix`. See [Clean up stuck capture](../OPERATIONS.md#clean-up-stuck-capture). Exit `0` = done, `1` = error, `2` = partly done. | |
 | `--session <id>` | With `--capture-cleanup`, act on one session. Repeatable; a unique prefix of the ID is enough. A bare ID after the action works too: `--capture-cleanup drain c0acdeb2`. | |
 | `--all` | With `--capture-cleanup`, act on every session. `drain` and `discard` need `--session` or `--all`. | `false` |
 | `--max-exchanges <n>` | With `--capture-cleanup drain`, stop after sending this many exchanges in total. | `200` |
@@ -397,6 +425,14 @@ auth skipped: 0                (calls dropped on a mid-run 401/403; re-run to re
 - **`--yes` without `--with-migrate`**: install succeeds silently and prints a one-line tip pointing at `create-meko-setup --migrate`. No migration is started.
 - **`--yes --with-migrate`**: install succeeds, then the detached migration is started automatically. Progress via `--migrate-status`.
 
+### Destination datapack
+
+`--datapack <name|id>` picks the datapack the migration writes to; without it the migration uses `meko_default_datapack`, or the server's own default when that row isn't visible. The resolved destination is printed before the run starts.
+
+- A name is looked up with `datapack_search(name=...)`, preferring a datapack you own over a shared one with the same name. A miss lists similar names.
+- A UUID is looked up with `datapack_describe`, so any datapack the API key can open resolves, however many the account has.
+- On a server whose `tools/list` has no `datapack_search`, both are matched against the `datapack_list` response instead.
+
 ### Idempotency, resume, and state
 
 - Per-run logs: `~/.meko/migrate/<run-id>/log.ndjson` (one JSON object per line). `tail -f | jq .` is a reasonable debug loop. This is the file the start banner points at, and the only one with run diagnostics in it.
@@ -412,7 +448,7 @@ auth skipped: 0                (calls dropped on a mid-run 401/403; re-run to re
 ### What does NOT get migrated (v1)
 
 - Slash-command skills, hooks, and `.claude/settings.json` — those remain in Claude Code's own config; Meko has no equivalent tool.
-- Knowledge-base documents — KB ingestion is UI-only (Datapack → Actions → Add Knowledge); not exposed via MCP.
+- Knowledge-base documents — this migration doesn't re-upload old KB files; add them via `knowledgebase_upload_document` or the UI (Datapack → Actions → Add Knowledge) after migrating.
 - Transcripts from unregistered coding agents (for example Aider, Continue.dev, or Windsurf).
 - `user_id` is left null on every call (the server fills it from the API key). Multi-user routing is a follow-up.
 
@@ -442,8 +478,8 @@ Cursor previously had a hybrid hook mode that also wrote Claude-compatible hooks
 **Never use the `mcp-remote` bridge with Kiro.** Kiro speaks remote MCP natively, so the installer registers `{ url, headers }` directly.
 
 What was measured against `https://mcp.mekodata.ai` before 2026-09-24. Production
-now accepts loopback redirects on `/register`, `/authorize`, and `/token`; DEV
-(`mcp.mekodev.com`) still refuses them. The `mcp-remote` findings below still
+now accepts loopback redirects on `/register`, `/authorize`, and `/token`, and a
+2026-10-07 re-measure found DEV (`mcp.mekodev.com`) accepts them too ([#277](https://github.com/yugabyte/meko-mcp-server/issues/277)). The `mcp-remote` findings below still
 apply, because an API key behind the bridge is never sent.
 
 - `mcp-remote@0.1.38` reads no auth env var (its only `process.env` reference is `MCP_REMOTE_CONFIG_DIR`), so `MEKO_API_KEY` is never sent; headers come only from `--header`. It therefore connects unauthenticated and begins OAuth.
@@ -460,7 +496,7 @@ Confirmed on `kiro-cli` 2.18.1 itself. Its DCR registration is:
 
 so against Cloud Meko it fails with `Dynamic registration failed: Registration failed: HTTP 403 Forbidden`. Its first `POST /mcp` also goes out with **no `User-Agent`**, which trips a second HTML-403 rule independently. With Mode 1 headers and a valid `mko_tkn_…` key it connects and lists all 23 tools — no OAuth, no 403.
 
-Both surfaces are verified against Cloud Meko with a real key. On the **Kiro IDE** (1.0.337), the installer's config produces `[meko] Connected` in its `Kiro - MCP Logs` output. On **`kiro-cli`** (2.18.1) the agent enumerates all 23 tools. The steering file is confirmed to reach the model, not just disk: asked with tools disabled what its Meko steering requires, the agent answered that it must call `memory_add` when the user states a durable fact and that this "explicitly overrides the meko-mcp-tools skill", which assumes capture hooks are running.
+Both surfaces are verified against Cloud Meko with a real key. On the **Kiro IDE** (1.0.337), the installer's config produces `[meko] Connected` in its `Kiro - MCP Logs` output. On **`kiro-cli`** (2.18.1) the agent enumerated all 23 tools the server had at the time; production now lists 42, including 14 `amp_*` tools. The steering file is confirmed to reach the model, not just disk: asked with tools disabled what its Meko steering requires, the agent answered that it must call `memory_add` when the user states a durable fact and that this "explicitly overrides the meko-mcp-tools skill", which assumes capture hooks are running.
 
 One naming correction worth knowing, since it has caused confusion: **`Q DEV CLI` is not an OAuth client id.** It is the MCP `initialize` handshake's `clientInfo.name` (`"clientInfo":{"name":"Q DEV CLI","version":"1.0.0"}`); the string appears nowhere in the `kiro-cli` binary's OAuth path, and its actual DCR `client_name` is `kiro`. There is nothing named `Q DEV CLI` to allowlist. See [#277](https://github.com/yugabyte/meko-mcp-server/issues/277).
 
@@ -481,12 +517,12 @@ Uninstall removes only files carrying installer ownership markers: the three sta
 | | Cloud Meko | Local Meko |
 |---|-----------|-----------|
 | **URL** | `https://mcp.mekodata.ai/mcp` (or the endpoint shown by cloud.mekodata.ai) | `http://localhost:8000/mcp` |
-| **Authentication** | Requires `--api-key` or `$MEKO_API_KEY` env var | None |
+| **Authentication** | Browser sign-in creates an API key, or pass `--api-key` / `$MEKO_API_KEY` | None |
 | **MCP registration** | Includes `-H "Authorization: Bearer <key>"` header | No auth header |
 | **Hook env vars** | Both `MEKO_MCP_URL` and `MEKO_API_KEY` written to settings | Only `MEKO_MCP_URL` written |
 | **Infrastructure** | Hosted, no local setup needed | Requires `docker compose up -d` running the Meko stack |
 | **Use case** | Production, team collaboration | Development, testing |
-| **Flag** | `--url <url> --api-key <key>` | `--local` |
+| **Flag** | `--url <url>` (optionally `--api-key <key>`) | `--local` |
 
 The installer auto-detects cloud vs local based on the URL: any URL containing `localhost` or `127.0.0.1` is treated as local (no API key required). All other URLs are cloud and require authentication.
 
@@ -558,7 +594,7 @@ Re-running the installer is idempotent but not inert. A re-run:
 
 ### Updating the skills plugin (Claude Code)
 
-The `meko-agent-skills` plugin is distributed via the Claude Code plugin marketplace and versions independently of the installer npm package. Re-running the installer now picks up the latest skill definitions automatically: it probes `claude plugin list` and, when the plugin is already present, calls
+The `meko-agent-skills` plugin is distributed via the Claude Code plugin marketplace from yugabyte/meko-skills, not npm. It also carries the Claude Code capture hooks. From 2.5.0, the plugin, the installer, and the `.mcpb` share one version number. Re-running the installer now picks up the latest skill definitions automatically: it probes `claude plugin list` and, when the plugin is already present, calls
 
 ```bash
 claude plugin update meko-agent-skills@meko-agent-skills --scope <scope>
@@ -725,10 +761,11 @@ Three known causes:
 - **No `User-Agent` header.** The WAF refuses any request without one. Add
   `User-Agent: meko-mcp-installer/1.0`. The installer always does; hand-written
   configs and some native MCP clients don't.
-- **An OAuth callback on a loopback address (DEV only).** The DEV WAF refuses
-  any `redirect_uri` pointing at an internal host, so dynamic client
-  registration fails there for any client that registers such a callback,
-  including IDEs. Production accepts these callbacks as of 2026-09-24. Tracked in
+- **An OAuth callback on a loopback address (DEV, historically).** The DEV WAF
+  refused any `redirect_uri` pointing at an internal host, so dynamic client
+  registration failed there for any client that registers such a callback,
+  including IDEs. Production accepts these callbacks as of 2026-09-24, and a
+  2026-10-07 re-measure didn't reproduce the DEV block. Tracked in
   [#277](https://github.com/yugabyte/meko-mcp-server/issues/277).
 - **Message text that looks like a path.** Capture writes containing `../` or
   absolute paths can trip a traversal rule. Tracked in
@@ -745,7 +782,7 @@ API-key checks:
 - If using `$MEKO_API_KEY` env var, ensure it is exported in the current shell.
 - Confirm the key environment matches the URL: PATs minted on `app.mekodev.com` only validate against `mcp.mekodev.com`; PATs minted on `cloud.mekodata.ai` only validate against `mcp.mekodata.ai`.
 - The installer normalizes API keys (trims surrounding whitespace and a single matching pair of quotes) so a paste with a trailing newline or a literal `"…"` from a `.env` file is fine — but your raw shell variable might still be contaminated. Echo it (`echo "[$MEKO_API_KEY]"`) and check the brackets bracket the key tightly with no extra characters.
-- Re-run the installer interactively to re-enter the key.
+- Re-run the installer in a terminal without `--api-key` and with `$MEKO_API_KEY` unset to sign in through the browser and create a new key, or pass a new key with `--api-key`.
 
 ### Plugin marketplace already registered
 
@@ -774,7 +811,7 @@ cp ~/.claude/settings.json.bak ~/.claude/settings.json
 Missing core tools: memory_search, memory_get_by_id, conversation_create. Found 0 tool(s) total.
 ```
 
-The MCP server responded but does not expose the expected tools (`memory_search`, `memory_get_by_id`, `conversation_create`, `datapack_list`). This usually means a server version mismatch. Update the MCP server or check which datapack is connected. `memory_get_by_id` is used by the canary round-trip for direct-row verification (see [Post-install validation](#post-install-validation-canary-round-trip) above), so an older server that exposes `memory_search` but not `memory_get_by_id` will fail the canary check.
+The MCP server responded but does not expose the expected tools (`memory_search`, `memory_get_by_id`, `conversation_create`, `datapack_list`). This usually means a server version mismatch. Update the MCP server or check which datapack is connected. The canary itself calls `datapack_search`, or `datapack_list` on a server without it (see [Post-install validation](#post-install-validation-canary) above).
 
 ### DNS lookup failed
 
@@ -862,6 +899,8 @@ node installer/bin/create-meko-setup.mjs --uninstall --verbose
 |---|----------|-------|-----------------|
 | M1 | Fresh local install | `node installer/bin/create-meko-setup.mjs --local --yes` with docker stack running | All 5 steps pass, validation shows 3 green checks |
 | M2 | Fresh cloud install | Run interactively, provide Cloud Meko URL + API key | MCP registered with `Authorization: Bearer` header, env vars set, validation passes |
+| M2b | Browser sign-in | In a terminal with `$MEKO_API_KEY` unset, run `--url https://mcp.mekodata.ai/mcp` without `--api-key` and sign in | A key is created through `POST /api-keys`; validation passes |
+| M2c | No terminal, no key | Pipe stdin (or run under CI) with no `--api-key` and no `$MEKO_API_KEY` | Exits with "API key is required for Cloud Meko" |
 | M3 | Existing config | Run installer when `meko` MCP is already registered | Prompts to overwrite; answering No keeps existing config |
 | M4 | No claude CLI | Run on a machine without `claude` in PATH | Exits with error message and install link |
 | M5 | Server unreachable | Install with `--skip-validation`, then re-run without it | Install succeeds; validation warns about connectivity |