docks-kit 0.15.2 → 0.15.4

package/AGENTS.md

@@ -4,29 +4,35 @@ Canonical instructions for coding agents working on this project. Compatible wit
 
 ## Repository purpose
 
-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?*
+Portable configuration kit for AI coding agents. Per-tool Single Source of Truth
+(SoT) directories deploy to each tool's user-config location through
+`./docks-kit sync`. Clone once to get a consistent AI-assisted environment on
+supported Linux, macOS, and Windows hosts. The kit focuses on **token efficiency
+without sacrificing quality**. Every setting and hook minimizes token use while
+preserving rigorous output. When you add or edit 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, 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.
 
 
-docks-kit runtime and standalone binary support is exactly Linux x64/arm64 and
-macOS x64/arm64. Unsupported hosts fail before the launcher can fall back to
-Bun source.
+docks-kit runtime and standalone binary support covers Linux x64/arm64, macOS
+x64/arm64, and Windows x64/arm64. Hosts outside this matrix fail before either
+launcher can fall back to Bun source.
 
 ## Repository layout (cross-cutting)
 
 | Path | Purpose |
 |------|---------|
-| `docks-kit` | CLI launcher: on supported hosts, runs the platform binary in `cli/dist/` only when its `--version` matches `package.json`, otherwise Bun-from-source (auto-installs Bun + `node_modules`). Unsupported hosts fail before source fallback. No-Bun recovery is the standalone platform release binary |
+| `docks-kit` / `docks-kit.ps1` | POSIX and Windows CLI launchers. On supported hosts, each runs the matching binary in `cli/dist/` only when its `--version` matches `package.json`. Otherwise it runs Bun-from-source and auto-installs Bun plus `node_modules`. Hosts outside the support matrix fail before source fallback. The standalone platform release binary provides no-Bun recovery. |
 | `cli/src/engine-native/` | EngineNative implementation for `sync`, `model`, and `toolchain`; idempotent, flag-gated for destructive reconciliation |
