docs: SPEC_16 verified and corrected against codebase

Audit findings corrected:
- simple.py: 778 lines (was 761)
- advanced.py: 488 lines (was 400)
- search_handler.py: 219 lines (was ~150)
- OpenAIChatClient: 25 refs across 5 files (now documented with line numbers)
- Anthropic removal: 46 refs across 6 files (now fully scoped)

New sections added:
- Technical Requirements (BaseChatClient abstract methods verified)
- Required Config Changes (gemini_api_key MUST be added)
- Complete file modification list with line numbers
- Verification checklist for implementer

All line counts and imports verified against actual codebase.

docs/specs/SPEC_16_UNIFIED_CHAT_CLIENT_ARCHITECTURE.md

@@ -4,6 +4,7 @@
 **Priority**: P1 (Architectural Simplification)
 **Issue**: Updates [#105](https://github.com/The-Obstacle-Is-The-Way/DeepBoner/issues/105), [#109](https://github.com/The-Obstacle-Is-The-Way/DeepBoner/issues/109)
 **Created**: 2025-12-01
+**Last Verified**: 2025-12-01 (line counts and imports verified against codebase)
 
 ## Summary
 
@@ -22,19 +23,19 @@ Eliminate the Simple Mode / Advanced Mode parallel universe by implementing a pl
 ```
 User Query
     │
-    ├── Has API Key? ──Yes──→ Advanced Mode (400 lines)
+    ├── Has API Key? ──Yes──→ Advanced Mode (488 lines)
     │                         └── Microsoft Agent Framework
     │                         └── OpenAIChatClient (hardcoded dependency)
     │
-    └── No API Key? ──────────→ Simple Mode (761 lines)
+    └── No API Key? ──────────→ Simple Mode (778 lines)
                                 └── While-loop orchestration
                                 └── Pydantic AI + HuggingFace
 ```
 
 **Problems:**
-1. **Double Maintenance**: 1,161 lines across two systems.
-2. **Namespace Lock-in**: The Advanced Orchestrator is tightly coupled to `OpenAIChatClient`.
-3. **Fragmented Chains**: Using Anthropic requires a "frankstein" chain (Anthropic LLM + OpenAI Embeddings).
+1. **Double Maintenance**: 1,266 lines across two orchestrator systems.
+2. **Namespace Lock-in**: The Advanced Orchestrator is tightly coupled to `OpenAIChatClient` (25 references across 5 files).
+3. **Fragmented Chains**: Using Anthropic requires a "Frankenstein" chain (Anthropic LLM + OpenAI Embeddings).
 4. **Testing Burden**: Two test suites, two CI paths.
 
 ## Proposed Solution: ChatClientFactory
@@ -99,7 +100,7 @@ def get_chat_client(
             api_key=api_key or settings.openai_api_key,
         )
 
-    # Gemini (High Performance Alternative)
+    # Gemini (High Performance Alternative) - REQUIRES config.py update first
     if provider == "gemini" or (provider is None and settings.has_gemini_key):
         from src.clients.gemini import GeminiChatClient
         return GeminiChatClient(
@@ -138,23 +139,114 @@ class AdvancedOrchestrator:
         )
 ```
 
-## Migration Plan
+---
 
-### Phase 1: Neutralize Namespace & Add HuggingFace
-- [ ] Create `src/clients/` package.
-- [ ] Implement `HuggingFaceChatClient` adapter.
-- [ ] Implement `ChatClientFactory`.
-- [ ] Refactor `AdvancedOrchestrator` to use `get_chat_client()`.
-- [ ] Update strict typing to use `BaseChatClient` instead of `OpenAIChatClient`.
+## Technical Requirements
+
+### BaseChatClient Protocol (Verified)
+
+The `agent_framework.BaseChatClient` requires implementing **2 abstract methods**:
+
+```python
+class HuggingFaceChatClient(BaseChatClient):
+    """Adapter for HuggingFace Inference API."""
+
+    async def _inner_get_response(
+        self,
+        messages: list[ChatMessage],
+        **kwargs
+    ) -> ChatResponse:
+        """Synchronous response generation."""
+        ...
+
+    async def _inner_get_streaming_response(
+        self,
+        messages: list[ChatMessage],
+        **kwargs
+    ) -> AsyncIterator[ChatResponseUpdate]:
+        """Streaming response generation."""
+        ...
+```
+
+### Required Config Changes
+
+**BEFORE implementation**, add to `src/utils/config.py`:
+
+```python
+# Settings class additions:
+gemini_api_key: str | None = Field(default=None, description="Google Gemini API key")
+
+@property
+def has_gemini_key(self) -> bool:
+    """Check if Gemini API key is available."""
+    return bool(self.gemini_api_key)
+```
+
+---
+
+## Files to Modify (Complete List)
 
-### Phase 2: Simplify Provider Chain
-- [ ] Remove `Anthropic` references (Issue #110).
-- [ ] (Future) Implement `GeminiChatClient` to support Google's full stack.
+### Category 1: OpenAIChatClient References (25 total)
 
-### Phase 3: Deprecate Simple Mode
-- [ ] Update `src/orchestrators/factory.py` to use unified `AdvancedOrchestrator`.
-- [ ] Delete `src/orchestrators/simple.py`.
-- [ ] Delete `src/tools/search_handler.py`.
+| File | Lines | Changes Required |
+|------|-------|------------------|
+| `src/orchestrators/advanced.py` | 31, 70, 95, 101, 122 | Replace with `get_chat_client()` |
+| `src/agents/magentic_agents.py` | 4, 17, 29, 58, 70, 117, 129, 161, 173 | Change type hints to `BaseChatClient` |
+| `src/agents/retrieval_agent.py` | 5, 53, 62 | Change type hints to `BaseChatClient` |
+| `src/agents/code_executor_agent.py` | 7, 43, 52 | Change type hints to `BaseChatClient` |
+| `src/utils/llm_factory.py` | 19, 22, 35, 38, 42 | Merge into `clients/factory.py` |
+
+### Category 2: Anthropic References (46 total - Issue #110)
+
+| File | Refs | Changes Required |
+|------|------|------------------|
+| `src/agent_factory/judges.py` | 10 | Remove Anthropic imports and fallback |
+| `src/utils/config.py` | 10 | Remove `anthropic_api_key`, `anthropic_model`, `has_anthropic_key` |
+| `src/utils/llm_factory.py` | 10 | Remove Anthropic model creation |
+| `src/app.py` | 12 | Remove Anthropic key detection and UI |
+| `src/orchestrators/simple.py` | 2 | Remove Anthropic mentions |
+| `src/agents/hypothesis_agent.py` | 1 | Update comment |
+
+### Category 3: Files to Delete (Phase 3)
+
+| File | Lines | Reason |
+|------|-------|--------|
+| `src/orchestrators/simple.py` | 778 | Replaced by unified Advanced Mode |
+| `src/tools/search_handler.py` | 219 | Manager agent handles orchestration |
+
+**Total deletion: ~997 lines**
+**Total addition: ~400 lines (new clients)**
+**Net: ~600 fewer lines, single architecture**
+
+---
+
+## Migration Plan
+
+### Phase 1: Neutralize Namespace & Add HuggingFace
+- [ ] Add `gemini_api_key` and `has_gemini_key` to `src/utils/config.py`
+- [ ] Create `src/clients/` package
+- [ ] Implement `HuggingFaceChatClient` adapter (~150 lines)
+- [ ] Implement `ChatClientFactory` (~50 lines)
+- [ ] Refactor `AdvancedOrchestrator` to use `get_chat_client()`
+- [ ] Update type hints in `magentic_agents.py`, `retrieval_agent.py`, `code_executor_agent.py`
+- [ ] Merge `llm_factory.py` functionality into `clients/factory.py`
+
+### Phase 2: Simplify Provider Chain (Issue #110)
+- [ ] Remove Anthropic from `judges.py` (10 refs)
+- [ ] Remove Anthropic from `config.py` (10 refs)
+- [ ] Remove Anthropic from `llm_factory.py` (10 refs)
+- [ ] Remove Anthropic from `app.py` (12 refs)
+- [ ] Update user-facing strings mentioning Anthropic
+- [ ] (Future) Implement `GeminiChatClient` (~200 lines)
+
+### Phase 3: Deprecate Simple Mode (Issue #105)
+- [ ] Update `src/orchestrators/factory.py` to use unified `AdvancedOrchestrator`
+- [ ] Delete `src/orchestrators/simple.py` (778 lines)
+- [ ] Delete `src/tools/search_handler.py` (219 lines)
+- [ ] Update tests to only test Advanced Mode
+- [ ] Archive deleted files to `docs/archive/` for reference
+
+---
 
 ## Why This is "Elegant"
 
@@ -162,8 +254,26 @@ class AdvancedOrchestrator:
 2.  **Dependency Injection**: The specific LLM provider is injected, not hardcoded.
 3.  **Full Stack Alignment**: We prioritize providers (OpenAI, Gemini) that own the whole vertical (LLM + Embeddings), reducing environment complexity.
 
+---
+
+## Verification Checklist (For Implementer)
+
+Before starting implementation, verify:
+
+- [x] `agent_framework.BaseChatClient` exists (verified: `agent_framework._clients.BaseChatClient`)
+- [x] Abstract methods: `_inner_get_response`, `_inner_get_streaming_response`
+- [x] `agent_framework.ChatResponse`, `ChatResponseUpdate`, `ChatMessage` importable
+- [x] `settings.has_openai_key` exists (line 118)
+- [ ] `settings.has_gemini_key` **MUST BE ADDED** (does not exist)
+- [ ] `settings.gemini_api_key` **MUST BE ADDED** (does not exist)
+
+---
+
 ## References
 
 - Microsoft Agent Framework: `agent_framework.BaseChatClient`
 - Gemini API: [Embeddings + LLM](https://ai.google.dev/gemini-api/docs/embeddings)
-- HuggingFace Inference: `huggingface_hub.InferenceClient`
+- HuggingFace Inference: `huggingface_hub.InferenceClient`
+- Issue #105: Deprecate Simple Mode
+- Issue #109: Simplify Provider Architecture
+- Issue #110: Remove Anthropic Provider Support