docks-kit 0.6.0 → 0.7.1

package/AGENTS.md

@@ -14,10 +14,10 @@ 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`). 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 |
+| `docks-kit` | CLI launcher: runs the platform binary in `cli/dist/` only when its `--version` matches `package.json`, otherwise Bun-from-source (auto-installs Bun + `node_modules`). No-Bun recovery is the standalone platform release binary |
+| `cli/src/engine-native/` | EngineNative implementation for `sync`, `model`, `workflow`, and `toolchain`; idempotent, flag-gated for destructive reconciliation |
 | `cli/` | Effect-TS CLI + bundled docs topics |
-| `SoT/models.json` | Kit-verified model catalog |
+| `SoT/models.json` | Kit-verified model catalog plus the strict Docks workflow-role registry |
 | `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 |
@@ -36,6 +36,7 @@ Codex SoT notes:
 - `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.
 - `docks-kit status` verifies Session Relay only through the supported `codex plugin list --json` inventory. `ready` means installed and enabled for a newly started Codex session; it is not evidence about an old process, lifecycle state, receive-path health, or worker quiescence. The global prompt SoTs carry the owner's standing authorization for Docks cross-company plan review, which never overrides host or platform denial.
+- Both global prompt SoTs carry one byte-identical compact `Docks-workflow-models:` record. Root `--model-orchestrator` / `--model-reviewer` / `--model-implementer` / review-bound flags update only that deployed record; `docks-kit models workflow` lists the closed selectors, and a flag-less sync restores defaults.
 - 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.
@@ -47,7 +48,7 @@ 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>` / `--claude-effort=<level>` / `--claude-advisor=<on|off|default>` / `--codex-model=<m>` / `--codex-effort=<level>` (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`, `--skip-plugin-refresh` (install missing plugins without refreshing existing caches; used by `docks-kit update`), `--reconcile`, `--prune`, `--yes` (auto-accept toolchain prompts), and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--claude-effort=<level>` / `--claude-advisor=<on|off|default>` / `--codex-model=<m>` / `--codex-effort=<level>` (see `CLAUDE.md` § Deploy-time modifiers).
 - **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`; `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`.
@@ -86,10 +87,10 @@ When a kit-mechanic skill, its `references/`, or a wrapper agent (`.claude/agent
 ## Plans
 
 <constraint>
-Multi-commit work plans live in `docs/plans/active/` (status is a frontmatter field) and `docs/plans/finished/` (archive). Every plan file is a complete handoff document — `goal`, `Steps`, `Acceptance criteria`, `Review` — so any agent can pick one up cold. Skills handle every operation: `plan-init` (bootstrap/migrate), `plan-manager` (list/show/start/block/ship/new, auto-commit on transition, self-review on draft), `plan-review` (verification). Trigger by natural language or the matching `plan-*` skill. `active/` is multi-occupancy.
+Multi-commit work plans live in `docs/plans/active/` (status is a frontmatter field) and `docs/plans/finished/` (archive). Every plan file is a complete cold-handoff document — goal, context & rationale, environment & how-to-run, steps with exact paths, executable acceptance criteria, and a binary cold-handoff checklist — so any agent (or a weaker model) can pick one up cold without guessing. Skills handle every operation: `plan-init` (bootstrap/migrate), `plan-manager` (list/show/start/block/ship/new, auto-commit on transition, self-review on draft), `plan-review` (verification). Trigger by natural language or the matching `plan-*` skill. `active/` is multi-occupancy.
 </constraint>
 
-The full convention (frontmatter schema, body sections, self-review loop, open-questions, age tokens) lives in `docs/plans/AGENTS.md`. `docs/plans/CLAUDE.md` is a one-line `@AGENTS.md` import for Claude Code's nested discovery.
+The full convention (frontmatter schema, body sections, one-pass local self-review, bounded strong-default X/S review receipts, workflow roles, open-questions, age tokens) lives in `docs/plans/AGENTS.md`. `docs/plans/CLAUDE.md` is a one-line `@AGENTS.md` import for Claude Code's nested discovery. If `.codex/agents/plan-manager.toml` and `.codex/agents/plan-review.toml` exist, Codex may use them for explicit subagent delegation; otherwise run the matching `plan-*` skill inline.
 
 Distinct from per-tool **Open Concerns** sections (wait-on-upstream
 blockers tied to a vendor shipping a fix — these live inside the per-tool

package/README.md

@@ -17,8 +17,10 @@ cd ~/projects/public
 ./docks-kit status          # doctor view: drift, toolchain, plugins, skills
 ```
 
-The `./docks-kit` launcher prefers a compiled binary (`cli/dist/`), then runs
-from source via Bun — auto-installing Bun and dependencies when missing.
+The `./docks-kit` launcher prefers a compiled binary (`cli/dist/`) only when
+its version matches the checkout, then runs from source via Bun — auto-installing
+Bun and dependencies when missing. Stale ignored build artifacts cannot mask
+newer checkout code.
 
 Other install paths (global `bun add -g docks-kit`, curl installer) —
 see `./docks-kit docs install`.
@@ -39,7 +41,7 @@ RTK/Bun download boundaries, not as a global sync prerequisite.
 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 models [claude|codex|workflow]   model and workflow-role catalogs (`--json`)
 docks-kit toolchain [check|ensure <tool>]  verified-version floors for external tools
 docks-kit status [--json]                  deployed-vs-SoT drift + toolchain + counts
 docks-kit plugins list [--json]            enabledPlugins tri-state vs installed
@@ -65,12 +67,28 @@ golden-regression coverage for dry-run output, mutation snapshots, and argv logs
 | `--claude-plugin=<name>` | Sticky opt-in plugin (supabase, n8n) |
 | `--codex-model=<m>` | Deploy-time modifier: deployed Codex model |
 | `--skip-rtk` | Skip optional tool bootstrap |
+| `--skip-plugin-refresh` | Install missing plugins but skip refresh-only updates (used automatically by `docks-kit update`) |
 | `--yes` | Auto-accept toolchain prompts (CI/containers) |
 
 **Deploy-time modifiers** change deployed config only — the SoT is untouched
 and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 (includes the old→new rename table for the pre-CLI `sync.sh` flags).
 
+### Docks workflow roles (root flags)
+
+| Flag | Effect |
+|------|--------|
+| `--model-orchestrator=<selector>` | Override the Docks orchestrator candidate/profile |
+| `--model-reviewer=<selector>` | Override the Docks reviewer candidate/profile |
+| `--model-implementer=<selector>` | Override the Docks implementer candidate/profile |
+| `--review-min-score=<0..100>` | Override the completion-review target |
+| `--review-max-rounds=<1..10>` | Bound completion-review batches |
+
+Selectors are strict `profile:<name>` or `<tool>:<model>@<effort>` values from
+`docks-kit models workflow`. These root flags update only the identical compact
+record in `~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md`; omitted fields retain
+their current valid values, while a later flag-less sync restores all defaults.
+
 ## How syncing works
 
 - **Additive by default** — user-only settings keys, plugins, and skills
@@ -83,7 +101,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
   (`--yes` accepts; non-TTY falls back to the pinned verified version
   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.
+  model validation, listings, pickers, and the Docks workflow-role registry.
 - **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,
@@ -97,7 +115,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 | `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/models.json` | Kit-verified model and Docks workflow-role 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 |

package/cli/docs/flags.md

@@ -19,6 +19,7 @@ docks-kit sync claude agents        # two
 | `--reconcile` | Settings layer reconciled toward SoT (SoT keys win; user-only keys preserved; permissions arrays replaced) |
 | `--prune` | Uninstall kit-managed installs not in SoT: plugins, marketplaces, universal skills |
 | `--skip-rtk` | Skip optional tool bootstrap (RTK, bubblewrap) |
+| `--skip-plugin-refresh` | Install missing Claude/Codex plugins but skip refresh-only updates; `docks-kit update` uses this automatically |
 | `--yes` | Auto-accept toolchain above-verified prompts (containers/CI) |
 | `--verbose` / `-v` | Also print no-op confirmations (already in sync, up to date, left as-is); accepted on `sync`, `model`, and `toolchain` |
 
@@ -39,6 +40,23 @@ 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.
 
+## Docks workflow root flags
+
+These flags belong at the root (`docks-kit --model-reviewer=...`), not after
+`sync`. They update only the shared deployed workflow record.
+
+| Flag | Accepted value |
+|------|----------------|
+| `--model-orchestrator=<selector>` | `profile:<name>` or `<tool>:<model>@<effort>` |
+| `--model-reviewer=<selector>` | same strict selector grammar |
+| `--model-implementer=<selector>` | same strict selector grammar |
+| `--review-min-score=<n>` | base-10 integer `0..100` |
+| `--review-max-rounds=<n>` | base-10 integer `1..10` |
+
+Use `docks-kit models workflow [--json]` for the closed registry. Bare, empty,
+unknown, or malformed values print that helper and exit 2 before either prompt
+file changes.
+
 ## Renamed legacy flags (pre-CLI sync.sh)
 
 Old flags exit with a rename hint — there is no compat behavior.

package/cli/docs/install.md

@@ -8,9 +8,10 @@ cd ~/projects/public
 ./docks-kit sync
 ```
 
-The `./docks-kit` launcher prefers a compiled binary in `cli/dist/`, then
-falls back to Bun-from-source (auto-installing Bun via download-then-run and
-`bun install --frozen-lockfile` when needed).
+The `./docks-kit` launcher prefers a compiled binary in `cli/dist/` only when
+its reported version matches `package.json`, then falls back to Bun-from-source
+(auto-installing Bun via download-then-run and `bun install --frozen-lockfile`
+when needed). An ignored stale build is reported and bypassed.
 
 ## 2. Global via Bun (effect-solutions-style)
 
@@ -78,7 +79,7 @@ Two supported paths (CI-verified on windows-2025, native PowerShell):
 ## Keeping the kit up to date
 
 ```
-docks-kit update            # autodetect + update + chained flag-less sync
+docks-kit update            # autodetect + update + install-missing-only sync
 docks-kit update --no-sync  # update only
 ```
 
@@ -86,8 +87,10 @@ 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.
+`npm install -g docks-kit@latest`). The chained sync skips refresh-only work
+for already-installed Claude/Codex plugins but still installs missing ones.
+A compiled binary inside a checkout updates the checkout; on the next invocation
+the launcher bypasses that now-stale binary and uses updated source until rebuilt.
 Every `docks-kit sync` also does a best-effort behind-upstream check and
 nudges when the checkout is stale (silent offline / detached / no git).
 

package/cli/docs/models.md

@@ -31,8 +31,27 @@ docks-kit models claude --json    # machine-readable
 docks-kit model claude            # current deployed + SoT + picker (TTY)
 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
+docks-kit models workflow             # Docks workflow profiles and defaults
+docks-kit models workflow --json      # closed machine-readable registry
 ```
 
+## Docks workflow-role registry
+
+The `workflow` section is strict even though ordinary tool-model modifiers are
+forward-compatible. It accepts only known `profile:<name>` values or exact
+`<tool>:<model>@<effort>` targets whose model and effort both appear in the
+catalog. The defaults are:
+
+- orchestrator: `profile:claude-best`, ordered as `claude:fable@high` then
+  `claude:opus@xhigh`;
+- reviewer and implementer: `codex:gpt-5.6-sol@xhigh`;
+- review minimum score 90 and maximum 3 rounds.
+
+`claude:best@high` is Claude's native one-model alias. It is deliberately not
+the same as the Docks-managed `profile:claude-best` candidate chain.
+Availability is `checked_when_used`: Docks classifies each launch attempt;
+docks-kit neither probes providers nor promises provider-wide fallback.
+
 ## Advisor pairing note (Claude)
 
 The SoT ships `model: fable` with advisor off (`advisorModel` unset).

package/cli/docs/modifiers.md

@@ -44,6 +44,29 @@ docks-kit model codex gpt-5.5     # codex flavor
 The set path calls the same engine functions as the sync flags —
 one implementation, two entry points.
 
+## Workflow-role overrides (root, no full sync)
+
+The root workflow flags are deployed modifiers for Docks rather than one tool:
+
+```text
+docks-kit --model-orchestrator=profile:claude-best \
+  --model-reviewer=codex:gpt-5.6-terra@high \
+  --review-min-score=80 --review-max-rounds=5
+```
+
+They atomically write one byte-identical complete record to
+`~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md`. Omitted fields retain the
+current valid record; a missing side is repaired. Invalid or conflicting state
+stops before mutation, a repeated request is a no-op, and failure on the second
+atomic write restores both snapshots. A later flag-less sync restores the
+embedded defaults. Start fresh sessions after changing the record.
+
+Selectors are strict `profile:<name>` or `<tool>:<model>@<effort>` entries from
+`docks-kit models workflow`. `profile:claude-best` is the ordered Docks
+Fable-high then Opus-xhigh chain; `claude:best@high` is instead Claude's native
+single-model alias. Docks checks each candidate when used—there is no docks-kit
+provider preflight.
+
 ## Sticky opt-ins are NOT modifiers
 
 `--claude-plugin=<name>` installs+enables an optional plugin and it STAYS

package/cli/docs/overview.md

@@ -17,7 +17,7 @@ AI-assisted dev environment on every machine.
 | `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 |
+| `docks-kit` | Launcher: version-matching compiled binary → bun-from-source, with Bun auto-install |
 
 ## Design rules
 

package/cli/src/commands/models.ts

@@ -2,9 +2,10 @@ import { Args, Command, Options } from "@effect/cli"
 import { Console, Effect, Option } from "effect"
 import { bail } from "../engine"
 import { modelCatalog, type Tool } from "../manifests"
+import { workflowCatalog, workflowRegistryJson } from "../workflowModels"
 
 const tool = Args.text({ name: "tool" }).pipe(
-  Args.withDescription("claude | codex (omit for both)"),
+  Args.withDescription("claude | codex | workflow (omit for both tool catalogs)"),
   Args.optional
 )
 const json = Options.boolean("json").pipe(
@@ -24,8 +25,11 @@ const renderTool = (t: Tool) =>
 export const modelsCommand = Command.make("models", { tool, json }, (config) =>
   Effect.gen(function* () {
     const requested = Option.getOrUndefined(config.tool)
+    if (requested === "workflow") {
+      return yield* Console.log(config.json ? workflowRegistryJson() : workflowCatalog())
+    }
     if (requested !== undefined && requested !== "claude" && requested !== "codex") {
-      return yield* bail(`Unknown tool '${requested}' (valid: claude, codex)`)
+      return yield* bail(`Unknown tool '${requested}' (valid: claude, codex, workflow)`)
     }
     const tools: Array<Tool> = requested !== undefined ? [requested as Tool] : ["claude", "codex"]
 
@@ -42,5 +46,5 @@ export const modelsCommand = Command.make("models", { tool, json }, (config) =>
     )
   })
 ).pipe(
-  Command.withDescription("List the kit-verified model catalog (SoT/models.json) for claude/codex.")
+  Command.withDescription("List kit-verified tool models or the Docks workflow role registry (SoT/models.json).")
 )

package/cli/src/commands/sync.ts

@@ -80,6 +80,9 @@ const prune = Options.boolean("prune").pipe(
 const skipRtk = Options.boolean("skip-rtk").pipe(
   Options.withDescription("Skip optional tool bootstrap (RTK, bubblewrap)")
 )
+const skipPluginRefresh = Options.boolean("skip-plugin-refresh").pipe(
+  Options.withDescription("Install missing plugins but skip refresh-only updates for existing plugins")
+)
 const yes = Options.boolean("yes").pipe(
   Options.withDescription("Auto-accept toolchain prompts (containers/CI)")
 )
@@ -129,6 +132,7 @@ export const syncCommand = Command.make(
     reconcile,
     prune,
     skipRtk,
+    skipPluginRefresh,
     yes,
     verbose,
     claudeModel,
@@ -172,6 +176,7 @@ export const syncCommand = Command.make(
       if (config.reconcile) args.push("--reconcile")
       if (config.prune) args.push("--prune")
       if (config.skipRtk) args.push("--skip-rtk")
+      if (config.skipPluginRefresh) args.push("--skip-plugin-refresh")
       if (config.yes) args.push("--yes")
       if (config.verbose) args.push("--verbose")
       if (config.claudePermissive) args.push("--claude-permissive")

package/cli/src/commands/update.ts

@@ -26,6 +26,12 @@ const chainSync = (argv0: string, args: Array<string>): Effect.Effect<void> =>
     if (res.error !== undefined || res.status !== 0) process.exit(res.status ?? 1)
   })
 
+export const updateSyncArgs = (home: string): Array<string> => [
+  join(home, "cli/src/main.ts"),
+  "sync",
+  "--skip-plugin-refresh"
+]
+
 const updateCheckout = (home: string, skipSync: boolean) =>
   Effect.gen(function* () {
     if (spawnSync("git", ["--version"], { stdio: "ignore" }).status !== 0) {
@@ -62,12 +68,12 @@ const updateCheckout = (home: string, skipSync: boolean) =>
 
     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"
+        "This compiled binary still runs the previous version - the checkout launcher will use updated source next time. Run: ./docks-kit sync (rebuild with bash cli/build-binaries.sh to restore the binary fast path)."
       )
     }
     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"])
+    return yield* chainSync(process.execPath, updateSyncArgs(home))
   })
 
 const updatePackage = (home: string, skipSync: boolean) =>
@@ -93,7 +99,7 @@ const updatePackage = (home: string, skipSync: boolean) =>
     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"])
+    return yield* chainSync(process.execPath, updateSyncArgs(home))
   })
 
 export const updateCommand = Command.make("update", { noSync }, (config) =>
@@ -111,6 +117,6 @@ export const updateCommand = Command.make("update", { noSync }, (config) =>
   })
 ).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)."
