@yugabytedb/meko-mcp 1.0.8 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Meko Setup Installer
 
-A zero-dependency Node.js CLI that configures [Meko MCP Server](https://mekodata.netlify.app/) for Claude Code, Claude Desktop, and Cursor 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, 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.
 
 Reduces manual setup to a single command.
 
@@ -18,7 +18,7 @@ The installer is path-agnostic — the three forms below are equivalent. Pick th
 | Repo clone, from repo root | `node installer/bin/create-meko-setup.mjs [options]` |
 | Repo clone, from `installer/` | `node bin/create-meko-setup.mjs [options]` |
 
-Claude Desktop install (issue [#7](https://github.com/amiramm/meko-mcp-server/issues/7)) still requires a repo clone — the `.skill` packaging script isn't bundled. All other clients work from the npm tarball without a checkout.
+Claude Desktop has two install paths: a one-click `.mcpb` Desktop Extension downloaded from GitHub Releases, and the scripted installer here (run via `npx` or from a clone) — only the latter also installs the agent skill bundle. See [Claude Desktop install](#claude-desktop-install) below for the full comparison.
 
 **Interactive (recommended for first-time users):**
 
@@ -40,19 +40,57 @@ npx @yugabytedb/meko-mcp --local --yes
 npx @yugabytedb/meko-mcp --client cursor --local --scope project --yes
 ```
 
-**Claude Desktop install (local, from a repo clone):**
+**Claude Desktop install:**
 
-Claude Desktop supports two install paths — pick one per machine:
+Claude Desktop has two install paths — pick based on whether you want the agent skill (the behavioral guide that teaches the agent *when* to call Meko tools, like proactive `memory_add`):
 
-**Option A — Desktop Extension (`.mcpb`), one-click.** Download `meko-<version>.mcpb` from the [GitHub Releases page](https://github.com/amiramm/meko-mcp-server/releases) and drag it onto **Claude Desktop > Settings > Extensions > Install from file**. You'll be prompted for your Meko MCP URL and API key in the Settings UI, and that's it. Best for non-technical users. See [`mcpb/README.md`](../mcpb/README.md) for what's in the bundle. Prerequisite: Node 18+ on PATH (the bundle launches `npx mcp-remote` under the hood).
+| | Option A: `.mcpb` Desktop Extension | Option B: `create-meko-setup` installer |
+|---|---|---|
+| Installs MCP server | Yes | Yes |
+| Installs the agent skill (behavioral guide) | **No** | **Yes** |
+| Repo clone needed | No | No (works via `npx`); clones also work |
+| Best for | Non-technical users; quickest path to a working MCP connection | Anyone who wants the skill that teaches the agent *when* to call Meko tools |
+| Auto-capture of conversations/memories | No (see [issue #8](https://github.com/amiramm/meko-mcp-server/issues/8)) | Skill-driven only — the agent is prompted to call `memory_add` proactively, but it's not as reliable as Claude Code hooks |
+
+You can also combine both: install via `.mcpb` for the MCP wiring, then run Option B to add the skill bundle. If you re-run the Option B installer on top of an `.mcpb` install, it detects the existing entry and prompts before overwriting `mcpServers.meko`.
+
+**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`).
+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.
+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.
 
-**Option B — `create-meko-setup` installer.** Use this when you want a scripted / repeatable install, or when you need the `.skill` bundle built at the same time:
+**Option B — `create-meko-setup` installer:**
+
+Run via `npx` (no clone needed) — pick the form that matches the table at the top of this section. From a repo clone:
 
 ```bash
 node installer/bin/create-meko-setup.mjs --client claude-desktop --local --yes
 ```
 
-Builds a `.skill` bundle at `skills/meko-mcp-tools-desktop.skill`. Drag it onto Claude Desktop (or import via Settings > Extensions) once and restart the app. The installer also merges `mcpServers.meko` into `claude_desktop_config.json`. If it detects that Meko was previously installed via the `.mcpb` path (Option A), it flags the entry and prompts before overwriting so you don't end up with two conflicting configs.
+Or via npm without a clone:
+
+```bash
+npx @yugabytedb/meko-mcp --client claude-desktop --local --yes
+```
+
+This does two things:
+
+1. Merges `mcpServers.meko` into `claude_desktop_config.json` (backed up to `.bak`).
+2. Builds the `meko-mcp-tools-desktop.skill` bundle and prints its absolute path. The location depends on how you invoked the installer — under the npm package's asset root for `npx`, or under `skills/` in your clone.
+
+Then, **once per machine**:
+
+1. Open the path that the installer printed (look for the `Built Meko skill bundle: ...` log line).
+2. Drag `meko-mcp-tools-desktop.skill` onto the Claude Desktop window — or import it via **Settings > Extensions > Install from file**.
+3. Quit and relaunch Claude Desktop.
+4. Verify the skill loaded: ask *"Which Meko skills do you have available?"* — the agent should mention `meko-mcp-tools-desktop`.
+
+Re-run the installer to refresh the bundle when skill content updates; you'll need to re-drag the rebuilt `.skill` to pick up changes.
 
 **Install on multiple clients at once:**
 
@@ -82,10 +120,18 @@ The installer performs up to 5 steps (some are skippable via flags):
 | Step | Action | Command / File Modified |
 |------|--------|------------------------|
 | 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 |
+| 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` |
 | 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 |
+| 5 | Validate setup | Config check via `claude mcp list`, MCP `initialize` handshake, `tools/list` verification, and a canary `datapack_list` call |
+
+### 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.
+
+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.
+
+`--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).
 
 **Files modified (depends on `--client`):**
 
@@ -100,6 +146,15 @@ The installer performs up to 5 steps (some are skippable via flags):
   - MCP config: `~/.cursor/mcp.json` or `.cursor/mcp.json`
   - Hooks config: `~/.cursor/hooks.json` or `.cursor/hooks.json` (native mode)
   - Skills path: `~/.cursor/skills` or `.cursor/skills`
+- **OpenAI Codex (CLI + Desktop App)** — one install configures both surfaces (they share `~/.codex/`).
+  - MCP config: `~/.codex/config.toml` (TOML; `[mcp_servers.<name>]` block).
+  - Skills path: `~/.agents/skills/meko-mcp-tools/` (the shared agent-skills convention).
+  - System prompt: `~/.codex/AGENTS.md` (a Meko-managed sentinel block is upserted; user content outside the fence is preserved).
+  - **Cloud auth (MCP server)**: Codex's TOML stores `bearer_token_env_var = "MEKO_API_KEY"` rather than the key itself. You must export `MEKO_API_KEY` in your shell before launching Codex. The installer offers (interactively, never with `--yes`) to append the export line to your shell rc (`~/.zshrc` / `~/.bashrc` / `~/.config/fish/config.fish`). On macOS, when the desktop app is detected and an API key is supplied, the installer runs `launchctl setenv MEKO_API_KEY ...` so Codex.app launched from Finder/Dock can authenticate in the current login session.
+  - **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 writes Meko lifecycle hooks to `~/.codex/hooks.json` and prunes stale Meko hook entries from deleted install paths. Memory persistence still also works via the model proactively calling `memory_search` / `memory_add` (the AGENTS.md block prompts this).
+  - **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 '/.../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` after install.
+  - **Restart Codex.app** after install so it picks up the new MCP server registration.
 
 ## CLI Reference
 
@@ -110,15 +165,16 @@ Usage:
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--client <list>` | Target client(s): one or more of `claude-code`, `claude-desktop`, `cursor`. Comma-separated, or `all` | `claude-code` |
+| `--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)_ |
-| `--api-key <key>` | API key for Cloud Meko authentication | _(interactive prompt or `$MEKO_API_KEY` env)_ |
+| `--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` |
 | `--name <name>` | MCP server name in config | `meko` |
-| `--cursor-hook-mode <mode>` | Cursor hook strategy: `native`, `claude-compat`, `hybrid` | `hybrid` |
+| `--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` |
 | `--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` |
@@ -149,9 +205,9 @@ After installing Meko, `--migrate` seeds your new datapack with the conversation
 |---|---|---|
 | Claude Code transcripts | `~/.claude/projects/<slug>/<uuid>.jsonl` | One Meko conversation (one Langfuse trace) per session; one paired user↔assistant turn per message pair. |
 | Cursor transcripts | `~/.cursor/projects/<name>/agent-transcripts/<uuid>/*.jsonl` | Same — one conversation per session, one paired turn per user↔assistant round. |
-| User-scope CLAUDE.md | `~/.claude/CLAUDE.md` | One memory per top-level `# ` section (agent = `claude-code:user`). |
-| Project-scope CLAUDE.md | `<projectCwd>/.claude/CLAUDE.md` | One memory per top-level `# ` section (agent = `claude-code:<slug>`). |
-| Indexed project memories | `~/.claude/projects/<slug>/memory/*.md` | One memory per file; YAML frontmatter (`name`, `description`, `type`) is preserved in metadata. |
+| User-scope CLAUDE.md | `~/.claude/CLAUDE.md` | One memory per top-level `# ` section (`agent_id = "meko_agent"` — the cross-project common bucket — with `metadata.scope = "user"`). |
+| Project-scope CLAUDE.md | `<projectCwd>/.claude/CLAUDE.md` | One memory per top-level `# ` section (`agent_id = "claude_code:<repo-basename>"`, `metadata.scope = "project"`, `metadata.cwd = <project path>`). |
+| Indexed project memories | `~/.claude/projects/<slug>/memory/*.md` | One memory per file (`agent_id = "claude_code:<repo-basename>"`); YAML frontmatter (`name`, `description`, `type`) is preserved in metadata. |
 
 Project `cwd` is derived by reading the `cwd` field from a real session file in each slug directory — never by reverse-slugging the directory name, which loses `.` and `-` in component names.
 
@@ -227,7 +283,7 @@ status:       running         (pending → running → done | failed | stopped)
 scope:        user
 started:      2026-04-29T00:09:12.673Z
 finished:     (in progress)
-current:      claude-code:-Users-.../meko-test / a2f6a1d6-...  (<adapter>:<source-session> / <message-id>)
+current:      agent / a2f6a1d6-...  (agent_id / source-session-uuid)
 sessions:     76 / 111        (processed / discovered)
 messages:     674
 memory pairs: 674              (memory_add from Mem0 extractor)
@@ -260,31 +316,35 @@ memory errs:  0                (failed memory_add calls; re-run with --force to
 
 - Per-run logs: `~/.meko/migrate/<run-id>/log.ndjson` (one JSON object per line). `tail -f | jq .` is a reasonable debug loop.
 - Per-run progress snapshot: `~/.meko/migrate/<run-id>/progress.json` (what `--migrate-status` reads).
-- Durable state: `~/.meko/migrate/state.json` tracks per-session checkpoints (`conversationId`, `messagesSent`, `lastUuid`, `status`) and per-memory content hashes. A re-run skips sessions marked `done` and memories whose body hash is unchanged. A partial session resumes from `lastUuid + 1`.
+- Durable state: `~/.meko/migrate/state/<datapack-key>.json` tracks per-session checkpoints (`conversationId`, `messagesSent`, `lastUuid`, `status`) and per-memory content hashes, **scoped per destination datapack**. A re-run skips sessions marked `done` and memories whose body hash is unchanged. A partial session resumes from `lastUuid + 1`.
+- **Per-datapack scoping**: the datapack key is the UUID segment of the MCP URL (`https://<uuid>.mcp.mekodev.com/mcp` → `<uuid>`), or a stable 16-char sha256 prefix for non-UUID URLs (e.g. `http://localhost:8000/mcp`). Switching datapacks produces completely independent state — migrating into a fresh datapack never falsely treats sessions as already-done just because an earlier run populated a different one. `--migrate-status` prints the `datapack:` key of the latest run so you can tell at a glance which state it belongs to.
+- Back-compat for the legacy layout: migrations created before this change wrote to a single `~/.meko/migrate/state.json`. On the first run after upgrading, if `state/` is empty and `state.json` exists, the installer asks (or, under `--yes` / CI, silently accepts) "treat the legacy state as belonging to the current datapack" and copies `state.json` → `state/<current-key>.json`. The legacy file is kept on disk in case you roll back the installer.
 - Server-side dedup: `conversation_add_message` gets a deterministic `seed = sha256(agentId + ":" + sessionUuid + ":" + messageUuid)` so partial-run overlap doesn't create duplicate messages.
-- `--force` wipes resume state and re-issues every MCP call (useful for testing or after a server-side wipe).
+- `--force` wipes the **current datapack's** resume state and re-issues every MCP call for it. Other datapacks' state files are untouched. If you only want to re-migrate into a new datapack, just point `--url` at the new one — no `--force` needed.
 
 ### 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 — would need an S3 upload path and `knowledgebase_trigger_index_creation` wiring.
-- Transcripts from other coding agents (Aider, Continue.dev, Windsurf, Codex CLI). Claude Code + Cursor only.
+- Transcripts from other coding agents (Aider, Continue.dev, Windsurf, Codex). Claude Code + Cursor only.
 - `user_id` is left null on every call (the server fills it from the API key). Multi-user routing is a follow-up.
 
 ## Client Compatibility Matrix
 
-| Capability | Claude Code | Claude Desktop | Cursor |
-|---|---|---|---|
-| One-command install | 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 |
-| Backup before config write | `.bak` on `~/.claude/settings.json` | `.bak` on `claude_desktop_config.json` | `.bak` on Cursor config |
-| Automatic conversation capture | Yes (hooks) | **No** — see [issue #8](https://github.com/amiramm/meko-mcp-server/issues/8) | Yes (hybrid hook mode) |
-| Automatic memory persistence | Yes (hooks + skill) | Skill only (proactive `memory_add`) | Yes (hooks + skill) |
-| Skill install | Plugin marketplace (automatic) | `.skill` bundle auto-built, user drags into app | Copy into `.cursor/skills` |
-| Uninstall | Full automatic | MCP entry removed; skill must be removed manually from app | MCP + hooks + skills cleaned up |
-| `agent_id` used by skill | `claude_code` | `claude_desktop` | `claude_code` |
-| Transport | HTTP only | HTTP (or stdio via hand-edited config) | HTTP only |
-| Deferred to a follow-up | — | `.mcpb` Desktop Extension packaging — see [issue #7](https://github.com/amiramm/meko-mcp-server/issues/7) | — |
+| 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) | Yes (hooks via `~/.codex/hooks.json`) |
+| Automatic memory persistence | Yes (hooks + skill) | Skill only (proactive `memory_add`) | Yes (hooks + skill) | Yes (hooks + skill + AGENTS.md) |
+| 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 |
+| `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` | `claude_code:<repo>` per project (capture.js still classifies non-cursor hooks as the `claude_code` client; native `codex:<repo>` derivation is a follow-up); 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) |
+| 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 |
 
 ## Cloud vs Local
 
@@ -302,10 +362,19 @@ The installer auto-detects cloud vs local based on the URL: any URL containing `
 
 ## Security
 
-**Where credentials are stored:**
+**Where credentials are stored** (per client; all files inherit standard user-only filesystem permissions):
 
-- **API key header** -- stored in `~/.claude.json` (MCP server config, managed by `claude mcp add`). Readable only by the current user.
-- **`MEKO_API_KEY` env var** -- written to `~/.claude/settings.json` so lifecycle hooks can authenticate with the MCP server. This file has standard user-only filesystem permissions.
+- **Claude Code**
+  - API key header — stored in `~/.claude.json` (MCP server config, managed by `claude mcp add`).
+  - `MEKO_API_KEY` env var — written to `~/.claude/settings.json` under `env` so lifecycle hooks can authenticate with the MCP server.
+- **Claude Desktop**
+  - `MEKO_API_KEY` env var — written to `claude_desktop_config.json` under `mcpServers.<name>.env`. The header itself uses `${MEKO_API_KEY}` interpolation in `args`, so the key value lives only in the `env` block.
+- **Cursor**
+  - API key header — stored in `~/.cursor/mcp.json` (or `.cursor/mcp.json` for project scope) under `mcpServers.<name>.headers.Authorization`.
+  - `MEKO_API_KEY` env var — written to `~/.cursor/hooks.json` (native hook mode) and/or `~/.claude/settings.json` (claude-compat hook mode) under `env` so lifecycle hooks can authenticate.
+- **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` after install.
 
 **How credentials are protected:**
 
@@ -313,11 +382,103 @@ The installer auto-detects cloud vs local based on the URL: any URL containing `
 - `--dry-run` mode redacts the key in displayed commands (shown as `<set>`).
 - The API key is never logged to stdout or stderr during normal operation.
 - Interactive mode uses masked input (echoes `*` characters) when prompting for the API key.
-- The `MEKO_API_KEY` env var fallback means the key does not need to appear in shell history -- set it in your shell profile or CI secrets.
+- The `MEKO_API_KEY` env var fallback means the key does not need to appear in shell history — set it in your shell profile or CI secrets.
+- During Codex installs, the installer emits a `warn`-level log line confirming where the API key has been written.
 
 **Backups:**
 
-Before modifying `~/.claude/settings.json`, the installer creates a `.bak` copy at `~/.claude/settings.json.bak`. The merge is additive: existing keys are preserved unless explicitly overridden.
+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.
+
+## Upgrading
+
+There is no separate upgrade command — re-running the installer is the upgrade mechanism. The steps below cover the canonical paths and what to expect.
+
+### Upgrading via `npx` (recommended)
+
+```bash
+npx @yugabytedb/meko-mcp@latest
+```
+
+The `@latest` tag is load-bearing. `npx` aggressively caches the installer tarball based on semver resolution, so plain `npx @yugabytedb/meko-mcp` can silently re-run a stale cached copy and appear to do nothing. `@latest` forces a registry lookup and pulls the newest published version. This applies to every `npx @yugabytedb/meko-mcp ...` example earlier in this README — append `@latest` whenever you intend to upgrade rather than re-run the same version.
+
+### Upgrading a globally-installed copy
+
+If you installed via `npm install -g @yugabytedb/meko-mcp`, the `npx` path above will not touch the global copy. Update the global package first, then re-run:
+
+```bash
+npm update -g @yugabytedb/meko-mcp
+create-meko-setup
+```
+
+### What a re-run actually does
+
+Re-running the installer is idempotent but not inert. A re-run:
+
+- Overwrites the `env` block in `~/.claude/settings.json` (with a `.bak` backup — see the Security section above for backup semantics and locations).
+- Prunes stale Meko hook entries in `settings.json.hooks` that reference a prior install path (e.g., a frozen `capture.js` from an old `npx` cache or homebrew-global copy). The current install's hook entries — whether they come from the plugin (`${CLAUDE_PLUGIN_ROOT}/...`) or an absolute path matching the current `hooks-handlers/` root — are preserved. Non-Meko hooks in the same arrays are untouched.
+- Rewrites the Cursor skill directory and hooks config if `--client cursor` is targeted.
+- Auto-updates the skills plugin if it's already installed (via `claude plugin update meko-agent-skills@meko-agent-skills`), otherwise installs it. See "Updating the skills plugin" below.
+- Rebuilds the Claude Desktop `.skill` bundle if `--client claude-desktop` is targeted. You must re-drag the rebuilt bundle into Claude Desktop to pick up the new skill content.
+
+### 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
+
+```bash
+claude plugin update meko-agent-skills@meko-agent-skills --scope <scope>
+```
+
+using the qualified `plugin@marketplace` form required by Claude Code CLI 2.1.x. Older CLIs that don't know `plugin update` fall back to an uninstall-then-install dance to achieve the same refresh. You can still run the update manually if you want to bypass the installer:
+
+```bash
+claude plugin update meko-agent-skills@meko-agent-skills
+```
+
+#### Inside an active Claude Code session
+
+If you're already in a session and want to pull the latest skill content without exiting:
+
+```
+/plugin marketplace update meko-agent-skills
+/reload-plugins
+```
+
+The first command refetches the marketplace's source and rebuilds the plugin cache; the second activates the new content without restarting. Run `/doctor` afterward to confirm there are no plugin load errors.
+
+#### Enabling auto-update so future skill changes land automatically
+
+Auto-update is **per-marketplace and disabled by default for third-party marketplaces** (only Anthropic-official marketplaces auto-update out of the box). To opt in:
+
+1. Open the in-session `/plugin` command, switch to the **Marketplaces** tab, select `meko-agent-skills`, and toggle **Enable auto-update**.
+2. Or set it directly in your settings file (`~/.claude/settings.json` for user scope, or a project's `.claude/settings.json`):
+
+   ```json
+   {
+     "extraKnownMarketplaces": {
+       "meko-agent-skills": {
+         "autoUpdate": true
+       }
+     }
+   }
+   ```
+
+Once enabled, Claude Code refreshes the marketplace and pulls the latest plugin version on each session start. There's no global "auto-update everything" switch — opt in per marketplace.
+
+### Checking your installed version
+
+```bash
+create-meko-setup --version
+```
+
+### Rollback
+
+If an upgrade breaks something, restore the `.bak` backups the installer wrote before its changes:
+
+```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.
 
 ## Troubleshooting
 
@@ -342,14 +503,25 @@ Connection refused. Is the MCP server running?
 For local Meko, ensure `docker compose up -d` has started the stack.
 ```
 
-For local setups, confirm the stack is running and the MCP endpoint is accessible:
+For local setups, confirm the stack is running and the MCP endpoint is accessible. Note that the `Accept` header **must** advertise both `application/json` and `text/event-stream` per the MCP Streamable HTTP spec — sending only one yields HTTP 406:
 
 ```bash
 curl -s http://localhost:8000/mcp -X POST \
   -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
   -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'
 ```
 
+For cloud, swap the URL and add `-H "Authorization: Bearer $MEKO_API_KEY"`.
+
+### HTTP 406 Not Acceptable
+
+```
+Server returned HTTP 406: ... "Client must accept both application/json and text/event-stream"
+```
+
+The MCP server is enforcing strict Streamable HTTP compliance: clients must advertise both content types in their `Accept` header. The installer does this automatically; if you see this error, you're likely on an older installer release. Upgrade with `npx @yugabytedb/meko-mcp@latest`.
+
 ### Authentication failure (401 / 403)
 
 ```
@@ -358,6 +530,8 @@ Server returned 401. Verify your API key is correct and has not expired.
 
 - Confirm the API key at app.mekodev.com > 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.
 - Re-run the installer interactively to re-enter the key.
 
 ### Plugin marketplace already registered
@@ -384,10 +558,10 @@ cp ~/.claude/settings.json.bak ~/.claude/settings.json
 ### Missing core tools
 
 ```
-Missing core tools: memory_search, conversation_create. Found 0 tool(s) total.
+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`, `conversation_create`, `db_summarize_database`). This usually means a server version mismatch. Update the MCP server or check which datapack is connected.
+The MCP server responded but does not expose the expected tools (`memory_search`, `memory_get_by_id`, `conversation_create`, `db_summarize_database`). 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.
 
 ### DNS lookup failed
 
@@ -490,17 +664,27 @@ installer/
     create-meko-setup.mjs    # CLI entry point (arg parsing, orchestration)
   lib/
     installer.mjs            # Shared multi-client orchestration
-    clients/                 # Per-client adapters (claude-code/desktop/cursor)
-    claude-code.mjs          # Backward-compatible Claude wrapper
+    clients/                 # Per-client adapters (claude-code/desktop/cursor), aliases, common helpers
     config.mjs               # Safe JSON read/merge/write + path helpers
     detect.mjs               # Claude CLI and existing config detection
     logger.mjs               # ANSI-colored console output (respects NO_COLOR)
     prompt.mjs               # Interactive readline prompts (choice, text, secret, yes/no)
-    validate.mjs             # Post-install validation (config, connectivity, tools)
+    validate.mjs             # Post-install validation (config, connectivity, tools, canary)
+    migrate.mjs              # Migrate subcommand orchestration + per-datapack state
+    migrate/
+      id.mjs                 # datapackKeyFromUrl + agent-id / seed helpers
+      orchestrator.mjs, daemon.mjs, state.mjs, progress.mjs, lockfile.mjs, logger.mjs
+      claude-parser.mjs, mcp-client.mjs, adapters/
+  scripts/
+    bundle-assets.mjs        # prepack: copy skill/hook assets into the npm tarball
+    prepublish-smoke.sh      # Pre-publish smoke harness (run before `npm publish`)
   test/
     config.test.mjs          # Unit tests for JSON merge/read/write
-    clients.test.mjs         # Unit tests for cursor adapter behavior
-    validate.test.mjs        # Unit tests for validation logic
+    clients.test.mjs         # Unit tests for cursor/claude-code/desktop adapters
+    validate.test.mjs        # Unit tests for validation logic (including the canary round-trip)
+    migrate.test.mjs         # Unit tests for migrator + datapackKeyFromUrl helper
+    migrate-integration.test.mjs   # Integration tests for migrator scoping + legacy state back-compat
+    prepublish-smoke.test.mjs      # Piped-stdin smoke tests, gated by SMOKE_HARNESS=1
     installer.test.mjs       # Integration tests for full install flow
     fixtures/                # Mock settings files for tests
 ```
@@ -524,12 +708,26 @@ npm run test:integration
 export MEKO_TEST_CLOUD_URL=https://<your-mcp>.mekodev.com/mcp
 export MEKO_TEST_API_KEY=<your-cloud-api-key>
 npm run test:integration:cloud
+
+# Pre-publish smoke harness: npm pack → install tarball into a throwaway
+# $HOME → exercise the installed CLI (`--version`, `--help`, `--dry-run`)
+# via both the raw node entry and the `node_modules/.bin/meko-mcp` symlink
+# that `npx` resolves through. Gated piped-stdin tests in
+# `test/prepublish-smoke.test.mjs` (SMOKE_HARNESS=1) are run by the harness.
+npm run smoke
 ```
 
 The cloud round-trip tests point the installer at a throw-away `$HOME` via
 `spawnSync`, so the developer's real `~/.claude/settings.json` is never
 modified. They skip cleanly when either env var is unset.
 
+The pre-publish smoke harness is the last gate before `npm publish`. See
+[`RELEASING.md`](../RELEASING.md) at the repo root for the full release
+procedure (version bump → smoke harness → manual TTY checklist → tag → CI
+publish workflows). A CI workflow at `.github/workflows/prepublish-smoke.yml`
+runs the harness on Ubuntu and macOS for every push to a `release/*`
+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`.

package/assets/hooks-handlers/before-submit-prompt.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+
+# Cursor native beforeSubmitPrompt hook. It only reads local cache populated by
+# cursor-session-start.sh; it never performs Meko network calls.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+load_cursor_hook_env() {
+  if [ -n "${MEKO_MCP_URL:-}" ]; then
+    return
+  fi
+  eval "$(node -e '
+    const fs = require("fs");
+    const path = require("path");
+    function shellQuote(value) {
+      return "'"'"'" + String(value).replace(/'"'"'/g, "'"'"'\\'"'"''"'"'") + "'"'"'";
+    }
+    const candidates = [
+      path.join(process.cwd(), ".cursor", "hooks.json"),
+      path.join(process.env.HOME || "", ".cursor", "hooks.json"),
+    ];
+    for (const file of candidates) {
+      try {
+        const cfg = JSON.parse(fs.readFileSync(file, "utf8"));
+        const env = cfg && cfg.env && typeof cfg.env === "object" ? cfg.env : {};
+        const out = [];
+        for (const key of ["MEKO_MCP_URL", "MEKO_API_KEY"]) {
+          if (typeof env[key] === "string" && env[key]) {
+            out.push(`export ${key}=${shellQuote(env[key])}`);
+          }
+        }
+        if (out.length) {
+          process.stdout.write(out.join("\n"));
+          break;
+        }
+      } catch {}
+    }
+  ')"
+}
+
+load_cursor_hook_env
+HOOK_INPUT="$(cat)"
+
+printf '%s' "$HOOK_INPUT" | MEKO_HOOK_CLIENT=cursor node "$SCRIPT_DIR/lib/capture.js" before-submit-prompt

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

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+
+# Cursor native SessionStart hook. Cursor only documents context injection from
+# SessionStart, so this wrapper returns the Meko context synchronously.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+load_cursor_hook_env() {
+  if [ -n "${MEKO_MCP_URL:-}" ]; then
+    return
+  fi
+  eval "$(node -e '
+    const fs = require("fs");
+    const path = require("path");
+    function shellQuote(value) {
+      return "'"'"'" + String(value).replace(/'"'"'/g, "'"'"'\\'"'"''"'"'") + "'"'"'";
+    }
+    const candidates = [
+      path.join(process.cwd(), ".cursor", "hooks.json"),
+      path.join(process.env.HOME || "", ".cursor", "hooks.json"),
+    ];
+    for (const file of candidates) {
+      try {
+        const cfg = JSON.parse(fs.readFileSync(file, "utf8"));
+        const env = cfg && cfg.env && typeof cfg.env === "object" ? cfg.env : {};
+        const out = [];
+        for (const key of ["MEKO_MCP_URL", "MEKO_API_KEY"]) {
+          if (typeof env[key] === "string" && env[key]) {
+            out.push(`export ${key}=${shellQuote(env[key])}`);
+          }
+        }
+        if (out.length) {
+          process.stdout.write(out.join("\n"));
+          break;
+        }
+      } catch {}
+    }
+  ')"
+}
+
+load_cursor_hook_env
+MEKO_HOOK_CLIENT=cursor node "$SCRIPT_DIR/lib/capture.js" session-start