Improve developer documentation

Docs/_site/index.json

@@ -182,16 +182,16 @@
   "getting-started.html": {
     "href": "getting-started.html",
     "title": "Getting Started | CapyKit Documentation",
-    "summary": "Getting Started"
+    "summary": "Getting Started This guide shows the common setup and first-use patterns for consuming CapyKit from a .NET 8 project. Install Add CapyKit to your project from NuGet: dotnet add package CapyKit If you are working from a local checkout instead, reference the project directly: dotnet add reference ../CapyKit/CapyKit.csproj Add Namespaces Most APIs live in one of three namespaces: using CapyKit; using CapyKit.Extensions; using CapyKit.Helpers; Use CapyKit for core types such as Password, Pool<T>, and CapyEventReporter. Use CapyKit.Extensions for extension methods. Use CapyKit.Helpers for serialization, compression, security, keys, language, and calculation helpers. Work With Strings using CapyKit.Extensions; string? suppliedName = \"\"; string name = suppliedName.IfNullOrWhiteSpace(\"Guest\"); IfNullOrEmpty and IfNullOrWhiteSpace return the original value when it is usable and return your replacement value when it is not. Page And Filter Collections using CapyKit.Extensions; var activeUsers = users.Filter(user => user.Disabled); var secondPage = activeUsers.Page(pageNumber: 2, pageSize: 25); int pageCount = activeUsers.PageCount(pageSize: 25); Filter removes items that match the predicate. Page uses natural page numbering, so the first page is 1. Serialize And Compress Data using CapyKit.Helpers; var json = SerializationHelper.SerializeToString(order); var copy = SerializationHelper.Deserialize<Order>(json); var compressed = CompressionHelper.CompressToString(order); var restored = CompressionHelper.Decompress<Order>(compressed); Serialization uses System.Text.Json. Compression stores the serialized JSON payload using gzip; CompressToString returns a Base64 representation for easier storage or transport. Hash And Verify Passwords using CapyKit; using CapyKit.Helpers; Password storedPassword = SecurityHelper.Pbkdf2(\"correct horse battery staple\"); bool passwordMatches = SecurityHelper.CompareHashedPassword( storedPassword, \"correct horse battery staple\", storedPassword.Salt, Password.Pbkdf2Algorithm); SecurityHelper.Pbkdf2 creates a Password with a random salt. Store the hash, salt, and algorithm information required by your application, then compare future password attempts using the same salt and algorithm. Generate Random Values using CapyKit.Helpers; string token = SecurityHelper.GetRandomString(32); string password = SecurityHelper.GetRandomPassword( 20, ValidCharacterCollection.Lowercase, ValidCharacterCollection.Uppercase, ValidCharacterCollection.Numbers, ValidCharacterCollection.Special); Random string and password generation use .NET cryptographic random number generation. Create And Validate Keys using System.Text; using CapyKit.Helpers; var keyHelper = new KeyHelper(); keyHelper.SetMasterKeyAccessor(() => Encoding.UTF8.GetBytes(\"replace-with-your-master-key\")); keyHelper.SetSaltSizeAccessor(() => 8); keyHelper.SetNumPartsAccessor(() => 4); string key = keyHelper.GenerateKey(); bool valid = keyHelper.ValidateKey(key); KeyHelper uses an application-provided master key to sign generated key material. Keep the master key secret and stable for keys that must remain valid over time. Subscribe To CapyKit Events using CapyKit; CapyEventReporter.Subscribe( e => Console.WriteLine($\"[{e.Level}] {e.MethodName}: {e.Message}\"), EventLevel.Warning); CapyKit does not require a logging framework. Subscribe to events and forward them to whatever logging or telemetry system your application already uses. Browse The API For the full list of namespaces, types, overloads, and member signatures, open the generated API Reference."
   },
   "index.html": {
     "href": "index.html",
-    "title": "This is the HOMEPAGE. | CapyKit Documentation",
-    "summary": "This is the HOMEPAGE. Refer to Markdown for how to write markdown files. Quick Start Notes: Add images to the images folder if the file is referencing an image."
+    "title": "CapyKit Documentation | CapyKit Documentation",
+    "summary": "CapyKit Documentation CapyKit is a small .NET utility library for the code you end up writing repeatedly: collection helpers, string and enum extensions, JSON serialization, gzip compression, password hashing, random token generation, simple key validation, distance calculations, and lightweight event reporting. The library targets .NET 8 and keeps its public surface intentionally direct. Most features are static helpers or extension methods, so consuming projects can adopt one piece at a time without taking on a framework or application model. Start Here Introduction explains what CapyKit includes and how the namespaces are organized. Getting Started shows installation, imports, and common usage examples. API Reference contains the generated DocFX reference for every public type and member. Common Tasks Work with strings and collections Use CapyKit.Extensions for small quality-of-life helpers such as null fallback values, pagination, inverted filtering, left outer joins, enum display names, and property copying. using CapyKit.Extensions; var displayName = user.Name.IfNullOrWhiteSpace(\"Guest\"); var page = users.Page(pageNumber: 2, pageSize: 25); Serialize, compress, and restore values Use CapyKit.Helpers.SerializationHelper and CapyKit.Helpers.CompressionHelper when you need straightforward JSON serialization or gzip compression around serializable values. using CapyKit.Helpers; var payload = SerializationHelper.SerializeToString(order); var compressed = CompressionHelper.CompressToString(order); var restored = CompressionHelper.Decompress<Order>(compressed); Hash passwords and generate tokens Use SecurityHelper for PBKDF2 password hashes, salts, and random values backed by .NET cryptographic random number generation. using CapyKit; using CapyKit.Helpers; Password password = SecurityHelper.Pbkdf2(\"correct horse battery staple\"); bool matches = SecurityHelper.CompareHashedPassword( password, \"correct horse battery staple\", password.Salt, Password.Pbkdf2Algorithm); Listen to CapyKit events CapyKit reports warnings and errors through CapyEventReporter instead of choosing a logging framework for you. Subscribe at the level your application cares about and route events into your own logging pipeline. using CapyKit; CapyEventReporter.Subscribe( e => logger.LogWarning(\"{Method}: {Message}\", e.MethodName, e.Message), EventLevel.Warning); Build The Docs Locally The documentation is generated with DocFX from the Markdown files in this folder and the XML comments in the CapyKit project. dotnet tool install -g docfx docfx Docs/docfx.json --serve DocFX writes the generated site to Docs/_site."
   },
   "introduction.html": {
     "href": "introduction.html",
     "title": "Introduction | CapyKit Documentation",
-    "summary": "Introduction"
+    "summary": "Introduction CapyKit is a practical toolkit for .NET applications. It collects common helpers and extension methods into one package so application code can stay focused on business behavior instead of re-implementing the same plumbing in every project. The project began as shared infrastructure for HappyCapy and is now available as a standalone library. It currently targets .NET 8. What CapyKit Provides Extension Methods The CapyKit.Extensions namespace contains helpers for common language and LINQ tasks: StringExtensions provides fallback helpers such as IfNullOrEmpty and IfNullOrWhiteSpace. LINQExtensions adds pagination, page counts, inverted filtering, and left outer join helpers for enumerable and queryable collections. EnumerationExtensions makes enum names, numeric values, descriptions, and human-readable names easier to retrieve. ObjectExtensions copies matching writable properties from one object to another. Helper Classes The CapyKit.Helpers namespace contains focused utility classes: SerializationHelper serializes and deserializes values with System.Text.Json. CompressionHelper compresses serialized values with gzip and can represent compressed data as Base64. SecurityHelper creates PBKDF2 password hashes, salts, random strings, and random passwords. KeyHelper creates and validates formatted HMAC-backed keys using a caller-provided master key. CalculationHelper includes distance calculations, unit conversion, angle conversion, and quick non-cryptographic hash helpers. LanguageHelper converts camel case identifiers into human-readable text. Core Utility Types The root CapyKit namespace includes small types that support the helpers: Password, IPasswordAlgorithm, and Pbkdf2Algorithm model password hashing. Pool<T> and PoolItem<T> provide a simple resource pool abstraction. PropertyComparer<T, U> compares objects by a selected property. CapyEventReporter, CapyEventArgs, and EventLevel expose library diagnostics without requiring a specific logging package. NamedColor provides a large named color enumeration based on the XKCD color survey palette. Design Approach CapyKit favors explicit, discoverable APIs. Most helpers are static methods or extension methods and can be adopted independently. You can use only the namespaces you need, and the library does not impose dependency injection, hosting, logging, or configuration conventions on the consuming application. Where CapyKit needs to communicate warnings or errors internally, it uses CapyEventReporter. Applications can subscribe to these events and map them into their preferred logging, telemetry, or diagnostics system. API Reference The generated API reference is available through the DocFX navigation and starts at API Reference. Use it for exact signatures, overloads, return types, exceptions, and XML comment details."
   }
 }