Main

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,49 @@
+---
+name: Bug Report
+about: Create a report to help us improve
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Bug Description
+
+A clear and concise description of what the bug is.
+
+## Steps to Reproduce
+
+1. Run command: `...`
+2. See error: `...`
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened.
+
+## Environment
+
+- **OS**: [e.g., Windows 10, macOS 13, Ubuntu 22.04]
+- **Python Version**: [e.g., 3.9.7]
+- **Mewtwo Version**: [e.g., 0.0.7]
+- **Ollama Version**: [e.g., 0.13.5] (if using Ollama)
+- **Tesseract Version**: [e.g., 5.4.0]
+
+## Logs/Output
+
+```
+Paste relevant logs or error messages here
+```
+
+## Additional Context
+
+Add any other context about the problem here.
+
+## Checklist
+
+- [ ] I have checked [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)
+- [ ] I have verified my ROM file is valid
+- [ ] I have checked that all prerequisites are installed
+- [ ] I have included relevant logs/output

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,33 @@
+---
+name: Feature Request
+about: Suggest an idea for this project
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Feature Description
+
+A clear and concise description of the feature you'd like to see.
+
+## Motivation
+
+Why is this feature needed? What problem does it solve?
+
+## Proposed Solution
+
+Describe how you envision this feature working.
+
+## Alternatives Considered
+
+Describe any alternative solutions or features you've considered.
+
+## Additional Context
+
+Add any other context, screenshots, or examples about the feature request here.
+
+## Checklist
+
+- [ ] I have checked [TODO.md](TODO.md) to see if this is already planned
+- [ ] I have checked existing issues to avoid duplicates
+- [ ] This feature aligns with the project's goals

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,28 @@
+---
+name: Question
+about: Ask a question about the project
+title: '[QUESTION] '
+labels: question
+assignees: ''
+---
+
+## Question
+
+Your question here.
+
+## Context
+
+Provide any relevant context about your question.
+
+## What I've Tried
+
+Describe what you've already tried or checked:
+- [ ] Checked [README.md](README.md)
+- [ ] Checked [QUICKSTART.md](QUICKSTART.md)
+- [ ] Checked [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)
+- [ ] Searched existing issues
+
+## Additional Information
+
+Any other information that might be helpful.
+

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,35 @@
+## Description
+Brief description of what this PR does.
+
+## Type of Change
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Performance improvement
+- [ ] Code refactoring
+
+## Changes Made
+- 
+- 
+- 
+
+## Testing
+- [ ] I have tested this locally
+- [ ] I have added/updated tests
+- [ ] All existing tests pass
+
+## Checklist
+- [ ] My code follows the project's style guidelines
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have updated the documentation accordingly
+- [ ] My changes generate no new warnings
+- [ ] I have checked that ROM files are not included
+- [ ] I have checked that no sensitive data (API keys, etc.) is included
+
+## Related Issues
+Closes #
+
+## Screenshots (if applicable)
+Add screenshots here if your changes affect the UI or visual output.
+

.github/README.md

@@ -0,0 +1,10 @@
+# GitHub Repository Files
+
+This directory contains GitHub-specific configuration files:
+
+- **ISSUE_TEMPLATE/**: Templates for bug reports and feature requests
+- **PULL_REQUEST_TEMPLATE.md**: Template for pull requests
+- **dependabot.yml**: Automated dependency updates configuration
+
+These files help maintain consistency and quality in issues and pull requests.
+

.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 5
+

.gitignore

@@ -6,6 +6,7 @@ __pycache__/
 .Python
 env/
 venv/
+.venv/
 ENV/
 build/
 develop-eggs/
@@ -22,34 +23,105 @@ wheels/
 *.egg-info/
 .installed.cfg
 *.egg
+MANIFEST
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+*.cover
+*.py,cover
+.cache
+nosetests.xml
+coverage.xml
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+
+# Linting
+.ruff_cache/
+.flake8
 
 # Environment variables
 .env
 .env.local
+.env.*.local
 
 # ROM files (copyrighted)
 *.gb
 *.gbc
 *.rom
 *.gb.ram
+*.sav
+*.state
 
 # IDE
 .vscode/
 .idea/
 *.swp
 *.swo
 *~
+*.sublime-project
+*.sublime-workspace
+*.code-workspace
+.claude/
+.cursor/
+
+# Jupyter Notebook
+.ipynb_checkpoints
 
 # OS
 .DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
 Thumbs.db
+Desktop.ini
 
 # Logs
 *.log
-
-# Agent logs
 logs/
 *.json
 !package.json
 !package-lock.json
+!tsconfig.json
+!pytest.ini
+# Keep validation results in logs/validation/ if needed
+logs/validation/
+
+# Screenshots
+logs/screenshots/
+validation_screenshots/
+*.png
+*.jpg
+*.jpeg
+*.gif
+*.bmp
+*.tiff
+!docs/**/*.png
+!docs/**/*.jpg
+!docs/**/*.jpeg
+
+# Temporary files
+*.tmp
+*.temp
+*.bak
+*.backup
+*.old
+*.orig
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
 

