skillrepo 3.0.0 → 3.1.1

package/README.md

@@ -41,22 +41,24 @@ Requires Node.js 18 or later.
 
 ### `init` — first-run setup
 
-Validates your access key, detects installed IDEs, writes the MCP config,
-and runs the first library sync.
-
 ```sh
-skillrepo init [--key <key>] [--url <url>] [--yes] [--force] [--ide <list>] [--global] [--json]
+skillrepo init [--key <key>] [--url <url>] [--yes] [--force] [--ide <list>] [--global] [--json] [--no-session-sync]
 ```
 
+Validates your access key, detects installed IDEs, writes the MCP config,
+installs the Claude Code SessionStart hook (opt-in — see `session-sync`
+below), and runs the first library sync.
+
 | Flag | Description |
 |------|-------------|
 | `--key, -k <key>` | Access key. Falls back to `SKILLREPO_ACCESS_KEY` env var, then interactive prompt. |
 | `--url, -u <url>` | Server URL. Defaults to `https://skillrepo.dev`. Use for self-hosted. |
-| `--yes, -y` | Non-interactive. Skip all confirmation prompts. Required for CI. |
+| `--yes, -y` | Non-interactive. Skip all confirmation prompts. Required for CI. Installs the session-sync hook by default — pass `--no-session-sync` to opt out. |
 | `--force` | Re-prompt for a new key even if `~/.claude/skillrepo/config.json` is valid. |
 | `--ide <list>` | Comma-separated vendor override. One or more of `claude`, `cursor`, `windsurf`, `vscode`, or `all`. |
 | `--global` | Write skills to `~/.claude/skills/` (personal) instead of `.claude/skills/` (project). |
-| `--json` | Emit a structured JSON summary on success. |
+| `--no-session-sync` | Skip step 6 (SessionStart hook install). Works in both interactive and `--yes` modes. Use for CI scripts that bootstrap a project without ever starting a Claude Code session. |
+| `--json` | Emit a structured JSON summary on success. Includes a `sessionSync: { action, path }` block describing whether the hook was installed. |
 
 `init` is idempotent: re-running with a valid existing config re-runs
 detection + MCP merge + first sync without re-prompting for a key. If the
@@ -129,6 +131,72 @@ DELETEs from `/api/v1/library` and deletes the local directory. Requires
 a write-scoped access key. The local delete is immediate and does not
 wait for a follow-up sync.
 
