diff --git a/config/default.yaml b/config/default.yaml
index d6ff6e7..9c04420 100644
--- a/config/default.yaml
+++ b/config/default.yaml
@@ -11,14 +11,57 @@ server:
   port: 18800
 
 models:
+  # ── Model tiers ────────────────────────────────────────────────────
+  # Each tier (default, fast, complex, local) defines a primary model.
+  # When an Anthropic tier fails, Flynn automatically tries the same
+  # model via GitHub Models before falling through to the global chain.
+  #
+  # You can override auto-fallback with an inline `fallback:` block:
+  #
+  #   default:
+  #     provider: anthropic
+  #     model: claude-sonnet-4-20250514
+  #     fallback:                          # ← inline per-tier fallback
+  #       provider: openai
+  #       model: gpt-4o
+  #
+  # ── Fallback order ─────────────────────────────────────────────────
+  # 1. Primary client for the tier
+  # 2. Auto same-model fallback via GitHub Models (Anthropic tiers only,
+  #    skipped when an inline `fallback:` block is present)
+  # 3. Inline `fallback:` client (if configured)
+  # 4. Global fallback_chain (tried in order)
+  #
   default:
     provider: anthropic
     model: claude-sonnet-4-20250514
   local:
     provider: ollama
     model: llama3.2:1b
+
+  # ── Global fallback chain ──────────────────────────────────────────
+  # Entries can be tier names (default, fast, complex, local) or keys
+  # from local_providers below. Tried in order after per-tier fallbacks
+  # are exhausted.
   fallback_chain: [local]
 
+  # ── Named providers (optional) ─────────────────────────────────────
+  # Define additional providers that can be referenced by name in
+  # fallback_chain. Useful for secondary API accounts or self-hosted
+  # endpoints that aren't tied to a specific tier.
+  #
+  # local_providers:
+  #   openrouter-backup:
+  #     provider: openrouter
+  #     model: anthropic/claude-sonnet-4
+  #   ollama-big:
+  #     provider: ollama
+  #     model: llama3.1:70b
+  #     endpoint: http://gpu-server:11434
+  #
+  # Then reference them in fallback_chain:
+  #   fallback_chain: [openrouter-backup, ollama-big, local]
+
 hooks:
   confirm:
     - shell.*