diff --git a/AI_AGENT.md b/AI_AGENT.md
index 20811aa..4db1f0c 100644
--- a/AI_AGENT.md
+++ b/AI_AGENT.md
@@ -4,44 +4,67 @@
 
 This is a Python Terminal User Interface (TUI) application for managing media files. It uses the Textual library to provide a curses-like interface in the terminal. The app allows users to scan directories for video files, display them in a hierarchical tree view, view detailed metadata information including video, audio, and subtitle tracks, and rename files based on intelligent metadata extraction.
 
+**Current Version**: 0.5.10
+
 Key features:
-- Recursive directory scanning
+- Recursive directory scanning with tree navigation
+- Dual-mode display: Technical (codec/track details) and Catalog (TMDB metadata with posters)
 - Tree-based file navigation with expand/collapse functionality
-- Detailed metadata extraction from multiple sources
-- Intelligent file renaming with proposed names
+- Multi-source metadata extraction (MediaInfo, filename parsing, embedded tags, TMDB API)
+- Intelligent file renaming with proposed names and confirmation
+- Settings management with persistent configuration
+- Advanced caching system with TTL (6h extractors, 6h TMDB, 30d posters)
+- Terminal poster display using rich-pixels
 - Color-coded information display
 - Keyboard and mouse navigation
-- Multiple UI screens (main app, directory selection, help, rename confirmation)
+- Multiple UI screens (main app, directory selection, help, rename confirmation, settings)
 - Extensible extractor and formatter architecture
-- Loading indicators and error handling
+- Loading indicators and comprehensive error handling
 
 ## Technology Stack
 
 - Python 3.11+
-- Textual (TUI framework)
-- PyMediaInfo (detailed track information)
-- Mutagen (embedded metadata)
-- Python-Magic (MIME type detection)
-- Langcodes (language code handling)
-- UV (package manager)
+- Textual ≥6.11.0 (TUI framework)
+- PyMediaInfo ≥6.0.0 (detailed track information)
+- Mutagen ≥1.47.0 (embedded metadata)
+- Python-Magic ≥0.4.27 (MIME type detection)
+- Langcodes ≥3.5.1 (language code handling)
+- Requests ≥2.31.0 (HTTP client for TMDB API)
+- Rich-Pixels ≥1.0.0 (terminal image display)
+- Pytest ≥7.0.0 (testing framework)
+- UV (package manager and build tool)
 
 ## Code Structure
 
-- `main.py`: Main application entry point with argument parsing
-- `pyproject.toml`: Project configuration and dependencies (version 0.2.0)
+- `renamer/main.py`: Main application entry point with argument parsing
+- `pyproject.toml`: Project configuration and dependencies (version 0.5.10)
 - `README.md`: User documentation
+- `DEVELOP.md`: Developer guide with debugging info
+- `INSTALL.md`: Installation instructions
+- `CLAUDE.md`: Comprehensive AI assistant reference guide
 - `ToDo.md`: Development task tracking
-- `AI_AGENT.md`: This file
+- `AI_AGENT.md`: This file (AI agent instructions)
 - `renamer/`: Main package
   - `app.py`: Main Textual application class with tree management and file operations
-  - `extractor.py`: MediaExtractor class coordinating multiple extractors
+  - `settings.py`: Settings management with JSON storage
+  - `cache.py`: File-based caching system with TTL support
+  - `secrets.py`: API keys and secrets (TMDB)
+  - `constants.py`: Application constants (media types, sources, resolutions, special editions)
+  - `screens.py`: Additional UI screens (OpenScreen, HelpScreen, RenameConfirmScreen, SettingsScreen)
+  - `bump.py`: Version bump utility
+  - `release.py`: Release automation script
   - `extractors/`: Individual extractor classes
+    - `extractor.py`: MediaExtractor class coordinating all extractors
     - `mediainfo_extractor.py`: PyMediaInfo-based extraction
-    - `filename_extractor.py`: Filename parsing
-    - `metadata_extractor.py`: Mutagen-based metadata
+    - `filename_extractor.py`: Filename parsing with regex patterns
+    - `metadata_extractor.py`: Mutagen-based embedded metadata
     - `fileinfo_extractor.py`: Basic file information
+    - `tmdb_extractor.py`: The Movie Database API integration
+    - `default_extractor.py`: Fallback extractor
   - `formatters/`: Data formatting classes
+    - `formatter.py`: Base formatter interface
     - `media_formatter.py`: Main formatter coordinating display
+    - `catalog_formatter.py`: Catalog mode formatting with TMDB data
     - `proposed_name_formatter.py`: Generates rename suggestions
     - `track_formatter.py`: Track information formatting
     - `size_formatter.py`: File size formatting
@@ -52,9 +75,17 @@ Key features:
     - `extension_formatter.py`: File extension formatting
     - `helper_formatter.py`: Helper formatting utilities
     - `special_info_formatter.py`: Special edition information
-  - `constants.py`: Application constants (supported media types)
-  - `screens.py`: Additional UI screens (OpenScreen, HelpScreen, RenameConfirmScreen)
+  - `decorators/`: Utility decorators
+    - `caching.py`: Caching decorator for automatic method caching
   - `test/`: Unit tests for extractors
