threadnote 0.1.0 → 0.2.1

package/README.md

@@ -4,8 +4,24 @@
 It is intentionally scoped to curated docs, memories, skills, and handoffs. It is not a source-navigation replacement,
 and it does not index whole repositories by default.
 
+## Real-World Uses
+
+Want to continue work in a fresh agent session? `threadnote install` adds user-level Codex and Claude instructions so
+new agents automatically recall recent handoffs and relevant memories before they start changing code.
+
+Implemented a feature a while ago and need to pick it up again? Ask the agent to recall the feature, branch, or repo.
+Threadnote returns auditable `viking://` pointers that the agent can read before deciding what still matters.
+
+Switching between Codex and Claude? Install the MCP adapter for both. The user-level instructions tell agents to store a
+handoff before they pause, so the next agent can search the same local memory layer instead of reconstructing context
+from chat history.
+
+Found a durable workflow fact, like how a repo runs tests or where release notes live? Ask the agent to remember it.
+Threadnote keeps that memory local and searchable without editing unrelated repo files.
+
 ## Safety Model
 
+- Machine writes stay **locally** under `THREADNOTE_HOME`, which defaults to `~/.openviking`.
 - Curated manifests only: seed commands import only paths listed in `config/seed-manifest.example.yaml` or an explicit
   per-developer manifest.
 - Ignore rules: `.threadnoteignore` excludes build output, binary artifacts, local auth files, env files, and logs.
@@ -15,7 +31,6 @@ and it does not index whole repositories by default.
 - User instructions: `install` upserts a managed Threadnote block in `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md`
   without replacing existing personal instructions.
 - Agent config changes are explicit: `mcp-install` prints commands and snippets by default; use `--apply` to run them.
-- Machine writes stay under `THREADNOTE_HOME`, which defaults to `~/.openviking`.
 
 ## Install
 
@@ -28,6 +43,15 @@ curl -fsSL https://raw.githubusercontent.com/Kashkovsky/threadnote/main/scripts/
 This installs the published package from npmjs and runs `threadnote install`. It does not use npm `postinstall`,
 because setup writes local machine config and should be an explicit action.
 
+Start the local server and confirm it is healthy:
+
+```bash
+threadnote start
+threadnote doctor --dry-run
+```
+
+If install or health checks fail, see `docs/troubleshooting.md`.
+
 To force a runtime:
 
 ```bash
@@ -40,45 +64,82 @@ Or install manually:
 ```bash
 npm install --global threadnote
 threadnote install
+threadnote start
+threadnote doctor --dry-run
 ```
 
-For a one-off check before installing globally:
+### 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.
+
+Dry-run examples:
 
 ```bash
-npm exec --yes threadnote@latest -- doctor --dry-run
-bunx threadnote@latest doctor --dry-run
-deno run --allow-read --allow-env --allow-run --allow-net npm:threadnote@latest doctor --dry-run
+threadnote mcp-install codex
+threadnote mcp-install claude
 ```
 
-Avoid using `npm exec` for `threadnote install`; durable shims and MCP launchers should point at a stable global installation, not npm's temporary package cache.
+Apply after review:
 
-## Source Checkout
+```bash
+threadnote mcp-install codex --apply
+threadnote mcp-install claude --apply
+```
 
-For local development from this repo:
+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.
+
+If the package or checkout that originally installed `threadnote` has moved, run repair:
 
 ```bash
-npm install
-npm run build
-npm run doctor -- --dry-run
-npm run threadnote -- install
+threadnote repair
 ```
 
-`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:
+This rewrites the `threadnote` shim and reinstalls the stdio MCP adapter for available agents so launcher paths point
+at the current checkout.
+
+The default install uses the bundled stdio MCP adapter, because OpenViking `0.3.12` does not expose the native `/mcp`
+HTTP route:
+
+```bash
+codex mcp add threadnote -- threadnote-mcp-server
+claude mcp add threadnote -- threadnote-mcp-server
+```
+
+If a future OpenViking build exposes a healthy native endpoint, install it explicitly:
+
+```bash
+threadnote mcp-install claude --native-http --apply
+```
+
+### Seed Local Repos
+
+Memories and handoffs work before seeding. Seed local repos when you want agents to recall repo guidance, docs, and
+skills without reopening the same files by hand.
+
+Create or update the local manifest with the repos you care about:
 
 ```bash
-threadnote doctor --dry-run
 threadnote init-manifest --repo ~/src/my-service --repo ~/work/mobile-app
-threadnote start
+```
+
+Review what will be imported, then seed curated repo guidance:
+
+```bash
 threadnote seed --dry-run
+threadnote seed
+```
+
+Optionally seed shared and repo-local skills:
+
+```bash
 threadnote seed-skills --dry-run
+threadnote seed-skills
 ```
 
-If `~/.local/bin` is not on your `PATH`, either add it or set `THREADNOTE_BIN_DIR` before running `install`.
-After reviewing dry-run output, remove `--dry-run` for the operation you want to perform.
+When you add another local repo later, rerun `init-manifest --repo <path>` and seed again.
 
-The bundled `config/seed-manifest.example.yaml` is only an example. Each developer should create a local manifest at
-`~/.openviking/seed-manifest.yaml` with `threadnote init-manifest`; repo paths can be anywhere.
+This is it! Start working with your agents as usual. The agent will automatically recall relevant memories and store the new ones. If you want to force it to recall/handoff something, just ask explicitly.
 
 ## Commands
 
