feat: Enhance documentation update protocol in AGENTS.md and REFACTORING_PROGRESS.md; remove version info from CLAUDE.md

AGENTS.md

@@ -651,14 +651,30 @@ except (LookupError, ValueError, AttributeError) as e:
 4. **Simplicity First**: Avoid over-engineering solutions
 5. **Document Changes**: Update relevant documentation
 
-### When Adding Features
+### Documentation Update Protocol
+
+**After every change to functionality, architecture, or deployment — always:**
+
+1. **Update CHANGELOG.md** — add an entry under `[Unreleased]` describing what changed and why
+2. **Update AGENTS.md** — if architecture, file structure, key bindings, settings, screens, or any documented component changed
+3. **Update README.md** — if user-facing behaviour, commands, or config changed
+4. **Check `docs/ToDo.md`** — if the completed work matches a task there, mark it ✅ done
+5. **Propose these updates to the user** before finishing — don't silently skip doc updates
+
+**When a feature request is deferred or postponed:**
+
+1. **Propose adding it to `docs/ToDo.md`** under the appropriate priority section
+2. **If it's large or complex** (multi-step, affects multiple components, or needs design decisions): propose creating a standalone spec file in `docs/` (e.g. `docs/feature-mkv-editor.md`) and add a reference link in `docs/ToDo.md`
+3. **Always confirm with the user** before creating new doc files
+
+**When adding a new feature:**
 
 1. Read existing code and understand architecture
-2. Check `REFACTORING_PROGRESS.md` for pending tasks
+2. Check `docs/ToDo.md` and `docs/REFACTORING_PROGRESS.md` for related pending tasks
 3. Implement features incrementally
 4. Test with real media files
 5. Ensure backward compatibility
-6. Update documentation
+6. Apply Documentation Update Protocol above
 7. Update tests as needed
 8. Run `uv run release` before committing
 
@@ -677,6 +693,7 @@ except (LookupError, ValueError, AttributeError) as e:
 3. Check all formatters (formatting is centralized)
 4. Verify extractor chain (ensure data flow intact)
 5. Run full test suite
+6. Apply Documentation Update Protocol above
 
 ### Common Pitfalls to Avoid
 

CLAUDE.md

@@ -1,8 +1,5 @@
 # CLAUDE.md - AI Assistant Reference
 
-**Version**: 0.8.11
-**Last Updated**: 2026-04-11
-
 > **📘 All technical documentation has been moved to [AGENTS.md](AGENTS.md)**
 
 ## For AI Assistants

docs/REFACTORING_PROGRESS.md

@@ -1,331 +1,105 @@
 # moma - Refactoring Roadmap
 
 **Version**: 0.8.11
-**Last Updated**: 2026-04-11
+**Last Updated**: 2026-04-12
 
-> **📋 For completed work, see [CHANGELOG.md](CHANGELOG.md)**
+> **📋 For completed work detail, see [CHANGELOG.md](../CHANGELOG.md)**
-
-This document tracks the future refactoring plan for moma v0.8.x+.
 
 ---
 
-## Completed Phases
+## Completed (Summary)
 
-✅ **Phase 1**: Critical Bug Fixes (5/5) - [See CHANGELOG.md](CHANGELOG.md)
+| Phase | Description | Version |
-✅ **Phase 2**: Architecture Foundation (5/5) - [See CHANGELOG.md](CHANGELOG.md)
+|-------|-------------|---------|
-✅ **Phase 3**: Code Quality (5/5) - [See CHANGELOG.md](CHANGELOG.md)
+| ✅ Phase 1 | Critical Bug Fixes — cache key fix, resource leaks, thread safety, logging | 0.7.0 |
+| ✅ Phase 2 | Architecture Foundation — `DataExtractor` Protocol, service layer, utility modules, command palette (Ctrl+P) | 0.7.0 |
+| ✅ Phase 3 | Code Quality — constants split into 8 modules, type hints, docstrings, dynamic year validation | 0.7.0 |
+| ✅ Phase 3.6 | Cleanup — `ProposedFilenameView` moved to decorator pattern; `src/decorators/` dir removed | 0.7.0 |
+| ✅ Phase 5 (4/6) | Tests — service, utility, formatter, cache, dataset tests; 560 total, 100% pass rate | 0.7.0 |
+| ✅ Phase 6 (partial) | Docs — AGENTS.md, CHANGELOG.md, README.md, DEVELOP.md created/updated | 0.7.0 |
 
 ---
 
