docks-kit 0.14.2 → 0.14.3

package/AGENTS.md

@@ -7,7 +7,7 @@ Canonical instructions for coding agents working on this project. Compatible wit
 Portable configuration kit for AI coding agents. Per-tool Single Source of Truth (SoT) directories get deployed to each tool's user-config location via `./docks-kit sync` — clone once and get a consistent AI-assisted dev environment across supported Linux and macOS hosts. The kit focuses on **token efficiency without sacrificing quality**: every setting and hook is tuned to minimize token consumption while preserving rigorous output. When adding or editing anything, ask: *does this change reduce tokens without weakening correctness?*
 
 Tool-specific instructions live alongside this file:
-- **`CLAUDE.md`** — Claude Code SoT (`SoT/.claude/`), env vars, hooks, plugins, RTK, status line, session management, permission mode, open concerns.
+- **`CLAUDE.md`** — Claude Code SoT (`SoT/.claude/`), env vars, hooks, plugins, status line, session management, permission mode, open concerns.
 - Codex uses this `AGENTS.md` file plus the Codex SoT under `SoT/.codex/`; no separate root `CODEX.md` is needed.
 
 
@@ -42,7 +42,6 @@ Codex SoT notes:
 - `SoT/.codex/plugins/marketplace.json` deploys to Codex's personal marketplace path at `~/.agents/plugins/marketplace.json`; when the `codex` CLI is available, sync reruns `codex plugin add <plugin@marketplace>` for enabled SoT plugins so stale cached installs are refreshed.
 - The global prompt SoTs carry the owner's standing authorization for Docks cross-company plan review, which never overrides host or platform denial.
 - The `codex` CLI binary is upstream-owned, not kit-owned. The official standalone installer keeps package metadata under `$CODEX_HOME/packages/standalone` and places the `codex` symlink in `~/.local/bin` by default; sync only warns with a download-then-run installer command when the CLI is missing. Existing installs can self-update with `codex update`; npm and Homebrew remain upstream alternatives.
-- Neither global prompt SoT imports `@RTK.md`; Claude uses the hook-backed RTK integration, while Codex has no kit-managed RTK integration.
 - Claude runtime settings are an authoring template with sentinels. `claudeRuntime.ts` materializes absolute Bun/script paths only after the shared `bun.ts` bootstrap is ready; `claudeSync.ts` writes all runtime assets before atomically committing settings, then prunes the legacy shell scripts and Stop hook. Native `rate_limits` is the sole quota source, so jq/curl/OAuth caches are not runtime dependencies. A missing Bun defers only this cutover and preserves legacy pointers/files.
 - Claude's deployed SoT defaults are `model: opus` and `effortLevel: high`; `advisorModel` is deliberately absent/off. `--claude-advisor=on` is the per-machine opt-in and writes `advisorModel: fable` after the settings merge. `opus` is the alias, not a pinned id: the `minimumVersion` floor of 2.1.219 ensures Claude Code can resolve it to the newest Opus its provider offers — Opus 5 on the Anthropic API or Opus 4.6 on Microsoft Foundry — instead of silently capping Anthropic API users at Opus 4.8 under the former 2.1.170 floor. Keeping the alias provides provider portability and tracks future Opus releases; the literal `claude-opus-5` is unavailable on Foundry. The floor also subsumes Fable 5's older 2.1.170 requirement.
 
@@ -52,7 +51,7 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT d
 
 - **Idempotent operations.** Every EngineNative sync step must be safe to re-run. Settings merges, plugin installs, and marketplace adds are all idempotent — re-running with no SoT changes is a no-op.
 - **Removed bash engine.** The bash engine was removed after the `bash-engine-final` tag. `DOCKS_KIT_ENGINE=bash` must fail with the removed-engine message; engine bugs are fixed forward in EngineNative.
