From 07ad1418e0f6365ddc5ef5174fd1b4eb345efa11 Mon Sep 17 00:00:00 2001
From: Alex Clarke <alex.j.tusa@gmail.com>
Date: Tue, 21 Jul 2026 10:43:35 -0600
Subject: [PATCH] docs: Reordered Clients OAuth docs

---
 Clients.md | 27 +++++++++++++--------------
 1 file changed, 13 insertions(+), 14 deletions(-)

diff --git a/Clients.md b/Clients.md
index aa87af1..4b8eaed 100644
--- a/Clients.md
+++ b/Clients.md
@@ -238,15 +238,6 @@ clients:
       flow: client_credentials
 ```
 
-### Providers with Bundled OAuth Defaults
-
-Coyote ships OAuth defaults for the following providers, so you only need `auth: oauth` in your config:
-
-* **xAI:** SuperGrok / X Premium+ subscribers
-
-To bundle defaults for additional providers locally, edit your `models.yaml` (see [Local Models Override](#local-models-override))
-and add an `oauth:` block under the provider entry.
-
 ### client_credentials Flow
 
 For headless machine-to-machine (M2M) authentication (i.e. no browser, no user interaction), set `flow: client_credentials`
@@ -259,7 +250,7 @@ non-interactive environments.
 
 ### Device Authorization Grant (Device Flow, RFC 8628)
 
-For CLIs and headless environments — no browser callback required. Coyote displays a short
+For CLIs and headless environments; no browser callback required. Coyote displays a short
 `user_code` and a `verification_uri`. You visit the URL on any device (your phone, another
 computer, or the same browser Coyote tries to open) and enter the code to approve. Coyote
 polls the token endpoint until you approve or the code expires.
@@ -277,9 +268,8 @@ To enable, set `flow: device_code` in your `oauth:` block and provide a `device_
           token_url: https://auth.example.com/oauth/token
           flow: device_code
 
-**Optional:** some providers require PKCE with device flow (per draft-ietf-oauth-device-flow §5.4).
-Set `use_pkce_in_device_flow: true` to opt in — Coyote generates a fresh `code_verifier` and
-`code_challenge` (S256) on each authentication.
+**Optional:** some providers require PKCE with device flow. Set `use_pkce_in_device_flow: true` to opt
+in. Coyote generates a fresh `code_verifier` and `code_challenge` on each authentication.
 
 Token refresh works the same as the Auth Code + PKCE flow: `refresh_token` is silently
 exchanged for a new `access_token` when the current one expires.
@@ -287,7 +277,7 @@ exchanged for a new `access_token` when the current one expires.
 **Sandbox / headless environments:** when Coyote runs inside a sandbox (`coyote --sandbox`),
 your host OAuth tokens (`~/.cache/coyote/oauth/`) are copied into the container so agents can
 call OAuth-authenticated providers without re-authenticating. If you do need to authenticate
-from inside a sandbox, Device Flow works out of the box — Coyote prints a QR code you can
+from inside a sandbox, Device Flow works out of the box: Coyote prints a QR code you can
 scan with your phone camera to visit the verification URL. Auth Code + PKCE flows (like xAI's)
 generally cannot complete inside a sandbox because they require an inbound callback listener;
 authenticate on the host first and let the token copy carry you through.
@@ -301,6 +291,15 @@ overwrite each other's tokens.
 To prevent accidental collisions, Coyote now rejects configuration files with duplicate `name` values across all
 `clients[]` entries at load time. Fixing the underlying single-namespace layout is future work.
 
+### OpenAI-Compatible Providers with Bundled OAuth Defaults
+
+Coyote ships OAuth defaults for the following providers, so you only need `auth: oauth` in your config:
+
+* **xAI:** SuperGrok / X Premium+ subscribers
+
+To bundle defaults for additional providers locally, edit your `models.yaml` (see [Local Models Override](#local-models-override))
+and add an `oauth:` block under the provider entry.
+
 ## Providers That Support OAuth
 * Claude
 * Gemini