docks-kit 0.1.5 → 0.2.0

package/cli/src/engine-native/os.ts

@@ -0,0 +1,29 @@
+/**
+ * Platform capability seam (Output Policy in DESIGN.md) — the only engine
+ * module that reads process.platform besides exec.ts's PATH/executability
+ * primitives. Per-tool package identifiers stay in deps.ts; symlink handling
+ * stays try-then-fallback at the call site (capability-driven, not predicted).
+ */
+
+export type PlatformName = "linux" | "darwin" | "windows" | "unknown"
+
+export function rawPlatform(): NodeJS.Platform {
+  return process.platform
+}
+
+export function platformName(pf: NodeJS.Platform = rawPlatform()): PlatformName {
+  return pf === "linux" ? "linux" : pf === "darwin" ? "darwin" : pf === "win32" ? "windows" : "unknown"
+}
+
+export function isWindows(): boolean {
+  return rawPlatform() === "win32"
+}
+
+export function isLinux(): boolean {
+  return rawPlatform() === "linux"
+}
+
+/** Shell-rc exports (bashrc/zshrc) apply only off Windows. */
+export function shellRcApplicable(): boolean {
+  return !isWindows()
+}

package/cli/src/engine-native/parseArgs.ts

@@ -4,10 +4,8 @@
  * early parser exit and is caught once in runEngineNative.
  */
 
-import { commandExists } from "./exec"
 import type { Ctx } from "./index"
 import { printModels, validateClaudeModel, validateCodexModel } from "./models"
