Merge branch 'feature/docs-overhaul' into develop

Professional documentation overhaul (Diátaxis on DocFX):
- rewrite landing + getting-started
- add reference articles + normalise all 41 package READMEs to a uniform template
- add 5 Concept pages with Mermaid diagrams, 4 how-to + 4 provider decision guides
- add 4 compiling sample projects (Crypto/Vfs/Secrets/Actors) and 6 tutorials
- full link/diagram audit; every package has README + article + TOC entry

# Conflicts:
#	src/SquidStd.Actors/README.md
#	src/SquidStd.Generators/README.md
#	src/SquidStd.Messaging.Sqs/README.md

Author: tgiachi

SquidStd.slnx

@@ -59,6 +59,10 @@
         <Project Path="samples/SquidStd.Samples.Caching/SquidStd.Samples.Caching.csproj" />
         <Project Path="samples/SquidStd.Samples.EventsJobsScheduling/SquidStd.Samples.EventsJobsScheduling.csproj" />
         <Project Path="samples/SquidStd.Samples.GettingStarted/SquidStd.Samples.GettingStarted.csproj" />
+        <Project Path="samples/SquidStd.Samples.Crypto/SquidStd.Samples.Crypto.csproj" />
+        <Project Path="samples/SquidStd.Samples.Vfs/SquidStd.Samples.Vfs.csproj" />
+        <Project Path="samples/SquidStd.Samples.Secrets/SquidStd.Samples.Secrets.csproj" />
+        <Project Path="samples/SquidStd.Samples.Actors/SquidStd.Samples.Actors.csproj" />
     </Folder>
     <Folder Name="/tests/">
         <Project Path="tests/SquidStd.Tests/SquidStd.Tests.csproj" />

docs/articles/actors.md

@@ -0,0 +1 @@
+[!include[](../../src/SquidStd.Actors/README.md)]

docs/articles/concepts/abstractions-first.md

@@ -0,0 +1,21 @@
+# Abstractions first
+
+SquidStd is built abstractions-first: code depends on contracts, and concrete backends are chosen at composition time. This is what makes a SquidStd application easy to test and easy to retarget.
+
+## Contract package plus provider packages
+
+Each capability is a contract package paired with one or more provider packages. The contract package — `*.Abstractions` — defines the interfaces and DTOs. Provider packages implement them. Your application references the abstraction and depends on the provider only in the host project. See the [architecture](architecture.md) overview for how this shapes the package graph.
+
+## In-memory for tests, external for prod
+
+Most capabilities ship an in-memory provider for tests and an external-backend provider for production:
+
+- **Messaging** — in-memory, or `SquidStd.Messaging.RabbitMq` / `SquidStd.Messaging.Sqs`.
+- **Caching** — in-memory, or `SquidStd.Caching.Redis`.
+- **Storage** — file-backed, or `SquidStd.Storage.S3` (S3 and MinIO).
+
+Tests run fast and deterministically against the in-memory provider; production swaps in the external backend.
+
+## Swapping providers without touching call sites
+
+Because call sites depend only on the contract, switching backends is a registration change in the host — `container.AddInMemoryMessaging()` versus `container.AddRabbitMqMessaging(...)` — with no edits to the code that publishes or consumes messages. See [dependency injection](dependency-injection.md) for the registration pattern that makes the swap a one-line change.

docs/articles/concepts/architecture.md

@@ -0,0 +1,34 @@
+# Architecture
+
+SquidStd is a modular .NET toolkit. Rather than a single monolithic library, it ships one package per capability, so an application depends only on the pieces it actually uses.
+
+## Modular by design
+
+Every capability is split in two: an `*.Abstractions` package that holds the contracts (interfaces and DTOs) and one or more provider packages that implement them. For example `SquidStd.Messaging.Abstractions` defines the messaging contracts, while `SquidStd.Messaging`, `SquidStd.Messaging.RabbitMq`, and `SquidStd.Messaging.Sqs` provide implementations. This keeps call sites coupled to contracts, not to a concrete backend. See [abstractions first](abstractions-first.md) for why this matters.
+
+## Layers
+
+The dependency flow runs in one direction:
+
+- **Core** (`SquidStd.Core`) — primitives, options, and the building blocks everything else sits on.
+- **Abstractions** — per-capability contract packages.
+- **Providers** — concrete implementations of those contracts.
+- **Host** — `SquidStdBootstrap` composes services and runs them.
+
+Higher layers depend on lower ones, never the reverse.
+
+## Package graph
+
+```mermaid
+graph TD
+  Core[SquidStd.Core] --> Services[SquidStd.Services.Core]
+  Abstr[*.Abstractions contracts] --> Providers[Provider packages]
+  Services --> Host[SquidStdBootstrap host]
+  Providers --> Host
+  Host --> App[Your application]
+```
+
+## Next
+
+- [Bootstrap lifecycle](bootstrap-lifecycle.md) — how the host starts and stops services.
+- [Abstractions first](abstractions-first.md) — the contract-plus-provider pattern in depth.

