skillrepo 4.0.0 → 4.1.0

package/README.md

@@ -100,7 +100,19 @@ and just write the config + gitignore.
     "skipped": ["..."],
     "failed": [{ "path": "...", "reason": "..." }]
   },
-  "sessionSync": { "action": "installed|unchanged|skipped|failed|not-applicable", "path": "..." },
+  "sessionSync": {
+    "action": "installed|unchanged|skipped|failed|not-applicable",
+    "path": "...",
+    "cohortHooks": [
+      {
+        "vendorKey": "cursor|gemini|codex|copilot",
+        "displayName": "...",
+        "path": "~/.cursor/hooks.json",
+        "action": "installed|updated|unchanged|failed",
+        "reason": "..."
+      }
+    ]
+  },
   "sync": {
     "added": 0,
     "updated": 0,
@@ -114,6 +126,7 @@ and just write the config + gitignore.
 
 Field notes:
 - `vendors` is the resolved canonical-key list, NOT the raw `--agent` input. `--agent agents` produces every cohort vendor (cursor, windsurf, gemini, codex, cline, copilot); `--agent none` produces an empty array.
+- `sessionSync.cohortHooks[]` reports per-vendor outcomes for the auto-refresh hooks installed alongside the Claude Code SessionStart hook (one entry per cohort vendor with a non-null `agentHook` registry spec — Cursor, Gemini CLI, Codex CLI, VS Code + Copilot). `reason` is present only when `action: "failed"`. Empty array when `--no-session-sync` was passed or no cohort vendor was selected.
 - `sync.fullSync` is `true` for first-time syncs (no prior `.last-sync`), `false` for delta syncs, and `null` only on synthesized-failure summaries when the network call never completed (also signals via `sync.failureReason`).
 - `sync.failureReason: string` is present only when the first sync failed but the rest of init succeeded — config is still saved; user should re-run `skillrepo update`.
 
@@ -137,7 +150,7 @@ or a vendor name like `cursor`) to bypass the picker entirely.
 ### `update` — sync your library
 
 ```sh
-skillrepo update [--global] [--agent <list>] [--json]
+skillrepo update [--global] [--agent <list>] [--json] [--silent]
 ```
 
 Pulls the latest state of your library from the server using a delta
@@ -146,6 +159,16 @@ from the library, and skips skills that are unchanged. Uses ETag
 caching so repeat runs return `304 Not Modified` when nothing has
 changed.
 
