Enhance documentation across multiple files with detailed guides on features, installation, pagination, multi-tenancy, soft delete, and query helpers; improve clarity and usability for users.

Author: Clifftech123

.gitignore

@@ -362,5 +362,3 @@ MigrationBackup/
 # Fody - auto-generated XML schema
 FodyWeavers.xsd
 
-# Personal implementation notes
-IMPLEMENTATION_GUIDE.md

README.md

@@ -80,6 +80,20 @@ Install just what you need, or grab the umbrella package:
 dotnet add package EfCoreKit
 ```
 
+## Documentation
+
+Each feature has a dedicated guide with full examples, configuration options, and best practices:
+
+| Guide | What You'll Learn |
+|-------|-------------------|
+| [Getting Started](docs/getting-started.md) | Installation, DbContext setup, DI registration |
+| [Soft Delete](docs/soft-delete.md) | ISoftDeletable, cascade delete, restoring records |
+| [Audit Trail](docs/audit-trail.md) | IAuditable, auto-stamping, CreatedAt/CreatedBy protection |
+| [Multi-Tenancy](docs/multi-tenancy.md) | ITenantEntity, automatic filtering, tenant validation |
+| [Pagination](docs/pagination.md) | Offset and keyset pagination, PagedResult, KeysetPagedResult |
+| [Query Helpers](docs/query-helpers.md) | WhereIf, OrderByDynamic, specifications, DbSet extensions |
+| [Bulk Operations](docs/bulk-operations.md) | BulkInsert/Update/Delete/Upsert, BulkConfig tuning |
+
 ## License
 
 MIT — free for personal and commercial use, forever.

docs/audit-trail.md

@@ -1 +1,110 @@
+# Audit Trail
+
+EfCoreKit automatically timestamps entity creation and modification, and records which user made the change.
+
+## How It Works
+
+The `AuditInterceptor` hooks into every `SaveChanges` / `SaveChangesAsync` call:
+
+| State | What happens |
+|-------|-------------|
+| `Added` | Sets `CreatedAt` to `DateTime.UtcNow` and `CreatedBy` to the current user ID |
+| `Modified` | Sets `UpdatedAt` to `DateTime.UtcNow` and `UpdatedBy` to the current user ID. Protects `CreatedAt` and `CreatedBy` from being overwritten |
+
+## Setup
+
+```csharp
+builder.Services.AddEfCoreKit<AppDbContext>(
+    options => options.UseSqlServer(connectionString),
+    kit => kit
+        .EnableAuditTrail()
+        .UseUserProvider<HttpContextUserProvider>()
+);
+```
+
+## Implement the Interface
+
+Add `IAuditable` to any entity you want to track:
+
+```csharp
+public class Product : IAuditable
+{
+    public int Id { get; set; }
+    public string Name { get; set; } = string.Empty;
+    public decimal Price { get; set; }
+
+    // IAuditable
+    public DateTime CreatedAt { get; set; }
+    public string? CreatedBy { get; set; }
+    public DateTime? UpdatedAt { get; set; }
+    public string? UpdatedBy { get; set; }
+}
+```
+
+## Usage
+
+No extra code needed — just save normally:
+
+```csharp
+// Insert — CreatedAt and CreatedBy are set automatically
+var product = new Product { Name = "Widget", Price = 9.99m };
+context.Products.Add(product);
+await context.SaveChangesAsync();
+// product.CreatedAt == DateTime.UtcNow
+// product.CreatedBy == "user-123" (from IUserProvider)
+
+// Update — UpdatedAt and UpdatedBy are set automatically
+product.Price = 12.99m;
+await context.SaveChangesAsync();
+// product.UpdatedAt == DateTime.UtcNow
+// product.UpdatedBy == "user-123"
+// product.CreatedAt remains unchanged (protected)
+```
+
+## IUserProvider
+
+EfCoreKit resolves the current user through `IUserProvider`. You provide the implementation:
+
+```csharp
+public interface IUserProvider
+{
+    string? GetCurrentUserId();
+    string? GetCurrentUserName();
+}
+```
+
+### ASP.NET Core Example
+
+```csharp
+public class HttpContextUserProvider : IUserProvider
+{
+    private readonly IHttpContextAccessor _accessor;
+
+    public HttpContextUserProvider(IHttpContextAccessor accessor) => _accessor = accessor;
+
+    public string? GetCurrentUserId()
+        => _accessor.HttpContext?.User?.FindFirst(ClaimTypes.NameIdentifier)?.Value;
+
+    public string? GetCurrentUserName()
+        => _accessor.HttpContext?.User?.Identity?.Name;
+}
+```
+
+### Console App / Background Service Example
+
+```csharp
+public class SystemUserProvider : IUserProvider
+{
+    public string? GetCurrentUserId() => "system";
+    public string? GetCurrentUserName() => "Background Service";
+}
+```
+
+## CreatedAt / CreatedBy Protection
+
+The audit interceptor marks `CreatedAt` and `CreatedBy` as `IsModified = false` on updates. This means even if your code accidentally sets these properties during an update, the original values are preserved in the database.
+
+## Combining with Soft Delete
+
+When an entity implements both `IAuditable` and `ISoftDeletable`, soft delete triggers a `Modified` state change, which means `UpdatedAt` and `UpdatedBy` are also set when an entity is soft-deleted.
 

docs/bulk-operations.md

@@ -1 +1,143 @@
+# Bulk Operations
+
+EfCoreKit provides high-performance batch operations that execute in a single database round trip instead of one command per row.
+
+## Supported Operations
+
+| Method | Description |
+|--------|-------------|
+| `BulkInsertAsync<T>` | Insert thousands of rows in one call |
+| `BulkUpdateAsync<T>` | Update many rows by primary key |
+| `BulkDeleteAsync<T>` | Delete many rows by primary key |
+| `BulkUpsertAsync<T>` | Insert or update (merge) based on key match |
+
+## Supported Databases
+
+Each database has its own provider package with an optimized implementation:
+
+| Package | Database | Registration |
+|---------|----------|-------------|
+| `EfCoreKit.SqlServer` | SQL Server 2016+ | `services.AddEfCoreKitSqlServer()` |
+| `EfCoreKit.PostgreSql` | PostgreSQL 12+ | `services.AddEfCoreKitPostgreSql()` |
+| `EfCoreKit.MySql` | MySQL 8.0+ | `services.AddEfCoreKitMySql()` |
+| `EfCoreKit.Sqlite` | SQLite 3.x | `services.AddEfCoreKitSqlite()` |
+
+Or install `EfCoreKit` (umbrella package) to get all providers at once.
+
+## Setup
+
+```csharp
+builder.Services.AddEfCoreKit<AppDbContext>(
+    options => options.UseSqlServer(connectionString));
+
+// Register the bulk operations provider
+builder.Services.AddEfCoreKitSqlServer();
+```
+
+## Usage
+
+Inject `IBulkExecutor` and use it with your `DbContext`:
+
+```csharp
+public class OrderService
+{
+    private readonly AppDbContext _context;
+    private readonly IBulkExecutor _bulk;
+
+    public OrderService(AppDbContext context, IBulkExecutor bulk)
+    {
+        _context = context;
+        _bulk = bulk;
+    }
+
+    public async Task ImportOrders(List<Order> orders)
+    {
+        await _bulk.BulkInsertAsync(_context, orders);
+    }
+}
+```
+
+### Insert
+
+```csharp
+var customers = Enumerable.Range(1, 10_000)
+    .Select(i => new Customer { Name = $"Customer {i}" })
+    .ToList();
+
+await bulk.BulkInsertAsync(context, customers);
+```
+
+### Update
+
+```csharp
+// Load entities, modify them, then bulk update
+var products = await context.Products.Where(p => p.Category == "Sale").ToListAsync();
+foreach (var p in products) p.Price *= 0.9m; // 10% off
+
+await bulk.BulkUpdateAsync(context, products);
+```
+
+### Delete
+
+```csharp
+var expired = await context.Orders.Where(o => o.ExpiresAt < DateTime.UtcNow).ToListAsync();
+await bulk.BulkDeleteAsync(context, expired);
+```
+
+### Upsert (Insert or Update)
+
+```csharp
+// Inserts new rows, updates existing ones (matched by primary key)
+await bulk.BulkUpsertAsync(context, incomingProducts);
+```
+
+## BulkConfig Options
+
+All operations accept an optional `BulkConfig` for fine-tuning:
+
+```csharp
+await bulk.BulkInsertAsync(context, customers, new BulkConfig
+{
+    BatchSize = 5000,              // Rows per batch (default: 1000)
+    Timeout = 60,                  // Seconds (default: 30)
+    PreserveInsertOrder = true,    // Maintain list order (default: true)
+    SetOutputIdentity = true,      // Populate generated IDs after insert
+    UseTransaction = true,         // Wrap in transaction (default: true)
+    TrackEntities = false,         // Add to EF change tracker after operation
+
+    // Column control
+    PropertiesToInclude = ["Name", "Email"],     // Only update these columns
+    PropertiesToExclude = ["CreatedAt"],          // Skip these columns
+
+    // Upsert key
+    UpdateByProperties = ["ExternalId"],          // Match on this instead of PK
+
+    // Progress reporting
+    OnProgress = (processed, total) =>
+        Console.WriteLine($"{processed}/{total}")
+});
+```
+
+### BulkConfig Properties
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `BatchSize` | 1000 | Number of rows per batch |
+| `Timeout` | 30 | Command timeout in seconds |
+| `PreserveInsertOrder` | `true` | Maintain the order of the input list |
+| `SetOutputIdentity` | `false` | Populate auto-generated keys after insert |
+| `UpdateByProperties` | `null` | Columns to match on for upsert (defaults to PK) |
+| `PropertiesToInclude` | `null` | Only include these columns |
+| `PropertiesToExclude` | `null` | Exclude these columns |
+| `UseTransaction` | `true` | Wrap operation in a transaction |
+| `TrackEntities` | `false` | Add entities to the change tracker after the operation |
+| `OnProgress` | `null` | Callback for progress reporting `(processed, total)` |
+
+## Performance Notes
+
+- Bulk operations bypass the EF Core change tracker — they go directly to the database
+- `BulkInsertAsync` with 10,000 rows is typically **10-50x faster** than `AddRange` + `SaveChanges`
+- Set `BatchSize` based on your row size — larger rows benefit from smaller batches
+- `SetOutputIdentity = true` adds overhead (an extra round trip) but populates generated keys
+- Interceptors (audit, soft delete) do **not** apply to bulk operations since they bypass `SaveChanges`