grounder 0.4.0 → 0.6.0

package/dist/help.js

@@ -1,8 +1,8 @@
 /** Help tiers and command metadata for the grounder CLI. */
-const GROUP_ORDER = ["Setup", "Write", "Paths", "Maintain", "Advanced"];
+const GROUP_ORDER = ["Setup", "Write", "Retrieve", "Paths", "Maintain", "Advanced"];
 const QUICKSTART = `Quickstart:
-  grounder vault init <path-to-your-vault>
-  grounder init
+  grounder setup <path-to-your-vault>
+  grounder link
   grounder note "my first note"
   grounder handoff $'# Handoff\\n\\n## Next\\n1. …'
   grounder handoff list
@@ -14,109 +14,139 @@ const QUICKSTART = `Quickstart:
  */
 export const COMMANDS = [
     {
-        id: "vault",
+        id: "setup",
         group: "Setup",
-        summary: "Vault setup commands",
-        listUsage: "vault init <path>",
-        usage: "grounder vault init <path> [--yes] [--force] [--agent <id>] [--hooks]",
-        list: false,
-        flags: `Subcommands:
-  vault init   Initialize vault + home config (once per machine)`,
-    },
-    {
-        id: "vault init",
-        group: "Setup",
-        summary: "Initialize vault + home config (once per machine)",
-        listUsage: "vault init <path>",
-        usage: "grounder vault init <path> [--yes] [--force] [--agent <id>] [--hooks]",
+        summary: "Connect to a markdown vault (once per machine)",
+        listUsage: "setup <path>",
+        usage: "grounder setup <path> [--yes] [--force] [--agent <id>] [--hooks] [--dry-run]",
         flags: `Flags:
   --yes          Skip confirmation prompts
   --force        Overwrite existing home config / generated files
   --agent <id>   Install for a specific agent (repeatable; default: auto-detect)
                  Supported: cursor, claude
-  --hooks        Also install session-start teaser hooks`,
+  --hooks        Also install session-start teaser hooks
+  --dry-run      Preview without writing`,
     },
     {
-        id: "init",
+        id: "link",
         group: "Setup",
-        summary: "Connect the current repo to your vault",
-        listUsage: "init",
-        usage: "grounder init [--yes] [--force] [--id <id>] [--vault <path>]",
+        summary: "Link this project inside the markdown vault (once per project)",
+        listUsage: "link",
+        usage: "grounder link [--yes] [--force] [--id <id>] [--vault <path>] [--dry-run]",
         flags: `Flags:
   --yes          Skip confirmation prompts
   --force        Overwrite an existing link marker
   --id <id>      Override detected project id
-  --vault <path> Override home vault root for this run`,
+  --vault <path> Override home vault root for this run
+  --dry-run      Preview without writing`,
     },
     {
         id: "note",
         group: "Write",
         summary: "Write a note to the vault",
         listUsage: "note <text>",
-        usage: "grounder note <text> [--title <slug>]",
+        usage: "grounder note <text> [--title <slug>] [--topics <list>]",
         flags: `Flags:
-  --title <slug> Short slug in filename (default: slugified first line)
+  --title <slug>  Short slug in filename (default: slugified first line)
+  --topics <list> Comma-separated keywords for search (e.g. "auth,jwt,session")
 
 Subcommands:
-  note list   Print recent notes (count header + numbered title/path, newest first)`,
+  note list   Print recent notes under notes/** (bucket-relative titles, newest first)`,
     },
     {
         id: "note list",
         group: "Write",
-        summary: "Print recent notes (count header + numbered title/path, newest first)",
+        summary: "Print recent notes under notes/** (bucket-relative titles, newest first)",
         listUsage: "note list",
-        usage: "grounder note list [--limit <n>]",
+        usage: "grounder note list [--limit <n>] [--markdown]",
         flags: `Flags:
-  --limit <n>  Max notes to print (default: 5)`,
+  --limit <n>  Max notes to print (default: 5)
+  --markdown   Agent relay: [bucketRelativePath](fileUri) title lines
+               (lists notes/**; nested e.g. feature/name.md)`,
     },
     {
         id: "handoff",
         group: "Write",
         summary: "Write a session handoff to vault logs/",
         listUsage: "handoff <text>",
-        usage: "grounder handoff <text> [--title <slug>]",
+        usage: "grounder handoff <text> [--title <slug>] [--topics <list>]",
         flags: `Flags:
-  --title <slug> Short slug in filename (default: slugified first line)
+  --title <slug>  Short slug in filename (default: slugified first line)
+  --topics <list> Comma-separated keywords for search (e.g. "auth,jwt,session")
 
 Subcommands:
-  handoff list   Print recent handoffs (count header + numbered title/path, newest first)
+  handoff list   Print recent handoffs under logs/** (bucket-relative titles, newest first)
   handoff peek   One-line latest-handoff teaser (session hooks)`,
     },
     {
         id: "handoff list",
         group: "Write",
-        summary: "Print recent handoffs (count header + numbered title/path, newest first)",
+        summary: "Print recent handoffs under logs/** (bucket-relative titles, newest first)",
         listUsage: "handoff list",
-        usage: "grounder handoff list [--limit <n>] [--head]",
+        usage: "grounder handoff list [--limit <n>] [--head] [--markdown]",
         flags: `Flags:
   --limit <n>  Max handoffs to print (default: 5)
   --head       Print only the newest usable path
-               (skips empty/unreadable files; same pick as handoff peek)`,
+               (skips empty/unreadable files; same pick as handoff peek)
+  --markdown   Agent relay: [bucketRelativePath](fileUri) title lines
+               (lists logs/**; nested e.g. feature/name.md; not with --head)`,
     },
     {
         id: "plan",
         group: "Write",
         summary: "Write/update a named plan under vault plans/",
         listUsage: "plan <text>",
-        usage: "grounder plan <text> (--title <name> [--force] | --path <file>)",
+        usage: "grounder plan <text> (--title <name> [--force] | --path <file>) [--topics <list>]",
         flags: `Flags:
-  --title <name> Required filename stem when creating/updating by name
-                 (trailing .md ok; sanitized, max 80 chars)
-  --path <file>  Update an existing plan by path (must resolve under this
-                 project's plans/; no title sanitization; always overwrites)
-  --force        With --title: overwrite an existing plan (preserves created)
+  --title <name>  Required filename stem when creating/updating by name
+                  (trailing .md ok; sanitized, max 80 chars)
+  --path <file>   Update an existing plan by path (must resolve under this
+                  project's plans/; no title sanitization; always overwrites)
+  --force         With --title: overwrite an existing plan (preserves created)
+  --topics <list> Comma-separated keywords for search (e.g. "caching,redis,api").
+                  On update, omit to keep existing topics.
 
 Subcommands:
-  plan list   Print recent plans (count header + numbered title/path, newest first)`,
+  plan list   Print recent plans under plans/** (bucket-relative titles, newest first)`,
     },
     {
         id: "plan list",
         group: "Write",
-        summary: "Print recent plans (count header + numbered title/path, newest first)",
+        summary: "Print recent plans under plans/** (bucket-relative titles, newest first)",
         listUsage: "plan list",
-        usage: "grounder plan list [--limit <n>]",
+        usage: "grounder plan list [--limit <n>] [--markdown]",
         flags: `Flags:
-  --limit <n>  Max plans to print (default: 5)`,
+  --limit <n>  Max plans to print (default: 5)
+  --markdown   Agent relay: [bucketRelativePath](fileUri) title lines
+               (lists plans/**; nested e.g. migration/cutover.md)`,
+    },
+    {
+        id: "search",
+        group: "Retrieve",
+        summary: "Search linked project vault for keywords (scoped retrieval)",
+        listUsage: "search <query>",
+        usage: "grounder search <query> [--terms <csv>] [--limit <n>] [--max-hits <n>] [--context <n>] [--since <date>] [--markdown] [--json]",
+        flags: `Flags:
+  --terms <csv>   Extra keyword variants (comma-separated)
+  --limit <n>     Max files to print (default: 10)
+  --max-hits <n>  Max stored line snippets per file during scan (default: 50)
+  --context <n>   Context lines around each snippet (default: 1)
+  --since <date>  Only files modified on or after date (YYYY-MM-DD local midnight, or Nd, e.g. 7d)
+  --after <date>  Alias for --since
+  --markdown      Agent relay: file:// links + fenced snippets
+  --json          Structured output (relativePath, fileUri, alsoMatchedHint per hit)`,
+    },
+    {
+        id: "overview",
+        group: "Retrieve",
+        summary: "Bird's-eye view: counts + recent titles across notes/handoffs/plans",
+        listUsage: "overview",
+        usage: "grounder overview [--limit <n>] [--markdown] [--json]",
+        flags: `Flags:
+  --limit <n>  Max recent titles to print per bucket (default: 3)
+  --markdown   Agent relay: [bucketRelativePath](fileUri) title lines
+  --json       Structured output (total, count, truncated, items per bucket;
+               each item includes mtimeMs)`,
     },
     {
         id: "path notes",
@@ -156,7 +186,9 @@ Subcommands:
         group: "Maintain",
         summary: "Snapshot of machine + project link + resolved paths",
         listUsage: "status",
-        usage: "grounder status",
+        usage: "grounder status [--json]",
+        flags: `Flags:
+  --json  Print a single-line JSON payload instead of formatted text`,
     },
     {
         id: "doctor",
@@ -172,13 +204,20 @@ Subcommands:
         group: "Maintain",
         summary: "Refresh agent install after upgrading grounder",
         listUsage: "migrate",
-        usage: "grounder migrate [--force] [--dry-run] [--agent <id>] [--hooks]",
+        usage: "grounder migrate [--force] [--dry-run] [--agent <id>] [--hooks | --no-hooks]",
         flags: `Flags:
-  --force      Overwrite command files you edited locally; also needed
-               once when upgrading from Grounder before 0.3
+  --force      Overwrite skill files you edited locally; also needed
+               once when upgrading from Grounder before 0.3. Also
+               deletes locally-edited pre-skill grounder-*.md command
+               files left over from before 0.6 (edits are not ported)
   --dry-run    Preview without writing
   --agent <id> Limit to a specific agent (repeatable)
-  --hooks      Also install hooks if not previously installed`,
+  --hooks      Also install hooks if not previously installed
+  --no-hooks   Turn hooks off and remove the installed hook entry
+               (sticky — a later plain migrate will not re-enable it)
+
+Also retires pre-skill grounder-*.md command files superseded by
+SKILL.md packaging (safe ones automatically; edited ones need --force).`,
     },
     {
         id: "handoff peek",
@@ -204,7 +243,7 @@ Examples:
   grounder help
   grounder help note
   grounder help handoff list
-  grounder help vault init`,
+  grounder help setup`,
     },
 ];
 /**
@@ -212,9 +251,8 @@ Examples:
  * `cli.ts` / `helpExitCode(...)` call sites — the invariant test locks this.
  */
 export const DISPATCHED_COMMAND_IDS = [
-    "vault",
-    "vault init",
-    "init",
+    "setup",
+    "link",
     "note",
     "note list",
     "handoff",
@@ -222,6 +260,8 @@ export const DISPATCHED_COMMAND_IDS = [
     "handoff peek",
     "plan",
     "plan list",
+    "search",
+    "overview",
     "path",
     "path notes",
     "path logs",
@@ -316,9 +356,10 @@ function formatFullCommandDetails() {
     }
     return blocks.join("\n\n");
 }
+const BANNER = "grounder — markdown-native memory for AI agents";
 /** Bare `grounder` / `-h` — short grouped synopsis (no flag encyclopedia). */
 export function printSynopsis() {
-    process.stdout.write(`grounder — connect git projects to Obsidian dev vaults for AI agents
+    process.stdout.write(`${BANNER}
 
 ${formatGroupedLists()}
 
@@ -335,7 +376,7 @@ ${QUICKSTART}
 }
 /** `--help` / `grounder help` with no args — one-shot reference for humans/agents. */
 export function printFullHelp() {
-    process.stdout.write(`grounder — connect git projects to Obsidian dev vaults for AI agents
+    process.stdout.write(`${BANNER}
 
 ${formatGroupedLists()}
 

package/dist/help.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAoB5D,MAAM,WAAW,GAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;AAErF,MAAM,UAAU,GAAG;;;;;;;qBAOE,CAAC;AAEtB;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAA2B;IAC9C;QACE,EAAE,EAAE,OAAO;QACX,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,sBAAsB;QAC/B,SAAS,EAAE,mBAAmB;QAC9B,KAAK,EAAE,uEAAuE;QAC9E,IAAI,EAAE,KAAK;QACX,KAAK,EAAE;iEACsD;KAC9D;IACD;QACE,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,mDAAmD;QAC5D,SAAS,EAAE,mBAAmB;QAC9B,KAAK,EAAE,uEAAuE;QAC9E,KAAK,EAAE;;;;;yDAK8C;KACtD;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,wCAAwC;QACjD,SAAS,EAAE,MAAM;QACjB,KAAK,EAAE,8DAA8D;QACrE,KAAK,EAAE;;;;uDAI4C;KACpD;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,2BAA2B;QACpC,SAAS,EAAE,aAAa;QACxB,KAAK,EAAE,uCAAuC;QAC9C,KAAK,EAAE;;;;oFAIyE;KACjF;IACD;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,uEAAuE;QAChF,SAAS,EAAE,WAAW;QACtB,KAAK,EAAE,kCAAkC;QACzC,KAAK,EAAE;+CACoC;KAC5C;IACD;QACE,EAAE,EAAE,SAAS;QACb,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,wCAAwC;QACjD,SAAS,EAAE,gBAAgB;QAC3B,KAAK,EAAE,0CAA0C;QACjD,KAAK,EAAE;;;;;gEAKqD;KAC7D;IACD;QACE,EAAE,EAAE,cAAc;QAClB,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,0EAA0E;QACnF,SAAS,EAAE,cAAc;QACzB,KAAK,EAAE,8CAA8C;QACrD,KAAK,EAAE;;;yEAG8D;KACtE;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,8CAA8C;QACvD,SAAS,EAAE,aAAa;QACxB,KAAK,EAAE,iEAAiE;QACxE,KAAK,EAAE;;;;;;;;oFAQyE;KACjF;IACD;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,uEAAuE;QAChF,SAAS,EAAE,WAAW;QACtB,KAAK,EAAE,kCAAkC;QACzC,KAAK,EAAE;+CACoC;KAC5C;IACD;QACE,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,gCAAgC;QACzC,SAAS,EAAE,YAAY;QACvB,KAAK,EAAE,qBAAqB;KAC7B;IACD;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,+BAA+B;QACxC,SAAS,EAAE,WAAW;QACtB,KAAK,EAAE,oBAAoB;KAC5B;IACD;QACE,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,gCAAgC;QACzC,SAAS,EAAE,YAAY;QACvB,KAAK,EAAE,qBAAqB;KAC7B;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,yDAAyD;QAClE,SAAS,EAAE,yBAAyB;QACpC,KAAK,EAAE,kCAAkC;QACzC,IAAI,EAAE,KAAK;QACX,KAAK,EAAE;;;8CAGmC;KAC3C;IACD;QACE,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,UAAU;QACjB,OAAO,EAAE,qDAAqD;QAC9D,SAAS,EAAE,QAAQ;QACnB,KAAK,EAAE,iBAAiB;KACzB;IACD;QACE,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,UAAU;QACjB,OAAO,EAAE,8BAA8B;QACvC,SAAS,EAAE,QAAQ;QACnB,KAAK,EAAE,4BAA4B;QACnC,KAAK,EAAE;2DACgD;KACxD;IACD;QACE,EAAE,EAAE,SAAS;QACb,KAAK,EAAE,UAAU;QACjB,OAAO,EAAE,gDAAgD;QACzD,SAAS,EAAE,SAAS;QACpB,KAAK,EAAE,iEAAiE;QACxE,KAAK,EAAE;;;;;8DAKmD;KAC3D;IACD;QACE,EAAE,EAAE,cAAc;QAClB,KAAK,EAAE,UAAU;QACjB,OAAO,EAAE,wDAAwD;QACjE,SAAS,EAAE,cAAc;QACzB,KAAK,EAAE,gCAAgC;QACvC,KAAK,EAAE;;yCAE8B;KACtC;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,UAAU;QACjB,OAAO,EAAE,0CAA0C;QACnD,SAAS,EAAE,kBAAkB;QAC7B,KAAK,EAAE,2BAA2B;QAClC,IAAI,EAAE,KAAK;QACX,KAAK,EAAE;;;;;;;2BAOgB;KACxB;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,OAAO;IACP,YAAY;IACZ,MAAM;IACN,MAAM;IACN,WAAW;IACX,SAAS;IACT,cAAc;IACd,cAAc;IACd,MAAM;IACN,WAAW;IACX,MAAM;IACN,YAAY;IACZ,WAAW;IACX,YAAY;IACZ,QAAQ;IACR,QAAQ;IACR,SAAS;IACT,MAAM;CACE,CAAC;AAEX,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAErD,+DAA+D;AAC/D,MAAM,UAAU,SAAS,CAAC,IAAc;IACtC,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,QAAQ,CAAC,CAAC;AAC9D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAkB;IACnD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,KAAK,IAAI,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC;QAChD,MAAM,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1B,IAAI,IAAI,EAAE,CAAC;YACT,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAiB;IAChD,IAAI,GAAG,GAAG,UAAU,IAAI,CAAC,KAAK,IAAI,CAAC;IACnC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,GAAG,IAAI,KAAK,IAAI,CAAC,OAAO,IAAI,CAAC;IAC/B,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,GAAG,IAAI,KAAK,IAAI,CAAC,KAAK,IAAI,CAAC;IAC7B,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,EAAU;IAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC1B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,gBAAgB,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,YAAY,CAAC,IAAc,EAAE,SAAiB;IAC5D,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,cAAc;IACrB,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,kBAAkB;IACzB,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IACjE,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;QACrD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,SAAS;QACX,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAC9E,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC7B,CAAC;AAED,SAAS,mBAAmB,CAAC,CAAc;IACzC,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,YAAY,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IACjD,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;QACZ,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,wBAAwB;IAC/B,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;QACrD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,SAAS;QACX,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,KAAK,IAAI,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC7B,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,aAAa;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;;EAErB,kBAAkB,EAAE;;;;;;;;;;EAUpB,UAAU;CACX,CAAC,CAAC;AACH,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,aAAa;IAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;;EAErB,kBAAkB,EAAE;;;;;;;;EAQpB,wBAAwB,EAAE;;EAE1B,UAAU;CACX,CAAC,CAAC;AACH,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,OAAO,CAAC,IAAc;IACpC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,aAAa,EAAE,CAAC;QAChB,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,IAAI,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACxE,OAAO,CAAC,CAAC;IACX,CAAC;IAED,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACvB,OAAO,CAAC,CAAC;AACX,CAAC"}
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"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"}

package/dist/reconcile/apply.d.ts

@@ -0,0 +1,31 @@
+import { type PlanEntry } from "./core.js";
+export interface ApplyPlanOptions {
+    agentId: string;
+    plan: readonly PlanEntry[];
+    /** Desired content for `create`/`update`/`noop` entries — path → rendered bytes. */
+    content: Record<string, string>;
+    grounderVersion: string;
+    homeDir?: string;
+    /**
+     * Directories this agent is allowed to write into / delete from (its own
+     * `AgentAdapter#ownedPrefixes`) — re-checked here via
+     * {@link isUnderOwnedPrefix}, not trusted solely from the caller, so a plan
+     * built from a stray/corrupted ledger entry can never be applied as a
+     * filesystem write outside the agent's own tree.
+     */
+    ownedPrefixes: readonly string[];
+}
+/**
+ * Execute a whole-file plan: write/delete each path, and persist that path's
+ * ledger hash right after its own file write succeeds (per-artifact, not
+ * batched) — a mid-run crash leaves the ledger consistent with whatever
+ * actually completed.
+ *
+ * Returns nothing: callers render their tables from the `PlanEntry[]` they
+ * passed in (see `commands/render-artifact-table.ts`'s
+ * `rowStatusFromPlanAction`), so a second per-path outcome vocabulary here
+ * would only be a chance for the two to disagree. Failure is a throw, not a
+ * status — every entry that doesn't throw did exactly what its action says.
+ */
+export declare function applyPlan(opts: ApplyPlanOptions): Promise<void>;
+//# sourceMappingURL=apply.d.ts.map

package/dist/reconcile/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/reconcile/apply.ts"],"names":[],"mappings":"AAIA,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAE/D,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;IAC3B,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkFrE"}

package/dist/reconcile/apply.js

@@ -0,0 +1,97 @@
+import { unlink } from "node:fs/promises";
+import { forgetLedgerFile, setLedgerFileHash } from "../connector/state.js";
+import { writeFileAtomic } from "../util/fs.js";
+import { hashContent } from "../util/hash.js";
+import { isUnderOwnedPrefix } from "./core.js";
+/**
+ * Execute a whole-file plan: write/delete each path, and persist that path's
+ * ledger hash right after its own file write succeeds (per-artifact, not
+ * batched) — a mid-run crash leaves the ledger consistent with whatever
+ * actually completed.
+ *
+ * Returns nothing: callers render their tables from the `PlanEntry[]` they
+ * passed in (see `commands/render-artifact-table.ts`'s
+ * `rowStatusFromPlanAction`), so a second per-path outcome vocabulary here
+ * would only be a chance for the two to disagree. Failure is a throw, not a
+ * status — every entry that doesn't throw did exactly what its action says.
+ */
+export async function applyPlan(opts) {
+    for (const entry of opts.plan) {
+        if ((entry.action === "create" || entry.action === "update" || entry.action === "delete") &&
+            !isUnderOwnedPrefix(entry.path, opts.ownedPrefixes)) {
+            throw new Error(`Refusing to ${entry.action} ${entry.path}: outside ${opts.agentId}'s owned prefixes`);
+        }
+        switch (entry.action) {
+            case "create":
+            case "update": {
+                const content = opts.content[entry.path];
+                if (content === undefined) {
+                    throw new Error(`No desired content for ${entry.path} (action: ${entry.action})`);
+                }
+                await writeFileAtomic(entry.path, content);
+                await setLedgerFileHash({
+                    agentId: opts.agentId,
+                    filePath: entry.path,
+                    hash: hashContent(content),
+                    grounderVersion: opts.grounderVersion,
+                    homeDir: opts.homeDir,
+                });
+                break;
+            }
+            case "noop": {
+                // A desired path already matching on disk — hydrate the ledger hash
+                // when it wasn't recorded yet (or recorded stale), so a manually
+                // correct file becomes safely Grounder-managed going forward.
+                const content = opts.content[entry.path];
+                if (content !== undefined) {
+                    await setLedgerFileHash({
+                        agentId: opts.agentId,
+                        filePath: entry.path,
+                        hash: hashContent(content),
+                        grounderVersion: opts.grounderVersion,
+                        homeDir: opts.homeDir,
+                    });
+                }
+                break;
+            }
+            case "delete": {
+                try {
+                    await unlink(entry.path);
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT") {
+                        // A real failure (EACCES, EISDIR, …) — propagate rather than
+                        // forgetting the ledger hash for a file that's still on disk;
+                        // swallowing it here would leave the ledger and disk permanently
+                        // disagreeing, with no way for a future run to notice and retry.
+                        throw error;
+                    }
+                }
+                await forgetLedgerFile({
+                    agentId: opts.agentId,
+                    filePath: entry.path,
+                    grounderVersion: opts.grounderVersion,
+                    homeDir: opts.homeDir,
+                });
+                break;
+            }
+            case "forget": {
+                // Already gone from disk, but the ledger still holds a stale hash
+                // (removed outside `migrate`) — drop it so it doesn't linger forever.
+                await forgetLedgerFile({
+                    agentId: opts.agentId,
+                    filePath: entry.path,
+                    grounderVersion: opts.grounderVersion,
+                    homeDir: opts.homeDir,
+                });
+                break;
+            }
+            case "conflict":
+                // Left alone on purpose — on-disk content Grounder can't confirm it
+                // wrote. `--force` is what turns this into an `update`/`delete`
+                // upstream in `reconcile()`, so there is nothing to do here.
+                break;
+        }
+    }
+}
+//# sourceMappingURL=apply.js.map

package/dist/reconcile/apply.js.map

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

package/dist/reconcile/core.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Pure reconciliation core — no I/O anywhere in this file.
+ *
+ * Two shapes, per the design: {@link desiredDrift} answers "would migrate
+ * change something" cheaply (ledger vs. rendered template hashes only, no
+ * disk read) for `peek`/`status`; {@link reconcile} is the full three-way
+ * (desired vs. ledger vs. on-disk) plan `setup`/`migrate`/`doctor` execute or
+ * preview. Modeled on chezmoi's source/destination/target state and dpkg's
+ * old-pristine/new-pristine/on-disk compare.
+ */
+/**
+ * True when `filePath` sits under one of `prefixes` (a directory, matched
+ * exactly or via a `prefix + separator` boundary — never a bare substring
+ * match, and never a `..`-segment escape). Callers use this to keep a
+ * ledger's extra/stray entries — a hand-edited or corrupted `state.json`,
+ * say — from ever being treated as delete candidates for paths outside the
+ * directories an adapter actually manages. Comparison is lexical
+ * (`path.resolve` + `path.relative`, no symlink following): both sides are
+ * resolved to absolute form first, so a `../` segment in `filePath` cannot
+ * walk back out of a prefix it superficially starts with.
+ * `reconcile()` itself stays agnostic to this (see its own docs); callers
+ * filter `ledger` before passing it in.
+ */
+export declare function isUnderOwnedPrefix(filePath: string, prefixes: readonly string[]): boolean;
+export type DriftKind = "create" | "update";
+export interface DriftEntry {
+    path: string;
+    kind: DriftKind;
+}
+/** One agent's last-applied manifest — path → hash of the bytes Grounder wrote. */
+export type LedgerManifest = Record<string, {
+    hash?: string;
+}>;
+/**
+ * Compare desired (rendered template) hashes against one agent's last-applied
+ * ledger manifest. No disk I/O — the caller renders + hashes templates, and
+ * passes in the ledger's `files` map already read from `state.json`.
+ *
+ * `ledger === undefined` means this agent has no ledger entry at all (never
+ * installed) — returns no drift. Scoping to ledger-recorded agents lives
+ * here, not in every caller: otherwise a detected-but-never-installed agent
+ * would tease `migrate` forever with no command able to silence it.
+ *
+ * Within a ledger-recorded agent, a desired path missing from its `files` map
+ * IS drift (`"create"`) — that's how a newly added skill file surfaces here.
+ */
+export declare function desiredDrift(desired: Record<string, string>, ledger: LedgerManifest | undefined): DriftEntry[];
+export type PlanAction = "create" | "update" | "delete" | "conflict" | "noop" | "forget";
+export interface PlanEntry {
+    path: string;
+    action: PlanAction;
+    /** Only set when `action === "conflict"` — which action `--force` would take. */
+    blockedAction?: "overwrite" | "delete";
+}
+/** path → on-disk content hash, `undefined` when the path does not exist. */
+export type DiskHashes = Record<string, string | undefined>;
+/**
+ * Full three-way reconcile for one agent's whole-file artifacts: desired
+ * (current templates) vs. ledger (last-applied) vs. disk (actual). Pure —
+ * `disk`/`ledger` are already-read snapshots, not live filesystem access.
+ *
+ * `tombstones` are extra "previously desired, no longer desired" paths
+ * (pre-skill command files, etc.) unioned into the retirement side of the
+ * diff even when the ledger never recorded them — the case a pure
+ * ledger-manifest diff is blind to (pre-hash-tracking installs).
+ *
+ * Safety: only ever call this for a known agent id whose `desired` this
+ * binary can actually compute — never for an unrecognized ledger entry,
+ * which would treat its entire recorded file set as delete candidates.
+ */
+export declare function reconcile(desired: Record<string, string>, tombstones: readonly string[], ledger: LedgerManifest | undefined, disk: DiskHashes, force: boolean): PlanEntry[];
+/**
+ * Would applying `plan` actually change the ledger? Pure — mirrors exactly
+ * what `applyPlan()`'s per-artifact writes do (each has its own no-op guard):
+ * `create`/`update`/`noop` only write when the recorded hash would actually
+ * change; `delete` only forgets an entry that exists; `forget` always writes
+ * (by construction it only exists when there's something to forget);
+ * `conflict` never touches the ledger. Used so `--dry-run` and a real run
+ * predict/report the exact same thing for the exact same reason.
+ */
+export declare function planChangesLedger(plan: readonly PlanEntry[], ledger: LedgerManifest | undefined, desired: Record<string, string>): boolean;
+//# sourceMappingURL=core.d.ts.map

package/dist/reconcile/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/reconcile/core.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAezF;AAED,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE5C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,mFAAmF;AACnF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,MAAM,EAAE,cAAc,GAAG,SAAS,GACjC,UAAU,EAAE,CAcd;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEzF,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;IACnB,iFAAiF;IACjF,aAAa,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC;CACxC;AAED,6EAA6E;AAC7E,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,OAAO,GACb,SAAS,EAAE,CA4Cb;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,SAAS,EAAE,EAC1B,MAAM,EAAE,cAAc,GAAG,SAAS,EAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,OAAO,CAyBT"}