diff --git a/docs/v3/contributing/configuration.mdx b/docs/v3/contributing/configuration.mdx
index 0c073a56..384c7841 100644
--- a/docs/v3/contributing/configuration.mdx
+++ b/docs/v3/contributing/configuration.mdx
@@ -197,6 +197,21 @@ Because provider params live on each model config, background workers such as
 the Deriver and Dreamer can use longer request timeouts while synchronous
 chat paths keep tighter defaults.
 
+`timeout` gotchas:
+
+- The value is validated **at config load**: it must coerce to a positive,
+  finite number of seconds (numbers or numeric strings like `"3600"`), or the
+  process refuses to start with an error naming the offending config path.
+  This applies to both the primary model config and its `fallback.overrides`.
+- The unit is always **seconds**, regardless of transport. OpenAI and
+  Anthropic receive it as the SDK's `timeout` kwarg; Gemini has no such
+  kwarg, so Honcho converts it to milliseconds on `http_options.timeout`.
+- When unset, nothing is forwarded and each SDK's default applies — adding
+  this key is opt-in and changes no existing behavior.
+- A too-tight timeout doesn't fail once: the aborted request goes through the
+  normal retry/fallback chain before the caller sees an error, so the
+  observed latency is several multiples of the timeout.
+
 #### Transport passthrough keys
 
 Three keys inside `provider_params` are recognized as request-level escape hatches and forwarded to the underlying transport. Where a transport actually validates and merges one of these keys, its value must be a mapping — a non-mapping value raises a configuration error (see the per-transport behavior below; a key a transport ignores is not validated):