catherd-cli 1.1.1 → 1.2.0

package/src/domain/sources.ts

@@ -0,0 +1,144 @@
+import { z } from "zod";
+import { DIMS, type Family, FamilyFactsSchema, ScoreSchema } from "./catalog.ts";
+
+/** Spec 1.2 §3.1: the sources `catherd catalog sync` reads, one cache file each in `<data>/sources/`. */
+export const SOURCE_IDS = [
+  "models-dev",
+  "openrouter-models",
+  "openrouter-endpoints",
+  "litellm",
+  "arena",
+  "vectara",
+  "epoch",
+  "artificial-analysis",
+] as const;
+export type SourceId = (typeof SOURCE_IDS)[number];
+
+/** `catalog/sources.json`: each source with its license and attribution line, the id aliases, default efforts. */
+export const SourcesFileSchema = z.looseObject({
+  schema: z.literal(1),
+  version: z.string(),
+  sources: z.array(
+    z.object({
+      id: z.enum(SOURCE_IDS),
+      name: z.string(),
+      url: z.url(),
+      license: z.string(),
+      attribution: z.string(),
+      keyed: z.boolean(),
+    }),
+  ),
+  /** a source's irregular model id → the catalog's id (spec 1.2 §3.4) */
+  aliases: z.record(z.string(), z.string()),
+  /** family id → the effort a source that names none means; a family not listed means `high` */
+  defaultEffort: z.record(z.string(), z.string()),
+});
+export type SourcesFile = z.infer<typeof SourcesFileSchema>;
+
+/** Effort words as catherd writes them, weakest first; a source's spelling (`xHigh`, `MAX`) is folded onto these. */
+export const EFFORT_ORDER = ["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"] as const;
+
+/** `s` as a catherd effort word (`xHigh` → `xhigh`), or null when it is not one. */
+export function effortWord(s: string): string | null {
+  const w = s.trim().toLowerCase();
+  return (EFFORT_ORDER as readonly string[]).includes(w) ? w : null;
+}
+
+/**
+ * Spec 1.2 §3.4: a source's model id in catherd's form: without a `vendor/` prefix, lower case, and each run
+ * of dots and blanks as one `-` (`openai/gpt-5.6-sol` and `GPT 5.6 Sol` → `gpt-5-6-sol`).
+ */
+export function normalizeId(id: string): string {
+  return id
+    .slice(id.lastIndexOf("/") + 1)
+    .trim()
+    .toLowerCase()
+    .replace(/[\s.]+/g, "-")
+    .replace(/-+/g, "-");
+}
+
+/** A parser's `rung`: `<source's model id>#<effort>`, or the bare id when the source names no effort. */
+export function splitSourceRung(rung: string): { id: string; effort: string | null } {
+  const hash = rung.lastIndexOf("#");
+  return hash < 0 ? { id: rung, effort: null } : { id: rung.slice(0, hash), effort: rung.slice(hash + 1) };
+}
+
+export interface IdMapper {
+  /** the id pairs are keyed by: normalized, then through the alias table */
+  key(id: string): string;
+  /** the catalog family a source id names, directly, by a backend's own id or through an alias; never guessed */
+  family(id: string): Family | null;
+}
+
+/** Spec 1.2 §3.4: matches a source's ids to the catalog's families. */
+export function idMapper(families: Family[], aliases: Record<string, string>): IdMapper {
+  const alias = new Map(Object.entries(aliases).map(([from, to]) => [normalizeId(from), normalizeId(to)]));
+  const byKey = new Map<string, Family>();
+  for (const f of families) {
+    for (const on of Object.values(f.on)) if (on) byKey.set(normalizeId(on.id), f);
+    byKey.set(normalizeId(f.id), f);
+  }
+  const key = (id: string) => {
+    const n = normalizeId(id);
+    return alias.get(n) ?? n;
+  };
+  return { key, family: (id) => byKey.get(key(id)) ?? null };
+}
+
+/** Spec 1.2 §3.4: the effort a source that names none means for `family`. */
+export const defaultEffortOf = (sources: SourcesFile, family: Family): string =>
+  sources.defaultEffort[family.id] ?? "high";
+
+const order = (e: string) => (EFFORT_ORDER as readonly string[]).indexOf(e);
+
+/** Every effort the family offers on any backend, weakest first (spec 1.2 §4.3 `adjacent`). */
+export function familyEfforts(f: Family): string[] {
+  const all = new Set<string>();
+  for (const on of Object.values(f.on)) for (const e of on?.efforts ?? []) all.add(e);
+  return [...all].filter((e) => order(e) >= 0).sort((a, b) => order(a) - order(b));
+}
+
+/** Spec 1.2 §4.2: one source's fit onto a dimension's anchor, used or not, and why not. */
+export const FitRowSchema = z.object({
+  dim: z.enum(DIMS),
+  source: z.string(),
+  field: z.string(),
+  n: z.number().int(),
+  a: z.number().nullable(),
+  b: z.number().nullable(),
+  r2: z.number().nullable(),
+  used: z.boolean(),
+  why: z.string().optional(),
+});
+export type FitRow = z.infer<typeof FitRowSchema>;
+
+/**
+ * `<data>/sources/derived.json`: what a sync made of the cached answers. `scores` are the synced values the
+ * catalog layers over the shipped ones (`measured`, `calibrated`, `adjacent`), `facts` each family's facts,
+ * `unmatched` each source's ids no family matched (never guessed), `warnings` the cross-checks that failed.
+ */
+export const DerivedSchema = z.looseObject({
+  schema: z.literal(1),
+  builtAt: z.iso.datetime(),
+  scores: z.array(ScoreSchema),
+  facts: z.record(z.string(), FamilyFactsSchema),
+  fits: z.array(FitRowSchema),
+  unmatched: z.record(z.string(), z.array(z.string())),
+  warnings: z.array(z.string()),
+  /** canonical rung → the Artificial Analysis stand-in features (spec 1.2 §6.3); a file before plan 14 has none */
+  features: z.record(z.string(), z.record(z.string(), z.number())).default({}),
+});
+export type Derived = z.infer<typeof DerivedSchema>;
+
+/** The effort of `have` nearest `target` (the weaker one on a tie); null when `have` holds no effort word. */
+export function nearestEffort(target: string, have: string[]): string | null {
+  const t = order(target);
+  let best: string | null = null;
+  for (const e of have) {
+    const i = order(e);
+    if (i < 0 || t < 0) continue;
+    const b = best === null ? Number.POSITIVE_INFINITY : Math.abs(order(best) - t);
+    if (Math.abs(i - t) < b || (Math.abs(i - t) === b && i < order(best as string))) best = e;
+  }
+  return best;
+}

