Merge origin/main with local pending work and update AGENTS.md references

- Resolve 14 conflicts from popping local stash on top of origin's
  eed1e88 + 8d3352f doc-comment additions (11 mechanical, plus
  version.rs, DashboardAuthenticatorTests.cs, DashboardGalaxyProjector.cs)
- Fix 4 test files that used AGENTS.md as the repo-root sentinel
  (now use CLAUDE.md, since AGENTS.md was removed in 4731ab5)
- Redirect 10 doc citations from AGENTS.md to the matching gateway.md
  sections (Value Model, Status Model, Security, STA Worker Thread
  Model, gRPC Layer rule, cancellation rule)

Verified: solution build clean, x86 worker build clean, 266/266
gateway tests passing, 121/121 worker tests passing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/MxGateway.Server/Security/Authentication/ApiKeyAdminCliRunner.cs

@@ -67,6 +67,7 @@ public sealed class ApiKeyAdminCliRunner(
                     SecretHash: hasher.HashSecret(secret),
                     DisplayName: Required(command.DisplayName),
                     Scopes: command.Scopes,
+                    Constraints: command.Constraints,
                     CreatedUtc: DateTimeOffset.UtcNow),
                 cancellationToken)
             .ConfigureAwait(false);
@@ -172,6 +173,7 @@ public sealed class ApiKeyAdminCliRunner(
             KeyPrefix: key.KeyPrefix,
             DisplayName: key.DisplayName,
             Scopes: key.Scopes,
+            Constraints: key.Constraints,
             CreatedUtc: key.CreatedUtc,
             LastUsedUtc: key.LastUsedUtc,
             RevokedUtc: key.RevokedUtc);

src/MxGateway.Server/Security/Authentication/ApiKeyAdminCommand.cs

@@ -7,4 +7,5 @@ public sealed record ApiKeyAdminCommand(
     string? Pepper,
     string? KeyId,
     string? DisplayName,
-    IReadOnlySet<string> Scopes);
+    IReadOnlySet<string> Scopes,
+    ApiKeyConstraints Constraints);

src/MxGateway.Server/Security/Authentication/ApiKeyAdminCommandLineParser.cs

@@ -22,7 +22,7 @@ public static class ApiKeyAdminCommandLineParser
             return ApiKeyAdminParseResult.Fail($"Unknown apikey subcommand '{args[1]}'.");
         }
 
-        Dictionary<string, string?> options = new(StringComparer.OrdinalIgnoreCase);
+        Dictionary<string, List<string?>> options = new(StringComparer.OrdinalIgnoreCase);
         bool json = false;
 
         for (int index = 2; index < args.Count; index++)
@@ -52,18 +52,42 @@ public static class ApiKeyAdminCommandLineParser
             {
                 if (index + 1 >= args.Count || args[index + 1].StartsWith("--", StringComparison.Ordinal))
                 {
-                    return ApiKeyAdminParseResult.Fail($"Option '--{name}' requires a value.");
+                    if (IsBooleanConstraintFlag(name))
+                    {
+                        value = "true";
+                    }
+                    else
+                    {
+                        return ApiKeyAdminParseResult.Fail($"Option '--{name}' requires a value.");
+                    }
+                }
+                else
+                {
+                    value = args[++index];
                 }
-
-                value = args[++index];
             }
 
-            options[name] = value;
+            if (!options.TryGetValue(name, out List<string?>? values))
+            {
+                values = [];
+                options[name] = values;
+            }
+
+            values.Add(value);
         }
 
         string? keyId = GetOption(options, "key-id");
         string? displayName = GetOption(options, "display-name");
         IReadOnlySet<string> scopes = ParseScopes(GetOption(options, "scopes"));
+        ApiKeyConstraints constraints;
+        try
+        {
+            constraints = ParseConstraints(options);
+        }
+        catch (FormatException exception)
+        {
+            return ApiKeyAdminParseResult.Fail(exception.Message);
+        }
 
         string? validationError = Validate(kind, keyId, displayName);
         if (validationError is not null)
@@ -78,7 +102,8 @@ public static class ApiKeyAdminCommandLineParser
             Pepper: GetOption(options, "pepper"),
             KeyId: keyId,
             DisplayName: displayName,
