grounder 0.5.0 → 0.6.0

package/README.md

@@ -7,7 +7,7 @@ Session summaries, plans, and notes in files you own.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/andrej-kolic/grounder/main/docs/assets/what-dark.svg">
-  <img alt="Grounder connects Cursor, Claude Code, and more agents to one markdown vault through slash commands and the CLI. The vault is a folder tree: 10-Projects/your-project/ containing plans (updated across sessions), notes (always a new file), and logs (saved session summaries). Caption: Any agent. One vault. Only when you ask." src="https://raw.githubusercontent.com/andrej-kolic/grounder/main/docs/assets/what.svg">
+  <img alt="Grounder connects Cursor, Claude Code, and more agents to one markdown vault through skills and the CLI. The vault is a folder tree: 10-Projects/your-project/ containing plans (updated across sessions), notes (always a new file), and logs (saved session summaries). Caption: Any agent. One vault. Only when you ask." src="https://raw.githubusercontent.com/andrej-kolic/grounder/main/docs/assets/what.svg">
 </picture>
 
 <div>&nbsp;</div>
@@ -21,7 +21,7 @@ Session summaries, plans, and notes in files you own.
 directory. Because it's files instead of chat history, work started in Cursor can be
 picked up in Claude Code, weeks later, on a different machine.
 
