Harden composite group product surfaces

docs/COMPOSITE_GROUPS.md

@@ -0,0 +1,49 @@
+# Composite Groups
+
+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.
+
+## Supported Providers
+
+Composite groups can route to these concrete account platforms:
+
+- Anthropic
+- Gemini
+- OpenAI
+- Antigravity
+- Grok
+
+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
+
+Composite routing detects common public model IDs and provider-prefixed IDs:
+
+- `claude-*` and `anthropic/claude-*` route to Anthropic.
+- `gemini-*` and `google/gemini-*` route to Gemini.
+- `gpt-*`, `o*`, `codex-*`, `text-embedding-*`, `dall-e-*`, and
+  `openai/*` route to OpenAI.
+- `grok-*` and `xai/grok-*` route to Grok.
+
+Unknown or ambiguous model names fail closed with a client error instead of
+guessing a provider.
+
+## Admin Workflows
+
+- Admins can create a group with platform `composite`.
+- 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.
+- Channel configuration exposes composite groups in concrete provider sections.
+  The channel `group_ids` payload is still flat; provider-specific model
+  mapping and pricing remain keyed by concrete platform.
+
+## 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.