-## Pending Phases
+## Pending
 
-### Phase 3.6: Cleanup and Preparation (2/2 COMPLETED)
+### Phase 4: Refactor to New Architecture
-
-#### 3.6.1 Refactor ProposedNameFormatter to Use Decorator Pattern
-**Status**: ✅ COMPLETED
-
-The class was renamed `ProposedFilenameView` and moved to `src/views/proposed_filename.py`. It now uses the decorator pattern with `@conditional_decorators`, `@text_decorators`, etc. — consistent with the rest of the formatter system.
-
-#### 3.6.2 Clean Up Decorators Directory
-**Status**: ✅ COMPLETED
-
-`src/decorators/` directory no longer exists. All cache decorators live in `src/cache/decorators.py`.
-
----
-
-### Phase 4: Refactor to New Architecture (0/4)
-
-**Goal**: Migrate existing code to use the new architecture from Phase 2.
 
 **Status**: NOT STARTED  
+**Goal**: Migrate existing code to fully use the architecture established in Phase 2.
 
 #### 4.1 Refactor Extractors to Use Protocol
 - Update all extractors to explicitly implement `DataExtractor` Protocol
-- Ensure consistent method signatures
+- Ensure consistent method signatures and fill missing Protocol methods
-- Add missing Protocol methods where needed
+- Update type hints throughout
-- Update type hints to match Protocol
 
-**Files to Update**:
+**Files**: `filename_extractor.py`, `mediainfo_extractor.py`, `metadata_extractor.py`, `fileinfo_extractor.py`, `tmdb_extractor.py`
-- `filename_extractor.py`
-- `mediainfo_extractor.py`
-- `metadata_extractor.py`
-- `fileinfo_extractor.py`
-- `tmdb_extractor.py`
 
 #### 4.2 Refactor Formatters to Use Base Classes
-- Update all formatters to inherit from appropriate base classes
+- Update all formatters to inherit from `DataFormatter`, `TextFormatter`, or `MarkupFormatter`
-- Move to `DataFormatter`, `TextFormatter`, or `MarkupFormatter`
+- Ensure consistent interface across formatter hierarchy
-- Ensure consistent interface
-- Add missing abstract methods
 
-**Files to Update**:
+**Files**: `catalog_formatter.py`, `track_formatter.py`, and all specialized formatters in `src/formatters/`
-- `media_formatter.py`
-- `catalog_formatter.py`
-- `track_formatter.py`
-- `proposed_name_formatter.py`
-- All specialized formatters
 
 #### 4.3 Integrate MomaApp with Services
-- Refactor `app.py` to use service layer
+- Refactor `app.py` to use service layer exclusively
 - Replace direct extractor calls with `MetadataService`
 - Replace direct file operations with `RenameService`
 - Replace direct tree building with `FileTreeService`
-- Remove business logic from UI layer
+- Remove all business logic from UI layer
-
-**Expected Benefits**:
-- Cleaner separation of concerns
-- Easier testing
-- Better error handling
-- More maintainable code
 
 #### 4.4 Update Imports and Dependencies
-- Update all imports to use new architecture
+- Clean up imports after Phase 4.1–4.3
-- Remove deprecated patterns
+- Remove deprecated patterns, verify no circular dependencies
-- Verify no circular dependencies
 - Update tests to match new structure
 
 ---
 
-### Phase 5: Test Coverage (4/6 - 66% Complete)
+### Phase 5: Test Coverage (4/6 — IN PROGRESS)
 
-**Goal**: Achieve comprehensive test coverage for all components.
+#### ⏳ 5.5 Screen Tests
+- Test all 6 screens: OpenScreen, HelpScreen, RenameConfirmScreen, ConvertConfirmScreen, DeleteConfirmScreen, SettingsScreen
+- Mock user input, verify screen transitions and error handling
 
