grounder 0.5.0 → 0.6.0

package/dist/util/merge-json.d.ts

@@ -1,15 +1,26 @@
 export type MergeJsonResult = {
     ok: true;
     created: boolean;
+    changed: boolean;
 } | {
     ok: false;
     error: "unparseable";
     message: string;
 };
+export interface MergeJsonFileOptions {
+    /** Compute the result without writing to disk. */
+    dryRun?: boolean;
+}
 /**
- * Read a JSON object file (default `{}` if missing), apply `merge`, write pretty-printed.
+ * Read a JSON object file (default `{}` if missing), apply `merge`, write pretty-printed —
+ * only when the merged content actually differs from what's on disk, so callers can trust
+ * `changed` to mean a real content change rather than "we ran the merge function."
+ * A `merge` that returns its `current` argument by reference is treated as a no-op and
+ * never writes, even if the file's on-disk formatting (indentation, line endings, key
+ * order) differs from `JSON.stringify(current, null, 2)` — callers rely on this to leave
+ * a file with nothing to change byte-for-byte untouched instead of reformatting it.
  * On parse failure or non-object root: leaves the file untouched and returns an error
  * so callers can warn without clobbering shared config.
  */
-export declare function mergeJsonFile(filePath: string, merge: (current: Record<string, unknown>) => Record<string, unknown>): Promise<MergeJsonResult>;
+export declare function mergeJsonFile(filePath: string, merge: (current: Record<string, unknown>) => Record<string, unknown>, options?: MergeJsonFileOptions): Promise<MergeJsonResult>;
 //# sourceMappingURL=merge-json.d.ts.map

