threadnote 0.2.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,91 +64,13 @@ Or install manually:
 ```bash
 npm install --global threadnote
 threadnote install
-```
-
-For a one-off check before installing globally:
-
-```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
-```
-
-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.
-
-## 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
+threadnote doctor --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.
-
-## Commands
-
-- `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
-  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
-  `seed-skills --native` only after configuring a working VLM provider.
-- `mcp-install codex|claude`: installs or prints OpenViking MCP configuration for Codex or Claude.
-- `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.
-- `read`: reads a `viking://` URI returned by `recall` or `list`.
-- `list` / `ls`: lists a `viking://` directory.
-- `handoff`: stores current git state and next-step notes as a durable handoff.
-- `forget`: removes a `viking://` URI.
-- `export-pack` / `import-pack`: moves local context through `.ovpack` files.
-
-## Configuration
-
-Environment variables:
-
-- `THREADNOTE_HOME`: local state directory, default `~/.openviking`.
-- `THREADNOTE_MANIFEST`: seed manifest path. Defaults to `~/.openviking/seed-manifest.yaml` if present, otherwise
-  the bundled example manifest.
-- `THREADNOTE_ACCOUNT`: OpenViking account header/config value, default `local`.
-- `THREADNOTE_USER`: OpenViking user value, default local username.
-- `THREADNOTE_AGENT_ID`: shared agent identity, default `threadnote`.
-- `THREADNOTE_OPENVIKING_VERSION`: package version to install, default `0.3.12`.
-- `THREADNOTE_BIN_DIR`: directory for the `threadnote` shim, default `~/.local/bin`.
-- `THREADNOTE_HOST`: local bind host, default `127.0.0.1`.
-- `THREADNOTE_PORT`: local bind port, default `1933`.
-
-Local projects using `localhost:80` or `localhost:443` do not conflict with OpenViking on `127.0.0.1:1933`. A conflict
-only occurs when another process already owns the same host and port. If that happens, choose a different
-`THREADNOTE_PORT`.
+### MCP
 
-## 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:
 
@@ -166,47 +112,109 @@ If a future OpenViking build exposes a healthy native endpoint, install it expli
 threadnote mcp-install claude --native-http --apply
 ```
 
-## Uninstall
+### 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.
 
-Preview removal:
+Create or update the local manifest with the repos you care about:
 
 ```bash
-threadnote uninstall --dry-run
+threadnote init-manifest --repo ~/src/my-service --repo ~/work/mobile-app
 ```
 
-Remove Threadnote setup while keeping local OpenViking memories:
+Review what will be imported, then seed curated repo guidance:
 
 ```bash
-threadnote uninstall
+threadnote seed --dry-run
+threadnote seed
 ```
 
-Erase local memories too:
+Optionally seed shared and repo-local skills:
 
 ```bash
-threadnote uninstall --erase-memories
+threadnote seed-skills --dry-run
+threadnote seed-skills
 ```
 
-`uninstall` removes only Threadnote-managed files and agent config. The npm, Bun, or Deno package remains installed;
-remove that with the package manager you used to install it.
+When you add another local repo later, rerun `init-manifest --repo <path>` and seed again.
 
-## Notes
+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
 
-OpenViking itself is not vendored here. This prototype installs and controls a local service and should get legal and
-security review before broader rollout.
+- `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
+  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
+  `seed-skills --native` only after configuring a working VLM provider.
+- `mcp-install codex|claude`: installs or prints OpenViking MCP configuration for Codex or Claude.
+- `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.
+- `read`: reads a `viking://` URI returned by `recall` or `list`.
+- `list` / `ls`: lists a `viking://` directory.
+- `handoff`: stores current git state and next-step notes as a durable handoff.
+- `forget`: removes a `viking://` URI.
+- `export-pack` / `import-pack`: moves local context through `.ovpack` files.
 
-## Publishing
+## Source Checkout
 
-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.
+For local development from this repo:
 
 ```bash
-npm run typecheck
+npm install
 npm run build
-npm pack --dry-run
-npm publish
+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:
+
+- `THREADNOTE_HOME`: local state directory, default `~/.openviking`.
+- `THREADNOTE_MANIFEST`: seed manifest path. Defaults to `~/.openviking/seed-manifest.yaml` if present, otherwise
+  the bundled example manifest.
+- `THREADNOTE_ACCOUNT`: OpenViking account header/config value, default `local`.
+- `THREADNOTE_USER`: OpenViking user value, default local username.
+- `THREADNOTE_AGENT_ID`: shared agent identity, default `threadnote`.
+- `THREADNOTE_OPENVIKING_VERSION`: package version to install, default `0.3.12`.
+- `THREADNOTE_BIN_DIR`: directory for the `threadnote` shim, default `~/.local/bin`.
+- `THREADNOTE_HOST`: local bind host, default `127.0.0.1`.
+- `THREADNOTE_PORT`: local bind port, default `1933`.
+
+Local projects using `localhost:80` or `localhost:443` do not conflict with OpenViking on `127.0.0.1:1933`. A conflict
+only occurs when another process already owns the same host and port. If that happens, choose a different
+`THREADNOTE_PORT`.
+
+## 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

@@ -6131,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 -->";
@@ -6257,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"]));
@@ -6289,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,
@@ -6312,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;
@@ -6436,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)) {
@@ -6445,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_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 {
@@ -6824,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);
@@ -6867,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) {
@@ -6904,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 {
@@ -6913,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"])) {
@@ -7149,11 +7226,20 @@ async function installLaunchAgent(config, dryRun) {
     return;
   }
   await ensureDirectory((0, import_node_path2.dirname)(destination), false);
+  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`);
@@ -7310,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 {
@@ -7813,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) => {

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`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threadnote",
-  "version": "0.2.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"