docs: expand providerAllowlist and document model field in customization guide

docs/contributing/ai-artifacts-common.md

@@ -3,7 +3,7 @@ title: 'AI Artifacts Common Standards'
 description: 'Common standards and quality gates for all AI artifact contributions to hve-core'
 sidebar_position: 2
 author: Microsoft
-ms.date: 2026-03-12
+ms.date: 2026-06-15
 ms.topic: reference
 ---
 
@@ -77,23 +77,18 @@ Focus on agents that:
 
 ## Model Version Requirements
 
-All AI artifacts (agents, instructions, prompts) **MUST** target the **latest available models** from Anthropic and OpenAI only.
-
-The model catalog (`scripts/linting/model-catalog.json`) contains the full list of models available in GitHub Copilot for validation purposes, but not all cataloged models are accepted for use in hve-core artifacts, per above.
+All AI artifacts (agents, instructions, prompts) **MUST** target models listed in the model catalog (`scripts/linting/model-catalog.json`). The catalog defines which models are available in GitHub Copilot and which providers are accepted via the `providerAllowlist` field.
 
 ### Accepted Models
 
-| Provider  | Models                                                          |
-|-----------|-----------------------------------------------------------------|
-| Anthropic | Latest Claude models (e.g., Claude Sonnet 4.6, Claude Opus 4.6) |
-| OpenAI    | Latest GPT models (e.g., GPT-5.4, GPT-5.3-Codex)                |
+Any model in the catalog whose provider appears in `providerAllowlist` and whose status is `ga` or `preview`. Run `npm run lint:models` to validate references against the catalog.
 
 ### Not Accepted
 
-* ❌ Models from other providers
-* ❌ Older model versions not in the catalog (e.g., GPT-4o, Claude 3.5)
+* ❌ Models not present in the catalog
+* ❌ Models from providers outside the catalog's `providerAllowlist`
 * ❌ Custom or fine-tuned models
-* ❌ Deprecated or retired model versions
+* ❌ Models with `retiring` or `retired` status
 
 ### Model Name Format
 

docs/contributing/custom-agents.md

@@ -3,7 +3,7 @@ title: 'Contributing Agents to HVE Core'
 description: 'Requirements and standards for contributing GitHub Copilot agent files to hve-core'
 sidebar_position: 5
 author: Microsoft
-ms.date: 2026-03-14
+ms.date: 2026-06-15
 ms.topic: how-to
 ---
 
@@ -93,11 +93,11 @@ Focus on agents that:
 
 ### Model Version Requirements
 
-All agents **MUST** target the **latest available models** from Anthropic and OpenAI only. The model catalog (`scripts/linting/model-catalog.json`) contains the full list of models available in GitHub Copilot, but hve-core restricts usage to Anthropic and OpenAI.
+All agents **MUST** target models listed in the model catalog (`scripts/linting/model-catalog.json`). The catalog defines which models are available in GitHub Copilot and which providers are accepted via the `providerAllowlist` field.
 
-Accepted: Latest Claude and GPT models with `(copilot)` suffix (e.g., `Claude Sonnet 4.6 (copilot)`, `GPT-5.4 (copilot)`)
+Accepted: Any model in the catalog whose provider appears in `providerAllowlist` and whose status is `ga` or `preview` (e.g., `Claude Sonnet 4.6 (copilot)`, `GPT-5.4 (copilot)`, `Gemini 2.5 Pro (copilot)`)
 
-Not Accepted: Models from other providers, older model versions not in the catalog, custom/fine-tuned models, deprecated versions
+Not Accepted: Models not present in the catalog, models from providers outside the `providerAllowlist`, custom/fine-tuned models, models with `retiring` or `retired` status
 
 ### Model Selection for Subagents
 

docs/customization/custom-agents.md

@@ -2,7 +2,7 @@
 title: Creating Custom Agents
 description: Build specialized agents with tool restrictions, subagent delegation, and mode-based workflows for your team
 author: Microsoft
-ms.date: 2026-02-24
+ms.date: 2026-06-15
 ms.topic: how-to
 keywords:
   - agents
@@ -228,15 +228,34 @@ For full frontmatter schema, naming conventions, and contribution requirements,
 
 Agent frontmatter supports these fields:
 
-| Field                      | Type    | Required | Purpose                                                      |
-|----------------------------|---------|----------|--------------------------------------------------------------|
-| `name`                     | string  | Yes      | Human-readable name shown in the agent picker                |
-| `description`              | string  | Yes      | One-line purpose with attribution suffix                     |
-| `tools`                    | array   | No       | Restrict available tools; omit for full access               |
-| `agents`                   | array   | No       | Human-readable names of subagent dependencies                |
-| `handoffs`                 | array   | No       | Structured transitions to other agents                       |
-| `disable-model-invocation` | boolean | No       | Set `true` for orchestrators that only delegate to subagents |
-| `user-invocable`           | boolean | No       | Set `false` for subagents not meant for direct invocation    |
+| Field                      | Type           | Required | Purpose                                                                          |
+|----------------------------|----------------|----------|----------------------------------------------------------------------------------|
+| `name`                     | string         | Yes      | Human-readable name shown in the agent picker                                    |
+| `description`              | string         | Yes      | One-line purpose with attribution suffix                                         |
+| `tools`                    | array          | No       | Restrict available tools; omit for full access                                   |
+| `agents`                   | array          | No       | Human-readable names of subagent dependencies                                    |
+| `handoffs`                 | array          | No       | Structured transitions to other agents                                           |
+| `model`                    | string / array | No       | Preferred model(s); array tried in order until one is available; omit to inherit |
+| `disable-model-invocation` | boolean        | No       | Set `true` for orchestrators that only delegate to subagents                     |
+| `user-invocable`           | boolean        | No       | Set `false` for subagents not meant for direct invocation                        |
+
+### model
+
+Specifies a preferred AI model as a single string or prioritized fallback array. The system tries each entry in order until one is available. When omitted, the agent inherits the parent conversation model.
+
+```yaml
+# Single model
+model: Claude Sonnet 4.6 (copilot)
+```
+
+```yaml
+# Prioritized fallback array
+model:
+  - Claude Haiku 4.5 (copilot)
+  - GPT-5.4 mini (copilot)
+```
+
+Subagents that perform read-only or validation tasks should use fast-tier models for cost optimization. Accepted models are those in `scripts/linting/model-catalog.json` whose provider appears in `providerAllowlist` and whose status is `ga` or `preview`. Run `npm run lint:models` to validate references.
 
 ### description
 

scripts/linting/model-catalog.json

@@ -179,6 +179,9 @@
     ],
     "providerAllowlist": [
         "Anthropic",
+        "Google",
+        "OpenAI",
+        "xAI",
         "OpenAI",
         "Microsoft"
     ],