skillwiki 0.10.110 → 0.10.112

package/dist/watcher-MGHQD3UI.js

@@ -0,0 +1,526 @@
+#!/usr/bin/env node
+import {
+  readJournal,
+  upsertJournal,
+  writeJournal
+} from "./chunk-FCA3RRNF.js";
+import {
+  buildReadyHint
+} from "./chunk-OSL4J7GF.js";
+import {
+  readRegular
+} from "./chunk-K3M6OSUW.js";
+import {
+  sha256Hex
+} from "./chunk-ZRGZBAVS.js";
+import "./chunk-QESNTTVY.js";
+import "./chunk-EE7W3GLA.js";
+import {
+  assertPublicHttpsUrl
+} from "./chunk-LOVLZNLX.js";
+import "./chunk-7POLZOFY.js";
+
+// src/clip-outbox/watcher.ts
+import { createRequire } from "module";
+import { randomBytes as randomBytes2 } from "crypto";
+import { mkdir as mkdir2, readdir, rmdir, unlink, writeFile } from "fs/promises";
+import { basename, join as join2, resolve as resolve2 } from "path";
+
+// src/clip-outbox/seal.ts
+import { randomBytes } from "crypto";
+import { mkdir, open } from "fs/promises";
+import { dirname, join, relative as relative2 } from "path";
+import yaml from "js-yaml";
+
+// src/clip-outbox/localize.ts
+import { randomUUID } from "crypto";
+import { readFile } from "fs/promises";
+import { isAbsolute, relative, resolve } from "path";
+
+// src/clip-outbox/images.ts
+var MD_IMAGE = /!\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+var HTML_IMAGE = /<img\b[^>]*\bsrc=["']([^"']+)["'][^>]*>/gi;
+var WIKI_EMBED = /!\[\[([^\]]+)\]\]/g;
+var REF_DEF = /^\[([^\]]+)\]:\s+(\S+)/gm;
+var REF_IMAGE = /!\[([^\]]*)\]\[([^\]]+)\]/g;
+function parseImageDependencies(markdown, sourceUrl) {
+  const refs = [];
+  const definitions = /* @__PURE__ */ new Map();
+  for (const m of markdown.matchAll(REF_DEF)) {
+    definitions.set(m[1].toLowerCase(), m[2]);
+  }
+  for (const m of markdown.matchAll(MD_IMAGE)) {
+    refs.push(makeRef(m[0], m[2], "markdown", sourceUrl));
+  }
+  for (const m of markdown.matchAll(REF_IMAGE)) {
+    const href = definitions.get(m[2].toLowerCase());
+    if (!href) continue;
+    refs.push(makeRef(m[0], href, "markdown", sourceUrl));
+  }
+  for (const m of markdown.matchAll(HTML_IMAGE)) {
+    refs.push(makeRef(m[0], m[1], "html", sourceUrl));
+  }
+  for (const m of markdown.matchAll(WIKI_EMBED)) {
+    refs.push(makeRef(m[0], m[1].split("|")[0].trim(), "wikilink", sourceUrl));
+  }
+  return refs;
+}
+function makeRef(raw, target, kind, sourceUrl) {
+  const trimmed = target.trim();
+  const local = kind === "wikilink" || trimmed.startsWith("raw/assets/") || !/^[a-z][a-z0-9+.-]*:/i.test(trimmed);
+  let resolved = trimmed;
+  if (!local && sourceUrl) {
+    try {
+      resolved = new URL(trimmed, sourceUrl).toString();
+    } catch {
+      resolved = trimmed;
+    }
+  }
+  return { raw, kind, target: resolved, local };
+}
+function sniffImageKind(bytes) {
+  if (bytes.length >= 8 && bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71) {
+    return "png";
+  }
+  if (bytes.length >= 3 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) {
+    return "jpeg";
+  }
+  if (bytes.length >= 6 && bytes.subarray(0, 6).toString("ascii") === "GIF87a") return "gif";
+  if (bytes.length >= 6 && bytes.subarray(0, 6).toString("ascii") === "GIF89a") return "gif";
+  if (bytes.length >= 12 && bytes.subarray(0, 4).toString("ascii") === "RIFF" && bytes.subarray(8, 12).toString("ascii") === "WEBP") {
+    return "webp";
+  }
+  return void 0;
+}
+function extensionForKind(kind) {
+  return kind === "jpeg" ? "jpg" : kind;
+}
+function pngPixelCount(bytes) {
+  if (sniffImageKind(bytes) !== "png" || bytes.length < 24) return void 0;
+  const width = bytes.readUInt32BE(16);
+  const height = bytes.readUInt32BE(20);
+  return width * height;
+}
+function localAssetRelPath(target) {
+  const cleaned = target.replace(/\\/g, "/").replace(/^\.\//, "");
+  if (cleaned.startsWith("raw/assets/")) return cleaned;
+  if (cleaned.startsWith("/raw/assets/")) return cleaned.slice(1);
+  return void 0;
+}
+
+// src/clip-outbox/localize.ts
+var LocalizeError = class extends Error {
+  constructor(message, code = "LOCALIZE_HELD") {
+    super(message);
+    this.code = code;
+    this.name = "LocalizeError";
+  }
+  code;
+};
+function isInsideDir(root, candidate) {
+  const rel = relative(resolve(root), resolve(candidate));
+  return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+async function localizeCapture(markdown, opts, deps = {}) {
+  const captureId = opts.captureId ?? randomUUID().replace(/-/g, "").slice(0, 16);
+  const refs = parseImageDependencies(markdown, opts.sourceUrl);
+  if (refs.length > opts.config.maxImages) {
+    throw new LocalizeError(`too many images: ${refs.length}`);
+  }
+  const fetchImpl = deps.fetch ?? fetch;
+  const now = deps.now ?? Date.now;
+  const assets = [];
+  const seenUrl = /* @__PURE__ */ new Map();
+  const replacements = /* @__PURE__ */ new Map();
+  const deadline = now() + opts.config.localizeTimeoutMs;
+  let bundleBytes = Buffer.byteLength(markdown);
+  for (const ref of refs) {
+    if (now() > deadline) throw new LocalizeError("localize deadline exceeded");
+    let asset = seenUrl.get(ref.target);
+    if (!asset) {
+      if (ref.local) {
+        const rel = localAssetRelPath(ref.target);
+        if (!rel) throw new LocalizeError(`unsafe or missing local image: ${ref.target}`);
+        const abs = resolve(opts.outboxRoot, rel);
+        if (!isInsideDir(resolve(opts.outboxRoot, "raw/assets"), abs)) {
+          throw new LocalizeError("local image outside raw/assets");
+        }
+        const reader = deps.readLocal ?? ((p) => readFile(p));
+        const bytes = await reader(abs);
+        asset = sealAsset(captureId, bytes, ref.target, opts.config);
+        asset.captureRel = rel;
+      } else {
+        const bytes = await downloadImage(ref.target, opts.config, fetchImpl, deps.lookup);
+        asset = sealAsset(captureId, bytes, ref.target, opts.config);
+      }
+      bundleBytes += asset.bytes.length;
+      if (bundleBytes > opts.config.maxBundleBytes) throw new LocalizeError("bundle too large");
+      assets.push(asset);
+      seenUrl.set(ref.target, asset);
+    }
+    replacements.set(ref.raw, `![[${asset.captureRel}]]`);
+  }
+  let rewritten = markdown;
+  for (const [raw, embed] of replacements) {
+    rewritten = rewritten.replaceAll(raw, embed);
+  }
+  const indexMarkdown = [
+    "---",
+    `title: clip assets ${captureId}`,
+    "---",
+    "",
+    ...assets.map((a) => `- ![[${a.captureRel}]]`),
+    ""
+  ].join("\n");
+  bundleBytes += Buffer.byteLength(indexMarkdown);
+  if (bundleBytes > opts.config.maxBundleBytes) throw new LocalizeError("bundle too large");
+  return { captureId, markdown: rewritten, assets, indexMarkdown };
+}
+function sealAsset(captureId, bytes, source, config) {
+  if (bytes.length > config.maxImageBytes) throw new LocalizeError("image too large");
+  const kind = sniffImageKind(bytes);
+  if (!kind || !config.imageTypes.includes(kind)) throw new LocalizeError("unsupported image type");
+  const pixels = pngPixelCount(bytes);
+  if (pixels !== void 0 && pixels > config.maxPixels) throw new LocalizeError("image pixel budget exceeded");
+  const sha256 = sha256Hex(bytes);
+  return {
+    captureRel: `raw/assets/${captureId}/${sha256}.${extensionForKind(kind)}`,
+    sha256,
+    bytes,
+    kind,
+    source
+  };
+}
+async function downloadImage(href, config, fetchImpl, lookup) {
+  let current = href;
+  for (let hop = 0; hop <= config.maxRedirects; hop++) {
+    const guarded = await assertPublicHttpsUrl(current, lookup);
+    if (!guarded.ok) {
+      throw new LocalizeError(
+        hop === 0 ? `blocked image URL: ${guarded.reason}` : `redirect blocked: ${guarded.reason}`
+      );
+    }
+    const res = await fetchImpl(current, {
+      method: "GET",
+      redirect: "manual",
+      headers: { Accept: "image/*" },
+      signal: AbortSignal.timeout(config.requestTimeoutMs)
+    });
+    if (res.status >= 300 && res.status < 400) {
+      const loc = res.headers.get("location");
+      if (!loc) throw new LocalizeError("redirect without location");
+      current = new URL(loc, current).toString();
+      continue;
+    }
+    if (!res.ok || !res.body) throw new LocalizeError(`image HTTP ${res.status}`);
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of res.body) {
+      total += chunk.byteLength;
+      if (total > config.maxImageBytes) throw new LocalizeError("image too large");
+      chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+  }
+  throw new LocalizeError("too many redirects");
+}
+
+// src/clip-outbox/seal.ts
+var UnstableCapture = class extends Error {
+};
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function snapshotPath(config, entry, key) {
+  if (!/^(raw\/articles\/|raw\/assets\/)[A-Za-z0-9._/-]+$/.test(key) || key.split("/").some((p) => !p || p === "." || p === "..")) throw new Error("unsafe snapshot key");
+  return join(config.stateRoot, entry.captureId, entry.snapshotId ?? "legacy", "files", key);
+}
+async function durableFile(root, path, bytes) {
+  await mkdir(dirname(path), { recursive: true, mode: 448 });
+  const f = await open(path, "wx", 384);
+  try {
+    await f.writeFile(bytes);
+    await f.sync();
+  } finally {
+    await f.close();
+  }
+  let dir = dirname(path);
+  while (true) {
+    const handle = await open(dir, "r");
+    try {
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    if (dir === root) break;
+    const parent = dirname(dir);
+    if (parent === dir) throw new Error("snapshot directory outside state root");
+    dir = parent;
+  }
+}
+async function sealCapture(config, entry, deps = {}) {
+  entry = { ...entry, snapshotId: randomBytes(8).toString("hex") };
+  const source = entry.source;
+  const inputs = /* @__PURE__ */ new Map();
+  const article = await readRegular(config.root, source, config.maxArticleBytes);
+  inputs.set(source, article);
+  let sourceUrl;
+  const fm = article.toString("utf8").match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (fm) {
+    const metadata = yaml.load(fm[1]);
+    const url = metadata?.source_url ?? metadata?.source;
+    if (typeof url === "string") sourceUrl = url;
+  }
+  const localized = await localizeCapture(article.toString("utf8"), { config, sourceUrl, outboxRoot: config.root, captureId: entry.captureId }, {
+    ...deps,
+    readLocal: async (path) => {
+      const bytes = await readRegular(config.root, path, config.maxImageBytes);
+      inputs.set(path, bytes);
+      return bytes;
+    }
+  });
+  await (deps.delay ?? sleep)(config.stableHashMs);
+  for (const [path, bytes] of inputs) {
+    const next = await readRegular(config.root, path, path === source ? config.maxArticleBytes : config.maxImageBytes);
+    if (sha256Hex(bytes) !== sha256Hex(next)) throw new UnstableCapture("capture changed before seal");
+  }
+  const finalArticle = Buffer.from(localized.markdown);
+  if (finalArticle.length > config.maxArticleBytes) throw new Error("localized article too large");
+  const objects = new Map(localized.assets.map((a) => [a.captureRel, a.bytes]));
+  objects.set(`raw/assets/${entry.captureId}/note.md`, Buffer.from(localized.indexMarkdown));
+  objects.set(entry.articleKey, finalArticle);
+  if ([...objects.values()].reduce((n, b) => n + b.length, 0) > config.maxBundleBytes) throw new Error("sealed bundle too large");
+  await durableFile(config.stateRoot, join(config.stateRoot, entry.captureId, entry.snapshotId, "original.md"), article);
+  for (const [key, bytes] of objects) await durableFile(config.stateRoot, snapshotPath(config, entry, key), bytes);
+  return { ...entry, sourceSha256: sha256Hex(article), assetKeys: [...objects.keys()].filter((k) => k !== entry.articleKey), sha256: Object.fromEntries([...objects].map(([k, b]) => [k, sha256Hex(b)])), sizes: Object.fromEntries([...objects].map(([k, b]) => [k, b.length])), receipts: {}, state: "sealed", reason: void 0, attempts: 0, retryAt: void 0, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
+}
+function admittedArticle(root, path) {
+  const rel = relative2(root, path).replaceAll("\\", "/");
+  if (!rel.startsWith("raw/articles/") || !rel.endsWith(".md")) return false;
+  return rel.split("/").every((part) => part !== "." && part !== ".." && !part.startsWith(".") && !/[\x00-\x1f]/.test(part) && !part.endsWith("~"));
+}
+
+// src/clip-outbox/watcher.ts
+var RESCAN_FLAGS = 1 | 2 | 4 | 8 | 32 | 64 | 128 | 131072;
+var nativeEvents = async (root, onEvent) => {
+  if (process.platform !== "darwin") throw new Error("clip-outbox watch requires macOS FSEvents");
+  const fsevents = createRequire(import.meta.url)("fsevents");
+  return fsevents.watch(root, onEvent);
+};
+async function workerLock(root) {
+  const path = join2(root, ".skillwiki-clip-worker.lock");
+  const owner = `owner-${process.pid}-${randomBytes2(12).toString("hex")}`;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      await mkdir2(path, { mode: 448 });
+      await writeFile(join2(path, owner), "", { mode: 384, flag: "wx" });
+      return async () => {
+        await unlink(join2(path, owner));
+        await rmdir(path);
+      };
+    } catch (e) {
+      if (e.code !== "EEXIST") throw e;
+      const files = await readdir(path);
+      if (files.length !== 1 || !/^owner-[0-9]+-[a-f0-9]+$/.test(files[0])) throw new Error("invalid worker lock");
+      const pid = Number(files[0].split("-")[1]);
+      if (!Number.isSafeInteger(pid) || pid < 1) throw new Error("invalid worker lock");
+      try {
+        process.kill(pid, 0);
+        throw new Error("clip worker already running");
+      } catch (error) {
+        if (error.code !== "ESRCH") throw error;
+      }
+      try {
+        await unlink(join2(path, files[0]));
+        await rmdir(path);
+      } catch (error) {
+        if (!["ENOENT", "ENOTEMPTY"].includes(error.code ?? "")) throw error;
+      }
+    }
+  }
+  throw new Error("clip worker lock unavailable");
+}
+async function startClipWorker(config, deps) {
+  const release = await workerLock(config.root);
+  let stopEvents;
+  let entries = [];
+  const timers = /* @__PURE__ */ new Map();
+  const queued = /* @__PURE__ */ new Set();
+  let chain = Promise.resolve();
+  let stopped = false;
+  let fallback;
+  const save = async (entry) => {
+    entry.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    entries = upsertJournal(entries, entry);
+    await writeJournal(config.stateRoot, entries);
+  };
+  const submit = (fn) => {
+    chain = chain.then(async () => {
+      if (!stopped) await fn();
+    }).catch(() => {
+      stopped = true;
+      deps.onError?.("WORKER_STOPPED");
+    });
+  };
+  const schedule = (path, delay = config.debounceMs) => {
+    if (stopped) return;
+    clearTimeout(timers.get(path));
+    timers.set(path, setTimeout(() => {
+      timers.delete(path);
+      if (queued.has(path)) return;
+      queued.add(path);
+      submit(async () => {
+        queued.delete(path);
+        await processPath(path);
+      });
+    }, Math.max(0, delay)));
+  };
+  const processPath = async (path) => {
+    if (!admittedArticle(config.root, path)) return;
+    let entry = entries.find((e) => e.source === path);
+    if (entry?.state === "conflict") return;
+    if (!entry) {
+      const captureId = randomBytes2(16).toString("hex");
+      const title = basename(path, ".md").replace(/[^A-Za-z0-9_-]/g, "-").slice(0, 100);
+      entry = { captureId, source: path, articleKey: `raw/articles/${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}-${title}-${captureId}.md`, assetKeys: [], sha256: {}, state: "discovered" };
+      await save(entry);
+    }
+    if (entry.sourceSha256) {
+      try {
+        const input = await readRegular(config.root, path, config.maxArticleBytes);
+        if (sha256Hex(input) !== entry.sourceSha256 && entry.reason !== "SEALED_SOURCE_CHANGED") {
+          entry.reason = "SEALED_SOURCE_CHANGED";
+          await save(entry);
+        }
+      } catch {
+        if (entry.reason !== "SEALED_SOURCE_UNAVAILABLE") {
+          entry.reason = "SEALED_SOURCE_UNAVAILABLE";
+          await save(entry);
+        }
+      }
+    }
+    if (entry.state === "central-visible" || entry.state === "mirrored") return;
+    if (entry.state === "held" && entry.sourceSha256) return;
+    await deps.validate?.();
+    try {
+      if (!entry.sourceSha256) {
+        entry.state = "preparing";
+        await save(entry);
+        entry = await (deps.seal ?? sealCapture)(config, entry);
+        await save(entry);
+      }
+      await deps.validate?.();
+      if (entry.state !== "notify-pending" && entry.state !== "article-verified") {
+        for (const key of [...entry.assetKeys, entry.articleKey]) {
+          if (entry.receipts?.[key]) continue;
+          const body = await readRegular(join2(config.stateRoot, entry.captureId), snapshotPath(config, entry, key), config.maxBundleBytes);
+          if (sha256Hex(body) !== entry.sha256[key] || body.length !== entry.sizes?.[key]) throw new Error("SNAPSHOT_CHANGED");
+          await deps.validate?.();
+          const receipt = await deps.put(key, body);
+          if (receipt.status === "conflict") {
+            entry.state = "conflict";
+            entry.reason = "REMOTE_CONFLICT";
+            await save(entry);
+            return;
+          }
+          entry.receipts = { ...entry.receipts, [key]: receipt.status };
+          if (key === entry.articleKey) entry.state = "article-verified";
+          else if (entry.assetKeys.every((k) => entry.receipts?.[k])) entry.state = "assets-verified";
+          await save(entry);
+        }
+      }
+      entry.state = "notify-pending";
+      await save(entry);
+      const result = await deps.ready(buildReadyHint(config.vaultId, [...entry.assetKeys, entry.articleKey].map((key) => ({ path: key, sha256: entry.sha256[key] }))));
+      if (!result.ok) {
+        if ([400, 401, 403, 404, 409, 413].includes(result.status ?? 0)) {
+          entry.state = "held";
+          entry.reason = `READY_HTTP_${result.status}`;
+          await save(entry);
+          return;
+        }
+        throw new Error("READY_RETRY");
+      }
+      entry.state = "central-visible";
+      entry.attempts = 0;
+      entry.retryAt = void 0;
+      await save(entry);
+    } catch (e) {
+      entry.attempts = (entry.attempts ?? 0) + 1;
+      const status = e.$metadata?.httpStatusCode;
+      const unstable = e instanceof UnstableCapture;
+      const persistent = [400, 401, 403].includes(status ?? 0) || e instanceof Error && /SNAPSHOT_CHANGED|TOMBSTONE_HOLD|DELETE_INTENT_UNAVAILABLE/.test(e.message);
+      entry.reason = unstable ? "INPUT_UNSTABLE" : persistent ? "DELIVERY_HELD" : entry.sourceSha256 ? "DELIVERY_RETRY" : "PREPARATION_HELD";
+      if (!entry.sourceSha256 || persistent) entry.state = "held";
+      const delay = Math.min(6e4, 1e3 * 2 ** Math.min(entry.attempts - 1, 6)) * (0.8 + (deps.random ?? Math.random)() * 0.2);
+      entry.retryAt = persistent ? void 0 : Date.now() + delay;
+      await save(entry);
+      if (!persistent) schedule(path, unstable ? config.debounceMs : delay);
+    }
+  };
+  const scan = async () => {
+    await deps.validate?.();
+    const walk = async (dir) => {
+      let children;
+      try {
+        children = await readdir(dir, { withFileTypes: true });
+      } catch (e) {
+        if (e.code === "ENOENT") return;
+        throw e;
+      }
+      for (const child of children) {
+        const path = join2(dir, child.name);
+        if (child.isDirectory() && !child.name.startsWith(".")) await walk(path);
+        else if (child.isFile() && admittedArticle(config.root, path)) schedule(path);
+      }
+    };
+    await walk(join2(config.root, "raw/articles"));
+  };
+  let scanQueued = false;
+  const requestScan = () => {
+    if (scanQueued) return;
+    scanQueued = true;
+    submit(async () => {
+      scanQueued = false;
+      await scan();
+    });
+  };
+  try {
+    entries = await readJournal(config.stateRoot);
+    stopEvents = await (deps.events ?? nativeEvents)(config.root, (path, flags) => {
+      if (flags & RESCAN_FLAGS) {
+        requestScan();
+        return;
+      }
+      const absolute = resolve2(path);
+      if (admittedArticle(config.root, absolute)) schedule(absolute);
+      else if (absolute.startsWith(join2(config.root, "raw/assets") + "/")) {
+        for (const entry of entries) if (!entry.sourceSha256 && entry.source) schedule(entry.source);
+      }
+    });
+    for (const entry of entries) if (entry.source) schedule(entry.source, Math.max(0, (entry.retryAt ?? Date.now()) - Date.now()));
+    await scan();
+    if (config.pollFallbackEnabled) fallback = setInterval(requestScan, config.reconcileSeconds * 1e3);
+    return {
+      entries: () => structuredClone(entries),
+      stop: async () => {
+        stopped = true;
+        for (const timer of timers.values()) clearTimeout(timer);
+        timers.clear();
+        if (fallback) clearInterval(fallback);
+        await stopEvents?.();
+        await chain;
+        await release();
+      }
+    };
+  } catch (e) {
+    stopped = true;
+    for (const timer of timers.values()) clearTimeout(timer);
+    await stopEvents?.();
+    await release();
+    throw e;
+  }
+}
+export {
+  RESCAN_FLAGS,
+  nativeEvents,
+  startClipWorker
+};

package/docs/clip-outbox.md

@@ -0,0 +1,119 @@
+# Clip-outbox worker and attended migration
+
+The channel remains disabled by default. Installing or updating npm ships the
+worker and launchd template; it does not change `clip_outbox.enabled`, load a
+job, import browser settings, or enable wiki-push. `skillwiki doctor` reports
+**clip channel not configured** until attended setup is complete.
+
+After upgrading the CLI, refresh the host plist explicitly:
+
+```sh
+skillwiki clip-outbox install-or-migrate
+skillwiki doctor
+```
+
+This writes or refreshes
+`~/Library/LaunchAgents/com.karlchow.skillwiki-clip-outbox.plist` from the new
+package. It preserves host configuration and does not call launchctl. Existing
+customizations to this dedicated plist are replaced by the packaged template.
+Its arguments use the absolute installed Node executable and npm `skillwiki`
+bin symlink (including `/opt/homebrew/bin/skillwiki`); npm version upgrades keep
+that bin path. WatchPaths expands the configured outbox root. KeepAlive and
+RunAtLoad supervise the worker; WatchPaths only aids wakeup. The actual recursive
+watch is native macOS FSEvents. If Node's installation prefix changes, rerun the
+migration. Installing with `--omit=optional` omits FSEvents and the worker fails
+closed instead of switching to polling.
+
+## Before operator enablement
+
+1. Create/select the dedicated `~/Obsidian/clip-outbox` Obsidian vault, with
+   `raw/articles` and `raw/assets`. Never select `~/wiki`. Import the existing
+   clipper template separately in every browser profile and confirm scratch
+   captures arrive in this outbox. Startup scans discover files already there;
+   move historical backlog elsewhere until an attended exact-file selection is
+   implemented. Do not copy a historical vault into the dedicated outbox.
+2. Configure the existing `clip_outbox.*` namespace: `root`, `state_root`,
+   `mirror_root`, `ready_url`, `s3_credential_ref`, `ready_credential_ref`, and
+   either an inventoried `d8_note_root` or explicit `d8_note_absent=true`.
+   Leave `enabled=false` throughout preparation. State lives outside both
+   vaults, for example `~/Library/Application Support/SkillWiki/clip-outbox`;
+   create its parent first. The resolver enforces disjoint roots and the fixed
+   `central` / `seaweed-wiki:cloud/wiki` destination. The mirror freeze marker
+   must exist and `vault_sync.push_enabled=false` must remain set, with the
+   wiki-push job unloaded.
+3. Install separately scoped credentials in the operator-owned, mode-0600 host
+   file `~/.skillwiki/clip-outbox-credentials.json`. It is a JSON provider map:
+   the name referenced by `s3_credential_ref` maps to an object with `endpoint`,
+   optional `region` (default `us-east-1`), `accessKeyId`, `secretAccessKey`, and
+   optional `sessionToken`; the name referenced by `ready_credential_ref` maps
+   to the separately issued file-ingress token string. References may instead
+   resolve from service environment variables (S3 value is the same JSON object
+   encoded as text). Never place values in a plist, vault page, or command line.
+   Launchd does not inherit an interactive shell's exports, so prefer the
+   protected file for unattended operation. An MCP token is rejected as the
+   file token, including one stored only in the host `.env` file.
+4. Provision S3 permissions for create-only article/asset writes and hash
+   readback, plus read-only access to `wiki/meta/delete-intents/` for the exact
+   path and ancestor admission checks. Missing/unknown delete-intent access
+   blocks publication. Prove concurrent **If-None-Match: \*** creation on the
+   deployed SeaweedFS endpoint: one writer wins, identical retries reuse bytes,
+   different bytes cannot replace them. Verify the destination binding and
+   independent file-ingress notifier token. Local unit tests are not deployed
+   conditional-create evidence.
+5. After those checks, the operator explicitly sets `clip_outbox.enabled=true`
+   using `skillwiki config set`, then explicitly requests loading:
+
+   ```sh
+   skillwiki clip-outbox install-or-migrate --load --conditional-create-proven
+   skillwiki doctor
+   skillwiki clip-outbox status
+   ```
+
+   `--conditional-create-proven` is an operator attestation of the deployed race
+   test, not a test performed by this command. It records a non-secret receipt
+   bound to the endpoint and destination outside the vault. Both flags and the
+   existing enable setting are required for loading. The foreground
+   `skillwiki clip-outbox watch` command requires the same valid configuration
+   and recorded evidence. A different endpoint invalidates the receipt.
+
+## Worker behavior and recovery
+
+The worker subscribes before one startup journal/root scan. FSEvents coalescing,
+directory-level events, overflow/drop/root-change flags trigger a recovery scan.
+Normal file events use 500 ms quiet debounce and matching complete input hashes
+500 ms apart. It localizes images with the existing guarded helper, rechecks the
+article and every referenced local binary, and seals exact snapshots outside
+raw. Original input bytes are retained there too; the capture input is not
+rewritten. New article keys include a date and random capture identity; existing
+local asset paths are preserved. The sibling asset `note.md` is included.
+
+Sealing enters one serial publication queue immediately. Every asset, including
+the index, is conditionally created and read back for SHA-256 verification before
+the article. Each verified object gets a durable journal receipt. Unknown PUT
+outcomes are inspected before retry. Conflicts and auth/admission failures hold
+the item; transient failures use jittered exponential backoff from about one
+second to at most 60 seconds. No minute/hour timer participates in normal
+publication. The optional hourly root scan is recovery only; disable it with
+`clip_outbox.poll_fallback_enabled=false` for an isolated realtime rehearsal.
+
+After article verification, the worker immediately POSTs the v0.10.110 ready
+contract (`vault_id`, `files` with exact paths/hashes) to `/file-ingress/ready`.
+It sends no article or binary content. A failed/unknown hint stays
+`notify-pending`; restart retries that notification without uploading verified
+objects again. Only a verified response accounting for every path records
+`central-visible`. The worker never infers `mirrored`; confirm central pending
+inventory, SSE, exact mirror hashes and image preview separately.
+
+`clip-outbox status` lists capture identities, journal states, redacted reason
+codes and attempts. Edits to an already sealed input report
+`SEALED_SOURCE_CHANGED`; the sealed snapshot and published keys remain fixed.
+A corrupt journal or incomplete worker lock stops startup for attended recovery.
+Do not delete a journal/lock while a worker is running. Queue data and receipts
+are retained indefinitely in this slice (there is no automatic pruning), which
+also preserves the required seven-day minimum and all undelivered/conflicted
+items. Disabling the job retains that evidence; it never deletes cloud raw.
+
+A successful upload proves S3 storage; a successful ready adoption proves
+central materialization. Mirror freshness and pending-source visibility still
+require the isolated end-to-end rollout checks. Neither this migration nor the
+worker unfreezes the mirror, calls wiki_capture, or runs wiki-push.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.110",
+  "version": "0.10.112",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js",
@@ -9,6 +9,7 @@
   "files": [
     "dist",
     "templates",
+    "docs",
     "skills",
     "README.md"
   ],
@@ -42,5 +43,8 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "optionalDependencies": {
+    "fsevents": "^2.3.3"
   }
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.110",
+  "version": "0.10.112",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 22 prompt-only skills (wiki-*, proj-*, using-skillwiki, skillwiki-mcp, skillwiki-connect) backed by the deterministic `skillwiki` CLI.",
   "author": {

package/skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.110",
+  "version": "0.10.112",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 22 prompt-only skills backed by the deterministic skillwiki CLI.",
   "author": {
     "name": "karlorz",