+    "Self-update the kit: autodetects the install (git checkout -> ff-only pull; bun/npm global -> @latest) and chains an install-missing-only sync with the new version (--no-sync to skip)."
   )
 )

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

@@ -31,6 +31,7 @@ import { ExitError } from "./parseArgs"
 import { mergeSettings, reconcileSettings } from "./settings"
 import { ensure, field } from "./toolchain"
 import { payloadBytes, payloadDisplayPath, payloadText } from "../payload"
+import { renderDefaultWorkflowInstructions } from "./workflowDeploy"
 
 export type ClaudeRuntimeState =
   | { readonly kind: "ready"; readonly paths: ClaudeRuntimePaths }
@@ -222,7 +223,7 @@ function syncClaudeMd(ctx: Ctx, claudeDir: string): void {
     return
   }
 
-  const source = payloadText("SoT/.claude/CLAUDE.md")
+  const source = renderDefaultWorkflowInstructions(payloadText("SoT/.claude/CLAUDE.md"))
   const stripReason = ctx.skipRtk ? "--skip-rtk" : rtkMdAbsent ? "~/.claude/RTK.md absent (rtk not initialized)" : ""
   if (stripReason !== "") {
     const stripped = source
@@ -503,6 +504,10 @@ const REMOVED_MANIFEST = {
     "env.CLAUDE_CODE_FORK_SUBAGENT",
     "env.CLAUDE_CODE_EFFORT_LEVEL"
   ],
+  permissionRules: {
+    allow: ["Write(./)"],
+    deny: ["Write(**/.env)", "Write(**/.env.local)", "Write(**/secrets/**)"]
+  },
   claudeJsonKeys: [] as Array<string>,
   runtimeReady: {
     hooks: ["notify.sh"],
@@ -544,6 +549,30 @@ function pruneJsonKeys(ctx: Ctx, file: string, keys: Array<string>): number {
   return presentKeys.length
 }
 
+function prunePermissionRules(
+  ctx: Ctx,
+  file: string,
+  rules: Readonly<Record<"allow" | "deny", ReadonlyArray<string>>>
+): number {
+  if (!existsSync(file)) return 0
+  const doc = parseJson(readFileSync(file, "utf8"))
+  if (doc === undefined || !isObject(doc) || !isObject(doc["permissions"])) return 0
+  const permissions = doc["permissions"]
+  let present = 0
+  for (const key of ["allow", "deny"] as const) {
+    const values = permissions[key]
+    if (!Array.isArray(values)) continue
+    const removed = new Set(rules[key])
+    present += rules[key].filter((rule) => values.includes(rule)).length
+    if (!ctx.dryRun) permissions[key] = values.filter((value) => typeof value !== "string" || !removed.has(value))
+  }
+  if (present > 0 && !ctx.dryRun) {
+    writeFileSync(`${file}.tmp`, jqStringify(doc))
+    renameSync(`${file}.tmp`, file)
+  }
+  return present
+}
+
 function syncRemovals(ctx: Ctx, claudeDir: string, runtime: ClaudeRuntimeState): void {
   const { change, echo } = ctx.services.logger
   let hooksRemoved = 0
@@ -591,16 +620,25 @@ function syncRemovals(ctx: Ctx, claudeDir: string, runtime: ClaudeRuntimeState):
   }
 
   const skeys = pruneJsonKeys(ctx, p(claudeDir, "settings.json"), settingsKeys)
+  const permissionRules = prunePermissionRules(
+    ctx,
+    p(claudeDir, "settings.json"),
+    REMOVED_MANIFEST.permissionRules
+  )
   const cjkeys = pruneJsonKeys(ctx, p(ctx.home, ".claude.json"), REMOVED_MANIFEST.claudeJsonKeys)
 
   if (ctx.dryRun) {
     if (skeys > 0) echo(`[dry-run] del ${skeys} stale key(s) from ${p(claudeDir, "settings.json")}`)
+    if (permissionRules > 0) {
+      echo(`[dry-run] del ${permissionRules} stale permission rule(s) from ${p(claudeDir, "settings.json")}`)
+    }
     if (cjkeys > 0) echo(`[dry-run] del ${cjkeys} stale key(s) from ${p(ctx.home, ".claude.json")}`)
     return
   }
 
-  if (hooksRemoved + filesRemoved + skeys + cjkeys > 0) {
-    change(`Pruned stale artifacts (hooks: ${hooksRemoved}, files: ${filesRemoved}, settings keys: ${skeys}, claude.json keys: ${cjkeys})`)
+  if (hooksRemoved + filesRemoved + skeys + permissionRules + cjkeys > 0) {
+    const permissionSummary = permissionRules > 0 ? `, permission rules: ${permissionRules}` : ""
+    change(`Pruned stale artifacts (hooks: ${hooksRemoved}, files: ${filesRemoved}, settings keys: ${skeys}, claude.json keys: ${cjkeys}${permissionSummary})`)
     ctx.nextStepTriggers.claudeRestart = true
   }
 }
@@ -636,7 +674,11 @@ function syncPlugins(ctx: Ctx, claudeDir: string): void {
   const installedPlugins = p(claudeDir, "plugins", "installed_plugins.json")
 
   if (ctx.dryRun) {
-    echo("[dry-run] bootstrap + update plugin marketplaces + plugins from SoT")
+    echo(
+      ctx.skipPluginRefresh
+        ? "[dry-run] bootstrap + install missing plugins from SoT; skip refresh-only plugin updates"
+        : "[dry-run] bootstrap + update plugin marketplaces + plugins from SoT"
+    )
     if (ctx.prune) {
       echo("[dry-run] (--prune) would also uninstall plugins not in SoT and remove extra marketplaces")
     }
@@ -694,13 +736,16 @@ function syncPlugins(ctx: Ctx, claudeDir: string): void {
     }
   }
 
-  // Pass 3 — refresh every installed plugin.
-  cli(["plugin", "marketplace", "update"])
   let updatedPl = 0
   const installedDoc = readJsonFile(installedPlugins)
   const installedKeys = installedDoc !== undefined && isObject(installedDoc) ? sortedKeys(installedDoc["plugins"]) : []
-  for (const pluginId of installedKeys) {
-    if (cli(["plugin", "update", pluginId]).out.includes("Successfully updated")) updatedPl++
+  // Pass 3 — refresh every installed plugin unless the update command
+  // selected its install-missing-only fast path.
+  if (!ctx.skipPluginRefresh) {
+    cli(["plugin", "marketplace", "update"])
+    for (const pluginId of installedKeys) {
+      if (cli(["plugin", "update", pluginId]).out.includes("Successfully updated")) updatedPl++
+    }
   }
 
   // Passes 4 + 5 — prune-gated uninstall + marketplace removal.

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

@@ -12,6 +12,7 @@ import type { Ctx } from "./index"
 import { compareCodepoints, isObject, jqStringify, parseJson, type Json } from "./jq"
 import { sessionRelayReadiness } from "./sessionRelayReadiness"
 import { payloadBytes, payloadDisplayPath, payloadPaths, payloadText, type PayloadPath } from "../payload"
+import { renderDefaultWorkflowInstructions } from "./workflowDeploy"
 
 export function codexSync(ctx: Ctx): void {
   const codexDir = p(ctx.home, ".codex")
@@ -24,7 +25,7 @@ export function codexSync(ctx: Ctx): void {
   syncCodexModel(ctx, ctx.codexModel)
   syncCodexEffort(ctx, ctx.codexEffort)
   syncRules(ctx, payloadPaths("SoT/.codex/rules/"), p(codexDir, "rules"))
-  syncAgentsMd(ctx, payloadText("SoT/.codex/AGENTS.md"), p(codexDir, "AGENTS.md"))
+  syncAgentsMd(ctx, renderDefaultWorkflowInstructions(payloadText("SoT/.codex/AGENTS.md")), p(codexDir, "AGENTS.md"))
   syncMarketplace(ctx, payloadText("SoT/.codex/plugins/marketplace.json"), p(ctx.agentsDir, "plugins", "marketplace.json"))
   removeLegacyDocksMarketplace(ctx, userConfig)
   syncPlugins(ctx, sotConfig)
@@ -431,10 +432,30 @@ function manualPluginRefreshCommand(sotConfigText: string): string {
   return first !== undefined ? `codex plugin add ${first}` : "codex plugin add <plugin@marketplace>"
 }
 
+function installedPluginIdsFromCli(): Set<string> | undefined {
+  const result = spawnSync("codex", ["plugin", "list", "--json"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+  })
+  if (result.error !== undefined || result.status !== 0) return undefined
+  const value = parseJson(result.stdout ?? "")
+  if (value === undefined || !isObject(value) || !Array.isArray(value["installed"])) return undefined
+  const ids = new Set<string>()
+  for (const row of value["installed"]) {
+    if (!isObject(row) || row["installed"] !== true || typeof row["pluginId"] !== "string") continue
+    ids.add(row["pluginId"])
+  }
+  return ids
+}
+
 function syncPlugins(ctx: Ctx, sotConfigText: string): void {
-  const { change, echo, warn } = ctx.services.logger
+  const { change, echo, verbose, warn } = ctx.services.logger
   if (ctx.dryRun) {
-    echo("[dry-run] add enabled Codex plugins from SoT")
+    echo(
+      ctx.skipPluginRefresh
+        ? "[dry-run] add missing enabled Codex plugins from SoT; skip refresh-only plugin updates"
+        : "[dry-run] add enabled Codex plugins from SoT"
+    )
     return
   }
 
@@ -453,9 +474,20 @@ function syncPlugins(ctx: Ctx, sotConfigText: string): void {
     return
   }
 
+  const desiredPluginIds = enabledPluginIdsFromText(sotConfigText)
+  let pluginIds = desiredPluginIds
+  if (ctx.skipPluginRefresh) {
+    const installedPluginIds = installedPluginIdsFromCli()
+    if (installedPluginIds === undefined) {
+      warn("Codex plugin inventory unavailable — falling back to the full refresh path")
+    } else {
+      pluginIds = desiredPluginIds.filter((pluginId) => !installedPluginIds.has(pluginId))
+    }
+  }
+
   let refreshed = 0
   let failed = 0
-  for (const pluginId of enabledPluginIdsFromText(sotConfigText)) {
+  for (const pluginId of pluginIds) {
     const res = spawnSync("codex", ["plugin", "add", pluginId], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
     const addOut = `${res.stdout ?? ""}${res.stderr ?? ""}`
     if (res.error === undefined && res.status === 0) {
@@ -482,6 +514,7 @@ function syncPlugins(ctx: Ctx, sotConfigText: string): void {
       warn(`Session Relay readiness unavailable after refresh: ${readiness.reason}`)
     }
   }
+  if (ctx.skipPluginRefresh && pluginIds.length === 0) verbose("Codex plugins already installed; refresh-only updates skipped")
   if (failed > 0) warn(`${failed} Codex plugin operation(s) failed — re-run sync or install manually`)
 }
 

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

@@ -15,7 +15,8 @@ import { claudeNextSteps, claudeSummary, claudeSync } from "./claudeSync"
 import { codexNextSteps, codexSummary, codexSync } from "./codexSync"
 import { skillsNextSteps, skillsSummary, skillsSync } from "./skillsSync"
 import { modeModel, modeToolchain } from "./modes"
-import { ExitError, parseArgs, validateModifierFlags } from "./parseArgs"
+import { ExitError, parseArgs, parseWorkflowArgs, printWorkflowUsage, validateModifierFlags } from "./parseArgs"
+import { deployWorkflowOverrides } from "./workflowDeploy"
 
 export type ModifierFlag =
   | "--claude-model"
@@ -31,6 +32,7 @@ export interface Ctx {
   dryRun: boolean
   verbose: boolean
   skipRtk: boolean
+  skipPluginRefresh?: boolean
   reconcile: boolean
   prune: boolean
   assumeYes: boolean
@@ -71,6 +73,7 @@ function makeCtx(services: EngineServices): Ctx {
     dryRun: env["DRY_RUN"] === "1",
     verbose: env["DOCKS_KIT_VERBOSE"] === "1",
     skipRtk: env["SKIP_RTK"] === "1",
+    skipPluginRefresh: false,
     reconcile: env["RECONCILE"] === "1",
     prune: env["PRUNE"] === "1",
     assumeYes: env["ASSUME_YES"] === "1",
@@ -124,6 +127,19 @@ function engineSync(ctx: Ctx, args: ReadonlyArray<string>): number {
   return 0
 }
 
+function engineWorkflow(ctx: Ctx, args: ReadonlyArray<string>): number {
+  try {
+    const overrides = parseWorkflowArgs(ctx, args)
+    deployWorkflowOverrides(ctx, overrides)
+    return 0
+  } catch (error) {
+    if (error instanceof ExitError) throw error
+    printWorkflowUsage(ctx)
+    ctx.services.logger.err(error instanceof Error ? error.message : String(error))
+    throw new ExitError(2)
+  }
+}
+
 export function runEngineNative(argv: ReadonlyArray<string>, services?: EngineServices): number {
   let ctx!: Ctx
   const baseServices = services ?? makeEngineServices()
@@ -149,6 +165,8 @@ export function runEngineNative(argv: ReadonlyArray<string>, services?: EngineSe
         return modeModel(ctx, argv.slice(1))
       case "toolchain":
         return modeToolchain(ctx, argv.slice(1))
+      case "workflow":
+        return engineWorkflow(ctx, argv.slice(1))
       case "sync":
         return engineSync(ctx, argv.slice(1))
       default: