docks-kit 0.2.0 → 0.4.0

package/AGENTS.md

@@ -19,10 +19,11 @@ Tool-specific instructions live alongside this file:
 | `cli/` | Effect-TS CLI + bundled docs topics |
 | `SoT/models.json` | Kit-verified 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 binaries + npm publish |
 | `README.md` | Front door |
-| `package.json` / `bun.lock` | npm package: `bin` = `cli/src/main.ts`; bundles `cli/` + `SoT/` |
+| `package.json` / `bun.lock` | npm package: `bin` = `cli/src/main.ts`; bundles `cli/` with the generated in-memory SoT payload |
 | `SoT/.agents/skills.txt` | Universal-skill manifest. One [agentskills.io](https://agentskills.io) slug per line; EngineNative runs `npx skills add` for each missing entry into `~/.agents/skills/`, where Codex et al. discover it natively and Claude Code follows a symlink at `~/.claude/skills/` |
 | `notification.mp3` | Audio asset for Notification hooks (consumed by Claude Code today; tool-agnostic file) |
 | `docs/plans/` | Multi-commit work-item plans (`active/` with status in frontmatter, plus `finished/` archive). Convention: `docs/plans/AGENTS.md` |
@@ -36,6 +37,7 @@ Codex SoT notes:
 - `SoT/.codex/plugins/marketplace.json` deploys to Codex's personal marketplace path at `~/.agents/plugins/marketplace.json`; when the `codex` CLI is available, sync reruns `codex plugin add <plugin@marketplace>` for enabled SoT plugins so stale cached installs are refreshed.
 - The `codex` CLI binary is upstream-owned, not kit-owned. The official standalone installer keeps package metadata under `$CODEX_HOME/packages/standalone` and places the `codex` symlink in `~/.local/bin` by default; sync only warns with a download-then-run installer command when the CLI is missing. Existing installs can self-update with `codex update`; npm and Homebrew remain upstream alternatives.
 - `SoT/.codex/AGENTS.md` deliberately does not import `@RTK.md`: RTK's published Codex integration is prompt-file based rather than hook based, so importing it leaks implementation detail into agent-visible context. Use Codex hooks for RTK only after the kit installs a hook-backed Codex integration.
+- Claude runtime settings are an authoring template with sentinels. `claudeRuntime.ts` materializes absolute Bun/script paths only after the shared `bun.ts` bootstrap is ready; `claudeSync.ts` writes all runtime assets before atomically committing settings, then prunes the legacy shell scripts and Stop hook. Native `rate_limits` is the sole quota source, so jq/curl/OAuth caches are not runtime dependencies. A missing Bun defers only this cutover and preserves legacy pointers/files.
 
 For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT directory.
 
@@ -46,7 +48,7 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT d
 - **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 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`.
+- **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`.
 - **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.
@@ -75,7 +77,7 @@ This project ships **kit-mechanic skills** under `.claude/skills/` — narrowly-
 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 `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`).
+**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. It calls the shared `bun.ts` `bunBootstrap` when needed, then symlinks **both** `bun` and the CLI into `~/.local/bin`. Linking Bun too is mandatory — the CLI's `#!/usr/bin/env bun` shebang needs it 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

@@ -25,11 +25,13 @@ see `./docks-kit docs install`.
 
 **No-Bun recovery path**:
 
-Download the platform release binary from GitHub Releases and run it from a
-kit checkout, or set `DOCKS_KIT_HOME` to the checkout containing `SoT/`.
+Download the platform release binary from GitHub Releases and run it directly.
+The executable carries the generated sync payload; no checkout or adjacent
+`SoT/` directory is required.
 
-Prerequisites for source/global installs: Bun plus `jq` and `curl` for sync
-preflight; Node/npm for npm-global tools.
+Prerequisites for source/global installs: Bun; Node/npm for npm-global tools.
+`jq` is optional doctor/test tooling. `curl` is used only at requested POSIX
+RTK/Bun download boundaries, not as a global sync prerequisite.
 
 ## CLI
 
