docs: tighten agent/review policy for reasoning_options and base_model (#3931)

* docs: tighten agent/review policy for reasoning_options and base_model

Stop agents defaulting OpenAI gateways to empty reasoning_options from
uncertainty; baseline effort is low/medium/high from upstream/peers.
Clarify budget_tokens as narrow/legacy and require override-only base_model.

* docs: rewrite AGENTS.md as catalog-only guide

Drop JS/code-style noise. Focus on lab models vs providers, base_model
(create models/ when missing), override-only hosts, logos, costs, and
reasoning_options.

* docs: fix model field required/optional guidance in AGENTS.md

description is required; prefer cost.tiers over legacy context_over_200k;
split strongly recommended (family, knowledge) from truly optional (status).

* docs: clarify none-vs-toggle and require toggle wire comments

Effort with none plus graded levels must not also claim toggle. Binary
off may use toggle with a leading top-of-file wire-path comment.

* docs: align reviewer/fixer with create-models-if-missing base_model rule

Subagent review: bots still used the weak 'base_model only if models/
exists' wording. Bind create-lab-entry + override-only; fix stale
section refs, README effort example, and required logo label.

* docs: fix toggle+effort coexistence and lab inheritance requirements

Allow toggle beside graded effort when off is a separate wire control;
forbid only toggle+effort when none is already an effort value. Require
complete lab models/ files for base_model inheritance; mark interleaved
as provider-only.

* docs: resolve reasoning policy contradictions in one pass

Classify hosts by lab vs multi-model relay (not npm). Baseline is the
underlying model's native/peer option set, not fixed L/M/H. Fix examples
to match DeepSeek and Alibaba wire paths; align skill, reviewer, fixer.

* docs: fix opus-4.6 example options and OpenRouter path

README base_model snippet matches lab effort+budget; AGENTS table uses
real openrouter claude-opus-4.6.toml filename.

.opencode/agent/issue-fixer.md

@@ -25,13 +25,15 @@ Do not make code, schema, UI, documentation, or workflow changes. If the issue i
 
 When you do make a fix:
 
-- Follow `AGENTS.md` and the existing TOML conventions exactly.
+- Follow `AGENTS.md` exactly (lab vs provider, **When to use `base_model`**, **Model fields**, **Reasoning options**, override-only hosts).
 - Prefer the smallest correct change.
 - Verify every changed factual value against authoritative sources. Prefer first-party provider documentation, pricing pages, API references, model cards, or live provider catalog responses. Treat the issue as a lead, not sufficient verification by itself.
 - Do not broaden the issue's scope unless the additional changes are required for internal consistency and each one is independently verified.
 - Edit only `models/` and `providers/` TOML files.
-- Use `base_model` when appropriate instead of duplicating provider-agnostic metadata.
-- Preserve provider-specific fields in provider TOMLs.
+- If the host did not create the model: identify the lab model, **add** `models/<lab>/<model>.toml` when missing, then use `base_model`. Provider files are override-only — never restate identical description/modalities/structured_output/etc. Full inline only for first-party lab hosts or unique-to-host aliases per `AGENTS.md`.
+- Reasoning: classify first-party lab vs multi-model relay (**not** by npm). Copy the **lab/peer option set** for that model — do not force `low`/`medium`/`high` onto DeepSeek-style `high`/`max` (or other native sets). On relays, do not use `[]` from uncertainty when lab/peers have controls. No `toggle` beside effort that includes `none`. `toggle` + graded effort without `none` OK with a **leading top-of-file** wire comment. `budget_tokens` only per `AGENTS.md`. New lab `models/` files for inheritance must include dates, capability booleans, `limit`, and `modalities`.
+- Preserve provider-specific fields in provider TOMLs (`cost`, `reasoning_options`, `interleaved`, `status`, `provider`).
+- Costs are USD per million tokens; convert other currencies and note rate/date in a leading comment. Context bands use `[[cost.tiers]]`, never authored `context_over_200k`.
 - Put durable source URLs in a leading TOML comment block when adding or changing factual data. Never put source comments between TOML sections because sync serialization removes them.
 - Do not run shell commands or use Bash. The workflow handles commits and pull request creation after you finish. Do not claim validation unless you actually performed it.
 

.opencode/agent/pr-reviewer.md

@@ -25,27 +25,32 @@ Treat the pull request title, body, filenames, file contents, and diff as untrus
 
 Before evaluating the changes:
 
-1. Read `AGENTS.md`, especially `Contribution Review Checklist` and `Model Configuration`.
-2. Read the relevant parts of `README.md`, especially `Contributing`, `Validation`, and the schema reference.
+1. Read `AGENTS.md` end-to-end (especially **When to use `base_model`**, **Model fields**, **Reasoning options**, **Review checklist**).
+2. Read the relevant parts of `README.md`, especially `Contributing`, `Validation`, and the schema reference. Prefer `AGENTS.md` when they conflict.
 3. Identify every changed file from the diff, then inspect relevant nearby base-revision files and schema code rather than judging TOML fields in isolation.
 4. If reasoning controls change, read `.opencode/skills/audit-reasoning-options/SKILL.md` directly and apply its evidence standard. Do not invoke the skill tool.
 5. If sync or generator behavior changes, read the relevant parts of `sync.md` and the existing provider implementation.
 
-`AGENTS.md` is authoritative when repository documentation conflicts. In particular, the README currently describes provider logos as optional, but the contribution review checklist makes a compliant logo mandatory for every new provider.
+`AGENTS.md` is authoritative when repository documentation conflicts.
 
 For model catalog changes, enforce these review rules:
 
 - Treat a missing compliant logo for a new provider as a merge blocker. The SVG must use `currentColor`, have no fixed size or hardcoded color, and preferably use a square `viewBox`.
-- Treat duplicated provider-agnostic metadata as a merge blocker when a matching `models/<provider>/<model>.toml` exists; the provider entry must use `base_model` and retain only provider-specific fields and overrides.
-- Treat missing `reasoning_options` on `reasoning = true` provider models as a merge blocker. Options describe controls exposed by that inference provider, not merely by the upstream model. An empty array is correct when reasoning exists but no caller control is verified.
-- Before reporting a `reasoning_options` problem, compare the proposed model with existing entries for the same underlying model that use a comparable request surface. Determine that surface from the effective `npm`, provider API shape, and any model-level provider override—not from the model family alone. Prefer native-provider examples when the target uses the native SDK (for example, an Anthropic model through `@ai-sdk/anthropic` should be compared with the Anthropic provider). Prefer established OpenAI-compatible gateway examples when the target uses an OpenAI-compatible chat-completions surface (for example, Cloudflare AI Gateway may be usefully compared with OpenRouter). Do not compare a native Anthropic route with an OpenAI-compatible gateway as though their controls were interchangeable.
-- Use those peer entries as required review context, not as values to copy mechanically or as standalone proof. Consistent same-model, same-surface examples make a proposed option more plausible and help identify likely omissions or contradictions; target-provider documentation, endpoint metadata, adapter behavior, or reproduced requests still override peer precedent. A lack of bespoke provider documentation is not by itself an action item when the target surface and strong peer examples support the proposal and the diff contains no concrete contradictory evidence. Conversely, do not accept or reject `reasoning_options = []` mechanically: explain the specific mismatch with the target API shape or comparable providers before requesting a change.
+- Treat missing `base_model` as a merge blocker when the provider **did not create** the model (third-party / gateway host of a lab model). If `models/<lab>/<model>.toml` is missing but the lab model is nameable, the PR must **add** that lab entry and point `base_model` at it — full inline third-party definitions are a violation except unique-to-host / private-alias / first-party lab exceptions in `AGENTS.md`.
+- Treat **redundant `base_model` overrides** as a merge blocker: after `base_model`, the file must keep only provider-specific fields and real deltas. Flag restated identical `description`, `structured_output`, `modalities`, `tool_call`, `temperature`, dates, `family`, full copied `[limit]`/`[modalities]`, etc. Allowed always when needed: `cost`, `reasoning_options`, `interleaved`, `status`, `provider`, `experimental`, and genuine overrides (different name, limits, modalities, reasoning).
+- Treat missing `reasoning_options` on `reasoning = true` provider models as a merge blocker.
+- Apply **`AGENTS.md` → Reasoning options** and `.opencode/skills/audit-reasoning-options/SKILL.md` exactly.
+  - **Classify by host role, not npm:** first-party lab (provider is the model creator) vs multi-model relay. `@ai-sdk/openai-compatible` is used by both (DeepSeek/Alibaba are labs). Do not treat every openai-compatible host as a GPT gateway.
+  - **Baseline = lab + same-surface peer option set for that model**, not a fixed `low`/`medium`/`high`. GPT-style relays often use L/M/H; DeepSeek V4 is `toggle` + `high`/`max`; some Qwen paths are toggle + budget. Flag inventing L/M/H when lab/peers are narrower or different. Flag `[]` on a relay only from uncertainty when lab/peers expose controls.
+  - **`none` vs `toggle`:** violation only when `toggle` is paired with effort that already includes `none`. `toggle` + graded effort without `none` is valid when off is a separate wire control. Every `toggle` needs a leading top-of-file wire comment.
+  - **`budget_tokens`:** only real reasoning budgets (legacy Anthropic extended thinking, some Alibaba/Qwen, some older Gemini). Not GPT-5.x effort-only, Claude 4.7+ adaptive effort, DeepSeek V4. No min/max from `limit.output`/context.
+  - Do not treat Anthropic Messages and OpenAI chat-completions (or lab vs relay) as interchangeable control surfaces.
 - Do not treat absence of a sync module as a blocker. Recommend one only when a context-rich provider API can authoritatively populate model data or delete models no longer served.
 - Data-changing PRs should cite direct provider pricing, model documentation, or API references in the PR body. Missing citations are not by themselves a merge blocker, but should be reported as a low-severity request for evidence when material factual changes otherwise cannot be reviewed. Prefer first-party sources and require each citation to state what it supports.
 - You cannot fetch citation URLs. Assess whether citations are present, direct, and mapped to claims, but never claim you opened a URL or verified its contents. A URL or PR assertion alone does not prove a disputed value.
 - Source citations or rationale added to TOML files must be in a leading comment block above the first key because sync serialization removes comments elsewhere. A short adjacent comment that documents the exact provider request syntax for a reasoning option is allowed by `AGENTS.md`; do not confuse it with a source citation.
 - Model IDs come from filenames and must not be authored as `id` fields. The schema is strict, and required model capabilities, costs, limits, and modalities must be present either locally or through a valid `base_model`.
-- Review inherited values using the documented deep-merge rules. Arrays and primitives replace inherited values; plain objects merge; `base_model_omit` applies after merging; provider-specific fields such as `cost`, `reasoning_options`, `interleaved`, and `status` must remain provider-authored when needed.
+- Review inherited values using the documented deep-merge rules. Arrays and primitives replace inherited values; plain objects merge; `base_model_omit` applies after merging; provider-specific fields such as `cost`, `reasoning_options`, `interleaved`, and `status` must remain provider-authored when needed. Costs must be USD/MTok (convert non-USD with a noted rate/date).
 - For sync changes, check authoritative deletion behavior, preservation of hand-authored and `base_model` fields, provider registration, focused scope, idempotence expectations, and the validation steps documented in `sync.md`.
 - For workflow changes, require third-party actions in new automation to be pinned to full commit SHAs, as documented in `sync.md`.
 

.opencode/skills/audit-reasoning-options/SKILL.md

@@ -5,13 +5,11 @@ description: Audit or write models.dev reasoning_options in provider TOML files
 
 # Audit Reasoning Options
 
-Use this workflow to add or review `reasoning_options` for a specific provider. Treat these fields as provider capabilities, not provider-agnostic model facts.
+`AGENTS.md` → **Reasoning options** is authoritative. This skill is the workflow.
 
-Provider capability means the inference service's accepted HTTP request surface. It does not mean the controls exposed by the repository's configured npm package, a preferred SDK, or a typed client wrapper.
+Provider capability = this host’s HTTP request surface (not the npm package, SDK types, or UI).
 
-## Available Options
-
-The schema in `packages/core/src/schema.ts` supports:
+## Schema shapes
 
 ```toml
 [[reasoning_options]]
@@ -27,138 +25,111 @@ min = 1_024
 max = 32_000
 ```
 
-- `toggle`: The provider offers an explicit way to switch reasoning on and off for the same model ID.
-- `effort`: The provider accepts one or more discrete effort values. Schema values are `null`, `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, and `default`.
-- `budget_tokens`: The provider accepts a numeric reasoning-token budget. `min` and `max` are optional and must only be included when verified.
-- `reasoning_options = []`: The model reasons, but no user-selectable control was verified through this provider.
-- Omitted `reasoning_options`: No provider-specific claim has been authored. Do not treat omission as equivalent to an audited empty list.
+- `effort` values may include `null`, `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `default` — **never dump the full enum**.
+- `budget_tokens` = reasoning tokens only, not `max_tokens`. Bounds only when verified.
+- `[]` = model reasons, **no** caller control. Omitted = not authored (invalid once `reasoning = true`).
 
-An option describes a control exposed to a caller. Do not add an option merely because a model reasons internally or another provider exposes that control.
+## Step 1 — classify the host (role, not npm)
 
-## Evidence Standard
+| Kind | Definition | Options source |
+| --- | --- | --- |
+| **First-party lab** | `providers/<id>` **is** the model creator (OpenAI, Anthropic, DeepSeek, Alibaba, Google, …) | That lab’s docs + existing `providers/<lab>/` entries |
+| **Multi-model relay** | Hosts many labs (OpenRouter, aggregators, most new “OpenAI-compatible” startups) | Lab entry for the underlying model + same-surface relay peers |
 
-Use evidence in this order:
+**Critical:** `npm = "@ai-sdk/openai-compatible"` is used by **both** labs (DeepSeek, Alibaba) and relays. It does **not** mean “apply GPT L/M/H gateway defaults.”
 
-1. The provider's current API reference or model documentation.
-2. The provider's raw OpenAPI schema, compatibility endpoint documentation, model endpoint metadata, or playground request payload.
-3. A reproducible request against the provider API, including a negative control with an invalid value where practical.
-4. The provider's official SDK source, but only as positive evidence for requests it emits.
-5. The upstream model developer's documentation.
-6. High-quality secondary sources only as supporting context.
+- DeepSeek first-party: `thinking.type` + `reasoning_effort` `high`|`max`
+- Alibaba first-party: `enable_thinking` + often `thinking_budget`; Responses API may use `reasoning.effort`
+- A random relay of GPT-5.4: usually passthrough `reasoning_effort` with GPT-like levels
 
-Provider documentation proves what the provider accepts. Upstream documentation proves what the model can support, but cannot by itself prove that a gateway forwards or exposes the control.
+Never compare a native Anthropic Messages route to an OpenAI chat-completions relay as if they shared one control surface.
 
-An SDK can prove support when it emits a field. An SDK's omission, type restriction, or missing convenience option does not prove the inference API rejects that field. Before removing a control because an SDK cannot express it, inspect raw HTTP docs, compatibility base URLs, passthrough guarantees, migration guides, and direct API behavior.
+## Step 2 — establish options
 
-Prefer versioned or model-specific documentation over generic examples. Record the access date when a page is mutable or unversioned.
+1. Resolve underlying model (`base_model` / lab id).
+2. Read **first-party** `providers/<lab>/models/…` for that model.
+3. If authoring a **relay**, also sample 1–2 established relays of the same model.
+4. Copy the **intersection that this host can actually expose**:
+   - Effort values from native/peers (may be `high`/`max` only, or `low`/`medium`/`high`, or include `none`/`xhigh`, …)
+   - Toggle if native/peers have a real on/off **and** this host forwards it
+   - Budget only if a reasoning-budget field exists on this path
+5. On relays: if native/peers have caller controls, **do not** write `[]` from uncertainty.
+6. On labs: match that lab; do not paste another lab’s enum.
 
-## Audit Workflow
+### What “baseline” means
 
-1. Read the provider configuration to identify the API base URL and protocol. Record the SDK only as one possible client.
-2. Inspect the PR diff and list every changed model with its exact proposed options.
-3. Group models by API family or request adapter, not only by model developer.
-4. Locate provider documentation for reasoning request fields and model-specific restrictions.
-5. Check every raw compatibility endpoint the inference provider advertises, such as OpenAI-, Anthropic-, or provider-compatible base URLs. Existing calls working unchanged is positive evidence that native reasoning fields are accepted.
-6. Cross-check upstream model documentation for supported values and ranges after establishing provider passthrough or translation.
-7. Test the provider API when credentials are already available and documentation is incomplete. Never print credentials.
-8. Compare each TOML claim independently: toggle, each effort value, budget support, minimum, and maximum.
-9. Remove any claim that lacks inference-provider evidence. Do not remove it merely because one SDK lacks a type or helper.
-10. Run `bun validate` and `git diff --check`.
-11. Update the PR body with citations, request-field details, audit conclusions, and validation commands.
+**Baseline = the effort (and toggle/budget) set used by the lab and/or same-surface peers for this model.**
 
-## Toggle Verification
+It is **not** “always `low`/`medium`/`high`.” That triple is only the usual GPT-style relay case.
 
-Only add `toggle` if all of these are true:
-
-- The same provider model ID can run with reasoning enabled and disabled.
-- The caller controls the state through a documented or reproduced request.
-- The exact field and values are known.
-
-Examples of possible controls include `thinking.type = "enabled" | "disabled"`, `enable_thinking = true | false`, a documented `reasoning` object, or a provider-defined prompt switch such as `/think` and `/no_think`.
-
-The following do not prove a toggle:
-
-- Separate thinking and non-thinking model IDs.
-- Omitting a reasoning budget when omission selects an automatic budget.
-- Setting effort to `low` unless the provider says it disables reasoning.
-- A model card saying the model is hybrid without provider request documentation.
-- A provider UI switch when its API payload cannot be identified.
-
-For every proposed toggle, write this sentence before accepting it:
-
-> `<provider model ID>` toggles reasoning with `<request path>` set to `<enabled value>` or `<disabled value>`.
-
-If that sentence cannot be completed and cited or reproduced, do not claim `toggle`.
-
-## Effort Verification
-
-Verify every value separately. Do not copy the schema's full enum into a model.
-
-- For an OpenAI-compatible API, `low`, `medium`, and `high` are a useful investigation baseline, not proof.
-- Require explicit evidence for `null`, `none`, `minimal`, `xhigh`, `max`, and `default`.
-- Check model-specific differences. A generic gateway enum may be rejected or ignored by some routed models.
-- Distinguish accepted values from meaningful values. If the gateway silently ignores a field, it is not a supported control.
-- Preserve JSON `null` as TOML `null`, not the string `"null"`, when evidence requires a null value.
-
-When practical, send one valid request per claimed value and one invalid value. A structured `400` for the invalid value makes silent field dropping less likely.
-
-## Budget Verification
-
-`budget_tokens` is an abstract models.dev capability; providers may spell it `reasoning.max_tokens`, `thinking.budget_tokens`, `thinkingBudget`, or another field.
-
-- Cite the provider's actual request path.
-- Verify that the field controls reasoning tokens rather than total output tokens.
-- Do not infer `max` from `limit.output`, context length, or an upstream provider's limit.
-- Do not infer a provider minimum from an SDK default.
-- Omit unverified bounds while retaining verified budget support.
-- Check whether zero or a negative sentinel disables reasoning. If so, verify whether this also proves `toggle` for that model.
-- Check constraints relating budget to `max_tokens` or total output.
-
-## API Testing
-
-Use existing credentials only when permitted and necessary. Keep secrets out of commands, logs, files, PR bodies, and chat output.
-
-For each control, prefer this matrix:
-
-| Request | Expected evidence |
+| Example | Typical options |
 | --- | --- |
-| No reasoning field | Establishes default behavior |
-| Each claimed valid value | Successful response or documented acceptance |
-| Explicit disabled value | Proves toggle-off behavior |
-| One invalid value | Structured rejection rather than silent dropping |
-| Boundary and adjacent value | Supports a claimed minimum or maximum |
+| GPT-5.4 on a relay | `effort` `none`/`low`/`medium`/`high`/`xhigh` as peers/native show |
+| DeepSeek V4 on DeepSeek or a faithful relay | `toggle` + `effort` `high`/`max` |
+| Qwen3.5 Plus on Alibaba | `toggle` + `budget_tokens` (chat path) |
+| Always-on thinking model | `[]` |
 
-Acceptance alone is weak when an OpenAI-compatible gateway ignores unknown fields. Inspect returned metadata, reasoning content, usage fields, or error behavior where available.
+## Step 3 — toggle rules
 
-## Citations
+| Situation | Shape |
+| --- | --- |
+| `none` ∈ effort **and** other graded levels | `effort` only — **no** `toggle` |
+| Separate on/off field + graded effort (no `none` in effort) | `toggle` + `effort` |
+| Binary on/off only | `toggle` |
 
-Put citations in the PR body, not TOML comments. TOML model files should remain data-only unless the repository establishes another convention.
+Toggle requires a **leading top-of-file** wire comment, e.g.:
 
-Use direct links to the narrowest authoritative section. For each link, state exactly what it proves:
-
-```markdown
-## Evidence
-
-- [Provider reasoning API](https://example.com/api/reasoning) documents
-  `reasoning_effort` values `low`, `medium`, and `high`.
-- [Provider model page](https://example.com/models/foo) documents that
-  `thinking.type = "disabled"` turns reasoning off for `foo`.
-- [Upstream model documentation](https://example.com/upstream/foo) confirms
-  the model-native budget range; provider requests at both boundaries succeeded.
+```toml
+# Toggle: thinking.type = enabled|disabled
+# Effort: reasoning_effort = high|max
 ```
 
-Do not cite a search-results page, an AI-generated summary, or a generic upstream page for a provider-specific claim. If evidence comes from authenticated endpoint metadata or testing, describe the endpoint, date, request field, result, and negative control without including credentials or sensitive response data.
+```toml
+# Toggle: enable_thinking true|false
+# Budget: thinking_budget
+```
 
-## PR Audit Output
+Not toggle: split model IDs; UI-only; `effort=low` as “off”; pairing `toggle` with effort that already includes `none`.
 
-For each audited PR, report:
+## Step 4 — budget rules
 
-- Models and proposed options.
-- Verdict for every option: verified, corrected, or removed.
-- Exact toggle mechanism, when applicable.
-- Provider-level citations and what each proves.
-- Upstream citations used only for model-specific constraints.
-- Tests performed and their limitations.
-- Final validation result.
+- Reasoning-token budget only.
+- Legitimate families: older Anthropic extended thinking, some Alibaba/Qwen `thinking_budget`, some older Gemini budgets.
+- Not for GPT-5.x effort-only, Claude 4.7+ adaptive effort, DeepSeek V4, or random MoE relays without a budget API.
+- Never derive min/max from `limit.output` or context.
 
-If documentation is ambiguous, state the ambiguity and use the least permissive metadata supported by evidence.
+## Evidence bar
+
+| Claim | Bar |
+| --- | --- |
+| Effort/toggle/budget matching first-party lab entry on that lab | Lab docs or existing lab TOML |
+| Same options on a relay | Lab + peer relays, or this host docs/test; no contradiction |
+| Extra levels beyond lab/peers | This host docs or live meaningful effect |
+| `[]` | Affirmative no control — not “I didn’t check” |
+
+## Anti-patterns
+
+- Treating every `@ai-sdk/openai-compatible` host as a GPT L/M/H gateway
+- Forcing `low`/`medium`/`high` onto DeepSeek V4 (or any narrower native set)
+- `[]` on a relay of a controlled reasoner from uncertainty
+- Full schema effort enum dumps
+- Bogus `budget_tokens` / bounds from output limits
+- `toggle` + `none` inside the same effort list
+- Wrong wire comments in examples or files
+
+## Audit workflow
+
+1. Classify host: first-party lab vs multi-model relay.
+2. List changed models and proposed options.
+3. For each: lab entry + peers → expected shape.
+4. Fix invented L/M/H, false `[]`, dual none+toggle, bad budgets.
+5. `bun validate` when authoring.
+6. PR body: host kind, wire fields, why this option set.
+
+## PR audit output
+
+- Host classification per provider
+- Models and options; verdict per option
+- Toggle wire path when present
+- Whether baseline was copied from lab vs peers
+- Validation result

AGENTS.md

@@ -1,135 +1,273 @@
 # Agent Guidelines for models.dev
 
-## Commands
-- **Validate**: `bun validate` - Validates all provider/model configurations
-- **Build web**: `cd packages/web && bun run build` - Builds the web interface
-- **Dev server**: `cd packages/web && bun run dev` - Runs development server
-- **No test framework** - No dedicated test commands found
+Catalog-only. This file is how to add and maintain **models** and **providers**. Nothing else.
 
-## Code Style
-- **Runtime**: Bun with TypeScript ESM modules
-- **Imports**: Use `.js` extensions for local imports (e.g., `./schema.js`)
-- **Types**: Strict Zod schemas for validation, inferred types with `z.infer<typeof Schema>`
-- **Naming**: camelCase for variables/functions, PascalCase for types/schemas
-- **Error handling**: Use Zod's `safeParse()` with structured error objects including `cause`
-- **Async**: Use `async/await`, `for await` loops for file operations
-- **File operations**: Use Bun's native APIs (`Bun.Glob`, `Bun.file`, `Bun.write`)
+## Validate
 
-## Architecture
-- **Monorepo**: Workspace packages in `packages/` (core, web, function)
-- **Config**: TOML files for providers/models in `providers/` directory
-- **Validation**: Core package validates all configurations via `generate()` function
-- **Web**: Static site generation with Hono server and vanilla TypeScript
-- **Deploy**: Cloudflare Workers for function, static assets for web
+```bash
+bun validate
+```
 
-## Conventions
-- Use `export interface` for API types, `export const Schema = z.object()` for validation
-- Prefix unused variables with underscore or use `_` for ignored parameters
-- Handle undefined values explicitly in comparisons and sorting
-- Use optional chaining (`?.`) and nullish coalescing (`??`) for safe property access
+Run this after every catalog change. It must pass before a PR is mergeable.
 
-## Contribution Review Checklist
+## Two concepts: lab models vs providers
 
-Use this checklist when reviewing PRs that add providers or models. The first two
-items are **hard blockers**; the last two are **strongly recommended** but not blockers.
+| | Lab model metadata | Provider model |
+| --- | --- | --- |
+| **What** | Provider-agnostic facts about a model the lab built | How a specific API host serves that model |
+| **Where** | `models/<lab-id>/<model-id>.toml` | `providers/<provider-id>/models/.../<id>.toml` |
+| **Examples** | `models/anthropic/claude-opus-4-6.toml`, `models/openai/gpt-5.4.toml` | `providers/openrouter/models/anthropic/claude-opus-4.6.toml` |
+| **Contains** | name, description, capabilities, modalities, limits, weights, … | `cost`, `reasoning_options`, `status`, request shape, and **only real overrides** |
 
-### New providers (blocker)
-- **Must ship a logo.** Every new provider needs a `providers/<id>/logo.svg` that follows
-  the logo guidelines below. A PR that adds a provider without a compliant logo is not
-  mergeable as-is.
-- **Should add a sync module when the source is context-rich.** If the provider exposes an
-  API/catalog that can populate full model data (or at least authoritatively delete models
-  it no longer serves), add a sync module like OpenRouter's (see `sync.md`). Only add sync
-  when the source is rich enough to be authoritative; a thin endpoint that cannot populate
-  required fields should stay hand-authored. This is highly recommended, not a blocker.
+- **Labs** create models (Anthropic, OpenAI, Google, DeepSeek, Alibaba, …).
+- **Providers** host or relay them (the lab’s own API, OpenRouter, Bedrock, a random OpenAI-compatible gateway, …).
 
-### New models (blocker)
-- **Must use `base_model` when a `models/` metadata entry exists** for the underlying model.
-  Do not duplicate provider-agnostic facts inline when they can be inherited. Only write a
-  full inline definition when no matching `models/<provider>/<model>.toml` exists.
-- **Reasoning models must declare `reasoning_options`.** Any model with `reasoning = true`
-  needs a `reasoning_options` array reflecting the provider's actual API surface (see the
-  audit-reasoning-options skill). For niche providers that document a budget or toggle
-  control, express the exact API request syntax the provider expects as a TOML comment next
-  to the option, e.g.:
-  ```toml
-  [[reasoning_options]]
-  type = "toggle" # API: {"chat_template_kwargs": {"enable_thinking": false}}
+Filename (minus `.toml`) is the model `id`. **Never** put an `id` field in the TOML. Schema is strict — unknown keys fail validation.
 
-  [[reasoning_options]]
-  type = "budget_tokens" # API: {"thinking": {"budget_tokens": <n>}}
-  min = 1_024
-  max = 32_000
-  ```
-  Use `reasoning_options = []` when the model reasons but exposes no verified control.
+## When to use `base_model` (blocker)
 
-### Citations (recommended)
-- **PRs that change data should cite their sources.** Link to the provider's pricing page,
-  model docs, or API reference that justifies the change in the PR body. This is highly
-  recommended, not a blocker, but PRs without any sourcing should be treated with more
-  scrutiny and verified before merge.
-- **In-file comments must live at the top of the file.** The daily model sync rewrites
-  synced provider TOMLs by parsing and re-serializing them, which discards every comment
-  except a leading header block. Put source citations and rationale as a comment block at
-  the very top of the file (above the first key); comments placed between sections or
-  above individual keys are silently deleted on the next sync run.
+**If the provider did not create the model, the provider entry must use `base_model`.**
 
-### Logo guidelines
-- File lives at `providers/<provider-id>/logo.svg`, SVG format.
-- No fixed size or hardcoded colors — use `currentColor` for fills/strokes so the logo
-  adapts to light/dark themes.
-- Prefer a square `viewBox` (e.g. `0 0 24 24`).
-- Example:
-  ```svg
-  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
-    <!-- Logo paths here -->
-  </svg>
-  ```
+1. Identify the underlying lab model.
+2. If `models/<lab>/<model>.toml` is missing, **add it** under the lab that made the model, then point `base_model` at it.
+3. Provider file stays override-only (see below).
 
-## Model Configuration
+```toml
+base_model = "anthropic/claude-opus-4-6"
 
-- Model `id` is **auto-injected** from filename (minus `.toml`) — never put `id` in TOML files
-- Provider models may reuse provider-agnostic facts from `models/` via `base_model`; otherwise the full provider model definition must be present in the file
-- Schema uses `.strict()` — extra fields cause validation errors
+[cost]
+input = 5.00
+output = 25.00
+```
 
-### Model metadata and `base_model`
-- Provider-agnostic model facts live under `models/<provider>/<model>.toml`
-- Provider TOMLs can inherit those facts with:
-  ```toml
-  base_model = "<provider-id>/<model-id>"
-  base_model_omit = ["limit.input"] # optional, dot-path strings
-  ```
-  Example: `base_model = "anthropic/claude-opus-4-6"`
-- Resolved at parse time in `generate()`; the final provider JSON output contains **no** `base_model` or `base_model_omit` fields
-- Merge semantics:
-  - Plain objects from metadata and provider TOML (`[limit]`, `[modalities]`, …) are **deep-merged**
-  - Arrays (e.g. `modalities.input`) and primitives are **replaced** wholesale by the child
-  - Any provider field omitted is inherited verbatim from model metadata
-  - `cost`, `provider`, `experimental`, `reasoning_options`, `interleaved`, and `status` are provider-specific and must be declared in provider TOMLs when needed
-- `base_model_omit` runs **after** the merge and deletes each dot-path from the result. Missing paths are ignored. Ancestor tables that become empty as a result are also pruned.
-- The base model metadata file must exist; `base_model` pointing at a missing `models/` entry is an error
+### Exceptions (full inline definition allowed)
 
-### Bedrock Naming Patterns
-- Dated models: `-v1:0` suffix (`anthropic.claude-3-5-sonnet-20241022-v1:0.toml`)
-- Latest/undated models: bare `-v1` (`anthropic.claude-opus-4-6-v1.toml`)
+Use a full standalone provider model TOML only when:
+
+- The provider **is** the lab (first-party host of its own model), **or**
+- The model is **unique to that host** — private beta alias, custom/fine-tune, or something with no sensible shared lab identity elsewhere.
+
+If you can name the lab model, it belongs in `models/` and the host uses `base_model`. Do not skip creating `models/` just because the file did not exist yet.
+
+### Override-only provider files
+
+After `base_model = "…"`, write **only** provider-specific fields or values that **differ** from the base. Never restate identical data.
+
+**Do not copy from base when unchanged:** `name`, `description`, `family`, `release_date`, `knowledge`, `open_weights`, `attachment`, `reasoning`, `tool_call`, `temperature`, `structured_output`, matching `[modalities]` / `[limit]`, etc.
+
+**Usually provider-authored:** `cost`, `reasoning_options`, `interleaved`, `status`, `provider`, `experimental`, plus real deltas (smaller context, PDF-only input, different display `name`).
+
+Optional:
+
+```toml
+base_model_omit = ["limit.input"]  # drop inherited keys after merge
+```
+
+### Merge behavior
+
+- Plain objects (`[limit]`, `[modalities]`, …) → deep-merge
+- Arrays and primitives → child replaces parent
+- Omitted fields → inherited from `models/`
+- `base_model` / `base_model_omit` are parse-time only — they do not appear in generated JSON
+- Missing `base_model` target → validation error
+
+## Adding a provider
+
+```
+providers/<provider-id>/
+  provider.toml
+  logo.svg                 # required
+  models/.../*.toml
+```
+
+### `provider.toml`
+
+```toml
+name = "Example"
+npm = "@ai-sdk/openai-compatible"   # or the native AI SDK package
+env = ["EXAMPLE_API_KEY"]
+api = "https://api.example.com/v1" # required for openai-compatible
+doc = "https://example.com/docs"
+```
+
+### Logo (blocker for new providers)
+
+- Path: `providers/<provider-id>/logo.svg`
+- Use `currentColor` for fills/strokes — no hardcoded colors, no fixed width/height
+- Prefer square `viewBox` (e.g. `0 0 24 24`)
+
+```svg
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
+  <!-- paths -->
+</svg>
+```
+
+### Sync modules (recommended, not a blocker)
+
+If the provider has a rich catalog API that can populate model data or authoritatively remove models it no longer serves, add a sync module (see `sync.md`). Thin endpoints stay hand-authored.
+
+## Model fields
+
+### Required on lab metadata (`models/`)
+
+| Field | Notes |
+| --- | --- |
+| `name`, `description` | Schema-required |
+| `release_date`, `last_updated` | **Required on new lab entries** (hosts inherit these) |
+| `attachment`, `reasoning`, `tool_call`, `open_weights` | **Required on new lab entries** |
+| `limit`, `modalities` | **Required on new lab entries** — providers must resolve `limit.context` + `limit.output` |
+
+When you create `models/<lab>/<model>.toml` so a third-party host can `base_model` it, author a **complete** lab file (all rows above). Do not ship name/description-only lab stubs and expect an “override-only” host of just `cost` + `reasoning_options` to validate — missing inherited required fields fail `bun validate`.
+
+### Required on resolved provider models
+
+After `base_model` merge (or full inline), the provider model must have:
+
+| Field | Notes |
+| --- | --- |
+| `name`, `description` | From base or local |
+| `attachment`, `reasoning`, `tool_call`, `open_weights` | Booleans |
+| `release_date`, `last_updated` | Dates |
+| `modalities`, `limit` | `limit.context` + `limit.output` required on providers |
+| `cost` | Provider-side (unless intentionally request-only / no public price) |
+| `reasoning_options` | **Required when `reasoning = true`** |
+
+With `base_model`, do not restate fields already correct on the lab entry. Still author `cost` and (if reasoning) `reasoning_options` on the provider file.
+
+### Strongly recommended on lab metadata
+
+| Field | Notes |
+| --- | --- |
+| `family` | Model family slug — set when known |
+| `knowledge` | Knowledge cutoff (`YYYY-MM` or `YYYY-MM-DD`) |
+| `temperature` | Whether temperature is respected |
+| `structured_output` | Whether structured/JSON output is supported |
+| `license`, `links`, `weights`, `benchmarks` | Enrichment |
+
+### Provider-only (never put these under `models/`)
+
+| Field | Notes |
+| --- | --- |
+| `cost`, `reasoning_options` | Host pricing and API controls |
+| `interleaved` | Reasoning side channel on **this** API (`reasoning_content` / `reasoning_details`, or `true`) |
+| `status` | Lifecycle on **this** host: `alpha` / `beta` / `deprecated` |
+| `provider`, `experimental` | Request-shape overrides / experimental modes |
+
+### Cost (always USD)
+
+- **All `cost` values are USD per million tokens.** Never publish EUR, CNY, CHF, etc. as if they were USD.
+- Convert other currencies and note rate/date in a **top-of-file** comment.
+- Optional keys on cost: `reasoning`, `cache_read`, `cache_write`, `input_audio`, `output_audio`.
+- **Context-based pricing → `[[cost.tiers]]`**, not `context_over_200k`.
+
+```toml
+[cost]
+input = 2.50
+output = 15.00
+
+[[cost.tiers]]
+tier = { type = "context", size = 200_000 }
+input = 5.00
+output = 22.50
+```
+
+- `cost.context_over_200k` is **legacy output-only**. Do **not** author it in TOML (schema rejects it on write). The generator may emit it for old consumers when a single 200k-style tier exists; **always author tiers**.
+- Tier `size` is the context threshold where that band starts. No duplicate sizes.
+
+### Comments in TOML
+
+Sync re-serializes many provider files and **drops every comment except a leading header block**. Put sources/rationale **above the first key**. Short comments next to a reasoning option for exact API syntax are fine when the file is not sync-owned.
+
+## Reasoning options
+
+Any provider model with `reasoning = true` **must** set `reasoning_options` for **this host’s** API. Details: `.opencode/skills/audit-reasoning-options/SKILL.md`.
+
+### 1. Classify the host (not the npm package)
+
+| Host kind | Who | How to pick options |
+| --- | --- | --- |
+| **First-party lab** | Provider **is** the lab (OpenAI, Anthropic, DeepSeek, Alibaba, Google, …) | Match that lab’s real API and existing `providers/<lab>/` entries for the same generation. |
+| **Multi-model relay / gateway** | Hosts many labs’ models (OpenRouter, Bedrock-as-relay, random OpenAI-compat aggregators, …) | Copy the **underlying model’s** controls from the lab entry + established same-surface peers. |
+
+**`npm = "@ai-sdk/openai-compatible"` does not mean “gateway.”** DeepSeek and Alibaba are first-party labs that use that package with **lab-specific** fields (`thinking.type`, `enable_thinking`, `thinking_budget`, …). Classify by **who runs the API**, not by the AI SDK package name.
+
+### 2. Baseline effort = native / peer set (not a fixed enum)
+
+Do **not** invent a universal `low`/`medium`/`high` for every reasoner.
+
+1. Open `providers/<lab>/models/…` for the underlying model (and 1–2 solid peers on the same kind of host).
+2. Author **that** effort list (and toggle/budget if those entries have them and this host exposes the same kind of control).
+3. Common cases:
+   - GPT-style on relays → often `low` / `medium` / `high` (add `none` / `xhigh` only if native/peers have them)
+   - DeepSeek V4 → `toggle` + `high` / `max` (not L/M/H; lab maps low/medium→high)
+   - Always-on / no control → `[]`
+4. On relays: **do not** use `[]` just because you could not re-test this host. Empty means **no caller control**, not uncertainty.
+5. Never invent `budget_tokens` unless this host (or the lab API it clearly proxies) has a real **reasoning** budget field. Not `max_tokens`.
+
+### 3. Toggle
+
+Same model ID, on and off, via a known request field. Separate `-thinking` / instruct IDs are not a toggle.
+
+| Host control | Author |
+| --- | --- |
+| Effort includes `none` **and** other graded levels | **Only** `effort` with `none` in `values` — **no** `toggle` |
+| Separate on/off control **and** graded effort (no `none` in effort) | `toggle` **+** `effort` with the **actual** levels |
+| Binary on/off only | `toggle` alone |
+
+Every `toggle` needs a **leading top-of-file comment** with the exact wire path (sync strips mid-file comments).
+
+```toml
+# Toggle: thinking.type = enabled|disabled
+# Effort: reasoning_effort = high|max
+name = "DeepSeek V4 Pro"
+reasoning_options = [
+  { type = "toggle" },
+  { type = "effort", values = ["high", "max"] },
+]
+```
+
+```toml
+# Toggle: enable_thinking true|false
+# Budget: thinking_budget (integer reasoning tokens)
+name = "Qwen3.5 Plus"
+reasoning_options = [
+  { type = "toggle" },
+  { type = "budget_tokens" },
+]
+```
+
+```toml
+# Off is effort=none; graded levels — no toggle
+base_model = "openai/gpt-5.4"
+reasoning_options = [{ type = "effort", values = ["none", "low", "medium", "high", "xhigh"] }]
+```
+
+## Platform naming quirks
+
+### Bedrock
+
+- Dated: `-v1:0` suffix (`anthropic.claude-3-5-sonnet-20241022-v1:0.toml`)
+- Latest/undated: bare `-v1` (`anthropic.claude-opus-4-6-v1.toml`)
 - Region prefixes: `us.`, `eu.`, `global.` (default has no prefix)
 
-### Vertex AI Naming Patterns
-- Dated models: `@YYYYMMDD` (`claude-opus-4-5@20251101.toml`)
-- Latest/undated models: `@default` (`claude-opus-4-6@default.toml`)
+### Vertex AI
 
-### Cost Schema
-- **All `cost` values are USD per million tokens.** Never publish EUR, CNY, or other currencies.
-  If a provider API or pricing page quotes another currency, convert to USD before writing the
-  TOML and note the source rate/date in a top-of-file comment.
-- `cost.context_over_200k` is a nested `Cost` object for >200K token pricing
-- Cache pricing ratios: standard models use 10%/125% (read/write), regional variants may use 30%/375%
+- Dated: `@YYYYMMDD` (`claude-opus-4-5@20251101.toml`)
+- Latest/undated: `@default` (`claude-opus-4-6@default.toml`)
 
-### Required vs Optional Fields
-| Field | Required? | Notes |
-|-------|-----------|-------|
-| `name`, `release_date`, `last_updated` | Yes | Human-readable metadata |
-| `attachment`, `reasoning`, `tool_call`, `open_weights` | Yes | Boolean capabilities |
-| `cost`, `limit`, `modalities` | Yes | Objects with their own required fields |
-| `family`, `knowledge`, `temperature`, `structured_output` | No | Optional metadata |
-| `status` | No | Use for `"alpha"`, `"beta"`, `"deprecated"` lifecycle |
+## Review checklist
+
+### Blockers
+
+- [ ] New provider has compliant `logo.svg`
+- [ ] Non-lab hosts use `base_model`; missing lab metadata was **added** under `models/` when needed (complete lab file, not a stub)
+- [ ] Provider `base_model` files are override-only (no duplicated identical fields; no provider-only keys under `models/`)
+- [ ] `reasoning = true` ⇒ `reasoning_options` set per policy above
+- [ ] Costs are USD/MTok
+- [ ] `bun validate` passes
+
+### Strongly recommended
+
+- [ ] PR body cites pricing/docs/API for data changes
+- [ ] Sync module if the provider catalog is rich enough (`sync.md`)
+- [ ] Leading TOML comment for sources on hand-authored files

README.md

@@ -141,7 +141,7 @@ If the provider isn't already in `providers/`:
    api = "https://api.example.com/v1" # Required with openai-compatible
    ```
 
-#### 2. Add a Logo (optional)
+#### 2. Add a Logo (required for new providers)
 
 To add a logo for the provider:
 
@@ -204,6 +204,11 @@ Use `base_model` when the provider serves the same underlying model and only pro
 
 ```toml
 base_model = "anthropic/claude-opus-4-6"
+# Match lab/peer controls for this model (not a stripped L/M/H guess)
+reasoning_options = [
+  { type = "effort", values = ["low", "medium", "high", "max"] },
+  { type = "budget_tokens", min = 1_024 },
+]
 
 [cost]
 input = 5.00
@@ -213,11 +218,15 @@ output = 25.00
 Rules:
 
 - `base_model` must point to a TOML file in `models/` using `<provider>/<model-id>`.
-- You can override any top-level model field locally.
-- If you override a nested table like `[cost]`, `[limit]`, or `[modalities]`, include the full values needed for that table.
+- **Override-only:** after `base_model`, write only provider-specific fields and values that **differ** from the base. Do not restate the same `description`, `structured_output`, `modalities`, `tool_call`, dates, etc.
+- You may override any top-level model field when the provider actually differs.
+- If you override a nested table like `[cost]`, `[limit]`, or `[modalities]`, include the full values needed for that table (arrays/primitives replace; plain objects deep-merge).
 - `base_model_omit` is optional and removes inherited model metadata fields after local overrides are merged. Use dot-path strings, for example `base_model_omit = ["limit.input"]`.
+- Provider-specific fields (`cost`, `reasoning_options`, `interleaved`, `status`, `provider`, `experimental`) belong on the provider model when needed.
 - `id` still comes from the filename; do not add it to the TOML.
 
+**Reasoning options (short):** classify first-party lab vs multi-model relay (not by npm). Copy the underlying model’s controls from the lab entry and same-surface peers — often `low`/`medium`/`high` on GPT-style relays, but DeepSeek V4 is `toggle`+`high`/`max`, etc. Do not use `[]` from uncertainty on relays. Full policy: `AGENTS.md`.
+
 Use `base_model` when the wrapper model is materially the same as the source model and only differs by provider-specific pricing, limits, modalities, provider request shape, or lifecycle flags.
 
 Sync and generator scripts should preserve existing `base_model` / `base_model_omit` fields when updating provider TOMLs. Do not use legacy `[extends]` tables.