mohdel 0.125.0 → 1.0.0

package/js/session/run_image.js

@@ -13,7 +13,7 @@
  * @module session/run_image
  */
 
-import { getImageAdapter } from './adapters/image/index.js'
+import { IMAGE_ADAPTER_NAMES } from './adapters/_registry.js'
 import { classifyProviderError } from './adapters/_errors.js'
 import { providerOf } from '#core/model-id.js'
 
@@ -31,10 +31,19 @@ import { providerOf } from '#core/model-id.js'
  *   | {ok: false, error: import('#core/errors.js').TypedError}
  * >}
  */
-export async function runImage (envelope, { resolveAdapter = getImageAdapter, spec } = {}) {
+// Loaded per provider rather than as a registry: the image adapters pull the
+// OpenAI SDK, which a text-only caller never needs. Checked against the known
+// list first — the name comes off the envelope.
+const loadImageAdapter = async (provider) => {
+  if (!IMAGE_ADAPTER_NAMES.includes(provider)) throw new Error(`no image adapter for provider: ${provider}`)
+  const module = await import(`./adapters/image/${provider}.js`)
+  return module[`${provider}Image`]
+}
+
+export async function runImage (envelope, { resolveAdapter = loadImageAdapter, spec } = {}) {
   let adapter
   try {
-    adapter = resolveAdapter(providerOf(envelope.model))
+    adapter = await resolveAdapter(providerOf(envelope.model))
   } catch (e) {
     return {
       ok: false,

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "mohdel",
-  "version": "0.125.0",
+  "version": "1.0.0",
   "license": "MIT",
   "author": {
     "name": "Christophe Le Bars",
     "email": "clb@toort.net"
   },
-  "description": "Self-hosted LLM gateway and SDK for Node — a LiteLLM-style unified API for 11 providers (Anthropic, OpenAI, Gemini, Mistral, Groq, xAI, DeepSeek, OpenRouter, …) with per-call USD cost tracking, streaming, tool calls, vision, speech-to-text, and built-in OpenTelemetry. Run in-process, or behind the process-isolated thin-gate for fault containment.",
+  "description": "Self-hosted LLM gateway and SDK for Node — a LiteLLM-style unified API for 13 providers (Anthropic, OpenAI, Gemini, Mistral, Groq, xAI, DeepSeek, OpenRouter, …) with per-call USD cost tracking, streaming, tool calls, vision, speech-to-text, and built-in OpenTelemetry. Run in-process, or behind the process-isolated thin-gate for fault containment.",
   "type": "module",
   "keywords": [
     "llm",
@@ -42,14 +42,38 @@
   },
   "main": "src/lib/index.js",
   "exports": {
-    ".": "./src/lib/index.js",
-    "./providers": "./src/lib/providers.js",
-    "./creators": "./src/lib/creators.js",
-    "./utils": "./src/lib/utils.js",
-    "./errors": "./js/core/errors.js",
-    "./client": "./js/client/index.js",
-    "./session": "./js/session/index.js",
-    "./session/bin": "./js/session/bin.js"
+    ".": {
+      "types": "./src/lib/index.d.ts",
+      "default": "./src/lib/index.js"
+    },
+    "./providers": {
+      "types": "./src/lib/providers.d.ts",
+      "default": "./src/lib/providers.js"
+    },
+    "./creators": {
+      "types": "./src/lib/creators.d.ts",
+      "default": "./src/lib/creators.js"
+    },
+    "./utils": {
+      "types": "./src/lib/utils.d.ts",
+      "default": "./src/lib/utils.js"
+    },
+    "./errors": {
+      "types": "./js/core/errors.d.ts",
+      "default": "./js/core/errors.js"
+    },
+    "./client": {
+      "types": "./js/client/index.d.ts",
+      "default": "./js/client/index.js"
+    },
+    "./session": {
+      "types": "./js/session/index.d.ts",
+      "default": "./js/session/index.js"
+    },
+    "./session/bin": {
+      "types": "./js/session/bin.d.ts",
+      "default": "./js/session/bin.js"
+    }
   },
   "imports": {
     "#core": "./js/core/index.js",
@@ -64,7 +88,9 @@
     "src/cli",
     "config",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "js/**/*.d.ts",
+    "src/lib/**/*.d.ts"
   ],
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -73,10 +99,12 @@
   },
   "scripts": {
     "lint": "standard",
+    "clean:types": "find js src/lib -name '*.d.ts' -delete",
+    "build:types": "npm run clean:types && tsc -p tsconfig.build.json",
     "test": "npm run test:js && npm run test:rust",
     "test:js": "vitest run test/unit",
     "test:rust": "cargo test --manifest-path rust/thin-gate/Cargo.toml && cargo test --manifest-path rust/napi-addon/Cargo.toml",
-    "prerelease": "npm run lint && npm run test",
+    "prerelease": "npm run lint && npm run build:types && npm run test",
     "release": "release-it",
     "test:provider": "vitest run test/integration/provider.test.js",
     "test:multiturn": "vitest run test/integration/multiturn.test.js",
@@ -104,20 +132,20 @@
     }
   },
   "optionalDependencies": {
-    "@clack/prompts": "^1.7.0",
+    "@clack/prompts": "^1.8.8",
     "@opentelemetry/exporter-trace-otlp-grpc": "^0.222.0",
     "@opentelemetry/sdk-node": "^0.222.0",
     "chalk": "^6.0.0",
-    "mohdel-thin-gate-linux-x64-gnu": "0.125.0"
+    "mohdel-thin-gate-linux-x64-gnu": "1.0.0"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.123.0",
+    "@anthropic-ai/sdk": "^0.125.0",
     "@cerebras/cerebras_cloud_sdk": "^1.91.0",
-    "@google/genai": "^2.21.0",
+    "@google/genai": "^2.22.0",
     "@opentelemetry/api": "^1.9.1",
     "env-paths": "^4.0.0",
     "groq-sdk": "^1.6.0",
-    "openai": "^7.9.0",
+    "openai": "^7.15.0",
     "undici": "^7.29.0"
   },
   "lint-staged": {
@@ -125,9 +153,11 @@
   },
   "devDependencies": {
     "gpt-tokenizer": "^4.0.0",
-    "lint-staged": "^17.4.1",
+    "lint-staged": "^17.5.1",
     "release-it": "^21.0.2",
     "standard": "^17.1.2",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.11"
-  }
+  },
+  "types": "./src/lib/index.d.ts"
 }

