skillwiki 0.9.33 → 0.9.35

package/dist/{chunk-OPXMAS4O.js → chunk-TK4ZIQNE.js}

@@ -63,7 +63,8 @@ var ExitCode = {
   LOG_APPEND_LOCK_HELD: 49,
   FLEET_MANIFEST_INVALID: 50,
   SENSITIVE_CONTENT_DETECTED: 51,
-  FLEET_SATELLITE_HEALTH_FAILED: 52
+  FLEET_SATELLITE_HEALTH_FAILED: 52,
+  PROTECTED_SNAPSHOTTER_WRITE_BLOCKED: 53
 };
 
 // ../shared/src/json-output.ts
@@ -152,6 +153,26 @@ var CompoundSchema = z.object({
   promoted_to: wikilink.optional(),
   cssclasses: z.array(z.string()).optional()
 });
+var sessionPinPath = z.string().regex(
+  /^(entities|concepts|comparisons|queries|meta)\/.+\.md$/,
+  "must reference a typed-knowledge markdown page"
+);
+var SessionPinSchema = z.object({
+  title: z.string().min(1),
+  path: sessionPinPath,
+  scope: z.enum(["global", "project"]),
+  project: wikilink.optional(),
+  summary: z.string().min(1).optional(),
+  updated: isoDate.optional()
+}).superRefine((v, ctx) => {
+  if (v.scope === "project" && v.project === void 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["project"],
+      message: "project is required when scope is project"
+    });
+  }
+});
 var MetaSchema = z.object({
   title: z.string().min(1),
   aliases: z.array(z.string()).optional(),
@@ -164,9 +185,17 @@ var MetaSchema = z.object({
   provenance_projects: z.array(wikilink).optional(),
   generated_by: z.string().min(1).optional(),
   generated_at: z.string().datetime().optional(),
-  generated_kind: z.enum(["session-brief"]).optional()
+  generated_kind: z.enum(["session-brief"]).optional(),
+  meta_kind: z.enum(["session-pins"]).optional(),
+  stale_ttl: z.number().int().positive().optional(),
+  pins: z.array(SessionPinSchema).optional()
 }).superRefine((v, ctx) => {
-  if (v.generated_kind !== "session-brief" && (!v.provenance_projects || v.provenance_projects.length < 2)) {
+  const isGeneratedSessionBrief = v.generated_kind === "session-brief";
+  const isSessionPins = v.meta_kind === "session-pins";
+  if (isSessionPins && (!v.pins || v.pins.length === 0)) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["pins"], message: "required when meta_kind is session-pins" });
+  }
+  if (!isGeneratedSessionBrief && !isSessionPins && (!v.provenance_projects || v.provenance_projects.length < 2)) {
     ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["provenance_projects"], message: "meta pages must reference \u22652 projects" });
   }
   if (v.provenance && v.provenance !== "research" && (!v.provenance_projects || v.provenance_projects.length === 0)) {
@@ -4370,7 +4399,7 @@ function formatKnownContext(input) {
   const selfAliases = collectSelfAliases(input.manifest, input.hostId);
   const outbound = collectOutboundAccess(input.manifest, input.hostId);
   const maintenanceLines = formatMaintenanceLines(host);
-  const guidance = input.hostId === "macos-dev" ? "use declared SSH aliases for remote work when needed; do not assume undeclared hosts have reciprocal SSH access." : `this session is already on \`${input.hostId}\`; do not SSH to self aliases unless the user explicitly asks. Do not assume outbound SSH to other fleet hosts is configured.`;
+  const guidance = host.role === "snapshotter" && host.protected === true ? `this session is already on \`${input.hostId}\`; this is a protected snapshotter host. Do not mutate the vault or repo-local project workspaces from this session except explicitly approved snapshot maintenance. Use read-only investigation here and route authoring to a leaf host.` : input.hostId === "macos-dev" ? "use declared SSH aliases for remote work when needed; do not assume undeclared hosts have reciprocal SSH access." : `this session is already on \`${input.hostId}\`; do not SSH to self aliases unless the user explicitly asks. Do not assume outbound SSH to other fleet hosts is configured.`;
   return [
     "## Runtime Host Context",
     "",
@@ -8848,6 +8877,7 @@ export {
   ok,
   err,
   TypedKnowledgeSchema,
+  MetaSchema,
   detectSchema,
   isBlockedHost,
   splitFrontmatter,
@@ -8899,6 +8929,7 @@ export {
   FLEET_REL_PATH,
   runFleetValidate,
   runFleetContext,
+  loadFleetManifestAndHost,
   loadFleetManifest,
   resolveFleetHostId,
   SATELLITE_STALE_MS,

package/dist/cli.js

@@ -2,6 +2,7 @@
 import {
   ExitCode,
   FLEET_REL_PATH,
+  MetaSchema,
   SATELLITE_STALE_MS,
   TypedKnowledgeSchema,
   appendLastOp,
@@ -21,6 +22,7 @@ import {
   isFailedRunStatus,
   isValidRemoteDeleteCap,
   loadFleetManifest,
+  loadFleetManifestAndHost,
   normalizeRemoteRoot,
   ok,
   parseDotenvFile,
@@ -73,7 +75,7 @@ import {
   triggerAutoUpdate,
   writeCache,
   writeDotenv
-} from "./chunk-OPXMAS4O.js";
+} from "./chunk-TK4ZIQNE.js";
 import {
   normalizeDistTag
 } from "./chunk-E6UWZ3S3.js";
@@ -2386,14 +2388,27 @@ async function runSessionBrief(input) {
   const today = generatedAt.slice(0, 10);
   const project = await resolveProject(input);
   try {
-    const transcripts = await loadTranscriptInfo(scan.data.raw);
-    const workItems = await loadWorkItems(scan.data.workItems);
-    const digests = await loadTrendDigests(scan.data.typedKnowledge);
+    const [
+      transcripts,
+      workItems,
+      digests,
+      baseHealthWarnings,
+      satelliteHealth,
+      sessionPins,
+      memoryTopics
+    ] = await Promise.all([
+      loadTranscriptInfo(scan.data.raw),
+      loadWorkItems(scan.data.workItems),
+      loadTrendDigests(scan.data.typedKnowledge),
+      loadHealthWarnings(input.vault),
+      loadSatelliteHealth(input.vault),
+      loadSessionPins(input.vault, project),
+      project ? loadMemoryTopics(input.vault, project) : Promise.resolve([])
+    ]);
     const healthWarnings = [
-      ...await loadHealthWarnings(input.vault),
-      ...satelliteHealthWarnings(await loadSatelliteHealth(input.vault))
+      ...baseHealthWarnings,
+      ...satelliteHealthWarnings(satelliteHealth)
     ];
-    const memoryTopics = project ? await loadMemoryTopics(input.vault, project) : [];
     const latestLogs = newest(transcripts.filter((t) => t.kind === "session-log"), 3);
     const unclaimedCaptures = newest(transcripts.filter((t) => {
       if (t.kind !== "task" && t.kind !== "bug") return false;
@@ -2408,6 +2423,7 @@ async function runSessionBrief(input) {
     const brief = capWords(renderBrief({
       project,
       generatedAt,
+      sessionPins,
       latestLogs,
       unclaimedCaptures,
       activeWork,
@@ -2443,6 +2459,7 @@ async function runSessionBrief(input) {
         index_updated: indexUpdated,
         log_updated: logUpdated,
         generated_at: generatedAt,
+        session_pins: sessionPins,
         memory_topics: memoryTopics,
         humanHint
       })
@@ -2544,6 +2561,29 @@ async function loadTrendDigests(typedPages) {
   }
   return out;
 }
+async function loadSessionPins(vault, project) {
+  const text = await readIfExists(join15(vault, "meta", "session-pins.md"));
+  if (!text) return [];
+  const fm = extractFrontmatter(text);
+  if (!fm.ok) return [];
+  const parsed = MetaSchema.safeParse(fm.data);
+  if (!parsed.success || parsed.data.meta_kind !== "session-pins") return [];
+  const registryUpdated = parsed.data.updated;
+  const out = [];
+  for (const pin of parsed.data.pins ?? []) {
+    const pinProject = wikilinkSlug(pin.project);
+    if (pin.scope === "project" && (!project || pinProject !== project)) continue;
+    out.push({
+      path: pin.path,
+      title: pin.title,
+      summary: pin.summary ?? "",
+      date: pin.updated ?? registryUpdated,
+      project: pinProject,
+      kind: "session-pin"
+    });
+  }
+  return newest(out, 5);
+}
 function renderBrief(input) {
   const lines = [
     "# Session Brief",
@@ -2552,6 +2592,7 @@ function renderBrief(input) {
     `Scope: ${input.project ? `[[${input.project}]] plus global context` : "global context"}`,
     ""
   ];
+  appendPinnedContextSection(lines, input.sessionPins);
   appendSection(lines, "Active Work", input.activeWork, "No active project work found.");
   appendSection(lines, "Unclaimed Captures", input.unclaimedCaptures, "No unclaimed task or bug captures found.");
   appendSection(lines, "Recent Session Logs", input.project ? input.projectLogs : input.latestLogs, "No recent session logs found.");
@@ -2577,6 +2618,16 @@ function appendMemoryTopicsSection(lines, project, topics) {
   }
   lines.push("");
 }
+function appendPinnedContextSection(lines, pins) {
+  if (pins.length === 0) return;
+  lines.push("## Pinned Context", "");
+  for (const pin of pins) {
+    const date = pin.date ? `${pin.date} ` : "";
+    const summary = pin.summary ? ` \u2014 ${pin.summary}` : "";
+    lines.push(`- ${date}${pin.title} (${pin.path})${summary}`);
+  }
+  lines.push("");
+}
 function appendSection(lines, title, items, empty) {
   lines.push(`## ${title}`, "");
   if (items.length === 0) {
@@ -4704,6 +4755,36 @@ async function postCommit(vault, exitCode) {
   clearLastOp(vault);
 }
 
+// src/utils/protected-vault-write-guard.ts
+async function guardProtectedVaultWrite(input) {
+  const load = await loadFleetManifestAndHost({
+    vault: input.vault,
+    hostId: input.hostId,
+    env: input.env ?? process.env,
+    home: input.home ?? process.env.HOME ?? "",
+    cwd: input.cwd ?? process.cwd(),
+    osHostname: input.osHostname ?? process.env.HOSTNAME,
+    user: input.user ?? process.env.USER
+  });
+  if (!load?.hostId || load.identityStatus !== "known") {
+    return { blocked: false };
+  }
+  const host = load.manifest.hosts[load.hostId];
+  if (!host || host.role !== "snapshotter" || host.protected !== true) {
+    return { blocked: false };
+  }
+  return {
+    blocked: true,
+    exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED,
+    result: err("PROTECTED_SNAPSHOTTER_WRITE_BLOCKED", {
+      host_id: load.hostId,
+      command: input.command,
+      reason: `refusing vault mutation from protected snapshotter host '${load.hostId}'`,
+      guidance: "Use a leaf authoring host for vault/project writes. Keep protected snapshotter sessions read-only except explicit snapshot maintenance."
+    })
+  };
+}
+
 // src/cli.ts
 var pkg = readCliPackageJson();
 var program = new Command();
@@ -4715,6 +4796,21 @@ async function emit(r, vault, opts) {
   if (vault && opts?.postCommit !== false) await postCommit(vault, r.exitCode);
   process.exit(r.exitCode);
 }
+async function emitGuardedVaultWrite(vault, command, run, opts) {
+  const guard = await guardProtectedVaultWrite({
+    vault,
+    command,
+    env: process.env,
+    home: process.env.HOME ?? "",
+    cwd: process.cwd(),
+    osHostname: process.env.HOSTNAME,
+    user: process.env.USER
+  });
+  if (guard.blocked) {
+    return emit({ exitCode: guard.exitCode, result: guard.result }, void 0, { postCommit: false });
+  }
+  return emit(await run(), vault, opts);
+}
 program.command("hash <file>").description("compute SHA-256 hash of a vault page body").action(async (file) => emit(await runHash({ file })));
 program.command("fetch-guard <url>").description("check if a URL passes fetch guard rules and sanitize secrets").action(async (url) => emit(await runFetchGuard({ url })));
 program.command("validate <file>").description("validate vault page frontmatter against its detected schema").option("--apply", "auto-update vault index.md and log.md after successful validation", false).option("--vault <dir>", "vault root directory (required with --apply)").option("--wiki <name>", "wiki profile name").action(async (file, opts) => {
@@ -4724,17 +4820,20 @@ program.command("validate <file>").description("validate vault page frontmatter
     if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
     else vault = v.vault;
   }
+  if (opts.apply && vault) {
+    return emitGuardedVaultWrite(vault, "validate --apply", () => runValidate({ file, apply: true, vault }), void 0);
+  }
   emit(await runValidate({ file, apply: !!opts.apply, vault }), vault);
 });
 program.command("graph").description("graph subcommands").command("build <vault>").option("--out <path>", "graph output path (default: <vault>/.skillwiki/graph.json)").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const out = opts.out ?? join25(vault, ".skillwiki", "graph.json");
-  emit(await runGraphBuild({ vault, out }), vault);
+  return emitGuardedVaultWrite(vault, "graph build", () => runGraphBuild({ vault, out }));
 });
 var canvasCmd = program.command("canvas").description("manage Obsidian canvas files");
 canvasCmd.command("generate [vault]").description("generate .canvas from graph.json").option("--graph-path <path>", "explicit path to graph.json").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(await runCanvasGenerate({ vault: v.vault, graphPath: opts.graphPath }), v.vault);
+  else return emitGuardedVaultWrite(v.vault, "canvas generate", () => runCanvasGenerate({ vault: v.vault, graphPath: opts.graphPath }));
 });
 program.command("overlap [vault]").description("detect typed-knowledge pages that share the same raw sources").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
@@ -4836,12 +4935,21 @@ program.command("topic-map-check [vault]").description("check whether a topic ma
 program.command("stale [vault]").description("identify stale transcripts and incomplete work items").option("--archive", "move stale items to _archive/", false).option("--days <n>", "staleness threshold in days", (s) => parseInt(s, 10), 3).option("--force-scan", "infer kind/project from filename and content when frontmatter is missing", false).option("--project <slug>", "scope to a single project").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(await runStale({ vault: v.vault, days: opts.days, archive: !!opts.archive, forceScan: !!opts.forceScan, project: opts.project }), v.vault);
+  else if (opts.archive) return emitGuardedVaultWrite(
+    v.vault,
+    "stale --archive",
+    () => runStale({ vault: v.vault, days: opts.days, archive: true, forceScan: !!opts.forceScan, project: opts.project })
+  );
+  else emit(await runStale({ vault: v.vault, days: opts.days, archive: false, forceScan: !!opts.forceScan, project: opts.project }), v.vault);
 });
 program.command("claim <transcript> [vault]").description("claim an unclaimed transcript by creating a work item with source: link").option("--project <slug>", "project slug (overrides transcript frontmatter)").option("--slug <slug>", "work-item slug (defaults to transcript filename without date/kind prefix)").option("--wiki <name>", "wiki profile name").action(async (transcript, vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
-  else emit(await runClaim({ vault: v.vault, transcript, project: opts.project, slug: opts.slug }), v.vault);
+  else return emitGuardedVaultWrite(
+    v.vault,
+    "claim",
+    () => runClaim({ vault: v.vault, transcript, project: opts.project, slug: opts.slug })
+  );
 });
 program.command("pagesize [vault]").description("report page sizes and flag oversized pages").option("--lines <n>", "max body lines", (s) => parseInt(s, 10), 200).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
@@ -4851,23 +4959,47 @@ program.command("pagesize [vault]").description("report page sizes and flag over
 program.command("log-rotate [vault]").description("rotate or trim the vault log file").option("--threshold <n>", "entry count threshold", (s) => parseInt(s, 10), 500).option("--apply", "actually rotate", 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 emit(await runLogRotate({ vault: v.vault, threshold: opts.threshold, apply: !!opts.apply }), v.vault);
+  else if (opts.apply) return emitGuardedVaultWrite(
+    v.vault,
+    "log-rotate --apply",
+    () => runLogRotate({ vault: v.vault, threshold: opts.threshold, apply: true })
+  );
+  else emit(await runLogRotate({ vault: v.vault, threshold: opts.threshold, apply: false }), v.vault);
 });
 program.command("log-append [vault]").description("append a single entry to the vault log under a short advisory lock").requiredOption("--content <text>", "log entry text to append").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(await runLogAppend({ vault: v.vault, content: opts.content }), v.vault);
+  else return emitGuardedVaultWrite(
+    v.vault,
+    "log-append",
+    () => runLogAppend({ vault: v.vault, content: opts.content })
+  );
 });
 program.command("lint [vault]").description("run all vault health checks").option("--days <n>", "stale threshold", (s) => parseInt(s, 10), 90).option("--lines <n>", "pagesize threshold", (s) => parseInt(s, 10), 200).option("--log-threshold <n>", "log rotation threshold", (s) => parseInt(s, 10), 500).option("--fix", "auto-fix supported lint violations").option("--only <bucket>", "run only the specified lint bucket").option("--summary", "emit bounded bucket counts instead of full item arrays", false).option("--examples <n>", "example count per bucket in summary mode", (s) => parseInt(s, 10), 3).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.fix) return emitGuardedVaultWrite(
+    v.vault,
+    "lint --fix",
+    () => runLint({
+      vault: v.vault,
+      source: vault ? "flag" : void 0,
+      days: opts.days,
+      lines: opts.lines,
+      logThreshold: opts.logThreshold,
+      fix: true,
+      only: opts.only,
+      summary: !!opts.summary,
+      examplesLimit: opts.summary ? opts.examples : void 0
+    })
+  );
   else if (opts.summary) emit(await runLint({
     vault: v.vault,
     source: vault ? "flag" : void 0,
     days: opts.days,
     lines: opts.lines,
     logThreshold: opts.logThreshold,
-    fix: opts.fix ?? false,
+    fix: false,
     only: opts.only,
     summary: true,
     examplesLimit: opts.examples
@@ -4878,7 +5010,7 @@ program.command("lint [vault]").description("run all vault health checks").optio
     days: opts.days,
     lines: opts.lines,
     logThreshold: opts.logThreshold,
-    fix: opts.fix ?? false,
+    fix: false,
     only: opts.only
   }), v.vault);
 });
@@ -4927,24 +5059,56 @@ program.command("status [vault]").description("output vault diagnostics").option
 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("--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) => {
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
-  else emit(await runArchive({
+  else if (opts.cascade && !opts.apply) emit(await runArchive({
     vault: v.vault,
     page,
-    cascade: !!opts.cascade,
-    apply: !!opts.apply,
+    cascade: true,
+    apply: false,
     remote: opts.remote,
     remoteDelete: !!opts.remoteDelete,
     maxRemoteDeletes: Number.parseInt(opts.maxRemoteDeletes, 10)
   }), v.vault);
+  else return emitGuardedVaultWrite(
+    v.vault,
+    "archive",
+    () => runArchive({
+      vault: v.vault,
+      page,
+      cascade: !!opts.cascade,
+      apply: !!opts.apply,
+      remote: opts.remote,
+      remoteDelete: !!opts.remoteDelete,
+      maxRemoteDeletes: Number.parseInt(opts.maxRemoteDeletes, 10)
+    })
+  );
 });
 program.command("drift [vault]").description("detect content drift in raw sources").option("--apply", "update sha256 in drifted sources").option("--new <date>", "list raw files ingested on/after this date (YYYY-MM-DD)").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(await runDrift({ vault: v.vault, apply: opts.apply, newSince: opts.new }), v.vault);
+  else if (opts.apply) return emitGuardedVaultWrite(
+    v.vault,
+    "drift --apply",
+    () => runDrift({ vault: v.vault, apply: true, newSince: opts.new })
+  );
+  else emit(await runDrift({ vault: v.vault, apply: false, newSince: opts.new }), v.vault);
 });
 program.command("dedup [vault]").description("detect duplicate raw sources by sha256").option("--apply", "rewire citations and remove duplicate raw files", false).option("--canonical-policy <policy>", "canonical policy: stable-path or scan-order", "stable-path").option("--manifest-out <path>", "write raw dedup delete manifest before applying").option("--manifest-in <path>", "read existing raw dedup delete manifest for remote pruning").option("--remote <remote>", "rclone remote root, for example seaweed-wiki:cloud/wiki").option("--remote-delete", "delete manifest duplicate paths from the remote", false).option("--max-remote-deletes <n>", "maximum remote object deletes allowed", "50").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.apply || opts.manifestOut) return emitGuardedVaultWrite(
+    v.vault,
+    opts.apply ? "dedup --apply" : "dedup --manifest-out",
+    () => runDedup({
+      vault: v.vault,
+      apply: opts.apply,
+      canonicalPolicy: opts.canonicalPolicy,
+      manifestOut: opts.manifestOut,
+      manifestIn: opts.manifestIn,
+      remote: opts.remote,
+      remoteDelete: !!opts.remoteDelete,
+      maxRemoteDeletes: Number.parseInt(opts.maxRemoteDeletes, 10)
+    })
+  );
   else emit(await runDedup({
     vault: v.vault,
     apply: opts.apply,
@@ -4959,12 +5123,22 @@ program.command("dedup [vault]").description("detect duplicate raw sources by sh
 program.command("migrate-citations [vault]").description("migrate ^[raw/...] markers to paragraph-end citations").option("--dry-run", "preview changes 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 emit(await runMigrateCitations({ vault: v.vault, dryRun: !!opts.dryRun }), v.vault);
+  else if (opts.dryRun) emit(await runMigrateCitations({ vault: v.vault, dryRun: true }), v.vault);
+  else return emitGuardedVaultWrite(
+    v.vault,
+    "migrate-citations",
+    () => runMigrateCitations({ vault: v.vault, dryRun: false })
+  );
 });
 program.command("frontmatter-fix [vault]").description("fix common frontmatter issues on typed-knowledge pages").option("--dry-run", "preview changes 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 emit(await runFrontmatterFix({ vault: v.vault, dryRun: !!opts.dryRun }), v.vault);
+  else if (opts.dryRun) emit(await runFrontmatterFix({ vault: v.vault, dryRun: true }), v.vault);
+  else return emitGuardedVaultWrite(
+    v.vault,
+    "frontmatter-fix",
+    () => runFrontmatterFix({ vault: v.vault, dryRun: false })
+  );
 });
 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 ?? "",
@@ -4983,13 +5157,23 @@ program.command("transcripts [vault]").description("list transcript files in raw
 program.command("project-index <slug> [vault]").description("generate a knowledge index for a project workspace").option("--apply", "write knowledge.md to the project directory", false).option("--wiki <name>", "wiki profile name").action(async (slug, vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
-  else emit(await runProjectIndex({ vault: v.vault, slug, apply: !!opts.apply }), v.vault);
+  else if (opts.apply) return emitGuardedVaultWrite(
+    v.vault,
+    "project-index --apply",
+    () => runProjectIndex({ vault: v.vault, slug, apply: true })
+  );
+  else emit(await runProjectIndex({ vault: v.vault, slug, apply: false }), v.vault);
 });
 var compoundCmd = program.command("compound").description("manage project compound entries");
 compoundCmd.command("promote [vault]").description("promote retros with Generalize?: yes to compound entries").requiredOption("--project <slug>", "project slug (e.g., llm-wiki)").option("--dry-run", "preview promotions without writing files", 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 emit(await runCompound({ vault: v.vault, project: opts.project, dryRun: !!opts.dryRun }), v.vault);
+  else if (opts.dryRun) emit(await runCompound({ vault: v.vault, project: opts.project, dryRun: true }), v.vault);
+  else return emitGuardedVaultWrite(
+    v.vault,
+    "compound promote",
+    () => runCompound({ vault: v.vault, project: opts.project, dryRun: false })
+  );
 });
 compoundCmd.command("list [vault]").description("list compound entries for a project").requiredOption("--project <slug>", "project slug (e.g., llm-wiki)").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
@@ -4999,12 +5183,21 @@ compoundCmd.command("list [vault]").description("list compound entries for a pro
 compoundCmd.command("delete <entry> [vault]").description("delete a compound entry and regenerate knowledge index").requiredOption("--project <slug>", "project slug (e.g., llm-wiki)").option("--wiki <name>", "wiki profile name").action(async (entry, vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
-  else emit(await runCompoundDelete({ vault: v.vault, project: opts.project, entry }), v.vault);
+  else return emitGuardedVaultWrite(
+    v.vault,
+    "compound delete",
+    () => runCompoundDelete({ vault: v.vault, project: opts.project, entry })
+  );
 });
 program.command("tag-sync [vault]").description("mirror frontmatter enum values to nested Obsidian tags").option("--dry-run", "preview changes 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 emit(await runTagSync({ vault: v.vault, dryRun: !!opts.dryRun }), v.vault);
+  else if (opts.dryRun) emit(await runTagSync({ vault: v.vault, dryRun: true }), v.vault);
+  else return emitGuardedVaultWrite(
+    v.vault,
+    "tag-sync",
+    () => runTagSync({ vault: v.vault, dryRun: false })
+  );
 });
 var syncCmd = program.command("sync").description("manage vault sync");
 syncCmd.command("status [vault]").description("check vault git sync status").option("--wiki <name>", "wiki profile name").option("--include-stashes", "enumerate all stashes in output", false).action(async (vault, opts) => {
@@ -5015,25 +5208,41 @@ syncCmd.command("status [vault]").description("check vault git sync status").opt
 syncCmd.command("push [vault]").description("lint, commit, and push vault changes to remote").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(await runSyncPush({ vault: v.vault }));
+  else return emitGuardedVaultWrite(
+    v.vault,
+    "sync push",
+    () => runSyncPush({ vault: v.vault })
+  );
 });
 syncCmd.command("pull [vault]").description("pull remote vault changes and lint").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(await runSyncPull({ vault: v.vault }), v.vault);
+  else return emitGuardedVaultWrite(
+    v.vault,
+    "sync pull",
+    () => runSyncPull({ vault: v.vault })
+  );
 });
 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 });
   else {
     const ttl = parseInt(opts.ttlMinutes, 10) || 30;
-    emit(runSyncLock({ vault: v.vault, summary: opts.summary, ttlMinutes: ttl, force: !!opts.force, sessionId: getCliSessionId() }));
+    return emitGuardedVaultWrite(
+      v.vault,
+      "sync lock",
+      async () => runSyncLock({ vault: v.vault, summary: opts.summary, ttlMinutes: ttl, force: !!opts.force, sessionId: getCliSessionId() })
+    );
   }
 });
 syncCmd.command("unlock [vault]").description("release advisory lock on vault").option("--force", "release lock regardless of holder", 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 emit(runSyncUnlock({ vault: v.vault, force: !!opts.force, sessionId: getCliSessionId() }));
+  else return emitGuardedVaultWrite(
+    v.vault,
+    "sync unlock",
+    async () => runSyncUnlock({ vault: v.vault, force: !!opts.force, sessionId: getCliSessionId() })
+  );
 });
 syncCmd.command("peers [vault]").description("list active locks and recent wiki-sync stashes").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
