shotgun-sh 0.3.3.dev1__py3-none-any.whl → 0.6.2__py3-none-any.whl

shotgun/codebase/indexing_state.py

@@ -0,0 +1,86 @@
+"""State tracking for codebase indexing operations."""
+
+import asyncio
+from typing import ClassVar
+
+from shotgun.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class IndexingState:
+    """Tracks which graph_ids are currently being indexed.
+
+    This is a simple state container that tools can check to determine
+    if a graph is available or currently being built. This prevents
+    race conditions on Windows where Kuzu uses exclusive file locking.
+
+    Uses class-level state so all service instances share the same state.
+    This is similar to how CodebaseGraphManager shares connections.
+    """
+
+    # Error message for when tools try to access a graph being indexed
+    INDEXING_IN_PROGRESS_ERROR = (
+        "This codebase is currently being indexed. "
+        "Please wait for indexing to complete before accessing it."
+    )
+
+    # Class-level state shared across all instances
+    _active_graphs: ClassVar[set[str]] = set()
+    _lock: ClassVar[asyncio.Lock | None] = None
+
+    @classmethod
+    def _get_lock(cls) -> asyncio.Lock:
+        """Get or create the class-level lock."""
+        if cls._lock is None:
+            cls._lock = asyncio.Lock()
+        return cls._lock
+
+    async def start(self, graph_id: str) -> None:
+        """Mark a graph as being indexed.
+
+        Args:
+            graph_id: The graph ID that is starting to be indexed
+        """
+        lock = self._get_lock()
+        async with lock:
+            self._active_graphs.add(graph_id)
+            logger.debug(f"Indexing started for graph: {graph_id}")
+
+    async def complete(self, graph_id: str) -> None:
+        """Mark a graph as finished indexing.
+
+        Args:
+            graph_id: The graph ID that finished indexing
+        """
+        lock = self._get_lock()
+        async with lock:
+            self._active_graphs.discard(graph_id)
+            logger.debug(f"Indexing completed for graph: {graph_id}")
+
+    def is_active(self, graph_id: str) -> bool:
+        """Check if a specific graph is currently being indexed.
+
+        Args:
+            graph_id: The graph ID to check
+
+        Returns:
+            True if the graph is currently being indexed
+        """
+        return graph_id in self._active_graphs
+
+    def has_active(self) -> bool:
+        """Check if any graph is currently being indexed.
+
+        Returns:
+            True if any graph is being indexed
+        """
+        return len(self._active_graphs) > 0
+
+    def get_active_ids(self) -> set[str]:
+        """Get set of graph IDs currently being indexed.
+
+        Returns:
+            Copy of the set of graph IDs being indexed
+        """
+        return self._active_graphs.copy()

shotgun/codebase/models.py

@@ -16,6 +16,15 @@ class GraphStatus(StrEnum):
     ERROR = "ERROR"  # Last operation failed
 
 
+class IgnoreReason(StrEnum):
+    """Reason why a file or directory was ignored during indexing."""
+
+    HARDCODED = (
+        "hardcoded"  # Matched hardcoded ignore patterns (venv, node_modules, etc.)
+    )
+    GITIGNORE = "gitignore"  # Matched .gitignore pattern
+
+
 class QueryType(StrEnum):
     """Type of query being executed."""
 
@@ -33,6 +42,55 @@ class ProgressPhase(StrEnum):
     FLUSH_RELATIONSHIPS = "flush_relationships"  # Flushing relationships to database
 
 