@@ -82,17 +84,23 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
   when possible). `docks-kit toolchain check` shows the full table.
 - **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`
+  programs for statusline, SessionStart, and Notification. Quota display uses
+  Claude's native `rate_limits`; there is no OAuth fetch, shared usage cache,
+  or Stop hook. If Bun cannot be resolved or bootstrapped, sync preserves a
+  working legacy hook/statusline setup and reports that migration is deferred.
 
 ## Repository map
 
 | Path | Purpose |
 |------|---------|
-| `SoT/.claude/` | Claude Code SoT (settings, hooks, status line, CLAUDE.md) |
+| `SoT/.claude/` | Claude Code SoT (settings template, Bun runtime programs, CLAUDE.md) |
 | `SoT/.codex/` | Codex SoT (config.toml, rules, AGENTS.md, marketplace) |
 | `SoT/.agents/` | Universal-skill manifest |
 | `SoT/models.json` | Kit-verified model catalog |
 | `SoT/toolchain.json` | Verified-version floors |
 | `cli/src/engine-native/` | EngineNative sync/model/toolchain implementation |
+| `cli/src/generated/sotPayload.ts` | Generated in-memory payload used by standalone and npm installs |
 | `cli/` | docks-kit CLI (Effect-TS on Bun) + bundled docs topics |
 | `docks-kit` | Launcher (binary → bun-from-source) |
 | `install.sh` | Global installer (Bun bootstrap + `bun add -g`) |
@@ -113,8 +121,8 @@ Details: `docks-kit docs platforms`.
 
 Tagging `cli-v*` builds five standalone binaries (+ SHA256SUMS) and attaches
 them to the GitHub release; npm publish runs when the `NPM_TOKEN` secret is
-configured. Package bundles the CLI + SoT, so npm releases are versioned config
-snapshots.
+configured. Package bundles the CLI + generated payload, so npm releases are
+versioned config snapshots without shipping the authoring `SoT/` tree.
 
 ## Deeper docs
 

package/cli/docs/install.md

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

package/cli/docs/overview.md

@@ -9,11 +9,12 @@ AI-assisted dev environment on every machine.
 
 | Piece | Role |
 |-------|------|
-| `SoT/.claude/` | Claude Code config (settings, hooks, status line, CLAUDE.md) |
+| `SoT/.claude/` | Claude Code config (settings template, Bun runtime programs, CLAUDE.md) |
 | `SoT/.codex/` | Codex config (config.toml, rules, AGENTS.md, marketplace) |
 | `SoT/.agents/` | Universal agent skills manifest (agentskills.io standard) |
 | `SoT/models.json` | Kit-verified model catalog (see `docks-kit docs models`) |
 | `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
+| `cli/src/generated/sotPayload.ts` | Deterministic generated payload embedded in standalone/npm execution |
 | `cli/src/engine-native/` | EngineNative mutation logic for sync/model/toolchain |
 | `cli/` | This CLI (Effect-TS on Bun) plus bundled docs |
 | `docks-kit` | Launcher: compiled binary → bun-from-source, with Bun auto-install |
@@ -31,6 +32,11 @@ AI-assisted dev environment on every machine.
   changes, and a later flag-less sync reverts them (`docks-kit docs modifiers`).
 - **Engine/CLI split**: the CLI adds UX (typed flags, pickers, docs, JSON);
   EngineNative owns mutation. No-Bun recovery is a platform release binary.
+- **Authoring/runtime split**: changes begin in `SoT/`; build/prepack freshness
+  checks keep the generated in-memory payload byte-identical for every runtime.
+- **Native Claude runtime**: three dependency-free Bun `.mjs` programs own the
+  statusline, SessionStart, and Notification. Quotas come only from native
+  `rate_limits`; missing Bun defers cutover without deleting legacy fallbacks.
 
 ## Where to go next
 

package/cli/docs/platforms.md

@@ -16,12 +16,10 @@ Supported entrypoints (both verified in CI on windows-2025 under native
 PowerShell — see `.github/workflows/windows-entrypoints.yml`):
 
 - **`docks-kit-windows-x64.exe`** (release asset) — the no-toolchain path.
-  No Bun, no Git Bash; the exe embeds the runtime and EngineNative runs
-  in-process. It still needs the SoT it deploys: run from a kit checkout or
-  set `DOCKS_KIT_HOME`.
+  No Bun, no Git Bash; the exe embeds the runtime and generated payload, and
+  EngineNative runs in-process from any working directory.
 - **`bun add -g docks-kit`** — bun creates a working Windows shim for the