@@ -5068,41 +5277,65 @@ backupCmd.command("restore [vault]").description("restore vault from S3-compatib
   }
   const home = process.env.HOME ?? process.env.USERPROFILE ?? "/tmp";
   const dotenv = await parseDotenvFile(configPath(home));
-  emit(await runBackupRestore({
-    vault: v.vault,
-    bucket: opts.bucket ?? dotenv["BACKUP_BUCKET"] ?? "",
-    endpoint: opts.endpoint ?? dotenv["BACKUP_ENDPOINT"] ?? "",
-    region: opts.region ?? dotenv["BACKUP_REGION"] ?? "us-east-1",
-    accessKeyId: dotenv["BACKUP_ACCESS_KEY_ID"] ?? "",
-    secretAccessKey: dotenv["BACKUP_SECRET_ACCESS_KEY"] ?? "",
-    target: opts.target
-  }), v.vault);
+  return emitGuardedVaultWrite(
+    v.vault,
+    "backup restore",
+    () => runBackupRestore({
+      vault: v.vault,
+      bucket: opts.bucket ?? dotenv["BACKUP_BUCKET"] ?? "",
+      endpoint: opts.endpoint ?? dotenv["BACKUP_ENDPOINT"] ?? "",
+      region: opts.region ?? dotenv["BACKUP_REGION"] ?? "us-east-1",
+      accessKeyId: dotenv["BACKUP_ACCESS_KEY_ID"] ?? "",
+      secretAccessKey: dotenv["BACKUP_SECRET_ACCESS_KEY"] ?? "",
+      target: opts.target
+    })
+  );
 });
 program.command("seed [vault]").description("populate a vault with example content").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(await runSeed({ vault: v.vault }), v.vault);
