docks-kit 0.3.0 → 0.5.0

package/AGENTS.md

@@ -19,6 +19,7 @@ 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 |
@@ -31,11 +32,13 @@ Tool-specific instructions live alongside this file:
 
 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.5"`, sets reasoning effort/summaries (`xhigh` + `detailed`), `model_verbosity = "medium"` (Codex ships gpt-5.5 at `low`; medium restores the API default), `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 Docks plugins as `docks@docks` + `session-relay@docks`.
+- `SoT/.codex/config.toml` pins Codex to `model = "gpt-5.6-sol"`, sets reasoning effort/summaries (`xhigh` + `detailed`), `model_verbosity = "medium"`, `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 Docks plugins as `docks@docks` + `session-relay@docks`.
 - `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 `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.
+- Claude's deployed SoT defaults are `model: fable` and `effortLevel: high`; `advisorModel` is deliberately absent/off. `--claude-advisor=on` is the per-machine opt-in and writes `advisorModel: fable` after the settings merge.
 
 For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT directory.
 
@@ -43,10 +46,10 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT d
 
 - **Idempotent operations.** Every EngineNative sync step must be safe to re-run. Settings merges, plugin installs, and marketplace adds are all idempotent — re-running with no SoT changes is a no-op.
 - **Removed bash engine.** The bash engine was removed after the `bash-engine-final` tag. `DOCKS_KIT_ENGINE=bash` must fail with the removed-engine message; engine bugs are fixed forward in EngineNative.
-- **Targeted syncs.** `./docks-kit sync` accepts positional targets: `claude`, `codex`, and `agents`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync codex` for Codex-only config edits); targets can be combined with `--dry-run`, `--skip-rtk`, `--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).
+- **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>` / `--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; 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 +78,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

@@ -29,8 +29,9 @@ 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
 
@@ -83,12 +84,17 @@ 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 |

package/cli/docs/flags.md

@@ -27,12 +27,17 @@ docks-kit sync claude agents        # two
 | Flag | Effect |
 |------|--------|
 | `--claude-model=<m>` | Deploy-time modifier: deployed model (aliases or full claude-* IDs; `default` unsets) |
+| `--claude-effort=<level>` | Deploy-time modifier: `effortLevel`; valid `low`, `medium`, `high`, `xhigh`, or `default` (Claude SoT: `high`) |
+| `--claude-advisor=<state>` | Deploy-time modifier: advisor `on`, `off`, or `default` (SoT off/unset) |
 | `--claude-compact-window=<n>` | Deploy-time modifier: autocompact window in tokens (`680000` or `680k`) |
 | `--claude-permissive` | Deploy-time modifier: empty permissions.ask/deny (sandboxes) |
 | `--claude-plugin=<name>` | Sticky opt-in plugin (known: supabase, n8n); comma-separate for several |
 | `--codex-model=<m>` | Deploy-time modifier: deployed Codex model |
+| `--codex-effort=<level>` | Deploy-time modifier: `model_reasoning_effort`; valid `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultra`, or `default` (Codex SoT: `xhigh`; model-dependent) |
 
-Bare `--claude-model` / `--codex-model` (no value) prints the model catalog.
+Bare model, effort, or advisor modifiers print the relevant valid-value catalog
+and exit 2. A modifier for a target not selected by the positional arguments is
+ignored with a warning; Claude modifiers never touch Codex config and vice versa.
 
 ## Renamed legacy flags (pre-CLI sync.sh)
 

package/cli/docs/install.md

@@ -26,6 +26,30 @@ are versioned config snapshots without publishing the authoring `SoT/` tree.
 Kit-home resolution remains available for checkout/package update behavior and
 display paths, but sync reads do not depend on it.
 
+### Bun 1.3.14 blocked-postinstall notice
+
+A supported global install may finish successfully with this exact notice:
+
+```
+Blocked 1 postinstall. Run `bun pm -g untrusted` for details.
+```
+
+For the pinned production dependency graph, the diagnostic names only:
+
+```
+./node_modules/@parcel/watcher @2.5.6
+ » [install]: node scripts/build-from-source.js
+```
+
+`@parcel/watcher` is a transitive of the Effect Bun runtime. Supported default
+installs already carry its platform prebuilt package, and that install script
+only attempts a source build when `npm_config_build_from_source=true` was
+explicitly requested. `esbuild` is not in the consumer production graph. The
+blocked notice therefore needs no trust action for the supported default
+install; `docks-kit --version`, model catalogs, toolchain checks, and real sync
+remain functional with the script blocked. CI pins the one-package/one-command
+identity above and will fail if the script-bearing set changes.
+
 ## 3. curl installer (Unix-only)
 
 ```
