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/Framework/Database/Migration/MigrationRunnerTest.php

@@ -5,12 +5,31 @@ declare(strict_types=1);
 use App\Framework\Database\ConnectionInterface;
 use App\Framework\Database\Exception\DatabaseException;
 use App\Framework\Database\Migration\Migration;
+use App\Framework\Database\Migration\MigrationCollection;
 use App\Framework\Database\Migration\MigrationRunner;
+use App\Framework\Database\Platform\MySqlPlatform;
 use App\Framework\Database\ResultInterface;
+use App\Framework\Database\ValueObjects\SqlQuery;
+use App\Framework\DateTime\SystemClock;
+use App\Framework\Performance\MemoryMonitor;
+use App\Framework\Performance\OperationTracker;
 
 beforeEach(function () {
     $this->connection = new TestConnection();
-    $this->migrationRunner = new MigrationRunner($this->connection, 'test_migrations');
+    $this->platform = new MySqlPlatform();
+    $this->clock = new SystemClock();
+    $this->memoryMonitor = new MemoryMonitor();
+    $this->operationTracker = new OperationTracker();
+
+    $this->migrationRunner = new MigrationRunner(
+        $this->connection,
+        $this->platform,
+        $this->clock,
+        null, // tableConfig
+        null, // logger
+        $this->operationTracker,
+        $this->memoryMonitor
+    );
 });
 
 test('constructor creates migrations table', function () {
@@ -25,16 +44,12 @@ test('constructor creates migrations table', function () {
 test('migrate runs pending migrations', function () {
     // Mock migration
     $migration = new TestMigration();
-    $migrationData = (object) [
-        'version' => '2024_01_01_000000',
-        'description' => 'Test Migration',
-        'instance' => $migration,
-    ];
+    $migrations = new MigrationCollection($migration);
 
     // Set no applied migrations initially
     $this->connection->setAppliedMigrations([]);
 
-    $result = $this->migrationRunner->migrate([$migrationData]);
+    $result = $this->migrationRunner->migrate($migrations);
 
     expect($result)->toContain('2024_01_01_000000');
     expect($migration->wasExecuted())->toBeTrue();
@@ -44,7 +59,7 @@ test('migrate runs pending migrations', function () {
     $insertQueries = array_filter(
         $queries,
         fn ($q) =>
-        $q['type'] === 'execute' && str_contains($q['sql'], 'INSERT INTO test_migrations')
+        $q['type'] === 'execute' && str_contains($q['sql'], 'INSERT INTO')
     );
     expect($insertQueries)->toHaveCount(1);
 });
@@ -219,38 +234,38 @@ class TestConnection implements ConnectionInterface
         $this->shouldFail = $fail;
     }
 
-    public function execute(string $sql, array $parameters = []): int
+    public function execute(SqlQuery $query): int
     {
-        $this->queries[] = ['type' => 'execute', 'sql' => $sql, 'params' => $parameters];
+        $this->queries[] = ['type' => 'execute', 'sql' => $query->sql, 'params' => $query->parameters->toArray()];
 
-        if ($this->shouldFail && strpos($sql, 'INSERT INTO') !== false) {
+        if ($this->shouldFail && strpos($query->sql, 'INSERT INTO') !== false) {
             throw new DatabaseException('Simulated database failure');
         }
 
         return 1;
     }
 
-    public function query(string $sql, array $parameters = []): ResultInterface
+    public function query(SqlQuery $query): ResultInterface
     {
-        $this->queries[] = ['type' => 'query', 'sql' => $sql, 'params' => $parameters];
+        $this->queries[] = ['type' => 'query', 'sql' => $query->sql, 'params' => $query->parameters->toArray()];
 
         return new TestResult($this->appliedMigrations);
     }
 
-    public function queryOne(string $sql, array $parameters = []): ?array
+    public function queryOne(SqlQuery $query): ?array
     {
         return null;
     }
 
-    public function queryColumn(string $sql, array $parameters = []): array
+    public function queryColumn(SqlQuery $query): array
     {
-        $this->queries[] = ['type' => 'queryColumn', 'sql' => $sql, 'params' => $parameters];
+        $this->queries[] = ['type' => 'queryColumn', 'sql' => $query->sql, 'params' => $query->parameters->toArray()];
 
         // Return the versions from applied migrations
         return array_column($this->appliedMigrations, 'version');
     }
 
-    public function queryScalar(string $sql, array $parameters = []): mixed
+    public function queryScalar(SqlQuery $query): mixed
     {
         return null;
     }