+  else return emitGuardedVaultWrite(
+    v.vault,
+    "seed",
+    () => runSeed({ vault: v.vault })
+  );
 });
 program.command("observe [vault]").description("create a raw transcript observation entry").requiredOption("--text <text>", "observation text").option("--kind <kind>", "observation kind (note|bug|task|idea|session-log)", "task").option("--project <slug>", "associated project slug (required for task/bug claim detection)").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(await runObserve({
-    vault: v.vault,
-    text: opts.text,
-    kind: opts.kind,
-    project: opts.project
-  }), v.vault);
+  else return emitGuardedVaultWrite(
+    v.vault,
+    "observe",
+    () => runObserve({
+      vault: v.vault,
+      text: opts.text,
+      kind: opts.kind,
+      project: opts.project
+    })
+  );
 });
 program.command("session-brief [vault]").description("render or refresh the bounded startup session brief").option("--project <slug>", "project slug, or auto for deterministic detection", "auto").option("--write", "write meta/latest-session-brief.md and local cache files", 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.write) return emitGuardedVaultWrite(
+    v.vault,
+    "session-brief --write",
+    () => runSessionBrief({
+      vault: v.vault,
+      project: opts.project,
+      write: true,
+      cwd: process.cwd(),
+      env: { SKILLWIKI_PROJECT: process.env.SKILLWIKI_PROJECT }
+    }),
+    { postCommit: true }
+  );
   else emit(await runSessionBrief({
     vault: v.vault,
     project: opts.project,
-    write: !!opts.write,
+    write: false,
     cwd: process.cwd(),
     env: { SKILLWIKI_PROJECT: process.env.SKILLWIKI_PROJECT }
-  }), v.vault, { postCommit: !!opts.write });
+  }), v.vault, { postCommit: false });
 });
 var memoryCmd = program.command("memory").description("inspect derived agent memory caches");
 memoryCmd.command("topics [vault]").description("list topic-oriented memory from the optional derived cache").option("--project <slug>", "filter topics by project slug").option("--limit <n>", "maximum topics to return", (s) => parseInt(s, 10), 10).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
