docks-kit 0.16.7 → 0.16.8

package/AGENTS.md

@@ -63,10 +63,10 @@ Codex SoT notes:
 omp SoT notes:
 - `SoT/.omp/AGENTS.md`, `config.yml`, `models.yml`, and `mcp.json` deploy to `~/.omp/agent/`.
 - `SoT/.omp/intercom.json` deploys to `$PI_CODING_AGENT_DIR/intercom/config.json`. The default root is `~/.pi/agent`.
-- `ompSync.ts syncMergedYaml` deep-merges `config.yml` through `mergeOmpConfig`.
+- `ompSync.ts syncMergedYaml` deep-merges `config.yml` through `ompYaml.ts mergeOmpConfig` and `models.yml` through `mergeOmpModels`. Both wrap one generic mapping merge; only the config wrapper prunes stale `retry.fallbackChains` wildcards.
 - `cycleOrder` ends with the `fable` role (`modelRoles.fable` = `anthropic/claude-fable-5-1:medium`, `modelTags.fable` visible, `retry.fallbackChains.fable` empty), so the model switcher reaches Fable 5.1 as its fourth stop and never falls back off it. The hidden `switch_fable` role points at the same model and level.
 - `modelRoles.task` is `openai-codex/gpt-6-astra:low`, chosen for 2.60 s TTFT and 4k output tokens per task at cost parity with the previous `gpt-5.6-sol:high`. `task.agentModelOverrides` points four reviewer names at `@task`; only the bundled `reviewer` and `security-reviewer` are discoverable OMP agents, so those two inherit `task`, and the `code-reviewer` and `plan-reviewer` entries are dormant. Artificial Analysis publishes no per-level Astra Coding Agent Index score, so reviewer output is the signal to watch.
-- `SoT/.omp/models.yml` deploys to `~/.omp/agent/models.yml` through the same `mergeOmpConfig` merge as `config.yml`. A user file may carry provider credentials, so whole-file replacement is wrong. It restricts the `gpt-6-astra` effort ladder to `low`, so every Astra subagent runs `low` while `task.maxEffort: high` lets `scout` and `sonic` reach Luna `high` with `effort: hi`. `ompSync.ts syncMergedYaml` owns both YAML deployments. `cli/docs/omp-models.md` records the verification.
+- `SoT/.omp/models.yml` deploys to `~/.omp/agent/models.yml` through `mergeOmpModels`, which keeps every deployed-only key. A user file may carry provider credentials, so whole-file replacement is wrong. It restricts the `gpt-6-astra` effort ladder to `low`, so every Astra subagent runs `low` while `task.maxEffort: high` lets `scout` and `sonic` reach Luna `high` with `effort: hi`. `cli/docs/omp-models.md` records the verification.
 - `SoT/.omp/AGENTS.md` carries the rule `Please remove all mannered prose.` Anthropic's Fable 5.1 prompting guide documents mannered prose as a Fable 5.1 behavior and gives that sentence as its short-version fix: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1
 - `cli/docs/omp-models.md` (topic `omp-models`) records the role map rationale and the Artificial Analysis snapshot behind it. Model choices change with published benchmarks, so update that topic in the same commit as a role change.
 - Sync registers the `docks` marketplace. It installs or upgrades `docks@docks` and `plan-lifecycle@docks` at user scope.

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

@@ -14,7 +14,7 @@ import { p, spawnProcess, type AsyncProcessResult } from "./exec"
 import type { Ctx } from "./index"
 import { isObject, parseJson } from "./jq"
 import { ompPaths } from "./ompPaths"
-import { mergeOmpConfig } from "./ompYaml"
+import { mergeOmpConfig, mergeOmpModels } from "./ompYaml"
 import { field } from "./toolchain"
 
 const MARKETPLACE_NAME = "docks"
