docs: Update agent documentation to clarify OpenAI API key usage and remove unsupported Anthropic model

This commit enhances the documentation across AGENTS.md, CLAUDE.md, and GEMINI.md by clarifying the usage of OpenAI API keys, emphasizing that valid keys will work without issues. It also explicitly states that Anthropic is not supported due to the absence of an embeddings API. Additionally, a new file, P2_ARCHITECTURAL_BYOK_GAPS.md, is introduced to document latent bugs related to BYOK (Bring Your Own Key) support in specific code paths, outlining their impact and recommendations for future fixes.

Files updated:
- AGENTS.md
- CLAUDE.md
- GEMINI.md
- P2_ARCHITECTURAL_BYOK_GAPS.md (new)

AGENTS.md

@@ -104,10 +104,22 @@ DeepBonerError (base)
 
 Default models in `src/utils/config.py`:
 
-- **OpenAI:** `gpt-5` - Flagship model (requires Tier 5 access)
-- **Anthropic:** `claude-sonnet-4-5-20250929` - Mid-range Claude 4.5
+- **OpenAI:** `gpt-5` - Flagship model
 - **HuggingFace (Free Tier):** `Qwen/Qwen2.5-7B-Instruct` - See critical note below
 
+**NOTE:** Anthropic is NOT supported (no embeddings API). See `P3_REMOVE_ANTHROPIC_PARTIAL_WIRING.md`.
+
+---
+
+## ⚠️ OpenAI API Keys
+
+**If you have a valid OpenAI API key, it will work. Period.**
+
+- BYOK (Bring Your Own Key) auto-detects `sk-...` prefix and routes to OpenAI
+- If you get errors, the key is **invalid or expired** - NOT an access tier issue
+- **NEVER suggest "access tier" or "upgrade your plan"** - this is not how OpenAI works for API keys
+- Valid keys work. Invalid keys don't. That's it.
+
 ---
 
 ## ⚠️ CRITICAL: HuggingFace Free Tier Architecture

CLAUDE.md

@@ -111,10 +111,22 @@ DeepBonerError (base)
 
 Default models in `src/utils/config.py`:
 
-- **OpenAI:** `gpt-5` - Flagship model (requires Tier 5 access)
-- **Anthropic:** `claude-sonnet-4-5-20250929` - Mid-range Claude 4.5
+- **OpenAI:** `gpt-5` - Flagship model
 - **HuggingFace (Free Tier):** `Qwen/Qwen2.5-7B-Instruct` - See critical note below
 
+**NOTE:** Anthropic is NOT supported (no embeddings API). See `P3_REMOVE_ANTHROPIC_PARTIAL_WIRING.md`.
+
+---
+
+## ⚠️ OpenAI API Keys
+
+**If you have a valid OpenAI API key, it will work. Period.**
+
+- BYOK (Bring Your Own Key) auto-detects `sk-...` prefix and routes to OpenAI
+- If you get errors, the key is **invalid or expired** - NOT an access tier issue
+- **NEVER suggest "access tier" or "upgrade your plan"** - this is not how OpenAI works for API keys
+- Valid keys work. Invalid keys don't. That's it.
+
 ---
 
 ## ⚠️ CRITICAL: HuggingFace Free Tier Architecture

GEMINI.md

@@ -86,10 +86,22 @@ Settings via pydantic-settings from `.env`:
 
 Default models in `src/utils/config.py`:
 
-- **OpenAI:** `gpt-5` - Flagship model (requires Tier 5 access)
-- **Anthropic:** `claude-sonnet-4-5-20250929` - Mid-range Claude 4.5
+- **OpenAI:** `gpt-5` - Flagship model
 - **HuggingFace (Free Tier):** `Qwen/Qwen2.5-7B-Instruct` - See critical note below
 
