Progmasoft Git

progmaweb

The site and account service of Progmasoft: a Next.js frontend and an ASP.NET Core API.

Clonegit clone https://git.progmasoft.com/progmaweb

Require documentation for every item of the API reference

The DocFX gate only failed on a broken link or an unresolved reference.
DocFX does not report a declaration without a comment, and the API had
none, so the gate passed over a reference with no descriptions at all.

The gate now has three parts:

- DocFX still builds the reference with warnings as errors.
- The API project compiles its XML documentation. With warnings as errors
  already on, an undocumented public declaration or a wrong cref now fails
  the build.
- docs/api/CheckDocumentation.cs reads the metadata DocFX generated and
  fails when a namespace, type or member has no summary. This covers
  internal and private members, which the compiler does not check. It runs
  as a file-based .NET program, so the gate needs no tool beyond the SDK.
  It refuses to pass when the metadata is missing or defines nothing.

To satisfy the gate, every declaration of apps/api has documentation
comments, 131 reference items in all, and the two namespaces are described
by overwrite files in docs/api/namespaces. Only comment lines were added to
the C# sources; no statement changed.

docs/api/filterConfig.yml leaves generator-written code out of the
reference: the generated regular-expression namespace, and the one partial
method whose generated half replaces the comment of its declaration.

Verified locally: the solution builds with no warnings, the 23 API tests
pass, DocFX builds with no warnings and the coverage check passes. Removing
one summary and one namespace file made the check fail and name both.
Commit
b1cf9a3bea0c81c1cb3ed2e0ddce2b9a56e175ef
Author
Leitwolf11 ·
Parents
e9eb2812a47b

Files · Download .tar.gz

Changes

 .github/workflows/backend.yml                      |   7 +-
 apps/api/Accounts/AccountContracts.cs              |  38 +++++++
 apps/api/Accounts/AccountEndpoints.cs              |  67 ++++++++++++
 apps/api/Accounts/AccountNamePolicy.cs             |  19 ++++
 apps/api/Accounts/AccountRecord.cs                 |  18 ++++
 apps/api/Accounts/AccountService.cs                |  53 +++++++++
 apps/api/Accounts/EmailAddressPolicy.cs            |  12 +++
 apps/api/Accounts/IAccountStore.cs                 |  33 ++++++
 apps/api/Accounts/InMemoryAccountStore.cs          |  18 ++++
 apps/api/Accounts/PasswordPolicy.cs                |  11 ++
 apps/api/Accounts/SessionService.cs                |  36 +++++++
 apps/api/Progmaweb.Api.csproj                      |   3 +
 apps/api/Program.cs                                |   5 +
 apps/api/Security/ForwardedHeadersPolicy.cs        |   9 ++
 apps/api/Security/SecurityHeadersMiddleware.cs     |   9 ++
 docs/api/CheckDocumentation.cs                     | 118 +++++++++++++++++++++
 docs/api/docfx.json                                |  22 +++-
 docs/api/filterConfig.yml                          |  14 +++
 docs/api/index.md                                  |  23 +++-
 .../Progmasoft.Progmaweb.Api.Accounts.md           |  10 ++
 .../Progmasoft.Progmaweb.Api.Security.md           |  10 ++
 justfile                                           |   1 +
 22 files changed, 528 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/backend.yml b/.github/workflows/backend.yml
index a1f6320..6504906 100644
--- a/.github/workflows/backend.yml
+++ b/.github/workflows/backend.yml
@@ -47,10 +47,13 @@ jobs:
       - run: dotnet build Progmaweb.slnx --configuration Release --no-restore
       - run: dotnet test --project apps/api-tests/Progmaweb.Api.Tests.csproj --configuration Release --no-build --coverlet --coverlet-output-format cobertura
 
-      # Documentation gate: DocFX reads the API project and builds the
-      # reference; an unresolved reference or a broken link is an error.
+      # Documentation gate. DocFX reads the API project and builds the
+      # reference; an unresolved reference or a broken link is an error. The
+      # coverage check then fails when a namespace, type or member of the
+      # reference has no description, which DocFX itself does not report.
       - run: dotnet tool restore
       - run: dotnet docfx docs/api/docfx.json --warningsAsErrors
+      - run: dotnet run docs/api/CheckDocumentation.cs -- docs/api
 
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
diff --git a/apps/api/Accounts/AccountContracts.cs b/apps/api/Accounts/AccountContracts.cs
index ca7ddb1..4a803a0 100644
--- a/apps/api/Accounts/AccountContracts.cs
+++ b/apps/api/Accounts/AccountContracts.cs
@@ -3,27 +3,65 @@
 
 namespace Progmasoft.Progmaweb.Api.Accounts;
 
+/// <summary>Body of <c>POST /api/v1/accounts/register</c>.</summary>
+/// <remarks>
+/// Every field is optional on the wire so that a missing value is reported as a validation error of that field
+/// instead of a malformed request.
+/// </remarks>
+/// <param name="AccountName">Requested account name; see <see cref="AccountNamePolicy"/>.</param>
+/// <param name="Email">Email address of the account; see <see cref="EmailAddressPolicy"/>.</param>
+/// <param name="Password">Password in plain text; see <see cref="PasswordPolicy"/>. It is hashed before it is stored.</param>
 public sealed record RegisterAccountRequest(string? AccountName, string? Email, string? Password);
 
+/// <summary>Body of <c>POST /api/v1/accounts/login</c>.</summary>
+/// <param name="Email">Email address the account was registered with.</param>
+/// <param name="Password">Password in plain text.</param>
 public sealed record LoginAccountRequest(string? Email, string? Password);
 
+/// <summary>Public view of an account, returned by the register, login and <c>/me</c> endpoints.</summary>
+/// <param name="AccountName">Account name in its canonical spelling.</param>
+/// <param name="Email">Email address as the owner entered it.</param>
+/// <param name="CreatedAt">Moment the account was created, in UTC.</param>
 public sealed record AccountResponse(string AccountName, string Email, DateTimeOffset CreatedAt);
 
+/// <summary>An account together with the session that was just opened for it.</summary>
+/// <param name="Account">The signed-in account.</param>
+/// <param name="SessionToken">
+/// Session token for the cookie. It exists only here and in the browser; the store keeps its digest.
+/// </param>
+/// <param name="ExpiresAt">Moment the session stops being valid, in UTC.</param>
 internal sealed record AuthenticatedAccount(AccountRecord Account, string SessionToken, DateTimeOffset ExpiresAt);
 
+/// <summary>Outcome of asking the store to create an account.</summary>
 internal enum CreateAccountStatus
 {
+    /// <summary>The account was stored.</summary>
     Created,
+    /// <summary>Another account already has this name, compared without case.</summary>
     AccountNameUnavailable,
+    /// <summary>Another account already has this email address, compared without case.</summary>
     EmailUnavailable,
+    /// <summary>Another account is already linked to this Google identity.</summary>
     GoogleSubjectUnavailable
 }
 