-- **Targeted syncs.** `./docks-kit sync` accepts positional targets: `claude`, `codex`, and `agents`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync codex` for Codex-only config edits); targets can be combined with `--dry-run`, `--skip-rtk`, `--skip-plugin-refresh` (install missing plugins without refreshing existing caches; used by `docks-kit update`), `--reconcile`, `--prune`, `--yes` (auto-accept toolchain prompts), and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--claude-effort=<level>` / `--claude-advisor=<on|off|default>` / `--codex-model=<m>` / `--codex-effort=<level>` (see `CLAUDE.md` § Deploy-time modifiers).
+- **Targeted syncs.** `./docks-kit sync` accepts positional targets: `claude`, `codex`, and `agents`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync codex` for Codex-only config edits); targets can be combined with `--dry-run`, `--skip-bubblewrap` (skip optional bubblewrap bootstrap for the Codex Linux sandbox), `--skip-plugin-refresh` (install missing plugins without refreshing existing caches; used by `docks-kit update`), `--reconcile`, `--prune`, `--yes` (auto-accept toolchain prompts), and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--claude-effort=<level>` / `--claude-advisor=<on|off|default>` / `--codex-model=<m>` / `--codex-effort=<level>` (see `CLAUDE.md` § Deploy-time modifiers).
 - **Additive by default.** Keys present in deployed config but absent from SoT are preserved on default sync. This protects user-only additions, but means drift accumulates — neither flag-less reset can clean it up. The one exception is the Claude `removed` manifest (`claude::_removed_manifest`), a curated list of unambiguous kit-owned artifacts that `claude::sync_removals` force-prunes on every sync, including the home-relative `~/.local/bin/session-relay` artifact installed outside `~/.claude`; see `CLAUDE.md` § Pruning stale artifacts.
 - **`--reconcile` / `--prune` are the kit-owned reconcile flags.** Orthogonal — `--reconcile` reconciles the settings layer (SoT-declared keys/tables/arrays win; user-only keys and nested objects are preserved; permissions arrays are replaced wholesale by SoT). `--prune` uninstalls kit-managed installations not in the SoT (plugins, marketplaces, and `~/.agents/skills/*` entries tracked in `~/.agents/.kit-managed-skills`). Combine for a full reset to SoT's kit-managed scope. User-only additions outside the kit's scope (custom env vars, mcpServers, manually-installed skills, third-party plugins not declared in SoT) are always preserved. Each tool's per-tool file documents the specific paths and diff recipes.
 - **SOLID-aligned modules.** `cli/src/engine-native/parseArgs.ts` owns flag parsing/validation. `toolchain.ts` owns the verified-version gate over `SoT/toolchain.json`; `bun.ts` owns the shared, memoized Bun bootstrap; `claudeRuntime.ts` owns Claude settings materialization. `claudeSync.ts`, `codexSync.ts`, and `skillsSync.ts` own tool-specific sync logic. `index.ts` is the thin orchestrator. The public CLI seam is `cli/src/engine.ts`.
@@ -69,7 +68,7 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT d
 ## Security
 
 - No secrets in SoT. The kit's SoT directories are committed; treat them as declarative config only.
-- Treat external installers (RTK, plugin marketplaces) as untrusted input. Prefer download-then-run over `curl … | bash` — stream truncation has bitten this kit before (see `CLAUDE.md` § RTK).
+- Treat external plugin marketplaces and installer downloads as untrusted input. Prefer download-then-run over `curl … | bash` so a truncated stream cannot execute a partial script.
 - **Pin, never float.** Every kit-driven install is pinned to a `SoT/toolchain.json` `verified` version or gated by one — no `@latest` npm/bun installs (Shai-Hulud-class worm surface), no mutable action tags in workflows (commit SHAs only), installer scripts fetched from version tags where upstream supports it. New install surface ⇒ manifest pin first. Details: the `toolchain-context` skill and `cli/docs/toolchain.md`.
 
 ## Testing

package/README.md

@@ -34,8 +34,8 @@ The executable carries the generated sync payload; no checkout or adjacent
 `SoT/` directory is required.
 
 Prerequisites for source/global installs: Bun; Node/npm for npm-global tools.
-`jq` is optional doctor/test tooling. `curl` is used only at requested Linux/macOS
-RTK/Bun download boundaries, not as a global sync prerequisite.
+`jq` is optional doctor/test tooling. `curl` is used only when a requested
+Linux/macOS Bun bootstrap must download an installer.
 
 ## CLI
 