package/src/entry/catalog-command.ts

@@ -9,8 +9,67 @@ import {
   refreshDiscovery,
   saveTreatLike,
 } from "../services/catalog-service.ts";
+import { readDerived } from "../infra/sources/cache.ts";
+import { type SyncReport, syncSources } from "../services/source-sync.ts";
+import { clearTreatLike, type LeftOnStandIn, resetTreatLikes, suggestFor } from "../services/treat-likes.ts";
 import { exitCodeOf, JSON_ARG, mark, printError } from "./cli-kit.ts";
 
+/**
+ * Spec 1.2 §9: a sync, one line per source (fetched, fresh, skipped, or failed with the answer it kept),
+ * then the rungs newly scored, the user's stand-ins no longer needed and the cross-check warnings.
+ */
+export function syncLines(r: SyncReport, plain = false): string[] {
+  if (r.busy) return ["- sources: another sync is running; its results apply when it ends"];
+  const out: string[] = [];
+  for (const s of r.sources) {
+    if (s.state === "fetched") out.push(`${mark("ok", plain)} ${s.source}: fetched`);
+    else if (s.state === "fresh") out.push(`- ${s.source}: fresh (fetched ${s.fetchedAt})`);
+    else if (s.state === "skipped") out.push(`- ${s.source}: ${s.detail}`);
+    else
+      out.push(
+        `${mark("warn", plain)} ${s.source}: ${s.error}; ${s.fetchedAt ? `keeps the answer fetched ${s.fetchedAt}` : "no earlier answer"}`,
+      );
+  }
+  if (r.newlyScored.length) out.push(`newly scored: ${r.newlyScored.join(", ")}`);
+  for (const n of r.noLongerNeeded)
+    out.push(`stand-in no longer needed: ${n.rung} has values of its own for what ${n.like} lent it`);
+  for (const w of r.warnings) out.push(`${mark("warn", plain)} ${w}`);
+  return out;
+}
+
+const sync = defineCommand({
+  meta: {
+    name: "sync",
+    description:
+      "Fetch the public model facts and scores now (each source at most every 12 hours unless --force) and show what changed",
+  },
+  args: {
+    force: { type: "boolean", description: "fetch every source, however fresh" },
+    unmatched: {
+      type: "boolean",
+      description: "also list each source's ids that match no model in the catalog",
+    },
+    ...JSON_ARG,
+  },
+  async run({ args }) {
+    try {
+      const r = await syncSources({ force: args.force === true });
+      if (args.json) console.log(JSON.stringify(r, null, 2));
+      else for (const l of syncLines(r)) console.log(l);
+      if (args.unmatched && !args.json) {
+        const unmatched = readDerived()?.unmatched ?? {};
+        if (Object.keys(unmatched).length === 0) console.log("unmatched: none");
+        for (const [source, ids] of Object.entries(unmatched))
+          console.log(`unmatched in ${source}: ${ids.join(", ")}`);
+      }
+      const got = r.sources.some((s) => s.state === "fetched" || s.state === "fresh");
+      process.exitCode = r.failed.length && !got ? 1 : 0;
+    } catch (e) {
+      fail(e);
+    }
+  },
+});
+
 /** One backend's refresh: its model count, else why it listed none, then its fix on a line of its own. */
 export function formatRefreshed(r: Refreshed, plain = false): string {
   if (!r.error) return `${mark("ok", plain)} ${r.backend}: ${r.models} models`;
@@ -20,10 +79,32 @@ export function formatRefreshed(r: Refreshed, plain = false): string {
   ].join("\n");
 }
 