-| `cli/` | Effect 4 beta CLI + bundled docs topics |
+| `cli/` | Effect 4 RC CLI + bundled docs topics |
 | `SoT/models.json` | Kit-verified Claude and Codex model catalog |
 | `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative) |
 | `SoT/.claude/bin/` | Dependency-free Bun runtime programs for Claude's statusline, SessionStart, and Notification |
-| `install.sh` | Global installer |
-| `.github/workflows/release-cli.yml` | `cli-v*` release: four Linux/macOS x64/arm64 binaries, `SHA256SUMS`, and npm publish |
+| `install.sh` / `install.ps1` | POSIX and Windows global installers |
+| `.github/workflows/release-cli.yml` | `cli-v*` release: six binaries for Linux, macOS, and Windows on x64 and arm64, plus `SHA256SUMS` and npm publish |
 | `README.md` | Front door |
 | `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, intentionally empty by default. Adding an [agentskills.io](https://agentskills.io/specification) slug opts it into EngineNative's shared `~/.agents/skills/` bootstrap and Claude symlink. |
@@ -37,7 +43,7 @@ Bun source.
 
 Codex SoT notes:
 - `SoT/.codex/AGENTS.md` deploys to `~/.codex/AGENTS.md` as global Codex instructions.
-- `SoT/.codex/config.toml` pins Codex to `model = "gpt-5.6-sol"`, sets normal and plan reasoning to `high` with concise summaries, and sets `model_verbosity = "low"`, `personality`, live top-level `web_search`, workspace-write sandboxing with sandboxed command network access, cross-session `memories` (+ dedicated note tools), `[agents]` subagent limits (`max_threads = 12`, `max_depth = 2` — intentionally above Codex defaults for broad parallel kit work; deeper recursion increases cost and predictability risk), a 128 KiB `project_doc_max_bytes` budget for the repo-side AGENTS.md chain (the global `~/.codex/AGENTS.md` is uncapped and not counted), and enables the three Docks plugins `docks@docks`, `plan-lifecycle@docks` (the shared plan lifecycle and an `effect-kit@docks` dependency), and `effect-kit@docks`.
+- `SoT/.codex/config.toml` pins Codex to `model = "gpt-5.6-sol"`, sets normal and plan reasoning to `high` with concise summaries, and sets `model_verbosity = "low"`, `personality`, live top-level `web_search`, workspace-write sandboxing with sandboxed command network access, cross-session `memories` (+ dedicated note tools), `[agents]` subagent limits (`max_threads = 12`, `max_depth = 2` — intentionally above Codex defaults for broad parallel kit work; deeper recursion increases cost and predictability risk), a 128 KiB `project_doc_max_bytes` budget for the repo-side AGENTS.md chain (the global `~/.codex/AGENTS.md` is uncapped and not counted), and enables the two Docks plugins `docks@docks` and `plan-lifecycle@docks` (the shared plan lifecycle).
 - `SoT/.codex/rules/*.rules` deploys to `~/.codex/rules/` as kit-managed Codex command policy. This is Codex's equivalent of permission allow/prompt/block rules; user-learned approvals in `~/.codex/rules/default.rules` are preserved.
 - `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.
@@ -51,12 +57,12 @@ 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.
-- **Effect 4 CLI stack.** The CLI pins `effect@4.0.0-beta.107` (including `effect/unstable/cli`), `@effect/platform-bun@4.0.0-beta.107` (`BunServices.layer`, `BunRuntime.runMain`), `@effect/vitest@4.0.0-beta.107`, and `vitest@4.1.10` (required by the `@effect/vitest` peer range). `@effect/cli` and `@effect/platform` are removed and must not be reintroduced.
-- **Effect skill routing.** Effect work in this checkout must use the `effect-v4` skill from the already-enabled `effect-kit@docks` plugin; `effect-ts-setup`, `effect-ts-port`, and `effect-ts-specialist` target Effect 3.x and do not apply. Verify migration and API call shapes against the installed declarations under `node_modules/effect/dist/unstable/cli/`, never from memory or a mutable dist-tag.
-- **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).
+- **Effect 4 CLI stack.** The CLI pins `effect@4.0.0-rc.109` (including `effect/unstable/cli`), `@effect/platform-bun@4.0.0-rc.109` (`BunServices.layer`, `BunRuntime.runMain`), `@effect/vitest@4.0.0-rc.109`, and `vitest@4.1.10` (required by the `@effect/vitest` peer range). `@effect/cli` and `@effect/platform` are removed and must not be reintroduced.
+- **Effect skill routing.** Effect work in this checkout must verify migration and API call shapes against the installed declarations under `node_modules/effect/dist/unstable/cli/`, never from memory or a mutable dist-tag. The `effect-ts-setup`, `effect-ts-port`, and `effect-ts-specialist` skills target Effect 3.x and do not apply.
+- **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`, 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`.
+- **SOLID-aligned modules.** `cli/src/engine-native/parseArgs.ts` owns flag parsing/validation. `toolchain.ts` owns verified-version floor reporting 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`.
 - **Small, reviewable changes.** Bundled multi-concern PRs are harder to review and revert. Split an engine/CLI change and a per-tool config change unless the change requires atomicity.
 - **Dry-run before destructive flags.** Always preview with `./docks-kit sync --dry-run` (or the relevant `diff <(jq -S …)` recipe in the per-tool file) before invoking `--reconcile` or `--prune`. User-added permissions / env vars / plugins absent from SoT will be discarded.
 - **SoT prompt files are rules, not explanation.** `SoT/.claude/CLAUDE.md` and `SoT/.codex/AGENTS.md` are loaded into every agent session's prompt context — every line costs prompt tokens on every turn for every user. Restrict their content to rules, heuristics, and `<constraint>` blocks the agent must *act on* during a turn. Do NOT add inline source citations (`Source: …`, attributed quotes), "why this rule exists" preface text, version-watermarking trivia (e.g. "Distilled from X v2.0, captured 2025-11-07"), per-bug workarounds, or installation instructions. Provenance, motivation, and historical context belong in `CLAUDE.md` / `AGENTS.md` at the repo root (humans read once) or in commit messages — never in the SoT. For every line, apply the official test: would removing it cause the agent to make mistakes? If not, cut it — over-instruction degrades adherence on current frontier models.
@@ -71,8 +77,8 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT d
 
 - No secrets in SoT. The kit's SoT directories are committed; treat them as declarative config only.
 - 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`.
-
+- **Pin, never float.** Every kit-driven install of third-party software is pinned to a `SoT/toolchain.json` `verified` version — 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 third-party install surface ⇒ manifest pin first. Details: the `toolchain-context` skill and `cli/docs/toolchain.md`.
+- **One exemption: the kit's own package.** `install.sh` and `install.ps1` end with `bun add -g docks-kit@latest`, because a global installer that pinned itself would install a fixed old kit forever, and pinning it to `package.json` would request an unpublished version between the release-prep commit and the npm publish. The exemption covers `docks-kit` alone. Both installers still pin the Bun installer they download to the manifest's verified version, and `cli/test/unit/install.test.ts` asserts that pin in all four launcher and installer scripts.
 ## Testing
 
 Automated coverage includes `bun run test:unit`, `bun run golden:dryrun`, and `bun run golden:mutation`; prove-red modes must exit non-zero after detecting planted mismatches. Also verify user-facing changes via `./docks-kit sync --dry-run`, per-tool sanity (`/doctor`, `/plugin`, etc.), and `diff <(jq -S . <SoT>) <(jq -S . <deployed>)` recipes from the per-tool file.

package/README.md

@@ -1,9 +1,9 @@
 # docks-kit
 
 Portable configuration kit for AI coding agents. Per-tool **Single Source of
-Truth (SoT)** directories are deployed to each tool's user-config location —
-clone once and get a consistent AI-assisted dev environment across supported
-Linux and macOS machines. Tuned for **token efficiency without sacrificing quality**.
+Truth (SoT)** directories deploy to each tool's user-config location. Clone
+once to get a consistent AI-assisted environment on supported Linux, macOS,
+and Windows machines. Tuned for **token efficiency without sacrificing quality**.
 
 Supported tools: **Claude Code**, **Codex**, and any agent consuming
 [agentskills.io](https://agentskills.io) universal skills.
@@ -17,15 +17,15 @@ cd ~/projects/public
 ./docks-kit status          # doctor view: drift, toolchain, plugins, skills
 ```
 
-The `./docks-kit` launcher supports Linux x64/arm64 and macOS x64/arm64.
-On those hosts it prefers a compiled binary (`cli/dist/`) only when its version
-matches the checkout, then runs from source via Bun—auto-installing Bun and
-dependencies when missing. Unsupported hosts fail immediately and never fall
-back to Bun source. Stale ignored build artifacts cannot mask newer checkout
-code.
+POSIX hosts use the `./docks-kit` launcher on x64 and arm64. Windows uses
+`.\docks-kit.ps1` on x64 and arm64. Each launcher prefers the matching compiled
+binary in `cli/dist/` only when its version matches the checkout. Otherwise it
+runs from source via Bun and auto-installs Bun plus dependencies when needed.
+Hosts outside this matrix fail immediately and never fall back to Bun source.
+Stale ignored build artifacts cannot mask newer checkout code.
 
-Other install paths (global `bun add -g docks-kit`, curl installer) —
-see `./docks-kit docs install`.
+Other install paths include global `bun add -g docks-kit`, the POSIX curl
+installer, and the Windows PowerShell installer. See `./docks-kit docs install`.
 
 **No-Bun recovery path**:
 
@@ -33,9 +33,10 @@ 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; Node/npm for npm-global tools.
-`jq` is optional doctor/test tooling. `curl` is used only when a requested
-Linux/macOS Bun bootstrap must download an installer.
+Source and global installs require Bun. npm-global tools require Node/npm.
+`jq` is optional doctor/test tooling. `curl` downloads Bun only when a source
+launcher needs it. POSIX runs `install.sh`; Windows runs `install.ps1` through
+PowerShell.
 
 ## CLI
 
@@ -52,12 +53,12 @@ docks-kit docs [topic]                     self-documentation (9 topics)
 --help --version --wizard --completions    built-in
 ```
 
-The CLI is a typed Effect 4 beta front-end on Bun; all mutation runs through
+The CLI is a typed Effect 4 RC front-end on Bun; all mutation runs through
 EngineNative in `cli/src/engine-native/`, with golden-regression coverage for
 dry-run output, mutation snapshots, and argv logs. Its dependency graph is
-`effect@4.0.0-beta.107` (including `effect/unstable/cli`),
-`@effect/platform-bun@4.0.0-beta.107` (`BunServices.layer` and
-`BunRuntime.runMain`), `@effect/vitest@4.0.0-beta.107`, and `vitest@4.1.10`
+`effect@4.0.0-rc.109` (including `effect/unstable/cli`),
+`@effect/platform-bun@4.0.0-rc.109` (`BunServices.layer` and
+`BunRuntime.runMain`), `@effect/vitest@4.0.0-rc.109`, and `vitest@4.1.10`
 (required by the `@effect/vitest` peer range). `@effect/cli` and
 `@effect/platform` are removed: neither has a 4.x release, the CLI API moved
 into core, and the standalone platform package was unused here.
@@ -76,7 +77,6 @@ into core, and the standalone platform package was unused here.
 | `--codex-model=<m>` | Deploy-time modifier: deployed Codex model |
 | `--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) |
 
 **Deploy-time modifiers** change deployed config only — the SoT is untouched
 and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
