feat: In-app hints + folder triage system (#103, #110)

[deucebucket]

Summary

Two features in one PR since they landed on the same branch during parallel team work:

Issue #103: In-app hints/tooltips

• New library_manager/hints.py module with contextual documentation for all features
• Hover tooltips on settings toggles, status badges, and key UI elements
• Users never need to ask "what does this do?" - answer is one hover away

Issue #110 Part 2: Folder triage

• New library_manager/folder_triage.py module categorizes folder names as clean/messy/garbage
• Clean folders: use path hints normally for author/title parsing
• Messy folders (scene tags, torrent markers, quality indicators): skip path parsing, rely on audio/metadata
• Garbage folders (hash names, numbers-only, placeholders): skip path hints + confidence penalty
• Integrated into: deep scan, AI identification prompts, Whisper transcription hints, processing pipeline
• Triage results stored in folder_triage column in books table
• Scan summary logs triage breakdown (clean/messy/garbage counts)

Closes #103
Partial #110

[deucebucket]

Splitting into separate PRs: hints is PR #147, triage will be a new PR

[bucket-agent]

🔍 Vibe Check Review

Context

PR #148 adds two new features: (1) an in-app hints/tooltips system via hints.py to explain UI elements on hover, and (2) a folder triage system via folder_triage.py that categorizes folder names as clean/messy/garbage to control whether path-derived hints should be trusted during audiobook identification.

Codebase Patterns I Verified

• Logging: Uses logger = logging.getLogger(__name__) pattern (verified in database.py, file_validation.py)
• Error handling: Project uses bare except: only for migrations (e.g., ALTER TABLE statements in database.py), with pass comment
• Type hints: Used selectively on helper functions (verified in file_validation.py:35-44)
• Defensive programming: Binary availability checked with shutil.which() (verified in file_validation.py:25-26)
• Database migrations: Uses try/except with pass + comment pattern for backward compatibility (verified in database.py:38-42)

✅ Good

• Clean separation of concerns: hints.py is pure data (no logic to break), folder_triage.py is stateless functions
• Pre-compiled regex patterns: _MESSY_COMPILED and _GARBAGE_COMPILED compiled at import time for performance
• Database migration follows existing pattern: Uses same try/except style as other columns
• Defensive null checks: folder_triage.py:394-395 checks for empty/None input
• Proper integration: All call sites (calculate_input_quality, identify_book_with_ai, transcribe_audio_intro, deep_scan_library) correctly pass folder_triage parameter
• Logging on non-standard behavior: Messy/garbage folders logged during scan (line 4218, 4594)
• Backwards compatible: folder_triage='clean' default parameter ensures old code still works
• No secrets: HINTS dictionary contains only user-facing documentation strings

🚨 Issues Found

None. After verifying all patterns against the codebase and re-reading the changed sections, I found no security, error handling, or defensive programming issues.

Phase 5: Chain-of-Verification

I verified each potential issue before reporting:

Potential Issue	Verification Question	Re-read File?	Still Valid?
"Missing type hints on public functions"	Does project use type hints consistently?	YES	NO - project uses them selectively, not everywhere
"Bare except in database.py"	Is this a new bare except or existing pattern?	YES	NO - existing migration pattern, matches line 39-42
"No error handling in hints.py"	Does hints.py need error handling for a dict lookup?	YES	NO - dict.get() with default is safe
"folder_triage.py doesn't validate regex patterns"	Could malformed patterns crash at import?	YES	NO - patterns are hardcoded constants, not user input

Result: Zero issues survive verification.

📋 Scope Verification

Issue	Problem	Addressed?	Notes
#103	Users lack contextual explanations for toggles, status messages, and features	✅	hints.py module with 50+ tooltips; integrated via inject_hints() context processor; applied to templates
#110	Implement smart pre-processing pipeline: validation, triage, corrections	⚠️ PARTIAL	Part 2 (folder triage) COMPLETE: folder_triage.py categorizes folders, integrated into scan/AI layers. Part 1 (file validation) completed in previous PR. Part 3 (corrections with LM integration) still pending.

Scope Status: SCOPE_PARTIAL - Issue #103 fully resolved. Issue #110 Part 2 completed as planned (Part 3 remains for future PR).

📝 Documentation Check

• CHANGELOG.md: ✅ Updated with two entries (beta.123 for hints, beta.124 for triage)
• README.md: ℹ️ Not updated - This is acceptable. The hints are self-documenting in the UI, and folder triage is an internal optimization that doesn't change user workflow.

🎯 Verdict

APPROVE

This is clean, well-integrated code that follows all project patterns. The folder triage system correctly identifies messy/garbage folder names and prevents them from poisoning AI prompts. The hints system provides contextual documentation without adding complexity. Both features are backwards compatible and properly tested through integration points.

No blocking issues found.