+### `session-sync` — auto-sync on Claude Code session start
+
+```sh
+skillrepo session-sync enable [--global] [--json]
+skillrepo session-sync disable [--global] [--json]
+```
+
+Installs (or removes) a Claude Code [SessionStart hook](https://docs.claude.com/en/docs/claude-code/hooks) that calls `skillrepo update` every time you open a Claude Code session — keeping your library current without you remembering to sync manually. The hook lives in `.claude/settings.local.json` (per-developer, gitignored by default) and runs your existing globally-installed `skillrepo` binary.
+
+By default `skillrepo init` prompts you to install this hook. If you said no (or passed `--no-session-sync`), run `session-sync enable` later to turn it on.
+
+**Requires a stable global install.** The hook is skipped (with a clear warning) when `skillrepo init` is invoked via `npx`, because the npx cache path is transient and the baked-in hook command would break on the next cache eviction. Install globally with `npm install -g skillrepo` before running `session-sync enable`.
+
+**The hook cannot block your session.** The command it runs is `<path-to-skillrepo> update --session-hook 2>&1 [|| true]`. The `--session-hook` flag makes `update` exit 0 on every failure — network outage, revoked key, disk error, anything — and print a single-line failure message to your session. On POSIX systems the `|| true` shell backstop is appended as belt-and-suspenders; on Windows it's omitted because cmd.exe doesn't know the `true` builtin (the `--session-hook` flag's exit-0 contract is the primary defense regardless of platform). Session starts are never blocked by sync failures.
+
+**On 304 (nothing changed) the hook is silent.** You only see output when your library actually syncs or a failure happens. No "Syncing…" noise on every session.
+
+Flags:
+
+- `--global` — operates on `~/.claude/settings.local.json` so the hook fires in every Claude Code session across all projects on your machine.
+- `--json` — emit structured JSON with `action`, `path`, and `command` fields for scripting.
+
+### `uninstall` — remove SkillRepo from a project
+
+```sh
+skillrepo uninstall [--dry-run] [--yes] [--global] [--json]
+```
+
+Surgically removes every SkillRepo artifact from the current project:
+
+- `mcpServers.skillrepo` from `.mcp.json`, `.cursor/mcp.json`,
+  and `.vscode/mcp.json` (plus the matching `inputs` prompt in the
+  VS Code config)
+- `SKILLREPO_ACCESS_KEY=...` lines from `.env.local`
+- The SkillRepo section of `.gitignore`
+- The SkillRepo `SessionStart` hook from `.claude/settings.local.json`
+  (if present)
+- The `.claude/skills/` directory
+
+Non-SkillRepo entries in shared files are preserved. Runs offline — no
+server call required, so a revoked or missing access key is not a
+problem. Interactive by default: the command prints a full list of what
+will be removed and prompts for confirmation before touching anything.
+
+With `--global`, also removes:
+
+- `mcpServers.skillrepo` from `~/.codeium/windsurf/mcp_config.json`
+- The `~/.claude/skills/` global skill cache
+- The `~/.claude/skillrepo/` directory (stored credentials + sync cache)
+
+Flags:
+
+- `--dry-run` / `-n` — print what would be removed and exit without
+  touching any file.
+- `--yes` / `-y` — skip the confirmation prompt.
+- `--global` — also remove user-global state. By default the command
+  leaves your credential and other projects' integrations untouched.
+- `--json` — emit structured JSON instead of human output. The summary
+  includes `removed[]` and `errors[]` arrays suitable for scripting.
+
+The command is idempotent — a second run with nothing left to remove
+exits 0 and reports "Nothing to remove." If any artifact fails to
+remove (e.g. a file is read-only), the command continues processing
+the others, surfaces every error at the end, and exits with code 3
+(disk error).
+
 ## Configuration
 
 ### Credentials

package/bin/skillrepo.mjs

@@ -28,6 +28,8 @@ import { runAdd } from "../src/commands/add.mjs";
 import { runRemove } from "../src/commands/remove.mjs";
 import { runList } from "../src/commands/list.mjs";
 import { runSearch } from "../src/commands/search.mjs";
+import { runUninstall } from "../src/commands/uninstall.mjs";
+import { runSessionSync } from "../src/commands/session-sync.mjs";
 import { CliError, EXIT_OK, EXIT_VALIDATION } from "../src/lib/errors.mjs";
 
 // ── Command registry ────────────────────────────────────────────────────
@@ -75,6 +77,18 @@ const COMMANDS = {
     usage: "skillrepo search <query> [--limit <n>] [--json] [--semantic]",
     run: async (argv) => runSearch(argv),
   },
+  uninstall: {
+    description:
+      "Remove SkillRepo from this project (and optionally global state with --global)",
+    usage: "skillrepo uninstall [--dry-run] [--yes] [--global] [--json]",
+    run: async (argv) => runUninstall(argv),
+  },
+  "session-sync": {
+    description:
+      "Enable or disable the Claude Code SessionStart hook that auto-syncs your library",
+    usage: "skillrepo session-sync <enable|disable> [--global] [--json]",
+    run: async (argv) => runSessionSync(argv),
+  },
 };
 
 const COMMAND_NAMES = Object.keys(COMMANDS);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {

package/src/commands/init.mjs

@@ -1,5 +1,5 @@
 /**
- * `skillrepo init` (#673) — PR3b rewrite.
+ * `skillrepo init` (#673) — PR3b rewrite, v3.1.0 session-sync (#884).
  *
  * First-run command. Replaces the v2.0.0 init that consumed the
  * deprecated `/api/v1/setup` endpoint and wrote hook-delivery
@@ -10,8 +10,9 @@
  *   3. Write ~/.claude/skillrepo/config.json via config.mjs
  *   4. Detect installed IDEs (.claude/, .cursor/, .vscode/, ~/.codeium/windsurf/)
  *   5. Run MCP auto-merge for detected IDEs (user-confirmed unless --yes)
- *   6. Run the first library sync via sync.mjs
- *   7. Print summary
+ *   6. Install Claude Code SessionStart hook (v3.1.0 #884)
+ *   7. Run the first library sync via sync.mjs
+ *   8. Print summary
  *
  * Key differences from v2.0.0:
  *
@@ -42,11 +43,12 @@
 import { validateAccessKey } from "../lib/http.mjs";
 import { detectIdes, formatDetectedIdes } from "../lib/detect-ides.mjs";
 import { readConfig, writeConfig } from "../lib/config.mjs";
-import { resolveFlags, effectiveVendors } from "../lib/cli-config.mjs";
+import { resolveFlags, effectiveVendors, isNpxInvocation } from "../lib/cli-config.mjs";
 import { mergeMcpForVendors, printManualMcpInstructions } from "../lib/mcp-merge.mjs";
 import { runSync } from "../lib/sync.mjs";
 import { mergeEnvLocal } from "../lib/mergers/env-local.mjs";
 import { mergeGitignore } from "../lib/mergers/gitignore.mjs";
+import { mergeSessionHook } from "../lib/mergers/session-hook.mjs";
 import { resolveKeyFromEnvFiles } from "../lib/resolve-key.mjs";
 import {
   promptSecret,
@@ -141,7 +143,7 @@ export async function runInit(argv, io = {}) {
   const stdout = io.stdout ?? process.stdout;
   const stderr = io.stderr ?? process.stderr;
 
-  const { flags, yes, force } = parseInitFlags(argv);
+  const { flags, yes, force, noSessionSync } = parseInitFlags(argv);
 
   // In --json mode, suppress all step-progress output so stdout
   // carries only the final JSON blob.
@@ -150,7 +152,7 @@ export async function runInit(argv, io = {}) {
   p.header("SkillRepo Init");
 
   // ── Step 1: Collect credentials ───────────────────────────────
-  p.step(1, 6, "Credentials");
+  p.step(1, 7, "Credentials");
 
   // Try sources in priority: --key flag > --url flag > global
   // config > env vars > interactive prompt.
@@ -202,7 +204,7 @@ export async function runInit(argv, io = {}) {
   p.blank();
 
   // ── Step 2: Validate against the server ──────────────────────
-  p.step(2, 6, "Validating key");
+  p.step(2, 7, "Validating key");
   let accountCtx;
   try {
     accountCtx = await validateAccessKey(serverUrl, apiKey);
@@ -232,7 +234,7 @@ export async function runInit(argv, io = {}) {
   p.blank();
 
   // ── Step 3: Write global config ──────────────────────────────
-  p.step(3, 6, "Writing config");
+  p.step(3, 7, "Writing config");
   const configAction = writeConfig({
     apiKey,
     serverUrl,
@@ -290,7 +292,7 @@ export async function runInit(argv, io = {}) {
   p.blank();
 
   // ── Step 4: Detect IDEs ──────────────────────────────────────
-  p.step(4, 6, "Detecting IDEs");
+  p.step(4, 7, "Detecting IDEs");
 
   // The v2.0.0 CLI had a silent fallback to [claudeCode, cursor]
   // when nothing was detected. The v3.0.0 CLI removes that — the
@@ -343,7 +345,7 @@ export async function runInit(argv, io = {}) {
   p.blank();
 
   // ── Step 5: MCP auto-merge ───────────────────────────────────
-  p.step(5, 6, "Configuring MCP");
+  p.step(5, 7, "Configuring MCP");
   const mcpUrl = `${serverUrl}/api/mcp`;
   // In --json mode, pass a black-hole stdout to mergeMcpForVendors
   // so its per-vendor preview lines don't pollute the JSON output.
@@ -375,8 +377,103 @@ export async function runInit(argv, io = {}) {
   }
   p.blank();
 
-  // ── Step 6: First sync ───────────────────────────────────────
-  p.step(6, 6, "Pulling library");
+  // ── Step 6: Session sync (#884) ──────────────────────────────
+  //
+  // Install the Claude Code SessionStart hook so the user's library
+  // auto-syncs on every session start. Per the architect design in
+  // issue #884:
+  //   - Opt-in by default. Interactive mode prompts before installing.
+  //     `--yes` skips the prompt and installs. `--no-session-sync`
+  //     is the explicit opt-out for BOTH modes — CI bootstraps
+  //     without session sync by passing it.
+  //   - If `which skillrepo` fails (e.g. npx user without a global
+  //     install), we SKIP with a warning. Init continues — do not
+  //     abort for this.
+  //   - A failure writing the settings file is non-fatal: the
+  //     config, MCP, and first sync still run. Users can re-run
+  //     `skillrepo session-sync enable` later.
+  //   - **Skip entirely when Claude Code is not the target.** The
+  //     SessionStart hook is Claude Code-specific: it lives at
+  //     `.claude/settings.local.json` and is only read by Claude
+  //     Code's session-start machinery. A Cursor-only or
+  //     Windsurf-only user doesn't benefit from it and shouldn't
+  //     get a prompt for it. Cross-PR review (v3.1.0) flagged this
+  //     as a silent-useless-state bug: without the guard, the hook
+  //     file was written even for non-Claude projects. The only
+  //     "Claude Code is the target" signals are:
+  //       • `vendors` includes "claudeCode" (either explicit
+  //         `--ide claude` or detected `.claude/` directory), OR
+  //       • `--global` is passed (writes to
+  //         `~/.claude/settings.local.json`, which is explicitly
+  //         Claude Code's user-wide path).
+  //     Everything else → skip with a clear message.
+  //
+  // This step is INSERTED between MCP merge (step 5) and the first
+  // sync (step 7). Order matters — we need the config written
+  // (step 3) so the hook's `skillrepo update` calls find creds.
+  p.step(6, 7, "Session sync");
+  let sessionSyncAction = "skipped";
+  let sessionSyncPath = null;
+  const claudeTargeted =
+    Boolean(flags.global) ||
+    (Array.isArray(vendors) && vendors.includes("claudeCode"));
+  if (noSessionSync) {
+    p.warning("Session sync skipped (--no-session-sync).");
+    sessionSyncAction = "opted-out";
+  } else if (!claudeTargeted) {
+    // Non-Claude-Code target (e.g. `--ide cursor`) — the hook would
+    // never fire, so skip the prompt AND the install. This is the
+    // v3.1.0 cross-PR review fix.
+    p.warning(
+      "Session sync skipped: the SessionStart hook is Claude Code-specific " +
+        "and no Claude Code target was configured.",
+    );
+    sessionSyncAction = "not-applicable";
+  } else {
+    let proceed = true;
+    if (!yes) {
+      proceed = await confirm(
+        "Install Claude Code SessionStart hook so your library auto-syncs on every session start?",
+        true,
+      );
+    }
+    if (!proceed) {
+      p.warning(
+        "Session sync skipped. Run `skillrepo session-sync enable` to install it later.",
+      );
+      sessionSyncAction = "declined";
+    } else {
+      try {
+        const result = mergeSessionHook({ global: flags.global });
+        sessionSyncAction = result.action;
+        sessionSyncPath = result.path;
+        if (result.action === "installed") {
+          p.success(`SessionStart hook installed (${result.path})`);
+        } else if (result.action === "updated") {
+          p.success(`SessionStart hook updated (${result.path})`);
+        } else if (result.action === "unchanged") {
+          p.success(`SessionStart hook already installed (${result.path})`);
+        } else if (result.action === "skipped") {
+          // Binary not resolvable — the installer returned a reason.
+          p.warning(result.reason ?? "Session sync skipped.");
+        }
+      } catch (err) {
+        // Disk error (corrupt settings file, permissions). The
+        // other init steps already ran, so the config and MCP are
+        // still in place. Surface the error and continue to the
+        // first sync step — do NOT abort.
+        p.warning(
+          `Session sync failed: ${err?.message ?? String(err)}. ` +
+            `Run \`skillrepo session-sync enable\` after fixing the issue.`,
+        );
+        sessionSyncAction = "failed";
+      }
+    }
+  }
+  p.blank();
+
+  // ── Step 7: First sync ───────────────────────────────────────
+  p.step(7, 7, "Pulling library");
   let syncSummary;
   let syncFailedReason = null;
   try {
@@ -422,16 +519,46 @@ export async function runInit(argv, io = {}) {
       updated: 0,
       removed: 0,
       notModified: false,
+      // On a synthesized failure summary we genuinely don't know
+      // whether the sync WOULD have been full or delta — the network
+      // call never completed. Architect review (v3.1.1) flagged that
+      // emitting `fullSync: false` here is misleading for --json
+      // consumers: it looks like a legitimate "delta sync returned
+      // zero" signal. Using `null` makes the unknown-state
+      // explicit — any typed consumer must handle it separately
+      // from true/false. The always-present `sync.failureReason`
+      // field is still the authoritative "did the sync fail"
+      // indicator; fullSync is just additional context.
+      fullSync: null,
       syncedAt: new Date().toISOString(),
     };
   }
 
+  const zeroDeltas =
+    syncSummary.added + syncSummary.updated + syncSummary.removed === 0;
+
   if (syncFailedReason) {
     // The warning already printed; the step-summary success line
     // would be misleading, so we skip it. Any helpful "next steps"
     // is in the final `SkillRepo is ready` block.
-  } else if (syncSummary.notModified || syncSummary.added + syncSummary.updated + syncSummary.removed === 0) {
+  } else if (syncSummary.notModified) {
+    // 304 Not Modified — the client had the current ETag already.
+    // Definitively "up to date" regardless of whether the library
+    // is empty or populated.
+    p.success("Library is up to date.");
+  } else if (zeroDeltas && syncSummary.fullSync) {
+    // Full sync (no prior .last-sync state existed) with zero
+    // results — the account's library is genuinely empty.
     p.success("No skills in library yet (add some with `skillrepo add @owner/name`)");
+  } else if (zeroDeltas) {
+    // Delta sync with zero results — nothing changed since the
+    // last sync. Could be zero skills total, or N skills all
+    // unchanged. Without a full-sync roundtrip we can't tell, so
+    // the accurate phrasing is "no changes." Before this fix, the
+    // init step-7 message conflated this with the truly-empty
+    // case, which lied to any user who had skills but had already
+    // synced them on a prior run.
+    p.success("Library is up to date (no changes since last sync).");
   } else {
     p.success(
       `${syncSummary.added} added, ${syncSummary.updated} updated, ${syncSummary.removed} removed`,
@@ -457,6 +584,17 @@ export async function runInit(argv, io = {}) {
             skipped: skipped.map((r) => r.path),
             failed: failed.map((r) => ({ path: r.path, reason: r.reason })),
           },
+          // Session-sync block — action values:
+          //   "installed" | "updated" | "unchanged" (success states)
+          //   "opted-out" (--no-session-sync)
+          //   "declined" (user said no at the prompt)
+          //   "not-applicable" (no Claude Code target — e.g. `--ide cursor`)
+          //   "skipped" (binary not resolvable — reason in non-json path)
+          //   "failed" (disk error during install)
+          sessionSync: {
+            action: sessionSyncAction,
+            path: sessionSyncPath,
+          },
           // Sync block always shows the counts (zeroed on failure)
           // and adds `failureReason` when the first sync blew up —
           // downstream scripts can `.failureReason != null` to
@@ -473,10 +611,27 @@ export async function runInit(argv, io = {}) {
   }
 
   stdout.write("\n  ✓ SkillRepo is ready.\n\n");
+  // Pick the command prefix the user can actually run. If they
+  // invoked init via `npx skillrepo ...`, bare `skillrepo list` will
+  // fail with "command not found" — they need `npx skillrepo list`.
+  // Under a global install, the bare command is correct. We default
+  // to bare and add the `npx` prefix ONLY when we can detect the
+  // current invocation is npx.
+  const prefix = isNpxInvocation() ? "npx skillrepo" : "skillrepo";
   stdout.write("  Next steps:\n");
-  stdout.write("    • skillrepo list    — see what's in your library\n");
-  stdout.write("    • skillrepo search <query>  — find skills\n");
-  stdout.write("    • skillrepo add @owner/name — add a skill\n\n");
+  stdout.write(`    • ${prefix} list    — see what's in your library\n`);
+  stdout.write(`    • ${prefix} search <query>  — find skills\n`);
+  stdout.write(`    • ${prefix} add @owner/name — add a skill\n`);
+  if (isNpxInvocation()) {
+    // Soft recommendation: running under npx works but every command
+    // re-downloads the package. Global install is faster AND enables
+    // the session-sync feature (which requires a stable binary path).
+    stdout.write(
+      "\n  Tip: `npm install -g skillrepo` for faster commands " +
+        "and to enable session-start sync.\n",
+    );
+  }
+  stdout.write("\n");
 }
 
 /**
@@ -486,10 +641,12 @@ export async function runInit(argv, io = {}) {
 function parseInitFlags(argv) {
   // resolveFlags handles --key/--url/--global/--ide/--json and
   // rejects unknown flags via its acceptPositional callback. We
-  // intercept --yes and --force as "positional-shaped" flags via
-  // the callback so we don't need to pre-filter argv.
+  // intercept --yes, --force, and --no-session-sync as "positional-
+  // shaped" flags via the callback so we don't need to pre-filter
+  // argv.
   let yes = false;
   let force = false;
+  let noSessionSync = false;
 
   const flags = resolveFlags(argv, {
     requireAuth: false, // init MAY prompt for a key, so don't hard-fail
@@ -510,9 +667,17 @@ function parseInitFlags(argv) {
         force = true;
         return 1;
       }
+      if (arg === "--no-session-sync") {
+        // #884: explicit opt-out for BOTH interactive and --yes
+        // modes. CI scripts that bootstrap a project without ever
+        // starting a Claude Code session pass this to skip the hook
+        // installation entirely.
+        noSessionSync = true;
+        return 1;
+      }
       return false; // anything else is unknown
     },
   });
 
-  return { flags, yes, force };
+  return { flags, yes, force, noSessionSync };
 }

package/src/commands/remove.mjs

@@ -11,19 +11,14 @@
  * Why direct local delete instead of calling sync.mjs to process
  * the tombstone:
  *
- *   - The server's ETag computation does NOT currently factor in
- *     `libraryRemovals`, so a conditional sync after the DELETE
- *     would return 304 and the CLI would never see the tombstone.
- *     The CLI would leave the orphaned skill files on disk until
- *     some unrelated mutation bumps the ETag. This is documented
- *     in follow-up #875.
- *   - A direct local delete avoids that problem entirely. Since
- *     `remove` is called with a specific (owner, name) the CLI
- *     already knows exactly what to delete — there's no reason to
- *     go through a tombstone round-trip.
- *   - Cross-machine remove still works via the tombstone-on-server
- *     path (once #875 lands); `remove` just short-circuits the
- *     single-machine case.
+ *   - `remove` is called with a specific (owner, name), so the CLI
+ *     already knows exactly what to delete. Going through a full
+ *     sync round-trip to rediscover the tombstone is wasteful —
+ *     a direct unlink is the shortest correct path.
+ *   - Cross-machine remove propagation is handled by the sync
+ *     path: the ETag factors in `libraryRemovals` (fixed in #875)
+ *     so a conditional GET from another machine correctly
+ *     invalidates and returns the tombstone list.
  *
  * Idempotent semantics:
  *

package/src/commands/session-sync.mjs

@@ -0,0 +1,152 @@
+/**
+ * `skillrepo session-sync enable|disable` (#884).
+ *
+ * Thin command wrapper over the session-hook installer/remover in
+ * `src/lib/mergers/session-hook.mjs`. The command exists so users who
+ * want to toggle session-start sync WITHOUT re-running `skillrepo init`
+ * can do so with a single command. `init` calls the same underlying
+ * `mergeSessionHook` helper at its step 6.
+ *
+ * Usage:
+ *   skillrepo session-sync enable       — install the SessionStart hook
+ *   skillrepo session-sync disable      — remove it
+ *   skillrepo session-sync status       — print current state (future — not wired yet)
+ *
+ * Flags:
+ *   --global   Operate on ~/.claude/settings.local.json instead of the
+ *              project-local file. Mirrors `init --global` semantics.
+ *   --json     Emit structured JSON instead of human output.
+ *
+ * Exit codes:
+ *   0   success (installed, updated, unchanged, removed, or already disabled)
+ *   3   disk error (cannot read/write the settings file)
+ *   5   validation error (bad subcommand or flag combination)
+ *
+ * This command does NOT share the `update --session-hook` exit-0-on-
+ * errors contract. That contract exists specifically for the hook
+ * runner's startup path; when a user explicitly invokes
+ * `skillrepo session-sync enable` at the shell, they expect a
+ * non-zero exit on failure so their shell script knows something
+ * went wrong.
+ */
+
+import {
+  mergeSessionHook,
+  removeSessionHook,
+} from "../lib/mergers/session-hook.mjs";
+import { resolveFlags } from "../lib/cli-config.mjs";
+import { validationError } from "../lib/errors.mjs";
+
+/**
+ * Run `session-sync <subcommand>`. Throws CliError on failure; the
+ * dispatcher maps to the appropriate exit code.
+ *
+ * @param {string[]} argv
+ * @param {object} [io]
+ * @param {NodeJS.WritableStream} [io.stdout=process.stdout]
+ * @param {NodeJS.WritableStream} [io.stderr=process.stderr]
+ */
+export async function runSessionSync(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+
+  // ── Subcommand + flag parsing ───────────────────────────────────
+  //
+  // The subcommand is the first positional arg — "enable" or
+  // "disable". Use resolveFlags' acceptPositional callback to
+  // consume it (same pattern `get`, `search`, `add`, `remove` use
+  // for their positional args).
+  let subcommand = null;
+  const flags = resolveFlags(argv, {
+    requireAuth: false, // no server call — key not needed
+    skipConfig: true, // don't read the global config file
+    acceptPositional(arg) {
+      if (arg === "enable" || arg === "disable") {
+        if (subcommand !== null) {
+          throw validationError(
+            `session-sync accepts exactly one subcommand; got "${subcommand}" and "${arg}"`,
+          );
+        }
+        subcommand = arg;
+        return 1;
+      }
+      return false;
+    },
+  });
+
+  if (!subcommand) {
+    throw validationError(
+      "session-sync requires a subcommand (enable or disable).",
+      { hint: "Usage: skillrepo session-sync <enable|disable> [--global] [--json]" },
+    );
+  }
+
+  // ── Dispatch ────────────────────────────────────────────────────
+  if (subcommand === "enable") {
+    const result = mergeSessionHook({ global: flags.global });
+    if (flags.json) {
+      stdout.write(JSON.stringify(result, null, 2) + "\n");
+      return;
+    }
+    printEnableResult(result, stdout);
+    return;
+  }
+
+  if (subcommand === "disable") {
+    const result = removeSessionHook({ global: flags.global });
+    if (flags.json) {
+      stdout.write(JSON.stringify(result, null, 2) + "\n");
+      return;
+    }
+    printDisableResult(result, stdout);
+    return;
+  }
+
+  // Unreachable — the acceptPositional callback only accepts the
+  // two subcommands. Defensive throw so a future addition with a
+  // typo'd branch surfaces immediately.
+  throw validationError(`session-sync: unknown subcommand "${subcommand}"`);
+}
+
+function printEnableResult(result, out) {
+  if (result.action === "installed") {
+    out.write(`\n  ✓ SessionStart hook installed (${result.path})\n\n`);
+    return;
+  }
+  if (result.action === "updated") {
+    out.write(`\n  ✓ SessionStart hook updated (${result.path})\n\n`);
+    return;
+  }
+  if (result.action === "unchanged") {
+    out.write(`\n  ✓ SessionStart hook already installed (${result.path})\n\n`);
+    return;
+  }
+  // "skipped" — reason is set
+  out.write(`\n  ⚠ Could not enable session sync: ${result.reason}\n\n`);
+}
+
+function printDisableResult(result, out) {
+  if (result.action === "removed") {
+    out.write(`\n  ✓ SessionStart hook removed (${result.path})\n\n`);
+    return;
+  }
+  if (result.action === "unchanged") {
+    out.write(
+      `\n  ✓ SessionStart hook was not installed (${result.path}) — nothing to do.\n\n`,
+    );
+    return;
+  }
+  // "skipped" with an error — the settings file exists but couldn't
+  // be parsed. Both reviewers (round 2) flagged the observability
+  // gap: without this branch, a corrupt file looked identical to
+  // "file doesn't exist" in human output, and users couldn't tell
+  // the difference. The --json path already surfaces result.error
+  // via its full serialize, so only human mode was affected.
+  if (result.action === "skipped" && result.error) {
+    out.write(`\n  ⚠ ${result.error}\n\n`);
+    return;
+  }
+  // "skipped" without an error — file genuinely doesn't exist.
+  out.write(
+    `\n  ✓ No settings file at ${result.path} — session sync is not enabled.\n\n`,
+  );
+}