Improve developer documentation

Docs/getting-started.md

@@ -1 +1,132 @@
-# Getting Started
+# 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:
+
+```bash
+dotnet add package CapyKit
+```
+
+If you are working from a local checkout instead, reference the project directly:
+
+```bash
+dotnet add reference ../CapyKit/CapyKit.csproj
+```
+
+## Add Namespaces
+
+Most APIs live in one of three namespaces:
+
+```csharp
+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
+
+```csharp
+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
+
+```csharp
+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
+
+```csharp
+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
+
+```csharp
+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
+
+```csharp
+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
+
+```csharp
+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
+
+```csharp
+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](api/toc.yml).