From 9e331e58ce37ea93493c5d4ab009e33e63c1583d Mon Sep 17 00:00:00 2001
From: sHa <sha@shadoll.dev>
Date: Thu, 25 Dec 2025 01:43:07 +0000
Subject: [PATCH] Add AI agent instructions and update project TODO list with
 detailed steps

---
 AI_AGENT.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 todo.txt    | 26 +++++++++--------
 2 files changed, 95 insertions(+), 11 deletions(-)
 create mode 100644 AI_AGENT.md

diff --git a/AI_AGENT.md b/AI_AGENT.md
new file mode 100644
index 0000000..84e30b1
--- /dev/null
+++ b/AI_AGENT.md
@@ -0,0 +1,80 @@
+# AI Agent Instructions for Media File Renamer Project
+
+## Project Description
+
+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, and view detailed metadata information including video, audio, and subtitle tracks.
+
+Key features:
+- Recursive directory scanning
+- Tree-based file navigation
+- Detailed metadata extraction and display
+- Color-coded information
+- Keyboard and mouse navigation
+- Extensible for future renaming and editing features
+
+## Technology Stack
+
+- Python 3.11+
+- Textual (TUI framework)
+- Mutagen (audio/video metadata)
+- PyMediaInfo (detailed track information)
+- Python-Magic (MIME type detection)
+- UV (package manager)
+
+## Code Structure
+
+- `main.py`: Main application code
+- `pyproject.toml`: Project configuration and dependencies
+- `README.md`: User documentation
+- `todo.txt`: Development task list
+- `AI_AGENT.md`: This file
+
+## Instructions for AI Agents
+
+### Coding Standards
+
+- Use type hints where possible
+- Follow PEP 8 style guidelines
+- Use descriptive variable and function names
+- Add docstrings for functions and classes
+- Handle exceptions appropriately
+- Use pathlib for file operations
+
+### Development Workflow
+
+1. Read the current code and understand the structure
+2. Check the TODO list for pending tasks
+3. Implement features incrementally
+4. Test changes by running the app with `uv run python main.py [directory]`
+5. Update TODO list as tasks are completed
+6. Ensure backward compatibility
+
+### Key Components
+
+- `RenamerApp`: Main application class inheriting from Textual's App
+- `MediaTree`: Custom Tree widget with file-specific styling
+- `get_media_tracks`: Function to extract media track information
+- Various helper functions for formatting and detection
+
+### Future Enhancements
+
+- File renaming functionality
+- Batch operations
+- Advanced metadata editing
+- Plugin system for different media types
+
+### Testing
+
+- Run the app with `uv run python main.py [directory]`
+- Test navigation, selection, and display
+- Verify metadata extraction accuracy
+- Check for any errors or edge cases
+
+### Contribution Guidelines
+
+- Make small, focused changes
+- Update documentation as needed
+- Ensure the app runs without errors
+- Follow the existing code patterns
+
+This document should be updated as the project evolves.
\ No newline at end of file
diff --git a/todo.txt b/todo.txt
index 9100121..1b4d417 100644
--- a/todo.txt
+++ b/todo.txt
@@ -1,14 +1,18 @@
 Project: Media File Renamer and Metadata Editor (Python TUI with Textual)
 
 TODO Steps:
-1. Set up Python project structure with UV package manager
-2. Install dependencies: textual, mutagen (for metadata detection), pathlib for file handling
-3. Implement recursive directory scanning for video files (*.mkv, *.avi, *.mov, *.mp4, *.wmv, *.flv, *.webm, etc.)
-4. Detect real media container type using mutagen or similar library (not by extension)
-5. Create Textual TUI application with split layout (left: file tree, right: file details)
-6. Implement file tree display with navigation (keyboard arrows, mouse support)
-7. Add bottom command bar with initial 'exit' command
-8. Display file details on right side: file size, extension from filename, extension from metadata, file date
-9. Add functionality to select files in the tree and update right panel
-10. Implement metadata editing capabilities (future steps)
-11. Implement file renaming functionality (future steps)
\ No newline at end of file
+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.)
+4. ✅ Detect real media container type using mutagen and python-magic
+5. ✅ Create Textual TUI application with split layout (left: file tree, right: file details)
+6. ✅ Implement file tree display with navigation (keyboard arrows, mouse support)
+7. ✅ Add bottom command bar with 'quit', 'open directory', 'scan' commands
+8. ✅ Display file details on right side: file size, extension from filename, extension from metadata, file date
+9. ✅ Add functionality to select files in the tree and update right panel
+10. ✅ Implement detailed metadata display including video/audio/subtitle tracks with colors
+11. ✅ Add custom tree styling with file icons and colored guides
+12. ✅ Add scrollable details panel
+13. ✅ Handle markup escaping for file names with brackets
+14. Implement metadata editing capabilities (future steps)
+15. Implement file renaming functionality (future steps)
\ No newline at end of file