skillwiki 0.10.0 → 0.10.2

package/dist/{chunk-S5ABQCXQ.js → chunk-R6BKJWVC.js}

@@ -562,6 +562,305 @@ function safeUserName() {
   }
 }
 
+// src/utils/git.ts
+import { execFileSync } from "child_process";
+function git(cwd, args) {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch {
+    return "";
+  }
+}
+function gitStrict(cwd, args) {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+}
+
+// src/utils/operation-journal.ts
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync
+} from "fs";
+import { join as join2 } from "path";
+function journalDir(vault) {
+  const gitPath = git(vault, ["rev-parse", "--git-path", "vault-sync/operations"]);
+  if (!gitPath) return null;
+  return gitPath.startsWith("/") ? gitPath : join2(vault, gitPath);
+}
+function parseJournalEnv(text) {
+  return Object.fromEntries(
+    text.split("\n").filter((line) => line.includes("=")).map((line) => {
+      const i = line.indexOf("=");
+      return [line.slice(0, i), line.slice(i + 1)];
+    })
+  );
+}
+function serializeJournalEnv(fields, preferredOrder = []) {
+  const keys = [...preferredOrder.filter((k) => k in fields), ...Object.keys(fields).filter((k) => !preferredOrder.includes(k))];
+  const seen = /* @__PURE__ */ new Set();
+  const lines = [];
+  for (const k of keys) {
+    if (seen.has(k)) continue;
+    seen.add(k);
+    lines.push(`${k}=${fields[k]}`);
+  }
+  return lines.join("\n") + "\n";
+}
+function readJournal(vault, opId) {
+  const dir = journalDir(vault);
+  if (!dir) return null;
+  const path = join2(dir, `${opId}.env`);
+  if (!existsSync(path)) return null;
+  try {
+    return parseJournalEnv(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeJournal(vault, opId, fields) {
+  const dir = journalDir(vault);
+  if (!dir) return false;
+  try {
+    mkdirSync(dir, { recursive: true });
+    const path = join2(dir, `${opId}.env`);
+    const tmp = `${path}.tmp.${process.pid}`;
+    const order = [
+      "operation_id",
+      "phase",
+      "retry_count",
+      "original_branch",
+      "original_head",
+      "target_oid",
+      "owned_stash_oid",
+      "preservation_scope",
+      "lock_identity",
+      "helper_version",
+      "deployed_runtime_hash",
+      "conflict_identity",
+      "handoff",
+      "reason",
+      "prior_reason",
+      "superseded_at",
+      "cleared_reason",
+      "cleared_by",
+      "worktree_path",
+      "worktree_git_dir",
+      "inventory_path"
+    ];
+    writeFileSync(tmp, serializeJournalEnv(fields, order), "utf8");
+    renameSync(tmp, path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function listJournalOpIds(vault) {
+  const dir = journalDir(vault);
+  if (!dir || !existsSync(dir)) return [];
+  try {
+    return readdirSync(dir).filter((f) => f.endsWith(".env")).map((f) => f.replace(/\.env$/, "")).sort();
+  } catch {
+    return [];
+  }
+}
+function listReviewRequiredOps(vault) {
+  const currentGitDir = git(vault, ["rev-parse", "--absolute-git-dir"]);
+  const out = [];
+  for (const opId of listJournalOpIds(vault)) {
+    const fields = readJournal(vault, opId);
+    if (!fields) continue;
+    if (fields.phase !== "review-required" || fields.handoff !== "1") continue;
+    const journalGitDir = fields.worktree_git_dir ?? "";
+    if (!journalGitDir || !currentGitDir || journalGitDir === currentGitDir) {
+      out.push({ opId, fields });
+    }
+  }
+  return out;
+}
+function findReviewRequiredOp(vault) {
+  return listReviewRequiredOps(vault)[0]?.opId;
+}
+function hasUnmergedPaths(vault) {
+  const unmergedRaw = git(vault, ["diff", "--name-only", "--diff-filter=U"]);
+  return unmergedRaw ? unmergedRaw.split("\n").map((s) => s.trim()).filter(Boolean) : [];
+}
+function hasActiveGitSequencer(vault) {
+  const gitDir = git(vault, ["rev-parse", "--absolute-git-dir"]);
+  if (!gitDir) return false;
+  for (const m of ["MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD"]) {
+    if (existsSync(join2(gitDir, m))) return true;
+  }
+  if (existsSync(join2(gitDir, "rebase-merge")) || existsSync(join2(gitDir, "rebase-apply"))) {
+    return true;
+  }
+  return false;
+}
+function isWorktreeClean(vault) {
+  const porcelain = git(vault, ["status", "--porcelain"]);
+  return !porcelain || porcelain.trim() === "";
+}
+function canSupersedeJournal(vault, fields) {
+  if (hasUnmergedPaths(vault).length > 0) return false;
+  if (hasActiveGitSequencer(vault)) return false;
+  if (!isWorktreeClean(vault)) return false;
+  const target = fields.target_oid?.trim();
+  if (!target) return false;
+  const head = git(vault, ["rev-parse", "HEAD"]);
+  if (!head) return false;
+  return gitMergeBaseIsAncestor(vault, target, head);
+}
+function gitMergeBaseIsAncestor(vault, ancestor, tip) {
+  if (ancestor === tip) return true;
+  const mb = git(vault, ["merge-base", ancestor, tip]);
+  return mb !== "" && mb === ancestor;
+}
+function markJournalSuperseded(vault, opId, fields, by) {
+  const next = { ...fields };
+  if (next.reason && next.reason !== "superseded-stale-review-required") {
+    next.prior_reason = next.prior_reason || next.reason;
+  }
+  next.phase = "complete";
+  next.reason = "superseded-stale-review-required";
+  next.superseded_at = (/* @__PURE__ */ new Date()).toISOString();
+  next.cleared_by = by;
+  next.cleared_reason = `operator-or-preflight ${next.superseded_at}`;
+  if (!next.handoff) next.handoff = "1";
+  if (!next.operation_id) next.operation_id = opId;
+  return writeJournal(vault, opId, next);
+}
+function supersedeStaleReviewRequiredJournals(vault, opts = {}) {
+  const by = opts.by ?? "skillwiki-preflight";
+  const superseded = [];
+  const skipped = [];
+  if (hasUnmergedPaths(vault).length > 0 || hasActiveGitSequencer(vault) || !isWorktreeClean(vault)) {
+    for (const { opId } of listReviewRequiredOps(vault)) skipped.push(opId);
+    return { superseded, skipped };
+  }
+  for (const { opId, fields } of listReviewRequiredOps(vault)) {
+    if (!canSupersedeJournal(vault, fields)) {
+      skipped.push(opId);
+      continue;
+    }
+    if (opts.dryRun) {
+      superseded.push(opId);
+      continue;
+    }
+    if (markJournalSuperseded(vault, opId, fields, by)) {
+      superseded.push(opId);
+    } else {
+      skipped.push(opId);
+    }
+  }
+  return { superseded, skipped };
+}
+
+// src/utils/vault-sync-helper.ts
+import { spawnSync } from "child_process";
+import { existsSync as existsSync2 } from "fs";
+import { homedir, platform } from "os";
+import { dirname as dirname2, join as join3 } from "path";
+import { fileURLToPath } from "url";
+var HELPER_NAME = "wiki-pull-with-auto-resolve.sh";
+function candidateHelperPaths(input = { vault: "" }) {
+  const env = input.env ?? process.env;
+  const paths = [];
+  if (input.helperPath) paths.push(input.helperPath);
+  if (env.SKILLWIKI_VAULT_SYNC_PULL_HELPER) paths.push(env.SKILLWIKI_VAULT_SYNC_PULL_HELPER);
+  let here = input.moduleDir;
+  if (!here) {
+    try {
+      here = dirname2(fileURLToPath(import.meta.url));
+    } catch {
+      here = void 0;
+    }
+  }
+  if (here) {
+    paths.push(join3(here, "vault-sync", "scripts", HELPER_NAME));
+    paths.push(join3(here, "..", "vault-sync", "scripts", HELPER_NAME));
+    paths.push(join3(here, "..", "..", "vault-sync", "scripts", HELPER_NAME));
+    paths.push(join3(here, "..", "..", "..", "vault-sync", "scripts", HELPER_NAME));
+  }
+  const home = input.home ?? env.HOME ?? env.USERPROFILE ?? (() => {
+    try {
+      return homedir();
+    } catch {
+      return void 0;
+    }
+  })();
+  if (home) {
+    const xdg = env.XDG_DATA_HOME;
+    const isDarwin = platform() === "darwin";
+    if (isDarwin) {
+      paths.push(join3(home, "Library", "Application Support", "vault-sync", "bin", HELPER_NAME));
+    }
+    paths.push(join3(xdg || join3(home, ".local", "share"), "vault-sync", "bin", HELPER_NAME));
+    if (!isDarwin) {
+      paths.push(join3(home, "Library", "Application Support", "vault-sync", "bin", HELPER_NAME));
+    }
+  }
+  return paths;
+}
+function resolveVaultSyncPullHelper(input) {
+  for (const p of candidateHelperPaths(input)) {
+    if (p && existsSync2(p)) return p;
+  }
+  return null;
+}
+async function runVaultSyncPullHelper(input) {
+  const helperPath = resolveVaultSyncPullHelper(input);
+  if (!helperPath) {
+    const tried = candidateHelperPaths(input).filter(Boolean);
+    return err("GIT_PULL_FAILED", {
+      message: "canonical vault-sync pull helper not found; run skillwiki doctor; install skillwiki@0.10.1+ or set SKILLWIKI_VAULT_SYNC_PULL_HELPER; host install: ~/Library/Application Support/vault-sync/bin or ~/.local/share/vault-sync/bin",
+      tried_paths: tried.slice(0, 12)
+    });
+  }
+  const remote = input.remote ?? "origin";
+  const branch = input.branch ?? "main";
+  const beforeOid = git(input.vault, ["rev-parse", "HEAD"]);
+  if (!beforeOid) {
+    return err("GIT_PULL_FAILED", { message: "could not read HEAD before pull" });
+  }
+  const env = {
+    ...process.env,
+    ...input.env ?? {},
+    WIKI_DIR: input.vault
+  };
+  if (input.lockToken) {
+    env.VAULT_SYNC_MANAGED_LOCK_TOKEN = input.lockToken;
+  }
+  const result = spawnSync("bash", [helperPath, remote, branch], {
+    env,
+    encoding: "utf8",
+    cwd: input.vault
+  });
+  const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+  const status = result.status ?? 1;
+  if (status === 2) {
+    return err("PREFLIGHT_FAILED", { reason: "existing-handoff", output, helper_path: helperPath });
+  }
+  if (status !== 0) {
+    return err("GIT_PULL_FAILED", {
+      message: result.error ? String(result.error) : `helper exited ${status}`,
+      output,
+      helper_path: helperPath
+    });
+  }
+  const afterOid = git(input.vault, ["rev-parse", "HEAD"]);
+  if (!afterOid) {
+    return err("GIT_PULL_FAILED", { message: "could not read HEAD after pull", helper_path: helperPath });
+  }
+  return ok({
+    before_oid: beforeOid,
+    after_oid: afterOid,
+    changed: beforeOid !== afterOid,
+    helper_path: helperPath
+  });
+}
+
 export {
   CONFIG_KEYS,
   isValidWikiProfileKey,
@@ -576,5 +875,16 @@ export {
   snapshotterAliasForLocalHost,
   satelliteGateFromFleetLoad,
   loadFleetManifest,
-  resolveFleetHostId
+  resolveFleetHostId,
+  git,
+  gitStrict,
+  readJournal,
+  listJournalOpIds,
+  listReviewRequiredOps,
+  findReviewRequiredOp,
+  hasUnmergedPaths,
+  hasActiveGitSequencer,
+  supersedeStaleReviewRequiredJournals,
+  resolveVaultSyncPullHelper,
+  runVaultSyncPullHelper
 };

package/dist/{chunk-5TBIMLTZ.js → chunk-SCGC7YNM.js}

@@ -1,30 +1,19 @@
 #!/usr/bin/env node
 import {
-  loadFleetManifestAndHost
-} from "./chunk-S5ABQCXQ.js";
+  findReviewRequiredOp,
+  git,
+  hasActiveGitSequencer,
+  hasUnmergedPaths,
+  loadFleetManifestAndHost,
+  runVaultSyncPullHelper,
+  supersedeStaleReviewRequiredJournals
+} from "./chunk-R6BKJWVC.js";
 import {
   ExitCode,
   err,
   ok
 } from "./chunk-C5OLZRRM.js";
 
-// src/utils/managed-write-preflight.ts
-import { readdirSync, readFileSync as readFileSync2 } from "fs";
-import { join as join3 } from "path";
-
-// src/utils/git.ts
-import { execFileSync } from "child_process";
-function git(cwd, args) {
-  try {
-    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
-  } catch {
-    return "";
-  }
-}
-function gitStrict(cwd, args) {
-  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
-}
-
 // src/utils/managed-write-lock.ts
 import { randomBytes } from "crypto";
 import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
@@ -68,122 +57,12 @@ function releaseManagedWriteLock(handle) {
   }
 }
 
-// src/utils/vault-sync-helper.ts
-import { spawnSync } from "child_process";
-import { existsSync } from "fs";
-import { dirname as dirname2, join as join2 } from "path";
-import { fileURLToPath } from "url";
-function candidateHelperPaths(input) {
-  const env = input.env ?? process.env;
-  const paths = [];
-  if (input.helperPath) paths.push(input.helperPath);
-  if (env.SKILLWIKI_VAULT_SYNC_PULL_HELPER) paths.push(env.SKILLWIKI_VAULT_SYNC_PULL_HELPER);
-  try {
-    const here = dirname2(fileURLToPath(import.meta.url));
-    paths.push(join2(here, "..", "vault-sync", "scripts", "wiki-pull-with-auto-resolve.sh"));
-    paths.push(join2(here, "..", "..", "vault-sync", "scripts", "wiki-pull-with-auto-resolve.sh"));
-    paths.push(join2(here, "..", "..", "..", "vault-sync", "scripts", "wiki-pull-with-auto-resolve.sh"));
-  } catch {
-  }
-  return paths;
-}
-function resolveVaultSyncPullHelper(input) {
-  for (const p of candidateHelperPaths(input)) {
-    if (p && existsSync(p)) return p;
-  }
-  return null;
-}
-async function runVaultSyncPullHelper(input) {
-  const helperPath = resolveVaultSyncPullHelper(input);
-  if (!helperPath) {
-    return err("GIT_PULL_FAILED", { message: "canonical vault-sync pull helper not found" });
-  }
-  const remote = input.remote ?? "origin";
-  const branch = input.branch ?? "main";
-  const beforeOid = git(input.vault, ["rev-parse", "HEAD"]);
-  if (!beforeOid) {
-    return err("GIT_PULL_FAILED", { message: "could not read HEAD before pull" });
-  }
-  const env = {
-    ...process.env,
-    ...input.env ?? {},
-    WIKI_DIR: input.vault
-  };
-  if (input.lockToken) {
-    env.VAULT_SYNC_MANAGED_LOCK_TOKEN = input.lockToken;
-  }
-  const result = spawnSync("bash", [helperPath, remote, branch], {
-    env,
-    encoding: "utf8",
-    cwd: input.vault
-  });
-  const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
-  const status = result.status ?? 1;
-  if (status === 2) {
-    return err("PREFLIGHT_FAILED", { reason: "existing-handoff", output, helper_path: helperPath });
-  }
-  if (status !== 0) {
-    return err("GIT_PULL_FAILED", {
-      message: result.error ? String(result.error) : `helper exited ${status}`,
-      output,
-      helper_path: helperPath
-    });
-  }
-  const afterOid = git(input.vault, ["rev-parse", "HEAD"]);
-  if (!afterOid) {
-    return err("GIT_PULL_FAILED", { message: "could not read HEAD after pull", helper_path: helperPath });
-  }
-  return ok({
-    before_oid: beforeOid,
-    after_oid: afterOid,
-    changed: beforeOid !== afterOid,
-    helper_path: helperPath
-  });
-}
-
 // src/utils/managed-write-preflight.ts
 var DEFAULT_DEPS = {
   converge: (input) => runVaultSyncPullHelper(input)
 };
-function journalDir(vault) {
-  const gitPath = git(vault, ["rev-parse", "--git-path", "vault-sync/operations"]);
-  if (!gitPath) return null;
-  return gitPath.startsWith("/") ? gitPath : join3(vault, gitPath);
-}
-function findReviewRequiredOp(vault) {
-  const dir = journalDir(vault);
-  if (!dir) return void 0;
-  let files;
-  try {
-    files = readdirSync(dir).filter((f) => f.endsWith(".env"));
-  } catch {
-    return void 0;
-  }
-  const currentGitDir = git(vault, ["rev-parse", "--absolute-git-dir"]);
-  for (const file of files) {
-    let text;
-    try {
-      text = readFileSync2(join3(dir, file), "utf8");
-    } catch {
-      continue;
-    }
-    const fields = Object.fromEntries(
-      text.split("\n").filter((line) => line.includes("=")).map((line) => {
-        const i = line.indexOf("=");
-        return [line.slice(0, i), line.slice(i + 1)];
-      })
-    );
-    if (fields.phase !== "review-required" || fields.handoff !== "1") continue;
-    const journalGitDir = fields.worktree_git_dir ?? "";
-    if (!journalGitDir || !currentGitDir || journalGitDir === currentGitDir) {
-      return file.replace(/\.env$/, "");
-    }
-  }
-  return void 0;
-}
 function preflightBlocker(vault) {
-  const unmergedRaw = git(vault, ["diff", "--name-only", "--diff-filter=U"]);
-  const unmerged = unmergedRaw ? unmergedRaw.split("\n").map((s) => s.trim()).filter(Boolean) : [];
+  const unmerged = hasUnmergedPaths(vault);
   if (unmerged.length > 0) {
     return {
       reason: "unmerged-paths",
@@ -191,17 +70,10 @@ function preflightBlocker(vault) {
       unmerged_paths: unmerged
     };
   }
-  const gitDir = git(vault, ["rev-parse", "--absolute-git-dir"]);
-  if (gitDir) {
-    const markers = ["MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD"];
-    for (const m of markers) {
-      try {
-        readFileSync2(join3(gitDir, m));
-        return { reason: "git-operation-in-progress" };
-      } catch {
-      }
-    }
+  if (hasActiveGitSequencer(vault)) {
+    return { reason: "git-operation-in-progress" };
   }
+  supersedeStaleReviewRequiredJournals(vault, { by: "skillwiki-managed-write-preflight" });
   const op = findReviewRequiredOp(vault);
   if (op) return { reason: "review-required", operation_id: op };
   return null;
@@ -269,7 +141,8 @@ async function runManagedWritePreflight(input, deps = DEFAULT_DEPS) {
   const converge = await deps.converge({
     vault,
     lockToken: input.lockToken,
-    env: input.env
+    env: input.env,
+    home: input.home
   });
   if (!converge.ok) {
     const exitCode = converge.error === "PREFLIGHT_FAILED" ? ExitCode.PREFLIGHT_FAILED : ExitCode.SYNC_PULL_FAILED;
@@ -333,11 +206,8 @@ async function runManagedWriteTransaction(input, deps = DEFAULT_DEPS) {
 }
 
 export {
-  git,
-  gitStrict,
   acquireManagedWriteLock,
   releaseManagedWriteLock,
-  runVaultSyncPullHelper,
   runManagedWritePreflight,
   runManagedWriteTransaction
 };

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-DR7KFHNH.js → chunk-Z3WS45PL.js}

@@ -5,6 +5,7 @@ import {
 } from "./chunk-7I2TPIV5.js";
 import {
   atomicWriteText,
+  buildRootIndexUniverse,
   extractFrontmatter,
   mapWithConcurrency,
   prepareTypedPage,
@@ -18,18 +19,20 @@ import {
   splitFrontmatter,
   vaultIoConcurrency,
   writeRootIndexProjection
-} from "./chunk-IZABIE44.js";
+} from "./chunk-U34B2XQJ.js";
 import {
   CONFIG_KEYS,
   isValidWikiProfileKey,
+  listReviewRequiredOps,
   loadFleetManifestAndHost,
   parseDotenvFile,
   parseDotenvText,
   profileKey,
+  resolveVaultSyncPullHelper,
   satelliteGateFromFleetLoad,
   snapshotterAliasForLocalHost,
   writeDotenv
-} from "./chunk-S5ABQCXQ.js";
+} from "./chunk-R6BKJWVC.js";
 import {
   CompoundSchema,
   ExitCode,
@@ -1559,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");
@@ -1577,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 = [];
@@ -3032,6 +3035,10 @@ function buildCliSurface() {
   syncCmd.command("status").option("--wiki <name>").option("--include-stashes").option("--include-remote-health").option("--check-snapshotter");
   syncCmd.command("push").option("--wiki <name>");
   syncCmd.command("pull").option("--wiki <name>");
+  syncCmd.command("resolve-derived").option("--operation-id <id>").option("--wiki <name>");
+  const syncJournalCmd = syncCmd.command("journal");
+  syncJournalCmd.command("list").option("--wiki <name>");
+  syncJournalCmd.command("clear-stale").option("--dry-run").option("--wiki <name>");
   syncCmd.command("lock").option("--summary <text>").option("--ttl-minutes <n>").option("--force").option("--wiki <name>");
   syncCmd.command("unlock").option("--force").option("--wiki <name>");
   syncCmd.command("peers").option("--wiki <name>");
@@ -6210,6 +6217,42 @@ function checkVfsCacheHealth(resolvedPath) {
     `${stats.files} files, ${(stats.bytesUsed / 1024 / 1024).toFixed(1)}MB \u2014 clean (0 errored, 0 pending)`
   );
 }
+function checkVaultSyncPullHelper(home, env) {
+  const path = resolveVaultSyncPullHelper({
+    vault: "",
+    home,
+    env
+  });
+  if (path) {
+    return check("pass", "vault_sync_pull_helper", "Vault-sync pull helper", `Resolved: ${path}`);
+  }
+  return check(
+    "error",
+    "vault_sync_pull_helper",
+    "Vault-sync pull helper",
+    "Not found \u2014 install skillwiki@0.10.1+, redeploy vault-sync, or set SKILLWIKI_VAULT_SYNC_PULL_HELPER"
+  );
+}
+function checkVaultSyncReviewRequiredJournals(vaultPath) {
+  if (!vaultPath || !existsSync13(join24(vaultPath, ".git"))) {
+    return check("pass", "vault_sync_review_required_journals", "Review-required journals", "No git vault \u2014 check skipped");
+  }
+  try {
+    const ops = listReviewRequiredOps(vaultPath);
+    if (ops.length === 0) {
+      return check("pass", "vault_sync_review_required_journals", "Review-required journals", "None");
+    }
+    const sample = ops[0]?.opId ?? "?";
+    return check(
+      "warn",
+      "vault_sync_review_required_journals",
+      "Review-required journals",
+      `${ops.length} handoff(s); oldest/sample: ${sample} \u2014 if worktree clean: skillwiki sync journal clear-stale --dry-run`
+    );
+  } catch {
+    return check("pass", "vault_sync_review_required_journals", "Review-required journals", "Could not read journals \u2014 check skipped");
+  }
+}
 function readVaultSyncConfig(home) {
   try {
     const content = readFileSync10(join24(home, ".skillwiki", ".env"), "utf8");
@@ -6820,6 +6863,8 @@ async function runDoctor(input) {
     vaultSyncServiceScope: vsConfig.serviceScope,
     snapshotScriptPath: vsConfig.snapshotScript
   }));
+  checks.push(checkVaultSyncPullHelper(input.home, input.env ?? process.env));
+  checks.push(checkVaultSyncReviewRequiredJournals(resolvedPath));
   const satelliteGate = satelliteGateFromFleetLoad(fleetLoad);
   checks.push(checkSatelliteLastRun(resolvedPath, satelliteGate.satelliteExpected));
   checks.push(checkSatelliteTimer(satelliteGate.satelliteExpected));

package/dist/cli.js

@@ -68,7 +68,7 @@ import {
   satelliteLatestRunPath,
   taxonomyCommentForPage,
   upsertIndexEntry
-} from "./chunk-DR7KFHNH.js";
+} from "./chunk-Z3WS45PL.js";
 import {
   normalizeDistTag,
   readCache,
@@ -88,29 +88,33 @@ import {
   scanVault,
   splitFrontmatter,
   writeRootIndexProjection
-} from "./chunk-IZABIE44.js";
+} from "./chunk-U34B2XQJ.js";
 import {
   acquireManagedWriteLock,
-  git,
-  gitStrict,
   releaseManagedWriteLock,
   runManagedWritePreflight,
-  runManagedWriteTransaction,
-  runVaultSyncPullHelper
-} from "./chunk-5TBIMLTZ.js";
+  runManagedWriteTransaction
+} from "./chunk-SCGC7YNM.js";
 import {
   FLEET_REL_PATH,
+  git,
+  gitStrict,
+  listJournalOpIds,
+  listReviewRequiredOps,
   loadFleetManifest,
   loadFleetManifestAndHost,
   parseDotenvFile,
   parseDotenvText,
   profileKey,
+  readJournal,
   resolveFleetHostId,
   runFleetContext,
   runFleetValidate,
+  runVaultSyncPullHelper,
   snapshotterAliasForLocalHost,
+  supersedeStaleReviewRequiredJournals,
   writeDotenv
-} from "./chunk-S5ABQCXQ.js";
+} from "./chunk-R6BKJWVC.js";
 import {
   ExitCode,
   MetaSchema,
@@ -2529,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;
@@ -2640,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;
@@ -2990,6 +2994,30 @@ ${migratedBody}${newFooter}`;
 // src/commands/update.ts
 import { execSync } from "child_process";
 import { join as join19 } from "path";
+function parseCoreSemver(version) {
+  const m = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return null;
+  return { major: parseInt(m[1], 10), minor: parseInt(m[2], 10), patch: parseInt(m[3], 10) };
+}
+function needs0101Migration(previousVersion, newVersion) {
+  const p = parseCoreSemver(previousVersion);
+  const n = parseCoreSemver(newVersion);
+  if (!p || !n) return false;
+  const prevLt = p.major < 0 || p.major === 0 && p.minor < 10 || p.major === 0 && p.minor === 10 && p.patch < 1;
+  const newGe = n.major > 0 || n.major === 0 && n.minor > 10 || n.major === 0 && n.minor === 10 && n.patch >= 1;
+  return prevLt && newGe;
+}
+function migrationNotesForUpgrade(previousVersion, newVersion) {
+  if (!needs0101Migration(previousVersion, newVersion)) return [];
+  return [
+    "Migration 0.10.1:",
+    "- pull helper resolves from dist/ + host vault-sync install",
+    "- run: skillwiki doctor",
+    "- if managed writes blocked: skillwiki sync journal list",
+    "- then: skillwiki sync journal clear-stale --dry-run",
+    "- legacy override: SKILLWIKI_VAULT_SYNC_PULL_HELPER=<path-to-wiki-pull-with-auto-resolve.sh>"
+  ];
+}
 function resolveGlobalSkillsRoot() {
   try {
     const globalRoot = execSync("npm root -g", {
@@ -3085,6 +3113,9 @@ async function runUpdate(input) {
     hintLines.push(`version warnings: ${version_warnings.length}`);
     for (const w of version_warnings) hintLines.push(`  ${w}`);
   }
+  for (const line of migrationNotesForUpgrade(currentVersion, latest)) {
+    hintLines.push(line);
+  }
   return {
     exitCode: ExitCode.OK,
     result: ok({
@@ -5772,6 +5803,50 @@ function runSyncUnlock(input) {
   };
 }
 
+// src/commands/sync-journal.ts
+function runSyncJournalList(input) {
+  const byPhase = {};
+  for (const opId of listJournalOpIds(input.vault)) {
+    const fields = readJournal(input.vault, opId);
+    const phase = fields?.phase ?? "unknown";
+    byPhase[phase] = (byPhase[phase] ?? 0) + 1;
+  }
+  const review = listReviewRequiredOps(input.vault).map(({ opId, fields }) => ({
+    operation_id: opId,
+    reason: fields.reason,
+    target_oid: fields.target_oid,
+    original_head: fields.original_head
+  }));
+  const total = Object.values(byPhase).reduce((a, b) => a + b, 0);
+  const hint = review.length === 0 ? `journals: ${total} total; no review-required handoffs` : `journals: ${total} total; ${review.length} review-required \u2014 if worktree clean: skillwiki sync journal clear-stale --dry-run`;
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      total,
+      by_phase: byPhase,
+      review_required: review,
+      humanHint: hint
+    })
+  };
+}
+function runSyncJournalClearStale(input) {
+  const { superseded, skipped } = supersedeStaleReviewRequiredJournals(input.vault, {
+    dryRun: !!input.dryRun,
+    by: input.dryRun ? "skillwiki-sync-journal-clear-stale-dry-run" : "skillwiki-sync-journal-clear-stale"
+  });
+  const mode = input.dryRun ? "dry-run" : "write";
+  const hint = superseded.length === 0 ? `clear-stale (${mode}): nothing to supersede; skipped=${skipped.length}` : `clear-stale (${mode}): ${superseded.length} journal(s); skipped=${skipped.length}`;
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      dry_run: !!input.dryRun,
+      superseded,
+      skipped,
+      humanHint: hint
+    })
+  };
+}
+
 // src/commands/backup.ts
 import { statSync as statSync2, readdirSync, readFileSync as readFileSync11, mkdirSync as mkdirSync2, writeFileSync as writeFileSync4 } from "fs";
 import { join as join28, relative as relative2, dirname as dirname6 } from "path";
@@ -6674,7 +6749,7 @@ 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-SILEUQEV.js");
+  const { runManagedWriteTransaction: runManagedWriteTransaction2 } = await import("./managed-write-preflight-PW4OOOMV.js");
   const run = await runManagedWriteTransaction2({
     vault,
     command,
@@ -7225,6 +7300,24 @@ syncCmd.command("resolve-derived [vault]").description("resolve mixed derived co
     );
   }
 });
+var syncJournalCmd = syncCmd.command("journal").description("inspect or clear vault-sync operation journals");
+syncJournalCmd.command("list [vault]").description("list vault-sync operation journals and review-required handoffs").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 emit(runSyncJournalList({ vault: v.vault }));
+});
+syncJournalCmd.command("clear-stale [vault]").description("supersede stale review-required journals when worktree is clean").option("--dry-run", "report what would be cleared without writing", false).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.dryRun) emit(runSyncJournalClearStale({ vault: v.vault, dryRun: true }));
+  else {
+    return emitGuardedVaultWrite(
+      v.vault,
+      "sync journal clear-stale",
+      async () => runSyncJournalClearStale({ vault: v.vault, dryRun: false })
+    );
+  }
+});
 syncCmd.command("lock [vault]").description("acquire advisory lock on vault").option("--summary <text>", "lock description", "skillwiki sync").option("--ttl-minutes <n>", "lock time-to-live in minutes", "30").option("--force", "overwrite existing lock", false).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 });

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-SILEUQEV.js → managed-write-preflight-PW4OOOMV.js}

@@ -2,8 +2,8 @@
 import {
   runManagedWritePreflight,
   runManagedWriteTransaction
-} from "./chunk-5TBIMLTZ.js";
-import "./chunk-S5ABQCXQ.js";
+} from "./chunk-SCGC7YNM.js";
+import "./chunk-R6BKJWVC.js";
 import "./chunk-C5OLZRRM.js";
 export {
   runManagedWritePreflight,

package/dist/skillwiki-mcp.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   runSkillwikiMcpStdio
-} from "./chunk-DR7KFHNH.js";
+} from "./chunk-Z3WS45PL.js";
 import "./chunk-7I2TPIV5.js";
-import "./chunk-IZABIE44.js";
-import "./chunk-S5ABQCXQ.js";
+import "./chunk-U34B2XQJ.js";
+import "./chunk-R6BKJWVC.js";
 import "./chunk-C5OLZRRM.js";
 
 // src/mcp-entry.ts

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "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.0",
+  "version": "0.10.2",
   "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.0",
+  "version": "0.10.2",
   "private": true,
   "files": [
     "wiki-*",

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

@@ -80,6 +80,17 @@ path, run publisher dry-run, then run the same command with `--write`.
 
 Before a managed vault mutation, invoke the managed SkillWiki command while the draft remains outside the authoritative target path. The command resolves fleet authority, refuses existing unmerged/review-required state, converges an authorized Git writer, freezes the base OID, and only then applies the write. Do not run `git pull --rebase --autostash` after placing the authoritative change in the live worktree. Do not edit root `index.md` or root `log.md` directly; projection and log commands own those compatibility files.
 
+### Managed write / 0.10.1 migration troubleshooting
+
+After upgrading to skillwiki **≥0.10.1** (or when managed write fails):
+
+1. Run `skillwiki doctor` — checks `vault_sync_pull_helper` and `vault_sync_review_required_journals`.
+2. If pull helper is missing: install `skillwiki@0.10.1+` (helper must resolve from `dist/vault-sync/scripts/`) and/or redeploy vault-sync host install. Last-resort override: `SKILLWIKI_VAULT_SYNC_PULL_HELPER` pointing at `wiki-pull-with-auto-resolve.sh` under host vault-sync `bin/` (macOS Application Support or Linux `~/.local/share/vault-sync/bin`).
+3. If preflight reports `review-required` on a **clean** worktree: `skillwiki sync journal list`, then `skillwiki sync journal clear-stale --dry-run`, then `clear-stale` without dry-run. Preflight also auto-supersedes stale handoffs when criteria match; do not force-clear during active rebase/unmerged state.
+4. After `skillwiki update` across 0.10.1, read the printed Migration 0.10.1 notes.
+
+Also mirror these pointers in vault-presync / vault-sync-status skills when operating pull/push.
+
 - typed pages: `skillwiki page publish <draft> <vault> --target <path>` then the same command with `--write`
 - archive: `skillwiki archive <path> <vault>`
 - ad-hoc structural log: `skillwiki log-append <vault> --content '<entry>'` (Release A dual-write) or event materialization (Release B)

package/skills/using-skillwiki/SKILL.md

@@ -80,6 +80,17 @@ path, run publisher dry-run, then run the same command with `--write`.
 
 Before a managed vault mutation, invoke the managed SkillWiki command while the draft remains outside the authoritative target path. The command resolves fleet authority, refuses existing unmerged/review-required state, converges an authorized Git writer, freezes the base OID, and only then applies the write. Do not run `git pull --rebase --autostash` after placing the authoritative change in the live worktree. Do not edit root `index.md` or root `log.md` directly; projection and log commands own those compatibility files.
 
+### Managed write / 0.10.1 migration troubleshooting
+
+After upgrading to skillwiki **≥0.10.1** (or when managed write fails):
+
+1. Run `skillwiki doctor` — checks `vault_sync_pull_helper` and `vault_sync_review_required_journals`.
+2. If pull helper is missing: install `skillwiki@0.10.1+` (helper must resolve from `dist/vault-sync/scripts/`) and/or redeploy vault-sync host install. Last-resort override: `SKILLWIKI_VAULT_SYNC_PULL_HELPER` pointing at `wiki-pull-with-auto-resolve.sh` under host vault-sync `bin/` (macOS Application Support or Linux `~/.local/share/vault-sync/bin`).
+3. If preflight reports `review-required` on a **clean** worktree: `skillwiki sync journal list`, then `skillwiki sync journal clear-stale --dry-run`, then `clear-stale` without dry-run. Preflight also auto-supersedes stale handoffs when criteria match; do not force-clear during active rebase/unmerged state.
+4. After `skillwiki update` across 0.10.1, read the printed Migration 0.10.1 notes.
+
+Also mirror these pointers in vault-presync / vault-sync-status skills when operating pull/push.
+
 - typed pages: `skillwiki page publish <draft> <vault> --target <path>` then the same command with `--write`
 - archive: `skillwiki archive <path> <vault>`
 - ad-hoc structural log: `skillwiki log-append <vault> --content '<entry>'` (Release A dual-write) or event materialization (Release B)