Summary Update.

RelayServer/Models/Server/Roles.cs

@@ -2,6 +2,18 @@ using SurrealDb.Net.Models;
 
 namespace RelayServer.Models;
 
+/// <summary>
+/// The permission bitfield. The whole permission model is just:
+///
+///   ServerMembers.IsOwner = true                 → unconditional Administrator
+///   roles.Permissions has Administrator flag     → unconditional everything
+///   channel_permissions.Deny has a specific flag → that permission denied here
+///   channel_permissions.Allow has a specific flag → that permission allowed here
+///   roles.Permissions has the flag               → fallback (channel-independent)
+///
+/// PermissionService.HasPermissionAsync walks that ladder in order. See that class for the
+/// authoritative implementation.
+/// </summary>
 [Flags]
 public enum PermissionFlags
 {
@@ -18,11 +30,21 @@ public enum PermissionFlags
     DeleteChannel     = 1 << 9   // Delete a channel
 }
 
+/// <summary>
+/// Surreal record for the `roles` table. Defines a named permission bundle that can be
+/// assigned to users via UserRoles.
+/// </summary>
 public class Roles : Record
 {
+    /// <summary>Display name ("Admin", "Moderator", "Member").</summary>
     public required string Name { get; set; }
+
+    /// <summary>Base permission bitfield. Channel-level overrides in ChannelPermissions can add or remove.</summary>
     public required PermissionFlags Permissions { get; set; }
+
+    /// <summary>When the role was seeded.</summary>
     public required DateTime CreatedAt { get; set; }
 
+    /// <summary>Tie-breaker for future multi-role-per-user scenarios. Lower = higher priority. Not used by the current ladder.</summary>
     public int Priority { get; set; }
 }