Summary Update.

RelayServer/Models/Server/ChannelPermissions.cs

@@ -2,10 +2,24 @@ using SurrealDb.Net.Models;
 
 namespace RelayServer.Models;
 
+/// <summary>
+/// Surreal record for the `channel_permissions` table. Per-(channel, role) override of a
+/// role's base permissions.
+///
+/// Allow and Deny are independent masks (NOT a tri-state). Deny wins over Allow when both
+/// have the same flag set. Bits not set in either fall through to the role's base permissions.
+/// </summary>
 public class ChannelPermissions : Record
 {
+    /// <summary>"channels:xyz" — which channel this override applies in.</summary>
     public required string ChannelId { get; set; }
+
+    /// <summary>"roles:abc" — which role this override applies to.</summary>
     public required string RoleId { get; set; }
+
+    /// <summary>Permissions explicitly granted here (overrides "role doesn't have it" for this channel).</summary>
     public PermissionFlags Allow { get; set; }
+
+    /// <summary>Permissions explicitly denied here. Wins over Allow.</summary>
     public PermissionFlags Deny { get; set; }
 }

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; }
 }

RelayServer/Models/Server/ServerMembers.cs

@@ -2,9 +2,22 @@ using SurrealDb.Net.Models;
 
 namespace RelayServer.Models;
 
+/// <summary>
+/// Surreal record for the `server_members` table. Membership list.
+/// Drives DeliverToServerMembers (the fan-out target list for every chat message) and the
+/// authoritative ownership flag for PermissionService.
+/// </summary>
 public class ServerMembers : Record
 {
+    /// <summary>"users:keeper317" — references the Core users table by name convention.</summary>
     public required string UserId { get; set; }
+
+    /// <summary>When the user was added to this server.</summary>
     public required DateTime JoinedAt { get; set; }
+
+    /// <summary>
+    /// Authoritative owner flag. Owner gets unconditional Administrator via
+    /// PermissionService.IsServerOwnerAsync, independent of role assignments.
+    /// </summary>
     public bool IsOwner { get; set; }
-}
+}

RelayServer/Models/Server/Servers.cs

@@ -2,9 +2,18 @@ using SurrealDb.Net.Models;
 
 namespace RelayServer.Models;
 
+/// <summary>
+/// Surreal record for the `servers` table. Currently single-row (one server per deployment),
+/// but the schema supports multi-server in the future.
+/// </summary>
 public class Servers : Record
 {
+    /// <summary>Display name (currently "Test Server" from bootstrap).</summary>
     public required string Name { get; set; }
+
+    /// <summary>"users:keeper317" — the owner. Mirrored as IsOwner=true on the matching ServerMembers row.</summary>
     public required string OwnerUserId { get; set; }
+
+    /// <summary>Server creation timestamp.</summary>
     public required DateTime CreatedAt { get; set; }
-}
+}

RelayServer/Models/Server/UserRoles.cs

@@ -2,9 +2,21 @@ using SurrealDb.Net.Models;
 
 namespace RelayServer.Models;
 
+/// <summary>
+/// Surreal record for the `user_roles` table. Join table linking users to roles.
+///
+/// Invariant: ServerBootstrapService.SetUserRoleAsync guarantees exactly one row per user.
+/// Multi-role-per-user isn't currently supported by the permission ladder — adding it would
+/// just be a matter of removing the bootstrap's "delete stale rows" step.
+/// </summary>
 public class UserRoles : Record
 {
+    /// <summary>"users:keeper317" — the assignee.</summary>
     public required string UserId { get; set; }
+
+    /// <summary>"roles:abc" — the role being granted.</summary>
     public required string RoleId { get; set; }
+
+    /// <summary>When the assignment was made.</summary>
     public required DateTime AssignedAt { get; set; }
 }