Add Custom routers documentation page

src/content/docs/agent-platform/inference/custom-routers.mdx

@@ -0,0 +1,126 @@
+---
+title: Custom routers
+description: >-
+  Define a custom router that automatically picks the right model for each task,
+  based on task complexity or rules you write, and use it from the model picker.
+---
+
+Custom routers automatically pick the right model for each task, using routing logic you define. Instead of committing to a single model up front, you set the logic once, and Warp resolves a concrete model each time you send a prompt, based on either task complexity or rules you write.
+
+## Key features
+
+* **Complexity-based routing** - Warp classifies each task's difficulty and routes to the model you mapped to that level.
+* **Rule-based routing** - Write natural-language rules that describe when to use each model.
+* **Any supported model** - Route to any concrete model you have access to, across providers.
+* **Settings or file** - Create a router in settings, or author it as a YAML file that Warp loads automatically.
+* **Team-synced routers** - Admins can share a router with an entire team (Enterprise).
+
+## How it works
+
+A custom router appears in the [model picker](/agent-platform/inference/model-choice/#how-to-change-models) as its own entry, alongside Warp's built-in Auto models and individual models. You select it like any other model.
+
+When you send a prompt, the router resolves to a single concrete model and runs the task on it, just like Warp's built-in Auto models. You can always see which model actually ran.
+
+Warp chooses a model when you start a conversation and keeps using it for the rest of that conversation. Very short, trivial prompts (like a quick "hello") don't lock in the choice.
+
+:::note
+A router always resolves to concrete models that you choose. It can't route to an Auto model or to another router.
+:::
+
+## Routing types
+
+A router uses one of two routing types. You choose the type when you create the router.
+
+### Complexity-based routing
+
+Warp classifies each task as easy, medium, or hard and routes to the model you assigned to that level. You also set a default model, which Warp uses for any level you leave unset or when it can't determine complexity.
+
+Use complexity-based routing to put lower-cost models on simple work and more capable models on harder tasks, without describing tasks yourself.
+
+### Rule-based routing
+
+Rule-based routing routes each task using rules you write. Each rule pairs a classification prompt (a natural-language description of when to use a model, such as "debugging or fixing failing tests") with the model to use when that rule matches.
+
+* Warp evaluates rules from top to bottom, and the first rule that matches wins. Rules higher in the list take precedence over those below.
+* If no rule matches, Warp uses the required default model.
+
+## Create a router in Warp
+
+1. Open **Settings** > **Agents** > **Warp Agent** and find the **Custom Routers** section.
+2. Click **Add router** and enter a name.
+3. Under **Routing type**, choose **Complexity-based** or **Rule-based**.
+4. Configure the routing:
+   * **Complexity-based** - Select a **Default** model, then assign models to **Easy**, **Medium**, and **Hard**.
+   * **Rule-based** - Select a **Default model**, then click **Add rule** for each rule, write a **Classification prompt** describing when to use the model, and select the model. Rules are matched top to bottom, so order them by precedence.
+5. Click **Save**.
+
+Your router now appears in the model picker. Saving also writes a file: use **Open file** to edit it directly, or **Delete** to remove the router.
+
+## Author a router as a file
+
+Custom routers are stored as YAML files in `~/.warp/custom_model_routers/`, with one router per file. Warp loads every file in that directory and reloads automatically when you add, edit, or remove one, with no restart required. Routers you create in settings are saved here too.
+
+Routing targets use the same `model_id` values listed on the [Model choice](/agent-platform/inference/model-choice/#available-models) page. Every target must be a concrete, Warp-supported model. You can't route to an Auto model, another router, or a model from a [custom inference endpoint](/agent-platform/inference/custom-inference-endpoint/).
+
+A complexity router uses `type: complexity`. `default` is required and is used for any bucket you omit:
+
+```yaml title="~/.warp/custom_model_routers/cost-saver.yaml"
+name: Cost saver
+type: complexity
+default: claude-4-6-sonnet-high
+routing:
+  easy: claude-4-5-haiku
+  medium: claude-4-6-sonnet-high
+  hard: claude-4-8-opus-high
+```
+
+A rule-based router uses `type: prompt`. `default` is the required catch-all used when no rule matches, and `routing` is the ordered list of rules:
+
+```yaml title="~/.warp/custom_model_routers/by-task.yaml"
+name: By task
+type: prompt
+default: claude-4-6-sonnet-high
+routing:
+  - description: debugging or fixing failing tests
+    model: claude-4-8-opus-high
+  - description: writing documentation or comments
+    model: gpt-5-5-low
+  - description: simple one-line edits or renames
+    model: claude-4-5-haiku
+```
+
+If a file can't be parsed, Warp shows a non-blocking error identifying the file and skips it; your other routers keep working.
+
+## Use a router
+
+1. In the prompt input, open the model picker by clicking the current model name.
+2. Choose your router from the list.
+
+Your selection persists for future prompts, like any other model choice.
+
+## Team-synced routers
+
+Team admins can create routers that are shared with the whole team, so everyone can use the same routing strategy. Team-synced routers are an Enterprise feature, and only admins can create or edit them.
+
+To create one, an admin:
+
+1. Opens the [Admin Panel](https://app.warp.dev/admin/) and goes to **Models**.
+2. Finds the **Custom Routers** section and clicks **New router**.
+3. Chooses **Complexity-based** or **Rule-based**, sets the models or rules, and clicks **Create**.
+
+Team-synced routers appear in the model picker for every team member, who can select them like any other router.
+
+## Credits and model availability
+
+A custom router resolves to a concrete model, so credit usage matches whichever model the router selects for each task. See [Credits](/support-and-community/plans-and-billing/credits/) for how credits are consumed.
+
+Like Warp's built-in Auto models, custom routers consume Warp credits and don't draw on your own provider keys, even if you've configured [Bring Your Own API Key (BYOK)](/agent-platform/inference/bring-your-own-api-key/). To run a model on your own key, select that model directly instead of a router.
+
+If a router targets a model you don't have access to or that's disabled for your organization, Warp falls back to the router's default model. If no usable model remains, Warp falls back to a built-in default and tells you.
+
+## Related resources
+
+* [Model choice](/agent-platform/inference/model-choice/) — Supported models and `model_id` values, including Warp's built-in Auto models.
+* [Bring Your Own API Key](/agent-platform/inference/bring-your-own-api-key/) — Use your own OpenAI, Anthropic, or Google API keys.
+* [Custom inference endpoint](/agent-platform/inference/custom-inference-endpoint/) — Route Warp through any OpenAI-compatible endpoint.
+* [Admin Panel for teams](/enterprise/team-management/admin-panel/) — Manage team-wide settings, including team-synced routers.

src/content/docs/agent-platform/inference/model-choice.mdx

@@ -7,7 +7,7 @@ description: >-
   auto-select the best model).
 ---
 
-Warp lets you choose from a curated set of large language models to power your agents, or let Warp auto-select the best model for each task. Models from OpenAI, Anthropic, Google, and open source providers are available, with configurable reasoning levels and per-profile defaults.
+Warp lets you choose from a curated set of large language models to power your agents, or let Warp auto-select the best model for each task. Models from OpenAI, Anthropic, Google, and open source providers are available, with configurable reasoning levels and per-profile defaults. You can also define [custom routers](/agent-platform/inference/custom-routers/) that pick a model for each task using your own logic.
 
 ## Available models
 
@@ -57,6 +57,9 @@ All Auto models perform well across all agent workflows and are ideal if you pre
 
 | Model | `model_id` | Variant |
 | --- | --- | --- |
+| Claude Opus 4.8 | `claude-4-8-opus-xhigh` | Default effort |
+| Claude Opus 4.8 | `claude-4-8-opus-high` | High effort |
+| Claude Opus 4.8 | `claude-4-8-opus-max` | Max effort |
 | Claude Opus 4.7 | `claude-4-7-opus-xhigh` | Default effort |
 | Claude Opus 4.7 | `claude-4-7-opus-high` | High effort |
 | Claude Opus 4.7 | `claude-4-7-opus-max` | Max effort |
@@ -122,7 +125,13 @@ You can use the model picker in your prompt input to quickly switch between mode
 <figcaption>Model selector in Warp's input.</figcaption>
 </figure>
 
-To change models, click the displayed model name (for example, _Claude Sonnet 4.5_) to open a dropdown with all supported options. Your selection will automatically persist for future prompts.
+To change models, click the displayed model name (for example, _Claude Sonnet 4.6_) to open a dropdown with all supported options. Your selection will automatically persist for future prompts.
+
+### Custom routers
+
+Beyond the built-in Auto models, you can define your own custom routers that automatically pick a concrete model for each task, based on task complexity or rules you write. Custom routers appear in the model picker alongside Auto and individual models.
+
+See [Custom routers](/agent-platform/inference/custom-routers/) to create one.
 
 ### Model fallback
 

src/content/docs/enterprise/team-management/admin-panel.mdx

@@ -215,6 +215,8 @@ When enabled, agents understand your code patterns, architecture, and convention
 
 Control which LLM models are available to your team and how inference is routed. From the **Models** page, admins can enable or disable individual models and configure [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/) routing through AWS Bedrock.
 
+From the **Models** page, admins can also create team-synced [custom routers](/agent-platform/inference/custom-routers/) that route each task to a model based on complexity or rules. Team-synced routers appear in the model picker for every team member.
+
 **Models with provider-specific data retention requirements**
 
 Some models require data retention from the model provider and are therefore not available under [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr). For Enterprise teams, these models are **disabled by default**. A workspace admin must explicitly enable them before team members can use them.

src/sidebar.ts

@@ -302,6 +302,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [
 							collapsed: true,
 							items: [
 								{ slug: 'agent-platform/inference/model-choice', label: 'Model choice' },
+								{ slug: 'agent-platform/inference/custom-routers', label: 'Custom routers' },
 								'agent-platform/inference/bring-your-own-api-key',
 								{ slug: 'agent-platform/inference/custom-inference-endpoint', label: 'Custom inference endpoint' },
 								{ slug: 'agent-platform/inference/grok-subscription', label: 'SuperGrok subscription' },