docks-kit 0.20.0 → 0.20.1

package/AGENTS.md

@@ -78,7 +78,7 @@ omp SoT notes:
 - `modelRoles.task` is `openai-codex/gpt-6-sol:high`. `advisor` is `anthropic/claude-opus-5-5:medium` with an empty fallback chain, because a GPT-6 Sol advisor looped on repeated reads under an Opus 5.5 session; never put GPT-6 Sol in the advisor role or chain. `smol`, `commit`, and `tiny` use `openai-codex/gpt-6-luna`. The four reviewer entries in `task.agentModelOverrides` inherit `task` through `@task`. Only bundled `reviewer` and `security-reviewer` are discoverable OMP agents; `code-reviewer` and `plan-reviewer` stay dormant. omp 18.2.9 did not list `gpt-6-sol` or `gpt-6-luna` in its `openai-codex` catalog and fuzzy-matched both selectors to the GPT-5.6 models. omp 18.3.1 lists both ids and serves them as named. The `SoT/toolchain.json` omp floor is 18.3.1 because it is the oldest release the kit tested; releases 18.2.10 to 18.3.0 were not tested. `cli/docs/omp-models.md` records the checks.
 - The five Anthropic roles (`default`, `slow`, `plan`, `designer`, `vision`) and the five Anthropic retry chains use `anthropic/claude-opus-5-5` at the levels the role map records. `cli/docs/omp-models.md` carries the Artificial Analysis capture behind the role map, read 2026-09-22 at Intelligence Index v4.3.2 and Coding Agent Index v1.5 from the AA comparison-page metric tables. Opus 5.5 max has the highest index in that topic. AA has not measured speed or latency for Opus 5.5 max, GPT-6 Sol, or GPT-6 Luna.
 - `modelRoles.web` is `web/firecrawl` and `retry.fallbackChains.web` carries the explicit 20-entry provider order. The kit declares both keys because the legacy `providers.webSearchOrder` key is retired: omp expands it in memory into these two keys and then drops it, and never writes that expansion back to disk. An explicit chain replaces omp's built-in web order wholesale, so every entry left out is a provider omp never tries. The owner removed the seven entries that named older models (Gemini 2.5 Flash, Claude Haiku 4.5, GPT-5.6, GPT-5.5, and Grok 4.5); keep every other provider.
