caveat-cli 0.6.1 → 0.6.2

package/dist/index.js

@@ -21237,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" };
@@ -21362,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 {
       }
@@ -44680,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")
@@ -44788,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))
@@ -44797,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))
@@ -44806,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))
@@ -44815,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))
@@ -44824,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))
@@ -44833,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))
@@ -44842,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))