Add composite group route registry

docs/COMPOSITE_GROUPS.md

@@ -2,7 +2,8 @@
 
 Composite groups are an admin routing layer for API keys that should choose a
 concrete provider from the requested model instead of binding the key to a
-single provider group.
+single provider group. They support both built-in model detection and an
+admin-configured model route registry for public model aliases.
 
 ## Supported Providers
 
@@ -18,7 +19,41 @@ The selected concrete platform is used for account selection, user platform
 quota checks, post-usage billing, ops error platform attribution, channel
 mapping/pricing lookup, and platform usage reporting.
 
-## Model Detection
+## Route Registry
+
+Admins can configure routes on a composite group from the group list's
+`Routes` action or through the admin API:
+
+- `GET /api/v1/admin/groups/:id/composite-routes`
+- `POST /api/v1/admin/groups/:id/composite-routes`
+- `PUT /api/v1/admin/groups/:id/composite-routes/:route_id`
+- `DELETE /api/v1/admin/groups/:id/composite-routes/:route_id`
+- `POST /api/v1/admin/groups/:id/composite-routes/preview`
+
+Each route belongs to one composite group and contains:
+
+- `public_model`: model identifier the client sends.
+- `match_type`: `exact` or `prefix`.
+- `target_platform`: concrete provider platform.
+- `upstream_model`: model identifier sent upstream. If omitted, the public
+  model is reused.
+- `endpoint`: `any`, `messages`, `count_tokens`, `responses`,
+  `chat_completions`, `embeddings`, `images`, or `gemini`.
+- `priority`: lower values win after match specificity.
+- `enabled`: disabled routes are ignored by runtime resolution but remain
+  visible to admins.
+
+Resolution order is explicit route first, then built-in detection. When more
+than one explicit route matches, exact matches beat prefix matches,
+endpoint-specific routes beat `any`, longer prefixes beat shorter prefixes,
+then lower `priority`, then lower route id.
+
+For JSON-body endpoints, the gateway rewrites the request `model` field to the
+route's `upstream_model` before dispatch. For Gemini native paths such as
+`/v1beta/models/{model}:generateContent`, the gateway resolves `{model}` and
+the handler forwards the resolved upstream model.
+
+## Built-In Detection
 
 Composite routing detects common public model IDs and provider-prefixed IDs:
 
@@ -34,6 +69,7 @@ guessing a provider.
 ## Admin Workflows
 
 - Admins can create a group with platform `composite`.
+- Admins can add, edit, delete, and preview composite model routes.
 - Composite groups can copy accounts from concrete provider groups.
 - Concrete provider accounts can be assigned directly to composite groups from
   account create/edit and bulk account workflows.
@@ -43,7 +79,7 @@ guessing a provider.
 
 ## Limits
 
-Composite groups are not a full OpenRouter-compatible model registry. They do
-not add a provider/model mapping database, per-model admin routing overrides, or
-arbitrary third-party provider prefixes. Add those explicitly before relying on
-custom model IDs that cannot be detected from their names.
+Composite routes choose a concrete provider and upstream model; they do not
+create synthetic model metadata, pricing, or upstream capability records by
+themselves. Keep channel pricing/model mapping configured for the concrete
+provider platforms that the routes target.