diff --git a/frontend/src/components/pages/model-management-dialog.tsx b/frontend/src/components/pages/model-management-dialog.tsx
index 00e21283e..a3851203b 100644
--- a/frontend/src/components/pages/model-management-dialog.tsx
+++ b/frontend/src/components/pages/model-management-dialog.tsx
@@ -1,6 +1,6 @@
 "use client"
 
-import { useState, useMemo } from "react"
+import { useState, useMemo, useRef } from "react"
 import { Button } from "@/components/ui/button"
 import { Input } from "@/components/ui/input"
 import { Label } from "@/components/ui/label"
@@ -13,11 +13,13 @@ import { getApiUrl } from "@/lib/utils"
 import { useAuth } from "@/contexts/auth-context"
 import { apiRequest } from "@/lib/api-wrapper"
 import {
+  AbilitySuggestion,
   DefaultModelType,
+  getAbilitySuggestion,
   getProviderModels,
   ProviderModel,
   removeUserDefaultModel,
-  setUserDefaultModel
+  setUserDefaultModel,
 } from "@/lib/models"
 import {
   ArrowLeft,
@@ -92,6 +94,33 @@ export function ModelManagementDialog({
   const [hasInitializedDefaults, setHasInitializedDefaults] = useState(false)
   const [selectedDefaultConfigTypes, setSelectedDefaultConfigTypes] = useState<string[]>([])
 
+  // Ability auto-fill from curated catalog.
+  // - userTouchedAbilities: once the user clicks any ability button we stop
+  //   overwriting their selection. This survives switching to a different
+  //   model_name within the same Add-Model session, by design.
+  //   Initialised to true when the dialog opens in edit mode so we never
+  //   silently overwrite abilities the user previously chose.
+  // - abilitySuggestion: the latest catalog response, used to render a hint.
+  // - suggestionRequestCounter: monotonic counter used to discard responses
+  //   from stale in-flight requests when the user types quickly (e.g. in
+  //   the edit-mode Input where every keystroke triggers a lookup). Without
+  //   this, an older request resolving after a newer one would overwrite
+  //   the UI with a stale suggestion.
+  const [userTouchedAbilities, setUserTouchedAbilities] = useState(!!initialEditingModel)
+  const [abilitySuggestion, setAbilitySuggestion] = useState<
+    Pick<AbilitySuggestion, "source" | "matched_pattern"> | null
+  >(null)
+  const suggestionRequestCounter = useRef(0)
+  // Mirror userTouchedAbilities in a ref so async callbacks see the latest
+  // value rather than the closure-captured render-time value. Required so
+  // an in-flight applyAbilitySuggestion can't overwrite an ability edit the
+  // user makes while the request is still in flight.
+  const userTouchedAbilitiesRef = useRef<boolean>(!!initialEditingModel)
+  const setUserTouched = (value: boolean) => {
+    userTouchedAbilitiesRef.current = value
+    setUserTouchedAbilities(value)
+  }
+
   const getDefaultAbilitiesForCategory = (category: string): string[] => {
     if (category === 'llm') return ['chat']
     if (category === 'embedding') return ['embedding']
@@ -129,6 +158,69 @@ export function ModelManagementDialog({
     ]
   }
 
+  /**
+   * Reset all "fresh wizard run" ability auto-fill state. Used wherever
+   * the user starts a new model_name selection from scratch (entering the
+   * wizard, switching category, switching provider).
+   *
+   * Bumps suggestionRequestCounter so that any applyAbilitySuggestion()
+   * already in flight from the previous selection has its response
+   * discarded — otherwise a stale fetch could resolve after the reset
+   * and auto-fill the form with the previous model's abilities.
+   */
+  const resetAbilitySuggestionState = () => {
+    suggestionRequestCounter.current++
+    setUserTouched(false)
+    setAbilitySuggestion(null)
+  }
+
+  /**
+   * Look up abilities for the chosen (provider, model_name) against the
+   * backend catalog and, if the user hasn't manually touched the ability
+   * buttons yet, apply the suggestion. Always updates `abilitySuggestion`
+   * so the hint stays in sync, even when we don't auto-fill.
+   *
+   * Only applies for category='llm' — other categories have a fixed,
+   * single-ability shape that doesn't benefit from a catalog lookup.
+   *
+   * Race-condition safety: every call bumps a monotonic counter, and the
+   * response is only applied if the counter is still the latest when we
+   * resolve. This prevents an older keystroke's response from overwriting
+   * a newer one when network round-trips finish out of order.
+   */
+  const applyAbilitySuggestion = async (provider: string, modelName: string, category: string) => {
+    const requestId = ++suggestionRequestCounter.current
+    if (category !== 'llm' || !provider || !modelName) {
+      setAbilitySuggestion(null)
+      return
+    }
+    const result = await getAbilitySuggestion(provider, modelName)
+    // A newer request has been fired since — drop this stale response.
+    if (requestId !== suggestionRequestCounter.current) {
+      return
+    }
+    setAbilitySuggestion({ source: result.source, matched_pattern: result.matched_pattern })
+    // Re-check the ref instead of the closure value: the user may have
+    // edited abilities while this network request was in flight.
+    if (result.source !== 'none' && !userTouchedAbilitiesRef.current) {
+      setFormData(prev => ({ ...prev, abilities: result.abilities }))
+    }
+  }
+
+  /**
+   * Centralised handler for model_name changes. Used by both wizard and
+   * form-mode Inputs/Selects to avoid duplicating the setFormData +
+   * applyAbilitySuggestion pair. We read provider/category from the
+   * functional setState `prev` to avoid stale closure values when the
+   * user changes them in quick succession.
+   */
+  const handleModelNameChange = (newModelName: string) => {
+    setFormData(prev => {
+      void applyAbilitySuggestion(prev.model_provider, newModelName, prev.category)
+      return { ...prev, model_name: newModelName }
+    })
+  }
+
   const resetConnectionState = () => {
     setTestConnectionStatus('idle')
     setTestConnectionError(null)
@@ -251,6 +343,13 @@ export function ModelManagementDialog({
     setDefaultTargetModel(null)
     setEditingModel(model)
     const currentDefaults = getModelDefaultTypes(model.id)
+    // Editing an existing model: the user has already explicitly chosen
+    // these abilities (or accepted the catalog defaults at creation time),
+    // so we must not silently overwrite them when they tweak model_name.
+    // The hint UI still updates so they can see what the catalog would
+    // suggest for the new name.
+    setUserTouched(true)
+    setAbilitySuggestion(null)
     setFormData({
       model_id: model.model_id,
       category: model.category,
@@ -265,6 +364,8 @@ export function ModelManagementDialog({
       share_with_users: model.is_shared
     })
     setViewMode('form')
+    // Show the hint for the model they're editing, without changing abilities.
+    void applyAbilitySuggestion(model.model_provider, model.model_name, model.category)
   }
 
   const handleManageDefaults = (model: Model) => {
@@ -279,6 +380,8 @@ export function ModelManagementDialog({
     const providerConfig = providers.find(p => p.id === managingProviderId)
     resetConnectionState()
     setDefaultTargetModel(null)
+    // Fresh wizard run -> drop any prior auto-fill state.
+    resetAbilitySuggestionState()
     setFormData({
       model_id: "",
       category: activeTab,
@@ -598,6 +701,7 @@ export function ModelManagementDialog({
                           value={formData.category}
                           onValueChange={(value) => {
                             resetConnectionState()
+                            resetAbilitySuggestionState()
                             setFormData(prev => ({
                               ...prev,
                               category: value,
@@ -640,6 +744,9 @@ export function ModelManagementDialog({
                                 className={`flex items-center gap-4 p-4 cursor-pointer hover:bg-muted/50 ${formData.model_provider === provider.id ? 'bg-muted' : ''}`}
                                 onClick={() => {
                                   resetConnectionState()
+                                  // Provider change implies the prior model_name is gone, so any
+                                  // earlier suggestion no longer applies. Allow auto-fill again.
+                                  resetAbilitySuggestionState()
                                   setFormData(prev => ({
                                     ...prev,
                                     model_provider: provider.id,
@@ -763,7 +870,7 @@ export function ModelManagementDialog({
                         <Select
                           value={formData.model_name}
                           onValueChange={(val) => {
-                            setFormData({ ...formData, model_name: val })
+                            handleModelNameChange(val)
                             setTestConnectionStatus('idle')
                             setTestConnectionError(null)
                           }}
@@ -777,7 +884,7 @@ export function ModelManagementDialog({
                               ? prev
                               : [...prev, { id: val, object: "model", created: Date.now(), owned_by: formData.model_provider }]
                             )
-                            setFormData({ ...formData, model_name: val })
+                            handleModelNameChange(val)
                             setTestConnectionStatus('idle')
                             setTestConnectionError(null)
                           }}
@@ -814,6 +921,22 @@ export function ModelManagementDialog({
 
                       <div className="space-y-2">
                         <Label className="text-base font-medium">{t('models.form.abilities')}</Label>
+                        {formData.category === 'llm' && formData.model_name && abilitySuggestion && (
+                          abilitySuggestion.source !== 'none' ? (
+                            <p className="text-xs text-muted-foreground">
+                              {t('models.form.abilitiesAutoFilled', {
+                                pattern: abilitySuggestion.matched_pattern || '',
+                                defaultValue: 'Pre-selected based on a known model ({{pattern}}). Adjust if needed.'
+                              })}
+                            </p>
+                          ) : (
+                            <p className="text-xs text-muted-foreground">
+                              {t('models.form.abilitiesUnknownModel', {
+                                defaultValue: "We don't have ability info for this model — please pick what it supports."
+                              })}
+                            </p>
+                          )
+                        )}
                         <div className="flex gap-2 flex-wrap">
                           {getAbilityOptionsForCategory(formData.category).map(({ value, label }) => {
                             const cap = value
@@ -837,6 +960,8 @@ export function ModelManagementDialog({
                                 onClick={() => {
                                   const abilities = formData.abilities || []
                                   resetConnectionState()
+                                  // From this point on, never overwrite user choices from the catalog.
+                                  setUserTouched(true)
                                   if (isSelected) setFormData({ ...formData, abilities: abilities.filter(a => a !== cap) })
                                   else setFormData({ ...formData, abilities: [...abilities, cap] })
                                 }}
@@ -1155,7 +1280,14 @@ export function ModelManagementDialog({
                   <Select
                     value={formData.model_provider}
                     onValueChange={(value) => {
+                      // Upstream already clears model_name + resets abilities
+                      // to the new provider's defaults here, which by itself
+                      // prevents the stale-suggestion bug rogercloud/qinxuye
+                      // flagged. We still reset the suggestion hint state
+                      // explicitly so the "Auto-filled from <pattern>" badge
+                      // doesn't linger after the provider change.
                       resetConnectionState()
+                      resetAbilitySuggestionState()
                       setFormData(prev => ({
                         ...prev,
                         model_provider: value,
@@ -1234,13 +1366,19 @@ export function ModelManagementDialog({
                   <Input
                     id="model_name"
                     value={formData.model_name}
-                    onChange={(e) => setFormData({ ...formData, model_name: e.target.value })}
+                    onChange={(e) => {
+                      // Refresh the hint; userTouchedAbilities=true keeps
+                      // the actual ability buttons intact (set in handleEdit).
+                      handleModelNameChange(e.target.value)
+                    }}
                     placeholder={t('models.form.enterModelName')}
                   />
                 ) : (
                   <Select
                     value={formData.model_name}
-                    onValueChange={(value) => setFormData({ ...formData, model_name: value })}
+                    onValueChange={(value) => {
+                      handleModelNameChange(value)
+                    }}
                     options={fetchedModels.map(m => ({ value: m.id, label: m.id }))}
                     placeholder={t('models.form.selectModel')}
                     allowCustom={formData.model_provider !== 'deepseek'}
@@ -1250,7 +1388,7 @@ export function ModelManagementDialog({
                       if (!fetchedModels.find(m => m.id === value)) {
                         setFetchedModels([...fetchedModels, { id: value, object: "model", created: Date.now(), owned_by: formData.model_provider }])
                       }
-                      setFormData({ ...formData, model_name: value })
+                      handleModelNameChange(value)
                     }}
                   />
                 )}
@@ -1260,7 +1398,13 @@ export function ModelManagementDialog({
                 <Label className="mb-2 block">{t('models.form.abilities')}</Label>
                 <MultiSelect
                   values={formData.abilities || []}
-                  onValuesChange={(values) => setFormData({ ...formData, abilities: values })}
+                  onValuesChange={(values) => {
+                    // Mark abilities as user-touched so a later model_name
+                    // change in form mode doesn't auto-fill over the user's
+                    // explicit selection. Matches the wizard ability button.
+                    setUserTouched(true)
+                    setFormData({ ...formData, abilities: values })
+                  }}
                   options={
                     formData.category === 'llm' ? abilityOptions :
                       formData.category === 'embedding' ? embeddingAbilityOptions :
diff --git a/frontend/src/i18n/locales/en.ts b/frontend/src/i18n/locales/en.ts
index 7247ee343..e226702b5 100644
--- a/frontend/src/i18n/locales/en.ts
+++ b/frontend/src/i18n/locales/en.ts
@@ -1427,6 +1427,8 @@ Build when you need.`
       defaultPlaceholder: "Select default type...",
       shareWithUsers: "Share this model with all users",
       abilitiesPlaceholder: "Select abilities...",
+      abilitiesAutoFilled: "Pre-selected based on a known model ({{pattern}}). Adjust if needed.",
+      abilitiesUnknownModel: "We don't have ability info for this model — please pick what it supports.",
       update: "Update Model",
       create: "Create Model",
       enterModelName: "Enter model name manually...",
diff --git a/frontend/src/i18n/locales/zh.ts b/frontend/src/i18n/locales/zh.ts
index 06b024cb8..1fc6790ef 100644
--- a/frontend/src/i18n/locales/zh.ts
+++ b/frontend/src/i18n/locales/zh.ts
@@ -1427,6 +1427,8 @@ Build when you need.`
       defaultPlaceholder: "选择默认类型...",
       shareWithUsers: "与所有用户共享此模型",
       abilitiesPlaceholder: "选择能力...",
+      abilitiesAutoFilled: "已根据已知模型自动选择（{{pattern}}），如有偏差请手动修改。",
+      abilitiesUnknownModel: "暂无该模型的能力信息，请按实际支持手动选择。",
       update: "更新模型",
       create: "创建模型",
       enterModelName: "手动输入模型名称...",
diff --git a/frontend/src/lib/models.ts b/frontend/src/lib/models.ts
index 1b76ac7ae..bc45cdd5a 100644
--- a/frontend/src/lib/models.ts
+++ b/frontend/src/lib/models.ts
@@ -235,3 +235,68 @@ export async function getProviderModels(
   }
   return Array.isArray(data) ? data : [];
 }
+
+/**
+ * Result of looking up abilities for a (provider, model_name) pair against
+ * the curated ability catalog on the backend.
+ *
+ * `source` semantics:
+ *   - "exact":              matched a provider-specific rule
+ *   - "wildcard_provider":  matched a cross-provider rule (e.g. DeepSeek
+ *                           served via an OpenAI-compatible endpoint)
+ *   - "none":               no rule matched; abilities array will be empty
+ */
+export interface AbilitySuggestion {
+  abilities: string[]
+  matched_pattern: string | null
+  source: "exact" | "wildcard_provider" | "none"
+}
+
+/**
+ * Ask the backend which abilities to pre-select for a given model.
+ * Returns `{ abilities: [], source: "none" }` for unknown models so callers
+ * can simply test `source !== "none"` to decide whether to auto-fill.
+ *
+ * Network failures are swallowed and surfaced as `source: "none"` — the
+ * Add-Model wizard should keep working even if the catalog endpoint is down.
+ */
+export async function getAbilitySuggestion(
+  provider: string,
+  modelName: string,
+): Promise<AbilitySuggestion> {
+  if (!provider || !modelName) {
+    return { abilities: [], matched_pattern: null, source: "none" }
+  }
+  const apiUrl = getApiUrl()
+  const qs = new URLSearchParams({ provider, model_name: modelName }).toString()
+  try {
+    const response = await apiRequest(`${apiUrl}/api/models/abilities/suggest?${qs}`, {
+      method: "GET",
+    })
+    if (!response.ok) {
+      return { abilities: [], matched_pattern: null, source: "none" }
+    }
+    const data = (await response.json()) as Partial<AbilitySuggestion>
+    // Whitelist-validate `source` instead of casting: an unexpected value
+    // from the backend would otherwise leak through the cast into React
+    // state and break downstream union-narrowing.
+    const validSources: AbilitySuggestion["source"][] = [
+      "exact",
+      "wildcard_provider",
+      "none",
+    ]
+    const source: AbilitySuggestion["source"] = validSources.includes(
+      data.source as AbilitySuggestion["source"],
+    )
+      ? (data.source as AbilitySuggestion["source"])
+      : "none"
+    return {
+      abilities: Array.isArray(data.abilities) ? data.abilities : [],
+      matched_pattern: data.matched_pattern ?? null,
+      source,
+    }
+  } catch (error) {
+    console.error("Failed to get ability suggestion:", error)
+    return { abilities: [], matched_pattern: null, source: "none" }
+  }
+}
diff --git a/src/xagent/core/model/abilities_catalog.yaml b/src/xagent/core/model/abilities_catalog.yaml
new file mode 100644
index 000000000..1699ddea4
--- /dev/null
+++ b/src/xagent/core/model/abilities_catalog.yaml
@@ -0,0 +1,373 @@
+# Curated catalog of LLM abilities for common models.
+#
+# Format
+# ------
+# rules:
+#   - pattern: "<provider>/<model_name_glob>"
+#     abilities: [chat, vision, tool_calling, thinking_mode]
+#
+# - <provider> is the provider id used in xagent (openai, claude, gemini,
+#   zhipu, dashscope, alibaba-coding-plan, alibaba-coding-plan-cn,
+#   zai-coding-plan, zhipuai-coding-plan, minimax-coding-plan,
+#   minimax-cn-coding-plan, kimi-for-coding, xinference, ...).
+#   Use "*" to match any provider, useful for OpenAI-compatible endpoints
+#   that expose third-party models (e.g. DeepSeek through any base_url).
+# - <model_name_glob> uses fnmatch-style wildcards (* and ?). Matching is
+#   case-insensitive.
+# - Rules are evaluated in three tiers; within each tier the YAML order is
+#   preserved, so put the most specific patterns first:
+#     Tier 1: exact provider + specific model (model != "*")
+#     Tier 2: wildcard provider + specific model
+#     Tier 3: exact provider + "*" (provider fallback)
+# - Abilities are restricted to the LLM category and must be drawn from
+#   {chat, vision, tool_calling, thinking_mode}.
+#
+# Maintenance: when a new model ships, add a rule and bump the catalog
+# version comment below. The backend reloads on process restart; tests use
+# `model_catalog.reload_catalog()` to pick up edits.
+
+# Catalog version: 2026-05-07 (rev2 — added GPT-5 / Claude 4.5 / Gemini 3 / DeepSeek V4 series)
+
+rules:
+  # ============================================================
+  # OpenAI
+  # ============================================================
+  # GPT-5 family (2025 H2 / 2026)
+  - pattern: "openai/gpt-5.5*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "openai/gpt-5-nano*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "openai/gpt-5-mini*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "openai/gpt-5*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  # Reasoning / "o" series
+  - pattern: "openai/o3-mini*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "openai/o3*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "openai/o4-mini*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "openai/o1-mini*"
+    abilities: [chat, thinking_mode]
+  - pattern: "openai/o1*"
+    abilities: [chat, vision, thinking_mode]
+  # GPT-4 family
+  - pattern: "openai/gpt-4o-mini*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "openai/gpt-4o*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "openai/gpt-4-turbo*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "openai/gpt-4-vision*"
+    abilities: [chat, vision]
+  - pattern: "openai/gpt-4*"
+    abilities: [chat, tool_calling]
+  - pattern: "openai/gpt-3.5*"
+    abilities: [chat, tool_calling]
+  # Provider fallback
+  - pattern: "openai/*"
+    abilities: [chat, tool_calling]
+
+  # ============================================================
+  # Anthropic Claude
+  # NOTE: claude-5 family is not yet announced as of 2026-05-07. Latest
+  # released is Claude Opus 4.7 (2026-04-16), which is matched by the
+  # claude-opus-4* rule below. Add claude-5* rules only after public
+  # announcement.
+  # ============================================================
+  # Claude 4.5 (refresh, all support thinking)
+  - pattern: "claude/claude-opus-4.5*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "claude/claude-sonnet-4.5*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "claude/claude-haiku-4.5*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  # Claude 4 (extended thinking on Opus / Sonnet)
+  - pattern: "claude/claude-opus-4*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "claude/claude-sonnet-4*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "claude/claude-haiku-4*"
+    abilities: [chat, vision, tool_calling]
+  # Claude 3.7 (extended thinking)
+  - pattern: "claude/claude-3-7*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  # Claude 3.5
+  - pattern: "claude/claude-3-5-sonnet*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "claude/claude-3-5-haiku*"
+    abilities: [chat, tool_calling]
+  # Claude 3
+  - pattern: "claude/claude-3-opus*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "claude/claude-3-sonnet*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "claude/claude-3-haiku*"
+    abilities: [chat, vision, tool_calling]
+  # Provider fallback
+  - pattern: "claude/*"
+    abilities: [chat, tool_calling]
+
+  # ============================================================
+  # Google Gemini
+  # ============================================================
+  # Gemini 3 (2026)
+  - pattern: "gemini/gemini-3-pro*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "gemini/gemini-3-flash*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "gemini/gemini-3*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "gemini/gemini-2.5-pro*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "gemini/gemini-2.5-flash*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "gemini/gemini-2.0-flash-thinking*"
+    abilities: [chat, vision, thinking_mode]
+  - pattern: "gemini/gemini-2.0-flash*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "gemini/gemini-2.0-pro*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "gemini/gemini-1.5-pro*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "gemini/gemini-1.5-flash*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "gemini/*"
+    abilities: [chat, vision, tool_calling]
+
+  # ============================================================
+  # Zhipu AI (GLM, direct API)
+  # NOTE: glm-4.5v is the multimodal variant of 4.5 (image/video input +
+  # thinking mode); it must be matched before glm-4.5* otherwise it loses
+  # vision.
+  # ============================================================
+  - pattern: "zhipu/glm-4.5v*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "zhipu/glm-4.5*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "zhipu/glm-4v*"
+    abilities: [chat, vision]
+  - pattern: "zhipu/glm-4-plus*"
+    abilities: [chat, tool_calling]
+  - pattern: "zhipu/glm-4*"
+    abilities: [chat, tool_calling]
+  - pattern: "zhipu/glm-zero*"
+    abilities: [chat, thinking_mode]
+  - pattern: "zhipu/*"
+    abilities: [chat]
+
+  # ============================================================
+  # DashScope (Qwen via Alibaba public endpoint)
+  # ============================================================
+  - pattern: "dashscope/qwen*-vl*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "dashscope/qwq*"
+    abilities: [chat, thinking_mode]
+  - pattern: "dashscope/qwen3*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "dashscope/qwen2.5-vl*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "dashscope/qwen2.5*"
+    abilities: [chat, tool_calling]
+  - pattern: "dashscope/*"
+    abilities: [chat, tool_calling]
+
+  # ============================================================
+  # Alibaba Bailian Coding Plan (international + China)
+  # Curated models per providers.py: glm-4.7, glm-5, qwen3-coder-next/plus,
+  # qwen3-max-2026-01-23, qwen3.5-plus
+  # NOTE: -vl rule must come before generic qwen3.5*/qwen3-max* etc.,
+  # otherwise vision variants get matched as text-only.
+  # ============================================================
+  - pattern: "alibaba-coding-plan/qwen*-vl*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "alibaba-coding-plan/glm-4v*"
+    abilities: [chat, vision]
+  - pattern: "alibaba-coding-plan/glm-5*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "alibaba-coding-plan/glm-4.7*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "alibaba-coding-plan/qwen3-coder*"
+    abilities: [chat, tool_calling]
+  - pattern: "alibaba-coding-plan/qwen3-max*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "alibaba-coding-plan/qwen3.5*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "alibaba-coding-plan/*"
+    abilities: [chat, tool_calling]
+
+  - pattern: "alibaba-coding-plan-cn/qwen*-vl*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "alibaba-coding-plan-cn/glm-4v*"
+    abilities: [chat, vision]
+  - pattern: "alibaba-coding-plan-cn/glm-5*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "alibaba-coding-plan-cn/glm-4.7*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "alibaba-coding-plan-cn/qwen3-coder*"
+    abilities: [chat, tool_calling]
+  - pattern: "alibaba-coding-plan-cn/qwen3-max*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "alibaba-coding-plan-cn/qwen3.5*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "alibaba-coding-plan-cn/*"
+    abilities: [chat, tool_calling]
+
+  # ============================================================
+  # Z.AI Coding Plan / Zhipu AI Coding Plan (GLM via dedicated endpoints)
+  # NOTE: glm-4v* rule must come before generic glm-4*, otherwise the
+  # vision variant gets matched as text-only.
+  # ============================================================
+  - pattern: "zai-coding-plan/glm-4.5v*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "zai-coding-plan/glm-4v*"
+    abilities: [chat, vision]
+  - pattern: "zai-coding-plan/glm-4.5*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "zai-coding-plan/glm-4*"
+    abilities: [chat, tool_calling]
+  - pattern: "zai-coding-plan/glm-coder*"
+    abilities: [chat, tool_calling]
+  - pattern: "zai-coding-plan/*"
+    abilities: [chat, tool_calling]
+
+  - pattern: "zhipuai-coding-plan/glm-4.5v*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "zhipuai-coding-plan/glm-4v*"
+    abilities: [chat, vision]
+  - pattern: "zhipuai-coding-plan/glm-4.5*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "zhipuai-coding-plan/glm-4*"
+    abilities: [chat, tool_calling]
+  - pattern: "zhipuai-coding-plan/glm-coder*"
+    abilities: [chat, tool_calling]
+  - pattern: "zhipuai-coding-plan/*"
+    abilities: [chat, tool_calling]
+
+  # ============================================================
+  # MiniMax Coding Plan (international + China)
+  # Curated: MiniMax-M2, MiniMax-M2.1, MiniMax-M2.5
+  # ============================================================
+  - pattern: "minimax-coding-plan/minimax-m2.5*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "minimax-coding-plan/minimax-m2.1*"
+    abilities: [chat, tool_calling]
+  - pattern: "minimax-coding-plan/minimax-m2*"
+    abilities: [chat, tool_calling]
+  - pattern: "minimax-coding-plan/*"
+    abilities: [chat, tool_calling]
+
+  - pattern: "minimax-cn-coding-plan/minimax-m2.5*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "minimax-cn-coding-plan/minimax-m2.1*"
+    abilities: [chat, tool_calling]
+  - pattern: "minimax-cn-coding-plan/minimax-m2*"
+    abilities: [chat, tool_calling]
+  - pattern: "minimax-cn-coding-plan/*"
+    abilities: [chat, tool_calling]
+
+  # ============================================================
+  # Kimi for Coding (Moonshot)
+  # NOTE: K2.5 / K2.6 are native multimodal models with thinking mode;
+  # they must be matched before the generic kimi-k2* rule, otherwise
+  # they lose vision and thinking_mode.
+  # ============================================================
+  - pattern: "kimi-for-coding/kimi-k2.6*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "kimi-for-coding/kimi-k2.5*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "kimi-for-coding/kimi-k2*"
+    abilities: [chat, tool_calling]
+  - pattern: "kimi-for-coding/kimi-latest*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "kimi-for-coding/moonshot-v1*-vision*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "kimi-for-coding/moonshot-v1*"
+    abilities: [chat, tool_calling]
+  - pattern: "kimi-for-coding/*"
+    abilities: [chat, tool_calling]
+
+  # ============================================================
+  # Xinference (self-hosted; model name is user-defined, fall through to
+  # cross-provider rules below or to provider fallback)
+  # ============================================================
+  - pattern: "xinference/*"
+    abilities: [chat]
+
+  # ============================================================
+  # Cross-provider fallbacks (model name only)
+  # Catches models exposed through OpenAI-compatible endpoints under any
+  # provider id (DeepSeek via openai, Qwen via xinference, etc.)
+  # ============================================================
+  # DeepSeek
+  - pattern: "*/deepseek-r2*"
+    abilities: [chat, thinking_mode]
+  - pattern: "*/deepseek-reasoner*"
+    abilities: [chat, thinking_mode]
+  - pattern: "*/deepseek-r1*"
+    abilities: [chat, thinking_mode]
+  # NOTE: DeepSeek V4 (released 2026-04-24) is text-only. Multimodal is on
+  # the roadmap but not yet shipped — do NOT add vision here.
+  - pattern: "*/deepseek-v4*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "*/deepseek-v3.5*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "*/deepseek-chat*"
+    abilities: [chat, tool_calling]
+  - pattern: "*/deepseek-coder*"
+    abilities: [chat, tool_calling]
+  - pattern: "*/deepseek-v3*"
+    abilities: [chat, tool_calling]
+  - pattern: "*/deepseek*"
+    abilities: [chat]
+  # Qwen via openai-compat
+  - pattern: "*/qwen*-vl*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "*/qwq*"
+    abilities: [chat, thinking_mode]
+  - pattern: "*/qwen3*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "*/qwen2.5*"
+    abilities: [chat, tool_calling]
+  - pattern: "*/qwen*"
+    abilities: [chat, tool_calling]
+  # GLM via openai-compat (4.5v is multimodal — must come before 4.5*)
+  - pattern: "*/glm-4.5v*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "*/glm-4.5*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "*/glm-4v*"
+    abilities: [chat, vision]
+  - pattern: "*/glm-4*"
+    abilities: [chat, tool_calling]
+  # MiniMax via openai-compat
+  - pattern: "*/minimax-m2.5*"
+    abilities: [chat, tool_calling, thinking_mode]
+  - pattern: "*/minimax-m2*"
+    abilities: [chat, tool_calling]
+  # Kimi / Moonshot via openai-compat
+  # K2.5 / K2.6 are native multimodal with thinking; must match before */kimi-k2*
+  - pattern: "*/kimi-k2.6*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "*/kimi-k2.5*"
+    abilities: [chat, vision, tool_calling, thinking_mode]
+  - pattern: "*/kimi-k2*"
+    abilities: [chat, tool_calling]
+  - pattern: "*/moonshot-v1*-vision*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "*/moonshot-v1*"
+    abilities: [chat, tool_calling]
+  # Llama / open-source common families on Xinference
+  - pattern: "*/llama-4*-vision*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "*/llama-4*"
+    abilities: [chat, vision, tool_calling]
+  - pattern: "*/llama-3*-vision*"
+    abilities: [chat, vision]
+  - pattern: "*/llama-3*"
+    abilities: [chat, tool_calling]
+  - pattern: "*/mistral-large*"
+    abilities: [chat, tool_calling]
+  - pattern: "*/mistral*"
+    abilities: [chat, tool_calling]
diff --git a/src/xagent/web/api/model.py b/src/xagent/web/api/model.py
index 2077bd6e6..810487243 100644
--- a/src/xagent/web/api/model.py
+++ b/src/xagent/web/api/model.py
@@ -27,6 +27,7 @@
 from ..models.model import Model as DBModel
 from ..models.user import User, UserDefaultModel, UserModel
 from ..schemas.model import (
+    AbilitySuggestionResponse,
     ModelConnectionTestRequest,
     ModelCreate,
     ModelTestRequest,
@@ -37,6 +38,7 @@
     UserDefaultModelResponse,
 )
 from ..services.llm_utils import CoreStorage
+from ..services.model_catalog import lookup as lookup_ability_suggestion
 from ..services.model_store import ModelSharingConflictError, ModelStore
 from ..user_isolated_memory import UserContext
 
@@ -831,6 +833,31 @@ async def list_model_abilities(
     }
 
 
+@model_router.get(
+    "/abilities/suggest",
+    response_model=AbilitySuggestionResponse,
+)
+async def suggest_model_abilities(
+    provider: str = Query(..., description="Model provider id, e.g. 'openai'"),
+    model_name: str = Query(..., description="Model name, e.g. 'gpt-4o'"),
+    user: User = Depends(get_current_user),
+) -> AbilitySuggestionResponse:
+    """Suggest abilities for a (provider, model_name) pair from the curated
+    static catalog. Read-only; returns ``source='none'`` when no rule matches
+    so the frontend can fall back to current defaults without erroring.
+
+    Auth-gated only to keep the catalog out of unauthenticated probes — the
+    answers themselves are not user-specific.
+    """
+
+    suggestion = lookup_ability_suggestion(provider, model_name)
+    return AbilitySuggestionResponse(
+        abilities=suggestion.abilities,
+        matched_pattern=suggestion.matched_pattern,
+        source=suggestion.source,
+    )
+
+
 @model_router.get("/summary")
 async def get_models_summary(
     db: Session = Depends(get_db),
diff --git a/src/xagent/web/schemas/model.py b/src/xagent/web/schemas/model.py
index 34db7912d..5f803ffdb 100644
--- a/src/xagent/web/schemas/model.py
+++ b/src/xagent/web/schemas/model.py
@@ -1,5 +1,5 @@
 from datetime import datetime
-from typing import Any, List, Optional, Set
+from typing import Any, List, Literal, Optional, Set
 
 from pydantic import BaseModel, field_validator
 
@@ -372,3 +372,21 @@ class SupportedProvidersResponse(BaseModel):
     """Response schema for supported providers."""
 
     providers: List[ProviderInfo]
+
+
+class AbilitySuggestionResponse(BaseModel):
+    """Suggested abilities for a (provider, model_name) pair, derived from the
+    static ability catalog at ``src/xagent/core/model/abilities_catalog.yaml``.
+
+    ``source`` indicates how the suggestion was derived so the frontend can
+    decide whether to auto-fill silently or surface a hint:
+      - ``exact``: matched a provider-specific rule.
+      - ``wildcard_provider``: matched a cross-provider rule (e.g. DeepSeek
+        served via an OpenAI-compatible endpoint).
+      - ``none``: no rule matched. ``abilities`` will be empty and the
+        frontend should keep current values.
+    """
+
+    abilities: List[str]
+    matched_pattern: Optional[str] = None
+    source: Literal["exact", "wildcard_provider", "none"]
diff --git a/src/xagent/web/services/model_catalog.py b/src/xagent/web/services/model_catalog.py
new file mode 100644
index 000000000..64a7ebcc3
--- /dev/null
+++ b/src/xagent/web/services/model_catalog.py
@@ -0,0 +1,250 @@
+"""Static ability catalog for known LLM models.
+
+Loads ``src/xagent/core/model/abilities_catalog.yaml`` once at first use and
+provides a single ``lookup(provider, model_name)`` entry point that returns the
+recommended ability list for a given (provider, model_name) pair.
+
+Resolution order
+----------------
+1. Exact provider AND specific model pattern (``model_pattern != "*"``)
+2. Wildcard provider (``*``) AND specific model pattern
+3. Exact provider AND ``model_pattern == "*"`` (provider fallback)
+4. Otherwise: ``source="none"`` and an empty ability list
+
+Putting tier 2 above tier 3 is important: it lets ``*/deepseek-chat*`` win
+against ``openai/*`` when DeepSeek is added through an OpenAI-compatible
+endpoint. A pure provider fallback should only fire when no model-name rule
+matches at all.
+
+The catalog is loaded lazily and cached. Call :func:`reload_catalog` in tests
+to force a re-read after editing the YAML.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import logging
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+# Path is resolved at import time so it is independent of CWD.
+_CATALOG_PATH = (
+    Path(__file__).resolve().parent.parent.parent
+    / "core"
+    / "model"
+    / "abilities_catalog.yaml"
+)
+
+# Allowed abilities for category=llm. Mirrors the frontend list and the
+# server-side validator in ``schemas/model.py``.
+_ALLOWED_LLM_ABILITIES = {"chat", "vision", "tool_calling", "thinking_mode"}
+
+
+@dataclass(frozen=True)
+class CatalogRule:
+    """A single rule loaded from the catalog YAML."""
+
+    provider_pattern: str  # e.g. "openai" or "*"
+    model_pattern: str  # e.g. "gpt-4o*"
+    abilities: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class AbilitySuggestion:
+    """Result of a catalog lookup."""
+
+    abilities: List[str]
+    matched_pattern: Optional[str]
+    source: str  # "exact" | "wildcard_provider" | "none"
+
+
+@dataclass(frozen=True)
+class _RulesIndex:
+    """Rules pre-partitioned into the three matching tiers used by
+    :func:`lookup`, so each call iterates only the relevant slice instead
+    of scanning the entire catalog three times."""
+
+    tier1_exact_specific: tuple[CatalogRule, ...]
+    tier2_wildcard_specific: tuple[CatalogRule, ...]
+    tier3_provider_fallback: tuple[CatalogRule, ...]
+
+    @property
+    def all_rules(self) -> List[CatalogRule]:
+        return [
+            *self.tier1_exact_specific,
+            *self.tier2_wildcard_specific,
+            *self.tier3_provider_fallback,
+        ]
+
+
+_lock = threading.Lock()
+_index_cache: Optional[_RulesIndex] = None
+
+
+def _parse_pattern(pattern: str) -> tuple[str, str]:
+    """Split a ``provider/model`` pattern. Defaults to ``*/<pattern>`` if no
+    slash is present."""
+    if "/" not in pattern:
+        return "*", pattern
+    provider, model = pattern.split("/", 1)
+    return provider.strip() or "*", model.strip() or "*"
+
+
+def _load_rules() -> List[CatalogRule]:
+    """Load and parse the YAML catalog. Returns an empty list (and logs) if
+    the file is missing or malformed, so the API stays online."""
+    if not _CATALOG_PATH.exists():
+        logger.warning(
+            "Ability catalog not found at %s; suggestions disabled.",
+            _CATALOG_PATH,
+        )
+        return []
+    try:
+        with _CATALOG_PATH.open("r", encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+    except (yaml.YAMLError, OSError) as exc:
+        logger.error("Failed to read ability catalog %s: %s", _CATALOG_PATH, exc)
+        return []
+
+    raw_rules = data.get("rules") or []
+    if not isinstance(raw_rules, list):
+        logger.error("Ability catalog 'rules' must be a list, got %s", type(raw_rules))
+        return []
+
+    parsed: List[CatalogRule] = []
+    for idx, item in enumerate(raw_rules):
+        if not isinstance(item, dict):
+            logger.warning("Skipping non-dict catalog rule at index %d", idx)
+            continue
+        pattern = str(item.get("pattern", "")).strip()
+        abilities_raw = item.get("abilities") or []
+        if not pattern or not isinstance(abilities_raw, list):
+            logger.warning("Skipping malformed catalog rule at index %d", idx)
+            continue
+
+        # Filter to allowed abilities; drop unknowns with a warning rather than
+        # silently letting bad data leak to the UI.
+        cleaned: List[str] = []
+        for a in abilities_raw:
+            if not isinstance(a, str):
+                continue
+            a_norm = a.strip().lower()
+            if a_norm in _ALLOWED_LLM_ABILITIES:
+                cleaned.append(a_norm)
+            else:
+                logger.warning(
+                    "Catalog rule '%s' references unknown ability '%s'; ignoring.",
+                    pattern,
+                    a,
+                )
+        if not cleaned:
+            continue
+
+        provider_pat, model_pat = _parse_pattern(pattern)
+        parsed.append(
+            CatalogRule(
+                provider_pattern=provider_pat.lower(),
+                model_pattern=model_pat.lower(),
+                abilities=tuple(cleaned),
+            )
+        )
+
+    logger.info("Loaded %d ability catalog rules from %s", len(parsed), _CATALOG_PATH)
+    return parsed
+
+
+def _partition_rules(rules: List[CatalogRule]) -> _RulesIndex:
+    """Bucket the flat rule list into the three resolution tiers so that
+    :func:`lookup` doesn't have to scan rules belonging to other tiers."""
+    t1: List[CatalogRule] = []
+    t2: List[CatalogRule] = []
+    t3: List[CatalogRule] = []
+    for rule in rules:
+        provider_wild = rule.provider_pattern == "*"
+        model_wild = rule.model_pattern == "*"
+        if not provider_wild and not model_wild:
+            t1.append(rule)
+        elif provider_wild and not model_wild:
+            t2.append(rule)
+        elif not provider_wild and model_wild:
+            t3.append(rule)
+        # "*/*" is meaningless — silently drop.
+    return _RulesIndex(
+        tier1_exact_specific=tuple(t1),
+        tier2_wildcard_specific=tuple(t2),
+        tier3_provider_fallback=tuple(t3),
+    )
+
+
+def _get_index() -> _RulesIndex:
+    global _index_cache
+    if _index_cache is None:
+        with _lock:
+            if _index_cache is None:
+                _index_cache = _partition_rules(_load_rules())
+    return _index_cache
+
+
+def _get_rules() -> List[CatalogRule]:
+    """Backwards-compatible flat view of all rules across tiers."""
+    return _get_index().all_rules
+
+
+def reload_catalog() -> int:
+    """Force a re-read of the catalog YAML. Returns the number of rules
+    loaded. Intended for tests / admin reload endpoints."""
+    global _index_cache
+    with _lock:
+        _index_cache = _partition_rules(_load_rules())
+    return len(_index_cache.all_rules)
+
+
+def lookup(provider: str, model_name: str) -> AbilitySuggestion:
+    """Return the recommended abilities for a given (provider, model) pair.
+
+    Both inputs are matched case-insensitively. Whitespace is stripped.
+    """
+    provider_norm = (provider or "").strip().lower()
+    model_norm = (model_name or "").strip().lower()
+    if not model_norm:
+        return AbilitySuggestion(abilities=[], matched_pattern=None, source="none")
+
+    index = _get_index()
+
+    def _matches(rule: CatalogRule) -> bool:
+        return fnmatch.fnmatchcase(model_norm, rule.model_pattern)
+
+    # Tier 1: exact provider + specific model
+    for rule in index.tier1_exact_specific:
+        if rule.provider_pattern == provider_norm and _matches(rule):
+            return AbilitySuggestion(
+                abilities=list(rule.abilities),
+                matched_pattern=f"{rule.provider_pattern}/{rule.model_pattern}",
+                source="exact",
+            )
+
+    # Tier 2: wildcard provider + specific model
+    for rule in index.tier2_wildcard_specific:
+        if _matches(rule):
+            return AbilitySuggestion(
+                abilities=list(rule.abilities),
+                matched_pattern=f"*/{rule.model_pattern}",
+                source="wildcard_provider",
+            )
+
+    # Tier 3: provider-only fallback
+    for rule in index.tier3_provider_fallback:
+        if rule.provider_pattern == provider_norm:
+            return AbilitySuggestion(
+                abilities=list(rule.abilities),
+                matched_pattern=f"{rule.provider_pattern}/*",
+                source="exact",
+            )
+
+    return AbilitySuggestion(abilities=[], matched_pattern=None, source="none")
diff --git a/tests/web/test_model_catalog.py b/tests/web/test_model_catalog.py
new file mode 100644
index 000000000..b41ebbead
--- /dev/null
+++ b/tests/web/test_model_catalog.py
@@ -0,0 +1,462 @@
+"""Unit tests for ``xagent.web.services.model_catalog``.
+
+Covers:
+- YAML loading from the bundled real catalog
+- Three-tier resolution (exact provider+model, wildcard provider+model,
+  provider-only fallback)
+- Case-insensitive matching, whitespace tolerance, empty inputs
+- Graceful degradation when the YAML is missing or malformed
+- ``reload_catalog`` picks up edits without restarting the process
+- Regression tests for known-good rules and a recent vision-routing bug fix
+"""
+
+from __future__ import annotations
+
+import textwrap
+from pathlib import Path
+from typing import List
+
+import pytest
+
+from xagent.web.services import model_catalog
+from xagent.web.services.model_catalog import (
+    AbilitySuggestion,
+    lookup,
+    reload_catalog,
+)
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(autouse=True)
+def _reset_real_catalog():
+    """Each test starts with a fresh load of the real bundled catalog so
+    that one test's monkeypatching can't leak into the next."""
+    reload_catalog()
+    yield
+    reload_catalog()
+
+
+@pytest.fixture
+def temp_catalog(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    """Return a callable that writes a tiny YAML and points the catalog
+    module at it. Returns the new rule count after reload."""
+
+    def _write(yaml_body: str) -> int:
+        catalog_path = tmp_path / "abilities_catalog.yaml"
+        catalog_path.write_text(textwrap.dedent(yaml_body), encoding="utf-8")
+        monkeypatch.setattr(model_catalog, "_CATALOG_PATH", catalog_path)
+        return reload_catalog()
+
+    return _write
+
+
+# ---------------------------------------------------------------------------
+# Loading
+# ---------------------------------------------------------------------------
+
+
+class TestCatalogLoading:
+    """Verify the bundled catalog file loads and basic shape is sane."""
+
+    def test_real_catalog_loads_some_rules(self):
+        n = reload_catalog()
+        assert n > 50, f"expected > 50 rules in bundled catalog, got {n}"
+
+    def test_lookup_returns_AbilitySuggestion(self):
+        result = lookup("openai", "gpt-4o")
+        assert isinstance(result, AbilitySuggestion)
+        assert isinstance(result.abilities, list)
+        assert result.source in {"exact", "wildcard_provider", "none"}
+
+
+# ---------------------------------------------------------------------------
+# Three-tier resolution
+# ---------------------------------------------------------------------------
+
+
+class TestResolutionTiers:
+    """The three-tier fallback is the heart of the lookup logic — exercise
+    every transition explicitly."""
+
+    def test_tier1_exact_provider_and_model(self):
+        r = lookup("openai", "gpt-4o-2024-08-06")
+        assert r.source == "exact"
+        assert r.matched_pattern == "openai/gpt-4o*"
+        assert "vision" in r.abilities
+        assert "tool_calling" in r.abilities
+
+    def test_tier2_wildcard_provider_for_cross_provider_model(self):
+        # DeepSeek through OpenAI-compatible endpoint should NOT be
+        # absorbed by ``openai/*`` provider fallback.
+        r = lookup("openai", "deepseek-reasoner-v2")
+        assert r.source == "wildcard_provider"
+        assert r.matched_pattern == "*/deepseek-reasoner*"
+        assert r.abilities == ["chat", "thinking_mode"]
+
+    def test_tier3_provider_only_fallback(self):
+        # Unknown OpenAI model name should fall to ``openai/*`` rule.
+        r = lookup("openai", "some-completely-unknown-2050-model")
+        assert r.source == "exact"
+        assert r.matched_pattern == "openai/*"
+
+    def test_no_match_returns_none(self):
+        r = lookup("totally-unknown-provider", "some-random-model")
+        assert r.source == "none"
+        assert r.abilities == []
+        assert r.matched_pattern is None
+
+    def test_specific_rule_wins_over_provider_fallback(self):
+        # ``openai/o1*`` should win over ``openai/*``
+        r = lookup("openai", "o1-preview")
+        assert r.matched_pattern == "openai/o1*"
+        assert "thinking_mode" in r.abilities
+
+    def test_wildcard_provider_beats_provider_only_fallback(self):
+        # ``*/deepseek-chat*`` (specific model, wildcard provider) must win
+        # against ``openai/*`` (provider fallback). This is THE design
+        # invariant that lets DeepSeek/Qwen via openai-compat be detected
+        # without forcing every alias into the openai block.
+        r = lookup("openai", "deepseek-chat-1.5")
+        assert r.matched_pattern == "*/deepseek-chat*"
+        assert "tool_calling" in r.abilities
+
+
+# ---------------------------------------------------------------------------
+# Robustness
+# ---------------------------------------------------------------------------
+
+
+class TestRobustness:
+    """Inputs from the wild: weird casing, whitespace, empty strings, etc."""
+
+    def test_case_insensitive_provider(self):
+        a = lookup("OpenAI", "gpt-4o")
+        b = lookup("openai", "gpt-4o")
+        assert a.abilities == b.abilities
+        assert a.source == b.source
+
+    def test_case_insensitive_model_name(self):
+        a = lookup("openai", "GPT-4O-2024-08-06")
+        b = lookup("openai", "gpt-4o-2024-08-06")
+        assert a.abilities == b.abilities
+
+    def test_strips_whitespace(self):
+        a = lookup("  openai  ", "  gpt-4o  ")
+        b = lookup("openai", "gpt-4o")
+        assert a.abilities == b.abilities
+
+    def test_empty_model_name_returns_none(self):
+        r = lookup("openai", "")
+        assert r.source == "none"
+        assert r.abilities == []
+
+    def test_empty_provider_with_known_model_uses_wildcard(self):
+        # Empty provider + a model that has a */xxx* rule should still hit
+        # tier 2 (wildcard provider).
+        r = lookup("", "deepseek-chat")
+        assert r.source == "wildcard_provider"
+
+    def test_lookup_never_raises_on_weird_input(self):
+        # Catalog should be defensive about garbage inputs. None of these
+        # should raise.
+        for provider, model in [
+            (None, None),  # type: ignore[arg-type]
+            (None, "gpt-4o"),  # type: ignore[arg-type]
+            ("openai", None),  # type: ignore[arg-type]
+            ("", ""),
+            ("openai", "a" * 10_000),  # extremely long model name
+        ]:
+            r = lookup(provider, model)  # type: ignore[arg-type]
+            assert isinstance(r, AbilitySuggestion)
+
+
+# ---------------------------------------------------------------------------
+# Catalog file degradation paths
+# ---------------------------------------------------------------------------
+
+
+class TestCatalogDegradation:
+    """If the YAML is missing or malformed the API stays online — lookups
+    return ``source='none'`` instead of crashing the request."""
+
+    def test_missing_catalog_file(self, tmp_path, monkeypatch):
+        bogus = tmp_path / "does_not_exist.yaml"
+        monkeypatch.setattr(model_catalog, "_CATALOG_PATH", bogus)
+        n = reload_catalog()
+        assert n == 0
+        assert lookup("openai", "gpt-4o").source == "none"
+
+    def test_malformed_yaml_does_not_crash(self, temp_catalog):
+        # Intentionally broken YAML; loader logs and returns no rules.
+        n = temp_catalog("rules: [unclosed list with: {nested broken")
+        assert n == 0
+        assert lookup("openai", "gpt-4o").source == "none"
+
+    def test_unknown_ability_value_filtered_out(self, temp_catalog):
+        n = temp_catalog(
+            """
+            rules:
+              - pattern: "openai/test*"
+                abilities: [chat, vision, made_up_ability]
+            """
+        )
+        assert n == 1
+        r = lookup("openai", "test-model")
+        # 'made_up_ability' must not leak through — only the whitelisted
+        # ones survive.
+        assert r.abilities == ["chat", "vision"]
+        assert "made_up_ability" not in r.abilities
+
+    def test_rule_with_only_unknown_abilities_dropped(self, temp_catalog):
+        n = temp_catalog(
+            """
+            rules:
+              - pattern: "openai/test*"
+                abilities: [foo_ability, bar_ability]
+            """
+        )
+        # Rule had no valid abilities at all -> dropped entirely.
+        assert n == 0
+        assert lookup("openai", "test-model").source == "none"
+
+
+# ---------------------------------------------------------------------------
+# Reload semantics
+# ---------------------------------------------------------------------------
+
+
+class TestReload:
+    def test_reload_picks_up_edits(self, temp_catalog):
+        n1 = temp_catalog(
+            """
+            rules:
+              - pattern: "demo/x*"
+                abilities: [chat]
+            """
+        )
+        assert n1 == 1
+        assert lookup("demo", "x1").abilities == ["chat"]
+
+        # Update the same file with a different rule set; reload should
+        # see it without a process restart.
+        n2 = temp_catalog(
+            """
+            rules:
+              - pattern: "demo/x*"
+                abilities: [chat, vision]
+              - pattern: "demo/y*"
+                abilities: [chat, tool_calling]
+            """
+        )
+        assert n2 == 2
+        assert lookup("demo", "x1").abilities == ["chat", "vision"]
+        assert lookup("demo", "y2").abilities == ["chat", "tool_calling"]
+
+
+# ---------------------------------------------------------------------------
+# Real-catalog regression checks
+# ---------------------------------------------------------------------------
+
+
+class TestRealCatalogRegression:
+    """Concrete model -> abilities expectations the team has agreed on.
+    Update these when the catalog rules change intentionally."""
+
+    @pytest.mark.parametrize(
+        "provider,model_name,expected_abilities",
+        [
+            # OpenAI core
+            ("openai", "gpt-4o-2024-08-06", ["chat", "vision", "tool_calling"]),
+            ("openai", "gpt-3.5-turbo", ["chat", "tool_calling"]),
+            ("openai", "o1-preview", ["chat", "vision", "thinking_mode"]),
+            ("openai", "o3-mini", ["chat", "tool_calling", "thinking_mode"]),
+            # Anthropic
+            (
+                "claude",
+                "claude-3-5-sonnet-20241022",
+                ["chat", "vision", "tool_calling"],
+            ),
+            (
+                "claude",
+                "claude-sonnet-4-5",
+                ["chat", "vision", "tool_calling", "thinking_mode"],
+            ),
+            ("claude", "claude-3-5-haiku", ["chat", "tool_calling"]),
+            # Gemini
+            (
+                "gemini",
+                "gemini-2.5-pro",
+                ["chat", "vision", "tool_calling", "thinking_mode"],
+            ),
+            ("gemini", "gemini-1.5-flash-002", ["chat", "vision", "tool_calling"]),
+            # Zhipu
+            ("zhipu", "glm-4.5-air", ["chat", "tool_calling", "thinking_mode"]),
+            ("zhipu", "glm-4.5v", ["chat", "vision", "tool_calling", "thinking_mode"]),
+            ("zhipu", "glm-4v-plus", ["chat", "vision"]),
+            # Cross-provider via OpenAI-compatible endpoints
+            ("openai", "deepseek-chat", ["chat", "tool_calling"]),
+            ("openai", "deepseek-reasoner", ["chat", "thinking_mode"]),
+            (
+                "openai",
+                "kimi-k2.5",
+                ["chat", "vision", "tool_calling", "thinking_mode"],
+            ),
+        ],
+    )
+    def test_known_model(
+        self,
+        provider: str,
+        model_name: str,
+        expected_abilities: List[str],
+    ):
+        r = lookup(provider, model_name)
+        assert r.source != "none", f"{provider}/{model_name} expected to be in catalog"
+        assert r.abilities == expected_abilities, (
+            f"{provider}/{model_name} matched {r.matched_pattern}: "
+            f"expected {expected_abilities}, got {r.abilities}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Bug regressions
+# ---------------------------------------------------------------------------
+
+
+class TestBugRegressions:
+    """Each test here corresponds to a bug we fixed. Don't delete them
+    when refactoring — they pin specific catalog behavior."""
+
+    @pytest.mark.parametrize(
+        "provider,model_name",
+        [
+            ("alibaba-coding-plan", "qwen3.5-vl-plus"),
+            ("alibaba-coding-plan", "qwen3-vl-max"),
+            ("alibaba-coding-plan", "qwen2.5-vl-72b"),
+            ("alibaba-coding-plan-cn", "qwen3.5-vl-plus"),
+            ("alibaba-coding-plan-cn", "qwen-vl-max"),
+        ],
+    )
+    def test_alibaba_coding_plan_vl_variants_have_vision(
+        self, provider: str, model_name: str
+    ):
+        """Bug: ``alibaba-coding-plan/qwen3.5*`` was catching vision variants
+        before a more specific ``qwen*-vl*`` rule was added. This regression
+        test pins the fix."""
+        r = lookup(provider, model_name)
+        assert "vision" in r.abilities, (
+            f"{provider}/{model_name} must include 'vision'; "
+            f"matched={r.matched_pattern}, abilities={r.abilities}"
+        )
+        assert "tool_calling" in r.abilities
+
+    @pytest.mark.parametrize(
+        "provider,model_name",
+        [
+            ("zai-coding-plan", "glm-4v-plus"),
+            ("zai-coding-plan", "glm-4v-flash"),
+            ("zai-coding-plan", "glm-4.5v"),
+            ("zhipuai-coding-plan", "glm-4v"),
+            ("zhipuai-coding-plan", "glm-4.5v"),
+            ("zhipu", "glm-4.5v"),
+        ],
+    )
+    def test_glm_coding_plan_4v_variants_have_vision(
+        self, provider: str, model_name: str
+    ):
+        """Bug: ``glm-4*`` rule in the GLM coding-plan blocks was eating
+        ``glm-4v*`` (vision variant). Fixed by inserting an explicit
+        ``glm-4v*`` rule above ``glm-4*``."""
+        r = lookup(provider, model_name)
+        assert "vision" in r.abilities, (
+            f"{provider}/{model_name} must include 'vision'; "
+            f"matched={r.matched_pattern}"
+        )
+        assert "thinking_mode" in r.abilities or "glm-4v" in model_name
+
+    @pytest.mark.parametrize(
+        "provider,model_name",
+        [
+            ("kimi-for-coding", "kimi-k2.5"),
+            ("kimi-for-coding", "kimi-k2.6"),
+            ("openai", "kimi-k2.5"),
+            ("openai", "kimi-k2.6"),
+        ],
+    )
+    def test_kimi_k2_5_and_2_6_variants_keep_vision_and_thinking(
+        self, provider: str, model_name: str
+    ):
+        """Bug: generic ``kimi-k2*`` was catching newer multimodal K2.5/K2.6
+        models before more specific rules could add vision + thinking."""
+        r = lookup(provider, model_name)
+        assert "vision" in r.abilities, (
+            f"{provider}/{model_name} must include 'vision'; "
+            f"matched={r.matched_pattern}, abilities={r.abilities}"
+        )
+        assert "thinking_mode" in r.abilities
+
+    @pytest.mark.parametrize(
+        "provider,model_name",
+        [
+            # Pure text models that were regression-checked after adding the
+            # -vl rules — these must NOT pick up vision.
+            ("alibaba-coding-plan", "qwen3.5-plus"),
+            ("alibaba-coding-plan", "qwen3-coder-plus"),
+            ("alibaba-coding-plan", "qwen3-max-2026-01-23"),
+            ("alibaba-coding-plan", "glm-5"),
+            ("alibaba-coding-plan", "glm-4.7"),
+            ("zai-coding-plan", "glm-4.5-air"),
+            ("zai-coding-plan", "glm-4-plus"),
+            ("zhipuai-coding-plan", "glm-4.5-flash"),
+        ],
+    )
+    def test_text_only_variants_do_not_have_vision(
+        self, provider: str, model_name: str
+    ):
+        """No false-positive vision after the -vl/-4v fix."""
+        r = lookup(provider, model_name)
+        assert "vision" not in r.abilities, (
+            f"{provider}/{model_name} should be text-only; "
+            f"matched={r.matched_pattern}, abilities={r.abilities}"
+        )
+
+    def test_provider_fallback_does_not_eat_cross_provider_model(self):
+        """Regression for the resolution-tier ordering bug: previously
+        ``openai/*`` was winning over ``*/deepseek-chat*``."""
+        r = lookup("openai", "deepseek-chat")
+        assert r.source == "wildcard_provider"
+        assert r.matched_pattern == "*/deepseek-chat*"
+
+    def test_deepseek_v4_remains_text_only(self):
+        """Regression: DeepSeek V4 Preview is text-only and must not gain
+        false-positive multimodal support from the catalog."""
+        r = lookup("openai", "deepseek-v4")
+        assert "vision" not in r.abilities
+        assert "tool_calling" in r.abilities
+        assert "thinking_mode" in r.abilities
+
+    @pytest.mark.parametrize(
+        "provider,model_name,must_include",
+        [
+            # Catalog rev2: GPT-5/5.5, Claude 4.5, Gemini 3, DeepSeek V4 etc.
+            ("openai", "gpt-5.5", "thinking_mode"),
+            ("openai", "gpt-5", "thinking_mode"),
+            ("openai", "gpt-5-mini", "thinking_mode"),
+            ("claude", "claude-opus-4.5", "thinking_mode"),
+            ("gemini", "gemini-3-pro", "thinking_mode"),
+            ("openai", "deepseek-v4", "thinking_mode"),
+            ("openai", "deepseek-r2", "thinking_mode"),
+        ],
+    )
+    def test_recent_models_picked_up(
+        self, provider: str, model_name: str, must_include: str
+    ):
+        """Catalog rev2 added rules for newer models. Pin them so future
+        edits don't accidentally remove."""
+        r = lookup(provider, model_name)
+        assert must_include in r.abilities, (
+            f"{provider}/{model_name} expected to include {must_include}; "
+            f"got {r.abilities} (matched={r.matched_pattern})"
+        )