# cv-tui-py Roadmap

This document outlines planned features and improvements for cv-tui-py, the Python Textual TUI for CV management. Items are organized by category and represent the evolution of the project over coming releases.

## UI & Navigation

- [ ] Vim keybindings mode with full motion support (hjkl, w, b, gg, G, /, ?)
- [ ] Mouse support for clickable actions and widget focus (improve desktop usability)
- [ ] Global search overlay across all screens (Ctrl+/ or /)
- [ ] Custom color themes beyond Catppuccin Mocha (Nord, Dracula, Solarized, user-defined)
- [ ] Breadcrumb navigation indicator for better context awareness
- [ ] Sidebar navigation panel for quick access to screens and filters

## Features & UX

- [ ] Rich notes editor modal (inline editing, markdown preview, multi-line input)
- [ ] File browser widget to preview and download cover letters, resumes
- [ ] Real-time action streaming with progress indicators (percentage, ETA, cancel button)
- [ ] Advanced filtering panel (multi-field, date range, custom predicates, saved filters)
- [ ] Bulk actions on applications (change status, delete, tag, apply action to multiple)
- [ ] Interview scheduling modal with calendar integration
- [ ] Activity timeline with detailed logs of all application state changes
- [ ] Notifications system for completed actions (desktop notifications, Bell widget)

## Configuration & Customization

- [ ] YAML/TOML config schema for keybindings customization
- [ ] Theme generator tool to create custom color palettes
- [ ] Per-screen display preferences (columns shown, sort order, row height)
- [ ] Plugin system architecture for extending screens and widgets
- [ ] Import/export application data (JSON, CSV with templates)

## Performance & Reliability

- [ ] Async connection pooling for httpx client (reuse connections, reduce latency)
- [ ] Lazy loading for large application lists (virtual scrolling, pagination)
- [ ] Request caching with TTL for dashboard and stats data
- [ ] Offline mode with local SQLite fallback (cache applications, replay actions)
- [ ] Auto-reconnect logic with exponential backoff on API timeouts

## Platform & Distribution

- [ ] Homebrew tap for macOS installation (cv-tui-py formula)
- [ ] Snap package for Linux distributions
- [ ] Windows Terminal native support (test ANSI escape sequences, colors, fonts)
- [ ] Build and publish to PyPI with automated releases on GitHub tags
- [ ] Docker container image with cv-api sidecar for easy local setup

## Testing & Quality

- [ ] Snapshot testing for screen outputs (textual-snapshot or similar)
- [ ] Integration tests with mock cv-api server
- [ ] End-to-end tests for user workflows (navigation, create app, run action)
- [ ] Property-based testing for config loading and parsing
- [ ] Coverage reporting and enforcement (>80% line coverage gate)
- [ ] Type checking coverage enforcement with mypy

## Developer Experience

- [ ] Structured logging with DEBUG mode (-v flag) for troubleshooting
- [ ] OpenTelemetry instrumentation for API calls and widget lifecycle
- [ ] Contributing guidelines with architecture documentation
- [ ] Component showcase/storybook for testing widgets in isolation
- [ ] Hot reload capability during development (watch mode)

## CI/CD & Automation

- [ ] Automated changelog generation from conventional commits
- [ ] Semantic versioning with auto-bump on releases
- [ ] Build matrix testing (Python 3.12, 3.13, 3.14+ across macOS, Linux, Windows)
- [ ] Automated PyPI publishing from GitHub Actions on tagged releases
- [ ] Dependabot integration for dependency updates and security patches
- [ ] Code coverage reports to Codecov or similar service

## Documentation

- [ ] API client library documentation (docstrings, type hints, examples)
- [ ] Keybindings reference guide with searchable cheat sheet
- [ ] Widget component documentation for developers
- [ ] Migration guides for breaking changes between versions
- [ ] Troubleshooting guide with common issues and solutions

## Known Issues & Debt

- [ ] Refactor screen base classes to reduce duplication (common _load pattern)
- [ ] Replace hardcoded status strings with enum definitions
- [ ] Add type stubs for Textual dynamic attributes
- [ ] Reduce CSS duplication across theme files
- [ ] Consider state management library (Redux-like pattern) for complex interactions

## CV Integration

### Theme Support

- [ ] Theme preview widget -- Textual widget displaying current theme's primary color and font size
- [ ] Theme selection modal -- interactive screen to preview and select theme before running tailor action
- [ ] Batch theme generation -- action to generate all 4 theme variant PDFs in one go
- [ ] Theme config -- allow per-view theme overrides in ~/.config/cv/config.toml

### Data Quality

- [ ] CV health audit screen -- full-screen view showing 7 audit metrics as progress bars, highlighted duplicate bullet pairs with similarity scores, overused words with frequency counts
- [ ] Health score in apps list -- show color-coded audit score next to each application in the list view
- [ ] Health check command -- `cv-tui health` subcommand showing audit scores and debug info

### AI & Debug

- [ ] Verbose logging with -v flag -- show provider fallback chain in output: "Gemini rate-limited, trying Claude..."
- [ ] AI provider display -- show which provider was used for last action in application detail

---

**Last Updated**: 2026-03-08
**Target Release Cadence**: Quarterly feature updates + continuous bug fixes
**Current Version**: 0.1.0