package/src/cli/aliases.js

@@ -0,0 +1,20 @@
+// Short commands → noun + verb. Shared by dispatch and by completion, which
+// must resolve the same chain the router would.
+export const ALIASES = {
+  models: { noun: 'model', inject: ['list'] },
+  providers: { noun: 'provider', inject: ['list'] },
+  creators: { noun: 'creator', inject: ['list'] },
+  tags: { noun: 'tag', inject: ['list'] },
+  ls: { noun: 'model', inject: ['list'] },
+  show: { noun: 'model', inject: ['show'] },
+  search: { noun: 'model', inject: ['search'] },
+  stats: { noun: 'model', inject: ['stats'] },
+  check: { noun: 'model', inject: ['check'] },
+  setup: { noun: 'provider', inject: ['setup'] },
+  rank: { noun: 'model', inject: ['rank'] },
+  bench: { noun: 'model', inject: ['bench'] },
+  curate: { noun: 'model', inject: ['curate'] },
+  apply: { noun: 'model', inject: ['apply'] },
+  instructions: { noun: 'model', inject: ['instructions'] },
+  rl: { noun: 'ratelimit', inject: [] }
+}

package/src/cli/ask.js

@@ -1,11 +1,28 @@
 import mohdel, { silent } from '../lib/index.js'
-import { loadDefaultEnv } from '../lib/common.js'
+import { getConfig, loadDefaultEnv } from '../lib/common.js'
 
 const noop = () => {}
 
 // Friendly next-step hints for common ask-time failures. Pure pattern match on
 // err.message — keeps the lib layer neutral, but gives CLI users a copy-pasteable
 // command instead of just an error. Shared with `mo transcribe`.