CHANGELOG.md

@@ -5,6 +5,77 @@ All notable changes to Mewtwo will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.7] - 2025-12-21 (In Progress)
+
+### Added
+- **Blank screen detection and handling**
+  - `detect_blank_screen()` method in `GameState` class
+  - Detects screens that are >80% white or black
+  - Automatic handling of blank screens during gameplay transitions
+  - Progressive A-press strategy for blank screen transitions
+- **Character creation protection**
+  - Detects character creation/naming screens
+  - Multiple layers of B-button blocking during character creation
+  - LLM prompt warnings against B during character creation
+  - Response filtering to prevent B presses
+- **Enhanced stuck detection with screenshot saving**
+  - Automatic screenshot saving when agent gets stuck (non-blank screens only)
+  - Descriptive filenames with stuck reason and step count
+  - Multi-modal stuck detection combining multiple signals
+  - Screenshot saving skips blank screens to avoid useless images
+
+### Changed
+- State detection now validates screen content before reporting state
+- Blank screens correctly detected and reported as "loading" state
+- Prevents false "overworld" state detection on blank screens
+- Enhanced stuck detection to skip blank screens
+
+### Fixed
+- Fixed false "overworld" state detection when screen is blank
+- Fixed agent backing out after starting new game
+- Fixed screenshot saving for blank screens (now skipped)
+- Fixed state detection to validate screen content
+
+## [0.0.6] - 2025-12-21
+
+### Added
+- **Enhanced logging and analytics**
+  - Performance metrics tracking (step timing, OCR timing, LLM timing)
+  - Cache hit rate monitoring with detailed statistics
+  - LLM call statistics (count, latency, tokens, success rate, errors, timeouts)
+  - Metrics automatically logged to JSON files
+  - Human-readable metrics summary displayed at end of runs
+  - Rolling averages for recent performance trends
+- **Comprehensive test suite expansion**
+  - Performance benchmark tests (`tests/test_performance.py` - 7 tests)
+    - Step time benchmarks (<50ms target)
+    - Cache hit rate benchmarks (>80% target)
+    - LLM latency benchmarks (<500ms target)
+    - OCR timing benchmarks
+    - Performance regression detection
+  - End-to-end tests (`tests/test_end_to_end.py` - 5 tests)
+    - Early game sequence tests
+    - Menu navigation tests
+    - Overworld movement tests
+    - Dialogue handling tests
+    - State transition tests
+  - Stress tests (`tests/test_stress.py` - 6 tests)
+    - Extended run tests (1000+ and 5000+ steps)
+    - Memory leak detection
+    - Long-running stability tests
+    - Resource limit tests (cache size, action history)
+  - Edge case tests (`tests/test_edge_cases.py` - 10 tests)
+    - Error recovery tests (LLM, game state, memory)
+    - Stuck detection tests (repetitive actions, position stuck, same state)
+    - Edge case scenarios (empty text, long text, rapid changes, invalid actions)
+  - Total test count: 123 tests (up from 95)
+
+### Changed
+- Metrics tracking is now integrated into all components (agent, LLM provider, game state)
+- Log files now include comprehensive metrics data
+- Cache statistics now track evictions
+- Test suite expanded from 95 to 123 tests with comprehensive coverage
+
 ## [0.0.5.1] - 2025-12-19
 
 ### Fixed