-            Scopes: scopes));
+            Scopes: scopes,
+            Constraints: constraints));
     }
 
     private static bool TryParseKind(string value, out ApiKeyAdminCommandKind kind)
@@ -147,9 +172,56 @@ public static class ApiKeyAdminCommandLineParser
             || character is '.' or '-');
     }
 
-    private static string? GetOption(Dictionary<string, string?> options, string name)
+    private static string? GetOption(Dictionary<string, List<string?>> options, string name)
     {
-        return options.TryGetValue(name, out string? value) ? value : null;
+        return options.TryGetValue(name, out List<string?>? values) && values.Count > 0 ? values[^1] : null;
+    }
+
+    private static IReadOnlyList<string> GetOptions(Dictionary<string, List<string?>> options, string name)
+    {
+        return options.TryGetValue(name, out List<string?>? values)
+            ? values.Where(value => !string.IsNullOrWhiteSpace(value)).Select(value => value!).ToArray()
+            : Array.Empty<string>();
+    }
+
+    private static bool HasFlag(Dictionary<string, List<string?>> options, string name)
+    {
+        return options.ContainsKey(name);
+    }
+
+    private static bool IsBooleanConstraintFlag(string name)
+    {
+        return string.Equals(name, "read-alarm-only", StringComparison.OrdinalIgnoreCase)
+            || string.Equals(name, "read-historized-only", StringComparison.OrdinalIgnoreCase);
+    }
+
+    private static ApiKeyConstraints ParseConstraints(Dictionary<string, List<string?>> options)
+    {
+        return new ApiKeyConstraints(
+            ReadSubtrees: GetOptions(options, "read-subtree"),
+            WriteSubtrees: GetOptions(options, "write-subtree"),
+            ReadTagGlobs: GetOptions(options, "read-tag-glob"),
+            WriteTagGlobs: GetOptions(options, "write-tag-glob"),
+            MaxWriteClassification: ParseNullableInt(GetOption(options, "max-write-classification")),
+            BrowseSubtrees: GetOptions(options, "browse-subtree"),
+            ReadAlarmOnly: HasFlag(options, "read-alarm-only"),
+            ReadHistorizedOnly: HasFlag(options, "read-historized-only"));
+    }
+
+    private static int? ParseNullableInt(string? value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            return null;
+        }
+
+        return int.TryParse(
+            value,
+            System.Globalization.NumberStyles.Integer,
+            System.Globalization.CultureInfo.InvariantCulture,
+            out int parsed)
+            ? parsed
+            : throw new FormatException("--max-write-classification must be an integer.");
     }
 
     private static IReadOnlySet<string> ParseScopes(string? scopes)

src/MxGateway.Server/Security/Authentication/ApiKeyAdminListedKey.cs

@@ -5,6 +5,7 @@ public sealed record ApiKeyAdminListedKey(
     string KeyPrefix,
     string DisplayName,
     IReadOnlySet<string> Scopes,
+    ApiKeyConstraints Constraints,
     DateTimeOffset CreatedUtc,
     DateTimeOffset? LastUsedUtc,
     DateTimeOffset? RevokedUtc);

src/MxGateway.Server/Security/Authentication/ApiKeyCreateRequest.cs

@@ -6,4 +6,5 @@ public sealed record ApiKeyCreateRequest(
     byte[] SecretHash,
     string DisplayName,
     IReadOnlySet<string> Scopes,
+    ApiKeyConstraints Constraints,
     DateTimeOffset CreatedUtc);

src/MxGateway.Server/Security/Authentication/ApiKeyIdentity.cs

@@ -4,4 +4,8 @@ public sealed record ApiKeyIdentity(
     string KeyId,
     string KeyPrefix,
     string DisplayName,
-    IReadOnlySet<string> Scopes);
+    IReadOnlySet<string> Scopes,
+    ApiKeyConstraints? Constraints = null)
+{
+    public ApiKeyConstraints EffectiveConstraints => Constraints ?? ApiKeyConstraints.Empty;
+}

src/MxGateway.Server/Security/Authentication/ApiKeyRecord.cs