@@ -75,7 +99,9 @@ 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/models.md

@@ -18,8 +18,8 @@ the entry and date when a model ships or retires.
 ## The `best` alias and `default` pseudo-value
 
 - `best` resolves to Fable 5 where the org has access, latest Opus otherwise.
-  Needs Claude Code >= 2.1.170. (The kit SoT default is `opus`, paired with
-  the `fable` advisor — see the advisor note below.)
+  Needs Claude Code >= 2.1.170. The kit SoT pins `fable` directly, so lack of
+  Fable access is surfaced instead of silently changing the configured model.
 - `default` is an engine pseudo-value: it DELETES the deployed `model` key so
   the account default applies. It never reaches the settings file as a value.
 
@@ -29,14 +29,14 @@ the entry and date when a model ships or retires.
 docks-kit models                  # both catalogs
 docks-kit models claude --json    # machine-readable
 docks-kit model claude            # current deployed + SoT + picker (TTY)
-docks-kit model claude fable      # set deployed model
+docks-kit model claude opus       # per-machine override from the Fable SoT
 docks-kit sync claude --claude-model=opus   # same, as part of a sync
 ```
 
 ## Advisor pairing note (Claude)
 
-The advisor model must be at least as capable as the main model; Fable
-outranks Opus, so an Opus main + Fable advisor works while Fable main +
-Opus advisor is rejected. The SoT ships `model: opus` + `advisorModel:
-fable` as the deployed-everywhere default; use settings.local.json only
-for a deliberate per-machine deviation.
+The SoT ships `model: fable` with advisor off (`advisorModel` unset).
+Advisor is a per-machine opt-in: `docks-kit sync claude --claude-advisor=on`
+writes `advisorModel: fable`; `off` and `default` delete the key. Fable-main +
+Fable-advisor is an accepted pairing. The advisor needs Fable org access and
+Claude Code >= 2.1.170.

package/cli/docs/modifiers.md

@@ -5,15 +5,32 @@ the SoT is never touched. They all share one contract:
 
 > A later flag-less sync reverts the modifier: the settings merge (Claude)
 > and the config.toml merge (Codex) re-assert SoT values for kit-owned keys.
-> Re-pass the flag on machines that should keep the override, or make it
-> persistent in `~/.claude/settings.local.json` (which sync never touches).
+> Re-pass the flag on machines that should keep the override. Claude-only
+> profiles can instead use `~/.claude/settings.local.json`, which sync never
+> touches.
+
+Claude's embedded SoT is `model: fable`, `effortLevel: high`, with advisor
+off (`advisorModel` unset). Codex's embedded reasoning effort is `xhigh`.
 
 | Modifier | Deployed change | Typical use |
 |----------|-----------------|-------------|
-| `--claude-model=<m>` | `.model` in ~/.claude/settings.json (`default` deletes the key) | Drop one machine to opus while the SoT stays on `best` |
+| `--claude-model=<m>` | `.model` in ~/.claude/settings.json (`default` deletes the key) | Override one machine while the SoT retains `fable` |
+| `--claude-effort=<level>` | `.effortLevel` in ~/.claude/settings.json (`default` writes `high`) | Tune persisted Claude effort per machine; valid `low`, `medium`, `high`, `xhigh` |
+| `--claude-advisor=<state>` | `on` sets `.advisorModel = "fable"`; `off`/`default` remove it | Enable Claude advisor only on machines that need it |
 | `--claude-compact-window=<n>` | `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Disposable containers running long autonomous work (e.g. `680k`) — not host machines |
 | `--claude-permissive` | `permissions.ask = []`, `permissions.deny = []` | Sandboxes/containers where prompts stall unattended work. Never on a host — the deny list is the safety floor |
 | `--codex-model=<m>` | top-level `model = "…"` in ~/.codex/config.toml | Same as claude-model, for Codex |
