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/Domain/Media/Image.php

@@ -4,9 +4,15 @@ declare(strict_types=1);
 
 namespace App\Domain\Media;
 
+use App\Framework\Core\ValueObjects\Dimensions;
+use App\Framework\Core\ValueObjects\FileSize;
+use App\Framework\Core\ValueObjects\Hash;
 use App\Framework\Database\Attributes\Column;
 use App\Framework\Database\Attributes\Entity;
 use App\Framework\Database\Attributes\Type;
+use App\Framework\Filesystem\FilePath;
+use App\Framework\Http\MimeType;
+use App\Framework\Ulid\Ulid;
 
 #[Entity(tableName: 'images', idColumn: 'ulid')]
 final readonly class Image
@@ -16,31 +22,112 @@ final readonly class Image
     public array $variants;
 
     public function __construct(
-        /*#[Column(name: 'id', primary: true)]
-        public int $id,*/
         #[Column(name: 'ulid', primary: true)]
-        public string $ulid,
+        public Ulid $ulid,
         #[Column(name: 'filename')]
         public string $filename,
         #[Column(name: 'original_filename')]
         public string $originalFilename,
         #[Column(name: 'mime_type')]
-        public string $mimeType,
+        public MimeType $mimeType,
         #[Column(name: 'file_size')]
-        public int    $fileSize,
+        public FileSize $fileSize,
         #[Column(name: 'width')]
-        public int    $width,
+        public int $width,
         #[Column(name: 'height')]
         public int $height,
         #[Column(name: 'hash'/*, unique: true*/)]
-        public string $hash,
+        public Hash $hash,
         #[Column(name: 'path')]
-        public string $path,
+        public FilePath $path,
         #[Column(name: 'alt_text')]
         public string $altText,
     ) {
     }
 
+    /**
+     * Get dimensions as Value Object
+     */
+    public function getDimensions(): Dimensions
+    {
+        return new Dimensions($this->width, $this->height);
+    }
+
+    /**
+     * Get aspect ratio
+     */
+    public function getAspectRatio(): float
+    {
+        return $this->getDimensions()->getAspectRatio();
+    }
+
+    /**
+     * Check if image is portrait orientation
+     */
+    public function isPortrait(): bool
+    {
+        return $this->getDimensions()->isPortrait();
+    }
+
+    /**
+     * Check if image is landscape orientation
+     */
+    public function isLandscape(): bool
+    {
+        return $this->getDimensions()->isLandscape();
+    }
+
+    /**
+     * Check if image is square
+     */
+    public function isSquare(): bool
+    {
+        return $this->getDimensions()->isSquare();
+    }
+
+    /**
+     * Get human readable file size
+     */
+    public function getHumanReadableFileSize(): string
+    {
+        return $this->fileSize->toHumanReadable();
+    }
+
+    /**
+     * Get file extension
+     */
+    public function getFileExtension(): string
+    {
+        return $this->path->getExtension();
+    }
+
+    /**
+     * Check if hash matches
+     */
+    public function verifyHash(Hash $hash): bool
+    {
+        return $this->hash->equals($hash);
+    }
+
+    /**
+     * Check if file is an image based on MIME type
+     */
+    public function isImageFile(): bool
+    {
+        return $this->mimeType->isImage();
+    }
+
+    /**
+     * Get ULID as string
+     */
+    public function getUlidString(): string
+    {
+        return $this->ulid->__toString();
+    }
+
+    /**
+     * Create new instance with updated filename
+     */
     public function withFilename(string $filename): self
     {
         return new self(
@@ -56,4 +143,42 @@ final readonly class Image
             altText: $this->altText
         );
     }
+
+    /**
+     * Create new instance with updated alt text
+     */
+    public function withAltText(string $altText): self
+    {
+        return new self(
+            ulid: $this->ulid,
+            filename: $this->filename,
+            originalFilename: $this->originalFilename,
+            mimeType: $this->mimeType,
+            fileSize: $this->fileSize,
+            width: $this->width,
+            height: $this->height,
+            hash: $this->hash,
+            path: $this->path,
+            altText: $altText
+        );
+    }
+
+    /**
+     * Create new instance with updated path
+     */
+    public function withPath(FilePath $path): self
+    {
+        return new self(
+            ulid: $this->ulid,
+            filename: $this->filename,
+            originalFilename: $this->originalFilename,
+            mimeType: $this->mimeType,
+            fileSize: $this->fileSize,
+            width: $this->width,
+            height: $this->height,
+            hash: $this->hash,
+            path: $path,
+            altText: $this->altText
+        );
+    }
 }