@context-vault/core 2.14.0 → 2.17.0

package/src/server/tools/get-context.js

@@ -1,4 +1,7 @@
 import { z } from "zod";
+import { createHash } from "node:crypto";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
 import { hybridSearch } from "../../retrieve/index.js";
 import { categoryFor } from "../../core/categories.js";
 import { normalizeKind } from "../../core/files.js";
@@ -6,6 +9,33 @@ import { ok, err } from "../helpers.js";
 import { isEmbedAvailable } from "../../index/embed.js";
 
 const STALE_DUPLICATE_DAYS = 7;
+const DEFAULT_PIVOT_COUNT = 2;
+const SKELETON_BODY_CHARS = 100;
+const CONSOLIDATION_TAG_THRESHOLD = 10;
+const CONSOLIDATION_SNAPSHOT_MAX_AGE_DAYS = 7;
+const BRIEF_SCORE_BOOST = 0.05;
+
+/**
+ * Truncate a body string to ~SKELETON_BODY_CHARS, breaking at sentence or
+ * word boundary. Returns the truncated string with "..." appended.
+ */
+export function skeletonBody(body) {
+  if (!body) return "";
+  if (body.length <= SKELETON_BODY_CHARS) return body;
+  const slice = body.slice(0, SKELETON_BODY_CHARS);
+  const sentenceEnd = Math.max(
+    slice.lastIndexOf(". "),
+    slice.lastIndexOf(".\n"),
+  );
+  if (sentenceEnd > SKELETON_BODY_CHARS * 0.4) {
+    return slice.slice(0, sentenceEnd + 1) + "...";
+  }
+  const wordEnd = slice.lastIndexOf(" ");
+  if (wordEnd > SKELETON_BODY_CHARS * 0.4) {
+    return slice.slice(0, wordEnd) + "...";
+  }
+  return slice + "...";
+}
 
 /**
  * Detect conflicts among a set of search result entries.
@@ -86,6 +116,131 @@ export function detectConflicts(entries, _ctx) {
   return conflicts;
 }
 
+/**
+ * Detect tag clusters that would benefit from consolidation via create_snapshot.
+ * A suggestion is emitted when a tag appears on threshold+ entries in the full
+ * vault AND no recent brief (kind='brief') exists for that tag within the
+ * staleness window.
+ *
+ * Tag counts are derived from the full vault (not just the search result set)
+ * so the check reflects the true size of the knowledge cluster. Only tags that
+ * appear in the current search results are evaluated — this keeps the check
+ * targeted to what the user is actually working with.
+ *
+ * @param {Array} entries - Search result rows (used to select candidate tags)
+ * @param {import('node:sqlite').DatabaseSync} db - Database handle for vault-wide counts and brief lookups
+ * @param {number|undefined} userId - Optional user_id scope
+ * @param {{ tagThreshold?: number, maxAgeDays?: number }} opts - Configurable thresholds
+ * @returns {Array<{tag: string, entry_count: number, last_snapshot_age_days: number|null}>}
+ */
+export function detectConsolidationHints(entries, db, userId, opts = {}) {
+  const tagThreshold = opts.tagThreshold ?? CONSOLIDATION_TAG_THRESHOLD;
+  const maxAgeDays = opts.maxAgeDays ?? CONSOLIDATION_SNAPSHOT_MAX_AGE_DAYS;
+
+  const candidateTags = new Set();
+  for (const entry of entries) {
+    if (entry.kind === "brief") continue;
+    const entryTags = entry.tags ? JSON.parse(entry.tags) : [];
+    for (const tag of entryTags) candidateTags.add(tag);
+  }
+
+  if (candidateTags.size === 0) return [];
+
+  const suggestions = [];
+  const cutoff = new Date(Date.now() - maxAgeDays * 86400000).toISOString();
+
+  for (const tag of candidateTags) {
+    let vaultCount = 0;
+    try {
+      const userClause =
+        userId !== undefined ? " AND user_id = ?" : " AND user_id IS NULL";
+      const countParams =
+        userId !== undefined ? [`%"${tag}"%`, userId] : [`%"${tag}"%`];
+      const countRow = db
+        .prepare(
+          `SELECT COUNT(*) as c FROM vault WHERE kind != 'brief' AND tags LIKE ?${userClause} AND (expires_at IS NULL OR expires_at > datetime('now')) AND superseded_by IS NULL`,
+        )
+        .get(...countParams);
+      vaultCount = countRow?.c ?? 0;
+    } catch {
+      continue;
+    }
+
+    if (vaultCount < tagThreshold) continue;
+
+    let lastSnapshotAgeDays = null;
+    try {
+      const userClause =
+        userId !== undefined ? " AND user_id = ?" : " AND user_id IS NULL";
+      const params =
+        userId !== undefined ? [`%"${tag}"%`, userId] : [`%"${tag}"%`];
+      const recentBrief = db
+        .prepare(
+          `SELECT created_at FROM vault WHERE kind = 'brief' AND tags LIKE ?${userClause} ORDER BY created_at DESC LIMIT 1`,
+        )
+        .get(...params);
+
+      if (recentBrief) {
+        lastSnapshotAgeDays = Math.round(
+          (Date.now() - new Date(recentBrief.created_at).getTime()) / 86400000,
+        );
+        if (recentBrief.created_at >= cutoff) continue;
+      }
+    } catch {
+      continue;
+    }
+
+    suggestions.push({
+      tag,
+      entry_count: vaultCount,
+      last_snapshot_age_days: lastSnapshotAgeDays,
+    });
+  }
+
+  return suggestions;
+}
+
+/**
+ * Check if an entry's source files have changed since the entry was saved.
+ * Returns { stale: true, stale_reason } if stale, or null if fresh.
+ * Best-effort: any read/parse failure returns null (no crash).
+ *
+ * @param {object} entry - DB row with source_files JSON column
+ * @returns {{ stale: boolean, stale_reason: string } | null}
+ */
+function checkStaleness(entry) {
+  if (!entry.source_files) return null;
+  let sourceFiles;
+  try {
+    sourceFiles = JSON.parse(entry.source_files);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(sourceFiles) || sourceFiles.length === 0) return null;
+
+  for (const sf of sourceFiles) {
+    try {
+      const absPath = sf.path.startsWith("/")
+        ? sf.path
+        : resolve(process.cwd(), sf.path);
+      if (!existsSync(absPath)) {
+        return { stale: true, stale_reason: "source file not found" };
+      }
+      const contents = readFileSync(absPath);
+      const currentHash = createHash("sha256").update(contents).digest("hex");
+      if (currentHash !== sf.hash) {
+        return {
+          stale: true,
+          stale_reason: "source file modified since observation",
+        };
+      }
+    } catch {
+      // skip this file on any error — best-effort
+    }
+  }
+  return null;
+}
+
 export const name = "get_context";
 
 export const description =
