Repository navigation
Improve model-routing discoverability and task-oriented examples #2387
Description
Reader need
"I want a stronger planning model, cheaper agents for smaller tasks, and a way to check which model actually ran."
Current gap
user-docs/features/sessions/model-routing.md already owns the necessary behavior and configuration. It is linked from Capabilities and partway through Choose models and providers, but has no direct entry point from the Use Mecatl index, customization guide, or delegation workflow. Its first example combines aliases, auxiliary slots, categories, and the Jev classifier before a reader completes a small task.
Proposed work
Improve the existing routing page rather than create a competing guide. Add task-oriented entry points for a planning model, routing delegated work by task complexity, and verifying the actual model. Start with the smallest useful configuration; introduce classifier backend choices when the automatic-routing scenario needs them. Make links from relevant client/delegation and operator entry points describe the outcome.
Reader framing
Lead with the desired outcome and configured model policy. A reader should be able to describe a task normally while eligible delegation uses operator defaults and automatic routing. Present explicit model or category selection as an optional control for tasks that need it, rather than something users must specify in every prompt.
Distinguish the model's choice of delegation mechanism from the router's selection of a model for an eligible delegated call. Neither guarantees that every task will be delegated or that every configured category will be used. Show how to inspect what actually ran and how an unavailable or unsuitable route is handled.
Acceptance criteria
- A reader can reach routing from Use Mecatl and delegated-work guidance without knowing the feature name.
- At least one minimal configuration-to-task-to-verification example precedes the comprehensive configuration treatment.
- Session model selection, plan-mode model selection, auxiliary slots, and delegated routing are distinguished without duplicating their full contracts.
- The example explains configuration ownership, provider setup prerequisites, and when an operator must make the change on a remote server.
- The reader can verify the actual delegated provider/model and recognize a fallback; a classifier candidate is not presented as proof of execution.
- The main worked example starts with an ordinary task prompt after policy setup, then verifies the actual selection; users do not need to name a model or category for each task.
- Explicit model/category overrides are clearly optional and explain their effect on automatic routing; do not imply that explicit choices still exercise the classifier.
- Delegation-mode selection and model routing are distinguished, with no promise that the agent always chooses a particular mode or model.
- Existing routing URLs and canonical ownership are preserved.
Tracking
Part of #2386. Follow the parent issue's shared ownership and validation criteria.
Activity