docs: update README files across layers to enhance clarity and consistency

- Added detailed guidelines for Markdown file formatting in CLAUDE.md.
- Improved README files in the Application, Domain, and Infrastructure layers to include additional context and examples.
- Ensured all README files follow a consistent structure and style for better readability.
- Updated documentation for Forum, Tracker, and User domains to reflect recent architectural changes.

These updates aim to provide clearer guidance for developers and maintainers, aligning with the project's focus on modern architecture and clean code practices.

CLAUDE.md

@@ -137,3 +137,23 @@ The TorrentPier 3.0 release represents a major architectural shift focused on:
 - **Language system**: Update global $lang usage to new Language singleton methods
 
 When working with this codebase, prioritize modern architecture patterns and clean code practices. Focus on the new systems in `/src/` directory rather than maintaining legacy compatibility.
+
+## Markdown File Guidelines
+
+When creating or editing `.md` files in this project, follow these linting rules:
+
+### MD032 - Lists surrounded by blank lines
+Always add blank lines before and after lists:
+
+```markdown
+Some text here.
+
+- First item
+- Second item
+- Third item
+
+More text here.
+```
+
+### MD047 - Files should end with a single newline
+Ensure every markdown file ends with exactly one newline character at the end of the file.

docs/specs/hexagonal-architecture-spec.md

