@yugabytedb/meko-mcp 1.0.8 → 1.2.0

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

@@ -0,0 +1,155 @@
+# Troubleshooting — Error Recovery and Retry Strategies
+
+These patterns are extracted from real agent sessions. Follow them to avoid wasting tool calls and context window on repeated failures.
+
+## General rules
+
+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.** For Claude Desktop the default is `claude_desktop`; for cross-project common facts use `meko_agent`. Other clients use `<client>:<repo-basename>` (e.g. `claude_code:meko-mcp-server`). Use `agent_id="meko_agent"` deliberately on `memory_search`/`memory_get_all` only when you want the common bucket — empty string also resolves to `meko_agent`, not a cross-agent fan-out. Don't switch between forms mid-session.
+
+---
+
+## Connection errors: "connection already closed"
+
+**Affects:** Memory tools (`memory_add`, `memory_search`, `memory_get_all`) most frequently. DB tools less often.
+
+**Why it happens:** The Python memory subsystem uses a connection cache that doesn't recover from dropped connections (unlike the Go API server which has retry logic with 5 retries and 3-second delays).
+
+**What to do:**
+
+1. Retry the same call **once**.
+2. If it fails again, the memory subsystem is unhealthy for this session — stop trying memory calls and tell the user. Do not waste tokens re-sending the same payload.
+3. Direct-SQL fallback **does not apply** on cloud Free Tier (`db_run_read_only_query` returns `{"error": "not_available", "detail": "Free Tier: DB Tools access is not enabled. coming soon."}`). On self-hosted / paid deployments where DB tools are available, inspect memory rows via the multi-tenant schema — tables are namespaced by datapack, not by agent_id. The old `{agent_id}_mem0_collection` per-agent-table layout is gone.
+
+**Anti-pattern from real sessions:** Agent called `memory_add` with 500+ tokens of text, got "connection already closed", retried the identical call 3 more times (each 500+ tokens). Wasted ~2000 tokens on guaranteed failures.
+
+---
+
+## RAG pipeline stuck at INIT
+
+**Affects:** `knowledgebase_trigger_index_creation` — the build triggers but never completes.
+
+**Symptoms:**
+- `knowledgebase_check_index_status` returns empty `pipeline_details` and `pipeline_stats`
+- Documents remain at `INIT` status indefinitely
+- Work queue tasks are `IN_PROGRESS` with `lease_expires_at` in the past
+
+**Diagnosis:** Query the work queue directly:
+```
+db_run_read_only_query(scope="read",
+    query="SELECT task_type, status, lease_expires_at FROM dist_rag.work_queue WHERE index_name = 'your_index' ORDER BY created_at DESC LIMIT 10")
+```
+
+Look for tasks stuck `IN_PROGRESS` with expired leases — these indicate crashed or hung workers.
+
+**What to do:**
+
+1. Poll status **at most 3 times** with 1-2 minute intervals
+2. If no progress after 3 checks, **stop polling** — the pipeline is stuck
+3. There is **no way to reset or retry stuck tasks via MCP tools**
+4. Creating a new index with a different name (e.g., `_v2`) is a workaround, but if the workers themselves are down, this will also get stuck
+5. Recommend the user check worker logs or restart the pipeline service
+
+**Anti-pattern from real sessions:** Agent created indexes `v1`, `v2`, `v3` — all stuck with the same symptoms. Even making the S3 bucket public didn't help. The issue was worker infrastructure, not permissions.
+
+---
+
+## db_run_write_query guardrail error
+
+**Error:** `'dict' object has no attribute 'guardrail_config'`
+
+**Affects:** `db_run_write_query` in some deployments.
+
+**What to do:**
+
+1. Try the call once. If it fails with this specific error, write operations are unavailable in this deployment.
+2. For reads, always use `db_run_read_only_query` (never `db_run_write_query` for SELECT).
+3. Report the issue — it's a server-side bug, not a parameter problem.
+
+---
+
+## knowledgebase_add_source_to_index failure
+
+**Error shape:** `{"error": "not_available", "detail": "Vector index creation is not available on the free tier."}`
+
+You're on cloud Free Tier; the ingestion tools are gated off. There is no retry that will succeed. Point the user at the Meko UI's **Add Knowledge** file-upload flow (Datapack → Actions → Add Knowledge) instead.
+
+**Error shape:** `{"error": "index_not_found", "detail": "No vector index found with name '...'"}`
+
+The `index_name` doesn't exist in this datapack's `dist_rag.vector_indexes` table. Either you're targeting the wrong datapack (check `datapack_id`), or the index hasn't been created yet — call `knowledgebase_trigger_index_creation` first.
+
+**Error shape:** tool returns `"build_triggered"` but `knowledgebase_check_index_status` shows documents stuck at `INIT` for >5 minutes.
+
+Most common cause on self-hosted deployments: the worker can't reach the S3 bucket. `S3BucketCrawler()` uses boto3's default credential chain — check `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / IAM role / `~/.aws/credentials` on the worker host, not on the MCP server. Second cause: the URI isn't `s3://`-prefixed (`aws_source_processor.py` rejects other schemes with `ValueError("Invalid source URI")` async).
+
+**Historical note:** the old `r_index_name` vs `r_index_id` parameter-mismatch bug is fixed on main — the MCP tool now resolves `index_name → index_id` internally via a `SELECT id FROM dist_rag.vector_indexes WHERE index_name = %s` step. Older docs referencing this bug are stale.
+
+---
+
+## Scope parameter errors
+
+**Error:** `Insufficient scope: 'all'. This tool requires 'read' or higher.`
+
+The only valid scope values are: `"read"`, `"write"`, `"admin"`.
+
+- Use `"read"` for all read operations (default choice)
+- Use `"write"` for inserts, updates, creates, memory writes
+- Use `"admin"` only for destructive deletes
+
+**Never use:** `"all"`, `"readwrite"`, `"rw"`, or any other value.
+
+---
+
+## 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.
+
+`agent_id` is **not a constant**. Cloud Meko supports multiple agents on one datapack, and the Cloud UI renders every `agent_id` as a badge on each row regardless of value. The canonical shape for new writes is `<client>:<repo-basename>` for coding agents (e.g. `claude_code:meko-mcp-server`), a bare client name for non-coding clients like Claude Desktop (`claude_desktop`), or `meko_agent` for the cross-project common bucket — see `tools-agent-id-conventions.md`.
+
+### "My writes are landing in `meko_agent` instead of my agent's bucket"
+
+If you call `memory_add` with empty / None / whitespace `agent_id`, the server does NOT reject the write. It silently resolves the value to `meko_agent` (the cross-project common bucket) and the row lands there. The Cloud UI then shows a `meko_agent` badge instead of your client's badge.
+
+Fix: always pass a concrete non-empty `agent_id`. For Claude Desktop use `agent_id="claude_desktop"`; for hook-driven clients (Claude Code, Cursor) fetch the value the SessionStart hook injected into `additionalContext` and pass it verbatim. Use `agent_id="meko_agent"` only when you genuinely want a fact in the cross-project pool (user identity, global preferences).
+
+### "My reads return fewer results than I expected"
+
+`memory_search` and `memory_get_all` filter strictly on your passed `agent_id`. A memory written by `claude-code:<slug-A>` is invisible to a search with `agent_id="cursor:<slug-B>"`. If you need a broader view, call repeatedly across the agent_ids you want to cover, or point the user at the UI's Memory Summary page (which shows every row regardless of agent_id).
+
+### "I'm seeing rows tagged with legacy agent_id values"
+
+Pre-existing data may be tagged `"agent"`, `"claude_code"`, `"cursor:<slug>"`, or similar ad-hoc values. All remain readable. New writes should follow the canonical `<client>:<project-slug>` form; don't try to retag old rows.
+
+---
+
+## Permission denied on data tables
+
+**Error:** `permission denied for table customer_complaints`
+
+**Why:** The MCP database user may not have read access to all tables, particularly data tables created by the provisioning system within a datapack.
+
+**What to do:**
+
+1. This is a server-side configuration issue — not fixable via MCP tools.
+2. Don't retry. Don't try different query formulations.
+3. Use `db_summarize_database` to see which tables you CAN access.
+4. Report the permission gap to the Meko admin.
+
+---
+
+## Safe-to-retry vs not
+
+| Tool | Safe to retry? | Why |
+|------|---------------|-----|
+| All `read` scope tools | Yes | Reads are idempotent |
+| `memory_add` | Yes (once) | Mem0 has dedup logic |
+| `memory_update` | Yes (once) | Overwrites same ID |
+| `memory_delete_by_id` | Yes | Deleting already-deleted is a no-op |
+| `db_run_write_query` (INSERT) | **No** | May double-insert rows |
+| `db_run_write_query` (CREATE TABLE) | **No** | "Table already exists" error |
+| `knowledgebase_trigger_index_creation` | **No** | Creates duplicate indexes |
+| `conversation_create` | **No** | Creates duplicate conversations |
+| `conversation_add_message` with `seed` | Yes | Seed-based dedup prevents duplicates |
+| `conversation_add_message` without `seed` | **No** | Creates duplicate messages |

