@yugabytedb/meko-mcp 2.1.0 → 2.3.0

package/assets/skills/meko-mcp-tools-desktop/references/tools-rag-workflow.md

@@ -1,6 +1,7 @@
 # Knowledge Base / RAG workflow
 
-`knowledgebase_search` is the only KB tool exposed via MCP. Index
+MCP exposes two KB tools: `knowledgebase_search` (retrieval) and
+`knowledgebase_delete_document` (remove ONE uploaded file). Index
 creation and ingestion happen out of band — through the **Meko UI**
 (`cloud.mekodata.ai`).
 
@@ -8,9 +9,10 @@ creation and ingestion happen out of band — through the **Meko UI**
 
 | Situation | Use this | Why |
 |---|---|---|
-| Search an existing KB | `knowledgebase_search` | The one KB tool exposed via MCP |
+| Search an existing KB | `knowledgebase_search` | Retrieval over the indexed chunks |
 | Add documents to a KB | **Meko UI** — Datapack → Actions → **Add Knowledge** | File-upload dialog (PDF/TXT/MD/JSON/MP4, 5 MB each, 10/batch). No MCP equivalent |
-| Anything else (list / delete / rename / re-index) | **UI** | No MCP tools for KB lifecycle |
+| Delete ONE uploaded file | `knowledgebase_delete_document` | Destructive; `document_id` from search hits; confirm with the user first |
+| Anything else (list / rename / re-index / source lifecycle) | **UI** | No MCP tools for the rest of KB lifecycle |
 
 ## knowledgebase_search — the one you'll actually call
 
@@ -23,7 +25,7 @@ knowledgebase_search(
     limit=10)
 ```
 
-Required: `query`, `agent_id`, `conversation_id`, `datapack_id`.
+Required: `query`, `conversation_id`, `datapack_id`.
 Unlike the memory tools, `datapack_id` has no default here — you must
 pass it explicitly. `agent_id` is **ignored for filtering** on this
 tool (KB results are team-shared on the datapack), but you still pass
@@ -37,10 +39,12 @@ Populated KB:
 {
   "results": [
     {
-      "content": "<chunk text>",
-      "similarity": 0.87,
-      "source_uri": "<original source URI>",
-      "document_name": "<file key>",
+      "id": "<chunk id>",
+      "chunk_text": "<chunk text>",
+      "document_id": "<KB document id; pass to knowledgebase_delete_document>",
+      "metadata_filters": {},
+      "distance": 0.31,
+      "match_type": "semantic" | "keyword" | "hybrid",
       ...
     },
     ...
@@ -49,6 +53,8 @@ Populated KB:
 }
 ```
 
+Lower `distance` is closer. Promoted memories appear as hits whose `metadata_filters.source` is `"memory"`. Hits carry no filename, so show the user the `document_id` and chunk text when they need to identify a file.
+
 Empty or nonexistent KB: `{"results": [], "count": 0}` (no error,
 just an empty array).
 

package/assets/skills/meko-mcp-tools-desktop/references/tools-troubleshooting.md