+/// <summary>Result of <see cref="IAccountStore.CreateAsync"/>.</summary>
+/// <param name="Status">Whether the account was stored, and if not, which uniqueness rule refused it.</param>
+/// <param name="Account">The stored account; <see langword="null"/> unless <paramref name="Status"/> is created.</param>
 internal sealed record CreateAccountResult(CreateAccountStatus Status, AccountRecord? Account)
 {
+    /// <summary>Creates the result of a stored account.</summary>
+    /// <param name="account">The account that was stored.</param>
+    /// <returns>A result with the created status and the account.</returns>
     public static CreateAccountResult Created(AccountRecord account) => new(CreateAccountStatus.Created, account);
+    /// <summary>Creates the result of a refused account name.</summary>
+    /// <returns>A result without an account.</returns>
     public static CreateAccountResult AccountNameUnavailable() => new(CreateAccountStatus.AccountNameUnavailable, null);
+    /// <summary>Creates the result of a refused email address.</summary>
+    /// <returns>A result without an account.</returns>
     public static CreateAccountResult EmailUnavailable() => new(CreateAccountStatus.EmailUnavailable, null);
+    /// <summary>Creates the result of a refused Google identity.</summary>
+    /// <returns>A result without an account.</returns>
     public static CreateAccountResult GoogleSubjectUnavailable() =>
         new(CreateAccountStatus.GoogleSubjectUnavailable, null);
 }
diff --git a/apps/api/Accounts/AccountEndpoints.cs b/apps/api/Accounts/AccountEndpoints.cs
index 06f4997..c5be51c 100644
--- a/apps/api/Accounts/AccountEndpoints.cs
+++ b/apps/api/Accounts/AccountEndpoints.cs
@@ -7,10 +7,29 @@ using System.Security.Claims;
 using Microsoft.AspNetCore.Authentication;
 using Microsoft.AspNetCore.Authentication.Google;
 
+/// <summary>HTTP endpoints of the account service under <c>/api/v1/accounts</c>.</summary>
+/// <remarks>
+/// <list type="table">
+/// <item><term><c>POST /register</c></term><description>Creates a password account and signs it in.</description></item>
+/// <item><term><c>POST /login</c></term><description>Signs in with email address and password.</description></item>
+/// <item><term><c>POST /logout</c></term><description>Ends the current session.</description></item>
+/// <item><term><c>GET /me</c></term><description>Returns the signed-in account.</description></item>
+/// <item><term><c>GET /oauth/google/start</c></term><description>Begins sign-in with Google.</description></item>
+/// <item><term><c>GET /oauth/google/complete</c></term><description>Finishes sign-in with Google.</description></item>
+/// </list>
+/// The endpoints that accept credentials share the <c>account-auth</c> rate limit.
+/// </remarks>
 internal static class AccountEndpoints
 {
+    /// <summary>
+    /// Authentication scheme of the short-lived cookie that carries the Google identity between the provider callback
+    /// and <c>/oauth/google/complete</c>.
+    /// </summary>
     internal const string ExternalCookieScheme = "ProgmasoftExternal";
 
+    /// <summary>Registers the account endpoints.</summary>
+    /// <param name="endpoints">The route builder of the application.</param>
+    /// <returns>The same route builder, for chaining.</returns>
     public static IEndpointRouteBuilder MapAccountEndpoints(this IEndpointRouteBuilder endpoints)
     {
         RouteGroupBuilder accounts = endpoints.MapGroup("/api/v1/accounts");
@@ -25,6 +44,15 @@ internal static class AccountEndpoints
         return endpoints;
     }
 
+    /// <summary>Begins sign-in with Google.</summary>
+    /// <param name="accountName">
+    /// Account name to create when the Google identity is new; omitted when signing in to an existing account.
+    /// </param>
+    /// <param name="configuration">Application configuration with the Google client credentials.</param>
+    /// <returns>
+    /// A challenge that sends the browser to Google, a redirect back to registration when the name is invalid, or
+    /// 503 when Google sign-in is not configured.
+    /// </returns>
     private static IResult StartGoogleAsync(string? accountName, IConfiguration configuration)
     {
         if (string.IsNullOrWhiteSpace(configuration["Authentication:Google:ClientId"]) ||
@@ -54,6 +82,12 @@ internal static class AccountEndpoints
         return Results.Challenge(properties, [GoogleDefaults.AuthenticationScheme]);
     }
 
+    /// <summary>Finishes sign-in with Google after the provider callback.</summary>
+    /// <param name="accounts">Account service.</param>
+    /// <param name="sessions">Session service.</param>
+    /// <param name="context">The current request, holding the external cookie.</param>
+    /// <param name="cancellationToken">Cancels the operation.</param>
+    /// <returns>A redirect to the dashboard on success, or to the page that explains the failure.</returns>
     private static async Task<IResult> CompleteGoogleAsync(
         AccountService accounts,
         SessionService sessions,
@@ -90,6 +124,13 @@ internal static class AccountEndpoints
         return Results.Redirect($"/{Uri.EscapeDataString(authentication.Account.AccountName)}/dashboard");
     }
 
+    /// <summary>Creates a password account and opens a session for it.</summary>
+    /// <param name="request">The registration body.</param>
+    /// <param name="accounts">Account service.</param>
+    /// <param name="sessions">Session service.</param>
+    /// <param name="context">The current request; receives the session cookie.</param>
+    /// <param name="cancellationToken">Cancels the operation.</param>
+    /// <returns>201 with the account, or a validation problem that names each refused field.</returns>
     private static async Task<IResult> RegisterAsync(
         RegisterAccountRequest request,
         AccountService accounts,
@@ -110,6 +151,15 @@ internal static class AccountEndpoints
             ToResponse(authentication.Account));
     }
 
+    /// <summary>Signs in with email address and password.</summary>
+    /// <param name="request">The login body.</param>
+    /// <param name="accounts">Account service.</param>
+    /// <param name="sessions">Session service.</param>
+    /// <param name="context">The current request; receives the session cookie.</param>
+    /// <param name="cancellationToken">Cancels the operation.</param>
+    /// <returns>
+    /// 200 with the account, or 401 with one message that does not reveal whether the address or the password was wrong.
+    /// </returns>
     private static async Task<IResult> LoginAsync(
         LoginAccountRequest request,
         AccountService accounts,
@@ -130,6 +180,11 @@ internal static class AccountEndpoints
         return Results.Ok(ToResponse(authentication.Account));
     }
 
+    /// <summary>Ends the current session and deletes its cookie.</summary>
+    /// <param name="sessions">Session service.</param>
+    /// <param name="context">The current request.</param>
+    /// <param name="cancellationToken">Cancels the operation.</param>
+    /// <returns>204, also when no session existed.</returns>
     private static async Task<IResult> LogoutAsync(
         SessionService sessions,
         HttpContext context,
@@ -147,6 +202,11 @@ internal static class AccountEndpoints
         return Results.NoContent();
     }
 
+    /// <summary>Returns the account of the current session.</summary>
+    /// <param name="sessions">Session service.</param>
+    /// <param name="context">The current request.</param>
+    /// <param name="cancellationToken">Cancels the operation.</param>
+    /// <returns>200 with the account, or 401 when the request has no valid session.</returns>
     private static async Task<IResult> MeAsync(
         SessionService sessions,
         HttpContext context,
@@ -157,6 +217,10 @@ internal static class AccountEndpoints
         return account is null ? Results.Unauthorized() : Results.Ok(ToResponse(account));
     }
 
+    /// <summary>Writes the session cookie of a new session to the response.</summary>
+    /// <param name="context">The current request.</param>
+    /// <param name="sessions">Session service, which names the cookie.</param>
+    /// <param name="authentication">The session that was opened.</param>
     private static void WriteSessionCookie(
         HttpContext context,
         SessionService sessions,
@@ -166,6 +230,9 @@ internal static class AccountEndpoints
             authentication.SessionToken,
             SessionService.CreateCookieOptions(authentication.ExpiresAt));
 
+    /// <summary>Projects a stored account to its public view.</summary>
+    /// <param name="account">The stored account.</param>
+    /// <returns>The fields a client may see.</returns>
     private static AccountResponse ToResponse(AccountRecord account) =>
         new(account.AccountName, account.Email, account.CreatedAt);
 }