+    - `test_filename_extractor.py`: Filename parsing tests
+    - `test_mediainfo_extractor.py`: MediaInfo extraction tests
+    - `test_mediainfo_frame_class.py`: Frame class detection tests
+    - `test_fileinfo_extractor.py`: File info tests
+    - `test_metadata_extractor.py`: Metadata extraction tests
+    - `test_filename_detection.py`: Filename pattern detection tests
+    - `filenames.txt`, `test_filenames.txt`: Sample test data
+    - `test_cases.json`, `test_mediainfo_frame_class.json`: Test fixtures
 
 ## Instructions for AI Agents
 
@@ -113,14 +144,26 @@ The app uses multiple screens for different operations:
 - `HelpScreen`: Comprehensive help with key bindings
 - `RenameConfirmScreen`: File rename confirmation with error handling
 
+### Completed Major Features
+
+- ✅ Settings management with JSON configuration
+- ✅ Mode toggle (technical/catalog)
+- ✅ Caching system with TTL support
+- ✅ TMDB integration for catalog data
+- ✅ Poster display in terminal
+- ✅ Settings UI screen
+
 ### Future Enhancements
 
 - Metadata editing capabilities
 - Batch rename operations
-- Configuration file support
 - Plugin system for custom extractors/formatters
 - Advanced search and filtering
 - Undo/redo functionality
+- Blue highlighting for changed parts in proposed filename
+- Exclude dev commands from distributed package
+- Full genre name expansion (currently shows codes)
+- Optimized poster quality and display
 
 ### Testing
 
@@ -141,4 +184,16 @@ The app uses multiple screens for different operations:
 - Update ToDo.md when completing tasks
 - Update version numbers appropriately
 