@@ -7,7 +7,7 @@ These patterns are extracted from real agent sessions. Follow them to avoid wast
 1. **Never retry the identical failed call more than once.** If it fails twice with the same error, it's not transient — diagnose the cause.
 2. **Distinguish transient vs persistent failures.** "Connection already closed" is transient (retry once). "Permission denied" is persistent (stop, don't retry).
 3. **Don't guess parameters sequentially.** If a tool fails with one parameter format, don't try 4 variations. Check this skill's docs for the correct format first.
-4. **Use your session's `agent_id` consistently on writes.** For Claude Desktop the default is `claude_desktop`; use `meko_agent` when writing cross-project facts. Other clients use `<client>:<repo-basename>` (e.g. `claude_code:meko-mcp-server`). Memory reads and `conversation_list` span all of this user's agents regardless of the value passed; `conversation_get` requires the creating agent's exact value.
+4. **Use your session's `agent_id` consistently on writes.** For Claude Desktop the default is `claude_desktop`; use `meko_agent` when writing cross-project facts. Other clients use `<client>:<repo-basename>` (e.g. `claude_code:meko-mcp-server`). Memory reads and `conversation_list` span all of this user's agents regardless of the value passed; the conversation calls (`conversation_get`, `conversation_add_message`, `conversation_update`, `conversation_delete`) require the creating agent's exact value.
 
 ---
 
@@ -26,6 +26,72 @@ These patterns are extracted from real agent sessions. Follow them to avoid wast
 
 ---
 
+## Connection errors: `[Errno 111] Connection refused`
+
+**Affects:** any tool, intermittently. Reports show `memory_add`, `conversation_create`, `memory_search`, and `context_search` failing this way while identical calls succeed minutes later.
+
+**What it means:** the request reached no listening server, usually a server instance that was restarting or scaling. It is not a timeout and not a rejected argument.
+
+**What to do:** wait a few seconds and retry once. Retry `conversation_add_message` only with a `seed`, and never retry `conversation_create` (see the table below). If the retry also fails, report the failure. For a write, tell the user it was not saved; don't let a failed write pass silently.
+
+---
+
+## `memory_search` hangs or times out
+
+`memory_search` can stall for minutes under backend load while other tools respond. Don't raise the client timeout; that only makes the stall longer. Retry once. If it stalls again, report that the search failed, and if the user needs an answer now, try `context_search` or `memory_get_by_id` for a known id. `memory_get_all` only returns a recent window, so it can't replace a search.
+
+---
+
+## Quota errors that look like auth errors
+
+`free_tier_limit_reached` can arrive with HTTP 403, and automatic capture that hits a cap shows up as capture failing with 403. Read the error code, not the status. A quota error means the account reached a lifetime cap (see `tools-known-limitations.md`). Don't rotate keys or reinstall. Tell the user which tool hit the cap and that upgrading the plan lifts it.
+
+---
+
+## Datapack and ownership errors
+
+| Error | Meaning | What to do |
+|---|---|---|
+| `datapack_access_denied` | The `datapack_id` isn't a UUID, or it isn't owned by or shared with your account. The access check also fails closed on a transient server database error. | Retry once. If it repeats, stop; don't switch to another datapack. If the id came from a pin, ask the user to re-pin with the select-datapack skill. |
+| `datapack_id_required` | The call couldn't resolve a datapack. Conversation reads and writes (including `conversation_list`), `datapack_describe`, and `knowledgebase_delete_document` return it. | Pass the pinned `datapack_id`. Don't drop the parameter to make the call pass. |
+| `not_found` from `memory_get_by_id`, `memory_update`, or `memory_delete_by_id` | The memory doesn't exist **or** belongs to another account. The server returns the same error for both on purpose. | Check the id came from a search in this datapack. |
+| `memory_is_promoted` | The memory was promoted to shared knowledge and is read-only through MCP. | Point the user at the Cloud UI Learnings tab. |
+| `invalid_run_id` | `memory_delete_all` got a `run_id` that isn't a conversation id. | Pass the conversation UUID, or omit `run_id`. |
+| `embedder_error` from `knowledgebase_search` | The server couldn't resolve the embedding setup for this datapack's index. | Report it; retrying won't help. |
+| `invalid_force_source` from `context_search` | `force_source` isn't `auto`, `memory`, `knowledge_base`, or `conversation`. | Omit `force_source`. |
+
+---
+
+## Conversation writes fail right after `conversation_create`
+
+`conversation_add_message` has intermittently returned `not_found`, or `agent_id_mismatch` naming agent `'None'`, seconds after `conversation_create` returned that id. It shows up most with several parallel subagents writing to one conversation. Retry once with the same `seed` after a few seconds. If it still fails, don't create a new conversation for the same work: save the durable findings with `memory_add` and tell the user the transcript is incomplete.
+
+On a long conversation that has worked before, `not_found` can instead mean the trace grew too large to load. See `tools-known-limitations.md`.
+
+---
+
+## "No Meko account found for cognito identity ..." on every call
+
+Every Meko tool fails with this error while the connection itself looks fine. Two users hit it for the same reason: Claude Desktop had both the Meko URL connector (Settings > Connectors, which signs in through the browser) and the API-key install from `npx @yugabytedb/meko-mcp --client claude-desktop`, and Desktop used the connector's identity. The word "provisioned" in the error points at a backend account problem, but the fix is on the client:
+
+1. Ask the user for the full list under Settings > Connectors, not just `claude_desktop_config.json`.
+2. Have them remove the Meko URL connector and keep only the API-key install. Use the full API key from the downloaded file.
+3. Quit Claude Desktop completely (Cmd+Q) and reopen it.
+
+---
+
+## "Server disconnected" with `SyntaxError ... node:fs/promises ... 'constants'`
+
+The MCP bridge started under an old Node.js version. `npx` picked up a Node older than 20 from the user's `PATH` (often through `nvm`). Have the user make Node 20 or later the default, for example `nvm alias default 20`, then fully quit and reopen Claude Desktop. Current installer releases declare Node 20.18.1 or later as their minimum.
+
+---
+
+## You can't run a delete the user asked for
+
+Some Claude Desktop deployments refuse Meko delete tools (`memory_delete_by_id`, `memory_delete_all`, `conversation_delete`, `knowledgebase_delete_document`) by policy, even when the datapack owner asks. If that applies to you, say so plainly. Give the user the exact ids with a one-line summary of each and the tool call to run from a client that allows deletes, such as Claude Code. Don't report anything as deleted.
+
+---
+
 ## agent_id errors
 
 On the Cloud multi-tenant schema, `agent_id` is a TEXT column value — not a PostgreSQL identifier — so arbitrary strings are accepted.

package/assets/skills/meko-select-datapack-desktop/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 license: MIT
 metadata:
   author: Meko
-  version: "1.2.0"
+  version: "1.2.2"
   tags: meko, datapack, selection, project, claude-desktop, desktop
 ---
 
@@ -28,7 +28,7 @@ text:        "meko_active_datapack=<uuid> name=<name> selected_at=<iso8601>"
 metadata:    { "type": "active-datapack-pin" }
 ```
 
-You discover it by calling `memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)` at the start of any turn that's about to make a Meko MCP write. If you find a pin, pass `datapack_id="<uuid>"` to every Meko call that accepts it. If you don't find one, fall back to the server default (omit the parameter).
+You discover it by calling `memory_search(query="meko_active_datapack", agent_id="claude_desktop", conversation_id="<this conversation's id>", limit=1)` (`conversation_id` is required and must be a 32-hex id; before `conversation_create`, pass a freshly generated one, never `""`) at the start of any turn that's about to make a Meko MCP write. If you find a pin, pass `datapack_id="<uuid>"` to every Meko call that accepts it. If you don't find one, fall back to the server default (omit the parameter).
 
 ## When to invoke this skill
 
@@ -85,7 +85,7 @@ the Role column. Do not hardcode "Owner", do not invent or normalize the value
 response is the source of truth — see `references/role-display-future.md` for
 the taxonomy.
 
-If the response has zero entries, tell the user: *"You don't have any datapacks yet. Run `datapack_create(name='<name>')` to make one, or visit the Meko Cloud console."* Stop here.
+If the response has zero entries, tell the user: *"You don't have any datapacks yet. Run `datapack_create(name='<name>', conversation_id='<conversation id>')` to make one, or visit the Meko Cloud console."* Stop here.
 
 If the response has exactly **one** entry, **auto-select it**. Print: *"Only one datapack: `<name>`. Auto-selecting. Run `meko-select-datapack-desktop` again with `clear` to unset."* Skip the table; jump to step 4 (persist) and step 5 (confirm).
 
@@ -192,7 +192,7 @@ would split capture across the old and new datapacks or fail outright.
 ## Edge cases
 
 - **Multiple pin memories somehow exist** — the user (or a buggy earlier run) created duplicates. Use the most recent (highest `selected_at`); offer to delete the others.
-- **The pinned datapack no longer exists on the server** — the next Meko MCP call will fail with a not-found error. Re-run the skill to pick a new one or `clear` the stale pin.
+- **The pinned datapack no longer exists or was unshared** — the next Meko MCP call that passes it fails with `datapack_access_denied`. Re-run the skill to pick a new one or `clear` the stale pin.
 - **memory_search times out or fails** — fall back to the server default (omit `datapack_id`) and tell the user *"Couldn't read the active-datapack pin. Using server default for this call."* Don't guess a UUID.
 - **User explicitly overrides for a single call** — pass the user's `datapack_id` for that one call. Do NOT update the pin memory.
 

package/assets/skills/meko-select-datapack-desktop/references/cookbook.md

@@ -8,10 +8,10 @@ Concrete transcripts of the four flows the skill supports on Claude Desktop.
 
 **Skill:**
 ```
-> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", conversation_id="<conv-id>", limit=1)
 [empty]
 
-> datapack_list()
+> datapack_list(conversation_id="<conv-id>")
 [14 entries returned, filtering by "prod-research"]
 
 One match: `prod-research`. Pinning.
@@ -23,7 +23,7 @@ One match: `prod-research`. Pinning.
              metadata='{"type":"active-datapack-pin"}')
 [returns id=mem_abc123]
 
-> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", conversation_id="<conv-id>", limit=1)
 [verifies the row exists]
 
 Pinned datapack `prod-research` (`8b1c…f4a2`) for Claude Desktop.
@@ -41,10 +41,10 @@ datapack_id flows through automatically.
 
 **Skill:**
 ```
-> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", conversation_id="<conv-id>", limit=1)
 [returns id=mem_abc123, text="meko_active_datapack=8b1c…f4a2 name=prod-research …"]
 
-> datapack_list()
+> datapack_list(conversation_id="<conv-id>")
 [14 entries returned, filtering by "q2-roadmap-deck"]
 
 One match: `q2-roadmap-deck`. Switching pin.
@@ -66,10 +66,10 @@ The `memory_update` is critical here — using `memory_add` again would create a
 
 **Skill:**
 ```
-> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", conversation_id="<conv-id>", limit=1)
 [empty]
 