@@ -6,6 +6,7 @@ public sealed record ApiKeyRecord(
     byte[] SecretHash,
     string DisplayName,
     IReadOnlySet<string> Scopes,
+    ApiKeyConstraints Constraints,
     DateTimeOffset CreatedUtc,
     DateTimeOffset? LastUsedUtc,
     DateTimeOffset? RevokedUtc);

src/MxGateway.Server/Security/Authentication/ApiKeyRecordReader.cs

@@ -16,9 +16,10 @@ public static class ApiKeyRecordReader
             SecretHash: (byte[])reader["secret_hash"],
             DisplayName: reader.GetString(3),
             Scopes: ApiKeyScopeSerializer.Deserialize(reader.GetString(4)),
-            CreatedUtc: DateTimeOffset.Parse(reader.GetString(5), System.Globalization.CultureInfo.InvariantCulture),
-            LastUsedUtc: ReadNullableDateTimeOffset(reader, 6),
-            RevokedUtc: ReadNullableDateTimeOffset(reader, 7));
+            Constraints: ApiKeyConstraintSerializer.Deserialize(reader.IsDBNull(5) ? null : reader.GetString(5)),
+            CreatedUtc: DateTimeOffset.Parse(reader.GetString(6), System.Globalization.CultureInfo.InvariantCulture),
+            LastUsedUtc: ReadNullableDateTimeOffset(reader, 7),
+            RevokedUtc: ReadNullableDateTimeOffset(reader, 8));
     }
 
     private static DateTimeOffset? ReadNullableDateTimeOffset(SqliteDataReader reader, int ordinal)

src/MxGateway.Server/Security/Authentication/ApiKeyVerifier.cs

@@ -58,6 +58,7 @@ public sealed class ApiKeyVerifier(
             KeyId: storedKey.KeyId,
             KeyPrefix: storedKey.KeyPrefix,
             DisplayName: storedKey.DisplayName,
-            Scopes: storedKey.Scopes));
+            Scopes: storedKey.Scopes,
+            Constraints: storedKey.Constraints));
     }
 }

src/MxGateway.Server/Security/Authentication/SqliteApiKeyAdminStore.cs

@@ -21,6 +21,7 @@ public sealed class SqliteApiKeyAdminStore(AuthSqliteConnectionFactory connectio
                 secret_hash,
                 display_name,
                 scopes,
+                constraints,
                 created_utc,
                 last_used_utc,
                 revoked_utc)
@@ -30,6 +31,7 @@ public sealed class SqliteApiKeyAdminStore(AuthSqliteConnectionFactory connectio
                 $secret_hash,
                 $display_name,
                 $scopes,
+                $constraints,
                 $created_utc,
                 NULL,
                 NULL);
@@ -47,7 +49,7 @@ public sealed class SqliteApiKeyAdminStore(AuthSqliteConnectionFactory connectio
 
         await using SqliteCommand command = connection.CreateCommand();
         command.CommandText = """
-            SELECT key_id, key_prefix, secret_hash, display_name, scopes, created_utc, last_used_utc, revoked_utc
+            SELECT key_id, key_prefix, secret_hash, display_name, scopes, constraints, created_utc, last_used_utc, revoked_utc
             FROM api_keys
             ORDER BY key_id;
             """;
@@ -118,6 +120,9 @@ public sealed class SqliteApiKeyAdminStore(AuthSqliteConnectionFactory connectio
         command.Parameters.Add("$secret_hash", SqliteType.Blob).Value = request.SecretHash;
         command.Parameters.AddWithValue("$display_name", request.DisplayName);
         command.Parameters.AddWithValue("$scopes", ApiKeyScopeSerializer.Serialize(request.Scopes));
+        command.Parameters.AddWithValue(
+            "$constraints",
+            (object?)ApiKeyConstraintSerializer.Serialize(request.Constraints) ?? DBNull.Value);
         command.Parameters.AddWithValue("$created_utc", request.CreatedUtc.ToString("O"));
     }
 }

src/MxGateway.Server/Security/Authentication/SqliteApiKeyStore.cs

