grounder 0.5.0 → 0.6.0

package/dist/commands/install-drift.d.ts

@@ -0,0 +1,34 @@
+import { type GrounderState } from "../connector/state.js";
+/**
+ * Cheap "would migrate change something" check for `peek`/`status`: no
+ * Cursor/Claude host-file I/O, just a package-local template render + hash
+ * per ledger-recorded agent, diffed against `state.json`'s `files` map, plus
+ * one ledger-only lookup for tombstoned legacy paths still on record.
+ * Scoped to agents already present in the ledger — a detected-but-never-set-up
+ * agent produces no drift here (see `desiredDrift`'s own scoping rule), so
+ * this never teases `migrate` forever with no command able to silence it.
+ *
+ * `ledgerFiles` is run through `ownedLedgerFiles()` first, same as
+ * `migrate`/`doctor`/`applyPlan()` — a stray key outside the adapter's
+ * `ownedPrefixes` (a hand-edited or corrupted `state.json` entry) is invisible
+ * to `reconcile()` and refused on apply, so counting it as drift here would
+ * nag `migrate` forever for a path `migrate` will never actually touch.
+ *
+ * A tombstoned path still present in the ledger's `files` map means `migrate`
+ * has something to retire (delete, forget, or a conflict needing `--force`) —
+ * checking that is a plain key lookup against data already in memory, not a
+ * disk read, so it stays as cheap as the hash diff above. Doctor's own
+ * `agent-*-legacy-commands` check is the one place that actually reads disk
+ * to tell delete/conflict/already-gone apart; this only answers "is migrate
+ * a no-op," which none of those three are.
+ *
+ * An owned ledger key that is neither desired nor tombstoned (a skill dropped
+ * from the current release with nobody remembering to tombstone the old path)
+ * is the same kind of drift: `reconcile()` never plans a non-desired ledger
+ * path as `noop`, so `migrate` always has something to do with it (forget it
+ * if already gone from disk, else delete/conflict). Same plain key-lookup
+ * cost as the tombstone check above — no disk read needed to know *that*
+ * there's drift, only to know which of forget/delete/conflict it'll be.
+ */
+export declare function installDriftDetected(state: GrounderState | null, homeDir?: string): Promise<boolean>;
+//# sourceMappingURL=install-drift.d.ts.map

package/dist/commands/install-drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-drift.d.ts","sourceRoot":"","sources":["../../src/commands/install-drift.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,aAAa,EAAsC,MAAM,uBAAuB,CAAC;AAI/F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,aAAa,GAAG,IAAI,EAC3B,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CAmClB"}

package/dist/commands/install-drift.js

