From 1b56beecb1564471761e4a85c572f149a40c206c Mon Sep 17 00:00:00 2001
From: Amolith <amolith@secluded.site>
Date: Tue, 10 Feb 2026 19:59:35 -0700
Subject: [PATCH] docs(config): add supports_developer_role docs

Add note explaining OpenAI's developer role usage for reasoning models
and compatibility issues with OpenAI-compatible endpoints that return
"Incorrect role information" errors. Include configuration example for
custom models with reasoning=true.
---
 README.md           | 7 +++++++
 config.example.toml | 6 ++++++
 2 files changed, 13 insertions(+)

diff --git a/README.md b/README.md
index 9e099f9c162fea4324e17374a77daa55d8f37a7c..f829021a99f2408768024d6807c179258a4c18b9 100644
--- a/README.md
+++ b/README.md
@@ -124,6 +124,13 @@ requires_thinking_as_text = true
 requires_mistral_tool_ids = true
 ```
 
+**Note on `supports_developer_role`:** OpenAI's Responses API uses `role:
+"developer"` instead of `"system"` for reasoning models. Most OpenAI-compatible
+endpoints do not support this and will return "Incorrect role information"
+errors. If your custom model has `reasoning = true` and you encounter this
+error, set `supports_developer_role = false` in the compat section to use
+`"system"` instead.
+
 ### Credentials
 
 Set credentials either via config (above) or environment:
diff --git a/config.example.toml b/config.example.toml
index 77a2a5ac2f52d16330fa4310e0492dbf2cdb69cb..53dc6ae2cc9614a7c516cb4ab5c29ed18ab54a97 100644
--- a/config.example.toml
+++ b/config.example.toml
@@ -63,6 +63,12 @@ cost = { input = 0.59, output = 0.79 }
 context_window = 131072
 max_tokens = 8192
 
+# Compatibility settings for OpenAI-compatible endpoints.
+# If your model has `reasoning = true` and you get "Incorrect role information"
+# errors, add this compat section:
+# [custom_models.groq.compat]
+# supports_developer_role = false
+
 [custom_models.openrouter]
 # OpenRouter API (model aggregation)
 provider = "openrouter"