docs: update README and add architecture and testing documentation

README.md

···
 .JML.    YM  `Ybmd9'  `Mbmo`Mbmmd'.JMML.`Mbmmd' `Moo9^Yo..JMML.
 ```
 
-A note, task & time management CLI built with Golang & Charm.sh libs. Inspired by TaskWarrior & todo.txt CLI applications.
+Noteleaf is a unified personal productivity CLI that combines task management, note-taking, and media tracking in one place.
+It provides TaskWarrior-inspired task management with additional support for notes, articles, books, movies, and TV shows - all built with Golang & Charm.sh libs. Inspired by TaskWarrior & todo.txt CLI applications.
+
+## Why?
+
+- **Fragmented productivity tools**: Instead of juggling multiple apps for tasks, notes, reading lists, and media queues, Noteleaf provides a single CLI interface
+- **Terminal-native workflow**: For developers and power users who prefer staying in the terminal, Noteleaf offers rich TUIs without leaving your command line
+    - **Lightweight and fast**: No desktop apps or web interfaces - just a fast, focused CLI tool
+- **Unified data model**: Tasks, notes, and media items can reference each other, creating a connected knowledge and productivity system
+
+## Getting started
+
+### Prerequisites
+
+Go v1.24+
+
+### Installation
+
+```sh
+git clone https://github.com/stormlightlabs/noteleaf
+cd noteleaf
+go build -o ./tmp/noteleaf ./cmd
+go install
+```
+
+### Basic usage
+
+```sh
+# Initialize the application
+noteleaf setup
+
+# Add sample data for exploration
+noteleaf setup seed
+
+# Create your first task
+noteleaf task add "Learn Noteleaf CLI"
+
+# View tasks
+noteleaf task list
+
+# Create a note
+noteleaf note add "My first note"
+
+# Add a book to your reading list
+noteleaf media book add "The Name of the Wind"
+```
+
+## Status
+
+**Status**: Work in Progress (MVP completed)
+
+### Completed
 
-## Development
+Core functionality is complete and stable:
 
-Requires Go v1.24+
+- Task management with projects and tags
+- Note-taking system
+- Article parsing from URLs
+- Media tracking (books, movies, TV shows)
+
+### Planned
+
+- Time tracking integration
+- Advanced search and filtering
+- Export/import functionality
+- Plugin system

docs/cli.md

···
-# CLI Docs
-
-## CommandGroup Interface Pattern
-
-This section outlines the CommandGroup interface pattern for implementing CLI commands in the noteleaf application.
-
-### Core Concepts
-
-Each major command group implements the CommandGroup interface with a `Create() *cobra.Command` method. Command groups receive handlers as constructor dependencies, enabling dependency injection for testing. Handler initialization occurs centrally in main.go with `log.Fatalf` error handling to fail fast during application startup.
-
-### CommandGroup Interface
-
-interface `CommandGroup` provides a consistent contract for all command groups. Each implementation encapsulates related commands and the shared handler dependency. The Create method returns a fully configured cobra command tree.
-
-#### Implementations
-
-TaskCommands handles todo and task-related operations using TaskHandler. MovieCommand manages movie queue operations via MovieHandler.
-TVCommand handles TV show queue operations through TVHandler. NoteCommand manages note operations using NoteHandler.
-
-### Handler Lifecycle
-
-Handlers are created once in `main.go` during application startup. Initialization errors prevent application launch rather than causing runtime failures.
-Handlers persist for the application lifetime without requiring cleanup. Commands access handlers through struct fields rather than creating new instances.
-
-### Testing
-
-`CommandGroup` structs accept handlers as constructor parameters, enabling easy dependency injection of mock handlers for testing.
-Command logic can be tested independently of handler implementations. The interface allows mocking entire command groups for integration testing.
-
-### Registry
-
-`main.go` uses a registry pattern to organize command groups by category. Core commands include task, note, and media functionality.
-Management commands handle configuration, setup, and maintenance operations. The pattern provides clean separation and easy extension for new command groups.
-
-## UI and Styling System
-
-The application uses a structured color palette system located in `internal/ui/colors.go` for consistent terminal output styling.
-
-### Color Architecture
-
-The color system implements a `Key` type with 74 predefined colors from the Charm ecosystem, including warm tones (Cumin, Tang, Paprika), cool tones (Sapphire, Oceania, Zinc), and neutral grays (Pepper through Butter). Each color provides hex values via the `Hex()` method and implements Go's `color.Color` interface through `RGBA()`.
-
-### Predefined Styles
-
-Three core lipgloss styles handle common UI elements:
-
-- `TitleColorStyle` uses color 212 with bold formatting for command titles
-- `SelectedColorStyle` provides white-on-212 highlighting for selected items
-- `HeaderColorStyle` applies color 240 with bold formatting for section headers
-
-### Color Categories
-
-Colors are organized into primary, secondary, and tertiary categories are accessed through `IsPrimary()`, `IsSecondary()`, and `IsTertiary()` methods on the `Key` type.
-
-### Lipgloss Integration
-
-The styling system integrates with the Charmbracelet lipgloss library for terminal UI rendering.
-Colors from the `Key` type convert to lipgloss color values through their `Hex()` method. The predefined `TitleColorStyle`, `SelectedColorStyle`, and `HeaderColorStyle` variables provide lipgloss styles that can be applied to strings with `.Render()`.

docs/dev/ARCHITECTURE.md

···
+# System Architecture
+
+Noteleaf is a CLI/TUI application for task and content management built on Go with SQLite persistence and terminal-based interfaces.
+
+## Core Architecture
+
+### Application Structure
+
+The application follows a layered architecture with clear separation between presentation, business logic, and data access layers.
+
+**Entry Point** - `cmd/main.go` initializes the application with dependency injection, creates handlers, and configures the Cobra command tree using the CommandGroup pattern.
+
+**CLI Framework** - Built on `spf13/cobra` with `charmbracelet/fang` providing enhanced CLI features including color schemes, versioning, and improved help formatting.
+
+**TUI Components** - Interactive interfaces use `charmbracelet/bubbletea` for state management and `charmbracelet/lipgloss` for styling with a consistent color palette system in `internal/ui/colors.go`.
+
+### Data Layer
+
+**Database** - SQLite with schema migrations in `internal/store/sql/migrations/`. The `internal/store` package manages database connections and configuration.
+
+**Repository Pattern** - Data access abstracts through repository interfaces in `internal/repo/` with validation logic ensuring data integrity at the persistence boundary.
+
+**Models** - Entity definitions in `internal/models/` implement standardized Model interfaces with common fields (ID, Created, Modified).
+
+### Business Logic
+
+**Handlers** - Business logic resides in `internal/handlers/` with one handler per domain (TaskHandler, NoteHandler, ArticleHandler, etc.). Handlers receive repository dependencies through constructor injection.
+
+**Services** - Domain-specific operations in `internal/services/` handle complex business workflows and external integrations.
+
+**Validation** - Schema-based validation at repository level with custom ValidationError types providing detailed field-level error messages.
+
+## Domain Features
+
+### Content Management
+
+**Articles** - Web scraping using `gocolly/colly` with domain-specific extraction rules stored in `internal/articles/rules/`. Articles are parsed to markdown and stored with dual file references (markdown + HTML).
+
+**Tasks** - Todo/task management inspired by TaskWarrior with filtering, status tracking, and interactive TUI views.
+
+**Notes** - Simple note management with markdown support and glamour-based terminal rendering.
+
+**Media Queues** - Separate queues for books, movies, and TV shows with status tracking and metadata management.
+
+### User Interface
+
+**Command Groups** - Commands organized into core functionality (task, note, article, media) and management operations (setup, config, status) using the CommandGroup interface pattern.
+
+**Interactive Views** - Bubbletea-based TUI components for list navigation, item selection, and data entry with consistent styling through the lipgloss color system.
+
+**Terminal Output** - Markdown rendering through `charmbracelet/glamour` for rich text display in terminal environments.
+
+## Dependencies
+
+**CLI/TUI** - Cobra command framework, Bubbletea state management, Lipgloss styling, Fang CLI enhancements.
+
+**Data** - SQLite driver (`mattn/go-sqlite3`), TOML configuration parsing.
+
+**Content Processing** - Colly web scraping, HTML/XML query libraries, Glamour markdown rendering, text processing utilities.
+
+**Utilities** - UUID generation, time handling, logging through `charmbracelet/log`.
+
+## Design Decisions and Tradeoffs
+
+### Technology Choices
+
+**Go over Rust** - Go was selected for its simplicity, excellent CLI ecosystem (Cobra, Charm libraries), and faster development velocity. While Rust + Ratatui would provide better memory safety and potentially superior performance, Go's straightforward concurrency model and mature tooling ecosystem made it the pragmatic choice for rapid prototyping and iteration.
+
+**SQLite over PostgreSQL** - SQLite provides zero-configuration deployment and sufficient performance for single-user CLI applications. The embedded database eliminates setup complexity while supporting full SQL features needed for filtering and querying. PostgreSQL would add deployment overhead without meaningful benefits for this use case.
+
+**Repository Pattern over Active Record** - Repository interfaces enable clean separation between business logic and data access, facilitating testing through dependency injection. This pattern scales better than Active Record for complex domain logic while maintaining clear boundaries between layers.
+
+### Architectural Tradeoffs
+
+**CommandGroup Interface** - Centralizes command registration while enabling modular command organization. The pattern requires additional abstraction but provides consistent dependency injection and testing capabilities across all command groups.
+
+**Handler-based Business Logic** - Business logic in handlers rather than rich domain models keeps the codebase simple and avoids over-engineering. While this approach may not scale to complex business rules, it provides clear separation of concerns for the current feature set.
+
+**Dual Storage for Articles** - Articles store both markdown and HTML versions to balance processing speed with format flexibility. This doubles storage requirements but eliminates runtime conversion overhead and preserves original formatting.
+
+### Component Interactions
+
+**Handler → Repository → Database** - Request flow follows a linear path from CLI commands through business logic to data persistence. This pattern ensures consistent validation and error handling while maintaining clear separation of concerns.
+
+**TUI State Management** - Bubbletea's unidirectional data flow provides predictable state updates for interactive components. The model-view-update pattern ensures consistent UI behavior across different terminal environments.
+
+**Configuration and Migration** - Application startup validates configuration and runs database migrations before initializing handlers. This fail-fast approach prevents runtime errors and ensures consistent database schema across deployments.

docs/dev/TESTING.md

···
+# Testing Documentation
+
+This document outlines the testing patterns and practices used in the `noteleaf` application.
+
+## Overview
+
+The codebase follows Go's standard testing practices with specialized testing utilities for complex scenarios. Tests use the standard library along with carefully selected dependencies like faker for data generation and BubbleTea for TUI testing. This approach keeps dependencies minimal while providing robust testing infrastructure for interactive components and complex integrations.
+
+### Organization
+
+Each package contains its own test files alongside the source code. Test files are organized by functionality and mirror the structure of the source code they test. The codebase includes four main test utility files that provide specialized testing infrastructure:
+
+- `internal/services/test_utilities.go` - HTTP mocking and media service testing
+- `internal/repo/test_utilities.go` - Database testing and data generation
+- `internal/ui/test_utilities.go` - TUI testing framework and interactive component testing
+- `internal/handlers/test_utilities.go` - Handler testing with database isolation and input simulation
+
+## Patterns
+
+### Handler Creation
+
+Tests create real handler instances using temporary databases to ensure test isolation. Factory functions handle both database setup and handler initialization, returning both the handler and a cleanup function.
+
+### Database Isolation
+
+Tests use temporary directories and environment variable manipulation to create isolated database instances. Each test gets its own temporary SQLite database that is automatically cleaned up after the test completes.
+
+The `setupCommandTest` function creates a temporary directory, sets `XDG_CONFIG_HOME` to point to it, and initializes the database schema. This ensures tests don't interfere with each other or with development data.
+
+### Resource Management
+
+Tests properly manage resources using cleanup functions returned by factory methods. The cleanup function handles both handler closure and temporary directory removal. This pattern ensures complete resource cleanup even if tests fail.
+
+### Error Handling
+
+Tests use `t.Fatal` for setup errors that prevent test execution and `t.Error` for test assertion failures. Fatal errors stop test execution while errors allow tests to continue checking other conditions.
+
+### Context Cancellation
+
+Error case testing frequently uses context cancellation to simulate database and network failures. The pattern creates a context, immediately cancels it, then calls the function under test to verify error handling. This provides a reliable way to test error paths without requiring complex mock setups or external failure injection.
+
+### Command Structure
+
+Command group tests verify cobra command structure including use strings, aliases, short descriptions, and subcommand presence. Tests check that commands are properly configured without executing their logic.
+
+### Interface Compliance
+
+Tests verify interface compliance using compile-time checks with blank identifier assignments. This ensures structs implement expected interfaces without runtime overhead.
+
+## Test Infrastructure
+
+### Test Utility Frameworks
+
+The codebase provides comprehensive testing utilities organized by layer and functionality. Each test utility file contains specialized helpers, mocks, and test infrastructure for its respective domain.
+
+#### Database Testing Utilities
+
+`internal/repo/test_utilities.go` provides comprehensive database testing infrastructure:
+
+- **In-Memory Database Creation**: `CreateTestDB` creates isolated SQLite databases with full schema
+- **Sample Data Factories**: Functions like `CreateSampleTask`, `CreateSampleBook` generate realistic test data
+- **Faker Integration**: Uses jaswdr/faker for generating realistic fake data with `CreateFakeArticle`
+- **Test Setup Helpers**: `SetupTestData` creates a full set of sample data across all models
+- **Custom Assertions**: Generic assertion helpers like `AssertEqual`, `AssertContains`, `AssertNoError`
+
+#### HTTP Service Testing
+
+`internal/services/test_utilities.go` provides HTTP mocking and media service testing:
+
+- **Mock Configuration**: `MockConfig` structure for configuring service behavior
+- **Function Replacement**: `SetupMediaMocks` replaces service functions with controllable mocks
+- **Sample Data Access**: Helper functions that use embedded HTML samples for realistic testing
+- **Specialized Scenarios**: Pre-configured mock setups for success and failure scenarios
+- **Assertion Helpers**: Domain-specific assertions for movies, TV shows, and error conditions
+
+#### TUI Testing Framework
+
+`internal/ui/test_utilities.go` provides a comprehensive BubbleTea testing framework:
+
+- **TUITestSuite**: Complete testing infrastructure for interactive TUI components
+- **Controlled I/O**: `ControlledOutput` and `ControlledInput` for deterministic testing
+- **Message Simulation**: Key press simulation, message queuing, and timing control
+- **State Verification**: Model state checking and view content assertions
+- **Timeout Handling**: Configurable timeouts for async operations
+- **Mock Repository**: Test doubles for repository interfaces
+
+#### Handler Testing Infrastructure
+
+`internal/handlers/test_utilities.go` provides end-to-end handler testing:
+
+- **Environment Isolation**: `HandlerTestHelper` creates isolated test environments
+- **Input Simulation**: `InputSimulator` for testing interactive components that use `fmt.Scanf`
+- **HTTP Mocking**: Comprehensive HTTP server mocking for external API testing
+- **Database Helpers**: Database corruption and error scenario testing
+- **Editor Mocking**: `MockEditor` for testing file editing workflows
+- **Assertion Helpers**: Handler-specific assertions and verification functions
+
+### Advanced Testing Patterns
+
+#### Input Simulation for Interactive Components
+
+Interactive handlers that use `fmt.Scanf` require special testing infrastructure with an `io.Reader` implementation.
+
+The `InputSimulator` provides controlled input sequences that prevent tests from hanging while maintaining coverage of interactive code paths.
+
+#### TUI Testing with BubbleTea Framework
+
+The TUI testing framework addresses the fundamental challenge of testing interactive terminal applications in a deterministic, concurrent environment. BubbleTea's message-passing architecture creates unique testing requirements that standard Go testing patterns cannot adequately address.
+
+The framework implements a controlled execution environment that replaces BubbleTea's typical program loop with a deterministic testing harness. Rather than running an actual terminal program, the "testing suite" directly manages model state transitions by simulating the Update/View cycle. This approach eliminates the non-deterministic behavior inherent in real terminal interactions while preserving the exact message flow patterns that production code experiences.
+
+State verification relies on function composition patterns where test conditions are expressed as closures that capture specific model states. The `WaitFor` mechanism uses polling with configurable timeouts, addressing the async nature of BubbleTea model updates without creating race conditions. This pattern bridges imperative test assertions with BubbleTea's declarative update model.
+This is inspired by front-end/TS/JS testing patterns.
+
+The framework's I/O abstraction layer replaces terminal input/output with controlled buffers that implement standard Go interfaces.
+This design maintains interface compatibility while providing complete control over timing and content. The controlled I/O system captures all output for later verification and injects precise input sequences, enabling complex interaction testing without external dependencies.
+
+Concurrency management uses channels and context propagation to coordinate between the testing framework and the model under test.
+The suite manages goroutine lifecycle and ensures proper cleanup, preventing test interference and resource leaks. This architecture supports testing of models that perform background operations or handle async events.
+
+#### HTTP Service Mocking
+
+Service testing uses HTTP mocking with request capture. A `MockServer` is instantiated, and its URL is used in test scoped services.
+
+#### Database Schema Testing
+
+Database tests use comprehensive schema setup with (automatic) cleanup
+
+#### Environment Manipulation
+
+Environment testing utilities provide controlled environment manipulation. Environment variables are restored after instantiation.
+
+## Test Organization Patterns
+
+### Single Root Test
+
+The preferred test organization pattern uses a single root test function with nested subtests using `t.Run`. This provides clear hierarchical organization and allows running specific test sections while maintaining shared setup and context. This pattern offers several advantages: clear test hierarchy with logical grouping, ability to run specific test sections, consistent test structure across the codebase, and shared setup that can be inherited by subtests.
+
+### Integration vs Unit Testing
+
+The codebase emphasizes integration testing over heavy mocking by using real handlers and services to verify actual behavior rather than mocked interactions. The goal is to catch integration issues while maintaining test reliability.
+
+### Static Output
+
+UI components support static output modes for testing. Tests capture output using bytes.Buffer and verify content using string contains checks rather than exact string matching for better test maintainability.
+
+### Standard Output Redirection
+
+For testing functions that write to stdout, tests use a pipe redirection pattern with goroutines to capture output. The pattern saves the original stdout, redirects to a pipe, captures output in a separate goroutine, and restores stdout after the test. This ensures clean output capture without interfering with the testing framework.
+
+## Utilities
+
+### Test Data Generation
+
+The codebase uses sophisticated data generation strategies:
+
+- **Factory Functions**: Each package provides factory functions for creating valid test data
+- **Faker Integration**: Uses `jaswdr/faker` for generating realistic fake data with proper randomization
+- **Sample Data Creators**: Functions like `CreateSampleTask`, `CreateSampleBook` provide consistent test data
+- **Embedded Resources**: Services use embedded HTML samples from real API responses for realistic testing
+
+### Assertion Helpers
+
+Custom assertion functions provide clear error messages and reduce test code duplication:
+
+- **Generic Assertions**: `AssertEqual`, `AssertNoError`, `AssertContains` for common checks
+- **Domain-Specific Assertions**: `AssertMovieInResults`, `AssertNoteExists` for specialized verification
+- **TUI Assertions**: `AssertViewContains`, `AssertModelState` for BubbleTea model testing
+- **HTTP Assertions**: `AssertRequestMade` for verifying HTTP interactions
+
+### Mock Infrastructure
+
+Each layer provides specialized mocking capabilities:
+
+- **Service Mocking**: Function replacement with configurable behavior and embedded test data
+- **HTTP Mocking**: `HTTPMockServer` with request capture and response customization
+- **Input Mocking**: `InputSimulator` for deterministic interactive component testing
+- **Editor Mocking**: `MockEditor` for file editing workflow testing
+- **Repository Mocking**: `MockTaskRepository` for TUI component testing
+
+### Environment and Resource Management
+
+Testing utilities provide comprehensive resource management:
+
+- **Environment Isolation**: `EnvironmentTestHelper` for controlled environment variable manipulation
+- **Database Isolation**: Temporary SQLite databases with automatic cleanup
+- **File System Isolation**: Temporary directories with automatic cleanup
+- **Process Isolation**: Handler helpers that create completely isolated test environments
+
+## Testing CLI Commands
+
+Command group tests focus on structure verification rather than execution testing. Tests check command configuration, subcommand presence, and interface compliance. This approach ensures command trees are properly constructed without requiring complex execution mocking.
+
+### CommandGroup Interface Testing
+
+The CommandGroup interface enables testable CLI architecture. Tests verify that command groups implement the interface correctly and return properly configured cobra commands. This pattern separates command structure from command execution.
+
+Interface compliance is tested using compile-time checks within the "Interface Implementations" subtest, ensuring all command structs properly implement the CommandGroup interface without runtime overhead.
+
+## Performance Considerations
+
+Tests avoid expensive operations in setup functions. Handler creation uses real instances but tests focus on structure verification rather than full execution paths. This keeps test suites fast while maintaining coverage of critical functionality.
+
+The single root test pattern allows for efficient resource management where setup costs can be amortized across multiple related test cases.
+
+## Interactive Component Testing
+
+The codebase provides comprehensive testing infrastructure for interactive components, including both terminal UI applications and command-line interfaces that require user input.
+
+### Input Simulation Framework
+
+Interactive handlers that use `fmt.Scanf` require specialized testing infrastructure:
+
+- **InputSimulator**: Provides controlled input sequences that implement `io.Reader`
+- **Menu Selection Helpers**: `MenuSelection`, `MenuCancel`, `MenuSequence` for common interaction patterns
+- **Handler Integration**: Handlers can accept `io.Reader` for input, enabling deterministic testing
+- **Cleanup Management**: Automatic cleanup prevents resource leaks in test environments
+
+### TUI Testing with BubbleTea
+
+The TUI testing framework provides complete testing infrastructure for interactive terminal interfaces:
+
+- **TUITestSuite**: Comprehensive testing framework for BubbleTea models
+- **Message Simulation**: Key press simulation, window resize events, and custom message handling
+- **State Verification**: Model state checking with custom condition functions
+- **View Assertions**: Content verification and output capture
+- **Timing Control**: Configurable timeouts and delay handling for async operations
+- **Mock Integration**: Repository mocking for isolated component testing
+
+### Interactive Test Scenarios
+
+Interactive handlers should test comprehensive scenarios:
+
+- **Valid user selections** - User chooses valid menu options and inputs
+- **Cancellation flows** - User chooses to cancel operations (option 0 or escape keys)
+- **Invalid choices** - User selects out-of-range options or provides invalid input
+- **Navigation patterns** - Keyboard navigation, scrolling, and multi-step interactions
+- **Error handling** - Network errors, service failures, and data validation errors
+- **Empty states** - Search returns no results, empty lists, and missing data
+- **Edge cases** - Boundary conditions, malformed input, and resource constraints
+
+### TUI Component Testing Patterns
+
+BubbleTea components use specialized testing patterns:
+
+- **Key Sequence Testing**: Simulate complex user interactions with timing
+- **State Transition Testing**: Verify model state changes through user actions
+- **View Content Testing**: Assert specific content appears in rendered output
+- **Async Operation Testing**: Handle loading states and network operations
+- **Responsive Design Testing**: Test different terminal sizes and window resize handling
+
+This comprehensive testing approach ensures interactive components work reliably in automated environments while maintaining full coverage of user interaction paths.
+
+## Errors
+
+Error coverage follows a systematic approach to identify and test failure scenarios:
+
+1. **Context Cancellation** - Primary method for testing database and network timeout scenarios
+2. **Invalid Input** - Malformed data, empty inputs, boundary conditions
+3. **Resource Exhaustion** - Database connection failures, memory limits
+4. **Constraint Violations** - Duplicate keys, foreign key failures
+5. **State Validation** - Testing functions with invalid system states
+6. **Interactive Input** - Invalid user choices, cancellation handling, input simulation errors

docs/testing.md

···
-# Testing Documentation
-
-This document outlines the testing patterns and practices used in the `noteleaf` application.
-
-## Overview
-
-The codebase follows Go's standard testing practices without external libraries. Tests use only the standard library package and avoid mock frameworks or assertion libraries. This is to keep dependencies minimal and tests readable using standard Go patterns.
-
-### Organization
-
-Each package contains its own test files alongside the source code. Test files are organized by functionality and mirror the structure of the source code they test.
-
-## Patterns
-
-### Handler Creation Pattern
-
-Tests create real handler instances using temporary databases to ensure test isolation. Factory functions handle both database setup and handler initialization, returning both the handler and a cleanup function.
-
-### Database Isolation
-
-Tests use temporary directories and environment variable manipulation to create isolated database instances. Each test gets its own temporary SQLite database that is automatically cleaned up after the test completes.
-
-The `setupCommandTest` function creates a temporary directory, sets `XDG_CONFIG_HOME` to point to it, and initializes the database schema. This ensures tests don't interfere with each other or with development data.
-
-### Resource Management
-
-Tests properly manage resources using cleanup functions returned by factory methods. The cleanup function handles both handler closure and temporary directory removal. This pattern ensures complete resource cleanup even if tests fail.
-
-### Error Handling
-
-Tests use `t.Fatal` for setup errors that prevent test execution and `t.Error` for test assertion failures. Fatal errors stop test execution while errors allow tests to continue checking other conditions.
-
-### Context Cancellation Testing Pattern
-
-Error case testing frequently uses context cancellation to simulate database and network failures. The pattern creates a context, immediately cancels it, then calls the function under test to verify error handling. This provides a reliable way to test error paths without requiring complex mock setups or external failure injection.
-
-### Command Structure Testing
-
-Command group tests verify cobra command structure including use strings, aliases, short descriptions, and subcommand presence. Tests check that commands are properly configured without executing their logic.
-
-### Interface Compliance Testing
-
-Tests verify interface compliance using compile-time checks with blank identifier assignments. This ensures structs implement expected interfaces without runtime overhead.
-
-## Test Organization Patterns
-
-### Single Root Test
-
-The preferred test organization pattern uses a single root test function with nested subtests using `t.Run`. This provides clear hierarchical organization and allows running specific test sections while maintaining shared setup and context. This pattern offers several advantages: clear test hierarchy with logical grouping, ability to run specific test sections, consistent test structure across the codebase, and shared setup that can be inherited by subtests.
-
-### Integration vs Unit Testing
-
-The codebase emphasizes integration testing over heavy mocking by using real handlers and services to verify actual behavior rather than mocked interactions. The goal is to catch integration issues while maintaining test reliability.
-
-### Static Output
-
-UI components support static output modes for testing. Tests capture output using bytes.Buffer and verify content using string contains checks rather than exact string matching for better test maintainability.
-
-### Standard Output Redirection
-
-For testing functions that write to stdout, tests use a pipe redirection pattern with goroutines to capture output. The pattern saves the original stdout, redirects to a pipe, captures output in a separate goroutine, and restores stdout after the test. This ensures clean output capture without interfering with the testing framework.
-
-## Utilities
-
-### Helpers
-
-Test files include helper functions for creating test data and finding elements in collections. These utilities reduce code duplication and improve test readability.
-
-### Mock Data
-
-Tests create realistic mock data using factory functions (powered by faker) that return properly initialized structs with sensible defaults.
-
-## Testing CLI Commands
-
-Command group tests focus on structure verification rather than execution testing. Tests check command configuration, subcommand presence, and interface compliance. This approach ensures command trees are properly constructed without requiring complex execution mocking.
-
-### CommandGroup Interface Testing
-
-The CommandGroup interface enables testable CLI architecture. Tests verify that command groups implement the interface correctly and return properly configured cobra commands. This pattern separates command structure from command execution.
-
-Interface compliance is tested using compile-time checks within the "Interface Implementations" subtest, ensuring all command structs properly implement the CommandGroup interface without runtime overhead.
-
-## Performance Considerations
-
-Tests avoid expensive operations in setup functions. Handler creation uses real instances but tests focus on structure verification rather than full execution paths. This keeps test suites fast while maintaining coverage of critical functionality.
-
-The single root test pattern allows for efficient resource management where setup costs can be amortized across multiple related test cases.
-
-## Interactive Component Testing
-
-Interactive components that use `fmt.Scanf` for user input require special testing infrastructure to prevent tests from hanging while waiting for stdin.
-
-### Testing Success Scenarios
-
-Interactive handlers should test both success and error paths:
-
-- **Valid user selections** - User chooses valid menu options
-- **Cancellation** - User chooses to cancel (option 0)
-- **Invalid choices** - User selects out-of-range options
-- **Empty results** - Search returns no results
-- **Network errors** - Service calls fail
-
-This ensures tests run reliably in automated environments while maintaining coverage of the non-interactive code paths.
-
-## Errors
-
-Error coverage follows a systematic approach to identify and test failure scenarios:
-
-1. **Context Cancellation** - Primary method for testing database and network timeout scenarios
-2. **Invalid Input** - Malformed data, empty inputs, boundary conditions
-3. **Resource Exhaustion** - Database connection failures, memory limits
-4. **Constraint Violations** - Duplicate keys, foreign key failures
-5. **State Validation** - Testing functions with invalid system states
-6. **Interactive Input** - Invalid user choices, cancellation handling, input simulation errors