diff --git a/.cursor/rules/cleanup.mdc b/.cursor/rules/cleanup.mdc
index f672857..1356560 100644
--- a/.cursor/rules/cleanup.mdc
+++ b/.cursor/rules/cleanup.mdc
@@ -1,9 +1,68 @@
-# Cleanup Logic Guide
-
-- [manager.py](mdc:src/cleanup/manager.py) manages cleanup operations and resource management.
-- [modes.py](mdc:src/cleanup/modes.py) defines cleanup modes and strategies.
-- This directory is responsible for resource cleanup and related logic.
-description:
-globs:
-alwaysApply: false
 ---
+description: Comprehensive guide for account cleanup operations and resource management. Apply when working with token account cleanup operations.
+globs: src/cleanup/*.py
+alwaysApply: true
+---
+
+# Account Cleanup System Guide
+
+## Overview
+
+The cleanup module handles the safe management and disposal of Solana token accounts after trading operations. This system ensures resources are properly released and minimizes unnecessary account maintenance fees.
+
+## Core Components
+
+### AccountCleanupManager
+
+@src/cleanup/manager.py implements the `AccountCleanupManager` class which:
+- Handles safe cleanup of Associated Token Accounts (ATAs)
+- Manages token burning operations when needed
+- Implements proper account closure to recover rent
+- Integrates with priority fee systems for high-congestion scenarios
+
+```python
+# Example usage
+cleanup_manager = AccountCleanupManager(client, wallet, priority_fee_manager, use_priority_fees)
+await cleanup_manager.cleanup_ata(token_mint)
+```
+
+### Cleanup Modes
+
+@src/cleanup/modes.py defines various cleanup strategies and their implementation:
+
+1. **Disabled** - No automatic cleanup performed
+2. **On Failure** - Clean up accounts only after transaction failures
+3. **After Sell** - Clean up accounts after successful sell operations
+4. **Post-Session** - Clean up all empty accounts when a trading session ends
+
+```python
+# Example implementation
+if should_cleanup_after_sell(cleanup_mode):
+    await manager.cleanup_ata(mint)
+```
+
+## Configuration
+
+Account cleanup is configured in bot YAML files:
+
+```yaml
+cleanup:
+  mode: "post_session"          # Options: "disabled", "on_fail", "after_sell", "post_session"
+  force_close_with_burn: false  # Force burn remaining tokens before closing
+  with_priority_fee: false      # Use priority fees for cleanup transactions
+```
+
+## When to Use Each Mode
+
+| Mode | Use Case |
+|------|----------|
+| `disabled` | Development/testing or when manual account management is preferred |
+| `on_fail` | Conservative approach to only clean up failed transaction remnants |
+| `after_sell` | Balance between efficiency and account reuse |
+| `post_session` | Maximum cleanup, recommended for production |
+
+## Related Files
+
+- @src/cleanup/manager.py: Core account cleanup implementation
+- @src/cleanup/modes.py: Cleanup mode strategies and handlers
+- @src/core/client.py: Solana client interface used by cleanup operations
diff --git a/.cursor/rules/core.mdc b/.cursor/rules/core.mdc
index da6b816..31d62c5 100644
--- a/.cursor/rules/core.mdc
+++ b/.cursor/rules/core.mdc
@@ -1,11 +1,76 @@
-# Core Logic Guide
-
-- [client.py](mdc:src/core/client.py) handles blockchain client interactions.
-- [wallet.py](mdc:src/core/wallet.py) manages wallet logic.
-- [pubkeys.py](mdc:src/core/pubkeys.py) stores and manages public keys.
-- [curve.py](mdc:src/core/curve.py) provides curve math and related utilities.
-- This directory contains core abstractions and logic for blockchain and protocol interactions.
-description:
-globs:
-alwaysApply: false
 ---
+description: Core blockchain interaction components and Solana protocol abstractions. Apply when working with blockchain operations, transactions, or protocol-specific logic.
+globs: src/core/*.py
+alwaysApply: true
+---
+
+# Core Blockchain Components Guide
+
+## Overview
+
+The core module provides essential abstractions and utilities for interacting with the Solana blockchain, managing wallets, handling transactions, and working with protocol-specific logic such as bonding curves and token operations.
+
+## Key Components
+
+### Solana Client
+
+@src/core/client.py implements the `SolanaClient` class which:
+- Handles RPC communication with Solana nodes
+- Manages transaction submission and confirmation
+- Provides methods for account data retrieval and subscription
+- Implements retry logic and error handling for blockchain operations
+
+```python
+# Example usage
+client = SolanaClient(rpc_endpoint, wss_endpoint)
+await client.get_token_account_data(token_account)
+```
+
+### Wallet Management
+
+@src/core/wallet.py provides wallet functionality:
+- Secure private key handling
+- Transaction signing
+- Account derivation and management
+- Integration with hardware wallets (where applicable)
+
+### Public Key Management
+
+@src/core/pubkeys.py contains:
+- System address constants
+- Program ID references
+- Address derivation utilities
+- Token account resolution functions
+
+### Bonding Curve Mathematics
+
+@src/core/curve.py offers:
+- Mathematical models for bonding curve calculations
+- Price impact estimation
+- Liquidity modeling
+- Swap pricing utilities
+
+### Priority Fee Management
+
+@src/core/priority_fee/manager.py implements:
+- Dynamic priority fee calculation
+- Fee cap enforcement
+- Network congestion detection
+- Transaction prioritization strategies
+
+## Common Operations
+
+| Operation | Key Functions |
+|-----------|--------------|
+| Send Transaction | `client.send_transaction(tx, opts)` |
+| Get Account Data | `client.get_account_info(pubkey)` |
+| Sign Message | `wallet.sign_message(message)` |
+| Calculate Price | `curve.calculate_price_impact(amount)` |
+
+## Related Files
+
+- @src/core/client.py: Solana RPC client implementation
+- @src/core/wallet.py: Wallet and signing functionality
+- @src/core/pubkeys.py: Address management and derivation
+- @src/core/curve.py: Bonding curve and pricing mathematics
+- @src/core/priority_fee/manager.py: Transaction fee optimization
diff --git a/.cursor/rules/idl.mdc b/.cursor/rules/idl.mdc
index af22eca..93429e6 100644
--- a/.cursor/rules/idl.mdc
+++ b/.cursor/rules/idl.mdc
@@ -1,8 +1,89 @@
+---
+description: Program interface definitions for on-chain contract interactions. Apply when working with smart contract integration or program data structures.
+globs: idl/*.json
+alwaysApply: true
+---
+
 # Interface Definition Guide
 
-- JSON files in this directory define program interfaces (IDLs) for interacting with on-chain programs.
-- These files are used for serialization, deserialization, and program interaction logic.
-description:
-globs:
-alwaysApply: false
----
+## Overview
+
+The IDL (Interface Definition Language) files define the structure and interface of on-chain Solana programs. These definitions enable the bot to interact with smart contracts, serialize/deserialize data, and interpret on-chain events correctly.
+
+## Core IDL Files
+
+### Pump Fun IDL
+
+@idl/pump_fun_idl.json contains the core protocol definitions:
+- Main pump.fun protocol instruction schemas
+- Account structures and data layouts
+- Token creation and management instructions
+- Event definitions and discriminators
+
+### Pump Swap IDL
+
+@idl/pump_swap_idl.json defines the swap interface:
+- Token swap instruction formats
+- Liquidity management operations
+- Price calculation functions
+- Fee structure definitions
+
+### Raydium AMM IDL
+
+@idl/raydium_amm_idl.json provides integration with Raydium:
+- AMM pool interface definitions
+- Liquidity provider instructions
+- Market making operations
+- Price discovery mechanisms
+
+## Working with IDLs
+
+IDL files are used throughout the codebase for:
+
+```python
+# Example: Using IDLs for instruction building
+with open("idl/pump_fun_idl.json", "r") as f:
+    pump_idl = json.load(f)
+    
+# Extract instruction discriminator
+discriminator = bytes(pump_idl["instructions"][0]["discriminator"])
+```
+
+## IDL Structure
+
+Each IDL file follows this structure:
+
+```json
+{
+  "address": "Program address on chain",
+  "metadata": {
+    "name": "Program name",
+    "version": "Version number"
+  },
+  "instructions": [
+    {
+      "name": "instructionName",
+      "discriminator": [byte array],
+      "accounts": [...],
+      "args": [...]
+    }
+  ],
+  "accounts": [...],
+  "events": [...]
+}
+```
+
+## IDL Usage
+
+| Component | Usage |
+|-----------|-------|
+| Instructions | Building transaction instructions |
+| Discriminators | Identifying program events in logs |
+| Accounts | Parsing account data |
+| Events | Interpreting program-emitted events |
+
+## Related Files
+
+- @idl/pump_fun_idl.json: Main pump.fun protocol definition
+- @idl/pump_swap_idl.json: Swap functionality interface
+- @idl/raydium_amm_idl.json: Raydium AMM integration
diff --git a/.cursor/rules/monitoring.mdc b/.cursor/rules/monitoring.mdc
index 6a4037e..c2e223c 100644
--- a/.cursor/rules/monitoring.mdc
+++ b/.cursor/rules/monitoring.mdc
@@ -1,9 +1,96 @@
-# Monitoring Logic Guide
-
-- Listener files (e.g., [pumpportal_listener.py](mdc:src/monitoring/pumpportal_listener.py), [logs_listener.py](mdc:src/monitoring/logs_listener.py), [geyser_listener.py](mdc:src/monitoring/geyser_listener.py), [block_listener.py](mdc:src/monitoring/block_listener.py)) are responsible for subscribing to and receiving events from various sources.
-- Event processor files (e.g., [pumpportal_event_processor.py](mdc:src/monitoring/pumpportal_event_processor.py), [logs_event_processor.py](mdc:src/monitoring/logs_event_processor.py), [geyser_event_processor.py](mdc:src/monitoring/geyser_event_processor.py), [block_event_processor.py](mdc:src/monitoring/block_event_processor.py)) handle the logic for processing and reacting to those events.
-- [base_listener.py](mdc:src/monitoring/base_listener.py) provides shared abstractions for listeners.
-description:
-globs:
-alwaysApply: false
 ---
+description: Event monitoring and data collection systems for tracking blockchain activity. Apply when implementing token detection, event processing, or subscription logic.
+globs: src/monitoring/*.py
+alwaysApply: true
+---
+
+# Monitoring System Guide
+
+## Overview
+
+The monitoring module provides various mechanisms to detect and process events from the Solana blockchain. It offers multiple strategies for token discovery, event filtering, and real-time notifications through different data sources.
+
+## Listener Architecture
+
+### Base Listener
+
+@src/monitoring/base_listener.py defines the abstract base class `BaseTokenListener` which:
+- Provides a common interface for all token listeners
+- Declares required methods for event subscription
+- Standardizes token event processing
+
+```python
+# Common listener interface
+async def listen_for_tokens(
+    self,
+    token_callback: Callable[[TokenInfo], Awaitable[None]],
+    match_string: str | None = None,
+    creator_address: str | None = None,
+) -> None:
+    pass
+```
+
+### Listener Implementations
+
+#### Geyser Listener (Fastest)
+
+@src/monitoring/geyser_listener.py implements the Geyser-based listener:
+- Direct connection to Geyser WebSocket endpoint
+- Lowest latency for token detection
+- Advanced filtering capabilities
+
+#### Logs Listener
+
+@src/monitoring/logs_listener.py provides log-based monitoring:
+- Subscription to program logs
+- Pattern matching for token creation events
+- Program-specific event detection
+
+#### Block Listener
+
+@src/monitoring/block_listener.py implements block-based scanning:
+- Processes entire blocks
+- Extracts transaction data
+- Identifies token creation events
+
+#### PumpPortal Listener
+
+@src/monitoring/pumpportal_listener.py offers integration with external service:
+- Connects to PumpPortal API
+- Receives preprocessed token events
+- Simplifies integration with third-party data providers
+
+## Event Processing
+
+Each listener has a corresponding event processor that:
+- Validates incoming events
+- Extracts relevant token information
+- Applies filtering rules
+- Dispatches events to trading components
+
+## Configuration
+
+In bot configuration files, specify the listener type:
+
+```yaml
+filters:
+  listener_type: "geyser"  # Options: "logs", "blocks", "geyser", "pumpportal"
+  max_token_age: 0.001     # Maximum token age in seconds
+```
+
+## Comparison of Approaches
+
+| Listener Type | Latency | CPU Usage | Reliability | Use Case |
+|---------------|---------|-----------|-------------|----------|
+| Geyser        | Lowest  | Medium    | High        | Production sniper bots |
+| Logs          | Low     | Low       | High        | General purpose |
+| Blocks        | Medium  | High      | Very High   | Deep scanning |
+| PumpPortal    | Varies  | Very Low  | Depends     | Easy integration |
+
+## Related Files
+
+- @src/monitoring/base_listener.py: Abstract listener interface
+- @src/monitoring/geyser_listener.py: Geyser-based implementation
+- @src/monitoring/logs_listener.py: Program log monitoring
+- @src/monitoring/block_listener.py: Block processing implementation
+- @src/monitoring/pumpportal_listener.py: External API integration
diff --git a/.cursor/rules/project-structure.mdc b/.cursor/rules/project-structure.mdc
index 5d97e0b..2f6665b 100644
--- a/.cursor/rules/project-structure.mdc
+++ b/.cursor/rules/project-structure.mdc
@@ -1,17 +1,109 @@
+---
+description: Comprehensive overview of the project architecture and organization. Apply when working with the codebase structure or integrating new components.
+globs: *.md
+alwaysApply: true
+---
+
 # Project Structure Guide
 
-- The main source code is in the [src/](mdc:src/) directory.
-- Trading logic is in [src/trading/](mdc:src/trading/), including [trader.py](mdc:src/trading/trader.py), [buyer.py](mdc:src/trading/buyer.py), and [seller.py](mdc:src/trading/seller.py).
-- Monitoring logic is in [src/monitoring/](mdc:src/monitoring/), with various listeners and event processors.
-- Utility functions are in [src/utils/](mdc:src/utils/).
-- Core abstractions and blockchain logic are in [src/core/](mdc:src/core/).
-- Cleanup logic is in [src/cleanup/](mdc:src/cleanup/).
-- Geyser-related code is in [src/geyser/](mdc:src/geyser/).
-- Bot configuration files are in [bots/](mdc:bots/).
-- Trade logs are in [trades/](mdc:trades/).
-- Interface definitions are in [idl/](mdc:idl/).
-- Tests are in [tests/](mdc:tests/).
-description:
-globs:
-alwaysApply: false
----
+## Overview
+
+The pump-bot system is organized into modular components with clear separation of concerns. This architecture facilitates maintainability, testing, and extension of functionality.
+
+## Directory Structure
+
+### Source Code
+
+The main codebase is organized as follows:
+
+- @src/: Root source directory
+  - @src/bot_runner.py: Entry point for bot execution
+  - @src/config_loader.py: Configuration loading and validation
+
+#### Core Components
+
+- @src/core/: Blockchain interaction and protocol abstractions
+  - @src/core/client.py: Solana client implementation
+  - @src/core/wallet.py: Wallet management and transaction signing
+  - @src/core/pubkeys.py: System and program addresses
+  - @src/core/curve.py: Bonding curve mathematics
+  - @src/core/priority_fee/: Priority fee optimization system
+
+#### Trading System
+
+- @src/trading/: Trading execution and strategy
+  - @src/trading/trader.py: Main trading coordination
+  - @src/trading/buyer.py: Token purchase implementation
+  - @src/trading/seller.py: Token sale implementation
+  - @src/trading/position.py: Position tracking and management
+  - @src/trading/base.py: Shared abstractions
+
+#### Monitoring System
+
+- @src/monitoring/: Event detection and processing
+  - @src/monitoring/geyser_listener.py: Geyser-based monitoring
+  - @src/monitoring/logs_listener.py: Log-based monitoring
+  - @src/monitoring/block_listener.py: Block-based monitoring
+  - @src/monitoring/pumpportal_listener.py: PumpPortal integration
+  - @src/monitoring/base_listener.py: Shared listener abstractions
+
+#### Resource Management
+
+- @src/cleanup/: Token account management
+  - @src/cleanup/manager.py: Account cleanup operations
+  - @src/cleanup/modes.py: Cleanup strategy implementation
+
+#### Utilities
+
+- @src/utils/: Shared utilities
+  - @src/utils/logger.py: Logging framework
+  - @src/utils/env.py: Environment configuration
+
+### Configuration
+
+- @bots/: Bot configuration files
+  - @bots/bot-sniper-1-geyser.yaml: Geyser-based sniper configuration
+  - @bots/bot-sniper-2-logs.yaml: Log-based sniper configuration
+  - @bots/bot-sniper-3-blocks.yaml: Block-based sniper configuration
+  - @bots/bot-sniper-4-pp.yaml: PumpPortal sniper configuration
+
+### Program Interfaces
+
+- @idl/: Interface definitions for on-chain programs
+  - @idl/pump_fun_idl.json: Pump.fun protocol interface
+  - @idl/pump_swap_idl.json: Swap interface definition
+  - @idl/raydium_amm_idl.json: Raydium AMM interface
+
+### Testing
+
+- @tests/: Test cases and validation
+  - @tests/compare_listeners.py: Listener comparison framework
+  - @tests/test_geyser_listener.py: Geyser listener tests
+  - @tests/test_logs_listener.py: Logs listener tests
+  - @tests/test_block_listener.py: Block listener tests
+
+### Operational Data
+
+- @logs/: Application logs
+- @trades/: Trading activity records
+
+## Development Flow
+
+1. Configure bot parameters in @bots/*.yaml
+2. Launch bot using @src/bot_runner.py
+3. Monitor execution in @logs/
+4. Review trade outcomes in @trades/trades.log
+
+## Architecture Principles
+
+1. **Modular Design**: Components have clear responsibilities and interfaces
+2. **Configurability**: External configuration for adjustable behavior
+3. **Extensibility**: Easy to add new listeners or trading strategies
+4. **Reliability**: Error handling and recovery throughout the system
+5. **Observability**: Comprehensive logging and monitoring
+
+## Related Documents
+
+- @README.md: Project overview and setup instructions
+- @MAINTAINERS.md: Maintenance guidelines and procedures
+- @CLAUDE.md: Integration with Claude AI for strategy development
diff --git a/.cursor/rules/tests.mdc b/.cursor/rules/tests.mdc
index 3c8642a..306d8b8 100644
--- a/.cursor/rules/tests.mdc
+++ b/.cursor/rules/tests.mdc
@@ -1,9 +1,87 @@
+---
+description: Testing framework and test cases for system validation. Apply when writing tests or performing system validation.
+globs: tests/*.py
+alwaysApply: true
+---
+
 # Testing Guide
 
-- Python files in this directory contain tests for listeners and other core components.
-- Tests are organized by component type (e.g., geyser, logs, block listeners).
-- [compare_listeners.py](mdc:tests/compare_listeners.py) is used for comparing listener outputs.
-description:
-globs:
-alwaysApply: false
----
+## Overview
+
+The testing framework provides validation for key components of the pump-bot system, focusing on listener accuracy, trading execution, and system integration. Tests ensure reliability and proper functioning of critical bot operations.
+
+## Test Organization
+
+### Listener Tests
+
+Multiple implementations are tested for correctness and performance:
+
+- @tests/test_geyser_listener.py: Tests the Geyser-based implementation
+- @tests/test_logs_listener.py: Validates log-based token detection
+- @tests/test_block_listener.py: Verifies block scanning functionality
+
+### Comparison Testing
+
+@tests/compare_listeners.py provides comparative analysis:
+- Side-by-side execution of different listener implementations
+- Latency measurement and comparison
+- Detection reliability metrics
+- False positive/negative analysis
+
+```python
+# Example comparison usage
+python -m tests.compare_listeners --duration 600 --output-file results.json
+```
+
+## Test Configuration
+
+Tests use environment variables for configuration:
+- Connection endpoints
+- API keys
+- Test durations
+- Output verbosity
+
+```bash
+# Example test execution
+SOLANA_NODE_RPC_ENDPOINT=https://api.mainnet-beta.solana.com \
+GEYSER_ENDPOINT=wss://geyser.example.com/subscribe \
+python -m tests.test_geyser_listener
+```
+
+## Test Data
+
+The test suite includes:
+- Mock token creation events
+- Historical transaction data
+- Performance benchmarks
+- Edge case scenarios
+
+## Running Tests
+
+### Individual Component Tests
+
+```bash
+# Run a specific listener test
+python -m tests.test_logs_listener
+
+# Run with custom parameters
+python -m tests.test_block_listener --duration 60
+```
+
+### Full Test Suite
+
+```bash
+# Run all tests
+python -m pytest tests/
+
+# Run with coverage report
+python -m pytest --cov=src tests/
+```
+
+## Related Files
+
+- @tests/test_geyser_listener.py: Geyser listener validation
+- @tests/test_logs_listener.py: Logs listener validation
+- @tests/test_block_listener.py: Block listener validation
+- @tests/compare_listeners.py: Comparative listener analysis
+- @tests/test_trading.py: Trading execution validation
diff --git a/.cursor/rules/trading.mdc b/.cursor/rules/trading.mdc
index f9f57f8..549ab46 100644
--- a/.cursor/rules/trading.mdc
+++ b/.cursor/rules/trading.mdc
@@ -1,11 +1,92 @@
-# Trading Logic Guide
-
-- [trader.py](mdc:src/trading/trader.py) is the main entry point for trading operations, orchestrating buy and sell actions.
-- [buyer.py](mdc:src/trading/buyer.py) implements logic for buying assets.
-- [seller.py](mdc:src/trading/seller.py) implements logic for selling assets.
-- [position.py](mdc:src/trading/position.py) manages trading positions.
-- [base.py](mdc:src/trading/base.py) provides base classes and shared abstractions for trading components.
-description:
-globs:
-alwaysApply: false
 ---
+description: Core trading functionality including buy/sell operations, position management, and execution strategies. Apply when working with trading logic or transaction execution.
+globs: src/trading/*.py
+alwaysApply: true
+---
+
+# Trading System Guide
+
+## Overview
+
+The trading module forms the core of the pump-bot's execution capabilities, handling token purchases, sales, position management, and trading strategy implementation. This system translates token detection events into actual on-chain transactions.
+
+## Core Components
+
+### Trading Coordinator
+
+@src/trading/trader.py implements the `PumpTrader` class which:
+- Orchestrates the entire trading lifecycle
+- Manages token detection to execution flow
+- Implements risk management controls
+- Coordinates buy and sell operations
+- Handles position tracking and reporting
+
+```python
+# Example usage
+trader = PumpTrader(config, client, wallet)
+await trader.process_token(token_info)
+```
+
+### Buy Operations
+
+@src/trading/buyer.py provides the `TokenBuyer` class:
+- Implements token purchase logic
+- Handles slippage calculation and management
+- Creates and submits buy transactions
+- Validates transaction success
+
+### Sell Operations
+
+@src/trading/seller.py implements the `TokenSeller` class:
+- Manages token selling operations
+- Implements various exit strategies
+- Handles profit calculation and optimization
+- Ensures proper transaction construction
+
+### Position Management
+
+@src/trading/position.py offers position tracking:
+- Records entry and exit prices
+- Calculates profit/loss metrics
+- Manages position state throughout lifecycle
+- Implements risk management boundaries
+
+### Base Abstractions
+
+@src/trading/base.py defines core abstractions:
+- Common interfaces for trading components
+- Shared data structures
+- Type definitions and constants
+- Interface contracts for strategy implementations
+
+## Trading Strategies
+
+The system supports multiple exit strategies:
+
+1. **Time-Based**: Automatically sells after a configurable holding period
+2. **TP/SL**: Uses Take Profit / Stop Loss targets to manage exits
+3. **Manual**: Requires explicit sell commands
+
+```yaml
+# Configuration example
+trade:
+  exit_strategy: "tp_sl"
+  take_profit_percentage: 0.2
+  stop_loss_percentage: 0.2
+```
+
+## Common Trading Flows
+
+| Operation | Flow |
+|-----------|------|
+| Token Purchase | Detection → Validation → Buy Transaction → Position Creation |
+| Token Sale | Strategy Trigger → Position Update → Sell Transaction → Cleanup |
+| Error Handling | Error Detection → Transaction Retry → Position Closure → Cleanup |
+
+## Related Files
+
+- @src/trading/trader.py: Main trading coordination
+- @src/trading/buyer.py: Buy transaction implementation
+- @src/trading/seller.py: Sell transaction implementation
+- @src/trading/position.py: Position tracking and management
+- @src/trading/base.py: Core abstractions and interfaces
diff --git a/.cursor/rules/utils.mdc b/.cursor/rules/utils.mdc
index 27d7b11..729c071 100644
--- a/.cursor/rules/utils.mdc
+++ b/.cursor/rules/utils.mdc
@@ -1,8 +1,44 @@
+---
+description: Shared utilities and helper functions for common operations. Apply when working with project-wide utilities.
+globs: src/utils/*.py
+alwaysApply: true
+---
+
 # Utility Functions Guide
 
-- [logger.py](mdc:src/utils/logger.py) provides logging utilities for the project.
-- Utility modules in this directory are intended for shared, reusable helper functions and classes.
-description:
-globs:
-alwaysApply: false
----
+## Overview
+
+The utils module provides shared functionality and helper methods used throughout the pump-bot system. These utilities handle common concerns like logging.
+
+## Core Utilities
+
+### Logging
+
+@src/utils/logger.py implements a centralized logging system:
+- Consistent log formatting across the application
+- Log level management
+- File and console output handling
+- Context-aware logging with component identification
+
+```python
+# Example usage
+logger = get_logger(__name__)
+logger.info("Processing token %s", token_mint)
+```
+
+## Common Patterns
+
+| Operation | Utility |
+|-----------|---------|
+| Logging | `get_logger(__name__)` |
+
+## Best Practices
+
+1. **Reuse existing utilities** rather than implementing similar functionality
+2. **Keep utilities focused** on a single responsibility
+3. **Document usage examples** for each utility
+4. **Maintain backward compatibility** when enhancing utilities
+
+## Related Files
+
+- @src/utils/logger.py: Centralized logging system