-> datapack_list()
+> datapack_list(conversation_id="<conv-id>")
 [1 entry returned]
 
 Only one datapack: `meko-local-setup`. Auto-selecting.
@@ -90,7 +90,7 @@ Pinned datapack `meko-local-setup` (`a17d…cc91`). Run this skill again with
 
 **Skill:**
 ```
-> memory_search(query="meko_active_datapack", agent_id="claude_desktop", limit=1)
+> memory_search(query="meko_active_datapack", agent_id="claude_desktop", conversation_id="<conv-id>", limit=1)
 [returns id=mem_abc123]
 
 > memory_delete_by_id(

package/assets/skills/meko-select-datapack-desktop/references/role-display-future.md

@@ -24,13 +24,15 @@ Note that the upstream Go source (the `Datapack` struct in `api_server/internal/
 
 ## Other fields the live response includes
 
-Beyond the columns the skill renders by default, `datapack_list` returns counts that may be useful in some flows:
+`datapack_list` doesn't compute counts; its list response carries no count fields. If the user asks for counts, call `datapack_describe(datapack_id=<id>, conversation_id="<conversation id>")` and read them from that response:
 
-- `memory_count` — total memories the caller has under this datapack (per `(user_id, agent_id)` scoping).
-- `knowledge_count` — knowledge-base entries on the datapack.
-- `learnings_count` — promoted-to-shared memories on the datapack.
+- `memory_count`: all memories stored in the datapack.
+- `collective_memory_count`: memories promoted to shared knowledge.
+- `learnings_count`: memories awaiting a promotion decision.
+- `knowledge_base_file_count`: uploaded KB documents (`null` if the status endpoint is unreachable).
+- `knowledge_chunk_count`: KB chunks across all documents. `knowledge_count` is a deprecated alias.
 
-These aren't in the spec column set. Don't add them silently. If the user asks for counts, render them on request — and read the numbers from the live response, never invent them.
+Don't add counts to the table silently, and never invent the numbers.
 
 ## Sharing UI vs API state
 

package/assets/skills/meko-select-datapack-desktop/references/troubleshooting.md

