docs: consolidate documentation into organized structure

- Move 12 markdown files from root to docs/ subdirectories
- Organize documentation by category:
  • docs/troubleshooting/ (1 file)  - Technical troubleshooting guides
  • docs/deployment/      (4 files) - Deployment and security documentation
  • docs/guides/          (3 files) - Feature-specific guides
  • docs/planning/        (4 files) - Planning and improvement proposals

Root directory cleanup:
- Reduced from 16 to 4 markdown files in root
- Only essential project files remain:
  • CLAUDE.md (AI instructions)
  • README.md (Main project readme)
  • CLEANUP_PLAN.md (Current cleanup plan)
  • SRC_STRUCTURE_IMPROVEMENTS.md (Structure improvements)

This improves:
✅ Documentation discoverability
✅ Logical organization by purpose
✅ Clean root directory
✅ Better maintainability

src/Framework/Exception/ErrorCode.php

@@ -22,8 +22,12 @@ enum ErrorCode: string
     case DB_CONSTRAINT_VIOLATION = 'DB003';
     case DB_TRANSACTION_FAILED = 'DB004';
     case DB_MIGRATION_FAILED = 'DB005';
-    case DB_POOL_EXHAUSTED = 'DB006';
-    case DB_TIMEOUT = 'DB007';
+    case DB_MIGRATION_ROLLBACK_FAILED = 'DB006';
+    case DB_MIGRATION_TABLE_CREATION_FAILED = 'DB007';
+    case DB_MIGRATION_DEPENDENCY_ERROR = 'DB008';
+    case DB_MIGRATION_PREFLIGHT_FAILED = 'DB009';
+    case DB_POOL_EXHAUSTED = 'DB010';
+    case DB_TIMEOUT = 'DB011';
 
     // Authentication Errors (AUTH)
     case AUTH_CREDENTIALS_INVALID = 'AUTH001';
@@ -41,6 +45,8 @@ enum ErrorCode: string
     case VAL_DUPLICATE_VALUE = 'VAL004';
     case VAL_BUSINESS_RULE_VIOLATION = 'VAL005';
     case VAL_INVALID_INPUT = 'VAL006';
+    case VAL_UNSUPPORTED_OPERATION = 'VAL007';
+    case VAL_INVALID_ARGUMENT = 'VAL008';
 
     // HTTP Errors (HTTP)
     case HTTP_NOT_FOUND = 'HTTP001';
@@ -56,6 +62,7 @@ enum ErrorCode: string
     case SEC_CSRF_TOKEN_MISMATCH = 'SEC004';
     case SEC_UNAUTHORIZED_ACCESS = 'SEC005';
     case SEC_SUSPICIOUS_ACTIVITY = 'SEC006';
+    case SEC_FILE_UPLOAD_REJECTED = 'SEC007';
 
     // Cache Errors (CACHE)
     case CACHE_CONNECTION_FAILED = 'CACHE001';
@@ -77,6 +84,12 @@ enum ErrorCode: string
     case API_INVALID_RESPONSE = 'API004';
     case API_TIMEOUT = 'API005';
 
+    // Payment Errors (PAY)
+    case PAYMENT_GATEWAY_ERROR = 'PAY001';
+    case PAYMENT_INSUFFICIENT_FUNDS = 'PAY002';
+    case PAYMENT_CARD_DECLINED = 'PAY003';
+    case PAYMENT_PROCESSING_FAILED = 'PAY004';
+
     // Service Errors (SVC)
     case SERVICE_CIRCUIT_OPEN = 'SVC001';
     case SERVICE_CIRCUIT_HALF_OPEN = 'SVC002';
@@ -164,6 +177,11 @@ enum ErrorCode: string
     case TPL_VARIABLE_NOT_FOUND = 'TPL003';
     case TPL_COMPILATION_FAILED = 'TPL004';
     case TPL_RENDERING_FAILED = 'TPL005';
+    case TPL_CACHE_FAILED = 'TPL006';
+    case TPL_CONTENT_LOADING_FAILED = 'TPL007';
+    case TPL_PROCESSOR_FAILED = 'TPL008';
+    case TPL_ASSET_NOT_FOUND = 'TPL009';
+    case TPL_INVALID_TEMPLATE_TYPE = 'TPL010';
 
     // Value Object Errors (VO)
     case VO_INVALID_VALUE = 'VO001';
@@ -261,6 +279,11 @@ enum ErrorCode: string
             self::TPL_VARIABLE_NOT_FOUND => 'Template variable not found',
             self::TPL_COMPILATION_FAILED => 'Template compilation failed',
             self::TPL_RENDERING_FAILED => 'Template rendering failed',
+            self::TPL_CACHE_FAILED => 'Template cache operation failed',
+            self::TPL_CONTENT_LOADING_FAILED => 'Template content loading failed',
+            self::TPL_PROCESSOR_FAILED => 'Template processor execution failed',
+            self::TPL_ASSET_NOT_FOUND => 'Template asset file not found',
+            self::TPL_INVALID_TEMPLATE_TYPE => 'Invalid template type or format',
 
             // Value Object Errors
             self::VO_INVALID_VALUE => 'Invalid value for value object',
