mohdel 0.124.0 → 1.0.0

package/src/cli/onboard.js

@@ -1,97 +1,11 @@
-import { intro, outro, select, text, isCancel, cancel, note } from '@clack/prompts'
+import { intro, outro, select, text, isCancel, cancel, note, spinner } from '@clack/prompts'
 import { id, label, meta, ok } from './colors.js'
-import { chmodSync, existsSync } from 'fs'
+import { chmodSync, existsSync, readFileSync } from 'fs'
 import { readFile, writeFile, mkdir } from 'fs/promises'
-import { dirname } from 'path'
-import { loadDefaultEnv, getAPIKey, ENV_PATH } from '../lib/common.js'
+import { dirname, resolve } from 'path'
+import { loadDefaultEnv, getAPIKey, getConfig, saveConfig, getCuratedModels, catalogEntries, ENV_PATH } from '../lib/common.js'
 import providers from '../lib/providers.js'
-
-const PROVIDER_INFO = {
-  gemini: {
-    label: 'Google Gemini',
-    description: 'Gemini 2.5/3 — long context, vision, video. Free tier, no card required.',
-    url: 'https://aistudio.google.com/apikey',
-    hint: 'Create an API key at aistudio.google.com → Get API Key',
-    free: true
-  },
-  groq: {
-    label: 'Groq',
-    description: 'Llama 4 — fastest inference available. Free tier, no card required.',
-    url: 'https://console.groq.com/keys',
-    hint: 'Create an API key at console.groq.com → API Keys',
-    free: true
-  },
-  cerebras: {
-    label: 'Cerebras',
-    description: 'Llama, Qwen — fast inference on custom hardware. Free tier available.',
-    url: 'https://cloud.cerebras.ai/platform',
-    hint: 'Create an API key at cloud.cerebras.ai → Platform → API Keys',
-    free: true
-  },
-  anthropic: {
-    label: 'Anthropic',
-    description: 'Claude Opus, Sonnet, Haiku — reasoning, coding, vision, tool use.',
-    url: 'https://console.anthropic.com/settings/keys',
-    hint: 'Create an API key at console.anthropic.com → Settings → API Keys',
-    free: false
-  },
-  openai: {
-    label: 'OpenAI',
-    description: 'GPT-5, o-series — reasoning, vision, image generation.',
-    url: 'https://platform.openai.com/api-keys',
-    hint: 'Create an API key at platform.openai.com → API Keys',
-    free: false
-  },
-  xai: {
-    label: 'xAI',
-    description: 'Grok — reasoning and tool use.',
-    url: 'https://console.x.ai',
-    hint: 'Create an API key at console.x.ai',
-    free: false
-  },
-  mistral: {
-    label: 'Mistral',
-    description: 'Mistral Large, Codestral, Pixtral — coding, reasoning, vision. Free tier available.',
-    url: 'https://console.mistral.ai/api-keys',
-    hint: 'Create an API key at console.mistral.ai → API Keys',
-    free: true
-  },
-  deepseek: {
-    label: 'DeepSeek',
-    description: 'DeepSeek R1/V3 — reasoning, coding. Low cost.',
-    url: 'https://platform.deepseek.com/api_keys',
-    hint: 'Create an API key at platform.deepseek.com → API Keys',
-    free: false
-  },
-  fireworks: {
-    label: 'Fireworks',
-    description: 'Llama, Qwen, DeepSeek — serverless inference with reasoning.',
-    url: 'https://fireworks.ai/account/api-keys',
-    hint: 'Create an API key at fireworks.ai → Account → API Keys',
-    free: false
-  },
-  openrouter: {
-    label: 'OpenRouter',
-    description: 'Multi-provider router — access 200+ models with one key.',
-    url: 'https://openrouter.ai/settings/keys',
-    hint: 'Create an API key at openrouter.ai → Settings → Keys',
-    free: false
-  },
-  novita: {
-    label: 'Novita',
-    description: 'Image generation — Flux, SDXL.',
-    url: 'https://novita.ai/dashboard/key',
-    hint: 'Create an API key at novita.ai → Dashboard → API Key',
-    free: false
-  },
-  qwen: {
-    label: 'Qwen Cloud',
-    description: 'Qwen 3.7 Max/Plus, 3.6 Flash — reasoning, coding, long context. Free quota for new users.',
-    url: 'https://home.qwencloud.com/api-keys',
-    hint: 'Create an API key at home.qwencloud.com → API Keys',
-    free: false
-  }
-}
+import PROVIDER_INFO from '../lib/provider-info.js'
 
 export { PROVIDER_INFO, appendToEnvFile }
 