@@ -88,11 +88,10 @@ 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 (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
-  when possible). `docks-kit toolchain check` shows the full table.
+- **Toolchain floors** — `SoT/toolchain.json` records the kit-verified version
+  floors for external tools (bun, bwrap, …). `docks-kit toolchain check` prints
+  the full doctor table. Bun is the one managed install and is pinned to its
+  verified version.
 - **Model catalog** — `SoT/models.json` is the research-verified source for
   model validation, listings, and pickers.
 - **Claude runtime** — sync materializes three dependency-free Bun `.mjs`
@@ -112,9 +111,9 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 | `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 4 beta on Bun) + bundled docs topics |
-| `docks-kit` | Launcher (binary → bun-from-source) |
-| `install.sh` | Global installer (Bun bootstrap + `bun add -g`) |
+| `cli/` | docks-kit CLI (Effect 4 RC on Bun) + bundled docs topics |
+| `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers (binary → Bun-from-source) |
+| `install.sh` / `install.ps1` | POSIX and Windows global installers |
 | `docs/plans/` | Multi-commit work-item plans |
 | `AGENTS.md` / `CLAUDE.md` | Agent-facing engineering rules / Claude Code specifics |
 
@@ -126,15 +125,18 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 | Linux | arm64 | ✅ | ✅ native |
 | macOS | x64 | ✅ | ✅ native |
 | macOS | arm64 | ✅ | ✅ native |