docs/articles/concepts/bootstrap-lifecycle.md

@@ -0,0 +1,51 @@
+# Bootstrap lifecycle
+
+`SquidStdBootstrap` is the entry point that wires up dependency injection and drives the lifecycle of every registered service. The flow is always the same: create, configure, start, stop.
+
+## Create
+
+Begin by creating the bootstrap from `SquidStdOptions`:
+
+```csharp
+var bootstrap = SquidStdBootstrap.Create(new SquidStdOptions
+{
+    ConfigName = "squidstd",
+    RootDirectory = AppContext.BaseDirectory
+});
+```
+
+`ConfigName` selects the configuration file and `RootDirectory` anchors relative paths.
+
+## ConfigureServices
+
+Register your services into the DryIoc container:
+
+```csharp
+bootstrap.ConfigureServices(container =>
+{
+    container.AddSomething();
+});
+```
+
+See [dependency injection](dependency-injection.md) for the container and the `AddXxx` / `RegisterXxx` pattern.
+
+## Start and stop over ISquidStdService
+
+Services implementing `ISquidStdService` participate in the lifecycle. On `StartAsync` they are started in registration order; on `StopAsync` they are stopped in reverse order, so dependencies remain available while their dependents shut down.
+
+```mermaid
+sequenceDiagram
+  participant App
+  participant Bootstrap as SquidStdBootstrap
+  participant Svc as ISquidStdService(s)
+  App->>Bootstrap: Create(options)
+  App->>Bootstrap: ConfigureServices(container)
+  App->>Bootstrap: StartAsync()
+  Bootstrap->>Svc: StartAsync() (in order)
+  App->>Bootstrap: StopAsync()
+  Bootstrap->>Svc: StopAsync() (reverse order)
+```
+
+## RunAsync for long-running hosts
+
+For long-running hosts, call `RunAsync`. It starts every service and then blocks until cancellation, stopping services cleanly on shutdown. Resolve dependencies anywhere with `bootstrap.Resolve<T>()`. See the [architecture](architecture.md) overview for how the host fits the layers.

docs/articles/concepts/dependency-injection.md

