grounder 0.4.0 → 0.5.0

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

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

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

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

package/dist/vault/write-plan.js

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

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

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "grounder",
-  "version": "0.4.0",
-  "description": "Markdown-native memory for Cursor and Claude Code — session handoffs and plans in a vault you own",
+  "version": "0.5.0",
+  "description": "Connect projects to an Obsidian vault (or any markdown folder) for AI agent memory — session handoffs, plans, and notes in files you own",
   "type": "module",
   "bin": {
     "grounder": "./dist/cli.js"
@@ -20,7 +20,14 @@
     "handoff",
     "developer-tools",
     "ai",
-    "cli"
+    "cli",
+    "agent-memory",
+    "local-first",
+    "vault",
+    "session-handoff",
+    "context-management",
+    "second-brain",
+    "pkm"
   ],
   "license": "MIT",
   "repository": {

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

@@ -1,9 +1,9 @@
-Save a note to the Obsidian vault for this project.
+Save a note to the markdown vault for this project.
 
 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.
 
-**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).
+**Special case: the instruction asks to view existing notes, not write one** (`list`, `list 3 oldest`, `show notes`, etc.) → run `{{GROUNDER_CLI}} note list --limit <N> --markdown` (N = count named, else 5; ignore order words like "oldest" — output is always newest-first, never resort or relabel it) and stop — no note write. Relay the CLI stdout as-is (it already includes the count header; title lines are clickable `[relativePath](fileUri)` links).
 
 Rules:
 - Default → distill the args into a clean note body
@@ -18,6 +18,10 @@ Optional short title slug (filename):
 
   {{GROUNDER_CLI}} note --title <slug> "<body>"
 
+Always include `--topics` with 3-5 comma-separated lowercase keywords that capture the note's core concepts (e.g. `--topics "schema,migration,postgres"`). Pick terms a future search would use — concrete nouns and technical terms, not verbs or filler:
+
+  {{GROUNDER_CLI}} note --topics "keyword1,keyword2,keyword3" "<body>"
+
 For multi-line bodies, prefer a shell heredoc so quoting does not break:
 
 ```bash

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

@@ -1,4 +1,4 @@
-Write a named, updatable plan document to the Obsidian vault for this project.
+Write a named, updatable plan document to the markdown vault for this project.
 
 Distill the instruction after `/grounder-plan` into a structured plan — not a chat transcript.
 Do not dump tool traces, full conversation, or false starts.
@@ -22,7 +22,7 @@ Build a markdown body with these sections:
 …
 ```
 
-**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).
+**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> --markdown` (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; title lines are clickable `[relativePath](fileUri)` links).
 
 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.
 
@@ -31,12 +31,12 @@ Otherwise, resolve the target, then **state it plainly before writing** — `Upd
 **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 list --limit 5
+{{GROUNDER_CLI}} plan list --limit 5 --markdown
 ```
 
-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.
+CLI output starts with a count header, then each result as a numbered two-line block — `N. ` + `[relativePath](fileUri)` on the first line, the absolute path indented beneath it (use that absolute path for `--path`).
 
-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.
+A match counts only if the filename stem / relative path 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 indented absolute 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:
 
@@ -62,6 +62,8 @@ EOF
 
 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`.
 
+Always include `--topics` with 3-5 comma-separated lowercase keywords that capture the plan's core concepts (e.g. `--topics "caching,redis,performance,api"`). Pick terms a future search would use — concrete nouns and technical terms, not verbs or filler.
+
 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.
 

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