+// Waiting on a model is the one place mohdel has nothing to show for several
+// seconds. The frames carry the resolved id, so the id is visible while it is
+// useful and gone afterwards. stderr only, so pipes see nothing.
+const startSpinner = (text) => {
+  if (!process.stderr.isTTY) return null
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+  let i = 0
+  const timer = setInterval(() => {
+    process.stderr.write(`\r${frames[i++ % frames.length]} ${text}`)
+  }, 80)
+  timer.unref?.()
+  return () => {
+    clearInterval(timer)
+    process.stderr.write('\r\u001b[K')
+  }
+}
+
 export const hintsForError = (err, modelId) => {
   const msg = String(err?.message || '')
   const detail = String(err?.detail || '')
@@ -16,6 +33,7 @@ export const hintsForError = (err, modelId) => {
   if (/not found in catalog/i.test(both)) {
     if (provider) {
       hints.push(`→ run:  mo curate ${provider}        # add upstream models from this provider`)
+      hints.push(`→ then: mo model instructions ${provider}   # let your coding agent fill in the prices`)
       hints.push(`→ or:   mo model add ${modelId}      # add this one manually`)
     } else {
       hints.push('→ run:  mo ls                       # list available models')
@@ -49,18 +67,21 @@ Usage:
   mo ask <model> "question" < file     Combined: args + stdin
 
 Options:
-  --effort <level>     Thinking effort: high, medium, low, none
+  --effort <level>     Thinking effort: none, low, medium, high, xhigh, max
   --budget <tokens>    Output token budget
   --json               Output full result as JSON
   --stream             Stream output to stdout in real time
-  -v, --verbose        Show debug info on stderr (cooldown, rate limit, SDK calls)
+  -v, --verbose        Show debug info on stderr (cooldown, rate limits)
+  -q, --quiet          Nothing on stderr but errors — no usage summary
 
 Output:
   stdout: model output text (raw, no formatting — or JSON with --json)
-  stderr: model name + token usage summary
+  stderr: token usage summary, and errors
+          --json omits the summary (the same numbers are in the payload);
+          --quiet omits it too, leaving stderr for failures alone
 
 Examples:
-  mo ask gemini/gemini-3-flash-preview "why is the sky blue"
+  mo ask openai/gpt-5.6-luna "why is the sky blue"
   cat article.txt | mo ask anthropic/claude-sonnet-4-6 "summarize this"
   mo ask openai/gpt-5.4 --effort high "explain monads" --json | jq .cost`)
     process.exit(0)
@@ -86,18 +107,23 @@ Examples:
   const json = flag('--json')
   const stream = flag('--stream')
   const verbose = flag('--verbose') || flag('-v')
+  const quiet = flag('--quiet') || flag('-q')
   const effort = flagVal('--effort')
   const budget = flagVal('--budget')
 
   // First remaining arg is model
-  const modelId = args[0]
+  // A model id always carries a provider segment, so a first argument without
+  // a slash is prompt text and the configured default model applies. Typing a
+  // full id on every call is the first thing that wears out.
+  const given = args[0]?.includes('/') ? args[0] : null
+  const modelId = given ?? (await getConfig()).defaultModel
   if (!modelId) {
     console.error('Usage: mo ask <model> [prompt]')
+    console.error('→ or:   mo default                   # pick one, then "mo ask" needs no model')
     process.exit(1)
   }
 
-  // Remaining args form the prompt
-  const promptArgs = args.slice(1).join(' ').trim()
+  const promptArgs = args.slice(given ? 1 : 0).join(' ').trim()
 
   // Read stdin if piped
   let stdinContent = ''
@@ -140,15 +166,32 @@ Examples:
   const options = {}
   if (effort) options.outputEffort = effort
   if (budget) options.outputBudget = parseInt(budget, 10)
+
+  // --verbose puts log lines on stderr on purpose; a spinner would be
+  // overwritten by them and leave its last frame behind.
+  const stopSpinner = (json || verbose || quiet) ? null : startSpinner(model.id)
+  let stopped = false
+  const stop = () => {
+    if (stopped) return
+    stopped = true
+    stopSpinner?.()
+  }
+
   if (stream && !json) {
-    options.realtimeHandler = (delta) => process.stdout.write(delta)
+    options.realtimeHandler = (delta) => {
+      stop()
+      process.stdout.write(delta)
+    }
     options.bufferOpts = { maxChars: 1, maxMs: 0 }
   }
 
-  process.stderr.write(`${model.id}\n`)
+  // Without a terminal the id is worth echoing only when it is not what was
+  // typed — an alias or a partial that resolved to something else.
+  if (!stopSpinner && !quiet && model.id !== modelId) process.stderr.write(`${model.id}\n`)
 
   try {
     const result = await model.answer(prompt, options)
+    stop()
     const output = typeof result === 'string' ? result : result?.output || ''
     const tokens = typeof result === 'object' ? result : {}
 
@@ -170,7 +213,7 @@ Examples:
       if (output && !output.endsWith('\n')) process.stdout.write('\n')
     }
 
-    // Token + timing summary to stderr
+    // Token + timing summary to stderr.
     const summary = []
     if (tokens.inputTokens) summary.push(`${tokens.inputTokens} in`)
     if (tokens.outputTokens) summary.push(`${tokens.outputTokens} out`)
@@ -195,8 +238,11 @@ Examples:
       if (ttft != null) summary.push(`${Math.round(ttft)}ms ttft`)
       if (total != null) summary.push(`${Math.round(total)}ms total`)
     }
-    if (summary.length) process.stderr.write(`${summary.join(', ')}\n`)
+    // --json already carries these numbers in the payload; --quiet keeps
+    // stderr free so a caller can treat anything on it as a failure.
+    if (summary.length && !json && !quiet) process.stderr.write(`${summary.join(', ')}\n`)
   } catch (err) {
+    stop()
     console.error(`Error: ${err.detail || err.message}`)
     for (const h of hintsForError(err, modelId)) console.error(h)
     process.exit(1)

package/src/cli/backup.js

@@ -14,7 +14,8 @@ Usage:
   model backup restore <slot>      Restore from a backup slot
   model backup diff <slot>         Show changes between current and slot
 
-Slots: prev (last save), daily (first save of the day), weekly (first save of the week)`)
+Slots: prev (last save), daily (first save of the day),
+       weekly (first save of the week)`)
     process.exit(0)
   }
 

package/src/cli/check.js

@@ -1,106 +1,35 @@
 import { label, err, warn, ok } from './colors.js'
-import providers from '../lib/providers.js'
-import { validate, isValidTag } from '../lib/schema.js'
-import { adapters } from '../../js/session/adapters/index.js'
-import { getCuratedModels, loadDefaultEnv, catalogEntries, catalogValues } from '../lib/common.js'
-
-// --- Local validation ---
-
-const checkLocal = (curated) => {
-  const errors = []
-  const warnings = []
-  const knownProviders = new Set(Object.keys(providers))
-
-  for (const [key, spec] of catalogEntries(curated)) {
-    const [keyProvider] = key.split('/')
-
-    if (spec.deprecated) {
-      if (!curated[spec.deprecated]) {
-        errors.push(`${key}: deprecated target '${spec.deprecated}' not in curated`)
-      }
-      continue
-    }
-
-    for (const issue of validate(spec, key)) {
-      if (issue.severity === 'error') errors.push(`${key}: ${issue.field} — ${issue.message}`)
-      else warnings.push(`${key}: ${issue.field} — ${issue.message}`)
-    }
-
-    if (!knownProviders.has(keyProvider)) {
-      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}'`)
-    }
-
-    const providerConfig = providers[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 = adapters[keyProvider]?.speedLanes
-    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}$/`)
-      }
-    }
-  }
-
-  return { errors, warnings }
-}
+import { reviewCatalog } from '../lib/catalog-review.js'
+import { localConventionsOrExit } from './local.js'
+import { getCuratedModels, loadDefaultEnv, catalogValues } from '../lib/common.js'
 
 // --- CLI ---
 
 export async function runCheck (args) {
   if (args.includes('-h') || args.includes('--help')) {
-    console.log(`mohdel model check — validate curated catalog
+    console.log(`mohdel model check — validate the catalog
 
 Usage:
   model check [options]
+  model check --entry <file|->   Validate entries not yet in the catalog
 
 Options:
   --json               Output as JSON
+  --entry <file|->     Read entries in curated.json shape and report what they
+                       would change, without writing. 'mo model apply' writes.
 
 Checks:
   Schema types, required fields, deprecated targets, provider/sdk
-  consistency, tiered pricing, thinking config.
-
-Note: 0.90 drops the upstream-drift check that piggybacked on the
-legacy per-provider SDK factory. If you need upstream drift
-detection, file an issue — it'll be rebuilt on the /session stack.`)
+  consistency, tiered pricing, thinking config.`)
     process.exit(0)
   }
 
+  if (args.includes('--entry')) {
+    const { runCheckEntry } = await import('./entry.js')
+    await runCheckEntry(args)
+    return
+  }
+
   loadDefaultEnv()
 
   const json = args.includes('--json')
@@ -114,7 +43,7 @@ detection, file an issue — it'll be rebuilt on the /session stack.`)
     console.log(`${label('Catalog:')} ${active} active, ${deprecated} deprecated\n`)
   }
 