@@ -5117,12 +5350,23 @@ memoryCmd.command("topics [vault]").description("list topic-oriented memory from
 memoryCmd.command("index [vault]").description("build the derived project memory topic cache").requiredOption("--project <slug>", "project slug").option("--check", "report whether the local project memory cache is missing or stale without writing", false).option("--if-stale", "rebuild the local project memory cache only when it is missing or stale", 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 emit(await runMemoryIndex({
+  else if (opts.check) emit(await runMemoryIndex({
     vault: v.vault,
     project: opts.project,
-    check: !!opts.check,
+    check: true,
     ifStale: !!opts.ifStale
-  }), v.vault, { postCommit: !opts.check });
+  }), v.vault, { postCommit: false });
+  else return emitGuardedVaultWrite(
+    v.vault,
+    opts.ifStale ? "memory index --if-stale" : "memory index",
+    () => runMemoryIndex({
+      vault: v.vault,
+      project: opts.project,
+      check: false,
+      ifStale: !!opts.ifStale
+    }),
+    { postCommit: true }
+  );
 });
 memoryCmd.command("recall [vault]").description("recall bounded source summaries for a memory topic").requiredOption("--project <slug>", "project slug").requiredOption("--topic <slug>", "memory topic slug").option("--scope <scope>", "memory scope: project, global, cross-agent, or all").option("--limit <n>", "maximum sources to return", (s) => parseInt(s, 10), 10).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