@@ -18,12 +18,12 @@ You (or an earlier run) created duplicates by using `memory_add` instead of `mem
 
 The cookbook's Flow 2 demonstrates the correct switch path.
 
-## Symptom: A pinned datapack returns "not found" when used
+## Symptom: A pinned datapack returns `datapack_access_denied` when used
 
-The pin became stale — the datapack was deleted in another client. Tell the user:
+The pin became stale: the datapack was deleted, or its share to you was revoked, in another client. The server checks ownership and shares on every call that passes a `datapack_id`, so the call fails with `datapack_access_denied` (older servers returned a not-found error). The check also fails closed on a transient server database error, so retry the call once before treating the pin as stale. Tell the user:
 
 ```
-The pinned datapack `<name>` (`<id>`) no longer exists on the server.
+The pinned datapack `<name>` (`<id>`) no longer exists or is no longer shared with you.
 Run `meko-select-datapack-desktop` to pick a fresh one, or `clear` to unpin.
 ```
 
@@ -40,7 +40,7 @@ The user has zero datapacks. Print:
 ```
 You don't have any datapacks yet. Create one with:
 
-  datapack_create(name="<your-datapack-name>")
+  datapack_create(name="<your-datapack-name>", conversation_id="<conversation id>")
 
 Or visit the Meko Cloud console (Datapacks → New datapack).
 ```

package/bin/create-meko-setup.mjs

@@ -18,6 +18,8 @@ import { resolveSuggestedMcpUrl } from '../lib/url-selection.mjs';
 import { parseClientList } from '../lib/clients/aliases.mjs';
 import { startMigration, runChildMigration, readStatus, stopMigration } from '../lib/migrate.mjs';
 import { checkLatest } from '../lib/version-check.mjs';
+import { runCaptureStatus } from '../lib/capture-status.mjs';
+import { captureCleanupArgs, runCaptureCleanup } from '../lib/capture-cleanup.mjs';
 
 // ---------------------------------------------------------------------------
 // Flag definitions
@@ -44,6 +46,15 @@ const options = {
   help:               { type: 'boolean', short: 'h', default: false },
   version:            { type: 'boolean', short: 'v', default: false },
 
+  // --- Capture health (Capture V2 Workstream D) ---
+  'capture-status':   { type: 'boolean', default: false },
+  json:               { type: 'boolean', default: false },
+  'capture-cleanup':  { type: 'string' },
+  session:            { type: 'string', multiple: true },
+  all:                { type: 'boolean', default: false },
+  'max-exchanges':    { type: 'string' },
+  'pace-ms':          { type: 'string' },
+
   // --- Migrate subcommand ---
   migrate:            { type: 'boolean', default: false },
   'migrate-status':   { type: 'boolean', default: false },
@@ -70,11 +81,11 @@ function readVersion() {
   return pkg.version;
 }
 
-const ALL_CLIENTS = ['claude-code', 'claude-desktop', 'cursor', 'codex'];
+const ALL_CLIENTS = ['claude-code', 'claude-desktop', 'cursor', 'codex', 'kiro', 'opencode'];
 
 function printHelp() {
   const text = `
-Meko Setup for Claude Clients and Cursor
+Meko Setup for Claude Code, Claude Desktop, Cursor, Codex, Kiro, and OpenCode
 
 Install and configure Meko MCP Server in one command.
 
@@ -100,15 +111,25 @@ Examples:
   # Install for OpenAI Codex (CLI + Desktop App share the same config):
   create-meko-setup --client codex --yes
 
+  # Install for Kiro (IDE and kiro-cli share the same config):
+  create-meko-setup --client kiro --yes
+
+  create-meko-setup --client opencode --scope user --yes
+
   # Local Meko (docker-compose stack, Claude Code):
   create-meko-setup --local --yes
 
 Options:
-  --client <list>       Target clients: one or more of claude-code, claude-desktop, cursor, codex.
-                        "claude" is accepted as an alias for claude-code.
+  --client <list>       Target clients: one or more of claude-code, claude-desktop, cursor, codex, kiro, opencode.
+                        "claude" is accepted as an alias for claude-code;
+                        "kiro-cli" and "kiro-ide" for kiro.
                         Comma-separated, or "all" to target every supported client (default: claude-code)
                         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. It installs
