context-vault 3.9.0 → 3.11.0

package/.claude-plugin/README.md

@@ -0,0 +1,219 @@
+# context-vault Claude Plugin
+
+Persistent memory and knowledge management for AI agents. Save decisions, insights, patterns, and context across sessions using semantic search and project-scoped buckets.
+
+## What is context-vault?
+
+context-vault is a local-first memory system that lets Claude persistently store and retrieve knowledge. Think of it as a personal knowledge base that follows you across sessions, projects, and contexts.
+
+### Key Features
+
+- **Persistent Memory** -- Save insights, decisions, patterns, and references across sessions
+- **Semantic Search** -- Find entries by meaning, not just keywords
+- **Project Buckets** -- Organize entries by project for easy scoping
+- **Team Vaults** -- Share knowledge with your team (requires hosted API)
+- **Deduplication** -- Automatic detection of similar entries
+- **Encoding Context** -- Future-proof your saves with metadata for discovery months later
+- **Snapshot Briefs** -- Consolidate scattered entries into a single context brief
+- **Recall Tracking** -- Monitor how often your entries are actually used
+
+## Installation
+
+Install via Claude Code:
+
+```
+/plugin install context-vault
+```
+
+For full setup with embedding model download and agent rules:
+
+```bash
+npx context-vault setup
+```
+
+## Quick Start
+
+### Save Your First Insight
+
+```javascript
+save_context({
+  kind: "insight",
+  title: "PostgreSQL connection pooling lesson",
+  body: "Connections without pooling exhausted at 100 concurrent users...",
+  tags: ["bucket:myproject", "database"],
+  encoding_context: { project: "myproject", arc: "scaling", task: "investigation" }
+})
+```
+
+### Load Context for a Task
+
+```javascript
+// At the start of a session, scope to your project and get an overview
+clear_context({
+  preload_bucket: "myproject",
+  max_tokens: 4000
+})
+
+// Then search for specific context
+get_context({
+  query: "how do we handle database scaling?",
+  buckets: ["myproject"]
+})
+```
+
+### Create a Context Brief
+
+```javascript
+create_snapshot({
+  topic: "API authentication decisions",
+  buckets: ["myproject"]
+})
+```
+
+## Commands
+
+Three slash commands for common vault workflows:
+
+- **/vault-status** -- Check vault health (entry counts, recall ratio, warnings)
+- **/vault-snapshot** -- Create a consolidated context brief for a topic
+- **/vault-cleanup** -- Triage stale entries, consolidate duplicates, manage growth
+
+## Skills
+
+Three skills teach Claude how to use the vault effectively:
+
+### 1. Memory Management
+When to save, what kind to use, how to tag entries, and how to keep your vault healthy.
+
+### 2. Knowledge Capture
+Session-end protocol: extract and save the insights and decisions you discovered.
+
+### 3. Context Assembly
+Load relevant knowledge at task start. Assemble context efficiently and scope to your project.
+
+## Use Cases
+
+### Personal Memory
+Save decisions and insights from your work, then access them months later.
+
+```javascript
+save_context({
+  kind: "decision",
+  title: "Chose SQLite + embeddings for local RAG",
+  body: "Evaluated: PostgreSQL (setup), Pinecone (cost), local SQLite (simplicity). Chose SQLite + sqlite-vec for full control and no external dependencies.",
+  tags: ["bucket:rag-project", "architecture", "database"],
+  tier: "durable"
+})
+```
+
+### Team Knowledge Sharing
+Capture lessons learned that the team should know, then publish to a shared vault.
+
+```javascript
+save_context({
+  kind: "pattern",
+  title: "Always test OAuth flow end-to-end on real device",
+  body: "Simulator behavior differs from real devices. Always test with physical phone before production.",
+  tags: ["bucket:mobile-team", "oauth", "testing"],
+  tier: "durable"
+})
+
+// Later, share to team vault
+publish_to_team({ id: "entry-id" })
+```
+
+### Project Onboarding
+Create a snapshot of all decisions and patterns for a new team member.
+
+```javascript
+create_snapshot({
+  topic: "project architecture and key decisions",
+  buckets: ["project-x"],
+  kinds: ["decision", "pattern"]
+})
+```
+
+## Tools Reference
+
+The plugin provides 14 MCP tools:
+
+### Read-Only (no side effects)
+- `list_context` -- Browse entries by kind, tags, date range
+- `context_status` -- Vault health dashboard (entry counts, recall stats, warnings)
+- `list_buckets` -- List all project buckets
+- `session_start` -- Load project context at session start
+
+### Read with Analytics (update access counters as side effect)
+- `get_context` -- Search vault by query, kind, bucket, or date. Updates `hit_count` and `recall_count` on returned entries.
+- `recall` -- Proactive context surfacing. Takes a `signal` (text) and `signal_type` (prompt/error/file/task), returns relevant hints. Records co-retrieval pairs.
+
+### Write (create new entries)
+- `save_context` -- Create or update an entry. Supports `encoding_context` for future discovery and `supersedes` to retire old entries.
+- `create_snapshot` -- Consolidate scattered entries into a single brief. Returns a confirmation with the new entry's ID and identity_key.
+- `ingest_url` -- Fetch a web page and save as a reference entry
+- `ingest_project` -- Scan a project directory and save metadata
+- `session_end` -- Capture session learnings (auto-save insights)
+- `publish_to_team` -- Copy an entry to your team vault
+
+### Destructive (modify or delete existing data)
+- `delete_context` -- Permanently remove an entry by ID
+- `clear_context` -- Reset session scope. With `preload_bucket`, returns recent entries from that bucket in the response.
+
+## Storage
+
+Data is stored in two locations:
+
+```
+~/.context-mcp/              # Data directory
+├── vault.db                  # SQLite database (entries, embeddings, FTS index)
+├── config.json               # User configuration
+└── telemetry.jsonl           # Local usage telemetry
+
+~/vault/ (or configured path)  # Vault directory (markdown source of truth)
+├── knowledge/                 # Decisions, insights, patterns, references
+├── entity/                    # People, projects, tools
+└── event/                     # Session logs, activity
+```
+
+Markdown files are the source of truth. The SQLite database is a derived index, rebuildable via `context-vault reindex`.
+
+## Privacy
+
+**Local-first:** All data stored locally on your machine. No network calls unless you explicitly enable hosted sync or team vaults.
+
+**Hosted sync (optional):** When configured, entries sync to your personal cloud vault (per-user isolated database). Team vault entries are shared only when you call `publish_to_team`.
+
+**Your vault is never accessed or indexed by third parties.** Full privacy policy: https://context-vault.com/privacy
+
+## Tips
+
+- **Encoding context is key:** Entries without `encoding_context` are rarely discovered later. Always include project, arc, and task.
+- **Check before saving:** Call `get_context` first to avoid duplicates. Duplicates hurt recall ratio.
+- **Use tiers wisely:** `durable` for architecture decisions, `working` (default) for active context, `ephemeral` for temp notes.
+- **Snapshot for scale:** If you have 20+ entries on a topic, create a snapshot instead of loading them individually.
+- **Recall ratio:** 20-30% is healthy. Run `/vault-status` to check yours.
+
+## Troubleshooting
+
+**"I can't find my entry"**
+- Check the right bucket: `get_context({ query: "...", buckets: ["myproject"] })`
+- Try a broader query: "authentication" instead of "OAuth 2.0 PKCE state handling"
+- Browse by kind: `list_context({ kind: "decision", tags: ["bucket:myproject"] })`
+
+**"Vault is growing too fast"**
+- Run `/vault-cleanup` to identify stale or duplicate entries
+- Create snapshots to consolidate large topics
+- Check for session/debug noise mixed with knowledge entries
+
+**"Embeddings not working"**
+- Run `context-vault reindex` to regenerate the embedding index
+- Run `context-vault doctor` for a full diagnostic
+
+## Support
+
+- GitHub: https://github.com/fellanH/context-vault/issues
+- Website: https://context-vault.com
+
+## License
+
+MIT

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "context-vault",
+  "version": "3.10.0",
+  "description": "Persistent memory and knowledge management for AI agents. Save decisions, insights, patterns, and context across sessions. Semantic search, project-scoped buckets, team vaults, and recall tracking.",
+  "author": "Klarhimmel",
+  "homepage": "https://context-vault.com",
+  "repository": "https://github.com/fellanH/context-vault",
+  "license": "MIT",
+  "keywords": ["memory", "knowledge", "vault", "context", "mcp", "persistence", "recall"],
+  "categories": ["productivity", "knowledge-management", "developer-tools"]
+}

