shotgun-sh 0.2.3.dev2__py3-none-any.whl → 0.2.11.dev5__py3-none-any.whl

shotgun/cli/plan.py

@@ -55,7 +55,7 @@ def plan(
         )
 
         # Create the plan agent with deps and provider
-        agent, deps = create_plan_agent(agent_runtime_options, provider)
+        agent, deps = asyncio.run(create_plan_agent(agent_runtime_options, provider))
 
         # Start planning process
         logger.info("🎯 Starting planning...")

shotgun/cli/research.py

@@ -73,7 +73,7 @@ async def async_research(
     agent_runtime_options = AgentRuntimeOptions(interactive_mode=not non_interactive)
 
     # Create the research agent with deps and provider
-    agent, deps = create_research_agent(agent_runtime_options, provider)
+    agent, deps = await create_research_agent(agent_runtime_options, provider)
 
     # Start research process
     logger.info("🔬 Starting research...")

shotgun/cli/specify.py

@@ -51,7 +51,7 @@ def specify(
         )
 
         # Create the specify agent with deps and provider
-        agent, deps = create_specify_agent(agent_runtime_options, provider)
+        agent, deps = asyncio.run(create_specify_agent(agent_runtime_options, provider))
 
         # Start specification process
         logger.info("📋 Starting specification generation...")

shotgun/cli/tasks.py

@@ -60,7 +60,7 @@ def tasks(
         )
 
         # Create the tasks agent with deps and provider
-        agent, deps = create_tasks_agent(agent_runtime_options, provider)
+        agent, deps = asyncio.run(create_tasks_agent(agent_runtime_options, provider))
 
         # Start task creation process
         logger.info("🎯 Starting task creation...")

shotgun/cli/update.py

@@ -45,7 +45,7 @@ def update(
 
     This command will:
     - Check PyPI for the latest version
-    - Detect your installation method (pipx, pip, or venv)
+    - Detect your installation method (uvx, uv-tool, pipx, pip, or venv)
     - Perform the appropriate upgrade command
 
     Examples:
@@ -93,6 +93,8 @@ def update(
         )
         console.print(
             "Use --force to update anyway, or install the stable version with:\n"
+            "  uv tool install shotgun-sh\n"
+            "  or\n"
             "  pipx install shotgun-sh\n"
             "  or\n"
             "  pip install shotgun-sh",
@@ -134,7 +136,19 @@ def update(
             console.print(f"\n[red]✗[/red] {message}", style="bold red")
 
             # Provide manual update instructions
-            if method == "pipx":
+            if method == "uvx":
+                console.print(
+                    "\n[yellow]Run uvx again to use the latest version:[/yellow]\n"
+                    "  uvx shotgun-sh\n"
+                    "\n[yellow]Or install permanently:[/yellow]\n"
+                    "  uv tool install shotgun-sh"
+                )
+            elif method == "uv-tool":
+                console.print(
+                    "\n[yellow]Try updating manually:[/yellow]\n"
+                    "  uv tool upgrade shotgun-sh"
+                )
+            elif method == "pipx":
                 console.print(
                     "\n[yellow]Try updating manually:[/yellow]\n"
                     "  pipx upgrade shotgun-sh"

shotgun/codebase/core/change_detector.py

@@ -6,6 +6,7 @@ from enum import Enum
 from pathlib import Path
 from typing import Any, cast
 
+import aiofiles
 import kuzu
 
 from shotgun.logging_config import get_logger
@@ -301,7 +302,7 @@ class ChangeDetector:
             # Direct substring match
             return pattern in filepath
 
-    def _calculate_file_hash(self, filepath: Path) -> str:
+    async def _calculate_file_hash(self, filepath: Path) -> str:
         """Calculate hash of file contents.
 
         Args:
@@ -311,8 +312,9 @@ class ChangeDetector:
             SHA256 hash of file contents
         """
         try:
-            with open(filepath, "rb") as f:
-                return hashlib.sha256(f.read()).hexdigest()
+            async with aiofiles.open(filepath, "rb") as f:
+                content = await f.read()
+                return hashlib.sha256(content).hexdigest()
         except Exception as e:
             logger.error(f"Failed to calculate hash for {filepath}: {e}")
             return ""

shotgun/codebase/core/code_retrieval.py

@@ -3,6 +3,7 @@
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+import aiofiles
 from pydantic import BaseModel
 
 from shotgun.logging_config import get_logger
@@ -141,8 +142,9 @@ async def retrieve_code_by_qualified_name(
 
         # Read the file and extract the snippet
         try:
-            with full_path.open("r", encoding="utf-8") as f:
-                all_lines = f.readlines()
+            async with aiofiles.open(full_path, encoding="utf-8") as f:
+                content = await f.read()
+                all_lines = content.splitlines(keepends=True)
 
             # Extract the relevant lines (1-indexed to 0-indexed)
             snippet_lines = all_lines[start_line - 1 : end_line]

shotgun/codebase/core/ingestor.py

@@ -1,5 +1,6 @@
 """Kuzu graph ingestor for building code knowledge graphs."""
 
+import asyncio
 import hashlib
 import os
 import time
@@ -8,6 +9,7 @@ from collections import defaultdict
 from pathlib import Path
 from typing import Any
 
+import aiofiles
 import kuzu
 from tree_sitter import Node, Parser, QueryCursor
 
@@ -619,7 +621,7 @@ class SimpleGraphBuilder:
             # Don't let progress callback errors crash the build
             logger.debug(f"Progress callback error: {e}")
 
-    def run(self) -> None:
+    async def run(self) -> None:
         """Run the three-pass graph building process."""
         logger.info(f"Building graph for project: {self.project_name}")
 
@@ -629,7 +631,7 @@ class SimpleGraphBuilder:
 
         # Pass 2: Definitions
         logger.info("Pass 2: Processing files and extracting definitions...")
-        self._process_files()
+        await self._process_files()
 
         # Pass 3: Relationships
         logger.info("Pass 3: Processing relationships (calls, imports)...")
@@ -771,7 +773,7 @@ class SimpleGraphBuilder:
             phase_complete=True,
         )
 
-    def _process_files(self) -> None:
+    async def _process_files(self) -> None:
         """Second pass: Process files and extract definitions."""
         # First pass: Count total files
         total_files = 0
@@ -807,7 +809,7 @@ class SimpleGraphBuilder:
                 lang_config = get_language_config(ext)
 
                 if lang_config and lang_config.name in self.parsers:
-                    self._process_single_file(filepath, lang_config.name)
+                    await self._process_single_file(filepath, lang_config.name)
                     file_count += 1
 
                     # Report progress after each file
@@ -832,7 +834,7 @@ class SimpleGraphBuilder:
             phase_complete=True,
         )
 
-    def _process_single_file(self, filepath: Path, language: str) -> None:
+    async def _process_single_file(self, filepath: Path, language: str) -> None:
         """Process a single file."""
         relative_path = filepath.relative_to(self.repo_path)
         relative_path_str = str(relative_path).replace(os.sep, "/")
@@ -873,8 +875,8 @@ class SimpleGraphBuilder:
 
         # Parse file
         try:
-            with open(filepath, "rb") as f:
-                content = f.read()
+            async with aiofiles.open(filepath, "rb") as f:
+                content = await f.read()
 
             parser = self.parsers[language]
             tree = parser.parse(content)
@@ -1636,7 +1638,7 @@ class CodebaseIngestor:
             )
             if self.project_name:
                 builder.project_name = self.project_name
-            builder.run()
+            asyncio.run(builder.run())
 
             logger.info(f"Graph successfully created at: {self.db_path}")
 

shotgun/codebase/core/manager.py

@@ -371,7 +371,16 @@ class CodebaseGraphManager:
                 )
                 import shutil
 
-                shutil.rmtree(graph_path)
+                # Handle both files and directories (kuzu v0.11.2+ uses files)
+                if graph_path.is_file():
+                    graph_path.unlink()  # Delete file
+                    # Also delete WAL file if it exists
+                    wal_path = graph_path.with_suffix(graph_path.suffix + ".wal")
+                    if wal_path.exists():
+                        wal_path.unlink()
+                        logger.debug(f"Deleted WAL file: {wal_path}")
+                else:
+                    shutil.rmtree(graph_path)  # Delete directory
 
         # Import the builder from local core module
         from shotgun.codebase.core import CodebaseIngestor
@@ -760,7 +769,7 @@ class CodebaseGraphManager:
 
                     lang_config = get_language_config(full_path.suffix)
                     if lang_config and lang_config.name in parsers:
-                        builder._process_single_file(full_path, lang_config.name)
+                        await builder._process_single_file(full_path, lang_config.name)
                         stats["nodes_modified"] += 1  # Approximate
 
             # Process additions
@@ -775,7 +784,7 @@ class CodebaseGraphManager:
 
                     lang_config = get_language_config(full_path.suffix)
                     if lang_config and lang_config.name in parsers:
-                        builder._process_single_file(full_path, lang_config.name)
+                        await builder._process_single_file(full_path, lang_config.name)
                         stats["nodes_added"] += 1  # Approximate
 
             # Flush all pending operations
@@ -1742,7 +1751,7 @@ class CodebaseGraphManager:
             )
 
             # Build the graph
-            builder.run()
+            asyncio.run(builder.run())
 
         # Run build in thread pool
         await anyio.to_thread.run_sync(_build_graph)

shotgun/codebase/core/nl_query.py

@@ -34,7 +34,7 @@ async def llm_cypher_prompt(
     Returns:
         CypherGenerationResponse with cypher_query, can_generate flag, and reason if not
     """
-    model_config = get_provider_model()
+    model_config = await get_provider_model()
 
     # Create an agent with structured output for Cypher generation
     cypher_agent = Agent(

shotgun/llm_proxy/__init__.py

@@ -1,6 +1,9 @@
 """LiteLLM proxy client utilities and configuration."""
 
-from .clients import create_anthropic_proxy_client, create_litellm_provider
+from .clients import (
+    create_anthropic_proxy_provider,
+    create_litellm_provider,
+)
 from .constants import (
     LITELLM_PROXY_ANTHROPIC_BASE,
     LITELLM_PROXY_BASE_URL,
@@ -12,5 +15,5 @@ __all__ = [
     "LITELLM_PROXY_ANTHROPIC_BASE",
     "LITELLM_PROXY_OPENAI_BASE",
     "create_litellm_provider",
-    "create_anthropic_proxy_client",
+    "create_anthropic_proxy_provider",
 ]

shotgun/llm_proxy/clients.py

@@ -1,6 +1,6 @@
 """Client creation utilities for LiteLLM proxy."""
 
-from anthropic import Anthropic
+from pydantic_ai.providers.anthropic import AnthropicProvider
 from pydantic_ai.providers.litellm import LiteLLMProvider
 
 from .constants import LITELLM_PROXY_ANTHROPIC_BASE, LITELLM_PROXY_BASE_URL
@@ -21,19 +21,24 @@ def create_litellm_provider(api_key: str) -> LiteLLMProvider:
     )
 
 
-def create_anthropic_proxy_client(api_key: str) -> Anthropic:
-    """Create Anthropic client configured for LiteLLM proxy.
+def create_anthropic_proxy_provider(api_key: str) -> AnthropicProvider:
+    """Create Anthropic provider configured for LiteLLM proxy.
 
-    This client will proxy token counting requests through the
-    LiteLLM proxy to Anthropic's actual token counting API.
+    This provider uses native Anthropic API format while routing through
+    the LiteLLM proxy. This preserves Anthropic-specific features like
+    tool_choice and web search.
+
+    The provider's .client attribute provides access to the async Anthropic
+    client (AsyncAnthropic), which should be used for all API operations
+    including token counting.
 
     Args:
         api_key: Shotgun API key
 
     Returns:
-        Anthropic client configured to use LiteLLM proxy
+        AnthropicProvider configured to use LiteLLM proxy /anthropic endpoint
     """
-    return Anthropic(
+    return AnthropicProvider(
         api_key=api_key,
         base_url=LITELLM_PROXY_ANTHROPIC_BASE,
     )

shotgun/logging_config.py

@@ -2,12 +2,16 @@
 
 import logging
 import logging.handlers
-import os
 import sys
+from datetime import datetime, timezone
 from pathlib import Path
 
+from shotgun.settings import settings
 from shotgun.utils.env_utils import is_truthy
 
+# Generate a single timestamp for this run to be used across all loggers
+_RUN_TIMESTAMP = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+
 
 def get_log_directory() -> Path:
     """Get the log directory path, creating it if necessary.
@@ -66,21 +70,16 @@ def setup_logger(
     logger = logging.getLogger(name)
 
     # Check if we already have a file handler
-    has_file_handler = any(
-        isinstance(h, logging.handlers.TimedRotatingFileHandler)
-        for h in logger.handlers
-    )
+    has_file_handler = any(isinstance(h, logging.FileHandler) for h in logger.handlers)
 
     # If we already have a file handler, just return the logger
     if has_file_handler:
         return logger
 
-    # Get log level from environment variable, default to INFO
-    env_level = os.getenv("SHOTGUN_LOG_LEVEL", "INFO").upper()
-    if env_level not in ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]:
-        env_level = "INFO"
+    # Get log level from settings (already validated and uppercased)
+    log_level = settings.logging.log_level
 
-    logger.setLevel(getattr(logging, env_level))
+    logger.setLevel(getattr(logging, log_level))
 
     # Default format string
     if format_string is None:
@@ -102,13 +101,13 @@ def setup_logger(
     # Check if console logging is enabled (default: off)
     # Force console logging OFF if Logfire is enabled in dev build
     console_logging_enabled = (
-        is_truthy(os.getenv("LOGGING_TO_CONSOLE", "false")) and not is_logfire_dev_build
+        settings.logging.logging_to_console and not is_logfire_dev_build
     )
 
     if console_logging_enabled:
         # Create console handler
         console_handler = logging.StreamHandler(sys.stdout)
-        console_handler.setLevel(getattr(logging, env_level))
+        console_handler.setLevel(getattr(logging, log_level))
 
         # Use colored formatter for console
         console_formatter = ColoredFormatter(format_string, datefmt="%H:%M:%S")
@@ -118,26 +117,21 @@ def setup_logger(
         logger.addHandler(console_handler)
 
     # Check if file logging is enabled (default: on)
-    file_logging_enabled = is_truthy(os.getenv("LOGGING_TO_FILE", "true"))
+    file_logging_enabled = settings.logging.logging_to_file
 
     if file_logging_enabled:
         try:
-            # Create file handler with rotation
+            # Create file handler with ISO8601 timestamp for each run
             log_dir = get_log_directory()
-            log_file = log_dir / "shotgun.log"
+            log_file = log_dir / f"shotgun-{_RUN_TIMESTAMP}.log"
 
-            # Use TimedRotatingFileHandler - rotates daily and keeps 7 days of logs
-            file_handler = logging.handlers.TimedRotatingFileHandler(
+            # Use regular FileHandler - each run gets its own isolated log file
+            file_handler = logging.FileHandler(
                 filename=log_file,
-                when="midnight",  # Rotate at midnight
-                interval=1,  # Every 1 day
-                backupCount=7,  # Keep 7 days of logs
                 encoding="utf-8",
             )
 
-            # Also set max file size (10MB) using RotatingFileHandler as fallback
-            # Note: We'll use TimedRotatingFileHandler which handles both time and size
-            file_handler.setLevel(getattr(logging, env_level))
+            file_handler.setLevel(getattr(logging, log_level))
 
             # Use standard formatter for file (no colors)
             file_formatter = logging.Formatter(
@@ -191,10 +185,7 @@ def get_logger(name: str) -> logging.Logger:
     logger = logging.getLogger(name)
 
     # Check if we have a file handler already
-    has_file_handler = any(
-        isinstance(h, logging.handlers.TimedRotatingFileHandler)
-        for h in logger.handlers
-    )
+    has_file_handler = any(isinstance(h, logging.FileHandler) for h in logger.handlers)
 
     # If no file handler, set up the logger (will add file handler)
     if not has_file_handler:

shotgun/main.py

@@ -23,8 +23,11 @@ from dotenv import load_dotenv
 from shotgun import __version__
 from shotgun.agents.config import get_config_manager
 from shotgun.cli import (
+    clear,
     codebase,
+    compact,
     config,
+    context,
     export,
     feedback,
     plan,
@@ -53,8 +56,10 @@ logger.debug("Logfire observability enabled: %s", _logfire_enabled)
 
 # Initialize configuration
 try:
+    import asyncio
+
     config_manager = get_config_manager()
-    config_manager.load()  # Ensure config is loaded at startup
+    asyncio.run(config_manager.load())  # Ensure config is loaded at startup
 except Exception as e:
     logger.debug("Configuration initialization warning: %s", e)
 
@@ -78,6 +83,9 @@ app.add_typer(config.app, name="config", help="Manage Shotgun configuration")
 app.add_typer(
     codebase.app, name="codebase", help="Manage and query code knowledge graphs"
 )
+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")
@@ -125,6 +133,41 @@ def main(
             help="Continue previous TUI conversation",
         ),
     ] = False,
+    web: Annotated[
+        bool,
+        typer.Option(
+            "--web",
+            help="Serve TUI as web application",
+        ),
+    ] = False,
+    port: Annotated[
+        int,
+        typer.Option(
+            "--port",
+            help="Port for web server (only used with --web)",
+        ),
+    ] = 8000,
+    host: Annotated[
+        str,
+        typer.Option(
+            "--host",
+            help="Host address for web server (only used with --web)",
+        ),
+    ] = "localhost",
+    public_url: Annotated[
+        str | None,
+        typer.Option(
+            "--public-url",
+            help="Public URL if behind proxy (only used with --web)",
+        ),
+    ] = None,
+    force_reindex: Annotated[
+        bool,
+        typer.Option(
+            "--force-reindex",
+            help="Force re-indexing of codebase (ignores existing index)",
+        ),
+    ] = False,
 ) -> None:
     """Shotgun - AI-powered CLI tool."""
     logger.debug("Starting shotgun CLI application")
@@ -134,16 +177,35 @@ def main(
         perform_auto_update_async(no_update_check=no_update_check)
 
     if ctx.invoked_subcommand is None and not ctx.resilient_parsing:
-        logger.debug("Launching shotgun TUI application")
-        try:
-            tui_app.run(
-                no_update_check=no_update_check, continue_session=continue_session
-            )
-        finally:
-            # Ensure PostHog is shut down cleanly even if TUI exits unexpectedly
-            from shotgun.posthog_telemetry import shutdown
-
-            shutdown()
+        if web:
+            logger.debug("Launching shotgun TUI as web application")
+            try:
+                tui_app.serve(
+                    host=host,
+                    port=port,
+                    public_url=public_url,
+                    no_update_check=no_update_check,
+                    continue_session=continue_session,
+                    force_reindex=force_reindex,
+                )
+            finally:
+                # Ensure PostHog is shut down cleanly even if server exits unexpectedly
+                from shotgun.posthog_telemetry import shutdown
+
+                shutdown()
+        else:
+            logger.debug("Launching shotgun TUI application")
+            try:
+                tui_app.run(
+                    no_update_check=no_update_check,
+                    continue_session=continue_session,
+                    force_reindex=force_reindex,
+                )
+            finally:
+                # Ensure PostHog is shut down cleanly even if TUI exits unexpectedly
+                from shotgun.posthog_telemetry import shutdown
+
+                shutdown()
         raise typer.Exit()
 
     # For CLI commands, register PostHog shutdown handler

shotgun/posthog_telemetry.py

@@ -10,6 +10,7 @@ from shotgun import __version__
 from shotgun.agents.config import get_config_manager
 from shotgun.agents.conversation_manager import ConversationManager
 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__)
@@ -32,10 +33,15 @@ def setup_posthog_observability() -> bool:
             logger.debug("PostHog is already initialized, skipping")
             return True
 
-        # Hardcoded PostHog configuration
-        api_key = "phc_KKnChzZUKeNqZDOTJ6soCBWNQSx3vjiULdwTR9H5Mcr"
+        # Get API key from settings (handles build constants + env vars automatically)
+        api_key = settings.telemetry.posthog_api_key
 
-        logger.debug("Using hardcoded PostHog configuration")
+        # If no API key is available, skip PostHog initialization
+        if not api_key:
+            logger.debug("No PostHog API key available, skipping initialization")
+            return False
+
+        logger.debug("Using PostHog API key from settings")
 
         # Determine environment based on version
         # Dev versions contain "dev", "rc", "alpha", or "beta"
@@ -53,8 +59,10 @@ def setup_posthog_observability() -> bool:
 
         # Set user context with anonymous shotgun instance ID from config
         try:
+            import asyncio
+
             config_manager = get_config_manager()
-            shotgun_instance_id = config_manager.get_shotgun_instance_id()
+            shotgun_instance_id = asyncio.run(config_manager.get_shotgun_instance_id())
 
             # Identify the user in PostHog
             posthog.identify(  # type: ignore[attr-defined]
@@ -101,9 +109,11 @@ def track_event(event_name: str, properties: dict[str, Any] | None = None) -> No
         return
 
     try:
+        import asyncio
+
         # Get shotgun instance ID for tracking
         config_manager = get_config_manager()
-        shotgun_instance_id = config_manager.get_shotgun_instance_id()
+        shotgun_instance_id = asyncio.run(config_manager.get_shotgun_instance_id())
 
         # Add version and environment to properties
         if properties is None:
@@ -162,10 +172,16 @@ def submit_feedback_survey(feedback: Feedback) -> None:
         logger.debug("PostHog not initialized, skipping feedback survey")
         return
 
+    import asyncio
+
     config_manager = get_config_manager()
-    config = config_manager.load()
+    config = asyncio.run(config_manager.load())
     conversation_manager = ConversationManager()
-    conversation = conversation_manager.load()
+    conversation = None
+    try:
+        conversation = asyncio.run(conversation_manager.load())
+    except Exception as e:
+        logger.debug(f"Failed to load conversation history: {e}")
     last_10_messages = []
     if conversation is not None:
         last_10_messages = conversation.get_agent_messages()[:10]

shotgun/prompts/agents/export.j2

@@ -124,6 +124,7 @@ content_tasks = read_file('tasks.md')         # Read implementation details
    - `plan.md` - Extract development approach and stages
    - `tasks.md` - Understand implementation tasks and structure
 2. **Map content to agents.md standard sections**:
+   - **Research, Specifications, and Planning**: ALWAYS include this section first. Check which pipeline files exist in `.shotgun/` (research.md, specification.md, plan.md, tasks.md) and list only the ones that exist. If none exist, omit this section.
    - **Project Overview**: Brief description and key technologies from specification.md
    - **Dev Environment Setup**: Installation, dependencies, dev server commands
    - **Code Style Guidelines**: Coding conventions and patterns from research.md
@@ -170,6 +171,14 @@ For additional specialized exports (only if specifically requested):
 <CORRECT_CONTENT_TEMPLATE>
 # Agents.md - [Project Name]
 
+## Research, Specifications, and Planning
+
+The `.shotgun/` folder contains background research, specifications, and implementation planning files. Refer to these files for additional context:
+- `research.md` - Codebase analysis and research findings
+- `specification.md` - Project requirements and specifications
+- `plan.md` - Development plan and implementation approach
+- `tasks.md` - Task breakdown and implementation progress
+
 ## Project Overview
 - Brief description of what the project does
 - Key technologies and frameworks used
@@ -253,6 +262,14 @@ This project is about [making assumptions without reading files]...
 <GOOD_CONTENT_EXAMPLE>
 # Agents.md - E-commerce API Project
 
+## Research, Specifications, and Planning
+
+The `.shotgun/` folder contains background research, specifications, and implementation planning files. Refer to these files for additional context:
+- `research.md` - Codebase analysis and research findings
+- `specification.md` - Project requirements and specifications
+- `plan.md` - Development plan and implementation approach
+- `tasks.md` - Task breakdown and implementation progress
+
 ## Project Overview
 - REST API for product catalog management with authentication
 - Built with Python/FastAPI for high performance async operations
@@ -316,7 +333,7 @@ This project is about [making assumptions without reading files]...
 USER INTERACTION - CLARIFY EXPORT REQUIREMENTS:
 
 - ALWAYS ask clarifying questions when export requirements are unclear
-- Use ask_user tool to gather specific details about:
+- Use clarifying questions to gather specific details about:
   - Target format and file type preferences
   - Intended use case and audience for the export
   - Specific content sections to include/exclude from files