+                        inline CLI 2.x and standalone CLI 3.x/IDE capture hooks;
+                        untrusted IDE workspaces and non-managed CLI agents fall
+                        back to agent-driven persistence.
   --url <url>           MCP server URL (from cloud.mekodata.ai > Datapacks > Connect)
   --api-key <key>       API key for Cloud Meko authentication
   --local               Use local Meko at http://localhost:8000/mcp
@@ -134,6 +155,34 @@ Options:
   -h, --help            Show this help message
   -v, --version         Show version
 
+Capture health (durable outbox / recovery):
+  --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.
+  --json                With --capture-status, print machine-readable JSON
+                        matching the capture-health cache shape. Also
+                        accepted by --capture-cleanup.
+  --capture-cleanup <action>
+                        Clean up stuck capture on this machine:
+                          status   list sessions with unsent work and the
+                                   background capture processes (read-only)
+                          stop     stop SessionEnd workers and in-flight
+                                   drains, and park all unsent work so no
+                                   hook retries it (nothing is deleted)
+                          resume   unpark and hand back to the hooks
+                          drain    send now, one session at a time; stops
+                                   and re-parks at the first failure
+                          discard  skip a session's unsent exchanges for
+                                   good (needs --yes)
+                          repair   clear stale failure fields and leftover
+                                   PID, lease, and job files
+                        Options: --session <id> or a bare session ID
+                        (repeatable, prefix ok),
+                        --all, --dry-run, --json, --yes,
+                        --max-exchanges N (drain, default 200),
+                        --pace-ms N (drain, default 1000).
+
 Migrate existing conversations and memories into Meko:
   --migrate             Start a detached migration of existing Claude Code
                         and Cursor conversations + CLAUDE.md memories.
