docs: Audit and fix architecture documentation for accuracy

Verified all architecture docs against actual codebase:

- component-inventory.md: Fixed RetrievalAgent (it's a factory function,
not a class) and WebSearchTool (added dead code warning per issue #134)

- overview.md: Added Status column to Agents table, added RetrievalAgent
with "Not wired" status (see #134)

- agent-tool-state-contracts.md: Added dead code warning for RetrievalAgent
explaining it's implemented but not wired into magentic_agents.py

- workflow-diagrams.md: Fixed Implementation Highlights to show actual
factory pattern (not fake MagenticBuilder code), updated footer to
distinguish Active Agents (4) from Implemented but Not Wired (1)

- production-readiness.md: Removed timeline estimates from Next Steps
sections per style guidelines

All verified against:
- src/agents/magentic_agents.py (factory functions)
- src/agents/retrieval_agent.py (create_retrieval_agent, search_web)
- src/agents/tools.py (line numbers verified)
- src/utils/exceptions.py (exception hierarchy verified)
- src/utils/models.py (data models verified)

docs/architecture/agent-tool-state-contracts.md

@@ -54,6 +54,10 @@ This document defines the exact contracts between agents, tools, and shared stat
 | **ReportAgent** | `magentic_agents.py` | Report synthesis | get_bibliography |
 | **RetrievalAgent** | `retrieval_agent.py` | Web search | search_web |
 
+> **⚠️ Dead Code Warning:** RetrievalAgent is implemented but NOT wired into `magentic_agents.py`.
+> The orchestrator only uses SearchAgent (PubMed, ClinicalTrials, EuropePMC), not web search.
+> See GitHub issue #134 for decision to delete or wire in.
+
 ---
 
 ## Agent Contracts

docs/architecture/component-inventory.md

@@ -170,7 +170,10 @@ else:
 ### `retrieval_agent.py`
 | Component | Type | Description |
 |-----------|------|-------------|
-| `RetrievalAgent` | Class | Evidence retrieval coordination |
+| `create_retrieval_agent()` | Factory | Creates ChatAgent for web search |
+| `search_web` | @ai_function | DuckDuckGo web search tool |
+
+> **Note:** This module is implemented but NOT wired into `magentic_agents.py`. See GitHub issue #134.
 
 ### `hypothesis_agent.py`
 | Component | Type | Description |
@@ -292,7 +295,9 @@ else:
 ### `web_search.py`
 | Component | Type | Description |
 |-----------|------|-------------|
-| Web search | Module | DuckDuckGo integration |
+| `WebSearchTool` | Class | DuckDuckGo integration wrapper |
+
+> **Note:** Used by `search_web` in `retrieval_agent.py`. See GitHub issue #134 for dead code status.
 
 ---
 

docs/architecture/overview.md

@@ -161,12 +161,13 @@ def get_chat_client():
 
 ### Agents (`src/agents/`)
 
-| Agent | File | Role |
-|-------|------|------|
-| SearchAgent | `search_agent.py` | Evidence retrieval |
-| JudgeAgent | `judge_agent.py` | Evidence evaluation |
-| ReportAgent | `report_agent.py` | Report synthesis |
-| HypothesisAgent | `hypothesis_agent.py` | Mechanistic pathway analysis |
+| Agent | File | Role | Status |
+|-------|------|------|--------|
+| SearchAgent | `search_agent.py` | Evidence retrieval | ✅ Active |
+| JudgeAgent | `judge_agent.py` | Evidence evaluation | ✅ Active |
+| ReportAgent | `report_agent.py` | Report synthesis | ✅ Active |
+| HypothesisAgent | `hypothesis_agent.py` | Mechanistic pathway analysis | ✅ Active |
+| RetrievalAgent | `retrieval_agent.py` | Web search (DuckDuckGo) | ⚠️ Not wired (see #134) |
 
 ### Tools (`src/tools/`)
 

docs/architecture/production-readiness.md

@@ -323,22 +323,22 @@ None. The system is functional for demo/research use.
 
 ## Next Steps (If Going to Production)
 
-### Phase 1: Observability (2-3 weeks)
+### Phase 1: Observability
 1. Add OpenTelemetry instrumentation
 2. Emit trace IDs in AgentEvents
 3. Add token counting to LLM clients
 
-### Phase 2: Safety (1-2 weeks)
+### Phase 2: Safety
 1. Add input validation layer
 2. Implement prompt injection detection
 3. Add confidence thresholds for escalation
 
-### Phase 3: Resilience (1-2 weeks)
+### Phase 3: Resilience
 1. Add per-tool circuit breakers
 2. Improve rate limit handling
 3. Add health checks
 
-### Phase 4: Evaluation (2-4 weeks)
+### Phase 4: Evaluation
 1. Create evaluation datasets
 2. Implement meta-evaluation of Judge
 3. Establish quality baselines

docs/architecture/workflow-diagrams.md

@@ -640,39 +640,36 @@ gantt
 
 ## Implementation Highlights
 
-**Simple 4-Agent Setup:**
+**Actual Agent Factory Pattern (from `magentic_agents.py`):**
 ```python
-workflow = (
-    MagenticBuilder()
-    .participants(
-        hypothesis=HypothesisAgent(tools=[background_tool]),
-        search=SearchAgent(tools=[web_search, rag_tool]),
-        analysis=AnalysisAgent(tools=[code_execution]),
-        report=ReportAgent(tools=[code_execution, visualization])
-    )
-    .with_standard_manager(
-        chat_client=AnthropicClient(model="claude-sonnet-4"),
-        max_round_count=15,    # Prevent infinite loops
-        max_stall_count=3      # Detect stuck workflows
-    )
-    .build()
-)
+# Create agents via factory functions
+search_agent = create_search_agent(chat_client, domain, api_key)
+judge_agent = create_judge_agent(chat_client, domain, api_key)
+hypothesis_agent = create_hypothesis_agent(chat_client, domain, api_key)
+report_agent = create_report_agent(chat_client, domain, api_key)
+
+# Each agent is a ChatAgent with specific tools:
+# - SearchAgent: search_pubmed, search_clinical_trials, search_preprints
+# - JudgeAgent: None (LLM-only evaluation)
+# - HypothesisAgent: None (LLM-only generation)
+# - ReportAgent: get_bibliography
 ```
 
 **Current Agent Capabilities:**
-- **HypothesisAgent**: Generates research hypotheses
 - **SearchAgent**: Multi-source search (PubMed, ClinicalTrials, Europe PMC)
 - **JudgeAgent**: Evaluates evidence quality, determines sufficiency
-- **ReportAgent**: Generates final research report
-- **RetrievalAgent**: Web search via DuckDuckGo
+- **HypothesisAgent**: Generates research hypotheses
+- **ReportAgent**: Generates final research report with bibliography
+- **RetrievalAgent**: Web search via DuckDuckGo (⚠️ NOT wired in - see issue #134)
 
 **Manager** (AdvancedOrchestrator) coordinates agent execution and workflow.
 
 ---
 
-**Document Version**: 2.1 (Revised for accuracy)
+**Document Version**: 2.2 (Audited for accuracy)
 **Last Updated**: 2025-12-06
 **Architecture**: Microsoft Magentic Orchestration Pattern
-**Implemented Agents**: 5 (Hypothesis, Search, Judge, Report, Retrieval) + Manager
-**Planned but Not Implemented**: Analysis Agent (code execution removed in PR #130)
+**Active Agents**: 4 (Search, Judge, Hypothesis, Report) + Manager
+**Implemented but Not Wired**: RetrievalAgent (see issue #134)
+**Planned but Not Implemented**: AnalysisAgent (code execution removed in PR #130)
 **License**: MIT