grounder 0.0.1 → 0.0.2

package/dist/util/yaml.js

@@ -0,0 +1,13 @@
+/**
+ * Double-quote a YAML scalar and escape `\`, `"`, and newlines.
+ * Always quoted so values with `:`, `#`, leading spaces, etc. stay valid.
+ */
+export function yamlDoubleQuoted(value) {
+    const escaped = value
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\r/g, "\\r")
+        .replace(/\n/g, "\\n");
+    return `"${escaped}"`;
+}
+//# sourceMappingURL=yaml.js.map

package/dist/util/yaml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.js","sourceRoot":"","sources":["../../src/util/yaml.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,MAAM,OAAO,GAAG,KAAK;SAClB,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;SACpB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC;SACrB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACzB,OAAO,IAAI,OAAO,GAAG,CAAC;AACxB,CAAC"}

package/dist/vault/layout.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Pure vault layout: path segments only — no config files or env overrides.
+ */
+export declare const PROJECTS_DIR = "10-Projects";
+/** `<vault>/10-Projects` — parent of all project folders. */
+export declare function projectsParent(vaultRoot: string): string;
+/** `<vault>/10-Projects/{projectId}`. */
+export declare function projectDir(vaultRoot: string, projectId: string): string;
+/** `<vault>/10-Projects/{projectId}/notes`. */
+export declare function notesDir(vaultRoot: string, projectId: string): string;
+/** `<vault>/10-Projects/{projectId}/logs` — session handoffs. */
+export declare function logsDir(vaultRoot: string, projectId: string): string;
+//# sourceMappingURL=layout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../src/vault/layout.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,eAAO,MAAM,YAAY,gBAAgB,CAAC;AAE1C,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,yCAAyC;AACzC,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,+CAA+C;AAC/C,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,iEAAiE;AACjE,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpE"}

package/dist/vault/layout.js

@@ -0,0 +1,22 @@
+/**
+ * Pure vault layout: path segments only — no config files or env overrides.
+ */
+import path from "node:path";
+export const PROJECTS_DIR = "10-Projects";
+/** `<vault>/10-Projects` — parent of all project folders. */
+export function projectsParent(vaultRoot) {
+    return path.join(vaultRoot, PROJECTS_DIR);
+}
+/** `<vault>/10-Projects/{projectId}`. */
+export function projectDir(vaultRoot, projectId) {
+    return path.join(vaultRoot, PROJECTS_DIR, projectId);
+}
+/** `<vault>/10-Projects/{projectId}/notes`. */
+export function notesDir(vaultRoot, projectId) {
+    return path.join(vaultRoot, PROJECTS_DIR, projectId, "notes");
+}
+/** `<vault>/10-Projects/{projectId}/logs` — session handoffs. */
+export function logsDir(vaultRoot, projectId) {
+    return path.join(vaultRoot, PROJECTS_DIR, projectId, "logs");
+}
+//# sourceMappingURL=layout.js.map

package/dist/vault/layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../../src/vault/layout.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAC;AAE1C,6DAA6D;AAC7D,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;AAC5C,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,UAAU,CAAC,SAAiB,EAAE,SAAiB;IAC7D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,QAAQ,CAAC,SAAiB,EAAE,SAAiB;IAC3D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAChE,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,OAAO,CAAC,SAAiB,EAAE,SAAiB;IAC1D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;AAC/D,CAAC"}

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

@@ -0,0 +1,10 @@
+export interface ListHandoffsOptions {
+    /** Max paths to return (newest first). Omit to return all. */
+    limit?: number;
+}
+/**
+ * Lists handoff markdown files under `logsDir`, newest filename first.
+ * Returns absolute paths. Missing or empty dirs yield `[]`.
+ */
+export declare function listHandoffs(logsDir: string, options?: ListHandoffsOptions): Promise<string[]>;
+//# sourceMappingURL=list-handoffs.d.ts.map

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

@@ -0,0 +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"}

package/dist/vault/list-handoffs.js

@@ -0,0 +1,30 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Lists handoff markdown files under `logsDir`, newest filename first.
+ * 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 [];
+        }
+        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));
+    if (options.limit === undefined) {
+        return paths;
+    }
+    if (options.limit <= 0) {
+        return [];
+    }
+    return paths.slice(0, options.limit);
+}
+//# sourceMappingURL=list-handoffs.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,21 @@
+/** Options for {@link writeHandoff}. */
+export interface WriteHandoffOptions {
+    /** Project id written into YAML frontmatter. */
+    projectId: string;
+    /** Optional title slug for the filename and frontmatter. */
+    title?: string;
+    /** Git branch when known; omitted from frontmatter if unset. */
+    branch?: string;
+    /** Timestamp for filename prefix and `created` (default: now). */
+    now?: Date;
+}
+/**
+ * Writes a new handoff markdown file under `logsDir` (created if missing).
+ * Prepends YAML frontmatter (`project`, optional `branch`/`title`, `created`)
+ * ahead of `body`. Never overwrites — exclusive create with `_NN` on collision.
+ * @param logsDir - Absolute project logs directory.
+ * @param body - Agent-supplied markdown (sections such as Done / Next); not validated here.
+ * @returns Absolute path of the written file.
+ */
+export declare function writeHandoff(logsDir: string, body: string, options: WriteHandoffOptions): Promise<string>;
+//# sourceMappingURL=write-handoff.d.ts.map

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

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

package/dist/vault/write-handoff.js

@@ -0,0 +1,40 @@
+import { mkdir } from "node:fs/promises";
+import { writeUniqueMarkdown } from "../util/fs.js";
+import { timestampedBasename } from "../util/timestamp-slug.js";
+import { yamlDoubleQuoted } from "../util/yaml.js";
+function buildFrontmatter(options) {
+    const lines = ["---", `project: ${yamlDoubleQuoted(options.projectId)}`];
+    if (options.branch) {
+        lines.push(`branch: ${yamlDoubleQuoted(options.branch)}`);
+    }
+    lines.push(`created: ${yamlDoubleQuoted(options.created)}`);
+    if (options.title) {
+        lines.push(`title: ${yamlDoubleQuoted(options.title)}`);
+    }
+    lines.push("---");
+    return `${lines.join("\n")}\n\n`;
+}
+/**
+ * Writes a new handoff markdown file under `logsDir` (created if missing).
+ * Prepends YAML frontmatter (`project`, optional `branch`/`title`, `created`)
+ * ahead of `body`. Never overwrites — exclusive create with `_NN` on collision.
+ * @param logsDir - Absolute project logs directory.
+ * @param body - Agent-supplied markdown (sections such as Done / Next); not validated here.
+ * @returns Absolute path of the written file.
+ */
+export async function writeHandoff(logsDir, body, options) {
+    const now = options.now ?? new Date();
+    await mkdir(logsDir, { recursive: true });
+    const basename = timestampedBasename(body, {
+        title: options.title,
+        now,
+    });
+    const content = buildFrontmatter({
+        projectId: options.projectId,
+        branch: options.branch,
+        created: now.toISOString(),
+        title: options.title,
+    }) + body;
+    return writeUniqueMarkdown(logsDir, basename, content);
+}
+//# sourceMappingURL=write-handoff.js.map

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

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

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

@@ -0,0 +1,11 @@
+export interface WriteNoteOptions {
+    title?: string;
+    now?: Date;
+}
+/**
+ * Writes a new note markdown file under `notesDir` (created if missing).
+ * Never overwrites — exclusive create with `_NN` on collision.
+ * @returns Absolute path of the written file.
+ */
+export declare function writeNote(notesDir: string, text: string, options?: WriteNoteOptions): Promise<string>;
+//# sourceMappingURL=write-note.d.ts.map

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

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

package/dist/vault/write-note.js

@@ -0,0 +1,15 @@
+import { mkdir } from "node:fs/promises";
+import { writeUniqueMarkdown } from "../util/fs.js";
+import { timestampedBasename } from "../util/timestamp-slug.js";
+/**
+ * Writes a new note markdown file under `notesDir` (created if missing).
+ * Never overwrites — exclusive create with `_NN` on collision.
+ * @returns Absolute path of the written file.
+ */
+export async function writeNote(notesDir, text, options = {}) {
+    const now = options.now ?? new Date();
+    await mkdir(notesDir, { recursive: true });
+    const basename = timestampedBasename(text, { title: options.title, now });
+    return writeUniqueMarkdown(notesDir, basename, text);
+}
+//# sourceMappingURL=write-note.js.map

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

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

package/package.json

@@ -1,13 +1,48 @@
 {
   "name": "grounder",
-  "version": "0.0.1",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "0.0.2",
+  "description": "Connect git projects to Obsidian dev vaults for AI agent memory",
+  "type": "module",
+  "bin": {
+    "grounder": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "obsidian",
+    "cursor",
+    "mcp",
+    "ai",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andrej-kolic/grounder.git",
+    "directory": "packages/grounder"
+  },
+  "bugs": {
+    "url": "https://github.com/andrej-kolic/grounder/issues"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "type": "commonjs"
-}
+  "homepage": "https://github.com/andrej-kolic/grounder/tree/main/packages/grounder#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "pretest": "pnpm run build",
+    "test": "vitest run"
+  }
+}

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

@@ -0,0 +1,11 @@
+Save a note to the Obsidian vault for this project.
+
+Run from the linked project folder or any subdirectory beneath it:
+
+  npx grounder note "<user text>"
+
+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-task-handoff.md

@@ -0,0 +1,54 @@
+Write a session handoff checkpoint to the Obsidian 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.
+
+Build a markdown body with these sections (lean; roughly half a screen to one screen):
+
+```markdown
+# Handoff: <short label>
+
+## Done
+- …
+
+## Next
+1. …   # ordered; most important section for resume — required
+2. …
+
+## Blockers
+- None | …
+
+## Decisions
+- …    # include rejected alternatives / pitfalls when useful
+
+## Files
+- path/to/relevant.ts
+```
+
+Rules:
+- **Next is mandatory and ordered** — if only one section is read, this is it
+- Empty sections are OK (`Blockers: None` beats omission)
+- Few concrete file paths, not an exhaustive diff
+
+Then run from the linked project folder or any subdirectory beneath it:
+
+  npx grounder handoff "<body>"
+
+Optional short title slug (filename + frontmatter):
+
+  npx grounder handoff --title <slug> "<body>"
+
+For multi-line bodies, prefer a shell heredoc so quoting does not break:
+
+```bash
+npx grounder handoff "$(cat <<'EOF'
+# Handoff: …
+…
+EOF
+)"
+```
+
+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.

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

@@ -0,0 +1,20 @@
+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:
+
+1. List recent handoffs (newest first):
+
+   npx grounder handoff list --limit 5
+
+2. If the list is empty: tell the user there are no handoffs yet, then read repo `AGENTS.md` only and proceed.
+
+3. If handoffs exist: read the newest file (first path). Optionally skim other listed paths if the user names a session or the newest is clearly wrong.
+
+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 — grant shell permissions if Claude Code prompts you.
+Use free-text after `/grounder-task` as optional focus (session name, index, or task hint).

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

@@ -0,0 +1,11 @@
+Save a note to the Obsidian vault for this project.
+
+Run from the linked project folder or any subdirectory beneath it:
+
+  npx grounder note "<user text>"
+
+The vault is outside the workspace — approve shell permissions if Cursor 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/cursor/commands/grounder-task-handoff.md

@@ -0,0 +1,54 @@
+Write a session handoff checkpoint to the Obsidian 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.
+
+Build a markdown body with these sections (lean; roughly half a screen to one screen):
+
+```markdown
+# Handoff: <short label>
+
+## Done
+- …
+
+## Next
+1. …   # ordered; most important section for resume — required
+2. …
+
+## Blockers
+- None | …
+
+## Decisions
+- …    # include rejected alternatives / pitfalls when useful
+
+## Files
+- path/to/relevant.ts
+```
+
+Rules:
+- **Next is mandatory and ordered** — if only one section is read, this is it
+- Empty sections are OK (`Blockers: None` beats omission)
+- Few concrete file paths, not an exhaustive diff
+
+Then run from the linked project folder or any subdirectory beneath it:
+
+  npx grounder handoff "<body>"
+
+Optional short title slug (filename + frontmatter):
+
+  npx grounder handoff --title <slug> "<body>"
+
+For multi-line bodies, prefer a shell heredoc so quoting does not break:
+
+```bash
+npx grounder handoff "$(cat <<'EOF'
+# Handoff: …
+…
+EOF
+)"
+```
+
+The vault is outside the workspace — approve shell permissions if Cursor 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.

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

@@ -0,0 +1,20 @@
+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:
+
+1. List recent handoffs (newest first):
+
+   npx grounder handoff list --limit 5
+
+2. If the list is empty: tell the user there are no handoffs yet, then read repo `AGENTS.md` only and proceed.
+
+3. If handoffs exist: read the newest file (first path). Optionally skim other listed paths if the user names a session or the newest is clearly wrong.
+
+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.
+Use free-text after `/grounder-task` as optional focus (session name, index, or task hint).

package/templates/vault/session-handoff.md

@@ -0,0 +1,19 @@
+<!-- Reference shape for /grounder-task-handoff. Not installed or filled by the CLI — slash commands embed this structure. -->
+
+# Handoff: <title or short label>
+
+## Done
+- …
+
+## Next
+1. …
+2. …
+
+## Blockers
+- None
+
+## Decisions
+- …
+
+## Files
+- path/to/relevant.ts

package/index.js

@@ -1 +0,0 @@
-module.exports = {};