feat: provider integration harness and models.dev catalog

.changeset/bright-cli-providers.md

@@ -0,0 +1,5 @@
+---
+'@agentskit/cli': patch
+---
+
+Allow `agentskit run` and `agentskit chat` to select Groq and OpenRouter using their environment keys and current catalog-backed default models.

.changeset/bright-providers-switch.md

@@ -0,0 +1,5 @@
+---
+'@agentskit/adapters': patch
+---
+
+Add a tested provider-swap recipe for OpenAI, Anthropic, Gemini, OpenRouter, Groq, and Ollama, align provider documentation with the adapters' supported configuration, and migrate Groq's default from the retiring Llama 3.3 model to `openai/gpt-oss-120b`.

.changeset/clear-gemini-aliases.md

@@ -0,0 +1,5 @@
+---
+'@agentskit/cli': patch
+---
+
+Accept Google API-key aliases when resolving Gemini, align CLI model defaults with the provider registry, and add a no-network compatibility gate for every registry-backed CLI provider.

.changeset/fresh-models-catalog.md

@@ -0,0 +1,6 @@
+---
+'@agentskit/adapters': minor
+'@agentskit/cli': patch
+---
+
+Refresh the models.dev-backed catalog with normalized provenance, lifecycle and pricing metadata, add offline freshness checks, and reject nested ternaries in changed source files. CLI provider diagnostics now use named fix helpers instead of nested conditional expressions.

.changeset/quiet-scaffolds-connect.md

@@ -0,0 +1,5 @@
+---
+'@agentskit/cli': patch
+---
+
+Allow `agentskit init` to scaffold Groq and OpenRouter starters with the correct adapter imports, current default models, and environment-file hints.

.changeset/steady-doctors-check.md

@@ -0,0 +1,5 @@
+---
+'@agentskit/cli': patch
+---
+
+Drive `agentskit doctor` from a static provider registry with explicit credential, reachability, and default-model status for high-demand providers, while keeping unsupported providers and secret values clearly out of network checks and output.

.changeset/tidy-provider-scaffolds.md

@@ -0,0 +1,5 @@
+---
+'@agentskit/cli': patch
+---
+
+Allow `agentskit init` to scaffold DeepSeek, Grok, and Kimi starters with their runtime adapters, current default models, and environment-file hints.

.doc-bridge/capabilities.json

@@ -7,7 +7,7 @@
     "name": "AgentsKit",
     "root": "."
   },
