Fix preset thumbnail route conflict, improve docs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

app/RSpade/Core/Files/CLAUDE.md

@@ -97,18 +97,55 @@ $name = $photo->original_filename;
 
 ## Thumbnail System
 
-Thumbnails are generated on-demand and cached:
+Thumbnails are generated on-demand and cached.
 
-**Preset types** (defined in config):
-- `cover` - Cover image aspect ratio
-- `square` - 1:1 aspect ratio
-- `landscape` - 16:9 aspect ratio
+**Dynamic thumbnail types** (for `get_thumbnail_url()`):
+- `'cover'` - Crops image to fill exact dimensions
+- `'fit'` - Scales image to fit within dimensions, maintaining aspect ratio
+
+**Retina support**: Thumbnails are automatically generated at 2x the requested dimensions.
+Request your CSS display size - a 300x200 request generates a 600x400 image.
 
 **Dynamic thumbnails**:
-- Limited to `max_dynamic_size` (default 2000px)
+- Limited to `max_dynamic_size` (default 800px base, 1600px actual with 2x)
 - Cached for performance
 - Automatic cleanup via scheduled task
 
+**Preset thumbnails** (for `get_thumbnail_url_preset()`):
+
+Presets must be defined in config before use:
+
+```php
+// rsx/resource/config/rsx.php
+'thumbnails' => [
+    'presets' => [
+        'profile' => [
+            'type' => 'cover',    // 'cover' or 'fit'
+            'width' => 150,       // base width (CSS display size)
+            'height' => 150,      // base height
+        ],
+        'card_image' => [
+            'type' => 'cover',
+            'width' => 400,
+            'height' => 250,
+        ],
+        'document_preview' => [
+            'type' => 'fit',
+            'width' => 800,
+            'height' => 600,
+        ],
+    ],
+],
+```
+
+Usage:
+```php
+$photo->get_thumbnail_url_preset('profile')
+// Generates: /_thumbnail/preset/{key}/profile
+```
+
+**Best practice**: Create a preset for every fixed-size thumbnail in your application (profile photos, card images, list thumbnails, etc.). Presets are preserved permanently. Only use dynamic thumbnails when the size is determined at runtime or varies based on context (e.g., responsive galleries, user-resizable containers).
+
 ## Controller Implementation Pattern
 
 ```php

app/RSpade/Core/Files/File_Attachment_Controller.php

@@ -493,14 +493,14 @@ class File_Attachment_Controller extends Rsx_Controller_Abstract
     /**
      * Generate preset thumbnail for image attachments
      *
-     * Route: /_thumbnail/:key/preset/:preset_name
+     * Route: /_thumbnail/preset/:key/:preset_name
      *
      * Security: Checks file.thumbnail.authorize only
      *
      * @param string $key Attachment key
      * @param string $preset_name Preset name from config
      */
-    #[Route('/_thumbnail/:key/preset/:preset_name', methods: ['GET'])]
+    #[Route('/_thumbnail/preset/:key/:preset_name', methods: ['GET'])]
     #[Auth('Permission::anybody()')]
     public static function thumbnail_preset(Request $request, array $params = [])
     {

app/RSpade/Core/Files/File_Attachment_Model.php

@@ -287,7 +287,7 @@ class File_Attachment_Model extends Rsx_Site_Model_Abstract
             throw new Exception("Thumbnail preset '{$preset_name}' not defined in config");
         }
 
-        return url("/_thumbnail/{$this->key}/preset/{$preset_name}");
+        return url("/_thumbnail/preset/{$this->key}/{$preset_name}");
     }
 
     /**

app/RSpade/Core/Files/THUMBNAILS.md

@@ -53,7 +53,7 @@ Edge case: Identical file content uploaded with different extensions (e.g., `doc
 
 ### Request Processing
 
-**Route**: `/_thumbnail/:key/:type/:width/:height` (dynamic) or `/_thumbnail/:key/preset/:preset_name` (preset)
+**Route**: `/_thumbnail/:key/:type/:width/:height` (dynamic) or `/_thumbnail/preset/:key/:preset_name` (preset)
 
 **Common Flow** (via `generate_and_serve_thumbnail()`):
 1. Validate authorization (`file.thumbnail.authorize` event)