skillwiki 0.9.37 → 0.9.39

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

@@ -1110,7 +1110,13 @@ async function runOrphans(input) {
   if (input.vault) {
     vault = input.vault;
   } else {
-    const r = await resolveRuntimePath({ flag: void 0, envValue: input.envValue, home: input.home ?? "", wiki: input.wiki });
+    const r = await resolveRuntimePath({
+      flag: void 0,
+      envValue: input.envValue,
+      home: input.home ?? "",
+      wiki: input.wiki,
+      cwd: input.cwd
+    });
     if (!r.ok) {
       const exitCode = r.error === "UNKNOWN_WIKI_PROFILE" ? ExitCode.UNKNOWN_WIKI_PROFILE : ExitCode.NO_VAULT_CONFIGURED;
       return { exitCode, result: r };
@@ -4399,7 +4405,7 @@ function formatKnownContext(input) {
   const selfAliases = collectSelfAliases(input.manifest, input.hostId);
   const outbound = collectOutboundAccess(input.manifest, input.hostId);
   const maintenanceLines = formatMaintenanceLines(host);
-  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.`;
+  const guidance = host.role === "snapshotter" && host.protected === true ? `this session is already on \`${input.hostId}\`; this is a protected snapshotter host. Live-vault authoring at the resolved \`skillwiki path\` is allowed here. Do not mutate snapshot worktrees or repo-local project workspaces from this session except explicitly approved snapshot maintenance. Keep release-validation workflows read-only when they are documented as such.` : 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",
     "",
@@ -6393,7 +6399,12 @@ async function runDoctor(input) {
   checks.push(await checkConfigFile(input.home));
   checks.push(await checkProfiles(input.home));
   checks.push(await checkProjectLocalOverride(input.cwd));
-  const resolved = await resolveRuntimePath({ flag: void 0, envValue: input.envValue, home: input.home });
+  const resolved = await resolveRuntimePath({
+    flag: void 0,
+    envValue: input.envValue,
+    home: input.home,
+    cwd: input.cwd
+  });
   if (resolved.ok) {
     checks.push(check("pass", "wiki_path_set", "WIKI_PATH configured", `Resolved via ${resolved.data.source}: ${resolved.data.path}`));
   } else {
@@ -7923,7 +7934,8 @@ async function resolveMcpVault(input) {
       envValue: process.env.WIKI_PATH,
       wikiEnv: process.env.WIKI,
       home,
-      wiki: input.wiki
+      wiki: input.wiki,
+      cwd: input.cwd ?? process.cwd()
     });
     if (!r.ok) return r;
     vaultPath = resolve7(r.data.path);

package/dist/cli.js

@@ -75,13 +75,13 @@ import {
   triggerAutoUpdate,
   writeCache,
   writeDotenv
-} from "./chunk-TK4ZIQNE.js";
+} from "./chunk-XBYPWCIS.js";
 import {
   normalizeDistTag
 } from "./chunk-E6UWZ3S3.js";
 
 // src/cli.ts
-import { join as join25 } from "path";
+import { join as join26 } from "path";
 import { Command } from "commander";
 
 // src/utils/output.ts
@@ -425,6 +425,7 @@ async function runPath(input) {
       flag: input.flag,
       envValue: input.envValue,
       home: input.home,
+      cwd: input.cwd,
       explain: input.explain
     });
     return { exitCode: ExitCode.OK, result: ok({ path: r2.path, source: r2.source, ...r2.chain ? { chain: r2.chain } : {}, humanHint: `${r2.path} (via ${r2.source})` }) };
@@ -434,6 +435,7 @@ async function runPath(input) {
     envValue: input.envValue,
     home: input.home,
     wiki: input.wiki,
+    cwd: input.cwd,
     explain: input.explain
   });
   if (!r.ok) {
@@ -4795,13 +4797,19 @@ async function postCommit(vault, exitCode) {
 }
 
 // src/utils/protected-vault-write-guard.ts
+import { readFileSync as readFileSync7 } from "fs";
+import { join as join25, resolve as resolvePath } from "path";
 async function guardProtectedVaultWrite(input) {
+  const env = input.env ?? process.env;
+  const home = input.home ?? process.env.HOME ?? "";
+  const cwd = input.cwd ?? process.cwd();
+  const liveVaultPath = await resolveLiveVaultPath({ env, home, cwd });
   const load = await loadFleetManifestAndHost({
-    vault: input.vault,
+    vault: liveVaultPath ?? input.vault,
     hostId: input.hostId,
-    env: input.env ?? process.env,
-    home: input.home ?? process.env.HOME ?? "",
-    cwd: input.cwd ?? process.cwd(),
+    env,
+    home,
+    cwd,
     osHostname: input.osHostname ?? process.env.HOSTNAME,
     user: input.user ?? process.env.USER
   });
@@ -4812,16 +4820,77 @@ async function guardProtectedVaultWrite(input) {
   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."
-    })
-  };
+  const snapshotWorktree = resolveSnapshotWorktree(home);
+  const targetVault = resolvePath(input.vault);
+  const canonicalLiveVault = liveVaultPath ? resolvePath(liveVaultPath) : void 0;
+  const canonicalSnapshotWorktree = snapshotWorktree ? resolvePath(snapshotWorktree) : void 0;
+  if (canonicalLiveVault && targetVault === canonicalLiveVault) {
+    return { blocked: false };
+  }
+  if (canonicalSnapshotWorktree && targetVault === canonicalSnapshotWorktree) {
+    return {
+      blocked: true,
+      exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED,
+      result: err("PROTECTED_SNAPSHOTTER_WRITE_BLOCKED", {
+        host_id: load.hostId,
+        command: input.command,
+        reason: `refusing mutation of snapshot worktree '${canonicalSnapshotWorktree}' on protected snapshotter host '${load.hostId}'`,
+        guidance: canonicalLiveVault ? `Use the live vault path '${canonicalLiveVault}' for authoring. Keep snapshot worktrees read-only except explicit snapshot maintenance.` : "Use the live skillwiki vault path for authoring. Keep snapshot worktrees read-only except explicit snapshot maintenance."
+      })
+    };
+  }
+  if (canonicalLiveVault && targetVault !== canonicalLiveVault) {
+    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 outside the live vault path '${canonicalLiveVault}' on protected snapshotter host '${load.hostId}'`,
+        guidance: "Use the resolved live skillwiki vault path for authoring. Keep alternate vault roots and snapshot worktrees read-only unless explicitly approved."
+      })
+    };
+  }
+  return { blocked: false };
+}
+async function resolveLiveVaultPath(input) {
+  const resolved = await resolveRuntimePath({
+    flag: void 0,
+    envValue: input.env.WIKI_PATH,
+    wikiEnv: input.env.WIKI,
+    home: input.home,
+    cwd: input.cwd
+  });
+  return resolved.ok ? resolved.data.path : void 0;
+}
+function resolveSnapshotWorktree(home) {
+  const skillwikiEnv = join25(home, ".skillwiki", ".env");
+  const explicitWorktree = readEnvKey(skillwikiEnv, ["vault_sync.snapshot_worktree"]);
+  if (explicitWorktree) return explicitWorktree;
+  const snapshotProfile = readEnvKey(skillwikiEnv, ["vault_sync.snapshot_profile"]);
+  if (snapshotProfile) {
+    const fromProfile = readEnvKey(snapshotProfile, ["WIKI_GIT_WORKTREE", "SNAPSHOT_WORKTREE", "GIT_DIR"]);
+    if (fromProfile) return fromProfile;
+  }
+  return "/root/wiki-git";
+}
+function readEnvKey(path, keys) {
+  try {
+    const content = readFileSync7(path, "utf8");
+    for (const line of content.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (trimmed.length === 0 || trimmed.startsWith("#")) continue;
+      const eq = trimmed.indexOf("=");
+      if (eq <= 0) continue;
+      const key = trimmed.slice(0, eq).trim();
+      if (!keys.includes(key)) continue;
+      const value = trimmed.slice(eq + 1).trim();
+      if (value.length > 0) return value;
+    }
+  } catch {
+    return void 0;
+  }
+  return void 0;
 }
 
 // src/cli.ts
@@ -4865,7 +4934,7 @@ program.command("validate <file>").description("validate vault page frontmatter
   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");
+  const out = opts.out ?? join26(vault, ".skillwiki", "graph.json");
   return emitGuardedVaultWrite(vault, "graph build", () => runGraphBuild({ vault, out }));
 });
 var canvasCmd = program.command("canvas").description("manage Obsidian canvas files");
@@ -4888,7 +4957,8 @@ program.command("orphans [vault]").description("find pages not referenced by any
   vault,
   envValue: process.env.WIKI_PATH,
   home: process.env.HOME ?? "",
-  wiki: opts.wiki
+  wiki: opts.wiki,
+  cwd: process.cwd()
 })));
 program.command("audit <file>").description("audit citation markers and source provenance for a vault page").action(async (file) => emit(await runAudit({ file })));
 program.command("install").description("install skillwiki SKILL.md files into ~/.claude/skills/").option("--target <dir>", "target install directory", `${process.env.HOME ?? ""}/.claude/skills/`).option("--dry-run", "preview only", false).option("--skills-root <dir>", "source skills directory (defaults to packaged)").option("--symlink", "create symlinks instead of copies (dev mode \u2014 edits to source are immediately visible)", false).option("--force", "install CLI copies even when the skillwiki@llm-wiki plugin channel is active", false).action(async (opts) => {
@@ -4904,6 +4974,7 @@ program.command("path").description("show the resolved vault path").option("--va
     home: process.env.HOME ?? "",
     initTime,
     wiki: opts.wiki,
+    cwd: process.cwd(),
     explain: !!opts.explain
   }));
 });
@@ -4938,7 +5009,8 @@ async function resolveVaultArg(arg, wiki) {
     envValue: process.env.WIKI_PATH,
     wikiEnv: process.env.WIKI,
     home: process.env.HOME ?? "",
-    wiki
+    wiki,
+    cwd: process.cwd()
   });
   if (!r.ok) {
     const exitCode = r.error === "UNKNOWN_WIKI_PROFILE" ? 35 : 25;

package/dist/skillwiki-mcp.js

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

package/package.json

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

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

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

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

@@ -124,7 +124,11 @@ Key CLI subcommands: `init`, `health`, `lint`, `config`, `doctor`, `path`, `lang
 Run `skillwiki health <vault> --out /tmp/skillwiki-health.json --no-fail` for a bounded whole-system report that includes doctor, lint, vault-sync, query-readiness, source-freshness, risk flags, and self-check coverage. Run `skillwiki lint <vault> --summary` for lint-only bucket counts with capped examples and details commands. Run `skillwiki doctor` to diagnose setup/runtime issues only. Run `skillwiki config list` to see current configuration.
 
 ## Runtime Host Context and Fleet Freshness
-The live output of `skillwiki --human fleet context <vault>` is authoritative for host identity. It overrides stale injected SessionStart context, remembered workspace context, and prior conversation summaries. `fleet context` is local and network-free; it reports `identity_status`, resolver trace, warnings, and the fact that remote freshness was not checked.
+Resolve the active project vault with `skillwiki path` first. Then pass that exact path to `skillwiki --human fleet context <vault>` for host identity and safety guidance. `fleet context` is authoritative for host identity. It overrides stale injected SessionStart context, remembered workspace context, and prior conversation summaries. `fleet context` is local and network-free; it reports `identity_status`, resolver trace, warnings, and the fact that remote freshness was not checked.
+
+Do not substitute infrastructure mirrors such as `~/wiki-git` or other snapshot worktrees for the project vault just to inspect fleet status. Those paths are snapshot infrastructure unless `skillwiki path` itself resolves there.
+
+On snapshotter hosts, `protected: true` does not by itself mean the live vault is read-only for agent authoring. Treat the resolved `skillwiki path` as the live authoring vault when the host policy allows it, and treat snapshot worktrees such as `~/wiki-git` as protected infrastructure unless the user explicitly asks for snapshot maintenance.
 
 Use the local identity check for ordinary runtime context:
 ```bash

package/skills/skills/wiki-sync/SKILL.md

@@ -182,6 +182,8 @@ Some deployments use a cloud-backed vault (`rclone mount`) with a separate git r
 ~/wiki-git       → git repository cloned from GitHub — snapshot target
 cron hourly      → rsync ~/wiki/ → ~/wiki-git/ → git commit → git push
 ```
+On snapshotter hosts, `~/wiki` remains the active SkillWiki vault for path resolution unless the operator explicitly configures otherwise. `~/wiki-git` is snapshot infrastructure, not the default authoring or dev-loop vault. Agents may author the live vault path when the host policy allows it, but should not point project work or `fleet context` at `~/wiki-git` unless `skillwiki path` intentionally resolves there.
+
 ### Implementation (wiki-snapshot.sh)
 ```bash
 #!/bin/bash
@@ -217,7 +219,7 @@ git reset --hard origin/main
 bash ~/.hermes/scripts/wiki-snapshot.sh  # Re-sync fresh
 ```
 **Prevention**: Avoid editing the GitHub repo directly via web interface or uncoordinated clones. The canonical flow is **single-writer-git** (see `concepts/vault-write-authority-model.md`):
-- Server (sg01): rclone mount → rsync → git commit "Snapshot ..." → git push — **sole git writer to `main`**
+- Server (sg01): agents may author the live vault at `~/wiki`; the snapshot job promotes cloud-backed live-vault state into `~/wiki-git`, then commits and pushes — **sole git writer to `main`**
 - macOS/desktop: edit → `wiki-push` rclone copy to S3 (NO git push) → consume sg01 snapshots via `wiki-fetch-notify` (opt-in `WIKI_FETCH_PULL_ON_DELTA=1`) or manual `skillwiki sync`
 - `wiki-sync` skill push is for **explicit** agent/human edit commits only, not automated background pushes
 2. **Slow rsync on rclone mounts**: The rclone FUSE mount can be slow for large directory listings. Use `rsync -q` (quiet) to reduce output overhead, and consider `--delete-delay` instead of `--delete` if file churn is high. The rclone mount latency can cause `du` and `find` operations to timeout — this is normal, not an error.

package/skills/using-skillwiki/SKILL.md

@@ -124,7 +124,11 @@ Key CLI subcommands: `init`, `health`, `lint`, `config`, `doctor`, `path`, `lang
 Run `skillwiki health <vault> --out /tmp/skillwiki-health.json --no-fail` for a bounded whole-system report that includes doctor, lint, vault-sync, query-readiness, source-freshness, risk flags, and self-check coverage. Run `skillwiki lint <vault> --summary` for lint-only bucket counts with capped examples and details commands. Run `skillwiki doctor` to diagnose setup/runtime issues only. Run `skillwiki config list` to see current configuration.
 
 ## Runtime Host Context and Fleet Freshness
-The live output of `skillwiki --human fleet context <vault>` is authoritative for host identity. It overrides stale injected SessionStart context, remembered workspace context, and prior conversation summaries. `fleet context` is local and network-free; it reports `identity_status`, resolver trace, warnings, and the fact that remote freshness was not checked.
+Resolve the active project vault with `skillwiki path` first. Then pass that exact path to `skillwiki --human fleet context <vault>` for host identity and safety guidance. `fleet context` is authoritative for host identity. It overrides stale injected SessionStart context, remembered workspace context, and prior conversation summaries. `fleet context` is local and network-free; it reports `identity_status`, resolver trace, warnings, and the fact that remote freshness was not checked.
+
+Do not substitute infrastructure mirrors such as `~/wiki-git` or other snapshot worktrees for the project vault just to inspect fleet status. Those paths are snapshot infrastructure unless `skillwiki path` itself resolves there.
+
+On snapshotter hosts, `protected: true` does not by itself mean the live vault is read-only for agent authoring. Treat the resolved `skillwiki path` as the live authoring vault when the host policy allows it, and treat snapshot worktrees such as `~/wiki-git` as protected infrastructure unless the user explicitly asks for snapshot maintenance.
 
 Use the local identity check for ordinary runtime context:
 ```bash

package/skills/wiki-sync/SKILL.md

@@ -182,6 +182,8 @@ Some deployments use a cloud-backed vault (`rclone mount`) with a separate git r
 ~/wiki-git       → git repository cloned from GitHub — snapshot target
 cron hourly      → rsync ~/wiki/ → ~/wiki-git/ → git commit → git push
 ```
+On snapshotter hosts, `~/wiki` remains the active SkillWiki vault for path resolution unless the operator explicitly configures otherwise. `~/wiki-git` is snapshot infrastructure, not the default authoring or dev-loop vault. Agents may author the live vault path when the host policy allows it, but should not point project work or `fleet context` at `~/wiki-git` unless `skillwiki path` intentionally resolves there.
+
 ### Implementation (wiki-snapshot.sh)
 ```bash
 #!/bin/bash
@@ -217,7 +219,7 @@ git reset --hard origin/main
 bash ~/.hermes/scripts/wiki-snapshot.sh  # Re-sync fresh
 ```
 **Prevention**: Avoid editing the GitHub repo directly via web interface or uncoordinated clones. The canonical flow is **single-writer-git** (see `concepts/vault-write-authority-model.md`):
-- Server (sg01): rclone mount → rsync → git commit "Snapshot ..." → git push — **sole git writer to `main`**
+- Server (sg01): agents may author the live vault at `~/wiki`; the snapshot job promotes cloud-backed live-vault state into `~/wiki-git`, then commits and pushes — **sole git writer to `main`**
 - macOS/desktop: edit → `wiki-push` rclone copy to S3 (NO git push) → consume sg01 snapshots via `wiki-fetch-notify` (opt-in `WIKI_FETCH_PULL_ON_DELTA=1`) or manual `skillwiki sync`
 - `wiki-sync` skill push is for **explicit** agent/human edit commits only, not automated background pushes
 2. **Slow rsync on rclone mounts**: The rclone FUSE mount can be slow for large directory listings. Use `rsync -q` (quiet) to reduce output overhead, and consider `--delete-delay` instead of `--delete` if file churn is high. The rclone mount latency can cause `du` and `find` operations to timeout — this is normal, not an error.