+| Windows | x64 | ✅ | ✅ native |
+| Windows | arm64 | ✅ | ✅ native |
 
 Details: `docks-kit docs platforms`.
 
 ## Releases
 
-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.15.2 bundles the CLI + generated payload, so npm releases
+Tagging `cli-v*` builds six standalone binaries for Linux, macOS, and Windows
+on x64 and arm64. The workflow attaches them plus `SHA256SUMS` to the GitHub
+release. npm publishes the exact package tarball through trusted publishing
+with OIDC provenance.
+Package `docks-kit` 0.15.4 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,7 +20,6 @@ docks-kit sync claude agents        # two
 | `--prune` | Uninstall kit-managed installs not in SoT: plugins, marketplaces, universal skills |
 | `--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` |
 
 ## Environment overrides

package/cli/docs/install.md

@@ -1,7 +1,7 @@
 # Installing docks-kit
 
-Supported hosts are Linux x64/arm64 and macOS x64/arm64. Unsupported hosts
-fail before the launcher can fall back to Bun source.
+Supported hosts are Linux x64/arm64, macOS x64/arm64, and Windows x64/arm64.
+Hosts outside this matrix fail before a launcher can fall back to Bun source.
 
 ## 1. Repo checkout (development / current users)
 
@@ -11,13 +11,13 @@ cd ~/projects/public
 ./docks-kit sync
 ```
 
-On a supported host, the `./docks-kit` launcher prefers a compiled binary in
-`cli/dist/` only when its reported version matches `package.json`, then falls
-back to Bun-from-source (auto-installing Bun via download-then-run and
-`bun install --frozen-lockfile` when needed). An ignored stale build is reported
-and bypassed.
+POSIX hosts use `./docks-kit`. Windows uses `.\docks-kit.ps1`. Each
+launcher prefers a compiled binary in `cli/dist/` only when its reported
+version matches `package.json`. It then falls back to Bun-from-source and
+auto-installs Bun plus `node_modules` when needed. Each launcher reports and
+bypasses an ignored stale build.
 
-## 2. Global via Bun (effect-solutions-style)
+## 2. Global via Bun
 
 ```
 bun add -g docks-kit@latest
