code-finder 0.1.0__py3-none-any.whl

claude_context/mode_handler.py

@@ -0,0 +1,1774 @@
+"""
+Documentation Generation Mode Handler
+
+Integrates the three documentation modes (AUTO, INTERACTIVE, HYBRID)
+with the existing Vibe2Doc pipeline.
+"""
+
+import logging
+import json
+import asyncio
+import os
+from pathlib import Path
+from typing import Dict, Any, Optional, List, Tuple, TYPE_CHECKING
+from enum import Enum
+from dataclasses import dataclass, field
+import sys
+import hashlib
+
+from .config import ClaudeContextConfig
+from .embeddings import LocalEmbeddings
+from .indexer import RepositoryIndexer
+from .search import create_hybrid_searcher
+from .context_manager import ExternalContextManager, ContextItem
+from .explorer_with_context import InteractiveExplorerWithContext
+from .repository_adapter import create_repository_adapter
+from .readme_extractor import extract_from_readme, InstallationInfo, CodeExample
+from .synthesis.logic_explainer import LogicExplainer
+
+if TYPE_CHECKING:  # pragma: no cover - type checking only
+    from .synthesis.editor_agent import EditorAgent, EditorReview
+# simple_doc_generator removed - LLM synthesis is now mandatory
+
+logger = logging.getLogger(__name__)
+
+
+class DocumentationMode(Enum):
+    """Documentation generation mode"""
+    GENERATE = "generate"  # Unified mode with optional interactive Q&A
+
+
+@dataclass
+class ModeContext:
+    """Context for documentation generation.
+
+    The two-pass workflow under design stores both the synthesized drafts
+    and (in a future change) the editor-agent revisions.  When the editor
+    stage lands, this context should supply:
+
+    - raw_summaries: first-pass `SYNTHESIZED_*` sections emitted by the LLM
+    - editor_requests: structured critique prompts built from logic summaries
+      and repository evidence
+    - editor_outputs: finalized Markdown that replaces the synthesized drafts
+
+    We only document the contract here; the actual fields will be added when
+    the editor agent module is implemented.
+    """
+    mode: DocumentationMode
+    repository_path: str
+    output_path: str = "./docs"
+    interactive: bool = False  # Enable Q&A session
+
+    # Claude Context components
+    config: Optional[ClaudeContextConfig] = None
+    indexer: Optional[RepositoryIndexer] = None
+    searcher: Optional[Any] = None
+    explorer: Optional[InteractiveExplorerWithContext] = None
+    
+    # External context
+    context_manager: Optional[ExternalContextManager] = None
+    context_files: List[str] = field(default_factory=list)
+    jira_config: Optional[Dict] = None
+    
+    # Q&A session data
+    qa_history: List[Dict] = field(default_factory=list)
+    exploration_complete: bool = False
+    
+    # Generated content
+    documentation_plan: List[str] = field(default_factory=list)
+    generated_docs: Dict[str, str] = field(default_factory=dict)
+    structured_evidence: Dict[str, Any] = field(default_factory=dict)
+    # Synthesis
+    synthesis_enabled: bool = False
+    synthesis_template: Optional[Dict[str, Any]] = None
+    user_focused: bool = False  # Use user-focused questions (quickstart first) vs technical (architecture first)
+
+    # Logic explainer and rationale harvesting
+    logic_explainer: Optional[LogicExplainer] = None
+    logic_summaries: List[Dict[str, Any]] = field(default_factory=list)
+    rationale_records: Dict[str, Any] = field(default_factory=dict)
+
+    # Editor workflow integration (populated when editor pass is enabled)
+    editor_enabled: bool = False
+    editor_agent: Optional["EditorAgent"] = None
+    editor_reviews: List["EditorReview"] = field(default_factory=list)
+    editor_outputs: Dict[str, str] = field(default_factory=dict)
+
+    # Multi-README support (default: discover all READMEs)
+    single_readme_mode: bool = False  # When True, only use root README (legacy behavior)
+
+    # Editor workflow placeholders (see Two-Pass Documentation plan in doc.plan.md).
+    # The upcoming editor agent will attach critique data and revised Markdown
+    # without altering the synthesized drafts.  Fields such as
+    # `editor_feedback` and `editor_docs` will be introduced alongside the
+    # implementation so downstream components can publish the edited versions.
+
+
+class DocumentationModeHandler:
+    """
+    Handles the three documentation generation modes.
+    Bridges Claude Context with the existing Vibe2Doc pipeline.
+    """
+    
+    def __init__(self):
+        """Initialize the mode handler"""
+        self.current_context: Optional[ModeContext] = None
+        logger.info("DocumentationModeHandler initialized")
+    
+    async def initialize_mode(
+        self,
+        repository_path: str,
+        output_path: str = "./docs",
+        interactive: bool = False,
+        context_files: Optional[List[str]] = None,
+        jira_config: Optional[Dict] = None,
+        synthesis: bool = False,
+        synthesis_template: Optional[Dict[str, Any]] = None,
+        user_focused: bool = False,
+        editor_enabled: Optional[bool] = None,
+        single_readme_mode: bool = False,
+    ) -> ModeContext:
+        """
+        Initialize documentation generation.
+
+        Args:
+            repository_path: Path to the repository
+            output_path: Where to save documentation
+            interactive: Enable Q&A session (default: False)
+            context_files: External context files
+            jira_config: Jira configuration
+            synthesis: Enable synthesis (deprecated, always True)
+            synthesis_template: Custom template
+            user_focused: Use user-focused prompts
+            single_readme_mode: Use only root README (legacy behavior). Default: False (multi-README)
+
+        Returns:
+            Initialized ModeContext
+        """
+        logger.info(f"Initializing {'interactive' if interactive else 'automatic'} documentation generation for {repository_path}")
+        
+        # Create context
+        context = ModeContext(
+            mode=DocumentationMode.GENERATE,
+            repository_path=repository_path,
+            output_path=output_path,
+            interactive=interactive,
+            context_files=context_files or [],
+            jira_config=jira_config,
+            synthesis_enabled=True,  # Always enabled
+            synthesis_template=synthesis_template,
+            user_focused=user_focused,
+            single_readme_mode=single_readme_mode
+        )
+
+        env_editor = os.getenv("V2D_ENABLE_EDITOR")
+        editor_flag = editor_enabled
+        if editor_flag is None and env_editor is not None:
+            editor_flag = env_editor.lower() in {"1", "true", "yes", "on"}
+        context.editor_enabled = bool(editor_flag)
+        
+        # Initialize Claude Context components
+        context.config = ClaudeContextConfig()
+        context.config.milvus_db_path = f"./data/{Path(repository_path).name}_milvus.db"
+        
+        # Initialize embeddings
+        embeddings = LocalEmbeddings(context.config.embedding_model)
+        
+        # Initialize indexer
+        from .config import MilvusManager
+        milvus_manager = MilvusManager(context.config)
+        
+        context.indexer = RepositoryIndexer(
+            config=context.config,
+            embeddings=embeddings,
+            milvus_manager=milvus_manager
+        )
+        
+        # Index the repository
+        logger.info("Indexing repository...")
+        adapter = create_repository_adapter(repository_path)
+        stats = await self._index_repository_async(context.indexer, adapter)
+        logger.info(f"Indexed {stats['files_indexed']} files, {stats.get('chunks_created', stats.get('total_chunks', 0))} chunks")
+        
+        # Create searcher
+        context.searcher = create_hybrid_searcher(
+            config=context.config,
+            embeddings=embeddings,
+            milvus_manager=milvus_manager
+        )
+        
+        # Initialize context manager (always available)
+        context.context_manager = ExternalContextManager()
+
+        # Initialize logic explainer for rationale-rich summaries
+        try:
+            context.logic_explainer = LogicExplainer()
+        except Exception as exc:  # pragma: no cover - defensive
+            logger.warning("LogicExplainer initialization failed: %s", exc)
+            context.logic_explainer = None
+
+        # Initialize editor agent (optional second pass)
+        if context.editor_enabled:
+            try:
+                from .synthesis.editor_agent import EditorAgent
+
+                context.editor_agent = EditorAgent(searcher=context.searcher)
+                logger.info("Editor agent initialized (two-pass workflow enabled)")
+            except Exception as exc:  # pragma: no cover - defensive
+                logger.warning("Editor agent initialization failed: %s", exc)
+                context.editor_enabled = False
+
+        # Load context files
+        for file_path in context_files or []:
+            try:
+                context.context_manager.add_file(file_path)
+                logger.info(f"Added context file: {file_path}")
+            except Exception as e:
+                logger.warning(f"Failed to add context file {file_path}: {e}")
+
+        # TODO: Add Jira integration if configured
+        if jira_config:
+            logger.info("Jira integration configured but not yet implemented")
+
+        # Initialize explorer ONLY if interactive mode
+        if interactive:
+            context.explorer = InteractiveExplorerWithContext(
+                searcher=context.searcher,
+                context_manager=context.context_manager,
+                enable_llm_fallback=True  # Enable LLM query interpretation for conceptual questions
+            )
+            logger.info("Interactive mode: Q&A session enabled (with LLM query interpretation)")
+        
+        self.current_context = context
+        return context
+    
+    async def _index_repository_async(self, indexer, adapter):
+        """Async wrapper for repository indexing"""
+        return await asyncio.to_thread(indexer.index_from_adapter, adapter)
+    
+    # AUTO mode removed - LLM synthesis is now mandatory for documentation
+    # Use HYBRID mode for automatic documentation generation
+    
+    async def run_generate_mode(self, context: ModeContext) -> Dict[str, str]:
+        """
+        Run unified documentation generation with optional Q&A.
+
+        Flow:
+        1. Auto-extract evidence (README + code) - ALWAYS
+        2. [Optional] Interactive Q&A session
+        3. Generate documentation with LLM synthesis - ALWAYS
+
+        Args:
+            context: The mode context (includes interactive flag)
+
+        Returns:
+            Generated documentation
+        """
+        mode_label = "interactive" if context.interactive else "automatic"
+        logger.info(f"Running {mode_label} documentation generation...")
+
+        # Show context summary
+        context_summary = context.context_manager.get_summary() if context.context_manager else {}
+        logger.info(f"Using {context_summary.get('total_items', 0)} context items")
+
+        # Phase 1: Auto-extract evidence (ALWAYS)
+        if context.interactive:
+            print("\n🔍 Phase 1: Auto-extracting evidence...")
+
+        structured_evidence = self._collect_structured_evidence(context)
+        # NOTE: The forthcoming editor agent will consume both `structured_evidence`
+        # and `context.generated_docs` to critique the first draft.  Keep these
+        # collections immutable so the second pass can diff against the raw output.
+        context.structured_evidence = structured_evidence
+
+        # Show what was auto-extracted
+        if context.interactive:
+            essentials = structured_evidence.get("essentials", {})
+            print(f"\n✅ Auto-extracted from README:")
+            if essentials.get("installation"):
+                print(f"  ✓ Installation command")
+            if essentials.get("quickstart"):
+                print(f"  ✓ Quickstart example")
+            if essentials.get("authentication"):
+                print(f"  ✓ Authentication setup")
+
+        # Phase 2: Optional Q&A session
+        if context.interactive:
+            if not context.explorer:
+                logger.warning("Interactive mode requested but explorer not initialized")
+            else:
+                print(f"\n" + "="*60)
+                print(f"💬 Phase 2: Interactive Q&A Session")
+                print(f"="*60)
+                print(f"\nAuto-extraction complete. You can now:")
+                print(f"  • Ask questions to add insights")
+                print(f"  • Type 'generate docs' to create documentation")
+                print(f"")
+
+                if not context.exploration_complete:
+                    await self._run_interactive_session(context)
+
+                # Show Q&A summary
+                if context.qa_history:
+                    high_conf = sum(1 for qa in context.qa_history if qa.get("confidence", 0) >= 0.7)
+                    print(f"\n📊 Q&A Summary:")
+                    print(f"  • {len(context.qa_history)} questions asked")
+                    print(f"  • {high_conf} high-confidence answers")
+                    print(f"  • These insights will be incorporated into documentation\n")
+
+        # Phase 3: LLM synthesis (ALWAYS REQUIRED)
+        try:
+            logger.info("🤖 Starting LLM synthesis...")
+            docs = self._run_synthesis_overview(context)
+            logger.info(f"✅ Synthesis completed: {len(docs)} sections generated")
+        except Exception as e:
+            logger.error(f"❌ Synthesis failed: {e}")
+            print(f"\n❌ Error: LLM synthesis failed: {e}")
+            print("\nLLM synthesis is required for documentation generation.")
+            print("Please check:")
+            print("  1. API key is set correctly (ANTHROPIC_API_KEY or OPENAI_API_KEY)")
+            print("  2. API key has sufficient quota")
+            print("  3. Network connectivity")
+            raise RuntimeError(f"Documentation generation failed: {e}") from e
+
+        # Optional Phase 4: Editor pass (second stage)
+        if context.editor_enabled:
+            self._run_editor_pass(context, structured_evidence, docs)
+
+        context.generated_docs = docs
+        return docs
+
+    def _collect_structured_evidence(self, context: ModeContext) -> Dict[str, Any]:
+        """
+        Collect evidence with clear priority tiers (EVIDENCE-FIRST approach).
+
+        Returns structured evidence instead of flat list:
+        - essentials: Installation, quickstart, auth from README (TIER 1 - MANDATORY)
+        - usage: Examples, configuration from README/samples (TIER 2 - HIGH PRIORITY)
+        - implementation: Code analysis, patterns (TIER 3 - SUPPLEMENTARY)
+
+        This ensures README fundamentals appear in docs before code internals.
+        """
+        evidence = {
+            "essentials": {},
+            "usage": {},
+            "implementation": {},
+            "rationale": {
+                "logic": [],
+                "decisions": [],
+                "qa": []
+            }
+        }
+
+        # TIER 1: Extract essentials from README(s) (HIGHEST PRIORITY)
+        # Multi-README discovery: root README for essentials, module READMEs for usage
+        readmes = self._get_readme_contents(context)
+
+        if not readmes:
+            logger.warning("⚠️  No README found - essentials tier will be empty")
+        else:
+            # Determine primary README (root or shallowest if no root)
+            primary_readme_depth = readmes[0]['depth']
+            if primary_readme_depth > 0:
+                logger.warning(f"⚠️  No root README found. Using {readmes[0]['path']} as primary (depth={primary_readme_depth})")
+
+            # Initialize module_readmes list for usage tier
+            evidence["usage"]["module_readmes"] = []
+
+            for readme in readmes:
+                readme_path = readme['path']
+                readme_content = readme['content']
+                depth = readme['depth']
+
+                logger.info(f"📖 Extracting from {readme_path} (depth={depth})...")
+                readme_essentials = extract_from_readme(readme_content)
+
+                if depth == primary_readme_depth:
+                    # PRIMARY README: Extract to essentials tier
+                    # Installation
+                    if readme_essentials.get('installation'):
+                        install_info = readme_essentials['installation']
+                        evidence["essentials"]["installation"] = {
+                            "command": install_info.command,
+                            "requirements": install_info.requirements,
+                            "source": readme_path
+                        }
+                        logger.info(f"  ✅ Installation: {install_info.command}")
+
+                    # Quickstart - EXACT code
+                    if readme_essentials.get('quickstart'):
+                        quickstart = readme_essentials['quickstart']
+                        evidence["essentials"]["quickstart"] = {
+                            "code": quickstart.code,
+                            "language": quickstart.language,
+                            "source": readme_path
+                        }
+                        logger.info(f"  ✅ Quickstart: {len(quickstart.code)} chars of {quickstart.language}")
+
+                    # Authentication
+                    if readme_essentials.get('authentication'):
+                        auth = readme_essentials['authentication']
+                        evidence["essentials"]["authentication"] = {
+                            "code": auth.code,
+                            "language": auth.language,
+                            "source": readme_path
+                        }
+                        logger.info(f"  ✅ Authentication: {len(auth.code)} chars")
+
+                    # All code examples for usage tier
+                    if readme_essentials.get('examples'):
+                        evidence["usage"]["readme_examples"] = [
+                            {
+                                "code": ex.code,
+                                "language": ex.language,
+                                "context": ex.context
+                            }
+                            for ex in readme_essentials['examples']
+                        ]
+                        logger.info(f"  ✅ Examples: {len(readme_essentials['examples'])} found")
+
+                    # Overview/description
+                    if readme_essentials.get('overview'):
+                        evidence["essentials"]["overview"] = readme_essentials['overview']
+                        logger.info(f"  ✅ Overview: {len(readme_essentials['overview'])} chars")
+
+                    # Feature list
+                    if readme_essentials.get('features'):
+                        features = readme_essentials['features']
+                        evidence["essentials"]["features"] = {
+                            "items": features.items,
+                            "section": features.section,
+                            "source": readme_path
+                        }
+                        logger.info(f"  ✅ Features: {len(features.items)} items")
+
+                    # Tables (compatibility matrices, status tables)
+                    if readme_essentials.get('tables'):
+                        evidence["usage"]["tables"] = [
+                            {
+                                "raw_content": t.raw_content,
+                                "headers": t.headers,
+                                "row_count": t.row_count,
+                                "section": t.section,
+                                "has_status_indicators": t.has_status_indicators,
+                                "source": readme_path
+                            }
+                            for t in readme_essentials['tables']
+                        ]
+                        status_tables = sum(1 for t in readme_essentials['tables'] if t.has_status_indicators)
+                        logger.info(f"  ✅ Tables: {len(readme_essentials['tables'])} found ({status_tables} with status indicators)")
+
+                    # Callouts (coming soon, experimental, warnings)
+                    if readme_essentials.get('callouts'):
+                        evidence["usage"]["callouts"] = [
+                            {
+                                "text": c.text,
+                                "callout_type": c.callout_type,
+                                "context": c.context,
+                                "source": readme_path
+                            }
+                            for c in readme_essentials['callouts']
+                        ]
+                        callout_types = set(c.callout_type for c in readme_essentials['callouts'])
+                        logger.info(f"  ✅ Callouts: {len(readme_essentials['callouts'])} found (types: {', '.join(callout_types)})")
+
+                else:
+                    # MODULE README (depth > primary): Add to usage tier
+                    module_data = {
+                        'path': readme_path,
+                        'depth': depth,
+                        'overview': None,
+                        'examples': [],
+                        'features': None,
+                        'tables': []
+                    }
+
+                    # Try structured extraction first
+                    has_structured_data = False
+
+                    if readme_essentials.get('overview'):
+                        module_data['overview'] = readme_essentials['overview']
+                        has_structured_data = True
+
+                    if readme_essentials.get('examples'):
+                        module_data['examples'] = [
+                            {
+                                "code": ex.code,
+                                "language": ex.language,
+                                "context": ex.context
+                            }
+                            for ex in readme_essentials['examples']
+                        ]
+                        has_structured_data = True
+
+                    if readme_essentials.get('features'):
+                        features = readme_essentials['features']
+                        module_data['features'] = {
+                            "items": features.items,
+                            "section": features.section
+                        }
+                        has_structured_data = True
+
+                    if readme_essentials.get('tables'):
+                        module_data['tables'] = [
+                            {
+                                "raw_content": t.raw_content,
+                                "headers": t.headers,
+                                "section": t.section
+                            }
+                            for t in readme_essentials['tables']
+                        ]
+                        has_structured_data = True
+
+                    # RAW-OVERVIEW FALLBACK for module READMEs only
+                    # Only apply if no structured data was extracted
+                    if not has_structured_data:
+                        logger.info(f"  ℹ️  Using raw-overview fallback for {readme_path}")
+                        # Grab first paragraph (up to 1000 chars)
+                        paragraphs = readme_content.split('\n\n')
+                        first_paragraph = ''
+                        for para in paragraphs:
+                            para = para.strip()
+                            # Skip headers and empty lines
+                            if para and not para.startswith('#'):
+                                first_paragraph = para[:1000]
+                                break
+
+                        if first_paragraph:
+                            module_data['overview'] = first_paragraph
+                            module_data['raw_fallback'] = True
+
+                        # Also grab any code blocks as examples
+                        import re
+                        code_block_pattern = r'```(\w*)\n(.*?)```'
+                        code_blocks = re.findall(code_block_pattern, readme_content, re.DOTALL)
+                        for lang, code in code_blocks[:3]:  # Limit to 3 code blocks
+                            module_data['examples'].append({
+                                "code": code.strip()[:500],
+                                "language": lang or "text",
+                                "context": f"From {readme_path}"
+                            })
+
+                    # Only add if we have some content
+                    if module_data['overview'] or module_data['examples']:
+                        evidence["usage"]["module_readmes"].append(module_data)
+                        ex_count = len(module_data['examples'])
+                        fallback_marker = " (raw fallback)" if module_data.get('raw_fallback') else ""
+                        logger.info(f"  ✅ Module README: {readme_path} - overview={bool(module_data['overview'])}, examples={ex_count}{fallback_marker}")
+                    else:
+                        logger.debug(f"  ⏭️  Skipping {readme_path} - no extractable content")
+
+            # Clean up empty module_readmes list
+            if not evidence["usage"]["module_readmes"]:
+                del evidence["usage"]["module_readmes"]
+
+        # TIER 2: Q&A insights (HIGH PRIORITY - User-identified topics)
+        if context.qa_history:
+            logger.info("💬 Collecting Q&A insights...")
+            qa_insights = []
+
+            for qa in context.qa_history:
+                # Only include high-confidence Q&A (>= 0.5)
+                confidence = qa.get("confidence", 0)
+                if confidence >= 0.5:
+                    qa_insights.append({
+                        "question": qa["question"],
+                        "answer": qa["answer"],
+                        "confidence": confidence,
+                        "context_used": qa.get("context_used", False)
+                    })
+
+            if qa_insights:
+                evidence["usage"]["qa_insights"] = qa_insights
+                high_conf_count = sum(1 for qa in qa_insights if qa["confidence"] >= 0.7)
+                logger.info(f"  ✅ Q&A insights: {len(qa_insights)} answers ({high_conf_count} high-confidence)")
+
+        # TIER 2.5: Code docstrings (HIGH PRIORITY - Author's documented intent)
+        if context.indexer and hasattr(context.indexer, 'last_indexed_chunks'):
+            logger.info("📝 Extracting docstrings from code...")
+            docstrings = []
+            chunks = context.indexer.last_indexed_chunks or []
+
+            for chunk in chunks:
+                # Chunks are stored as dictionaries, access via .get()
+                docstring = chunk.get('docstring') if isinstance(chunk, dict) else getattr(chunk, 'docstring', None)
+                if docstring and len(docstring.strip()) > 20:  # Skip trivial docstrings
+                    if isinstance(chunk, dict):
+                        docstrings.append({
+                            "source": chunk.get('file_path', 'unknown'),
+                            "chunk_type": chunk.get('chunk_type', 'code'),
+                            "name": chunk.get('chunk_name', 'unnamed'),
+                            "docstring": docstring.strip(),
+                            "start_line": chunk.get('start_line', 0),
+                            "end_line": chunk.get('end_line', 0),
+                        })
+                    else:
+                        # Fallback for CodeChunk objects
+                        docstrings.append({
+                            "source": getattr(chunk, 'file_path', 'unknown'),
+                            "chunk_type": getattr(chunk, 'chunk_type', 'code'),
+                            "name": getattr(chunk, 'name', 'unnamed'),
+                            "docstring": docstring.strip(),
+                            "start_line": getattr(chunk, 'start_line', 0),
+                            "end_line": getattr(chunk, 'end_line', 0),
+                        })
+
+            # Sort by docstring length (longer = more informative) and limit
+            docstrings.sort(key=lambda d: len(d["docstring"]), reverse=True)
+            docstrings = docstrings[:20]  # Keep top 20 most informative
+
+            if docstrings:
+                evidence["usage"]["docstrings"] = docstrings
+                logger.info(f"  ✅ Docstrings: {len(docstrings)} extracted from code")
+
+        # TIER 3: Code patterns from analysis (SUPPLEMENTARY)
+        if context.searcher:
+            logger.info("🔍 Searching code for implementation patterns...")
+            terms = self._derive_search_terms(context, max_terms=15)
+            code_results = []
+
+            for term in terms[:15]:  # Increased from 10 for better coverage
+                try:
+                    results = context.searcher.search(term, limit=8)  # Increased from 5
+                    for r in results:
+                        code_results.append({
+                            "source": f"{r.file_path}:{r.start_line}-{r.end_line}",
+                            "snippet": (r.content or "").strip()[:600]
+                        })
+                except Exception:
+                    pass
+
+            evidence["implementation"]["code_patterns"] = code_results
+            logger.info(f"  ✅ Found {len(code_results)} code patterns")
+
+        # TIER 4: Rationale (WHY) evidence from decisions, logic explainer, and Q&A
+        rationale = self._collect_rationale_evidence(context)
+        if rationale:
+            evidence["rationale"] = rationale
+
+        logger.info(f"\n📊 Evidence collection complete:")
+        logger.info(f"   TIER 1 (Essentials): {len(evidence['essentials'])} items")
+        logger.info(f"   TIER 2 (Usage): {len(evidence['usage'])} items")
+        logger.info(f"   TIER 2.5 (Docstrings): {len(evidence['usage'].get('docstrings', []))} extracted")
+        logger.info(f"   TIER 3 (Implementation): {len(evidence['implementation'])} items")
+        logger.info(
+            "   TIER 4 (Rationale): %s logic summaries, %s context decisions, %s QA insights",
+            len(evidence["rationale"].get("logic", [])),
+            len(evidence["rationale"].get("decisions", [])),
+            len(evidence["rationale"].get("qa", [])),
+        )
+
+        context.rationale_records = evidence["rationale"]
+        return evidence
+
+    def _run_editor_pass(
+        self,
+        context: ModeContext,
+        structured_evidence: Dict[str, Any],
+        synthesized_docs: Dict[str, str],
+    ) -> None:
+        """Run the optional editor workflow, storing revisions alongside drafts."""
+
+        if not context.editor_agent:
+            logger.info("Editor agent unavailable; skipping editor pass")
+            return
+
+        sections = {
+            name: content
+            for name, content in synthesized_docs.items()
+            if name.startswith("SYNTHESIZED_") and content.strip()
+        }
+
+        if not sections:
+            logger.info("No synthesized sections found for editor pass")
+            return
+
+        logger.info("Editor agent reviewing %d sections", len(sections))
+        reviews = context.editor_agent.review_sections(
+            sections,
+            structured_evidence=structured_evidence,
+            repository_path=context.repository_path,
+        )
+
+        context.editor_reviews = reviews
+        for review in reviews:
+            filename = f"editor/{review.section}"
+            context.editor_outputs[filename] = review.revised_text
+            synthesized_docs[filename] = review.revised_text
+
+        logger.info("Editor pass completed with %d revised sections", len(reviews))
+
+    def _get_readme_content(self, context: ModeContext) -> Optional[str]:
+        """
+        Legacy method: Get only root README content.
+        Used when --single-readme flag is set or for backward compatibility.
+
+        Returns:
+            README markdown content or None
+        """
+        # Try to get from context manager first
+        if context.context_manager:
+            for item in context.context_manager.get_all_context():
+                if 'readme' in item.source.lower():
+                    return item.content
+
+        # Try to read from repository directly
+        repo_path = Path(context.repository_path)
+        for readme_name in ['README.md', 'readme.md', 'Readme.md', 'README.rst']:
+            readme_path = repo_path / readme_name
+            if readme_path.exists():
+                try:
+                    return readme_path.read_text()
+                except Exception as e:
+                    logger.warning(f"Failed to read {readme_path}: {e}")
+
+        return None
+
+    def _get_readme_contents(self, context: ModeContext) -> List[Dict[str, Any]]:
+        """
+        Discover and return all README files in the repository.
+
+        Multi-README discovery with priority tiers:
+        - Root README (depth=0): Used for essentials (installation, quickstart)
+        - Module READMEs (depth>0): Added to usage tier as supplementary evidence
+
+        Returns:
+            List of README dicts with keys: path, content, depth, absolute_path, 
+            size_chars, truncated
+        """
+        # Legacy mode: only return root README
+        if getattr(context, 'single_readme_mode', False):
+            readme_content = self._get_readme_content(context)
+            if readme_content:
+                repo_path = Path(context.repository_path)
+                # Find actual README path
+                for readme_name in ['README.md', 'readme.md', 'Readme.md', 'README.rst']:
+                    readme_path = repo_path / readme_name
+                    if readme_path.exists():
+                        return [{
+                            'path': readme_name,
+                            'content': readme_content,
+                            'depth': 0,
+                            'absolute_path': str(readme_path),
+                            'size_chars': len(readme_content),
+                            'truncated': False
+                        }]
+            return []
+
+        # Multi-README discovery mode
+        repo_path = Path(context.repository_path)
+        readmes: List[Dict[str, Any]] = []
+        total_chars = 0
+        seen_paths: set = set()  # Track canonical paths to avoid duplicates from symlinks
+
+        # Load .v2dignore patterns if present
+        v2dignore_patterns = self._load_v2dignore(repo_path)
+
+        # Discover all README files recursively
+        # On case-insensitive filesystems (macOS), rglob may return the same file
+        # multiple times with different case patterns. We normalize to lowercase
+        # for deduplication.
+        for readme_pattern in ['README.md', 'readme.md', 'Readme.md', 'README.rst']:
+            for readme_path in repo_path.rglob(readme_pattern):
+                # Handle symlinks and normalize for case-insensitive deduplication
+                try:
+                    canonical = readme_path.resolve()
+                    # Normalize to lowercase for case-insensitive filesystem deduplication
+                    canonical_lower = str(canonical).lower()
+                    if canonical_lower in seen_paths:
+                        continue
+                    seen_paths.add(canonical_lower)
+                except Exception:
+                    # Skip broken symlinks
+                    continue
+
+                # Calculate depth
+                try:
+                    relative = readme_path.relative_to(repo_path)
+                    depth = len(relative.parts) - 1
+                except ValueError:
+                    continue
+
+                # Skip if too deep (max 4 levels)
+                if depth > 4:
+                    logger.debug(f"Skipping README too deep (depth={depth}): {readme_path}")
+                    continue
+
+                # Skip if in ignored directory
+                if self._should_ignore_readme(readme_path, repo_path, v2dignore_patterns):
+                    logger.debug(f"Skipping ignored README: {readme_path}")
+                    continue
+
+                # Read content
+                try:
+                    content = readme_path.read_text(encoding='utf-8')
+                except Exception as e:
+                    logger.warning(f"Failed to read {readme_path}: {e}")
+                    continue
+
+                # Validate quality
+                if not self._is_valid_readme(content):
+                    logger.debug(f"Skipping low-quality README: {readme_path}")
+                    continue
+
+                # Truncate if oversized (10K char limit per README)
+                truncated = False
+                if len(content) > 10_000:
+                    content = content[:10_000] + "\n\n[... truncated ...]"
+                    truncated = True
+                    logger.info(f"Truncated README > 10K chars: {readme_path}")
+
+                # Check total budget (100K chars max)
+                if total_chars + len(content) > 100_000:
+                    logger.warning(f"Reached 100K char total limit, stopping at {len(readmes)} READMEs")
+                    break
+
+                readmes.append({
+                    'path': str(relative),
+                    'content': content,
+                    'depth': depth,
+                    'absolute_path': str(readme_path),
+                    'size_chars': len(content),
+                    'truncated': truncated
+                })
+                total_chars += len(content)
+
+        # Sort deterministically: depth, then directory priority, then alphabetical
+        readmes.sort(key=lambda r: (
+            r['depth'],
+            self._calculate_directory_priority(r['path']),
+            r['path']
+        ))
+
+        # Limit to 15 READMEs
+        if len(readmes) > 15:
+            logger.warning(f"Found {len(readmes)} READMEs, limiting to 15")
+            readmes = readmes[:15]
+            total_chars = sum(r['size_chars'] for r in readmes)
+
+        # Log summary with token estimate
+        est_tokens = int(total_chars / 1.5)  # Rough estimate: ~1.5 chars per token
+        logger.info(f"📖 Discovered {len(readmes)} README files (max depth=4, limit=15)")
+        logger.info(f"📊 Total README content: {total_chars:,} chars (~{est_tokens:,} tokens)")
+
+        if est_tokens > 60_000:
+            logger.warning(f"⚠️  README content is large ({est_tokens:,} tokens). May impact context budget.")
+
+        for readme in readmes:
+            truncated_marker = " [TRUNCATED]" if readme.get('truncated') else ""
+            logger.info(f"  • {readme['path']} (depth={readme['depth']}, {readme['size_chars']:,} chars{truncated_marker})")
+
+        return readmes
+
+    def _load_v2dignore(self, repo_path: Path) -> List[str]:
+        """
+        Load .v2dignore patterns from repository root.
+
+        Returns list of gitignore-style patterns.
+        """
+        v2dignore_path = repo_path / '.v2dignore'
+        patterns: List[str] = []
+
+        if v2dignore_path.exists():
+            try:
+                content = v2dignore_path.read_text()
+                for line in content.splitlines():
+                    line = line.strip()
+                    # Skip empty lines and comments
+                    if line and not line.startswith('#'):
+                        patterns.append(line)
+                logger.info(f"Loaded {len(patterns)} patterns from .v2dignore")
+            except Exception as e:
+                logger.warning(f"Failed to read .v2dignore: {e}")
+
+        return patterns
+
+    def _should_ignore_readme(
+        self, 
+        readme_path: Path, 
+        repo_root: Path,
+        v2dignore_patterns: Optional[List[str]] = None
+    ) -> bool:
+        """
+        Check if README should be ignored based on directory patterns.
+
+        Args:
+            readme_path: Absolute path to README file
+            repo_root: Repository root path
+            v2dignore_patterns: Custom ignore patterns from .v2dignore
+
+        Returns:
+            True if README should be ignored
+        """
+        try:
+            relative = readme_path.relative_to(repo_root)
+            path_str = str(relative)
+        except ValueError:
+            return True  # Not under repo root
+
+        # Hardcoded ignore patterns
+        hardcoded_patterns = [
+            'node_modules/', 'venv/', '.venv/', 'env/',
+            '.git/', '.github/', '.gitlab/',
+            '__pycache__/', '.pytest_cache/', '.mypy_cache/',
+            'dist/', 'build/', 'target/',
+            'vendor/', 'third_party/',
+            '.tox/', '.nox/', '.eggs/',
+            'site-packages/',
+        ]
+
+        for pattern in hardcoded_patterns:
+            if pattern in path_str:
+                return True
+
+        # Check .v2dignore patterns
+        if v2dignore_patterns:
+            import fnmatch
+            for pattern in v2dignore_patterns:
+                # Support both directory patterns and glob patterns
+                if pattern.endswith('/'):
+                    # Directory pattern: match if path contains this directory
+                    if pattern.rstrip('/') in path_str:
+                        return True
+                else:
+                    # Glob pattern: match against relative path
+                    if fnmatch.fnmatch(path_str, pattern) or fnmatch.fnmatch(path_str, f"**/{pattern}"):
+                        return True
+
+        return False
+
+    def _is_valid_readme(self, content: str) -> bool:
+        """
+        Check if README content is substantial enough to include.
+
+        Filters out:
+        - Stub READMEs (< 200 chars)
+        - READMEs with excessive TODOs (likely incomplete)
+
+        Args:
+            content: README file content
+
+        Returns:
+            True if README is valid for inclusion
+        """
+        # Too short (likely a stub)
+        if len(content) < 200:
+            return False
+
+        # Too many TODOs relative to size (likely incomplete/placeholder)
+        todo_count = content.upper().count('TODO')
+        if todo_count > 5 and len(content) < 1000:
+            logger.debug(f"Skipping README with {todo_count} TODOs and < 1000 chars (likely stub)")
+            return False
+
+        return True
+
+    def _calculate_directory_priority(self, path: str) -> int:
+        """
+        Calculate priority score for README based on directory.
+
+        Lower score = higher priority.
+        Used for deterministic sorting when multiple READMEs at same depth.
+
+        Args:
+            path: Relative path to README
+
+        Returns:
+            Priority score (0=highest, 3=lowest)
+        """
+        path_lower = path.lower()
+
+        # Highest priority: common source directories
+        if any(d in path_lower for d in ['src/', 'lib/', 'core/']):
+            return 0
+
+        # Medium priority: package/module directories
+        if any(d in path_lower for d in ['packages/', 'modules/', 'components/']):
+            return 1
+
+        # Lower priority: docs, examples, tests
+        if any(d in path_lower for d in ['docs/', 'examples/', 'tests/']):
+            return 2
+
+        # Default priority
+        return 3
+    
+    def _collect_context_evidence(
+        self,
+        context: ModeContext,
+        limit: int = 5,
+        structured: Optional[Dict[str, Any]] = None
+    ) -> List[Dict[str, str]]:
+        """
+        Legacy method for backward compatibility.
+        Converts structured evidence to flat list format.
+        """
+        structured = structured or self._collect_structured_evidence(context)
+        
+        # Flatten to old format (for now)
+        evidence = []
+        
+        # Add essentials first
+        if structured["essentials"].get("installation"):
+            inst = structured["essentials"]["installation"]
+            evidence.append({
+                "source": f"{inst['source']} (installation)",
+                "snippet": f"Installation: {inst['command']}\nRequirements: {', '.join(inst.get('requirements', []))}"
+            })
+        
+        if structured["essentials"].get("quickstart"):
+            qs = structured["essentials"]["quickstart"]
+            evidence.append({
+                "source": f"{qs['source']} (quickstart)",
+                "snippet": f"```{qs['language']}\n{qs['code']}\n```"
+            })
+        
+        if structured["essentials"].get("authentication"):
+            auth = structured["essentials"]["authentication"]
+            evidence.append({
+                "source": f"{auth['source']} (authentication)",
+                "snippet": f"```{auth['language']}\n{auth['code']}\n```"
+            })
+        
+        # Add usage examples
+        for ex in structured["usage"].get("readme_examples", [])[:3]:
+            evidence.append({
+                "source": f"README ({ex['context']})",
+                "snippet": f"```{ex['language']}\n{ex['code'][:400]}\n```"
+            })
+
+        # Add Q&A insights (TIER 2)
+        for qa in structured["usage"].get("qa_insights", [])[:3]:
+            evidence.append({
+                "source": f"Q&A Session (confidence: {qa['confidence']:.0%})",
+                "snippet": f"Q: {qa['question']}\n\nA: {qa['answer'][:400]}"
+            })
+
+        # Add code patterns last (TIER 3)
+        evidence.extend(structured["implementation"].get("code_patterns", [])[:3])
+
+        return evidence
+
+    def _collect_rationale_evidence(self, context: ModeContext) -> Dict[str, Any]:
+        """Gather rationale-focused evidence (decisions, logic summaries, QA insights)."""
+
+        rationale: Dict[str, Any] = {
+            "logic": [],
+            "decisions": [],
+            "qa": []
+        }
+        rationale_errors: List[str] = []
+        index_payloads: List[Dict[str, Any]] = []
+
+        decision_items: List[ContextItem] = []
+
+        if context.context_manager:
+            for ctx_type in ("decisions", "design_docs", "requirements"):
+                try:
+                    items = context.context_manager.get_all_context(ctx_type)
+                except Exception as exc:  # pragma: no cover - defensive
+                    logger.warning("Failed to read %s context: %s", ctx_type, exc)
+                    rationale_errors.append(f"Context load failed for {ctx_type}: {exc}")
+                    items = []
+                for item in items:
+                    decision_items.append(item)
+                    rationale["decisions"].append({
+                        "id": item.id,
+                        "type": ctx_type,
+                        "summary": item.get_summary(),
+                        "source": item.source,
+                    })
+                    decision_text = (item.content or "")[:2000]
+                    index_payloads.append({
+                        "record_id": f"decision::{item.id}",
+                        "record_type": f"rationale_decision::{ctx_type}",
+                        "text": decision_text or item.get_summary(),
+                        "source_path": item.source or "",
+                        "title": item.get_summary(),
+                    })
+
+        logic_summaries: List[Dict[str, Any]] = []
+        if (
+            context.logic_explainer
+            and context.indexer
+            and getattr(context.indexer, "last_indexed_chunks", None)
+        ):
+            try:
+                logic_summaries = context.logic_explainer.summarize_chunks(
+                    context.indexer.last_indexed_chunks,
+                    decision_items,
+                )
+            except Exception as exc:  # pragma: no cover - defensive
+                logger.warning("LogicExplainer summarization failed: %s", exc)
+                rationale_errors.append(f"LogicExplainer failed: {exc}")
+
+        if logic_summaries:
+            context.logic_summaries = logic_summaries
+            rationale["logic"] = logic_summaries
+            for summary in logic_summaries:
+                text_parts = [
+                    f"Summary: {summary.get('summary', '')}",
+                    f"Why: {summary.get('rationale', '')}",
+                ]
+                if summary.get("trade_offs"):
+                    text_parts.append(f"Trade-offs: {', '.join(summary['trade_offs'])}")
+                if summary.get("side_effects"):
+                    text_parts.append(f"Side-effects: {', '.join(summary['side_effects'])}")
+                index_payloads.append({
+                    "record_id": f"logic::{summary.get('unit_id')}",
+                    "record_type": "rationale_logic",
+                    "text": "\n".join([part for part in text_parts if part]),
+                    "source_path": summary.get("file_path", ""),
+                    "title": summary.get("unit_id", ""),
+                })
+
+        qa_rationale: List[Dict[str, Any]] = []
+        for qa in context.qa_history:
+            rationale_points = qa.get("rationale_points") or []
+            if qa.get("question_type") == "reasoning" or rationale_points:
+                qa_rationale.append({
+                    "question": qa.get("question"),
+                    "answer": qa.get("answer"),
+                    "confidence": qa.get("confidence"),
+                    "rationale_points": rationale_points,
+                })
+                qa_id_seed = (qa.get("question") or "") + (qa.get("answer") or "")
+                note_lines = [f"Question: {qa.get('question','')}", f"Answer: {qa.get('answer','')}"]
+                if rationale_points:
+                    point_notes = [p.get("note") for p in rationale_points if isinstance(p, dict)]
+                    filtered = [p for p in point_notes if p]
+                    if filtered:
+                        note_lines.append("Notes: " + "; ".join(filtered))
+                index_payloads.append({
+                    "record_id": f"qa::{hashlib.sha256(qa_id_seed.encode('utf-8')).hexdigest()[:32]}",
+                    "record_type": "rationale_qa",
+                    "text": "\n".join(note_lines),
+                    "title": qa.get("question", ""),
+                })
+
+        if qa_rationale:
+            rationale["qa"] = qa_rationale
+
+        if rationale_errors:
+            rationale["errors"] = rationale_errors
+
+        if context.indexer and index_payloads:
+            try:
+                context.indexer.upsert_rationale_entries(index_payloads)
+            except Exception as exc:  # pragma: no cover - defensive
+                logger.warning("Failed to index rationale entries: %s", exc)
+                rationale.setdefault("errors", []).append(f"Indexing failed: {exc}")
+
+        return rationale
+
+    def _run_synthesis_overview(self, context: ModeContext) -> Dict[str, str]:
+        """Run synthesis to produce comprehensive documentation files."""
+        try:
+            from .synthesis.llm_synthesizer import LLMSynthesizer
+        except Exception as e:
+            raise RuntimeError("Synthesis module not available. Ensure Phase 3 synthesis is installed.") from e
+
+        # Use provided template, or load universal template as default
+        template_spec = context.synthesis_template
+
+        if not template_spec:
+            # Load universal template as default
+            import yaml
+            from pathlib import Path
+
+            # Find templates directory relative to this file
+            templates_dir = Path(__file__).parent.parent.parent / "templates"
+            universal_template_path = templates_dir / "synthesis_universal.yaml"
+
+            if universal_template_path.exists():
+                try:
+                    with open(universal_template_path, 'r') as f:
+                        template_spec = yaml.safe_load(f)
+                    logger.info(f"📋 Using universal template (5 sections, ~7,700 words)")
+                except Exception as e:
+                    logger.warning(f"Failed to load universal template: {e}")
+                    template_spec = None
+
+            # Fallback to minimal hardcoded template if universal template fails
+            if not template_spec:
+                logger.info("📋 Using minimal fallback template (3 sections)")
+                template_spec = {
+                    "sections": [
+                        {
+                            "name": "Overview",
+                            "instructions": "Explain WHAT the project does and WHY key decisions were made, citing evidence.",
+                            "max_words": 650,
+                            "rules": {
+                                "require_citations": True,
+                                "min_citations": 1,
+                                "citation_style": "[CITE:source]",
+                                "mark_inference": True,
+                                "required_elements": ["Purpose", "Key Components"]
+                            }
+                        },
+                        {
+                            "name": "Architecture",
+                            "instructions": "Describe the system architecture: core modules, data flow, and key dependencies. Cite code locations.",
+                            "max_words": 600,
+                            "rules": {
+                                "require_citations": True,
+                                "min_citations": 2,
+                                "citation_style": "[CITE:source]",
+                                "mark_inference": True,
+                                "required_elements": ["Modules", "Data Flow"]
+                            }
+                        },
+                        {
+                            "name": "API",
+                            "instructions": "Summarize main public interfaces or endpoints discovered in code. Include file:line citations.",
+                            "max_words": 600,
+                            "rules": {
+                                "require_citations": True,
+                                "min_citations": 2,
+                                "citation_style": "[CITE:source]",
+                                "mark_inference": True,
+                                "required_elements": ["Interfaces"]
+                            }
+                        }
+                    ]
+                }
+
+        # EVIDENCE-FIRST APPROACH: Collect structured evidence
+        # This prioritizes README essentials over code internals
+        structured_evidence = self._collect_structured_evidence(context)
+        
+        # Also collect legacy format for backward compatibility
+        context_evidence = self._collect_context_evidence(context, limit=5, structured=structured_evidence)
+        terms = self._derive_search_terms(context, max_terms=8)
+        code_evidence = self._collect_code_evidence(context, terms=terms, per_term=2)
+        
+        logger.info("📊 Evidence collected:")
+        if structured_evidence["essentials"]:
+            logger.info(f"  ✓ Essentials: {list(structured_evidence['essentials'].keys())}")
+        logger.info(f"  ✓ Usage examples: {len(structured_evidence['usage'].get('readme_examples', []))}")
+        logger.info(f"  ✓ Code patterns: {len(structured_evidence['implementation'].get('code_patterns', []))}")
+
+        # Create synthesizer with user_focused flag
+        synthesizer = LLMSynthesizer(user_focused=context.user_focused)
+        sections = synthesizer.synthesize(
+            template_spec=template_spec,
+            code_evidence=code_evidence,
+            context_evidence=context_evidence,
+            structured_evidence=structured_evidence,  # NEW: Pass structured evidence
+            system_prompt=None,  # Uses user-focused prompt if flag is set
+        )
+
+        outputs: Dict[str, str] = {}
+        
+        # Process ALL sections returned by the synthesizer dynamically
+        for section_name, content in sections.items():
+            if content:  # Only add non-empty sections
+                # Convert section name to filename format
+                filename = f"SYNTHESIZED_{section_name.upper().replace(' ', '_')}.md"
+                outputs[filename] = content
+                logger.info(f"✅ Generated synthesis for section: {section_name}")
+        
+        if not outputs:
+            logger.warning("⚠️ No sections were synthesized - check template configuration")
+        
+        return outputs
+
+    def _collect_code_evidence(self, context: ModeContext, terms: Optional[List[str]] = None, per_term: int = 2) -> List[Dict[str, str]]:
+        """Collect top code snippets as evidence using search terms."""
+        evidence: List[Dict[str, str]] = []
+        if not context.searcher:
+            return evidence
+        if not terms:
+            terms = ["api", "service", "auth", "config", "database", "client", "router", "endpoint"]
+        used = set()
+        for term in terms:
+            try:
+                results = context.searcher.search(term, limit=per_term)
+            except Exception:
+                results = []
+            for r in results:
+                key = (r.file_path, r.start_line, r.end_line)
+                if key in used:
+                    continue
+                used.add(key)
+                src = f"{r.file_path}:{r.start_line}-{r.end_line}"
+                snip = (r.content or "").strip()[:800]
+                evidence.append({"source": src, "snippet": snip})
+        return evidence
+
+    def _derive_search_terms(self, context: ModeContext, max_terms: int = 8) -> List[str]:
+        """Derive search terms from repo stats, structure, and recent questions."""
+        terms: List[str] = []
+        # From stats: chunk types
+        try:
+            chunk_types = list((context.indexer.stats or {}).get("chunks_by_type", {}).keys())
+            for ct in chunk_types:
+                if ct:
+                    terms.append(ct.lower())
+        except Exception:
+            pass
+        # From repo structure: common dirs under repo/src
+        try:
+            repo = Path(context.repository_path)
+            candidates = []
+            for name in ["src", "app", "server", "backend", "api"]:
+                p = repo / name
+                if p.exists() and p.is_dir():
+                    candidates.extend([d.name for d in p.iterdir() if d.is_dir()])
+            terms.extend([t for t in candidates if len(t) > 2])
+        except Exception:
+            pass
+        # From Q&A history: keywords from last 5 questions
+        try:
+            for qa in (context.qa_history or [])[-5:]:
+                q = (qa.get("question") or "").lower()
+                for w in q.replace("?", " ").split():
+                    if len(w) > 3 and w.isalpha():
+                        terms.append(w)
+        except Exception:
+            pass
+        # Seed/common terms
+        seed = ["api", "route", "controller", "service", "client", "model", "database", "config", "auth", "main"]
+        terms.extend(seed)
+        # Deduplicate and limit
+        seen = set()
+        unique = []
+        for t in terms:
+            if t not in seen:
+                seen.add(t)
+                unique.append(t)
+        return unique[:max_terms]
+    
+    def _generate_adaptive_questions(self, context: ModeContext) -> List:
+        """
+        Generate adaptive question suggestions based on project type and template.
+        
+        Uses the new adaptive question generator to provide relevant suggestions.
+        Now supports user-focused mode for README-style quickstart questions!
+        
+        Args:
+            context: The mode context with template and repository info
+            
+        Returns:
+            List of GeneratedQuestion objects
+        """
+        from .question_generator import TemplateQuestionGenerator, QuestionFocus
+        
+        # Only generate if we have a synthesis template
+        if not context.synthesis_template:
+            return []
+        
+        # Get README content for better project type detection
+        readme_content = None
+        if context.context_manager:
+            all_items = context.context_manager.get_all_context()
+            readme_items = [
+                item for item in all_items
+                if "readme" in item.source.lower()
+            ]
+            if readme_items:
+                readme_content = readme_items[0].content
+        
+        # Generate adaptive questions with appropriate focus
+        generator = TemplateQuestionGenerator()
+        
+        # Choose focus mode based on user_focused flag
+        focus = QuestionFocus.USER_FOCUSED if context.user_focused else QuestionFocus.TECHNICAL
+        
+        try:
+            questions = generator.generate_questions_from_template(
+                template_spec=context.synthesis_template,
+                repository_path=context.repository_path,
+                readme_content=readme_content,
+                max_questions=10,
+                focus=focus
+            )
+            return questions
+        except Exception as e:
+            logger.warning(f"Could not generate adaptive questions: {e}")
+            return []
+    
+    def _suggest_next_question(self, context: ModeContext) -> Optional[str]:
+        """
+        Suggest the next question based on what's been asked so far.
+        
+        Uses adaptive question generator to find unanswered questions that
+        would help fill gaps in documentation.
+        
+        Args:
+            context: The mode context with Q&A history
+            
+        Returns:
+            Suggested question text or None
+        """
+        from .question_generator import suggest_next_question
+        
+        if not context.synthesis_template or not context.qa_history:
+            return None
+        
+        # Convert Q&A history to format expected by suggest_next_question
+        qa_tuples = [
+            (qa.get("question", ""), qa.get("answer", ""))
+            for qa in context.qa_history
+        ]
+        
+        try:
+            suggestion = suggest_next_question(
+                qa_history=qa_tuples,
+                template_spec=context.synthesis_template,
+                current_phase=None  # Auto-detect based on history length
+            )
+            return suggestion
+        except Exception as e:
+            logger.warning(f"Could not generate next question suggestion: {e}")
+            return None
+    
+    async def _run_interactive_session(self, context: ModeContext):
+        """
+        Run the interactive Q&A session with adaptive question suggestions.
+        
+        Now includes project type detection and smart question suggestions!
+        
+        Args:
+            context: The mode context
+        """
+        print("\n" + "="*60)
+        print("🚀 Interactive Documentation Explorer")
+        print("="*60)
+        
+        # Show context summary
+        if context.context_manager and context.context_manager.total_items > 0:
+            summary = context.context_manager.get_summary()
+            print(f"\n📚 Loaded Context: {summary['total_items']} items")
+            for ctx_type, info in summary.get('by_type', {}).items():
+                print(f"  • {ctx_type}: {info['count']} items")
+        
+        # Generate adaptive question suggestions
+        suggested_questions = self._generate_adaptive_questions(context)
+        
+        if suggested_questions:
+            print(f"\n💡 Suggested questions based on your project:")
+            for i, question in enumerate(suggested_questions[:5], 1):
+                priority_icon = {
+                    "critical": "🔴",
+                    "high": "🟡",
+                    "medium": "🟢",
+                    "low": "⚪"
+                }.get(question.priority.value, "❓")
+                print(f"   {i}. {priority_icon} {question.text}")
+            print("   (You can ask these or any other questions)")
+        
+        print("\n✨ Let's explore your codebase!")
+        print("Commands:")
+        print("  • Ask any question about the code")
+        print("  • Type 'add context' to add more context")
+        print("  • Type 'generate docs' to create documentation")
+        print("  • Type 'help' for more commands")
+        print("")
+        
+        while not context.exploration_complete:
+            try:
+                question = input("\n❓ > ").strip()
+                
+                if not question:
+                    continue
+                
+                # Handle special commands
+                if question.lower() == 'generate docs':
+                    context.exploration_complete = True
+                    print("\n📝 Generating documentation from exploration...")
+                    
+                    # Show query interpretation metrics
+                    if context.explorer and hasattr(context.explorer, 'print_metrics_report'):
+                        context.explorer.print_metrics_report()
+                    
+                    break
+                
+                elif question.lower() == 'add context':
+                    if context.explorer.add_context_interactive():
+                        print("✅ Context added successfully")
+                    continue
+                
+                elif question.lower() == 'help':
+                    self._show_help()
+                    continue
+                
+                elif question.lower() == 'exit':
+                    print("👋 Exiting without generating documentation")
+                    sys.exit(0)
+                
+                # Ask the question
+                result = context.explorer.ask(question)
+                
+                # Display the answer
+                print(f"\n💡 {result.format_with_context()}")
+                
+                # Show follow-up suggestions
+                if result.follow_up_suggestions:
+                    print("\n🔍 You might also want to ask:")
+                    for suggestion in result.follow_up_suggestions[:3]:
+                        print(f"  • {suggestion}")
+                
+                # Store in Q&A history
+                context.qa_history.append({
+                    "question": question,
+                    "answer": result.answer,
+                    "context_used": len(result.context_items) > 0,
+                    "code_results": len(result.code_results),
+                    "confidence": result.confidence,
+                    "question_type": getattr(result, "question_type", None).name.lower() if getattr(result, "question_type", None) else None,
+                    "rationale_points": getattr(result, "rationale_points", [])
+                })
+                
+                # Show adaptive next question suggestion every few questions
+                if len(context.qa_history) % 3 == 0 and context.synthesis_template:
+                    next_suggestion = self._suggest_next_question(context)
+                    if next_suggestion:
+                        print(f"\n💭 Suggested next question: {next_suggestion}")
+                
+            except KeyboardInterrupt:
+                print("\n\n👋 Interrupted. Exiting...")
+                sys.exit(0)
+            except Exception as e:
+                print(f"\n❌ Error: {e}")
+                logger.exception("Error in interactive session")
+    
+    def _show_help(self):
+        """Show help for interactive mode"""
+        print("\n📖 Interactive Mode Help")
+        print("="*40)
+        print("Questions you can ask:")
+        print("  • What are the main components?")
+        print("  • How does authentication work?")
+        print("  • Why do we use [technology]?")
+        print("  • Show me the API endpoints")
+        print("  • What does [class/function] do?")
+        print("")
+        print("Commands:")
+        print("  • add context    - Add requirements, tickets, or docs")
+        print("  • generate docs  - Create documentation from exploration")
+        print("  • help          - Show this help")
+        print("  • exit          - Exit without generating")
+    
+    # Documentation generation methods (simplified for now)
+    
+    def _generate_auto_readme(self, context: ModeContext) -> str:
+        """Generate README for AUTO mode"""
+        return f"""# {Path(context.repository_path).name}
+
+## Overview
+*Generated from code analysis*
+
+This documentation was automatically generated from code analysis.
+
+## Structure
+Repository contains code files that were analyzed using:
+- AST-based semantic chunking
+- Vector embeddings for similarity
+- BM25 keyword search
+
+## Note
+This is AUTO mode documentation - based purely on code analysis without external context.
+For richer documentation including business context, use INTERACTIVE or HYBRID modes.
+"""
+    
+    def _generate_hybrid_readme(self, context: ModeContext) -> str:
+        """Generate README for HYBRID mode"""
+        context_summary = context.context_manager.get_summary() if context.context_manager else {}
+        
+        return f"""# {Path(context.repository_path).name}
+
+## Overview
+*Generated from code analysis + external context*
+
+This documentation was generated using HYBRID mode, combining:
+- Code analysis (AST, embeddings, search)
+- External context ({context_summary.get('total_items', 0)} items)
+
+## Context Sources
+{self._format_context_sources(context_summary)}
+
+## Note
+This documentation includes external context but was generated without interactive exploration.
+For documentation that captures specific insights, use INTERACTIVE mode.
+"""
+    
+    def _generate_interactive_readme(self, context: ModeContext) -> str:
+        """Generate README for INTERACTIVE mode"""
+        qa_count = len(context.qa_history)
+        context_summary = context.context_manager.get_summary() if context.context_manager else {}
+        
+        return f"""# {Path(context.repository_path).name}
+
+## Overview
+*Generated from interactive exploration with Q&A*
+
+This documentation was created through INTERACTIVE exploration:
+- {qa_count} questions explored
+- {context_summary.get('total_items', 0)} context items used
+- Code + Context + Human insights combined
+
+## Key Insights from Exploration
+{self._format_qa_insights(context.qa_history[:5])}
+
+## Note
+This documentation reflects the understanding gained through interactive Q&A.
+It combines code analysis, external context, and human-guided exploration.
+"""
+    
+    def _generate_auto_architecture(self, context: ModeContext) -> str:
+        """Generate architecture doc for AUTO mode"""
+        return "# Architecture\n\n*Generated from code structure analysis*\n\nTODO: Integrate with existing pipeline"
+    
+    def _generate_hybrid_architecture(self, context: ModeContext) -> str:
+        """Generate architecture doc for HYBRID mode"""
+        return "# Architecture\n\n*Generated from code + context*\n\nTODO: Integrate with context-aware generation"
+    
+    def _generate_interactive_architecture(self, context: ModeContext) -> str:
+        """Generate architecture doc for INTERACTIVE mode"""
+        return "# Architecture\n\n*Generated from exploration insights*\n\nTODO: Build from Q&A insights"
+    
+    def _generate_auto_api(self, context: ModeContext) -> str:
+        """Generate API doc for AUTO mode"""
+        return "# API Reference\n\n*Generated from code analysis*\n\nTODO: Extract from AST"
+    
+    def _generate_hybrid_api(self, context: ModeContext) -> str:
+        """Generate API doc for HYBRID mode"""
+        return "# API Reference\n\n*Generated with context*\n\nTODO: Add context citations"
+    
+    def _generate_interactive_api(self, context: ModeContext) -> str:
+        """Generate API doc for INTERACTIVE mode"""
+        return "# API Reference\n\n*Generated from exploration*\n\nTODO: Include Q&A insights"
+    
+    def _generate_requirements_tracing(self, context: ModeContext) -> str:
+        """Generate requirements tracing document"""
+        if not context.context_manager:
+            return "# Requirements Tracing\n\nNo requirements context available."
+        
+        return f"""# Requirements Tracing
+
+## Context Sources
+{self._format_context_sources(context.context_manager.get_summary())}
+
+## Traceability Matrix
+TODO: Map requirements to implementation
+"""
+    
+    def _generate_exploration_insights(self, context: ModeContext) -> str:
+        """Generate insights from Q&A exploration"""
+        return f"""# Exploration Insights
+
+## Questions Explored
+Total questions: {len(context.qa_history)}
+
+## Key Findings
+{self._format_qa_insights(context.qa_history)}
+
+## Confidence Levels
+High confidence answers: {sum(1 for q in context.qa_history if q.get('confidence', 0) > 0.7)}
+With context support: {sum(1 for q in context.qa_history if q.get('context_used', False))}
+"""
+    
+    def _format_context_sources(self, summary: Dict) -> str:
+        """Format context sources for documentation"""
+        lines = []
+        for ctx_type, info in summary.get('by_type', {}).items():
+            lines.append(f"- **{ctx_type}**: {info['count']} items")
+            for item in info.get('items', [])[:2]:
+                lines.append(f"  - {item}")
+        return "\n".join(lines) if lines else "No context loaded"
+    
+    def _format_qa_insights(self, qa_history: List[Dict]) -> str:
+        """Format Q&A insights for documentation"""
+        lines = []
+        for i, qa in enumerate(qa_history[:10], 1):
+            lines.append(f"{i}. **Q:** {qa['question']}")
+            lines.append(f"   **Confidence:** {qa.get('confidence', 0):.1%}")
+        return "\n".join(lines) if lines else "No Q&A session conducted"
+
+
+async def run_documentation_mode(
+    repository_path: str,
+    output_path: str = "./docs",
+    interactive: bool = False,
+    context_files: Optional[List[str]] = None,
+    jira_config: Optional[Dict] = None,
+    synthesis: bool = True,
+    synthesis_template: Optional[Dict[str, Any]] = None,
+    user_focused: bool = False,
+    editor_enabled: Optional[bool] = None,
+    single_readme_mode: bool = False,
+) -> ModeContext:
+    """
+    Main entry point for documentation generation.
+
+    Args:
+        repository_path: Path to repository
+        output_path: Output directory
+        interactive: Enable Q&A session (default: False for automatic)
+        context_files: External context files
+        jira_config: Jira configuration
+        synthesis: Enable synthesis (deprecated, always True)
+        synthesis_template: Custom template
+        user_focused: Use user-focused prompts
+        editor_enabled: Enable two-pass editor workflow (overrides V2D_ENABLE_EDITOR env)
+        single_readme_mode: Use only root README (legacy behavior). Default: False (multi-README)
+
+    Returns:
+        ModeContext populated with generated documentation and editor outputs
+    """
+    # Create handler
+    handler = DocumentationModeHandler()
+
+    # Initialize
+    context = await handler.initialize_mode(
+        repository_path=repository_path,
+        output_path=output_path,
+        interactive=interactive,
+        context_files=context_files,
+        jira_config=jira_config,
+        synthesis=synthesis,
+        synthesis_template=synthesis_template,
+        user_focused=user_focused,
+        editor_enabled=editor_enabled,
+        single_readme_mode=single_readme_mode,
+    )
+
+    # Generate docs
+    docs = await handler.run_generate_mode(context)
+
+    # Save documentation
+    output_dir = Path(output_path)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    for filename, content in docs.items():
+        file_path = output_dir / filename
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_text(content)
+        logger.info(f"Saved {filename}")
+
+    context.generated_docs = docs
+
+    print(f"\n✅ Documentation generated in {output_path}")
+    return context
+
+
+if __name__ == "__main__":
+    # Test the mode handler
+    import sys
+    
+    if len(sys.argv) < 3:
+        print("Usage: python mode_handler.py <mode> <repository_path> [context_files...]")
+        print("Modes: auto, interactive, hybrid")
+        sys.exit(1)
+    
+    mode = sys.argv[1]
+    repo_path = sys.argv[2]
+    context_files = sys.argv[3:] if len(sys.argv) > 3 else None
+    
+    # Run the mode
+    asyncio.run(run_documentation_mode(
+        mode=mode,
+        repository_path=repo_path,
+        context_files=context_files
+    ))