-  "contentHash": "c878f166fb291e94a157ccd5817b91568c86796330c4368cd27d22d3b3060d31",
+  "contentHash": "4b8372dc800cc78266ddc77be7184f5451bcfa6a91c36f3ef631f6119733c5e6",
   "artifacts": {
     "index": ".doc-bridge/index.json",
     "llmsTxt": "llms.txt"

.doc-bridge/index.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
-  "contentHash": "c878f166fb291e94a157ccd5817b91568c86796330c4368cd27d22d3b3060d31",
+  "contentHash": "4b8372dc800cc78266ddc77be7184f5451bcfa6a91c36f3ef631f6119733c5e6",
   "contentHashAlgo": "sha256-normalized-v1",
-  "generatedAt": "2026-08-13T00:09:29.294Z",
+  "generatedAt": "2026-08-13T01:23:01.529Z",
   "project": {
     "name": "AgentsKit",
     "root": "."
@@ -14,7 +14,7 @@
       "title": "adapters",
       "path": "apps/docs-next/content/docs/for-agents/adapters.mdx",
       "description": "Every LLM provider, one contract. Stream, tool calls, retry, abort all normalized. Plus higher-order adapters that compose candidates (router, ensemble, fallback) and a `createAdapter` factory for custom providers.",
-      "body": "Purpose Every LLM provider, one contract. Stream, tool calls, retry, abort all normalized. Plus higher-order adapters that compose candidates (router, ensemble, fallback) and a createAdapter factory for custom providers. Contract and failure semantics - Every stream ends exactly once with done or error . Error chunks expose an Error as metadata.error ; a provider connection that closes before its native completion marker is an error, not a partial success. - abort(reason) propagates to active transports. Custom parsers receive the request signal and response so they can cancel work and validate protocols. - Tool-capable native adapters serialize assistant calls and correlated tool results across turns. Parallel results are grouped into one provider turn for Anthropic and Gemini/Vertex. - Gemini authenticates through x-goog-api-key , keeping credentials out of request URLs. vercelAI validates and parses the Vercel UI message stream v1 framing rather than treating it as OpenAI SSE. - Embedders reject empty, missing, or non-numeric vectors instead of returning unusable data. The package remains beta . Its implementation is being prepared for an API freeze, but ADR 0024 still requires the elapsed beta window, qualifying release lines, an accepted package RFC, and complete repository evidence before 1.0. Install Primary exports Native adapters - anthropic , openai , gemini , grok , ollama , deepseek , kimi , langchain , langgraph , vercelAI , generic . - azureOpenAI / azureOpenAIAdapter — Azure-hosted OpenAI deployments. - vertex / vertexAdapter — Google Vertex AI (Gemini, Anthropic-on-Vertex). - bedrock / bedrockAdapter — AWS Bedrock. - replicate / replicateAdapter — Replicate inference. - bail / bailAdapter (alias qwen ) — Alibaba DashScope / Qwen. - webllm / webllmAdapter — browser-only WebGPU via @mlc-ai/web-llm (peer dep). - createAdapter({ send, parse, abort }) — build your own. See . OpenAI-compatible providers mistral , cohere , together , groq , fireworks , openrouter , huggingface , lmstudio , vllm , llamacpp , cerebras (with cerebrasAdapter factory variant). All share the createOpenAICompatibleAdapter base; each exposes a default baseUrl and accepts an override. Composition - createRouter({ candidates, policy, classify, onRoute }) — pick one per request by cost / latency / tags / custom. See . - createEnsembleAdapter({ candidates, aggregate }) — fan-out + merge (majority-vote / concat / longest / fn). See . - createFallbackAdapter([candidates], { shouldRetry, onFallback }) — try in order, fall through on open / first-chunk / zero-chunk failures. See . Testing + utilities - mockAdapter , recordingAdapter , replayAdapter , inMemorySink — ship without network. - simulateStream , chunkText , fetchWithRetry — lower-level helpers. Cost / carbon / lifecycle - applyCarbonTable , estimateCO2Grams , DEFAULT CARBON TABLE — carbon-aware routing inputs; feed into createRouter policy. - resolveModel , withDeprecationPolicy , DEFAULT DEPRECATION TABLE — auto-upgrade deprecated model IDs at adapter construction. - refreshCredentials , createRotatingCredentials — opt-in credential-rotation primitives. Stock adapters do not call these automatically; wire them yourself (e.g. resolve current() per request) or reconstruct the adapter after rotation. Embedders - openaiEmbedder , geminiEmbedder , ollamaEmbedder , deepseekEmbedder , grokEmbedder , kimiEmbedder , createOpenAICompatibleEmbedder . Catalog ( @agentskit/adapters/catalog subpath) Data-driven provider/model metadata adapted from models.dev , cached as a committed snapshot. Large, so it ships only via the ./catalog subpath — never bundled into the main entry. The runtime never fetches models.dev ; regenerate with pnpm sync:models and commit the diff. - getProvider , getModel , listProviders , listOpenAICompatibleProviders — query the catalog. - dispatchFromCatalog({ provider, model, apiKey, baseUrl? }) — build a native OpenAI-compatible adapter for any provider the snapshot marks compatible (first-class anthropic/openai/gemini/ollama keep their own factories). Throws typed CatalogDispatchError . - resolveCost(provider, model, { live?, timeoutMs? }) — cache-only by default; opt-in live tries models.dev then falls back to cache, never throwing on a network failure. Returns { cost, source, stale } . - applyOverrides(snapshot, { allowedProviders, disabledProviders, allowedModels }) — local policy without forking the catalog. - detectCatalogDrift() — CI guard; flags undispatchable providers. - catalogSnapshotSchema (JSON Schema, public contract), catalogSource() (provenance + generatedAt for staleness). Minimal example Common patterns - Rank candidates by cost and fall back on errors: compose createRouter with createFallbackAdapter . - A/B providers without users: or . - Test without keys: pair recordingAdapter + replayAdapter ( ). Related packages - — the AdapterFactory contract lives here. - - Source - npm: https://www.npmjs.com/package/@agentskit/adapters - repo: https://github.com/AgentsKit-io/agentskit/tree/main/packages/adapters"
+      "body": "Purpose Every LLM provider, one contract. Stream, tool calls, retry, abort all normalized. Plus higher-order adapters that compose candidates (router, ensemble, fallback) and a createAdapter factory for custom providers. Contract and failure semantics - Every stream ends exactly once with done or error . Error chunks expose an Error as metadata.error ; a provider connection that closes before its native completion marker is an error, not a partial success. - abort(reason) propagates to active transports. Custom parsers receive the request signal and response so they can cancel work and validate protocols. - Tool-capable native adapters serialize assistant calls and correlated tool results across turns. Parallel results are grouped into one provider turn for Anthropic and Gemini/Vertex. - Gemini authenticates through x-goog-api-key , keeping credentials out of request URLs. vercelAI validates and parses the Vercel UI message stream v1 framing rather than treating it as OpenAI SSE. - Embedders reject empty, missing, or non-numeric vectors instead of returning unusable data. The package remains beta . Its implementation is being prepared for an API freeze, but ADR 0024 still requires the elapsed beta window, qualifying release lines, an accepted package RFC, and complete repository evidence before 1.0. Install Primary exports Native adapters - anthropic , openai , gemini , grok , ollama , deepseek , kimi , langchain , langgraph , vercelAI , generic . - azureOpenAI / azureOpenAIAdapter — Azure-hosted OpenAI deployments. - vertex / vertexAdapter — Google Vertex AI (Gemini, Anthropic-on-Vertex). - bedrock / bedrockAdapter — AWS Bedrock. - replicate / replicateAdapter — Replicate inference. - bail / bailAdapter (alias qwen ) — Alibaba DashScope / Qwen. - webllm / webllmAdapter — browser-only WebGPU via @mlc-ai/web-llm (peer dep). - createAdapter({ send, parse, abort }) — build your own. See . OpenAI-compatible providers mistral , cohere , together , groq , fireworks , openrouter , huggingface , lmstudio , vllm , llamacpp , cerebras (with cerebrasAdapter factory variant). All share the createOpenAICompatibleAdapter base; each exposes a default baseUrl and accepts an override. Composition - createRouter({ candidates, policy, classify, onRoute }) — pick one per request by cost / latency / tags / custom. See . - createEnsembleAdapter({ candidates, aggregate }) — fan-out + merge (majority-vote / concat / longest / fn). See . - createFallbackAdapter([candidates], { shouldRetry, onFallback }) — try in order, fall through on open / first-chunk / zero-chunk failures. See . Testing + utilities - mockAdapter , recordingAdapter , replayAdapter , inMemorySink — ship without network. - simulateStream , chunkText , fetchWithRetry — lower-level helpers. Cost / carbon / lifecycle - applyCarbonTable , estimateCO2Grams , DEFAULT CARBON TABLE — carbon-aware routing inputs; feed into createRouter policy. - resolveModel , withDeprecationPolicy , DEFAULT DEPRECATION TABLE — auto-upgrade deprecated model IDs at adapter construction. - refreshCredentials , createRotatingCredentials — opt-in credential-rotation primitives. Stock adapters do not call these automatically; wire them yourself (e.g. resolve current() per request) or reconstruct the adapter after rotation. Embedders - openaiEmbedder , geminiEmbedder , ollamaEmbedder , deepseekEmbedder , grokEmbedder , kimiEmbedder , createOpenAICompatibleEmbedder . Catalog ( @agentskit/adapters/catalog subpath) Data-driven provider/model metadata adapted from models.dev , cached as a committed snapshot. Large, so it ships only via the ./catalog subpath — never bundled into the main entry. The runtime never fetches models.dev ; regenerate with pnpm sync:models and commit the diff. The snapshot carries a normalized content hash and ETag, while scheduled CI checks freshness and upstream drift. - getProvider , getModel , listProviders , listOpenAICompatibleProviders — query the catalog. - dispatchFromCatalog({ provider, model, apiKey, baseUrl? }) — build a native OpenAI-compatible adapter for any provider the snapshot marks compatible (first-class anthropic/openai/gemini/ollama keep their own factories). Throws typed CatalogDispatchError . - resolveCost(provider, model, { live?, timeoutMs? }) — cache-only by default; opt-in live tries models.dev then falls back to cache, never throwing on a network failure. Returns { cost, source, stale } . - applyOverrides(snapshot, { allowedProviders, disabledProviders, allowedModels }) — local policy without forking the catalog. - detectCatalogDrift() — CI guard; flags undispatchable providers. - classifyCatalogProvider(provider) — marks each entry as native , openai-compatible , or unsupported so catalog breadth is not confused with transport coverage. - catalogSnapshotSchema (JSON Schema, public contract), catalogSource() (provenance + generatedAt for staleness). Minimal example Common patterns - Rank candidates by cost and fall back on errors: compose createRouter with createFallbackAdapter . - A/B providers without users: or . - Test without keys: pair recordingAdapter + replayAdapter ( ). Related packages - — the AdapterFactory contract lives here. - - Source - npm: https://www.npmjs.com/package/@agentskit/adapters - repo: https://github.com/AgentsKit-io/agentskit/tree/main/packages/adapters"
     },
     {
       "id": "angular",

.github/workflows/models-dev-catalog.yml

@@ -0,0 +1,23 @@
+name: models.dev catalog freshness
+
+on:
+  schedule:
+    - cron: '15 3 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  freshness:
+    name: Compare committed catalog with models.dev
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 1
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: 22
+      - name: Check snapshot freshness and upstream drift
+        run: node scripts/check-models-dev-freshness.mjs --live --max-age-days 35

apps/docs-next/content/docs/data/providers/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Providers
-description: 25 native chat and embedder adapters, plus higher-order adapters that compose candidates. Separate from the 140-provider models catalog.
+description: 25 native chat and embedder adapters, plus higher-order adapters that compose candidates. Separate from the 184-provider models.dev catalog.
 ---
 
 ## Taxonomy
@@ -9,7 +9,7 @@ description: 25 native chat and embedder adapters, plus higher-order adapters th
 | --- | --- | --- |
 | **Native adapters** | 25 (verified) | First-class packages/factories in `@agentskit/adapters` (hosted + local + embedders + higher-order) |
 | **Hosted chat factories** | 17 listed below | Managed-LLM entry points you import by name |
-| **Catalog providers** | 140 (verified) | Broader models.dev-style catalog surface used in ecosystem stats |
+| **Catalog providers** | 184 (verified) | Broader models.dev catalog surface used in ecosystem stats |
 
 Numbers on this site always mean one of those layers — never mix them without a label.
 

apps/docs-next/content/docs/for-agents/adapters.mdx

@@ -100,7 +100,9 @@ npm install @agentskit/adapters
 Data-driven provider/model metadata adapted from `models.dev`, cached
 as a committed snapshot. Large, so it ships only via the `./catalog`
 subpath — never bundled into the main entry. The runtime never fetches
-`models.dev`; regenerate with `pnpm sync:models` and commit the diff.
+`models.dev`; regenerate with `pnpm sync:models` and commit the diff. The
+snapshot carries a normalized content hash and ETag, while scheduled CI checks
+freshness and upstream drift.
 
 - `getProvider`, `getModel`, `listProviders`,
   `listOpenAICompatibleProviders` — query the catalog.
@@ -114,6 +116,9 @@ subpath — never bundled into the main entry. The runtime never fetches
 - `applyOverrides(snapshot, { allowedProviders, disabledProviders, allowedModels })`
   — local policy without forking the catalog.
 - `detectCatalogDrift()` — CI guard; flags undispatchable providers.
+- `classifyCatalogProvider(provider)` — marks each entry as `native`,
+  `openai-compatible`, or `unsupported` so catalog breadth is not confused with
+  transport coverage.
 - `catalogSnapshotSchema` (JSON Schema, public contract),
   `catalogSource()` (provenance + `generatedAt` for staleness).
 

apps/docs-next/content/docs/reference/packages/adapters.mdx

@@ -39,7 +39,7 @@ The important part is not the constructor itself, but that the rest of your stac
 
 The `@agentskit/adapters/catalog` subpath: data-driven provider/model metadata adapted from [`models.dev`](https://models.dev) into AgentsKit's own JSON Schema and cached as a committed snapshot. Broad, current coverage lands via a version bump instead of bespoke per-provider code.
 
-The snapshot is large (thousands of models), so it ships **only** via the `./catalog` subpath — the main `@agentskit/adapters` bundle is unaffected.
+The snapshot is large (thousands of models), so it ships **only** via the `./catalog` subpath — the main `@agentskit/adapters` bundle is unaffected. The current committed snapshot covers 184 providers and 6,293 models; those counts are regenerated from the artifact rather than hand-maintained.
 
 ```ts
 import {
@@ -61,10 +61,11 @@ const adapter = dispatchFromCatalog({
 })
 ```
 
-**No runtime fetch.** The runtime loads the committed snapshot; it never calls `models.dev`. If `models.dev` ever disappears, the last snapshot keeps working. Regenerate on demand (run monthly) and commit the diff:
+**No runtime fetch.** The runtime loads the committed snapshot; it never calls `models.dev`. If `models.dev` ever disappears, the last snapshot keeps working. Refresh it with `pnpm sync:models`; the snapshot includes a normalized content hash and upstream ETag. A scheduled CI check compares the committed hash with the live source and fails when the snapshot is older than 35 days or has drifted:
 
 ```bash
 pnpm sync:models   # fetch → normalize → emit packages/adapters/src/catalog/snapshot.json
+pnpm check:models  # offline freshness check for local/normal CI
 ```
 
 The snapshot carries `generatedAt` + a pinned `source.version` (`catalogSource()`) so you can reason about staleness. **Pricing/limits are advisory cached metadata**, not a hard contract.
@@ -76,7 +77,7 @@ const { cost, source, stale } = await resolveCost('openai', 'o3', { live: true }
 // source: 'live' | 'cache'  ·  stale: true when the snapshot is > 30 days old
 ```
 
-**Policy overrides** (`applyOverrides`) constrain the catalog without forking it (allowed/disabled providers, per-provider model allow-lists). **Drift** (`detectCatalogDrift`) flags any snapshot provider that is neither first-class nor OpenAI-compatible — wire it into CI so a regenerated snapshot can't ship an unroutable provider silently.
+**Policy overrides** (`applyOverrides`) constrain the catalog without forking it (allowed/disabled providers, per-provider model allow-lists). **Drift** (`detectCatalogDrift`) flags any snapshot provider that is neither first-class nor OpenAI-compatible — wire it into CI so a regenerated snapshot can't ship an unroutable provider silently. `classifyCatalogProvider(provider)` exposes the explicit `native` / `openai-compatible` / `unsupported` matrix so catalog breadth is never confused with transport coverage.
 
 The catalog schema (`catalogSnapshotSchema`, JSON Schema) is the public contract; the snapshot is validated against it at build time.
 

apps/docs-next/lib/ecosystem-claims.snapshot.json

@@ -59,9 +59,9 @@
         },
         {
           "id": "catalog-providers",
-          "value": 140,
+          "value": 184,
           "noun": "providers",
-          "conservativeFloor": 140,
+          "conservativeFloor": 180,
           "evidence": {
             "type": "repository-derivation",
             "repo": "AgentsKit-io/agentskit",
@@ -71,9 +71,9 @@
         },
         {
           "id": "catalog-models",
-          "value": 5162,
+          "value": 6293,
           "noun": "models",
-          "conservativeFloor": 5000,
+          "conservativeFloor": 6000,
           "evidence": {
             "type": "repository-derivation",
             "repo": "AgentsKit-io/agentskit",