docks-kit 0.1.5 → 0.3.0

package/AGENTS.md

@@ -22,7 +22,7 @@ Tool-specific instructions live alongside this file:
 | `install.sh` | Global installer |
 | `.github/workflows/release-cli.yml` | `cli-v*` release binaries + npm publish |
 | `README.md` | Front door |
-| `package.json` / `bun.lock` | npm package: `bin` = `cli/src/main.ts`; bundles `cli/` + `SoT/` |
+| `package.json` / `bun.lock` | npm package: `bin` = `cli/src/main.ts`; bundles `cli/` with the generated in-memory SoT payload |
 | `SoT/.agents/skills.txt` | Universal-skill manifest. One [agentskills.io](https://agentskills.io) slug per line; EngineNative runs `npx skills add` for each missing entry into `~/.agents/skills/`, where Codex et al. discover it natively and Claude Code follows a symlink at `~/.claude/skills/` |
 | `notification.mp3` | Audio asset for Notification hooks (consumed by Claude Code today; tool-agnostic file) |
 | `docs/plans/` | Multi-commit work-item plans (`active/` with status in frontmatter, plus `finished/` archive). Convention: `docs/plans/AGENTS.md` |

package/README.md

@@ -25,8 +25,9 @@ see `./docks-kit docs install`.
 
 **No-Bun recovery path**:
 
-Download the platform release binary from GitHub Releases and run it from a
-kit checkout, or set `DOCKS_KIT_HOME` to the checkout containing `SoT/`.
+Download the platform release binary from GitHub Releases and run it directly.
+The executable carries the generated sync payload; no checkout or adjacent
+`SoT/` directory is required.
 
 Prerequisites for source/global installs: Bun plus `jq` and `curl` for sync
 preflight; Node/npm for npm-global tools.
@@ -93,6 +94,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 | `SoT/models.json` | Kit-verified model catalog |
 | `SoT/toolchain.json` | Verified-version floors |
 | `cli/src/engine-native/` | EngineNative sync/model/toolchain implementation |
+| `cli/src/generated/sotPayload.ts` | Generated in-memory payload used by standalone and npm installs |
 | `cli/` | docks-kit CLI (Effect-TS on Bun) + bundled docs topics |
 | `docks-kit` | Launcher (binary → bun-from-source) |
 | `install.sh` | Global installer (Bun bootstrap + `bun add -g`) |
@@ -105,7 +107,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`.
 
@@ -113,8 +115,8 @@ Details: `docks-kit docs platforms`.
 
 Tagging `cli-v*` builds five standalone binaries (+ SHA256SUMS) and attaches
 them to the GitHub release; npm publish runs when the `NPM_TOKEN` secret is
-configured. Package bundles the CLI + SoT, so npm releases are versioned config
-snapshots.
+configured. Package bundles the CLI + generated payload, so npm releases are
+versioned config snapshots without shipping the authoring `SoT/` tree.
 
 ## Deeper docs
 

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/install.md

@@ -21,10 +21,10 @@ docks-kit sync
 bunx docks-kit status
 ```
 
-The npm package bundles the CLI and the SoT — releases are versioned config
-snapshots. Kit-home resolution: `DOCKS_KIT_HOME` env → nearest ancestor
-directory containing `SoT/` + `package.json` (a checkout wins over the bundled
-copy) → the package's own bundled SoT.
+The npm package bundles the CLI and its generated in-memory payload — releases
+are versioned config snapshots without publishing the authoring `SoT/` tree.
+Kit-home resolution remains available for checkout/package update behavior and
+display paths, but sync reads do not depend on it.
 
 ## 3. curl installer (Unix-only)
 
@@ -44,12 +44,10 @@ kit before. The installer bootstraps Bun when absent, runs
 Two supported paths (CI-verified on windows-2025, native PowerShell):
 
 - **Compiled binary** — `docks-kit-windows-x64.exe` release asset. No Bun,
-  no Git Bash: the exe embeds the runtime and EngineNative runs in-process.
-  It still needs the SoT it deploys — run it from inside a kit checkout, or
-  point `DOCKS_KIT_HOME` at one.
+  no Git Bash: the exe embeds the runtime and generated payload, and
+  EngineNative runs in-process from any working directory.
 - **`bun add -g docks-kit`** — bun creates a working shim for the
-  `#!/usr/bin/env bun` bin; outside a checkout the package's own bundled
-  SoT is used.
+  `#!/usr/bin/env bun` bin; the package carries the same generated payload.
 
 `install.sh` is not a Windows path.
 
@@ -72,8 +70,8 @@ nudges when the checkout is stale (silent offline / detached / no git).
 ## No-Bun recovery
 
 No Bun or constrained sandbox: download the platform release binary from GitHub
-Releases and run it from inside a kit checkout, or set `DOCKS_KIT_HOME` to the
-checkout containing `SoT/`.
+Releases and run it directly. No checkout or `DOCKS_KIT_HOME` is required for
+sync/config reads.
 
 ## Prerequisites
 

package/cli/docs/overview.md

@@ -14,6 +14,7 @@ AI-assisted dev environment on every machine.
 | `SoT/.agents/` | Universal agent skills manifest (agentskills.io standard) |
 | `SoT/models.json` | Kit-verified model catalog (see `docks-kit docs models`) |
 | `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
+| `cli/src/generated/sotPayload.ts` | Deterministic generated payload embedded in standalone/npm execution |
 | `cli/src/engine-native/` | EngineNative mutation logic for sync/model/toolchain |
 | `cli/` | This CLI (Effect-TS on Bun) plus bundled docs |
 | `docks-kit` | Launcher: compiled binary → bun-from-source, with Bun auto-install |
@@ -21,6 +22,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).
@@ -28,6 +32,8 @@ AI-assisted dev environment on every machine.
   changes, and a later flag-less sync reverts them (`docks-kit docs modifiers`).
 - **Engine/CLI split**: the CLI adds UX (typed flags, pickers, docs, JSON);
   EngineNative owns mutation. No-Bun recovery is a platform release binary.
+- **Authoring/runtime split**: changes begin in `SoT/`; build/prepack freshness
+  checks keep the generated in-memory payload byte-identical for every runtime.
 
 ## Where to go next
 

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`
@@ -16,12 +16,10 @@ Supported entrypoints (both verified in CI on windows-2025 under native
 PowerShell — see `.github/workflows/windows-entrypoints.yml`):
 
 - **`docks-kit-windows-x64.exe`** (release asset) — the no-toolchain path.
-  No Bun, no Git Bash; the exe embeds the runtime and EngineNative runs
-  in-process. It still needs the SoT it deploys: run from a kit checkout or
-  set `DOCKS_KIT_HOME`.
+  No Bun, no Git Bash; the exe embeds the runtime and generated payload, and
+  EngineNative runs in-process from any working directory.
 - **`bun add -g docks-kit`** — bun creates a working Windows shim for the
-  `#!/usr/bin/env bun` bin; outside a checkout kit-home resolves to the
-  package's own bundled SoT.
+  `#!/usr/bin/env bun` bin; the package carries the same generated payload.
 - `install.sh` is **Unix-only** and not a Windows path.
 
 The managed tools all run natively on Windows: Claude Code (requires Git
@@ -38,7 +36,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

@@ -36,6 +36,79 @@ explicit removed-engine diagnostic and exits 2 with the recovery tag message.
   shell script.
 - **Backups precede mutation.** Deployed settings/config files write `.bak`
   backups before replacement.
+- **Runtime payload is in memory.** `SoT/` remains the reviewed authoring tree;
+  generated payload freshness gates build/package production, and EngineNative
+  never needs an adjacent runtime `SoT/` directory.
+
+## 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
 
@@ -43,6 +116,7 @@ explicit removed-engine diagnostic and exits 2 with the recovery tag message.
 |---|---|
 | `parseArgs.ts` | engine usage, target selection, flag parsing, legacy rename hints, preflight, model flag validation |
 | `index.ts` | sync orchestration, target dispatch, run summary and next-step blocks |
+| `../payload.ts` | generated text/byte payload reads and presentation-only source labels |
 | `claudeSync.ts` | Claude pipeline: RTK, assets, settings merge, deploy-time modifiers, `~/.claude.json`, connector env, removed artifacts, plugins, optional plugins, LSP binaries |
 | `settings.ts` | pure Claude settings merge/reconcile semantics and permission-array union |
 | `claudeModel.ts` | deployed Claude model modifier and direct `model claude` write path |
@@ -53,8 +127,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
 }