skillrepo 3.1.1 → 3.1.2

package/README.md

@@ -53,7 +53,7 @@ below), and runs the first library sync.
 |------|-------------|
 | `--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. Installs the session-sync hook by default — pass `--no-session-sync` to opt out. |
+| `--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. Under `npx`, this also auto-runs `npm install -g skillrepo@<this-version>` if no global install is present (so the session-sync hook can use the resulting absolute path). |
 | `--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). |
@@ -142,7 +142,9 @@ Installs (or removes) a Claude Code [SessionStart hook](https://docs.claude.com/
 
 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`.
+**Under `npx skillrepo init`, the CLI offers to install itself globally.** Session sync needs the binary at a stable absolute path (the `npx` cache path is transient and would break on the next cache eviction). Rather than skipping with a warning the way v3.1.1 did, v3.1.2 prompts during init: *"SkillRepo needs a global install to enable session sync. Install `skillrepo` globally now? (Y/n)"* — saying yes runs `npm install -g skillrepo@<version>` (pinned to the version you just invoked) and then installs the hook with the resulting absolute path. Under `--yes` the install runs without prompting; under `--no-session-sync` it's skipped entirely. If the install fails (permissions, network, registry), init prints actionable next-steps and continues; the rest of init still completes successfully.
+
+`skillrepo session-sync enable` does **not** auto-install — it's an explicit, deliberate command and assumes you already have a global install. If invoked under `npx` without a global install present, it returns a clear "install globally first" message rather than mutating your global package set.
 
 **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.
 

package/package.json

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

package/src/commands/init-session-sync.mjs

