caveat-cli 0.6.0 → 0.6.2

package/dist/index.js

@@ -16095,7 +16095,11 @@ function resolvePaths(caveatHome, knowledgeRepo, userHome) {
     knowledgeRepo: resolved,
     dbPath: join5(caveatHome, "index", "caveat.db"),
     entriesDir: join5(resolved, "entries"),
-    communityDir: join5(resolved, "community")
+    // community/ lives at caveatHome level, NOT inside knowledgeRepo. Community
+    // clones are external knowledge caches — not semantically "owned" by the
+    // user — and they embed their own .git dirs which would otherwise nest
+    // inside the user's git-tracked knowledge repo.
+    communityDir: join5(caveatHome, "community")
   };
 }
 
@@ -21233,6 +21237,12 @@ async function pushEntry(opts) {
       detail: `entry id=${opts.id} not found under ${opts.entriesDir}`
     };
   }
+  if (owned.visibility === "private") {
+    return {
+      status: "visibility-private",
+      detail: `entry id=${opts.id} has visibility: private and cannot be pushed to the public community DB. Update the entry to visibility: public first (the user declared this entry local-only).`
+    };
+  }
   const ghUser = resolveGhUser();
   if (!ghUser) {
     return { status: "failed", detail: "gh api user failed" };
@@ -21253,16 +21263,16 @@ async function pushEntry(opts) {
     const stagingDir = forkStagingDir(opts.caveatHome);
     ensureStagingClone(stagingDir, ghUser, sharedName, sharedOwner);
     const branch = `caveat-push-${owned.id}-${Date.now().toString(36)}`;
-    run("git", ["checkout", "-b", branch], { cwd: stagingDir });
+    runOrThrow("git", ["checkout", "-b", branch], { cwd: stagingDir });
     const destPath = join7(stagingDir, "entries", owned.relPath);
     mkdirSync3(dirname4(destPath), { recursive: true });
     copyFileSync(owned.absPath, destPath);
-    run("git", ["add", join7("entries", owned.relPath)], { cwd: stagingDir });
+    runOrThrow("git", ["add", join7("entries", owned.relPath)], { cwd: stagingDir });
     const isUpdate = upstreamAlreadyHas(stagingDir, "entries/" + owned.relPath);
     const verb = isUpdate ? "update" : "add";
     const commitMsg = `${verb}: ${owned.title}`;
-    run("git", ["commit", "-m", commitMsg], { cwd: stagingDir });
-    run("git", ["push", "--set-upstream", "origin", branch], { cwd: stagingDir });
+    runOrThrow("git", ["commit", "-m", commitMsg], { cwd: stagingDir });
+    runOrThrow("git", ["push", "--set-upstream", "origin", branch], { cwd: stagingDir });
     const prTitle = `${verb}: ${owned.title}`;
     const prBody = [
       `Contribution of caveat \`${owned.id}\` via \`caveat push\`.`,
@@ -21272,7 +21282,7 @@ async function pushEntry(opts) {
       "",
       "Merged PRs will appear in subscribers' repos on their next `caveat pull`."
     ].join("\n");
-    const pr = spawnSync(
+    const pr = runCapture(
       "gh",
       [
         "pr",
@@ -21288,16 +21298,15 @@ async function pushEntry(opts) {
         "--body",
         prBody
       ],
-      { cwd: stagingDir, encoding: "utf-8", shell: true }
+      { cwd: stagingDir }
     );
     if (pr.status !== 0) {
       return {
         status: "failed",
-        detail: (typeof pr.stderr === "string" ? pr.stderr : String(pr.stderr ?? "")).trim() || "gh pr create failed"
+        detail: (pr.stderr || "gh pr create failed").trim()
       };
     }
-    const prUrl = (typeof pr.stdout === "string" ? pr.stdout : String(pr.stdout ?? "")).trim();
-    return { status: "ok", prUrl };
+    return { status: "ok", prUrl: pr.stdout.trim() };
   } catch (err) {
     return {
       status: "failed",
@@ -21305,21 +21314,41 @@ async function pushEntry(opts) {
     };
   }
 }
+function shellQuote(s) {
+  if (!/[\s&|<>^()"`$!*?\[\]{}\\]/.test(s)) return s;
+  return `"${s.replace(/"/g, '""')}"`;
+}
+function runCapture(command, args, opts = {}) {
+  const line = [command, ...args].map(shellQuote).join(" ");
+  const r2 = spawnSync(line, {
+    encoding: "utf-8",
+    cwd: opts.cwd,
+    shell: true
+  });
+  return {
+    status: r2.status,
+    stdout: typeof r2.stdout === "string" ? r2.stdout : "",
+    stderr: typeof r2.stderr === "string" ? r2.stderr : ""
+  };
+}
+function runOrThrow(command, args, opts = {}) {
+  const r2 = runCapture(command, args, opts);
+  if (r2.status !== 0) {
+    throw new Error(
+      `${command} ${args.join(" ")} failed: ${(r2.stderr || r2.stdout || "unknown").trim()}`
+    );
+  }
+}
 function checkGhAvailable() {
-  const r2 = spawnSync("gh", ["--version"], { encoding: "utf-8", shell: true });
-  return r2.status === 0;
+  return runCapture("gh", ["--version"]).status === 0;
 }
 function checkGhAuthed() {
-  const r2 = spawnSync("gh", ["auth", "status"], { encoding: "utf-8", shell: true });
-  return r2.status === 0;
+  return runCapture("gh", ["auth", "status"]).status === 0;
 }
 function resolveGhUser() {
-  const r2 = spawnSync("gh", ["api", "user", "--jq", ".login"], {
-    encoding: "utf-8",
-    shell: true
-  });
+  const r2 = runCapture("gh", ["api", "user", "--jq", ".login"]);
   if (r2.status !== 0) return void 0;
-  return typeof r2.stdout === "string" ? r2.stdout.trim() : "";
+  return r2.stdout.trim() || void 0;
 }
 function parseOwnerRepo(url) {
   const m = /^https:\/\/github\.com\/([^/]+)\/([^/]+?)(\.git)?\/?$/.exec(url);
@@ -21339,7 +21368,13 @@ function findOwnedEntry(entriesDir, id) {
         const parsed = parseMarkdown(raw2);
         if (parsed.frontmatter.id === id) {
           const relPath = relative2(entriesDir, absPath).replace(/\\/g, "/");
-          return { id, title: parsed.frontmatter.title, absPath, relPath };
+          return {
+            id,
+            title: parsed.frontmatter.title,
+            absPath,
+            relPath,
+            visibility: parsed.frontmatter.visibility
+          };
         }
       } catch {
       }
@@ -21351,44 +21386,28 @@ function forkStagingDir(caveatHome) {
   return join7(caveatHome, "push-fork");
 }
 function ensureFork(owner, repo) {
-  spawnSync(
-    "gh",
-    ["repo", "fork", `${owner}/${repo}`, "--clone=false", "--remote=false"],
-    { encoding: "utf-8", shell: true }
-  );
+  runCapture("gh", ["repo", "fork", `${owner}/${repo}`, "--clone=false", "--remote=false"]);
 }
 function ensureStagingClone(stagingDir, ghUser, sharedName, upstreamOwner) {
   if (!existsSync7(stagingDir)) {
     mkdirSync3(dirname4(stagingDir), { recursive: true });
     const forkUrl = `https://github.com/${ghUser}/${sharedName}.git`;
-    run("git", ["clone", "--depth", "30", forkUrl, stagingDir]);
-    run(
+    runOrThrow("git", ["clone", "--depth", "30", forkUrl, stagingDir]);
+    runOrThrow(
       "git",
       ["remote", "add", "upstream", `https://github.com/${upstreamOwner}/${sharedName}.git`],
       { cwd: stagingDir }
     );
   } else {
-    run("git", ["checkout", "main"], { cwd: stagingDir });
-    run("git", ["fetch", "upstream", "main"], { cwd: stagingDir });
-    run("git", ["reset", "--hard", "upstream/main"], { cwd: stagingDir });
-    run("git", ["push", "origin", "main", "--force-with-lease"], { cwd: stagingDir });
+    runOrThrow("git", ["checkout", "main"], { cwd: stagingDir });
+    runOrThrow("git", ["fetch", "upstream", "main"], { cwd: stagingDir });
+    runOrThrow("git", ["reset", "--hard", "upstream/main"], { cwd: stagingDir });
+    runOrThrow("git", ["push", "origin", "main", "--force-with-lease"], { cwd: stagingDir });
   }
 }
 function upstreamAlreadyHas(stagingDir, relFromRoot) {
   return existsSync7(join7(stagingDir, relFromRoot));
 }
-function run(command, args, opts = {}) {
-  const r2 = spawnSync(command, args, {
-    encoding: "utf-8",
-    cwd: opts.cwd,
-    shell: true
-  });
-  if (r2.status !== 0) {
-    const stderr = typeof r2.stderr === "string" ? r2.stderr : String(r2.stderr ?? "");
-    const stdout = typeof r2.stdout === "string" ? r2.stdout : String(r2.stdout ?? "");
-    throw new Error(`${command} ${args.join(" ")} failed: ${(stderr || stdout || "unknown").trim()}`);
-  }
-}
 
 // ../../packages/core/dist/pullShared.js
 import { existsSync as existsSync8, readdirSync as readdirSync5 } from "node:fs";
@@ -21435,6 +21454,21 @@ function buildContext(logger, overrides = {}) {
   return { caveatHome, userHome, userConfigPath, config: config3, paths, logger };
 }
 
+// src/version.ts
+import { readFileSync as readFileSync6 } from "node:fs";
+import { dirname as dirname5, join as join10 } from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+function resolveVersion() {
+  try {
+    const here2 = dirname5(fileURLToPath3(import.meta.url));
+    const pkg = JSON.parse(readFileSync6(join10(here2, "..", "package.json"), "utf-8"));
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+var CAVEAT_VERSION = resolveVersion();
+
 // src/logger.ts
 var stdoutLogger = {
   info: (m) => process.stdout.write(`[caveat] ${m}
@@ -21446,13 +21480,13 @@ var stdoutLogger = {
 };
 
 // src/commands/init.ts
-import { existsSync as existsSync10, mkdirSync as mkdirSync5, readdirSync as readdirSync6, writeFileSync as writeFileSync5 } from "node:fs";
-import { join as join11 } from "node:path";
+import { existsSync as existsSync10, mkdirSync as mkdirSync5, readdirSync as readdirSync6, renameSync, rmdirSync, writeFileSync as writeFileSync5 } from "node:fs";
+import { join as join12 } from "node:path";
 
 // src/claudeInstall.ts
 import { spawnSync as spawnSync2 } from "node:child_process";
-import { copyFileSync as copyFileSync2, existsSync as existsSync9, mkdirSync as mkdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
-import { dirname as dirname5, join as join10 } from "node:path";
+import { copyFileSync as copyFileSync2, existsSync as existsSync9, mkdirSync as mkdirSync4, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
+import { dirname as dirname6, join as join11 } from "node:path";
 var EVENT_USER_PROMPT_SUBMIT = "UserPromptSubmit";
 var EVENT_STOP = "Stop";
 function quote(p2) {
@@ -21487,10 +21521,10 @@ function removeHook(settings, event, command) {
 }
 function readSettings(path) {
   if (!existsSync9(path)) return {};
-  return JSON.parse(readFileSync6(path, "utf-8"));
+  return JSON.parse(readFileSync7(path, "utf-8"));
 }
 function writeSettings(path, settings) {
-  const dir = dirname5(path);
+  const dir = dirname6(path);
   if (!existsSync9(dir)) mkdirSync4(dir, { recursive: true });
   let backupPath = "";
   if (existsSync9(path)) {
@@ -21501,11 +21535,11 @@ function writeSettings(path, settings) {
   return backupPath;
 }
 var CLAUDE_BIN = "claude";
-function shellQuote(s) {
+function shellQuote2(s) {
   return /[\s&|<>^()]/.test(s) ? `"${s}"` : s;
 }
 function runClaude(args) {
-  const line = [CLAUDE_BIN, ...args].map(shellQuote).join(" ");
+  const line = [CLAUDE_BIN, ...args].map(shellQuote2).join(" ");
   return spawnSync2(line, { shell: true, encoding: "utf-8" });
 }
 function registerMcp(nodePath, cliScriptPath, dryRun, logger) {
@@ -21556,7 +21590,7 @@ function unregisterMcp(dryRun, logger) {
   return { action: "skipped", detail: "not registered or removal failed" };
 }
 function installClaudeIntegration(opts) {
-  const settingsPath = join10(opts.claudeDir, "settings.json");
+  const settingsPath = join11(opts.claudeDir, "settings.json");
   const settings = readSettings(settingsPath);
   const usCmd = hookCommand(opts.nodePath, opts.cliScriptPath, "user-prompt-submit");
   const stopCmd = hookCommand(opts.nodePath, opts.cliScriptPath, "stop");
@@ -21575,7 +21609,7 @@ function installClaudeIntegration(opts) {
   return { mcp, hooks: { userPromptSubmit, stop }, backupPath };
 }
 function uninstallClaudeIntegration(opts) {
-  const settingsPath = join10(opts.claudeDir, "settings.json");
+  const settingsPath = join11(opts.claudeDir, "settings.json");
   const settings = readSettings(settingsPath);
   const usCmd = hookCommand(opts.nodePath, opts.cliScriptPath, "user-prompt-submit");
   const stopCmd = hookCommand(opts.nodePath, opts.cliScriptPath, "stop");
@@ -21605,11 +21639,6 @@ var KNOWLEDGE_GITIGNORE = [
   "",
   "# Obsidian per-user config: workspace layout, theme, plugin state, cache.",
   ".obsidian/",
-  "",
-  "# community/ is a local cache of shallow-cloned third-party caveat repos",
-  "# (populated by `caveat community add`). Each contains its own .git and is not",
-  "# part of this repo's tracked knowledge.",
-  "community/",
   ""
 ].join("\n");
 async function runInit(ctx, opts = { skipClaude: false, skipShared: false, dryRun: false }) {
@@ -21622,7 +21651,8 @@ async function runInit(ctx, opts = { skipClaude: false, skipShared: false, dryRu
   } else {
     ctx.logger.info(`knowledge repo: ${ctx.paths.knowledgeRepo}`);
   }
-  const gitignorePath = join11(ctx.paths.knowledgeRepo, ".gitignore");
+  migrateLegacyCommunityDir(ctx);
+  const gitignorePath = join12(ctx.paths.knowledgeRepo, ".gitignore");
   if (!existsSync10(gitignorePath)) {
     writeFileSync5(gitignorePath, KNOWLEDGE_GITIGNORE, "utf-8");
     ctx.logger.info(`.gitignore created: ${gitignorePath}`);
@@ -21650,7 +21680,7 @@ async function runInit(ctx, opts = { skipClaude: false, skipShared: false, dryRu
     return;
   }
   const result = installClaudeIntegration({
-    claudeDir: join11(ctx.userHome, ".claude"),
+    claudeDir: join12(ctx.userHome, ".claude"),
     cliScriptPath,
     nodePath: process.execPath,
     dryRun: opts.dryRun,
@@ -21658,6 +21688,28 @@ async function runInit(ctx, opts = { skipClaude: false, skipShared: false, dryRu
   });
   reportInstallResult(ctx, result, opts.dryRun);
 }
+function migrateLegacyCommunityDir(ctx) {
+  const legacy = join12(ctx.paths.knowledgeRepo, "community");
+  const current = ctx.paths.communityDir;
+  if (legacy === current) return;
+  if (!existsSync10(legacy)) return;
+  if (existsSync10(current)) {
+    ctx.logger.warn(
+      `legacy community dir still exists at ${legacy} \u2014 remove manually (new location in use)`
+    );
+    return;
+  }
+  mkdirSync5(current, { recursive: true });
+  for (const entry of readdirSync6(legacy, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    renameSync(join12(legacy, entry.name), join12(current, entry.name));
+  }
+  try {
+    rmdirSync(legacy);
+  } catch {
+  }
+  ctx.logger.info(`migrated legacy community/ \u2192 ${current}`);
+}
 async function subscribeSharedRepo(ctx, db) {
   const url = ctx.config.sharedRepo;
   const validation = validateCommunityUrl(url);
@@ -21668,7 +21720,7 @@ async function subscribeSharedRepo(ctx, db) {
     return;
   }
   const handle = validation.handle;
-  const target = join11(ctx.paths.communityDir, handle);
+  const target = join12(ctx.paths.communityDir, handle);
   if (!existsSync10(target)) {
     if (!existsSync10(ctx.paths.communityDir)) {
       mkdirSync5(ctx.paths.communityDir, { recursive: true });
@@ -21697,7 +21749,7 @@ async function subscribeSharedRepo(ctx, db) {
     for (const entry of readdirSync6(ctx.paths.communityDir, { withFileTypes: true })) {
       if (!entry.isDirectory()) continue;
       const source = `community/${entry.name}`;
-      const root = join11(ctx.paths.communityDir, entry.name, "entries");
+      const root = join12(ctx.paths.communityDir, entry.name, "entries");
       if (!existsSync10(root)) continue;
       const result = scanSource({ db, source, entriesRoot: root });
       ctx.logger.info(`indexed ${source}: +${result.added}`);
@@ -21711,7 +21763,7 @@ function runUninstall(ctx, opts) {
     process.exit(1);
   }
   const result = uninstallClaudeIntegration({
-    claudeDir: join11(ctx.userHome, ".claude"),
+    claudeDir: join12(ctx.userHome, ".claude"),
     cliScriptPath,
     nodePath: process.execPath,
     dryRun: opts.dryRun,
@@ -21749,9 +21801,9 @@ function reportInstallResult(ctx, result, dryRun) {
 
 // src/commands/indexCmd.ts
 import { existsSync as existsSync11, readdirSync as readdirSync7, mkdirSync as mkdirSync6 } from "node:fs";
-import { dirname as dirname6, join as join12 } from "node:path";
+import { dirname as dirname7, join as join13 } from "node:path";
 function runIndex(ctx, opts) {
-  const dbDir = dirname6(ctx.paths.dbPath);
+  const dbDir = dirname7(ctx.paths.dbPath);
   if (!existsSync11(dbDir)) mkdirSync6(dbDir, { recursive: true });
   const db = openDb({ path: ctx.paths.dbPath, logger: ctx.logger });
   try {
@@ -21769,7 +21821,7 @@ function runIndex(ctx, opts) {
       for (const entry of readdirSync7(ctx.paths.communityDir, { withFileTypes: true })) {
         if (!entry.isDirectory()) continue;
         const source = `community/${entry.name}`;
-        const root = join12(ctx.paths.communityDir, entry.name, "entries");
+        const root = join13(ctx.paths.communityDir, entry.name, "entries");
         if (!existsSync11(root)) continue;
         const result = scanSource({ db, source, entriesRoot: root });
         ctx.logger.info(`${source}: +${result.added} ~${result.updated} -${result.deleted}`);
@@ -22544,11 +22596,11 @@ var serve = (options2, listeningListener) => {
 
 // ../web/dist/context.js
 import { homedir as homedir2 } from "node:os";
-import { join as join13 } from "node:path";
+import { join as join14 } from "node:path";
 function buildWebContext(overrides = {}) {
   const userHome = overrides.userHome ?? homedir2();
   const caveatHome = overrides.caveatHome ?? findCaveatHome(userHome);
-  const userConfigPath = join13(userHome, ".caveatrc.json");
+  const userConfigPath = join14(userHome, ".caveatrc.json");
   const logger = overrides.logger ?? stderrLogger;
   const config3 = loadConfig(userConfigPath);
   const paths = resolvePaths(caveatHome, config3.knowledgeRepo, userHome);
@@ -30276,13 +30328,13 @@ function createDetailRoute(ctx) {
 
 // ../web/dist/routes/community.js
 import { existsSync as existsSync12, readdirSync as readdirSync8, statSync as statSync4 } from "node:fs";
-import { join as join14 } from "node:path";
+import { join as join15 } from "node:path";
 function listCommunity(communityDir, db) {
   if (!existsSync12(communityDir)) return [];
   const handles = [];
   for (const entry of readdirSync8(communityDir, { withFileTypes: true })) {
     if (!entry.isDirectory()) continue;
-    const handlePath = join14(communityDir, entry.name);
+    const handlePath = join15(communityDir, entry.name);
     const countRow = db.prepare("SELECT COUNT(*) AS n FROM entries WHERE source = ?").get(`community/${entry.name}`);
     handles.push({
       handle: entry.name,
@@ -44580,11 +44632,11 @@ var StdioServerTransport = class {
 
 // ../mcp/dist/context.js
 import { homedir as homedir3 } from "node:os";
-import { join as join15 } from "node:path";
+import { join as join16 } from "node:path";
 function buildMcpContext(overrides = {}) {
   const userHome = overrides.userHome ?? homedir3();
   const caveatHome = overrides.caveatHome ?? findCaveatHome(userHome);
-  const userConfigPath = join15(userHome, ".caveatrc.json");
+  const userConfigPath = join16(userHome, ".caveatrc.json");
   const logger = overrides.logger ?? stderrLogger;
   const config3 = loadConfig(userConfigPath);
   const paths = resolvePaths(caveatHome, config3.knowledgeRepo, userHome);
@@ -44640,7 +44692,9 @@ var recordInputShape = {
   context: external_exports.string().optional(),
   confidence: confidenceSchema2.optional(),
   outcome: outcomeSchema.optional(),
-  visibility: visibilitySchema.optional(),
+  visibility: visibilitySchema.describe(
+    'REQUIRED. Ask the user "public (share to community) or private (keep local only)?" before calling \u2014 never auto-classify. The user owns the knowledge; they decide its reach.'
+  ),
   tags: external_exports.array(external_exports.string()).optional(),
   environment: external_exports.record(external_exports.string(), external_exports.string()).optional(),
   category: external_exports.string().optional().describe("Directory under entries/ (e.g., gpu, claude-code). Default: misc")
@@ -44748,7 +44802,7 @@ function registerAllTools(server, ctx) {
     "caveat_search",
     {
       title: "caveat_search",
-      description: "Full-text search across caveats (external spec gotchas). Returns summary; use caveat_get for body.",
+      description: 'Search the "caveats" knowledge base \u2014 records of time-wasting traps in EXTERNAL specs (GPU/driver/CUDA versions, native-module builds, IDE/shell quirks, platform-specific behavior, library version incompatibilities) that someone already diagnosed. Call this FIRST when a problem smells environmental rather than a logic bug \u2014 before reading stack traces top-to-bottom or trying fixes. Query: 3+ chars, plain tokens only (no OR/NEAR/other FTS5 operators). Returns summary rows including `{id, source}` \u2014 pass BOTH to caveat_get for the full body.',
       inputSchema: searchInputShape
     },
     async (args) => jsonResult(handleSearch(ctx, args))
@@ -44757,7 +44811,7 @@ function registerAllTools(server, ctx) {
     "caveat_get",
     {
       title: "caveat_get",
-      description: "Fetch full caveat by id (frontmatter + sections + body).",
+      description: 'Fetch the full body (frontmatter + H2 sections + text) of a caveat by id. IMPORTANT: when the id came from caveat_search, you MUST pass the `source` field from that same result (e.g., "community/Caveat"). The default source is "own" only; omitting source for a community entry returns not-found.',
       inputSchema: getInputShape
     },
     async (args) => jsonResult(handleGet(ctx, args))
@@ -44766,7 +44820,7 @@ function registerAllTools(server, ctx) {
     "caveat_record",
     {
       title: "caveat_record",
-      description: "Create a new caveat markdown file. Auto-fills source_session and environment fingerprint for unspecified keys. source_project is left null by design (publicly-shared knowledge should not leak per-user project names).",
+      description: "Create a new caveat: a record of an external-spec trap that wasted real time (wrong driver, version mismatch, platform bug, IDE quirk, native-module issue, etc.) so future sessions can find it via caveat_search. REQUIRED BEFORE CALLING: (1) run caveat_search first to avoid duplicates, (2) ASK THE USER whether this should be `public` (shareable to the community DB) or `private` (kept local only) \u2014 never auto-classify visibility; the user owns the knowledge and decides its reach. Qualifies: specific symptom + diagnosed cause (or `outcome: impossible` verdict) + environment fingerprint. Does NOT qualify: project-internal bugs, user preferences, session summaries, ephemeral task notes. Auto-fills source_session and environment defaults; source_project is left null by design (shared knowledge must not leak per-user project names).",
       inputSchema: recordInputShape
     },
     async (args) => jsonResult(handleRecord(ctx, args))
@@ -44775,7 +44829,7 @@ function registerAllTools(server, ctx) {
     "caveat_update",
     {
       title: "caveat_update",
-      description: "Patch an existing caveat. Frontmatter shallow-merges (arrays replace). Sections matched by case-insensitive H2 heading. Immutable keys: id, created_at, source_session, source_project.",
+      description: "Patch an existing caveat \u2014 use when newer evidence extends or corrects one that already exists. Frontmatter shallow-merges, but array fields (tags etc.) REPLACE rather than append \u2014 to add one tag, read the current list first, then patch with the full new array. Sections match by case-insensitive H2 heading. Immutable keys: id, created_at, source_session, source_project. Common uses: bump `last_verified` after re-confirming, add a resolution when it was `tentative`, flip `outcome` to `impossible`.",
       inputSchema: updateInputShape
     },
     async (args) => jsonResult(handleUpdate(ctx, args))
@@ -44784,7 +44838,7 @@ function registerAllTools(server, ctx) {
     "caveat_list_recent",
     {
       title: "caveat_list_recent",
-      description: "List caveats by updated_at DESC.",
+      description: "List caveats ordered by updated_at DESC. Use for browsing recent additions \u2014 e.g., showing the user what is new after caveat_pull. Not for search; use caveat_search when you have a query.",
       inputSchema: listRecentInputShape
     },
     async (args) => jsonResult(handleListRecent(ctx, args))
@@ -44793,7 +44847,7 @@ function registerAllTools(server, ctx) {
     "caveat_pull",
     {
       title: "caveat_pull",
-      description: "git-pull all subscribed community caveat repos (incl. the shared DB) and re-index. Call this when the user asks if others have documented a similar trap, or at the start of a session that might benefit from fresh external knowledge. Safe and idempotent \u2014 re-running is cheap.",
+      description: "git-pull the subscribed community caveat repos (the shared knowledge DB + any user-added remotes) and re-index. Call when: (a) the user explicitly asks about others' knowledge on a topic, or (b) caveat_search returned empty for a query that feels like it should have hits and the DB might be stale. Do NOT call reflexively at session start \u2014 it is cheap but not free, and stale-by-minutes is acceptable. Safe and idempotent.",
       inputSchema: pullInputShape
     },
     async (args) => jsonResult(await handlePull(ctx, args))
@@ -44802,7 +44856,7 @@ function registerAllTools(server, ctx) {
     "caveat_push",
     {
       title: "caveat_push",
-      description: "Contribute a user-owned caveat to the shared community DB via fork + PR. Call this after caveat_record when the entry looks genuinely reusable by others (not a one-off project tie-in, not duplicated by existing community entries). Requires the `gh` CLI on the user's machine; returns status=gh-missing or gh-unauthed when unavailable. Use dry_run=true to preview without touching GitHub.",
+      description: "Contribute a user-owned caveat to the public shared DB via fork + PR on GitHub. This is a PUBLIC, externally-visible action (the PR appears on GitHub and is hard to fully retract). Confirm with the user before calling without dry_run \u2014 or call with dry_run=true first to show the plan. Only push entries that document a trap genuinely reusable by others (not project-specific ties, not duplicated by existing community entries). Entries with `visibility: private` are rejected (`status=visibility-private`) \u2014 the user has declared them local-only. Requires `gh` CLI authenticated; returns `status=gh-missing` / `gh-unauthed` on failure.",
       inputSchema: pushInputShape
     },
     async (args) => jsonResult(await handlePush(ctx, args))
@@ -45022,7 +45076,7 @@ function runCommunityList(ctx) {
 
 // src/index.ts
 var program = new Command();
-program.name("caveat").description("External spec gotcha knowledge base CLI").version("0.6.0");
+program.name("caveat").description("External spec gotcha knowledge base CLI").version(CAVEAT_VERSION);
 program.command("init").description(
   "Initialize ~/.caveatrc.json, ~/.caveat/, subscribe to the shared community DB, and register Claude Code integration"
 ).option("--skip-claude", "skip Claude Code MCP + hook registration", false).option("--skip-shared", "skip subscribing to the shared community DB", false).option("--dry-run", "show planned changes without writing", false).action(async (opts) => {