@krimto-labs/krimto 0.2.27 → 0.2.32

package/bin/krimto.mjs

@@ -10,12 +10,18 @@ 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 +144,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 +222,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 +253,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,12 +353,14 @@ 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).
@@ -280,11 +375,49 @@ try {
     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 +536,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 +549,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.32",
   "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

@@ -140,7 +140,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");

package/src/cli/folderCmd.ts

@@ -0,0 +1,216 @@
+// `krimto folder` — guided move of the notes folder (`KRIMTO_DATA`) to a new location.
+// The Maria-journey doc §06 names this as a "direct shortcut for power users". v0.2.31.
+//
+// What it does:
+//   1. Reads the current data dir via resolveDataDir() (honours KRIMTO_DATA).
+//   2. Prompts for a destination path (or accepts --to <path>).
+//   3. Validates: destination must not exist OR be an empty directory we can take over.
+//   4. Confirms with the user, listing the consequences.
+//   5. If the always-running service is installed, uninstalls it first (the launchd plist
+//      / systemd unit env still points at the OLD path; we'll reinstall with the new one
+//      after the move).
+//   6. Atomic-ish rename (`fs.rename`). When source and destination are on different
+//      filesystems and `rename` errors with EXDEV, fall back to a recursive copy + remove.
+//   7. Reinstalls the service (if it was installed) with `KRIMTO_DATA=<new path>` baked in.
+//   8. Prints an `export KRIMTO_DATA=<new>` hint so the user's terminal sessions and any
+//      scripts pick up the new path on next shell.
+
+import { confirm, input } from "@inquirer/prompts";
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+
+import {
+  detectPlatform,
+  installService,
+  isServiceInstalled,
+  uninstallService,
+  type InstallResult,
+} from "./service";
+import { defaultIdentity } from "./init";
+import { defaultIO, isExitPrompt, type WizardIO } from "./promptHelpers";
+
+export interface FolderCmdOptions {
+  io?: WizardIO;
+  /** Current data dir — usually `resolveDataDir()`. */
+  from: string;
+  /** Destination path. When omitted, the user is prompted. */
+  to?: string;
+  /** Override `os.homedir()` so installService writes the new service unit to a temp dir in tests. */
+  homeDir?: string;
+  /** Skip the confirmation prompt. */
+  yes?: boolean;
+  /** Forwarded to installService for tests so we don't really hit launchctl/systemctl. */
+  dryRun?: boolean;
+}
+
+export interface FolderCmdResult {
+  status: "ok" | "no-change" | "error";
+  from: string;
+  to: string;
+  serviceReinstalled: boolean;
+  message: string;
+  reinstall?: InstallResult;
+}
+
+export async function runFolderCmd(opts: FolderCmdOptions): Promise<FolderCmdResult | null> {
+  const io = opts.io ?? defaultIO;
+  const fromDir = path.resolve(opts.from);
+
+  try {
+    io.out("\nKrimto — Move the notes folder\n\n");
+    io.out(`  Current location:  ${fromDir}\n\n`);
+
+    const to =
+      opts.to ??
+      (await input({
+        message: "New location (absolute path):",
+        validate: (v) => {
+          const trimmed = v.trim();
+          if (trimmed.length === 0) return "Path is required";
+          if (!path.isAbsolute(trimmed)) return "Must be an absolute path (starts with /)";
+          return true;
+        },
+      }));
+    const toDir = path.resolve(to);
+
+    if (toDir === fromDir) {
+      return {
+        status: "no-change",
+        from: fromDir,
+        to: toDir,
+        serviceReinstalled: false,
+        message: "\n  Source and destination are the same — nothing to move.\n\n",
+      };
+    }
+
+    // Destination must be either absent or an empty directory. Refuse anything else so we
+    // never silently merge into an existing notes folder.
+    const destState = await classifyDestination(toDir);
+    if (destState === "non-empty") {
+      return {
+        status: "error",
+        from: fromDir,
+        to: toDir,
+        serviceReinstalled: false,
+        message:
+          `\n❌ ${toDir} exists and isn't empty.\n` +
+          `   Pick an absent path or an empty directory. Krimto won't merge into an existing folder.\n\n`,
+      };
+    }
+
+    io.out("\n  This will:\n");
+    io.out(`    • Move every file from ${fromDir}\n`);
+    io.out(`      to ${toDir}\n`);
+    io.out("    • Reinstall the background service (if installed) with the new path\n\n");
+    io.out("  This will NOT touch:\n");
+    io.out("    • Editor MCP configs (they point at the HTTP server, not the dir)\n");
+    io.out("    • Project rule files (.cursor/rules/*.mdc, CLAUDE.md, etc.)\n\n");
+    io.out("  ⚠️  After the move, set KRIMTO_DATA in your shell so any new krimto\n");
+    io.out("     processes (CLI or editor stdio launches) pick up the new path:\n\n");
+    io.out(`       export KRIMTO_DATA="${toDir}"\n\n`);
+
+    if (!opts.yes) {
+      const ok = await confirm({ message: "Proceed?", default: false });
+      if (!ok) {
+        return {
+          status: "no-change",
+          from: fromDir,
+          to: toDir,
+          serviceReinstalled: false,
+          message: "\nAborted. Nothing moved.\n\n",
+        };
+      }
+    }
+
+    // Uninstall the service first — its plist/unit env still names the OLD KRIMTO_DATA.
+    // After the move we reinstall with the new one. We do this BEFORE the rename so launchd
+    // / systemd isn't holding any handles into the (about-to-vanish) source dir.
+    const platform = detectPlatform();
+    const svc = await isServiceInstalled(platform, opts.homeDir);
+    let serviceWasInstalled = false;
+    if (svc.installed) {
+      serviceWasInstalled = true;
+      await uninstallService({ platform, homeDir: opts.homeDir, dryRun: opts.dryRun });
+    }
+
+    // The move itself. fs.rename is atomic when src + dst share a filesystem. When they
+    // don't, Node throws EXDEV — fall back to copy-then-remove.
+    try {
+      await fs.mkdir(path.dirname(toDir), { recursive: true });
+      await fs.rename(fromDir, toDir);
+    } catch (e) {
+      const code = (e as NodeJS.ErrnoException).code;
+      if (code === "EXDEV") {
+        // Cross-device fallback: cp -R then rm -rf, both via fs primitives.
+        await fs.cp(fromDir, toDir, { recursive: true, preserveTimestamps: true });
+        await fs.rm(fromDir, { recursive: true, force: true });
+      } else {
+        return {
+          status: "error",
+          from: fromDir,
+          to: toDir,
+          serviceReinstalled: false,
+          message: `\n❌ Move failed: ${e instanceof Error ? e.message : String(e)}\n\n`,
+        };
+      }
+    }
+
+    // Reinstall the service (if it was) with the new data dir baked into its env.
+    let reinstall: InstallResult | undefined;
+    let serviceReinstalled = false;
+    if (serviceWasInstalled) {
+      const identity = await defaultIdentity();
+      reinstall = await installService(
+        {
+          binPath: process.execPath,
+          args: [process.argv[1] ?? "krimto", "serve"],
+          env: { KRIMTO_IDENTITY: identity, KRIMTO_DATA: toDir, KRIMTO_HTTP_PORT: "8080" },
+          homeDir: opts.homeDir,
+        },
+        { dryRun: opts.dryRun, platform },
+      );
+      serviceReinstalled = true;
+    }
+
+    const lines: string[] = [
+      "",
+      `✅ Notes folder moved.`,
+      `   from: ${fromDir}`,
+      `   to:   ${toDir}`,
+      "",
+    ];
+    if (serviceReinstalled) lines.push("   • Background service reinstalled with the new path.");
+    lines.push("");
+    lines.push("Add this to your shell so future krimto runs find the new location:");
+    lines.push(`   export KRIMTO_DATA="${toDir}"`);
+    lines.push("");
+
+    return {
+      status: "ok",
+      from: fromDir,
+      to: toDir,
+      serviceReinstalled,
+      message: lines.join("\n"),
+      ...(reinstall ? { reinstall } : {}),
+    };
+  } catch (e) {
+    if (isExitPrompt(e)) {
+      io.err("\nAborted.\n");
+      process.exitCode = 130;
+      return null;
+    }
+    throw e;
+  }
+}
+
+/** Categorise the destination: "absent" (we'll create it), "empty" (take over), or "non-empty" (refuse). */
+async function classifyDestination(dir: string): Promise<"absent" | "empty" | "non-empty"> {
+  try {
+    const entries = await fs.readdir(dir);
+    return entries.length === 0 ? "empty" : "non-empty";
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === "ENOENT") return "absent";
+    // Other errors (permission, not-a-dir) — treat as non-empty so we refuse.
+    return "non-empty";
+  }
+}