+class NodeLabel(StrEnum):
+    """Node type labels for the code knowledge graph."""
+
+    PROJECT = "Project"  # Top-level project node
+    PACKAGE = "Package"  # Python package/namespace
+    FOLDER = "Folder"  # Directory structure
+    FILE = "File"  # Source file
+    MODULE = "Module"  # Python module
+    CLASS = "Class"  # Class definition
+    FUNCTION = "Function"  # Function definition
+    METHOD = "Method"  # Method definition (inside a class)
+    FILE_METADATA = "FileMetadata"  # File tracking metadata (hash, mtime)
+    EXTERNAL_PACKAGE = "ExternalPackage"  # External dependency
+    DELETION_LOG = "DeletionLog"  # Deletion audit trail
+
+
+class RelationshipType(StrEnum):
+    """Relationship types for the code knowledge graph."""
+
+    # Containment relationships (used with suffixes _PKG, _FOLDER in tables)
+    CONTAINS_PACKAGE = "CONTAINS_PACKAGE"  # Container to Package
+    CONTAINS_FOLDER = "CONTAINS_FOLDER"  # Container to Folder
+    CONTAINS_FILE = "CONTAINS_FILE"  # Container to File
+    CONTAINS_MODULE = "CONTAINS_MODULE"  # Container to Module
+
+    # Definition relationships
+    DEFINES = "DEFINES"  # Module to Class
+    DEFINES_FUNC = "DEFINES_FUNC"  # Module to Function
+    DEFINES_METHOD = "DEFINES_METHOD"  # Class to Method
+
+    # Call relationships
+    CALLS = "CALLS"  # Function to Function
+    CALLS_FM = "CALLS_FM"  # Function to Method
+    CALLS_MF = "CALLS_MF"  # Method to Function
+    CALLS_MM = "CALLS_MM"  # Method to Method
+
+    # Tracking relationships (FileMetadata to entity)
+    TRACKS_MODULE = "TRACKS_Module"  # FileMetadata to Module
+    TRACKS_CLASS = "TRACKS_Class"  # FileMetadata to Class
+    TRACKS_FUNCTION = "TRACKS_Function"  # FileMetadata to Function
+    TRACKS_METHOD = "TRACKS_Method"  # FileMetadata to Method
+
+    # Other relationships
+    INHERITS = "INHERITS"  # Child Class to Parent Class
+    OVERRIDES = "OVERRIDES"  # Method to Method (override)
+    IMPORTS = "IMPORTS"  # Module to Module
+    DEPENDS_ON_EXTERNAL = "DEPENDS_ON_EXTERNAL"  # Project to ExternalPackage
+
+
 class IndexProgress(BaseModel):
     """Progress information for codebase indexing."""
 
@@ -49,6 +107,42 @@ class IndexProgress(BaseModel):
 ProgressCallback = Callable[[IndexProgress], None]
 
 
+class GitignoreStats(BaseModel):
+    """Statistics from gitignore pattern matching."""
+
+    gitignore_files_loaded: int = Field(
+        default=0, description="Number of .gitignore files loaded"
+    )
+    patterns_loaded: int = Field(default=0, description="Total patterns loaded")
+    files_checked: int = Field(default=0, description="Number of paths checked")
+    files_ignored: int = Field(
+        default=0, description="Number of paths ignored by gitignore"
+    )
+
+
+class IndexingStats(BaseModel):
+    """Statistics from codebase indexing."""
+
+    dirs_scanned: int = Field(default=0, description="Directories scanned")
+    dirs_ignored_hardcoded: int = Field(
+        default=0, description="Directories ignored by hardcoded patterns"
+    )
+    dirs_ignored_gitignore: int = Field(
+        default=0, description="Directories ignored by gitignore"
+    )
+    files_scanned: int = Field(default=0, description="Files scanned")
+    files_ignored_hardcoded: int = Field(
+        default=0, description="Files ignored by hardcoded patterns"
+    )
+    files_ignored_gitignore: int = Field(
+        default=0, description="Files ignored by gitignore"
+    )
+    files_ignored_no_parser: int = Field(
+        default=0, description="Files ignored due to no parser available"
+    )
+    files_processed: int = Field(default=0, description="Files successfully processed")
+
+
 class OperationStats(BaseModel):
     """Statistics for a graph operation (build/update)."""
 

shotgun/codebase/service.py

@@ -7,6 +7,7 @@ from typing import Any
 from shotgun.codebase.core.cypher_models import CypherGenerationNotPossibleError
 from shotgun.codebase.core.manager import CodebaseGraphManager
 from shotgun.codebase.core.nl_query import generate_cypher
+from shotgun.codebase.indexing_state import IndexingState
 from shotgun.codebase.models import CodebaseGraph, QueryResult, QueryType
 from shotgun.logging_config import get_logger
 
@@ -28,6 +29,18 @@ class CodebaseService:
         self.storage_dir = storage_dir
         self.storage_dir.mkdir(parents=True, exist_ok=True)
         self.manager = CodebaseGraphManager(storage_dir)
