docks-kit 0.4.0 → 0.5.0

package/AGENTS.md

@@ -32,12 +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.
 
@@ -45,7 +46,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>` / `--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`; `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`.

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)
 
 ```

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/sync-layers.md

@@ -15,18 +15,21 @@ Order matters — runtime readiness and settings form one transaction:
    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.
+   settings.
 4. **settings.json merge semantics** — additive: SoT keys win, permissions arrays are
    unioned, user-only keys survive. `--reconcile` replaces permissions arrays
    wholesale instead.
-5. **Deploy-time modifiers** (`--claude-compact-window`, `--claude-permissive`,
-   `--claude-model`) — deployed file only.
-6. ~/.claude.json (showTurnDuration, user-scoped MCP servers), connector env
-   export, removed-artifact pruning.
-7. **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>`.
-8. 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.
@@ -35,8 +38,8 @@ usage cache, jq/curl runtime dependency, or Stop fetch hook.
 
 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/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/claudeSettingsModifiers.ts

@@ -0,0 +1,101 @@
+/** Atomic top-level Claude settings modifiers, including direct model mode. */
+import { p } from "./exec"
+import { readFileSync, renameSync, writeFileSync } from "node:fs"
+
+import { resolveEffort } from "../efforts"
+import type { Ctx } from "./index"
+import { isObject, jqStringify, parseJson } from "./jq"
+
+interface ClaudeSettingEdit {
+  readonly tag: string
+  readonly key: "model" | "effortLevel" | "advisorModel"
+  readonly value: string | undefined
+  readonly dryRun: string
+  readonly changed: string
+  readonly unchanged: string
+}
+
+function syncClaudeSetting(ctx: Ctx, edit: ClaudeSettingEdit): void {
+  const { change, echo, err, verbose, warn } = ctx.services.logger
+  const userSettings = p(ctx.home, ".claude", "settings.json")
+
+  if (ctx.dryRun) {
+    echo(`[dry-run] (${edit.tag}) ${edit.dryRun} in ${userSettings}`)
+    return
+  }
+
+  let text: string
+  try {
+    text = readFileSync(userSettings, "utf8")
+  } catch {
+    warn(`(${edit.tag}) ${userSettings} missing — skipped`)
+    return
+  }
+  const doc = parseJson(text)
+  if (doc === undefined) {
+    err(`(${edit.tag}) ${userSettings} is not valid JSON — skipped`)
+    return
+  }
+  if (isObject(doc)) {
+    if (edit.value === undefined) delete doc[edit.key]
+    else doc[edit.key] = edit.value
+  }
+  const out = jqStringify(doc)
+  if (out === text) {
+    verbose(edit.unchanged)
+    return
+  }
+  writeFileSync(`${userSettings}.tmp`, out)
+  renameSync(`${userSettings}.tmp`, userSettings)
+  change(edit.changed)
+  ctx.nextStepTriggers.claudeRestart = true
+}
+
+export function syncClaudeModel(ctx: Ctx, model: string): void {
+  if (model === "") return
+  const unset = model === "default"
+  syncClaudeSetting(ctx, {
+    tag: "--claude-model",
+    key: "model",
+    value: unset ? undefined : model,
+    dryRun: unset ? "delete .model (account default applies)" : `set .model=${model}`,
+    changed: `Model: deployed settings model set to ${model} (SoT unchanged; flag-less sync reverts)`,
+    unchanged: `Model: deployed settings model already ${unset ? "unset (account default)" : model}`
+  })
+}
+
+export function syncClaudeEffort(ctx: Ctx, effort: string): void {
+  if (effort === "") return
+  const resolved = resolveEffort("claude", effort)
+  const useDefault = effort === "default"
+  syncClaudeSetting(ctx, {
+    tag: "--claude-effort",
+    key: "effortLevel",
+    value: resolved,
+    dryRun: `set .effortLevel=${resolved}`,
+    changed: useDefault
+      ? `Effort: deployed settings effortLevel set to ${resolved} (SoT default)`
+      : `Effort: deployed settings effortLevel set to ${resolved} (SoT unchanged; flag-less sync reverts)`,
+    unchanged: `Effort: deployed settings effortLevel already ${resolved}`
+  })
+}
+
+export function syncClaudeAdvisor(ctx: Ctx, state: string): void {
+  if (state === "") return
+  const enabled = state === "on"
+  const useDefault = state === "default"
+  syncClaudeSetting(ctx, {
+    tag: "--claude-advisor",
+    key: "advisorModel",
+    value: enabled ? "fable" : undefined,
+    dryRun: enabled ? "set .advisorModel=fable" : "delete .advisorModel (advisor disabled)",
+    changed: enabled
+      ? "Advisor: deployed settings advisorModel set to fable (SoT unchanged; flag-less sync reverts)"
+      : useDefault
+        ? "Advisor: deployed settings advisorModel unset (SoT default: off)"
+        : "Advisor: deployed settings advisorModel unset (--claude-advisor=off; SoT unchanged)",
+    unchanged: enabled
+      ? "Advisor: deployed settings advisorModel already fable"
+      : `Advisor: deployed settings advisorModel already unset (${useDefault ? "SoT default: off" : "advisor off"})`
+  })
+}

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

@@ -17,7 +17,11 @@ import {
 } from "node:fs"
 import { tmpdir } from "node:os"
 import { bunBootstrap } from "./bun"
-import { syncClaudeModel } from "./claudeModel"
+import {
+  syncClaudeAdvisor,
+  syncClaudeEffort,
+  syncClaudeModel
+} from "./claudeSettingsModifiers"
 import { claudeRuntimePaths, materializeClaudeSettings, type ClaudeRuntimePaths } from "./claudeRuntime"
 import { p, writeBytesIfChanged, writeFileIfChanged, writeTextIfChanged } from "./exec"
 import type { Ctx } from "./index"
@@ -73,6 +77,8 @@ export function claudeSync(ctx: Ctx): ClaudeRuntimeState {
   syncCompactWindow(ctx, claudeDir)
   syncPermissive(ctx, claudeDir)
   syncClaudeModel(ctx, ctx.claudeModel)
+  syncClaudeEffort(ctx, ctx.claudeEffort)
+  syncClaudeAdvisor(ctx, ctx.claudeAdvisor)
   syncClaudeJson(ctx)
   syncConnectorEnv(ctx)
   syncPlugins(ctx, claudeDir)
@@ -489,6 +495,7 @@ const REMOVED_MANIFEST = {
   files: ["alert_bubble.mp3"],
   settingsKeys: [
     "showTurnDuration",
+    "advisorModel",
     "env.CLAUDE_CODE_SUBAGENT_MODEL",
     "env.ANTHROPIC_DEFAULT_OPUS_MODEL",
     "env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE",
@@ -550,7 +557,7 @@ function syncRemovals(ctx: Ctx, claudeDir: string, runtime: ClaudeRuntimeState):
     ...(runtime.kind === "ready" ? REMOVED_MANIFEST.runtimeReady.files : [])
   ]
   const settingsKeys = [
-    ...REMOVED_MANIFEST.settingsKeys,
+    ...REMOVED_MANIFEST.settingsKeys.filter((key) => key !== "advisorModel" || ctx.claudeAdvisor === ""),
     ...(runtime.kind === "ready" ? REMOVED_MANIFEST.runtimeReady.settingsKeys : [])
   ]
 

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

@@ -6,7 +6,7 @@
 import { spawnSync } from "node:child_process"
 import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
 
-import { syncCodexModel, replaceTopLevelSettingInFile } from "./codexToml"
+import { syncCodexEffort, syncCodexModel, replaceTopLevelSettingInFile } from "./codexToml"
 import { p } from "./exec"
 import type { Ctx } from "./index"
 import { compareCodepoints, isObject, jqStringify, parseJson, type Json } from "./jq"
@@ -21,6 +21,7 @@ export function codexSync(ctx: Ctx): void {
   if (!ctx.dryRun) mkdirSync(codexDir, { recursive: true })
   syncConfig(ctx, sotConfig, userConfig)
   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"))
   syncMarketplace(ctx, payloadText("SoT/.codex/plugins/marketplace.json"), p(ctx.agentsDir, "plugins", "marketplace.json"))

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

@@ -7,6 +7,7 @@
 import { p } from "./exec"
 import { readFileSync, renameSync, writeFileSync } from "node:fs"
 
+import { resolveEffort } from "../efforts"
 import type { Ctx } from "./index"
 
 export function replaceTopLevelSetting(content: string, key: string, replacement: string): string {
@@ -48,27 +49,59 @@ export function replaceTopLevelSettingInFile(file: string, key: string, replacem
   return true
 }
 
-export function syncCodexModel(ctx: Ctx, model: string): void {
+interface CodexSettingEdit {
+  readonly tag: string
+  readonly key: "model" | "model_reasoning_effort"
+  readonly value: string
+  readonly changed: string
+  readonly unchanged: string
+}
+
+function syncCodexSetting(ctx: Ctx, edit: CodexSettingEdit): void {
   const { change, echo, verbose, warn } = ctx.services.logger
   const userCodexSettings = p(ctx.home, ".codex", "config.toml")
 
-  if (model === "") return
-
   if (ctx.dryRun) {
-    echo(`[dry-run] (--codex-model) set model = "${model}" in ${userCodexSettings}`)
+    echo(`[dry-run] (${edit.tag}) set ${edit.key} = "${edit.value}" in ${userCodexSettings}`)
     return
   }
 
   try {
     readFileSync(userCodexSettings)
   } catch {
-    warn(`(--codex-model) ${userCodexSettings} missing — skipped`)
+    warn(`(${edit.tag}) ${userCodexSettings} missing — skipped`)
     return
   }
-  if (replaceTopLevelSettingInFile(userCodexSettings, "model", `model = "${model}"`)) {
-    change(`Model: deployed Codex model set to ${model} (SoT unchanged; flag-less sync reverts)`)
+  if (replaceTopLevelSettingInFile(userCodexSettings, edit.key, `${edit.key} = "${edit.value}"`)) {
+    change(edit.changed)
     ctx.nextStepTriggers.codexRestart = true
   } else {
-    verbose(`Model: deployed Codex model already ${model}`)
+    verbose(edit.unchanged)
   }
 }
+
+export function syncCodexModel(ctx: Ctx, model: string): void {
+  if (model === "") return
+  syncCodexSetting(ctx, {
+    tag: "--codex-model",
+    key: "model",
+    value: model,
+    changed: `Model: deployed Codex model set to ${model} (SoT unchanged; flag-less sync reverts)`,
+    unchanged: `Model: deployed Codex model already ${model}`
+  })
+}
+
+export function syncCodexEffort(ctx: Ctx, effort: string): void {
+  if (effort === "") return
+  const resolved = resolveEffort("codex", effort)
+  const useDefault = effort === "default"
+  syncCodexSetting(ctx, {
+    tag: "--codex-effort",
+    key: "model_reasoning_effort",
+    value: resolved,
+    changed: useDefault
+      ? `Effort: deployed Codex model_reasoning_effort set to ${resolved} (SoT default)`
+      : `Effort: deployed Codex model_reasoning_effort set to ${resolved} (SoT unchanged; flag-less sync reverts)`,
+    unchanged: `Effort: deployed Codex model_reasoning_effort already ${resolved}`
+  })
+}

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

@@ -15,7 +15,14 @@ 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, validateModelFlags } from "./parseArgs"
+import { ExitError, parseArgs, validateModifierFlags } from "./parseArgs"
+
+export type ModifierFlag =
+  | "--claude-model"
+  | "--claude-effort"
+  | "--claude-advisor"
+  | "--codex-model"
+  | "--codex-effort"
 
 export interface Ctx {
   readonly repoDir: string
@@ -31,7 +38,12 @@ export interface Ctx {
   claudePermissive: boolean
   claudePlugins: Array<string>
   claudeModel: string
+  claudeEffort: string
+  claudeAdvisor: string
   codexModel: string
+  codexEffort: string
+  /** Distinguishes an explicitly empty modifier from an option that was not supplied. */
+  modifierFlags?: Set<ModifierFlag>
   /** Injected capability seam (logger/deps/platform) — see services.ts. */
   readonly services: EngineServices
   bunRuntime?: BunRuntimeState
@@ -66,7 +78,11 @@ function makeCtx(services: EngineServices): Ctx {
     claudePermissive: env["CLAUDE_PERMISSIVE"] === "1",
     claudePlugins: (env["CLAUDE_PLUGINS"] ?? "").split(" ").filter((s) => s !== ""),
     claudeModel: env["CLAUDE_MODEL"] ?? "",
+    claudeEffort: "",
+    claudeAdvisor: "",
     codexModel: env["CODEX_MODEL"] ?? "",
+    codexEffort: "",
+    modifierFlags: new Set(),
     services,
     targetFilterSet: false,
     syncClaude: false,
@@ -79,7 +95,7 @@ function makeCtx(services: EngineServices): Ctx {
 function engineSync(ctx: Ctx, args: ReadonlyArray<string>): number {
   const { echo } = ctx.services.logger
   parseArgs(ctx, args)
-  validateModelFlags(ctx)
+  validateModifierFlags(ctx)
 
   const claudeRan = ctx.syncClaude
   const claudeRuntime = claudeRan ? claudeSync(ctx) : undefined

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

@@ -6,7 +6,7 @@ import { p } from "./exec"
 import { readFileSync } from "node:fs"
 import { payloadText } from "../payload"
 
-import { syncClaudeModel } from "./claudeModel"
+import { syncClaudeModel } from "./claudeSettingsModifiers"
 import { syncCodexModel } from "./codexToml"
 import type { Ctx } from "./index"
 import { isObject, parseJson, type Json } from "./jq"

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

@@ -4,7 +4,17 @@
  * early parser exit and is caught once in runEngineNative.
  */
 
-import type { Ctx } from "./index"
+import type { Ctx, ModifierFlag } from "./index"
+import {
+  CLAUDE_ADVISOR_STATES,
+  advisorCatalog,
+  advisorFlagGrammar,
+  advisorValueGrammar,
+  effortCatalog,
+  effortFlagGrammar,
+  effortValueGrammar,
+  isEffortModifierValue
+} from "../efforts"
 import { printModels, validateClaudeModel, validateCodexModel } from "./models"
 
 export class ExitError extends Error {
@@ -14,6 +24,13 @@ export class ExitError extends Error {
 }
 
 const KNOWN_CLAUDE_OPTIN_PLUGINS = ["supabase", "n8n"]
+const MODIFIER_FLAGS = new Set<ModifierFlag>([
+  "--claude-model",
+  "--claude-effort",
+  "--claude-advisor",
+  "--codex-model",
+  "--codex-effort"
+])
 
 function usage(ctx: Ctx): void {
   const { echo } = ctx.services.logger
@@ -41,6 +58,8 @@ function usage(ctx: Ctx): void {
   echo(
     "  --claude-model=<m>            set deployed ~/.claude/settings.json model (aliases: best|opus|fable|sonnet|haiku, full claude-* IDs, or 'default' to unset)"
   )
+  echo(`  ${effortFlagGrammar("claude").padEnd(39)} set deployed effortLevel`)
+  echo(`  ${advisorFlagGrammar().padEnd(39)} set deployed advisor state`)
   echo(
     "  --claude-compact-window=<n>   set deployed autocompact window in tokens (e.g. 680000 or 680k) for disposable sessions"
   )
@@ -48,6 +67,7 @@ function usage(ctx: Ctx): void {
     "  --claude-permissive           empty permissions.ask/deny in deployed settings (sandboxes/containers; unattended commits + pushes)"
   )
   echo("  --codex-model=<m>             set deployed ~/.codex/config.toml model (e.g. gpt-5.5)")
+  echo(`  ${effortFlagGrammar("codex").padEnd(39)} set deployed model_reasoning_effort`)
   echo("")
   echo("Sticky opt-ins (installed + enabled until --prune)")
   echo(
@@ -81,9 +101,42 @@ function selectTarget(ctx: Ctx, target: string): void {
   ctx.targetFilterSet = true
 }
 
+function setModifier(ctx: Ctx, flag: ModifierFlag, value: string): void {
+  switch (flag) {
+    case "--claude-model":
+      ctx.claudeModel = value
+      break
+    case "--claude-effort":
+      ctx.claudeEffort = value
+      break
+    case "--claude-advisor":
+      ctx.claudeAdvisor = value
+      break
+    case "--codex-model":
+      ctx.codexModel = value
+      break
+    case "--codex-effort":
+      ctx.codexEffort = value
+      break
+  }
+  const flags = ctx.modifierFlags ?? new Set<ModifierFlag>()
+  flags.add(flag)
+  ctx.modifierFlags = flags
+}
+
+function isModifierFlag(value: string): value is ModifierFlag {
+  return MODIFIER_FLAGS.has(value as ModifierFlag)
+}
+
 export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
   const { err } = ctx.services.logger
-  for (const arg of args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] ?? ""
+    if (isModifierFlag(arg) && args[index + 1] === "") {
+      setModifier(ctx, arg, "")
+      index += 1
+      continue
+    }
     switch (arg) {
       case "claude":
       case "codex":
@@ -116,6 +169,18 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
         printModels(ctx, "codex")
         err("--codex-model requires a value: --codex-model=<model>")
         throw new ExitError(2)
+      case "--claude-effort":
+        printCatalog(ctx, effortCatalog("claude"))
+        err(`--claude-effort requires a value: ${effortFlagGrammar("claude")}`)
+        throw new ExitError(2)
+      case "--codex-effort":
+        printCatalog(ctx, effortCatalog("codex"))
+        err(`--codex-effort requires a value: ${effortFlagGrammar("codex")}`)
+        throw new ExitError(2)
+      case "--claude-advisor":
+        printCatalog(ctx, advisorCatalog())
+        err(`--claude-advisor requires a value: ${advisorFlagGrammar()}`)
+        throw new ExitError(2)
       case "--claude-compact-window":
         err("--claude-compact-window requires a value: --claude-compact-window=<tokens> (e.g. 680k)")
         throw new ExitError(2)
@@ -159,9 +224,15 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
         break
     }
     if (arg.startsWith("--claude-model=")) {
-      ctx.claudeModel = arg.slice("--claude-model=".length)
+      setModifier(ctx, "--claude-model", arg.slice("--claude-model=".length))
     } else if (arg.startsWith("--codex-model=")) {
-      ctx.codexModel = arg.slice("--codex-model=".length)
+      setModifier(ctx, "--codex-model", arg.slice("--codex-model=".length))
+    } else if (arg.startsWith("--claude-effort=")) {
+      setModifier(ctx, "--claude-effort", arg.slice("--claude-effort=".length))
+    } else if (arg.startsWith("--codex-effort=")) {
+      setModifier(ctx, "--codex-effort", arg.slice("--codex-effort=".length))
+    } else if (arg.startsWith("--claude-advisor=")) {
+      setModifier(ctx, "--claude-advisor", arg.slice("--claude-advisor=".length))
     } else if (arg.startsWith("--claude-compact-window=")) {
       const parsed = parseCompactWindow(arg.slice("--claude-compact-window=".length))
       if (parsed === undefined) {
@@ -184,9 +255,15 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
   }
 }
 
-export function validateModelFlags(ctx: Ctx): void {
+function printCatalog(ctx: Ctx, catalog: string): void {
+  for (const line of catalog.split("\n")) ctx.services.logger.echo(line)
+}
+
+export function validateModifierFlags(ctx: Ctx): void {
   const { err, warn } = ctx.services.logger
-  if (ctx.claudeModel !== "") {
+  const supplied = (flag: ModifierFlag, value: string): boolean =>
+    value !== "" || ctx.modifierFlags?.has(flag) === true
+  if (supplied("--claude-model", ctx.claudeModel)) {
     if (!ctx.syncClaude) {
       warn("--claude-model ignored: claude target not selected")
       ctx.claudeModel = ""
@@ -196,7 +273,27 @@ export function validateModelFlags(ctx: Ctx): void {
       throw new ExitError(2)
     }
   }
-  if (ctx.codexModel !== "") {
+  if (supplied("--claude-effort", ctx.claudeEffort)) {
+    if (!ctx.syncClaude) {
+      warn("--claude-effort ignored: claude target not selected")
+      ctx.claudeEffort = ""
+    } else if (!isEffortModifierValue("claude", ctx.claudeEffort)) {
+      printCatalog(ctx, effortCatalog("claude"))
+      err(`Invalid Claude effort '${ctx.claudeEffort}' — valid: ${effortValueGrammar("claude")}`)
+      throw new ExitError(2)
+    }
+  }
+  if (supplied("--claude-advisor", ctx.claudeAdvisor)) {
+    if (!ctx.syncClaude) {
+      warn("--claude-advisor ignored: claude target not selected")
+      ctx.claudeAdvisor = ""
+    } else if (!CLAUDE_ADVISOR_STATES.some((state) => state === ctx.claudeAdvisor)) {
+      printCatalog(ctx, advisorCatalog())
+      err(`Invalid Claude advisor state '${ctx.claudeAdvisor}' — valid: ${advisorValueGrammar()}`)
+      throw new ExitError(2)
+    }
+  }
+  if (supplied("--codex-model", ctx.codexModel)) {
     if (!ctx.syncCodex) {
       warn("--codex-model ignored: codex target not selected")
       ctx.codexModel = ""
@@ -206,4 +303,14 @@ export function validateModelFlags(ctx: Ctx): void {
       throw new ExitError(2)
     }
   }
+  if (supplied("--codex-effort", ctx.codexEffort)) {
+    if (!ctx.syncCodex) {
+      warn("--codex-effort ignored: codex target not selected")
+      ctx.codexEffort = ""
+    } else if (!isEffortModifierValue("codex", ctx.codexEffort)) {
+      printCatalog(ctx, effortCatalog("codex"))
+      err(`Invalid Codex effort '${ctx.codexEffort}' — valid: ${effortValueGrammar("codex")}`)
+      throw new ExitError(2)
+    }
+  }
 }

package/cli/src/generated/sotPayload.ts

@@ -1,13 +1,15 @@
 // Generated by cli/scripts/generate-sot-payload.ts. DO NOT EDIT.
-// Edit SoT/ or notification.mp3, then run: bun cli/scripts/generate-sot-payload.ts
+// Edit SoT/, notification.mp3, or package.json, then run: bun cli/scripts/generate-sot-payload.ts
+
+export const GENERATED_PACKAGE_VERSION = "0.5.0"
 
 export const GENERATED_PAYLOAD_TEXT = {
   "SoT/.agents/skills.txt": "# Universal AI-agent skills (agentskills.io standard).\n# Bootstrapped to ~/.agents/skills/ by cli/src/engine-native/skillsSync.ts during ./docks-kit sync.\n# One slug per line: <owner>/<repo>. Lines starting with # are comments.\n# Each skill's canonical SKILL.md lands in ~/.agents/skills/<name>/ — Codex\n# reads that path natively; Claude Code gets a ~/.claude/skills/<name>\n# symlink to it. The skills sync names both agents the kit supports\n# (-a claude-code codex) so the CLI keeps the shared canonical copy.\n\n# Browser automation CLI — reaches JS-rendered, auth-walled, login-gated pages\n# (x.com, LinkedIn, Confluence) that built-in WebFetch can't. The skills sync\n# auto-installs the `agent-browser` npm package + downloads Chrome for Testing\n# (~175 MB) on first sync; Linux runs `agent-browser install --with-deps` which\n# may prompt for sudo to install system libs (libnss3, libatk, ...).\nvercel-labs/agent-browser\n",
-  "SoT/models.json": "{\n  \"$comment\": \"Kit-verified model catalog — single source for EngineNative validators, the docks-kit CLI (models/model commands, pickers, bare-flag help), and docs. Entries are research-proofed: update an entry and its tool-level `verified` date when a model ships or retires. The catalog informs, it doesn't imprison: well-formed IDs outside it (claude-* / codex charset) apply with a warning.\",\n  \"claude\": {\n    \"verified\": \"2026-07-08\",\n    \"models\": [\n      { \"id\": \"best\", \"kind\": \"alias\", \"note\": \"Fable 5 where the org has access, latest Opus otherwise (Claude Code >=2.1.170)\" },\n      { \"id\": \"opus\", \"kind\": \"alias\", \"note\": \"latest Opus (currently Opus 4.8) — the kit SoT default, paired with the fable advisor\" },\n      { \"id\": \"fable\", \"kind\": \"alias\", \"note\": \"Fable 5 — needs org access + Claude Code >=2.1.170\" },\n      { \"id\": \"sonnet\", \"kind\": \"alias\", \"note\": \"latest Sonnet (currently Sonnet 5)\" },\n      { \"id\": \"haiku\", \"kind\": \"alias\", \"note\": \"latest Haiku (currently Haiku 4.5)\" },\n      { \"id\": \"default\", \"kind\": \"alias\", \"note\": \"engine pseudo-value: deletes the deployed model key so the account default applies\" },\n      { \"id\": \"claude-fable-5\", \"kind\": \"id\", \"note\": \"Fable 5\" },\n      { \"id\": \"claude-opus-4-8\", \"kind\": \"id\", \"note\": \"Opus 4.8\" },\n      { \"id\": \"claude-sonnet-5\", \"kind\": \"id\", \"note\": \"Sonnet 5\" },\n      { \"id\": \"claude-haiku-4-5-20251001\", \"kind\": \"id\", \"note\": \"Haiku 4.5\" }\n    ]\n  },\n  \"codex\": {\n    \"verified\": \"2026-07-09\",\n    \"models\": [\n      { \"id\": \"gpt-5.6-sol\", \"kind\": \"id\", \"note\": \"GPT-5.6 Sol — frontier, recommended default; the kit SoT pin\" },\n      { \"id\": \"gpt-5.6-terra\", \"kind\": \"id\", \"note\": \"GPT-5.6 Terra — balanced tier\" },\n      { \"id\": \"gpt-5.6-luna\", \"kind\": \"id\", \"note\": \"GPT-5.6 Luna — fast/light tier\" },\n      { \"id\": \"gpt-5.5\", \"kind\": \"id\", \"note\": \"previous generation\" },\n      { \"id\": \"gpt-5.5-codex\", \"kind\": \"id\", \"note\": \"codex-tuned gpt-5.5\" },\n      { \"id\": \"gpt-5.1\", \"kind\": \"id\", \"note\": \"previous generation\" },\n      { \"id\": \"gpt-5\", \"kind\": \"id\", \"note\": \"previous generation\" },\n      { \"id\": \"gpt-5-codex\", \"kind\": \"id\", \"note\": \"codex-tuned gpt-5\" }\n    ]\n  }\n}\n",
+  "SoT/models.json": "{\n  \"$comment\": \"Kit-verified model catalog — single source for EngineNative validators, the docks-kit CLI (models/model commands, pickers, bare-flag help), and docs. Entries are research-proofed: update an entry and its tool-level `verified` date when a model ships or retires. The catalog informs, it doesn't imprison: well-formed IDs outside it (claude-* / codex charset) apply with a warning.\",\n  \"claude\": {\n    \"verified\": \"2026-07-08\",\n    \"models\": [\n      { \"id\": \"best\", \"kind\": \"alias\", \"note\": \"Fable 5 where the org has access, latest Opus otherwise (Claude Code >=2.1.170)\" },\n      { \"id\": \"opus\", \"kind\": \"alias\", \"note\": \"latest Opus (currently Opus 4.8)\" },\n      { \"id\": \"fable\", \"kind\": \"alias\", \"note\": \"Fable 5 — the kit SoT default; needs org access + Claude Code >=2.1.170\" },\n      { \"id\": \"sonnet\", \"kind\": \"alias\", \"note\": \"latest Sonnet (currently Sonnet 5)\" },\n      { \"id\": \"haiku\", \"kind\": \"alias\", \"note\": \"latest Haiku (currently Haiku 4.5)\" },\n      { \"id\": \"default\", \"kind\": \"alias\", \"note\": \"engine pseudo-value: deletes the deployed model key so the account default applies\" },\n      { \"id\": \"claude-fable-5\", \"kind\": \"id\", \"note\": \"Fable 5\" },\n      { \"id\": \"claude-opus-4-8\", \"kind\": \"id\", \"note\": \"Opus 4.8\" },\n      { \"id\": \"claude-sonnet-5\", \"kind\": \"id\", \"note\": \"Sonnet 5\" },\n      { \"id\": \"claude-haiku-4-5-20251001\", \"kind\": \"id\", \"note\": \"Haiku 4.5\" }\n    ]\n  },\n  \"codex\": {\n    \"verified\": \"2026-07-09\",\n    \"models\": [\n      { \"id\": \"gpt-5.6-sol\", \"kind\": \"id\", \"note\": \"GPT-5.6 Sol — frontier, recommended default; the kit SoT pin\" },\n      { \"id\": \"gpt-5.6-terra\", \"kind\": \"id\", \"note\": \"GPT-5.6 Terra — balanced tier\" },\n      { \"id\": \"gpt-5.6-luna\", \"kind\": \"id\", \"note\": \"GPT-5.6 Luna — fast/light tier\" },\n      { \"id\": \"gpt-5.5\", \"kind\": \"id\", \"note\": \"previous generation\" },\n      { \"id\": \"gpt-5.5-codex\", \"kind\": \"id\", \"note\": \"codex-tuned gpt-5.5\" },\n      { \"id\": \"gpt-5.1\", \"kind\": \"id\", \"note\": \"previous generation\" },\n      { \"id\": \"gpt-5\", \"kind\": \"id\", \"note\": \"previous generation\" },\n      { \"id\": \"gpt-5-codex\", \"kind\": \"id\", \"note\": \"codex-tuned gpt-5\" }\n    ]\n  }\n}\n",
   "SoT/toolchain.json": "{\n  \"$comment\": \"Kit toolchain manifest — DATA only (versions, floors, policy); check/install logic lives in cli/src/engine-native/toolchain.ts with per-surface sync callbacks in cli/src/engine-native/. kind: check (doctor visibility only) | managed (kit installs/upgrades it) | pin (no binary probe — a version pin for a tool the kit invokes via npx). policy (managed only): track (upgrade toward latest, gated by `verified`) | present (install when missing, never upgrade). `verified` = last kit-tested version — anything above it prompts before install (--yes auto-accepts; non-TTY declines and falls back to the pinned `verified` when pinnable). Supply-chain stance: every kit-driven install is pinned to `verified` or gated by it — never floating @latest (npm-worm/Shai-Hulud surface). Update `verified` after testing a new release.\",\n  \"tools\": {\n    \"jq\":     { \"kind\": \"check\", \"note\": \"optional operator CLI; EngineNative JSON and Claude runtime do not invoke it\" },\n    \"curl\":   { \"kind\": \"check\", \"note\": \"contextual POSIX installer transport for RTK/Bun bootstrap\" },\n    \"git\":    { \"kind\": \"check\", \"note\": \"plugin marketplaces (claude/codex clone them) + kit checkout updates\" },\n    \"node\":   { \"kind\": \"check\", \"note\": \"hosts npm globals (agent-browser, LSP servers)\" },\n    \"npm\":    { \"kind\": \"check\", \"note\": \"npm-global installer\" },\n    \"claude\": { \"kind\": \"check\", \"floor\": \"2.1.170\", \"note\": \"kit floor — `best` alias + Fable 5 need >=2.1.170 (mirrors settings minimumVersion)\" },\n    \"codex\":  { \"kind\": \"check\", \"note\": \"upstream-owned; standalone installer prints when missing\" },\n    \"ffplay\": { \"kind\": \"check\", \"note\": \"Notification hook sound (previously unchecked)\" },\n    \"bwrap\":  { \"kind\": \"check\", \"os\": \"linux\", \"note\": \"Codex Linux sandbox runtime\" },\n    \"intelephense\": { \"kind\": \"check\", \"verified\": \"1.18.5\", \"note\": \"php-lsp server binary; `verified` pins claude::sync_lsp_servers' npm install\" },\n    \"typescript-language-server\": { \"kind\": \"check\", \"verified\": \"5.3.0\", \"note\": \"typescript-lsp server binary; `verified` pins claude::sync_lsp_servers' npm install\" },\n    \"tsc\":    { \"kind\": \"check\", \"verified\": \"6.0.3\", \"note\": \"typescript-lsp dependency (npm package `typescript`); `verified` pins claude::sync_lsp_servers' npm install. Deliberately on the 6.x line: typescript-language-server embeds TypeScript's programmatic API, which TS7 (native) doesn't yet expose — the repo's own devDependency runs TS7 for tsc --noEmit\" },\n    \"rtk\":    { \"kind\": \"managed\", \"policy\": \"track\", \"floor\": \"0.43.0\", \"verified\": \"0.43.0\", \"pinnable\": true,\n                \"note\": \"PreToolUse hook — supply-chain review before unverified upgrades; installer honors RTK_VERSION=vX.Y.Z pin\" },\n    \"bun\":    { \"kind\": \"managed\", \"policy\": \"present\", \"verified\": \"1.3.14\", \"pinnable\": true,\n                \"note\": \"runtime for effect-solutions + the docks-kit CLI; bootstrap installs the verified release (installer takes bun-vX.Y.Z); self-updates via `bun upgrade` when wanted\" },\n    \"effect-solutions\": { \"kind\": \"managed\", \"policy\": \"track\", \"verified\": \"0.5.3\", \"pinnable\": true,\n                \"note\": \"Effect docs CLI (bun global) — track keeps it self-upgrading, gated by the verified pin\" },\n    \"agent-browser\":    { \"kind\": \"managed\", \"policy\": \"track\", \"verified\": \"0.31.1\", \"pinnable\": true,\n                \"note\": \"browser-automation CLI (npm global), gated by the verified pin; first install also downloads Chrome for Testing\" },\n    \"skills-cli\": { \"kind\": \"pin\", \"verified\": \"1.5.15\",\n                \"note\": \"the `skills` npm package the kit runs via `npx skills@<verified>` on every agents sync (universal-skill install/remove) — pinned, never @latest\" }\n  }\n}\n",
-  "SoT/.claude/CLAUDE.md": "@RTK.md\n\n## Research Before Implementation\n\nBefore writing or modifying code that uses an API, hook, method, or config surface you have not verified in this session, research current documentation first.\n\n**Research workflow:**\n1. Use `resolve-library-id` → `query-docs` (context7) to fetch up-to-date docs for the specific library/framework\n2. If context7 doesn't cover it, read the official docs with `agent-browser` (it reaches JS-rendered, auth-walled, and login-gated pages); fall back to `WebFetch` for a simple static page\n3. Only then proceed to implementation\n\n**When to research:**\n- Installing or configuring a dependency\n- Using an API, hook, method, or pattern you haven't verified in this session\n- Upgrading or migrating between versions\n- Any task where you'd otherwise rely on training data for syntax/behavior\n\n**Do NOT:**\n- Assume API signatures, method names, or config options from memory\n- Generate framework code without checking current docs first\n- Skip research because the library \"seems familiar\"\n\n<constraint>\nResearch the codebase before editing. Never change code you haven't read.\n</constraint>\n\n## Agentic Harness Heuristics\n\n**1. Persistence.** Keep going until the user's query is completely resolved. Only yield when sure the problem is solved. Before ending a turn, check the last paragraph: if it is a plan, a question you can answer yourself, or a promise of work not done (\"I'll…\"), do that work now.\n\n**2. Default to parallel.** Whenever you have multiple independent operations (reads, greps, web fetches, independent edits), invoke them in a single response with multiple tool-use blocks. Sequential calls only when output of one operation is required as input to the next.\n\n**3. Multi-pass search.** First-pass search often misses — vary the wording (colleague-questions over keywords) before concluding something doesn't exist.\n\n**4. Trace symbols.** Before modifying a symbol, trace it to its definitions and all usages. Don't assume a function's behavior or a type's shape from the call site alone.\n\n**5. Linter-loop 3-strike rule.** Don't loop more than 3 times fixing linter errors on the same file. On the third attempt, stop and ask the user — repeated failure usually means the diagnosis is wrong, not the code.\n\n**6. Read-before-Edit TTL.** If you haven't read a file with the Read tool in the last ~5 messages, re-read it before editing. Cached file content goes stale silently when the user edits between turns.\n\n**7. Big-file rule.** For files >1000 lines, prefer Grep + scoped Read (`offset` + `limit`) over reading the entire file. Whole-file reads bloat context; targeted reads keep the working set small.\n\n**8. Todo hygiene.** Use TaskCreate for items with meaningful outcome (≥5 min, distinct deliverable). Never include operational sub-actions (linting, testing, searching, examining the codebase) as their own todos — those are sub-steps in service of higher-level tasks. Mark complete immediately when done, never in batches.\n\n**9. Literal-instruction rule.** Current frontier models follow instructions literally — they do not silently generalize from intent. Phrase requirements as explicit checklists with success criteria, not narrative.\n\n**10. Context hygiene.** Prefer `/clear` at task boundaries and `/rewind` for wrong-path detours over carrying rot forward (corrections accumulate noise; rewinds preserve the prefix and discard the bad branch). On a continuing task, run `/compact` with steering before context quality degrades. Never stop, summarize, or suggest a new session on account of context limits.\n\n**11. Autonomy calibration.** For minor choices (naming, formatting, default values, which of two equivalent approaches), pick a reasonable option and note it — don't ask. Ask first only for scope changes, destructive actions, or decisions that change the deliverable. When the user is describing a problem or asking a question rather than requesting a change, the deliverable is your assessment — report findings and stop; don't apply fixes until asked. Don't close a finished task with \"Want me to also…?\" — run the obvious verification, then stop cleanly.\n\n**12. Capability triggering.** When the answer depends on current or version-specific information, search or fetch before answering — never answer from memory. When work fans out across independent items (many files to read, many tests to run, many candidates to check), delegate to parallel subagents; never spawn one for work you can complete directly. For verification, prefer a fresh-context subagent over self-critique. On tasks longer than a few turns, keep a running notes file and re-read it before each phase.\n\n<constraint>\nTreat the 12 heuristics above as protocol, not preference. If a turn ends without honoring an applicable one (e.g., lint-loop guard not respected, edit without re-read), self-correct in the next turn before continuing.\n</constraint>\n\n## Project Skills\n\nProjects may have a `.claude/skills/` directory with Tool Wrapper skills managed by `/docs`. Claude Code auto-discovers these at session start — only descriptions are loaded, full content loads on demand via the Skill tool.\n\nSkills follow the [agentskills.io](https://agentskills.io) open standard:\n- **SKILL.md**: frontmatter (`name`, `description`, `user-invocable: false`, `metadata`) + body (≤500 lines)\n- **references/**: on-demand detail files (30-150 lines each), loaded when the skill instructs Claude to read them\n- **Discovery**: Claude Code scans `.claude/skills/*/SKILL.md` at session start, loads only `name` + `description` (~100 tokens per skill)\n- **Triggering**: Claude semantically matches descriptions against user tasks, invokes via `Skill` tool — no `@import` or pointer tables needed\n- **CSO (Claude Search Optimization)**: descriptions MUST start with \"Use when...\" and describe trigger conditions, not capabilities\n- **Third-party / vendored skills**: add an `upstream:` frontmatter block (`source`, `license`, `vendored_at: \"YYYY-MM-DD\"`) when vendoring a skill from an external repo. The block marks the skill as vendored so kit-specific checks (CSO start-prefix, `user-invocable`, `metadata.updated`) are relaxed and the skill's body is preserved verbatim from upstream. Universal structural checks (fenced frontmatter, name matches directory, description length, 500-line body cap) still apply.\n\n<constraint>\nAfter any code change affecting documented patterns, update the relevant skill in `.claude/skills/` and its `metadata.updated` frontmatter field. When introducing something new, create a skill or add a `references/` file to an existing skill.\n</constraint>\n\n## Project Agents\n\nProjects and the global kit may have a `.claude/agents/` directory containing subagent definitions. Each agent file declares its `model` (`sonnet`/`opus`/`haiku`/`inherit`/full model ID), `tools`, and system prompt. Claude Code auto-discovers them at session start and delegates when a `subagent_type` matches or when a slash command explicitly invokes them.\n\nAgent files follow this structure:\n- **Frontmatter**: `name` (kebab-case, matches filename), `description` (CSO — starts \"Use when…\" with a \"Not for…\" exclusion clause), `tools`, `model`\n- **Body** (≤500 lines): `<constraint>` blocks for non-negotiable rules, `## Workflow` with context-acknowledgment as step 1, `## Output Format`, `## Anti-Hallucination Checks`, `## Success Criteria`\n- **Model-selection resolution** (per Claude Code docs): `CLAUDE_CODE_SUBAGENT_MODEL` env var → per-invocation `model` param → agent frontmatter `model:` → parent conversation. The env var is NOT set in this kit, so per-agent frontmatter controls selection.\n\n<constraint>\nWhen adding a new agent: use kebab-case name matching filename, CSO-compliant description (starts \"Use when…\", contains a \"Not\" exclusion clause), explicit `model` and `tools`.\n</constraint>\n\n## Picking the right models for workflows and subagents\n\nRankings, higher = better. Intelligence is how hard a problem the model can be handed unsupervised. Taste covers UI/UX, code quality, API design, and copy. Cost is relative spend — a tie-breaker only.\n\n| model    | cost | intelligence | taste |\n|----------|------|--------------|-------|\n| gpt-5.5  | 9    | 8            | 5     |\n| opus-4.8 | 4    | 7            | 8     |\n| sonnet-5 | 5    | 5            | 7     |\n\nFable 5 outranks all three on intelligence and taste, but its limits are spent for now — treat opus-4.8 as the ceiling until Fable access returns, then Fable takes the top intelligence+taste slot.\n\nHow to apply:\n- These are defaults, not limits. Standing permission to override: if a cheaper model's output misses the bar, rerun with a smarter one without asking. Judge the output, not the price tag — escalating costs less than shipping mediocre work.\n- Cost is a tie-breaker only; when axes conflict for anything that ships, intelligence > taste > cost.\n- Bulk/mechanical work (clear-spec implementation, data analysis, migrations): gpt-5.5.\n- Anything user-facing (UI, copy, API design) needs taste ≥ 7 → opus-4.8 (sonnet-5 when Opus is saturated).\n- Reviews of plans/implementations: opus-4.8, optionally gpt-5.5 as a second independent perspective.\n- Never use Haiku.\n- gpt-5.5 is reachable only through the Codex CLI (`~/.codex/config.toml` defaults to gpt-5.5): `codex exec` for headless implementation/analysis, `codex review` for diff review, `codex exec -s read-only` with a self-contained prompt for ad-hoc investigation, UI verification, or data analysis. Codex is more efficient than Claude on well-specced execution and stronger at computer-use and UI/UX verification — offload those and report results back.\n- Claude models run via the Agent/Workflow `model` parameter (`opus`, `sonnet`).\n\nUsing gpt-5.5 inside workflows and subagents (the `model` parameter takes only Claude models, so wrap it):\n- Spawn a thin Claude wrapper agent with `model: 'sonnet', effort: 'low'` whose prompt tells it to write a self-contained Codex prompt, run `codex exec` via Bash, and return Codex's output verbatim. The wrapper only shuttles the prompt and result — gpt-5.5 does the work.\n\nReaching gpt-5.5 (or a full-context worker in another project) as a persistent session — the `session-relay` skill (shared bus + `relay` CLI, Claude ⇄ Codex):\n- `codex exec` is one-shot and stateless. When the offload must be resumable, span several turns, or run in another project with that project's own config, spawn a real session instead: `relay spawn <dir> --tool codex --model gpt-5.5 --effort xhigh` (or `--tool claude --model opus` for a Claude worker), then continue it with `send` / `wake`.\n- Two independent perspectives on a plan = the red-team pair spawn: a gpt-5.5 worker and an opus worker debate over the bus, orchestrator writes the verdict — the concrete form of the \"second independent perspective\" review above.\n- Pin `--model`/`--effort` on every spawn/wake; never leave an unattended relay child on a top interactive default (e.g. Fable). Each spawn/wake bills the target's subscription — spawn deliberately, never in loops.\n\n## Agentic Engineering Discipline\n\n1. **State assumptions; push back when warranted.** If a requirement is ambiguous in a way that changes the deliverable, surface the ambiguity and propose 1–2 concrete interpretations in your first message — do not silently pick one and run with it. Surface inconsistencies and confusion instead of guessing past them; present tradeoffs when approaches genuinely differ; push back when the request looks wrong. Agreeable-but-wrong is the failure mode, not disagreement.\n2. **Minimum code that solves the stated problem.** Each named pattern below is a defect — catch it during generation, not after:\n\n   **Code slop**\n   - **Defensive guards** around internally-trusted calls (`try`, `if x != null`). Validate at system boundaries only.\n   - **Speculative abstraction.** No helper for one caller; no interface for one implementer. Three similar lines beats premature DRY.\n   - **Backwards-compat shims** without a caller — re-exports, deprecation aliases, untoggled feature flags. Just change the code.\n   - **Half-finished stubs.** `TODO handle later`, `throw new Error('not implemented')`. Implement or remove the path.\n   - **Underscore-rename of unused vars.** Delete the var.\n   - **Dead code left behind.** After a refactor, delete the paths, helpers, and imports the change made unreachable.\n\n   **Comment slop**\n   - **Restate-the-code.** `// increment i`. The identifier already says it.\n   - **Provenance.** `// added for ticket X`, `// used by Y`. Belongs in the PR description; rots in code.\n   - **Tombstones.** `// removed Z`, `// previously did W`. Git remembers.\n   - **Docstring bloat** on self-evident functions. One line, only when the WHY isn't obvious from the name.\n\n   **Output slop**\n   - **End-of-turn diff-restatement.** One or two sentences: what changed, what's next. Don't recap what's in the diff.\n   - **Narration tics.** \"Now I'll…\", \"Let me check…\", play-by-play between tool calls. Terse working shorthand between tool calls is fine; play-by-play is not — write a sentence when something load-bearing happens (a finding, a direction change, a blocker).\n   - **Compressed final summaries.** The final message is for a reader who didn't watch the work: outcome first, complete sentences. Shorten by dropping detail, never by compressing into fragments or arrow chains.\n3. **Surgical changes only.** Do not modify code, comments, or formatting outside the explicit scope of the request. Surface unrelated issues as follow-ups — do not fix inline.\n4. **State how success will be verified before implementing.** Name the test, build, smoke check, or diff inspection that will prove the change works. Prefer executable criteria — a test that fails before and passes after, a command with expected output — over judgment calls, and keep each change small enough that its diff is reviewable in one sitting.\n5. **Review scope follows the pipeline.** In pipeline reviews with a downstream filter (multi-agent scans, verification phases), report every issue found with confidence and severity — filtering happens downstream. In ad-hoc reviews, flag only gaps that affect correctness or the stated requirements; treat the rest as optional.\n6. **Ground every progress claim in evidence.** Before reporting progress or completion, audit each claim against a tool result from this session — show the test output, the command and what it returned. If something is unverified, say so explicitly; if tests fail, say so with the output.\n\n<constraint>\nTreat the six rules above as preventive (during generation), not remedial (after the fact). Self-correct if a turn drifts.\n</constraint>\n",
+  "SoT/.claude/CLAUDE.md": "@RTK.md\n\n## Research Before Implementation\n\nBefore writing or modifying code that uses an API, hook, method, or config surface you have not verified in this session, research current documentation first.\n\n**Research workflow:**\n1. Use `resolve-library-id` → `query-docs` (context7) to fetch up-to-date docs for the specific library/framework\n2. If context7 doesn't cover it, read the official docs with `agent-browser` (it reaches JS-rendered, auth-walled, and login-gated pages); fall back to `WebFetch` for a simple static page\n3. Only then proceed to implementation\n\n**When to research:**\n- Installing or configuring a dependency\n- Using an API, hook, method, or pattern you haven't verified in this session\n- Upgrading or migrating between versions\n- Any task where you'd otherwise rely on training data for syntax/behavior\n\n**Do NOT:**\n- Assume API signatures, method names, or config options from memory\n- Generate framework code without checking current docs first\n- Skip research because the library \"seems familiar\"\n\n<constraint>\nResearch the codebase before editing. Never change code you haven't read.\n</constraint>\n\n## Agentic Harness Heuristics\n\n**1. Persistence.** Keep going until the user's query is completely resolved. Only yield when sure the problem is solved. Before ending a turn, check the last paragraph: if it is a plan, a question you can answer yourself, or a promise of work not done (\"I'll…\"), do that work now.\n\n**2. Default to parallel.** Whenever you have multiple independent operations (reads, greps, web fetches, independent edits), invoke them in a single response with multiple tool-use blocks. Sequential calls only when output of one operation is required as input to the next.\n\n**3. Multi-pass search.** First-pass search often misses — vary the wording (colleague-questions over keywords) before concluding something doesn't exist.\n\n**4. Trace symbols.** Before modifying a symbol, trace it to its definitions and all usages. Don't assume a function's behavior or a type's shape from the call site alone.\n\n**5. Linter-loop 3-strike rule.** Don't loop more than 3 times fixing linter errors on the same file. On the third attempt, stop and ask the user — repeated failure usually means the diagnosis is wrong, not the code.\n\n**6. Read-before-Edit TTL.** If you haven't read a file with the Read tool in the last ~5 messages, re-read it before editing. Cached file content goes stale silently when the user edits between turns.\n\n**7. Big-file rule.** For files >1000 lines, prefer Grep + scoped Read (`offset` + `limit`) over reading the entire file. Whole-file reads bloat context; targeted reads keep the working set small.\n\n**8. Todo hygiene.** Use TaskCreate for items with meaningful outcome (≥5 min, distinct deliverable). Never include operational sub-actions (linting, testing, searching, examining the codebase) as their own todos — those are sub-steps in service of higher-level tasks. Mark complete immediately when done, never in batches.\n\n**9. Literal-instruction rule.** Current frontier models follow instructions literally — they do not silently generalize from intent. Phrase requirements as explicit checklists with success criteria, not narrative.\n\n**10. Context hygiene.** Prefer `/clear` at task boundaries and `/rewind` for wrong-path detours over carrying rot forward (corrections accumulate noise; rewinds preserve the prefix and discard the bad branch). On a continuing task, run `/compact` with steering before context quality degrades. Never stop, summarize, or suggest a new session on account of context limits.\n\n**11. Autonomy calibration.** For minor choices (naming, formatting, default values, which of two equivalent approaches), pick a reasonable option and note it — don't ask. Ask first only for scope changes, destructive actions, or decisions that change the deliverable. When the user is describing a problem or asking a question rather than requesting a change, the deliverable is your assessment — report findings and stop; don't apply fixes until asked. Don't close a finished task with \"Want me to also…?\" — run the obvious verification, then stop cleanly.\n\n**12. Capability triggering.** When the answer depends on current or version-specific information, search or fetch before answering — never answer from memory. When work fans out across independent items (many files to read, many tests to run, many candidates to check), delegate to parallel subagents; never spawn one for work you can complete directly. For verification, prefer a fresh-context subagent over self-critique. On tasks longer than a few turns, keep a running notes file and re-read it before each phase.\n\n<constraint>\nTreat the 12 heuristics above as protocol, not preference. If a turn ends without honoring an applicable one (e.g., lint-loop guard not respected, edit without re-read), self-correct in the next turn before continuing.\n</constraint>\n\n## Project Skills\n\nProjects may have a `.claude/skills/` directory with Tool Wrapper skills managed by `/docs`. Claude Code auto-discovers these at session start — only descriptions are loaded, full content loads on demand via the Skill tool.\n\nSkills follow the [agentskills.io](https://agentskills.io) open standard:\n- **SKILL.md**: frontmatter (`name`, `description`, `user-invocable: false`, `metadata`) + body (≤500 lines)\n- **references/**: on-demand detail files (30-150 lines each), loaded when the skill instructs Claude to read them\n- **Discovery**: Claude Code scans `.claude/skills/*/SKILL.md` at session start, loads only `name` + `description` (~100 tokens per skill)\n- **Triggering**: Claude semantically matches descriptions against user tasks, invokes via `Skill` tool — no `@import` or pointer tables needed\n- **CSO (Claude Search Optimization)**: descriptions MUST start with \"Use when...\" and describe trigger conditions, not capabilities\n- **Third-party / vendored skills**: add an `upstream:` frontmatter block (`source`, `license`, `vendored_at: \"YYYY-MM-DD\"`) when vendoring a skill from an external repo. The block marks the skill as vendored so kit-specific checks (CSO start-prefix, `user-invocable`, `metadata.updated`) are relaxed and the skill's body is preserved verbatim from upstream. Universal structural checks (fenced frontmatter, name matches directory, description length, 500-line body cap) still apply.\n\n<constraint>\nAfter any code change affecting documented patterns, update the relevant skill in `.claude/skills/` and its `metadata.updated` frontmatter field. When introducing something new, create a skill or add a `references/` file to an existing skill.\n</constraint>\n\n## Project Agents\n\nProjects and the global kit may have a `.claude/agents/` directory containing subagent definitions. Each agent file declares its `model` (`sonnet`/`opus`/`haiku`/`inherit`/full model ID), `tools`, and system prompt. Claude Code auto-discovers them at session start and delegates when a `subagent_type` matches or when a slash command explicitly invokes them.\n\nAgent files follow this structure:\n- **Frontmatter**: `name` (kebab-case, matches filename), `description` (CSO — starts \"Use when…\" with a \"Not for…\" exclusion clause), `tools`, `model`\n- **Body** (≤500 lines): `<constraint>` blocks for non-negotiable rules, `## Workflow` with context-acknowledgment as step 1, `## Output Format`, `## Anti-Hallucination Checks`, `## Success Criteria`\n- **Model-selection resolution** (per Claude Code docs): `CLAUDE_CODE_SUBAGENT_MODEL` env var → per-invocation `model` param → agent frontmatter `model:` → parent conversation. The env var is NOT set in this kit, so per-agent frontmatter controls selection.\n\n<constraint>\nWhen adding a new agent: use kebab-case name matching filename, CSO-compliant description (starts \"Use when…\", contains a \"Not\" exclusion clause), explicit `model` and `tools`.\n</constraint>\n\n## Picking the right models for workflows and subagents\n\nRankings, all scores 10 = best. Intelligence is how hard a problem the model can be handed unsupervised. Taste covers UI/UX, code quality, API design, and copy. Budget fit is marginal spend plus quota headroom — a tie-breaker only.\n\n| model       | budget fit | intelligence | taste |\n|-------------|------------|--------------|-------|\n| gpt-5.6-sol | 9          | 10           | 6     |\n| fable-5     | 3          | 9            | 9     |\n| opus-4.8    | 5          | 7            | 8     |\n| sonnet-5    | 7          | 5            | 7     |\n\nCapacity: Sol has abundant subscription headroom; Fable is scarce; Opus is moderate; Sonnet is economical. gpt-5.6-sol holds the top intelligence slot — it is the default implementer for plan-sized work. Fable 5 (available again; the kit's Claude default) holds the top taste slot and is the orchestrator/interactive tier, not a bulk executor.\n\nHow to apply:\n- These are defaults, not limits. Standing permission to override: if a cheaper model's output misses the bar, rerun with a smarter one without asking. Judge the output, not the price tag — escalating costs less than shipping mediocre work.\n- Budget fit is a tie-breaker only; when axes conflict for anything that ships, intelligence > taste > budget fit.\n- Implementation of plans, and bulk/mechanical work (clear-spec implementation, data analysis, migrations): gpt-5.6-sol.\n- Anything user-facing (UI, copy, API design) needs taste ≥ 7 → fable-5 or opus-4.8 (sonnet-5 when both are saturated).\n- Reviews of plans/implementations: gpt-5.6-sol, optionally the best available Claude — fable-5 when access allows, opus-4.8 otherwise — as a second independent perspective.\n- Never use Haiku.\n- Claude models run via the Agent/Workflow `model` parameter (`opus`, `sonnet`, `fable` where org access allows).\n\nReaching gpt-5.6-sol — always through the `session-relay` skill (shared bus + `relay` CLI, Claude ⇄ Codex), even for one-shots, so every exchange stays resumable:\n- `relay spawn <dir> --tool codex --model gpt-5.6-sol --effort xhigh` (or `--tool claude --model opus` for a Claude worker in another project), then continue it with `send` / `wake`. Codex runs on its own CLI (`~/.codex/config.toml` defaults to gpt-5.6-sol) and is more efficient than Claude on well-specced execution and stronger at computer-use and UI/UX verification — offload those and report results back.\n- An independent fresh-context review = a NEW spawn (fresh spawn is fresh context). Two independent perspectives on a plan = the red-team pair spawn: a gpt-5.6-sol worker and an opus worker debate over the bus, orchestrator writes the verdict — the concrete form of the \"second independent perspective\" review above.\n- Pin `--model`/`--effort` on every spawn/wake; never leave an unattended relay child on a top interactive default (e.g. Fable). Each spawn/wake bills the target's subscription — spawn deliberately, never in loops.\n\n## Agentic Engineering Discipline\n\n1. **State assumptions; push back when warranted.** If a requirement is ambiguous in a way that changes the deliverable, surface the ambiguity and propose 1–2 concrete interpretations in your first message — do not silently pick one and run with it. Surface inconsistencies and confusion instead of guessing past them; present tradeoffs when approaches genuinely differ; push back when the request looks wrong. Agreeable-but-wrong is the failure mode, not disagreement.\n2. **Minimum code that solves the stated problem.** Each named pattern below is a defect — catch it during generation, not after:\n\n   **Code slop**\n   - **Defensive guards** around internally-trusted calls (`try`, `if x != null`). Validate at system boundaries only.\n   - **Speculative abstraction.** No helper for one caller; no interface for one implementer. Three similar lines beats premature DRY.\n   - **Backwards-compat shims** without a caller — re-exports, deprecation aliases, untoggled feature flags. Just change the code.\n   - **Half-finished stubs.** `TODO handle later`, `throw new Error('not implemented')`. Implement or remove the path.\n   - **Underscore-rename of unused vars.** Delete the var.\n   - **Dead code left behind.** After a refactor, delete the paths, helpers, and imports the change made unreachable.\n\n   **Comment slop**\n   - **Restate-the-code.** `// increment i`. The identifier already says it.\n   - **Provenance.** `// added for ticket X`, `// used by Y`. Belongs in the PR description; rots in code.\n   - **Tombstones.** `// removed Z`, `// previously did W`. Git remembers.\n   - **Docstring bloat** on self-evident functions. One line, only when the WHY isn't obvious from the name.\n\n   **Output slop**\n   - **End-of-turn diff-restatement.** One or two sentences: what changed, what's next. Don't recap what's in the diff.\n   - **Narration tics.** \"Now I'll…\", \"Let me check…\", play-by-play between tool calls. Terse working shorthand between tool calls is fine; play-by-play is not — write a sentence when something load-bearing happens (a finding, a direction change, a blocker).\n   - **Compressed final summaries.** The final message is for a reader who didn't watch the work: outcome first, complete sentences. Shorten by dropping detail, never by compressing into fragments or arrow chains.\n3. **Surgical changes only.** Do not modify code, comments, or formatting outside the explicit scope of the request. Surface unrelated issues as follow-ups — do not fix inline.\n4. **State how success will be verified before implementing.** Name the test, build, smoke check, or diff inspection that will prove the change works. Prefer executable criteria — a test that fails before and passes after, a command with expected output — over judgment calls, and keep each change small enough that its diff is reviewable in one sitting.\n5. **Review scope follows the pipeline.** In pipeline reviews with a downstream filter (multi-agent scans, verification phases), report every issue found with confidence and severity — filtering happens downstream. In ad-hoc reviews, flag only gaps that affect correctness or the stated requirements; treat the rest as optional.\n6. **Ground every progress claim in evidence.** Before reporting progress or completion, audit each claim against a tool result from this session — show the test output, the command and what it returned. If something is unverified, say so explicitly; if tests fail, say so with the output.\n\n<constraint>\nTreat the six rules above as preventive (during generation), not remedial (after the fact). Self-correct if a turn drifts.\n</constraint>\n",
   "SoT/.claude/mcp-servers.json": "{\n  \"mcpServers\": {\n    \"chrome-devtools\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"chrome-devtools-mcp@1.5.0\"],\n      \"env\": {}\n    }\n  }\n}\n",
