docs: add architecture diagrams pattern for OOP codebases

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

CHANGELOG.md

@@ -8,6 +8,30 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 
+## [3.11.7] - 2026-01-25
+
+### Added
+
+- **ClawdBot vs Claude Code FAQ** (`guide/ultimate-guide.md:14263`)
+  - New Appendix B: FAQ section addressing community confusion between ClawdBot and Claude Code
+  - Comprehensive comparison table (9 dimensions): interface, audience, use cases, pricing, architecture
+  - Decision tree: when to choose each tool, when to use both together
+  - Early warning note in "Before You Start" section (line 33) to alert readers immediately
+  - Community misconceptions addressed: different architectures, complementary not competitive
+  - Resources: ClawdBot website, GitHub repo, setup guides
+  - Context: Jan 2026 buzz on X/Reddit created confusion ("dominated X timeline over 1-2 months")
+  - Related: ClawdBot is self-hosted chatbot for messaging apps (personal automation, smart home); Claude Code is CLI for developers (terminal/IDE, code generation)
+  - Total additions: +76 lines in guide, +3 lines in reference.yaml
+
+- **Architecture Diagrams as Context (Advanced Pattern)** (`guide/ai-ecosystem.md:1379`)
+  - Pattern documentation for using architecture diagrams in OOP codebases
+  - MCP tools reference: Archy MCP, Mermaid MCP, Blueprint MCP (ArcadeAI)
+  - ACM 2024 research validation for LLM OOP limitations
+  - Recommended workflow: Serena → Archy MCP → Manual inline Mermaid
+  - Use cases: OOP codebases >20 modules, Java/Spring projects with deep polymorphism
+  - Source: [LinkedIn discussion (Jan 2026)](https://www.linkedin.com/posts/tigraff_uml-claude-wibecoding-activity-7420595633826258944-gGO5)
+  - Evaluation report: `claudedocs/resource-evaluations/uml-oop-diagrams-eval.md`
+
 - **AI Traceability & Attribution Guide** (`guide/ai-traceability.md`)
   - Comprehensive documentation on AI code attribution and disclosure (~500 lines)
   - LLVM "Human-in-the-Loop" policy (January 2026): `Assisted-by:` trailer standard
@@ -35,6 +59,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
   - 14 new entries for AI traceability topics
   - Template locations for disclosure files
 
+- **Architecture Diagrams as Context (Advanced Pattern)** (`guide/ai-ecosystem.md:1379`)
+  - Pattern documentation for using architecture diagrams in OOP codebases
+  - MCP tools reference: Archy MCP, Mermaid MCP, Blueprint MCP (ArcadeAI)
+  - ACM 2024 research validation for LLM OOP limitations
+  - Recommended workflow: Serena → Archy MCP → Manual inline Mermaid
+  - Use cases: OOP codebases >20 modules, Java/Spring projects with deep polymorphism
+  - Source: [LinkedIn discussion (Jan 2026)](https://www.linkedin.com/posts/tigraff_uml-claude-wibecoding-activity-7420595633826258944-gGO5)
+  - Evaluation report: `claudedocs/resource-evaluations/uml-oop-diagrams-eval.md`
+
 ## [3.11.6] - 2026-01-24
 
 ### Added

guide/ai-ecosystem.md

@@ -1376,6 +1376,76 @@ Claude Code automatically reads files as needed, but external tools exist for:
 
 - Addy Osmani: [My AI Coding Workflow in 2026](https://addyosmani.com/blog/ai-coding-workflow/) — Discusses context packing as part of a broader AI development workflow
 
+### Architecture Diagrams as Context (Advanced Pattern)
+
+For large OOP codebases, research confirms LLMs struggle with polymorphism and dependency reasoning when processing files in chunks ([ACM 2024](https://dl.acm.org/doi/10.1145/3639474.3640052): "LLMs Still Can't Avoid Instanceof").
+
+**Problem**: File chunking loses structural relationships (class hierarchies, interface implementations, cross-module dependencies).
+
+**Solution**: Include architecture diagrams in project context to provide explicit relationships.
+
+#### Approaches
+
+| Approach | Maintenance | Token Cost | Best For |
+|----------|-------------|------------|----------|
+| **Archy MCP** | Zero (auto-gen) | On-demand | GitHub repos with class hierarchies |
+| **Inline Mermaid** | Manual | 200-500 tokens | Custom architectural views |
+| **PlantUML ref** | Manual | Minimal | Enterprise/IDE integration |
+
+#### MCP Tools for Architecture Visualization
+
+**Archy MCP** (phxdev1, April 2025):
+- Auto-generates Mermaid from GitHub repos or text descriptions
+- Supports: flowcharts, class diagrams, sequence diagrams
+- URL: [pulsemcp.com/servers/phxdev1-archy](https://www.pulsemcp.com/servers/phxdev1-archy)
+
+**Mermaid MCP** (hustcc, 61.4K users):
+- Custom themes, background colors
+- Real-time rendering
+
+**Blueprint MCP** (ArcadeAI):
+- Text descriptions → technical diagrams
+- Async job management
+
+#### Inline Example (CLAUDE.md)
+
+```markdown
+## Architecture Overview
+
+\`\`\`mermaid
+classDiagram
+    class UserService {
+        +authenticate()
+        +getProfile()
+    }
+    class AuthProvider {
+        <<interface>>
+        +validate()
+    }
+    UserService --> AuthProvider
+\`\`\`
+```
+
+#### When to Use
+
+- OOP codebases >20 modules with complex inheritance
+- Java/Spring projects with deep polymorphism
+- When Serena symbol overview is insufficient
+
+#### Recommended Workflow
+
+1. **Try Serena first**: `get_symbols_overview` + `find_symbol` (zero maintenance)
+2. **If insufficient**: Use **Archy MCP** to auto-generate class diagrams
+3. **Last resort**: Manual inline Mermaid for custom views
+
+#### Key Insight
+
+> "Context structure matters more than context size" — Explicit relationships improve LLM reasoning on OOP architectures.
+
+**Source**: [LinkedIn discussion (Jan 2026)](https://www.linkedin.com/posts/tigraff_uml-claude-wibecoding-activity-7420595633826258944-gGO5)
+
+**Note**: Pattern reported on Java/Spring project. Not validated at scale. Alternative Serena + grepai achieves similar results with zero maintenance.
+
 ---
 
 ## Alternative Providers (Community Workarounds)

machine-readable/reference.yaml

@@ -4,7 +4,7 @@
 # Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code
 
 version: "3.11.6"
-updated: "2026-01-24"
+updated: "2026-01-25"
 
 # ════════════════════════════════════════════════════════════════
 # DEEP DIVE - Line numbers in guide/ultimate-guide.md
@@ -260,6 +260,14 @@ deep_dive:
   ai_ecosystem_goose: "guide/ai-ecosystem.md:1116"
   ai_ecosystem_goose_comparison: "guide/ai-ecosystem.md:1132"
   ai_ecosystem_context_packing: "guide/ai-ecosystem.md:1208"
+  # Architecture Diagrams as Context (advanced pattern) - Added 2026-01-25
+  architecture_diagrams_input: "guide/ai-ecosystem.md:1379"
+  architecture_diagrams_mcp_tools:
+    - "Archy MCP: https://www.pulsemcp.com/servers/phxdev1-archy"
+    - "Mermaid MCP: 61.4K users"
+    - "Blueprint MCP (ArcadeAI)"
+  llm_oop_research: "https://dl.acm.org/doi/10.1145/3639474.3640052"
+  architecture_diagrams_source: "https://www.linkedin.com/posts/tigraff_uml-claude-wibecoding-activity-7420595633826258944-gGO5"
   ai_ecosystem_voice_to_text: "guide/ai-ecosystem.md:449"
   ai_ecosystem_alternative_providers: "guide/ai-ecosystem.md:959"
   voice_refine_skill: "examples/skills/voice-refine/SKILL.md"
@@ -279,6 +287,10 @@ deep_dive:
   cowork_workflows: "https://github.com/FlorianBruniaux/claude-cowork-guide/tree/main/workflows"
   cowork_section: "guide/ai-ecosystem.md:760"
   cowork_ultimate_guide: 10759
+  # Appendix
+  appendix_a_file_locations: 14087
+  appendix_b_faq: 14263
+  faq_clawdbot_vs_claudecode: 14265
 
 # ════════════════════════════════════════════════════════════════
 # DECISION TREE (most important - en premier)