grounder 0.3.0 → 0.4.0

package/dist/vault/list-notes.js

@@ -0,0 +1,44 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Lists note markdown files under `notesDir`, newest mtime first.
+ * Returns absolute paths. Missing or empty dirs yield `[]`.
+ * Ties break by filename 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.
+ */
+export async function listNotes(notesDir, options = {}) {
+    let entries;
+    try {
+        entries = await readdir(notesDir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+    const mdNames = entries.filter((name) => name.endsWith(".md"));
+    const withMtime = await Promise.all(mdNames.map(async (name) => {
+        const filePath = path.join(notesDir, name);
+        const { mtimeMs } = await stat(filePath);
+        return { filePath, name, mtimeMs };
+    }));
+    withMtime.sort((a, b) => {
+        if (a.mtimeMs !== b.mtimeMs) {
+            return b.mtimeMs - a.mtimeMs;
+        }
+        return a.name < b.name ? 1 : a.name > b.name ? -1 : 0;
+    });
+    const paths = withMtime.map((entry) => entry.filePath);
+    if (options.limit === undefined) {
+        return paths;
+    }
+    if (options.limit <= 0) {
+        return [];
+    }
+    return paths.slice(0, options.limit);
+}
+//# sourceMappingURL=list-notes.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list-notes.js","sourceRoot":"","sources":["../../src/vault/list-notes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,IAAI,MAAM,WAAW,CAAC;AAO7B;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,QAAgB,EAChB,UAA4B,EAAE;IAE9B,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpC,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,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,GAAG,CACjC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC3C,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACrC,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,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,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"}

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.4.0",
+  "description": "Markdown-native memory for Cursor and Claude Code — session handoffs and plans in a vault you own",
   "type": "module",
   "bin": {
     "grounder": "./dist/cli.js"
@@ -16,7 +16,9 @@
   "keywords": [
     "obsidian",
     "cursor",
-    "mcp",
+    "claude-code",
+    "handoff",
+    "developer-tools",
     "ai",
     "cli"
   ],

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

@@ -1,11 +1,33 @@
 Save a note to the Obsidian 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>` (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).
+
+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>"
+
+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.

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

@@ -22,31 +22,35 @@ Build a markdown body with these sections:
 …
 ```
 
-Update vs create — never guess a `--title` for an update:
+**Special case: the instruction asks to view existing plans, not name a new topic** (`list`, `list 3 oldest`, `show plans`, etc.) → run `{{GROUNDER_CLI}} plan list --limit <N>` (N = count named, else 5; ignore order words like "oldest" — output is always newest-first, never resort or relabel it) and stop — no plan write, no title. Relay the CLI stdout as-is (it already includes the count header).
 
-**1. Path known** (attached/open in chat, or printed by an earlier `grounder plan` this conversation): update that exact file.
+Otherwise, resolve the target, then **state it plainly before writing** — `Updating plan at <path>.` or `Creating new plan titled <title>.` This is a visible record, not a blocking confirmation — updates overwrite with no `--force`, so get the match right.
+
+**1. Known path** (attached/open in chat, or printed by an earlier `grounder plan` this conversation) → update it directly.
+
+**2. No path, but update intent** (e.g. "update/continue/revise the plan", or a name that sounds like an existing one) → look it up first:
 
 ```bash
-{{GROUNDER_CLI}} plan "$(cat <<'EOF'
-# Plan: …
-…
-EOF
-)" --path <path-to-existing-plan.md>
+{{GROUNDER_CLI}} plan list --limit 5
 ```
 
-`--path` must resolve under this project's `plans/` dir; it always overwrites (no `--force`).
+CLI output starts with a count header, then each result as a numbered two-line block — `N. ` + title (filename stem) on the first line, the absolute path indented beneath it.
 
-**2. Path unknown** (e.g. "update the plan" with nothing attached and no prior path this conversation): look it up, then update as in (1).
+A match counts only if its title actually corresponds to what the user named — not just "it's the only plan in the project." No name given and exactly one plan exists → that counts too. If the user refers to a plan by the number shown in *this* listing (e.g. "update plan 2"), that counts as a match too — resolve it to the path from this same output, don't reuse a number from an earlier listing in the conversation (it's positional, not a stable id, and can shift if plans changed since). Otherwise (no match, several matches, or a name/number that doesn't correspond to any existing plan) → ask; never guess.
+
+Cases 1 and 2 (update) — run:
 
 ```bash
-{{GROUNDER_CLI}} plan list --limit 5
+{{GROUNDER_CLI}} plan "$(cat <<'EOF'
+# Plan: …
+…
+EOF
+)" --path <path>
 ```
 
-Pick the path matching the user's intent; ask if none or several match.
+`--path` must resolve under this project's `plans/` dir; it always overwrites (no `--force`).
 
-**3. Genuinely new plan** (not an update): derive a `--title`.
-- If the instruction names one explicitly (e.g. `save as "implementation-phase-1"` or `…phase-1.md`), use it (strip a trailing `.md`).
-- Otherwise derive a short kebab-case name from the plan's title/goal and confirm it with the user before writing.
+**3. No path, no update intent → genuinely new plan.** Derive a `--title` (the user's explicit name, else a short kebab-case slug from the plan's title/goal) and write immediately — don't ask about the name itself.
 
 ```bash
 {{GROUNDER_CLI}} plan "$(cat <<'EOF'
@@ -56,10 +60,10 @@ EOF
 )" --title <name>
 ```
 
-If the CLI refuses because that name already exists (non-zero exit; stderr names the conflict), tell the user and ask whether to overwrite (`--force`) or pick a different name. `--force` only resolves this title collision — it is never how you update a plan you already meant to target (use `--path` for that). **Never** silently pass `--force`.
+If `--title` collides with an existing plan (non-zero exit; stderr names the conflict), ask: overwrite (`--force`) or a different name. `--force` only resolves that collision — **never** use it to update a plan you meant to target with `--path`.
 
 Run from the linked project folder or any subdirectory beneath it.
 The vault is outside the workspace — grant shell permissions if Claude Code prompts you.
 
 Do not compute vault paths or write files yourself — the CLI handles it.
-Report the CLI output path from stdout to the user.
+Report the exact path the CLI prints on stdout — it confirms the real outcome, not just the intent.

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

@@ -2,7 +2,9 @@ Hydrate this session from the latest vault handoff and repo truth.
 
 Read-only — do not write to the vault. Do not invent vault paths.
 
-From the linked project folder or any subdirectory beneath it:
+**Special case: the instruction asks to view existing handoffs, not hydrate** (`list`, `list 3 oldest`, `show handoffs`, etc.) → run `{{GROUNDER_CLI}} handoff list --limit <N>` (N = count named, else 5; ignore order words like "oldest" — output is always newest-first, never resort or relabel it) and stop — no hydrate, no `AGENTS.md`, no “start work.” Relay the CLI stdout as-is (it already includes the count header).
+
+Otherwise, from the linked project folder or any subdirectory beneath it:
 
 1. Get the current handoff (skips empty/unreadable files, same pick as the session-start teaser):
 
@@ -10,7 +12,7 @@ From the linked project folder or any subdirectory beneath it:
 
 2. If empty: tell the user there are no handoffs yet, then read repo `AGENTS.md` only and proceed.
 
-3. Otherwise, read that file. If the user names a specific session instead, run `{{GROUNDER_CLI}} handoff list --limit 5` and read the path they mean.
+3. Otherwise, read that file. If the user names a specific session instead: `{{GROUNDER_CLI}} handoff list --limit 5` → match name/index to the indented path in *this* listing (positional, not a stable id). Miss → once with `--limit 50` (*that* listing only). Still miss → tell the user and stop — no guessed hydrate.
 
 4. Read repo `AGENTS.md` (project conventions and constraints).
 

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

@@ -1,11 +1,33 @@
 Save a note to the Obsidian 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>` (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).
 
-The vault is outside the workspace — approve shell permissions if Cursor prompts you.
+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>"
+
+For multi-line bodies, prefer a shell heredoc so quoting does not break:
+
+```bash
+{{GROUNDER_CLI}} note "$(cat <<'EOF'
+…
+EOF
+)"
+```
+
+Run {{GROUNDER_CLI}} with `required_permissions: ["all"]` (vault is outside the workspace).
 
-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.

package/templates/agents/cursor/commands/grounder-plan.md

@@ -22,31 +22,35 @@ Build a markdown body with these sections:
 …
 ```
 
-Update vs create — never guess a `--title` for an update:
+**Special case: the instruction asks to view existing plans, not name a new topic** (`list`, `list 3 oldest`, `show plans`, etc.) → run `{{GROUNDER_CLI}} plan list --limit <N>` (N = count named, else 5; ignore order words like "oldest" — output is always newest-first, never resort or relabel it) and stop — no plan write, no title. Relay the CLI stdout as-is (it already includes the count header).
 
-**1. Path known** (attached/open in chat, or printed by an earlier `grounder plan` this conversation): update that exact file.
+Otherwise, resolve the target, then **state it plainly before writing** — `Updating plan at <path>.` or `Creating new plan titled <title>.` This is a visible record, not a blocking confirmation — updates overwrite with no `--force`, so get the match right.
+
+**1. Known path** (attached/open in chat, or printed by an earlier `grounder plan` this conversation) → update it directly.
+
+**2. No path, but update intent** (e.g. "update/continue/revise the plan", or a name that sounds like an existing one) → look it up first:
 
 ```bash
-{{GROUNDER_CLI}} plan "$(cat <<'EOF'
-# Plan: …
-…
-EOF
-)" --path <path-to-existing-plan.md>
+{{GROUNDER_CLI}} plan list --limit 5
 ```
 
-`--path` must resolve under this project's `plans/` dir; it always overwrites (no `--force`).
+CLI output starts with a count header, then each result as a numbered two-line block — `N. ` + title (filename stem) on the first line, the absolute path indented beneath it.
 
-**2. Path unknown** (e.g. "update the plan" with nothing attached and no prior path this conversation): look it up, then update as in (1).
+A match counts only if its title actually corresponds to what the user named — not just "it's the only plan in the project." No name given and exactly one plan exists → that counts too. If the user refers to a plan by the number shown in *this* listing (e.g. "update plan 2"), that counts as a match too — resolve it to the path from this same output, don't reuse a number from an earlier listing in the conversation (it's positional, not a stable id, and can shift if plans changed since). Otherwise (no match, several matches, or a name/number that doesn't correspond to any existing plan) → ask; never guess.
+
+Cases 1 and 2 (update) — run:
 
 ```bash
-{{GROUNDER_CLI}} plan list --limit 5
+{{GROUNDER_CLI}} plan "$(cat <<'EOF'
+# Plan: …
+…
+EOF
+)" --path <path>
 ```
 
-Pick the path matching the user's intent; ask if none or several match.
+`--path` must resolve under this project's `plans/` dir; it always overwrites (no `--force`).
 
-**3. Genuinely new plan** (not an update): derive a `--title`.
-- If the instruction names one explicitly (e.g. `save as "implementation-phase-1"` or `…phase-1.md`), use it (strip a trailing `.md`).
-- Otherwise derive a short kebab-case name from the plan's title/goal and confirm it with the user before writing.
+**3. No path, no update intent → genuinely new plan.** Derive a `--title` (the user's explicit name, else a short kebab-case slug from the plan's title/goal) and write immediately — don't ask about the name itself.
 
 ```bash
 {{GROUNDER_CLI}} plan "$(cat <<'EOF'
@@ -56,10 +60,10 @@ EOF
 )" --title <name>
 ```
 
-If the CLI refuses because that name already exists (non-zero exit; stderr names the conflict), tell the user and ask whether to overwrite (`--force`) or pick a different name. `--force` only resolves this title collision — it is never how you update a plan you already meant to target (use `--path` for that). **Never** silently pass `--force`.
+If `--title` collides with an existing plan (non-zero exit; stderr names the conflict), ask: overwrite (`--force`) or a different name. `--force` only resolves that collision — **never** use it to update a plan you meant to target with `--path`.
 
 Run from the linked project folder or any subdirectory beneath it.
-The vault is outside the workspace — approve shell permissions if Cursor prompts you.
+Run {{GROUNDER_CLI}} with `required_permissions: ["all"]` (vault is outside the workspace).
 
 Do not compute vault paths or write files yourself — the CLI handles it.
-Report the CLI output path from stdout to the user.
+Report the exact path the CLI prints on stdout — it confirms the real outcome, not just the intent.

package/templates/agents/cursor/commands/grounder-task-handoff.md

@@ -48,7 +48,7 @@ EOF
 )"
 ```
 
-The vault is outside the workspace — approve shell permissions if Cursor prompts you.
+Run {{GROUNDER_CLI}} with `required_permissions: ["all"]` (vault is outside the workspace).
 
 Do not compute vault paths or write files yourself — the CLI handles it.
 Report the CLI output path from stdout to the user.

package/templates/agents/cursor/commands/grounder-task.md

@@ -2,7 +2,9 @@ Hydrate this session from the latest vault handoff and repo truth.
 
 Read-only — do not write to the vault. Do not invent vault paths.
 
-From the linked project folder or any subdirectory beneath it:
+**Special case: the instruction asks to view existing handoffs, not hydrate** (`list`, `list 3 oldest`, `show handoffs`, etc.) → run `{{GROUNDER_CLI}} handoff list --limit <N>` (N = count named, else 5; ignore order words like "oldest" — output is always newest-first, never resort or relabel it) and stop — no hydrate, no `AGENTS.md`, no “start work.” Relay the CLI stdout as-is (it already includes the count header).
+
+Otherwise, from the linked project folder or any subdirectory beneath it:
 
 1. Get the current handoff (skips empty/unreadable files, same pick as the session-start teaser):
 
@@ -10,11 +12,11 @@ From the linked project folder or any subdirectory beneath it:
 
 2. If empty: tell the user there are no handoffs yet, then read repo `AGENTS.md` only and proceed.
 
-3. Otherwise, read that file. If the user names a specific session instead, run `{{GROUNDER_CLI}} handoff list --limit 5` and read the path they mean.
+3. Otherwise, read that file. If the user names a specific session instead: `{{GROUNDER_CLI}} handoff list --limit 5` → match name/index to the indented path in *this* listing (positional, not a stable id). Miss → once with `--limit 50` (*that* listing only). Still miss → tell the user and stop — no guessed hydrate.
 
 4. Read repo `AGENTS.md` (project conventions and constraints).
 
 5. Summarize briefly what is next (from the handoff `## Next` section when present), then start work.
 
-The vault is outside the workspace — approve shell permissions if Cursor prompts you.
+Run {{GROUNDER_CLI}} with `required_permissions: ["all"]` (vault is outside the workspace).
 Use free-text after `/grounder-task` as optional focus (session name, index, or task hint).