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/Database/PdoConnection.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace App\Framework\Database;
 
 use App\Framework\Database\Exception\DatabaseException;
+use App\Framework\Database\ValueObjects\SqlQuery;
 
 final class PdoConnection implements ConnectionInterface
 {
@@ -19,11 +20,11 @@ final class PdoConnection implements ConnectionInterface
         #$this->pdo->setAttribute(\PDO::ATTR_DEFAULT_FETCH_MODE, \PDO::FETCH_ASSOC);
     }
 
-    public function execute(string $sql, array $parameters = []): int
+    public function execute(SqlQuery $query): int
     {
         try {
-            $statement = $this->pdo->prepare($sql);
-            $statement->execute($parameters);
+            $statement = $this->pdo->prepare($query->sql);
+            $statement->execute($query->parameters->toPdoArray());
 
             return $statement->rowCount();
         } catch (\PDOException $e) {
@@ -31,35 +32,37 @@ final class PdoConnection implements ConnectionInterface
         }
     }
 
-    public function query(string $sql, array $parameters = []): ResultInterface
+    public function query(SqlQuery $query): ResultInterface
     {
         try {
-            $statement = $this->pdo->prepare($sql);
-            $statement->execute($parameters);
+            $statement = $this->pdo->prepare($query->sql);
+            $statement->execute($query->parameters->toPdoArray());
 
             return new PdoResult($statement);
         } catch (\PDOException $e) {
-            throw DatabaseException::simple("Failed to execute query: {$e->getMessage()} --- SQL: {$sql} PARAMETERS: {".implode(", ", $parameters)."}", $e);
+            $debug = $query->toDebugString();
+
+            throw DatabaseException::simple("Failed to execute query: {$e->getMessage()} --- Debug: {$debug}", $e);
         }
     }
 
-    public function queryOne(string $sql, array $parameters = []): ?array
+    public function queryOne(SqlQuery $query): ?array
     {
-        $result = $this->query($sql, $parameters);
+        $result = $this->query($query);
 
         return $result->fetch();
     }
 
-    public function queryColumn(string $sql, array $parameters = []): array
+    public function queryColumn(SqlQuery $query): array
     {
-        $result = $this->query($sql, $parameters);
+        $result = $this->query($query);
 
         return $result->fetchColumn();
     }
 
-    public function queryScalar(string $sql, array $parameters = []): mixed
+    public function queryScalar(SqlQuery $query): mixed
     {
-        $result = $this->query($sql, $parameters);
+        $result = $this->query($query);
 
         return $result->fetchScalar();
     }