+/**
+ * One model: its rungs scored and roles, then (spec 1.2 §4.1, §5.3, §8) its price and speed facts, and each
+ * rung's values with their confidence and source, and the runs catherd has made on it.
+ */
 export function formatModel(m: CatalogModel): string {
   const scored = m.rungs.filter((r) => r.enabled).length;
   const listed = m.listed === false ? "  not offered by this account" : "";
-  return `${m.backend}:${m.model}  ${scored}/${m.rungs.length} rungs scored  roles ${m.roles.join(",") || "none"}${listed}`;
+  const lines = [
+    `${m.backend}:${m.model}  ${scored}/${m.rungs.length} rungs scored  roles ${m.roles.join(",") || "none"}${listed}`,
+  ];
+  const facts = [
+    ...(m.price ? [`$${m.price.input}/$${m.price.output} per M tokens in/out`] : []),
+    ...Object.entries(m.speed).map(([k, v]) => `${k} ${Number(v.toPrecision(4))}`),
+  ];
+  if (facts.length) lines.push(`  ${facts.join(" · ")}`);
+  for (const r of m.rungs) {
+    // spec 1.2 §5.3: each value with its confidence and source, as `route` reports it; a guess names its rung
+    const values = Object.entries(r.scores).map(
+      ([dim, v]) =>
+        `${dim} ${Number(v.value.toPrecision(4))} (${v.from ? `inferred from ${v.from}` : v.confidence}, ${v.source})`,
+    );
+    if (values.length === 0 && !r.evidence) continue;
+    lines.push(`  #${r.rung.slice(r.rung.lastIndexOf("#") + 1)}  ${values.join(" · ") || "unscored"}`);
+    if (r.evidence) lines.push(`    runs: ${r.evidence}`);
+  }
+  return lines.join("\n");
 }
 
 /** The repository the command runs in, for per-repository listings; none outside one (global). */
@@ -79,28 +160,102 @@ const list = defineCommand({
   },
 });
 
