@yugabytedb/meko-mcp 2.0.0 → 2.2.0

package/README.md

@@ -1,12 +1,34 @@
 # Meko Setup Installer
 
-A zero-dependency Node.js CLI that configures [Meko MCP Server](https://mekodata.netlify.app/) for Claude Code, Claude Desktop, Cursor, and OpenAI Codex (CLI + Desktop App) in one command. It registers MCP server settings, configures hook/runtime environment where supported, installs skills support, and validates the setup.
+A zero-dependency Node.js CLI that configures [Meko MCP Server](https://mekodata.netlify.app/) for Claude Code, Claude Desktop, Cursor, OpenAI Codex (CLI + Desktop App), and Kiro (IDE + CLI) in one command. It registers MCP server settings, configures hook/runtime environment where supported, installs skills support, and validates the setup.
 
 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
+`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 isn't currently usable from
+clients that register a loopback callback.
+
+**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
+the client config references it. The installer creates that reference for
+Codex and Claude Desktop; installer-managed capture hooks also read
+`MEKO_API_KEY` when they send data directly.
+
 ## Prerequisites
 
-- **Node.js 18 or newer** on your PATH. Get it from [nodejs.org](https://nodejs.org/) or via a version manager (`nvm`, `fnm`, `asdf`). `npx`, which comes bundled with Node, is how you invoke the installer.
+- **Node.js 20.18.1 or newer** on your PATH. Get it from [nodejs.org](https://nodejs.org/) or via a version manager (`nvm`, `fnm`, `asdf`). `npx`, which comes bundled with Node, is how you invoke the installer. (The Claude Desktop `mcp-remote` bridge depends on `undici@^7`, whose every release declares `engines.node >= 20.18.1`; the installer enforces that exact floor so the bridge can start.)
 
 ## Quick Start
 
@@ -62,7 +84,7 @@ You can also combine both: install via `.mcpb` for the MCP wiring, then run Opti
 4. Quit and relaunch Claude Desktop.
 5. Verify in chat: *"Is Claude configured with an MCP Server for Meko?"*
 
-Prerequisite: Node 18+ on `PATH` (the bundle launches `npx mcp-remote` under the hood). See [`mcpb/README.md`](../mcpb/README.md) for what's in the bundle.
+Prerequisite: Node 20.18.1+ on `PATH` (the bundle launches `npx mcp-remote` under the hood). See [`mcpb/README.md`](../mcpb/README.md) for what's in the bundle.
 
 **Option B — `create-meko-setup` installer:**
 
@@ -98,7 +120,7 @@ Re-run the installer to refresh the bundles when skill content updates; you'll n
 # Target two clients in one run:
 npx @yugabytedb/meko-mcp --client claude-code,claude-desktop --local --yes
 
-# Target every supported client (claude-code, claude-desktop, cursor):
+# Target every supported client (claude-code, claude-desktop, cursor, codex, kiro):
 npx @yugabytedb/meko-mcp --client all --local --yes
 ```
 
@@ -108,7 +130,7 @@ Each client is installed sequentially. A failure on one does not abort the other
 
 ```bash
 npx @yugabytedb/meko-mcp \
-  --url https://your-mcp.mekodev.com/mcp \
+  --url https://mcp.mekodata.ai/mcp \
   --api-key "$MEKO_API_KEY" \
   --yes
 ```
@@ -121,7 +143,7 @@ The installer performs up to 5 steps (some are skippable via flags):
 |------|--------|------------------------|
 | 1 | Register MCP server | `claude mcp add meko <url> --transport http --scope user` (with `-H "Authorization: Bearer <key>"` for cloud) |
 | 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 plugin marketplace | `claude plugin marketplace add yugabyte/meko-mcp-server --scope user` |
+| 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 |
 
@@ -159,9 +181,16 @@ The canary used to do a `memory_add` → `memory_get_by_id` → `memory_delete_b
     ```
     This is **scoped to the Meko server block only** — it affects requests Codex makes to the Meko MCP server and nothing else (other MCP servers, other Codex traffic are untouched). The installer **merges** rather than clobbers: it reads whatever headers you already have — in either the inline `http_headers = { … }` form or the table form `[mcp_servers.meko.http_headers]` — keeps every one of them, and only *adds* a `User-Agent` if you don't already have one (a custom User-Agent is left exactly as you set it). If you had the table form, it's folded into the single inline line so there's never a conflicting duplicate definition. This holds **across a reinstall** too: re-registration deletes and rewrites the whole server block, so the installer snapshots your headers beforehand and merges them back. It **backs up `config.toml` to `config.toml.bak`** before writing. Local installs skip this (no WAF in front of `localhost`). Related: the capture-hook side of the same WAF issue is [#174](https://github.com/yugabyte/meko-mcp-server/issues/174).
   - **No project scope**: Codex has no per-project config. `--scope project --client codex` warns and degrades to user scope.
-  - **Auto-capture hooks**: when Codex hooks are available, the installer copies the Meko hook scripts to `~/.codex/meko-hooks/hooks-handlers/`, writes Meko lifecycle hooks to `~/.codex/hooks.json` pointing at that copy, and prunes stale Meko hook entries from deleted install paths. The scripts live under `$CODEX_HOME` (not the shipped package) on purpose: under `npx @yugabytedb/meko-mcp` the package unpacks into an ephemeral `~/.npm/_npx/<hash>/` cache dir that npx later garbage-collects, so a `hooks.json` pinned there would become a dangling `bash '<missing>'` and Codex would report `SessionStart hook (failed) — hook exited with code 127`. Copying under `$CODEX_HOME` gives the hook a home-dir-stable target; re-running the installer refreshes the copy and auto-heals any stale npx-pinned entry. `memory_search` still handles recall; capture is driven by the hooks (and, where hooks are unavailable, by AGENTS.md-prompted per-turn `conversation_add_message` posting that the server extracts memories from). Explicit `memory_add` is reserved for the narrow cases — the user says "remember this", a fact lives only in the assistant's output or a tool result, or a negated/corrected fact needs overwriting.
+  - **Auto-capture hooks**: the installer copies the Meko hook scripts to `~/.codex/meko-hooks/hooks-handlers/`, writes Meko lifecycle hooks to `~/.codex/hooks.json` pointing at that copy, and prunes stale Meko hook entries from deleted install paths. The scripts live under `$CODEX_HOME` (not the shipped package) on purpose: under `npx @yugabytedb/meko-mcp` the package unpacks into an ephemeral `~/.npm/_npx/<hash>/` cache dir that npx later garbage-collects, so a `hooks.json` pinned there would become a dangling `bash '<missing>'` and Codex would report `SessionStart hook (failed) — hook exited with code 127`. Copying under `$CODEX_HOME` gives the hook a home-dir-stable target; re-running the installer refreshes the copy and auto-heals any stale npx-pinned entry. `memory_search` still handles recall; capture is driven by the hooks (and, where hooks are unavailable, by AGENTS.md-prompted per-turn `conversation_add_message` posting that the server extracts memories from). Explicit `memory_add` is reserved for the narrow cases — the user says "remember this", a fact lives only in the assistant's output or a tool result, or a negated/corrected fact needs overwriting.
   - **API key storage** (security note): Codex's hooks.json schema rejects a top-level `env` block and provides no per-command env field. The installer writes `MEKO_MCP_URL` and (when supplied) `MEKO_API_KEY` to `~/.codex/meko-env.sh` at mode 0600 (user read/write only); each hook's `command` field sources that file before invoking bash, e.g. `. '/Users/you/.codex/meko-env.sh' && bash '/Users/you/.codex/meko-hooks/hooks-handlers/session-start.sh'`. The key never appears in process arguments, so `ps -ef` from another user can't lift it while a hook is running. Trust boundary is the same as `~/.aws/credentials` or `~/.netrc` — file-system permissions on the user's home directory. If your threat model precludes even that, install for the local Meko URL (no API key prompt), or skip hook installation by deleting the Meko entries from `~/.codex/hooks.json` and removing `~/.codex/meko-env.sh` and `~/.codex/meko-hooks/` after install.
   - **Restart Codex.app** after install so it picks up the new MCP server registration.
+- **Kiro (IDE + `kiro-cli`)** — one install configures both surfaces (they share the same config tree). `$KIRO_HOME` overrides the global root, matching how Kiro resolves every global surface.
+  - MCP config: `~/.kiro/settings/mcp.json` or `.kiro/settings/mcp.json`. Registered as a native remote server (`url` + `headers`), never via the `mcp-remote` stdio bridge. Because the file contains the bearer token, the adapter writes and reasserts mode 0600 — see [Kiro notes](#kiro-notes).
+  - Skills path: `~/.kiro/skills` or `.kiro/skills`. Kiro implements the same [Agent Skills](https://agentskills.io) standard our skills ship in, so they install by copy with no conversion. Packaged installs copy rather than symlink back into the ephemeral npm cache.
+  - Standalone hooks: `~/.kiro/hooks/meko-{session-start,user-prompt-submit,stop}.json` or the project equivalents, covering CLI 3.x and trusted IDE workspaces.
+  - Managed CLI 2.x agent: `~/.kiro/agents/meko-default.json` or `.kiro/agents/meko-default.json`, with inline `agentSpawn`, `userPromptSubmit`, and `stop` hooks. The installer preserves the previous `chat.defaultAgent` before selecting it.
+  - Stable capture runtime: `~/.kiro/hooks/meko-hooks/hooks-handlers/` or the project equivalent. `kiro-hook-env.json` stores the endpoint and optional API key at mode 0600.
+  - 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).
 
 ## CLI Reference
 
@@ -172,8 +201,8 @@ Usage:
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--client <list>` | Target client(s): one or more of `claude-code`, `claude-desktop`, `cursor`, `codex`. Comma-separated, or `all`. `codex` covers both the OpenAI Codex CLI and the Codex Desktop App (they share `~/.codex/config.toml`). | `claude-code` |
-| `--url <url>` | MCP server URL (from app.mekodev.com > Datapacks > Connect) | _(interactive prompt)_ |
+| `--client <list>` | Target client(s): one or more of `claude-code`, `claude-desktop`, `cursor`, `codex`, `kiro`. 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`). 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)_ |
 | `--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` |
@@ -189,6 +218,13 @@ Usage:
 | `-h`, `--help` | Show help message | |
 | `-v`, `--version` | Show version | |
 
+Capture health flags (durable outbox / recovery — Capture V2):
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--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. | `false` |
+
 Migrate subcommand flags (see [Migrate Existing Data](#migrate-existing-data) below for details):
 
 | Flag | Description | Default |
@@ -338,28 +374,66 @@ memory errs:  0                (failed memory_add calls; re-run with --force to
 
 ## Client Compatibility Matrix
 
-| Capability | Claude Code | Claude Desktop | Cursor | Codex (CLI + App) |
-|---|---|---|---|---|
-| One-command install | Yes | Yes | Yes | Yes |
-| MCP server registration | via `claude mcp add` | via `claude_desktop_config.json` merge using `mcp-remote` stdio bridge | via `.cursor/mcp.json` merge | via `codex mcp add` (CLI) or direct TOML write (App-only) |
-| Backup before config write | `.bak` on `~/.claude/settings.json` | `.bak` on `claude_desktop_config.json` | `.bak` on Cursor config | `.bak` on `~/.codex/config.toml` and `~/.codex/AGENTS.md` |
-| Automatic conversation capture | Yes (hooks) | **No** — see [issue #8](https://github.com/amiramm/meko-mcp-server/issues/8) | Yes (native hooks; first SessionStart may pause briefly while creating the Meko conversation) | **No** — Codex has no user-installable hooks; AGENTS.md prompts proactive memory tool calls instead |
-| Automatic memory persistence | Yes (hooks + skill) | Skill only (proactive `memory_add`) | Yes (hooks + skill) | Skill + AGENTS.md (proactive `memory_add`) |
-| Skill install | Plugin marketplace (automatic) | `.skill` bundle auto-built, user drags into app | Copy into `.cursor/skills` | Copy into `~/.agents/skills/meko-mcp-tools/` |
-| Uninstall | Full automatic | MCP entry removed; skill must be removed manually from app | MCP + hooks + skills cleaned up | MCP entry, skill dir, and AGENTS.md block all cleaned up |
+| Capability | Claude Code | Claude Desktop | Cursor | Codex (CLI + App) | Kiro (IDE + `kiro-cli`) |
+|---|---|---|---|---|---|
+| One-command install | Yes | Yes | Yes | Yes | Yes |
+| MCP server registration | via `claude mcp add` | via `claude_desktop_config.json` merge using `mcp-remote` stdio bridge | via `.cursor/mcp.json` merge | via `codex mcp add` (CLI) or direct TOML write (App-only) | via `~/.kiro/settings/mcp.json` merge (native remote MCP) |
+| Backup before config write | `.bak` on `~/.claude/settings.json` | `.bak` on `claude_desktop_config.json` | No `.bak` — additive JSON writes preserve unrelated MCP servers, hooks, and settings | `.bak` on `~/.codex/config.toml` and `~/.codex/AGENTS.md` | No `.bak` — the write is an additive merge that preserves other `mcpServers` entries |
+| Automatic conversation capture | Yes (hooks) | **No** — see [issue #8](https://github.com/amiramm/meko-mcp-server/issues/8) | Yes (native hooks; first SessionStart may pause briefly while creating the Meko conversation) | Yes (hooks) — `SessionStart` / `PreCompact` / `SessionEnd` written to `~/.codex/hooks.json`; the AGENTS.md block provides fallback instructions when hooks are unavailable | Yes — inline CLI 2.x plus standalone CLI 3.x/IDE hooks share Capture v2 |
+| Automatic memory persistence | Yes (hooks + skill) | Skill only (proactive `memory_add`) | Yes (hooks + skill) | Hooks + skill; AGENTS.md fallback when hooks are unavailable | Hooks + skill; conditional steering fallback when the hook marker is absent |
+| Skill install | Plugin marketplace (automatic) | `.skill` bundle auto-built, user drags into app | Copy into `.cursor/skills` | Copy into `~/.agents/skills/meko-mcp-tools/` | Copy into `~/.kiro/skills/` (native Agent Skills format) |
+| Uninstall | Full automatic | MCP entry removed; skill must be removed manually from app | MCP + hooks + skills cleaned up | MCP entry, skill dir, and AGENTS.md block all cleaned up | MCP entry plus installer-owned hooks, managed agent, private env, skills, and steering; pending outbox data is preserved |
+| `agent_id` used by skill | `claude_code:<repo>` per project (via SessionStart hook); cross-project facts go to `meko_agent` | `claude_desktop` | `cursor:<repo>` per project (via Cursor hook); cross-project facts go to `meko_agent` | `codex:<repo>` per project (via SessionStart hook); cross-project facts go to `meko_agent` | `kiro:<repo>` per project via hook capture; cross-project facts go to `meko_agent` |
+| Transport | HTTP only | HTTP (or stdio via hand-edited config) | HTTP only | HTTP (Codex's `bearer_token_env_var` model) | HTTP only |
+| Auth model | inline `Authorization: Bearer ...` header | inline header via `mcp-remote` | inline header | MCP server: env-var name reference (`MEKO_API_KEY` exported in shell or via `launchctl setenv`). Hooks: key written to `~/.codex/meko-env.sh` at mode 0600; each hook command sources the file before bash (no env block in Codex's hooks schema; see [Security](#security)). | inline `Authorization: Bearer ...` header (never `mcp-remote` — see note below) |
+| Project scope | Yes (`--scope project`) | No | Yes (`--scope project`) | No (warns and degrades to user scope) | Yes (`--scope project`) |
+| Deferred to a follow-up | — | `.mcpb` Desktop Extension packaging — see [issue #7](https://github.com/amiramm/meko-mcp-server/issues/7) | — | — | Tool-call/hidden-reasoning capture (not exposed by Kiro hook events) |
 
 Cursor previously had a hybrid hook mode that also wrote Claude-compatible hooks into `~/.claude/settings.json`. If you used that mode and now see duplicate `claude_code:*` Meko instructions in Cursor, remove the old Meko hook entries from `~/.claude/settings.json` unless you still use them for Claude Code.
-| `agent_id` used by skill | `claude_code:<repo>` per project (via SessionStart hook); cross-project facts go to `meko_agent` | `claude_desktop` | `cursor:<repo>` per project (via Cursor hook); cross-project facts go to `meko_agent` | Whatever the agent derives by following the meko-mcp-tools skill (no hook injects an agent_id; the AGENTS.md block defers to the skill) |
-| Transport | HTTP only | HTTP (or stdio via hand-edited config) | HTTP only | HTTP (Codex's `bearer_token_env_var` model) |
-| Auth model | inline `Authorization: Bearer ...` header | inline header via `mcp-remote` | inline header | MCP server: env-var name reference (`MEKO_API_KEY` exported in shell or via `launchctl setenv`). Hooks: key written to `~/.codex/meko-env.sh` at mode 0600; each hook command sources the file before bash (no env block in Codex's hooks schema; see [Security](#security)). |
-| Project scope | Yes (`--scope project`) | No | Yes (`--scope project`) | No (warns and degrades to user scope) |
-| Deferred to a follow-up | — | `.mcpb` Desktop Extension packaging — see [issue #7](https://github.com/amiramm/meko-mcp-server/issues/7) | — | Native `codex:<repo>` agent_id classification in capture.js |
+
+### Kiro notes
+
+**One adapter, both surfaces.** The Kiro IDE and `kiro-cli` read the same `mcpServers` config and the same skills directories, so `--client kiro` configures both. `kiro-cli` and `kiro-ide` are accepted as aliases. `$KIRO_HOME` is honored for the global config tree, matching how Kiro resolves every global surface.
+
+**Never use the `mcp-remote` bridge with Kiro.** Kiro speaks remote MCP natively, so the installer registers `{ url, headers }` directly.
+
+What is measured, against `https://mcp.mekodata.ai`:
+
+- `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.
+- Run directly, it fails at `registerClient` — the DCR POST — with `HTTP 403: Invalid OAuth error response … Raw body: <html>403 Forbidden</html>`. Its source builds `redirect_uri` as `http://${host}:${callbackPort}${callbackPath}`, defaulting to `localhost` and `/oauth/callback`.
+- Sending mcp-remote's exact registration body to `POST /register` reproduces it, and changing **only** the redirect host fixes it: loopback → `403 text/html` from `server: awselb/2.0`; `https://example.com/...` → `201 application/json` from `server: uvicorn`. So the block is at the AWS load balancer, before the app, and keys on the redirect host — not the scheme (`http://example.com` passes) and not the `client_id` (an unregistered one returns a helpful `400 JSON`).
+- Refused redirect hosts: `localhost`, `127.0.0.1`, `0.0.0.0`, RFC1918, `169.254.169.254`. Accepted: public hosts and private-use schemes. (`[::1]` and `127.1` also pass — the rule is not exhaustive.)
+- **This hits the Kiro IDE too, not just `kiro-cli`.** Both start a `http://localhost:<port>/oauth/callback` server, so OAuth fails identically on both surfaces. Verified against the installed IDE: with the installer's headers its MCP log shows `[meko] Connected`; remove the headers and change nothing else and it logs `HTTP 403 ... Raw body: <html>403 Forbidden</html>`, then closes the connection. Don't assume a GUI client is safe — what matters is the callback it registers, not whether it has a window.
+
+Confirmed on `kiro-cli` 2.18.1 itself. Its DCR registration is:
+
+```json
+{"client_name":"kiro","redirect_uris":["http://127.0.0.1:56459"],"application_type":"native", ...}
+```
+
+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.
+
+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).
+
+Header auth avoids the OAuth path entirely. `installer/test/clients-kiro.test.mjs` guards this.
+
+**Two hook generations coexist.** Kiro 2.18.1 CLI 2.x reads lowercase inline hooks from the selected custom agent, while CLI 3.x and IDE 1.x read [standalone PascalCase hooks](https://kiro.dev/docs/hooks/) from `hooks/`. The installer writes both formats and routes them to one handler. It creates a default-like `meko-default` agent for CLI 2.x, records and selects it, and restores the previous `chat.defaultAgent` on uninstall only when `meko-default` is still selected. Existing files at installer-owned names are treated as user-owned collisions and left untouched.
+
+The handler captures the exact user prompt exposed by `UserPromptSubmit`/`userPromptSubmit` and the exact final assistant response exposed by `Stop`/`stop`. Kiro does not expose tool calls or hidden reasoning through these events, so those are outside the capture boundary. Inline and standalone hooks may both deliver the same event; prompt hashes and stable turn IDs deduplicate them, including the initial prompt repeated after `agentSpawn`. If another prompt arrives before Stop, the prior turn receives the standard interrupted-response marker.
+
+Events are fsynced to a mode-0600 local JSONL journal before delivery. The handler initializes the shared Capture v2 session on spawn/start, launches a non-blocking drain on each Stop, and starts the normal recovery timer. Create/add failures remain queued; acknowledgements advance only through the existing validated Capture v2 protocol. Kiro's `session_id` is preferred; absent that, host PID plus working directory provides correlation. Project ownership is stable as `kiro:<repo>`, and these sessions appear in the normal `--capture-status` health view.
+
+IDE workspace hooks run only in trusted workspaces. The installer does not alter Kiro's trust decision. The steering file is therefore conditional: `MEKO_CAPTURE_SESSION_STARTED` means hooks are active and normal capture rules apply; without it, hooks may be disabled or untrusted, or CLI 2.x may be using another agent, so steering asks the agent to persist turns proactively. The file carries a `Managed by meko installer` marker and is removed only when owned by the installer.
+
+Uninstall removes only files carrying installer ownership markers: the three standalone hook files, managed agent, private hook environment/runtime, skills, and steering. It preserves user config and filename collisions, and deliberately leaves the Capture v2 event journal and pending outbox state so recovery can finish after a reinstall.
 
 ## Cloud vs Local
 
 | | Cloud Meko | Local Meko |
 |---|-----------|-----------|
-| **URL** | Provided by app.mekodev.com > Datapacks > Connect | `http://localhost:8000/mcp` |
+| **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 |
 | **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 |
@@ -384,6 +458,9 @@ The installer auto-detects cloud vs local based on the URL: any URL containing `
 - **OpenAI Codex (CLI + Desktop App)**
   - MCP-server bearer reference — `~/.codex/config.toml` stores `bearer_token_env_var = "MEKO_API_KEY"`, **not** the key itself. The runtime env (shell rc or `launchctl setenv`) supplies the value.
   - Hook commands — Codex's `~/.codex/hooks.json` schema rejects a top-level `env` block and provides no per-command env field, so the installer writes `MEKO_API_KEY` to `~/.codex/meko-env.sh` at **mode 0600** (user read/write only). Each Meko hook's `command` field sources that file before invoking bash, so the key never appears in process arguments — `ps -ef` from another user can't lift it while the hook runs. Same trust boundary as `~/.aws/credentials` or `~/.netrc` (file-system permissions on the user's home directory). To opt out: install for the local Meko URL (no key prompt), or skip Codex hook installation by deleting the Meko entries from `~/.codex/hooks.json` and removing `~/.codex/meko-env.sh` and `~/.codex/meko-hooks/` after install. The hook scripts themselves are copied to `~/.codex/meko-hooks/hooks-handlers/` (a home-dir-stable location) rather than referenced from the shipped package, so `npx`'s cache garbage-collection can't leave the hook pointing at a deleted script (which would fail with `code 127`).
+- **Kiro (IDE + `kiro-cli`)**
+  - API key header — stored in `~/.kiro/settings/mcp.json` (or `.kiro/settings/mcp.json` for project scope) under `mcpServers.<name>.headers.Authorization`. The adapter forces the file to **mode 0600** on registration and removal rewrites.
+  - Hook runtime — the endpoint and optional API key are also stored in `kiro-hook-env.json` at **mode 0600** so inline and standalone hooks can authenticate without putting the key in their command strings.
 
 **How credentials are protected:**
 
@@ -396,7 +473,7 @@ The installer auto-detects cloud vs local based on the URL: any URL containing `
 
 **Backups:**
 
-Before modifying any config file the installer touches, it creates a `.bak` copy alongside the original (e.g. `~/.claude/settings.json.bak`, `~/.codex/config.toml.bak`, `~/.codex/AGENTS.md.bak`). The merge is additive: existing keys are preserved unless explicitly overridden.
+Adapters that use backup-aware merge helpers create a `.bak` copy alongside the original (for example `~/.claude/settings.json.bak`, `~/.codex/config.toml.bak`, or `~/.codex/AGENTS.md.bak`). The support matrix above lists backup behavior per client. Cursor and Kiro use additive JSON writes but do not create `.bak` files; they preserve unrelated settings and user-owned collisions instead.
 
 ## Upgrading
 
@@ -481,13 +558,13 @@ create-meko-setup --version
 
 ### Rollback
 
-If an upgrade breaks something, restore the `.bak` backups the installer wrote before its changes:
+For Claude Code, Claude Desktop, or Codex, restore the relevant `.bak` file written before the change. For example, to restore Claude Code settings:
 
 ```bash
 cp ~/.claude/settings.json.bak ~/.claude/settings.json
 ```
 
-See the Security section above for the full list of backup locations across Claude Code, Claude Desktop, and Cursor.
+See the Security section above for the exact backup locations. Cursor and Kiro do not write `.bak` files; rerun or uninstall the relevant adapter to remove installer-owned entries while preserving unrelated settings and user-owned files.
 
 ## Troubleshooting
 
@@ -505,6 +582,31 @@ which claude
 claude --version
 ```
 
+### MCP server `meko` already exists in the user config
+
+```
+[1/4] Failed to register MCP server.
+MCP server meko already exists in the user config
+Install for claude-code failed: MCP server registration failed.
+```
+
+Claude Code's `claude mcp add` refuses to overwrite an existing registration, so a re-run — or a previous install that failed partway through — aborts at step 1. Remove the stale entry, then re-run the installer:
+
+```bash
+claude mcp list                     # confirm the "meko" entry and which scope it is on
+claude mcp remove meko --scope user # or --scope local / --scope project, matching what `list` showed
+claude mcp list                     # confirm it is gone
+npx @yugabytedb/meko-mcp@latest     # re-run the installer
+```
+
+If `claude mcp remove` errors or you want to edit the file directly, the user-scope config lives at `~/.claude.json` — open it, find the `"mcpServers"` block, and delete the `"meko": { ... }` entry. Claude Desktop and Claude Code keep **separate** configs, so a clean Desktop install does not imply a clean Code install.
+
+Logs worth collecting before filing a bug:
+
+- **Installer log** — `ls -lt ~/.meko*/logs 2>/dev/null; ls -lt /tmp/meko-installer* 2>/dev/null` — share the newest file.
+- **Claude Code MCP log** (macOS) — `ls -lt ~/Library/Caches/claude-cli-nodejs/*/mcp-logs-meko/ 2>/dev/null` — most recent `*.txt` shows the registration attempt and any stderr from the spawned process.
+- **Current config snippet** — `grep -A 20 '"meko"' ~/.claude.json` — confirms what state Claude Code was in when the install was attempted.
+
 ### Connection refused
 
 ```
@@ -533,11 +635,48 @@ The MCP server is enforcing strict Streamable HTTP compliance: clients must adve
 
 ### Authentication failure (401 / 403)
 
-```
+Check the response shape first — it tells you which layer rejected you, and the
+two causes have nothing to do with each other.
+
+**A JSON 401 means the server saw your request and refused the credential.**
+
+```output
 Server returned 401. Verify your API key is correct and has not expired.
 ```
 
-- Confirm the API key at app.mekodev.com > Datapacks > Connect.
+Work through the API-key checks below.
+
+**An HTML 403 means a load balancer rejected the request before it reached the
+server.** You'll see an unparseable error, often wrapped in a JSON parse failure
+because the client expected JSON:
+
+```output
+HTTP 403: Invalid OAuth error response: SyntaxError: Unexpected token '<',
+"<html>..." is not valid JSON. Raw body: <html>403 Forbidden</html>
+```
+
+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.** The WAF refuses any `redirect_uri`
+  pointing at an internal host, so dynamic client registration fails for any
+  client that registers such a callback, including IDEs. Use API-key auth
+  instead. 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
+  [#245](https://github.com/yugabyte/meko-mcp-server/issues/245).
+
+**A stale key can surface as the HTML 403, not the JSON 401.** If your key is
+expired, the server returns 401, the client quietly falls back to OAuth, and the
+registration attempt returns the HTML 403. So verify your key before concluding
+that OAuth is broken.
+
+API-key checks:
+
+- Confirm the API key at cloud.mekodata.ai > Datapacks > Connect.
 - 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.
@@ -596,7 +735,7 @@ After the installer writes `claude_desktop_config.json`, **quit and relaunch** C
    ```json
    "meko": {
      "command": "npx",
-     "args": ["-y", "mcp-remote", "<url>", "--transport", "http-only", "--header", "User-Agent:meko-mcp-installer/1.0"]
+     "args": ["-y", "mcp-remote@0.1.38", "<url>", "--transport", "http-only", "--header", "User-Agent:meko-mcp-installer/1.0"]
    }
    ```
    If you see a `"url"` field at the top level instead, re-run the installer to rewrite it.
@@ -633,6 +772,17 @@ This reverses installer-managed changes for the selected client:
 
 Each step is safe if the component was already removed -- the uninstaller logs a warning and continues.
 
+### Claude Desktop: which artifact, and why the UI can't remove it
+
+Claude Desktop can be connected to Meko in two different ways, and they are removed differently:
+
+- **Config-file server** — the `mcpServers.<name>` entry this installer writes into `claude_desktop_config.json`. Claude Desktop shows it with a **"Local dev"** badge; that badge is just Desktop's label for *any* config-file server, **not** a Meko setting. It is **not** removable from the Desktop UI — remove it with the uninstall flow:
+  ```bash
+  npx @yugabytedb/meko-mcp --client claude-desktop --uninstall
+  ```
+  This removes the `mcpServers.<name>` entry (via `removeKeys(..., ['mcpServers.<name>'])`). If you installed under a non-default server name, pass `--name <name>`. Note: running bare `npx @yugabytedb/meko-mcp` re-runs the **install** flow and re-adds the entry — always include `--uninstall`. The uninstall strips only the MCP server entry; the imported Desktop **skill** must still be removed manually via **Settings > Extensions**.
+- **OAuth Connector** — added by URL under **Settings > Connectors**. This is UI-managed and **is** removable directly from the Desktop UI; no CLI needed.
+
 Use `--verbose` for detailed output during uninstall:
 
 ```bash
@@ -661,7 +811,7 @@ node installer/bin/create-meko-setup.mjs --uninstall --verbose
 
 ### Prerequisites
 
-- Node.js >= 18.0.0 (required for `util.parseArgs` and `node:test`)
+- Node.js >= 20.18.1 (the Claude Desktop `mcp-remote` bridge's `undici@^7` dependency requires it; `util.parseArgs` and `node:test` are also used)
 - No `npm install` needed -- zero external dependencies
 
 ### Project Structure
@@ -714,7 +864,7 @@ npm run test:integration
 
 # Cloud round-trip tests (opt-in; regression coverage for MEKO-20).
 # Requires credentials in the shell:
-export MEKO_TEST_CLOUD_URL=https://<your-mcp>.mekodev.com/mcp
+export MEKO_TEST_CLOUD_URL=https://mcp.mekodata.ai/mcp
 export MEKO_TEST_API_KEY=<your-cloud-api-key>
 npm run test:integration:cloud
 
@@ -740,7 +890,7 @@ branch.
 ### Design Principles
 
 - **Zero external dependencies** -- Node.js built-ins only (`fs`, `path`, `readline`, `child_process`, `url`, `http`, `https`, `os`, `node:test`, `node:assert`), matching the pattern of `capture.js`.
-- **Non-destructive** -- Creates `.bak` backups before modifying settings.
+- **Non-destructive** -- Preserves unrelated settings and user-owned files, and creates `.bak` backups where the client adapter supports them (see the support matrix).
 - **Additive merges** -- New env vars are added without overwriting existing unrelated keys.
 - **Graceful failures** -- Non-critical errors (plugin already exists) warn and continue; only missing prerequisites cause hard failures.
 - **API key safety** -- Never logged, always redacted in output.

package/assets/hooks-handlers/codex-session-end.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+#
+# Codex SessionEnd hook.
+#
+# Codex caps SessionEnd hooks at three seconds. The foreground invocation
+# therefore enqueues via the shared terminal-handoff worker and exits
+# immediately with `{}`. The worker drains lifecycle=closing and may retry
+# until MEKO_WORKER_MAX_AGE_SECONDS, leaving the outbox pending afterward.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+exec node "$SCRIPT_DIR/lib/terminal-handoff.js" enqueue

package/assets/hooks-handlers/cursor-session-start.sh

@@ -2,6 +2,8 @@
 
 # Cursor native SessionStart hook. Cursor only documents context injection from
 # SessionStart, so this wrapper returns the Meko context synchronously.
+# Also spawns the checkpoint/recovery daemon (same as Claude/Codex) so Cursor
+# sessions get live checkpoints and participate in self-draining recovery.
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
@@ -39,4 +41,20 @@ load_cursor_hook_env() {
 }
 
 load_cursor_hook_env
-MEKO_HOOK_CLIENT=cursor node "$SCRIPT_DIR/lib/capture.js" session-start
+
+HOOK_INPUT="$(cat)"
+TRANSCRIPT_PATH="$(printf '%s' "$HOOK_INPUT" | node -e '
+  const d = JSON.parse(require("fs").readFileSync(0,"utf-8"));
+  const p = d.transcript_path || (d.hookSpecificInput||{}).transcript_path || "";
+  process.stdout.write(p);
+' 2>/dev/null)"
+
+if [ -n "$TRANSCRIPT_PATH" ]; then
+  MEKO_LOG_DIR="${MEKO_WATERMARK_DIR:-$HOME/.claude/meko-capture}"
+  mkdir -p "$MEKO_LOG_DIR"
+  nohup node "$SCRIPT_DIR/lib/checkpoint-timer.js" "$TRANSCRIPT_PATH" \
+    </dev/null >/dev/null 2>>"$MEKO_LOG_DIR/timer.log" &
+  disown 2>/dev/null || true
+fi
+
+printf '%s' "$HOOK_INPUT" | MEKO_HOOK_CLIENT=cursor node "$SCRIPT_DIR/lib/capture.js" session-start