@@ -35,8 +35,8 @@ export async function ompSync(ctx: Ctx): Promise<OmpState> {
 
   syncWholeFile(ctx, "SoT/.omp/AGENTS.md", p(agentDir, "AGENTS.md"), "omp AGENTS.md already in sync", "omp AGENTS.md synced")
   syncWholeFile(ctx, "SoT/.omp/mcp.json", p(agentDir, "mcp.json"), "omp mcp.json already in sync", "omp mcp.json synced")
-  syncMergedYaml(ctx, "SoT/.omp/config.yml", p(agentDir, "config.yml"))
-  syncMergedYaml(ctx, "SoT/.omp/models.yml", p(agentDir, "models.yml"))
+  syncMergedYaml(ctx, "SoT/.omp/config.yml", p(agentDir, "config.yml"), mergeOmpConfig)
+  syncMergedYaml(ctx, "SoT/.omp/models.yml", p(agentDir, "models.yml"), mergeOmpModels)
 
   const intercomRootSetting = process.env["PI_CODING_AGENT_DIR"]
   const intercomRoot = intercomRootSetting !== undefined && intercomRootSetting !== ""
@@ -112,7 +112,12 @@ function syncWholeFile(
   ctx.nextStepTriggers.ompRestart = true
 }
 
-function syncMergedYaml(ctx: Ctx, sourcePath: OmpTextPayloadPath, target: string): void {
+function syncMergedYaml(
+  ctx: Ctx,
+  sourcePath: OmpTextPayloadPath,
+  target: string,
+  merge: (sotText: string, deployedText: string) => string
+): void {
   const { change, echo, verbose } = ctx.services.logger
   const source = payloadDisplayPath(sourcePath)
   const sotText = payloadText(sourcePath)
@@ -130,7 +135,7 @@ function syncMergedYaml(ctx: Ctx, sourcePath: OmpTextPayloadPath, target: string
   }
 
   const deployedText = readFileSync(target, "utf8")
-  const merged = mergeOmpConfig(sotText, deployedText)
+  const merged = merge(sotText, deployedText)
   if (merged === deployedText) {
     verbose(`omp ${name} already in sync`)
     return

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

@@ -1,12 +1,18 @@
 /**
- * YAML merge for the omp config.yml and models.yml files.
- * The kit uses the yaml package rather than a line-based merge. Deployed-only keys are
- * retained except for slash-bearing keys directly under retry.fallbackChains:
- * omp treats those as model or provider wildcards ahead of role chains, so a
- * stale wildcard would silently override the kit-managed role chains.
+ * YAML merge for the omp config.yml and models.yml files. omp serialises both
+ * files itself, so the kit uses the yaml package rather than a line-based
+ * merge. Deployed-only keys are retained, except where the file-specific
+ * wrapper drops them: config.yml drops slash-bearing keys directly under
+ * retry.fallbackChains, because omp treats those as model or provider
+ * wildcards ahead of role chains, so a stale wildcard would silently override
+ * the kit-managed role chains. models.yml drops nothing; a user file may carry
+ * provider credentials and custom models the kit never declares.
  */
 import { isMap, isScalar, parseDocument, type YAMLMap } from "yaml"
 
+/** Decides whether a deployed-only key at `path` is dropped instead of kept. */
+type DropDeployedKey = (path: ReadonlyArray<string>, key: string) => boolean
+
 const fallbackChainsPath = ["retry", "fallbackChains"] as const
 
 function stringKey(key: unknown): string | undefined {
@@ -15,29 +21,31 @@ function stringKey(key: unknown): string | undefined {
   return undefined
 }
 
-function isFallbackChains(path: ReadonlyArray<string>): boolean {
-  return (
-    path.length === fallbackChainsPath.length &&
-    path[0] === fallbackChainsPath[0] &&
-    path[1] === fallbackChainsPath[1]
-  )
+function keyName(key: unknown): string {
+  return isScalar(key) ? String(key.value) : String(key)
 }
 
-function pruneFallbackWildcards(mapping: YAMLMap, path: ReadonlyArray<string>): void {
-  const underFallbackChains = isFallbackChains(path)
+const dropFallbackWildcard: DropDeployedKey = (path, key) =>
+  path.length === fallbackChainsPath.length &&
+  path[0] === fallbackChainsPath[0] &&
+  path[1] === fallbackChainsPath[1] &&
+  key.includes("/")
+
+const keepEveryKey: DropDeployedKey = () => false
+
+function pruneMapping(mapping: YAMLMap, path: ReadonlyArray<string>, drop: DropDeployedKey): void {
   for (let index = mapping.items.length - 1; index >= 0; index--) {
     const pair = mapping.items[index]
     if (pair === undefined) continue
 
-    const keyName = isScalar(pair.key) ? String(pair.key.value) : String(pair.key)
-    if (underFallbackChains && keyName.includes("/")) {
+    if (drop(path, keyName(pair.key))) {
       mapping.items.splice(index, 1)
       continue
     }
 
     const key = stringKey(pair.key)
     if (key !== undefined && isMap(pair.value)) {
-      pruneFallbackWildcards(pair.value, [...path, key])
+      pruneMapping(pair.value, [...path, key], drop)
     }
   }
 }
@@ -45,7 +53,8 @@ function pruneFallbackWildcards(mapping: YAMLMap, path: ReadonlyArray<string>):
 function mergeMappings(
   sotMapping: YAMLMap,
   deployedMapping: YAMLMap,
-  path: ReadonlyArray<string>
+  path: ReadonlyArray<string>,
+  drop: DropDeployedKey
 ): void {
   for (const sotPair of sotMapping.items) {
     const key = stringKey(sotPair.key)
@@ -53,7 +62,7 @@ function mergeMappings(
 
     const deployedPair = deployedMapping.items.find((candidate) => stringKey(candidate.key) === key)
     if (deployedPair !== undefined && isMap(sotPair.value) && isMap(deployedPair.value)) {
-      mergeMappings(sotPair.value, deployedPair.value, [...path, key])
+      mergeMappings(sotPair.value, deployedPair.value, [...path, key], drop)
     }
   }
 
@@ -63,22 +72,24 @@ function mergeMappings(
       key !== undefined && sotMapping.items.some((candidate) => stringKey(candidate.key) === key)
     if (isManaged) continue
 
-    const keyName = isScalar(deployedPair.key)
-      ? String(deployedPair.key.value)
-      : String(deployedPair.key)
-    if (isFallbackChains(path) && keyName.includes("/")) continue
+    if (drop(path, keyName(deployedPair.key))) continue
     if (key !== undefined && isMap(deployedPair.value)) {
-      pruneFallbackWildcards(deployedPair.value, [...path, key])
+      pruneMapping(deployedPair.value, [...path, key], drop)
     }
     sotMapping.items.push(deployedPair)
   }
 }
 
-export function mergeOmpConfig(sotText: string, deployedText: string): string {
+function mergeYamlDocuments(
+  sotText: string,
+  deployedText: string,
+  name: string,
+  drop: DropDeployedKey
+): string {
   const deployedDoc = parseDocument(deployedText)
   const deployedError = deployedDoc.errors[0]
   if (deployedError !== undefined) {
-    throw new Error(`Invalid deployed omp YAML: ${deployedError.message}`)
+    throw new Error(`Invalid deployed omp ${name} YAML: ${deployedError.message}`)
   }
 
   const deployedContents = deployedDoc.contents
@@ -90,18 +101,28 @@ export function mergeOmpConfig(sotText: string, deployedText: string): string {
     return sotText
   }
   if (!isMap(deployedContents)) {
-    throw new Error("Deployed omp YAML root must be a mapping")
+    throw new Error(`Deployed omp ${name} YAML root must be a mapping`)
   }
 
   const sotDoc = parseDocument(sotText)
   const sotError = sotDoc.errors[0]
   if (sotError !== undefined) {
-    throw new Error(`Invalid SoT omp YAML: ${sotError.message}`)
+    throw new Error(`Invalid SoT omp ${name} YAML: ${sotError.message}`)
   }
   if (!isMap(sotDoc.contents)) {
-    throw new Error("SoT omp YAML root must be a mapping")
+    throw new Error(`SoT omp ${name} YAML root must be a mapping`)
   }
 
-  mergeMappings(sotDoc.contents, deployedContents, [])
+  mergeMappings(sotDoc.contents, deployedContents, [], drop)
   return sotDoc.toString()
 }
+
+/** config.yml merge: keeps user-only keys, drops stale fallback-chain wildcards. */
+export function mergeOmpConfig(sotText: string, deployedText: string): string {
+  return mergeYamlDocuments(sotText, deployedText, "config.yml", dropFallbackWildcard)
+}
+
+/** models.yml merge: keeps every user-only key, including credentials and custom models. */
+export function mergeOmpModels(sotText: string, deployedText: string): string {
+  return mergeYamlDocuments(sotText, deployedText, "models.yml", keepEveryKey)
+}

package/cli/src/generated/sotPayload.ts

@@ -1,7 +1,7 @@
 // Generated by cli/scripts/generate-sot-payload.ts. DO NOT EDIT.
 // Edit SoT/, notification.mp3, or package.json, then run: bun cli/scripts/generate-sot-payload.ts
 
-export const GENERATED_PACKAGE_VERSION = "0.16.7"
+export const GENERATED_PACKAGE_VERSION = "0.16.8"
 
 export const GENERATED_PAYLOAD_TEXT = {
   "SoT/.agents/skills.txt": "# Universal AI-agent skill manifest intentionally empty.\n# Global skill discovery is opt-in: add one <owner>/<repo> slug per line.\n# EngineNative ignores comments and blank lines.\n",
@@ -21,7 +21,7 @@ export const GENERATED_PAYLOAD_TEXT = {
   "SoT/.omp/config.yml": "symbolPreset: unicode\n\ntheme:\n  dark: titanium\n\nstatusLine:\n  preset: default\n  compactThinkingLevel: false\n  showHookStatus: true\n  sessionAccent: true\n  transparent: false\n\nterminal:\n  showProgress: false\n\ntui:\n  textSizing: false\n  tight: false\n\ndefaultThinkingLevel: high\n\ncycleOrder:\n  - smol\n  - default\n  - slow\n  - fable\n\ntier:\n  openai: none\n  anthropic: none\n\nadvisor:\n  enabled: true\n  syncBacklog: \"1\"\n\ngithub:\n  enabled: true\n\ntask:\n  eager: always\n  showResolvedModelBadge: true\n  softRequestBudget: 200\n  softRequestBudgetNotice: true\n  batch: true\n  enableLsp: true\n  enableEffort: true\n  maxEffort: high\n  maxConcurrency: 16\n  maxRecursionDepth: 2\n  maxRuntimeMs: 3600000\n  agentModelOverrides:\n    reviewer: \"@task\"\n    security-reviewer: \"@task\"\n    code-reviewer: \"@task\"\n    plan-reviewer: \"@task\"\n\nmodelRoles:\n  smol: openai-codex/gpt-5.6-luna:medium\n  advisor: openai-codex/gpt-5.6-sol:medium\n  designer: anthropic/claude-opus-5:high\n  plan: anthropic/claude-opus-5:xhigh\n  commit: openai-codex/gpt-5.6-luna:medium\n  task: openai-codex/gpt-6-astra:low\n  vision: anthropic/claude-opus-5:medium\n  tiny: openai-codex/gpt-5.6-luna:low\n  default: anthropic/claude-opus-5:high\n  slow: anthropic/claude-opus-5:xhigh\n  fable: anthropic/claude-fable-5-1:medium\n  switch_fable: anthropic/claude-fable-5-1:medium\n\nmodelTags:\n  fable:\n    name: Fable 5.1\n  switch_fable:\n    name: Fable switch default\n    hidden: true\n\ndisplay:\n  shimmer: classic\n  showTokenUsage: true\n\nproviders:\n  anthropic:\n    serverSideFallback: false\n  fetch: auto\n  webSearchTimeoutSeconds: 30\n  webSearchOrder:\n    - firecrawl\n    - exa\n    - perplexity\n    - gemini\n    - codex\n\nretry:\n  usageAwareFallback: true\n  fallbackChains:\n    default:\n      - openai-codex/gpt-5.6-sol:high\n    advisor:\n      - anthropic/claude-opus-5:medium\n    task:\n      - anthropic/claude-opus-5:high\n    vision:\n      - openai-codex/gpt-5.6-sol:medium\n    smol:\n      - anthropic/claude-opus-5:low\n    tiny:\n      - anthropic/claude-opus-5:low\n    commit:\n      - anthropic/claude-opus-5:medium\n    switch_fable: []\n    fable: []\n\nomitThinking: false\nincludeWorkspaceTree: false\nautocompleteMaxVisible: 10\nemojiAutocomplete: true\n\nbranchSummary:\n  enabled: true\n\nreadLineNumbers: false\n\ncommands:\n  enableOpencodeProject: false\n  enableOpencodeUser: false\n\nskills:\n  enableClaudeUser: false\n  enableCodexUser: false\n  enableAgentsUser: true\n\nsteeringMode: all\ninterruptMode: immediate\n\ndev:\n  autoqa: false\n  autoqaConsent: denied\n\ncompaction:\n  thresholdTokens: 231200\n  idleEnabled: true\n  handoffSaveToDisk: true\n\ndoubleEscapeAction: tree\nhideThinkingBlock: false\nautoResume: false\ntextVerbosity: low\n\nfeatures:\n  unexpectedStopDetection: smart\n\ncodexResets:\n  autoRedeem: \"no\"\n\nstartup:\n  quiet: true\n  changelogMode: summary\n\ntools:\n  approvalMode: yolo\n",
   "SoT/.omp/intercom.json": "{\n  \"brokerCommand\": \"bun\",\n  \"brokerArgs\": []\n}\n",
   "SoT/.omp/mcp.json": "{\n  \"$schema\": \"https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json\",\n  \"disabledServers\": [\n    \"chrome-devtools\",\n    \"context7:context7\",\n    \"openaiDeveloperDocs\"\n  ]\n}\n",
-  "SoT/.omp/models.yml": "providers:\n  openai-codex:\n    modelOverrides:\n      gpt-6-astra:\n        thinking:\n          mode: effort\n          efforts: [low]\n          defaultLevel: low\n"
+  "SoT/.omp/models.yml": "providers:\n  openai-codex:\n    modelOverrides:\n      gpt-6-astra:\n        thinking:\n          mode: effort\n          efforts:\n            - low\n          defaultLevel: low\n"
 } as const
 
 export const GENERATED_PAYLOAD_BASE64 = {
@@ -50,4 +50,4 @@ export const GENERATED_PAYLOAD_PATHS = [
   "notification.mp3"
 ] as const
 
-export const GENERATED_PAYLOAD_HASH = "a6afdeb3a37285dda06cb48bcf39b5a42702e8d06bf9c47f590047ba6c767bc9"
+export const GENERATED_PAYLOAD_HASH = "5f9f8b3d00c15f6611af2bd8d92bbfcd12481442ff6e0e249846ac2e320b4e37"

package/package.json

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