@@ -31,31 +31,27 @@ 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.
 
-### Bun 1.3.14 blocked-postinstall notice
+### Bun 1.4.0 install output
 
-A supported global install may finish successfully with this exact notice:
+A supported global install completes with no blocked postinstall: `bun pm -g
+untrusted` reports zero untrusted dependencies with scripts. Neither
+`@parcel/watcher` nor `esbuild` is in the consumer graph. The graph does carry
+one package with an `install` script, `msgpackr-extract` by way of
+`effect > msgpackr`, and Bun raises no trust prompt for it.
 
-```
-Blocked 1 postinstall. Run `bun pm -g untrusted` for details.
-```
-
-For the pinned production dependency graph, the diagnostic names only:
+The install does print one expected warning:
 
 ```
-./node_modules/@parcel/watcher @2.5.6
- » [install]: node scripts/build-from-source.js
+warn: incorrect peer dependency "effect@4.0.0-rc.109"
 ```
 
-`@parcel/watcher` is a transitive of the Effect Bun runtime. Supported default
-installs already carry its platform prebuilt package, and that install script
-only attempts a source build when `npm_config_build_from_source=true` was
-explicitly requested. `esbuild` is not in the consumer production graph. The
-blocked notice therefore needs no trust action for the supported default
-install; `docks-kit --version`, model catalogs, toolchain checks, and real sync
-remain functional with the script blocked. CI pins the one-package/one-command
-identity above and will fail if the script-bearing set changes.
+`@effect/platform-bun` resolves `@effect/platform-node-shared` through a caret
+range, which installs rc.111, and that release declares a peer requirement of
+`effect@^4.0.0-rc.111`. The kit pins `effect@4.0.0-rc.109` deliberately, so this
+newer transitive peer range cannot be satisfied. `docks-kit --version`, model
+catalogs, toolchain checks, and real sync are unaffected.
 
