grounder 0.3.0 → 0.5.0

package/dist/vault/search.js

@@ -0,0 +1,328 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { parseHandoffFrontmatter } from "../util/frontmatter.js";
+import { listMarkdownFiles } from "./list-markdown.js";
+const DEFAULT_LIMIT = 10;
+const DEFAULT_MAX_HITS = 50;
+const DEFAULT_CONTEXT = 1;
+const DEFAULT_MAX_HITS_PER_FILE = 1;
+/** Cap line hits stored per file during scan (counts stay full for ranking). */
+const MAX_STORED_HITS_PER_FILE = 50;
+/** Known vault subfolders — light tiebreaker after recency. */
+const FOLDER_SIGNAL = {
+    notes: 2,
+    plans: 2,
+    logs: 1,
+};
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Single-token terms only — phrases may contain spaces or punctuation. */
+function isWordLikeTerm(term) {
+    return /^[\w-]+$/.test(term);
+}
+function pruneOverlappingTerms(query, terms) {
+    const queryKey = query.trim().toLowerCase();
+    return terms.filter((term) => {
+        const lower = term.toLowerCase();
+        if (lower === queryKey) {
+            return true;
+        }
+        return !terms.some((other) => {
+            if (other === term) {
+                return false;
+            }
+            const otherLower = other.toLowerCase();
+            if (otherLower.length <= lower.length || !isWordLikeTerm(term) || !isWordLikeTerm(other)) {
+                return false;
+            }
+            return otherLower.startsWith(lower);
+        });
+    });
+}
+function normalizeTerms(query, extra) {
+    const seen = new Set();
+    const out = [];
+    // Always include the query — multi-word phrases use substring matching in
+    // termMatchesLine, so exact phrases only match lines that contain them verbatim.
+    for (const raw of [query, ...(extra ?? [])]) {
+        const term = raw.trim();
+        if (!term) {
+            continue;
+        }
+        const key = term.toLowerCase();
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        out.push(term);
+    }
+    return pruneOverlappingTerms(query, out);
+}
+/**
+ * Soft-demote search dogfood notes when the user is not asking about search.
+ * (`discussions/search/…`, `search-feature.md`, `Search Results.md`)
+ */
+function searchMetaPenalty(rootDir, filePath, query) {
+    if (/\bsearch\b/i.test(query)) {
+        return 0;
+    }
+    const rel = path.relative(rootDir, filePath);
+    const segments = rel.split(path.sep).map((segment) => segment.toLowerCase());
+    for (let i = 0; i < segments.length - 1; i++) {
+        if (segments[i] === "discussions" && segments[i + 1] === "search") {
+            return 1;
+        }
+    }
+    const stem = path.basename(filePath, path.extname(filePath)).toLowerCase();
+    if (stem === "search-feature" || stem === "search results") {
+        return 1;
+    }
+    return 0;
+}
+function termMatchesLine(line, term) {
+    if (term.includes(" ")) {
+        return line.toLowerCase().includes(term.toLowerCase());
+    }
+    const re = new RegExp(`\\b${escapeRegex(term)}\\b`, "i");
+    return re.test(line);
+}
+function matchingTermsOnLine(line, terms) {
+    return terms.filter((term) => termMatchesLine(line, term));
+}
+function longestTerm(matches) {
+    return matches.reduce((best, term) => (term.length > best.length ? term : best));
+}
+function topicsMatchTerms(topics, terms) {
+    if (!topics?.length) {
+        return false;
+    }
+    const lowered = topics.map((t) => t.toLowerCase());
+    return terms.some((term) => lowered.includes(term.toLowerCase()));
+}
+function folderSignal(rootDir, filePath) {
+    const rel = path.relative(rootDir, filePath);
+    const first = rel.split(path.sep)[0];
+    return first ? (FOLDER_SIGNAL[first] ?? 0) : 0;
+}
+/** Deprioritize archived plans/notes — still searchable, ranked lower. */
+function archivePenalty(rootDir, filePath) {
+    const rel = path.relative(rootDir, filePath);
+    const segments = rel.split(path.sep);
+    return segments.some((segment) => segment.toLowerCase() === "archive") ? 1 : 0;
+}
+function buildSnippet(lines, lineIndex, context) {
+    const start = Math.max(0, lineIndex - context);
+    const end = Math.min(lines.length - 1, lineIndex + context);
+    const parts = [];
+    for (let i = start; i <= end; i++) {
+        parts.push(lines[i] ?? "");
+    }
+    return parts.join("\n");
+}
+function countFilenameTermMatches(rootDir, filePath, terms) {
+    const rel = path.relative(rootDir, filePath);
+    const haystack = rel.replace(/[/\\]/g, " ").replace(/\.md$/i, "").toLowerCase();
+    let count = 0;
+    for (const term of terms) {
+        const lower = term.toLowerCase();
+        if (lower.includes(" ")) {
+            if (haystack.includes(lower)) {
+                count++;
+            }
+            continue;
+        }
+        const re = new RegExp(`\\b${escapeRegex(lower)}\\b`, "i");
+        if (re.test(haystack)) {
+            count++;
+        }
+    }
+    return count;
+}
+function contentHasPhrase(content, query) {
+    const trimmed = query.trim();
+    if (!trimmed.includes(" ")) {
+        return false;
+    }
+    return content.toLowerCase().includes(trimmed.toLowerCase());
+}
+/**
+ * Partial n-gram match: 2 consecutive words for 3-word queries, 3 consecutive
+ * words for 4+ word queries. Trigrams cut false positives where a doc only
+ * shares a loose bigram (e.g. "slash commands") without migration context.
+ */
+function contentHasPartialPhrase(content, query) {
+    const words = query.trim().split(/\s+/).filter(Boolean);
+    if (words.length < 3) {
+        return false;
+    }
+    const lower = content.toLowerCase();
+    const windowSize = words.length >= 4 ? 3 : 2;
+    for (let i = 0; i <= words.length - windowSize; i++) {
+        const ngram = words
+            .slice(i, i + windowSize)
+            .join(" ")
+            .toLowerCase();
+        if (lower.includes(ngram)) {
+            return true;
+        }
+    }
+    return false;
+}
+function relevanceScore(file, rootDir, query) {
+    return (file.distinctTermCount * 1000 +
+        Math.min(file.idfDensity, 100) * 10 +
+        (file.topicsMatch ? 800 : 0) +
+        file.filenameTermCount * 200 +
+        (file.phraseMatch ? 300 : 0) +
+        (file.partialPhraseMatch ? 100 : 0) -
+        // Strong enough to lose to real notes with similar distinct-term coverage
+        // (meta dumps / search dogfood often win on raw hit density alone).
+        searchMetaPenalty(rootDir, file.filePath, query) * 5000);
+}
+function pickBestHits(hits, maxHitsPerFile) {
+    if (hits.length <= maxHitsPerFile) {
+        return hits;
+    }
+    const sorted = [...hits].sort((a, b) => b.matchedTerm.length - a.matchedTerm.length);
+    return sorted.slice(0, maxHitsPerFile);
+}
+/**
+ * Case-insensitive markdown scan under `rootDir`.
+ * Frontmatter `topics:` matches boost file ranking; body and frontmatter lines
+ * both contribute line hits. Files rank by relevance (distinct terms, hit
+ * density, filename/path terms, topics; demotes search dogfood when query is
+ * unrelated), then archive, recency, folder. Pure fs — no index, no deps.
+ */
+export async function searchVault(options) {
+    const terms = normalizeTerms(options.query, options.terms);
+    const limit = options.limit ?? DEFAULT_LIMIT;
+    const maxHits = options.maxHits ?? DEFAULT_MAX_HITS;
+    const context = options.context ?? DEFAULT_CONTEXT;
+    const maxHitsPerFile = options.maxHitsPerFile ?? DEFAULT_MAX_HITS_PER_FILE;
+    const perFileStoreCap = Math.min(MAX_STORED_HITS_PER_FILE, maxHits);
+    if (terms.length === 0) {
+        return {
+            query: options.query,
+            terms: [],
+            termHitCounts: {},
+            totalMatchCount: 0,
+            totalFileCount: 0,
+            files: [],
+            truncated: false,
+        };
+    }
+    const filePaths = await listMarkdownFiles(options.rootDir);
+    const rawFiles = [];
+    let totalMatchCount = 0;
+    // Lowercased doc-freq for ranking; JSON output remaps to original `terms` spelling.
+    const termDocFreq = Object.fromEntries(terms.map((t) => [t.toLowerCase(), 0]));
+    for (const filePath of filePaths) {
+        let content;
+        let mtimeMs;
+        try {
+            [content, { mtimeMs }] = await Promise.all([readFile(filePath, "utf8"), stat(filePath)]);
+        }
+        catch {
+            continue;
+        }
+        if (options.since !== undefined && mtimeMs < options.since.getTime()) {
+            continue;
+        }
+        const lines = content.split(/\r?\n/);
+        const frontmatter = parseHandoffFrontmatter(content);
+        const topicsMatch = topicsMatchTerms(frontmatter.topics, terms);
+        const fileHits = [];
+        const matchedTerms = new Set();
+        const perTermHits = new Map();
+        let totalHitCount = 0;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i] ?? "";
+            const lineMatches = matchingTermsOnLine(line, terms);
+            if (lineMatches.length === 0) {
+                continue;
+            }
+            for (const term of lineMatches) {
+                const termKey = term.toLowerCase();
+                matchedTerms.add(termKey);
+                perTermHits.set(termKey, (perTermHits.get(termKey) ?? 0) + 1);
+            }
+            totalHitCount++;
+            totalMatchCount++;
+            if (fileHits.length < perFileStoreCap) {
+                fileHits.push({
+                    line: i + 1,
+                    matchedTerm: longestTerm(lineMatches),
+                    snippet: buildSnippet(lines, i, context),
+                });
+            }
+        }
+        if (matchedTerms.size > 0) {
+            for (const t of matchedTerms) {
+                termDocFreq[t] = (termDocFreq[t] ?? 0) + 1;
+            }
+            rawFiles.push({
+                filePath,
+                mtimeMs,
+                topicsMatch,
+                hits: fileHits,
+                distinctTermCount: matchedTerms.size,
+                totalHitCount,
+                idfDensity: 0,
+                filenameTermCount: countFilenameTermMatches(options.rootDir, filePath, terms),
+                phraseMatch: contentHasPhrase(content, options.query),
+                partialPhraseMatch: contentHasPartialPhrase(content, options.query),
+                perTermHits,
+            });
+        }
+    }
+    // Scale hit density by IDF so rare identifiers outweigh common tokens like "grounder".
+    for (const file of rawFiles) {
+        let density = 0;
+        for (const [term, count] of file.perTermHits) {
+            const df = termDocFreq[term] ?? 1;
+            density += count / Math.log(1 + df);
+        }
+        file.idfDensity = density;
+    }
+    rawFiles.sort((a, b) => {
+        const scoreDiff = relevanceScore(b, options.rootDir, options.query) -
+            relevanceScore(a, options.rootDir, options.query);
+        if (scoreDiff !== 0) {
+            return scoreDiff;
+        }
+        const archiveDiff = archivePenalty(options.rootDir, a.filePath) - archivePenalty(options.rootDir, b.filePath);
+        if (archiveDiff !== 0) {
+            return archiveDiff;
+        }
+        if (a.mtimeMs !== b.mtimeMs) {
+            return b.mtimeMs - a.mtimeMs;
+        }
+        const folderDiff = folderSignal(options.rootDir, b.filePath) - folderSignal(options.rootDir, a.filePath);
+        if (folderDiff !== 0) {
+            return folderDiff;
+        }
+        return a.filePath.localeCompare(b.filePath);
+    });
+    const totalFileCount = rawFiles.length;
+    const truncated = totalFileCount > limit;
+    const files = rawFiles.slice(0, limit).map((file) => ({
+        filePath: file.filePath,
+        mtimeMs: file.mtimeMs,
+        topicsMatch: file.topicsMatch,
+        hits: pickBestHits(file.hits, maxHitsPerFile),
+        matchedTerms: terms
+            .filter((term) => file.perTermHits.has(term.toLowerCase()))
+            .sort((a, b) => b.length - a.length),
+    }));
+    return {
+        query: options.query,
+        terms,
+        termHitCounts: Object.fromEntries(terms.map((term) => [term, termDocFreq[term.toLowerCase()] ?? 0])),
+        totalMatchCount,
+        totalFileCount,
+        files,
+        truncated,
+    };
+}
+//# sourceMappingURL=search.js.map

