threadnote 0.2.1 → 0.3.0

package/README.md

@@ -28,8 +28,8 @@ Threadnote keeps that memory local and searchable without editing unrelated repo
 - Redaction: known config files such as `.mcp.json`, `config.toml`, and settings JSON are copied through a redactor
   before import.
 - Secret scanning: candidate files are skipped if common token or private-key patterns remain after redaction.
-- User instructions: `install` upserts a managed Threadnote block in `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md`
-  without replacing existing personal instructions.
+- User instructions: `install` upserts a managed Threadnote block in `~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`, and
+  `~/.cursor/rules/threadnote.md` without replacing existing personal instructions.
 - Agent config changes are explicit: `mcp-install` prints commands and snippets by default; use `--apply` to run them.
 
 ## Install
@@ -70,13 +70,15 @@ threadnote doctor --dry-run
 
 ### MCP
 
-Make the agents you use aware of Threadnote. Use only the MCP install lines for agents you actually use. Open a fresh Codex or Claude session after installing MCP so the new server registration is loaded.
+Make the agents you use aware of Threadnote. Use only the MCP install lines for agents you actually use. Open a fresh
+agent session after installing MCP so the new server registration is loaded.
 
 Dry-run examples:
 
 ```bash
 threadnote mcp-install codex
 threadnote mcp-install claude
+threadnote mcp-install cursor
 ```
 
 Apply after review:
@@ -84,10 +86,12 @@ Apply after review:
 ```bash
 threadnote mcp-install codex --apply
 threadnote mcp-install claude --apply
+threadnote mcp-install cursor --apply
 ```
 
 Claude installs at `user` scope by default so the same OpenViking MCP server is available from any repo or worktree.
 Use `--scope local` or `--scope project` only when you intentionally want repo-scoped Claude MCP config.
+Cursor installs by updating the global `~/.cursor/mcp.json` file.
 
 If the package or checkout that originally installed `threadnote` has moved, run repair:
 
@@ -106,6 +110,8 @@ codex mcp add threadnote -- threadnote-mcp-server
 claude mcp add threadnote -- threadnote-mcp-server
 ```
 
+Cursor uses the equivalent entry in `~/.cursor/mcp.json`.
+
 If a future OpenViking build exposes a healthy native endpoint, install it explicitly:
 
 ```bash
@@ -146,7 +152,7 @@ This is it! Start working with your agents as usual. The agent will automaticall
 - `doctor`: checks prerequisites, the generated command shim, manifest shape, templates, and local OpenViking health.
 - `install`: installs `openviking[local-embed]==0.3.12` if missing, creates `~/.openviking` config files if absent,
   writes the command shim, and upserts user-level agent instructions.
-- `repair`: fixes install/config/shim/manifest/server health issues and rewrites Codex/Claude MCP configs from the
+- `repair`: fixes install/config/shim/manifest/server health issues and rewrites Codex/Claude/Cursor MCP configs from the
   current checkout.
 - `start`: starts `openviking-server` on `127.0.0.1:1933`.
 - `stop`: stops the detached server pid or macOS LaunchAgent.
@@ -156,7 +162,7 @@ This is it! Start working with your agents as usual. The agent will automaticall
 - `seed`: imports curated repo guidance and docs from the manifest.
 - `seed-skills`: imports global and repo-local `SKILL.md` files as a searchable resource catalog. Use
   `seed-skills --native` only after configuring a working VLM provider.
-- `mcp-install codex|claude`: installs or prints OpenViking MCP configuration for Codex or Claude.
+- `mcp-install codex|claude|cursor`: installs or prints OpenViking MCP configuration for Codex, Claude, or Cursor.
 - `remember`: stores a durable memory.
 - `recall`: searches shared OpenViking context. It infers repo or skill scope from queries like
   `skills for api service`; use `--uri` or `--no-infer-scope` to override.
@@ -178,7 +184,8 @@ npm run threadnote -- install
 ```
 
 `install` writes a small command shim to `~/.local/bin/threadnote` by default and upserts user-level agent guidance in
-`~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md`. After that, use the short command from any repo or working directory:
+`~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`, and `~/.cursor/rules/threadnote.md`. After that, use the short command from
+any repo or working directory:
 
 ```bash
 threadnote doctor --dry-run

package/dist/threadnote.cjs