@@ -0,0 +1,72 @@
+import { ALL_AGENTS, ownedLedgerFiles } from "../agents/index.js";
+import { ledgerFilesFor, recordedInvocation } from "../connector/state.js";
+import { desiredDrift } from "../reconcile/core.js";
+import { hashContent } from "../util/hash.js";
+/**
+ * Cheap "would migrate change something" check for `peek`/`status`: no
+ * Cursor/Claude host-file I/O, just a package-local template render + hash
+ * per ledger-recorded agent, diffed against `state.json`'s `files` map, plus
+ * one ledger-only lookup for tombstoned legacy paths still on record.
+ * Scoped to agents already present in the ledger — a detected-but-never-set-up
+ * agent produces no drift here (see `desiredDrift`'s own scoping rule), so
+ * this never teases `migrate` forever with no command able to silence it.
+ *
+ * `ledgerFiles` is run through `ownedLedgerFiles()` first, same as
+ * `migrate`/`doctor`/`applyPlan()` — a stray key outside the adapter's
+ * `ownedPrefixes` (a hand-edited or corrupted `state.json` entry) is invisible
+ * to `reconcile()` and refused on apply, so counting it as drift here would
+ * nag `migrate` forever for a path `migrate` will never actually touch.
+ *
+ * A tombstoned path still present in the ledger's `files` map means `migrate`
+ * has something to retire (delete, forget, or a conflict needing `--force`) —
+ * checking that is a plain key lookup against data already in memory, not a
+ * disk read, so it stays as cheap as the hash diff above. Doctor's own
+ * `agent-*-legacy-commands` check is the one place that actually reads disk
+ * to tell delete/conflict/already-gone apart; this only answers "is migrate
+ * a no-op," which none of those three are.
+ *
+ * An owned ledger key that is neither desired nor tombstoned (a skill dropped
+ * from the current release with nobody remembering to tombstone the old path)
+ * is the same kind of drift: `reconcile()` never plans a non-desired ledger
+ * path as `noop`, so `migrate` always has something to do with it (forget it
+ * if already gone from disk, else delete/conflict). Same plain key-lookup
+ * cost as the tombstone check above — no disk read needed to know *that*
+ * there's drift, only to know which of forget/delete/conflict it'll be.
+ */
+export async function installDriftDetected(state, homeDir) {
+    if (!state) {
+        return false;
+    }
+    for (const agent of ALL_AGENTS) {
+        const ledgerFiles = ownedLedgerFiles(agent, ledgerFilesFor(state, agent.id), homeDir);
+        if (!ledgerFiles) {
+            continue;
+        }
+        // Replay the invocation baked in at this agent's last real install
+        // instead of this process's own `process.execPath` — otherwise a
+        // checking process with a different interpreter path (e.g. an editor
+        // extension host vs. a terminal) would manufacture drift that isn't
+        // real. See docs/architecture/runtime-invocation.md's "Repair loop".
+        // Falls back to the live invocation for a ledger predating this field.
+        const desired = await agent.desiredArtifacts(homeDir, {
+            invocation: recordedInvocation(state, agent.id),
+        });
+        const desiredHashes = {};
+        for (const [p, content] of Object.entries(desired)) {
+            desiredHashes[p] = hashContent(content);
+        }
+        if (desiredDrift(desiredHashes, ledgerFiles).length > 0) {
+            return true;
+        }
+        const tombstonePaths = new Set(agent.tombstones(homeDir));
+        if ([...tombstonePaths].some((p) => p in ledgerFiles)) {
+            return true;
+        }
+        const desiredPaths = new Set(Object.keys(desiredHashes));
+        if (Object.keys(ledgerFiles).some((p) => !desiredPaths.has(p) && !tombstonePaths.has(p))) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=install-drift.js.map

package/dist/commands/install-drift.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-drift.js","sourceRoot":"","sources":["../../src/commands/install-drift.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAsB,cAAc,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC/F,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAA2B,EAC3B,OAAgB;IAEhB,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,KAAK,CAAC;IACf,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE,CAAC;QAC/B,MAAM,WAAW,GAAG,gBAAgB,CAAC,KAAK,EAAE,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;QACtF,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,SAAS;QACX,CAAC;QACD,mEAAmE;QACnE,iEAAiE;QACjE,qEAAqE;QACrE,oEAAoE;QACpE,qEAAqE;QACrE,uEAAuE;QACvE,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE;YACpD,UAAU,EAAE,kBAAkB,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC;SAChD,CAAC,CAAC;QACH,MAAM,aAAa,GAA2B,EAAE,CAAC;QACjD,KAAK,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACnD,aAAa,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;QACD,IAAI,YAAY,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC;QAC1D,IAAI,CAAC,GAAG,cAAc,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,WAAW,CAAC,EAAE,CAAC;YACtD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC;QACzD,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACzF,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/commands/migrate.d.ts

@@ -1,7 +1,10 @@
 import { type AgentAdapter } from "../agents/index.js";
+import { type GrounderState } from "../connector/state.js";
 export interface MigrateOptions {
     force?: boolean;
     hooks?: boolean;
+    /** Turn hooks off (sticky — removes the fragment, flips hooksEnabled false). */
+    noHooks?: boolean;
     dryRun?: boolean;
     homeDir?: string;
     /** Agent ids to migrate. Defaults to ledger keys, else auto-detect. */
@@ -14,10 +17,15 @@ export interface MigrateOptions {
  * 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.
+ * skipped with a stderr warning — same forward-compat idea as the version
+ * hard stop, but migrate can still refresh the agents it understands.
+ *
+ * Takes the already-read `state` rather than reading it itself — the caller
+ * has already read it once (and needs it again for the too-new guard and the
+ * trailing state row), so this stays pure lookup logic instead of a second
+ * read of the same file.
  */
-export declare function resolveMigrateAgents(explicitIds: string[] | undefined, homeDir?: string): Promise<AgentAdapter[]>;
+export declare function resolveMigrateAgents(explicitIds: string[] | undefined, state: GrounderState | null): 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

@@ -1 +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"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAA6B,MAAM,oBAAoB,CAAC;AAElF,OAAO,EACL,KAAK,aAAa,EAInB,MAAM,uBAAuB,CAAC;AAe/B,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gFAAgF;IAChF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EAAE,GAAG,SAAS,EACjC,KAAK,EAAE,aAAa,GAAG,IAAI,GAC1B,OAAO,CAAC,YAAY,EAAE,CAAC,CAkBzB;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAqBhE;AAED,wBAAsB,qBAAqB,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAuFzF"}

package/dist/commands/migrate.js

@@ -1,10 +1,12 @@
 import { ALL_AGENTS, resolveAgents } from "../agents/index.js";
 import { readHomeConfig, withHomeDir } from "../connector/home.js";
-import { assertAgentSchemasSupported, readGrounderState, statePath } from "../connector/state.js";
+import { ledgerVersionChanged, readGrounderState, statePath, } from "../connector/state.js";
 import { isUnsupportedSchemaError } from "../connector/unsupported-schema.js";
 import { helpExitCode } from "../help.js";
+import { VERSION } from "../index.js";
 import { flagBool, flagStrings, parseArgs } from "../util/parse-args.js";
-import { applyAgentInstalls } from "./apply-agent-installs.js";
+import { applyAgentInstalls } from "./apply.js";
+import { renderAgentErrors, renderModifiedNote, renderSummary, renderTable, rowsFromApplyResult, stateRow, } from "./render-artifact-table.js";
 /**
  * Resolve which agents to migrate:
  * 1. Explicit `--agent` ids (unknown ids still throw)
@@ -12,14 +14,18 @@ import { applyAgentInstalls } from "./apply-agent-installs.js";
  * 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.
+ * skipped with a stderr warning — same forward-compat idea as the version
+ * hard stop, but migrate can still refresh the agents it understands.
+ *
+ * Takes the already-read `state` rather than reading it itself — the caller
+ * has already read it once (and needs it again for the too-new guard and the
+ * trailing state row), so this stays pure lookup logic instead of a second
+ * read of the same file.
  */
-export async function resolveMigrateAgents(explicitIds, homeDir) {
+export async function resolveMigrateAgents(explicitIds, state) {
     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();
@@ -38,9 +44,16 @@ export async function runMigrate(argv) {
     }
     const { flags, repeated } = parseArgs(argv);
     const agents = flagStrings(repeated, "agent");
+    const hooks = flagBool(flags, "hooks");
+    const noHooks = flagBool(flags, "no-hooks");
+    if (hooks && noHooks) {
+        process.stderr.write("Cannot pass both --hooks and --no-hooks.\n");
+        return 1;
+    }
     return runMigrateWithOptions({
         force: flagBool(flags, "force", "f"),
-        hooks: flagBool(flags, "hooks"),
+        hooks,
+        noHooks,
         dryRun: flagBool(flags, "dry-run"),
         agents: agents.length > 0 ? agents : undefined,
     });
@@ -50,16 +63,21 @@ export async function runMigrateWithOptions(options = {}) {
         const homeDir = options.homeDir;
         const force = options.force ?? false;
         const hooks = options.hooks ?? false;
+        const noHooks = options.noHooks ?? false;
         const dryRun = options.dryRun ?? false;
         const home = await readHomeConfig();
         if (!home) {
             process.stderr.write("No home config found. Run `grounder setup <path>` first.\n");
             return 1;
         }
-        const agents = await resolveMigrateAgents(options.agents, homeDir);
+        // Read once, up front, inside this guard — `resolveMigrateAgents` used to
+        // trigger a second, unguarded read (migrate.ts:46 pre-refactor) that a
+        // too-new ledger threw through before this catch was ever reached.
+        let state;
+        let agents;
         try {
-            const state = await readGrounderState(homeDir);
-            assertAgentSchemasSupported(state, agents);
+            state = await readGrounderState(homeDir);
+            agents = await resolveMigrateAgents(options.agents, state);
         }
         catch (error) {
             if (isUnsupportedSchemaError(error)) {
@@ -69,34 +87,50 @@ export async function runMigrateWithOptions(options = {}) {
             throw error;
         }
         process.stdout.write(`Vault root: ${home.vaultRoot}\n`);
-        process.stdout.write("Refresh Grounder after an upgrade (slash commands/hooks; vault path unchanged).\n");
-        process.stdout.write(dryRun ? "Would refresh:\n" : "Will refresh:\n");
+        process.stdout.write("Refresh Grounder after an upgrade (skills/hooks; vault path unchanged).\n");
         if (agents.length === 0) {
-            process.stdout.write("  (no agents recorded or detected)\n");
+            process.stdout.write("No agents recorded or detected — nothing to migrate.\n" +
+                "Run `grounder setup` first, or pass --agent to target one explicitly.\n");
+            return 0;
         }
-        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`);
+        if (dryRun) {
+            process.stdout.write("Dry run — no files will be written.\n");
         }
         process.stdout.write("\n");
-        if (agents.length === 0) {
-            process.stdout.write("Nothing to migrate.\n");
-            return 0;
+        let applyResult;
+        try {
+            applyResult = await applyAgentInstalls({
+                agents,
+                force,
+                hooks,
+                noHooks,
+                refreshInstalledHooks: true,
+                dryRun,
+                homeDir,
+                grounderVersion: VERSION,
+            });
         }
-        await applyAgentInstalls({
-            agents,
-            force,
-            hooks,
-            refreshInstalledHooks: true,
-            dryRun,
-            homeDir,
-        });
-        return 0;
+        catch (error) {
+            if (isUnsupportedSchemaError(error)) {
+                process.stderr.write(`${error.message}\n`);
+                return 1;
+            }
+            throw error;
+        }
+        const rows = rowsFromApplyResult(applyResult);
+        // Computed once, by the same code, whether or not this is `--dry-run` —
+        // `applyAgentInstalls` decides "would this write change the ledger" from
+        // the reconciled plan itself, and only actually writes when it's real. So
+        // there's no separate prediction to keep in sync here: real and dry-run
+        // report the exact same thing for the exact same reason.
+        const ledgerChanged = applyResult.agents.some((a) => a.ledgerChanged) || ledgerVersionChanged(state, VERSION);
+        rows.push(stateRow(ledgerChanged, state, statePath(homeDir)));
+        renderTable(rows);
+        process.stdout.write("\n");
+        renderSummary(rows, dryRun);
+        renderModifiedNote(rows, "grounder migrate");
+        renderAgentErrors(applyResult);
+        return applyResult.agents.some((a) => a.error !== undefined) ? 1 : 0;
     });
 }
 //# sourceMappingURL=migrate.js.map

package/dist/commands/migrate.js.map

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

package/dist/commands/overview.d.ts

@@ -0,0 +1,33 @@
+/** Options for {@link runOverviewWithOptions} (CLI parsing and tests). */
+export interface OverviewOptions {
+    /** Directory used to find the linked repo (default: `process.cwd()`). */
+    cwd?: string;
+    /** Max recent titles to print per bucket (default: 3). */
+    limit?: number;
+    /**
+     * Agent relay: `[bucketRelativePath](fileUri)` on each title line (default:
+     * plain bucket-relative stem path).
+     */
+    markdown?: boolean;
+    /** Structured JSON payload instead of formatted text. Mutually exclusive with `markdown`. */
+    json?: boolean;
+    /** Override home dir / `GROUNDER_HOME` (tests). */
+    homeDir?: string;
+}
+/**
+ * CLI entry for `grounder overview [--limit <n>] [--markdown] [--json]`.
+ * `--limit` must be a positive integer when provided.
+ * @returns Exit code (`0` on success, `1` on usage or config errors).
+ */
+export declare function runOverview(argv: string[]): Promise<number>;
+/**
+ * Resolves the linked project, gathers a per-bucket count + capped recent
+ * titles across `notes/`, `logs/` (handoffs), and `plans/` — the same
+ * newest-first listings `note/handoff/plan list` use, in one call. `--json`
+ * items also include `mtimeMs` (the same on-disk mtime each lister already
+ * fetches to rank entries; see `listNotesDetailed` / `listHandoffsDetailed` /
+ * `listPlansDetailed`). Text and markdown stay title + path only.
+ * @returns Exit code (`0` on success, `1` when vault/link is missing).
+ */
+export declare function runOverviewWithOptions(options?: OverviewOptions): Promise<number>;
+//# sourceMappingURL=overview.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overview.d.ts","sourceRoot":"","sources":["../../src/commands/overview.ts"],"names":[],"mappings":"AAaA,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,6FAA6F;IAC7F,IAAI,CAAC,EAAE,OAAO,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,CAuCjE;AA6FD;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2C3F"}

package/dist/commands/overview.js

@@ -0,0 +1,150 @@
+import { withHomeDir } from "../connector/home.js";
+import { resolveLogsDir, resolveNotesDir, resolvePlansDir } from "../connector/vault.js";
+import { helpExitCode } from "../help.js";
+import { flagBool, parseArgs } from "../util/parse-args.js";
+import { toFileUri, vaultRelativePath } from "../util/path.js";
+import { listHandoffsDetailed } from "../vault/list-handoffs.js";
+import { listNotesDetailed } from "../vault/list-notes.js";
+import { listPlansDetailed } from "../vault/list-plans.js";
+import { writeSection, writeVaultItemListEntries } from "./output.js";
+import { requireLinkedProject } from "./require-linked.js";
+const DEFAULT_LIMIT = 3;
+const USAGE = "Usage: grounder overview [--limit <n>] [--markdown] [--json]\n";
+function usageError() {
+    process.stderr.write(USAGE);
+    return 1;
+}
+/**
+ * CLI entry for `grounder overview [--limit <n>] [--markdown] [--json]`.
+ * `--limit` must be a positive integer when provided.
+ * @returns Exit code (`0` on success, `1` on usage or config errors).
+ */
+export async function runOverview(argv) {
+    const helpCode = helpExitCode(argv, "overview");
+    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" && key !== "markdown" && key !== "json") {
+            return usageError();
+        }
+    }
+    const markdown = flagBool(flags, "markdown");
+    const json = flagBool(flags, "json");
+    if (markdown && json) {
+        process.stderr.write("Use only one of --markdown or --json.\n");
+        return 1;
+    }
+    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 runOverviewWithOptions({ limit, markdown, json });
+}
+/**
+ * Lists a bucket uncapped (each lister already builds this full sorted array
+ * internally before slicing, so this costs no extra traversal) and slices
+ * locally — giving `--json` an honest `total` instead of reporting the
+ * shown-count twice under different names.
+ */
+async function gatherBucket(dir, noun, title, limit, lister) {
+    const all = await lister(dir);
+    return { dir, noun, title, all, shown: all.slice(0, limit) };
+}
+function jsonBucket(bucket) {
+    return {
+        total: bucket.all.length,
+        count: bucket.shown.length,
+        truncated: bucket.all.length > bucket.shown.length,
+        items: bucket.shown.map((entry) => ({
+            path: entry.path,
+            relativePath: vaultRelativePath(bucket.dir, entry.path),
+            fileUri: toFileUri(entry.path),
+            mtimeMs: entry.mtimeMs,
+        })),
+    };
+}
+/**
+ * Header line for one bucket's text/markdown section. Unlike the shared
+ * `note`/`handoff`/`plan list` header (`writeVaultItemList`'s
+ * `count === limit` → "there may be more" guess), overview already has the
+ * true total for free (see {@link gatherBucket}), so it reports an exact
+ * "N of M" instead of a maybe — the `--markdown` skill path relays this
+ * straight to the agent, where an honest count matters more than terseness.
+ */
+function bucketHeader(bucket) {
+    const total = bucket.all.length;
+    const shown = bucket.shown.length;
+    if (total === 0) {
+        return `No ${bucket.noun.plural}.\n`;
+    }
+    if (shown === total) {
+        const label = total === 1 ? bucket.noun.singular : bucket.noun.plural;
+        return `All ${total} ${label}:\n\n`;
+    }
+    return `Most recent ${shown} of ${total} ${bucket.noun.plural}:\n\n`;
+}
+function writeTextOutput(buckets, markdown) {
+    buckets.forEach((bucket, index) => {
+        if (index > 0) {
+            process.stdout.write("\n");
+        }
+        writeSection(bucket.title);
+        process.stdout.write(bucketHeader(bucket));
+        writeVaultItemListEntries(bucket.shown.map((entry) => entry.path), { markdown, titleRootDir: bucket.dir });
+    });
+}
+function writeJsonOutput(buckets) {
+    const payload = {};
+    for (const bucket of buckets) {
+        payload[bucket.noun.plural] = jsonBucket(bucket);
+    }
+    process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+/**
+ * Resolves the linked project, gathers a per-bucket count + capped recent
+ * titles across `notes/`, `logs/` (handoffs), and `plans/` — the same
+ * newest-first listings `note/handoff/plan list` use, in one call. `--json`
+ * items also include `mtimeMs` (the same on-disk mtime each lister already
+ * fetches to rank entries; see `listNotesDetailed` / `listHandoffsDetailed` /
+ * `listPlansDetailed`). Text and markdown stay title + path only.
+ * @returns Exit code (`0` on success, `1` when vault/link is missing).
+ */
+export async function runOverviewWithOptions(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 logsDir = resolveLogsDir(linked.home, linked.repo);
+        const plansDir = resolvePlansDir(linked.home, linked.repo);
+        const buckets = await Promise.all([
+            gatherBucket(notesDir, { singular: "note", plural: "notes" }, "Notes", limit, listNotesDetailed),
+            gatherBucket(logsDir, { singular: "handoff", plural: "handoffs" }, "Handoffs", limit, listHandoffsDetailed),
+            gatherBucket(plansDir, { singular: "plan", plural: "plans" }, "Plans", limit, listPlansDetailed),
+        ]);
+        if (options.json) {
+            writeJsonOutput(buckets);
+        }
+        else {
+            writeTextOutput(buckets, options.markdown === true);
+        }
+        return 0;
+    });
+}
+//# sourceMappingURL=overview.js.map

package/dist/commands/overview.js.map

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

package/dist/commands/render-artifact-table.d.ts

@@ -0,0 +1,85 @@
+import type { ArtifactStatus } from "../agents/types.js";
+import type { GrounderState } from "../connector/state.js";
+import type { PlanAction, PlanEntry } from "../reconcile/core.js";
+import type { ApplyAgentInstallsResult } from "./apply.js";
+/** A row's plan status, independent of tense — "current" never changes wording; the
+ * others are rendered as an infinitive in a dry run and past tense in a real one. */
+export type RowStatus = "current" | "create" | "update" | "delete" | "forget" | "modified";
+export interface Row {
+    status: RowStatus;
+    target: string;
+    path: string;
+    /** Only meaningful when `status === "modified"` — what `--force` would do to this path. */
+    forceAction?: "overwrite" | "delete";
+}
+/** For hook/runtime rows, still reported via the old imperative `ArtifactStatus` shape. */
+export declare function toRowStatus(status: ArtifactStatus): RowStatus;
+/**
+ * Whole-file artifact rows come straight from the reconciler's own plan
+ * vocabulary. `forget` gets its own status, distinct from `noop`'s
+ * "current" — a forget entry always changes `state.json` (see
+ * `planChangesLedger`), even though it never touches the file itself, so
+ * folding it into "current"/"unchanged" would hide the one row that explains
+ * why the trailing state row says "updated".
+ */
+export declare function rowStatusFromPlanAction(action: PlanAction): RowStatus;
+export declare function rowFromPlanEntry(target: string, entry: PlanEntry): Row;
+export declare const VERB: Record<RowStatus, {
+    dry: string;
+    real: string;
+}>;
+/**
+ * Table cell label per status — the same word in dry-run and real, so the
+ * table asserts one outcome vocabulary instead of reconjugating per row
+ * (matching `kubectl apply`'s created/configured/unchanged). Dry-run-ness is
+ * already announced once above the table and in the summary sentence, which
+ * keeps its own tense (`VERB` above) since "would create" is a sentence
+ * construction, not a table cell.
+ *
+ * `modified` is deliberately not "modified" here: that word would read as
+ * Grounder having modified the file, when the row means the opposite — a
+ * local edit was found and Grounder left it untouched. "conflict" names that
+ * outcome without implying an action was taken (see the STATUS header below,
+ * not ACTION, for the same reason).
+ *
+ * `forget` is deliberately not "unchanged" here, even though the file itself
+ * is untouched: the ledger entry for it is dropped, which is exactly the
+ * "updated" the trailing state row reports — collapsing it into "unchanged"
+ * would leave that state-row change unexplained by any visible row.
+ */
+export declare const TABLE_LABEL: Record<RowStatus, string>;
+/**
+ * Runtime + per-agent whole-file/hook rows shared by `setup` and `migrate` —
+ * both callers add the trailing state/ledger row on top since that isn't
+ * part of `applyAgentInstalls`'s result. Tombstone retirement is already
+ * folded into each agent's own `plan`, so it lands right after that agent's
+ * own artifact rows with no separate grouping step needed.
+ */
+export declare function rowsFromApplyResult(applyResult: ApplyAgentInstallsResult): Row[];
+/**
+ * The trailing `state` row both `setup` and `migrate` append — same
+ * create/update/current rule either way, so the two callers can't drift on
+ * how a ledger write is reported. `ledgerChanged` is each caller's own
+ * computation; this only owns turning that bit plus prior-state nullness
+ * into a `Row`.
+ */
+export declare function stateRow(ledgerChanged: boolean, priorState: GrounderState | null, path: string): Row;
+export declare function plural(count: number, noun: string): string;
+export declare function renderTable(rows: Row[]): void;
+export declare function renderSummary(rows: Row[], dryRun: boolean): void;
+/**
+ * Per-agent hook failures `applyAgentInstalls` isolated (see
+ * `AgentApplyResult#error`) — printed after the table/summary so a failing
+ * agent's hook error doesn't obscure whether other agents (or this agent's
+ * own whole-file artifacts, already applied by this point) succeeded.
+ */
+export declare function renderAgentErrors(applyResult: ApplyAgentInstallsResult): void;
+/**
+ * @param forceCommand The command line (without `--force`) the reader should
+ * re-run to resolve conflicts. Both `setup` and `migrate` pass `"grounder
+ * migrate"` today — `setup --force` applies just as well, but pointing every
+ * conflict at one canonical command keeps the remediation message the same
+ * regardless of which command surfaced the conflict.
+ */
+export declare function renderModifiedNote(rows: Row[], forceCommand: string): void;
+//# sourceMappingURL=render-artifact-table.d.ts.map

package/dist/commands/render-artifact-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-artifact-table.d.ts","sourceRoot":"","sources":["../../src/commands/render-artifact-table.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE3D;qFACqF;AACrF,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE3F,MAAM,WAAW,GAAG;IAClB,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,WAAW,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC;CACtC;AAED,2FAA2F;AAC3F,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,CAS7D;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAerE;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,GAAG,CAOtE;AAED,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,SAAS,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAOjE,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAOjD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,wBAAwB,GAAG,GAAG,EAAE,CA8BhF;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,aAAa,EAAE,OAAO,EACtB,UAAU,EAAE,aAAa,GAAG,IAAI,EAChC,IAAI,EAAE,MAAM,GACX,GAAG,CAGL;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAW7C;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CA4DhE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,wBAAwB,GAAG,IAAI,CAa7E;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAuB1E"}