docks-kit 0.2.0 → 0.3.0

package/AGENTS.md

@@ -22,7 +22,7 @@ Tool-specific instructions live alongside this file:
 | `install.sh` | Global installer |
 | `.github/workflows/release-cli.yml` | `cli-v*` release binaries + npm publish |
 | `README.md` | Front door |
-| `package.json` / `bun.lock` | npm package: `bin` = `cli/src/main.ts`; bundles `cli/` + `SoT/` |
+| `package.json` / `bun.lock` | npm package: `bin` = `cli/src/main.ts`; bundles `cli/` with the generated in-memory SoT payload |
 | `SoT/.agents/skills.txt` | Universal-skill manifest. One [agentskills.io](https://agentskills.io) slug per line; EngineNative runs `npx skills add` for each missing entry into `~/.agents/skills/`, where Codex et al. discover it natively and Claude Code follows a symlink at `~/.claude/skills/` |
 | `notification.mp3` | Audio asset for Notification hooks (consumed by Claude Code today; tool-agnostic file) |
 | `docs/plans/` | Multi-commit work-item plans (`active/` with status in frontmatter, plus `finished/` archive). Convention: `docs/plans/AGENTS.md` |

package/README.md

@@ -25,8 +25,9 @@ see `./docks-kit docs install`.
 
 **No-Bun recovery path**:
 
-Download the platform release binary from GitHub Releases and run it from a
-kit checkout, or set `DOCKS_KIT_HOME` to the checkout containing `SoT/`.
+Download the platform release binary from GitHub Releases and run it directly.
+The executable carries the generated sync payload; no checkout or adjacent
+`SoT/` directory is required.
 
 Prerequisites for source/global installs: Bun plus `jq` and `curl` for sync
 preflight; Node/npm for npm-global tools.
@@ -93,6 +94,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 | `SoT/models.json` | Kit-verified model catalog |
 | `SoT/toolchain.json` | Verified-version floors |
 | `cli/src/engine-native/` | EngineNative sync/model/toolchain implementation |
+| `cli/src/generated/sotPayload.ts` | Generated in-memory payload used by standalone and npm installs |
 | `cli/` | docks-kit CLI (Effect-TS on Bun) + bundled docs topics |
 | `docks-kit` | Launcher (binary → bun-from-source) |
 | `install.sh` | Global installer (Bun bootstrap + `bun add -g`) |
@@ -113,8 +115,8 @@ Details: `docks-kit docs platforms`.
 
 Tagging `cli-v*` builds five standalone binaries (+ SHA256SUMS) and attaches
 them to the GitHub release; npm publish runs when the `NPM_TOKEN` secret is
-configured. Package bundles the CLI + SoT, so npm releases are versioned config
-snapshots.
+configured. Package bundles the CLI + generated payload, so npm releases are
+versioned config snapshots without shipping the authoring `SoT/` tree.
 
 ## Deeper docs
 

package/cli/docs/install.md

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

package/cli/docs/overview.md

@@ -14,6 +14,7 @@ AI-assisted dev environment on every machine.
 | `SoT/.agents/` | Universal agent skills manifest (agentskills.io standard) |
 | `SoT/models.json` | Kit-verified model catalog (see `docks-kit docs models`) |
 | `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
+| `cli/src/generated/sotPayload.ts` | Deterministic generated payload embedded in standalone/npm execution |
 | `cli/src/engine-native/` | EngineNative mutation logic for sync/model/toolchain |
 | `cli/` | This CLI (Effect-TS on Bun) plus bundled docs |
 | `docks-kit` | Launcher: compiled binary → bun-from-source, with Bun auto-install |
@@ -31,6 +32,8 @@ AI-assisted dev environment on every machine.
   changes, and a later flag-less sync reverts them (`docks-kit docs modifiers`).
 - **Engine/CLI split**: the CLI adds UX (typed flags, pickers, docs, JSON);
   EngineNative owns mutation. No-Bun recovery is a platform release binary.
+- **Authoring/runtime split**: changes begin in `SoT/`; build/prepack freshness
+  checks keep the generated in-memory payload byte-identical for every runtime.
 
 ## Where to go next
 

package/cli/docs/platforms.md

@@ -16,12 +16,10 @@ Supported entrypoints (both verified in CI on windows-2025 under native
 PowerShell — see `.github/workflows/windows-entrypoints.yml`):
 
 - **`docks-kit-windows-x64.exe`** (release asset) — the no-toolchain path.
-  No Bun, no Git Bash; the exe embeds the runtime and EngineNative runs
-  in-process. It still needs the SoT it deploys: run from a kit checkout or
-  set `DOCKS_KIT_HOME`.
+  No Bun, no Git Bash; the exe embeds the runtime and generated payload, and
+  EngineNative runs in-process from any working directory.
 - **`bun add -g docks-kit`** — bun creates a working Windows shim for the
-  `#!/usr/bin/env bun` bin; outside a checkout kit-home resolves to the
-  package's own bundled SoT.
+  `#!/usr/bin/env bun` bin; the package carries the same generated payload.
 - `install.sh` is **Unix-only** and not a Windows path.
 
 The managed tools all run natively on Windows: Claude Code (requires Git

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

@@ -36,6 +36,9 @@ explicit removed-engine diagnostic and exits 2 with the recovery tag message.
   shell script.
 - **Backups precede mutation.** Deployed settings/config files write `.bak`
   backups before replacement.
+- **Runtime payload is in memory.** `SoT/` remains the reviewed authoring tree;
+  generated payload freshness gates build/package production, and EngineNative
+  never needs an adjacent runtime `SoT/` directory.
 
 ## Output Policy (log UX contract)
 
@@ -113,6 +116,7 @@ active logger binding.
 |---|---|
 | `parseArgs.ts` | engine usage, target selection, flag parsing, legacy rename hints, preflight, model flag validation |
 | `index.ts` | sync orchestration, target dispatch, run summary and next-step blocks |
+| `../payload.ts` | generated text/byte payload reads and presentation-only source labels |
 | `claudeSync.ts` | Claude pipeline: RTK, assets, settings merge, deploy-time modifiers, `~/.claude.json`, connector env, removed artifacts, plugins, optional plugins, LSP binaries |
 | `settings.ts` | pure Claude settings merge/reconcile semantics and permission-array union |
 | `claudeModel.ts` | deployed Claude model modifier and direct `model claude` write path |

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

@@ -17,13 +17,14 @@ import {
 } from "node:fs"
 import { tmpdir } from "node:os"
 import { syncClaudeModel } from "./claudeModel"
-import { copyFileIfChanged, copyTreeIfChanged, ensureExecutable, p, writeFileIfChanged } from "./exec"
+import { ensureExecutable, p, writeBytesIfChanged, writeFileIfChanged, writeTextIfChanged } from "./exec"
 import type { Ctx } from "./index"
 import { compareCodepoints, deepMerge, isObject, jqStringify, parseJson, type Json } from "./jq"
 import type { EngineServices } from "./services"
 import { ExitError } from "./parseArgs"
 import { mergeSettings, reconcileSettings } from "./settings"
 import { ensure, field } from "./toolchain"
+import { payloadBytes, payloadDisplayPath, payloadText } from "../payload"
 
 export function claudeSync(ctx: Ctx): void {
   const { warn } = ctx.services.logger
@@ -127,15 +128,15 @@ function syncScripts(ctx: Ctx, claudeDir: string): void {
   }
 
   let changed = false
-  for (const script of ["statusline.sh", "fetch-usage.sh"]) {
-    const src = p(ctx.repoDir, "SoT", ".claude", script)
-    if (existsSync(src)) {
-      if (copyFileIfChanged(src, p(claudeDir, script))) changed = true
-      if (ensureExecutable(p(claudeDir, script))) changed = true
-    }
-  }
-  const mp3 = p(ctx.repoDir, "notification.mp3")
-  if (existsSync(mp3) && copyFileIfChanged(mp3, p(claudeDir, "notification.mp3"))) changed = true
+  for (const [script, source] of [
+    ["statusline.sh", "SoT/.claude/statusline.sh"],
+    ["fetch-usage.sh", "SoT/.claude/fetch-usage.sh"]
+  ] as const) {
+    const path = p(claudeDir, script)
+    if (writeTextIfChanged(path, payloadText(source))) changed = true
+    if (ensureExecutable(path)) changed = true
+  }
+  if (writeBytesIfChanged(p(claudeDir, "notification.mp3"), payloadBytes("notification.mp3"))) changed = true
   if (changed) {
     change("Scripts synced (statusline, fetch-usage, notification)")
     ctx.nextStepTriggers.claudeRestart = true
@@ -152,8 +153,7 @@ function shellScriptCount(hooksDir: string): number {
 
 function syncHooks(ctx: Ctx, claudeDir: string): void {
   const { change, echo, verbose } = ctx.services.logger
-  const sotHooks = p(ctx.repoDir, "SoT", ".claude", "hooks")
-  if (!existsSync(sotHooks)) return
+  const sotHooks = payloadDisplayPath("SoT/.claude/hooks/notify.sh", ctx.repoDir).replace(/\/notify\.sh$/, "")
 
   if (ctx.dryRun) {
     echo(`[dry-run] cp -R ${sotHooks}/. ${claudeDir}/hooks/`)
@@ -162,7 +162,7 @@ function syncHooks(ctx: Ctx, claudeDir: string): void {
 
   const hooksDir = p(claudeDir, "hooks")
   mkdirSync(hooksDir, { recursive: true })
-  let changed = copyTreeIfChanged(sotHooks, hooksDir)
+  let changed = writeTextIfChanged(p(hooksDir, "notify.sh"), payloadText("SoT/.claude/hooks/notify.sh"))
   for (const e of readdirSync(hooksDir, { withFileTypes: true })) {
     if (e.isFile() && e.name.endsWith(".sh")) {
       if (ensureExecutable(p(hooksDir, e.name))) changed = true
@@ -193,10 +193,10 @@ function syncClaudeMd(ctx: Ctx, claudeDir: string): void {
     return
   }
 
-  const src = p(ctx.repoDir, "SoT", ".claude", "CLAUDE.md")
+  const source = payloadText("SoT/.claude/CLAUDE.md")
   const stripReason = ctx.skipRtk ? "--skip-rtk" : rtkMdAbsent ? "~/.claude/RTK.md absent (rtk not initialized)" : ""
   if (stripReason !== "") {
-    const stripped = readFileSync(src, "utf8")
+    const stripped = source
       .split("\n")
       .filter((l) => l !== "@RTK.md")
       .join("\n")
@@ -205,7 +205,7 @@ function syncClaudeMd(ctx: Ctx, claudeDir: string): void {
     } else {
       verbose("CLAUDE.md already in sync")
     }
-  } else if (copyFileIfChanged(src, p(claudeDir, "CLAUDE.md"))) {
+  } else if (writeTextIfChanged(p(claudeDir, "CLAUDE.md"), source)) {
     change("CLAUDE.md synced")
   } else {
     verbose("CLAUDE.md already in sync")
@@ -216,7 +216,8 @@ function syncClaudeMd(ctx: Ctx, claudeDir: string): void {
 
 function syncSettings(ctx: Ctx, claudeDir: string): void {
   const { change, echo, err, verbose } = ctx.services.logger
-  const repoSettings = p(ctx.repoDir, "SoT", ".claude", "settings.json")
+  const repoSettings = payloadDisplayPath("SoT/.claude/settings.json", ctx.repoDir)
+  const repoSettingsText = payloadText("SoT/.claude/settings.json")
   const userSettings = p(claudeDir, "settings.json")
 
   if (ctx.dryRun) {
@@ -231,7 +232,7 @@ function syncSettings(ctx: Ctx, claudeDir: string): void {
   }
 
   if (!existsSync(userSettings)) {
-    copyFileSync(repoSettings, userSettings)
+    writeFileSync(userSettings, repoSettingsText)
     change("Settings installed")
     ctx.nextStepTriggers.claudeRestart = true
     return
@@ -243,7 +244,7 @@ function syncSettings(ctx: Ctx, claudeDir: string): void {
     err(`Skipping settings sync: ${userSettings} is not valid JSON. Fix it manually or delete it to reinstall.`)
     throw new ExitError(1)
   }
-  const repo = parseJson(readFileSync(repoSettings, "utf8"))!
+  const repo = parseJson(repoSettingsText)!
 
   const merged = ctx.reconcile ? reconcileSettings(repo, user) : mergeSettings(repo, user)
   const out = jqStringify(merged)
@@ -334,10 +335,8 @@ function syncPermissive(ctx: Ctx, claudeDir: string): void {
 function syncClaudeJson(ctx: Ctx): void {
   const { change, echo, err, verbose } = ctx.services.logger
   const claudeJson = p(ctx.home, ".claude.json")
-  const mcpSot = p(ctx.repoDir, "SoT", ".claude", "mcp-servers.json")
 
-  let mcp: Json | undefined
-  if (existsSync(mcpSot)) mcp = parseJson(readFileSync(mcpSot, "utf8"))
+  const mcp: Json | undefined = parseJson(payloadText("SoT/.claude/mcp-servers.json"))
   const haveMcp = mcp !== undefined
 
   if (ctx.dryRun) {
@@ -564,7 +563,6 @@ function pluginUserScopeInstalled(installedPlugins: string, pluginId: string): b
 
 function syncPlugins(ctx: Ctx, claudeDir: string): void {
   const { change, echo, verbose, warn } = ctx.services.logger
-  const repoSettingsFile = p(ctx.repoDir, "SoT", ".claude", "settings.json")
   const knownMarketplaces = p(claudeDir, "plugins", "known_marketplaces.json")
   const installedPlugins = p(claudeDir, "plugins", "installed_plugins.json")
 
@@ -589,7 +587,7 @@ function syncPlugins(ctx: Ctx, claudeDir: string): void {
     return
   }
 
-  const repoSettings = readJsonFile(repoSettingsFile)
+  const repoSettings = parseJson(payloadText("SoT/.claude/settings.json"))
   const repoObj = repoSettings !== undefined && isObject(repoSettings) ? repoSettings : {}
   const sotMarketplaces = isObject(repoObj["extraKnownMarketplaces"]) ? repoObj["extraKnownMarketplaces"] : {}
   const sotPlugins = isObject(repoObj["enabledPlugins"]) ? repoObj["enabledPlugins"] : {}
@@ -799,7 +797,7 @@ function lspPkg(ctx: Ctx, tool: string, pkg: string): string {
 
 function syncLspServers(ctx: Ctx): void {
   const { change, echo, verbose, warn } = ctx.services.logger
-  const sot = readJsonFile(p(ctx.repoDir, "SoT", ".claude", "settings.json"))
+  const sot = parseJson(payloadText("SoT/.claude/settings.json"))
   const enabled = sot !== undefined && isObject(sot) && isObject(sot["enabledPlugins"]) ? sot["enabledPlugins"] : undefined
   if (enabled === undefined) return
   const hasPhp = Object.prototype.hasOwnProperty.call(enabled, "php-lsp@claude-plugins-official")

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

@@ -4,25 +4,26 @@
  * change. Guard order, message strings, and backup behavior are golden-tested.
  */
 import { spawnSync } from "node:child_process"
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
 
 import { syncCodexModel, replaceTopLevelSettingInFile } from "./codexToml"
 import { p } from "./exec"
 import type { Ctx } from "./index"
 import { compareCodepoints, isObject, jqStringify, parseJson, type Json } from "./jq"
+import { payloadBytes, payloadDisplayPath, payloadPaths, payloadText, type PayloadPath } from "../payload"
 
 export function codexSync(ctx: Ctx): void {
   const codexDir = p(ctx.home, ".codex")
-  const sotConfig = p(ctx.repoDir, "SoT", ".codex", "config.toml")
+  const sotConfig = payloadText("SoT/.codex/config.toml")
   const userConfig = p(codexDir, "config.toml")
 
   ensureBubblewrap(ctx)
   if (!ctx.dryRun) mkdirSync(codexDir, { recursive: true })
   syncConfig(ctx, sotConfig, userConfig)
   syncCodexModel(ctx, ctx.codexModel)
-  syncRules(ctx, p(ctx.repoDir, "SoT", ".codex", "rules"), p(codexDir, "rules"))
-  syncAgentsMd(ctx, p(ctx.repoDir, "SoT", ".codex", "AGENTS.md"), p(codexDir, "AGENTS.md"))
-  syncMarketplace(ctx, p(ctx.repoDir, "SoT", ".codex", "plugins", "marketplace.json"), p(ctx.agentsDir, "plugins", "marketplace.json"))
+  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"))
   removeLegacyDocksMarketplace(ctx, userConfig)
   syncPlugins(ctx, sotConfig)
 }
@@ -95,9 +96,9 @@ function bwrapDetectPmInstallCmd(ctx: Ctx): string {
 
 // --------------------------------------------------------------- config ----
 
-function syncConfig(ctx: Ctx, sotConfig: string, userConfig: string): void {
+function syncConfig(ctx: Ctx, sotConfigText: string, userConfig: string): void {
   const { change, echo, verbose } = ctx.services.logger
-  if (!existsSync(sotConfig)) return
+  const sotConfig = payloadDisplayPath("SoT/.codex/config.toml", ctx.repoDir)
 
   if (ctx.dryRun) {
     echo(`[dry-run] merge ${sotConfig} -> ${userConfig}`)
@@ -105,7 +106,7 @@ function syncConfig(ctx: Ctx, sotConfig: string, userConfig: string): void {
   }
 
   if (!existsSync(userConfig)) {
-    copyFileSync(sotConfig, userConfig)
+    writeFileSync(userConfig, sotConfigText)
     change("Codex config installed")
     ctx.nextStepTriggers.codexRestart = true
     return
@@ -119,8 +120,8 @@ function syncConfig(ctx: Ctx, sotConfig: string, userConfig: string): void {
   writeFileSync(staging, before)
 
   scrubDeprecatedFeatures(ctx, staging)
-  mergeTopLevelSettings(sotConfig, staging)
-  mergeTableSettings(sotConfig, staging)
+  mergeTopLevelSettings(sotConfigText, staging)
+  mergeTableSettings(sotConfigText, staging)
 
   if (readFileSync(staging, "utf8") === before) {
     rmSync(staging, { force: true })
@@ -179,8 +180,8 @@ function scrubDeprecatedFeatures(ctx: Ctx, userConfig: string): void {
   change("Codex: scrubbed deprecated [features].use_legacy_landlock")
 }
 
-function mergeTopLevelSettings(sotConfig: string, userConfig: string): void {
-  for (const line of readFileSync(sotConfig, "utf8").split("\n")) {
+function mergeTopLevelSettings(sotConfigText: string, userConfig: string): void {
+  for (const line of sotConfigText.split("\n")) {
     if (line.startsWith("[")) break
     if (/^[ \t]*($|#)/.test(line)) continue
     if (!/^[A-Za-z0-9_.-]+[ \t]*=/.test(line)) continue
@@ -189,8 +190,8 @@ function mergeTopLevelSettings(sotConfig: string, userConfig: string): void {
   }
 }
 
-function mergeTableSettings(sotConfig: string, userConfig: string): void {
-  const sotLines = readFileSync(sotConfig, "utf8").split("\n")
+function mergeTableSettings(sotConfigText: string, userConfig: string): void {
+  const sotLines = sotConfigText.split("\n")
   for (const tableHeader of sotLines.filter((l) => /^\[[^\]]+\]/.test(l))) {
     // Extract the SoT block: from the exact header line to (excluding) the
     // next table header; `$(...)` strips trailing newlines.
@@ -225,9 +226,12 @@ function mergeTableSettings(sotConfig: string, userConfig: string): void {
 
 // ------------------------------------------------------- rules + agents ----
 
-function syncRules(ctx: Ctx, sotRulesDir: string, userRulesDir: string): void {
+function syncRules(ctx: Ctx, sotRules: ReadonlyArray<PayloadPath>, userRulesDir: string): void {
   const { change, echo, verbose } = ctx.services.logger
-  if (!existsSync(sotRulesDir)) return
+  const firstRule = sotRules[0]
+  if (firstRule === undefined) return
+  const firstDisplay = payloadDisplayPath(firstRule, ctx.repoDir)
+  const sotRulesDir = firstDisplay.slice(0, firstDisplay.lastIndexOf("/"))
 
   if (ctx.dryRun) {
     echo(`[dry-run] cp ${sotRulesDir}/*.rules -> ${userRulesDir}/`)
@@ -237,17 +241,15 @@ function syncRules(ctx: Ctx, sotRulesDir: string, userRulesDir: string): void {
   mkdirSync(userRulesDir, { recursive: true })
   let sawRules = false
   let rulesChanged = false
-  const ruleFiles = readdirSync(sotRulesDir, { withFileTypes: true })
-    .filter((e) => e.isFile() && e.name.endsWith(".rules"))
-    .map((e) => p(sotRulesDir, e.name))
-    .sort(compareCodepoints)
+  const ruleFiles = sotRules.filter((path) => path.endsWith(".rules")).sort(compareCodepoints)
   for (const ruleFile of ruleFiles) {
     sawRules = true
     const userRuleFile = p(userRulesDir, ruleFile.slice(ruleFile.lastIndexOf("/") + 1))
-    const identical = existsSync(userRuleFile) && readFileSync(userRuleFile).equals(readFileSync(ruleFile))
+    const content = payloadBytes(ruleFile)
+    const identical = existsSync(userRuleFile) && readFileSync(userRuleFile).equals(content)
     if (identical) continue
     if (existsSync(userRuleFile)) copyFileSync(userRuleFile, `${userRuleFile}.bak`)
-    copyFileSync(ruleFile, userRuleFile)
+    writeFileSync(userRuleFile, content)
     rulesChanged = true
   }
   if (rulesChanged) {
@@ -256,30 +258,30 @@ function syncRules(ctx: Ctx, sotRulesDir: string, userRulesDir: string): void {
   } else if (sawRules) verbose("Codex rules already in sync")
 }
 
-function syncAgentsMd(ctx: Ctx, sotAgentsMd: string, userAgentsMd: string): void {
+function syncAgentsMd(ctx: Ctx, sotAgentsMdText: string, userAgentsMd: string): void {
   const { change, echo, verbose } = ctx.services.logger
-  if (!existsSync(sotAgentsMd)) return
+  const sotAgentsMd = payloadDisplayPath("SoT/.codex/AGENTS.md", ctx.repoDir)
 
   if (ctx.dryRun) {
     echo(`[dry-run] cp ${sotAgentsMd} -> ${userAgentsMd}`)
     return
   }
 
-  if (existsSync(userAgentsMd) && readFileSync(userAgentsMd).equals(readFileSync(sotAgentsMd))) {
+  if (existsSync(userAgentsMd) && readFileSync(userAgentsMd, "utf8") === sotAgentsMdText) {
     verbose("Codex AGENTS.md already in sync")
     return
   }
   if (existsSync(userAgentsMd)) copyFileSync(userAgentsMd, `${userAgentsMd}.bak`)
-  copyFileSync(sotAgentsMd, userAgentsMd)
+  writeFileSync(userAgentsMd, sotAgentsMdText)
   change("Codex AGENTS.md synced")
   ctx.nextStepTriggers.codexRestart = true
 }
 
 // ---------------------------------------------------------- marketplace ----
 
-function syncMarketplace(ctx: Ctx, sotMarketplace: string, userMarketplace: string): void {
+function syncMarketplace(ctx: Ctx, sotMarketplaceText: string, userMarketplace: string): void {
   const { change, echo, err, verbose } = ctx.services.logger
-  if (!existsSync(sotMarketplace)) return
+  const sotMarketplace = payloadDisplayPath("SoT/.codex/plugins/marketplace.json", ctx.repoDir)
 
   if (ctx.dryRun) {
     echo(`[dry-run] cp ${sotMarketplace} -> ${userMarketplace}`)
@@ -287,7 +289,7 @@ function syncMarketplace(ctx: Ctx, sotMarketplace: string, userMarketplace: stri
   }
 
   mkdirSync(p(ctx.agentsDir, "plugins"), { recursive: true })
-  const repo = parseJson(readFileSync(sotMarketplace, "utf8"))
+  const repo = parseJson(sotMarketplaceText)
   if (repo === undefined) throw new Error(`invalid SoT marketplace JSON: ${sotMarketplace}`)
 
   if (existsSync(userMarketplace)) {
@@ -307,7 +309,7 @@ function syncMarketplace(ctx: Ctx, sotMarketplace: string, userMarketplace: stri
     change("Codex marketplace merged (backup at marketplace.json.bak)")
     ctx.nextStepTriggers.codexRestart = true
   } else {
-    copyFileSync(sotMarketplace, userMarketplace)
+    writeFileSync(userMarketplace, sotMarketplaceText)
     change("Codex marketplace installed")
     ctx.nextStepTriggers.codexRestart = true
   }
@@ -390,13 +392,17 @@ const standaloneInstallCommand = (ctx: Ctx): string => ctx.services.deps.spec("c
 /** codex::_enabled_plugin_ids — [plugins."<id>"] tables with enabled = true. */
 export function enabledPluginIds(configFile: string): Array<string> {
   if (!existsSync(configFile)) return []
+  return enabledPluginIdsFromText(readFileSync(configFile, "utf8"))
+}
+
+export function enabledPluginIdsFromText(configText: string): Array<string> {
   const ids: Array<string> = []
   let plugin = ""
   let enabled = false
   const flush = (): void => {
     if (plugin !== "" && enabled) ids.push(plugin)
   }
-  for (const line of readFileSync(configFile, "utf8").split("\n")) {
+  for (const line of configText.split("\n")) {
     const m = /^\[plugins\."([^"]+)"\][ \t]*$/.exec(line)
     if (m !== null) {
       flush()
@@ -418,12 +424,12 @@ export function enabledPluginIds(configFile: string): Array<string> {
   return ids
 }
 
-function manualPluginRefreshCommand(sotConfig: string): string {
-  const first = enabledPluginIds(sotConfig)[0]
+function manualPluginRefreshCommand(sotConfigText: string): string {
+  const first = enabledPluginIdsFromText(sotConfigText)[0]
   return first !== undefined ? `codex plugin add ${first}` : "codex plugin add <plugin@marketplace>"
 }
 
-function syncPlugins(ctx: Ctx, sotConfig: string): void {
+function syncPlugins(ctx: Ctx, sotConfigText: string): void {
   const { change, echo, warn } = ctx.services.logger
   if (ctx.dryRun) {
     echo("[dry-run] add enabled Codex plugins from SoT")
@@ -432,7 +438,7 @@ function syncPlugins(ctx: Ctx, sotConfig: string): void {
 
   if (ctx.services.deps.probe("codex").state === "missing") {
     warn(
-      `codex CLI not in PATH - deployed config/marketplace only; install Codex with: ${standaloneInstallCommand(ctx)} | docs: https://developers.openai.com/codex/cli; then run: ${manualPluginRefreshCommand(sotConfig)}`
+      `codex CLI not in PATH - deployed config/marketplace only; install Codex with: ${standaloneInstallCommand(ctx)} | docs: https://developers.openai.com/codex/cli; then run: ${manualPluginRefreshCommand(sotConfigText)}`
     )
     return
   }
@@ -447,7 +453,7 @@ function syncPlugins(ctx: Ctx, sotConfig: string): void {
 
   let refreshed = 0
   let failed = 0
-  for (const pluginId of enabledPluginIds(sotConfig)) {
+  for (const pluginId of enabledPluginIdsFromText(sotConfigText)) {
     const res = spawnSync("codex", ["plugin", "add", pluginId], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
     const addOut = `${res.stdout ?? ""}${res.stderr ?? ""}`
     if (res.error === undefined && res.status === 0) {

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

@@ -4,7 +4,7 @@
  * substitution: stdout with trailing newlines stripped, empty on failure.
  */
 import { spawnSync } from "node:child_process"
-import { accessSync, chmodSync, constants, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs"
+import { accessSync, chmodSync, constants, existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
 import { delimiter, isAbsolute, join } from "node:path"
 
 /**
@@ -69,34 +69,19 @@ export function ensureExecutable(path: string): boolean {
   return true
 }
 
-export function writeFileIfChanged(path: string, content: string): boolean {
+export function writeTextIfChanged(path: string, content: string): boolean {
   if (existsSync(path) && readFileSync(path, "utf8") === content) return false
   writeFileSync(path, content)
   return true
 }
 
-/** Copy only when dest differs from src; returns whether a copy happened. */
-export function copyFileIfChanged(src: string, dest: string): boolean {
-  if (existsSync(dest) && readFileSync(dest).equals(readFileSync(src))) return false
-  copyFileSync(src, dest)
+export function writeBytesIfChanged(path: string, content: Uint8Array): boolean {
+  const bytes = Buffer.from(content)
+  if (existsSync(path) && readFileSync(path).equals(bytes)) return false
+  writeFileSync(path, bytes)
   return true
 }
 
-/** Recursive copy via copyFileIfChanged; returns whether anything changed. */
-export function copyTreeIfChanged(srcDir: string, destDir: string): boolean {
-  let changed = false
-  for (const e of readdirSync(srcDir, { withFileTypes: true })) {
-    const src = p(srcDir, e.name)
-    const dest = p(destDir, e.name)
-    if (e.isDirectory()) {
-      if (!existsSync(dest)) {
-        mkdirSync(dest, { recursive: true })
-        changed = true
-      }
-      if (copyTreeIfChanged(src, dest)) changed = true
-    } else if (copyFileIfChanged(src, dest)) {
-      changed = true
-    }
-  }
-  return changed
+export function writeFileIfChanged(path: string, content: string): boolean {
+  return writeTextIfChanged(path, content)
 }

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

@@ -6,7 +6,6 @@
  * vocabulary directly.
  */
 import { p } from "./exec"
-import { existsSync } from "node:fs"
 import { homedir } from "node:os"
 
 import { kitHome } from "../kitHome"
@@ -81,13 +80,13 @@ function engineSync(ctx: Ctx, args: ReadonlyArray<string>): number {
   preflight(ctx)
   validateModelFlags(ctx)
 
-  const claudeRan = ctx.syncClaude && existsSync(p(ctx.repoDir, "SoT", ".claude"))
+  const claudeRan = ctx.syncClaude
   if (claudeRan) claudeSync(ctx)
 
-  const codexRan = ctx.syncCodex && existsSync(p(ctx.repoDir, "SoT", ".codex"))
+  const codexRan = ctx.syncCodex
   if (codexRan) codexSync(ctx)
 
-  const skillsState = ctx.syncAgents && existsSync(p(ctx.repoDir, "SoT", ".agents")) ? skillsSync(ctx) : undefined
+  const skillsState = ctx.syncAgents ? skillsSync(ctx) : undefined
 
   echo("")
   echo("--- Sync complete ---")