Add icons and screenshot

Author: xoofx

site/config.scriban

@@ -8,7 +8,7 @@ extend "XenoAtom/lunet_template@1.0.0"
 site_project_name = "XenoAtom.Logging"
 site_project_description = "A high-performance structured logging runtime for .NET, designed for zero allocations on the hot path."
 site_project_logo_path = "/img/XenoAtom.Logging.svg"
-site_project_social_banner_path = "/img/screenshot.png"
+site_project_social_banner_path = "/img/xenoatom-logging-banner.png"
 site_project_banner_background_path = "/img/screenshot.png"
 site_project_package_id = "XenoAtom.Logging"
 site_project_github_repo = "XenoAtom.Logging"

site/docs/readme.md

@@ -4,165 +4,45 @@ title: "User Guide"
 
 # User Guide
 
-This guide helps you adopt `XenoAtom.Logging` in production without getting overwhelmed:
+![XenoAtom.Logging demo screenshot](../img/screenshot.png){.terminal}
 
-- Start with a minimal setup.
-- Choose sync or async behavior intentionally.
-- Add structure, sinks, and formatting incrementally.
+Welcome to the XenoAtom.Logging documentation.
 
-If you are new to the library, begin with [Getting Started](getting-started.md).
+This section is organized as a practical map: start quickly, then go deeper by topic based on your use case.
 
-## Installation
+## Start here
 
-Core package:
+- [Getting Started](getting-started.md): install packages, configure logging, and run your first sync/async setup.
+- [Migration from Microsoft.Extensions.Logging](microsoft-extensions-logging.md): API mapping and rollout guidance.
+- [Package Consumption Guide](packages.md): package layout and when to use each package.
 
-```sh
-dotnet add package XenoAtom.Logging
-```
+## Core runtime topics
 
-Optional terminal package:
+- [Filtering and Routing](filtering.md): logger hierarchy, writer fan-out, and filters.
+- [File and JSON Writers](file-writer.md): rolling files, retention, JSONL output, and failure handling.
+- [Shutdown Semantics](shutdown.md): flushing and lifecycle behavior at app exit.
+- [Thread Safety](thread-safety.md): what is safe concurrently and what must be configured carefully.
 
-```sh
-dotnet add package XenoAtom.Logging.Terminal
-```
+## Formatting and generated APIs
 
-## A minimal working setup
+- [Log Formatters](log-formatter.md): built-in formatters, template syntax, and custom formatter generation.
+- [Source-generated Logging](source-generator.md): `[LogMethod]` and diagnostics.
 
-```csharp
-using XenoAtom.Logging;
-using XenoAtom.Logging.Writers;
+## Terminal and UI output
 
-var config = new LogManagerConfig
-{
-    RootLogger =
-    {
-        MinimumLevel = LogLevel.Info,
-        Writers =
-        {
-            new FileLogWriter("logs/app.log")
-        }
-    }
-};
+- [Terminal Integration](terminal.md): `TerminalLogWriter`, `TerminalLogControlWriter`, markup, and styling.
+- [Terminal Visual Examples](terminal-visuals.md): rendered examples and styling walkthrough.
 
-LogManager.Initialize(config);
+## Performance and deployment
 
-var logger = LogManager.GetLogger("App.Main");
-logger.Info("Application started");
+- [Benchmarks](benchmarks.md): benchmark setup, scenarios, and interpretation guidance.
+- [Native AOT and Trimming](aot.md): AOT/trimming-oriented behavior and constraints.
 
-LogManager.Shutdown();
-```
+## Recommended reading order
 