-**Status**: IN PROGRESS
+#### ⏳ 5.6 App Integration Tests
+- End-to-end: directory scan → metadata display → rename
+- Mode switching, cache integration, error handling, command palette flows
 
-#### ✅ 5.1 Service Layer Tests (COMPLETED)
+**Target**: >90% coverage
-- 30+ tests for FileTreeService, MetadataService, RenameService
-- Integration tests for service workflows
-
-#### ✅ 5.2 Utility Module Tests (COMPLETED)
-- 70+ tests for PatternExtractor, LanguageCodeExtractor, FrameClassMatcher
-- Integration tests for utility interactions
-
-#### ✅ 5.3 Formatter Tests (COMPLETED)
-- 40+ tests for all formatter classes
-- FormatterApplier testing
-
-#### ✅ 5.4 Dataset Organization (COMPLETED)
-- Consolidated test data into `datasets/`
-- 46 filename test cases
-- 25 frame class test cases
-- Sample file generator
-
-#### ⏳ 5.5 Screen Tests (PENDING)
-**Status**: NOT STARTED
-
-**Scope**:
-- Test OpenScreen functionality
-- Test HelpScreen display
-- Test RenameConfirmScreen workflow
-- Test SettingsScreen interactions
-- Mock user input
-- Verify screen transitions
-
-#### ⏳ 5.6 App Integration Tests (PENDING)
-**Status**: NOT STARTED
-
-**Scope**:
-- End-to-end workflow testing
-- Directory scanning → metadata display → rename
-- Mode switching (technical/catalog)
-- Cache integration
-- Error handling flows
-- Command palette integration
-
-**Target Coverage**: >90%
 
 ---
 
-### Phase 6: Documentation and Release (0/7)
+### Phase 6: Documentation and Release (partially done)
 
-**Goal**: Finalize documentation and prepare for release.
+#### ✅ Done
+- AGENTS.md — comprehensive technical reference
+- CHANGELOG.md — version history
+- README.md — streamlined user guide
+- DEVELOP.md — developer setup
 
-**Status**: NOT STARTED
+#### Remaining
-
-#### 6.1 Update Technical Documentation
-- ✅ AGENTS.md created
 - [ ] API documentation generation
-- [ ] Architecture diagrams
+- [ ] Architecture diagrams and component interaction flows
-- [ ] Component interaction flows
+- [ ] Contributing guidelines, PR/issue templates
-
+- [ ] Build and test distribution (`uv build`, clean install test)
-#### 6.2 Update User Documentation
+- [ ] PyPI release (optional)
-- ✅ README.md streamlined
-- [ ] User guide with screenshots
-- [ ] Common workflows documentation
-- [ ] Troubleshooting guide
-- [ ] FAQ section
-
-#### 6.3 Update Developer Documentation
-- ✅ DEVELOP.md streamlined
-- [ ] Contributing guidelines
-- [ ] Code review checklist
-- [ ] PR template
-- [ ] Issue templates
-
-#### 6.4 Create CHANGELOG
-- ✅ CHANGELOG.md created
-- [ ] Detailed version history
-- [ ] Migration guides for breaking changes
-- [ ] Deprecation notices
-
-#### 6.5 Version Bump to 0.7.0
-- [ ] Update version in `pyproject.toml`
-- [ ] Update version in all documentation
-- [ ] Tag release in git
-- [ ] Create GitHub release
-
-#### 6.6 Build and Test Distribution
-- [ ] Build wheel and tarball
-- [ ] Test installation from distribution
-- [ ] Verify all commands work
-- [ ] Test on clean environment
-- [ ] Cross-platform testing
-
-#### 6.7 Prepare for PyPI Release (Optional)
-- [ ] Create PyPI account
-- [ ] Configure package metadata
-- [ ] Test upload to TestPyPI
-- [ ] Upload to PyPI
-- [ ] Verify installation from PyPI
 
 ---
 
-## Testing Status
-
-### Current Metrics
-- **Total Tests**: 560
-- **Pass Rate**: 100% (559 passed, 1 skipped)
-- **Coverage**: ~70% (estimated)
-- **Target**: >90%
-
 ### Manual Testing Checklist
