skillwiki 0.9.30 → 0.9.32

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

@@ -1170,8 +1170,9 @@ var FRONTMATTER = /^---\n[\s\S]*?\n---\n?/;
 function stripFences(body) {
   return body.replace(FENCE2, "").replace(INLINE_CODE, "");
 }
+var TILDE_FENCE = /~~~[\s\S]*?~~~/g;
 function stripFencedBlocks(body) {
-  return body.replace(FENCE2, "");
+  return body.replace(FENCE2, "").replace(TILDE_FENCE, "");
 }
 function extractCitationMarkers(body) {
   const stripped = stripFences(body);
@@ -2055,11 +2056,57 @@ ${markdown_links.map((l) => `  line ${l.line}: ${l.text}`).join("\n")}`;
 
 // src/commands/dedup.ts
 import { createHash as createHash2 } from "crypto";
-import { execFile } from "child_process";
 import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, unlinkSync as unlinkSync2 } from "fs";
 import { dirname as dirname4, join as join12, resolve as resolve3 } from "path";
+
+// src/utils/rclone.ts
+import { execFile } from "child_process";
 import { promisify } from "util";
 var execFileAsync = promisify(execFile);
+function normalizeRemoteRoot(remote) {
+  return remote?.replace(/\/+$/, "");
+}
+function buildRemoteObjectPath(remoteRoot, relPath) {
+  return remoteRoot ? `${remoteRoot}/${relPath}` : void 0;
+}
+function isValidRemoteDeleteCap(maxRemoteDeletes) {
+  if (maxRemoteDeletes === void 0) return true;
+  return Number.isInteger(maxRemoteDeletes) && maxRemoteDeletes > 0;
+}
+async function planAndMaybePruneRemoteObjects(plannedDeletes, input) {
+  const output = { plannedDeletes, deleted: [] };
+  if (!input.remoteDelete) return ok(output);
+  const maxDeletes = input.maxRemoteDeletes ?? input.defaultMaxDeletes ?? 1;
+  if (!Number.isInteger(maxDeletes) || maxDeletes < 1) {
+    return err("USAGE", { message: "--max-remote-deletes must be a positive integer" });
+  }
+  if (plannedDeletes.length > maxDeletes) {
+    return err("USAGE", { message: `remote delete cap exceeded: ${plannedDeletes.length} > ${maxDeletes}` });
+  }
+  const runner = input.rcloneRunner ?? defaultRcloneRunner;
+  for (const path of plannedDeletes) {
+    const result = await runner(["deletefile", path]);
+    if (result.exitCode !== 0) {
+      return err("SYNC_PUSH_FAILED", { path, stderr: result.stderr, deleted: output.deleted });
+    }
+    output.deleted.push(path);
+  }
+  return ok(output);
+}
+async function defaultRcloneRunner(args) {
+  try {
+    const result = await execFileAsync("rclone", args, { encoding: "utf-8" });
+    return { exitCode: 0, stdout: result.stdout, stderr: result.stderr };
+  } catch (e) {
+    return {
+      exitCode: typeof e?.code === "number" ? e.code : 1,
+      stdout: typeof e?.stdout === "string" ? e.stdout : "",
+      stderr: typeof e?.stderr === "string" ? e.stderr : String(e)
+    };
+  }
+}
+
+// src/commands/dedup.ts
 async function runDedup(input) {
   if (input.canonicalPolicy && input.canonicalPolicy !== "scan-order" && input.canonicalPolicy !== "stable-path") {
     return { exitCode: ExitCode.USAGE, result: err("USAGE", { message: "--canonical-policy must be stable-path or scan-order" }) };
@@ -2258,39 +2305,9 @@ function readManifest(path) {
   }
 }
 async function planAndMaybePruneRemote(input, entries) {
-  const remoteRoot = input.remote?.replace(/\/+$/, "");
+  const remoteRoot = normalizeRemoteRoot(input.remote);
   const plannedDeletes = remoteRoot ? entries.flatMap((entry) => entry.duplicates.map((path) => `${remoteRoot}/${path}`)) : [];
-  const output = { plannedDeletes, deleted: [] };
-  if (!input.remoteDelete) return ok(output);
-  const maxDeletes = input.maxRemoteDeletes ?? 50;
-  if (!Number.isInteger(maxDeletes) || maxDeletes < 1) {
-    return err("USAGE", { message: "--max-remote-deletes must be a positive integer" });
-  }
-  if (plannedDeletes.length > maxDeletes) {
-    return err("USAGE", { message: `remote delete cap exceeded: ${plannedDeletes.length} > ${maxDeletes}` });
-  }
-  const runner = input.rcloneRunner ?? defaultRcloneRunner;
-  for (const path of plannedDeletes) {
-    const result = await runner(["deletefile", path]);
-    if (result.exitCode !== 0) {
-      output.failed = { path, stderr: result.stderr };
-      return err("SYNC_PUSH_FAILED", { path, stderr: result.stderr });
-    }
-    output.deleted.push(path);
-  }
-  return ok(output);
-}
-async function defaultRcloneRunner(args) {
-  try {
-    const result = await execFileAsync("rclone", args, { encoding: "utf-8" });
-    return { exitCode: 0, stdout: result.stdout, stderr: result.stderr };
-  } catch (e) {
-    return {
-      exitCode: typeof e?.code === "number" ? e.code : 1,
-      stdout: typeof e?.stdout === "string" ? e.stdout : "",
-      stderr: typeof e?.stderr === "string" ? e.stderr : String(e)
-    };
-  }
+  return planAndMaybePruneRemoteObjects(plannedDeletes, { ...input, defaultMaxDeletes: 50 });
 }
 
 // src/utils/safe-write.ts
@@ -2710,7 +2727,7 @@ function buildCliSurface() {
   program.command("health").option("--wiki <name>").option("--sync <mode>").option("--no-fail").option("--out <path>").option("--examples <n>");
   program.command("doctor");
   program.command("status").option("--wiki <name>");
-  program.command("archive").option("--wiki <name>").option("--cascade").option("--apply");
+  program.command("archive").option("--wiki <name>").option("--cascade").option("--apply").option("--remote <remote>").option("--remote-delete").option("--max-remote-deletes <n>");
   program.command("drift").option("--apply").option("--new <date>").option("--wiki <name>");
   program.command("dedup").option("--apply").option("--canonical-policy <policy>").option("--manifest-out <path>").option("--manifest-in <path>").option("--remote <remote>").option("--remote-delete").option("--max-remote-deletes <n>").option("--wiki <name>");
   program.command("migrate-citations").option("--dry-run").option("--wiki <name>");
@@ -2922,6 +2939,23 @@ function hasDuplicateFrontmatter(body) {
   }
   return false;
 }
+var CANONICAL_LOCAL_SOURCE_LABEL = /^\s*(?:>\s*)?(?:[-*+]\s*)?Source (?:file|inspected):/i;
+var LOCAL_ABSOLUTE_SOURCE_REF = /(?:file:\/\/(?:\/)?(?:Users|home)\/|\/(?:Users|home)\/)/;
+function hasCanonicalLocalSourceAssertion(body) {
+  const visibleBody = stripFencedBlocks(body);
+  return visibleBody.split(/\r?\n/).some(
+    (line) => CANONICAL_LOCAL_SOURCE_LABEL.test(line) && LOCAL_ABSOLUTE_SOURCE_REF.test(line)
+  );
+}
+function shouldCheckCanonicalLocalSourceAssertion(page) {
+  if (page.relPath.startsWith("raw/transcripts/")) return false;
+  if (/^projects\/[^/]+\/work\/[^/]+\/log\.md$/.test(page.relPath)) return false;
+  if (page.relPath.startsWith("raw/")) return true;
+  if (/^(entities|concepts|comparisons|queries|meta)\//.test(page.relPath)) return true;
+  if (/^projects\/[^/]+\/compound\//.test(page.relPath)) return true;
+  if (/^projects\/[^/]+\/work\/[^/]+\/(spec|plan)\.md$/.test(page.relPath)) return true;
+  return false;
+}
 function extractSourceEntries(rawFm) {
   const lines = rawFm.split(/\r?\n/);
   const sourcesLineIdx = lines.findIndex((l) => /^sources:/.test(l));
@@ -3196,14 +3230,18 @@ async function runLint(input) {
     if (subDirDupes.length > 0) {
       buckets.raw_subdirectory_duplicate = subDirDupes;
     }
-    const fileSourceUrlFlags = [];
+    const fileSourceUrlFlags = /* @__PURE__ */ new Set();
+    const fileSourceUrlFrontmatterFlags = /* @__PURE__ */ new Set();
     const rawIdentityConflicts = [];
+    const rawPageBodyByPath = /* @__PURE__ */ new Map();
     for (const raw of scan.data.raw) {
       const text = await readPage(raw);
       const split = splitFrontmatter(text);
       if (!split.ok) continue;
+      rawPageBodyByPath.set(raw.relPath, split.data.body);
       if (/^source_url:\s*file:\/\//m.test(split.data.rawFrontmatter)) {
-        fileSourceUrlFlags.push(raw.relPath);
+        fileSourceUrlFlags.add(raw.relPath);
+        fileSourceUrlFrontmatterFlags.add(raw.relPath);
       }
       const sourceUrl = split.data.rawFrontmatter.match(/^source_url:\s*(.+)$/m)?.[1]?.trim().replace(/^["']|["']$/g, "") ?? "";
       const assessment = assessSourceIdentity({
@@ -3222,7 +3260,26 @@ async function runLint(input) {
         });
       }
     }
-    if (fileSourceUrlFlags.length > 0) buckets.file_source_url = fileSourceUrlFlags;
+    const canonicalSourcePages = [
+      ...scan.data.raw,
+      ...scan.data.typedKnowledge,
+      ...scan.data.compound,
+      ...scan.data.workItems
+    ];
+    for (const page of canonicalSourcePages) {
+      if (!shouldCheckCanonicalLocalSourceAssertion(page)) continue;
+      let body = rawPageBodyByPath.get(page.relPath);
+      if (body === void 0) {
+        const text = await readPage(page);
+        const split = splitFrontmatter(text);
+        if (!split.ok) continue;
+        body = split.data.body;
+      }
+      if (hasCanonicalLocalSourceAssertion(body)) {
+        fileSourceUrlFlags.add(page.relPath);
+      }
+    }
+    if (fileSourceUrlFlags.size > 0) buckets.file_source_url = [...fileSourceUrlFlags];
     if (rawIdentityConflicts.length > 0) buckets.raw_source_identity_conflict = rawIdentityConflicts;
     const legacyPages = [];
     const orphanedPages = [];
@@ -3697,9 +3754,9 @@ ${newBody}`;
         else delete buckets.wikilink_citation;
       }
     }
-    if (shouldFix("file_source_url") && fileSourceUrlFlags.length > 0) {
+    if (shouldFix("file_source_url") && fileSourceUrlFrontmatterFlags.size > 0) {
       const FILE_FIXED = [];
-      for (const relPath of fileSourceUrlFlags) {
+      for (const relPath of fileSourceUrlFrontmatterFlags) {
         try {
           const absPath = `${input.vault}/${relPath}`;
           const raw = await readFile12(absPath, "utf8");
@@ -3730,9 +3787,26 @@ ${newBody}`;
       }
       fixed.push(...FILE_FIXED);
       if (FILE_FIXED.length > 0) {
-        const fixedSet = new Set(FILE_FIXED);
-        const remaining = fileSourceUrlFlags.filter((p) => !fixedSet.has(p));
-        if (remaining.length > 0) buckets.file_source_url = remaining;
+        const remaining = new Set(fileSourceUrlFlags);
+        for (const relPath of FILE_FIXED) {
+          try {
+            const page = scan.data.allMarkdown.find((p) => p.relPath === relPath);
+            if (!page) {
+              remaining.delete(relPath);
+              continue;
+            }
+            const text = await readPage(page);
+            const split = splitFrontmatter(text);
+            if (!split.ok) continue;
+            const stillHasFileSourceUrl = /^source_url:\s*file:\/\//m.test(split.data.rawFrontmatter);
+            const stillHasCanonicalBodyAssertion = shouldCheckCanonicalLocalSourceAssertion(page) && hasCanonicalLocalSourceAssertion(split.data.body);
+            if (!stillHasFileSourceUrl && !stillHasCanonicalBodyAssertion) {
+              remaining.delete(relPath);
+            }
+          } catch {
+          }
+        }
+        if (remaining.size > 0) buckets.file_source_url = [...remaining];
         else delete buckets.file_source_url;
       }
     }
@@ -8805,6 +8879,10 @@ export {
   runLogRotate,
   runTopicMapCheck,
   runIndexLinkFormat,
+  normalizeRemoteRoot,
+  buildRemoteObjectPath,
+  isValidRemoteDeleteCap,
+  planAndMaybePruneRemoteObjects,
   runDedup,
   safeWritePage,
   runFrontmatterFix,

package/dist/cli.js

@@ -6,6 +6,7 @@ import {
   TypedKnowledgeSchema,
   appendLastOp,
   assessSourceIdentity,
+  buildRemoteObjectPath,
   clearLastOp,
   configPath,
   detectSchema,
@@ -18,10 +19,13 @@ import {
   fixPathTooLong,
   isBlockedHost,
   isFailedRunStatus,
+  isValidRemoteDeleteCap,
   loadFleetManifest,
+  normalizeRemoteRoot,
   ok,
   parseDotenvFile,
   parseDotenvText,
+  planAndMaybePruneRemoteObjects,
   profileKey,
   readCliPackageJson,
   readLastOp,
@@ -69,7 +73,7 @@ import {
   triggerAutoUpdate,
   writeCache,
   writeDotenv
-} from "./chunk-JENSKJP6.js";
+} from "./chunk-OPXMAS4O.js";
 import {
   normalizeDistTag
 } from "./chunk-E6UWZ3S3.js";
@@ -1339,6 +1343,12 @@ function arraysEqual(a, b) {
   return true;
 }
 async function runArchive(input) {
+  if (input.remoteDelete && !input.remote) {
+    return { exitCode: ExitCode.USAGE, result: err("USAGE", { message: "--remote-delete requires --remote" }) };
+  }
+  if (input.remoteDelete && !isValidRemoteDeleteCap(input.maxRemoteDeletes)) {
+    return { exitCode: ExitCode.USAGE, result: err("USAGE", { message: "--max-remote-deletes must be a positive integer" }) };
+  }
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
   const lookup = (pages) => {
@@ -1355,6 +1365,8 @@ async function runArchive(input) {
   if (relPath.startsWith("_archive/")) return { exitCode: ExitCode.ARCHIVE_ALREADY_ARCHIVED, result: err("ARCHIVE_ALREADY_ARCHIVED", { page: relPath }) };
   const slug = relPath.replace(/\.md$/, "").split("/").pop();
   const archivePath = join10("_archive", relPath).replace(/\\/g, "/");
+  const remoteRoot = normalizeRemoteRoot(input.remote);
+  const remoteObjectPath = buildRemoteObjectPath(remoteRoot, relPath);
   let cascade;
   if (input.cascade) {
     const wikilinkRefs = [];
@@ -1398,7 +1410,8 @@ async function runArchive(input) {
         index_updated: false,
         applied: false,
         cascade,
-        humanHint: summary
+        ...remoteObjectPath ? { remote: { plannedDeletes: [remoteObjectPath], deleted: [] } } : {},
+        humanHint: summary + (remoteObjectPath ? ` (remote planned ${input.remoteDelete ? "delete" : "preview"}: ${remoteObjectPath})` : "")
       })
     };
   }
@@ -1445,8 +1458,18 @@ ${fmRewritten}
     files: [relPath],
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   });
+  let remote;
+  if (remoteObjectPath) {
+    const plannedDeletes = [remoteObjectPath];
+    const pruned = await planAndMaybePruneRemoteObjects(plannedDeletes, input);
+    if (!pruned.ok) {
+      return { exitCode: ExitCode.SYNC_PUSH_FAILED, result: pruned };
+    }
+    remote = pruned.data;
+  }
   const applied = input.cascade ? true : void 0;
   const cascadeNote = input.cascade ? ` (cascade: ${cascade.source_array_refs.length} src arrays updated, ${cascade.wikilink_refs.length} wikilinks reported)` : "";
+  const remoteNote = remote ? ` (remote ${input.remoteDelete ? `deleted ${remote.deleted.length}` : `planned ${remote.plannedDeletes.length}`})` : "";
   return {
     exitCode: ExitCode.OK,
     result: ok({
@@ -1455,7 +1478,8 @@ ${fmRewritten}
       index_updated: indexUpdated,
       ...applied !== void 0 ? { applied } : {},
       ...cascade ? { cascade } : {},
-      humanHint: `${relPath} -> ${archivePath}${indexUpdated ? " (index updated)" : ""}${cascadeNote}`
+      ...remote ? { remote } : {},
+      humanHint: `${relPath} -> ${archivePath}${indexUpdated ? " (index updated)" : ""}${cascadeNote}${remoteNote}`
     })
   };
 }
@@ -4886,10 +4910,18 @@ program.command("status [vault]").description("output vault diagnostics").option
     langEnvValue: process.env.WIKI_LANG
   }), v.vault);
 });
-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).action(async (page, vault, opts) => {
+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({ vault: v.vault, page, cascade: !!opts.cascade, apply: !!opts.apply }), v.vault);
+  else emit(await runArchive({
+    vault: v.vault,
+    page,
+    cascade: !!opts.cascade,
+    apply: !!opts.apply,
+    remote: opts.remote,
+    remoteDelete: !!opts.remoteDelete,
+    maxRemoteDeletes: Number.parseInt(opts.maxRemoteDeletes, 10)
+  }), v.vault);
 });
 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);

package/dist/skillwiki-mcp.js

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

package/package.json

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

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

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

package/skills/proj-distill/SKILL.md

@@ -32,6 +32,7 @@ When reading retros as source material:
    `provenance: project` and
    `provenance_projects: ["[[slug]]"]`. Validate with
    `skillwiki validate`.
+   - **Portable source references:** follow `using-skillwiki` → Portable Source References (commit-pinned GitHub URLs or repo-relative paths; not canonical `Source file:` / `Source inspected:` host paths).
    - **Tag hygiene:** `tags:` must only contain entries from
      `{vault}/SCHEMA.md` taxonomy. Never derive tags from prose text
      (lesson/evidence sections) — use only established taxonomy tags

package/skills/proj-work/SKILL.md

@@ -53,6 +53,7 @@ Rules:
 - Resolve `<vault-root>` via `skillwiki path` (never hardcode).
 - proj-work does NOT invoke any PRD skill — it provides paths only.
 - If the PRD skill cannot accept custom save paths, fall back to manual `wiki-ingest`.
+- When `spec.md` or `plan.md` mentions repo files, follow `using-skillwiki` → Portable Source References.
 
 ## Pitfalls
 - **Wiki-as-truth fallacy**: tasks.md status markers are aspirational claims by previous sessions. They are often wrong. Always audit the actual file system before accepting a "DONE" label.

package/skills/skills/proj-distill/SKILL.md

@@ -32,6 +32,7 @@ When reading retros as source material:
    `provenance: project` and
    `provenance_projects: ["[[slug]]"]`. Validate with
    `skillwiki validate`.
+   - **Portable source references:** follow `using-skillwiki` → Portable Source References (commit-pinned GitHub URLs or repo-relative paths; not canonical `Source file:` / `Source inspected:` host paths).
    - **Tag hygiene:** `tags:` must only contain entries from
      `{vault}/SCHEMA.md` taxonomy. Never derive tags from prose text
      (lesson/evidence sections) — use only established taxonomy tags

package/skills/skills/proj-work/SKILL.md

@@ -53,6 +53,7 @@ Rules:
 - Resolve `<vault-root>` via `skillwiki path` (never hardcode).
 - proj-work does NOT invoke any PRD skill — it provides paths only.
 - If the PRD skill cannot accept custom save paths, fall back to manual `wiki-ingest`.
+- When `spec.md` or `plan.md` mentions repo files, follow `using-skillwiki` → Portable Source References.
 
 ## Pitfalls
 - **Wiki-as-truth fallacy**: tasks.md status markers are aspirational claims by previous sessions. They are often wrong. Always audit the actual file system before accepting a "DONE" label.

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

@@ -59,6 +59,15 @@ sha256:          # computed by skillwiki hash over body bytes after closing ---
 ## Sensitive Content Policy
 Vault content must not contain live credentials, access keys, tokens, passwords, cookies, bearer headers, private keys, or other authenticating secrets. This includes development-only and local-only credentials. Redact values before filing using `[REDACTED:<kind>]` or `[REDACTED:<kind>:<fingerprint>]`. If a source contains live secrets, stop and ask for a redacted source or explicit rotation/remediation direction; do not preserve the secret in `raw/`.
 
+## Portable Source References
+The vault is shared across hosts, so host-local absolute paths are not durable source identity.
+
+- Prefer commit-pinned GitHub URLs when the source file is in a pushed repository and the commit is known.
+- Otherwise prefer repo-relative identity in prose, such as repo slug + relative path.
+- Use vault-relative references or `[[wikilinks]]` for pages already inside the wiki.
+- Keep host-local absolute paths (`/Users/...`, `/home/...`, `file:///...`) only as clearly labeled observations such as `Observed on host: ...`, not as canonical `Source file:` or `Source inspected:` lines.
+- Do not use markdown links to local vault files when a `[[wikilink]]` should be used instead.
+
 ### Ad-hoc capture: three entry points
 | Entry | When | What happens |
 |-------|------|-------------|

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

@@ -22,7 +22,7 @@ Standard four reads (SCHEMA, index, log, project context if applicable).
 
 0. Resolve vault: `skillwiki path` and `skillwiki lang`.
 1. Identify the target page. Confirm with the user which page to archive (show full relPath).
-2. Run `skillwiki archive <page> [vault]`. Read the JSON output.
+2. Run `skillwiki archive <page> [vault]`. On a vault-sync leaf host where S3 stale originals must be pruned, use `skillwiki archive <page> [vault] --remote seaweed-wiki:cloud/wiki --remote-delete --max-remote-deletes 1` only when that remote path deletion is explicitly intended. Read the JSON output.
 3. Verify with `skillwiki index-check [vault]` — confirm no ghost entries remain.
 4. Run `skillwiki lint [vault]` — check for broken wikilinks from other pages that still reference the archived page. If found, update those pages to point to the replacement or remove the stale link.
 5. **Raw file archiving (N9 Reingest Protocol only):** When archiving a `raw/` file due to content drift, update ALL `^[raw/...]` citation markers and `sources:` frontmatter entries that reference the old path. Change `raw/articles/foo.md` to `_archive/raw/articles/foo.md` in every referencing page. Verify with `skillwiki audit` that no broken markers remain.
@@ -30,7 +30,7 @@ Standard four reads (SCHEMA, index, log, project context if applicable).
 
 ## Reversibility
 
-Archiving is reversible: move the file back from `_archive/` to its original directory and re-add the wikilink entry to `index.md`. No data is deleted.
+Archiving is locally reversible: move the file back from `_archive/` to its original directory and re-add the wikilink entry to `index.md`. If `--remote-delete` was used, the stale active-path object is pruned from the remote after the archive move, but the archived copy remains and a restore will republish the active path on the next push.
 
 ## Stop conditions
 
@@ -42,4 +42,4 @@ Archiving is reversible: move the file back from `_archive/` to its original dir
 - Archiving `raw/` files outside the N9 Reingest Protocol (raw is immutable except during content-drift reingestion).
 - Archiving raw files without updating all `^[raw/...]` citation markers that reference them.
 - Archiving without user confirmation.
-- Deleting files (archive moves, never deletes).
+- Deleting local vault files directly (archive moves locally; remote stale-path pruning is only allowed through the explicit `skillwiki archive --remote ... --remote-delete --max-remote-deletes 1` path).

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

@@ -17,6 +17,7 @@ Standard four reads. If cwd is inside `projects/{slug}/`, also read project READ
 3. Compose the page with citations pre-attached. Reuse existing `raw/` sources where possible. Every page MUST include:
 - `> **TL;DR:**` blockquote as the first content after the title heading — a one-sentence summary of the page's key takeaway (under 200 chars). See SCHEMA.md `## TL;DR Convention`.
 - For pages tagged `architecture` or explaining workflows/systems: include a Mermaid diagram (`graph TB` or `sequenceDiagram`) in the body. Follow Obsidian-compatible Mermaid rules (see SCHEMA.md `## Mermaid Diagrams`).
+- When referring to local repo files in narrative prose, follow `using-skillwiki` → Portable Source References.
 For `comparison`, evaluation-style `query`, or research-summary pages, end the body with:
 ```markdown
 ## Decision Closeout
@@ -36,5 +37,6 @@ Use exactly one disposition. Keep this as a prompt/template convention; do not a
 ## Forbidden
 - Filing without explicit `provenance:`.
 - Updating `index.md` before `validate` passes.
+- Writing host-local absolute paths as canonical durable source references when a portable reference is available (see `using-skillwiki` → Portable Source References).
 - Writing `[[wikilinks]]` to pages that don't exist in the vault. Before linking, verify the target exists: check `index.md` or `ls` the target directory. If the target doesn't exist yet, use plain text instead of a wikilink.
 - Writing live credentials, access keys, tokens, passwords, cookies, bearer headers, private keys, or other authenticating secrets to the vault.

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

@@ -18,6 +18,7 @@ Run `skillwiki lang` at the start. Generate page-body prose, narrative sections,
 0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`. Use the resolved vault path for all writes; use the canonical language for all generated prose.
 1. **Guard.** For each URL: run `skillwiki fetch-guard <url>`. If exit ≠ 0, STOP and surface the error. Do not retry.
 2. **Fetch.** Use `web_fetch` (or read local file) under Layer 2 controls (the CLI Layer 2 fetcher applies in tests; in skill runtime use `web_fetch` directly and treat any error as STOP).
+   - **Portable local-source rule:** follow `using-skillwiki` → Portable Source References. Do not use `source_url: file:///...` as the canonical durable reference; prefer commit-pinned GitHub `blob/<commit>/<path>` when resolvable, else empty `source_url` plus portable repo-relative prose.
 3. **Identity guard.** Before writing raw files, ensure the target raw filename/title, `source_url`, fetched H1/title, and early body subject agree. If `skillwiki ingest` reports `INGEST_VALIDATION_FAILED` with `source identity conflict`, STOP. Do not fix by renaming after the fact; choose the correct title/source pair or ask the user.
 4. **Sensitive content guard.** Before writing or filing any vault page, scan the source and generated body for live credentials, access keys, tokens, passwords, cookies, bearer headers, or private keys. Redact generated prose before writing. If the source itself must remain raw and contains a live secret, STOP instead of preserving it.
 5. **Hash.** Write the raw file (frontmatter + body). Run `skillwiki hash <raw-file>` and embed the result in raw frontmatter `sha256:`.
@@ -56,6 +57,7 @@ Raw ephemeral data (market feeds, logs, transient JSON) must be written to the *
 - Updating `index.md` or `log.md` before all pages validate.
 - Modifying any existing file in `raw/`.
 - Writing raw ephemeral data directly to cloud-mounted wiki paths (`~/wiki/`).
+- Writing host-local absolute paths as canonical durable source references (see `using-skillwiki` → Portable Source References).
 - Writing `[[wikilinks]]` to pages that don't exist in the vault. Before linking, verify the target exists: check `index.md` or `ls` the target directory. If the target doesn't exist yet, use plain text instead of a wikilink.
 ## Batch Mode
 When the user provides multiple sources (a directory of files, a list of URLs, or a multi-document input):

package/skills/using-skillwiki/SKILL.md

@@ -59,6 +59,15 @@ sha256:          # computed by skillwiki hash over body bytes after closing ---
 ## Sensitive Content Policy
 Vault content must not contain live credentials, access keys, tokens, passwords, cookies, bearer headers, private keys, or other authenticating secrets. This includes development-only and local-only credentials. Redact values before filing using `[REDACTED:<kind>]` or `[REDACTED:<kind>:<fingerprint>]`. If a source contains live secrets, stop and ask for a redacted source or explicit rotation/remediation direction; do not preserve the secret in `raw/`.
 
+## Portable Source References
+The vault is shared across hosts, so host-local absolute paths are not durable source identity.
+
+- Prefer commit-pinned GitHub URLs when the source file is in a pushed repository and the commit is known.
+- Otherwise prefer repo-relative identity in prose, such as repo slug + relative path.
+- Use vault-relative references or `[[wikilinks]]` for pages already inside the wiki.
+- Keep host-local absolute paths (`/Users/...`, `/home/...`, `file:///...`) only as clearly labeled observations such as `Observed on host: ...`, not as canonical `Source file:` or `Source inspected:` lines.
+- Do not use markdown links to local vault files when a `[[wikilink]]` should be used instead.
+
 ### Ad-hoc capture: three entry points
 | Entry | When | What happens |
 |-------|------|-------------|

package/skills/wiki-archive/SKILL.md

@@ -22,7 +22,7 @@ Standard four reads (SCHEMA, index, log, project context if applicable).
 
 0. Resolve vault: `skillwiki path` and `skillwiki lang`.
 1. Identify the target page. Confirm with the user which page to archive (show full relPath).
-2. Run `skillwiki archive <page> [vault]`. Read the JSON output.
+2. Run `skillwiki archive <page> [vault]`. On a vault-sync leaf host where S3 stale originals must be pruned, use `skillwiki archive <page> [vault] --remote seaweed-wiki:cloud/wiki --remote-delete --max-remote-deletes 1` only when that remote path deletion is explicitly intended. Read the JSON output.
 3. Verify with `skillwiki index-check [vault]` — confirm no ghost entries remain.
 4. Run `skillwiki lint [vault]` — check for broken wikilinks from other pages that still reference the archived page. If found, update those pages to point to the replacement or remove the stale link.
 5. **Raw file archiving (N9 Reingest Protocol only):** When archiving a `raw/` file due to content drift, update ALL `^[raw/...]` citation markers and `sources:` frontmatter entries that reference the old path. Change `raw/articles/foo.md` to `_archive/raw/articles/foo.md` in every referencing page. Verify with `skillwiki audit` that no broken markers remain.
@@ -30,7 +30,7 @@ Standard four reads (SCHEMA, index, log, project context if applicable).
 
 ## Reversibility
 
-Archiving is reversible: move the file back from `_archive/` to its original directory and re-add the wikilink entry to `index.md`. No data is deleted.
+Archiving is locally reversible: move the file back from `_archive/` to its original directory and re-add the wikilink entry to `index.md`. If `--remote-delete` was used, the stale active-path object is pruned from the remote after the archive move, but the archived copy remains and a restore will republish the active path on the next push.
 
 ## Stop conditions
 
@@ -42,4 +42,4 @@ Archiving is reversible: move the file back from `_archive/` to its original dir
 - Archiving `raw/` files outside the N9 Reingest Protocol (raw is immutable except during content-drift reingestion).
 - Archiving raw files without updating all `^[raw/...]` citation markers that reference them.
 - Archiving without user confirmation.
-- Deleting files (archive moves, never deletes).
+- Deleting local vault files directly (archive moves locally; remote stale-path pruning is only allowed through the explicit `skillwiki archive --remote ... --remote-delete --max-remote-deletes 1` path).

package/skills/wiki-crystallize/SKILL.md

@@ -17,6 +17,7 @@ Standard four reads. If cwd is inside `projects/{slug}/`, also read project READ
 3. Compose the page with citations pre-attached. Reuse existing `raw/` sources where possible. Every page MUST include:
 - `> **TL;DR:**` blockquote as the first content after the title heading — a one-sentence summary of the page's key takeaway (under 200 chars). See SCHEMA.md `## TL;DR Convention`.
 - For pages tagged `architecture` or explaining workflows/systems: include a Mermaid diagram (`graph TB` or `sequenceDiagram`) in the body. Follow Obsidian-compatible Mermaid rules (see SCHEMA.md `## Mermaid Diagrams`).
+- When referring to local repo files in narrative prose, follow `using-skillwiki` → Portable Source References.
 For `comparison`, evaluation-style `query`, or research-summary pages, end the body with:
 ```markdown
 ## Decision Closeout
@@ -36,5 +37,6 @@ Use exactly one disposition. Keep this as a prompt/template convention; do not a
 ## Forbidden
 - Filing without explicit `provenance:`.
 - Updating `index.md` before `validate` passes.
+- Writing host-local absolute paths as canonical durable source references when a portable reference is available (see `using-skillwiki` → Portable Source References).
 - Writing `[[wikilinks]]` to pages that don't exist in the vault. Before linking, verify the target exists: check `index.md` or `ls` the target directory. If the target doesn't exist yet, use plain text instead of a wikilink.
 - Writing live credentials, access keys, tokens, passwords, cookies, bearer headers, private keys, or other authenticating secrets to the vault.

package/skills/wiki-ingest/SKILL.md

@@ -18,6 +18,7 @@ Run `skillwiki lang` at the start. Generate page-body prose, narrative sections,
 0. **Resolve vault and language.** Run `skillwiki path` (fail if NO_VAULT_CONFIGURED) and `skillwiki lang`. Use the resolved vault path for all writes; use the canonical language for all generated prose.
 1. **Guard.** For each URL: run `skillwiki fetch-guard <url>`. If exit ≠ 0, STOP and surface the error. Do not retry.
 2. **Fetch.** Use `web_fetch` (or read local file) under Layer 2 controls (the CLI Layer 2 fetcher applies in tests; in skill runtime use `web_fetch` directly and treat any error as STOP).
+   - **Portable local-source rule:** follow `using-skillwiki` → Portable Source References. Do not use `source_url: file:///...` as the canonical durable reference; prefer commit-pinned GitHub `blob/<commit>/<path>` when resolvable, else empty `source_url` plus portable repo-relative prose.
 3. **Identity guard.** Before writing raw files, ensure the target raw filename/title, `source_url`, fetched H1/title, and early body subject agree. If `skillwiki ingest` reports `INGEST_VALIDATION_FAILED` with `source identity conflict`, STOP. Do not fix by renaming after the fact; choose the correct title/source pair or ask the user.
 4. **Sensitive content guard.** Before writing or filing any vault page, scan the source and generated body for live credentials, access keys, tokens, passwords, cookies, bearer headers, or private keys. Redact generated prose before writing. If the source itself must remain raw and contains a live secret, STOP instead of preserving it.
 5. **Hash.** Write the raw file (frontmatter + body). Run `skillwiki hash <raw-file>` and embed the result in raw frontmatter `sha256:`.
@@ -56,6 +57,7 @@ Raw ephemeral data (market feeds, logs, transient JSON) must be written to the *
 - Updating `index.md` or `log.md` before all pages validate.
 - Modifying any existing file in `raw/`.
 - Writing raw ephemeral data directly to cloud-mounted wiki paths (`~/wiki/`).
+- Writing host-local absolute paths as canonical durable source references (see `using-skillwiki` → Portable Source References).
 - Writing `[[wikilinks]]` to pages that don't exist in the vault. Before linking, verify the target exists: check `index.md` or `ls` the target directory. If the target doesn't exist yet, use plain text instead of a wikilink.
 ## Batch Mode
 When the user provides multiple sources (a directory of files, a list of URLs, or a multi-document input):