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

tests/debug/test-error-context-system.php

@@ -0,0 +1,172 @@
+<?php
+
+declare(strict_types=1);
+
+require_once __DIR__ . '/../../vendor/autoload.php';
+
+use App\Framework\Exception\FrameworkException;
+use App\Framework\Exception\ErrorCode;
+use App\Framework\Exception\ExceptionContext;
+use App\Framework\Exception\ErrorHandlerContext;
+use App\Framework\Exception\RequestContext;
+use App\Framework\Exception\SystemContext;
+use App\Framework\ErrorHandling\ErrorLogger;
+
+echo "=== Testing Advanced Error Context System ===\n\n";
+
+echo "1. Testing Basic FrameworkException with ErrorCode:\n";
+try {
+    $exception = FrameworkException::create(
+        ErrorCode::DB_CONNECTION_FAILED,
+        "Connection to database failed"
+    )->withData([
+        'host' => 'localhost',
+        'port' => 3306,
+        'database' => 'test_db'
+    ])->withOperation('database.connect', 'DatabaseManager');
+
+    throw $exception;
+} catch (FrameworkException $e) {
+    echo "   ✅ Exception created with ErrorCode\n";
+    echo "      • Message: {$e->getMessage()}\n";
+    echo "      • Error Code: {$e->getErrorCode()?->value}\n";
+    echo "      • Category: {$e->getErrorCode()?->getCategory()}\n";
+    echo "      • Recoverable: " . ($e->isRecoverable() ? 'Yes' : 'No') . "\n";
+    echo "      • Retry After: " . ($e->getRetryAfter() ?? 'None') . " seconds\n";
+    echo "      • Recovery Hint: {$e->getRecoveryHint()}\n";
+    echo "      • Operation: {$e->getContext()->operation}\n";
+    echo "      • Component: {$e->getContext()->component}\n\n";
+}
+
+echo "2. Testing ExceptionContext fluent interface:\n";
+try {
+    $context = ExceptionContext::forOperation('user.create', 'UserService')
+        ->withData([
+            'user_id' => 'user_123',
+            'email' => 'test@example.com'
+        ])
+        ->withDebug([
+            'validation_errors' => ['email_already_exists'],
+            'retry_count' => 1
+        ])
+        ->withMetadata([
+            'security_event' => false,
+            'business_critical' => true
+        ]);
+
+    echo "   ✅ ExceptionContext created with fluent interface\n";
+    echo "      • Operation: {$context->operation}\n";
+    echo "      • Component: {$context->component}\n";
+    echo "      • Data keys: " . implode(', ', array_keys($context->data)) . "\n";
+    echo "      • Debug keys: " . implode(', ', array_keys($context->debug)) . "\n";
+    echo "      • Metadata keys: " . implode(', ', array_keys($context->metadata)) . "\n\n";
+} catch (\Throwable $e) {
+    echo "   ❌ Error: {$e->getMessage()}\n\n";
+}
+
+echo "3. Testing ErrorHandlerContext creation:\n";
+try {
+    $exceptionContext = ExceptionContext::forOperation('payment.process', 'PaymentService')
+        ->withData([
+            'amount' => 99.99,
+            'currency' => 'EUR',
+            'customer_id' => 'cust_123'
+        ])
+        ->withMetadata([
+            'security_event' => true,
+            'security_level' => 'WARN',
+            'security_description' => 'Suspicious payment attempt'
+        ]);
+
+    $requestContext = RequestContext::fromGlobals();
+    $systemContext = SystemContext::current();
+
+    $errorContext = ErrorHandlerContext::create(
+        $exceptionContext,
+        $requestContext,
+        $systemContext,
+        ['transaction_id' => 'tx_456']
+    );
+
+    echo "   ✅ ErrorHandlerContext created\n";
+    echo "      • Request method: " . ($errorContext->request->requestMethod ?? 'CLI') . "\n";
+    echo "      • Client IP: " . ($errorContext->request->clientIp ?? 'localhost') . "\n";
+    echo "      • Memory usage: {$errorContext->system->memoryUsage}\n";
+    echo "      • PHP version: {$errorContext->system->phpVersion}\n";
+    echo "      • Security event: " . ($errorContext->exception->metadata['security_event'] ? 'Yes' : 'No') . "\n\n";
+
+    // Test security event format
+    echo "   📊 Security Event Format:\n";
+    $securityEvent = $errorContext->toSecurityEventFormat('test-app');
+    foreach ($securityEvent as $key => $value) {
+        if (is_string($value) || is_numeric($value)) {
+            echo "      • {$key}: {$value}\n";
+        }
+    }
+    echo "\n";
+
+} catch (\Throwable $e) {
+    echo "   ❌ Error: {$e->getMessage()}\n\n";
+}
+
+echo "4. Testing Error Logging:\n";
+try {
+    // Create an exception with security context
+    $exception = FrameworkException::create(
+        ErrorCode::SEC_UNAUTHORIZED_ACCESS,
+        "Unauthorized access attempt detected"
+    )->withData([
+        'endpoint' => '/admin/dashboard',
+        'user_agent' => 'curl/7.68.0',
+        'ip_address' => '192.168.1.100'
+    ])->withMetadata([
+        'security_event' => true,
+        'security_level' => 'ERROR',
+        'security_description' => 'Unauthorized admin access attempt'
+    ]);
+
+    $errorContext = ErrorHandlerContext::fromException($exception, [
+        'alert_sent' => true,
+        'blocked' => true
+    ]);
+
+    $errorLogger = new ErrorLogger();
+
+    echo "   ✅ Created security exception and error context\n";
+    echo "      • Exception type: " . get_class($exception) . "\n";
+    echo "      • Error code: {$exception->getErrorCode()?->value}\n";
+    echo "      • Security event: " . ($errorContext->exception->metadata['security_event'] ? 'Yes' : 'No') . "\n";
+
+    // Test logging data format
+    $loggingData = $errorContext->forLogging();
+    echo "      • Logging data keys: " . implode(', ', array_keys($loggingData)) . "\n\n";
+
+} catch (\Throwable $e) {
+    echo "   ❌ Error: {$e->getMessage()}\n\n";
+}
+
+echo "5. Testing ErrorCode system:\n";
+try {
+    $errorCodes = [
+        ErrorCode::DB_CONNECTION_FAILED,
+        ErrorCode::AUTH_TOKEN_EXPIRED,
+        ErrorCode::SEC_XSS_ATTEMPT,
+        ErrorCode::VAL_BUSINESS_RULE_VIOLATION,
+        ErrorCode::HTTP_RATE_LIMIT_EXCEEDED
+    ];
+
+    echo "   📋 ErrorCode Analysis:\n";
+    foreach ($errorCodes as $code) {
+        echo "      • {$code->value}:\n";
+        echo "        - Category: {$code->getCategory()}\n";
+        echo "        - Description: {$code->getDescription()}\n";
+        echo "        - Recoverable: " . ($code->isRecoverable() ? 'Yes' : 'No') . "\n";
+        echo "        - Retry after: " . ($code->getRetryAfterSeconds() ?? 'None') . " seconds\n";
+        echo "        - Recovery hint: {$code->getRecoveryHint()}\n\n";
+    }
+
+} catch (\Throwable $e) {
+    echo "   ❌ Error: {$e->getMessage()}\n\n";
+}
+
+echo "=== Advanced Error Context System Test Completed ===\n";