package/dist/vault/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/vault/search.ts"],"names":[],"mappings":"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"}

package/dist/vault/write-handoff.d.ts

@@ -6,6 +6,8 @@ export interface WriteHandoffOptions {
     title?: string;
     /** Git branch when known; omitted from frontmatter if unset. */
     branch?: string;
+    /** 3-5 topic keywords for search (flat list, omitted when empty/unset). */
+    topics?: string[];
     /** Timestamp for filename prefix and `created` (default: now). */
     now?: Date;
 }

package/dist/vault/write-handoff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-handoff.d.ts","sourceRoot":"","sources":["../../src/vault/write-handoff.ts"],"names":[],"mappings":"AAKA,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAoBD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAiBjB"}
+{"version":3,"file":"write-handoff.d.ts","sourceRoot":"","sources":["../../src/vault/write-handoff.ts"],"names":[],"mappings":"AAKA,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,kEAAkE;IAClE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAyBD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAkBjB"}

package/dist/vault/write-handoff.js

@@ -11,6 +11,10 @@ function buildFrontmatter(options) {
     if (options.title) {
         lines.push(`title: ${yamlDoubleQuoted(options.title)}`);
     }
+    if (options.topics && options.topics.length > 0) {
+        const items = options.topics.map((t) => yamlDoubleQuoted(t)).join(", ");
+        lines.push(`topics: [${items}]`);
+    }
     lines.push("---");
     return `${lines.join("\n")}\n\n`;
 }