+| `--codex-effort=<level>` | top-level `model_reasoning_effort = "…"` (`default` writes `xhigh`) | Tune Codex effort per machine; valid `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultra` (model-dependent) |
+
+Bare effort/advisor flags print their verified catalog and exit 2. Invalid
+values do the same with a clear error. Passing a tool-specific modifier without
+selecting that positional target warns and ignores it.
+
+A flag-less Claude sync also removes the formerly kit-owned `advisorModel`
+from machines synced before advisor became opt-in. Any explicit advisor state
+owns that key for the run: `on` writes `fable`; `off` and `default` delete it.
+Codex has no advisor modifier because its documented config has no advisor
+setting; `review_model` applies only to `/review`.
 
 ## Standalone get/set (no full sync)
 

package/cli/docs/overview.md

@@ -9,7 +9,7 @@ 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`) |
@@ -34,6 +34,9 @@ AI-assisted dev environment on every machine.
   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

@@ -33,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,30 +5,41 @@ 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.
+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`,
-   `--claude-model`) — deployed file only.
-5. ~/.claude.json (showTurnDuration, user-scoped MCP servers), connector env
-   export, removed-artifact pruning.
-6. **Plugins** — seven idempotent passes via the `claude plugin` CLI
+5. **Removed-artifact pruning** — prune old shell assets, the Stop hook, and
+   stale kit-owned settings. A flag-less sync removes `advisorModel`; an
+   explicit advisor state excludes only that key so the modifier owns it.
+6. **Deploy-time modifiers** (`--claude-compact-window`, `--claude-permissive`,
+   `--claude-model`, `--claude-effort`, `--claude-advisor`) — deployed file only.
+7. ~/.claude.json (showTurnDuration, user-scoped MCP servers) and connector env
+   export.
+8. **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).
+9. 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)
 
 bubblewrap check (Linux), config.toml merge (top-level keys replaced
 per-key, [table] blocks replaced wholesale, user-only keys/tables preserved),
-`--codex-model` modifier, rules, AGENTS.md, personal marketplace file,
-`codex plugin add` refresh.
+`--codex-model` then `--codex-effort` modifiers, rules, AGENTS.md, personal
+marketplace file, `codex plugin add` refresh.
 
 ## agents (→ ~/.agents/skills, ~/.claude/skills symlinks)
 

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/commands/sync.ts

@@ -5,6 +5,12 @@ import { existsSync } from "node:fs"
 import { join } from "node:path"
 import { bail, engine } from "../engine"
 import type { Logger } from "../engine-native/logger"
+import {
+  advisorCatalog,
+  advisorFlagGrammar,
+  effortCatalog,
+  effortFlagGrammar
+} from "../efforts"
 import { kitHome } from "../kitHome"
 import { modelCatalog, type Tool } from "../manifests"
 import { LoggerService } from "../services"
@@ -49,7 +55,7 @@ const LEGACY_HINTS: Record<string, string> = {
   "--agents": "--agents was renamed: pass the target as a word, e.g. 'sync agents'"
 }
 