-## 3. curl installer (Linux/macOS)
+## 3. curl installer (POSIX)
 
 ```
 curl -fsSL https://raw.githubusercontent.com/DocksDocks/public/main/install.sh -o /tmp/docks-kit-install.sh
@@ -64,8 +60,22 @@ bash /tmp/docks-kit-install.sh && rm /tmp/docks-kit-install.sh
 
 Download-then-run, never `curl | bash` — stream truncation has bitten this
 kit before. The installer bootstraps Bun when absent, runs
-`bun add -g docks-kit`, and links the binary into `~/.local/bin`.
-This installer supports Linux and macOS only.
+`bun add -g docks-kit@latest`, and links the binary into `~/.local/bin`.
+This installer serves the two POSIX platforms. Windows uses the PowerShell
+installer below.
+
+## 4. PowerShell installer (Windows)
+
+```powershell
+Invoke-WebRequest https://raw.githubusercontent.com/DocksDocks/public/main/install.ps1 -OutFile "$env:TEMP\docks-kit-install.ps1"
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$env:TEMP\docks-kit-install.ps1"
+Remove-Item "$env:TEMP\docks-kit-install.ps1"
+```
+
+Download the script before execution. Never stream it into PowerShell. The
+installer bootstraps Bun when absent. It then runs
+`bun add -g docks-kit@latest` and copies the CLI plus Bun into
+`%USERPROFILE%\.local\bin`.
 
 ## Keeping the kit up to date
 
@@ -114,6 +124,7 @@ sync/config reads.
 - Bun for source/global installs; release binaries embed the runtime
 - 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 Bun bootstrap must download
-  an installer; an already-present Bun does not require it
+- curl is required only when a source launcher must download Bun. The POSIX
+  launchers run `install.sh`; Windows runs `install.ps1` through PowerShell.
+  An already-present Bun does not require curl.
 - See `docks-kit toolchain check` for the full picture on this machine

package/cli/docs/overview.md

@@ -16,8 +16,8 @@ AI-assisted dev environment on every machine.
 | `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 4 beta on Bun) plus bundled docs |
-| `docks-kit` | Launcher: version-matching compiled binary → bun-from-source, with Bun auto-install |
+| `cli/` | This CLI (Effect 4 RC on Bun) plus bundled docs |
+| `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers: version-matching compiled binary → Bun-from-source, with Bun auto-install |
 
 ## Design rules
 

package/cli/docs/platforms.md

@@ -8,9 +8,12 @@ The supported host matrix is exact:
 | Linux | arm64 | `docks-kit-linux-arm64` | EngineNative (TS) |
 | macOS | x64 | `docks-kit-darwin-x64` | EngineNative (TS) |
 | macOS | arm64 | `docks-kit-darwin-arm64` | EngineNative (TS) |
+| Windows | x64 | `docks-kit-windows-x64.exe` | EngineNative (TS) |
+| Windows | arm64 | `docks-kit-windows-arm64.exe` | EngineNative (TS) |
 
-Windows and every other host are unsupported. The launcher fails before any
-Bun-from-source fallback.
+POSIX hosts use the `docks-kit` launcher. Windows uses `docks-kit.ps1`.
+Hosts outside this table fail before either launcher can fall back to Bun
+source.
 
 EngineNative is the only supported engine on supported hosts.
 `DOCKS_KIT_ENGINE=bash` exits with the removed-engine message and points at the

package/cli/docs/sync-layers.md

@@ -17,8 +17,8 @@ Order matters — runtime readiness and settings form one transaction:
    unioned, user-only keys survive. `--reconcile` replaces permissions arrays
    wholesale instead.
 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
+   kit-owned settings, retired kit-owned plugin enablement, and every
+   manifest-listed kit-owned `~/.local/bin` command. A flag-less sync removes
    `advisorModel`; an explicit advisor state excludes only that key so the
    modifier owns it.
 5. **Deploy-time modifiers** (`--claude-compact-window`, `--claude-permissive`,
@@ -43,8 +43,7 @@ and `codex plugin add` refresh.
 
 ## agents (→ ~/.agents/skills, ~/.claude/skills symlinks)
 
-`npx skills add` per missing manifest slug, Claude symlink healing,
-the effect-solutions CLI (toolchain-gated), and the
+`npx skills add` per missing manifest slug, Claude symlink healing, and the
 kit-managed snapshot that `--prune` reconciles against.
 
 ## Reconcile flags

package/cli/docs/toolchain.md

@@ -4,53 +4,47 @@
 
 | Field | Meaning |
 |-------|---------|
-| `kind` | `check` (doctor visibility) / `managed` (kit installs + upgrades) / `pin` (no binary — a version pin for npx-invoked tools, e.g. `skills-cli`) |
-| `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 |
+| `kind` | `check` (doctor visibility) / `managed` (kit-managed install) / `pin` (no binary — a version pin for npx-invoked tools, e.g. `skills-cli`) |
+| `policy` | Installation policy; `present` installs when missing and never upgrades |
+| `floor` | Minimum acceptable version shown in the doctor table |
+| `verified` | Last kit-tested version and the exact pin for kit-driven installs |
 | `pinnable` | Whether an exact version can be installed |
 