package/dist/util/merge-json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"merge-json.d.ts","sourceRoot":"","sources":["../../src/util/merge-json.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnE,OAAO,CAAC,eAAe,CAAC,CAiC1B"}
+{"version":3,"file":"merge-json.d.ts","sourceRoot":"","sources":["../../src/util/merge-json.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAChD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,MAAM,WAAW,oBAAoB;IACnC,kDAAkD;IAClD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpE,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,eAAe,CAAC,CA2C1B"}

package/dist/util/merge-json.js

@@ -1,19 +1,25 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { fileExists } from "./fs.js";
+import { readFile, stat } from "node:fs/promises";
+import { fileExists, writeFileAtomic } from "./fs.js";
 /**
- * Read a JSON object file (default `{}` if missing), apply `merge`, write pretty-printed.
+ * Read a JSON object file (default `{}` if missing), apply `merge`, write pretty-printed —
+ * only when the merged content actually differs from what's on disk, so callers can trust
+ * `changed` to mean a real content change rather than "we ran the merge function."
+ * A `merge` that returns its `current` argument by reference is treated as a no-op and
+ * never writes, even if the file's on-disk formatting (indentation, line endings, key
+ * order) differs from `JSON.stringify(current, null, 2)` — callers rely on this to leave
+ * a file with nothing to change byte-for-byte untouched instead of reformatting it.
  * On parse failure or non-object root: leaves the file untouched and returns an error
  * so callers can warn without clobbering shared config.
  */
-export async function mergeJsonFile(filePath, merge) {
+export async function mergeJsonFile(filePath, merge, options = {}) {
     const existed = await fileExists(filePath);
     let current = {};
+    let originalRaw;
     if (existed) {
-        const raw = await readFile(filePath, "utf8");
+        originalRaw = await readFile(filePath, "utf8");
         let parsed;
         try {
-            parsed = JSON.parse(raw);
+            parsed = JSON.parse(originalRaw);
         }
         catch (err) {
             const detail = err instanceof Error ? err.message : String(err);
@@ -33,8 +39,16 @@ export async function mergeJsonFile(filePath, merge) {
         current = parsed;
     }
     const next = merge(current);
-    await mkdir(path.dirname(filePath), { recursive: true });
-    await writeFile(filePath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
-    return { ok: true, created: !existed };
+    const nextRaw = `${JSON.stringify(next, null, 2)}\n`;
+    const changed = next !== current && nextRaw !== originalRaw;
+    if (changed && !options.dryRun) {
+        // Preserve the existing file's permission bits across the tmp+rename
+        // swap — these are host-owned config files (Cursor/Claude Code), not
+        // Grounder's own state, so a rename shouldn't reset them to the tmp
+        // file's default umask.
+        const mode = existed ? (await stat(filePath)).mode & 0o777 : undefined;
+        await writeFileAtomic(filePath, nextRaw, mode !== undefined ? { mode } : {});
+    }
+    return { ok: true, created: !existed, changed };
 }
 //# sourceMappingURL=merge-json.js.map

package/dist/util/merge-json.js.map

@@ -1 +1 @@
-{"version":3,"file":"merge-json.js","sourceRoot":"","sources":["../../src/util/merge-json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAMrC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAAgB,EAChB,KAAoE;IAEpE,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,OAAO,GAA4B,EAAE,CAAC;IAE1C,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC7C,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAChE,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,aAAa;gBACpB,OAAO,EAAE,sBAAsB,QAAQ,mBAAmB,MAAM,GAAG;aACpE,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3E,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,aAAa;gBACpB,OAAO,EAAE,sBAAsB,QAAQ,oCAAoC;aAC5E,CAAC;QACJ,CAAC;QAED,OAAO,GAAG,MAAiC,CAAC;IAC9C,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5B,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,MAAM,SAAS,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;AACzC,CAAC"}
+{"version":3,"file":"merge-json.js","sourceRoot":"","sources":["../../src/util/merge-json.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAWtD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,QAAgB,EAChB,KAAoE,EACpE,UAAgC,EAAE;IAElC,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,OAAO,GAA4B,EAAE,CAAC;IAC1C,IAAI,WAA+B,CAAC;IAEpC,IAAI,OAAO,EAAE,CAAC;QACZ,WAAW,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC/C,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QACnC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAChE,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,aAAa;gBACpB,OAAO,EAAE,sBAAsB,QAAQ,mBAAmB,MAAM,GAAG;aACpE,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3E,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,aAAa;gBACpB,OAAO,EAAE,sBAAsB,QAAQ,oCAAoC;aAC5E,CAAC;QACJ,CAAC;QAED,OAAO,GAAG,MAAiC,CAAC;IAC9C,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5B,MAAM,OAAO,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;IACrD,MAAM,OAAO,GAAG,IAAI,KAAK,OAAO,IAAI,OAAO,KAAK,WAAW,CAAC;IAE5D,IAAI,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QAC/B,qEAAqE;QACrE,qEAAqE;QACrE,oEAAoE;QACpE,wBAAwB;QACxB,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QACvE,MAAM,eAAe,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC;AAClD,CAAC"}

package/dist/vault/list-handoffs.d.ts

@@ -2,11 +2,21 @@ export interface ListHandoffsOptions {
     /** Max paths to return (newest first). Omit to return all. */
     limit?: number;
 }
+/** One handoff with its mtime (see {@link listHandoffsDetailed}). */
+export interface HandoffEntry {
+    path: string;
+    mtimeMs: number;
+}
 /**
  * Lists handoff markdown files under `logsDir` recursively, newest basename
- * first (timestamp-prefixed names sort correctly). Same basename in different
- * subfolders ties break by vault-relative path descending.
- * Returns absolute paths. Missing or empty dirs yield `[]`.
+ * first (timestamp-prefixed names sort correctly), with each entry's mtime
+ * attached. Same basename in different subfolders ties break by
+ * vault-relative path descending. Missing or empty dirs yield `[]`.
+ *
+ * Ranking never reads mtime (filenames already sort correctly), so this
+ * stats only the paths a `limit` actually keeps, not the whole bucket.
  */
+export declare function listHandoffsDetailed(logsDir: string, options?: ListHandoffsOptions): Promise<HandoffEntry[]>;
+/** Same ranking as {@link listHandoffsDetailed}, paths only (no stat calls). */
 export declare function listHandoffs(logsDir: string, options?: ListHandoffsOptions): Promise<string[]>;
 //# sourceMappingURL=list-handoffs.d.ts.map

package/dist/vault/list-handoffs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-handoffs.d.ts","sourceRoot":"","sources":["../../src/vault/list-handoffs.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,MAAM,EAAE,CAAC,CAwBnB"}
+{"version":3,"file":"list-handoffs.d.ts","sourceRoot":"","sources":["../../src/vault/list-handoffs.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qEAAqE;AACrE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AA6BD;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,YAAY,EAAE,CAAC,CAMzB;AAED,gFAAgF;AAChF,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,MAAM,EAAE,CAAC,CAGnB"}

package/dist/vault/list-handoffs.js

@@ -1,14 +1,8 @@
+import { stat } from "node:fs/promises";
 import path from "node:path";
 import { vaultRelativePath } from "../util/path.js";
 import { listMarkdownFiles } from "./list-markdown.js";
-/**
- * Lists handoff markdown files under `logsDir` recursively, newest basename
- * first (timestamp-prefixed names sort correctly). Same basename in different
- * subfolders ties break by vault-relative path descending.
- * Returns absolute paths. Missing or empty dirs yield `[]`.
- */
-export async function listHandoffs(logsDir, options = {}) {
-    const mdPaths = await listMarkdownFiles(logsDir);
+function rankHandoffPaths(mdPaths, logsDir) {
     const ranked = mdPaths.map((filePath) => ({
         filePath,
         name: path.basename(filePath),
@@ -20,13 +14,34 @@ export async function listHandoffs(logsDir, options = {}) {
         }
         return a.rel < b.rel ? 1 : a.rel > b.rel ? -1 : 0;
     });
-    const paths = ranked.map((entry) => entry.filePath);
-    if (options.limit === undefined) {
-        return paths;
+    return ranked.map((entry) => entry.filePath);
+}
+function applyLimit(paths, limit) {
+    if (limit === undefined) {
+        return [...paths];
     }
-    if (options.limit <= 0) {
+    if (limit <= 0) {
         return [];
     }
-    return paths.slice(0, options.limit);
+    return paths.slice(0, limit);
+}
+/**
+ * Lists handoff markdown files under `logsDir` recursively, newest basename
+ * first (timestamp-prefixed names sort correctly), with each entry's mtime
+ * attached. Same basename in different subfolders ties break by
+ * vault-relative path descending. Missing or empty dirs yield `[]`.
+ *
+ * Ranking never reads mtime (filenames already sort correctly), so this
+ * stats only the paths a `limit` actually keeps, not the whole bucket.
+ */
+export async function listHandoffsDetailed(logsDir, options = {}) {
+    const mdPaths = await listMarkdownFiles(logsDir);
+    const paths = applyLimit(rankHandoffPaths(mdPaths, logsDir), options.limit);
+    return Promise.all(paths.map(async (filePath) => ({ path: filePath, mtimeMs: (await stat(filePath)).mtimeMs })));
+}
+/** Same ranking as {@link listHandoffsDetailed}, paths only (no stat calls). */
+export async function listHandoffs(logsDir, options = {}) {
+    const mdPaths = await listMarkdownFiles(logsDir);
+    return applyLimit(rankHandoffPaths(mdPaths, logsDir), options.limit);
 }
 //# sourceMappingURL=list-handoffs.js.map

package/dist/vault/list-handoffs.js.map

@@ -1 +1 @@
-{"version":3,"file":"list-handoffs.js","sourceRoot":"","sources":["../../src/vault/list-handoffs.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAOvD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAe,EACf,UAA+B,EAAE;IAEjC,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QACxC,QAAQ;QACR,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAC7B,GAAG,EAAE,iBAAiB,CAAC,OAAO,EAAE,QAAQ,CAAC;KAC1C,CAAC,CAAC,CAAC;IAEJ,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACnB,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;YACtB,OAAO,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAEpD,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC"}
+{"version":3,"file":"list-handoffs.js","sourceRoot":"","sources":["../../src/vault/list-handoffs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAavD,SAAS,gBAAgB,CAAC,OAA0B,EAAE,OAAe;IACnE,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QACxC,QAAQ;QACR,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAC7B,GAAG,EAAE,iBAAiB,CAAC,OAAO,EAAE,QAAQ,CAAC;KAC1C,CAAC,CAAC,CAAC;IAEJ,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACnB,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;YACtB,OAAO,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,UAAU,CAAC,KAAwB,EAAE,KAAyB;IACrE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;IACpB,CAAC;IACD,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACf,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAe,EACf,UAA+B,EAAE;IAEjC,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,UAAU,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC5E,OAAO,OAAO,CAAC,GAAG,CAChB,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAC7F,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAe,EACf,UAA+B,EAAE;IAEjC,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACjD,OAAO,UAAU,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;AACvE,CAAC"}

package/dist/vault/list-notes.d.ts

@@ -2,14 +2,23 @@ export interface ListNotesOptions {
     /** Max paths to return (newest first). Omit to return all. */
     limit?: number;
 }
+/** One note with the mtime already used to rank it (see {@link listNotesDetailed}). */
+export interface NoteEntry {
+    path: string;
+    mtimeMs: number;
+}
 /**
- * Lists note markdown files under `notesDir` recursively, newest mtime first.
- * Returns absolute paths. Missing or empty dirs yield `[]`.
- * Ties break by vault-relative path descending for stable output.
+ * Lists note markdown files under `notesDir` recursively, newest mtime first,
+ * with each entry's mtime attached — the same stat this module already does
+ * internally to rank notes, just not thrown away after sorting. Missing or
+ * empty dirs yield `[]`. Ties break by vault-relative path descending for
+ * stable output.
  *
  * Matches {@link listPlans} sorting for consistency across list commands
  * (filename-descending alone is viable for timestamp-prefixed notes, like
  * {@link listHandoffs}).
  */
+export declare function listNotesDetailed(notesDir: string, options?: ListNotesOptions): Promise<NoteEntry[]>;
+/** Same ranking as {@link listNotesDetailed}, paths only. */
 export declare function listNotes(notesDir: string, options?: ListNotesOptions): Promise<string[]>;
 //# sourceMappingURL=list-notes.d.ts.map

package/dist/vault/list-notes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-notes.d.ts","sourceRoot":"","sources":["../../src/vault/list-notes.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,MAAM,EAAE,CAAC,CAyBnB"}
+{"version":3,"file":"list-notes.d.ts","sourceRoot":"","sources":["../../src/vault/list-notes.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,uFAAuF;AACvF,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,SAAS,EAAE,CAAC,CAyBtB;AAED,6DAA6D;AAC7D,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,MAAM,EAAE,CAAC,CAEnB"}

package/dist/vault/list-notes.js

@@ -2,15 +2,17 @@ import { stat } from "node:fs/promises";
 import { vaultRelativePath } from "../util/path.js";
 import { listMarkdownFiles } from "./list-markdown.js";
 /**
- * Lists note markdown files under `notesDir` recursively, newest mtime first.
- * Returns absolute paths. Missing or empty dirs yield `[]`.
- * Ties break by vault-relative path descending for stable output.
+ * Lists note markdown files under `notesDir` recursively, newest mtime first,
+ * with each entry's mtime attached — the same stat this module already does
+ * internally to rank notes, just not thrown away after sorting. Missing or
+ * empty dirs yield `[]`. Ties break by vault-relative path descending for
+ * stable output.
  *
  * Matches {@link listPlans} sorting for consistency across list commands
  * (filename-descending alone is viable for timestamp-prefixed notes, like
  * {@link listHandoffs}).
  */
-export async function listNotes(notesDir, options = {}) {
+export async function listNotesDetailed(notesDir, options = {}) {
     const mdPaths = await listMarkdownFiles(notesDir);
     const withMtime = await Promise.all(mdPaths.map(async (filePath) => {
         const { mtimeMs } = await stat(filePath);
@@ -22,13 +24,17 @@ export async function listNotes(notesDir, options = {}) {
         }
         return a.rel < b.rel ? 1 : a.rel > b.rel ? -1 : 0;
     });
-    const paths = withMtime.map((entry) => entry.filePath);
+    const entries = withMtime.map((entry) => ({ path: entry.filePath, mtimeMs: entry.mtimeMs }));
     if (options.limit === undefined) {
-        return paths;
+        return entries;
     }
     if (options.limit <= 0) {
         return [];
     }
-    return paths.slice(0, options.limit);
+    return entries.slice(0, options.limit);
+}
+/** Same ranking as {@link listNotesDetailed}, paths only. */
+export async function listNotes(notesDir, options = {}) {
+    return (await listNotesDetailed(notesDir, options)).map((entry) => entry.path);
 }
 //# sourceMappingURL=list-notes.js.map

package/dist/vault/list-notes.js.map

@@ -1 +1 @@
-{"version":3,"file":"list-notes.js","sourceRoot":"","sources":["../../src/vault/list-notes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAOvD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,QAAgB,EAChB,UAA4B,EAAE;IAE9B,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,GAAG,CACjC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE;QAC7B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzC,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IAC3E,CAAC,CAAC,CACH,CAAC;IAEF,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACtB,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;YAC5B,OAAO,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;QAC/B,CAAC;QACD,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAEvD,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC"}
+{"version":3,"file":"list-notes.js","sourceRoot":"","sources":["../../src/vault/list-notes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAavD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAgB,EAChB,UAA4B,EAAE;IAE9B,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,GAAG,CACjC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE;QAC7B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzC,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IAC3E,CAAC,CAAC,CACH,CAAC;IAEF,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACtB,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;YAC5B,OAAO,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;QAC/B,CAAC;QACD,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAE7F,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AAED,6DAA6D;AAC7D,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,QAAgB,EAChB,UAA4B,EAAE;IAE9B,OAAO,CAAC,MAAM,iBAAiB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACjF,CAAC"}

package/dist/vault/list-plans.d.ts

@@ -2,10 +2,19 @@ export interface ListPlansOptions {
     /** Max paths to return (newest first). Omit to return all. */
     limit?: number;
 }
+/** One plan with the mtime already used to rank it (see {@link listPlansDetailed}). */
+export interface PlanEntry {
+    path: string;
+    mtimeMs: number;
+}
 /**
- * Lists plan markdown files under `plansDir` recursively, newest mtime first.
- * Returns absolute paths. Missing or empty dirs yield `[]`.
- * Ties break by vault-relative path descending for stable output.
+ * Lists plan markdown files under `plansDir` recursively, newest mtime first,
+ * with each entry's mtime attached — the same stat this module already does
+ * internally to rank plans, just not thrown away after sorting. Missing or
+ * empty dirs yield `[]`. Ties break by vault-relative path descending for
+ * stable output.
  */
+export declare function listPlansDetailed(plansDir: string, options?: ListPlansOptions): Promise<PlanEntry[]>;
+/** Same ranking as {@link listPlansDetailed}, paths only. */
 export declare function listPlans(plansDir: string, options?: ListPlansOptions): Promise<string[]>;
 //# sourceMappingURL=list-plans.d.ts.map

package/dist/vault/list-plans.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-plans.d.ts","sourceRoot":"","sources":["../../src/vault/list-plans.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,MAAM,EAAE,CAAC,CAyBnB"}
+{"version":3,"file":"list-plans.d.ts","sourceRoot":"","sources":["../../src/vault/list-plans.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,uFAAuF;AACvF,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,SAAS,EAAE,CAAC,CAyBtB;AAED,6DAA6D;AAC7D,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,MAAM,EAAE,CAAC,CAEnB"}

package/dist/vault/list-plans.js

@@ -2,11 +2,13 @@ import { stat } from "node:fs/promises";
 import { vaultRelativePath } from "../util/path.js";
 import { listMarkdownFiles } from "./list-markdown.js";
 /**
- * Lists plan markdown files under `plansDir` recursively, newest mtime first.
- * Returns absolute paths. Missing or empty dirs yield `[]`.
- * Ties break by vault-relative path descending for stable output.
+ * Lists plan markdown files under `plansDir` recursively, newest mtime first,
+ * with each entry's mtime attached — the same stat this module already does
+ * internally to rank plans, just not thrown away after sorting. Missing or
+ * empty dirs yield `[]`. Ties break by vault-relative path descending for
+ * stable output.
  */
-export async function listPlans(plansDir, options = {}) {
+export async function listPlansDetailed(plansDir, options = {}) {
     const mdPaths = await listMarkdownFiles(plansDir);
     const withMtime = await Promise.all(mdPaths.map(async (filePath) => {
         const { mtimeMs } = await stat(filePath);
@@ -18,13 +20,17 @@ export async function listPlans(plansDir, options = {}) {
         }
         return a.rel < b.rel ? 1 : a.rel > b.rel ? -1 : 0;
     });
-    const paths = withMtime.map((entry) => entry.filePath);
+    const entries = withMtime.map((entry) => ({ path: entry.filePath, mtimeMs: entry.mtimeMs }));
     if (options.limit === undefined) {
-        return paths;
+        return entries;
     }
     if (options.limit <= 0) {
         return [];
     }
-    return paths.slice(0, options.limit);
+    return entries.slice(0, options.limit);
+}
+/** Same ranking as {@link listPlansDetailed}, paths only. */
+export async function listPlans(plansDir, options = {}) {
+    return (await listPlansDetailed(plansDir, options)).map((entry) => entry.path);
 }
 //# sourceMappingURL=list-plans.js.map

package/dist/vault/list-plans.js.map

@@ -1 +1 @@
-{"version":3,"file":"list-plans.js","sourceRoot":"","sources":["../../src/vault/list-plans.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAOvD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,QAAgB,EAChB,UAA4B,EAAE;IAE9B,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,GAAG,CACjC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE;QAC7B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzC,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IAC3E,CAAC,CAAC,CACH,CAAC;IAEF,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACtB,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;YAC5B,OAAO,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;QAC/B,CAAC;QACD,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAEvD,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;AACvC,CAAC"}
+{"version":3,"file":"list-plans.js","sourceRoot":"","sources":["../../src/vault/list-plans.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAavD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAgB,EAChB,UAA4B,EAAE;IAE9B,MAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,GAAG,CACjC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE;QAC7B,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzC,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IAC3E,CAAC,CAAC,CACH,CAAC;IAEF,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACtB,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;YAC5B,OAAO,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;QAC/B,CAAC;QACD,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAE7F,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AAED,6DAA6D;AAC7D,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,QAAgB,EAChB,UAA4B,EAAE;IAE9B,OAAO,CAAC,MAAM,iBAAiB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACjF,CAAC"}

package/dist/vault/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/vault/search.ts"],"names":[],"mappings":"AAKA,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,kEAAkE;IAClE,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,KAAK,CAAC,EAAE,IAAI,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;CACpB;AAuOD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAqJhF"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/vault/search.ts"],"names":[],"mappings":"AAKA,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,kEAAkE;IAClE,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,KAAK,CAAC,EAAE,IAAI,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;CACpB;AAsUD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CA8LhF"}

package/dist/vault/search.js

@@ -80,15 +80,27 @@ function searchMetaPenalty(rootDir, filePath, query) {
     }
     return 0;
 }
-function termMatchesLine(line, term) {
-    if (term.includes(" ")) {
+// Deliberately separate from termMatchesHaystack's dot-aware boundary below —
+// body content has no dotted-pseudo-extension convention to guard against, so
+// plain `\b` is correct here. Do not "unify" the two matchers: a shared regex
+// would either reintroduce `plan` matching `<id>.plan.md` in filenames, or
+// stop `.plan` matching `plan` in body text, silently changing one side.
+/** One compiled matcher per term, built once per search so the per-line scan never recompiles a RegExp. */
+function buildTermMatchers(terms) {
+    const matchers = new Map();
+    for (const term of terms) {
+        matchers.set(term, term.includes(" ") ? null : new RegExp(`\\b${escapeRegex(term)}\\b`, "i"));
+    }
+    return matchers;
+}
+function termMatchesLine(line, term, matcher) {
+    if (matcher === null) {
         return line.toLowerCase().includes(term.toLowerCase());
     }
-    const re = new RegExp(`\\b${escapeRegex(term)}\\b`, "i");
-    return re.test(line);
+    return matcher.test(line);
 }
-function matchingTermsOnLine(line, terms) {
-    return terms.filter((term) => termMatchesLine(line, term));
+function matchingTermsOnLine(line, terms, matchers) {
+    return terms.filter((term) => termMatchesLine(line, term, matchers.get(term) ?? null));
 }
 function longestTerm(matches) {
     return matches.reduce((best, term) => (term.length > best.length ? term : best));
@@ -120,24 +132,79 @@ function buildSnippet(lines, lineIndex, context) {
     }
     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;
+/**
+ * `.` only counts as a word character on the *leading* side of a match
+ * (unlike `\b`'s default), so a term can't start right after a dot — this
+ * stops a dotted filename convention like `<id>.plan.md` from letting a
+ * generic term match its dotted suffix as a standalone word (query "plan"
+ * must not match every `*.plan.md` file), while still letting the id itself
+ * match (`schema_versioning` must match `schema_versioning.plan.md`) since a
+ * term is still allowed to *end* right before a dot. `\w`-based boundaries
+ * are otherwise unchanged from before this fix: a hyphen still splits words
+ * (`search` matches `search-feature.md`), but `_` does not (`search` does
+ * *not* match `search_feature.md` — same as `\b`'s existing behavior).
+ */
+function termMatchesHaystack(haystack, lower, matcher) {
+    if (matcher === null) {
+        return haystack.includes(lower);
+    }
+    return matcher.test(haystack);
+}
+/** One compiled matcher per lowercased term, built once per search — same rationale as {@link buildTermMatchers}. */
+function buildHaystackMatchers(terms) {
+    const matchers = new Map();
     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++;
+        matchers.set(lower, lower.includes(" ") ? null : new RegExp(`(?<![\\w.])${escapeRegex(lower)}(?!\\w)`, "i"));
+    }
+    return matchers;
+}
+/**
+ * Lowercased `terms` that appear in `filePath`'s vault-relative path,
+ * including parent directory names (e.g. `plans/p1.md` matches both `plans`
+ * and `p1`). Ranking signal only (`filenameTermCount`) — never a matching
+ * gate, since a query for a common folder name (`plans`, `notes`, `archive`)
+ * would otherwise return every file in that folder regardless of content.
+ */
+/** Shared by {@link pathMatchedTerms} and {@link stemMatchedTerms} — only the haystack differs between the two. */
+function matchTermsAgainstHaystack(haystack, terms, haystackMatchers) {
+    const matched = new Set();
+    for (const term of terms) {
+        const lower = term.toLowerCase();
+        if (termMatchesHaystack(haystack, lower, haystackMatchers.get(lower) ?? null)) {
+            matched.add(lower);
         }
     }
-    return count;
+    return matched;
+}
+function pathMatchedTerms(rootDir, filePath, terms, haystackMatchers) {
+    const rel = path.relative(rootDir, filePath);
+    const haystack = rel.replace(/[/\\]/g, " ").replace(/\.md$/i, "").toLowerCase();
+    return matchTermsAgainstHaystack(haystack, terms, haystackMatchers);
+}
+/**
+ * Lowercased `terms` that appear in `filePath`'s own filename stem only (no
+ * parent directories, no extension) — e.g. `plans/pluggable.md` matches
+ * `pluggable` but not `plans`. Narrow enough to gate inclusion for a file
+ * with no content match, unlike {@link pathMatchedTerms}.
+ */
+/**
+ * Strips a leading vault timestamp prefix (`YYYY-MM-DD-HHmm[ss]`, see
+ * `dateSecondPrefix`/`dateMinutePrefix` in `timestamp-slug.ts`) so a bare
+ * date/time query doesn't stem-match every handoff/log filename — hyphens
+ * alone don't stop it, since each numeric segment still matches standalone
+ * as a "word" via termMatchesHaystack's boundary check. Strips to empty for
+ * a slug-less date-only stem, same as any other narrow-to-nothing case.
+ */
+function stripTimestampPrefix(stem) {
+    // `_` terminates too, not just `-`/end — a slug-less collision-suffixed
+    // stem (`writeUniqueMarkdown`'s `_02`, `_03`, …) attaches directly to the
+    // date with no separating hyphen.
+    return stem.replace(/^\d{4}-\d{2}-\d{2}-\d{4,6}(-|_|$)/, "");
+}
+function stemMatchedTerms(filePath, terms, haystackMatchers) {
+    const stem = stripTimestampPrefix(path.basename(filePath, path.extname(filePath)).toLowerCase());
+    return matchTermsAgainstHaystack(stem, terms, haystackMatchers);
 }
 function contentHasPhrase(content, query) {
     const trimmed = query.trim();
@@ -213,6 +280,8 @@ export async function searchVault(options) {
         };
     }
     const filePaths = await listMarkdownFiles(options.rootDir);
+    const termMatchers = buildTermMatchers(terms);
+    const haystackMatchers = buildHaystackMatchers(terms);
     const rawFiles = [];
     let totalMatchCount = 0;
     // Lowercased doc-freq for ranking; JSON output remaps to original `terms` spelling.
@@ -238,7 +307,7 @@ export async function searchVault(options) {
         let totalHitCount = 0;
         for (let i = 0; i < lines.length; i++) {
             const line = lines[i] ?? "";
-            const lineMatches = matchingTermsOnLine(line, terms);
+            const lineMatches = matchingTermsOnLine(line, terms, termMatchers);
             if (lineMatches.length === 0) {
                 continue;
             }
@@ -257,7 +326,37 @@ export async function searchVault(options) {
                 });
             }
         }
-        if (matchedTerms.size > 0) {
+        // Path terms (dir segments + stem) stay a ranking-only signal — they must
+        // never gate inclusion, or a query for a common folder name (`plans`,
+        // `notes`, `archive`) would return every file in that folder regardless
+        // of content. The *matcher* underneath did change (shares
+        // termMatchesHaystack's dot-boundary fix with stem matching below), so a
+        // content-matching `<id>.plan.md` no longer earns filenameTermCount for
+        // its dotted suffix — only the gating behavior is unchanged, not the
+        // matcher itself.
+        const pathTerms = pathMatchedTerms(options.rootDir, filePath, terms, haystackMatchers);
+        // Stem terms are narrow enough (the file's own name, not its folder) to
+        // justify surfacing a file that has no content match at all — e.g.
+        // `pluggable.md`, whose body never repeats the word "pluggable".
+        const stemTerms = stemMatchedTerms(filePath, terms, haystackMatchers);
+        if (matchedTerms.size === 0 && stemTerms.size > 0) {
+            // Every other zero-hit check in the CLI and its consumers (summary
+            // text, JSON, the extension's QuickPick) keys off `totalMatchCount`,
+            // not file count — count the title match itself so a filename-only
+            // result doesn't get reported as "no matches" while still returning a hit.
+            totalMatchCount++;
+        }
+        if (matchedTerms.size > 0 || stemTerms.size > 0) {
+            for (const t of stemTerms) {
+                // Only stem terms feed doc-freq (not the wider path terms): a term
+                // that only ever appears in a title should still show a nonzero
+                // `termHitCounts`, so the skill's zero-hit "bad term" broaden check
+                // doesn't misfire on it — but a common folder name shouldn't inflate
+                // every other term's IDF weighting.
+                if (!matchedTerms.has(t)) {
+                    termDocFreq[t] = (termDocFreq[t] ?? 0) + 1;
+                }
+            }
             for (const t of matchedTerms) {
                 termDocFreq[t] = (termDocFreq[t] ?? 0) + 1;
             }
@@ -266,10 +365,15 @@ export async function searchVault(options) {
                 mtimeMs,
                 topicsMatch,
                 hits: fileHits,
+                // Content-only: a filename/stem match justifies inclusion (above)
+                // and still earns the flat `filenameTermCount` rank bonus below, but
+                // doesn't inflate distinct-term coverage — a file that only matches
+                // by title shouldn't outrank one that actually discusses the topic.
                 distinctTermCount: matchedTerms.size,
                 totalHitCount,
                 idfDensity: 0,
-                filenameTermCount: countFilenameTermMatches(options.rootDir, filePath, terms),
+                filenameTermCount: pathTerms.size,
+                stemMatchedTerms: stemTerms,
                 phraseMatch: contentHasPhrase(content, options.query),
                 partialPhraseMatch: contentHasPartialPhrase(content, options.query),
                 perTermHits,
@@ -312,7 +416,7 @@ export async function searchVault(options) {
         topicsMatch: file.topicsMatch,
         hits: pickBestHits(file.hits, maxHitsPerFile),
         matchedTerms: terms
-            .filter((term) => file.perTermHits.has(term.toLowerCase()))
+            .filter((term) => file.perTermHits.has(term.toLowerCase()) || file.stemMatchedTerms.has(term.toLowerCase()))
             .sort((a, b) => b.length - a.length),
     }));
     return {