skillwiki 0.10.107 → 0.10.109

package/dist/{chunk-PGD3J2GE.js → chunk-FYAKMULW.js}

@@ -43,9 +43,25 @@ import {
   vaultIoConcurrency
 } from "./chunk-GJC2CI3W.js";
 
+// src/utils/home.ts
+import { homedir } from "os";
+import { resolve } from "path";
+function resolveSkillwikiHome(home, env = process.env) {
+  for (const candidate of [home, env.HOME, env.USERPROFILE]) {
+    if (candidate?.trim()) return resolve(candidate);
+  }
+  try {
+    const fallback = homedir();
+    if (fallback?.trim()) return resolve(fallback);
+  } catch {
+    throw new Error("Could not resolve SkillWiki home directory");
+  }
+  throw new Error("Could not resolve SkillWiki home directory");
+}
+
 // src/utils/managed-write-preflight.ts
 import { existsSync as existsSync11 } from "fs";
-import { join as join21, resolve as resolve6 } from "path";
+import { join as join21, resolve as resolve7 } from "path";
 
 // src/commands/fleet.ts
 import { readFile as readFile2 } from "fs/promises";
@@ -175,7 +191,7 @@ async function runFleetValidate(input) {
 }
 async function runFleetContext(input) {
   const env = input.env ?? process.env;
-  const home = input.home ?? env.HOME ?? "";
+  const home = resolveSkillwikiHome(input.home, env);
   const cwd = input.cwd ?? process.cwd();
   const osHostname = input.osHostname ?? safeEnvValue(env.HOSTNAME) ?? nodeHostname();
   const user = input.user ?? safeEnvValue(env.USER) ?? safeUserName();
@@ -297,7 +313,7 @@ async function runFleetContext(input) {
 }
 function fleetContextEnv(input) {
   const env = input.env ?? process.env;
-  const home = input.home ?? env.HOME ?? "";
+  const home = resolveSkillwikiHome(input.home, env);
   const osHostname = input.osHostname ?? safeEnvValue(env.HOSTNAME) ?? nodeHostname();
   const vault = input.vault ?? safeEnvValue(env.WIKI_PATH);
   const file = input.file ?? (vault ? join(vault, FLEET_REL_PATH) : void 0);
@@ -2414,7 +2430,7 @@ async function runTopicMapCheck(input) {
 // src/commands/dedup.ts
 import { createHash as createHash3 } from "crypto";
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname3, join as join10, posix, resolve } from "path";
+import { dirname as dirname3, join as join10, posix, resolve as resolve2 } from "path";
 
 // src/utils/rclone.ts
 import { execFile } from "child_process";
@@ -2649,7 +2665,7 @@ async function runDedup(input) {
   const manifest = safeEntries.length > 0 ? {
     version: 1,
     created_at: (/* @__PURE__ */ new Date()).toISOString(),
-    vault: resolve(input.vault),
+    vault: resolve2(input.vault),
     entries: safeEntries
   } : void 0;
   const remoteDeleteCount = safeEntries.reduce((count, entry) => count + entry.duplicates.length, 0);
@@ -2843,11 +2859,11 @@ function readManifest(path) {
   }
 }
 function validateManifestLocalState(vault, manifest) {
-  if (resolve(manifest.vault) !== resolve(vault)) {
+  if (resolve2(manifest.vault) !== resolve2(vault)) {
     return err("APPROVAL_INVALID", {
       message: "dedup manifest belongs to a different vault",
       manifest_vault: manifest.vault,
-      vault: resolve(vault)
+      vault: resolve2(vault)
     });
   }
   for (const entry of manifest.entries) {
@@ -2929,7 +2945,7 @@ async function runRawBodyDedup(vault, scan, pageTextCache) {
 
 // src/commands/audit.ts
 import { readFile as readFile11, stat as stat2 } from "fs/promises";
-import { dirname as dirname4, resolve as resolve2, join as join11 } from "path";
+import { dirname as dirname4, resolve as resolve3, join as join11 } from "path";
 async function runAudit(input) {
   let text;
   try {
@@ -2941,7 +2957,7 @@ async function runAudit(input) {
   if (!fm.ok) return { exitCode: ExitCode.INVALID_FRONTMATTER, result: fm };
   const split = splitFrontmatter(text);
   const body = split.ok ? split.data.body : text;
-  const vault = await findVaultRoot(dirname4(resolve2(input.file)));
+  const vault = await findVaultRoot(dirname4(resolve3(input.file)));
   if (!vault) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID") };
   const markers = extractCitationMarkers(body);
   const resolved = await Promise.all(markers.map(async (m) => {
@@ -3043,7 +3059,7 @@ async function validateCompoundReferences(vault, existingScan, pageTextCache) {
 // src/commands/path-too-long.ts
 import { existsSync as existsSync3 } from "fs";
 import { mkdir as mkdir4, readFile as readFile12, rename as rename3, unlink as unlink2 } from "fs/promises";
-import { dirname as dirname5, join as join12, posix as posix2, resolve as resolve3 } from "path";
+import { dirname as dirname5, join as join12, posix as posix2, resolve as resolve4 } from "path";
 var MAX_PATH_LENGTH = 240;
 var WINDOWS_ABSOLUTE_PATH_LIMIT = 259;
 async function runPathTooLong(input) {
@@ -3136,7 +3152,7 @@ function findPathTooLongViolations(pages, maxLength) {
 }
 function maxFixPathLength(vault) {
   if (process.platform !== "win32") return MAX_PATH_LENGTH;
-  const root = resolve3(vault);
+  const root = resolve4(vault);
   const separatorBudget = root.endsWith("\\") || root.endsWith("/") ? 0 : 1;
   const absoluteSafeRelLength = WINDOWS_ABSOLUTE_PATH_LIMIT - root.length - separatorBudget;
   return Math.max(1, Math.min(MAX_PATH_LENGTH, absoluteSafeRelLength));
@@ -5723,7 +5739,7 @@ function probeRemoteHealth(input) {
 // src/utils/vault-sync-helper.ts
 import { spawnSync } from "child_process";
 import { existsSync as existsSync7 } from "fs";
-import { homedir, platform } from "os";
+import { platform } from "os";
 import { dirname as dirname6, join as join16 } from "path";
 import { fileURLToPath } from "url";
 var HELPER_NAME = "wiki-pull-with-auto-resolve.sh";
@@ -5746,13 +5762,7 @@ function candidateHelperPaths(input = { vault: "" }) {
     paths.push(join16(here, "..", "..", "vault-sync", "scripts", HELPER_NAME));
     paths.push(join16(here, "..", "..", "..", "vault-sync", "scripts", HELPER_NAME));
   }
-  const home = input.home ?? env.HOME ?? env.USERPROFILE ?? (() => {
-    try {
-      return homedir();
-    } catch {
-      return void 0;
-    }
-  })();
+  const home = resolveSkillwikiHome(input.home, env);
   if (home) {
     const xdg = env.XDG_DATA_HOME;
     const isDarwin = platform() === "darwin";
@@ -5942,7 +5952,7 @@ function runSyncStatus(input) {
     output.stashes = stashes;
   }
   if (input.includeRemoteHealth) {
-    const home = input.home ?? process.env.HOME ?? "";
+    const home = resolveSkillwikiHome(input.home);
     const remote_health = probeRemoteHealth({
       vaultPath: vault,
       home,
@@ -6527,7 +6537,7 @@ import {
   writeFileSync as writeFileSync4
 } from "fs";
 import { hostname } from "os";
-import { dirname as dirname7, join as join18, resolve as resolve4 } from "path";
+import { dirname as dirname7, join as join18, resolve as resolve5 } from "path";
 function managedWriteLockPath(vault) {
   const gitPath = git(vault, ["rev-parse", "--git-path", "vault-sync/managed-write.lock"]);
   if (gitPath) return gitPath.startsWith("/") ? gitPath : join18(vault, gitPath);
@@ -6572,7 +6582,7 @@ function hasLocalOwnerProof(vault, record) {
 }
 function reclaimDeadManagedWriteLockOwner(vault, options = {}) {
   const path = managedWriteLockPath(vault);
-  const gitStateVault = resolve4(options.gitStateVault ?? vault);
+  const gitStateVault = resolve5(options.gitStateVault ?? vault);
   if (!existsSync9(path)) return ok({ reclaimed: false });
   const record = readLockRecord(path);
   if (!record) {
@@ -6859,7 +6869,7 @@ function supersedeStaleReviewRequiredJournals(vault, opts = {}) {
 
 // src/utils/snapshot-worktree.ts
 import { readFileSync as readFileSync8 } from "fs";
-import { join as join20, resolve as resolve5 } from "path";
+import { join as join20, resolve as resolve6 } from "path";
 function readSkillWikiConfig(path) {
   try {
     return parseDotenvText(readFileSync8(path, "utf8"));
@@ -6888,12 +6898,12 @@ function resolveConfiguredSnapshotWorktree(home) {
   if (!home) return void 0;
   const config = readSkillWikiConfig(join20(home, ".skillwiki", ".env"));
   const explicit = config["vault_sync.snapshot_worktree"];
-  if (explicit) return resolve5(explicit);
+  if (explicit) return resolve6(explicit);
   const snapshotProfile = config["vault_sync.snapshot_profile"];
   if (!snapshotProfile) return void 0;
-  const profile = readSnapshotProfile(resolve5(snapshotProfile));
+  const profile = readSnapshotProfile(resolve6(snapshotProfile));
   const fromProfile = profile.WIKI_GIT_WORKTREE ?? profile.SNAPSHOT_WORKTREE ?? profile.GIT_DIR;
-  return fromProfile ? resolve5(fromProfile) : void 0;
+  return fromProfile ? resolve6(fromProfile) : void 0;
 }
 
 // src/utils/managed-write-preflight.ts
@@ -6910,7 +6920,7 @@ var DEFAULT_DEPS = {
   converge: (input) => runVaultSyncPullHelper(input),
   resolveConfiguredSnapshotWorktree,
   syncPeers: runSyncPeers,
-  sleepMs: (ms) => new Promise((resolve7) => setTimeout(resolve7, ms)),
+  sleepMs: (ms) => new Promise((resolve8) => setTimeout(resolve8, ms)),
   nowMs: () => Date.now(),
   logHeartbeat: (message) => {
     process.stderr.write(`${message}
@@ -7102,8 +7112,8 @@ function isGitVault(vault) {
   return Boolean(git(vault, ["rev-parse", "--absolute-git-dir"]));
 }
 async function runManagedWritePreflight(input, deps = DEFAULT_DEPS) {
-  const mutationVault = resolve6(input.vault);
-  let convergenceVault = input.convergenceVault && resolve6(input.convergenceVault) !== mutationVault ? resolve6(input.convergenceVault) : void 0;
+  const mutationVault = resolve7(input.vault);
+  let convergenceVault = input.convergenceVault && resolve7(input.convergenceVault) !== mutationVault ? resolve7(input.convergenceVault) : void 0;
   let convergenceSource = convergenceVault ? "explicit" : "single-path";
   const mutationBlocker = preflightBlocker(mutationVault);
   if (mutationBlocker) {
@@ -7181,7 +7191,7 @@ async function runManagedWritePreflight(input, deps = DEFAULT_DEPS) {
     };
   }
   if (!convergenceVault && host.role === "snapshotter" && host.protected === true) {
-    const home = input.home ?? input.env?.HOME ?? process.env.HOME ?? "";
+    const home = resolveSkillwikiHome(input.home, input.env);
     const configured = (deps.resolveConfiguredSnapshotWorktree ?? resolveConfiguredSnapshotWorktree)(home);
     if (!configured) {
       return {
@@ -7193,7 +7203,7 @@ async function runManagedWritePreflight(input, deps = DEFAULT_DEPS) {
         })
       };
     }
-    convergenceVault = resolve6(configured);
+    convergenceVault = resolve7(configured);
     convergenceSource = "configured";
     if (convergenceVault === mutationVault) {
       return {
@@ -7302,9 +7312,9 @@ async function runManagedWritePreflight(input, deps = DEFAULT_DEPS) {
   };
 }
 async function runManagedWriteTransaction(input, deps = DEFAULT_DEPS) {
-  const mutationVault = resolve6(input.vault);
+  const mutationVault = resolve7(input.vault);
   const lock = acquireManagedWriteLock(mutationVault, input.command, {
-    gitStateVault: input.convergenceVault ? resolve6(input.convergenceVault) : mutationVault
+    gitStateVault: input.convergenceVault ? resolve7(input.convergenceVault) : mutationVault
   });
   if (!lock.ok) {
     return { exitCode: ExitCode.SYNC_LOCK_HELD, result: lock };
@@ -7357,6 +7367,7 @@ async function runManagedWriteTransaction(input, deps = DEFAULT_DEPS) {
 }
 
 export {
+  resolveSkillwikiHome,
   readLastOp,
   appendLastOp,
   clearLastOp,

package/dist/{chunk-Z4NCF6K6.js → chunk-LDEZQXH6.js}

@@ -31,6 +31,7 @@ import {
   releaseOwnedSyncLock,
   resolveConfiguredSnapshotWorktree,
   resolveRuntimePath,
+  resolveSkillwikiHome,
   resolveVaultSyncPullHelper,
   resolveWikiS3Remote,
   runLint,
@@ -40,7 +41,7 @@ import {
   snapshotterAliasForLocalHost,
   toUndirectedWeighted,
   writeDotenv
-} from "./chunk-PGD3J2GE.js";
+} from "./chunk-FYAKMULW.js";
 import {
   atomicWriteText,
   prepareTypedPage
@@ -636,7 +637,7 @@ function computeAdamicAdar(adj) {
 import { resolve as resolvePath } from "path";
 async function guardProtectedVaultWrite(input) {
   const env = input.env ?? process.env;
-  const home = input.home ?? process.env.HOME ?? "";
+  const home = resolveSkillwikiHome(input.home, env);
   const cwd = input.cwd ?? process.cwd();
   const liveVaultPath = await resolveLiveVaultPath({ env, home, cwd });
   const load = await loadFleetManifestAndHost({
@@ -1023,7 +1024,7 @@ function displayConfigValue(key, value) {
   return value;
 }
 function configPath(home) {
-  return join5(home, ".skillwiki", ".env");
+  return join5(resolveSkillwikiHome(home), ".skillwiki", ".env");
 }
 async function runConfigGet(input) {
   if (!validateKey(input.key)) {
@@ -1104,7 +1105,7 @@ function mcpAuthFromEnv(env) {
 }
 async function resolveMcpAuthEnv(input) {
   const processAuth = mcpAuthFromEnv(input.env ?? process.env);
-  const dotenv = await parseDotenvFile(join6(input.home, ".skillwiki", ".env"));
+  const dotenv = await parseDotenvFile(join6(resolveSkillwikiHome(input.home, input.env), ".skillwiki", ".env"));
   const fileAuth = mcpAuthFromEnv(dotenv);
   return {
     url: processAuth.url ?? fileAuth.url,
@@ -1398,7 +1399,7 @@ async function checkConfigFile(home) {
   try {
     const map = await parseDotenvFile(cfgPath);
     const keys = Object.keys(map);
-    return check("pass", "config_file", "Config file exists", `Found with keys: ${keys.length > 0 ? keys.join(", ") : "(none set)"}`);
+    return check("pass", "config_file", "Config file exists", `Found ${cfgPath} with keys: ${keys.length > 0 ? keys.join(", ") : "(none set)"}`);
   } catch (e) {
     return check("warn", "config_file", "Config file exists", `Failed to parse ${cfgPath}: ${String(e)}`);
   }
@@ -4255,6 +4256,46 @@ var dsStoreNoiseProbe = {
 // src/doctor/probes/mcp-handshake.ts
 import { existsSync as existsSync17 } from "fs";
 import { join as join21 } from "path";
+
+// src/utils/mcp-client.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+var MCP_PROBE_TIMEOUT_MS = 1e4;
+async function withMcpClient(input, probe) {
+  const controller = new AbortController();
+  const client = new Client({ name: input.clientName, version: input.version });
+  const fetchFn = input.fetchFn ?? globalThis.fetch;
+  const transport = new StreamableHTTPClientTransport(new URL(input.url), {
+    requestInit: { headers: { Authorization: `Bearer ${input.token}` } },
+    fetch: (url, init) => fetchFn(url, {
+      ...init,
+      signal: init?.signal ? AbortSignal.any([init.signal, controller.signal]) : controller.signal
+    })
+  });
+  let timer;
+  const deadline = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => {
+      const error = new Error(`MCP probe timed out after ${MCP_PROBE_TIMEOUT_MS}ms`);
+      reject(error);
+      controller.abort(error);
+    }, MCP_PROBE_TIMEOUT_MS);
+  });
+  try {
+    const work = async () => {
+      await client.connect(transport, { signal: controller.signal, timeout: MCP_PROBE_TIMEOUT_MS });
+      return probe(client, controller.signal);
+    };
+    return await Promise.race([work(), deadline]);
+  } catch (error) {
+    throw new Error(redactMcpSecret(error instanceof Error ? error.message : String(error), input.token));
+  } finally {
+    clearTimeout(timer);
+    controller.abort();
+    await client.close();
+  }
+}
+
+// src/doctor/probes/mcp-handshake.ts
 var DEFAULT_MCP_URL = "https://wiki.karldigi.dev/mcp";
 function mcpEnv(ctx) {
   return ctx.input.env ?? process.env;
@@ -4322,54 +4363,6 @@ function redactSecret(detail, secret) {
 function handshakeRow(status, detail, secret) {
   return check(status, HANDSHAKE_ID, HANDSHAKE_LABEL, redactSecret(detail, secret));
 }
-function parseMcpBody(text) {
-  const trimmed = text.trim();
-  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
-    return JSON.parse(trimmed);
-  }
-  for (const line of trimmed.split(/\r?\n/)) {
-    const prefix = line.startsWith("data:") ? line.slice(5).trim() : "";
-    if (prefix.startsWith("{")) return JSON.parse(prefix);
-  }
-  throw new Error("non-JSON MCP body");
-}
-function jsonRpcResult(body) {
-  if (typeof body !== "object" || body === null) {
-    throw new Error("invalid JSON-RPC body");
-  }
-  const rec = body;
-  if (rec.error) {
-    throw new Error(typeof rec.error.message === "string" ? rec.error.message : "JSON-RPC error");
-  }
-  if (typeof rec.result !== "object" || rec.result === null) {
-    throw new Error("missing JSON-RPC result");
-  }
-  return rec.result;
-}
-async function mcpJsonRpc(fetchFn, url, token, method, id, params, sessionId) {
-  const headers = {
-    Authorization: `Bearer ${token}`,
-    "Content-Type": "application/json",
-    Accept: "application/json, text/event-stream"
-  };
-  if (sessionId) headers["mcp-session-id"] = sessionId;
-  const res = await fetchFn(url, {
-    method: "POST",
-    headers,
-    body: JSON.stringify({ jsonrpc: "2.0", id, method, params })
-  });
-  if (!res.ok) {
-    throw new Error(`HTTP ${res.status}`);
-  }
-  const nextSession = res.headers.get("mcp-session-id") ?? sessionId;
-  const result = jsonRpcResult(parseMcpBody(await res.text()));
-  return { result, sessionId: nextSession ?? void 0 };
-}
-function toolNames(result) {
-  const tools = result.tools;
-  if (!Array.isArray(tools)) return [];
-  return tools.map((t) => typeof t === "object" && t !== null && typeof t.name === "string" ? t.name : "").filter((name) => name.length > 0);
-}
 async function checkMcpHandshake(ctx) {
   if (!ctx.input.checkMcp) {
     return handshakeRow("pass", "not requested \u2014 check skipped");
@@ -4384,33 +4377,16 @@ async function checkMcpHandshake(ctx) {
   const fetchFn = ctx.input.mcpFetch ?? globalThis.fetch;
   const shipped = ctx.input.currentVersion;
   try {
-    const init = await mcpJsonRpc(
-      fetchFn,
-      url,
-      token,
-      "initialize",
-      1,
-      {
-        protocolVersion: "2025-11-25",
-        capabilities: {},
-        clientInfo: { name: "skillwiki-doctor", version: shipped }
-      }
+    const { advertised, tools } = await withMcpClient(
+      { fetchFn, url, token, clientName: "skillwiki-doctor", version: shipped },
+      async (client, signal) => ({
+        advertised: client.getServerVersion()?.version ?? "",
+        tools: (await client.listTools({}, { signal })).tools.map((tool) => tool.name)
+      })
     );
-    const serverInfo = init.result.serverInfo;
-    const advertised = typeof serverInfo === "object" && serverInfo !== null && typeof serverInfo.version === "string" ? serverInfo.version : "";
     if (!advertised) {
       return handshakeRow("error", "handshake failed \u2014 missing serverInfo.version", token);
     }
-    const listed = await mcpJsonRpc(
-      fetchFn,
-      url,
-      token,
-      "tools/list",
-      2,
-      {},
-      init.sessionId
-    );
-    const tools = toolNames(listed.result);
     const frozen = Boolean(ctx.resolvedPath && existsSync17(join21(ctx.resolvedPath, ".WIKI_GIT_FROZEN")));
     if (frozen && !tools.includes(WORKITEM_TOOL)) {
       return handshakeRow(
@@ -4482,6 +4458,7 @@ var DoctorRunner = class {
     return this.probes;
   }
   async run(input) {
+    input = { ...input, home: resolveSkillwikiHome(input.home, input.env) };
     const devSourceRun = isDevSourceRun(input.argv);
     const vsConfig = readVaultSyncConfig(input.home);
     const baseEnv = input.env ?? process.env;
@@ -6894,7 +6871,7 @@ function getVaultAllowlistFromEnv() {
 
 // src/mcp/vault-resolve.ts
 async function resolveMcpVault(input) {
-  const home = input.home ?? process.env.HOME ?? "";
+  const home = resolveSkillwikiHome(input.home);
   let vaultPath;
   let source = "resolved";
   if (input.vault !== void 0 && input.vault.length > 0) {
@@ -6943,7 +6920,6 @@ function formatToolResult(payload) {
 
 // src/mcp/audit-log.ts
 import { appendFileSync, mkdirSync as mkdirSync2 } from "fs";
-import { homedir } from "os";
 import { join as join28 } from "path";
 function auditEnabled() {
   const v = process.env.SKILLWIKI_MCP_AUDIT;
@@ -6956,7 +6932,7 @@ function auditSink() {
 function auditFilePath() {
   const custom = process.env.SKILLWIKI_MCP_AUDIT_FILE;
   if (custom && custom.length > 0) return custom;
-  return join28(homedir(), ".skillwiki", "mcp-audit.jsonl");
+  return join28(resolveSkillwikiHome(), ".skillwiki", "mcp-audit.jsonl");
 }
 function auditMcpToolCall(entry) {
   if (!auditEnabled()) return;
@@ -7059,7 +7035,7 @@ function registerMcpTools(server) {
       await resolveMcpVault({ vault, wiki });
       const pkg = readCliPackageJson();
       const r = await runDoctor({
-        home: process.env.HOME ?? "",
+        home: resolveSkillwikiHome(),
         envValue: process.env.WIKI_PATH,
         argv: process.argv,
         currentVersion: pkg.version,
@@ -7132,7 +7108,7 @@ function registerMcpTools(server) {
       })
     },
     async ({ key }) => runMcpToolHandler("skillwiki.config_get", {}, async () => {
-      const r = await runConfigGet({ key, home: process.env.HOME ?? "" });
+      const r = await runConfigGet({ key, home: resolveSkillwikiHome() });
       return formatToolResult(r);
     })
   );
@@ -7955,6 +7931,7 @@ export {
   MCP_TOKEN_ENV,
   MCP_HOST_ID_ENV,
   nonEmptyEnvValue,
+  mcpAuthFromEnv,
   mergeMcpAuthIntoEnv,
   redactMcpSecret,
   configPath,
@@ -7972,6 +7949,7 @@ export {
   readSatelliteLatestRunFromText,
   readSatelliteLatestRunAt,
   evaluateSatelliteRunHealthState,
+  withMcpClient,
   DEFAULT_MCP_URL,
   runDoctor,
   readCliPackageJson,

package/dist/cli.js

@@ -21,6 +21,7 @@ import {
   guardProtectedVaultWrite,
   isEventLedgerPath,
   isFailedRunStatus,
+  mcpAuthFromEnv,
   measureDirtyVolume,
   memoryAuthorityTiersRank,
   mergeMcpAuthIntoEnv,
@@ -62,8 +63,9 @@ import {
   scanConflictMarkerBlocksInText,
   snapshotterHealthChecks,
   upsertIndexEntry,
-  vectorIndexStatus
-} from "./chunk-Z4NCF6K6.js";
+  vectorIndexStatus,
+  withMcpClient
+} from "./chunk-LDEZQXH6.js";
 import {
   normalizeDistTag,
   readCache,
@@ -133,6 +135,7 @@ import {
   resolveFleetHostId,
   resolveInitTimePath,
   resolveRuntimePath,
+  resolveSkillwikiHome,
   resolveWikiS3Remote,
   rewriteRawSourceReferences,
   runAudit,
@@ -168,7 +171,7 @@ import {
   supersedeStaleReviewRequiredJournals,
   taxonomyCommentForPage,
   writeDotenv
-} from "./chunk-PGD3J2GE.js";
+} from "./chunk-FYAKMULW.js";
 import {
   assertTargetInsideVault,
   atomicWriteText,
@@ -3671,6 +3674,7 @@ ${formatHostRow(normalizedHash, hostId, granted.vaults)}` };
 }
 
 // src/commands/connect.ts
+import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
 var CONNECT_DESCRIPTION = "HTTP MCP leaf connect: ingest a chat-attached env file into ~/.skillwiki/.env (mode 0600). Never runs skillwiki init. Cloud Drive / \u4E91\u76D8 is unsupported.";
 var RESERVED_HOST_IDS = ["msi", "doubao-linux-agent", "macos-dev"];
 var DEST_MODE = 384;
@@ -3712,44 +3716,16 @@ function redactConnectPayload(data, secret) {
   };
 }
 async function readWikiStatus(fetchFn, url, token) {
-  const headers = {
-    Authorization: `Bearer ${token}`,
-    "Content-Type": "application/json",
-    Accept: "application/json, text/event-stream"
-  };
   try {
-    const initRes = await fetchFn(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({
-        jsonrpc: "2.0",
-        id: 1,
-        method: "initialize",
-        params: {
-          protocolVersion: "2025-11-25",
-          capabilities: {},
-          clientInfo: { name: "skillwiki-connect", version: "0" }
-        }
-      })
-    });
-    const session = initRes.headers.get("mcp-session-id");
-    if (session) headers["mcp-session-id"] = session;
-    const statusRes = await fetchFn(url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({
-        jsonrpc: "2.0",
-        id: 2,
-        method: "tools/call",
-        params: { name: "wiki_status", arguments: {} }
-      })
-    });
-    const raw = await statusRes.text();
-    const parsed = JSON.parse(raw.startsWith("data:") ? raw.replace(/^data:\s*/m, "") : raw);
-    const structured = parsed.result?.structuredContent;
-    let body = structured;
+    const result = await withMcpClient(
+      { fetchFn, url, token, clientName: "skillwiki-connect", version: "0" },
+      async (client, signal) => CallToolResultSchema.parse(await client.callTool({ name: "wiki_status", arguments: {} }, void 0, { signal }))
+    );
+    if (result.isError) return { writer_id: null, ok: null, reconcile_ready: null, error: "wiki_status returned a tool error" };
+    let body = result.structuredContent;
     if (!body) {
-      const text = parsed.result?.content?.find((c) => typeof c.text === "string")?.text;
+      const content = result.content.find((item) => item.type === "text");
+      const text = content?.type === "text" ? content.text : void 0;
       if (text) {
         try {
           body = JSON.parse(text);
@@ -3758,17 +3734,26 @@ async function readWikiStatus(fetchFn, url, token) {
         }
       }
     }
-    if (!body) return { writer_id: null, ok: null, reconcile_ready: null };
+    if (!body || typeof body !== "object" || Array.isArray(body) || typeof body.ok !== "boolean" || typeof body.reconcile_ready !== "boolean" || body.writer_id !== void 0 && typeof body.writer_id !== "string") {
+      return { writer_id: null, ok: null, reconcile_ready: null, error: "wiki_status returned an invalid status object" };
+    }
+    if (!body.ok) return { writer_id: null, ok: false, reconcile_ready: body.reconcile_ready, error: "wiki_status reported failure" };
     return {
-      writer_id: typeof body.writer_id === "string" ? body.writer_id : null,
-      ok: typeof body.ok === "boolean" ? body.ok : null,
-      reconcile_ready: typeof body.reconcile_ready === "boolean" ? body.reconcile_ready : null
+      writer_id: body.writer_id ?? null,
+      ok: body.ok,
+      reconcile_ready: body.reconcile_ready
+    };
+  } catch (error) {
+    return {
+      writer_id: null,
+      ok: null,
+      reconcile_ready: null,
+      error: redactMcpSecret(error instanceof Error ? error.message : String(error), token)
     };
-  } catch {
-    return { writer_id: null, ok: null, reconcile_ready: null };
   }
 }
 async function runConnect(input) {
+  input = { ...input, home: resolveSkillwikiHome(input.home, input.env) };
   const dest = join18(input.home, ".skillwiki", ".env");
   const fromFile = input.fromFile?.trim();
   const fromStdin = Boolean(input.fromStdin);
@@ -3878,8 +3863,13 @@ async function runConnect(input) {
     if (doctor.result.ok) {
       handshake = doctor.result.data.checks.find((c) => c.id === "mcp_handshake")?.detail ?? null;
     }
-    const url = incomingUrl ?? DEFAULT_MCP_URL;
-    const status = await readWikiStatus(input.mcpFetch ?? globalThis.fetch, url, incomingToken);
+    const auth = mcpAuthFromEnv(env);
+    const url = auth.url ?? DEFAULT_MCP_URL;
+    const status = await readWikiStatus(input.mcpFetch ?? globalThis.fetch, url, auth.token ?? incomingToken);
+    if (status.error) {
+      doctorExit = ExitCode.DOCTOR_HAS_ERRORS;
+      handshake = `${handshake ?? ""}; wiki_status verification failed \u2014 ${status.error}`;
+    }
     writerId = status.writer_id;
     statusOk = status.ok;
     reconcileReady = status.reconcile_ready;
@@ -6119,7 +6109,6 @@ import {
   unlinkSync,
   writeFileSync as writeFileSync5
 } from "fs";
-import { homedir } from "os";
 import { dirname as dirname6, join as join28 } from "path";
 var PUBLICATION_JOURNAL_SCHEMA = "skillwiki-publication-operation-v1";
 var PHASE_ORDER2 = [
@@ -6148,10 +6137,10 @@ function vaultIdentity(vaultPath) {
   }
   return sha256Hex(real).slice(0, 16);
 }
-function publicationJournalRoot(home = process.env.HOME || homedir()) {
-  return join28(home, ".skillwiki", "publication-operations");
+function publicationJournalRoot(home = resolveSkillwikiHome()) {
+  return join28(resolveSkillwikiHome(home), ".skillwiki", "publication-operations");
 }
-function resolveJournalPaths(vaultPath, operationId2, home = process.env.HOME || homedir()) {
+function resolveJournalPaths(vaultPath, operationId2, home = resolveSkillwikiHome()) {
   const identity = vaultIdentity(vaultPath);
   const rootDir = publicationJournalRoot(home);
   const vaultDir = join28(rootDir, identity);
@@ -6261,7 +6250,7 @@ function buildIdentitySummary(input) {
     prior_target_sha256: input.prior_target_sha256
   };
 }
-function readPublicationJournal(vaultPath, operationId2, home = process.env.HOME || homedir()) {
+function readPublicationJournal(vaultPath, operationId2, home = resolveSkillwikiHome()) {
   const { journalPath: journalPath2 } = resolveJournalPaths(vaultPath, operationId2, home);
   if (!existsSync10(journalPath2)) return ok(null);
   let text;
@@ -6279,7 +6268,7 @@ function readPublicationJournal(vaultPath, operationId2, home = process.env.HOME
   return validateRecord(parsed);
 }
 function createPublicationJournal(input) {
-  const home = input.home ?? process.env.HOME ?? homedir();
+  const home = resolveSkillwikiHome(input.home);
   const paths = resolveJournalPaths(input.vaultPath, input.operationId, home);
   if (existsSync10(paths.journalPath)) {
     return err("WRITE_FAILED", { message: "journal already exists", path: paths.journalPath });
@@ -6306,7 +6295,7 @@ function createPublicationJournal(input) {
   return ok(record);
 }
 function advancePublicationJournal(input) {
-  const home = input.home ?? process.env.HOME ?? homedir();
+  const home = resolveSkillwikiHome(input.home);
   const existing = readPublicationJournal(input.vaultPath, input.operationId, home);
   if (!existing.ok) return existing;
   if (!existing.data) {
@@ -6351,7 +6340,7 @@ function advancePublicationJournal(input) {
   }
   return ok(record);
 }
-function deletePublicationJournal(vaultPath, operationId2, home = process.env.HOME || homedir()) {
+function deletePublicationJournal(vaultPath, operationId2, home = resolveSkillwikiHome()) {
   const { journalPath: journalPath2 } = resolveJournalPaths(vaultPath, operationId2, home);
   if (!existsSync10(journalPath2)) return ok({ deleted: false });
   try {
@@ -6372,7 +6361,7 @@ function completePublicationJournal(input) {
   const deleted = deletePublicationJournal(
     input.vaultPath,
     input.operationId,
-    input.home ?? process.env.HOME ?? homedir()
+    resolveSkillwikiHome(input.home)
   );
   if (!deleted.ok) return deleted;
   return ok({ completed: true });
@@ -8898,7 +8887,7 @@ function refusalErr(code, reason, guidance) {
 }
 async function runSnapshotMaintenanceDryRun(input) {
   const env = input.env ?? process.env;
-  const home = input.home ?? env.HOME ?? "";
+  const home = resolveSkillwikiHome(input.home, env);
   const audit = input.auditSink ?? defaultAuditSink(home);
   const now = input.now ?? Date.now();
   const liveVaultPath = input.liveVaultPath ? canonicalize(input.liveVaultPath) : await resolveLiveVault({ env, home });
@@ -9039,7 +9028,7 @@ function makeAuditEvent(input, hostId, now, result, errorCode, approvalId, comma
 }
 async function runSnapshotMaintenanceExecute(input) {
   const env = input.env ?? process.env;
-  const home = input.home ?? env.HOME ?? "";
+  const home = resolveSkillwikiHome(input.home, env);
   const audit = input.auditSink ?? defaultAuditSink(home);
   const now = input.now ?? Date.now();
   const isTty = input.isTty ?? !!process.stdin.isTTY;
@@ -9174,7 +9163,7 @@ function extraUnmergedPaths(unmerged) {
 }
 async function authorizeRepairContext(input) {
   const env = input.env ?? process.env;
-  const home = input.home ?? env.HOME ?? "";
+  const home = resolveSkillwikiHome(input.home, env);
   const audit = input.auditSink ?? defaultAuditSink(home);
   const now = input.now ?? Date.now();
   const liveVaultPath = input.liveVaultPath ? canonicalize(input.liveVaultPath) : await resolveLiveVault({ env, home });
@@ -9238,7 +9227,7 @@ async function authorizeRepairContext(input) {
 }
 async function runProjectionConflictRepairDryRun(input) {
   const env = input.env ?? process.env;
-  const home = input.home ?? env.HOME ?? "";
+  const home = resolveSkillwikiHome(input.home, env);
   const audit = input.auditSink ?? defaultAuditSink(home);
   const now = input.now ?? Date.now();
   const ctx = await authorizeRepairContext(input);
@@ -9341,7 +9330,7 @@ async function performProjectionRepair(input, plan, audit, now) {
 }
 async function runProjectionConflictRepairExecute(input) {
   const env = input.env ?? process.env;
-  const home = input.home ?? env.HOME ?? "";
+  const home = resolveSkillwikiHome(input.home, env);
   const audit = input.auditSink ?? defaultAuditSink(home);
   const now = input.now ?? Date.now();
   const isTty = input.isTty ?? !!process.stdin.isTTY;
@@ -10869,7 +10858,7 @@ function rowHealthy(reachable, timer, runUnhealthy, timerBad, platform3) {
 async function runFleetHealth(input) {
   const deps = input.deps ?? defaultDeps3();
   const env = input.env ?? process.env;
-  const home = input.home ?? env.HOME ?? "";
+  const home = resolveSkillwikiHome(input.home, env);
   const osHostname = input.osHostname ?? env.HOSTNAME ?? nodeHostname();
   const vault = input.vault ?? env.WIKI_PATH;
   const file = input.file ?? (vault ? join43(vault, FLEET_REL_PATH) : void 0);
@@ -10974,7 +10963,7 @@ function isValidLastOpPath(file) {
 }
 async function postCommit(vault, exitCode) {
   if (exitCode !== 0) return;
-  const home = process.env.HOME ?? "";
+  const home = resolveSkillwikiHome();
   const dotenv = await parseDotenvFile(configPath(home));
   const autoCommit = process.env.AUTO_COMMIT ?? dotenv["AUTO_COMMIT"];
   if (autoCommit === "false") return;
@@ -11192,7 +11181,7 @@ async function emitGuardedVaultWrite(vault, command, run, opts) {
     vault,
     command,
     env: process.env,
-    home: process.env.HOME ?? "",
+    home: resolveSkillwikiHome(),
     cwd: process.cwd(),
     osHostname: process.env.HOSTNAME,
     user: process.env.USER
@@ -11211,7 +11200,7 @@ async function emitManagedVaultWrite(vault, command, mutate, opts) {
     vault,
     command,
     env: process.env,
-    home: process.env.HOME ?? "",
+    home: resolveSkillwikiHome(),
     cwd: process.cwd(),
     osHostname: process.env.HOSTNAME,
     user: process.env.USER
@@ -11223,14 +11212,14 @@ async function emitManagedVaultWrite(vault, command, mutate, opts) {
   if (dirty) {
     return emit(dirty, void 0, { postCommit: false });
   }
-  const { runManagedWriteTransaction: runManagedWriteTransaction2 } = await import("./managed-write-preflight-AYD3CJYD.js");
+  const { runManagedWriteTransaction: runManagedWriteTransaction2 } = await import("./managed-write-preflight-MAIGWFQJ.js");
   const run = await runManagedWriteTransaction2({
     vault,
     command,
     allowImmutableRecord: opts?.allowImmutableRecord === true,
     convergenceVault: opts?.convergenceVault,
     env: process.env,
-    home: process.env.HOME ?? "",
+    home: resolveSkillwikiHome(),
     cwd: process.cwd(),
     osHostname: process.env.HOSTNAME,
     user: process.env.USER,
@@ -11476,14 +11465,14 @@ sourcesCmd.command("dispose <raw-path> [vault]").description("permanently delete
 program.command("orphans [vault]").description("find pages not referenced by any other page").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => emit(await runOrphans({
   vault,
   envValue: process.env.WIKI_PATH,
-  home: process.env.HOME ?? "",
+  home: resolveSkillwikiHome(),
   wiki: opts.wiki,
   cwd: process.cwd()
 })));
 program.command("audit <file>").description("audit citation markers and source provenance for a vault page").action(async (file) => emit(await runAudit({ file })));
-program.command("install").description("install skillwiki SKILL.md files into ~/.claude/skills/").option("--target <dir>", "target install directory", `${process.env.HOME ?? ""}/.claude/skills/`).option("--dry-run", "preview only", false).option("--skills-root <dir>", "source skills directory (defaults to packaged)").option("--symlink", "create symlinks instead of copies (dev mode \u2014 edits to source are immediately visible)", false).option("--force", "install CLI copies even when the skillwiki@llm-wiki plugin channel is active", false).action(async (opts) => {
+program.command("install").description("install skillwiki SKILL.md files into ~/.claude/skills/").option("--target <dir>", "target install directory", `${resolveSkillwikiHome()}/.claude/skills/`).option("--dry-run", "preview only", false).option("--skills-root <dir>", "source skills directory (defaults to packaged)").option("--symlink", "create symlinks instead of copies (dev mode \u2014 edits to source are immediately visible)", false).option("--force", "install CLI copies even when the skillwiki@llm-wiki plugin channel is active", false).action(async (opts) => {
   const skillsRoot = opts.skillsRoot ?? new URL("../skills/", import.meta.url).pathname;
-  emit(await runInstall({ skillsRoot, target: opts.target, dryRun: !!opts.dryRun, symlink: !!opts.symlink, home: process.env.HOME ?? "", force: !!opts.force }));
+  emit(await runInstall({ skillsRoot, target: opts.target, dryRun: !!opts.dryRun, symlink: !!opts.symlink, home: resolveSkillwikiHome(), force: !!opts.force }));
 });
 program.command("path").description("show the resolved vault path").option("--vault <dir>", "explicit vault override (runtime)").option("--target <dir>", "explicit target override (init-time)").option("--wiki <name>", "wiki profile name").option("--init-time", "use init-time chain instead of runtime", false).option("--explain", "include resolution chain in output", false).option("--plain", "print only the vault path (no JSON wrapper)", false).action(async (opts) => {
   const initTime = !!opts.initTime;
@@ -11491,7 +11480,7 @@ program.command("path").description("show the resolved vault path").option("--va
   const r = await runPath({
     flag,
     envValue: process.env.WIKI_PATH,
-    home: process.env.HOME ?? "",
+    home: resolveSkillwikiHome(),
     initTime,
     wiki: opts.wiki,
     cwd: process.cwd(),
@@ -11509,7 +11498,7 @@ program.command("lang").description("get or set the vault language").option("--l
   emit(await runLang({
     flag: opts.lang,
     envValue: process.env.WIKI_LANG,
-    home: process.env.HOME ?? "",
+    home: resolveSkillwikiHome(),
     explain: !!opts.explain
   }));
 });
@@ -11519,7 +11508,7 @@ program.command("init").description("bootstrap a new vault with SCHEMA.md, index
   emit(await runInit({
     flag: opts.target,
     envValue: process.env.WIKI_PATH,
-    home: process.env.HOME ?? "",
+    home: resolveSkillwikiHome(),
     templates,
     domain: opts.domain,
     taxonomy,
@@ -11537,7 +11526,7 @@ async function resolveVaultArg(arg, wiki) {
     flag: void 0,
     envValue: process.env.WIKI_PATH,
     wikiEnv: process.env.WIKI,
-    home: process.env.HOME ?? "",
+    home: resolveSkillwikiHome(),
     wiki,
     cwd: process.cwd()
   });
@@ -11841,7 +11830,7 @@ program.command("health [vault]").description("bounded whole-system wiki health
   else emit(await runHealth({
     vault: v.vault,
     vaultSource: vault ? "flag" : "resolved",
-    home: process.env.HOME ?? "",
+    home: resolveSkillwikiHome(),
     envValue: process.env.WIKI_PATH,
     argv: process.argv,
     currentVersion: pkg.version,
@@ -11853,12 +11842,12 @@ program.command("health [vault]").description("bounded whole-system wiki health
   }), void 0, { postCommit: false, humanDetailHints: healthLintDetailHints });
 });
 var configCmd = program.command("config").description("manage skillwiki configuration");
-configCmd.command("get <key>").description("print the value of a config key").action(async (key) => emit(await runConfigGet({ key, home: process.env.HOME ?? "" })));
-configCmd.command("set <key> <value>").description("set a config key value").action(async (key, value) => emit(await runConfigSet({ key, value, home: process.env.HOME ?? "" })));
-configCmd.command("list").option("--profiles", "show wiki profiles summary", false).description("list all config key=value pairs").action(async (opts) => emit(await runConfigList({ home: process.env.HOME ?? "", profiles: !!opts.profiles })));
-configCmd.command("path").description("print the config file path").action(async () => emit(await runConfigPath({ home: process.env.HOME ?? "" })));
+configCmd.command("get <key>").description("print the value of a config key").action(async (key) => emit(await runConfigGet({ key, home: resolveSkillwikiHome() })));
+configCmd.command("set <key> <value>").description("set a config key value").action(async (key, value) => emit(await runConfigSet({ key, value, home: resolveSkillwikiHome() })));
+configCmd.command("list").option("--profiles", "show wiki profiles summary", false).description("list all config key=value pairs").action(async (opts) => emit(await runConfigList({ home: resolveSkillwikiHome(), profiles: !!opts.profiles })));
+configCmd.command("path").description("print the config file path").action(async () => emit(await runConfigPath({ home: resolveSkillwikiHome() })));
 program.command("doctor").description("diagnose skillwiki setup issues").option("--check-snapshotter", "SSH-probe fleet snapshotter (short timeout)", false).option("--check-mcp", "live-handshake HTTP MCP initialize + tools/list (network)", false).action(async (opts) => emit(await runDoctor({
-  home: process.env.HOME ?? "",
+  home: resolveSkillwikiHome(),
   envValue: process.env.WIKI_PATH,
   argv: process.argv,
   currentVersion: pkg.version,
@@ -11868,7 +11857,7 @@ program.command("doctor").description("diagnose skillwiki setup issues").option(
   env: process.env
 })));
 program.command("connect").description(CONNECT_DESCRIPTION).option("--from-file <path>", "chat-attached env file (not Drive / \u4E91\u76D8)").option("--from-stdin", "read env file from stdin (no echo)").option("--dry-run", "validate without writing ~/.skillwiki/.env").option("--force", "overwrite a different existing token").action(async (opts) => emit(await runConnect({
-  home: process.env.HOME ?? "",
+  home: resolveSkillwikiHome(),
   fromFile: opts.fromFile,
   fromStdin: !!opts.fromStdin,
   dryRun: !!opts.dryRun,
@@ -11882,7 +11871,7 @@ program.command("status [vault]").description("output vault diagnostics").option
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else emit(await runStatus({
     vault: v.vault,
-    home: process.env.HOME ?? "",
+    home: resolveSkillwikiHome(),
     langEnvValue: process.env.WIKI_LANG
   }), v.vault);
 });
@@ -11891,7 +11880,7 @@ program.command("copy-status [vault]").description("plane-tagged vault freshness
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else emit(await runCopyStatusCommand({
     vault: v.vault,
-    home: process.env.HOME ?? ""
+    home: resolveSkillwikiHome()
   }), v.vault, { postCommit: false });
 });
 program.command("archive <page> [vault]").description("archive a typed-knowledge or raw page").option("--wiki <name>", "wiki profile name").option("--cascade", "scan vault for references (wikilinks + sources arrays); preview by default", false).option("--apply", "with --cascade: mutate sources arrays and archive (without --apply, --cascade is preview-only)", false).option("--approve <token>", "approve an exact state-bound raw archive plan").option("--remote <remote>", "rclone remote root to prune the archived source path, for example seaweed-wiki:cloud/wiki").option("--remote-delete", "delete the archived source path from the remote after local archive", false).option("--max-remote-deletes <n>", "maximum remote object deletes allowed", "1").action(async (page, vault, opts) => {
@@ -11998,11 +11987,11 @@ program.command("frontmatter-fix [vault]").description("fix common frontmatter i
   );
 });
 program.command("update").description("update skillwiki CLI from npm dist-tag").option("--tag <tag>", "npm dist-tag", "latest").action(async (opts) => emit(await runUpdate({
-  home: process.env.HOME ?? "",
+  home: resolveSkillwikiHome(),
   distTag: opts.tag
 })));
 program.command("self-update").description("update skillwiki CLI from local source or npm dist-tag").option("--check", "check for updates without installing", false).option("--tag <tag>", "npm dist-tag", "latest").action(async (opts) => emit(await runSelfUpdate({
-  home: process.env.HOME ?? "",
+  home: resolveSkillwikiHome(),
   check: !!opts.check,
   distTag: opts.tag
 })));
@@ -12071,7 +12060,7 @@ syncCmd.command("status [vault]").description("check vault git sync status").opt
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else {
-    const home = process.env.HOME ?? "";
+    const home = resolveSkillwikiHome();
     let snapshotterAlias;
     if (opts.checkSnapshotter) {
       const fleetLoad = await loadFleetManifestAndHost({
@@ -12205,7 +12194,7 @@ backupCmd.command("sync [vault]").description("sync vault to S3-compatible remot
     emit({ exitCode: v.exitCode, result: v.payload });
     return;
   }
-  const home = process.env.HOME ?? process.env.USERPROFILE ?? "/tmp";
+  const home = resolveSkillwikiHome();
   const dotenv = await parseDotenvFile(configPath(home));
   emit(await runBackupSync({
     vault: v.vault,
@@ -12224,7 +12213,7 @@ backupCmd.command("restore [vault]").description("restore vault from S3-compatib
     emit({ exitCode: v.exitCode, result: v.payload });
     return;
   }
-  const home = process.env.HOME ?? process.env.USERPROFILE ?? "/tmp";
+  const home = resolveSkillwikiHome();
   const dotenv = await parseDotenvFile(configPath(home));
   return emitGuardedVaultWrite(
     v.vault,
@@ -12403,7 +12392,7 @@ fleetCmd.command("context [vault]").description("render compact Runtime Host Con
     file: opts.file,
     hostId: opts.hostId,
     env: process.env,
-    home: process.env.HOME ?? "",
+    home: resolveSkillwikiHome(),
     cwd: process.cwd(),
     osHostname: process.env.HOSTNAME,
     user: process.env.USER
@@ -12416,7 +12405,7 @@ fleetCmd.command("health [vault]").description("read-only health probe for skill
     hostId: opts.hostId,
     json: !!opts.json,
     env: process.env,
-    home: process.env.HOME ?? "",
+    home: resolveSkillwikiHome(),
     cwd: process.cwd(),
     osHostname: process.env.HOSTNAME,
     user: process.env.USER
@@ -12481,10 +12470,10 @@ mcpAuthCmd.command("issue-host").description("append a host-id hash to the metal
     allowedVaults
   }));
 });
-for (const w of getDeprecatedWarnings(process.env.HOME ?? "")) {
+for (const w of getDeprecatedWarnings(resolveSkillwikiHome())) {
   process.stderr.write(w + "\n");
 }
-triggerAutoUpdate(process.env.HOME ?? "", pkg.version);
+triggerAutoUpdate(resolveSkillwikiHome(), pkg.version);
 program.parseAsync(process.argv).catch((e) => {
   process.stdout.write(JSON.stringify({ ok: false, error: "INTERNAL", detail: { message: String(e) } }) + "\n");
   process.exit(ExitCode.INTERNAL_ERROR);

package/dist/{managed-write-preflight-AYD3CJYD.js → managed-write-preflight-MAIGWFQJ.js}

@@ -6,7 +6,7 @@ import {
   runManagedWritePeerGate,
   runManagedWritePreflight,
   runManagedWriteTransaction
-} from "./chunk-PGD3J2GE.js";
+} from "./chunk-FYAKMULW.js";
 import "./chunk-HMHMCPCE.js";
 import "./chunk-JCDAEZVD.js";
 import "./chunk-GJC2CI3W.js";

package/dist/skillwiki-mcp.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   runSkillwikiMcpStdio
-} from "./chunk-Z4NCF6K6.js";
+} from "./chunk-LDEZQXH6.js";
 import "./chunk-7I2TPIV5.js";
 import "./chunk-DTTKCCQ4.js";
-import "./chunk-PGD3J2GE.js";
+import "./chunk-FYAKMULW.js";
 import "./chunk-HMHMCPCE.js";
 import "./chunk-QU2IXZRN.js";
 import "./chunk-JCDAEZVD.js";

package/dist/vault-sync/scripts/wiki-snapshot.sh

@@ -1067,28 +1067,33 @@ snapshot_post_sync_log_append_race_detected() {
 # delete-intent reconciliation, re-read the current store, and re-run the
 # existing exact worktree parity and semantic preview gates. Returns 0 only when
 # the recovery converged; the caller refuses (without a second retry) otherwise.
-snapshot_retry_sync_after_log_append_race() {
+# reason is log-append (store log is a strict prefix extension) or
+# semantic-preview (worktree matches store but preview reports index/log drift).
+snapshot_retry_sync_after_projection_race() {
     local context="${1:-post-sync}"
+    local reason="${2:-log-append}"
     if ! rclone sync "$CLOUD_REMOTE" "$SNAPSHOT_WORKTREE" "${RCLONE_OPTS[@]}" --stats 10s 2>&1 | tee "$RCLONE_LOG"; then
-        log "ERROR: $context log-append race retry rclone sync failed"
+        log "ERROR: $context $reason race retry rclone sync failed"
         tail -50 "$RCLONE_LOG" >> "$LOG_FILE" 2>/dev/null || true
         rm -f "$RCLONE_LOG"
         return 1
     fi
     rm -f "$RCLONE_LOG"
-    log "post-sync log-append race detected; performed one additional rclone sync context=$context"
+    log "post-sync $reason race detected; performed one additional rclone sync context=$context"
     if ! snapshot_reconcile_delete_intents; then
-        log "ERROR: $context log-append race retry delete-intent reconciliation failed"
+        log "ERROR: $context $reason race retry delete-intent reconciliation failed"
         return 1
     fi
     snapshot_gate_projection_candidate \
-        "FAIL $context log-append race retry projection expectation refresh; snapshot promotion refused" \
-        "FAIL $context log-append race retry projection candidate verification; snapshot promotion refused"
+        "FAIL $context $reason race retry projection expectation refresh; snapshot promotion refused" \
+        "FAIL $context $reason race retry projection candidate verification; snapshot promotion refused"
 }
 
-# Post-sync projection gate with at most one log-append-race recovery.
-# A first failure that is not the recoverable log-append shape (or that does not
-# converge after the single retry) is logged as the terminal refusal.
+# Post-sync projection gate with at most one recoverable-race re-sync.
+# Recoverable shapes are a store-ahead log append, or exact worktree==store
+# byte parity whose semantic preview still reports index/log drift (a late
+# typed page whose matching index.md has not landed yet). Any other mismatch,
+# or a retry that does not converge, is the terminal refusal.
 snapshot_gate_projection_candidate_with_race_retry() {
     local context="${1:-post-sync}"
     local refresh_fail="$2"
@@ -1097,14 +1102,17 @@ snapshot_gate_projection_candidate_with_race_retry() {
         log "$refresh_fail"
         return 1
     fi
-    # Exact byte parity is the ordinary path. Its semantic preview is terminal:
-    # a later append must not turn a preview failure into a retry.
     if [ -z "$PROJECTION_STATE_DIR" ] \
         || { cmp -s "$PROJECTION_STATE_DIR/expected-index.md" "$SNAPSHOT_WORKTREE/index.md" \
             && cmp -s "$PROJECTION_STATE_DIR/expected-log.md" "$SNAPSHOT_WORKTREE/log.md"; }; then
         if snapshot_verify_projection_candidate; then
             return 0
         fi
+        # Exact byte parity with a drifting preview is the page-vs-index race:
+        # retry once. A later append must not get a second retry after this.
+        if snapshot_retry_sync_after_projection_race "$context" "semantic-preview"; then
+            return 0
+        fi
         log "$verify_fail"
         return 1
     fi
@@ -1113,7 +1121,7 @@ snapshot_gate_projection_candidate_with_race_retry() {
         log "$verify_fail"
         return 1
     fi
-    if snapshot_retry_sync_after_log_append_race "$context"; then
+    if snapshot_retry_sync_after_projection_race "$context" "log-append"; then
         return 0
     fi
     log "$verify_fail"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.107",
+  "version": "0.10.109",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js",

package/skills/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.107",
+  "version": "0.10.109",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 22 prompt-only skills (wiki-*, proj-*, using-skillwiki, skillwiki-mcp, skillwiki-connect) backed by the deterministic `skillwiki` CLI.",
   "author": {

package/skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.107",
+  "version": "0.10.109",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 22 prompt-only skills backed by the deterministic skillwiki CLI.",
   "author": {
     "name": "karlorz",

package/skills/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.107",
+  "version": "0.10.109",
   "description": "Project-aware Karpathy-style knowledge base: 22 prompt-only skills (wiki-*, proj-*, using-skillwiki, skillwiki-mcp, skillwiki-connect) backed by HTTP MCP wiki_capture.",
   "author": {
     "name": "karlorz"

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.10.107",
+  "version": "0.10.109",
   "private": true,
   "files": [
     "wiki-*",

package/skills/skills/skillwiki-connect/SKILL.md

@@ -68,6 +68,14 @@ skillwiki connect --from-stdin --dry-run
 
 Doctor on an MCP-only leaf (no vault + token present + vault-sync not installed) treats missing `WIKI_PATH` as info, not an init cluster.
 
+## Windows MCP-only leaves
+
+- Do not configure an optional Git mirror as `WIKI_PATH`: CLI `skillwiki query` reads that local mirror, not HTTP MCP. Use the advertised `wiki_query` tool for live reads and `wiki_context` for active work.
+- User config home resolves from a nonblank explicit home, then `HOME`, `USERPROFILE`, and the OS home directory. Empty or unset `HOME` does not require persisting a workaround environment variable. `skillwiki config path` and doctor's config-file row show the resolved absolute path.
+- If the npm-generated PowerShell launcher fails or interrupts a command sequence, use `skillwiki.cmd config path` and `skillwiki.cmd doctor --check-mcp`, or invoke the installed `dist/cli.js` with Node. Do not edit generated shims or infer a SkillWiki defect without inspecting the failing wrapper.
+- POSIX mode `0600` is not proof of a restrictive Windows ACL. The operator must keep the user config private. If a harness blocks attachment/stdin credential transfer, stop and request operator-controlled configuration of that resolved file with restricted access; never automatically bypass the harness, print the token, or store it in a repo or Drive.
+- Record CLI/plugin/daemon versions separately when investigating drift. A scheduled notifier is not evidence that an upgrade completed; use an explicit operator-approved upgrade and restart the client when delivery includes installation changes.
+
 ## Stop conditions
 
 - A non-local-only SkillWiki connector already authenticates.

package/skills/skills/skillwiki-mcp/SKILL.md

@@ -45,10 +45,18 @@ Check the successful write receipt's `vault_id` against the intended vault befor
 
 ## Reads
 
+CLI `skillwiki query` reads a local configured vault; it does not forward to HTTP MCP. On an MCP-only leaf, leave `WIKI_PATH` unset and use the advertised MCP `wiki_query` for live reads. Optional Git mirrors are read-only snapshots and may lag the live writer.
+
 Local `~/wiki` (or `skillwiki path`) is fine for reads. MCP read tools are optional. Prefer ordinary file reads of the local mirror. Frozen-leaf agents should use HTTP `wiki_sources_pending`, `wiki_lint_summary`, `wiki_stale`, `wiki_compile_status`, and `wiki_reviews` instead of local CLI commands when those tools are advertised.
 
 `wiki_query` is typed knowledge only unless `scope` is `work` or `all`. For recent progress, key projects, or to-dos, feature-detect and call `wiki_progress`; apply `project`, `host`, or `agent_role` filters when requested, and present `recent_progress`, `key_projects`, and `todos` as complete bullet lists. For queued work, doctor, plugin-drift, or MCP diagnose questions, call `wiki_context` first (active_work) or pass `scope: "work"` / `"all"`. Do not treat a top typed packet hit as the live work queue.
 
+## Bridge diagnostics
+
+Use a protocol SDK rather than copying a one-line SSE parser. SkillWiki diagnostic clients use the existing MCP TypeScript SDK to validate initialization, negotiate the protocol, send `notifications/initialized`, carry optional session IDs and negotiated protocol headers, and parse JSON or SSE (including multiline data). Empty HTTP 202 bodies acknowledge notifications/responses, not a successful initialize result. Doctor/connect probes have a 10-second overall deadline per connection and close their transports without terminating the server session.
+
+Treat a missing/invalid initialize result, authentication refusal, or timeout as a failed handshake; do not proceed to tools calls merely because the HTTP status is successful. Preserve bearer redaction in all diagnostics.
+
 ## Errors
 
 Report handshake, capture, and append failures literally. If tools are missing after a 401 or `missing_prereq`, stop and tell the operator to set `SKILLWIKI_MCP_TOKEN` via process env, host Configure, or `skillwiki connect --from-file` (unknown agents; never paste-into-chat), run `grok plugin update skillwiki`, and start a new session. Over SSH, treat an OAuth login URL the same way: report `headless_oauth_loopback` and stop. Do not fall back to local `raw/transcripts/` writes.

package/skills/skillwiki-connect/SKILL.md

@@ -68,6 +68,14 @@ skillwiki connect --from-stdin --dry-run
 
 Doctor on an MCP-only leaf (no vault + token present + vault-sync not installed) treats missing `WIKI_PATH` as info, not an init cluster.
 
+## Windows MCP-only leaves
+
+- Do not configure an optional Git mirror as `WIKI_PATH`: CLI `skillwiki query` reads that local mirror, not HTTP MCP. Use the advertised `wiki_query` tool for live reads and `wiki_context` for active work.
+- User config home resolves from a nonblank explicit home, then `HOME`, `USERPROFILE`, and the OS home directory. Empty or unset `HOME` does not require persisting a workaround environment variable. `skillwiki config path` and doctor's config-file row show the resolved absolute path.
+- If the npm-generated PowerShell launcher fails or interrupts a command sequence, use `skillwiki.cmd config path` and `skillwiki.cmd doctor --check-mcp`, or invoke the installed `dist/cli.js` with Node. Do not edit generated shims or infer a SkillWiki defect without inspecting the failing wrapper.
+- POSIX mode `0600` is not proof of a restrictive Windows ACL. The operator must keep the user config private. If a harness blocks attachment/stdin credential transfer, stop and request operator-controlled configuration of that resolved file with restricted access; never automatically bypass the harness, print the token, or store it in a repo or Drive.
+- Record CLI/plugin/daemon versions separately when investigating drift. A scheduled notifier is not evidence that an upgrade completed; use an explicit operator-approved upgrade and restart the client when delivery includes installation changes.
+
 ## Stop conditions
 
 - A non-local-only SkillWiki connector already authenticates.

package/skills/skillwiki-mcp/SKILL.md

@@ -45,10 +45,18 @@ Check the successful write receipt's `vault_id` against the intended vault befor
 
 ## Reads
 
+CLI `skillwiki query` reads a local configured vault; it does not forward to HTTP MCP. On an MCP-only leaf, leave `WIKI_PATH` unset and use the advertised MCP `wiki_query` for live reads. Optional Git mirrors are read-only snapshots and may lag the live writer.
+
 Local `~/wiki` (or `skillwiki path`) is fine for reads. MCP read tools are optional. Prefer ordinary file reads of the local mirror. Frozen-leaf agents should use HTTP `wiki_sources_pending`, `wiki_lint_summary`, `wiki_stale`, `wiki_compile_status`, and `wiki_reviews` instead of local CLI commands when those tools are advertised.
 
 `wiki_query` is typed knowledge only unless `scope` is `work` or `all`. For recent progress, key projects, or to-dos, feature-detect and call `wiki_progress`; apply `project`, `host`, or `agent_role` filters when requested, and present `recent_progress`, `key_projects`, and `todos` as complete bullet lists. For queued work, doctor, plugin-drift, or MCP diagnose questions, call `wiki_context` first (active_work) or pass `scope: "work"` / `"all"`. Do not treat a top typed packet hit as the live work queue.
 
+## Bridge diagnostics
+
+Use a protocol SDK rather than copying a one-line SSE parser. SkillWiki diagnostic clients use the existing MCP TypeScript SDK to validate initialization, negotiate the protocol, send `notifications/initialized`, carry optional session IDs and negotiated protocol headers, and parse JSON or SSE (including multiline data). Empty HTTP 202 bodies acknowledge notifications/responses, not a successful initialize result. Doctor/connect probes have a 10-second overall deadline per connection and close their transports without terminating the server session.
+
+Treat a missing/invalid initialize result, authentication refusal, or timeout as a failed handshake; do not proceed to tools calls merely because the HTTP status is successful. Preserve bearer redaction in all diagnostics.
+
 ## Errors
 
 Report handshake, capture, and append failures literally. If tools are missing after a 401 or `missing_prereq`, stop and tell the operator to set `SKILLWIKI_MCP_TOKEN` via process env, host Configure, or `skillwiki connect --from-file` (unknown agents; never paste-into-chat), run `grok plugin update skillwiki`, and start a new session. Over SSH, treat an OAuth login URL the same way: report `headless_oauth_loopback` and stop. Do not fall back to local `raw/transcripts/` writes.