@@ -251,7 +300,22 @@ function parseRate(raw) {
 // ---------------------------------------------------------------------------
 
 async function main() {
-  const { values: flags } = parseArgs({ options, strict: true });
+  const { values: flags, positionals } = parseArgs({
+    options,
+    strict: true,
+    allowPositionals: true,
+  });
+  // Only --capture-cleanup takes bare arguments: session IDs, so
+  // `--capture-cleanup drain c0acdeb2` works like `--session c0acdeb2`.
+  if (positionals.length > 0) {
+    if (flags['capture-cleanup'] === undefined) {
+      error(
+        `Unexpected argument '${positionals[0]}'. This command does not take positional arguments`,
+      );
+      process.exit(1);
+    }
+    flags.session = [...(flags.session || []), ...positionals];
+  }
   const projectRoot = process.cwd();
 
   // --help
@@ -267,6 +331,29 @@ async function main() {
     process.exit(0);
   }
 
+  // --capture-status — aggregate outbox health (Capture V2). Combine with
+  // --json for machine-readable output. Exit codes: 0 healthy|catching_up,
+  // 2 degraded_retrying, 3 blocked_action_required.
+  if (flags['capture-status']) {
+    const out = runCaptureStatus({ json: Boolean(flags.json) });
+    if (out.stdout) process.stdout.write(out.stdout);
+    if (out.stderr) process.stderr.write(out.stderr);
+    process.exit(out.code);
+  }
+  // --capture-cleanup <action>: inspect, stop, park, drain, or discard
+  // stuck capture sessions. Exit codes: 0 done, 1 error, 2 partly done.
+  if (flags['capture-cleanup'] !== undefined) {
+    const out = runCaptureCleanup(
+      captureCleanupArgs(flags['capture-cleanup'], flags),
+    );
+    if (out.error) error(out.error);
+    process.exit(out.code);
+  }
+  if (flags.json) {
+    error('--json requires --capture-status or --capture-cleanup');
+    process.exit(1);
+  }
+
   // --check-updates — synchronous probe of the npm registry. Never fails:
   // network errors produce "status: network error (<message>)" and exit 0.
   if (flags['check-updates']) {
@@ -442,6 +529,8 @@ async function main() {
         'claude-desktop': 'Claude Desktop',
         cursor: 'Cursor',
         codex: 'OpenAI Codex (CLI + App)',
+        kiro: 'Kiro (IDE + kiro-cli)',
+        opencode: 'OpenCode CLI/TUI',
       }[id];
       return {
         label: id,
@@ -542,12 +631,14 @@ async function main() {
     }
 
     // Step 4 — skills
-    const installSkills = await askYesNo(
-      'Install Meko agent skills plugin? (behavioral guides for MCP tools)',
-      true,
-    );
-    if (!installSkills) {
-      skipSkills = true;
+    if (!skipSkills) {
+      const installSkills = await askYesNo(
+        'Install Meko agent skills plugin? (behavioral guides for MCP tools)',
+        true,
+      );
+      if (!installSkills) {
+        skipSkills = true;
+      }
     }
 
     // Step 5 — statusline (Claude Code only). --no-statusline / --statusline
@@ -722,15 +813,23 @@ async function maybeOfferMigration({ url, apiKey, scope, projectRoot, datapack }
       dryRun: true,
       datapack: datapack ?? null,
     });
+    if (dry && dry.ok === false) {
+      dim(`Skipped migration offer: ${dry.message || "dry run failed"}`);
+      return;
+    }
     const s = dry?.message?.match(/Claude Code sessions: *(\d+)/);
     const c = dry?.message?.match(/Cursor sessions: *(\d+)/);
+    const x = dry?.message?.match(/Codex sessions: *(\d+)/);
+    const o = dry?.message?.match(/OpenCode sessions: *(\d+)/);
     const m = dry?.message?.match(/Memory items \(MD\): *(\d+)/);
     const counts = {
       claude: s ? Number(s[1]) : 0,
       cursor: c ? Number(c[1]) : 0,
+      codex: x ? Number(x[1]) : 0,
+      opencode: o ? Number(o[1]) : 0,
       memory: m ? Number(m[1]) : 0,
     };
-    const total = counts.claude + counts.cursor + counts.memory;
+    const total = counts.claude + counts.cursor + counts.codex + counts.opencode + counts.memory;
     if (total === 0) return;
 
     console.log('');
@@ -738,6 +837,8 @@ async function maybeOfferMigration({ url, apiKey, scope, projectRoot, datapack }
       `Found existing data to migrate: ` +
       `${counts.claude} Claude Code sessions, ` +
       `${counts.cursor} Cursor sessions, ` +
+      `${counts.codex} Codex sessions, ` +
+      `${counts.opencode} OpenCode sessions, ` +
       `${counts.memory} memory items.`,
     );
     const proceed = await askYesNo(

package/lib/capture-cleanup.mjs

@@ -0,0 +1,63 @@
+/**
+ * capture-cleanup.mjs: installer helper that invokes capture-cleanup-cli.js.
+ *
+ * Resolves the CLI the same way capture-status.mjs does, so a published
+ * package runs the bundled copy next to the capture.js it drains with.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { resolveCaptureStatusCli } from "./capture-status.mjs";
+
+/**
+ * Absolute path to capture-cleanup-cli.js under the active asset root.
+ * @returns {string}
+ */
+export function resolveCaptureCleanupCli() {
+  return join(dirname(resolveCaptureStatusCli()), "capture-cleanup-cli.js");
+}
+
+/**
+ * Build the CLI argument list from parsed installer flags.
+ *
+ * @param {string} action
+ * @param {{ session?: string[], all?: boolean, 'dry-run'?: boolean,
+ *   json?: boolean, yes?: boolean, 'max-exchanges'?: string,
+ *   'pace-ms'?: string }} flags
+ * @returns {string[]}
+ */
+export function captureCleanupArgs(action, flags = {}) {
+  const args = [action];
+  for (const id of flags.session || []) args.push("--session", id);
+  if (flags.all) args.push("--all");
+  if (flags["dry-run"]) args.push("--dry-run");
+  if (flags.json) args.push("--json");
+  if (flags.yes) args.push("--yes");
+  if (flags["max-exchanges"] != null) args.push("--max-exchanges", String(flags["max-exchanges"]));
+  if (flags["pace-ms"] != null) args.push("--pace-ms", String(flags["pace-ms"]));
+  return args;
+}
+
+/**
+ * Run the capture-cleanup CLI with inherited stdio (drain prints progress)
+ * and return its exit code.
+ *
+ * @param {string[]} args
+ * @param {{ env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {{ code: number, cliPath: string, error?: string }}
+ */
+export function runCaptureCleanup(args, opts = {}) {
+  const cliPath = resolveCaptureCleanupCli();
+  if (!existsSync(cliPath)) {
+    return { code: 1, cliPath, error: `capture-cleanup CLI not found at ${cliPath}` };
+  }
+  const result = spawnSync(process.execPath, [cliPath, ...args], {
+    stdio: "inherit",
+    env: opts.env ? { ...process.env, ...opts.env } : process.env,
+  });
+  const code =
+    typeof result.status === "number" && result.status >= 0 ? result.status : 1;
+  return { code, cliPath };
+}

package/lib/capture-status.mjs

@@ -0,0 +1,67 @@
+/**
+ * capture-status.mjs — Installer helper that invokes capture-status-cli.js.
+ *
+ * Resolves the CLI next to bundled/source hooks (same root as capture.js).
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { resolveHooksRoot } from "./clients/common.mjs";
+
+/**
+ * Absolute path to capture-status-cli.js under the active asset root.
+ * @returns {string}
+ */
+export function resolveCaptureStatusCli() {
+  // Prefer the stable source-tree path in a checkout. Bundle tests create and
+  // remove installer/assets concurrently, so probing that transient directory
+  // first can race between existsSync and spawnSync. Published packages do not
+  // contain the repository skills tree and therefore fall back to assets.
+  const here = dirname(fileURLToPath(import.meta.url));
+  const sourceCli = resolve(
+    here,
+    "..",
+    "..",
+    "skills",
+    "hooks-handlers",
+    "lib",
+    "capture-status-cli.js",
+  );
+  if (existsSync(sourceCli)) return sourceCli;
+  return join(resolveHooksRoot(), "lib", "capture-status-cli.js");
+}
+
+/**
+ * Run the capture-status CLI and return its result.
+ *
+ * @param {{ json?: boolean, env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {{ code: number, stdout: string, stderr: string, cliPath: string }}
+ */
+export function runCaptureStatus(opts = {}) {
+  const cliPath = resolveCaptureStatusCli();
+  if (!existsSync(cliPath)) {
+    return {
+      code: 1,
+      stdout: "",
+      stderr: `capture-status CLI not found at ${cliPath}`,
+      cliPath,
+    };
+  }
+  const args = [cliPath];
+  if (opts.json) args.push("--json");
+  const result = spawnSync(process.execPath, args, {
+    encoding: "utf8",
+    env: opts.env ? { ...process.env, ...opts.env } : process.env,
+  });
+  const code =
+    typeof result.status === "number" && result.status >= 0 ? result.status : 1;
+  return {
+    code,
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+    cliPath,
+  };
+}

package/lib/clients/aliases.mjs

@@ -3,6 +3,11 @@
 // import it without booting the bin entry point.
 export const CLIENT_ALIASES = Object.freeze({
   claude: "claude-code",
+  // The Kiro IDE and `kiro-cli` share one adapter: same mcp.json paths, same
+  // skills directories. Users reach for whichever name matches the surface
+  // they're installing for, so both resolve to the single `kiro` adapter.
+  "kiro-cli": "kiro",
+  "kiro-ide": "kiro",
 });
 
 /**

package/lib/clients/claude-code.mjs

@@ -65,6 +65,7 @@ const MEKO_MARKETPLACE_NAME = "meko-agent-skills";
 const MEKO_ALWAYS_AVAILABLE_TOOLS = [
   "mcp__meko__memory_add",
   "mcp__meko__memory_search",
+  "mcp__meko__context_search",
   "mcp__meko__memory_get_all",
   "mcp__meko__memory_get_by_id",
   "mcp__meko__memory_update",