@lh8ppl/claude-memory-kit 0.2.4 → 0.3.1

package/src/subcommands.mjs

@@ -17,6 +17,7 @@ import { install as installAction, initUserTier as initUserTierAction } from './
 import { removeClaudeMdBlock } from './claude-md.mjs';
 import { reindex as reindexAction } from './reindex.mjs';
 import { openIndexDb } from './index-db.mjs';
+import { resolveDefaultSearchMode } from './semantic-backend.mjs';
 import { reindexBoot, reindexFull } from './index-rebuild.mjs';
 import { search as searchAction, SEARCH_MODES } from './search.mjs';
 import { memoryWrite } from './memory-write.mjs';
@@ -26,12 +27,14 @@ import { weeklyCurate } from './weekly-curate.mjs';
 import { autoPersona } from './auto-persona.mjs';
 import { exportPersona, importPersona } from './persona-portability.mjs';
 import { setNativeAutoMemory, nativeMemoryInstallNote } from './native-memory.mjs';
-import { rememberRich, richFactTitle, nonProjectTierNote } from './remember-core.mjs';
+import { rememberRich, richFactTitle, nonProjectTierNote, prepareNearDupGuard } from './remember-core.mjs';
 import { getObservations, citeLink, buildTimeline, recentActivity } from './read-core.mjs';
 import { readHookStdin } from './read-hook-stdin.mjs';
 import { runLazyCompress } from './lazy-compress.mjs';
 import { runDoctor } from './doctor.mjs';
 import { importAnthropicMemory } from './import-anthropic-memory.mjs';
+import { configGet, configSet, configShowOrigin } from './config-core.mjs';
+import { importClaudeMd } from './import-claude-md.mjs';
 import { extractTranscript, discoverSessions } from './transcripts.mjs';
 import { runRepair } from './repair.mjs';
 import { runRoll, ROLL_SCOPES } from './roll.mjs';
@@ -59,10 +62,38 @@ import { overrideTrust as overrideTrustAction } from './trust.mjs';
 import { resolveConflictQueue, mergeScratchpadBullets } from './conflict-queue.mjs';
 import { resolveReviewQueue } from './review-queue.mjs';
 import { createInterface } from 'node:readline';
+import { spawnSync } from 'node:child_process';
+import { checkKitBinding } from './native-binding.mjs';
 import { resolve as resolvePath, join, basename } from 'node:path';
 
 const NOTICE_PREFIX = 'not yet implemented';
 
+/**
+ * The install summary line for the Task-46 semantic outcome (Task 125.4:
+ * pure + exported so the branches are testable without running install).
+ * Returns null when there is nothing to print: an `error` action already
+ * surfaces through result.errors, and the opt-in tip is suppressed under
+ * --no-hooks (scaffold-only installs).
+ */
+export function formatSemanticSummary(semantic, { noHooks = false } = {}) {
+  if (semantic?.action === 'enabled') {
+    const w = semantic.warmed;
+    return (
+      '  Semantic recall ENABLED — `cmk search` now defaults to hybrid here.' +
+      (w?.ok
+        ? ` Model cached (${Math.round(w.ms / 1000)}s).`
+        : ' Model downloads on first search.')
+    );
+  }
+  if (semantic?.action === 'disabled') {
+    return '  Semantic recall pinned OFF for this project (search.default_mode=keyword).';
+  }
+  if (semantic?.action === 'skipped' && !noHooks) {
+    return '  Tip: `cmk install --with-semantic` adds local semantic recall (ask in your own words; one-time ~260 MB, no API calls).';
+  }
+  return null;
+}
+
 /**
  * Real `cmk install` action — wired in Task 3, extended in Task 4 with
  * --force passed through to the CLAUDE.md downgrade guard. Reads CLI
@@ -70,18 +101,94 @@ const NOTICE_PREFIX = 'not yet implemented';
  * summary, and reports the CLAUDE.md action (created / appended /
  * replaced / upgraded / downgrade-blocked / forced-downgrade / unchanged).
  */