@@ -5148,25 +5392,53 @@ memoryCmd.command("review [vault]").description("review deterministic memory gap
 memoryCmd.command("import [vault]").description("preview or apply local memory imports into raw captures").requiredOption("--from <path>", "source file or directory to scan").requiredOption("--project <slug>", "project slug").option("--dry-run", "preview only; do not write captures", false).option("--apply", "write validated raw captures for ready entries", false).option("--max-bytes <n>", "reject source files above this size", (s) => parseInt(s, 10), 2e5).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.apply && !opts.dryRun) return emitGuardedVaultWrite(
+    v.vault,
+    "memory import --apply",
+    () => runMemoryImport({
+      vault: v.vault,
+      from: opts.from,
+      project: opts.project,
+      apply: true,
+      maxBytes: opts.maxBytes
+    }),
+    { postCommit: true }
+  );
   else emit(await runMemoryImport({
     vault: v.vault,
     from: opts.from,
     project: opts.project,
-    apply: !!opts.apply && !opts.dryRun,
+    apply: false,
     maxBytes: opts.maxBytes
-  }), v.vault, { postCommit: !!opts.apply && !opts.dryRun });
+  }), v.vault, { postCommit: false });
 });
 program.command("ingest <source>").description("ingest a source URL or local file into the vault").requiredOption("--vault <path>", "vault root directory").requiredOption("--type <type>", "typed-knowledge type (entity|concept|comparison|query)").requiredOption("--title <title>", "page title").option("--tags <csv>", "comma-separated tags").option("--provenance <provenance>", "provenance (research|project)").option("--dry-run", "preview without writing files", false).action(async (source, opts) => {
   const tags = typeof opts.tags === "string" ? opts.tags.split(",").map((s) => s.trim()).filter((s) => s.length > 0) : [];
-  emit(await runIngest({
-    source,
-    vault: opts.vault,
-    type: opts.type,
-    title: opts.title,
-    tags,
-    provenance: opts.provenance,
-    dryRun: !!opts.dryRun
-  }), opts.vault);
+  if (opts.dryRun) {
+    emit(await runIngest({
+      source,
+      vault: opts.vault,
+      type: opts.type,
+      title: opts.title,
+      tags,
+      provenance: opts.provenance,
+      dryRun: true
+    }), opts.vault);
+    return;
+  }
+  return emitGuardedVaultWrite(
+    opts.vault,
+    "ingest",
+    () => runIngest({
+      source,
+      vault: opts.vault,
+      type: opts.type,
+      title: opts.title,
+      tags,
+      provenance: opts.provenance,
+      dryRun: false
+    })
+  );
 });
 var fleetCmd = program.command("fleet").description("manage fleet topology metadata");
 fleetCmd.command("validate <file>").description("validate a fleet manifest").action(async (file) => {

package/dist/skillwiki-mcp.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runSkillwikiMcpStdio
-} from "./chunk-OPXMAS4O.js";
+} from "./chunk-TK4ZIQNE.js";
 import "./chunk-E6UWZ3S3.js";
 
 // src/mcp-entry.ts

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.9.33",
+  "version": "0.9.35",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 18 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.9.33",
+  "version": "0.9.35",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 18 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.9.33",
+  "version": "0.9.35",
   "private": true,
   "files": [
     "wiki-*",