skillwiki 0.10.1 → 0.10.3

package/dist/{chunk-SCGC7YNM.js → chunk-QH5MAV74.js}

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import {
+  FLEET_REL_PATH,
   findReviewRequiredOp,
   git,
   hasActiveGitSequencer,
@@ -14,6 +15,10 @@ import {
   ok
 } from "./chunk-C5OLZRRM.js";
 
+// src/utils/managed-write-preflight.ts
+import { existsSync, readFileSync as readFileSync2 } from "fs";
+import { join as join2, resolve } from "path";
+
 // src/utils/managed-write-lock.ts
 import { randomBytes } from "crypto";
 import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
@@ -78,19 +83,52 @@ function preflightBlocker(vault) {
   if (op) return { reason: "review-required", operation_id: op };
   return null;
 }
+function fleetManifestBytes(vault) {
+  const path = join2(vault, FLEET_REL_PATH);
+  if (!existsSync(path)) return null;
+  return readFileSync2(path);
+}
+function isGitVault(vault) {
+  return Boolean(git(vault, ["rev-parse", "--absolute-git-dir"]));
+}
 async function runManagedWritePreflight(input, deps = DEFAULT_DEPS) {
   const vault = input.vault;
-  const blocker = preflightBlocker(vault);
-  if (blocker) {
+  const convergenceVault = input.convergenceVault && resolve(input.convergenceVault) !== resolve(vault) ? resolve(input.convergenceVault) : void 0;
+  const gitVault = convergenceVault ?? vault;
+  const mutationBlocker = preflightBlocker(vault);
+  if (mutationBlocker) {
     return {
       exitCode: ExitCode.PREFLIGHT_FAILED,
       result: err("PREFLIGHT_FAILED", {
-        reason: blocker.reason,
-        operation_id: blocker.operation_id,
-        unmerged_paths: blocker.unmerged_paths
+        reason: mutationBlocker.reason,
+        operation_id: mutationBlocker.operation_id,
+        unmerged_paths: mutationBlocker.unmerged_paths
       })
     };
   }
+  if (convergenceVault) {
+    if (!isGitVault(convergenceVault)) {
+      return {
+        exitCode: ExitCode.PREFLIGHT_FAILED,
+        result: err("PREFLIGHT_FAILED", {
+          reason: "convergence-vault-not-git",
+          convergence_vault: convergenceVault
+        })
+      };
+    }
+    const gitBlocker = preflightBlocker(convergenceVault);
+    if (gitBlocker) {
+      return {
+        exitCode: ExitCode.PREFLIGHT_FAILED,
+        result: err("PREFLIGHT_FAILED", {
+          reason: gitBlocker.reason,
+          operation_id: gitBlocker.operation_id,
+          unmerged_paths: gitBlocker.unmerged_paths,
+          convergence_vault: convergenceVault
+        })
+      };
+    }
+  }
   const fleet = await loadFleetManifestAndHost({
     vault,
     hostId: input.hostId,
@@ -98,14 +136,16 @@ async function runManagedWritePreflight(input, deps = DEFAULT_DEPS) {
     home: input.home,
     osHostname: input.osHostname
   });
+  const dualPathMeta = convergenceVault ? { convergence_vault: convergenceVault } : {};
   if (!fleet) {
-    const head = git(vault, ["rev-parse", "HEAD"]) || null;
+    const head = git(gitVault, ["rev-parse", "HEAD"]) || null;
     return {
       exitCode: ExitCode.OK,
       result: ok({
         mode: "standalone",
         base_oid: head,
-        converged: false
+        converged: false,
+        ...dualPathMeta
       })
     };
   }
@@ -119,6 +159,27 @@ async function runManagedWritePreflight(input, deps = DEFAULT_DEPS) {
       })
     };
   }
+  if (convergenceVault && fleetManifestBytes(convergenceVault)) {
+    const convergeFleetCtx = await loadFleetManifestAndHost({
+      vault: convergenceVault,
+      hostId: input.hostId ?? fleet.hostId,
+      env: input.env,
+      home: input.home,
+      osHostname: input.osHostname
+    });
+    if (!convergeFleetCtx || convergeFleetCtx.identityStatus !== "known" || convergeFleetCtx.hostId !== fleet.hostId) {
+      return {
+        exitCode: ExitCode.PREFLIGHT_FAILED,
+        result: err("PREFLIGHT_FAILED", {
+          reason: "convergence-vault-identity-mismatch",
+          host_id: fleet.hostId,
+          convergence_host_id: convergeFleetCtx?.hostId,
+          convergence_identity_status: convergeFleetCtx?.identityStatus,
+          convergence_vault: convergenceVault
+        })
+      };
+    }
+  }
   const host = fleet.manifest.hosts[fleet.hostId];
   if (!host) {
     return {
@@ -134,12 +195,13 @@ async function runManagedWritePreflight(input, deps = DEFAULT_DEPS) {
         mode: "immutable-record",
         host_id: fleet.hostId,
         base_oid: null,
-        converged: false
+        converged: false,
+        ...dualPathMeta
       })
     };
   }
   const converge = await deps.converge({
-    vault,
+    vault: gitVault,
     lockToken: input.lockToken,
     env: input.env,
     home: input.home
@@ -148,11 +210,14 @@ async function runManagedWritePreflight(input, deps = DEFAULT_DEPS) {
     const exitCode = converge.error === "PREFLIGHT_FAILED" ? ExitCode.PREFLIGHT_FAILED : ExitCode.SYNC_PULL_FAILED;
     return { exitCode, result: converge };
   }
-  const baseOid = git(vault, ["rev-parse", "HEAD"]);
+  const baseOid = git(gitVault, ["rev-parse", "HEAD"]);
   if (!baseOid) {
     return {
       exitCode: ExitCode.PREFLIGHT_FAILED,
-      result: err("PREFLIGHT_FAILED", { reason: "missing-head-after-converge" })
+      result: err("PREFLIGHT_FAILED", {
+        reason: "missing-head-after-converge",
+        ...dualPathMeta
+      })
     };
   }
   return {
@@ -162,7 +227,8 @@ async function runManagedWritePreflight(input, deps = DEFAULT_DEPS) {
       host_id: fleet.hostId,
       base_oid: baseOid,
       converged: true,
-      helper_path: converge.data.helper_path
+      helper_path: converge.data.helper_path,
+      ...dualPathMeta
     })
   };
 }