diff --git a/apps/api/Accounts/AccountNamePolicy.cs b/apps/api/Accounts/AccountNamePolicy.cs
index 76e9dcf..3b2328d 100644
--- a/apps/api/Accounts/AccountNamePolicy.cs
+++ b/apps/api/Accounts/AccountNamePolicy.cs
@@ -6,19 +6,35 @@ using System.Text.RegularExpressions;
 
 namespace Progmasoft.Progmaweb.Api.Accounts;
 
+/// <summary>Rules for account names.</summary>
+/// <remarks>
+/// A name is 8 to 128 ASCII letters or digits and begins with an upper-case letter. Names are unique without regard
+/// to case, so two names that differ only in case cannot both exist, while each keeps the spelling its owner chose.
+/// The same name is the ViGet publisher name.
+/// </remarks>
 internal static partial class AccountNamePolicy
 {
+    /// <summary>Fewest characters an account name may have.</summary>
     public const int MinimumLength = 8;
+    /// <summary>Most characters an account name may have.</summary>
     public const int MaximumLength = 128;
 
+    /// <summary>Names nobody may register, in their lookup form.</summary>
     // These names identify Progmasoft itself and the initial administrative identity. They are provisioned only by
     // trusted operations tooling, never by the public registration endpoint.
     private static readonly FrozenSet<string> ReservedNames =
         new[] { "LEITWOLF", "PROGMASOFT" }.ToFrozenSet(StringComparer.Ordinal);
 
+    /// <summary>Matches a name of the allowed length, alphabet and first letter.</summary>
+    /// <returns>The compiled expression.</returns>
     [GeneratedRegex("^[A-Z][A-Za-z0-9]{7,127}$", RegexOptions.CultureInvariant)]
     private static partial Regex CanonicalPattern();
 
+    /// <summary>Validates an account name and returns its canonical spelling.</summary>
+    /// <param name="value">The name as entered; surrounding white space is ignored.</param>
+    /// <param name="canonical">The trimmed name. It is meaningful only when the method returns <see langword="true"/>.</param>
+    /// <param name="error">Message for the user when the name is refused; empty otherwise.</param>
+    /// <returns><see langword="true"/> when the name satisfies every rule and is not reserved.</returns>
     public static bool TryNormalize(string? value, out string canonical, out string error)
     {
         canonical = value?.Trim() ?? string.Empty;
@@ -45,5 +61,8 @@ internal static partial class AccountNamePolicy
         return true;
     }
 
+    /// <summary>Returns the key under which a name is compared for uniqueness.</summary>
+    /// <param name="canonical">A name that <see cref="TryNormalize"/> accepted.</param>
+    /// <returns>The name in upper case.</returns>
     public static string NormalizeForLookup(string canonical) => canonical.ToUpperInvariant();
 }
diff --git a/apps/api/Accounts/AccountRecord.cs b/apps/api/Accounts/AccountRecord.cs
index 7625168..5e27f3e 100644
--- a/apps/api/Accounts/AccountRecord.cs
+++ b/apps/api/Accounts/AccountRecord.cs
@@ -3,6 +3,19 @@
 
 namespace Progmasoft.Progmaweb.Api.Accounts;
 