-## The gate
-
-When an install/upgrade candidate is **above `verified`**:
-
-- **TTY**: prompt — "X <latest> is not kit-verified (verified: <v>). Install anyway? [y/N]"
-- **`--yes`**: proceed with a warning (containers/CI)
-- **non-TTY, declined**:
-  - install mode (tool missing) + pinnable → install the pinned `verified` version
-  - upgrade mode → stay on the installed version, warn
-
-At or below `verified`, installs/upgrades run silently. After testing a new
-release, bump `verified` in SoT/toolchain.json — that is the "this version is
-now kit-approved" act.
+`docks-kit toolchain check` reports each installed version against the
+manifest's `floor` and `verified` columns.
+Before running `bun install --frozen-lockfile`, the checkout launchers reject Bun versions below the manifest's `floor` and direct the user to `bun upgrade`.
+Their generated Bun floor is intentionally separate from the generated `verified` pin: the floor gates lockfile compatibility, while the verified pin selects the exact release for kit-driven installs.
 
 ## Managed tools
 
-- **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** — policy `track`: self-upgrades toward npm latest,
-  gated by its `verified` pin.
+- **bun** — policy `present`: installed from the pinned `verified` release and
+  never auto-upgraded. `bun.ts` `bunBootstrap` owns one per-engine-run memo
+  shared by the Claude runtime and direct `toolchain ensure bun` on every
+  supported host. The POSIX modules download `install.sh` with curl and run it
+  with Bash. The Windows module downloads `install.ps1` with curl and runs it
+  through `powershell.exe`.
 
 jq and curl are `check` rows, not global prerequisites. jq is not consumed by
-normal sync. curl is checked only when a requested Linux/macOS Bun bootstrap
-must download an installer.
+normal sync. curl is checked only when a requested Bun bootstrap must download
+an installer. An already-present Bun skips that download on every host.
 
 ## Supply-chain stance
 
-Every kit-driven install is pinned to a `verified` version or gated by one —
-never floating `@latest` (the npm-worm / Shai-Hulud attack surface). That
-includes the `npx skills@<verified>` invocations on agents sync and the release
-workflow (actions pinned to commit SHAs, exact bun/npm versions).
-Callbacks receive the exact gate-approved version; an offline "latest unknown"
-probe falls back to the pinned `verified`, never to an ungated latest.
+Every kit-driven install of third-party software is pinned to a
+`SoT/toolchain.json` `verified` version — never floating `@latest` (the
+npm-worm / Shai-Hulud attack surface). That includes the
+`npx skills@<verified>` invocations on agents sync and the release workflow
+(actions pinned to commit SHAs, exact bun/npm versions).
+
+The kit's own package is the single exemption. `install.sh` and `install.ps1`
+end with `bun add -g docks-kit@latest` because a global installer that pinned
+itself would install a fixed old kit forever. The exemption covers `docks-kit`
+alone; both installers still pin the Bun installer they download to the
+manifest's `verified` version.
 
 ## Commands
 
 ```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
+docks-kit toolchain ensure bun               # ensure the only managed tool
 ```

package/cli/src/commands/docs.ts