@@ -68,7 +68,7 @@ golden-regression coverage for dry-run output, mutation snapshots, and argv logs
 | `--claude-permissive` | Deploy-time modifier: empty ask/deny (sandboxes only) |
 | `--claude-plugin=<name>` | Sticky opt-in plugin (supabase, n8n) |
 | `--codex-model=<m>` | Deploy-time modifier: deployed Codex model |
-| `--skip-rtk` | Skip optional tool bootstrap |
+| `--skip-bubblewrap` | Skip optional bubblewrap bootstrap (Codex Linux sandbox) |
 | `--skip-plugin-refresh` | Install missing plugins but skip refresh-only updates (used automatically by `docks-kit update`) |
 | `--yes` | Auto-accept toolchain prompts (CI/containers) |
 
@@ -82,7 +82,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
   survive a plain sync. Reconciliation toward the SoT is explicit
   (`--reconcile` / `--prune`).
 - **Idempotent** — every step is safe to re-run; no-change syncs are no-ops.
-- **Toolchain floors** — external tools (RTK, bun, agent-browser,
+- **Toolchain floors** — external tools (bun, bwrap,
   effect-solutions, …) install/upgrade against `SoT/toolchain.json`:
   versions above the kit-verified pin prompt before installing
   (`--yes` accepts; non-TTY falls back to the pinned verified version
@@ -128,7 +128,7 @@ Details: `docks-kit docs platforms`.
 Tagging `cli-v*` builds four standalone binaries (Linux x64/arm64 and macOS
 x64/arm64) plus `SHA256SUMS` and attaches them to the GitHub release; npm
 publishes the exact package tarball through trusted publishing with OIDC provenance.
-Package `docks-kit` 0.14.2 bundles the CLI + generated payload, so npm releases
+Package `docks-kit` 0.14.3 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

@@ -18,7 +18,7 @@ docks-kit sync claude agents        # two
 | `--dry-run` | Preview without applying |
 | `--reconcile` | Settings layer reconciled toward SoT (SoT keys win; user-only keys preserved; permissions arrays replaced) |
 | `--prune` | Uninstall kit-managed installs not in SoT: plugins, marketplaces, universal skills |
-| `--skip-rtk` | Skip optional tool bootstrap (RTK, bubblewrap) |
+| `--skip-bubblewrap` | Skip optional bubblewrap bootstrap (Codex Linux sandbox) |
 | `--skip-plugin-refresh` | Install missing Claude/Codex plugins but skip refresh-only updates; `docks-kit update` uses this automatically |
 | `--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` |
@@ -52,4 +52,3 @@ Old flags exit with a rename hint — there is no compat behavior.
 | `--680k` | `--claude-compact-window=680k` |
 | `--permissive` | `--claude-permissive` |
 | `--supabase` / `--n8n` | `--claude-plugin=supabase` / `--claude-plugin=n8n` |
-| `--no-rtk` | `--skip-rtk` |

package/cli/docs/install.md

@@ -94,8 +94,8 @@ sync/config reads.
 ## Prerequisites
 
 - Bun for source/global installs; release binaries embed the runtime
-- Node/npm for npm-global tools (agent-browser, LSP servers)
+- Node/npm for npm-global LSP servers
 - jq is optional doctor/test tooling; sync has no jq runtime dependency
-- curl is required only when a requested Linux/macOS RTK/Bun bootstrap must download
+- curl is required only when a requested Linux/macOS Bun bootstrap must download
   an installer; an already-present Bun does not require it
 - See `docks-kit toolchain check` for the full picture on this machine

package/cli/docs/sync-layers.md

@@ -7,31 +7,28 @@ no target means all three.
 
 Order matters — runtime readiness and settings form one transaction:
 
-1. **RTK** (toolchain-gated): install/upgrade, then `rtk init --global` on
-   first install. Runs FIRST because rtk init rewrites settings.json — the
-   later settings merge normalizes whatever it wrote.
-2. Resolve/bootstrap pinned Bun, materialize the sentinel settings template,
+1. Resolve/bootstrap pinned Bun, materialize the sentinel settings template,
    and prepare the merged settings bytes without mutation. If Bun remains
    unavailable, omit only the new runtime pointers and preserve legacy ones.
-3. When ready, write `bin/statusline.mjs`, `bin/session-start.mjs`,
+2. When ready, write `bin/statusline.mjs`, `bin/session-start.mjs`,
    `bin/notify.mjs`, and `notification.mp3`; deploy CLAUDE.md; atomically commit
    settings.
-4. **settings.json merge semantics** — additive: SoT keys win, permissions arrays are
+3. **settings.json merge semantics** — additive: SoT keys win, permissions arrays are
    unioned, user-only keys survive. `--reconcile` replaces permissions arrays
    wholesale instead.
-5. **Removed-artifact pruning** — prune old shell assets, the Stop hook, stale
+4. **Removed-artifact pruning** — prune old shell assets, the Stop hook, stale
    kit-owned settings, retired kit-owned plugin enablement, and the stale
    `~/.local/bin/session-relay` command. A flag-less sync removes
    `advisorModel`; an explicit advisor state excludes only that key so the
    modifier owns it.
-6. **Deploy-time modifiers** (`--claude-compact-window`, `--claude-permissive`,
+5. **Deploy-time modifiers** (`--claude-compact-window`, `--claude-permissive`,
    `--claude-model`, `--claude-effort`, `--claude-advisor`) — deployed file only.
-7. ~/.claude.json (showTurnDuration, user-scoped MCP servers) and connector env
+6. ~/.claude.json (showTurnDuration, user-scoped MCP servers) and connector env
    export.
-8. **Plugins** — seven idempotent passes via the `claude plugin` CLI
+7. **Plugins** — seven idempotent passes via the `claude plugin` CLI
    (marketplaces → install → update → [--prune: uninstall/remove] → re-assert
    SoT enabled-state). Optional opt-ins via `--claude-plugin=<name>`.
-9. LSP server binaries (npm globals).
+8. LSP server binaries (npm globals).
 
 The statusline reads Claude's native `rate_limits`. There is no OAuth request,
 usage cache, jq/curl runtime dependency, or Stop fetch hook.
@@ -47,7 +44,7 @@ and `codex plugin add` refresh.
 ## agents (→ ~/.agents/skills, ~/.claude/skills symlinks)
 
 `npx skills add` per missing manifest slug, Claude symlink healing,
-CLI binaries (agent-browser, effect-solutions — toolchain-gated), and the
+the effect-solutions CLI (toolchain-gated), and the
 kit-managed snapshot that `--prune` reconciles against.
 
 ## Reconcile flags

package/cli/docs/toolchain.md

@@ -8,7 +8,7 @@
 | `policy` | `track` (upgrade toward latest, gated by `verified`) / `present` (install when missing, never upgrade) |
 | `floor` | Minimum acceptable version (below → upgrade automatically) |
 | `verified` | Last kit-tested version — the gate line |
-| `pinnable` | Whether an exact version can be installed (rtk: `RTK_VERSION=vX.Y.Z`) |
+| `pinnable` | Whether an exact version can be installed |
 
 ## The gate
 
@@ -26,20 +26,16 @@ now kit-approved" act.
 
 ## Managed tools
 
-- **rtk** — PreToolUse hook (supply-chain sensitive: review releases before
-  bumping `verified`). Runs FIRST in the claude sync so `rtk init`'s
-  settings rewrite is normalized by the merge that follows. Pinned installs
-  fetch the installer script from the version tag, not mutable master.
 - **bun** — policy `present`: bootstrap only (pinned to `verified` via the
   installer's version argument), never auto-upgraded. `bun.ts` owns one
   per-engine-run memo shared by Claude runtime, effect-solutions, and direct
   toolchain ensure on supported Linux/macOS hosts.
-- **effect-solutions**, **agent-browser** — policy `track`: self-upgrade
-  toward npm latest, gated by their `verified` pins.
+- **effect-solutions** — policy `track`: self-upgrades toward npm latest,
+  gated by its `verified` pin.
 
 jq and curl are `check` rows, not global prerequisites. jq is not consumed by
-normal sync. curl is checked only at a requested Linux/macOS RTK/Bun installer
-download boundary.
+normal sync. curl is checked only when a requested Linux/macOS Bun bootstrap
+must download an installer.
 
 ## Supply-chain stance
 
@@ -52,8 +48,9 @@ probe falls back to the pinned `verified`, never to an ungated latest.
 
 ## Commands
 
-```
-docks-kit toolchain check            # doctor table (also inside docks-kit status)
-docks-kit toolchain ensure rtk       # install/upgrade one tool per policy
-docks-kit sync --yes                 # unattended: auto-accept gates
+```text
+docks-kit toolchain check                    # doctor table (also inside docks-kit status)
+docks-kit toolchain ensure bun               # ensure one supported managed tool
+docks-kit toolchain ensure effect-solutions  # ensure the other supported managed tool
+docks-kit sync --yes                         # unattended: auto-accept gates
 ```

package/cli/src/commands/sync.ts

@@ -49,7 +49,7 @@ const LEGACY_HINTS: Record<string, string> = {
   "--permissive": "--permissive was renamed to --claude-permissive",
   "--supabase": "--supabase was renamed to --claude-plugin=supabase",
   "--n8n": "--n8n was renamed to --claude-plugin=n8n",
-  "--no-rtk": "--no-rtk was renamed to --skip-rtk",
+  "--skip-rtk": "--skip-rtk was renamed to --skip-bubblewrap",
   "--claude": "--claude was renamed: pass the target as a word, e.g. 'sync claude'",
   "--codex": "--codex was renamed: pass the target as a word, e.g. 'sync codex'",
   "--agents": "--agents was renamed: pass the target as a word, e.g. 'sync agents'"
@@ -77,8 +77,8 @@ const reconcile = Options.boolean("reconcile").pipe(
 const prune = Options.boolean("prune").pipe(
   Options.withDescription("Uninstall kit-managed installs not in SoT (plugins, marketplaces, universal skills)")
 )
-const skipRtk = Options.boolean("skip-rtk").pipe(
-  Options.withDescription("Skip optional tool bootstrap (RTK, bubblewrap)")
+const skipBubblewrap = Options.boolean("skip-bubblewrap").pipe(
+  Options.withDescription("Skip optional bubblewrap bootstrap (Codex Linux sandbox)")
 )
 const skipPluginRefresh = Options.boolean("skip-plugin-refresh").pipe(
   Options.withDescription("Install missing plugins but skip refresh-only updates for existing plugins")
@@ -131,7 +131,7 @@ export const syncCommand = Command.make(
     dryRun,
     reconcile,
     prune,
-    skipRtk,
+    skipBubblewrap,
     skipPluginRefresh,
     yes,
     verbose,
@@ -175,7 +175,7 @@ export const syncCommand = Command.make(
       if (config.dryRun) args.push("--dry-run")
       if (config.reconcile) args.push("--reconcile")
       if (config.prune) args.push("--prune")
-      if (config.skipRtk) args.push("--skip-rtk")
+      if (config.skipBubblewrap) args.push("--skip-bubblewrap")
       if (config.skipPluginRefresh) args.push("--skip-plugin-refresh")
       if (config.yes) args.push("--yes")
       if (config.verbose) args.push("--verbose")

package/cli/src/commands/toolchain.ts

@@ -2,7 +2,7 @@ import { Args, Command, Options } from "@effect/cli"
 import { Effect, Option } from "effect"
 import { bail, engine } from "../engine"
 
-const MANAGED = ["rtk", "bun", "effect-solutions", "agent-browser"]
+const MANAGED = ["bun", "effect-solutions"]
 
 const op = Args.text({ name: "op" }).pipe(
   Args.withDescription("check (default) | ensure <tool>"),

package/cli/src/commands/update.ts

@@ -1,7 +1,7 @@
 import { Command, Options } from "@effect/cli"
 import { Console, Effect } from "effect"
 import { spawnSync } from "node:child_process"
-import { existsSync } from "node:fs"
+import { existsSync, readFileSync } from "node:fs"
 import { join } from "node:path"
 import { bail, compiled } from "../engine"
 import { kitHome } from "../kitHome"
@@ -32,6 +32,27 @@ export const updateSyncArgs = (home: string): Array<string> => [
   "--skip-plugin-refresh"
 ]
 
+const readPackageVersion = (home: string): string => {
+  try {
+    const doc: unknown = JSON.parse(readFileSync(join(home, "package.json"), "utf8"))
+    if (doc === null || typeof doc !== "object" || !("version" in doc)) return ""
+    return typeof doc.version === "string" ? doc.version : ""
+  } catch {
+    return ""
+  }
+}
+
+export const packageUpdateResult = (
+  before: string,
+  after: string
+): { alreadyCurrent: boolean; message: string } => {
+  if (before === "" || after === "") return { alreadyCurrent: false, message: "" }
+  if (before === after) {
+    return { alreadyCurrent: true, message: `Already at the latest version (${after}).` }
+  }
+  return { alreadyCurrent: false, message: `Updated ${before} -> ${after}.` }
+}
+
 const updateCheckout = (home: string, skipSync: boolean) =>
   Effect.gen(function* () {
     if (spawnSync("git", ["--version"], { stdio: "ignore" }).status !== 0) {
@@ -52,7 +73,7 @@ const updateCheckout = (home: string, skipSync: boolean) =>
     const after = git(home, ["rev-parse", "HEAD"]).out
 
     if (before === after) {
-      return yield* Console.log(`Already up to date (${after.slice(0, 7)}, upstream ${upstream.out}).`)
+      return yield* Console.log(`Already at the latest version (${after.slice(0, 7)}, upstream ${upstream.out}).`)
     }
 
     const count = git(home, ["rev-list", "--count", `${before}..${after}`]).out
@@ -89,12 +110,17 @@ const updatePackage = (home: string, skipSync: boolean) =>
       home.includes("\\.bun\\") ||
       underEnvDir("BUN_INSTALL_GLOBAL_DIR") ||
       underEnvDir("BUN_INSTALL")
+    const beforeVersion = readPackageVersion(home)
     const res = viaBun
       ? spawnSync("bun", ["add", "-g", "docks-kit@latest"], { stdio: "inherit" })
       : spawnSync("npm", ["install", "-g", "docks-kit@latest"], { stdio: "inherit" })
     if (res.error !== undefined || res.status !== 0) {
       return yield* bail(`global package update failed (${viaBun ? "bun add -g" : "npm install -g"} docks-kit@latest)`, 1)
     }
+
+    const result = packageUpdateResult(beforeVersion, readPackageVersion(home))
+    if (result.message !== "") yield* Console.log(result.message)
+    if (result.alreadyCurrent) return
     if (skipSync) return yield* Console.log("Kit updated. Run: docks-kit sync")
     yield* Console.log("Kit updated - running sync with the new version...")
     // Chain through the package dir just updated (global installs update in

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

@@ -27,12 +27,12 @@ explicit removed-engine diagnostic and exits 2 with the recovery tag message.
 - **Prove-red stays red.** The golden suites compare live native output to a
   mismatched golden under `--prove-red` and must exit non-zero after printing
   `prove-red OK`.
-- **Step ordering is load-bearing.** The Claude pipeline runs RTK, resolves Bun,
-  prepares materialized settings, writes runtime assets, commits settings, then
-  performs readiness-gated legacy cleanup. Modifiers run after the base commit,
-  removals before plugins, and LSP checks after plugin state.
-- **External CLIs stay external.** `claude`, `codex`, `npx`, `npm`, `rtk`,
-  `bun`, `curl`, and platform package managers are spawned with argv arrays,
+- **Step ordering is load-bearing.** The Claude pipeline resolves Bun, prepares
+  materialized settings, writes runtime assets, commits settings, then performs
+  readiness-gated legacy cleanup. Modifiers run after the base commit, removals
+  before plugins, and LSP checks after plugin state.
+- **External CLIs stay external.** `claude`, `codex`, `npx`, `npm`, `bun`,
+  `curl`, and platform package managers are spawned with argv arrays,
   not shell command strings except where the external installer contract is a
   shell script.
 - **Backups precede mutation.** Deployed settings/config files write `.bak`
@@ -55,6 +55,7 @@ warnings, and the summary. Status-quo confirmations exist but are opt-in.
 | `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 |
+| `progress(msg)` | stderr | interactive only | interactive only | dim, transient single-line status with no newline |
 | `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
@@ -63,6 +64,15 @@ warnings, and the summary. Status-quo confirmations exist but are opt-in.
   printed unfiltered at every verbosity.
 - Prefixes and ANSI codes are stable golden surface; the level controls
   visibility, not the prefix.
+- `logger.ts` `makeLogger`, at progress sink selection, enables transient
+  progress when `LoggerSinks.progress` exists. It also enables progress when no
+  stderr sink exists and `process.stderr.isTTY` is `true`. It disables progress
+  in every other case. Injected golden sinks therefore keep their existing
+  bytes unless the harness supplies a progress sink.
+- Each progress write replaces one terminal line. `clearProgress()` erases a
+  pending line and does nothing when no line is pending. Every durable
+  `change`, `verbose`, `warn`, `err`, or `echo` write erases the pending line
+  before it writes durable output.
 
 ### Change detection
 
@@ -76,9 +86,9 @@ each such skip is an intentional behavior change named in its golden diff.
 Exactly one deduplicated warn per requested missing tool per run, uniform shape:
 `[warn] <tool> not installed — <platform-correct install command>`, sourced
 from the dependency registry (`deps.ts`). jq and curl are optional report rows:
-jq has no runtime consumer, while curl warns only at a requested POSIX RTK/Bun
-download boundary. A missing Bun defers Claude runtime migration without
-deleting working legacy hooks or statusline files.
+jq has no runtime consumer, while curl warns only when a requested POSIX Bun
+bootstrap needs an installer download. A missing Bun defers Claude runtime
+migration without deleting working legacy hooks or statusline files.
 
 ### Summary and next steps
 
@@ -89,10 +99,9 @@ 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`.
+`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
 
@@ -118,14 +127,14 @@ active logger binding.
 | `parseArgs.ts` | engine usage, target selection, flag parsing, legacy rename hints, 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, prepared settings transaction, runtime assets, deploy-time modifiers, `~/.claude.json`, readiness-gated removed artifacts, plugins, optional plugins, LSP binaries |
+| `claudeSync.ts` | Claude pipeline: Bun bootstrap, prepared settings transaction, runtime assets, deploy-time modifiers, `~/.claude.json`, readiness-gated removed artifacts, plugins, optional plugins, LSP binaries |
 | `bun.ts` | per-run memoized Bun resolution/bootstrap shared by Claude runtime, effect-solutions, and direct toolchain ensure |
 | `claudeRuntime.ts` | sentinel validation, absolute runtime paths, no-cutover settings projection, and POSIX statusline commands |
 | `settings.ts` | pure Claude settings merge/reconcile semantics and permission-array union |
 | `claudeModel.ts` | deployed Claude model modifier and direct `model claude` write path |
 | `codexSync.ts` | Codex pipeline: bubblewrap check, config merge, rules, AGENTS.md, personal marketplace, plugin refresh |
 | `codexToml.ts` | line-based top-level TOML replacement and deployed Codex model modifier |
-| `skillsSync.ts` | universal skill install/prune, Claude symlink healing, agent-browser/effect-solutions callbacks, managed-skill snapshot |
+| `skillsSync.ts` | universal skill install/prune, Claude symlink healing, effect-solutions callback, managed-skill snapshot |
 | `toolchain.ts` | tool presence/version probes, verified-version gate, managed install/upgrade orchestration, report table |
 | `modes.ts` | direct `model` and `toolchain` modes |
 | `models.ts` | model catalog listing and validation |