@@ -375,26 +375,31 @@ return [
 ## Implementation Order
 
 1. **Phase 1: Foundation**
+
    - Create directory structure
    - Set up base classes in Domain/Shared
    - Configure dependency injection
 
 2. **Phase 2: Domain Modeling**
+
    - Implement core aggregates
    - Create value objects
    - Define repository interfaces
 
 3. **Phase 3: Application Services**
+
    - Create commands and queries
    - Implement handlers
    - Set up event dispatching
 
 4. **Phase 4: Infrastructure**
+
    - Implement repositories
    - Configure database adapter
    - Set up caching
 
 5. **Phase 5: Presentation**
+
    - Create controllers
    - Implement middleware
    - Build CLI commands

src/Application/Forum/Command/README.md

@@ -1,6 +1,7 @@
 # Forum Commands
 
 Commands representing write operations:
+
 - `CreateThreadCommand`: Start new discussion
 - `CreatePostCommand`: Reply to thread
 - `EditPostCommand`: Modify existing post

src/Application/Forum/Handler/README.md

@@ -1,6 +1,7 @@
 # Forum Handlers
 
 Command and query handlers for forum operations:
+
 - `CreateThreadHandler`: Handles thread creation
 - `CreatePostHandler`: Handles post creation
 - `GetThreadListHandler`: Retrieves thread listings

src/Application/Forum/Query/README.md

@@ -1,6 +1,7 @@
 # Forum Queries
 
 Read-only queries for forum data:
+
 - `GetThreadListQuery`: Paginated thread listing
 - `GetPostsByThreadQuery`: Thread posts with pagination
 - `SearchPostsQuery`: Full-text post search

src/Application/README.md

@@ -1,11 +1,13 @@
 # Application Layer
 
 Contains application services that orchestrate domain objects to fulfill use cases.
+
 - Commands: Write operations that change state
 - Queries: Read operations for data retrieval
 - Handlers: Process commands and queries
 
 This layer should:
+
 - Coordinate domain objects
 - Handle transactions
 - Dispatch domain events

src/Application/Tracker/Command/README.md

@@ -1,11 +1,13 @@
 # Tracker Commands
 
 Commands representing write operations:
+
 - `RegisterTorrentCommand`: Register new torrent
 - `UpdateTorrentCommand`: Modify torrent details
 - `DeleteTorrentCommand`: Remove torrent from tracker
 
 Example:
+
 ```php
 final class RegisterTorrentCommand
 {

src/Application/Tracker/Handler/README.md

@@ -1,6 +1,7 @@
 # Tracker Handlers
 
 Command and query handlers for tracker operations:
+
 - `RegisterTorrentHandler`: Processes torrent registration
 - `GetTorrentDetailsHandler`: Retrieves torrent information
 - `UpdateTorrentHandler`: Handles torrent updates

src/Application/Tracker/Query/README.md

@@ -1,6 +1,7 @@
 # Tracker Queries
 
 Read-only queries for tracker data:
+
 - `GetTorrentDetailsQuery`: Single torrent information
 - `GetPeerListQuery`: Active peers for torrent
 - `GetTorrentStatsQuery`: Download/upload statistics

src/Application/User/Command/README.md

@@ -1,6 +1,7 @@
 # User Commands
 
 Commands for user management operations:
+
 - `RegisterUserCommand`: New user registration
 - `ChangePasswordCommand`: Password update
 - `UpdateProfileCommand`: Profile modifications

src/Application/User/Handler/README.md

@@ -1,6 +1,7 @@
 # User Handlers
 
 Command and query handlers for user operations:
+
 - `RegisterUserHandler`: Processes user registration
 - `ChangePasswordHandler`: Handles password changes
 - `GetUserProfileHandler`: Retrieves user profiles

src/Application/User/Query/README.md

@@ -1,6 +1,7 @@
 # User Queries
 
 Read operations for user data:
+
 - `GetUserProfileQuery`: User profile details
 - `SearchUsersQuery`: User search with filters
 - `GetUserStatisticsQuery`: Upload/download stats

src/Domain/Forum/Exception/README.md

@@ -1,6 +1,7 @@
 # Forum Domain Exceptions
 
 Domain-specific exceptions for forum operations:
+
 - `ThreadLockedException`: Attempt to post in locked thread
 - `PostEditTimeExpiredException`: Edit time limit exceeded
 - `ForumAccessDeniedException`: Insufficient permissions

src/Domain/Forum/Model/README.md

@@ -1,12 +1,14 @@
 # Forum Domain Models
 
 Contains aggregate roots and entities for the forum system:
+
 - `Forum`: Forum category aggregate
 - `Thread`: Discussion thread aggregate root
 - `Post`: Individual post entity
 - `Attachment`: File attachment entity
 
 Business rules enforced at this level:
+
 - Post editing time limits
 - Thread locking rules
 - Forum access permissions

src/Domain/Forum/Repository/README.md

@@ -1,6 +1,7 @@
 # Forum Repository Interfaces
 
 Repository interfaces for forum aggregates:
+
 - `ForumRepositoryInterface`: Forum aggregate persistence
 - `ThreadRepositoryInterface`: Thread aggregate persistence
 - `PostRepositoryInterface`: Post queries (read-only)

src/Domain/Forum/ValueObject/README.md

@@ -1,6 +1,7 @@
 # Forum Value Objects
 
 Immutable objects representing forum concepts:
+
 - `PostId`: Unique post identifier
 - `ThreadTitle`: Thread title with validation
 - `PostContent`: Formatted post content

src/Domain/README.md

@@ -1,12 +1,14 @@
 # Domain Layer
 
 This directory contains the core business logic of TorrentPier. Code here should:
+
 - Have no dependencies on frameworks or infrastructure
 - Represent pure business rules and domain models
 - Be testable in isolation
 - Use only PHP language features and domain concepts
 
 ## Bounded Contexts
+
 - **Forum**: Discussion forums, posts, threads
 - **Tracker**: BitTorrent tracking, peers, torrents
 - **User**: User management, authentication, profiles

src/Domain/Shared/Event/README.md

@@ -1,11 +1,13 @@
 # Domain Events
 
 Base classes and interfaces for domain event system:
+
 - `DomainEvent`: Base event interface
 - `EventRecording`: Trait for aggregate event recording
 - `AggregateHistory`: Event sourcing support
 
 Example events:
+
 - `UserRegisteredEvent`
 - `TorrentUploadedEvent`
 - `ThreadCreatedEvent`

src/Domain/Shared/Exception/README.md

@@ -1,6 +1,7 @@
 # Shared Domain Exceptions
 
 Base exception classes used across all bounded contexts:
+
 - `DomainException`: Base domain exception
 - `InvalidArgumentException`: Invalid input validation
 - `EntityNotFoundException`: Generic entity not found

src/Domain/Shared/Model/README.md

@@ -1,6 +1,7 @@
 # Shared Domain Models
 
 Base classes and interfaces used across bounded contexts:
+
 - `AggregateRoot`: Base class for all aggregates
 - `Entity`: Base class for entities
 - `DomainEvent`: Interface for domain events

src/Domain/Shared/Repository/README.md

@@ -1,9 +1,9 @@
 # Shared Repository Interfaces
 
 Common repository patterns and base interfaces:
+
 - `RepositoryInterface`: Base repository contract
 - `ReadOnlyRepositoryInterface`: Query-only operations
 - `AggregateRepositoryInterface`: Aggregate-specific methods
-- `Specification`: Query specification pattern
 
 These define common persistence patterns without implementation details.

src/Domain/Shared/ValueObject/README.md

@@ -1,6 +1,7 @@
 # Shared Value Objects
 
 Common value objects used across contexts:
+
 - `Id`: Generic identifier base class
 - `DateTime`: Immutable datetime wrapper
 - `Money`: Monetary value representation

src/Domain/Tracker/Exception/README.md

@@ -1,6 +1,7 @@
 # Tracker Domain Exceptions
 
 Domain-specific exceptions for tracker operations:
+
 - `InvalidInfoHashException`: Malformed info hash
 - `InactiveTorrentException`: Torrent not active
 - `PeerLimitExceededException`: Too many peers

src/Domain/Tracker/Model/README.md

@@ -1,11 +1,13 @@
 # Tracker Domain Models
 
 Contains aggregate roots and entities for the BitTorrent tracker:
+
 - `Torrent`: Aggregate root for torrent management
 - `Peer`: Entity representing a BitTorrent peer
 - `TorrentStatistics`: Value object for torrent stats
 
 Example:
+
 ```php
 class Torrent extends AggregateRoot
 {

src/Domain/Tracker/Repository/README.md

@@ -1,6 +1,7 @@
 # Tracker Repository Interfaces
 
 Repository interfaces for tracker aggregates:
+
 - `TorrentRepositoryInterface`: Torrent aggregate persistence
 - `PeerRepositoryInterface`: Peer data access
 - `TrackerStatsRepositoryInterface`: Statistics queries

src/Domain/Tracker/ValueObject/README.md

@@ -1,12 +1,14 @@
 # Tracker Value Objects
 
 Immutable objects representing domain concepts:
+
 - `InfoHash`: 20-byte torrent identifier
 - `PeerId`: Peer client identifier
 - `Port`: Network port (1-65535)
 - `BytesTransferred`: Upload/download bytes
 
 Example:
+
 ```php
 final class InfoHash
 {

src/Domain/User/Exception/README.md

@@ -1,6 +1,7 @@
 # User Domain Exceptions
 
 Domain-specific exceptions for user operations:
+
 - `UserNotFoundException`: User not found
 - `DuplicateUsernameException`: Username already taken
 - `InvalidCredentialsException`: Authentication failed

src/Domain/User/Model/README.md

@@ -1,12 +1,14 @@
 # User Domain Models
 
 Contains user management aggregates and entities:
+
 - `User`: User aggregate root
 - `UserProfile`: User profile information
 - `UserCredentials`: Authentication credentials
 - `UserPermissions`: Authorization rules
 
 Business rules:
+
 - Password complexity requirements
 - Username uniqueness
 - Email verification workflow

src/Domain/User/Repository/README.md

@@ -1,6 +1,7 @@
 # User Repository Interface
 
 Repository interface for user aggregate:
+
 - `UserRepositoryInterface`: User persistence and retrieval
   - `findById(UserId $id): ?User`
   - `findByUsername(Username $username): ?User`

src/Domain/User/ValueObject/README.md

@@ -1,6 +1,7 @@
 # User Value Objects
 
 Immutable objects for user domain:
+
 - `UserId`: Unique user identifier
 - `Username`: Username with validation
 - `Email`: Email address with format validation

src/Infrastructure/Cache/File/README.md

@@ -1,6 +1,7 @@
 # File Cache Adapter
 
 File system-based caching implementation:
+
 - Simple file-based storage
 - Suitable for single-server deployments
 - Directory structure optimization

src/Infrastructure/Cache/Memcached/README.md

@@ -1,6 +1,7 @@
 # Memcached Cache Adapter
 
 Memcached-based caching implementation:
+
 - Simple key-value caching
 - Distributed cache support
 - Automatic key expiration

src/Infrastructure/Cache/Redis/README.md

@@ -1,6 +1,7 @@
 # Redis Cache Adapter
 
 Redis-based caching implementation:
+
 - High-performance key-value storage
 - Support for data structures (lists, sets, hashes)
 - TTL management

src/Infrastructure/Email/Template/README.md

@@ -1,6 +1,7 @@
 # Email Templates
 
 Email template management:
+
 - HTML and plain text templates
 - Template variables and placeholders
 - Multi-language support
@@ -8,6 +9,7 @@ Email template management:
 - Preview functionality
 
 Common templates:
+
 - User registration confirmation
 - Password reset
 - Torrent notifications

src/Infrastructure/Email/Transport/README.md

@@ -1,6 +1,7 @@
 # Email Transport
 
 Email delivery mechanisms:
+
 - `SmtpTransport`: Traditional SMTP delivery
 - `SendgridTransport`: SendGrid API integration
 - `MailgunTransport`: Mailgun API integration

src/Infrastructure/FileStorage/Local/README.md

@@ -1,6 +1,7 @@
 # Local File Storage
 
 Local filesystem storage implementation:
+
 - Direct disk storage
 - Directory structure management
 - File permissions handling

src/Infrastructure/FileStorage/S3/README.md

@@ -1,6 +1,7 @@
 # S3 File Storage
 
 Amazon S3 (or compatible) storage implementation:
+
 - Cloud object storage
 - Pre-signed URLs for direct uploads
 - CDN integration support

src/Infrastructure/Persistence/Database/README.md

@@ -1,6 +1,7 @@
 # Database Adapter
 
 Database connection and query building layer:
+
 - `DatabaseAdapterInterface`: Common database operations
 - `QueryBuilder`: Fluent query construction
 - `ConnectionPool`: Connection management

src/Infrastructure/Persistence/Migration/README.md

@@ -1,6 +1,7 @@
 # Database Migrations
 
 Schema version control and migration management:
+
 - Migration files for schema changes
 - Seed data for initial setup
 - Rollback support

src/Infrastructure/Persistence/Repository/README.md

@@ -1,12 +1,14 @@
 # Repository Implementations
 
 Concrete implementations of domain repository interfaces:
+
 - Uses database adapter for persistence
 - Implements caching strategies
 - Handles query optimization
 - Supports multiple database backends
 
 Example:
+
 ```php
 class TorrentRepository implements TorrentRepositoryInterface
 {

src/Infrastructure/README.md

@@ -1,6 +1,7 @@
 # Infrastructure Layer
 
 Technical implementations and external service adapters:
+
 - Database persistence
 - Caching mechanisms
 - Email services

src/Presentation/Cli/Commands/README.md

@@ -1,6 +1,7 @@
 # CLI Commands
 
 Console commands for administrative tasks:
+
 - `UserCreateCommand`: Create users from CLI
 - `CacheClearCommand`: Clear cache stores
 - `MigrateCommand`: Run database migrations

src/Presentation/Http/Controllers/Admin/README.md

@@ -1,12 +1,14 @@
 # Admin Panel Controllers
 
 Administrative interface controllers with enhanced security:
+
 - Role-based access control (RBAC)
 - Audit logging for all actions
 - Additional authentication checks
 - Administrative dashboards and reports
 
 Example:
+
 ```php
 class AdminUserController
 {

src/Presentation/Http/Controllers/Api/README.md

@@ -1,12 +1,14 @@
 # API Controllers
 
 RESTful API endpoints following OpenAPI specification:
+
 - JSON request/response format
 - Proper HTTP status codes
 - HATEOAS where applicable
 - Rate limiting aware
 
 Example:
+
 ```php
 class UserController
 {

src/Presentation/Http/Controllers/Web/README.md

@@ -1,6 +1,7 @@
 # Web Controllers
 
 Traditional web interface controllers:
+
 - HTML response generation
 - Template rendering
 - Form handling
@@ -8,6 +9,7 @@ Traditional web interface controllers:
 - CSRF protection
 
 Controllers for:
+
 - Forum browsing and posting
 - Torrent browsing and downloading
 - User profiles and settings

src/Presentation/Http/Middleware/README.md

@@ -1,6 +1,7 @@
 # HTTP Middleware
 
 Request/response pipeline middleware:
+
 - `AuthenticationMiddleware`: User authentication
 - `AuthorizationMiddleware`: Permission checks
 - `CsrfProtectionMiddleware`: CSRF token validation

src/Presentation/Http/Requests/README.md

@@ -1,6 +1,7 @@
 # HTTP Requests
 
 Request objects and validation:
+
 - Request DTOs with validation rules
 - Type-safe access to request data
 - File upload handling
@@ -8,6 +9,7 @@ Request objects and validation:
 - Custom validation rules
 
 Example:
+
 ```php
 class RegisterRequest extends FormRequest
 {

src/Presentation/Http/Responses/README.md

@@ -1,6 +1,7 @@
 # HTTP Responses
 
 Response transformation and formatting:
+
 - Response factories
 - JSON transformers
 - View presenters

src/Presentation/README.md

@@ -1,6 +1,7 @@
 # Presentation Layer
 
 User interface implementations:
+
 - HTTP controllers for web and API
 - CLI commands for console operations
 - Request/response handling