+        self.indexing = IndexingState()
+
+    def compute_graph_id(self, repo_path: str | Path) -> str:
+        """Compute graph_id for a repo path without creating the graph.
+
+        Args:
+            repo_path: Path to the repository
+
+        Returns:
+            The graph_id that would be used for this repo path
+        """
+        return self.manager.generate_graph_id(str(repo_path))
 
     async def list_graphs(self) -> list[CodebaseGraph]:
         """List all existing graphs.

shotgun/exceptions.py

@@ -7,8 +7,8 @@ SHOTGUN_SIGNUP_URL = "https://shotgun.sh"
 SHOTGUN_CONTACT_EMAIL = "contact@shotgun.sh"
 
 
-class ErrorNotPickedUpBySentry(Exception):  # noqa: N818
-    """Base for user-actionable errors that shouldn't be sent to Sentry.
+class UserActionableError(Exception):  # noqa: N818
+    """Base for user-actionable errors that shouldn't be sent to telemetry.
 
     These errors represent expected user conditions requiring action
     rather than bugs that need tracking.
@@ -37,7 +37,7 @@ class ErrorNotPickedUpBySentry(Exception):  # noqa: N818
 # ============================================================================
 
 
-class AgentCancelledException(ErrorNotPickedUpBySentry):
+class AgentCancelledException(UserActionableError):  # noqa: N818
     """Raised when user cancels an agent operation."""
 
     def __init__(self) -> None:
@@ -53,7 +53,7 @@ class AgentCancelledException(ErrorNotPickedUpBySentry):
         return "⚠️  Operation cancelled by user"
 
 
-class ContextSizeLimitExceeded(ErrorNotPickedUpBySentry):
+class ContextSizeLimitExceeded(UserActionableError):  # noqa: N818
     """Raised when conversation context exceeds the model's limits.
 
     This is a user-actionable error - they need to either:
@@ -81,7 +81,7 @@ class ContextSizeLimitExceeded(ErrorNotPickedUpBySentry):
             f"⚠️ **Context too large for {self.model_name}**\n\n"
             f"Your conversation history exceeds this model's limit ({self.max_tokens:,} tokens).\n\n"
             f"**Choose an action:**\n\n"
-            f"1. Switch to a larger model (`Ctrl+P` → Change Model)\n"
+            f"1. Switch to a larger model (`/` → Change Model)\n"
             f"2. Switch to a larger model, compact (`/compact`), then switch back to {self.model_name}\n"
             f"3. Clear conversation (`/clear`)\n"
         )
@@ -103,7 +103,7 @@ class ContextSizeLimitExceeded(ErrorNotPickedUpBySentry):
 # ============================================================================
 
 
-class ShotgunAccountException(ErrorNotPickedUpBySentry):
+class ShotgunAccountException(UserActionableError):  # noqa: N818
     """Base class for Shotgun Account service errors.
 
     TUI will check isinstance() of this class to show contact email UI.
@@ -216,7 +216,7 @@ class ShotgunRateLimitException(ShotgunAccountException):
 # ============================================================================
 
 
-class BYOKAPIException(ErrorNotPickedUpBySentry):
+class BYOKAPIException(UserActionableError):  # noqa: N818
     """Base class for BYOK API errors.
 
     All BYOK errors suggest using Shotgun Account to avoid the issue.
@@ -313,7 +313,7 @@ class BYOKGenericAPIException(BYOKAPIException):
 # ============================================================================
 
 
-class GenericAPIStatusException(ErrorNotPickedUpBySentry):
+class GenericAPIStatusException(UserActionableError):  # noqa: N818
     """Raised for generic API status errors that don't fit other categories."""
 
     def __init__(self, message: str):
@@ -334,7 +334,7 @@ class GenericAPIStatusException(ErrorNotPickedUpBySentry):
         return f"⚠️  AI service error: {self.api_message}"
 
 
-class UnknownAgentException(ErrorNotPickedUpBySentry):
+class UnknownAgentException(UserActionableError):  # noqa: N818
     """Raised for unknown/unclassified agent errors."""
 
     def __init__(self, original_exception: Exception):

shotgun/main.py

@@ -28,18 +28,13 @@ from shotgun.cli import (
     compact,
     config,
     context,
-    export,
     feedback,
-    plan,
-    research,
+    run,
     spec,
-    specify,
-    tasks,
     update,
 )
 from shotgun.logging_config import configure_root_logger, get_logger
 from shotgun.posthog_telemetry import setup_posthog_observability
