documentation and env changes

src/Command/SeedUserAvatarsCommand.php

@@ -18,6 +18,13 @@ use Symfony\Component\Console\Style\SymfonyStyle;
     name: 'app:seed-user-avatars',
     description: 'Assign generated profile images to existing users.'
 )]
+/**
+ * Seeds or refreshes user profile images using the DiceBear avatar API.
+ *
+ * - Skips users that already have an image unless --overwrite is provided.
+ * - Builds deterministic avatar URLs based on user identity and an optional seed prefix.
+ * - Does not download or cache the avatars locally; URLs are stored directly.
+ */
 class SeedUserAvatarsCommand extends Command
 {
     public function __construct(
@@ -54,6 +61,7 @@ class SeedUserAvatarsCommand extends Command
                 continue;
             }
             if (!$overwrite && $user->getProfileImagePath()) {
+                // Respect existing uploads unless the operator explicitly allows clobbering them.
                 continue;
             }
             $user->setProfileImagePath($this->buildAvatarUrl($user, $style, $seedPrefix));
@@ -73,7 +81,11 @@ class SeedUserAvatarsCommand extends Command
 
     private function buildAvatarUrl(User $user, string $style, string $seedPrefix): string
     {
+        // Use a stable identifier (display name when present, email as fallback)
+        // so the same user is always mapped to the same avatar for a given prefix.
         $identifier = trim((string) ($user->getDisplayName() ?? $user->getEmail()));
+        // Combine prefix, identifier, and primary key into a deterministic hash
+        // and trim it to a shorter seed value accepted by DiceBear.
         $seed = substr(hash('sha256', $seedPrefix . '|' . strtolower($identifier) . '|' . (string) $user->getId()), 0, 32);
 
         return sprintf('https://api.dicebear.com/7.x/%s/svg?seed=%s', rawurlencode($style), $seed);