@@ -138,26 +52,54 @@ export async function runOnboard () {
   loadDefaultEnv()
   const { configured, unconfigured } = getConfiguredProviders()
 
-  // Has providers configured — show status
+  // Already set up: a status line and the step that follows from it, not a
+  // menu. `mo --help` is the menu.
   if (configured.length > 0) {
-    console.log(label('mohdel') + meta(` — ${configured.length} provider${configured.length > 1 ? 's' : ''} configured\n`))
-    for (const name of configured) {
-      console.log(`  ${ok('●')} ${id(name)}`)
+    const curated = await getCuratedModels()
+    const active = catalogEntries(curated).filter(([, s]) => !s.deprecated)
+    const unpriced = active.filter(([, s]) => s.inputPrice == null).length
+
+    const catalog = active.length === 0
+      ? 'catalog empty'
+      : `${active.length} model${active.length > 1 ? 's' : ''}` +
+        (unpriced ? `, ${unpriced} without prices` : '')
+    const shown = configured.slice(0, 4).map(n => id(n)).join(meta(', '))
+    const more = configured.length > 4 ? meta(` +${configured.length - 4} more`) : ''
+    console.log(`${label('mohdel')} ${meta('—')} ${shown}${more}  ${meta('·')} ${meta(catalog)}\n`)
+
+    const first = configured[0]
+    const next = []
+    let handOver = null
+    if (active.length === 0) {
+      next.push([`mo curate ${first}`, 'add the models this key can reach'])
+      // An interrupted run leaves the brief behind. Telling someone to write
+      // one that is already sitting in front of them is the wrong step.
+      const { BRIEF_FILE, BRIEF_HEADING } = await import('./instructions.js')
+      const briefPath = resolve(process.cwd(), BRIEF_FILE)
+      const briefReady = existsSync(briefPath) &&
+        readFileSync(briefPath, 'utf8').startsWith(BRIEF_HEADING)
+      if (briefReady) {
+        const { detectAssistants, preferredAgent, briefPrompt } = await import('../lib/assistants.js')
+        const agent = preferredAgent((await getConfig()).assistant, detectAssistants())
+        handOver = { file: BRIEF_FILE, line: agent.start(`"${briefPrompt(BRIEF_FILE, first)}"`) }
+      } else {
+        next.push([`mo model instructions ${first}`, 'let your agent fill in the prices'])
+      }
+    } else {
+      if (unpriced) next.push([`mo model instructions ${first}`, 'fill in the missing prices'])
+      next.push(['mo ask <model> "..."', 'one-shot inference'])
+      next.push(['mo ls', 'browse the catalog'])
     }
     if (unconfigured.length) {
-      console.log('')
-      for (const name of unconfigured) {
-        console.log(`  ${meta('○')} ${meta(name)}`)
-      }
+      next.push(['mo providers', `${unconfigured.length} more providers available`])
+    }
+    next.push(['mo --help', 'everything else'])
+
+    const width = Math.max(...next.map(([cmd]) => cmd.length))
+    for (const [cmd, why] of next) console.log(`  ${id(cmd.padEnd(width))}  ${meta(why)}`)
+    if (handOver) {
+      console.log(`\n  ${meta(`${handOver.file} is written — hand it over:`)}\n    ${id(handOver.line)}`)
     }
-    console.log(`\n${meta('Commands:')}
-  mo ask <model> "..."     One-shot inference (pipeable)
-  mo doctor                Check install health
-  mo model list            Browse curated models
-  mo model show <model>    Model details
-  mo default               Set default model
-  mo provider setup <p>    Add another provider
-  mo --help                All commands`)
     return
   }
 
@@ -221,27 +163,150 @@ export async function runOnboard () {
 
   note(`${ok('✓')} Saved ${envVar} to ${meta(ENV_PATH)}`, 'Done')
 
-  // Reload env so the new key is visible, then offer to curate models
+  // Reload env so the new key is visible, then fill the catalog.
   loadDefaultEnv()
-  const { confirm } = await import('@clack/prompts')
-  const shouldCurate = await confirm({
-    message: `Fetch and curate models from ${info.label}?`,
-    initialValue: true
-  })
 
-  if (isCancel(shouldCurate) || !shouldCurate) {
-    outro(`Run ${id('mo model curate ' + selected)} later to browse available models.`)
+  // OpenRouter's model list carries prices, so picking by hand is complete
+  // there and needs no agent at all.
+  const selfPricing = !!providers[selected]?.pricesFromApi
+
+  // Where the prices are published, the models that cost nothing are the whole
+  // offer for someone with no coding agent. The count belongs on the menu: put
+  // it behind a search over hundreds of ids and nobody finds it.
+  let api = null
+  let free = []
+  if (selfPricing) {
+    const { providerApi, freeModels } = await import('../lib/select.js')
+    api = await providerApi(selected)
+    if (api?.listModels) {
+      const s = spinner()
+      s.start(`Reading ${info.label}'s model list...`)
+      try {
+        free = freeModels(await api.listModels())
+        s.stop(`${info.label}: ${free.length} of its models cost nothing`)
+      } catch (e) {
+        s.stop(`Could not read ${info.label}'s model list: ${e.message}`)
+      }
+    }
+  }
+
+  const how = await select({
+    message: 'How do you want to fill your catalog?',
+    initialValue: free.length ? 'free' : selfPricing ? 'hand' : 'agent',
+    options: selfPricing
+      ? [
+          ...(free.length
+            ? [{ value: 'free', label: `Add the free models (${free.length})`, hint: 'nothing to pay, nothing to type' }]
+            : []),
+          { value: 'hand', label: 'Pick models by hand', hint: `${info.label} publishes prices — nothing else needed` },
+          { value: 'agent', label: 'Let my coding agent do it', hint: 'for anything the model list omits' },
+          { value: 'later', label: 'Later' }
+        ]
+      : [
+          { value: 'agent', label: 'Let my coding agent do it', hint: 'fetches the model list and the prices' },
+          { value: 'hand', label: 'Pick models by hand', hint: 'ids only — prices left for later' },
+          { value: 'later', label: 'Later' }
+        ]
+  })
+  if (isCancel(how) || how === 'later') {
+    outro(`Later: ${id('mo model instructions ' + selected)}  ${meta('│')}  ${id('mo curate ' + selected)}`)
     return
   }
 
-  const { initializeAPIs, processModels } = await import('../lib/select.js')
-  const { api } = await initializeAPIs()
+  if (how === 'free') {
+    const { addModels } = await import('../lib/select.js')
+    const s = spinner()
+    s.start(`Adding ${free.length} model${free.length > 1 ? 's' : ''}...`)
+    await addModels(selected, api, free)
+    s.stop(`Added ${free.length} model${free.length > 1 ? 's' : ''}, priced at $0`)
+    outro(`Ready — ${id('mo ls')} lists them, then ${id('mo ask <model> "…"')}. ` +
+      `${id('mo curate ' + selected)} adds the paid ones.`)
+    return
+  }
 
-  if (!api[selected]) {
-    outro(`Could not initialize ${info.label}. Run ${id('mo model curate ' + selected)} to retry.`)
+  if (how === 'hand') {
+    const { providerApi, processModels } = await import('../lib/select.js')
+    api = api || await providerApi(selected)
+    if (!api) {
+      outro(`Could not reach ${info.label}. Run ${id('mo curate ' + selected)} to retry.`)
+      return
+    }
+    if (!await processModels(selected, api)) {
+      outro(`Nothing curated. Retry with ${id('mo curate ' + selected)}.`)
+      return
+    }
+    outro(selfPricing
+      ? `Catalog complete — ${id('mo ls')} to see it, then ${id('mo ask <model> "…"')}.`
+      : `Prices are still missing — ${id('mo model instructions ' + selected)} fills them in.`)
     return
   }
 
-  await processModels(selected, api[selected])
-  outro(`Run ${id('mo model list')} to see your curated models.`)
+  await writeCatalogBrief(selected)
+}
+
+// The provider API returns model ids, never prices — entries land unpriced and
+// `cost` stays 0 on every result until the numbers are filled in. This is the
+// moment the user is still in the flow.
+async function writeCatalogBrief (selected) {
+  const { AGENTS, detectAssistants, preferredAgent, briefPrompt } = await import('../lib/assistants.js')
+  const installed = detectAssistants()
+
+  const stored = (await getConfig()).assistant
+  if (!installed.length && !stored) {
+    note(
+      `Nothing on your PATH looks like a coding agent. Mohdel does not ship
+one — Claude Code, Codex CLI and opencode all install from npm.
+
+Whichever you use has to be able to fetch a web page: it is being sent to
+read the provider's pricing page.
+
+To skip the agent entirely, use OpenRouter: it publishes prices in its own
+model list, so "mo curate openrouter" writes a complete catalog by itself.`,
+      'You will need an agent'
+    )
+  }
+  const chosen = await select({
+    message: 'Which coding agent do you use?',
+    initialValue: stored || installed[0] || AGENTS[0].bin,
+    options: [
+      ...AGENTS.map(a => ({
+        value: a.bin,
+        label: a.label,
+        hint: installed.includes(a.bin) ? 'found on your PATH' : undefined
+      })),
+      { value: '__other', label: 'Other…', hint: 'any command that takes a prompt' }
+    ]
+  })
+  if (isCancel(chosen)) return
+
+  let bin = chosen
+  if (chosen === '__other') {
+    const typed = await text({
+      message: 'Command that starts it:',
+      placeholder: 'my-agent',
+      validate: (v) => v?.trim() ? undefined : 'A command is required'
+    })
+    if (isCancel(typed)) return
+    bin = typed.trim()
+  }
+
+  const config = await getConfig()
+  await saveConfig({ ...config, assistant: bin })
+
+  const { writeBrief } = await import('./instructions.js')
+  const name = await writeBrief(selected)
+
+  const agent = preferredAgent(bin, installed)
+  const prompt = `"${briefPrompt(name, selected)}"`
+  note(
+    `${ok('✓')} Wrote ${meta(name)} in this directory.
+
+${agent.start(prompt)}
+
+The agent drafts mohdel-candidate.json and checks it with
+${meta('mo model check --entry mohdel-candidate.json')}; you apply it with
+${meta('mo model apply mohdel-candidate.json')}, which shows the diff first.`,
+    `Hand it to ${agent.label}`
+  )
+  outro(`Launch lines for other agents: ${id('mo model instructions --help')}`)
 }

package/src/cli/rank.js

@@ -15,7 +15,8 @@ Usage:
   model rank [options]
 
 Options:
-  --use-case <name>   Weight preset: ${USE_CASES.join(', ')} (default: balanced)
+  --use-case <name>   Weight preset (default: balanced)
+                      ${USE_CASES.join(', ')}
   --top N             Number of results (default: 20)
   --breakdown, -b     Show per-group sub-scores
   --all               Include all upstream models (default: curated only)

package/src/cli/ratelimit.js

@@ -19,9 +19,9 @@ Usage:
   ratelimit provider rm <provider>               Remove provider-level limits
 
 Examples:
-  ratelimit show anthropic                     Show provider limits
-  ratelimit show gemini/gemini-2.0-flash       Show model limits (with provider fallback)
-  ratelimit set gemini/gemini-2.0-flash 15 1000000
+  ratelimit show anthropic                   Provider limits
+  ratelimit show gemini/gemini-flash-latest  Model limits, then provider
+  ratelimit set gemini/gemini-flash-latest 15 1000000
   ratelimit provider set anthropic 60 100000
 
 Aliases:

package/src/cli/tag.js

@@ -1,6 +1,7 @@
 import mohdel, { silent } from '../lib/index.js'
 import { parseJsonFlag, jsonOutput } from './json-output.js'
 import { id, label, tag, meta, err } from './colors.js'
+import { EMPTY_CATALOG } from './model.js'
 
 // CLI logger: silent for noisy levels, console.error for errors and fatals.
 const cliLogger = { ...silent, error: console.error, fatal: console.error }
@@ -52,6 +53,7 @@ Usage:
       jsonOutput(sorted.map(t => ({ tag: t })), jsonFlag.fields)
       return
     }
+    if (!sorted.length) { console.log(meta(EMPTY_CATALOG)); return }
     for (const t of sorted) console.log(tag(t))
     return
   }

package/src/lib/assistants.js

@@ -0,0 +1,93 @@
+import { statSync } from 'node:fs'
+import { join, delimiter } from 'node:path'
+
+// Launch forms are the vendor-documented ones for starting a session on an
+// initial prompt — not the one-shot/print flags, since picking a model is a
+// conversation.
+const AGENTS = [
+  { bin: 'claude', label: 'Claude Code', start: p => `claude ${p}` },
+  { bin: 'codex', label: 'Codex CLI', start: p => `codex ${p}` },
+  { bin: 'gemini', label: 'Gemini CLI', start: p => `gemini -i ${p}` },
+  { bin: 'opencode', label: 'opencode', start: p => `opencode --prompt ${p}` },
+  { bin: 'cursor-agent', label: 'Cursor CLI', start: p => `cursor-agent ${p}`, note: "installs as 'agent' on some platforms" },
+  { bin: 'aider', label: 'Aider', start: p => `aider --message ${p}`, note: 'sends one message, then exits' }
+]
+
+const isExecutable = (path) => {
+  try {
+    const stat = statSync(path)
+    return stat.isFile() && (stat.mode & 0o111) !== 0
+  } catch {
+    return false
+  }
+}
+
+export const detectAssistants = () => {
+  const dirs = (process.env.PATH || '').split(delimiter).filter(Boolean)
+  return AGENTS.map(a => a.bin).filter(bin => dirs.some(dir => isExecutable(join(dir, bin))))
+}
+
+const TOP = AGENTS.slice(0, 5)
+
+export const launchLines = (installed = detectAssistants(), chosen = null, indent = '     ') => {
+  const rows = chosen && !AGENTS.some(a => a.bin === chosen) ? [custom(chosen), ...TOP] : TOP
+  const width = Math.max(...rows.map(a => a.start('"<prompt>"').length))
+  return rows.map(a => {
+    const mark = a.bin === chosen
+      ? '← yours'
+      : installed.includes(a.bin) ? '← on your PATH' : null
+    const marks = [mark, a.note].filter(Boolean)
+    const line = indent + a.start('"<prompt>"')
+    return marks.length ? `${line.padEnd(indent.length + width + 3)}${marks.join('; ')}` : line
+  })
+}
+
+// A binary the user named that mohdel has no entry for. Passing the prompt as
+// one argument is the form every agent CLI accepts.
+const custom = (bin) => ({ bin, label: bin, start: p => `${bin} ${p}` })
+
+// Which agent the recipe should name. A stated preference beats detection —
+// PATH cannot see which of two installed agents someone actually uses, nor an
+// agent that lives in an editor.
+export const preferredAgent = (chosen, installed = detectAssistants()) => {
+  if (chosen) return AGENTS.find(a => a.bin === chosen) || custom(chosen)
+  return TOP.find(a => installed.includes(a.bin)) || TOP[0]
+}
+
+export const handoff = (provider, installed = detectAssistants(), chosen = null) => {
+  const scope = provider ? ` ${provider}` : ''
+
+  const none = installed.length === 0 && !chosen
+    ? `
+
+Nothing on your PATH looks like a coding agent. Mohdel does not ship one;
+Claude Code, Codex CLI and opencode all install from npm.
+
+You can also skip the agent entirely: OpenRouter publishes prices in its own
+model list, so 'mo curate openrouter' writes a complete catalog with no brief
+and no pricing page. It has a free tier and needs no card.`
+    : ''
+
+  return `This brief is written for a coding agent, not for you.${none}
+
+1. mo model instructions${scope} > mohdel-brief.md
+
+2. start your coding agent on <prompt>:
+
+     ${briefPrompt('mohdel-brief.md', provider)}
+
+${launchLines(installed, chosen).join('\n')}
+
+   Any other agent works too, with one requirement: it must be able to fetch a
+   web page. The brief sends it to the provider's pricing page, and an agent
+   that cannot read one will either stop or guess.
+
+3. it drafts mohdel-candidate.json and checks it with
+   'mo model check --entry mohdel-candidate.json', then hands you
+   'mo model apply mohdel-candidate.json' — which shows the diff before writing.`
+}
+
+export const briefPrompt = (file, provider) =>
+  `read ${file} and add ${provider ? provider + ' ' : ''}models to my mohdel catalog`
+
+export { AGENTS }

package/src/lib/catalog/openrouter.js

@@ -21,7 +21,12 @@ export default (sdkConfig) => {
     return cache
   }
   return {
-    listModels: async () => (await load()).map(m => ({ id: m.id, label: m.name || m.id })),
+    listModels: async () => (await load()).map(m => ({
+      id: m.id,
+      label: m.name || m.id,
+      inputPrice: toPerMillion(m.pricing?.prompt),
+      outputPrice: toPerMillion(m.pricing?.completion)
+    })),
     getModelInfo: async (id) => {
       const m = (await load()).find(x => x.id === id)
       if (!m) return null

package/src/lib/catalog-review.js

@@ -0,0 +1,195 @@
+import providers from './providers.js'
+import { validate, isValidTag, stripComputed } from './schema.js'
+import { isMetaKey, catalogEntries } from './common.js'
+import { SPEED_LANES } from '../../js/session/adapters/_registry.js'
+import { catalogKey } from '../../js/core/model-id.js'
+
+const sortDeep = (value) => {
+  if (Array.isArray(value)) return value.map(sortDeep)
+  if (value && typeof value === 'object') {
+    const sorted = {}
+    for (const key of Object.keys(value).sort()) sorted[key] = sortDeep(value[key])
+    return sorted
+  }
+  return value
+}
+
+const same = (a, b) => JSON.stringify(sortDeep(a)) === JSON.stringify(sortDeep(b))
+
+const TYPE_OF = (value) => Array.isArray(value) ? 'array' : typeof value
+
+const reviewLocal = (key, spec, local) => {
+  const errors = []
+  const warnings = []
+
+  for (const [field, def] of Object.entries(local.fields)) {
+    const value = spec[field]
+    if (value === undefined) continue
+    if (TYPE_OF(value) !== def.type) {
+      errors.push(`${key}: ${field} — expected ${def.type}, got ${TYPE_OF(value)} (local field)`)
+    }
+  }
+
+  for (const tag of spec.tags || []) {
+    const def = local.tags[tag]
+    if (!def) continue
+    const missing = def.requires.filter(field => spec[field] === undefined)
+    if (!missing.length) continue
+    const message = `${key}: tag '${tag}' requires ${missing.join(', ')} — ${def.description}`
+    if (def.severity === 'error') errors.push(message)
+    else warnings.push(message)
+  }
+
+  return { errors, warnings }
+}
+
+export const reviewEntry = (key, spec, catalog, { strict = false, local = null } = {}) => {
+  const errors = []
+  const warnings = []
+  const [keyProvider] = key.split('/')
+
+  if (catalogKey(key) !== key) {
+    errors.push(`${key}: catalog key carries a ':effort' or '@speed' suffix — those are call-time, not entry keys`)
+  }
+
+  if (spec.deprecated) {
+    if (!catalog[spec.deprecated]) {
+      errors.push(`${key}: deprecated target '${spec.deprecated}' not in curated`)
+    }
+    return { errors, warnings }
+  }
+
+  for (const issue of validate(spec, key, { strict })) {
+    // Custom fields are namespaced by convention (docs/CATALOG.md) and
+    // round-trip untouched, so they are not drift.
+    if (issue.message === 'unknown field' && issue.field.includes(':')) continue
+    if (issue.message === 'unknown field' && local?.fields[issue.field]) continue
+    if (issue.severity === 'error') errors.push(`${key}: ${issue.field} — ${issue.message}`)
+    else warnings.push(`${key}: ${issue.field} — ${issue.message}`)
+  }
+
+  const providerConfig = providers[keyProvider]
+  if (!providerConfig) {
+    errors.push(`${key}: provider '${keyProvider}' not in providers.js`)
+  }
+  if (spec.provider && spec.provider !== keyProvider) {
+    errors.push(`${key}: spec.provider '${spec.provider}' doesn't match key prefix '${keyProvider}'`)
+  }
+  if (providerConfig && spec.sdk && spec.sdk !== providerConfig.sdk) {
+    errors.push(`${key}: spec.sdk '${spec.sdk}' doesn't match provider sdk '${providerConfig.sdk}'`)
+  }
+
+  if (!spec.label) warnings.push(`${key}: missing label`)
+
+  for (const priceField of ['inputPrice', 'outputPrice', 'thinkingPrice']) {
+    const val = spec[priceField]
+    if (val != null && typeof val === 'object' && val.default == null) {
+      errors.push(`${key}: ${priceField} is tiered but missing 'default' key`)
+    }
+  }
+
+  if (spec.thinkingEffortLevels && !spec.defaultThinkingEffort) {
+    warnings.push(`${key}: has thinkingEffortLevels but no defaultThinkingEffort`)
+  }
+
+  const lanes = SPEED_LANES[keyProvider]
+  for (const [lane, overlay] of Object.entries(spec.speeds || {})) {
+    if (!lanes?.has(lane)) {
+      const detail = lanes ? `accepts: ${[...lanes].join(', ')}` : 'implements no speed lanes'
+      errors.push(`${key}: speeds.${lane} — provider '${keyProvider}' ${detail}; calls on that lane would fail at dispatch`)
+    }
+    for (const priceField of ['inputPrice', 'outputPrice', 'thinkingPrice']) {
+      const val = overlay[priceField]
+      if (val != null && typeof val === 'object' && val.default == null) {
+        errors.push(`${key}: speeds.${lane}.${priceField} is tiered but missing 'default' key`)
+      }
+    }
+    const priced = ['inputPrice', 'outputPrice'].some(f => overlay[f] != null)
+    if (!priced) {
+      warnings.push(`${key}: speeds.${lane} restates no prices — the lane will bill at base rates`)
+    }
+  }
+
+  if (Array.isArray(spec.tags)) {
+    for (const t of spec.tags) {
+      if (!isValidTag(t)) warnings.push(`${key}: invalid tag "${t}" — must match /^[a-zA-Z][a-zA-Z0-9._-]{0,31}$/`)
+    }
+  }
+
+  if (local) {
+    const localIssues = reviewLocal(key, spec, local)
+    errors.push(...localIssues.errors)
+    warnings.push(...localIssues.warnings)
+  }
+
+  return { errors, warnings }
+}
+
+export const reviewCatalog = (catalog, { local = null } = {}) => {
+  const errors = []
+  const warnings = []
+  for (const [key, spec] of catalogEntries(catalog)) {
+    const entry = reviewEntry(key, spec, catalog, { local })
+    errors.push(...entry.errors)
+    warnings.push(...entry.warnings)
+  }
+  return { errors, warnings }
+}
+
+export const diffEntry = (before, after) => {
+  const from = before ? stripComputed(before) : {}
+  const to = stripComputed(after)
+  const fields = [...new Set([...Object.keys(from), ...Object.keys(to)])].sort()
+  const changes = []
+  for (const field of fields) {
+    if (same(from[field], to[field])) continue
+    changes.push({ field, from: from[field], to: to[field] })
+  }
+  return changes
+}
+
+export const parseCandidates = (text) => {
+  let doc
+  try {
+    doc = JSON.parse(text)
+  } catch (e) {
+    throw new Error(`candidate is not valid JSON: ${e.message}`)
+  }
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+    throw new Error('candidate must be a JSON object keyed by model id: { "<provider>/<model>": { … } }')
+  }
+
+  const entries = {}
+  const ignored = []
+  for (const [key, value] of Object.entries(doc)) {
+    if (isMetaKey(key)) {
+      ignored.push(key)
+      continue
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      const got = Array.isArray(value) ? 'array' : typeof value
+      throw new Error(`'${key}' maps to a ${got}, not an entry object — the shape is { "<provider>/<model>": { … } }`)
+    }
+    entries[key] = value
+  }
+  if (!Object.keys(entries).length) {
+    throw new Error('candidate contains no entries')
+  }
+  return { entries, ignored }
+}
+
+export const reviewCandidates = (catalog, entries, { local = null } = {}) => {
+  const merged = { ...catalog, ...entries }
+  return Object.entries(entries).map(([key, entry]) => {
+    const { errors, warnings } = reviewEntry(key, entry, merged, { strict: true, local })
+    const existing = catalog[key]
+    const changes = diffEntry(existing, entry)
+    return {
+      key,
+      status: existing ? (changes.length ? 'changed' : 'unchanged') : 'new',
+      errors,
+      warnings,
+      changes
+    }
+  })
+}