+`--silent` suppresses normal output and writes a single `{}` line to
+stdout on success. Designed for SessionStart hooks that pipe stdout
+to their agent's session log — Gemini CLI specifically requires hook
+stdout to be valid JSON, and the empty object satisfies that without
+injecting model context. Sync progress and warnings still go to
+stderr. On failure, the command exits with the appropriate non-zero
+code and the error message goes to stderr (distinct from
+`--session-hook`, which is Claude-Code-specific and exits 0 on every
+error so a sync failure can't block a session start).
+
 ### `get` — fetch a single skill
 
 ```sh
@@ -207,6 +230,23 @@ 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.
 
+#### Auto-refresh hooks for other agents
+
+For Cursor, Gemini CLI, Codex CLI, and VS Code + Copilot, `skillrepo init` writes a SessionStart hook to each agent's user-scope hook config so your library refreshes on every session start without a separate command. Each hook invokes `npx --yes skillrepo update --silent`, so it works without a global `skillrepo` install.
+
+| Agent | Hook config path | Notes |
+|-------|------------------|-------|
+| Cursor | `~/.cursor/hooks.json` (`sessionStart` event) | `timeout: 60` (seconds) |
+| Gemini CLI | `~/.gemini/settings.json` (`SessionStart` event) | `matcher: "*"` group filter, `timeout: 60000` (milliseconds), entry named `skillrepo-update` |
+| Codex CLI | `~/.codex/hooks.json` (`SessionStart` event) | `timeout: 60` (seconds). Codex also reads `[hooks]` from `~/.codex/config.toml`; both sources coexist — Codex merges them at runtime, so a hand-written TOML entry won't conflict with our JSON. |
+| VS Code + Copilot | `~/.copilot/hooks/skillrepo-update.json` (`sessionStart` event) | `timeout: 60` (seconds). **Preview status**: GitHub currently labels Copilot's hook system as Preview; the schema may shift before GA. |
+
+`skillrepo init` writes these alongside the Claude Code hook for every selected vendor that publishes a SessionStart-equivalent event. `--no-session-sync` skips ALL of them. `skillrepo uninstall --global` removes them surgically — other tools' entries (1Password, Snyk, your own scripts) in those config files are preserved.
+
+**Cloud-agent runners** (e.g. GitHub Codespaces, Copilot's cloud agent) read only the committed default-branch content. Because skills sync to a per-developer, gitignored cache, those runners do not see the local skill library — same documented limitation as `.agents/skills/` placement. The auto-refresh hooks above are per-developer; they don't run in cloud runners.
+
+Auto-refresh hooks for Windsurf and Cline are not yet supported — those agents lack a documented SessionStart-equivalent event today. Run `skillrepo update` manually in those environments.
+
 **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.
@@ -247,6 +287,13 @@ 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)
+- The SkillRepo SessionStart entry from each cohort vendor's hook config —
+  `~/.cursor/hooks.json`, `~/.gemini/settings.json`, `~/.codex/hooks.json`,
+  and `~/.copilot/hooks/skillrepo-update.json`. Other tools' entries
+  (1Password, Snyk, Apiiro, the user's own hooks) and unrelated top-level
+  keys (theme, mcpServers, etc.) are preserved — only our entry, identified
+  by the canonical command `npx --yes skillrepo update --silent`, is
+  filtered out.
 
 Flags:
 

package/package.json

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

package/src/commands/init-cohort-hooks.mjs

@@ -0,0 +1,127 @@
+/**
+ * `skillrepo init` step-6 sibling for cohort SessionStart hooks (#1240).
+ *
+ * Runs ALONGSIDE `installSessionSyncHook` (the legacy Claude-Code-only
+ * installer). Where the Claude installer has to resolve a stable
+ * absolute `binaryPath` for the hook command — three branches
+ * (non-npx, existing global, auto-install) — the cohort installer has
+ * no such concern: every cohort hook is `npx --yes skillrepo update
+ * --silent`, which works on any host without a global install.
+ *
+ * That's why this is a sibling step, not an extension of
+ * `installSessionSyncHook`. The two flows share almost no logic. The
+ * architect review on #1240 specifically called out conflating them
+ * as a structural mistake — `installSessionSyncHook` is named for
+ * Claude Code's hook mechanism, and folding cohort logic into it
+ * would create a function with four irreducible branches by Phase 4
+ * (#1241-#1244).
+ *
+ * ## Decision tree
+ *
+ *   noSessionSync                  → skip all cohort hooks (mirrors
+ *                                    Claude path's --no-session-sync
+ *                                    semantics)
+ *   no cohort vendors selected    → no-op (nothing to install)
+ *   cohort vendors selected       → install hooks for each one;
+ *                                    per-vendor failures don't abort
+ *                                    siblings
+ *
+ * ## Return shape
+ *
+ *   { hooks: AgentHookInstallResult[] }
+ *
+ * Each entry: `{ vendorKey, displayName, path, action, reason? }`. The
+ * caller (init.mjs) merges these into the `sessionSync.cohortHooks`
+ * field of the JSON summary.
+ */
+
+import { installAgentHooksForVendors } from "../lib/agent-hook-merge.mjs";
+import { getAgentByKey } from "../lib/agent-registry.mjs";
+
+/**
+ * @typedef {Object} CohortHookOptions
+ * @property {boolean} noSessionSync - True if `--no-session-sync` was
+ *           passed. The flag covers BOTH the Claude session hook and
+ *           the cohort hooks — semantically "skip all auto-refresh
+ *           hooks." Pre-#1240 this was a Claude-only flag; the
+ *           framing widened with the cohort feature.
+ * @property {string[]} vendors - Canonical vendor keys the user
+ *           selected (via `--agent` or the picker). Vendors without
+ *           an `agentHook` spec are silently skipped by the
+ *           dispatcher; truly unknown keys surface as failures.
+ * @property {object} p - Init's printer (from `init.mjs:makePrinter`).
+ *           Silenced under `--json`; otherwise renders one line per
+ *           cohort hook installed/updated/failed.
+ */
+
+/**
+ * Run the cohort sibling step. Always returns a result; never throws
+ * on user-recoverable failures (per-vendor errors are captured in
+ * each result entry).
+ *
+ * @param {CohortHookOptions} options
+ * @returns {{ hooks: import("../lib/agent-hook-merge.mjs").AgentHookInstallResult[] }}
+ */
+export function installCohortHooks({ noSessionSync, vendors, p }) {
+  if (noSessionSync) {
+    // Match the Claude path's --no-session-sync semantics: silent
+    // skip. The Claude path already prints the warning, so we don't
+    // double-warn here. If somehow the user passes --no-session-sync
+    // AND no Claude target (so the Claude path doesn't print), the
+    // user got exactly what they asked for — explicit opt-out.
+    return { hooks: [] };
+  }
+
+  // Filter vendors to those with an agentHook spec. The dispatcher
+  // does this filtering internally too (silently skipping unknown
+  // entries), but doing it here lets us avoid the noise of "Skipped
+  // claudeCode (no agentHook)" lines for every vendor in the cohort
+  // list that isn't ours to install. Claude Code, Windsurf, and
+  // Cline all hit this filter; only the four cohort vendors with
+  // `agentHook != null` reach the dispatcher.
+  const eligible = vendors.filter((v) => {
+    const entry = getAgentByKey(v);
+    return entry && entry.agentHook !== null;
+  });
+
+  if (eligible.length === 0) {
+    return { hooks: [] };
+  }
+
+  const results = installAgentHooksForVendors({ vendors: eligible });
+
+  // Surface each result on the printer so the user sees what was
+  // written / refreshed / failed. Mirrors `installSessionSyncHook`'s
+  // per-action printing for Claude.
+  for (const r of results) {
+    if (r.action === "installed") {
+      p.success(`Cohort SessionStart hook installed for ${r.displayName} (${r.path})`);
+    } else if (r.action === "updated") {
+      p.success(`Cohort SessionStart hook updated for ${r.displayName} (${r.path})`);
+    } else if (r.action === "unchanged") {
+      p.success(`Cohort SessionStart hook already installed for ${r.displayName} (${r.path})`);
+    } else if (r.action === "failed") {
+      p.warning(
+        `Cohort SessionStart hook for ${r.displayName} failed: ${r.reason}. ` +
+          `Run \`skillrepo init\` again after fixing the issue.`,
+      );
+    }
+  }
+
+  // VS Code + Copilot's hook system is currently labelled Preview by
+  // GitHub (#1244). Surface that caveat once if Copilot was among the
+  // installed vendors so users know the hook schema may shift before
+  // GA. Skip the warning if Copilot's install actually failed — we
+  // already printed the failure line above and a Preview note would
+  // muddle the actionable signal.
+  const copilotResult = results.find((r) => r.vendorKey === "copilot");
+  if (copilotResult && copilotResult.action !== "failed") {
+    p.warning(
+      "Copilot's SessionStart hook system is currently labelled Preview by GitHub. " +
+        "The schema may shift before GA; re-run `skillrepo init` after upgrading the CLI " +
+        "if Copilot's hook config format changes.",
+    );
+  }
+
+  return { hooks: results };
+}