-- `SoT/.omp/models.yml` declares Astra's full `low, medium, high, xhigh, max` ladder with `defaultLevel: xhigh` as the worked provider ladder-override example. It also carries a temporary `anthropic.modelOverrides.claude-opus-5-5` block with that model's limits, ladder, and prices, because the shared catalog still serves the id as a stub with null limits and zero cost; remove the block once the catalog publishes the row. `ompYaml.ts mergeOmpModels` preserves deployed-only keys in `~/.omp/agent/models.yml`, because a user file may carry provider credentials. Whole-file replacement is wrong.
+- `SoT/.omp/models.yml` declares Astra's full `low, medium, high, xhigh, max` ladder with `defaultLevel: xhigh` as the worked provider ladder-override example. The temporary `anthropic.modelOverrides.claude-opus-5-5` block is gone, because the shared catalog now publishes the same limits, ladder, and prices. `ompRemovals.ts syncOmpModelRemovals, retired-block inventory` prunes it from `~/.omp/agent/models.yml` after the models merge, but only while the deployed block still equals the shipped one. `ompYaml.ts mergeOmpModels` preserves deployed-only keys in `~/.omp/agent/models.yml`, because a user file may carry provider credentials. Whole-file replacement is wrong.
 - `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.
 - `SoT/.omp/config.yml` sets `compaction.thresholdTokens` to `-1`, omp's schema default sentinel selecting reserve-based behavior: the trigger becomes `contextWindow` minus `max(floor(contextWindow * 0.15), 16384)`, which is 231,200 on the 272,000-token Codex window and 850,000 on the 1,000,000-token Anthropic window. The key ships as `-1` rather than being deleted because `ompYaml.ts mergeOmpConfig` is additive, so removing a key from SoT never removes it from a deployed file. `cli/docs/omp-context.md` (topic `omp-context`) carries the derivation and the measured evidence, so update that topic in the same commit as any compaction-setting change.

package/cli/docs/omp-models.md

@@ -182,10 +182,12 @@ write, which the AA comparison table does not show. Context 1M, maximum output
 Index in this topic at this capture. AA has not measured speed or latency for
 max. It measures a longer TTFT for medium than for high.
 
-`SoT/.omp/models.yml` carries the Anthropic limits and prices as an `anthropic`
-`modelOverrides` block, because the shared catalog still serves this id as a
-stub with null limits and zero cost. Remove that block once the catalog
-publishes the row.
+Until 0.20.1, `SoT/.omp/models.yml` carried the Anthropic limits and prices as
+an `anthropic` `modelOverrides` block, because the shared catalog served this
+id as a stub with null limits and zero cost. On 2026-09-25 the catalog at
+`catalog.stencil.so` published the same context window, output cap, ladder,
+and prices, so the block was removed. Sync prunes the deployed copy only while
+it still equals the shipped block.
 
 ### Claude Fable 5.1 (Anthropic) - `anthropic/claude-fable-5-1`
 

package/cli/docs/toolchain.md

@@ -78,7 +78,11 @@ these alone and warns:
 - `typescript-language-server` when Node is older than the `node` floor.
 
 When the PATH copy of an npm-owned server is outside `npm prefix -g`, it warns
-that the upgrade changes only the npm copy. A package that is not installed
+that the upgrade changes only the npm copy. The check follows links and
+accepts only a file inside the package directory
+(`<prefix>/lib/node_modules/<pkg>` on POSIX), so a link from another PATH
+directory into it counts as the npm copy, while a distro binary under a
+`/usr` prefix does not. On Windows, a shim in `<prefix>` counts. A package that is not installed
 stays missing, because `sync claude` owns first installs. A failed npm call
 exits 1. After the install, it reads `npm ls -g` again and exits 1 when a
 package is not at its pin.

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

@@ -6,7 +6,8 @@
  * and spawned argv are part of the contract.
  */
 import { defaultProbeExecutor, npmGlobalVersions, type ToolId } from "./deps";
-import { capture, p, spawnProcess } from "./exec";
+import { realpathSync } from "node:fs";
+import { capture, spawnProcess } from "./exec";
 import type { Ctx } from "./index";
 import { isObject, parseJson } from "./jq";
 import { belowFloor, field, installedVersion, isNewer } from "./toolchain";
@@ -177,12 +178,30 @@ export async function upgradeLspServers(ctx: Ctx): Promise<number> {
   const owned = await npmGlobalVersions(defaultProbeExecutor);
   const prefix = await capture("npm", ["prefix", "-g"]);
   const windows = ctx.services.platform.name() === "windows";
-  // npm links global executables into <prefix>/bin on POSIX and into <prefix> on Windows.
-  const npmBin = prefix === "" ? "" : windows ? prefix : p(prefix, "bin");
   const comparable = (path: string): string => {
     const slashed = path.replaceAll("\\", "/");
     return windows ? slashed.toLowerCase() : slashed;
   };
+  const resolved = (path: string): string => {
+    try {
+      return realpathSync(path);
+    } catch {
+      return path;
+    }
+  };
+  // A PATH entry is the npm copy of `pkg` when the file it resolves to lies in
+  // that package's own directory: <prefix>/lib/node_modules/<pkg> on POSIX,
+  // where npm's bin entries are links into it. Any other file under the prefix
+  // does not count, because a system Node uses /usr or /usr/local as its prefix
+  // and distro binaries live there too. npm writes Windows shims straight into
+  // <prefix> instead of linking, so there a shim in <prefix> itself counts.
+  const npmRoot = prefix === "" ? "" : `${comparable(resolved(prefix))}/`;
+  const isNpmCopy = (path: string, pkg: string): boolean => {
+    const packageDir = `${npmRoot}${windows ? "" : "lib/"}node_modules/${comparable(pkg)}/`;
+    if (comparable(resolved(path)).startsWith(packageDir)) return true;
+    const entry = comparable(path);
+    return windows && entry.slice(0, entry.lastIndexOf("/") + 1) === `${comparable(prefix)}/`;
+  };
 
   const targets: Array<readonly [string, string]> = [];
   const moves: Array<string> = [];
@@ -202,13 +221,9 @@ export async function upgradeLspServers(ctx: Ctx): Promise<number> {
       }
       continue;
     }
-    if (
-      onPath !== "" &&
-      npmBin !== "" &&
-      !comparable(onPath).startsWith(`${comparable(npmBin)}/`)
-    ) {
+    if (onPath !== "" && npmRoot !== "" && !isNpmCopy(onPath, pkg)) {
       warn(
-        `${tool} on PATH is ${onPath}, not the npm global copy in ${npmBin}; an upgrade changes only the npm copy`,
+        `${tool} on PATH is ${onPath}, not the npm global copy under ${prefix}; an upgrade changes only the npm copy`,
       );
     }
     if (!isNewer(verified, installed)) {

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

@@ -1,13 +1,14 @@
 /**
- * EngineNative `sync omp` retired-key pruning. `ompYaml.ts mergeOmpConfig` is
- * additive: its `mergeMappings, deployed-key retention loop` returns every
- * deployed key absent from the SoT to the merged result. Removing a key from
- * `SoT/.omp/config.yml` therefore never removes it from an existing
- * `~/.omp/agent/config.yml`. This pass force-prunes an inventory of retired
- * kit-owned keys on every sync, without `--reconcile`. Message strings and
- * prune semantics are part of the contract.
+ * EngineNative `sync omp` retired-key pruning. `ompYaml.ts mergeOmpConfig` and
+ * `mergeOmpModels` are additive: their `mergeMappings, deployed-key retention
+ * loop` returns every deployed key absent from the SoT to the merged result.
+ * Removing a key from `SoT/.omp/config.yml` or `SoT/.omp/models.yml` therefore
+ * never removes it from the deployed file. This pass force-prunes an inventory
+ * of retired kit-owned keys on every sync, without `--reconcile`. Message
+ * strings and prune semantics are part of the contract.
  */
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { isDeepStrictEqual } from "node:util";
 import { isMap, isScalar, parseDocument, type YAMLMap } from "yaml";
 import type { Ctx } from "./index";
 
@@ -49,6 +50,37 @@ const OMP_RETIRED_VALUES: ReadonlyArray<readonly [string, RetiredScalar]> = [
  */
 const OMP_RETIRED_KEYS: ReadonlyArray<string> = ["providers.webSearchOrder"];
 
+/**
+ * models.yml blocks the kit used to deploy, each with the exact value it
+ * deployed. A block is pruned only while the deployed block still equals that
+ * value, so a user edit survives.
+ *
+ * `claude-opus-5-5` carried limits, ladder, and prices while the shared catalog
+ * served the id as an empty stub. The catalog now publishes the same limits,
+ * prices, and ladder. The block's `defaultLevel: high` applied only to a bare
+ * selector, and every kit selector names its level.
+ */
+const OMP_RETIRED_MODEL_BLOCKS: ReadonlyArray<readonly [string, unknown]> = [
+  [
+    "providers.anthropic.modelOverrides.claude-opus-5-5",
+    {
+      name: "Claude Opus 5.5",
+      reasoning: true,
+      input: ["text", "image"],
+      contextWindow: 1000000,
+      maxTokens: 128000,
+      cost: { input: 4, output: 20, cacheRead: 0.2, cacheWrite: 5 },
+      thinking: {
+        mode: "effort",
+        efforts: ["low", "medium", "high", "xhigh", "max"],
+        defaultLevel: "high",
+      },
+    },
+  ],
+];
+
+type RetiredEntry = readonly [string, (node: unknown) => boolean];
+
 function indexOfKey(mapping: YAMLMap, key: string): number {
   return mapping.items.findIndex((pair) => {
     const name: unknown = pair.key;
@@ -122,38 +154,63 @@ function deletePath(
   return true;
 }
 
-/** Prunes retired kit-owned keys from a deployed omp config.yml. */
-export function syncOmpRemovals(ctx: Ctx, configFile: string): number {
+/** Prunes each matching retired entry from one deployed omp YAML file. */
+function pruneRetired(
+  ctx: Ctx,
+  file: string,
+  label: string,
+  entries: ReadonlyArray<RetiredEntry>,
+): number {
   const { change, echo, verbose, warn } = ctx.services.logger;
-  if (!existsSync(configFile)) return 0;
+  if (!existsSync(file)) return 0;
 
-  const doc = parseDocument(readFileSync(configFile, "utf8"));
+  const doc = parseDocument(readFileSync(file, "utf8"));
   const parseError = doc.errors[0];
   if (parseError !== undefined) {
-    warn(`omp config.yml unreadable, retired keys not pruned: ${parseError.message}`);
+    warn(`omp ${label} unreadable, retired keys not pruned: ${parseError.message}`);
     return 0;
   }
   const contents = doc.contents;
   if (!isMap(contents)) return 0;
 
   const pruned: Array<string> = [];
-  for (const [path, value] of OMP_RETIRED_VALUES) {
-    const matches = (node: unknown): boolean => isScalar(node) && node.value === value;
+  for (const [path, matches] of entries) {
     if (deletePath(contents, path.split("."), matches)) pruned.push(path);
   }
-  for (const path of OMP_RETIRED_KEYS) {
-    if (deletePath(contents, path.split("."), () => true)) pruned.push(path);
-  }
 
   if (pruned.length === 0) {
-    verbose("omp config.yml carries no retired keys");
+    verbose(`omp ${label} carries no retired keys`);
     return 0;
   }
   if (ctx.dryRun) {
-    echo(`[dry-run] prune ${configFile}: ${pruned.join(", ")}`);
+    echo(`[dry-run] prune ${file}: ${pruned.join(", ")}`);
     return pruned.length;
   }
-  writeFileSync(configFile, String(doc));
-  change(`omp config.yml pruned ${pruned.length} retired key(s): ${pruned.join(", ")}`);
+  writeFileSync(file, String(doc));
+  change(`omp ${label} pruned ${pruned.length} retired key(s): ${pruned.join(", ")}`);
   return pruned.length;
 }
+
+/** Prunes retired kit-owned keys from a deployed omp config.yml. */
+export function syncOmpRemovals(ctx: Ctx, configFile: string): number {
+  return pruneRetired(ctx, configFile, "config.yml", [
+    ...OMP_RETIRED_VALUES.map(([path, value]): RetiredEntry => [
+      path,
+      (node) => isScalar(node) && node.value === value,
+    ]),
+    ...OMP_RETIRED_KEYS.map((path): RetiredEntry => [path, () => true]),
+  ]);
+}
+
+/** Prunes retired kit-owned blocks from a deployed omp models.yml. */
+export function syncOmpModelRemovals(ctx: Ctx, modelsFile: string): number {
+  return pruneRetired(
+    ctx,
+    modelsFile,
+    "models.yml",
+    OMP_RETIRED_MODEL_BLOCKS.map(([path, block]): RetiredEntry => [
+      path,
+      (node) => isMap(node) && isDeepStrictEqual(node.toJSON(), block),
+    ]),
+  );
+}

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

@@ -21,7 +21,7 @@ import { mergeOmpConfig, mergeOmpModels } from "./ompYaml";
 import { ensureDirectory, syncMergedYaml, syncWholeFile } from "./ompFileDeploy";
 import { syncMarketplace } from "./ompMarketplace";
 import { syncPlugins } from "./ompPlugins";
-import { syncOmpRemovals } from "./ompRemovals";
+import { syncOmpModelRemovals, syncOmpRemovals } from "./ompRemovals";
 
 export interface OmpState {
   readonly pluginsInstalled: number;
@@ -56,6 +56,7 @@ export async function ompSync(ctx: Ctx): Promise<OmpState> {
   // mergeOmpConfig is additive, so the prune must run on the merged result.
   syncOmpRemovals(ctx, p(agentDir, "config.yml"));
   syncMergedYaml(ctx, "SoT/.omp/models.yml", p(agentDir, "models.yml"), mergeOmpModels);
+  syncOmpModelRemovals(ctx, p(agentDir, "models.yml"));
 
   const intercomRootSetting = process.env["PI_CODING_AGENT_DIR"];
   const intercomRoot =

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.20.0"
+export const GENERATED_PACKAGE_VERSION = "0.20.1"
 
 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": "statusLine:\n  compactThinkingLevel: false\n\ndefaultThinkingLevel: high\n\ncycleOrder:\n  - smol\n  - default\n  - slow\n  - fable\n  - astra\n\ntier:\n  openai: none\n  anthropic: none\n\nadvisor:\n  enabled: true\n  syncBacklog: \"1\"\n\ngithub:\n  enabled: true\n\nfind:\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: max\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-6-luna:medium\n  advisor: anthropic/claude-opus-5-5:medium\n  designer: anthropic/claude-opus-5-5:high\n  plan: anthropic/claude-opus-5-5:xhigh\n  commit: openai-codex/gpt-6-luna:medium\n  task: openai-codex/gpt-6-sol:high\n  vision: anthropic/claude-opus-5-5:medium\n  tiny: openai-codex/gpt-6-luna:low\n  default: anthropic/claude-opus-5-5:high\n  slow: anthropic/claude-opus-5-5:xhigh\n  fable: anthropic/claude-fable-5-1:medium\n  switch_fable: anthropic/claude-fable-5-1:medium\n  astra: openai-codex/gpt-6-astra:xhigh\n  web: web/firecrawl\n\nmodelTags:\n  fable:\n    name: Fable 5.1\n  switch_fable:\n    name: Fable switch default\n    hidden: true\n  astra:\n    name: GPT-6 Astra\n\ndisplay:\n  showTokenUsage: true\n\nproviders:\n  anthropic:\n    serverSideFallback: false\n  fetch: auto\n  webSearchTimeoutSeconds: 30\n\nretry:\n  usageAwareFallback: true\n  fallbackChains:\n    default:\n      - openai-codex/gpt-6-sol:high\n    advisor: []\n    task:\n      - anthropic/claude-opus-5-5:high\n    vision:\n      - openai-codex/gpt-6-sol:medium\n    smol:\n      - anthropic/claude-opus-5-5:low\n    tiny:\n      - anthropic/claude-opus-5-5:low\n    commit:\n      - anthropic/claude-opus-5-5:medium\n    switch_fable: []\n    fable:\n      - openai-codex/gpt-6-astra:xhigh\n    astra:\n      - anthropic/claude-fable-5-1:medium\n    web:\n      - web/exa\n      - web/perplexity\n      - openai-codex/gpt-6-luna\n      - web/parallel\n      - web/zai\n      - web/tinyfish\n      - web/jina\n      - web/kagi\n      - web/tavily\n      - web/brave\n      - web/kimi\n      - web/synthetic\n      - web/ollama\n      - web/searxng\n      - web/startpage\n      - web/duckduckgo\n      - web/ecosia\n      - web/google\n      - web/mojeek\n      - web/public\n\nincludeWorkspaceTree: false\n\nbranchSummary:\n  enabled: true\n\ncommands:\n  enableOpencodeProject: false\n  enableOpencodeUser: false\n\nskills:\n  enableClaudeUser: false\n  enableCodexUser: false\n  enableAgentsUser: true\n\nsteeringMode: all\n\ndev:\n  autoqa: false\n  autoqaConsent: denied\n\ncompaction:\n  thresholdTokens: -1\n  idleEnabled: true\n  handoffSaveToDisk: true\n\ndoubleEscapeAction: tree\ntextVerbosity: low\n\nfeatures:\n  unexpectedStopDetection: smart\n\ncodexResets:\n  autoRedeem: \"no\"\n\nstartup:\n  quiet: true\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  # Temporary metadata for an id the shared models.dev catalog still publishes\n  # as an empty stub. Remove this block once that catalog row carries the real\n  # context window, output cap, ladder, and prices. `defaultLevel` is the kit's\n  # choice for a bare selector, not the Claude API default, which is `medium`.\n  anthropic:\n    modelOverrides:\n      claude-opus-5-5:\n        name: Claude Opus 5.5\n        reasoning: true\n        input:\n          - text\n          - image\n        contextWindow: 1000000\n        maxTokens: 128000\n        cost:\n          input: 4\n          output: 20\n          cacheRead: 0.2\n          cacheWrite: 5\n        thinking:\n          mode: effort\n          efforts:\n            - low\n            - medium\n            - high\n            - xhigh\n            - max\n          defaultLevel: high\n  openai-codex:\n    modelOverrides:\n      gpt-6-astra:\n        thinking:\n          mode: effort\n          efforts:\n            - low\n            - medium\n            - high\n            - xhigh\n            - max\n          defaultLevel: xhigh\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            - medium\n            - high\n            - xhigh\n            - max\n          defaultLevel: xhigh\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 = "f57eb42f09dac1f0336ff710bf9e6f3cf3ac68d8f72c9ff5212348ab943d1931"
+export const GENERATED_PAYLOAD_HASH = "e2be3fa8d70047257cc542bd25040bbb1d5fe167d1ab4486f7c947c2955b0c5b"

package/package.json

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