grounder 0.2.0 → 0.4.0

package/dist/commands/handoff/list.js.map

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

package/dist/commands/handoff/peek.d.ts

@@ -17,8 +17,9 @@ export interface HandoffPeekOptions {
 export declare function labelFromHandoffFilename(filePath: string): string;
 /**
  * CLI entry for `grounder handoff peek`.
- * Silent by default: prints nothing and exits 0 when unlinked, empty, or on any error.
- * Used by session-start hooks — must never crash or print noise.
+ * Silent by default: prints nothing and exits 0 when unlinked, empty, or on any error
+ * (unless install schemas are stale — then a one-line migrate nudge).
+ * Used by session-start hooks — must never crash or print noise on stderr.
  * Reads Cursor hook stdin for `workspace_roots[0]` when present; falls back to
  * `CURSOR_PROJECT_DIR` (user-level hooks often run with cwd under `~/.cursor`).
  * Pass `--json` for Cursor's `additional_context` stdout contract.
@@ -31,6 +32,8 @@ export declare function runHandoffPeek(argv: string[]): Promise<number>;
  * files and falls back to the next-newest — the same selection `grounder handoff list
  * --head` uses, so the teaser and `/grounder-task` never disagree about which handoff
  * is current.
+ * Also checks `state.json` and may add a one-line "run grounder migrate" hint
+ * for people who never run doctor.
  * Uses {@link resolveLinkedProject} directly (not `requireLinkedProject`) so failures stay silent.
  * @returns Always `0`.
  */

package/dist/commands/handoff/peek.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"peek.d.ts","sourceRoot":"","sources":["../../../src/commands/handoff/peek.ts"],"names":[],"mappings":"AASA,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAKD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWjE;AA4CD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAOpE;AAED;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BjG"}
+{"version":3,"file":"peek.d.ts","sourceRoot":"","sources":["../../../src/commands/handoff/peek.ts"],"names":[],"mappings":"AAYA,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAOD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWjE;AA6ED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAYpE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BjG"}

package/dist/commands/handoff/peek.js

@@ -1,11 +1,15 @@
 import path from "node:path";
 import { readCursorHookWorkspaceRoot } from "../../agents/cursor-hook-input.js";
+import { ALL_AGENTS } from "../../agents/index.js";
 import { withHomeDir } from "../../connector/home.js";
 import { resolveLinkedProject } from "../../connector/linked.js";
+import { isInstallSchemaStale, readGrounderState } from "../../connector/state.js";
 import { resolveLogsDir } from "../../connector/vault.js";
+import { helpExitCode } from "../../help.js";
 import { parseHandoffFrontmatter } from "../../util/frontmatter.js";
 import { flagBool, parseArgs } from "../../util/parse-args.js";
 import { findUsableHandoff } from "../../vault/find-usable-handoff.js";
