agent foundation

lib/Http/ApiSystemAuditReporter.php

@@ -91,6 +91,8 @@ class ApiSystemAuditReporter
         );
     }
 
+    // Recording strategy: always log writes and server errors; for reads, only log
+    // failures on security-sensitive endpoints (auth, tokens) to keep volume manageable.
     private function shouldRecord(string $method, string $path, int $statusCode): bool
     {
         if ($method === 'OPTIONS') {
@@ -123,6 +125,8 @@ class ApiSystemAuditReporter
         return str_starts_with($path, '/api/v1/me/tokens');
     }
 
+    // Normalizes dynamic path segments (IDs, UUIDs, token selectors) so audit queries
+    // can group by endpoint pattern rather than individual resource IDs.
     private function endpointKey(string $path): string
     {
         $path = '/' . ltrim(trim($path), '/');