grounder 0.4.0 → 0.5.0

package/dist/help.js

@@ -1,8 +1,8 @@
 /** Help tiers and command metadata for the grounder CLI. */
-const GROUP_ORDER = ["Setup", "Write", "Paths", "Maintain", "Advanced"];
+const GROUP_ORDER = ["Setup", "Write", "Retrieve", "Paths", "Maintain", "Advanced"];
 const QUICKSTART = `Quickstart:
-  grounder vault init <path-to-your-vault>
-  grounder init
+  grounder setup <path-to-your-vault>
+  grounder link
   grounder note "my first note"
   grounder handoff $'# Handoff\\n\\n## Next\\n1. …'
   grounder handoff list
@@ -14,109 +14,127 @@ const QUICKSTART = `Quickstart:
  */
 export const COMMANDS = [
     {
-        id: "vault",
+        id: "setup",
         group: "Setup",
-        summary: "Vault setup commands",
-        listUsage: "vault init <path>",
-        usage: "grounder vault init <path> [--yes] [--force] [--agent <id>] [--hooks]",
-        list: false,
-        flags: `Subcommands:
-  vault init   Initialize vault + home config (once per machine)`,
-    },
-    {
-        id: "vault init",
-        group: "Setup",
-        summary: "Initialize vault + home config (once per machine)",
-        listUsage: "vault init <path>",
-        usage: "grounder vault init <path> [--yes] [--force] [--agent <id>] [--hooks]",
+        summary: "Connect to a markdown vault (once per machine)",
+        listUsage: "setup <path>",
+        usage: "grounder setup <path> [--yes] [--force] [--agent <id>] [--hooks] [--dry-run]",
         flags: `Flags:
   --yes          Skip confirmation prompts
   --force        Overwrite existing home config / generated files
   --agent <id>   Install for a specific agent (repeatable; default: auto-detect)
                  Supported: cursor, claude
-  --hooks        Also install session-start teaser hooks`,
+  --hooks        Also install session-start teaser hooks
+  --dry-run      Preview without writing`,
     },
     {
-        id: "init",
+        id: "link",
         group: "Setup",
-        summary: "Connect the current repo to your vault",
-        listUsage: "init",
-        usage: "grounder init [--yes] [--force] [--id <id>] [--vault <path>]",
+        summary: "Link this project inside the markdown vault (once per project)",
+        listUsage: "link",
+        usage: "grounder link [--yes] [--force] [--id <id>] [--vault <path>] [--dry-run]",
         flags: `Flags:
   --yes          Skip confirmation prompts
   --force        Overwrite an existing link marker
   --id <id>      Override detected project id
-  --vault <path> Override home vault root for this run`,
+  --vault <path> Override home vault root for this run
+  --dry-run      Preview without writing`,
     },
     {
         id: "note",
         group: "Write",
         summary: "Write a note to the vault",
         listUsage: "note <text>",
-        usage: "grounder note <text> [--title <slug>]",
+        usage: "grounder note <text> [--title <slug>] [--topics <list>]",
         flags: `Flags:
-  --title <slug> Short slug in filename (default: slugified first line)
+  --title <slug>  Short slug in filename (default: slugified first line)
+  --topics <list> Comma-separated keywords for search (e.g. "auth,jwt,session")
 
 Subcommands:
-  note list   Print recent notes (count header + numbered title/path, newest first)`,
+  note list   Print recent notes under notes/** (bucket-relative titles, newest first)`,
     },
     {
         id: "note list",
         group: "Write",
-        summary: "Print recent notes (count header + numbered title/path, newest first)",
+        summary: "Print recent notes under notes/** (bucket-relative titles, newest first)",
         listUsage: "note list",
-        usage: "grounder note list [--limit <n>]",
+        usage: "grounder note list [--limit <n>] [--markdown]",
         flags: `Flags:
-  --limit <n>  Max notes to print (default: 5)`,
+  --limit <n>  Max notes to print (default: 5)
+  --markdown   Agent relay: [bucketRelativePath](fileUri) title lines
+               (lists notes/**; nested e.g. feature/name.md)`,
     },
     {
         id: "handoff",
         group: "Write",
         summary: "Write a session handoff to vault logs/",
         listUsage: "handoff <text>",
-        usage: "grounder handoff <text> [--title <slug>]",
+        usage: "grounder handoff <text> [--title <slug>] [--topics <list>]",
         flags: `Flags:
-  --title <slug> Short slug in filename (default: slugified first line)
+  --title <slug>  Short slug in filename (default: slugified first line)
+  --topics <list> Comma-separated keywords for search (e.g. "auth,jwt,session")
 
 Subcommands:
-  handoff list   Print recent handoffs (count header + numbered title/path, newest first)
+  handoff list   Print recent handoffs under logs/** (bucket-relative titles, newest first)
   handoff peek   One-line latest-handoff teaser (session hooks)`,
     },
     {
         id: "handoff list",
         group: "Write",
-        summary: "Print recent handoffs (count header + numbered title/path, newest first)",
+        summary: "Print recent handoffs under logs/** (bucket-relative titles, newest first)",
         listUsage: "handoff list",
-        usage: "grounder handoff list [--limit <n>] [--head]",
+        usage: "grounder handoff list [--limit <n>] [--head] [--markdown]",
         flags: `Flags:
   --limit <n>  Max handoffs to print (default: 5)
   --head       Print only the newest usable path
-               (skips empty/unreadable files; same pick as handoff peek)`,
+               (skips empty/unreadable files; same pick as handoff peek)
+  --markdown   Agent relay: [bucketRelativePath](fileUri) title lines
+               (lists logs/**; nested e.g. feature/name.md; not with --head)`,
     },
     {
         id: "plan",
         group: "Write",
         summary: "Write/update a named plan under vault plans/",
         listUsage: "plan <text>",
-        usage: "grounder plan <text> (--title <name> [--force] | --path <file>)",
+        usage: "grounder plan <text> (--title <name> [--force] | --path <file>) [--topics <list>]",
         flags: `Flags:
-  --title <name> Required filename stem when creating/updating by name
-                 (trailing .md ok; sanitized, max 80 chars)
-  --path <file>  Update an existing plan by path (must resolve under this
-                 project's plans/; no title sanitization; always overwrites)
-  --force        With --title: overwrite an existing plan (preserves created)
+  --title <name>  Required filename stem when creating/updating by name
+                  (trailing .md ok; sanitized, max 80 chars)
+  --path <file>   Update an existing plan by path (must resolve under this
+                  project's plans/; no title sanitization; always overwrites)
+  --force         With --title: overwrite an existing plan (preserves created)
+  --topics <list> Comma-separated keywords for search (e.g. "caching,redis,api").
+                  On update, omit to keep existing topics.
 
 Subcommands:
-  plan list   Print recent plans (count header + numbered title/path, newest first)`,
+  plan list   Print recent plans under plans/** (bucket-relative titles, newest first)`,
     },
     {
         id: "plan list",
         group: "Write",
-        summary: "Print recent plans (count header + numbered title/path, newest first)",
+        summary: "Print recent plans under plans/** (bucket-relative titles, newest first)",
         listUsage: "plan list",
-        usage: "grounder plan list [--limit <n>]",
+        usage: "grounder plan list [--limit <n>] [--markdown]",
+        flags: `Flags:
+  --limit <n>  Max plans to print (default: 5)
+  --markdown   Agent relay: [bucketRelativePath](fileUri) title lines
+               (lists plans/**; nested e.g. migration/cutover.md)`,
+    },
+    {
+        id: "search",
+        group: "Retrieve",
+        summary: "Search linked project vault for keywords (scoped retrieval)",
+        listUsage: "search <query>",
+        usage: "grounder search <query> [--terms <csv>] [--limit <n>] [--max-hits <n>] [--context <n>] [--since <date>] [--markdown] [--json]",
         flags: `Flags:
-  --limit <n>  Max plans to print (default: 5)`,
+  --terms <csv>   Extra keyword variants (comma-separated)
+  --limit <n>     Max files to print (default: 10)
+  --max-hits <n>  Max stored line snippets per file during scan (default: 50)
+  --context <n>   Context lines around each snippet (default: 1)
+  --since <date>  Only files modified on or after date (YYYY-MM-DD local midnight, or Nd, e.g. 7d)
+  --after <date>  Alias for --since
+  --markdown      Agent relay: file:// links + fenced snippets
+  --json          Structured output (relativePath, fileUri, alsoMatchedHint per hit)`,
     },
     {
         id: "path notes",
@@ -204,7 +222,7 @@ Examples:
   grounder help
   grounder help note
   grounder help handoff list
-  grounder help vault init`,
+  grounder help setup`,
     },
 ];
 /**
@@ -212,9 +230,8 @@ Examples:
  * `cli.ts` / `helpExitCode(...)` call sites — the invariant test locks this.
  */
 export const DISPATCHED_COMMAND_IDS = [
-    "vault",
-    "vault init",
-    "init",
+    "setup",
+    "link",
     "note",
     "note list",
     "handoff",
@@ -222,6 +239,7 @@ export const DISPATCHED_COMMAND_IDS = [
     "handoff peek",
     "plan",
     "plan list",
+    "search",
     "path",
     "path notes",
     "path logs",
@@ -316,9 +334,10 @@ function formatFullCommandDetails() {
     }
     return blocks.join("\n\n");
 }
+const BANNER = "grounder — markdown-native memory for AI agents";
 /** Bare `grounder` / `-h` — short grouped synopsis (no flag encyclopedia). */
 export function printSynopsis() {
-    process.stdout.write(`grounder — connect git projects to Obsidian dev vaults for AI agents
+    process.stdout.write(`${BANNER}
 
 ${formatGroupedLists()}
 
@@ -335,7 +354,7 @@ ${QUICKSTART}
 }
 /** `--help` / `grounder help` with no args — one-shot reference for humans/agents. */
 export function printFullHelp() {
-    process.stdout.write(`grounder — connect git projects to Obsidian dev vaults for AI agents
+    process.stdout.write(`${BANNER}
 
 ${formatGroupedLists()}
 

package/dist/help.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAoB5D,MAAM,WAAW,GAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;AAErF,MAAM,UAAU,GAAG;;;;;;;qBAOE,CAAC;AAEtB;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAA2B;IAC9C;QACE,EAAE,EAAE,OAAO;QACX,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,sBAAsB;QAC/B,SAAS,EAAE,mBAAmB;QAC9B,KAAK,EAAE,uEAAuE;QAC9E,IAAI,EAAE,KAAK;QACX,KAAK,EAAE;iEACsD;KAC9D;IACD;QACE,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,mDAAmD;QAC5D,SAAS,EAAE,mBAAmB;QAC9B,KAAK,EAAE,uEAAuE;QAC9E,KAAK,EAAE;;;;;yDAK8C;KACtD;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,wCAAwC;QACjD,SAAS,EAAE,MAAM;QACjB,KAAK,EAAE,8DAA8D;QACrE,KAAK,EAAE;;;;uDAI4C;KACpD;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,2BAA2B;QACpC,SAAS,EAAE,aAAa;QACxB,KAAK,EAAE,uCAAuC;QAC9C,KAAK,EAAE;;;;oFAIyE;KACjF;IACD;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,uEAAuE;QAChF,SAAS,EAAE,WAAW;QACtB,KAAK,EAAE,kCAAkC;QACzC,KAAK,EAAE;+CACoC;KAC5C;IACD;QACE,EAAE,EAAE,SAAS;QACb,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,wCAAwC;QACjD,SAAS,EAAE,gBAAgB;QAC3B,KAAK,EAAE,0CAA0C;QACjD,KAAK,EAAE;;;;;gEAKqD;KAC7D;IACD;QACE,EAAE,EAAE,cAAc;QAClB,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,0EAA0E;QACnF,SAAS,EAAE,cAAc;QACzB,KAAK,EAAE,8CAA8C;QACrD,KAAK,EAAE;;;yEAG8D;KACtE;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,8CAA8C;QACvD,SAAS,EAAE,aAAa;QACxB,KAAK,EAAE,iEAAiE;QACxE,KAAK,EAAE;;;;;;;;oFAQyE;KACjF;IACD;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,uEAAuE;QAChF,SAAS,EAAE,WAAW;QACtB,KAAK,EAAE,kCAAkC;QACzC,KAAK,EAAE;+CACoC;KAC5C;IACD;QACE,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,gCAAgC;QACzC,SAAS,EAAE,YAAY;QACvB,KAAK,EAAE,qBAAqB;KAC7B;IACD;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,+BAA+B;QACxC,SAAS,EAAE,WAAW;QACtB,KAAK,EAAE,oBAAoB;KAC5B;IACD;QACE,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,gCAAgC;QACzC,SAAS,EAAE,YAAY;QACvB,KAAK,EAAE,qBAAqB;KAC7B;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,yDAAyD;QAClE,SAAS,EAAE,yBAAyB;QACpC,KAAK,EAAE,kCAAkC;QACzC,IAAI,EAAE,KAAK;QACX,KAAK,EAAE;;;8CAGmC;KAC3C;IACD;QACE,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,UAAU;QACjB,OAAO,EAAE,qDAAqD;QAC9D,SAAS,EAAE,QAAQ;QACnB,KAAK,EAAE,iBAAiB;KACzB;IACD;QACE,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,UAAU;QACjB,OAAO,EAAE,8BAA8B;QACvC,SAAS,EAAE,QAAQ;QACnB,KAAK,EAAE,4BAA4B;QACnC,KAAK,EAAE;2DACgD;KACxD;IACD;QACE,EAAE,EAAE,SAAS;QACb,KAAK,EAAE,UAAU;QACjB,OAAO,EAAE,gDAAgD;QACzD,SAAS,EAAE,SAAS;QACpB,KAAK,EAAE,iEAAiE;QACxE,KAAK,EAAE;;;;;8DAKmD;KAC3D;IACD;QACE,EAAE,EAAE,cAAc;QAClB,KAAK,EAAE,UAAU;QACjB,OAAO,EAAE,wDAAwD;QACjE,SAAS,EAAE,cAAc;QACzB,KAAK,EAAE,gCAAgC;QACvC,KAAK,EAAE;;yCAE8B;KACtC;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,UAAU;QACjB,OAAO,EAAE,0CAA0C;QACnD,SAAS,EAAE,kBAAkB;QAC7B,KAAK,EAAE,2BAA2B;QAClC,IAAI,EAAE,KAAK;QACX,KAAK,EAAE;;;;;;;2BAOgB;KACxB;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,OAAO;IACP,YAAY;IACZ,MAAM;IACN,MAAM;IACN,WAAW;IACX,SAAS;IACT,cAAc;IACd,cAAc;IACd,MAAM;IACN,WAAW;IACX,MAAM;IACN,YAAY;IACZ,WAAW;IACX,YAAY;IACZ,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,MAAM;CACE,CAAC;AAEX,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAErD,+DAA+D;AAC/D,MAAM,UAAU,SAAS,CAAC,IAAc;IACtC,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,QAAQ,CAAC,CAAC;AAC9D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAkB;IACnD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,KAAK,IAAI,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC;QAChD,MAAM,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1B,IAAI,IAAI,EAAE,CAAC;YACT,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAiB;IAChD,IAAI,GAAG,GAAG,UAAU,IAAI,CAAC,KAAK,IAAI,CAAC;IACnC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,GAAG,IAAI,KAAK,IAAI,CAAC,OAAO,IAAI,CAAC;IAC/B,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,GAAG,IAAI,KAAK,IAAI,CAAC,KAAK,IAAI,CAAC;IAC7B,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,EAAU;IAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC1B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,gBAAgB,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,YAAY,CAAC,IAAc,EAAE,SAAiB;IAC5D,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,cAAc;IACrB,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,kBAAkB;IACzB,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IACjE,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;QACrD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,SAAS;QACX,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAC9E,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,mBAAmB,CAAC,CAAc;IACzC,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,YAAY,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IACjD,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;QACZ,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,wBAAwB;IAC/B,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;QACrD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,SAAS;QACX,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,KAAK,IAAI,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC7B,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,aAAa;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;;EAErB,kBAAkB,EAAE;;;;;;;;;;EAUpB,UAAU;CACX,CAAC,CAAC;AACH,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,aAAa;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;;EAErB,kBAAkB,EAAE;;;;;;;;EAQpB,wBAAwB,EAAE;;EAE1B,UAAU;CACX,CAAC,CAAC;AACH,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,OAAO,CAAC,IAAc;IACpC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,aAAa,EAAE,CAAC;QAChB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,IAAI,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACxE,OAAO,CAAC,CAAC;IACX,CAAC;IAED,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACvB,OAAO,CAAC,CAAC;AACX,CAAC"}
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"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"}

package/dist/util/frontmatter.d.ts

@@ -1,11 +1,13 @@
+export interface ParsedFrontmatter {
+    title?: string;
+    created?: string;
+    topics?: string[];
+}
 /**
- * Parse `title` / `created` from Grounder handoff frontmatter.
- * Accepts the quoted `key: "value"` shape {@link writeHandoff} writes today, and
- * unquoted `key: value` from earlier handoffs. Not a general YAML parser.
+ * Parse `title` / `created` / `topics` from Grounder frontmatter.
+ * Accepts the quoted `key: "value"` shape write commands produce, and
+ * unquoted `key: value` from earlier files. Not a general YAML parser.
  * Returns `{}` on anything unexpected; never throws.
  */
-export declare function parseHandoffFrontmatter(content: string): {
-    title?: string;
-    created?: string;
-};
+export declare function parseHandoffFrontmatter(content: string): ParsedFrontmatter;
 //# sourceMappingURL=frontmatter.d.ts.map

package/dist/util/frontmatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/util/frontmatter.ts"],"names":[],"mappings":"AA6BA;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAqC7F"}
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/util/frontmatter.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAoBD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CA2C1E"}

package/dist/util/frontmatter.js

@@ -27,9 +27,28 @@ function unescapeYamlDoubleQuoted(value) {
     return result;
 }
 /**
- * Parse `title` / `created` from Grounder handoff frontmatter.
- * Accepts the quoted `key: "value"` shape {@link writeHandoff} writes today, and
- * unquoted `key: value` from earlier handoffs. Not a general YAML parser.
+ * Parse a YAML flow sequence like `["a", "b"]` or `[a, b]` into a string array.
+ * Returns `undefined` on anything unexpected.
+ */
+function parseYamlFlowSequence(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith("[") || !trimmed.endsWith("]"))
+        return undefined;
+    const inner = trimmed.slice(1, -1);
+    if (!inner.trim())
+        return [];
+    return inner.split(",").map((item) => {
+        const s = item.trim();
+        if (s.startsWith('"') && s.endsWith('"')) {
+            return unescapeYamlDoubleQuoted(s.slice(1, -1));
+        }
+        return s;
+    });
+}
+/**
+ * Parse `title` / `created` / `topics` from Grounder frontmatter.
+ * Accepts the quoted `key: "value"` shape write commands produce, and
+ * unquoted `key: value` from earlier files. Not a general YAML parser.
  * Returns `{}` on anything unexpected; never throws.
  */
 export function parseHandoffFrontmatter(content) {
@@ -44,13 +63,19 @@ export function parseHandoffFrontmatter(content) {
             if (line === "---") {
                 break;
             }
+            const topicsMatch = /^topics:\s*(\[.*\])\s*$/.exec(line);
+            if (topicsMatch) {
+                const parsed = parseYamlFlowSequence(topicsMatch[1] ?? "");
+                if (parsed)
+                    result.topics = parsed;
+                continue;
+            }
             const quoted = /^(title|created):\s*"(.*)"\s*$/.exec(line);
             if (quoted) {
                 const key = quoted[1];
                 result[key] = unescapeYamlDoubleQuoted(quoted[2] ?? "");
                 continue;
             }
-            // Opening quote without a closing pair — ignore rather than treat as unquoted.
             if (/^(title|created):\s*"/.test(line)) {
                 continue;
             }

package/dist/util/frontmatter.js.map

@@ -1 +1 @@
-{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/util/frontmatter.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,SAAS,wBAAwB,CAAC,KAAa;IAC7C,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YAC9C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC1B,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;gBAClC,MAAM,IAAI,IAAI,CAAC;gBACf,CAAC,EAAE,CAAC;gBACJ,SAAS;YACX,CAAC;YACD,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;gBACjB,MAAM,IAAI,IAAI,CAAC;gBACf,CAAC,EAAE,CAAC;gBACJ,SAAS;YACX,CAAC;YACD,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;gBACjB,MAAM,IAAI,IAAI,CAAC;gBACf,CAAC,EAAE,CAAC;gBACJ,SAAS;YACX,CAAC;QACH,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC;YACvB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,MAAM,GAAyC,EAAE,CAAC;QACxD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAC5B,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;gBACnB,MAAM;YACR,CAAC;YAED,MAAM,MAAM,GAAG,gCAAgC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3D,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAwB,CAAC;gBAC7C,MAAM,CAAC,GAAG,CAAC,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;gBACxD,SAAS;YACX,CAAC;YAED,+EAA+E;YAC/E,IAAI,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBACvC,SAAS;YACX,CAAC;YAED,MAAM,QAAQ,GAAG,+BAA+B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC5D,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAwB,CAAC;gBAC/C,MAAM,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAClC,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/util/frontmatter.ts"],"names":[],"mappings":"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"}

package/dist/util/path.d.ts

@@ -17,4 +17,27 @@ export declare function isPathInside(parent: string, child: string): boolean;
  * Returns `null` if either path cannot be resolved (e.g. missing).
  */
 export declare function isRealPathInside(parent: string, child: string): Promise<boolean | null>;
+/** `file://` href for an absolute filesystem path (spaces percent-encoded). */
+export declare function toFileUri(filePath: string): string;
+/**
+ * Escape text for a Markdown link label (`[label](...)`) so `\`, `[`, and `]`
+ * do not break the link syntax.
+ */
+export declare function escapeMarkdownLinkLabel(text: string): string;
+/**
+ * `[label](fileUri)` for an absolute path. Escapes special chars in the label;
+ * percent-encodes `(` / `)` in the URI so they do not close the destination.
+ */
+export declare function formatMarkdownFileLink(label: string, filePath: string): string;
+/**
+ * Path relative to a vault/project root, always with `/` separators
+ * (stable for markdown links and JSON across platforms).
+ */
+export declare function vaultRelativePath(rootDir: string, filePath: string): string;
+/**
+ * Plain list title: path relative to `rootDir` with a trailing `.md` stripped
+ * (e.g. `migration/phase-1`). Falls back to the filename stem when `rootDir`
+ * is omitted.
+ */
+export declare function vaultItemPlainTitle(filePath: string, rootDir?: string): string;
 //# sourceMappingURL=path.d.ts.map

package/dist/util/path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/util/path.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,GAAG,MAAM,CAElF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAanE;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAQ7F"}
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/util/path.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,GAAG,MAAM,CAElF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAanE;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAQ7F;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG9E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAM9E"}

package/dist/util/path.js

@@ -1,6 +1,7 @@
 import { realpath } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 /**
  * Expand a leading `~` / `~/…` to the user home directory.
  * Leaves other paths unchanged (including a mid-path `~`, which is not home).
@@ -50,4 +51,42 @@ export async function isRealPathInside(parent, child) {
         return null;
     }
 }
+/** `file://` href for an absolute filesystem path (spaces percent-encoded). */
+export function toFileUri(filePath) {
+    return pathToFileURL(filePath).href;
+}
+/**
+ * Escape text for a Markdown link label (`[label](...)`) so `\`, `[`, and `]`
+ * do not break the link syntax.
+ */
+export function escapeMarkdownLinkLabel(text) {
+    return text.replace(/\\/g, "\\\\").replace(/\[/g, "\\[").replace(/\]/g, "\\]");
+}
+/**
+ * `[label](fileUri)` for an absolute path. Escapes special chars in the label;
+ * percent-encodes `(` / `)` in the URI so they do not close the destination.
+ */
+export function formatMarkdownFileLink(label, filePath) {
+    const uri = toFileUri(filePath).replace(/\(/g, "%28").replace(/\)/g, "%29");
+    return `[${escapeMarkdownLinkLabel(label)}](${uri})`;
+}
+/**
+ * Path relative to a vault/project root, always with `/` separators
+ * (stable for markdown links and JSON across platforms).
+ */
+export function vaultRelativePath(rootDir, filePath) {
+    return path.relative(rootDir, filePath).split(path.sep).join("/");
+}
+/**
+ * Plain list title: path relative to `rootDir` with a trailing `.md` stripped
+ * (e.g. `migration/phase-1`). Falls back to the filename stem when `rootDir`
+ * is omitted.
+ */
+export function vaultItemPlainTitle(filePath, rootDir) {
+    if (rootDir === undefined) {
+        return path.basename(filePath, ".md");
+    }
+    const rel = vaultRelativePath(rootDir, filePath);
+    return rel.endsWith(".md") ? rel.slice(0, -3) : rel;
+}
 //# sourceMappingURL=path.js.map

package/dist/util/path.js.map

@@ -1 +1 @@
-{"version":3,"file":"path.js","sourceRoot":"","sources":["../../src/util/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;QAClB,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;IACtB,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;QAC/D,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa,EAAE,MAAc,OAAO,CAAC,GAAG,EAAE;IACxE,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,KAAa;IACxD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7C,OAAO,CACL,QAAQ,KAAK,EAAE;QACf,QAAQ,KAAK,IAAI;QACjB,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;QACrC,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAC3B,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAc,EAAE,KAAa;IAClE,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,CAAC;QACrC,OAAO,IAAI,KAAK,MAAM,IAAI,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../src/util/path.ts"],"names":[],"mappings":"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"}

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

@@ -3,7 +3,9 @@ export interface ListHandoffsOptions {
     limit?: number;
 }
 /**
- * Lists handoff markdown files under `logsDir`, newest filename first.
+ * 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 declare function listHandoffs(logsDir: string, options?: ListHandoffsOptions): Promise<string[]>;

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":"AAGA,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,MAAM,EAAE,CAAC,CAuBnB"}
+{"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"}

package/dist/vault/list-handoffs.js

@@ -1,24 +1,26 @@
-import { readdir } 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`, newest filename first.
+ * 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 = {}) {
-    let entries;
-    try {
-        entries = await readdir(logsDir);
-    }
-    catch (error) {
-        if (error.code === "ENOENT") {
-            return [];
+    const mdPaths = await listMarkdownFiles(logsDir);
+    const ranked = mdPaths.map((filePath) => ({
+        filePath,
+        name: path.basename(filePath),
+        rel: vaultRelativePath(logsDir, filePath),
+    }));
+    ranked.sort((a, b) => {
+        if (a.name !== b.name) {
+            return a.name < b.name ? 1 : -1;
         }
-        throw error;
-    }
-    const paths = entries
-        .filter((name) => name.endsWith(".md"))
-        .sort((a, b) => (a < b ? 1 : a > b ? -1 : 0))
-        .map((name) => path.join(logsDir, name));
+        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;
     }

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,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,IAAI,MAAM,WAAW,CAAC;AAO7B;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAe,EACf,UAA+B,EAAE;IAEjC,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvD,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IAED,MAAM,KAAK,GAAG,OAAO;SAClB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;SACtC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SAC5C,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;IAE3C,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,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"}

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

@@ -0,0 +1,8 @@
+/**
+ * Recursively lists `*.md` files under `rootDir` (absolute paths).
+ * Missing dirs yield `[]`. Does not follow directory symlinks (`Dirent`
+ * type checks); plain files that are symlinks to `.md` are included when
+ * `isFile()` reports true.
+ */
+export declare function listMarkdownFiles(rootDir: string): Promise<string[]>;
+//# sourceMappingURL=list-markdown.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list-markdown.d.ts","sourceRoot":"","sources":["../../src/vault/list-markdown.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA0B1E"}

package/dist/vault/list-markdown.js

@@ -0,0 +1,35 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Recursively lists `*.md` files under `rootDir` (absolute paths).
+ * Missing dirs yield `[]`. Does not follow directory symlinks (`Dirent`
+ * type checks); plain files that are symlinks to `.md` are included when
+ * `isFile()` reports true.
+ */
+export async function listMarkdownFiles(rootDir) {
+    const results = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return;
+            }
+            throw error;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".md")) {
+                results.push(full);
+            }
+        }
+    }
+    await walk(rootDir);
+    return results;
+}
+//# sourceMappingURL=list-markdown.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list-markdown.js","sourceRoot":"","sources":["../../src/vault/list-markdown.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAe;IACrD,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,UAAU,IAAI,CAAC,GAAW;QAC7B,IAAI,OAAiB,CAAC;QACtB,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACvD,OAAO;YACT,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;QAED,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACxC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;YACnB,CAAC;iBAAM,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBACxD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC;IACpB,OAAO,OAAO,CAAC;AACjB,CAAC"}

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

@@ -3,13 +3,13 @@ export interface ListNotesOptions {
     limit?: number;
 }
 /**
- * Lists note markdown files under `notesDir`, newest mtime first.
+ * Lists note markdown files under `notesDir` recursively, newest mtime first.
  * Returns absolute paths. Missing or empty dirs yield `[]`.
- * Ties break by filename descending for stable output.
+ * Ties break by vault-relative path descending for stable output.
  *
- * Filename-descending alone is a viable alternative for notes (timestamp
- * prefixes, like `listHandoffs`), but this intentionally matches `listPlans`
- * for consistency across list commands.
+ * Matches {@link listPlans} sorting for consistency across list commands
+ * (filename-descending alone is viable for timestamp-prefixed notes, like
+ * {@link listHandoffs}).
  */
 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":"AAGA,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,CAoCnB"}
+{"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"}