package/src/commands/init.mjs

@@ -81,6 +81,7 @@ import {
 import { mergeEnvLocal } from "../lib/mergers/env-local.mjs";
 import { mergeGitignore } from "../lib/mergers/gitignore.mjs";
 import { installSessionSyncHook } from "./init-session-sync.mjs";
+import { installCohortHooks } from "./init-cohort-hooks.mjs";
 import { resolveKeyFromEnvFiles } from "../lib/resolve-key.mjs";
 import {
   claudeSkillsProjectRoot,
@@ -466,14 +467,32 @@ export async function runInit(argv, io = {}, deps = {}) {
   }
   p.blank();
 
-  // ── Step 6: Session sync (#884, v3.1.2 auto-install #894) ─────
+  // ── Step 6: Session sync (#884 Claude path + #1240 cohort path) ─
   //
-  // 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).
+  // Two sibling installers run here:
+  //
+  //   - Claude Code's SessionStart hook (#884) — `installSessionSyncHook`
+  //     in `init-session-sync.mjs`. Has its own six-branch decision
+  //     tree because Claude Code's hook needs an absolute-path command
+  //     (Claude doesn't load PATH at hook time), which under `npx
+  //     skillrepo init` requires offering to install skillrepo
+  //     globally first.
+  //   - Cohort SessionStart hooks (#1240) — `installCohortHooks` in
+  //     `init-cohort-hooks.mjs`. Writes hooks for every selected vendor
+  //     whose agent-registry entry has a non-null `agentHook` spec
+  //     (Cursor, Gemini CLI, Codex CLI, VS Code + Copilot). Uses
+  //     `npx --yes skillrepo update --silent` as the universal hook
+  //     command — no global install needed.
+  //
+  // The two flows are deliberately separate. Folding them into a single
+  // function would create irreducible branching by Phase 4 (#1241-1244)
+  // because Claude's binaryPath resolution has no analogue in the
+  // cohort path.
+  //
+  // `--no-session-sync` skips BOTH paths (semantics widened in #1240
+  // from "skip Claude" to "skip all auto-refresh hooks").
   p.step(6, 7, "Session sync");
+
   // Install the Claude Code SessionStart hook only when Claude Code
   // is actually a target. Pre-#1249 this condition also included
   // `Boolean(flags.global)` because bare `--global` historically
@@ -495,6 +514,16 @@ export async function runInit(argv, io = {}, deps = {}) {
   const sessionSyncAction = sessionSync.action;
   const sessionSyncPath = sessionSync.path;
   const globalInstallActive = sessionSync.globalInstallActive;
+
+  // Cohort SessionStart hooks for every non-Claude selected vendor
+  // with an `agentHook` spec. Skipped under `--no-session-sync` AND
+  // when no eligible vendors are selected (e.g. `--agent claude` only,
+  // or `--agent none`). Per-vendor failures do not abort init —
+  // each result entry carries its own `action: "failed"` + `reason`.
+  const cohortHooksResult =
+    Array.isArray(vendors) && vendors.length > 0
+      ? installCohortHooks({ noSessionSync, vendors, p })
+      : { hooks: [] };
   p.blank();
 
   // ── Step 7: First sync ───────────────────────────────────────
@@ -637,9 +666,19 @@ export async function runInit(argv, io = {}, deps = {}) {
           // Session-sync block. `action` is one of the
           // `SessionSyncAction` enum values defined in
           // `./session-sync-actions.mjs` (single source of truth).
+          // `cohortHooks` (added in #1240) reports per-vendor cohort
+          // SessionStart hook outcomes — empty array when no cohort
+          // vendor was selected or when --no-session-sync was passed.
           sessionSync: {
             action: sessionSyncAction,
             path: sessionSyncPath,
+            cohortHooks: cohortHooksResult.hooks.map((h) => ({
+              vendorKey: h.vendorKey,
+              displayName: h.displayName,
+              path: h.path,
+              action: h.action,
+              ...(h.reason ? { reason: h.reason } : {}),
+            })),
           },
           // Sync block always shows the counts (zeroed on failure)
           // and adds `failureReason` when the first sync blew up —

package/src/commands/uninstall.mjs

@@ -58,6 +58,7 @@ import { removeCursorMcp } from "../lib/removers/cursor-mcp.mjs";
 import { removeVscodeMcp } from "../lib/removers/vscode-mcp.mjs";
 import { removeWindsurfMcp } from "../lib/removers/windsurf-mcp.mjs";
 import { removeSettingsSessionHook } from "../lib/removers/settings.mjs";
+import { removeAgentHookArtifact } from "../lib/removers/agent-hooks.mjs";
 import { confirm } from "../lib/prompt.mjs";
 import { resolveFlags } from "../lib/cli-config.mjs";
 import { diskError } from "../lib/errors.mjs";
@@ -398,6 +399,14 @@ function runForDescriptor(descriptor, { dryRun }) {
   if (descriptor.kind === "directory") {
     return removeDirectoryArtifact(descriptor, { dryRun });
   }
+  // Cohort SessionStart-hook descriptors (#1240) dispatch by `kind`
+  // rather than by id: every `kind: "agent-hook"` descriptor goes to
+  // the same batch remover, which uses the descriptor's `vendorKey`
+  // to route to the per-shape merger. Adding a new cohort vendor =
+  // one registry entry + one descriptor; this dispatch never changes.
+  if (descriptor.kind === "agent-hook") {
+    return removeAgentHookArtifact(descriptor, { dryRun });
+  }
   const fn = FILE_REMOVERS[descriptor.id];
   if (!fn) {
     // Only reachable for descriptors that share a remover with a
@@ -418,7 +427,9 @@ function renderPreviewLine(descriptor, result) {
       ? "   [dir]   "
       : descriptor.kind === "line" || descriptor.kind === "section"
         ? "   [lines] "
-        : "   [entry] ";
+        : descriptor.kind === "agent-hook"
+          ? "   [hook]  "
+          : "   [entry] ";
   const detail = result.error
     ? `→ ${result.error}`
     : result.detail

package/src/commands/update.mjs

@@ -21,6 +21,22 @@
  *                    command behaves as before (exit non-zero on
  *                    network / auth / disk failures).
  *
+ * v4.1.0 silent mode (#1240):
+ *   --silent         Suppress stdout: write `{}` on success, propagate
+ *                    failures (non-zero exit) with the error on stderr.
+ *                    Used by the per-agent SessionStart hooks (Cursor,
+ *                    Gemini CLI, Codex CLI, VS Code + Copilot) the
+ *                    cohort installer writes via `npx --yes skillrepo
+ *                    update --silent`. Gemini CLI specifically requires
+ *                    hook stdout to be valid JSON; the empty `{}`
+ *                    satisfies that. Distinct from `--session-hook` —
+ *                    `--silent` does NOT suppress error exit codes,
+ *                    because none of the cohort agents block session
+ *                    start on non-zero hook exits the way Claude Code
+ *                    does. If primary-source evidence later shows a
+ *                    cohort vendor DOES block, give that vendor its
+ *                    own contract flag rather than widening this one.
+ *
  * Exit codes are inherited from sync.mjs / http.mjs error types,
  * EXCEPT under `--session-hook` — see the flag's contract below.
  */
@@ -62,14 +78,12 @@ import {
  */
 export async function runUpdate(argv, io = {}) {
   const stdout = io.stdout ?? process.stdout;
-  // `stderr` is not used directly — the session-hook path pipes to
-  // BLACK_HOLE_STREAM and the normal path forwards `io` to runSync
-  // which reads `io.stderr` itself.
+  const stderr = io.stderr ?? process.stderr;
 
-  // ── Pre-pass: detect --session-hook BEFORE resolveFlags runs ─────
+  // ── Pre-pass: detect --session-hook / --silent BEFORE resolveFlags runs ─
   //
-  // resolveFlags can throw in three categories we must catch under
-  // session-hook mode:
+  // resolveFlags can throw in three categories the wrapping mode must
+  // catch:
   //   - `authError` when no access key is configured (e.g., session
   //     fires before `skillrepo init` has run — a real first-run
   //     scenario, not synthetic)
@@ -78,15 +92,27 @@ export async function runUpdate(argv, io = {}) {
   //
   // All three happen INSIDE resolveFlags, before our try/catch block
   // could see them if we called it after. The only robust answer is
-  // to detect --session-hook without invoking resolveFlags, then
-  // wrap resolveFlags + runSync together in the error handler.
+  // to detect the mode flags without invoking resolveFlags, then wrap
+  // resolveFlags + runSync together in the error handler.
   //
-  // A simple argv scan is safe here: `--session-hook` has no value
-  // argument, so a plain `.includes` match can't misinterpret
-  // positional args. This DOES NOT accept variations like
-  // `--session-hook=true` or `-SH` — single canonical form only,
-  // matching what the installer writes.
+  // A simple argv scan is safe here: neither flag takes a value, so a
+  // plain `.includes` match can't misinterpret positional args. This
+  // DOES NOT accept variations like `--session-hook=true` or `-S` —
+  // single canonical form only, matching what the installers write.
   const sessionHook = argv.includes("--session-hook");
+  const silent = argv.includes("--silent");
+
+  // Precedence: when both flags appear in argv, `--session-hook`
+  // wins because the order of the branches below dispatches it
+  // first. The session-hook path's `acceptPositional` accepts both
+  // flags so it doesn't reject `--silent` as unknown. The silent
+  // path only accepts `--silent` (different exit-code contract).
+  // Don't reorder these branches without coordinating with the two
+  // hook-installer paths in `commands/init-cohort-hooks.mjs` and
+  // `mergers/session-hook.mjs`. Practical exposure: zero — neither
+  // installer writes a hook command containing both flags. The
+  // precedence is defensive against a future code path or a manual
+  // user edit, not an active scenario.
 
   if (sessionHook) {
     // Session-hook mode: wrap EVERY error path in try/catch so a
@@ -94,10 +120,13 @@ export async function runUpdate(argv, io = {}) {
     try {
       const flags = resolveFlags(argv, {
         acceptPositional(arg) {
-          // resolveFlags sees --session-hook as unknown unless we
-          // consume it here. Kept for the non-error path — the
-          // real "catch errors" logic is the outer try.
+          // resolveFlags sees these as unknown unless we consume them
+          // here. Both flags are accepted because a future caller may
+          // combine them (defense — installers should pick one); the
+          // outer mode dispatch above already chose `session-hook` if
+          // present, so accepting `--silent` here is a no-op tolerance.
           if (arg === "--session-hook") return 1;
+          if (arg === "--silent") return 1;
           return false;
         },
       });
@@ -148,6 +177,58 @@ export async function runUpdate(argv, io = {}) {
     return;
   }
 
+  // ── Silent mode (#1240): cohort SessionStart hook contract ──────
+  //
+  // Used by Cursor / Gemini CLI / Codex CLI / VS Code + Copilot. Their
+  // SessionStart hook config invokes `npx --yes skillrepo update
+  // --silent`. Contract:
+  //
+  //   - stdout produces ONE valid-JSON line on success: `{}`. Gemini
+  //     CLI specifically requires hook stdout to be JSON; the empty
+  //     object is the minimal valid value that injects no model
+  //     context. Other vendors tolerate it.
+  //   - On failure, stdout writes nothing extra; the typed error
+  //     propagates through the dispatcher's catch which writes to
+  //     stderr and exits with the appropriate code. We do NOT write
+  //     `{}` on failure — partial JSON output alongside an error
+  //     message on stderr would mislead a hook runner that treats
+  //     stdout as model context.
+  //   - All sync progress lines (the "failed to persist last-sync
+  //     state" warning from sync.mjs, etc.) are routed to a black-hole
+  //     stdout so they cannot leak into the JSON expectation.
+  //
+  // Distinct from `--session-hook`. That mode is Claude-Code-specific
+  // and contracts "EXIT 0 ON ALL ERRORS" because Claude Code's hook
+  // runner blocks session start on non-zero exits. The cohort vendors
+  // handled here have no documented session-blocking behavior, so a
+  // failure should surface as a real exit code — the user can then
+  // investigate via `skillrepo update` directly.
+  if (silent) {
+    const flags = resolveFlags(argv, {
+      acceptPositional(arg) {
+        if (arg === "--silent") return 1;
+        return false;
+      },
+    });
+    const vendors = effectiveVendors(flags);
+    requireVendorTargets(vendors, "update");
+
+    await runSync({
+      serverUrl: flags.serverUrl,
+      apiKey: flags.apiKey,
+      vendors,
+      global: flags.global,
+      // sync.mjs surfaces non-fatal warnings (e.g. failed to persist
+      // last-sync state) via stderr; preserve that channel so a real
+      // operator running `update --silent` from a terminal can still
+      // see them. Stdout is the contract-bearing stream and stays
+      // black-hole until we emit `{}` ourselves.
+      io: { stdout: BLACK_HOLE_STREAM, stderr },
+    });
+    stdout.write("{}\n");
+    return;
+  }
+
   // ── Normal mode: original behavior ───────────────────────────────
   // Forward `io` to runSync so the non-fatal "failed to persist
   // last-sync state" warning lands on the injected stderr stream