docs: providers.md, routing a model to a transport

One Tier-2 page owns the routed provider: transports, route order, the
providers/<name>.toml format, the three presets, translation channels, and
how to check a route. architecture.md's Copilot Responses section becomes
the Responses dialect section and links to it. SKILL.md gains one row.

Author: gluck

skills/figaro/SKILL.md

@@ -94,6 +94,7 @@ about changing figaro rather than using it live under
 | [reference/turns.md](reference/turns.md) | Turn ids, the turn-shaped read wire, pagination. |
 | [reference/arias.md](reference/arias.md) | Reading an aria off disk, and the store layout. |
 | [reference/architecture.md](reference/architecture.md) | The three roles, the IR, the form, the RPC wire, the provider layer. |
+| [reference/providers.md](reference/providers.md) | Writing `providers/<name>.toml`, pointing a gateway at a new endpoint, or a model failing on one provider and working on another. |
 | [reference/ui-stream.md](reference/ui-stream.md) | How a conversation reaches a terminal: the read wire, inline freeze, the pager. |
 | [reference/quoting.md](reference/quoting.md) | Quoting a passage into a prompt (`<412.0:23-1180>!`), visual selection, and the pager's `:send` / `:fork` / `:listen` / `:attend`. |
 | [reference/cache-control.md](reference/cache-control.md) | Prompt caching, and overriding it. |

skills/figaro/reference/architecture.md

@@ -369,7 +369,7 @@ Translates IR ↔ Anthropic wire and caches the per-aria wire bytes
   thinking blocks rather than emit unsigned ones.
 - **A stream that closed cleanly is not yet a reply.** Both Anthropic-shaped
   providers (this one and the hand-rolled `internal/provider/anthropic`, which
-  the copilot Messages route rides) run the drained message through
+  the routed `messages` transport rides) run the drained message through
   `provider.CheckCompletion` before it lands. Two faults: no content blocks at
   all, whatever the stop reason; or a stop reason that is not a way of
   finishing. `provider.AnthropicStopReason` is the one table for the wire's
@@ -444,14 +444,16 @@ Translates IR ↔ Anthropic wire and caches the per-aria wire bytes
   flags. `anthropic-beta` does not need `interleaved-thinking` for adaptive
   models.
 
-### Copilot Responses: per-request streams, local history
+### Responses dialect: `internal/provider/responses`
 
-`internal/provider/copilot` routes by the Copilot model catalog's advertised
-endpoints. The Responses route sends the locally reconstructed conversation on
-one WebSocket per request. There is no remote continuation dependency,
-`previous_response_id`, or durable server-side session.
+Which provider and transport a model reaches is decided in
+`internal/provider/routed`; see [providers.md](providers.md). The Responses
+dialect sends the locally reconstructed conversation as one request per turn,
+over a WebSocket or an HTTP SSE stream as the route chose. There is no remote
+continuation dependency, `previous_response_id`, or durable server-side
+session.
 
-- `responses_stream.go` forwards argument deltas immediately and correlates
+- `stream.go` forwards argument deltas immediately and correlates
   calls by call ID, announced item ID, then an **explicit** output index.
   Copilot may re-encrypt item IDs between events; an absent index must not
   accidentally match tool zero. Complete calls can execute while other output
@@ -474,7 +476,8 @@ one WebSocket per request. There is no remote continuation dependency,
   before credential resolution. Astra rejects sampling controls and supports
   `low`, `medium`, `high`, `xhigh`, `max` reasoning effort. Unknown model families
   remain unconstrained; settings are never silently discarded.
-- `wirelog.BeginStream` makes WebSocket attempts visible in `doctor provider`,
+- `wirelog.BeginStream` makes both transports visible in `doctor provider`
+  (method `WS` or `SSE`),
   including while in flight. It records timing, byte/event counts, argument
   deltas, unmatched deltas and terminal status, not headers, argument text,
   opaque identifiers or free-form provider errors. An unknown event increments

skills/figaro/reference/providers.md

@@ -0,0 +1,69 @@
+# Providers: routing a model to a transport
+
+`copilot`, `gateway` and `openrouter` are one provider, `internal/provider/routed`,
+given three different specs. A spec names a host, the headers to send, and how
+to choose a transport for each model. `anthropic` (native OAuth) is separate.
+
+## Transports
+
+| Name | Wire | Endpoint |
+|---|---|---|
+| `messages` | Anthropic Messages | `base_url` + `messages_path` (default `/v1/messages`) |
+| `chat` | OpenAI Chat Completions | `base_url` + `/chat/completions` |
+| `responses` | OpenAI Responses, HTTP SSE | `base_url` + `/responses` |
+| `responses-ws` | OpenAI Responses, WebSocket | `ws(s)://` `base_url` + `/responses` |
+
+## Route order
+
+1. The first `[[routing.rule]]` whose `model` glob matches.
+2. The catalog: `GET base_url + routing.catalog`, then the model's
+   `supported_endpoints`. Preference: `responses-ws` > `responses` > `messages` >
+   `chat`. A `ws:` prefix marks a socket.
+3. `routing.default`.
+4. Otherwise the send is refused, and the error names all three.
+
+## The file: `providers/<name>.toml`
+
+```toml
+base_url      = "http://localhost:4000/v1"
+api_key       = "..."                       # or the provider's env var
+cache_markers = "trusted"                   # chat only; see cache-control.md
+messages_path = "/messages"                 # when base_url already ends in /v1
+headers       = { "X-Team" = "figaro" }     # every request, every transport
+
+[transport_headers.responses]               # one transport only
+"X-Experiment" = "1"
+
+[routing]
+catalog = "/models"                         # optional
+default = "chat"
+
+[[routing.rule]]                            # file rules run before the preset's
+model     = "grok-*"
+transport = "responses"
+```
+
+The provider fails to build, rather than guess, on an unknown transport, a rule
+with no transport, a bad glob, or a spec with no way to route at all.
+
+## Presets
+
+| Provider | Built in | The file adds |
+|---|---|---|
+| `copilot` | catalog `/models`; rule `claude-*` → `messages`; Copilot and identity headers; host from the hush token | rules, headers. `base_url` stays Copilot's own override (`token_mode`, `enterprise_domain`). |
+| `gateway` | default `chat`; credential optional | everything. `base_url` is required; `FIGARO_GATEWAY_BASE_URL` wins over the file. |
+| `openrouter` | default `chat`; OpenRouter host; `anthropic/` model prefix | everything. |
+
+## Translation channels
+
+`chat` writes `<name>`, `messages` writes `<name>-messages`, and both Responses
+transports write `<name>-responses`. The names predate routing, so existing arias
+keep their caches. Entries are translated as they land only when routing is
+static (a default, no catalog, no rules); otherwise they are translated at send
+time, once the model's transport is known.
+
+## Checking a route
+
+`figaro doctor provider --id <id> -j` files Responses streams as `WS` or `SSE`
+and HTTP round-trips by path. `figaro models` lists catalog models that have a
+route.