package/bin/create-meko-setup.mjs

@@ -7,11 +7,12 @@ import { dirname, join } from 'node:path';
 
 import { install, uninstall } from '../lib/installer.mjs';
 import { askChoice, askMultiChoice, askText, askSecret, askYesNo, close as closePrompts } from '../lib/prompt.mjs';
-import { banner, error, dim } from '../lib/logger.mjs';
+import { banner, error, dim, info } from '../lib/logger.mjs';
 import { isPackagedInstall, selfInvocation } from '../lib/clients/common.mjs';
 import { getClientAdapters } from '../lib/clients/index.mjs';
 import { parseClientList } from '../lib/clients/aliases.mjs';
 import { startMigration, runChildMigration, readStatus, stopMigration } from '../lib/migrate.mjs';
+import { checkLatest } from '../lib/version-check.mjs';
 
 // ---------------------------------------------------------------------------
 // Flag definitions
@@ -24,10 +25,12 @@ const options = {
   scope:              { type: 'string',  default: 'user' },
   name:               { type: 'string',  default: 'meko' },
   client:             { type: 'string',  default: 'claude-code' },
-  'cursor-hook-mode': { type: 'string',  default: 'hybrid' },
+  'cursor-hook-mode': { type: 'string',  default: 'native' },
   'skip-skills':      { type: 'boolean', default: false },
   'skip-validation':  { type: 'boolean', default: false },
+  'no-canary':        { type: 'boolean', default: false },
   'dry-run':          { type: 'boolean', default: false },
+  'check-updates':    { type: 'boolean', default: false },
   uninstall:          { type: 'boolean', default: false },
   verbose:            { type: 'boolean', default: false },
   yes:                { type: 'boolean', default: false },
@@ -43,6 +46,7 @@ const options = {
   rate:               { type: 'string' },
   'no-extract':       { type: 'boolean', default: false },
   'run-id':           { type: 'string' },
+  datapack:           { type: 'string' },
   '__migrate-child':  { type: 'boolean', default: false },
 };
 
@@ -59,7 +63,7 @@ function readVersion() {
   return pkg.version;
 }
 
-const ALL_CLIENTS = ['claude-code', 'claude-desktop', 'cursor'];
+const ALL_CLIENTS = ['claude-code', 'claude-desktop', 'cursor', 'codex'];
 
 function printHelp() {
   const text = `
@@ -86,22 +90,32 @@ Examples:
   # Install on every supported client:
   create-meko-setup --client all --local --yes
 
+  # Install for OpenAI Codex (CLI + Desktop App share the same config):
+  create-meko-setup --client codex --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.
+  --client <list>       Target clients: one or more of claude-code, claude-desktop, cursor, codex.
                         "claude" is accepted as an alias for claude-code.
                         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).
   --url <url>           MCP server URL (from app.mekodev.com > Datapacks > Connect)
   --api-key <key>       API key for Cloud Meko authentication
   --local               Use local Meko at http://localhost:8000/mcp
   --scope <scope>       Config scope: user or project (default: user)
+                        codex always installs at user scope (no project-level
+                        config); --scope=project degrades with a warning.
   --name <name>         MCP server name in config (default: meko)
-  --cursor-hook-mode    Cursor hook mode: native, claude-compat, hybrid (default: hybrid)
+  --cursor-hook-mode    Cursor hook mode: native or claude-compat (default: native)
   --skip-skills         Skip plugin and skills installation
   --skip-validation     Skip post-install validation
+  --no-canary           Skip the canary datapack_list call. The
+                        connectivity + tools/list checks still run.
   --dry-run             Show what would be done without making changes
+  --check-updates       Compare installed version against npm registry and exit
   --uninstall           Remove Meko MCP server, skills, and env vars
   --verbose             Show detailed output
   --yes                 Accept all defaults (non-interactive)
@@ -121,6 +135,10 @@ Migrate existing conversations and memories into Meko:
   --rate <n>            Max concurrent MCP calls during migration (default 4).
   --force               Ignore a live lockfile or re-ingest processed items.
   --run-id <id>         Target a specific run-id for --migrate-status.
+  --datapack <name|id>  Migration destination datapack. Accepts a datapack
+                        name or UUID. When omitted, the user's default
+                        datapack is used (resolved at run time and printed
+                        before the run starts).
 `.trimStart();
 
   console.log(text);
@@ -130,6 +148,31 @@ function isCloudUrl(url) {
   return url && !url.includes('localhost') && !url.includes('127.0.0.1');
 }
 
+/**
+ * Sanitize a raw API key from any source (CLI flag, env var, askSecret prompt).
+ *
+ * Strips surrounding whitespace and a single matching pair of surrounding
+ * quotes. The contaminated value would otherwise be concatenated into
+ * `Authorization: Bearer <key>` verbatim and 401 against any server. Common
+ * sources of contamination: a trailing newline from
+ * `export MEKO_API_KEY=$(cat token.txt)`, a literal `"..."` copied out of a
+ * `.env` file, or a stray space at the end of a paste.
+ *
+ * Returns `null` for null/undefined/empty so the existing `!apiKey` checks
+ * still funnel into the "no key supplied" path.
+ */
+function normalizeApiKey(value) {
+  if (value === null || value === undefined) return null;
+  let s = String(value).trim();
+  if (
+    (s.startsWith('"') && s.endsWith('"') && s.length >= 2) ||
+    (s.startsWith("'") && s.endsWith("'") && s.length >= 2)
+  ) {
+    s = s.slice(1, -1).trim();
+  }
+  return s || null;
+}
+
 /**
  * Parse --client into a deduplicated list of client IDs.
  * Accepts a single value, a comma-separated list, or the keyword "all".
@@ -175,7 +218,7 @@ function detectInstalledClients() {
 }
 
 function isValidCursorHookMode(mode) {
-  return ['native', 'claude-compat', 'hybrid'].includes(mode);
+  return ['native', 'claude-compat'].includes(mode);
 }
 
 /**
@@ -208,9 +251,41 @@ async function main() {
   // --version
   if (flags.version) {
     console.log(readVersion());
+    console.log('(run with --check-updates to compare against npm registry)');
     process.exit(0);
   }
 
+  // --check-updates — synchronous probe of the npm registry. Never fails:
+  // network errors produce "status: network error (<message>)" and exit 0.
+  if (flags['check-updates']) {
+    const current = readVersion();
+    const result = await checkLatest({ currentVersion: current });
+    console.log(`current: ${current}`);
+    if (result.latest) {
+      console.log(`latest:  ${result.latest}`);
+      if (result.isOutdated) {
+        console.log('status:  outdated — run `npx @yugabytedb/meko-mcp@latest` to upgrade');
+      } else {
+        console.log('status:  up to date');
+      }
+    } else {
+      console.log('latest:  unknown');
+      console.log(`status:  network error (${result.error ?? 'unknown'})`);
+    }
+    process.exit(0);
+  }
+
+  // Kick off a background version check on normal runs. We intentionally don't
+  // await — if the registry is slow or unreachable we don't want to delay
+  // (or fail) the install. `background: true` unrefs the underlying socket so
+  // an in-flight probe never keeps Node alive after the install exits; the
+  // result is still consulted (via Promise.race with an already-resolved
+  // sentinel) in time for the post-install banner when it arrives early.
+  const versionCheckPromise = checkLatest({ currentVersion: readVersion(), background: true });
+  versionCheckPromise.catch(() => {
+    /* checkLatest never rejects, but belt-and-suspenders. */
+  });
+
   // --- Migrate subcommand dispatch ---
 
   // Detached child branch: re-entry inside the spawned process.
