grounder 0.2.0 → 0.4.0

package/dist/util/path.d.ts

@@ -7,4 +7,14 @@ export declare function expandHome(input: string): string;
  * Expand a leading `~`, then resolve to an absolute path (relative to `cwd` if given).
  */
 export declare function resolveUserPath(input: string, cwd?: string): string;
+/**
+ * True when `child` is inside `parent` (or equal), using lexical `path.resolve` only
+ * (does not follow symlinks). Rejects `..` escape and cross-root relatives.
+ */
+export declare function isPathInside(parent: string, child: string): boolean;
+/**
+ * True when `child`'s real path is strictly inside `parent` (symlinks followed).
+ * Returns `null` if either path cannot be resolved (e.g. missing).
+ */
+export declare function isRealPathInside(parent: string, child: string): Promise<boolean | null>;
 //# 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":"AAGA;;;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"}
+{"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"}

package/dist/util/path.js

@@ -1,3 +1,4 @@
+import { realpath } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 /**
@@ -19,4 +20,34 @@ export function expandHome(input) {
 export function resolveUserPath(input, cwd = process.cwd()) {
     return path.resolve(cwd, expandHome(input));
 }
+/**
+ * True when `child` is inside `parent` (or equal), using lexical `path.resolve` only
+ * (does not follow symlinks). Rejects `..` escape and cross-root relatives.
+ */
+export function isPathInside(parent, child) {
+    const root = path.resolve(parent);
+    const target = path.resolve(child);
+    if (root === target) {
+        return true;
+    }
+    const relative = path.relative(root, target);
+    return (relative !== "" &&
+        relative !== ".." &&
+        !relative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relative));
+}
+/**
+ * True when `child`'s real path is strictly inside `parent` (symlinks followed).
+ * Returns `null` if either path cannot be resolved (e.g. missing).
+ */
+export async function isRealPathInside(parent, child) {
+    try {
+        const root = await realpath(parent);
+        const target = await realpath(child);
+        return root !== target && isPathInside(root, target);
+    }
+    catch {
+        return null;
+    }
+}
 //# 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,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"}
+{"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"}

package/dist/util/plan-name.d.ts

@@ -0,0 +1,10 @@
+/** Generous cap for plan filenames — real plan names often exceed note/handoff's 20-char slug. */
+export declare const MAX_PLAN_NAME_LENGTH = 80;
+/**
+ * Sanitize a `--title` value into a filename-safe plan name.
+ * Trims, strips a trailing `.md` (case-insensitive), applies {@link sanitizeProjectId}
+ * character rules, and caps at {@link MAX_PLAN_NAME_LENGTH}.
+ * Returns `""` when the result is empty / unusable.
+ */
+export declare function sanitizePlanName(rawTitle: string): string;
+//# sourceMappingURL=plan-name.d.ts.map

package/dist/util/plan-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-name.d.ts","sourceRoot":"","sources":["../../src/util/plan-name.ts"],"names":[],"mappings":"AAEA,kGAAkG;AAClG,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOzD"}

package/dist/util/plan-name.js

@@ -0,0 +1,18 @@
+import { sanitizeProjectId } from "./project-id.js";
+/** Generous cap for plan filenames — real plan names often exceed note/handoff's 20-char slug. */
+export const MAX_PLAN_NAME_LENGTH = 80;
+/**
+ * Sanitize a `--title` value into a filename-safe plan name.
+ * Trims, strips a trailing `.md` (case-insensitive), applies {@link sanitizeProjectId}
+ * character rules, and caps at {@link MAX_PLAN_NAME_LENGTH}.
+ * Returns `""` when the result is empty / unusable.
+ */
+export function sanitizePlanName(rawTitle) {
+    const trimmed = rawTitle.trim().replace(/\.md$/i, "");
+    const sanitized = sanitizeProjectId(trimmed);
+    if (!sanitized) {
+        return "";
+    }
+    return sanitized.slice(0, MAX_PLAN_NAME_LENGTH).replace(/-+$/g, "");
+}
+//# sourceMappingURL=plan-name.js.map

package/dist/util/plan-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-name.js","sourceRoot":"","sources":["../../src/util/plan-name.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,kGAAkG;AAClG,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACtD,MAAM,SAAS,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,oBAAoB,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACtE,CAAC"}

package/dist/util/semver.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Compare npm-style `major.minor.patch` prefixes.
+ * Returns negative / zero / positive like `strcmp`, or `null` if either side
+ * lacks a leading `x.y.z` (prerelease/build suffixes after the triple are ignored).
+ */
+export declare function compareSemver(a: string, b: string): number | null;
+/** How the running package version relates to the last-recorded ledger version. */
+export type PackageVersionRelation = "match" | "ahead" | "behind" | "differs";
+export declare function packageVersionRelation(running: string, recorded: string): PackageVersionRelation;
+//# sourceMappingURL=semver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"semver.d.ts","sourceRoot":"","sources":["../../src/util/semver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwBjE;AAED,mFAAmF;AACnF,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9E,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,sBAAsB,CAUhG"}