@@ -89,6 +150,8 @@ The bundled `config/seed-manifest.example.yaml` is only an example. Each develop
   current checkout.
 - `start`: starts `openviking-server` on `127.0.0.1:1933`.
 - `stop`: stops the detached server pid or macOS LaunchAgent.
+- `uninstall`: removes Threadnote shims, MCP config, launchd config, and managed user instructions. Memories are
+  preserved by default; pass `--erase-memories` to delete `THREADNOTE_HOME`.
 - `init-manifest`: creates or updates `~/.openviking/seed-manifest.yaml` from one or more developer repo roots.
 - `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
@@ -103,6 +166,34 @@ The bundled `config/seed-manifest.example.yaml` is only an example. Each develop
 - `forget`: removes a `viking://` URI.
 - `export-pack` / `import-pack`: moves local context through `.ovpack` files.
 
+## Source Checkout
+
+For local development from this repo:
+
+```bash
+npm install
+npm run build
+npm run doctor -- --dry-run
+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:
+
+```bash
+threadnote doctor --dry-run
+threadnote init-manifest --repo ~/src/my-service --repo ~/work/mobile-app
+threadnote start
+threadnote seed --dry-run
+threadnote seed-skills --dry-run
+```
+
+If `~/.local/bin` is not on your `PATH`, either add it or set `THREADNOTE_BIN_DIR` before running `install`.
+After reviewing dry-run output, remove `--dry-run` for the operation you want to perform.
+
+The bundled `config/seed-manifest.example.yaml` is only an example. Each developer should create a local manifest at
+`~/.openviking/seed-manifest.yaml` with `threadnote init-manifest`; repo paths can be anywhere.
+
 ## Configuration
 
 Environment variables:
@@ -122,65 +213,7 @@ Local projects using `localhost:80` or `localhost:443` do not conflict with Open
 only occurs when another process already owns the same host and port. If that happens, choose a different
 `THREADNOTE_PORT`.
 
-## MCP
-
-Dry-run examples:
-
-```bash
-threadnote mcp-install codex
-threadnote mcp-install claude
-```
-
-Apply after review:
-
-```bash
-threadnote mcp-install codex --apply
-threadnote mcp-install claude --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.
-
-If the package or checkout that originally installed `threadnote` has moved, run repair:
-
-```bash
-threadnote repair
-```
-
-This rewrites the `threadnote` shim and reinstalls the stdio MCP adapter for available agents so launcher paths point
-at the current checkout.
-
-The default install uses the bundled stdio MCP adapter, because OpenViking `0.3.12` does not expose the native `/mcp`
-HTTP route:
-
-```bash
-codex mcp add threadnote -- threadnote-mcp-server
-claude mcp add threadnote -- threadnote-mcp-server
-```
-
-If a future OpenViking build exposes a healthy native endpoint, install it explicitly:
-
-```bash
-threadnote mcp-install claude --native-http --apply
-```
-
-## Notes
-
-OpenViking itself is not vendored here. This prototype installs and controls a local service and should get legal and
-security review before broader rollout.
-
-## Publishing
-
-The npm package ships bundled CommonJS `.cjs` entrypoints in `dist/`; `tsx` is only used by `npm run dev` for
-source-checkout development. There is no published TypeScript runner and no runtime npm dependency tree. The generated
-user shim tries Node, Bun, then Deno.
-
-```bash
-npm run typecheck
-npm run build
-npm pack --dry-run
-npm publish
-```
+## Misc
 
 See `docs/migration.md` for switching an existing repo workflow to `threadnote` without deleting canonical
 `AGENTS.md`, `CLAUDE.md`, `.claude/`, or `.agents/` files.

package/dist/threadnote.cjs

@@ -3491,11 +3491,12 @@ var import_promises6 = require("node:fs/promises");
 var import_promises7 = require("node:fs/promises");
 var import_node_path5 = require("node:path");
 var import_node_path6 = require("node:path");
+var import_promises8 = require("node:fs/promises");
 var import_node_path7 = require("node:path");
 var import_node_child_process = require("node:child_process");
-var import_promises8 = require("node:fs/promises");
-var import_node_os3 = require("node:os");
 var import_promises9 = require("node:fs/promises");
+var import_node_os3 = require("node:os");
+var import_promises10 = require("node:fs/promises");
 
 // node_modules/.deno/js-yaml@4.1.1/node_modules/js-yaml/dist/js-yaml.mjs
 function isNothing(subject) {
@@ -6130,8 +6131,12 @@ var DEFAULT_AGENT_ID = "threadnote";
 var OPENVIKING_PACKAGE_NAME = "openviking[local-embed]";
 var OPENVIKING_SERVER_COMMAND = "openviking-server";
 var OPENVIKING_MCP_NAME = "threadnote";
+var PYTHON_SYSTEM_CERTS_MODULE = "pip_system_certs";
+var PYTHON_SYSTEM_CERTS_PACKAGE = "pip-system-certs";
 var LAUNCHD_LABEL = "io.threadnote.openviking";
 var MAX_SECRET_MATCHES_TO_PRINT = 5;
+var START_HEALTH_POLL_INTERVAL_MS = 500;
+var START_HEALTH_TIMEOUT_MS = 15e3;
 var SHIM_MARKER = "Generated by threadnote";
 var USER_INSTRUCTIONS_START_MARKER = "<!-- BEGIN THREADNOTE USER INSTRUCTIONS -->";
 var USER_INSTRUCTIONS_END_MARKER = "<!-- END THREADNOTE USER INSTRUCTIONS -->";
@@ -6178,6 +6183,13 @@ async function main() {
   program2.command("stop").description("Stop the local OpenViking server or LaunchAgent").option("--dry-run", "Print the stop actions without running them").action(async (options) => {
     await runStop(getRuntimeConfig(program2), options);
   });
+  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",
+    "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);
+  });
   program2.command("seed").description("Seed curated context from the manifest; never indexes whole repos by default").option("--dry-run", "Print files and ov commands without importing").option("--manifest <path>", "Manifest path for this seed run").action(async (options) => {
     await runSeed(getRuntimeConfig(program2, options.manifest), options);
   });