@@ -0,0 +1,144 @@
+Search this project's vault content for relevant context.
+
+**Silence:** write **no assistant text** until step 3. Rounds 1–2 are tool calls with an empty/absent text part — not “I’ll search…”, not “I’ll read…”, not “**Analyzing…**”, not query/terms narration.
+
+Use this when the user asks to find prior project-vault context by topic, keyword, concept, or phrase.
+
+Scope is this linked project only — the CLI resolves and searches under the linked project vault root. Do not search outside it.
+
+## Turn budget (speed)
+
+**Rounds 1–2: tool calls only — no text part in those messages.** Not even one sentence.
+
+Exactly **two** assistant turns with tools, then the answer. Allowed tools, nothing else:
+
+1. Round 1 — Shell only: one `search … --json` (optional second search in the *same* round only per the broaden rule below). Message = that tool call, nothing else.
+2. Round 2 — Read only: **one** parallel batch of full-file reads (hits 1–4). Message = those Read calls, nothing else.
+3. Final answer to the user (first and only chat text).
+
+**Do not** Glob, Grep, extra Shell, or status/UI tools (`UpdateCurrentStep`, `TodoWrite`, and similar). Do not add a third tool turn. Do not explore the repo.
+
+## Output contract (default — hybrid)
+
+- Do not echo commands or shell output.
+- **Never paste CLI JSON, snippets, or raw stdout into chat** — parse `--json` internally only.
+- One final synthesized response only.
+
+**Path links (mandatory for every listed file):**
+- Visible title = `hits[].relativePath` from JSON **exactly** (project-vault-relative; the folder that contains `notes/`, `logs/`, and `plans/`). Example: `plans/archive/0.2.0 and older/doc.md`.
+- **Do not** derive the title from `hits[].file`, path segments, or parent-vault prefixes.
+- **Wrong titles:** `10-Projects/grounder/plans/…`, `%20` in the visible title, or any path above the project vault root.
+- Link href = `hits[].fileUri` from JSON (spaces already percent-encoded).
+- Markdown form: `[hits[i].relativePath](hits[i].fileUri)`
+
+**Numbering (mandatory):**
+- Number every listed file, continuing across sections (`1…` in **Read these**, then `5…` in **Also matched`).
+- Do not restart at 1 in **Also matched**. Do not use bullet-only lists without numbers.
+
+Structure:
+
+1. **Opening** — one sentence of what the vault says (not a search recap). Never start with “I have searched…”, “I found…”, or similar.
+2. **Read these** — hits 1–4 only; numbered linked paths + optional role + short bullets under each. You may list a design/archive authority first *among those four*.
+3. **Also matched** — leftover top-10 **in CLI order** (do not reshuffle); numbered linked paths + one short phrase each (`hits[].alsoMatchedHint` or `matches[].term`). Every line must end with ` — phrase`; bare links are invalid. Omit if empty.
+
+Example shape (`##` headings required — not bold-only, not `###`):
+
+```markdown
+Vault notes discuss …
+
+## Read these
+1. [plans/archive/0.3.0/schema_….md](file:///…/schema_….md) — design authority
+   - …
+2. [plans/…](file:///…) — …
+## Also matched
+3. [plans/archive/0.2.0 and older/doc.md](file:///…/0.2.0%20and%20older/doc.md) — one phrase
+4. [plans/…](file:///…) — one phrase
+```
+
+**Lookup mode:** explicit lookup wording (`exact phrase`, `this line`, `the wording`) **or** the entire input after stripping retrieval wrappers is a bare `"quoted span"` → relay CLI `--markdown` as-is (one search, no `--terms`, no full reads).
+
+## Steps
+
+1. **Query and terms (private)** — classify, then build argv. Classification is silent (no chat text). The CLI always line-scans `query` plus `--terms`. Multi-word queries only match lines that contain that phrase verbatim. Rank is dominated by how many distinct terms hit the **same** file — complementary vault words beat extra English synonyms and source module names.
+
+   **Classify** after stripping retrieval wrappers (`find`, `search for`, `documents discussing`, `notes about`, `look up`). Then pick one:
+
+   - **Lookup** — explicit lookup wording (`exact phrase`, `this line`, `the wording`), **or** leftover is a bare `"quoted span"`. `query` = the quoted text, unmodified. Relay CLI `--markdown` as-is; no `--terms`, no full reads.
+   - **Request** — leftover still has request syntax (any of): `that mention` / `that discuss` / `that talk about`; leftover starts with `plans that` / `notes that` / `docs that` / `documents that`; trailing scope `both in` / `either in` / `in CLI and`. Do **not** pass that leftover as `query`. `query` = one primary noun or named command from the topic (tight phrase; do not prefix a product name). Extra nouns go in `--terms`.
+   - **Topic leftover** — leftover is already a topic noun-phrase. `query` = leftover, same words, same order. Do not paraphrase, shorten, or coin a new phrase.
+
+   Strip only retrieval wrappers. Do not pass the whole utterance. Do not recycle the query as a `--terms` item.
+
+   Examples below are a **fictional** domain. Copy the shape; invent tokens for *this* topic. Do not reuse these strings as `--terms`.
+
+   Example — lookup. User: `find "retry of expired jobs"`
+   - class: lookup
+   - argv: {{GROUNDER_CLI}} search "retry of expired jobs" --markdown
+
+   Example — topic leftover. User: `find documents discussing retry of expired jobs`
+   - class: topic leftover
+   - query: `retry of expired jobs` (leftover after stripping the wrapper)
+   - wrong query: `expired job retries` (rewritten)
+   - wrong class: request (`documents discussing` is a wrapper)
+
+   Example — request. User: `find plans that mention updating the charge or refund command, both in worker and API`
+   - class: request (`plans that mention` / `both in` stay leftover — not the topic)
+   - query: `charge` (one named command from leftover; not `billing charge`)
+   - terms: `refund,settlement,invoices.json,RefundPolicy`
+     - from leftover: `refund` (the other named command)
+     - invented: `settlement` (domain), `invoices.json` (file), `RefundPolicy` (schema) — guess this project's equivalents
+   - wrong query: `plans that mention updating the charge or refund command, both in worker and API`
+   - wrong query: `charge refund command` (joined nouns)
+   - not as terms: `plan`, `command`, `api`
+
+   **Terms** — invent 3–5 complementary vault tokens for *this* topic, then stop. They need not appear in the utterance:
+   1. Domain noun/phrase from the topic (skip if it would duplicate the query)
+   2. Named command or product verb if the topic has one — never a lone generic verb (`migrate`, `install`)
+   3. One on-disk identifier (filename, config key, schema field) guessed for this project
+   4–5. Only another vault/product token. No paraphrase of the query.
+
+   **Never as terms** (unless the user asked about code layout): repo paths, `packages/…`, source module / file stems. Lone high-df words (`plan`, `command`, `cli`) flatten rank. Prefer words that appear in vault notes (named commands, config files, domain identifiers).
+
+   Example — user: `look up why the retry queue must skip expired jobs`
+   - class: topic leftover
+   - query: `why the retry queue must skip expired jobs`
+   - terms: `retry queue,dead letter,jobs.json,RetryPolicy,ttl` (`retry queue` from leftover; others invented)
+   - not: `queue-worker`, `process-jobs`, `skip`, `look up`
+
+2. **Search (tool round 1):**
+
+```bash
+{{GROUNDER_CLI}} search "<query>" --terms "<csv>" --context 2 --json
+```
+
+**Always quote `--terms`.** Unquoted CSV with spaces corrupts argv.
+
+Parse JSON privately. Take hits in CLI order (`hits[0]` …). For links use `relativePath` + `fileUri`; for Also matched gloss use `alsoMatchedHint` or `matches[].term` — do not quote snippets.
+
+**Broaden once (silent)** only if: `totalFileCount` is 0; or ≤2 and every hit is meta (`discussions/search/`, or snippet only quotes the query); or any term in `termHitCounts` has a count of 0 (that term produced no files — it was a bad guess and must be replaced). Otherwise do not re-search.
+
+   Broaden call (use `--context 3` — weaker matches need more context):
+
+```bash
+{{GROUNDER_CLI}} search "<query>" --terms "<csv-with-replacement>" --context 3 --json
+```
+
+   **Broaden strategy (deterministic):** check `termHitCounts` first — if any term has count 0, replace **that term** (not slot-3) with a different product/vault token. If no zero-hit term, drop slot-3 (the on-disk identifier). Keep slots 1–2 (product noun/verb) unchanged. Do not invent new terms or rewrite existing ones.
+
+3. **Read (tool round 2)** — mandatory unless lookup:
+   - Full-read CLI hits **1–4** in rank order, **all in one parallel batch**.
+   - Read path = `hits[i].file` (absolute). Link title/href = `hits[i].relativePath` + `hits[i].fileUri`.
+   - **No skips, no substitutions, no “maybe also hit 5.”** Trust CLI order; judge relevance only when writing the answer.
+   - Grant read permissions for vault paths outside the workspace when needed.
+
+4. **Answer** — synthesize immediately after reads:
+   - Claims only from files you full-read. Unread hits must not grow new facts.
+   - **Read these:** useful full-reads (those 1–4 only). Thin/off-topic reads get one blunt numbered line there or move to **Also matched**.
+   - **Also matched:** remaining top-10 you did not deep-summarize, **in CLI leftover order**. Copy `alsoMatchedHint` or phrase from `matches[].term`; every line ends with ` — phrase`.
+   - Every file line: `[relativePath](fileUri)` from JSON; continue numbering across sections.
+   - Prefer design/archive docs when they are the authority among the files you read.
+
+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 write to vault files during search.
+Do not grep the vault yourself — the CLI ranks; you read and synthesize.

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

@@ -1,4 +1,4 @@
-Write a session handoff checkpoint to the Obsidian vault for this project.
+Write a session handoff checkpoint to the markdown vault for this project.
 
 Summarize the session into a structured handoff — not a chat transcript.
 Do not dump tool traces, full conversation, or false starts.
@@ -38,6 +38,10 @@ Optional short title slug (filename + frontmatter):
 
   {{GROUNDER_CLI}} handoff --title <slug> "<body>"
 
+Always include `--topics` with 3-5 comma-separated lowercase keywords that capture the session's core concepts (e.g. `--topics "auth,middleware,jwt,session"`). Pick terms a future search would use — concrete nouns and technical terms, not verbs or filler:
+
+  {{GROUNDER_CLI}} handoff --topics "keyword1,keyword2,keyword3" "<body>"
+
 For multi-line bodies, prefer a shell heredoc so quoting does not break:
 
 ```bash

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

@@ -2,7 +2,7 @@ Hydrate this session from the latest vault handoff and repo truth.
 
 Read-only — do not write to the vault. Do not invent vault paths.
 
-**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).
+**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> --markdown` (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; title lines are clickable `[relativePath](fileUri)` links).
 
 Otherwise, from the linked project folder or any subdirectory beneath it:
 
@@ -12,7 +12,7 @@ Otherwise, 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: `{{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.
+3. Otherwise, read that file. If the user names a specific session instead: `{{GROUNDER_CLI}} handoff list --limit 5 --markdown` → match name/index to the indented absolute path in *this* listing (positional, not a stable id). Miss → once with `--limit 50 --markdown` (*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,9 +1,9 @@
-Save a note to the Obsidian vault for this project.
+Save a note to the markdown vault for this project.
 
 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.
 
-**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).
+**Special case: the instruction asks to view existing notes, not write one** (`list`, `list 3 oldest`, `show notes`, etc.) → run `{{GROUNDER_CLI}} note list --limit <N> --markdown` (N = count named, else 5; ignore order words like "oldest" — output is always newest-first, never resort or relabel it) and stop — no note write. Relay the CLI stdout as-is (it already includes the count header; title lines are clickable `[relativePath](fileUri)` links).
 
 Rules:
 - Default → distill the args into a clean note body
@@ -18,6 +18,10 @@ Optional short title slug (filename):
 
   {{GROUNDER_CLI}} note --title <slug> "<body>"
 
+Always include `--topics` with 3-5 comma-separated lowercase keywords that capture the note's core concepts (e.g. `--topics "schema,migration,postgres"`). Pick terms a future search would use — concrete nouns and technical terms, not verbs or filler:
+
+  {{GROUNDER_CLI}} note --topics "keyword1,keyword2,keyword3" "<body>"
+
 For multi-line bodies, prefer a shell heredoc so quoting does not break:
 
 ```bash

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

@@ -1,4 +1,4 @@
-Write a named, updatable plan document to the Obsidian vault for this project.
+Write a named, updatable plan document to the markdown vault for this project.
 
 Distill the instruction after `/grounder-plan` into a structured plan — not a chat transcript.
 Do not dump tool traces, full conversation, or false starts.
@@ -22,7 +22,7 @@ Build a markdown body with these sections:
 …
 ```
 
-**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).
+**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> --markdown` (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; title lines are clickable `[relativePath](fileUri)` links).
 
 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.
 
@@ -31,12 +31,12 @@ Otherwise, resolve the target, then **state it plainly before writing** — `Upd
 **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 list --limit 5
+{{GROUNDER_CLI}} plan list --limit 5 --markdown
 ```
 
-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.
+CLI output starts with a count header, then each result as a numbered two-line block — `N. ` + `[relativePath](fileUri)` on the first line, the absolute path indented beneath it (use that absolute path for `--path`).
 
-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.
+A match counts only if the filename stem / relative path 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 indented absolute 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:
 
@@ -62,6 +62,8 @@ EOF
 
 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`.
 
+Always include `--topics` with 3-5 comma-separated lowercase keywords that capture the plan's core concepts (e.g. `--topics "caching,redis,performance,api"`). Pick terms a future search would use — concrete nouns and technical terms, not verbs or filler.
+
 Run from the linked project folder or any subdirectory beneath it.
 Run {{GROUNDER_CLI}} with `required_permissions: ["all"]` (vault is outside the workspace).
 

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

@@ -0,0 +1,144 @@
+Search this project's vault content for relevant context.
+
+**Silence:** write **no assistant text** until step 3. Rounds 1–2 are tool calls with an empty/absent text part — not “I’ll search…”, not “I’ll read…”, not “**Analyzing…**”, not query/terms narration.
+
+Use this when the user asks to find prior project-vault context by topic, keyword, concept, or phrase.
+
+Scope is this linked project only — the CLI resolves and searches under the linked project vault root. Do not search outside it.
+
+## Turn budget (speed)
+
+**Rounds 1–2: tool calls only — no text part in those messages.** Not even one sentence.
+
+Exactly **two** assistant turns with tools, then the answer. Allowed tools, nothing else:
+
+1. Round 1 — Shell only: one `search … --json` (optional second search in the *same* round only per the broaden rule below). Message = that tool call, nothing else.
+2. Round 2 — Read only: **one** parallel batch of full-file reads (hits 1–4). Message = those Read calls, nothing else.
+3. Final answer to the user (first and only chat text).
+
+**Do not** Glob, Grep, extra Shell, or status/UI tools (`UpdateCurrentStep`, `TodoWrite`, and similar). Do not add a third tool turn. Do not explore the repo.
+
+## Output contract (default — hybrid)
+
+- Do not echo commands or shell output.
+- **Never paste CLI JSON, snippets, or raw stdout into chat** — parse `--json` internally only.
+- One final synthesized response only.
+
+**Path links (mandatory for every listed file):**
+- Visible title = `hits[].relativePath` from JSON **exactly** (project-vault-relative; the folder that contains `notes/`, `logs/`, and `plans/`). Example: `plans/archive/0.2.0 and older/doc.md`.
+- **Do not** derive the title from `hits[].file`, path segments, or parent-vault prefixes.
+- **Wrong titles:** `10-Projects/grounder/plans/…`, `%20` in the visible title, or any path above the project vault root.
+- Link href = `hits[].fileUri` from JSON (spaces already percent-encoded).
+- Markdown form: `[hits[i].relativePath](hits[i].fileUri)`
+
+**Numbering (mandatory):**
+- Number every listed file, continuing across sections (`1…` in **Read these**, then `5…` in **Also matched`).
+- Do not restart at 1 in **Also matched**. Do not use bullet-only lists without numbers.
+
+Structure:
+
+1. **Opening** — one sentence of what the vault says (not a search recap). Never start with “I have searched…”, “I found…”, or similar.
+2. **Read these** — hits 1–4 only; numbered linked paths + optional role + short bullets under each. You may list a design/archive authority first *among those four*.
+3. **Also matched** — leftover top-10 **in CLI order** (do not reshuffle); numbered linked paths + one short phrase each (`hits[].alsoMatchedHint` or `matches[].term`). Every line must end with ` — phrase`; bare links are invalid. Omit if empty.
+
+Example shape (`##` headings required — not bold-only, not `###`):
+
+```markdown
+Vault notes discuss …
+
+## Read these
+1. [plans/archive/0.3.0/schema_….md](file:///…/schema_….md) — design authority
+   - …
+2. [plans/…](file:///…) — …
+## Also matched
+3. [plans/archive/0.2.0 and older/doc.md](file:///…/0.2.0%20and%20older/doc.md) — one phrase
+4. [plans/…](file:///…) — one phrase
+```
+
+**Lookup mode:** explicit lookup wording (`exact phrase`, `this line`, `the wording`) **or** the entire input after stripping retrieval wrappers is a bare `"quoted span"` → relay CLI `--markdown` as-is (one search, no `--terms`, no full reads).
+
+## Steps
+
+1. **Query and terms (private)** — classify, then build argv. Classification is silent (no chat text). The CLI always line-scans `query` plus `--terms`. Multi-word queries only match lines that contain that phrase verbatim. Rank is dominated by how many distinct terms hit the **same** file — complementary vault words beat extra English synonyms and source module names.
+
+   **Classify** after stripping retrieval wrappers (`find`, `search for`, `documents discussing`, `notes about`, `look up`). Then pick one:
+
+   - **Lookup** — explicit lookup wording (`exact phrase`, `this line`, `the wording`), **or** leftover is a bare `"quoted span"`. `query` = the quoted text, unmodified. Relay CLI `--markdown` as-is; no `--terms`, no full reads.
+   - **Request** — leftover still has request syntax (any of): `that mention` / `that discuss` / `that talk about`; leftover starts with `plans that` / `notes that` / `docs that` / `documents that`; trailing scope `both in` / `either in` / `in CLI and`. Do **not** pass that leftover as `query`. `query` = one primary noun or named command from the topic (tight phrase; do not prefix a product name). Extra nouns go in `--terms`.
+   - **Topic leftover** — leftover is already a topic noun-phrase. `query` = leftover, same words, same order. Do not paraphrase, shorten, or coin a new phrase.
+
+   Strip only retrieval wrappers. Do not pass the whole utterance. Do not recycle the query as a `--terms` item.
+
+   Examples below are a **fictional** domain. Copy the shape; invent tokens for *this* topic. Do not reuse these strings as `--terms`.
+
+   Example — lookup. User: `find "retry of expired jobs"`
+   - class: lookup
+   - argv: {{GROUNDER_CLI}} search "retry of expired jobs" --markdown
+
+   Example — topic leftover. User: `find documents discussing retry of expired jobs`
+   - class: topic leftover
+   - query: `retry of expired jobs` (leftover after stripping the wrapper)
+   - wrong query: `expired job retries` (rewritten)
+   - wrong class: request (`documents discussing` is a wrapper)
+
+   Example — request. User: `find plans that mention updating the charge or refund command, both in worker and API`
+   - class: request (`plans that mention` / `both in` stay leftover — not the topic)
+   - query: `charge` (one named command from leftover; not `billing charge`)
+   - terms: `refund,settlement,invoices.json,RefundPolicy`
+     - from leftover: `refund` (the other named command)
+     - invented: `settlement` (domain), `invoices.json` (file), `RefundPolicy` (schema) — guess this project's equivalents
+   - wrong query: `plans that mention updating the charge or refund command, both in worker and API`
+   - wrong query: `charge refund command` (joined nouns)
+   - not as terms: `plan`, `command`, `api`
+
+   **Terms** — invent 3–5 complementary vault tokens for *this* topic, then stop. They need not appear in the utterance:
+   1. Domain noun/phrase from the topic (skip if it would duplicate the query)
+   2. Named command or product verb if the topic has one — never a lone generic verb (`migrate`, `install`)
+   3. One on-disk identifier (filename, config key, schema field) guessed for this project
+   4–5. Only another vault/product token. No paraphrase of the query.
+
+   **Never as terms** (unless the user asked about code layout): repo paths, `packages/…`, source module / file stems. Lone high-df words (`plan`, `command`, `cli`) flatten rank. Prefer words that appear in vault notes (named commands, config files, domain identifiers).
+
+   Example — user: `look up why the retry queue must skip expired jobs`
+   - class: topic leftover
+   - query: `why the retry queue must skip expired jobs`
+   - terms: `retry queue,dead letter,jobs.json,RetryPolicy,ttl` (`retry queue` from leftover; others invented)
+   - not: `queue-worker`, `process-jobs`, `skip`, `look up`
+
+2. **Search (tool round 1):**
+
+```bash
+{{GROUNDER_CLI}} search "<query>" --terms "<csv>" --context 2 --json
+```
+
+**Always quote `--terms`.** Unquoted CSV with spaces corrupts argv.
+
+Parse JSON privately. Take hits in CLI order (`hits[0]` …). For links use `relativePath` + `fileUri`; for Also matched gloss use `alsoMatchedHint` or `matches[].term` — do not quote snippets.
+
+**Broaden once (silent)** only if: `totalFileCount` is 0; or ≤2 and every hit is meta (`discussions/search/`, or snippet only quotes the query); or any term in `termHitCounts` has a count of 0 (that term produced no files — it was a bad guess and must be replaced). Otherwise do not re-search.
+
+   Broaden call (use `--context 3` — weaker matches need more context):
+
+```bash
+{{GROUNDER_CLI}} search "<query>" --terms "<csv-with-replacement>" --context 3 --json
+```
+
+   **Broaden strategy (deterministic):** check `termHitCounts` first — if any term has count 0, replace **that term** (not slot-3) with a different product/vault token. If no zero-hit term, drop slot-3 (the on-disk identifier). Keep slots 1–2 (product noun/verb) unchanged. Do not invent new terms or rewrite existing ones.
+
+3. **Read (tool round 2)** — mandatory unless lookup:
+   - Full-read CLI hits **1–4** in rank order, **all in one parallel batch**.
+   - Read path = `hits[i].file` (absolute). Link title/href = `hits[i].relativePath` + `hits[i].fileUri`.
+   - **No skips, no substitutions, no “maybe also hit 5.”** Trust CLI order; judge relevance only when writing the answer.
+   - Request vault read permissions as needed.
+
+4. **Answer** — synthesize immediately after reads:
+   - Claims only from files you full-read. Unread hits must not grow new facts.
+   - **Read these:** useful full-reads (those 1–4 only). Thin/off-topic reads get one blunt numbered line there or move to **Also matched**.
+   - **Also matched:** remaining top-10 you did not deep-summarize, **in CLI leftover order**. Copy `alsoMatchedHint` or phrase from `matches[].term`; every line ends with ` — phrase`.
+   - Every file line: `[relativePath](fileUri)` from JSON; continue numbering across sections.
+   - Prefer design/archive docs when they are the authority among the files you read.
+
+Run from the linked project folder or any subdirectory beneath it.
+Run {{GROUNDER_CLI}} with `required_permissions: ["all"]` (vault is outside the workspace).
+Do not write to vault files during search.
+Do not grep the vault yourself — the CLI ranks; you read and synthesize.

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