-import { echo, err, warn } from "./output"
 
 export class ExitError extends Error {
   constructor(readonly code: number) {
@@ -18,6 +16,7 @@ export class ExitError extends Error {
 const KNOWN_CLAUDE_OPTIN_PLUGINS = ["supabase", "n8n"]
 
 function usage(ctx: Ctx): void {
+  const { echo } = ctx.services.logger
   const argv0 = "docks-kit sync"
   echo(`Usage: ${argv0} [claude] [codex] [agents] [flags]`)
   echo("")
@@ -36,6 +35,7 @@ function usage(ctx: Ctx): void {
   )
   echo("  --skip-rtk        skip optional tool bootstrap (RTK, bubblewrap)")
   echo("  --yes             auto-accept toolchain prompts (containers/CI)")
+  echo("  --verbose         also print no-op confirmations (already in sync, up to date, left as-is)")
   echo("")
   echo("Deploy-time modifiers (deployed config only; SoT untouched; a later flag-less sync reverts)")
   echo(
@@ -66,6 +66,7 @@ export function parseCompactWindow(v: string): string | undefined {
 }
 
 function addClaudePlugin(ctx: Ctx, name: string): void {
+  const { err } = ctx.services.logger
   if (!KNOWN_CLAUDE_OPTIN_PLUGINS.includes(name)) {
     err(`Unknown opt-in plugin '${name}'. Known: ${KNOWN_CLAUDE_OPTIN_PLUGINS.join(", ")}`)
     throw new ExitError(2)
@@ -81,6 +82,7 @@ function selectTarget(ctx: Ctx, target: string): void {
 }
 
 export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
+  const { err } = ctx.services.logger
   for (const arg of args) {
     switch (arg) {
       case "claude":
@@ -103,12 +105,15 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
       case "--yes":
         ctx.assumeYes = true
         continue
+      case "--verbose":
+        ctx.verbose = true
+        continue
       case "--claude-model":
-        printModels(ctx.repoDir, "claude")
+        printModels(ctx, "claude")
         err("--claude-model requires a value: --claude-model=<model>")
         throw new ExitError(2)
       case "--codex-model":
-        printModels(ctx.repoDir, "codex")
+        printModels(ctx, "codex")
         err("--codex-model requires a value: --codex-model=<model>")
         throw new ExitError(2)
       case "--claude-compact-window":
@@ -180,32 +185,29 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
 }
 
 export function preflight(ctx: Ctx): void {
+  const { err } = ctx.services.logger
   if (ctx.syncClaude || ctx.syncCodex) {
-    if (!commandExists("jq")) {
-      const hint = process.platform === "win32"
-        ? "winget install jqlang.jq (then open a new terminal)"
-        : process.platform === "darwin"
-          ? "brew install jq"
-          : "sudo apt install -y jq"
-      err(`jq is required (deployed statusline/hooks call it). Install: ${hint}`)
+    if (ctx.services.deps.probe("jq").state === "missing") {
+      err(`jq is required (deployed statusline/hooks call it). Install: ${ctx.services.deps.spec("jq").installHint()}`)
       throw new ExitError(1)
     }
   }
   if (ctx.syncClaude) {
-    if (!commandExists("curl")) {
-      err("curl is required.")
+    if (ctx.services.deps.probe("curl").state === "missing") {
+      err(`curl is required. Install: ${ctx.services.deps.spec("curl").installHint()}`)
       throw new ExitError(1)
     }
   }
 }
 
 export function validateModelFlags(ctx: Ctx): void {
+  const { err, warn } = ctx.services.logger
   if (ctx.claudeModel !== "") {
     if (!ctx.syncClaude) {
       warn("--claude-model ignored: claude target not selected")
       ctx.claudeModel = ""
-    } else if (!validateClaudeModel(ctx.repoDir, ctx.claudeModel)) {
-      printModels(ctx.repoDir, "claude")
+    } else if (!validateClaudeModel(ctx, ctx.claudeModel)) {
+      printModels(ctx, "claude")
       err(`Invalid Claude model '${ctx.claudeModel}' — use an alias above or a full claude-* ID`)
       throw new ExitError(2)
     }
@@ -214,8 +216,8 @@ export function validateModelFlags(ctx: Ctx): void {
     if (!ctx.syncCodex) {
       warn("--codex-model ignored: codex target not selected")
       ctx.codexModel = ""
-    } else if (!validateCodexModel(ctx.repoDir, ctx.codexModel)) {
-      printModels(ctx.repoDir, "codex")
+    } else if (!validateCodexModel(ctx, ctx.codexModel)) {
+      printModels(ctx, "codex")
       err(`Invalid Codex model '${ctx.codexModel}' — must match ^[A-Za-z0-9._-]+$`)
       throw new ExitError(2)
     }

package/cli/src/engine-native/services.ts

@@ -0,0 +1,96 @@
+/**
+ * Shared service factory — the single construction point for the engine's
+ * injectable capabilities (Output Policy in DESIGN.md). The Effect rim wraps
+ * these in Layers (cli/src/services.ts); the harness-private native-raw entry
+ * and engineCapture's parent-side warn call it directly, so every execution
+ * path shares one implementation.
+ */
+import {
+  DEPENDENCIES,
+  defaultProbeExecutor,
+  resolveDependency,
+  resolveLocation,
+  resolvePath,
+  resolveVersion,
+  type DependencySpec,
+  type DependencyLocation,
+  type ProbeExecutor,
+  type ProbeResult,
+  type ToolId
+} from "./deps"
+import { makeLogger, type Logger, type LoggerSinks } from "./logger"
+import { platformName, rawPlatform, type PlatformName } from "./os"
+
+export type { Logger } from "./logger"
+
+export interface DependencyManager {
+  readonly spec: (id: ToolId) => DependencySpec
+  readonly probe: (id: ToolId) => ProbeResult
+  readonly version: (id: ToolId) => string
+  readonly path: (id: ToolId) => string
+  readonly location: (id: ToolId) => DependencyLocation
+  readonly latest: (id: ToolId) => string
+  readonly warnMissing: (id: ToolId, logger: Logger, context?: string) => void
+}
+
+export interface Platform {
+  readonly raw: () => NodeJS.Platform
+  readonly name: () => PlatformName
+  readonly isWindows: () => boolean
+  readonly isLinux: () => boolean
+  readonly shellRcApplicable: () => boolean
+}
+
+export interface EngineServices {
+  readonly logger: Logger
+  readonly deps: DependencyManager
+  readonly platform: Platform
+}
+
+export interface EngineServiceOptions {
+  readonly sinks?: LoggerSinks
+}
+
+/** Platform view over an injectable platform id (tests pass e.g. "win32"). */
+export const makePlatform = (pf: NodeJS.Platform = rawPlatform()): Platform => ({
+  raw: () => pf,
+  name: () => platformName(pf),
+  isWindows: () => pf === "win32",
+  isLinux: () => pf === "linux",
+  shellRcApplicable: () => pf !== "win32"
+})
+
+/** DependencyManager whose hints default to the INJECTED platform, not the host. */
+export const makeDependencyManager = (
+  platform: Platform,
+  exec: ProbeExecutor = defaultProbeExecutor
+): DependencyManager => {
+  const warned = new Set<ToolId>()
+  return {
+    spec: (id) => {
+      const s = DEPENDENCIES[id]
+      return { ...s, installHint: (pf = platform.raw()) => s.installHint(pf) }
+    },
+    probe: (id) => resolveDependency(DEPENDENCIES[id], exec, platform.raw()),
+    version: (id) => resolveVersion(DEPENDENCIES[id], exec),
+    path: (id) => resolvePath(DEPENDENCIES[id], exec, platform.raw()),
+    location: (id) => resolveLocation(DEPENDENCIES[id], exec, platform.raw()),
+    latest: (id) => DEPENDENCIES[id].latest?.(exec) ?? "",
+    warnMissing: (id, logger, context) => {
+      if (warned.has(id)) return
+      warned.add(id)
+      const suffix = context !== undefined && context !== "" ? ` (${context})` : ""
+      logger.warn(`${id} not installed — ${DEPENDENCIES[id].installHint(platform.raw())}${suffix}`)
+    }
+  }
+}
+
+export const makeEngineServices = (opts?: EngineServiceOptions): EngineServices => {
+  const platform = makePlatform()
+  const logger = makeLogger(opts?.sinks ?? {})
+  return {
+    logger,
+    deps: makeDependencyManager(platform),
+    platform
+  }
+}

package/cli/src/engine-native/skillsSync.ts

@@ -7,10 +7,10 @@
 import { spawnSync } from "node:child_process"
 import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, rmdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
-import { capture, commandExists, isExecutable, p, which } from "./exec"
+import { p, writeFileIfChanged } from "./exec"
 import type { Ctx } from "./index"
 import { compareCodepoints } from "./jq"
-import { echo, log, warn } from "./output"
+import type { EngineServices, Platform } from "./services"
 import { ensure, field } from "./toolchain"
 
 export interface SkillsState {
@@ -58,8 +58,9 @@ function readSlugs(file: string): Array<string> {
 }
 
 function syncUniversal(ctx: Ctx, state: SkillsState, skillsDir: string, manifest: string): void {
-  if (!commandExists("node")) {
-    warn("node/npx not in PATH — skipping universal skills bootstrap (install Node.js to enable)")
+  const { change, echo, verbose, warn } = ctx.services.logger
+  if (ctx.services.deps.probe("npx").state === "missing") {
+    ctx.services.deps.warnMissing("npx", ctx.services.logger, "skipping universal skills bootstrap")
     return
   }
 
@@ -103,12 +104,14 @@ function syncUniversal(ctx: Ctx, state: SkillsState, skillsDir: string, manifest
   state.present = added + already
 
   if (added > 0) {
-    log(`Universal skills synced (+${added} new, ${already} already present)`)
+    change(`Universal skills synced (+${added} new, ${already} already present)`)
+    ctx.nextStepTriggers.skillsRestart = true
   } else {
-    log(`Universal skills already in sync (${already} present)`)
+    verbose(`Universal skills already in sync (${already} present)`)
   }
   if (healed > 0) {
-    log(`Claude per-tool symlinks healed (+${healed}) — canonical present, ~/.claude/skills/<name> was missing or broken`)
+    change(`Claude per-tool symlinks healed (+${healed}) — canonical present, ~/.claude/skills/<name> was missing or broken`)
+    ctx.nextStepTriggers.skillsRestart = true
   }
   if (failed > 0) {
     warn(`${failed} skill install(s) failed — re-run sync or install manually with: npx skills add <slug> -g -y -a claude-code codex`)
@@ -125,6 +128,7 @@ function isDir(path: string): boolean {
 
 /** skills::heal_claude_symlink — true when a heal occurred. */
 function healClaudeSymlink(ctx: Ctx, skillsDir: string, base: string): boolean {
+  const { echo, warn } = ctx.services.logger
   const canonical = p(skillsDir, base)
   const claudeSkillsDir = p(ctx.home, ".claude", "skills")
   const claudeLink = p(claudeSkillsDir, base)
@@ -138,7 +142,7 @@ function healClaudeSymlink(ctx: Ctx, skillsDir: string, base: string): boolean {
     if (current === relTarget) return false
     // win32: `npx skills add` creates absolute symlinks/junctions — any link
     // that RESOLVES to the canonical dir is healthy, not stale.
-    if (process.platform === "win32" && realpathEquals(claudeLink, canonical)) return false
+    if (ctx.services.platform.isWindows() && realpathEquals(claudeLink, canonical)) return false
     if (ctx.dryRun) {
       echo(`[dry-run] would replace stale Claude symlink: ~/.claude/skills/${base} -> ${current}  (correct: ${relTarget})`)
       return true
@@ -156,7 +160,7 @@ function healClaudeSymlink(ctx: Ctx, skillsDir: string, base: string): boolean {
   }
 
   mkdirSync(claudeSkillsDir, { recursive: true })
-  return linkOrCopy(relTarget, claudeLink)
+  return linkOrCopyWithWarnings(relTarget, claudeLink, ctx.services)
 }
 
 function lstat(path: string): ReturnType<typeof lstatSync> | undefined {
@@ -201,10 +205,10 @@ function removeLink(path: string): boolean {
 }
 
 /** skills::_link_or_copy — real symlink preferred, copy fallback (Windows). */
-export function linkOrCopy(target: string, link: string): boolean {
+export function linkOrCopy(target: string, link: string, platform: Platform): boolean {
   removeLink(link)
   try {
-    symlinkSync(target, link, process.platform === "win32" ? "dir" : undefined)
+    symlinkSync(target, link, platform.isWindows() ? "dir" : undefined)
   } catch {
     // fall through to the copy fallback below
   }
@@ -216,47 +220,56 @@ export function linkOrCopy(target: string, link: string): boolean {
   } catch {
     // fall through to the existence check below
   }
-  if (existsSync(link)) {
-    warn(`symlinks unsupported here — ${link} is a copy (refreshed on sync; enable Windows Developer Mode for real links)`)
-    return true
+  return existsSync(link)
+}
+
+function linkOrCopyWithWarnings(target: string, link: string, services: EngineServices): boolean {
+  const linked = linkOrCopy(target, link, services.platform)
+  if (!linked) {
+    services.logger.warn(`could not create ${link} (symlink and copy both failed)`)
+  } else if (lstat(link)?.isSymbolicLink() !== true) {
+    services.logger.warn(`symlinks unsupported here — ${link} is a copy (refreshed on sync; enable Windows Developer Mode for real links)`)
   }
-  warn(`could not create ${link} (symlink and copy both failed)`)
-  return false
+  return linked
 }
 
 // ------------------------------------------------- toolchain callbacks ----
 
 /** skills::_agent_browser_install. */
-export function agentBrowserInstall(mode: "install" | "upgrade", version: string): number {
+export function agentBrowserInstall(mode: "install" | "upgrade", version: string, services: EngineServices): number {
+  const { change, verbose, warn } = services.logger
   const verb = mode === "upgrade" ? "Upgrading" : "Installing"
   const pkg = version !== "" ? `agent-browser@${version}` : "agent-browser"
-  const installFlags = process.platform === "linux" ? ["--with-deps"] : []
+  const installFlags = services.platform.isLinux() ? ["--with-deps"] : []
 
-  log(`${verb} agent-browser CLI via npm${version !== "" ? ` (pinned ${version})` : ""}...`)
+  verbose(`${verb} agent-browser CLI via npm${version !== "" ? ` (pinned ${version})` : ""}...`)
   if (spawnSync("npm", ["install", "-g", pkg], { stdio: "ignore" }).status !== 0) {
     warn(`npm install -g ${pkg} failed. Try manually: npm install -g ${pkg}`)
     return 1
   }
 
   if (mode === "install") {
-    log("Downloading Chrome for Testing (~175 MB; sudo may be requested for system libs on Linux)...")
+    warn("Downloading Chrome for Testing (~175 MB; sudo may be requested for system libs on Linux)...")
     if (spawnSync("agent-browser", ["install", ...installFlags], { stdio: "inherit" }).status !== 0) {
       warn(`agent-browser install failed. Re-run manually: agent-browser install ${installFlags.join(" ")}`)
       return 1
     }
   }
-  const out = capture("agent-browser", ["--version"])
+  const out = services.deps.version("agent-browser")
   const fields = (out.split("\n")[0] ?? "").trim().split(/[ \t]+/)
   const version2 = out !== "" ? fields[fields.length - 1] ?? "version unknown" : "version unknown"
-  log(`agent-browser CLI ready (${version2})`)
+  change(`agent-browser CLI ready (${version2})`)
   return 0
 }
 
 function syncAgentBrowserCli(ctx: Ctx, manifest: string): void {
+  const { warn } = ctx.services.logger
   if (!existsSync(manifest) || !readFileSync(manifest, "utf8").split("\n").includes("vercel-labs/agent-browser")) return
 
-  if (!commandExists("npm")) {
-    if (!ctx.dryRun) warn("npm not found — cannot auto-install agent-browser CLI. Install Node.js, then re-run sync.")
+  if (ctx.services.deps.probe("npm").state === "missing") {
+    if (!ctx.dryRun) {
+      ctx.services.deps.warnMissing("npm", ctx.services.logger, "cannot auto-install agent-browser CLI; re-run sync after installing")
+    }
     return
   }
 
@@ -267,21 +280,16 @@ function syncAgentBrowserCli(ctx: Ctx, manifest: string): void {
 
 /** skills::_find_bun — resolved bun path or "". */
 function findBun(ctx: Ctx): string {
-  const onPath = which("bun")
-  if (onPath !== "") return onPath
-  const bunInstall = process.env["BUN_INSTALL"] !== undefined && process.env["BUN_INSTALL"] !== "" ? process.env["BUN_INSTALL"] : p(ctx.home, ".bun")
-  for (const cand of [p(bunInstall, "bin", "bun"), p(ctx.home, ".bun", "bin", "bun")]) {
-    if (isExecutable(cand)) return cand
-  }
-  return ""
+  return ctx.services.deps.path("bun")
 }
 
 /** skills::_bun_bootstrap — bun path or "" after a failed bootstrap. */
-export function bunBootstrap(ctx: Ctx): string {
+export function bunBootstrap(ctx: Ctx, services: EngineServices): string {
+  const { change, warn } = services.logger
   let bun = findBun(ctx)
   if (bun !== "") return bun
 
-  if (!commandExists("curl")) {
+  if (services.deps.probe("curl").state === "missing") {
     warn("Bun and curl both missing — cannot bootstrap Bun. Install Bun manually, then re-run sync.")
     return ""
   }
@@ -298,41 +306,44 @@ export function bunBootstrap(ctx: Ctx): string {
     warn("Bun install failed. Install manually: curl -fsSL https://bun.sh/install -o /tmp/bun.sh && bash /tmp/bun.sh")
     return ""
   }
-  const v = capture(bun, ["--version"])
-  log(`Bun installed (${v !== "" ? v : "version unknown"})`)
+  const version = services.deps.version("bun")
+  change(`Bun installed (${version !== "" ? version : "version unknown"})`)
   return bun
 }
 
 /** skills::_effect_solutions_install. */
-export function effectSolutionsInstall(ctx: Ctx): (mode: "install" | "upgrade", version: string) => number {
-  return (mode, version) => {
+export function effectSolutionsInstall(
+  ctx: Ctx
+): (mode: "install" | "upgrade", version: string, services: EngineServices) => number {
+  return (mode, version, services) => {
+    const { change, verbose, warn } = services.logger
     const verb = mode === "upgrade" ? "Upgrading" : "Installing"
     const pkg = `effect-solutions@${version !== "" ? version : "latest"}`
 
-    const bun = bunBootstrap(ctx)
+    const bun = bunBootstrap(ctx, services)
     if (bun === "") return 1
 
-    log(`${verb} effect-solutions CLI via bun${version !== "" ? ` (pinned ${version})` : ""}...`)
+    verbose(`${verb} effect-solutions CLI via bun${version !== "" ? ` (pinned ${version})` : ""}...`)
     if (spawnSync(bun, ["add", "-g", pkg], { stdio: "ignore" }).status !== 0) {
       warn(`bun add -g ${pkg} failed. Try manually: bun add -g ${pkg}`)
       return 1
     }
 
-    const gbin = capture(bun, ["pm", "-g", "bin"])
+    const location = services.deps.location("effect-solutions")
+    const gbin = location.binDir
     // win32: bun writes an .exe shim (not the bare Unix name), and the
     // ~/.local/bin link step below is Unix-only plumbing (non-interactive
     // agent PATH) — bun's global bin is already the Windows PATH entry.
-    if (process.platform === "win32") {
-      const found = gbin !== "" && ["exe", "cmd", "bunx"].some((ext) => existsSync(p(gbin, `effect-solutions.${ext}`)))
-      if (found) log(`effect-solutions CLI ready (${gbin})`)
+    if (services.platform.isWindows()) {
+      if (location.path !== "") change(`effect-solutions CLI ready (${gbin})`)
       else warn(`effect-solutions installed but no shim found under '${gbin !== "" ? gbin : "<unknown>"}' — check bun pm -g bin`)
       return 0
     }
-    if (gbin !== "" && isExecutable(p(gbin, "effect-solutions"))) {
+    if (location.path !== "") {
       mkdirSync(p(ctx.home, ".local", "bin"), { recursive: true })
-      linkOrCopy(bun, p(ctx.home, ".local", "bin", "bun"))
-      linkOrCopy(p(gbin, "effect-solutions"), p(ctx.home, ".local", "bin", "effect-solutions"))
-      log("effect-solutions CLI ready (linked bun + effect-solutions into ~/.local/bin)")
+      linkOrCopyWithWarnings(bun, p(ctx.home, ".local", "bin", "bun"), services)
+      linkOrCopyWithWarnings(location.path, p(ctx.home, ".local", "bin", "effect-solutions"), services)
+      change("effect-solutions CLI ready (linked bun + effect-solutions into ~/.local/bin)")
     } else {
       warn(`effect-solutions installed but binary not found under '${gbin !== "" ? gbin : "<unknown>"}' — link it onto PATH manually`)
     }
@@ -341,6 +352,7 @@ export function effectSolutionsInstall(ctx: Ctx): (mode: "install" | "upgrade",
 }
 
 function syncEffectSolutionsCli(ctx: Ctx): void {
+  const { warn } = ctx.services.logger
   const settings = p(ctx.repoDir, "SoT", ".claude", "settings.json")
   if (!existsSync(settings)) return
   if (!/"effect-kit@docks"[ \t]*:[ \t]*true/.test(readFileSync(settings, "utf8"))) return
@@ -353,6 +365,7 @@ function syncEffectSolutionsCli(ctx: Ctx): void {
 // ----------------------------------------------------- prune + snapshot ----
 
 function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string): void {
+  const { change, echo, warn } = ctx.services.logger
   if (!existsSync(snapshot)) {
     if (ctx.dryRun) {
       echo(
@@ -383,7 +396,10 @@ function reconcileRemovals(ctx: Ctx, manifest: string, snapshot: string): void {
     }
   }
 
-  if (removed > 0) log(`Kit-managed skills removed (-${removed})`)
+  if (removed > 0) {
+    change(`Kit-managed skills removed (-${removed})`)
+    ctx.nextStepTriggers.skillsRestart = true
+  }
   if (failed > 0) warn(`${failed} skill remove(s) failed — re-run with --prune or run: npx skills remove -g -y -a '*' -s <name>`)
 }
 
@@ -392,18 +408,21 @@ function updateSnapshot(ctx: Ctx, manifest: string, snapshot: string): void {
 
   mkdirSync(ctx.agentsDir, { recursive: true })
   const sorted = [...new Set(readSlugs(manifest))].sort(compareCodepoints)
-  writeFileSync(snapshot, sorted.length > 0 ? `${sorted.join("\n")}\n` : "")
+  writeFileIfChanged(snapshot, sorted.length > 0 ? `${sorted.join("\n")}\n` : "")
 }
 
 // -------------------------------------------------------------- summary ----
 
 export function skillsSummary(ctx: Ctx, state: SkillsState): void {
+  const { echo } = ctx.services.logger
   echo(`Skills:   ${p(ctx.agentsDir, "skills")}`)
   if (!ctx.dryRun) {
     echo(`          ${state.present} universal skill(s) installed`)
   }
 }
 
-export function skillsNextSteps(): void {
-  echo("Restart Claude Code (and Codex) to discover newly installed universal skills.")
+export function skillsNextSteps(ctx: Ctx): Array<string> {
+  return ctx.verbose || ctx.nextStepTriggers.skillsRestart
+    ? ["Restart Claude Code (and Codex) to discover newly installed universal skills."]
+    : []
 }