-from shotgun.sentry_telemetry import setup_sentry_observability
 from shotgun.telemetry import setup_logfire_observability
 from shotgun.tui import app as tui_app
 from shotgun.utils.update_checker import perform_auto_update_async
@@ -66,11 +61,7 @@ try:
 except Exception as e:
     logger.debug("Configuration initialization warning: %s", e)
 
-# Initialize Sentry telemetry
-_sentry_enabled = setup_sentry_observability()
-logger.debug("Sentry observability enabled: %s", _sentry_enabled)
-
-# Initialize PostHog analytics
+# Initialize PostHog analytics (includes exception tracking)
 _posthog_enabled = setup_posthog_observability()
 logger.debug("PostHog analytics enabled: %s", _posthog_enabled)
 
@@ -89,11 +80,7 @@ app.add_typer(
 app.add_typer(context.app, name="context", help="Analyze conversation context usage")
 app.add_typer(compact.app, name="compact", help="Compact conversation history")
 app.add_typer(clear.app, name="clear", help="Clear conversation history")
-app.add_typer(research.app, name="research", help="Perform research with agentic loops")
-app.add_typer(plan.app, name="plan", help="Generate structured plans")
-app.add_typer(specify.app, name="specify", help="Generate comprehensive specifications")
-app.add_typer(tasks.app, name="tasks", help="Generate task lists with agentic approach")
-app.add_typer(export.app, name="export", help="Export artifacts to various formats")
+app.add_typer(run.app, name="run", help="Run a prompt using the Router agent")
 app.add_typer(update.app, name="update", help="Check for and install updates")
 app.add_typer(feedback.app, name="feedback", help="Send us feedback")
 app.add_typer(spec.app, name="spec", help="Manage shared specifications")

shotgun/posthog_telemetry.py

@@ -1,34 +1,86 @@
 """PostHog analytics setup for Shotgun."""
 
+import platform
 from enum import StrEnum
 from typing import Any
 
-import posthog
+from posthog import Posthog
 from pydantic import BaseModel
 
 from shotgun import __version__
 from shotgun.agents.config import get_config_manager
 from shotgun.agents.conversation import ConversationManager
+from shotgun.exceptions import UserActionableError
 from shotgun.logging_config import get_early_logger
 from shotgun.settings import settings
 
 # Use early logger to prevent automatic StreamHandler creation
 logger = get_early_logger(__name__)
 
+
+def _get_environment() -> str:
+    """Determine environment from version string.
+
+    Returns:
+        'development' for dev/rc/alpha/beta versions, 'production' otherwise
+    """
+    if any(marker in __version__ for marker in ["dev", "rc", "alpha", "beta"]):
+        return "development"
+    return "production"
+
+
 # Global PostHog client instance
-_posthog_client = None
+_posthog_client: Posthog | None = None
 
-# Cache the shotgun instance ID to avoid async calls during event tracking
+# Cache user context to avoid async calls during event tracking
 _shotgun_instance_id: str | None = None
+_user_context: dict[str, Any] = {}
+
+# Store original exception hook
+_original_excepthook: Any = None
+
+
+def _install_exception_hook() -> None:
+    """Install custom exception hook to capture unhandled exceptions with full context."""
+    import sys
+
+    global _original_excepthook
+
+    # Store original excepthook
+    _original_excepthook = sys.excepthook
+
+    def custom_excepthook(
+        exc_type: type[BaseException],
+        exc_value: BaseException,
+        exc_traceback: Any,
+    ) -> None:
+        """Custom exception hook that captures exceptions to PostHog."""
+        # Only capture Exception subclasses (not KeyboardInterrupt, SystemExit, etc.)
+        if isinstance(exc_value, Exception):
+            capture_exception(exc_value)
+
+            # Flush PostHog to ensure exception is sent before process exits
+            if _posthog_client is not None:
+                try:
+                    _posthog_client.flush()  # type: ignore[no-untyped-call]
+                except Exception:  # noqa: S110 - intentionally silent during crash
+                    pass
+
+        # Call original excepthook to maintain normal behavior
+        if _original_excepthook is not None:
+            _original_excepthook(exc_type, exc_value, exc_traceback)
+
+    sys.excepthook = custom_excepthook
+    logger.debug("Installed custom exception hook for PostHog")
 
 
 def setup_posthog_observability() -> bool:
-    """Set up PostHog analytics for usage tracking.
+    """Set up PostHog analytics for usage tracking and exception capture.
 
     Returns:
         True if PostHog was successfully set up, False otherwise
     """
-    global _posthog_client, _shotgun_instance_id
+    global _posthog_client, _shotgun_instance_id, _user_context
 
     try:
         # Check if PostHog is already initialized
@@ -46,27 +98,49 @@ def setup_posthog_observability() -> bool:
 
         logger.debug("Using PostHog API key from settings")
 
-        # Determine environment based on version
-        # Dev versions contain "dev", "rc", "alpha", or "beta"
-        if any(marker in __version__ for marker in ["dev", "rc", "alpha", "beta"]):
-            environment = "development"
-        else:
-            environment = "production"
+        environment = _get_environment()
 
-        # Initialize PostHog client
-        posthog.api_key = api_key
-        posthog.host = "https://us.i.posthog.com"  # Use US cloud instance
+        def on_error(e: Exception, batch: list[dict[str, Any]]) -> None:
+            """Handle PostHog errors."""
+            logger.warning("PostHog error: %s", e)
 
-        # Store the client for later use
-        _posthog_client = posthog
+        # Initialize PostHog client (we use custom exception hook instead of autocapture)
+        _posthog_client = Posthog(
+            project_api_key=api_key,
+            host="https://us.i.posthog.com",
+            on_error=on_error,
+        )
 
-        # Cache the shotgun instance ID for later use (avoids async issues)
+        # Cache user context for later use (avoids async issues in exception capture)
         try:
             import asyncio
 
             config_manager = get_config_manager()
             _shotgun_instance_id = asyncio.run(config_manager.get_shotgun_instance_id())
 
+            # Load config to get account type and model info
+            config = asyncio.run(config_manager.load())
+
+            # Cache user context for exception tracking
+            is_shotgun_account = config.shotgun.has_valid_account
+            _user_context["account_type"] = "shotgun" if is_shotgun_account else "byok"
+            _user_context["selected_model"] = (
+                config.selected_model.value if config.selected_model else None
+            )
+
+            # Set user properties for tracking
+            _posthog_client.capture(
+                distinct_id=_shotgun_instance_id,
+                event="$identify",
+                properties={
+                    "$set": {
+                        "app_version": __version__,
+                        "environment": environment,
+                        "account_type": _user_context["account_type"],
+                    },
+                },
+            )
+
             logger.debug(
                 "PostHog initialized with shotgun instance ID: %s",
                 _shotgun_instance_id,
@@ -75,6 +149,9 @@ def setup_posthog_observability() -> bool:
             logger.warning("Failed to load shotgun instance ID: %s", e)
             # Continue anyway - we'll try to get it during event tracking
 
+        # Install custom exception hook to capture unhandled exceptions with full context
+        _install_exception_hook()
+
         logger.debug(
             "PostHog analytics configured successfully (environment: %s, version: %s)",
             environment,
@@ -112,12 +189,7 @@ def track_event(event_name: str, properties: dict[str, Any] | None = None) -> No
         if properties is None:
             properties = {}
         properties["version"] = __version__
-
-        # Determine environment
-        if any(marker in __version__ for marker in ["dev", "rc", "alpha", "beta"]):
-            properties["environment"] = "development"
-        else:
-            properties["environment"] = "production"
+        properties["environment"] = _get_environment()
 
         # Track the event using PostHog's capture method
         _posthog_client.capture(
@@ -128,13 +200,82 @@ def track_event(event_name: str, properties: dict[str, Any] | None = None) -> No
         logger.warning("Failed to track PostHog event '%s': %s", event_name, e)
 
 
+def capture_exception(
+    exception: Exception,
+    properties: dict[str, Any] | None = None,
+) -> None:
+    """Manually capture an exception in PostHog.
+
+    Uses the PostHog SDK's built-in capture_exception method which properly
+    formats the exception with stack traces, fingerprinting, and all required
+    fields for PostHog's Error Tracking system.
+
+    Note: UserActionableError exceptions are filtered out as they represent
+    expected user conditions, not bugs.
+
+    Args:
+        exception: The exception to capture
+        properties: Optional additional properties
+    """
+    global _posthog_client, _shotgun_instance_id
+
+    if _posthog_client is None:
+        logger.debug("PostHog not initialized, skipping exception capture")
+        return
+
+    # Filter out user-actionable errors - these are expected conditions
+    if isinstance(exception, UserActionableError):
+        logger.debug(
+            "Skipping UserActionableError in PostHog exception capture: %s",
+            type(exception).__name__,
+        )
+        return
+
+    try:
+        if _shotgun_instance_id is None:
+            logger.warning(
+                "Shotgun instance ID not available, skipping exception capture"
+            )
+            return
+
+        # Build properties with app/user context
+        event_properties: dict[str, Any] = {
+            # App info
+            "version": __version__,
+            "environment": _get_environment(),
+            # System info
+            "python_version": platform.python_version(),
+            "os": platform.system(),
+            "os_version": platform.release(),
+            # User context
+            "shotgun_instance_id": _shotgun_instance_id,
+            "account_type": _user_context.get("account_type"),
+            "selected_model": _user_context.get("selected_model"),
+        }
+
+        # Add custom properties
+        if properties:
+            event_properties.update(properties)
+
+        # Use the SDK's built-in capture_exception method which properly
+        # formats the exception with stack traces, fingerprinting, etc.
+        _posthog_client.capture_exception(
+            exception,
+            distinct_id=_shotgun_instance_id,
+            properties=event_properties,
+        )
+        logger.debug("Captured exception in PostHog: %s", type(exception).__name__)
+    except Exception as e:
+        logger.warning("Failed to capture exception in PostHog: %s", e)
+
+
 def shutdown() -> None:
     """Shutdown PostHog client and flush any pending events."""
     global _posthog_client
 
     if _posthog_client is not None:
         try:
-            _posthog_client.shutdown()
+            _posthog_client.shutdown()  # type: ignore[no-untyped-call]
             logger.debug("PostHog client shutdown successfully")
         except Exception as e:
             logger.warning("Error shutting down PostHog: %s", e)

shotgun/prompts/agents/export.j2

@@ -10,6 +10,8 @@ Your primary job is to generate Agents.md or CLAUDE.md files following the https
 
 {% include 'agents/partials/common_agent_system_prompt.j2' %}
 
+{% include 'agents/partials/router_delegation_mode.j2' %}
+
 ## MEMORY MANAGEMENT PROTOCOL
 
 - You can write to ANY file EXCEPT protected files

shotgun/prompts/agents/file_read.j2

@@ -0,0 +1,48 @@
+You are a File Reading Agent - a lightweight, focused assistant for finding and reading files.
+
+## YOUR PURPOSE
+
+Your job is to:
+1. **Search** for files matching the user's description
+2. **Read** file contents (including PDFs and images)
+3. **Summarize** what you found
+4. **Return** the file paths so they can be loaded into context
+
+## TOOLS AVAILABLE
+
+- `directory_lister` - List contents of a directory
+- `file_read` - Read text file contents
+- `read_file` - Read file by path
+- `multimodal_file_read` - Verify PDFs and images exist and get their absolute paths
+
+## WORKFLOW
+
+1. **Understand the request** - What file is the user looking for?
+2. **Search systematically** - Use directory_lister to explore, then read candidates
+3. **For PDFs/images** - Use `multimodal_file_read` to verify they exist and get the absolute path
+4. **Identify the right file** - Confirm you found what was requested
+5. **Return results** - Include the absolute file path in `files_found` so the Router can load it
+
+## OUTPUT FORMAT
+
+When you find the file(s):
+- Provide a brief summary of what you found
+- **Always include absolute file paths in the `files_found` field** of your response
+- This allows the Router to load the files into its context
+
+Example response:
+```json
+{
+  "response": "Found the user stories document at /home/user/docs/user_stories_v2.pdf. It contains 3 user stories about authentication, profile management, and notifications.",
+  "files_found": ["/home/user/docs/user_stories_v2.pdf"]
+}
+```
+
+## IMPORTANT NOTES
+
+- You are a **read-only** agent - you cannot create or modify files
+- Use `multimodal_file_read` for PDFs and images to verify they exist and get absolute paths
+- The Router will load the actual file content using the paths you return in `files_found`
+- Be efficient - search systematically, don't read every file
+- Return file paths as **absolute paths** for reliability
+- If you can't find the file, say so clearly and suggest alternatives