@@ -34,6 +38,7 @@ export async function writeHandoff(logsDir, body, options) {
         branch: options.branch,
         created: now.toISOString(),
         title: options.title,
+        topics: options.topics,
     }) + body;
     return writeUniqueMarkdown(logsDir, basename, content);
 }

package/dist/vault/write-handoff.js.map

@@ -1 +1 @@
-{"version":3,"file":"write-handoff.js","sourceRoot":"","sources":["../../src/vault/write-handoff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAcnD,SAAS,gBAAgB,CAAC,OAKzB;IACC,MAAM,KAAK,GAAG,CAAC,KAAK,EAAE,YAAY,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACzE,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,KAAK,CAAC,IAAI,CAAC,WAAW,gBAAgB,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,YAAY,gBAAgB,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC5D,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,UAAU,gBAAgB,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;AACnC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAe,EACf,IAAY,EACZ,OAA4B;IAE5B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IACtC,MAAM,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE1C,MAAM,QAAQ,GAAG,mBAAmB,CAAC,IAAI,EAAE;QACzC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,GAAG;KACJ,CAAC,CAAC;IACH,MAAM,OAAO,GACX,gBAAgB,CAAC;QACf,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,GAAG,CAAC,WAAW,EAAE;QAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC,GAAG,IAAI,CAAC;IAEZ,OAAO,mBAAmB,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AACzD,CAAC"}
+{"version":3,"file":"write-handoff.js","sourceRoot":"","sources":["../../src/vault/write-handoff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAgBnD,SAAS,gBAAgB,CAAC,OAMzB;IACC,MAAM,KAAK,GAAG,CAAC,KAAK,EAAE,YAAY,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACzE,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,KAAK,CAAC,IAAI,CAAC,WAAW,gBAAgB,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,YAAY,gBAAgB,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC5D,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,UAAU,gBAAgB,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChD,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxE,KAAK,CAAC,IAAI,CAAC,YAAY,KAAK,GAAG,CAAC,CAAC;IACnC,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;AACnC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAe,EACf,IAAY,EACZ,OAA4B;IAE5B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IACtC,MAAM,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE1C,MAAM,QAAQ,GAAG,mBAAmB,CAAC,IAAI,EAAE;QACzC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,GAAG;KACJ,CAAC,CAAC;IACH,MAAM,OAAO,GACX,gBAAgB,CAAC;QACf,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,GAAG,CAAC,WAAW,EAAE;QAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,GAAG,IAAI,CAAC;IAEZ,OAAO,mBAAmB,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AACzD,CAAC"}

package/dist/vault/write-note.d.ts

@@ -1,5 +1,7 @@
 export interface WriteNoteOptions {
     title?: string;
+    /** 3-5 topic keywords for search (flat list, omitted when empty/unset). */
+    topics?: string[];
     now?: Date;
 }
 /**

package/dist/vault/write-note.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-note.d.ts","sourceRoot":"","sources":["../../src/vault/write-note.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAMjB"}
+{"version":3,"file":"write-note.d.ts","sourceRoot":"","sources":["../../src/vault/write-note.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAQD;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAOjB"}

package/dist/vault/write-note.js

@@ -1,6 +1,13 @@
 import { mkdir } from "node:fs/promises";
 import { writeUniqueMarkdown } from "../util/fs.js";
 import { timestampedBasename } from "../util/timestamp-slug.js";
+import { yamlDoubleQuoted } from "../util/yaml.js";
+function buildNoteContent(text, topics) {
+    if (!topics || topics.length === 0)
+        return text;
+    const items = topics.map((t) => yamlDoubleQuoted(t)).join(", ");
+    return `---\ntopics: [${items}]\n---\n\n${text}`;
+}
 /**
  * Writes a new note markdown file under `notesDir` (created if missing).
  * Never overwrites — exclusive create with `_NN` on collision.
@@ -10,6 +17,7 @@ export async function writeNote(notesDir, text, options = {}) {
     const now = options.now ?? new Date();
     await mkdir(notesDir, { recursive: true });
     const basename = timestampedBasename(text, { title: options.title, now });
-    return writeUniqueMarkdown(notesDir, basename, text);
+    const content = buildNoteContent(text, options.topics);
+    return writeUniqueMarkdown(notesDir, basename, content);
 }
 //# sourceMappingURL=write-note.js.map

package/dist/vault/write-note.js.map

@@ -1 +1 @@
-{"version":3,"file":"write-note.js","sourceRoot":"","sources":["../../src/vault/write-note.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAOhE;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,QAAgB,EAChB,IAAY,EACZ,UAA4B,EAAE;IAE9B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IACtC,MAAM,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE3C,MAAM,QAAQ,GAAG,mBAAmB,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IAC1E,OAAO,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;AACvD,CAAC"}
+{"version":3,"file":"write-note.js","sourceRoot":"","sources":["../../src/vault/write-note.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AASnD,SAAS,gBAAgB,CAAC,IAAY,EAAE,MAAiB;IACvD,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAChD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChE,OAAO,iBAAiB,KAAK,aAAa,IAAI,EAAE,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,QAAgB,EAChB,IAAY,EACZ,UAA4B,EAAE;IAE9B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IACtC,MAAM,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE3C,MAAM,QAAQ,GAAG,mBAAmB,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IAC1E,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACvD,OAAO,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AAC1D,CAAC"}

package/dist/vault/write-plan.d.ts

@@ -4,6 +4,8 @@ export interface WritePlanOptions {
     projectId: string;
     /** When true, overwrite an existing plan (preserving original `created`). */
     force?: boolean;
+    /** 3-5 topic keywords for search (flat list, omitted when empty/unset). */
+    topics?: string[];
     /** Timestamp for `created` / `updated` (default: now). */
     now?: Date;
 }
@@ -15,6 +17,7 @@ export interface WritePlanResult {
 /**
  * Overwrites an existing plan at an absolute path.
  * Preserves original `created` (falls back to `now` if missing) and sets `updated`.
+ * Omitting `topics` keeps existing frontmatter topics; passing `topics` replaces them.
  * Caller must validate the path (e.g. inside this project's `plans/` dir).
  */
 export declare function updatePlanAtPath(filePath: string, body: string, options: Omit<WritePlanOptions, "force">): Promise<WritePlanResult>;
@@ -23,6 +26,7 @@ export declare function updatePlanAtPath(filePath: string, body: string, options
  * Target is always `plansDir/<name>.md` — no collision suffixes.
  * Without `force`, an existing file is left untouched and status `"exists"` is returned.
  * With `force`, overwrites the body, preserves original `created`, and sets `updated`.
+ * Omitting `topics` on overwrite keeps existing frontmatter topics.
  */
 export declare function writePlan(plansDir: string, name: string, body: string, options: WritePlanOptions): Promise<WritePlanResult>;
 //# sourceMappingURL=write-plan.d.ts.map

package/dist/vault/write-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-plan.d.ts","sourceRoot":"","sources":["../../src/vault/write-plan.ts"],"names":[],"mappings":"AAMA,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,CAAC;AAEnE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,eAAe,CAAC;CACzB;AAmBD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,CAAC,GACvC,OAAO,CAAC,eAAe,CAAC,CAgB1B;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAuB1B"}
+{"version":3,"file":"write-plan.d.ts","sourceRoot":"","sources":["../../src/vault/write-plan.ts"],"names":[],"mappings":"AAMA,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,CAAC;AAEnE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,eAAe,CAAC;CACzB;AAwBD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,CAAC,GACvC,OAAO,CAAC,eAAe,CAAC,CAkB1B;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CA4B1B"}

package/dist/vault/write-plan.js

@@ -12,12 +12,17 @@ function buildFrontmatter(options) {
     if (options.updated) {
         lines.push(`updated: ${yamlDoubleQuoted(options.updated)}`);
     }
+    if (options.topics && options.topics.length > 0) {
+        const items = options.topics.map((t) => yamlDoubleQuoted(t)).join(", ");
+        lines.push(`topics: [${items}]`);
+    }
     lines.push("---");
     return `${lines.join("\n")}\n\n`;
 }
 /**
  * Overwrites an existing plan at an absolute path.
  * Preserves original `created` (falls back to `now` if missing) and sets `updated`.
+ * Omitting `topics` keeps existing frontmatter topics; passing `topics` replaces them.
  * Caller must validate the path (e.g. inside this project's `plans/` dir).
  */
 export async function updatePlanAtPath(filePath, body, options) {
@@ -26,10 +31,12 @@ export async function updatePlanAtPath(filePath, body, options) {
     const fm = parseHandoffFrontmatter(existing);
     const created = fm.created ?? now.toISOString();
     const updated = now.toISOString();
+    const topics = options.topics ?? fm.topics;
     const content = buildFrontmatter({
         projectId: options.projectId,
         created,
         updated,
+        topics,
     }) + body;
     await writeFile(filePath, content, "utf8");
     return { path: filePath, status: "overwritten" };
@@ -39,6 +46,7 @@ export async function updatePlanAtPath(filePath, body, options) {
  * Target is always `plansDir/<name>.md` — no collision suffixes.
  * Without `force`, an existing file is left untouched and status `"exists"` is returned.
  * With `force`, overwrites the body, preserves original `created`, and sets `updated`.
+ * Omitting `topics` on overwrite keeps existing frontmatter topics.
  */
 export async function writePlan(plansDir, name, body, options) {
     const now = options.now ?? new Date();
@@ -49,11 +57,16 @@ export async function writePlan(plansDir, name, body, options) {
         return { path: filePath, status: "exists" };
     }
     if (exists && options.force) {
-        return updatePlanAtPath(filePath, body, { projectId: options.projectId, now });
+        return updatePlanAtPath(filePath, body, {
+            projectId: options.projectId,
+            topics: options.topics,
+            now,
+        });
     }
     const content = buildFrontmatter({
         projectId: options.projectId,
         created: now.toISOString(),
+        topics: options.topics,
     }) + body;
     await writeFile(filePath, content, "utf8");
     return { path: filePath, status: "created" };

package/dist/vault/write-plan.js.map

@@ -1 +1 @@
-{"version":3,"file":"write-plan.js","sourceRoot":"","sources":["../../src/vault/write-plan.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"write-plan.js","sourceRoot":"","sources":["../../src/vault/write-plan.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "grounder",
-  "version": "0.3.0",
-  "description": "Connect git projects to Obsidian dev vaults for AI agent memory",
+  "version": "0.5.0",
+  "description": "Connect projects to an Obsidian vault (or any markdown folder) for AI agent memory — session handoffs, plans, and notes in files you own",
   "type": "module",
   "bin": {
     "grounder": "./dist/cli.js"
@@ -16,9 +16,18 @@
   "keywords": [
     "obsidian",
     "cursor",
-    "mcp",
+    "claude-code",
+    "handoff",
+    "developer-tools",
     "ai",
-    "cli"
+    "cli",
+    "agent-memory",
+    "local-first",
+    "vault",
+    "session-handoff",
+    "context-management",
+    "second-brain",
+    "pkm"
   ],
   "license": "MIT",
   "repository": {

package/templates/agents/claude/commands/grounder-note.md

@@ -1,11 +1,37 @@
-Save a note to the Obsidian vault for this project.
+Save a note to the markdown vault for this project.
 
-Run from the linked project folder or any subdirectory beneath it:
+Distill the instruction after `/grounder-note` into a clean note body — not a chat transcript.
+Do not dump tool traces, full conversation, or false starts.
 
-  {{GROUNDER_CLI}} note "<user text>"
+**Special case: the instruction asks to view existing notes, not write one** (`list`, `list 3 oldest`, `show notes`, etc.) → run `{{GROUNDER_CLI}} note list --limit <N> --markdown` (N = count named, else 5; ignore order words like "oldest" — output is always newest-first, never resort or relabel it) and stop — no note write. Relay the CLI stdout as-is (it already includes the count header; title lines are clickable `[relativePath](fileUri)` links).
+
+Rules:
+- Default → distill the args into a clean note body
+- Exact wording marked to keep (quoted, "save exactly:"/"verbatim:", or a fenced block) → use that verbatim instead, unmodified
+- Empty args → distill the central point of the current thread instead
+
+Then run from the linked project folder or any subdirectory beneath it:
+
+  {{GROUNDER_CLI}} note "<body>"
+
+Optional short title slug (filename):
+
+  {{GROUNDER_CLI}} note --title <slug> "<body>"
+
+Always include `--topics` with 3-5 comma-separated lowercase keywords that capture the note's core concepts (e.g. `--topics "schema,migration,postgres"`). Pick terms a future search would use — concrete nouns and technical terms, not verbs or filler:
+
+  {{GROUNDER_CLI}} note --topics "keyword1,keyword2,keyword3" "<body>"
+
+For multi-line bodies, prefer a shell heredoc so quoting does not break:
+
+```bash
+{{GROUNDER_CLI}} note "$(cat <<'EOF'
+…
+EOF
+)"
+```
 
 The vault is outside the workspace — grant shell permissions if Claude Code prompts you.
 
-Use the text after `/grounder-note` as the note body.
 Do not compute vault paths or write files yourself — the CLI handles it.
 Report the CLI output path from stdout to the user.