-  "SoT/.claude/settings.json": "{\n  \"$schema\": \"https://json.schemastore.org/claude-code-settings.json\",\n  \"minimumVersion\": \"2.1.170\",\n  \"model\": \"opus\",\n  \"advisorModel\": \"fable\",\n  \"effortLevel\": \"xhigh\",\n  \"autoMemoryEnabled\": true,\n  \"skillListingMaxDescChars\": 2048,\n  \"respectGitignore\": true,\n  \"cleanupPeriodDays\": 14,\n  \"skillListingBudgetFraction\": 0.05,\n  \"env\": {\n    \"CLAUDE_CODE_MAX_OUTPUT_TOKENS\": \"64000\",\n    \"CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR\": \"1\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"468000\",\n    \"CLAUDE_CODE_NO_FLICKER\": \"1\"\n  },\n  \"permissions\": {\n    \"defaultMode\": \"auto\",\n    \"allow\": [\n      \"Read\",\n      \"Glob\",\n      \"Grep\",\n      \"WebFetch\",\n      \"WebSearch\",\n      \"Edit(./)\",\n      \"Write(./)\",\n      \"Bash(git *)\",\n      \"Bash(git add *)\",\n      \"Bash(git commit *)\",\n      \"Bash(git status *)\",\n      \"Bash(git diff *)\",\n      \"Bash(git log *)\",\n      \"Bash(git branch *)\",\n      \"Bash(git checkout *)\",\n      \"Bash(git switch *)\",\n      \"Bash(git stash *)\",\n      \"Bash(git fetch *)\",\n      \"Bash(git pull *)\",\n      \"Bash(git tag *)\",\n      \"Bash(git show *)\",\n      \"Bash(git blame *)\",\n      \"Bash(git worktree *)\",\n      \"Bash(gh *)\",\n      \"Bash(pnpm *)\",\n      \"Bash(npm *)\",\n      \"Bash(npx *)\",\n      \"Bash(node *)\",\n      \"Bash(docker *)\",\n      \"Bash(docker-compose *)\",\n      \"Bash(rtk *)\",\n      \"Bash(ls *)\",\n      \"Bash(cat *)\",\n      \"Bash(find *)\",\n      \"Bash(grep *)\",\n      \"Bash(head *)\",\n      \"Bash(tail *)\",\n      \"Bash(wc *)\",\n      \"Bash(sort *)\",\n      \"Bash(uniq *)\",\n      \"Bash(diff *)\",\n      \"Bash(which *)\",\n      \"Bash(pwd *)\",\n      \"Bash(date *)\",\n      \"Bash(mkdir *)\",\n      \"Bash(basename *)\",\n      \"Bash(dirname *)\",\n      \"Bash(realpath *)\",\n      \"Bash(jq *)\",\n      \"Bash(curl *)\",\n      \"Bash(tree *)\",\n      \"Bash(sed *)\",\n      \"Bash(awk *)\",\n      \"Bash(cut *)\",\n      \"Bash(tr *)\",\n      \"Bash(tee *)\",\n      \"Bash(echo *)\",\n      \"Bash(printf *)\",\n      \"Bash(env *)\",\n      \"Bash(printenv *)\",\n      \"Bash(uname *)\",\n      \"Bash(file *)\",\n      \"Bash(stat *)\",\n      \"Bash(du *)\",\n      \"Bash(id *)\",\n      \"Bash(whoami *)\",\n      \"Bash(php *)\",\n      \"Bash(composer *)\",\n      \"Bash(python3 *)\",\n      \"Bash(python *)\",\n      \"Bash(pip *)\",\n      \"Bash(pip3 *)\"\n    ],\n    \"deny\": [\n      \"Read(**/.env)\",\n      \"Read(**/.env.local)\",\n      \"Read(**/secrets/**)\",\n      \"Read(**/*.key)\",\n      \"Read(**/*.pem)\",\n      \"Read(**/*.p12)\",\n      \"Read(**/.credentials*)\",\n      \"Edit(**/.env)\",\n      \"Edit(**/.env.local)\",\n      \"Edit(**/secrets/**)\",\n      \"Write(**/.env)\",\n      \"Write(**/.env.local)\",\n      \"Write(**/secrets/**)\",\n      \"Bash(sudo *)\",\n      \"Bash(rm -rf /)\",\n      \"Bash(rm -rf / *)\",\n      \"Bash(rm -rf ~)\",\n      \"Bash(rm -rf ~ *)\",\n      \"Bash(rm -rf $HOME)\",\n      \"Bash(rm -rf $HOME *)\",\n      \"Bash(> /dev *)\",\n      \"Bash(dd if= *)\",\n      \"Bash(mkfs *)\",\n      \"Bash(eval *)\",\n      \"Bash(chmod 777 *)\",\n      \"Bash(chmod -R 777 *)\",\n      \"Bash(git push --force origin main *)\",\n      \"Bash(git push --force origin master *)\",\n      \"Bash(git push -f origin main *)\",\n      \"Bash(git push -f origin master *)\"\n    ],\n    \"ask\": [\n      \"Bash(git clean *)\",\n      \"Bash(docker volume rm *)\",\n      \"Bash(docker system prune *)\"\n    ]\n  },\n  \"hooks\": {\n    \"SessionStart\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"__DOCKS_KIT_BUN__\",\n            \"args\": [\"__DOCKS_KIT_SESSION_START__\"],\n            \"timeout\": 5\n          }\n        ]\n      }\n    ],\n    \"Notification\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"__DOCKS_KIT_BUN__\",\n            \"args\": [\"__DOCKS_KIT_NOTIFY__\"],\n            \"timeout\": 10,\n            \"async\": true\n          }\n        ]\n      }\n    ],\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"rtk hook claude\"\n          }\n        ]\n      }\n    ],\n    \"PostToolUseFailure\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"echo '{\\\"hookSpecificOutput\\\":{\\\"hookEventName\\\":\\\"PostToolUseFailure\\\",\\\"additionalContext\\\":\\\"Last bash command failed. Repository / file state may have shifted \\u2014 re-read affected files before retrying. If the failure is a missing dependency or env mismatch, surface it to the user rather than retrying blindly.\\\"}}'\",\n            \"timeout\": 5\n          }\n        ]\n      }\n    ],\n    \"SubagentStop\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"prompt\",\n            \"prompt\": \"You are a quality gate for subagent outputs in a multi-agent code-analysis pipeline.\\n\\nEvaluate the subagent's `last_assistant_message` field (in the JSON below) against these requirements:\\n\\n1. ALLOW (return `{}`): Mode-selection or no-issues responses. Examples: \\\"Which mode do you prefer\\\", \\\"select an option\\\", \\\"no issues / problems / violations / blockers found\\\".\\n\\n2. ALLOW (return `{}`): Output contains at least one concrete file:line citation \\u2014 e.g. `src/auth.ts:42`, `lib/db.ts:100-115`, or path references that include line numbers.\\n\\n3. BLOCK (return `{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"<one-line explanation>\\\"}`): Output claims about code or findings WITHOUT concrete file:line citations. Vague references like \\\"the auth handler\\\" or \\\"near the database code\\\" are not acceptable as the only evidence.\\n\\nSubagent invocation JSON:\\n$ARGUMENTS\\n\\nReturn ONLY the JSON decision (no commentary, no markdown fences).\",\n            \"timeout\": 30\n          }\n        ]\n      }\n    ]\n  },\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"__DOCKS_KIT_STATUSLINE__\",\n    \"refreshInterval\": 5\n  },\n  \"enabledPlugins\": {\n    \"context7@claude-plugins-official\": true,\n    \"frontend-design@claude-plugins-official\": true,\n    \"php-lsp@claude-plugins-official\": true,\n    \"typescript-lsp@claude-plugins-official\": true,\n    \"docks@docks\": true,\n    \"session-relay@docks\": true,\n    \"effect-kit@docks\": true\n  },\n  \"extraKnownMarketplaces\": {\n    \"docks\": {\n      \"source\": {\n        \"source\": \"github\",\n        \"repo\": \"DocksDocks/docks\"\n      }\n    }\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"showThinkingSummaries\": true,\n  \"viewMode\": \"default\",\n  \"theme\": \"dark-daltonized\",\n  \"skipDangerousModePermissionPrompt\": true\n}\n",
+  "SoT/.claude/settings.json": "{\n  \"$schema\": \"https://json.schemastore.org/claude-code-settings.json\",\n  \"minimumVersion\": \"2.1.170\",\n  \"model\": \"fable\",\n  \"effortLevel\": \"high\",\n  \"autoMemoryEnabled\": true,\n  \"skillListingMaxDescChars\": 2048,\n  \"respectGitignore\": true,\n  \"cleanupPeriodDays\": 14,\n  \"skillListingBudgetFraction\": 0.05,\n  \"env\": {\n    \"CLAUDE_CODE_MAX_OUTPUT_TOKENS\": \"64000\",\n    \"CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR\": \"1\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"468000\",\n    \"CLAUDE_CODE_NO_FLICKER\": \"1\"\n  },\n  \"permissions\": {\n    \"defaultMode\": \"auto\",\n    \"allow\": [\n      \"Read\",\n      \"Glob\",\n      \"Grep\",\n      \"WebFetch\",\n      \"WebSearch\",\n      \"Edit(./)\",\n      \"Write(./)\",\n      \"Bash(git *)\",\n      \"Bash(git add *)\",\n      \"Bash(git commit *)\",\n      \"Bash(git status *)\",\n      \"Bash(git diff *)\",\n      \"Bash(git log *)\",\n      \"Bash(git branch *)\",\n      \"Bash(git checkout *)\",\n      \"Bash(git switch *)\",\n      \"Bash(git stash *)\",\n      \"Bash(git fetch *)\",\n      \"Bash(git pull *)\",\n      \"Bash(git tag *)\",\n      \"Bash(git show *)\",\n      \"Bash(git blame *)\",\n      \"Bash(git worktree *)\",\n      \"Bash(gh *)\",\n      \"Bash(pnpm *)\",\n      \"Bash(npm *)\",\n      \"Bash(npx *)\",\n      \"Bash(node *)\",\n      \"Bash(docker *)\",\n      \"Bash(docker-compose *)\",\n      \"Bash(rtk *)\",\n      \"Bash(ls *)\",\n      \"Bash(cat *)\",\n      \"Bash(find *)\",\n      \"Bash(grep *)\",\n      \"Bash(head *)\",\n      \"Bash(tail *)\",\n      \"Bash(wc *)\",\n      \"Bash(sort *)\",\n      \"Bash(uniq *)\",\n      \"Bash(diff *)\",\n      \"Bash(which *)\",\n      \"Bash(pwd *)\",\n      \"Bash(date *)\",\n      \"Bash(mkdir *)\",\n      \"Bash(basename *)\",\n      \"Bash(dirname *)\",\n      \"Bash(realpath *)\",\n      \"Bash(jq *)\",\n      \"Bash(curl *)\",\n      \"Bash(tree *)\",\n      \"Bash(sed *)\",\n      \"Bash(awk *)\",\n      \"Bash(cut *)\",\n      \"Bash(tr *)\",\n      \"Bash(tee *)\",\n      \"Bash(echo *)\",\n      \"Bash(printf *)\",\n      \"Bash(env *)\",\n      \"Bash(printenv *)\",\n      \"Bash(uname *)\",\n      \"Bash(file *)\",\n      \"Bash(stat *)\",\n      \"Bash(du *)\",\n      \"Bash(id *)\",\n      \"Bash(whoami *)\",\n      \"Bash(php *)\",\n      \"Bash(composer *)\",\n      \"Bash(python3 *)\",\n      \"Bash(python *)\",\n      \"Bash(pip *)\",\n      \"Bash(pip3 *)\"\n    ],\n    \"deny\": [\n      \"Read(**/.env)\",\n      \"Read(**/.env.local)\",\n      \"Read(**/secrets/**)\",\n      \"Read(**/*.key)\",\n      \"Read(**/*.pem)\",\n      \"Read(**/*.p12)\",\n      \"Read(**/.credentials*)\",\n      \"Edit(**/.env)\",\n      \"Edit(**/.env.local)\",\n      \"Edit(**/secrets/**)\",\n      \"Write(**/.env)\",\n      \"Write(**/.env.local)\",\n      \"Write(**/secrets/**)\",\n      \"Bash(sudo *)\",\n      \"Bash(rm -rf /)\",\n      \"Bash(rm -rf / *)\",\n      \"Bash(rm -rf ~)\",\n      \"Bash(rm -rf ~ *)\",\n      \"Bash(rm -rf $HOME)\",\n      \"Bash(rm -rf $HOME *)\",\n      \"Bash(> /dev *)\",\n      \"Bash(dd if= *)\",\n      \"Bash(mkfs *)\",\n      \"Bash(eval *)\",\n      \"Bash(chmod 777 *)\",\n      \"Bash(chmod -R 777 *)\",\n      \"Bash(git push --force origin main *)\",\n      \"Bash(git push --force origin master *)\",\n      \"Bash(git push -f origin main *)\",\n      \"Bash(git push -f origin master *)\"\n    ],\n    \"ask\": [\n      \"Bash(git clean *)\",\n      \"Bash(docker volume rm *)\",\n      \"Bash(docker system prune *)\"\n    ]\n  },\n  \"hooks\": {\n    \"SessionStart\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"__DOCKS_KIT_BUN__\",\n            \"args\": [\"__DOCKS_KIT_SESSION_START__\"],\n            \"timeout\": 5\n          }\n        ]\n      }\n    ],\n    \"Notification\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"__DOCKS_KIT_BUN__\",\n            \"args\": [\"__DOCKS_KIT_NOTIFY__\"],\n            \"timeout\": 10,\n            \"async\": true\n          }\n        ]\n      }\n    ],\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"rtk hook claude\"\n          }\n        ]\n      }\n    ],\n    \"PostToolUseFailure\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"echo '{\\\"hookSpecificOutput\\\":{\\\"hookEventName\\\":\\\"PostToolUseFailure\\\",\\\"additionalContext\\\":\\\"Last bash command failed. Repository / file state may have shifted \\u2014 re-read affected files before retrying. If the failure is a missing dependency or env mismatch, surface it to the user rather than retrying blindly.\\\"}}'\",\n            \"timeout\": 5\n          }\n        ]\n      }\n    ],\n    \"SubagentStop\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"prompt\",\n            \"prompt\": \"You are a quality gate for subagent outputs in a multi-agent code-analysis pipeline.\\n\\nEvaluate the subagent's `last_assistant_message` field (in the JSON below) against these requirements:\\n\\n1. ALLOW (return `{}`): Mode-selection or no-issues responses. Examples: \\\"Which mode do you prefer\\\", \\\"select an option\\\", \\\"no issues / problems / violations / blockers found\\\".\\n\\n2. ALLOW (return `{}`): Output contains at least one concrete file:line citation \\u2014 e.g. `src/auth.ts:42`, `lib/db.ts:100-115`, or path references that include line numbers.\\n\\n3. BLOCK (return `{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"<one-line explanation>\\\"}`): Output claims about code or findings WITHOUT concrete file:line citations. Vague references like \\\"the auth handler\\\" or \\\"near the database code\\\" are not acceptable as the only evidence.\\n\\nSubagent invocation JSON:\\n$ARGUMENTS\\n\\nReturn ONLY the JSON decision (no commentary, no markdown fences).\",\n            \"timeout\": 30\n          }\n        ]\n      }\n    ]\n  },\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"__DOCKS_KIT_STATUSLINE__\",\n    \"refreshInterval\": 5\n  },\n  \"enabledPlugins\": {\n    \"context7@claude-plugins-official\": true,\n    \"frontend-design@claude-plugins-official\": true,\n    \"php-lsp@claude-plugins-official\": true,\n    \"typescript-lsp@claude-plugins-official\": true,\n    \"docks@docks\": true,\n    \"session-relay@docks\": true,\n    \"effect-kit@docks\": true\n  },\n  \"extraKnownMarketplaces\": {\n    \"docks\": {\n      \"source\": {\n        \"source\": \"github\",\n        \"repo\": \"DocksDocks/docks\"\n      }\n    }\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"showThinkingSummaries\": true,\n  \"viewMode\": \"default\",\n  \"theme\": \"dark-daltonized\",\n  \"skipDangerousModePermissionPrompt\": true\n}\n",
   "SoT/.claude/bin/statusline.mjs": "const ESC = \"\\x1b[\"\nconst PIPE = `${ESC}90m | ${ESC}0m`\nconst DOT = `${ESC}90m • ${ESC}0m`\nconst DIM = `${ESC}2m${ESC}38;2;156;162;175m`\n\nfunction isRecord(value) {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value)\n}\n\nfunction finitePercentage(value) {\n  return typeof value === \"number\" && Number.isFinite(value) && value >= 0 && value <= 100\n    ? value\n    : undefined\n}\n\nfunction roundHalfEven(value) {\n  const lower = Math.floor(value)\n  const fraction = value - lower\n  if (fraction < 0.5) return lower\n  if (fraction > 0.5) return lower + 1\n  return lower % 2 === 0 ? lower : lower + 1\n}\n\nfunction pathBasename(path) {\n  const parts = path.split(/[\\\\/]+/).filter((part) => part !== \"\")\n  return parts.at(-1) ?? \"\"\n}\n\nfunction modelName(input) {\n  const model = isRecord(input.model) && typeof input.model.display_name === \"string\"\n    ? input.model.display_name\n    : \"\"\n  const suffix = model.indexOf(\" (\")\n  return suffix === -1 ? model : model.slice(0, suffix)\n}\n\nfunction workingDirectory(input, cwd) {\n  if (isRecord(input.workspace) && typeof input.workspace.current_dir === \"string\" && input.workspace.current_dir !== \"\") {\n    return input.workspace.current_dir\n  }\n  if (typeof input.cwd === \"string\" && input.cwd !== \"\") return input.cwd\n  return cwd\n}\n\nfunction compactWindow(env, total) {\n  const raw = env.CLAUDE_CODE_AUTO_COMPACT_WINDOW\n  if (typeof raw !== \"string\" || !/^[0-9]+$/.test(raw)) return total\n  const parsed = Number(raw)\n  return Number.isSafeInteger(parsed) && parsed >= 1000 && parsed < total ? parsed : total\n}\n\nfunction formatTokensK(value) {\n  if (value < 1000) return `${value}k`\n  if (value % 1000 === 0) return `${value / 1000}M`\n  return `${(roundHalfEven(value / 100) / 10).toFixed(1)}M`\n}\n\nfunction contextSegment(input, env) {\n  if (!isRecord(input.context_window)) return \"\"\n  const used = finitePercentage(input.context_window.used_percentage)\n  if (used === undefined) return \"\"\n\n  const total = input.context_window.context_window_size\n  if (typeof total !== \"number\" || !Number.isFinite(total) || total <= 0) {\n    return `${ESC}38;2;130;160;230mctx ${roundHalfEven(used)}%${ESC}0m`\n  }\n\n  const usedK = roundHalfEven((used / 100) * (total / 1000))\n  const effectiveK = Math.trunc(compactWindow(env, total) / 1000)\n  if (effectiveK <= 0) return `${ESC}38;2;130;160;230mctx ${roundHalfEven(used)}%${ESC}0m`\n  const effectivePercentage = roundHalfEven((usedK / effectiveK) * 100)\n  return `${ESC}38;2;130;160;230mctx ${effectivePercentage}%${ESC}0m ${DIM}(${formatTokensK(usedK)}/${formatTokensK(effectiveK)})${ESC}0m`\n}\n\nfunction resetDelta(value, nowMs) {\n  if (typeof value !== \"number\" || !Number.isFinite(value) || value < 0) return \"\"\n  const seconds = Math.trunc(value) - Math.floor(nowMs / 1000)\n  if (seconds <= 0) return \"now\"\n  const days = Math.trunc(seconds / 86_400)\n  if (days > 0) return `${days}d`\n  const hours = Math.trunc((seconds % 86_400) / 3_600)\n  if (hours > 0) return `${hours}h`\n  return `${Math.trunc((seconds % 3_600) / 60)}m`\n}\n\nfunction quotaWindow(value, label, color, nowMs) {\n  if (!isRecord(value)) return \"\"\n  const used = finitePercentage(value.used_percentage)\n  if (used === undefined) return \"\"\n  const delta = resetDelta(value.resets_at, nowMs)\n  const reset = delta === \"\" ? \"\" : ` ${DIM}(${delta})${ESC}0m`\n  return `${ESC}38;2;${color}m${label} ${roundHalfEven(used)}%${ESC}0m${reset}`\n}\n\nfunction decodeStdout(result) {\n  const stdout = result?.stdout\n  if (stdout === undefined || stdout === null) return \"\"\n  return typeof stdout === \"string\" ? stdout : stdout.toString()\n}\n\nfunction resolveBranch(directory, which, spawnSync) {\n  const git = which(\"git\")\n  if (typeof git !== \"string\" || git === \"\") return \"\"\n  const commands = [\n    [git, \"-C\", directory, \"symbolic-ref\", \"--short\", \"HEAD\"],\n    [git, \"-C\", directory, \"rev-parse\", \"--short\", \"HEAD\"]\n  ]\n  for (const command of commands) {\n    try {\n      const result = spawnSync(command, { stdin: \"ignore\", stdout: \"pipe\", stderr: \"ignore\" })\n      if (result?.success === true) return decodeStdout(result).trim()\n    } catch {\n      return \"\"\n    }\n  }\n  return \"\"\n}\n\nexport function formatStatusline(input, options = {}) {\n  if (!isRecord(input)) return \"\"\n  const env = isRecord(options.env) ? options.env : process.env\n  const nowMs = typeof options.nowMs === \"number\" ? options.nowMs : Date.now()\n  const cwd = typeof options.cwd === \"string\" ? options.cwd : process.cwd()\n  const branch = typeof options.branch === \"string\" ? options.branch : \"\"\n  const directory = workingDirectory(input, cwd)\n\n  const model = `${ESC}38;5;208m${ESC}1m${modelName(input)}${ESC}22m${ESC}0m`\n  const folder = `${ESC}1m${ESC}38;2;76;208;222m${pathBasename(directory)}${ESC}22m${ESC}0m`\n  const branchSegment = branch === \"\" ? \"\" : `${DOT}${ESC}1m${ESC}38;2;192;103;222m${branch}${ESC}22m${ESC}0m`\n  const context = contextSegment(input, env)\n\n  const rateLimits = isRecord(input.rate_limits) ? input.rate_limits : {}\n  const fiveHour = quotaWindow(rateLimits.five_hour, \"5h\", \"100;200;200\", nowMs)\n  const sevenDay = quotaWindow(rateLimits.seven_day, \"7d\", \"230;180;90\", nowMs)\n  const quota = fiveHour === \"\" && sevenDay === \"\"\n    ? \"\"\n    : `${PIPE}${fiveHour}${fiveHour !== \"\" && sevenDay !== \"\" ? DOT : \"\"}${sevenDay}`\n\n  return `${model}${PIPE}${folder}${branchSegment}${context === \"\" ? \"\" : `${PIPE}${context}`}${quota}`\n}\n\nexport async function main(options = {}) {\n  const readStdin = options.readStdin ?? (() => Bun.stdin.text())\n  const writeStdout = options.writeStdout ?? ((value) => process.stdout.write(value))\n  let raw\n  try {\n    raw = await readStdin()\n  } catch {\n    return 0\n  }\n\n  let input\n  try {\n    input = JSON.parse(raw)\n  } catch {\n    return 0\n  }\n  if (!isRecord(input)) return 0\n\n  const cwd = typeof options.cwd === \"string\" ? options.cwd : process.cwd()\n  const directory = workingDirectory(input, cwd)\n  const branch = resolveBranch(\n    directory,\n    options.which ?? ((name) => Bun.which(name)),\n    options.spawnSync ?? ((argv, spawnOptions) => Bun.spawnSync(argv, spawnOptions))\n  )\n  const output = formatStatusline(input, {\n    env: options.env ?? process.env,\n    nowMs: options.nowMs ?? Date.now(),\n    cwd,\n    branch\n  })\n  if (output !== \"\") writeStdout(`${output}\\n`)\n  return 0\n}\n\nif (import.meta.main) process.exit(await main())\n",
   "SoT/.claude/bin/session-start.mjs": "import { readFileSync } from \"node:fs\"\nimport { homedir } from \"node:os\"\n\nfunction isRecord(value) {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value)\n}\n\nfunction nonEmpty(value, fallback) {\n  return typeof value === \"string\" && value !== \"\" ? value : fallback\n}\n\nfunction pad(value) {\n  return String(value).padStart(2, \"0\")\n}\n\nfunction configuredEffort(home, readText) {\n  try {\n    const parsed = JSON.parse(readText(`${home}/.claude/settings.json`))\n    return isRecord(parsed) ? nonEmpty(parsed.effortLevel, \"default\") : \"default\"\n  } catch {\n    return \"default\"\n  }\n}\n\nfunction localZone(now) {\n  const part = new Intl.DateTimeFormat(\"en-US\", { timeZoneName: \"short\" })\n    .formatToParts(now)\n    .find((value) => value.type === \"timeZoneName\")\n  return part?.value ?? \"\"\n}\n\nexport function sessionStartLines(options = {}) {\n  const env = isRecord(options.env) ? options.env : process.env\n  const now = options.now instanceof Date ? options.now : new Date()\n  const home = typeof options.home === \"string\" ? options.home : homedir()\n  const readText = options.readText ?? ((path) => readFileSync(path, \"utf8\"))\n  const weekday = new Intl.DateTimeFormat(\"en-US\", { weekday: \"long\" }).format(now)\n  const date = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`\n  const time = `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`\n  const effort = nonEmpty(env.CLAUDE_CODE_EFFORT_LEVEL, configuredEffort(home, readText))\n  const context = env.CLAUDE_CODE_DISABLE_1M_CONTEXT === \"1\" ? \"200K\" : \"1M\"\n  const compactWindow = nonEmpty(env.CLAUDE_CODE_AUTO_COMPACT_WINDOW, \"full\")\n  const subagent = nonEmpty(env.CLAUDE_CODE_SUBAGENT_MODEL, \"default\")\n  return [\n    `[CONTEXT] Current date: ${weekday}, ${date} ${time} ${localZone(now)}`,\n    `[CONFIG] Context: ${context} | Compact-window: ${compactWindow} | Effort: ${effort} | Thinking: adaptive | Subagent: ${subagent}`\n  ]\n}\n\nexport async function main(options = {}) {\n  const writeStdout = options.writeStdout ?? ((value) => process.stdout.write(value))\n  writeStdout(`${sessionStartLines(options).join(\"\\n\")}\\n`)\n  return 0\n}\n\nif (import.meta.main) process.exit(await main())\n",
   "SoT/.claude/bin/notify.mjs": "const DEFAULT_SOUND = `${import.meta.dir}/../notification.mp3`\n\nexport function selectPlayer(options = {}) {\n  const platform = options.platform ?? process.platform\n  const sound = options.sound ?? DEFAULT_SOUND\n  const which = options.which ?? ((name) => Bun.which(name))\n  if (platform === \"darwin\") {\n    const afplay = which(\"afplay\")\n    if (typeof afplay === \"string\" && afplay !== \"\") return [afplay, sound]\n  }\n  const ffplay = which(\"ffplay\")\n  if (typeof ffplay === \"string\" && ffplay !== \"\") {\n    return [ffplay, \"-nodisp\", \"-autoexit\", \"-loglevel\", \"quiet\", sound]\n  }\n  const paplay = which(\"paplay\")\n  if (typeof paplay === \"string\" && paplay !== \"\") return [paplay, sound]\n  const aplay = which(\"aplay\")\n  if (typeof aplay === \"string\" && aplay !== \"\") return [aplay, \"-q\", sound]\n  return undefined\n}\n\nexport async function main(options = {}) {\n  const sound = options.sound ?? DEFAULT_SOUND\n  const fileExists = options.fileExists ?? ((path) => Bun.file(path).exists())\n  if (!await fileExists(sound)) return 0\n  const command = selectPlayer({ ...options, sound })\n  if (command === undefined) return 0\n  const spawnSync = options.spawnSync ?? ((argv, spawnOptions) => Bun.spawnSync(argv, spawnOptions))\n  const result = spawnSync(command, { stdin: \"ignore\", stdout: \"ignore\", stderr: \"ignore\" })\n  return typeof result.exitCode === \"number\" ? result.exitCode : 1\n}\n\nif (import.meta.main) process.exit(await main())\n",
