clawvault 3.4.1 → 3.5.0

package/dist/{chunk-PLNK37JD.js → chunk-QUFQBAHP.js}

@@ -1,6 +1,19 @@
 import {
   buildRecallResult
 } from "./chunk-RL2L6I6K.js";
+import {
+  recover
+} from "./chunk-OIWVQYQF.js";
+import {
+  formatAge
+} from "./chunk-7ZRP733D.js";
+import {
+  buildSessionRecap
+} from "./chunk-ZKGY7WTT.js";
+import {
+  checkpoint,
+  flush
+} from "./chunk-F55HGNU4.js";
 import {
   synthesizeEntityProfiles
 } from "./chunk-NSXYM6EZ.js";
@@ -707,7 +720,7 @@ import * as fs4 from "fs";
 import * as path4 from "path";
 
 // src/plugin/clawvault-cli.ts
-import { execFileSync } from "child_process";
+import { execFileSync, spawn } from "child_process";
 import * as fs3 from "fs";
 import * as path3 from "path";
 
@@ -806,8 +819,6 @@ function verifyExecutableIntegrity(executablePath, expectedSha256) {
 
 // src/plugin/clawvault-cli.ts
 var MAX_CONTEXT_PROMPT_LENGTH = 500;
-var MAX_CONTEXT_SNIPPET_LENGTH = 220;
-var MAX_RECAP_SNIPPET_LENGTH = 220;
 var CLAWVAULT_EXECUTABLE = "clawvault";
 var ONE_KIB = 1024;
 var ONE_MIB = ONE_KIB * ONE_KIB;
@@ -823,139 +834,6 @@ function sanitizePromptForContext(value) {
   if (typeof value !== "string") return "";
   return value.replace(/[\x00-\x1f\x7f]/g, " ").replace(/\s+/g, " ").trim().slice(0, MAX_CONTEXT_PROMPT_LENGTH);
 }
-function truncateSnippet(snippet) {
-  const safe = sanitizeForDisplay(snippet).replace(/\s+/g, " ").trim();
-  if (safe.length <= MAX_CONTEXT_SNIPPET_LENGTH) return safe;
-  return `${safe.slice(0, MAX_CONTEXT_SNIPPET_LENGTH - 3).trimEnd()}...`;
-}
-function truncateRecapSnippet(snippet) {
-  const safe = sanitizeForDisplay(snippet).replace(/\s+/g, " ").trim();
-  if (safe.length <= MAX_RECAP_SNIPPET_LENGTH) return safe;
-  return `${safe.slice(0, MAX_RECAP_SNIPPET_LENGTH - 3).trimEnd()}...`;
-}
-function isRecord2(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-function parseTopLevelJson(output) {
-  const text = output.trim();
-  if (!text) return null;
-  const tryParse = (candidate) => {
-    try {
-      const parsed = JSON.parse(candidate);
-      return isRecord2(parsed) ? parsed : null;
-    } catch {
-      return null;
-    }
-  };
-  const direct = tryParse(text);
-  if (direct) return direct;
-  const findJsonEnd = (start) => {
-    const open = text[start];
-    if (open !== "{" && open !== "[") return -1;
-    const stack = [open];
-    let inString = false;
-    let escaped = false;
-    for (let i = start + 1; i < text.length; i += 1) {
-      const ch = text[i];
-      if (inString) {
-        if (escaped) {
-          escaped = false;
-          continue;
-        }
-        if (ch === "\\") {
-          escaped = true;
-          continue;
-        }
-        if (ch === '"') {
-          inString = false;
-        }
-        continue;
-      }
-      if (ch === '"') {
-        inString = true;
-        continue;
-      }
-      if (ch === "{" || ch === "[") {
-        stack.push(ch);
-        continue;
-      }
-      if (ch === "}" || ch === "]") {
-        const expected = ch === "}" ? "{" : "[";
-        const top = stack[stack.length - 1];
-        if (top !== expected) return -1;
-        stack.pop();
-        if (stack.length === 0) {
-          return i;
-        }
-      }
-    }
-    return -1;
-  };
-  for (let start = 0; start < text.length; start += 1) {
-    const ch = text[start];
-    if (ch !== "{" && ch !== "[") continue;
-    const end = findJsonEnd(start);
-    if (end < 0) continue;
-    const parsed = tryParse(text.slice(start, end + 1));
-    if (parsed) return parsed;
-  }
-  return null;
-}
-function resolveEntryArray(parsed, keys) {
-  for (const key of keys) {
-    const value = parsed[key];
-    if (!Array.isArray(value)) continue;
-    return value.filter((item) => isRecord2(item));
-  }
-  return [];
-}
-function parseContextJson(output, maxResults) {
-  const parsed = parseTopLevelJson(output);
-  if (!parsed) {
-    return [];
-  }
-  const rows = resolveEntryArray(parsed, ["context", "results", "entries", "memories"]);
-  return rows.slice(0, maxResults).map((entry) => {
-    const nestedDocument = isRecord2(entry.document) ? entry.document : null;
-    const title = sanitizeForDisplay(
-      entry.title ?? nestedDocument?.title ?? nestedDocument?.id ?? entry.path ?? "Untitled"
-    );
-    const resolvedPath = sanitizeForDisplay(
-      entry.path ?? entry.relPath ?? nestedDocument?.path ?? ""
-    );
-    const resolvedAge = sanitizeForDisplay(entry.age ?? entry.modified ?? "unknown age");
-    const snippetSource = String(
-      entry.snippet ?? entry.text ?? entry.content ?? nestedDocument?.snippet ?? nestedDocument?.content ?? ""
-    );
-    return {
-      title,
-      path: resolvedPath,
-      age: resolvedAge,
-      snippet: truncateSnippet(snippetSource),
-      score: Number.isFinite(Number(entry.score)) ? Number(entry.score) : 0
-    };
-  }).filter((entry) => entry.snippet.length > 0);
-}
-function parseSessionRecapJson(output, maxResults) {
-  const parsed = parseTopLevelJson(output);
-  if (!parsed) {
-    return [];
-  }
-  const rows = resolveEntryArray(parsed, ["messages", "turns", "recap"]);
-  return rows.map((entry) => {
-    const role = typeof entry.role === "string" ? entry.role.toLowerCase() : "";
-    const normalizedRole = role === "user" || role === "human" ? "User" : role === "assistant" || role === "ai" ? "Assistant" : "";
-    if (!normalizedRole) return null;
-    const text = truncateRecapSnippet(
-      typeof entry.text === "string" ? entry.text : typeof entry.content === "string" ? entry.content : ""
-    );
-    if (!text) return null;
-    return {
-      role: normalizedRole,
-      text
-    };
-  }).filter((entry) => Boolean(entry)).slice(-maxResults);
-}
 function formatSessionContextInjection(recapEntries, memoryEntries) {
   const lines = [
     "[ClawVault] Session context restored:",
@@ -1043,22 +921,6 @@ function runClawvault(args, pluginConfig, options = {}) {
     };
   }
 }
-function parseRecoveryOutput(output) {
-  if (!output || typeof output !== "string") {
-    return { hadDeath: false, workingOn: null };
-  }
-  const hadDeath = output.includes("Context death detected") || output.includes("died") || output.includes("\u26A0\uFE0F");
-  if (!hadDeath) {
-    return { hadDeath: false, workingOn: null };
-  }
-  const workingOnLine = output.split("\n").find((line) => line.toLowerCase().includes("working on"));
-  if (!workingOnLine) {
-    return { hadDeath: true, workingOn: null };
-  }
-  const parts = workingOnLine.split(":");
-  const workingOn = parts.length > 1 ? sanitizeForDisplay(parts.slice(1).join(":").trim()) : null;
-  return { hadDeath: true, workingOn: workingOn || null };
-}
 function getObserveCursorPath(vaultPath) {
   return path3.join(vaultPath, ".clawvault", OBSERVE_CURSOR_FILE);
 }
@@ -1141,12 +1003,43 @@ function shouldObserveActiveSessions(vaultPath, agentId, pluginConfig) {
   return false;
 }
 function runObserverCron(vaultPath, agentId, pluginConfig, options = {}) {
+  if (!isOptInEnabled(pluginConfig, "allowClawvaultExec")) {
+    return false;
+  }
   const args = ["observe", "--cron", "--agent", agentId, "-v", vaultPath];
   if (Number.isFinite(options.minNewBytes) && Number(options.minNewBytes) > 0) {
     args.push("--min-new", String(Math.floor(Number(options.minNewBytes))));
   }
-  const result = runClawvault(args, pluginConfig, { timeoutMs: 12e4 });
-  return !result.skipped && result.success;
+  const executablePath = resolveExecutablePath(CLAWVAULT_EXECUTABLE, {
+    explicitPath: getConfiguredExecutablePath(pluginConfig)
+  });
+  if (!executablePath) {
+    return false;
+  }
+  const expectedSha256 = getConfiguredExecutableSha256(pluginConfig);
+  const integrityResult = verifyExecutableIntegrity(executablePath, expectedSha256);
+  if (!integrityResult.ok) {
+    return false;
+  }
+  let sanitizedArgs;
+  try {
+    sanitizedArgs = sanitizeExecArgs(args);
+  } catch {
+    return false;
+  }
+  try {
+    const child = spawn(executablePath, sanitizedArgs, {
+      detached: process.platform !== "win32",
+      stdio: "ignore",
+      shell: false
+    });
+    child.on("error", () => {
+    });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
 }
 function resolveSessionKey(input) {
   return sanitizeSessionKey(input);
@@ -1575,20 +1468,51 @@ function rewriteQuestionWithMemoryEvidence(originalContent, memoryHits) {
 }
 
 // src/plugin/vault-context-injector.ts
+import * as path5 from "path";
 var DEFAULT_MAX_CONTEXT_RESULTS = 4;
 var DEFAULT_MAX_RECAP_RESULTS = 6;
+var DEFAULT_MIN_CONTEXT_SCORE = 0.2;
+function normalizeRelativePath(vaultPath, absolutePath) {
+  const relativePath = path5.relative(vaultPath, absolutePath).replace(/\\/g, "/");
+  if (!relativePath || relativePath.startsWith("..")) {
+    return path5.basename(absolutePath);
+  }
+  return relativePath;
+}
+function formatContextAge(modified) {
+  const ageMs = Date.now() - modified.getTime();
+  return `${formatAge(ageMs)} ago`;
+}
+function toContextEntry(vaultPath, result) {
+  const relativePath = normalizeRelativePath(vaultPath, result.document.path);
+  return {
+    title: sanitizeForDisplay(result.document.title || "Untitled"),
+    path: sanitizeForDisplay(relativePath),
+    age: sanitizeForDisplay(formatContextAge(result.document.modified)),
+    snippet: sanitizeForDisplay(result.snippet).replace(/\s+/g, " ").trim().slice(0, 220),
+    score: Number.isFinite(Number(result.score)) ? Number(result.score) : 0
+  };
+}
+function truncateRecapText(text) {
+  const cleaned = sanitizeForDisplay(text).replace(/\s+/g, " ").trim();
+  if (cleaned.length <= 220) return cleaned;
+  return `${cleaned.slice(0, 217).trimEnd()}...`;
+}
 async function fetchSessionRecapEntries(options) {
   const sessionKey = resolveSessionKey(options.sessionKey);
   if (!sessionKey) return [];
-  const recapArgs = ["session-recap", sessionKey, "--format", "json"];
-  if (options.agentId) {
-    recapArgs.push("--agent", options.agentId);
-  }
-  const recapResult = runClawvault(recapArgs, options.pluginConfig, { timeoutMs: 2e4 });
-  if (!recapResult.success) {
+  try {
+    const recap = await buildSessionRecap(sessionKey, {
+      limit: DEFAULT_MAX_RECAP_RESULTS,
+      agentId: options.agentId
+    });
+    return recap.messages.slice(-DEFAULT_MAX_RECAP_RESULTS).map((message) => ({
+      role: message.role === "user" ? "User" : "Assistant",
+      text: truncateRecapText(message.text)
+    })).filter((message) => message.text.length > 0);
+  } catch {
     return [];
   }
-  return parseSessionRecapJson(recapResult.output, DEFAULT_MAX_RECAP_RESULTS);
 }
 async function fetchMemoryContextEntries(options) {
   const prompt = sanitizePromptForContext(options.prompt);
@@ -1603,43 +1527,21 @@ async function fetchMemoryContextEntries(options) {
     return { entries: [], vaultPath: null };
   }
   const maxResults = Number.isFinite(options.maxResults) ? Math.max(1, Math.min(20, Number(options.maxResults))) : DEFAULT_MAX_CONTEXT_RESULTS;
-  const profile = options.contextProfile ?? options.pluginConfig.contextProfile ?? "auto";
-  const contextArgs = [
-    "context",
-    prompt,
-    "--format",
-    "json",
-    "--profile",
-    profile,
-    "--limit",
-    String(maxResults),
-    "-v",
-    vaultPath
-  ];
-  const contextResult = runClawvault(contextArgs, options.pluginConfig, { timeoutMs: 25e3 });
-  if (contextResult.success) {
+  try {
+    const vault = new ClawVault(vaultPath);
+    await vault.load();
+    const results = await vault.find(prompt, {
+      limit: maxResults,
+      minScore: DEFAULT_MIN_CONTEXT_SCORE,
+      temporalBoost: true
+    });
     return {
-      entries: parseContextJson(contextResult.output, maxResults),
+      entries: results.map((result) => toContextEntry(vaultPath, result)).filter((entry) => entry.snippet.length > 0),
       vaultPath
     };
-  }
-  const fallbackSearchArgs = [
-    "search",
-    prompt,
-    "--json",
-    "-n",
-    String(maxResults),
-    "-v",
-    vaultPath
-  ];
-  const fallbackSearchResult = runClawvault(fallbackSearchArgs, options.pluginConfig, { timeoutMs: 25e3 });
-  if (!fallbackSearchResult.success) {
+  } catch {
     return { entries: [], vaultPath };
   }
-  return {
-    entries: parseContextJson(fallbackSearchResult.output, maxResults),
-    vaultPath
-  };
 }
 async function buildVaultContextInjection(options) {
   const [recapEntries, memoryResult] = await Promise.all([
@@ -1761,13 +1663,13 @@ function createMessageSendingHandler(dependencies) {
 
 // src/plugin/fact-extractor.ts
 import * as fs5 from "fs";
-import * as path5 from "path";
+import * as path6 from "path";
 import { createHash as createHash2 } from "crypto";
 var FACTS_FILE = "facts.jsonl";
 var ENTITY_GRAPH_FILE = "entity-graph.json";
 var MAX_TEXT_LENGTH = 6e3;
 function ensureClawVaultDir(vaultPath) {
-  const dir = path5.join(vaultPath, ".clawvault");
+  const dir = path6.join(vaultPath, ".clawvault");
   if (!fs5.existsSync(dir)) {
     fs5.mkdirSync(dir, { recursive: true });
   }
@@ -1887,7 +1789,7 @@ function buildEntityGraph(facts) {
   };
 }
 function ensureFactsLogFile(vaultPath) {
-  const filePath = path5.join(ensureClawVaultDir(vaultPath), FACTS_FILE);
+  const filePath = path6.join(ensureClawVaultDir(vaultPath), FACTS_FILE);
   if (!fs5.existsSync(filePath)) {
     fs5.writeFileSync(filePath, "", "utf-8");
   }
@@ -1900,7 +1802,7 @@ function persistFactsAndGraph(vaultPath, extractedFacts) {
   store.save();
   const allFacts = store.getAllFacts();
   const graph = buildEntityGraph(allFacts);
-  const graphPath = path5.join(ensureClawVaultDir(vaultPath), ENTITY_GRAPH_FILE);
+  const graphPath = path6.join(ensureClawVaultDir(vaultPath), ENTITY_GRAPH_FILE);
   fs5.writeFileSync(graphPath, `${JSON.stringify(graph, null, 2)}
 `, "utf-8");
   return {
@@ -1977,19 +1879,16 @@ async function handleGatewayStart(event, ctx, deps) {
     deps.logger?.warn("[clawvault] No vault found, skipping startup recovery");
     return;
   }
-  const result = runClawvault(["recover", "--clear", "-v", vaultPath], deps.pluginConfig, {
-    timeoutMs: 2e4
-  });
-  if (result.skipped) {
-    return;
-  }
-  if (!result.success) {
+  let recoveryResult;
+  try {
+    recoveryResult = await recover(vaultPath, { clearFlag: true });
+  } catch {
     deps.logger?.warn("[clawvault] Startup recovery command failed");
     return;
   }
-  const parsed = parseRecoveryOutput(result.output);
-  if (parsed.hadDeath) {
-    const message = parsed.workingOn ? `[ClawVault] Context death detected. Last working on: ${parsed.workingOn}. Run \`clawvault wake\` for full recovery context.` : "[ClawVault] Context death detected. Run `clawvault wake` for full recovery context.";
+  if (recoveryResult.died) {
+    const lastWorkingOn = typeof recoveryResult.checkpoint?.workingOn === "string" ? recoveryResult.checkpoint.workingOn.trim() : "";
+    const message = lastWorkingOn ? `[ClawVault] Context death detected. Last working on: ${lastWorkingOn}. Run \`clawvault wake\` for full recovery context.` : "[ClawVault] Context death detected. Run `clawvault wake` for full recovery context.";
     deps.runtimeState.setStartupRecoveryNotice(message);
     deps.logger?.warn("[clawvault] Context death detected at startup");
   }
@@ -2036,16 +1935,14 @@ async function handleBeforeReset(event, ctx, deps) {
   if (autoCheckpointEnabled) {
     const safeSessionKey = sanitizeForCheckpoint(sessionKey, 120);
     const safeReason = sanitizeForCheckpoint(event.reason ?? "before_reset", 80);
-    const checkpointResult = runClawvault([
-      "checkpoint",
-      "--working-on",
-      `Session reset via ${safeReason}`,
-      "--focus",
-      `Pre-reset checkpoint, session: ${safeSessionKey}`,
-      "-v",
-      vaultPath
-    ], deps.pluginConfig, { timeoutMs: 3e4 });
-    if (!checkpointResult.success && !checkpointResult.skipped) {
+    try {
+      await checkpoint({
+        workingOn: `Session reset via ${safeReason}`,
+        focus: `Pre-reset checkpoint, session: ${safeSessionKey}`,
+        vaultPath
+      });
+      await flush();
+    } catch {
       deps.logger?.warn("[clawvault] Auto-checkpoint before reset failed");
     }
   }

package/dist/cli/index.js

@@ -11,7 +11,6 @@ import "../chunk-D5U3Q4N5.js";
 import "../chunk-BLQXXX7Q.js";
 import "../chunk-VXAGOLDP.js";
 import "../chunk-7SWP5FKU.js";
-import "../chunk-HRLWZGMA.js";
 import "../chunk-DVOUSOR3.js";
 import "../chunk-4PY655YM.js";
 import "../chunk-AXSJIFOJ.js";
@@ -20,6 +19,7 @@ import "../chunk-T7E764W3.js";
 import "../chunk-HEHO7SMV.js";
 import "../chunk-2PKBIKDH.js";
 import "../chunk-35JCYSRR.js";
+import "../chunk-HRLWZGMA.js";
 import "../chunk-BSJ6RIT7.js";
 import "../chunk-ECGJYWNA.js";
 import "../chunk-2CDEETQN.js";

package/dist/commands/compat.js

@@ -2,7 +2,7 @@ import {
   checkOpenClawCompatibility,
   compatCommand,
   compatibilityExitCode
-} from "../chunk-X3SPPUFG.js";
+} from "../chunk-JI7VUQV7.js";
 import "../chunk-2ZDO52B4.js";
 export {
   checkOpenClawCompatibility,

package/dist/commands/observe.js

@@ -4,10 +4,10 @@ import {
 } from "../chunk-BLQXXX7Q.js";
 import "../chunk-VXAGOLDP.js";
 import "../chunk-7SWP5FKU.js";
-import "../chunk-HRLWZGMA.js";
 import "../chunk-DVOUSOR3.js";
 import "../chunk-4PY655YM.js";
 import "../chunk-AXSJIFOJ.js";
+import "../chunk-HRLWZGMA.js";
 import "../chunk-BSJ6RIT7.js";
 import "../chunk-2CDEETQN.js";
 import "../chunk-GJO3CFUN.js";

package/dist/commands/status.js

@@ -1,18 +1,18 @@
-import {
-  formatAge
-} from "../chunk-7ZRP733D.js";
 import {
   scanVaultLinks
 } from "../chunk-7YZWHM36.js";
 import "../chunk-J7ZWCI2C.js";
+import {
+  formatAge
+} from "../chunk-7ZRP733D.js";
 import {
   getObserverStaleness
 } from "../chunk-VXAGOLDP.js";
 import "../chunk-7SWP5FKU.js";
-import "../chunk-HRLWZGMA.js";
 import "../chunk-DVOUSOR3.js";
 import "../chunk-4PY655YM.js";
 import "../chunk-AXSJIFOJ.js";
+import "../chunk-HRLWZGMA.js";
 import "../chunk-BSJ6RIT7.js";
 import {
   ClawVault

package/dist/index.js

@@ -13,11 +13,6 @@ import {
   registerReplayCommand,
   replayCommand
 } from "./chunk-HGDDW24U.js";
-import {
-  buildSessionRecap,
-  formatSessionRecapMarkdown,
-  sessionRecapCommand
-} from "./chunk-ZKGY7WTT.js";
 import {
   setupCommand
 } from "./chunk-EL6UBSX5.js";
@@ -40,7 +35,7 @@ import {
   checkOpenClawCompatibility,
   compatCommand,
   compatibilityExitCode
-} from "./chunk-X3SPPUFG.js";
+} from "./chunk-JI7VUQV7.js";
 import {
   doctor
 } from "./chunk-CSHO3PJB.js";
@@ -60,11 +55,19 @@ import {
   openclaw_plugin_default,
   plausibilityScore,
   registerMemorySlot
-} from "./chunk-PLNK37JD.js";
+} from "./chunk-QUFQBAHP.js";
 import {
   buildRecallResult,
   classifyRecallQuery
 } from "./chunk-RL2L6I6K.js";
+import "./chunk-OIWVQYQF.js";
+import "./chunk-7ZRP733D.js";
+import {
+  buildSessionRecap,
+  formatSessionRecapMarkdown,
+  sessionRecapCommand
+} from "./chunk-ZKGY7WTT.js";
+import "./chunk-F55HGNU4.js";
 import {
   ensureEntityProfiles,
   readEntityProfile,
@@ -146,7 +149,6 @@ import {
   createLlmFunction,
   resolveFactExtractionMode
 } from "./chunk-7SWP5FKU.js";
-import "./chunk-HRLWZGMA.js";
 import {
   requestLlmCompletion,
   resolveLlmProvider
@@ -192,6 +194,7 @@ import {
 } from "./chunk-HEHO7SMV.js";
 import "./chunk-2PKBIKDH.js";
 import "./chunk-35JCYSRR.js";
+import "./chunk-HRLWZGMA.js";
 import {
   FactStore,
   extractFactsLlm,

package/dist/openclaw-plugin.js

@@ -1,10 +1,15 @@
 import {
   createMemorySlotPlugin,
   openclaw_plugin_default
-} from "./chunk-PLNK37JD.js";
+} from "./chunk-QUFQBAHP.js";
 import "./chunk-RL2L6I6K.js";
+import "./chunk-OIWVQYQF.js";
+import "./chunk-7ZRP733D.js";
+import "./chunk-ZKGY7WTT.js";
+import "./chunk-F55HGNU4.js";
 import "./chunk-NSXYM6EZ.js";
 import "./chunk-35JCYSRR.js";
+import "./chunk-HRLWZGMA.js";
 import "./chunk-BSJ6RIT7.js";
 import "./chunk-ECGJYWNA.js";
 import "./chunk-2CDEETQN.js";

package/docs/clawhub-security-release-playbook.md

@@ -0,0 +1,75 @@
+# ClawHub Security Release Playbook
+
+This playbook captures what kept the ClawHub/OpenClaw security review stable for `clawvault` and what repeatedly caused "suspicious" regressions.
+
+## Goal
+
+Keep ClawHub scanner classification at least `Benign` by ensuring bundle metadata, SKILL frontmatter, and shipped files stay consistent.
+
+## Known-good frontmatter contract
+
+Use compact, parser-safe frontmatter with documented keys only:
+
+- `name`, `description`, `author`, `source`, `repository`, `homepage`
+- `user-invocable`
+- `openclaw` (single-line JSON object)
+- `metadata` (single-line JSON object with `openclaw`)
+
+For `openclaw` and `metadata.openclaw`, use only documented fields:
+
+- `emoji`
+- `requires.bins`
+- `requires.env` (can be `[]` if no required env vars)
+- `install` (installer spec array)
+- `homepage`
+
+Avoid non-spec keys inside `openclaw` metadata (for example ad-hoc fields such as `env_optional`), because strict scanners may treat the metadata block as invalid and fall back to "no requirements/install spec".
+
+## Bundle composition
+
+Always publish a minimal auditable bundle:
+
+- `SKILL.md`
+- `openclaw.plugin.json`
+- `dist/openclaw-plugin.js`
+
+If plugin manifest/runtime files are missing from the published bundle, scanners flag visibility/supply-chain concerns.
+
+## Required pre-publish checks
+
+1. Validate SKILL frontmatter is single-line JSON for `openclaw` and `metadata`.
+2. Confirm runtime dependencies are declared in both:
+   - frontmatter metadata (`requires.bins`, `install`)
+   - human docs in SKILL (`Install (Canonical)`, safe install flow)
+3. Confirm `source` and `homepage` fields are present and accurate.
+4. Confirm plugin manifest/runtime paths referenced in SKILL exist in the bundle.
+
+## Publish + verify workflow
+
+1. Publish skill patch version to ClawHub.
+2. Wait for propagation (`clawhub inspect` can temporarily return `Skill not found`).
+3. Verify metadata and files:
+   - `npx clawhub inspect clawvault --file SKILL.md`
+   - `npx clawhub inspect clawvault --files`
+4. Verify page classification in browser snapshot (not just CLI):
+   - Open `https://clawhub.ai/G9Pedro/clawvault`
+   - Confirm status badge is `Benign` (or better) and review details.
+
+## If scanner regresses
+
+If warning text mentions mismatch between registry metadata and SKILL/docs:
+
+1. Compare scanner claim to frontmatter values first.
+2. Remove unsupported keys from metadata block.
+3. Re-publish patch version with normalized metadata.
+4. Re-check in browser after propagation.
+
+## Security posture notes
+
+Even with clean metadata, this skill can still receive cautionary language because it:
+
+- runs plugin lifecycle handlers,
+- reads/modifies OpenClaw session files,
+- and relies on external CLI packages (`clawvault`, `qmd`).
+
+That caution is expected and should be addressed with transparent docs, explicit safe-install guidance, and auditable shipped plugin code.