docks-kit 0.1.4 → 0.2.0

package/README.md

@@ -105,7 +105,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 |----------|-----|-------------|
 | Linux | ✅ native | ✅ native |
 | macOS (x64/arm64) | ✅ native | ✅ native |
-| Windows | ✅ native binary (`.exe` and `bun add -g` CI-verified) | ✅ EngineNative (TS, default engine — no Git Bash); real-machine verify pending — RTK hooks are native too (rtk ≥0.37.2) |
+| Windows | ✅ native binary (`.exe` and `bun add -g` CI-verified) | ✅ EngineNative (TS, default engine — no Git Bash); real-machine verified 2026-07-09 — RTK hooks are native too (rtk ≥0.37.2) |
 
 Details: `docks-kit docs platforms`.
 

package/SoT/.codex/config.toml

@@ -1,4 +1,4 @@
-model = "gpt-5.5"
+model = "gpt-5.6-sol"
 model_reasoning_effort = "xhigh"
 plan_mode_reasoning_effort = "xhigh"
 model_reasoning_summary = "detailed"

package/SoT/models.json

@@ -16,9 +16,12 @@
     ]
   },
   "codex": {
-    "verified": "2026-07-08",
+    "verified": "2026-07-09",
     "models": [
-      { "id": "gpt-5.5", "kind": "id", "note": "Codex default — the kit SoT pin" },
+      { "id": "gpt-5.6-sol", "kind": "id", "note": "GPT-5.6 Sol — frontier, recommended default; the kit SoT pin" },
+      { "id": "gpt-5.6-terra", "kind": "id", "note": "GPT-5.6 Terra — balanced tier" },
+      { "id": "gpt-5.6-luna", "kind": "id", "note": "GPT-5.6 Luna — fast/light tier" },
+      { "id": "gpt-5.5", "kind": "id", "note": "previous generation" },
       { "id": "gpt-5.5-codex", "kind": "id", "note": "codex-tuned gpt-5.5" },
       { "id": "gpt-5.1", "kind": "id", "note": "previous generation" },
       { "id": "gpt-5", "kind": "id", "note": "previous generation" },

package/SoT/toolchain.json

@@ -3,6 +3,7 @@
   "tools": {
     "jq":     { "kind": "required", "note": "deployed Claude hooks/statusline assets" },
     "curl":   { "kind": "required", "note": "installers + usage fetch" },
+    "git":    { "kind": "check", "note": "plugin marketplaces (claude/codex clone them) + kit checkout updates" },
     "node":   { "kind": "check", "note": "hosts npm globals (agent-browser, LSP servers)" },
     "npm":    { "kind": "check", "note": "npm-global installer" },
     "claude": { "kind": "check", "floor": "2.1.170", "note": "kit floor — `best` alias + Fable 5 need >=2.1.170 (mirrors settings minimumVersion)" },

package/cli/docs/flags.md

@@ -20,6 +20,7 @@ docks-kit sync claude agents        # two
 | `--prune` | Uninstall kit-managed installs not in SoT: plugins, marketplaces, universal skills |
 | `--skip-rtk` | Skip optional tool bootstrap (RTK, bubblewrap) |
 | `--yes` | Auto-accept toolchain above-verified prompts (containers/CI) |
+| `--verbose` / `-v` | Also print no-op confirmations (already in sync, up to date, left as-is); accepted on `sync`, `model`, and `toolchain` |
 
 ## Per-tool flags
 

package/cli/docs/overview.md

@@ -21,6 +21,9 @@ AI-assisted dev environment on every machine.
 ## Design rules
 
 - **Idempotent**: every sync step is safe to re-run; no-change syncs are no-ops.
+- **Quiet on no-ops**: by default a re-run prints only real changes, warnings
+  (with a platform-correct install command when a tool is missing), and the
+  summary; `--verbose` / `-v` also prints the no-op confirmations.
 - **Additive by default**: user-only keys/plugins/skills survive a plain sync.
   Reconciliation toward the SoT is explicit: `--reconcile` (settings) and
   `--prune` (plugins/marketplaces/skills).

package/cli/docs/platforms.md

@@ -4,7 +4,7 @@
 |----------|-----------------|-------------|-------|
 | Linux | native | EngineNative (TS) | Primary target |
 | macOS | native (x64 + arm64) | EngineNative (TS) | Release binary or Bun source path |
-| Windows | native (`.exe` / `bun add -g`, CI-verified) | EngineNative (TS) — no Git Bash | Real-machine verify pending |
+| Windows | native (`.exe` / `bun add -g`, CI-verified) | EngineNative (TS) — no Git Bash | Real-machine verified 2026-07-09 |
 
 EngineNative is the only supported engine on all platforms. `DOCKS_KIT_ENGINE=bash`
 now exits with the removed-engine message and points at the `bash-engine-final`
@@ -38,7 +38,8 @@ spawning (npm), toolchain gate branches (`.github/workflows/parity.yml`,
 Deployed hook/statusline assets stay shell scripts by design — Claude Code on
 Windows executes them through its own Git Bash.
 
-**Status: supported, pending one manual gate** — a real-machine interactive
-verify (Claude Code loads the synced `%USERPROFILE%\.claude`, the rtk hook
-fires, hook/statusline commands run or are knowingly skipped) tracked as
-step 9 of the `windows-support` plan.
+**Status: supported** — real-machine verified 2026-07-09 (Claude Code loads
+the synced `%USERPROFILE%\.claude`; full sync, self-update, plugin passes,
+universal skills, and agent-browser all green on native PowerShell). Needs
+git on PATH for plugin marketplaces; rtk installs natively via its Windows
+release (the kit's auto-install is Unix-only).

package/cli/src/commands/model.ts

@@ -13,26 +13,30 @@ const value = Args.text({ name: "value" }).pipe(
 const dryRun = Options.boolean("dry-run").pipe(
   Options.withDescription("Preview without applying")
 )
+const verbose = Options.boolean("verbose").pipe(
+  Options.withAlias("v"),
+  Options.withDescription("Also print no-op confirmations (already in sync, up to date)")
+)
 
 const KEEP = "__keep__"
 
 export const modelCommand = Command.make(
   "model",
-  { tool, value, dryRun },
+  { tool, value, dryRun, verbose },
   (config) =>
     Effect.gen(function* () {
       if (config.tool !== "claude" && config.tool !== "codex") {
         return yield* bail(`Unknown tool '${config.tool}' (valid: claude, codex)`)
       }
       const t = config.tool as Tool
-      const dry = config.dryRun ? ["--dry-run"] : []
+      const dry = [...(config.dryRun ? ["--dry-run"] : []), ...(config.verbose ? ["--verbose"] : [])]
 
       if (Option.isSome(config.value)) {
         return yield* engine(["model", t, config.value.value, ...dry])
       }
 
       // No value: show current (engine prints deployed + SoT + catalog) …
-      yield* engine(["model", t])
+      yield* engine(["model", t, ...(config.verbose ? ["--verbose"] : [])])
 
       // … and offer an interactive picker when attached to a terminal.
       if (!process.stdin.isTTY || !process.stdout.isTTY) return

package/cli/src/commands/sync.ts

@@ -4,13 +4,15 @@ import { spawnSync } from "node:child_process"
 import { existsSync } from "node:fs"
 import { join } from "node:path"
 import { bail, engine } from "../engine"
+import type { Logger } from "../engine-native/logger"
 import { kitHome } from "../kitHome"
 import { modelCatalog, type Tool } from "../manifests"
+import { LoggerService } from "../services"
 
 /** Best-effort update autodetection: nudge (never block, never fail) when
  * the kit checkout is behind its upstream. Silent on detached HEADs, no
  * upstream, no network, no git. */
-const updateNudge = (): void => {
+const updateNudge = (logger: Logger): void => {
   try {
     const home = kitHome()
     if (!existsSync(join(home, ".git"))) return
@@ -21,7 +23,7 @@ const updateNudge = (): void => {
     })
     const behind = (res.stdout ?? "").trim()
     if (res.status === 0 && behind !== "" && behind !== "0") {
-      process.stderr.write(`\x1b[1;33m[warn]\x1b[0m kit checkout is ${behind} commit(s) behind its upstream — run: docks-kit update\n`)
+      logger.warn(`kit checkout is ${behind} commit(s) behind its upstream — run: docks-kit update`)
     }
   } catch {
     // nudge only — a sync must never fail because the update check did
@@ -75,6 +77,10 @@ const skipRtk = Options.boolean("skip-rtk").pipe(
 const yes = Options.boolean("yes").pipe(
   Options.withDescription("Auto-accept toolchain prompts (containers/CI)")
 )
+const verbose = Options.boolean("verbose").pipe(
+  Options.withAlias("v"),
+  Options.withDescription("Also print no-op confirmations (already in sync, up to date, left as-is)")
+)
 const claudeModel = Options.text("claude-model").pipe(
   Options.withDescription("Deploy-time modifier: set deployed Claude model (see `docks-kit models claude`)"),
   Options.optional
@@ -106,6 +112,7 @@ export const syncCommand = Command.make(
     prune,
     skipRtk,
     yes,
+    verbose,
     claudeModel,
     claudeCompactWindow,
     claudePermissive,
@@ -138,6 +145,7 @@ export const syncCommand = Command.make(
       if (config.prune) args.push("--prune")
       if (config.skipRtk) args.push("--skip-rtk")
       if (config.yes) args.push("--yes")
+      if (config.verbose) args.push("--verbose")
       if (config.claudePermissive) args.push("--claude-permissive")
       Option.map(config.claudeModel, (m) => args.push(`--claude-model=${m}`))
       Option.map(config.claudeCompactWindow, (w) => args.push(`--claude-compact-window=${w}`))
@@ -152,7 +160,10 @@ export const syncCommand = Command.make(
 
       // Not on --dry-run: the nudge's git fetch writes FETCH_HEAD/remote
       // refs, and a preview command must not mutate the checkout.
-      if (!config.dryRun) yield* Effect.sync(updateNudge)
+      if (!config.dryRun) {
+        const logger = yield* LoggerService
+        yield* Effect.sync(() => updateNudge(logger))
+      }
       yield* engine(args)
     })
 ).pipe(

package/cli/src/commands/toolchain.ts

@@ -15,15 +15,19 @@ const tool = Args.text({ name: "tool" }).pipe(
 const yes = Options.boolean("yes").pipe(
   Options.withDescription("Auto-accept above-verified installs")
 )
+const verbose = Options.boolean("verbose").pipe(
+  Options.withAlias("v"),
+  Options.withDescription("Also print no-op confirmations (present, up to date)")
+)
 
-export const toolchainCommand = Command.make("toolchain", { op, tool, yes }, (config) =>
+export const toolchainCommand = Command.make("toolchain", { op, tool, yes, verbose }, (config) =>
   Effect.gen(function* () {
     const operation = Option.getOrElse(config.op, () => "check")
-    const flags = config.yes ? ["--yes"] : []
+    const flags = [...(config.yes ? ["--yes"] : []), ...(config.verbose ? ["--verbose"] : [])]
 
     switch (operation) {
       case "check":
-        return yield* engine(["toolchain", "check"])
+        return yield* engine(["toolchain", "check", ...(config.verbose ? ["--verbose"] : [])])
       case "ensure": {
         const t = Option.getOrUndefined(config.tool)
         if (t === undefined || !MANAGED.includes(t)) {

package/cli/src/engine-native/DESIGN.md

@@ -37,6 +37,76 @@ explicit removed-engine diagnostic and exits 2 with the recovery tag message.
 - **Backups precede mutation.** Deployed settings/config files write `.bak`
   backups before replacement.
 
+## Output Policy (log UX contract)
+
+The default run reads like a change report: only actual changes, actionable
+warnings, and the summary. Status-quo confirmations exist but are opt-in.
+(Rationale + full call-site audit: `docs/plans/active/cli-log-ux-overhaul.md`.)
+
+### Channels and levels
+
+| Emitter | Channel | Default | `--verbose` | Prefix / form |
+|---|---|---|---|---|
+| `error(msg)` | stderr | shown | shown | `[err]` red (`\x1b[1;31m`) |
+| `warn(msg)` | stderr | shown | shown | `[warn]` yellow (`\x1b[1;33m`) |
+| `change(msg)` | stderr | shown | shown | `[ok]` green (`\x1b[1;32m`) — ONLY after an operation actually mutated |
+| `verbose(msg)` | stderr | hidden | shown | `[ok]` green — no-op confirmations ("already …", "present", "up to date", "left as-is"), skips |
+| `data(line)` | stdout | shown | shown | bare — dry-run report lines, `status --json`, summary block, usage text |
+
+- stdout is data, stderr is logs — the logger NEVER writes to stdout
+  (`engineCapture` depends on it).
+- **Dry-run is a complete inspection report**: `[dry-run]` lines are `data`,
+  printed unfiltered at every verbosity.
+- Prefixes and ANSI codes are stable golden surface; the level controls
+  visibility, not the prefix.
+
+### Change detection
+
+Every mutating operation reports `changed: boolean`. A changed outcome logs
+via `change`; an unchanged outcome logs via `verbose`. Operations that today
+rewrite deployed files unconditionally may skip a provably-identical rewrite —
+each such skip is an intentional behavior change named in its golden diff.
+
+### Missing dependencies
+
+Exactly one deduplicated warn per missing tool per run, uniform shape:
+`[warn] <tool> not installed — <platform-correct install command>`, sourced
+from the dependency registry (`deps.ts`). Required tools keep their current
+exit behavior — the error carries the same install hint.
+
+### Summary and next steps
+
+`model` and `toolchain` modes have no separate summary block by design —
+their stdout IS the deliverable (`deployed:`/`SoT:` + catalog lines for
+`model`; the report table for `toolchain check`), so nothing prints after
+it. The schema below applies to `sync` only.
+
+The `--- Sync complete ---` block (stdout, `data`) prints on every run,
+including dry-run, with the per-target inventory lines (`Claude:`/`Hooks:`/
+`RTK:`/`Plugins:`/`Codex:`/`Skills:`). Next-step advice lines print only when
+their trigger changed this run (plugins changed → `/reload-plugins` line;
+hooks/env changed → restart line; skills changed → discovery line) or under
+`--verbose`.
+
+### Platform seam
+
+All platform branching routes through `os.ts` — the only engine module that
+reads `process.platform`, with one named exemption: `exec.ts`'s path/exec
+primitives (`commandExists` PATHEXT resolution and `X_OK` probing) stay
+self-contained because they sit below the seam. `deps.ts` install hints
+default their platform from `os.ts` and keep the parameter injectable for
+tests.
+
+### Verbosity plumbing
+
+`--verbose` / `-v` on the public `sync`, `model`, and `toolchain` commands;
+`DOCKS_KIT_VERBOSE=1` selects it on the harness-private raw channel (same
+`${VAR:-default}` contract as the other `Ctx` env globals). The default
+service factory returns a raw Logger. `runEngineNative` wraps the default or
+injected Logger with explicit delegates and owns the sole `ctx.verbose` gate.
+There is no factory-level verbosity callback, module-global verbosity flag, or
+active logger binding.
+
 ## Module Map
 
 | Module | Owns |
@@ -53,8 +123,11 @@ explicit removed-engine diagnostic and exits 2 with the recovery tag message.
 | `modes.ts` | direct `model` and `toolchain` modes |
 | `models.ts` | model catalog listing and validation |
 | `jq.ts` | JSON helpers that preserve jq-style merge/order/stringify behavior where the deployed file contract needs it |
-| `exec.ts` | path helpers, command probes, capture/spawn wrappers, Windows command resolution |
-| `output.ts` | stable stdout/stderr emitters |
+| `exec.ts` | path helpers, command probes, capture/spawn wrappers, Windows command resolution, change-detecting write/copy helpers |
+| `logger.ts` | Logger shape + stable raw stdout/stderr sink factory; the run-scoped verbosity gate lives in `index.ts` |
+| `deps.ts` | external-tool registry: identity, requirement class, presence probe, platform-correct install hints, per-manager missing-tool dedup; callers supply the current run Logger to `warnMissing` |
+| `os.ts` | platform capability seam — the single `process.platform` reader (`platformName`, `isWindows`, `isLinux`, shell-rc applicability) |
+| `services.ts` | shared raw-Logger + DependencyManager + Platform factory; wrapped in Effect Layers at `cli/src/services.ts`, with the run-scoped Logger gate applied only by `runEngineNative` |
 
 ## Windows Specifics
 

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

@@ -7,9 +7,9 @@ import { readFileSync, renameSync, writeFileSync } from "node:fs"
 
 import type { Ctx } from "./index"
 import { isObject, jqStringify, parseJson } from "./jq"
-import { echo, err, log, warn } from "./output"
 
 export function syncClaudeModel(ctx: Ctx, model: string): void {
+  const { change, echo, err, verbose, warn } = ctx.services.logger
   const userSettings = p(ctx.home, ".claude", "settings.json")
 
   if (model === "") return
@@ -42,7 +42,13 @@ export function syncClaudeModel(ctx: Ctx, model: string): void {
       doc["model"] = model
     }
   }
-  writeFileSync(`${userSettings}.tmp`, jqStringify(doc))
+  const out = jqStringify(doc)
+  if (out === text) {
+    verbose(`Model: deployed settings model already ${model === "default" ? "unset (account default)" : model}`)
+    return
+  }
+  writeFileSync(`${userSettings}.tmp`, out)
   renameSync(`${userSettings}.tmp`, userSettings)
-  log(`Model: deployed settings model set to ${model} (SoT unchanged; flag-less sync reverts)`)
+  change(`Model: deployed settings model set to ${model} (SoT unchanged; flag-less sync reverts)`)
+  ctx.nextStepTriggers.claudeRestart = true
 }