@@ -6249,6 +6261,7 @@ async function runDoctor(config, options) {
   checks.push(await commandCheck("openviking-server", ["--help"]));
   checks.push(await firstCommandCheck("openviking cli", ["ov", "openviking"], ["--help"]));
   checks.push(await localEmbeddingCheck());
+  checks.push(await pythonSystemCertificatesCheck());
   checks.push(await firstCommandCheck("python installer", ["pipx", "uv", "pip3"], ["--version"]));
   checks.push(await commandPresenceCheck("codex", ["--version"]));
   checks.push(await commandPresenceCheck("claude", ["--version"]));
@@ -6281,14 +6294,19 @@ 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) {
-      console.log("OpenViking local embedding extra is missing; repairing install.");
-      const installCommand = await getInstallCommand(config, options.packageManager, true);
-      await maybeRun(options.dryRun === true, installCommand.executable, installCommand.args);
+      repairReasons.push("local embedding extra is missing");
+    }
+    if (await hasPythonSystemCertificatesPatch(serverPath) === false) {
+      repairReasons.push("Python system certificate bridge is missing");
+    }
+    if (repairReasons.length > 0) {
+      console.log(`OpenViking install needs repair: ${repairReasons.join("; ")}.`);
+      await runInstallCommands(config, options.packageManager, true, options.dryRun === true);
     }
   } else {
-    const installCommand = await getInstallCommand(config, options.packageManager, false);
-    await maybeRun(options.dryRun === true, installCommand.executable, installCommand.args);
+    await runInstallCommands(config, options.packageManager, false, options.dryRun === true);
   }
   await writeTemplateIfMissing({
     config,
@@ -6304,9 +6322,9 @@ async function runInstall(config, options) {
     shouldRepair: (content) => shouldRepairLegacyOvCliConfig(content) || repairInvalidConfigs && parseJsonConfigObject(content) === void 0,
     templatePath: (0, import_node_path4.join)(toolRoot(), "config", "ovcli.conf.template.json")
   });
-  console.log("Install complete. Run doctor, then start:");
-  console.log("  threadnote doctor");
+  console.log("Install complete. Run start, then doctor:");
   console.log("  threadnote start");
+  console.log("  threadnote doctor");
 }
 async function runRepair(config, options) {
   const dryRun = options.dryRun === true;
@@ -6318,7 +6336,7 @@ async function runRepair(config, options) {
   } else {
     console.log("Skipping server health repair because --no-start was provided.");
   }
-  const mcpClients = await resolveRepairMcpClients(options.mcp ?? "available");
+  const mcpClients = await resolveMcpClients(options.mcp ?? "available", "repair");
   if (mcpClients.length === 0) {
     console.log("Skipping MCP config repair.");
   } else {
@@ -6330,6 +6348,28 @@ async function runRepair(config, options) {
   console.log("\nPost-repair doctor:");
   await runDoctor(config, { dryRun, strict: false });
 }
+async function runUninstall(config, options) {
+  const dryRun = options.dryRun === true;
+  if (options.eraseMemories === true && options.preserveMemories === true) {
+    throw new Error("Use either --erase-memories or --preserve-memories, not both.");
+  }
+  console.log("Uninstalling local Threadnote setup.");
+  await runStop(config, { dryRun });
+  await removePathIfExists((0, import_node_path4.join)(config.agentContextHome, "openviking-server.pid"), "pid file", dryRun);
+  await removeLaunchAgent(dryRun);
+  await removeMcpConfigs(options.mcp ?? "available", dryRun);
+  await removeMcpSnippets(config, dryRun);
+  await removeCommandShim(dryRun);
+  await removeUserAgentInstructions(dryRun);
+  if (options.eraseMemories === true) {
+    await eraseThreadnoteHome(config.agentContextHome, dryRun);
+  } else {
+    console.log(`Preserving local memories and OpenViking home: ${config.agentContextHome}`);
+    console.log("Use --erase-memories to delete this directory during uninstall.");
+  }
+  console.log("Uninstall complete.");
+  console.log("The package remains installed. Remove it with your package manager if desired.");
+}
 async function repairManifest(config, dryRun) {
   try {
     await readSeedManifest(config.manifestPath);
@@ -6373,11 +6413,11 @@ async function repairManifest(config, dryRun) {
   const currentContent = await readFileIfExists(config.manifestPath);
   if (currentContent !== void 0) {
     const backupPath = `${config.manifestPath}.legacy-${safeTimestamp()}`;
-    await (0, import_promises9.writeFile)(backupPath, currentContent, { encoding: "utf8", mode: 384 });
+    await (0, import_promises10.writeFile)(backupPath, currentContent, { encoding: "utf8", mode: 384 });
     await (0, import_promises2.chmod)(backupPath, 384);
     console.log(`Backup: ${backupPath}`);
   }
-  await (0, import_promises9.writeFile)(config.manifestPath, output, { encoding: "utf8", mode: 384 });
+  await (0, import_promises10.writeFile)(config.manifestPath, output, { encoding: "utf8", mode: 384 });
   await (0, import_promises2.chmod)(config.manifestPath, 384);
   console.log(`Wrote replacement manifest: ${config.manifestPath}`);
 }
@@ -6406,8 +6446,9 @@ async function runStart(config, options) {
     return;
   }
   const existingHealth = await readOpenVikingHealthIfAvailable(config, 500);
+  const healthUrl = openVikingHealthUrl(config);
   if (existingHealth) {
-    console.log(`OpenViking is already healthy at http://${config.host}:${config.port}/health`);
+    console.log(`OpenViking is already healthy at ${healthUrl}`);
     return;
   }
   if (await isTcpPortOpen(config.host, config.port, 500)) {
@@ -6415,19 +6456,26 @@ async function runStart(config, options) {
       `Port ${config.host}:${config.port} is already in use, but it is not a healthy OpenViking server. Set THREADNOTE_PORT or pass --port to use a different port.`
     );
   }
-  await ensureDirectory((0, import_node_path4.join)(config.agentContextHome, "logs"), false);
+  const logPath = openVikingLogPath(config);
+  await ensureDirectory((0, import_node_path2.dirname)(logPath), false);
   if (options.foreground === true) {
     const result = await runInteractive(server, args);
     process.exitCode = result;
     return;
   }
-  const logPath = (0, import_node_path4.join)(config.agentContextHome, "logs", "server.log");
   const logFd = (0, import_node_fs3.openSync)(logPath, "a");
   const child = spawnDetachedServerWithLog(server, args, logFd);
   child.unref();
-  await (0, import_promises9.writeFile)((0, import_node_path4.join)(config.agentContextHome, "openviking-server.pid"), `${child.pid}
+  await (0, import_promises10.writeFile)((0, import_node_path4.join)(config.agentContextHome, "openviking-server.pid"), `${child.pid}
 `, "utf8");
-  console.log(`Started OpenViking with pid ${child.pid}. Logs: ${logPath}`);
+  const health = await waitForOpenVikingHealth(config, START_HEALTH_TIMEOUT_MS);
+  if (health) {
+    console.log(`Started OpenViking with pid ${child.pid}. Health OK at ${healthUrl}. Logs: ${logPath}`);
+    return;
+  }
+  throw new Error(
+    `Started OpenViking with pid ${child.pid}, but ${healthUrl} did not become healthy within ${START_HEALTH_TIMEOUT_MS / 1e3}s. Logs: ${logPath}`
+  );
 }
 function spawnDetachedServerWithLog(server, args, logFd) {
   try {
@@ -6445,7 +6493,11 @@ function spawnDetachedServer(server, args, logFd) {
 async function runStop(config, options) {
   const launchAgentPath = expandPath(`~/Library/LaunchAgents/${LAUNCHD_LABEL}.plist`);
   if ((0, import_node_os2.platform)() === "darwin") {
-    await maybeRun(options.dryRun === true, "launchctl", ["unload", launchAgentPath], { allowFailure: true });
+    if (options.dryRun === true || await exists(launchAgentPath)) {
+      await maybeRun(options.dryRun === true, "launchctl", ["unload", launchAgentPath], { allowFailure: true });
+    } else {
+      console.log(`No LaunchAgent found: ${launchAgentPath}`);
+    }
   }
   const pidPath = (0, import_node_path4.join)(config.agentContextHome, "openviking-server.pid");
   const pidText = await readFileIfExists(pidPath);
@@ -6541,7 +6593,7 @@ async function runInitManifest(config, options) {
     return;
   }
   await ensureDirectory((0, import_node_path2.dirname)(manifestPath), false);
-  await (0, import_promises9.writeFile)(manifestPath, output, { encoding: "utf8", mode: 384 });
+  await (0, import_promises10.writeFile)(manifestPath, output, { encoding: "utf8", mode: 384 });
   await (0, import_promises2.chmod)(manifestPath, 384);
   console.log(`Wrote manifest: ${manifestPath}`);
   console.log("Seed with:");
@@ -6790,6 +6842,21 @@ async function localEmbeddingCheck() {
     detail: "llama_cpp missing; install will repair with openviking[local-embed]"
   };
 }
+async function pythonSystemCertificatesCheck() {
+  const serverPath = await findExecutable([OPENVIKING_SERVER_COMMAND]);
+  if (!serverPath) {
+    return { name: "python system certs", status: "warn", detail: "openviking-server missing" };
+  }
+  const hasDependency = await hasPythonSystemCertificatesPatch(serverPath);
+  if (hasDependency === void 0) {
+    return { name: "python system certs", status: "warn", detail: "could not inspect tool Python" };
+  }
+  return hasDependency ? { name: "python system certs", status: "ok", detail: `${PYTHON_SYSTEM_CERTS_MODULE} import works` } : {
+    name: "python system certs",
+    status: "warn",
+    detail: `${PYTHON_SYSTEM_CERTS_MODULE} missing; install will repair corporate TLS support`
+  };
+}
 async function commandShimCheck() {
   const shimPath = (0, import_node_path4.join)(expandPath(process.env.THREADNOTE_BIN_DIR ?? "~/.local/bin"), "threadnote");
   const content = await readFileIfExists(shimPath);
@@ -6833,11 +6900,17 @@ async function userAgentInstructionsChecks() {
   );
 }
 async function hasLocalEmbeddingDependency(serverPath) {
+  return hasPythonModule(serverPath, "llama_cpp");
+}
+async function hasPythonSystemCertificatesPatch(serverPath) {
+  return hasPythonModule(serverPath, PYTHON_SYSTEM_CERTS_MODULE);
+}
+async function hasPythonModule(serverPath, moduleName) {
   const pythonPath = await siblingPythonForExecutable(serverPath);
   if (!pythonPath) {
     return void 0;
   }
-  const result = await runCommand(pythonPath, ["-c", "import llama_cpp"], { allowFailure: true });
+  const result = await runCommand(pythonPath, ["-c", `import ${moduleName}`], { allowFailure: true });
   return result.exitCode === 0;
 }
 async function siblingPythonForExecutable(executablePath) {
@@ -6870,7 +6943,7 @@ async function healthCheck(config) {
   }
 }
 async function readOpenVikingHealth(config, timeoutMs) {
-  return httpGetText(`http://${config.host}:${config.port}/health`, timeoutMs);
+  return httpGetText(openVikingHealthUrl(config), timeoutMs);
 }
 async function readOpenVikingHealthIfAvailable(config, timeoutMs) {
   try {
@@ -6879,24 +6952,62 @@ async function readOpenVikingHealthIfAvailable(config, timeoutMs) {
     return void 0;
   }
 }
-async function getInstallCommand(config, preferred, force) {
+function openVikingHealthUrl(config) {
+  return `http://${config.host}:${config.port}/health`;
+}
+function openVikingLogPath(config) {
+  return (0, import_node_path4.join)(config.agentContextHome, "logs", "server.log");
+}
+async function waitForOpenVikingHealth(config, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() <= deadline) {
+    const requestTimeoutMs = Math.max(100, Math.min(1e3, deadline - Date.now()));
+    const health = await readOpenVikingHealthIfAvailable(config, requestTimeoutMs);
+    if (health) {
+      return health;
+    }
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      break;
+    }
+    await sleep(Math.min(START_HEALTH_POLL_INTERVAL_MS, remainingMs));
+  }
+  return void 0;
+}
+async function runInstallCommands(config, preferred, force, dryRun) {
+  const installCommands = await getInstallCommands(config, preferred, force);
+  for (const installCommand of installCommands) {
+    await maybeRun(dryRun, installCommand.executable, installCommand.args);
+  }
+}
+async function getInstallCommands(config, preferred, force) {
   const packageSpec = `${OPENVIKING_PACKAGE_NAME}==${config.openVikingVersion}`;
   const manager = preferred ?? await detectPackageManager();
   if (manager === "pipx") {
-    return { executable: "pipx", args: force ? ["install", "--force", packageSpec] : ["install", packageSpec] };
+    return [
+      { executable: "pipx", args: force ? ["install", "--force", packageSpec] : ["install", packageSpec] },
+      {
+        executable: "pipx",
+        args: force ? ["inject", "--force", "openviking", PYTHON_SYSTEM_CERTS_PACKAGE] : ["inject", "openviking", PYTHON_SYSTEM_CERTS_PACKAGE]
+      }
+    ];
   }
   if (manager === "uv") {
-    return {
-      executable: "uv",
-      args: force ? ["tool", "install", "--force", packageSpec] : ["tool", "install", packageSpec]
-    };
+    const uvArgs = ["tool", "install", "--native-tls", "--with", PYTHON_SYSTEM_CERTS_PACKAGE];
+    return [
+      {
+        executable: "uv",
+        args: force ? [...uvArgs, "--force", packageSpec] : [...uvArgs, packageSpec]
+      }
+    ];
   }
   const pipArgs = ["-m", "pip", "install", "--user"];
   if (force) {
     pipArgs.push("--upgrade", "--force-reinstall");
   }
+  pipArgs.push(PYTHON_SYSTEM_CERTS_PACKAGE);
   pipArgs.push(packageSpec);
-  return { executable: "python3", args: pipArgs };
+  return [{ executable: "python3", args: pipArgs }];
 }
 async function detectPackageManager() {
   if (await findExecutable(["pipx"])) {
@@ -6920,9 +7031,9 @@ async function writeTemplateIfMissing(options) {
       return;
     }
     const backupPath = `${options.destinationPath}.legacy-${safeTimestamp()}`;
-    await (0, import_promises9.writeFile)(backupPath, currentContent, { encoding: "utf8", mode: 384 });
+    await (0, import_promises10.writeFile)(backupPath, currentContent, { encoding: "utf8", mode: 384 });
     await (0, import_promises2.chmod)(backupPath, 384);
-    await (0, import_promises9.writeFile)(options.destinationPath, rendered2, { encoding: "utf8", mode: 384 });
+    await (0, import_promises10.writeFile)(options.destinationPath, rendered2, { encoding: "utf8", mode: 384 });
     await (0, import_promises2.chmod)(options.destinationPath, 384);
     console.log(`Repaired generated config: ${options.destinationPath}`);
     console.log(`Backup: ${backupPath}`);
@@ -6934,7 +7045,7 @@ async function writeTemplateIfMissing(options) {
     return;
   }
   await ensureDirectory((0, import_node_path2.dirname)(options.destinationPath), false);
-  await (0, import_promises9.writeFile)(options.destinationPath, rendered, { encoding: "utf8", mode: 384 });
+  await (0, import_promises10.writeFile)(options.destinationPath, rendered, { encoding: "utf8", mode: 384 });
   await (0, import_promises2.chmod)(options.destinationPath, 384);
   console.log(`Wrote ${options.destinationPath}`);
 }
@@ -6956,10 +7067,23 @@ async function installCommandShim(dryRun) {
     return;
   }
   await ensureDirectory(binDir, false);
-  await (0, import_promises9.writeFile)(shimPath, content, { encoding: "utf8", mode: 493 });
+  await (0, import_promises10.writeFile)(shimPath, content, { encoding: "utf8", mode: 493 });
   await (0, import_promises2.chmod)(shimPath, 493);
   console.log(`Wrote command shim: ${shimPath}`);
 }
+async function removeCommandShim(dryRun) {
+  const shimPath = (0, import_node_path4.join)(expandPath(process.env.THREADNOTE_BIN_DIR ?? "~/.local/bin"), "threadnote");
+  const content = await readFileIfExists(shimPath);
+  if (content === void 0) {
+    console.log(`Already absent: ${shimPath}`);
+    return;
+  }
+  if (!isManagedCommandShim(content)) {
+    console.log(`WARN not removing unmanaged command shim: ${shimPath}`);
+    return;
+  }
+  await removePath(shimPath, "command shim", dryRun);
+}
 async function installUserAgentInstructions(dryRun) {
   const block = await renderUserAgentInstructionsBlock();
   for (const target of USER_AGENT_INSTRUCTION_TARGETS) {
@@ -6979,10 +7103,39 @@ async function installUserAgentInstructions(dryRun) {
       continue;
     }
     await ensureDirectory((0, import_node_path2.dirname)(targetPath), false);
-    await (0, import_promises9.writeFile)(targetPath, nextContent, { encoding: "utf8", mode: 420 });
+    await (0, import_promises10.writeFile)(targetPath, nextContent, { encoding: "utf8", mode: 420 });
     console.log(currentContent === void 0 ? `Wrote ${targetPath}` : `Updated ${targetPath}`);
   }
 }
+async function removeUserAgentInstructions(dryRun) {
+  for (const target of USER_AGENT_INSTRUCTION_TARGETS) {
+    const targetPath = expandPath(target.path);
+    const currentContent = await readFileIfExists(targetPath);
+    if (currentContent === void 0) {
+      console.log(`Already absent: ${targetPath}`);
+      continue;
+    }
+    const nextContent = removeManagedBlock(currentContent);
+    if (nextContent === void 0) {
+      console.log(`WARN ${targetPath} has partial threadnote markers; not modifying it`);
+      continue;
+    }
+    if (nextContent === currentContent) {
+      console.log(`No threadnote block found: ${targetPath}`);
+      continue;
+    }
+    if (nextContent.trim().length === 0) {
+      await removePath(targetPath, target.label, dryRun);
+      continue;
+    }
+    if (dryRun) {
+      console.log(`Would update ${targetPath}`);
+      continue;
+    }
+    await (0, import_promises10.writeFile)(targetPath, nextContent, { encoding: "utf8", mode: 420 });
+    console.log(`Updated ${targetPath}`);
+  }
+}
 async function renderUserAgentInstructionsBlock() {
   const instructions = (await (0, import_promises5.readFile)((0, import_node_path4.join)(toolRoot(), "docs", "agent-instructions.md"), "utf8")).trim();
   return `${USER_INSTRUCTIONS_START_MARKER}
@@ -7010,6 +7163,20 @@ function upsertManagedBlock(content, block) {
   }
   return joinMarkdownSections([content.trimEnd(), block]);
 }
+function removeManagedBlock(content) {
+  const startIndex = content.indexOf(USER_INSTRUCTIONS_START_MARKER);
+  const endIndex = content.indexOf(USER_INSTRUCTIONS_END_MARKER);
+  if (startIndex === -1 !== (endIndex === -1) || endIndex < startIndex) {
+    return void 0;
+  }
+  if (startIndex === -1) {
+    return content;
+  }
+  const before = content.slice(0, startIndex).trimEnd();
+  const after = content.slice(endIndex + USER_INSTRUCTIONS_END_MARKER.length).trimStart();
+  const nextContent = joinMarkdownSections([before, after]);
+  return nextContent.trim().length > 0 ? nextContent : "";
+}
 function joinMarkdownSections(sections) {
   return `${sections.filter((section) => section.length > 0).join("\n\n")}
 `;
@@ -7059,11 +7226,52 @@ async function installLaunchAgent(config, dryRun) {
     return;
   }
   await ensureDirectory((0, import_node_path2.dirname)(destination), false);
-  await (0, import_promises9.writeFile)(destination, rendered, "utf8");
+  await ensureDirectory((0, import_node_path2.dirname)(openVikingLogPath(config)), false);
+  await (0, import_promises10.writeFile)(destination, rendered, "utf8");
   await maybeRun(false, "launchctl", ["unload", destination], { allowFailure: true });
   await maybeRun(false, "launchctl", ["load", destination]);
   await maybeRun(false, "launchctl", ["start", LAUNCHD_LABEL]);
-  console.log(`Installed and started ${LAUNCHD_LABEL}`);
+  const healthUrl = openVikingHealthUrl(config);
+  const health = await waitForOpenVikingHealth(config, START_HEALTH_TIMEOUT_MS);
+  if (health) {
+    console.log(`Installed and started ${LAUNCHD_LABEL}. Health OK at ${healthUrl}`);
+    return;
+  }
+  throw new Error(
+    `Installed and started ${LAUNCHD_LABEL}, but ${healthUrl} did not become healthy within ${START_HEALTH_TIMEOUT_MS / 1e3}s. Logs: ${openVikingLogPath(config)}`
+  );
+}
+async function removeLaunchAgent(dryRun) {
+  const launchAgentPath = expandPath(`~/Library/LaunchAgents/${LAUNCHD_LABEL}.plist`);
+  const content = await readFileIfExists(launchAgentPath);
+  if (content === void 0) {
+    console.log(`Already absent: ${launchAgentPath}`);
+    return;
+  }
+  if (!content.includes(LAUNCHD_LABEL) || !content.includes(OPENVIKING_SERVER_COMMAND)) {
+    console.log(`WARN not removing unmanaged LaunchAgent: ${launchAgentPath}`);
+    return;
+  }
+  await removePath(launchAgentPath, "LaunchAgent", dryRun);
+}
+async function removeMcpConfigs(value, dryRun) {
+  const clients = await resolveMcpClients(value, "remove");
+  if (clients.length === 0) {
+    console.log("Skipping MCP config removal.");
+    return;
+  }
+  for (const client of clients) {
+    const command = buildMcpRemoveCommand(client, OPENVIKING_MCP_NAME);
+    await maybeRun(dryRun, command.executable, command.args, { allowFailure: true, cwd: command.cwd });
+  }
+}
+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);
+}
+async function eraseThreadnoteHome(path, dryRun) {
+  assertSafeThreadnoteHomeForErase(path);
+  await removePathIfExists(path, "THREADNOTE_HOME and all memories", dryRun);
 }
 function openVikingServerArgs(config) {
   return ["--config", (0, import_node_path4.join)(config.agentContextHome, "ov.conf"), "--host", config.host, "--port", String(config.port)];
@@ -7123,7 +7331,7 @@ async function prepareSeedFile(config, candidate, dryRun) {
     return redactedPath;
   }
   await ensureDirectory((0, import_node_path2.dirname)(redactedPath), false);
-  await (0, import_promises9.writeFile)(redactedPath, redactedContent, { encoding: "utf8", mode: 384 });
+  await (0, import_promises10.writeFile)(redactedPath, redactedContent, { encoding: "utf8", mode: 384 });
   await (0, import_promises2.chmod)(redactedPath, 384);
   return redactedPath;
 }
@@ -7188,7 +7396,7 @@ function buildMcpInstallCommand(config, agent, name, options) {
     if (agent === "codex") {
       return {
         executable: "codex",
-        args: ["mcp", "add", ...env.flatMap((value) => ["--env", value]), name, "--", ...command]
+        args: ["mcp", "add", ...env.flatMap((value) => ["--env", value]), name, "--", "/usr/bin/env", ...command]
       };
     }
     return {
@@ -7263,7 +7471,7 @@ async function storeMemory(config, memory, dryRun) {
     console.log(formatShellCommand(ov, withIdentity(config, ["add-memory", memory])));
     return;
   }
-  await (0, import_promises9.writeFile)(memoryPath, memory, { encoding: "utf8", mode: 384 });
+  await (0, import_promises10.writeFile)(memoryPath, memory, { encoding: "utf8", mode: 384 });
   await (0, import_promises2.chmod)(memoryPath, 384);
   await maybeRun(false, ov, withIdentity(config, ["add-memory", memory]));
 }
@@ -7691,6 +7899,11 @@ async function httpGetText(url, timeoutMs) {
     request.on("error", rejectPromise);
   });
 }
+async function sleep(ms) {
+  return new Promise((resolvePromise) => {
+    setTimeout(resolvePromise, ms);
+  });
+}
 async function readHttpStatus(url, timeoutMs) {
   return new Promise((resolvePromise) => {
     const request = (0, import_node_http.get)(url, (response) => {
@@ -7764,14 +7977,14 @@ async function exists(path) {
 }
 async function isFile(path) {
   try {
-    return (await (0, import_promises8.stat)(path)).isFile();
+    return (await (0, import_promises9.stat)(path)).isFile();
   } catch (_err) {
     return false;
   }
 }
 async function isDirectory(path) {
   try {
-    return (await (0, import_promises8.stat)(path)).isDirectory();
+    return (await (0, import_promises9.stat)(path)).isDirectory();
   } catch (_err) {
     return false;
   }
@@ -7783,6 +7996,21 @@ async function readFileIfExists(path) {
     return void 0;
   }
 }
+async function removePathIfExists(path, label, dryRun) {
+  if (!await exists(path)) {
+    console.log(`Already absent: ${path}`);
+    return;
+  }
+  await removePath(path, label, dryRun);
+}
+async function removePath(path, label, dryRun) {
+  if (dryRun) {
+    console.log(`Would remove ${label}: ${path}`);
+    return;
+  }
+  await (0, import_promises8.rm)(path, { force: true, recursive: true });
+  console.log(`Removed ${label}: ${path}`);
+}
 function renderTemplate(template, config) {
   return template.replaceAll("{{THREADNOTE_HOME}}", config.agentContextHome).replaceAll("{{OPENVIKING_ACCOUNT}}", config.account).replaceAll("{{OPENVIKING_AGENT_ID}}", config.agentId).replaceAll("{{OPENVIKING_HOST}}", config.host).replaceAll("{{OPENVIKING_PORT}}", String(config.port)).replaceAll("{{OPENVIKING_USER}}", config.user);
 }
@@ -7818,7 +8046,7 @@ function parseClaudeMcpScope(value) {
   }
   throw new Error(`Invalid Claude MCP scope: ${value}. Expected local, project, or user.`);
 }
-async function resolveRepairMcpClients(value) {
+async function resolveMcpClients(value, action) {
   const normalized = value.trim().toLowerCase();
   if (normalized === "none" || normalized === "false" || normalized === "off") {
     return [];
@@ -7832,7 +8060,7 @@ async function resolveRepairMcpClients(value) {
   const clients = [];
   for (const client of requested) {
     if (!await findExecutable([client])) {
-      console.log(`WARN ${client} command not found; cannot repair ${client} MCP config.`);
+      console.log(`WARN ${client} command not found; cannot ${action} ${client} MCP config.`);
       continue;
     }
     if (!clients.includes(client)) {
@@ -7858,6 +8086,12 @@ function expandPath(path) {
   }
   return (0, import_node_path3.isAbsolute)(path) ? path : (0, import_node_path6.resolve)(getInvocationCwd(), path);
 }
+function assertSafeThreadnoteHomeForErase(path) {
+  const resolvedPath = (0, import_node_path6.resolve)(path);
+  if (resolvedPath === "/" || resolvedPath === (0, import_node_os.homedir)() || resolvedPath === (0, import_node_path2.dirname)((0, import_node_os.homedir)())) {
+    throw new Error(`Refusing to erase unsafe THREADNOTE_HOME: ${resolvedPath}`);
+  }
+}
 function portablePath(path) {
   const home = (0, import_node_os.homedir)();
   const resolvedPath = (0, import_node_path6.resolve)(path);

package/docs/rollout.md

@@ -21,4 +21,4 @@ Start with a local-only pilot.
 - Codex and Claude can both store and recall a shared handoff.
 - Seeding curated guidance does not import known secret patterns.
 - Fresh agents can recall repo testing guidance and discover relevant skills.
-- Removing OpenViking leaves agent configs in a known state.
+- `uninstall --dry-run` previews removal, and `uninstall` leaves memories intact unless `--erase-memories` is explicit.

package/docs/security.md

@@ -17,6 +17,7 @@
 - `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.
+- `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.
 
 ## Rollout Requirements

package/docs/troubleshooting.md

@@ -10,6 +10,38 @@ threadnote install
 
 The installer prefers `pipx`, then `uv`, then `python3 -m pip install --user`.
 
+## `uv` Fails With `UnknownIssuer`
+
+Some corporate machines trust PyPI through certificates installed in the system keychain. Threadnote passes
+`--native-tls` when it uses `uv` so those system certificates are loaded.
+
+If an older install still fails with `invalid peer certificate: UnknownIssuer`, retry with:
+
+```bash
+UV_NATIVE_TLS=1 threadnote install
+```
+
+Or use a different Python installer:
+
+```bash
+threadnote install --package-manager pipx
+threadnote install --package-manager pip
+```
+
+## Model Download Fails With `CERTIFICATE_VERIFY_FAILED`
+
+On first start, OpenViking may download the local embedding model from Hugging Face. If `~/.openviking/logs/server.log`
+shows `SSLCertVerificationError`, `self-signed certificate in certificate chain`, or `Failed to download local embedding
+model`, repair the OpenViking Python environment and start again:
+
+```bash
+threadnote repair --package-manager uv
+threadnote start
+```
+
+Threadnote installs `pip-system-certs` into the OpenViking environment so Python `requests` can use certificates trusted
+by the operating system.
+
 ## Local Embedding Extra Missing
 
 The default OpenViking config uses the local embedding backend. If the server log says `llama-cpp-python` is missing,
@@ -23,6 +55,14 @@ The installer repairs this by installing `openviking[local-embed]`.
 
 ## Server Health Fails
 
+If `doctor` reports `WARN openviking health: connect ECONNREFUSED 127.0.0.1:1933`, the local server is not running.
+Start it and recheck:
+
+```bash
+threadnote start
+threadnote doctor --dry-run
+```
+
 Check whether the server is running:
 
 ```bash
@@ -35,6 +75,9 @@ For detached starts, logs are written to:
 ~/.openviking/logs/server.log
 ```
 
+If `start` reports that OpenViking did not become healthy, open that log. Certificate failures during the first embedding
+model download are covered above.
+
 ## Port Already In Use
 
 The default bind address is `127.0.0.1:1933`. This does not conflict with projects serving `localhost:80`,
@@ -105,3 +148,15 @@ This is expected. Run with `--apply` after reviewing the command:
 ```bash
 threadnote mcp-install codex --apply
 ```
+
+## Uninstall Without Losing Memories
+
+Run:
+
+```bash
+threadnote uninstall --dry-run
+threadnote uninstall
+```
+
+By default, uninstall removes Threadnote-managed shims, MCP config, launchd config, and user instruction blocks while
+preserving `THREADNOTE_HOME`. To delete local OpenViking data too, pass `--erase-memories`.

package/package.json

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

package/scripts/install.sh

@@ -125,4 +125,8 @@ if ! have threadnote; then
 fi
 
 say ""
-say "Threadnote is installed. Run: threadnote doctor --dry-run"
+say "Threadnote is installed. Next:"
+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"