package/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "context-vault": {
+      "command": "context-vault",
+      "args": ["serve"]
+    }
+  }
+}
+

package/bin/cli.js

@@ -416,6 +416,7 @@ ${bold('Commands:')}
   ${cyan('stats')} recall|co-retrieval  Measure recall ratio and co-retrieval graph
   ${cyan('remote')} setup|status|sync|pull  Connect to hosted vault (cloud sync)
   ${cyan('team')} join|leave|status|browse  Join or manage a team vault
+  ${cyan('public')} create|seed|list|add  Manage and consume public vaults
   ${cyan('update')}                     Check for and install updates
   ${cyan('uninstall')}                  Remove MCP configs and optionally data
 `);
@@ -7367,6 +7368,313 @@ async function runTeam() {
   console.log();
 }
 
+async function runPublic() {
+  const subcommand = args[1];
+  const { getRemoteConfig, saveRemoteConfig } = await import('@context-vault/core/config');
+  const dataDir = join(HOME, '.context-mcp');
+
+  if (subcommand === 'create') {
+    const name = args[2];
+    const slug = getFlag('--slug') || (name ? name.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-') : null);
+    const description = getFlag('--description') || '';
+    const domainTags = getFlag('--domains') ? getFlag('--domains').split(',').map(s => s.trim()) : [];
+    const visibility = getFlag('--visibility') || 'free';
+
+    if (!name || !slug) {
+      console.error(`\n  ${red('Usage:')} context-vault public create <name> [--slug <slug>] [--description <desc>] [--domains <tag1,tag2>] [--visibility free|pro]\n`);
+      process.exit(1);
+    }
+
+    const remote = getRemoteConfig(dataDir);
+    if (!remote || !remote.enabled || !remote.apiKey) {
+      console.error(`\n  ${red('✘')} Remote is not configured. Run ${cyan('context-vault remote setup')} first.\n`);
+      process.exit(1);
+    }
+
+    console.log(`\n  Creating public vault "${bold(name)}" (${slug})...`);
+    try {
+      const res = await fetch(`${remote.url.replace(/\/$/, '')}/api/public/vaults`, {
+        method: 'POST',
+        headers: { 'Authorization': `Bearer ${remote.apiKey}`, 'Content-Type': 'application/json' },
+        signal: AbortSignal.timeout(15000),
+        body: JSON.stringify({ name, slug, description, domain_tags: domainTags, visibility }),
+      });
+      if (res.ok) {
+        const data = await res.json();
+        console.log(`  ${green('✓')} Created public vault: ${bold(data.slug || slug)}`);
+        console.log(`  Visibility: ${visibility}`);
+        if (domainTags.length) console.log(`  Domains:    ${domainTags.join(', ')}`);
+      } else {
+        const data = await res.json().catch(() => ({}));
+        console.error(`  ${red('✘')} Failed: ${data.error || `HTTP ${res.status}`}`);
+        process.exit(1);
+      }
+    } catch (e) {
+      console.error(`  ${red('✘')} Connection failed: ${e.message}`);
+      process.exit(1);
+    }
+    console.log();
+    return;
+  }
+
+  if (subcommand === 'seed') {
+    const vaultSlug = getFlag('--vault');
+    const tagsFlag = getFlag('--tags');
+    const remote = getRemoteConfig(dataDir);
+
+    if (!remote || !remote.enabled || !remote.apiKey) {
+      console.error(`\n  ${red('✘')} Remote is not configured. Run ${cyan('context-vault remote setup')} first.\n`);
+      process.exit(1);
+    }
+
+    if (!vaultSlug) {
+      console.error(`\n  ${red('Usage:')} context-vault public seed --vault <slug> [--tags <filter>] [--dry-run]\n`);
+      process.exit(1);
+    }
+
+    // Load local vault DB
+    const { resolveConfig } = await import('@context-vault/core/config');
+    const config = resolveConfig();
+
+    let DatabaseSync;
+    try {
+      DatabaseSync = (await import('node:sqlite')).DatabaseSync;
+    } catch {
+      console.error(`\n  ${red('✘')} Node.js SQLite not available. Requires Node >= 22.5.\n`);
+      process.exit(1);
+    }
+
+    const db = new DatabaseSync(config.dbPath, { open: true });
+
+    let sql = 'SELECT id, kind, category, title, body, tags, meta, source, identity_key, tier FROM vault WHERE superseded_by IS NULL';
+    const params = [];
+    if (tagsFlag) {
+      sql += ' AND tags LIKE ?';
+      params.push(`%"${tagsFlag}"%`);
+    }
+
+    const rows = db.prepare(sql).all(...params);
+    db.close();
+
+    let publishedKnowledge = 0;
+    let publishedEntities = 0;
+    let skippedEvents = 0;
+    let blockedPrivacy = 0;
+    const blockedEntries = [];
+    let errors = 0;
+
+    const apiUrl = remote.url.replace(/\/$/, '');
+
+    console.log();
+    console.log(`  ${bold('◇ Public Vault Seed')}`);
+    console.log(`  Vault: ${vaultSlug}`);
+    console.log(`  Filter: ${tagsFlag || dim('(all entries)')}`);
+    console.log(`  Entries: ${rows.length}`);
+    console.log();
+
+    if (isDryRun) {
+      for (const row of rows) {
+        if (row.category === 'event') skippedEvents++;
+        else if (row.category === 'entity') publishedEntities++;
+        else publishedKnowledge++;
+      }
+      console.log(`  ${dim('[dry run]')}`);
+      console.log(`  Would publish: ${green(publishedKnowledge)} knowledge, ${cyan(publishedEntities)} entities`);
+      console.log(`  Would skip:    ${dim(skippedEvents)} events (blocked for public)`);
+      console.log();
+      return;
+    }
+
+    for (const row of rows) {
+      if (row.category === 'event') {
+        skippedEvents++;
+        continue;
+      }
+
+      const tags = row.tags ? JSON.parse(row.tags) : [];
+      const meta = row.meta ? JSON.parse(row.meta) : {};
+
+      try {
+        const res = await fetch(`${apiUrl}/api/public/${vaultSlug}/entries`, {
+          method: 'POST',
+          headers: { 'Authorization': `Bearer ${remote.apiKey}`, 'Content-Type': 'application/json' },
+          signal: AbortSignal.timeout(15000),
+          body: JSON.stringify({
+            kind: row.kind,
+            title: row.title,
+            body: row.body,
+            tags,
+            meta,
+            source: row.source,
+            identity_key: row.identity_key,
+            tier: row.tier,
+            category: row.category,
+          }),
+        });
+
+        if (res.ok) {
+          if (row.category === 'entity') publishedEntities++;
+          else publishedKnowledge++;
+        } else if (res.status === 422) {
+          const data = await res.json().catch(() => ({}));
+          if (data.code === 'PRIVACY_SCAN_FAILED') {
+            const matchTypes = Array.isArray(data.matches) ? data.matches.map(m => m.type) : [];
+            const uniqueTypes = [...new Set(matchTypes)];
+            console.log(`  ${yellow('!')} Blocked: "${row.title || row.id}" (${uniqueTypes.join(', ') || 'sensitive content'})`);
+            blockedPrivacy++;
+            blockedEntries.push({ title: row.title || row.id, types: uniqueTypes });
+          } else {
+            errors++;
+            console.error(`  ${red('!')} 422 for "${row.title || row.id}": ${data.error || 'unknown'}`);
+          }
+        } else {
+          errors++;
+          const text = await res.text().catch(() => '');
+          console.error(`  ${red('!')} HTTP ${res.status} for "${row.title || row.id}": ${text.slice(0, 200)}`);
+        }
+      } catch (e) {
+        errors++;
+        console.error(`  ${red('✘')} Failed: ${row.title || row.id} (${e.message})`);
+      }
+
+      const processed = publishedKnowledge + publishedEntities + skippedEvents + blockedPrivacy + errors;
+      if (processed % 10 === 0) {
+        process.stdout.write(`  ${dim(`${processed}/${rows.length}...`)}\r`);
+      }
+    }
+
+    console.log(`  Seeded: ${green(publishedKnowledge)} knowledge, ${cyan(publishedEntities)} entities, ${dim(skippedEvents)} skipped (events), ${blockedPrivacy > 0 ? yellow(blockedPrivacy) : dim(blockedPrivacy)} blocked (privacy)`);
+    if (errors > 0) console.log(`  Errors: ${red(errors)}`);
+    if (blockedEntries.length > 0) {
+      console.log();
+      console.log(`  ${yellow('Blocked entries (review and clean before re-seeding):')}`);
+      for (const entry of blockedEntries) {
+        console.log(`    - ${entry.title} [${entry.types.join(', ')}]`);
+      }
+    }
+    console.log();
+    return;
+  }
+
+  if (subcommand === 'list') {
+    const domain = getFlag('--domain');
+    const remote = getRemoteConfig(dataDir);
+
+    const apiUrl = remote?.url?.replace(/\/$/, '') || 'https://api.context-vault.com';
+    const headers = {};
+    if (remote?.apiKey) headers['Authorization'] = `Bearer ${remote.apiKey}`;
+    headers['Content-Type'] = 'application/json';
+
+    const query = new URLSearchParams();
+    if (domain) query.set('domain', domain);
+
+    console.log();
+    console.log(`  ${bold('◇ Public Vaults')}`);
+    console.log();
+
+    try {
+      const res = await fetch(`${apiUrl}/api/public/vaults?${query.toString()}`, {
+        headers,
+        signal: AbortSignal.timeout(10000),
+      });
+      if (res.ok) {
+        const data = await res.json();
+        const vaults = Array.isArray(data.vaults) ? data.vaults : Array.isArray(data) ? data : [];
+        if (vaults.length === 0) {
+          console.log(`  ${dim('No public vaults found.')}`);
+        } else {
+          for (const v of vaults) {
+            const domains = Array.isArray(v.domain_tags) ? v.domain_tags.join(', ') : '';
+            console.log(`  ${bold(v.name || v.slug)} ${dim(`(${v.slug})`)}`);
+            if (v.description) console.log(`    ${v.description}`);
+            const stats = [`${v.consumer_count ?? 0} consumers`, `${v.total_recalls ?? 0} recalls`];
+            if (domains) stats.push(domains);
+            console.log(`    ${dim(stats.join(' · '))}`);
+            console.log();
+          }
+        }
+      } else {
+        console.error(`  ${red('✘')} Failed to list vaults: HTTP ${res.status}`);
+      }
+    } catch (e) {
+      console.error(`  ${red('✘')} Connection failed: ${e.message}`);
+    }
+    console.log();
+    return;
+  }
+
+  if (subcommand === 'add') {
+    const slug = args[2];
+    if (!slug) {
+      console.error(`\n  ${red('Usage:')} context-vault public add <slug>\n`);
+      process.exit(1);
+    }
+
+    const configPath = join(dataDir, 'config.json');
+    let config = {};
+    try {
+      config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    } catch {}
+
+    if (!config.remote) config.remote = {};
+    if (!Array.isArray(config.remote.publicVaults)) config.remote.publicVaults = [];
+
+    if (config.remote.publicVaults.includes(slug)) {
+      console.log(`\n  ${dim('Already added:')} ${slug}\n`);
+      return;
+    }
+
+    config.remote.publicVaults.push(slug);
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+    console.log(`\n  ${green('✓')} Added public vault: ${bold(slug)}`);
+    console.log(`  Your agent will now query this vault in get_context, session_start, and recall.\n`);
+    return;
+  }
+
+  if (subcommand === 'remove') {
+    const slug = args[2];
+    if (!slug) {
+      console.error(`\n  ${red('Usage:')} context-vault public remove <slug>\n`);
+      process.exit(1);
+    }
+
+    const configPath = join(dataDir, 'config.json');
+    let config = {};
+    try {
+      config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    } catch {}
+
+    if (!config.remote?.publicVaults || !config.remote.publicVaults.includes(slug)) {
+      console.log(`\n  ${dim('Not found:')} ${slug}\n`);
+      return;
+    }
+
+    config.remote.publicVaults = config.remote.publicVaults.filter(s => s !== slug);
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+    console.log(`\n  ${green('✓')} Removed public vault: ${bold(slug)}\n`);
+    return;
+  }
+
+  // Default: show public help
+  console.log();
+  console.log(`  ${bold('◇ context-vault public')}`);
+  console.log();
+  console.log(`  ${cyan('create <name>')}      Create a new public vault`);
+  console.log(`    ${dim('--slug <slug>')}      URL-friendly identifier`);
+  console.log(`    ${dim('--description <d>')} Vault description`);
+  console.log(`    ${dim('--domains <tags>')}  Comma-separated domain tags`);
+  console.log(`    ${dim('--visibility <v>')} free (default) or pro`);
+  console.log(`  ${cyan('seed')}               Publish local entries to a public vault`);
+  console.log(`    ${dim('--vault <slug>')}    Target public vault slug (required)`);
+  console.log(`    ${dim('--tags <filter>')}   Filter entries by tag`);
+  console.log(`    ${dim('--dry-run')}         Preview without publishing`);
+  console.log(`  ${cyan('list')}               Browse available public vaults`);
+  console.log(`    ${dim('--domain <tag>')}    Filter by domain tag`);
+  console.log(`  ${cyan('add <slug>')}         Add a public vault to your agent config`);
+  console.log(`  ${cyan('remove <slug>')}      Remove a public vault from your config`);
+  console.log();
+}
+
 async function runRemote() {
   const subcommand = args[1];
   const { getRemoteConfig, saveRemoteConfig } = await import('@context-vault/core/config');
@@ -8045,6 +8353,9 @@ async function main() {
     case 'team':
       await runTeam();
       break;
+    case 'public':
+      await runPublic();
+      break;
     default:
       console.error(red(`Unknown command: ${command}`));
       console.error(`Run ${cyan('context-vault --help')} for usage.`);

package/commands/vault-cleanup.md

@@ -0,0 +1,43 @@
+# /vault-cleanup — Vault Maintenance
+
+Identify stale, duplicate, or low-value entries and help the user clean up their vault.
+
+## Steps
+
+1. **Gather vault state.** Call `context_status()` to get entry counts, kind breakdown, recall stats, and warnings.
+
+2. **Identify cleanup candidates.** Use `list_context` to browse entries that may need attention:
+   ```
+   list_context({ kind: "session", limit: 20 })
+   list_context({ kind: "feedback", tags: ["auto-captured"], limit: 20 })
+   list_context({ kind: "observation", limit: 20 })
+   ```
+   Review results for entries with `recall_count: 0` (never recalled) and old `created_at` dates.
+
+3. **Check for duplicates.** Search for topics the user likely has many entries on:
+   ```
+   get_context({ query: "<suspected duplicate topic>", buckets: ["<project>"], limit: 15 })
+   ```
+   If multiple entries cover the same insight, suggest consolidating via `create_snapshot`.
+
+4. **Present a triage report.** For each category, show:
+   - Entry title, kind, created date, recall count
+   - Recommended action: **delete**, **consolidate**, **expire**, or **keep**
+
+5. **Execute only user-approved actions.** Wait for explicit confirmation before any deletion.
+
+## Available Actions
+
+| Action | How | When |
+|--------|-----|------|
+| **Delete** | `delete_context({ id: "<entry-id>" })` | Duplicates, noise, irrelevant entries |
+| **Consolidate** | `create_snapshot({ topic: "...", buckets: ["..."] })` | Many scattered entries on one topic |
+| **Set to expire** | `save_context({ id: "<entry-id>", tier: "ephemeral" })` | Stale but not worth deleting now |
+| **Supersede** | `save_context({ title: "...", body: "...", supersedes: ["<old-id>"] })` | Replace outdated with current |
+
+## Important
+
+- `delete_context` is **permanent and irreversible**. Always confirm with the user.
+- There is no bulk delete. Each deletion requires a separate call with a specific entry ID.
+- There is no "archive" or "soft delete." To deprioritize without deleting, set `tier: "ephemeral"`.
+- Do not reference tools or parameters that don't exist. Only use: `context_status`, `list_context`, `get_context`, `delete_context`, `save_context`, `create_snapshot`.

package/commands/vault-snapshot.md

@@ -0,0 +1,43 @@
+# /vault-snapshot — Create a Context Brief
+
+Consolidate scattered vault entries on a topic into a single brief.
+
+## Steps
+
+1. Ask the user what topic they want a snapshot of. Also ask which project bucket to scope to (if not obvious from context).
+
+2. Call `create_snapshot` with the topic as a **natural language search query** (not a slug):
+   ```
+   create_snapshot({
+     topic: "API authentication decisions and patterns",
+     buckets: ["project-name"],
+     kinds: ["decision", "pattern"],
+     tags: ["authentication"]
+   })
+   ```
+   All parameters except `topic` are optional. `kinds` filters by entry kind. `tags` adds tag filters. `buckets` scopes to a project.
+
+3. The tool returns a short confirmation (not the brief content):
+   ```
+   ✓ Snapshot created → id: <entry-id>
+     title: <topic> — Context Brief
+     identity_key: snapshot-<slugified-topic>
+     synthesized from: N entries
+   ```
+   The brief is saved to the vault as a `kind: brief` entry.
+
+4. To show the user the brief, make a follow-up call:
+   ```
+   get_context({ kind: "brief", identity_key: "snapshot-<slugified-topic>" })
+   ```
+
+5. Present the brief and offer next steps:
+   - "Share this with your team" via `publish_to_team({ id: "<entry-id>" })`
+   - "Create another snapshot on a related topic"
+   - "Search for more context" via `get_context`
+
+## Tips
+
+- The `topic` is used as a search query (hybrid FTS + semantic). Use descriptive natural language for best results. "API authentication decisions" works better than "api-auth".
+- If "no entries found," try a broader query or different bucket.
+- Snapshots are idempotent on `identity_key`. Re-running with the same topic updates the existing snapshot.