skillwiki 0.9.38 → 0.9.40

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

@@ -4405,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",
     "",

package/dist/cli.js

@@ -75,13 +75,13 @@ import {
   triggerAutoUpdate,
   writeCache,
   writeDotenv
-} from "./chunk-G52HKU7I.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
@@ -4797,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
   });
@@ -4814,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
@@ -4867,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");

package/dist/skillwiki-mcp.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runSkillwikiMcpStdio
-} from "./chunk-G52HKU7I.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.38",
+  "version": "0.9.40",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js",

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

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

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

@@ -128,6 +128,8 @@ Resolve the active project vault with `skillwiki path` first. Then pass that exa
 
 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
 VAULT="$(skillwiki --human path | sed 's/ (via.*//')"

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

@@ -182,7 +182,7 @@ 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. Do not point project work or `fleet context` at `~/wiki-git` unless `skillwiki path` intentionally resolves there.
+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
@@ -219,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

@@ -128,6 +128,8 @@ Resolve the active project vault with `skillwiki path` first. Then pass that exa
 
 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
 VAULT="$(skillwiki --human path | sed 's/ (via.*//')"

package/skills/wiki-sync/SKILL.md

@@ -182,7 +182,7 @@ 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. Do not point project work or `fleet context` at `~/wiki-git` unless `skillwiki path` intentionally resolves there.
+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
@@ -219,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.