@@ -230,11 +305,12 @@ async function main() {
       runId: flags['run-id'],
       scope: flags.scope,
       url: flags.url,
-      apiKey: process.env.MEKO_API_KEY ?? null,
+      apiKey: normalizeApiKey(process.env.MEKO_API_KEY),
       projectRoot,
       noExtract: flags['no-extract'],
       force: flags.force,
       rate: childRate,
+      datapack: flags.datapack ?? null,
     });
     process.exit(code);
   }
@@ -257,7 +333,7 @@ async function main() {
       process.exit(1);
     }
     let url = flags.url ?? process.env.MEKO_MCP_URL ?? null;
-    let apiKey = flags['api-key'] ?? process.env.MEKO_API_KEY ?? null;
+    let apiKey = normalizeApiKey(flags['api-key'] ?? process.env.MEKO_API_KEY);
     if (flags.local) { url = 'http://localhost:8000/mcp'; apiKey = null; }
 
     let parentRate;
@@ -274,6 +350,8 @@ async function main() {
       noExtract: flags['no-extract'],
       force: flags.force,
       rate: parentRate,
+      nonInteractive: flags.yes,
+      datapack: flags.datapack ?? null,
     });
     console.log(out.message);
     process.exit(out.ok ? 0 : 1);
@@ -289,6 +367,15 @@ async function main() {
     process.exit(1);
   }
 
