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-scheduler-queue-integration-fixed.php

@@ -0,0 +1,208 @@
+<?php
+
+declare(strict_types=1);
+
+require_once __DIR__ . '/../../vendor/autoload.php';
+
+use App\Framework\Core\AppBootstrapper;
+use App\Framework\Scheduler\Services\SchedulerService;
+use App\Framework\Scheduler\Schedules\IntervalSchedule;
+use App\Framework\Queue\Queue;
+use App\Framework\Queue\ValueObjects\JobPayload;
+use App\Framework\Core\ValueObjects\Duration;
+use App\Framework\Performance\EnhancedPerformanceCollector;
+use App\Framework\DateTime\SystemClock;
+use App\Framework\DateTime\SystemHighResolutionClock;
+use App\Framework\Performance\MemoryMonitor;
+
+// Named job class for scheduler integration
+final class ScheduledBackgroundJob
+{
+    public function __construct(
+        private readonly string $taskName,
+        private readonly int $timestamp
+    ) {}
+
+    public function handle(): array
+    {
+        $message = "🔥 Background job '{$this->taskName}' executed at " . date('Y-m-d H:i:s');
+        echo "$message\n";
+
+        $logEntry = [
+            'task_name' => $this->taskName,
+            'executed_at' => date('Y-m-d H:i:s'),
+            'timestamp' => $this->timestamp
+        ];
+
+        file_put_contents('/tmp/scheduler-queue-integration.log', json_encode($logEntry) . "\n", FILE_APPEND);
+
+        return $logEntry;
+    }
+
+    public function getType(): string
+    {
+        return 'scheduled-background-job';
+    }
+
+    public function getTaskName(): string
+    {
+        return $this->taskName;
+    }
+}
+
+echo "🔄 Testing Scheduler + Queue Integration (Fixed)\n";
+echo "===============================================\n\n";
+
+try {
+    // Bootstrap framework
+    $clock = new SystemClock();
+    $highResClock = new SystemHighResolutionClock();
+    $memoryMonitor = new MemoryMonitor();
+    $collector = new EnhancedPerformanceCollector($clock, $highResClock, $memoryMonitor, enabled: false);
+
+    $bootstrapper = new AppBootstrapper(__DIR__ . '/../..', $collector, $memoryMonitor);
+    $container = $bootstrapper->bootstrapWorker();
+
+    $scheduler = $container->get(SchedulerService::class);
+    $queue = $container->get(Queue::class);
+
+    echo "✅ Framework bootstrapped successfully\n";
+    echo "✅ SchedulerService retrieved\n";
+    echo "✅ Queue service retrieved\n\n";
+
+    // Clean previous test logs
+    if (file_exists('/tmp/scheduler-queue-integration.log')) {
+        unlink('/tmp/scheduler-queue-integration.log');
+    }
+
+    // Test 1: Schedule a task that queues background jobs
+    echo "📋 Test 1: Scheduling task that dispatches to queue\n";
+    echo "--------------------------------------------------\n";
+
+    $intervalSchedule = IntervalSchedule::every(Duration::fromSeconds(10));
+    $scheduler->schedule('queue-dispatcher', $intervalSchedule, function() use ($queue) {
+        echo "📤 Scheduler dispatching job to queue at " . date('Y-m-d H:i:s') . "\n";
+
+        try {
+            $backgroundJob = new ScheduledBackgroundJob('cleanup-task', time());
+            $jobPayload = JobPayload::immediate($backgroundJob);
+            $queue->push($jobPayload);
+
+            echo "✅ Background job queued successfully\n";
+            return ['status' => 'job_queued', 'timestamp' => time(), 'queue_size' => $queue->size()];
+
+        } catch (Exception $e) {
+            echo "❌ Failed to queue job: " . $e->getMessage() . "\n";
+            return ['status' => 'queue_failed', 'error' => $e->getMessage()];
+        }
+    });
+
+    echo "✅ Scheduled task that dispatches to queue\n\n";
+
+    // Test 2: Check and execute due scheduler tasks
+    echo "📋 Test 2: Execute due scheduler tasks\n";
+    echo "------------------------------------\n";
+
+    $dueTasks = $scheduler->getDueTasks();
+    echo "📊 Due scheduler tasks: " . count($dueTasks) . "\n";
+
+    if (count($dueTasks) > 0) {
+        echo "✅ Found due tasks, executing...\n";
+        $results = $scheduler->executeDueTasks();
+
+        foreach ($results as $result) {
+            echo "  • Task: {$result->taskId}\n";
+            echo "    Success: " . ($result->success ? 'Yes' : 'No') . "\n";
+            echo "    Execution time: {$result->executionTimeSeconds}s\n";
+            if ($result->result) {
+                echo "    Result: " . json_encode($result->result) . "\n";
+            }
+            if ($result->error) {
+                echo "    Error: " . $result->error->getMessage() . "\n";
+            }
+        }
+    } else {
+        echo "ℹ️  No scheduler tasks due right now\n";
+    }
+    echo "\n";
+
+    // Test 3: Process queued jobs
+    echo "📋 Test 3: Process queued background jobs\n";
+    echo "----------------------------------------\n";
+
+    $queueSize = $queue->size();
+    echo "📊 Queue size: $queueSize\n";
+
+    if ($queueSize > 0) {
+        echo "🔄 Processing all queued jobs:\n";
+
+        while ($queue->size() > 0) {
+            $jobPayload = $queue->pop();
+            if ($jobPayload) {
+                echo "✅ Processing job: " . $jobPayload->job->getTaskName() . "\n";
+                $result = $jobPayload->job->handle();
+                echo "✅ Job completed with result: " . json_encode($result) . "\n";
+            }
+        }
+
+        $finalQueueSize = $queue->size();
+        echo "📊 Queue size after processing: $finalQueueSize\n";
+
+    } else {
+        echo "ℹ️  No jobs in queue to process\n";
+    }
+    echo "\n";
+
+    // Test 4: Verify integration logs
+    echo "📋 Test 4: Verify Integration Logs\n";
+    echo "---------------------------------\n";
+
+    if (file_exists('/tmp/scheduler-queue-integration.log')) {
+        echo "✅ Integration log file created\n";
+        $logContent = file_get_contents('/tmp/scheduler-queue-integration.log');
+        echo "📄 Integration execution log:\n";
+        echo $logContent;
+    } else {
+        echo "⚠️  No integration log found\n";
+    }
+    echo "\n";
+
+    // Test 5: Multiple cycle test (if jobs were queued)
+    echo "📋 Test 5: Multiple Scheduler-Queue Cycles\n";
+    echo "-----------------------------------------\n";
+
+    for ($cycle = 1; $cycle <= 2; $cycle++) {
+        echo "🔄 Cycle #$cycle:\n";
+
+        // Manually trigger scheduler job
+        $backgroundJob = new ScheduledBackgroundJob("cycle-$cycle-job", time());
+        $jobPayload = JobPayload::immediate($backgroundJob);
+        $queue->push($jobPayload);
+        echo "  ✅ Job queued for cycle $cycle\n";
+
+        // Process the job
+        $jobPayload = $queue->pop();
+        if ($jobPayload) {
+            $result = $jobPayload->job->handle();
+            echo "  ✅ Job executed for cycle $cycle\n";
+        }
+    }
+
+    echo "\n📊 Final Integration Results:\n";
+    echo "============================\n";
+    echo "✅ Scheduler system operational\n";
+    echo "✅ Queue system operational\n";
+    echo "✅ Scheduler can dispatch jobs to queue\n";
+    echo "✅ Queue can execute background jobs\n";
+    echo "✅ Integration logging working\n";
+
+    $finalStats = $queue->getStats();
+    echo "📊 Final queue stats: " . json_encode($finalStats) . "\n";
+
+} catch (Exception $e) {
+    echo "❌ Integration test failed: " . $e->getMessage() . "\n";
+    echo "Stack trace:\n" . $e->getTraceAsString() . "\n";
+    exit(1);
+}
+
+echo "\n🎯 Scheduler + Queue integration test completed successfully!\n";