+/** Spec 1.2 §6.4: the profile rungs a removal leaves on an inferred stand-in or unscored, one line each. */
+export function leftLines(left: LeftOnStandIn[], plain = false): string[] {
+  return left.map(
+    (l) =>
+      `${mark("warn", plain)} ${l.profile}: ${l.rung} is left ${l.unscored ? "unscored: routing skips it" : `on an inferred stand-in for ${l.dims.join(", ")}`}`,
+  );
+}
+
+/** Spec 1.2 §6.4 `--suggest`: the three nearest stand-ins, each with its distance and the features it rests on. */
+export function suggestLines(r: ReturnType<typeof suggestFor>, rung: string): string[] {
+  const head = r.lacking.length
+    ? `${r.canonical} has no ${r.lacking.join(", ")} value of its own; the nearest stand-ins:`
+    : `${r.canonical} has every value the bars use; the nearest scored rungs:`;
+  if (r.suggestions.length === 0)
+    return [
+      `${r.canonical}: no scored rung shares 3 features with it; map it by hand: catherd catalog treat-like ${rung} <rung>`,
+    ];
+  return [
+    head,
+    ...r.suggestions.map(
+      (s, i) =>
+        `  ${i + 1}. ${s.like}  distance ${s.distance.toFixed(2)}  lends ${s.lends.join(", ")}  on ${s.features.join(", ")}`,
+    ),
+    `map one: catherd catalog treat-like ${rung} <rung>`,
+  ];
+}
+
 const treatLike = defineCommand({
-  meta: { name: "treat-like", description: "Score an unscored rung as a scored one" },
+  meta: {
+    name: "treat-like",
+    description:
+      "Score an unscored rung as a scored one; --suggest ranks stand-ins, --clear and --reset remove your mappings",
+  },
   args: {
     rung: {
       type: "positional",
-      required: true,
+      required: false,
       description: "the unscored rung, backend:model#effort or model#effort",
     },
-    like: { type: "positional", required: true, description: "the scored rung whose scores it borrows" },
+    like: { type: "positional", required: false, description: "the scored rung whose scores it borrows" },
+    suggest: { type: "string", description: "list the 3 nearest stand-ins for this rung" },
+    clear: { type: "string", description: "remove your treat-like for this rung" },
+    reset: { type: "boolean", description: "remove every treat-like of yours" },
+    ...JSON_ARG,
   },
   async run({ args }) {
     try {
-      const r = await saveTreatLike(args.rung, args.like);
-      console.log(`✓ ${r.rung} is treated like ${r.like}`);
+      const modes = [
+        args.suggest !== undefined,
+        args.clear !== undefined,
+        args.reset === true,
+        args.rung !== undefined,
+      ];
+      if (modes.filter(Boolean).length !== 1 || (args.rung !== undefined && args.like === undefined))
+        throw new CatherdError(
+          "E_INPUT_INVALID",
+          "treat-like takes <rung> <like>, or one of --suggest, --clear, --reset",
+          {
+            fix: "catherd catalog treat-like <rung> <like> | --suggest <rung> | --clear <rung> | --reset",
+          },
+        );
+      if (args.suggest !== undefined) {
+        const r = suggestFor(args.suggest);
+        if (args.json) console.log(JSON.stringify(r, null, 2));
+        else for (const l of suggestLines(r, args.suggest)) console.log(l);
+        return;
+      }
+      if (args.clear !== undefined) {
+        const r = await clearTreatLike(args.clear);
+        if (args.json) return console.log(JSON.stringify(r, null, 2));
+        for (const l of leftLines(r.left)) console.log(l);
+        console.log(`${mark("ok")} ${r.rung} is no longer treated like ${r.like}`);
+        return;
+      }
+      if (args.reset) {
+        const r = await resetTreatLikes();
+        if (args.json) return console.log(JSON.stringify(r, null, 2));
+        for (const l of leftLines(r.left)) console.log(l);
+        console.log(
+          r.removed.length
+            ? `${mark("ok")} removed ${r.removed.length} treat-like${r.removed.length === 1 ? "" : "s"}: ${r.removed.map(([a, b]) => `${a} → ${b}`).join(", ")}`
+            : "no treat-like of yours to remove",
+        );
+        return;
+      }
+      const r = await saveTreatLike(args.rung as string, args.like as string);
+      if (args.json) return console.log(JSON.stringify(r, null, 2));
+      console.log(`${mark("ok")} ${r.rung} is treated like ${r.like}`);
     } catch (e) {
       fail(e);
     }
   },
 });
 
-/** Spec §8: `catherd catalog refresh|list|treat-like <rung> <like>`. */
+/** Spec §8 and 1.2 §9: `catherd catalog refresh|list|sync|treat-like <rung> <like> | --suggest|--clear|--reset`. */
 export const catalogCommand = defineCommand({
   meta: { name: "catalog", description: "The model catalog" },
-  subCommands: { refresh, list, "treat-like": treatLike },
+  subCommands: { refresh, list, sync, "treat-like": treatLike },
 });

package/src/entry/init-command.ts

