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/MiddlewareConnection.php

@@ -6,6 +6,7 @@ namespace App\Framework\Database;
 
 use App\Framework\Database\Middleware\MiddlewarePipeline;
 use App\Framework\Database\Middleware\QueryContext;
+use App\Framework\Database\ValueObjects\SqlQuery;
 
 final class MiddlewareConnection implements ConnectionInterface
 {
@@ -15,54 +16,55 @@ final class MiddlewareConnection implements ConnectionInterface
     ) {
     }
 
-    public function execute(string $sql, array $parameters = []): int
+    public function execute(SqlQuery $query): int
     {
-        $context = new QueryContext('execute', $sql, $parameters, $this->baseConnection);
+        $context = new QueryContext('execute', $query, $this->baseConnection);
 
         return $this->pipeline->process($context, function (QueryContext $ctx): int {
-            return $ctx->connection->execute($ctx->sql, $ctx->parameters);
+            return $ctx->connection->execute($ctx->query);
         });
     }
 
-    public function query(string $sql, array $parameters = []): ResultInterface
+    public function query(SqlQuery $query): ResultInterface
     {
-        $context = new QueryContext('query', $sql, $parameters, $this->baseConnection);
+        $context = new QueryContext('query', $query, $this->baseConnection);
 
         return $this->pipeline->process($context, function (QueryContext $ctx): ResultInterface {
-            return $ctx->connection->query($ctx->sql, $ctx->parameters);
+            return $ctx->connection->query($ctx->query);
         });
     }
 
-    public function queryOne(string $sql, array $parameters = []): ?array
+    public function queryOne(SqlQuery $query): ?array
     {
-        $context = new QueryContext('queryOne', $sql, $parameters, $this->baseConnection);
+        $context = new QueryContext('queryOne', $query, $this->baseConnection);
 
         return $this->pipeline->process($context, function (QueryContext $ctx): ?array {
-            return $ctx->connection->queryOne($ctx->sql, $ctx->parameters);
+            return $ctx->connection->queryOne($ctx->query);
         });
     }
 
-    public function queryColumn(string $sql, array $parameters = []): array
+    public function queryColumn(SqlQuery $query): array
     {
-        $context = new QueryContext('queryColumn', $sql, $parameters, $this->baseConnection);
+        $context = new QueryContext('queryColumn', $query, $this->baseConnection);
 
         return $this->pipeline->process($context, function (QueryContext $ctx): array {
-            return $ctx->connection->queryColumn($ctx->sql, $ctx->parameters);
+            return $ctx->connection->queryColumn($ctx->query);
         });
     }
 
-    public function queryScalar(string $sql, array $parameters = []): mixed
+    public function queryScalar(SqlQuery $query): mixed
     {
-        $context = new QueryContext('queryScalar', $sql, $parameters, $this->baseConnection);
+        $context = new QueryContext('queryScalar', $query, $this->baseConnection);
 
         return $this->pipeline->process($context, function (QueryContext $ctx): mixed {
-            return $ctx->connection->queryScalar($ctx->sql, $ctx->parameters);
+            return $ctx->connection->queryScalar($ctx->query);
         });
     }
 
     public function beginTransaction(): void
     {
-        $context = new QueryContext('beginTransaction', '', [], $this->baseConnection);
+        $emptyQuery = SqlQuery::create('');
+        $context = new QueryContext('beginTransaction', $emptyQuery, $this->baseConnection);
 
         $this->pipeline->process($context, function (QueryContext $ctx): void {
             $ctx->connection->beginTransaction();
@@ -71,7 +73,8 @@ final class MiddlewareConnection implements ConnectionInterface
 
     public function commit(): void
     {
-        $context = new QueryContext('commit', '', [], $this->baseConnection);
+        $emptyQuery = SqlQuery::create('');
+        $context = new QueryContext('commit', $emptyQuery, $this->baseConnection);
 
         $this->pipeline->process($context, function (QueryContext $ctx): void {
             $ctx->connection->commit();
@@ -80,7 +83,8 @@ final class MiddlewareConnection implements ConnectionInterface
 
     public function rollback(): void
     {
-        $context = new QueryContext('rollback', '', [], $this->baseConnection);
+        $emptyQuery = SqlQuery::create('');
+        $context = new QueryContext('rollback', $emptyQuery, $this->baseConnection);
 
         $this->pipeline->process($context, function (QueryContext $ctx): void {
             $ctx->connection->rollback();