+const MIGRATE_TEASER = "[grounder] Install outdated — run: grounder migrate.";
 /** `YYYY-MM-DD-HHmm` or `YYYY-MM-DD-HHmmss`, optionally followed by `-slug`. */
 const TIMESTAMP_STEM = /^(\d{4}-\d{2}-\d{2})-\d{4}(?:\d{2})?(?:-(.*))?$/;
 /**
@@ -60,16 +64,50 @@ function resolveCursorHookCwd(stdinWorkspaceRoot) {
     const fromEnv = process.env.CURSOR_PROJECT_DIR?.trim();
     return fromEnv || undefined;
 }
+/**
+ * Whether to print the "run grounder migrate" line from session peek.
+ * Only looks at `~/.grounder/state.json` — does not open Cursor/Claude files.
+ *
+ * If hooks were never enabled (no hooks version in state), that is not "out of
+ * date" here. Doctor is the place that checks whether hook files exist on disk.
+ * If state is missing or unreadable, stay quiet — doctor reports that.
+ */
+async function schemaMigrateNeeded(homeDir) {
+    try {
+        const state = await readGrounderState(homeDir);
+        return isInstallSchemaStale(state, ALL_AGENTS);
+    }
+    catch {
+        return false;
+    }
+}
+function composeTeaser(handoffLine, migrateNeeded) {
+    if (handoffLine && migrateNeeded) {
+        return `${handoffLine}\n${MIGRATE_TEASER}`;
+    }
+    if (handoffLine) {
+        return handoffLine;
+    }
+    if (migrateNeeded) {
+        return MIGRATE_TEASER;
+    }
+    return undefined;
+}
 /**
  * CLI entry for `grounder handoff peek`.
- * Silent by default: prints nothing and exits 0 when unlinked, empty, or on any error.
- * Used by session-start hooks — must never crash or print noise.
+ * Silent by default: prints nothing and exits 0 when unlinked, empty, or on any error
+ * (unless install schemas are stale — then a one-line migrate nudge).
+ * Used by session-start hooks — must never crash or print noise on stderr.
  * Reads Cursor hook stdin for `workspace_roots[0]` when present; falls back to
  * `CURSOR_PROJECT_DIR` (user-level hooks often run with cwd under `~/.cursor`).
  * Pass `--json` for Cursor's `additional_context` stdout contract.
  * @returns Always `0`.
  */
 export async function runHandoffPeek(argv) {
+    const helpCode = helpExitCode(argv, "handoff peek");
+    if (helpCode !== null) {
+        return helpCode;
+    }
     const { flags } = parseArgs(argv);
     const stdinWorkspaceRoot = await readCursorHookWorkspaceRoot(process.stdin);
     return runHandoffPeekWithOptions({
@@ -83,13 +121,15 @@ export async function runHandoffPeek(argv) {
  * files and falls back to the next-newest — the same selection `grounder handoff list
  * --head` uses, so the teaser and `/grounder-task` never disagree about which handoff
  * is current.
+ * Also checks `state.json` and may add a one-line "run grounder migrate" hint
+ * for people who never run doctor.
  * Uses {@link resolveLinkedProject} directly (not `requireLinkedProject`) so failures stay silent.
  * @returns Always `0`.
  */
 export async function runHandoffPeekWithOptions(options = {}) {
     try {
         return await withHomeDir(options.homeDir, async () => {
-            let teaser;
+            let handoffLine;
             try {
                 const resolved = await resolveLinkedProject(options.cwd ?? process.cwd());
                 if (resolved.ok) {
@@ -100,15 +140,16 @@ export async function runHandoffPeekWithOptions(options = {}) {
                         const label = fm.title?.trim() || labelFromHandoffFilename(usable.path);
                         const createdDate = formatCreatedDate(fm.created, usable.path);
                         if (createdDate) {
-                            teaser = `[grounder] Latest handoff: "${label}" (${createdDate}). Run /grounder-task to load it, or ignore if unrelated.`;
+                            handoffLine = `[grounder] Latest handoff: "${label}" (${createdDate}). Run /grounder-task to load it, or ignore if unrelated.`;
                         }
                     }
                 }
             }
             catch {
-                teaser = undefined;
+                handoffLine = undefined;
             }
-            writePeekOutput(teaser, options.json);
+            const migrateNeeded = await schemaMigrateNeeded(options.homeDir);
+            writePeekOutput(composeTeaser(handoffLine, migrateNeeded), options.json);
             return 0;
         });
     }

package/dist/commands/handoff/peek.js.map

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

package/dist/commands/handoff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../../src/commands/handoff.ts"],"names":[],"mappings":"AAOA,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAahE;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAoBpF"}
+{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../../src/commands/handoff.ts"],"names":[],"mappings":"AAQA,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBhE;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAoBpF"}

package/dist/commands/handoff.js

@@ -1,6 +1,7 @@
 import { currentBranch } from "../connector/git.js";
 import { withHomeDir } from "../connector/home.js";
 import { resolveLogsDir } from "../connector/vault.js";
+import { helpExitCode } from "../help.js";
 import { flagString, parseArgs } from "../util/parse-args.js";
 import { writeHandoff } from "../vault/write-handoff.js";
 import { requireLinkedProject } from "./require-linked.js";
@@ -9,6 +10,10 @@ import { requireLinkedProject } from "./require-linked.js";
  * @returns Exit code (`0` on success, `1` on usage or config errors).
  */
 export async function runHandoff(argv) {
+    const helpCode = helpExitCode(argv, "handoff");
+    if (helpCode !== null) {
+        return helpCode;
+    }
     const { positional, flags } = parseArgs(argv);
     const text = positional.join(" ").trim();
     if (!text) {

package/dist/commands/handoff.js.map

@@ -1 +1 @@
-{"version":3,"file":"handoff.js","sourceRoot":"","sources":["../../src/commands/handoff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAgB3D;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAc;IAC7C,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAEzC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACzD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,qBAAqB,CAAC;QAC3B,IAAI;QACJ,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC;KAClC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,OAAuB;IACjE,OAAO,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QAED,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QACvC,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAClE,MAAM,WAAW,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE;YAC5D,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM;YACN,GAAG,EAAE,OAAO,CAAC,GAAG;SACjB,CAAC,CAAC;QAEH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,WAAW,IAAI,CAAC,CAAC;QAC/C,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"handoff.js","sourceRoot":"","sources":["../../src/commands/handoff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAgB3D;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAc;IAC7C,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAC/C,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAEzC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACzD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,qBAAqB,CAAC;QAC3B,IAAI;QACJ,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC;KAClC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,OAAuB;IACjE,OAAO,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QAED,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QACvC,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAClE,MAAM,WAAW,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE;YAC5D,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM;YACN,GAAG,EAAE,OAAO,CAAC,GAAG;SACjB,CAAC,CAAC;QAEH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,WAAW,IAAI,CAAC,CAAC;QAC/C,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/migrate.d.ts

@@ -0,0 +1,23 @@
+import { type AgentAdapter } from "../agents/index.js";
+export interface MigrateOptions {
+    force?: boolean;
+    hooks?: boolean;
+    dryRun?: boolean;
+    homeDir?: string;
+    /** Agent ids to migrate. Defaults to ledger keys, else auto-detect. */
+    agents?: string[];
+}
+/**
+ * Resolve which agents to migrate:
+ * 1. Explicit `--agent` ids (unknown ids still throw)
+ * 2. Else agents recorded in `~/.grounder/state.json` that this binary knows
+ * 3. Else auto-detect installed agents (legacy / pre-ledger)
+ *
+ * Ledger keys from a newer Grounder (agents this binary does not know) are
+ * skipped with a stderr warning — same forward-compat idea as schema hard-stops,
+ * but migrate can still refresh the agents it understands.
+ */
+export declare function resolveMigrateAgents(explicitIds: string[] | undefined, homeDir?: string): Promise<AgentAdapter[]>;
+export declare function runMigrate(argv: string[]): Promise<number>;
+export declare function runMigrateWithOptions(options?: MigrateOptions): Promise<number>;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/commands/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAA6B,MAAM,oBAAoB,CAAC;AAQlF,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EAAE,GAAG,SAAS,EACjC,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,EAAE,CAAC,CAmBzB;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAchE;AAED,wBAAsB,qBAAqB,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8DzF"}

package/dist/commands/migrate.js

@@ -0,0 +1,104 @@
+import { ALL_AGENTS, resolveAgents } from "../agents/index.js";
+import { readHomeConfig, withHomeDir } from "../connector/home.js";
+import { assertAgentSchemasSupported, readGrounderState, statePath } from "../connector/state.js";
+import { isUnsupportedSchemaError } from "../connector/unsupported-schema.js";
+import { helpExitCode } from "../help.js";
+import { flagBool, flagStrings, parseArgs } from "../util/parse-args.js";
+import { applyAgentInstalls } from "./apply-agent-installs.js";
+/**
+ * Resolve which agents to migrate:
+ * 1. Explicit `--agent` ids (unknown ids still throw)
+ * 2. Else agents recorded in `~/.grounder/state.json` that this binary knows
+ * 3. Else auto-detect installed agents (legacy / pre-ledger)
+ *
+ * Ledger keys from a newer Grounder (agents this binary does not know) are
+ * skipped with a stderr warning — same forward-compat idea as schema hard-stops,
+ * but migrate can still refresh the agents it understands.
+ */
+export async function resolveMigrateAgents(explicitIds, homeDir) {
+    if (explicitIds && explicitIds.length > 0) {
+        return resolveAgents(explicitIds);
+    }
+    const state = await readGrounderState(homeDir);
+    const recordedIds = state ? Object.keys(state.agents) : [];
+    if (recordedIds.length === 0) {
+        return resolveAgents();
+    }
+    const known = ALL_AGENTS.filter((a) => recordedIds.includes(a.id));
+    const unknown = recordedIds.filter((id) => !ALL_AGENTS.some((a) => a.id === id));
+    if (unknown.length > 0) {
+        process.stderr.write(`Skipping unknown agent(s) in install state: ${unknown.join(", ")}. Upgrade grounder to migrate them.\n`);
+    }
+    return known;
+}
+export async function runMigrate(argv) {
+    const helpCode = helpExitCode(argv, "migrate");
+    if (helpCode !== null) {
+        return helpCode;
+    }
+    const { flags, repeated } = parseArgs(argv);
+    const agents = flagStrings(repeated, "agent");
+    return runMigrateWithOptions({
+        force: flagBool(flags, "force", "f"),
+        hooks: flagBool(flags, "hooks"),
+        dryRun: flagBool(flags, "dry-run"),
+        agents: agents.length > 0 ? agents : undefined,
+    });
+}
+export async function runMigrateWithOptions(options = {}) {
+    return withHomeDir(options.homeDir, async () => {
+        const homeDir = options.homeDir;
+        const force = options.force ?? false;
+        const hooks = options.hooks ?? false;
+        const dryRun = options.dryRun ?? false;
+        const home = await readHomeConfig();
+        if (!home) {
+            process.stderr.write("No home config found. Run `grounder vault init <path>` first.\n");
+            return 1;
+        }
+        const agents = await resolveMigrateAgents(options.agents, homeDir);
+        try {
+            const state = await readGrounderState(homeDir);
+            assertAgentSchemasSupported(state, agents);
+        }
+        catch (error) {
+            if (isUnsupportedSchemaError(error)) {
+                process.stderr.write(`${error.message}\n`);
+                return 1;
+            }
+            throw error;
+        }
+        process.stdout.write(`Vault root: ${home.vaultRoot}\n`);
+        if (dryRun) {
+            process.stdout.write("Dry run — no files will be written.\n");
+        }
+        process.stdout.write("Will refresh:\n");
+        if (agents.length === 0) {
+            process.stdout.write("  (no agents recorded or detected)\n");
+        }
+        else {
+            for (const agent of agents) {
+                for (const artifactPath of agent.expectedArtifacts(homeDir)) {
+                    process.stdout.write(`  ${agent.id.padEnd(8)} ${artifactPath}\n`);
+                }
+            }
+            process.stdout.write("  hooks    previously installed or --hooks (owned JSON always refreshed)\n");
+            process.stdout.write(`  state    ${statePath(homeDir)}\n`);
+        }
+        process.stdout.write("\n");
+        if (agents.length === 0) {
+            process.stdout.write("Nothing to migrate.\n");
+            return 0;
+        }
+        await applyAgentInstalls({
+            agents,
+            force,
+            hooks,
+            refreshInstalledHooks: true,
+            dryRun,
+            homeDir,
+        });
+        return 0;
+    });
+}
+//# sourceMappingURL=migrate.js.map

package/dist/commands/migrate.js.map

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

package/dist/commands/note/list.d.ts

@@ -0,0 +1,28 @@
+/** Options for {@link runNoteListWithOptions} (CLI parsing and tests). */
+export interface NoteListOptions {
+    /** Directory used to find the linked repo (default: `process.cwd()`). */
+    cwd?: string;
+    /** Max notes to print, newest first (default: 5). */
+    limit?: number;
+    /** Override home dir / `GROUNDER_HOME` (tests). */
+    homeDir?: string;
+}
+/**
+ * CLI entry for `grounder note list [--limit <n>]`.
+ * `--limit` must be a positive integer when provided.
+ * @returns Exit code (`0` on success, `1` on usage or config errors).
+ */
+export declare function runNoteList(argv: string[]): Promise<number>;
+/**
+ * Resolves the linked project, lists recent notes under `notes/` (newest first).
+ * Prints a count header (blank line after when non-empty), then each note as a
+ * numbered two-line block — `N. ` + full filename stem (including any date
+ * prefix), then the indented absolute path — separated by a blank line. The
+ * title line ends with two trailing spaces (a Markdown hard line break) so
+ * agents can relay stdout into chat and keep title and path on separate
+ * rendered lines. When `notes/` is empty, prints `No notes.` only. Same
+ * vault/link prerequisites as `grounder note`.
+ * @returns Exit code (`0` on success, `1` when vault/link is missing).
+ */
+export declare function runNoteListWithOptions(options?: NoteListOptions): Promise<number>;
+//# sourceMappingURL=list.d.ts.map

package/dist/commands/note/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/commands/note/list.ts"],"names":[],"mappings":"AAUA,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AASD;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAgCjE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CAa3F"}

package/dist/commands/note/list.js

@@ -0,0 +1,72 @@
+import { withHomeDir } from "../../connector/home.js";
+import { resolveNotesDir } from "../../connector/vault.js";
+import { helpExitCode } from "../../help.js";
+import { parseArgs } from "../../util/parse-args.js";
+import { listNotes } from "../../vault/list-notes.js";
+import { writeVaultItemList } from "../output.js";
+import { requireLinkedProject } from "../require-linked.js";
+const DEFAULT_LIMIT = 5;
+const USAGE = "Usage: grounder note list [--limit <n>]\n";
+function usageError() {
+    process.stderr.write(USAGE);
+    return 1;
+}
+/**
+ * CLI entry for `grounder note list [--limit <n>]`.
+ * `--limit` must be a positive integer when provided.
+ * @returns Exit code (`0` on success, `1` on usage or config errors).
+ */
+export async function runNoteList(argv) {
+    const helpCode = helpExitCode(argv, "note list");
+    if (helpCode !== null) {
+        return helpCode;
+    }
+    const { positional, flags } = parseArgs(argv);
+    if (positional.length > 0) {
+        return usageError();
+    }
+    for (const key of flags.keys()) {
+        if (key !== "limit") {
+            return usageError();
+        }
+    }
+    const limitRaw = flags.get("limit");
+    let limit = DEFAULT_LIMIT;
+    if (limitRaw !== undefined) {
+        if (typeof limitRaw !== "string") {
+            return usageError();
+        }
+        const trimmed = limitRaw.trim();
+        const parsed = Number.parseInt(trimmed, 10);
+        if (!/^\d+$/.test(trimmed) || Number.isNaN(parsed) || parsed < 1) {
+            return usageError();
+        }
+        limit = parsed;
+    }
+    return runNoteListWithOptions({ limit });
+}
+/**
+ * Resolves the linked project, lists recent notes under `notes/` (newest first).
+ * Prints a count header (blank line after when non-empty), then each note as a
+ * numbered two-line block — `N. ` + full filename stem (including any date
+ * prefix), then the indented absolute path — separated by a blank line. The
+ * title line ends with two trailing spaces (a Markdown hard line break) so
+ * agents can relay stdout into chat and keep title and path on separate
+ * rendered lines. When `notes/` is empty, prints `No notes.` only. Same
+ * vault/link prerequisites as `grounder note`.
+ * @returns Exit code (`0` on success, `1` when vault/link is missing).
+ */
+export async function runNoteListWithOptions(options = {}) {
+    return withHomeDir(options.homeDir, async () => {
+        const linked = await requireLinkedProject(options.cwd ?? process.cwd());
+        if (!linked) {
+            return 1;
+        }
+        const limit = options.limit ?? DEFAULT_LIMIT;
+        const notesDir = resolveNotesDir(linked.home, linked.repo);
+        const paths = await listNotes(notesDir, { limit });
+        writeVaultItemList(paths, limit, { singular: "note", plural: "notes" });
+        return 0;
+    });
+}
+//# sourceMappingURL=list.js.map

package/dist/commands/note/list.js.map

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

package/dist/commands/note.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"note.d.ts","sourceRoot":"","sources":["../../src/commands/note.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAa7D;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAgB9E"}
+{"version":3,"file":"note.d.ts","sourceRoot":"","sources":["../../src/commands/note.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB7D;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAgB9E"}

package/dist/commands/note.js

@@ -1,13 +1,18 @@
 import { withHomeDir } from "../connector/home.js";
 import { resolveNotesDir } from "../connector/vault.js";
+import { helpExitCode } from "../help.js";
 import { flagString, parseArgs } from "../util/parse-args.js";
 import { writeNote } from "../vault/write-note.js";
 import { requireLinkedProject } from "./require-linked.js";
 export async function runNote(argv) {
+    const helpCode = helpExitCode(argv, "note");
+    if (helpCode !== null) {
+        return helpCode;
+    }
     const { positional, flags } = parseArgs(argv);
     const text = positional.join(" ").trim();
     if (!text) {
-        process.stderr.write("Usage: grounder note <text>\n");
+        process.stderr.write("Usage: grounder note <text> [--title <slug>]\n");
         return 1;
     }
     return runNoteWithOptions({

package/dist/commands/note.js.map

@@ -1 +1 @@
-{"version":3,"file":"note.js","sourceRoot":"","sources":["../../src/commands/note.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAU3D,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAc;IAC1C,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAEzC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACtD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,kBAAkB,CAAC;QACxB,IAAI;QACJ,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC;KAClC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAAoB;IAC3D,OAAO,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QAED,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3D,MAAM,WAAW,GAAG,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE;YAC1D,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,GAAG,EAAE,OAAO,CAAC,GAAG;SACjB,CAAC,CAAC;QAEH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,WAAW,IAAI,CAAC,CAAC;QAC/C,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"note.js","sourceRoot":"","sources":["../../src/commands/note.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAU3D,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAc;IAC1C,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5C,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAEzC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACvE,OAAO,CAAC,CAAC;IACX,CAAC;IAED,OAAO,kBAAkB,CAAC;QACxB,IAAI;QACJ,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC;KAClC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAAoB;IAC3D,OAAO,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QAED,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3D,MAAM,WAAW,GAAG,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE;YAC1D,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,GAAG,EAAE,OAAO,CAAC,GAAG;SACjB,CAAC,CAAC;QAEH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,WAAW,IAAI,CAAC,CAAC;QAC/C,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/commands/output.d.ts

@@ -0,0 +1,27 @@
+/** Shared checklist/snapshot formatting for `doctor` and `status`. */
+export declare function writeSection(title: string): void;
+/** Append a fix hint (` → cmd`), or empty when none. */
+export declare function fixArrow(fix?: string): string;
+/** Singular/plural labels for vault item list headers (`note`/`notes`, …). */
+export type VaultItemListNoun = {
+    singular: string;
+    plural: string;
+};
+/**
+ * Lead line for note/handoff/plan list stdout: truncation signal when
+ * `count === limit`, complete inventory when fewer, or empty-dir notice.
+ */
+export declare function formatVaultItemListHeader(count: number, limit: number, noun: VaultItemListNoun): string;
+/**
+ * Writes numbered title + absolute-path blocks (blank line between items).
+ * Each title line ends with two trailing spaces (a Markdown hard line break)
+ * so agents can relay stdout into chat and keep title and path on separate
+ * rendered lines.
+ */
+export declare function writeVaultItemListEntries(paths: readonly string[]): void;
+/**
+ * Count header + numbered title/path blocks for vault item lists.
+ * When `paths` is empty, prints only the empty-dir notice from the header.
+ */
+export declare function writeVaultItemList(paths: readonly string[], limit: number, noun: VaultItemListNoun): void;
+//# sourceMappingURL=output.d.ts.map

package/dist/commands/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/commands/output.ts"],"names":[],"mappings":"AAEA,sEAAsE;AAEtE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEhD;AAED,wDAAwD;AACxD,wBAAgB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,8EAA8E;AAC9E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAMF;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,iBAAiB,GACtB,MAAM,CASR;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CASxE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,iBAAiB,GACtB,IAAI,CAGN"}

package/dist/commands/output.js

@@ -0,0 +1,51 @@
+import path from "node:path";
+/** Shared checklist/snapshot formatting for `doctor` and `status`. */
+export function writeSection(title) {
+    process.stdout.write(`${title}\n`);
+}
+/** Append a fix hint (` → cmd`), or empty when none. */
+export function fixArrow(fix) {
+    return fix ? ` → ${fix}` : "";
+}
+function vaultItemNoun(count, noun) {
+    return count === 1 ? noun.singular : noun.plural;
+}
+/**
+ * Lead line for note/handoff/plan list stdout: truncation signal when
+ * `count === limit`, complete inventory when fewer, or empty-dir notice.
+ */
+export function formatVaultItemListHeader(count, limit, noun) {
+    if (count === 0) {
+        return `No ${noun.plural}.\n`;
+    }
+    const label = vaultItemNoun(count, noun);
+    if (count === limit) {
+        return `Most recent ${count} ${label} (there may be more):\n\n`;
+    }
+    return `All ${count} ${label}:\n\n`;
+}
+/**
+ * Writes numbered title + absolute-path blocks (blank line between items).
+ * Each title line ends with two trailing spaces (a Markdown hard line break)
+ * so agents can relay stdout into chat and keep title and path on separate
+ * rendered lines.
+ */
+export function writeVaultItemListEntries(paths) {
+    paths.forEach((filePath, index) => {
+        if (index > 0) {
+            process.stdout.write("\n");
+        }
+        const stem = path.basename(filePath, ".md");
+        // Two trailing spaces: Markdown hard break when stdout is relayed into chat.
+        process.stdout.write(`${index + 1}. ${stem}  \n  ${filePath}\n`);
+    });
+}
+/**
+ * Count header + numbered title/path blocks for vault item lists.
+ * When `paths` is empty, prints only the empty-dir notice from the header.
+ */
+export function writeVaultItemList(paths, limit, noun) {
+    process.stdout.write(formatVaultItemListHeader(paths.length, limit, noun));
+    writeVaultItemListEntries(paths);
+}
+//# sourceMappingURL=output.js.map

package/dist/commands/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/commands/output.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,sEAAsE;AAEtE,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,QAAQ,CAAC,GAAY;IACnC,OAAO,GAAG,CAAC,CAAC,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAChC,CAAC;AAQD,SAAS,aAAa,CAAC,KAAa,EAAE,IAAuB;IAC3D,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAa,EACb,KAAa,EACb,IAAuB;IAEvB,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;QAChB,OAAO,MAAM,IAAI,CAAC,MAAM,KAAK,CAAC;IAChC,CAAC;IACD,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACzC,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;QACpB,OAAO,eAAe,KAAK,IAAI,KAAK,2BAA2B,CAAC;IAClE,CAAC;IACD,OAAO,OAAO,KAAK,IAAI,KAAK,OAAO,CAAC;AACtC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAAwB;IAChE,KAAK,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE;QAChC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACd,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC5C,6EAA6E;QAC7E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,GAAG,CAAC,KAAK,IAAI,SAAS,QAAQ,IAAI,CAAC,CAAC;IACnE,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAwB,EACxB,KAAa,EACb,IAAuB;IAEvB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,yBAAyB,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;IAC3E,yBAAyB,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC"}

package/dist/commands/package-version-notice.d.ts

@@ -0,0 +1,18 @@
+import { type PackageVersionRelation } from "../util/semver.js";
+export interface PackageVersionNotice {
+    relation: Exclude<PackageVersionRelation, "match">;
+    /** Doctor check message (plain language; versions in parentheses). */
+    message: string;
+    /** Suggested fix action. */
+    fix: string;
+    /** One-line stderr banner (includes trailing newlines). */
+    banner: string;
+    /** `grounder status` value after the Package: label. */
+    status: string;
+}
+/**
+ * Plain-language notice when the running Grounder and the version recorded for
+ * this machine's configuration disagree.
+ */
+export declare function packageVersionNotice(running: string, recorded: string): PackageVersionNotice | null;
+//# sourceMappingURL=package-version-notice.d.ts.map

package/dist/commands/package-version-notice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-version-notice.d.ts","sourceRoot":"","sources":["../../src/commands/package-version-notice.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,sBAAsB,EAA0B,MAAM,mBAAmB,CAAC;AAKxF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,OAAO,CAAC,sBAAsB,EAAE,OAAO,CAAC,CAAC;IACnD,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,oBAAoB,GAAG,IAAI,CAiC7B"}