@@ -113,7 +268,15 @@ export const inputSchema = {
   tags: z
     .array(z.string())
     .optional()
-    .describe("Filter by tags (entries must match at least one)"),
+    .describe(
+      "Filter by tags (entries must match at least one). Use 'bucket:' prefixed tags for project-scoped retrieval (e.g., ['bucket:autohub']).",
+    ),
+  buckets: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "Filter by project-scoped buckets. Each name expands to a 'bucket:<name>' tag. Composes with 'tags' via OR (entries matching any tag or any bucket are included).",
+    ),
   since: z
     .string()
     .optional()
@@ -135,6 +298,30 @@ export const inputSchema = {
     .describe(
       "If true, compare results for contradicting entries and append a conflicts array. Flags superseded entries still in results and stale duplicates (same kind+tags, updated_at >7 days apart). No LLM calls — pure DB logic.",
     ),
+  max_tokens: z
+    .number()
+    .optional()
+    .describe(
+      "Limit output to entries that fit within this token budget (rough estimate: 1 token ≈ 4 chars). Entries are packed greedily by relevance rank. At least 1 result is always returned. Response metadata includes tokens_used and tokens_budget.",
+    ),
+  pivot_count: z
+    .number()
+    .optional()
+    .describe(
+      "Skeleton mode: top pivot_count entries by relevance are returned with full body. Remaining entries are returned as skeletons (title + tags + first ~100 chars of body). Default: 2. Set to 0 to skeleton all results, or a high number to disable.",
+    ),
+  include_ephemeral: z
+    .boolean()
+    .optional()
+    .describe(
+      "If true, include ephemeral tier entries in results. Default: false — only working and durable tiers are returned.",
+    ),
+  include_events: z
+    .boolean()
+    .optional()
+    .describe(
+      "If true, include event category entries in semantic search results. Default: false — events are excluded from query-based search but remain accessible via category/tag filters.",
+    ),
 };
 
 /**
@@ -149,11 +336,16 @@ export async function handler(
     category,
     identity_key,
     tags,
+    buckets,
     since,
     until,
     limit,
     include_superseded,
     detect_conflicts,
+    max_tokens,
+    pivot_count,
+    include_ephemeral,
+    include_events,
   },
   ctx,
   { ensureIndexed, reindexFailed },
@@ -162,8 +354,12 @@ export async function handler(
   const userId = ctx.userId !== undefined ? ctx.userId : undefined;
 
   const hasQuery = query?.trim();
+  const shouldExcludeEvents = hasQuery && !include_events && !category;
+  // Expand buckets to bucket: prefixed tags and merge with explicit tags
+  const bucketTags = buckets?.length ? buckets.map((b) => `bucket:${b}`) : [];
+  const effectiveTags = [...(tags ?? []), ...bucketTags];
   const hasFilters =
-    kind || category || tags?.length || since || until || identity_key;
+    kind || category || effectiveTags.length || since || until || identity_key;
   if (!hasQuery && !hasFilters)
     return err(
       "Required: query or at least one filter (kind, category, tags, since, until, identity_key)",
@@ -215,7 +411,7 @@ export async function handler(
   const effectiveLimit = limit || 10;
   // When tag-filtering, over-fetch to compensate for post-filter reduction
   const MAX_FETCH_LIMIT = 500;
-  const fetchLimit = tags?.length
+  const fetchLimit = effectiveTags.length
     ? Math.min(effectiveLimit * 10, MAX_FETCH_LIMIT)
     : effectiveLimit;
 
@@ -225,6 +421,7 @@ export async function handler(
     const sorted = await hybridSearch(ctx, query, {
       kindFilter,
       categoryFilter: category || null,
+      excludeEvents: shouldExcludeEvents,
       since: effectiveSince,
       until: effectiveUntil,
       limit: fetchLimit,
@@ -234,11 +431,11 @@ export async function handler(
     });
 
     // Post-filter by tags if provided, then apply requested limit
-    filtered = tags?.length
+    filtered = effectiveTags.length
       ? sorted
           .filter((r) => {
             const entryTags = r.tags ? JSON.parse(r.tags) : [];
-            return tags.some((t) => entryTags.includes(t));
+            return effectiveTags.some((t) => entryTags.includes(t));
           })
           .slice(0, effectiveLimit)
       : sorted;
@@ -267,6 +464,9 @@ export async function handler(
       params.push(effectiveUntil);
     }
     clauses.push("(expires_at IS NULL OR expires_at > datetime('now'))");
+    if (!include_superseded) {
+      clauses.push("superseded_by IS NULL");
+    }
     const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
     params.push(fetchLimit);
     const rows = ctx.db
@@ -274,11 +474,11 @@ export async function handler(
       .all(...params);
 
     // Post-filter by tags if provided, then apply requested limit
-    filtered = tags?.length
+    filtered = effectiveTags.length
       ? rows
           .filter((r) => {
             const entryTags = r.tags ? JSON.parse(r.tags) : [];
-            return tags.some((t) => entryTags.includes(t));
+            return effectiveTags.some((t) => entryTags.includes(t));
           })
           .slice(0, effectiveLimit)
       : rows;
@@ -287,6 +487,23 @@ export async function handler(
     for (const r of filtered) r.score = 0;
   }
 
+  // Brief score boost: briefs rank slightly higher so consolidated snapshots
+  // surface above the individual entries they summarize.
+  for (const r of filtered) {
+    if (r.kind === "brief") r.score = (r.score || 0) + BRIEF_SCORE_BOOST;
+  }
+  filtered.sort((a, b) => b.score - a.score);
+
+  // Tier filter: exclude ephemeral entries by default (NULL tier treated as working)
+  if (!include_ephemeral) {
+    filtered = filtered.filter((r) => r.tier !== "ephemeral");
+  }
+
+  // Event category filter: exclude events from semantic search by default
+  if (shouldExcludeEvents) {
+    filtered = filtered.filter((r) => r.category !== "event");
+  }
+
   if (!filtered.length) {
     if (autoWindowed) {
       const days = config.eventDecayDays || 30;
@@ -315,6 +532,29 @@ export async function handler(
     }
   }
 
+  // Token-budgeted packing
+  let tokensBudget = null;
+  let tokensUsed = null;
+  if (max_tokens != null && max_tokens > 0) {
+    tokensBudget = max_tokens;
+    const packed = [];
+    let used = 0;
+    for (const entry of filtered) {
+      const entryTokens = Math.ceil((entry.body?.length || 0) / 4);
+      if (packed.length === 0 || used + entryTokens <= tokensBudget) {
+        packed.push(entry);
+        used += entryTokens;
+      }
+      if (used >= tokensBudget) break;
+    }
+    tokensUsed = used;
+    filtered = packed;
+  }
+
+  // Skeleton mode: determine pivot threshold
+  const effectivePivot =
+    pivot_count != null ? pivot_count : DEFAULT_PIVOT_COUNT;
+
   // Conflict detection
   const conflicts = detect_conflicts ? detectConflicts(filtered, ctx) : [];
 
@@ -329,6 +569,11 @@ export async function handler(
     );
   const heading = hasQuery ? `Results for "${query}"` : "Filtered entries";
   lines.push(`## ${heading} (${filtered.length} matches)\n`);
+  if (tokensBudget != null) {
+    lines.push(
+      `> Token budget: ${tokensUsed} / ${tokensBudget} tokens used.\n`,
+    );
+  }
   if (autoWindowed) {
     const days = config.eventDecayDays || 30;
     lines.push(
@@ -337,23 +582,36 @@ export async function handler(
   }
   for (let i = 0; i < filtered.length; i++) {
     const r = filtered[i];
+    const isSkeleton = i >= effectivePivot;
     const entryTags = r.tags ? JSON.parse(r.tags) : [];
     const tagStr = entryTags.length ? entryTags.join(", ") : "none";
     const relPath =
       r.file_path && config.vaultDir
         ? r.file_path.replace(config.vaultDir + "/", "")
         : r.file_path || "n/a";
+    const skeletonLabel = isSkeleton ? " ⊘ skeleton" : "";
     lines.push(
-      `### [${i + 1}/${filtered.length}] ${r.title || "(untitled)"} [${r.kind}/${r.category}]`,
+      `### [${i + 1}/${filtered.length}] ${r.title || "(untitled)"} [${r.kind}/${r.category}]${skeletonLabel}`,
     );
     const dateStr =
       r.updated_at && r.updated_at !== r.created_at
         ? `${r.created_at} (updated ${r.updated_at})`
         : r.created_at || "";
+    const tierStr = r.tier ? ` · tier: ${r.tier}` : "";
     lines.push(
-      `${r.score.toFixed(3)} · ${tagStr} · ${relPath} · ${dateStr} · id: \`${r.id}\``,
+      `${r.score.toFixed(3)} · ${tagStr} · ${relPath} · ${dateStr} · skeleton: ${isSkeleton}${tierStr} · id: \`${r.id}\``,
     );
-    lines.push(r.body?.slice(0, 300) + (r.body?.length > 300 ? "..." : ""));
+    const stalenessResult = checkStaleness(r);
+    if (stalenessResult) {
+      r.stale = true;
+      r.stale_reason = stalenessResult.stale_reason;
+      lines.push(`> ⚠ **Stale**: ${stalenessResult.stale_reason}`);
+    }
+    if (isSkeleton) {
+      lines.push(skeletonBody(r.body));
+    } else {
+      lines.push(r.body?.slice(0, 300) + (r.body?.length > 300 ? "..." : ""));
+    }
     lines.push("");
   }
 
@@ -374,5 +632,47 @@ export async function handler(
     }
   }
 
-  return ok(lines.join("\n"));
+  // Consolidation suggestion detection — lazy, opportunistic, vault-wide
+  const consolidationOpts = {
+    tagThreshold:
+      config.consolidation?.tagThreshold ?? CONSOLIDATION_TAG_THRESHOLD,
+    maxAgeDays:
+      config.consolidation?.maxAgeDays ?? CONSOLIDATION_SNAPSHOT_MAX_AGE_DAYS,
+  };
+  const consolidationSuggestions = detectConsolidationHints(
+    filtered,
+    ctx.db,
+    userId,
+    consolidationOpts,
+  );
+
+  // Auto-consolidate: fire-and-forget create_snapshot for eligible tags
+  if (
+    config.consolidation?.autoConsolidate &&
+    consolidationSuggestions.length > 0
+  ) {
+    const { handler: snapshotHandler } = await import("./create-snapshot.js");
+    for (const suggestion of consolidationSuggestions) {
+      snapshotHandler({ topic: suggestion.tag, tags: [suggestion.tag] }, ctx, {
+        ensureIndexed: async () => {},
+      }).catch(() => {});
+    }
+  }
+
+  const result = ok(lines.join("\n"));
+  const meta = {};
+  if (tokensBudget != null) {
+    meta.tokens_used = tokensUsed;
+    meta.tokens_budget = tokensBudget;
+  }
+  if (buckets?.length) {
+    meta.buckets = buckets;
+  }
+  if (consolidationSuggestions.length > 0) {
+    meta.consolidation_suggestions = consolidationSuggestions;
+  }
+  if (Object.keys(meta).length > 0) {
+    result._meta = meta;
+  }
+  return result;
 }

package/src/server/tools/ingest-project.js

@@ -0,0 +1,244 @@
+import { z } from "zod";
+import { readFileSync, existsSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { join, basename } from "node:path";
+import { captureAndIndex } from "../../capture/index.js";
+import { ok, err, ensureVaultExists } from "../helpers.js";
+
+export const name = "ingest_project";
+
+export const description =
+  "Scan a local project directory and register it as a project entity in the vault. Extracts metadata from package.json, git history, and README. Also creates a bucket entity for project-scoped tagging.";
+
+export const inputSchema = {
+  path: z.string().describe("Absolute path to the project directory to ingest"),
+  tags: z
+    .array(z.string())
+    .optional()
+    .describe("Additional tags to apply (bucket tags are auto-generated)"),
+  pillar: z
+    .string()
+    .optional()
+    .describe("Parent pillar/domain name — creates a bucket:pillar tag"),
+};
+
+function safeRead(filePath) {
+  try {
+    return readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+function safeExec(cmd, cwd) {
+  try {
+    return execSync(cmd, { cwd, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function detectTechStack(projectPath, pkgJson) {
+  const stack = [];
+
+  if (existsSync(join(projectPath, "pyproject.toml")) || existsSync(join(projectPath, "setup.py"))) {
+    stack.push("python");
+  }
+  if (existsSync(join(projectPath, "Cargo.toml"))) {
+    stack.push("rust");
+  }
+  if (existsSync(join(projectPath, "go.mod"))) {
+    stack.push("go");
+  }
+  if (pkgJson) {
+    stack.push("javascript");
+    const allDeps = {
+      ...(pkgJson.dependencies || {}),
+      ...(pkgJson.devDependencies || {}),
+    };
+    if (allDeps.typescript || existsSync(join(projectPath, "tsconfig.json"))) {
+      stack.push("typescript");
+    }
+    if (allDeps.react || allDeps["react-dom"]) stack.push("react");
+    if (allDeps.next || allDeps["next"]) stack.push("nextjs");
+    if (allDeps.vue) stack.push("vue");
+    if (allDeps.svelte) stack.push("svelte");
+    if (allDeps.express) stack.push("express");
+    if (allDeps.fastify) stack.push("fastify");
+    if (allDeps.hono) stack.push("hono");
+    if (allDeps.vite) stack.push("vite");
+    if (allDeps.electron) stack.push("electron");
+    if (allDeps.tauri || allDeps["@tauri-apps/api"]) stack.push("tauri");
+  }
+
+  return [...new Set(stack)];
+}
+
+function extractReadmeDescription(projectPath) {
+  const raw = safeRead(join(projectPath, "README.md")) || safeRead(join(projectPath, "readme.md"));
+  if (!raw) return null;
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    return trimmed.slice(0, 200);
+  }
+  return null;
+}
+
+function buildProjectBody({ projectName, description, techStack, repoUrl, lastCommit, projectPath, hasClaudeMd }) {
+  const lines = [];
+  lines.push(`## ${projectName}`);
+  if (description) lines.push("", description);
+  lines.push("", "### Metadata");
+  lines.push(`- **Path**: \`${projectPath}\``);
+  if (repoUrl) lines.push(`- **Repo**: ${repoUrl}`);
+  if (techStack.length) lines.push(`- **Stack**: ${techStack.join(", ")}`);
+  if (lastCommit) lines.push(`- **Last commit**: ${lastCommit}`);
+  lines.push(`- **CLAUDE.md**: ${hasClaudeMd ? "yes" : "no"}`);
+  return lines.join("\n");
+}
+
+/**
+ * @param {object} args
+ * @param {import('../types.js').BaseCtx & Partial<import('../types.js').HostedCtxExtensions>} ctx
+ * @param {import('../types.js').ToolShared} shared
+ */
+export async function handler({ path: projectPath, tags, pillar }, ctx, { ensureIndexed }) {
+  const { config } = ctx;
+  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
+
+  const vaultErr = ensureVaultExists(config);
+  if (vaultErr) return vaultErr;
+
+  if (!projectPath?.trim()) {
+    return err("Required: path (absolute path to project directory)", "INVALID_INPUT");
+  }
+  if (!existsSync(projectPath)) {
+    return err(`Directory not found: ${projectPath}`, "INVALID_INPUT");
+  }
+
+  await ensureIndexed();
+
+  // Read package.json if present
+  let pkgJson = null;
+  const pkgPath = join(projectPath, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      pkgJson = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    } catch {
+      pkgJson = null;
+    }
+  }
+
+  // Derive project name
+  let projectName = basename(projectPath);
+  if (pkgJson?.name) {
+    projectName = pkgJson.name.replace(/^@[^/]+\//, "");
+  }
+
+  // Slug-safe identity_key
+  const identityKey = projectName.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+
+  // Description: package.json > README
+  const description =
+    pkgJson?.description || extractReadmeDescription(projectPath) || null;
+
+  // Tech stack detection
+  const techStack = detectTechStack(projectPath, pkgJson);
+
+  // Git metadata
+  const isGitRepo = existsSync(join(projectPath, ".git"));
+  const repoUrl = isGitRepo
+    ? safeExec("git remote get-url origin", projectPath)
+    : null;
+  const lastCommit = isGitRepo
+    ? safeExec("git log -1 --format=%ci", projectPath)
+    : null;
+
+  // CLAUDE.md presence
+  const hasClaudeMd = existsSync(join(projectPath, "CLAUDE.md"));
+
+  // Build tags
+  const bucketTag = `bucket:${identityKey}`;
+  const autoTags = [bucketTag];
+  if (pillar) autoTags.push(`bucket:${pillar}`);
+  const allTags = [...new Set([...autoTags, ...(tags || [])])];
+
+  // Build body
+  const body = buildProjectBody({
+    projectName,
+    description,
+    techStack,
+    repoUrl,
+    lastCommit,
+    projectPath,
+    hasClaudeMd,
+  });
+
+  // Build meta
+  const meta = {
+    path: projectPath,
+    ...(repoUrl ? { repo_url: repoUrl } : {}),
+    ...(techStack.length ? { tech_stack: techStack } : {}),
+    has_claude_md: hasClaudeMd,
+  };
+
+  // Save project entity
+  const projectEntry = await captureAndIndex(ctx, {
+    kind: "project",
+    title: projectName,
+    body,
+    tags: allTags,
+    identity_key: identityKey,
+    meta,
+    userId,
+  });
+
+  // Save bucket entity if it doesn't already exist
+  const bucketUserClause = userId !== undefined ? "AND user_id = ?" : "";
+  const bucketParams = userId !== undefined ? [bucketTag, userId] : [bucketTag];
+  const bucketExists = ctx.db
+    .prepare(
+      `SELECT 1 FROM vault WHERE kind = 'bucket' AND identity_key = ? ${bucketUserClause} LIMIT 1`,
+    )
+    .get(...bucketParams);
+
+  let bucketEntry = null;
+  if (!bucketExists) {
+    bucketEntry = await captureAndIndex(ctx, {
+      kind: "bucket",
+      title: projectName,
+      body: `Bucket for project: ${projectName}`,
+      tags: allTags,
+      identity_key: bucketTag,
+      meta: { project_path: projectPath },
+      userId,
+    });
+  }
+
+  const relPath = projectEntry.filePath
+    ? projectEntry.filePath.replace(config.vaultDir + "/", "")
+    : projectEntry.filePath;
+
+  const parts = [
+    `✓ Ingested project → ${relPath}`,
+    `  id: ${projectEntry.id}`,
+    `  title: ${projectEntry.title}`,
+    `  tags: ${allTags.join(", ")}`,
+    ...(techStack.length ? [`  stack: ${techStack.join(", ")}`] : []),
+    ...(repoUrl ? [`  repo: ${repoUrl}`] : []),
+  ];
+
+  if (bucketEntry) {
+    const bucketRelPath = bucketEntry.filePath
+      ? bucketEntry.filePath.replace(config.vaultDir + "/", "")
+      : bucketEntry.filePath;
+    parts.push(``, `✓ Created bucket → ${bucketRelPath}`);
+    parts.push(`  id: ${bucketEntry.id}`);
+  } else {
+    parts.push(``, `  (bucket '${bucketTag}' already exists — skipped)`);
+  }
+
+  parts.push("", "_Use get_context with bucket tag to retrieve project-scoped entries._");
+  return ok(parts.join("\n"));
+}