Improve developer documentation

Docs/index.md

@@ -1,11 +1,79 @@
----
-_layout: landing
----
-
-# This is the **HOMEPAGE**.
-
-Refer to [Markdown](http://daringfireball.net/projects/markdown/) for how to write markdown files.
-
-## Quick Start Notes:
-
-1. Add images to the *images* folder if the file is referencing an image.
+---
+_layout: landing
+---
+
+# 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](introduction.md) explains what CapyKit includes and how the namespaces are organized.
+- [Getting Started](getting-started.md) shows installation, imports, and common usage examples.
+- [API Reference](api/toc.yml) 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.
+
+```csharp
+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.
+
+```csharp
+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.
+
+```csharp
+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.
+
+```csharp
+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.
+
+```bash
+dotnet tool install -g docfx
+docfx Docs/docfx.json --serve
+```
+
+DocFX writes the generated site to `Docs/_site`.