-async function runInstall(options /* , command */) {
+// Task 141a (D-129): the install-time binding ask. npm 12 blocks
+// better-sqlite3's binding build on a fresh `npm install -g` — the user's
+// 2026-06-12 steer: ask AT INSTALL, never leave it to a secondary command.
+// Interactive consent is required because the fix is itself an
+// `npm install -g` (the design §14 ask-before-install rule); non-interactive
+// runs print the command instead. All deps injectable for tests.
+async function offerBindingFix(nativeBinding, options, { log, logError }) {
+  if (!nativeBinding || nativeBinding.ok) return;
+  const remedy = nativeBinding.remedy;
+  logError(
+    `  warning: better-sqlite3's native binding is unavailable (${nativeBinding.reason}).`,
+  );
+  logError(
+    '  Most common cause: npm 12 blocks dependency install scripts by default (a Node major upgrade is the other). Search/reindex cannot work until the binding is rebuilt.',
+  );
+  // An explicit askImpl implies a consent channel exists (the test seam /
+  // programmatic caller); only the readline default needs a real TTY.
+  const interactive =
+    options?.interactive ?? (options?.askImpl ? true : process.stdin.isTTY === true);
+  const askFn =
+    options?.askImpl ??
+    (interactive
+      ? (question) =>
+          new Promise((resolveAnswer) => {
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            rl.question(question, (answer) => {
+              rl.close();
+              resolveAnswer(answer);
+            });
+          })
+      : null);
+  if (!interactive || !askFn) {
+    logError(`  Fix it any time with: ${remedy}`);
+    return;
+  }
+  const answer = String(await askFn(`  Fix it now by running \`${remedy}\`? [Y/n] `))
+    .trim()
+    .toLowerCase();
+  const yes = answer === '' || answer === 'y' || answer === 'yes';
+  if (!yes) {
+    log(`  Skipped. Fix it any time with: ${remedy}`);
+    return;
+  }
+  const fixRunner =
+    options?.fixRunner ??
+    ((cmd) =>
+      // Constant command under shell:true (npm is npm.cmd on Windows); the
+      // 10-min ceiling mirrors buildDefaultNpmRunner's spawn discipline.
+      spawnSync(cmd, { stdio: 'inherit', shell: true, timeout: 600_000 }));
+  const r = fixRunner(remedy);
+  const reProbe = options?.reProbe ?? checkKitBinding;
+  const after = r.status === 0 ? reProbe() : { ok: false };
+  if (after.ok) {
+    log('  Binding rebuilt — search is ready.');
+  } else {
+    logError(`  The binding is still unavailable — run it manually later: ${remedy}`);
+  }
+}
+
+// Exported for tests (Task 141a) — dep-injectable (cwd / userTier / log /
+// logError / bindingProbe / askImpl / fixRunner / reProbe / interactive) on
+// the runImportClaudeMd pattern. Defaults unchanged for production.
+export async function runInstall(options /* , command */) {
+  const log = options?.log ?? console.log;
+  const logError = options?.logError ?? console.error;
   // commander maps `--no-hooks` to options.hooks === false.
   const noHooks = !!(options && options.hooks === false);
   const verbose = !!(options && options.verbose);
-  const result = await installAction({ force: !!(options && options.force), noHooks });
+  const result = await installAction({
+    force: !!(options && options.force),
+    noHooks,
+    // Task 46: two flags, 3-state semantics (enable / pin-off / untouched).
+    // commander maps `--no-semantic` to options.semantic === false (the
+    // same negation pattern as --no-hooks above); `--with-semantic` maps
+    // to options.withSemantic.
+    withSemantic: !!(options && options.withSemantic),
+    noSemantic: !!(options && options.semantic === false),
+    projectRoot: options?.cwd,
+    userTier: options?.userTier,
+    bindingProbe: options?.bindingProbe,
+  });
 
   // Outcome over inventory (self-test UX finding): state the resulting state +
   // next action, not a file tally. The old "scaffolded 5, skipped 4 existing"
   // read like a problem on a FRESH folder — the "skipped" are the cross-project
   // user tier at ~/.claude-memory-kit/ (OUTSIDE this folder), already on disk.
   // The full per-tier breakdown is --verbose only.
-  const projectName = basename(resolvePath(process.cwd()));
+  const projectName = basename(result.projectRoot);
   const wired =
     result.hooks.action === 'wired' || result.hooks.action === 'unchanged';
   const broughtSomethingNew =
@@ -90,20 +197,20 @@ async function runInstall(options /* , command */) {
     result.claudeMd.action === 'created';
 
   if (broughtSomethingNew) {
-    console.log(
+    log(
       `cmk install: ${projectName} ready — context/ scaffolded${
         wired ? ', hooks wired' : ''
       }.`,
     );
   } else {
-    console.log(
+    log(
       `cmk install: ${projectName} already set up (your edits preserved)${
         wired ? ', hooks refreshed' : ''
       }.`,
     );
   }
   if (wired) {
-    console.log(
+    log(
       '  Restart Claude Code to activate. Complete install — no separate /plugin step needed.',
     );
   }
@@ -111,30 +218,39 @@ async function runInstall(options /* , command */) {
   // Auto Memory by default; surface the one-command opt-out (null when already
   // opted out, so we don't nag).
   const nativeNote = nativeMemoryInstallNote(result.projectRoot);
-  if (nativeNote) console.log(nativeNote);
+  if (nativeNote) log(nativeNote);
+  // Task 46: semantic-recall outcome (pure formatter, Task 125.4 — testable
+  // without spawning install; the error case returns null because enableSemantic
+  // errors already land in result.errors and print through the error path).
+  const semanticLine = formatSemanticSummary(result.semantic, { noHooks });
+  if (semanticLine) log(semanticLine);
   if (verbose) {
-    console.log(
+    log(
       `  files: ${result.created.length} created, ${result.skipped.length} already present` +
         (result.skipped.length
           ? ' (incl. the cross-project user tier at ~/.claude-memory-kit/, outside this folder)'
           : ''),
     );
-    console.log(
+    log(
       `  .gitignore=${result.gitignore.action} · CLAUDE.md=${result.claudeMd.action} · hooks=${result.hooks.action}`,
     );
   }
 
   if (result.claudeMd.action === 'downgrade-blocked') {
-    console.error(
+    logError(
       `  warning: CLAUDE.md already has a newer kit block (v${result.claudeMd.oldVersion}). ` +
         `Re-run with --force to downgrade.`
     );
   }
 
   if (result.errors.length > 0) {
-    for (const e of result.errors) console.error(`  error: ${e.path}: ${e.error}`);
+    for (const e of result.errors) logError(`  error: ${e.path}: ${e.error}`);
     process.exitCode = 1;
   }
+
+  // Task 141a: the binding ask comes LAST — it's the one thing the user may
+  // still need to act on, and the tail of install output is what gets read.
+  await offerBindingFix(result.nativeBinding, options, { log, logError });
 }
 
 /**
@@ -251,8 +367,9 @@ function runLessonsPromote(id, options = {}) {
  *
  * The keyword backend (FTS5 BM25 over the observations index) always
  * ships. Semantic + hybrid modes require the Layer-5b semantic backend,
- * which is not yet shipped; both error with exit code 2 and a clear
- * "not yet shipped" hint per tasks.md 30.2. The `semanticBackend` DI seam
+ * (Task 65: prepared automatically when the optional embedder is installed;
+ * absent embedder errors with exit code 2 + an install hint, per the 30.2
+ * contract). The `semanticBackend` DI seam
  * is the drop-in point for the future backend.
  *
  * Filter flags (per tasks.md 30.4):
@@ -263,7 +380,7 @@ function runLessonsPromote(id, options = {}) {
  *   --limit <N>                        (default 20)
  *   --include-tombstoned               (default false)
  */
-function runSearch(queryParts, options) {
+async function runSearch(queryParts, options) {
   const projectRoot = resolvePath(process.cwd());
   const userDir =
     process.env.MEMORY_KIT_USER_DIR ?? join(homedir(), '.claude-memory-kit');
@@ -287,15 +404,51 @@ function runSearch(queryParts, options) {
           'searching the existing index. Run `cmk reindex --full` if results look stale.',
       );
     }
+    // Task 65: semantic/hybrid prepare the REAL embedded backend (async —
+    // search() itself stays sync; the seam gets a sync closure over the
+    // pre-embedded query vector). Task 46: an explicit --mode wins;
+    // otherwise the project's configured default (context/settings.json
+    // search.default_mode, set by `cmk install --with-semantic`), falling
+    // back to keyword. Explicit-but-unavailable → exit 2 + hint (the 30.2
+    // contract); configured-but-unavailable → graceful keyword fallback
+    // (the default must never break every search).
+    const explicitMode = options?.mode;
+    let mode = explicitMode ?? resolveDefaultSearchMode({ projectRoot });
+    // Task 104.2 — the L3 raw tier: `--scope transcripts` searches the
+    // separate transcript-chunk index (synthetic T: ids; no tier/trust).
+    const scope = options?.scope ?? 'facts';
+    let semanticBackend;
+    if (mode === SEARCH_MODES.SEMANTIC || mode === SEARCH_MODES.HYBRID) {
+      const { prepareSemanticBackend } = await import('./semantic-backend.mjs');
+      const prep = await prepareSemanticBackend({ db, query, scope });
+      if (!prep.ok && explicitMode) {
+        console.error(
+          `cmk search: semantic backend unavailable (${prep.reason}).` +
+            (prep.hint ? `\n  ${prep.hint}` : ' Use --mode=keyword.'),
+        );
+        process.exitCode = 2;
+        return;
+      }
+      if (!prep.ok) {
+        console.error(
+          `cmk search: semantic default unavailable (${prep.reason}) — falling back to keyword.`,
+        );
+        mode = SEARCH_MODES.KEYWORD;
+      } else {
+        semanticBackend = prep.backend;
+      }
+    }
     const r = searchAction({
       db,
       query,
-      mode: options?.mode ?? SEARCH_MODES.KEYWORD,
+      mode,
+      scope,
       minTrust: options?.minTrust,
       tier: options?.tier,
       since: options?.since,
       limit: options?.limit !== undefined ? Number(options.limit) : undefined,
       includeTombstoned: options?.includeTombstoned === true,
+      semanticBackend,
     });
     if (r.action === 'error') {
       for (const e of r.errors) console.error(`cmk search: ${e}`);
@@ -311,13 +464,15 @@ function runSearch(queryParts, options) {
     for (const hit of r.results) {
       // Plain-text output suitable for terminal piping. Snippet uses
       // FTS5's <b>...</b> markers; preserved as-is so callers can pipe
-      // to a TUI that renders them OR strip via sed.
+      // to a TUI that renders them OR strip via sed. Transcript hits carry
+      // no tier/trust (raw chunks) — the column shows the scope instead.
+      const provenance = hit.tier ? `${hit.tier}/${hit.trust}` : 'transcript';
       console.log(
-        `${hit.id}\t${hit.tier}/${hit.trust}\t${hit.source_file}:${hit.source_line}\t${hit.snippet}`,
+        `${hit.id}\t${provenance}\t${hit.source_file}:${hit.source_line}\t${hit.snippet}`,
       );
     }
     console.log(
-      `\ncmk search: ${r.results.length} result(s) (mode=${r.mode})`,
+      `\ncmk search: ${r.results.length} result(s) (mode=${r.mode}${r.scope && r.scope !== 'facts' ? `, scope=${r.scope}` : ''})`,
     );
   } finally {
     db.close();
@@ -576,7 +731,10 @@ export function parseFactInput(options, { readFile, readStdin } = {}) {
   };
 }
 
-export function runRemember(textParts, options, deps = {}) {
+// Task 143: async since the near-dup guard may embed the incoming text
+// (one model call, explicit path only). Commander awaits actions; the
+// terse-path tests were updated to await (contract change, intent preserved).
+export async function runRemember(textParts, options, deps = {}) {
   const projectRoot = deps.projectRoot ?? resolvePath(process.cwd());
   const userDir =
     deps.userDir ?? process.env.MEMORY_KIT_USER_DIR ?? join(homedir(), '.claude-memory-kit');
@@ -637,6 +795,10 @@ export function runRemember(textParts, options, deps = {}) {
   const tier = 'P';
   const trust = options?.trust ?? 'high';
   const section = options?.section ?? 'Active Threads';
+  // Task 143 (D-130): semantic near-dup guard — extra opts only when this
+  // project is semantic-configured and the embedder is available; {} keeps
+  // the literal pipeline (graceful degradation, never blocks capture).
+  const nearDup = await prepareNearDupGuard({ projectRoot, text, ...(deps.nearDupGuard ? { prepareImpl: deps.nearDupGuard.prepareImpl, resolveModeImpl: deps.nearDupGuard.resolveModeImpl } : {}) });
   const r = memoryWrite({
     action: 'add',
     text,
@@ -647,22 +809,23 @@ export function runRemember(textParts, options, deps = {}) {
     source: 'user-explicit',
     projectRoot,
     userDir,
+    ...nearDup,
   });
   if (r.action === 'error') {
     for (const e of r.errors ?? [`error (${r.errorCategory})`]) {
-      console.error(`cmk remember: ${e}`);
+      logError(`cmk remember: ${e}`);
     }
     process.exitCode = 2;
     return;
   }
   if (r.action === 'queued') {
-    console.log(
-      `cmk remember: queued for review — a higher-trust fact already covers this. ` +
+    log(
+      `cmk remember: queued for review — a similar or higher-trust fact already covers this. ` +
         `Resolve with \`cmk queue conflicts\` (${r.path}).`,
     );
     return;
   }
-  console.log(
+  log(
     `cmk remember: saved to P/MEMORY.md (${section})${r.id ? ` [${r.id}]` : ''}`,
   );
 }
@@ -1103,12 +1266,93 @@ async function runDoctorCli(/* options */) {
       `Summary: ${counts.pass} pass · ${counts.fail} fail · ${counts.skip} skip (${r.duration_ms}ms)`,
     );
     if (counts.fail > 0) process.exitCode = 1;
+
+    // Task 144 (D-130): the memory-HEALTH section — content quality, not
+    // plumbing. Informational only: read-only, never changes the exit code,
+    // best-effort (a content-stat hiccup must not fail a healthy doctor).
+    try {
+      const { analyzeMemoryHealth, formatMemoryHealth } = await import('./memory-health.mjs');
+      console.log('');
+      console.log(formatMemoryHealth(analyzeMemoryHealth({ projectRoot })));
+    } catch {
+      // informational section only — stay silent on failure
+    }
   } catch (err) {
     console.error(`cmk doctor: unexpected error: ${err?.message ?? err}`);
     process.exitCode = 2;
   }
 }
 
+// Task 129 (D-121): `cmk config` — real, replacing the v0.1.0 stub. Dotted-key
+// get/set/--show-origin over the per-tier settings.json files. Dep-injectable
+// (cwd/userDir/log/logError) on the runImportClaudeMd pattern for testing the
+// CLI surface. The pure resolution/mutation lives in config-core.mjs.
+const TIER_FLAG_TO_NAME = { local: 'local', project: 'project', user: 'user' };
+
+export function runConfigGet(key, options = {}) {
+  const projectRoot = options?.cwd ?? resolvePath(process.cwd());
+  const userDir = options?.userDir ?? join(homedir(), '.claude-memory-kit');
+  const log = options?.log ?? console.log;
+  const logError = options?.logError ?? console.error;
+  const r = configGet(key, { projectRoot, userDir });
+  if (!r.found) {
+    logError(`cmk config get: '${key}' is not set in any tier`);
+    process.exitCode = 2;
+    return r;
+  }
+  log(typeof r.value === 'string' ? r.value : JSON.stringify(r.value));
+  return r;
+}
+
+export function runConfigSet(key, value, options = {}) {
+  const projectRoot = options?.cwd ?? resolvePath(process.cwd());
+  const userDir = options?.userDir ?? join(homedir(), '.claude-memory-kit');
+  const log = options?.log ?? console.log;
+  const logError = options?.logError ?? console.error;
+  const tier = TIER_FLAG_TO_NAME[options?.tier ?? 'project'] ?? 'project';
+  const r = configSet(key, value, { projectRoot, userDir, tier });
+  if (!r.ok) {
+    logError(`cmk config set: ${r.error}`);
+    process.exitCode = 2;
+    return r;
+  }
+  log(`cmk config set: ${key} = ${value} (${r.tier} tier)`);
+  return r;
+}
+
+export function runConfigShowOrigin(key, options = {}) {
+  const projectRoot = options?.cwd ?? resolvePath(process.cwd());
+  const userDir = options?.userDir ?? join(homedir(), '.claude-memory-kit');
+  const log = options?.log ?? console.log;
+  const logError = options?.logError ?? console.error;
+  const r = configShowOrigin(key, { projectRoot, userDir });
+  if (!r.found) {
+    logError(`cmk config --show-origin: '${key}' is not set in any tier`);
+    process.exitCode = 2;
+    return r;
+  }
+  for (const e of r.entries) {
+    const val = typeof e.value === 'string' ? `"${e.value}"` : JSON.stringify(e.value);
+    const note = e.winner ? '' : `   (shadowed by ${e.shadowedBy})`;
+    log(`${e.tier.padEnd(8)} ${e.path}   ${val}${note}`);
+  }
+  return r;
+}
+
+// The parent `cmk config` action: handle the --show-origin flag here; the
+// get/set children carry their own actions (wired in the registry below).
+// Exported for the branch test (the no-subcommand path).
+export function runConfigCli(options /* , command */) {
+  if (options?.showOrigin) {
+    return runConfigShowOrigin(options.showOrigin, options);
+  }
+  const logError = options?.logError ?? console.error;
+  logError(
+    'cmk config: specify a subcommand — `get <key>`, `set <key> <value>`, or `--show-origin <key>`.',
+  );
+  process.exitCode = 2;
+}
+
 async function runRepairCli(options /* , command */) {
   const projectRoot = resolvePath(process.cwd());
   const userDir = join(homedir(), '.claude-memory-kit');
@@ -1224,6 +1468,59 @@ export async function runImportAnthropicMemory(options = {}) {
   }
 }
 
+// Task 142 (D-130): onboard from an existing rules file. Dep-injectable
+// (projectRoot / log / logError / importFn) on the runImportAnthropicMemory
+// pattern so the real CLI path is verifiable in a sandbox. `file` is the
+// optional positional (commander passes it first), defaulting to CLAUDE.md.
+export async function runImportClaudeMd(file, options = {}) {
+  const projectRoot = options?.projectRoot ?? resolvePath(process.cwd());
+  const log = options?.log ?? console.log;
+  const logError = options?.logError ?? console.error;
+  const dryRun = options?.dryRun === true;
+  const acceptAll = options?.yes === true;
+  const importFn = options?.importFn ?? importClaudeMd;
+  try {
+    const r = await importFn({ projectRoot, file, dryRun, acceptAll });
+    if (r.action === 'error') {
+      logError(`cmk import-claude-md: error — ${(r.errors ?? []).join('; ')}`);
+      process.exitCode = 2;
+      return r;
+    }
+    if (r.reason === 'no-source') {
+      log(`cmk import-claude-md: no rules file found at ${r.sourcePath}`);
+      return r;
+    }
+    if (r.reason) {
+      // e.g. read-source-failed — completed-with-failure must not print the
+      // success-shaped "applied 0" line (skill-review 2026-06-12 finding).
+      logError(`cmk import-claude-md: ${r.reason} (${r.sourcePath})`);
+      process.exitCode = 2;
+      return r;
+    }
+    const listProposals = () => {
+      for (const p of r.proposals) log(`  + [${p.type}] L${p.line}: ${p.text}`);
+    };
+    if (r.mode === 'dry-run') {
+      log(`cmk import-claude-md: dry-run — ${r.proposals.length} proposal(s), ${r.skipped} duplicate(s) skipped`);
+      listProposals();
+      return r;
+    }
+    if (r.mode === 'requires-confirmation') {
+      log(`cmk import-claude-md: ${r.proposals.length} proposal(s) ready to apply.`);
+      log('  Re-run with --yes to apply, or --dry-run to inspect.');
+      listProposals();
+      return r;
+    }
+    const rejectedNote = r.rejected > 0 ? `, ${r.rejected} rejected by Poison_Guard` : '';
+    const errorNote = r.errors > 0 ? `, ${r.errors} error(s)` : '';
+    log(`cmk import-claude-md: applied ${r.accepted} fact(s), skipped ${r.skipped} duplicate(s)${rejectedNote}${errorNote}`);
+    return r;
+  } catch (err) {
+    logError(`cmk import-claude-md: unexpected error: ${err?.message ?? err}`);
+    process.exitCode = 2;
+  }
+}
+
 async function runTranscriptsDispatch(childName, options) {
   if (childName === 'extract') {
     return runTranscriptsExtract(options);
@@ -1346,7 +1643,10 @@ async function runMcpDispatch(childName) {
     }
     return;
   }
-  console.error(`cmk mcp: ${NOTICE_PREFIX} (unknown sub-verb '${childName}')`);
+  // A bare `cmk mcp` (no sub-verb) reaches here post-Task-129 (the parent
+  // action is now wired) — commander passes an options object, not a string.
+  const verb = typeof childName === 'string' ? childName : '(none)';
+  console.error(`cmk mcp: ${NOTICE_PREFIX} (run \`cmk mcp serve\`; got sub-verb '${verb}')`);
   process.exitCode = 2;
 }
 
@@ -1357,7 +1657,10 @@ async function runQueueDispatch(childName) {
   if (childName === 'review') {
     return runQueueReview();
   }
-  console.log(`cmk queue: ${NOTICE_PREFIX} (unknown sub-verb '${childName}')`);
+  // A bare `cmk queue` reaches here post-Task-129 (parent action wired);
+  // commander passes an options object, not a string sub-verb.
+  const verb = typeof childName === 'string' ? childName : '(none)';
+  console.log(`cmk queue: ${NOTICE_PREFIX} (run \`cmk queue review\` or \`cmk queue conflicts\`; got '${verb}')`);
   process.exitCode = 2;
 }
 
@@ -1611,6 +1914,8 @@ export const subcommands = [
     optionSpec: [
       { flags: '--force', description: 'allow downgrade of an existing newer-version CLAUDE.md block' },
       { flags: '--no-hooks', description: 'scaffold only; do NOT wire hooks into .claude/settings.json' },
+      { flags: '--with-semantic', description: 'enable semantic recall: install the local embedder (~260 MB once), default search to hybrid, pre-warm the model' },
+      { flags: '--no-semantic', description: 'pin keyword-only search for this project (writes search.default_mode=keyword)' },
       { flags: '--verbose', description: 'show the per-tier created/skipped file breakdown' },
     ],
     action: runInstall,
@@ -1653,7 +1958,8 @@ export const subcommands = [
     milestone: 30,
     argSpec: [{ flags: '<query...>', description: 'query terms' }],
     optionSpec: [
-      { flags: '--mode <mode>', description: 'keyword | semantic | hybrid (default: keyword; semantic + hybrid need the Layer-5b semantic backend, not yet shipped)' },
+      { flags: '--mode <mode>', description: 'keyword | semantic | hybrid (default: keyword; semantic + hybrid use the embedded Layer-5b backend — needs the optional @huggingface/transformers embedder)' },
+      { flags: '--scope <scope>', description: 'facts | transcripts (default: facts — curated memory; transcripts = the raw session record, the last-resort recall tier)' },
       { flags: '--min-trust <level>', description: 'low | medium | high' },
       { flags: '--tier <tier>', description: 'U | P | L (filter to a single tier)' },
       { flags: '--since <date>', description: 'ISO date — exclude observations older than this' },
@@ -1715,34 +2021,32 @@ export const subcommands = [
   },
   {
     name: 'config',
-    description: 'settings access (per design §7.2)',
-    milestone: 'v0.1.x',
+    description: 'read/write kit settings (context/settings.json) without hand-editing JSON',
+    milestone: 129,
     optionSpec: [
-      { flags: '--show-origin <key>', description: 'print where each value comes from (project / user / local tier)' },
+      { flags: '--show-origin <key>', description: 'print every tier that defines a setting (winner + shadowed) — the "where did this come from?" debug surface' },
     ],
     children: [
       {
         name: 'get',
-        description: 'print the resolved value of a setting',
-        argSpec: [{ flags: '<key>', description: 'setting key (dotted path)' }],
+        description: 'print the resolved value of a setting (dotted key; local > project > user)',
+        argSpec: [{ flags: '<key>', description: 'setting key (dotted path, e.g. search.default_mode)' }],
+        action: (key, options) => runConfigGet(key, options),
       },
       {
         name: 'set',
-        description: 'set a setting in the current tier',
+        description: 'set a setting in the project tier (or --local)',
         argSpec: [
           { flags: '<key>', description: 'setting key (dotted path)' },
-          { flags: '<value>', description: 'new value' },
+          { flags: '<value>', description: 'new value (true/false/number coerced; else string)' },
         ],
+        optionSpec: [
+          { flags: '--local', description: 'write to the local tier (context.local/, gitignored) instead of project' },
+        ],
+        action: (key, value, options) => runConfigSet(key, value, { tier: options?.local ? 'local' : 'project' }),
       },
     ],
-    action: stub('config', 'v0.1.x'),
-  },
-  {
-    name: 'view',
-    description: 'open a local markdown viewer at 127.0.0.1:37778',
-    milestone: 'v0.1.x',
-    optionSpec: [{ flags: '--port <n>', description: 'override default port 37778' }],
-    action: stub('view', 'v0.1.x'),
+    action: runConfigCli,
   },
   {
     name: 'import-anthropic-memory',
@@ -1754,6 +2058,19 @@ export const subcommands = [
     ],
     action: runImportAnthropicMemory,
   },
+  {
+    name: 'import-claude-md',
+    description: 'onboard from an existing rules file (CLAUDE.md / .cursorrules / AGENTS.md) — parse it into typed facts through the safe write path',
+    milestone: 142,
+    argSpec: [
+      { flags: '[file]', description: 'rules file to import, relative to the project root (default: CLAUDE.md)' },
+    ],
+    optionSpec: [
+      { flags: '--dry-run', description: 'preview the typed proposals without modifying files' },
+      { flags: '--yes', description: 'apply every proposal without prompting (apply requires explicit --yes)' },
+    ],
+    action: runImportClaudeMd,
+  },
   {
     name: 'transcripts',
     description: "extract clean markdown transcripts from Claude Code session jsonls under ~/.claude/projects/",