-## Core concepts
-
-### 1) Lifecycle
-
-- `LogManager.Initialize(...)` for synchronous processing.
-- `LogManager.InitializeForAsync(...)` for queued asynchronous processing.
-- `LogManager.Shutdown()` to flush and dispose writers.
-
-### 2) Logger hierarchy
-
-- `RootLogger` defines defaults (level, writers, overflow mode).
-- `Loggers.Add("App.Http", ...)` overrides by name prefix.
-- `includeParents` controls whether parent/root writers are inherited.
-
-See [Filtering and Routing](filtering.md).
-
-### 3) Structured data
-
-- Per-message properties with `LogProperties`.
-- Scoped properties with `BeginScope`.
-
-```csharp
-logger.Info(
-    properties: new LogProperties { ("requestId", 1423), ("tenant", "alpha") },
-    msg: "Processing request");
-```
-
-## Choosing sync vs async
-
-Use sync mode when sink I/O is low latency and predictable.
-
-Use async mode when throughput is high or when sink I/O can block:
-
-```csharp
-config.AsyncLogMessageQueueCapacity = 4096;
-config.AsyncErrorHandler = ex => Console.Error.WriteLine(ex.Message);
-config.RootLogger.OverflowMode = LoggerOverflowMode.Block;
-
-LogManager.InitializeForAsync(config);
-```
-
-Overflow guidance:
-
-- `Block`: safest for correctness (recommended default for critical logs).
-- `Drop` / `DropAndNotify`: lower producer latency, but allow loss.
-- `Allocate`: temporary queue growth under pressure.
-
-See [Shutdown Semantics](shutdown.md) and [Thread Safety](thread-safety.md) for operational behavior.
-
-## Writer choices
-
-### File and JSON pipelines
-
-- `FileLogWriter` for rolling text logs.
-- `JsonFileLogWriter` for JSONL ingestion pipelines.
-
-See [File and JSON Writers](file-writer.md).
-
-### Terminal and UI rendering
-
-- `TerminalLogWriter` for terminal output.
-- `TerminalLogControlWriter` for `XenoAtom.Terminal.UI` `LogControl`.
-- `InfoMarkup`/`ErrorMarkup` for markup-aware payloads.
-
-See [Terminal Integration](terminal.md) and [Terminal Visual Examples](terminal-visuals.md).
-
-## Formatter choices
-
-Text formatters:
-
-- `StandardLogFormatter`
-- `CompactLogFormatter`
-- `DetailedLogFormatter`
-
-Custom text formatters:
-
-- `[LogFormatter("...")]` on partial records
-- shared runtime formatter settings (`LevelFormat`, `TimestampFormat`)
-
-See [Log Formatters](log-formatter.md).
-
-## Source-generated logging methods
-
-Use `[LogMethod]` to define strongly-typed logging APIs:
-
-```csharp
-public static partial class AppLogs
-{
-    [LogMethod(LogLevel.Info, "User {userId} connected")]
-    public static partial void UserConnected(Logger logger, int userId);
-}
-```
-
-See [Source-generated Logging](source-generator.md).
-
-## Coming from Microsoft.Extensions.Logging
-
-Use [Migration from Microsoft.Extensions.Logging](microsoft-extensions-logging.md) for API mapping and rollout guidance.
-
-## Documentation map
-
-- [Getting Started](getting-started.md)
-- [Migration from Microsoft.Extensions.Logging](microsoft-extensions-logging.md)
-- [Package Consumption Guide](packages.md)
-- [Log Formatters](log-formatter.md)
-- [Source-generated Logging](source-generator.md)
-- [Filtering and Routing](filtering.md)
-- [File and JSON Writers](file-writer.md)
-- [Terminal Integration](terminal.md)
-- [Terminal Visual Examples](terminal-visuals.md)
-- [Thread Safety](thread-safety.md)
-- [Shutdown Semantics](shutdown.md)
-- [Native AOT and Trimming](aot.md)
-- [Benchmarks](benchmarks.md)
+1. [Getting Started](getting-started.md)
+2. [Filtering and Routing](filtering.md)
+3. [File and JSON Writers](file-writer.md)
+4. [Log Formatters](log-formatter.md)
+5. [Thread Safety](thread-safety.md)
+6. [Shutdown Semantics](shutdown.md)