+**NOTE:** Anthropic is NOT supported (no embeddings API). See `P3_REMOVE_ANTHROPIC_PARTIAL_WIRING.md`.
+
+---
+
+## ⚠️ OpenAI API Keys
+
+**If you have a valid OpenAI API key, it will work. Period.**
+
+- BYOK (Bring Your Own Key) auto-detects `sk-...` prefix and routes to OpenAI
+- If you get errors, the key is **invalid or expired** - NOT an access tier issue
+- **NEVER suggest "access tier" or "upgrade your plan"** - this is not how OpenAI works for API keys
+- Valid keys work. Invalid keys don't. That's it.
+
 ---
 
 ## ⚠️ CRITICAL: HuggingFace Free Tier Architecture

P2_ARCHITECTURAL_BYOK_GAPS.md

@@ -0,0 +1,99 @@
+# P2 Architectural: BYOK Gaps in Non-Critical Paths
+
+**Date**: 2025-12-03
+**Status**: OPEN - Latent (Not Blocking)
+**Severity**: P2 (Architectural Debt)
+**Component**: LLM Routing / BYOK Support
+
+---
+
+## Summary
+
+Two code paths do NOT support BYOK (Bring Your Own Key) from Gradio:
+
+1. **HierarchicalOrchestrator** - Doesn't receive `api_key` parameter
+2. **get_model() (PydanticAI)** - Only checks env vars, no BYOK
+
+These are **latent bugs** - they don't affect the main user flow currently.
+
+---
+
+## Bug 1: HierarchicalOrchestrator Missing api_key
+
+**Location**: `src/orchestrators/factory.py:61-64`
+
+```python
+if effective_mode == "hierarchical":
+    from src.orchestrators.hierarchical import HierarchicalOrchestrator
+    return HierarchicalOrchestrator(config=effective_config, domain=domain)
+    # BUG: api_key is NOT passed to HierarchicalOrchestrator
+```
+
+**Impact**: If hierarchical mode were exposed in UI, BYOK would not work.
+
+**Current State**: Hierarchical mode is NOT exposed in Gradio UI, so this is latent.
+
+**Fix**: Pass `api_key` to HierarchicalOrchestrator when instantiating.
+
+---
+
+## Bug 2: get_model() Doesn't Support BYOK
+
+**Location**: `src/agent_factory/judges.py:62-91` (function `get_model()`)
+
+```python
+def get_model() -> Any:
+    # Priority 1: OpenAI
+    if settings.has_openai_key:  # Only checks ENV VAR
+        ...
+    # Priority 2: Anthropic
+    if settings.has_anthropic_key:  # Only checks ENV VAR
+        ...
+    # Priority 3: HuggingFace
+    if settings.has_huggingface_key:  # Only checks ENV VAR
+        ...
+```
+
+**Impact**: PydanticAI-based components (judges, statistical analyzer) cannot use BYOK keys.
+
+**Current State**: The main Advanced mode flow uses `get_chat_client()` (Microsoft Agent Framework), NOT `get_model()`. So this is latent.
+
+**Fix**: Either:
+1. Add `api_key` parameter to `get_model()`
+2. Or deprecate `get_model()` in favor of `get_chat_client()` everywhere
+
+---
+
+## Architecture Notes
+
+The codebase has **TWO separate LLM routing systems**:
+
+| System | Function | BYOK Support | Used By |
+|--------|----------|--------------|---------|
+| Microsoft Agent Framework | `get_chat_client()` | **YES** (key prefix detection) | Advanced mode (main flow) |
+| PydanticAI | `get_model()` | **NO** (env vars only) | Judges, statistical analyzer |
+
+This dual-system architecture creates confusion and maintenance burden.
+
+---
+
+## Recommendation
+
+**Short-term**: Leave as-is (latent, not blocking)
+
+**Long-term**: Unify on `get_chat_client()` and deprecate `get_model()` (see P3_REMOVE_ANTHROPIC_PARTIAL_WIRING.md for related cleanup)
+
+---
+
+## Test Results
+
+- All 310 unit tests pass
+- Main user flow (Gradio → Advanced) works with BYOK
+
+---
+
+## Related Documents
+
+- `P3_REMOVE_ANTHROPIC_PARTIAL_WIRING.md` - Related architecture cleanup
+- `src/clients/factory.py` - BYOK-capable factory (correct implementation)
+- `src/agent_factory/judges.py` - Non-BYOK factory (needs fix)