@@ -0,0 +1,307 @@
+/**
+ * `skillrepo init` step 6 — Claude Code SessionStart hook installation.
+ *
+ * Extracted from `init.mjs` for readability (#894 / v3.1.2). The
+ * v3.1.2 auto-install-global feature added five branches to what
+ * was a two-branch step in v3.1.0; nesting that inside init.mjs
+ * crossed the readability threshold. This module owns the entire
+ * decision tree and returns a flat result the caller integrates
+ * into the init summary + JSON output.
+ *
+ * ## Decision tree
+ *
+ *   noSessionSync                → "opted-out"   (no further action)
+ *   !claudeTargeted              → "not-applicable" (Claude-specific
+ *                                  hook would never fire)
+ *   non-npx install              → resolve via PATH, install hook
+ *   npx with EXISTING global     → use the global directly
+ *   npx without global, --yes    → auto-install global, install hook
+ *   npx without global, prompt   → ask first, then auto-install or
+ *                                  decline
+ *
+ * The auto-install branch runs `npm install -g skillrepo@<version>`
+ * itself so the user doesn't have to. v3.1.1 skipped the install
+ * with a "do it yourself" warning AFTER prompting for consent —
+ * the prompt-then-fail UX bug v3.1.2 fixes.
+ *
+ * ## Return shape
+ *
+ *   {
+ *     action: SessionSyncAction,           // see ./session-sync-actions.mjs
+ *     path: string | null,                 // settings.local.json display path
+ *     globalInstallActive: boolean,        // true when a stable global
+ *                                          // skillrepo binary is now on
+ *                                          // PATH (used by Next-Steps to
+ *                                          // suppress the now-stale
+ *                                          // "install globally" tip)
+ *   }
+ *
+ * ## Failure semantics
+ *
+ * Every recoverable failure (auto-install error, hook write error,
+ * version-read error) sets `action` to a descriptive enum value and
+ * returns. The caller (init.mjs) does NOT abort init — the rest of
+ * init has already succeeded and the user's library is on disk.
+ */
+
+import { mergeSessionHook } from "../lib/mergers/session-hook.mjs";
+import {
+  installSkillrepoGlobally,
+  resolveGlobalBinary,
+} from "../lib/global-install.mjs";
+import { getCliVersion } from "../lib/cli-version.mjs";
+import {
+  detectTransientRunner,
+  isTransientRunnerInvocation,
+  globalInstallCommandFor,
+} from "../lib/transient-runners.mjs";
+import { confirm as realConfirm } from "../lib/prompt.mjs";
+import { SessionSyncAction, isHookActive } from "./session-sync-actions.mjs";
+
+/**
+ * @typedef {Object} SessionSyncResult
+ * @property {string} action - One of the `SessionSyncAction` enum values.
+ * @property {string | null} path - Display path of the settings file
+ *           the hook was written to (or `null` if no write happened).
+ * @property {boolean} globalInstallActive - True if a stable global
+ *           skillrepo binary is on PATH after this step. Used by the
+ *           Next-Steps Tip block to decide whether to suggest
+ *           `npm install -g`.
+ */
+
+/**
+ * @typedef {Object} SessionSyncOptions
+ * @property {boolean} noSessionSync - True if `--no-session-sync`.
+ * @property {boolean} claudeTargeted - True if Claude Code is in the
+ *           vendor target list (via `--ide claude` or `--global` or
+ *           auto-detection).
+ * @property {boolean} yes - True if `--yes`.
+ * @property {boolean} json - True if `--json`. Affects spawn output
+ *           mode (silent vs inherit) so npm progress doesn't pollute
+ *           the JSON stdout.
+ * @property {boolean} global - True if `--global` (writes to
+ *           `~/.claude/settings.local.json`).
+ * @property {object} p - Printer (from init.mjs makePrinter).
+ * @property {object} [deps] - Test-only injection.
+ * @property {Function} [deps.spawn] - For installSkillrepoGlobally.
+ * @property {Function} [deps.getCliVersion] - For testing the version-
+ *           read failure recovery path (ESM exports can't be
+ *           monkey-patched).
+ * @property {Function} [deps.confirmFn] - For testing the interactive
+ *           prompt path. Default: real `confirm` from prompt.mjs.
+ */
+
+/**
+ * Run step 6. Always returns a result; never throws on user-recoverable
+ * failures. (`mergeSessionHook` may throw a disk error on a corrupt
+ * settings file — that's caught and surfaced as `action: "failed"`.)
+ *
+ * @param {SessionSyncOptions} options
+ * @returns {Promise<SessionSyncResult>}
+ */
+export async function installSessionSyncHook({
+  noSessionSync,
+  claudeTargeted,
+  yes,
+  json,
+  global,
+  p,
+  deps = {},
+}) {
+  if (noSessionSync) {
+    p.warning("Session sync skipped (--no-session-sync).");
+    return result(SessionSyncAction.OptedOut);
+  }
+
+  if (!claudeTargeted) {
+    p.warning(
+      "Session sync skipped: the SessionStart hook is Claude Code-specific " +
+        "and no Claude Code target was configured.",
+    );
+    return result(SessionSyncAction.NotApplicable);
+  }
+
+  const npxMode = isTransientRunnerInvocation();
+  if (!npxMode) {
+    return await runNonNpxBranch({ yes, global, p, deps });
+  }
+
+  // Transient-runner mode (npx/pnpx/yarn dlx/bunx). Decide between
+  // using a pre-existing global and
+  // offering to install one.
+  const existingGlobalBinary = resolveGlobalBinary();
+  if (existingGlobalBinary) {
+    return runUseExistingGlobalBranch({
+      binaryPath: existingGlobalBinary,
+      global,
+      p,
+    });
+  }
+  return await runAutoInstallBranch({ yes, json, global, p, deps });
+}
+
+// ── Branch implementations ───────────────────────────────────────────
+
+/**
+ * Non-npx case: stable install with skillrepo on PATH (or PATH
+ * misconfigured — handled gracefully). Existing v3.1.0/v3.1.1 path,
+ * preserved unchanged.
+ */
+async function runNonNpxBranch({ yes, global, p, deps }) {
+  const confirmFn = deps.confirmFn ?? realConfirm;
+  const proceed =
+    yes ||
+    (await confirmFn(
+      "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.",
+    );
+    return result(SessionSyncAction.Declined);
+  }
+  return tryMergeAndPrint({ global, p });
+}
+
+/**
+ * Pre-existing global on PATH (likely user installed manually before
+ * running `npx skillrepo init`). No install offer; use the existing
+ * binary directly via the binaryPath bypass.
+ */
+function runUseExistingGlobalBranch({ binaryPath, global, p }) {
+  p.success(
+    `Found global skillrepo at ${binaryPath} — using it for session sync.`,
+  );
+  const r = tryMergeAndPrint({ global, p, binaryPath });
+  // Pre-existing global IS active regardless of hook write outcome.
+  return { ...r, globalInstallActive: true };
+}
+
+/**
+ * Auto-install branch (the v3.1.2 fix): under npx with no global,
+ * install ourselves globally then install the hook with the resulting
+ * absolute path.
+ */
+async function runAutoInstallBranch({ yes, json, global, p, deps }) {
+  const confirmFn = deps.confirmFn ?? realConfirm;
+  const proceed =
+    yes ||
+    (await confirmFn(
+      "SkillRepo needs a global install to enable session sync. " +
+        "Install `skillrepo` globally now?",
+      true,
+    ));
+  if (!proceed) {
+    p.warning("Session sync skipped (declined).");
+    printManualSteps(p, detectTransientRunner());
+    return result(SessionSyncAction.Declined);
+  }
+
+  // `getCliVersion` throws on a corrupt CLI tarball. Catch so init
+  // doesn't crash on a condition that should never happen but might.
+  const getVersionFn = deps.getCliVersion ?? getCliVersion;
+  let version;
+  try {
+    version = getVersionFn();
+  } catch (err) {
+    p.warning(
+      `Could not determine CLI version for global install: ${err?.message ?? String(err)}.`,
+    );
+    printManualSteps(p, detectTransientRunner());
+    return result(SessionSyncAction.Skipped);
+  }
+
+  // p.success is silenced under --json; in human mode it tells the
+  // user what's about to happen before npm's stream begins.
+  p.success(`Running: npm install -g skillrepo@${version}`);
+  const installResult = await installSkillrepoGlobally({
+    version,
+    outputMode: json ? "silent" : "inherit",
+    spawn: deps.spawn,
+  });
+
+  if (!installResult.success) {
+    p.warning(
+      `Could not install skillrepo globally: ${installResult.error}`,
+    );
+    printManualSteps(p, detectTransientRunner());
+    return result(SessionSyncAction.Skipped);
+  }
+
+  p.success(
+    `Installed skillrepo@${version} globally (${installResult.binaryPath}).`,
+  );
+  const r = tryMergeAndPrint({
+    global,
+    p,
+    binaryPath: installResult.binaryPath,
+  });
+  return { ...r, globalInstallActive: true };
+}
+
+// ── Shared helpers ───────────────────────────────────────────────────
+
+/**
+ * Call `mergeSessionHook` and translate the result into a print +
+ * structured return. The optional `binaryPath` bypasses the
+ * `isNpxInvocation` guard inside `resolveSkillrepoBinary` (the v3.1.2
+ * contract that lets npx-mode init still install a hook with a stable
+ * absolute path).
+ */
+function tryMergeAndPrint({ global, p, binaryPath }) {
+  try {
+    const r = mergeSessionHook({ global, binaryPath });
+    if (r.action === SessionSyncAction.Installed) {
+      p.success(`SessionStart hook installed (${r.path})`);
+    } else if (r.action === SessionSyncAction.Updated) {
+      p.success(`SessionStart hook updated (${r.path})`);
+    } else if (r.action === SessionSyncAction.Unchanged) {
+      p.success(`SessionStart hook already installed (${r.path})`);
+    } else if (r.action === SessionSyncAction.Skipped) {
+      // Reached only by the bare-install path when `which skillrepo`
+      // returns nothing (and we didn't auto-install). Surface the
+      // helper's actionable reason verbatim.
+      p.warning(r.reason ?? "Session sync skipped.");
+    }
+    return {
+      action: r.action,
+      path: r.path,
+      globalInstallActive: isHookActive(r.action),
+    };
+  } catch (err) {
+    // Disk error (corrupt settings file). The other init steps
+    // succeeded — surface and continue.
+    p.warning(
+      `Session sync failed: ${err?.message ?? String(err)}. ` +
+        `Run \`skillrepo session-sync enable\` after fixing the issue.`,
+    );
+    return result(SessionSyncAction.Failed);
+  }
+}
+
+function printManualSteps(p, runnerName) {
+  // Use the runner's canonical install command (`pnpm add -g`,
+  // `bun add -g`, etc.) so the suggestion matches the package
+  // manager the user is actually invoking through. Falls back to
+  // `npm install -g` when no runner is detected (non-transient
+  // failure path) — the universal command that works alongside
+  // every runner.
+  const installCmd =
+    globalInstallCommandFor(runnerName) ?? "npm install -g skillrepo";
+  p.warning(
+    "To enable session sync later: " +
+      `run \`${installCmd}\` (with sudo if needed), then ` +
+      "`skillrepo session-sync enable`.",
+  );
+}
+
+/** Build a default-shaped step-6 result for an action that didn't
+ *  install anything (opted-out / not-applicable / declined / skipped).
+ *  Both `path` and `globalInstallActive` are always falsy in those
+ *  cases — installed/updated/unchanged use `tryMergeAndPrint`'s
+ *  return shape directly.
+ */
+function result(action) {
+  return { action, path: null, globalInstallActive: false };
+}