@@ -4,11 +4,14 @@ import { errorMessage, isCatherdError } from "../domain/errors.ts";
 import { configDir } from "../infra/paths.ts";
 import { VERSION } from "../infra/version.ts";
 import { doctor } from "../services/doctor.ts";
+import { testAaKey } from "../infra/sources/artificial-analysis.ts";
+import { aaKey, saveAaKey } from "../services/credentials.ts";
 import { jevKey, saveJevKey, testJevKey } from "../services/jev-service.ts";
+import { type SyncReport, syncSources } from "../services/source-sync.ts";
 import { reinstallCommand } from "../services/doctor-checks.ts";
 import { ensureGlobal, type GlobalInstallDeps, realGlobalInstall } from "../services/global-install.ts";
 import { hasProfileFile, type InitResult, initSetup, moveLegacy } from "../services/setup.ts";
-import { formatRefreshed } from "./catalog-command.ts";
+import { formatRefreshed, syncLines } from "./catalog-command.ts";
 import { mark as markOf } from "./cli-kit.ts";
 import { formatReport } from "./doctor-command.ts";
 import { mcpHandshake } from "./mcp/handshake.ts";
@@ -65,6 +68,71 @@ export async function jevStep(
   }
 }
 
+/**
+ * Spec 1.2 §9: the Artificial Analysis key step, after Jev's. ARTIFICIAL_ANALYSIS_API_KEY wins, else the saved
+ * key, else a prompt (Enter skips). A typed key is tested with one request: a 200 saves it, a 401 does not,
+ * and a key that cannot be checked (no network) is not saved either. It never stops `init`.
+ */
+export async function aaStep(
+  ask: Prompter | null,
+  d: {
+    testAaKey?: (key: string) => Promise<{ result: "ok" | "refused" | "unchecked"; error?: string }>;
+    saveAaKey?: (key: string) => void;
+  } = {},
+  plain = false,
+): Promise<void> {
+  const mark = (state: State) => markOf(state, plain);
+  if (process.env.ARTIFICIAL_ANALYSIS_API_KEY?.trim()) {
+    ask?.skip?.();
+    return console.log(`${mark("ok")} Artificial Analysis: using ARTIFICIAL_ANALYSIS_API_KEY`);
+  }
+  if (aaKey()) {
+    ask?.skip?.();
+    return console.log(`${mark("ok")} Artificial Analysis: using the saved key`);
+  }
+  const key = ask ? await ask.secret("Artificial Analysis API key (optional; Enter skips): ") : "";
+  if (!key)
+    return console.log(
+      "- Artificial Analysis: no key; scores come from the keyless sources (add one later with catherd init)",
+    );
+  const t = await (d.testAaKey ?? testAaKey)(key).catch((e: unknown) => ({
+    result: "unchecked" as const,
+    error: errorMessage(e),
+  }));
+  if (t.result === "refused")
+    return console.log(`${mark("warn")} Artificial Analysis: the key was refused (401), so it was not saved`);
+  if (t.result === "unchecked")
+    return console.log(
+      `${mark("warn")} Artificial Analysis: the key could not be checked (${t.error ?? "no answer"}), so it was not saved; run catherd init again to retry`,
+    );
+  try {
+    (d.saveAaKey ?? saveAaKey)(key);
+    console.log(`${mark("ok")} Artificial Analysis: the key answers; saved with mode 600`);
+  } catch (e) {
+    console.log(
+      `${mark("warn")} Artificial Analysis: could not save the key: ${errorMessage(e).split("\n").join(" ")}`,
+    );
+    if (isCatherdError(e) && e.fix) console.log(`    fix: ${e.fix}`);
+  }
+}
+
+/**
+ * Spec 1.2 §9: `init` syncs the public sources in the foreground, after the keys. It never stops `init`;
+ * CATHERD_NO_SYNC=1 skips it.
+ */
+export async function syncStep(o: { plain?: boolean; sync?: () => Promise<SyncReport> } = {}): Promise<void> {
+  const plain = o.plain === true;
+  if (process.env.CATHERD_NO_SYNC === "1")
+    return console.log("- sources: not synced (CATHERD_NO_SYNC=1); catherd catalog sync fetches them");
+  console.log("syncing the public model sources…");
+  try {
+    for (const l of syncLines(await (o.sync ?? (() => syncSources()))(), plain)) console.log(l);
+  } catch (e) {
+    console.log(`${markOf("warn", plain)} sources: ${errorMessage(e).split("\n").join(" ")}`);
+    console.log("    fix: catherd catalog sync");
+  }
+}
+
 /**
  * Spec 1.1 §12: installs the global CLI at this version (the plugin's launcher then needs no bunx), and
  * says "installing catherd…" before the resolve. It never stops `init`: a failure is a `!` line and its fix.
@@ -124,7 +192,7 @@ export const initCommand = defineCommand({
   meta: {
     name: "init",
     description:
-      "First run: the global catherd command, the Jev key, the default profile, its agents, and a readiness report. Piped, it reads the answers from stdin one per line, a line per question even when this machine skips it (the Jev key, the profile, whether to replace it), and waits for stdin to close; --no-input asks nothing",
+      "First run: the global catherd command, the Jev key, the Artificial Analysis key, a sync of the public model sources, the default profile, its agents, and a readiness report. Piped, it reads the answers from stdin one per line, a line per question even when this machine skips it (the Jev key, the Artificial Analysis key, the profile, whether to replace it), and waits for stdin to close; --no-input asks nothing",
   },
   args: {
     // citty reads --no-input as input: false, whatever the flag is named; naming it no-input shows it as is
@@ -148,6 +216,8 @@ export const initCommand = defineCommand({
       console.log(`catherd ${VERSION}: setting up in ${configDir()}`);
       await globalStep(VERSION, { skip: (args as { global?: boolean }).global === false, plain });
       await jevStep(ask, {}, plain);
+      await aaStep(ask, {}, plain);
+      await syncStep({ plain });
       if (args.profile !== undefined) ask?.skip?.();
       const name = assertProfileName(
         args.profile ?? (ask ? (await ask.ask("Profile to set up [default]: ")) || "default" : "default"),

package/src/entry/mcp/lane-tools.ts

@@ -13,7 +13,7 @@ export function registerLaneTools(server: McpServer, deps: Deps): void {
     "route",
     {
       description:
-        "The rung for a lane (from Jev, else the lane file's Kind/Difficulty lines, else the profile default) or, without a lane file, a role's default rung, with the ladder above it. Rungs are backend:model#effort; a claude: rung comes with the agent to run it as. A lane whose Kind: or Difficulty: the catalog does not know is refused with E_LANE_INVALID.",
+        "The rung for a lane (from Jev, else the lane file's Kind/Difficulty lines, else the profile default) or, without a lane file, a role's default rung, with the ladder above it. Rungs are backend:model#effort; a claude: rung comes with the agent to run it as. `provenance` says why: each threshold of the lane's bar with the value used against it, that value's confidence, source and date (`inferred: true` when a treat-like or a stand-in lent it), the rung's speed and cost facts, and catherd's own run evidence for it (shown, never used to route). A lane whose Kind: or Difficulty: the catalog does not know is refused with E_LANE_INVALID.",
       inputSchema: {
         run: z.string(),
         lane_file: z.string().optional(),

package/src/entry/mcp/server.ts

@@ -1,11 +1,13 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { errorMessage } from "../../domain/errors.ts";
 import { log } from "../../infra/log.ts";
 import { startNotifier } from "../../services/notifier.ts";
 import type { Deps } from "../../services/ports.ts";
 import { reconcileAll } from "../../services/reconcile.ts";
+import { backgroundSync } from "../../services/source-sync.ts";
 import { defaultDeps } from "../deps.ts";
 import { registerDispatchTools } from "./dispatch-tools.ts";
 import { registerLaneTools } from "./lane-tools.ts";
@@ -60,9 +62,13 @@ export function buildServer(deps: Deps = defaultDeps()): McpServer {
 
 /**
  * Spec §4.7: connect first, so the client never waits on a scan; then reconcile every run. Spec §3.4: the notifier
- * starts before reconcile, so what reconcile settles is announced, and scans for the rest once it is done.
+ * starts before reconcile, so what reconcile settles is announced, and scans for the rest once it is done. Spec
+ * 1.2 §3.2: the source sync starts once connected and is never awaited, so neither the handshake nor a tool call
+ * waits on the network. Tests pass their own transport and sync.
  */
