docks-kit 0.1.0 → 0.1.2

package/AGENTS.md

@@ -14,18 +14,16 @@ Tool-specific instructions live alongside this file:
 
 | Path | Purpose |
 |------|---------|
-| `docks-kit` | CLI launcher: runs the compiled binary in `cli/dist/` when present, otherwise Bun-from-source (auto-installs Bun + `node_modules`). Front-end over the bash engine; idempotent, flag-gated for destructive reconciliation |
-| `lib/engine.sh` | Engine entry — direct modes `sync` / `model` / `toolchain`; the zero-dependency escape hatch when Bun is unavailable: `bash lib/engine.sh <same args>` |
-| `lib/toolchain.sh` | Verified-version floors for external tools (RTK, …) over `SoT/toolchain.json` |
-| `lib/` | Shared sync helpers — `common.sh` for flag parsing/validation/preflight, plus per-tool `claude.sh` / `codex.sh` / `skills.sh` sync implementations |
-| `cli/` | Effect-TS CLI (typed front-end over the engine) + bundled docs topics |
+| `docks-kit` | CLI launcher: runs the compiled binary in `cli/dist/` when present, otherwise Bun-from-source (auto-installs Bun + `node_modules`). No-Bun recovery is the platform release binary |
+| `cli/src/engine-native/` | EngineNative implementation for `sync`, `model`, and `toolchain`; idempotent, flag-gated for destructive reconciliation |
+| `cli/` | Effect-TS CLI + bundled docs topics |
 | `SoT/models.json` | Kit-verified model catalog |
-| `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by `lib/toolchain.sh`) |
+| `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative) |
 | `install.sh` | Global installer |
 | `.github/workflows/release-cli.yml` | `cli-v*` release binaries + npm publish |
 | `README.md` | Front door |
