clawvault 3.4.0 → 3.5.0

package/dist/{chunk-QYQAGBTM.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,49 +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 parseContextJson(output, maxResults) {
-  try {
-    const parsed = JSON.parse(output);
-    if (!parsed || !Array.isArray(parsed.context)) return [];
-    return parsed.context.slice(0, maxResults).map((entry) => ({
-      title: sanitizeForDisplay(entry.title ?? "Untitled"),
-      path: sanitizeForDisplay(entry.path ?? ""),
-      age: sanitizeForDisplay(entry.age ?? "unknown age"),
-      snippet: truncateSnippet(String(entry.snippet ?? "")),
-      score: Number.isFinite(Number(entry.score)) ? Number(entry.score) : 0
-    })).filter((entry) => entry.snippet.length > 0);
-  } catch {
-    return [];
-  }
-}
-function parseSessionRecapJson(output, maxResults) {
-  try {
-    const parsed = JSON.parse(output);
-    if (!parsed || !Array.isArray(parsed.messages)) return [];
-    return parsed.messages.map((entry) => {
-      const role = typeof entry.role === "string" ? entry.role.toLowerCase() : "";
-      if (role !== "user" && role !== "assistant") return null;
-      const text = truncateRecapSnippet(typeof entry.text === "string" ? entry.text : "");
-      if (!text) return null;
-      return {
-        role: role === "user" ? "User" : "Assistant",
-        text
-      };
-    }).filter((entry) => Boolean(entry)).slice(-maxResults);
-  } catch {
-    return [];
-  }
-}
 function formatSessionContextInjection(recapEntries, memoryEntries) {
   const lines = [
     "[ClawVault] Session context restored:",
@@ -953,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);
 }
@@ -1051,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);
@@ -1132,8 +1115,8 @@ function toSafeFilePath(vaultPath, relPath) {
   if (!mapped || mapped.includes("..")) {
     throw new Error("Invalid memory path");
   }
-  if (mapped !== "MEMORY.md" && !mapped.startsWith("memory/")) {
-    throw new Error("memory_get only allows MEMORY.md or memory/* paths");
+  if (!mapped.toLowerCase().endsWith(".md")) {
+    throw new Error("memory_get only allows Markdown note paths inside the vault");
   }
   const absolute = path4.resolve(vaultPath, mapped);
   const vaultRootWithSep = vaultPath.endsWith(path4.sep) ? vaultPath : `${vaultPath}${path4.sep}`;
@@ -1260,8 +1243,17 @@ function buildToolSchema(properties, required = []) {
     additionalProperties: false
   };
 }
+function resolveToolInput(toolCallIdOrInput, maybeInput) {
+  if (maybeInput && typeof maybeInput === "object" && !Array.isArray(maybeInput)) {
+    return maybeInput;
+  }
+  if (toolCallIdOrInput && typeof toolCallIdOrInput === "object" && !Array.isArray(toolCallIdOrInput)) {
+    return toolCallIdOrInput;
+  }
+  return {};
+}
 function createMemorySearchToolFactory(memoryManager) {
-  return () => {
+  return (_toolContext) => {
     const inputSchema = buildToolSchema({
       query: {
         type: "string",
@@ -1284,7 +1276,8 @@ function createMemorySearchToolFactory(memoryManager) {
         description: "Optional OpenClaw session key for scoped recall."
       }
     }, ["query"]);
-    const execute = async (input) => {
+    const execute = async (toolCallIdOrInput, maybeInput) => {
+      const input = resolveToolInput(toolCallIdOrInput, maybeInput);
       const query = typeof input.query === "string" ? input.query : "";
       if (!query.trim()) {
         return { query, count: 0, results: [] };
@@ -1301,6 +1294,7 @@ function createMemorySearchToolFactory(memoryManager) {
       };
     };
     return {
+      label: "Memory Search",
       name: "memory_search",
       description: "Search ClawVault memory for relevant snippets before answering.",
       inputSchema,
@@ -1313,11 +1307,15 @@ function createMemorySearchToolFactory(memoryManager) {
   };
 }
 function createMemoryGetToolFactory(memoryManager) {
-  return () => {
+  return (_toolContext) => {
     const inputSchema = buildToolSchema({
+      path: {
+        type: "string",
+        description: "Relative path from memory_search result (for OpenClaw compatibility)."
+      },
       relPath: {
         type: "string",
-        description: "Relative path from memory_search result (e.g. memory/2026-01-01.md)."
+        description: "Alias of path (e.g. memory/2026-01-01.md)."
       },
       from: {
         type: "number",
@@ -1330,9 +1328,11 @@ function createMemoryGetToolFactory(memoryManager) {
         maximum: 400,
         description: "Optional number of lines to read."
       }
-    }, ["relPath"]);
-    const execute = async (input) => {
-      const relPath = typeof input.relPath === "string" ? input.relPath : "";
+    });
+    inputSchema.anyOf = [{ required: ["path"] }, { required: ["relPath"] }];
+    const execute = async (toolCallIdOrInput, maybeInput) => {
+      const input = resolveToolInput(toolCallIdOrInput, maybeInput);
+      const relPath = typeof input.path === "string" ? input.path : typeof input.relPath === "string" ? input.relPath : "";
       if (!relPath.trim()) {
         return { path: relPath, text: "" };
       }
@@ -1343,6 +1343,7 @@ function createMemoryGetToolFactory(memoryManager) {
       });
     };
     return {
+      label: "Memory Get",
       name: "memory_get",
       description: "Read a specific memory file or line range from ClawVault.",
       inputSchema,
@@ -1467,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);
@@ -1495,27 +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: results.map((result) => toContextEntry(vaultPath, result)).filter((entry) => entry.snippet.length > 0),
+      vaultPath
+    };
+  } catch {
     return { entries: [], vaultPath };
   }
-  return {
-    entries: parseContextJson(contextResult.output, maxResults),
-    vaultPath
-  };
 }
 async function buildVaultContextInjection(options) {
   const [recapEntries, memoryResult] = await Promise.all([
@@ -1637,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 });
   }
@@ -1763,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");
   }
@@ -1776,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 {
@@ -1853,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");
   }
@@ -1912,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");
     }
   }
@@ -2007,8 +2028,10 @@ async function registerOpenClawPlugin(api) {
       warn: api.logger.warn
     }
   });
-  api.registerTool(createMemorySearchToolFactory(memoryManager), { name: "memory_search" });
-  api.registerTool(createMemoryGetToolFactory(memoryManager), { name: "memory_get" });
+  const memorySearchTool = createMemorySearchToolFactory(memoryManager)();
+  const memoryGetTool = createMemoryGetToolFactory(memoryManager)();
+  api.registerTool(memorySearchTool, { name: "memory_search" });
+  api.registerTool(memoryGetTool, { name: "memory_get" });
   api.on("before_prompt_build", createBeforePromptBuildHandler({
     pluginConfig,
     runtimeState

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-QYQAGBTM.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-QYQAGBTM.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.