-const catalogHint = (t: Tool): string => {
+const modelCatalogHint = (t: Tool): string => {
   const c = modelCatalog(t)
   const list = c.models
     .map((m) => `  ${m.id}${m.note !== undefined ? `  — ${m.note}` : ""}`)
@@ -85,6 +91,14 @@ const claudeModel = Options.text("claude-model").pipe(
   Options.withDescription("Deploy-time modifier: set deployed Claude model (see `docks-kit models claude`)"),
   Options.optional
 )
+const claudeEffort = Options.text("claude-effort").pipe(
+  Options.withDescription("Deploy-time modifier: set Claude effortLevel (bare flag shows valid levels)"),
+  Options.optional
+)
+const claudeAdvisor = Options.text("claude-advisor").pipe(
+  Options.withDescription("Deploy-time modifier: set Claude advisor on/off/default"),
+  Options.optional
+)
 const claudeCompactWindow = Options.text("claude-compact-window").pipe(
   Options.withDescription("Deploy-time modifier: set deployed autocompact window in tokens (e.g. 680000 or 680k)"),
   Options.optional
@@ -102,6 +116,10 @@ const codexModel = Options.text("codex-model").pipe(
   Options.withDescription("Deploy-time modifier: set deployed Codex model (see `docks-kit models codex`)"),
   Options.optional
 )
+const codexEffort = Options.text("codex-effort").pipe(
+  Options.withDescription("Deploy-time modifier: set Codex model_reasoning_effort (bare flag shows valid levels)"),
+  Options.optional
+)
 
 export const syncCommand = Command.make(
   "sync",
@@ -114,10 +132,13 @@ export const syncCommand = Command.make(
     yes,
     verbose,
     claudeModel,
+    claudeEffort,
+    claudeAdvisor,
     claudeCompactWindow,
     claudePermissive,
     claudePlugin,
-    codexModel
+    codexModel,
+    codexEffort
   },
   (config) =>
     Effect.gen(function* () {
@@ -125,7 +146,14 @@ export const syncCommand = Command.make(
         if (VALID_TARGETS.includes(t)) continue
         if (t === "--claude-model" || t === "--codex-model") {
           const tool: Tool = t === "--claude-model" ? "claude" : "codex"
-          return yield* bail(`${catalogHint(tool)}\n${t} requires a value: ${t}=<model>`)
+          return yield* bail(`${modelCatalogHint(tool)}\n${t} requires a value: ${t}=<model>`)
+        }
+        if (t === "--claude-effort" || t === "--codex-effort") {
+          const tool: Tool = t === "--claude-effort" ? "claude" : "codex"
+          return yield* bail(`${effortCatalog(tool)}\n${t} requires a value: ${effortFlagGrammar(tool)}`)
+        }
+        if (t === "--claude-advisor") {
+          return yield* bail(`${advisorCatalog()}\n${t} requires a value: ${advisorFlagGrammar()}`)
         }
         const hint = LEGACY_HINTS[t]
         if (hint !== undefined) {
@@ -148,8 +176,11 @@ export const syncCommand = Command.make(
       if (config.verbose) args.push("--verbose")
       if (config.claudePermissive) args.push("--claude-permissive")
       Option.map(config.claudeModel, (m) => args.push(`--claude-model=${m}`))
+      Option.map(config.claudeEffort, (level) => args.push(`--claude-effort=${level}`))
+      Option.map(config.claudeAdvisor, (state) => args.push(`--claude-advisor=${state}`))
       Option.map(config.claudeCompactWindow, (w) => args.push(`--claude-compact-window=${w}`))
       Option.map(config.codexModel, (m) => args.push(`--codex-model=${m}`))
+      Option.map(config.codexEffort, (level) => args.push(`--codex-effort=${level}`))
       for (const occurrence of config.claudePlugin) {
         occurrence
           .split(",")

package/cli/src/efforts.ts

@@ -0,0 +1,91 @@
+import { sotClaudeSettings, type Tool } from "./manifests"
+import { payloadText } from "./payload"
+
+export const CLAUDE_EFFORT_LEVELS = ["low", "medium", "high", "xhigh"] as const
+export const CODEX_REASONING_EFFORTS = [
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+  "ultra"
+] as const
+export const CLAUDE_ADVISOR_STATES = ["on", "off", "default"] as const
+
+const VERIFIED = "2026-07-10"
+const DEFAULT = "default"
+
+export type ClaudeEffortLevel = typeof CLAUDE_EFFORT_LEVELS[number]
+export type CodexReasoningEffort = typeof CODEX_REASONING_EFFORTS[number]
+export type ClaudeAdvisorState = typeof CLAUDE_ADVISOR_STATES[number]
+
+const upstreamEfforts = (tool: Tool): ReadonlyArray<string> =>
+  tool === "claude" ? CLAUDE_EFFORT_LEVELS : CODEX_REASONING_EFFORTS
+
+export const effortModifierValues = (tool: Tool): ReadonlyArray<string> => [
+  ...upstreamEfforts(tool),
+  DEFAULT
+]
+
+export const effortValueGrammar = (tool: Tool): string => effortModifierValues(tool).join("|")
+
+export const effortFlagGrammar = (tool: Tool): string =>
+  `--${tool}-effort=<${effortValueGrammar(tool)}>`
+
+export const advisorValueGrammar = (): string => CLAUDE_ADVISOR_STATES.join("|")
+
+export const advisorFlagGrammar = (): string => `--claude-advisor=<${advisorValueGrammar()}>`
+
+export const isEffortModifierValue = (tool: Tool, value: string): boolean =>
+  effortModifierValues(tool).includes(value)
+
+export function validateEffortDefault(tool: Tool, value: unknown): string {
+  const toolName = tool === "claude" ? "Claude" : "Codex"
+  const setting = tool === "claude" ? "effortLevel" : "model_reasoning_effort"
+  if (typeof value !== "string" || value === "") {
+    throw new Error(`Embedded SoT ${toolName} ${setting} is missing`)
+  }
+  if (!upstreamEfforts(tool).includes(value)) {
+    throw new Error(`Embedded SoT ${toolName} ${setting} '${value}' is outside the verified catalog`)
+  }
+  return value
+}
+
+function codexSotEffort(): string | undefined {
+  return payloadText("SoT/.codex/config.toml").match(/^model_reasoning_effort\s*=\s*"([^"]+)"/m)?.[1]
+}
+
+export function sotEffort(tool: Tool): string {
+  const value = tool === "claude" ? sotClaudeSettings().effortLevel : codexSotEffort()
+  return validateEffortDefault(tool, value)
+}
+
+export function resolveEffort(tool: Tool, value: string): string {
+  if (value === DEFAULT) return sotEffort(tool)
+  if (!upstreamEfforts(tool).includes(value)) {
+    throw new Error(`Invalid ${tool} effort '${value}'`)
+  }
+  return value
+}
+
+export function effortCatalog(tool: Tool): string {
+  const setting = tool === "claude" ? "effortLevel" : "model_reasoning_effort"
+  const lines = [
+    `Available ${tool} effort levels (${setting}; verified ${VERIFIED}):`,
+    ...upstreamEfforts(tool).map((value) => `  ${value}`),
+    `  default  — SoT: ${sotEffort(tool)}`
+  ]
+  if (tool === "codex") lines.push("  (support is model-dependent)")
+  return lines.join("\n")
+}
+
+export function advisorCatalog(): string {
+  return [
+    `Available claude advisor states (advisorModel; verified ${VERIFIED}):`,
+    "  on  — set advisorModel: fable",
+    "  off  — unset advisorModel",
+    "  default  — SoT: off (unset)"
+  ].join("\n")
+}

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

@@ -27,9 +27,10 @@ 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
@@ -72,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
 
@@ -114,15 +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 |
 | `../payload.ts` | generated text/byte payload reads and presentation-only source labels |
-| `claudeSync.ts` | Claude pipeline: RTK, assets, settings merge, deploy-time modifiers, `~/.claude.json`, connector env, removed artifacts, plugins, optional plugins, LSP binaries |
+| `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 |
@@ -142,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
 
@@ -153,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.
 
@@ -162,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.