@@ -274,6 +297,7 @@ enum ErrorCode: string
             self::DB_CONSTRAINT_VIOLATION => 'Database constraint violation occurred',
             self::DB_TRANSACTION_FAILED => 'Database transaction failed',
             self::DB_MIGRATION_FAILED => 'Database migration failed',
+            self::DB_MIGRATION_DEPENDENCY_ERROR => 'Migration dependency validation failed',
             self::DB_POOL_EXHAUSTED => 'Database connection pool exhausted',
             self::DB_TIMEOUT => 'Database operation timed out',
 
@@ -308,6 +332,7 @@ enum ErrorCode: string
             self::SEC_CSRF_TOKEN_MISMATCH => 'CSRF token mismatch',
             self::SEC_UNAUTHORIZED_ACCESS => 'Unauthorized access attempt',
             self::SEC_SUSPICIOUS_ACTIVITY => 'Suspicious activity detected',
+            self::SEC_FILE_UPLOAD_REJECTED => 'File upload rejected by security validation',
 
             // Cache Errors
             self::CACHE_CONNECTION_FAILED => 'Cache connection failed',
@@ -428,6 +453,11 @@ enum ErrorCode: string
             self::TPL_VARIABLE_NOT_FOUND => 'Provide required template variables',
             self::TPL_COMPILATION_FAILED => 'Check template compiler configuration',
             self::TPL_RENDERING_FAILED => 'Review template data and rendering context',
+            self::TPL_CACHE_FAILED => 'Check template cache permissions and storage availability',
+            self::TPL_CONTENT_LOADING_FAILED => 'Verify template file permissions and filesystem access',
+            self::TPL_PROCESSOR_FAILED => 'Check template processor configuration and dependencies',
+            self::TPL_ASSET_NOT_FOUND => 'Verify asset file path and build process',
+            self::TPL_INVALID_TEMPLATE_TYPE => 'Use supported template format or check template extension',
 
             // Value Object Errors
             self::VO_INVALID_VALUE => 'Provide valid value according to value object constraints',
@@ -441,6 +471,7 @@ enum ErrorCode: string
             self::DB_CONSTRAINT_VIOLATION => 'Check data integrity and constraint definitions',
             self::DB_TRANSACTION_FAILED => 'Retry transaction or check for deadlocks',
             self::DB_MIGRATION_FAILED => 'Review migration scripts and database state',
+            self::DB_MIGRATION_DEPENDENCY_ERROR => 'Add missing dependency migrations or review dependency chains',
             self::DB_POOL_EXHAUSTED => 'Increase connection pool size or optimize queries',
             self::DB_TIMEOUT => 'Optimize query performance or increase timeout limits',
 
@@ -475,6 +506,7 @@ enum ErrorCode: string
             self::SEC_CSRF_TOKEN_MISMATCH => 'Include valid CSRF token in request',
             self::SEC_UNAUTHORIZED_ACCESS => 'Authenticate and ensure proper authorization',
             self::SEC_SUSPICIOUS_ACTIVITY => 'Review security logs and investigate activity',
+            self::SEC_FILE_UPLOAD_REJECTED => 'Check file type, size, and content requirements',
 
             // Search Errors
             self::SEARCH_INDEX_FAILED => 'Check search engine connectivity and document format',
@@ -551,6 +583,12 @@ enum ErrorCode: string
             self::EVENT_DISPATCH_FAILED => 5,
             self::EVENT_TIMEOUT => 30,
 
+            // Template retry intervals
+            self::TPL_CACHE_FAILED => 10,
+            self::TPL_CONTENT_LOADING_FAILED => 5,
+            self::TPL_PROCESSOR_FAILED => 15,
+            self::TPL_RENDERING_FAILED => 5,
+
             default => null,
         };
     }

src/Framework/Exception/FrameworkException.php

@@ -228,11 +228,14 @@ class FrameworkException extends \RuntimeException
      */
     public function withErrorCode(ErrorCode $errorCode): self
     {
-        $new = clone $this;
-        $new->errorCode = $errorCode;
-        $new->retryAfter = $errorCode->getRetryAfterSeconds();
-
-        return $new;
+        return new static(
+            message: $this->getMessage(),
+            context: $this->context,
+            code: $this->getCode(),
+            previous: $this->getPrevious(),
+            errorCode: $errorCode,
+            retryAfter: $errorCode->getRetryAfterSeconds()
+        );
     }
 
     /**
@@ -240,10 +243,14 @@ class FrameworkException extends \RuntimeException
      */
     public function withRetryAfter(int $seconds): self
     {
-        $new = clone $this;
-        $new->retryAfter = $seconds;
-
-        return $new;
+        return new static(
+            message: $this->getMessage(),
+            context: $this->context,
+            code: $this->getCode(),
+            previous: $this->getPrevious(),
+            errorCode: $this->errorCode,
+            retryAfter: $seconds
+        );
     }
 
     /**