docks-kit 0.15.1 → 0.15.3

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.
@@ -91,9 +97,43 @@ When a kit-mechanic skill, its `references/`, or a wrapper agent (`.claude/agent
 
 ## Plans
 
-Use direct implementation for one clear reversible low-risk local diff with one bounded acceptance path; it creates no plan, reviewer, or automatic commit. Canonical plans live in `docs/plans/active/`; lifecycle is frontmatter, and `docs/plans/finished/` is terminal. Exactly three skills own the workflow: `plan-workspace` maintains the workspace, main-context `plan-manager` owns classify → draft/review/one repair → start → implement/delegate → observed acceptance → finish/archive, and internal `plan-reviewer` returns read-only `PlanReviewV1` evidence from one immutable bundle. Only the reviewer has wrappers.
+Use direct implementation for one clear, reversible, low-risk local diff with one
+bounded acceptance path; it creates no tracked plan, reviewer, or automatic
+commit. Use a canonical plan for explicit planning, multi-commit or
+cross-repository work, cold handoff, an unresolved decision, a cross-subsystem or
+public-contract change, security-sensitive or destructive work, or any
+non-`local` effect.
+
+<constraint>
+Canonical plans live in `docs/plans/active/`; status is frontmatter and
+`docs/plans/finished/` is terminal. Exactly three skills own the workflow:
+`plan-workspace` maintains the workspace; main-context `plan-manager` runs six
+phases — decide, draft, research, one plan review, implement, code review — and
+archives; internal `plan-reviewer` returns a readable pre-implementation verdict.
+Two read-only reviewer wrappers ship, `plan-reviewer` and `code-reviewer`, and
+nothing else in the lifecycle has a wrapper.
+</constraint>
 
-The current record is one compact-JCS `Plan-run: PlanRunV1` line. Schemas 1–6 are historical validation/quarantine only. Every Steps row has `Effect: local|probe|production_access|publish|push|release|deploy`; a persisted requested effect is never live authority. The complete transaction, review-budget, checkpoint, legacy-quarantine, and external-authority contract lives in `docs/plans/AGENTS.md`; `docs/plans/CLAUDE.md` contains only `@AGENTS.md`.
+The record is markdown only: `plan_contract: v2` frontmatter plus eight `##`
+sections — `## Goal`, `## Research`, `## Steps`, `## Acceptance`,
+`## Do not touch`, `## Open questions`, `## Review`, `## Verification Results`.
+There are no hashes, permits, run identities, locks, bundles, or `v2`/`vN` plan
+files, and the `plan.mjs` shipped inside the installed `plan-lifecycle` plugin
+is the only lifecycle tool. This lifecycle creates zero commits and never
+pushes; commit when the user asks, under `docks:commit-discipline`.
+
+Every Steps row carries an `Effect` of exactly
+`local|probe|production_access|publish|push|release|deploy`. A step whose
+`Effect` is not `local` requires an in-session `ask` confirmation immediately
+before it runs; when `ask` is unavailable the step is set `blocked` with
+`blocked_reason` naming the unconfirmed effect. Persisted effects record intent
+only.
+
+A plan carrying a `Plan-run:` line is a v1 plan: render it, never parse or
+migrate it, and finish it by hand by moving the file byte-unchanged to
+`docs/plans/finished/<YYYY-MM-DD>-<slug>.md` with a `## Retirement` section
+appended. The complete contract lives in `docs/plans/AGENTS.md`;
+`docs/plans/CLAUDE.md` contains only `@AGENTS.md`.
 
 Distinct from per-tool **Open Concerns** sections (wait-on-upstream
 blockers tied to a vendor shipping a fix — these live inside the per-tool

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.1 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.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

@@ -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
@@ -55,7 +55,7 @@ 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.
 
-## 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 +64,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 +128,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,45 @@
 
 | 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.
 
 ## 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/model.ts

@@ -32,6 +32,9 @@ export const modelCommand = Command.make(
       const dry = [...(config.dryRun ? ["--dry-run"] : []), ...(config.verbose ? ["--verbose"] : [])]
 
       if (Option.isSome(config.value)) {
+        if (config.value.value.trim() === "") {
+          return yield* bail("Model value must not be empty or blank")
+        }
         return yield* engine(["model", t, config.value.value, ...dry])
       }
 

package/cli/src/commands/models.ts

@@ -18,6 +18,11 @@ const renderTool = (t: Tool) =>
     for (const m of catalog.models) {
       yield* Console.log(`  ${m.id.padEnd(28)} ${m.kind.padEnd(6)} ${m.note ?? ""}`)
     }
+    yield* Console.log(
+      t === "claude"
+        ? "  (full claude-* model IDs outside the catalog are accepted with a warning)"
+        : "  (well-formed IDs outside the catalog are accepted with a warning)"
+    )
     yield* Console.log("")
   })
 
@@ -37,9 +42,6 @@ export const modelsCommand = Command.make("models", { tool, json }, (config) =>
     for (const t of tools) {
       yield* renderTool(t)
     }
-    yield* Console.log(
-      "Catalog: SoT/models.json (research-verified). Well-formed IDs outside it apply with a warning."
-    )
   })
 ).pipe(
   Command.withDescription("List kit-verified Claude and Codex models (SoT/models.json).")