package/dist/util/semver.js

@@ -0,0 +1,40 @@
+/**
+ * Compare npm-style `major.minor.patch` prefixes.
+ * Returns negative / zero / positive like `strcmp`, or `null` if either side
+ * lacks a leading `x.y.z` (prerelease/build suffixes after the triple are ignored).
+ */
+export function compareSemver(a, b) {
+    const parse = (v) => {
+        const match = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
+        if (!match) {
+            return null;
+        }
+        return [Number(match[1]), Number(match[2]), Number(match[3])];
+    };
+    const left = parse(a);
+    const right = parse(b);
+    if (!left || !right) {
+        return null;
+    }
+    for (let i = 0; i < 3; i++) {
+        if (left[i] < right[i]) {
+            return -1;
+        }
+        if (left[i] > right[i]) {
+            return 1;
+        }
+    }
+    return 0;
+}
+export function packageVersionRelation(running, recorded) {
+    if (running === recorded) {
+        return "match";
+    }
+    const cmp = compareSemver(running, recorded);
+    if (cmp === null || cmp === 0) {
+        // Unparseable, or same x.y.z with different suffix/string form.
+        return "differs";
+    }
+    return cmp > 0 ? "ahead" : "behind";
+}
+//# sourceMappingURL=semver.js.map

package/dist/util/semver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semver.js","sourceRoot":"","sources":["../../src/util/semver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,CAAS,EAAE,CAAS;IAChD,MAAM,KAAK,GAAG,CAAC,CAAS,EAAmC,EAAE;QAC3D,MAAM,KAAK,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,CAAC,CAAC;IAEF,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACtB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,CAAC,CAAC;QACZ,CAAC;QACD,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,CAAC;QACX,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAKD,MAAM,UAAU,sBAAsB,CAAC,OAAe,EAAE,QAAgB;IACtE,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QACzB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC7C,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC;QAC9B,gEAAgE;QAChE,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC;AACtC,CAAC"}

package/dist/vault/layout.d.ts

@@ -10,4 +10,6 @@ export declare function projectDir(vaultRoot: string, projectId: string): string
 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;
+/** `<vault>/10-Projects/{projectId}/plans` — named, updatable plan docs. */
+export declare function plansDir(vaultRoot: string, projectId: string): string;
 //# sourceMappingURL=layout.d.ts.map

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

@@ -1 +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"}
+{"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;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAErE"}

package/dist/vault/layout.js

@@ -19,4 +19,8 @@ export function notesDir(vaultRoot, projectId) {
 export function logsDir(vaultRoot, projectId) {
     return path.join(vaultRoot, PROJECTS_DIR, projectId, "logs");
 }
+/** `<vault>/10-Projects/{projectId}/plans` — named, updatable plan docs. */
+export function plansDir(vaultRoot, projectId) {
+    return path.join(vaultRoot, PROJECTS_DIR, projectId, "plans");
+}
 //# sourceMappingURL=layout.js.map

package/dist/vault/layout.js.map

@@ -1 +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"}
+{"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;AAED,4EAA4E;AAC5E,MAAM,UAAU,QAAQ,CAAC,SAAiB,EAAE,SAAiB;IAC3D,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AAChE,CAAC"}

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

@@ -0,0 +1,15 @@
+export interface ListNotesOptions {
+    /** Max paths to return (newest first). Omit to return all. */
+    limit?: number;
+}
+/**
+ * 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 declare function listNotes(notesDir: string, options?: ListNotesOptions): Promise<string[]>;
+//# sourceMappingURL=list-notes.d.ts.map

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

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

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/dist/vault/list-plans.d.ts

@@ -0,0 +1,11 @@
+export interface ListPlansOptions {
+    /** Max paths to return (newest first). Omit to return all. */
+    limit?: number;
+}
+/**
+ * Lists plan markdown files under `plansDir`, newest mtime first.
+ * Returns absolute paths. Missing or empty dirs yield `[]`.
+ * Ties break by filename descending for stable output.
+ */
+export declare function listPlans(plansDir: string, options?: ListPlansOptions): Promise<string[]>;
+//# sourceMappingURL=list-plans.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list-plans.d.ts","sourceRoot":"","sources":["../../src/vault/list-plans.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,MAAM,EAAE,CAAC,CAoCnB"}

package/dist/vault/list-plans.js