-This document should be updated as the project evolves.
\ No newline at end of file
+## Important Files for AI Assistants
+
+For comprehensive project information, AI assistants should refer to:
+1. **CLAUDE.md**: Complete AI assistant reference guide (most comprehensive)
+2. **AI_AGENT.md**: This file (concise instructions)
+3. **DEVELOP.md**: Developer setup and debugging
+4. **ToDo.md**: Current task list and completed items
+5. **README.md**: User-facing documentation
+
+This document should be updated as the project evolves.
+
+---
+**Last Updated**: 2025-12-31
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..3bd97b5
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,441 @@
+# CLAUDE.md - AI Assistant Reference Guide
+
+This document provides comprehensive project information for AI assistants (like Claude) working on the Renamer project.
+
+## Project Overview
+
+**Renamer** is a sophisticated Terminal User Interface (TUI) application for managing, viewing metadata, and renaming media files. Built with Python and the Textual framework, it provides an interactive, curses-like interface for media collection management.
+
+### Current Version
+- **Version**: 0.5.10
+- **Python**: 3.11+
+- **Status**: Active development with media catalog mode features
+
+## Project Purpose
+
+Renamer serves two primary use cases:
+1. **Technical Mode**: Detailed technical metadata viewing (video tracks, audio streams, codecs, bitrates)
+2. **Catalog Mode**: Media library catalog view with TMDB integration (posters, ratings, descriptions, genres)
+
+## Architecture Overview
+
+### Core Components
+
+#### Main Application (`renamer/app.py`)
+- Main `RenamerApp` class inheriting from Textual's `App`
+- Manages TUI layout with split view: file tree (left) and details panel (right)
+- Handles keyboard/mouse navigation and user commands
+- Coordinates file operations and metadata extraction
+- Implements efficient tree updates for file renaming
+
+#### Entry Point (`renamer/main.py`)
+- Argument parsing for directory selection
+- Application initialization and launch
+
+#### Constants (`renamer/constants.py`)
+Defines comprehensive dictionaries:
+- `MEDIA_TYPES`: Supported video formats (mkv, avi, mov, mp4, etc.)
+- `SOURCE_DICT`: Video source types (WEB-DL, BDRip, BluRay, etc.)
+- `FRAME_CLASSES`: Resolution classifications (480p-8K)
+- `MOVIE_DB_DICT`: Database identifiers (TMDB, IMDB, Trakt, TVDB)
+- `SPECIAL_EDITIONS`: Edition types (Director's Cut, Extended, etc.)
+
+### Extractor System (`renamer/extractors/`)
+
+Modular architecture for gathering metadata from multiple sources:
+
+#### Core Extractors
+1. **MediaInfoExtractor** (`mediainfo_extractor.py`)
+   - Uses PyMediaInfo library
+   - Extracts detailed track information (video, audio, subtitle)
+   - Provides codec, bitrate, frame rate, resolution data
+
+2. **FilenameExtractor** (`filename_extractor.py`)
+   - Parses metadata from filename patterns
+   - Detects year, resolution, source, codecs, edition info
+   - Uses regex patterns to extract structured data
+
+3. **MetadataExtractor** (`metadata_extractor.py`)
+   - Reads embedded metadata using Mutagen
+   - Extracts tags, container format info
+
+4. **FileInfoExtractor** (`fileinfo_extractor.py`)
+   - Basic file information (size, dates, permissions)
+   - MIME type detection via python-magic
+
+5. **TMDBExtractor** (`tmdb_extractor.py`)
+   - The Movie Database API integration
+   - Fetches title, year, ratings, overview, genres, poster
+   - Supports movie and TV show data
+
+6. **DefaultExtractor** (`default_extractor.py`)
+   - Fallback extractor providing minimal data
+
+#### Extractor Coordinator (`extractor.py`)
+- `MediaExtractor` class orchestrates all extractors
+- Provides unified `get()` interface for data retrieval
+- Caching support via decorators
+
+### Formatter System (`renamer/formatters/`)
+
+Transforms raw extracted data into formatted display strings:
+
+#### Specialized Formatters
+1. **MediaFormatter** (`media_formatter.py`)
+   - Main formatter coordinating all format operations
+   - Mode-aware (technical vs catalog)
+   - Applies color coding and styling
+
+2. **CatalogFormatter** (`catalog_formatter.py`)
+   - Formats catalog mode display
+   - Renders TMDB data, ratings, genres, overview
+   - Terminal image display for posters (rich-pixels)
+
+3. **TrackFormatter** (`track_formatter.py`)
+   - Video/audio/subtitle track formatting
+   - Color-coded track information
+
+4. **ProposedNameFormatter** (`proposed_name_formatter.py`)
+   - Generates intelligent rename suggestions
+   - Pattern: `Title (Year) [Resolution Source Edition].ext`
+   - Sanitizes filenames (removes invalid characters)
+
+5. **Utility Formatters**
+   - `SizeFormatter`: Human-readable file sizes
+   - `DateFormatter`: Timestamp formatting
+   - `DurationFormatter`: Duration in HH:MM:SS
+   - `ResolutionFormatter`: Resolution display
+   - `TextFormatter`: Text styling utilities
+   - `ExtensionFormatter`: File extension handling
+   - `SpecialInfoFormatter`: Edition/source formatting
+   - `HelperFormatter`: General formatting helpers
+
+### Settings & Caching
+
+#### Settings System (`renamer/settings.py`)
+- JSON configuration stored in `~/.config/renamer/config.json`
+- Configurable options:
+  - `mode`: "technical" or "catalog"
+  - `cache_ttl_extractors`: 21600s (6 hours)
+  - `cache_ttl_tmdb`: 21600s (6 hours)
+  - `cache_ttl_posters`: 2592000s (30 days)
+- Automatic save/load with defaults
+
+#### Cache System (`renamer/cache.py`)
+- File-based cache with TTL support
+- Location: `~/.cache/renamer/`
+- Subdirectory organization (tmdb/, posters/, extractors/, general/)
+- Supports JSON and pickle serialization
+- In-memory cache for performance
+- Image caching for TMDB posters
+- Automatic expiration and cleanup
+
+#### Caching Decorators (`renamer/decorators/caching.py`)
+- `@cached` decorator for automatic method caching
+- Integrates with Settings for TTL configuration
+
+### UI Screens (`renamer/screens.py`)
+
+Additional UI screens for user interaction:
+
+1. **OpenScreen**: Directory selection dialog with validation
+2. **HelpScreen**: Comprehensive help with key bindings
+3. **RenameConfirmScreen**: File rename confirmation with error handling
+4. **SettingsScreen**: Settings configuration interface
+
+### Development Tools
+
+#### Version Management (`renamer/bump.py`)
+- `bump-version` command
+- Auto-increments patch version in `pyproject.toml`
+
+#### Release Automation (`renamer/release.py`)
+- `release` command
+- Runs: version bump → dependency sync → package build
+
+## Key Features
+
+### Current Features (v0.5.10)
+- Recursive directory scanning for video files
+- Tree view with expand/collapse navigation
+- Dual-mode display (technical/catalog)
+- Detailed metadata extraction from multiple sources
+- Intelligent file renaming with preview
+- TMDB integration with poster display
+- Settings configuration UI
+- Persistent caching with TTL
+- Loading indicators and error handling
+- Confirmation dialogs for file operations
+- Color-coded information display
+- Keyboard and mouse navigation
+
+### Keyboard Commands
+- `q`: Quit application
+- `o`: Open directory
+- `s`: Scan/rescan directory
+- `f`: Refresh metadata for selected file
+- `r`: Rename file with proposed name
+- `p`: Toggle tree expansion
+- `h`: Show help screen
+- `^p`: Open command palette
+- Settings menu via action bar
+
+## Technology Stack
+
+### Core Dependencies
+- **textual** (≥6.11.0): TUI framework
+- **pymediainfo** (≥6.0.0): Media track analysis
+- **mutagen** (≥1.47.0): Embedded metadata
+- **python-magic** (≥0.4.27): MIME detection
+- **langcodes** (≥3.5.1): Language code handling
+- **requests** (≥2.31.0): HTTP for TMDB API
+- **rich-pixels** (≥1.0.0): Terminal image display
+- **pytest** (≥7.0.0): Testing framework
+
+### System Requirements
+- Python 3.11 or higher
+- UV package manager (recommended)
+- MediaInfo library (system dependency for pymediainfo)
+
+## Development Workflow
+
+### Setup
+```bash
+# Install UV
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Clone and sync
+cd /path/to/renamer
+uv sync
+
+# Run from source
+uv run python renamer/main.py [directory]
+```
+
+### Development Commands
+```bash
+uv run renamer              # Run installed version
+uv run pytest               # Run tests
+uv run bump-version         # Increment version
+uv run release              # Build release (bump + sync + build)
+uv build                    # Build wheel/tarball
+uv tool install .           # Install as global tool
+```
+
+### Debugging
+```bash
+# Enable formatter logging
+FORMATTER_LOG=1 uv run renamer /path/to/directory
+# Creates formatter.log with detailed call traces
+```
+
+### Testing
+- Test files in `renamer/test/`
+- Sample filenames in `test/filenames.txt` and `test/test_filenames.txt`
+- Test cases in `test/test_cases.json`
+- Run with: `uv run pytest`
+
+## Code Style & Standards
+
+### Python Standards
+- Type hints encouraged
+- PEP 8 style guidelines
+- Descriptive variable/function names
+- Docstrings for classes and functions
+- Pathlib for file operations
+- Proper exception handling
+
+### Architecture Patterns
+- Extractor pattern: Each extractor focuses on one data source
+- Formatter pattern: Formatters handle display logic, extractors handle data
+- Separation of concerns: Data extraction → formatting → display
+- Dependency injection: Extractors and formatters are modular
+- Configuration management: Settings class for all config
+
+### Best Practices
+- Avoid over-engineering (keep solutions simple)
+- Only add features when explicitly requested
+- Validate at system boundaries only (user input, external APIs)
+- Don't add unnecessary error handling for internal code
+- Trust framework guarantees
+- Delete unused code completely (no backwards-compat hacks)
+
+## File Operations
+
+### Directory Scanning
+- Recursive search for supported video formats
+- File tree representation with hierarchical structure
+- Efficient tree updates on file operations
+
+### File Renaming
+1. Select file in tree
+2. Press `r` to initiate rename
+3. Review proposed name (shows current vs proposed)
+4. Confirm with `y` or cancel with `n`
+5. Tree updates in-place without full reload
+
+### Metadata Caching
+- First extraction cached for 6 hours
+- TMDB data cached for 6 hours
+- Posters cached for 30 days
+- Force refresh with `f` command
+- Cache invalidated on file rename
+
+## API Integration
+
+### TMDB API
+- API key stored in `renamer/secrets.py`
+- Search endpoint for movie lookup by title/year
+- Image base URL for poster downloads
+- Handles rate limiting and errors gracefully
+- Falls back to filename data if API unavailable
+
+## Project Files
+
+### Documentation
+- `README.md`: User-facing documentation
+- `AI_AGENT.md`: AI agent instructions (legacy)
+- `DEVELOP.md`: Developer guide
+- `INSTALL.md`: Installation instructions
+- `ToDo.md`: Task tracking
+- `CLAUDE.md`: This file (AI assistant reference)
+
+### Configuration
+- `pyproject.toml`: Project metadata, dependencies, build config
+- `uv.lock`: Locked dependencies
+
+### Build Artifacts
+- `dist/`: Built wheels and tarballs
+- `build/`: Build intermediates
+- `renamer.egg-info/`: Package metadata
+
+## Known Issues & Limitations
+
+### Current Limitations
+- TMDB API requires internet connection
+- Poster display requires terminal with image support
+- Some special characters in filenames need sanitization
+- Large directories may have initial scan delay
+
+### Future Enhancements (See ToDo.md)
+- Metadata editing capabilities
+- Batch rename operations
+- Advanced search and filtering
+- Undo/redo functionality
+- Plugin system for custom extractors/formatters
+- Full genre name expansion (currently shows codes)
+- Improved poster quality/display optimization
+
+## Contributing Guidelines
+
+### Making Changes
+1. Read existing code and understand architecture
+2. Check `ToDo.md` for pending tasks
+3. Implement features incrementally
+4. Test with real media files
+5. Ensure backward compatibility
+6. Update documentation
+7. Update tests as needed
+8. Run `uv run release` before committing
+
+### Commit Standards
+- Clear, descriptive commit messages
+- Focus on "why" not "what"
+- One logical change per commit
+- Reference related issues/tasks
+
+### Code Review Checklist
+- [ ] Follows PEP 8 style
+- [ ] Type hints added where appropriate
+- [ ] No unnecessary complexity
+- [ ] Tests pass (`uv run pytest`)
+- [ ] Documentation updated
+- [ ] No security vulnerabilities (XSS, injection, etc.)
+- [ ] Efficient resource usage (no memory leaks)
+
+## Security Considerations
+
+- Input sanitization for filenames (see `ProposedNameFormatter`)
+- No shell command injection risks
+- Safe file operations (pathlib, proper error handling)
+- TMDB API key should not be committed (stored in `secrets.py`)
+- Cache directory permissions should be user-only
+
+## Performance Notes
+
+- In-memory cache reduces repeated extraction overhead
+- File cache persists across sessions
+- Tree updates optimized for rename operations
+- TMDB requests throttled to respect API limits
+- Large directory scans use async/await patterns
+
+## Special Notes for AI Assistants
+
+### When Adding Features
+1. **Always read relevant files first** - Never modify code you haven't read
+2. **Check ToDo.md** - See if feature is already planned
+3. **Understand existing patterns** - Follow established architecture
+4. **Test with real files** - Use actual media files for testing
+5. **Update documentation** - Keep docs in sync with code
+
+### When Debugging
+1. **Enable formatter logging** - Use `FORMATTER_LOG=1` for detailed traces
+2. **Check cache state** - Clear cache if stale data suspected
+3. **Verify file permissions** - Ensure read/write access
+4. **Test with sample filenames** - Use test fixtures first
+
+### When Refactoring
+1. **Maintain backward compatibility** - Unless explicitly breaking change
+2. **Update tests** - Reflect refactored code
+3. **Check all formatters** - Formatting is centralized
+4. **Verify extractor chain** - Ensure data flow intact
+
+### Common Pitfalls to Avoid
+- Don't create new files unless absolutely necessary (edit existing)
+- Don't add features beyond what's requested
+- Don't over-engineer solutions
+- Don't skip testing with real files
+- Don't forget to update version number for releases
+- Don't commit secrets or API keys
+- Don't use deprecated Textual APIs
+
+## Project History
+
+### Evolution
+- Started as simple file renamer
+- Added metadata extraction (MediaInfo, Mutagen)
+- Expanded to TUI with Textual framework
+- Added filename parsing intelligence
+- Integrated TMDB for catalog mode
+- Added settings and caching system
+- Implemented poster display with rich-pixels
+- Added dual-mode interface (technical/catalog)
+
+### Version Milestones
+- 0.2.x: Initial TUI with basic metadata
+- 0.3.x: Enhanced extractors and formatters
+- 0.4.x: Added TMDB integration
+- 0.5.x: Settings, caching, catalog mode, poster display
+
+## Resources
+
+### External Documentation
+- [Textual Documentation](https://textual.textualize.io/)
+- [PyMediaInfo Documentation](https://pymediainfo.readthedocs.io/)
+- [Mutagen Documentation](https://mutagen.readthedocs.io/)
+- [TMDB API Documentation](https://developers.themoviedb.org/3)
+- [UV Documentation](https://docs.astral.sh/uv/)
+
+### Internal Documentation
+- Main README: User guide and quick start
+- DEVELOP.md: Developer setup and debugging
+- INSTALL.md: Installation methods
+- AI_AGENT.md: Legacy AI instructions (historical)
+- ToDo.md: Current task list
+
+---
+
+**Last Updated**: 2025-12-31
+**For AI Assistant**: Claude (Anthropic)
+**Project Maintainer**: sha
+**Repository**: `/home/sha/bin/renamer`
diff --git a/DEVELOP.md b/DEVELOP.md
index eab4572..0e8ae54 100644
--- a/DEVELOP.md
+++ b/DEVELOP.md
@@ -2,6 +2,8 @@
 
 This guide contains information for developers working on the Renamer project.
 
+**Current Version**: 0.5.10
+
 ## Development Setup
 
 ### Prerequisites
@@ -67,43 +69,85 @@ Enable detailed logging for formatter operations:
 FORMATTER_LOG=1 uv run renamer /path/to/directory
 ```
 
-This creates `formatter.log` with:
+This creates `formatter.log` in the current directory with:
 - Formatter call sequences and ordering
 - Input/output values for each formatter
 - Caller information (file and line number)
 - Any errors during formatting
+- Timestamp for each operation
+
+### Cache Inspection
+Cache is stored in `~/.cache/renamer/` with subdirectories:
+- `extractors/`: Extractor results cache
+- `tmdb/`: TMDB API response cache
+- `posters/`: Downloaded poster images
+- `general/`: General purpose cache
+
+To clear cache:
+```bash
+rm -rf ~/.cache/renamer/
+```
+
+### Settings Location
+Settings are stored in `~/.config/renamer/config.json`:
+```json
+{
+  "mode": "technical",
+  "cache_ttl_extractors": 21600,
+  "cache_ttl_tmdb": 21600,
+  "cache_ttl_posters": 2592000
+}
+```
 
 ## Architecture
 
-The application uses a modular architecture:
+The application uses a modular architecture with clear separation of concerns:
+
+### Core Application (`renamer/`)
+- **app.py**: Main RenamerApp class (Textual App), tree management, file operations
+- **main.py**: Entry point with argument parsing
+- **constants.py**: Comprehensive constants (media types, sources, resolutions, editions)
+- **settings.py**: Settings management with JSON persistence (`~/.config/renamer/`)
+- **cache.py**: File-based caching system with TTL support (`~/.cache/renamer/`)
+- **secrets.py**: API keys and secrets (TMDB)
 
 ### Extractors (`renamer/extractors/`)
-- **MediaInfoExtractor**: Extracts detailed track information using PyMediaInfo
-- **FilenameExtractor**: Parses metadata from filenames
-- **MetadataExtractor**: Extracts embedded metadata using Mutagen
-- **FileInfoExtractor**: Provides basic file information
-- **DefaultExtractor**: Fallback extractor
-- **MediaExtractor**: Main extractor coordinating all others
+Data extraction from multiple sources:
+- **extractor.py**: MediaExtractor coordinator class
+- **mediainfo_extractor.py**: PyMediaInfo for detailed track information
+- **filename_extractor.py**: Regex-based filename parsing
+- **metadata_extractor.py**: Mutagen for embedded metadata
+- **fileinfo_extractor.py**: Basic file information (size, dates, MIME)
+- **tmdb_extractor.py**: The Movie Database API integration
+- **default_extractor.py**: Fallback extractor
 
 ### Formatters (`renamer/formatters/`)
-- **MediaFormatter**: Formats extracted data for display
-- **ProposedNameFormatter**: Generates intelligent rename suggestions
-- **TrackFormatter**: Formats video/audio/subtitle track information
-- **SizeFormatter**: Formats file sizes
-- **DateFormatter**: Formats timestamps
-- **DurationFormatter**: Formats time durations
-- **ResolutionFormatter**: Formats video resolutions
-- **TextFormatter**: Text styling utilities
+Display formatting and rendering:
+- **formatter.py**: Base formatter interface
+- **media_formatter.py**: Main formatter coordinating all format operations
+- **catalog_formatter.py**: Catalog mode display (TMDB data, posters)
+- **proposed_name_formatter.py**: Intelligent rename suggestions
+- **track_formatter.py**: Video/audio/subtitle track formatting
+- **size_formatter.py**: Human-readable file sizes
+- **date_formatter.py**: Timestamp formatting
+- **duration_formatter.py**: Duration in HH:MM:SS format
+- **resolution_formatter.py**: Resolution display
+- **extension_formatter.py**: File extension handling
+- **special_info_formatter.py**: Edition/source formatting
+- **text_formatter.py**: Text styling utilities
+- **helper_formatter.py**: General formatting helpers
 
 ### Screens (`renamer/screens.py`)
-- **OpenScreen**: Directory selection dialog
-- **HelpScreen**: Application help and key bindings
-- **RenameConfirmScreen**: File rename confirmation dialog
+UI screens for user interaction:
+- **OpenScreen**: Directory selection with validation
+- **HelpScreen**: Comprehensive help with key bindings
+- **RenameConfirmScreen**: File rename confirmation with preview
+- **SettingsScreen**: Settings configuration UI
 
-### Main Components
-- **app.py**: Main TUI application
-- **main.py**: Entry point
-- **constants.py**: Application constants
+### Utilities
+- **decorators/caching.py**: Caching decorator for automatic method caching
+- **bump.py**: Version bump utility script
+- **release.py**: Release automation (bump + sync + build)
 
 ## Testing
 
@@ -133,9 +177,18 @@ uv tool uninstall renamer
 
 ## Code Style
 
-The project uses standard Python formatting. Consider using tools like:
+The project follows Python best practices:
+- **PEP 8**: Standard Python style guide
+- **Type Hints**: Encouraged where appropriate
+- **Docstrings**: For all classes and public methods
+- **Descriptive Naming**: Clear variable and function names
+- **Pathlib**: For all file operations
+- **Error Handling**: Appropriate exception handling at boundaries
+
+Consider using tools like:
 - `ruff` for linting and formatting
-- `mypy` for type checking (if added)
+- `mypy` for type checking
+- `black` for consistent formatting
 
 ## Contributing
 
@@ -146,4 +199,22 @@ The project uses standard Python formatting. Consider using tools like:
 5. Run the release process: `uv run release`
 6. Submit a pull request
 
-For more information, see the main [README.md](../README.md).
\ No newline at end of file
+## Additional Documentation
+
+For comprehensive project information:
+- **[README.md](README.md)**: User guide and features
+- **[CLAUDE.md](CLAUDE.md)**: Complete AI assistant reference
+- **[AI_AGENT.md](AI_AGENT.md)**: AI agent instructions
+- **[INSTALL.md](INSTALL.md)**: Installation methods
+- **[ToDo.md](ToDo.md)**: Task list and priorities
+
+## Project Resources
+
+- **Cache Directory**: `~/.cache/renamer/`
+- **Config Directory**: `~/.config/renamer/`
+- **Test Files**: `renamer/test/`
+- **Build Output**: `dist/` and `build/`
+
+---
+
+**Last Updated**: 2025-12-31
\ No newline at end of file
diff --git a/README.md b/README.md
index f4993ca..5f85607 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,23 @@
-# Renamer - Media File Renamer and Metadata Editor
+# Renamer - Media File Renamer and Metadata Viewer
 
-A terminal-based (TUI) application for scanning directories, viewing media file details, and renaming files based on extracted metadata. Built with Python and Textual.
+A powerful terminal-based (TUI) application for managing media collections. Scan directories, view detailed metadata, browse TMDB catalog information with posters, and intelligently rename files. Built with Python and Textual.
+
+**Version**: 0.5.10
 
 ## Features
 
-- Recursive directory scanning for video files
-- Tree view navigation with keyboard and mouse support
-- Detailed metadata extraction from multiple sources (MediaInfo, filename parsing, embedded metadata)
-- Intelligent file renaming with proposed names based on metadata
-- Color-coded information display
-- Command-based interface with hotkeys
-- Extensible extractor and formatter system
-- Support for video, audio, and subtitle track information
-- Confirmation dialogs for file operations
+### Core Capabilities
+- **Dual Display Modes**: Switch between Technical (codec/track details) and Catalog (TMDB metadata with posters)
+- **Recursive Directory Scanning**: Finds all video files in nested directories
+- **Tree View Navigation**: Keyboard and mouse support with expand/collapse
+- **Multi-Source Metadata**: Combines MediaInfo, filename parsing, embedded tags, and TMDB API
+- **Intelligent Renaming**: Proposes standardized names based on extracted metadata
+- **Persistent Settings**: Configurable mode and cache TTLs saved to `~/.config/renamer/`
+- **Advanced Caching**: File-based cache with TTL (6h extractors, 6h TMDB, 30d posters)
+- **Terminal Poster Display**: View movie posters in your terminal using rich-pixels
+- **Color-Coded Display**: Visual highlighting for different data types
+- **Confirmation Dialogs**: Safe file operations with preview and confirmation
+- **Extensible Architecture**: Modular extractor and formatter system for easy extension
 
 ## Installation
 
@@ -48,14 +53,16 @@ renamer
 renamer /path/to/media/directory
 ```
 
-### Commands
+### Keyboard Commands
 - **q**: Quit the application
 - **o**: Open directory selection dialog
-- **s**: Rescan current directory
-- **f**: Refresh metadata for selected file
+- **s**: Scan/rescan current directory
+- **f**: Force refresh metadata for selected file (bypass cache)
 - **r**: Rename selected file with proposed name
 - **p**: Toggle tree expansion (expand/collapse all)
 - **h**: Show help screen
+- **^p**: Open command palette (settings, mode toggle)
+- **Settings**: Access via action bar (top-right corner)
 
 ### Navigation
 - Use arrow keys to navigate the file tree
@@ -67,9 +74,14 @@ renamer /path/to/media/directory
 ### File Renaming
 1. Select a media file in the tree
 2. Press **r** to initiate rename
-3. Review the proposed new name
+3. Review the proposed new name in the confirmation dialog
 4. Press **y** to confirm or **n** to cancel
-5. The file will be renamed and the tree updated automatically
+5. The file will be renamed and the tree updated automatically (cache invalidated)
+
+### Display Modes
+- **Technical Mode**: Shows codec details, bitrates, track information, resolutions
+- **Catalog Mode**: Shows TMDB data including title, year, rating, overview, genres, and poster
+- Toggle between modes via Settings menu or command palette (^p)
 
 ## Development
 
@@ -88,8 +100,19 @@ For development setup, architecture details, debugging information, and contribu
 - .ogv
 
 ## Dependencies
-- textual: TUI framework
-- pymediainfo: Detailed media track information
-- mutagen: Embedded metadata extraction
-- python-magic: MIME type detection
-- langcodes: Language code handling
+- **textual** ≥6.11.0: TUI framework
+- **pymediainfo** ≥6.0.0: Detailed media track information
+- **mutagen** ≥1.47.0: Embedded metadata extraction
+- **python-magic** ≥0.4.27: MIME type detection
+- **langcodes** ≥3.5.1: Language code handling
+- **requests** ≥2.31.0: HTTP client for TMDB API
+- **rich-pixels** ≥1.0.0: Terminal image display
+- **pytest** ≥7.0.0: Testing framework
+
+### System Requirements
+- **Python**: 3.11 or higher
+- **MediaInfo Library**: System dependency for pymediainfo
+  - Ubuntu/Debian: `sudo apt install libmediainfo-dev`
+  - Fedora/CentOS: `sudo dnf install libmediainfo-devel`
+  - Arch Linux: `sudo pacman -S libmediainfo`
+  - macOS/Windows: Automatically handled by pymediainfo
diff --git a/ToDo.md b/ToDo.md
index c85aa03..652df17 100644
--- a/ToDo.md
+++ b/ToDo.md
@@ -1,6 +1,8 @@
-Project: Media File Renamer and Metadata Editor (Python TUI with Textual)
+Project: Media File Renamer and Metadata Viewer (Python TUI with Textual)
 
-TODO Steps:
+**Current Version**: 0.5.10
+
+## TODO Steps:
 1. ✅ Set up Python project structure with UV package manager
 2. ✅ Install dependencies: textual, mutagen, pymediainfo, python-magic, pathlib for file handling
 3. ✅ Implement recursive directory scanning for video files (*.mkv, *.avi, *.mov, *.mp4, *.wmv, *.flv, *.webm, etc.)
@@ -24,10 +26,11 @@ TODO Steps:
 21. ✅ Add error handling for file operations and metadata extraction
 22. 🔄 Implement blue highlighting for changed parts in proposed filename display (show differences between current and proposed names)
 23. 🔄 Implement build script to exclude dev commands (bump-version, release) from distributed package
-24. Implement metadata editing capabilities (future enhancement)
-25. Add batch rename operations (future enhancement)
-26. Add configuration file support (future enhancement)
-27. Add plugin system for custom extractors/formatters (future enhancement)
+24. 📋 Implement metadata editing capabilities (future enhancement)
+25. 📋 Add batch rename operations (future enhancement)
+26. 📋 Add plugin system for custom extractors/formatters (future enhancement)
+27. 📋 Add advanced search and filtering capabilities (future enhancement)
+28. 📋 Implement undo/redo functionality for file operations (future enhancement)
 
 ---
 
@@ -60,9 +63,74 @@ TODO Steps:
 
 ### Phase 5: Poster Handling and Display
 15. ✅ Add poster caching (images in cache dir with 1-month TTL)
-16. ✅ Implement terminal image display (research rich-pixels or alternatives, add poster_display.py)
+16. ✅ Implement terminal image display (using rich-pixels library)
+
+### Phase 6: Polish and Documentation
+17. ✅ Create comprehensive CLAUDE.md for AI assistants
+18. ✅ Update all markdown documentation files
+19. ✅ Ensure version consistency across all files
 
 ### Additional TODOs from Plan
-- Retrieve full movie details from TMDB (future)
-- Expand genres to full names instead of codes (future)
-- Optimize poster quality and display (future)
\ No newline at end of file
+- 📋 Retrieve full movie details from TMDB (currently basic data only)
+- 📋 Expand genres to full names instead of codes (currently shows genre IDs)
+- 📋 Optimize poster quality and display (improve image rendering)
+- 📋 Add TV show support (currently movie-focused)
+- 📋 Implement blue highlighting for filename differences
+- 📋 Build script to exclude dev commands from distribution
+
+---
+
+## Recently Completed (v0.5.x)
+
+### Version 0.5.10
+- Complete media catalog mode implementation
+- TMDB integration with poster display
+- Settings system with persistent JSON storage
+- Advanced caching with TTL support
+- Dual-mode display (technical/catalog)
+- Settings UI screen
+
+### Version 0.4.x
+- Enhanced extractor system
+- TMDB extractor foundation
+- Improved formatter architecture
+
+### Version 0.3.x
+- Expanded metadata extraction
+- Multiple formatter types
+- Special edition detection
+
+### Version 0.2.x
+- Initial TUI implementation
+- Basic metadata extraction
+- File tree navigation
+- Rename functionality
+
+---
+
+## Development Priorities
+
+### High Priority
+1. 🔄 Blue highlighting for filename differences (UX improvement)
+2. 🔄 Build script for clean distribution packages
+3. 📋 Genre ID to name expansion (TMDB lookup)
+
+### Medium Priority
+1. 📋 Batch rename operations
+2. 📋 Advanced search/filtering
+3. 📋 TV show support
+
+### Low Priority (Future)
+1. 📋 Metadata editing
+2. 📋 Plugin system
+3. 📋 Undo/redo functionality
+4. 📋 Configuration profiles
+
+---
+
+**Legend:**
+- ✅ Completed
+- 🔄 In Progress / Partially Complete
+- 📋 Planned / Future Enhancement
+
+**Last Updated**: 2025-12-31
\ No newline at end of file
diff --git a/pyproject.toml b/pyproject.toml
index 54745ba..d1f6242 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "renamer"
-version = "0.5.10"
+version = "0.6.0"
 description = "Terminal-based media file renamer and metadata viewer"
 readme = "README.md"
 requires-python = ">=3.11"
diff --git a/renamer/settings.py b/renamer/settings.py
index fb2840e..f0b9e7c 100644
--- a/renamer/settings.py
+++ b/renamer/settings.py
@@ -14,7 +14,7 @@ class Settings:
         "cache_ttl_posters": 2592000,  # 30 days in seconds
     }
 
-    def __init__(self, config_dir: Path = None):
+    def __init__(self, config_dir: Path | None = None):
         if config_dir is None:
             config_dir = Path.home() / ".config" / "renamer"
         self.config_dir = config_dir
@@ -26,7 +26,7 @@ class Settings:
         """Load settings from file, using defaults if file doesn't exist."""
         if self.config_file.exists():
             try:
-                with open(self.config_file, 'r') as f:
+                with open(self.config_file, "r") as f:
                     data = json.load(f)
                     # Validate and merge with defaults
                     for key, default_value in self.DEFAULTS.items():
@@ -46,7 +46,7 @@ class Settings:
         """Save current settings to file."""
         try:
             self.config_dir.mkdir(parents=True, exist_ok=True)
-            with open(self.config_file, 'w') as f:
+            with open(self.config_file, "w") as f:
                 json.dump(self._settings, f, indent=2)
         except IOError as e:
             print(f"Error: Could not save settings: {e}")
@@ -69,4 +69,4 @@ class Settings:
 
     def get_all(self) -> Dict[str, Any]:
         """Get all current settings."""
-        return self._settings.copy()
\ No newline at end of file
+        return self._settings.copy()