+/// <summary>An account as the store keeps it.</summary>
+/// <param name="Id">Stable identifier; sessions refer to the account by it.</param>
+/// <param name="AccountName">Account name in its canonical spelling, as shown and used in URLs.</param>
+/// <param name="NormalizedAccountName">Upper-case form of the name; the uniqueness key.</param>
+/// <param name="Email">Email address as the owner entered it.</param>
+/// <param name="NormalizedEmail">Upper-case form of the address; the uniqueness key.</param>
+/// <param name="GoogleSubject">
+/// Subject identifier of the linked Google identity; <see langword="null"/> for a password account.
+/// </param>
+/// <param name="PasswordHash">
+/// ASP.NET Core Identity password hash; <see langword="null"/> for an account that signs in through Google only.
+/// </param>
+/// <param name="CreatedAt">Moment the account was created, in UTC.</param>
 internal sealed record AccountRecord(
     Guid Id,
     string AccountName,
@@ -13,6 +26,11 @@ internal sealed record AccountRecord(
     string? PasswordHash,
     DateTimeOffset CreatedAt);
 
+/// <summary>A session as the store keeps it.</summary>
+/// <param name="TokenDigest">SHA-256 digest of the session token. The token itself is never stored.</param>
+/// <param name="AccountId">Identifier of the account the session belongs to.</param>
+/// <param name="CreatedAt">Moment the session was opened, in UTC.</param>
+/// <param name="ExpiresAt">Moment the session stops being valid, in UTC.</param>
 internal sealed record SessionRecord(
     byte[] TokenDigest,
     Guid AccountId,
diff --git a/apps/api/Accounts/AccountService.cs b/apps/api/Accounts/AccountService.cs
index 7168eb6..cd3e711 100644
--- a/apps/api/Accounts/AccountService.cs
+++ b/apps/api/Accounts/AccountService.cs
@@ -5,10 +5,14 @@ using Microsoft.AspNetCore.Identity;
 
 namespace Progmasoft.Progmaweb.Api.Accounts;
 
+/// <summary>Registration and sign-in rules of the account service.</summary>
+/// <param name="store">Store that keeps accounts.</param>
+/// <param name="timeProvider">Clock used for creation times.</param>
 internal sealed class AccountService(
     IAccountStore store,
     TimeProvider timeProvider)
 {
+    /// <summary>An account that never exists; the subject of the dummy verification.</summary>
     private static readonly AccountRecord DummyAccount = new(
         Guid.Empty,
         "Missing00",
@@ -18,11 +22,24 @@ internal sealed class AccountService(
         null,
         string.Empty,
         DateTimeOffset.UnixEpoch);
+    /// <summary>
+    /// A hash that no submitted password matches. Verifying against it makes a sign-in with an unknown address cost
+    /// as much as one with a wrong password.
+    /// </summary>
     private static readonly string DummyPasswordHash =
         new PasswordHasher<AccountRecord>().HashPassword(DummyAccount, "not-the-provided-password");
 
+    /// <summary>Hashes and verifies passwords with the ASP.NET Core Identity algorithm.</summary>
     private readonly PasswordHasher<AccountRecord> passwordHasher = new();
 
+    /// <summary>Creates a password account and opens a session for it.</summary>
+    /// <param name="request">The registration body.</param>
+    /// <param name="sessions">Session service.</param>
+    /// <param name="cancellationToken">Cancels the operation.</param>
+    /// <returns>
+    /// The signed-in account and no errors, or no account and the messages of each refused field, keyed by
+    /// <c>accountName</c>, <c>email</c> and <c>password</c>.
+    /// </returns>
     public async ValueTask<(AuthenticatedAccount? Authentication, Dictionary<string, string[]> Errors)> RegisterAsync(
         RegisterAccountRequest request,
         SessionService sessions,
@@ -63,6 +80,15 @@ internal sealed class AccountService(
         return (authentication, errors);
     }
 
+    /// <summary>Signs in with email address and password.</summary>
+    /// <remarks>
+    /// An unknown address costs one password verification against a private dummy hash, so the response time does not
+    /// reveal whether an address is registered.
+    /// </remarks>
+    /// <param name="request">The login body.</param>
+    /// <param name="sessions">Session service.</param>
+    /// <param name="cancellationToken">Cancels the operation.</param>
+    /// <returns>The signed-in account, or <see langword="null"/> when the credentials are refused.</returns>
     public async ValueTask<AuthenticatedAccount?> LoginAsync(
         LoginAccountRequest request,
         SessionService sessions,
@@ -92,6 +118,18 @@ internal sealed class AccountService(
         return await sessions.CreateAsync(account, cancellationToken);
     }
 
+    /// <summary>Signs in with a Google identity, creating the account on first use.</summary>
+    /// <remarks>
+    /// An identity that is already linked signs in to its account. A new identity creates an account under the
+    /// requested name. A new identity whose email address belongs to an existing account is refused: password
+    /// registrations do not verify the address, so linking by address could hand an account to someone else.
+    /// </remarks>
+    /// <param name="providerSubject">Subject identifier Google issued for the identity.</param>
+    /// <param name="providerEmail">Email address Google reported for the identity.</param>
+    /// <param name="requestedAccountName">Account name to create for a new identity; may be <see langword="null"/>.</param>
+    /// <param name="sessions">Session service.</param>
+    /// <param name="cancellationToken">Cancels the operation.</param>
+    /// <returns>The signed-in account, or no account and the reason.</returns>
     public async ValueTask<(AuthenticatedAccount? Authentication, GoogleAccountFailure Failure)>
         AuthenticateGoogleAsync(
             string? providerSubject,
@@ -165,6 +203,12 @@ internal sealed class AccountService(
         return (await sessions.CreateAsync(account, cancellationToken), GoogleAccountFailure.None);
     }
 
+    /// <summary>Validates every field of a registration and collects the messages of the refused ones.</summary>
+    /// <param name="request">The registration body.</param>
+    /// <param name="accountName">The canonical account name.</param>
+    /// <param name="email">The email address as entered, trimmed.</param>
+    /// <param name="normalizedEmail">The email address in its lookup form.</param>
+    /// <returns>Messages keyed by field name; empty when the registration is valid.</returns>
     private static Dictionary<string, string[]> ValidateRegistration(
         RegisterAccountRequest request,
         out string accountName,
@@ -192,11 +236,20 @@ internal sealed class AccountService(
     }
 }
 
+/// <summary>Reason a sign-in with Google did not produce a session.</summary>
 internal enum GoogleAccountFailure
 {
+    /// <summary>The sign-in succeeded.</summary>
     None,
+    /// <summary>
+    /// The identity cannot be used: Google reported no usable subject or address, or the address belongs to another
+    /// account.
+    /// </summary>
     ProviderRejected,
+    /// <summary>The identity is new and no account name was supplied.</summary>
     AccountNameRequired,
+    /// <summary>The supplied account name breaks <see cref="AccountNamePolicy"/>.</summary>
     InvalidAccountName,
+    /// <summary>The supplied account name is taken.</summary>
     AccountNameUnavailable
 }
diff --git a/apps/api/Accounts/EmailAddressPolicy.cs b/apps/api/Accounts/EmailAddressPolicy.cs
index 9710b0c..898d07c 100644
--- a/apps/api/Accounts/EmailAddressPolicy.cs
+++ b/apps/api/Accounts/EmailAddressPolicy.cs
@@ -5,10 +5,22 @@ using System.Net.Mail;
 
 namespace Progmasoft.Progmaweb.Api.Accounts;
 
+/// <summary>Rules for email addresses.</summary>
+/// <remarks>
+/// An address is accepted when it parses as a single mailbox without a display name and is at most 254 characters
+/// long. Ownership of the address is not verified.
+/// </remarks>
 internal static class EmailAddressPolicy
 {
+    /// <summary>Most characters an email address may have.</summary>
     public const int MaximumLength = 254;
 
+    /// <summary>Validates an email address and returns its stored and lookup forms.</summary>
+    /// <param name="value">The address as entered; surrounding white space is ignored.</param>
+    /// <param name="canonical">The trimmed address, kept as the owner wrote it.</param>
+    /// <param name="normalized">The address in upper case; the uniqueness key. Empty when the address is refused.</param>
+    /// <param name="error">Message for the user when the address is refused; empty otherwise.</param>
+    /// <returns><see langword="true"/> when the address is a single valid mailbox.</returns>
     public static bool TryNormalize(string? value, out string canonical, out string normalized, out string error)
     {
         canonical = value?.Trim() ?? string.Empty;
diff --git a/apps/api/Accounts/IAccountStore.cs b/apps/api/Accounts/IAccountStore.cs
index 6bb2955..cef8bee 100644
--- a/apps/api/Accounts/IAccountStore.cs
+++ b/apps/api/Accounts/IAccountStore.cs
@@ -3,14 +3,47 @@
 
 namespace Progmasoft.Progmaweb.Api.Accounts;
 
+/// <summary>Persistence of accounts and sessions.</summary>
+/// <remarks>
+/// The store owns the uniqueness rules: account name, email address and Google identity are each unique, and a
+/// creation that would break one of them is refused atomically. It offers no enumeration and no bulk deletion.
+/// </remarks>
 internal interface IAccountStore
 {
+    /// <summary>Stores a new account unless its name, email address or Google identity is taken.</summary>
+    /// <param name="account">The account to store, with its normalized keys filled in.</param>
+    /// <param name="cancellationToken">Cancels the operation.</param>
+    /// <returns>The stored account, or the uniqueness rule that refused it.</returns>
     ValueTask<CreateAccountResult> CreateAsync(AccountRecord account, CancellationToken cancellationToken);
+    /// <summary>Finds an account by its normalized email address.</summary>
+    /// <param name="normalizedEmail">Upper-case email address, as <see cref="EmailAddressPolicy"/> produces it.</param>
+    /// <param name="cancellationToken">Cancels the operation.</param>
+    /// <returns>The account, or <see langword="null"/> when no account has this address.</returns>
     ValueTask<AccountRecord?> FindByEmailAsync(string normalizedEmail, CancellationToken cancellationToken);
+    /// <summary>Finds the account linked to a Google identity.</summary>
+    /// <param name="googleSubject">Subject identifier Google issued for the identity.</param>
+    /// <param name="cancellationToken">Cancels the operation.</param>
+    /// <returns>The account, or <see langword="null"/> when the identity is not linked.</returns>
     ValueTask<AccountRecord?> FindByGoogleSubjectAsync(string googleSubject, CancellationToken cancellationToken);
+    /// <summary>Finds an account by its identifier.</summary>
+    /// <param name="id">Identifier of the account.</param>
+    /// <param name="cancellationToken">Cancels the operation.</param>
+    /// <returns>The account, or <see langword="null"/> when it does not exist.</returns>
     ValueTask<AccountRecord?> FindByIdAsync(Guid id, CancellationToken cancellationToken);
+    /// <summary>Stores a session, replacing one with the same token digest.</summary>
+    /// <param name="session">The session to store.</param>
+    /// <param name="cancellationToken">Cancels the operation.</param>
+    /// <returns>A task that completes when the session is stored.</returns>
     ValueTask StoreSessionAsync(SessionRecord session, CancellationToken cancellationToken);
+    /// <summary>Finds a session by the digest of its token.</summary>
+    /// <param name="tokenDigest">SHA-256 digest of the session token.</param>
+    /// <param name="cancellationToken">Cancels the operation.</param>
+    /// <returns>The session, or <see langword="null"/> when it does not exist or was revoked.</returns>
     ValueTask<SessionRecord?> FindSessionAsync(byte[] tokenDigest, CancellationToken cancellationToken);
+    /// <summary>Removes a session. Revoking an unknown session is not an error.</summary>
+    /// <param name="tokenDigest">SHA-256 digest of the session token.</param>
+    /// <param name="cancellationToken">Cancels the operation.</param>
+    /// <returns>A task that completes when the session is gone.</returns>
     ValueTask RevokeSessionAsync(byte[] tokenDigest, CancellationToken cancellationToken);
 }
 
diff --git a/apps/api/Accounts/InMemoryAccountStore.cs b/apps/api/Accounts/InMemoryAccountStore.cs
index 9f183e7..7a6930f 100644
--- a/apps/api/Accounts/InMemoryAccountStore.cs
+++ b/apps/api/Accounts/InMemoryAccountStore.cs
@@ -5,15 +5,27 @@ namespace Progmasoft.Progmaweb.Api.Accounts;
 
 // This development store models the uniqueness and session semantics required by the future PostgreSQL implementation.
 // It deliberately exposes no enumeration or bulk-delete surface to public endpoints.
+/// <summary>An <see cref="IAccountStore"/> that keeps everything in the memory of the process.</summary>
+/// <remarks>
+/// It implements the uniqueness and session rules a durable store must keep, under one lock. Nothing survives a
+/// restart of the service: every account and every session is lost when the process stops.
+/// </remarks>
 internal sealed class InMemoryAccountStore : IAccountStore
 {
+    /// <summary>Guards every dictionary below; each operation holds it for its whole duration.</summary>
     private readonly Lock gate = new();
+    /// <summary>Every account, by identifier.</summary>
     private readonly Dictionary<Guid, AccountRecord> accountsById = [];
+    /// <summary>Account identifiers by normalized email address; the uniqueness index of addresses.</summary>
     private readonly Dictionary<string, Guid> accountIdsByEmail = new(StringComparer.Ordinal);
+    /// <summary>Account identifiers by Google subject; the uniqueness index of linked identities.</summary>
     private readonly Dictionary<string, Guid> accountIdsByGoogleSubject = new(StringComparer.Ordinal);
+    /// <summary>Account identifiers by normalized account name; the uniqueness index of names.</summary>
     private readonly Dictionary<string, Guid> accountIdsByName = new(StringComparer.Ordinal);
+    /// <summary>Sessions by the hexadecimal form of their token digest.</summary>
     private readonly Dictionary<string, SessionRecord> sessionsByDigest = new(StringComparer.Ordinal);
 
+    /// <inheritdoc/>
     public ValueTask<CreateAccountResult> CreateAsync(AccountRecord account, CancellationToken cancellationToken)
     {
         cancellationToken.ThrowIfCancellationRequested();
@@ -46,6 +58,7 @@ internal sealed class InMemoryAccountStore : IAccountStore
         }
     }
 
+    /// <inheritdoc/>
     public ValueTask<AccountRecord?> FindByGoogleSubjectAsync(
         string googleSubject,
         CancellationToken cancellationToken)
@@ -58,6 +71,7 @@ internal sealed class InMemoryAccountStore : IAccountStore
         }
     }
 
+    /// <inheritdoc/>
     public ValueTask<AccountRecord?> FindByEmailAsync(string normalizedEmail, CancellationToken cancellationToken)
     {
         cancellationToken.ThrowIfCancellationRequested();
@@ -68,6 +82,7 @@ internal sealed class InMemoryAccountStore : IAccountStore
         }
     }
 
+    /// <inheritdoc/>
     public ValueTask<AccountRecord?> FindByIdAsync(Guid id, CancellationToken cancellationToken)
     {
         cancellationToken.ThrowIfCancellationRequested();
@@ -78,6 +93,7 @@ internal sealed class InMemoryAccountStore : IAccountStore
         }
     }
 
+    /// <inheritdoc/>
     public ValueTask StoreSessionAsync(SessionRecord session, CancellationToken cancellationToken)
     {
         cancellationToken.ThrowIfCancellationRequested();
@@ -88,6 +104,7 @@ internal sealed class InMemoryAccountStore : IAccountStore
         }
     }
 
+    /// <inheritdoc/>
     public ValueTask<SessionRecord?> FindSessionAsync(byte[] tokenDigest, CancellationToken cancellationToken)
     {
         cancellationToken.ThrowIfCancellationRequested();
@@ -98,6 +115,7 @@ internal sealed class InMemoryAccountStore : IAccountStore
         }
     }
 
+    /// <inheritdoc/>
     public ValueTask RevokeSessionAsync(byte[] tokenDigest, CancellationToken cancellationToken)
     {
         cancellationToken.ThrowIfCancellationRequested();
diff --git a/apps/api/Accounts/PasswordPolicy.cs b/apps/api/Accounts/PasswordPolicy.cs
index baf8c75..6a5bf38 100644
--- a/apps/api/Accounts/PasswordPolicy.cs
+++ b/apps/api/Accounts/PasswordPolicy.cs
@@ -3,11 +3,22 @@
 
 namespace Progmasoft.Progmaweb.Api.Accounts;
 
+/// <summary>Rules for passwords.</summary>
+/// <remarks>
+/// Only length is constrained, so long passphrases are welcome. The upper bound keeps hashing cost bounded for a
+/// request that an anonymous caller can send.
+/// </remarks>
 internal static class PasswordPolicy
 {
+    /// <summary>Fewest characters a password may have.</summary>
     public const int MinimumLength = 12;
+    /// <summary>Most characters a password may have.</summary>
     public const int MaximumLength = 256;
 
+    /// <summary>Validates a new password.</summary>
+    /// <param name="password">The password in plain text.</param>
+    /// <param name="error">Message for the user when the password is refused; empty otherwise.</param>
+    /// <returns><see langword="true"/> when the password may be used.</returns>
     public static bool TryValidate(string? password, out string error)
     {
         if (password is null || password.Length < MinimumLength)
diff --git a/apps/api/Accounts/SessionService.cs b/apps/api/Accounts/SessionService.cs
index c96be11..d6d04b0 100644
--- a/apps/api/Accounts/SessionService.cs
+++ b/apps/api/Accounts/SessionService.cs
@@ -6,20 +6,37 @@ using Microsoft.Extensions.Options;
 
 namespace Progmasoft.Progmaweb.Api.Accounts;
 
+/// <summary>Settings of account sessions, bound from the <c>AccountSessions</c> configuration section.</summary>
 internal sealed class AccountSessionOptions
 {
+    /// <summary>Name of the configuration section.</summary>
     public const string SectionName = "AccountSessions";
+    /// <summary>Hours a session stays valid. Values outside 1 to 168 are clamped to that range.</summary>
     public int LifetimeHours { get; init; } = 12;
+    /// <summary>Name of the session cookie. The <c>__Host-</c> prefix binds it to this host over HTTPS.</summary>
     public string CookieName { get; init; } = "__Host-ProgmasoftSession";
 }
 
+/// <summary>Opens, checks and revokes account sessions.</summary>
+/// <remarks>
+/// A session is a random 256-bit token that only the browser holds. The store keeps its SHA-256 digest, so a copy
+/// of the store does not reveal a usable token.
+/// </remarks>
+/// <param name="store">Store that keeps the session digests.</param>
+/// <param name="timeProvider">Clock used for creation and expiry.</param>
+/// <param name="options">Session settings.</param>
 internal sealed class SessionService(
     IAccountStore store,
     TimeProvider timeProvider,
     IOptions<AccountSessionOptions> options)
 {
+    /// <summary>The session settings in effect.</summary>
     private readonly AccountSessionOptions settings = options.Value;
 
+    /// <summary>Opens a session for an account.</summary>
+    /// <param name="account">The account that signed in.</param>
+    /// <param name="cancellationToken">Cancels the operation.</param>
+    /// <returns>The account with the new session token and its expiry.</returns>
     public async ValueTask<AuthenticatedAccount> CreateAsync(AccountRecord account, CancellationToken cancellationToken)
     {
         byte[] tokenBytes = RandomNumberGenerator.GetBytes(32);
@@ -35,6 +52,13 @@ internal sealed class SessionService(
         return new AuthenticatedAccount(account, token, expiresAt);
     }
 
+    /// <summary>Resolves a session token to its account.</summary>
+    /// <param name="token">The token from the session cookie.</param>
+    /// <param name="cancellationToken">Cancels the operation.</param>
+    /// <returns>
+    /// The account, or <see langword="null"/> when the token is malformed, unknown or expired. An expired session is
+    /// revoked on the way.
+    /// </returns>
     public async ValueTask<AccountRecord?> AuthenticateAsync(string? token, CancellationToken cancellationToken)
     {
         if (!TryDigest(token, out byte[] digest))
@@ -57,6 +81,10 @@ internal sealed class SessionService(
         return await store.FindByIdAsync(session.AccountId, cancellationToken);
     }
 
+    /// <summary>Ends the session of a token. A malformed or unknown token is ignored.</summary>
+    /// <param name="token">The token from the session cookie.</param>
+    /// <param name="cancellationToken">Cancels the operation.</param>
+    /// <returns>A task that completes when the session is gone.</returns>
     public async ValueTask RevokeAsync(string? token, CancellationToken cancellationToken)
     {
         if (TryDigest(token, out byte[] digest))
@@ -65,6 +93,9 @@ internal sealed class SessionService(
         }
     }
 
+    /// <summary>Creates the attributes of the session cookie.</summary>
+    /// <param name="expiresAt">Moment the session expires; the cookie expires with it.</param>
+    /// <returns>Options for a secure, HTTP-only, same-site cookie on the root path.</returns>
     public static CookieOptions CreateCookieOptions(DateTimeOffset expiresAt) => new()
     {
         Expires = expiresAt,
@@ -75,8 +106,13 @@ internal sealed class SessionService(
         Secure = true
     };
 
+    /// <summary>Name of the session cookie.</summary>
     public string CookieName => settings.CookieName;
 
+    /// <summary>Computes the digest of a token that has the shape of a session token.</summary>
+    /// <param name="token">The candidate token.</param>
+    /// <param name="digest">The SHA-256 digest; empty when the token is refused.</param>
+    /// <returns><see langword="true"/> when the token has a plausible length and alphabet.</returns>
     private static bool TryDigest(string? token, out byte[] digest)
     {
         digest = [];
diff --git a/apps/api/Progmaweb.Api.csproj b/apps/api/Progmaweb.Api.csproj
index c633ca7..926e696 100644
--- a/apps/api/Progmaweb.Api.csproj
+++ b/apps/api/Progmaweb.Api.csproj
@@ -7,6 +7,9 @@
     <RootNamespace>Progmasoft.Progmaweb.Api</RootNamespace>
     <AssemblyName>Progmaweb.Api</AssemblyName>
     <Version>1.0.0</Version>
+    <!-- The XML documentation is compiled so that a broken reference or an undocumented public
+         declaration fails the build; DocFX publishes the same comments. -->
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
   </PropertyGroup>
   <ItemGroup>
     <PackageReference Include="Microsoft.AspNetCore.Authentication.Google" Version="10.0.11" />
diff --git a/apps/api/Program.cs b/apps/api/Program.cs
index 0b71d06..5f6a7a5 100644
--- a/apps/api/Program.cs
+++ b/apps/api/Program.cs
@@ -82,4 +82,9 @@ app.MapAccountEndpoints();
 
 app.Run();
 
+/// <summary>Entry point of the Progmaweb account API.</summary>
+/// <remarks>
+/// The top-level statements configure the services, the request pipeline and the routes. The class is declared so
+/// that the integration tests can start the application in memory.
+/// </remarks>
 public partial class Program;
diff --git a/apps/api/Security/ForwardedHeadersPolicy.cs b/apps/api/Security/ForwardedHeadersPolicy.cs
index 046ad56..776c1e4 100644
--- a/apps/api/Security/ForwardedHeadersPolicy.cs
+++ b/apps/api/Security/ForwardedHeadersPolicy.cs
@@ -6,11 +6,20 @@ using Microsoft.AspNetCore.HttpOverrides;
 
 namespace Progmasoft.Progmaweb.Api.Security;
 
+/// <summary>Decides which forwarded headers the API trusts.</summary>
+/// <remarks>
+/// The API listens on loopback behind Nginx and the Next.js server. Only those local proxies may state the client
+/// address, host and scheme; the authentication rate limiter depends on the client address being genuine.
+/// </remarks>
 internal static class ForwardedHeadersPolicy
 {
+    /// <summary>Number of proxy hops whose headers are read.</summary>
     internal const int MaximumForwardedHops = 1;
+    /// <summary>Addresses of the proxies that may send forwarded headers.</summary>
     internal static readonly IPAddress[] TrustedProxies = [IPAddress.Loopback, IPAddress.IPv6Loopback];
 
+    /// <summary>Applies the policy to the forwarded-headers middleware.</summary>
+    /// <param name="options">Options to configure.</param>
     public static void Configure(ForwardedHeadersOptions options)
     {
         options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedHost |
diff --git a/apps/api/Security/SecurityHeadersMiddleware.cs b/apps/api/Security/SecurityHeadersMiddleware.cs
index 42383ef..d17a3fe 100644
--- a/apps/api/Security/SecurityHeadersMiddleware.cs
+++ b/apps/api/Security/SecurityHeadersMiddleware.cs
@@ -3,8 +3,17 @@
 
 namespace Progmasoft.Progmaweb.Api.Security;
 
+/// <summary>Adds the security headers of a JSON API to every response.</summary>
+/// <remarks>
+/// The API serves no documents, so its content security policy allows nothing, it may not be framed, and its
+/// responses are never cached.
+/// </remarks>
+/// <param name="next">The next middleware in the pipeline.</param>
 internal sealed class SecurityHeadersMiddleware(RequestDelegate next)
 {
+    /// <summary>Sets the headers and continues the pipeline.</summary>
+    /// <param name="context">The current request.</param>
+    /// <returns>A task that completes when the rest of the pipeline has run.</returns>
     public async Task InvokeAsync(HttpContext context)
     {
         IHeaderDictionary headers = context.Response.Headers;
diff --git a/docs/api/CheckDocumentation.cs b/docs/api/CheckDocumentation.cs
new file mode 100644
index 0000000..f359661
--- /dev/null
+++ b/docs/api/CheckDocumentation.cs
@@ -0,0 +1,118 @@
+// SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1
+
+// Documentation coverage gate of the API reference.
+//
+// DocFX builds a reference from whatever comments exist and does not report a declaration that has none. This
+// program reads the metadata DocFX generated and fails when a namespace, type or member is undocumented, so the
+// reference cannot contain an entry without a description.
+//
+// Usage, after `dotnet docfx metadata docs/api/docfx.json`:
+//
+//     dotnet run docs/api/CheckDocumentation.cs -- docs/api
+//
+// The exit code is 0 when everything is documented, 1 when something is not, and 2 when the metadata is missing.
+
+using System.Text.RegularExpressions;
+
+string root = args.Length > 0 ? args[0] : "docs/api";
+string referenceDirectory = Path.Combine(root, "reference");
+string namespaceDirectory = Path.Combine(root, "namespaces");
+
+if (!Directory.Exists(referenceDirectory))
+{
+    Console.Error.WriteLine($"No metadata in '{referenceDirectory}'. Run 'dotnet docfx metadata' first.");
+    return 2;
+}
+
+// A namespace has no declaration that could carry a comment. Its description is an overwrite file named after it.
+HashSet<string> describedNamespaces = Directory.Exists(namespaceDirectory)
+    ? Directory.EnumerateFiles(namespaceDirectory, "*.md")
+        .Where(HasDescription)
+        .Select(path => Path.GetFileNameWithoutExtension(path)!)
+        .ToHashSet(StringComparer.Ordinal)
+    : [];
+
+List<string> undocumented = [];
+int checkedItems = 0;
+
+foreach (string file in Directory.EnumerateFiles(referenceDirectory, "*.yml").Order(StringComparer.Ordinal))
+{
+    if (Path.GetFileName(file) == "toc.yml")
+    {
+        continue;
+    }
+
+    // The items a file defines come first; the `references` section after them repeats names of other files.
+    string text = File.ReadAllText(file).ReplaceLineEndings("\n");
+    int references = text.IndexOf("\nreferences:", StringComparison.Ordinal);
+    string definitions = references < 0 ? text : text[..references];
+
+    foreach (string item in ItemStart().Split(definitions).Skip(1))
+    {
+        string uid = item[..item.IndexOf('\n')].Trim();
+        string type = ItemType().Match(item) is { Success: true } match ? match.Groups[1].Value : "Item";
+        checkedItems++;
+
+        bool documented = type == "Namespace"
+            ? describedNamespaces.Contains(uid)
+            : ItemSummary().IsMatch(item);
+        if (!documented)
+        {
+            undocumented.Add($"{type} {uid}");
+        }
+    }
+}
+
+if (checkedItems == 0)
+{
+    Console.Error.WriteLine($"The metadata in '{referenceDirectory}' defines nothing; the gate would pass vacuously.");
+    return 2;
+}
+
+if (undocumented.Count != 0)
+{
+    Console.Error.WriteLine($"{undocumented.Count} of {checkedItems} API items have no documentation:");
+    foreach (string entry in undocumented)
+    {
+        Console.Error.WriteLine($"  {entry}");
+    }
+
+    Console.Error.WriteLine("Add a <summary> to each declaration, or a file in docs/api/namespaces for a namespace.");
+    return 1;
+}
+
+Console.WriteLine($"All {checkedItems} API items are documented.");
+return 0;
+
+// An overwrite file describes its namespace when it has text after its front matter and comment header.
+static bool HasDescription(string path)
+{
+    string text = File.ReadAllText(path).ReplaceLineEndings("\n");
+    int frontMatterEnd = text.IndexOf("\n---", 3, StringComparison.Ordinal);
+    if (!text.StartsWith("---\n", StringComparison.Ordinal) || frontMatterEnd < 0)
+    {
+        return false;
+    }
+
+    string body = HtmlComment().Replace(text[(frontMatterEnd + 4)..], string.Empty);
+    return text[..frontMatterEnd].Contains($"uid: {Path.GetFileNameWithoutExtension(path)}", StringComparison.Ordinal)
+        && !string.IsNullOrWhiteSpace(body);
+}
+
+internal static partial class Program
+{
+    // Every defined item starts with its identifier at the left margin.
+    [GeneratedRegex(@"^- uid: ", RegexOptions.Multiline)]
+    private static partial Regex ItemStart();
+
+    [GeneratedRegex(@"^  type: (\w+)", RegexOptions.Multiline)]
+    private static partial Regex ItemType();
+
+    // A summary with content: text on the same line, or a block scalar followed by an indented line.
+    [GeneratedRegex(@"^  summary: (?:[^\s>|].*|[>|][-+]?\n    \S)", RegexOptions.Multiline)]
+    private static partial Regex ItemSummary();
+
+    [GeneratedRegex(@"<!--.*?-->", RegexOptions.Singleline)]
+    private static partial Regex HtmlComment();
+}
diff --git a/docs/api/docfx.json b/docs/api/docfx.json
index e10a9b0..eb2ffe7 100644
--- a/docs/api/docfx.json
+++ b/docs/api/docfx.json
@@ -4,23 +4,37 @@
       "src": [
         {
           "src": "../../apps/api",
-          "files": ["Progmaweb.Api.csproj"]
+          "files": [
+            "Progmaweb.Api.csproj"
+          ]
         }
       ],
       "dest": "reference",
-      "includePrivateMembers": true
+      "includePrivateMembers": true,
+      "filter": "filterConfig.yml"
     }
   ],
   "build": {
     "content": [
       {
-        "files": ["index.md", "toc.yml", "reference/**/*.yml"]
+        "files": [
+          "index.md",
+          "toc.yml",
+          "reference/**/*.yml"
+        ]
       }
     ],
     "dest": "_site",
     "globalMetadata": {
       "_appTitle": "Progmaweb API",
       "_enableSearch": false
-    }
+    },
+    "overwrite": [
+      {
+        "files": [
+          "namespaces/*.md"
+        ]
+      }
+    ]
   }
 }
diff --git a/docs/api/filterConfig.yml b/docs/api/filterConfig.yml
new file mode 100644
index 0000000..5b7b327
--- /dev/null
+++ b/docs/api/filterConfig.yml
@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1
+
+# Code that a source generator writes at build time is not part of the
+# reference: nobody maintains it, and it cannot carry documentation.
+apiRules:
+  - exclude:
+      uidRegex: ^System\.Text\.RegularExpressions\.Generated
+  # The regular-expression generator also writes the body of this partial
+  # method, and its generated comment replaces the one on the declaration, so
+  # the summary in the source never reaches the reference.
+  - exclude:
+      uidRegex: ^Progmasoft\.Progmaweb\.Api\.Accounts\.AccountNamePolicy\.CanonicalPattern$
+      type: Method
diff --git a/docs/api/index.md b/docs/api/index.md
index 868fff1..71b532b 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -12,8 +12,27 @@ The service is an application, not a library, so most of its types are
 internal. The reference includes them: it documents the code for the people
 who maintain it.
 
-Build it from the repository root:
+Build and check it from the repository root:
 
 ```sh
-docfx docs/api/docfx.json --warningsAsErrors
+dotnet tool restore
+dotnet docfx docs/api/docfx.json --warningsAsErrors
+dotnet run docs/api/CheckDocumentation.cs -- docs/api
 ```
+
+## What the gate requires
+
+Three things fail the check, locally and in CI:
+
+- **A broken link or an unresolved reference.** DocFX runs with every warning treated as an error.
+- **An undocumented public declaration or a wrong `cref`.** The API project compiles its XML documentation, and the
+  build treats the compiler's documentation warnings as errors.
+- **Any undocumented item of the reference.** `CheckDocumentation.cs` reads the metadata DocFX generated and fails
+  when a namespace, type or member has no summary. This covers internal and private members too, which the compiler
+  does not check.
+
+A namespace has no declaration that could hold a comment. Its description is a file in `namespaces/`, named after
+the namespace.
+
+`filterConfig.yml` lists what is left out of the reference: code written by a source generator, which nobody
+maintains and which cannot carry documentation. Do not add an entry there to get past the gate; write the summary.
diff --git a/docs/api/namespaces/Progmasoft.Progmaweb.Api.Accounts.md b/docs/api/namespaces/Progmasoft.Progmaweb.Api.Accounts.md
new file mode 100644
index 0000000..926cd64
--- /dev/null
+++ b/docs/api/namespaces/Progmasoft.Progmaweb.Api.Accounts.md
@@ -0,0 +1,10 @@
+---
+uid: Progmasoft.Progmaweb.Api.Accounts
+summary: *content
+---
+
+<!-- SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com> -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1 -->
+
+Accounts and sessions: the HTTP endpoints, the rules for account names, email addresses and passwords, the
+registration and sign-in logic, and the store that keeps accounts and session digests.
diff --git a/docs/api/namespaces/Progmasoft.Progmaweb.Api.Security.md b/docs/api/namespaces/Progmasoft.Progmaweb.Api.Security.md
new file mode 100644
index 0000000..c4cf45a
--- /dev/null
+++ b/docs/api/namespaces/Progmasoft.Progmaweb.Api.Security.md
@@ -0,0 +1,10 @@
+---
+uid: Progmasoft.Progmaweb.Api.Security
+summary: *content
+---
+
+<!-- SPDX-FileCopyrightText: 2026 Progmasoft <support@progmasoft.com> -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later WITH AdditionRef-Progmasoft-Patent-Grant-1.1 -->
+
+Request-pipeline policy that is not specific to accounts: which forwarded headers the service trusts and which
+security headers every response carries.
diff --git a/justfile b/justfile
index d3c29c6..7543809 100644
--- a/justfile
+++ b/justfile
@@ -23,3 +23,4 @@ verify: web-check web-build api-build api-test
 api-docs:
     dotnet tool restore
     dotnet docfx docs/api/docfx.json --warningsAsErrors
+    dotnet run docs/api/CheckDocumentation.cs -- docs/api