@@ -1,4 +1,4 @@
-Write a session handoff checkpoint to the Obsidian vault for this project.
+Write a session handoff checkpoint to the markdown vault for this project.
 
 Summarize the session into a structured handoff — not a chat transcript.
 Do not dump tool traces, full conversation, or false starts.
@@ -38,6 +38,10 @@ Optional short title slug (filename + frontmatter):
 
   {{GROUNDER_CLI}} handoff --title <slug> "<body>"
 
+Always include `--topics` with 3-5 comma-separated lowercase keywords that capture the session's core concepts (e.g. `--topics "auth,middleware,jwt,session"`). Pick terms a future search would use — concrete nouns and technical terms, not verbs or filler:
+
+  {{GROUNDER_CLI}} handoff --topics "keyword1,keyword2,keyword3" "<body>"
+
 For multi-line bodies, prefer a shell heredoc so quoting does not break:
 
 ```bash

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

@@ -2,7 +2,7 @@ Hydrate this session from the latest vault handoff and repo truth.
 
 Read-only — do not write to the vault. Do not invent vault paths.
 
-**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).
+**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> --markdown` (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; title lines are clickable `[relativePath](fileUri)` links).
 
 Otherwise, from the linked project folder or any subdirectory beneath it:
 
@@ -12,7 +12,7 @@ Otherwise, 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: `{{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.
+3. Otherwise, read that file. If the user names a specific session instead: `{{GROUNDER_CLI}} handoff list --limit 5 --markdown` → match name/index to the indented absolute path in *this* listing (positional, not a stable id). Miss → once with `--limit 50 --markdown` (*that* listing only). Still miss → tell the user and stop — no guessed hydrate.
 
 4. Read repo `AGENTS.md` (project conventions and constraints).