-The daily loop is five slash commands — [examples](#examples) show what you type.
+The daily loop is five skills, typed as `/name` — [examples](#examples) show what you type.
 
 ## The problem
 
@@ -36,9 +36,9 @@ The daily loop is five slash commands — [examples](#examples) show what you ty
 - **Plans live, sessions accumulate** — a plan updates in place across sessions; notes and handoffs are dated files, kept to go back to. `search` ranks across all of them.
 - **Deliberate** — nothing is read or written until you run a command. No auto-capture, no RAG, no tokens spent otherwise.
 - **Follows you across machines** — the vault is just a folder, so git (or Syncthing, or Dropbox) is all the sync you need.
-- **Cursor and Claude Code today** — slash commands for both; more agents on the [roadmap](#roadmap).
+- **Cursor and Claude Code today** — skills for both; more agents on the [roadmap](#roadmap).
 
-**Requirements:** Node.js 18+ and a folder to keep the files in — an existing Obsidian
+**Requirements:** Node.js 22+ and a folder to keep the files in — an existing Obsidian
 vault, or an empty directory Grounder fills over time. Git is optional.
 
 ## Install
@@ -63,7 +63,7 @@ run it (e.g. "set up grounder"). Skip the global install with
 ## Quickstart
 
 ```bash
-# Once per machine — connect to a vault + install agent slash commands
+# Once per machine — connect to a vault + install agent skills
 grounder setup <path-to-your-vault> --hooks
 
 # Once per project folder
@@ -78,12 +78,12 @@ one-line reminder at session start when a saved session exists — see
 
 ## Daily use
 
-Work from the agent's chat. A typical loop starts by resuming the last saved session and
+Work from the agent's chat. A typical loop starts by recalling the last saved session and
 ends by saving a short summary.
 
-Anything after a slash command is an instruction, not file content. The agent follows
-it — writes a plan, saves a note, or searches the vault. `/grounder-task` and
-`/grounder-task-handoff` don't need text at all.
+Anything after the skill name is an instruction, not file content. The agent follows
+it — writes a plan, saves a note, or searches the vault. `/grounder-recall` and
+`/grounder-handoff` don't need text at all.
 
 ### Examples
 
@@ -91,22 +91,22 @@ A typical session:
 
 | You type | What it does |
 | -------- | ------------ |
-| `/grounder-task` | Resume the latest saved session |
+| `/grounder-recall` | Recall the latest saved session |
 | `/grounder-plan save insights from this session as an implementation plan with steps` | Write a named plan |
 | `/grounder-search decisions and discussions on token refresh` | Search the vault |
 | `/grounder-note explain why we rejected cookie sessions` | Save a new note |
-| `/grounder-task-handoff` | Save a short session summary |
+| `/grounder-handoff` | Save a short session summary |
 
-Later, update the living plan or resume a named session:
+Later, update the living plan or recall a named session:
 
 | You type | What it does |
 | -------- | ------------ |
 | `/grounder-plan update the auth rewrite plan — jwt validator is done` | Update an existing plan |
-| `/grounder-task resume the auth-middleware session` | Resume a specific saved session, not the latest |
+| `/grounder-recall the auth-middleware session` | Recall a specific saved session, not the latest |
 
 ### Demo
 
-![Daily-use session loop across the five slash commands](https://raw.githubusercontent.com/andrej-kolic/grounder/main/packages/demo-casts/out/readme.gif)
+![Daily-use session loop across the five skills](https://raw.githubusercontent.com/andrej-kolic/grounder/main/packages/demo-casts/out/readme.gif)
 
 ## How it works
 
@@ -133,7 +133,7 @@ Three things, and that's the whole model:
 `10-Projects/` is a common Obsidian vault convention, so Grounder slots into an existing vault instead
 of fighting it. A **handoff** is a saved session summary — what got done, what's next,
 what's blocked — and they live under `logs/` because they accumulate one per session.
-`/grounder-task` resumes the latest saved session by default, or an earlier one by name.
+`/grounder-recall` recalls the latest saved session by default, or an earlier one by name.
 
 Here's the living plan, `plans/auth-rewrite.md`:
 
@@ -163,7 +163,7 @@ Machine config, the link marker, and how commands find the project:
 
 ## Commands
 
-No agent, or want to write by hand? Each slash command has a matching CLI command.
+No agent, or want to write by hand? Each skill has a matching CLI command.
 Pass the file text (or search query) — not an instruction for the agent.
 
 ```bash
@@ -172,6 +172,7 @@ grounder note "Investigate auth middleware"               # always a new note
 grounder handoff $'# Handoff: ...\n\n## Next\n1. ...'     # saved session summary
 grounder search "token refresh"                           # find earlier documents on token refresh
 grounder plan list                                        # also: note list, handoff list
+grounder overview                                         # counts + recent titles, all three buckets
 grounder status                                           # am I wired up?
 grounder doctor                                           # why isn't this working?
 ```
@@ -184,11 +185,11 @@ Full flags and behavior: **[CLI reference](https://github.com/andrej-kolic/groun
 
 Those are instructions written once: stable rules about the project. Grounder stores
 what accumulates: what happened last session, what's next, the plan currently in flight.
-They're complements — `/grounder-task` reads the latest saved session *and* `AGENTS.md`.
+They're complements — `/grounder-recall` reads the latest saved session *and* `AGENTS.md`.
 
 ### Is this an MCP server?
 
-No. It's a CLI plus slash command files. Nothing is registered with the agent, nothing
+No. It's a CLI plus skill files. Nothing is registered with the agent, nothing
 runs in the background, and no tokens are spent until you type a command.
 
 ### Do I need Obsidian?
@@ -204,7 +205,7 @@ with the project.
 
 ### What does it put in my repo?
 
-Only `.grounder.json` — two lines, safe to commit. Slash commands go under `~/.cursor` and
+Only `.grounder.json` — two lines, safe to commit. Skill files go under `~/.cursor` and
 `~/.claude`; vault content stays outside the project tree entirely.
 
 ### Does it capture my conversations automatically?
@@ -222,7 +223,7 @@ No. Nothing is written or loaded unless you ask. That's the point.
 ## Roadmap
 
 - **Support for Copilot, Codex, and other popular agents** — expand beyond Cursor and Claude Code so more agent tools can use the same vault memory.
-- **Auto-draft handoff on session end** (under consideration) — a hook that has the agent write the same structured Done/Next/Blockers checkpoint automatically, instead of requiring `/grounder-task-handoff`.
+- **Auto-draft handoff on session end** (under consideration) — a hook that has the agent write the same structured Done/Next/Blockers checkpoint automatically, instead of requiring `/grounder-handoff`.
 
 ## Development
 

package/dist/agents/claude.d.ts

@@ -1,7 +1,7 @@
 import type { AgentAdapter } from "./types.js";
 /**
  * Canonical SessionStart command for Claude Code (home-local runtime, not `npx`).
- * @see {@link peekHookCommand} — REVERT: restore `"npx grounder handoff peek"` and drop runtime.
+ * @see {@link peekHookCommand}
  */
 export declare function claudePeekHookCommand(homeDir?: string): string;
 /**
@@ -9,13 +9,13 @@ export declare function claudePeekHookCommand(homeDir?: string): string;
  * Excludes `resume` and `fork` — those sessions already carry prior context.
  */
 export declare const CLAUDE_SESSION_START_MATCHER = "startup|clear|compact";
-export declare function claudeCommandsDir(homeDir?: string): string;
+export declare function claudeSkillsDir(homeDir?: string): string;
 /** Absolute path to Claude Code's shared settings file (`~/.claude/settings.json`). */
 export declare function claudeSettingsJsonPath(homeDir?: string): string;
 export declare function grounderNoteCommandPath(homeDir?: string): string;
 export declare function grounderPlanCommandPath(homeDir?: string): string;
-export declare function grounderTaskHandoffCommandPath(homeDir?: string): string;
-export declare function grounderTaskCommandPath(homeDir?: string): string;
+export declare function grounderHandoffCommandPath(homeDir?: string): string;
+export declare function grounderRecallCommandPath(homeDir?: string): string;
 export declare function expectedArtifacts(homeDir?: string): string[];
 /** Paths of hook config this adapter touches — currently just `settings.json`. */
 export declare function expectedHookArtifacts(homeDir?: string): string[];

package/dist/agents/claude.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,YAAY,EAIb,MAAM,YAAY,CAAC;AAapB;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B,0BAA0B,CAAC;AAEpE,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,uFAAuF;AACvF,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,8BAA8B,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAE5D;AAED,kFAAkF;AAClF,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAEhE;AA+ND,eAAO,MAAM,MAAM,EAAE,YAwCpB,CAAC"}
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAA2C,MAAM,YAAY,CAAC;AAQxF;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B,0BAA0B,CAAC;AAEpE,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,uFAAuF;AACvF,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,0BAA0B,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAE5D;AAED,kFAAkF;AAClF,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAEhE;AAyPD,eAAO,MAAM,MAAM,EAAE,YAapB,CAAC"}

package/dist/agents/claude.js

@@ -1,23 +1,18 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import { resolveHomeDir } from "../connector/home.js";
 import { fileExists } from "../util/fs.js";
-import { mergeJsonFile } from "../util/merge-json.js";
-import { installHookRuntime, isGrounderPeekHookCommand, isHookRuntimeStale, peekHookCommand, } from "./hook-runtime.js";
-import { installCommandFile, recordCommandFileHashes } from "./install-command.js";
-const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
-const templateDir = path.join(pkgRoot, "templates", "agents", "claude", "commands");
-const COMMANDS = [
-    "grounder-note.md",
-    "grounder-search.md",
-    "grounder-plan.md",
-    "grounder-task-handoff.md",
-    "grounder-task.md",
-];
+import { homeSkillsLayout } from "./home-skills.js";
+import { readEventEntries, readHooksObject, removeMatchingEntries } from "./hook-fragment.js";
+import { installHookFragment, removeHookFragment } from "./hook-install.js";
+import { isGrounderPeekHookCommand, isHookRuntimeStale, peekHookCommand } from "./hook-runtime.js";
+/** Whole-file artifacts: `~/.claude/skills/` plus the retired `~/.claude/commands/`. */
+const layout = homeSkillsLayout({ id: "claude", agentDir: ".claude" });
+/** Hook event Grounder owns in `settings.json`. */
+const SESSION_START_EVENT = "SessionStart";
 /**
  * Canonical SessionStart command for Claude Code (home-local runtime, not `npx`).
- * @see {@link peekHookCommand} — REVERT: restore `"npx grounder handoff peek"` and drop runtime.
+ * @see {@link peekHookCommand}
  */
 export function claudePeekHookCommand(homeDir) {
     return peekHookCommand(homeDir);
@@ -27,27 +22,27 @@ export function claudePeekHookCommand(homeDir) {
  * Excludes `resume` and `fork` — those sessions already carry prior context.
  */
 export const CLAUDE_SESSION_START_MATCHER = "startup|clear|compact";
-export function claudeCommandsDir(homeDir) {
-    return path.join(resolveHomeDir(homeDir), ".claude", "commands");
+export function claudeSkillsDir(homeDir) {
+    return layout.skillsDir(homeDir);
 }
 /** Absolute path to Claude Code's shared settings file (`~/.claude/settings.json`). */
 export function claudeSettingsJsonPath(homeDir) {
     return path.join(resolveHomeDir(homeDir), ".claude", "settings.json");
 }
 export function grounderNoteCommandPath(homeDir) {
-    return path.join(claudeCommandsDir(homeDir), "grounder-note.md");
+    return layout.skillPath("grounder-note", homeDir);
 }
 export function grounderPlanCommandPath(homeDir) {
-    return path.join(claudeCommandsDir(homeDir), "grounder-plan.md");
+    return layout.skillPath("grounder-plan", homeDir);
 }
-export function grounderTaskHandoffCommandPath(homeDir) {
-    return path.join(claudeCommandsDir(homeDir), "grounder-task-handoff.md");
+export function grounderHandoffCommandPath(homeDir) {
+    return layout.skillPath("grounder-handoff", homeDir);
 }
-export function grounderTaskCommandPath(homeDir) {
-    return path.join(claudeCommandsDir(homeDir), "grounder-task.md");
+export function grounderRecallCommandPath(homeDir) {
+    return layout.skillPath("grounder-recall", homeDir);
 }
 export function expectedArtifacts(homeDir) {
-    return COMMANDS.map((filename) => path.join(claudeCommandsDir(homeDir), filename));
+    return layout.expectedArtifacts(homeDir);
 }
 /** Paths of hook config this adapter touches — currently just `settings.json`. */
 export function expectedHookArtifacts(homeDir) {
@@ -83,62 +78,86 @@ export function expectedHookArtifacts(homeDir) {
 //   - matcher group      → { matcher, hooks: Hook[] }
 //   - hook entry         → { type: "command", command: string }
 //
-// Idempotency: {@link isGrounderPeekHookCommand} (runtime path or legacy npx).
+// Idempotency / recognizer: {@link isGrounderPeekHookCommand} (runtime path
+// or legacy npx). Always-converge (Ansible `blockinfile` / Kubernetes
+// Server-Side Apply sole-owner model): every recognizer match — however many,
+// wherever they live across matcher groups — is removed and replaced with
+// exactly one canonical entry. No conflict / `--force` gate.
 // ---------------------------------------------------------------------------
 function peekHookEntry(homeDir) {
     return { type: "command", command: claudePeekHookCommand(homeDir) };
 }
-/**
- * Locate Grounder's peek command inside a `hooks.SessionStart` array.
- *
- * @param sessionStart - `settings.hooks.SessionStart` — array of matcher groups
- * @returns Indices into that array / the group's `hooks` array, or `null` if absent
- */
-function findPeekHook(sessionStart) {
-    for (let groupIdx = 0; groupIdx < sessionStart.length; groupIdx++) {
-        const group = sessionStart[groupIdx];
-        if (!group || typeof group !== "object" || Array.isArray(group)) {
-            continue;
-        }
-        const hooks = group.hooks;
-        if (!Array.isArray(hooks)) {
+function isClaudeHookEntry(hook) {
+    return (hook !== null &&
+        typeof hook === "object" &&
+        !Array.isArray(hook) &&
+        hook.type === "command" &&
+        isGrounderPeekHookCommand(hook.command));
+}
+function isMatcherGroup(group) {
+    return group !== null && typeof group === "object" && !Array.isArray(group);
+}
+/** Every Grounder hook entry across every matcher group, tagged with its group's matcher. */
+function findAllPeekHooksPlaced(sessionStart) {
+    const found = [];
+    for (const group of sessionStart) {
+        if (!isMatcherGroup(group) || !Array.isArray(group.hooks)) {
             continue;
         }
-        for (let hookIdx = 0; hookIdx < hooks.length; hookIdx++) {
-            const hook = hooks[hookIdx];
-            if (hook &&
-                typeof hook === "object" &&
-                !Array.isArray(hook) &&
-                isGrounderPeekHookCommand(hook.command)) {
-                return { groupIdx, hookIdx };
-            }
+        for (const hook of group.hooks.filter(isClaudeHookEntry)) {
+            found.push({ matcher: group.matcher, hook });
         }
     }
-    return null;
+    return found;
 }
-/** Whether `settings.json` already lists any Grounder peek command (for status labeling). */
-async function peekHookHadGrounderEntry(filePath) {
-    try {
-        const parsed = JSON.parse(await readFile(filePath, "utf8"));
-        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-            return false;
-        }
-        const hooks = parsed.hooks;
-        if (!hooks || typeof hooks !== "object" || Array.isArray(hooks)) {
-            return false;
+/** Every Grounder hook entry across every matcher group, flattened. */
+function findAllPeekHooks(sessionStart) {
+    return findAllPeekHooksPlaced(sessionStart).map((placed) => placed.hook);
+}
+/** Remove every Grounder hook entry from every matcher group's `hooks` array. */
+function removeAllPeekHooks(sessionStart) {
+    return sessionStart.map((group) => {
+        if (!isMatcherGroup(group) || !Array.isArray(group.hooks)) {
+            return group;
         }
-        const sessionStart = hooks.SessionStart;
-        return Array.isArray(sessionStart) && findPeekHook(sessionStart) !== null;
+        return { ...group, hooks: removeMatchingEntries(group.hooks, isClaudeHookEntry) };
+    });
+}
+function hasHooks(group) {
+    return isMatcherGroup(group) && Array.isArray(group.hooks) && group.hooks.length > 0;
+}
+/**
+ * Drop matcher groups that removal itself emptied — i.e. `next[i]` has no
+ * hooks left but `before[i]` (same index, pre-removal) did. A group that was
+ * already empty for reasons of its own (not something Grounder touched) is
+ * left alone: it isn't clutter Grounder created room for, so it isn't
+ * Grounder's call to delete it. `next` may be longer than `before` (a newly
+ * appended canonical group) — those extra entries always have hooks, so the
+ * length mismatch never reaches the `before[i]` lookup.
+ */
+function dropGroupsEmptiedByRemoval(before, next) {
+    return next.filter((group, i) => hasHooks(group) || !hasHooks(before[i]));
+}
+/** `hooks.SessionStart` from a settings.json on disk; `null` if absent or unreadable. */
+async function readSessionStart(filePath) {
+    try {
+        return readEventEntries(JSON.parse(await readFile(filePath, "utf8")), SESSION_START_EVENT);
     }
     catch {
-        return false;
+        return null;
     }
 }
+/** Whether `settings.json` already lists any Grounder peek command (for status labeling). */
+async function peekHookHadGrounderEntry(filePath) {
+    return findAllPeekHooks((await readSessionStart(filePath)) ?? []).length > 0;
+}
 /**
- * Skip only when the canonical command is already present *and* the runtime is
- * current for the running grounder version/source. Legacy `npx` entries or a
- * stale runtime (missing, or symlinked/copied from a different source) always
- * refresh — no `--force` required to migrate or to pick up an upgrade.
+ * Skip only when exactly one canonical entry is already present *under the
+ * canonical matcher group* ({@link CLAUDE_SESSION_START_MATCHER}) *and* the
+ * runtime is current for the running grounder version/source. Anything else
+ * — no entry, a legacy `npx` form, a drifted command, more than one match
+ * (however scattered across matcher groups), or the one match sitting under
+ * the wrong matcher — always converges.
  */
 async function peekHookUpToDate(filePath, homeDir) {
     if (!(await fileExists(filePath))) {
@@ -147,149 +166,109 @@ async function peekHookUpToDate(filePath, homeDir) {
     if (await isHookRuntimeStale(homeDir)) {
         return false;
     }
-    try {
-        const parsed = JSON.parse(await readFile(filePath, "utf8"));
-        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-            return false;
-        }
-        const hooks = parsed.hooks;
-        if (!hooks || typeof hooks !== "object" || Array.isArray(hooks)) {
-            return false;
-        }
-        const sessionStart = hooks.SessionStart;
-        if (!Array.isArray(sessionStart)) {
-            return false;
-        }
-        const found = findPeekHook(sessionStart);
-        if (!found) {
-            return false;
-        }
-        const group = sessionStart[found.groupIdx];
-        return group.hooks[found.hookIdx]?.command === claudePeekHookCommand(homeDir);
+    const sessionStart = await readSessionStart(filePath);
+    if (!sessionStart) {
+        return false;
     }
-    catch {
+    const placed = findAllPeekHooksPlaced(sessionStart);
+    if (placed.length !== 1 || placed[0].matcher !== CLAUDE_SESSION_START_MATCHER) {
         return false;
     }
+    return JSON.stringify(placed[0].hook) === JSON.stringify(peekHookEntry(homeDir));
 }
 /**
- * Deep-merge Grounder's SessionStart hook into an existing settings object.
+ * Converge Grounder's SessionStart hook into an existing settings object:
+ * remove every recognizer match from every matcher group, then insert
+ * exactly one canonical entry.
+ *
+ * Preserves every key except the nested path it owns. Insertion strategy
+ * (after removal, so this always runs against a Grounder-free tree):
+ * 1. A matcher group with `matcher === CLAUDE_SESSION_START_MATCHER` exists
+ *    (possibly the very one a match was just removed from) → append there.
+ * 2. Else → push a new matcher group with Grounder's hook.
  *
- * Preserves every key except the nested path it owns. Strategy:
- * 1. If a Grounder peek hook already exists (runtime or legacy npx) → replace in place.
- * 2. Else if a matcher group with `matcher === CLAUDE_SESSION_START_MATCHER` exists →
- *    append Grounder's hook to that group's `hooks` array.
- * 3. Else → push a new matcher group with Grounder's hook.
+ * Any matcher group the removal step emptied — e.g. a Grounder-only hook
+ * that lived under a non-canonical matcher — is dropped rather than left
+ * behind as clutter, matching {@link removeClaudeHooks}'s uninstall path.
  *
  * @param current - Parsed settings.json root (object). Other top-level keys untouched.
  * @param homeDir - Home override for the canonical command path
  * @returns New settings object with `hooks.SessionStart` updated
  */
 function mergeClaudeHooks(current, homeDir) {
-    const hooks = current.hooks && typeof current.hooks === "object" && !Array.isArray(current.hooks)
-        ? { ...current.hooks }
-        : {};
-    const sessionStart = Array.isArray(hooks.SessionStart) ? [...hooks.SessionStart] : [];
-    const found = findPeekHook(sessionStart);
+    const hooks = readHooksObject(current, claudeSettingsJsonPath(homeDir));
+    const raw = hooks[SESSION_START_EVENT];
+    const sessionStart = Array.isArray(raw) ? raw : [];
+    const cleaned = removeAllPeekHooks(sessionStart);
     const entry = peekHookEntry(homeDir);
-    if (found) {
-        // Path 1: refresh existing Grounder hook entry in place
-        const group = { ...sessionStart[found.groupIdx] };
+    const matcherIdx = cleaned.findIndex((group) => isMatcherGroup(group) && group.matcher === CLAUDE_SESSION_START_MATCHER);
+    let nextSessionStart;
+    if (matcherIdx >= 0) {
+        const group = { ...cleaned[matcherIdx] };
         const groupHooks = Array.isArray(group.hooks) ? [...group.hooks] : [];
-        groupHooks[found.hookIdx] = entry;
+        groupHooks.push(entry);
         group.hooks = groupHooks;
-        sessionStart[found.groupIdx] = group;
+        nextSessionStart = [...cleaned];
+        nextSessionStart[matcherIdx] = group;
     }
     else {
-        const matcherIdx = sessionStart.findIndex((group) => group &&
-            typeof group === "object" &&
-            !Array.isArray(group) &&
-            group.matcher === CLAUDE_SESSION_START_MATCHER);
-        if (matcherIdx >= 0) {
-            // Path 2: same matcher group already exists (e.g. user hooks) — append ours
-            const group = { ...sessionStart[matcherIdx] };
-            const groupHooks = Array.isArray(group.hooks) ? [...group.hooks] : [];
-            groupHooks.push(entry);
-            group.hooks = groupHooks;
-            sessionStart[matcherIdx] = group;
-        }
-        else {
-            // Path 3: no matching group — create the canonical SessionStart entry
-            sessionStart.push({
-                matcher: CLAUDE_SESSION_START_MATCHER,
-                hooks: [entry],
-            });
-        }
+        nextSessionStart = [...cleaned, { matcher: CLAUDE_SESSION_START_MATCHER, hooks: [entry] }];
     }
-    return { ...current, hooks: { ...hooks, SessionStart: sessionStart } };
+    nextSessionStart = dropGroupsEmptiedByRemoval(sessionStart, nextSessionStart);
+    return { ...current, hooks: { ...hooks, [SESSION_START_EVENT]: nextSessionStart } };
 }
 /**
- * Install (or refresh) Grounder's SessionStart teaser hook into `~/.claude/settings.json`.
- *
- * Also materializes `~/.grounder/runtime` (see {@link installHookRuntime}).
- *
- * Force semantics:
- * - Up-to-date canonical entry + fresh runtime and `force` false → skip
- * - Otherwise → refresh runtime + merge host config
- *
- * Unparseable settings.json: {@link mergeJsonFile} backs off and this throws (never clobbers).
+ * Remove every Grounder hook entry from every matcher group, touching
+ * nothing else, and drop a matcher group only when this removal is what left
+ * its `hooks` array empty (see {@link dropGroupsEmptiedByRemoval}) — clutter
+ * Grounder itself created room for, not a group that started empty for
+ * reasons of its own. Returns `current` verbatim when there's no Grounder
+ * entry to remove, so `mergeJsonFile` sees no change and leaves an unrelated
+ * `settings.json` untouched instead of reformatting it.
  */
-async function installHooks(opts) {
-    const dest = claudeSettingsJsonPath(opts.homeDir);
-    const upToDate = await peekHookUpToDate(dest, opts.homeDir);
-    if (upToDate && !opts.force) {
-        return { artifacts: { [dest]: "skipped" } };
-    }
-    if (opts.dryRun) {
-        const fileExisted = await fileExists(dest);
-        const hadGrounderEntry = fileExisted && (await peekHookHadGrounderEntry(dest));
-        const status = hadGrounderEntry ? "overwritten" : "created";
-        return { artifacts: { [dest]: status } };
-    }
-    await installHookRuntime({ homeDir: opts.homeDir });
-    const fileExisted = await fileExists(dest);
-    const hadGrounderEntry = fileExisted && (await peekHookHadGrounderEntry(dest));
-    const result = await mergeJsonFile(dest, (current) => mergeClaudeHooks(current, opts.homeDir));
-    if (!result.ok) {
-        throw new Error(result.message);
+function removeClaudeHooks(current) {
+    const hooks = current.hooks && typeof current.hooks === "object" && !Array.isArray(current.hooks)
+        ? current.hooks
+        : undefined;
+    const raw = hooks?.[SESSION_START_EVENT];
+    const sessionStart = Array.isArray(raw) ? raw : [];
+    if (findAllPeekHooks(sessionStart).length === 0) {
+        return current;
     }
-    const status = hadGrounderEntry ? "overwritten" : "created";
-    return { artifacts: { [dest]: status } };
+    const cleaned = dropGroupsEmptiedByRemoval(sessionStart, removeAllPeekHooks(sessionStart));
+    return { ...current, hooks: { ...hooks, [SESSION_START_EVENT]: cleaned } };
+}
+/**
+ * Install (or converge) Grounder's SessionStart teaser hook into `~/.claude/settings.json`.
+ * @see {@link installHookFragment} for the shared install/report scaffolding.
+ */
+async function installHooks(opts) {
+    return installHookFragment({
+        dest: claudeSettingsJsonPath(opts.homeDir),
+        isUpToDate: (filePath) => peekHookUpToDate(filePath, opts.homeDir),
+        hasGrounderEntry: peekHookHadGrounderEntry,
+        merge: (current) => mergeClaudeHooks(current, opts.homeDir),
+    }, opts);
+}
+/**
+ * Remove Grounder's SessionStart hook entry entirely (`--no-hooks`) — the
+ * opt-out must also remove the fragment, not just flip `hooksEnabled` false,
+ * or the session hook keeps firing and the tri-state's stickiness against
+ * the next plain `migrate` would have nothing to rest on.
+ */
+async function removeHooks(opts) {
+    return removeHookFragment(claudeSettingsJsonPath(opts.homeDir), removeClaudeHooks, opts);
 }
 export const claude = {
     id: "claude",
     name: "Claude Code",
-    commandsSchema: 3,
-    hooksSchema: 1,
-    async isInstalled() {
-        return fileExists(path.join(resolveHomeDir(), ".claude"));
-    },
+    isInstalled: layout.isInstalled,
     expectedArtifacts,
     expectedHookArtifacts,
-    async install(opts) {
-        const artifacts = {};
-        const files = {};
-        for (const filename of COMMANDS) {
-            const { dest, status, hash } = await installCommandFile({
-                ...opts,
-                agentId: claude.id,
-                templateDir,
-                commandsDir: claudeCommandsDir(opts.homeDir),
-                filename,
-            });
-            artifacts[dest] = status;
-            if (hash) {
-                files[dest] = { hash };
-            }
-        }
-        await recordCommandFileHashes({
-            agentId: claude.id,
-            commandsSchema: claude.commandsSchema,
-            files,
-            homeDir: opts.homeDir,
-            dryRun: opts.dryRun,
-        });
-        return { artifacts };
-    },
+    desiredArtifacts: layout.desiredArtifacts,
+    tombstones: layout.tombstones,
+    ownedPrefixes: layout.ownedPrefixes,
     installHooks,
+    removeHooks,
 };
 //# sourceMappingURL=claude.js.map