-- [ ] Test with large directories (1000+ files)
-- [ ] Test with various video formats
-- [ ] Test TMDB integration with real API
-- [ ] Test poster download and display
-- [ ] Test cache expiration and cleanup
-- [ ] Test concurrent file operations
-- [ ] Test error recovery
-- [ ] Test resource cleanup (no leaks)
-- [ ] Performance regression testing
 
----
+- [ ] Large directories (1000+ files)
-
+- [ ] Various video formats
-## Known Limitations
+- [ ] TMDB integration with real API key
-
+- [ ] Poster download and display (pseudo/viu/richpixels modes)
-### Current Issues
+- [ ] Cache expiration and cleanup
-- TMDB API requires internet connection
+- [ ] Concurrent file operations
-- Poster display requires image-capable terminal
+- [ ] Error recovery (missing files, permission errors, network failures)
-- Some special characters need sanitization
-- Large directories may have slow initial scan
-
-### Planned Fixes
-- Add offline mode with cached data
-- Graceful degradation for terminal without image support
-- Improve filename sanitization
-- Optimize directory scanning with progress indication
-
----
-
-## Breaking Changes to Consider
-
-### Potential Breaking Changes in 0.7.0
-- Cache key format (already changed in 0.6.0)
-- Service layer API (internal, shouldn't affect users)
-- Configuration file schema (may need migration)
-
-### Migration Strategy
-- Provide migration scripts where needed
-- Document all breaking changes in CHANGELOG
-- Maintain backward compatibility where possible
-- Deprecation warnings before removal
-
----
-
-## Performance Goals
-
-### Current Performance
-- ~2 seconds for 100 files (initial scan)
-- ~50ms per file (metadata extraction with cache)
-- ~200ms per file (TMDB lookup)
-
-### Target Performance
-- <1 second for 100 files
-- <30ms per file (cached)
-- <100ms per file (TMDB with cache)
-- Background loading for large directories
-
----
-
-## Architecture Improvements
-
-### Already Implemented (Phase 2)
-- ✅ Protocol-based extractors
-- ✅ Service layer
-- ✅ Utility modules
-- ✅ Unified cache subsystem
-- ✅ Thread pool for concurrent operations
-
-### Future Improvements
-- [ ] Plugin system for custom extractors/formatters
-- [ ] Event-driven architecture for UI updates
-- [ ] Dependency injection container
-- [ ] Configuration validation schema
-- [ ] API versioning
-
----
-
-## Success Criteria
-
-### Phase 4 Complete When:
-- [ ] All extractors implement Protocol
-- [ ] All formatters use base classes
-- [ ] MomaApp uses services exclusively
-- [ ] No direct business logic in UI
-- [ ] All tests passing
-- [ ] No performance regression
-
-### Phase 5 Complete When:
-- [ ] >90% code coverage
-- [ ] All screens tested
-- [ ] Integration tests complete
-- [ ] Manual testing checklist done
-- [ ] Performance goals met
-
-### Phase 6 Complete When:
-- [ ] All documentation updated
-- [ ] Version bumped to 0.7.0
-- [ ] Distribution built and tested
-- [ ] Release notes published
-- [ ] Migration guide available
-
----
-
-## Next Steps
-
-1. **Start Phase 4**: Refactor to new architecture
-   - Begin with extractor Protocol implementation
-   - Update one extractor at a time
-   - Run tests after each change
-   - Document any issues encountered
-
-2. **Complete Phase 5**: Finish test coverage
-   - Add screen tests
-   - Add integration tests
-   - Run coverage analysis
-   - Fix any gaps
-
-3. **Execute Phase 6**: Documentation and release
-   - Update all docs
-   - Build distribution
-   - Test thoroughly
-   - Release v0.7.0
 
 ---
 
 **See Also**:
-- [CHANGELOG.md](CHANGELOG.md) - Completed work
+- [../CHANGELOG.md](../CHANGELOG.md) — Completed work with full details
-- [ToDo.md](ToDo.md) - Future feature requests
+- [ToDo.md](ToDo.md) — Feature requests and future ideas
-- [AGENTS.md](AGENTS.md) - Technical documentation
+- [../AGENTS.md](../AGENTS.md) — Architecture and technical documentation
 
-**Last Updated**: 2026-04-11
+**Last Updated**: 2026-04-12