@krimto-labs/krimto 0.2.27 → 0.2.34

package/bin/krimto.mjs

@@ -6,16 +6,40 @@
 import process from "node:process";
 import { tsImport } from "tsx/esm/api";
 
+/**
+ * v0.2.34 — collect every value passed via a repeating flag. Used by `editors --add cursor
+ * --add codex` and similar. Accepts both `--flag value` and `--flag=value` forms; ignores
+ * the flag itself.
+ */
+function collectFlagValues(flags, name) {
+  const values = [];
+  for (let i = 0; i < flags.length; i++) {
+    const f = flags[i];
+    if (f === name) {
+      if (typeof flags[i + 1] === "string") values.push(flags[i + 1]);
+    } else if (typeof f === "string" && f.startsWith(`${name}=`)) {
+      values.push(f.slice(name.length + 1));
+    }
+  }
+  return values;
+}
+
 try {
   // Two-word command support (v0.2.17.1): `team init`, `team disband`. Collapse argv[2]+argv[3]
   // into one cmd string when argv[2] is one of the namespaced verbs.
   const rawCmd = process.argv[2];
+  const sub = process.argv[3];
+  // v0.2.32 — `service stop` / `service start` are explicit, scriptable subverbs (no prompt).
+  // `service` alone still launches the interactive wizard. Mirrors the team/set two-word shape.
+  const serviceSubverbs = ["stop", "start"];
   const cmd =
-    rawCmd === "team" && typeof process.argv[3] === "string"
-      ? `team ${process.argv[3]}`
-      : rawCmd === "set" && typeof process.argv[3] === "string"
-        ? `set ${process.argv[3]}`
-        : rawCmd;
+    rawCmd === "team" && typeof sub === "string"
+      ? `team ${sub}`
+      : rawCmd === "set" && typeof sub === "string"
+        ? `set ${sub}`
+        : rawCmd === "service" && typeof sub === "string" && serviceSubverbs.includes(sub)
+          ? `service ${sub}`
+          : rawCmd;
 
   // Guard: `krimto team` alone (or with an unknown subverb) shouldn't fall through to the stdio
   // MCP server. Print usage and exit instead.
@@ -138,8 +162,13 @@ try {
             "  3. Verify it landed: $ npx @krimto-labs/krimto verify-connection\n" +
             mcpWarning +
             "\n" +
-            "To undo:  $ npx @krimto-labs/krimto uninit\n" +
-            "Manual:   delete the block between <!-- krimto:start --> and <!-- krimto:end -->\n\n",
+            // v0.2.32 — three honest off-ramps, three blast radii. The old single line said
+            // "To undo: krimto uninit" which only stripped this project's rule files; users
+            // were stranded thinking they had a working stop button when the service kept
+            // running on their machine.
+            "To stop the service:        $ npx @krimto-labs/krimto stop\n" +
+            "To undo this project only:  $ npx @krimto-labs/krimto uninit\n" +
+            "To disconnect everything:   $ npx @krimto-labs/krimto reset       (notes preserved)\n\n",
         );
       }
     } else if (yes) {
@@ -211,6 +240,16 @@ try {
   } else if (cmd === "uninit") {
     // `krimto uninit` — remove the always-use-Krimto rule from this project's rules files,
     // flipping the project back from AUTO MODE to DEFAULT MODE.
+    //
+    // v0.2.32: the smoke-6 audit caught users assuming `uninit` was the full undo button —
+    // it wasn't (the background service kept running). After rule removal, if a service
+    // and/or a live krimto process is detected on this machine, we now ask whether the
+    // user also wants to stop it. Default is No (the service is machine-wide; other
+    // projects may use it). The flag `--also-stop` skips the prompt; `--keep-running`
+    // explicitly suppresses it (for scripted runs).
+    const flags = process.argv.slice(3);
+    const alsoStopFlag = flags.includes("--also-stop");
+    const keepRunningFlag = flags.includes("--keep-running");
     const { runUninit } = await tsImport("../src/cli/uninit.ts", import.meta.url);
     const res = await runUninit(process.cwd());
     if (res.cleaned.length === 0) {
@@ -232,11 +271,83 @@ try {
       body += "  Run `krimto init` to switch back to AUTO MODE.\n";
       body += "\n  Restart your editor so it picks up the change.\n\n";
       process.stderr.write(body);
+
+      // Now offer to stop the service. Skip the prompt if either flag was passed.
+      if (!keepRunningFlag) {
+        const { isServiceInstalled, detectPlatform } = await tsImport("../src/cli/service.ts", import.meta.url);
+        const svc = await isServiceInstalled(detectPlatform());
+        if (svc.installed) {
+          let stop = alsoStopFlag;
+          if (!alsoStopFlag && process.stdin.isTTY === true) {
+            const { confirmStop } = await tsImport("../src/cli/stopCmd.ts", import.meta.url);
+            process.stderr.write(
+              "ℹ️  The background service is still running on this machine — other projects may use it.\n",
+            );
+            stop = await confirmStop();
+          }
+          if (stop) {
+            const { runStop } = await tsImport("../src/cli/stopCmd.ts", import.meta.url);
+            const { resolveDataDir } = await tsImport("../src/server/index.ts", import.meta.url);
+            const stopRes = await runStop({ dataDir: resolveDataDir() });
+            process.stdout.write(stopRes.message);
+          }
+        }
+      }
     }
   } else if (cmd === "where") {
-    // `krimto where` — print the data directory (honors KRIMTO_DATA), so files aren't a surprise.
+    // `krimto where` — print the data directory. v0.2.31: deprecated in favour of
+    // `krimto status` (which shows the data dir + everything else in one screen). Output is
+    // preserved for scripts that grep for the path; deprecation hint goes to stderr so it
+    // doesn't break pipes like `cd "$(krimto where)"`.
     const { resolveDataDir } = await tsImport("../src/server/index.ts", import.meta.url);
     process.stdout.write(`${resolveDataDir()}\n`);
+    process.stderr.write("\n→ `krimto where` is now part of `krimto status` (the data-dir is in the Storage block).\n");
+  } else if (cmd === "folder") {
+    // `krimto folder` — guided move of the data dir. v0.2.31. Stops the service (if any),
+    // moves the dir (atomic when same filesystem; cp+rm fallback for EXDEV), reinstalls the
+    // service with the new KRIMTO_DATA env, prints an export hint for the user's shell.
+    const flags = process.argv.slice(3);
+    const toIdx = flags.indexOf("--to");
+    const to = toIdx >= 0 ? flags[toIdx + 1] : undefined;
+    const yes = flags.includes("--yes");
+    const { runFolderCmd } = await tsImport("../src/cli/folderCmd.ts", import.meta.url);
+    const { resolveDataDir } = await tsImport("../src/server/index.ts", import.meta.url);
+    const result = await runFolderCmd({
+      from: resolveDataDir(),
+      ...(to ? { to } : {}),
+      yes,
+    });
+    if (result !== null) {
+      process.stdout.write(result.message);
+      if (result.status === "error") process.exitCode = 1;
+    }
+  } else if (cmd === "remote") {
+    // `krimto remote` — friendly wrapper around setup-remote: show current / set new / remove.
+    // v0.2.31. Reuses runSetupRemote for the set path so URL validation + first-push verification
+    // happen in one place.
+    const flags = process.argv.slice(3);
+    const action = flags.includes("--show")
+      ? "show"
+      : flags.includes("--remove")
+        ? "remove"
+        : flags.includes("--set")
+          ? "set"
+          : undefined;
+    const setIdx = flags.indexOf("--set");
+    const url = setIdx >= 0 ? flags[setIdx + 1] : undefined;
+    const yes = flags.includes("--yes");
+    const { runRemoteCmd } = await tsImport("../src/cli/remoteCmd.ts", import.meta.url);
+    const { resolveDataDir } = await tsImport("../src/server/index.ts", import.meta.url);
+    const result = await runRemoteCmd({
+      dataDir: resolveDataDir(),
+      ...(action ? { action } : {}),
+      ...(url ? { url } : {}),
+      yes,
+    });
+    if (result !== null) {
+      process.stdout.write(result.message);
+      if (result.setupResult && result.setupResult.status !== "ok") process.exitCode = 1;
+    }
   } else if (cmd === "setup-remote") {
     // `krimto setup-remote <url>` — point the data dir's git repo at a remote and verify a push.
     // Krimto must NOT be running while this is invoked (locks the .git/ index).
@@ -260,31 +371,139 @@ try {
     process.stdout.write(result.message);
     if (result.status === "error") process.exitCode = 1;
   } else if (cmd === "verify-connection") {
-    // `krimto verify-connection` — read the lockfile + activity JSONL to answer "is my agent
-    // actually calling Krimto right now?" Works from any terminal regardless of how Krimto launched.
+    // `krimto verify-connection` — v0.2.31: deprecated in favour of `krimto status` (which
+    // includes the same lock + activity + sync info as one of its blocks). Existing output
+    // preserved verbatim so existing scripts/READMEs keep working; deprecation hint to stderr.
     const { runVerifyConnection } = await tsImport("../src/cli/verifyConnection.ts", import.meta.url);
     const { resolveDataDir } = await tsImport("../src/server/index.ts", import.meta.url);
     const result = await runVerifyConnection(resolveDataDir());
     process.stdout.write(result.message);
+    process.stderr.write("\n→ `krimto verify-connection` is now part of `krimto status` (one command, four answers).\n");
     if (result.status === "none") process.exitCode = 1;
   } else if (cmd === "editors") {
-    // `krimto editors` — one-question shortcut to add/remove editor connections (Phase B).
-    const { runEditors } = await tsImport("../src/cli/editors.ts", import.meta.url);
-    const result = await runEditors();
-    if (result === null) process.exitCode = 1;
+    // `krimto editors` — Phase B shortcut. v0.2.34 added flag forms for AI-agent + CI use:
+    //   --add <name>       Connect one editor (merge with current set). Repeatable.
+    //   --remove <name>    Disconnect one editor (merge with current set). Repeatable.
+    //   --set <list>       Replace the entire connected set (comma-separated).
+    //   --list             Print current connected editors, one per line.
+    // No flags + TTY → interactive checkbox wizard (unchanged).
+    // No flags + no TTY → the new assertInteractiveOrUsage guard prints flag usage and exits 2.
+    const flags = process.argv.slice(3);
+    if (flags.includes("--list")) {
+      const { listConnectedEditors } = await tsImport("../src/cli/editors.ts", import.meta.url);
+      const connected = await listConnectedEditors();
+      for (const e of connected) process.stdout.write(`${e}\n`);
+    } else {
+      const adds = collectFlagValues(flags, "--add");
+      const removes = collectFlagValues(flags, "--remove");
+      const setIdx = flags.indexOf("--set");
+      const setValue = setIdx >= 0 ? flags[setIdx + 1] : undefined;
+      const yes = flags.includes("--yes");
+      const { runEditors, parseEditorList, listConnectedEditors } = await tsImport(
+        "../src/cli/editors.ts",
+        import.meta.url,
+      );
+      if (adds.length > 0 || removes.length > 0 || setValue !== undefined) {
+        // Programmatic path — compute the target set and call applyEditors directly through
+        // the wrapper. `editors` option short-circuits the prompt.
+        let target;
+        try {
+          if (setValue !== undefined) {
+            target = parseEditorList([setValue]);
+          } else {
+            const current = await listConnectedEditors();
+            const toAdd = parseEditorList(adds);
+            const toRemove = new Set(parseEditorList(removes));
+            target = [...current];
+            for (const a of toAdd) if (!target.includes(a)) target.push(a);
+            target = target.filter((e) => !toRemove.has(e));
+          }
+        } catch (err) {
+          process.stderr.write(`krimto editors: ${err instanceof Error ? err.message : String(err)}\n`);
+          process.exit(2);
+        }
+        const result = await runEditors({ editors: target, ...(yes ? { yes: true } : {}) });
+        if (result === null) process.exitCode = 1;
+      } else {
+        // No flags — TTY user gets the interactive checkbox; agents get the guard's usage.
+        const result = await runEditors();
+        if (result === null) process.exitCode = 1;
+      }
+    }
   } else if (cmd === "search") {
     // `krimto search` — change the search provider (Keyword vs OpenAI) without re-running the
-    // whole setup wizard (Phase B).
+    // whole setup wizard (Phase B). v0.2.34 added flag forms for agent / CI use:
+    //   --keyword                   Switch to keyword search (default, no API key).
+    //   --openai --api-key sk-...   Switch to OpenAI semantic search (key verified first).
+    // No flags + TTY → interactive select; no flags + no TTY → guard prints usage + exit 2.
+    const flags = process.argv.slice(3);
+    const keyword = flags.includes("--keyword");
+    const openai = flags.includes("--openai");
+    const apiKeyIdx = flags.indexOf("--api-key");
+    const keyIdx = flags.indexOf("--key");
+    const apiKey =
+      apiKeyIdx >= 0 ? flags[apiKeyIdx + 1] : keyIdx >= 0 ? flags[keyIdx + 1] : undefined;
     const { runSearchSettings } = await tsImport("../src/cli/searchSettings.ts", import.meta.url);
-    const result = await runSearchSettings();
-    if (result === null) process.exitCode = 1;
+    if (keyword) {
+      const result = await runSearchSettings({ provider: "keyword" });
+      if (result === null) process.exitCode = 1;
+    } else if (openai) {
+      if (!apiKey) {
+        process.stderr.write("krimto search --openai requires --api-key <sk-...>\n");
+        process.exit(2);
+      }
+      const result = await runSearchSettings({ provider: "openai", apiKey });
+      if (result === null) process.exitCode = 1;
+    } else {
+      // No flags — TTY user gets the interactive select; agents get the guard's usage.
+      const result = await runSearchSettings();
+      if (result === null) process.exitCode = 1;
+    }
   } else if (cmd === "service") {
     // `krimto service` — change run mode (as-needed / always-running / manual). Installs or
-    // uninstalls the platform service to match (Phase B).
+    // uninstalls the platform service to match (Phase B). v0.2.32: accepts `--as-needed`,
+    // `--always` (alias for --always-running), or `--manual` to skip the prompt for scripts.
+    const flags = process.argv.slice(3);
+    const flagMode = flags.includes("--as-needed")
+      ? "as-needed"
+      : flags.includes("--always") || flags.includes("--always-running")
+        ? "always-running"
+        : flags.includes("--manual")
+          ? "manual"
+          : undefined;
     const { runServiceCmd } = await tsImport("../src/cli/serviceCmd.ts", import.meta.url);
     const { resolveDataDir } = await tsImport("../src/server/index.ts", import.meta.url);
-    const result = await runServiceCmd({ dataDir: resolveDataDir() });
+    const result = await runServiceCmd({
+      dataDir: resolveDataDir(),
+      ...(flagMode ? { mode: flagMode } : {}),
+    });
     if (result === null) process.exitCode = 1;
+  } else if (cmd === "stop" || cmd === "service stop") {
+    // `krimto stop` — v0.2.32 first-class teardown verb. Uninstalls the launchd/systemd
+    // service (if installed) and SIGTERMs whatever PID is holding the lock. Idempotent.
+    // `service stop` is the same code path, named for users coming via `service` discovery.
+    const { runStop } = await tsImport("../src/cli/stopCmd.ts", import.meta.url);
+    const { resolveDataDir } = await tsImport("../src/server/index.ts", import.meta.url);
+    const result = await runStop({ dataDir: resolveDataDir() });
+    process.stdout.write(result.message);
+  } else if (cmd === "start" || cmd === "service start") {
+    // `krimto start` — v0.2.32 counterpart to stop. If a service plist exists on disk,
+    // reinstall + bootstrap (goes through the v0.2.26 kickstart-or-bootstrap path). If no
+    // service is configured, prints an instructive message instead of doing a brittle
+    // background-detached spawn.
+    const { runStart } = await tsImport("../src/cli/stopCmd.ts", import.meta.url);
+    const { resolveDataDir } = await tsImport("../src/server/index.ts", import.meta.url);
+    const result = await runStart({ dataDir: resolveDataDir() });
+    process.stdout.write(result.message);
+    if (result.status === "no-service-configured" || result.status === "error") process.exitCode = 1;
+  } else if (cmd === "restart") {
+    // `krimto restart` — v0.2.32. stop + start. On always-running mode this is effectively
+    // `launchctl kickstart -k` via installService's v0.2.26 reload path — atomic, no
+    // port-unbound window.
+    const { runRestart } = await tsImport("../src/cli/stopCmd.ts", import.meta.url);
+    const { resolveDataDir } = await tsImport("../src/server/index.ts", import.meta.url);
+    const result = await runRestart({ dataDir: resolveDataDir() });
+    process.stdout.write(result.message);
   } else if (cmd === "reset") {
     // `krimto reset` — disconnect from all editors + uninstall service + wipe local key store.
     // `--wipe-notes` adds a second confirmation and moves the data dir to a trash sibling.
@@ -403,11 +622,12 @@ try {
     process.stdout.write(result.message + "\n");
     if (result.status !== "ok") process.exitCode = 1;
   } else if (cmd === "storage") {
-    // `krimto storage` — explain where Krimto keeps data (markdown / git / index) in plain English,
-    // so the "you own your data" half of Krimto's pitch is reachable without reading the README.
+    // `krimto storage` — v0.2.31: deprecated in favour of `krimto status` (Storage block).
+    // Existing output preserved; deprecation hint to stderr.
     const { formatStorage } = await tsImport("../src/cli/storage.ts", import.meta.url);
     const { resolveDataDir } = await tsImport("../src/server/index.ts", import.meta.url);
     process.stdout.write(formatStorage(resolveDataDir()));
+    process.stderr.write("\n→ `krimto storage` is now part of `krimto status` (look for the Storage block).\n");
   } else if (cmd === "serve") {
     // `krimto serve` — boot the HTTP server (with /ui and /ui/connect) from the npx on-ramp,
     // so a stranger doesn't have to clone the repo or install Docker just to see the dashboard.
@@ -415,11 +635,38 @@ try {
     if (!process.env.KRIMTO_HTTP_PORT) process.env.KRIMTO_HTTP_PORT = "8080";
     const mod = await tsImport("../src/server/index.ts", import.meta.url);
     await mod.main();
+  } else if (cmd === "ui") {
+    // `krimto ui` — open the browser dashboard. The Maria-journey doc names this as one of the
+    // four user-facing verbs; the implementation is a one-liner over the platform "open this URL"
+    // command. If no krimto server is running, the browser will hit ECONNREFUSED — surface a
+    // pointer rather than a cryptic error.
+    const port = process.env.KRIMTO_HTTP_PORT ?? "8080";
+    const url = `http://localhost:${port}/ui`;
+    const { spawn } = await import("node:child_process");
+    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open";
+    spawn(opener, [url], { detached: true, stdio: "ignore" }).unref();
+    process.stdout.write(`Opening ${url}\n`);
+    process.stdout.write(`If the page doesn't load, start the server first:  $ krimto serve\n`);
+  } else if (cmd === "open") {
+    // `krimto open` — reveal the notes folder in the OS file manager. Companion to `krimto ui`
+    // for users who want to inspect / back up the markdown directly. macOS uses `open`, Linux
+    // `xdg-open`, Windows `explorer`. We deliberately do NOT do this from a browser button on
+    // /ui (cross-origin POST + a process running as the user can `open arbitrary://` URLs);
+    // the CLI is the right surface.
+    const { resolveDataDir } = await tsImport("../src/server/index.ts", import.meta.url);
+    const dataDir = resolveDataDir();
+    const { spawn } = await import("node:child_process");
+    const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open";
+    spawn(opener, [dataDir], { detached: true, stdio: "ignore" }).unref();
+    process.stdout.write(`Revealing ${dataDir} in your file manager.\n`);
   } else if (cmd === "usage") {
-    // `krimto usage` — the long-form guide: the five tools, both modes, copy-paste examples.
+    // `krimto usage` — the long-form guide. v0.2.31: kept (the guide is genuinely long and
+    // doesn't fit in `krimto status`) but still flagged so users who want the dashboard know
+    // where to find it.
     const { formatUsage } = await tsImport("../src/cli/usage.ts", import.meta.url);
     const { KRIMTO_VERSION } = await tsImport("../src/server/index.ts", import.meta.url);
     process.stdout.write(formatUsage(KRIMTO_VERSION));
+    process.stderr.write("\n→ For runtime status (is Krimto running, recent calls, where data lives) use `krimto status`.\n");
   } else if (cmd === "connect") {
     // `krimto connect` — print stdio connect snippets (the npx on-ramp shape), so a solo user
     // doesn't have to chase the README. Honors KRIMTO_IDENTITY when set.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krimto-labs/krimto",
-  "version": "0.2.27",
+  "version": "0.2.34",
   "description": "Open-source team memory layer for AI agents — markdown files in git, user/team/org hierarchy, cross-vendor MCP server.",
   "license": "Apache-2.0",
   "type": "module",

package/src/access/scope.ts

@@ -58,6 +58,14 @@ export interface Requester {
   identity: string;
   /** Team slugs the requester belongs to. */
   teams: string[];
+  /**
+   * v0.2.31 — best-effort editor attribution. Set by the HTTP MCP handler from User-Agent
+   * sniffing ("Cursor/1.x" → "cursor", "claude-code/x" → "claude-code", etc.) so that fact
+   * frontmatter can record "saved from a Cursor chat" without each MCP-tool caller needing
+   * to pass `source` explicitly. Undefined over stdio transport (no UA available) and
+   * whenever the User-Agent is unrecognised.
+   */
+  source?: string;
 }
 
 export type ScopeRelation = "own-user" | "own-team" | "org" | "other";

package/src/agentRule.ts

@@ -29,6 +29,17 @@ Don't save secrets, transient state, or one-off chatter.`;
 const START = "<!-- krimto:start -->";
 const END = "<!-- krimto:end -->";
 
+/**
+ * v0.2.29 — Cursor's `.cursor/rules/*.mdc` files require YAML frontmatter to be auto-applied.
+ * Without `alwaysApply: true`, Cursor treats the rule as MANUAL-attach only — the agent only
+ * loads it when the user explicitly says "krimto" (or `@krimto`) in their prompt. The smoke-6
+ * cross-editor test showed this: Claude Code (which auto-reads CLAUDE.md with no frontmatter
+ * needed) saved facts correctly, but Cursor wouldn't recall them until the user typed "krimto".
+ * Other editors (CLAUDE.md, AGENTS.md, GEMINI.md) are plain markdown — they don't use this
+ * convention, so the frontmatter is added ONLY for the cursor target.
+ */
+const CURSOR_FRONTMATTER = "---\nalwaysApply: true\n---\n";
+
 /** The rule wrapped in stable markers, so it can be found and updated in place later. */
 export function ruleBlock(): string {
   return `${START}\n${AGENT_RULE}\n${END}`;
@@ -40,19 +51,34 @@ export function ruleBlock(): string {
  * - existing WITHOUT our markers → append the block, preserving all existing content
  * - existing WITH our markers    → replace only the marked block, preserving the rest
  * Re-applying the same rule yields identical content (so callers can detect a no-op).
+ *
+ * `opts.cursorMdc` prepends the Cursor-required YAML frontmatter (`alwaysApply: true`) so
+ * `.cursor/rules/krimto.mdc` is auto-loaded by Cursor on every prompt instead of being
+ * manual-attach-only. Idempotent: if frontmatter already exists at the top, it's preserved.
  */
-export function applyRule(existing: string | null): string {
+export function applyRule(
+  existing: string | null,
+  opts: { cursorMdc?: boolean } = {},
+): string {
   const block = ruleBlock();
-  if (!existing || existing.trim() === "") return `${block}\n`;
+
+  // Helper: ensure the result starts with `---\nalwaysApply: true\n---\n` when requested.
+  const withFrontmatter = (content: string): string => {
+    if (!opts.cursorMdc) return content;
+    if (content.startsWith("---\n")) return content; // user-supplied frontmatter — leave alone
+    return CURSOR_FRONTMATTER + content;
+  };
+
+  if (!existing || existing.trim() === "") return withFrontmatter(`${block}\n`);
 
   const startIdx = existing.indexOf(START);
   const endIdx = existing.indexOf(END);
   if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-    return existing.slice(0, startIdx) + block + existing.slice(endIdx + END.length);
+    return withFrontmatter(existing.slice(0, startIdx) + block + existing.slice(endIdx + END.length));
   }
 
   const sep = existing.endsWith("\n") ? "\n" : "\n\n";
-  return `${existing}${sep}${block}\n`;
+  return withFrontmatter(`${existing}${sep}${block}\n`);
 }
 
 /**

package/src/cli/editors.ts

@@ -24,7 +24,7 @@ import {
   writeMcpConfig,
   type WriteAction,
 } from "./mcpConfig";
-import { defaultIO, isExitPrompt, type WizardIO } from "./promptHelpers";
+import { assertInteractiveOrUsage, defaultIO, isExitPrompt, type WizardIO } from "./promptHelpers";
 
 const EDITOR_LABEL: Record<EditorKind, string> = {
   cursor: "Cursor",
@@ -89,6 +89,13 @@ export async function applyEditors(
 
 export async function runEditors(opts: EditorsOptions = {}): Promise<EditorsResult | null> {
   const io = opts.io ?? defaultIO;
+  // v0.2.34 — when no editor list was supplied programmatically, we'd open the checkbox
+  // prompt. Without a TTY (AI-agent Bash, CI) that prompt would hang then crash with the
+  // cryptic "unsettled top-level await" warning. Detect and surface the right flags
+  // instead, so agents get a clean exit + actionable usage.
+  if (!opts.editors) {
+    assertInteractiveOrUsage(EDITORS_USAGE);
+  }
   try {
     const cwd = opts.cwd ?? process.cwd();
     const envs = await detectEditorEnvironments(cwd, opts.homeDir);
@@ -114,6 +121,62 @@ export async function runEditors(opts: EditorsOptions = {}): Promise<EditorsResu
   }
 }
 
+/** Non-interactive usage shown by the TTY guard when an agent runs `krimto editors` cold. */
+const EDITORS_USAGE =
+  "For non-interactive use (AI agents / CI):\n" +
+  "  krimto editors --add cursor [--yes]            Connect one editor (repeat or comma-list ok)\n" +
+  "  krimto editors --remove cursor [--yes]         Disconnect one editor\n" +
+  "  krimto editors --set cursor,claude-code [--yes]  Replace the full connected set\n" +
+  "  krimto editors --list                          Print current connections (one per line)";
+
+/**
+ * v0.2.34 — parse a comma-separated / repeated CLI value into a deduped EditorKind list.
+ * Accepts the canonical slugs plus common variants. Throws (with a clear message) on
+ * unknown names so an agent passing a typo learns immediately instead of silently no-op'ing.
+ */
+export function parseEditorList(values: string[]): EditorKind[] {
+  const aliases: Record<string, EditorKind> = {
+    cursor: "cursor",
+    "claude-code": "claude-code",
+    claudecode: "claude-code",
+    claude_code: "claude-code",
+    claude: "claude-code",
+    codex: "codex",
+    gemini: "gemini-cli",
+    "gemini-cli": "gemini-cli",
+    geminicli: "gemini-cli",
+  };
+  const out: EditorKind[] = [];
+  const seen = new Set<EditorKind>();
+  for (const raw of values) {
+    for (const part of raw.split(",").map((s) => s.trim()).filter(Boolean)) {
+      const key = part.toLowerCase();
+      const kind = aliases[key];
+      if (!kind) {
+        throw new Error(
+          `Unknown editor "${part}". Expected one of: cursor, claude-code, codex, gemini-cli.`,
+        );
+      }
+      if (!seen.has(kind)) {
+        out.push(kind);
+        seen.add(kind);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * v0.2.34 — programmatic helpers the bin uses to compute the target editor set without
+ * spawning the checkbox prompt. `--add` / `--remove` are merge ops over the current
+ * snapshot; `--set` replaces the list outright.
+ */
+export async function listConnectedEditors(opts: { cwd?: string; homeDir?: string } = {}): Promise<EditorKind[]> {
+  const cwd = opts.cwd ?? process.cwd();
+  const snapshot = await detectExistingSetup(cwd, opts.homeDir);
+  return snapshot.registeredEditors;
+}
+
 async function askEditorsList(
   envs: EditorEnvironment[],
   current: EditorKind[],
@@ -140,7 +203,8 @@ async function askEditorsList(
 async function applyRuleToFile(cwd: string, env: EditorEnvironment): Promise<boolean> {
   const rulePath = path.join(cwd, env.rulesPath);
   const existing = await readMaybe(rulePath);
-  const next = applyRule(existing);
+  // v0.2.29 — Cursor's .mdc rules need `alwaysApply: true` frontmatter.
+  const next = applyRule(existing, { cursorMdc: env.editor === "cursor" });
   if (next === existing) return false;
   await fs.mkdir(path.dirname(rulePath), { recursive: true });
   await fs.writeFile(rulePath, next, "utf8");