agent foundation

lib/Support/Flash.php

@@ -4,6 +4,7 @@ namespace MintyPHP\Support;
 
 use MintyPHP\Session;
 
+// Session-based flash message store. Messages are written before a redirect and consumed on the next page.
 class Flash
 {
     private const SESSION_KEY = 'flash_messages';
@@ -19,6 +20,7 @@ class Flash
         }
     }
 
+    // If a key is given, any existing message with the same key+scope is replaced — prevents duplicate notices.
     public static function add(string $type, string $message, ?string $scope = null, ?string $key = null): string
     {
         self::ensureSession();
@@ -93,6 +95,7 @@ class Flash
         }
     }
 
+    // Prevents messages from being cleared on the next render — useful when a redirect chain crosses multiple pages.
     public static function keep(int $times = 1)
     {
         self::ensureSession();