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

@@ -14,7 +14,8 @@ final readonly class BatchRelationLoader
         private DatabaseManager $databaseManager,
         private MetadataRegistry $metadataRegistry,
         private IdentityMap $identityMap,
-        private HydratorInterface $hydrator
+        private HydratorInterface $hydrator,
+        private TypeResolver $typeResolver
     ) {
     }
 
@@ -75,7 +76,8 @@ final readonly class BatchRelationLoader
         // Set relations on entities
         foreach ($entities as $entity) {
             $localKey = $this->getLocalKey($entity, $relationMetadata);
-            $relations = $groupedRelations[$localKey] ?? [];
+            $keyString = $this->convertKeyForArray($localKey);
+            $relations = $groupedRelations[$keyString] ?? [];
             $this->setRelationOnEntity($entity, $relationMetadata->name, $relations);
         }
     }
@@ -109,7 +111,8 @@ final readonly class BatchRelationLoader
         // Set relations on entities
         foreach ($entities as $entity) {
             $foreignKey = $this->getForeignKey($entity, $relationMetadata);
-            $relation = $indexedRelations[$foreignKey] ?? null;
+            $keyString = $this->convertKeyForArray($foreignKey);
+            $relation = $indexedRelations[$keyString] ?? null;
             $this->setRelationOnEntity($entity, $relationMetadata->name, $relation);
         }
     }
@@ -140,7 +143,8 @@ final readonly class BatchRelationLoader
 
         foreach ($entities as $entity) {
             $localKey = $this->getLocalKey($entity, $relationMetadata);
-            $relation = $groupedRelations[$localKey][0] ?? null; // Take first (should be only one)
+            $keyString = $this->convertKeyForArray($localKey);
+            $relation = $groupedRelations[$keyString][0] ?? null; // Take first (should be only one)
             $this->setRelationOnEntity($entity, $relationMetadata->name, $relation);
         }
     }
@@ -205,7 +209,8 @@ final readonly class BatchRelationLoader
         foreach ($entities as $entity) {
             $key = $this->getPropertyValue($entity, $foreignKeyProperty);
             if ($key !== null) {
-                $grouped[$key][] = $entity;
+                $keyString = $this->convertKeyForArray($key);
+                $grouped[$keyString][] = $entity;
             }
         }
 
@@ -223,7 +228,8 @@ final readonly class BatchRelationLoader
         foreach ($entities as $entity) {
             $key = $this->getPropertyValue($entity, 'id'); // Assuming 'id' is primary key
             if ($key !== null) {
-                $indexed[$key] = $entity;
+                $keyString = $this->convertKeyForArray($key);
+                $indexed[$keyString] = $entity;
             }
         }
 
@@ -261,7 +267,8 @@ final readonly class BatchRelationLoader
             $query .= " WHERE " . implode(' AND ', $conditions);
         }
 
-        $result = $this->databaseManager->getConnection()->query($query, $params);
+        $sqlQuery = ValueObjects\SqlQuery::create($query, $params);
+        $result = $this->databaseManager->getConnection()->query($sqlQuery);
 
         $entities = [];
         foreach ($result->fetchAll() as $data) {
@@ -302,4 +309,13 @@ final readonly class BatchRelationLoader
             }
         }
     }
+
+    /**
+     * Convert a key to a string for use as array index
+     * Uses TypeResolver to handle Value Objects like ULID properly
+     */
+    private function convertKeyForArray(mixed $key): string
+    {
+        return $this->typeResolver->toArrayKey($key);
+    }
 }