package/src/commands/init.mjs

@@ -43,12 +43,16 @@
 import { validateAccessKey } from "../lib/http.mjs";
 import { detectIdes, formatDetectedIdes } from "../lib/detect-ides.mjs";
 import { readConfig, writeConfig } from "../lib/config.mjs";
-import { resolveFlags, effectiveVendors, isNpxInvocation } from "../lib/cli-config.mjs";
+import { resolveFlags, effectiveVendors } from "../lib/cli-config.mjs";
+import {
+  detectTransientRunner,
+  globalInstallCommandFor,
+} from "../lib/transient-runners.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 { installSessionSyncHook } from "./init-session-sync.mjs";
 import { resolveKeyFromEnvFiles } from "../lib/resolve-key.mjs";
 import {
   promptSecret,
@@ -138,13 +142,29 @@ const BLACK_HOLE_STREAM = {
  * @param {object} [io]
  * @param {NodeJS.WritableStream} [io.stdout=process.stdout]
  * @param {NodeJS.WritableStream} [io.stderr=process.stderr]
+ * @param {object} [deps] - Test-only dependency injection. Production
+ *        callers leave this empty. Forwarded to step 6
+ *        (`installSessionSyncHook`); see `init-session-sync.mjs` for
+ *        the supported keys (`spawn`, `getCliVersion`, `confirmFn`).
  */
-export async function runInit(argv, io = {}) {
+export async function runInit(argv, io = {}, deps = {}) {
   const stdout = io.stdout ?? process.stdout;
   const stderr = io.stderr ?? process.stderr;
 
   const { flags, yes, force, noSessionSync } = parseInitFlags(argv);
 
+  // `--json` is for non-interactive consumers (CI scripts, programmatic
+  // callers). Without `--yes`, init would hang at step 5 (MCP merge
+  // per-vendor confirm prompt) waiting for stdin that no one is going
+  // to provide. Surface that loudly at parse time rather than letting
+  // the user discover it via a 5-minute test-runner timeout.
+  if (flags.json && !yes) {
+    throw validationError(
+      "--json requires --yes (init has interactive prompts that --json suppresses).",
+      { hint: "Pass --yes alongside --json for non-interactive runs." },
+    );
+  }
+
   // In --json mode, suppress all step-progress output so stdout
   // carries only the final JSON blob.
   const p = makePrinter(stdout, stderr, flags.json);
@@ -377,99 +397,29 @@ export async function runInit(argv, io = {}) {
   }
   p.blank();
 
-  // ── 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.
+  // ── Step 6: Session sync (#884, v3.1.2 auto-install #894) ─────
   //
-  // 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.
+  // The full decision tree (six branches) lives in
+  // `init-session-sync.mjs`. This step is inserted between MCP
+  // merge (step 5) and the first sync (step 7) — order matters
+  // because the hook's `skillrepo update` calls expect the config
+  // to already be written (step 3).
   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";
-      }
-    }
-  }
+  const sessionSync = await installSessionSyncHook({
+    noSessionSync,
+    claudeTargeted,
+    yes,
+    json: flags.json,
+    global: flags.global,
+    p,
+    deps,
+  });
+  const sessionSyncAction = sessionSync.action;
+  const sessionSyncPath = sessionSync.path;
+  const globalInstallActive = sessionSync.globalInstallActive;
   p.blank();
 
   // ── Step 7: First sync ───────────────────────────────────────
@@ -584,13 +534,9 @@ 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)
+          // Session-sync block. `action` is one of the
+          // `SessionSyncAction` enum values defined in
+          // `./session-sync-actions.mjs` (single source of truth).
           sessionSync: {
             action: sessionSyncAction,
             path: sessionSyncPath,
@@ -611,24 +557,41 @@ 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";
+  // Pick the command prefix the user can actually run. The user is
+  // either:
+  //   - running a stable global install → bare `skillrepo list` works
+  //   - running via a transient runner (npx/pnpx/yarn dlx/bunx) AND
+  //     the auto-install in step 6 put a global on PATH
+  //     (`globalInstallActive`) → bare `skillrepo list` ALSO works
+  //     (subject to PATH refresh on Windows; see the
+  //     path-not-updated branch in global-install.mjs)
+  //   - running via a transient runner with NO global → bare
+  //     `skillrepo` would fail; they need to invoke through their
+  //     runner. v3.1.2 detects WHICH runner (npx/pnpx/yarn dlx/bunx)
+  //     so the prefix matches what they actually used.
+  const transientRunner = detectTransientRunner();
+  const showRunnerPrefix = transientRunner && !globalInstallActive;
+  const prefix = showRunnerPrefix ? `${transientRunner} skillrepo` : "skillrepo";
   stdout.write("  Next steps:\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).
+  if (showRunnerPrefix) {
+    // The Tip is only useful when the user is still on a transient
+    // runner post-init: it tells them how to switch to a faster,
+    // sync-enabled global install. After a successful auto-install
+    // (or when a pre-existing global was used), the global IS active
+    // and the tip would be stale.
+    //
+    // Use the runner's CANONICAL global-install command so a `pnpx`
+    // user gets `pnpm add -g skillrepo` instead of `npm install -g
+    // skillrepo`. Falls back to the universal `npm install -g` for
+    // any unrecognized runner.
+    const installCmd =
+      globalInstallCommandFor(transientRunner) ?? "npm install -g skillrepo";
     stdout.write(
-      "\n  Tip: `npm install -g skillrepo` for faster commands " +
-        "and to enable session-start sync.\n",
+      `\n  Tip: \`${installCmd}\` for faster commands ` +
+        "and session-start sync.\n",
     );
   }
   stdout.write("\n");

package/src/commands/session-sync-actions.mjs

@@ -0,0 +1,92 @@
+/**
+ * Single source of truth for the `sessionSync.action` enum surfaced
+ * by `skillrepo init` (#894 / v3.1.2).
+ *
+ * The enum appears in three places that MUST stay in sync:
+ *   - the `--json` output's `sessionSync.action` field (consumer
+ *     contract for CI scripts and programmatic callers)
+ *   - the human-readable summary at the end of init
+ *   - the README's `init` flag table
+ *
+ * Before this module existed, the values were declared inline in a
+ * JSDoc comment block and re-typed as string literals at every
+ * assignment site — drift risk. Centralizing here means adding a
+ * new value is one edit (this file + the consumer that needs it),
+ * not a grep-and-pray pass across init.mjs.
+ *
+ * The enum is `Object.freeze`d so callers can't mutate it. JS
+ * doesn't have first-class enums; this is the standard idiom.
+ */
+
+/**
+ * @typedef {"installed" | "updated" | "unchanged" | "opted-out" | "declined" | "not-applicable" | "skipped" | "failed"} SessionSyncActionValue
+ */
+
+/**
+ * Action enum constants. Use these instead of string literals at
+ * assignment sites. Values:
+ *
+ *   - `Installed`     — fresh hook write
+ *   - `Updated`       — existing hook found, command differed,
+ *                       replaced in place (e.g. binary path changed)
+ *   - `Unchanged`     — identical hook already present, no write
+ *   - `OptedOut`      — `--no-session-sync` was passed
+ *   - `Declined`      — user said no at the prompt
+ *   - `NotApplicable` — Claude Code wasn't a vendor target (the hook
+ *                       is Claude-specific, would never fire)
+ *   - `Skipped`       — install offer was accepted but the install
+ *                       failed (npm error, version-read error,
+ *                       prerequisite missing). Distinct from
+ *                       `OptedOut` (user explicit) and `Declined`
+ *                       (user said no).
+ *   - `Failed`        — disk error while writing the settings file
+ *                       (corrupt JSON, permissions, etc.)
+ */
+export const SessionSyncAction = Object.freeze({
+  Installed: "installed",
+  Updated: "updated",
+  Unchanged: "unchanged",
+  OptedOut: "opted-out",
+  Declined: "declined",
+  NotApplicable: "not-applicable",
+  Skipped: "skipped",
+  Failed: "failed",
+});
+
+/**
+ * True when the action represents a state where the SessionStart
+ * hook is currently in place on disk (and therefore the global
+ * `skillrepo` binary referenced by the hook is also active on PATH,
+ * because `mergeSessionHook` only emits these actions when it
+ * successfully wrote/found a working hook).
+ *
+ * Used by `init` to suppress the now-stale "install globally"
+ * Next-Steps tip after step 6 has put a hook in place.
+ *
+ * @param {string} action
+ * @returns {boolean}
+ */
+export function isHookActive(action) {
+  return (
+    action === SessionSyncAction.Installed ||
+    action === SessionSyncAction.Updated ||
+    action === SessionSyncAction.Unchanged
+  );
+}
+
+/**
+ * Frozen array of all valid `sessionSync.action` string values.
+ * Useful for runtime validation in tests and for the JSON-schema-
+ * style documentation generator.
+ *
+ * Built from `Object.values(SessionSyncAction)` so it stays in sync
+ * automatically. We use a frozen array (rather than a Set) because
+ * `Object.freeze` on a Set does NOT prevent `.add()` from mutating
+ * the internal storage — JS frozen-Set semantics are surprising.
+ * Frozen arrays ARE immutable end-to-end. Membership checks are
+ * `.includes()` instead of `.has()`; the values list is small (8)
+ * so the linear scan is irrelevant.
+ */
+export const SESSION_SYNC_ACTION_VALUES = Object.freeze(
+  Object.values(SessionSyncAction),
+);