-| `package.json` / `bun.lock` | npm package: `bin` = `cli/src/main.ts`; bundles `lib/` + `SoT/` |
-| `SoT/.agents/skills.txt` | Universal-skill manifest. One [agentskills.io](https://agentskills.io) slug per line; `lib/skills.sh` runs `npx skills add` for each missing entry into `~/.agents/skills/`, where Codex et al. discover it natively and Claude Code follows a symlink at `~/.claude/skills/` |
+| `package.json` / `bun.lock` | npm package: `bin` = `cli/src/main.ts`; bundles `cli/` + `SoT/` |
+| `SoT/.agents/skills.txt` | Universal-skill manifest. One [agentskills.io](https://agentskills.io) slug per line; EngineNative runs `npx skills add` for each missing entry into `~/.agents/skills/`, where Codex et al. discover it natively and Claude Code follows a symlink at `~/.claude/skills/` |
 | `notification.mp3` | Audio asset for Notification hooks (consumed by Claude Code today; tool-agnostic file) |
 | `docs/plans/` | Multi-commit work-item plans (`active/` with status in frontmatter, plus `finished/` archive). Convention: `docs/plans/AGENTS.md` |
 | `CLAUDE.md` | Claude-specific instructions; imports this `AGENTS.md` |
@@ -43,11 +41,12 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT d
 
 ## Engineering rules
 
-- **Idempotent operations.** Every step in `lib/engine.sh` and `lib/*.sh` 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.
+- **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`, `--reconcile`, `--prune`, `--yes` (auto-accept toolchain prompts), and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--codex-model=<m>` (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; 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 libraries.** `lib/common.sh` owns shared primitives plus flag parsing/validation. `lib/toolchain.sh` owns the verified-version gate over `SoT/toolchain.json`. Each `lib/<tool>.sh` owns the tool-specific logic (plugin install passes, marketplace add) plus its toolchain install callbacks. `lib/engine.sh` is the thin orchestrator: source common → detect SoTs → dispatch. The TypeScript CLI (`cli/src/`) is a typed front-end whose single mutation seam is spawning `lib/engine.sh`.
+- **SOLID-aligned modules.** `cli/src/engine-native/parseArgs.ts` owns flag parsing/validation. `toolchain.ts` owns the verified-version gate over `SoT/toolchain.json`. `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.
@@ -55,7 +54,7 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT d
 
 ## Code style
 
-- Bash: `set -euo pipefail`, quoted variables, `[[ ]]` over `[ ]`, function-scoped `local`. Match `lib/engine.sh`.
+- Bash: for launchers/installers/hook assets, use `set -euo pipefail`, quoted variables, `[[ ]]` over `[ ]`, and function-scoped `local`.
 - JSON config: edit the SoT (`SoT/<tool>/`) and run `./docks-kit sync`. Never edit deployed config (`~/.claude/`, `~/.codex/`) directly.
 
 ## Security
@@ -66,17 +65,17 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT d
 
 ## Testing
 
-No automated tests yet. Verify 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. Shell-script tests are tracked in `docs/plans/`.
+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.
 
 ## Skills
 
-This project ships **kit-mechanic skills** under `.claude/skills/` — narrowly-scoped references for how the sync engine (`lib/engine.sh`) itself works (settings merge, plugin bootstrap, universal-skill install, Codex TOML merge, sync orchestration). They cost prompt tokens only inside this repo's sessions and document regression-prone bash/awk/jq logic in `lib/*.sh`. **Pipeline content** (multi-agent slash commands, refactor/security/docs workflows, parallel-scanner agents) belongs in the separate [DocksDocks/docks](https://github.com/DocksDocks/docks) plugin — not here. Project-level agents under `.claude/agents/` follow the same rule: kit-mechanic agents that wrap kit-mechanic skills are permitted; pipeline agents live in the docks plugin.
+This project ships **kit-mechanic skills** under `.claude/skills/` — narrowly-scoped references for how EngineNative works (settings merge, plugin bootstrap, universal-skill install, Codex TOML merge, sync orchestration). They cost prompt tokens only inside this repo's sessions and document regression-prone TypeScript sync logic in `cli/src/engine-native/`. **Pipeline content** (multi-agent slash commands, refactor/security/docs workflows, parallel-scanner agents) belongs in the separate [DocksDocks/docks](https://github.com/DocksDocks/docks) plugin — not here. Project-level agents under `.claude/agents/` follow the same rule: kit-mechanic agents that wrap kit-mechanic skills are permitted; pipeline agents live in the docks plugin.
 
 <constraint>
-When a kit-mechanic skill, its `references/`, or a wrapper agent (`.claude/agents/*.md` + its `.codex/agents/*.toml` twin) cites `lib/*.sh` / `lib/engine.sh` internals, name the **enclosing function + a semantic anchor** (e.g. `claude::_plugins_uninstall, the has($n) guard`) — never a raw `file:NNN` line number, which goes stale on every refactor. Keep exactly one coarse `metadata.source_files[].lines` range per skill file as the sole intentional line-number touchpoint.
+When a kit-mechanic skill, its `references/`, or a wrapper agent (`.claude/agents/*.md` + its `.codex/agents/*.toml` twin) cites EngineNative internals, name the **module + exported/local function + semantic anchor** (e.g. `claudeSync.ts syncPlugins, pass 5 uninstall guard`) — never a raw `file:NNN` line number, which goes stale on every refactor. Keep exactly one coarse `metadata.source_files[].lines` range per skill file as the sole intentional line-number touchpoint.
 </constraint>
 
-**Universal-skill bootstrap.** `SoT/.agents/skills.txt` declares [agentskills.io](https://agentskills.io/specification) slugs the kit installs to `~/.agents/skills/` on every machine via `lib/skills.sh`. The bootstrap invokes `npx skills add <slug> -g -y -a claude-code codex` per missing skill — `<slug>` comes first because the CLI's `-a/--agent` flag is variadic and would otherwise swallow it. Naming **both** agents (`claude-code` + `codex`, the kit's support matrix) keeps the CLI in multi-agent mode: it writes the canonical `SKILL.md` to the universal `~/.agents/skills/<name>/` path — which Codex reads natively (per [OpenAI's Codex docs](https://developers.openai.com/codex/skills/), `$HOME/.agents/skills` is a user-level skill source) — and symlinks `~/.claude/skills/<name>` → it for Claude Code, which wants its own per-tool directory. A *single* `-a claude-code` would instead trigger a copy-direct shortcut (a real copy into `~/.claude/skills/`, no canonical path, Codex uncovered); `-a '*'` would over-reach into every AI tool the CLI can detect (~50). Add a new universal skill by appending one `<owner>/<repo>` line to `skills.txt` and re-running `./docks-kit sync` — idempotent: existing skills are skipped (`lib/skills.sh` pre-checks `~/.agents/skills/<name>`). Skills that depend on a separate CLI binary get an explicit auto-install helper in `lib/skills.sh` (e.g. `skills::sync_agent_browser_cli` runs `npm install -g agent-browser` + `agent-browser install --with-deps` on Linux; the `--with-deps` flag may prompt for sudo to install system libs). That helper also **self-upgrades** a present-but-stale binary: when `agent-browser`'s installed version is older than npm's `latest` it re-runs `npm install -g agent-browser` (the `skills::_agent_browser_newer_npm` numeric-sort compare never downgrades a locally-newer pre-release, and skips silently when npm is absent/offline); the Chrome download is not repeated on upgrade. A second such helper, `skills::sync_effect_solutions_cli`, installs the optional `effect-solutions` Effect-docs CLI used by the `effect-kit` plugin: gated on `effect-kit` being enabled in SoT, it auto-installs Bun when absent (download-then-run, never `curl | bash`) and symlinks **both** `bun` and the CLI into `~/.local/bin`. Linking bun too is mandatory — the CLI's `#!/usr/bin/env bun` shebang needs `bun` on PATH at run time — and `~/.local/bin` is the only dir reliably on the *non-interactive* agent PATH, since `~/.bashrc`'s "if not interactive, return" guard means rc PATH edits never reach agent shells (the same PATH reason the official Codex standalone installer targets `~/.local/bin`).
+**Universal-skill bootstrap.** `SoT/.agents/skills.txt` declares [agentskills.io](https://agentskills.io/specification) slugs the kit installs to `~/.agents/skills/` on every machine via `skillsSync.ts`. The bootstrap invokes `npx skills add <slug> -g -y -a claude-code codex` per missing skill — `<slug>` comes first because the CLI's `-a/--agent` flag is variadic and would otherwise swallow it. Naming **both** agents (`claude-code` + `codex`, the kit's support matrix) keeps the CLI in multi-agent mode: it writes the canonical `SKILL.md` to the universal `~/.agents/skills/<name>/` path — which Codex reads natively (per [OpenAI's Codex docs](https://developers.openai.com/codex/skills/), `$HOME/.agents/skills` is a user-level skill source) — and symlinks `~/.claude/skills/<name>` → it for Claude Code, which wants its own per-tool directory. A *single* `-a claude-code` would instead trigger a copy-direct shortcut (a real copy into `~/.claude/skills/`, no canonical path, Codex uncovered); `-a '*'` would over-reach into every AI tool the CLI can detect (~50). Add a new universal skill by appending one `<owner>/<repo>` line to `skills.txt` and re-running `./docks-kit sync` — idempotent: existing skills are skipped after checking `~/.agents/skills/<name>`. Skills that depend on a separate CLI binary get an explicit auto-install helper in `skillsSync.ts` (e.g. `syncAgentBrowserCli` runs `npm install -g agent-browser` + `agent-browser install --with-deps` on Linux; the `--with-deps` flag may prompt for sudo to install system libs). That helper also **self-upgrades** a present-but-stale binary: when `agent-browser`'s installed version is older than npm's `latest` it re-runs `npm install -g agent-browser` (the numeric-sort compare never downgrades a locally-newer pre-release, and skips silently when npm is absent/offline); the Chrome download is not repeated on upgrade. A second helper, `syncEffectSolutionsCli`, installs the optional `effect-solutions` Effect-docs CLI used by the `effect-kit` plugin: gated on `effect-kit` being enabled in SoT, it auto-installs Bun when absent (download-then-run, never `curl | bash`) and symlinks **both** `bun` and the CLI into `~/.local/bin`. Linking bun too is mandatory — the CLI's `#!/usr/bin/env bun` shebang needs `bun` on PATH at run time — and `~/.local/bin` is the only dir reliably on the *non-interactive* agent PATH, since `~/.bashrc`'s "if not interactive, return" guard means rc PATH edits never reach agent shells (the same PATH reason the official Codex standalone installer targets `~/.local/bin`).
 
 ## Plans
 

package/README.md

@@ -23,18 +23,19 @@ from source via Bun — auto-installing Bun and dependencies when missing.
 Other install paths (global `bun add -g docks-kit`, curl installer) —
 see `./docks-kit docs install`.
 
-**Zero-dependency escape hatch** (no Bun, constrained sandboxes):
+**No-Bun recovery path**:
 
-```bash
-bash lib/engine.sh sync [targets] [flags]    # same flags as the CLI
-```
+Download the platform release binary from GitHub Releases and run it from a
+kit checkout, or set `DOCKS_KIT_HOME` to the checkout containing `SoT/`.
 
-Prerequisites: `bash`, `jq`, `curl` (Node/npm for npm-global tools).
+Prerequisites for source/global installs: Bun plus `jq` and `curl` for sync
+preflight; Node/npm for npm-global tools.
 
 ## CLI
 
 ```text
 docks-kit sync [claude] [codex] [agents]   deploy the SoT (default: all three)
+docks-kit update [--no-sync]               self-update the kit (autodetects checkout vs global install), then sync
 docks-kit model <claude|codex> [value]     get/set the DEPLOYED model (TTY picker)
 docks-kit models [tool] [--json]           kit-verified model catalog
 docks-kit toolchain [check|ensure <tool>]  verified-version floors for external tools
@@ -46,8 +47,8 @@ docks-kit docs [topic]                     self-documentation (9 topics)
 ```
 
 The CLI is a typed front-end ([Effect-TS](https://effect.website) on Bun);
-**all mutation runs through the bash engine** (`lib/*.sh`) — battle-tested,
-idempotent, independently usable.
+all mutation runs through EngineNative in `cli/src/engine-native/`, with
+golden-regression coverage for dry-run output, mutation snapshots, and argv logs.
 
 ### Key flags (`docks-kit sync`)
 
@@ -91,7 +92,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 | `SoT/.agents/` | Universal-skill manifest |
 | `SoT/models.json` | Kit-verified model catalog |
 | `SoT/toolchain.json` | Verified-version floors |
-| `lib/` | Bash engine: `common`, `toolchain`, `claude`, `codex`, `skills`, `engine` |
+| `cli/src/engine-native/` | EngineNative sync/model/toolchain implementation |
 | `cli/` | docks-kit CLI (Effect-TS on Bun) + bundled docs topics |
 | `docks-kit` | Launcher (binary → bun-from-source) |
 | `install.sh` | Global installer (Bun bootstrap + `bun add -g`) |
@@ -104,7 +105,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 |----------|-----|-------------|
 | Linux | ✅ native | ✅ native |
 | macOS (x64/arm64) | ✅ native | ✅ native |
-| Windows | ✅ native binary | ⚠️ experimental via Git Bash (present wherever Claude Code is); full RTK hooks need WSL |
+| Windows | ✅ native binary (`.exe` and `bun add -g` CI-verified) | ✅ EngineNative (TS, default engine — no Git Bash); real-machine verify pending — RTK hooks are native too (rtk ≥0.37.2) |
 
 Details: `docks-kit docs platforms`.
 
@@ -112,8 +113,8 @@ Details: `docks-kit docs platforms`.
 
 Tagging `cli-v*` builds five standalone binaries (+ SHA256SUMS) and attaches
 them to the GitHub release; npm publish runs when the `NPM_TOKEN` secret is
-configured. Package bundles the engine + SoT, so npm releases are versioned
-config snapshots.
+configured. Package bundles the CLI + SoT, so npm releases are versioned config
+snapshots.
 
 ## Deeper docs
 

package/SoT/.agents/skills.txt

@@ -1,13 +1,13 @@
 # Universal AI-agent skills (agentskills.io standard).
-# Bootstrapped to ~/.agents/skills/ by lib/skills.sh during ./sync.sh.
+# Bootstrapped to ~/.agents/skills/ by cli/src/engine-native/skillsSync.ts during ./docks-kit sync.
 # One slug per line: <owner>/<repo>. Lines starting with # are comments.
 # Each skill's canonical SKILL.md lands in ~/.agents/skills/<name>/ — Codex
 # reads that path natively; Claude Code gets a ~/.claude/skills/<name>
-# symlink to it. lib/skills.sh names both agents the kit supports
+# symlink to it. The skills sync names both agents the kit supports
 # (-a claude-code codex) so the CLI keeps the shared canonical copy.
 
 # Browser automation CLI — reaches JS-rendered, auth-walled, login-gated pages
-# (x.com, LinkedIn, Confluence) that built-in WebFetch can't. `lib/skills.sh`
+# (x.com, LinkedIn, Confluence) that built-in WebFetch can't. The skills sync
 # auto-installs the `agent-browser` npm package + downloads Chrome for Testing
 # (~175 MB) on first sync; Linux runs `agent-browser install --with-deps` which
 # may prompt for sudo to install system libs (libnss3, libatk, ...).

package/SoT/.claude/settings.json

@@ -124,32 +124,9 @@
       "Bash(git push -f origin master *)"
     ],
     "ask": [
-      "Bash(git push *)",
-      "Bash(git reset *)",
       "Bash(git clean *)",
-      "Bash(git merge *)",
-      "Bash(git rebase *)",
-      "Bash(git checkout -- *)",
-      "Bash(git checkout . *)",
-      "Bash(rm *)",
-      "Bash(mv *)",
-      "Bash(chmod *)",
-      "Bash(chown *)",
-      "Bash(kill *)",
-      "Bash(pkill *)",
-      "Bash(docker run *)",
-      "Bash(docker rm *)",
-      "Bash(docker stop *)",
       "Bash(docker volume rm *)",
-      "Bash(docker system prune *)",
-      "Bash(docker-compose down *)",
-      "Bash(docker-compose up *)",
-      "Bash(sed -i *)",
-      "Bash(xargs *)",
-      "Bash(pip install *)",
-      "Bash(pip uninstall *)",
-      "Bash(pip3 install *)",
-      "Bash(pip3 uninstall *)"
+      "Bash(docker system prune *)"
     ]
   },
   "hooks": {
@@ -198,7 +175,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PostToolUseFailure\",\"additionalContext\":\"Last bash command failed. Repository / file state may have shifted — re-read affected files before retrying. If the failure is a missing dependency or env mismatch, surface it to the user rather than retrying blindly.\"}}'",
+            "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PostToolUseFailure\",\"additionalContext\":\"Last bash command failed. Repository / file state may have shifted \u2014 re-read affected files before retrying. If the failure is a missing dependency or env mismatch, surface it to the user rather than retrying blindly.\"}}'",
             "timeout": 5
           }
         ]
@@ -221,7 +198,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "You are a quality gate for subagent outputs in a multi-agent code-analysis pipeline.\n\nEvaluate the subagent's `last_assistant_message` field (in the JSON below) against these requirements:\n\n1. ALLOW (return `{}`): Mode-selection or no-issues responses. Examples: \"Which mode do you prefer\", \"select an option\", \"no issues / problems / violations / blockers found\".\n\n2. ALLOW (return `{}`): Output contains at least one concrete file:line citation — e.g. `src/auth.ts:42`, `lib/db.ts:100-115`, or path references that include line numbers.\n\n3. BLOCK (return `{\"decision\":\"block\",\"reason\":\"<one-line explanation>\"}`): Output claims about code or findings WITHOUT concrete file:line citations. Vague references like \"the auth handler\" or \"near the database code\" are not acceptable as the only evidence.\n\nSubagent invocation JSON:\n$ARGUMENTS\n\nReturn ONLY the JSON decision (no commentary, no markdown fences).",
+            "prompt": "You are a quality gate for subagent outputs in a multi-agent code-analysis pipeline.\n\nEvaluate the subagent's `last_assistant_message` field (in the JSON below) against these requirements:\n\n1. ALLOW (return `{}`): Mode-selection or no-issues responses. Examples: \"Which mode do you prefer\", \"select an option\", \"no issues / problems / violations / blockers found\".\n\n2. ALLOW (return `{}`): Output contains at least one concrete file:line citation \u2014 e.g. `src/auth.ts:42`, `lib/db.ts:100-115`, or path references that include line numbers.\n\n3. BLOCK (return `{\"decision\":\"block\",\"reason\":\"<one-line explanation>\"}`): Output claims about code or findings WITHOUT concrete file:line citations. Vague references like \"the auth handler\" or \"near the database code\" are not acceptable as the only evidence.\n\nSubagent invocation JSON:\n$ARGUMENTS\n\nReturn ONLY the JSON decision (no commentary, no markdown fences).",
             "timeout": 30
           }
         ]

package/SoT/models.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "Kit-verified model catalog — single source for the engine validators (lib/common.sh), the docks-kit CLI (models/model commands, pickers, bare-flag help), and docs. Entries are research-proofed: update an entry and its tool-level `verified` date when a model ships or retires. The catalog informs, it doesn't imprison: well-formed IDs outside it (claude-* / codex charset) apply with a warning.",
+  "$comment": "Kit-verified model catalog — single source for EngineNative validators, the docks-kit CLI (models/model commands, pickers, bare-flag help), and docs. Entries are research-proofed: update an entry and its tool-level `verified` date when a model ships or retires. The catalog informs, it doesn't imprison: well-formed IDs outside it (claude-* / codex charset) apply with a warning.",
   "claude": {
     "verified": "2026-07-08",
     "models": [

package/SoT/toolchain.json

@@ -1,7 +1,7 @@
 {
-  "$comment": "Kit toolchain manifest — DATA only (versions, floors, policy); the check/install logic lives in lib/toolchain.sh and the per-tool install callbacks in each lib. kind: required (preflight hard dep) | check (doctor visibility only) | managed (kit installs/upgrades it) | pin (no binary probe — a version pin for a tool the kit invokes via npx). policy (managed only): track (upgrade toward latest, gated by `verified`) | present (install when missing, never upgrade). `verified` = last kit-tested version — anything above it prompts before install (--yes auto-accepts; non-TTY declines and falls back to the pinned `verified` when pinnable). Supply-chain stance: every kit-driven install is pinned to `verified` or gated by it — never floating @latest (npm-worm/Shai-Hulud surface). Update `verified` after testing a new release.",
+  "$comment": "Kit toolchain manifest — DATA only (versions, floors, policy); check/install logic lives in cli/src/engine-native/toolchain.ts with per-surface sync callbacks in cli/src/engine-native/. kind: required (preflight hard dep) | check (doctor visibility only) | managed (kit installs/upgrades it) | pin (no binary probe — a version pin for a tool the kit invokes via npx). policy (managed only): track (upgrade toward latest, gated by `verified`) | present (install when missing, never upgrade). `verified` = last kit-tested version — anything above it prompts before install (--yes auto-accepts; non-TTY declines and falls back to the pinned `verified` when pinnable). Supply-chain stance: every kit-driven install is pinned to `verified` or gated by it — never floating @latest (npm-worm/Shai-Hulud surface). Update `verified` after testing a new release.",
   "tools": {
-    "jq":     { "kind": "required", "note": "settings merges + manifest reads" },
+    "jq":     { "kind": "required", "note": "deployed Claude hooks/statusline assets" },
     "curl":   { "kind": "required", "note": "installers + usage fetch" },
     "node":   { "kind": "check", "note": "hosts npm globals (agent-browser, LSP servers)" },
     "npm":    { "kind": "check", "note": "npm-global installer" },
@@ -11,7 +11,7 @@
     "bwrap":  { "kind": "check", "os": "linux", "note": "Codex Linux sandbox runtime" },
     "intelephense": { "kind": "check", "verified": "1.18.5", "note": "php-lsp server binary; `verified` pins claude::sync_lsp_servers' npm install" },
     "typescript-language-server": { "kind": "check", "verified": "5.3.0", "note": "typescript-lsp server binary; `verified` pins claude::sync_lsp_servers' npm install" },
-    "tsc":    { "kind": "check", "verified": "6.0.3", "note": "typescript-lsp dependency (npm package `typescript`); `verified` pins claude::sync_lsp_servers' npm install" },
+    "tsc":    { "kind": "check", "verified": "6.0.3", "note": "typescript-lsp dependency (npm package `typescript`); `verified` pins claude::sync_lsp_servers' npm install. Deliberately on the 6.x line: typescript-language-server embeds TypeScript's programmatic API, which TS7 (native) doesn't yet expose — the repo's own devDependency runs TS7 for tsc --noEmit" },
     "rtk":    { "kind": "managed", "policy": "track", "floor": "0.43.0", "verified": "0.43.0", "pinnable": true,
                 "note": "PreToolUse hook — supply-chain review before unverified upgrades; installer honors RTK_VERSION=vX.Y.Z pin" },
     "bun":    { "kind": "managed", "policy": "present", "verified": "1.3.14", "pinnable": true,

package/cli/docs/install.md

@@ -21,12 +21,12 @@ docks-kit sync
 bunx docks-kit status
 ```
 
-The npm package bundles the engine (`lib/*.sh`) and the SoT — releases are
-versioned config snapshots. Kit-home resolution: `DOCKS_KIT_HOME` env →
-nearest ancestor directory containing `SoT/` (a checkout wins over the
-bundled copy) → the package's own bundled SoT.
+The npm package bundles the CLI and the SoT — releases are versioned config
+snapshots. Kit-home resolution: `DOCKS_KIT_HOME` env → nearest ancestor
+directory containing `SoT/` + `package.json` (a checkout wins over the bundled
+copy) → the package's own bundled SoT.
 
-## 3. curl installer
+## 3. curl installer (Unix-only)
 
 ```
 curl -fsSL https://raw.githubusercontent.com/DocksDocks/public/main/install.sh -o /tmp/docks-kit-install.sh
@@ -36,21 +36,48 @@ 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`.
+**Linux/macOS only** — on Windows use the compiled `.exe` or `bun add -g`
+(both CI-verified; see below).
 
-## Zero-dependency escape hatch
+## Windows entrypoints
 
-No Bun, no binary, constrained sandbox:
+Two supported paths (CI-verified on windows-2025, native PowerShell):
+
+- **Compiled binary** — `docks-kit-windows-x64.exe` release asset. No Bun,
+  no Git Bash: the exe embeds the runtime and EngineNative runs in-process.
+  It still needs the SoT it deploys — run it from inside a kit checkout, or
+  point `DOCKS_KIT_HOME` at one.
+- **`bun add -g docks-kit`** — bun creates a working shim for the
+  `#!/usr/bin/env bun` bin; outside a checkout the package's own bundled
+  SoT is used.
+
+`install.sh` is not a Windows path.
+
+## Keeping the kit up to date
 
 ```
-bash lib/engine.sh sync [targets] [flags]
-bash lib/engine.sh model claude opus
-bash lib/engine.sh toolchain check
+docks-kit update            # autodetect + update + chained flag-less sync
+docks-kit update --no-sync  # update only
 ```
 
-Requires only bash + jq (+ curl for installers).
+Autodetection: a kit home with `.git` is a checkout (requires a clean
+worktree and an upstream; `git pull --ff-only`, re-runs
+`bun install --frozen-lockfile` when the lockfile changed); a kit home
+under `node_modules` is a global package (`bun add -g` /
+`npm install -g docks-kit@latest`). A compiled binary inside a checkout
+updates the checkout and tells you to rebuild/download the binary.
+Every `docks-kit sync` also does a best-effort behind-upstream check and
+nudges when the checkout is stale (silent offline / detached / no git).
+
+## No-Bun recovery
+
+No Bun or constrained sandbox: download the platform release binary from GitHub
+Releases and run it from inside a kit checkout, or set `DOCKS_KIT_HOME` to the
+checkout containing `SoT/`.
 
 ## Prerequisites
 
-- bash, jq, curl (hard requirements — preflight checks them)
+- jq and curl (sync preflight checks them for the deployed assets and installers)
+- Bun for source/global installs; release binaries embed the runtime
 - Node/npm for npm-global tools (agent-browser, LSP servers)
 - See `docks-kit toolchain check` for the full picture on this machine

package/cli/docs/overview.md

@@ -14,9 +14,8 @@ AI-assisted dev environment on every machine.
 | `SoT/.agents/` | Universal agent skills manifest (agentskills.io standard) |
 | `SoT/models.json` | Kit-verified model catalog (see `docks-kit docs models`) |
 | `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
-| `lib/*.sh` | The bash engine — all mutation logic; battle-tested, idempotent |
-| `lib/engine.sh` | Engine entry: `sync`, `model`, `toolchain` — the zero-dependency escape hatch |
-| `cli/` | This CLI (Effect-TS on Bun) — typed front-end over the engine |
+| `cli/src/engine-native/` | EngineNative mutation logic for sync/model/toolchain |
+| `cli/` | This CLI (Effect-TS on Bun) plus bundled docs |
 | `docks-kit` | Launcher: compiled binary → bun-from-source, with Bun auto-install |
 
 ## Design rules
@@ -28,7 +27,7 @@ AI-assisted dev environment on every machine.
 - **Deploy-time modifiers** mutate deployed config only — the SoT never
   changes, and a later flag-less sync reverts them (`docks-kit docs modifiers`).
 - **Engine/CLI split**: the CLI adds UX (typed flags, pickers, docs, JSON);
-  the engine owns mutation. `bash lib/engine.sh <same args>` always works.
+  EngineNative owns mutation. No-Bun recovery is a platform release binary.
 
 ## Where to go next
 

package/cli/docs/platforms.md

@@ -2,30 +2,43 @@
 
 | Platform | CLI (docks-kit) | Sync engine | Notes |
 |----------|-----------------|-------------|-------|
-| Linux | native | native | Primary target |
-| macOS | native (x64 + arm64) | native | bash 3.2-compatible engine |
-| Windows | native (binary/Bun) | **experimental via Git Bash**; full hooks under WSL | See below |
+| Linux | native | EngineNative (TS) | Primary target |
+| macOS | native (x64 + arm64) | EngineNative (TS) | Release binary or Bun source path |
+| Windows | native (`.exe` / `bun add -g`, CI-verified) | EngineNative (TS) — no Git Bash | Real-machine verify pending |
 
-## Windows detail
-
-The managed tools all run natively on Windows: Claude Code (requires Git
-Bash for its Bash tool — so Git Bash is present on any Windows machine
-running Claude Code), Codex CLI (native PowerShell + Windows sandbox),
-RTK (native binaries via GitHub releases/winget — but its PreToolUse hook
-mechanism is Unix-only; Windows falls back to RTK's `--claude-md` mode).
+EngineNative is the only supported engine on all platforms. `DOCKS_KIT_ENGINE=bash`
+now exits with the removed-engine message and points at the `bash-engine-final`
+tag for historical recovery.
 
-The kit's engine is bash+jq, so on Windows it runs under Git Bash. Status:
-**experimental and not yet verified on a real Windows machine** — expect
-rough edges around:
-
-- shell-rc env exports (needs `setx` translation)
-- the notification hook (ffplay)
-- bubblewrap (Linux-only; skipped)
+## Windows detail
 
-For full fidelity (RTK hooks included), run the kit inside WSL.
+Supported entrypoints (both verified in CI on windows-2025 under native
+PowerShell — see `.github/workflows/windows-entrypoints.yml`):
 
-## Roadmap
+- **`docks-kit-windows-x64.exe`** (release asset) — the no-toolchain path.
+  No Bun, no Git Bash; the exe embeds the runtime and EngineNative runs
+  in-process. It still needs the SoT it deploys: run from a kit checkout or
+  set `DOCKS_KIT_HOME`.
+- **`bun add -g docks-kit`** — bun creates a working Windows shim for the
+  `#!/usr/bin/env bun` bin; outside a checkout kit-home resolves to the
+  package's own bundled SoT.
+- `install.sh` is **Unix-only** and not a Windows path.
 
-A native TypeScript engine (module-by-module port inside the CLI, swappable
-behind the same seam) would remove the Git Bash requirement entirely. Tracked
-as a follow-up plan — not part of the current CLI.
+The managed tools all run natively on Windows: Claude Code (requires Git
+Bash for its own Bash tool — that requirement is Claude Code's, not this
+kit's), Codex CLI (native PowerShell + Windows sandbox), RTK (native
+binaries; since rtk 0.37.2 the PreToolUse hook is a native binary command —
+`rtk hook claude`, no shell or jq. Only the kit's *auto-installer* is
+Unix-only: install rtk natively, then sync).
+
+CI coverage (all on the pinned windows-2025 label): EngineNative PowerShell
+smoke with `HOME` unset — `%USERPROFILE%` path resolution, `.cmd` tool
+spawning (npm), toolchain gate branches (`.github/workflows/parity.yml`,
+`native-windows` job); the two entrypoints above (`windows-entrypoints.yml`).
+Deployed hook/statusline assets stay shell scripts by design — Claude Code on
+Windows executes them through its own Git Bash.
+
+**Status: supported, pending one manual gate** — a real-machine interactive
+verify (Claude Code loads the synced `%USERPROFILE%\.claude`, the rtk hook
+fires, hook/statusline commands run or are knowingly skipped) tracked as
+step 9 of the `windows-support` plan.

package/cli/src/commands/sync.ts

@@ -1,13 +1,38 @@
 import { Args, Command, Options } from "@effect/cli"
 import { Effect, Option } from "effect"
+import { spawnSync } from "node:child_process"
+import { existsSync } from "node:fs"
+import { join } from "node:path"
 import { bail, engine } from "../engine"
+import { kitHome } from "../kitHome"
 import { modelCatalog, type Tool } from "../manifests"
 
+/** Best-effort update autodetection: nudge (never block, never fail) when
+ * the kit checkout is behind its upstream. Silent on detached HEADs, no
+ * upstream, no network, no git. */
+const updateNudge = (): void => {
+  try {
+    const home = kitHome()
+    if (!existsSync(join(home, ".git"))) return
+    if (spawnSync("git", ["-C", home, "fetch", "--quiet"], { stdio: "ignore", timeout: 4000 }).status !== 0) return
+    const res = spawnSync("git", ["-C", home, "rev-list", "--count", "HEAD..@{u}"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    })
+    const behind = (res.stdout ?? "").trim()
+    if (res.status === 0 && behind !== "" && behind !== "0") {
+      process.stderr.write(`\x1b[1;33m[warn]\x1b[0m kit checkout is ${behind} commit(s) behind its upstream — run: docks-kit update\n`)
+    }
+  } catch {
+    // nudge only — a sync must never fail because the update check did
+  }
+}
+
 const VALID_TARGETS = ["claude", "codex", "agents"]
 
-// Renamed sync.sh-era flags: @effect/cli routes unknown flags into the excess
-// positional args, so the rename hints (lib/common.sh's exit-2 arms) are
-// mirrored here to keep the parser contract identical across both front-ends.
+// Renamed pre-CLI flags: @effect/cli routes unknown flags into the excess
+// positional args, so the rename hints are mirrored here before EngineNative
+// sees the normalized argv.
 const LEGACY_HINTS: Record<string, string> = {
   "--force": "--force was renamed to --reconcile",
   "--remove-plugins":
@@ -125,10 +150,13 @@ export const syncCommand = Command.make(
           .forEach((p) => args.push(`--claude-plugin=${p}`))
       }
 
+      // Not on --dry-run: the nudge's git fetch writes FETCH_HEAD/remote
+      // refs, and a preview command must not mutate the checkout.
+      if (!config.dryRun) yield* Effect.sync(updateNudge)
       yield* engine(args)
     })
 ).pipe(
   Command.withDescription(
-    "Deploy the SoT to this machine (engine: lib/engine.sh — same flags, zero-dependency escape hatch). Deploy-time modifiers touch deployed config only; a later flag-less sync reverts them to SoT."
+    "Deploy the SoT to this machine with EngineNative. Deploy-time modifiers touch deployed config only; a later flag-less sync reverts them to SoT."
   )
 )

package/cli/src/commands/update.ts

@@ -0,0 +1,116 @@
+import { Command, Options } from "@effect/cli"
+import { Console, Effect } from "effect"
+import { spawnSync } from "node:child_process"
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+import { bail, compiled } from "../engine"
+import { kitHome } from "../kitHome"
+
+const noSync = Options.boolean("no-sync").pipe(
+  Options.withDescription("Update the kit only; skip the chained flag-less sync")
+)
+
+const git = (home: string, args: Array<string>): { ok: boolean; out: string } => {
+  const res = spawnSync("git", ["-C", home, ...args], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  })
+  return { ok: res.error === undefined && res.status === 0, out: `${res.stdout ?? ""}${res.stderr ?? ""}`.trim() }
+}
+
+/** Spawn the freshly-updated code — the running process still has the old
+ * version loaded, so the chained sync must be a new process. */
+const chainSync = (argv0: string, args: Array<string>): Effect.Effect<void> =>
+  Effect.sync(() => {
+    const res = spawnSync(argv0, args, { stdio: "inherit" })
+    if (res.error !== undefined || res.status !== 0) process.exit(res.status ?? 1)
+  })
+
+const updateCheckout = (home: string, skipSync: boolean) =>
+  Effect.gen(function* () {
+    if (spawnSync("git", ["--version"], { stdio: "ignore" }).status !== 0) {
+      return yield* bail("git not found - cannot update the kit checkout")
+    }
+    const dirty = git(home, ["status", "--porcelain"])
+    if (!dirty.ok) return yield* bail(`git status failed in ${home}: ${dirty.out}`)
+    if (dirty.out !== "") {
+      return yield* bail(`kit checkout ${home} has local changes - commit or stash them, then re-run docks-kit update`)
+    }
+    const upstream = git(home, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"])
+    if (!upstream.ok) {
+      return yield* bail("current branch has no upstream - set one (git branch --set-upstream-to) or update manually")
+    }
+    const before = git(home, ["rev-parse", "HEAD"]).out
+    const pull = git(home, ["pull", "--ff-only"])
+    if (!pull.ok) return yield* bail(`git pull --ff-only failed (diverged history?):\n${pull.out}`)
+    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}).`)
+    }
+
+    const count = git(home, ["rev-list", "--count", `${before}..${after}`]).out
+    yield* Console.log(`Updated ${before.slice(0, 7)}..${after.slice(0, 7)} (${count} commit(s) from ${upstream.out}).`)
+
+    const touched = git(home, ["diff", "--name-only", before, after]).out.split("\n")
+    if (touched.includes("bun.lock") || touched.includes("package.json")) {
+      const res = spawnSync("bun", ["install", "--frozen-lockfile"], { cwd: home, stdio: "inherit" })
+      if (res.error !== undefined || res.status !== 0) {
+        return yield* bail("dependencies changed but 'bun install --frozen-lockfile' failed - fix that, then run docks-kit sync", 1)
+      }
+    }
+
+    if (compiled) {
+      return yield* Console.log(
+        "This compiled binary still runs the previous version - rebuild (bash cli/build-binaries.sh) or download the latest release binary, then run: docks-kit sync"
+      )
+    }
+    if (skipSync) return yield* Console.log("Kit updated. Run: docks-kit sync")
+    yield* Console.log("Kit updated - running sync with the new version...")
+    return yield* chainSync(process.execPath, [join(home, "cli/src/main.ts"), "sync"])
+  })
+
+const updatePackage = (home: string, skipSync: boolean) =>
+  Effect.gen(function* () {
+    // Bun's global dir is configurable (BUN_INSTALL_GLOBAL_DIR / BUN_INSTALL),
+    // so the ~/.bun path shape alone under-detects Bun installs.
+    const underEnvDir = (v: string): boolean => {
+      const dir = process.env[v]
+      return dir !== undefined && dir !== "" && home.startsWith(dir)
+    }
+    const viaBun =
+      home.includes("/.bun/") ||
+      home.includes("\\.bun\\") ||
+      underEnvDir("BUN_INSTALL_GLOBAL_DIR") ||
+      underEnvDir("BUN_INSTALL")
+    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)
+    }
+    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
+    // place) — a bare `docks-kit` PATH lookup could hit a different shim.
+    return yield* chainSync(process.execPath, [join(home, "cli/src/main.ts"), "sync"])
+  })
+
+export const updateCommand = Command.make("update", { noSync }, (config) =>
+  Effect.gen(function* () {
+    const home = kitHome()
+    if (existsSync(join(home, ".git"))) {
+      return yield* updateCheckout(home, config.noSync)
+    }
+    if (home.includes("node_modules")) {
+      return yield* updatePackage(home, config.noSync)
+    }
+    return yield* bail(
+      `kit home ${home} is neither a git checkout nor a global package install - update it the way it was installed (e.g. download the latest release binary)`
+    )
+  })
+).pipe(
+  Command.withDescription(
+    "Self-update the kit: autodetects the install (git checkout -> ff-only pull; bun/npm global -> @latest) and chains a flag-less sync with the new version (--no-sync to skip)."
+  )
+)