diff --git a/.github/workflows/benchmarks.yml b/.github/workflows/benchmarks.yml
index 527e5b2..256759e 100644
--- a/.github/workflows/benchmarks.yml
+++ b/.github/workflows/benchmarks.yml
@@ -14,10 +14,10 @@ jobs:
   benchmark:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Setup .NET
-        uses: actions/setup-dotnet@v4
+        uses: actions/setup-dotnet@v5
         with:
           dotnet-version: |
             8.0.x
@@ -58,7 +58,7 @@ jobs:
 
       - name: Upload raw artifacts
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: benchmark-results-${{ github.run_number }}
           path: PasswordGenerator.Benchmarks/BenchmarkDotNet.Artifacts/results/
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 0e291c2..d04e877 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -13,12 +13,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0 # full history so SourceLink can resolve the commit
 
       - name: Setup .NET
-        uses: actions/setup-dotnet@v4
+        uses: actions/setup-dotnet@v5
         with:
           dotnet-version: |
             8.0.x
@@ -39,7 +39,7 @@ jobs:
 
       - name: Upload test results
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: test-results
           path: ./test-results/*.trx
@@ -48,7 +48,7 @@ jobs:
         run: dotnet pack PasswordGenerator/PasswordGenerator.csproj -c Release --no-build -o artifacts
 
       - name: Upload package
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: nuget
           path: |
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index e392bd6..07e75c6 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -12,12 +12,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0 # full history so SourceLink can resolve the commit
 
       - name: Setup .NET
-        uses: actions/setup-dotnet@v4
+        uses: actions/setup-dotnet@v5
         with:
           dotnet-version: |
             8.0.x
diff --git a/PasswordGenerator.Benchmarks/Benchmarks/AsyncBenchmarks.cs b/PasswordGenerator.Benchmarks/Benchmarks/AsyncBenchmarks.cs
index a0ab1ef..05b597d 100644
--- a/PasswordGenerator.Benchmarks/Benchmarks/AsyncBenchmarks.cs
+++ b/PasswordGenerator.Benchmarks/Benchmarks/AsyncBenchmarks.cs
@@ -26,13 +26,13 @@ public void Cleanup()
         }
 
         [Benchmark]
-        public Task<string> NextAsync()
+        public ValueTask<string> NextAsync()
         {
             return _password.NextAsync();
         }
 
         [Benchmark]
-        public Task<IReadOnlyList<string>> GenerateAsync()
+        public ValueTask<IReadOnlyList<string>> GenerateAsync()
         {
             return _password.GenerateAsync(Count);
         }
diff --git a/PasswordGenerator.Tests/Phase3Tests.cs b/PasswordGenerator.Tests/Phase3Tests.cs
index 095e3a0..2758096 100644
--- a/PasswordGenerator.Tests/Phase3Tests.cs
+++ b/PasswordGenerator.Tests/Phase3Tests.cs
@@ -29,6 +29,30 @@ public void NextAsync_WithAlreadyCancelledToken_Throws()
                 Throws.InstanceOf<OperationCanceledException>());
         }
 
+        [Test]
+        public void NextAsync_WithCancelledToken_SurfacesCancellationThroughTask()
+        {
+            var pwd = new Password(20);
+            var cts = new CancellationTokenSource();
+            cts.Cancel();
+
+            // Cancellation must come back through the returned task, not as a synchronous throw,
+            // so the result composes correctly when not awaited immediately.
+            var task = pwd.NextAsync(cts.Token);
+            Assert.That(task.IsCanceled, Is.True);
+        }
+
+        [Test]
+        public void GenerateAsync_WithCancelledToken_SurfacesCancellationThroughTask()
+        {
+            var pwd = new Password(16);
+            var cts = new CancellationTokenSource();
+            cts.Cancel();
+
+            var task = pwd.GenerateAsync(10, cts.Token);
+            Assert.That(task.IsCanceled, Is.True);
+        }
+
         [Test]
         public void Generate_ReturnsRequestedCount()
         {
diff --git a/PasswordGenerator/CharacterClass.cs b/PasswordGenerator/CharacterClass.cs
index ea525c7..e5947f3 100644
--- a/PasswordGenerator/CharacterClass.cs
+++ b/PasswordGenerator/CharacterClass.cs
@@ -6,9 +6,16 @@ namespace PasswordGenerator
     /// </summary>
     public enum CharacterClass
     {
+        /// <summary>Lowercase letters (<c>a–z</c>).</summary>
         Lowercase,
+
+        /// <summary>Uppercase letters (<c>A–Z</c>).</summary>
         Uppercase,
+
+        /// <summary>Digits (<c>0–9</c>).</summary>
         Numeric,
+
+        /// <summary>Special / symbol characters.</summary>
         Special
     }
 }
diff --git a/PasswordGenerator/CryptoRandomSource.cs b/PasswordGenerator/CryptoRandomSource.cs
index 93a220e..d3f7ace 100644
--- a/PasswordGenerator/CryptoRandomSource.cs
+++ b/PasswordGenerator/CryptoRandomSource.cs
@@ -10,6 +10,15 @@ namespace PasswordGenerator
     /// </summary>
     public sealed class CryptoRandomSource : IRandomSource
     {
+        /// <summary>
+        ///     Returns a uniformly distributed, non-negative random integer that is less than
+        ///     <paramref name="maxExclusive" />.
+        /// </summary>
+        /// <param name="maxExclusive">The exclusive upper bound; must be positive.</param>
+        /// <returns>A random integer in the range <c>[0, maxExclusive)</c>.</returns>
+        /// <exception cref="ArgumentOutOfRangeException">
+        ///     <paramref name="maxExclusive" /> is zero or negative.
+        /// </exception>
         public int NextInt(int maxExclusive)
         {
             if (maxExclusive <= 0)
diff --git a/PasswordGenerator/IPassword.cs b/PasswordGenerator/IPassword.cs
index 70fe6ee..a778230 100644
--- a/PasswordGenerator/IPassword.cs
+++ b/PasswordGenerator/IPassword.cs
@@ -2,12 +2,31 @@
 
 namespace PasswordGenerator
 {
+    /// <summary>
+    ///     Fluent builder for configuring and generating passwords. Each configuration method returns the
+    ///     same instance so calls can be chained.
+    /// </summary>
     public interface IPassword
     {
+        /// <summary>Includes lowercase letters in the pool.</summary>
+        /// <returns>The same builder, for chaining.</returns>
         IPassword IncludeLowercase();
+
+        /// <summary>Includes uppercase letters in the pool.</summary>
+        /// <returns>The same builder, for chaining.</returns>
         IPassword IncludeUppercase();
+
+        /// <summary>Includes digits in the pool.</summary>
+        /// <returns>The same builder, for chaining.</returns>
         IPassword IncludeNumeric();
+
+        /// <summary>Includes the default special characters in the pool.</summary>
+        /// <returns>The same builder, for chaining.</returns>
         IPassword IncludeSpecial();
+
+        /// <summary>Includes the given special characters in the pool.</summary>
+        /// <param name="specialCharactersToInclude">The special characters to add to the pool.</param>
+        /// <returns>The same builder, for chaining.</returns>
         IPassword IncludeSpecial(string specialCharactersToInclude);
 
         /// <summary>Replaces the pool with an explicit set of characters (no forced composition).</summary>
@@ -22,9 +41,25 @@ public interface IPassword
         /// <summary>Requires at least <paramref name="count" /> characters from the given class.</summary>
         IPassword RequireAtLeast(CharacterClass characterClass, int count);
 
+        /// <summary>Sets the required password length.</summary>
+        /// <param name="passwordLength">The number of characters the generated password should contain.</param>
+        /// <returns>The same builder, for chaining.</returns>
         IPassword LengthRequired(int passwordLength);
+
+        /// <summary>Generates a single password using the current settings.</summary>
+        /// <returns>The generated password.</returns>
         string Next();
+
+        /// <summary>Attempts to generate a single password without throwing on invalid settings.</summary>
+        /// <param name="password">
+        ///     When this method returns <see langword="true" />, the generated password; otherwise <see langword="null" />.
+        /// </param>
+        /// <returns><see langword="true" /> if a password was generated; otherwise <see langword="false" />.</returns>
         bool TryNext(out string? password);
+
+        /// <summary>Generates a sequence of passwords using the current settings.</summary>
+        /// <param name="numberOfPasswordsToGenerate">How many passwords to generate.</param>
+        /// <returns>The generated passwords.</returns>
         IEnumerable<string> NextGroup(int numberOfPasswordsToGenerate);
     }
 }
\ No newline at end of file
diff --git a/PasswordGenerator/IPasswordGenerator.cs b/PasswordGenerator/IPasswordGenerator.cs
index b842dc4..e3651c9 100644
--- a/PasswordGenerator/IPasswordGenerator.cs
+++ b/PasswordGenerator/IPasswordGenerator.cs
@@ -17,10 +17,12 @@ public interface IPasswordGenerator
         bool TryNext(out string? password);
 
         /// <summary>
-        ///     Generates a single password. Generation is CPU-bound; this overload exists for ergonomics
-        ///     and to honour cancellation, not to offload work to another thread.
+        ///     Generates a single password. Generation is CPU-bound and completes synchronously; this overload
+        ///     exists for ergonomics and to honour cancellation, not to offload work to another thread. A
+        ///     <see cref="ValueTask{TResult}" /> is used because the result is always available synchronously.
+        ///     If <paramref name="cancellationToken" /> is already cancelled, the returned task is cancelled.
         /// </summary>
-        Task<string> NextAsync(CancellationToken cancellationToken = default);
+        ValueTask<string> NextAsync(CancellationToken cancellationToken = default);
 
         /// <summary>Generates the default number of passwords (configurable; one unless overridden).</summary>
         IReadOnlyList<string> Generate();
@@ -29,9 +31,9 @@ public interface IPasswordGenerator
         IReadOnlyList<string> Generate(int count);
 
         /// <summary>Generates the default number of passwords, observing <paramref name="cancellationToken" />.</summary>
-        Task<IReadOnlyList<string>> GenerateAsync(CancellationToken cancellationToken = default);
+        ValueTask<IReadOnlyList<string>> GenerateAsync(CancellationToken cancellationToken = default);
 
         /// <summary>Generates <paramref name="count" /> passwords, observing <paramref name="cancellationToken" />.</summary>
-        Task<IReadOnlyList<string>> GenerateAsync(int count, CancellationToken cancellationToken = default);
+        ValueTask<IReadOnlyList<string>> GenerateAsync(int count, CancellationToken cancellationToken = default);
     }
 }
diff --git a/PasswordGenerator/IPasswordSettings.cs b/PasswordGenerator/IPasswordSettings.cs
index 8dbebd3..ddd2b97 100644
--- a/PasswordGenerator/IPasswordSettings.cs
+++ b/PasswordGenerator/IPasswordSettings.cs
@@ -7,11 +7,22 @@ namespace PasswordGenerator
     /// </summary>
     public interface IPasswordSettings
     {
+        /// <summary>Whether lowercase letters are included in the pool.</summary>
         bool IncludeLowercase { get; }
+
+        /// <summary>Whether uppercase letters are included in the pool.</summary>
         bool IncludeUppercase { get; }
+
+        /// <summary>Whether digits are included in the pool.</summary>
         bool IncludeNumeric { get; }
+
+        /// <summary>Whether special characters are included in the pool.</summary>
         bool IncludeSpecial { get; }
+
+        /// <summary>The number of characters the generated password should contain.</summary>
         int PasswordLength { get; set; }
+
+        /// <summary>The full set of characters the password is drawn from, after applying all settings.</summary>
         string CharacterSet { get; }
 
         /// <summary>True when a custom pool (e.g. <see cref="UseCharacters" />) replaces the per-class sets.</summary>
@@ -28,13 +39,35 @@ public interface IPasswordSettings
         ///     guarantee at least one character from each required class is present in the output.
         /// </summary>
         IReadOnlyList<string> CharacterGroups { get; }
+
+        /// <summary>The maximum number of attempts allowed when generating a valid password.</summary>
         int MaximumAttempts { get; }
+
+        /// <summary>The smallest allowed password length.</summary>
         int MinimumLength { get; }
+
+        /// <summary>The largest allowed password length.</summary>
         int MaximumLength { get; }
+
+        /// <summary>Enables lowercase letters in the pool.</summary>
+        /// <returns>The same settings, for chaining.</returns>
         IPasswordSettings AddLowercase();
+
+        /// <summary>Enables uppercase letters in the pool.</summary>
+        /// <returns>The same settings, for chaining.</returns>
         IPasswordSettings AddUppercase();
+
+        /// <summary>Enables digits in the pool.</summary>
+        /// <returns>The same settings, for chaining.</returns>
         IPasswordSettings AddNumeric();
+
+        /// <summary>Enables the default special characters in the pool.</summary>
+        /// <returns>The same settings, for chaining.</returns>
         IPasswordSettings AddSpecial();
+
+        /// <summary>Enables the given special characters in the pool.</summary>
+        /// <param name="specialCharactersToAdd">The special characters to add to the pool.</param>
+        /// <returns>The same settings, for chaining.</returns>
         IPasswordSettings AddSpecial(string specialCharactersToAdd);
 
         /// <summary>Replaces the entire pool with an explicit set of characters (no forced composition).</summary>
@@ -49,6 +82,7 @@ public interface IPasswordSettings
         /// <summary>Requires at least <paramref name="count" /> characters from the given class, enabling it if needed.</summary>
         IPasswordSettings RequireAtLeast(CharacterClass characterClass, int count);
 
+        /// <summary>The special characters used when special characters are included.</summary>
         string SpecialCharacters { get; set; }
     }
 }
\ No newline at end of file
diff --git a/PasswordGenerator/PassphraseGenerator.cs b/PasswordGenerator/PassphraseGenerator.cs
index e4ea7b7..00549e1 100644
--- a/PasswordGenerator/PassphraseGenerator.cs
+++ b/PasswordGenerator/PassphraseGenerator.cs
@@ -16,6 +16,16 @@ public class PassphraseGenerator : IPasswordGenerator, IDisposable
         private readonly IRandomSource _random;
         private readonly bool _ownsRandom;
 
+        /// <summary>Creates a passphrase generator.</summary>
+        /// <param name="wordCount">The number of words in each passphrase; must be at least one.</param>
+        /// <param name="separator">The character placed between words (and before the trailing number).</param>
+        /// <param name="capitalize">Whether to capitalize the first letter of each word.</param>
+        /// <param name="includeNumber">Whether to append a random two-digit number.</param>
+        /// <param name="randomSource">
+        ///     An optional random source. When supplied, the caller owns it; otherwise a
+        ///     <see cref="CryptoRandomSource" /> is created and owned by this instance.
+        /// </param>
+        /// <exception cref="ArgumentOutOfRangeException"><paramref name="wordCount" /> is less than one.</exception>
         public PassphraseGenerator(int wordCount = 4, char separator = '-', bool capitalize = false,
             bool includeNumber = true, IRandomSource? randomSource = null)
         {
@@ -30,14 +40,22 @@ public PassphraseGenerator(int wordCount = 4, char separator = '-', bool capital
             _ownsRandom = randomSource == null;
         }
 
+        /// <summary>The number of words in each passphrase.</summary>
         public int WordCount { get; }
+
+        /// <summary>The character placed between words.</summary>
         public char Separator { get; }
+
+        /// <summary>Whether the first letter of each word is capitalized.</summary>
         public bool Capitalize { get; }
+
+        /// <summary>Whether a random two-digit number is appended.</summary>
         public bool IncludeNumber { get; }
 
         /// <summary>The number of passphrases produced by the parameterless <see cref="Generate()" /> overload.</summary>
         public int DefaultBatchCount { get; set; } = 1;
 
+        /// <inheritdoc />
         public string Next()
         {
             var sb = new StringBuilder();
@@ -67,23 +85,28 @@ public string Next()
             return sb.ToString();
         }
 
+        /// <inheritdoc />
         public bool TryNext(out string? password)
         {
             password = Next();
             return true;
         }
 
-        public Task<string> NextAsync(CancellationToken cancellationToken = default)
+        /// <inheritdoc />
+        public ValueTask<string> NextAsync(CancellationToken cancellationToken = default)
         {
-            cancellationToken.ThrowIfCancellationRequested();
-            return Task.FromResult(Next());
+            return cancellationToken.IsCancellationRequested
+                ? ValueTask.FromCanceled<string>(cancellationToken)
+                : new ValueTask<string>(Next());
         }
 
+        /// <inheritdoc />
         public IReadOnlyList<string> Generate()
         {
             return Generate(DefaultBatchCount);
         }
 
+        /// <inheritdoc />
         public IReadOnlyList<string> Generate(int count)
         {
             if (count < 0)
@@ -96,24 +119,30 @@ public IReadOnlyList<string> Generate(int count)
             return passphrases;
         }
 
-        public Task<IReadOnlyList<string>> GenerateAsync(CancellationToken cancellationToken = default)
+        /// <inheritdoc />
+        public ValueTask<IReadOnlyList<string>> GenerateAsync(CancellationToken cancellationToken = default)
         {
             return GenerateAsync(DefaultBatchCount, cancellationToken);
         }
 
-        public Task<IReadOnlyList<string>> GenerateAsync(int count, CancellationToken cancellationToken = default)
+        /// <inheritdoc />
+        public ValueTask<IReadOnlyList<string>> GenerateAsync(int count, CancellationToken cancellationToken = default)
         {
             if (count < 0)
                 throw new ArgumentOutOfRangeException(nameof(count), "count cannot be negative.");
 
+            if (cancellationToken.IsCancellationRequested)
+                return ValueTask.FromCanceled<IReadOnlyList<string>>(cancellationToken);
+
             var passphrases = new List<string>(count);
             for (var i = 0; i < count; i++)
             {
-                cancellationToken.ThrowIfCancellationRequested();
+                if (cancellationToken.IsCancellationRequested)
+                    return ValueTask.FromCanceled<IReadOnlyList<string>>(cancellationToken);
                 passphrases.Add(Next());
             }
 
-            return Task.FromResult<IReadOnlyList<string>>(passphrases);
+            return new ValueTask<IReadOnlyList<string>>(passphrases);
         }
 
         /// <summary>Estimates passphrase entropy in bits from the word-list size, word count, and trailing number.</summary>
@@ -124,6 +153,7 @@ public double EstimateEntropyBits()
             return bits;
         }
 
+        /// <summary>Disposes the random source when this instance owns it (i.e. it was not supplied by the caller).</summary>
         public void Dispose()
         {
             if (_ownsRandom && _random is IDisposable disposable)
diff --git a/PasswordGenerator/Password.cs b/PasswordGenerator/Password.cs
index 4e44763..8cc48f5 100644
--- a/PasswordGenerator/Password.cs
+++ b/PasswordGenerator/Password.cs
@@ -20,6 +20,7 @@ public class Password : IPassword, IPasswordGenerator, IDisposable
         private readonly IRandomSource _random;
         private readonly bool _ownsRandom;
 
+        /// <summary>Creates a generator with the default settings (all character classes, length 16).</summary>
         public Password()
         {
             Settings = new PasswordSettings(DefaultIncludeLowercase, DefaultIncludeUppercase,
@@ -29,6 +30,8 @@ public Password()
             _ownsRandom = true;
         }
 
+        /// <summary>Creates a generator from the supplied settings.</summary>
+        /// <param name="settings">The settings to use.</param>
         public Password(IPasswordSettings settings)
         {
             Settings = settings;
@@ -36,6 +39,8 @@ public Password(IPasswordSettings settings)
             _ownsRandom = true;
         }
 
+        /// <summary>Creates a generator with the default character classes and the given length.</summary>
+        /// <param name="passwordLength">The required password length.</param>
         public Password(int passwordLength)
         {
             Settings = new PasswordSettings(DefaultIncludeLowercase, DefaultIncludeUppercase,
@@ -44,6 +49,11 @@ public Password(int passwordLength)
             _ownsRandom = true;
         }
 
+        /// <summary>Creates a generator with the given character classes enabled and the default length.</summary>
+        /// <param name="includeLowercase">Whether to include lowercase letters.</param>
+        /// <param name="includeUppercase">Whether to include uppercase letters.</param>
+        /// <param name="includeNumeric">Whether to include digits.</param>
+        /// <param name="includeSpecial">Whether to include special characters.</param>
         public Password(bool includeLowercase, bool includeUppercase, bool includeNumeric, bool includeSpecial)
         {
             Settings = new PasswordSettings(includeLowercase, includeUppercase, includeNumeric,
@@ -52,6 +62,12 @@ public Password(bool includeLowercase, bool includeUppercase, bool includeNumeri
             _ownsRandom = true;
         }
 
+        /// <summary>Creates a generator with the given character classes enabled and a specific length.</summary>
+        /// <param name="includeLowercase">Whether to include lowercase letters.</param>
+        /// <param name="includeUppercase">Whether to include uppercase letters.</param>
+        /// <param name="includeNumeric">Whether to include digits.</param>
+        /// <param name="includeSpecial">Whether to include special characters.</param>
+        /// <param name="passwordLength">The required password length.</param>
         public Password(bool includeLowercase, bool includeUppercase, bool includeNumeric, bool includeSpecial,
             int passwordLength)
         {
@@ -61,6 +77,13 @@ public Password(bool includeLowercase, bool includeUppercase, bool includeNumeri
             _ownsRandom = true;
         }
 
+        /// <summary>Creates a generator with the given character classes, length, and attempt limit.</summary>
+        /// <param name="includeLowercase">Whether to include lowercase letters.</param>
+        /// <param name="includeUppercase">Whether to include uppercase letters.</param>
+        /// <param name="includeNumeric">Whether to include digits.</param>
+        /// <param name="includeSpecial">Whether to include special characters.</param>
+        /// <param name="passwordLength">The required password length.</param>
+        /// <param name="maximumAttempts">The maximum number of generation attempts.</param>
         public Password(bool includeLowercase, bool includeUppercase, bool includeNumeric, bool includeSpecial,
             int passwordLength, int maximumAttempts)
         {
@@ -81,62 +104,73 @@ public Password(IPasswordSettings settings, IRandomSource randomSource)
             _ownsRandom = false;
         }
 
+        /// <summary>The settings that drive generation. Replaced in place by the fluent configuration methods.</summary>
         public IPasswordSettings Settings { get; set; }
 
+        /// <inheritdoc />
         public IPassword IncludeLowercase()
         {
             Settings = Settings.AddLowercase();
             return this;
         }
 
+        /// <inheritdoc />
         public IPassword IncludeUppercase()
         {
             Settings = Settings.AddUppercase();
             return this;
         }
 
+        /// <inheritdoc />
         public IPassword IncludeNumeric()
         {
             Settings = Settings.AddNumeric();
             return this;
         }
 
+        /// <inheritdoc />
         public IPassword IncludeSpecial()
         {
             Settings = Settings.AddSpecial();
             return this;
         }
 
+        /// <inheritdoc />
         public IPassword IncludeSpecial(string specialCharactersToInclude)
         {
             Settings = Settings.AddSpecial(specialCharactersToInclude);
             return this;
         }
 
+        /// <inheritdoc />
         public IPassword WithCharacters(string characters)
         {
             Settings = Settings.UseCharacters(characters);
             return this;
         }
 
+        /// <inheritdoc />
         public IPassword WithAllAscii()
         {
             Settings = Settings.UseAllAscii();
             return this;
         }
 
+        /// <inheritdoc />
         public IPassword ExcludeAmbiguous()
         {
             Settings = Settings.ExcludeAmbiguousCharacters();
             return this;
         }
 
+        /// <inheritdoc />
         public IPassword RequireAtLeast(CharacterClass characterClass, int count)
         {
             Settings = Settings.RequireAtLeast(characterClass, count);
             return this;
         }
 
+        /// <inheritdoc />
         public IPassword LengthRequired(int passwordLength)
         {
             Settings.PasswordLength = passwordLength;
@@ -182,22 +216,27 @@ public bool TryNext(out string? password)
             return true;
         }
 
+        /// <inheritdoc />
         public IEnumerable<string> NextGroup(int numberOfPasswordsToGenerate)
         {
             return Generate(numberOfPasswordsToGenerate);
         }
 
-        public Task<string> NextAsync(CancellationToken cancellationToken = default)
+        /// <inheritdoc />
+        public ValueTask<string> NextAsync(CancellationToken cancellationToken = default)
         {
-            cancellationToken.ThrowIfCancellationRequested();
-            return Task.FromResult(Next());
+            return cancellationToken.IsCancellationRequested
+                ? ValueTask.FromCanceled<string>(cancellationToken)
+                : new ValueTask<string>(Next());
         }
 
+        /// <inheritdoc />
         public IReadOnlyList<string> Generate()
         {
             return Generate(DefaultBatchCount);
         }
 
+        /// <inheritdoc />
         public IReadOnlyList<string> Generate(int count)
         {
             if (count < 0)
@@ -210,24 +249,30 @@ public IReadOnlyList<string> Generate(int count)
             return passwords;
         }
 
-        public Task<IReadOnlyList<string>> GenerateAsync(CancellationToken cancellationToken = default)
+        /// <inheritdoc />
+        public ValueTask<IReadOnlyList<string>> GenerateAsync(CancellationToken cancellationToken = default)
         {
             return GenerateAsync(DefaultBatchCount, cancellationToken);
         }
 
-        public Task<IReadOnlyList<string>> GenerateAsync(int count, CancellationToken cancellationToken = default)
+        /// <inheritdoc />
+        public ValueTask<IReadOnlyList<string>> GenerateAsync(int count, CancellationToken cancellationToken = default)
         {
             if (count < 0)
                 throw new ArgumentOutOfRangeException(nameof(count), "count cannot be negative.");
 
+            if (cancellationToken.IsCancellationRequested)
+                return ValueTask.FromCanceled<IReadOnlyList<string>>(cancellationToken);
+
             var passwords = new List<string>(count);
             for (var i = 0; i < count; i++)
             {
-                cancellationToken.ThrowIfCancellationRequested();
+                if (cancellationToken.IsCancellationRequested)
+                    return ValueTask.FromCanceled<IReadOnlyList<string>>(cancellationToken);
                 passwords.Add(Next());
             }
 
-            return Task.FromResult<IReadOnlyList<string>>(passwords);
+            return new ValueTask<IReadOnlyList<string>>(passwords);
         }
 
         private static readonly CharacterClass[] OrderedClasses =
@@ -369,6 +414,7 @@ private static bool LengthIsValid(int passwordLength, int minLength, int maxLeng
             return passwordLength >= minLength && passwordLength <= maxLength;
         }
 
+        /// <summary>Disposes the random source when this instance owns it (i.e. it was not supplied by the caller).</summary>
         public void Dispose()
         {
             if (_ownsRandom && _random is IDisposable disposable)
diff --git a/PasswordGenerator/PasswordGenerator.csproj b/PasswordGenerator/PasswordGenerator.csproj
index ae8ce7a..a4c08df 100644
--- a/PasswordGenerator/PasswordGenerator.csproj
+++ b/PasswordGenerator/PasswordGenerator.csproj
@@ -5,6 +5,9 @@
         <Nullable>enable</Nullable>
         <LangVersion>latest</LangVersion>
 
+        <!-- Ship XML docs so consumers get IntelliSense for the public API -->
+        <GenerateDocumentationFile>true</GenerateDocumentationFile>
+
         <!-- Single source of version truth -->
         <Version>3.0.0</Version>
         <AssemblyVersion>3.0.0.0</AssemblyVersion>
diff --git a/PasswordGenerator/PasswordOptions.cs b/PasswordGenerator/PasswordOptions.cs
index b9eb066..a025bbe 100644
--- a/PasswordGenerator/PasswordOptions.cs
+++ b/PasswordGenerator/PasswordOptions.cs
@@ -6,14 +6,22 @@ namespace PasswordGenerator
     /// </summary>
     public class PasswordOptions
     {
+        /// <summary>Whether lowercase letters are included in the pool. Defaults to <see langword="true" />.</summary>
         public bool IncludeLowercase { get; set; } = true;
+
+        /// <summary>Whether uppercase letters are included in the pool. Defaults to <see langword="true" />.</summary>
         public bool IncludeUppercase { get; set; } = true;
+
+        /// <summary>Whether digits are included in the pool. Defaults to <see langword="true" />.</summary>
         public bool IncludeNumeric { get; set; } = true;
+
+        /// <summary>Whether special characters are included in the pool. Defaults to <see langword="true" />.</summary>
         public bool IncludeSpecial { get; set; } = true;
 
         /// <summary>Custom special characters. When null/empty the library default special set is used.</summary>
         public string? SpecialCharacters { get; set; }
 
+        /// <summary>The password length. Defaults to <c>16</c>.</summary>
         public int Length { get; set; } = 16;
 
         /// <summary>Removes look-alike characters from the pool when true.</summary>
diff --git a/PasswordGenerator/PasswordSettings.cs b/PasswordGenerator/PasswordSettings.cs
index 26b6431..5f9c947 100644
--- a/PasswordGenerator/PasswordSettings.cs
+++ b/PasswordGenerator/PasswordSettings.cs
@@ -9,14 +9,33 @@ namespace PasswordGenerator
     /// </summary>
     public class PasswordSettings : IPasswordSettings
     {
+        /// <summary>The lowercase letters (<c>a–z</c>) used when lowercase is enabled.</summary>
         public const string LowercaseCharacters = "abcdefghijklmnopqrstuvwxyz";
+
+        /// <summary>The uppercase letters (<c>A–Z</c>) used when uppercase is enabled.</summary>
         public const string UppercaseCharacters = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+        /// <summary>The digits (<c>0–9</c>) used when numeric is enabled.</summary>
         public const string NumericCharacters = "0123456789";
+
         private const string DefaultSpecialCharacters = @"!#$%&*@\";
         private const int DefaultMinPasswordLength = 4;
         private const int DefaultMaxPasswordLength = 256;
+
+        /// <inheritdoc />
         public string SpecialCharacters { get; set; }
 
+        /// <summary>Creates a settings instance.</summary>
+        /// <param name="includeLowercase">Whether to include lowercase letters.</param>
+        /// <param name="includeUppercase">Whether to include uppercase letters.</param>
+        /// <param name="includeNumeric">Whether to include digits.</param>
+        /// <param name="includeSpecial">Whether to include special characters.</param>
+        /// <param name="passwordLength">The required password length.</param>
+        /// <param name="maximumAttempts">The maximum number of generation attempts.</param>
+        /// <param name="usingDefaults">
+        ///     Whether these are the library defaults; when <see langword="true" />, the first fluent
+        ///     configuration call clears the default pool before applying changes.
+        /// </param>
         public PasswordSettings(bool includeLowercase, bool includeUppercase, bool includeNumeric, bool includeSpecial,
             int passwordLength, int maximumAttempts, bool usingDefaults)
         {
@@ -36,19 +55,43 @@ public PasswordSettings(bool includeLowercase, bool includeUppercase, bool inclu
         private bool UsingDefaults { get; set; }
         private readonly Dictionary<CharacterClass, int> _minimumCounts = new Dictionary<CharacterClass, int>();
 
+        /// <inheritdoc />
         public bool IncludeLowercase { get; private set; }
+
+        /// <inheritdoc />
         public bool IncludeUppercase { get; private set; }
+
+        /// <inheritdoc />
         public bool IncludeNumeric { get; private set; }
+
+        /// <inheritdoc />
         public bool IncludeSpecial { get; private set; }
+
+        /// <inheritdoc />
         public int PasswordLength { get; set; }
+
+        /// <inheritdoc />
         public string CharacterSet { get; private set; }
+
+        /// <inheritdoc />
         public bool IsCustomPool { get; private set; }
+
+        /// <inheritdoc />
         public bool ExcludeAmbiguous { get; private set; }
+
+        /// <inheritdoc />
         public IReadOnlyDictionary<CharacterClass, int> MinimumCounts => _minimumCounts;
+
+        /// <inheritdoc />
         public int MaximumAttempts { get; }
+
+        /// <inheritdoc />
         public int MinimumLength { get; }
+
+        /// <inheritdoc />
         public int MaximumLength { get; }
 
+        /// <inheritdoc />
         public IReadOnlyList<string> CharacterGroups
         {
             get
@@ -62,6 +105,7 @@ public IReadOnlyList<string> CharacterGroups
             }
         }
 
+        /// <inheritdoc />
         public IPasswordSettings AddLowercase()
         {
             StopUsingDefaults();
@@ -70,6 +114,7 @@ public IPasswordSettings AddLowercase()
             return this;
         }
 
+        /// <inheritdoc />
         public IPasswordSettings AddUppercase()
         {
             StopUsingDefaults();
@@ -78,6 +123,7 @@ public IPasswordSettings AddUppercase()
             return this;
         }
 
+        /// <inheritdoc />
         public IPasswordSettings AddNumeric()
         {
             StopUsingDefaults();
@@ -86,6 +132,7 @@ public IPasswordSettings AddNumeric()
             return this;
         }
 
+        /// <inheritdoc />
         public IPasswordSettings AddSpecial()
         {
             StopUsingDefaults();
@@ -95,6 +142,7 @@ public IPasswordSettings AddSpecial()
             return this;
         }
 
+        /// <inheritdoc />
         public IPasswordSettings AddSpecial(string specialCharactersToAdd)
         {
             StopUsingDefaults();
@@ -104,6 +152,7 @@ public IPasswordSettings AddSpecial(string specialCharactersToAdd)
             return this;
         }
 
+        /// <inheritdoc />
         public IPasswordSettings UseCharacters(string characters)
         {
             if (characters == null) throw new ArgumentNullException(nameof(characters));
@@ -119,17 +168,20 @@ public IPasswordSettings UseCharacters(string characters)
             return this;
         }
 
+        /// <inheritdoc />
         public IPasswordSettings UseAllAscii()
         {
             return UseCharacters(CharacterFilter.AllPrintableAscii);
         }
 
+        /// <inheritdoc />
         public IPasswordSettings ExcludeAmbiguousCharacters()
         {
             ExcludeAmbiguous = true;
             return this;
         }
 
+        /// <inheritdoc />
         public IPasswordSettings RequireAtLeast(CharacterClass characterClass, int count)
         {
             if (count < 0) throw new ArgumentOutOfRangeException(nameof(count), "count cannot be negative.");
diff --git a/PasswordGenerator/PoolEntropyEstimator.cs b/PasswordGenerator/PoolEntropyEstimator.cs
index 0bd8753..b8a2308 100644
--- a/PasswordGenerator/PoolEntropyEstimator.cs
+++ b/PasswordGenerator/PoolEntropyEstimator.cs
@@ -7,6 +7,15 @@ namespace PasswordGenerator
     /// </summary>
     public class PoolEntropyEstimator : IEntropyEstimator
     {
+        /// <summary>
+        ///     Estimates the entropy, in bits, of passwords produced with the given
+        ///     <paramref name="settings" /> as <c>length × log2(effective pool size)</c>.
+        /// </summary>
+        /// <param name="settings">The settings describing the character pool and length.</param>
+        /// <returns>
+        ///     The estimated entropy in bits, or <c>0</c> when the pool is empty or the length is not positive.
+        /// </returns>
+        /// <exception cref="ArgumentNullException"><paramref name="settings" /> is <see langword="null" />.</exception>
         public double EstimateBits(IPasswordSettings settings)
         {
             if (settings == null) throw new ArgumentNullException(nameof(settings));
diff --git a/docs/api-surface.md b/docs/api-surface.md
index 61723f4..7e3fffc 100644
--- a/docs/api-surface.md
+++ b/docs/api-surface.md
@@ -28,7 +28,7 @@ flowchart TD
     subgraph Gen["Generation (IPasswordGenerator)"]
         g1["Next() : string  (throws on bad config)"]
         g2["TryNext(out string) : bool"]
-        g3["NextAsync(ct) : Task~string~"]
+        g3["NextAsync(ct) : ValueTask~string~"]
         g4["Generate() / Generate(count)"]
         g5["GenerateAsync() / GenerateAsync(count, ct)"]
     end