-  const { errors, warnings: localWarnings } = checkLocal(curated)
+  const { errors, warnings: localWarnings } = reviewCatalog(curated, { local: await localConventionsOrExit() })
 
   if (!json) {
     if (errors.length) {

package/src/cli/complete.js

@@ -0,0 +1,130 @@
+import providerDefs from '../lib/providers.js'
+import { fieldDefs } from '../lib/schema.js'
+import { getCuratedModels, catalogEntries } from '../lib/common.js'
+import { ALIASES } from './aliases.js'
+
+// Completion must never import the factory (`src/lib/index.js`), which pulls
+// every adapter, provider SDK and the OTel stack — 350ms that would be paid on
+// every press of the tab key. Reading the catalog costs about 30ms.
+
+const NOUNS = ['model', 'provider', 'creator', 'tag', 'ratelimit', 'ask', 'transcribe', 'default', 'doctor']
+
+const VERBS = {
+  model: ['list', 'search', 'stats', 'show', 'get', 'set', 'rm', 'add', 'instructions',
+    'check', 'apply', 'rank', 'bench', 'curate', 'backup'],
+  provider: ['list', 'show', 'models', 'setup', 'rm'],
+  creator: ['list', 'show'],
+  tag: ['list', 'show', 'add', 'rm'],
+  ratelimit: ['show', 'set', 'rm', 'provider']
+}
+
+// What the argument at a given offset after `<noun> <verb>` names. `model` is
+// an id already in the catalog, so `model add` — which takes a new one — is
+// deliberately absent.
+const ARGUMENT = {
+  ask: ['model'],
+  transcribe: ['model'],
+  'model show': ['model'],
+  'model get': ['model', 'field'],
+  'model set': ['model', 'field'],
+  'model rm': ['model', 'field'],
+  'model bench': ['model'],
+  'model curate': ['provider'],
+  'model instructions': ['provider'],
+  'provider list': ['provider'],
+  'provider show': ['provider'],
+  'provider models': ['provider'],
+  'provider setup': ['provider'],
+  'provider rm': ['provider'],
+  'creator show': ['creator'],
+  'tag list': ['model'],
+  'tag show': ['tag'],
+  'tag add': ['model', 'tag'],
+  'tag rm': ['model', 'tag'],
+  'ratelimit show': ['model'],
+  'ratelimit set': ['model'],
+  'ratelimit rm': ['model']
+}
+
+const fromCatalog = async (pick) => {
+  const catalog = await getCuratedModels()
+  const out = new Set()
+  for (const [key, spec] of catalogEntries(catalog)) {
+    if (spec.deprecated) continue
+    pick(key, spec, out)
+  }
+  return [...out]
+}
+
+const kinds = {
+  model: () => fromCatalog((key, _spec, out) => out.add(key)),
+  creator: () => fromCatalog((_key, spec, out) => spec.creator && out.add(spec.creator)),
+  tag: () => fromCatalog((_key, spec, out) => (spec.tags || []).forEach(t => out.add(t))),
+  provider: async () => Object.keys(providerDefs),
+  field: async () => Object.keys(fieldDefs)
+}
+
+/**
+ * @param {number} cword  Index of the word being completed (bash COMP_CWORD).
+ * @param {string[]} words  The full command line, split (bash COMP_WORDS).
+ * @returns {Promise<string[]>}
+ */
+export const candidates = async (cword, words) => {
+  const current = words[cword] ?? ''
+  const before = words.slice(1, cword).filter(w => !w.startsWith('-'))
+
+  const offer = (list) => list.filter(c => c.startsWith(current)).sort()
+
+  if (!before.length) {
+    return offer([...NOUNS, ...Object.keys(ALIASES)])
+  }
+
+  // Resolve the alias exactly as the router does, so completion and dispatch
+  // never disagree about what a word means.
+  const alias = ALIASES[before[0]]
+  const chain = alias ? [alias.noun, ...alias.inject, ...before.slice(1)] : before
+  const [noun, verb, ...rest] = chain
+
+  if (chain.length === 1 && VERBS[noun]) return offer(VERBS[noun])
+
+  // `model show <id>` keys on two words; `ask <id>` on one. Whichever matched
+  // decides where the argument list starts.
+  const paired = ARGUMENT[`${noun} ${verb}`]
+  const shape = paired ?? ARGUMENT[noun]
+  if (!shape) return []
+  const typed = paired ? rest : [verb, ...rest].filter(Boolean)
+
+  const kind = shape[typed.length]
+  if (!kind || !kinds[kind]) return []
+  return offer(await kinds[kind]())
+}
+
+export const BASH_SCRIPT = `# mohdel completion for bash.  Add to ~/.bashrc:
+#   source <(mo completion bash)
+_mo_completion() {
+  local IFS=$'\\n'
+  COMPREPLY=($(mo __complete "$COMP_CWORD" "\${COMP_WORDS[@]}" 2>/dev/null))
+}
+complete -o default -F _mo_completion mo
+`
+
+export async function runComplete (args) {
+  // A crash here would break the user's tab key, so an unreadable or corrupt
+  // catalog offers nothing rather than an error.
+  try {
+    const cword = Number.parseInt(args[0], 10)
+    if (!Number.isFinite(cword)) return
+    const list = await candidates(cword, args.slice(1))
+    if (list.length) process.stdout.write(`${list.join('\n')}\n`)
+  } catch {}
+}
+
+export function runCompletionScript (args) {
+  const shell = args[0]
+  if (shell === 'bash') {
+    process.stdout.write(BASH_SCRIPT)
+    return
+  }
+  console.error(`Usage: mo completion bash${shell ? `  (got "${shell}")` : ''}`)
+  process.exit(1)
+}

package/src/cli/default.js

@@ -1,11 +1,37 @@
 import { intro, outro, select, isCancel, cancel } from '@clack/prompts'
-import { getCuratedModels, CONFIG_PATH, saveConfig, catalogEntries } from '../lib/common.js'
-import providers from '../lib/providers.js'
+import { getConfig, getCuratedModels, saveConfig, catalogEntries } from '../lib/common.js'
 
-export async function runDefault () {
-  intro('Mohdel — Set Default Model')
+// CLI-only. The default model is a convenience for someone typing `mo ask`;
+// the library and the gate never read it. A program picks a model by id or by
+// tag, where the choice is explicit and reviewable — a machine inheriting a
+// human's terminal preference is how a call ends up on a model nobody chose.
+export async function runDefault (args = []) {
+  if (args.includes('-h') || args.includes('--help')) {
+    console.log(`mohdel default — the model "mo ask" uses when you name none
+
+Usage:
+  default                Pick one from your catalog (interactive)
+  default <model>        Set it directly
+
+Stored in ~/.config/mohdel/default.json. The library and the gate never
+read it: a program names its model, or selects one by tag.`)
+    process.exit(0)
+  }
 
   const curated = await getCuratedModels()
+
+  const named = args.find(a => !a.startsWith('-'))
+  if (named) {
+    if (!curated[named] || curated[named].deprecated) {
+      console.error(`'${named}' is not a model in your catalog. "mo ls" lists them.`)
+      process.exit(1)
+    }
+    await saveConfig({ ...(await getConfig()), defaultModel: named })
+    console.log(`Default set to ${named} — "mo ask" uses it when you give no model.`)
+    return
+  }
+
+  intro('mohdel — set the default model')
   const modelOptions = catalogEntries(curated).map(([modelId, info]) => ({
     value: modelId,
     label: `${info.label} (${modelId})`
@@ -22,16 +48,11 @@ export async function runDefault () {
     process.exit(0)
   }
 
-  const [providerName] = selectedModelId.split('/')
-
   try {
-    const config = { defaultModel: selectedModelId }
-    const apiKeyEnv = providers[providerName]?.apiKeyEnv
-    if (apiKeyEnv) {
-      config.apiKeyInfo = `Set ${apiKeyEnv} environment variable for this provider`
-    }
-    await saveConfig(config)
-    outro(`Default set to ${selectedModelId} — saved to ${CONFIG_PATH}`)
+    // Merge: the file also holds the chosen coding agent, and replacing the
+    // object wholesale would drop it.
+    await saveConfig({ ...(await getConfig()), defaultModel: selectedModelId })
+    outro(`Default set to ${selectedModelId} — "mo ask" uses it when you give no model.`)
   } catch (err) {
     cancel(`Error: ${err.message}`)
     process.exit(1)