+  // Validate --scope BEFORE any branch that interpolates it into a shell
+  // command. The --uninstall path now forwards --scope to
+  // `claude plugin uninstall --scope <X>`, so an invalid value must be
+  // caught here, not after it's already been handed to the shell.
+  if (!isValidScope(flags.scope)) {
+    error(`Unknown scope "${flags.scope}". Valid values: user, project.`);
+    process.exit(1);
+  }
+
   // --uninstall
   if (flags.uninstall) {
     for (const client of clients) {
@@ -303,19 +390,20 @@ async function main() {
     }
     process.exit(0);
   }
-
-  if (!isValidScope(flags.scope)) {
-    error(`Unknown scope "${flags.scope}". Valid values: user, project.`);
-    process.exit(1);
-  }
   if (!isValidCursorHookMode(flags['cursor-hook-mode'])) {
-    error(`Unknown --cursor-hook-mode "${flags['cursor-hook-mode']}". Valid values: native, claude-compat, hybrid.`);
+    error(`Unknown --cursor-hook-mode "${flags['cursor-hook-mode']}". Valid values: native, claude-compat.`);
     process.exit(1);
   }
 
   let url    = flags.url    ?? null;
-  let apiKey = flags['api-key'] ?? null;
+  let apiKey = normalizeApiKey(flags['api-key']);
   let skipSkills = flags['skip-skills'];
+  // Tracks whether the full interactive flow already prompted for the API
+  // key. The Cloud-URL fallback below should only run for the
+  // semi-interactive `--url ... --client ...` paste path — otherwise
+  // submitting an empty value at the full-flow prompt would re-ask the
+  // same question.
+  let promptedForApiKey = false;
 
   // --local shortcut
   if (flags.local) {
@@ -336,6 +424,7 @@ async function main() {
         'claude-code': 'Claude Code',
         'claude-desktop': 'Claude Desktop',
         cursor: 'Cursor',
+        codex: 'OpenAI Codex (CLI + App)',
       }[id];
       return {
         label: id,
@@ -391,8 +480,11 @@ async function main() {
       // Step 2 — MCP URL
       url = await askText('MCP server URL (from app.mekodev.com > Datapacks > Connect):');
 
-      // Step 3 — API key
-      apiKey = await askSecret('API key:');
+      // Step 3 — API key. Normalize: terminal paste can drag in trailing
+      // whitespace/CR or accidental surrounding quotes, all of which would
+      // sail straight into `Authorization: Bearer ...` and 401.
+      apiKey = normalizeApiKey(await askSecret('API key:'));
+      promptedForApiKey = true;
     } else {
       url    = 'http://localhost:8000/mcp';
       apiKey = null;
@@ -414,9 +506,22 @@ async function main() {
     process.exit(1);
   }
 
-  // Validation — Cloud URL requires an API key
+  // Validation — Cloud URL requires an API key.
+  // Resolution order: --api-key (already in `apiKey`) → $MEKO_API_KEY →
+  // interactive prompt (only on a TTY, not under --yes, and only if the
+  // full interactive flow above didn't already ask). The prompt fallback
+  // exists so a user who pastes the cloud one-liner from the UI (which
+  // only shows --url and --client) isn't dead-ended on a hard error when
+  // they forgot to supply the key. Skipping it after a full-flow prompt
+  // avoids re-asking the same question when the user submitted empty.
   if (isCloudUrl(url) && !apiKey) {
-    apiKey = process.env.MEKO_API_KEY ?? null;
+    apiKey = normalizeApiKey(process.env.MEKO_API_KEY);
+    if (apiKey) {
+      dim('Using API key from MEKO_API_KEY environment variable.');
+    } else if (!flags.yes && !promptedForApiKey && process.stdin.isTTY) {
+      dim('No --api-key or MEKO_API_KEY env var found; prompting for API key.');
+      apiKey = normalizeApiKey(await askSecret('API key:'));
+    }
     if (!apiKey) {
       error(
         'API key is required for Cloud Meko. ' +
@@ -424,7 +529,6 @@ async function main() {
       );
       process.exit(1);
     }
-    dim('Using API key from MEKO_API_KEY environment variable.');
   }
 
   // Install — loop through each selected client sequentially so failures
@@ -439,6 +543,7 @@ async function main() {
         name:           flags.name,
         skipSkills,
         skipValidation: flags['skip-validation'],
+        skipCanary:     flags['no-canary'],
         dryRun:         flags['dry-run'],
         verbose:        flags.verbose,
         yes:            flags.yes,
@@ -472,6 +577,7 @@ async function main() {
         apiKey,
         scope: flags.scope,
         projectRoot,
+        datapack: flags.datapack ?? null,
       });
     } else if (flags.yes) {
       console.log('');
@@ -482,16 +588,35 @@ async function main() {
         apiKey,
         scope: flags.scope,
         projectRoot,
+        datapack: flags.datapack ?? null,
       });
     }
   }
+
+  // Upgrade hint — only print if the background probe finished in time.
+  // We race the check against a pre-resolved sentinel so an in-flight
+  // probe (slow network) is silently dropped instead of delaying exit.
+  try {
+    const raced = await Promise.race([
+      versionCheckPromise,
+      Promise.resolve({ timedOut: true }),
+    ]);
+    if (raced && raced.isOutdated === true && raced.latest && raced.current) {
+      info(
+        `A newer version is available (${raced.latest}, you have ${raced.current}). ` +
+        'Re-run with `npx @yugabytedb/meko-mcp@latest`.',
+      );
+    }
+  } catch {
+    /* never reached — checkLatest doesn't reject — but don't block exit. */
+  }
 }
 
 /**
  * Unattended migration — used by --yes --with-migrate.
  * No prompts; errors are surfaced but do not fail the install.
  */
-async function runUnattendedMigration({ url, apiKey, scope, projectRoot }) {
+async function runUnattendedMigration({ url, apiKey, scope, projectRoot, datapack }) {
   try {
     const out = await startMigration({
       url,
@@ -499,6 +624,8 @@ async function runUnattendedMigration({ url, apiKey, scope, projectRoot }) {
       scope,
       projectRoot,
       scriptPath: __filename,
+      nonInteractive: true,
+      datapack: datapack ?? null,
     });
     console.log('');
     console.log(out.message);
@@ -516,7 +643,7 @@ async function runUnattendedMigration({ url, apiKey, scope, projectRoot }) {
  * whether to kick off the detached migration. Any error here is non-fatal —
  * install has already succeeded.
  */
-async function maybeOfferMigration({ url, apiKey, scope, projectRoot }) {
+async function maybeOfferMigration({ url, apiKey, scope, projectRoot, datapack }) {
   try {
     const dry = await startMigration({
       url,
@@ -525,6 +652,7 @@ async function maybeOfferMigration({ url, apiKey, scope, projectRoot }) {
       projectRoot,
       scriptPath: __filename,
       dryRun: true,
+      datapack: datapack ?? null,
     });
     const s = dry?.message?.match(/Claude Code sessions: *(\d+)/);
     const c = dry?.message?.match(/Cursor sessions: *(\d+)/);
@@ -559,6 +687,7 @@ async function maybeOfferMigration({ url, apiKey, scope, projectRoot }) {
       scope,
       projectRoot,
       scriptPath: __filename,
+      datapack: datapack ?? null,
     });
     console.log(out.message);
   } catch (err) {