@@ -177,6 +243,7 @@ async function runManagedWriteTransaction(input, deps = DEFAULT_DEPS) {
       {
         vault: input.vault,
         command: input.command,
+        convergenceVault: input.convergenceVault,
         hostId: input.hostId,
         lockToken: handle.ownerToken,
         env: input.env,

package/dist/{chunk-IZABIE44.js → chunk-U34B2XQJ.js}

@@ -9,8 +9,7 @@ import {
 } from "./chunk-C5OLZRRM.js";
 
 // src/utils/index-projection.ts
-import { readdirSync, readFileSync as readFileSync2 } from "fs";
-import { readFile as readFile3 } from "fs/promises";
+import { readFile as readFile4 } from "fs/promises";
 import { join as join3 } from "path";
 
 // src/utils/atomic-write.ts
@@ -59,6 +58,9 @@ async function atomicWriteText(path, text) {
   }
 }
 
+// src/utils/index-universe.ts
+import { readFile as readFile3 } from "fs/promises";
+
 // src/utils/typed-page.ts
 import { lstatSync, realpathSync } from "fs";
 import { dirname as dirname2, posix, relative, resolve, sep } from "path";
@@ -440,8 +442,15 @@ async function readPageCached(p, cache) {
   return pending;
 }
 
-// src/utils/index-projection.ts
-var SECTION_ORDER = ["Entities", "Concepts", "Comparisons", "Queries", "Meta", "Projects"];
+// src/utils/index-universe.ts
+var ROOT_INDEX_SECTION_ORDER = [
+  "Entities",
+  "Concepts",
+  "Comparisons",
+  "Queries",
+  "Meta",
+  "Projects"
+];
 var TYPE_SECTION = {
   entity: "Entities",
   concept: "Concepts",
@@ -450,6 +459,106 @@ var TYPE_SECTION = {
   meta: "Meta"
 };
 var compareText = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+function projectTitleFromReadme(text, slug) {
+  const match = text.match(/^#\s+Project:\s+(.+)$/m);
+  return match?.[1]?.trim() || slug;
+}
+async function buildRootIndexUniverse(input) {
+  const scanned = input.scan ? ok(input.scan) : await scanVault(input.vault);
+  if (!scanned.ok) return scanned;
+  const required = [];
+  const rejectedTyped = [];
+  const seen = /* @__PURE__ */ new Map();
+  let duplicatesRemoved = 0;
+  const typedPages = [...scanned.data.typedKnowledge].sort((a, b) => compareText(a.relPath, b.relPath));
+  for (const page of typedPages) {
+    let text;
+    try {
+      text = await readFile3(page.absPath, "utf8");
+    } catch {
+      continue;
+    }
+    const prepared = prepareTypedPage(text, page.relPath);
+    if (!prepared.ok) {
+      rejectedTyped.push({
+        relPath: page.relPath,
+        error: prepared.error,
+        detail: prepared.detail
+      });
+      continue;
+    }
+    const section = TYPE_SECTION[prepared.data.type];
+    if (!section) {
+      rejectedTyped.push({
+        relPath: page.relPath,
+        error: "SCHEME_REJECTED",
+        detail: { type: prepared.data.type }
+      });
+      continue;
+    }
+    const target = prepared.data.target.replace(/\.md$/, "");
+    const previousTitle = seen.get(target);
+    if (previousTitle !== void 0) {
+      if (previousTitle !== prepared.data.title) {
+        return err("SCHEME_REJECTED", {
+          message: `duplicate index target ${target} with differing titles`,
+          titles: [previousTitle, prepared.data.title]
+        });
+      }
+      duplicatesRemoved += 1;
+      continue;
+    }
+    seen.set(target, prepared.data.title);
+    required.push({
+      section,
+      target,
+      title: prepared.data.title,
+      source: "typed"
+    });
+  }
+  const projectReadmes = scanned.data.allMarkdown.filter((page) => /^projects\/[^/]+\/README\.md$/.test(page.relPath)).sort((a, b) => compareText(a.relPath, b.relPath));
+  for (const readme of projectReadmes) {
+    let text;
+    try {
+      text = await readFile3(readme.absPath, "utf8");
+    } catch {
+      continue;
+    }
+    const projectSlug = readme.relPath.split("/")[1];
+    const target = `projects/${projectSlug}/README`;
+    const title = projectTitleFromReadme(text, projectSlug);
+    const previousTitle = seen.get(target);
+    if (previousTitle !== void 0) {
+      if (previousTitle !== title) {
+        return err("SCHEME_REJECTED", {
+          message: `duplicate index target ${target} with differing titles`
+        });
+      }
+      duplicatesRemoved += 1;
+      continue;
+    }
+    seen.set(target, title);
+    required.push({ section: "Projects", target, title, source: "project" });
+  }
+  required.sort((a, b) => {
+    const sectionA = ROOT_INDEX_SECTION_ORDER.indexOf(a.section);
+    const sectionB = ROOT_INDEX_SECTION_ORDER.indexOf(b.section);
+    if (sectionA !== sectionB) return sectionA - sectionB;
+    return compareText(a.target, b.target);
+  });
+  const knownTargets = new Set(required.map((entry) => entry.target));
+  for (const page of [...scanned.data.compound].sort((a, b) => compareText(a.relPath, b.relPath))) {
+    knownTargets.add(page.relPath.replace(/\.md$/, ""));
+  }
+  return ok({
+    required,
+    knownTargets,
+    rejectedTyped,
+    duplicatesRemoved
+  });
+}
+
+// src/utils/index-projection.ts
 var UNMANAGED_START = "<!-- skillwiki:index-unmanaged:start -->";
 var UNMANAGED_END = "<!-- skillwiki:index-unmanaged:end -->";
 function extractUnmanaged(currentText) {
@@ -480,94 +589,27 @@ function priorWikilinkTargets(text) {
   }
   return out;
 }
-function projectTitleFromReadme(text, slug) {
-  const m = text.match(/^#\s+Project:\s+(.+)$/m);
-  return m?.[1]?.trim() || slug;
-}
 async function renderRootIndex(input) {
   const vault = input.vault;
   let currentText = input.currentText;
   if (currentText === void 0) {
     try {
-      currentText = await readFile3(join3(vault, "index.md"), "utf8");
+      currentText = await readFile4(join3(vault, "index.md"), "utf8");
     } catch {
       currentText = "";
     }
   }
   const unmanaged = extractUnmanaged(currentText);
   if (!unmanaged.ok) return unmanaged;
-  const scan = await scanVault(vault);
-  if (!scan.ok) return scan;
-  const entries = [];
-  const seen = /* @__PURE__ */ new Map();
-  let duplicatesRemoved = 0;
-  for (const page of scan.data.typedKnowledge) {
-    let text;
-    try {
-      text = await readFile3(join3(vault, page.relPath), "utf8");
-    } catch {
-      continue;
-    }
-    const prepared = prepareTypedPage(text, page.relPath);
-    if (!prepared.ok) continue;
-    const section = TYPE_SECTION[prepared.data.type];
-    if (!section) continue;
-    const target = prepared.data.target.replace(/\.md$/, "");
-    const prev = seen.get(target);
-    if (prev !== void 0) {
-      if (prev !== prepared.data.title) {
-        return err("SCHEME_REJECTED", {
-          message: `duplicate index target ${target} with differing titles`,
-          titles: [prev, prepared.data.title]
-        });
-      }
-      duplicatesRemoved += 1;
-      continue;
-    }
-    seen.set(target, prepared.data.title);
-    entries.push({
-      section,
-      target,
-      title: prepared.data.title,
-      source: "typed"
-    });
-  }
-  try {
-    const projectsRoot = join3(vault, "projects");
-    for (const slug of readdirSync(projectsRoot, { withFileTypes: true })) {
-      if (!slug.isDirectory()) continue;
-      const readmePath = join3(projectsRoot, slug.name, "README.md");
-      let text;
-      try {
-        text = readFileSync2(readmePath, "utf8");
-      } catch {
-        continue;
-      }
-      const target = `projects/${slug.name}/README`;
-      const title = projectTitleFromReadme(text, slug.name);
-      const prev = seen.get(target);
-      if (prev !== void 0) {
-        if (prev !== title) {
-          return err("SCHEME_REJECTED", {
-            message: `duplicate index target ${target} with differing titles`
-          });
-        }
-        duplicatesRemoved += 1;
-        continue;
-      }
-      seen.set(target, title);
-      entries.push({ section: "Projects", target, title, source: "project" });
-    }
-  } catch {
-  }
-  entries.sort((a, b) => {
-    const sa = SECTION_ORDER.indexOf(a.section);
-    const sb = SECTION_ORDER.indexOf(b.section);
-    if (sa !== sb) return sa - sb;
-    return compareText(a.target, b.target);
-  });
+  const universe = await buildRootIndexUniverse({ vault });
+  if (!universe.ok) return universe;
+  const entries = universe.data.required;
+  let duplicatesRemoved = universe.data.duplicatesRemoved;
   const prior = priorWikilinkTargets(currentText);
-  const generatedTargets = new Set(entries.map((e) => e.target));
+  const knownTargets = universe.data.knownTargets;
+  const knownBasenames = new Set(
+    [...knownTargets].map((target) => target.split("/").pop().toLowerCase())
+  );
   const priorLower = /* @__PURE__ */ new Map();
   for (const t of prior) {
     const k = t.toLowerCase();
@@ -585,15 +627,10 @@ async function renderRootIndex(input) {
   const ghostsRemoved = [
     ...new Set(
       prior.filter((t) => {
-        const bare = t.includes("/") ? t : null;
-        if (bare && !generatedTargets.has(bare) && !generatedTargets.has(t)) {
-          if (!seen.has(t)) return true;
-        }
         if (!t.includes("/")) {
-          const matches = [...generatedTargets].filter((g) => g.split("/").pop() === t);
-          return matches.length === 0;
+          return !knownBasenames.has(t.toLowerCase());
         }
-        return !generatedTargets.has(t);
+        return !knownTargets.has(t);
       })
     )
   ];
@@ -603,7 +640,7 @@ async function renderRootIndex(input) {
     "Generated by `skillwiki index rebuild`. Generated sections are derived from typed-page frontmatter and project manifests.",
     ""
   ];
-  for (const section of SECTION_ORDER) {
+  for (const section of ROOT_INDEX_SECTION_ORDER) {
     lines.push(`## ${section}`, "");
     const sectionEntries = entries.filter((e) => e.section === section);
     for (const e of sectionEntries) {
@@ -642,6 +679,7 @@ export {
   scanVault,
   readPage,
   readPageCached,
+  buildRootIndexUniverse,
   renderRootIndex,
   writeRootIndexProjection
 };

package/dist/{chunk-XSTXPA34.js → chunk-Z3WS45PL.js}

@@ -5,6 +5,7 @@ import {
 } from "./chunk-7I2TPIV5.js";
 import {
   atomicWriteText,
+  buildRootIndexUniverse,
   extractFrontmatter,
   mapWithConcurrency,
   prepareTypedPage,
@@ -18,7 +19,7 @@ import {
   splitFrontmatter,
   vaultIoConcurrency,
   writeRootIndexProjection
-} from "./chunk-IZABIE44.js";
+} from "./chunk-U34B2XQJ.js";
 import {
   CONFIG_KEYS,
   isValidWikiProfileKey,
@@ -1561,8 +1562,11 @@ function normalizeIndexTarget(raw) {
   return raw.replace(/\.md$/, "").replace(/^\.?\//, "");
 }
 async function runIndexCheck(input) {
-  const scan = input.scan ? ok(input.scan) : await scanVault(input.vault);
-  if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const universe = await buildRootIndexUniverse({ vault: input.vault, scan: input.scan });
+  if (!universe.ok) {
+    const exitCode = universe.error === "VAULT_PATH_INVALID" ? ExitCode.VAULT_PATH_INVALID : ExitCode.SCHEME_REJECTED;
+    return { exitCode, result: universe };
+  }
   let indexText = "";
   try {
     indexText = await readFile6(join10(input.vault, "index.md"), "utf8");
@@ -1579,25 +1583,22 @@ async function runIndexCheck(input) {
     indexBare.set(bare, list);
   }
   const required = /* @__PURE__ */ new Map();
-  const known = /* @__PURE__ */ new Set();
-  for (const p of scan.data.typedKnowledge) {
-    const target = p.relPath.replace(/\.md$/, "");
-    required.set(target, p.relPath);
-    known.add(target);
+  for (const entry of universe.data.required) {
+    required.set(entry.target, `${entry.target}.md`);
   }
-  for (const p of scan.data.compound) {
-    known.add(p.relPath.replace(/\.md$/, ""));
+  const requiredBasenameCounts = /* @__PURE__ */ new Map();
+  for (const target of required.keys()) {
+    const basename3 = target.split("/").pop().toLowerCase();
+    requiredBasenameCounts.set(basename3, (requiredBasenameCounts.get(basename3) ?? 0) + 1);
   }
+  const known = universe.data.knownTargets;
   const missing_from_index = [];
   for (const [target, relPath] of required.entries()) {
     if (indexTargets.has(target)) continue;
     const bare = target.split("/").pop().toLowerCase();
     const bareHits = indexBare.get(bare) ?? [];
     const basenameOnly = bareHits.filter((t) => !t.includes("/"));
-    const sameNameRequired = [...required.keys()].filter(
-      (t) => t.split("/").pop().toLowerCase() === bare
-    );
-    if (basenameOnly.length === 1 && sameNameRequired.length === 1) continue;
+    if (basenameOnly.length === 1 && requiredBasenameCounts.get(bare) === 1) continue;
     missing_from_index.push(relPath);
   }
   const ghost_entries = [];

package/dist/cli.js

@@ -68,7 +68,7 @@ import {
   satelliteLatestRunPath,
   taxonomyCommentForPage,
   upsertIndexEntry
-} from "./chunk-XSTXPA34.js";
+} from "./chunk-Z3WS45PL.js";
 import {
   normalizeDistTag,
   readCache,
@@ -88,13 +88,13 @@ import {
   scanVault,
   splitFrontmatter,
   writeRootIndexProjection
-} from "./chunk-IZABIE44.js";
+} from "./chunk-U34B2XQJ.js";
 import {
   acquireManagedWriteLock,
   releaseManagedWriteLock,
   runManagedWritePreflight,
   runManagedWriteTransaction
-} from "./chunk-SCGC7YNM.js";
+} from "./chunk-QH5MAV74.js";
 import {
   FLEET_REL_PATH,
   git,
@@ -2533,7 +2533,7 @@ ${fmRewritten}
   await rename2(join17(input.vault, relPath), join17(input.vault, archivePath));
   let indexUpdated = false;
   if (!isRaw) {
-    const { renderRootIndex: renderRootIndex2, writeRootIndexProjection: writeRootIndexProjection2 } = await import("./index-projection-ERFX76U5.js");
+    const { renderRootIndex: renderRootIndex2, writeRootIndexProjection: writeRootIndexProjection2 } = await import("./index-projection-VNJ3TLEK.js");
     const before = await readFile7(join17(input.vault, "index.md"), "utf8").catch(() => "");
     const fullTarget = relPath.replace(/\.md$/, "");
     const bare = fullTarget.split("/").pop() ?? fullTarget;
@@ -2644,7 +2644,7 @@ async function runRemove(input) {
   if (relPath.endsWith(".md") && !relPath.startsWith("raw/")) {
     const { readFile: readFile17 } = await import("fs/promises");
     const { join: pathJoin } = await import("path");
-    const { renderRootIndex: renderRootIndex2, writeRootIndexProjection: writeRootIndexProjection2 } = await import("./index-projection-ERFX76U5.js");
+    const { renderRootIndex: renderRootIndex2, writeRootIndexProjection: writeRootIndexProjection2 } = await import("./index-projection-VNJ3TLEK.js");
     const before = await readFile17(pathJoin(input.vault, "index.md"), "utf8").catch(() => "");
     const fullTarget = relPath.replace(/\.md$/, "");
     const bare = fullTarget.split("/").pop() ?? fullTarget;
@@ -6749,11 +6749,12 @@ async function emitManagedVaultWrite(vault, command, mutate, opts) {
   if (guard.blocked) {
     return emit({ exitCode: guard.exitCode, result: guard.result }, void 0, { postCommit: false });
   }
-  const { runManagedWriteTransaction: runManagedWriteTransaction2 } = await import("./managed-write-preflight-PW4OOOMV.js");
+  const { runManagedWriteTransaction: runManagedWriteTransaction2 } = await import("./managed-write-preflight-DTNXZBLI.js");
   const run = await runManagedWriteTransaction2({
     vault,
     command,
     allowImmutableRecord: opts?.allowImmutableRecord === true,
+    convergenceVault: opts?.convergenceVault,
     mutate: async (receipt) => await mutate(receipt)
   });
   return emit(run, vault, opts);
@@ -6982,26 +6983,28 @@ logCmd.command("materialize [vault]").description("preview or write root log.md
     );
   } else emit(await runLogMaterialize({ vault: v.vault, write: false }), v.vault);
 });
-logCmd.command("migrate-legacy [vault]").description("backfill immutable events from historical root log.md blocks").option("--write", "write events", false).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+logCmd.command("migrate-legacy [vault]").description("backfill immutable events from historical root log.md blocks").option("--write", "write events", false).option("--converge-vault <dir>", "Git vault used for managed pull and base-OID proof").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else if (opts.write) {
     return emitManagedVaultWrite(
       v.vault,
       "log migrate-legacy",
-      () => runLogMigrateLegacy({ vault: v.vault, write: true })
+      () => runLogMigrateLegacy({ vault: v.vault, write: true }),
+      { convergenceVault: opts.convergeVault }
     );
   } else emit(await runLogMigrateLegacy({ vault: v.vault, write: false }), v.vault);
 });
 var projectionsCmd = program.command("projections").description("root index/log projection materialization");
-projectionsCmd.command("materialize [vault]").description("preview or write root index.md and log.md as a pair").option("--write", "write projections", false).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+projectionsCmd.command("materialize [vault]").description("preview or write root index.md and log.md as a pair").option("--write", "write projections", false).option("--converge-vault <dir>", "Git vault used for managed pull and base-OID proof").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else if (opts.write) {
     return emitManagedVaultWrite(
       v.vault,
       "projections materialize",
-      () => runProjectionsMaterialize({ vault: v.vault, write: true })
+      () => runProjectionsMaterialize({ vault: v.vault, write: true }),
+      { convergenceVault: opts.convergeVault }
     );
   } else emit(await runProjectionsMaterialize({ vault: v.vault, write: false }), v.vault);
 });

package/dist/{index-projection-ERFX76U5.js → index-projection-VNJ3TLEK.js}

@@ -2,7 +2,7 @@
 import {
   renderRootIndex,
   writeRootIndexProjection
-} from "./chunk-IZABIE44.js";
+} from "./chunk-U34B2XQJ.js";
 import "./chunk-C5OLZRRM.js";
 export {
   renderRootIndex,

package/dist/{managed-write-preflight-PW4OOOMV.js → managed-write-preflight-DTNXZBLI.js}

@@ -2,7 +2,7 @@
 import {
   runManagedWritePreflight,
   runManagedWriteTransaction
-} from "./chunk-SCGC7YNM.js";
+} from "./chunk-QH5MAV74.js";
 import "./chunk-R6BKJWVC.js";
 import "./chunk-C5OLZRRM.js";
 export {

package/dist/skillwiki-mcp.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import {
   runSkillwikiMcpStdio
-} from "./chunk-XSTXPA34.js";
+} from "./chunk-Z3WS45PL.js";
 import "./chunk-7I2TPIV5.js";
-import "./chunk-IZABIE44.js";
+import "./chunk-U34B2XQJ.js";
 import "./chunk-R6BKJWVC.js";
 import "./chunk-C5OLZRRM.js";
 

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

@@ -308,9 +308,35 @@ fi
 
 refresh_git_baseline
 
+# Dual-path requires distinct live mutation vs Git convergence roots.
+# Same-path would materialize projections then immediately rclone-overwrite them.
+if [ "$(cd "$WIKI_DIR" 2>/dev/null && pwd -P)" = "$(cd "$SNAPSHOT_WORKTREE" 2>/dev/null && pwd -P)" ]; then
+    log "ERROR: WIKI_DIR and WIKI_GIT_WORKTREE must be distinct paths for dual-path projection (got: $WIKI_DIR)"
+    exit 1
+fi
+
 # Single-authority root projections before FUSE/S3 pull promotion.
-if command -v skillwiki >/dev/null 2>&1; then
-    if ! skillwiki projections materialize "$WIKI_DIR" --write >>"$LOG_FILE" 2>&1; then
+# Mutation target is the live vault ($WIKI_DIR); Git pull/base-OID use
+# $SNAPSHOT_WORKTREE so FUSE/S3 hosts without a local Git HEAD still work.
+SKILLWIKI_BIN="${WIKI_SNAPSHOT_SKILLWIKI_BIN:-skillwiki}"
+if command -v "$SKILLWIKI_BIN" >/dev/null 2>&1; then
+    case "${WIKI_SNAPSHOT_MIGRATE_LEGACY:-0}" in
+        0) ;;
+        1)
+            if ! "$SKILLWIKI_BIN" log migrate-legacy "$WIKI_DIR" --write \
+                --converge-vault "$SNAPSHOT_WORKTREE" >>"$LOG_FILE" 2>&1; then
+                log "FAIL legacy log migration; snapshot promotion refused"
+                exit 1
+            fi
+            log "OK legacy log migration before projection (attended one-run)"
+            ;;
+        *)
+            log "ERROR: WIKI_SNAPSHOT_MIGRATE_LEGACY must be 0 or 1 (got: ${WIKI_SNAPSHOT_MIGRATE_LEGACY})"
+            exit 1
+            ;;
+    esac
+    if ! "$SKILLWIKI_BIN" projections materialize "$WIKI_DIR" --write \
+        --converge-vault "$SNAPSHOT_WORKTREE" >>"$LOG_FILE" 2>&1; then
         log "FAIL root projection materialization; snapshot promotion refused"
         exit 1
     fi

package/package.json

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

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

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

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

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

package/skills/package.json

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