-export async function startMcpServer(): Promise<void> {
+export async function startMcpServer(
+  o: { transport?: Transport; sync?: () => Promise<unknown> } = {},
+): Promise<void> {
   const deps = defaultDeps();
   // which of the session's variables this server got (never their values): the live check of spec §3.9
   log("info", "session", {
@@ -72,7 +78,11 @@ export async function startMcpServer(): Promise<void> {
     token: Boolean(deps.session?.token),
   });
   const notifier = startNotifier(deps);
-  await buildServer(deps).connect(new StdioServerTransport());
+  await buildServer(deps).connect(o.transport ?? new StdioServerTransport());
+  const sync = o.sync ?? (() => backgroundSync());
+  void Promise.resolve()
+    .then(sync)
+    .catch((e: unknown) => log("debug", "sources", { error: errorMessage(e) }));
   try {
     const r = await reconcileAll(deps);
     const shown = r.warnings.length;

package/src/entry/mcp/setup-tools.ts

@@ -5,6 +5,7 @@ import { PROFILE_NAME, ProfilePatchSchema } from "../../domain/profile.ts";
 import { ROLES } from "../../domain/roles.ts";
 import { gitToplevel } from "../../infra/git.ts";
 import type { Deps } from "../../services/ports.ts";
+import { syncSources } from "../../services/source-sync.ts";
 import { handle } from "./result.ts";
 
 const PROFILE = z.string().regex(PROFILE_NAME).optional();
@@ -28,7 +29,7 @@ export function registerSetupTools(server: McpServer, deps: Deps): void {
     "catalog_query",
     {
       description:
-        "Models catherd can place, with capabilities, the roles they can fill, their scored rungs (backend:model#effort), any 'treat like', their cost under the billing of `repo`'s profile, and whether this account's last listing offers them (`listed: false`: it does not); `enabled: false` rungs are unscored. Scored models first. opencode's models are as listed in `repo` (default: this server's directory), as route sees them there.",
+        "Models catherd can place, with capabilities, the roles they can fill, their scored rungs (backend:model#effort), any 'treat like', their cost under the billing of `repo`'s profile, and whether this account's last listing offers them (`listed: false`: it does not); `enabled: false` rungs are unscored. Each score has its confidence, source and date (`from` names the rung a lent value belongs to); each model its price and speed facts, each rung catherd's own run evidence. Scored models first. opencode's models are as listed in `repo` (default: this server's directory), as route sees them there.",
       inputSchema: {
         repo: z.string().min(1).optional(),
         role: z.enum(ROLES).optional(),
@@ -49,6 +50,27 @@ export function registerSetupTools(server: McpServer, deps: Deps): void {
       }),
   );
 
+  server.registerTool(
+    "catalog_sync",
+    {
+      description:
+        "Fetch the public model facts and scores now (models.dev, OpenRouter, LiteLLM, Arena, Vectara, Epoch AI, and Artificial Analysis with the user's key): each source at most every 12 hours unless `force`. Returns the rungs newly scored, the user's treat-likes no longer needed (their rung now has values of its own), the sources that failed (each keeps its last good answer) and each source's state. route and catalog_query read the result at once.",
+      inputSchema: { force: z.boolean().default(false) },
+    },
+    (a) =>
+      handle(async () => {
+        const r = await (deps.sync ?? ((o) => syncSources(o)))({ force: a.force });
+        return {
+          newlyScored: r.newlyScored,
+          standInsNoLongerNeeded: r.noLongerNeeded,
+          failed: r.failed,
+          sources: r.sources,
+          warnings: r.warnings,
+          ...(r.busy ? { busy: "another sync was running; call catalog_sync again" } : {}),
+        };
+      }),
+  );
+
   server.registerTool(
     "profile_get",
     {
@@ -73,7 +95,7 @@ export function registerSetupTools(server: McpServer, deps: Deps): void {
     "profile_set",
     {
       description:
-        "Apply a patch to a profile (without a name: the profile this repo runs on, as in profile_get; a new name starts from the default profile): objective, jev.use, billing, roles (enabled, access, network, rungs, defaultRung), harness isolation per backend, failover, budget, timeouts, preflight.confirm, lock.heavy and notify. Lists replace, maps merge, and null removes a key. An unknown key is refused. It validates first and writes nothing when invalid; otherwise it saves, rewrites the agent files and relinks them. Returns the errors and warnings, the diff, and newSessionNeededFor: the agents that apply from the next Claude Code session.",
+        "Apply a patch to a profile (without a name: the profile this repo runs on, as in profile_get; a new name starts from the default profile): objective, jev.use, billing, roles (enabled, access, network, rungs, defaultRung), harness isolation per backend, failover, budget, timeouts, preflight.confirm, lock.heavy and notify. Lists replace, maps merge, and null removes a key. An unknown key is refused. It validates first and writes nothing when invalid, unless the patch repairs an invalid profile: it fixes at least one of its errors and adds none, and then it saves with `errors` listing those still open. A save rewrites the agent files and relinks them. Returns saved, the errors and warnings, the diff, and newSessionNeededFor: the agents that apply from the next Claude Code session.",
       inputSchema: { name: PROFILE, repo: REPO, patch: ProfilePatchSchema },
     },
     (a) => handle(async () => deps.profiles.set(a.name, a.patch, await toplevel(a.repo))),

package/src/entry/profile-command.ts

@@ -38,6 +38,8 @@ export interface StandIn {
   to: string;
   inferred: boolean;
   via: string | null;
+  /** what the treat-like lends, as `profile show` says it */
+  note: string | null;
 }
 
 /** Spec §7.2: each stand-in; `via` names the rung whose scores it borrows (spec 1.1 §11). */
@@ -46,7 +48,7 @@ export function standIns(p: Profile, c: Catalog): StandIn[] {
     try {
       return { from, to, ...inferredScores(c, rungInfo(c, to)) };
     } catch {
-      return { from, to, inferred: false, via: null };
+      return { from, to, inferred: false, via: null, note: null };
     }
   });
 }
@@ -93,8 +95,7 @@ export function formatProfile(
   const harness = Object.entries(p.harness).filter(runs);
   lines.push(`harness ${harness.map(([k, h]) => `${k} ${h.isolated ? "isolated" : "native"}`).join(" · ")}`);
   lines.push(o.standIns.length ? "failover" : "failover none");
-  for (const s of o.standIns)
-    lines.push(`  ${s.from} → ${s.to}${s.via ? ` (scores borrowed from ${s.via})` : ""}`);
+  for (const s of o.standIns) lines.push(`  ${s.from} → ${s.to}${s.note ? ` (${s.note})` : ""}`);
   const budget = Object.entries(p.budget).map(([k, v]) => (k === "usd" ? `$${v}` : `${v} ${k}`));
   lines.push(`budget ${budget.join(" · ") || "no cap"}`);
   lines.push(`timeouts idle ${p.timeouts.idleMin} min · wall ${p.timeouts.wallMin} min`);
@@ -265,7 +266,12 @@ const set = defineCommand({
     if (!r.saved) throw refused(r.errors);
     if (r.diff.length === 0) console.log("no change");
     for (const c of r.diff) console.log(`${mark("ok")} ${formatChange(c)}`);
-    printIssues([], r.warnings);
+    // spec 1.2 §6.2: a save that repairs part of an invalid profile goes through; it lists what is still open
+    if (r.errors.length)
+      console.log(
+        `${mark("warn")} saved; ${r.errors.length} ${r.errors.length === 1 ? "error is" : "errors are"} still open:`,
+      );
+    printIssues(r.errors, r.warnings);
     printSynced(r);
   },
 });

package/src/entry/tui/commands.ts

@@ -211,12 +211,12 @@ export const COMMANDS = [
   },
   {
     id: "catalog.refresh",
-    title: "Refresh the model catalog",
+    title: "Sync the public sources and refresh the model catalog",
     group: "Profiles",
     scope: "tab.profiles",
     keys: ["r"],
     palette: true,
-    cli: "catherd catalog refresh",
+    cli: "catherd catalog sync",
   },
   {
     id: "edit.undo",
@@ -305,6 +305,24 @@ export const COMMANDS = [
     short: "change",
   },
   { id: "tree.expand", title: "Expand", group: "Profiles", scope: "row.profiles", keys: ["right", "l"] },
+  {
+    id: "tree.detail",
+    title: "Show the rung's values, sources and runs",
+    group: "Profiles",
+    scope: "row.profiles",
+    keys: ["i"],
+    palette: true,
+    cli: "catherd catalog list --json",
+  },
+  {
+    id: "tree.treatLike",
+    title: "Treat the rung like another…",
+    group: "Profiles",
+    scope: "row.profiles",
+    keys: ["t"],
+    palette: true,
+    cli: "catherd catalog treat-like --suggest <rung>",
+  },
   {
     id: "tree.collapse",
     title: "Collapse, or go to the parent",