@@ -46,12 +46,12 @@ public sealed class SqliteApiKeyStore(AuthSqliteConnectionFactory connectionFact
         await using SqliteCommand command = connection.CreateCommand();
         command.CommandText = requireActive
             ? """
-              SELECT key_id, key_prefix, secret_hash, display_name, scopes, created_utc, last_used_utc, revoked_utc
+              SELECT key_id, key_prefix, secret_hash, display_name, scopes, constraints, created_utc, last_used_utc, revoked_utc
               FROM api_keys
               WHERE key_id = $key_id AND revoked_utc IS NULL;
               """
             : """
-              SELECT key_id, key_prefix, secret_hash, display_name, scopes, created_utc, last_used_utc, revoked_utc
+              SELECT key_id, key_prefix, secret_hash, display_name, scopes, constraints, created_utc, last_used_utc, revoked_utc
               FROM api_keys
               WHERE key_id = $key_id;
               """;

src/MxGateway.Server/Security/Authentication/SqliteAuthSchema.cs

@@ -2,7 +2,7 @@ namespace MxGateway.Server.Security.Authentication;
 
 public static class SqliteAuthSchema
 {
-    public const int CurrentVersion = 1;
+    public const int CurrentVersion = 2;
 
     public const string SchemaVersionTable = "schema_version";
 

src/MxGateway.Server/Security/Authentication/SqliteAuthStoreMigrator.cs

@@ -24,6 +24,8 @@ public sealed class SqliteAuthStoreMigrator(AuthSqliteConnectionFactory connecti
         }
 
         await ApplyVersionOneAsync(connection, transaction, cancellationToken).ConfigureAwait(false);
+        await ApplyVersionTwoAsync(connection, transaction, cancellationToken).ConfigureAwait(false);
+        await WriteSchemaVersionAsync(connection, transaction, cancellationToken).ConfigureAwait(false);
 
         await transaction.CommitAsync(cancellationToken).ConfigureAwait(false);
     }
@@ -85,6 +87,7 @@ public sealed class SqliteAuthStoreMigrator(AuthSqliteConnectionFactory connecti
                 secret_hash BLOB NOT NULL,
                 display_name TEXT NOT NULL,
                 scopes TEXT NOT NULL,
+                constraints TEXT NULL,
                 created_utc TEXT NOT NULL,
                 last_used_utc TEXT NULL,
                 revoked_utc TEXT NULL
@@ -107,6 +110,34 @@ public sealed class SqliteAuthStoreMigrator(AuthSqliteConnectionFactory connecti
             """,
             cancellationToken).ConfigureAwait(false);
 
+    }
+
+    private static async Task ApplyVersionTwoAsync(
+        SqliteConnection connection,
+        SqliteTransaction transaction,
+        CancellationToken cancellationToken)
+    {
+        if (await ColumnExistsAsync(connection, transaction, SqliteAuthSchema.ApiKeysTable, "constraints", cancellationToken)
+            .ConfigureAwait(false))
+        {
+            return;
+        }
+
+        await ExecuteNonQueryAsync(
+            connection,
+            transaction,
+            """
+            ALTER TABLE api_keys
+            ADD COLUMN constraints TEXT NULL;
+            """,
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    private static async Task WriteSchemaVersionAsync(
+        SqliteConnection connection,
+        SqliteTransaction transaction,
+        CancellationToken cancellationToken)
+    {
         await using SqliteCommand versionCommand = connection.CreateCommand();
         versionCommand.Transaction = transaction;
         versionCommand.CommandText = """
@@ -122,6 +153,31 @@ public sealed class SqliteAuthStoreMigrator(AuthSqliteConnectionFactory connecti
         await versionCommand.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
     }
 
+    private static async Task<bool> ColumnExistsAsync(
+        SqliteConnection connection,
+        SqliteTransaction transaction,
+        string tableName,
+        string columnName,
+        CancellationToken cancellationToken)
+    {
+        await using SqliteCommand command = connection.CreateCommand();
+        command.Transaction = transaction;
+        command.CommandText = $"PRAGMA table_info({tableName});";
+
+        await using SqliteDataReader reader = await command.ExecuteReaderAsync(cancellationToken)
+            .ConfigureAwait(false);
+
+        while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false))
+        {
+            if (string.Equals(reader.GetString(1), columnName, StringComparison.OrdinalIgnoreCase))
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
     private static async Task ExecuteNonQueryAsync(
         SqliteConnection connection,
         SqliteTransaction transaction,