@@ -38,4 +40,4 @@ export const GENERATED_PAYLOAD_PATHS = [
   "notification.mp3"
 ] as const
 
-export const GENERATED_PAYLOAD_HASH = "4b7580dd66aeaabf4a11c62a01290837398c9ced7790d2dcb2ef056c9f2151e7"
+export const GENERATED_PAYLOAD_HASH = "ee72d5dbc640f90fbacba29a6486e668adbbf7632e958f55952d8eb94cc8286e"

package/cli/src/main.ts

@@ -12,6 +12,7 @@ import { statusCommand } from "./commands/status"
 import { syncCommand } from "./commands/sync"
 import { toolchainCommand } from "./commands/toolchain"
 import { updateCommand } from "./commands/update"
+import { GENERATED_PACKAGE_VERSION } from "./generated/sotPayload"
 
 const root = Command.make("docks-kit", {}, () =>
   Effect.gen(function* () {
@@ -59,16 +60,25 @@ if (process.env["DOCKS_KIT_ENGINE"] === "native-raw") {
 
 const cli = Command.run(root, {
   name: "docks-kit",
-  version: "0.1.0"
+  version: GENERATED_PACKAGE_VERSION
 })
 
-// @effect/cli's Options.repeated does not accept `--flag=value` syntax (only
-// `--flag value`), but the documented form for the repeatable opt-in is
-// `--claude-plugin=<name>` — normalize it here so both spellings work.
-const argv = process.argv.flatMap((a) =>
-  a.startsWith("--claude-plugin=")
-    ? ["--claude-plugin", a.slice("--claude-plugin=".length)]
-    : [a]
-)
+// Normalize the repeatable plugin's documented equals form and exact empty
+// text-option assignments that @effect/cli otherwise routes into positional
+// targets. EngineNative owns the resulting shared empty-value validation.
+const emptyTextOptions = new Set([
+  "--claude-model=",
+  "--claude-effort=",
+  "--claude-advisor=",
+  "--codex-model=",
+  "--codex-effort="
+])
+const argv = process.argv.flatMap((a) => {
+  if (a.startsWith("--claude-plugin=")) {
+    return ["--claude-plugin", a.slice("--claude-plugin=".length)]
+  }
+  if (emptyTextOptions.has(a)) return [a.slice(0, -1), ""]
+  return [a]
+})
 
 cli(argv).pipe(Effect.provide(Layer.mergeAll(BunContext.layer, EngineServicesLive)), BunRuntime.runMain)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docks-kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
   "type": "module",
   "license": "MIT",

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

@@ -1,54 +0,0 @@
-/**
- * --claude-model deploy-time modifier, shared with the `model claude <value>`
- * direct mode.
- */
-import { p } from "./exec"
-import { readFileSync, renameSync, writeFileSync } from "node:fs"
-
-import type { Ctx } from "./index"
-import { isObject, jqStringify, parseJson } from "./jq"
-
-export function syncClaudeModel(ctx: Ctx, model: string): void {
-  const { change, echo, err, verbose, warn } = ctx.services.logger
-  const userSettings = p(ctx.home, ".claude", "settings.json")
-
-  if (model === "") return
-
-  if (ctx.dryRun) {
-    if (model === "default") {
-      echo(`[dry-run] (--claude-model) delete .model in ${userSettings} (account default applies)`)
-    } else {
-      echo(`[dry-run] (--claude-model) set .model=${model} in ${userSettings}`)
-    }
-    return
-  }
-
-  let text: string
-  try {
-    text = readFileSync(userSettings, "utf8")
-  } catch {
-    warn(`(--claude-model) ${userSettings} missing — skipped`)
-    return
-  }
-  const doc = parseJson(text)
-  if (doc === undefined) {
-    err(`(--claude-model) ${userSettings} is not valid JSON — skipped`)
-    return
-  }
-  if (isObject(doc)) {
-    if (model === "default") {
-      delete doc["model"]
-    } else {
-      doc["model"] = model
-    }
-  }
-  const out = jqStringify(doc)
-  if (out === text) {
-    verbose(`Model: deployed settings model already ${model === "default" ? "unset (account default)" : model}`)
-    return
-  }
-  writeFileSync(`${userSettings}.tmp`, out)
-  renameSync(`${userSettings}.tmp`, userSettings)
-  change(`Model: deployed settings model set to ${model} (SoT unchanged; flag-less sync reverts)`)
-  ctx.nextStepTriggers.claudeRestart = true
-}