@@ -0,0 +1,40 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Lists plan markdown files under `plansDir`, newest mtime first.
+ * Returns absolute paths. Missing or empty dirs yield `[]`.
+ * Ties break by filename descending for stable output.
+ */
+export async function listPlans(plansDir, options = {}) {
+    let entries;
+    try {
+        entries = await readdir(plansDir);
+    }
+    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(plansDir, 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-plans.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list-plans.js","sourceRoot":"","sources":["../../src/vault/list-plans.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,IAAI,MAAM,WAAW,CAAC;AAO7B;;;;GAIG;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/dist/vault/write-plan.d.ts

@@ -0,0 +1,28 @@
+/** Options for {@link writePlan}. */
+export interface WritePlanOptions {
+    /** Project id written into YAML frontmatter. */
+    projectId: string;
+    /** When true, overwrite an existing plan (preserving original `created`). */
+    force?: boolean;
+    /** Timestamp for `created` / `updated` (default: now). */
+    now?: Date;
+}
+export type WritePlanStatus = "created" | "overwritten" | "exists";
+export interface WritePlanResult {
+    path: string;
+    status: WritePlanStatus;
+}
+/**
+ * Overwrites an existing plan at an absolute path.
+ * Preserves original `created` (falls back to `now` if missing) and sets `updated`.
+ * 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>;
+/**
+ * Writes or updates a named plan markdown file under `plansDir` (created if missing).
+ * 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`.
+ */
+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

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

package/dist/vault/write-plan.js

@@ -0,0 +1,61 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parseHandoffFrontmatter } from "../util/frontmatter.js";
+import { fileExists } from "../util/fs.js";
+import { yamlDoubleQuoted } from "../util/yaml.js";
+function buildFrontmatter(options) {
+    const lines = [
+        "---",
+        `project: ${yamlDoubleQuoted(options.projectId)}`,
+        `created: ${yamlDoubleQuoted(options.created)}`,
+    ];
+    if (options.updated) {
+        lines.push(`updated: ${yamlDoubleQuoted(options.updated)}`);
+    }
+    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`.
+ * Caller must validate the path (e.g. inside this project's `plans/` dir).
+ */
+export async function updatePlanAtPath(filePath, body, options) {
+    const now = options.now ?? new Date();
+    const existing = await readFile(filePath, "utf8");
+    const fm = parseHandoffFrontmatter(existing);
+    const created = fm.created ?? now.toISOString();
+    const updated = now.toISOString();
+    const content = buildFrontmatter({
+        projectId: options.projectId,
+        created,
+        updated,
+    }) + body;
+    await writeFile(filePath, content, "utf8");
+    return { path: filePath, status: "overwritten" };
+}
+/**
+ * Writes or updates a named plan markdown file under `plansDir` (created if missing).
+ * 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`.
+ */
+export async function writePlan(plansDir, name, body, options) {
+    const now = options.now ?? new Date();
+    await mkdir(plansDir, { recursive: true });
+    const filePath = path.join(plansDir, `${name}.md`);
+    const exists = await fileExists(filePath);
+    if (exists && !options.force) {
+        return { path: filePath, status: "exists" };
+    }
+    if (exists && options.force) {
+        return updatePlanAtPath(filePath, body, { projectId: options.projectId, now });
+    }
+    const content = buildFrontmatter({
+        projectId: options.projectId,
+        created: now.toISOString(),
+    }) + body;
+    await writeFile(filePath, content, "utf8");
+    return { path: filePath, status: "created" };
+}
+//# sourceMappingURL=write-plan.js.map

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

@@ -0,0 +1 @@
+{"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.2.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.
 
-  npx grounder 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

@@ -0,0 +1,69 @@
+Write a named, updatable plan document to the Obsidian 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.
+
+Build a markdown body with these sections:
+
+```markdown
+# Plan: <title>
+
+## Goal
+…
+
+## Steps
+1. …
+2. …
+
+## Decisions / open questions
+- …
+
+## Status
+…
+```
+
+**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).
+
+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 list --limit 5
+```
+
+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.
+
+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 "$(cat <<'EOF'
+# Plan: …
+…
+EOF
+)" --path <path>
+```
+
+`--path` must resolve under this project's `plans/` dir; it always overwrites (no `--force`).
+
+**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'
+# Plan: …
+…
+EOF
+)" --title <name>
+```
+
+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 exact path the CLI prints on stdout — it confirms the real outcome, not just the intent.

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

@@ -32,16 +32,16 @@ Rules:
 
 Then run from the linked project folder or any subdirectory beneath it:
 
-  npx grounder handoff "<body>"
+  {{GROUNDER_CLI}} handoff "<body>"
 
 Optional short title slug (filename + frontmatter):
 
-  npx grounder handoff --title <slug> "<body>"
+  {{GROUNDER_CLI}} handoff --title <slug> "<body>"
 
 For multi-line bodies, prefer a shell heredoc so quoting does not break:
 
 ```bash
-npx grounder handoff "$(cat <<'EOF'
+{{GROUNDER_CLI}} handoff "$(cat <<'EOF'
 # Handoff: …
 …
 EOF

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

@@ -2,15 +2,17 @@ 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):
 
-   npx grounder handoff list --head
+   {{GROUNDER_CLI}} handoff list --head
 
 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 `npx grounder 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).