-  `#!/usr/bin/env bun` bin; outside a checkout kit-home resolves to the
-  package's own bundled SoT.
+  `#!/usr/bin/env bun` bin; the package carries the same generated payload.
 - `install.sh` is **Unix-only** and not a Windows path.
 
 The managed tools all run natively on Windows: Claude Code (requires Git
@@ -35,8 +33,11 @@ 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.
+Deployed SessionStart/Notification hooks directly exec an absolute real
+`bun.exe`. Claude still shell-evaluates the statusline, so its stored command is
+an encoded PowerShell missing-file guard that behaves identically when the outer
+shell is native PowerShell or Git Bash. CI executes both outer-shell paths and
+pins output bytes/channels plus latency ceilings.
 
 **Status: supported** — real-machine verified 2026-07-09 (Claude Code loads
 the synced `%USERPROFILE%\.claude`; full sync, self-update, plugin passes,

package/cli/docs/sync-layers.md

@@ -5,23 +5,31 @@ no target means all three.
 
 ## claude (→ ~/.claude, ~/.claude.json, shell rc)
 
-Order matters — toolchain first, config after:
+Order matters — runtime readiness and settings form one transaction:
 
 1. **RTK** (toolchain-gated): install/upgrade, then `rtk init --global` on
    first install. Runs FIRST because rtk init rewrites settings.json — the
    later settings merge normalizes whatever it wrote.
-2. Scripts (statusline, fetch-usage, notification.mp3), hooks, CLAUDE.md.
-3. **settings.json merge** — additive: SoT keys win, permissions arrays are
+2. Resolve/bootstrap pinned Bun, materialize the sentinel settings template,
+   and prepare the merged settings bytes without mutation. If Bun remains
+   unavailable, omit only the new runtime pointers and preserve legacy ones.
+3. When ready, write `bin/statusline.mjs`, `bin/session-start.mjs`,
+   `bin/notify.mjs`, and `notification.mp3`; deploy CLAUDE.md; atomically commit
+   settings; then prune the old shell assets and Stop hook.
+4. **settings.json merge semantics** — additive: SoT keys win, permissions arrays are
    unioned, user-only keys survive. `--reconcile` replaces permissions arrays
    wholesale instead.
-4. **Deploy-time modifiers** (`--claude-compact-window`, `--claude-permissive`,
+5. **Deploy-time modifiers** (`--claude-compact-window`, `--claude-permissive`,
    `--claude-model`) — deployed file only.
-5. ~/.claude.json (showTurnDuration, user-scoped MCP servers), connector env
+6. ~/.claude.json (showTurnDuration, user-scoped MCP servers), connector env
    export, removed-artifact pruning.
-6. **Plugins** — seven idempotent passes via the `claude plugin` CLI
+7. **Plugins** — seven idempotent passes via the `claude plugin` CLI
    (marketplaces → install → update → [--prune: uninstall/remove] → re-assert
    SoT enabled-state). Optional opt-ins via `--claude-plugin=<name>`.
-7. LSP server binaries (npm globals).
+8. LSP server binaries (npm globals).
+
+The statusline reads Claude's native `rate_limits`. There is no OAuth request,
+usage cache, jq/curl runtime dependency, or Stop fetch hook.
 
 ## codex (→ ~/.codex, ~/.agents/plugins)
 

package/cli/docs/toolchain.md

@@ -4,7 +4,7 @@
 
 | Field | Meaning |
 |-------|---------|
-| `kind` | `required` (preflight hard dep) / `check` (doctor visibility) / `managed` (kit installs + upgrades) / `pin` (no binary — a version pin for npx-invoked tools, e.g. `skills-cli`) |
+| `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 |
@@ -31,10 +31,16 @@ now kit-approved" act.
   settings rewrite is normalized by the merge that follows. Pinned installs
   fetch the installer script from the version tag, not mutable master.
 - **bun** — policy `present`: bootstrap only (pinned to `verified` via the
-  installer's `bun-vX.Y.Z` release-tag argument), never auto-upgraded.
+  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. Windows resolves only a real absolute `bun.exe` for hooks.
 - **effect-solutions**, **agent-browser** — policy `track`: self-upgrade
   toward npm latest, gated by their `verified` pins.
 
+jq and curl are `check` rows, not global prerequisites. jq is not consumed by
+normal sync. curl is checked only at a requested POSIX RTK/Bun installer
+download boundary; Windows Bun bootstrap uses PowerShell's native download.
+
 ## Supply-chain stance
 
 Every kit-driven install is pinned to a `verified` version or gated by one —

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

@@ -27,15 +27,19 @@ explicit removed-engine diagnostic and exits 2 with the recovery tag message.
 - **Prove-red stays red.** The golden suites compare live native output to a
   mismatched golden under `--prove-red` and must exit non-zero after printing
   `prove-red OK`.
-- **Step ordering is load-bearing.** The Claude pipeline runs RTK before the
-  settings merge, modifiers after it, removals before plugins, and LSP checks
-  after plugin state.
+- **Step ordering is load-bearing.** The Claude pipeline runs RTK, resolves Bun,
+  prepares materialized settings, writes runtime assets, commits settings, then
+  performs readiness-gated legacy cleanup. Modifiers run after the base commit,
+  removals before plugins, and LSP checks after plugin state.
 - **External CLIs stay external.** `claude`, `codex`, `npx`, `npm`, `rtk`,
   `bun`, `curl`, and platform package managers are spawned with argv arrays,
   not shell command strings except where the external installer contract is a
   shell script.
 - **Backups precede mutation.** Deployed settings/config files write `.bak`
   backups before replacement.
+- **Runtime payload is in memory.** `SoT/` remains the reviewed authoring tree;
+  generated payload freshness gates build/package production, and EngineNative
+  never needs an adjacent runtime `SoT/` directory.
 
 ## Output Policy (log UX contract)
 
@@ -69,10 +73,12 @@ each such skip is an intentional behavior change named in its golden diff.
 
 ### Missing dependencies
 
-Exactly one deduplicated warn per missing tool per run, uniform shape:
+Exactly one deduplicated warn per requested missing tool per run, uniform shape:
 `[warn] <tool> not installed — <platform-correct install command>`, sourced
-from the dependency registry (`deps.ts`). Required tools keep their current
-exit behavior — the error carries the same install hint.
+from the dependency registry (`deps.ts`). jq and curl are optional report rows:
+jq has no runtime consumer, while curl warns only at a requested POSIX RTK/Bun
+download boundary. A missing Bun defers Claude runtime migration without
+deleting working legacy hooks or statusline files.
 
 ### Summary and next steps
 
@@ -111,14 +117,17 @@ active logger binding.
 
 | Module | Owns |
 |---|---|
-| `parseArgs.ts` | engine usage, target selection, flag parsing, legacy rename hints, preflight, model flag validation |
+| `parseArgs.ts` | engine usage, target selection, flag parsing, legacy rename hints, model flag validation |
 | `index.ts` | sync orchestration, target dispatch, run summary and next-step blocks |
-| `claudeSync.ts` | Claude pipeline: RTK, assets, settings merge, deploy-time modifiers, `~/.claude.json`, connector env, removed artifacts, plugins, optional plugins, LSP binaries |
+| `../payload.ts` | generated text/byte payload reads and presentation-only source labels |
+| `claudeSync.ts` | Claude pipeline: RTK, prepared settings transaction, runtime assets, deploy-time modifiers, `~/.claude.json`, readiness-gated removed artifacts, plugins, optional plugins, LSP binaries |
+| `bun.ts` | per-run memoized Bun resolution/bootstrap shared by Claude runtime, effect-solutions, and direct toolchain ensure |
+| `claudeRuntime.ts` | sentinel validation, absolute runtime paths, no-cutover settings projection, and POSIX/encoded-PowerShell statusline commands |
 | `settings.ts` | pure Claude settings merge/reconcile semantics and permission-array union |
 | `claudeModel.ts` | deployed Claude model modifier and direct `model claude` write path |
 | `codexSync.ts` | Codex pipeline: bubblewrap check, config merge, rules, AGENTS.md, personal marketplace, plugin refresh |
 | `codexToml.ts` | line-based top-level TOML replacement and deployed Codex model modifier |
-| `skillsSync.ts` | universal skill install/prune, Claude symlink healing, agent-browser/effect-solutions/Bun helpers, managed-skill snapshot |
+| `skillsSync.ts` | universal skill install/prune, Claude symlink healing, agent-browser/effect-solutions callbacks, managed-skill snapshot |
 | `toolchain.ts` | tool presence/version probes, verified-version gate, managed install/upgrade orchestration, report table |
 | `modes.ts` | direct `model` and `toolchain` modes |
 | `models.ts` | model catalog listing and validation |
@@ -138,8 +147,9 @@ active logger binding.
 - Symlink creation falls back to copy where the platform or permissions require
   it.
 - Bubblewrap and shell-rc work are Linux/macOS only.
-- Claude hook/statusline assets remain shell scripts because Claude Code owns
-  that runtime.
+- Claude command hooks directly exec the resolved absolute `bun.exe`; the
+  statusline stores an encoded PowerShell missing-file guard because Claude
+  shell-evaluates `statusLine.command` through PowerShell or Git Bash.
 
 ## Tests
 
@@ -149,8 +159,9 @@ active logger binding.
 - `bun run golden:mutation` compares live native mutation snapshots, argv logs,
   output, and TOML invariants to `cli/test/goldens/mutation.json`.
 - `.github/workflows/parity.yml` is now the golden-regression workflow: Linux
-  runs unit + golden + prove-red; the `native-windows` job runs PowerShell
-  smoke checks for native Windows behavior.
+  runs unit + golden + prove-red plus the exact materialized POSIX runtime
+  commands; the `native-windows` job executes the same stored statusline command
+  through PowerShell and Git Bash plus direct Bun hooks.
 - `.github/workflows/windows-entrypoints.yml` verifies the release binary and
   `bun add -g` entrypoints on Windows.
 
@@ -158,5 +169,5 @@ active logger binding.
 
 - Reintroducing the removed shell engine as a supported fallback. Fix forward in
   EngineNative; recover historical source only from `bash-engine-final`.
-- Porting Claude Code's hook/statusline shell assets.
+- Adding a compiled runner or CLI hook subcommand for Claude's Bun runtime.
 - Adding new sync features while changing the engine contract.

package/cli/src/engine-native/bun.ts

@@ -0,0 +1,87 @@
+import { spawnSync } from "node:child_process"
+import { rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+
+import { p } from "./exec"
+import type { Ctx } from "./index"
+import { encodePowerShellCommand, powerShellLiteral } from "./powershell"
+import type { EngineServices } from "./services"
+import { field } from "./toolchain"
+
+export type BunRuntimeState =
+  | { readonly kind: "ready"; readonly executable: string }
+  | { readonly kind: "deferred"; readonly reason: "missing-curl" | "install-failed" }
+
+function remember(ctx: Ctx, state: BunRuntimeState): BunRuntimeState {
+  ctx.bunRuntime = state
+  return state
+}
+
+function predictedExecutable(ctx: Ctx, services: EngineServices): string {
+  const root = process.env["BUN_INSTALL"] !== undefined && process.env["BUN_INSTALL"] !== ""
+    ? process.env["BUN_INSTALL"]!
+    : p(ctx.home, ".bun")
+  return p(root, "bin", services.platform.isWindows() ? "bun.exe" : "bun")
+}
+
+function windowsDownloadScript(installer: string): string {
+  return `$ErrorActionPreference = 'Stop'; Invoke-WebRequest -Uri ${powerShellLiteral("https://bun.sh/install.ps1")} -OutFile ${powerShellLiteral(installer)}`
+}
+
+function installBun(ctx: Ctx, services: EngineServices, pin: string, installer: string): void {
+  if (services.platform.isWindows()) {
+    const encoded = encodePowerShellCommand(windowsDownloadScript(installer))
+    const download = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-EncodedCommand", encoded], { stdio: "ignore" })
+    if (download.error === undefined && download.status === 0) {
+      spawnSync(
+        "powershell.exe",
+        ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", installer, "-Version", pin, "-DownloadWithoutCurl"],
+        { stdio: "ignore" }
+      )
+    }
+    return
+  }
+
+  const download = spawnSync("curl", ["-fsSL", "https://bun.sh/install", "-o", installer], { stdio: "ignore" })
+  if (download.error === undefined && download.status === 0) {
+    spawnSync("bash", [installer, `bun-v${pin}`], { stdio: "ignore" })
+  }
+}
+
+export function bunBootstrap(ctx: Ctx, services: EngineServices): BunRuntimeState {
+  if (ctx.bunRuntime !== undefined) return ctx.bunRuntime
+
+  const existing = services.deps.path("bun")
+  if (existing !== "") return remember(ctx, { kind: "ready", executable: existing })
+
+  const pin = field(ctx, "bun", "verified")
+  if (pin === "") {
+    services.logger.warn("Bun bootstrap aborted — SoT/toolchain.json has no verified Bun pin")
+    return remember(ctx, { kind: "deferred", reason: "install-failed" })
+  }
+  if (!services.platform.isWindows() && services.deps.probe("curl").state === "missing") {
+    services.deps.warnMissing("curl", services.logger, "cannot bootstrap Bun; install Bun manually, then re-run sync")
+    return remember(ctx, { kind: "deferred", reason: "missing-curl" })
+  }
+  if (ctx.dryRun) {
+    const executable = predictedExecutable(ctx, services)
+    services.logger.echo(`[dry-run] install Bun ${pin} (kit-verified) -> ${executable}`)
+    return remember(ctx, { kind: "ready", executable })
+  }
+  services.logger.warn(`Bun not found — installing Bun ${pin} (kit-verified)...`)
+  const installer = p(tmpdir(), `bun-install-${process.pid}.${services.platform.isWindows() ? "ps1" : "sh"}`)
+  try {
+    installBun(ctx, services, pin, installer)
+  } finally {
+    rmSync(installer, { force: true })
+  }
+
+  const installed = services.deps.path("bun")
+  if (installed === "") {
+    services.logger.warn("Bun install failed. Install manually from https://bun.sh/docs/installation, then re-run sync.")
+    return remember(ctx, { kind: "deferred", reason: "install-failed" })
+  }
+  const version = services.deps.version("bun")
+  services.logger.change(`Bun installed (${version !== "" ? version : "version unknown"})`)
+  return remember(ctx, { kind: "ready", executable: installed })
+}

package/cli/src/engine-native/claudeRuntime.ts

@@ -0,0 +1,132 @@
+import { p } from "./exec"
+import { isObject, parseJson, type Json } from "./jq"
+import { encodePowerShellCommand, powerShellLiteral } from "./powershell"
+import type { Platform } from "./services"
+
+const BUN_SENTINEL = "__DOCKS_KIT_BUN__"
+const SESSION_START_SENTINEL = "__DOCKS_KIT_SESSION_START__"
+const NOTIFY_SENTINEL = "__DOCKS_KIT_NOTIFY__"
+const STATUSLINE_SENTINEL = "__DOCKS_KIT_STATUSLINE__"
+
+export interface ClaudeRuntimePaths {
+  readonly bun: string
+  readonly statusline: string
+  readonly sessionStart: string
+  readonly notify: string
+}
+
+export function claudeRuntimePaths(claudeDir: string, bun: string): ClaudeRuntimePaths {
+  return {
+    bun,
+    statusline: p(claudeDir, "bin", "statusline.mjs"),
+    sessionStart: p(claudeDir, "bin", "session-start.mjs"),
+    notify: p(claudeDir, "bin", "notify.mjs")
+  }
+}
+
+function cloneJson(value: Json): Json {
+  const cloned = parseJson(JSON.stringify(value))
+  if (cloned === undefined) throw new Error("Claude settings template cannot be serialized")
+  return cloned
+}
+
+function countString(value: Json, expected: string): number {
+  if (value === expected) return 1
+  if (Array.isArray(value)) return value.reduce<number>((total, item) => total + countString(item, expected), 0)
+  if (!isObject(value)) return 0
+  return Object.values(value).reduce<number>((total, item) => total + countString(item, expected), 0)
+}
+
+function hooksObject(template: Json): { [key: string]: Json } {
+  if (!isObject(template) || !isObject(template["hooks"])) throw new Error("Claude settings hooks object is missing")
+  return template["hooks"]
+}
+
+function commandHandler(template: Json, event: "SessionStart" | "Notification"): { [key: string]: Json } {
+  const entries = hooksObject(template)[event]
+  if (!Array.isArray(entries) || entries.length !== 1 || !isObject(entries[0])) {
+    throw new Error(`${event} sentinel location is invalid`)
+  }
+  const handlers = entries[0]["hooks"]
+  if (!Array.isArray(handlers) || handlers.length !== 1 || !isObject(handlers[0])) {
+    throw new Error(`${event} sentinel handler is invalid`)
+  }
+  return handlers[0]
+}
+
+function oneArg(handler: { [key: string]: Json }, sentinel: string, event: string): void {
+  const args = handler["args"]
+  if (!Array.isArray(args) || args.length !== 1 || args[0] !== sentinel) {
+    throw new Error(`${event} argument sentinel location is invalid`)
+  }
+}
+
+function validateTemplate(template: Json): void {
+  const sessionStart = commandHandler(template, "SessionStart")
+  const notification = commandHandler(template, "Notification")
+  if (sessionStart["command"] !== BUN_SENTINEL) throw new Error("SessionStart Bun sentinel location is invalid")
+  if (notification["command"] !== BUN_SENTINEL) throw new Error("Notification Bun sentinel location is invalid")
+  oneArg(sessionStart, SESSION_START_SENTINEL, "SessionStart")
+  oneArg(notification, NOTIFY_SENTINEL, "Notification")
+
+  const hooks = hooksObject(template)
+  if (hooks["Stop"] !== undefined) throw new Error("hooks.Stop must be absent from the Claude settings template")
+  if (!isObject(template) || !isObject(template["statusLine"]) || template["statusLine"]["command"] !== STATUSLINE_SENTINEL) {
+    throw new Error("Statusline sentinel location is invalid")
+  }
+  const counts: ReadonlyArray<[string, string, number]> = [
+    ["Bun", BUN_SENTINEL, 2],
+    ["SessionStart", SESSION_START_SENTINEL, 1],
+    ["notify", NOTIFY_SENTINEL, 1],
+    ["statusline", STATUSLINE_SENTINEL, 1]
+  ]
+  for (const [label, sentinel, expected] of counts) {
+    if (countString(template, sentinel) !== expected) throw new Error(`${label} sentinel residue/cardinality is invalid`)
+  }
+}
+
+function posixLiteral(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`
+}
+
+export function statusLineCommand(runtime: ClaudeRuntimePaths, platform: Platform): string {
+  if (!platform.isWindows()) {
+    const bun = posixLiteral(runtime.bun)
+    const script = posixLiteral(runtime.statusline)
+    return `test -x ${bun} && test -f ${script} && exec ${bun} ${script} || true`
+  }
+  const bun = powerShellLiteral(runtime.bun.replaceAll("\\", "/"))
+  const script = powerShellLiteral(runtime.statusline.replaceAll("\\", "/"))
+  const guard = `$ProgressPreference = 'SilentlyContinue'; if ((Test-Path -LiteralPath ${bun} -PathType Leaf) -and (Test-Path -LiteralPath ${script} -PathType Leaf)) { & ${bun} ${script} }`
+  return `powershell.exe -NoProfile -NonInteractive -EncodedCommand ${encodePowerShellCommand(guard)}`
+}
+
+export function materializeClaudeSettings(
+  template: Json,
+  runtime: ClaudeRuntimePaths | undefined,
+  platform: Platform
+): Json {
+  validateTemplate(template)
+  const result = cloneJson(template)
+  const hooks = hooksObject(result)
+  if (runtime === undefined) {
+    delete hooks["SessionStart"]
+    delete hooks["Notification"]
+    if (!isObject(result)) throw new Error("Claude settings template must be an object")
+    delete result["statusLine"]
+  } else {
+    const sessionStart = commandHandler(result, "SessionStart")
+    sessionStart["command"] = runtime.bun
+    sessionStart["args"] = [runtime.sessionStart]
+    const notification = commandHandler(result, "Notification")
+    notification["command"] = runtime.bun
+    notification["args"] = [runtime.notify]
+    if (!isObject(result) || !isObject(result["statusLine"])) throw new Error("Claude statusLine object is missing")
+    result["statusLine"]["command"] = statusLineCommand(runtime, platform)
+  }
+
+  for (const sentinel of [BUN_SENTINEL, SESSION_START_SENTINEL, NOTIFY_SENTINEL, STATUSLINE_SENTINEL]) {
+    if (countString(result, sentinel) !== 0) throw new Error(`Claude settings sentinel residue: ${sentinel}`)
+  }
+  return result
+}