@@ -6143,7 +6143,8 @@ var USER_INSTRUCTIONS_END_MARKER = "<!-- END THREADNOTE USER INSTRUCTIONS -->";
 var USER_MANIFEST_NAME = "seed-manifest.yaml";
 var USER_AGENT_INSTRUCTION_TARGETS = [
   { label: "codex user instructions", path: "~/.codex/AGENTS.md" },
-  { label: "claude user instructions", path: "~/.claude/CLAUDE.md" }
+  { label: "claude user instructions", path: "~/.claude/CLAUDE.md" },
+  { label: "cursor user rule", path: "~/.cursor/rules/threadnote.md" }
 ];
 var DEFAULT_SEED_PATTERNS = [
   "AGENTS.md",
@@ -6172,7 +6173,7 @@ async function main() {
   });
   program2.command("repair").description("Repair local OpenViking install, config files, server health, shim, manifest, and MCP config").option("--dry-run", "Print the repair actions without making changes").option(
     "--mcp <clients>",
-    "MCP clients to repair: available, all, none, codex, claude, or comma-separated list",
+    "MCP clients to repair: available, all, none, codex, claude, cursor, or comma-separated list",
     "available"
   ).option("--no-start", "Do not start OpenViking if health is failing").option("--package-manager <manager>", "pipx, uv, or pip", parsePackageManager).action(async (options) => {
     await runRepair(getRuntimeConfig(program2), options);
@@ -6185,7 +6186,7 @@ async function main() {
   });
   program2.command("uninstall").description("Remove Threadnote setup and optionally erase local memories").option("--dry-run", "Print uninstall actions without making changes").option(
     "--mcp <clients>",
-    "MCP clients to remove: available, all, none, codex, claude, or comma-separated list",
+    "MCP clients to remove: available, all, none, codex, claude, cursor, or comma-separated list",
     "available"
   ).option("--preserve-memories", "Preserve THREADNOTE_HOME and OpenViking memories (default)").option("--erase-memories", "Delete THREADNOTE_HOME, including all OpenViking memories").action(async (options) => {
     await runUninstall(getRuntimeConfig(program2), options);
@@ -6199,10 +6200,10 @@ async function main() {
   program2.command("seed-skills").description("Seed Codex, Claude, and repo-local SKILL.md files as a searchable catalog").option("--dry-run", "Print skill files and ov commands without importing").option("--manifest <path>", "Manifest path for repo-local skill discovery").option("--native", "Use native OpenViking skill ingestion; requires a working VLM config").action(async (options) => {
     await runSeedSkills(getRuntimeConfig(program2, options.manifest), options);
   });
-  program2.command("mcp-install").description("Install OpenViking MCP config for a supported agent").argument("<agent>", "codex or claude").option("--apply", "Actually modify the selected agent config").option("--name <name>", "MCP server name", OPENVIKING_MCP_NAME).option("--native-http", "Install OpenViking native HTTP MCP endpoint instead of the local stdio adapter").option("--scope <scope>", "Claude MCP config scope: user, local, or project", parseClaudeMcpScope, "user").option("--url <url>", "OpenViking native HTTP MCP URL").option("--bearer-token-env-var <name>", "Environment variable containing the local API key").action(async (agent, options) => {
+  program2.command("mcp-install").description("Install OpenViking MCP config for a supported agent").argument("<agent>", "codex, claude, or cursor").option("--apply", "Actually modify the selected agent config").option("--name <name>", "MCP server name", OPENVIKING_MCP_NAME).option("--native-http", "Install OpenViking native HTTP MCP endpoint instead of the local stdio adapter").option("--scope <scope>", "Claude MCP config scope: user, local, or project", parseClaudeMcpScope, "user").option("--url <url>", "OpenViking native HTTP MCP URL").option("--bearer-token-env-var <name>", "Environment variable containing the local API key").action(async (agent, options) => {
     await runMcpInstall(getRuntimeConfig(program2), parseAgentClient(agent), options);
   });
-  program2.command("remember").description("Store a durable engineering memory in OpenViking").option("--dry-run", "Print memory and ov command without storing").option("--source-agent-client <name>", "codex, claude, gemini, or another client name", "codex").option("--stdin", "Read memory text from stdin").option("--text <text>", "Memory text to store").action(async (options) => {
+  program2.command("remember").description("Store a durable engineering memory in OpenViking").option("--dry-run", "Print memory and ov command without storing").option("--source-agent-client <name>", "codex, claude, cursor, gemini, or another client name", "codex").option("--stdin", "Read memory text from stdin").option("--text <text>", "Memory text to store").action(async (options) => {
     await runRemember(getRuntimeConfig(program2), options);
   });
   program2.command("recall").description("Search shared OpenViking context").requiredOption("--query <query>", "Search query").option("--dry-run", "Print ov command without searching").option("-n, --node-limit <count>", "Maximum number of search results").option("--no-infer-scope", "Disable query-based scope inference").option("--uri <uri>", "Restrict search to a viking:// URI").action(async (options) => {
@@ -6214,7 +6215,7 @@ async function main() {
   program2.command("list").alias("ls").description("List a viking:// directory").argument("[uri]", "viking:// URI to list", "viking://").option("-a, --all", "Show hidden files such as .abstract.md and .overview.md").option("--dry-run", "Print ov command without listing").option("-n, --node-limit <count>", "Maximum number of nodes to list").option("-r, --recursive", "List subdirectories recursively").option("-s, --simple", "Print only paths").action(async (uri, options) => {
     await runList(getRuntimeConfig(program2), uri, options);
   });
-  program2.command("handoff").description("Capture current repo state as a durable cross-agent handoff memory").option("--blockers <text>", "Known blockers").option("--dry-run", "Print handoff without storing").option("--next-step <text>", "Suggested next step").option("--source-agent-client <name>", "codex, claude, gemini, or another client name", "codex").option("--task <text>", "Current task summary").option("--tests <text>", "Tests or checks run").action(async (options) => {
+  program2.command("handoff").description("Capture current repo state as a durable cross-agent handoff memory").option("--blockers <text>", "Known blockers").option("--dry-run", "Print handoff without storing").option("--next-step <text>", "Suggested next step").option("--source-agent-client <name>", "codex, claude, cursor, gemini, or another client name", "codex").option("--task <text>", "Current task summary").option("--tests <text>", "Tests or checks run").action(async (options) => {
     await runHandoff(getRuntimeConfig(program2), options);
   });
   program2.command("forget").description("Remove a viking:// URI from local OpenViking context").argument("<uri>", "viking:// URI to remove").option("--dry-run", "Print ov command without deleting").action(async (uri, options) => {
@@ -6294,16 +6295,20 @@ async function runInstall(config, options) {
   const serverPath = await findExecutable([OPENVIKING_SERVER_COMMAND]);
   if (serverPath) {
     console.log(`OpenViking server already installed: ${serverPath}`);
-    const repairReasons = [];
-    if (await hasLocalEmbeddingDependency(serverPath) === false) {
+    const localEmbeddingMissing = await hasLocalEmbeddingDependency(serverPath) === false;
+    const pythonSystemCertificatesMissing = await hasPythonSystemCertificatesPatch(serverPath) === false;
+    if (localEmbeddingMissing) {
+      const repairReasons = [];
       repairReasons.push("local embedding extra is missing");
-    }
-    if (await hasPythonSystemCertificatesPatch(serverPath) === false) {
-      repairReasons.push("Python system certificate bridge is missing");
-    }
-    if (repairReasons.length > 0) {
+      if (pythonSystemCertificatesMissing) {
+        repairReasons.push("Python system certificate bridge is missing");
+      }
       console.log(`OpenViking install needs repair: ${repairReasons.join("; ")}.`);
       await runInstallCommands(config, options.packageManager, true, options.dryRun === true);
+    } else if (pythonSystemCertificatesMissing) {
+      console.log("OpenViking install needs repair: Python system certificate bridge is missing.");
+      const installCommand = await getPythonSystemCertificatesInstallCommand(serverPath);
+      await maybeRun(options.dryRun === true, installCommand.executable, installCommand.args);
     }
   } else {
     await runInstallCommands(config, options.packageManager, false, options.dryRun === true);
@@ -6651,13 +6656,6 @@ async function runMcpInstall(config, agent, options) {
   const url = options.url ?? `http://${config.host}:${config.port}/mcp`;
   const apply = options.apply === true;
   const nativeHttp = options.nativeHttp === true;
-  const command = buildMcpInstallCommand(config, agent, name, {
-    bearerTokenEnvVar: options.bearerTokenEnvVar,
-    nativeHttp,
-    scope: options.scope,
-    url
-  });
-  const removeCommand = buildMcpRemoveCommand(agent, name);
   if (nativeHttp) {
     const mcpStatus = await readHttpStatus(url, 1200);
     const unavailable = mcpStatus === void 0 || mcpStatus === 404;
@@ -6670,6 +6668,22 @@ async function runMcpInstall(config, agent, options) {
       console.log(`WARN OpenViking native MCP endpoint is not available at ${url}; default mcp-install uses stdio.`);
     }
   }
+  if (agent === "cursor") {
+    await runCursorMcpInstall(config, name, {
+      apply,
+      bearerTokenEnvVar: options.bearerTokenEnvVar,
+      nativeHttp,
+      url
+    });
+    return;
+  }
+  const command = buildMcpInstallCommand(config, agent, name, {
+    bearerTokenEnvVar: options.bearerTokenEnvVar,
+    nativeHttp,
+    scope: options.scope,
+    url
+  });
+  const removeCommand = buildMcpRemoveCommand(agent, name);
   if (!apply) {
     console.log("Dry run. Re-run with --apply to modify the selected agent config.");
     if (removeCommand.cwd || command.cwd) {
@@ -6686,6 +6700,32 @@ async function runMcpInstall(config, agent, options) {
   });
   await maybeRun(false, command.executable, command.args, { cwd: command.cwd });
 }
+async function runCursorMcpInstall(config, name, options) {
+  const path = cursorMcpConfigPath();
+  const serverConfig = buildCursorMcpServerConfig(config, {
+    bearerTokenEnvVar: options.bearerTokenEnvVar,
+    nativeHttp: options.nativeHttp,
+    url: options.url
+  });
+  const currentContent = await readFileIfExists(path);
+  const nextContent = renderCursorMcpConfig(currentContent, name, serverConfig);
+  if (!options.apply) {
+    console.log("Dry run. Re-run with --apply to modify Cursor MCP config.");
+    printCursorMcpSnippet(config, name, {
+      bearerTokenEnvVar: options.bearerTokenEnvVar,
+      nativeHttp: options.nativeHttp,
+      url: options.url
+    });
+    return;
+  }
+  if (currentContent === nextContent) {
+    console.log(`Already configured: ${path}`);
+    return;
+  }
+  await ensureDirectory((0, import_node_path2.dirname)(path), false);
+  await (0, import_promises10.writeFile)(path, nextContent, { encoding: "utf8", mode: 420 });
+  console.log(currentContent === void 0 ? `Wrote Cursor MCP config: ${path}` : `Updated Cursor MCP config: ${path}`);
+}
 async function runRemember(config, options) {
   const text = await getInputText(options.text, options.stdin === true);
   if (!text.trim()) {
@@ -6980,6 +7020,20 @@ async function runInstallCommands(config, preferred, force, dryRun) {
     await maybeRun(dryRun, installCommand.executable, installCommand.args);
   }
 }
+async function getPythonSystemCertificatesInstallCommand(serverPath) {
+  const pythonPath = await siblingPythonForExecutable(serverPath);
+  if (!pythonPath) {
+    throw new Error(`Could not find the OpenViking Python environment for ${serverPath}`);
+  }
+  const uvPath = await findExecutable(["uv"]);
+  if (uvPath) {
+    return {
+      executable: uvPath,
+      args: ["pip", "install", "--native-tls", "--python", pythonPath, PYTHON_SYSTEM_CERTS_PACKAGE]
+    };
+  }
+  return { executable: pythonPath, args: ["-m", "pip", "install", PYTHON_SYSTEM_CERTS_PACKAGE] };
+}
 async function getInstallCommands(config, preferred, force) {
   const packageSpec = `${OPENVIKING_PACKAGE_NAME}==${config.openVikingVersion}`;
   const manager = preferred ?? await detectPackageManager();
@@ -7261,6 +7315,10 @@ async function removeMcpConfigs(value, dryRun) {
     return;
   }
   for (const client of clients) {
+    if (client === "cursor") {
+      await removeCursorMcpConfig(OPENVIKING_MCP_NAME, dryRun);
+      continue;
+    }
     const command = buildMcpRemoveCommand(client, OPENVIKING_MCP_NAME);
     await maybeRun(dryRun, command.executable, command.args, { allowFailure: true, cwd: command.cwd });
   }
@@ -7268,6 +7326,7 @@ async function removeMcpConfigs(value, dryRun) {
 async function removeMcpSnippets(config, dryRun) {
   await removePathIfExists((0, import_node_path4.join)(config.agentContextHome, "mcp", `${OPENVIKING_MCP_NAME}.codex.toml`), "MCP snippet", dryRun);
   await removePathIfExists((0, import_node_path4.join)(config.agentContextHome, "mcp", `${OPENVIKING_MCP_NAME}.claude.txt`), "MCP snippet", dryRun);
+  await removePathIfExists((0, import_node_path4.join)(config.agentContextHome, "mcp", `${OPENVIKING_MCP_NAME}.cursor.json`), "MCP snippet", dryRun);
 }
 async function eraseThreadnoteHome(path, dryRun) {
   assertSafeThreadnoteHomeForErase(path);
@@ -7388,6 +7447,9 @@ async function resolveAbsolutePattern(pattern) {
   return files.filter((filePath) => regex.test(toPosixPath(filePath)));
 }
 function buildMcpInstallCommand(config, agent, name, options) {
+  if (agent === "cursor") {
+    throw new Error("Cursor MCP config is written directly to ~/.cursor/mcp.json.");
+  }
   const claudeCwd = getInvocationCwd();
   const claudeScope = options.scope ?? "user";
   if (!options.nativeHttp) {
@@ -7429,6 +7491,9 @@ function mcpAdapterCommand() {
   return [(0, import_node_path4.join)(toolRoot(), "bin", "threadnote-mcp-server.cjs")];
 }
 function buildMcpRemoveCommand(agent, name) {
+  if (agent === "cursor") {
+    throw new Error("Cursor MCP config is removed directly from ~/.cursor/mcp.json.");
+  }
   return agent === "codex" ? { executable: "codex", args: ["mcp", "remove", name] } : { executable: "claude", args: ["mcp", "remove", name], cwd: getInvocationCwd() };
 }
 function mcpEnvironment(config) {
@@ -7439,6 +7504,72 @@ function mcpEnvironment(config) {
     `THREADNOTE_AGENT_ID=${config.agentId}`
   ];
 }
+function mcpEnvironmentObject(config) {
+  return {
+    THREADNOTE_ACCOUNT: config.account,
+    THREADNOTE_AGENT_ID: config.agentId,
+    THREADNOTE_HOME: config.agentContextHome,
+    THREADNOTE_USER: config.user
+  };
+}
+function buildCursorMcpServerConfig(config, options) {
+  if (options.nativeHttp) {
+    const server = { url: options.url };
+    if (options.bearerTokenEnvVar) {
+      server.headers = { Authorization: `Bearer \${env:${options.bearerTokenEnvVar}}` };
+    }
+    return server;
+  }
+  return {
+    args: [mcpAdapterCommand()[0]],
+    command: "/usr/bin/env",
+    env: mcpEnvironmentObject(config)
+  };
+}
+function renderCursorMcpConfig(currentContent, name, serverConfig) {
+  const parsed = currentContent === void 0 ? {} : parseJsonConfigObject(currentContent);
+  if (parsed === void 0) {
+    throw new Error(`${cursorMcpConfigPath()} exists but is not a JSON object; not modifying it.`);
+  }
+  if (parsed.mcpServers !== void 0 && !isJsonObject(parsed.mcpServers)) {
+    throw new Error(`${cursorMcpConfigPath()} has a non-object mcpServers field; not modifying it.`);
+  }
+  const nextConfig = { ...parsed };
+  const mcpServers = isJsonObject(parsed.mcpServers) ? { ...parsed.mcpServers } : {};
+  mcpServers[name] = serverConfig;
+  nextConfig.mcpServers = mcpServers;
+  return `${JSON.stringify(nextConfig, null, 2)}
+`;
+}
+async function removeCursorMcpConfig(name, dryRun) {
+  const path = cursorMcpConfigPath();
+  const currentContent = await readFileIfExists(path);
+  if (currentContent === void 0) {
+    console.log(`Already absent: ${path}`);
+    return;
+  }
+  const parsed = parseJsonConfigObject(currentContent);
+  if (parsed === void 0) {
+    console.log(`WARN ${path} exists but is not a JSON object; not modifying it.`);
+    return;
+  }
+  if (!isJsonObject(parsed.mcpServers) || parsed.mcpServers[name] === void 0) {
+    console.log(`No Cursor MCP config found: ${path}`);
+    return;
+  }
+  const nextConfig = { ...parsed };
+  const mcpServers = { ...parsed.mcpServers };
+  delete mcpServers[name];
+  nextConfig.mcpServers = mcpServers;
+  const nextContent = `${JSON.stringify(nextConfig, null, 2)}
+`;
+  if (dryRun) {
+    console.log(`Would update Cursor MCP config: ${path}`);
+    return;
+  }
+  await (0, import_promises10.writeFile)(path, nextContent, { encoding: "utf8", mode: 420 });
+  console.log(`Updated Cursor MCP config: ${path}`);
+}
 function withIdentity(config, args) {
   return [...args, "--account", config.account, "--user", config.user, "--agent-id", config.agentId];
 }
@@ -7450,6 +7581,10 @@ function uriSegment(value) {
   return normalized.length > 0 ? normalized : "unknown";
 }
 function printMcpSnippet(config, agent, name, options) {
+  if (agent === "cursor") {
+    printCursorMcpSnippet(config, name, { nativeHttp: options.nativeHttp, url: options.url });
+    return;
+  }
   const snippetPath = (0, import_node_path4.join)(config.agentContextHome, "mcp", `${name}.${agent}.${agent === "codex" ? "toml" : "txt"}`);
   const command = buildMcpInstallCommand(config, agent, name, {
     nativeHttp: options.nativeHttp,
@@ -7462,6 +7597,20 @@ function printMcpSnippet(config, agent, name, options) {
 Snippet (${snippetPath}):
 ${snippet2}`);
 }
+function printCursorMcpSnippet(config, name, options) {
+  const snippetPath = (0, import_node_path4.join)(config.agentContextHome, "mcp", `${name}.cursor.json`);
+  const snippet2 = JSON.stringify(
+    { mcpServers: { [name]: buildCursorMcpServerConfig(config, options) } },
+    null,
+    2
+  );
+  console.log(`
+Snippet (${snippetPath}; merge into ${cursorMcpConfigPath()}):
+${snippet2}`);
+}
+function cursorMcpConfigPath() {
+  return expandPath("~/.cursor/mcp.json");
+}
 async function storeMemory(config, memory, dryRun) {
   const ov = await openVikingCliForMode(dryRun);
   const memoryPath = (0, import_node_path4.join)(config.agentContextHome, "last-memory.txt");
@@ -8035,10 +8184,10 @@ function parsePackageManager(value) {
   throw new Error(`Invalid package manager: ${value}`);
 }
 function parseAgentClient(value) {
-  if (value === "codex" || value === "claude") {
+  if (value === "codex" || value === "claude" || value === "cursor") {
     return value;
   }
-  throw new Error(`Unsupported agent: ${value}. Expected codex or claude.`);
+  throw new Error(`Unsupported agent: ${value}. Expected codex, claude, or cursor.`);
 }
 function parseClaudeMcpScope(value) {
   if (value === "local" || value === "project" || value === "user") {
@@ -8053,12 +8202,22 @@ async function resolveMcpClients(value, action) {
   }
   let requested;
   if (normalized === "available" || normalized === "all") {
-    requested = ["codex", "claude"];
+    requested = ["codex", "claude", "cursor"];
   } else {
     requested = normalized.split(",").map((part) => part.trim()).filter(Boolean).map(parseAgentClient);
   }
   const clients = [];
   for (const client of requested) {
+    if (client === "cursor") {
+      if (!await isCursorAvailable()) {
+        console.log(`WARN Cursor config not found; cannot ${action} cursor MCP config.`);
+        continue;
+      }
+      if (!clients.includes(client)) {
+        clients.push(client);
+      }
+      continue;
+    }
     if (!await findExecutable([client])) {
       console.log(`WARN ${client} command not found; cannot ${action} ${client} MCP config.`);
       continue;
@@ -8069,6 +8228,15 @@ async function resolveMcpClients(value, action) {
   }
   return clients;
 }
+async function isCursorAvailable() {
+  if (await exists(expandPath("~/.cursor"))) {
+    return true;
+  }
+  if (await findExecutable(["cursor", "cursor-agent"])) {
+    return true;
+  }
+  return (0, import_node_os2.platform)() === "darwin" && await exists("/Applications/Cursor.app");
+}
 function assertVikingUri(uri) {
   if (!uri.startsWith("viking://")) {
     throw new Error(`Refusing non-viking URI: ${uri}`);

package/docs/migration.md

@@ -46,9 +46,9 @@ Create a handoff for the next agent before you stop.
 ```
 
 For better continuity, run `threadnote install` so it can add the agent-side guidance from `docs/agent-instructions.md`
-to the user-level `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md` files. That guidance tells agents to recall context at
-task start, store durable memories when explicitly asked or when a reusable workflow fact is learned, and create
-handoffs automatically before stopping meaningful work.
+to user-level Codex, Claude, and Cursor instruction files. That guidance tells agents to recall context at task start,
+store durable memories when explicitly asked or when a reusable workflow fact is learned, and create handoffs
+automatically before stopping meaningful work.
 
 ## Migration Steps
 
@@ -133,6 +133,15 @@ paths.
    Claude installs at user scope by default so it works from every repo/worktree. Use `--scope local` only when a
    repo-specific Claude MCP entry is intentional.
 
+   For Cursor:
+
+   ```bash
+   threadnote mcp-install cursor
+   threadnote mcp-install cursor --apply
+   ```
+
+   Cursor installs by updating the global `~/.cursor/mcp.json` file.
+
    Later, if the checkout that installed the MCP adapter is deleted or moved, repair it from any fresh checkout:
 
    ```bash
@@ -158,8 +167,7 @@ Remember this workflow note for future agents: ...
 Create a handoff now.
 ```
 
-Preferred agent behavior is automatic after `threadnote install` has updated the user-level Codex and Claude instruction
-files:
+Preferred agent behavior is automatic after `threadnote install` has updated the user-level instruction files:
 
 - On non-trivial task start, search OpenViking for recent handoffs and relevant repo guidance.
 - When the user says "remember", store the memory after checking that it contains no secret or customer data.

package/docs/rollout.md

@@ -18,7 +18,7 @@ Start with a local-only pilot.
 
 - Install completes in under 10 minutes after prerequisites.
 - `doctor` reports clear actionable checks.
-- Codex and Claude can both store and recall a shared handoff.
+- Codex, Claude, or Cursor can store and recall a shared handoff after MCP setup.
 - Seeding curated guidance does not import known secret patterns.
 - Fresh agents can recall repo testing guidance and discover relevant skills.
 - `uninstall --dry-run` previews removal, and `uninstall` leaves memories intact unless `--erase-memories` is explicit.

package/docs/security.md

@@ -6,7 +6,7 @@
 
 - Credentials, access tokens, API keys, certificates, private keys, or shell history.
 - Customer data, production data, HIPAA data, or production logs without explicit approval and scrubbing.
-- Local auth files such as `~/.codex/auth.json` or `~/.claude/.credentials.json`.
+- Local auth files such as `~/.codex/auth.json`, `~/.claude/.credentials.json`, or Cursor account/session files.
 - Local settings files that may contain secrets unless they go through redaction.
 
 ## Built-In Controls
@@ -14,9 +14,9 @@
 - `.threadnoteignore` excludes common secret and build-output paths.
 - `.mcp.json`, `config.toml`, and settings JSON are redacted before import.
 - Files are skipped if common secret patterns remain after redaction.
-- `mcp-install` requires `--apply` before it changes Codex or Claude config.
-- `install` updates user-level Codex and Claude instruction files through a managed Markdown block. Existing personal
-  instructions outside that block are preserved.
+- `mcp-install` requires `--apply` before it changes Codex, Claude, or Cursor config.
+- `install` updates user-level Codex, Claude, and Cursor instruction files through a managed Markdown block. Existing
+  personal instructions outside that block are preserved.
 - `uninstall` preserves local memories by default. `--erase-memories` is required before deleting `THREADNOTE_HOME`.
 - Config files created under `THREADNOTE_HOME` are written with user-only permissions.
 

package/docs/troubleshooting.md

@@ -42,6 +42,14 @@ threadnote start
 Threadnote installs `pip-system-certs` into the OpenViking environment so Python `requests` can use certificates trusted
 by the operating system.
 
+If an older Threadnote release tries to reinstall all of OpenViking and fails while fetching packages such as `openai`,
+install the certificate bridge directly into the existing OpenViking environment:
+
+```bash
+uv pip install --native-tls --python "$(dirname "$(realpath "$(which openviking-server)")")/python" pip-system-certs
+threadnote start
+```
+
 ## Local Embedding Extra Missing
 
 The default OpenViking config uses the local embedding backend. If the server log says `llama-cpp-python` is missing,
@@ -139,7 +147,7 @@ threadnote repair
 ```
 
 `repair` reinstalls the `threadnote` shim, repairs generated config files, starts OpenViking if needed, and rewrites
-Codex/Claude MCP configs to point at the current checkout.
+Codex/Claude/Cursor MCP configs to point at the current checkout.
 
 ## MCP Install Is Only Printing Commands
 
@@ -149,6 +157,15 @@ This is expected. Run with `--apply` after reviewing the command:
 threadnote mcp-install codex --apply
 ```
 
+For Cursor:
+
+```bash
+threadnote mcp-install cursor --apply
+```
+
+This updates the global `~/.cursor/mcp.json` file. Restart Cursor or open a fresh agent session after changing MCP
+config.
+
 ## Uninstall Without Losing Memories
 
 Run:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threadnote",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "commonjs",
   "main": "dist/threadnote.cjs",
   "description": "Shared local context and handoffs for development agents",

package/scripts/install.sh

@@ -130,3 +130,4 @@ say "  threadnote start"
 say "  threadnote doctor --dry-run"
 say "  threadnote mcp-install codex --apply    # if you use Codex"
 say "  threadnote mcp-install claude --apply   # if you use Claude"
+say "  threadnote mcp-install cursor --apply   # if you use Cursor"

package/docs/demo.md

@@ -1,279 +0,0 @@
-# Demo: Cross-Agent Development Context
-
-This demo shows `threadnote` as a shared local memory layer for engineering work. The story is intentionally simple:
-one agent starts a task in a worktree, stores a handoff, and another agent or worktree recalls it without the
-developer copy-pasting chat history, PR notes, or terminal output.
-
-## Demo Goal
-
-Show engineers that:
-
-- repo instructions still live in `AGENTS.md`, `CLAUDE.md`, and checked-in docs;
-- OpenViking adds durable, searchable context across agent sessions, worktrees, and repos;
-- agents should use MCP directly, while `threadnote` is the human-readable fallback and diagnostic path;
-- memories survive branch merges and worktree deletion because they live under the developer's OpenViking home, not in
-  the git worktree;
-- `repair` fixes the common stale-worktree and MCP launcher problems that show up during real local development.
-
-## Use Case
-
-Use "continue a PR after switching agents" as the live scenario.
-
-The engineer has a PR that updates a local tool. Codex has already done some work and creates a handoff. The engineer
-opens Claude, or a fresh Codex session from another repo/worktree, and asks it to continue. The new agent
-recalls the handoff, reads the relevant `viking://` memory, discovers repo guidance, and stores an updated handoff when
-it finishes.
-
-This is the highest-signal demo because it exercises the behavior engineers actually feel every day: context transfer,
-stale local setup, and "what did the previous agent already learn?"
-
-## Prep Checklist
-
-Run these before the meeting from this checkout:
-
-```bash
-npm install
-npm run doctor -- --dry-run
-npm run threadnote -- install
-threadnote start
-threadnote doctor --dry-run
-threadnote init-manifest --repo "$(pwd)"
-threadnote seed --dry-run
-threadnote seed
-threadnote seed-skills --dry-run
-threadnote seed-skills
-threadnote mcp-install codex --apply
-threadnote mcp-install claude --apply
-```
-
-Open a fresh Codex or Claude session after installing MCP. Existing sessions may not pick up newly registered MCP
-servers.
-
-Optional: create a deterministic demo handoff so the search result is easy to find.
-
-```bash
-threadnote handoff \
-  --task "Demo PR: continue the threadnote rollout after adding repair and docs" \
-  --tests "doctor --dry-run, mcp-install dry runs, local TypeScript checks" \
-  --next-step "Recall this handoff, read the most relevant viking URI, then summarize what changed and what to do next"
-```
-
-## Live Script
-
-### 1. Open With The Problem
-
-Say:
-
-```text
-When we switch from one agent session to another, we usually lose the useful middle: what was tried, what failed, what
-the branch is about, and what the next agent should avoid re-discovering. This tool gives agents a shared local context
-layer without replacing repo instructions or indexing entire repos.
-```
-
-Show that the repo still has normal instructions:
-
-```bash
-ls AGENTS.md CLAUDE.md
-```
-
-### 2. Show Local Health
-
-Run:
-
-```bash
-threadnote doctor --dry-run
-threadnote start
-```
-
-Say:
-
-```text
-The server is local. The default is 127.0.0.1:1933, so it does not conflict with apps running on localhost:80 or
-localhost:443. If the exact port is taken, we can set THREADNOTE_PORT.
-```
-
-### 3. Show MCP Is Installed
-
-Run the client-specific check you want to demo:
-
-```bash
-codex mcp list
-claude mcp list
-```
-
-Say:
-
-```text
-MCP is the expected agent path. The CLI exists so humans can inspect, repair, and reproduce what the agent is doing.
-Claude installs at user scope by default, so it works from other repos and worktrees.
-```
-
-If the MCP server does not appear in an already-open agent session, restart that session after `mcp-install --apply`.
-
-### 4. Recall The Previous Handoff
-
-In the agent UI, ask:
-
-```text
-Before touching code, recall recent OpenViking context for this branch and read the most relevant handoff.
-```
-
-For a terminal fallback, run:
-
-```bash
-threadnote recall --query "last handoff for threadnote rollout"
-```
-
-Point out that recall returns candidate `viking://` URIs and abstracts. Then read the best match:
-
-```bash
-threadnote read "<paste the most relevant viking:// URI>"
-```
-
-Say:
-
-```text
-Search is intentionally a pointer step. The agent should read or list the selected URI before treating it as context.
-That keeps recall cheap and makes the result auditable.
-```
-
-### 5. Discover Repo Guidance
-
-Ask the agent:
-
-```text
-Find any repo guidance or skills that matter for this task before you continue.
-```
-
-Terminal fallback:
-
-```bash
-threadnote recall --query "repo agent instructions testing guidance"
-threadnote recall --query "skills for this repo"
-```
-
-Say:
-
-```text
-This is not source navigation. It is a curated catalog of instructions, skills, and durable notes that helps the agent
-start in the right neighborhood.
-```
-
-### 6. Show Cross-Repo Or Cross-Worktree Continuity
-
-Switch to another repo or worktree and run the same recall:
-
-```bash
-cd ~/work/another-repo
-threadnote recall --query "last handoff for threadnote rollout"
-```
-
-Or ask a fresh Claude session from another repo:
-
-```text
-Use OpenViking to recall the latest handoff for the threadnote rollout and summarize the next step.
-```
-
-Say:
-
-```text
-The repo list is developer-local and manifest-driven. Nothing assumes a fixed source path. Memories are stored in the
-local OpenViking home, so deleting a worktree removes launcher paths, not the remembered handoff.
-```
-
-### 7. Remember A Durable Fact
-
-Ask the agent:
-
-```text
-Remember this workflow fact: threadnote MCP for Claude should be installed at user scope so it works from any repo or
-worktree.
-```
-
-Terminal fallback:
-
-```bash
-threadnote remember \
-  --text "Workflow fact: install Claude OpenViking MCP at user scope so it works from any repo or worktree."
-```
-
-Say:
-
-```text
-The rule is: remember durable workflow facts, not secrets, customer data, raw logs, or long diffs. Canonical repo rules
-should still be checked in.
-```
-
-### 8. Create The Next Handoff
-
-Ask the agent:
-
-```text
-Create a handoff for the next agent with the current status, tests run, blockers, and next step.
-```
-
-Terminal fallback:
-
-```bash
-threadnote handoff \
-  --task "Demo: verified cross-agent recall for the threadnote rollout" \
-  --tests "doctor --dry-run, recall, read, remember, handoff" \
-  --next-step "Open a fresh agent session and ask it to recall this handoff before continuing"
-```
-
-Say:
-
-```text
-This is the part we want agents to do automatically before pausing or finishing meaningful code changes.
-```
-
-### 9. Show Repair
-
-Run:
-
-```bash
-threadnote repair --dry-run
-```
-
-Say:
-
-```text
-This catches the ugly local cases: stale command shims, MCP launchers pointing at deleted worktrees, missing manifests,
-and a stopped local server. Repair rewrites paths from the current checkout.
-```
-
-### 10. Close
-
-Say:
-
-```text
-The important design choice is that this does not replace the repo. It makes the useful working memory around the repo
-available to whichever agent session picks up the task next.
-```
-
-## Expected Signals
-
-- `doctor --dry-run` reports no failures or prints concrete repair steps.
-- `recall` returns `memory`, `resource`, or `skill` rows with `viking://` URIs.
-- `read` turns a selected URI into actual handoff or memory content.
-- A fresh agent session can use the OpenViking MCP tools after MCP install.
-- `repair --dry-run` explains what it would fix without mutating anything.
-
-## Recovery Branches
-
-- MCP is installed but the current agent says no OpenViking tools are registered: open a fresh agent session.
-- `claude mcp list` does not show OpenViking: run `threadnote mcp-install claude --apply`; the default scope is
-  `user`.
-- `/health` is OK but `/mcp` fails: this is expected for OpenViking `0.3.12`; use the default stdio adapter instead of
-  `--native-http`.
-- The old checkout or worktree was deleted: run
-  `npm run threadnote -- repair` from any fresh checkout.
-- Recall returns only overview nodes: read the URI, or list the directory with
-  `threadnote list <uri> --all --recursive`.
-
-## What Not To Demo
-
-- Do not seed an entire repo.
-- Do not store secrets, tokens, customer data, raw production logs, or long diffs.
-- Do not present CLI commands as the ideal daily workflow. For normal work, the developer should ask the agent in
-  natural language and the agent should use MCP directly.