@yugabytedb/meko-mcp 1.0.6 → 1.1.0

package/README.md

@@ -1,9 +1,13 @@
 # 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.
 
+## 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.
+
 ## Quick Start
 
 The installer is path-agnostic — the three forms below are equivalent. Pick the one that matches how you obtained the code:
@@ -77,11 +81,19 @@ 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 "API_KEY: <key>"` for cloud) |
-| 2 | Set hook environment vars | Writes `MEKO_MCP_URL` and `MEKO_API_KEY` into `~/.claude/settings.json` under the `env` key |
-| 3 | Register plugin marketplace | `claude plugin marketplace add yugabyte/meko-mcp-server --sparse .claude-plugin,skills --scope user` |
+| 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` |
 | 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`):**
 
@@ -96,6 +108,14 @@ 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**: 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 the installer also offers to run `launchctl setenv MEKO_API_KEY ...` since macOS apps launched from Finder/Dock do not inherit shell-rc env vars.
+  - **No project scope**: Codex has no per-project config. `--scope project --client codex` warns and degrades to user scope.
+  - **No auto-capture**: Codex does not expose user-installable session lifecycle hooks, so `session-start` / `session-end` capture is not available. Memory persistence still works via the model proactively calling `memory_search` / `memory_add` (the AGENTS.md block prompts this).
+  - **Restart Codex.app** after install so it picks up the new MCP server registration.
 
 ## CLI Reference
 
@@ -106,15 +126,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` |
 | `--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` |
@@ -145,9 +166,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.
 
@@ -223,7 +244,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)
@@ -256,31 +277,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 (hybrid hook mode) | **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 |
+| `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 | env-var name reference (`MEKO_API_KEY` exported in shell or via `launchctl setenv`) |
+| 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) | — | Auto-capture (blocked on upstream Codex exposing user-installable hooks) |
 
 ## Cloud vs Local
 
@@ -288,7 +313,7 @@ memory errs:  0                (failed memory_add calls; re-run with --force to
 |---|-----------|-----------|
 | **URL** | Provided by app.mekodev.com > Datapacks > Connect | `http://localhost:8000/mcp` |
 | **Authentication** | Requires `--api-key` or `$MEKO_API_KEY` env var | None |
-| **MCP registration** | Includes `-H "API_KEY: <key>"` header | No auth header |
+| **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 |
@@ -315,6 +340,97 @@ The installer auto-detects cloud vs local based on the URL: any URL containing `
 
 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.
 
+## 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
 
 ### Claude Code CLI not found
@@ -338,14 +454,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)
 
 ```
@@ -354,6 +481,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
@@ -380,10 +509,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
 
@@ -457,7 +586,7 @@ node installer/bin/create-meko-setup.mjs --uninstall --verbose
 | # | Scenario | Steps | Expected Result |
 |---|----------|-------|-----------------|
 | 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 API_KEY header, env vars set, validation passes |
+| M2 | Fresh cloud install | Run interactively, provide Cloud Meko URL + API key | MCP registered with `Authorization: Bearer` header, env vars set, validation passes |
 | 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 |
@@ -486,17 +615,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
 ```
@@ -520,12 +659,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`.