@@ -0,0 +1,32 @@
+# Dependency injection
+
+SquidStd resolves every service through dependency injection. Understanding the container and its registration pattern is the key to wiring an application together.
+
+## DryIoc container
+
+The DI container is [DryIoc](https://github.com/dadhi/DryIoc), exposed as `IContainer`. It is fast, supports rich lifetimes, and validates required services at resolution time. Because the container owns validation, constructor dependencies that arrive from DI do not need manual null guards.
+
+## The AddXxx / RegisterXxx extension pattern
+
+Modules register themselves through C# 14 `extension(IContainer)` members named `AddXxx(...)` or `RegisterXxx(...)`. Each capability ships its own registration entry point, so wiring a module is a single call:
+
+```csharp
+container.AddInMemoryMessaging();
+container.RegisterCoreServices();
+```
+
+This keeps registration discoverable and colocated with the package that owns it.
+
+## Resolving through the bootstrap
+
+Once configured, resolve services through the bootstrap:
+
+```csharp
+var bus = bootstrap.Resolve<IEventBus>();
+```
+
+In most code you let constructor injection do the work and never call `Resolve` directly. See [bootstrap lifecycle](bootstrap-lifecycle.md) for where `ConfigureServices` runs.
+
+## Singletons and lifecycle
+
+Most infrastructure services are registered as singletons and live for the life of the host. Services implementing `ISquidStdService` are additionally started and stopped by the bootstrap, so a singleton can hold long-lived resources that are released on shutdown.

docs/articles/concepts/messaging-models.md

@@ -0,0 +1,27 @@
+# Messaging models
+
+SquidStd offers three in-process messaging models. Each fits a different shape of communication, and they can be mixed freely within one application.
+
+## Event Bus
+
+The Event Bus (`IEventBus`) is a stateless broadcast. Publishers call `PublishAsync` and any number of subscribers registered with `Subscribe` receive the event. Senders do not know who listens, and there is no return value. Use it for fan-out notifications where many parts of the system react to something that happened.
+
+## Command Dispatcher
+
+The Command Dispatcher is a stateless request routed to a single handler that returns a result. Unlike the Event Bus there is exactly one handler per command, and the caller awaits its result. Use it for request/response work — validating input, performing an operation, returning an outcome — where ownership of the action is unambiguous.
+
+## Actors
+
+Actors (`Actor<TMessage>`) provide an ordered, stateful, per-entity mailbox. Each actor processes its messages one at a time in order, so state inside an actor needs no locks. Send fire-and-forget messages with `TellAsync` or request a reply with `AskAsync`. Use actors when you need serialized access to per-entity state, such as a single account, device, or session.
+
+## Choosing
+
+```mermaid
+flowchart TD
+  Q{Need ordered, per-entity state?} -->|yes| A[Actors]
+  Q -->|no| R{Request → single handler with a result?}
+  R -->|yes| C[Command Dispatcher]
+  R -->|no| E[Event Bus broadcast]
+```
+
+All three are contract-first; see [abstractions first](abstractions-first.md) for swapping in external transports.

docs/articles/crypto.md

@@ -0,0 +1 @@
+[!include[](../../src/SquidStd.Crypto/README.md)]

docs/articles/getting-started.md

@@ -7,14 +7,19 @@ dotnet add package SquidStd.Services.Core
 ```
 
 ```csharp
-using DryIoc;
-using SquidStd.Services.Core.Extensions;
+using SquidStd.Core.Data.Bootstrap;
+using SquidStd.Services.Core.Services.Bootstrap;
 
-var container = new Container();
+// Core services wired automatically: config manager, event bus, command dispatcher,
+// job system, timer/cron scheduler, metrics, health checks, storage and secrets.
+var bootstrap = SquidStdBootstrap.Create(
+    new SquidStdOptions { ConfigName = "squidstd", RootDirectory = AppContext.BaseDirectory });
 
-// config manager + event bus + jobs + timer wheel + dispatcher + metrics + storage + secrets
-container.RegisterCoreServices("squidstd", Directory.GetCurrentDirectory());
+await bootstrap.StartAsync();
+// … resolve services, opt into modules with bootstrap.ConfigureServices(…) …
+await bootstrap.StopAsync();
 ```
 
-From here, add focused packages as needed — see the per-package guides in the sidebar and the
-[API reference](../api/index.md).
+Opt into modules with `ConfigureServices`, e.g. `container.AddInMemoryCache()`. See the
+[Concepts](concepts/bootstrap-lifecycle.md) for the full lifecycle and
+[Packages](getting-started.md) for per-module reference.

docs/articles/guides/choosing-caching.md

@@ -0,0 +1,19 @@
+# Choosing a cache
+
+The caching abstraction (`ICacheService`) has two backends. Both expose the same
+API, so you can develop against in-memory and promote to Redis without code changes.
+
+| Backend | Package · entrypoint | Use case | Scope | Survives restart | Ops cost |
+|---|---|---|---|---|---|
+| In-memory | `SquidStd.Caching` · `AddInMemoryCache` | Tests, single instance | Per-process | No | None |
+| Redis | `SquidStd.Caching.Redis` · `AddRedisCache` | Multiple instances, shared cache | Distributed | Yes (with persistence) | Run/host Redis |
+
+```csharp
+bootstrap.ConfigureServices(container => container.AddRedisCache("localhost:6379"));
+```
+
+## Recommendation
+
+Use `AddInMemoryCache` for tests and single-instance deployments; switch to
+`AddRedisCache` as soon as you run more than one instance or need the cache to
+outlive the process.