@@ -17,10 +17,10 @@ const TOPICS: Record<string, { summary: string; body: string }> = {
   "flags": { summary: "Full flag reference incl. the old→new rename table", body: flags },
   "modifiers": { summary: "Deploy-time modifiers and the flag-less-sync-reverts contract", body: modifiers },
   "models": { summary: "Model catalog, validation rules, model get/set", body: models },
-  "toolchain": { summary: "Verified-version floors, gate policy, --yes semantics", body: toolchain },
+  "toolchain": { summary: "Verified-version floors and the doctor table", body: toolchain },
   "plugins": { summary: "enabledPlugins tri-state + optional plugin opt-ins", body: plugins },
-  "install": { summary: "Install paths: repo checkout, bun add -g, curl installer", body: install },
-  "platforms": { summary: "Platform support: Linux/macOS x64 and arm64", body: platforms }
+  "install": { summary: "Install paths: repo checkout, bun add -g, POSIX/Windows installers", body: install },
+  "platforms": { summary: "Platform support: Linux, macOS, and Windows on x64 and arm64", body: platforms }
 }
 
 const topic = Argument.string("topic").pipe(

package/cli/src/commands/sync.ts

@@ -52,9 +52,6 @@ const skipBubblewrap = Flag.boolean("skip-bubblewrap").pipe(
 const skipPluginRefresh = Flag.boolean("skip-plugin-refresh").pipe(
   Flag.withDescription("Install missing plugins but skip refresh-only updates for existing plugins")
 )
-const yes = Flag.boolean("yes").pipe(
-  Flag.withDescription("Auto-accept toolchain prompts (containers/CI)")
-)
 const verbose = Flag.boolean("verbose").pipe(
   Flag.withAlias("v"),
   Flag.withDescription("Also print no-op confirmations (already in sync, up to date, left as-is)")
@@ -102,7 +99,6 @@ export const syncCommand = Command.make(
     prune,
     skipBubblewrap,
     skipPluginRefresh,
-    yes,
     verbose,
     claudeModel,
     claudeEffort,
@@ -128,7 +124,6 @@ export const syncCommand = Command.make(
       if (config.prune) args.push("--prune")
       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")
       if (config.claudePermissive) args.push("--claude-permissive")
       Option.map(config.claudeModel, (m) => args.push(`--claude-model=${m}`))

package/cli/src/commands/toolchain.ts

@@ -2,7 +2,7 @@ import { Argument, Command, Flag } from "effect/unstable/cli"
 import { Effect, Option } from "effect"
 import { bail, engine } from "../engine"
 
-const MANAGED = ["bun", "effect-solutions"]
+const MANAGED = ["bun"]
 
 const op = Argument.string("op").pipe(
   Argument.withDescription("check (default) | ensure <tool>"),
@@ -12,18 +12,15 @@ const tool = Argument.string("tool").pipe(
   Argument.withDescription(`Managed tool for ensure: ${MANAGED.join(", ")}`),
   Argument.optional
 )
-const yes = Flag.boolean("yes").pipe(
-  Flag.withDescription("Auto-accept above-verified installs")
-)
 const verbose = Flag.boolean("verbose").pipe(
   Flag.withAlias("v"),
   Flag.withDescription("Also print no-op confirmations (present, up to date)")
 )
 
-export const toolchainCommand = Command.make("toolchain", { op, tool, yes, verbose }, (config) =>
+export const toolchainCommand = Command.make("toolchain", { op, tool, verbose }, (config) =>
   Effect.gen(function* () {
     const operation = Option.getOrElse(config.op, () => "check")
-    const flags = [...(config.yes ? ["--yes"] : []), ...(config.verbose ? ["--verbose"] : [])]
+    const flags = config.verbose ? ["--verbose"] : []
 
     switch (operation) {
       case "check":
@@ -41,6 +38,6 @@ export const toolchainCommand = Command.make("toolchain", { op, tool, yes, verbo
   })
 ).pipe(
   Command.withDescription(
-    "Verified-version floors for external tools (SoT/toolchain.json): check prints the doctor table; ensure installs/upgrades one managed tool per policy (above-verified versions prompt; --yes accepts)."
+    "Verified-version floors for external tools (SoT/toolchain.json): check prints the doctor table; ensure installs one managed tool when it is missing."
   )
 )